Session log corruption from concurrent writers — 'corrupt session log: seq gap in committed region'

[Tang-mm95]

Symptom

A session that previously loaded fine starts failing to open with:

history unavailable for session "<id>": Error: corrupt session log: seq gap in committed region at line 2401 (expected 34843, got 34841)（internal）

The error comes from @deepseek-ai/dsh-session-persistence-jsonl's reader, which requires the decoded event stream to be strictly contiguous (events[i].seq === i). Once this fires, the whole session becomes unreadable — in every client (web UI, desktop wrappers) because they all read the same file under DSH_HOME.

Root cause: concurrent writers on one session log

The JSONL backend documents "One live writer per session" — append coordination exists only inside a single process. The file format assumes it: each append batch is a compressed frame appended at the writer's cached EOF offset, and packed chunk rows carry a seq0 cursor computed from that writer's in-memory view.

When two dsh server processes share one DSH_HOME (e.g. a desktop wrapper spawning its own server while another server already serves the same data root, or two dsh web processes in different terminals), the second writer's cursor is stale. Its next batch lands at an offset that overlaps the first writer's already-written rows. The result is not a torn frame (crash recovery handles those) but a structurally valid file with overlapping sequences — exactly what the committed-region check rejects.

Decoded rows at the corruption point (real capture):

行2399  packed  assistant/chunk  seq 34817..34840   ← both writers agree
行2400  raw     step/end         seq 34841         ← writer A: turn closed
行2401  raw     turn/end         seq 34842         ← writer A
行2402  packed  assistant/chunk  seq 34841..34855  ← writer B: stale seq0=34841, overlaps A
行2403+ raw     assistant/chunk  seq 34856..37143  ← writer B's complete continuation

The stale seq0 (off by exactly the two rows writer A appended) is the signature of the race.

This is not specific to any desktop wrapper: two plain dsh web instances on the same DSH_HOME can produce it identically. The persistence layer simply has no cross-process defense.

Detection (read-only scanner)

The scanner below uses the runtime's own decoder to verify every session log. It never modifies anything; run it periodically to catch corruption before a session refuses to open.

#!/bin/bash
# dsh-session-scan.sh — verify seq contiguity of every session under DSH_HOME (read-only)
set -euo pipefail
DSH_HOME_DIR="${DSH_HOME:-$HOME/.dsh}"
RUNTIME="${DSH_RUNTIME_DIR:-/Applications/DeepSeek Harness.app/Contents/Resources/runtime}" # dsh runtime dir containing node + node_modules
ZSTD_BIN="${ZSTD_BIN:-$(command -v zstd || echo /opt/homebrew/bin/zstd)}"
DECODER="$RUNTIME/dsh-session-scan-decoder.mjs"
cat > "$DECODER" <<'DECODER_EOF'
import { decodeStorageRecord } from '@deepseek-ai/dsh-session';
let text = '';
process.stdin.on('data', (c) => { text += c.toString('utf8'); });
process.stdin.on('end', () => {
  const lines = text.split('\n').filter((l) => l.trim());
  let events = 0; let issue = null;
  for (const [i, line] of lines.entries()) {
    if (i === 0) continue;
    let decoded;
    try { decoded = decodeStorageRecord(JSON.parse(line)); }
    catch (e) { issue = `line ${i + 1} decode failed: ${e.message}`; break; }
    for (const ev of decoded) {
      if (ev.seq !== events) { issue = `line ${i + 1} expected seq=${events} got=${ev.seq}`; break; }
      events++;
    }
    if (issue) break;
  }
  console.log(issue ? `✗ ${process.argv[2]}  ${issue}` : `✓ ${process.argv[2]}  ${events} events / ${lines.length - 1} rows`);
});
DECODER_EOF
trap 'rm -f "$DECODER"' EXIT
while IFS= read -r -d '' f; do
  sid=$(basename "$(dirname "$f")")
  "$ZSTD_BIN" -dc "$f" 2>/dev/null | "$RUNTIME/node" "$DECODER" "$sid"
done < <(find "$DSH_HOME_DIR/sessions" -name 'session.jsonl.zstd' -print0)

Manual repair (backup first!)

If the corruption is the overlap shape above (a batch with a stale seq0 overlapping a few rows the other writer already wrote), the history is often fully recoverable by removing the stale rows so the stream becomes contiguous again. In the capture above, deleting writer A's two stale closing rows (2400–2401) made the entire log — all 37,144 events — load again with zero content loss (A's rows were a premature duplicate close; B's continuation was the real history).

Procedure used (macOS, zstd CLI):

# 0. Back up
cp session.jsonl.zstd session.jsonl.zstd.bak-$(date +%Y%m%d-%H%M%S)

# 1. Decompress, remove the overlapping rows, re-encode as header frame + body frame
zstd -dc session.jsonl.zstd > /tmp/session.jsonl
sed -i '' '2400,2401d' /tmp/session.jsonl          # adjust to YOUR line numbers
head -1 /tmp/session.jsonl | zstd -q -c > session.jsonl.zstd.new
tail -n +2 /tmp/session.jsonl | zstd -q -c >> session.jsonl.zstd.new

# 2. Verify with the decoder above (must report ✓ and an event count)
zstd -dc session.jsonl.zstd.new | node decode.mjs

# 3. Replace
mv session.jsonl.zstd.new session.jsonl.zstd

Do not attempt this without understanding the exact rows involved — dump the decoded rows first (seq0/seq per row around the reported line) and only remove rows that overlap. Keep the backup until the session opens correctly in the UI.

Request

Please consider hardening the persistence layer against concurrent writers, any of which would have prevented this class of corruption:

1. A lock file per DSH_HOME (e.g. DSH_HOME/.lock holding pid + port, taken at server start) with a clear error instead of a silent second writer;
2. O_APPEND-style writes so a stale-cursor append can never overwrite a newer batch;
3. Re-validating the tail seq at append time (re-read the last committed seq from disk before writing a batch), turning the stale-cursor race into a loud failure instead of silent overlap.

Thanks for the great work on DSH — happy to provide the full corrupted-file capture or help test a fix.

[Tang-mm95]

Following the ecosystem-contribution route (external PRs aren't accepted yet), this report now has a companion community plugin: dsh-single-instance-guard — https://github.com/Tang-mm95/dsh-single-instance-guard

A zero-dependency cordis plugin that takes an exclusive .dsh-server.lock in DSH_HOME at startup and aborts loudly when a live dsh instance already holds it, so the concurrent-writer corruption above cannot happen silently. Installable as a profile bundle (dsh plugin --profile <name> add dsh-single-instance-guard once published to npm). 7 unit tests + a two-process integration test included.