Corrupt session log (first frame is not the header) blocks dsh web startup and session listing

[srstack]

Environment

• dsh 0.1.5-rc.1 (npm-global @deepseek-ai/dsh), Node v22.22.3, Linux
• Launch: dsh --profile web --no-open (reproduced with a plain manual launch too)

Summary

Three times in ~5 days, a session log under ~/.dsh/sessions/<project-slug>/<session-id>/session.v3.jsonl.zstd ended up with its first line being an event instead of the {"type":"session",...} header. Once such a file exists:

1. dsh --profile web fails to boot (exit code 1):

Error: dsh: plugin tree failed to load: failed to apply loader entry include (cordis:include): failed to apply loader entry workspace (@deepseek-ai/dsh-workspace): corrupt Zstandard session log: first frame is not exactly one header line
    at assertZstdHeaderFrame (.../dsh-session-persistence-jsonl/lib/index.js)
    ...
    at async WorkspaceRegistry.listStoredHeaders (.../dsh-workspace/lib/index.js)

2. In earlier occurrences the process still started, but session/list failed wholesale and every workspace showed no sessions, so the UI looked like all history was gone:

gateway/internal: session persistence listing failed: corrupt Zstandard session log: first frame is not exactly one header line

What the corrupt file looks like

• It decompresses fine with standard zstd (this is not a torn trailing frame). The first decoded line is a normal event, e.g.:

{"type":"agent/inbox/spliced","seq":3,"time":...,"data":{"target":"next-turn", ...}}

• The first surviving event has seq: 3, i.e. the header plus events seq 0..2 are missing — as if the beginning of the file was truncated/replaced, rather than a partial write at the end. Files are single-generation (session.v3.jsonl.zstd, no plain sibling).
• All three affected sessions use the session-<uuid> directory naming.

Impact

• One bad artifact bricks the harness: dsh web cannot start at all, not just the affected session.
• When boot succeeds, the session list returns nothing for every workspace.

Expected

• Writer: a session log must never lose frame 0. New generations should be published atomically (write temp + rename) and appends must never truncate the existing prefix.
• Reader: SessionPersistence.list() / WorkspaceRegistry.listStoredHeaders should skip (or quarantine) an unreadable log and continue; boot should not be blocked by a single corrupt session.

Workaround

Move the offending session directory out of ~/.dsh/sessions/ (e.g. to ~/.dsh/quarantine/). dsh web then boots and lists normally.

Notes

The raw logs contain session content, so I have not attached them; the redacted first line above is the essential shape. I can provide structural dumps (event type/seq only, no content) or a sanitized sample if that helps.

[srstack]

Follow-up with a runtime lead: on the affected machine the harness was running under Node v22.22.3. dsh's session persistence uses node:zlib's zstd (zstdCompress/zstdDecompress), which is still experimental on Node 22.x — a writer-side bug there would fit the symptom (frame 0 lost / prefix replaced, while the rest of the stream stays valid).

I switched the harness to Node v26.8.2 and it boots and lists sessions normally. I'll keep watching whether corrupt logs recur.

Is 26.x the supported runtime for 0.1.5-rc.1 (no engines field is published), and are there known Node-22 zstd issues? If the corruption is a Node-22 node:zlib bug rather than a dsh one, feel free to close this as upstream.

