jmagly
diff --git a/‎.claude/commands/ralph-external.md‎
Lines changed: 141 additions & 0 deletions b/‎.claude/commands/ralph-external.md‎
Lines changed: 141 additions & 0 deletions
diff --git a/‎test/unit/ralph-external/session-launcher.test.ts‎
Lines changed: 207 additions & 1 deletion b/‎test/unit/ralph-external/session-launcher.test.ts‎
Lines changed: 207 additions & 1 deletion
@@ -0,0 +1,141 @@
+---
+description: Start an external Ralph loop for crash-resilient iterative task execution
+category: sdlc-orchestration
+argument-hint: "<objective>" --completion "<criteria>" [--max-iterations N] [--verbose] [--checkpoint-interval M]
+allowed-tools: Bash, Read, Write
+model: opus
+---
+
+# /ralph-external
+
+Start an **External Ralph Loop** - a supervisor that wraps Claude Code sessions to provide crash recovery, cross-session persistence, and comprehensive state capture for long-running sessions (6-8 hours).
+
+## Arguments
+
+| Argument | Type | Required | Description |
+|----------|------|----------|-------------|
+| `<objective>` | string | Yes | Task objective |
+| `--completion` | string | Yes | Verifiable completion criteria |
+| `--max-iterations` | number | No | Max external iterations (default: 5) |
+| `--model` | string | No | Claude model (default: opus) |
+| `--budget` | number | No | Budget per iteration USD (default: 2.0) |
+| `--timeout` | number | No | Timeout per iteration minutes (default: 60) |
+| `--verbose` | flag | No | Enable verbose Claude output for debugging |
+| `--checkpoint-interval` | number | No | Checkpoint interval minutes (default: 30) |
+| `--no-snapshots` | flag | No | Disable pre/post session snapshots |
+| `--no-checkpoints` | flag | No | Disable periodic checkpoints |
+| `--use-claude-assessment` | flag | No | Use Claude for state assessment |
+| `--key-files` | string | No | Comma-separated key files to track |
+| `--gitea-issue` | flag | No | Create Gitea issue for tracking |
+
+## When to Use
+
+Use External Ralph when:
+- Task may take longer than a single session
+- Context corruption is a risk
+- You need crash recovery
+- Progress tracking across sessions is important
+
+Use Internal Ralph (`/ralph`) for:
+- Tasks that fit within a single session
+- Fast iteration cycles
+- Simple verification criteria
+
+## Workflow
+
+Each iteration follows a comprehensive capture flow:
+
+1. **Pre-Session Snapshot** - Captures git status, .aiwg state, file hashes
+2. **Prompt Generation** - Context-aware prompt with learnings and progress
+3. **Checkpoint Manager Start** - Begins periodic state snapshots
+4. **Session Launch** - Spawns Claude with stdout/stderr/transcript capture
+5. **Checkpoint Manager Stop** - Final checkpoint summary
+6. **Post-Session Snapshot** - Captures changes, calculates diff
+7. **Output Analysis** - Determines completion/continuation
+8. **State Update** - Records all capture artifacts
+
+## Capture Features
+
+| Feature | Default | Description |
+|---------|---------|-------------|
+| Pre/Post Snapshots | Enabled | Git and .aiwg state before/after session |
+| Periodic Checkpoints | Enabled | State snapshots every 30 min during session |
+| Session Transcript | Always | Claude transcript from ~/.claude/projects/ |
+| Stream-JSON Parsing | Always | Tool calls, errors, completions extracted |
+| Verbose Output | Disabled | Enable with --verbose for debugging |
+
+## Examples
+
+```bash
+# Simple task
+/ralph-external "Fix all failing tests" --completion "npm test passes"
+
+# With enhanced capture
+/ralph-external "Implement user authentication" \
+  --completion "npm test -- --testPathPattern=auth passes" \
+  --max-iterations 10 \
+  --verbose \
+  --checkpoint-interval 15
+
+# Long-running migration (6-8 hours)
+/ralph-external "Migrate codebase to TypeScript" \
+  --completion "npx tsc --noEmit exits 0" \
+  --max-iterations 20 \
+  --budget 5.0 \
+  --checkpoint-interval 20 \
+  --key-files "package.json,tsconfig.json,CLAUDE.md"
+
+# With Claude-powered assessment
+/ralph-external "Complex refactoring task" \
+  --completion "npm test && npm run lint" \
+  --max-iterations 15 \
+  --use-claude-assessment \
+  --gitea-issue
+
+# Minimal capture (faster)
+/ralph-external "Quick fix" \
+  --completion "npm test passes" \
+  --no-checkpoints
+```
+
+## State Directory
+
+```
+.aiwg/ralph-external/
+├── session-state.json           # Active loop state
+├── iterations/
+│   └── 001/
+│       ├── prompt.md            # Prompt used
+│       ├── stdout.log           # Captured stdout
+│       ├── stderr.log           # Captured stderr
+│       ├── pre-snapshot.json    # State before session
+│       ├── post-snapshot.json   # State after session
+│       ├── snapshot-diff.json   # Changes detected
+│       ├── analysis.json        # Output analysis
+│       ├── state-assessment.json # Two-phase assessment
+│       ├── session-transcript.jsonl # Claude transcript
+│       ├── parsed-events.json   # Stream-JSON events
+│       └── checkpoints/
+│           ├── 001-checkpoint.json
+│           ├── 002-checkpoint.json
+│           └── ...
+├── prompts/                      # All generated prompts
+├── analysis/                     # All analysis results
+└── completion-report.md          # Final summary
+```
+
+## Natural Language Triggers
+
+- "Start external ralph loop for..."
+- "Run crash-resilient loop to..."
+- "Execute long-running task..."
+
+## References
+
+- @tools/ralph-external/orchestrator.mjs - Main loop logic
+- @tools/ralph-external/index.mjs - CLI entry point
+- @tools/ralph-external/snapshot-manager.mjs - Pre/post session snapshots
+- @tools/ralph-external/checkpoint-manager.mjs - Periodic checkpoints
+- @tools/ralph-external/state-assessor.mjs - Two-phase assessment
+- @tools/ralph-external/session-launcher.mjs - Claude CLI wrapper
+- @.claude/agents/ralph-output-analyzer.md - Output analyzer
@@ -4,17 +4,28 @@
  * @source @tools/ralph-external/session-launcher.mjs
  */
 
