Signals, process groups and orphans
Killing a command means killing its whole tree. Learn process groups and sessions, why zombies appear, and what changes when your harness is PID 1.
A signal is an asynchronous notification from the kernel. SIGTERM politely asks a process to exit and can be caught. SIGKILL cannot be caught or ignored. SIGINT is Ctrl-C. SIGCHLD tells a parent that a child changed state. SIGPIPE means the reader went away.
Process groups and sessions
Every process belongs to a process group, and every group belongs to a session. A shell puts each pipeline in its own group so Ctrl-C reaches every process in it. kill(-pgid, SIGTERM), with a negative number, signals a whole group. A child started normally stays in its parent's group. A child started with setsid() leads a brand-new session and group.
Kill the child, or kill the tree
Process tree
4100harness (your agent)running4101bash -c "npm test"running4102npm testrunning4103node jestrunning4104node watch.js &running
All four processes are running and holding the stdout pipe.
npm test starts node, which starts a watcher in the background. Signalling only the bash PID leaves the rest running and the pipe open. Start the child in its own session, then signal the negative group ID.Zombies and orphans
When a process exits, the kernel keeps a small record holding its exit status until the parent calls wait. A dead process waiting to be reaped is a zombie. If the parent dies first, the children become orphans and are re-parented to PID 1 or a designated subreaper, which is expected to reap them.
PID 1 in containers
Inside a container, your app may run as PID 1, and PID 1 is special. The kernel does not apply default signal actions to it, so SIGTERM does nothing unless the program installs a handler, and docker stop waits ten seconds and then sends SIGKILL. PID 1 must also reap orphans, or zombies pile up. Use a tiny init such as tini or docker run --init.
import { spawn } from "node:child_process";
const child = spawn("bash", ["-lc", command], {
detached: true, // setsid(): new session and process group
stdio: ["ignore", "pipe", "pipe"],
});
function killTree(signal: NodeJS.Signals) {
try { process.kill(-child.pid!, signal); } // negative PID = whole group
catch (error) { if ((error as NodeJS.ErrnoException).code !== "ESRCH") throw error; }
}
const timer = setTimeout(() => {
killTree("SIGTERM"); // ask nicely
setTimeout(() => killTree("SIGKILL"), 2000); // then insist
}, timeoutMs);
child.on("exit", () => clearTimeout(timer));A process can still escape with its own setsid. Linux cgroups catch everything: cgroup.kill ends every process in a cgroup at once.
Where you will meet it
Jest, Vitest and Playwright spawn worker processes. A timeout that kills only the runner leaves workers holding ports and files.
systemd places each service in its own cgroup and stops the cgroup, which is why stray children of a service do not survive a restart.
Kubernetes sends SIGTERM to PID 1, waits for the grace period, then sends SIGKILL. Apps that ignore SIGTERM lose in-flight work every deploy.
Check yourself
Answer out loud before you open each one.
Your timeout sends SIGTERM to the child, yet its children keep running. Why?
The signal went to one PID. Start the child in a new session and signal the negative process group ID.
What is a zombie?
A process that has exited but whose parent has not yet collected its status with wait.
What goes wrong when your app runs as PID 1 in a container?
Default signal actions do not apply, so SIGTERM is ignored without a handler, and orphaned zombies are not reaped.
Try it
Run bash -c 'sleep 300 & sleep 300' from a Node script, kill only its PID, then run ps -o pid,ppid,pgid,cmd -e | grep sleep. Repeat with detached: true and a negative-PID kill.