vlln/dsh-skills/dsh-session-repair

DSH Session Log Repair

Use this skill when a DSH session's history is broken in the GUI. Two independent defects each make the WHOLE session unloadable, and a log can carry either one while looking perfectly fine line by line:

Seq corruption comes from concurrent multi-client writes: two clients (GUI tabs, or two dsh processes like the dsh-0806/dsh-0807 stations) appended to the same session log, and the second writer's seq counter was stale, so it appended events whose seqs repeat values already in the log.

Turn-structure corruption is a writer defect / lost append, not a seq problem: the log's seqs stay contiguous (the seq check reports OK!) while a turn is left open mid-log. Engine-side, turn/end is appended in a finally, so the interrupted turn's closer can go missing when the turn is superseded, the process is killed mid-turn, or a resumed writer continues the log.

Why the seq contract rejects the whole log

The persistence scanner (SessionLogScanner in @deepseek-ai/dsh-session-persistence-jsonl) requires the decoded event stream to be strictly contiguous seq 0,1,2,…,N — no duplicates, no gaps, no out-of-order events. One duplicated line freezes the scanner's commit cursor, so the WHOLE log is rejected:

corrupt Zstandard session log: complete frame contains a torn JSONL record

Why the turn contract rejects the whole log

Reading a stored artifact runs the released-format migration chain (session-format-v0-to-v1 → v1-to-v2 → v2-to-v3) in front of the current logical stream. That migration walks turns with a single openTurn slot and refuses the artifact outright when a new turn/start arrives while a turn is still open:

turn/start 39 does not close the prior turn;
source v0 artifact remains unchanged (raw log: …/session.jsonl.zstd)

~/.dsh wraps that as failed to observe session "…", and the session never opens — even though every seq is contiguous.

The harness recovers exactly one shape here (legacyInterruptedTurnRestart in the v0 relationships, then legacyInterruptedTurn in the v1→v2 migration): the released resume restart, where the event immediately before the offending turn/start is an agent/inbox/spliced insert with target: "next-turn" and a non-empty inserted. The harness then synthesizes turn/end {turn: <open>, reason: {kind: "interrupted"}} itself, so such a log loads normally and must NOT be "repaired" by hand.

Any other shape — the same break after a next-step insert (a subagent message), a lost turn/end, a resumed writer — is refused. Real-world frequency: in one store of 767 sessions, every mid-log open turn but one was the recoverable next-turn variant (and those sessions loaded fine); the single next-step variant was unloadable. Do not assume the recoverable majority means the unloadable one is fine.

Two auto-repairable seq classes (A/B)

Anything else — a gap (a seq is missing entirely) or an out-of-order line whose tail is a mixed pattern — is NOT auto-repairable; the script fails closed and asks for manual review. It never writes a file it cannot verify.

The auto-repairable turn-structure class (C)

Refused (exit 2, manual review): a turn/end with no matching open turn, a turn/start that skips a turn number, a pre-release "legacy" log (whose turn structure the harness normalizes itself), an open turn that starts before the last session/end-seed marker (closing it would move the inherited cut), and an interrupted turn with an unanswered tool/call — closing that one needs a synthetic tool result (which the harness synthesizes on resume but this skill will not fabricate).

Pipeline

Stage 1: Locate the session log

Sessions live under ~/.dsh/sessions/<project-dir>/<session-id>/session.jsonl.zstd (project dirs are URL-encoded cwd paths like --Users-vlln-Project-dsh-plugins--). Find the id from the GUI's workspace, or from ~/.dsh/storages/workspace.json (sessionIds per workspace) and ~/.dsh/storages/session_projcache.json (session id → title).

Stage 2: Check

export _S="$HOME/.agents/skills/dsh-session-repair"
python3 "$_S/scripts/check-session.py" <path/to/session.jsonl.zstd>

Or scan the whole store (finds every corrupted session at once):

python3 "$_S/scripts/check-session.py" --all

Exit 0 = all clean; 1 = a violation was found. Both families are checked in one pass:

• Seq violations name the kind (DUPLICATE / GAP / OUT-OF-ORDER), the

offending seq, the event type, the physical line, and the expected seq. Packed chunk rows (text-chunks/reasoning-chunks/tool-call-chunks) carry seq0 (not seq) and expand to seq0..seq0+len-1; the script handles this, do not hand-check raw lines.

• Turn-structure violations print `OPEN-TURN … — the harness cannot recover

it, plus the preceding event and its target`, and whether a step is open.

• Notes (not violations) explain benign shapes: an open turn the harness

closes itself (next-turn insert), a trailing open turn (normal crash shape, closed on resume), or a skipped structural check on a seeded log. --all --quiet-notes prints only failing files.

Stage 3: Repair (to a new file first)

Pick the script by the violation Stage 2 reported. If both are present, fix the seq family first — the turn-structure script requires a contiguous seq stream.

# seq family (classes A/B)
python3 "$_S/scripts/repair-session.py" <path/to/session.jsonl.zstd> \
  --out /tmp/session.fixed.jsonl.zstd
 
# turn-structure family (class C)
python3 "$_S/scripts/repair-turn-structure.py" <path/to/session.jsonl.zstd> \
  --out /tmp/session.fixed.jsonl.zstd

Exit 0 = repaired; 1 = nothing to repair; 2 = not auto-repairable (read the message; do not force it). Each output line states what was applied and the resulting event count/seq range. Checkpoint: never skip this — both scripts re-verify their own output (seq contiguity, and for class C the full turn structure) and refuse to write a file that does not pass.

Stage 4: Install and verify through the harness's own reader

# whichever script Stage 3 selected; both accept the same flags
python3 "$_S/scripts/repair-session.py" <path/to/session.jsonl.zstd> \
  --install --backup-dir <backup-dir>

--install backs up the original (<name>.bak-<timestamp>), replaces the log (atomically, chmod 600), and prints the backup path.

Then confirm the harness itself can read the result — this is the authoritative test, because it runs the real migration instead of the skill's approximation:

node "$_S/scripts/verify-session.mjs" <path/to/session.jsonl.zstd>

It copies the log into a throwaway store, opens it read-only with the installed @deepseek-ai/dsh-session-persistence-jsonl, and prints either OK — <n> logical events, <t> turn(s), interrupted closer(s) for turn(s) … or the refusal verbatim (exit 0/1). It never migrates or rewrites the real artifact. Set DSH_MODULES=<node_modules dir> if it cannot locate the installed dsh packages.

Finally refresh the GUI and open the session. The projection cache (~/.dsh/storages/session_projcache/) self-heals on the next cold read — do NOT edit it by hand.

Gotchas