# /grid:daemon - Background Execution Mode

---
name: grid:daemon
description: Fire-and-forget long-running autonomous execution
disable-model-invocation: true
argument-hint: "[task description | status | stop | resume]"
allowed-tools:
  - Read
  - Write
  - Edit
  - Bash
  - Glob
  - Grep
  - Task
---

Launch, monitor, and control long-running Grid sessions that execute in the background.

## USAGE

```bash
/grid:daemon "task description"     # Start new daemon
/grid:daemon status                 # Check active daemon
/grid:daemon status <id>            # Check specific daemon
/grid:daemon list                   # List all daemons
/grid:daemon stop                   # Stop active daemon
/grid:daemon stop <id>              # Stop specific daemon
/grid:daemon resume "response"      # Resume from checkpoint
/grid:daemon logs                   # Tail daemon logs
/grid:daemon logs <id>              # Tail specific daemon logs
```

## WHEN TO USE

**Good for:**
- Complex multi-hour builds
- Overnight refactoring
- Large codebase migrations
- Tasks you want to run while away
- Background work while you continue coding

**Use regular `/grid` for:**
- Interactive development
- Tasks needing frequent input
- Learning/exploration
- Quick builds (< 30 min)

---

## BEHAVIOR

### Starting a Daemon

When user runs `/grid:daemon "task"`:

1. **Generate Daemon ID**
   ```
   {YYYYMMDD}-{HHMMSS}-{slug}
   Example: 20260123-143000-build-auth-api
   ```

2. **Create Daemon Directory**
   ```
   .grid/daemon/{daemon-id}/
   ├── task.txt           # Original task description
   ├── checkpoint.json    # Execution state
   ├── heartbeat.json     # Health monitoring
   ├── output.log         # Full output log
   └── audit.log          # Action audit trail
   ```

3. **Initialize Checkpoint**
   ```json
   {
     "version": "1.0",
     "daemon_id": "{id}",
     "created": "{ISO timestamp}",
     "updated": "{ISO timestamp}",
     "status": "starting",
     "task": {
       "description": "{user description}",
       "mode": "autopilot"
     },
     "progress": {
       "current_wave": 0,
       "total_waves": 0,
       "completed_blocks": [],
       "current_block": null,
       "percent": 0
     }
   }
   ```

4. **Launch Background Execution**

   **Option A: Claude Code Background Agent (v2.0.60+)**
   - Spawn Task() with daemon orchestrator
   - Use Ctrl+B equivalent to background if available
   - Monitor via scratchpad

   **Option B: External Process (Fallback)**
   ```bash
   nohup claude --print -p "..." > .grid/daemon/{id}/output.log 2>&1 &
   echo $! > .grid/daemon/{id}/pid
   ```

5. **Display Confirmation**
   ```
   DAEMON SPAWNED
   ══════════════

   ID: 20260123-143000-build-auth-api
   Task: Build REST API with user authentication
   Mode: Autopilot

   Status: Initializing
   Monitor: /grid:daemon status
   Stop: /grid:daemon stop

   You can close this terminal. Work continues in background.

   End of Line.
   ```

---

### Checking Status

When user runs `/grid:daemon status`:

1. **Find Active Daemon**
   - Check `.grid/daemon/*/checkpoint.json` for `status != "complete"`
   - If multiple active, show list
   - If none active, show "No active daemons"

2. **Read Checkpoint State**
   ```json
   {
     "status": "executing",
     "progress": {
       "current_wave": 2,
       "total_waves": 4,
       "percent": 45
     }
   }
   ```

3. **Read Recent Scratchpad/Logs**
   - Last 10 entries from scratchpad
   - Last 20 lines from output.log

