[Bug report / incident] dsh web fails to boot on corrupt session-log first frame; zip restore loses link: junctions and "dsh plugin install" silently drops bundles (root cause + fix included)

[mengge237]

DSH Harness incident report: after an update / restore, plugins "fail to install" and dsh web won't start

Date: 2026-09-04 (UTC). Machine: Windows 10.0.26200, DSH 0.1.2-rc.1 (installed under E:/Visual Studio/nodejs/node_global), pnpm 11.23.0,
plus third-party plugins from the dsh-web family (@linxin666/dsh-web-all 0.3.13, dsh-doctor 0.3.13, dsh-session-archive 0.3.13).

Summary

Two independent bugs made the GUI unbootable after a backup -> clean -> restore cycle:

1. A session log whose FIRST zstd frame is no longer the header line makes dsh web crash at boot
   (corrupt Zstandard session log: first frame is not exactly one header line). The whole
   plugin tree fails to load.
2. Local plugins declared with link: deps (dsh-whale-widget, whalehub-market) live in node_modules as
   junctions. A plain zip backup does not preserve them, so after restoring from the zip the bundles
   are missing and dsh web cannot start. Worse: 'dsh plugin --profile web install' then prints
   pnpm "Already up to date" (exit 0) WITHOUT re-creating the missing links, and dsh's own reconcile
   step silently REMOVES those bundles from dsh.profile.bundles and rewrites package.json.

Root cause A: corrupt first zstd frame vs strict boot validation

• At boot, @deepseek-ai/dsh-workspace lists sessions via the JSONL persistence backend
  (readFirstZstdLine -> listArtifacts -> list). For every session.jsonl.zstd it decompresses the
  FIRST zstd frame and requires it to be exactly ONE header line ending in newline
  (assertZstdHeaderFrame). Any other content throws, and the throw is fatal for the whole boot
  ("dsh: plugin tree failed to load ... corrupt Zstandard session log ...").
• How it happened: a running session's log got trimmed/archived (rolling trim; dsh-session-archive
  is installed) in a way that dropped the header frame. The file that remained was fully decodable,
  but its first frame was a mid-log tool/result event. Every "restore" that copied the sessions
  folder back re-introduced this file and crashed boot again -> restore/crash loop.

Root cause B: zip backup loses junctions; pnpm "up to date"; reconcile silently downgrades

• Profiles/web/package.json had link:E:/S_Software/... deps. pnpm installs link: deps as junctions
  inside node_modules. The backup zip contains neither the junction semantics nor the content of the
  two linked local plugins.
• After restore: dsh web boot failed to resolve those two bundles.
• dsh plugin (lib/bin.js -> lib/plugin-*.js, runPlugin) spawns pnpm in the profile dir and, when pnpm
  exits 0, calls reconcilePlugins: for each dependency it resolves the package and checks whether it
  declares dsh.bundle.patch; packages that were bundles but are no longer resolvable are removed from
  dsh.profile.bundles and the manifest is rewritten.
• In this state pnpm reported "Already up to date" without creating the missing junctions, exited 0,
  and reconcile silently dropped the two bundles from the layer stack. The GUI then started with a
  degraded (3-bundle) profile and no warning to the user.

Fixes applied (and reusable restore checklist)

1. Validate every session log with the app's own rule (first zstd frame == one header line);
   quarantine invalid files instead of deleting them (original bytes kept), and never write them
   back under ~/.dsh/sessions.
2. Full restore of ~/.dsh from the second backup zip (41,313 entries, ~4.8 GB, 0 errors),
   excluding: the currently active session, .credentials.yaml (merged instead), and
   profiles/node_modules (a junction farm pointing at the global install on this machine).
3. Restore 30 historical sessions (29 from a 15:08 export + 1 from the backup), all header-valid.
4. Recreate the two missing junctions in profiles/web/node_modules:
   • dsh-whale-widget -> E:/S_Software/deepseek-harness/plugins/DeepSeek-Balance-Whale-Widget
   • whalehub-market -> E:/S_Software/deepseek-harness/plugins/whalehub-dsh/plugin
     (Both local plugins have no third-party deps, so junctions are sufficient.)
5. Restore the 5-bundle package.json (base, web-app, dsh-whale-widget, whalehub-market, dsh-web-all),
   then re-run 'dsh plugin --profile web install' and verify reconcile keeps all 5 bundles.

Suggested upstream changes (please consider)

