docs/cron-system.md

# OpenClaw Cron System

Cain's autonomous maintenance and health monitoring system.

## Overview

The cron system provides self-healing capabilities for Cain by automatically monitoring health status and recovering from errors.

## Job Configuration

Located in `.openclaw/cron/jobs.json`, following the OpenClaw cron schema:

```json
{
  "jobs": [
    {
      "id": "health-check",
      "schedule": "*/30 * * * *",
      "enabled": true,
      "description": "Monitor Cain's health and auto-recover from errors",
      "tool": "hf_space_status",
      "on_failure": {
        "tool": "hf_restart_space",
        "condition": "status in ['RUNTIME_ERROR', 'BUILDING'] and duration_minutes > 10"
      }
    }
  ]
}
```

## Current Jobs

### health-check
- **Schedule**: Every 30 minutes
- **Purpose**: Monitor Cain's Hugging Face Space status
- **Tool**: `hf_space_status`
- **Auto-recovery**: Restarts space if in RUNTIME_ERROR or BUILDING state for >10 minutes
- **Logs**: `.openclaw/logs/health-check.jsonl`

### session-archive
- **Schedule**: Weekly on Sunday at 2:00 AM
- **Purpose**: Automatically archive sessions older than 7 days
- **Tool**: `session_archive`
- **Parameters**: `threshold_days: 7`, `dry_run: false`
- **Logs**: `.openclaw/logs/session-archive.jsonl`

## Session Archival

Cain includes an automatic session archival system to keep the active sessions directory clean and performant.

### How It Works

1. **Automatic Archival**: Sessions older than 7 days (configurable) are automatically moved to the archived directory
2. **Scheduled Job**: Runs weekly by default (Sunday at 2:00 AM)
3. **Index Updates**: Both the main and archived session indices are updated
4. **Restore Capability**: Archived sessions can be restored if needed

### Directory Structure

```
.openclaw/agents/main/sessions/
├── sessions.json              # Main sessions index (active sessions only)
├── session_*.jsonl            # Active session files
└── archived/
    ├── archived_sessions.json # Index of archived sessions
    └── session_*.jsonl        # Archived session files
```

### Manual Archival Operations

Run the archive manager directly:

```bash
# Archive sessions (dry-run first)
python3 .openclaw/agents/main/sessions/archive_manager.py --archive --dry-run

# Actually archive sessions
python3 .openclaw/agents/main/sessions/archive_manager.py --archive

# List archived sessions
python3 .openclaw/agents/main/sessions/archive_manager.py --list

# Restore a session
python3 .openclaw/agents/main/sessions/archive_manager.py --restore SESSION_ID

# Show statistics
python3 .openclaw/agents/main/sessions/archive_manager.py --stats

# Custom threshold (e.g., 14 days)
python3 .openclaw/agents/main/sessions/archive_manager.py --archive --threshold 14
```

### Archival Log Format

```json
{"timestamp":"2026-03-14T02:00:00Z","action":"archive_sessions","threshold_days":7,"dry_run":false,"total_files":50,"archived_count":35,"skipped_count":10,"error_count":0,"status":"success"}
{"timestamp":"2026-03-14T02:00:01Z","action":"restore_session","session_id":"session_abc123","status":"success","restored_from":"/path/to/archived/session_abc123.jsonl"}
```

### Configuration

To modify the archival behavior, edit `.openclaw/cron/jobs/session-archive.json`:

```json
{
  "id": "session-archive",
  "schedule": "0 2 * * 0",  // Adjust cron schedule
  "enabled": true,
  "params": {
    "threshold_days": 7,     // Days before archival
    "dry_run": false         // Set true for testing
  }
}
```

## Log Format

Health checks are logged in JSONL format:

```json
{"timestamp":"2026-03-14T00:00:00Z","job_id":"health-check","status":"RUNNING","stage":"RUNNING","detail":"HuggingClaw is running","action":"check"}
{"timestamp":"2026-03-14T00:30:00Z","job_id":"health-check","status":"RUNTIME_ERROR","action":"recovery_triggered"}
{"timestamp":"2026-03-14T00:31:00Z","job_id":"health-check","status":"RUNNING","action":"recovery_success"}
```

## Adding New Jobs

1. Edit `.openclaw/cron/jobs.json`
2. Add a new job object to the `jobs` array
3. Set `enabled: true` to activate
4. Restart the cron daemon

## Monitoring

View recent health checks:
```bash
tail -20 .openclaw/logs/health-check.jsonl
```

Count failures in last 24 hours:
```bash
jq -r 'select(.action=="recovery_triggered")' .openclaw/logs/health-checks.jsonl | wc -l
```