pi-cache-optimizer 2.8.25 → 2.8.27

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/index.ts

@@ -13,7 +13,7 @@ import { atomicCreateTextFileNoReplace, atomicReplaceTextFilePreservingMode, ato
 import { getAssistantMessageModelTokenValues, getModelIdNameTokenValues, isAdaptiveGenerationModel, isKimiCodingAdaptiveModel } from "./src/model-detect.ts";
 import { findLastExactModelDefinition, mergeCacheCompat, resolveEffectiveCompatFromConfig } from "./src/compat-config.ts";
 import { analyzeModelsJsonForMissingEntry, applyModelsJsonFixTransaction, chooseFixPlacement, composeFixInsertion, composeMissingEntryInsertion, composeModelOverrideInsertion, composeModelsJsonReceiptRollback, composeProviderAffinityInsertion, createModelsJsonFixReceipt, createRollbackBackupPath, decideFixPlacement, formatCompatKeysForInsertion, hasExplicitLongRetentionOptInFromConfig, hasReceiptReasoningProtocolChange, isActionableModelsJsonFixReceipt, locateModelInJsonc, markModelsJsonFixReceiptRolledBack, parseModelsJsonFixReceipt, prepareModelsJsonRollback, readModelsJsonFixReceipt, readModelsJsonFixReceiptSnapshot, receiptBackupPath, resolveExplicitCompatValue, selfCheckFix, selfCheckMissingEntryInsertion, validateModelsJsonRollback, writeModelsJsonFixReceipt } from "./src/models-json-fix.ts";
-import { type CacheProviderId, type CacheStats, LEGACY_STATE_FILE_PATH, type PersistedRoutedModelRef, type PersistedStatsShardV7, SHARD_FILES_DIR, SHARD_GLOBAL_EPOCH_PATH, SHARD_STATE_DIR, STATE_FILE_PATH, type ShardAggregate, type UsageSnapshot, addUsageToCacheStats, advanceGlobalStatsEpoch, advanceModelStatsEpoch, aggregateStatsShardsV7, cleanupStatsShardsV7, cloneCacheStats, currentLocalDay, emptyAllCacheStats, emptyCacheStats, initialEpoch, loadStatsShardAggregateV7, maybeCleanupStatsShardsV7, modelEpochPath, parseCacheStats, parsePersistedRoutedModelRef, parsePersistedStatsShardV7, readGlobalStatsEpoch, readModelStatsEpoch, readValidStatsShardsV7, removeLegacyStatsFiles, writeStatsShardV7 } from "./src/stats-store.ts";
+import { type CacheProviderId, type CacheStats, LEGACY_STATE_FILE_PATH, type PersistedRoutedModelRef, type PersistedStatsShardV7, SHARD_FILES_DIR, SHARD_GLOBAL_EPOCH_PATH, SHARD_STATE_DIR, STATE_FILE_PATH, type ShardAggregate, type UsageSnapshot, addUsageToCacheStats, advanceGlobalStatsEpoch, advanceModelStatsEpoch, aggregateStatsShardsV7, cleanupStatsShardsV7, cloneCacheStats, mapWithConcurrency, currentLocalDay, emptyAllCacheStats, emptyCacheStats, initialEpoch, loadStatsShardAggregateV7, maybeCleanupStatsShardsV7, modelEpochPath, parseCacheStats, parsePersistedRoutedModelRef, parsePersistedStatsShardV7, readGlobalStatsEpoch, readModelStatsEpoch, readValidStatsShardsV7, removeLegacyStatsFiles, writeStatsShardV7 } from "./src/stats-store.ts";
 import { PI_VIRTUAL_MODEL_API, getCompat, isAnthropicMessagesApi, isKimiCodingEmptySignatureModel, isKnownThirdPartyOpenAIEndpoint, isMistralConversationsApi, isNativeVirtualModel, isOfficialOpenAIBaseUrl, isOpenAICompatibleApi, isOpenAICompatibleProxyApi, isOpenAIFamilyAssistantMessage, isOpenAIFamilyModel, isOpenAIFamilyToken, isPiBuiltInLlamaCppModel, isResponsesPromptRewriteBypassApi, isRoutedFallbackModel, isValidModelsConfigForEffectiveCompat, modelKey, readEffectiveCompatConfig } from "./src/model-identity.ts";
 import { CONFIG_FILE_PATH, VIRTUAL_REWRITE_ENV, FOOTER_MODE_ENV, TOOL_ORDER_ENV, featureEnabled, footerStatsMode, isEnabledEnv, isToolOrderEnabled, parseFooterStatsMode, parsePersistedCacheOptimizerConfig, readPersistedCacheOptimizerConfig, resolveFooterStatsMode, runtimeOptimizerEnabled, setPersistedCacheOptimizerConfig, shouldInjectOpenAIPromptCacheKey, writePersistedCacheOptimizerConfig, writePersistedFeature, writePersistedFooterMode } from "./src/config.ts";
 import { decideZeroPriceWarming, readCacheWarmingMode } from "./src/cache-warming.ts";
@@ -103,7 +103,13 @@ function notifyCacheCompatIfNeeded(
 // Internal helpers exported only so the task verification script
 // (.trellis/tasks/.../verify.ts) can exercise them. They are not part of the
 // extension's public API; pi only invokes the default export below.
+// Most recent background stats restore started by any extension instance in
+// this module. Tests await it after session_start; runtime code uses the
+// per-instance promise instead.
+let latestStatsRestoreForTests: Promise<void> = Promise.resolve();
+
 export const __internals_for_tests = {
+  waitForStatsRestore: (): Promise<void> => latestStatsRestoreForTests,
   getLastSkillCompressionOutcome,
   decidePromptCacheRetention,
   userRequestedLongCacheRetention,
@@ -317,6 +323,7 @@ export const __internals_for_tests = {
   aggregateStatsShardsV7,
   loadStatsShardAggregateV7,
   cleanupStatsShardsV7,
+  mapWithConcurrency,
   removeLegacyStatsFiles,
   readGlobalStatsEpoch,
   readModelStatsEpoch,
@@ -410,6 +417,20 @@ export default function (pi: ExtensionAPI) {
   let persistTimer: ReturnType<typeof setTimeout> | null = null;
   let shardRefreshTimer: ReturnType<typeof setTimeout> | null = null;
   let shardWatcher: ReturnType<typeof watch> | undefined;
+  // Historical stats are restored in the background so a large shard
+  // directory never holds up Pi's session_start (issue #28). Handlers that
+  // read or persist aggregated stats await this first.
+  let statsRestorePromise: Promise<void> = Promise.resolve();
+  let statsRestoreGeneration = 0;
+  async function waitForStatsRestore(): Promise<void> {
+    // A session_start may chain a newer restore while we wait; keep waiting
+    // until the chain is stable so callers never act on a half-restored view.
+    let current: Promise<void>;
+    do {
+      current = statsRestorePromise;
+      await current;
+    } while (current !== statsRestorePromise);
+  }
   const enqueuePersist = createSerializedAsyncRunner();
   let instanceId = randomUUID();
   const instanceStartedAt = Date.now();
@@ -664,7 +685,8 @@ export default function (pi: ExtensionAPI) {
     if (shardRefreshTimer !== null) clearTimeout(shardRefreshTimer);
     shardRefreshTimer = setTimeout(() => {
       shardRefreshTimer = null;
-      void refreshShardAggregate()
+      void waitForStatsRestore()
+        .then(() => refreshShardAggregate())
         .then(() => publishStatus(ctx as ExtensionContext, model ?? ctx?.model))
         .catch(() => undefined);
     }, SHARD_REFRESH_DEBOUNCE_MS);
@@ -771,7 +793,12 @@ export default function (pi: ExtensionAPI) {
     if (persistTimer !== null) clearTimeout(persistTimer);
     persistTimer = setTimeout(() => {
       persistTimer = null;
-      void persistCacheStats(ctx).then(() => refreshShardAggregate()).catch(() => undefined);
+      // A persist scheduled while a background restore runs (e.g. a routed
+      // model change without usage) must not race the restore's own write.
+      void waitForStatsRestore()
+        .then(() => persistCacheStats(ctx))
+        .then(() => refreshShardAggregate())
+        .catch(() => undefined);
     }, PERSIST_DEBOUNCE_MS);
     persistTimer.unref?.();
   }
@@ -818,7 +845,12 @@ export default function (pi: ExtensionAPI) {
     finally { rolloverPromise = undefined; }
   }
 
-  async function restoreCacheStats(reason: string, ctx: ExtensionContext): Promise<void> {
+  /**
+   * Synchronous part of a session restore: reset in-memory state immediately
+   * at session_start, so usage recorded before the background disk restore
+   * finishes is never wiped by a reset that runs later.
+   */
+  function resetStatsForSessionStart(reason: string, ctx: ExtensionContext): void {
     syncSessionHash(ctx);
     lastStatusText = undefined;
     cacheStatsProcessByModel = {};
@@ -826,19 +858,48 @@ export default function (pi: ExtensionAPI) {
     modelEpochByKey.clear();
     modelApiByKey.clear();
     modelNameByKey.clear();
-    currentGlobalEpoch = await readGlobalStatsEpoch();
     if (reason === "reload") {
       clearRecentSamples();
     }
+  }
+
+  async function restoreCacheStats(ctx: ExtensionContext): Promise<void> {
+    // Session identity was synced by resetStatsForSessionStart. Usage may
+    // already have been recorded (message_end does not wait to record), and
+    // message_end syncs the epoch before recording. If the disk epoch differs
+    // now, a reset happened after that usage: adopt it and drop the stale
+    // process bucket instead of re-labelling old counters with the new epoch.
+    const latestGlobalEpoch = await readGlobalStatsEpoch();
+    if (latestGlobalEpoch !== currentGlobalEpoch) {
+      currentGlobalEpoch = latestGlobalEpoch;
+      cacheStatsProcessByModel = {};
+      modelEpochByKey.clear();
+      modelApiByKey.clear();
+      modelNameByKey.clear();
+    }
     await removeLegacyStatsFiles();
     await mkdir(SHARD_FILES_DIR, { recursive: true });
+    await rollOverStatsIfNeeded(ctx);
+    // Run due retention maintenance before the single startup scan, so the
+    // aggregate never retains counters from files maintenance just removed and
+    // no second directory pass is needed. Cleanup also warms the parsed-shard
+    // cache, so the scan below only re-stats files.
+    try {
+      await maybeCleanupStatsShardsV7();
+    } catch (error) {
+      console.warn(`${LOG_PREFIX}: stats shard maintenance failed`, error);
+    }
+    // One scan adopts other processes' epochs and restores this session's
+    // routed-model metadata before this instance publishes its own shard.
+    // In-memory process counters were cleared above, so no pre-persist
+    // re-scan is needed; this instance's own shard is always replaced by its
+    // in-memory copy during aggregation, so no post-persist scan either.
     await refreshShardAggregate();
-    await flushPersistCacheStats(ctx);
-    await maybeCleanupStatsShardsV7();
-    // Maintenance may remove expired shard files after the initial refresh.
-    // Re-scan before publishing so startup/footer command state cannot retain
-    // counters from files that no longer exist.
-    await refreshShardAggregate();
+    if (persistTimer !== null) {
+      clearTimeout(persistTimer);
+      persistTimer = null;
+    }
+    await persistCacheStats(ctx);
   }
 
   async function publishStatus(ctx: ExtensionContext, model: PiModel | undefined = ctx.model): Promise<void> {
@@ -968,7 +1029,26 @@ export default function (pi: ExtensionAPI) {
 
   pi.on("session_start", async (event, ctx) => {
     if (runtimeOptimizerEnabled) requestLongCacheRetention();
-    await restoreCacheStats(event.reason, ctx);
+    // Do not block Pi's startup on historical stats (issue #28). The
+    // restore runs in the background (chained after any earlier restore so
+    // two never interleave) and the footer is published when it finishes.
+    // A newer session_start supersedes an older restore, which then must not
+    // publish a stale footer. Handlers that read or persist stats await
+    // waitForStatsRestore() first.
+    const generation = ++statsRestoreGeneration;
+    resetStatsForSessionStart(event.reason, ctx);
+    const previousRestore = statsRestorePromise;
+    statsRestorePromise = previousRestore
+      // A restore superseded before it started is skipped entirely: the newer
+      // one redoes all of its work, and its ctx may already be stale.
+      .then(() => (generation === statsRestoreGeneration ? restoreCacheStats(ctx) : undefined))
+      .then(async () => {
+        if (generation === statsRestoreGeneration) await publishStatus(ctx);
+      })
+      .catch((error) => {
+        console.warn(`${LOG_PREFIX}: failed to restore cache stats`, error);
+      });
+    latestStatsRestoreForTests = statsRestorePromise;
     if (ctx.mode === "tui" && !shardWatcher) {
       try {
         shardWatcher = watch(SHARD_FILES_DIR, () => scheduleShardRefresh(ctx));
@@ -977,13 +1057,13 @@ export default function (pi: ExtensionAPI) {
         // Lifecycle and explicit command refreshes remain authoritative.
       }
     }
-    await publishStatus(ctx);
   });
 
   pi.on("tool_execution_end", async (event, ctx) => {
     // Pi 0.99+ codemode scripts run nested tool calls in parallel; the calling
     // tool's own end event follows them, so one refresh covers the batch.
     if (isNonEmptyString((event as { parentToolCallId?: unknown } | undefined)?.parentToolCallId)) return;
+    await waitForStatsRestore();
     await refreshShardAggregate();
     await publishStatus(ctx);
   });
@@ -1003,12 +1083,14 @@ export default function (pi: ExtensionAPI) {
     // a record consumed out of order) so they cannot be correlated with the
     // next run's messages.
     providerRequestStates.length = 0;
+    await waitForStatsRestore();
     await refreshShardAggregate();
     await publishStatus(ctx);
   });
 
   pi.on("session_shutdown", async (_event, ctx) => {
     try {
+      await waitForStatsRestore();
       await flushPersistCacheStats(ctx, "closed");
     } finally {
       if (shardRefreshTimer !== null) clearTimeout(shardRefreshTimer);
@@ -1025,6 +1107,7 @@ export default function (pi: ExtensionAPI) {
 
   pi.on("model_select", async (event, ctx) => {
     if (runtimeOptimizerEnabled) notifyCacheCompatIfNeeded(resolveRouteModel(event.model, ctx) ?? event.model, ctx, warnedModels);
+    await waitForStatsRestore();
     await refreshShardAggregate();
     await publishStatus(ctx, event.model);
   });
@@ -1568,6 +1651,7 @@ export default function (pi: ExtensionAPI) {
       addUsageToCacheStats(getStatsForModel(undefined, adapter), usage);
     }
 
+    await waitForStatsRestore();
     schedulePersistCacheStats(ctx);
     await refreshShardAggregate();
     // A late response from an older selection must not replace the active
@@ -1627,6 +1711,11 @@ export default function (pi: ExtensionAPI) {
   pi.registerCommand("cache-optimizer", {
     description: "Configure and diagnose Pi cache behavior",
     getArgumentCompletions: getCacheOptimizerArgumentCompletions,
-    handler: handleCacheOptimizerCommand,
+    handler: async (args: string, cmdCtx: Parameters<typeof handleCacheOptimizerCommand>[1]) => {
+      // Commands read and reset aggregated stats; let a background restore
+      // finish first so they never act on a half-restored view.
+      await waitForStatsRestore();
+      return handleCacheOptimizerCommand(args, cmdCtx);
+    },
   });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-cache-optimizer",
-  "version": "2.8.25",
+  "version": "2.8.27",
   "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) {