[BUG] 两个 dsh web 实例并发打开同一会话，导致会话日志 seq 冲突、历史记录损坏

[2522669008-zcy]

[BUG] 两个 dsh web 实例并发打开同一会话，导致会话日志 seq 冲突、历史记录损坏

描述

当两个 dsh web 服务器实例（不同端口，如 3080 / 3081）共用同一个 DSH_HOME（~/.dsh），并在同一时间段内打开同一个会话并各自发送消息时，两个实例会各自基于日志尾部计算下一个 seq（log.at(-1).seq + 1），向同一个 session.jsonl.zstd 文件追加事件，导致两条事件获得相同/重叠的 seq。随后该会话的历史记录无法加载。

复现步骤

1. 启动第一个实例：npx @deepseek-ai/dsh web（端口 3080）
2. 启动第二个实例：npx @deepseek-ai/dsh web --port 3081（共用同一 ~/.dsh）
3. 在两个实例中都打开同一个会话，并在轮次边界（上一轮刚结束时）分别发送消息
4. 会话日志出现 seq 重复或回退，session.history / 会话列表加载失败

实际报错（两种形态）

• 形态一（seq 回退/断层）：

  corrupt session log: seq gap in committed region at line 11507 (expected 163616, got 162749)
  

• 形态二（turn 边界两个事件同 seq）：
  session/end-seed 与 agent/inbox/spliced 两个事件同时写入同一个 seq（如 138879），
  加载器报 event.seq 不连续。

期望行为

• 同一会话的日志不应被多个进程并发追加；应加锁、拒绝第二个写者，或检测到 seq 冲突时明确报错，而不是静默写坏日志。
• 至少应在错误信息中提示"疑似多实例并发写入"。

环境

• Windows 11
• Node.js v24.19.0
• @deepseek-ai/dsh 0.1.1-rc.2

补充

损坏日志可通过重建帧结构（header 单独一帧 + 事件帧）并把冲突片段重编号为后续 seq 来修复，用户侧可恢复，但过程繁琐且需要手动校验，希望能在产品层面避免。

---

给后来者的提醒（血泪教训 😅）

1. 不要同时在两个端口（两个 dsh web 实例）打开并操作同一个会话——两个实例会各自为下一轮分配 seq 并写入同一份日志，直接造成 seq 重叠/回退，日志损坏。

2. 测试插件或做实验时，请新开一个会话——不要反复"继续"同一个主会话（尤其是上一轮刚结束时紧接着再发消息），避免在轮次边界触发第二个会话实例。更稳妥的做法是用独立的 DSH_HOME 测试，例如 DSH_HOME=C:\Users\你的用户名\.dsh-test npx @deepseek-ai/dsh web。

修复方法参考（如果已经坏了）

• 推荐：dsh-session-surgeon（感谢 @xiaoshenming 的推荐）——先 dry-run 看会丢失多少内容，再 apply（会自动生成 .bak.<utc> 备份），裁切到缺口前最后一个完整回合。安装命令：dsh plugin --profile web add "github:xiaoshenming/dsh-session-surgeon#main"。
• 另一个思路：让 Agent 来修——如果你本机的 dsh（或其他能读写文件的 Agent）能打开这份日志，也可以直接让 Agent 修复（重建日志、保留全部内容）并自行验证加载是否正常，我这次就是用这个方式修好的。

[xiaoshenming]

两个 dsh web 共用 ~/.dsh 写同一会话，就是 committed 区 seq 重叠/回退。官方不会自动修好那份文件。

dsh-session-surgeon 可以 dry-run 看会丢掉多少，再 apply（先 .bak.<utc>），裁到缺口前最后一个完整回合。不会把冲突片段重编号接到后面（那是发明 seq）。

dsh plugin --profile web add "github:xiaoshenming/dsh-session-surgeon#main"

修好之后尽量不要再双开写同一 session。

[2522669008-zcy]

