Session corrupt: seed assistant/message at index 4002 has invalid settlement fields

[LyuXiaoDong0419]

Hi，我遇到一个会话历史加载失败的问题，报错如下：

历史加载失败：stored session "session-c72030f6-638b-4c63-bc35-43cb29336def" is corrupt: seed assistant/message at index 4002 has invalid settlement fields（gateway/internal）
基本信息：

Session ID：session-c72030f6-638b-4c63-bc35-43cb29336def

报错类型：gateway/internal

失败位置：assistant/message at index 4002

失败原因：invalid settlement fields

问题描述：
该会话在加载历史记录时直接失败，整个会话无法继续使用，历史记录全部无法读取。推测是第 4002 条 assistant 消息的 settlement 字段在写入时中途失败/不完整，或存储层数据损坏。

影响：
会话无法打开，历史内容全部丢失。

已尝试：

重启 / 重新加载会话，无效

报错稳定复现，指向同一条消息

请求：

帮忙清理或修复该会话的损坏记录

排查 settlement 字段写入失败的根因，确认是否与 subagent / 工具调用相关，避免其他会话出现同类问题

谢谢！

[Mide69]

我对着 packages/core/session/src/index.ts 核实了一下，能确认根因，虽然帮不了你恢复这一条已经写坏的记录。

turn/step/stream 这三个字段（也就是报错里说的 settlement fields）有一个专门的校验函数 assertAssistantSettlementShape，要求 turn、step 是非负安全整数，stream 是数组。但这个校验之前只挂在 seed/load 那条路径上，也就是 Session.fromRestore、从存储读回会话的时候才会跑。真正写入用的 Session.append，只调用了 validateSessionEventData 和 surfaceManager.validateNext，两个都不检查这三个字段。

结果就是：只要有任何写入方（插件、provider 适配器等）append 了一条 turn/step/stream 缺失或者格式不对的 assistant/message 或 assistant/attempt，写入当时完全不会报错，等到下次这个会话要从磁盘读回来，才会在 seed assistant/message at index N has invalid settlement fields 这里被拒收，整个会话读不出来，但已经没法知道到底是哪一次写入造成的了。你这条会话第 4002 条assistant/message，大概率就是这样被某次写入弄坏的，不是存储层数据损坏，是写入路径当时没挡住。

我把这个校验补到 append() 里了，位置和最近另一个类似问题（消息缺 id/role）的修法完全一致，推到了 fork 上：

https://github.com/Mide69/deepseek-harness/tree/fix/append-validates-assistant-settlement-shape

加了回归测试，复用现有 seed/load 那边的畸形数据 fixture，对 append() 跑一遍同样的拒绝断言；跑过 packages/core/session、packages/core/agent-loop、packages/core/agent、packages/api/session-controller、packages/subagent 的完整测试套件和仓库自己的 typecheck、lint，都通过。

这个修法能防止以后再出现同类问题，但没法修复你现在这条已经损坏的会话，那条记录已经是坏的了。要拿回历史内容的话，目前只能自己写个小工具，把会话文件按事件一条条读出来（不要用 Node 自带的 JSON 解析整份读，读到第 4002 条就会因为这个校验失败而整体失败），跳过或者修补 seq 4002 那一条的 turn/step/stream 字段后再继续读后面的事件。

[LyuXiaoDong0419]

thank you!

[xiaoshenming]

Reproduced this on the installed runtime (@deepseek-ai/dsh-session@0.1.7-rc.2), and it matches @Mide69's reading of the split.

The gate is assertAssistantSettlementShape (lib/index.js:1126 on 0.1.7-rc.2, :1166 on 0.2.0-rc.1), reached from assertCurrentLlmShape (:1101) via assertSessionEventEnvelope (:1070), which runs in the Session constructor's seed loop — so the same check that judges a live session also judges one being restored (Session.fromRestore, :1289, on the persistence read path). On assistant/message and assistant/attempt it requires:

• turn and step to be non-negative safe integers — -0 is rejected explicitly, not just negatives;
• stream to be an array.

One bad row refuses the whole session, which is the message in your report.

To see it on your own log without building anything, feed the decoded events in as the seed:

const { Session } = await import("<...>/@deepseek-ai/dsh-session/lib/index.js");
Session.fromRestore(header.id, events, header, 0, "detached", []);

As-is it constructs. Delete one assistant/message's stream, or set stream = null, or turn = -0, and it throws seed assistant/message at index N has invalid settlement fields. Two traps if you build a synthetic row: assistant/message needs surfaceOp (otherwise you get is surface-eligible and requires a surfaceOp, which is the fixture's fault, not the gate's) and message.source needs {kind:"model", provider, model}.

On the repair question I agree with @Mide69 — stream carries the streamed blocks and there is no way to rebuild them from the artifact, so this cannot be repaired, only reported.

What is available offline is a sharper diagnosis than the loader's: the official message names the type and the index but not which member tripped, and the row is identifiable from the file alone:

assistant settlement fields are invalid at seq 31 (assistant/message: stream) — …

I added exactly that to dsh-session-surgeon this round (invalid-settlement-fields, checked from v1 up — v0 is excluded because a released v0 assistant/message may not carry stream at all, the v0→v1 payload gate rejects it as an unexpected member). It stays report-only, for the reason above. Measured: 0 hits across the 7 real logs I have on hand (v3 + v4), ~1.6ms on a 140k-event log.

[LyuXiaoDong0419]

解决了

[xiaoshenming]

Follow-up on the root cause you asked about — "是否与 subagent / 工具调用相关" — because I can now rule out the official writer, which narrows it a lot.

