dsh-death-forensics: DSH Host Process Death Black Box

Introduction¶

The DSH Web process may die silently due to an external kill, a frozen event loop, or a crash. An external launcher can record how it died (exit code, stderr, uptime), but only inside the process can record what happened before death: the last heartbeat time, the crash stack, and whether the previous startup ended normally. This plugin is the in-process half. It should be used together with an external launcher (see DESIGN.md) to get the full picture.

Plugin Overview¶

dsh-death-forensics is a Cordis plugin (Bundle format) that acts as an in-process death black box in a DeepSeek Harness (dsh) host. It records the events leading up to death: the heartbeat window, the crash stack, and the self-check on startup. It is maintained by shenhuanageshei, belongs to the admin-security category, and is licensed under MIT.

Core Capabilities¶

Heartbeat Logging¶

The plugin appends JSONL logs to <DSH_HOME>/death-forensics/heartbeat.log. The logging interval is controlled by heartbeatIntervalMs, which defaults to 15 seconds. The log file has a line limit (maxHeartbeatLines); once reached, it is truncated.

Termination Type Self-Check¶

The plugin records the termination type when the process exits:

• graceful: triggered by SIGTERM or SIGINT.
• neutral: triggered by the exit event.
• running: the process crashed or was forcibly killed.

On the next startup, the plugin detects the previous non-graceful termination and records it in crash.log.

Crash Stack Capture¶

The plugin captures uncaughtException (including unhandled rejections processed through Node’s default throw chain), records the full stack trace, reprints the stack, and calls exit(1). In terms of host behavior, this is equivalent to the case where the plugin is not installed.

Report Tool¶

Using the death_forensics_report tool, you can inspect the current startup, the previous termination type, the death window (from the last heartbeat to the next startup), the tail of the crash log, and the tail of the external launcher log (if present).

Installation and Enablement¶

Install via CLI¶

Add the plugin to the target dsh profile (for example, web):

dsh plugin --profile web add /path/to/dsh-death-forensics

After adding it, restart dsh.

Install via Configuration File¶

Add the dependency and bundle configuration to profile/profiles/web/package.json:

{
  "dependencies": {
    "dsh-death-forensics": "link:/path/to/dsh-death-forensics"
  },
  "dsh": {
    "profile": {
      "bundles": [ ..., "dsh-death-forensics" ]
    }
  }
}

Typical Usage¶

1. Add the plugin to a profile and restart dsh.
2. Use the death_forensics_report tool to inspect the logs before and after a death incident.

Applicable Scenarios and Notes¶

Applicable Scenarios¶

It is suitable for scenarios that require deep investigations of silent DSH host crashes, analysis of the death window, and verification of graceful shutdown behavior.

Notes¶

• Dependency Environment: Before installation, ensure that the dsh checkout or profile installation includes the @deepseek-ai/* packages.
• Safety Mechanisms:
  • Zero Child Processes: The plugin does not start any child processes; it only performs file writes.
  • Fallback Strategy: The hot path uses synchronous writes and wraps operations in try/catch. If a write fails, it only disables the black box without affecting the host.
  • No Monkey Patching: It does not modify the internal logic of host services.
  • Hook Cleanup: It only adds listeners and performs automatic cleanup when the plugin is destroyed.
• Data Storage: All data files are stored under the <DSH_HOME>/death-forensics/ directory.

Configuration¶

Summary¶

dsh-death-forensics provides in-process visibility for diagnosing crashes. Through heartbeat logging, crash stack capture, and termination type self-checking, it fills the gap of process-internal information that external launchers cannot access. For DSH administrators who pursue high reliability, this is a necessary troubleshooting tool. For plugin details, see the community catalog or GitHub.