SBH — Storage Ballast Helper

Prevents disk-full disasters via ballast files, artifact scanning, and predictive pressure monitoring. Three-pronged: ballast (instant space), scanner (stale artifacts), special locations (/tmp, /dev/shm, swap).

Quick Check

sbh status                     # Pressure level + free space
sbh status --json | jq '.pressure'  # Machine-parseable
sbh check --need 5G            # "Do I have 5 GB free?"
sbh check --predict 30         # "Will I run out in 30 min?"

Exit codes: 0 = healthy, 1 = pressure, 2 = error.

---

Daemon

sbh daemon                          # Foreground (debugging)
systemctl --user start sbh          # Systemd user scope
sbh install --systemd --user --auto # Install + start (Linux)
sbh install --launchd --auto        # Install + start (macOS)
sbh install --wizard                # Guided interactive setup

Signals: SIGHUP = reload config, SIGUSR1 = force scan now, SIGTERM = graceful stop.

---

Ballast

Pre-allocated sacrificial files — released in milliseconds, no scanning needed.

sbh ballast status             # Per-volume inventory
sbh ballast provision          # Create/rebuild pool
sbh ballast release 3          # Free 3 files NOW
sbh ballast replenish          # Rebuild after pressure passes

Defaults: 10 x 1 GiB = 10 GiB. Ensure ballast dir is on same mount as pressure source.

---

Scanning & Cleanup

sbh scan /data/projects --top 20       # Rank artifacts by score
sbh clean /data/projects --dry-run     # Preview what would go
sbh clean --target-free 50G --yes      # Delete until 50 GB free

Scoring: Location (.25) + Name (.25) + Age (.20) + Size (.15) + Structure (.15) = 1.0.

---

Protection

sbh protect /path              # .sbh-protect marker (subtree)
sbh unprotect /path            # Remove marker

Config globs: scanner.protected_paths. Hard vetoes (always enforced): .git/ dirs, open files, age < 10 min, non-writable parents.

---

Emergency Recovery

Zero-write mode for near-100% full disks. No config file needed.

sbh emergency /data --yes              # Aggressive cleanup NOW
sbh emergency --target-free 10G        # Stop at 10 GB recovered

---

Observability

sbh dashboard                  # TUI: 7 screens (1-7 to jump)
sbh stats --window 24h         # Activity over last 24 hours
sbh blame --top 10             # Top 10 pressure sources
sbh explain --id <ID>          # Why was this decision made?

---

Configuration

Config: ~/.config/sbh/config.toml | Env: SBH_ prefix | Fallback: /etc/sbh/config.toml

sbh config show                # Current values
sbh config validate            # Check constraints
sbh config set KEY VALUE       # Change a value
sbh tune --apply --yes         # Auto-tune for this system

---

Anti-Patterns

Don't	Do Instead
Ballast on /tmp	paths.ballast_dir on same mount as pressure source
Daemon as root, CLI as user	--user scope — avoids state file permission mismatch
Skip pre-build check	sbh check --need 10G in CI/hook
Delete .sbh-protect by hand	sbh unprotect /path
Wait for Red to act	Act at Yellow — agent swarms escalate fast
min_file_age_minutes = 0	Keep >= 5 to protect in-flight writes

---

Reference Index

Topic	File
All commands, flags, env vars	COMMANDS.md
Full config key reference	CONFIG.md
Error codes, symptom-fix tables	TROUBLESHOOTING.md
Architecture, safety layers, internals	ARCHITECTURE.md