DeepSeek Harness (DSH) uses a fully plugin-based architecture. During version upgrades, plugin compatibility, storage format changes, and session data migration are the three main risk areas. dsh-compat-guard is an npm package designed to provide a compatibility governance workflow for DSH, including pre-upgrade gates, storage format fingerprint validation, automatic backups, session migration, and Profile-level lock file management.

Core Capabilities

This plugin mainly addresses the following four scenarios:

  1. Pre-upgrade check (gate)
    Use dsh-guard preflight to perform the check. It answers three questions: plugin compatibility, destructive storage format changes, and automatic backup. If a destructive storage format change is detected, the upgrade is rejected (exit 1). This is intended to prevent data-loss incidents caused by storage format changes.

  2. Plugin × DSH compatibility matrix
    It replaces manually written articles with machine-generated compatibility data. The registry is hosted in the Blue-Whale-Harness repository and contains plugin compatibility status and storage format information.

  3. Session data migration
    It provides the migrate command. The workflow follows a safety-first principle: detection (detectLegacy) -> backup -> conversion -> verification -> checkpoint. It supports converting the SQLite format to the zstd JSONL format, and for unknown formats it only creates a backup without forcing conversion.

  4. Profile-level lock files and rollback
    It generates profiles/<name>/dsh.guard.lock.json, recording information such as plugin version, configuration Hash, and storage format version. It supports snapshot (snapshot), verify (comparison against the lock file), and rollback (one-click rollback).

Installation

Install it as a standalone CLI tool:

npm i -g dsh-compat-guard

(Optional) Install it into a DSH profile to obtain bootstrap probes:

dsh plugin --profile <name> add dsh-compat-guard

Usage

For day-to-day use, wrap the dsh command with dsh-guard so that plugin operations automatically pass through the gate before execution.

Set an alias/function:

# bash
alias dsh='dsh-guard dsh'
# pwsh
function dsh { dsh-guard dsh @args }

Common commands:

  • Status check: View the current version, dist-tags, storage fingerprint, and lock file status.
    dsh-guard status
  • Pre-upgrade check: Run preflight, create an automatic backup, and check plugin compatibility and storage format.
    dsh-guard preflight
  • Create snapshot and lock file: Record the complete state of the current Profile.
    dsh-guard snapshot
  • Verify consistency: Compare the current environment against the lock file and detect team drift.
    dsh-guard verify
  • Rollback: Restore to the previous snapshot.
    dsh-guard rollback
  • Pass-through mode: Manually call dsh-guard dsh to run preflights for a specific subcommand.
    dsh-guard dsh plugin add <plugin-name>

Notes and Boundaries

  1. The gate is non-mandatory: Because dsh plugin in the DSH launcher has no pre-hook, the gate cannot forcibly block actions. Discipline must be enforced on the user side via the alias dsh='dsh-guard dsh'. The internal command-line parsing mechanism in dsh-web-app also does not support attaching a second parser inside the plugin tree.
  2. Registry source: The compatibility matrix data is hosted in the compat/ directory of Blue-Whale-Harness and is fetched via CDN by default. Offline use may require a cache.
  3. Format fingerprints and unknown data: lib/formats.json is seed data. If the storage format of the target version is not registered, the tool only warns rather than silently passing.
  4. Migration and verification: The migrated JSONL schema must be confirmed against the target version; the integrity check performed by the verify command is based on the sha256 of the plugin’s package.json, rather than npm integrity.

Conclusion

dsh-compat-guard is a defensive toolkit for DSH upgrade risks. Through pre-upgrade gates and Profile lock files, it provides a last line of defense for data safety in agent development environments. For more details, refer to the GitHub repository or the plugin directory.