dsh-stall-sentinel

Anyone who has babysat long-running tasks under dsh knows the anxiety: a background bash tool, a pwsh build, or an npm install suddenly stops appending to its log and you are left polling by hand, unsure whether it is dead or merely slow. dsh-stall-sentinel fills that gap with a zero-dependency, install-and-forget watchdog. On mount it transparently wraps ctx.subprocess.spawn to capture the real pid of every long-lived child, then fires a single read-only PowerShell probe roughly every 60 seconds that samples CPU delta, log size and mtime change, a stage sentinel, and the log tail within an approximately one-second window.

The decision model is deliberately conservative: two consecutive windows must both show frozen progress (log byte count unchanged, mtime unchanged, no sentinel) combined with either near-zero CPU (deadlock or half-open network) or saturated CPU with zero forward progress (busy loop) before the single sanctioned action fires—an alert plus a forensic report. It never kills, terminates, or silently retries. Sampling failures, missing logs, or mid-range CPU values all degrade to unknown, schedule the next checkpoint, and keep false positives low during I/O waits, slow starts, or transient hiccups.

It is aimed at dsh workflow authors whose long tasks travel through ctx.subprocess: bash tools, background pwsh (including dsh-pwsh-local start/run), and the npm installs or builds they spawn are covered out of the box. You do not need to hand-write spawn wrapping, timer management, or state routing; the plugin is effective the moment it loads, and uninstalling it tears down every timer and listener cleanly while restoring the original spawn method. Events land in a size-rotated JSONL file and an atomically written status.json snapshot, so post-mortem analysis is a one-liner.