活跃会话读取历史/恢复时偶发误报「corrupt Zstandard session log」

[Wo-hao-Mi]

正文

活跃会话写入期间读取其日志偶发报 zstd 损坏，文件实际无损，写入平息后同一文件即通过校验。

复现、预期与验收

• 复现步骤：
  1. dsh web（@deepseek-ai/dsh 0.1.0-rc.6）运行一个持续产生事件的活跃会话（agent 执行工具、消息流密集）
  2. 会话活跃期间读取该会话历史（打开历史视图，或从另一入口 resume 该会话）
  3. 概率性报错：corrupt Zstandard session log: complete frame contains a torn JSONL record（历史视图显示 history unavailable for session ...，resume 显示 resume failed for session ...）
  4. 单实例即可复现，无需第二个 dsh 实例
• 实际结果：历史加载/会话恢复失败，提示会话日志损坏（internal 错误）
• 预期结果：writer flush 的正常中间态不应被 reader 判为损坏；至少应返回截至最后一条完整记录的内容（与 torn frame 的恢复路径一致）
• 环境：macOS（arm64）、Node v24、@deepseek-ai/dsh 0.1.0-rc.6
• 验收条件：读取活跃写入中的会话不再报上述错误；或明确提示「会话正在写入，请稍后重试」而非「日志损坏」

技术分析与证据

根因定位

• 校验点：dsh-session-persistence-jsonl 的 readZstdPrefix：

  const complete = scanner.checkpoint();
  if (complete.committedBytes !== complete.inputBytes)
    throw new Error("corrupt Zstandard session log: complete frame contains a torn JSONL record");

• writer 行为：追加写入使用 INCOMPLETE_FRAME_OPTIONS = { finishFlush: ZSTD_e_flush } 按批 flush 帧。帧边界可能恰好落在一条 JSONL 记录中间（记录后半段随下一批写入下一帧）。

• reader 不对称：对「最后一帧字节不完整」（torn frame）有完整恢复路径（tornStart → tornMarker 截断+恢复），但对「最后一个完整帧以半条记录结尾」直接 throw。

• 该状态是瞬时的：writer 下一批把记录剩余部分追加后，同一文件立即通过校验。活跃会话期间这个窗口随每次跨帧记录周期性出现。

实测证据

• 报错文件的全量解码校验（按 scanZstdFrames 同款逻辑逐帧解码）：26661 个完整帧、32689 条 JSONL 记录、0 字节残缺
• 报错窗口内文件持续增长（10 秒 +70KB，lsof 确认写入进程持有句柄）→ 会话正在活跃写入
• 写入平息后无任何进程持有文件，同一文件校验立即通过 → 无持久损坏，历史完整
• 用户环境仅运行单个 dsh 实例，排除跨实例竞态：单实例内历史视图与自身 writer 即可竞态

修复建议

1. reader 侧（推荐）：将「最后完整帧以半条记录结尾」视同 torn frame 恢复路径处理——忽略未闭合尾部，返回已完整记录；对仍在增长的文件不触发截断写回。
2. writer 侧（可选加固）：flush 帧时不在记录中间切分——缓冲未闭合的 partial record，仅在记录边界 flush。

---

追加发现 2（更严重，建议并入同一 issue）：turn 边界 seq 回退导致持久损坏

现象、证据与修复记录

现象

同一会话日志中，turn/end 之后新一轮的事件 seq 回退复用了上一轮末尾的序号：

L30855: [99473] step/end
L30856: [99474] turn/end
L30857: [99473] assistant/chunk   ← 新一轮却从 99473 重新开始（应为 99475）
L30858: [99474] assistant/chunk
L30859: [99475,99476,99477] assistant/chunk ...

后果

• SessionLogScanner 要求 seq 全局单调连续，首个回退行之后永久无法提交
• 与发现 1 不同：这不是瞬时窗口，文件从此一直报 corrupt Zstandard session log，历史永远加载失败，会话无法 resume
• 表面错误信息仍是 "complete frame contains a torn JSONL record"，与真实原因（seq 回退）完全无关，严重误导排查

实测修复（供参考）

对回退点起的所有记录的 seq/seq0 统一 +2 重编号后，全文件通过解码器校验（111665 个事件，零内容丢失）。说明数据本身没丢，纯粹是 writer 的 seq 编号错误。

建议

