v3→v4 read-time migration refuses sessions with unresolved tool calls inside closed steps (damage from #7228's crash window)

[iinlanjian]

Summary

Follow-up to #7228 (the src/lib dual-module bug whose first symptom was every tool call failing with Cannot read properties of undefined (reading 'prepare')). That bug's crash window — between the tool/call append and the tool/result append in agent-loop's runGroup — left durable damage in sessions it hit. After upgrading past the v4 transition, any such session now fails to load entirely:

failed to observe session "session-…": Session migration from v3 to v4 refuses the transformed artifact:
step/end leaves unresolved tool call call_…; source v3 artifact remains unchanged (gateway/internal)

The raw v3 log is intact on disk (the non-destructive refusal works as documented), but there is no self-healing path, so the session — including all of its healthy earlier turns — is unreachable from the UI.

Why the existing repair does not cover it

openTurnClosers (@deepseek-ai/dsh-session/repair) deliberately repairs only an open tail: "Calls in already closed steps remain unchanged, including any missing results." The #7228 crash wrote step/end and turn/end (reason error) after the dangling tool/call, so the damage sits inside closed steps:

• turn 13–16 each advertised 1–3 parallel tool calls; the first call got its tool/call row, the rest never did;
• every one of the 6 calls lacks a tool/result;
• assertV4LifecycleRelationships refuses at the first step/end that follows (closeTools).

One real-world session produced six unresolved calls across four turns this way (four started, two advertised-but-never-started from one parallel batch).

A repair shape the current validator already accepts

For recovery purposes I confirmed the v4 relationships validator already accepts synthetic closers for both cases, inserted between the dangling tool/call (or the assistant/message, for never-started calls) and the step's step/end:

• Started calls: a released-V3 wrapper tool/result (role: "user", one tool-result wrapper with isError: true, inner text from CLOSER_TEXT.interrupted.started), envelope sourceEventSeqs: [<tool/call seq>], no error field. Accepted as a started call's normal result.
• Never-started calls: same wrapper shape with CLOSER_TEXT.interrupted.notStarted as the inner text, data.error = { name: 'ToolNotStartedError', code: 'TOOL_NOT_STARTED' }, no sourceEventSeqs, message id interrupted-tool-result-<callId>-<digits> — matching notStartedRepair exactly. Note the v3 canonical-payload rule requires error rows to carry the tool-result wrapper with isError: true (the bare first-class text shape is rejected by assertCanonicalPayload; the validator checks the lifted inner content).

With those six rows inserted (and subsequent seqs/reference fields shifted — sourceEventSeqs, surfaceOp.startSeq/endSeq, the remapV3References field set), the session migrates cleanly: MIGRATION OK (1796 v4 events) through createSessionFormatCatalogWithChildren(...).createRestore(header, { recovery: 'recoverable', validation: 'transformed' }).

Suggestion

The v3→v4 transform could synthesize exactly these closers when a step/end/turn/end would otherwise refuse on unresolved calls — mirroring openTurnClosers semantics for closed steps (TOOL_OUTCOME_UNKNOWN for started calls citing the call seq, TOOL_NOT_STARTED for advertised-but-never-started ones). That keeps the refuse-without-rewriting default while giving read-time migration a self-heal for crash damage that exists in the wild. Alternatively, a session-doctor path (as proposed in #1518) could apply the same repair explicitly.

The v3 generation on disk was never touched by the refusal; the repair above was applied to a user-consented copy with a backup, and the session loads normally again.

[yamingmou]

We maintain plugins for this harness and we have been reading the .agents/notes/ record alongside the migration work. On the repair shape in this report we can add one thing from that record, one code-level constraint on widening the repair, and a second report of the same transcript shape.

The decision record already covers the shape you propose

rejected/simplification/2026-06-20-truncate-interrupted-turns.md considered the inverse simplification — truncate the interrupted tail at load — and declined it, keeping the synthetic-close machinery instead. Its Status line reads:

a single turn can contain substantial real work, including many steps and large tool output. Preserving interrupted turns is preferable to silently dropping that tail on load.

The section that matters here is What we give up, last sentence (:30):

A future "recover partial crashed work" feature should be designed as an explicit user-facing recovery view, not as synthetic events silently inserted into the canonical transcript.

The shape you verified — six synthetic rows inserted into a released v3 artifact, with sourceEventSeqs, surfaceOp.startSeq/endSeq and the remap field set shifted to match — is the second shape in that sentence. That is worth knowing before anyone spends time on the patch, and it also suggests the stronger framing is "this session is unreachable and we need a way to recover it" rather than "the v4 validator already accepts these rows".

Cause ownership is deliberate, not incidental

dsh-session/lib/types/repair.js:35-37 states the constraint:

Package-internal: each cause has exactly one owner, so external callers go through interruptedTurnClosers (persistence crash recovery) or buildForkSeed in ./fork.ts (fork seeds) instead of selecting a cause.

openTurnClosers is not exported — types/index.js:20 exports interruptedTurnClosers, TOOL_NOT_STARTED and TOOL_OUTCOME_UNKNOWN. The two current owners pass { kind: 'interrupted' } and { kind: 'forked' } (fork.js:26). A repair pass added to the migration would be a third owner, with its own turn/end reason and its own model-visible wording — which is a decision about what the resumed transcript means, rather than an extra call site.

Why the repair cannot see closed steps: it is the cursor, not a rule

Two places in repair.js produce the behaviour you quoted:

• :66-69 — on step/end, pendingCalls.clear() and openStep = null;
• :98 — if (openTurn === null || last === undefined) return [];

So "only an open tail" is not a separate policy check that could be relaxed. The pending-call map is emptied at every step boundary, and the function returns empty whenever the last turn is already closed. Damage whose step has closed is invisible by construction.

The same structure exists in dsh-session@0.1.5-rc.2 (lib/index.js:611 in that package: same step/end clear, same early return), so it predates the v4 transition by several releases. In our reading the v4 gate is not the defect — it converts a transcript that was already unrunnable on at least one provider class into one that will not load at all.

The migration side is a codec

dsh-session-format-v3-to-v4/lib/index.js:647 requires that a tool/result for a not-started call be the exact TOOL_NOT_STARTED repair, and throws otherwise. So the migration will validate the rows you describe but will never produce them. "No self-healing path" is by construction rather than an oversight in that file.

The same transcript shape, a different gate

#7386 (@RayseeAll, 2026-09-21) reports the same shape — dangling tool_calls inside an already-closed turn — with a different failure surface: a chat-completions provider rejects every subsequent request with 400 INVALID_REQUEST ("insufficient tool messages following tool_calls message"), and he measured it unchanged across 0.1.1-rc.2, 0.1.2-rc.1, 0.1.5-rc.2 and dsh-session@0.1.6-alpha.2. Two gates failing on one shape points at the shape; the gates are only where it becomes visible.

Offered as an observation

If the record's position holds, the direction with the fewest open policy questions is a read-only recovery path: the v3 file is intact and the refusal is non-destructive, so a tool could read the log, apply the closers in memory, and write a new artifact or an export, leaving the original file exactly as the read path found it. We are not asking for a timeline or a specific design, and we have not reproduced your session — the reading above is from published packages (dsh-session@0.1.7-alpha.2, dsh-session-format-v3-to-v4@0.1.7-alpha.2) and the repository's own decision record.

Authorship note: this reading is mine, against published package contents and the repository's own decision record; 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. Contact: contact@offerkuai.com · GitHub: @yamingmou

---

中文版

我们维护这个 harness 的插件，做迁移这块工作的同时也一直在读仓库里的 .agents/notes/ 决策记录。关于你提出的修复形态，我们能补三样：决策记录里已有的一条立场、一条"把修复摊开到已闭合 step"会遇到的结构约束，以及一个同一损坏形状的早先报告。

你要做的那个形态，决策记录里已经有立场

rejected/simplification/2026-06-20-truncate-interrupted-turns.md 处理的正是同一机制的相反提案 —— 加载时截断被中断的最终轮次。它被拒绝了，理由写在 Status 行里：

单个轮次可以包含大量真实工作，包括多个步骤和大量工具输出。保留被中断的轮次，优于在加载时静默丢弃这段尾部。

而和这里最相关的是 What we give up 一节的最后一句（:30）：

A future "recover partial crashed work" feature should be designed as an explicit user-facing recovery view, not as synthetic events silently inserted into the canonical transcript.

（译文：未来若要做「恢复部分崩溃工作」的功能，应当设计成面向用户的显式恢复视图，而不是把合成事件静默插进规范 transcript。）

你实测出来的形态 —— 往一个已成版的 v3 档里插入六条合成行，并同步挪动 sourceEventSeqs、surfaceOp.startSeq/endSeq 与整套 remap 字段 —— 就是那句话里被点名的第二种形态。这件事值得在被投入工时之前知道；同时它也提示：更有力的论述角度可能是「这个会话已经打不开了，需要一条恢复途径」，而不是「v4 校验器本来就接受这些行」。

cause 的归属是刻意的，不是偶然的

dsh-session/lib/types/repair.js:35-37 把这条约束写在了注释里：

Package-internal: each cause has exactly one owner, so external callers go through interruptedTurnClosers (persistence crash recovery) or buildForkSeed in ./fork.ts (fork seeds) instead of selecting a cause.

openTurnClosers 并没有对外导出 —— types/index.js:20 导出的是 interruptedTurnClosers、TOOL_NOT_STARTED 和 TOOL_OUTCOME_UNKNOWN。现有的两个 owner 分别传 { kind: 'interrupted' } 与 { kind: 'forked' }（fork.js:26）。若把修复加在迁移这一步，它就会成为第三个 owner —— 要有自己的 turn/end 原因值、自己的模型可见措辞。那是一个"恢复后的 transcript 到底意味着什么"的决策，而不是多一处调用点。

为什么修复看不到已闭合的 step：是游标，不是规则

repair.js 里两处决定了你引到的那个行为：

• :66-69 —— 遇到 step/end 就 pendingCalls.clear() 并把 openStep 置空；
• :98 —— if (openTurn === null || last === undefined) return [];

所以「只修 open tail」不是一条可以放宽的策略判据，而是每个 step 边界都会清空待办表、且末轮一旦闭合整个函数就直接返回空。落在已闭合 step 里的损坏，从结构上就看不见。

同样的结构在 dsh-session@0.1.5-rc.2 里就有（该包 lib/index.js:611：一样的 step/end 清空、一样的提前返回）⇒ 这不是 v4 引入的回归，早于 v4 好几个版本。按我们的读法，v4 那道门本身不是缺陷：它只是把一个"在某些 provider 上早就跑不通"的 transcript，变成了"完全装不进来"。

迁移这一侧是 codec

dsh-session-format-v3-to-v4/lib/index.js:647 要求：未启动调用的 tool/result 必须是精确的 TOOL_NOT_STARTED 修复形态，否则抛错。也就是说迁移会校验你描述的那些行，但永远不会自己生成它们。「没有自愈路径」是构造决定的，不是那个文件漏了一处。

同一损坏形状，另一道门

#7386（@RayseeAll，2026-09-21）报的是同一个形状 —— 已闭合的轮次里留有悬空 tool_calls —— 但失效面不同：chat-completions 类 provider 会对此后的每一次请求返回 400 INVALID_REQUEST（"insufficient tool messages following tool_calls message"），他实测在 0.1.1-rc.2、0.1.2-rc.1、0.1.5-rc.2 与 dsh-session@0.1.6-alpha.2 上都没有变化。一个形状让两道门都失败，说明问题在形状本身，门只是它显形的地方。

作为一条观察，而非请求

如果决策记录的那条立场仍然有效，那么政策疑问最少的方向是一条只读的恢复路径：v3 原档完好、拒绝也是非破坏性的，所以一个工具可以读出日志、在内存里套用 closers，然后写出一个新的产物（或导出件），让原档保持读路径发现它时的原样。我们不要求时间表、也不指定具体设计；并且我们没有复现你的会话 —— 以上读数来自已发布包（dsh-session@0.1.7-alpha.2、dsh-session-format-v3-to-v4@0.1.7-alpha.2）与仓库自己的决策记录。

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

本报告由 OfferKuai（Offer快）团队提交。 联系：contact@offerkuai.com · GitHub：@yamingmou

[iinlanjian]

One more ripple worth noting: while the session was unloadable, the app also dropped it from its workspace's sessionIds membership (~/.dsh/storages/workspace.json) — after the log repair the session reappeared but under an ungrouped bucket instead of its project. Re-adding the id to the workspace entry fixed the grouping. So a refused migration doesn't just hide history; it can silently detach the session from its project.

[yamingmou]

A second store, and one consequence that is easy to lose inside the refusal itself.

What you describe is a disagreement between two stores. The log is the one that gets repaired; the workspace membership is the one that keeps the old state, and nothing on the opening path mentions it. So a refused session is not an unchanged session: one of the two was rewritten while the other was still refusing, and the second write left no message of its own.

That is the part we would keep next to a repair step, rather than inside it: after the log opens again, the membership is a separate thing to re-read, because a session can be present in the log and absent from its project at the same time. Your note also shows the two failure modes are independent — the grouping did not come back with the history, and it took a second, explicit change to bring it back.

We are reporting the shape of it rather than asking for anything; we have not reproduced it ourselves.

Authorship note: the observation restated above is another reporter's, on a version of @deepseek-ai/dsh named in the original thread; 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

---

中文版

这是第二个 store，以及一个容易在"拒收"本身里被忽略掉的后果。

你描述的是两个 store 之间的分歧：日志是被修的那一个，工作区成员表是留着旧状态的那一个，而打开会话的整条路上没有任何一处会提到它。所以一次被拒的会话不等于一个没被改动的会话 —— 两者之一在另一个还在拒收的时候已经被改写了，而那次改写自己没有留下任何消息。

这一点我们倾向放在修复步骤旁边、而不是里面：日志重新能打开之后，成员表是另一件要单独重读的事，因为一个会话完全可以同时"在日志里存在"而"不在它原本的项目里"。你这条也顺带说明这两种失效是相互独立的 —— 分组并没有随历史一起回来，它需要第二次、显式的改动才回来。

我们报告的是这个形状本身，不是提请任何改动；我们这边没有复现。

声明：上列观察转述自原帖报告者，其读数出自原帖已注明的 @deepseek-ai/dsh 版本；文稿撰写由 AI 辅助；核验与发布由我本人负责。我没有工程背景 —— 若任何技术表述有误，请直接指出，我会对照工具链重新核实并更正。我们是插件作者、不是维护者，本文不陈述任何官方政策。

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

[xiaoshenming]

One measurement that belongs next to this refusal, because it decides whether such a session can open at all.

The v4 relationship assertion is not only reached through publish. assertReleasedV4Relationships is called from SessionLogScanner.finish(), so a log already at v4 is refused while it is read. We ran this exact shape (one closed step, durable tool/call, no tool/result) through the real v3→v4 stage, wrote the rows as a real artifact and read it back through readStoredLog:

SessionPersistenceCorruptionError: session "…": stored log is corrupt: SessionFormatError: step/end leaves unresolved tool call c1

Identical on 0.1.7-rc.1 and 0.1.7-rc.2.

One detail that may help attribution: the read path wraps the format error as stored log is corrupt … (raw log: <path>), while restore/publish surfaces the bare SessionFormatError. The inner sentence is the same on every path — the wrapper is what names the entry point that decided.

Runnable probe (five rows: both migration stages accept, both restores refuse, a stored current-generation read refuses; exits non-zero if any row drifts): https://github.com/xiaoshenming/dsh-session-surgeon/blob/1bf58a3/fixtures/probes/run.mjs

Unrelated to any tool: your second-store observation is the part we would keep, too — a refused session is not an unchanged session, and the membership store keeps no message of its own.

[yamingmou]

Noted on the measurement, and the wrapper point carries over cleanly: the class names the entry point, so a report that quotes the outer sentence already answers "which path refused" without anyone reading code.

One note that may help a later reader, and it is about navigation rather than about the reading. This assertion now has two independent arrivals in the record — the one here, and the same measurement in #4549 (#4549), where the same shape was run through the real v3→v4 stage and read back. Someone who lands on one of the two has no way to know the other exists, and the two together are what make the fifth row look like a property of the assertion rather than of a particular caller.

On the second store: we have nothing to add beyond what we wrote here on 09-24, and we would keep the same half you kept — a refused session is not an unchanged session, and the membership store keeps no message of its own, so it has to be read again after the log is repaired rather than inferred from the repair. We say that as a restatement of the earlier note, not as a new finding.

Authorship note: the reading behind this reply is mine, against published package contents; 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.

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

---

中文版

测量这条收到；而包装器那一点可以直接沿用：错误类是入口的标签，所以一份引了外层那句话的报告，不必有人去读代码，就已经回答了"是哪条路径拒的"。

再给一条给后来读者的注记 —— 它关于导航，不关于读数本身。这道断言在记录里现在有两次独立到达：这里这一次，以及 #4549 里的同一测量（https://github.com/deepseek-ai/deepseek-harness/discussions/4549）——那里把同一个形状跑过真正的 v3→v4 阶段并读回。只落在其中一处的读者，无从知道另一处存在；而两处合起来，才让"第五行"读起来像是这道断言的性质，而不是某一个调用方的性质。

关于第二个 store：除了我们 09-24 在这里写过的那一句，补不了别的；而我们保留的正是你保留的那一半 —— 被拒的会话不是没变过的会话，成员存储自己不携带任何消息，所以它必须在日志修好之后被重新读一次，而不是从修复动作里推断出来。这一句是对先前那一条的重申，不是新发现。

声明：本回复所依据的判读由我本人对照已发布的包内容完成；文稿撰写由 AI 辅助；核验与发布由我本人负责。我没有工程背景 —— 若任何技术表述有误，请直接指出，我会对照已发布的包重新核实并更正。

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