rafcode 2.0.0 → 2.1.0

package/src/core/claude-runner.ts

@@ -50,6 +50,12 @@ export interface ClaudeRunnerOptions {
     /** Path to the outcome file that should be committed. */
     outcomeFilePath: string;
   };
+  /**
+   * Claude Code reasoning effort level.
+   * Sets CLAUDE_CODE_EFFORT_LEVEL env var for the spawned process.
+   * Only applied in non-interactive modes (run, runVerbose).
+   */
+  effortLevel?: 'low' | 'medium' | 'high';
 }
 
 export interface ClaudeRunnerConfig {
@@ -65,6 +71,7 @@ export interface RunResult {
   exitCode: number;
   timedOut: boolean;
   contextOverflow: boolean;
+  sessionId?: string;
 }
 
 const CONTEXT_OVERFLOW_PATTERNS = [
@@ -252,11 +259,20 @@ export class ClaudeRunner {
   private activeProcess: pty.IPty | null = null;
   private killed = false;
   private model: string;
+  private _sessionId: string | undefined;
 
   constructor(config: ClaudeRunnerConfig = {}) {
     this.model = config.model ?? 'opus';
   }
 
+  /**
+   * Get the session ID captured from the most recent Claude session.
+   * Available after the system.init event is received during run() or runVerbose().
+   */
+  get sessionId(): string | undefined {
+    return this._sessionId;
+  }
+
   /**
    * Run Claude interactively with stdin/stdout passthrough.
    * Used for planning phase where user interaction is needed.
@@ -367,7 +383,7 @@ export class ClaudeRunner {
    * - Default timeout is 60 minutes if not specified
    */
   async run(prompt: string, options: ClaudeRunnerOptions = {}): Promise<RunResult> {
-    const { timeout = 60, cwd = process.cwd(), outcomeFilePath, commitContext } = options;
+    const { timeout = 60, cwd = process.cwd(), outcomeFilePath, commitContext, effortLevel } = options;
     // Ensure timeout is a positive number, fallback to 60 minutes
     const validatedTimeout = Number(timeout) > 0 ? Number(timeout) : 60;
     const timeoutMs = validatedTimeout * 60 * 1000;
@@ -377,14 +393,20 @@ export class ClaudeRunner {
       let stderr = '';
       let timedOut = false;
       let contextOverflow = false;
+      let sessionId: string | undefined;
 
       const claudePath = getClaudePath();
 
       logger.debug(`Starting Claude execution session with model: ${this.model}`);
       logger.debug(`Claude path: ${claudePath}`);
 
-      // Use --append-system-prompt to add RAF instructions to system prompt
-      // This gives RAF instructions stronger precedence than passing as user message
+      // Build env, optionally injecting effort level
+      const env = effortLevel
+        ? { ...process.env, CLAUDE_CODE_EFFORT_LEVEL: effortLevel }
+        : process.env;
+
+      // Use --output-format stream-json to get structured events including session_id.
+      // Unlike runVerbose(), output is parsed silently without writing to stdout.
       // --dangerously-skip-permissions bypasses interactive prompts
       // -p enables print mode (non-interactive)
       const proc = spawn(claudePath, [
@@ -393,11 +415,14 @@ export class ClaudeRunner {
         this.model,
         '--append-system-prompt',
         prompt,
+        '--output-format',
+        'stream-json',
+        '--verbose',
         '-p',
         'Execute the task as described in the system prompt.',
       ], {
         cwd,
-        env: process.env,
+        env,
         stdio: ['ignore', 'pipe', 'pipe'], // no stdin needed
       });
 
@@ -408,6 +433,9 @@ export class ClaudeRunner {
       const timeoutHandle = setTimeout(() => {
         timedOut = true;
         logger.warn('Claude session timed out');
+        if (sessionId) {
+          logger.info(`Session ID: ${sessionId}`);
+        }
         proc.kill('SIGTERM');
       }, timeoutMs);
 
@@ -418,22 +446,47 @@ export class ClaudeRunner {
         commitContext,
       );
 
-      // Collect stdout
+      // Buffer for incomplete NDJSON lines (data chunks may split across line boundaries)
+      let lineBuffer = '';
+
+      // Collect stdout - parse NDJSON silently (no display output)
       proc.stdout.on('data', (data) => {
-        const text = data.toString();
-        output += text;
-
-        // Check for completion marker to start grace period
-        completionDetector.checkOutput(output);
-
-        // Check for context overflow
-        for (const pattern of CONTEXT_OVERFLOW_PATTERNS) {
-          if (pattern.test(text)) {
-            contextOverflow = true;
-            logger.warn('Context overflow detected');
-            proc.kill('SIGTERM');
-            break;
+        lineBuffer += data.toString();
+
+        // Process complete lines from the NDJSON stream
+        let newlineIndex: number;
+        while ((newlineIndex = lineBuffer.indexOf('\n')) !== -1) {
+          const line = lineBuffer.substring(0, newlineIndex);
+          lineBuffer = lineBuffer.substring(newlineIndex + 1);
+
+          const result = renderStreamEvent(line);
+
+          if (result.sessionId && !sessionId) {
+            sessionId = result.sessionId;
+            this._sessionId = sessionId;
           }
+
+          if (result.textContent) {
+            output += result.textContent;
+
+            // Check for completion marker to start grace period
+            completionDetector.checkOutput(output);
+
+            // Check for context overflow
+            for (const pattern of CONTEXT_OVERFLOW_PATTERNS) {
+              if (pattern.test(result.textContent)) {
+                contextOverflow = true;
+                logger.warn('Context overflow detected');
+                if (sessionId) {
+                  logger.info(`Session ID: ${sessionId}`);
+                }
+                proc.kill('SIGTERM');
+                break;
+              }
+            }
+          }
+
+          // Silently discard display output (unlike runVerbose)
         }
       });
 
@@ -443,6 +496,17 @@ export class ClaudeRunner {
       });
 
       proc.on('close', (exitCode) => {
+        // Process any remaining data in the line buffer
+        if (lineBuffer.trim()) {
+          const result = renderStreamEvent(lineBuffer);
+          if (result.sessionId && !sessionId) {
+            sessionId = result.sessionId;
+          }
+          if (result.textContent) {
+            output += result.textContent;
+          }
+        }
+
         clearTimeout(timeoutHandle);
         completionDetector.cleanup();
         this.activeProcess = null;
@@ -456,6 +520,7 @@ export class ClaudeRunner {
           exitCode: exitCode ?? (this.killed ? 130 : 1),
           timedOut,
           contextOverflow,
+          sessionId,
         });
       });
     });
@@ -474,7 +539,7 @@ export class ClaudeRunner {
    * - Default timeout is 60 minutes if not specified
    */
   async runVerbose(prompt: string, options: ClaudeRunnerOptions = {}): Promise<RunResult> {
-    const { timeout = 60, cwd = process.cwd(), outcomeFilePath, commitContext } = options;
+    const { timeout = 60, cwd = process.cwd(), outcomeFilePath, commitContext, effortLevel } = options;
     // Ensure timeout is a positive number, fallback to 60 minutes
     const validatedTimeout = Number(timeout) > 0 ? Number(timeout) : 60;
     const timeoutMs = validatedTimeout * 60 * 1000;
@@ -484,6 +549,7 @@ export class ClaudeRunner {
       let stderr = '';
       let timedOut = false;
       let contextOverflow = false;
+      let sessionId: string | undefined;
 
       const claudePath = getClaudePath();
 
@@ -491,6 +557,11 @@ export class ClaudeRunner {
       logger.debug(`Prompt length: ${prompt.length}, timeout: ${timeoutMs}ms, cwd: ${cwd}`);
       logger.debug(`Claude path: ${claudePath}`);
 
+      // Build env, optionally injecting effort level
+      const env = effortLevel
+        ? { ...process.env, CLAUDE_CODE_EFFORT_LEVEL: effortLevel }
+        : process.env;
+
       logger.debug('Spawning process...');
       // Use --output-format stream-json --verbose to get real-time streaming events
       // including tool calls, file operations, and intermediate output.
@@ -509,7 +580,7 @@ export class ClaudeRunner {
         'Execute the task as described in the system prompt.',
       ], {
         cwd,
-        env: process.env,
+        env,
         stdio: ['ignore', 'pipe', 'pipe'], // no stdin needed
       });
 
@@ -521,6 +592,9 @@ export class ClaudeRunner {
       const timeoutHandle = setTimeout(() => {
         timedOut = true;
         logger.warn('Claude session timed out');
+        if (sessionId) {
+          logger.info(`Session ID: ${sessionId}`);
+        }
         proc.kill('SIGTERM');
       }, timeoutMs);
 
@@ -549,27 +623,35 @@ export class ClaudeRunner {
           const line = lineBuffer.substring(0, newlineIndex);
           lineBuffer = lineBuffer.substring(newlineIndex + 1);
 
-          const { display, textContent } = renderStreamEvent(line);
+          const result = renderStreamEvent(line);
+
+          if (result.sessionId && !sessionId) {
+            sessionId = result.sessionId;
+            this._sessionId = sessionId;
+          }
 
-          if (textContent) {
-            output += textContent;
+          if (result.textContent) {
+            output += result.textContent;
 
             // Check for completion marker to start grace period
             completionDetector.checkOutput(output);
 
             // Check for context overflow
             for (const pattern of CONTEXT_OVERFLOW_PATTERNS) {
-              if (pattern.test(textContent)) {
+              if (pattern.test(result.textContent)) {
                 contextOverflow = true;
                 logger.warn('Context overflow detected');
+                if (sessionId) {
+                  logger.info(`Session ID: ${sessionId}`);
+                }
                 proc.kill('SIGTERM');
                 break;
               }
             }
           }
 
-          if (display) {
-            process.stdout.write(display);
+          if (result.display) {
+            process.stdout.write(result.display);
           }
         }
       });
@@ -582,12 +664,15 @@ export class ClaudeRunner {
       proc.on('close', (exitCode) => {
         // Process any remaining data in the line buffer
         if (lineBuffer.trim()) {
-          const { display, textContent } = renderStreamEvent(lineBuffer);
-          if (textContent) {
-            output += textContent;
+          const result = renderStreamEvent(lineBuffer);
+          if (result.sessionId && !sessionId) {
+            sessionId = result.sessionId;
           }
-          if (display) {
-            process.stdout.write(display);
+          if (result.textContent) {
+            output += result.textContent;
+          }
+          if (result.display) {
+            process.stdout.write(result.display);
           }
         }
 
@@ -605,6 +690,134 @@ export class ClaudeRunner {
           exitCode: exitCode ?? (this.killed ? 130 : 1),
           timedOut,
           contextOverflow,
+          sessionId,
+        });
+      });
+    });
+  }
+
+  /**
+   * Resume an interrupted Claude session by session ID.
+   * Spawns Claude with --resume flag only — no prompt, model, or system prompt flags.
+   * Uses stream-json output format for session ID extraction and completion detection.
+   */
+  async runResume(sessionId: string, options: ClaudeRunnerOptions = {}): Promise<RunResult> {
+    const { timeout = 60, cwd = process.cwd(), outcomeFilePath, commitContext, effortLevel } = options;
+    const validatedTimeout = Number(timeout) > 0 ? Number(timeout) : 60;
+    const timeoutMs = validatedTimeout * 60 * 1000;
+
+    return new Promise((resolve) => {
+      let output = '';
+      let stderr = '';
+      let timedOut = false;
+      let contextOverflow = false;
+      let newSessionId: string | undefined;
+
+      const claudePath = getClaudePath();
+
+      logger.debug(`Resuming Claude session: ${sessionId}`);
+
+      const env = effortLevel
+        ? { ...process.env, CLAUDE_CODE_EFFORT_LEVEL: effortLevel }
+        : process.env;
+
+      // Resume with minimal flags: --resume, --dangerously-skip-permissions, --output-format stream-json --verbose
+      // Do NOT pass --model, --append-system-prompt, or -p — Claude restores these from the session
+      const proc = spawn(claudePath, [
+        '--resume',
+        sessionId,
+        '--dangerously-skip-permissions',
+        '--output-format',
+        'stream-json',
+        '--verbose',
+      ], {
+        cwd,
+        env,
+        stdio: ['ignore', 'pipe', 'pipe'],
+      });
+
+      this.activeProcess = proc as any;
+
+      const timeoutHandle = setTimeout(() => {
+        timedOut = true;
+        logger.warn('Resumed Claude session timed out');
+        if (newSessionId) {
+          logger.info(`Session ID: ${newSessionId}`);
+        }
+        proc.kill('SIGTERM');
+      }, timeoutMs);
+
+      const completionDetector = createCompletionDetector(
+        () => proc.kill('SIGTERM'),
+        outcomeFilePath,
+        commitContext,
+      );
+
+      let lineBuffer = '';
+
+      proc.stdout.on('data', (data) => {
+        lineBuffer += data.toString();
+
+        let newlineIndex: number;
+        while ((newlineIndex = lineBuffer.indexOf('\n')) !== -1) {
+          const line = lineBuffer.substring(0, newlineIndex);
+          lineBuffer = lineBuffer.substring(newlineIndex + 1);
+
+          const result = renderStreamEvent(line);
+
+          if (result.sessionId && !newSessionId) {
+            newSessionId = result.sessionId;
+            this._sessionId = newSessionId;
+          }
+
+          if (result.textContent) {
+            output += result.textContent;
+            completionDetector.checkOutput(output);
+
+            for (const pattern of CONTEXT_OVERFLOW_PATTERNS) {
+              if (pattern.test(result.textContent)) {
+                contextOverflow = true;
+                logger.warn('Context overflow detected');
+                if (newSessionId) {
+                  logger.info(`Session ID: ${newSessionId}`);
+                }
+                proc.kill('SIGTERM');
+                break;
+              }
+            }
+          }
+        }
+      });
+
+      proc.stderr.on('data', (data) => {
+        stderr += data.toString();
+      });
+
+      proc.on('close', (exitCode) => {
+        if (lineBuffer.trim()) {
+          const result = renderStreamEvent(lineBuffer);
+          if (result.sessionId && !newSessionId) {
+            newSessionId = result.sessionId;
+          }
+          if (result.textContent) {
+            output += result.textContent;
+          }
+        }
+
+        clearTimeout(timeoutHandle);
+        completionDetector.cleanup();
+        this.activeProcess = null;
+
+        if (stderr) {
+          logger.debug(`Claude stderr: ${stderr}`);
+        }
+
+        resolve({
+          output,
+          exitCode: exitCode ?? (this.killed ? 130 : 1),
+          timedOut,
+          contextOverflow,
+          sessionId: newSessionId,
         });
       });
     });

package/src/core/shutdown-handler.ts

@@ -54,6 +54,11 @@ class ShutdownHandler {
     this.isShuttingDown = true;
     logger.info(`\nReceived ${signal}, shutting down gracefully...`);
 
+    // Print session ID if available (for resumption/debugging)
+    if (this.claudeRunner?.sessionId) {
+      logger.info(`Session ID: ${this.claudeRunner.sessionId}`);
+    }
+
     // Kill Claude process if running
     if (this.claudeRunner?.isRunning()) {
       logger.debug('Killing Claude process...');

package/src/core/worktree.ts

@@ -3,6 +3,7 @@ import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
 import { logger } from '../utils/logger.js';
+import { extractProjectNumber, extractProjectName, isBase26Prefix, decodeBase26 } from '../utils/paths.js';
 
 export interface WorktreeCreateResult {
   success: boolean;
@@ -355,3 +356,79 @@ export function listWorktreeProjects(repoBasename: string): string[] {
     return [];
   }
 }
+
+export interface WorktreeProjectResolution {
+  /** The worktree project folder name (e.g., "ahrren-turbo-finder") */
+  folder: string;
+  /** The worktree root path (e.g., ~/.raf/worktrees/RAF/ahrren-turbo-finder) */
+  worktreeRoot: string;
+}
+
+/**
+ * Resolve a project identifier against worktree folder names.
+ * Uses the same matching strategy as `resolveProjectIdentifierWithDetails`:
+ * 1. Full folder name match (exact, case-insensitive)
+ * 2. Base26 prefix match (6-char ID)
+ * 3. Project name match (the portion after the prefix)
+ *
+ * @param repoBasename - The basename of the current git repo
+ * @param identifier - The project identifier to resolve
+ * @returns The matched worktree project info or null if not found
+ */
+export function resolveWorktreeProjectByIdentifier(
+  repoBasename: string,
+  identifier: string,
+): WorktreeProjectResolution | null {
+  const wtProjectDirs = listWorktreeProjects(repoBasename);
+  if (wtProjectDirs.length === 0) return null;
+
+  const lowerIdentifier = identifier.toLowerCase();
+
+  // 1. Full folder name match (exact, case-insensitive)
+  for (const dir of wtProjectDirs) {
+    if (dir.toLowerCase() === lowerIdentifier) {
+      return {
+        folder: dir,
+        worktreeRoot: computeWorktreePath(repoBasename, dir),
+      };
+    }
+  }
+
+  // 2. Base26 prefix match
+  if (isBase26Prefix(identifier)) {
+    const targetNumber = decodeBase26(identifier);
+    if (targetNumber !== null) {
+      for (const dir of wtProjectDirs) {
+        const prefix = extractProjectNumber(dir);
+        if (prefix) {
+          const dirNumber = decodeBase26(prefix);
+          if (dirNumber === targetNumber) {
+            return {
+              folder: dir,
+              worktreeRoot: computeWorktreePath(repoBasename, dir),
+            };
+          }
+        }
+      }
+    }
+  }
+
+  // 3. Project name match (case-insensitive)
+  const nameMatches: string[] = [];
+  for (const dir of wtProjectDirs) {
+    const name = extractProjectName(dir);
+    if (name && name.toLowerCase() === lowerIdentifier) {
+      nameMatches.push(dir);
+    }
+  }
+
+  if (nameMatches.length === 1) {
+    return {
+      folder: nameMatches[0]!,
+      worktreeRoot: computeWorktreePath(repoBasename, nameMatches[0]!),
+    };
+  }
+
+  // Ambiguous or no match
+  return null;
+}

package/src/parsers/stream-renderer.ts

@@ -11,6 +11,7 @@
 export interface StreamEvent {
   type: string;
   subtype?: string;
+  session_id?: string;
   message?: {
     content?: ContentBlock[];
   };
@@ -72,6 +73,8 @@ export interface RenderResult {
   display: string;
   /** Text content to accumulate for output parsing (completion markers, etc.) */
   textContent: string;
+  /** Session ID extracted from system init event, if present */
+  sessionId?: string;
 }
 
 /**
@@ -93,7 +96,7 @@ export function renderStreamEvent(line: string): RenderResult {
 
   switch (event.type) {
     case 'system':
-      return { display: '', textContent: '' };
+      return { display: '', textContent: '', sessionId: event.session_id };
 
     case 'assistant':
       return renderAssistant(event);

package/src/types/config.ts

@@ -29,6 +29,7 @@ export interface DoCommandOptions {
   model?: ClaudeModelName;
   sonnet?: boolean;
   worktree?: boolean;
+  resume?: string;
 }
 
 export interface StatusCommandOptions {

package/tests/unit/claude-runner-interactive.test.ts

@@ -244,6 +244,30 @@ describe('ClaudeRunner - runInteractive', () => {
     });
   });
 
+  describe('effort level (not applied in interactive mode)', () => {
+    it('should NOT set CLAUDE_CODE_EFFORT_LEVEL in runInteractive env', async () => {
+      const mockProc = createMockPtyProcess();
+      const mockStdin = createMockStdin();
+      const mockStdout = createMockStdout();
+
+      Object.defineProperty(process, 'stdin', { value: mockStdin, configurable: true });
+      Object.defineProperty(process, 'stdout', { value: mockStdout, configurable: true });
+
+      mockPtySpawn.mockReturnValue(mockProc);
+
+      const runner = new ClaudeRunner();
+      // Even if effortLevel were somehow passed, interactive mode should use process.env as-is
+      const runPromise = runner.runInteractive('system', 'user');
+
+      const spawnOptions = mockPtySpawn.mock.calls[0][2];
+      // Interactive mode passes process.env directly, no effort level override
+      expect(spawnOptions.env).not.toHaveProperty('CLAUDE_CODE_EFFORT_LEVEL');
+
+      mockProc._exitCallback({ exitCode: 0 });
+      await runPromise;
+    });
+  });
+
   describe('--dangerously-skip-permissions flag', () => {
     it('should NOT include --dangerously-skip-permissions by default', async () => {
       const mockProc = createMockPtyProcess();