会话恢复的 end-seed 与 inbox-splice 序列号冲突，历史损坏无法加载

[jorinyang]

会话恢复的 end-seed 与 inbox-splice 序列号冲突，历史损坏无法加载。

复现、预期与验收

• 复现步骤：

  1. 一个长会话运行中，日志尾部为 turn/end（seq 406067）。
  2. 会话被恢复（resume）：Session 以存储日志为 seed 构造，因日志末尾不是 session/end-seed，构造函数自动在 seq = 406068 追加合成标记 session/end-seed（dsh-session 构造函数：if (seed !== void 0 && this.log.at(-1)?.type !== "session/end-seed") this.append("session/end-seed", {})）。
  3. 数分钟后用户发送新消息，经 Inbox.mutate → this.session.append("agent/inbox/spliced", …)（dsh-agent/lib/types/inbox.js）写入。该写入路径持有的 Session 实例 log.length 仍为 406068（未包含 end-seed 标记），于是再次分配 seq = 406068。
  4. 后续事件（turn/start 406069、agent/inbox/spliced 406070…）均基于该过期游标继续写入，整条尾流相对正确序列偏移 1。
  5. 加载历史时，dsh-session-persistence-jsonl 扫描器在物理行 31191 检测到 seq gap，直接抛错，整个会话历史不可用。

• 实际结果：

  • 历史加载失败：history unavailable for session "session-78f369a2-…": Error: corrupt session log: seq gap in committed region at line 31191 (expected 406069, got 406068)
  • 该会话全部 1,830,282 个事件不可读（并非只丢失尾部，而是整个历史加载直接失败）。

• 预期结果：

  • seq 唯一且连续（seq = log.length 契约成立），不同写入路径对同一会话的 seq 分配一致；
  • 或：加载端对"合成事件与后续事件 seq 重复"这类损坏可自动修复（类似现有 torn-tail 的 commitRepair 路径），而不是让整个历史不可读。

• 环境：

  • Windows 11（dsh desktop runtime）
  • @deepseek-ai/dsh、dsh-agent、dsh-session、dsh-session-persistence-jsonl 均为 0.1.0-rc.8
  • 持久化：JSONL + Zstandard 多帧容器（session.jsonl.zstd）

• 证据（日志实测，事件已脱敏）：

  seq 406067  turn/end            上一轮结束
  seq 406068  session/end-seed    time=1787304915720（恢复时自动追加，data={}）
  seq 406068  agent/inbox/spliced time=1787305300717（用户真实消息，target=next-turn）
  seq 406069  turn/start
  seq 406070  agent/inbox/spliced
  seq 406071  step/start
  seq 406072  user/message
  

  • 该会话日志中共有 5 处 session/end-seed（含此冲突处），说明会话被多次恢复；最后一次恢复的标记与 inbox-splice 冲突。
  • 本地修复已验证：删除 seq 406068 的 session/end-seed 行后，全部 1,830,282 个事件恢复连续（seq 0…1830281），Session.fromRestore 校验通过。

• 根因分析：

  • Session.append 的 seq 恒为 this.log.length（dsh-session 的 get seq 与 append），是"按 Session 实例"的本地游标，而非持久化层的权威游标。
  • session/end-seed 由构造函数在"以存储日志为 seed 恢复"时追加；agent/inbox/spliced 由 Inbox 经另一个 Session 引用追加。两个写入者若持有不同的 Session 实例（或同一实例的过期快照），就会分配出相同 seq。
  • 扫描器（dsh-session-persistence-jsonl 的 consumeEventLine）对 seq gap 直接抛错，没有像 torn-tail 那样的自修复路径。

• 建议修复（供维护者参考）：

  1. 加载/持久化层：对"合成标记类事件与下一事件 seq 重复"自动修复（跳过重复的合成事件，或截断到最后一个连续点），并支持修复后的续写（类似 commitRepair）。
  2. seq 分配权威化：inbox-splice 与恢复路径共享同一个 Session 实例；或在 append 时以持久化端最后 seq+1 为准，游标过期则拒绝/重试。
  3. 扫描器对 seq-gap 给出可操作的错误信息（当前错误信息未包含会话 id / 文件路径提示）。

• 验收条件：

  • 该场景下会话历史可正常加载，事件 seq 0…N-1 连续无重复；
  • 修复后"恢复 + inbox-splice"不再产生 seq 冲突；
  • （可选）加载端能自动修复历史中已有的此类损坏。

[argszero]

报告非常扎实——我把整个链路对照 rc.2（HEAD b150a551b8，与 rc.8 该段代码一致）验证了一遍，机制成立，并且你的日志证据本身就把根因钉死了。补充三层：源码锚点、家族定位（这是会话损坏家族的第 12 个机制）、以及读侧自愈的精确规则。

1. 源码锚点（全部确认）

• Session 构造器（packages/core/session/src/index.ts:539-547）：firstLiveSeq = this.log.length 在 :539 捕获，:545-546 当 seed 尾部不是 session/end-seed 时 this.append('session/end-seed', {}) —— 合成标记占用 firstLiveSeq（你的 406068）。
• Inbox.mutate（packages/core/agent/src/inbox.ts:186）：this.session.append('agent/inbox/spliced', splice)，写的是构造时传入的 Session 引用（agent.ts:87 new Inbox(session, …)）。
• 扫描器（packages/session/session-persistence-jsonl/src/format.ts:362-375）：严格连续检查 event.seq !== this.events.length → :367-370 抛 seq gap in committed region，与你的报错文本逐字一致。

