process-hygiene

Process hygiene

Agent sessions run tests from their per-session scratchpads. When a run is interrupted or times out, background children it started are re-parented to init and keep running: spin loops waiting on a file that will never appear, fixture servers, hung interpreters. They accumulate across sessions for days. This skill finds them by provenance, not by name, and stops them one target at a time.

Usage

python3 skills/process-hygiene/scripts/reap_orphans.py               # report only
python3 skills/process-hygiene/scripts/reap_orphans.py --reap        # stop candidates
python3 skills/process-hygiene/scripts/reap_orphans.py --spotlight   # Spotlight markers only

Every run appends one line per action and a summary to <workspace>/logs/process-hygiene.log and prints the summary. The exit status is 0 for every run that parsed its arguments, so a scheduled caller never retries in a loop; 2 on a usage error.

What is a candidate

ALL of:

1. owned by the user running the script;
2. PPID 1 — whatever started it is gone;
3. elapsed time over PROCESS_HYGIENE_MIN_AGE_S (default 7200);
4. its working directory (lsof -a -p PID -d cwd -Fn on macOS, /proc/PID/cwd on Linux), as a realpath, is inside a scratchpad root matching /private/tmp/claude-<uid>/*/*/scratchpad or /tmp/claude-<uid>/*/*/scratchpad. A root is used only when claude-<uid> is a real directory owned by this user, nothing between it and scratchpad is a symlink, and the resolved root sits under the resolved claude-<uid>; a symlinked scratchpad would otherwise make its target (a repo, the workspace) a root, for reaping and for --spotlight alike;
5. the Claude Code session that owns that scratchpad has ended (below);
6. no process in its process group holds a server socket — a listening TCP socket or any UDP socket (lsof -w -a -p PID -iTCP -sTCP:LISTEN -iUDP on macOS; the pid's socket inodes against /proc/PID/net/{tcp,tcp6,udp,udp6} on Linux). A dev server, database or tunnel an agent started on purpose is spared even after its session ended. If the sockets cannot be read for any member, the whole group is spared.