pi-cache-optimizer 2.8.9 → 2.8.11

package/README.md

@@ -61,7 +61,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 0.85.1. 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.
+This extension requires Pi 0.82+ and is validated against Pi 0.87.1. 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.
 
 ## Commands
 
@@ -134,21 +134,21 @@ 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 endpoints reject `prompt_cache_key` with HTTP 400 even though the same field is valid for other providers. Pi 0.85.1 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 endpoints reject `prompt_cache_key` with HTTP 400 even though the same field is valid for other providers. Pi 0.87.1 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 `prompt_cache_key` unsupported error for the exact provider/model, ordinary `/cache-optimizer fix` offers a confirmed model-scoped repair. 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, 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
 ```
 
-The preview explains that the setting is stored in the extension-owned `pi-cache-optimizer-config.json`. After confirmation, the final `before_provider_request` stage removes both `prompt_cache_key` and `promptCacheKey`, including a key that Pi core supplied earlier. This can reduce provider prompt-cache hits for that exact model, while other models retain the existing fallback behavior. The file is updated atomically, a privacy-safe backup/receipt is created, and `/reload` or a Pi restart is required. `/cache-optimizer rollback` restores the previous extension configuration without resetting `footerMode`.
+The preview explains that the setting is stored in the extension-owned `pi-cache-optimizer-config.json`. After confirmation, the final `before_provider_request` stage removes both `prompt_cache_key` and `promptCacheKey`, including a key that Pi core supplied earlier. This can reduce provider prompt-cache hits for that exact model, while other models retain the existing fallback behavior. The file is updated atomically without overwriting a concurrently created config, a privacy-safe backup/receipt is created, and `/reload` or a Pi restart is required. `/cache-optimizer rollback` restores the previous extension configuration without resetting `footerMode`; it binds the previewed receipt by file identity and hash, refuses a replaced receipt, and compensates the config if receipt marking fails.
 
 ## OpenAI-compatible proxy setup
 
 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. Pi 0.82+ core generates a session `prompt_cache_key` for it when cache retention is enabled, so this extension preserves that key and may add the same conservative fallback when missing. 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. Pi 0.85.1 has no native `supportsPromptCacheKey` compat field, so the per-model key opt-out is stored in this extension's `pi-cache-optimizer-config.json` instead of `models.json`. The extension config is independent of Pi's compat precedence and only affects the exact provider/model listed there.
+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. Pi 0.82+ core generates a session `prompt_cache_key` for it when cache retention is enabled, so this extension preserves that key and may add the same conservative fallback when missing. 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. Pi 0.87.1 has no native `supportsPromptCacheKey` compat field, so the per-model key opt-out is stored in this extension's `pi-cache-optimizer-config.json` instead of `models.json`. The extension config is independent of Pi's compat precedence and only affects the exact provider/model listed there.
 
 For real proxies, start with session affinity:
 
@@ -174,7 +174,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 0.85.1 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 0.87.1 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.
@@ -262,7 +262,7 @@ Pi 0.80.9+ already includes Kimi K3 in built-in Kimi Coding, Moonshot AI / China
 - DeepSeek Pi Mono replay compat (`requiresReasoningContentOnAssistantMessages: true` only when `thinkingFormat: "deepseek"` is already explicit; `/fix` never invents that format)
 - OpenAI-compatible proxy session affinity (`sendSessionAffinityHeaders: true` for `openai-completions`). Pi 0.80.7+ controls `openai-responses` header shape with `sessionAffinityFormat` and auto-detects its default; this extension no longer writes the removed `sendSessionIdHeader` field.
 
-**Scope:** only the currently active model. Other channels require switching models and running `fix` again.
+**Scope:** the fix starts from the currently active model. An affinity-only repair can write provider-level compat once for all applicable models on that provider, including models absent from `models[]` when the provider entry already exists and no higher-priority setting shadows it. Explicit per-model `false` remains an opt-out. Other or ambiguous repairs stay model-scoped.
 
 **Safety:**
 
@@ -275,15 +275,15 @@ Pi 0.80.9+ already includes Kimi K3 in built-in Kimi Coding, Moonshot AI / China
 7. Writes a privacy-safe, versioned receipt atomically only after a successful write; the receipt contains transaction/model identity, placement, scalar compat before/after values, file hashes, backup filename, timestamps/status, and no credentials or request data
 8. Uses unique, non-overwriting backup names and falls back to manual guidance if the JSONC scanner cannot confidently locate the target
 
-Existing `modelOverrides[modelId]` entries have Pi's highest precedence, so `fix` repairs them directly. For built-in or API-login models without a custom `models[]` entry, `fix` creates a compat-only `modelOverrides` entry instead of inventing a custom model definition. Runtime-observed provider failures are always written to that highest-precedence model override so extension-provided runtime compat cannot shadow the repair. Self-validation checks the full provider → custom model → runtime model → modelOverride result and rejects an ineffective lower-layer edit.
+Existing `modelOverrides[modelId]` entries have Pi's highest precedence, so `fix` repairs them directly. For built-in or API-login models without a custom `models[]` entry, an affinity-only fix prefers provider-level compat when the existing provider is safely locatable and no higher-priority explicit/runtime value shadows it; otherwise `fix` creates a compat-only `modelOverrides` entry instead of inventing a custom model definition. Runtime-observed provider failures are always written to that highest-precedence model override so extension-provided runtime compat cannot shadow the repair. Self-validation checks the full provider → custom model → runtime model → modelOverride result and rejects an ineffective lower-layer edit.
 
 **Non-interactive mode:** refuses to write; shows manual edit guidance instead.
 
-**Run:** `/cache-optimizer fix` when the active model has detected compat issues. The command shows "nothing to fix" when compat is already complete.
+**Run:** `/cache-optimizer fix` when the active model has detected compat issues. Affinity-only missing-compat notifications are shown once per provider per extension instance and point to this confirmed command; model-specific warnings remain separate. The command shows "nothing to fix" when compat is already complete.
 
 ## `/cache-optimizer rollback`
 
-Rollback is available through completion, direct execution, and the interactive menu. It always requires UI confirmation; without an interactive UI it gives manual-review guidance and does not write. The command selects the latest unapplied receipt for the active provider/model, validates the recorded backup and current file hashes, creates a new access-mode-preserving rollback backup, and uses temp-file + atomic rename. Fix and rollback transactions are serialized across extension instances; rollback also binds the receipt transaction id/hash from preview through commit and refuses if another transaction replaces it.
+Rollback is available through completion, direct execution, and the interactive menu. It always requires UI confirmation; without an interactive UI it gives manual-review guidance and does not write. The command selects the latest unapplied receipt for the active provider/model (or any active model on that provider for a provider-level receipt), validates the recorded backup and current file hashes, creates a new access-mode-preserving rollback backup, and uses temp-file + atomic rename. Fix and rollback transactions are serialized across extension instances; rollback also binds the receipt transaction id/hash from preview through commit and refuses if another transaction replaces it.
 
 If `models.json` is unchanged since the fix, rollback can restore the exact pre-fix JSONC. If the file changed, it never blindly replaces it: it may restore only receipt-owned scalar compat keys whose recorded post-fix values are still present, preserving later user changes. If a receipt-owned key changed, the target was removed/moved, or the fix created a new target entry, it refuses and points to the recorded backup for manual review. Successful rollback marks the receipt and requires `/reload` or a restart.
 

package/README.zh-CN.md

@@ -61,7 +61,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 0.85.1 验证。TypeScript 校验直接使用官方 Pi package 类型，同时只使用这些版本共有的 extension hooks、`getAgentDir()` 和 prompt options；不依赖 Pi 0.83+ 专有 API（例如 `ctx.scopedModels` 或 bundled TypeBox 1.3 aliases）。
+本扩展要求 Pi 0.82+，并已使用 Pi 0.87.1 验证。TypeScript 校验直接使用官方 Pi package 类型，同时只使用这些版本共有的 extension hooks、`getAgentDir()` 和 prompt options；不依赖 Pi 0.83+ 专有 API（例如 `ctx.scopedModels` 或 bundled TypeBox 1.3 aliases）。
 
 ## 命令
 
@@ -134,21 +134,21 @@ Footer 默认使用 `session`，避免另一个并行 Pi 终端使用相同 prov
 
 ## 按模型关闭 `prompt_cache_key`
 
-某些 OpenAI-compatible endpoint 会因 `prompt_cache_key` 返回 HTTP 400，但同一个字段对其他 provider 可能有效。Pi 0.85.1 没有原生的 `supportsPromptCacheKey` compat 字段，**不要**把这个未知字段加入 `models.json`。`supportsLongCacheRetention` 也不是等价开关，不应借用来实现此目的。
+某些 OpenAI-compatible endpoint 会因 `prompt_cache_key` 返回 HTTP 400，但同一个字段对其他 provider 可能有效。Pi 0.87.1 没有原生的 `supportsPromptCacheKey` compat 字段，**不要**把这个未知字段加入 `models.json`。`supportsLongCacheRetention` 也不是等价开关，不应借用来实现此目的。
 
-当扩展观察到精确 provider/model 明确拒绝 `prompt_cache_key` 后，普通 `/cache-optimizer fix` 会提供经过确认的模型级修复。如果你已经确定 endpoint 不支持该字段，可以主动执行：
+当扩展观察到精确 provider/model 对 `prompt_cache_key` 的明确字段级拒绝后，普通 `/cache-optimizer fix` 会提供经过确认的模型级修复。参数值校验失败，以及“设置 temperature 时不允许”这类条件限制都不构成证据。若不同模型的响应并发交错，而 Pi 又没有提供 request ID，扩展会忽略无法安全关联的 response-header 证据；只有最终 assistant message 提供精确 provider/model 身份时才恢复归因。如果你已经确定 endpoint 不支持该字段，可以主动执行：
 
 ```text
 /cache-optimizer fix prompt-cache-key
 ```
 
-预览会说明设置保存在扩展自有的 `pi-cache-optimizer-config.json` 中。确认后，`before_provider_request` 的最终阶段会移除 `prompt_cache_key` 和 `promptCacheKey`，包括 Pi core 之前已经放入的 key。这个精确模型可能因此失去 provider prompt-cache 命中，其他模型仍保持原有 fallback 行为。配置会使用原子替换写入，并生成不含敏感内容的备份/receipt；需要 `/reload` 或重启 Pi。`/cache-optimizer rollback` 可恢复之前的扩展配置，且不会重置 `footerMode`。
+预览会说明设置保存在扩展自有的 `pi-cache-optimizer-config.json` 中。确认后，`before_provider_request` 的最终阶段会移除 `prompt_cache_key` 和 `promptCacheKey`，包括 Pi core 之前已经放入的 key。这个精确模型可能因此失去 provider prompt-cache 命中，其他模型仍保持原有 fallback 行为。配置通过原子、不可覆盖并发新建文件的方式写入，并生成不含敏感内容的备份/receipt；需要 `/reload` 或重启 Pi。`/cache-optimizer rollback` 可恢复之前的扩展配置且不会重置 `footerMode`；它会绑定预览时 receipt 的文件身份和 hash，在 receipt 被替换时拒绝操作，并在 receipt 状态写入失败时补偿恢复配置。
 
 ## OpenAI-compatible 代理配置
 
 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。Pi 0.82+ core 在启用 cache retention 时会为它生成 session `prompt_cache_key`，因此本扩展会保留该 key，并在缺失时使用同样的保守 fallback。只有符合 Pi 内置 provider 明确 compat 指纹的模型会跳过通用 proxy 路由 / session-affinity 建议；仅复用 `llama.cpp` id 的自定义或覆盖 provider 仍按普通 OpenAI-compatible 渠道处理。`prompt_cache_retention` 继续遵循统一安全规则：仅官方 OpenAI 或 `models.json` 中有效配置为 `supportsLongCacheRetention: true` 时保留，否则发送前移除。Pi 0.85.1 没有原生的 `supportsPromptCacheKey` compat 字段，因此按模型关闭 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。Pi 0.82+ core 在启用 cache retention 时会为它生成 session `prompt_cache_key`，因此本扩展会保留该 key，并在缺失时使用同样的保守 fallback。只有符合 Pi 内置 provider 明确 compat 指纹的模型会跳过通用 proxy 路由 / session-affinity 建议；仅复用 `llama.cpp` id 的自定义或覆盖 provider 仍按普通 OpenAI-compatible 渠道处理。`prompt_cache_retention` 继续遵循统一安全规则：仅官方 OpenAI 或 `models.json` 中有效配置为 `supportsLongCacheRetention: true` 时保留，否则发送前移除。Pi 0.87.1 没有原生的 `supportsPromptCacheKey` compat 字段，因此按模型关闭 key 的策略保存在本扩展的 `pi-cache-optimizer-config.json` 中，而不是 `models.json`。扩展配置独立于 Pi 的 compat 优先级，只影响其中列出的精确 provider/model。
 
 对真正的代理，建议先启用 session affinity：
 
@@ -174,7 +174,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 0.85.1 没有定义这个 compat 字段。请使用 `/cache-optimizer fix prompt-cache-key` 在扩展自有配置中保存精确 provider/model 的 omit 规则；它会移除两种 key 写法，包括 Pi 提供的 key。
+- 不要把 `supportsPromptCacheKey` 加入 `models.json`：Pi 0.87.1 没有定义这个 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` 列为缺失修复项。
@@ -262,7 +262,7 @@ Pi 0.80.9+ 已在内置 Kimi Coding、Moonshot AI / 中国区、OpenRouter 和 V
 - DeepSeek Pi Mono replay compat（仅当已明确配置 `thinkingFormat: "deepseek"` 时使用 `requiresReasoningContentOnAssistantMessages: true`；`/fix` 不会自行推断该 format）
 - OpenAI-compatible proxy session affinity（`openai-completions` 使用 `sendSessionAffinityHeaders: true`）。Pi 0.80.7+ 使用 `sessionAffinityFormat` 控制 `openai-responses` header 形式并自动检测默认值；本扩展不再写入已移除的 `sendSessionIdHeader`。
 
