会话历史与恢复
选择 load、resume、分页 transcript 或导出，并处理恢复超时和游标失效。
daemon 的实时会话和 SSE 环形缓冲在内存中，持久对话写在磁盘。重启后可以恢复已保存上下文，但不承诺自动重跑未完成任务或重建每个客户端的全部状态。
选择接口
| 接口 | 适合用途 | capability |
|---|---|---|
| POST /session/:id/load | UI 没有历史，恢复并注入当前有限回放快照 | session_load |
| POST /session/:id/resume | UI 已有历史，只恢复 agent 上下文和句柄，不重复 UI 回放 | session_resume |
| GET /session/:id/transcript | 读取完整活动磁盘记录的分页回放 | session_transcript |
| GET /workspaces/:workspace/session/:id/transcript | 明确工作区的活动记录分页 | workspace_persisted_transcript |
| GET /workspaces/:workspace/session/:id/export | 从可信工作区导出完整活动会话附件 | workspace_session_export |
| GET /workspaces/:workspace/session/:id/archive/export | 直接导出已归档记录，不取消归档 | workspace_archived_session_export |
客户端先检查对应 capability。不要仅凭 session_export 或 workspace_qualified_rest_core 推断 secondary 支持导出；旧版本可能只导出 primary。当前 Web Shell 活动会话导出仍为 primary，归档行在能力存在时支持可信 primary/secondary。
load 的快照不是完整 transcript，受 compactedReplay 和当前 liveJournal 限制；缺历史时以 history_truncated 开头。resume 的旧 capability 别名 unstable_session_resume 仅用于兼容。
分页与导出
curl -H "Authorization: Bearer $QWEN_SERVER_TOKEN" \
"http://127.0.0.1:4170/session/$SESSION_ID/transcript?limit=100"先把 SESSION_ID 设为目标。分页事件没有实时事件 ID，不会通过这条读取附着客户端、创建 live session 或改变 SSE 窗口。limit 指活动聊天记录数，不是最终回放帧数；一条记录可生成多帧。向后分页为保留轮次和工具调用/结果边界，可扩展到最多 3 倍 limit。
第一页冻结 JSONL 快照大小，之后忽略新追加。hasMore 为 true 时用 nextCursor 继续；文件被删除、截断、替换、归档或与游标冲突则返回 409。过大快照在索引前返回 413 transcript_too_large，避免请求路径无限扫描。
工作区限定的正向页与 cursor 页由 daemon 本地读取；live session 的向后第一页可能通过 ACP 刷新持久尾部。此类游标只在当前 daemon 生命周期有效，重启后从第一页重新开始。
导出支持 html、md、json、jsonl。归档导出不会退回活动存储或 primary，活动但未归档的 ID 返回 409 session_not_archived。
恢复竞争与超时
同一 ID 的同类恢复请求会合并；load 与 resume 竞争，或指定 ID 的创建与恢复竞争，返回 409 restore_in_progress，通常 Retry-After 为 5 秒。
默认恢复期限 60000 毫秒；显式 initialize-timeout-ms 更长时会提高默认恢复预算，不会因更短初始化期限而缩短。SDK 和 Web Shell 分别增加 10 秒与 15 秒客户端余量。
超时返回可重试的 504 session_restore_timeout，不证明 daemon 已退出。未完成 child 请求仍被隔离，清理期间同 ID 重试返回 restore_in_progress、reason 为 awaiting_abandoned_cleanup，Retry-After 按预算限制在 5–120 秒。
清理无法确认或超过额外预算仍未结束时，新会话可能暂时收到 503 acp_channel_unavailable，reason 为 restore_cleanup_failed 或 restore_settlement_overdue。新会话初始化也有对应 new_session_cleanup_failed、new_session_settlement_overdue。已经 live 的会话仍可使用，不应因某次恢复观察超时就重启整个 daemon。
崩溃与读取成本
ACP 子进程崩溃会发 session_died 并移除 live 记录；只要能启动新子进程，磁盘会话仍可 load。daemon 重启丢失正在运行的内存会话和回放环，但不删除持久历史。文件原子写入只保证写入落地方式，不自动重放操作。
旧单数 transcript 路由在 channel-idle-timeout-ms 默认 0 时，空闲 ACP 可能每页后即退出，导致后续页重新启动并扫描快照。连续读取可配置正的 idle grace；容量回收仍可能提前收回 idle child。工作区限定正向/cursor 页避免这条重复 ACP 路径。
官方 Local Deployment 旧段落写“重启只可新建”，应以主章现有 load/resume 和磁盘恢复说明为准。应用级队列、未完成副作用和业务事务仍需由调用方设计恢复。