[Bug] A single corrupt session log makes the entire sidebar session list disappear

[cyhano]

Environment

• Package: @deepseek-ai/dsh v0.1.0-rc.7
• Repo: deepseek-ai/deepseek-harness (apps/cli)
• OS: macOS (Apple Silicon), Node v26.3.0
• Launch: dsh web → http://127.0.0.1:3080

Summary

When one session log file has an invalid Zstandard framing (e.g. the whole
JSONL is stored in a single zstd frame instead of the required "header-only
first frame"), the session.list RPC fails with a blanket error and the entire
sidebar session list renders empty — every other healthy session disappears
too, with no indication of which file is at fault.

This is the second time I've hit it (first on 2026-08-18, then again on
2026-08-19), so it is a recurring issue, not a one-off.

Steps to reproduce

1. Have a workspace with multiple sessions (e.g. 16 sessions under one
   workspace).

2. Recompress one of its session.jsonl.zstd files as a single frame, e.g.:

   zstd -dc bad/session.jsonl.zstd | zstd -f -o bad/session.jsonl.zstd.rebuilt
   mv bad/session.jsonl.zstd.rebuilt bad/session.jsonl.zstd

   (This produces one zstd frame containing the header line plus all event
   lines, instead of a dedicated first frame holding exactly the header line.)

3. Open the Web GUI, refresh, and select the workspace.

Actual behavior

• session.list returns:

  handler failure: Error: corrupt Zstandard session log: first frame is not exactly one header line
  

• The sidebar shows the workspace group but zero session titles underneath
  it. workspace.list still returns the correct sessionIds (because it does
  not read log bodies), so the IDs are there but no titles ever render.

• No error is surfaced in the UI and no console.error is emitted — the list
  is just silently empty.

Expected behavior

• A single malformed log should be skipped (and logged with a warning) while
  the remaining sessions still render, instead of failing the whole list.
• If the list must fail, the error should at least name the offending session
  file/path, so the user can find and repair it.

Root cause

In @deepseek-ai/dsh-session-persistence-jsonl, the JSONL artifact is a
multi-frame zstd container:

• the first frame must decode to exactly one header line (a JSON object
  ending in a single \n): plaintext.indexOf(10) === plaintext.length - 1
  (assertZstdHeaderFrame), and
• subsequent event batches live in their own frames, each written with an XXH64
  checksum ({ params: { [ZSTD_c_checksumFlag]: 1 } }).

function assertZstdHeaderFrame(plaintext) {
  if (plaintext.length === 0 || plaintext.indexOf(10) !== plaintext.length - 1)
    throw new Error("corrupt Zstandard session log: first frame is not exactly one header line");
}

The session.list path scans all artifacts and throws on the first bad one,
so a single single-frame file aborts the whole listing (fail-fast, non-isolated).

Suggested fixes

1. Isolate per-session failures in the list path — catch the per-artifact
   header-read error, log a warning that names the file, and continue with the
   other sessions (return them; optionally expose the broken ones as a
   degraded/corrupt set for the UI to show).
2. Include the session id / file path in the error message so a corrupt
   artifact is immediately locatable.
3. Optionally, surface a visible UI hint (e.g. "N sessions could not be loaded")
   instead of a silently empty list.

Manual repair (what worked for me)

Decompress the single-frame file, re-encode with the header in its own frame and
the events in a following frame, then write back:

import { readFileSync, writeFileSync } from "node:fs";
import { zstdCompress, constants } from "node:zlib";
import { promisify } from "node:util";
const compress = promisify(zstdCompress);

const plaintext = execSync(`zstd -dc ${file}`).toString("utf8");
const lines = plaintext.split("\n").filter((l, i, a) => !(i === a.length - 1 && l === ""));
const header = lines[0] + "\n";
const body = lines.slice(1).join("\n") + "\n";

const opts = { params: { [constants.ZSTD_c_checksumFlag]: 1 } };
const out = Buffer.concat([
  await compress(Buffer.from(header), opts),
  await compress(Buffer.from(body), opts),
]);
writeFileSync(file, out);

After this repair, session.list returned ok: true and the sidebar rendered
all 16 sessions again.

Related

This appears related to a previously-noted upstream issue where a
recover/replay flow appends mis-sequenced agent/inbox/spliced messages using a
stale seq cursor (observed 2026-08-18). If a fix uses zstd -f (single-frame)
during repair it produces exactly this header-frame corruption.

[denial123789]

The source confirms an important physical-format boundary here: readFirstZstdLine() independently decodes the first frame, and assertZstdHeaderFrame() requires that frame to contain exactly one newline at the end. A generic decompress/recompress pipeline can therefore produce valid Zstandard bytes that are invalid as a DSH session artifact.

The safest immediate operational recovery is containment: stop all writers, copy and hash the complete session directory, move only the identified session out of the active root, then verify that healthy sessions reappear. Keep repair work on a disposable copy. A future list-path fix should isolate each artifact, return healthy headers, and report the degraded session id/path without leaking message content.

Regression gates should include: one malformed artifact cannot hide healthy sessions; a single-frame header+body artifact is identified precisely; the original remains untouched; and a repaired copy is accepted by the exact producing-version reader before replacement.

I documented this as one of three distinct history failures here: https://sandbaseai.github.io/deepseek-harness-handbook/session-history-recovery.html

Disclosure: independent SandBase community handbook, not official DeepSeek documentation.