dsh-session-recovery

Recover deleted/corrupted DeepSeek Harness sessions & memory from raw disk

English · 中文

---

🛟 After rm -rf ~/.dsh or file corruption, dsh conversation logs (session.jsonl.zstd) and memory (memory.db) can usually be recovered straight from the raw block device — this repo is a battle-tested manual plus the scripts that made it work.

✨ Features

🧠 Memory recovery	Locate memory.db by its SQLite format 3 header, dump the window, rescue rows via SQLite's official .recover (skips corrupt pages, keeps readable data).
💬 Session recovery	Scan disk for zstd frame magic 0xFD2FB528, cluster frames by disk offset, split sessions at turn resets, rebuild official-format session.jsonl.zstd.
🔧 Automatic repair	Renumber seq contiguously, deep-fix sourceEventSeqs/messageSeqs, normalize surfaceOp — the rebuilt log passes DSH's validation.
🔁 Resume repair	Rebuilt sessions can fail at resume (invalid persisted inbox splice, Messages with role 'tool' must be a response to tool_calls) — repair-session.js (or the /session-repair web command) replays DSH's inbox/surface/wire rules and fixes the file.
🛡️ Safe by design	Scripts only read the block device and write to a directory you choose; the original disk is never modified.

🚀 Quick Start

# 1. Stop everything that writes to disk (systemd services, dsh itself)
systemctl stop dsh-web

# 2. Recover memory (SQLite)
node scripts/recover-memory.js /dev/<dev> /tmp/recovered/

# 3. Scan disk for session frames
node scripts/scan-zstd.js /dev/<dev> > /tmp/session-events.jsonl

# 4. Split mixed events into per-session files
node scripts/split-sessions.js /tmp/session-events.jsonl 2026-08-16T07:05:06Z

# 5. Rebuild a session file (official format)
node scripts/rebuild-session.js \
  --input /tmp/sess-A.jsonl \
  --id session-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx \
  --created-at 1786705157736 \
  --cwd /path/to/workspace \
  --out-dir ~/.dsh/sessions/--workspace-encoded--/

# 6. Before resuming: verify/repair the rebuilt session (fixes inbox splice
#    skew, duplicate/orphaned tool results, dangling tool calls)
node scripts/repair-session.js \
  ~/.dsh/sessions/--workspace-encoded--/<session-id>/session.jsonl.zstd --dry-run
node scripts/repair-session.js \
  ~/.dsh/sessions/--workspace-encoded--/<session-id>/session.jsonl.zstd
#   → writes session.jsonl.zstd.repaired (+ .bak-<ts>); review, then replace:
cp ~/.dsh/sessions/--workspace-encoded--/<session-id>/session.jsonl.zstd.repaired \
   ~/.dsh/sessions/--workspace-encoded--/<session-id>/session.jsonl.zstd

📖 Full step-by-step manual (Chinese, with every DSH validation rule and error you may hit): RECOVERY.md

📦 Install as a dsh plugin

Note: primarily a recovery toolkit (scripts + manual); it also installs as a dsh plugin that adds the /session-repair command to the web UI.

From a directory containing this repo (local install, no publish needed):

dsh plugin --profile web add file:/path/to/dsh-session-recovery
systemctl restart dsh-web

Then type in any session in the web UI:

/session-repair --dry-run              # analyze the current session (writes nothing)
/session-repair <session-id-or-path>   # repair → writes .repaired + a backup
/session-repair --apply <id>           # also replace the original file

…