procsentry

The supervisor sanity-check. It runs alongside systemd / PM2 / Docker — it doesn't replace them. It tells you the one thing they can't: when your supervisor is lying to you.

Linux · Node ≥18 · zero dependencies · AGPL-3.0.

npx procsentry            # audit this host
npx procsentry --json     # machine-readable
npx procsentry live 4051  # is pid 4051 truly alive (not a zombie)?
npx procsentry port 5432  # who holds this port, and who supervises it?

Why

Every supervisor answers one question: did I start it? None answer the three that actually bite at scale:

• Is it really alive — or a zombie pretending? A defunct (Z) process, or one hung holding its port, still reads "online." kill -0 says alive. It isn't.
• Is it the only one? Two managers (systemd and PM2/your own) told to run the same port fight forever — one wins, the other crash-loops. Neither tool sees the war, because each only watches its own half.
• Did anything leak? A supervised parent dies; its children reparent to pid 1 and keep holding ports and connections. Your supervisor forgets them; they pile up.

These cause the outage where every dashboard glows green while the thing is dead. procsentry is built to find exactly that.

What it flags

| Finding | Severity | Meaning | |---|---|---| | crash-storm | HIGH | a systemd unit with a runaway NRestarts — a crash-loop nobody stopped | | zombie-listener | HIGH | a port held by a defunct process — looks up, isn't | | zombies | MED | defunct children a parent never reaped | | orphan-listener | MED | a listener reparented to init under no supervisor — a leaked daemon | | dup-listener | MED | one port, multiple listener pids — possible duplicate supervision |

Exit code is non-zero if any HIGH — drop it in CI or a cron and get paged for the real failure mode.

How it works

Pure /proc + ss + systemctl introspection. No agent, no daemon, no config, no phone-home. Liveness is read from the kernel's process state (/proc/<pid>/stat), not kill -0 — so a zombie can't pass.

Library

import { isAlive, listeners, auditHost } from 'procsentry';
isAlive(4051);     // false if zombie/defunct, even though the pid exists
auditHost();       // → findings[]

The story behind it

A backend once crash-looped 92,288 times over six days — burning a CPU core and leaking 73 processes — while every dashboard read "healthy." The cause: two supervisors on one port, invisible to each. procsentry is the one-command check that would have caught it on day one. (It found two real crash-storms on its own author's box the first time it ran.)

— part of ANKR's honest-infrastructure work. The light can't lie.