-**范围：** 仅当前 active model。其他渠道需切换模型后再次运行 `fix`。
+**范围：** 从当前 active model 发起修复。仅缺少 affinity 时，如 provider 已有配置项且无更高优先级配置遮挡，可一次写入 provider 级 compat，覆盖其适用模型（包括不在 `models[]` 中的模型）；模型级显式 `false` 仍为 opt-out。其他或有歧义的修复仍按模型处理。
 
 **安全机制：**
 
@@ -274,15 +274,15 @@ Pi 0.80.9+ 已在内置 Kimi Coding、Moonshot AI / 中国区、OpenRouter 和 V
 6. 完全保留 `models.json` 原有访问权限，不主动收紧或放宽（例如 `0600` 保持 `0600`，`0644` 保持 `0644`）
 7. 备份名唯一且不会覆盖已有备份；如果 JSONC 扫描器无法置信定位目标，则回退到手动修改指引
 
-已有的 `modelOverrides[modelId]` 具有 Pi 的最高优先级，因此 `fix` 会直接修复该 entry。对于没有自定义 `models[]` entry 的内置模型或 API-login 模型，`fix` 会创建仅含 compat 的 `modelOverrides` entry，而不会凭空添加自定义模型定义。运行时观察到的 provider 失败也始终写入这一最高优先级 model override，避免 extension-provided runtime compat 遮挡修复。自检会验证完整的 provider → custom model → runtime model → modelOverride 结果；无效的低层写入会被拒绝。
+已有的 `modelOverrides[modelId]` 具有 Pi 的最高优先级，因此 `fix` 会直接修复该 entry。对于没有自定义 `models[]` entry 的内置模型或 API-login 模型，若现有 provider 可安全使用 provider 级 affinity 修复，则优先写入 provider compat；否则 `fix` 会创建仅含 compat 的 `modelOverrides` entry，而不会凭空添加自定义模型定义。运行时观察到的 provider 失败也始终写入这一最高优先级 model override，避免 extension-provided runtime compat 遮挡修复。自检会验证完整的 provider → custom model → runtime model → modelOverride 结果；无效的低层写入会被拒绝。
 
 **非交互模式：** 拒绝写入，显示手动编辑指引。
 
-**运行：** 当 active model 检测到 compat 问题时执行 `/cache-optimizer fix`。compat 已完整时，命令显示"无需修复"。
+**运行：** 当 active model 检测到 compat 问题时执行 `/cache-optimizer fix`。仅缺少 affinity 的提醒按 provider 在当前扩展实例内去重，并指向这一确认式命令；模型专属提醒仍单独显示。compat 已完整时，命令显示"无需修复"。
 
 ## `/cache-optimizer rollback`
 
-Rollback 可通过补全、直接命令和交互菜单使用，并始终需要 UI 确认。命令会选择匹配当前 provider/model 的最新未回滚 receipt，验证备份与文件 hash，创建新的保留访问权限的 rollback backup，并使用临时文件 + 原子替换。Fix 与 rollback 在多个 extension instance 间串行执行；rollback 还会把预览时的 receipt transaction id/hash 绑定到提交阶段，若另一事务替换 receipt 就安全拒绝。没有交互式 UI 时只提供手动恢复指引，不会写入文件。
+Rollback 可通过补全、直接命令和交互菜单使用，并始终需要 UI 确认。命令会选择匹配当前 provider/model（provider 级 receipt 可从同 provider 任一模型操作）的最新未回滚 receipt，验证备份与文件 hash，创建新的保留访问权限的 rollback backup，并使用临时文件 + 原子替换。Fix 与 rollback 在多个 extension instance 间串行执行；rollback 还会把预览时的 receipt transaction id/hash 绑定到提交阶段，若另一事务替换 receipt 就安全拒绝。没有交互式 UI 时只提供手动恢复指引，不会写入文件。
 
 如果 `models.json` 自 fix 后没有变化，rollback 可以恢复完整的 pre-fix JSONC；如果文件发生变化，则绝不会盲目替换整个文件，只会在 receipt-owned scalar key 仍等于记录的 post-fix 值时撤销该 key，并保留之后的用户修改。如果 receipt-owned key 已变化、目标被删除/移动，或 fix 新建了目标项，命令会安全拒绝并指向记录的 backup 供手动检查。成功后 receipt 会标记为已回滚，并需要 `/reload` 或重启。
 

