Introduction

DeepSeek Harness (DSH) adopts a plugin-based architecture, allowing developers to extend functionality through plugins. However, when a plugin errors during the loading phase (such as code errors or missing dependencies) or causes the process to become completely blocked (infinite loops, synchronous blocking), the entire Harness or PawWork process may crash or hang, preventing the application from starting. crash-guard-dsh addresses this pain point by automatically isolating faulty plugins to ensure system continuity.

What It Is

crash-guard-dsh is a DeepSeek Harness plugin maintained by developer limochaishang, licensed under the MIT License. Its core function is: when a plugin causes a startup crash or hang, automatically isolate that plugin to avoid repeated crashes.

Core Capabilities

The plugin provides the following main functions:

  • Automatic crash isolation: After detecting a loading-phase crash, it automatically disables the plugin that caused the crash on the next startup.
  • Automatic hang recovery: It detects completely hung states through an independent watchdog process, then automatically kills the process, disables suspicious plugins, and restarts.
  • Three-tier self-healing architecture: It includes three fallback layers: in-process monitoring, an independent watchdog process, and manual recovery.
  • Zero configuration: It works immediately after installation without additional configuration.
  • Safety guardrails: It avoids affecting normal plugins, does not isolate itself (id: crash-guard) or core packages (@deepseek-ai/*), and prevents duplicate disabling.
  • Heartbeat monitoring: The main process writes a heartbeat every 2 seconds, the watchdog checks every 5 seconds, and a state with no heartbeat for more than 30 seconds is determined to be a complete hang.

How It Works

Three-Tier Self-Healing Architecture

The system ensures runtime stability through the following three mechanisms:

  1. In-process monitoring: The main process tracks plugins currently being loaded every 50 ms and records their states. If loading does not complete within 15 seconds or the plugin does not enter the ready state, it is determined as a crash.
  2. Independent watchdog: A detached independent process is started. It does not load any plugins and only monitors the heartbeat file. If no heartbeat update is detected within 30 seconds, it determines that the main process is completely hung and executes process termination, plugin disabling, and restart.
  3. Manual recovery: When automatic mechanisms cannot resolve the issue, users can manually edit the configuration file to remove disabled entries.

Crash Detection Flow

crash-guard is loaded first in the profile bundles on each startup.

  1. Startup: crash-guard first executes apply and begins tracking the loading process.
  2. Recording: Every 50 ms, it records the ID of the plugin currently being loaded into the state file.
  3. Determination: After startup completes, the state is marked as ready; a normal exit is marked as clean.
  4. Isolation: If the next startup detects that the state file remains at booting and did not complete the flow, the previous loading phase crashed. At this point, the plugin being loaded before the crash is written into cordis.patch.yml with disabled: true, so the plugin is skipped on the next startup.

Independent Watchdog Mechanism

The limitation of in-process monitoring is that if a plugin completely blocks the event loop, the monitoring thread may also be frozen. The independent watchdog solves this problem through a separate process:
* The main process writes to heartbeat.json every 2 seconds.
* The watchdog checks the file modification time every 5 seconds.
* If no update occurs for more than 30 seconds, the automatic recovery process is triggered.

Installation and Enablement

Prerequisites: DeepSeek Harness / PawWork is installed, and Node.js 18+ is available (the runtime bundled with DSH is sufficient).

On Windows, run the following commands:

# 克隆或下载本仓库
git clone https://github.com/limochaishang/crash-guard-dsh.git
cd crash-guard-dsh

# 运行安装脚本
.\install.ps1

The installation script automatically copies the plugin into the target profile’s node_modules/, inserts it into the first position of dsh.profile.bundles in package.json, and then restarts DSH / PawWork to apply it.

Usage

After installation, no action is required; crash-guard works automatically:

  1. Normal startup: crash-guard tracks the loading process and enters the ready state after startup completes.
  2. Plugin crash: On the next startup, the plugin that caused the crash is automatically disabled, ensuring PawWork starts normally.
  3. Plugin hang: The watchdog detects missing heartbeat, automatically kills the process, disables the plugin, and restarts.
  4. View logs: Check $DSH_HOME/crash-guard/quarantine.log to view records of disabled plugins.

Manual Recovery

If you need to re-enable an automatically disabled plugin, manually edit the user-level configuration file (such as profiles/web/cordis.patch.yml) and delete content similar to the following:

# [crash-guard] 自动禁用：插件 "xxx" (yyy) 在最近一次启动时导致崩溃。
# 如需恢复，删除下面两行即可。
- id: yyy
  disabled: true

Restart after deleting the corresponding entry.

Limitations and Notes

  • Detection scope: It only handles loading-phase crashes or complete hangs; runtime crashes or forced termination by the system are only logged and not automatically disabled (because attribution is difficult).
  • Attribution limitation: If the crash occurs before crash-guard is loaded (such as issues in the base bundle itself), attribution is not possible.
  • Heuristic determination: Attribution is heuristic and may be inaccurate in extreme cases (for example, plugin A blocks the loader, causing it to incorrectly determine that plugin B is being loaded).
  • Self-crash: A crash of crash-guard itself does not write state, and it will try again on the next startup.
  • Configuration method: The plugin does not participate in the UI and has no configuration items (although parameters can be modified through patch, it works with zero configuration by default).

Conclusion

crash-guard-dsh provides a safety guardrail for DSH plugin development and solves startup failures caused by plugin crashes through a three-tier self-healing mechanism. For developers maintaining complex DSH environments, it is a practical tool that reduces the cost of manual troubleshooting.