4. **Display Status**
   ```
   DAEMON STATUS
   ═════════════

   ID: 20260123-143000-build-auth-api
   Runtime: 1h 23m
   Status: Executing

   Progress: [█████████░░░░░░░░░░░] 45%

   Current: Wave 2 of 4
     Block 05 - User Authentication
     ├─ Thread 5.1: JWT utilities ✓
     ├─ Thread 5.2: Auth middleware ⚡ In Progress
     └─ Thread 5.3: Protected routes ○ Pending

   Recent Activity:
     14:52 - executor-05: Implementing JWT verification
     14:48 - executor-04: Completed database models
     14:45 - recognizer: Wave 1 verified ✓

   Commits: 8 made
   Est. Remaining: ~2h 15m

   End of Line.
   ```

---

### Handling Checkpoints

When daemon reaches a checkpoint:

1. **Update Checkpoint State**
   ```json
   {
     "status": "checkpoint",
     "checkpoint_stack": [{
       "type": "human-verify",
       "block": "07",
       "details": {
         "what_built": "Stripe webhook endpoint",
         "how_to_verify": ["Run stripe listen...", "Trigger event..."]
       },
       "created": "{timestamp}"
     }]
   }
   ```

2. **Attempt Notification**
   - System notification (if enabled)
   - Write to `.grid/daemon/{id}/ATTENTION_NEEDED`

3. **Pause Execution**
   - Daemon waits for user response
   - Heartbeat continues (shows "checkpoint" status)

4. **Status Shows Checkpoint**
   ```
   DAEMON CHECKPOINT
   ═════════════════

   ID: 20260123-143000-build-auth-api
   Status: AWAITING USER

   Checkpoint Type: human-verify
   Block: 07 - Payment Webhooks

   What was built:
   - Stripe webhook endpoint at /api/webhooks/stripe
   - Event handlers for payment intents
   - Signature verification

   How to verify:
   1. Run: stripe listen --forward-to localhost:3000/api/webhooks/stripe
   2. Run: stripe trigger payment_intent.succeeded
   3. Check logs for "Payment succeeded" event

   Resume:
     /grid:daemon resume "approved"
     /grid:daemon resume "Issue: [describe problem]"

   End of Line.
   ```

---

### Resuming from Checkpoint

When user runs `/grid:daemon resume "response"`:

1. **Validate Response**
   - "approved" / "done" / "yes" → Clear checkpoint, continue
   - Other text → Pass as feedback, may re-plan

2. **Update Checkpoint**
   ```json
   {
     "status": "executing",
     "checkpoint_stack": [],
     "checkpoint_history": [{
       "type": "human-verify",
       "response": "approved",
       "resolved": "{timestamp}"
     }]
   }
   ```

3. **Signal Daemon to Continue**
   - Write response to `.grid/daemon/{id}/resume.txt`
   - Daemon monitors this file and continues

4. **Display Confirmation**
   ```
   DAEMON RESUMED
   ══════════════

   Checkpoint cleared: human-verify (Block 07)
   Response: approved

   Continuing execution...

   Current: Block 08 - Order Management
   Status: Executing

   End of Line.
   ```

---

### Stopping a Daemon

When user runs `/grid:daemon stop`:

1. **Request Graceful Stop**
   - Write "STOP" to `.grid/daemon/{id}/control.txt`
   - Daemon completes current Program, then exits

2. **Wait for Completion (with timeout)**
   ```
   DAEMON STOPPING
   ═══════════════

   ID: 20260123-143000-build-auth-api
   Waiting for current work to complete...

   [████████░░░░░░░░░░░░] 40% - Finishing executor-05

   Timeout: 2 minutes (then force stop)
   ```

3. **Update Final State**
   ```json
   {
     "status": "stopped",
     "stop_reason": "user_requested",
     "stopped_at": "{timestamp}"
   }
   ```

4. **Display Completion**
   ```
   DAEMON STOPPED
   ══════════════

   ID: 20260123-143000-build-auth-api
   Final Status: Stopped at Block 05

   Work Completed:
   - Blocks 01-04 complete
   - Block 05 partial (Thread 5.2 in progress)

   Commits Made: 8
   Files Modified: 15

   Resume Later:
     /grid:daemon resume-stopped 20260123-143000-build-auth-api

   End of Line.
   ```

