agentus 0.15.3 → 0.15.5

package/README.md

@@ -57,7 +57,7 @@ background process comes back as a turn of its own), an **ACP session that write
 cockpit-side failure is diagnosable afterwards), and a **DeepSeek web backend** (search +
 extract on the model key) — come from the fork's integration build instead. That is a five-line install:
 [§ Which Hermes to run](docs/installation.md#which-hermes-to-run) — currently the tag
-`agentus/v0.22.0/merge-20261026-1237`, on Hermes `v0.22.0`.
+`agentus/v0.22.0/merge-20261028-1949`, on Hermes `v0.22.0`.
 
 The first slot you start will use the Hermes home **your own agent already uses**
 (`~/.hermes`) unless the backend row names another one — see "HERMES_HOME" below.

package/README.zh-CN.md

@@ -51,7 +51,7 @@ web bundle、配套 APK —— 然后直接退出，不启动任何东西）。
 以及 **DeepSeek 的 web 后端**（搜索 + 正文抓取，共用模型 key）—— 来自 fork 的集成构建（tag）。
 装法就五行：
 [§ 该跑哪份 Hermes](docs/installation.zh-CN.md#该跑哪份-hermes) —— 当前是 tag
-`agentus/v0.22.0/merge-20261026-1237`，基座 Hermes `v0.22.0`。
+`agentus/v0.22.0/merge-20261028-1949`，基座 Hermes `v0.22.0`。
 
 你启动的第一个 slot 会使用**你自己的 agent 已经在用的**那个 Hermes home（`~/.hermes`），除非后端那一行
 指定了另一个 —— 见下面的「HERMES_HOME」。

package/docs/installation.md

@@ -60,7 +60,7 @@ ref and gets rebuilt, while a tag never moves — so pin the tag. The `agentus/`
 ours apart from upstream's own tags (`v0.22.0`, `v0.22.0+canary.*`), and the timestamp in the
 last segment sorts, so "newest" is a `sort -V`.
 
-**Current integration build: `agentus/v0.22.0/merge-20261026-1237`** — the newest tag on the fork,
+**Current integration build: `agentus/v0.22.0/merge-20261028-1949`** — the newest tag on the fork,
 built on Hermes `v0.22.0`. This line is for orientation only, not the source of truth: the
 `TAG=$(…)` step below resolves the newest one on every run, so read it there if this sentence
 ever looks stale.

package/docs/installation.zh-CN.md

@@ -52,7 +52,7 @@ agentus/<hermes 内部版本>/merge-<YYYYMMDD-HHMM>
 tag。`agentus/` 这个前缀也把它和上游自己的 tag（`v0.22.0`、`v0.22.0+canary.*`）分开；最后一段是时间戳，
 可排序，所以「最新」就是一次 `sort -V`。
 
-**当前集成构建：`agentus/v0.22.0/merge-20261026-1237`** —— fork 上最新的那个 tag，基座 Hermes
+**当前集成构建：`agentus/v0.22.0/merge-20261028-1949`** —— fork 上最新的那个 tag，基座 Hermes
 `v0.22.0`。这行只为一眼看个大概，不是权威：下面的 `TAG=$(…)` 每次都会自己解析出最新，觉得这行过期就
 以它为准。
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "agentus",
-  "version": "0.15.3",
-  "description": "Multi-session web cockpit for ACP-speaking coding agents (Qoder CLI / Hermes). UI has no intelligence \u2014 the agent lives in spawned CLI subprocesses.",
+  "version": "0.15.5",
+  "description": "Multi-session web cockpit for ACP-speaking coding agents (Qoder CLI / Hermes). UI has no intelligence — the agent lives in spawned CLI subprocesses.",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",

package/packages/server/mock/agent.mjs

@@ -949,17 +949,23 @@ const agent = () => ({
       used: s.used,
       size: picked > 0 ? picked : Number(process.env.MOCK_USAGE_SIZE || 200_000),
     });
-    // The prompt response's `usage`, shaped like the hermes adapter's (issue #70). ACP's semantics
-    // are "Total … across all turns", so the counters ACCUMULATE on the session state — a cockpit
-    // that forgot to diff would show the whole conversation on every turn, and a two-turn QA sweep
-    // is what proves it does not. `cachedWriteTokens` is filled too, because the fork's adapter
-    // still omits it and the cockpit must not depend on that omission.
+    // The prompt response's `usage`, shaped like the hermes adapter's (issue #70, #71). ACP's
+    // semantics are "Total … across all turns", so the counters ACCUMULATE on the session state —
+    // a cockpit that forgot to diff would show the whole conversation on every turn, and a
+    // two-turn QA sweep is what proves it does not.
+    //
+    // Issue #71: `inputTokens` is the FULL prompt — hermes fills it from `prompt_tokens`, which
+    // its own accounting defines as fresh input + cache read + cache write. The mock therefore
+    // adds the cache buckets INTO the input counter, exactly as the real adapter does: a mock that
+    // kept them separate would let the old 「input + read + write」 denominator stay green.
+    // `cachedWriteTokens` is filled too, because the fork's adapter still omits it and the cockpit
+    // must not depend on that omission.
     const outChars = words.join(" ").length + MOCK_MARKDOWN.length;
     s.tokens = s.tokens || {
       totalTokens: 0, inputTokens: 0, outputTokens: 0, thoughtTokens: 0,
       cachedReadTokens: 0, cachedWriteTokens: 0,
     };
-    s.tokens.inputTokens += text.length + 200;
+    s.tokens.inputTokens += text.length + 200 + 4096 + 128;
     s.tokens.cachedReadTokens += 4096;
     s.tokens.cachedWriteTokens += 128;
     s.tokens.outputTokens += Math.ceil(outChars / 4);

package/packages/server/src/acp/session-manager.ts

@@ -1404,7 +1404,7 @@ export class SessionManager {
       });
       if (!r.ok) console.log(`[agentus] model default not written (${info.backend}): ${r.reason}`);
       else if (r.changed) {
-        console.log(`[agentus] model default → ${modelId}${r.provider ? ` (provider ${r.provider})` : ""} for ${info.backend}`);
+        console.log(`[agentus] model default → ${r.model ?? modelId}${r.provider ? ` (provider ${r.provider})` : ""} for ${info.backend} (picked ${modelId})`);
       }
     } catch (e) {
       console.log(`[agentus] model default write-back failed: ${errMessage(e)}`);
@@ -3105,8 +3105,30 @@ export class SessionManager {
     if (known.length && !known.some((m) => m.modelId === modelId)) {
       throw new Error(`unknown model: ${modelId}`);
     }
-    await conn.request("session/set_model", { sessionId: s.info.acpSessionId, modelId });
-    if (s.info.models) s.info.models = { ...s.info.models, currentModelId: modelId };
+    const reply = await conn.request("session/set_model", { sessionId: s.info.acpSessionId, modelId });
+    // The agent answers with its model state; a few of them (hermes does) re-render the list and mark
+    // the new current there. Ignoring it leaves the slot and the cached handshake on the list from
+    // *before* the switch, which the next start dialog then reads (#72 review). Ids we already know
+    // keep their names/descriptions — the richer shape only exists on the live session.
+    const replied = (reply ?? {}) as {
+      models?: { currentModelId?: string; availableModels?: { modelId?: string }[] } | null;
+    };
+    const returnedIds = (replied.models?.availableModels ?? [])
+      .map((m) => String(m.modelId ?? "")).filter(Boolean);
+    if (s.info.models) {
+      const known = s.info.models.availableModels ?? [];
+      const merged = [...known];
+      for (const id of returnedIds) {
+        if (!merged.some((m) => m.modelId === id)) merged.push({ modelId: id, name: id, description: null });
+      }
+      s.info.models = { ...s.info.models, currentModelId: replied.models?.currentModelId ?? modelId, availableModels: merged };
+    }
+    // #72：缓存握手是"上一次真启动"的快照，新建会话对话框只读它 —— 换了模型却不改它，对话框会一直
+    // 显示（并且把）切换前的那个 id 当中文默认值。活会话手里有完整清单，顺手把两份都刷新。
+    this.#store.recordHandshakeModels(s.info.backend, {
+      currentModelId: modelId,
+      available: (s.info.models?.availableModels ?? []).map((m) => m.modelId).filter(Boolean),
+    });
     if (s.info.pendingModelId) s.info.pendingModelId = null;
     this.#store.setPendingModel(id, null);
     // #62-1: 只有 agent **接受**过的切换才计数 —— 被拒的条目永不加分，于是"广告了但实际不可用"
