BUG: 同一 DSH_HOME 下多进程并发写同一会话日志，导致 seq 重复、整段历史无法加载

[cow114514true]

环境 Environment

• 包版本 Package: @deepseek-ai/dsh 0.1.0-rc.6（dsh-session-persistence-jsonl 同一版本）
• Node.js: v24.16.0
• OS: Windows
• 数据目录 DSH_HOME: C:\Users\.dsh
• 会话存储格式: session.jsonl.zstd（zstd 多帧追加式 JSONL）

现象 Symptom

加载某个历史会话时整段历史不可用，报错：

history unavailable for session "session-9f666163-e5eb-44a5-b8c3-e9aca6904c3a":
Error: corrupt session log: seq gap in committed region at line 2371 (expected 38426, got 38422)（internal）

• 该错误在 Web 端（127.0.0.1:3080） 和 桌面端 均出现；
• 其余 15 个会话日志均正常，仅此一个损坏。

复现步骤 Repro

1. 启动 dsh Web 后端（监听 127.0.0.1:3080），在某个会话中持续对话（产生大量 append）；
2. 不退出 Web 后端，再启动另一个 DSH 实例（如社区桌面壳 DeepSeek-Harness-Desktop，共用同一 DSH_HOME）并打开/续用同一会话；
3. 两个进程同时向同一个 session.jsonl.zstd 追加事件帧；
4. 退出重启任一实例，加载该会话 → 触发上述错误，历史不可加载。

期望 vs 实际 Expected vs Actual

• 期望：并发写入不应破坏日志；任一实例重启后都能读取完整历史。
• 实际：日志中出现重复 seq 段（事件 38422–38425 被写入两次），加载器判定日志损坏并整体拒绝加载。

根因分析 Root Cause

1. dsh-session-persistence-jsonl 的追加路径（appendLines）只做了单进程内的防重防护（部分写入后按 before 大小截断回滚，注释明确："leaving partial bytes would create duplicate sequence numbers"），没有跨进程文件锁；
2. PersistenceCoordinator 的"串行化"是进程内 per-id promise 链与内存 LRU 独占（源码注释："All per-id operations are serialized"），不覆盖多进程；
3. 两个进程各自持有内存游标。游标滞后的进程在另一个进程已提交 38422–38425 后，又把这 4 个事件追加了一遍 → 文件内 seq 不连续；
4. SessionLogScanner 按设计 fail-loud：发现 seq 不连续且后续出现 turn/end 时直接抛错，整个会话拒绝加载（宁可不可用也不给残缺历史）。

证据 Evidence

• 损坏文件（已备份，未改动原文件前的完整副本）：
  C:\Users\.dsh\sessions\--C-Users-~5218~7545-source-repos-myCode-agent--\session-9f666163-e5eb-44a5-b8c3-e9aca6904c3a\session.jsonl.zstd.corrupt-20260814-230547
• 损坏点：事件 seq 38422–38425 首次出现于 JSONL 第 2368–2371 行，重复出现于第 2372–2375 行（逐字节一致），之后 seq 从 38426 继续，共 129,772 个事件。
• 修复方式（用户侧）：删除 4 行重复副本后，129,772 个事件全部连续、无缺失；加载校验通过（header 有效、以 turn/end 收尾）。
• 影响：数据本身未丢失（重复的是副本），但整个会话的 UI 历史不可访问，需人工离线修复。

建议修复 Suggested Fix

1. append 前校验 seq 起点：追加批次前读取文件尾部已提交的最大 seq，与批内首事件 seq 比对，不一致则拒绝或重放（把 read-modify-append 做成对并发安全）；
2. 或对会话日志文件引入跨进程锁（lockfile / 排他打开）；
3. 加载失败时提供诊断/恢复工具（如导出可读前缀、自动去重修复），而不是只抛 （internal） 错误让用户束手无策；
4. 文档注明：同一 DSH_HOME 同一时刻只允许一个写者进程。

[argszero]

你的报告和 #1333（今天早些时候的另一位用户 Firefly1007 的「seq 序号重复导致对话加载失败」）是同一个 bug 的两次独立命中——你的证据链比我当时给出的分析更完整，等于把那个假设实锤了。我把两边的分析对一下：

与 #1333 的关联

#1333 报的现象是 seq 147517 → 147513 回退（同一段 147513–147516 重复），我当时基于源码给出的判断是：跨进程并发写入——seq = log.length 是每进程实例内契约，进程内单写者由 PersistenceCoordinator 保证（per-id promise 链 + 内存 LRU 独占，coordinator.ts），但跨进程没有锁：appendLines 就是 open(path, 'a') + write + fsync（jsonl index.ts），O_APPEND 只保证单次 write 不撕裂、不保证 seq 不重叠；link() 只保护首次物化。

你的复现（Web 后端 + 桌面壳同开同一会话）和证据（seq 38422–38425 逐字节重复两次）正是"游标滞后的进程在另一进程已提交后又把同批事件追加一遍"的形态——与我推测的机制完全一致。两个独立报告指向同一根因，这个 bug 值得维护者优先处理。

补充几个点

1. zstd 路径同样受影响：你的文件是 session.jsonl.zstd（多帧追加），但追加路径是同一个 appendLines → encodeEventBatch（zstd 时 compressZstdFrame(body)）→ 同一个无锁 open('a')。所以压缩与否都中招。

2. 你建议 1（append 前校验 seq 起点）有 TOCTOU 坑：read（读文件尾最大 seq）→ 校验 → append 三步之间仍有窗口，两个进程可以同时读到同一水位再同时追加。要让 read-modify-append 对并发安全，校验和追加必须原子（如用排他锁文件把 read+append 包起来，或依赖 OS 级 flock/LockFile）。纯"先读后写"不加锁挡不住这个竞态。

3. SessionLogScanner fail-loud 是设计选择（宁可拒绝加载也不给残缺历史），但正如你说的，缺一个恢复工具：既然损坏形态是"整段重复"（数据没丢，只是重复），理论上可以自动去重修复（保留第一份、删后续重复段、校验连续性）。seq 序号重复导致对话加载失败 #1333 的作者也是被同样的"无法恢复"卡住。这个诊断/修复工具可以作为 feature request 提给维护者——SESSION_FORMAT_VERSION = 0，pre-release 阶段改加载策略没有兼容负担。

4. 文档层面：建议在 README/文档明确"同一 DSH_HOME 同一时刻只允许一个写者进程"（你的建议 4），至少让用户避免踩坑；但根本修复还是跨进程锁或 append 原子化。

需要的话，我可以把 #1333 + #1452 两帖的源码证据整理成一份完整的 feature request 草稿（含复现步骤、根因、修复方案 A/B），方便维护者直接跟进。