---

### Listing Daemons

When user runs `/grid:daemon list`:

```
DAEMON LIST
═══════════

Active:
  20260123-143000-build-auth-api    Executing    45%    1h 23m

Checkpointed:
  20260122-091500-refactor-db       human-verify          12h ago

Completed:
  20260121-160000-add-tests         Complete     100%   2d ago
  20260120-103000-fix-bugs          Complete     100%   3d ago

Stopped:
  20260119-143000-big-migration     Stopped       60%   4d ago

Commands:
  /grid:daemon status <id>     View details
  /grid:daemon resume <id>     Resume checkpointed
  /grid:daemon logs <id>       View logs
  /grid:daemon clean           Remove completed (>7 days)

End of Line.
```

---

### Viewing Logs

When user runs `/grid:daemon logs`:

```
DAEMON LOGS
═══════════

ID: 20260123-143000-build-auth-api
Showing last 50 lines (tail -f mode):

14:52:33 [executor-05] Starting JWT verification implementation
14:52:35 [executor-05] Reading existing auth utils...
14:52:38 [executor-05] Creating src/lib/jwt.ts
14:52:45 [executor-05] Writing verifyToken function
14:53:12 [executor-05] Adding refresh token rotation
14:53:45 [executor-05] Committing: feat(05): Add JWT utilities
14:53:48 [scratchpad] executor-05: Found pattern - uses jose library
14:54:02 [executor-05] Thread 5.1 complete
14:54:05 [executor-05] Starting Thread 5.2: Auth middleware
...

(Press Ctrl+C to exit log view)
```

---

## DAEMON ORCHESTRATOR

The daemon uses a specialized orchestrator that:

1. **Operates Headless**
   - No user prompts
   - Decisions logged, not asked
   - Checkpoints pause, don't prompt

2. **Writes Heartbeats**
   - Every 30 seconds to heartbeat.json
   - Enables external health monitoring

3. **Checkpoints Aggressively**
   - After every Program completion
   - After every wave
   - On any error

4. **Handles Recovery**
   - On start, checks for existing checkpoint
   - Verifies git state matches checkpoint
   - Resumes or reconciles as needed

### Orchestrator Prompt Template

```python
Task(
  prompt=f"""
First, read ~/.claude/agents/grid-daemon-orchestrator.md for your role.

DAEMON MODE EXECUTION
═════════════════════

Daemon ID: {daemon_id}
Task: {task_description}
Mode: Autopilot (zero user interaction unless checkpoint)

<checkpoint>
{checkpoint_json if resuming else "New daemon - no prior state"}
</checkpoint>

<warmth>
{warmth_from_checkpoint if resuming else "No prior warmth"}
</warmth>

RULES:
1. Write heartbeat every 30 seconds
2. Checkpoint after every Program completes
3. On checkpoint types, PAUSE and wait for resume signal
4. Never prompt user - log decisions instead
5. On error, checkpoint and STOP

Execute the task. Report progress to checkpoint.json.
""",
  subagent_type="general-purpose",
  model="opus",
  description=f"Daemon: {daemon_id}"
)
```

---

## DIRECTORY STRUCTURE

```
.grid/
├── STATE.md                    # Regular Grid state
├── daemon/
│   ├── active                  # Symlink to active daemon (if any)
│   ├── 20260123-143000-build-auth-api/
│   │   ├── task.txt            # Original task
│   │   ├── checkpoint.json     # Full execution state
│   │   ├── heartbeat.json      # Health monitoring
│   │   ├── control.txt         # Control signals (STOP, PAUSE)
│   │   ├── resume.txt          # Resume responses
│   │   ├── output.log          # Full Claude output
│   │   ├── audit.log           # Action audit trail
│   │   └── ATTENTION_NEEDED    # Flag file when checkpoint hit
│   └── 20260122-091500-refactor-db/
│       └── ...
└── ...
```

