Add a session doctor and versioned migrations

[CHXZAVARKA]

Problem

The session format is still version 0, and the persistence layer correctly refuses formats it cannot read. That is safe, but there is no user-facing migration or recovery path yet.

Recent reports show the practical cost of this gap. A malformed or interrupted JSONL log can make a session unreadable, and in some cases one bad session can stop a workspace from loading. Examples include #496, #647, #1452, #1473, and #1497.

Fixing each writer is necessary, but users also need a supported way to inspect and recover durable history before the format starts changing between releases.

Proposal

Add an offline session doctor and a versioned migration pipeline.

Possible commands:

dsh session doctor <session-id> --check
dsh session doctor <session-id> --repair --output <new-path>
dsh session migrate <session-id> --to <version> --output <new-path>

Repair and migration should write a new artifact by default. They should not overwrite the source log. The command should produce a machine-readable receipt listing the detected invariants, applied repairs, dropped or synthesized events, source hash, and output hash.

How I would implement it

The doctor should use the same event decoder and invariants as normal persistence. It can classify failures such as a torn tail, duplicate sequence, gap, unsupported event type, invalid synthetic closer, or a version mismatch.

Repairs should be explicit transforms with narrow preconditions. A transform that cannot prove a safe result should stop and explain the remaining problem instead of guessing.

Format migrations should be pure, versioned SessionEvent transforms. Each migration should be repeatable, tested against frozen fixtures, and able to emit the same audit receipt as a repair.

At workspace startup, one unreadable session should be quarantined and reported rather than preventing unrelated sessions from loading. The UI can then offer the doctor command or export the failing log.

Acceptance criteria

• --check never changes data and reports the first broken invariant plus its event position.
• --repair and migrate preserve the source and write a separate output artifact.
• Every change appears in a JSON receipt with source and output hashes.
• Repairs are deterministic and covered by fixtures for known JSONL failure modes.
• An unreadable session does not prevent the rest of the workspace from loading.
• A format bump ships with an explicit migration from the previous supported version.

The current refusal behavior is documented in the persistence subsystem.

[Electricitysheep]

session doctor + 版本迁移——会话格式 version 0 拒绝未知格式是对的（fail-safe），但没有诊断/迁移工具确实让用户被动。

配合 #1473/#1497（损坏会话拖垮 boot），一个 doctor 工具能救不少会话。第 8 章会话管理记录了这个痛点：https://github.com/Electricitysheep/dsh-handbook/blob/main/docs/08-tools-context.md

[argszero]

This proposal is exactly what the session-log family of reports has been converging on — I've been involved in three of the four corruption threads you cite (#1452, #1473, #1497, plus #1449 for the serializer-poison path), and your design covers the gaps they exposed. Strong +1. A few source-level specifics from that work to fold in:

The four distinct failure modes the doctor should classify (all seen in the wild today)

1. Duplicate seq segments (BUG: 同一 DSH_HOME 下多进程并发写同一会话日志，导致 seq 重复、整段历史无法加载 #1452, seq 序号重复导致对话加载失败 #1333): two processes append via unlocked open('a') (session-persistence-jsonl/src/index.ts:649) — same seq range written twice. Data intact, just duplicated; both affected users recovered by hand-deleting 4 lines. Repair = dedup with audit receipt.
2. Replayed committed tail (Bug: corrupt session log after unclean exit — replayed events cause seq gap in committed region, history unrecoverable #1497): unclean exit → write-behind recovery re-appends from a stale in-memory cursor after session/end-seed (core/session/src/index.ts:545-546). Repair = truncate to the last committed watermark.
3. Malformed first zstd frame ([Bug] A single corrupted session log prevents the whole workspace from booting (loader entry "workspace" fails to apply) #1473): assertZstdHeaderFrame (:47-51) throws on a structurally-complete frame decoding to 0 or 2+ lines; listArtifacts (:472) propagates → whole workspace won't boot. Torn frames are already skipped (asymmetry). Repair = re-frame / quarantine.
4. Content poisoning (bug 任何会话只要遇到截断在 emoji 中间的工具结果，就会永久 400 无法继续 #1449, Bug + tested fix: truncated tool-call arguments permanently poison a session (llm-deepseek serializer) #1519): lone surrogates (flattenText, llm-deepseek/src/serialize.ts:56-61) or malformed tool-call arguments (serializeAssistant, :71-99) permanently 400 every resume. Repair = sanitize content in place (surrogates → U+FFFD; invalid JSON args → {}).

Design points your proposal gets right (confirmed against the codebase)

• --check never mutates: correct — the loader's invariants (SessionLogScanner contiguity, assertSessionEventEnvelope, surface transitions) are all pure scans; a check pass needs no writes.
• Repair writes a new artifact, never overwrites: essential — both BUG: 同一 DSH_HOME 下多进程并发写同一会话日志，导致 seq 重复、整段历史无法加载 #1452 and Bug: corrupt session log after unclean exit — replayed events cause seq gap in committed region, history unrecoverable #1497 users edited their logs by hand; an atomic repair --output with source/output hashes would have made that safe and auditable.
• Quarantine at workspace startup: directly fixes [Bug] A single corrupted session log prevents the whole workspace from booting (loader entry "workspace" fails to apply) #1473's total outage. listArtifacts should skip+warn per artifact (return a { header?, path, error } marker) rather than throw — the boot path must never die on one bad session.
• Versioned migrations: with SESSION_FORMAT_VERSION = 0 there's literally zero compat burden — the right time to establish the migration pipeline is before the first real version bump.

One addition worth considering

A JSON audit receipt (your machine-readable receipt) is also the natural input for the UI/CLI flow: after --repair, the user can diff exactly which events were dropped/synthesized. Consider making the receipt the only mutation record — no repair without a receipt — so the doctor is provably audit-safe.

If you'd like, I can consolidate the four threads' source evidence (exact line numbers + repro shapes above) into the proposal body so maintainers have one self-contained document.

[CHXZAVARKA]

Thanks, this is the source-level evidence the proposal needed. Please add the exact locations and minimal repro shapes as a follow-up in this thread. Keeping that evidence in your comment preserves attribution and gives maintainers one place to verify the repair matrix.

I would keep one boundary explicit: these repairs do not all have the same safety level.

• Exact duplicate event ranges can be removed when the events are byte-for-byte or envelope-equivalent.
• A replayed tail can be truncated only when the last committed watermark is provable.
• A malformed frame can be reframed when its decoded event is valid; otherwise it should be quarantined.
• Lone surrogates can be converted to well-formed text in the new output artifact.
• Replacing invalid tool-call arguments with {} changes meaning. That should require an explicit lossy-repair flag, with quarantine as the default.

The receipt could classify every action as safe, lossy, or unrepaired. I agree that no repair should be produced without a receipt. Also, "sanitize in place" should mean inside the new output artifact, never inside the source log.

Your four failure classes would make a good initial fixture set for the doctor.