@@ -3574,27 +3596,44 @@ export function turnUsageOf(
     input: input ?? 0,
     output: output ?? 0,
     thought: thought ?? 0,
-    cacheRead: cacheRead ?? 0,
-    cacheWrite: cacheWrite ?? 0,
+    // issue #71: never `?? 0` here — the baseline is also what a persisted session reloads, and a
+    // washed-in 0 is indistinguishable from a measured zero on the next diff.
+    cacheRead,
+    cacheWrite,
   };
   const delta = (now: number, before: number | undefined): number =>
     (before === undefined ? now : now >= before ? now - before : now);
+  // Issue #71: a bucket the agent never reports stays NULL through the bill. 「写 0」 reads as
+  // "this turn's cache writes were measured at zero", and cache writes are the billed kind
+  // (Anthropic 1.25×). Omission is the honest shape; see tokens.ts. A null BASELINE means the
+  // first reported value is the turn's own — undefined and null never had a prior count.
+  const deltaOpt = (now: number | null, before: number | null | undefined): number | null =>
+    (now === null ? null : delta(now, before ?? undefined));
+  // Computed up front: the hit rate below divides by THIS turn's prompt delta, not the raw one.
+  const billInput = delta(cur.input, base?.input);
+  const billCacheRead = deltaOpt(cur.cacheRead, base?.cacheRead);
   const bill: TurnUsage = {
     total: delta(cur.total, base?.total),
-    input: delta(cur.input, base?.input),
+    input: billInput,
     output: delta(cur.output, base?.output),
     thought: delta(cur.thought, base?.thought),
-    cacheRead: delta(cur.cacheRead, base?.cacheRead),
-    cacheWrite: delta(cur.cacheWrite, base?.cacheWrite),
+    cacheRead: billCacheRead,
+    cacheWrite: deltaOpt(cur.cacheWrite, base?.cacheWrite),
     durationMs,
-    // Webui's denominator: the FULL prompt = input + cache read + cache write. Only when the agent
-    // reports a cache bucket at all — otherwise the page says 「未上报」, not a 0% hit rate.
+    // Issue #71 — the denominator is this turn's prompt total, i.e. the billed `input` DELTA.
+    // ACP's Usage.inputTokens is the FULL prompt (hermes' adapter fills it with `prompt_tokens`,
+    // which by definition = fresh input + cache read + cache write; see agent/usage_pricing.py in
+    // the fork), so the cache buckets are a SUBSET of input, not peers beside it. Adding them
+    // back counted every cached token twice and pinned the reading at cacheRead/(input+cacheRead)
+    // ≈ 50% for any cache-heavy session — the exact defect #71 measured (real hits 91–100%, page
+    // 50%). webui keeps one invariant across both of its sources: the denominator is a number
+    // that already IS the full prompt (api/models.py passes input_tokens alone); its additive
+    // form exists only for a rollup that stored uncached input separately. We read the first
+    // source, so no addition. `min(100, …)` stays as a clamp against a skewed diff, never as the
+    // thing that makes the ratio believable: with correct semantics normal data cannot exceed 100.
     cacheHitPercent: cacheRead === null && cacheWrite === null
       ? null
-      : (() => {
-        const prompt = (input ?? 0) + (cacheRead ?? 0) + (cacheWrite ?? 0);
-        return prompt > 0 ? Math.min(100, Math.round(((cacheRead ?? 0) / prompt) * 100)) : null;
-      })(),
+      : (billInput > 0 ? Math.min(100, Math.round(((billCacheRead ?? 0) / billInput) * 100)) : null),
   };
   // Average speed: this turn's OWN output over wall time (tool calls included, so a long tool
   // turn honestly reads slow rather than being dressed up as model speed).

