diff --git a/CLAUDE.md b/CLAUDE.md index 7fbfc343..e80049aa 100644 --- a/CLAUDE.md +++ b/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 `PHRASE`, 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. diff --git a/docs/respawn-state-machine.md b/docs/respawn-state-machine.md index 40ea8f9a..c1e5e1b1 100644 --- a/docs/respawn-state-machine.md +++ b/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 diff --git a/package.json b/package.json index 9474d385..aa6da8c4 100644 --- a/package.json +++ b/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",