docs: extract respawn and spawn protocol details into dedicated docs

Condense CLAUDE.md by moving detailed state machine diagrams and spawn protocol specs into docs/respawn-state-machine.md and docs/spawn-protocol.md. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-10-02 13:39:41 +02:00 · 2026-01-24 19:47:07 +01:00
parent 2bfebc5dba
commit 1cb5e62cc2
3 changed files with 145 additions and 69 deletions
@@ -0,0 +1,57 @@
+# Respawn Controller State Machine
+
+The respawn controller (`src/respawn-controller.ts`) manages autonomous session cycling. It detects idle sessions and restarts them through a configurable sequence of steps.
+
+## State Diagram
+
+```
+WATCHING → CONFIRMING_IDLE → SENDING_UPDATE → WAITING_UPDATE → SENDING_CLEAR → WAITING_CLEAR
+    ↑         │ (new output)                                                         │
+    │         ↓                                                                      ▼
+    │       (reset)                         SENDING_INIT → WAITING_INIT → MONITORING_INIT
+    │                                                                              │
+    │                                                         (if no work triggered) ▼
+    └────────────────────────────────────── SENDING_KICKSTART ← WAITING_KICKSTART ◄┘
+```
+
+## States
+
+| State | Description |
+|-------|-------------|
+| `watching` | Monitoring session output for idle signals |
+| `confirming_idle` | Waiting to confirm session is truly idle (cancels if new output arrives) |
+| `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.
@@ -0,0 +1,80 @@
+# Spawn1337 Protocol (Autonomous Agents)
+
+Spawned agents are full-power Claude sessions running in their own screen sessions. They communicate via a filesystem-based message bus and signal completion via RalphTracker's `<promise>` mechanism.
+
+## Primary Interface: MCP Server
+
+The `claudeman-mcp` binary exposes spawn tools to Claude Code via MCP protocol, replacing the legacy terminal-tag-parsing approach (SpawnDetector).
+
+### MCP Tools
+
+| Tool | Description |
+|------|-------------|
+| `spawn_agent` | Spawn a new autonomous agent (builds task spec from parameters) |
+| `list_agents` | List all agents (active + completed + queued) |
+| `get_agent_status` | Get detailed agent status + progress |
+| `get_agent_result` | Read a completed agent's result |
+| `send_agent_message` | Send a message to a running agent |
+| `cancel_agent` | Cancel a running agent |
+
+### Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `CLAUDEMAN_API_URL` | Base URL for the Claudeman API (default: `http://localhost:3000`) |
+| `CLAUDEMAN_SESSION_ID` | Session ID of the calling Claude session |
+
+## Protocol Flow
+
+```
+Claude calls spawn_agent MCP tool
+  → MCP server builds task spec YAML
+  → POST /api/spawn/trigger with task spec
+  → SpawnOrchestrator creates agent directory: ~/claudeman-cases/spawn-<agentId>/
+  → Spawns interactive Claude session in screen
+  → Injects initial prompt via writeViaScreen()
+  → Agent works autonomously, writes progress to spawn-comms/
+  → RalphTracker detects <promise>PHRASE</promise> on child
+  → Orchestrator reads result.md, notifies parent via SSE
+```
+
+## Agent Directory Structure
+
+Each agent gets: `~/claudeman-cases/spawn-<agentId>/`
+
+```
+spawn-<agentId>/
+├── CLAUDE.md              # Generated from spawn-claude-md.ts
+├── spawn-comms/
+│   ├── task.md            # Task specification
+│   ├── progress.json      # Current progress state
+│   ├── result.md          # Final result (on completion)
+│   └── messages/          # Inter-agent messaging
+└── workspace/             # Symlinked context files
+```
+
+## Resource Governance
+
+| Limit | Value |
+|-------|-------|
+| Max concurrent agents | 5 |
+| Max depth | 3 |
+| Default timeout | 30min |
+| Max timeout | 120min |
+| Budget warning | 80% |
+| Graceful shutdown | 100% |
+| Force kill | 110% |
+
+## Agent Tree
+
+Agents can spawn children. Sessions track `parentAgentId` and `childAgentIds`. Cancelling a parent cascades to all children.
+
+## Key Source Files
+
+| File | Purpose |
+|------|---------|
+| `src/mcp-server.ts` | MCP server binary exposing spawn tools |
+| `src/spawn-orchestrator.ts` | Full agent lifecycle: spawn, monitor, budget, queue, cleanup |
+| `src/spawn-claude-md.ts` | Generates CLAUDE.md for spawned agent sessions |
+| `src/spawn-types.ts` | Types, YAML parser, factory functions |
+| `src/spawn-detector.ts` | Legacy: detects `<spawn1337>` tags in terminal output |