feat: 每平台可用模型范围 + 降级尝试 + 失败回报

配置页为每个 Agent 平台划定「邮件场景下可用的模型」，插件按顺序逐个尝试，
全部失败把原因封装成邮件回复。目录由插件上报、管理员只做勾选 —— 手打模型名
会打错，而打错的后果要到真发邮件时才暴露成一次失败。

## 目录上报走心跳，不另设端点

模型清单会在运行中变（换 provider 配置、上游上下线、换 API key）。
只在注册时报一次的话目录会静静变陈，管理员在配置页选中一个平台其实调不到的
模型。心跳本来就是 30 秒一次的现成通道；另设一个 POST 等于给「目录是谁写的」
留两个答案，排查时要同时看两处。

心跳响应回传 `allowed_models`，因此管理员改了范围后最多一个周期生效，
不必重启插件。

与 platform_sessions 同一约定：拉不到目录时**省略字段**（保留现有目录），
传空数组会把配置页清成空白。

## 目录与选择分两张表

模型会从平台目录里消失（上游临时下线、换了 provider 配置）。合成一张带
allowed 标记的表时，整行被删就连带把管理员的选择也删了，模型回来还得重配一遍。
分开存之后「选了什么」是持久的，目录只决定「这一项现在是否可用」；
已选但不在目录里的标为 stale 显示出来 —— 不显示会让人以为自己没选过它。

## 最难的一点：模型失败不是同步抛出的

两个平台都踩了。`promptAsync()` 立即返回、`ctx.agents.create()` 不校验模型，
只包 try/catch 的话第二个模型永远不会被试到 —— 第一个无效模型会被判成成功。

必须等异步结论：
- opencode → `session.error` 事件（event 钩子在 deliverMail 之外，
  因此用 turnWatchers 表把两者接起来）
- DSH → `turn/end` 的 `reason.kind === 'error'`

DSH 还有个陷阱：**`assistant/chunk` 不能当成功信号**，它的 `finish` 子类型
也带错误 —— `{chunk:{type:'finish',reason:{kind:'error',failure:{code:'NO_ADAPTER'}}}}`。
实测「无效 provider 却判成功」正是因为把任意 chunk 当成了走通。判据要落在
chunk 的类型上：finish 看 reason，其余才意味着模型真的在产出。

超时按成功处理（60 秒窗口）：模型可能只是很慢，把慢当成失败会在换模型的同时
把已经在跑的那一轮丢掉。

DSH 换模型要换会话 id（`<原 id>-r1`）并 dispose 失败那个 agent：复用同一个 id
会让重试接在一条已经出错的会话后面，不 dispose 则 agent/status 还会为那个
死会话触发一次自动转发。

## 其他决策

- **范围优先于环境变量**：范围是运行时可改的策略，`AGENTMAIL_REPLY_*` 是部署时
  的兜底。反过来的话管理员在配置页改了却不生效，得去改 service 文件重启
- **范围为空返回 `[undefined]` 而非 `[]`**：空数组会让调用方一次都不试，
  而「管理员没配」的正确含义是不限定，不是「一个都不许用」
- **上限 10 个**：降级是串行的，选 50 个意味着最坏情况下一封邮件要等 50 次超时
- 前端 key 按**第一个** `/` 切分 provider/model：model id 可能含 `/`
  （如 `org/model-name`），按最后一个切会把 provider 切错
- 保存后用服务端返回的结果刷新界面而非回显入参：repo 层会跳过重复与空字段

## 验证

- Go 10 个新测试（含「模型从目录消失后选择必须留存」的直接回归）
- 两插件各 18 个模型范围测试，共 180 个
- 端到端四轮：正常路由 → 全部无效（收到失败回报邮件，used_rounds 保持 0
  确认走了免配额通道）→ DSH 降级（fake-a 失败 → llmsproxy/AUTO 成功）→
  opencode 降级（nonexistent/bad 失败 → AUTO 成功，日志确认「前 1 个失败」）
- 生产已部署，前端「模型范围」页可用

docs/API.md

@@ -307,6 +307,7 @@ POST /permission/request       请求人类决策
 POST /attachments              上传附件
 GET  /attachments/{id}         下载附件
 POST /sessions/{id}/sync       回写平台侧生成的会话标题/slug
+GET  /agent/models/allowed     读当前生效的模型范围（通常不需要——心跳已回传）
 ```
 
 发信与转发扣**本任务（会话）的往返预算**。
@@ -342,6 +343,28 @@ Gateway 只看得见邮件驱动的那部分，人直接在平台界面上开的
 字段要求见 [插件适配指南](PLUGIN-GUIDE.md#四平台会话快照上报)（含 subagent 过滤、
 slug 去重等规则）。
 
+心跳还可带 `models`（平台当前看得见的模型目录）：
+
+```json
+{ "models": [
+    { "provider": "llmsproxy", "model": "AUTO", "display_name": "AUTO (smart routing)" }
+] }
+```
+
+响应回传当前生效的模型范围，插件据此决定这一轮按什么顺序尝试：
+
+```json
+{
+  "status": "ok", "pending_mails": 0, "stats": {...},
+  "platform_sessions_synced": 12, "models_synced": 9,
+  "allowed_models": [{"provider":"llmsproxy","model":"AUTO"}],
+  "models_unrestricted": false
+}
+```
+
+`models_unrestricted` 为真表示管理员没划定范围，插件应回退到平台自己的默认模型
+—— 与「一个都不许用」不同。
+
 ### 标记已读
 
 ```bash
@@ -362,6 +385,31 @@ curl -X POST {host}/api/v1/mail/read -H "Authorization: Bearer $AGENT_KEY"
 - 「全部标掉」排除已归档会话：那些邮件在收件箱里看不到，
   标了只会让计数与用户看到的对不上
 
+### 每个 Agent 可用的模型范围
+
+```
+GET /admin/agents/{name}/models    目录（带已选标记与 rank）+ stale
+PUT /admin/agents/{name}/models    保存选择，数组顺序即优先级
+```
+
+```bash
+curl -X PUT {host}/api/v1/admin/agents/dsh/models -b cookie.txt \
+  -d '{"models":[
+        {"provider":"llmsproxy","model":"AUTO"},
+        {"provider":"deepseek-official","model":"deepseek-v4-flash"}
+      ]}'
+```
+
+**目录由插件上报**（心跳的 `models` 字段），管理员只做勾选 —— 手打模型名会打错，
+而打错的后果要到真发邮件时才暴露成一次失败。
+
+- **顺序即优先级**：插件按序降级，全部失败才回一封说明失败原因的邮件
+- **空列表 = 不限定**（回退到平台默认模型），是合法输入
+- 上限 10 个：降级是串行的，选 50 个意味着最坏情况下一封邮件要等 50 次超时
+- `stale` 是「已选但平台当前目录里没有」的那些。目录与选择分两张表存 ——
+  模型从平台目录消失（上游临时下线）时管理员的选择必须留存，
+  否则模型回来还得重配一遍
+
 ### 免配额通道：harness 代劳的转发
 
 **配额约束的是模型的自主发信，不是 harness 的转发。** 插件代劳搬运的两类消息不占额度：