谢谢回复！ 也感谢推荐 dsh-session-surgeon——如果以后再有类似情况，我会优先用它的 dry-run + apply 流程，比手工处理安全得多。

这个 bug 我已经自行修复了（重建了会话日志并保留了全部内容，已通过加载验证），现在会话恢复正常。

顺便给后来者两个小提醒（都是我实际踩过的坑 😅）：

1. 不要同时在两个端口（两个 dsh web 实例）打开并操作同一个会话——两个实例会各自为下一轮分配 seq 并写入同一份日志，直接造成 seq 重叠/回退，日志就坏了。
2. 测试插件或做实验时，请新开一个会话，不要反复"继续"同一个主会话（尤其是上一轮刚结束时紧接着再发消息），避免在轮次边界触发第二个会话实例。更稳妥的是用独立的 DSH_HOME 来测，比如：DSH_HOME=C:\Users\你的名字\.dsh-test npx @deepseek-ai/dsh web

感谢(｡>﹏<｡)

[2522669008-zcy]

我也实际测试了 dsh-session-surgeon，反馈一下效果 ✅

测试样本：一份真实的"双实例并发写同一会话"损坏日志（1403308 字节 / 1009 帧 / 11535 行），seq 缺口在 line 11507（expected 163616, got 162749）。

诊断：scan / inspect 非常准确——报出的错误与 DSH 加载器完全一致（seq-gap-committed），一眼定位到问题点和行号。

修复效果（repair --apply）：

• 自动备份原文件（.bak.<UTC>）✅
• 成功裁切掉 seq 冲突的异常片段：缺口后重复写入的 28 行"幽灵"turn 86（seq 162749–163083）
• 保留到缺口前最后一个完整回合：turn/end 87（seq 163615），此前内容一条不少
• 修复后文件：145 帧 / seq 0–163615 完全连续 / 末事件 turn/end 87 / afterHealth: ok；我还用独立扫描验证了帧结构与 seq 连续性，均通过

发现一个 Windows 上的问题：--apply 在 Windows 会报 EPERM: operation not permitted, fsync。定位到 encode.mjs 的 backupThenWrite：它用只读句柄（O_RDONLY）打开备份文件后调用 sync()，Windows 的 FlushFileBuffers 对只读句柄返回拒绝。本地去掉该只读 fsync 后一切正常。建议跳过只读句柄的 sync（或改用写句柄打开）。

一个使用建议（供参考）：裁切策略很稳健（保底不保全），但会丢弃冲突片段的内容。如果后续能提供"保留冲突片段、重编号续接为后续轮次"的可选模式，就能兼顾全部内容不丢，两种思路可以互补。

tip：ds老师真的很厉害(๑•̀ㅂ•́)و✧

[2522669008-zcy]

后续进展总结（均已实测验证）

把这个问题的完整闭环分享给大家：

1. 根因
两个 dsh web 实例共用同一 ~/.dsh 并打开同一个会话时，两个实例各自基于日志尾部分配 seq、写入同一份 session.jsonl.zstd，造成 seq 重叠/回退，日志损坏。

2. 预防（两道保险，都实测过 ✅）

• dsh-single-instance-guard：同一 DSH_HOME 下第二个实例启动即被锁拦截，报错含 pid / 启动时间 / 锁文件路径。实测：启动第二个实例被成功阻止。
• 独立数据目录做测试：测试环境用 DSH_HOME=~/.dsh-test npx @deepseek-ai/dsh web --port 3081，与正式环境（~/.dsh:3080）完全隔离。实测：即使两个环境同时写入"同一个会话"，写入的也是各自目录里的不同文件副本，对原始 ~/.dsh 零影响——这是比"新开会话"更彻底的隔离方式，测试插件/实验首选。

3. 恢复（两种思路都验证可用）