package/index.ts

@@ -1,5 +1,5 @@
 import { createHash, randomUUID } from "node:crypto";
-import { chmod, copyFile, lstat, mkdir, readFile, readdir, rename, rm, stat, unlink, writeFile } from "node:fs/promises";
+import { chmod, copyFile, link, lstat, mkdir, readFile, readdir, rename, rm, stat, unlink, writeFile } from "node:fs/promises";
 import { constants as fsConstants, readFileSync, statSync, watch } from "node:fs";
 import { homedir } from "node:os";
 import { basename, dirname, join } from "node:path";
@@ -204,6 +204,12 @@ type PromptCacheKeyConfigReceipt = {
   status?: "rolled_back";
   rolledBackAt?: number;
 };
+type PromptCacheKeyConfigReceiptSnapshot = {
+  receipt: PromptCacheKeyConfigReceipt;
+  receiptPath: string;
+  hash: string;
+  identity: FileIdentity;
+};
 const PI_ROUTING_REGISTRY_SYMBOL = Symbol.for("pi.routing.registry.v1");
 const PI_CACHE_HINTS_SYMBOL = Symbol.for("pi.cache.hints.v1");
 const PI_CACHE_HINTS_OWNER_SYMBOL = Symbol.for("pi.cache.optimizer.hints-owner.v1");
@@ -2041,21 +2047,7 @@ async function writePersistedCacheOptimizerConfigUnlocked(
     return;
   }
 
