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.