Preface¶

DeepSeek Harness (dsh) is an open-source agent runtime developed by DeepSeek, which the official repository summarizes in one sentence: Everything is a plugin. Models, tools, skills, sessions, sandboxes, storage, loops, and interfaces are all mounted as plugins. The official team also emphasizes another key point: the content seen by the model is written into an append-only session log—including system prompts, inference results, tool calls and their outputs, sub-agent scheduling, and every context injection.

This log is not plain text by default. The official persistence subsystem dsh-session-persistence-jsonl stores each session as a zstd multi-frame concatenated stream with checksums: many zstd frames are concatenated end-to-end in a single file, rather than packaged as a single-frame compressed archive. When a process is force-killed, a write is interrupted, or someone reads the multi-frame file using a single-frame decoding API, the common outcome is not an error, but only seeing the header and misjudging the session as “completely empty”.

dsh-session-health turns this issue into a model-callable tool: it scans session files under $DSH_HOME/sessions, performs frame-level diagnostics, and outputs a health report and cleanup suggestions. It operates in read-only mode, without modifying or deleting any files. The following content is organized after cross-verifying with the community directory page, GitHub repository README / package.json / source code, and the official DeepSeek Harness repository.

What is this¶

dsh-session-health is a session and message type DSH plugin maintained by the community organization omdsh-dev. Its repository is located at omdsh-dev/dsh-session-health, licensed under MIT. The package name is @deepseek-ai/dsh-session-health. After installation, it registers the tool session_health with a profile layer ID of tool-session-health. The community directory included this plugin on 2026-08-09, and the last push to the repository was on 2026-08-14; on the day this article was verified, the GitHub API showed 8 stars.

You need to distinguish two layers of sources first. DeepSeek Harness itself is developed by DeepSeek AI, with its official repository at deepseek-ai/deepseek-harness, which is still in developer preview at the time of writing, and the documentation notes that there will be breaking changes. The plugin directory referenced in this article, deepseek-harness-plugin.com, is an independent community site. Its About page clearly states that it has no affiliation, endorsement, or sponsorship relationship with DeepSeek / High-Flyer, and does not host plugin code. The omdsh-dev organization profile also states that it is an unofficial community plugin collection organization with no affiliation or authorization relationship with DeepSeek.

It solves a very specific problem: checking whether the session files on disk are complete multi-frame zstd logs, checking for torn writes, structural corruption, empty files, leftover plaintext .jsonl files, and stray temporary files. It does not perform repairs or modify session content.

Core Features¶

Frame-level Scanning Instead of Full Package Decompression¶