-  const tempPath = uniqueTempPath(configPath, "config");
-  try {
-    await writeFile(tempPath, payloadText, { encoding: "utf8", mode: targetMode, flag: "wx" });
-    await chmod(tempPath, targetMode);
-    try {
-      await lstat(configPath);
-      throw new Error("optimizer config appeared during write; no changes were made");
-    } catch (error) {
-      if (getErrorCode(error) !== "ENOENT") throw error;
-    }
-    await rename(tempPath, configPath);
-  } catch (error) {
-    await unlink(tempPath).catch((cleanupError) => { if (getErrorCode(cleanupError) !== "ENOENT") console.warn(`${LOG_PREFIX}: failed to remove temporary config`, cleanupError); });
-    throw error;
-  }
+  await atomicCreateTextFileNoReplace(configPath, payloadText, targetMode, "config");
 }
 
 async function writePersistedCacheOptimizerConfig(
@@ -2087,24 +2079,15 @@ async function writePersistedFooterModeUnlocked(
     if (targetInfo && (targetInfo.isSymbolicLink() || !targetInfo.isFile())) throw new Error("optimizer config is not a regular file; no changes were made");
     const targetText = targetInfo ? await readFile(configPath, "utf8") : undefined;
     const targetMode = targetInfo ? targetInfo.mode & 0o7777 : 0o600;
-    const tempPath = uniqueTempPath(configPath, "config-footer");
-    try {
-      await writeFile(tempPath, JSON.stringify({ version: 1, footerMode: mode }, null, 2) + "\n", { encoding: "utf8", mode: targetMode, flag: "wx" });
-      await chmod(tempPath, targetMode);
-      if (targetInfo && targetText !== undefined) {
-        await validateAtomicTarget(configPath, { identity: targetInfo, hash: hashText(targetText), mode: targetMode });
-      } else {
-        try {
-          await lstat(configPath);
-          throw new Error("optimizer config appeared during footer write; no changes were made");
-        } catch (error) {
-          if (getErrorCode(error) !== "ENOENT") throw error;
-        }
-      }
-      await rename(tempPath, configPath);
-    } catch (error) {
-      await unlink(tempPath).catch(() => {});
-      throw error;
+    const footerText = JSON.stringify({ version: 1, footerMode: mode }, null, 2) + "\n";
+    if (targetInfo && targetText !== undefined) {
+      await atomicReplaceTextFilePreservingMode(configPath, footerText, targetMode, "config-footer", {
+        identity: targetInfo,
+        hash: hashText(targetText),
+        mode: targetMode,
+      });
+    } else {
+      await atomicCreateTextFileNoReplace(configPath, footerText, targetMode, "config-footer");
     }
     return;
   }
@@ -2132,7 +2115,12 @@ function parsePromptCacheKeyConfigReceipt(value: unknown): PromptCacheKeyConfigR
   if (![record.transactionId, record.provider, record.modelId].every(isSafeReceiptText)) return undefined;
   if (!isSha256(record.beforeHash) || !isSha256(record.afterHash) || record.beforeHash === record.afterHash) return undefined;
   if (!isSafeReceiptText(record.backupFile) || basename(record.backupFile) !== record.backupFile || !record.backupFile.startsWith("pi-cache-optimizer-config.backup-")) return undefined;
-  if (typeof record.targetExistedBefore !== "boolean" || !isReceiptTimestamp(record.createdAt) || !isReceiptTimestamp(record.appliedAt)) return undefined;
+  if (
+    typeof record.targetExistedBefore !== "boolean" ||
+    !isReceiptTimestamp(record.createdAt) ||
+    !isReceiptTimestamp(record.appliedAt) ||
+    record.appliedAt < record.createdAt
+  ) return undefined;
   const addedModelKey = `${record.provider}/${record.modelId}`;
   const targetHadModelKey = record.version === 1 ? false : record.targetHadModelKey;
   if (typeof targetHadModelKey !== "boolean") return undefined;
@@ -2162,25 +2150,95 @@ function isActionablePromptCacheKeyConfigReceipt(receipt: PromptCacheKeyConfigRe
   return receipt !== undefined && receipt.status === undefined;
 }
 
-async function readPromptCacheKeyConfigReceipt(receiptPath: string = CONFIG_RECEIPT_PATH): Promise<PromptCacheKeyConfigReceipt | undefined> {
+async function assertPromptCacheKeyConfigReceiptSnapshotUnchanged(
+  snapshot: PromptCacheKeyConfigReceiptSnapshot,
+): Promise<void> {
+  const info = await lstat(snapshot.receiptPath);
+  if (info.isSymbolicLink() || !info.isFile() || !sameFileIdentity(snapshot.identity, info)) {
+    throw new Error("prompt-cache-key receipt changed since the rollback preview");
+  }
+  const text = await readFile(snapshot.receiptPath, "utf8");
+  const afterRead = await lstat(snapshot.receiptPath);
+  if (
+    afterRead.isSymbolicLink() ||
+    !afterRead.isFile() ||
+    !sameFileIdentity(info, afterRead) ||
+    hashText(text) !== snapshot.hash
+  ) {
+    throw new Error("prompt-cache-key receipt changed since the rollback preview");
+  }
+}
+
+async function readPromptCacheKeyConfigReceiptSnapshot(
+  receiptPath: string = CONFIG_RECEIPT_PATH,
+): Promise<PromptCacheKeyConfigReceiptSnapshot | undefined> {
   try {
     const info = await lstat(receiptPath);
     if (info.isSymbolicLink() || !info.isFile()) return undefined;
-    const receipt = parsePromptCacheKeyConfigReceipt(JSON.parse(await readFile(receiptPath, "utf8")));
-    return receipt;
+    const text = await readFile(receiptPath, "utf8");
+    const afterRead = await lstat(receiptPath);
+    if (afterRead.isSymbolicLink() || !afterRead.isFile() || !sameFileIdentity(info, afterRead)) return undefined;
+    const receipt = parsePromptCacheKeyConfigReceipt(JSON.parse(text));
+    if (!receipt) return undefined;
+    return { receipt, receiptPath, hash: hashText(text), identity: afterRead };
   } catch {
     return undefined;
   }
 }
 
-async function writePromptCacheKeyConfigReceipt(receipt: PromptCacheKeyConfigReceipt, receiptPath: string = CONFIG_RECEIPT_PATH): Promise<void> {
+async function readPromptCacheKeyConfigReceipt(receiptPath: string = CONFIG_RECEIPT_PATH): Promise<PromptCacheKeyConfigReceipt | undefined> {
+  return (await readPromptCacheKeyConfigReceiptSnapshot(receiptPath))?.receipt;
+}
+
+async function writePromptCacheKeyConfigReceipt(
+  receipt: PromptCacheKeyConfigReceipt,
+  receiptPath: string = CONFIG_RECEIPT_PATH,
+  expectedSnapshot?: PromptCacheKeyConfigReceiptSnapshot,
+  /** Test-only race injector; production callers leave this undefined. */
+  beforeRename?: () => Promise<void>,
+): Promise<void> {
   if (!parsePromptCacheKeyConfigReceipt(receipt)) throw new Error("invalid prompt cache key config receipt");
+  if (expectedSnapshot?.receiptPath !== undefined && expectedSnapshot.receiptPath !== receiptPath) {
+    throw new Error("prompt-cache-key receipt path changed since the rollback preview");
+  }
+  if (expectedSnapshot) await assertPromptCacheKeyConfigReceiptSnapshotUnchanged(expectedSnapshot);
   await mkdir(dirname(receiptPath), { recursive: true });
+  let existingReceiptInfo: Awaited<ReturnType<typeof lstat>> | undefined;
+  try {
+    const info = await lstat(receiptPath);
+    if (info.isSymbolicLink() || !info.isFile()) throw new Error("invalid prompt-cache-key receipt path");
+    existingReceiptInfo = info;
+  } catch (error) {
+    if (getErrorCode(error) !== "ENOENT") throw error;
+  }
   const tempPath = uniqueTempPath(receiptPath, "config-receipt");
   try {
     await writeFile(tempPath, JSON.stringify(receipt, null, 2) + "\n", { encoding: "utf8", mode: 0o600, flag: "wx" });
+    const tempInfo = await lstat(tempPath);
+    if (tempInfo.isSymbolicLink() || !tempInfo.isFile()) throw new Error("invalid temporary prompt-cache-key receipt");
     await chmod(tempPath, 0o600);
-    await rename(tempPath, receiptPath);
+    const assertDestinationUnchanged = async (): Promise<void> => {
+      try {
+        const currentInfo = await lstat(receiptPath);
+        if (!existingReceiptInfo || !sameFileIdentity(existingReceiptInfo, currentInfo)) {
+          throw new Error("prompt-cache-key receipt changed during atomic write");
+        }
+      } catch (error) {
+        if (getErrorCode(error) !== "ENOENT" || existingReceiptInfo) throw error;
+      }
+      if (expectedSnapshot) await assertPromptCacheKeyConfigReceiptSnapshotUnchanged(expectedSnapshot);
+    };
+    await assertDestinationUnchanged();
+    if (beforeRename) await beforeRename();
+    await assertDestinationUnchanged();
+    if (existingReceiptInfo) {
+      await rename(tempPath, receiptPath);
+    } else {
+      await link(tempPath, receiptPath);
+      await unlink(tempPath).catch((cleanupError) => {
+        console.warn(`${LOG_PREFIX}: committed prompt-cache-key receipt but failed to remove its temporary hard link`, cleanupError);
+      });
+    }
   } catch (error) {
     await unlink(tempPath).catch((cleanupError) => { if (getErrorCode(cleanupError) !== "ENOENT") console.warn(`${LOG_PREFIX}: failed to remove temporary config receipt`, cleanupError); });
     throw error;
@@ -2211,6 +2269,7 @@ async function applyPromptCacheKeyConfigFixUnderLock(
   const key = modelKey(model);
   const existingOmit = current.promptCacheKey?.omit ?? [];
   const targetHadModelKey = existingOmit.includes(key);
+  if (targetHadModelKey) throw new Error("prompt-cache-key is already configured; no changes were made");
   const omit = [...new Set([...existingOmit, key])].sort();
   const next: PersistedCacheOptimizerConfigV2 = { ...current, version: 2, promptCacheKey: { omit } };
   const modifiedText = JSON.stringify(next, null, 2) + "\n";
@@ -2238,8 +2297,19 @@ async function applyPromptCacheKeyConfigFixUnderLock(
         if (getErrorCode(error) !== "ENOENT") throw error;
       }
     }
-    await rename(tempPath, configPath);
-    committedInfo = await lstat(configPath);
+    if (originalInfo) {
+      await rename(tempPath, configPath);
+      committedInfo = await lstat(configPath);
+    } else {
+      // Do not overwrite a config created after the absence check. Record the
+      // committed inode before cleaning up its temporary hard-link name so a
+      // cleanup failure can still compensate the config transaction.
+      await link(tempPath, configPath);
+      committedInfo = await lstat(configPath);
+      await unlink(tempPath).catch((cleanupError) => {
+        console.warn(`${LOG_PREFIX}: committed optimizer config but failed to remove its temporary hard link`, cleanupError);
+      });
+    }
     const receipt: PromptCacheKeyConfigReceipt = {
       version: 2,
       kind: "pi-cache-optimizer-config-receipt",
@@ -2259,10 +2329,17 @@ async function applyPromptCacheKeyConfigFixUnderLock(
     return { receipt, backupPath };
   } catch (error) {
     await unlink(tempPath).catch(() => {});
-    if (targetExistedBefore && committedInfo) {
-      await atomicRestoreFileFromBackup(backupPath, configPath, mode, { identity: committedInfo, hash: afterHash, mode }).catch(() => {});
-    } else if (!targetExistedBefore && committedInfo) {
-      await validateAtomicTarget(configPath, { identity: committedInfo, hash: afterHash, mode }).then(() => unlink(configPath)).catch(() => {});
+    try {
+      if (targetExistedBefore && committedInfo) {
+        await atomicRestoreFileFromBackup(backupPath, configPath, mode, { identity: committedInfo, hash: afterHash, mode });
+      } else if (!targetExistedBefore && committedInfo) {
+        await validateAtomicTarget(configPath, { identity: committedInfo, hash: afterHash, mode });
+        await unlink(configPath);
+      }
+    } catch (compensationError) {
+      const writeMessage = error instanceof Error ? error.message : String(error);
+      const compensationMessage = compensationError instanceof Error ? compensationError.message : String(compensationError);
+      throw new Error(`prompt-cache-key fix receipt update failed (${writeMessage}) and config compensation failed (${compensationMessage})`);
     }
     throw error;
   }
@@ -2276,15 +2353,26 @@ async function applyPromptCacheKeyConfigFix(
   return withModelsJsonTransactionLock(() => applyPromptCacheKeyConfigFixUnderLock(model, configPath, receiptPath));
 }
 
+type PromptCacheKeyRollbackOptions = {
+  /** Test-only race injector; production callers leave this undefined. */
+  beforeReceiptRename?: () => Promise<void>;
+};
+
 async function rollbackPromptCacheKeyConfigUnderLock(
-  receipt: PromptCacheKeyConfigReceipt,
+  snapshot: PromptCacheKeyConfigReceiptSnapshot,
   configPath: string = CONFIG_FILE_PATH,
   receiptPath: string = CONFIG_RECEIPT_PATH,
+  options: PromptCacheKeyRollbackOptions = {},
 ): Promise<void> {
+  if (snapshot.receiptPath !== receiptPath) throw new Error("prompt-cache-key receipt path changed since the rollback preview");
+  await assertPromptCacheKeyConfigReceiptSnapshotUnchanged(snapshot);
+  const receipt = snapshot.receipt;
   const currentInfo = await lstat(configPath);
   if (currentInfo.isSymbolicLink() || !currentInfo.isFile()) throw new Error("optimizer config is not a regular file; refusing to overwrite user changes");
   const currentText = await readFile(configPath, "utf8");
-  if (hashText(currentText) !== receipt.afterHash) throw new Error("optimizer config changed after the fix; refusing to overwrite user changes");
+  const currentHash = hashText(currentText);
+  const currentMode = currentInfo.mode & 0o7777;
+  if (currentHash !== receipt.afterHash) throw new Error("optimizer config changed after the fix; refusing to overwrite user changes");
   const current = parsePersistedCacheOptimizerConfig(JSON.parse(currentText));
   if (!current) throw new Error("optimizer config is invalid; refusing to overwrite user changes");
   const key = `${receipt.provider}/${receipt.modelId}`;
@@ -2292,46 +2380,90 @@ async function rollbackPromptCacheKeyConfigUnderLock(
   if (receipt.targetHadModelKey) throw new Error("prompt-cache-key was already configured before this fix; refusing to remove user configuration");
   const omit = current.version === 2 ? current.promptCacheKey?.omit ?? [] : [];
   if (!omit.includes(receipt.addedModelKey)) throw new Error("prompt-cache-key opt-out is no longer present; refusing to change user config");
+
+  let rollbackResultText: string | undefined;
+  let rollbackResultMode: number | undefined;
+  let rollbackResultInfo: Awaited<ReturnType<typeof lstat>> | undefined;
   const backupPath = configReceiptBackupPath(receipt, receiptPath);
   if (receipt.targetExistedBefore) {
     const backupInfo = await lstat(backupPath);
     if (backupInfo.isSymbolicLink() || !backupInfo.isFile()) throw new Error("config backup is not a regular file");
     const backupText = await readFile(backupPath, "utf8");
     if (hashText(backupText) !== receipt.beforeHash) throw new Error("config backup hash does not match the fix receipt");
+    rollbackResultText = backupText;
+    rollbackResultMode = backupInfo.mode & 0o7777;
     await atomicRestoreFileFromBackup(
       backupPath,
       configPath,
-      backupInfo.mode & 0o7777,
-      { backupHash: receipt.beforeHash, identity: currentInfo, hash: hashText(currentText), mode: currentInfo.mode & 0o7777 },
+      rollbackResultMode,
+      { backupHash: receipt.beforeHash, identity: currentInfo, hash: currentHash, mode: currentMode },
     );
+    rollbackResultInfo = await lstat(configPath);
+  } else if (current.footerMode || omit.length > 1) {
+    const restored: PersistedCacheOptimizerConfigV2 = {
+      version: 2,
+      ...(current.footerMode ? { footerMode: current.footerMode } : {}),
+      ...(omit.length > 1 ? { promptCacheKey: { omit: omit.filter((item) => item !== receipt.addedModelKey) } } : {}),
+    };
+    rollbackResultText = JSON.stringify(restored, null, 2) + "\n";
+    rollbackResultMode = currentMode;
+    await atomicReplaceTextFilePreservingMode(
+      configPath,
+      rollbackResultText,
+      rollbackResultMode,
+      "config-rollback",
+      { identity: currentInfo, hash: currentHash, mode: currentMode },
+    );
+    rollbackResultInfo = await lstat(configPath);
   } else {
-    if (current.footerMode || omit.length > 1) {
-      const restored: PersistedCacheOptimizerConfigV2 = {
-        version: 2,
-        ...(current.footerMode ? { footerMode: current.footerMode } : {}),
-        ...(omit.length > 1 ? { promptCacheKey: { omit: omit.filter((item) => item !== receipt.addedModelKey) } } : {}),
-      };
-      await atomicReplaceTextFilePreservingMode(
-        configPath,
-        JSON.stringify(restored, null, 2) + "\n",
-        currentInfo.mode & 0o7777,
-        "config-rollback",
-        { identity: currentInfo, hash: hashText(currentText), mode: currentInfo.mode & 0o7777 },
-      );
-    } else {
-      await validateAtomicTarget(configPath, { identity: currentInfo, hash: hashText(currentText), mode: currentInfo.mode & 0o7777 });
-      await unlink(configPath);
+    await validateAtomicTarget(configPath, { identity: currentInfo, hash: currentHash, mode: currentMode });
+    await unlink(configPath);
+  }
+
+  try {
+    await writePromptCacheKeyConfigReceipt(
+      { ...receipt, status: "rolled_back", rolledBackAt: Date.now() },
+      receiptPath,
+      snapshot,
+      options.beforeReceiptRename,
+    );
+  } catch (receiptError) {
+    // Receipt marking is part of the transaction. If it fails after the config
+    // mutation, restore the exact post-fix config rather than leaving an
+    // actionable receipt paired with an already-rolled-back file.
+    try {
+      if (rollbackResultText === undefined) {
+        await atomicCreateTextFileNoReplace(configPath, currentText, currentMode, "config-rollback-compensation");
+      } else {
+        if (!rollbackResultInfo || rollbackResultMode === undefined) throw new Error("missing rollback result guard");
+        await atomicReplaceTextFilePreservingMode(
+          configPath,
+          currentText,
+          currentMode,
+          "config-rollback-compensation",
+          {
+            identity: rollbackResultInfo,
+            hash: hashText(rollbackResultText),
+            mode: rollbackResultMode,
+          },
+        );
+      }
+    } catch (compensationError) {
+      const receiptMessage = receiptError instanceof Error ? receiptError.message : String(receiptError);
+      const compensationMessage = compensationError instanceof Error ? compensationError.message : String(compensationError);
+      throw new Error(`prompt-cache-key rollback receipt update failed (${receiptMessage}) and config compensation failed (${compensationMessage})`);
     }
+    throw receiptError;
   }
-  await writePromptCacheKeyConfigReceipt({ ...receipt, status: "rolled_back", rolledBackAt: Date.now() }, receiptPath);
 }
 
 async function rollbackPromptCacheKeyConfig(
-  receipt: PromptCacheKeyConfigReceipt,
+  snapshot: PromptCacheKeyConfigReceiptSnapshot,
   configPath: string = CONFIG_FILE_PATH,
   receiptPath: string = CONFIG_RECEIPT_PATH,
+  options: PromptCacheKeyRollbackOptions = {},
 ): Promise<void> {
-  return withModelsJsonTransactionLock(() => rollbackPromptCacheKeyConfigUnderLock(receipt, configPath, receiptPath));
+  return withModelsJsonTransactionLock(() => rollbackPromptCacheKeyConfigUnderLock(snapshot, configPath, receiptPath, options));
 }
 
 function resolveFooterStatsMode(
@@ -2470,7 +2602,7 @@ function isPiBuiltInLlamaCppModel(model: PiModel | undefined): boolean {
 }
 
 function shouldInjectOpenAIPromptCacheKeyForModel(model: PiModel | undefined): boolean {
-  // Pi 0.85.1 has no native supportsPromptCacheKey compat field. Per-model
+  // Pi 0.87.1 has no native supportsPromptCacheKey compat field. Per-model
   // opt-out is owned by this extension's promptCacheKey.omit configuration;
   // this helper only exposes the transport API gate for fixture consumers.
   return isOpenAICompatibleApi(model?.api);
@@ -3679,22 +3811,25 @@ function hasPromptCacheRetentionUnsupportedErrorMessage(message: unknown): boole
 }
 
 function hasPromptCacheKeyUnsupportedText(value: unknown): boolean {
-  const normalized = lower(value).replace(/["'`]/g, "").replace(/[_-]+/g, "_").replace(/\s+/g, " ").trim();
-  const key = "(?:prompt ?cache ?key|prompt_cache_key)";
+  const normalized = lower(value)
+    .replace(/["'`]/g, "")
+    .replace(/[\s_-]+/g, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+  const key = String.raw`(?:prompt ?cache ?key|promptcachekey)`;
+  const field = String.raw`(?:parameter|field|input|argument)`;
+  const unsupported = String.raw`(?:unsupported|unknown|unrecognized|unexpected|not supported|not allowed|not permitted|must be omitted|should be omitted)`;
   if (!new RegExp(key).test(normalized)) return false;
 
-  // Only classify a field-level capability rejection. Value validation,
-  // conditional restrictions, and generic invalid-parameter messages are not
-  // proof that the endpoint lacks support for the field.
-  return [
-    new RegExp(`unsupported (?:parameter|field|input|argument)[: ]+.*${key}`),
-    new RegExp(`unknown (?:parameter|field|input|argument)[: ]+.*${key}`),
-    new RegExp(`unrecognized (?:parameter|field|input|argument)[: ]+.*${key}`),
-    new RegExp(`(?:parameter|field|input|argument)[: ]+${key} (?:is )?(?:unsupported|unknown|unrecognized|not supported|not allowed|not permitted)`),
-    new RegExp(`${key} (?:is )?(?:unsupported|unknown|unrecognized|not supported|not allowed|not permitted)`),
-    new RegExp(`extra inputs?(?: are)? (?:not permitted|not allowed)[: ]+.*${key}`),
-    new RegExp(`(?:not supported|not permitted|not allowed)[: ]+.*${key}`),
-  ].some((pattern) => pattern.test(normalized));
+  // 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`(?=$|[}\]>,.;])`;
+  return (
+    new RegExp(String.raw`(?:unsupported|unknown|unrecognized|unexpected)\s+${field}\s*[:=]?\s*${key}${terminal}`).test(normalized) ||
+    new RegExp(String.raw`(?:extra\s+inputs?|${field}\s+not\s+(?:allowed|permitted|supported))\s*[:=]\s*${key}${terminal}`).test(normalized) ||
+    new RegExp(String.raw`${key}(?:\s+${field})?\s*[:=]?\s*(?:is\s+)?${unsupported}${terminal}`).test(normalized)
+  );
 }
 
 function hasPromptCacheKeyUnsupportedSignal(headers: Record<string, string> | undefined): boolean {
@@ -4065,7 +4200,7 @@ function buildOpenAIProxyCompatWarningText(key: string, missing: string[]): stri
   const modelsJsonPath = getModelsJsonDisplayPath();
   const lines: string[] = [
     `💡 pi-cache-optimizer: ${key} is a third-party OpenAI-compatible proxy but merged compat lacks ${missing.join(" and ")}.`,
-    `Edit ${modelsJsonPath} -> providers["${providerLabel}"] -> compat (at the same level as baseUrl/api/apiKey/models).`,
+    `Run /cache-optimizer fix to preview a confirmed repair (or edit ${modelsJsonPath} -> providers["${providerLabel}"] -> compat manually).`,
     ``,
   ];
 
@@ -5177,7 +5312,12 @@ function notifyCacheCompatIfNeeded(
   const text = adapter?.warningText?.(model);
   if (!adapter || !text) return;
 
-  const key = `${adapter.id}:${modelKey(model)}`;
+  const affinityOnly = adapter.warningText !== undefined &&
+    describeMissingOpenAICompatibleProxyCompat(model).length === 1 &&
+    describeMissingCacheCompatForModel(model).length === 1;
+  const key = affinityOnly
+    ? `proxy-affinity:${model.provider}`
+    : `${adapter.id}:${modelKey(model)}`;
   if (warnedModels.has(key)) return;
   warnedModels.add(key);
 
@@ -7290,6 +7430,50 @@ interface ModelOverrideNodeLocation {
   modelOverrideCompatEnd: number;
 }
 
+interface ProviderCompatNodeLocation {
+  providerObjectBrace: number;
+  providerObjectEnd: number;
+  providerCompatBrace: number;
+  providerCompatEnd: number;
+}
+
+/** Locate a unique provider and its direct compat object without requiring models[]. */
+function locateProviderCompatInJsonc(
+  text: string,
+  providerLabel: string,
+): ProviderCompatNodeLocation | undefined {
+  const clean = stripJsoncComments(text);
+  const rootBrace = skipJsonWhitespace(clean, 0);
+  if (clean[rootBrace] !== "{") return undefined;
+  const providersKey = findJsonObjectKey(clean, rootBrace, "providers");
+  if (!providersKey || providersKey.count !== 1) return undefined;
+  const providersBrace = skipJsonWhitespace(clean, providersKey.valueStart);
+  if (clean[providersBrace] !== "{") return undefined;
+  const providersEnd = findMatchingBracket(clean, providersBrace);
+  if (providersEnd === undefined) return undefined;
+  const providerKey = findJsonObjectKey(clean, providersBrace, providerLabel);
+  if (!providerKey || providerKey.count !== 1 || providerKey.keyStart > providersEnd) return undefined;
+  const providerObjectBrace = skipJsonWhitespace(clean, providerKey.valueStart);
+  if (clean[providerObjectBrace] !== "{") return undefined;
+  const providerObjectEnd = findMatchingBracket(clean, providerObjectBrace);
+  if (providerObjectEnd === undefined || providerObjectEnd > providersEnd) return undefined;
+
+  for (const key of ["models", "modelOverrides"]) {
+    const child = findJsonObjectKey(clean, providerObjectBrace, key);
+    if (child?.count && child.count > 1) return undefined;
+  }
+  const compatKey = findJsonObjectKey(clean, providerObjectBrace, "compat");
+  if (compatKey?.count && compatKey.count > 1) return undefined;
+  if (!compatKey) {
+    return { providerObjectBrace, providerObjectEnd, providerCompatBrace: -1, providerCompatEnd: -1 };
+  }
+  const providerCompatBrace = skipJsonWhitespace(clean, compatKey.valueStart);
+  if (clean[providerCompatBrace] !== "{") return undefined;
+  const providerCompatEnd = findMatchingBracket(clean, providerCompatBrace);
+  if (providerCompatEnd === undefined || providerCompatEnd > providerObjectEnd) return undefined;
+  return { providerObjectBrace, providerObjectEnd, providerCompatBrace, providerCompatEnd };
+}
+
 /** Locate a provider and optional modelOverrides entry without requiring models[]. */
 function locateModelOverrideInJsonc(
   text: string,
@@ -8248,9 +8432,44 @@ function chooseFixPlacement(
   return decision;
 }
 
+type CompatInsertionLocation = Pick<ModelNodeLocation,
+  | "modelObjectBrace"
+  | "compatObjectBrace"
+  | "compatObjectEnd"
+  | "providerObjectBrace"
+  | "providerCompatBrace"
+  | "providerCompatEnd"
+  | "modelOverrideObjectBrace"
+  | "modelOverrideCompatBrace"
+  | "modelOverrideCompatEnd"
+>;
+
+function composeProviderAffinityInsertion(
+  original: string,
+  providerLabel: string,
+): { modifiedText: string; placementLabel: string } | undefined {
+  const location = locateProviderCompatInJsonc(original, providerLabel);
+  if (!location) return undefined;
+  const node: CompatInsertionLocation = {
+    modelObjectBrace: -1,
+    compatObjectBrace: -1,
+    compatObjectEnd: -1,
+    providerObjectBrace: location.providerObjectBrace,
+    providerCompatBrace: location.providerCompatBrace,
+    providerCompatEnd: location.providerCompatEnd,
+    modelOverrideObjectBrace: -1,
+    modelOverrideCompatBrace: -1,
+    modelOverrideCompatEnd: -1,
+  };
+  return {
+    modifiedText: composeFixInsertion(original, node, { sendSessionAffinityHeaders: true }, "provider"),
+    placementLabel: `providers["${providerLabel}"] -> compat (provider level)`,
+  };
+}
+
 function composeFixInsertion(
   original: string,
-  location: ModelNodeLocation,
+  location: CompatInsertionLocation,
   compatKeys: Record<string, unknown>,
   placement: "provider" | "model" | "modelOverride" = "model",
 ): string {
@@ -8688,6 +8907,41 @@ async function atomicReplaceTextFilePreservingMode(
   }
 }
 
+async function atomicCreateTextFileNoReplace(
+  targetPath: string,
+  content: string,
+  mode: number,
+  purpose: string,
+  /** Test-only race injector; production callers leave this undefined. */
+  beforeLink?: () => Promise<void>,
+): Promise<void> {
+  const tempPath = uniqueTempPath(targetPath, purpose);
+  try {
+    await writeFile(tempPath, content, { encoding: "utf8", mode, flag: "wx" });
+    const tempInfo = await lstat(tempPath);
+    if (tempInfo.isSymbolicLink() || !tempInfo.isFile()) {
+      throw new Error("temporary creation is not a regular file");
+    }
+    await chmod(tempPath, mode);
+    // A hard link gives us an atomic no-replace create. Unlike rename(), it
+    // cannot overwrite a file that appeared after the absence check.
+    if (beforeLink) await beforeLink();
+    await link(tempPath, targetPath);
+    await unlink(tempPath).catch((cleanupError) => {
+      console.warn(`${LOG_PREFIX}: committed config file but failed to remove its temporary hard link`, cleanupError);
+    });
+  } catch (error) {
+    try {
+      await unlink(tempPath);
+    } catch (cleanupError) {
+      if (getErrorCode(cleanupError) !== "ENOENT") {
+        console.warn(`${LOG_PREFIX}: failed to remove temporary config file`, cleanupError);
+      }
+    }
+    throw error;
+  }
+}
+
 async function atomicRestoreFileFromBackup(
   backupPath: string,
   targetPath: string,
@@ -9205,7 +9459,14 @@ async function writeModelsJsonFixReceipt(
     await assertReceiptDestinationUnchanged();
     if (beforeRename) await beforeRename();
     await assertReceiptDestinationUnchanged();
-    await rename(tempPath, receiptPath);
+    if (existingReceiptInfo) {
+      await rename(tempPath, receiptPath);
+    } else {
+      await link(tempPath, receiptPath);
+      await unlink(tempPath).catch((cleanupError) => {
+        console.warn(`${LOG_PREFIX}: committed fix receipt but failed to remove its temporary hard link`, cleanupError);
+      });
+    }
   } catch (error) {
     try {
       await unlink(tempPath);
@@ -9287,20 +9548,27 @@ function locateReceiptCompatTarget(
     };
   }
 
+  if (placement === "provider") {
+    const location = locateProviderCompatInJsonc(text, provider);
+    if (!location) return undefined;
+    return {
+      targetExists: true,
+      compatBrace: location.providerCompatBrace,
+      compatEnd: location.providerCompatEnd,
+    };
+  }
   const location = locateModelInJsonc(text, provider, modelId);
   if (!location || location.providerKeyCount !== 1) return undefined;
-  // A changed-file surgical rollback cannot tell which duplicate model object
-  // was the receipt's target. Refuse that ambiguity instead of touching a
-  // later user-added definition. Provider-level changes do not need to inspect
-  // model compat, but duplicate target ids still make the receipt identity
-  // ambiguous and are rejected for both placements.
+  // A changed-file model-scoped rollback cannot tell which duplicate model
+  // object was the receipt's target. Refuse that ambiguity instead of touching
+  // a later user-added definition. Provider-level receipts returned above do
+  // not depend on model-array identity.
   if (location.allModelIds.filter((id) => id === modelId).length !== 1) return undefined;
-  if (placement === "provider" && location.providerCompatKeyCount > 1) return undefined;
-  if (placement === "model" && location.modelCompatKeyCount > 1) return undefined;
+  if (location.modelCompatKeyCount > 1) return undefined;
   return {
     targetExists: location.modelObjectBrace >= 0,
-    compatBrace: placement === "provider" ? location.providerCompatBrace : location.compatObjectBrace,
-    compatEnd: placement === "provider" ? location.providerCompatEnd : location.compatObjectEnd,
+    compatBrace: location.compatObjectBrace,
+    compatEnd: location.compatObjectEnd,
   };
 }
 
@@ -9925,6 +10193,7 @@ export const __internals_for_tests = {
   parsePromptCacheKeyConfigReceipt,
   isActionablePromptCacheKeyConfigReceipt,
   readPromptCacheKeyConfigReceipt,
+  readPromptCacheKeyConfigReceiptSnapshot,
   writePromptCacheKeyConfigReceipt,
   applyPromptCacheKeyConfigFix,
   rollbackPromptCacheKeyConfig,
@@ -9985,11 +10254,13 @@ export const __internals_for_tests = {
   hasExplicitLongRetentionOptInFromConfig,
   locateModelInJsonc,
   locateModelOverrideInJsonc,
+  locateProviderCompatInJsonc,
   composeFixInsertion,
   selfCheckFix,
   analyzeModelsJsonForMissingEntry,
   composeMissingEntryInsertion,
   composeModelOverrideInsertion,
+  composeProviderAffinityInsertion,
   selfCheckMissingEntryInsertion,
   decideFixPlacement,
   chooseFixPlacement,
@@ -9998,6 +10269,7 @@ export const __internals_for_tests = {
   formatCompatKeysForInsertion,
   backupTimestamp,
   atomicReplaceTextFilePreservingMode,
+  atomicCreateTextFileNoReplace,
   atomicRestoreFileFromBackup,
   applyModelsJsonFixTransaction,
   hashText,
@@ -10071,7 +10343,11 @@ export default function (pi: ExtensionAPI) {
   // finalized assistant message consumes the oldest completed record, falling
   // back to the oldest request only when a transport emitted no response hook.
   // This preserves response A when request B/C starts before message_end(A).
-  type ProviderRequestState = { model: PiModel; responseReceived: boolean };
+  type ProviderRequestState = {
+    model: PiModel;
+    responseReceived: boolean;
+    correlationAmbiguous: boolean;
+  };
   const providerRequestStates: ProviderRequestState[] = [];
   let shardCreatedAt = Date.now();
   const PERSIST_DEBOUNCE_MS = 2000;
@@ -10094,7 +10370,12 @@ export default function (pi: ExtensionAPI) {
       };
     }
     if (isSessionAffinity403Applicable(model) && sendSessionAffinityHeaders403Models.has(key)) {
-      return { providerLabel, modelId: model.id, compatKeys: { sendSessionAffinityHeaders: false } };
+      return {
+        providerLabel,
+        modelId: model.id,
+        compatKeys: { sendSessionAffinityHeaders: false },
+        forceModelLevel: true,
+      };
     }
     return undefined;
   }
@@ -10772,10 +11053,11 @@ export default function (pi: ExtensionAPI) {
 
   pi.on("before_provider_request", (event, ctx) => {
     const requestModel = resolveRouteModel(ctx.model, ctx) ?? ctx.model;
-    if (runtimeOptimizerEnabled) {
-      const snapshot = snapshotProviderRequestModel(requestModel);
-      if (snapshot) providerRequestStates.push({ model: snapshot, responseReceived: false });
-    }
+    // Request-local identity is also needed by the always-on Anthropic TTL
+    // validity repair, so retain the credential-blind snapshot even while the
+    // optional runtime optimizer features are disabled.
+    const snapshot = snapshotProviderRequestModel(requestModel);
+    if (snapshot) providerRequestStates.push({ model: snapshot, responseReceived: false, correlationAmbiguous: false });
     let requestPayload: unknown = event.payload;
     let toolOrderChanged = false;
 
@@ -10843,9 +11125,25 @@ export default function (pi: ExtensionAPI) {
   });
 
   pi.on("after_provider_response", async (event, ctx) => {
-    const responseState = providerRequestStates.find((state) => !state.responseReceived);
+    const pendingStates = providerRequestStates.filter((state) => !state.responseReceived);
+    let responseState: ProviderRequestState | undefined;
+    if (pendingStates.length === 1) {
+      responseState = pendingStates[0];
+    } else if (pendingStates.length > 1) {
+      const pendingModelKeys = new Set(pendingStates.map((state) => modelKey(state.model)));
+      if (pendingModelKeys.size === 1) {
+        // Identity is still exact when concurrent requests use the same model.
+        responseState = pendingStates[0];
+      } else {
+        // Pi supplies no request id here, so out-of-order concurrent responses
+        // cannot be assigned safely. Preserve the lifecycle records for a
+        // message-local identity, but never turn ambiguous headers into a
+        // model-scoped persistent-fix suggestion.
+        for (const state of pendingStates) state.correlationAmbiguous = true;
+      }
+    }
     if (responseState) responseState.responseReceived = true;
-    const model = responseState?.model ?? (resolveRouteModel(ctx.model, ctx) ?? ctx.model);
+    const model = responseState?.model ?? (pendingStates.length === 0 ? (resolveRouteModel(ctx.model, ctx) ?? ctx.model) : undefined);
     if (!runtimeOptimizerEnabled || !model) return;
 
     // Keep only the category, never the provider's complete error text. This
@@ -10938,21 +11236,39 @@ export default function (pi: ExtensionAPI) {
   pi.on("message_end", async (event, ctx) => {
     syncSessionHash(ctx);
     const msgRecord = asRecord(event.message);
-    const requestModelForMessage = msgRecord?.role === "assistant"
+    const requestCorrelationForMessage = msgRecord?.role === "assistant"
       ? (() => {
+        const explicitModel = modelFromAssistantMessage(event.message, undefined);
+        const explicitIndex = explicitModel
+          ? providerRequestStates.findIndex((state) => modelKey(state.model) === modelKey(explicitModel))
+          : -1;
         const completedIndex = providerRequestStates.findIndex((state) => state.responseReceived);
-        const index = completedIndex >= 0 ? completedIndex : 0;
-        return providerRequestStates.splice(index, 1)[0]?.model;
+        const contextModel = resolveRouteModel(ctx.model, ctx) ?? ctx.model;
+        const contextIndex = contextModel && !providerRequestStates.some((state) => state.correlationAmbiguous)
+          ? providerRequestStates.findIndex((state) => modelKey(state.model) === modelKey(contextModel))
+          : -1;
+        const index = explicitIndex >= 0
+          ? explicitIndex
+          : (completedIndex >= 0 ? completedIndex : (contextIndex >= 0 ? contextIndex : 0));
+        const state = providerRequestStates.splice(index, 1)[0];
+        if (!state) return { model: undefined, ambiguous: false };
+        return {
+          model: state.correlationAmbiguous && explicitIndex < 0 ? undefined : state.model,
+          ambiguous: state.correlationAmbiguous && explicitIndex < 0,
+        };
       })()
-      : undefined;
+      : { model: undefined, ambiguous: false };
+    const requestModelForMessage = requestCorrelationForMessage.model;
+    const contextualFallbackForMessage = requestCorrelationForMessage.ambiguous
+      ? undefined
+      : (resolveRouteModel(ctx.model, ctx) ?? ctx.model);
 
     // Some providers expose an HTTP 400 error body only through the finalized
     // assistant error message; after_provider_response may contain the status
     // and no diagnostic response headers. Record only the model-scoped
     // reasoning-protocol category from that authoritative message identity.
     if (runtimeOptimizerEnabled && hasReasoningProtocolRejectionErrorMessage(event.message)) {
-      const fallbackModel = requestModelForMessage
-        ?? (resolveRouteModel(ctx.model, ctx) ?? ctx.model);
+      const fallbackModel = requestModelForMessage ?? contextualFallbackForMessage;
       const messageModel = modelFromAssistantMessage(event.message, fallbackModel) ?? fallbackModel;
       const errorModel = messageModel
         ? findModelInRegistry(ctx.modelRegistry, messageModel.provider, messageModel.id) ?? messageModel
@@ -10967,7 +11283,7 @@ export default function (pi: ExtensionAPI) {
       }
     }
     if (runtimeOptimizerEnabled && hasPromptCacheKeyUnsupportedErrorMessage(event.message)) {
-      const fallbackModel = requestModelForMessage ?? (resolveRouteModel(ctx.model, ctx) ?? ctx.model);
+      const fallbackModel = requestModelForMessage ?? contextualFallbackForMessage;
       const messageModel = modelFromAssistantMessage(event.message, fallbackModel) ?? fallbackModel;
       const errorModel = messageModel
         ? findModelInRegistry(ctx.modelRegistry, messageModel.provider, messageModel.id) ?? messageModel
@@ -10985,8 +11301,7 @@ export default function (pi: ExtensionAPI) {
       }
     }
     if (runtimeOptimizerEnabled && hasPromptCacheRetentionUnsupportedErrorMessage(event.message)) {
-      const fallbackModel = requestModelForMessage
-        ?? (resolveRouteModel(ctx.model, ctx) ?? ctx.model);
+      const fallbackModel = requestModelForMessage ?? contextualFallbackForMessage;
       const messageModel = modelFromAssistantMessage(event.message, fallbackModel) ?? fallbackModel;
       const errorModel = messageModel
         ? findModelInRegistry(ctx.modelRegistry, messageModel.provider, messageModel.id) ?? messageModel
@@ -11010,8 +11325,7 @@ export default function (pi: ExtensionAPI) {
     // non-retryable 400 in Pi 0.82.1, so the fallback applies to the next
     // subsequent request (and to a retry only if another layer initiates one).
     if (hasAnthropicCacheTtlOrderError(event.message)) {
-      const fallbackModel = requestModelForMessage
-        ?? (resolveRouteModel(ctx.model, ctx) ?? ctx.model);
+      const fallbackModel = requestModelForMessage ?? contextualFallbackForMessage;
       const errorModel = modelFromAssistantMessage(event.message, fallbackModel) ?? fallbackModel;
       if (errorModel && isAnthropicMessagesApi(errorModel.api)) {
         const key = modelKey(errorModel);
@@ -11240,12 +11554,14 @@ export default function (pi: ExtensionAPI) {
           cmdCtx.ui.notify("No active model selected. Select a model first with /model or pi --model.", "warning");
           return;
         }
-        const configReceipt = await readPromptCacheKeyConfigReceipt();
+        const configReceiptSnapshot = await readPromptCacheKeyConfigReceiptSnapshot();
+        const configReceipt = configReceiptSnapshot?.receipt;
         const modelsReceipt = await readModelsJsonFixReceipt();
         const useConfigReceipt = isActionablePromptCacheKeyConfigReceipt(configReceipt) &&
           configReceipt.provider === model.provider &&
           configReceipt.modelId === model.id &&
-          (!isActionableModelsJsonFixReceipt(modelsReceipt) || modelsReceipt.provider !== model.provider || modelsReceipt.modelId !== model.id || configReceipt.appliedAt >= modelsReceipt.appliedAt);
+          (!isActionableModelsJsonFixReceipt(modelsReceipt) || modelsReceipt.provider !== model.provider ||
+            (modelsReceipt.placement !== "provider" && modelsReceipt.modelId !== model.id) || configReceipt.appliedAt >= modelsReceipt.appliedAt);
         if (useConfigReceipt) {
           if (!cmdCtx.hasUI) {
             cmdCtx.ui.notify("❌ Rollback requires interactive confirmation. No changes were made.\nRun /cache-optimizer rollback in Pi's interactive UI to restore the prompt-cache-key setting.", "warning");
@@ -11260,7 +11576,8 @@ export default function (pi: ExtensionAPI) {
             return;
           }
           try {
-            await rollbackPromptCacheKeyConfig(configReceipt);
+            if (!configReceiptSnapshot) throw new Error("prompt-cache-key receipt changed since the rollback preview");
+            await rollbackPromptCacheKeyConfig(configReceiptSnapshot);
             setPersistedCacheOptimizerConfig(readPersistedCacheOptimizerConfig());
             cmdCtx.ui.notify(`✅ Restored prompt_cache_key behavior for ${modelKey(model)}. Run /reload or restart Pi for the change to take effect.`, "info");
           } catch (error) {
@@ -11287,7 +11604,7 @@ export default function (pi: ExtensionAPI) {
           cmdCtx.ui.notify("ℹ️ No unapplied /cache-optimizer fix receipt was found.", "info");
           return;
         }
-        if (receipt.provider !== model.provider || receipt.modelId !== model.id) {
+        if (receipt.provider !== model.provider || (receipt.placement !== "provider" && receipt.modelId !== model.id)) {
           cmdCtx.ui.notify(
             `ℹ️ The latest fix receipt is for ${receipt.provider}/${receipt.modelId}, not the active model ${model.provider}/${model.id}. ` +
             "Switch to the matching model before running rollback. No changes were made.",
@@ -11525,6 +11842,79 @@ export default function (pi: ExtensionAPI) {
         const location = locateModelInJsonc(originalText, suggestion.providerLabel, suggestion.modelId);
         if (!location) {
           const diagnosis = analyzeModelsJsonForMissingEntry(originalText, suggestion.providerLabel, suggestion.modelId);
+          const parsedOriginal = (() => { try { return parseJsonc(originalText); } catch { return undefined; } })();
+          const provider = asRecord(asRecord(parsedOriginal)?.providers)?.[suggestion.providerLabel];
+          const explicit = resolveExplicitCompatValue(parsedOriginal, suggestion.providerLabel, suggestion.modelId, "sendSessionAffinityHeaders");
+          const targetOverrideLocation = locateModelOverrideInJsonc(
+            originalText, suggestion.providerLabel, suggestion.modelId,
+          );
+          const hasTargetOverride = (targetOverrideLocation?.modelOverrideObjectBrace ?? -1) >= 0;
+          const providerPlan = diagnosis && diagnosis.scenario !== "provider_missing" &&
+            isValidModelsConfigForEffectiveCompat(parsedOriginal) && asRecord(provider) &&
+            Object.keys(suggestion.compatKeys).length === 1 && suggestion.compatKeys.sendSessionAffinityHeaders === true &&
+            !suggestion.forceModelLevel && !hasTargetOverride && explicit === undefined &&
+            getEffectiveCompatValueSource(model, parsedOriginal, "sendSessionAffinityHeaders") === undefined
+              ? composeProviderAffinityInsertion(originalText, suggestion.providerLabel)
+              : undefined;
+          if (providerPlan) {
+            const checkProvider = (writtenText: string): string | null => {
+              try {
+                const changed = parseJsonc(writtenText);
+                if (!isValidModelsConfigForEffectiveCompat(changed)) return "provider config is invalid";
+                if (resolveEffectiveCompatFromConfig(model, changed).sendSessionAffinityHeaders !== true) return "affinity flag is not effective";
+                const reverted = JSON.parse(JSON.stringify(changed)) as Record<string, unknown>;
+                const target = asRecord(asRecord(reverted.providers)?.[suggestion.providerLabel]);
+                const compat = asRecord(target?.compat);
+                if (!target || !compat || compat.sendSessionAffinityHeaders !== true) return "provider affinity key is missing";
+                delete compat.sendSessionAffinityHeaders;
+                const originalCompat = asRecord(asRecord(provider)?.compat);
+                if (!originalCompat) delete target.compat;
+                return JSON.stringify(reverted) === JSON.stringify(parsedOriginal) ? null : "unrelated configuration was altered";
+              } catch { return "invalid provider JSONC"; }
+            };
+            const checkError = checkProvider(providerPlan.modifiedText);
+            if (checkError) {
+              cmdCtx.ui.notify(`❌ Provider-level self-check failed: ${checkError}. No changes were made.`, "error");
+              return;
+            }
+            const backupPath = `${MODELS_JSON_PATH}.backup-cache-optimizer-${backupTimestamp()}`;
+            const confirmed = await cmdCtx.ui.confirm("Cache Optimizer — Fix provider affinity", [
+              `📝 Preview of changes to ${getModelsJsonDisplayPath()}:`,
+              `Location: ${providerPlan.placementLabel}`,
+              `Compat JSON to write: ${JSON.stringify(suggestion.compatKeys)}`,
+              `⚠️ This affects all models using this provider across all sessions; model-level overrides remain authoritative.`,
+              `A timestamped backup will be written to: ${backupPath}`,
+              "Run /reload or restart Pi for the change to take effect.",
+              "Apply these changes?",
+            ].join("\n"));
+            if (!confirmed) {
+              cmdCtx.ui.notify("No changes were made. Canceled by user.", "info");
+              return;
+            }
+            const receipt = createModelsJsonFixReceipt(
+              originalText, providerPlan.modifiedText, suggestion.providerLabel, suggestion.modelId,
+              "provider", suggestion.compatKeys, true, backupPath,
+            );
+            if (!receipt) {
+              cmdCtx.ui.notify("❌ Could not create a privacy-safe fix receipt. No changes were made.", "error");
+              return;
+            }
+            try {
+              const result = await applyModelsJsonFixTransaction(providerPlan.modifiedText, backupPath, checkProvider, {
+                expectedCurrentHash: hashText(originalText), purpose: "fix",
+                onCommitted: async () => writeModelsJsonFixReceipt(receipt),
+              });
+              if ("postCheckError" in result) {
+                cmdCtx.ui.notify(`❌ Post-write self-check failed: ${result.postCheckError}. Backup restored.`, "error");
+                return;
+              }
+              invalidateModelsConfigCache();
+              cmdCtx.ui.notify(`✅ Fix applied to ${getModelsJsonDisplayPath()}.\nBackup saved to: ${backupPath}\nRun /reload or restart Pi.`, "info");
+            } catch (error) {
+              cmdCtx.ui.notify(`❌ Write failed: ${error instanceof Error ? error.message : String(error)}. Backup may be at: ${backupPath}`, "error");
+            }
+            return;
+          }
           if (diagnosis && cmdCtx.hasUI) {
             const overrideLocation = locateModelOverrideInJsonc(
               originalText, suggestion.providerLabel, suggestion.modelId,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-cache-optimizer",
-  "version": "2.8.9",
+  "version": "2.8.11",
   "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",
@@ -35,8 +35,8 @@
     "check": "npm run typecheck && npm test && npm run check:diff && npm run check:pack"
   },
   "devDependencies": {
-    "@earendil-works/pi-coding-agent": "^0.85.1",
-    "@earendil-works/pi-server": "0.85.1",
+    "@earendil-works/pi-coding-agent": "^0.87.1",
+    "@earendil-works/pi-server": "0.87.1",
     "@types/node": "^22.0.0",
     "jiti": "^2.7.0",
     "typescript": "^5.8.3"