---

## CONFIGURATION

Settings in `.grid/config.json`:

```json
{
  "daemon": {
    "default_mode": "autopilot",
    "max_runtime_hours": 24,
    "checkpoint_on_wave_complete": true,
    "heartbeat_interval_seconds": 30,
    "stall_threshold_minutes": 30,

    "notifications": {
      "system": true,
      "sound": true,
      "webhook": null
    },

    "notify_on": {
      "start": false,
      "checkpoint": true,
      "complete": true,
      "error": true,
      "stall": true
    },

    "cleanup": {
      "auto_clean_completed_days": 7,
      "keep_audit_logs": true
    }
  }
}
```

---

## CONSTRAINTS

- **One active daemon per project** (multiple stopped/completed allowed)
- **Autopilot mode only** (no GUIDED/HANDS ON in daemon)
- **Checkpoints still require user** (design intentional for safety)
- **No destructive git operations** without explicit prior approval
- **Max runtime enforced** (default 24 hours, configurable)

---

## ERROR HANDLING

### Daemon Crash

If daemon process dies unexpectedly:

1. Next `/grid:daemon status` detects no heartbeat
2. Offers recovery:
   ```
   DAEMON RECOVERY NEEDED
   ══════════════════════

   ID: 20260123-143000-build-auth-api
   Last Heartbeat: 15 minutes ago
   Last Checkpoint: Block 05, Thread 5.2

   The daemon appears to have crashed.

   Options:
     /grid:daemon recover     Resume from last checkpoint
     /grid:daemon status -f   Force status check
     /grid:daemon stop -f     Mark as stopped, don't resume

   End of Line.
   ```

### API Errors

Rate limits, auth failures, etc:

1. Daemon enters exponential backoff
2. After 5 retries, checkpoints and pauses
3. Status shows error state:
   ```
   Status: ERROR - API rate limit
   Retry in: 5 minutes
   Or: /grid:daemon resume "retry now"
   ```

---

## CURRENT LIMITATIONS

**What works today (via manual setup):**
- Basic daemon pattern with nohup
- State persistence via checkpoint files
- Manual resume via /grid:daemon resume

**What needs Claude Code changes:**
- Native daemon/service mode
- Built-in notifications
- IPC for status queries
- Automatic crash recovery

**What needs external tooling:**
- Process monitoring daemon
- System notification integration
- Webhook delivery service

See `/docs/DAEMON_ARCHITECTURE.md` for full technical design and future roadmap.

---

## EXAMPLES

### Basic Usage

```bash
# Start daemon for overnight work
/grid:daemon "Refactor entire codebase to TypeScript with full type safety"

# Check progress next morning
/grid:daemon status

# Handle checkpoint
/grid:daemon resume "approved"

# View logs if something seems wrong
/grid:daemon logs
```

### Complex Project

```bash
# Large project with expected checkpoints
/grid:daemon "Build complete SaaS application with:
- User authentication (email + OAuth)
- Stripe billing integration
- Admin dashboard
- API documentation"

# Expected checkpoints:
# 1. human-verify: Auth flow working
# 2. human-action: Set up Stripe test keys
# 3. human-verify: Billing integration working
# 4. human-verify: Final review
```

---

## RULES

1. **Fire and forget** - User launches, daemon runs independently
2. **Checkpoint at boundaries** - Every wave, every completion
3. **Heartbeat always** - 30 second intervals for health monitoring
4. **Graceful degradation** - Crash → checkpoint → resume
5. **No silent failures** - Errors trigger notification + pause
6. **Audit everything** - Full trail in audit.log
7. **One active per project** - Prevents conflicts
8. **Safety first** - Checkpoints for anything destructive

End of Line.