# Cleanup / Garbage Collection

The `agents cleanup` command group provides garbage collection for stale
platform resources: sandboxes, checkpoints, sessions, logs, and backups.
All operations respect configurable retention policies and protect active
resources from accidental deletion.

---

## Subcommands

### `agents cleanup scan`

Dry-run scan that identifies stale resources without deleting anything.
Prints a per-resource summary table and lists every item that would be
cleaned.

```
agents cleanup scan
```

### `agents cleanup purge`

Remove stale resources based on retention policies.

```
agents cleanup purge [--dry-run] [--all] [--yes|-y]
```

| Flag | Default | Description |
|------|---------|-------------|
| `--dry-run` | `false` | Report what would be removed without deleting. |
| `--all` | `false` | Purge all resource types (sandboxes, checkpoints, sessions, logs, backups). Without this flag, only sandboxes and checkpoints are purged. |
| `--yes`, `-y` | `false` | Skip the interactive confirmation prompt. |

### `agents cleanup status`

Display current retention policy settings.

```
agents cleanup status
```

---

## Resource Types

### Sandboxes

Sandbox directories live in the system temp directory with prefixes
`ca-sandbox-` and `ca-cow-sandbox-`.  A sandbox is considered stale when
its modification time exceeds `cleanup_sandbox_max_age_hours`.  Sandboxes
linked to a currently-running plan are skipped and logged.

### Checkpoints

LangGraph checkpoint files (`checkpoint_*.json`) reside under
`<data_dir>/checkpoints/<plan_id>/`.  When a plan accumulates more
checkpoints than `cleanup_checkpoint_max_per_plan`, the oldest files are
pruned while always keeping the first and most recent checkpoint.

### Sessions

Sessions in the SQLite database that have not been updated for longer than
`cleanup_session_inactivity_days` are eligible for removal.  Session
cleanup is only performed when `--all` is passed to `purge`.

### Logs

Log files (`*.log`) under `<log_dir>` older than
`cleanup_log_retention_days` are removed during an `--all` purge.

### Backups

Backup files under `<data_dir>/backups/` older than
`cleanup_backup_retention_days` are removed during an `--all` purge.

---

## Configuration

All retention policies are configurable via environment variables or the
Settings model.

| Setting | Env Variable | Default | Description |
|---------|-------------|---------|-------------|
| `cleanup_sandbox_max_age_hours` | `CLEVERAGENTS_CLEANUP_SANDBOX_MAX_AGE_HOURS` | `48` | Max sandbox age in hours before eligibility. |
| `cleanup_checkpoint_max_per_plan` | `CLEVERAGENTS_CHECKPOINT_MAX` | `50` | Max checkpoints retained per plan. |
| `cleanup_session_inactivity_days` | `CLEVERAGENTS_CLEANUP_SESSION_INACTIVITY_DAYS` | `30` | Days of inactivity before session is stale. |
| `cleanup_log_retention_days` | `CLEVERAGENTS_LOG_RETENTION_DAYS` | `30` | Days to retain log files. |
| `cleanup_backup_retention_days` | `CLEVERAGENTS_BACKUP_RETENTION_DAYS` | `7` | Days to retain backup snapshots. |
| `cleanup_schedule` | `CLEVERAGENTS_CLEANUP_SCHEDULE` | `manual` | `manual` (user-initiated) or `auto` (stub). |

These correspond to the specification config keys:

- `sandbox.cleanup` → `manual` (MVP)
- `sandbox.checkpoint.max-per-plan` → 50
- `core.log.retention-days` → 30
- `core.backup.retention-days` → 7

---

## Safety

- **Active plan protection**: Sandboxes linked to a running plan ID are
  never deleted.  The skipped items and reasons appear in the report.
- **Confirmation prompt**: `purge` requires interactive confirmation
  unless `--yes` is passed.
- **Dry-run**: Both `scan` and `purge --dry-run` preview cleanup without
  side effects.
- **Checkpoint preservation**: The first and most recent checkpoint for
  each plan are always retained, even when pruning excess files.

---

## Examples

Scan for stale resources:

```
$ agents cleanup scan
Cleanup Scan Results (dry-run)

  Mode: Dry-run
  Sandboxes        scanned=4  to remove=2  skipped=1
  Checkpoints      scanned=120  to remove=15  skipped=0
  Sessions         scanned=0  to remove=0  skipped=0
  Logs             scanned=8  to remove=3  skipped=0
  Backups          scanned=5  to remove=2  skipped=0

Stale items found:
  [sandbox] /tmp/ca-sandbox-plan123-abcd (3 days old)
  [checkpoint] .cleveragents/checkpoints/plan456/checkpoint_003.json (excess)
  ...
```

Purge only sandboxes and checkpoints (default):

```
$ agents cleanup purge --yes
Cleanup Complete

  Mode: Purge
  Sandboxes        scanned=4  removed=2  skipped=1
  Checkpoints      scanned=120  removed=15  skipped=0
  Sessions         scanned=0  removed=0  skipped=0
  Logs             scanned=0  removed=0  skipped=0
  Backups          scanned=0  removed=0  skipped=0
```

Purge all resource types with dry-run preview:

```
$ agents cleanup purge --all --dry-run
```

View current retention settings:

```
$ agents cleanup status
Cleanup Retention Policies

  Sandbox max age:        48 hours
  Checkpoint max/plan:    50
  Session inactivity:     30 days
  Log retention:          30 days
  Backup retention:       7 days
  Schedule:               manual
```