Expand description
G28: orphan-process reaper that runs at CLI startup. G28: Reaper for orphan external processes.
When the CLI crashes or is killed (SIGKILL, OOM, machine reset), child
processes spawned by claude -p or codex exec may be left running.
Without cleanup they accumulate as zombies that consume CPU, RAM, and
MCP-spawned subprocess trees (the 2026-06-03 incident: 1.877 processes
total, load average 276 on a 10-CPU host).
crate::reaper::scan_and_kill_orphans walks the process table at startup and
terminates any invocation whose PPID is 1
(reparented to init/launchd after the parent died) and that is
older than the ORPHAN_MIN_AGE_SECS constant. The scan is conservative: it only
kills processes that (a) match a known target name, AND (b) are
orphaned, AND (c) are older than the threshold. A short-lived CLI
that is just starting up is left alone.
§Portability
GAP-SG-261: the walk reads the process table through sysinfo, not through
/proc. The /proc implementation was gated on #[cfg(unix)], which is
TRUE on macOS — a platform with no /proc — so there the very first
read_dir failed and the caller was told “no orphan subprocesses detected”.
A verdict reported without a measurement is worse than an error, because it
reads like one.
Only terminate_pid still splits by platform, because asking a process to
stop is where the systems genuinely differ: SIGTERM on Unix, and
sysinfo’s own request on Windows. The split is at that one call rather
than around the whole scan.
Structs§
- Reaper
Report - Reaper report.
Functions§
- scan_
and_ kill_ orphans - Walks the process table and kills orphan LLM invocations.