docs: add ai-plan-checker, test utilities, and update respawn state machine

- Add ai-plan-checker.ts to CLAUDE.md Key Files table
- Document test utilities (MockSession, MockAiIdleChecker, MockAiPlanChecker)
- Update port allocation (3127 reserved for respawn-integration)
- Add ai_checking state to respawn state diagram
- Document AI Plan Checker in respawn-state-machine.md
- Add references to test documentation files

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

CLAUDE.md

@@ -17,7 +17,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 Claudeman is a Claude Code session manager with a web interface and autonomous Ralph Loop. It spawns Claude CLI processes via PTY, streams output in real-time via SSE, and supports scheduled/timed runs.
 
-**Version**: 0.1346
+**Version**: 0.1347
 
 **Tech Stack**: TypeScript (ES2022/NodeNext, strict mode), Node.js, Fastify, Server-Sent Events, node-pty
 
@@ -99,9 +99,12 @@ npx vitest run -t "should create session" # By pattern
 | 3115 | integration-flows.test.ts |
 | 3120 | session-cleanup.test.ts |
 | 3125 | ralph-integration.test.ts |
-| 3127+ | Next available |
+| 3127 | respawn-integration.test.ts (reserved) |
+| 3128+ | Next available |
 
-Unit tests (no port needed): respawn-controller, ralph-tracker, pty-interactive, task-queue, task, ralph-loop, session-manager, state-store, types, templates, ralph-config, spawn-detector, spawn-types, spawn-orchestrator, hooks-config, ai-idle-checker
+Unit tests (no port needed): respawn-controller, ralph-tracker, pty-interactive, task-queue, task, ralph-loop, session-manager, state-store, types, templates, ralph-config, spawn-detector, spawn-types, spawn-orchestrator, hooks-config, ai-idle-checker, ai-plan-checker
+
+**Test Utilities**: `test/respawn-test-utils.ts` provides MockSession, MockAiIdleChecker, MockAiPlanChecker, time controller, state tracker, and event recorder for respawn controller testing. See `test/respawn-test-plan.md` for architecture and `test/respawn-scenarios.md` for comprehensive test scenarios.
 
 **Test Safety**: `test/setup.ts` enforces max 10 concurrent screens, performs orphan cleanup, and protects its own process tree. You can safely run tests from within a Claudeman-managed session - the cleanup will not kill your own Claude instance. The respawn-controller tests use MockSession (not real screens).
 
@@ -182,6 +185,7 @@ claudeman reset                    # Reset all state
 | `src/session.ts` | Core PTY wrapper for Claude CLI. Modes: `runPrompt()`, `startInteractive()`, `startShell()` |
 | `src/respawn-controller.ts` | State machine for autonomous session cycling |
 | `src/ai-idle-checker.ts` | Spawns fresh Claude session to analyze terminal output for IDLE/WORKING verdict |
+| `src/ai-plan-checker.ts` | Spawns fresh Claude session to detect plan mode approval prompts for auto-accept |
 | `src/screen-manager.ts` | GNU screen persistence, ghost discovery, 4-strategy kill |
 | `src/ralph-tracker.ts` | Detects `<promise>PHRASE</promise>`, todos, loop status in output |
 | `src/ralph-config.ts` | Parses `.claude/ralph-loop.local.md` and CLAUDE.md for Ralph config |
@@ -215,7 +219,7 @@ claudeman reset                    # Reset all state
 
 ### Respawn State Machine
 
-State machine for autonomous session cycling: `watching` → `confirming_idle` → `sending_update` → `waiting_update` → `sending_clear` → `waiting_clear` → `sending_init` → `waiting_init` → `monitoring_init` → (optionally) `sending_kickstart`. Steps can be skipped via config (`sendClear: false`, `sendInit: false`). After each step, waits for `completionConfirmMs` (10s) of output silence before proceeding.
+State machine for autonomous session cycling: `watching` → `confirming_idle` → `ai_checking` → `sending_update` → `waiting_update` → `sending_clear` → `waiting_clear` → `sending_init` → `waiting_init` → `monitoring_init` → (optionally) `sending_kickstart`. Steps can be skipped via config (`sendClear: false`, `sendInit: false`). After each step, waits for `completionConfirmMs` (10s) of output silence before proceeding. AI idle check uses a fresh Claude session to analyze terminal output for IDLE/WORKING verdict.
 
 See `docs/respawn-state-machine.md` for the full state diagram, idle detection layers, and auto-accept behavior.
 

docs/respawn-state-machine.md

@@ -5,13 +5,13 @@ The respawn controller (`src/respawn-controller.ts`) manages autonomous session
 ## 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 ◄┘
+WATCHING → CONFIRMING_IDLE → AI_CHECKING → SENDING_UPDATE → WAITING_UPDATE → SENDING_CLEAR → WAITING_CLEAR
+    ↑         │ (new output)      │ (WORKING)                                              │
+    │         ↓                   ↓                                                        ▼
+    │       (reset)           (cooldown)              SENDING_INIT → WAITING_INIT → MONITORING_INIT
+    │                                                                                    │
+    │                                                           (if no work triggered)   ▼
+    └──────────────────────────────────────── SENDING_KICKSTART ← WAITING_KICKSTART ◄────┘
 ```
 
 ## States
@@ -20,6 +20,7 @@ WATCHING → CONFIRMING_IDLE → SENDING_UPDATE → WAITING_UPDATE → SENDING_C
 |-------|-------------|
 | `watching` | Monitoring session output for idle signals |
 | `confirming_idle` | Waiting to confirm session is truly idle (cancels if new output arrives) |
+| `ai_checking` | Running AI idle check to verify IDLE/WORKING status |
 | `sending_update` | About to send `/update` command |
 | `waiting_update` | Waiting for `/update` to complete (output silence) |
 | `sending_clear` | About to send `/clear` command |
@@ -55,3 +56,23 @@ Uses `confirming_idle` state to prevent false positives. Cancels idle confirmati
 ## 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.
+
+## AI Plan Checker
+
+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
+- `test/respawn-test-utils.ts` - Mock utilities (MockSession, MockAiIdleChecker, MockAiPlanChecker)
+- `test/respawn-analysis.md` - Code coverage analysis and identified issues

package.json

@@ -1,6 +1,6 @@
 {
   "name": "claudeman",
-  "version": "0.1346",
+  "version": "0.1347",
   "description": "The missing control plane for Claude Code - run 20 autonomous agents with real-time monitoring and session persistence",
   "type": "module",
   "main": "dist/index.js",