feat(session): add turn-aware retention and reliable archive recovery

[yeshion23333]

背景与目标

本 PR 落地 RFC #3330：

用 Turn 保证语义完整，用 token budget 控制长度，用目录状态保证消息不丢。

原有 keep_recent_count 按物理 Message 数量切分。在工具密集型对话中，一次 User 请求可能展开成多条 assistant/tool 消息，导致 active context 从 assistant 开始、call/result 被拆开，或单个长 Turn 长期占满上下文。同时，异步 commit 期间的 pending/failed archive 还存在原始消息暂时或永久不可见的风险。

本次改动目标：

• 保留真实 User query，并将同轮 assistant text + tool calls + results 作为原子 Step；
• 使用 Turn 数与 token budget 共同约束 retained messages；
• 对超长 Turn 生成 checkpoint，仅保留最近 raw tail；
• 根据 archive 目录状态恢复 pending/failed 原文，确保消息不丢；
• 保持 latest_archive_overview + messages 的公开返回结构兼容。

改动概览

维度	改动前	改动后
保留边界	最后 N 条物理 Message	最近 K 个逻辑 Turn + token budget
Assistant/Tool 关系	可能在边界处拆开	Assistant Step 原子保留或整体归档
超长 Turn	全量保留或按 Message 截断	User anchor + checkpoint + recent raw tail/final
Tool 输出限制	单 Assistant Message 聚合	完整逻辑 Turn 聚合并 externalize
Pending 判定	依赖 commit_count 与 marker	完全根据 archive 目录状态
Failed archive	原文可能退出上下文	未覆盖原文恢复为 logical live，并由后续成功 commit 收敛
Get 预算	可能受 commit retention 配置隐式影响	仅由 get_session_context(token_budget) 控制本次读取

1. Turn-aware retention

• Message schema 增加可选字段：turn_id、message_kind、source_message_ids；旧消息仍可通过 role/parts 推断。
• 新增纯 Retention Planner，将消息组织为 User Turn 与 Assistant Step；Step 不跨 retained/archive 边界拆分。
• 新增 turn_budget 模式及 keep_recent_turn_count、retained_message_token_budget、min_raw_tail_steps 参数。
• 单个最新 Turn 超预算时，完整保留 User anchor、最近 Assistant Steps 和 final assistant，将较早 Steps 归档。
• Tool 输出按完整 Turn 聚合计算 externalization 阈值，完整结果继续保存到 tool-results/。

2. Checkpoint 与 Working Memory

• 对被部分归档的长 Turn，在 User anchor 后插入 message_kind=checkpoint 的 ContextPart，连接归档前缀与保留的 raw tail。
• Working Memory overview 与 checkpoint summaries 由现有 Phase 2 LLM 调用一次返回两个产物，不增加额外 LLM 调用。
• checkpoint 保存 server-owned 的 anchor/source message IDs；读取时使用持久化摘要，最终统一由 get 请求预算裁剪。
• 不保存模型私有 reasoning。

3. Archive 状态与恢复

• 统一扫描 pending、completed、failed、invalid/uncovered 状态；commit_count 仅保留为统计信息。
• context 按 latest completed overview + uncovered pending/failed raw + root messages.jsonl 组装，并按 message ID stable dedup。
• failed archive 原文恢复为 logical live；后续成功 archive 通过 coverage range/covered_failed_archives 将其 roll forward 到新 overview。
• working_memory=false 的已完成 archive 保持归档，不把 raw 放回 active；旧 .done marker 继续兼容。
• 强化 Phase 1 持久化顺序、session root lock、stale worker snapshot 与 enqueue/rewrite 失败恢复，避免并发 append/commit 丢消息。

4. API、SDK 与 VikingBot 接入

• Commit API、Python client/SDK、HTTP compatibility layer、MCP 与生成类型均支持新的可选 retention 参数。
• 未传 retention_mode=turn_budget 时继续沿用 keep_recent_count，现有接入无需修改。
• get_session_context(token_budget) 独立控制本次 overview + messages 返回预算；retained_message_token_budget 只用于 commit 阶段。
• VikingBot 保留原始中间 assistant/tool 关系后提交到 OpenViking，并过滤内部 auto_memory_search；默认保留 3 个 Turn、6000 retained tokens、1 个 raw tail Step。
• VikingBot 的旧配置 commit_keep_recent_count 继续保留，避免已有配置解析失败。

行为与兼容性

• OpenViking Core 的新 retention 模式为显式 opt-in；未使用新参数的服务保持原有行为。
• 公开 context 字段和存储主结构不变；新增 marker/meta 字段均为向后兼容扩展。
• VikingBot 启用 session context 时改用 Turn-aware retention，active 切分边界会从物理 Message 数切换为逻辑 Turn。
• 任意已接受消息始终至少存在于 overview coverage、uncovered archive raw 或 root live messages 之一。

Human Involvement

• A human participated in the implementation or review loop
• This PR was generated entirely by AI agents without human participation in the loop

Related

• RFC：OpenViking Session 上下文优化 #3330
• 背景改动：VikingBot 保留原始 assistant/tool 关系 #3236

Type of Change

• Bug fix (non-breaking change that fixes an issue)
• New feature (non-breaking change that adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation update
• Refactoring (no functional changes)
• Performance improvement
• Test update

Testing

• 新增 Turn/Step planner、checkpoint、Tool externalization、pending/failed recovery、coverage、并发持久化和 VikingBot 接入测试。
• Session context/retention：55 passed。
• Session API：31 passed。
• VikingBot 相关单测：26 passed。
• Ruff 与 git diff --check 通过。
• 测试平台：macOS。

Checklist

• 代码符合项目现有风格，并通过静态检查。
• 已完成自查，关键并发、恢复与兼容分支均有回归测试。
• 复杂状态转换和边界条件已补充代码注释。
• RFC 已记录设计目标、状态模型和兼容策略。
• checkpoint 复用现有 Working Memory 调用，不增加额外 LLM 消耗。

Additional Notes

• PR 当前保持 Draft，便于继续验证大规模/多 worker 场景后再转 Ready for review。

[qin-ctx]

Turn-aware retention 与归档恢复的总体方向合理，但当前仍有两处会破坏核心上下文保证的阻塞问题：核心预算规划可能丢掉最新 final Step，VikingBot 的最终二次裁剪也可能重新丢掉 user anchor。请修复 inline comments 中的两个边界场景后再合并。