0.1.7 read-time migration refuses released subagent/descriptor v2 sessions (fix available)

[kenz1117]

Summary

@deepseek-ai/dsh 0.1.7-alpha.2 refuses to read sessions whose subagent/descriptor payload carries version: 2, so any session opened between 2026-07-27 (payload v2 shipped in #2663) and 2026-08-28 (v3) fails whole-artifact v0-to-v1 migration with SessionFormatUnsupportedMigrationError and becomes unreadable. Downstream aggregation (e.g. the usage-billing plugin) skips these artifacts, so users see silently missing cost statistics for sessions they still actively append to. The raw v0 log stays unchanged on disk — nothing is lost, but there is no self-healing path.

Reproduction

Open (or continue appending to) a session created in that window on 0.1.7-alpha.2. The reader refuses with:

SessionFormatUnsupportedMigrationError: subagent/descriptor <seq> uses unsupported descriptor version 2

Proposed fix

Descriptor v2 is a strict subset of what the v3 payload validator already accepts (required: mode/version/provider; optional: label and composition members), so the v0 edge can admit version 2 alongside 3 with the same released-key policy — no new validation branches beyond the version literal. Versions outside {2, 3} keep refusing.

A complete patch (with migration pass/refuse tests and a bilingual Agent Note) is on my fork, based on current master 00102833df:

https://github.com/kenz1117/deepseek-harness/tree/fix/descriptor-v2-migration

Since both issues and pull requests are disabled in this repository, I am posting it here; happy to move it wherever the maintainers prefer. session-format-v0-to-v1 passes 111/111 on that branch.

[yamingmou]

We are the account that posted the store-side split in #6045 — same gate, and we have been measuring it on our own store. Three things we can add: what we read for the affected window, a split by rule that our store happens to make visible, and one observation from the Agent Notes that we have not seen raised in this thread.

What we read for the affected window

Corrected 2026-09-24 — the start of this window was wrong in the first version of this comment. Our table was read from a local set of package copies that began at 0.1.0-rc.8, and we presented it as the window; @kenz1117 re-ran the reading against the full npm version list and caught it. The earlier start below is his correction, not ours.

Complete reading across all 27 published versions of dsh-subagent (2026-08-10 → 09-23), straight out of the tarballs:

version	constant	npm publish
0.0.1-rc.1	2	2026-08-10 (first npm release of the package)
0.0.1-rc.2 · rc.3 · rc.5	2	08-11 · 08-12
0.1.0-rc.2 · rc.3 · rc.6	2	08-13
0.1.0-rc.7	2	08-17
0.1.0-rc.8	2	08-19
0.1.1-rc.1 · rc.2	2	08-21
0.1.2-alpha.2	3	2026-08-30 (first npm release carrying 3)

So the v2 writing window on published artifacts is 0.0.1-rc.1 (08-10) … 0.1.1-rc.2 (08-21) — a week earlier at the start than we first said. The endpoint is unchanged.

What the fuller table adds: the constant is 2 across all eleven published versions from 08-10 to 08-21 — no second transition inside the window — and 3 from 0.1.2-alpha.2 (08-30) onward. 0.1.2-alpha.1 exists only as a git tag, consistent with @PerryLink's git reading in #6045 and with f76a225a7d (merged 2026-08-24T10:23:42Z) being the change that moves the constant 2 → 3 rather than the change that introduced the v2 payload. One detail that reading leaves open, offered as an observation: between the 08-24 merge and the 08-30 release, master carried 3 while the newest published artifact still carried 2. And we still cannot place a boundary at 2026-07-27.

Two rules, and why our numbers look different from a smaller store's

Read-only through sessionFormatCatalog.createRestore (validation: 'current', recovery: 'strict', then decodeRow per row and finish()), on a store whose sessions were all written by 0.1.1-rc.2: roughly nine in ten sessions were refused, and the split of refusals is the part that matters here:

rule that refused	share of refusals
this descriptor gate	the large majority (about six in seven)
other fail-closed rules	the rest

We report that split as an observation, not as a rule — another installation may look different. It does seem to bear on the estimate question, though: @moonquake2004 measured 13 refusals on a 74-log store, of which 3 were this gate and 10 were the permission/preset + origin shape, while ours runs the other way (in our reading the large majority of refusals are this gate, and none of the other refusals is the origin shape). If that holds, a "how many sessions will I lose" figure measured on one store would not transfer to another — which is part of why running the chain per store looks necessary to us.

One observation from the Agent Notes

alpha-historical-unknown-event-refusal (implemented, 2026-08-31) is the note this gate comes from, and it describes itself as provisional:

"Community feedback will determine the next policy. A later release may add an explicit external-owner migration interface, permit omission of explicitly ignorable historical events while retaining the exact source generation, or keep strict refusal. No option is implied by the alpha marker."

What we noticed is that the same condition is already resolved the other way on an adjacent edge. v3-incomplete-child-catalog-evidence (implemented, 2026-09-19) decides that a child log carrying "an unsupported descriptor version" must not make otherwise readable history unavailable:

"Requiring one supported descriptor to migrate the parent makes unavailable discovery fields prevent access to otherwise readable history."

So on V3→V4 that condition keeps the history readable, and on v0→v1 it refuses the whole artifact. We are flagging the asymmetry only in case it is useful — it is an observation about two notes, not a view on which policy is right.

Gate locations we have pinned

Both still hold on published artifacts, and we mention them only because a patch that widens one of the two would still meet the other:

• session-format-v0-to-v1/lib/index.js:1584 — if (event.type === "subagent/descriptor" && data["version"] !== 3), throwing at :1586
• payload-validation's subagentDescriptorValue opens with literalValue(data['version'], [3])

Authorship note: reproduced and measured by me against my own store; root-cause tracing and drafting assisted by AI; verification and publication by me. I have no engineering background — if any technical claim reads wrong, please call it out; I will re-verify against the toolchain and correct.

Reported by the OfferKuai Team — Founder: Zhaofeng (Yaming). Website: https://www.offerkuai.com/ | Contact: contact@offerkuai.com

---

中文版

我们是 #6045 里贴出那份库侧拆分的一方 —— 同一道门，我们一直在自己的库上量它。这里能补三条：我方对受影响窗口的读数、一份我方库恰好能分开的按规则拆分，以及一条我们在 Agent Notes 里看到、但此线程里没见有人提的观察。

我方对受影响窗口的读数

2026-09-24 更正 —— 本条评论最初的窗口起点是错的。 我们那张表读的是本地的一组包副本，而它们最早只到 0.1.0-rc.8；我们却把它当成了整个窗口。是 @kenz1117 把读数重跑在完整的 npm 版本列表上才发现的。下面这个更早的起点是他的校正，不是我们的。

对 dsh-subagent 全部 27 个已发布版本（2026-08-10 → 09-23）的完整读数，直接取自包内：

版本	常量值	npm 发布
0.0.1-rc.1	2	2026-08-10（该包的首个 npm 发布）
0.0.1-rc.2 · rc.3 · rc.5	2	08-11 · 08-12
0.1.0-rc.2 · rc.3 · rc.6	2	08-13
0.1.0-rc.7	2	08-17
0.1.0-rc.8	2	08-19
0.1.1-rc.1 · rc.2	2	08-21
0.1.2-alpha.2	3	2026-08-30（首个带 3 的 npm 发布）

⇒ 已发布产物上的 v2 写作窗口 = 0.0.1-rc.1（08-10）… 0.1.1-rc.2（08-21），起点比我们最初说的早一周；终点不变。

更全的表多说明两件事：从 08-10 到 08-21 的全部十一个已发布版本，常量都是 2（窗口内没有第二处跳变）；从 0.1.2-alpha.2（08-30）起才是 3。0.1.2-alpha.1 只作为 git tag 存在 —— 这与 @PerryLink 在 #6045 的 git 读数一致，也与 f76a225a7d（合入 2026-08-24T10:23:42Z）是把常量从 2 推到 3、而不是引入 v2 payload 那次改动的判断一致。顺带一处这份读数留下的空白，只作观察：08-24 合入到 08-30 发布之间，master 已是 3，而最新的已发布产物仍带 2。 另外，2026-07-27 这个边界我们依然定位不到。

两条规则 —— 以及为什么我方的数字看起来和小库不一样

以只读方式走 sessionFormatCatalog.createRestore（validation: 'current'、recovery: 'strict'，再逐行 decodeRow 与 finish()），对象是一个全部由 0.1.1-rc.2 写入的库：大约每十个会话里有九个被拒；而这里要紧的是拒绝的构成：

拦下它的规则	占拒绝数的比例
本道 descriptor 门	绝大多数（约七分之六）
其他 fail-closed 规则	其余

这份拆分我们只当观察报出、不当规则 —— 别的安装环境可能长得不一样。不过它似乎与"估算"这个问题有关：@moonquake2004 在一份 74 日志的库里测得 13 个拒绝，其中 3 个是这道门、10 个是 permission/preset + origin 那个形状；而我们的构成正好相反（在我们的读数里，绝大多数拒绝都是这道门，而其余部分里没有一条是 origin 形状）。若这一点成立，那么在某个库上测出的"我会丢多少会话"就不能搬到另一个库 —— 这也是我们觉得有必要逐库跑一遍链路的原因之一。

一条来自 Agent Notes 的观察

alpha-historical-unknown-event-refusal（implemented，2026-08-31）就是这道门所依据的那份 note，而它把自己描述为临时状态：

"Community feedback will determine the next policy. A later release may add an explicit external-owner migration interface, permit omission of explicitly ignorable historical events while retaining the exact source generation, or keep strict refusal. No option is implied by the alpha marker."

（译：后续政策由社区反馈决定。之后的版本可能增加显式的外部属主迁移接口、允许在保留精确源代的前提下略过显式可忽略的历史事件，或者维持严格拒绝。alpha 标记本身并不意味着必须选哪一种。）

我们注意到的是：同一条件在相邻的一条边上已经按相反方式处理。v3-incomplete-child-catalog-evidence（implemented，2026-09-19）决定：子日志即使携带 "an unsupported descriptor version"，也不得让本来可读的历史变得不可用：

"Requiring one supported descriptor to migrate the parent makes unavailable discovery fields prevent access to otherwise readable history."

（译：要求必须有一个受支持的 descriptor 才能迁移父会话，会让"发现字段不可用"这件事阻断本来可读的历史。）

也就是说，在 V3→V4 上这个条件保住可读性，在 v0→v1 上它拒绝整个 artifact。这条仅供参考地把这处不对称摆出来 —— 它是对两份 note 的观察，不是我们对"哪种政策才对"的意见。

我们钉过的两道门位置

两者在已发布产物上仍然成立；提及它们只是因为：放宽其中一处、仍会被另一处拦下。

• session-format-v0-to-v1/lib/index.js:1584 —— if (event.type === "subagent/descriptor" && data["version"] !== 3)，抛错在 :1586
• payload-validation 的 subagentDescriptorValue 起手即 literalValue(data['version'], [3])

声明：本次实测与统计由我针对自己的数据完成；根因追查与文稿撰写由 AI 辅助；核验与发布由我本人负责。我没有工程背景 —— 若任何技术表述有误，请直接指出，我会对照工具链重新核实并更正。

本报告由 OfferKuai（Offer快）团队提交 —— 创始人：Zhaofeng（Yaming）。官网：https://www.offerkuai.com/ | 联系：contact@offerkuai.com

[kenz1117]

Thanks for the measurements — we re-ran your method against the published tarballs and can confirm the direction, with one extension and two corrections to our own post.

Tarball audit of SUBAGENT_DESCRIPTOR_VERSION (same read as yours, extended to the npm boundaries):

version	constant	npm publish
0.0.1-rc.1	2	2026-08-10 (first npm release of the package)
0.1.0-rc.6	2	2026-08-13
0.1.1-rc.2	2	2026-08-21
0.1.2-alpha.2	3	2026-08-30 (first npm release carrying 3)

Two consequences:

• The 2026-07-27 boundary in our post was wrong — we withdraw it. On published artifacts the v2 writing window opens at 0.0.1-rc.1 (2026-08-10), a week earlier than the rc.7 start in your table.
• Symmetrically, the first published artifact writing 3 is 0.1.2-alpha.2 (08-30); 0.1.2-alpha.1 exists only as a git tag, consistent with your f76a225a7d merge date (08-24) marking the 2 to 3 transition inside master.

On the two gate locations you pinned: our patch widens both, and only both — session-format-v0-to-v1 now refuses descriptor versions outside {2, 3} at the edge check, and payload-validation subagentDescriptorValue accepts literalValue([2, 3]) with the same released-key policy as v3. A diff touching only one of the two would indeed still refuse.

On the store-to-store variance: agreed that single-store counts do not transfer. For our reporter specifically the descriptor gate is confirmed by the diagnostic itself (uses unsupported descriptor version 2), so the patch covers the reported case regardless of the 200/33-style mix on other stores.

We also noted the asymmetry you flagged against v3-incomplete-child-catalog-evidence; it reads as a precedent the maintainers have already set for keeping otherwise-readable history available, which is exactly what this patch asks for at the v0 edge.

[yamingmou]

We have replaced the window table in our comment above, and the correction is his: 0.0.1-rc.1 (2026-08-10) is the start, not the 0.1.0-rc.7 we posted. We edited the comment in place rather than leaving our old table standing next to a newer one, and we wrote in it that the earlier start came from your re-run.

One thing we can add, now that we have the whole version list rather than a sample. Reading the constant out of all 27 published versions of dsh-subagent (08-10 → 09-23) puts finer edges on the window than either of our tables had:

• The constant is 2 in every published version from 08-10 through 08-21 — eleven releases, no second transition anywhere inside the window. So the window is not only "opens at 08-10"; it is uniformly 2 across its whole length.
• The other end leaves a gap that neither table showed: f76a225a7d merged on 08-24 and moved master to 3, and the first published artifact carrying 3 is 0.1.2-alpha.2 on 08-30. Between those dates there is no release at all — master said 3 while the newest installable artifact still said 2. For anyone reconstructing which sessions are affected, that is the one interval where "what the tag says" and "what a user actually ran" can disagree.

On the two gate locations: your reading matches ours, and the "both, and only both" point is the part we could not have determined from the outside.

One note on the precedent you cited. We read v3-incomplete-child-catalog-evidence the same way, and we would add only this distinction: it sits in implemented/, not in proposed/. It is a decision already taken on one edge rather than a proposal for another — which is what makes the asymmetry citable as precedent rather than merely worth noting.

We are plugin authors, not maintainers, and we differ from you on nothing here.

Authorship note: this reading is mine, against published package contents; root-cause reading and drafting assisted by AI; verification and publication by me. I have no engineering background — if any technical claim reads wrong, please call it out; I will re-verify against the published packages and correct. We are plugin authors, not maintainers, and nothing here states official policy.

Reported by the OfferKuai Team — Founder: Zhaofeng (Yaming). Website: https://www.offerkuai.com/ | Contact: contact@offerkuai.com

---

中文版

我们已就地替换了上一条评论里的窗口表 —— 而这个更正是他的：起点是 0.0.1-rc.1（2026-08-10），不是我们原来写的 0.1.0-rc.7。我们没有把旧表留在那里和新表并排，而是直接改掉了它，并在评论里写明这个更早的起点来自你的重跑。

有一件事可以补上 —— 现在手里是完整版本列表、而不是一份抽样。把常量从 dsh-subagent 全部 27 个已发布版本（08-10 → 09-23）里读出来，窗口的两条边比我们任何一张表都更清楚：

• 从 08-10 到 08-21 的每一个已发布版本，常量都是 2 —— 十一个版本，窗口内没有任何第二处跳变。所以这个窗口不只是"从 08-10 开始"，而是整段均匀为 2。
• 另一端留了一处两张表都没显示的空白：f76a225a7d 于 08-24 合入、把 master 推到了 3，而首个带 3 的已发布产物是 08-30 的 0.1.2-alpha.2。这两日之间没有任何发布 —— master 说的是 3，而任何人当时能装到的最新产物仍说 2。对任何要重建"哪些会话受影响"的人来说，这是唯一一处「tag 说的」与「用户实际跑的」可能不一致的区间。

关于两处门：你的读数与我们一致；而"两处、且只有两处"这一点，是我们从外面无法确定的。

关于你引用的那条先例，我们只补一处区分：v3-incomplete-child-catalog-evidence 位于 implemented/ 而不是 proposed/。它是一条已经就另一条边做出的决策，而不是针对新的一条边的提议 —— 这正是它可以作为先例被引用、而不只是值得一记的原因。

我们是插件作者、不是维护者；在这件事上我们与你没有分歧。

声明：本次通读与核对由我本人完成（对象为已发布包内容）；文稿撰写由 AI 辅助；核验与发布由我本人负责。我没有工程背景 —— 若任何技术表述有误，请直接指出，我会对照已发布包重新核实并更正。我们是插件作者、不是维护者，本文不陈述任何官方政策。

本报告由 OfferKuai（Offer快）团队提交 —— 创始人：Zhaofeng（Yaming）。官网：https://www.offerkuai.com/ | 联系：contact@offerkuai.com