1. Boot resilience: when a session log fails the first-frame header check, skip + quarantine it and
   report the path instead of failing the whole plugin tree. Ship a dsh doctor command that scans
   and fixes this (quarantine + profile bundle preflight).
2. Session trim/archive must never drop the first (header) frame; self-check after any rewrite.
3. Backup/export tooling should either preserve junction/symlink semantics or emit a list of links
   that were not archived; restore flows should run a consistency check (bundles resolvable).
4. dsh plugin reconcile should not silently edit the user's bundle layer: distinguish "user removed"
   from "dependency missing / not installed"; in the latter case warn loudly with a suggested fix
   and/or keep an undo copy instead of deleting the entry.
5. Before trusting pnpm's "Already up to date", verify the actual node_modules state for link:
   dependencies; missing top-level links should be recreated or reported as an error.

Reproduction

A) Boot crash: take any session.jsonl.zstd, drop its first zstd frame, keep the rest, put it under
sessions///, run dsh web -> boot fails with the corrupt-header error.
B) Restore-loss + silent downgrade: profile with link: deps installed as junctions -> zip backup ->
wipe -> restore from zip -> dsh web fails on the missing bundles -> 'dsh plugin --profile web
install' reports up to date but reconcile removes the bundles from dsh.profile.bundles.

Supporting data (this machine)

• Backups: C:/Users/Lenovo/.dsh.zip (1st), C:/Users/Lenovo/.dsh_backup.zip (2nd)
• Session export snapshot: C:/Users/Lenovo/dsh-git-backup/
• Quarantine: C:/Users/Lenovo/dsh-git-backup/quarantine/
• Restore worker log: C:/Users/Lenovo/.dsh-restore-work/worker.log
• Relevant code in the 0.1.2-rc.1 install:
  • @deepseek-ai/dsh-session-persistence-jsonl/lib/index.js (assertZstdHeaderFrame, readFirstZstdLine, listArtifacts)
  • @deepseek-ai/dsh-workspace/lib/index.js:324 (boot scan trigger)
  • @deepseek-ai/dsh/bin.js -> lib/plugin-*.js (runPlugin / reconcilePlugins / exportsPatch / writeProfileManifest)

[mengge237]

Follow-up (same incident, second root cause found & fixed):

An update to 0.1.2-rc.1 (npm install -g @deepseek-ai/dsh@0.1.2-rc.1, 2026-09-04 13:19 UTC) removed the Session.events array member (now eventAt/snapshotEvents/ownEvents). A user agent preset that still used session.events (tool-bootstrap.mjs scanEvents) crashed on every turn start with "Cannot read properties of undefined (reading 'length')". Built-in presets are unaffected.

Fix applied preset-side with a compatibility fallback (session.snapshotEvents?.() ?? []). Full report (Chinese + English): C:/Users/Lenovo/dsh-issue-report-2026-09-04/ on the reporting machine, also pushed to the user's backup repo mengge237/dsh-backup-2026-09-04.

Suggestions: keep a deprecated session.events alias during the transition; include stack traces in turn/end error records; add an explicit Node-version check (rc.1 needs node:zlib createZstdDecompress / node:module stripTypeScriptTypes, missing on Node 22.12).

[mengge237]

Published write-up (public, sanitized):

Full incident analysis (Chinese + English) is now in a public repository with a v1.0.0 release:

• Repo: https://github.com/mengge237/dsh-incident-report-2026-09-04
• Release: https://github.com/mengge237/dsh-incident-report-2026-09-04/releases/tag/v1.0.0

It covers the boot crash on a corrupt session-log first frame, the zip-restore loss of link: junctions plus the "Already up to date" false success, and the Session.events removal regression (reading 'length' crash) — each with root causes, fixes, reproduction steps and upstream suggestions. No session data or credentials are included.

[mengge237]

Companion interim shim plugin now published (works around all three root causes until upstream fixes land):

• Repo: https://github.com/mengge237/dsh-legacy-compat
• One-line install (verified — auto-appends to the bundle stack, no npm needed):
  dsh plugin --profile web add github:mengge237/dsh-legacy-compat then fully restart dsh web; it appears under Settings → Plugins.
• What it does: quarantines corrupt session logs at boot so the GUI can start; restores the Session.events alias for legacy presets/plugins; Node preflight. Quiet by default (DSH_LEGACY_COMPAT_VERBOSE=1 for details); bin/uninstall.mjs for clean removal.