[Bug] 0.2.1-rc.5: a session log that fails the protected-head invariant is silently truncated to a frame prefix on app start (no backup); writer still emits the invalid append

[rusliksu]

Component: @deepseek-ai/dsh-session-persistence-jsonl (recovery/rewrite path), @deepseek-ai/dsh-agent-loop (SystemPromptProjection), @deepseek-ai/dsh-session-format-v3-to-v4 (Relationships.foldSurface)
Version: DeepSeek Harness 0.2.1-rc.5 desktop (Electron 44.7.0, Node 24.21.0, Windows 11 x64); session format v4, zstd multi-frame log
Related: #10619 (same write-path invariant violation on 0.2.1-rc.2 — still reproduces on rc.5), #12007, #12008, #8125, #8888

Summary

The write-path invariant violation from #10619 still exists on 0.2.1-rc.5: a session whose surface starts with user/message (imported/forked history, no system/message) gets system/message appended by SystemPromptProjection.project() on the first live turn, and the log becomes unreadable.

What is new here: on this build the next app start silently replaced the log with a prefix of complete zstd frames — 729,460 bytes / 1,058 events became 4,129 bytes / 34 events — and kept no backup. The rest of the history was only recoverable because a full decode had been captured before the rewrite.

Evidence

Timeline (local time, Windows):

• 00:21:23 — log intact: 729,460 bytes, 428 complete zstd frames, 1,058 events, dense seq 0..1057, every record parses, every frame decodes cleanly.
• ~00:20 — GUI reports stored session "<id>" is corrupt: ... SessionFormatError: system/message requires a protected first surface head.
• 00:21:52 — the file is replaced by 4,129 bytes: exactly its first two complete frames (frame boundaries 0–152–4,129 preserved), decoding to the header + 34 events (seq 0..33). At the same second the mtimes of ~15 other session logs changed too, i.e. this happened during an app-start pass, not from a manual edit.
• No .bak and no copy of the original bytes remained anywhere under the DSH data directory (only the session projection cache survived); 1,024 of 1,058 events were gone from the artifact.

The kept prefix is exactly the complete frames preceding the frame that contains the first invalid event — some recovery/rewrite path appears to commit a validated frame prefix and never preserves the rest.

Event shape that produces the invalid log (sanitized):

seq 3   turn/start        turn 1
seq 4   step/start        turn 1, step 1
seq 5   user/message      surfaceOp: append   <- imported history starts here, no system/message
...
seq 34  session/end-seed  {}                  <- seeded/forked history cut
seq 37  turn/start        turn 6
seq 39  step/start        turn 6, step 1
seq 40  system/message    surfaceOp: append   <- SystemPromptProjection; illegal without a protected head

The session then kept appending events for ~35 minutes (two more turns completed) — the writer path never validates this relationship, only the loader does:

// dsh-session-format-v3-to-v4/lib/index.js, Relationships.foldSurface (~:597-601)
if (event.type === "system/message" && this.surface.length > 0 && this.protectedHead === void 0)
  throw new SessionFormatError("system/message requires a protected first surface head");

Expected

