Preface¶

DSH persists conversation processes as session files under $DSH_HOME/sessions. These files are not single-frame zstd compressed blocks but concatenations of multiple zstd frames— as illustrated in the README, a 19MB session can contain 119,952 frames. If a multi-frame file is read using a single-frame decoding API, often only the header is visible, which can easily lead to misinterpreting the session as “completely empty.”

When troubleshooting such issues, typically, one must write scripts to scan frame by frame and compare structures. dsh-session-health productizes this diagnostic logic as a DSH tool: models or developers can directly ask “Is the session file healthy?” and receive a structured report with cleanup suggestions, without needing to write ad-hoc analysis scripts each time. It complements dsh-session-repair-skill (for repairing corrupted sessions): this plugin performs read-only diagnostics, while the repair skill handles the actual fixes.

What This Is¶

dsh-session-health is maintained by omdsh-dev and categorized under admin-security. The plugin performs frame-level scanning on multi-frame zstd session files in the sessions directory, detecting issues such as torn, corrupted, empty sessions, and stray files, outputting a health report and cleanup suggestions. It is entirely read-only and does not modify or delete any files.

npm package name: @deepseek-ai/dsh-session-health, version 0.0.1, MIT license. GitHub repository: https://github.com/omdsh-dev/dsh-session-health. Community directory page: https://www.skillhub.cn/plugins/omdsh-dev/dsh-session-health.

The plugin registers a session_health tool (row id tool-session-health), outputting unified JSON text.

Core Features¶

Frame-Level Scanning and Detection Items¶

The scanner is independently implemented based on the RFC 8878 structure (reading bytes via DataView), differing from the official scanZstdFrames implementation, with zero business dependencies. The detectable anomaly categories are as follows:

Report fields include: root, scanned, errors, suspicious, totals (bytes, frame count, event batch estimation), detail, deep, suggestions. suggestions provide cleanup/repair recommendations based on issue templates but do not execute automatically.

Tool Parameters¶

When deep: true, it dynamically imports the official decoder for event distribution and interruption detection; if the decoder is unavailable, the report explicitly notes deep: "unavailable", but frame-level scanning continues normally.

Security Model¶

1. Read-Only Guarantee: Never modifies or deletes files; tests cover “file byte count remains unchanged after scanning” (files.spec SH-06 case).
2. Path Fencing: Session id strictly whitelists directory names; absolute paths and final files undergo fs.realpath containment checks; enumeration uses lstat to reject symlinks.
3. Fixed Input Scope: Only the sessions directory, no network, no execution surface.

Installation and Enabling¶

The plugin has undergone full-link verification under @deepseek-ai/dsh@0.1.0-rc.8. Node requires ^22.19.0 || >=24.0.0.

Below is the installation method from GitHub (recommended in the README). Web and headless are different profiles: dsh run uses the headless profile by default; installing in the web profile will not automatically override headless.

# Interactive (web) profile
dsh plugin --profile web add github:omdsh-dev/dsh-session-health

# One-time task (headless) profile — dsh run uses headless by default
dsh plugin --profile headless add github:omdsh-dev/dsh-session-health

Alternatively, you can install using the npm pack artifact:

dsh plugin --profile web add dsh-session-health-*.tgz

The dsh.bundle.patch within the package automatically adds the plugin to the profile’s layer stack after installation. Peer dependencies (@deepseek-ai/cordis, @deepseek-ai/dsh-tools) are provided by the profile’s healed profiles/node_modules fallback installation.

Verify if the installation is effective:

dsh --profile web --dump-config | grep tool-session-health

Start DSH (lib production mode, do not install globally):

npx -p @deepseek-ai/dsh@0.1.0-rc.8 dsh web

Typical Usage¶

Scan the entire sessions directory:

session_health { action: "scan" }

Example return structure:

{"root":"C:\\Users\\admin\\.dsh\\sessions","scanned":39,"errors":{...},"suspicious":{...},"suggestions":[...]}

Perform deep analysis on a single session:

session_health { action: "file", path: "session-abc123", deep: true }

You can also let the model call it via dsh run:

dsh run "Use the session_health tool to scan the session directory health status"

Use Cases and Notes¶

Who It’s For

• When local sessions directory anomalies occur (sessions “appear empty,” write interruptions, residual tmp files), requiring quick identification of problem files.
• If you don’t want to write zstd frame scanning scripts manually each time and want the model to query health status directly in conversation.
• In conjunction with dsh-session-repair-skill: use this plugin for diagnosis first, then repair as needed.

Notes

1. The plugin runs with the current dsh process permissions; before installation, check the source code and MIT license.
2. deep mode depends on @deepseek-ai/dsh-session-persistence-jsonl; under npm 0.1.0-rc.8, this tarball does not contain src/, and the root entry does not export zstd APIs, so deep will degrade to decoder-unavailable, but frame-level scanning is unaffected.
3. Event batch estimation = frame count - 1, which is an estimate rather than an exact event count, as noted in the report.
4. Use forward slashes for Windows paths (C:/...).

Conclusion¶

dsh-session-health transforms multi-frame zstd session diagnosis from manual scripts into a reusable DSH tool: read-only, frame-level, with path fencing, outputting structured reports and suggestions. If you maintain local DSH sessions or troubleshoot persistence issues, you can install it into your profile for a baseline scan.

• Community directory: https://www.skillhub.cn/plugins/omdsh-dev/dsh-session-health
• GitHub: https://github.com/omdsh-dev/dsh-session-health