The official agent loop cannot produce this row. dsh-agent-loop appends assistant/message / assistant/attempt at five sites, and every one of them passes stream: live.stream, where:

get stream() {
    return [...this.accumulator.snapshot()];
}

That is always an array — possibly empty, never undefined — so JSON.stringify always writes the key. I checked the same two lines in 0.1.5-rc.3 (from the npm tarball), 0.1.7-rc.1 and 0.1.7-rc.2: identical. Nothing in the subagent or tool-call paths touches stream.

And a v0/v1/v2 log cannot produce this message either. v0→v1 does emit assistant/message as turn,step,message with no stream (v0's released inventory forbids the member), but v1→v2 passes that through and then v2→v3 refuses it first: contentArray(data["stream"], label + ".stream") → format v2 assistant/message at seq N data.stream: content must be an array. So the settlement wording you got implies the file is v3 or v4 — a generation where the row is read (or passed through v3→v4) as-is.

Put together: the row came from something other than the official agent loop — a plugin or provider adapter calling session.append("assistant/message", …) without stream, or with stream: undefined — and it is not specific to subagents or tool calls.

I also checked that our own tool is not a candidate, since it rewrites these files: across 5 real v4 logs, all 925 assistant/message rows keep an array stream through a full decode → plan → encode round-trip (the missing-id fix spreads the row and replaces only message).

None of that recovers the row, and I agree with @Mide69 that it cannot be repaired: stream holds the streamed blocks and nothing on disk lets you rebuild them. What is worth knowing is that the writer that damaged it is not the agent loop, so it is fixable at the source — a session.append caller that omits stream is exactly the append-time gap @Mide69's branch closes.

[xiaoyuyu6420]

两位把根因挖透了，补上你没被回答的那半——这条坏记录怎么修。坏的是一行（v2 起每行一个事件），assertAssistantSettlementShape 只挑形状毛病：turn / step 须为非负安全整数、stream 须为数组。所以修复 = 原地改这一行的字段值，不需要重编号：

1. 老三样：停 dsh 进程、整个 session 目录先拷一份留底；
2. 定位：解压日志，按 "index":4002 对应的那条 assistant/message 找到行；
3. 修字段：turn / step 抄相邻消息的值（看 index 4001 / 4003 属于哪个 turn/step——别凭空填 0，分组语义会歪）；stream 若数组本身损坏给 [] 最保守——消息正文在 content 里，不丢正文；
4. 该行在哪个 zstd 帧就只重编那个帧，其余帧字节不动；
5. 放回前用宿主同款校验（对全文件逐行跑 assertAssistantSettlementShape 及相邻 seq 检查）过一遍。

两个后续提醒：

• Mide69 指出这个校验只挂在 seed/load 路径——意味着在线写入路径还在产这种行。修完这条之前，先弄清写入侧是谁（xiaoshenming 已排除官方 writer，那大概率是某个第三方插件或直接写日志的工具），否则修完还会再坏；
• 确认稳定之前，留着的那个留底目录别删。

（会话日志的行级手术是我熟的路子——备份插件的 doctor 平时干的就是这类活。）

[xiaoshenming]

@xiaoyuyu6420 — you are right and I was wrong, so let me correct my own follow-up above rather than leave it standing. I said the row could not be repaired. It can.

Your step 3 is the part that decided it: stream: []. I had reasoned that stream is unrecoverable and stopped there, without asking whether some value is still admissible. It is, and there are two gates rather than one:

• assertAssistantSettlementShape needs stream to be an array — Array.isArray([]) holds, so the gate that produced your error is satisfied;
• assertCurrentAssistantStreams (persistence-jsonl lib/index.js:1833) then expands the stream and continues before comparing anything whenever the expansion is empty:

  timed = expandAssistantStream(event.data.stream);
  for (const member of timed) assembler.push(member.chunk);
  if (event.type === "assistant/attempt" || timed.length === 0) continue;

  So the message.content / usage / message.source.replayState cross-check is skipped for that row — it cannot fail against blocks that are gone.

Measured, not read: stream: [] constructs; a deleted or null stream fails both gates (the second one with stream is not iterable). And your reasoning about the body holds — the text is in message.content, which the repair never touches, so nothing recoverable is lost: the streamed deltas for that attempt are already absent, and [] is the only value that is admissible.

Your step 3's other half I would sharpen, though. Copying turn/step from the neighbouring rows is right when the row sits in the same step, but it does not have to be a heuristic at all: the log itself states which turn and step are open at that seq, and that is exactly the value the row belongs to. I mutated a healthy row's turn to -0 and let the derivation run — it restored 1, the value the row originally carried, which is the evidence that it recovers the true value and not merely an admissible one. When nothing is open at the seq, there is nothing to derive, and that is the only case I leave alone.

One trap in your step 5 worth knowing, since you validate with the host's checker: readStoredLog does not run either gate — it goes through decodeStoredLog → validateStoredEvents, which is imported from elsewhere and contains neither check, so a log with a deleted stream still "loads" there. The path that produces your error is the verifying one (verifyCurrentGeneration, :1798, Session.fromRestore + assertCurrentAssistantStreams). Validating with readStoredLog alone will report a pass on a file the real loader still refuses.

So: thank you — this was a real correction, not a nitpick, and it is now shipped. dsh-session-surgeon repairs these rows (repair --apply, backup first) instead of only flagging them, for all seven broken shapes I could construct: stream deleted / null / a string, turn deleted / -0 / a float, and both at once — each one refused by Session.fromRestore before the repair and constructing after it. Landed as 43b3af7; the matrix is in test/settlement.test.mjs.