system-health

A read-only advisor: does this machine need a cleanup, and is Heimdall causing it? It grades disk + memory pressure, counts Heimdall's own leaked python, and SUGGESTS the fix. It never deletes or kills anything unless you explicitly ask for the scoped self-reap.

Pairs with mac-deep-clean (the executor that actually reclaims disk) — shipped with Heimdall as skills/mac-deep-clean/ and invoked as hmd:mac-deep-clean. This skill is the trigger — the thing that notices you need it — and it checks the executor is actually present before ever naming it: the plugin-shipped <plugin>/skills/mac-deep-clean/SKILL.md, or a copy you installed yourself (~/.claude/skills/mac-deep-clean/SKILL.md or the project-level equivalent — still counted, and named as plain mac-deep-clean). It falls back to plain read-only investigation commands when neither exists.

Why this exists (the lesson it encodes)

A long Heimdall session leaks background python: the presence keeper's presence-doctor spawns mock_cp.py (a mock control-plane) children that get orphaned to launchd (ppid 1) and are never reaped. One session accumulated ~692 of them, pinning all 16G of RAM and thrashing swap 17G/17G. heimdall-gc reaps orphaned keeper pidfiles, but NOT these launchd-reparented children (nothing tracks them) — so they slip the collector. Most of a real cleanup session was just purging these do-nothing python procs. This advisor is the check that catches them early.

Run it — the unified core (both axes at once)

bin/heimdall-cleanup is the ONE entrypoint that covers BOTH axes — MEMORY (RAM/swap + hmd's orphan leak) and DISK (hmd's own reclaimable garbage). It ORCHESTRATES the two reapers below; it never re-implements them. Reach for it first:

heimdall-cleanup           # report (DEFAULT, read-only): unified health + reclaimable-now MB
heimdall-cleanup --json    # {severity, memory, disk, procs, reclaim} for programmatic use
heimdall-cleanup --apply   # reap hmd's OWN garbage only (orphaned hmd python + gc disk)
heimdall-cleanup --deep    # SUGGEST-only handoff to mac-deep-clean (confirm-gated, nothing auto)

report is provably read-only (sysmon with no mutating flag + gc run --dry-run + read-only probes) — the cc-selfheal lesson: a "status" that secretly mutates causes the error it exists to prevent. It is wired into SessionStart/End via --auto (runs gc always; reaps orphaned hmd python ONLY on a genuine runaway so a live keeper is never killed). Opt out with HEIMDALL_NO_CLEANUP=1 or ~/.heimdall/no-cleanup.

The underlying reapers (the core delegates to these — use directly for a single axis)

heimdall-sysmon            # MEMORY axis: human report + a SUGGESTION block; exit 0 ok / 1 warn / 2 critical
heimdall-sysmon --quiet    # print ONLY when action is advised (ideal at session start)
heimdall-sysmon --json     # {severity, disk, memory, procs, ...} for programmatic use
heimdall-gc run            # DISK axis: reap merged worktrees / temp / logs / retired claude versions

Three graded sections:

Overall exit code = the worst section. Thresholds override via HMD_SYSMON_* env vars.

Interpret + suggest

• procs WARN/CRIT → Heimdall is leaking. Suggest the scoped self-reap (below). This is the single highest-value action — it's do-nothing python pinning RAM.
• memory WARN/CRIT → reaping does not touch wired RAM (killing procs does not free non-pageable wired memory). Split the two axes, because they behave differently:
  • swap is elastic — macOS sizes it on demand and reclaims it on its own as pressure eases, with no reboot. A high swap % is a symptom to watch, not by itself an action.
  • wired is kernel-side. A reboot drops the pages, but any holder that re-arms at boot re-wires them immediately — so a restart is a temporary reclaim, not the fix. Name the persistent holder instead: heimdall-cleanup --advise detects the cheaply-visible ones (mounted OS/simulator runtime volumes, running hypervisors) and says the holder is unidentified when it cannot see one. Never prescribe a reboot as the fix.
• disk WARN/CRIT → hand off to mac-deep-clean (hmd:mac-deep-clean; tiered, read-only investigation first, then deletes only caches / dead repos / SDK-simulator bloat) — IF it's present (the plugin-shipped copy, or one you installed). Otherwise the suggestion names manual, read-only investigation commands instead (never a skill absent from this machine).

Do NOT auto-delete or auto-reboot. Suggest; let the user confirm.

The one mutating action — scoped self-reap

heimdall-sysmon --reap-hmd-orphans

Kills only procs that are (a) orphaned to launchd (ppid 1) and (b) carry Heimdall's own signature (mock_cp.py, presence-doctor, or a heimdall-tagged python), then stops the presence spawner so they don't respawn. A foreign python (real parent, or no heimdall marker) is never matched. The detector and the reaper share ONE matcher (--filter-orphans is that matcher exposed for testing), so what it counts is exactly what it would kill.

Safety: this only reaps Heimdall's OWN garbage. For anything foreign, or a full disk sweep, defer to the user / mac-deep-clean. Wired RAM is outside Heimdall's reach entirely — say so, and say that a reboot only reclaims it until its holder re-arms.

Optional: proactive nudge at session start

Wire a non-nagging advisory (prints only on WARN/CRIT) into your session start:

# in a SessionStart hook / shell rc:
heimdall-sysmon --quiet || true

Left opt-in (not auto-wired) so it never adds startup noise or a hook dependency you didn't ask for.

Verification

• heimdall-sysmon prints disk / memory / procs sections and a severity, exits 0/1/2.
• heimdall-sysmon --json | jq . is valid JSON with the three sections.
• --filter-orphans matches mock_cp.py/presence-doctor orphans but NOT a foreign python nor a non-orphan (proven by test/heimdall-sysmon.test.sh).
• A reap suggestion appears iff procs is WARN/CRIT; a mac-deep-clean suggestion iff disk is WARN/CRIT AND the skill is actually present (plugin-shipped → hmd:mac-deep-clean, user/project-installed → mac-deep-clean) — otherwise a manual read-only fallback (proven by the mac-deep-clean-availability cases in test/heimdall-sysmon.test.sh and test/sys-cleanup.test.sh).