Maintaining macOS Health

Maintaining macOS Health

Recovery and prevention playbook for macOS disk and memory crises. Validated against a real watchdog-timeout kernel panic on Apple Silicon caused by vm_compressor segments saturated to 100 % with the disk over 90 % full. The same playbook works for routine cleanup or first-time setup on a new machine.

Table of contents

• When to use
• Skill layout
• Core mental model
• Standard workflows
  • First interactive use: optional disk responses
  • A. "Free space NOW" (incident response)
  • B. "Set up alerting" (new machine or first time)
  • C. Alerter stopped working / making noise
  • D. "Uninstall an app cleanly"
• Safety rules (non-negotiable)
• Domain quirks captured
• Outcomes scale

When to use

Trigger on any of:

• Disk free < 20 % or user complains about being out of space
• Watchdog-timeout / kernel panic / "no checkins from watchdogd"
• New JetsamEvent-*.ips with vm-compressor-space-shortage
• "Mac is slow", swap > 6 GB, sustained Critical memory pressure
• A process persistently consumes a core, or the whole machine stays CPU-saturated
• User wants to set up monitoring/alerting from scratch
• Migration to a new Mac → restore the same alerter
• General "clean my Mac" / "audit storage" / "free space" requests

Skill layout

Read the relevant reference before acting. Do NOT operate from memory of these files — the details are calibrated to a real incident and small changes break safety.

Core mental model

1. Monitor passively — Stats menubar (brew install --cask stats) — you see issues forming, not just when they explode.
2. Alert actively, diagnose quietly — disk, memory, Jetsam, and whole-system CPU saturation are critical. A single process burning CPU is a silent advisory only after a long sustained window; routine samples stay in the log.
3. Cleanup tiers — start zero-risk (caches, orphan data), only escalate to project artifacts and sudo categories if needed. Mole's mo purge and mo clean are the right primary tools.
4. Mole is the safety floor — even when running shell commands by hand, follow Mole's path-validation rules: never delete inside /System, /bin, /usr, /etc, /var/db outside specific allowlisted subpaths; bin/ only under .NET; vendor/ only under PHP; protect AI/password/VPN/keychain bundle IDs.

Standard workflows

First interactive use: optional disk responses

On the first operational, interactive use on a Mac (including an existing installation upgraded to this skill), read references/optional-disk-responses.md and offer both options separately in the user's language. Do this before routine setup; during an incident, do not delay immediate triage. A request to edit or review this skill is not consent to activate it on the development machine. Background invocations must never prompt for enrollment.

• Emergency cleanup, free space < 2%: permission for a bounded Mole cleanup of explicitly approved regenerable caches without another question at incident time. Explain the exact profile, irreversible deletion, possible cache rebuild/download cost, and exclusions before accepting consent. This is not permission for general mo clean, project purge, Trash emptying, sudo, or process termination.
• Agent cleanup plan, free space <= 5%: permission to launch the chosen agent automatically, inspect non-secret storage metadata, and open the local selection page in the default browser. Explain provider usage/cost and what metadata leaves the Mac. The agent may propose deletion but may not perform it; Submit is a selection, and applying still requires a separate confirmation.

Record each explicit answer independently; silence, a generic "set up monitoring", or approval of one option does not authorize the other. Keep declined choices across sessions and upgrades. Ask again only on user request, a new machine, or a material change to the consent scope. Existing monitoring continues without either option.

Implementation scope: the bundled controller supports a pinned Mole 1.39.0 adapter and a restricted Codex CLI session with the same cleanup-plan UI used by Workflow A. Emergency cleanup covers only old Homebrew package downloads and npm content-cache files. Automated planning runs Workflow A's fixed read-only bulk metadata scan, Mole clean/purge preview, Docker inventory and Downloads audit. The automatic executor remains narrower: it can delete only controller-verified regenerable cache files; storage-map and possible user-data findings are visible but disabled and require a later interactive Workflow A session. Read the reference, disclose these limits and verify local compatibility before recording approval with mac-health-disk configure. Installation alone never enables a mode. No consent is inferred from a feature-development request.