-import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { describe, it, expect, beforeEach, vi, afterEach } from 'vitest';
+import { mkdirSync, writeFileSync, rmSync, existsSync } from 'fs';
+import { join } from 'path';
 
 // Import the module under test
 // @ts-ignore - ESM import
 import { SessionLauncher } from '../../../tools/ralph-external/session-launcher.mjs';
 
 describe('SessionLauncher', () => {
   let launcher: InstanceType<typeof SessionLauncher>;
+  let testDir: string;
 
   beforeEach(() => {
     launcher = new SessionLauncher();
+    testDir = join('/tmp', `ralph-test-${Date.now()}`);
+    mkdirSync(testDir, { recursive: true });
+  });
+
+  afterEach(() => {
+    if (existsSync(testDir)) {
+      rmSync(testDir, { recursive: true, force: true });
+    }
   });
 
   describe('constructor', () => {
@@ -36,6 +47,7 @@ describe('SessionLauncher', () => {
       workingDir: '/project',
       stdoutPath: '/tmp/stdout.log',
       stderrPath: '/tmp/stderr.log',
+      outputDir: '/tmp/output',
     };
 
     it('should include required flags', () => {
@@ -54,6 +66,35 @@ describe('SessionLauncher', () => {
       expect(args[args.length - 1]).toBe('Fix the bug');
     });
 
+    it('should include verbose flag when specified', () => {
+      const args = launcher.buildArgs({
+        ...baseOptions,
+        verbose: true,
+      });
+
+      expect(args).toContain('--verbose');
+    });
+
+    it('should not include verbose flag when false', () => {
+      const args = launcher.buildArgs({
+        ...baseOptions,
+        verbose: false,
+      });
+
+      expect(args).not.toContain('--verbose');
+    });
+
+    it('should include max-turns when specified', () => {
+      const args = launcher.buildArgs({
+        ...baseOptions,
+        maxTurns: 10,
+      });
+
+      const turnsIndex = args.indexOf('--max-turns');
+      expect(turnsIndex).toBeGreaterThan(-1);
+      expect(args[turnsIndex + 1]).toBe('10');
+    });
+
     it('should include model when specified', () => {
       const args = launcher.buildArgs({
         ...baseOptions,
@@ -117,6 +158,171 @@ describe('SessionLauncher', () => {
       expect(args).not.toContain('--max-budget-usd');
       expect(args).not.toContain('--mcp-config');
       expect(args).not.toContain('--append-system-prompt');
+      expect(args).not.toContain('--max-turns');
+      expect(args).not.toContain('--verbose');
+    });
+  });
+
+  describe('parseStreamEvents', () => {
+    it('should parse valid stream-json events', async () => {
+      const stdoutPath = join(testDir, 'stdout.log');
+
+      // Create mock stream-json output
+      const mockEvents = [
+        { type: 'message_start', message: { id: 'msg_1' } },
+        { type: 'content_block_start', index: 0 },
+        { type: 'content_block_delta', delta: { type: 'text_delta', text: 'Hello' } },
+        { name: 'tool_read_file', type: 'tool_use', id: 'tool_1' },
+        { error: 'File not found', code: 'not_found' },
+        { type: 'message_stop' },
+      ];
+
+      writeFileSync(stdoutPath, mockEvents.map(e => JSON.stringify(e)).join('\n'));
+
+      const { path, stats } = await launcher.parseStreamEvents(stdoutPath, testDir);
+
+      expect(path).toBe(join(testDir, 'parsed-events.json'));
+      expect(stats.totalEvents).toBe(6);
+      expect(stats.toolCallCount).toBe(1);
+      expect(stats.errorCount).toBe(1);
+    });
+
+    it('should handle empty stdout file', async () => {
+      const stdoutPath = join(testDir, 'stdout-empty.log');
+      writeFileSync(stdoutPath, '');
+
+      const { path, stats } = await launcher.parseStreamEvents(stdoutPath, testDir);
+
+      expect(path).toBe(join(testDir, 'parsed-events.json'));
+      expect(stats.totalEvents).toBe(0);
+      expect(stats.toolCallCount).toBe(0);
+      expect(stats.errorCount).toBe(0);
+    });
+
+    it('should skip malformed JSON lines', async () => {
+      const stdoutPath = join(testDir, 'stdout-malformed.log');
+
+      const content = [
+        '{"type": "valid"}',
+        'not json',
+        '{"type": "also_valid"}',
+        '{incomplete',
+      ].join('\n');
+
+      writeFileSync(stdoutPath, content);
+
+      const { path, stats } = await launcher.parseStreamEvents(stdoutPath, testDir);
+
+      expect(path).toBe(join(testDir, 'parsed-events.json'));
+      expect(stats.totalEvents).toBe(2); // Only valid lines counted
+    });
+
+    it('should categorize different event types', async () => {
+      const stdoutPath = join(testDir, 'stdout-types.log');
+
+      const mockEvents = [
+        { type: 'message_start' },
+        { type: 'content_block_start' },
+        { type: 'content_block_delta', delta: {} },
+        { type: 'content_block_stop' },
+        { type: 'message_stop' },
+        { tool_use: true, name: 'test_tool' },
+        { error: 'Test error' },
+      ];
+
+      writeFileSync(stdoutPath, mockEvents.map(e => JSON.stringify(e)).join('\n'));
+
+      const { path, stats } = await launcher.parseStreamEvents(stdoutPath, testDir);
+
+      expect(stats.totalEvents).toBe(7);
+      expect(stats.toolCallCount).toBeGreaterThan(0);
+      expect(stats.errorCount).toBeGreaterThan(0);
+    });
+  });
+
+  describe('_categorizeStreamEvent', () => {
+    it('should categorize by type field', () => {
+      expect(launcher._categorizeStreamEvent({ type: 'message_start' })).toBe('message_start');
+      expect(launcher._categorizeStreamEvent({ type: 'error' })).toBe('error');
+    });
+
+    it('should detect tool calls', () => {
+      expect(launcher._categorizeStreamEvent({ tool: 'read' })).toBe('tool_call');
+      expect(launcher._categorizeStreamEvent({ tool_use: true })).toBe('tool_call');
+      expect(launcher._categorizeStreamEvent({ name: 'tool_something' })).toBe('tool_call');
+    });
+
+    it('should detect errors', () => {
+      expect(launcher._categorizeStreamEvent({ error: 'failure' })).toBe('error');
+      expect(launcher._categorizeStreamEvent({ message: 'error occurred' })).toBe('error');
+    });
+
+    it('should detect completions', () => {
+      expect(launcher._categorizeStreamEvent({ stop_reason: 'end_turn' })).toBe('completion');
+      expect(launcher._categorizeStreamEvent({ content: [{ type: 'text' }] })).toBe('completion');
+    });
+
+    it('should detect deltas', () => {
+      expect(launcher._categorizeStreamEvent({ delta: {} })).toBe('content_delta');
+      expect(launcher._categorizeStreamEvent({ content_block_delta: {} })).toBe('content_delta');
+    });
+
+    it('should detect start events', () => {
+      expect(launcher._categorizeStreamEvent({ message_start: {} })).toBe('start');
+      expect(launcher._categorizeStreamEvent({ content_block_start: {} })).toBe('start');
+    });
+
+    it('should detect stop events', () => {
+      expect(launcher._categorizeStreamEvent({ message_stop: {} })).toBe('stop');
+      expect(launcher._categorizeStreamEvent({ content_block_stop: {} })).toBe('stop');
+    });
+
+    it('should return unknown for unrecognized events', () => {
+      expect(launcher._categorizeStreamEvent({ random: 'data' })).toBe('unknown');
+      expect(launcher._categorizeStreamEvent({})).toBe('unknown');
+    });
+  });
+
+  describe('copySessionTranscript', () => {
+    it('should encode working directory path correctly', async () => {
+      const sessionId = 'test-session-123';
+      const workingDir = '/foo/bar/baz';
+
+      // Mock the home directory to our test dir for this test
+      const expectedEncodedPath = '-foo-bar-baz';
+
+      // This will fail to find the file, but we can check the emitted event
+      let emittedPath = '';
+      launcher.on('transcript-not-found', ({ sourcePath }) => {
+        emittedPath = sourcePath;
+      });
+
+      await launcher.copySessionTranscript(sessionId, workingDir, testDir);
+
+      expect(emittedPath).toContain(expectedEncodedPath);
+      expect(emittedPath).toContain(sessionId);
+    });
+
+    it('should return null when transcript does not exist', async () => {
+      const result = await launcher.copySessionTranscript(
+        'nonexistent-session',
+        '/some/path',
+        testDir
+      );
+
+      expect(result).toBeNull();
+    });
+
+    it('should emit transcript-not-found event', async () => {
+      const emittedEvents: any[] = [];
+      launcher.on('transcript-not-found', (data) => {
+        emittedEvents.push(data);
+      });
+
+      await launcher.copySessionTranscript('test', '/path', testDir);
+
+      expect(emittedEvents.length).toBeGreaterThan(0);
+      expect(emittedEvents[0].sourcePath).toBeDefined();
     });
   });