Preface¶

DSH writes session logs as session.vN.jsonl[.zstd], maintaining readability between events through the nesting and order of turns and steps. Once the coordinates of an event are written incorrectly—for example, writing tool/ptc-dispatch-start without opening a turn—the entire session becomes a corrupt session in the eyes of the current reader. It will only report “Session corrupted” without telling you which specific event or step went wrong. If you want to locate the issue yourself by inspecting the file, you have to manually decompress and parse line by line.

The dsh-session-doctor introduced below is designed for this type of issue: it reads only and writes nothing, highlighting each event that violates the reader’s check rules for you. It corresponds to troubleshooting scenarios like those discussed in deepseek-harness Discussions #11971, #11981, and #11121.

What is it¶

dsh-session-doctor is a DSH plugin maintained by aturzone, categorized under admin-security. The directory page shows 0 stars, and the README itself is marked as “early plugin, using pre-release tag.”

What it does can be summarized in one sentence: decode events in session.vN.jsonl[.zstd] one by one, replay the turn/step/scope rules currently enforced by the reader, and then report specifically which sequence number, which event type, and which rule no longer holds. The entire process is read-only and will not write to the session file.

What can it find¶

The check items listed in the README fall into four categories:

1. Turn/step coordinate integrity: nesting and order of turn/start, turn/end, step/start, and step/end.
2. Step numbering restarting within the same unclosed turn.
3. Events within the turn/step scope written outside the scope: replacement records of request/header, request/context, tool/ptc-dispatch-start, tool/ptc-dispatch, assistant/message, tool/call, tool/result, etc.
4. Line-level corruption: invalid JSON, missing headers, non-event lines.

You should note its positioning: this is a “signature detector aligned with the current V4 reader,” not a complete format validator. It does not reimplement message payload validation or format migration, nor does it handle compression framing other than zstd. Therefore, its conclusion is “which rules are violated here,” not “whether the file format is correct.”

Installation¶

Install from npm (the plugin is in early stages, using the next pre-release tag):

dsh plugin --profile web add dsh-session-doctor@next

Install from a Git repository; the command triggers the package’s prepare build:

dsh plugin --profile web add git+https://github.com/aturzone/dsh-session-doctor.git

The engines in package.json restrict dsh >=0.2.2-rc.1 <0.3.0 and node >=24.9.0; the former depends on @deepseek-ai/cordis ^4.1.0, and the latter on @deepseek-ai/dsh-tools >=0.2.2-rc.1 <0.3.0. The project uses zstd decompression, so the Node version requirement is not low. The license is MIT.

Enable as a Bundle¶

After installation, the bundle only inserts one line of plugin declaration into the configuration. The plugin registers a session_doctor tool facing model invocations, scanning $DSH_HOME/sessions (you can also pass the sessionsRoot parameter), returning a report identical to the CLI, also read-only.

If you want to use overlay files for development and debugging on a local checkout, the approach given in the README is to first write the overlay:

# overlay.yml
- insert:
    - id: session-doctor-dev
      name: /absolute/path/to/dsh-session-doctor/src/index.ts

Then start with the patch:

pnpm dsh web --patch ./overlay.yml

The significance of this step is to mount the source code path directly into the running dsh, without needing to package and publish first.

Use as CLI¶

If you don’t want to use the model tool and only want to inspect once in a script, you can call the command line directly:

session-doctor [--home <DSH_HOME>] [--sessions-root <dir>] [--json] [--all-generations]

Parameter behaviors are organized in the README:

1. By default, it first looks for $DSH_HOME/sessions, and falls back to ~/.dsh/sessions if not found.
2. By default, it only checks the canonical generation with the highest version number in each session; adding --all-generations will verify the retained older versions as well, such as when session.v3.jsonl and session.v4.jsonl coexist.
3. --sessions-root can be passed the session root directory or just a specific workspace bucket, e.g., --sessions-root .../sessions/--my-project--.
4. Exit codes: 0 is clean, 1 indicates a suspicious generation found, and 2 is a usage or I/O error. --json prints a structured report, making it easy to integrate into other scripts.

These exit codes can be used directly as judgment conditions in CI.

What the output looks like¶

The sample output given in the README looks roughly like this:

session root: /home/me/.dsh/sessions
sessions: 12 scanned, 1 with reader-incompatible signatures

✗ --home-me-project--/session-8bc9…
  file: …/session.v4.jsonl.zstd
  events: 41, version: 4
  - seq 22 tool/ptc-dispatch-start: turn-scope: tool/ptc-dispatch-start outside an open turn
  - seq 23 tool/ptc-dispatch: turn-scope: tool/ptc-dispatch outside an open turn

The report pinpoints the specific file, total number of events, version number, and the problematic sequence number, allowing you to view the context directly at the corresponding location.

Applicable Scenarios and Notes¶

Suitable for these types of people: DSH users who encounter corrupt session errors and want to locate the issue themselves rather than waiting for upstream to fix it; maintainers who want to audit a batch of historical sessions to see if they conform to current V4 reader rules; projects that want to catch session disk format changes in CI.

There are three points to note before using.

1. The plugin runs with the permissions of the current dsh process. Before installing, you should review the source code yourself to ensure that patches like cordis.patch.yml do not exceed expectations. The license is MIT, but “MIT” does not equal “install blindly.”
2. It is a detector, not a repair tool. The README explicitly states that there is currently no repair or quarantine capability; after the report identifies the defect, whether to move the corrupted generation is still a manual decision.
3. The rules are aligned with the V4 reader at release time; future format versions (session-format-vN-to-vN+1) require updating this plugin accordingly. Also, by default, it only scans the highest generation; older versions will not be visible without passing --all-generations. This is by design, not a missed detection.

The community directory (skillhub.cn) is an independent site with no official affiliation with DeepSeek or Hanxin; do not treat the plugin list as an official app store reference.

Conclusion¶

The value of dsh-session-doctor lies in breaking down an error like “Session corrupted,” which cannot be investigated further, into “which line, which event, which rule violation.” It is read-only, does not modify files, and does not promise a fix; the trade-off is maintaining the rules alongside the dsh reader version. When troubleshooting a corrupt session, running this plugin first is easier than manually decompressing zstd and parsing line by line.

• Directory page: https://www.skillhub.cn/plugins/aturzone/dsh-session-doctor
• GitHub: https://github.com/aturzone/dsh-session-doctor