Preface

DSH’s extensibility depends on a combination of numerous third-party plugins. Missing a plugin package, invalid entries in cordis.patch.yml, unavailable client artifacts, or the host plugin throwing runtime errors during the startup phase can all cause dsh web to hang at startup.

dsh-startup-guard is a startup guard plugin designed for DeepSeek Harness. Before startup, it checks session logs, plugin manifests, bundle parsing, patch composition, client artifacts, and the host’s apply(), addressing fixable issues first and isolating high-risk plugins.

What is this

dsh-startup-guard is maintained by aokamoaki and is licensed under MIT.

Its one-sentence positioning is: fix session logs, pre-check plugin combinations, execute host plugin smoke tests, and isolate crash sources to prevent “plugin corruption / log corruption” from freezing DSH at startup.

This plugin is not a replacement for DSH itself but provides a pre-startup check and fallback layer within the DSH plugin ecosystem.

Core Capabilities

Below are several verified capabilities of this plugin.

Session Log Repair

It can fix seq corruption, torn tail frames, and expired cache in session.jsonl[.zstd] and backs up the originals before fixing.

Suitable scenarios are: session logs in the local ~/.dsh directory have anomalies, but you don’t want to delete the entire log immediately; instead, perform a reversible repair first.

Plugin Manifest and Source Code Snapshots

It generates snapshots for the profile’s package.json, cordis.patch.yml, pnpm manifest, and linked plugin source code, and records host/client/patch fingerprints.

The purpose of this step is to lock in the current plugin combination, providing a comparable baseline for future rollbacks or troubleshooting.

Bundle Pre-check and Rollback

It validates whether third-party bundle directories are parsable. If they are not, it rolls back to a parsable snapshot and saves the bad manifest as package.json.broken.

This is suitable for handling issues where the plugin package installation results in incomplete directories, path resolution failures, or a mismatch between package.json and the actual bundle.

Combination Pre-check and Automatic Disabling

It detects duplicate entry id, unresolvable name, and fatal YAML shapes. For rows where name is invalid, it can automatically disable them; in strict mode, it writes a block marker and causes the launcher to refuse to start.

Client Artifact Validation

It validates exports['./client'] in client artifacts against the __ModuleLoader__.load registration and executes the load within a vm sandbox while detecting duplicate client IDs.

This step targets situations where “plugins can be installed, but client artifacts are unavailable.”

Host apply() Smoke Test

It executes the apply() method of third-party plugins in a subprocess and a mock Cordis environment, identifies errors thrown at startup, and caches results by fingerprint.

This step is used to discover runtime issues where host plugins throw exceptions early in the startup phase.

Crash Isolation

It triggers a full smoke test based on crash markers or startup markers. Whether to automatically disable the failed plugin depends on whether the crash marker is present, whether the plugin explicitly declares smoke as true, or whether it is due to client artifact corruption.

This mechanism also takes effect in pure dsh web scenarios.

Installation and Activation

First, install the plugin:

dsh plugin --profile web add dsh-startup-guard

If installing from GitHub source code, you can use:

dsh plugin --profile web add github:aokamoaki/dsh-startup-guard

After installation, restart dsh web and it will take effect automatically.

Regarding the runtime environment, the package.json requires Node >=22.13 and declares the peerDependency:

"@deepseek-ai/cordis": "^4.0.1"

The configuration file is located at:

~/.dsh/dsh-startup-guard.json

The configuration is optional, and default values are used by default. The modes include report, fix, and strict, with fix being the default mode; strict writes a block marker and causes the launcher to refuse to start.

Typical Usage

First Startup

After the first startup, it performs the following actions:

  1. Scan and fix session logs;
  2. Snapshot the current plugin manifest;
  3. Execute host smoke tests and client validation;
  4. Write a runtime report.

The report file is located at:

~/.dsh/dsh-preflight-report.json

Local Dry Run

If you just want to see the check results, you can run:

node guard-sessions.mjs --dry-run

If you want to check in strict mode:

node guard-sessions.mjs --mode strict

Invoking Core Entry Point

It can also be invoked via the core API:

import { runGuard } from 'dsh-startup-guard/lib/guard-core.mjs';

const r = await runGuard(home, { dryRun: true });

runGuard is the core entry point; it takes the home directory and runtime parameters and returns the execution result of this guard run.

Runtime Data and Recovery

Runtime data is written to ~/.dsh, including:

dsh-preflight.log
dsh-preflight-state.json
dsh-preflight-report.json
dsh-crash-state.json
dsh-boot-state.json
dsh-preflight-block.json
repair-backups/
plugin-snapshots/

Among them, repair-backups/ is used to save backups of original files before repair or disabling; plugin-snapshots/ is used to save plugin manifests and source code snapshots.

If a plugin is disabled by mistake, you can delete the disabled entry in the cordis.patch.yml of the corresponding profile. The original patch has been backed up to repair-backups/.

Automatic Disabling Strategy

You need to note its disabling boundaries here:

  1. A solo smoke failure will not automatically disable;
  2. If the crash marker is present and smoke fails, the corresponding plugin can be automatically disabled;
  3. If the plugin explicitly declares smoke as true and smoke fails, it can be automatically disabled;
  4. If it is client artifact corruption, it is automatically disabled as usual.

This strategy is relatively cautious: the smoke test runs in a mock environment, and a failure could be a real error or an environment gap caused by the plugin depending on real DSH services.

Applicable Scenarios and Notes

Suitable for the following users:

  1. People who perform daily maintenance of the dsh web profile;
  2. Developers who combine multiple third-party DSH plugins;
  3. People who want to change “crash on start” to “pre-start check + rollback” for log corruption, patch failure, bundle parse failure, or client artifact issues.

You need to confirm the following before use:

  1. The license is MIT;
  2. The README states that it is unrelated to DeepSeek;
  3. The plugin runs with the permissions of the current dsh process; you should check the source code and license before installing;
  4. Do not interpret it as part of the official DSH app store or official distribution channel;
  5. The directory page URL has not been confirmed in verified materials, it is recommended to refer to the GitHub repository.

GitHub Repository:

https://github.com/aokamoaki/dsh-startup-guard

Installation Command:

dsh plugin --profile web add dsh-startup-guard