launchd-process-health-check

---

title: Launchd Process Health Check name: launchd-process-health-check type: skill space: outcome description: Diagnose launchd service state when launchctl list shows stale exit codes but process is actually running tags: [skill, launchd, troubleshooting, diagnostics] created: 2026-05-31 updated: 2026-06-12 links:

• "[[@action/skills/SKILL-INDEX]]"
• "[[@memory/growth/harness-autonomous-behaviors]]"
• "[[@identity/brain/rules]]"---

Launchd Process Health Check

Problem

When checking launchctl list | grep <name>, the Exit code and PID columns can be misleading. A process can:

• Show "Exit -15" but actually be running (someone else restarted it)
• Show old PID but have been replaced by a new process
• Be managed by launchd but running under a different binary

Always Verify With These 3 Commands

# 1. launchd's view (may be stale)
launchctl list | grep <service-name>

# 2. Is it actually listening? (ground truth)
lsof -i :<port> 2>/dev/null

# 3. Is there a process? (ground truth)
ps aux | grep -i <process-name> | grep -v grep

Common Exit Codes Explained

Exit Code	Meaning
0	Clean exit (normal)
-15	SIGTERM received (killed)
-64	Exit with signal 64 (often network/socket issue)
87299	Large number — usually a PID shown as "last exit status", not an exit code

Important: The PID column shows the LAST process that exited, not the current one. A "running" service can show an old PID with a non-zero exit code.

Reverse Pattern: Process Died and launchd Didn't Restart

The opposite case is more dangerous and is the one that actually broke {{AGENT_NAME}} infra on 2026-06-10 (cron / n8n / quartz-fswatch all dead, never restarted, undetected for 6+ days):

Symptoms:

• launchctl list | grep <name> → row is present but PID is - and Exit is non-zero (e.g. -15 for SIGTERM, 1 for crash)
• lsof -i :<port> → empty (nothing listening)
• ps aux | grep <name> → empty (no process)
• cron-runner.log / n8n.log / quartz-fswatch.log → last entry is hours/days old, often a graceful shutdown ("Received SIGTERM. Shutting down...")