DeepSeek Harness upgrade: "refuses this format v0"

Old sessions that refuse to open with refuses this format v0 after a DeepSeek Harness upgrade are hitting a migration allow-list that was frozen against the writers still present on master, missing shapes older releases actually wrote: the data contains members such as permission/preset.origin from 0.1.1-rc.1 and a flat replayState, the migrator does not recognise them, and valid history is rejected as an illegal format. Back up the whole session directory first, then use a read-only repair tool — never hand-edit the files.

What the DeepSeek Harness refuses this format v0 error looks like

On the surface it is one format refusal, but it is really four different member classes being judged illegal, reported one at a time. A user hit this in the wild (see Discussion #6151):

1. After upgrading to 0.1.5, 15 of 35 sessions reported refuses this format v0 Session;
2. Only one error appears per attempt, and fixing one reveals the next, which makes it look like the count is growing;
3. The four refused shapes are: an extra origin on permission/preset, subagent/descriptor carrying version 2 instead of 3, plugin-defined message sources instruction-hint / at-file-mention, and unknown historical events that already carry ignorable: true;
4. An earlier variant of the same family: sessions written by an alpha build then opened with rc.2 (npm latest at the time) reported SessionPersistenceCorruptionError (see Discussion #5160).

Why a DSH plugin rejects released historical data as an illegal format

The core contradiction is that the reader freezes its allow-list against current code, while the writer produced more shapes in the past. After checking the 0.1.5-rc.1 source line by line, the community described the mechanism:

1. RELEASED_V0_EVENT_DISPOSITIONS is frozen only against writers that survive on master, so it misses the permission/preset.origin written by 0.1.1-rc.1 and the flat replayState used before the envelope wrapper (source: Discussion #5818);
2. subagent/descriptor hard-requires version === 3 while older data wrote 2; v3 only adds an optional agentReasoningEffort over v2, so bumping should be lossless;
3. Plugin-defined message sources belong to a closed kind / form set, and values written by earlier plugin versions fall outside it;
4. In the same family there is an encoding mismatch: the writer's encodeSeqRanges compresses three or more consecutive seqs into [[start,end]], while the rc.2 reader's assertProvenance only accepts flat integers, and SESSION_FORMAT_VERSION was never bumped, so the version guard was bypassed silently (source: Discussion #5160).

In short: the session is not corrupt — the reader no longer recognises shapes it once wrote itself.

How to handle refused sessions in DeepSeek Harness, and where the fix stands

The order is back up, inspect read-only, apply, then record what is left. Concretely:

1. Back up the entire session directory (~/.dsh/profiles/<name>/sessions/) first; the tool only touches the first three classes, so the backup is your only rollback;
2. Run the community tool dsh-session-surgeon in inspect mode to see which refusal class each session hits;
3. Only then apply repairs; one community report went from 1 of 57 sessions readable to all 57;
4. The fourth class (unknown historical events carrying ignorable: true) needs an upstream allow-list expansion and is outside the tool's coverage — record those and wait for the official fix;
5. Version clues: readers from 0.1.2-rc.1 onwards ship decodeSeqRanges and are healthy for ranged-seq sessions, while the root fix is still a writer that bumps the format version;
6. To check which release line you are on (latest / alpha / rc), review installed plugins and versions under Settings → Plugin Marketplace; for this project that is DSH Plugin Hub.

DSH plugin troubleshooting notes

Back up first and repair read-only; the two shortcuts below turn a repairable refusal into real corruption. Three points to keep in mind about a DeepSeek Harness plugin session:

1. Do not hand-edit session files: the version number, event shapes and seq encoding are interrelated, and one wrong edit turns a repairable refusal into real corruption.
2. Do not "open and re-save" with an older build: writes from an old reader can introduce new shape differences and spread the problem to more sessions.
3. The wider session story is collected in DeepSeek Harness session corruption: enumeration failures, format refusals and recovery.

Sources: Discussion #6151, Discussion #5818, Discussion #5160