package/packages/server/src/model-default.ts

@@ -8,7 +8,14 @@
 //   · 只在 server 的 setModel **成功之后**、且是操作者动作时调用（重放不算，见 session-manager）。
 //   · 写完必须能读回来：写盘前用真 YAML 解析器验一遍 `model.default` 是不是那个值，验不过就**拒写**。
 //     这是别人的全局配置文件，写坏了下次 spawn 直接起不来 —— 宁可不动，也不能"改成功但改坏"。
-//   · 原子写（临时文件 + rename）并保持原权限；只动 `model.default` / `model.provider` 两行。
+//   · 原子写（临时文件 + rename）并保持原权限。
+//   · 写进去的必须是 hermes 的**配置形状**，不是 ACP 的线格式：`default: <裸模型名>` +
+//     `provider: custom:<条目名>`。把选择器的三段 id（`custom:<条目>:<模型>`）直接塞进
+//     `model.default`，新建会话会把它整体当模型名发出去（`404 model_not_found`），或者被按第一个
+//     冒号切成 `provider=custom` + 剩下的整串 —— 静默跑到别的端点上（#72）。
+//   · 端点跟着条目走：命名条目自己声明 api_url/api_mode，块里残留的是**上一个** provider 的口子
+//     （`base_url` 指向旧云端点、`api_mode: codex_responses`），换 provider 时必须清掉，
+//     否则它会盖掉条目的声明。
 import { chmodSync, copyFileSync, existsSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
 import path from "node:path";
 import { parse as parseYaml } from "yaml";
@@ -18,6 +25,8 @@ export interface WriteBackResult {
   changed: boolean;
   /** 写进去的 provider；null = 没写（推不出或不安全） */
   provider: string | null;
+  /** 写进 `model.default` 的裸模型名（从 ACP choice id 拆出来的那个） */
+  model?: string;
   reason?: string;
 }
 
@@ -109,6 +118,166 @@ function setKey(lines: string[], key: string, value: string, indent: string): st
   return copy;
 }
 