• dsh-session-surgeon（裁切）：dry-run 预览损失 → apply 自动备份后裁到缺口前最后一个完整回合。实测对"双实例 seq 冲突"样本有效。注意：Windows 上 --apply 有一个只读句柄 fsync 报 EPERM 的 bug（encode.mjs 的 backupThenWrite），本地去掉该 fsync 后正常，建议作者修复。
• Agent 合并修复：保留主线程 + 把冲突片段重编号续接为后续轮次（内容全部保留），用 DSH 加载器验证通过。适合"一条都不想丢"的场景。

4. 经验教训

• 同一 DSH_HOME 只跑一个 dsh 实例；
• 测试插件/实验用独立 DSH_HOME（如 ~/.dsh-test），而不是换端口共用正式目录；
• 装 guard 插件把"双开"从"静默损坏"变成"启动即失败"。

5. 相关官方讨论

• #1452 同一 DSH_HOME 下多进程并发写同一会话日志，导致 seq 重复、整段历史无法加载——官方仓库中同一根因的 bug 报告
• #2571 会话日志损坏诊断报告——完整诊断、只读巡检工具与手动修复步骤（dsh-single-instance-guard 的 README 也引用了它）

[xiaoshenming]

感谢实测，尤其是那份 11535 行 / seq-gap-committed 的真实样本——inspect 对上官方 loader、apply 裁到缺口前最后一个完整 turn/end，正是这个插件该做的事。

Windows 上 --apply 在 .bak.<utc> 已经拷完之后，对只读备份句柄 fsync 报 EPERM，是 backupThenWrite 的真实 bug（encode.mjs）。已经修在 main（40c18bdd）：备份尽量用可写句柄同步；Windows / 某些网络盘上的 EPERM / ENOTSUP 视为 best-effort，不再中止后面的原子替换。请再 dsh plugin --profile web add "github:xiaoshenming/dsh-session-surgeon#main"（或拉最新 main）后试一次 apply。

仍然不会把冲突片段重编号接到后面——那是发明 seq。内容一条都不想丢的话，你帖里的 Agent 合并方案仍然是另一条路；我们只做「官方能重新 load」的截断。

双开预防继续听你的：不要两个 dsh web 写同一 session；测试用独立 DSH_HOME。

[yhfgyyf]

我也遇到过很多次，多个web app和tui开启同一个session，只要进入就会报错，做了一个跨session的host后修复

[denial123789]

I updated an independent recovery runbook with the prevention boundary from this report: https://github.com/sandbaseai/deepseek-harness-handbook/blob/main/docs/en/troubleshooting/duplicate-committed-session-seq.md

The key operational distinction is that changing only the port does not isolate persistence. Use a separate DSH_HOME for experiments; treat guard/surgeon plugins as discovery-only until their exact artifacts and effects are audited.

[2522669008-zcy]

Thanks for picking this report up into the handbook runbook and for crediting it — glad the prevention notes were useful.

The seq-duplication problem in this thread is resolved on our side, so we are closing it here.

One pointer in case it helps the page: the 0.1.5 converter refusals (assistant/message … chunk provenance is not one complete ordered attempt) were reported separately yesterday in #6175 — you have probably seen it already.

[MedicineKing]

同簇问题（同 #1497：seq 重叠/回退导致 committed 区拒读）。两条不丢历史的解法（官方未打补丁 0.1.1-rc.2 实测：931,455 事件零 seq gap，Session.fromRestore 通过）：

1. 读端容错补丁：SessionLogScanner 遇到已消费过的旧 seq（回退/重复/重叠段）时改为跳过而不是整体拒读——磁盘上的所有已提交内容零裁切保留。双实例并发撞号——读端容忍救回已坏文件；预防是别让两个实例写同一会话（zcy 的闭环已覆盖）；两者互补。
2. 零安装 CLI（dsh-corrupt-session-repair）：node dsh-corrupt-session-repair.mjs 扫描（只读）→ fix 预览 → fix --apply（先写 .bak.zstd；写回与官方同款 checksum 帧——header 单独一帧，assertZstdHeaderFrame 直接接受）。真跳号/物理损坏只报告、绝不重写。

