单个损坏的会话日志会导致整个 dsh 无法启动（0.1.6-alpha.2 实测）

[f-infinite-z]

环境

• dsh 0.1.6-alpha.2（npm 全局安装），Windows 11，Node v24.14.0，web profile
• 会话存储位置：$DSH_HOME/sessions/<workspace>/<session-id>/session*.jsonl.zstd

问题怎么暴露的
一次文件恢复工具的事故把一个会话日志写成了全 null（恢复工具的常见产物）。之后 dsh web 完全无法启动；唯一的办法是从报错信息里找到文件、手动移出 sessions/ 目录。

实测行为矩阵（隔离 DSH_HOME，dsh 0.1.6-alpha.2）

#	会话文件状态	启动结果
1	正常	正常启动
2	全 null 填充（invalid frame magic at byte 0）	中止
3	截断一半（torn frame）	正常启动（跳过）
4	目录重命名（header id 与路径不匹配）	中止
5	首帧魔数损坏	中止
6	空文件	正常启动（跳过）

中止发生在哪里（源码链路）
listArtifacts（dsh-session-persistence-jsonl）→ readGenerationHeader → readFirstZstdLine 在帧魔数损坏时抛错；路径/header 不匹配在 assertStoredIdentity 抛错。错误经 WorkspaceRegistry.listStoredHeaders 直接向上传播（workspace 的 sessionKnown 注释明确了这一设计："a failing sessionPersistence.list() propagates so storage faults never masquerade as an unknown session"），在 workspace 插件的初始化（cordis.init 生命周期）阶段失败，导致必需的 bootstrap Include 失败，进而整树中止。

为什么这看起来像一处不一致
listArtifacts 其实已经容忍读不出的会话：外部格式跳过、首行 JSON 损坏返回 undefined、torn/空文件正常启动。代码注释写明了设计意图："Listing skips a foreign format while opening its id still refuses with the selected physical location."（列出时跳过、显式打开时严格拒绝）。帧魔数损坏与 identity 不匹配属于同一类「这个列表项读不出来」，却直接中止了列出——于是单个坏文件拖垮整个应用，而列出路径本已有既定的跳过机制。

建议的修改（最小）
在 listArtifacts 的 catch 中，把单个会话的读取失败当作跳过项处理（记录一条带文件名的警告），显式 open/attach 保持严格（它已经会用物理位置拒绝）。这样对用户操作的 fail-loud 不变，同时让启动对单个坏文件有韧性。另外建议加一个 CLI 修复入口（如 dsh sessions prune --corrupt），让遇到这个问题的用户有内置出路。

背景
在做生态的插件运维工具（dsh-plugin-ops）时踩到的；如果方向认可，我们很乐意帮忙测补丁。

[argszero]

Your chain is right, and the matrix is the most useful part of the report — six states, measured, with source attribution. I re-checked all six against ddefc45fbc before writing this.

Two refinements, then the part where I'd argue against your proposal.

The tolerance set is four cases, expressed in two different vocabularies

The skip decisions are not all made in listArtifacts. readGenerationHeader (session-persistence-jsonl/src/index.ts:1013) already returns undefined for three of them, and listArtifacts only decides the fourth:

state	where it is tolerated	how
absent file	:1020	isENOENT → undefined
zero bytes (row 6)	:1343	first read() returns bytesRead === 0 → undefined
unparseable first line	:1027	JSON.parse catch → undefined
malformed header	catalog status === 'malformed'	undefined
unsupported format	readGenerationHeader throws SessionFormatUnsupportedError	the only skip expressed at the listing boundary — listArtifacts's catch (:987-991)

So rows 2, 4 and 5 fail not because the listing "forgot a case" but because they throw a bare Error from a different module than the one the boundary knows about:

• row 2 / 5: scanZstdFrames → zstd.ts:56, invalid frame magic at byte N (and the reserved-bit check at :62);
• row 4: assertStoredIdentity → index.ts:1459-1460, and note it runs with expectedId === undefined from the listing path (:992 calls readGenerationHeader(selected, undefined, signal)) — it is not an "open" refusal that leaked into the list, it is recomputation that the list performs itself.

The asymmetry is therefore vocabulary-shaped: skip is spelled undefined in one layer and a specific exception class in the other. A catch { continue } in listArtifacts closes the symptom while making the second spelling unnecessary — and it will keep matching whatever the next layer happens to throw.

Why I would not ship "treat a failed read as a skip"

The sessionKnown comment you quote is a design statement, and the failure it guards against is exactly the one a blanket skip introduces. If the listing starts dropping entries on any error, then row 4 stops being "dsh cannot boot" and becomes "my session vanished from the workspace list, with no message" — the same file, the same defect, now silent. Sessions drive archive state, quota accounting and the dsh sessions views; an entry that silently leaves the listing is a state divergence, not a degraded boot.

The distinction worth preserving is:

