Post-upgrade recovery after 0.1.6-alpha (v0 sessions + plugins) — toolkit & notes

[yao0759]

"## Summary\n\nAfter upgrading to 0.1.6-alpha I hit a cluster of post-upgrade failures\n(220 of 261 stored sessions + 3 plugins). I worked through them and packaged\nthe recovery into a runnable toolkit in case it helps others:\n\nhttps://github.com/yao0759/dsh-upgrade-toolkit (includes a Chinese README)\n\nOpening this here because the repo Issues are disabled and the README points\nbug reports/feedback to Discussions.\n\n## Symptoms\n\n- ... dsh-session-format-v0-to-v1 refuses this format v0 Session: ... source summary requires notice form\n- corrupt Zstandard session log: first frame is not exactly one header line\n- failed to create session: TypeError: session.events is not iterable\n- Old conversations fail to load; model tab stuck on "loading provider"\n\n## Root causes found\n\n1. Session payload rule. A plugin source carrying summary must use\nform: \"notice\". Older dsh-mnemon wrote form: \"instructions\" | \"recall\"\nwith a stray summary, which the new validator rejects. The summary there\nis display-only, so removing it preserves the instructions/recall content.\n\n2. Multi-frame Zstandard layout. session.jsonl.zstd is multi-frame:\nthe first frame independently decodes to exactly the one header line, later\nframes stream the events. Recompressing the whole file with a normal zstd\nCLI merges multiple lines into frame 1 \u2192 first frame is not exactly one\nheader. One such file aborts the workspace-registry init, which is why the\ncontrollers stay pending and the model tab looks stuck.\n\n3. Plugin/Host API drift. session.events was removed in favor of\nsession.snapshotEvents(). @anionex/dsh-vision-toolkit 0.1.40 iterated\nsession.events during attach, so every session create failed.\n\n## Fixes\n\n- Plugins (upgrade together with the Host):\n - dsh-pocket 2.10.0 \u2192 2.10.6 (Connection RPC / webServer inject)\n - dsh-mnemon 0.4.4 \u2192 0.5.12, plus remoteAccess: trusted-host in the profile patch for the settings RPC\n - @anionex/dsh-vision-toolkit 0.1.40 \u2192 0.1.45 (uses snapshotEvents() with events ?? [] fallback)\n- Session migration: dry-run/apply script that removes the invalid field and\n rebuilds the exact multi-frame zstd layout via node:zlib, backs each file\n up, validates with zstd -t, and atomically replaces.\n\nbash\nnode scripts/migrate-sessions.mjs # scan only\nnode scripts/migrate-sessions.mjs --apply # repair + backup\nsystemctl --user restart deepseek-harness.service\n\n\nRequires Node.js >= 22 and the zstd CLI.\n\n## Possibly useful upstream feedback\n\n- A bundled one-shot v0 session migration (payload + framing) would make\n upgrades much smoother \u2014 right now the strict validator rejects old\n sessions with no automatic repair path.\n- The first frame is not exactly one header error cascades into a\n workspace-registry init failure; isolating/reporting the offending session\n path directly would speed diagnosis.\n\nHappy to open this differently or provide more detail. Thanks for DSH!\n"