agentus 0.13.1 → 0.14.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentus",
-  "version": "0.13.1",
+  "version": "0.14.0",
   "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": {

package/packages/server/mock/agent.mjs

@@ -617,6 +617,39 @@ const agent = () => ({
       return { stopReason: "end_turn" };
     }
 
+    // `[tail-probe]` — 一次「说一半就去做工具」的回合，用来钉住朗读队列的那条规矩（#60）：
+    // 第一段文字以**没有句末标点的半句**结尾（朗读器会先扣着等合并），紧接着调一个工具（回合
+    // 因此不结束），然后**另一条消息**接着说。真实后端就是这个形状，而扣着的半句曾经在这里蒸发。
+    // QA only：别的提示词完全不走这条路。
+    if (/\[tail-probe\]/.test(text)) {
+      const first = `第一段：我先把结论说一遍。然后我去看文件，最后半句没有句号`;
+      await send(agent._conn, sessionId, {
+        sessionUpdate: "agent_message_chunk",
+        messageId: `tail-a-${sessionId}`,
+        content: { type: "text", text: first },
+      });
+      await sleep(60);
+      const id = `tc-${sessionId}-tail`;
+      await send(agent._conn, sessionId, {
+        sessionUpdate: "tool_call", toolCallId: id,
+        title: "read_file docs/notes.md", kind: "read", status: "in_progress",
+        rawInput: { path: "docs/notes.md" },
+      });
+      await sleep(400);
+      await send(agent._conn, sessionId, {
+        sessionUpdate: "tool_call_update", toolCallId: id,
+        status: "completed", rawOutput: "42 lines",
+      });
+      await sleep(120);
+      await send(agent._conn, sessionId, {
+        sessionUpdate: "agent_message_chunk",
+        messageId: `tail-b-${sessionId}`,
+        content: { type: "text", text: "文件看完了，这里是第二段。" },
+      });
+      await sleep(400);          // let the frame land before the turn closes (same as the other fixtures)
+      return { stopReason: "end_turn" };
+    }
+
     if (wantThink) {
       // ONE `messageId` per burst, like the real adapter sends: ACP gives every chunk of one
       // thought block the same id, and the cockpit/server coalesce on it (`block_key`). A mock

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

@@ -15,6 +15,7 @@ import type {
   RequestPermissionResponse,
 } from "@agentclientprotocol/sdk";
 import { applyContextWindow, BACKENDS, buildSpawnEnv, nativePlanSourceOf, type BackendSpec } from "./backends.js";
+import { providerFromDescription, writeModelDefault } from "../model-default.js";
 import { forgetAgentOwner, recordAgentOwner, verifyAgentOwner } from "./agent-owner.js";
 import { thinkingOptionOf, voiceAppliesToPrompt, voiceModeBlock } from "./voice-mode.js";
 import {
@@ -51,7 +52,7 @@ import type {
 } from "../../../shared/src/index.js";
 import { acceptsToolWrite, acceptsWriteFrom, clampExplanation, clampTitle, demoteInProgress, foldPlanUpdate, hasUnfinished, normalizeItems, v2PlanEnabled } from "../plan/plan.js";
 import { PLAN_GUIDANCE_ACTIVE, PLAN_GUIDANCE_INTRO, PLAN_GUIDANCE_NATIVE } from "../../../shared/src/index.js";
-import { AGENT_DEFAULT, PREFS_DEFAULT, agentSettings, type PlanHintSettings } from "../settings.js";
+import { AGENT_DEFAULT, PREFS_DEFAULT, agentSettings, bumpModelUsage, type PlanHintSettings } from "../settings.js";
 
 // The cockpit CLI an agent is handed (issue #15). Resolved from THIS module's location, so it points
 // at the same tree the server runs from — a checkout and an installed package alike (`bin/` is in the
@@ -964,6 +965,9 @@ export class SessionManager {
       // this method — that is exactly what keeps a per-session pick from being silently undone.
       await this.#applyDefaultMode(live);
       this.#updateSession(live);
+      // #62-2：新建会话从 `starting` 起步，握手这 1–3 秒里操作者已经能在 rail 上点它并选模型
+      // （那时走冷分支写进 pending）。没有这一句，那个选择要等到几小时后被回收再 resume 才生效。
+      await this.#replayPendingModel(live.info.id);
     } catch (err) {
       child.kill("SIGKILL");
       live.info.status = "error";
@@ -1213,7 +1217,12 @@ export class SessionManager {
         }
       }
       live.info.status = "ready";
+      // 新进程的 info 不会自带 pending：如果这里不补，下面 #updateSession 会把操作者在冷槽上
+      // 选好的模型按"没有"持久化掉 —— 意图在下一次写库时静默消失。
+      live.info.pendingModelId = row.pendingModelId ?? null;
       this.#updateSession(live);
+      // #62-2 重放：操作者在冷会话上选过的模型，现在有 agent 了，把它补发出去。
+      await this.#replayPendingModel(id);
       // a resumed slot is the same evidence as a fresh one: the row does work
       this.#noteBackendCheck(
         String(row.backend),
@@ -1354,12 +1363,59 @@ export class SessionManager {
   }
 
   /** One row in the shape list()/cold()/archived() produce, from a stored row. */
+  /** #62-3：把这次选择写进 agent 自己的配置。失败只记日志 —— 会话已经在新模型上跑起来了，
+   *  配置文件没写成是"下次新会话的默认没跟上"，不该回头把一次成功的切换报成失败。 */
+  /** #62-2 兑现"冷会话上选好的模型"。
+   *
+   *  **现读 store，不用 resume 开头那个快照**：resume 从读行到 status=ready 要 10–40 秒，这期间
+   *  操作者完全可能在界面上再点一个模型（走冷分支写进 pending）。快照重放会把新的那个覆盖掉，
+   *  而且重放成功后 pending 被清空 —— 新选择就静默消失了。 */
+  async #replayPendingModel(id: string): Promise<void> {
+    const pending = this.#store.getSession(id)?.pendingModelId ?? null;
+    if (!pending) return;
+    try {
+      await this.setModel(id, pending, { fromReplay: true });
+    } catch (e) {
+      const msg = errMessage(e);
+      // 结构性拒绝（agent 不认这个模型）永远不会成功，留着 pending 只会每次 resume 再撞一次；
+      // 传输类失败（连接刚断）才值得下一次再试。
+      if (/unknown model/i.test(msg)) {
+        this.#store.setPendingModel(id, null);
+        const live = this.#sessions.get(id);
+        if (live) live.info.pendingModelId = null;
+      }
+      console.log(`[agentus] pending model ${pending} for ${id} was refused: ${msg}`);
+    }
+  }
+
+  #writeBackModelDefault(info: SessionInfo, modelId: string): void {
+    try {
+      const shape = this.#spawnShape(info.backend);
+      if (!shape) return;
+      const home = buildSpawnEnv(shape.spec).home;
+      const desc = (info.models?.availableModels ?? []).find((m) => m.modelId === modelId)?.description ?? null;
+      const r = writeModelDefault(info.backend, home, modelId, {
+        provider: providerFromDescription(desc),
+        // `hermes -p <name>` 的配置住在 `<HERMES_HOME>/profiles/<name>/config.yaml`：不传这一项
+        // 就会改到默认 profile 的默认模型上，当前会话那个 profile 反而没变。
+        profile: shape.spec.profile ?? null,
+      });
+      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}`);
+      }
+    } catch (e) {
+      console.log(`[agentus] model default write-back failed: ${errMessage(e)}`);
+    }
+  }
+
   #infoFromRow(r: SessionRow): SessionInfo {
     return {
       id: r.id, backend: r.backend, acpSessionId: r.acpSessionId, cwd: r.cwd,
       workspace: r.workspace ?? null,
       models: (r.models ?? null) as SessionInfo["models"],
       contextLimit: r.contextLimit ?? null,
+      pendingModelId: r.pendingModelId ?? null,
       title: r.title, autoTitle: r.autoTitle ?? null, titleBy: r.titleBy ?? null, status: r.status, pid: null,
       createdAt: r.createdAt,
       modes: (r.modes ?? null) as SessionModeState | null,
@@ -2998,15 +3054,45 @@ export class SessionManager {
    *  SDK's typed surface, so it goes through the generic request() overload (verified
    *  against hermes acp, which implements set_session_model). A cold slot has no agent
    *  to switch: resume it first, then pick (same rule as modes). */
-  async setModel(id: string, modelId: string): Promise<SessionInfo> {
-    const s = this.#need(id);
-    if (!s.conn || !s.info.acpSessionId) throw new Error("session not ready — resume it first");
+  async setModel(id: string, modelId: string, opts: { fromReplay?: boolean } = {}): Promise<SessionInfo> {
+    const live = this.#sessions.get(id);
+    // 「能不能真的发出去」不是"map 里有没有这一条"，而是**进程还活着**：崩掉的槽位仍在 map 里、
+    // conn 也还挂着，对它发请求只会得到 `ACP connection closed`。所以先问进程。
+    const hot = Boolean(live && live.conn && live.info.acpSessionId && live.child
+      && live.child.exitCode === null && live.child.signalCode === null
+      && (live.info.status === "ready" || live.info.status === "running"));
+    // #62-2 冷会话：没有 agent 可以发 session/set_model —— 但"打开会话前先把它要用的模型定好"
+    // 恰恰是最常见的时机（夜里回收一批，早上逐个指定再开工）。所以把意图停在行上，resume 时重放；
+    // 以前这里第一行就 throw "session not ready — resume it first"，等于逼操作者先花 10–40 秒唤醒。
+    if (!hot) {
+      const row = this.#store.getSession(id);
+      if (!row) throw new Error(`no such session: ${id}`);
+      const known = ((row.models ?? null) as SessionInfo["models"])?.availableModels ?? [];
+      if (known.length && !known.some((m) => m.modelId === modelId)) {
+        throw new Error(`unknown model: ${modelId}`);
+      }
+      if (!this.#store.setPendingModel(id, modelId)) throw new Error(`no such session: ${id}`);
+      this.#emitSessions();
+      return this.#coldInfo(id);
+    }
+    const s = live as NonNullable<typeof live>;
+    const conn = s.conn;
+    if (!conn || !s.info.acpSessionId) throw new Error("session not ready — resume it first");
     const known = s.info.models?.availableModels ?? [];
     if (known.length && !known.some((m) => m.modelId === modelId)) {
       throw new Error(`unknown model: ${modelId}`);
     }
-    await s.conn.request("session/set_model", { sessionId: s.info.acpSessionId, modelId });
+    await conn.request("session/set_model", { sessionId: s.info.acpSessionId, modelId });
     if (s.info.models) s.info.models = { ...s.info.models, currentModelId: modelId };
+    if (s.info.pendingModelId) s.info.pendingModelId = null;
+    this.#store.setPendingModel(id, null);
+    // #62-1: 只有 agent **接受**过的切换才计数 —— 被拒的条目永不加分，于是"广告了但实际不可用"
+    // 的模型会自己沉到列表底部，不需要任何端点探活。
+    bumpModelUsage(`${s.info.backend}|${modelId}`);
+    // #62-3：选定即成为 agent 的全局默认（设置里可关）。同样只在这一行之后 —— 被拒的模型不落盘。
+    // **重放不算**：冷槽上留下的意图可能被一次无人值守的 completion 唤醒带上（resume <-
+    // `this.resume(e.origin)`），那时代码里没有"操作者在选模型"这件事，不该改全局配置。
+    if (!opts.fromReplay && agentSettings().modelWriteBack) this.#writeBackModelDefault(s.info, modelId);
     this.#updateSession(s);
     this.#emitSessions();
     return s.info;

package/packages/server/src/index.ts

@@ -27,6 +27,7 @@ import {
   SUMMARY_MAX_INPUT_CHARS, SUMMARY_THINKING_BUDGET,
   agentSettings, getSettings, initSettings, observerSettings, planHintSettings, publicSettings,
   saveAgent, saveCall, saveObserver, savePrefs, saveSettings, saveSummary, saveTheme, summarySettings,
+  modelUsage,
 } from "./settings.js";
 import { ObserverHub } from "./observer/hub.js";
 import * as auth from "./auth.js";
@@ -1478,6 +1479,10 @@ async function post(path){const r=await fetch(path,{method:'POST'});alert(r.ok?'
     }
     // Operator settings: the page reads and writes this. Secrets only ever leave
     // through a mask (publicSettings) — an unchanged mask round-trips as "keep".
+    // #62-1: 模型使用计数。列表排序要跨会话、跨设备一致，所以它在 server 上；前端只读。
+    if (url.pathname === "/api/model-usage" && req.method === "GET") {
+      return send(res, 200, { usage: modelUsage() });
+    }
     if (url.pathname === "/api/settings" && req.method === "GET") {
       return send(res, 200, publicSettings());
     }

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

@@ -0,0 +1,179 @@
+// 把"我刚选的模型"落成 agent 自己的全局默认（#62-3）。
+//
+// 为什么 server 直接改配置文件：agentus 换模型只影响当前会话，而 agent 侧的默认值住在它自己的
+// 配置里（Hermes 是 `<HERMES_HOME>/config.yaml` 的 `model.default` + `model.provider`）。桌面/
+// 沙箱部署一人一环境，"最近一次选择 = 我想要的默认"是正确语义，所以选定即回写，不弹确认。
+//
+// 三条纪律：
+//   · 只在 server 的 setModel **成功之后**、且是操作者动作时调用（重放不算，见 session-manager）。
+//   · 写完必须能读回来：写盘前用真 YAML 解析器验一遍 `model.default` 是不是那个值，验不过就**拒写**。
+//     这是别人的全局配置文件，写坏了下次 spawn 直接起不来 —— 宁可不动，也不能"改成功但改坏"。
+//   · 原子写（临时文件 + rename）并保持原权限；只动 `model.default` / `model.provider` 两行。
+import { chmodSync, copyFileSync, existsSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { parse as parseYaml } from "yaml";
+
+export interface WriteBackResult {
+  ok: boolean;
+  changed: boolean;
+  /** 写进去的 provider；null = 没写（推不出或不安全） */
+  provider: string | null;
+  reason?: string;
+}
+
+export interface WriteBackOptions {
+  /** agent 在 `availableModels[].description` 里自己声明的 provider；推不出就别传 */
+  provider?: string | null;
+  /** hermes 的 `-p <profile>`：named profile 是**另一个** home，不能写到默认 profile 上 */
+  profile?: string | null;
+}
+
+/** agent 的配置文件在哪。
+ *
+ *  `home` 是 `buildSpawnEnv().home`，对 hermes 而言**就是 HERMES_HOME 本身**（backends.ts 的
+ *  `isolation.homeVar = "HERMES_HOME"`, `homeDefault = ~/.hermes`）—— 不能再拼一层 `.hermes`。
+ *  同仓的 `speech/route.ts` 也是 `path.join(home, "config.yaml")`。 */
+function configPath(backend: string, home: string | null | undefined, profile: string | null | undefined): string | null {
+  if (backend !== "hermes" || !home) return null;
+  const root = profile ? path.join(home, "profiles", profile) : home;
+  return path.join(root, "config.yaml");
+}
+
+/** 从模型清单的 description（"Provider: DeepSeek"）里取 provider。
+ *  前缀猜（deepseek-* → deepseek）在共享 key 的多端点部署里是错的，agent 自己声明的那个才对。
+ *
+ *  但描述会带杂质：hermes 的 named catalog 拼的是 `Provider: <label> • <desc> • current`，
+ *  所以剥掉尾部的状态词之后还得**只接受标识符形状**（`Anthropic (Claude Sonnet 4.5)` 这种
+ *  写进 `model.provider` 会让 agent 起不来）—— 不合格就当没推出来，只写 default。 */
+export function providerFromDescription(description: string | null | undefined): string | null {
+  const m = /^\s*provider:\s*(.+)$/i.exec(description ?? "");
+  if (!m) return null;
+  const name = m[1]
+    .replace(/[•·|,-]?\s*\b(current|active|selected|default)\b\s*$/i, "")
+    .replace(/[•·|,\s-]+$/g, "")
+    .trim();
+  return /^[A-Za-z0-9._:-]+$/.test(name) ? name : null;
+}
+
+const headerAt = (lines: string[]): number => lines.findIndex((l) => /^model:\s*(#.*)?\r?$/.test(l));
+
+/** 在 `model:` 块里定位某个键的行号；列 0 的 `#` 是注释，不结束块（夹在块里是合法的）。 */
+function findInModelBlock(lines: string[], key: string): number {
+  const start = headerAt(lines);
+  if (start < 0) return -1;
+  for (let i = start + 1; i < lines.length; i++) {
+    const line = lines[i].replace(/\r$/, "");
+    if (!line.trim()) continue;
+    if (/^#/.test(line)) continue; // 注释：不影响结构，继续找
+    if (/^\S/.test(line)) break; // 下一个顶层键
+    if (new RegExp(`^\\s+${key}:`).test(line)) return i;
+  }
+  return -1;
+}
+
+/** 块内第一个键的缩进（插入新键时用它，别硬编码 2 空格 —— 4 空格的文件会写出 nested mapping）。 */
+function blockIndent(lines: string[]): string {
+  const start = headerAt(lines);
+  if (start < 0) return "  ";
+  for (let i = start + 1; i < lines.length; i++) {
+    const line = lines[i].replace(/\r$/, "");
+    if (!line.trim()) continue;
+    if (/^#/.test(line)) continue;
+    if (/^\S/.test(line)) break;
+    const m = /^(\s+)\S/.exec(line);
+    if (m) return m[1];
+  }
+  return "  ";
+}
+
+/** 只接受能安全裸写的标量；其余加单引号（`:`、`#`、`&`、`*` 会把标量改语义）。 */
+function yamlScalar(value: string): string {
+  if (/^[A-Za-z0-9._:/@+-]+$/.test(value)) return value;
+  return `'${value.replace(/'/g, "''")}'`;
+}
+
+function setKey(lines: string[], key: string, value: string, indent: string): string[] {
+  const eol = lines.some((l) => l.endsWith("\r")) ? "\r" : "";
+  const rendered = `${indent}${key}: ${yamlScalar(value)}`;
+  const at = findInModelBlock(lines, key);
+  if (at >= 0) {
+    if (lines[at].replace(/\r$/, "") === rendered) return lines;
+    const copy = [...lines];
+    copy[at] = `${rendered}${eol}`;
+    return copy;
+  }
+  const start = headerAt(lines);
+  if (start < 0) return [...lines, `model:${eol}`, `${rendered}${eol}`];
+  const copy = [...lines];
+  copy.splice(start + 1, 0, `${rendered}${eol}`);
+  return copy;
+}
+
+/** 把 modelId（以及可安全推断时的 provider）写进 agent 的配置文件。 */
+export function writeModelDefault(
+  backend: string,
+  home: string | null | undefined,
+  modelId: string,
+  options: WriteBackOptions = {},
+): WriteBackResult {
+  const profile = options.profile ? String(options.profile).trim() || null : null;
+  const file = configPath(backend, home, profile);
+  if (!file) return { ok: false, changed: false, provider: null, reason: `${backend}: no known config file` };
+  if (!existsSync(file)) return { ok: false, changed: false, provider: null, reason: `no config at ${file}` };
+  if (!modelId) return { ok: false, changed: false, provider: null, reason: "empty model id" };
+
+  let text: string;
+  let mode: number;
+  try {
+    text = readFileSync(file, "utf8");
+    mode = statSync(file).mode & 0o777;
+  } catch (e) {
+    return { ok: false, changed: false, provider: null, reason: `unreadable: ${(e as Error).message}` };
+  }
+
+  const lines = text.split("\n");
+  // 行内 flow（`model: {…}`）和锚点（`model: &m`）都不是"块"：追加会造出第二个顶层 `model:`。
+  // 这种形状一律拒写 —— 我们只改块，不重排别人的文件。
+  const header = lines.find((l) => /^model:/.test(l));
+  if (header !== undefined && headerAt(lines) < 0) {
+    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;
+  const indent = blockIndent(lines);
+  let work = lines;
+  if (provider) work = setKey(work, "provider", provider, indent);
+  work = setKey(work, "default", modelId, indent);
+
+  const next = work.join("\n");
+  if (next === text) return { ok: true, changed: false, 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]})` };
+  }
+  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" };
+  }
+  if (provider && model.provider !== provider) {
+    return { ok: false, changed: false, provider, reason: "refusing to write: model.provider would not read back" };
+  }
+
+  // 配置里可能有 api_key：比 0600 宽的一律收紧。
+  const targetMode = mode & 0o077 ? 0o600 : mode;
+  const tmp = `${file}.tmp-${process.pid}-${Date.now()}`;
+  try {
+    copyFileSync(file, `${file}.bak-${Date.now()}`); // 别人的配置，改之前留一份
+    writeFileSync(tmp, next, { mode: targetMode });
+    chmodSync(tmp, targetMode);
+    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: true, changed: true, provider };
+}

package/packages/server/src/settings.ts

@@ -209,6 +209,9 @@ export interface AgentSettings {
    *  (`context`/`messages`/`plan`) is NOT gated: it cannot change anything, and it is what the
    *  工作播报 observer runs on. */
   cockpitSend: boolean;
+  /** #62-3：选定模型后回写 agent 自己的配置文件（`model.default`）。默认开 —— 一人一环境里
+   *  "我最近选的模型就是我想要的默认"是正确语义；留这个开关只是为了能关掉别动别人的配置。 */
+  modelWriteBack: boolean;
   /** Let a finished background process wake the agent with its own result (issue #22). ON by default:
    *  this is what the CLI and the gateway already do, and the failure it prevents is the silent one —
    *  a session that looks finished while a build is still running, whose result nobody ever reads. */
@@ -230,7 +233,7 @@ export interface AgentSettings {
 }
 
 export const AGENT_DEFAULT: AgentSettings = {
-  idleKillMin: 5, warmSlots: 5, warmTtlHours: 24, cockpitSend: false, completionWake: true,
+  idleKillMin: 5, warmSlots: 5, warmTtlHours: 24, cockpitSend: false, completionWake: true, modelWriteBack: true,
   showSilentBackground: false, recallItemChars: 400, recallTotalChars: 12000,
 };
 
@@ -427,9 +430,27 @@ export interface Settings {
   agent: AgentSettings;
   observer: ObserverSettings;
   summary: SummarySettings;
+  /** 模型使用计数（#62-1）：key = `<backend>|<provider>|<modelId>`，value = 成功切换的次数。
+   *  放 server 而不是前端 localStorage —— 排序要跨会话、跨设备一致，且所有切换入口都收敛
+   *  在 server 的 setModel 上，记这一处就不漏。被 agent 拒的条目永不计数。 */
+  modelUsage: Record<string, number>;
   updatedAt: number;
 }
 
+/** 计数表的上限：一个 agent 广告几百个模型，键会脏（换过 provider 名字等），别让它无限长。 */
+const MODEL_USAGE_MAX = 3000;
+
+function pickModelUsage(raw: unknown): Record<string, number> {
+  const out: Record<string, number> = {};
+  if (!raw || typeof raw !== "object") return out;
+  const entries = Object.entries(raw as Record<string, unknown>)
+    .filter(([k, v]) => typeof k === "string" && k.length <= 200 && typeof v === "number" && Number.isFinite(v) && v > 0)
+    .sort((a, b) => Number(b[1]) - Number(a[1]))
+    .slice(0, MODEL_USAGE_MAX);
+  for (const [k, v] of entries) out[k] = Math.min(1e9, Math.round(Number(v)));
+  return out;
+}
+
 const DEFAULTS: VoiceSettings = {
   provider: "dashscope",
   baseUrl: "",
@@ -454,7 +475,7 @@ let legacyFile = "";
 let cache: Settings = {
   voice: { ...DEFAULTS }, theme: { ...THEME_DEFAULT }, call: { ...CALL_DEFAULT },
   prefs: { ...PREFS_DEFAULT }, agent: { ...AGENT_DEFAULT },
-  observer: { ...OBSERVER_DEFAULT }, summary: { ...SUMMARY_DEFAULT }, updatedAt: 0,
+  observer: { ...OBSERVER_DEFAULT }, summary: { ...SUMMARY_DEFAULT }, modelUsage: {}, updatedAt: 0,
 };
 /** keys that came from env/.env (shown as "auto-detected" and used when settings are empty) */
 let envCreds: { apiKey: string; baseUrl: string; source: string } | null = null;
@@ -521,6 +542,7 @@ export function initSettings(dataDir: string, store: Store): Settings {
     agent: pickAgent(stored.agent),
     observer: pickObserver(stored.observer),
     summary: pickSummary(stored.summary),
+    modelUsage: pickModelUsage((stored as Partial<Settings>).modelUsage),
     updatedAt: Number((stored as Settings).updatedAt ?? 0),
   };
   // an unset baseUrl/apiKey bootstrap from the environment: the operator said the
@@ -577,6 +599,7 @@ function pickAgent(raw: unknown): AgentSettings {
     take("recallItemChars", AGENT_RECALL_ITEM_RANGE);
     take("recallTotalChars", AGENT_RECALL_TOTAL_RANGE);
     if (typeof r.cockpitSend === "boolean") out.cockpitSend = r.cockpitSend;
+    if (typeof r.modelWriteBack === "boolean") out.modelWriteBack = r.modelWriteBack;
     if (typeof r.completionWake === "boolean") out.completionWake = r.completionWake;
     if (typeof r.showSilentBackground === "boolean") out.showSilentBackground = r.showSilentBackground;
   }
@@ -646,11 +669,27 @@ function persist(): void {
     db.setSetting("agent", cache.agent);
     db.setSetting("observer", cache.observer);
     db.setSetting("summary", cache.summary);
+    db.setSetting("modelUsage", cache.modelUsage);
   } catch (e) {
     console.error(`[agentus] cannot write settings: ${(e as Error).message}`);
   }
 }
 
+/** 模型计数快照（#62-1）。前端拿它给模型列表排序 —— 只是读，改不了。 */
+export function modelUsage(): Record<string, number> {
+  return cache.modelUsage;
+}
+
+/** 一次**成功**的模型切换。调用点在 session-manager.setModel 里 agent 接受之后 —— 被拒的
+ *  条目不加分，于是"广告了但实际不可用"的模型会自己沉底，不需要任何端点探活。 */
+export function bumpModelUsage(key: string): void {
+  if (!key) return;
+  const next = { ...cache.modelUsage };
+  next[key] = (next[key] ?? 0) + 1;
+  cache = { ...cache, modelUsage: pickModelUsage(next), updatedAt: Date.now() };
+  persist();
+}
+
 export function getSettings(): Settings {
   return cache;
 }
@@ -908,6 +947,10 @@ export function saveAgent(patch: Record<string, unknown>): Settings {
     if (typeof patch.cockpitSend !== "boolean") throw new Error("invalid cockpitSend: expected true or false");
     a.cockpitSend = patch.cockpitSend;
   }
+  if ("modelWriteBack" in patch) {
+    if (typeof patch.modelWriteBack !== "boolean") throw new Error("invalid modelWriteBack: expected true or false");
+    a.modelWriteBack = patch.modelWriteBack;
+  }
   if ("completionWake" in patch) {
     if (typeof patch.completionWake !== "boolean") throw new Error("invalid completionWake: expected true or false");
     a.completionWake = patch.completionWake;

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

@@ -168,6 +168,7 @@ export interface SessionRow {
   /** Models the agent advertised (JSON) + the operator's context-window override. */
   models?: unknown;
   contextLimit?: number | null;
+  pendingModelId?: string | null;
   /** The directory the cockpit works in for this slot: the file/terminal panel's
    *  root, and the cwd a cold slot is resumed with. Deliberately separate from
    *  `cwd` — a live ACP child cannot be re-cd'd (its cwd was fixed at newSession),
@@ -194,6 +195,7 @@ interface RawSessionRow {
   workspace?: string | null;
   home?: string | null;
   models?: string | null; context_limit?: number | null;
+  pending_model_id?: string | null;
   system?: number | null;
 }
 
@@ -263,6 +265,7 @@ function rowToSession(r: RawSessionRow): SessionRow {
     system: Boolean(r.system),
     models: parseJson(r.models),
     contextLimit: r.context_limit ?? null,
+    pendingModelId: r.pending_model_id ?? null,
   };
 }
 
@@ -479,6 +482,9 @@ export class Store {
     this.#db.exec("update sessions set auto_title = title where auto_title is null or auto_title = ''");
     // integer column, so it gets its own migration (the loop above assumes text)
     if (!cols.has("context_limit")) this.#db.exec("alter table sessions add column context_limit integer");
+    // #62-2: a cold slot has no agent to send session/set_model to, so the operator's pick is
+    // PARKED here and replayed on the next resume. text, so it rides the loop above.
+    if (!cols.has("pending_model_id")) this.#db.exec("alter table sessions add column pending_model_id text");
     // WHICH SESSIONS THE COCKPIT OWNS (issue #16): 1 = the 工作播报 observer, 0 = the operator's work.
     // Its own column rather than a title convention, because this flag decides whether a row is
     // allowed into the rail, the warm-slot ranking and the cockpit CLI's scope — a rename must not be
@@ -1702,6 +1708,14 @@ export class Store {
   }
 
   /** The operator's declared context window for a slot (null clears it). */
+  /** #62-2: the model a cold slot should adopt when it next wakes. */
+  setPendingModel(id: string, modelId: string | null): boolean {
+    const info = this.#db
+      .prepare("update sessions set pending_model_id = ? where id = ?")
+      .run(modelId || null, id);
+    return Number(info.changes ?? 0) > 0;
+  }
+
   setContextLimit(id: string, limit: number | null): boolean {
     const info = this.#db
       .prepare("update sessions set context_limit = ? where id = ?")

package/packages/shared/src/index.ts

@@ -88,6 +88,9 @@ export interface SessionInfo {
    *  what the agent reports via usage_update or this — the operator's declared window.
    *  null = use whatever the agent reports. */
   contextLimit?: number | null;
+  /** 冷会话上「下一个模型」（#62-2）：没有 agent 进程可以发 session/set_model，于是把意图存下来，
+   *  resume 成功后重放一次并清空。null = 没有待生效的选择。 */
+  pendingModelId?: string | null;
   /** The window the operator declared for the CURRENT model (remembered per model, the way
    *  hermes-studio stores a context length per provider+model). Precedence for the gauge:
    *  contextLimit (this session) → this → the agent's own usage_update.size. */