• a listing entry the harness cannot read → skip, but attributed: carry the skipped entries out of list() (path + reason) so [Service.init] can proceed and report them. Boot resilience without silent loss.
• a genuine invariant break → still fatal. :998, duplicate JSONL session id "…" appears in multiple project directories, must stay strict: two directories claiming one id makes the id → path mapping ambiguous, and that is not a boot-resilience question (same class as storage-sqlite: u_<unit>_<table> is ambiguous, so two domains can silently share one physical table #4264). I would not weaken it as part of this change.

That makes your "minimal change" slightly larger than a catch, but it is the version that does not trade a loud failure for a quiet one.

Row 4 is predictable before the boot

Worth highlighting because it is the row with the cheapest fix and the one your matrix proves the most about: the identity refusal is path recomputation, and generationLogPath/sessionDir/encodeSegment are pure functions of the header (format.ts:196-282). Nothing has to be read to predict it — only the directory names have to be compared against the header. The comparison the backend performs is path !== expectedPath && !sameFile(...), so a symlinked layout is accepted, but a directory renamed by hand is a definite mismatch.

What I built on this

I maintain @argszero/cordis-plugin-session-audit, a pre-boot audit for exactly this family, and your matrix is now the whole of its container/path surface. 0.1.5 (published today) audits both containers and reproduces the backend's derivation, so all six rows have a name and a severity before dsh starts:

$ session-audit "$DSH_HOME/sessions"

Session (unreadable container) — …/--Users-argszero-scm-my-project--/9c8d7e6f-…/session.jsonl.zstd
  format v-1 · 0 events · 4096 bytes · seed length 0 · zstd
  findings: 1
    [error] UNREADABLE_ARTIFACT @0 — corrupt Zstandard session log: invalid frame magic at byte 0 — the artifact listing aborts on this file, which takes the whole application boot down with it. The session cannot be opened; move the file out of the sessions root (or restore it) to boot again.
  ⚠ needs manual attention (replay would fail or drop history)

Session b7f1c2a0-… — …/b7f1c2a0 (renamed by hand)/session.jsonl.zstd
  format v0 · 2 events · 272 bytes · seed length 0 · zstd · 3 frame(s)
  findings: 1
    [error] SESSION_PATH_MISMATCH — the artifact sits in directory "b7f1c2a0 (renamed by hand)", but its header id "b7f1c2a0-…" identifies "b7f1c2a0-…". The backend re-derives the path from the header and refuses this read ("header id … and cwd identify …"), which aborts the artifact listing and the application boot. The comparison is a path shape only: if both names resolve to one file (a symlink or a hard link) the backend accepts the artifact and this finding is advisory. Otherwise move the file back to its identified directory.
  ⚠ needs manual attention (replay would fail or drop history)

Session b7f1c2a0-… — …/b7f1c2a0-…/session.jsonl.zstd
  format v0 · 2 events · 272 bytes · seed length 0 · zstd · 3 frame(s)
  OK — no corruption findings.

=== summary ===
  sessions scanned: 3
  clean: 1 · needs-manual: 2 · error findings: 2 · warn findings: 0

  ⚠ 2 artifact(s) would abort a boot or lose history — resolve these before launching dsh.

Exit code 1, so it can gate a launch. npm: https://www.npmjs.com/package/@argszero/cordis-plugin-session-audit, source: https://github.com/argszero/cordis-plugin-session-audit. The path derivation is verified against the harness's own encodeSegment/projectKey rather than against a copy of them — test/paths.spec.mjs slices both functions out of packages/session/session-persistence-jsonl/src/format.ts and compares over 22 awkward inputs (escapes, separators, Unicode, a 300-char path that must truncate at the same point). It skips when no checkout is present; a green tick over two implementations that agree on being wrong is worse than a skip.

One caveat, since the tool exists precisely because of it: zstdDecompressSync accepts a concatenated container and decodes only the first frame without error. A scanner built on it reports a badly truncated session as clean. The harness appends per-batch frames, so per-frame scanning is not an optimization.

On dsh sessions prune --corrupt

Agreed on the need, with one constraint from the matrix: prune must not be the first verb, because row 4 is recoverable by moving the file back to the directory its header names — the header is undamaged. prune --corrupt as the only entry point turns a recoverable corruption into data loss for the sessions where the fix was a rename. If you do build it: --repair-paths (move, and refuse when the target already exists) alongside --quarantine (move out of the root, never delete), and auto-deletion only behind an explicit flag with the file's size and finding printed first.

Happy to test a patch if the direction lands — the six rows are already a fixture shape I can point the audit at.

[f-infinite-z]

Thanks — and thanks for re-checking all six rows against ddefc45fbc. The vocabulary-asymmetry framing is more accurate than mine: I described the skip set as "what the listing tolerates", when the real shape is two spellings of skip (undefined out of readGenerationHeader, SessionFormatUnsupportedError at the listing boundary) plus bare errors thrown from modules the boundary does not know. And you are right that row 4 is recomputation performed by the listing itself (expectedId === undefined), not an open refusal that leaked into it — that changes how the row should be described.

You are also right about the proposal, and I will not defend it: a blanket catch { continue } trades a loud failure for a quiet one, and the state divergence you name (archive state, quota accounting, the dsh sessions views) is worse than a failed boot because nothing surfaces it. "Skip with attribution" — carrying the skipped entries out of list() with path and reason so [Service.init] can proceed and report — is the version worth shipping. Same for keeping duplicate JSONL session id strict: two directories claiming one id is an ambiguity no caller can recover from, not a resilience question.

Row 4 being predictable pre-boot is the direction I am building in, from the plugin side. I maintain dsh-plugin-ops — startup-lifecycle protection for dsh plugins: pre-boot static checks (patch-row resolution through the runtime generation, dependency drift, peer gaps), boot-failure attribution via the CLI's saved startup diagnostics, and reversible repairs. Session containers are the surface we do not audit; @argszero/cordis-plugin-session-audit covering it with a pre-boot exit code is the split I would want — the plugin tree on one side, session artifacts on the other. If you are open to it, I would rather cross-reference than duplicate: our check could point at session-audit for the container layer, and I am happy to align on output shapes so one gate can consume both.

The zstdDecompressSync caveat is a good catch for anyone building scanners — noted; per-frame scanning is not an optimization.

On prune: agreed that it must not be the first verb. --repair-paths (move back, refuse when the target exists) before --quarantine (move out, never delete), deletion only behind an explicit flag with size and finding printed first — recoverable before destructive is the right ordering. If the upstream change lands as skip-with-attribution, I am glad to test it against a real corrupt-container profile.