docs: sync all documentation with recent state persistence and respawn changes

- CLAUDE.md: Add step confirmation behavior, respawnEnabled field, recovery
  strategy with dual redundancy, updated state lifecycle
- README.md: Multi-layer idle detection, step confirmation, state persistence
  in performance table, updated architecture diagram with State Store
- docs/: Updated last-modified dates to 2026-01-22

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

CLAUDE.md

@@ -172,6 +172,8 @@ WATCHING → CONFIRMING_IDLE → SENDING_UPDATE → WAITING_UPDATE → SENDING_C
 
 Steps can be skipped via config (`sendClear: false`, `sendInit: false`). Optional `kickstartPrompt` triggers if `/init` doesn't start work. Multi-layer idle detection triggers state transitions.
 
+**Step confirmation**: After sending each step (update, clear, init, kickstart), the controller waits for `completionConfirmMs` (5s) of output silence before proceeding to the next step. This prevents sending commands while Claude is still processing.
+
 ### Session Modes
 
 Sessions have a `mode` property (`SessionMode` type):
@@ -402,6 +404,7 @@ Writes debounced (500ms) to `~/.claudeman/state.json`. The web server persists f
 | `autoClearEnabled`, `autoClearThreshold` | Auto-clear settings |
 | `autoCompactEnabled`, `autoCompactThreshold`, `autoCompactPrompt` | Auto-compact settings |
 | `ralphEnabled`, `ralphCompletionPhrase` | Ralph / Todo tracker state |
+| `respawnEnabled` | Whether respawn controller is currently running |
 | `respawnConfig` | Full respawn config including `durationMinutes` |
 | `totalCost`, `inputTokens`, `outputTokens` | Token and cost tracking |
 
@@ -471,6 +474,7 @@ Use `createErrorResponse(code, details?)` from `types.ts`:
 - **Ghost discovery**: `reconcileScreens()` finds orphaned screens on startup
 - **Cleanup** (`cleanupSession()`): stops respawn, clears buffers/timers, kills screen, removes from `state.json`
 - **State sync**: Every session create/delete/update calls `persistSessionState()` which writes full state (including respawn config from controller) to `state.json`
+- **Recovery on restart**: Server reads `state.json` first (has all settings), falls back to `screens.json` for any sessions not found. Settings (auto-compact, auto-clear, respawn config, Ralph state) restored to live session objects after screen reattachment.
 
 ## TUI Architecture (Ink/React)
 
@@ -604,8 +608,14 @@ Long-running sessions are supported with automatic trimming:
 - Web server creates → session added to `state.json` + `screens.json`
 - Settings change → `state.json` updated (debounced 500ms)
 - Session deleted → removed from `state.json` (screen may survive if `killScreen: false`)
-- Server shutdown → all sessions cleaned up from `state.json`, screens preserved for recovery
+- Server shutdown → sessions preserved in `state.json` (not wiped), screens preserved in `screens.json`
-- Server restart → sessions restored from `screens.json`, state rebuilt in `state.json`
+- Server restart → sessions restored from `state.json` (primary) with `screens.json` as fallback
+
+**Recovery strategy** (double redundancy):
+1. **Primary**: `state.json` retains full session state across restarts (settings, tokens, respawn config)
+2. **Fallback**: `screens.json` provides screen metadata if `state.json` is missing a session
+3. After restoration, all settings (auto-compact, auto-clear, respawn, Ralph) are re-applied to live sessions
+4. `persistSessionState()` called after all restorations complete to sync final state
 
 Cases created in `~/claudeman-cases/` by default.
 

README.md

@@ -42,7 +42,8 @@ CLAUDEMAN_SESSION_ID=abc-123-def
 CLAUDEMAN_SCREEN_NAME=claudeman-myproject
 ```
 
-- Sessions auto-recover on startup
+- Sessions auto-recover on startup (dual redundancy: `state.json` + `screens.json`)
+- All settings (respawn, auto-compact, tokens) survive server restarts
 - Ghost session discovery finds orphaned screens
 - Claude knows it's managed (won't kill its own screen)
 
@@ -58,9 +59,10 @@ WATCHING → IDLE DETECTED → SEND UPDATE → CLEAR → INIT → CONTINUE
     └──────────────────────────────────────────────────────┘
 ```
 
-- Detects idle state via prompt indicators (`↵ send`, `❯`)
+- Multi-layer idle detection (completion messages, output silence, token stability)
 - Sends configurable update prompts to continue work
 - Auto-cycles `/clear` → `/init` for fresh context
+- Step confirmation (5s silence) between each command
 - **Keeps working even when Ralph loops stop**
 - Run for **24+ hours** completely unattended
 
@@ -236,6 +238,7 @@ flowchart TB
 
         subgraph Persistence["Persistence Layer"]
             SCR["GNU Screen Manager"]
+            SS["State Store<br/><small>state.json</small>"]
         end
 
         subgraph External["External"]
@@ -249,6 +252,7 @@ flowchart TB
     SM --> S1
     SM --> S2
     SM --> RC
+    SM --> SS
     S1 --> SCR
     S2 --> SCR
     RC --> SCR
@@ -266,6 +270,7 @@ Optimized for long-running autonomous sessions:
 | **60fps terminal** | 16ms server batching, `requestAnimationFrame` client |
 | **Memory management** | Auto-trimming buffers (2MB terminal, 1MB text) |
 | **Event debouncing** | 50-500ms on rapid state changes |
+| **State persistence** | Debounced writes, dual-redundancy recovery |
 
 ---
 

docs/claude-code-hooks-reference.md

@@ -2,7 +2,7 @@
 
 > Official documentation for Claude Code hooks system, extracted from [code.claude.com](https://code.claude.com/docs/en/hooks).
 
-**Last Updated**: 2026-01-20
+**Last Updated**: 2026-01-22
 **Source**: [Claude Code Hooks Documentation](https://code.claude.com/docs/en/hooks)
 
 ---

docs/ralph-wiggum-guide.md

@@ -2,7 +2,7 @@
 
 > This document consolidates official Anthropic documentation, community best practices, and implementation details for autonomous Claude Code loops.
 
-**Last Updated**: 2026-01-20
+**Last Updated**: 2026-01-22
 **Sources**: [Official Anthropic Plugin](https://github.com/anthropics/claude-code/tree/main/plugins/ralph-wiggum), [Claude Code Docs](https://code.claude.com/docs/en/hooks), [Claude Code Best Practices](https://www.anthropic.com/engineering/claude-code-best-practices)
 
 ---