pi-cache-optimizer 2.8.25 → 2.8.26

package/README.md

@@ -63,7 +63,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.1.0. It uses the official Pi package types directly for type-checking, along with extension hooks, `getAgentDir()`, and prompt options shared by those versions; it does not depend on Pi 0.83+ APIs such as `ctx.scopedModels` or the bundled TypeBox 1.3 aliases. Native virtual model support and codemode nested-call coalescing activate only on Pi 0.99+ hosts that produce them; older hosts keep the previous behavior. The local development baseline uses Node.js 22.19.0 or newer, matching Pi 1.0.3's engine requirement.
+This extension requires Pi 0.82+ and is validated against Pi 1.3.0. It uses the official Pi package types directly for type-checking, along with extension hooks, `getAgentDir()`, and prompt options shared by those versions; it does not depend on Pi 0.83+ APIs such as `ctx.scopedModels` or the bundled TypeBox 1.3 aliases. Native virtual model support and codemode nested-call coalescing activate only on Pi 0.99+ hosts that produce them; older hosts keep the previous behavior. The local development baseline uses Node.js 22.19.0 or newer, matching Pi 1.0.3's engine requirement.
 
 ## Commands
 
@@ -82,9 +82,10 @@ This extension requires Pi 0.82+ and is validated against Pi 1.1.0. It uses the
 | `/cache-optimizer fix` | Auto-repairs safe compat issues for the active model. Shows preview + risk warning, requires confirmation. It writes `models.json` only for native compat fixes, or the extension config for an evidenced `prompt_cache_key` issue. |
 | `/cache-optimizer fix prompt-cache` | Adds `promptCache` lifetimes for the active model so Pi's native cache warming can run. Preview, backup, receipt, and rollback. Requires confirmation. |
 | `/cache-optimizer fix prompt-cache-key` | Explicitly configures the active OpenAI-compatible provider/model to omit `prompt_cache_key` and `promptCacheKey` from the final request body. Requires confirmation. |
+| `/cache-optimizer fix kimi-base-url` | Appends `/v1` to an official Kimi Code base URL (`api.kimi.com` / `api.kimi.ai`, path `/coding`) for a model on OpenAI Chat Completions (Pi 1.3.0+ `kimi-coding`). Preview, backup, receipt, and rollback. Requires confirmation. |
 | `/cache-optimizer rollback` | Reviews the latest matching confirmed fix and, after UI confirmation, restores either the extension config or `models.json` fix safely. |
 
-`/cache-optimizer` uses Pi's native Tab completion. Type `/cache-optimizer <Tab>` for the supported subcommands, `/cache-optimizer stats <Tab>` for `all` or `contributors`, `/cache-optimizer fix <Tab>` for `prompt-cache-key`, `/cache-optimizer c<Tab>` for `config`, `/cache-optimizer config <Tab>` for `footer-mode`, and `/cache-optimizer config footer-mode <Tab>` for `total`, `session`, or `process`. Suggestions are prefix-filtered and invalid prefixes are left to Pi's normal fallback behavior.
+`/cache-optimizer` uses Pi's native Tab completion. Type `/cache-optimizer <Tab>` for the supported subcommands, `/cache-optimizer stats <Tab>` for `all` or `contributors`, `/cache-optimizer fix <Tab>` for `prompt-cache`, `prompt-cache-key`, or `kimi-base-url`, `/cache-optimizer c<Tab>` for `config`, `/cache-optimizer config <Tab>` for `footer-mode`, and `/cache-optimizer config footer-mode <Tab>` for `total`, `session`, or `process`. Suggestions are prefix-filtered and invalid prefixes are left to Pi's normal fallback behavior.
 
 The interactive `/cache-optimizer` menu includes `Footer mode`, where you can choose `total`, `session`, or `process`. `enable` / `disable` are current-process switches. For a persistent opt-out, use environment variables below.
 
@@ -209,7 +210,7 @@ Notes:
 
 Pi itself can keep a prompt cache alive by re-sending the last request with a one-token output cap shortly before the entry expires (the global `cacheWarming` setting: `off`, `streaming` (default), or `idle`; change it with `/settings` → Cache warming or `"cacheWarming"` in `~/.pi/agent/settings.json`). This extension does not run a keepalive timer of its own: a second warmer would pay for duplicate refreshes and cannot replay Pi's exact request.
 
-Pi only warms a model that declares a cache lifetime for the retention tier in use, has input/cache prices, and is replayable (Anthropic budget-based thinking is not). Custom proxy models in `models.json` often lack the first two, so warming never starts. For models whose prices are all zero, Pi stops with "cache economics unavailable"; this extension answers Pi's `cache_warming_decision` with `warm` in that case only, since a refresh is just a cache read plus one output token. Models with real prices keep Pi's own decision, and Pi's mode, lifetime, replayability and time limits still apply. Each refresh is a real request, so a channel that does bill despite the zero prices pays for it. Pi's `/session` still shows "cache economics unavailable" between refreshes, and if another extension also handles `cache_warming_decision`, the one Pi runs last wins. Turn it off with `/cache-optimizer config zero-price-warming off` or `PI_CACHE_OPTIMIZER_NO_ZERO_PRICE_WARMING=1`. `/cache-optimizer doctor` now reports the mode, the tier, and what is missing, with a snippet such as `"promptCache": {"short":300,"long":3600}` for `anthropic-messages` models. Put it on the model entry (custom models) or under the provider's `modelOverrides` (built-in models), or run `/cache-optimizer fix prompt-cache` to have it written for you: it previews the edit, asks for confirmation, keeps a timestamped backup and comments, and records a receipt so `/cache-optimizer rollback` removes exactly that `promptCache` object (or restores the whole file if nothing else changed). It writes `{"short":300,"long":3600}` for `anthropic-messages` models (Anthropic's documented 5m/1h, the values Pi ships for its own Claude models) and `{"short":300}` elsewhere; when the long tier is in use and no long lifetime is documented for the API, it refuses rather than guessing. It never merges into or overwrites an existing `promptCache`, and it does not create a provider entry that models.json lacks.
+Pi only warms a model that declares a cache lifetime for the retention tier in use, has input/cache prices, and is replayable (Anthropic budget-based thinking is not). Custom proxy models in `models.json` often lack the first two, so warming never starts. For models whose prices are all zero, Pi stops with "cache economics unavailable"; this extension answers Pi's `cache_warming_decision` with `warm` in that case only, since a refresh is just a cache read plus one output token. Models with real prices keep Pi's own decision, and Pi's mode, lifetime, replayability and time limits still apply. Each refresh is a real request, so a channel that does bill despite the zero prices pays for it. Pi's `/session` still shows "cache economics unavailable" between refreshes, and if another extension also handles `cache_warming_decision`, the one Pi runs last wins. Two zeros are not treated as free: OpenRouter router models (ids starting with `openrouter/`, such as `openrouter/auto`), whose -1 placeholder price Pi 1.2.0+ shows as 0 although the routed model is billed, and models whose Pi 1.2.0 `cost.tiers` carry a positive price. Turn it off with `/cache-optimizer config zero-price-warming off` or `PI_CACHE_OPTIMIZER_NO_ZERO_PRICE_WARMING=1`. `/cache-optimizer doctor` now reports the mode, the tier, and what is missing, with a snippet such as `"promptCache": {"short":300,"long":3600}` for `anthropic-messages` models. Put it on the model entry (custom models) or under the provider's `modelOverrides` (built-in models), or run `/cache-optimizer fix prompt-cache` to have it written for you: it previews the edit, asks for confirmation, keeps a timestamped backup and comments, and records a receipt so `/cache-optimizer rollback` removes exactly that `promptCache` object (or restores the whole file if nothing else changed). It writes `{"short":300,"long":3600}` for `anthropic-messages` models (Anthropic's documented 5m/1h, the values Pi ships for its own Claude models) and `{"short":300}` elsewhere; when the long tier is in use and no long lifetime is documented for the API, it refuses rather than guessing. It never merges into or overwrites an existing `promptCache`, and it does not create a provider entry that models.json lacks.
 
 Streaming warming stops 60 minutes after the real request and idle warming after 30 minutes. With this extension's 1-hour retention, the refresh would fire at 54 minutes, so `idle` adds nothing; the 1-hour lifetime already covers breaks under an hour. Keep the default `streaming` unless you use 5-minute caches and often return within half an hour.
 
@@ -284,6 +285,8 @@ For Kimi Coding K3 custom channels, use model-level compat when the provider con
 
 Pi 0.80.9+ already includes Kimi K3 in built-in Kimi Coding, Moonshot AI / China, OpenRouter, and Vercel AI Gateway catalogs. The Moonshot/OpenRouter variants use their OpenAI-compatible transport and continue through the normal Kimi footer/proxy path; the adaptive compat above applies only to `anthropic-messages` Kimi Coding channels.
 
