🌿 pulsewatch v1.0.0 · MIT

Is your automation actually still alive? Check that heartbeat markers and status files are fresh — mtime or embedded JSON timestamp — with a cron-friendly exit code.

The problem

Cron jobs die silently. A watchdog that only checks processes misses the common case: the process runs, but the job stopped producing output weeks ago. pulsewatch checks the thing that actually matters — when did this state file last get touched?

What it checks

mtime freshness — any file younger than --max-age-hours (fractions allowed).
Embedded timestamps — ISO-8601 field inside a JSON file via --json-key a.b.0.ts (dotted paths, list indices supported). Naive timestamps are read as local time.
Glob patterns — watch many files at once; an unmatched pattern is an error, not a silence.
Missing files, bad JSON, unparseable dates — reported as errors, never swallowed.

Install (pip)

pip install pulsewatch @ git+https://mandrilly.com/git/pulsewatch.git

Usage

pulsewatch /var/run/heartbeat.marker            # mtime-based, 6h default budget
pulsewatch state.json --json-key last_action --max-age-hours 24
pulsewatch /var/run/*.marker state.json --json  # many files, machine-readable

Exit codes (cron-friendly): 0 all fresh · 1 stale file found · 2 error (missing, unmatched glob, bad JSON/timestamp). Zero third-party dependencies — Python ≥ 3.9.