The respawn controller (`src/respawn-controller.ts`) manages autonomous session cycling. It detects idle sessions and restarts them through a configurable sequence of steps.
| `sending_update` | About to send `/update` command |
| `waiting_update` | Waiting for `/update` to complete (output silence) |
| `sending_clear` | About to send `/clear` command |
| `waiting_clear` | Waiting for `/clear` to complete |
| `sending_init` | About to send `/init` command |
| `waiting_init` | Waiting for `/init` to complete |
| `monitoring_init` | Watching if `/init` triggered actual work |
| `sending_kickstart` | About to send kickstart prompt |
| `waiting_kickstart` | Waiting for kickstart to complete |
| `stopped` | Controller is disabled |
## Configuration
Steps can be skipped via config:
-`sendClear: false` - Skip the clear step
-`sendInit: false` - Skip the init step
-`kickstartPrompt` - Optional prompt if `/init` doesn't trigger work
## Step Confirmation
After sending each step (update, clear, init, kickstart), the controller waits for `completionConfirmMs` (10s) of output silence before proceeding. This prevents sending commands while Claude is still processing.
## Idle Detection (Multi-Layer)
1.**Completion message**: Primary signal - detects "Worked for Xm Xs" time patterns (requires "Worked" prefix to avoid false positives)
2.**AI Idle Check** (enabled by default): Spawns a fresh Claude session in a screen to analyze terminal output and provide IDLE/WORKING verdict. Uses `claude-opus-4-5-20251101` by default, sends last 16k chars of terminal buffer. Timeout 90s, cooldown 3min after WORKING. Auto-disables after 3 consecutive errors.
3.**Output silence**: Confirms idle after `completionConfirmMs` (10s) of no new output
4.**Token stability**: Tokens haven't changed
5.**Working patterns absent**: No `Thinking`, `Writing`, spinner chars
Uses `confirming_idle` state to prevent false positives. Cancels idle confirmation if substantial output (>2 chars after ANSI stripping) arrives during the wait. Fallback: `noOutputTimeoutMs` (30s) if no output at all. AI check is triggered after the no-output fallback; if AI check is disabled/errored, falls back to direct idle confirmation.
## Auto-Accept Plan Mode
Enabled by default. After `autoAcceptDelayMs` (8s) of silence with no completion message and no `elicitation_dialog` hook signal detected, sends Enter to accept the plan. Does NOT auto-accept AskUserQuestion prompts - those are blocked via the `elicitation_dialog` notification hook which signals the respawn controller to skip auto-accept.
When auto-accept is about to trigger, the AI Plan Checker (`src/ai-plan-checker.ts`) can optionally verify the terminal is showing a plan mode approval prompt before sending Enter. This prevents false auto-accepts.
- **Model**: `claude-opus-4-5-20251101` (same as idle checker)
- **Max context**: 8k chars (less than idle checker since plan prompts are visible at bottom)
- **Timeout**: 60s
- **Verdicts**: `PLAN_MODE` (safe to auto-accept) or `NOT_PLAN_MODE` (skip auto-accept)
- **Cooldown**: 30s after NOT_PLAN_MODE verdict
- **Error handling**: 3 consecutive errors disables the checker
Uses temp file for prompt to avoid E2BIG errors with large terminal buffers.
## Test Documentation
-`test/respawn-scenarios.md` - Comprehensive test scenarios for edge cases
-`test/respawn-test-plan.md` - Test environment architecture and strategies
