dsh-death-forensics

A dsh web process can vanish without a trace: an external kill, a frozen event loop, an uncaught exception. An external launcher can note the exit code and stderr, but it cannot answer the question that keeps ops people awake at 3 a.m. — what was the process actually doing in its final seconds, when was the last heartbeat, and what did the crash stack look like? dsh-death-forensics is the in-process black-box plugin that fills exactly that gap.

It does three things. First, it appends a timestamped JSON line to a bounded log on every heartbeat tick (default 15 s, configurable down to 5 s), building a liveness trail you can replay after the fact. Second, it catches uncaughtException — including unhandled rejections surfaced through Node's default throw chain — records the full stack, reprints it verbatim, and exits with code 1, so the host behaves byte-identically to the no-plugin case. Third, on the next boot it cross-references the last recorded state: SIGTERM or SIGINT is logged as a graceful shutdown, a plain exit as neutral, and a missing close frame as a non-graceful end written to the crash log. The built-in death_forensics_report tool then pulls the current boot identity, previous end kind, the death window (last heartbeat through next boot), the crash-log tail, and the external-launcher tail into a single consolidated view, turning post-mortem from guesswork into table lookup.

The safety contract is equally explicit: zero child processes are ever spawned, host services are never monkey-patched, and every write path is a synchronous file write wrapped in try/catch degrade — a recording failure silences the black box itself but never the host. It is built for ops and security teams running long-lived dsh web processes who need a verifiable, in-process audit trail; paired with an external launcher it reconstructs the complete timeline from the last heartbeat of the previous life to the first line of the next.