[Bug] seq gap + 跨 session 内容串写 -> 手动修复后单文件损坏导致 dsh web 启动崩溃

[DecarbonizedGlucose]

环境

• dsh 版本：0.1.1-rc.2
• 安装方式：aur
• Node.js：v26.7.0
• OS：Arch Linux
• 启动方式：dsh web

过程

1. 前一天晚上10点左右 yay -Syu 滚包，但是没有重启。
2. dsh web 一直运行。早晨6点我发出最后一条消息。很久后agent已经没有动静。期间有另一个实例 web-note (我用来测试插件)同时运行，在另一个workspace，此时已经没有输入和输出。
3. 早晨9点左右，确认agent已经没有在输出，急着关机时用了 Ctrl+C 强制中断了两个 dsh 进程。
4. 重启后仅 dsh web 打开工作 workspace + session，出现：

history unavailable for session "session-34102e56-6180-40ce-b597-6a04f9b5d012":
Error: corrupt session log: seq gap in committed region at line 74309 (expected 977738, got 977737)（internal）

3. 解压 session.jsonl.zstd 后发现 同一个 seq=977737 出现了两次：

• 短的一条：{"type":"session/end-seed","seq":977737,...}
• 超长的一条：{"type":"agent/inbox/spliced","seq":977737,...}，里面塞了一大段完全不属于本 session 的对话内容（也就是另一个实例打开的workspace的一个session的内容）。

4. 尝试手动删除超长污染行后，用普通 zstd 重新压缩，结果出现了：Error: corrupt Zstandard session log: first frame is not exactly one header line 和一大段报错。
   整个dsh完全无法启动。

尝试的修复

• 备份原文件
• 解压后删除重复的超长 agent/inbox/spliced 行
• 重新压缩（普通 zstd 单帧）→ 触发 first frame 校验失败
• 最终只能把整个 session 目录移走，才能让 dsh web 重新启动

相似问题

#4127

希望能增加并发写的保护以及session修复工具。
感谢！

[denial123789]

There are two separate corruptions in this timeline, and preserving that distinction matters.

Original artifact: two logical events share seq=977737 but have different types/payloads, with one apparently carrying another Session’s content. This is not an idempotent duplicate candidate and must not use “delete the repeated block” recovery. It is a divergent-history and possible cross-Session isolation incident. Keep both rows as restricted evidence; equal sequence numbers alone cannot identify the authoritative event.

Replacement artifact: ordinary zstd recompression creates one frame containing all decoded lines. The rc.2 default format requires an independent checksummed first frame containing exactly the immutable header line, followed by concatenated append frames. Therefore first frame is not exactly one header line describes the manually recompressed copy, not the original seq-gap cause. Do not overwrite the original with it.

For diagnosis I would freeze every writer first, copy and hash the whole Session directory, and record each concurrent DSH PID, profile, resolved DSH_HOME, persistence root, cwd, process start time, loaded plugins, interruption order, and artifact device/inode/size/timestamps. The overnight package update is useful timeline evidence but cannot change code already loaded in a running Node process, so it is not causal proof by itself. Likewise, two processes matter only after proving they shared a root or a plugin/cache/IPC boundary.

Because foreign content may be sensitive, keep the unredacted payload private, publish only minimized/redacted structure, and identify which Sessions/principals could have received it. The safest operational outcome remains quarantining the one Session and continuing in a fresh Session. A format-aware repair is possible only after a tool proves one authoritative history, emits a staged multi-frame artifact, and cold-loads it in an isolated Harness home; same-seq different values provide no exact-duplicate proof.

I added this specific rc.2 branch, evidence record, and recompression boundary to the independent recovery runbook: https://github.com/sandbaseai/deepseek-harness-handbook/blob/main/docs/en/troubleshooting/duplicate-committed-session-seq.md

[nokkies]

三件事：根因、为什么手动修复失败（附可用的修复步骤，我实测过），以及为什么一个坏文件能拖垮整个启动。

1. 根因：rc.2 的 session 日志没有跨进程写入串行化

你同时跑了两个 dsh 实例，这正是没有被保护的场景。

session-persistence-jsonl 的追加路径直到 #4662 的修复才加上 withFileLock 跨进程写者锁（该分支的提交标题就是 “serialize cross-process appends with a writer lock”）。0.1.1-rc.2 里没有这道锁，所以两个进程各写各的，谁也不知道对方在写。

为什么恰好是 seq 重复，而不是别的乱码：Session.append 分配 seq 的方式是

seq: this.log.length,

也就是说 seq 就是内存中日志数组的下标。两个写者各自持有自己的数组、各自从自己的长度算下一个 seq，于是必然撞号——你看到的 seq=977737 出现两次，正是这个机制的直接产物，而不是随机损坏。同理，读侧的 seq gap in committed region 也是同一件事的下游表现。

Ctrl+C 强杀只是把这个状态定格下来，不是起因。

2. 手动修复为什么失败，以及正确做法

session.jsonl.zstd 不是一个普通的单帧 zstd 流。读取时有这条断言：

/** Assert that the independently decodable first frame contains only the header record. */
function assertZstdHeaderFrame(plaintext: Buffer): void {
  if (plaintext.length === 0 || plaintext.indexOf(0x0A) !== plaintext.length - 1) {
    throw new Error('corrupt Zstandard session log: first frame is not exactly one header line')
  }
}

第一个可独立解码的帧必须恰好只有 header 那一行。普通 zstd file 会把整个文件压成一个帧，第一帧里有几十万行，所以必然报你看到的那条错。