+**Pi 1.3.0+:** the built-in `kimi-coding` provider now uses OpenAI Chat Completions (`openai-completions`) at `https://api.kimi.com/coding/v1` (international: `https://api.kimi.ai/coding/v1`), and Pi ships its compat (`thinkingFormat: "openai"`, `reasoning_content` replay). The K3 adaptive compat above therefore only applies to older Pi versions or custom channels that still declare `anthropic-messages`. The official Kimi Code hosts are first-party origins, not proxies, so doctor/compat/fix no longer flag them for `sendSessionAffinityHeaders`; Kimi reached through a third-party relay is still checked as before. A `baseUrl` override left over from the Anthropic era (`https://api.kimi.com/coding`, no `/v1`) makes every Chat Completions request fail: doctor reports it, and `/cache-optimizer fix kimi-base-url` (or plain `fix`) appends `/v1` with a preview, backup, receipt and rollback. It only touches an official host with the bare `/coding` path on a model that actually uses `openai-completions`; proxies, other paths and Anthropic-protocol entries get a hint and are never changed. A provider-level `baseUrl` that also feeds a custom or built-in model on another API (for example the `anthropic-messages` built-ins of Pi < 1.3.0) is refused; set `baseUrl` on the model entry instead.
+
 `/cache-optimizer doctor` and `/cache-optimizer compat` detect missing flags and show copyable JSON.
 
 ## Auto-repair with `/cache-optimizer fix`

package/README.zh-CN.md

@@ -63,7 +63,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.1.0 验证。TypeScript 校验直接使用官方 Pi package 类型，同时只使用这些版本共有的 extension hooks、`getAgentDir()` 和 prompt options；不依赖 Pi 0.83+ 专有 API（例如 `ctx.scopedModels` 或 bundled TypeBox 1.3 aliases）。原生虚拟模型支持与 codemode 嵌套工具调用合并只在会产生它们的 Pi 0.99+ 上生效，较早版本保持原有行为。本地开发基线需要 Node.js 22.19.0 或更高版本，与 Pi 1.0.3 的 engine 要求一致。
+本扩展要求 Pi 0.82+，并已使用 Pi 1.3.0 验证。TypeScript 校验直接使用官方 Pi package 类型，同时只使用这些版本共有的 extension hooks、`getAgentDir()` 和 prompt options；不依赖 Pi 0.83+ 专有 API（例如 `ctx.scopedModels` 或 bundled TypeBox 1.3 aliases）。原生虚拟模型支持与 codemode 嵌套工具调用合并只在会产生它们的 Pi 0.99+ 上生效，较早版本保持原有行为。本地开发基线需要 Node.js 22.19.0 或更高版本，与 Pi 1.0.3 的 engine 要求一致。
 
 ## 命令
 
@@ -82,9 +82,10 @@ Pi 0.79.7 及之后，`pi update` 默认只更新 Pi 本体。若要更新已安
 | `/cache-optimizer fix` | 为当前模型自动修复安全的 compat 问题。展示预览 + 风险提示，需要用户确认；原生 compat 修复写 `models.json`，已观测到的 `prompt_cache_key` 问题写扩展配置。 |
 | `/cache-optimizer fix prompt-cache` | 为当前模型写入 `promptCache` 缓存时长，让 Pi 原生保温生效。带预览、备份、receipt 和回滚。需要确认。 |
 | `/cache-optimizer fix prompt-cache-key` | 明确把当前 OpenAI-compatible provider/model 配置为从最终请求体移除 `prompt_cache_key` 与 `promptCacheKey`。需要确认。 |
+| `/cache-optimizer fix kimi-base-url` | 为使用 OpenAI Chat Completions 的模型（Pi 1.3.0+ `kimi-coding`）在官方 Kimi Code base URL（`api.kimi.com` / `api.kimi.ai`，路径 `/coding`）后补 `/v1`。带预览、备份、receipt 和回滚。需要确认。 |
 | `/cache-optimizer rollback` | 查看最近一次匹配的已确认修复；经 UI 确认后安全恢复扩展配置或 `models.json` 修复。 |
 
-`/cache-optimizer` 使用 Pi 原生 Tab 补全：输入 `/cache-optimizer <Tab>` 查看支持的子命令，输入 `/cache-optimizer stats <Tab>` 补全 `all` 或 `contributors`，输入 `/cache-optimizer fix <Tab>` 补全 `prompt-cache-key`，输入 `/cache-optimizer c<Tab>` 补全 `config`，输入 `/cache-optimizer config <Tab>` 补全 `footer-mode`，输入 `/cache-optimizer config footer-mode <Tab>` 补全 `total`、`session` 或 `process`。建议会按当前前缀过滤；无效前缀返回空结果，由 Pi 正常回退处理。
+`/cache-optimizer` 使用 Pi 原生 Tab 补全：输入 `/cache-optimizer <Tab>` 查看支持的子命令，输入 `/cache-optimizer stats <Tab>` 补全 `all` 或 `contributors`，输入 `/cache-optimizer fix <Tab>` 补全 `prompt-cache`、`prompt-cache-key` 或 `kimi-base-url`，输入 `/cache-optimizer c<Tab>` 补全 `config`，输入 `/cache-optimizer config <Tab>` 补全 `footer-mode`，输入 `/cache-optimizer config footer-mode <Tab>` 补全 `total`、`session` 或 `process`。建议会按当前前缀过滤；无效前缀返回空结果，由 Pi 正常回退处理。
 
 交互式 `/cache-optimizer` 菜单包含 `Footer mode`，可以选择 `total`、`session` 或 `process`。`enable` / `disable` 是当前进程内开关。若要持久关闭某些能力，请使用下面的环境变量。
 
@@ -209,7 +210,7 @@ Pi 0.84.1 还修复了内置 Fireworks 渠道对拒绝 `prompt_cache_retention`
 
 Pi 自带缓存保温：在缓存条目过期前，用一个 token 的输出上限原样重放上一次请求（全局设置 `cacheWarming`：`off`、`streaming`（默认）或 `idle`；在 `/settings` → Cache warming 中修改，或在 `~/.pi/agent/settings.json` 中设置 `"cacheWarming"`）。本扩展不自行运行保活定时器：第二个保温器会重复计费，而且无法精确重放 Pi 的请求。
 
-Pi 只会为满足以下条件的模型保温：为当前保留档位声明了缓存时长、有输入/缓存价格、请求可重放（Anthropic 基于 budget 的 thinking 不可重放）。`models.json` 里的自定义代理模型常常缺前两项，保温根本不会启动。对价格全为 0 的模型，Pi 会以 “cache economics unavailable” 停止保温；本扩展仅在这种情况下通过 `cache_warming_decision` 返回 `warm`，因为一次刷新只是一次缓存读取加一个输出 token。有真实价格的模型仍按 Pi 自己的判断，Pi 的模式、缓存时长、可重放性和时间上限也照常生效。每次刷新都是一次真实请求，若渠道价格写 0 但实际计费，会产生费用。刷新间隔里 Pi 的 `/session` 仍会显示 “cache economics unavailable”；若其他扩展也处理 `cache_warming_decision`，以 Pi 最后执行的那个为准。可用 `/cache-optimizer config zero-price-warming off` 或 `PI_CACHE_OPTIMIZER_NO_ZERO_PRICE_WARMING=1` 关闭。`/cache-optimizer doctor` 现在会显示保温模式、档位和缺失项，并给出片段，例如 `anthropic-messages` 模型的 `"promptCache": {"short":300,"long":3600}`。自定义模型写在该模型条目中，内置模型写在 provider 的 `modelOverrides` 下；也可以运行 `/cache-optimizer fix prompt-cache` 一键写入：先预览、需确认、保留带时间戳的备份和注释，并记录 receipt，`/cache-optimizer rollback` 只会删除这次加入的 `promptCache` 对象（若文件之后没有改动则整文件恢复）。`anthropic-messages` 模型写入 `{"short":300,"long":3600}`（Anthropic 文档的 5 分钟/1 小时，与 Pi 内置 Claude 模型一致），其他 API 写入 `{"short":300}`；若当前使用长档位而该 API 没有文档化的长时长，则拒绝写入而不是猜测。已有 `promptCache` 时不会合并或覆盖，models.json 中不存在的 provider 条目也不会被创建。
+Pi 只会为满足以下条件的模型保温：为当前保留档位声明了缓存时长、有输入/缓存价格、请求可重放（Anthropic 基于 budget 的 thinking 不可重放）。`models.json` 里的自定义代理模型常常缺前两项，保温根本不会启动。对价格全为 0 的模型，Pi 会以 “cache economics unavailable” 停止保温；本扩展仅在这种情况下通过 `cache_warming_decision` 返回 `warm`，因为一次刷新只是一次缓存读取加一个输出 token。有真实价格的模型仍按 Pi 自己的判断，Pi 的模式、缓存时长、可重放性和时间上限也照常生效。每次刷新都是一次真实请求，若渠道价格写 0 但实际计费，会产生费用。刷新间隔里 Pi 的 `/session` 仍会显示 “cache economics unavailable”；若其他扩展也处理 `cache_warming_decision`，以 Pi 最后执行的那个为准。有两种 0 不算免费：OpenRouter 路由模型（ID 以 `openrouter/` 开头，如 `openrouter/auto`），其 -1 占位价格在 Pi 1.2.0+ 显示为 0，但实际按路由到的模型计费；以及 Pi 1.2.0 `cost.tiers` 中有正价格的模型。可用 `/cache-optimizer config zero-price-warming off` 或 `PI_CACHE_OPTIMIZER_NO_ZERO_PRICE_WARMING=1` 关闭。`/cache-optimizer doctor` 现在会显示保温模式、档位和缺失项，并给出片段，例如 `anthropic-messages` 模型的 `"promptCache": {"short":300,"long":3600}`。自定义模型写在该模型条目中，内置模型写在 provider 的 `modelOverrides` 下；也可以运行 `/cache-optimizer fix prompt-cache` 一键写入：先预览、需确认、保留带时间戳的备份和注释，并记录 receipt，`/cache-optimizer rollback` 只会删除这次加入的 `promptCache` 对象（若文件之后没有改动则整文件恢复）。`anthropic-messages` 模型写入 `{"short":300,"long":3600}`（Anthropic 文档的 5 分钟/1 小时，与 Pi 内置 Claude 模型一致），其他 API 写入 `{"short":300}`；若当前使用长档位而该 API 没有文档化的长时长，则拒绝写入而不是猜测。已有 `promptCache` 时不会合并或覆盖，models.json 中不存在的 provider 条目也不会被创建。
 
 streaming 保温在真实请求后 60 分钟停止，idle 保温在 30 分钟后停止。本扩展使用 1 小时保留时，刷新会在第 54 分钟才触发，所以 `idle` 没有额外作用；1 小时的缓存本身已覆盖一小时内的中断。除非你使用 5 分钟缓存且经常在半小时内回来，否则保持默认的 `streaming` 即可。
 