The repository README clearly states that DSH session files are concatenated multiple zstd frames. Official documentation and community discussions (such as Discussion #2165) also describe JSONL sessions as concatenated Zstandard frames. Therefore, dsh-session-health first performs frame boundary scanning: it uses DataView to read magic numbers, frame headers, and block headers according to RFC 8878, counts the number of complete frames, marks truncated tails, and does not decode block data. The source code comments note that this scanner has been compared frame-by-frame with the official scanZstdFrames; the official implementation throws errors for invalid structures, while this tool returns structured error codes to facilitate diagnosis.

The default scanning root directory is $DSH_HOME/sessions. If DSH_HOME is not set, the source code falls back to ~/.dsh. The common path for session files is:

$DSH_HOME/sessions/<cwd encoding>/<session-id>/session.jsonl.zstd

The source code files.ts also records the encoding method for Windows cwd: replace \ with -, replace drive letter C: with C-, and wrap the result in --. The enumeration only goes through two levels of directories, and recognizes session.jsonl.zstd, plaintext .jsonl, and *.tmp / *.tmp.zstd.

Detection Items¶

The issues that can be identified by frame-level scanning are consistent between the directory page and the README, and the source code report.ts categorizes them into two buckets: errors and suspicious:

The report fields include: root, scanned, errors, suspicious, totals (bytes, frame count, estimated event batches), detail, deep, suggestions. suggestions provide cleanup or repair recommendations according to the issue template, and will not be executed automatically. The estimated event batch count is equal to “number of frames - 1”, and the README clearly states that this is not an exact event count.

Read-only and Path Sandboxing¶

This is a boundary that the plugin repeatedly emphasizes, consistent across the directory page, README, and source code comments:
- Read-only: No modification or deletion of any files. The test files.spec SH-06 test case covers “file byte count unchanged after scanning”.
- Path Sandboxing: Session IDs only allow [A-Za-z0-9._-]+, rejecting ../, drive letters, whitespace, and control characters; both absolute paths and final files are checked for fs.realpath containment; enumeration uses lstat, and symbolic links are skipped directly.
- Fixed input scope: Only scans the sessions directory, no network access, no execution surface.
- Zero business dependencies: The frame scanner is implemented independently, without introducing native zstd libraries.

deep: true will dynamically import the official decoder @deepseek-ai/dsh-session-persistence-jsonl/src/zstd.ts. If parsing fails, it will explicitly downgrade, mark deep: "unavailable" in the report, and will not silently treat it as a successful scan. Deep mode also has resource limits: compressed files larger than 16MB are skipped; decompressed bytes exceeding 64MB or event count exceeding 200,000 will stop processing subsequent frames.

Registered Tool¶

The plugin exports apply(ctx), which registers session_health to ctx.tools, with a timeout of 5000ms and outputs JSON text. The parameters are as follows:

scan scans the entire sessions directory; file diagnoses a single session; stats only outputs totals. When detail is true for scan, only files with issues are included in detail, not a full list.

Installation and Enablement¶

The installation command given on the directory page is as follows, run in the DeepSeek Harness terminal:

dsh plugin add github:omdsh-dev/dsh-session-health

For reproducible installations, the directory page requires pinning the commit hash. At the time of writing this article, the latest commit on main is 72065059cec89c5577b19ee8aaa26ebc2c34fbbf (2026-08-14):

dsh plugin add github:omdsh-dev/dsh-session-health#72065059cec89c5577b19ee8aaa26ebc2c34fbbf

The repository README adds the profile configuration method. Web and headless are different profiles: installing to the web profile will not automatically overwrite the headless profile; dsh run defaults to the headless profile. Use forward slashes for Windows paths.

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

# One-shot task (headless) profile
dsh plugin --profile headless add github:omdsh-dev/dsh-session-health

After installation, you can use the following command to confirm that tool-session-health appears in the layer:

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

The README also provides a run verification command:

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

The repository states that it has migrated to the @deepseek-ai/dsh@0.1.0-rc.6 dependency line, with peer dependencies of @deepseek-ai/cordis@^4.0.1, @deepseek-ai/dsh-tools, and @deepseek-ai/dsh-invariants. The engines.node field in package.json is ^22.19.0 || >=24.0.0. DeepSeek Harness is still in developer preview, so you should align your own dsh version before installing the plugin.

Typical Usage¶

The tool is called by the model within a session. The reproducible example given in the README is as follows.

Scan the entire session directory:

session_health { action: "scan" }

The returned result will be similar to:

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

The root and scanned: 39 above come from the repository README example, and are not the actual numbers on your local machine. The local result shall be based on the $DSH_HOME/sessions directory scanned.

Only view the summary without listing abnormal files:

session_health { action: "scan", detail: false }

Diagnose a single session and enable deep analysis:

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

The path can be a session ID or an absolute path within the sessions root directory. IDs that cross boundaries, contain symbolic links, or include ../ will be rejected. stats is similar to file, but does not include detail in the report.

If you just want the agent to run a directory health check, you can directly use the dsh run example from the README. Note: this command uses the headless profile, so you need to install the plugin into the headless profile beforehand; only installing it to the web profile is not sufficient.

Applicable Scenarios and Notes¶

It is suitable for the following situations:
- The session list appears blank, cannot be opened, or you suspect that the log was interrupted by a previous force kill
- You want to confirm whether the session.jsonl.zstd on disk is still a legal multi-frame zstd file, rather than a plaintext .jsonl or 0-byte file
- You need a JSON health report before deciding whether to manually clean up stray / empty sessions
- Give the model a read-only tool to answer “is the session file healthy” instead of writing a scanning script yourself

Before using it, please note the following points, all of which can be verified on the directory page or the repository:
1. The plugin runs with the permissions of the current dsh process, and may execute code during installation. You should check the source code repository and license before installing; pin the commit hash for reproducible installations. This is the original warning from the directory page.
2. It only diagnoses and does not repair. The README points to dsh-session-repair-skill for subsequent repairs; this repository address was unavailable when this article was retrieved, so do not treat it as an already installable supporting tool. The suggestions in the report are only advisory text.
3. Deep mode may not be available under npm 0.1.0-rc.6. The README states: the npm tarball of @deepseek-ai/dsh-session-persistence-jsonl still does not include src/, and the root entry does not export the zstd API, so deep mode will downgrade to decoder-unavailable. Frame-level scanning is not affected.
4. The event batch count is an estimated value; the timeout for single-frame scanning is 5 seconds. When there are many sessions or especially large files, first use scan + detail: false to view the summary.
5. The community directory is not an official app store. Before installing any DSH plugin, refer to the GitHub source code and license.

Summary¶

DSH writes each run into an append-only multi-frame zstd session log, which means “the file exists” does not equal “the file is healthy”. dsh-session-health performs frame-level, read-only, zero-business-dependency diagnostics: it scans $DSH_HOME/sessions, marks torn, corrupted, empty sessions, and stray files, and hands the results to the model and you, instead of modifying the disk on your behalf.

Community Directory Page: https://deepseek-harness-plugin.com/zh-CN/plugins/dsh-session-health/

GitHub Repository: https://github.com/omdsh-dev/dsh-session-health