已坏在磁盘上就用 2；想让未来崩溃也看不见就上 1。

[2522669008-zcy]

追加：升级到 dsh 0.1.5-rc.1 后，此前修复过的会话再次无法加载（chunk 溯源校验）

现象

把 dsh 从 0.1.1-rc.2 升级到 0.1.5-rc.1 后，本贴中修复过的会话（session-fd18fa92-…）重新无法打开，服务端报：

failed to observe session "session-fd18fa92-…":
assistant/message 139130 chunk provenance is not one complete ordered attempt;
source v0 artifact remains unchanged

注意最后一句：迁移失败时保留原始 v0 文件不变，所以不会造成进一步损坏——这一点体验很好。

根因

0.1.5 引入了会话格式 v0 → v2 迁移，迁移时会校验 assistant/message 的 sourceEventSeqs（chunk 溯源）必须与实际 chunk 序列完全一致（长度相同、逐个 seq 相等）。

而此前为修复"seq 重复/回退"所做的手工修复（把冲突片段重编号续接）只改了事件的 seq 字段，没有同步事件内部的 sourceEventSeqs 引用。旧版不校验该字段，因此一直正常；新版一旦校验便拒绝加载。

本例中恰好 4 条消息的溯源数组仍是旧编号（长度都对，只是整体偏移）：

消息 seq	轮次	需要的偏移
139130	67	+1
140110	68	+1
140388	69	+1
163948	88	+867

前三处来自一次"+1 整体重编号"的修复，第四处来自一次"把冲突片段接到日志尾部（+867）"的修复。

修复方法

对每条 assistant/message：

1. 从日志重建它所属 attempt（同 turn + step）的实际 chunk seq 序列；
2. 与其 sourceEventSeqs 逐项比较；
3. 若长度一致且偏移均匀，则按该偏移重写数组（非均匀偏移则拒绝修复，避免猜测）。

本次只改动了这 4 个数组，其余 12818 行原样保留。

修复后验证：

• 本地校验：溯源问题 0、seq 全程连续、末 seq 不变（179943）；
• 服务端：session/page 返回 ok: true，可正常读取历史记录；
• 修改前文件已完整备份。

可复现性

可复现：任何"重编号过 seq 但未同步内部引用"的会话，在 0.1.5+ 上都会触发同一错误。错误信息带具体 seq 与事件类型，便于定位。

对修复工具的启示

• 采用"裁切"策略的工具（如 dsh-session-surgeon）天然避开该问题：裁切不改变幸存事件的编号；
• 但任何"重编号续接"方案（把冲突片段接到日志尾部）必须同步重映射事件内部的跨引用，至少包括：
  • assistant/message.sourceEventSeqs（本次遇到）
  • 可能存在的 tool/result.sourceEventSeqs
  • compaction 的 shadowedRange
  • surface 替换的 start / end 等范围引用

附：新版诊断接口变化（供工具作者参考）

• Web 端启用了 Cookie 鉴权：直接请求首页也会返回 401，需先访问 dsh web 打印的带 launch token 的 URL；
• 旧接口 session.history 已由 session/page 取代，入参形如
  { request: { address: { kind: "session", sessionId }, throughSeq, maxMessages } }；
• 脚本化诊断时，可凭 ~/.dsh/.credentials.yaml 中 records.client-connection/browser-session 的签名密钥自签 Cookie（本机诊断用途）。

[xiaoshenming]

补一句后续：这里"手工重编号后 sourceEventSeqs 没同步"这一类，已在 #6348 给了自动化的说法 —— dsh-session-surgeon 的 v0-chunk-provenance 直接按磁盘上真实存在的 chunk run 重写引用，不需要"偏移均匀"这个前提（整段 +1、+867、混合偏移同样处理）；surfaceOp: replace（/rewind 撤回标记）的消息绝不动。先停写者、先 dry-run，apply 前留 .bak.<utc>。