+
+/** 命名端点（`providers:` 的键 / `custom_providers:` 的 name）在配置里声明的端点与协议。
+ *
+ *  写回时这两样是**端点归属**的唯一来源：provider 认条目，端口跟着条目走。块级的
+ *  `base_url` / `api_mode` 是上一个 provider 留下的，换 provider 时要清掉（#72）。 */
+export interface EndpointInfo {
+  /** 持久身份：`custom:<config 键>`（legacy 条目用规范化后的 name） */
+  id: string;
+  apiUrl: string | null;
+  apiMode: string | null;
+}
+
+/** hermes 的 `custom_provider_slug`：小写、空格换连字符、补 `custom:` 前缀。 */
+const customSlug = (display: string): string => {
+  const normalized = display.trim().toLowerCase().replace(/ /g, "-");
+  return normalized.startsWith("custom:") ? normalized : `custom:${normalized}`;
+};
+
+const bareName = (id: string): string => id.trim().toLowerCase().replace(/^custom:/, "");
+
+/** hermes 的 `is_provider_enabled`：`enabled:` 的假值一律视为停用。 */
+const isDisabled = (entry: Record<string, unknown>): boolean => {
+  const raw = entry.enabled;
+  if (raw === undefined || raw === null) return false;
+  if (typeof raw === "boolean") return !raw;
+  return ["false", "no", "off", "0", "disabled"].includes(String(raw).trim().toLowerCase());
+};
+
+/** 配置里的命名端点，**键是持久身份** `custom:<条目>`；显示名另作别名指向同一条目。
+ *
+ *  为什么别名也进这张表：choice id 是身份的权威来源（`custom:<键>:<模型>`），但旧形状
+ *  （`custom:<模型>`）与裸模型名只剩描述里的**显示名**可用。用显示名当 `model.provider` 写下去，
+ *  一旦操作者改了 `name:`，那份配置就再也解析不回来 —— 所以别名必须翻译成 `custom:<键>`，
+ *  而不是跟着名字走。
+ *
+ *  端点字段的顺序照 hermes 的 `_pick_provider_base_url`：`base_url` → `url` → `api`。
+ *  `api_url` 是 inventory 行（运行时）的字段，不是 config 键；它只作为最后的容错。 */
+export function namedEndpoints(doc: unknown): Map<string, EndpointInfo> {
+  const out = new Map<string, EndpointInfo>();
+  const endpointOf = (entry: Record<string, unknown>): string | null => {
+    for (const key of ["base_url", "url", "api", "api_url"]) {
+      const value = entry[key];
+      if (typeof value === "string" && value.trim()) return value.trim();
+    }
+    return null;
+  };
+  const add = (id: string, entry: Record<string, unknown>): void => {
+    const info: EndpointInfo = { id, apiUrl: endpointOf(entry), apiMode: typeof entry.api_mode === "string" ? entry.api_mode : null };
+    out.set(id, info);
+    const display = typeof entry.name === "string" ? entry.name.trim() : "";
+    if (display) out.set(customSlug(display), info);
+  };
+  const d = (doc ?? {}) as { providers?: unknown; custom_providers?: unknown };
+  const providers = d.providers;
+  if (providers && typeof providers === "object" && !Array.isArray(providers)) {
+    for (const [key, entry] of Object.entries(providers as Record<string, unknown>)) {
+      if (!entry || typeof entry !== "object" || Array.isArray(entry)) continue;
+      const raw = entry as Record<string, unknown>;
+      if (isDisabled(raw)) continue; // hermes 不认停用条目：写进 provider 等于让下一次 spawn 起不来
+      // 键是身份（显示名可以改），和 hermes 的 custom_provider_slug(display, key) 同一个取向。
+      add(customSlug(key), raw);
+    }
+  }
+  const legacy = d.custom_providers;
+  if (Array.isArray(legacy)) {
+    for (const entry of legacy) {
+      if (!entry || typeof entry !== "object" || Array.isArray(entry)) continue;
+      const raw = entry as Record<string, unknown>;
+      if (isDisabled(raw)) continue;
+      const name = typeof raw.name === "string" ? raw.name.trim() : "";
+      if (!name) continue;
+      add(customSlug(name), raw);
+    }
+  }
+  return out;
+}
+
+export interface ChoiceSplit {
+  /** hermes `model.default` 该写的值：裸模型名 */
+  model: string;
+  /** hermes `model.provider` 该写的值；null = 推不出来，保持原样 */
+  provider: string | null;
+  /** true = 这个 id 描述了一个本配置里不存在的条目：**不许写**，也算不出可信的模型名 */
+  unresolved?: boolean;
+}
+
+/** 把选择器的 choice id 拆回 `(裸模型名, 持久 provider 身份)`。
+ *
+ *  规则就是 hermes 自己的那条：provider 只在左半段是**已知 provider/条目**时才算分隔符，
+ *  否则整串都是模型名（`anthropic/claude-3.5-sonnet:beta` 不能被切）。条目名到身份的映射由
+ *  `namedEndpoints` 提供，所以这里不需要再猜"哪些名字是 provider"。 */
+export function splitChoiceId(
+  modelId: string,
+  providerHint: string | null,
+  endpoints: Map<string, EndpointInfo>,
+): ChoiceSplit {
+  const raw = (modelId ?? "").trim();
+  if (!raw) return { model: raw, provider: null };
+  const lowered = raw.toLowerCase();
+
+  // 描述里的名字是**显示名**：先翻成持久身份（改名也不会断），翻不到才当 canonical slug 用。
+  const hintSlug = providerHint ? (providerHint.includes(":") ? providerHint.trim().toLowerCase() : customSlug(providerHint)) : null;
+  const hintInfo = hintSlug ? endpoints.get(hintSlug) : undefined;
+  const hintId = hintInfo?.id ?? null;
+  const hintBares = new Set<string>();
+  if (hintSlug) hintBares.add(bareName(hintSlug));
+  if (hintId) hintBares.add(bareName(hintId));
+  hintBares.delete("custom");
+  hintBares.delete("");
+
+  // 1) 描述里声明的条目自己认领前缀：`custom:<条目>:<模型>` / `<条目>:<模型>`。
+  for (const bare of hintBares) {
+    const customPrefix = `custom:${bare}:`;
+    if (lowered.startsWith(customPrefix)) {
+      // 只有这个条目真的在配置里，才允许把它的名字当成身份写下去。
+      const entry = endpoints.get(`custom:${bare}`);
+      return { model: raw.slice(customPrefix.length).trim(), provider: entry?.id ?? hintId ?? null,
+        unresolved: entry ? undefined : true };
+    }
+    if (!lowered.startsWith("custom:") && lowered.startsWith(`${bare}:`)) {
+      return { model: raw.slice(bare.length + 1).trim(), provider: hintId ?? bare };
+    }
+  }
+
+  // 2) `custom:` 开头的三段 id：第二段是已配置条目才切。
+  if (lowered.startsWith("custom:")) {
+    const rest = raw.slice("custom:".length);
+    const cut = rest.indexOf(":");
+    if (cut > 0) {
+      const named = endpoints.get(customSlug(rest.slice(0, cut)));
+      if (named) return { model: rest.slice(cut + 1).trim(), provider: named.id };
+      // 这个条目本配置里没有（被改名/删掉，而对话框拿的是旧快照）。把整串写进 model.default
+      // 正是 #72 的病灶：模型名变成 `条目:模型`，或者被按第一个冒号切成 provider=custom。
+      return { model: raw, provider: hintId, unresolved: true };
+    }
+    // `custom:<模型>`（旧形状）：模型名是确定的那半，provider 只能靠描述推。
+    return { model: rest.trim(), provider: hintId };
+  }
+
+  // 3) `<provider>:<模型>`：左半段是已配置条目（含显示名）、或就是描述里声明的那个名字。
+  const colon = raw.indexOf(":");
+  if (colon > 0) {
+    const left = raw.slice(0, colon).trim().toLowerCase();
+    const named = endpoints.get(customSlug(left));
+    if (named) return { model: raw.slice(colon + 1).trim(), provider: named.id };
+    if (hintBares.has(left)) return { model: raw.slice(colon + 1).trim(), provider: hintId ?? left };
+  }
+
+  // 4) 裸模型名 + 描述里的条目：描述只用来定 provider，绝不改模型名。
+  return { model: raw, provider: hintId ?? (hintSlug && hintBares.size ? [...hintBares][0] : null) };
+}
+
+function deleteKey(lines: string[], key: string): string[] {
+  const at = findInModelBlock(lines, key);
+  if (at < 0) return lines;
+  const copy = [...lines];
+  copy.splice(at, 1);
+  return copy;
+}
+
 /** 把 modelId（以及可安全推断时的 provider）写进 agent 的配置文件。 */
 export function writeModelDefault(
   backend: string,
@@ -139,28 +308,69 @@ export function writeModelDefault(
     return { ok: false, changed: false, provider: null, reason: `model: is not a plain block (${header.trim().slice(0, 40)})` };
   }
 
-  const provider = options.provider ? String(options.provider).trim() : null;
+  // 配置里有哪些命名端点，决定了 choice id 怎么拆、以及块内残留的端点要不要清。
+  let before: unknown = null;
+  try { before = parseYaml(text); } catch { before = null; }
+  const endpoints = namedEndpoints(before);
+  const split = splitChoiceId(modelId, options.provider ?? null, endpoints);
+  const provider = split.provider;
+  const desiredModel = split.model;
+  if (split.unresolved) {
+    // 对话框拿的是旧快照时会出现：条目已被改名/删除，pick 却还带着 `custom:<旧名>:<模型>`。
+    // 把它当 model.default 写下去，等于把 #72 的病灶重新种进配置（模型名带条目前缀、或按第一个冒号
+    // 切成 provider=custom），所以整次拒写，让调用方看到原因。
+    return {
+      ok: false, changed: false, provider, model: desiredModel,
+      reason: `refusing to write: ${modelId} names an endpoint this config does not declare`,
+    };
+  }
+  const previousProvider = (before as { model?: { provider?: unknown } } | null)?.model?.provider;
+  const previous = typeof previousProvider === "string" ? previousProvider.trim() : null;
+  const providerChanged = provider != null && provider !== previous;
+  const entry = provider ? endpoints.get(provider) : undefined;
+  // 块级的 base_url/api_mode 是**上一个 provider 的口子**，两种情况下都必然过期或多余：
+  //   · 换了 provider —— 它描述的是被换掉的那一个；
+  //   · 新 provider 是命名条目 —— 端点归条目所有（条目改了端口/协议，块里那份就成了矛盾状态）。
+  // 只按「换 provider 且端点归某个条目」判断，会漏掉 `custom → openrouter`（新 provider 不声明端点），
+  // 于是写出「provider 是云厂商、base_url 还指着本地边车」的块，那正是 #72 B 段的错路由。
+  const dropEndpointKeys = providerChanged || Boolean(entry);
+
   const indent = blockIndent(lines);
   let work = lines;
   if (provider) work = setKey(work, "provider", provider, indent);
-  work = setKey(work, "default", modelId, indent);
+  work = setKey(work, "default", desiredModel, indent);
+  if (dropEndpointKeys) {
+    work = deleteKey(work, "base_url");
+    work = deleteKey(work, "api_mode");
+  }
 
   const next = work.join("\n");
-  if (next === text) return { ok: true, changed: false, provider };
+  if (next === text) return { ok: true, changed: false, provider, model: desiredModel };
 
-  // 写盘前的最后一道闸：真解析一遍，两个值都得读回来。任何一个不成立就一个字都不写。
+  // 写盘前的最后一道闸：真解析一遍。不只看"两行读得回"，要看**这个块自洽**——
+  // provider 指向的条目和块里的端点必须是同一个端点，否则整次拒写（旧闸门会稳定放过矛盾状态）。
   let doc: unknown;
   try {
     doc = parseYaml(next);
   } catch (e) {
-    return { ok: false, changed: false, provider, reason: `refusing to write: result would not parse (${(e as Error).message.split("\n")[0]})` };
+    return { ok: false, changed: false, provider, model: desiredModel, reason: `refusing to write: result would not parse (${(e as Error).message.split("\n")[0]})` };
   }
-  const model = (doc as { model?: { default?: unknown; provider?: unknown } } | null)?.model;
-  if (!model || model.default !== modelId) {
-    return { ok: false, changed: false, provider, reason: "refusing to write: model.default would not read back" };
+  const model = (doc as { model?: { default?: unknown; provider?: unknown; base_url?: unknown; api_mode?: unknown } } | null)?.model;
+  if (!model || model.default !== desiredModel) {
+    return { ok: false, changed: false, provider, model: desiredModel, reason: "refusing to write: model.default would not read back" };
   }
   if (provider && model.provider !== provider) {
-    return { ok: false, changed: false, provider, reason: "refusing to write: model.provider would not read back" };
+    return { ok: false, changed: false, provider, model: desiredModel, reason: "refusing to write: model.provider would not read back" };
+  }
+  if (entry?.apiUrl) {
+    const norm = (v: unknown) => String(v ?? "").trim().replace(/\/+$/, "").toLowerCase();
+    const blockUrl = norm(model.base_url);
+    if (blockUrl && blockUrl !== norm(entry.apiUrl)) {
+      return { ok: false, changed: false, provider, model: desiredModel, reason: `refusing to write: model.base_url (${String(model.base_url)}) is not where ${provider} lives (${entry.apiUrl})` };
+    }
+    if (model.api_mode && entry.apiMode && String(model.api_mode) !== entry.apiMode) {
+      return { ok: false, changed: false, provider, model: desiredModel, reason: `refusing to write: model.api_mode (${String(model.api_mode)}) contradicts ${provider} (${entry.apiMode})` };
+    }
   }
 
   // 配置里可能有 api_key：比 0600 宽的一律收紧。
@@ -173,7 +383,7 @@ export function writeModelDefault(
     renameSync(tmp, file);
   } catch (e) {
     try { rmSync(tmp, { force: true }); } catch { /* best effort */ }
-    return { ok: false, changed: false, provider, reason: `write failed: ${(e as Error).message}` };
+    return { ok: false, changed: false, provider, model: desiredModel, reason: `write failed: ${(e as Error).message}` };
   }
-  return { ok: true, changed: true, provider };
+  return { ok: true, changed: true, provider, model: desiredModel };
 }

package/packages/server/src/store/store.ts

@@ -1786,6 +1786,40 @@ export class Store {
     return Number(info.changes ?? 0) > 0;
   }
 
+  /**
+   * Refresh the MODEL half of a row's cached handshake.
+   *
+   * The handshake is a snapshot of the last real start, and it is the only thing a start dialog can
+   * read for a backend that is not running: a `currentModelId` captured before the operator switched
+   * models is stale forever (nothing else rewrites it), and the dialog would present — and replay —
+   * the model the agent no longer uses (#72). ``available`` is optional: only the live session knows
+   * the full list, so pass it when the caller has one.
+   */
+  recordHandshakeModels(
+    id: string,
+    models: { currentModelId?: string | null; available?: string[] },
+  ): void {
+    const row = this.#db.prepare("select handshake from backends where id = ?").get(id) as
+      | { handshake?: string | null }
+      | undefined;
+    if (!row?.handshake) return; // a row that never ran has no snapshot to correct
+    let hs: BackendHandshake;
+    try {
+      hs = JSON.parse(row.handshake) as BackendHandshake;
+    } catch {
+      return;
+    }
+    if (!hs?.models) return;
+    const current = models.currentModelId ?? null;
+    const supplied = models.available?.length ? models.available : hs.models.available;
+    // `current` must stay inside `available`: the dialog only shows an id that is in the list
+    // (`startModelValue`), so caching a current the list cannot contain would silently downgrade the
+    // next new-session default to "agent default" right after the operator switched (#72 review).
+    const available = current && !supplied.includes(current) ? [current, ...supplied] : supplied;
+    hs.models = { ...hs.models, currentModelId: current, available };
+    this.#db.prepare("update backends set handshake = ? where id = ?").run(JSON.stringify(hs), id);
+  }
+
   /**
    * Write back a health snapshot (and optionally a handshake) for one row. Deliberately a
    * column-scoped UPDATE rather than upsertBackend: a check must never resurrect a stale copy of

package/packages/shared/src/index.ts

@@ -140,29 +140,34 @@ export interface UsageView {
   totals?: UsageTotals | null;
 }
 
-/** Cumulative token buckets a turn's usage is measured against (ACP `Usage`). */
+/** Cumulative token buckets a turn's usage is measured against (ACP `Usage`).
+ *  `cacheRead`/`cacheWrite` are null = the agent never reports that bucket (issue #71); a
+ *  baseline of null diffs the first REPORTED value as the turn's own, same as undefined. */
 export interface UsageTotals {
   total: number;
   input: number;
   output: number;
   thought: number;
-  cacheRead: number;
-  cacheWrite: number;
+  cacheRead: number | null;
+  cacheWrite: number | null;
 }
 
 /** One turn's token bill (issue #70) — the DELTA of the agent's cumulative counters.
  *
- *  `cacheHitPercent` uses the webui's definition (prompt cache reads over the full prompt total:
- *  input + cache read + cache write), and is null when the agent reports no cache buckets at all —
- *  a Qoder session must read as unavailable, not as a 0% hit rate. `tps` is the turn AVERAGE
+ *  `cacheHitPercent` is cacheRead / input, where ACP's `inputTokens` is ALREADY the full prompt
+ *  (fresh + cache read + cache write — issue #71; do not add the buckets back, it counts cached
+ *  tokens twice and pins the reading near 50%). Null when the agent reports no cache buckets at
+ *  all — a Qoder session must read as unavailable, not as a 0% hit rate. `tps` is the turn AVERAGE
  *  (output tokens over wall time, tool calls included); it is deliberately labelled as an average
  *  rather than sold as instantaneous speed. */
 export interface TurnUsage {
   input: number;
   output: number;
   thought: number;
-  cacheRead: number;
-  cacheWrite: number;
+  /** NULL = the agent never reports this bucket (issue #71). A reported 0 is a real 0 — the
+   *  two must not collapse into one number, or 「写 0」 lies about cache writes (1.25× billed). */
+  cacheRead: number | null;
+  cacheWrite: number | null;
   total: number;
   durationMs?: number;
   cacheHitPercent?: number | null;