dsh-death-forensics
In-process death black box for a DeepSeek Harness (dsh) host. A Cordis plugin
(bundle format) that records what happened before the host died — heartbeat
windows, crash stacks, and an end-kind self-check at the next boot.
Why
dsh web processes can die without a trace (external kills, frozen event loops,
crashes). An external launcher can record how the process died (exit code /
stderr / uptime), but only something inside the process can record what
happened before: when the last heartbeat was, what the crash stack was, and
whether the previous boot ended gracefully.
This plugin is the in-process half. Pair it with an external launcher (see
DESIGN.md) for a complete picture.
Features
| Feature | Mechanism |
|---|
| Heartbeat | append JSONL to <DSH_HOME>/death-forensics/heartbeat.log every heartbeatIntervalMs (default 15s, bounded file) |
| End-kind self-check | SIGTERM/SIGINT record graceful; exit event records neutral exit; crash/kill leaves running → next boot detects a non-graceful end and appends a record to crash.log |
| Crash stacks | uncaughtException (incl. unhandled rejections via Node's default throw chain) records the full stack, then reprints it and exits(1) — host behavior is byte-identical to the no-plugin case |
| Report tool | death_forensics_report — current boot, previous end kind, death window (last heartbeat → next boot), crash log tail, external launcher log tail (if present) |
Data files (<DSH_HOME>/death-forensics/)
state.json — current boot identity + last end kind (single source of truth)heartbeat.log — append-only JSONL, truncated at maxHeartbeatLinescrash.log — append-only JSONL records (crashes + detected non-graceful ends)
Safety contract
- Zero child processes — never spawns anything; only file writes.
- Hot paths are synchronous writes with try/catch degrade — failures disable
the black box, never the host.
- Hooks are additive listeners only, cleaned up on plugin dispose.
- No monkey-patching of host services.
Install
Add to a dsh profile (e.g. profile/profiles/web/package.json):
"dependencies": {
"dsh-death-forensics": "link:/path/to/dsh-death-forensics"
},
"dsh": {
"profile": {
"bundles": [ ..., "dsh-death-forensics" ]
}
}
Then restart dsh. The bundle patch inserts entry id death-forensics.
Alternatively, via CLI: dsh plugin --profile web add /path/to/dsh-death-forensics.
Build
Requires a dsh checkout or profile install carrying @deepseek-ai/* packages
(resolved via $DSH_CHECKOUT, or $HOME/dsh-harness, $HOME/dsh,
$HOME/.dsh/dsh-harness), plus typescript:
# install devDependency offline (from any pnpm store)
node <pnpm.mjs> install --store-dir=<pnpm-store-dir> --prefer-offline \
--config.node-linker=hoisted --config.auto-install-peers=false
# compile src/ → lib/
bash scripts/build.sh # Git Bash on Windows; node must be on PATH
node lib/selftest.js # 17 pure-logic assertions
The published lib/ is committed so the plugin works from a plain clone.
Configuration
| Key | Default | Description |
|---|
heartbeatIntervalMs | 15000 | heartbeat interval (min 5000) |
maxHeartbeatLines | 20000 | heartbeat file line cap |
reportTailLines | 40 | tails shown by the report tool |
dataDir | <DSH_HOME>/death-forensics | data directory override |
Docs
DESIGN.md — full design (Chinese): state machine, hook semantics, acceptance criteria.- Death-window interpretation:
[last heartbeat of previous boot, this boot's start].
License
MIT — see LICENSE.