• writer 侧：turn 边界不应重置/复用 seq 计数器（疑似中断/重试路径重复提交或计数器回滚）
• reader 侧：报错信息应区分「seq 异常」与「帧撕裂」，并给出行号/期望值（scanner 内部已有这些信息）

[zoahdev]

Confirmed — the root cause is exactly where you pointed, and this is a reader/writer asymmetry, not file corruption.

The throw lives in readZstdPrefix (packages/session/session-persistence-jsonl/src/index.ts):

const complete = scanner.checkpoint()
if (complete.committedBytes !== complete.inputBytes) {
  throw new Error('corrupt Zstandard session log: complete frame contains a torn JSONL record')
}

SessionLogScanner already distinguishes the two things correctly: inputBytes counts every byte fed in, while committedBytes advances only past a complete newline-terminated record. A ZSTD_e_flush frame boundary can land inside a JSONL line, so the last complete frame legitimately ends with a half-record that the writer completes on its next append. That state is transient and self-heals — it's not corruption.

The evidence that this is a false positive rather than a real risk:

1. The plain-JSONL path already tolerates it — readPrefix does committedBytes < buffer.byteLength ? { tornMarker: { truncateTo: committedBytes, recoveredEvents: [] } } : {}. The zstd path is the only one that throws.
2. Real corruption is caught elsewhere in consumeEventLine (unparsable committed event → issue; seq gap → issue/throw on turn/end), not by the committedBytes !== inputBytes check.

The fix is to make readZstdPrefix mirror the plain path: when tornStart === undefined and the only discrepancy is a torn record tail, return the complete records and discard the tail instead of throwing. I can land that as a cherry-pick-ready branch with a regression test (a complete frame ending in a torn record must load, matching your "return up to the last complete record" acceptance). Want me to push it?

[zoahdev]

Shipped (finding 1 — the false-positive torn-record throw).

• Branch: zoahdev/deepseek-harness@fix/zstd-torn-record-tail-tolerate (cherry-pick-ready against 47f943859b).
• readZstdPrefix now returns the committed prefix when every frame is structurally complete, even if the last frame ends mid-record (a ZSTD_e_flush boundary inside a JSONL line). That state self-heals on the next append; scanner.finish already discards the torn tail, mirroring the plain-JSONL path. Real corruption stays caught by consumeEventLine, and the incomplete-final-frame recovery path is unchanged.
• Updated the existing regression (was asserting the old throw) to assert the new behavior; session-persistence-jsonl zstd.spec 80/80 green.

Finding 2 (the persistent seq regression at turn boundaries) is the same writer-side seq-minting bug as #2068 — I shipped the loader-side duplicate-seq tolerance there, but the root-cause fix (single atomic seq owner across the turn teardown + inbox-splice writers) still needs your captured writer interleaving or a repro to pin it. If you can share the session dir from that corrupted case, I can prepare the root-cause patch.

[Electricitysheep]

活跃会话写入期间读日志误报 zstd 损坏（文件实际无损）——读写竞争导致的误报，和第 8 章会话管理（#1473/#1497 损坏会话家族）相关但更温和（等写入平息即恢复）。

临时：等会话写入平息再恢复。会话坑位第 8 章有整理：https://github.com/Electricitysheep/dsh-handbook/blob/main/docs/08-tools-context.md

[Wo-hao-Mi]

直接修改会话的seg也可以修复这个问题

…

------------------ 原始邮件 ------------------ 发件人: "Zhou ***@***.***>; 发送时间: 2026年8月16日(星期天) 中午11:38 收件人: ***@***.***>; 抄送: ***@***.***>; ***@***.***>; 主题: Re: [deepseek-ai/deepseek-harness] 活跃会话读取历史/恢复时偶发误报「corrupt Zstandard session log」 (Discussion #2202) 活跃会话写入期间读日志误报 zstd 损坏（文件实际无损）——读写竞争导致的误报，和第 8 章会话管理（#1473/#1497 损坏会话家族）相关但更温和（等写入平息即恢复）。 临时：等会话写入平息再恢复。会话坑位第 8 章有整理：https://github.com/Electricitysheep/dsh-handbook/blob/main/docs/08-tools-context.md — Reply to this email directly, view it on GitHub, or unsubscribe. Triage notifications, keep track of coding agent tasks and review pull requests on the go with GitHub Mobile for iOS and Android. Download it today! You are receiving this because you authored the thread.Message ID: ***@***.***>