1. The writer must not emit that append: either fail fast with the same diagnostic, or materialize a protected head when the inherited/imported cut is created (the v3→v4 migration already inserts an inert placeholder head in the workaround from [Bug] 0.2.1-rc.2: sessions with non-empty surface but no system/message head fail to load (SessionFormatError: requires a protected first surface head) #10619).
2. A log that fails validation on read must never be rewritten or truncated. If automatic repair is offered, the original bytes must be preserved (.bak/copy) and the loss reported. The documented contract only allows discarding an incomplete final frame — committed complete frames must reject as corruption, not be silently dropped.
3. A supported repair path would help: a valid repair inserts a synthetic system/message head at the first step and converts the first real system/message into a replacement over that head (renumbering seq, surfaceOp, sourceEventSeqs, messageSeqs). I verified that a log repaired this way loads and continues normally.

Impact

Silent, irreversible loss of committed chat/tool history on startup for any affected session — the GUI shows only the "corrupt log" error, nothing about truncation or data loss. In this incident the session was created by the seeded/forked-history path, and 1,024 of 1,058 events were discarded without warning.

I can provide a sanitized minimal log fixture and the surviving prefix artifact if that helps.

[rusliksu]

Sanitized minimal fixture attached: https://gist.github.com/rusliksu/4495d81e38654aed73e972129ddec218

The failing log — header + 13 events, synthetic text only, cwd omitted so the fixture is cross-platform:

{"type":"session","version":4,"id":"session-11111111-1111-4111-8111-111111111111","createdAt":1700000000000,"isSeeded":false,"delegationDepth":0}
{"type":"turn/start","seq":0,"time":1700000000000,"data":{"turn":1}}
{"type":"step/start","seq":1,"time":1700000000000,"data":{"turn":1,"step":1}}
{"type":"user/message","seq":2,"time":1700000000001,"data":{"content":[{"type":"text","text":"hello"}],"source":{"kind":"user"},"role":"user","id":"u-0001"},"surfaceOp":"append"}
{"type":"assistant/message","seq":3,"time":1700000000002,"data":{"turn":1,"step":1,"message":{"id":"a-0001","role":"assistant","content":[{"type":"text","text":"hi"}],"source":{"kind":"model","provider":"test","model":"test"}},"usage":{"inputTokens":0,"outputTokens":0,"cacheReadTokens":0,"reasoningTokens":0},"stream":[]},"surfaceOp":"append"}
{"type":"step/end","seq":4,"time":1700000000002,"data":{"turn":1,"step":1}}
{"type":"turn/end","seq":5,"time":1700000000002,"data":{"turn":1,"reason":{"kind":"completed"}}}
{"type":"session/end-seed","seq":6,"time":1700000000003,"data":{}}
{"type":"turn/start","seq":7,"time":1700000000003,"data":{"turn":2}}
{"type":"step/start","seq":8,"time":1700000000003,"data":{"turn":2,"step":1}}
{"type":"system/message","seq":9,"time":1700000000004,"data":{"turn":2,"step":1,"message":{"id":"s-0001","role":"system","content":[{"type":"text","text":"You are a test assistant."}],"source":{"kind":"system-prompt"}}},"surfaceOp":"append"}
{"type":"user/message","seq":10,"time":1700000000005,"data":{"content":[{"type":"text","text":"again"}],"source":{"kind":"user"},"role":"user","id":"u-0002"},"surfaceOp":"append"}
{"type":"step/end","seq":11,"time":1700000000005,"data":{"turn":2,"step":1}}
{"type":"turn/end","seq":12,"time":1700000000005,"data":{"turn":2,"reason":{"kind":"completed"}}}

The surface starts with user/message (seq 2) and never gets a protected head; after the session/end-seed {} cut, the new turn appends system/message (seq 9) — exactly what SystemPromptProjection.project() does when systemNodes()[0] === undefined — and the reader rejects the already-committed log.

Headless reproduction (run in a DSH checkout with installed workspace deps, Node 22+/24):

node validate-fixture.mjs repro-session.v4.jsonl
# SessionFormatError: system/message requires a protected first surface head

node validate-fixture.mjs control-session.v4.jsonl
# OK: 12 events validate (control-session.v4.jsonl)

control-session.v4.jsonl (in the same gist) is the same conversation without the offending append and validates cleanly — so the artifact is not damaged; the only defect is the write-path invariant violation.

In-app reproduction: node make-fixture.mjs repro-session.v4.jsonl, copy the resulting .jsonl.zstd to
%USERPROFILE%\.dsh\sessions\_no-cwd\session-11111111-1111-4111-8111-111111111111\session.v4.jsonl.zstd, then start DSH and open the session.

Note: the fixture reproduces the unreadable-log part only. The second part of the report — the startup rewrite truncating such a log to a frame prefix without backup — needs a real (or long synthetic) log and is described with the observed sizes/timeline in the opening post. Keep a copy if you reproduce in-app.

[rusliksu]

Follow-up: tried to reproduce the destructive part (startup truncation) with the fixture — it did not reproduce; correction to the "app start" claim.

What I did (isolated environment, no real user data):

1. Created an isolated DSH_HOME with a test workspace, placed the fixture session at
   sessions/<encoded-workspace>/session-11111111-1111-4111-8111-111111111111/session.v4.jsonl.zstd
   (fixture variant with a valid cwd, 621 bytes, sha256 prefix 7AC2F7B1...), plus a valid control session with an open turn.
2. Booted the shipped web app in that home: DSH_HOME=<iso> dsh --profile web --no-open --port 0
   (the same app stack the desktop shell serves). Also booted dsh-desktop-host directly with the desktop profile (plugins loaded except a few unresolvable ones).
3. Opened the session through the real web client (headless Chrome via Playwright, token URL) — the path the desktop UI uses on open.

Results:

• Passive start does not touch the log. After boot the corrupt fixture was byte-identical (621 bytes, same sha256), and no .bak/copy of it existed anywhere under the isolated home.
• Opening the corrupt session reproduces the read error, not truncation. The sidebar lists the session; opening it sends session/follow and the gateway returns:

  gateway/internal: stored session "session-11111111-1111-4111-8111-111111111111" is corrupt:
  session "...": stored log is corrupt: SessionFormatError:
  system/message requires a protected first surface head
  (raw log: ...\session.v4.jsonl.zstd)
  

  The UI shows "Failed to load history: ...". Afterwards the log file was still byte-identical and no backup was created.
• The write path works on success. A valid control session with an open turn in the same home was resumed when opened: the app appended session/end-seed, permission/preset, sandbox/mode, approval/policy and synthetic closers (488 -> 867 bytes, new frame appended). So the environment writes when restore succeeds; the corrupt session's failure path writes nothing.

So the "rewritten to a frame prefix at app start" part of my first post is not reproduced by a clean start or by opening the corrupt session; that claim was inferred from mtime/size evidence in the affected installation (log replaced by exactly its first two complete frames), and the responsible path is still unknown. Context from the affected installation: dozens of session logs received synthetic closers in the same second while the app was already running, so some background path does restore sessions at runtime — but our isolated client only restored sessions it opened.

Questions for maintainers:

• Is there any maintenance/migration/rewrite pass that can replace a current v4 log with its complete-frame prefix (canonical-generation rewrite / checksum upgrade / recoverable-tail fallback)? If yes, it should preserve the original bytes and be tested against this fixture.
• Does the desktop shell restore all sidebar sessions at startup (for live status), and how does that path handle a corrupt log? In our test only the opened session was followed.

Repro (same as the gist README):

node make-fixture.mjs repro-session.v4.jsonl
DSH_HOME=<iso> dsh --profile web --no-open --port 0     # passive start: file unchanged
# open printed URL, click the session: read error above; file still unchanged

[rusliksu]

Code search: is there a canonical-rewrite / checksum-upgrade / recovery pass, and does it keep a backup?

I audited the shipped 0.2.1-rc.5 bundle (all @deepseek-ai packages in app.asar\dsh\node_modules, plus the third-party bundles in the affected desktop profile). Short answer: there is no rewrite/upgrade pass for current v4 logs; the only in-place truncation is torn-tail repair, and it keeps no backup.

1. No canonical rewrite / checksum upgrade for existing logs

• Checksums are write-time only: CHECKSUM_OPTIONS (dsh-session-persistence-jsonl/lib/index.js:1296) and ZSTD_CHECKSUM_OPTIONS (:1565-1568, migration writer) pass ZSTD_c_checksumFlag: 1 when compressing new frames (append / materialize / migration output).
• The reader accepts both flavours: scanZstdFrames (:1305) parses the checksum bit if present and decompressZstdFrame (:1382) just delegates to zstdDecompress; nothing re-encodes an existing log to add checksums.
• Compression is fixed per store: a .jsonl / .jsonl.zstd mismatch is rejected (encodingMismatch, checkRootEncoding :3527-3549), never converted.
• No pass re-encodes/recompresses/strips a current log. (Searched for recompress, rewrite, canonical, .bak, checksum across all shipped packages.)

2. The only in-place truncation is torn-tail repair

• readZstdPrefix (:2981-3046) returns tornTruncateTo only when scanZstdFrames reported tornStart, i.e. EOF inside the final frame; for a file whose frames are all complete it returns tornTruncateTo: void 0.
• truncateTornTail (:2938-2941) calls repair (:3337-3346), which is literally truncate(path, offset) + fsync, then re-persists the complete records recovered from the torn frame. It is invoked lazily by the write handle before its first append.
• Append failure rollback (appendLines :3299-3335 / rollbackAppend :3327-3335) truncates only to the previous size of the file.
• Neither path copies anything first: no .bak, no snapshot, no log entry about the discarded range.
• Materialization of a new artifact (materialize :3195-3256) refuses when a log already exists (rejectExistingLog :3253) and publishes a temp file atomically; it cannot replace an existing current log.
• Historical migration (publishPreparedMigration :2078-2146) writes a new generation next to the old one; the README states "The source remains byte-identical" (README:87) — nothing to back up by design.
• The package's documented contract (README:77) is unambiguous: "Committed events are never rewritten"; "a caught write or sync failure rolls the file back to its prior length"; "A torn final Zstandard frame contributes only its complete decoded JSONL records"; "Checksum, decompression, or structural failure in a complete committed frame rejects as corruption."

The codebase does have a backup convention — but not for logs: JSON state documents are moved aside as <key>.json.bak.<stamp> (dsh-storage-json/lib/index.js:473-485) and plugin patch files as cordis.patch.yml.bak-<ts> (dsh-app-boot/lib/index.js:1245-1256). Session logs have no analogous mechanism.

3. No startup pass writes session logs

• dsh-workspace init lists stored headers only (listStoredHeaders, :391/:898).
• The session-search index reads bodies for indexing via readColdSessionLog (dsh-session-query-sqlite/lib/index.js:724), but that helper opens a read handle and appends interruptedTurnClosers in memory only — no storage mutation (see next bullet).
• dsh-session-query cold reads append interruptedTurnClosers in memory only ("without taking ownership or mutating storage", :22-53).
• A live resume appends closers through the normal write handle (append at EOF) — dsh-agent-loop/lib/index.js:1992; that explains the "many logs got closers in one second" observation, not a prefix rewrite.

4. Third-party context for the affected installation

The affected desktop profile previously contained @alpacachen/dsh-simple-worktree@1.1.3-desktop.20 (installed 2026-11-02 11:42), which disables and replaces the core session-persistence-jsonl, agent-loop, workspace, session-controller and others with forked "native" copies (cordis.patch.yml: disabled: true for those ids + insert: of native/lib/*), built against dsh 0.2.1-rc.2 (native/source.json, revision 074289f9). So before it was dropped from the profile, the effective writer may have been third-party code, not stock DSH.

I checked its vendored persistence too: same readZstdPrefix/truncateTornTail/repair logic (in-place truncate, no backup), and its "chat relocation" is logical — it writes cwd-placement.json / cwd-placement.required.json / cwd-relocations/*.json and overrides header.cwd; it does not rewrite the log file. A host crash log shows it was skipped on rc.5: Plugin @alpacachen/dsh-simple-worktree@1.1.3-desktop.20 is incompatible with dsh 0.2.1-rc.5 (crash-2026-11-02T21-31-09-337Z-host.log). No cwd-placement* artifacts exist under ~/.dsh/sessions, so relocation never touched these logs.

5. Consequence for the incident

Nothing in the shipped code (nor in the previously installed forked persistence) can produce the observed artifact — a complete 729,460-byte / 428-frame log replaced by exactly its first two complete frames (4,129 bytes):

• torn-tail repair cannot fire for a file whose frames are all complete;
• if it did fire, it would cut at the start of the last incomplete frame (near EOF), not at offset 4,129;
• no other code path truncates or re-encodes a current log, and none keeps a backup.

So the responsible path is still unidentified. Concrete asks:

1. Is there any internal maintenance/migration/repair path outside dsh-session-persistence-jsonl (e.g. in the gateway/desktop host or a start-up sweep) that can rewrite a current generation? If not, the incident points at non-core code or an external writer.
2. Recommend hardening regardless: (a) require a .bak copy before any repair/truncate, (b) refuse repair when complete committed frames fail format validation (per the documented contract), (c) emit a diagnostic/log when any truncation happens.

I can provide the surviving 4,129-byte artifact, the decoded 1,058-event log, hashes and the ISO timeline if useful.

[rusliksu]

Follow-up: checked the third-party relocation bundle — it cannot rewrite or truncate a session log

To close the loop from my previous comment, I extracted and audited the forked persistence layer that one of the affected profile's third-party bundles (@alpacachen/dsh-simple-worktree@1.1.3-desktop.20) ships: its cordis.patch.yml disables and replaces the core session-persistence-jsonl, agent-loop, workspace, and session-controller with copies built against dsh 0.2.1-rc.2 (per its native/source.json).

1. It never mounted on 0.2.1-rc.5. The profile's plugin-manager log records Plugin ... is incompatible with dsh 0.2.1-rc.5 ... profile startup denies it; the host crash log records skipping profile bundle "@alpacachen/dsh-simple-worktree"; the only compatibility exemption on that machine names rc.3, not rc.5; the bundle was removed from the profile's bundles list on 2026-11-03. No cwd-placement.json, cwd-placement.required.json, cwd-relocation.pending.json, or cwd-relocations/ artifacts exist anywhere under the sessions root, i.e. relocation never executed.

2. Relocation is metadata-only. It writes exactly those four JSON artifacts and nothing else: the commit path re-checks the log file revision and publishes cwd-placement.json; recoverPlacement replays only placement/operation JSON. The log file is never opened for writing by relocation. Appends still resolve the physical log by session id, and the logical cwd is just an overlay: the bytes stay in the origin project directory.

3. It refuses damaged logs on purpose. Relocation requires a current generation with tornTruncateTo === undefined and recoveredTail.length === 0, otherwise it fails with session/relocate-recovery-required. A corrupt log fails earlier, when the stored log is decoded. So relocation cannot even start on the kind of log from this incident.

4. Truncation in that fork is unchanged from core: only the torn-tail repair (truncate(path, offset) when the reader reports an incomplete final frame) and the append rollback (truncate to the previous size). Neither makes a backup. The only backup in the whole bundle covers its own profile patch file (cordis.relocation-cold.original.yml), not session logs.

Other writers in the affected profile (audited, host side):

• core append paths: agent-loop (synthetic closers on resume) and message-feedback (opens a write handle even for a cold session and appends feedback events);
• @yuxianglin/dsh-bridge-browser: an explicit purge command acquires write ownership, archives the session, then deletes every file in the session directory except session.lock — deletion, not truncation, and running sessions are refused;
• @michengai/dsh-archive-manager: explicit deletion of archived sessions removes the session directory recursively;
• dsh-better-sidebar and dsh-model-failover: ordinary session.append(...) events on live sessions;
• the rest of the profile (context panel, token-optimizer spills, computer-use notes, ssh/mobile bridges, model routing, UI bundles) do not write session logs.

Conclusion for the incident. No shipped path and no previously installed profile code replaces a complete log with a prefix of itself. The only code that emits exactly "header frame + one event batch" (the two-frame shape of the 4,129-byte survivor) is materialize, and it refuses to run when a log already exists — its Windows publish also uses MoveFileExW(..., MOVEFILE_WRITE_THROUGH) without MOVEFILE_REPLACE_EXISTING. Deleting writers remove the file entirely and only on explicit commands. So the observed truncation is still unexplained by any code in the affected installation, and my earlier recommendation stands: (a) require a backup copy before any repair/truncate, (b) refuse repair when complete committed frames fail format validation, (c) emit a diagnostic event/log whenever a log is truncated.

Happy to share the formatted sources and exact function-level references if useful.

[rusliksu]

Patch: torn-tail repair safety (backup + refuse an invalid committed prefix)

I prepared a minimal core patch for the recovery side of this report: https://gist.github.com/rusliksu/8bebaeb0023ec1529bf3d8d1cce667b1

It is based on master 8bd07339 (0.2.2-alpha.3) and applies cleanly to tag dsh-v0.2.1-rc.5 as well; I compiled and tested it on both.

What it changes (@deepseek-ai/dsh-session-persistence-jsonl, 5 files, +267/−13):

• Backup before truncation. truncateTornTail first copies the pre-repair artifact beside the log as <log>.torn-<stamp>.bak and fsyncs the copy (and the POSIX directory entry), then truncates. A crash mid-repair can no longer leave the discarded bytes reachable only through the damaged artifact. Discovery ignores entries that are not generation filenames, so the copy is inert.
• Refuse repair when the committed prefix does not validate. Before writing anything, the artifact is re-read and the truncation point is recomputed from the bytes on disk: the committed prefix must decode and fold as the current format (readZstdPrefix/scanLog plus validateStoredEvents), the recomputed torn boundary must equal the reported offset, and the artifact must still identify this session. Any mismatch now throws SessionPersistenceCorruptionError and leaves the log byte-identical instead of truncating through committed events.
• The requested offset is range-checked against the artifact size.

This does not fix the writer bug reported in this thread (system/message without a protected surface head); it only makes the recovery path incapable of destroying evidence or committed bytes while that bug is fixed separately.

Verification:

• vitest for the package (21 spec files): 761 passed, 10 skipped.
• tsc -b and tsc -b --force exit 0 on master and on dsh-v0.2.1-rc.5 with the patch applied.
• Pre-commit hooks (lint, whitespace, vendor manifest) pass.
• New tests cover plaintext and Zstandard repair backups, a stale truncation offset, a damaged complete frame, an artifact that belongs to another session, and out-of-range offsets.

The gist contains the git am-able patch and a short README with the rationale, apply instructions, and the verification commands.

Branch: the commit is also available on a fork branch if the team wants to pull or cherry-pick it — https://github.com/rusliksu/deepseek-harness/tree/fix/torn-tail-repair-safety (compare view: master...rusliksu:fix/torn-tail-repair-safety). I did not open a pull request because CONTRIBUTING.md states that external pull requests are not accepted at the moment.

[rusliksu]

Request: would a maintainer consider taking this patch?

The commit 2e8b4f24 is on a fork branch — https://github.com/rusliksu/deepseek-harness/tree/fix/torn-tail-repair-safety (compare view: master...rusliksu:fix/torn-tail-repair-safety) — and the same patch is in the gist: https://gist.github.com/rusliksu/8bebaeb0023ec1529bf3d8d1cce667b1.

It is based on master 8bd07339 and applies to tag dsh-v0.2.1-rc.5; the package test suite (761 passed, 10 skipped) and the repository typecheck gate (5 passed, 0 failed) pass on both. This repository does not accept external pull requests, so I could not open one — the fork branch and the gist are the delivery path available to me.

If the direction is useful, I am happy to reshape the patch to fit the team's process: split it, drop the README change, rename the backup artifact, or rebase it onto a release branch.