# 修复切换对话消息气泡消失计划

## 目标

修复会话切换时“用户消息气泡暂时消失”的前端缓存状态错误，并保留对
WebSocket 半断导致切换超时的证据与边界；通过回归测试证明部分历史快照
不会再被当作完整会话缓存。服务不重启，避免影响其他运行中的对话。

## 验收标准

- 会话 A 历史大于初始窗口时，`session_info` 的 `historyCursor > 0`、
  `historyPending = false` 快照不能命中 strong cache；A → B → A 必须重新
  请求 `load_session`，不能只显示最近窗口。
- 完整快照必须同时满足：`complete = true`、`historyPending = false`、
  `historyCursor = 0`、`historyBaseIndex = 0`、`historyTruncated = false`、
  `historyBuffered >= historyTotal`。
- 历史分片按稳定消息索引合并；只有最后一页使游标归零时才写入完整缓存，
  旧分页或旧切换响应不能污染当前会话。
- 完整快照仍可 strong cache 命中；部分快照不会直接渲染为缓存会话。
- 客户端应用层心跳每 15 秒探测一次，连续 10 秒未收到服务端应答就主动关闭
  当前连接并复用现有重连/切换请求重放；服务端原生 pong 心跳仍负责底层连接。
  真实代理半断链路不在本轮浏览器自动化模拟范围。

## 阶段

- [完成] 1. 核对会话数据、WebSocket 协议和缓存根因
- [完成] 2. 增加部分历史快照缓存回归测试
- [完成] 3. 修复快照完整性判定与完整加载收口
- [完成] 4. 运行静态检查和回归测试
- [完成] 5. 汇总运行态限制、根因和剩余风险
- [完成] 6. 修复旧服务端与新版前端心跳协议不兼容，并补充断线提示/单一高亮收口

## 验证命令

```bash
node --check public/app.js
node --check server.js
node --check scripts/regression.js
node scripts/regression.js --target session-switch-race
node scripts/regression.js --target history-recall
node scripts/regression.js --target codexapp-stale-running
node scripts/regression.js
git diff --check
```

## 错误记录

| 旧版 PM2 服务端不认识 `client_heartbeat` | 前端先于服务端重启上线心跳 | 增加 `auth_result.features.clientHeartbeat` 能力闸门，并静默兼容旧错误 |
| 完整回归首次出现 `historyLoadMore is not defined` | 首次运行时测试进程与临时服务异常退出，定向回归可复现通过 | 重新运行完整回归已通过，未发现新的历史控件故障 |