A. "Free space NOW" (incident response)

1. Triage — read references/triage.md, identify which signal fired and how urgent.
2. Snapshot baseline — df -h /System/Volumes/Data and write down free GB.
3. Run all scans, don't delete yet — for a large local disk inventory, use the bundled bulk scanner and full folder tree described in references/storage-report.md; build the scanner before use and report build or scan failures explicitly; do not silently substitute another scan method. Also run mo clean --dry-run, mo purge --dry-run --debug, docker system df -v, ~/Downloads audit. Capture everything; deletion comes only after user picks via the UI.
4. Resolve unknown items before building JSON — for every candidate > 500 MB whose purpose you cannot explain in one sentence (unfamiliar app, unfamiliar bundle ID, unfamiliar dotfolder, vendor-specific cache, ML model weights, VM image, etc.), research it first: check references/never-touch.md for a known entry, then delegate a quick lookup to the web-searcher subagent ("what is <path or bundle id> on macOS, is it safe to delete in 2026"). Wait for the answer, then write a concrete description (1-3 sentences in the user's language) into the item — what it is, who created it, what feature uses it, what breaks if deleted, whether it auto-recreates. Never show the report with vague placeholders like "unknown" or "ML data" — that defeats the point of the UI. If a web lookup contradicts never-touch.md, prefer the web answer (it's fresher) and propose an update to the reference file.
5. Build the data JSON — every candidate becomes a structured item (id, label, path, size_bytes, age_days, kind, command, mandatory description, optional protected + warning). Write to /tmp/cleanup-data-<ts>.json. Use schema from assets/render-cleanup-plan.py docstring. Append a read-only disk inventory at the bottom of the report: a collapsible folder-size hierarchy followed by the largest files in descending allocated size. Follow references/storage-report.md for the storage_scan input, coverage labels, and size semantics. These rows are informational and must not become deletion candidates automatically.
6. Render and open the cleanup UI:

   python3 .../assets/render-cleanup-plan.py /tmp/cleanup-data-<ts>.json

   The script starts a one-shot HTTP server on 127.0.0.1:18347, opens the page in the user's default browser, and blocks until the user clicks Submit or Cancel. On submit it writes /tmp/cleanup-selection-<ts>.json and prints that path to stdout. Tell the user out loud: "браузер открыт — поставь галочки, нажми Submit, потом пингани меня". Then stop and wait.
7. After the user pings — read the selection JSON, render the user's choices back in chat (categories, item list, total GB, any protected overrides flagged ⚠), and ask one explicit confirmation before deleting. Don't run anything until they say "go".
8. Apply via the helper script — never hand-rolled rm:

   python3 .../assets/apply-cleanup-selection.py /tmp/cleanup-selection-<ts>.json

   The script reads selected_items from the selection JSON and executes each item's command field, with built-in safeguards: protected items must appear in protected_overrides or are skipped; commands are validated against a hard-protected path list and a ..-component check before execution; every action is logged to ~/.config/mole/operations.log in Mole-compatible TSV. --dry-run previews without executing. Do not write your own rm blocks in the apply phase — that's how you delete items the user explicitly unchecked. The selection JSON is the single source of truth; if it's not in selected_items, it does not get deleted. Run df -h /System/Volumes/Data before and after for the user-visible delta.
9. Stop at goal — most users target 100 GB free. Don't go below that just for sport.

The Python script is bash-3.2-friendly, uses only stdlib, and is safe to run from inside the agent's shell. Hard-protected items (per references/never-touch.md) must always appear in the UI with "protected": true + a concrete warning string — the UI dims them and requires a per-item confirm dialog before they can be checked. Never omit a protected item that user data depends on (Telegram tdata, Bear database, password-manager containers, etc.) — visibility teaches the user the surrounding risk.