2. 日志证据自洽 → 双实例是铁的

你的证据里两条 406068 时间戳相隔 6.4 分钟（end-seed 在前、inbox-spliced 在后）。若两个写者持有同一实例，end-seed 追加后 log.length 已是 406069，inbox-spliced 必然落在 406069。只有两个游标分叉的实例才能让 spliced 也拿到 406068——即 inbox 持有的是恢复前旧实例（或恢复替换了协调器实例但 agent 仍持旧引用）。你的"不同 Session 实例"推断被日志形状直接证实。

3. 家族定位：机制 #12 = 同进程双实例游标分叉

这是会话损坏家族的新机制，与此前最接近的两个区分开：

• Session log unreadable after resume across session/end-seed (seq gap in committed region) #3198（机制 #10，种子短于持久化尾部）：碰撞对是"新实例的活事件 vs 已持久化事件"，种子边界本身是 bug；
• 本报告：碰撞对是"构造器合成标记 vs 另一活实例的真实事件"——end-seed 是实例局部的（构造器只在当前实例上追加），第二个实例的游标正好落后 1。
• 家族共同根因依旧成立：seq = log.length 是实例级契约（index.ts:565-567），append 路径没有任何持久化所有权/序号连续性校验，也没有"一个 session id 只允许一个活实例"的强制。

4. 修复分层（含读侧自愈的精确规则）

• 写侧根因（对应你的修复 2）：inbox 应在 mutate 时从协调器解析当前权威实例，或 agent-loop resume 时转移实例。更普适的兜底 = 家族统一加固里的持久化序号断言：批次首事件 seq 必须 == 已提交长度 + 1，不符则响亮拒绝（Bug: session log corrupted on resume - last 4 committed events re-appended with fresh timestamps (seq gap in committed region) #2167/[BUG] 会话日志损坏：关机中断后 seq 序号冲突——"中断收尾"事件与真实事件的 seq 撞号，导致会话无法加载 #2342 教训：绝不能静默截断——静默截断会丢未刷盘事件）。
• 读侧自愈（对应你的修复 1，可以做得比"跳过重复合成事件"更精确）：session/end-seed 是水印而非状态事件，允许被 seq 相同的真实事件遮蔽——扫描器在"上一条是 end-seed 且下一条 seq == end-seed.seq"时丢弃 end-seed（真实事件赢）。这正是你手动删除的那一行，规则化后是确定性自愈。与 Session log unreadable after resume across session/end-seed (seq gap in committed region) #3198 提出的"end-seed 边界分段重置"互补（那是区域容忍，这是重复遮蔽）。⚠️ 边界：扫描器的严格性本身是完整性底线（[bug] 会话历史加载失败：崩溃恢复与残留执行流并发写同一日志，seq 重叠（corrupt session log: seq gap in committed region） #1586/[BUG] 会话日志损坏：关机中断后 seq 序号冲突——"中断收尾"事件与真实事件的 seq 撞号，导致会话无法加载 #2342 教训，不要弱化解码器），自愈规则必须只限合成标记类事件，真实事件之间的 seq 冲突仍应拒绝。
• 错误信息（你的修复 3，format.ts:368 缺 session id / 路径）：同意，廉价且高价值——1.8M 事件的会话定位全靠行号太痛苦。
• 测试缺口：双实例回归（实例 A 构造器追加 end-seed，实例 B 用旧引用 append → 断言持久层响亮拒绝或扫描器按遮蔽规则自愈）；dsh-doctor 离线检查候选（end-seed 后跟 seq 相同的真实事件 → 标记）。

验收条件里"修复后恢复 + inbox-splice 不再产生 seq 冲突"对应写侧；"加载端自动修复已有损坏"对应读侧规则——两层都做才闭环。需要我贴出扫描器遮蔽规则的改动形态可以随时说。

[xiaoyuyu6420]

跟着 argszero 的源码锚点补一个使用侧的观察（利益相关：dsh-backup 插件作者）：你们定位的家族共性是「恢复路径上出现了第二个写者，seq 从过期游标重新分配」——这意味着损坏往往在用户无感知时已经发生，等打开历史才爆炸。

两个建议给同样场景的人：

1. 手里永远留一份干净基线：/backup auto 12 定时备份（重启不中断）。会话日志损坏这种渐进式问题，备份的意义不是「恢复到坏前一秒」，而是「坏掉之后有路可退」。
2. 坏掉之后别手动删日志碰运气：/backup doctor 会扫描每个会话的结构完整性（seq 连续/帧完整），损坏文件先隔离再入档——隔离区不会被轮换清掉，既保住根因分析的证据，又防止下一轮备份把最后一份好副本轮换走；doctor --repair latest 从最近的好备份定点修复，不用整目录回滚。

写入侧的修复还是得等官方，这帖的分析质量值得被排进修复队列。