# Working With Krilly - Gateway Restart Protocol

## The Problem
Gateway restarts kill all running tasks and reset session context. This is annoying.

## The Solution: New Workflow Rules

### 1. BATCH CONFIG CHANGES
**OLD WAY:** Change → Restart → Change → Restart → Change → Restart  
**NEW WAY:** Change A → Change B → Change C → ONE Restart

**Rule:** Collect all config changes, apply them, THEN restart once.

### 2. USE BACKGROUND MODE FOR LONG TASKS
Any task that might take >30 seconds or involve downloads:

```javascript
exec({
  command: "long-task.sh",
  background: true,  // Detaches from session
  yieldMs: 5000      // Let it run 5s before backgrounding
})
```

Then poll for completion:
```javascript
process({action: "poll", sessionId: "xxx", timeout: 60000})
```

### 3. USE SUB-AGENTS FOR COMPLEX WORK
For multi-step tasks that could be interrupted:

```javascript
sessions_spawn({
  task: "Install X, configure Y, test Z",
  mode: "run",
  runtime: "subagent",
  label: "task-description"  // Easy to check later
})
```

Sub-agents:
- Run in isolated sessions
- Survive parent session issues
- Auto-announce when done
- Can be checked with `subagents list`

### 4. PRE-CHECK BEFORE RESTART
Before ANY restart, ask:
- "Any running tasks I should wait for?"
- "Should I background this first?"
- "Can we batch more changes?"

### 5. STATE PERSISTENCE
For tasks that need to resume:
- Save progress to files (`/tmp/progress.json`)
- Check for existing state before starting
- Design idempotent operations (safe to re-run)

---

## Quick Reference: When to Use What

| Task Type | Method | Example |
|-----------|--------|---------|
| Quick config edit (<30s) | Direct edit | Change model, restart |
| Download/install (>30s) | Background exec | Install 500MB skill |
| Multi-step setup | Sub-agent | Full server setup |
| Scheduled/recurring | Cron | Daily backups |
| Needs resume capability | State files + checks | Long research task |

---

## Communication Template

**Before restart, I'll say:**
> "I'm about to restart the gateway for [reason]. Any objections or running tasks I should wait for?"

**When using background mode:**
> "This will run in background. I'll check on it in [time]."

**When spawning sub-agent:**
> "Spawning sub-agent for [task]. It'll report back when done."

---

## Emergency: Task Got Killed

If a restart happens mid-task:
1. I'll acknowledge what was lost
2. Check if partial progress exists
3. Offer to resume from last checkpoint
4. Use sub-agent/background mode for retry

---

*Last updated: 2026-03-04*