omdsh-dev/dsh-session-health
DSH session health check plug-in: frame-level scan diagnosis of multi-frame zstd session files (torn/corruption/empty session detection), zero-dependency read-only, registered session_health tool
dsh-session-health is a read-only session health check plugin for DeepSeek Harness: it performs frame-level scan diagnostics on the multi-frame zstd session files under $DSH_HOME/sessions and outputs a health report with cleanup suggestions. DSH session files are a concatenation of multiple zstd frames (a 19MB session = 119,952 frames); reading with a single-frame decode API only reveals the header, which once caused a false 'all sessions empty' judgment. The plugin productizes frame-level diagnostics so the model can directly ask 'is my session file healthy?' instead of relying on hand-written scripts. Diagnoses: torn files (write interrupted mid-frame), corrupted frames (bad magic bytes or checksum), empty sessions (zero content frames), stray files (unexpected formats or naming). Outputs a structured health report with severity and cleanup suggestions (never auto-fixes). The session_health tool is registered for use in any conversation. Deep analysis (deep: true) imports the official zstd decoder for precise content inspection; on failure it degrades explicitly. Complements dsh-session-repair-skill (which repairs corrupted sessions): this plugin discovers via read-only diagnostics — the repair skill repairs.
Install
dsh plugin --profile web add dsh-session-healthnpm package dsh-session-health 0.6.0 (registry-verified 2026-08-23). Install from npm: dsh plugin --profile web add dsh-session-health. Install from GitHub: dsh plugin --profile web add github:omdsh-dev/dsh-session-health. Headless profile: dsh plugin --profile headless add github:omdsh-dev/dsh-session-health. npm pack tarball: dsh plugin --profile web add dsh-session-health-*.tgz. The bundled dsh.bundle.patch automatically adds the plugin to the profile's layer stack after installation.
Compatibility
DeepSeek Harness web and headless profiles. Scans $DSH_HOME/sessions. Read-only guarantee (covered by the 'file byte counts unchanged after scanning' test in the test suite — SH-06 case). Path fencing: session IDs go through a strict directory-name whitelist (prevents ../ traversal); both the absolute path and the final file pass fs.realpath real-path containment checks (prevents symlink/junction escape). Deep analysis optional: with deep: true the official decoder is dynamically imported; on parse failure it explicitly degrades to deep: 'unavailable', never silently. Zero business dependencies: the zstd frame scanner is an independent implementation (reads bytes with DataView, RFC 8878 structure).
Details
- Repo: omdsh-dev/dsh-session-health
- Category: Files & Data
- Stars: 8
- Version: npm package dsh-session-health 0.6.0 (registry-verified 2026-08-23)
- Last push: 2026-09-10
- First seen: 2026-08-08
Recent updates
The current English README (README.en.md, primary English) documents: frame-level zstd scan motivation (multi-frame session format, single-frame false negative), four diagnostic categories (torn/corrupted/empty/stray), security model (read-only, path fencing, realpath containment, no symlink follow, deep analysis explicit degradation), zero business dependency on zstd scanner, tool registration (session_health), and installation (npm + GitHub + tarball, web and headless profiles).
FAQ
- Why does DSH need a special session health check?
- DSH session files are concatenations of multiple zstd frames (a 19MB session can have 119,952 frames). Standard single-frame decoders only see the header — which once caused a false 'all sessions empty' diagnosis. Frame-level scanning is needed to catch torn writes, corrupted frames, and empty sessions correctly.
- Does the plugin modify or delete any session files?
- No — it is strictly read-only. It never modifies or deletes any file. The read-only guarantee is verified by a test case (SH-06) that confirms file byte counts are unchanged after scanning.
- How does this relate to dsh-session-repair-skill?
- dsh-session-health discovers problems via read-only diagnostics (what is wrong and where). dsh-session-repair-skill repairs corrupted sessions. Use the health plugin to identify issues first, then use the repair skill if you decide to fix them.
Alternatives
omdsh-dev/dsh-security-audit · chenw2759-wq/dsh-plugin-healthcheck · Airmetro/dsh-update-checker