@@ -284,6 +285,8 @@ Kimi Coding K3 自定义渠道如果包含混合模型，建议使用模型级 c
 
 Pi 0.80.9+ 已在内置 Kimi Coding、Moonshot AI / 中国区、OpenRouter 和 Vercel AI Gateway catalog 中加入 Kimi K3。Moonshot/OpenRouter 变体使用 OpenAI-compatible transport，继续走普通 Kimi footer / proxy 路径；上面的 adaptive compat 只适用于 `anthropic-messages` Kimi Coding 渠道。
 
+**Pi 1.3.0+：** 内置 `kimi-coding` 改用 OpenAI Chat Completions（`openai-completions`），地址为 `https://api.kimi.com/coding/v1`（海外：`https://api.kimi.ai/coding/v1`），compat 由 Pi 自带（`thinkingFormat: "openai"`、`reasoning_content` 回传）。因此上面的 K3 adaptive compat 只适用于旧版 Pi，或仍声明 `anthropic-messages` 的自定义渠道。官方 Kimi Code 地址是源站而不是代理，doctor/compat/fix 不再对它提示缺 `sendSessionAffinityHeaders`；经第三方中转访问 Kimi 时仍照常检查。Anthropic 时代留下的 `baseUrl` 覆盖（`https://api.kimi.com/coding`，缺 `/v1`）会让所有 Chat Completions 请求失败：doctor 会报告，`/cache-optimizer fix kimi-base-url`（或直接 `fix`）会补上 `/v1`，带预览、备份、receipt 和回滚。只处理官方域名、路径恰为 `/coding`、且模型实际使用 `openai-completions` 的情况；代理、其他路径和 Anthropic 协议条目只提示，不会修改。provider 级 `baseUrl` 若同时被其他 API 的自定义或内置模型继承（例如 Pi < 1.3.0 的 `anthropic-messages` 内置模型），则拒绝修改；请改在该模型条目上设置 `baseUrl`。
+
 `/cache-optimizer doctor` 和 `/cache-optimizer compat` 会检测缺失的 flag 并显示可复制的 JSON。
 
 ## 使用 `/cache-optimizer fix` 自动修复

package/package.json

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

package/src/cache-warming.ts

@@ -70,11 +70,46 @@ function hasPricing(model: PiModel): boolean {
   return ["input", "cacheRead", "cacheWrite"].some((key) => typeof cost[key] === "number" && (cost[key] as number) > 0);
 }
 
