0.1.3-alpha.1: old sessions cannot open — v0 migration refuses subagent/descriptor version 2

[slinf183]

Environment

• OS: Windows 11
• dsh version: 0.1.3-alpha.1 (upgraded from 0.1.2-rc.1)
• Launch: npx @deepseek-ai/dsh web

What happened
After upgrading, every old session that contains a subagent child (created by the
0.1.2-era build) fails to open / continue — the composer stays locked and the
migration fails with:

subagent/descriptor 0 uses unsupported descriptor version 2

Old sessions without subagent descriptors open and migrate fine.

Root cause (from source inspection)
packages/session/session-format-v0-to-v1/src/validation.ts
(assertReleasedEventPayload) requires subagent/descriptor in a v0 log to have
version === 3, otherwise it throws SessionFormatUnsupportedMigrationError:

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

But builds from before PR #2663 (2026-08-24) wrote SUBAGENT_DESCRIPTOR_VERSION = 2,
so real v0 logs written by the 0.1.2-era release legitimately contain descriptor
version 2. The v1 validation path tolerates other versions (return), while the v0
path hard-refuses, breaking migration for the whole session.

Workaround
For each affected session.jsonl.zstd, change the subagent/descriptor event's
data.version from 2 to 3 (the v2 payload shape is already v3-compatible).
After that, the shipped migration chain (v0→v1→v2) completes and validates cleanly.
I verified all 9 affected sessions on my machine this way.

Suggestion
Either (a) tolerate descriptor version 2 in v0 logs like the v1 path does, or
(b) normalize descriptor 2→3 inside the v0→v1 edge when the payload shape is
compatible. Thanks!

[NadjiHamid]

#5694

[argszero]

你的根因分析（validation.ts:227 对 subagent/descriptor 的 data['version'] !== 3 硬性拒绝）我在 d347e70390（v0.1.3-alpha.1, 当前 master）上确认了, 代码锚点精确。但我想对你的「0.1.2-era release 写的是 v2」这一归因做一个重要的源级更正——它可能改变这个 bug 的优先级。

关键事实：没有 0.1.2 发布线 carry 过 v2

我把所有 0.1.2 出的 tag 的 packages/subagent/subagent/src/descriptor.ts 都 diff 了：

tag	SUBAGENT_DESCRIPTOR_VERSION
dsh-v0.1.2-alpha.1	3
dsh-v0.1.2-alpha.2	3
dsh-v0.1.2-alpha.3	3
dsh-v0.1.2-alpha.4	3
dsh-v0.1.2-alpha.5	3
dsh-v0.1.2-rc.1	3

没有一个 0.1.2 发布 tag 是 v2。 v2 是 PR #2663（feat/subagent-provider）演进过程中的瞬态值——774ee34b9a（feat(subagent): catalog one-shot child sessions）把它从 v1 抬到 v2, 但同一 PR 在 merge 到 f76a225a7d 时已经是 v3（3d70889a8d/9135a13a8b 一带后来把它抬到 v3）。所以 v2 从未以发布形态流出。

这改变了什么

• 如果你的 v0 log 是 0.1.2-rc.1（或任何 0.1.2 alpha）真正写出来的, 它带的是 descriptor v3, 不该被 validation.ts:227 拒绝——那你的报错就另有来源。
• 如果你的 v0 log 是 npx @deepseek-ai/dsh 装的 0.1.2-rc.1 写的, 那你的「0.1.2-era 写 v2」一说不成立。
• 更可能的场景: 那段子代理会话是你在 PR 由插件重复安装引起的桌面端崩溃 #2663 开发途中从源码 build / 或某个拉取了中间 commit 的本地构建 写下的（那时 descriptor 恰好是 v2）。这种 log 不属于「released Session data」——按 upstream 的迁移契约（见 .agents/notes/implemented/architecture/2026-08-31-released-session-format-migrations.md）「body reads may add a version-named successor but never move/overwrite/delete committed generations; predecessors imply neither fallback nor downgrade support」, v0→v1 边对「从未发布过的 v2」拒绝其实是正确行为(防止把非 alpha 的中间体当正式数据误升级)。

建议

这大概率不是「released-data 回归」, 而是「从开发中间态构建的会话被 0.1.3 拒收」。两种处理路径都值得 maintainer 定夺:

• 修正归因后, 若确认你是从源码/中间 commit build 的, 这属于「非发布中间数据」——按迁移契约拒绝是对的, 只是报错文案可以更友好（e.g. 提示「此会话由未发布的中间构建产生, 请重建子代理或忽略」）, 让用户知道不是 upgrade 后数据损坏。
• 若你能提供确凿证据（0.1.2-rc.1 发布线真的写 v2——例如 node -e "require('@deepseek-ai/dsh-subagent').SUBAGENT_DESCRIPTOR_VERSION" 在 0.1.2-rc.1 下打印出 2）, 那我的 tag diff 有误, 请贴出来, 我会收回。

一个可证伪的验证点: 你在 0.1.2-rc.1 下 require('@deepseek-ai/dsh-subagent').SUBAGENT_DESCRIPTOR_VERSION 到底打印几? 这会一锤定音。另, 你的 v0 log 里的 subagent/descriptor 事件 data.version 到底是多少? 如果它真是 2, 且你确认是在 0.1.2-rc.1 下写的, 那这是个真回归, 我此前对 tag 的核查可能漏了什么——再容我 diff 一次确认。

附: 我 c306 在 #5704（exFAT EISDIR）里也做过类似的「报错 vs 真实机制」源级核对——dsh 的 FS 写原子性/迁移边常有「运行时误诊 vs 应用层兜住」的区分, 这次 #5753 是同一个观察方法的另一个案例。若确认是发布回归, 值得单独出修复。