# DSH Crash Guard

English | [中文](README.md)

Startup crash guard and error-boundary plugin for DeepSeek Harness (DSH). Inspired by the resilience philosophy of Minecraft mods like Not Enough Crashes, it isolates broken frontend plugins, prevents white-screen launch crashes, and recovers the GUI cleanly with revision-bound quarantine.

---

## Key Features

- **Dual-Layer Crash Protection**
  - **Node Host Precheck**: Performs rev-cached V8 script pre-compilation and Lazy-CJS contract verification during backend bootstrap, automatically pruning syntax-broken client bundles from `ClientModuleRegistry` and recomposing clean graph manifests.
  - **Web Boot Interception**: Intervenes before the browser's strict `IZ()` audit, pruning inactive entries (`state !== 2`) via `loader.remove()` to eliminate the fatal `N entries did not activate` Electron white-screen dialog.
- **Revision-bound Quarantine**
  - Automatically isolates faulty plugins during startup by recording their exact file and bundle revisions (`rev`) in `.dsh-market/crash-guard-quarantine.json`, **completely leaving official configuration files** (`package.json`, `state.json`, and `cordis.patch.yml`) **untouched**.
  - Subsequent launches silently bypass quarantined plugins without popups; editing local source code or upgrading the plugin automatically clears the quarantine and resumes normal loading.
- **Manual Permanent Disable Entry**
  - When you choose to permanently disable a problematic plugin via the rescue panel, the plugin performs three-layer configuration persistence: updating `.dsh-market/state.json`, removing the bundle from `package.json` (`dsh.profile.bundles`), and setting `disabled: true` in `cordis.patch.yml`.
- **Titlebar Rescue Overlay**
  - Fully integrates with DSH semantic color tokens (`--dsw-alias-*`), matching light and dark themes out of the box.
  - The minimized capsule sits in the Windows 40px titlebar drag region to the left of window control buttons (`right: 150px`), leaving your toolbar and chat areas completely unobstructed. Clicking it opens diagnostic details, upstream culprits (`blockedBy`), and stack traces.

---

## Comparison with Alternative Approaches

Two main approaches address startup stability in the DSH ecosystem, differing fundamentally in architecture and intervention points:

| Dimension | External Watchdog Wrappers | DSH Crash Guard (Native Plugin) |
| --- | --- | --- |
| Execution Model | Standalone background process, rewrites `bin/dsh.cmd` launch chain | Pure plugin, zero external dependencies, no modification to native launcher scripts |
| Interception Depth | Passive recovery after the host process hangs or exits | Dual-layer proactive defense: Node host precheck + Web renderer `__ModuleLoader__` interception |
| White-Screen Prevention | Cannot prevent white-screen crashes caused by frontend boot audit failures | Prunes inactive entries before `IZ()` audit runs, ensuring GUI loads reliably |
| Quarantine & Healing | Rewrites global configuration or relies on manual flags | Revision-bound (`rev`) quarantine with automatic recovery upon code edits |
| User Interface | Terminal output or OS notification popups | Native titlebar rescue capsule with interactive diagnostics and dependency chains |

---

## Installation

### Via DSH CLI

From npm registry:
```bash
dsh plugin add dsh-crash-guard
```

From GitHub repository directly:
```bash
dsh plugin add github:zxzc114514/dsh-crash-guard
```

### Manual Profile Configuration

Declare the dependency in your profile `package.json` (typically at `~/.dsh/profiles/desktop/package.json`):

```json
{
  "dependencies": {
    "dsh-crash-guard": "^1.0.0"
  },
  "dsh": {
    "profile": {
      "bundles": [
        "dsh-crash-guard"
      ]
    }
  }
}
```

Or targeting the GitHub tag:
```json
{
  "dependencies": {
    "dsh-crash-guard": "github:zxzc114514/dsh-crash-guard#v1.0.0"
  }
}
```

---

## Runtime Environment & Compatibility

### Supported Versions
- **DSH Engine**: `>=0.2.0-rc.2 <0.3.0-0`
- **Node.js**: `>=20`
- Note: DSH introduced `ClientModuleRegistry` and renderer `IZ()` audit in 0.2.0-rc.2. This plugin relies on these architectural foundations and intentionally does not target 0.1.x versions.

### Internal Hooks & Mechanisms
- **Node Host**: Hooks `ctx.clientModules.table`, pre-validates scripts using `vm.Script` and Lazy-CJS contracts, and dynamically rebuilds the bundle graph via `compose()`.
- **Web Renderer**: Injects early during `<head>` bootstrap to wrap `__ModuleLoader__.create`, performing graph pruning (`pruneInactiveEntries`) after module execution but before official `IZ()` audit.

---

## Verification & Test Scenarios

Verified against DSH 0.2.0-rc.2 and 0.2.0-rc.3 across core crash scenarios:

1. **Client Script Syntax Error**: Injected illegal top-level return statements into a test plugin. The Node precheck intercepted the error within 11ms, isolated the entry, and recomposed clean assets, preventing broken code from reaching the browser.
2. **Missing Injected Dependency**: Configured an unfulfilled `inject` requirement on a test plugin. The renderer interceptor safely pruned the unactivated entry before the audit fired, allowing the Electron window to render cleanly while highlighting the missing dependency under `blockedBy`.

---

## License

Released under the [MIT License](LICENSE).