Preface

In the use of DeepSeek Harness (DSH), Profile configuration failures or Harness Loader crashes can interrupt the development workflow. Traditional troubleshooting methods often rely on a running process; once the Loader crashes, diagnosis becomes impossible. DSH Lifeboat provides an isolated solution, ensuring that configuration can be diagnosed and recovery attempted even when the main process cannot start.

What Is This

DSH Lifeboat is a DSH plugin maintained by IoveCelestina. It acts as a standalone “lifeboat” system dedicated to safe Profile startup, fault isolation, and recovery operations. Its core value lies in fully decoupling the diagnostic and recovery processes from the main Harness process, ensuring that recovery operations are performed in an isolated temporary environment and do not directly damage the original configuration files.

Core Features

DSH Lifeboat provides the following core capabilities:

  • Process-Independent Rescue Console: The Rescue server is an independent process and never runs inside a failed Harness process. This means the console remains accessible even if the Loader crashes.
  • Web UI and CLI dual mode:
    • Web UI: Listens on 127.0.0.1 and provides real-time probe progress, evidence viewing, verified recovery plan selection, report download, and one-click undo.
    • CLI mode: Used for automated diagnostics and directly outputs diagnostic reports in dsh-lifeboat/v1 JSON format.
  • Intelligent diagnostic mechanism:
    • Uses dsh --profile <name> --dump-config to generate a configuration snapshot.
    • Clones the snapshot into a temporary Home directory for probe testing, ensuring that original files remain read-only.
    • Adopts an “upper-bound-priority removal search” algorithm, combined with delta debugging and exact enumeration, to find a minimized faulty bundle removal plan.
  • Safe recovery mechanism:
    • Before applying a recovery, performs full fingerprint checks, optimistic manifest hash verification, and timestamped backups.
    • Uses a cross-process lock to prevent concurrent recovery operations.
    • Recovery operations are atomic, support undo, and record recovery receipts.
  • Status marking: After installation, it adds a health marker to the chosen profile and writes to ~/.dsh/lifeboat/last-healthy.json after the Loader stabilizes.

Installation and Activation

To install the plugin, add the official release package using DSH’s CLI command:

dsh plugin --profile web add https://github.com/IoveCelestina/dsh-lifeboat/releases/download/v0.1.1/dsh-lifeboat-0.1.1.tgz

After installation, you can enable diagnostics or the rescue service in the following ways:

  • Start the Web UI:
    node ./src/cli.js serve

The default port is 4317; use `--port 0` to obtain a random available port.
  • CLI diagnostics:
    node ./src/cli.js diagnose --profile web
    node ./src/cli.js diagnose --profile web --json
  • Boot test with runtime probes:
    node ./src/cli.js diagnose --profile web --mode boot --allow-runtime-code-execution

Use Cases and Notes

  • Runtime environment: The plugin depends on Node.js and requires version ^22.19.0 or >=24.0.0. The plugin itself has no runtime dependencies.
  • Recovery logic: Recovery plans provide technical solutions (such as removing a bundle), not moral blame. If A and B fail only when run simultaneously, Lifeboat offers “disable A” or “disable B” as equivalent options.
  • Apply restriction: The “apply recovery” feature is available only when the report contains an independently verified bundle removal plan.
  • Report storage: Diagnostic reports are stored by default in $DSH_HOME/lifeboat/reports; the system automatically retains the latest 500 reports. If external policy management is required, set --max-reports 0.
  • Distribution channel: Release packages are distributed through GitHub Releases and do not go through the npm registry.

Conclusion

By decoupling diagnostics and recovery from the main Harness process, DSH Lifeboat provides a reliable fallback. In scenarios that require stable operation of DeepSeek Harness profiles, it is a worthwhile addition to your toolchain.

Plugin catalog
GitHub repository