feat: add automatic disk cleanup

[Peyton-Spencer]

What changed

• add an opt-in low-disk cleanup policy with a configurable minimum free-space target
• clean stopped runner workspaces and known CI caches while preserving active runner data
• add mac-runner cleanup, --dry-run, and --workspaces-only
• expose the automatic cleanup controls in Settings
• document the cleanup behavior and safety boundary

Why

Long-running self-hosted runners accumulate workspaces and dependency/build caches until the host disk fills. MacRunner owns the runner lifecycle and is the right place to reclaim that data without racing active jobs.

Safety

• automatic cleanup is off by default
• checks are throttled to at most once per hour
• running or busy runner workspaces are skipped
• shared caches are preserved whenever any runner is active
• dry-run reports the candidate size and item count without deleting data

Validation

• swift test — 108 tests passed
• git diff --check

Summary by CodeRabbit

• New Features
  • Added disk pressure cleanup for idle runner workspaces and CI caches.
  • Added cleanup CLI commands with dry-run and workspace-only options.
  • Added settings to enable automatic cleanup and configure the minimum free-space threshold.
  • Active runner workspaces are skipped, while shared caches are preserved when appropriate.
• Documentation
  • Updated the README with cleanup behavior, commands, and configuration guidance.
• Bug Fixes
  • Added safeguards to prevent cleanup from affecting active runner data.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 054d91b9-3aa8-4046-9b37-ea598c62574b

📥 Commits

Reviewing files that changed from the base of the PR and between 2f710c3 and 6747b3c.

📒 Files selected for processing (8)

• README.md
• Sources/Models/Runner.swift
• Sources/Services/CLIHandler.swift
• Sources/Services/DiskCleanupService.swift
• Sources/Services/RunnerManager.swift
• Sources/Views/MenuBarView.swift
• Tests/MacRunnerTests/AppSettingsTests.swift
• Tests/MacRunnerTests/DiskCleanupServiceTests.swift

---

📝 Walkthrough

Walkthrough

Adds disk pressure cleanup for idle runner workspaces and shared CI caches, with manual CLI commands, automatic threshold-based execution, Settings controls, persisted configuration, documentation, and XCTest coverage.

Changes

Disk cleanup

Layer / File(s)	Summary
Cleanup settings and controls Sources/Models/Runner.swift, Sources/Views/MenuBarView.swift, Tests/MacRunnerTests/AppSettingsTests.swift	Adds persisted cleanup settings, Settings controls, defaults, clamping, and initialization tests.
Cleanup engine and filesystem behavior Sources/Services/DiskCleanupService.swift, Tests/MacRunnerTests/DiskCleanupServiceTests.swift	Implements cleanup reports, workspace and cache discovery, active-runner protection, size accounting, dry-run behavior, and filesystem tests.
Manual cleanup command Sources/Services/CLIHandler.swift	Adds the cleanup command, flags, usage text, report output, and error handling.
Automatic cleanup integration and documentation Sources/Services/RunnerManager.swift, README.md	Runs cleanup after status updates when disk space is below the configured threshold, with hourly cooldown and documented behavior.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Sequence Diagram(s)

sequenceDiagram
  participant RunnerManager
  participant DiskCleanupService
  participant FileManager
  RunnerManager->>DiskCleanupService: check available disk space
  RunnerManager->>DiskCleanupService: cleanup idle workspaces and shared caches
  DiskCleanupService->>FileManager: enumerate and remove cleanup candidates
  DiskCleanupService-->>RunnerManager: return reclaimed bytes

Loading

Suggested labels: released

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch agent/automatic-disk-cleanup

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

🎉 This PR is included in version 1.18.0 🎉

The release is available on GitHub release

Your semantic-release bot 📦🚀