Recover corrupted DeepSeek Harness sessions: log, cache and delta fixes

Three typical signals of a corrupted DeepSeek Harness session: a seq gap in the log (an external tool rewrote the session log), a plummeting KV cache hit rate (the cache and the log are out of sync), and History failing with Failed to fetch (internal) (damaged delta data). Handle them in this order: locate the log → repair or recreate the session → clear and rebuild the cache → verify recovery.

DeepSeek Harness session corruption: the three symptoms

The three symptoms differ: a seq gap is a file-integrity error, a dropping cache rate is a performance signal, and an internal fetch failure is a frontend fetch error. One by one (source: dshbase troubleshooting):

1. Seq gap in the log — startup or session recovery reports corrupt session log: seq gap in committed region, and the session fails to open or only restores part of its content;
2. Plummeting KV cache hit rate — monitoring or logs show a clearly lower hit rate, session recovery gets slower and hits the disk repeatedly;
3. History reports Failed to fetch (internal) — after restoring a session, clicking History fails to load history, or the session list loads abnormally;
4. All three can appear together (cache and log share one source), but the handling order is the same: check log integrity first.

Root cause: external tools rewrite the log + cache/log mismatch + damaged delta data

Three root causes: an external tool rewrites the log file (seq gap), the cache and the log are out of sync (dropping hit rate), and delta data is damaged (internal fetch failure). In detail:

1. External tools rewrite the log — session logs are append-only JSONL files; text editors, sync drives and scripts can break the appended sequence, and a break in the committed region reports seq gap (source: dshbase troubleshooting);
2. Cache and log mismatch — once the log changes, KV cache keys go stale and the hit rate drops, so recovery falls back to the source often;
3. Damaged delta data — recovery replays delta data from the log, and malformed deltas make the frontend History fetch report Failed to fetch (internal) (source: dshbase troubleshooting);
4. The storage format is defined by packages/session/session-persistence-jsonl (source: session-persistence-jsonl), and appends are validated by sequence numbers.

Fix DeepSeek Harness session corruption: locate log, repair, rebuild cache, verify

Work in order: back up and locate first, then repair or recreate the session, clear and rebuild the cache, and finally verify recovery. Step by step:

1. Locate and back up the session log — enter the session storage path under the profile data directory (the JSONL append files defined by session-persistence-jsonl):
   bash

   # macOS/Linux example: inspect the profile directory first
   ls -la ~/.dsh/profiles/<profile>/sessions
   

   After finding the target session's .jsonl file, copy a backup.
2. Repair or recreate the session:
   • Light repair: restart dsh web; the host replays the log and tries to repair the break;
   • Repair fails: move the backup away and let the session start blank again (history is lost but the session works);
   • Keep the evidence: retain the backup file for reporting to the maintainers.
3. Clear and rebuild the cache — when the cache mismatch drops the hit rate, clear the session cache:
   bash

   # Find and remove the session cache directory (the path varies by version; follow dsh's hint)
   rm -rf ~/.dsh/profiles/<profile>/cache/<session-id>
   

   Restart dsh web so the cache rebuilds from the current log.
4. Verify recovery — reopen the session:
   • No more seq gap and full history recovery → done;
   • Still Failed to fetch (internal) → export a backup of the current session data, start a new session, and report the backup (source: dshbase troubleshooting).
5. Prevention — never edit JSONL session logs with external tools; back up sessions with dsh's export feature instead of hand-copying and editing.

How to verify a DeepSeek Harness session fix: log integrity, cache rebuild, and session usability

Three checks confirm the fix: the log sequence is continuous, the cache rebuilt, and History plus export both work — only when all three pass is the session recovered. In order:

1. Check the session log line count and sequence — inspect the profile's session directory:

   bash

   wc -l ~/.dsh/profiles/<profile>/sessions/*.jsonl
   

   The target file's line count matching the message volume and no seq gap in the startup log means file integrity is restored.

2. Restart the host and watch the recovery log:

   bash

   dsh web
   

   No corrupt session log: seq gap during startup and recovery, and the session replays from the log — the first gate passes.

3. Verify the cache rebuilt — the first recovery after cleanup reads from disk, then the hit rate recovers and recovery speeds up; no sustained source reads in monitoring or logs.

4. Verify History and the whole session — clicking History loads the full history without Failed to fetch (internal); open the session and scroll to earlier messages with the content intact.

5. Verify the export backup works — export a backup through the official export feature and confirm the key content opens fine; with a backup in hand, any later problem can be restored from it.

Notes: DeepSeek Harness — back up before repairing

1. Export or back up first — once a log file is corrupted, history cannot be recovered automatically.
2. If a seq gap cannot be repaired, recreate the session instead of repeatedly restarting.
3. For a dropping cache hit rate, clear the cache first; leave the log alone.
4. Restore session history with the official export capability; external tools are read-only.
5. See install error troubleshooting for other DeepSeek Harness install errors.

Sources: dshbase troubleshooting, DeepSeek Harness session-persistence-jsonl, DeepSeek Harness packages/session