cardbuddy 0.13.3 → 0.14.1

package/dist/vendored/server/core/ai-chat.js

@@ -14,7 +14,10 @@
  *     并附浅层清单：模型不必再自己试错形态，省下的步数用于真正的建卡动作。
  *   - system prompt 为精简协议 + 参考索引；模型用 skill_read 工具按需取
  *     skills/dsl-card-generator/references 下的文档（避免整份 skill 十万字进上下文放大空转思考）。
- *   - 客户端断开（前端「停止」按钮 / 关页）即中止 LLM 请求与工具循环，不再白跑。
+ *   - 客户端断开（刷新 / 断网 / 关标签页）不再等于终止：回合转 detached 在服务端继续跑，
+ *     事件全在回合日志里，重连按 seq 续订即可；真正「停止」是显式 POST /__ai/stop。
+ *   - 回合日志按卡片落盘 .cache/ai-turns/<cardId>.jsonl（跨回合追加，行内带 turnId + seq）：
+ *     断线续跑的回放源，也是回合收尾时「服务端权威历史」的唯一事实源（turnJournal.js）。
  *   - 对话记录按卡片落盘 .cache/ai-chats/<cardId>.json（.cache/ 不入库），切卡 / 重开可续。
  *   - 本地文件挂载：不上传，只解析绝对路径 + 元信息；图片预览由本机读盘直出。
  *
@@ -22,7 +25,10 @@
  *   GET/POST  /__ai/config            读取（脱敏；?reveal=1 回明文供设置面板回显）/ 保存模型配置
  *   POST      /__ai/ping              连通性自测（设置面板「测试连接」）
  *   POST      /__ai/chat              SSE 流式对话
- *   GET/POST/DELETE /__ai/history     按 cardId 读 / 存 / 清对话记录
+ *   GET/POST/DELETE /__ai/history     按 cardId 读 / 存（与服务端权威历史按 turnId 合并去重）/ 清对话记录
+ *   GET       /__ai/turns             这张卡的回合状态（活跃回合 turnId/seq/detached + 最近回合清单）
+ *   POST      /__ai/stop              显式终止当前回合（断开连接不再隐式终止）
+ *   GET       /__ai/turn              SSE 续订 / 回放：?cardId=&afterSeq=[&turnId=]，先补发断点后的行再跟新事件
  *   POST      /__ai/fs/pick           调起系统选择器，返回绝对路径
  *   GET       /__ai/fs/stat           路径元信息（文件 / 文件夹摘要）
  *   GET       /__ai/fs/raw            本地图片直出（仅预览用）
@@ -30,7 +36,10 @@
  *   POST      /__ai/fs/stash          剪贴板截图落盘为本机路径（同样只存本地 .cache/）
  *   POST      /__ai/approve           对话内审批回落（skill_exec / shell_exec 的「允许 / 本回合不再询问 / 拒绝」）
  *
- * /__ai/chat SSE 事件：
+ * /__ai/chat SSE 事件（每条都带自增 seq；断线后按 seq 向 GET /__ai/turn 要「断点之后」的事件，不重不漏）：
+ *   data: {"type":"turn-start","turnId":"t...","cardId":"...","startedAt":1700000000000,"seq":1}
+ *                                                                   回合开跑：turnId 是日志 / 续订 / 权威历史的对齐键
+ *   data: {"type":"client-detached","turnId":"t...","seq":N}         客户端断开、回合在服务端继续（只落日志）
  *   data: {"type":"reasoning-delta","text":"..."}
  *   data: {"type":"text-delta","text":"..."}
  *   data: {"type":"tool-call","toolCallId":"...","toolName":"card_write","args":{...}}
@@ -39,10 +48,17 @@
  *   data: {"type":"approval-request","approvalId":"...","toolName":"skill_exec","command":"python3 skills/...","args":{...}}
  *   data: {"type":"approval-decided","approvalId":"...","ok":true,"scope":"once|turn"}
  *   data: {"type":"approval-auto","toolName":"skill_exec","command":"node skills/..."}   免确认策略命中：没弹审批，直接执行
- *   data: {"type":"notice","message":"..."}                                  横幅提示（重复调用警告 / 上下文折叠 / 收敛催促）
+ *   data: {"type":"notice","level":"info|warn|error","code":"...","message":"..."}  过程事件（上下文折叠 / 自动续跑 / 收敛催促 / 网关重试…）
+ *                                                                   前端落进消息「过程事件」时间线持久可见，横幅只保留最近一条
+ *   data: {"type":"round-retry","reason":"stall|reasoning","attempt":1,"attempts":3,"dropReasoning":0,"dropText":0,"dropTools":0,"message":"..."}
+ *                                                                   本步自动重试：前端据 drop* 回滚已渲染的半截产物
+ *   data: {"type":"stream-alive"}                                     收到字节但无增量（长思考 / 网关缓冲工具参数），前端据此判断连接是否还活着
  *   data: {"type":"context-usage","used":12345,"total":96000,"window":65536}   每轮上下文占用（输入框圆环）
+ *   data: {"type":"usage","step":3,"promptTokens":123456,"cachedTokens":98765,"cacheMissTokens":24691,"hitRate":80.0,"reported":true}
+ *                                                                   累计用量与**前缀缓存命中率**：网关不报缓存字段时 reported=false（界面显示「未提供」）
  *   data: {"type":"turn-ended","reason":"loop|timeout|steps","message":"..."} 熔断收尾原因（前端落进对话记录，持久可见）
- *   data: {"type":"error","message":"..."}
+ *   data: {"type":"error","message":"...","code":"length|stall|empty|context|network|auth|wrap-failed|aborted|unknown"}
+ *                                                                   前端按 code 给定向动作（打开设置 / 重试本轮 / 复制错误）
  *   data: {"type":"aborted"}
  *   data: {"type":"done"}
  */
@@ -51,6 +67,20 @@ import fs from 'node:fs'
 import os from 'node:os'
 import { execFile, spawn, spawnSync } from 'node:child_process'
 import { SNAPSHOT_ROOT, skillsDirFor, resolveSkillPath, normalizeSkillRel } from './skillPaths.js'
+// 对话记录落盘（.cache/ai-chats/<cardId>.json）：读写清 + 删卡联动都在 chatHistory.js，
+// 本文件只负责 HTTP 端点编排，路径约定不再在这里重复一份。
+import {
+  chatHistoryDir,
+  safeCardId,
+  readHistory,
+  writeHistory,
+  deleteHistory,
+  listHistories,
+  mergeServerTurn,
+} from './chatHistory.js'
+// 回合日志（P2）：事件流按 seq 落盘 .cache/ai-turns/<cardId>.jsonl —— 断线续跑的回放源、
+// 收尾时 reduce 成服务端权威历史；客户端崩溃 / 关标签页不再丢整轮轨迹。
+import { openJournal, getLiveJournal, readJournalLines, listTurns, deleteJournal } from './turnJournal.js'
 
 /**
  * 快照根：仓库内运行 = 真仓库根；cardbuddy 发布态 = 包内 dist/vendored（构建期内联的迷你仓库快照，
@@ -59,8 +89,31 @@ import { SNAPSHOT_ROOT, skillsDirFor, resolveSkillPath, normalizeSkillRel } from
  */
 const REPO_ROOT = SNAPSHOT_ROOT
 
-/** 单卡片最多保留的消息条数，超出从头部裁剪（避免历史无限增长撑爆上下文与磁盘） */
-const MAX_HISTORY_MESSAGES = 200
+// ---- 提示词前缀缓存纪律（prompt cache） ------------------------------------------------------
+/**
+ * 网关的前缀缓存（DeepSeek / GLM 系都是「完全相同的前缀 + 64 token 块对齐」才有折扣）只认逐字节
+ * 相同的前缀：只要我们**改写了历史里的任何一条消息**，从那条起往后的全部 token 都要按原价重算。
+ * 实测（tools/tests 之外的线上探针）：同一个 570 token 前缀第二次请求命中 384 token（67%），
+ * 命中量正好是 64 的整数倍 —— 所以「别动历史」比「少带点内容」值钱得多。
+ *
+ * 由此定下三条纪律，后面所有逻辑都得遵守：
+ *  ① 同一个东西只有一个截断口径（TOOL_RESULT_MAX_CHARS）——轮内 live 上下文与下一回合前端回传的
+ *     历史必须是同一串字符，否则每过一轮前缀就在「第一个超长工具结果」处整段漂移。
+ *  ② 历史只追加、不回改：裁剪只能从「上次折到哪」继续往后折（粘滞），不允许把已折叠的还原、
+ *     也不允许为了省 token 回头改写更早的消息。
+ *  ③ 真发生改写时要留痕（prefixDrift）：命中率掉下来得能一眼看出是哪一步、哪一条开始漂的。
+ */
+const TOOL_RESULT_MAX_CHARS = 12000
+
+/**
+ * 让网关在流末尾回 usage（OpenAI 兼容网关默认**不回**）：没有 usage 就看不到缓存命中量，
+ * 「提高命中率」只能是空话。实测本仓两个网关都接受该字段（其中一个还会回
+ * prompt_cache_hit_tokens / prompt_tokens_details.cached_tokens）。
+ * 不认识的网关会 400 —— 由 callLLM 的扩展字段回退逻辑逐个摘掉后重试，不会把整轮打成失败。
+ */
+const USAGE_BODY = { stream_options: { include_usage: true } }
+/** 网关拒绝扩展字段时的摘除顺序：先摘观测字段（无副作用），再摘思考开关（有行为影响） */
+const EXT_PEEL_ORDER = ['stream_options', 'chat_template_kwargs']
 
 // ---- 工具定义（延迟加载） ----
 let _toolsCache = null
@@ -197,6 +250,12 @@ S1 要素包：kind=meaxure-export（Sketch MeaXure 标注导出）必须先有
      ② args=["--src","<导出目录>","--out","UI","--draft","<稿名>","--indices","<n>","--build"] 只产该画板（多个逗号；按名称子串用 "--only","<子串>"）；
      ③ script=skills/sketch-spec-to-card/scripts/cluster_states.py，args=["--out","UI/<稿名>"]。
    - 要素包落点记作 <bundle>：传了 --draft 在 UI/<稿名>/<画板名>/，否则 UI/<画板名>/；以 parse_meaxure.py 打印的落盘路径为准。仓库可能两种布局并存，manifest 说的画板在 UI/ 下找不到就用 fs_list UI 找同名目录，别急着判定产物缺失。
+S1.5 选卡门禁（多画板 / 多卡画板必需；SKILL.md §13 + rules.md §13.4）：目标目录定下后先跑 skill_exec script=skills/dsl-card-generator/scripts/spec_tree.mjs，args=["--list-cards","<目标目录>"] 拿「画板序号.卡片序号」全量清单（一个画板含 N 张卡展开为 K.1~K.N，行下自带 "图: <card-N.png 绝对路径>"）；S0 挂载段已带同一份命令就直接复用，不要重复跑。
+   - 只有 1 张卡、或用户已明说目标（序号如 2.3 / 画板名 / 卡片名）⇒ 直接进 S2，不要为走流程停下来问。
+   - 多张卡且用户未指定 ⇒ **本轮到此为止**：把清单写进正文 + 明确提问，然后**停止输出、等用户回序号再继续**。聊天面板**没有**弹选项工具（不存在 request_user_input），不要去调用或寻找弹窗工具，也不要替用户挑。
+     清单**逐行配图**：每个卡片行下紧跟它自己的聚焦图——把 "图:" 那行的绝对路径原样写成内联 Markdown 图片（让它直接显示出来，**不要只贴路径**），与序号一一对应；缺图显式标缺失，禁止把图堆到清单末尾。末尾追加一项「全部」，用户回「全部」才算显式批量授权（产了几张卡要在正文报）。
+     只回画板序号默认取该画板第 1 张卡。
+   - **禁止**自行挑画板 / 挑卡、**禁止**「先建一张看看」、**禁止**未经同意批量产卡。
 S2 审计（一步代替反复探索）：skill_exec script=skills/dsl-card-generator/scripts/spec_audit.mjs，args=["--spec","<bundle>/spec.json","--card","N","--slices-dir","<bundle>/slices","--project-slices","src/slices","--design","<bundle>/card-N.png","--save",".cache/ai-scratch/<id>.audit.json"]。
    它交叉审计 spec + 聚焦截图 + 切图目录，给出：bands（水平行与行内元素序）、gaps（padLeft / padRight / padTop / padBottom / rowGaps）、texts（文案 / 字号 / 字重 / 颜色 / 行高 / 对齐）、shapes（装饰条）、slices（存在性 / 复用 / 是否烘焙背景与标签文字）、colors（背景采样点）、missing（缺哪张切图 + 建议裁剪矩形）。
    它交叉审计 spec + 聚焦截图 + 切图目录，另给 bgGradientHint（顶部渐变带的起止色/跨度 + IR 正确写法）与 slices[].crops（reused-differs 时「矩形 → 该用哪张 _alt 图」的映射，exists=true 直接引用、false 才需裁）。
@@ -229,6 +288,13 @@ S6 收尾门禁：① skill_exec script=skills/dsl-card-generator/scripts/check_
 ${vision ? '你有视觉能力：S5 里 match 不达标可直接读注入的并排对比图定位差异（哪一行 / 哪个颜色 / 哪段间距）再 --set；数值指标仍是收敛判据，图只用于定位。' : '当前模型无视觉：不要声称看过图；S2 的审计值 + S5 的数值指标就是你的眼睛，所有尺寸颜色文案取审计值，缺时按 references/ui_fidelity_rules.md 降级规则处理，禁止凭空估数值。'}
 步数不设硬顶（除非用户在设置里配了上限），但有四道闸：①连续多轮「同工具 + 同参数」会被判定原地打转并强制收尾 ②单轮墙钟到点会强制收尾 ③每 24 步会收到一次收敛提醒 ④单轮上下文超预算时**早期工具结果会被折叠成摘要**并标注「已折叠」——看到折叠标记就用工具重读，不要拿摘要当结论。所以别把额度当免费：S2 / S3 / S5 各尽量一次调用解决；同类信息只读一次；收到重复调用警告就立刻换证据链（diff_bands.mjs / generation_pitfalls.md），不要把同一条调用原样再发一次；被中止过的轮次按上下文里的中止标记从中断处继续，不要从零重做。
 
