omdsh-dev/dsh-session-health
80Last commit Aug 14, 2026
dsh-session-health DSH plugin
dsh-session-health is a DSH plugin that performs frame-level scanning and diagnosis on multi-frame zstd session files under $DSH_HOME/sessions. It detects torn, corrupted, empty, and stray files, and outputs a health report with cleanup suggestions. The tool is strictly read-only and never modifies or deletes any file.
How to install the dsh-session-health DSH plugin
dsh plugin --profile web add github:omdsh-dev/dsh-session-healthCopying does not run this command. Review the repository and version before installing the dsh-session-health DSH plugin.
dsh-session-health DSH plugin data source
dsh-session-health DSH plugin snapshot date: Aug 16, 2026
discovered
What the dsh-session-health DSH plugin can do
- Scans multi-frame zstd session files at the frame level, detecting torn, corrupted, empty, and stray files.
- Generates a comprehensive health report with error counts, suspicious items, and actionable cleanup suggestions.
- Guarantees read-only operation with path containment, symlink resistance, and no network or execution surface.
- Supports optional deep analysis (deep: true) by dynamically importing the official decoder for event statistics.
- Provides three actions: scan (full directory), file (single file), and stats (summary).
Where the dsh-session-health DSH plugin fits
- Check the health of all session files in the DSH sessions directory to identify corrupt or incomplete sessions.
- Investigate a specific session file for frame-level issues like torn writes or interrupted turns.
- Detect stray temporary files (e.g., *.tmp) that can be safely cleaned up.
- Verify that session files are properly formed before using them in analysis or repair workflows.
- Generate a human-readable report of session health to share with the DSH team or community.
Who the dsh-session-health DSH plugin is for
- DSH users who want to monitor the integrity of their session files.
- Developers troubleshooting session corruption issues or debugging DSH internals.
dsh-session-health DSH plugin limitations
- Deep analysis (deep: true) depends on successful dynamic import of the official decoder; if unavailable, it degrades to frame-level scanning with a notation.
- Event batch estimation is approximate (frame count - 1) and not an exact event count, as noted in the report.
dsh-session-health DSH plugin: from the repository README
Quoted from the omdsh-dev/dsh-session-health README, the upstream source of the dsh-session-health DSH plugin. Copyright remains with the original authors.
DSH 会话健康检查插件 —— 对 `$DSH_HOME/sessions` 下的**多帧 zstd 会话文件**做帧级扫描诊断（torn / 损坏 / 空会话 / stray 文件），输出健康报告与清理建议。**只读**：绝不修改或删除任何文件。 [](LICENSE) 仓库：[https://github.com/omdsh-dev/dsh-session-health](https://github.com/omdsh-dev/dsh-session-health)（public） ## 动机 8/7 调查 issue #376 时对 39 个会话文件做了全量解码分析，过程中发现一个关键事实：**DSH 会话文件是多个 zstd frame 的串联**（一个 19MB 会话 = 119,952 个 frame），用单帧解码 API 读多帧文件只能看到 header——曾导致"会话全空"的误判。这套诊断逻辑值得产品化为工具：模型可以直接问"我的会话文件健康吗"，而不是靠人手工写脚本。 与 `dsh-session-repair-skill`（修复损坏会话）互补：本工具**只读诊断发现** → repair 技能**修复**。 ## 安全模型 - **只读保证**：绝不修改/删除任何文件（测试覆盖"扫描后文件字节数不变"，见 files.spec SH-06 用例） - **路径围栏**：session id 严格目录名白名单（防 `../` 穿越）；绝对路径与最终文件均做 `fs.realpath` 真实路径 containment（防符号链接/junction 逃逸）；枚举用 lstat 拒绝 symlink - **零业务依赖**：zstd 帧扫描器为独立实现（DataView 读字节，RFC 8878 结构，与官方 `scanZstdFrames` 差分一致） - **深度分析可选**：`deep: true` 时动态 import 官方解码器；解析失败明确降级 `deep: "unavailable"`，绝不静默 - 输入范围固定（sessions 目录），无网络、无执行面 ## 工具声明 注册 `session_health` 工具（`@deepseek-ai/dsh-session-health`，row id `tool-session-health`），统一输出 JSON 文本。 | 参数 | 类型 | 必填 | 说明 | |---|---|---|---| | `action` | string | ✅ | `scan` / `file` / `stats` | | `path` | string
Read the full READMERepository license: MIT
dsh-session-health DSH plugin questions
What does the session_health tool do?
The session_health tool scans multi-frame zstd session files in the DSH sessions directory. It detects issues like torn frames, empty sessions, stray files, and structural corruption. It outputs a JSON report with error counts and cleanup suggestions, and never modifies any files.
How do I install dsh-session-health?
You can install it from GitHub using `dsh plugin --profile web add github:omdsh-dev/dsh-session-health`. Alternatively, you can run `npm pack` to create a tarball and install it with `dsh plugin --profile web add dsh-session-health-*.tgz`. Verify installation with `dsh --profile web --dump-config | grep tool-session-health`.
Why is deep mode not available?
Deep mode (deep: true) depends on dynamically importing the official `@deepseek-ai/dsh-session-persistence-jsonl` decoder. If that package is not resolveable in the profile runtime, deep analysis degrades gracefully to frame-level scanning, and the report will note `deep: "unavailable"`. Frame-level scanning still works without the decoder.
Does dsh-session-health modify or delete any files?
No, it is strictly read-only. The README explicitly states 'never modify or delete any file', and the test suite includes a case that verifies file byte counts remain unchanged after scanning. It also has path containment to prevent accidental writes or symlink escapes.
What is the difference between dsh-session-health and dsh-session-repair-skill?
dsh-session-health is a read-only diagnostic tool that detects corruption and issues a report. dsh-session-repair-skill is a separate skill that actually repairs damaged session files. They are complementary: health identifies problems, and repair fixes them.