The v0 session codec refuses the subagent/descriptor version released 0.1.x wrote

[m0nk111]

Issue: the v0 session codec refuses the subagent/descriptor version released 0.1.x wrote

Area: packages/session/session-format-v0-to-v1 (+ packages/subagent/subagent)
Severity: blocks upgrading for any deployment whose history contains subagent sessions

Summary

A session log written by @deepseek-ai/dsh@0.1.0-rc.6 (and by 0.1.1-rc.2, whose checkout
declares the same constant) cannot be opened by any release that ships the v0→v1 codec,
because the codec requires subagent/descriptor events to carry version: 3 while those
releases wrote version: 2.

SessionFormatUnsupportedError: subagent/descriptor 0 uses unsupported descriptor version 2;
source v0 artifact remains unchanged (raw log: …/session.jsonl.zstd)
  at JsonlSessionPersistence.generationFailure
  at JsonlSessionPersistence.prepareStoredMigration

Opening fails for both access modes: the session still appears in listings and cannot be
opened or continued. The stored artifact is not modified.

Where it is decided

packages/session/session-format-v0-to-v1/src/payload-validation.ts:956 (master, verified
2026-10-03):

literalValue(data['version'], [3], `${label} version`)

and, before it, the migration's own gate:

if (event.type === "subagent/descriptor" && data["version"] !== 3) {
  const descriptorVersion = sessionFormatCount(data["version"], `${event.type} ${event.seq} version`)
  if (version === 0) throw new SessionFormatUnsupportedMigrationError(
    `${event.type} ${event.seq} uses unsupported descriptor version ${descriptorVersion}`)
  return
}

SUBAGENT_DESCRIPTOR_VERSION is 2 in 0.1.0-rc.6 and 0.1.1-rc.2, and 3 from 0.1.7-rc.2 onward
(checked against the published packages and against master, where it is still 3). The v0
format is frozen, but it was written by both sides of that bump.

Impact, measured on a real corpus

Measurement	Value
Session logs on the host	492
Logs refused after upgrading	340 (69 %)
Logs containing a descriptor with version: 3	0

Every session-backed subagent appends the descriptor at seq 0, so the refusal covers the
whole delegation history. A representative event:

{"type":"subagent/descriptor","seq":0,"time":1787335531324,"data":{"version":2,"mode":"continuable","provider":"spawn","label":"…","agentProvider":"guardian","agentModel":"…"}}

The migration itself is healthy: a log without that event reads and migrates correctly, and
the current-format artifact is published beside the untouched source.

The refused records look v3-shaped

foldSubagentDescriptor rejects unknown fields against the version's key set. Across all 333
descriptors inspected in that corpus:

Payload keys	Count	Inside the v3 key sets?
version, mode, provider, label, agentProvider, agentModel (continuable)	286	yes
version, mode, provider (one-shot)	44	yes
version, mode, provider, label (one-shot)	3	yes
records with a key outside the v3 sets	0	—

So the refusal is the version number alone, not information the record lacks.

Suggested direction (maintainer's call)

Accept the versions a released build actually wrote and upgrade the record while migrating —
a permissive codec alone is not enough. Measured here: when the migration merely lets a
version: 2 record through, the log becomes readable but foldSubagentDescriptor returns
undefined, so the child reports "no supported continuation state" and cannot be resumed;
stamping the migrated record as version 3 makes the same fold return the continuable descriptor
(provider, agent provider, agent model, label) that coldResume needs. Alternatively, give the
chain an explicit v2→v3 record migration. Either way, the frozen v0 codec's own predecessor is
currently unreadable, which also means the codec cannot be validated against real historical
corpora.

Minimal reproduction

npm pack @deepseek-ai/dsh@0.2.0-rc.2            # or install it in a scratch prefix
# copy one session directory whose log contains a v2 descriptor into a scratch root
# open it with that build:
#   backend.open(id, 'read')   -> SessionFormatUnsupportedError (shown above)
#   backend.open(id, 'write')  -> same error

Workaround in use meanwhile

A throwaway converter build — a scratch copy of a 0.2.x prefix whose codec accepts version 2 as
well as 3 — opens copies of the affected logs for writing, so the harness's own writer
publishes session.v4.jsonl.zstd; that artifact is installed next to the untouched original and
is read by the unpatched runtime. Verified here on real logs: the healed sessions read as
238/365/941 events ending in turn/end, every source log still matched its SHA-256, the last
record and timestamp are identical to the v0 log (the record count drops only because the chain
folds the streaming records), and the previous release still reads its own artifact when the v4
file sits beside it.