正确的做法是把 header 单独压成一帧，再把其余内容压成后续帧，然后拼接（zstd 支持帧串联）：

head -n 1 session.jsonl        > header.jsonl
tail -n +2 session.jsonl       > body.jsonl
zstd -q -o header.zst header.jsonl
zstd -q -o body.zst   body.jsonl
cat header.zst body.zst        > session.jsonl.zstd

我按读取侧那条规则实测过：单帧写法被拒绝，「header 一帧 + 正文一帧」被接受，且逐帧解码后与原始字节完全一致（帧边界处能看到 zstd 魔数 28b52ffd）。

一个验证时的坑：某些单次调用式的解压 API 只解第一帧，你会以为内容丢了。用 zstd -d 验证（CLI 会解完所有串联帧），不要用只解一帧的接口。

修好之后仍建议先备份，并确认 seq 连续——删掉那条超长的重复行之后，后面所有事件的 seq 相对 header 是否还连续，是这套校验的下一道关。

3. 「一个坏文件让整个 dsh 起不来」是另一个问题

这一条独立于并发写，值得单独知道：会话枚举以前遇到任何一个有问题的目录就整体抛错，于是一个坏 session 会让所有依赖枚举的功能一起失效——这正是 #4746 报的形态（那边是同一目录同时存在 .jsonl 和 .jsonl.zstd）。你最后只能把整个 session 目录移走才能启动，就是这个 fail-closed 行为的表现。

这一点我在本地已经改成：坏目录跳过并记一条警告，健康 session 照常可用；但如果所有目录都坏，则明确报错而不是假装“空仓库”。你的经历正是这个改动想避免的：为了一个 session 起不来，代价是整个 dsh 起不来。

关于你的两个诉求

• 并发写保护：会话日志并发写损坏修复：跨进程写锁 + 尾部 seq 校验（附完整修复分支） #4662 就是它，值得优先合入 —— 它同时解释了你这次的 seq 重复。
• session 修复工具：目前确实没有，上面那套 head/tail/双帧拼接是手工替代方案。考虑到 zstd 的帧约定不是自明的（你已经踩到了），一个 dsh session repair 之类的子命令价值很高。

[DecarbonizedGlucose]

感谢两位的详细分析！

的确 rc.2 没有跨进程写锁，seq 直接用内存 log.length 分配，两个实例撞号就说得通了。
跨 workspace 内容串写的情况也值得注意。

我这边没有更多可补充的证据了，原始损坏文件已隔离。后续会改从源码跟踪更新。

再次感谢。

[Jstn-1g]

To make the catalog-isolation behavior described above by nokkies inspectable, I published a narrow reference implementation against exact official master b150a551b8d465e31e418e1b2eaf5e79bbb7d28e:

• branch: https://github.com/Jstn-1g/deepseek-harness/tree/reference/discussion-4767-corrupt-header-isolation
• exact commit: Jstn-1g@194f604

Scope is catalog discovery only. A missing/malformed raw header or malformed Zstandard header frame is isolated when at least one unrelated healthy Session remains, with a once-per-path warning. Targeted reads still reject the artifact. An all-corrupt root still rejects rather than appearing empty. Wrong root/cwd/id, physical case aliases, duplicate valid IDs, opposite encoding/layout, cancellation, permission, and I/O faults remain fail-closed.

The original same-sequence divergent history is deliberately not repaired or selected. It receives an explicit diagnostic that automatic history selection is unsafe. Writer serialization remains the separate #4662 prevention lane; dual-encoding directory collisions remain the separate #4746 lane. This reference does not prove the incident's root cause or identify an authoritative event history.

Exact-head verification: JSONL/Zstandard focused suites 239/239; full package suite 247/247 with 100% coverage of the changed source files; full TypeScript, changed-file lint, pre-push host/contracts build, and all 28 bilingual documentation/catalog gates passed. An independent adversarial review found no blocking isolation or fail-open path.

[xiaoshenming]

手动用普通 zstd 重压成单帧，会变成 first frame is not exactly one header line——这是第二份损坏，不是原来的 seq gap。官方格式是 header 单独一帧 + 后面多帧拼接。

dsh-session-surgeon 按这个帧布局读写，不会把整份压成一帧：

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

• inspect：看是 seq-gap-committed / 帧头坏 / 还是你后写的那份单帧文件。
• 对原始双写文件：repair --apply 裁到缺口前最后一个完整 turn/end（先 .bak.<utc>）。不会在两条同 seq、内容不同的行里猜哪条是真的，更不会把串过来的另一份会话接回去。
• 已经被普通 zstd 重压过的那份：header 帧已经没了，我们也不敢自动修；留着原始 .bak / 隔离目录当证据，不要覆盖它。

启动连坐：把坏 session 目录移出 ~/.dsh/sessions 就能让 Web 起来（#4855 也是同一类）。根因仍是跨进程无锁追加，预防走 #4662 / 独立 DSH_HOME。

[MedicineKing]

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

1. 读端容错补丁：SessionLogScanner 遇到已消费过的旧 seq（回退/重复/重叠段）时改为跳过而不是整体拒读——磁盘上的所有已提交内容零裁切保留。手动重压单帧把二次损坏引入正片——工具写回用官方帧结构 + 备份 + 回读验证，避免重蹈覆辙。
2. 零安装 CLI（dsh-corrupt-session-repair）：node dsh-corrupt-session-repair.mjs 扫描（只读）→ fix 预览 → fix --apply（先写 .bak.zstd；写回与官方同款 checksum 帧——header 单独一帧，assertZstdHeaderFrame 直接接受）。真跳号/物理损坏只报告、绝不重写。

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