(For reference, the reader-side robustness request stands regardless: one unreadable log currently blocks dsh web startup and empties every workspace's session list.)

[moonquake2004]

Independent confirmation, plus one correction to the framing that matters for detection.

The enforced condition is narrower than "the first line is an event". @deepseek-ai/dsh-session-persistence-jsonl (lib/index.js:1891 and :2185) checks:

if (plaintext.length === 0 || plaintext.indexOf(10) !== plaintext.length - 1)
  throw new Error("corrupt Zstandard session log: first frame is not exactly one header line");

i.e. the first zstd frame's plaintext must be exactly one line (its only \n is the last byte). So it is not enough that the first line is the header — a first frame that wraps the header plus subsequent events fails the same way, and a single-frame container fails by construction. That widens the class: anything that disturbs the frame boundary, not just a lost header, blocks startup.

An honest note from the tooling side. We build an offline diagnostics tool (dsh-doctor), and it did not catch this class: constructing a log whose first row is user/message made S1/S2/S6/S8/S10 all pass — they analyse the event stream — while the whole-store scan reported "1 session, healthy, 0 damaged". A check that stays silent on a boot-blocking defect is the worst failure mode a diagnostic can have, so we treated it as a bug in our tool and fixed it: S13 now validates (a) the first row is the session header and (b) the first frame decodes to exactly one line, and S11 counts this class as damaged. It is offline and safe on a live store:

npx @moonquake2004/dsh-doctor                       # full store scan; S13 per session, S11 rolls up the damaged count
npx @moonquake2004/dsh-doctor --session <path-to/session.v3.jsonl.zstd>

Two notes that may help triage. (1) zstd -dc decodes all frames and therefore hides boundary damage; Node's one-shot zstdDecompressSync returns only the first frame — so the two disagree, and neither alone shows where the boundary moved. (2) For recovery, move the whole session directory out of sessions/ (isolation) rather than deleting it: once the blocking log leaves the tree, startup succeeds and the rest of the history comes back.

On the recurring part: three times in five days points at whatever establishes the first frame on the write path rather than at user action — your report is the reproducible signal for it. Ours only makes the damage visible before the boot fails.

[moonquake2004]

Your runtime lead checks out, with a source anchor — and the engines part has a twist that matters for how this gets closed.

The dependency on Node's built-in zstd is direct. @deepseek-ai/dsh-session-persistence-jsonl (lib/index.js:15) does:

import { constants, createZstdCompress, createZstdDecompress, zstdCompress, zstdDecompress, zstdDecompressSync } from "node:zlib";

and uses them for the actual log I/O (:1263 reads the first frame via zstdDecompressSync(source.subarray(start, end)), :1287/:1368 wrap the async pair). So the writer and the reader of every .zstd session log are the runtime's own zstd implementation — your hypothesis is well-founded, not speculative.

On the supported runtime: 0.1.5-rc.1 publishes no engines field. Verified against the registry metadata — there is nothing to declare a supported range, so "is 26.x supported" has no authoritative answer from the package. The range that circulates in the community (^22.19.0 || >=24.0.0) comes from the v1 vocabulary alignment (#1719/#2259), not from a manifest. Note what that means here: 22.22.3 satisfies ^22.19.0 and 26.8.2 satisfies >=24.0.0 — both are "in range", so an engines-based check cannot separate your affected machine from your working one.

What we can add empirically: on Node 24.20.0 the same zstd calls emit no ExperimentalWarning, so the experimental marking is version-dependent rather than a fixed boundary. Rather than hardcode a version table, we added E12 to dsh-doctor, which probes the running Node the same way (subprocess + ExperimentalWarning detection) and reports the runtime's state honestly, without asserting causation — plus a separate branch for runtimes that have no zstdDecompressSync at all, where .zstd logs simply cannot be read or written.

Reader-side robustness: agreed, and it is now detectable offline. S13 validates a log using the harness's own read path — zstdDecompressSync decodes only the first frame, so checking "that frame is exactly one header line" reproduces the failing condition in dsh-session-persistence-jsonl:1891/2185 exactly, including the frame-boundary and single-frame-container cases that a plain "is the first line a header" test misses. It is safe on a live store and tells you which log to isolate before you restart, instead of after the boot fails.

[ciceroyang]

On the runtime question, two verified facts that change how this should be closed.

Node 22.22.3 is inside the supported range. The repo root declares it — deepseek-harness/package.json:8:

"engines": { "node": "^22.19.0 || >=24.0.0" }

22.22.3 satisfies ^22.19.0, and so does 26.8.2 via >=24.0.0. So the corruption you hit is not an unsupported-runtime story: if the writer-side node:zlib zstd on 22.x can produce this, it can produce it inside the declared window. Switching to 26 is a good mitigation, but it does not answer whether 22.x is safe to declare — that is the bug, and it is worth leaving open rather than closing as upstream until someone can reproduce it on 22.x deliberately.

The engines field is also absent from every published @deepseek-ai/* package, so npm never warned you either way — which is exactly the gap reported in #2259 (the root declares a range; the published packages carry nothing). That is why "is 26.x supported" has no registry answer to check.

The reader-side point stands, and it has a cheap shape

One unreadable log should not be able to say "no sessions". The difference between a one-session incident and apparent total history loss is entirely in WorkspaceRegistry.listStoredHeaders:

• skip the unreadable session per entry, keep the ones that parsed;
• surface the count and the path of what was skipped (e.g. N sessions unreadable, M listed), so the UI can show a degraded state instead of an empty list;
• only fail the call when nothing at all could be listed.

Fail-soft per session turns a boot-blocking corruption into a visible, recoverable one-session problem, which is the same argument as fail-soft plugin loading generally.

An offline detector for exactly this condition

We shipped the check today in ciceroyang/dsh-doctor 0.5.4: log_health now enforces the condition moonquake2004 quoted — the first zstd frame's plaintext must be exactly one line, and that line must be the type: session header — so the failure can be found before the next dsh web start, with the reason in detail and no dsh web needed. Fixtures cover both variants from this thread: header+events wrapped into one frame, and an event-first frame.

node doctor.mjs --profile ~/.dsh   # log_health reports the first-frame violation by name

Release: https://github.com/ciceroyang/dsh-doctor/releases/tag/v0.5.4

It does not repair the log; it makes the condition visible offline and per-log, which is the piece that would have saved you the "all history is gone" window.

[ciceroyang]

两个补充,第二个可能会改变你们的复现方式。

engines 的机制:这个范围确实是仓库根声明的,但声明在私有根 workspace 上,而不是任何一个会发布的包上——package.json:2 是 "name": "@deepseek-ai/dsh-root",:5 是 "private": true,版本 0.1.0-rc.5。这解释了为什么 registry 查不到:没有任何已发布包会继承它,所以 npm 既不会校验也不会警告。你说的「范围来自社区对齐而不是 manifest」和「根上写了」两件事同时成立,而私有根就是它们之间的机制。这也正是 #2259 要解决的问题。

离线检查正在收敛到同一处:你们加了 S13/S11,我们这边也把 log_health 扩成了同样的条件(首帧明文必须恰好一行,且是 session header)。这里有个形态差别值得记一笔——你们是全库扫描 + S11 汇总 damaged 计数,我们是抽样最近 3 个日志并在 detail 里给原因。对「一个日志阻断整个启动」这一类,全库扫描是更对的形态,因为抽样恰好可能漏掉那一个;我打算把抽样改成可选的 --all-logs(或者直接扫全库,反正是纯离线读取)。

关于边界移动的诊断:你说的 zstd -dc 与一次性 zstdDecompressSync 的分歧很关键。还有第三条路:结构化扫描帧头(zstd 帧魔数 + block 布局,不做解压)能直接给出每个帧的字节区间,于是"边界被移到了哪里"是可测的——我们做会话聚合时就是用这种方式逐帧切分的(一次性解压只返回第一帧,这也是为什么必须先扫帧)。如果这个损坏是写侧偶发地把 header 和事件压进同一帧,字节区间的变化会比"解码不一致"更早暴露它。

恢复方式很实用,值得置顶:把整个会话目录移出 sessions/ 而不是删除——列表遍历看不到它,启动就能过,其余历史全部回来。这比删除安全得多,也给了之后分析这个文件的机会。

[ciceroyang]

按上一条说的做了:抽样改成可全库扫描,刚刚发在 dsh-doctor 0.5.5。

node doctor.mjs --all-logs

默认仍是抽样最新 3 个(快);--all-logs 扫全部会话日志,fail 时在 detail 里点名具体文件路径,便于直接隔离。为控制内存每个日志只读取头部 4MB——首帧是判断对象,通常只是一行 header;首帧没完整落在头部内的记为「未判定」而不是判 pass。

加这个的原因正是你描述的那种静默:唯一那个坏日志可能刚好在抽样之外,工具报 pass 而启动失败。新增的回归用例就锁这个场景:4 个日志里最旧的一个 header 损坏、其余 3 个健康——抽样给 pass(缺口真实存在),--all-logs 给 fail 并点名它。

https://github.com/ciceroyang/dsh-doctor/releases/tag/v0.5.5

[moonquake2004]

Correction to something I said above, now that @ciceroyang has traced it: I claimed the ^22.19.0 || >=24.0.0 range was community vocabulary rather than a manifest. That was wrong — the range is declared in a manifest, and I verified it against master just now:

// deepseek-harness/package.json (repo root)
{ "name": "@deepseek-ai/dsh-root", "version": "0.1.5-rc.2", "private": true,
  "engines": { "node": "^22.19.0 || >=24.0.0" } }

So the accurate statement has two halves, and I only had the second one:

• The range is real and official — it is the repo root's engines.node.
• But it sits on a private: true workspace package, so no published package inherits it: the registry shows nothing, and npm therefore neither validates nor warns at install time. That is the actual reason "there is no engines field" appears true from the outside — and it is a sharper finding than mine, because it means the constraint exists and is simply unenforced for everyone installing from npm.

Practical consequence for the tooling side: our E3 check's range was hardcoded from the v1 vocabulary alignment and turns out to match the declared engines exactly — so the check agrees with the official intent, which is reassuring, but it also means the number is maintained by hand and can drift when upstream changes it. We have corrected our own wording (it previously said "not from a manifest") and noted the maintenance risk. Ideally it reads the repo root when a checkout is present and falls back to the built-in value otherwise.

On your --all-logs addition: that is the right fix for the sampling blind spot, and the "read only the header 4 MB, otherwise mark as undetermined rather than pass" detail is exactly the discipline — an unreadable first frame is not a healthy one. Our whole-store scan already covers every log for this class (it was the "1 session, healthy, 0 damaged" line that made us treat our own silence as a bug in the first place); what yours adds is doing it in bounded memory, which we should copy.

[ciceroyang]

谢谢核对与更正。你补的那半句我完全同意,而且我认为它比「registry 里查不到 engines」这个观察更值得写成结论:约束是真实且官方的,只是没有被任何发布物继承,所以对所有人都不生效。

顺着这个,有一个共同的维护风险要记下来:你们的 E3、我们的 node 检查都把 ^22.19.0 || >=24.0.0 写成了手维护的常量。两份实现目前都与仓库根一致,但上游一改就会各自漂移。真正的解法仍在 #2259:让已发布的入口包(@deepseek-ai/dsh)带上 engines,那么两个工具都能读安装树的元数据,而不是抄一个数字;在那之前,任何写死这个范围的地方都该标注出处与核对日期。

另外你那句「一致是巧合还是有意」——从我们的角度是有意的:这个范围来自官方仓库根声明,不是社区约定。所以你之前的表述其实指向了正确的方向,只是机制说反了;现在两边记录一致了就好。

[moonquake2004]

同意你那句更该被写下来的结论：约束是真实且官方的，只是没有任何发布物继承它，所以对所有人都不生效。这比"registry 里查不到"准确，也更有行动含义——它说明矛盾不在文档，而在发布链。

你的维护风险我照做了（dsh-doctor@0.4.27）：

• 默认仍用内置常量，但 E3 的 detail 现在明写来源与核对日期：「内置常量（出处：仓库根 package.json engines.node，核对 2026-09-15）」——这样读报告的人自己就能判断它是否过时，而不是只看到一个数字；
• 若设置 DSH_DOCTOR_HARNESS_ROOT 指向 harness 检出，就真读该检出仓库根的 engines.node，detail 改为「真读 <path>」；判定走的是 P19 那套区间语义（同一份代码，不另写一份，避免两处语义再次漂移）。

关于 #2259 是真正的解法，我同意，并想补一条它比"让工具能读元数据"更强的理由：一旦已发布的入口包带上 engines，npm 自己就会在安装期给出 EBADENGINE 警告或拒绝。那才是唯一能触达"从不运行任何诊断工具的用户"的机制——我们这类工具只能覆盖已经装了工具的人，而这条约束现在恰好对所有人都不生效。所以 #2259 修的是覆盖面，不只是我们的实现质量。

顺带说一句：你那句"从我们的角度是有意的"也帮我修正了一处判断——我之前把它当成社区约定，是因为只查了 registry（正确的观察、错误的机制）。两边记录现在一致了。