dsh-session-migration-repair
Repair legacy (format v0) DSH session logs that the current build refuses to migrate: scan → back up → fix → verify offline against the host's own migration chain → write.
English | 中文
The problem
Since DSH 0.1.5 a stored session is migrated through v0 → v1 → v2 → v3 on open, and every step is validated strictly. Fields that older builds wrote empty are rejected by the migration chain, surfacing as "history unavailable" for that session. This tool fixes exactly those logs.
Four deterministic defect classes, all auto-repairable:
| Error | Root cause | Fix |
|---|
released tool-call-chunks row N id and optional name must be strings | streamed tool-call chunk rows carry an empty id (only the first row used to have it) | recover the real id/name from the assistant/chunk tool-call-delta of the same turn|step|index |
assistant/message N message content[k] name must be a non-empty string | tool-call block name is empty (often after an earlier repair tool rewrote the chain) | recover the tool name from the same step's delta |
format v2 assistant/message ... invalid message content kind "tool-call": user/message 0 content[0] id must be a non-empty string | the block-end tool-call block inside assistant/chunk has an empty id (the outer message is misleading) | fill it from the delta as well |
tool/call ... does not match one advertised tool call | tool/call.arguments no longer equals the advertised block's arguments | align both sides, preferring the side free of replacement characters (U+FFFD) |
Install
As a DSH plugin (registers one model-callable tool plus a bundled skill):
dsh plugin --profile web add dsh-session-migration-repair # from npm
dsh plugin --profile web add github:<owner>/dsh-session-migration-repair # from GitHub
# restart dsh web and reload the page
Or use the CLI standalone — zero dependencies, Node ≥ 22.15 (Node 20's node:zlib has no zstd API):
node bin/cli.mjs --help
CLI
dsh-session-migration-repair list # list sessions (generation + quarantined files)
dsh-session-migration-repair scan <session-id|path> # read-only diagnosis
dsh-session-migration-repair validate <session-id|path># run the full migration chain offline
dsh-session-migration-repair fix <session-id|path> --yes # backup → repair → verify → write
Options: --dry-run, --no-fix-arguments, --dsh-home <dir>, --dsh-root <dir>, --json.
Safety
- Backup first: the original is copied into
$DSH_HOME/session-migration-repair/backups/<timestamp>/ and an audit line is appended to audit/repair-log.jsonl.
- Minimal diff: only lines that actually change are re-serialized (a real 59,289-line session: 148 lines changed).
- Verify before write: the repaired log must pass the v0→v1→v2→v3 chain locally; the write itself is atomic (temp file + rename).
- Zero dependencies: multi-frame zstd read/write is built in — DSH logs are multi-frame and the first frame must contain exactly the header line, while Node's own zstd decoder only reads the first frame.
How it works
- Multi-frame zstd (
lib/core/zstd.mjs): walks physical frame boundaries (frame and block headers only), decompresses frame by frame and decodes UTF-8 once — concatenating per-chunk decodes corrupts multi-byte characters that straddle a boundary.
- Defect index: every streamed tool call is announced by an
assistant/chunk tool-call-delta carrying the real id and tool name, so every empty field can be recovered.
- Offline verification: DSH exposes its own load path as
sessionFormatCatalog.createRestore(); this tool drives it, so the verdict matches what the server would do — no restart-and-click loops.
Limitations
- Only logs that still exist (including
.corrupt-* quarantined backups) can be repaired; a session directory removed with rm -rf is unrecoverable.
- Only the four defect classes above are handled; any other migration error makes
fix refuse to write.
- Text already damaged (U+FFFD) cannot be restored — the tool only guarantees it will not add new damage.
Development
node --test test/*.test.mjs # unit tests
DSH_REAL_V0_LOG=/path/to/defective.jsonl.zstd node --test test/*.test.mjs # regression on a real log
License
MIT
