Storage Audit

Reclaim disk on the Mac mini

One rule: retire a path when it is a known-regenerable class and idle. The classes are the script's functions; nothing else is in scope. Success is the df delta, never the bytes selected.

Run it

cd ~/.hermes/profiles/matias
./scripts/storage-hygiene.sh --dry-run       # preview; audit records only
./scripts/storage-hygiene.sh                 # guarded cleanup
./scripts/storage-hygiene.sh --compact-only  # only shrink T3/OpenCode free pages

Target is 40 GiB free on /System/Volumes/Data. A run that starts below target switches to the short age gates itself (--aggressive: 3h instead of 24h on linked worktrees and their node_modules). Hermes cron storage-hygiene-every-3-hours (30 */3 * * *, no-agent) runs storage-hygiene-scheduled.sh, which reports failures at any free-space level and warns below 10 GiB.

Exit codes: 0 means completed above target, 3 means completed below target, 2 means failed, and 4 means another run owns the lock. A leftover run.lock file is normal. Its kernel lock releases on exit or crash; never delete the file to bypass a running owner.

Cleanup records live under ~/.hermes/state/storage-hygiene/: history.log, storage-hygiene.log, and last-run.json. Dry runs use separate audit.log, audit-history.log, and last-audit.json. Each verdict names a run directory containing candidates.json and failure evidence. Dry mode writes these audit records and lock metadata but does not retire files, change Git refs/worktree metadata, or prune/compact databases.

Read the result

The last log line is the verdict:

=== storage-hygiene done mode=cleanup freed=… free=… target=40GiB shortfall=… swap=… uptime='…' failures=N status=ok|below-target|failed evidence=… ===

Audit verdicts use background_delta instead of freed. Disk changes during a preview are other workloads, not cleanup success.

BUDGET lines rank candidates by allocated size with a reason and, for age gates, a gate_until timestamp. online is eligible now; offline requires owner closure, temporary space or admin maintenance; protected is retained. Nested paths are deduplicated within each category. Categories can overlap, so never add protected totals to selected totals. APFS shared blocks mean neither allocated bytes nor SQLite free pages promise an equal df gain. Swap is a separate reboot-dependent estimate, not an online candidate.

RETIRED and PRUNED describe completed actions; only the final df delta measures recovery; PROTECT <reason> kept something; JORGE-ACTION needs a human; FAILED counts toward failures. Read the reason literally before repeating it:

• Hard vetoes, never overridden: uncommitted-or-inspection-failed, unbacked, durable-or-unknown-convex-state, process-active and open. Failed inspection is not proof that a path is clean, idle or unused.
• Soft gates that time out: age-gate(24h) or age-gate(3h) on worktrees, active on caches. Each class has its own window (3h build caches, 24h worktrees and Xcode, 72h package caches, 14d Hugging Face). Measure against that window before calling a guard broken.

Classes

Out of scope, and never folded into a run: Application Support (Codex, T3, Cursor auth and state), Chrome profiles, ~/Documents, Screen Studio projects, credentials/, the vault, the selected Xcode and its current iOS runtime, Hermes state.db (reported by size only), Library/Caches/dotslash (App Management blocks unattended deletion).

Still below target after a run

Work the levers in this order; each is a fact the log already printed.

1. Swap and uptime. Multi-day uptime holds several GiB of swap; the release is a reboot after stopping live dev loops. Say so in the report.
2. T3 and OpenCode state files. Free database pages are an offline candidate until the one-time conversion to incremental auto-vacuum. Save ongoing work, close the owning apps, and verify no process holds either database or its WAL/SHM sidecars. Closing a window is not proof that all OpenCode instances exited. Use --dry-run --compact-only, then the authorized --compact-only run. It checks integrity before and after, converts to incremental mode and verifies the checkpoint. It does not prune history or sweep other paths. Full VACUUM requires temporary space: the script reserves twice the original file size plus 1 GiB, following SQLite's documented upper bound. If swap is large, reboot first and keep database owners closed to provide that headroom. Once converted, later runs can reclaim free pages incrementally while the app is open, subject to SQLite locking and successful checkpoint verification.
3. Pending macOS update or Preboot growth. Install and reboot. Never delete Preboot or update snapshots by hand.
4. Protected worktrees. List each protected worktree with its size, reason and ahead=/uncommitted= numbers. ahead=unknown is not zero. Preserve the work unless its recovery or discard is authorized; do not force past the guard to reach the target.
5. Do not re-open (measured and refuted, see vault context/mac-mini-storage.md): pnpm store prune, cold files, duplicate apps, source-code volume, the mounted simulator volume (a view of the 7.9 GiB asset, not extra bytes).

Report

FREE: <gib> (target 40)  FREED: <gib>  SWAP: <gib> (uptime …)
RETIRED: <counts by class>
PROTECTED: <worktree paths with the literal reason>
NEXT: <reboot | quit T3 once | Jorge decision on … | none>

For a dry audit, report measured free space, ranked estimates, the concrete path toward the target and what remains protected. Do not run cleanup when only a preview was requested. For an authorized cleanup, verify the final physical free space and record any failure or remaining maintenance step on the owning issue. Existing authorization persists; do not ask again merely because an offline step closes an app or needs a reboot.