+## 收尾协议（不要停下来等「继续」）
+- 任务没做完就不要交还控制权：接着调用工具推进到下一个门禁。**禁止**输出「下一步（请确认或直接说「继续」）」这类等待式收尾——用户已开启自动续跑，停手只会让任务白等一轮。
+- 只有两种情况允许「不调工具、只吐正文」结束本轮：①用户的要求已全部落地且门禁通过 ⇒ 正文最后单独一行 ${DONE_MARK}；②确实缺只有用户能给的信息（缺密钥 / 需求二义 / 要动工程外文件）⇒ 正文最后单独一行 ${ASK_MARK}，并写清要用户回答什么。
+- 两个标记都要逐字原样输出，且只在真正满足条件时用：没有标记又没调用工具，会被判定为「未完成却停手」并自动注入提醒续跑。
+- 中途被网关静默重试 / 思考催促打断过的步骤，按上下文里的提醒从中断处接着做，不要从零重做，也不要重复已经落盘的工作。
+- 别因为「怕超时」就把活儿切成「下一轮再做」：网关瞬时静默会自动重试本步、纯思考超时只会收到催促而不会中断任务、墙钟默认 60 分钟——一次把该跑的工具跑完，比拆成几轮等用户说「继续」又快又省。
+
 ## 按需参考索引（skill_read）
 ${lines.join('\n')}`
   _systemPromptCache = { key: cacheKey, text: _text }
@@ -1194,7 +1260,14 @@ async function runGuarded(root, res, { toolName, command, approved, auto = false
   }
   const approvalId = `ap_${Date.now().toString(36)}${Math.random().toString(36).slice(2, 8)}`
   const decision = await waitForApproval(res, { approvalId, toolName, command: label, args: { command: label } })
-  sseWrite(res, { type: 'approval-decided', approvalId, ok: decision.ok, scope: decision.scope })
+  // reason：审批超时（APPROVAL_TIMEOUT_MS）时带「超过 N 秒未确认，按拒绝处理」，前端据此区分「用户点了拒绝」与「走神超时」
+  sseWrite(res, {
+  type: 'approval-decided',
+  approvalId,
+  ok: decision.ok,
+  scope: decision.scope,
+  reason: decision.reason || '',
+  })
   if (!decision.ok) {
     auditShell(root, label, false)
     throw new Error(decision.reason || '用户拒绝了这次执行：请把命令原样写给用户自行运行，或改用结构化卡片工具')
@@ -1351,6 +1424,29 @@ function parseEnvFile(file) {
 const DEFAULT_TURN_TIMEOUT_MS = 60 * 60 * 1000
 /** 连续多少轮完全相同的工具调用即判定死循环（第 2 轮先警告，第 3 轮熔断） */
 const LOOP_BREAK_REPEATS = 3
+/**
+ * 保活三阈值：长程任务（设计稿建卡一轮几十次调用、几十分钟）只应被「用户主动中止」或
+ * 「模型服务明确报错」结束，网关瞬时抖动与模型长时间思考都不该整轮报废。
+ *   - stallTimeoutMs：上游一个字节都不回多久算「网关静默」（静默后自动重试本步，不是报错收尾）
+ *   - stallRetries：网关静默的自动重试次数，耗尽才报错
+ *   - reasoningTimeoutMs：单轮「纯思考」（只吐 reasoning、无正文无工具）多久算迟迟不产出，
+ *     到点先催促 + 关思考重试；催促若干次仍无产出就**停用该熔断**改由墙钟兜底，不再中断任务
+ */
+const DEFAULT_STALL_TIMEOUT_MS = 120 * 1000
+const DEFAULT_STALL_RETRIES = 3
+const DEFAULT_REASONING_TIMEOUT_MS = 600 * 1000
+/** 纯思考催促上限：超过后停用思考熔断（继续跑，交给墙钟 / 死循环熔断兜底） */
+const REASONING_NUDGE_MAX = 3
+/**
+ * 收尾协议标记：模型只有显式给出其中之一，才允许「不调工具、只吐正文」就把控制权交回用户。
+ * 实测没有协议时模型极爱输出「下一步（请确认或直接说「继续」）」——任务根本没做完（IR 写了但
+ * expand_ir 没跑、门禁没过），却把用户变成「继续」按钮。没有标记就自动续跑。
+ */
+const DONE_MARK = '[任务完成]'
+const ASK_MARK = '[需用户确认]'
+const TASK_SETTLED_RE = /\[\s*(?:任务完成|需用户确认)\s*\]/
+/** 单轮自动续跑上限（AI_AUTO_CONTINUE 可覆盖，0 = 关闭回到「等用户说继续」） */
+const DEFAULT_AUTO_CONTINUE_MAX = 12
 
 /** 时长人话：分钟为主，亚分钟（测试里常把墙钟压到几十毫秒）回落秒，别显示「0 分钟」 */
 function fmtDuration(ms) {
@@ -1409,25 +1505,56 @@ function readAiConfig(root = REPO_ROOT) {
     const isRealOverride = fromProcess !== undefined && fromProcess !== injected[key] && fromProcess !== shared[key]
     return String(isRealOverride ? fromProcess : (local[key] || shared[key] || ''))
   }
+  // 「模型身份 + 能力」字段唯一来源 = 模型库 AI_MODELS 中的生效项（不再在库外另存一份扁平键）。
+  // 若环境变量显式覆盖了该键（CI / 命令行导出），以真实覆盖为准；否则完全跟随模型库。
+  // 模型库为空（老用户未迁移）时回落扁平键，保持向后兼容。
+  let activeModel = null
+  try {
+    const { models, activeId } = readAiModels(root)
+    activeModel = models.find((m) => m.id === activeId) || models[0] || null
+  } catch {
+    activeModel = null
+  }
+  const fromModel = (key, flatKey) => {
+    const realEnv = process.env[key]
+    const isRealOverride = realEnv !== undefined && realEnv !== injected[key] && realEnv !== shared[key]
+    if (isRealOverride) return String(realEnv)
+    if (activeModel) return activeModel[key]
+    return local[flatKey] || shared[flatKey] || ''
+  }
   return {
-    baseUrl: pick('AI_BASE_URL'),
-    apiKey: pick('AI_API_KEY'),
-    model: pick('AI_MODEL'),
+    baseUrl: String(fromModel('baseUrl', 'AI_BASE_URL') || ''),
+    apiKey: String(fromModel('apiKey', 'AI_API_KEY') || ''),
+    model: String(fromModel('model', 'AI_MODEL') || ''),
     // 本地命令执行开关（默认开）：shell_exec 工具默认注册；是否逐次确认由 AI_AUTO_APPROVE 决定（默认 all=免确认）。
     // 显式 AI_ALLOW_SHELL=0 才关闭（本工具只监听 127.0.0.1，且命令过白名单 + 全量审计）
     shellAllowed: pick('AI_ALLOW_SHELL') !== '0',
-    // 单次输出上限（0 = 用默认值）：推理模型的思考也算 completion，太小会被截断
-    maxTokens: Number(pick('AI_MAX_TOKENS')) > 0 ? Number(pick('AI_MAX_TOKENS')) : 0,
-    // 深度思考开关（默认开）：关掉可显著提速，但仅在 vLLM / SGLang 系网关生效
-    thinking: pick('AI_THINKING') !== '0',
-    // 多模态视觉开关（默认关）：开启后先探测网关是否真支持图像，不支持自动降级数值闭环
-    vision: pick('AI_VISION') === '1',
+    // 单次输出上限（0 = 用默认值）：模型能力参数，跟随生效模型
+    maxTokens: Number(fromModel('maxTokens', 'AI_MAX_TOKENS')) > 0 ? Number(fromModel('maxTokens', 'AI_MAX_TOKENS')) : 0,
+    // 深度思考开关（默认开）：模型能力开关，跟随生效模型
+    thinking: activeModel ? activeModel.thinking !== false : pick('AI_THINKING') !== '0',
+    // 多模态视觉开关（默认关）：模型能力开关，跟随生效模型
+    vision: activeModel ? activeModel.vision === true : pick('AI_VISION') === '1',
     // 免确认执行策略（默认 all）：建卡管线连跑十几次脚本 / 命令，不该每次都等用户点「允许」
     autoApprove: normalizeAutoApprove(pick('AI_AUTO_APPROVE')),
     // 单轮工具调用步数硬顶（0 = 不限，默认）：>0 时到顶收尾汇报并提示「继续」，上下文不丢
     maxSteps: Number(pick('AI_MAX_STEPS')) > 0 ? Number(pick('AI_MAX_STEPS')) : 0,
     // 单轮墙钟上限（毫秒）：不限步数后唯一能兜住「无限跑下去」的闸门，到点收尾汇报而非无声挂着
     turnTimeoutMs: Number(pick('AI_TURN_TIMEOUT_MS')) > 0 ? Number(pick('AI_TURN_TIMEOUT_MS')) : DEFAULT_TURN_TIMEOUT_MS,
+    // 保活三阈值（env 可调，此前只能靠请求体传，磁盘配置改了也不生效）
+    stallTimeoutMs: Number(pick('AI_STALL_TIMEOUT_MS')) > 0 ? Number(pick('AI_STALL_TIMEOUT_MS')) : DEFAULT_STALL_TIMEOUT_MS,
+    // AI_STALL_RETRIES=0 显式关闭静默重试（回到「一次静默即报错」的旧行为）
+    stallRetries:
+      pick('AI_STALL_RETRIES') === ''
+        ? DEFAULT_STALL_RETRIES
+        : Math.max(0, Math.min(20, Number(pick('AI_STALL_RETRIES')) || 0)),
+    reasoningTimeoutMs:
+      Number(pick('AI_REASONING_TIMEOUT_MS')) > 0 ? Number(pick('AI_REASONING_TIMEOUT_MS')) : DEFAULT_REASONING_TIMEOUT_MS,
+    // 自动续跑：模型没给完成标记就停手时自动注入提醒接着跑的次数上限（0 = 关闭，回到「等用户说继续」）
+    autoContinueMax:
+      pick('AI_AUTO_CONTINUE') === ''
+        ? DEFAULT_AUTO_CONTINUE_MAX
+        : Math.max(0, Math.min(200, Number(pick('AI_AUTO_CONTINUE')) || 0)),
   }
 }
 
@@ -1438,40 +1565,41 @@ function maskKey(key) {
   return `${'*'.repeat(Math.min(8, key.length - 4))}${key.slice(-4)}`
 }
 
-/**
- * 保存 AI 配置到 .env.cb.local（个人覆盖层，.gitignore 已忽略，密钥不入库）。
- * 只写传入且非 undefined 的键；apiKey 传空串表示清除本地覆盖。
- * 未传的键**保持原值原样重写**：早先的实现会把没传的键从个人覆盖层删掉，
- * 于是「手写 env 只改一项」或「局部 POST」会连带清掉别的配置（与本文档相悖，实测 AI_ALLOW_SHELL 被抹掉）。
- */
+/** 全局公共配置（执行策略 / 环境）：allowShell / autoApprove / maxSteps / 各类超时 / 重试 / 续跑。
+ *  这些键与「模型身份」无关，所有模型共享一份；与 writeAiModelsLocal 管理的模型专属键(AI_BASE_URL 等)互不重叠。
+ *  只写传入且非 undefined 的键；未传的键保持原值原样重写（避免局部保存抹掉别的配置）。 */
 function writeAiConfigLocal(
   root = REPO_ROOT,
-  { baseUrl, apiKey, model, allowShell, maxTokens, thinking, vision, autoApprove, maxSteps } = {},
+  { allowShell, autoApprove, maxSteps, turnTimeoutMs, stallTimeoutMs, stallRetries, reasoningTimeoutMs, autoContinueMax } = {},
 ) {
   const envPath = path.join(root, '.env.cb.local')
   const lines = fs.existsSync(envPath) ? fs.readFileSync(envPath, 'utf8').split('\n') : []
   const KEYS = [
-    'AI_BASE_URL',
-    'AI_API_KEY',
-    'AI_MODEL',
     'AI_ALLOW_SHELL',
-    'AI_MAX_TOKENS',
-    'AI_THINKING',
-    'AI_VISION',
     'AI_AUTO_APPROVE',
     'AI_MAX_STEPS',
+    'AI_TURN_TIMEOUT_MS',
+    'AI_STALL_TIMEOUT_MS',
+    'AI_STALL_RETRIES',
+    'AI_REASONING_TIMEOUT_MS',
+    'AI_AUTO_CONTINUE',
   ]
+  const clamp = (v, lo, hi, dflt) => {
+    const n = Number(v)
+    if (!Number.isFinite(n) || n < 0) return dflt
+    return String(Math.max(lo, Math.min(hi, n)))
+  }
   const incoming = {
-    AI_BASE_URL: baseUrl,
-    AI_API_KEY: apiKey,
-    AI_MODEL: model,
     AI_ALLOW_SHELL: allowShell === undefined ? undefined : allowShell ? '1' : '0',
-    // 传空串 / 0 = 清除本地覆盖，回到内置默认
-    AI_MAX_TOKENS: maxTokens === undefined ? undefined : String(Number(maxTokens) > 0 ? Number(maxTokens) : ''),
-    AI_THINKING: thinking === undefined ? undefined : thinking ? '1' : '0',
-    AI_VISION: vision === undefined ? undefined : vision ? '1' : '0',
     AI_AUTO_APPROVE: autoApprove === undefined ? undefined : normalizeAutoApprove(autoApprove),
+    // 传空串 / 0 = 清除本地覆盖，回到内置默认
     AI_MAX_STEPS: maxSteps === undefined ? undefined : String(Number(maxSteps) > 0 ? Number(maxSteps) : ''),
+    AI_TURN_TIMEOUT_MS: turnTimeoutMs === undefined ? undefined : String(Number(turnTimeoutMs) > 0 ? Number(turnTimeoutMs) : ''),
+    AI_STALL_TIMEOUT_MS: stallTimeoutMs === undefined ? undefined : String(Number(stallTimeoutMs) > 0 ? Number(stallTimeoutMs) : ''),
+    // -1/空串 = 用内置默认；>=0 才是真实生效值
+    AI_STALL_RETRIES: stallRetries === undefined ? undefined : (Number(stallRetries) < 0 ? '' : clamp(stallRetries, 0, 20, '')),
+    AI_REASONING_TIMEOUT_MS: reasoningTimeoutMs === undefined ? undefined : String(Number(reasoningTimeoutMs) > 0 ? Number(reasoningTimeoutMs) : ''),
+    AI_AUTO_CONTINUE: autoContinueMax === undefined ? undefined : (Number(autoContinueMax) < 0 ? '' : clamp(autoContinueMax, 0, 200, '')),
   }
 
   // 文件里已有的受管键值：incoming 为 undefined 时按原值重写，实现「只改传入的键」
@@ -1514,6 +1642,208 @@ function writeAiConfigLocal(
   }
 }
 
+/**
+ * 模型库：把「多个模型配置」存进 .env.cb.local 的 AI_MODELS（JSON 数组），
+ * 当前生效模型以 AI_MODEL_ACTIVE 记录其 id。为兼容既有 chat / 探测 / ping
+ * （它们只读扁平 AI_*），每次写模型库都会把「生效模型」重新投影成扁平 AI_*，
+ * readAiConfig 无需改动即可继续工作。
+ *
+ * 迁移：首次打开（无 AI_MODELS）但旧版有单条扁平配置时，合入一条名为该 model 的默认模型，
+ * 避免老用户看到空列表、且旧配置不丢。
+ */
+function genModelId() {
+  return 'm' + Date.now().toString(36) + Math.random().toString(36).slice(2, 8)
+}
+
+/** 单条模型结构归一（缺省值兜底），不在此处做掩码。
+ *  仅存「模型身份 + 能力」字段；执行策略（allowShell / autoApprove / maxSteps / 各类超时 / 重试 / 续跑）是全局公共配置，见 writeAiConfigLocal，不随模型复制。 */
+function normalizeModel(m = {}) {
+  return {
+    id: String(m.id || genModelId()),
+    name: String(m.name || m.model || '未命名模型'),
+    baseUrl: String(m.baseUrl || ''),
+    apiKey: String(m.apiKey || ''),
+    model: String(m.model || ''),
+    // 单次输出上限（0 = 自动，按网关窗口协商）：不同模型窗口不同，属模型能力参数
+    maxTokens: Number(m.maxTokens) > 0 ? Number(m.maxTokens) : 0,
+    // 深度思考 / 多模态视觉：模型能力开关，随模型走
+    thinking: m.thinking === true || m.thinking === '1',
+    vision: m.vision === true || m.vision === '1',
+    createdAt: Number(m.createdAt) > 0 ? Number(m.createdAt) : Date.now(),
+    updatedAt: Number(m.updatedAt) > 0 ? Number(m.updatedAt) : Date.now(),
+  }
+}
+
+/** 读取模型库：{ models, activeId }（models 为脱敏前的完整结构） */
+function readAiModels(root = REPO_ROOT) {
+  const shared = parseEnvFile(path.join(root, '.env.cb'))
+  const local = parseEnvFile(path.join(root, '.env.cb.local'))
+  const get = (k) => (local[k] !== undefined ? local[k] : shared[k] !== undefined ? shared[k] : '')
+  let models = []
+  let rawExists = false
+  const raw = get('AI_MODELS')
+  if (raw) {
+    rawExists = true
+    try {
+      const parsed = JSON.parse(raw)
+      if (Array.isArray(parsed)) models = parsed
+      if (!Array.isArray(parsed)) rawExists = false
+    } catch {
+      models = []
+      rawExists = false
+    }
+  }
+  if (!Array.isArray(models)) models = []
+  // 迁移：旧版单条扁平配置 → 一条默认模型（只搬「模型身份 + 能力」；执行策略类公共键留在全局扁平键，readAiConfig 照常读）。
+  // 仅当 AI_MODELS 从未写过（rawExists=false）时才迁移：否则「用户删空模型库」会被遗留扁平键复活成一条「幽灵模型」。
+  if (!rawExists && !models.length && get('AI_MODEL')) {
+    models = [{
+      id: 'default',
+      name: get('AI_MODEL'),
+      baseUrl: get('AI_BASE_URL'),
+      apiKey: get('AI_API_KEY'),
+      model: get('AI_MODEL'),
+      maxTokens: Number(get('AI_MAX_TOKENS')) > 0 ? Number(get('AI_MAX_TOKENS')) : 0,
+      thinking: get('AI_THINKING') !== '0',
+      vision: get('AI_VISION') === '1',
+      createdAt: Date.now(),
+      updatedAt: Date.now(),
+    }]
+  }
+  models = models.map((m) => normalizeModel(m))
+  let activeId = get('AI_MODEL_ACTIVE') || (models[0] ? models[0].id : null)
+  if (!models.some((m) => m.id === activeId)) activeId = models[0] ? models[0].id : null
+  return { models, activeId }
+}
+
+/** 模型输入校验（后端兜底）：返回错误文案（不合法）或 null（合法）。
+ *  requireKey=true 时 apiKey 必填（新增 / 编辑时清空了密钥）。 */
+function validateModelInput(body = {}, { requireKey = false } = {}) {
+  const baseUrl = String(body.baseUrl || '').trim()
+  const model = String(body.model || '').trim()
+  if (!baseUrl) return 'Base URL 不能为空'
+  if (!/^https?:\/\/[^\s]+$/i.test(baseUrl)) return 'Base URL 需以 http:// 或 https:// 开头'
+  if (!model) return '模型名不能为空'
+  if (requireKey && !String(body.apiKey || '').trim()) return 'API Key 不能为空'
+  return null
+}
+
+/** 模型脱敏：列表 / 详情默认不回明文 key */
+function maskModel(m) {
+  return {
+    ...m,
+    apiKey: undefined,
+    hasKey: Boolean(m.apiKey),
+    apiKeyMasked: maskKey(m.apiKey),
+  }
+}
+
+/** 模型专属扁平键（旧式配置遗留）：模型库非空时由 AI_MODELS 取代，写入时一并清除，避免「库里一份、外面一份」。
+ *  仅当模型库为空（未迁移 / 用户手写）时才作为回退来源。 */
+const LEGACY_MODEL_FLAT_KEYS = [
+  'AI_BASE_URL', 'AI_API_KEY', 'AI_MODEL', 'AI_MAX_TOKENS', 'AI_THINKING', 'AI_VISION',
+]
+
+/** 写模型库到 .env.cb.local：只写 AI_MODELS(JSON) + AI_MODEL_ACTIVE。
+ *  模型身份 / 能力字段**只存于库内**，不再在库外投影扁平键（避免双份配置漂移）；
+ *  清掉遗留的 AI_BASE_URL 等扁平键（AI_ALLOW_SHELL / AI_AUTO_APPROVE 等执行策略类公共键不在此列，由 writeAiConfigLocal 管理）。
+ *  其它个人配置（非受管键）原样保留。 */
+function writeAiModelsLocal(root, models, activeId) {
+  const envPath = path.join(root, '.env.cb.local')
+  const lines = fs.existsSync(envPath) ? fs.readFileSync(envPath, 'utf8').split('\n') : []
+  const MANAGED = new Set([...LEGACY_MODEL_FLAT_KEYS, 'AI_MODELS', 'AI_MODEL_ACTIVE'])
+
+  const kept = lines.filter((l) => {
+    const t = l.trim()
+    if (!t || t.startsWith('#')) return true
+    const i = t.indexOf('=')
+    if (i < 0) return true
+    return !MANAGED.has(t.slice(0, i).trim())
+  })
+  while (kept.length && !kept[kept.length - 1].trim()) kept.pop()
+
+  const block = []
+  if (!kept.some((l) => l.startsWith('# AI 开发助手'))) {
+    block.push('# AI 开发助手模型配置（CardBuddy 设置面板写入；本文件为个人覆盖层，勿提交）')
+  }
+  block.push(`AI_MODELS=${JSON.stringify(models)}`)
+  block.push(`AI_MODEL_ACTIVE=${activeId || ''}`)
+
+  const out = [...kept, ...(kept.length ? [''] : []), ...block]
+  fs.writeFileSync(envPath, out.join('\n') + '\n', 'utf8')
+
+  // 清掉 dotenv 注入的旧扁平值，确保 readAiConfig 以文件 / 模型库实时读取为准
+  for (const k of LEGACY_MODEL_FLAT_KEYS) delete process.env[k]
+}
+
+/**
+ * 从 cc-switch（~/.cc-switch/cc-switch.db，SQLite）读取 Codex 类 provider 列表，
+ * 解析其 settings_config（JSON）里的 config（TOML 文本）+ auth（含密钥），提取 baseUrl / apiKey / model，
+ * 映射成本仓库模型库所需的 { name, baseUrl, apiKey, model } 结构。
+ * 只读 + 短事务（WAL 并发安全）；DB 不存在 / sqlite3 CLI 不可用时返回空列表 + reason。
+ * @returns {{ providers: Array, reason?: string }}
+ *  providers: [{ id, name, baseUrl, apiKey, model, isCurrent, wireApi }]
+ */
+function listCcSwitchProviders() {
+  const dbPath = path.join(os.homedir(), '.cc-switch', 'cc-switch.db')
+  if (!fs.existsSync(dbPath)) {
+    return { providers: [], reason: '未检测到 cc-switch 数据库（~/.cc-switch/cc-switch.db），请确认已安装并运行过 cc-switch' }
+  }
+  let raw
+  try {
+    const r = spawnSync('sqlite3', ['-json', dbPath,
+      `SELECT id, name, settings_config, is_current FROM providers WHERE app_type='codex' ORDER BY is_current DESC, sort_index`],
+      { encoding: 'utf8', timeout: 5000 })
+    if (r.error || r.status !== 0) {
+      const msg = r.error ? String(r.error.message) : (r.stderr || '').trim()
+      return { providers: [], reason: `sqlite3 执行失败${msg ? '：' + msg : ''}（macOS 自带 sqlite3，若环境异常请检查 PATH）` }
+    }
+    raw = (r.stdout || '').trim()
+  } catch (e) {
+    return { providers: [], reason: `读取 cc-switch 数据库异常：${String((e && e.message) || e)}` }
+  }
+  let rows
+  try {
+    rows = raw ? JSON.parse(raw) : []
+  } catch {
+    return { providers: [], reason: 'cc-switch 数据库返回格式异常（无法解析 JSON）' }
+  }
+  if (!Array.isArray(rows) || !rows.length) {
+    return { providers: [], reason: 'cc-switch 中尚未配置任何 Codex 类供应商' }
+  }
+  const providers = []
+  for (const row of rows) {
+    let sc
+    try {
+      sc = JSON.parse(row.settings_config || '{}')
+    } catch {
+      continue
+    }
+    const apiKey = String((sc.auth && sc.auth.OPENAI_API_KEY) || '').trim()
+    const toml = String(sc.config || '')
+    // TOML 是固定格式，用正则提取 model 与 base_url 即可（避免引入 TOML 解析依赖）
+    const modelMatch = toml.match(/^\s*model\s*=\s*"([^"]+)"/m)
+    const baseUrlMatch = toml.match(/^\s*base_url\s*=\s*"([^"]+)"/m)
+    const wireMatch = toml.match(/^\s*wire_api\s*=\s*"([^"]+)"/m)
+    let baseUrl = (baseUrlMatch && baseUrlMatch[1]) || ''
+    // Codex 网关常把 base_url 拼成 .../chat/completions，本仓库调用的是 ${baseUrl}/chat/completions，
+    // 导入时剥掉末尾的 /chat/completions（及尾部斜杠），避免拼出双段路径
+    baseUrl = baseUrl.replace(/\/chat\/completions\/?$/i, '').replace(/\/+$/, '')
+    const model = (modelMatch && modelMatch[1]) || ''
+    if (!baseUrl || !model) continue
+    providers.push({
+      id: String(row.id || ''),
+      name: String(row.name || model),
+      baseUrl,
+      apiKey,
+      model,
+      isCurrent: row.is_current === 1 || row.is_current === true,
+      wireApi: (wireMatch && wireMatch[1]) || '',
+    })
+  }
+  return { providers }
+}
+
 // ---- 请求体 / 响应辅助 ----
 
 function readBody(req, limitBytes = 8 * 1024 * 1024) {
@@ -1578,89 +1908,47 @@ function sendJson(req, res, code, payload) {
 }
 
 function sseWrite(res, obj) {
-  if (res.writableEnded || res.destroyed) return
-  res.write(`data: ${JSON.stringify(obj)}\n\n`)
-}
-
-// ---- 对话记录落盘 ----
-
-function safeCardId(cardId) {
-  const id = String(cardId || '').trim()
-  if (!id) return ''
-  // 只允许文件名安全字符，杜绝 ../ 路径穿越
-  return id.replace(/[^A-Za-z0-9._-]/g, '_').slice(0, 120)
-}
-
-function historyFile(chatDir, cardId) {
-  const id = safeCardId(cardId)
-  return id ? path.join(chatDir, `${id}.json`) : ''
-}
-
-function readHistory(chatDir, cardId) {
-  const file = historyFile(chatDir, cardId)
-  if (!file || !fs.existsSync(file)) return { cardId: String(cardId || ''), messages: [], updatedAt: 0 }
-  try {
-    const raw = JSON.parse(fs.readFileSync(file, 'utf8'))
-    return {
-      cardId: String(raw.cardId || cardId || ''),
-      messages: Array.isArray(raw.messages) ? raw.messages : [],
-      updatedAt: Number(raw.updatedAt || 0),
-    }
-  } catch {
-    return { cardId: String(cardId || ''), messages: [], updatedAt: 0 }
+  let payload = obj
+  const journal = res.__turnJournal
+  if (journal && !journal.closed) {
+    const line = journal.append(obj)
+    // seq 随事件下发：客户端重连时按它向 /__ai/turn 要「断点之后」的事件，不重不漏
+    if (line) payload = { ...obj, seq: line.seq }
   }
+  if (res.writableEnded || res.destroyed) return
+  res.write(`data: ${JSON.stringify(payload)}\n\n`)
 }
 
-function writeHistory(chatDir, cardId, messages) {
-  const file = historyFile(chatDir, cardId)
-  if (!file) return { ok: false, error: 'missing-card-id' }
-  fs.mkdirSync(chatDir, { recursive: true })
-  const list = Array.isArray(messages) ? messages.slice(-MAX_HISTORY_MESSAGES) : []
-  const payload = { cardId: safeCardId(cardId), messages: list, updatedAt: Date.now() }
-  const tmp = `${file}.tmp`
-  fs.writeFileSync(tmp, JSON.stringify(payload), 'utf8')
-  fs.renameSync(tmp, file)
-  return { ok: true, count: list.length, updatedAt: payload.updatedAt }
+/** 回放日志行给续订连接：行本身已带 seq，不再进日志（否则回放一次 seq 翻倍） */
+function sseRaw(res, line) {
+  if (res.writableEnded || res.destroyed) return
+  res.write(`data: ${JSON.stringify(line)}\n\n`)
 }
 
-function deleteHistory(chatDir, cardId) {
-  const file = historyFile(chatDir, cardId)
-  if (!file) return { ok: false, error: 'missing-card-id' }
-  try {
-    if (fs.existsSync(file)) fs.unlinkSync(file)
-  } catch (e) {
-    return { ok: false, error: String((e && e.message) || e) }
-  }
-  return { ok: true }
+/**
+ * notice 的统一出口：除文案外附带严重级（info / warn / error）与机器码。
+ * level 供前端决定横幅配色与是否打扰，code 供前端做定向提示；两字段都可缺省（旧前端只读 message 照常工作）。
+ * 所有 notice 前端都会落进该条消息的「过程事件」时间线并随对话记录落盘，不再阅后即焚。
+ */
+function sseNotice(res, message, level = 'warn', code = '') {
+  sseWrite(res, { type: 'notice', message, level, code })
 }
 
-/** 历史卡片清单（面板「最近对话」用，按更新时间倒序） */
-function listHistories(chatDir, limit = 30) {
-  try {
-    if (!fs.existsSync(chatDir)) return []
-    return fs
-      .readdirSync(chatDir)
-      .filter((f) => f.endsWith('.json'))
-      .map((f) => {
-        try {
-          const raw = JSON.parse(fs.readFileSync(path.join(chatDir, f), 'utf8'))
-          const messages = Array.isArray(raw.messages) ? raw.messages : []
-          return {
-            cardId: String(raw.cardId || f.replace(/\.json$/, '')),
-            updatedAt: Number(raw.updatedAt || 0),
-            count: messages.length,
-            preview: String(messages.find((m) => m.role === 'user')?.content || '').slice(0, 60),
-          }
-        } catch {
-          return null
-        }
-      })
-      .filter(Boolean)
-      .sort((a, b) => b.updatedAt - a.updatedAt)
-      .slice(0, limit)
-  } catch {
-    return []
-  }
+/**
+ * 把上游 / 网络异常归一成前端能给「定向动作」的错误码。
+ * 归一化而不是让前端猜文案：文案随时会改，code 是契约。
+ * network / context / stall / empty → 重试本轮；auth → 打开设置；length → 调高单次输出上限；其余 → 复制错误
+ */
+function classifyErrorCode(e) {
+  const msg = String((e && e.message) || e || '')
+  const raw = String((e && e.code) || '')
+  if (raw === 'context-overflow' || /maximum context|context (length|overflow)|too many tokens/i.test(msg)) return 'context'
+  if (/aborted|abort/i.test(msg) || raw === 'AbortError' || raw === 'ABORT_ERR') return 'aborted'
+  if (/\b(401|403)\b|invalid api key|incorrect api key|unauthorized|forbidden/i.test(msg)) return 'auth'
+  if (/\b(429)\b|rate limit|quota/i.test(msg)) return 'rate-limit'
+  if (raw === 'network-error' || /fetch failed|network|ECONNRESET|ECONNREFUSED|ETIMEDOUT|EAI_AGAIN|ENOTFOUND|socket hang up|terminated/i.test(msg)) return 'network'
+  if (/max_tokens|max tokens/i.test(msg)) return 'length'
+  return 'unknown'
 }
 
 // ---- 本地文件挂载（只读，不上传） ----
@@ -1939,6 +2227,60 @@ const NO_THINKING_BODY = { chat_template_kwargs: { enable_thinking: false } }
 const MAX_TOKENS_400_RE = /max_tokens[^\n]{0,160}(range|exceed|too (?:large|big)|must be|should be|limit|<=)|range of max_tokens/i
 /** 400 详情判定②：prompt / 上下文超窗（减半救不了，交给调用方裁剪重试） */
 const CONTEXT_400_RE = /(context|prompt|input)[^\n]{0,160}(length|long|exceed|limit|too (?:large|big|many))|maximum context/i
+/** 错误详情里没有任何可分类信号：详情为空 / HTML 错误页 > 300 字被 llmHttpError 截断后不留关键词。
+    这类必须原样抛出——旧的「详情不含 max_tokens 就 throw」在这里是靠反证成立的，
+    改成「按可修复性分流」后若不显式排除，HTML 错误页会被误判成「可以用改 body 修好」 */
+function isTypeless400(detail) {
+  const t = String(detail || '')
+  return t === '' || /<\s*(html|head|body|title|center)\b/i.test(t)
+}
+
+/**
+ * 窥一眼新响应是不是「流内 400」：DashScope 系网关对超限参数返回 HTTP 200 + text/event-stream，
+ * 但流里只有一条 data: {"error":{...}}，没有任何 choices。
+ * 只能 peek 不能 re-read：因此把已建立的 reader 与首块字节一并交还调用方，
+ * 真流时由调用方从首块起接着解析（不丢内容），出错时 reader 被丢弃即可。
+ * @param {Response} resp
+ * @returns {Promise<{ error: string|null, reader: ReadableStreamDefaultReader|null, first: Uint8Array|null }>}
+ */
+async function peekStreamError(resp) {
+  const ct = String(resp.headers?.get?.('content-type') || '')
+  if (!ct.includes('text/event-stream') || !resp.body) return { error: null, reader: null, first: null }
+  let reader = null
+  try {
+    reader = resp.body.getReader()
+    const { value } = await reader.read()
+    const first = value || null
+    const text = new TextDecoder().decode(first || new Uint8Array())
+    // 按行取 data: 载荷：不跨行匹配，避免把后续正常 chunk 的 "error" 字段也吞进来
+    let parsed = null
+    for (const line of text.split('\n')) {
+      const trimmed = line.trim()
+      if (!trimmed.startsWith('data:')) continue
+      const payload = trimmed.slice(5).trim()
+      if (!payload || payload === '[DONE]') continue
+      try {
+        const j = JSON.parse(payload)
+        if (j?.error) {
+          parsed = j
+          break
+        }
+      } catch {
+        /* 半截 JSON：可能首块被切断，交给外层解析器处理，这里不当错误 */
+      }
+    }
+    if (!parsed) return { error: null, reader, first }
+    // 确认是错误流：这条 reader 不再有用，释放掉让 body 可被丢弃
+    try {
+      reader.releaseLock?.()
+    } catch {
+      /* 忽略 */
+    }
+    return { error: JSON.stringify(parsed), reader: null, first: null }
+  } catch {
+    return { error: null, reader, first: null }
+  }
+}
 
 /**
  * 瞬时网关错误（超时 / 限流 / 5xx）：这类错误重试一次往往就过，整轮直接报错收尾代价太大——
@@ -1957,6 +2299,32 @@ function transientRetryDelays() {
 
 const nap = (ms) => new Promise((resolve) => setTimeout(resolve, ms))
 
+/** 网关静默后的重试间隔：AI_STALL_RETRY_MS 可覆盖（单测压成 0 提速）；次数多于间隔就沿用最后一个 */
+function stallRetryDelays() {
+  const list = String(process.env.AI_STALL_RETRY_MS || '2000,5000,10000')
+    .split(',')
+    .map((x) => Number(x.trim()))
+    .filter((x) => Number.isFinite(x) && x >= 0)
+  return list.length ? list : [2000, 5000, 10000]
+}
+
+/** 可被用户中止打断的等待：等满返回 true，中途被中止返回 false（调用方据此立刻收手） */
+function napUnlessAborted(ms, signal) {
+  if (signal?.aborted) return Promise.resolve(false)
+  if (!(Number(ms) > 0)) return Promise.resolve(true)
+  return new Promise((resolve) => {
+    const timer = setTimeout(() => {
+      signal?.removeEventListener?.('abort', onAbort)
+      resolve(!signal?.aborted)
+    }, Number(ms))
+    function onAbort() {
+      clearTimeout(timer)
+      resolve(false)
+    }
+    signal?.addEventListener?.('abort', onAbort, { once: true })
+  })
+}
+
 /**
  * 把网关错误摘成一句话：错误页多是 HTML（nginx 504 / 502），原样甩给用户或回喂给模型都是噪音。
  * 保留 `LLM <status>` 前缀——轮循环靠它识别 400 上下文溢出。
@@ -2008,16 +2376,22 @@ async function* callLLM({ baseUrl, apiKey, model, messages, tools, maxTokens = 4
         const resp = await post(extra, maxTok)
         if (resp.ok || !TRANSIENT_STATUS.has(resp.status) || !retryable) return resp
         const wait = delays[attempt]
-        pendingNotices.push(
-          `网关返回 HTTP ${resp.status}（瞬时错误）：${wait / 1000} 秒后自动重试本步（第 ${attempt + 1}/${delays.length} 次），任务不中断`,
-        )
+        pendingNotices.push({
+        level: 'warn',
+        code: 'gateway-retry',
+        text: `网关返回 HTTP ${resp.status}（瞬时错误）：${wait / 1000} 秒后自动重试本步（第 ${attempt + 1}/${delays.length} 次），任务不中断`,
+        })
         await nap(wait)
       } catch (e) {
         if (signal?.aborted) throw e
         lastErr = e
         if (!retryable) break
         const wait = delays[attempt]
-        pendingNotices.push(`网关连接失败（${String(e?.message || e).slice(0, 80)}）：${wait / 1000} 秒后自动重试本步`)
+        pendingNotices.push({
+        level: 'warn',
+        code: 'gateway-retry',
+        text: `网关连接失败（${String(e?.message || e).slice(0, 80)}）：${wait / 1000} 秒后自动重试本步`,
+        })
         await nap(wait)
       }
     }
@@ -2026,47 +2400,111 @@ async function* callLLM({ baseUrl, apiKey, model, messages, tools, maxTokens = 4
     throw err
   }
 
-  let curExtra = extraBody
+  // 扩展字段合并成一份：观测用的 stream_options（看缓存命中）＋ 可选的思考开关
+  const baseExtra = { ...USAGE_BODY, ...(extraBody || {}) }
+  let curExtra = Object.keys(baseExtra).length ? baseExtra : undefined
   let resp = await postRetry(curExtra)
-  for (const text of pendingNotices.splice(0)) yield { type: 'notice', text }
-  const hasExtra = Boolean(extraBody && Object.keys(extraBody).length)
-  if (!resp.ok && hasExtra) {
-    // 网关不认扩展字段（非 vLLM/SGLang 系）：去掉后原样重试一次，别让整轮直接失败
+  for (const n of pendingNotices.splice(0)) yield { type: 'notice', text: n.text, level: n.level, code: n.code }
+  const hasExtra = Boolean(curExtra && Object.keys(curExtra).length)
+  /** 扩展字段已摘干净：之后的 400 不再是「网关不认扩展字段」那类，别再无脑拿减半去赌 */
+  let extrasPeeled = false
+  /** 已读过的 400 详情。响应体只能读一次，下面减半分支复用它——二次读会拿到空串，
+      把「max_tokens 超限」误判成「不可分类错误」直接抛掉 */
+  let pre400Detail = ''
+  // 这两个分支只处理「只能改 body 才能修」的错误：上下文溢出由轮循环裁剪上下文（改 messages）修，
+  // 在这里重试毫无意义，必须原样抛回去
+  const isBodyFixable400 = (text) =>
+    MAX_TOKENS_400_RE.test(text) || (hasExtra && !extrasPeeled && !CONTEXT_400_RE.test(text))
+  if (!resp.ok && resp.status === 400 && hasExtra) {
+    // 网关不认扩展字段（非 vLLM/SGLang 系 / 严格校验的 OpenAI 兼容实现）：按顺序逐个摘掉再试，
+    // 别让「可选的观测字段」把整轮打成失败。
+    // 摘除顺序：网关在 400 详情里点名了哪个字段就先摘哪个（见下面 peelOrder 的说明）；
+    // 详情没点名时才按 EXT_PEEL_ORDER 的固定顺序——先摘 stream_options（纯观测、摘掉只损失缓存可见性），
+    // 再摘 chat_template_kwargs（摘掉会恢复深度思考）。
     const detail = await resp.text().catch(() => '')
-    curExtra = undefined
-    resp = await postRetry(curExtra)
-    if (!resp.ok) {
-      const text = await resp.text().catch(() => '')
-      throw llmHttpError(resp.status, text)
-    }
-    yield {
-      type: 'notice',
-      text: `当前网关不支持「关闭深度思考」参数（HTTP ${resp.status} 已回退）：${detail.slice(0, 120)}`,
+    // 若详情本身就指向 max_tokens 超限，去额外字段救不了它——留给下面的减半分支。
+    // detail 必须带过去（响应体只能读一次），否则减半分支读到空串、被 isTypeless400 判成不可分类直接抛
+    pre400Detail = detail
+    if (!MAX_TOKENS_400_RE.test(detail)) {
+      const removed = []
+      // 严格校验的 OpenAI 兼容网关通常**认得 stream_options**（OpenAI 规范字段，只影响观测），
+      // 却不认 vLLM 系的 chat_template_kwargs —— 它会在 400 详情里直接点名后者。
+      // 若不分青红皂白按固定顺序先摘 stream_options，本轮之后所有请求都拿不到 usage，
+      // 前端只能显示「缓存未提供」——为了关个思考，把整轮的缓存可见性一起赔进去，不值。
+      // 所以：被点名的先摘，没点名才退回固定顺序。
+      const named = EXT_PEEL_ORDER.filter((k) => String(detail).toLowerCase().includes(k))
+      const peelOrder = named.length ? [...named, ...EXT_PEEL_ORDER.filter((k) => !named.includes(k))] : EXT_PEEL_ORDER
+      for (const key of peelOrder) {
+        if (!curExtra || !(key in curExtra)) continue
+        const next = { ...curExtra }
+        delete next[key]
+        curExtra = Object.keys(next).length ? next : undefined
+        removed.push(key)
+        resp = await postRetry(curExtra)
+        for (const n of pendingNotices.splice(0)) yield { type: 'notice', text: n.text, level: n.level, code: n.code }
+        if (resp.ok) {
+          pre400Detail = ''
+          break
+        }
+        // 非 400（5xx / 网络）：不读 body，交给下面的错误归一分支
+        if (resp.status !== 400) {
+          pre400Detail = ''
+          break
+        }
+        pre400Detail = await resp.text().catch(() => '')
+        if (MAX_TOKENS_400_RE.test(pre400Detail)) break
+      }
+      extrasPeeled = true
+      if (removed.length) {
+        const thinkingGone = removed.includes('chat_template_kwargs')
+        yield {
+          type: 'notice',
+          level: 'warn',
+          code: thinkingGone ? 'thinking-unsupported' : 'extra-unsupported',
+          text: `当前网关不接受请求扩展字段（HTTP 400）：已摘除 ${removed.join(' / ')} 后重试${
+            resp.ok ? '成功' : '仍失败'
+          }${thinkingGone ? '——本轮的「关闭深度思考」参数失效，思考耗时可能变长' : '——本轮看不到缓存命中统计'}：${String(detail).slice(0, 120)}`,
+        }
+      }
     }
   }
 
-  // max_tokens 超网关硬上限 / 窗口：自动减半重试（最多 2 次），避免手填过大或探测值过时时整轮直接失败。
+  // max_tokens 超网关硬上限：自动减半重试（最多 2 次），避免手填过大或探测值过时时整轮直接失败。
   // 分类收紧：只有详情明确指向 max_tokens 才减半；prompt 超窗类 400 减半无意义，
-  // 打 context-overflow 标记抛出，由轮循环走「压缩上下文重试」分支
+  // 打 context-overflow 标记抛出，由轮循环走「压缩上下文重试」分支。
+  // 注意这里只处理「响应头阶段」的 400（真 HTTP 400）。DashScope 系把 400 包在 HTTP 200 的流里，
+  // 那种只能在流解析时发现，由下面的 halveAndReopen 负责——两者共用 effMax / halved 计数。
   let effMax = maxTokens
+  /** 已完成的减半次数（上限 2）：响应头阶段与流内阶段共用同一预算，不能各扣 2 次 */
+  let halved = 0
   for (let i = 0; i < 2 && !resp.ok && resp.status === 400; i++) {
-    const detail = await resp.text().catch(() => '')
-    if (!MAX_TOKENS_400_RE.test(detail)) {
+    // 扩展字段回退分支可能已经读过这个 400 的 body：复用，别二次读（二次读只会拿到空串）
+    const detail = pre400Detail || (await resp.text().catch(() => ''))
+    pre400Detail = ''
+    if (!isBodyFixable400(detail) || isTypeless400(detail)) {
       const err = llmHttpError(400, detail)
       if (CONTEXT_400_RE.test(detail)) err.code = 'context-overflow'
       throw err
     }
     const prev = effMax
+    halved++
     effMax = Math.max(2048, Math.floor(effMax / 2))
     resp = await postRetry(curExtra, effMax)
-    for (const text of pendingNotices.splice(0)) yield { type: 'notice', text }
-    yield { type: 'notice', text: `单次输出上限 ${prev} 被网关拒绝（HTTP 400）：已自动减半为 ${effMax} 重试` }
+    for (const n of pendingNotices.splice(0)) yield { type: 'notice', text: n.text, level: n.level, code: n.code }
+    yield {
+    type: 'notice',
+    level: 'warn',
+    code: 'max-tokens-halved',
+    text: `单次输出上限 ${prev} 被网关拒绝（HTTP 400）：已自动减半为 ${effMax} 重试`,
+    }
   }
 
   if (!resp.ok) {
-    const text = await resp.text().catch(() => '')
+    const text = pre400Detail || (await resp.text().catch(() => ''))
+    pre400Detail = ''
     throw llmHttpError(resp.status, text)
   }
+
   // 减半后的值被网关接受 = 「网关接受的单次输出上限」的证据：回写 capCache（**不是窗口缓存**）。
   // 窗口与输出上限是两回事：本网关实测 max_tokens 硬上限 131072、/models 又无窗口字段，
   // 把接受值当窗口会污染圆环分母与单轮上下文预算
@@ -2078,9 +2516,11 @@ async function* callLLM({ baseUrl, apiKey, model, messages, tools, maxTokens = 4
   if (!resp.body) throw new Error('LLM 返回空 body')
 
   const decoder = new TextDecoder()
-  const reader = resp.body.getReader()
+  let reader = resp.body.getReader()
   let buffer = ''
   let toolCallsAccum = null
+  /** halveAndReopen 换过流后置真：外层循环据此清空半截缓冲，避免新旧流内容混在一起 */
+  let reopened = false
 
   const flushToolCalls = () => {
     if (!toolCallsAccum) return null
@@ -2092,11 +2532,80 @@ async function* callLLM({ baseUrl, apiKey, model, messages, tools, maxTokens = 4
     return { type: 'tool-calls', toolCalls: finalized }
   }
 
+  /**
+   * 流内 400 的减半重试：换更小的 max_tokens 重新发起，并把新响应交回外层循环解析。
+   * 复用响应头阶段那套逻辑，但必须重新探测新流是不是又是一条 error——
+   * 不探的话外层循环会把它当真流读一遍，白跑一轮还把同一个错误重复抛出去。
+   * @returns {Promise<boolean>} true = 已换好新流可重新解析；false = 减半已用尽 / 新流仍是错误
+   */
+  const halveAndReopen = async function* () {
+    if (halved >= 2) return false
+    try {
+      reader.releaseLock?.()
+    } catch {
+      /* 已读完释放，忽略 */
+    }
+    // 上一版流的半截行/累积与新版无关：留着会把两版内容拼在一起
+    buffer = ''
+    toolCallsAccum = null
+    const prev = effMax
+    halved++
+    effMax = Math.max(2048, Math.floor(effMax / 2))
+    const next = await postRetry(curExtra, effMax)
+    for (const n of pendingNotices.splice(0)) yield { type: 'notice', text: n.text, level: n.level, code: n.code }
+    if (!next.ok || !next.body) {
+      const text = await next.text().catch(() => '')
+      const err = llmHttpError(next.status, text)
+      if (CONTEXT_400_RE.test(text)) err.code = 'context-overflow'
+      throw err
+    }
+    yield {
+      type: 'notice',
+      level: 'warn',
+      code: 'max-tokens-halved',
+      text: `单次输出上限 ${prev} 被网关拒绝（流内错误）：已自动减半为 ${effMax} 重试`,
+    }
+    const { error: peek, reader: nextReader, first } = await peekStreamError(next)
+    if (peek) {
+      // 减半后还是同一条错误：继续减（最多到 2048）或原样抛出，交给轮循环
+      if (halved < 2 && isBodyFixable400(peek)) {
+        resp = next
+        reader = next.body.getReader()
+        return yield* halveAndReopen()
+      }
+      const err = llmHttpError(400, peek)
+      if (CONTEXT_400_RE.test(peek)) err.code = 'context-overflow'
+      throw err
+    }
+    // 真流：沿用 peek 阶段已建立的 reader，把首块字节塞回缓冲后交外层继续读
+    resp = next
+    reader = nextReader || next.body.getReader()
+    if (first) buffer = new TextDecoder().decode(first)
+    reopened = true
+    return true
+  }
+
+  // 外层循环的存在只有一个理由：流内 400 无法在响应头阶段发现，只能读到那一行才知道。
+  // halveAndReopen 换好新流后把 buffer 重置为「新流已 peek 出的首块字节」并置 reopened，
+  // 这里只需丢掉上一版流残留的半截行与工具累积，不能碰 buffer（里面是新流的首块）。
+  // reader 的释放放在 finally：不能放循环体内——continue parse 要用新流的 reader 继续读，
+  // 在循环里释放会把新流的锁也解掉（实测报「not attached to a stream」）。
+  // 换流时旧的 reader 已由 peekStreamError 释放，这里的 releaseLock 对它是空操作。
   try {
+   parse: while (true) {
+    if (reopened) {
+      toolCallsAccum = null
+      reopened = false
+    }
     while (true) {
       if (signal?.aborted) return
       const { done, value } = await reader.read()
       if (done) break
+      // 收到字节就冒一个「连接还活着」事件：轮循环的静默看门狗据此区分「网关彻底不回应」与
+      // 「模型正在长思考 / 正在拼超长工具参数，中转网关只在末尾批量 flush」。
+      // 此前看门狗只认 reasoning / content / tool_calls 增量：网关缓冲工具参数时连接明明是活的，
+      // 也被判成「上游 N 秒没有返回任何数据」并整轮报废（实测设计稿建卡连续两轮死在 fs_write 参数半途）。
+      yield { type: 'stream-alive' }
       buffer += decoder.decode(value, { stream: true })
 
       const lines = buffer.split('\n')
@@ -2117,8 +2626,31 @@ async function* callLLM({ baseUrl, apiKey, model, messages, tools, maxTokens = 4
         } catch {
           continue
         }
+        // 部分网关（DashScope 系实测）把 4xx 包在 HTTP 200 的 SSE 流里回：body 只有一条
+        // data: {"error":{"code":...,"message":"<400> ... Range of max_tokens should be [1, 8192]"}}。
+        // 这类行没有 choices，旧逻辑会静默 continue → 整轮零产出 → 被下游误判成「网关返回空响应」，
+        // 真实原因（max_tokens 超限 / 参数非法 / 上下文溢出）全部丢失，且 max_tokens 减半兜底
+        // 因 !resp.ok 为假而永不触发。
+        // 处置：能靠改 body 修的（max_tokens 超限）当场减半并重开流解析；其余原样抛出交轮循环处理
+        if (chunk.error) {
+          const detail = JSON.stringify(chunk)
+          // 一次都没减半过才允许重来：吐过字节后再换 body 重放会造成前端内容重复
+          if (halved === 0 && isBodyFixable400(detail) && !isTypeless400(detail)) {
+            const ok = yield* halveAndReopen()
+            if (ok) continue parse
+          }
+          const err = llmHttpError(Number(chunk.error.code) || 400, detail)
+          if (CONTEXT_400_RE.test(detail)) err.code = 'context-overflow'
+          throw err
+        }
+        // usage 可能挂在收尾块（choices 为空）上，也可能挂在最后一个带 choice 的块上：
+        // 两个位置都取，命中率统计才不会因为网关风格不同而丢
+        if (chunk.usage) {
+          const usage = normalizeUsage(chunk.usage)
+          if (usage) yield { type: 'usage', usage }
+        }
         const choice = chunk.choices?.[0]
-        if (!choice) continue // usage chunk 等
+        if (!choice) continue // 只剩 usage 的收尾块
         const delta = choice.delta || {}
         // reasoning 字段各家命名不一：reasoning_content（DeepSeek/智谱）/ reasoning（部分网关）
         const reasoning = delta.reasoning_content ?? delta.reasoning ?? ''
@@ -2156,12 +2688,13 @@ async function* callLLM({ baseUrl, apiKey, model, messages, tools, maxTokens = 4
           if (evt) yield evt
         }
       }
-    }
+     }
+   }
   } finally {
     try {
       reader.releaseLock?.()
     } catch {
-      /* 已中止时忽略 */
+      /* 已释放 / 已中止：忽略 */
     }
   }
 
@@ -2185,6 +2718,31 @@ async function* callLLM({ baseUrl, apiKey, model, messages, tools, maxTokens = 4
 /** 工具结果里内联图片的体积上限（超出只留摘要，避免把上下文塞爆） */
 const TOOL_IMAGE_MAX_BYTES = 2 * 1024 * 1024
 
+/**
+ * 工具调用参数归一：网关原样吐的 arguments 字符串，与「下一回合回放时由前端 args 重新序列化」
+ * 的结果**未必逐字节相同**（多余空格、数字写法 1.0→1、转义差异）。只要差一个字节，
+ * 那条 assistant.tool_calls 消息就在轮边界被改写 ⇒ 前缀缓存从它起全部失效。
+ * 统一走 parse → stringify（解析失败保留原文），两侧就长得一模一样了。
+ */
+function normalizeToolArgs(raw) {
+  const s = typeof raw === 'string' ? raw : raw == null ? '' : String(raw)
+  if (!s) return '{}'
+  try {
+    return JSON.stringify(JSON.parse(s))
+  } catch {
+    return s
+  }
+}
+
+/** 落进模型上下文的工具调用：与 toOpenAiMessages 恢复出来的形状保持同一序列化口径 */
+function contextToolCalls(calls) {
+  return (calls || []).map((tc, i) => ({
+    id: tc?.id || `call_${i}`,
+    type: 'function',
+    function: { name: tc?.function?.name || '', arguments: normalizeToolArgs(tc?.function?.arguments) },
+  }))
+}
+
 /**
  * 拆出工具结果中的 base64 图片（card_screenshot 等）：
  * 图片对「文本模型」毫无价值却极占上下文，故从回传 LLM 的文本里剔除，只留给前端做预览。
@@ -2489,6 +3047,46 @@ function toolRoundSignature(toolCalls) {
   return toolCalls.map((tc) => `${tc?.function?.name || '?'}${stableStringify(safeParseArgs(tc?.function?.arguments))}`).join('|')
 }
 
+// ---- 前缀缓存观测：usage 归一 + 前缀漂移定位 ----
+
+/** 各家网关的缓存字段命名不一，统一摘成一份口径 */
+function normalizeUsage(u) {
+  if (!u || typeof u !== 'object') return null
+  const num = (v) => (Number.isFinite(Number(v)) ? Number(v) : 0)
+  const promptTokens = num(u.prompt_tokens ?? u.input_tokens)
+  const completionTokens = num(u.completion_tokens ?? u.output_tokens)
+  const details = u.prompt_tokens_details || u.input_tokens_details || {}
+  const rawCached = details.cached_tokens ?? u.prompt_cache_hit_tokens ?? u.cache_read_input_tokens ?? u.cached_tokens
+  const cachedTokens = num(rawCached)
+  const cacheMissTokens = u.prompt_cache_miss_tokens !== undefined ? num(u.prompt_cache_miss_tokens) : Math.max(0, promptTokens - cachedTokens)
+  return {
+    promptTokens,
+    completionTokens,
+    cachedTokens,
+    cacheMissTokens,
+    hitRate: promptTokens > 0 ? Math.round((cachedTokens / promptTokens) * 1000) / 10 : 0,
+    // reported=false ⇒ 该网关压根不报缓存字段（如本仓的微信 GLM 网关），界面只能显示「未提供」
+    reported: rawCached !== undefined,
+  }
+}
+
+/**
+ * 定位前缀漂移：逐条比对上一次实际发给网关的消息与本次的，返回第一处不同的下标。
+ * - 下标落在尾部（= 只是追加了新消息）⇒ 正常，缓存继续命中；
+ * - 下标落在中段（rewrote=true）⇒ 历史被改写，从那一条起缓存全部失效，应当留痕告警。
+ * 只比对序列化结果，不看语义：网关也是这么判的。
+ */
+function prefixDrift(prev, next) {
+  const a = Array.isArray(prev) ? prev : []
+  const b = Array.isArray(next) ? next : []
+  const limit = Math.min(a.length, b.length)
+  let i = 0
+  for (; i < limit; i++) {
+    if (JSON.stringify(a[i]) !== JSON.stringify(b[i])) break
+  }
+  return { index: i, tail: limit, rewrote: i < limit, shared: i }
+}
+
 // ---- 上下文预算与压缩 ----
 
 /** 输入上下文默认预算（token 粗估）：够装下几万字节卡片片段 + 十几轮对话，又不至于拖慢推理 */
@@ -2601,41 +3199,54 @@ function openAiMsgTokens(m) {
 }
 
 /**
- * 单轮内上下文裁剪：超预算时从**最早**的消息开始折叠，直到落回预算内。
+ * 单轮内上下文裁剪：超预算时折叠超长工具结果 / 注入图像，直到落回预算内。
  * 只改 content、绝不删消息 —— tool_calls 与 role:'tool' 的配对一旦被破坏，网关会直接 400。
- * @returns {{messages:any[], trimmed:number, tokens:number, before:number}}
+ *
+ * **粘滞推进（前缀缓存的关键）**：`from` = 上次已经处理到的下标，本次只从它往后折。
+ * 老实现每轮都从 index 1 重新扫，`floor = length - keepRecent` 又随消息增长不断右移，
+ * 于是一条「上一步还在最近窗口里、保持原文」的工具结果，下一步就被折叠改写 ——
+ * 历史中段被改写 ⇒ 从那条起往后的前缀缓存全部失效（实测每步都在丢命中）。
+ * 传 `from` 之后：折过的不会还原、没折过的不会被回头补折，前缀保持逐字节稳定。
+ * 只有「预算真的兜不住」（整个 [from, floor) 都折完仍超）才会回改早期区域，这是罕见且有提示的路径。
+ *
+ * @param {{budgetTokens?:number, keepRecent?:number, stubChars?:number, from?:number}} [opts]
+ * @returns {{messages:any[], trimmed:number, tokens:number, before:number, from:number}} from = 下次的起点
  */
-function trimTurnContext(messages, { budgetTokens = DEFAULT_TURN_CONTEXT_TOKENS, keepRecent = TRIM_KEEP_RECENT, stubChars = TRIM_STUB_CHARS } = {}) {
+function trimTurnContext(messages, { budgetTokens = DEFAULT_TURN_CONTEXT_TOKENS, keepRecent = TRIM_KEEP_RECENT, stubChars = TRIM_STUB_CHARS, from = 1 } = {}) {
   const list = Array.isArray(messages) ? messages.slice() : []
   const before = list.reduce((a, m) => a + openAiMsgTokens(m), 0)
   let total = before
-  if (!(budgetTokens > 0) || total <= budgetTokens) return { messages: list, trimmed: 0, tokens: total, before }
   // index 0 是系统提示，永远保留；最近 keepRecent 条也保持原文（当前工作记忆）
   const floor = Math.max(1, list.length - keepRecent)
+  const start = Math.max(1, Math.min(Number(from) || 1, floor))
+  if (!(budgetTokens > 0) || total <= budgetTokens) return { messages: list, trimmed: 0, tokens: total, before, from: start }
   let trimmed = 0
-  // ① 折叠早期超长工具结果：留下头部 + 明确的「重新调用可取全文」指引
-  for (let i = 1; i < floor && total > budgetTokens; i++) {
-    const m = list[i]
-    if (m?.role !== 'tool' || typeof m.content !== 'string' || m.content.length <= stubChars * 2) continue
-    const prev = openAiMsgTokens(m)
-    list[i] = {
-      ...m,
-      content: `${m.content.slice(0, stubChars)}…\n[工具结果已折叠以腾出单轮上下文预算；需要完整内容请重新调用该工具，不要凭这段摘要猜结论]`,
-    }
+  const stub = (i, content) => {
+    const prev = openAiMsgTokens(list[i])
+    list[i] = { ...list[i], content }
     total -= prev - openAiMsgTokens(list[i])
     trimmed++
   }
-  // ② 仍超预算：丢掉早期注入图像（图 token 很贵），保留其文字说明
-  for (let i = 1; i < floor && total > budgetTokens; i++) {
+  // ① 从 from 起顺序折叠：超长工具结果留头部 + 「重新调用可取全文」指引
+  let i = start
+  while (i < floor && total > budgetTokens) {
     const m = list[i]
-    if (m?.role !== 'user' || !Array.isArray(m.content) || !m.content.some((part) => part?.type === 'image_url')) continue
-    const prev = openAiMsgTokens(m)
-    const texts = m.content.filter((part) => part?.type === 'text').map((part) => part.text)
-    list[i] = { ...m, content: `${texts.join(' ')}\n[图像已折叠以腾出单轮上下文预算；需要看图请重新跑一次渲染 / 对比工具]` }
-    total -= prev - openAiMsgTokens(list[i])
-    trimmed++
+    if (m?.role === 'tool' && typeof m.content === 'string' && m.content.length > stubChars * 2) {
+      stub(i, `${m.content.slice(0, stubChars)}…\n[工具结果已折叠以腾出单轮上下文预算；需要完整内容请重新调用该工具，不要凭这段摘要猜结论]`)
+    } else if (m?.role === 'user' && Array.isArray(m.content) && m.content.some((part) => part?.type === 'image_url')) {
+      // 注入图像（图 token 很贵）折叠成文字说明
+      const texts = m.content.filter((part) => part?.type === 'text').map((part) => part.text)
+      stub(i, `${texts.join(' ')}\n[图像已折叠以腾出单轮上下文预算；需要看图请重新跑一次渲染 / 对比工具]`)
+    }
+    i++
+  }
+  // ② 整个活跃区都折完仍超预算：只能回改早期区域（会改写历史前缀，调用方据此告警）
+  for (let j = 1; j < start && total > budgetTokens; j++) {
+    const m = list[j]
+    if (m?.role !== 'tool' || typeof m.content !== 'string' || m.content.length <= stubChars * 2) continue
+    stub(j, `${m.content.slice(0, stubChars)}…\n[工具结果已折叠以腾出单轮上下文预算；需要完整内容请重新调用该工具，不要凭这段摘要猜结论]`)
   }
-  return { messages: list, trimmed, tokens: total, before }
+  return { messages: list, trimmed, tokens: total, before, from: i }
 }
 
 /** 深度压缩后最近多少条保持原文（含进行中的 assistant/tool 配对与最新证据） */
@@ -2717,7 +3328,9 @@ function toOpenAiMessages(messages) {
       out.push(msg)
       for (const tc of calls) {
         const result = tc.error ? `Error: ${tc.error}` : typeof tc.result === 'string' ? tc.result : JSON.stringify(tc.result ?? '')
-        out.push({ role: 'tool', tool_call_id: tc.toolCallId || tc.id || `call_${calls.indexOf(tc)}`, content: result.slice(0, 12000) })
+        // 截断口径必须与轮内 live 上下文（下方 currentMessages.push）逐字一致：
+        // 前端回传的历史是按同一上限截过的，两边不同就会在轮边界改写历史 ⇒ 前缀缓存整段失效
+        out.push({ role: 'tool', tool_call_id: tc.toolCallId || tc.id || `call_${calls.indexOf(tc)}`, content: result.slice(0, TOOL_RESULT_MAX_CHARS) })
       }
       continue
     }
@@ -2736,7 +3349,37 @@ export function createAiChatMiddleware(opts = {}) {
   // 仓库内运行由「root === 仓库根」自动成立；cardbuddy 发布态快照根在包内，由宿主显式开启。
   const allowDispatch = opts.allowDispatch === true
   /** 对话记录落盘目录（.cache/ 已在 .gitignore）：随 root 走，测试可用临时根隔离 */
-  const chatDir = path.join(root, '.cache', 'ai-chats')
+  const chatDir = chatHistoryDir(root)
+  /**
+   * 同卡单飞锁：一张卡同时只允许一个回合在跑。
+   * 并发回合会互相覆盖 card_write 落盘、把 .history 快照顺序打乱，前端也会渲染出两条「生成中」。
+   * 挂在中间件实例上（不是模块级）：测试里各自 createAiChatMiddleware() 互不串味。
+   * key = cardContext.id；没有卡上下文时用固定 key，仍然单飞。
+   */
+  const activeTurns = new Map()
+  /** 锁的兜底过期时间：墙钟熔断保证回合会在 turnTimeoutMs 附近结束，超时残留（进程异常 / 监听器漏放）就允许接管 */
+  const STALE_TURN_LOCK_MS = 30 * 60 * 1000
+
+  /**
+   * 是否有回合正在跑（跨所有卡片）。
+   * 用于「对话进行中禁止改动生效模型配置」：每轮对话在开跑时把 baseUrl/apiKey/model/maxTokens 快照进
+   * finalConfig，中途改配置不会影响这一轮（已验证），但会让用户误以为改了立刻生效——下一轮才切，
+   * 长任务里这种「改了没反应」极易被当成 bug。故运行期一律拒绝写生效模型。
+   * 与单飞锁同一套过期判定：残留锁不会永久锁死配置面板。
+   */
+  const anyTurnRunning = () => {
+    const now = Date.now()
+    for (const t of activeTurns.values()) {
+      if (now - t.since < Math.max(STALE_TURN_LOCK_MS, Number(t.turnTimeoutMs || 0) + 5 * 60 * 1000)) return true
+    }
+    return false
+  }
+  /** 运行期改动生效模型配置的统一拒绝响应 */
+  const rejectIfTurnRunning = (req, res, message) => {
+    if (!anyTurnRunning()) return false
+    sendJson(req, res, 409, { error: 'turn-in-flight', message })
+    return true
+  }
 
   return async (req, res, next) => {
     const rawUrl = req.url || ''
@@ -2777,13 +3420,21 @@ export function createAiChatMiddleware(opts = {}) {
           // maxTokens = 本轮实际会用的值；maxTokensAuto = 用户没填（面板据此留空 + 显示自动值）
           maxTokens: effectiveMaxTokens(cfg),
           maxTokensAuto: !(cfg.maxTokens > 0),
+          // cap = 网关**实测接受**的上限（唯一测量值）；ceiling = 自动模式封顶的**假设值**，两者不可混用
           maxTokensCap: capCache.get(maxTokensSig(cfg))?.cap || 0,
           maxTokensWindow: windowCache.get(maxTokensSig(cfg))?.window || 0,
+          maxTokensCeiling: AUTO_MAX_TOKENS_CEILING,
+          // 有回合在跑（跨卡片）：前端据此禁用模型库的切换 / 编辑生效项（后端另有 409 兜底）
+          turnRunning: anyTurnRunning(),
           thinking: cfg.thinking !== false,
           vision: cfg.vision === true,
           // 0 = 不限步数（默认）；>0 = 用户自设硬顶。面板据此留空并显示「不限 + 熔断器」说明
           maxSteps: cfg.maxSteps,
           turnTimeoutMs: cfg.turnTimeoutMs,
+          stallTimeoutMs: cfg.stallTimeoutMs,
+          stallRetries: cfg.stallRetries,
+          reasoningTimeoutMs: cfg.reasoningTimeoutMs,
+          autoContinueMax: cfg.autoContinueMax,
         }
         // 设置面板要「回显」已存密钥：仅 ?reveal=1 回明文（本系列端点只放行可信来源）
         if (query.get('reveal') === '1') out.apiKey = cfg.apiKey
@@ -2796,20 +3447,60 @@ export function createAiChatMiddleware(opts = {}) {
         } catch {
           return sendJson(req, res, 400, { error: 'invalid-body' })
         }
+        // 本端点只接受「执行策略类公共字段」。收到别的字段（尤其遗留的扁平模型键
+        // baseUrl / apiKey / model / maxTokens / thinking / vision）必须显式报错：
+        // 此前是静默忽略后返回 200 {ok:true}，调用方以为存成功，其实一个字节都没写
+        // （实测：POST {baseUrl,model} 返回 200，但 .env.cb.local 不变、回读仍是旧值）。
+        // 模型身份 / 能力字段走 /__ai/models，这里直接给出正确去处。
+        const ALLOWED = new Set([
+          'allowShell',
+          'autoApprove',
+          'maxSteps',
+          'turnTimeoutMs',
+          'stallTimeoutMs',
+          'stallRetries',
+          'reasoningTimeoutMs',
+          'autoContinueMax',
+        ])
+        const MODEL_FIELDS = new Set([
+          'id',
+          'name',
+          'baseUrl',
+          'apiKey',
+          'model',
+          'maxTokens',
+          'thinking',
+          'vision',
+          'createdAt',
+          'updatedAt',
+        ])
+        const unknown = Object.keys(body || {}).filter((k) => !ALLOWED.has(k))
+        if (unknown.length) {
+          const modelish = unknown.filter((k) => MODEL_FIELDS.has(k))
+          return sendJson(req, res, 400, {
+            error: 'unknown-fields',
+            message:
+              modelish.length > 0
+                ? `本端点只写执行策略类公共字段，不接受模型字段：${modelish.join(' / ')}。模型身份与能力请改用 /__ai/models（POST 新增 / PUT 更新）。`
+                : `未知字段：${unknown.join(' / ')}。本端点只接受：${[...ALLOWED].join(' / ')}。`,
+            unknown,
+            ...(modelish.length > 0 ? { modelFields: modelish, useInstead: '/__ai/models' } : {}),
+          })
+        }
         try {
           // apiKey 为空串 = 清除本地覆盖；未传（undefined）= 保持不变
           // 设置变更（换网关 / 换模型 / 换密钥 / 动视觉开关）→ 视觉探测结论作废，下轮重探
           visionProbeCache.clear()
+          // 全局公共配置：仅执行策略类字段（与模型身份无关，所有模型共享）。模型身份/能力字段走 /__ai/models。
           writeAiConfigLocal(root, {
-            baseUrl: body.baseUrl,
-            apiKey: body.apiKey === '' ? '' : body.apiKey,
-            model: body.model,
             allowShell: body.allowShell === undefined ? undefined : Boolean(body.allowShell),
-            maxTokens: body.maxTokens === undefined ? undefined : body.maxTokens,
-            thinking: body.thinking === undefined ? undefined : Boolean(body.thinking),
-            vision: body.vision === undefined ? undefined : Boolean(body.vision),
             autoApprove: body.autoApprove === undefined ? undefined : normalizeAutoApprove(body.autoApprove),
             maxSteps: body.maxSteps === undefined ? undefined : body.maxSteps,
+            turnTimeoutMs: body.turnTimeoutMs === undefined ? undefined : body.turnTimeoutMs,
+            stallTimeoutMs: body.stallTimeoutMs === undefined ? undefined : body.stallTimeoutMs,
+            stallRetries: body.stallRetries === undefined ? undefined : body.stallRetries,
+            reasoningTimeoutMs: body.reasoningTimeoutMs === undefined ? undefined : body.reasoningTimeoutMs,
+            autoContinueMax: body.autoContinueMax === undefined ? undefined : body.autoContinueMax,
           })
           const cfg = readAiConfig(root)
           return sendJson(req, res, 200, {
@@ -2823,11 +3514,17 @@ export function createAiChatMiddleware(opts = {}) {
             maxTokens: effectiveMaxTokens(cfg),
             maxTokensAuto: !(cfg.maxTokens > 0),
             maxTokensCap: capCache.get(maxTokensSig(cfg))?.cap || 0,
-          maxTokensWindow: windowCache.get(maxTokensSig(cfg))?.window || 0,
+            maxTokensWindow: windowCache.get(maxTokensSig(cfg))?.window || 0,
+            maxTokensCeiling: AUTO_MAX_TOKENS_CEILING,
+            turnRunning: anyTurnRunning(),
             thinking: cfg.thinking !== false,
             vision: cfg.vision === true,
             maxSteps: cfg.maxSteps,
             turnTimeoutMs: cfg.turnTimeoutMs,
+            stallTimeoutMs: cfg.stallTimeoutMs,
+            stallRetries: cfg.stallRetries,
+            reasoningTimeoutMs: cfg.reasoningTimeoutMs,
+            autoContinueMax: cfg.autoContinueMax,
           })
         } catch (e) {
           return sendJson(req, res, 500, { error: 'write-failed', message: String((e && e.message) || e) })
@@ -2836,24 +3533,154 @@ export function createAiChatMiddleware(opts = {}) {
       return sendJson(req, res, 405, { error: 'method-not-allowed' })
     }
 
+    // ---------- 模型库（多模型管理）----------
+    {
+      const mm = pathname.match(/^\/__ai\/models(?:\/([^/]+)(?:\/activate)?)?$/)
+      if (mm) {
+        const id = mm[1] || null
+        const activate = /\/activate$/.test(pathname)
+        if (req.method === 'GET' && !id) {
+          const { models, activeId } = readAiModels(root)
+          // turnRunning：有回合在跑时前端禁用「切换」与「编辑生效项」，与后端 409 兜底同源
+          return sendJson(req, res, 200, { models: models.map(maskModel), activeId, turnRunning: anyTurnRunning() })
+        }
+        if (req.method === 'GET' && id) {
+          const { models } = readAiModels(root)
+          const m = models.find((x) => x.id === id)
+          if (!m) return sendJson(req, res, 404, { error: 'model-not-found' })
+          // ?reveal=1 仅可信来源回明文 key（供编辑面板回显）
+          const reveal = query.get('reveal') === '1'
+          return sendJson(req, res, 200, reveal ? m : maskModel(m))
+        }
+        if (req.method === 'POST' && !id) {
+          // 新增：生成 id 入列。仅在「列表原本为空」时自动设为生效模型——
+          // 已有生效模型时新增不应抢夺生效权（新增多个模型不该来回切当前模型）。
+          let body
+          try {
+            body = await readBody(req)
+          } catch {
+            return sendJson(req, res, 400, { error: 'invalid-body' })
+          }
+          // 必填校验（后端兜底，前端已校验；防止绕过 UI 写入无法运行的模型）
+          const vErr = validateModelInput(body, { requireKey: true })
+          if (vErr) return sendJson(req, res, 400, { error: 'invalid-model', message: vErr })
+          const base = normalizeModel({ ...body, id: genModelId(), createdAt: Date.now(), updatedAt: Date.now() })
+          const { models, activeId: prevActive } = readAiModels(root)
+          models.push(base)
+          // 首个模型必激活（否则「只有一个模型却未启用」）；已有生效模型则保持不动
+          const activeId = models.length === 1 || !prevActive ? base.id : prevActive
+          writeAiModelsLocal(root, models, activeId)
+          return sendJson(req, res, 200, { model: maskModel(base), activeId })
+        }
+        if (req.method === 'PUT' && id) {
+          // 运行期禁止改动「正在使用」的模型：本轮已把配置快照进 finalConfig，改了不影响这一轮，
+          // 用户却会以为改动已生效 → 下一轮才切。长任务里这种「改了没反应」最容易被当成 bug。
+          if (id === readAiModels(root).activeId) {
+            if (rejectIfTurnRunning(req, res, '有对话正在进行，无法修改正在使用的模型：请先等这一轮结束，或在输入区点「停止」后再改'))
+              return
+          }
+          let body
+          try {
+            body = await readBody(req)
+          } catch {
+            return sendJson(req, res, 400, { error: 'invalid-body' })
+          }
+          const { models, activeId } = readAiModels(root)
+          const idx = models.findIndex((x) => x.id === id)
+          if (idx < 0) return sendJson(req, res, 404, { error: 'model-not-found' })
+          const prev = models[idx]
+          // apiKey 空串 = 清除；未传(undefined) = 沿用原值
+          const apiKey = body.apiKey === undefined ? prev.apiKey : body.apiKey === '' ? '' : body.apiKey
+          // 必填校验：合并后仍须满足（模型名/Base URL 非空；密钥在最终可沿用已存时不强制重填）
+          const vErr = validateModelInput({ ...prev, ...body }, { requireKey: !apiKey })
+          if (vErr) return sendJson(req, res, 400, { error: 'invalid-model', message: vErr })
+          const merged = normalizeModel({
+            ...prev,
+            ...body,
+            id: prev.id,
+            createdAt: prev.createdAt,
+            updatedAt: Date.now(),
+            apiKey,
+          })
+          models[idx] = merged
+          writeAiModelsLocal(root, models, activeId)
+          return sendJson(req, res, 200, { model: maskModel(merged), activeId })
+        }
+        if (req.method === 'DELETE' && id) {
+          const { models, activeId } = readAiModels(root)
+          const idx = models.findIndex((x) => x.id === id)
+          if (idx < 0) return sendJson(req, res, 404, { error: 'model-not-found' })
+          // 删掉正在使用的模型会让 activeId 静默回落，正在跑的回合与下一轮用到的是两个模型
+          if (id === activeId) {
+            if (rejectIfTurnRunning(req, res, '有对话正在进行，无法删除正在使用的模型：请先等这一轮结束，或在输入区点「停止」后再删'))
+              return
+          }
+          models.splice(idx, 1)
+          const newActive = activeId === id ? (models[0] ? models[0].id : null) : activeId
+          writeAiModelsLocal(root, models, newActive)
+          return sendJson(req, res, 200, { ok: true, activeId: newActive })
+        }
+        if (req.method === 'POST' && id && activate) {
+          const { models, activeId } = readAiModels(root)
+          if (!models.some((x) => x.id === id)) return sendJson(req, res, 404, { error: 'model-not-found' })
+          // 这就是核心那条：对话进行中不允许切换生效模型（在跑的回合与新回合会用不同模型）
+          if (id !== activeId) {
+            if (rejectIfTurnRunning(req, res, '有对话正在进行，无法切换模型：请先等这一轮结束，或在输入区点「停止」后再切换'))
+              return
+          }
+          writeAiModelsLocal(root, models, id)
+          return sendJson(req, res, 200, { ok: true, activeId: id })
+        }
+       return sendJson(req, res, 405, { error: 'method-not-allowed' })
+     }
+   }
+
+    // ---------- cc-switch 供应商导入（从 ~/.cc-switch/cc-switch.db 读 Codex 类 provider）----------
+    if (pathname === '/__ai/cc-switch-providers' && req.method === 'GET') {
+      const result = listCcSwitchProviders()
+      return sendJson(req, res, 200, result)
+    }
+
     // ---------- 单次输出上限探测（设置面板「探测」按钮）----------
     if (pathname === '/__ai/probe-maxtokens') {
       if (req.method !== 'POST') return sendJson(req, res, 405, { error: 'method-not-allowed' })
-      const cfg = readAiConfig(root)
+      let body = {}
+      try {
+        body = await readBody(req, 64 * 1024)
+      } catch {
+        return sendJson(req, res, 400, { error: 'invalid-body' })
+      }
+      const saved = readAiConfig(root)
+      // 优先探「表单里正在编辑的那个模型」：新增 / 改地址 / 改模型名时磁盘上的生效配置还是旧的，
+      // 只读 saved 会探错对象（实测：编辑未生效模型时探到的是另一个模型的上限）。
+      // 用 undefined 判定「未传」而非 `||`：`apiKey:''`（新增模型尚未填密钥）是**明确的空值**，
+      // 若回落 saved 就会拿别人的密钥去探别人的模型，把结果记到这个模型的名下
+      const pick = (v, fallback) => (v === undefined || v === null ? fallback : String(v))
+      const cfg = {
+        baseUrl: pick(body.baseUrl, saved.baseUrl || ''),
+        apiKey: pick(body.apiKey, saved.apiKey || ''),
+        model: pick(body.model, saved.model || ''),
+      }
       if (!cfg.baseUrl || !cfg.apiKey || !cfg.model) {
-        return sendJson(req, res, 400, { error: 'missing-config', message: '请先填写 Base URL / API Key / 模型名' })
+        return sendJson(req, res, 400, {
+          error: 'missing-config',
+          message: '请先填写 Base URL / API Key / 模型名（新增模型需先填好密钥才能探测）',
+        })
       }
       capCache.delete(maxTokensSig(cfg))
       windowCache.delete(maxTokensSig(cfg))
       maxTokensMetaMiss.delete(maxTokensSig(cfg))
       const probed = await probeMaxTokensSupport(cfg)
-      // maxTokens = 留空时后端真正会用的值（封顶后）；window = 上下文窗口（仅元数据）；cap = 接受的单次输出上限（试探 / 减半）
+      // cap  = 网关**实测接受**的单次输出上限（二分试探 / 400 减半回写）——探测的唯一「测量值」
+      // window = 上下文窗口（仅来自 /v1/models 元数据，拿不到就是 0）
+      // ceiling = 自动模式的封顶**假设值**，不是测量结果；单独回传让前端明示，勿与 cap 混淆
+      // autoMax = 留空（自动）时后端实际会用的值 = min(cap || window, ceiling)
       return sendJson(req, res, 200, {
         ok: true,
-        maxTokens: autoMaxTokens(probed.cap, probed.window),
-        window: probed.window,
         cap: probed.cap,
+        window: probed.window,
         ceiling: AUTO_MAX_TOKENS_CEILING,
+        autoMax: autoMaxTokens(probed.cap, probed.window),
         source: probed.source || 'fallback',
       })
     }
@@ -2904,6 +3731,69 @@ export function createAiChatMiddleware(opts = {}) {
       }
     }
 
+    // ---------- 回合日志：状态 / 终止 / 续订（P2-12 断线续跑） ----------
+    if (pathname === '/__ai/turns') {
+      if (req.method !== 'GET') return sendJson(req, res, 405, { error: 'method-not-allowed' })
+      const cardId = query.get('cardId') || ''
+      if (!safeCardId(cardId)) return sendJson(req, res, 400, { error: 'missing-card-id' })
+      const live = getLiveJournal(cardId)
+      return sendJson(req, res, 200, {
+        cardId,
+        active: live
+          ? { turnId: live.turnId, startedAt: live.startedAt, seq: live.seq, detached: live.detached, status: live.status }
+          : null,
+        recent: listTurns(root, cardId, 10),
+      })
+    }
+    if (pathname === '/__ai/stop') {
+      if (req.method !== 'POST') return sendJson(req, res, 405, { error: 'method-not-allowed' })
+      let body
+      try {
+        body = await readBody(req, 1024 * 1024)
+      } catch {
+        return sendJson(req, res, 400, { error: 'invalid-body' })
+      }
+      const live = getLiveJournal(body.cardId || '')
+      // 断开连接不再等于终止：停止必须是显式动作，否则一次断网就抹掉几十分钟的建卡
+      if (!live || live.closed || typeof live.stop !== 'function') {
+        return sendJson(req, res, 404, { error: 'no-turn', message: '这张卡当前没有正在跑的回合' })
+      }
+      live.stop()
+      return sendJson(req, res, 200, { ok: true, turnId: live.turnId })
+    }
+    if (pathname === '/__ai/turn') {
+      if (req.method !== 'GET') return sendJson(req, res, 405, { error: 'method-not-allowed' })
+      const cardId = query.get('cardId') || ''
+      if (!safeCardId(cardId)) return sendJson(req, res, 400, { error: 'missing-card-id' })
+      const afterSeq = Number(query.get('afterSeq')) || 0
+      const wantTurn = query.get('turnId') || ''
+      res.statusCode = 200
+      res.setHeader('Content-Type', 'text/event-stream; charset=utf-8')
+      res.setHeader('Cache-Control', 'no-cache, no-transform')
+      res.setHeader('Connection', 'keep-alive')
+      res.setHeader('X-Accel-Buffering', 'no')
+      const turnOrigin = trustedOrigin(req)
+      if (turnOrigin) res.setHeader('Access-Control-Allow-Origin', turnOrigin)
+      res.flushHeaders?.()
+      const live = getLiveJournal(cardId)
+      if (live && (!wantTurn || wantTurn === live.turnId)) {
+        // 活跃回合：先回放 afterSeq 之后的行，再续订新事件；turn-end 时 journal.close 会收尾连接
+        for (const l of live.replay(afterSeq)) sseRaw(res, l)
+        if (live.closed) return res.end()
+        live.subscribe(res)
+        req.on('close', () => live.unsubscribe(res))
+        return
+      }
+      // 没有活跃回合（服务重启过 / 回合已结束）：文件里的历史行一次性回放完就收尾
+      for (const l of readJournalLines(root, cardId)) {
+        if (l.seq <= afterSeq) continue
+        if (wantTurn && l.turnId !== wantTurn) continue
+        sseRaw(res, l)
+      }
+      return res.end()
+    }
+
+
     // ---------- 对话记录 ----------
     if (pathname === '/__ai/history') {
       const cardId = query.get('cardId') || ''
@@ -2922,7 +3812,30 @@ export function createAiChatMiddleware(opts = {}) {
         const id = body.cardId || cardId
         if (!safeCardId(id)) return sendJson(req, res, 400, { error: 'missing-card-id' })
         try {
-          return sendJson(req, res, 200, writeHistory(chatDir, id, body.messages))
+          // 服务端权威历史（P2-13）：浏览器这份是 live 视图副本，回合收尾时服务端已按 turnId 写过。
+          // 这里做「合并校对」而不是整表覆盖：
+          //   ① 同 turnId 的 assistant 消息以服务端那份（serverAuthored）为准，客户端副本丢掉；
+          //   ② 其余按 id 去重（后到的覆盖先到的，客户端补的编辑不丢），无 id 的原样保留；
+          //   ③ 合并后按 ts 稳定排序，用户消息与回答的先后不乱。
+          const stored = readHistory(chatDir, id)
+          const storedMsgs = Array.isArray(stored.messages) ? stored.messages : []
+          const srvTurns = new Set(storedMsgs.filter((m) => m && m.serverAuthored && m.turnId).map((m) => m.turnId))
+          const byId = new Map()
+          const anon = []
+          const put = (m) => {
+            if (!m || typeof m !== 'object') return
+            if (m.id) byId.set(m.id, m)
+            else anon.push(m)
+          }
+          for (const m of storedMsgs) put(m)
+          for (const m of Array.isArray(body.messages) ? body.messages : []) {
+            if (!m || typeof m !== 'object') continue
+            // 客户端的回合中副本：同 turnId 且非服务端权威 → 日志 reduce 出来的那份才是完整轨迹
+            if (m.role === 'assistant' && m.turnId && srvTurns.has(m.turnId) && !m.serverAuthored) continue
+            put(m)
+          }
+          const merged = [...byId.values(), ...anon].sort((x, y) => (Number(x.ts) || 0) - (Number(y.ts) || 0))
+          return sendJson(req, res, 200, writeHistory(chatDir, id, merged))
         } catch (e) {
           return sendJson(req, res, 500, { error: 'write-failed', message: String((e && e.message) || e) })
         }
@@ -2940,6 +3853,8 @@ export function createAiChatMiddleware(opts = {}) {
         const failed = []
         for (const id of cardIds) {
           const r = deleteHistory(chatDir, id)
+          // 回合日志与对话记录同生命周期：只清记录会把 .cache/ai-turns 留成孤儿证据链
+          deleteJournal(root, id)
           if (!r.ok) failed.push({ cardId: id, error: r.error })
         }
         return sendJson(req, res, failed.length ? 207 : 200, { ok: !failed.length, failed })
@@ -3106,6 +4021,18 @@ export function createAiChatMiddleware(opts = {}) {
       maxSteps: Number(config.maxSteps) > 0 ? Number(config.maxSteps) : defaults.maxSteps,
       // 单轮墙钟上限（毫秒）：不限步数后的失控兜底
       turnTimeoutMs: Number(config.turnTimeoutMs) > 0 ? Number(config.turnTimeoutMs) : defaults.turnTimeoutMs,
+      // 保活阈值同样「本次请求 > 设置/环境变量」，与 maxSteps / turnTimeoutMs 一致走 finalConfig
+      stallTimeoutMs: Number(config.stallTimeoutMs) > 0 ? Number(config.stallTimeoutMs) : defaults.stallTimeoutMs,
+      stallRetries:
+        config.stallRetries === undefined
+          ? defaults.stallRetries
+          : Math.max(0, Math.min(20, Number(config.stallRetries) || 0)),
+      reasoningTimeoutMs:
+        Number(config.reasoningTimeoutMs) > 0 ? Number(config.reasoningTimeoutMs) : defaults.reasoningTimeoutMs,
+      autoContinueMax:
+        config.autoContinueMax === undefined
+          ? defaults.autoContinueMax
+          : Math.max(0, Math.min(200, Number(config.autoContinueMax) || 0)),
     }
 
     // 手填值按「网关接受的单次输出上限」主动夹取：与其等网关 400 再减半（白白失败一次请求），
@@ -3124,6 +4051,26 @@ export function createAiChatMiddleware(opts = {}) {
       })
     }
 
+    // 同卡单飞：第二个并发回合直接 409，前端提示「上一回合还在跑」，而不是两条流互相覆盖落盘
+    const turnKey = String(cardContext?.id || '__no-card__')
+    const prevTurn = activeTurns.get(turnKey)
+    // 兜底过期：墙钟上限（turnTimeoutMs）+ 收尾汇总余量，比固定 30 分钟更贴合用户配置
+    const turnLockStaleMs = Math.max(STALE_TURN_LOCK_MS, Number(finalConfig.turnTimeoutMs || 0) + 5 * 60 * 1000)
+    if (prevTurn && Date.now() - prevTurn.since < turnLockStaleMs) {
+      return sendJson(req, res, 409, {
+        error: 'turn-in-flight',
+        message: `这张卡片已有一个回合在跑（${fmtDuration(Date.now() - prevTurn.since)}）：请先终止或等它结束，再发新消息`
+      })
+    }
+    const turnLock = { since: Date.now(), turnTimeoutMs: finalConfig.turnTimeoutMs }
+    activeTurns.set(turnKey, turnLock)
+    /** 释放本回合的单飞锁（幂等：只删自己那把，避免误删接管者的锁） */
+    const releaseTurnLock = () => {
+      if (activeTurns.get(turnKey) === turnLock) activeTurns.delete(turnKey)
+    }
+    // 探测窗口 / 加载工具阶段客户端就断开：锁必须立刻放掉，否则这张卡再也开不了新回合
+    req.once('close', releaseTurnLock)
+
     // 多模态视觉：开关开启 → 先探测网关是否真支持图像（带缓存）；不支持自动降级并在对话里提示一次
     const visionWanted = config.vision === undefined ? defaults.vision === true : Boolean(config.vision)
     const visionProbe = visionWanted ? await probeVisionSupport(finalConfig) : { ok: false, reason: '' }
@@ -3139,6 +4086,7 @@ export function createAiChatMiddleware(opts = {}) {
         root,
       })
     } catch (e) {
+      releaseTurnLock()
       return sendJson(req, res, 500, { error: 'tools-load-failed', message: String((e && e.message) || e) })
     }
     // skill_exec 常驻注册：它只能跑 skills/*/scripts/ 下的脚本（路径形状硬校验、参数不经 shell），
@@ -3189,33 +4137,60 @@ export function createAiChatMiddleware(opts = {}) {
     if (allow) res.setHeader('Access-Control-Allow-Origin', allow)
     res.flushHeaders?.()
 
-    // 前端「停止」= abort fetch = 连接关闭：立刻中止 LLM 请求与工具循环
+    // 回合日志开跑：从这一刻起每个 SSE 事件都带 seq 落盘（sseWrite 里挂钩）。
+    // 它同时是断线续跑的回放源与收尾时服务端权威历史的唯一事实源。
+    const turnId = `t${Date.now().toString(36)}${Math.random().toString(36).slice(2, 8)}`
+    // 本回合的「活卡 id」：模型用 card_rename 改掉当前卡 id 后必须跟着换，
+    // 否则回合收尾写服务端权威历史时会把内容写进已经改名的旧 id 下（凭空造一份孤儿 .cache/ai-chats/<旧id>.json）。
+    let liveCardId = cardContext?.id || ''
+    /** 本回合内发生过 card_rename 时的 {from,to}：用于给模型注入「旧 id 作废」的硬提醒 */
+    let renamedInTurn = null
+    const journal = openJournal({
+      root,
+      cardId: liveCardId,
+      turnId,
+      startedAt: Date.now(),
+      meta: { model: finalConfig.model },
+    })
+    if (journal) res.__turnJournal = journal
+    // 探测 / 加载工具阶段「客户端断开就放锁」到此为止：回合已真实开跑，锁交给 finally 释放，
+    // 否则 detached 续跑期间锁被提前放掉，同卡能再开一轮互相踩 schema
+    req.off('close', releaseTurnLock)
+    sseWrite(res, { type: 'turn-start', turnId, cardId: cardContext?.id || '', startedAt: journal ? journal.startedAt : Date.now() })
+
+    // 传输层断开（刷新 / 断网 / 关标签页）≠ 用户要停：回合转 detached 在服务端继续跑，
+    // 事件全在日志里，重连按 seq 续订即可。真正「停止」是 POST /__ai/stop（置 aborted + abort 上游）。
+    // 旧行为「断开即 abort」会把跑了几十分钟的建卡被一次网络抖动抹掉，代价不对等。
     const abortCtl = new AbortController()
     let aborted = false
-    const onClose = () => {
+    let detached = false
+    /** 主动终止（/__ai/stop）：与客户端断开区分开，界面与日志都如实记「用户停了」 */
+    const stopTurn = () => {
       if (aborted) return
       aborted = true
       abortCtl.abort()
     }
+    if (journal) journal.stop = stopTurn
+    const onClose = () => {
+      if (aborted) return
+      detached = true
+      if (journal) journal.markDetached()
+    }
     req.on('close', onClose)
     req.on('aborted', onClose)
     res.on('close', onClose)
+    /** 本轮是否以报错收尾（finally 里决定日志状态与权威历史的 status） */
+    let turnError = ''
 
     // 上下文预算：多轮对话 + 大工具结果超限时，把早期轮次折叠成摘要（按轮折叠，
     // 保证 assistant.tool_calls 与 tool 结果成对保留），并给前端一条 notice 说明
     const contextBudget = Number(config.contextTokens) > 0 ? Number(config.contextTokens) : DEFAULT_CONTEXT_TOKENS
     const compacted = compactContext(messages, contextBudget)
     if (compacted.droppedTurns) {
-      sseWrite(res, {
-        type: 'notice',
-        message: `对话较长：早期 ${compacted.droppedTurns} 轮已压缩为摘要（最近轮次保留原文），需要细节时 AI 会用工具重读`,
-      })
+      sseNotice(res, `对话较长：早期 ${compacted.droppedTurns} 轮已压缩为摘要（最近轮次保留原文），需要细节时 AI 会用工具重读`, 'info', 'context-compact')
     }
     if (visionWanted && !visionOn) {
-      sseWrite(res, {
-        type: 'notice',
-        message: `已开启多模态视觉，但本轮用不了图像，降级为数值闭环（pixelDiff.match）。原因：${visionProbe.reason || '探测失败'}`,
-      })
+      sseNotice(res, `已开启多模态视觉，但本轮用不了图像，降级为数值闭环（pixelDiff.match）。原因：${visionProbe.reason || '探测失败'}`, 'warn', 'vision-off')
     }
     const fullMessages = [{ role: 'system', content: contextPrompt }, ...toOpenAiMessages(compacted.messages)]
     // 视觉注入点①：用户挂载的图片随本轮 user 消息进上下文（落盘历史不含 base64，重开不重复注入）
@@ -3256,12 +4231,17 @@ export function createAiChatMiddleware(opts = {}) {
         : knownWindow > 0
           ? Math.max(8000, Math.min(DEFAULT_TURN_CONTEXT_TOKENS, Math.floor(knownWindow * 0.7)))
           : DEFAULT_TURN_CONTEXT_TOKENS
-    // 单轮「纯思考」预算：推理网关空转时（只吐 reasoning、迟迟不产出）中止上游并催促重试。
-    // 90s 对设计稿建卡太紧——实测前处理管线跑完、正要建卡时连续思考 90s+ 就被熔断，整轮白跑；
-    // 调到 240s（仍可 config.reasoningTimeoutMs 覆盖），另用 stallTimeoutMs 兜「网关彻底静默」。
-    const reasoningTimeoutMs = Number(config.reasoningTimeoutMs) > 0 ? Number(config.reasoningTimeoutMs) : 240000
-    // 网关静默判定：一个增量都不来才算挂起（与「正在思考」区分开），避免大上下文首 token 慢被误杀
-    const stallTimeoutMs = Number(config.stallTimeoutMs) > 0 ? Number(config.stallTimeoutMs) : 120000
+    // 单轮「纯思考」预算：只吐 reasoning、迟迟不产出时中止上游并催促重试。90s → 240s → 600s 的放宽
+    // 都是实测逼出来的：设计稿建卡单轮思考 200~250s 属正常产出前的酝酿，240s 会误伤健康轮次
+    // （实测一次 246s 思考被判超时，催促后模型只写了一份 IR 草稿就收尾，整轮价值大打折扣）。
+    // 催促到 REASONING_NUDGE_MAX 次仍无产出即**停用**该熔断，改由墙钟兜底：思考时长不再能中断长程任务。
+    const reasoningTimeoutMs =
+      Number(finalConfig.reasoningTimeoutMs) > 0 ? Number(finalConfig.reasoningTimeoutMs) : DEFAULT_REASONING_TIMEOUT_MS
+    // 网关静默判定：一个**字节**都不来才算挂起（与「正在思考 / 正在拼超长工具参数」区分开），
+    // 避免大上下文首 token 慢被误杀。静默后自动重试本步（stallRetries 次），重试耗尽才报错收尾。
+    const stallTimeoutMs =
+      Number(finalConfig.stallTimeoutMs) > 0 ? Number(finalConfig.stallTimeoutMs) : DEFAULT_STALL_TIMEOUT_MS
+    const stallRetries = Math.max(0, Number(finalConfig.stallRetries) || 0)
     let step = 0
     /** 本轮开始时刻：墙钟熔断的基准 */
     const turnStartedAt = Date.now()
@@ -3282,13 +4262,29 @@ export function createAiChatMiddleware(opts = {}) {
     let contextRetries = 0
     /** 网关静默空回复（无正文 / 无工具 / 无 finish 标记）的重试次数：最多 1 次 */
     let emptyRetries = 0
+    /** 网关静默后已自动重试本步的次数：中转网关瞬时静默不该让跑了几十分钟的长程任务整轮报废 */
+    let stallRetriesUsed = 0
+    /** 纯思考已催促次数：到 REASONING_NUDGE_MAX 仍无产出就停用思考熔断（reasoningGuardOff） */
+    let reasoningNudges = 0
+    /** 思考熔断是否已停用：停用后「只思考不产出」不再中止上游，交给墙钟 / 死循环熔断兜底 */
+    let reasoningGuardOff = false
+    /** 自动续跑剩余额度：模型没给完成标记就停手时，自动注入提醒接着跑，不用用户手打「继续」 */
+    let autoContinueLeft = Math.max(0, Number(finalConfig.autoContinueMax) || 0)
+    /** 连续「只吐正文不调工具」的轮数：连续两次就尊重模型停手，避免纯问答被反复续跑 */
+    let textOnlyRounds = 0
     /** 熔断收尾的人话原因：随 turn-ended 事件落进对话记录，重开面板仍看得见「这轮为什么停」 */
     let budgetWhy = ''
     let currentMessages = fullMessages
     /** 本轮工具产出的待注入图像（截图 / 并排对比图）：下一次 callLLM 前打包成一条 user 消息 */
     const visionQueue = []
-    /** 思考熔断后是否已催促重试过一次：重试仍超时才报错，给推理网关一次收敛机会 */
-    let thinkingNudged = false
+    /** 单轮折叠的粘滞游标：只从上次折到的地方往后折，绝不回头改写（前缀缓存纪律②） */
+    let trimFrom = 1
+    /** 上一次真正发给网关的消息序列（只用于比对漂移点，不参与业务） */
+    let lastSentMessages = null
+    /** 前缀被回改的告警一回合只发一次，免得刷屏 */
+    let prefixWarned = false
+    /** 本回合累计用量 + 缓存命中（网关不回 usage 时为 reported=false） */
+    const usageTotal = { steps: 0, promptTokens: 0, completionTokens: 0, cachedTokens: 0, cacheMissTokens: 0, hitRate: 0, reported: false }
     /** 重试轮关闭深度思考：实测推理模型会在思考里逐字拼完整 IR / schema，两轮 240s 都产不出工具调用 */
     let retryNoThinking = false
     /** 深度思考总开关（设置为关时每轮都走 NO_THINKING_BODY） */
@@ -3307,10 +4303,7 @@ export function createAiChatMiddleware(opts = {}) {
         }
         if (!timeNudged && elapsedMs > turnTimeoutMs * 0.8) {
           timeNudged = true
-          sseWrite(res, {
-            type: 'notice',
-            message: `本轮已跑 ${fmtDuration(elapsedMs)}（墙钟上限 ${fmtDuration(turnTimeoutMs)}）：已要求模型优先落盘 / 给结论`,
-          })
+          sseNotice(res, `本轮已跑 ${fmtDuration(elapsedMs)}（墙钟上限 ${fmtDuration(turnTimeoutMs)}）：已要求模型优先落盘 / 给结论`, 'warn', 'wall-clock')
           currentMessages.push({
             role: 'user',
             content: `[系统提醒] 本轮墙钟预算只剩 20%（上限 ${fmtDuration(turnTimeoutMs)}）：立即收敛——优先 card_write / card_patch 落盘或给出正文结论与下一步，不要再读资料、不要开新战线。`,
@@ -3318,10 +4311,7 @@ export function createAiChatMiddleware(opts = {}) {
         }
         // 熔断③软提醒：每 SOFT_NUDGE_EVERY 步催一次收敛，但**不打断**（步数多不等于空转）
         if (SOFT_NUDGE_EVERY > 0 && step % SOFT_NUDGE_EVERY === 0) {
-          sseWrite(res, {
-            type: 'notice',
-            message: `本轮已用 ${step} 步工具调用（步数不设硬顶）：提醒模型收敛，别在同类信息上重复取数`,
-          })
+          sseNotice(res, `本轮已用 ${step} 步工具调用（步数不设硬顶）：提醒模型收敛，别在同类信息上重复取数`, 'info', 'soft-nudge')
           currentMessages.push({
             role: 'user',
             content: `[系统提醒] 本轮已进行 ${step} 步工具调用（不设硬顶，但别空转）：自查是否已拿到足够证据——能落盘就 card_write / card_patch / iterate.mjs 落盘并推进到下一门禁；同类信息只读一次，不要重复读同一份资料、不要重跑同一条命令。`,
@@ -3329,19 +4319,18 @@ export function createAiChatMiddleware(opts = {}) {
         }
 
         // 熔断④上下文：步数不限后工具结果会一路累积，撑爆网关窗口 = 整轮 400 报废。
-        // 每轮发请求前先按预算折叠早期工具结果 / 注入图像（最近 TRIM_KEEP_RECENT 条保持原文）
-        const turnTrim = trimTurnContext(currentMessages, { budgetTokens: turnContextBudget })
+        // 每轮发请求前先按预算折叠早期工具结果 / 注入图像（最近 TRIM_KEEP_RECENT 条保持原文）。
+        // from = 上次折到哪：折叠只前进不回退，历史已折叠的部分保持原样 ⇒ 前缀缓存继续命中
+        const turnTrim = trimTurnContext(currentMessages, { budgetTokens: turnContextBudget, from: trimFrom })
+        trimFrom = turnTrim.from
         // 输入框圆环的数据源：本轮**实际送进网关**的上下文量（裁剪后），有窗口认知时前端按窗口画环
         sseWrite(res, { type: 'context-usage', used: turnTrim.tokens, total: turnContextBudget, window: knownWindow })
-        if (clampNotice) sseWrite(res, { type: 'notice', message: clampNotice })
+        if (clampNotice) sseNotice(res, clampNotice, 'warn', 'max-tokens-clamp')
         if (turnTrim.trimmed) {
           currentMessages = turnTrim.messages
           if (!trimNoticed) {
             trimNoticed = true
-            sseWrite(res, {
-              type: 'notice',
-              message: `单轮上下文接近预算（约 ${turnTrim.before} token，上限 ${turnContextBudget}）：已折叠 ${turnTrim.trimmed} 条早期工具结果 / 图像，最近 ${TRIM_KEEP_RECENT} 条保持原文`,
-            })
+            sseNotice(res, `单轮上下文接近预算（约 ${turnTrim.before} token，上限 ${turnContextBudget}）：已折叠 ${turnTrim.trimmed} 条早期工具结果 / 图像，最近 ${TRIM_KEEP_RECENT} 条保持原文`, 'warn', 'context-trim')
           }
         }
         // 深度压缩：折叠工具结果后仍超预算 ⇒ 整组丢弃最早的工具调用并留摘要。
@@ -3351,12 +4340,12 @@ export function createAiChatMiddleware(opts = {}) {
           const deep = deepCompactTurn(currentMessages, turnContextBudget)
           if (deep.droppedGroups) {
             currentMessages = deep.messages
+            // 丢消息会让下标整体左移：粘滞游标与漂移基准一起作废重来（这一步本来就改写了历史前缀）
+            trimFrom = 1
+            lastSentMessages = null
             if (!deepNoticed) {
               deepNoticed = true
-              sseWrite(res, {
-                type: 'notice',
-                message: `单轮上下文约 ${deep.before} token 超预算 ${turnContextBudget}：已深度压缩最早 ${deep.droppedGroups} 组工具调用为摘要（任务与最近 ${DEEP_KEEP_RECENT} 条保持原文），任务继续`,
-              })
+              sseNotice(res, `单轮上下文约 ${deep.before} token 超预算 ${turnContextBudget}：已深度压缩最早 ${deep.droppedGroups} 组工具调用为摘要（任务与最近 ${DEEP_KEEP_RECENT} 条保持原文），任务继续`, 'warn', 'context-deep')
             }
           }
         }
@@ -3367,7 +4356,12 @@ export function createAiChatMiddleware(opts = {}) {
         let lastDeltaAt = Date.now()
         let roundTimedOut = false
         let roundStalled = false
+        /** 本轮被墙钟打断：墙钟原本只在每轮开头检查，上游永不收尾时循环回不到轮首，整轮会挂住 */
+        let roundWallClock = false
         let finishReason = ''
+        /** 本轮已推给前端的思考字符数 / 工具行数：重试本步时让前端回滚这半截产物，别留下重复正文与幽灵工具行 */
+        let roundReasoningChars = 0
+        let roundToolRows = 0
 
         // 轮级 AbortController：思考熔断 / 静默看门狗只杀当前轮；客户端断开经 AbortSignal.any 一并生效
         const roundCtl = new AbortController()
@@ -3377,8 +4371,39 @@ export function createAiChatMiddleware(opts = {}) {
           if (Date.now() - lastDeltaAt > stallTimeoutMs) {
             roundStalled = true
             roundCtl.abort()
+            return
+          }
+          // 迟迟不产出：超过纯思考预算仍没有正文 / 工具调用（只吐 reasoning，或网关只发心跳字节）。
+          // 判定放在巡检里而不是 reasoning-delta 分支里——stream-alive 让「有字节但无增量」不再触发静默看门狗，
+          // 若仍只在收到思考增量时判定，纯心跳流就能一路挂到墙钟（60 分钟）才被发现。
+          if (!reasoningGuardOff && Date.now() - roundProgressAt > reasoningTimeoutMs) {
+            roundTimedOut = true
+            roundCtl.abort()
+            return
           }
-        }, Math.min(5000, Math.max(500, Math.floor(stallTimeoutMs / 4))))
+          // 墙钟到点也要能打断「一轮永不结束」的流（例如网关一直发心跳却永不收尾）：
+          // 墙钟是文档承诺的「唯一能兜住无限跑下去的闸门」，不能因为卡在流里就失效
+          if (Date.now() - turnStartedAt > turnTimeoutMs) {
+            roundWallClock = true
+            roundCtl.abort()
+          }
+          // 巡检间隔跟随两个阈值里更紧的那个缩放：既不误杀首 token 慢的大上下文请求，
+          // 也能在测试把阈值压到几百毫秒时及时判定
+        }, Math.min(5000, Math.max(250, Math.floor(Math.min(stallTimeoutMs, reasoningTimeoutMs) / 4))))
+        // 前缀漂移自检：命中率掉下来必须能定位到「哪一步开始改了历史」。
+        // 只在改写历史（漂移点落在中段而非追加尾部）时告警，正常追加不打扰用户
+        const drift = prefixDrift(lastSentMessages, currentMessages)
+        const hadPrev = Boolean(lastSentMessages)
+        lastSentMessages = currentMessages
+        if (hadPrev && drift.rewrote && !prefixWarned) {
+          prefixWarned = true
+          sseNotice(
+            res,
+            `本轮历史在第 ${drift.index} 条被改写（前缀缓存从该处起失效，后续 token 按原价重算）：这是上下文超预算后的压缩行为，属预期内的代价`,
+            'info',
+            'prompt-cache-rewrite',
+          )
+        }
         const gen = callLLM({
           baseUrl: finalConfig.baseUrl,
           apiKey: finalConfig.apiKey,
@@ -3398,11 +4423,7 @@ export function createAiChatMiddleware(opts = {}) {
             lastDeltaAt = Date.now()
             switch (evt.type) {
               case 'reasoning-delta':
-                if (Date.now() - roundProgressAt > reasoningTimeoutMs) {
-                  roundTimedOut = true
-                  roundCtl.abort()
-                  break
-                }
+                roundReasoningChars += String(evt.text || '').length
                 sseWrite(res, { type: 'reasoning-delta', text: evt.text })
                 break
               case 'text-delta':
@@ -3412,6 +4433,7 @@ export function createAiChatMiddleware(opts = {}) {
                 break
               case 'tool-call-start':
                 roundProgressAt = Date.now()
+                roundToolRows++
                 sseWrite(res, {
                   type: 'tool-call-start',
                   toolName: evt.toolName,
@@ -3422,13 +4444,32 @@ export function createAiChatMiddleware(opts = {}) {
               case 'finish':
                 if (evt.reason) finishReason = evt.reason
                 break
+              case 'usage': {
+                // 缓存命中率的唯一观测口径：把网关回的 usage 累加成本轮总计，再推给前端
+                const u = evt.usage || {}
+                usageTotal.steps++
+                usageTotal.promptTokens += Number(u.promptTokens) || 0
+                usageTotal.completionTokens += Number(u.completionTokens) || 0
+                usageTotal.cachedTokens += Number(u.cachedTokens) || 0
+                usageTotal.cacheMissTokens += Number(u.cacheMissTokens) || 0
+                if (u.reported) usageTotal.reported = true
+                usageTotal.hitRate =
+                  usageTotal.promptTokens > 0 ? Math.round((usageTotal.cachedTokens / usageTotal.promptTokens) * 1000) / 10 : 0
+                sseWrite(res, { type: 'usage', step, ...usageTotal })
+                break
+              }
               case 'notice':
-                sseWrite(res, { type: 'notice', message: evt.text })
+              sseNotice(res, evt.text, evt.level || 'warn', evt.code || '')
                 break
               case 'tool-calls':
                 roundProgressAt = Date.now()
-                assistantToolCalls = evt.toolCalls
-                for (const tc of evt.toolCalls) {
+                // 工具调用 id 归一：部分网关不回 id，落空串会让「轮内 live」与「下一回合回放」
+                // （回放侧用 call_<下标> 兜底）长出不同形状的同一条消息 ⇒ 前缀缓存从该条起失效。
+                // 在事件发出前补好，前端行匹配与上下文序列化看到的是同一个 id
+                assistantToolCalls = evt.toolCalls.map((tc, i) => (tc?.id ? tc : { ...tc, id: `call_${i}` }))
+                // 前端一行一个调用：没有 tool-call-start 直接来 tool-calls 的网关也要能回滚
+                roundToolRows = Math.max(roundToolRows, assistantToolCalls.length)
+                for (const tc of assistantToolCalls) {
                   sseWrite(res, {
                     type: 'tool-call',
                     toolName: tc.function.name,
@@ -3442,8 +4483,9 @@ export function createAiChatMiddleware(opts = {}) {
           }
         } catch (e) {
           // 熔断 / 看门狗主动 abort 时，上游生成器会抛 AbortError：这不是「用户中止」，
-          // 吞掉后交给下面的 roundStalled / roundTimedOut 分支给出准确原因
-          if (roundStalled || roundTimedOut) {
+          // 吞掉后交给下面的 roundWallClock / roundStalled / roundTimedOut 分支给出准确原因
+          // （漏了 roundWallClock 会让墙钟打断变成一条「请求已中止」错误，丢掉收尾汇总）
+          if (roundStalled || roundTimedOut || roundWallClock) {
             /* 吞掉，走下面分支 */
           } else if (
             contextRetries < 2 &&
@@ -3458,10 +4500,10 @@ export function createAiChatMiddleware(opts = {}) {
             currentMessages = deep.droppedGroups
               ? deep.messages
               : trimTurnContext(currentMessages, { budgetTokens: tight, keepRecent: 4, stubChars: 200 }).messages
-            sseWrite(res, {
-              type: 'notice',
-              message: `网关报上下文溢出（HTTP 400）：已${deep.droppedGroups ? `深度压缩 ${deep.droppedGroups} 组早期工具调用` : '加强折叠早期工具结果'}后自动重试本步，任务不中断`,
-            })
+            // 这一步必然改写了历史（否则不会超窗）：粘滞游标与漂移基准一起作废重来
+            trimFrom = 1
+            lastSentMessages = null
+            sseNotice(res, `网关报上下文溢出（HTTP 400）：已${deep.droppedGroups ? `深度压缩 ${deep.droppedGroups} 组早期工具调用` : '加强折叠早期工具结果'}后自动重试本步，任务不中断`, 'warn', 'context-overflow')
             continue
           } else {
             throw e
@@ -3474,28 +4516,67 @@ export function createAiChatMiddleware(opts = {}) {
           // 输出被截断：本轮的正文 / 工具参数都不可信，别拿去执行（半截 JSON 会得到莫名其妙的报错）
           sseWrite(res, {
             type: 'error',
+            code: 'length',
             message: `本轮输出被单次输出上限（max_tokens=${finalConfig.maxTokens}）截断，结果不可用。请在设置里调高「单次输出上限」，或要求 AI 走紧凑 IR 路线（fs_write 写 .cache/ai-scratch/*.ir.json → expand_ir.mjs 展开），不要一次性输出整份 schema`,
           })
           break
         }
 
+        // 墙钟优先于静默 / 思考重试：到点就走「收尾汇总」这条体面路径，不再叠加重试
+        if (roundWallClock) {
+          budgetReason = 'timeout'
+          break
+        }
         if (roundStalled) {
+          // 网关静默不再「一刀结束整轮」：工具是在流结束后才执行的，此刻本步零副作用，
+          // 原样重试即可——已执行的几十次调用、已落盘的产物、上下文全都不丢。
+          // 只有重试耗尽才报错（用户主动中止走 aborted 分支，上游明确报错走 throw 分支）。
+          if (!aborted && stallRetriesUsed < stallRetries) {
+            const delays = stallRetryDelays()
+            const wait = delays[Math.min(stallRetriesUsed, delays.length - 1)] || 0
+            stallRetriesUsed++
+            sseWrite(res, {
+              type: 'round-retry',
+              reason: 'stall',
+              attempt: stallRetriesUsed,
+              attempts: stallRetries,
+              // 前端据此回滚本轮已渲染的半截产物：重试会重新流式吐一遍，不回滚就是重复正文 + 幽灵工具行
+              dropReasoning: roundReasoningChars,
+              dropText: assistantContent.length,
+              dropTools: roundToolRows,
+              message: `上游 ${Math.round(stallTimeoutMs / 1000)} 秒没有返回任何数据（网关静默）：${
+                wait > 0 ? `${Math.round(wait / 1000)} 秒后` : '立即'
+              }自动重试本步（第 ${stallRetriesUsed}/${stallRetries} 次），已执行的工具与上下文都不丢，任务不中断`,
+            })
+            if (await napUnlessAborted(wait, abortCtl.signal)) continue
+            break
+          }
           sseWrite(res, {
             type: 'error',
-            message: `上游 ${Math.round(stallTimeoutMs / 1000)} 秒没有返回任何数据（网关静默），已中止本轮：请重试或检查模型服务`,
+            code: 'stall',
+            message: `上游 ${Math.round(stallTimeoutMs / 1000)} 秒没有返回任何数据（网关静默）${
+              stallRetries > 0 ? `，已自动重试 ${stallRetriesUsed} 次仍未恢复` : ''
+            }，本轮已停止：请重试，或检查模型服务 / 网络（阈值可在 .env.cb.local 用 AI_STALL_TIMEOUT_MS / AI_STALL_RETRIES 调）`,
           })
           break
         }
 
         if (roundTimedOut) {
-          if (!thinkingNudged) {
-            // 第一次熔断：不报错，插入催促 + **关掉深度思考**再给一轮机会。
-            // 只催促不关思考实测无效：模型继续用思考逐字草拟 schema，第二轮同样超时，整轮 10 分钟零产出。
-            thinkingNudged = true
+          // 纯思考熔断不再「两轮就报错」：长程任务里思考几分钟是正常的，中断的代价远大于多等一会。
+          // 每次都催促 + **关掉深度思考**重试（只催促不关思考实测无效：模型继续在思考里逐字草拟 schema）；
+          // 催促 REASONING_NUDGE_MAX 次仍无产出就停用本熔断，改由墙钟兜底——思考时长不再能中断任务。
+          if (reasoningNudges < REASONING_NUDGE_MAX) {
+            reasoningNudges++
             retryNoThinking = true
             sseWrite(res, {
-              type: 'notice',
-              message: `本轮思考超过 ${Math.round(reasoningTimeoutMs / 1000)} 秒仍无产出：已关闭深度思考并催促模型直接落盘，重试一次`,
+              type: 'round-retry',
+              reason: 'reasoning',
+              attempt: reasoningNudges,
+              attempts: REASONING_NUDGE_MAX,
+              dropReasoning: roundReasoningChars,
+              dropText: assistantContent.length,
+              dropTools: roundToolRows,
+              message: `本轮纯思考超过 ${fmtDuration(reasoningTimeoutMs)} 仍无产出：已关闭深度思考并催促模型直接落盘（第 ${reasoningNudges}/${REASONING_NUDGE_MAX} 次），任务不中断`,
             })
             currentMessages = [
               ...currentMessages,
@@ -3506,11 +4587,12 @@ export function createAiChatMiddleware(opts = {}) {
             ]
             continue
           }
-          sseWrite(res, {
-            type: 'error',
-            message: `两轮思考均超过 ${Math.round(reasoningTimeoutMs / 1000)} 秒仍无产出，已停止。可重试、简化需求或拆成更小步骤`,
-          })
-          break
+          if (!reasoningGuardOff) {
+            reasoningGuardOff = true
+            sseNotice(res, `纯思考已催促 ${reasoningNudges} 次仍无产出：停用思考熔断，本轮改由墙钟上限（${fmtDuration(turnTimeoutMs)}）兜底，不再因思考时长中断`, 'warn', 'reasoning-guard-off')
+          }
+          // 熔断刚停用的这一轮已被中止（零产出）：原样重跑一次，之后不会再因思考时长中止
+          continue
         }
         if (aborted) break
         // 网关静默空回复：无正文、无工具调用、连 finish 标记都没有——多是上游连接中途被切 / 空流。
@@ -3519,19 +4601,44 @@ export function createAiChatMiddleware(opts = {}) {
         if (!assistantToolCalls?.length && !assistantContent && !finishReason && !roundStalled && !roundTimedOut) {
           if (emptyRetries < 1) {
             emptyRetries++
-            sseWrite(res, {
-              type: 'notice',
-              message: '网关返回空响应（无正文、无结束标记，连接可能被切断）：自动重试本步一次',
-            })
+            sseNotice(res, '网关返回空响应（无正文、无结束标记，连接可能被切断）：自动重试本步一次', 'warn', 'empty-retry')
             continue
           }
           sseWrite(res, {
             type: 'error',
+            code: 'empty',
             message: '网关连续两次返回空响应（无正文、无结束标记）：本轮已停止。可重试，或检查模型服务 / 网络',
           })
           break
         }
-        if (!assistantToolCalls?.length) break
+        // 催促重试只为打断「空转思考」：本轮一旦有产出（正文 / 工具调用）就恢复深度思考，
+        // 否则一次思考熔断会把整轮后续所有步骤都降级成无思考模式，长程任务质量明显下滑
+        if (assistantContent || assistantToolCalls?.length) retryNoThinking = false
+
+        if (!assistantToolCalls?.length) {
+          // 自动续跑：模型只吐正文就停手——实测最常见形态是输出「下一步（请确认或直接说「继续」）」
+          // 把控制权甩回用户，而任务其实没做完（IR 写了但 expand_ir 没跑、门禁没过）。
+          // 除非它显式给了 [任务完成] / [需用户确认] 标记，或这是本回合第一次开口（纯问答不该被续跑），
+          // 或已经连续停手两次（尊重模型判断），否则自动注入提醒接着推进。
+          textOnlyRounds++
+          const settled = TASK_SETTLED_RE.test(assistantContent)
+          if (!settled && !aborted && step > 1 && textOnlyRounds < 2 && autoContinueLeft > 0) {
+            autoContinueLeft--
+            sseNotice(res, `任务未完成就停手（没有 ${DONE_MARK} / ${ASK_MARK} 标记）：已自动续跑，不用手动输入「继续」（本回合剩余 ${autoContinueLeft} 次）`, 'info', 'auto-continue')
+            currentMessages = [
+              ...currentMessages,
+              { role: 'assistant', content: assistantContent || null },
+              {
+                role: 'user',
+                content: `[系统提醒] 你没有完成任务就停下了，也没给出 ${DONE_MARK} / ${ASK_MARK} 标记。不要征求确认、不要输出「下一步请说继续」——直接接着调用工具推进到下一个门禁。全部要求都已落地且门禁通过时，才在正文最后单独一行输出 ${DONE_MARK}；确实缺只有用户能提供的信息时，才在正文最后单独一行输出 ${ASK_MARK} 并写清要用户回答什么。${designFlow ? '建卡未跑完 expand_ir + iterate --gate 就不算完成。' : ''}`,
+              },
+            ]
+            continue
+          }
+          break
+        }
+        // 有工具调用 = 任务在推进：重置「只吐正文」计数，下一次停手仍可自动续跑一次
+        textOnlyRounds = 0
 
         // 熔断①原地打转：同工具 + 同参数连续重复（实测最烧钱的失控形态，如反复 fs_read 同一份 spec.json、
         // 反复跑同一条 iterate --set）。第 2 轮先警告，第 3 轮不再执行、直接收尾汇报。
@@ -3547,19 +4654,22 @@ export function createAiChatMiddleware(opts = {}) {
           // 协议要求每个 tool_call 都有对应的 tool 结果：回填「已跳过」再收尾，别留下悬空 tool_calls
           currentMessages = [
             ...currentMessages,
-            { role: 'assistant', content: assistantContent || null, tool_calls: assistantToolCalls },
+            { role: 'assistant', content: assistantContent || null, tool_calls: contextToolCalls(assistantToolCalls) },
           ]
+          // 跳过的原因只写一份、两处共用：前端把它存进对话记录、下一回合原样回传成 `Error: <原因>`，
+          // 与这里推给模型的 live 文本必须逐字节相同（两处各写一份文案 = 又一处前缀漂移）
+          const skipNote = `已跳过——这是连续第 ${repeatRounds} 次完全相同的调用（同工具 + 同参数），说明当前思路拿不到新信息，本轮到此为止。`
           for (const tc of assistantToolCalls) {
             sseWrite(res, {
               type: 'tool-result',
               toolName: tc.function.name,
               toolCallId: tc.id,
-              error: `已跳过：连续 ${repeatRounds} 轮完全相同的调用（同工具同参数），触发死循环熔断`,
+              error: skipNote,
             })
             currentMessages.push({
               role: 'tool',
               tool_call_id: tc.id,
-              content: `Error: 已跳过——这是连续第 ${repeatRounds} 次完全相同的调用（同工具 + 同参数），说明当前思路拿不到新信息，本轮到此为止。`,
+              content: `Error: ${skipNote}`,
             })
           }
           break
@@ -3567,7 +4677,7 @@ export function createAiChatMiddleware(opts = {}) {
 
         currentMessages = [
           ...currentMessages,
-          { role: 'assistant', content: assistantContent || null, tool_calls: assistantToolCalls },
+          { role: 'assistant', content: assistantContent || null, tool_calls: contextToolCalls(assistantToolCalls) },
         ]
 
         for (const tc of assistantToolCalls) {
@@ -3586,6 +4696,16 @@ export function createAiChatMiddleware(opts = {}) {
               case 'card_patch':
                 result = await cardPatch(root, parsedArgs, dispatch, { allowDispatch })
                 break
+              case 'card_rename': {
+                result = await dispatch('card_rename', parsedArgs)
+                // 改名后本卡 id 已变：跟住活卡 id（回合收尾历史落点），并给模型一条硬提醒——
+                // system prompt 里的「当前卡片 ID」是本回合开始时冻结的，它不会自己更新。
+                if (result && result.ok && result.renamed && result.id) {
+                  liveCardId = result.id
+                  renamedInTurn = { from: result.oldId, to: result.id }
+                }
+                break
+              }
               case 'fs_read':
                 result = fsRead(root, parsedArgs, mountedRoots)
                 break
@@ -3608,15 +4728,17 @@ export function createAiChatMiddleware(opts = {}) {
                 result = await dispatch(toolName, parsedArgs)
             }
             const { text, image } = splitToolResult(result)
+            // 推给前端的 result 与下面的模型上下文**同一截断口径**：前端会把它原样存进对话记录、
+            // 下一回合再回传。给前端截得更短（旧值 4000）等于每轮都改写一次历史，前缀缓存从该条起全废
             sseWrite(res, {
               type: 'tool-result',
               toolName,
               toolCallId: tc.id,
-              result: text.slice(0, 4000),
-              truncated: text.length > 4000,
+              result: text.slice(0, TOOL_RESULT_MAX_CHARS),
+              truncated: text.length > TOOL_RESULT_MAX_CHARS,
               image,
             })
-            currentMessages.push({ role: 'tool', tool_call_id: tc.id, content: text.slice(0, 12000) })
+            currentMessages.push({ role: 'tool', tool_call_id: tc.id, content: text.slice(0, TOOL_RESULT_MAX_CHARS) })
             // 视觉注入点②：工具产出的图像先入队，循环末尾打包注入（文本模型下 image 恒为 undefined，零开销）
             if (visionOn && image) {
               visionQueue.push({ caption: `${toolName} 产出的渲染截图`, part: dataUrlPart(Buffer.from(image.base64, 'base64'), image.mime) })
@@ -3631,10 +4753,29 @@ export function createAiChatMiddleware(opts = {}) {
           } catch (e) {
             const errMsg = String(e?.message || e)
             sseWrite(res, { type: 'tool-result', toolName, toolCallId: tc.id, error: errMsg })
-            currentMessages.push({ role: 'tool', tool_call_id: tc.id, content: `Error: ${errMsg}` })
+            // 报错文本同样按统一口径截断：回放侧（toOpenAiMessages）会 slice 到同一上限，
+            // 两处不一致时，一条超长报错（路径回显 / 网关长详情）就会在轮边界改写历史、
+            // 把「这条之后」的前缀缓存整段打掉。Error: 前缀在两侧都算进同一个上限里
+            // 报错文本同样按统一口径截断：回放侧（toOpenAiMessages）会 slice 到同一上限，
+            // 两处不一致时，一条超长报错（路径回显 / 网关长详情）就会在轮边界改写历史、
+            // 把「这条之后」的前缀缓存整段打掉。Error: 前缀在两侧都算进同一个上限里
+            currentMessages.push({ role: 'tool', tool_call_id: tc.id, content: `Error: ${errMsg}`.slice(0, TOOL_RESULT_MAX_CHARS) })
           }
         }
 
+        // 本步里改过卡片 id：必须显式告知模型新 id 已生效、旧 id 作废。
+        // 不加这条，模型会拿 system prompt 里那份冻结的「当前卡片 ID（旧）」继续调 card_write，
+        // 换来一串 404，然后反复重试同样的旧 id 直到熔断——这是改名工具最容易踩的坑。
+        if (renamedInTurn) {
+          const { from, to } = renamedInTurn
+          renamedInTurn = null
+          sseNotice(res, `卡片已重命名：${from} → ${to}（后续调用一律使用新 id）`, 'info', 'card-renamed')
+          currentMessages.push({
+            role: 'user',
+            content: `[系统提醒] 卡片已重命名为「${to}」（原 id「${from}」已不存在）。后续所有卡片工具调用（card_read / card_grep / card_patch / card_write / card_validate / card_screenshot / card_node_models / card_rename 等）**必须改用新 id「${to}」**；对话记录、回合日志与封面已随目录一并迁移，不需要重建。`,
+          })
+        }
+
         // 视觉注入点②收尾：把本轮工具产出的图像打包成一条 user 消息回喂（数值指标仍是收敛判据）
         if (visionOn && visionQueue.length) {
           const batch = visionQueue.splice(0, VISION_INJECT_MAX)
@@ -3652,10 +4793,7 @@ export function createAiChatMiddleware(opts = {}) {
 
         // 连续第 2 轮相同调用：先给一次明确的「换证据链」警告（第 3 轮才熔断），多数模型这一句就能纠偏
         if (!aborted && repeatRounds >= 2) {
-          sseWrite(res, {
-            type: 'notice',
-            message: `连续第 ${repeatRounds} 轮完全相同的工具调用（${loopToolNames}）：已要求换证据链，再重复将熔断收尾`,
-          })
+          sseNotice(res, `连续第 ${repeatRounds} 轮完全相同的工具调用（${loopToolNames}）：已要求换证据链，再重复将熔断收尾`, 'warn', 'loop-warn')
           currentMessages.push({
             role: 'user',
             content: `[系统提醒] 你已连续 ${repeatRounds} 轮发起**完全相同**的工具调用（${loopToolNames}，参数一字不差），结果不会变。立刻换证据链：改参数 / 换工具（如 diff_bands.mjs 取逐带 dy、references/generation_pitfalls.md 查静默丢弃清单），或直接落盘 card_write / card_patch。再重复一次本轮就会被熔断收尾。`,
@@ -3664,7 +4802,7 @@ export function createAiChatMiddleware(opts = {}) {
 
         // 用户设了硬顶且额度快用尽：提前催收敛，别等超限才发现整轮没产出
         if (!aborted && HARD_STEPS > 0 && step === HARD_STEPS - 2) {
-          sseWrite(res, { type: 'notice', message: `本轮工具额度只剩 2 步：已要求模型优先落盘 / 给结论` })
+          sseNotice(res, `本轮工具额度只剩 2 步：已要求模型优先落盘 / 给结论`, 'warn', 'steps-left')
           currentMessages.push({
             role: 'user',
             content: `[系统提醒] 本轮工具调用额度只剩 2 步：立即收敛——优先 card_write / card_patch 落盘或给出正文结论与下一步，不要再读资料。`,
@@ -3686,10 +4824,16 @@ export function createAiChatMiddleware(opts = {}) {
               ? `本轮时长已达墙钟上限 ${fmtDuration(turnTimeoutMs)}（共用 ${step} 步工具调用）`
               : `已达单轮工具调用上限（${HARD_STEPS} 步）`
         budgetWhy = why
-        sseWrite(res, {
-          type: 'notice',
-          message: `${why}：正在汇总进度与下一步，回复「继续」可接着做`,
-        })
+        sseNotice(res, `${why}：正在汇总进度与下一步，回复「继续」可接着做`, 'warn', 'budget-wrap')
+        // 收尾汇总同样要挂静默看门狗：此前只挂用户中止信号，网关在汇总阶段静默就会把整轮永久挂住
+        // （界面一直「生成中…」，既拿不到汇总也拿不到报错）。汇总只是锦上添花，静默就放弃并明示原因。
+        const wrapCtl = new AbortController()
+        // 汇总只认「正文 / 思考增量」为活着：只发心跳字节的网关同样要能被掐掉，
+        // 否则界面会永久停在「生成中…」（汇总调用没有墙钟与思考熔断兜底）
+        let wrapAliveAt = Date.now()
+        const wrapWatchdog = setInterval(() => {
+          if (Date.now() - wrapAliveAt > stallTimeoutMs) wrapCtl.abort()
+        }, Math.min(5000, Math.max(250, Math.floor(stallTimeoutMs / 4))))
         try {
           const wrap = callLLM({
             baseUrl: finalConfig.baseUrl,
@@ -3708,18 +4852,30 @@ export function createAiChatMiddleware(opts = {}) {
             ],
             maxTokens: 2048,
             extraBody: NO_THINKING_BODY,
-            signal: abortCtl.signal,
+            signal: AbortSignal.any([abortCtl.signal, wrapCtl.signal]),
           })
           for await (const evt of wrap) {
             if (aborted) break
-            if (evt.type === 'text-delta') sseWrite(res, { type: 'text-delta', text: evt.text })
-            else if (evt.type === 'reasoning-delta') sseWrite(res, { type: 'reasoning-delta', text: evt.text })
+            if (evt.type === 'text-delta') {
+              wrapAliveAt = Date.now()
+              sseWrite(res, { type: 'text-delta', text: evt.text })
+            } else if (evt.type === 'reasoning-delta') {
+              wrapAliveAt = Date.now()
+              sseWrite(res, { type: 'reasoning-delta', text: evt.text })
+            }
           }
         } catch (e) {
+          const msg = String((e && e.message) || e)
           sseWrite(res, {
             type: 'error',
-            message: `${why}，收尾汇总也失败：${String((e && e.message) || e)}`,
+            code: 'wrap-failed',
+            message:
+              /abort/i.test(msg) && !aborted
+                ? `${why}，收尾汇总因上游 ${Math.round(stallTimeoutMs / 1000)} 秒静默被放弃（上下文已保留，回复「继续」可接着做）`
+                : `${why}，收尾汇总也失败：${msg}`,
           })
+        } finally {
+          clearInterval(wrapWatchdog)
         }
       }
       // 熔断 / 硬顶收尾都补一条持久事件：notice 横幅 6 秒就没了，对话记录里要留得住「为什么停」
@@ -3729,19 +4885,31 @@ export function createAiChatMiddleware(opts = {}) {
       if (!aborted) {
         console.error('[ai-chat] failed:', e)
         const msg = String((e && e.message) || e)
-        sseWrite(res, { type: 'error', message: /aborted/i.test(msg) ? '请求已中止' : msg })
+        turnError = msg
+        sseWrite(res, { type: 'error', message: /aborted/i.test(msg) ? '请求已中止' : msg, code: classifyErrorCode(e) })
       }
       sseWrite(res, { type: 'done' })
     } finally {
+      // 回合日志收尾 + 服务端权威历史（P2-13）：日志 reduce 出的 assistant 消息合并进
+      // .cache/ai-chats/<cardId>.json —— 客户端崩溃 / 关标签页 / 断网不再丢整轮轨迹；
+      // 浏览器随后的 POST 按 turnId 认亲去重，它那份只是 live 视图的副本
+      if (journal) {
+        const finalStatus = aborted ? 'aborted' : turnError ? 'error' : 'done'
+        // usage 随 turn-end 落盘：事后复盘「这轮花了多少、命中多少」不用再翻网关账单
+        await journal.close(finalStatus, { error: turnError, detached, usage: usageTotal.steps ? usageTotal : undefined })
+        if (liveCardId) mergeServerTurn(chatHistoryDir(root), liveCardId, journal.reduce())
+      }
       req.off('close', onClose)
       req.off('aborted', onClose)
       res.off('close', onClose)
+      // 单飞锁在 res.end() 前释放：这张卡立刻能接下一个回合
+      releaseTurnLock()
       if (!res.writableEnded) res.end()
     }
   }
 }
 
-// 单测入口（tools/tests/ai-chat-shell-gate.test.mjs）：网关与压缩是纯函数，直接断言
+// 单测入口（tools/tests/ai-chat-shell-gate.test.mjs / ai-chat.test.mjs）：网关、压缩与错误归一都是纯函数，直接断言
 export {
   assertShellAllowlist,
   segmentCommandWord,
@@ -3749,6 +4917,10 @@ export {
   trimTurnContext,
   deepCompactTurn,
   compactContext,
+  classifyErrorCode,
+  normalizeUsage,
+  prefixDrift,
+  TOOL_RESULT_MAX_CHARS,
 }
 
 export default createAiChatMiddleware