-/** Every price Pi uses for warming economics is zero or missing. */
-function isZeroPriced(model: PiModel): boolean {
+const PRICE_KEYS = ["input", "output", "cacheRead", "cacheWrite"] as const;
+
+function hasPositivePrice(record: Record<string, unknown> | undefined): boolean {
+  if (!record) return false;
+  return PRICE_KEYS.some((key) => typeof record[key] === "number" && (record[key] as number) > 0);
+}
+
+/**
+ * OpenRouter router models (`openrouter/auto`, `openrouter/free`-style ids)
+ * forward to whichever model the router picks. OpenRouter lists them with a -1
+ * placeholder price, which Pi 1.2.0+ normalises to 0, so a zero cost block
+ * means "unknown", not "free". Matched on the id prefix so the same router
+ * reached through another provider entry is covered too.
+ */
+export function isOpenRouterRouterModel(model: PiModel): boolean {
+  return typeof model.id === "string" && model.id.toLowerCase().startsWith("openrouter/");
+}
+
+function costTiers(cost: Record<string, unknown>): unknown[] {
+  return Array.isArray(cost.tiers) ? cost.tiers : [];
+}
+
+/** Prompt-length tiers carry prices but the base cost block does not. */
+function hasOnlyTierPrices(model: PiModel): boolean {
+  const cost = asRecord((model as unknown as Record<string, unknown>).cost);
+  if (!cost || hasPositivePrice(cost)) return false;
+  return costTiers(cost).some((tier) => hasPositivePrice(asRecord(tier)));
+}
+
+/**
+ * Every price Pi uses for warming economics is zero or missing, including the
+ * prompt-length cost tiers Pi 1.2.0 added, and the zero is not a placeholder
+ * for an unknown router price.
+ */
+export function isZeroPriced(model: PiModel): boolean {
+  if (isOpenRouterRouterModel(model)) return false;
   const cost = asRecord((model as unknown as Record<string, unknown>).cost);
   if (!cost) return true;
-  return ["input", "output", "cacheRead", "cacheWrite"].every((key) => !(typeof cost[key] === "number" && (cost[key] as number) > 0));
+  if (hasPositivePrice(cost)) return false;
+  return !costTiers(cost).some((tier) => hasPositivePrice(asRecord(tier)));
 }
 
 function isReplayableForWarming(model: PiModel): boolean {
@@ -141,6 +176,12 @@ export function buildCacheWarmingDiagnosis(model: PiModel, input: CacheWarmingDi
   if (!hasPricing(model)) {
     if (input.zeroPriceWarming && isZeroPriced(model)) {
       lines.push("- The model has no input/cache prices. Pi would skip warming; this extension overrides that (config zero-price-warming on).");
+    } else if (isOpenRouterRouterModel(model)) {
+      issues.push("pricing_unknown");
+      lines.push("- ⚠️ OpenRouter router models list a placeholder price that Pi shows as 0, but the routed model is billed at its own price. Pi cannot estimate savings and skips warming; zero-price warming does not apply.");
+    } else if (hasOnlyTierPrices(model)) {
+      issues.push("pricing_missing");
+      lines.push("- ⚠️ The model has prompt-length price tiers but no base input/cache prices, so Pi cannot estimate savings and skips warming. Add base prices to the cost block.");
     } else {
       issues.push("pricing_missing");
       lines.push("- ⚠️ The model has no input/cache prices, so Pi cannot estimate savings and skips warming. Add a cost block, or turn on /cache-optimizer config zero-price-warming.");

package/src/command-completion.ts

@@ -37,7 +37,7 @@ export const FEATURE_COMMAND_MAP: Record<string, PersistedCacheOptimizerFeature>
 
 export const CACHE_OPTIMIZER_STATS_ARGUMENTS = ["all", "contributors"] as const;
 
-export const CACHE_OPTIMIZER_FIX_ARGUMENTS = ["prompt-cache", "prompt-cache-key"] as const;
+export const CACHE_OPTIMIZER_FIX_ARGUMENTS = ["prompt-cache", "prompt-cache-key", "kimi-base-url"] as const;
 
 export function filterCommandCompletionItems(
   values: readonly string[],

package/src/command.ts

@@ -3,6 +3,7 @@ import { readFile } from "node:fs/promises";
 import { selectAdapterForModel } from "./adapters.ts";
 import { backupTimestamp, hashText, readRegularTextFile } from "./atomic-fs.ts";
 import { choosePromptCacheLifetimes, planPromptCacheFix, validateWrittenPromptCacheFix } from "./prompt-cache-fix.ts";
+import { buildKimiBaseUrlDoctorLines, diagnoseKimiCodeBaseUrl, planKimiBaseUrlFix, validateWrittenKimiBaseUrlFix } from "./kimi-base-url-fix.ts";
 import { FEATURE_COMMAND_MAP } from "./command-completion.ts";
 import { type PiModel, asRecord } from "./common.ts";
 import { describeMissingCacheCompatForModel, getModelsJsonDisplayPath, isAdaptiveThinkingCompatApplicable } from "./compat-advice.ts";
@@ -11,7 +12,7 @@ import { isZeroPriceWarmingEnabled, FOOTER_MODE_ENV, type FooterStatsMode, forma
 import { buildCompatDiagnosis, buildDoctorDiagnosis, buildLowHitDiagnosis, getCompatCheckNotApplicableLines, isCompatCheckApplicable, isDeepSeekCompatCheckApplicable, isPromptCacheKeyUnsupportedApplicable } from "./diagnostics.ts";
 import { locateModelOverrideInJsonc, parseJsonc } from "./jsonc.ts";
 import { invalidateModelsConfigCache, isValidModelsConfigForEffectiveCompat, modelKey } from "./model-identity.ts";
-import { analyzeModelsJsonForMissingEntry, applyModelsJsonFixTransaction, chooseFixPlacement, composeFixInsertion, composeModelOverrideInsertion, composeProviderAffinityInsertion, createModelsJsonFixReceipt, createPromptCacheFixReceipt, formatCompatKeysForInsertion, formatMissingEntryManualSnippet, isActionableModelsJsonFixReceipt, locateModelInJsonc, markModelsJsonFixReceiptRolledBack, prepareModelsJsonRollback, readModelsJsonFixReceipt, readModelsJsonFixReceiptSnapshot, resolveExplicitCompatValue, selfCheckFix, selfCheckMissingEntryInsertion, validateModelsJsonRollback, writeModelsJsonFixReceipt } from "./models-json-fix.ts";
+import { analyzeModelsJsonForMissingEntry, applyModelsJsonFixTransaction, chooseFixPlacement, composeFixInsertion, composeModelOverrideInsertion, composeProviderAffinityInsertion, createBaseUrlFixReceipt, createModelsJsonFixReceipt, createPromptCacheFixReceipt, formatCompatKeysForInsertion, formatMissingEntryManualSnippet, isActionableModelsJsonFixReceipt, locateModelInJsonc, markModelsJsonFixReceiptRolledBack, prepareModelsJsonRollback, readModelsJsonFixReceipt, readModelsJsonFixReceiptSnapshot, resolveExplicitCompatValue, selfCheckFix, selfCheckMissingEntryInsertion, validateModelsJsonRollback, writeModelsJsonFixReceipt } from "./models-json-fix.ts";
 import { MODELS_JSON_PATH } from "./paths.ts";
 import { applyPromptCacheKeyConfigFix, isActionablePromptCacheKeyConfigReceipt, readPromptCacheKeyConfigReceiptSnapshot, rollbackPromptCacheKeyConfig } from "./prompt-cache-key-config.ts";
 import { getEffectiveCompatValueSource, isPromptCacheKeyOmittedForModel } from "./request-payload.ts";
@@ -121,7 +122,8 @@ export function createCacheOptimizerCommandHandler(runtime: CommandRuntime) {
             zeroPriceWarming: isZeroPriceWarmingEnabled(),
           }).lines
           : [];
-        const fullDiagnosis = [routeNote, diagnosis, describeSkillCompressionOutcome(), describePromptCacheRetentionDecision(getLastPromptCacheRetentionDecision()), ...warmingLines, ...lowHitLines].filter((line) => line !== undefined).join("\n");
+        const kimiBaseUrlLines = buildKimiBaseUrlDoctorLines(model);
+        const fullDiagnosis = [routeNote, diagnosis, kimiBaseUrlLines.length > 0 ? kimiBaseUrlLines.join("\n") : undefined, describeSkillCompressionOutcome(), describePromptCacheRetentionDecision(getLastPromptCacheRetentionDecision()), ...warmingLines, ...lowHitLines].filter((line) => line !== undefined).join("\n");
         cmdCtx.ui.notify(fullDiagnosis, "info");
       } else if (subcommand === "stats") {
         const aggregate = await refreshShardAggregate();
@@ -286,6 +288,8 @@ export function createCacheOptimizerCommandHandler(runtime: CommandRuntime) {
 
         const rollbackScope = rollback.mode === "exact"
           ? "restore the exact pre-fix models.json because the file is unchanged since the fix"
+          : rollback.receipt.baseUrlChange
+            ? `restore baseUrl ${JSON.stringify(rollback.receipt.baseUrlChange.before)} (the value before the Kimi /v1 fix), preserving subsequent user changes`
           : rollback.receipt.promptCacheAdded
             ? "remove only the promptCache object the fix added (and restore any receipt-owned compat keys), preserving subsequent user changes"
             : "restore only the receipt-owned compat scalar keys and preserve subsequent user changes";
@@ -387,6 +391,13 @@ export function createCacheOptimizerCommandHandler(runtime: CommandRuntime) {
           return;
         }
 
+        // A Kimi Code base URL without /v1 makes every request fail, so plain
+        // `fix` handles it before any compat suggestion.
+        if (commandParts[1] === "kimi-base-url" || (commandParts[1] === undefined && diagnoseKimiCodeBaseUrl(model).kind === "fixable")) {
+          await runKimiBaseUrlFix(cmdCtx, model);
+          return;
+        }
+
         const promptCacheKeyRequested = commandParts[1] === "prompt-cache-key";
         const promptCacheKeyFixRequested = promptCacheKeyRequested || promptCacheKeyFixApplies(model);
         if (promptCacheKeyRequested && !isPromptCacheKeyUnsupportedApplicable(model)) {
@@ -1002,6 +1013,7 @@ export function createCacheOptimizerCommandHandler(runtime: CommandRuntime) {
         diagnosis.push("  fix     — Auto-fix compat issues (writes models.json or extension config, requires UI)");
         diagnosis.push("  fix prompt-cache — Add promptCache lifetimes so Pi's cache warming can run");
         diagnosis.push("  fix prompt-cache-key — Explicitly omit prompt_cache_key for the active model");
+        diagnosis.push("  fix kimi-base-url — Append /v1 to an official Kimi Code base URL (Pi 1.3.0+ OpenAI Chat Completions)");
         diagnosis.push("  rollback — Undo the latest confirmed fix (requires UI confirmation)");
         diagnosis.push("  reset   — Reset local provider/model stats for current model (does not affect upstream)");
         diagnosis.push("");
@@ -1140,3 +1152,116 @@ async function runPromptCacheFix(cmdCtx: ExtensionCommandContext, model: PiModel
     cmdCtx.ui.notify(`❌ Write failed: ${error instanceof Error ? error.message : String(error)}. No changes were kept.`, "error");
   }
 }
+
+/**
+ * `/cache-optimizer fix kimi-base-url`: append `/v1` to an official Kimi Code
+ * base URL for a model on OpenAI Chat Completions. Same safety model as the
+ * other fixes: preview + confirmation, timestamped backup, guarded atomic
+ * write, post-write check, and a receipt /cache-optimizer rollback reverses.
+ */
+async function runKimiBaseUrlFix(cmdCtx: ExtensionCommandContext, model: PiModel): Promise<void> {
+  const status = diagnoseKimiCodeBaseUrl(model);
+  if (status.kind === "hint") {
+    cmdCtx.ui.notify([...status.lines, "No changes were made."].join("\n"), "info");
+    return;
+  }
+  if (status.kind !== "fixable") {
+    cmdCtx.ui.notify(`✅ ${modelKey(model)} does not need the Kimi Code /v1 fix. No changes were made.`, "info");
+    return;
+  }
+  const manual = (reason: string): string => [
+    `❌ ${reason}. No changes were made.`,
+    "",
+    `Change the baseUrl that ${modelKey(model)} uses in ${getModelsJsonDisplayPath()} from`,
+    `  ${JSON.stringify(status.current)}`,
+    "to",
+    `  ${JSON.stringify(status.suggested)}`,
+    "then run /reload.",
+  ].join("\n");
+
+  if (!cmdCtx.hasUI) {
+    cmdCtx.ui.notify(manual("Non-interactive terminal detected. The fix requires UI confirmation"), "warning");
+    return;
+  }
+
+  let current: { text: string; mode: number };
+  try {
+    current = await readRegularTextFile(MODELS_JSON_PATH);
+  } catch {
+    cmdCtx.ui.notify(manual(`Could not read ${getModelsJsonDisplayPath()} as a regular file`), "error");
+    return;
+  }
+  let registeredModels: PiModel[] | undefined;
+  try {
+    const all = (cmdCtx as { modelRegistry?: { getAll?(): PiModel[] } }).modelRegistry?.getAll?.();
+    registeredModels = Array.isArray(all) ? all : undefined;
+  } catch {
+    registeredModels = undefined;
+  }
+  const plan = planKimiBaseUrlFix(current.text, model, registeredModels);
+  if ("error" in plan) {
+    cmdCtx.ui.notify(manual(`Cannot edit models.json safely: ${plan.error}`), "error");
+    return;
+  }
+
+  const backupPath = `${MODELS_JSON_PATH}.backup-cache-optimizer-${backupTimestamp()}`;
+  const pendingReceipt = await readModelsJsonFixReceipt();
+  const confirmed = await cmdCtx.ui.confirm("Cache Optimizer — Fix Kimi Code base URL", [
+    `📝 Preview of changes to ${getModelsJsonDisplayPath()}:`,
+    `Location: ${plan.locationLabel}`,
+    `Before: ${JSON.stringify(plan.before)}`,
+    `After:  ${JSON.stringify(plan.after)}`,
+    plan.affectedNote ?? "",
+    "",
+    "Why: this model uses OpenAI Chat Completions (Pi 1.3.0+ kimi-coding), whose official endpoint is /coding/v1.",
+    "Without /v1, requests go to /coding/chat/completions and fail.",
+    "",
+    `A timestamped backup will be written to: ${backupPath}`,
+    "Only this string changes; comments and unrelated fields are preserved. Undo with /cache-optimizer rollback.",
+    isActionableModelsJsonFixReceipt(pendingReceipt)
+      ? `⚠️ This replaces the rollback receipt of the earlier fix for ${pendingReceipt.provider}/${pendingReceipt.modelId}; its backup ${pendingReceipt.backupFile} stays on disk.`
+      : "",
+    "Run /reload or restart Pi for the change to take effect.",
+    "",
+    "Apply this change?",
+  ].filter((line, index, lines) => line !== "" || lines[index - 1] !== "").join("\n"));
+  if (!confirmed) {
+    cmdCtx.ui.notify("No changes were made. Canceled by user.", "info");
+    return;
+  }
+
+  const receipt = createBaseUrlFixReceipt(
+    current.text, plan.modifiedText, model.provider, model.id,
+    plan.placement, plan.before, plan.after, backupPath,
+  );
+  if (!receipt) {
+    cmdCtx.ui.notify("❌ Could not create a fix receipt for rollback. No changes were made.", "error");
+    return;
+  }
+  try {
+    const result = await applyModelsJsonFixTransaction(
+      plan.modifiedText,
+      backupPath,
+      (writtenText) => validateWrittenKimiBaseUrlFix(writtenText, plan),
+      {
+        expectedCurrentHash: hashText(current.text),
+        expectedCurrentMode: current.mode,
+        purpose: "fix",
+        onCommitted: async () => writeModelsJsonFixReceipt(receipt),
+      },
+    );
+    if ("postCheckError" in result) {
+      cmdCtx.ui.notify(`❌ Post-write self-check failed: ${result.postCheckError}. Backup restored.`, "error");
+      return;
+    }
+    invalidateModelsConfigCache();
+    cmdCtx.ui.notify(
+      `✅ baseUrl updated to ${plan.after} for ${modelKey(model)}.\n` +
+      `Backup saved to: ${backupPath}\n` +
+      "Run /reload or restart Pi, then /cache-optimizer doctor to confirm.",
+      "info",
+    );
+  } catch (error) {
+    cmdCtx.ui.notify(`❌ Write failed: ${error instanceof Error ? error.message : String(error)}. No changes were kept.`, "error");
+  }
+}

package/src/compat-advice.ts

@@ -1,6 +1,6 @@
 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 { getCompat, isDeepSeekLikeModel, isKimiCodingEmptySignatureModel, isKnownThirdPartyOpenAIEndpoint, isOpenAICompatibleProxyApi, isThirdPartyOpenAIProxyEndpoint, isOpenAIFamilyModel, isPiBuiltInLlamaCppModel, isRoutedFallbackModel } from "./model-identity.ts";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import { homedir } from "node:os";
 
@@ -86,7 +86,7 @@ export function describeMissingOpenAICompatibleProxyCompat(model: PiModel): stri
   const missing: string[] = [];
 
   if (!isOpenAICompatibleProxyApi(model.api)) return missing;
-  if (!isKnownThirdPartyOpenAIEndpoint(model)) return missing;
+  if (!isThirdPartyOpenAIProxyEndpoint(model)) return missing;
   if (isPiBuiltInLlamaCppModel(model)) return missing;
 
   if (compat.sendSessionAffinityHeaders === undefined) {

package/src/diagnostics.ts

@@ -2,7 +2,7 @@ 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";
 import { type FixSuggestion } from "./fix-types.ts";
-import { getCompat, isKnownThirdPartyOpenAIEndpoint, isMistralConversationsApi, isNativeVirtualModel, isOfficialOpenAIBaseUrl, isOpenAICompatibleApi, isOpenAICompatibleProxyApi, isPiBuiltInLlamaCppModel, modelKey } from "./model-identity.ts";
+import { getCompat, isKnownThirdPartyOpenAIEndpoint, isMistralConversationsApi, isNativeVirtualModel, isOfficialOpenAIBaseUrl, isOpenAICompatibleApi, isOfficialKimiCodeEndpoint, isOpenAICompatibleProxyApi, isPiBuiltInLlamaCppModel, isThirdPartyOpenAIProxyEndpoint, modelKey } from "./model-identity.ts";
 import { type CacheUsageSample, formatRecentTrendSummary } from "./stats-report.ts";
 import { type CacheStats, emptyCacheStats } from "./stats-store.ts";
 import { snapshotBaseUrlForDiagnostics } from "./request-state.ts";
@@ -38,7 +38,7 @@ export function describeOptionalOpenAICompatibleProxyCompat(model: PiModel): str
   const optional: string[] = [];
 
   if (!isOpenAICompatibleProxyApi(model.api)) return optional;
-  if (!isKnownThirdPartyOpenAIEndpoint(model)) return optional;
+  if (!isThirdPartyOpenAIProxyEndpoint(model)) return optional;
   if (isPiBuiltInLlamaCppModel(model)) return optional;
 
   if (compat.supportsLongCacheRetention !== true) {
@@ -143,7 +143,7 @@ export function isDeepSeekCompatCheckApplicable(model: PiModel): boolean {
 }
 
 export function isCompatCheckApplicable(model: PiModel): boolean {
-  return isOpenAICompatibleProxyApi(model.api) && isKnownThirdPartyOpenAIEndpoint(model) && !isPiBuiltInLlamaCppModel(model);
+  return isOpenAICompatibleProxyApi(model.api) && isThirdPartyOpenAIProxyEndpoint(model) && !isPiBuiltInLlamaCppModel(model);
 }
 
 export function isPromptCacheRetention400Applicable(model: PiModel): boolean {
@@ -223,7 +223,7 @@ export function describeRouterChannelDiagnostics(model: PiModel): string[] {
 
   // Unknown/default endpoints and official OpenAI are not diagnosable as
   // third-party router channels. Request-header bridging also fails closed.
-  if (!isKnownThirdPartyOpenAIEndpoint(model)) {
+  if (!isThirdPartyOpenAIProxyEndpoint(model)) {
     return notes;
   }
 
@@ -404,6 +404,13 @@ export function getCompatCheckNotApplicableLines(model: PiModel): string[] {
     ];
   }
 
+  if (isOpenAICompatibleApi(api) && isOfficialKimiCodeEndpoint(model)) {
+    return [
+      "ℹ️ Compat check not applicable for this model.",
+      "   Official Kimi Code endpoint: Pi ships this provider's compat itself, and proxy session-affinity flags do not apply to a first-party origin.",
+    ];
+  }
+
   return ["ℹ️ Compat check not applicable for this model."];
 }
 
@@ -499,7 +506,9 @@ export function buildDoctorDiagnosis(model: PiModel, options: { promptCacheReten
       lines.push("   (session_id, x-client-request-id, x-session-affinity) and return 403. If you");
       lines.push("   see 403 errors, run /cache-optimizer fix to set sendSessionAffinityHeaders: false.");
     }
-  } else if (isOpenAISdkHeader403Applicable(model)) {
+  } else if (isOpenAISdkHeader403Applicable(model) && (options.openAISdkHeader403 || !isOfficialKimiCodeEndpoint(model))) {
+    // Official Kimi Code gets the 403 hint only after a 403 was observed; the
+    // passive "after disabling sendSessionAffinityHeaders" advice is proxy-only.
     lines.push("");
     if (options.openAISdkHeader403) {
       lines.push("⚠️  A 403 response was observed while sendSessionAffinityHeaders is not enabled.");

package/src/fix-types.ts

@@ -35,11 +35,12 @@ export function samePromptCacheLifetimes(left: unknown, right: unknown): boolean
 /**
  * Version 1 receipts record scalar compat changes only. Version 2 receipts
  * also record a `promptCache` object the fix added (it never overwrites one),
- * so rollback can remove exactly that property. Older extension versions
- * reject version 2 receipts instead of misreading them.
+ * so rollback can remove exactly that property. Version 3 receipts record a
+ * single `baseUrl` string rewrite (`/cache-optimizer fix kimi-base-url`).
+ * Older extension versions reject newer receipts instead of misreading them.
  */
 export type ModelsJsonFixReceiptV1 = {
-  version: 1 | 2;
+  version: 1 | 2 | 3;
   kind: "pi-cache-optimizer-fix-receipt";
   transactionId: string;
   provider: string;
@@ -49,6 +50,11 @@ export type ModelsJsonFixReceiptV1 = {
   changedKeys: Record<string, FixReceiptCompatChange>;
   /** Version 2 only: the promptCache object added at the target (absent before). */
   promptCacheAdded?: PromptCacheLifetimes;
+  /**
+   * Version 3 only: the `baseUrl` string the fix rewrote at the provider or
+   * custom model target (official Kimi Code `/coding` → `/coding/v1`).
+   */
+  baseUrlChange?: { before: string; after: string };
   beforeHash: string;
   afterHash: string;
   backupFile: string;

package/src/kimi-base-url-fix.ts

@@ -0,0 +1,249 @@
+import { type PiModel, asRecord, isNonEmptyString } from "./common.ts";
+import { parseJsonc } from "./jsonc.ts";
+import { kimiCodeV1BaseUrl, normalizeBaseUrlForComparison, parseOfficialKimiCodeBaseUrl } from "./kimi-code.ts";
+import { isValidModelsConfigForEffectiveCompat } from "./model-identity.ts";
+import { type BaseUrlFixPlacement, locateBaseUrlTarget, readBaseUrlState, replaceBaseUrlValue } from "./models-json-fix.ts";
+
+/**
+ * Kimi Code base URL check and `/cache-optimizer fix kimi-base-url`.
+ *
+ * Pi 1.3.0 moved the built-in kimi-coding provider from anthropic-messages
+ * (`https://api.kimi.com/coding`) to OpenAI Chat Completions
+ * (`https://api.kimi.com/coding/v1`). A models.json `baseUrl` left over from
+ * the Anthropic era keeps `/coding`, so Pi posts to `/coding/chat/completions`
+ * and every request fails.
+ *
+ * The fix only appends `/v1`, and only when the live model uses
+ * openai-completions and its base URL is exactly an official Kimi Code host
+ * with the bare `/coding` path. The effective API is the real condition: Pi
+ * versions before 1.3.0 ship kimi-coding as anthropic-messages, and Kimi's
+ * OpenAI-compatible endpoint has always been `/coding/v1`. Proxies, other
+ * paths, and Anthropic-protocol entries only get a hint.
+ */
+
+export type KimiBaseUrlStatus =
+  | { kind: "not-applicable" }
+  | { kind: "fixable"; current: string; suggested: string }
+  | { kind: "hint"; lines: string[] };
+
+const KIMI_CODING_PATH = /\/coding\/*$/i;
+
+export function diagnoseKimiCodeBaseUrl(model: PiModel | undefined): KimiBaseUrlStatus {
+  if (!model || !isNonEmptyString(model.baseUrl)) return { kind: "not-applicable" };
+  const api = String(model.api ?? "").toLowerCase();
+  const official = parseOfficialKimiCodeBaseUrl(model.baseUrl);
+
+  if (api === "openai-completions") {
+    if (official && !official.hasV1) {
+      const suggested = kimiCodeV1BaseUrl(model.baseUrl);
+      if (suggested) return { kind: "fixable", current: model.baseUrl, suggested };
+    }
+    if (!official && isKimiLike(model) && KIMI_CODING_PATH.test(pathOf(model.baseUrl))) {
+      return {
+        kind: "hint",
+        lines: [
+          "ℹ️ This Kimi entry uses OpenAI Chat Completions, and its base URL ends in /coding without /v1.",
+          "   Kimi Code's official OpenAI endpoint is https://api.kimi.com/coding/v1. Check what your proxy expects;",
+          "   it is not an official Kimi host, so /cache-optimizer fix leaves it unchanged.",
+        ],
+      };
+    }
+    return { kind: "not-applicable" };
+  }
+
+  if (api === "anthropic-messages" && official?.hasV1) {
+    return {
+      kind: "hint",
+      lines: [
+        "ℹ️ This Kimi Code entry uses the Anthropic Messages API, but its base URL ends in /coding/v1.",
+        "   The Anthropic endpoint is https://api.kimi.com/coding (Pi appends /v1/messages itself).",
+        "   Pi 1.3.0+ ships kimi-coding on OpenAI Chat Completions; drop the api override or the /v1. Not changed automatically.",
+      ],
+    };
+  }
+  return { kind: "not-applicable" };
+}
+
+function isKimiLike(model: PiModel): boolean {
+  const provider = String(model.provider ?? "").toLowerCase();
+  const baseUrl = String(model.baseUrl ?? "").toLowerCase();
+  return provider.includes("kimi") || provider.includes("moonshot") || baseUrl.includes("kimi") || baseUrl.includes("moonshot");
+}
+
+function pathOf(baseUrl: string): string {
+  try {
+    return new URL(baseUrl.trim()).pathname;
+  } catch {
+    return "";
+  }
+}
+
+export function buildKimiBaseUrlDoctorLines(model: PiModel | undefined): string[] {
+  const status = diagnoseKimiCodeBaseUrl(model);
+  if (status.kind === "fixable") {
+    return [
+      "",
+      "⚠️  Kimi Code base URL is missing /v1.",
+      `   Current:  ${status.current}`,
+      `   Expected: ${status.suggested}`,
+      "   This model uses OpenAI Chat Completions (Pi 1.3.0+ kimi-coding), so requests to /coding/chat/completions fail.",
+      "   Run /cache-optimizer fix kimi-base-url to append /v1 with a preview, backup and rollback.",
+    ];
+  }
+  if (status.kind === "hint") return ["", ...status.lines];
+  return [];
+}
+
+export type KimiBaseUrlFixPlan = {
+  modifiedText: string;
+  placement: BaseUrlFixPlacement;
+  before: string;
+  after: string;
+  locationLabel: string;
+  /** Other models whose base URL changes too (provider-level edits). */
+  affectedNote?: string;
+};
+
+/**
+ * Plan the models.json edit for the active model. The `baseUrl` Pi uses comes
+ * from the model's own custom `models[]` entry when it has one, otherwise
+ * from the provider entry. The located string must match the live base URL;
+ * a mismatch means something else (an extension, another file) supplies it.
+ */
+export function planKimiBaseUrlFix(
+  originalText: string,
+  model: PiModel,
+  /** Live models from Pi's registry (`modelRegistry.getAll()`), when available. */
+  registeredModels?: readonly PiModel[],
+): KimiBaseUrlFixPlan | { error: string } {
+  const status = diagnoseKimiCodeBaseUrl(model);
+  if (status.kind !== "fixable") return { error: "the active model does not need the Kimi Code /v1 fix" };
+
+  let parsed: unknown;
+  try {
+    parsed = parseJsonc(originalText);
+  } catch {
+    return { error: "models.json is not valid JSONC" };
+  }
+  if (!isValidModelsConfigForEffectiveCompat(parsed)) {
+    return { error: "models.json does not match Pi's model configuration schema" };
+  }
+  const providerRecord = asRecord(asRecord(asRecord(parsed)?.providers)?.[model.provider]);
+  if (!providerRecord) {
+    return { error: `models.json has no "${model.provider}" provider entry, so the base URL comes from somewhere else (an extension or Pi's built-in catalog)` };
+  }
+  const definitions = (Array.isArray(providerRecord.models) ? providerRecord.models : []).map(asRecord);
+  const ownDefinitions = definitions.filter((entry) => entry?.id === model.id);
+  if (ownDefinitions.length > 1) return { error: `models.json defines ${model.provider}/${model.id} more than once` };
+
+  let placement: BaseUrlFixPlacement;
+  if (ownDefinitions[0] && ownDefinitions[0].baseUrl !== undefined) {
+    placement = "model";
+  } else if (providerRecord.baseUrl !== undefined) {
+    placement = "provider";
+    if (providerRecord.oauth === "radius") {
+      return { error: "the provider uses oauth \"radius\", where Pi ignores the provider baseUrl for built-in models" };
+    }
+    // A provider-level baseUrl also feeds custom models without their own.
+    // Refuse when one of them is declared on another protocol, since /v1
+    // would break it (Anthropic Messages wants the bare /coding path).
+    const providerApi = providerRecord.api;
+    const conflicting = definitions
+      .filter((entry) => entry && entry.baseUrl === undefined)
+      .filter((entry) => {
+        const api = entry?.api ?? providerApi;
+        return api !== undefined && String(api).toLowerCase() !== "openai-completions";
+      })
+      .map((entry) => String(entry?.id));
+    if (conflicting.length > 0) {
+      return { error: `the provider baseUrl is shared with custom models on another API (${conflicting.join(", ")}); give each its own baseUrl first` };
+    }
+    // The provider baseUrl also overrides every built-in model of the
+    // provider. On Pi < 1.3.0 the built-in kimi-coding models are
+    // anthropic-messages, so a custom openai-completions entry inheriting the
+    // provider baseUrl must not drag them onto /coding/v1. Check the live
+    // registry; without it, refuse for a custom entry (built-ins unknown).
+    const ownIds = new Set(definitions.map((entry) => entry?.id));
+    if (registeredModels) {
+      const builtInConflicts = registeredModels
+        .filter((entry) => entry.provider === model.provider && !ownIds.has(entry.id))
+        .filter((entry) => String(entry.api ?? "").toLowerCase() !== "openai-completions")
+        .filter((entry) => isNonEmptyString(entry.baseUrl) && normalizeBaseUrlForComparison(entry.baseUrl) === normalizeBaseUrlForComparison(String(providerRecord.baseUrl)))
+        .map((entry) => String(entry.id));
+      if (builtInConflicts.length > 0) {
+        return { error: `the provider baseUrl is shared with built-in models on another API (${builtInConflicts.join(", ")}); set baseUrl on the ${model.id} models[] entry instead` };
+      }
+    } else if (ownDefinitions[0]) {
+      return { error: `the provider baseUrl may also feed built-in ${model.provider} models on another API; set baseUrl on the ${model.id} models[] entry instead` };
+    }
+  } else {
+    return { error: `models.json sets no baseUrl for ${model.provider}/${model.id}, so the base URL comes from somewhere else` };
+  }
+
+  const target = locateBaseUrlTarget(originalText, model.provider, model.id, placement);
+  const before = readBaseUrlState(originalText, target);
+  if (!target || before === undefined || before === "invalid") {
+    return { error: "the baseUrl entry is duplicated or cannot be located safely" };
+  }
+  if (normalizeBaseUrlForComparison(before) !== normalizeBaseUrlForComparison(status.current)) {
+    return { error: "the baseUrl in models.json differs from the active model's base URL (an extension or another source overrides it)" };
+  }
+  const after = kimiCodeV1BaseUrl(before);
+  if (!after) return { error: "the baseUrl in models.json is not a bare official Kimi Code /coding URL" };
+  const modifiedText = replaceBaseUrlValue(originalText, target, after);
+  if (modifiedText === undefined) return { error: "the baseUrl value cannot be rewritten safely" };
+
+  const locationLabel = placement === "provider"
+    ? `providers[${JSON.stringify(model.provider)}].baseUrl`
+    : `providers[${JSON.stringify(model.provider)}].models[id=${JSON.stringify(model.id)}].baseUrl`;
+  const plan: KimiBaseUrlFixPlan = {
+    modifiedText,
+    placement,
+    before,
+    after,
+    locationLabel,
+    ...(placement === "provider" ? { affectedNote: `Every ${model.provider} model without its own baseUrl uses this value.` } : {}),
+  };
+  const checkError = selfCheckKimiBaseUrlFix(originalText, plan, model.provider, model.id);
+  if (checkError) return { error: `self-check failed: ${checkError}` };
+  return plan;
+}
+
+/** The edit must be valid, write `after`, and change nothing but that string. */
+export function selfCheckKimiBaseUrlFix(originalText: string, plan: KimiBaseUrlFixPlan, provider: string, modelId: string): string | null {
+  let original: unknown;
+  let modified: unknown;
+  try {
+    original = parseJsonc(originalText);
+    modified = parseJsonc(plan.modifiedText);
+  } catch {
+    return "the edited file is not valid JSONC";
+  }
+  if (!isValidModelsConfigForEffectiveCompat(modified)) return "the edited file does not match Pi's model configuration schema";
+  if (readBaseUrlState(plan.modifiedText, locateBaseUrlTarget(plan.modifiedText, provider, modelId, plan.placement)) !== plan.after) {
+    return "baseUrl was not written at the target";
+  }
+  const reverted = JSON.parse(JSON.stringify(modified)) as Record<string, unknown>;
+  const providerRecord = asRecord(asRecord(reverted.providers)?.[provider]);
+  if (!providerRecord) return "the provider entry disappeared";
+  if (plan.placement === "provider") {
+    providerRecord.baseUrl = plan.before;
+  } else {
+    const entry = (Array.isArray(providerRecord.models) ? providerRecord.models : []).map(asRecord).find((item) => item?.id === modelId);
+    if (!entry) return "the model entry disappeared";
+    entry.baseUrl = plan.before;
+  }
+  if (JSON.stringify(reverted) !== JSON.stringify(original)) return "unrelated configuration was altered";
+  return null;
+}
+
+/** Validate a file written by the fix transaction (re-read from disk). */
+export function validateWrittenKimiBaseUrlFix(writtenText: string, plan: KimiBaseUrlFixPlan): string | null {
+  if (writtenText !== plan.modifiedText) return "models.json content differs from the previewed edit";
+  try {
+    parseJsonc(writtenText);
+  } catch {
+    return "the written file is not valid JSONC";
+  }
+  return null;
+}

package/src/kimi-code.ts

@@ -0,0 +1,53 @@
+import { isNonEmptyString } from "./common.ts";
+
+// Moonshot's official Kimi Code hosts (China and international). Pi 1.3.0
+// ships kimi-coding as openai-completions at `<host>/coding/v1`; older Pi
+// versions used anthropic-messages at `<host>/coding`.
+const OFFICIAL_KIMI_CODE_HOSTS = new Set(["api.kimi.com", "api.kimi.ai"]);
+
+export type OfficialKimiCodeBaseUrl = {
+  host: string;
+  /** Whether the path is `/coding/v1` (true) or bare `/coding` (false). */
+  hasV1: boolean;
+};
+
+/**
+ * Parse an official Kimi Code base URL: https, one of the official hosts, no
+ * port, credentials, query or fragment, and a path of exactly `/coding` or
+ * `/coding/v1` (trailing slashes ignored). Anything else, including proxies
+ * that mirror the path, returns undefined.
+ */
+export function parseOfficialKimiCodeBaseUrl(baseUrl: unknown): OfficialKimiCodeBaseUrl | undefined {
+  if (!isNonEmptyString(baseUrl)) return undefined;
+  let url: URL;
+  try {
+    url = new URL(baseUrl.trim());
+  } catch {
+    return undefined;
+  }
+  if (url.protocol !== "https:" || url.port !== "" || url.username !== "" || url.password !== "") return undefined;
+  if (url.search !== "" || url.hash !== "" || /[?#]/.test(baseUrl)) return undefined;
+  const host = url.hostname.toLowerCase();
+  if (!OFFICIAL_KIMI_CODE_HOSTS.has(host)) return undefined;
+  const path = url.pathname.replace(/\/+$/, "").toLowerCase();
+  if (path === "/coding") return { host, hasV1: false };
+  if (path === "/coding/v1") return { host, hasV1: true };
+  return undefined;
+}
+
+/** Strip surrounding whitespace and trailing slashes for base URL comparison. */
+export function normalizeBaseUrlForComparison(baseUrl: string): string {
+  return baseUrl.trim().replace(/\/+$/, "");
+}
+
+/** The `/coding/v1` form of a bare official `/coding` base URL, keeping its spelling. */
+export function kimiCodeV1BaseUrl(baseUrl: string): string | undefined {
+  const parsed = parseOfficialKimiCodeBaseUrl(baseUrl);
+  if (!parsed || parsed.hasV1) return undefined;
+  return `${normalizeBaseUrlForComparison(baseUrl)}/v1`;
+}
+
+/** A receipt-recorded base URL change is exactly "bare official /coding" → "+ /v1". */
+export function isKimiCodeV1BaseUrlChange(before: unknown, after: unknown): boolean {
+  return typeof before === "string" && typeof after === "string" && kimiCodeV1BaseUrl(before) === after;
+}

package/src/model-identity.ts

@@ -2,6 +2,7 @@ import { type ModelIdentity, type PiModel, type UnknownRecord, asRecord, isNonEm
 import { type CacheCompat, NESTED_COMPAT_KEYS, resolveEffectiveCompatFromConfig } from "./compat-config.ts";
 import { parseJsonc } from "./jsonc.ts";
 import { getAssistantMessageModelTokenValues, getModelIdNameTokenValues, hasAnyTokenContaining, isKimiCodingAdaptiveModel, modelOrAssistantMessageHas } from "./model-detect.ts";
+import { parseOfficialKimiCodeBaseUrl } from "./kimi-code.ts";
 import { MODELS_JSON_PATH } from "./paths.ts";
 import { readFileSync, statSync } from "node:fs";
 
@@ -363,6 +364,21 @@ export function isKnownThirdPartyOpenAIEndpoint(model: PiModel): boolean {
   return isNonEmptyString(model.baseUrl) && !isOfficialOpenAIBaseUrl(model);
 }
 
+/** The model talks to Moonshot's official Kimi Code endpoint directly. */
+export function isOfficialKimiCodeEndpoint(model: PiModel | undefined): boolean {
+  return parseOfficialKimiCodeBaseUrl(model?.baseUrl) !== undefined;
+}
+
+/**
+ * A non-official OpenAI-compatible endpoint that may sit in front of several
+ * backends (relay, aggregator, gateway), where session-affinity headers help
+ * keep one session on one cache. Official first-party endpoints that Pi
+ * configures itself (Kimi Code) are origins, not proxies.
+ */
+export function isThirdPartyOpenAIProxyEndpoint(model: PiModel): boolean {
+  return isKnownThirdPartyOpenAIEndpoint(model) && !isOfficialKimiCodeEndpoint(model);
+}
+
 export function invalidateModelsConfigCache(): void {
   modelsConfigCache = undefined;
 }

package/src/models-json-fix.ts

@@ -8,6 +8,7 @@ import { findLastExactModelDefinition, resolveEffectiveCompatFromConfig } from "
 import { type FixReceiptCompatChange, type FixReceiptPlacement, type ModelsJsonFixReceiptV1, type PromptCacheLifetimes, RECEIPT_COMPAT_KEYS, type ReceiptScalar, type ReceiptScalarState, isReceiptTimestamp, isValidPromptCacheLifetimes, samePromptCacheLifetimes, isSafeReceiptText, isSha256 } from "./fix-types.ts";
 import { type JsonPropertyEdit, type ModelNodeLocation, deepEqualIgnoringKeys, deriveInnerIndent, findExistingCompatKeysInJsonc, findJsonObjectKey, findMatchingBracket, isJsonWhitespace, lineIndentOf, locateJsonPropertyValueSpan, locateModelOverrideInJsonc, locateProviderCompatInJsonc, parseJsonc, readJsonStringLiteral, skipJsonValue, skipJsonWhitespace, stripJsoncComments } from "./jsonc.ts";
 import { isAdaptiveGenerationModel, isKimiCodingAdaptiveModel } from "./model-detect.ts";
+import { isKimiCodeV1BaseUrlChange } from "./kimi-code.ts";
 import { FIX_RECEIPT_PATH, MODELS_JSON_PATH } from "./paths.ts";
 
 export type ExplicitCompatSource = "modelOverride" | "model" | "provider";
@@ -1528,10 +1529,10 @@ export function createRollbackBackupPath(modelsPath: string = MODELS_JSON_PATH):
 
 export function parseModelsJsonFixReceipt(value: unknown): ModelsJsonFixReceiptV1 | undefined {
   const record = asRecord(value);
-  if (!record || (record.version !== 1 && record.version !== 2) || record.kind !== "pi-cache-optimizer-fix-receipt") return undefined;
+  if (!record || (record.version !== 1 && record.version !== 2 && record.version !== 3) || record.kind !== "pi-cache-optimizer-fix-receipt") return undefined;
   const allowedKeys = new Set([
     "version", "kind", "transactionId", "provider", "modelId", "placement",
-    "targetExistedBefore", "changedKeys", "promptCacheAdded", "beforeHash", "afterHash", "backupFile",
+    "targetExistedBefore", "changedKeys", "promptCacheAdded", "baseUrlChange", "beforeHash", "afterHash", "backupFile",
     "createdAt", "appliedAt", "status", "rolledBackAt",
   ]);
   if (Object.keys(record).some((key) => !allowedKeys.has(key))) return undefined;
@@ -1549,8 +1550,19 @@ export function parseModelsJsonFixReceipt(value: unknown): ModelsJsonFixReceiptV
   const isV2 = record.version === 2;
   if (isV2 !== (record.promptCacheAdded !== undefined)) return undefined;
   if (isV2 && (!isValidPromptCacheLifetimes(record.promptCacheAdded) || record.placement === "provider")) return undefined;
+  // baseUrlChange is the version 3 marker: a single official Kimi Code
+  // `/coding` → `/coding/v1` rewrite at an existing provider or model target.
+  const isV3 = record.version === 3;
+  if (isV3 !== (record.baseUrlChange !== undefined)) return undefined;
+  const rawBaseUrlChange = asRecord(record.baseUrlChange);
+  if (isV3) {
+    if (!rawBaseUrlChange || Object.keys(rawBaseUrlChange).some((key) => key !== "before" && key !== "after")) return undefined;
+    if (!isKimiCodeV1BaseUrlChange(rawBaseUrlChange.before, rawBaseUrlChange.after)) return undefined;
+    if (record.placement === "modelOverride" || record.targetExistedBefore !== true) return undefined;
+  }
   const changedKeys = asRecord(record.changedKeys);
-  if (!changedKeys || (Object.keys(changedKeys).length === 0 && !isV2)) return undefined;
+  if (!changedKeys || (Object.keys(changedKeys).length === 0 && record.version === 1)) return undefined;
+  if (isV3 && Object.keys(changedKeys).length > 0) return undefined;
 
   const parsedChanges: Record<string, FixReceiptCompatChange> = {};
   for (const [key, rawChange] of Object.entries(changedKeys)) {
@@ -1569,8 +1581,11 @@ export function parseModelsJsonFixReceipt(value: unknown): ModelsJsonFixReceiptV
   if (record.status === undefined && record.rolledBackAt !== undefined) return undefined;
 
   const promptCacheAdded = isV2 ? record.promptCacheAdded as PromptCacheLifetimes : undefined;
+  const baseUrlChange = isV3 && rawBaseUrlChange
+    ? { before: rawBaseUrlChange.before as string, after: rawBaseUrlChange.after as string }
+    : undefined;
   return {
-    version: isV2 ? 2 : 1,
+    version: isV3 ? 3 : isV2 ? 2 : 1,
     kind: "pi-cache-optimizer-fix-receipt",
     transactionId: record.transactionId.trim(),
     provider: record.provider.trim(),
@@ -1579,6 +1594,7 @@ export function parseModelsJsonFixReceipt(value: unknown): ModelsJsonFixReceiptV
     targetExistedBefore: record.targetExistedBefore,
     changedKeys: parsedChanges,
     ...(promptCacheAdded ? { promptCacheAdded: { ...(promptCacheAdded.short !== undefined ? { short: promptCacheAdded.short } : {}), ...(promptCacheAdded.long !== undefined ? { long: promptCacheAdded.long } : {}) } } : {}),
+    ...(baseUrlChange ? { baseUrlChange } : {}),
     beforeHash,
     afterHash,
     backupFile: record.backupFile,
@@ -1854,6 +1870,100 @@ export function createPromptCacheFixReceipt(
   });
 }
 
+export type BaseUrlFixPlacement = "provider" | "model";
+
+/**
+ * Locate the object that holds a direct `baseUrl`: the provider object, or
+ * the single custom `models[]` entry with this id. Duplicate provider keys or
+ * duplicate model ids are refused.
+ */
+export function locateBaseUrlTarget(
+  text: string,
+  provider: string,
+  modelId: string,
+  placement: BaseUrlFixPlacement,
+): { objectBrace: number; objectEnd: number } | undefined {
+  if (placement === "provider") {
+    const location = locateProviderCompatInJsonc(text, provider);
+    return location ? { objectBrace: location.providerObjectBrace, objectEnd: location.providerObjectEnd } : undefined;
+  }
+  const location = locateModelInJsonc(text, provider, modelId);
+  if (!location || location.providerKeyCount !== 1 || location.modelObjectBrace < 0) return undefined;
+  if (location.allModelIds.filter((id) => id === modelId).length !== 1) return undefined;
+  return { objectBrace: location.modelObjectBrace, objectEnd: location.modelObjectEnd };
+}
+
+/**
+ * Read the direct `baseUrl` of a target: its string value, `undefined` when
+ * absent, or "invalid" when duplicated, not a string, or unreadable.
+ */
+export function readBaseUrlState(
+  text: string,
+  target: { objectBrace: number; objectEnd: number } | undefined,
+): string | undefined | "invalid" {
+  if (!target) return "invalid";
+  const clean = stripJsoncComments(text);
+  const property = findJsonObjectKey(clean, target.objectBrace, "baseUrl");
+  if (!property || property.keyStart >= target.objectEnd) return undefined;
+  if (property.count !== 1) return "invalid";
+  const valueStart = skipJsonWhitespace(clean, property.valueStart);
+  if (clean[valueStart] !== "\"") return "invalid";
+  const literal = readJsonStringLiteral(clean, valueStart);
+  if (!literal || literal.end > target.objectEnd) return "invalid";
+  return literal.value;
+}
+
+/** Replace the direct `baseUrl` string of a target, or explain why it cannot. */
+export function replaceBaseUrlValue(
+  text: string,
+  target: { objectBrace: number; objectEnd: number },
+  value: string,
+): string | undefined {
+  const property = locateJsonPropertyValueSpan(text, target.objectBrace, target.objectEnd, "baseUrl");
+  if (!property) return undefined;
+  const clean = stripJsoncComments(text);
+  if (clean[property.valueStart] !== "\"") return undefined;
+  return text.slice(0, property.valueStart) + JSON.stringify(value) + text.slice(property.valueEnd);
+}
+
+/**
+ * Receipt for `/cache-optimizer fix kimi-base-url`: a version 3 receipt with
+ * no compat changes and the single baseUrl string the fix rewrote.
+ */
+export function createBaseUrlFixReceipt(
+  originalText: string,
+  modifiedText: string,
+  provider: string,
+  modelId: string,
+  placement: BaseUrlFixPlacement,
+  before: string,
+  after: string,
+  backupPath: string,
+  now: number = Date.now(),
+): ModelsJsonFixReceiptV1 | undefined {
+  const backupFile = basename(backupPath);
+  if (!/^models\.json\.backup-cache-optimizer-/.test(backupFile)) return undefined;
+  if (!isKimiCodeV1BaseUrlChange(before, after)) return undefined;
+  if (readBaseUrlState(originalText, locateBaseUrlTarget(originalText, provider, modelId, placement)) !== before) return undefined;
+  if (readBaseUrlState(modifiedText, locateBaseUrlTarget(modifiedText, provider, modelId, placement)) !== after) return undefined;
+  return parseModelsJsonFixReceipt({
+    version: 3,
+    kind: "pi-cache-optimizer-fix-receipt",
+    transactionId: randomUUID(),
+    provider,
+    modelId,
+    placement,
+    targetExistedBefore: true,
+    changedKeys: {},
+    baseUrlChange: { before, after },
+    beforeHash: hashText(originalText),
+    afterHash: hashText(modifiedText),
+    backupFile,
+    createdAt: now,
+    appliedAt: now,
+  });
+}
+
 export function createModelsJsonFixReceipt(
   originalText: string,
   modifiedText: string,
@@ -1908,6 +2018,19 @@ export function composeModelsJsonReceiptRollback(
     return { error: "the fix created a new target entry and the file changed; refusing to remove user changes automatically" };
   }
 
+  if (receipt.baseUrlChange) {
+    if (receipt.placement === "modelOverride") return { error: "the receipt's baseUrl target is not supported" };
+    const baseUrlTarget = locateBaseUrlTarget(currentText, receipt.provider, receipt.modelId, receipt.placement);
+    const current = readBaseUrlState(currentText, baseUrlTarget);
+    if (current === "invalid" || !baseUrlTarget) return { error: "receipt-owned baseUrl is no longer safely locatable" };
+    if (current !== receipt.baseUrlChange.after) {
+      return { error: "receipt-owned baseUrl was changed after the fix; refusing to overwrite it" };
+    }
+    const modifiedText = replaceBaseUrlValue(currentText, baseUrlTarget, receipt.baseUrlChange.before);
+    if (modifiedText === undefined) return { error: "receipt-owned baseUrl is no longer safely locatable" };
+    return { modifiedText, changed: modifiedText !== currentText };
+  }
+
   const target = locateReceiptCompatTarget(currentText, receipt.provider, receipt.modelId, receipt.placement);
   if (!target?.targetExists) {
     return { error: "the original target entry is missing or no longer safely locatable" };
@@ -1969,6 +2092,12 @@ export function validateModelsJsonRollback(
   // newly created target entry (which intentionally did not exist before).
   if (expectedHash !== undefined) return null;
 
+  if (receipt.baseUrlChange) {
+    if (receipt.placement === "modelOverride") return "rollback result has an unsupported baseUrl target";
+    const state = readBaseUrlState(writtenText, locateBaseUrlTarget(writtenText, receipt.provider, receipt.modelId, receipt.placement));
+    return state === receipt.baseUrlChange.before ? null : "rollback result did not restore baseUrl";
+  }
+
   const target = locateReceiptCompatTarget(writtenText, receipt.provider, receipt.modelId, receipt.placement);
   if (!target?.targetExists) return "rollback result lost the original target entry";
   for (const [key, change] of Object.entries(receipt.changedKeys)) {