rafcode 1.3.2 → 2.1.0

package/src/core/claude-runner.ts

@@ -45,11 +45,17 @@ export interface ClaudeRunnerOptions {
   commitContext?: {
     /** HEAD commit hash recorded before task execution began. */
     preExecutionHead: string;
-    /** Expected commit message prefix (e.g., "RAF[005:001]"). */
+    /** Expected commit message prefix (e.g., "RAF[005:01]"). */
     expectedPrefix: string;
     /** 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 = [
@@ -104,7 +111,7 @@ export const OUTCOME_POLL_INTERVAL_MS = 5_000;
 export interface CommitContext {
   /** HEAD commit hash recorded before task execution began. */
   preExecutionHead: string;
-  /** Expected commit message prefix (e.g., "RAF[005:001]"). */
+  /** Expected commit message prefix (e.g., "RAF[005:01]"). */
   expectedPrefix: string;
   /** Path to the outcome file that should be committed. */
   outcomeFilePath: string;
@@ -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/git.ts

@@ -12,9 +12,9 @@ export interface GitStatus {
 /**
  * Check if we're in a git repository.
  */
-export function isGitRepo(): boolean {
+export function isGitRepo(cwd?: string): boolean {
   try {
-    execSync('git rev-parse --is-inside-work-tree', { encoding: 'utf-8', stdio: 'pipe' });
+    execSync('git rev-parse --is-inside-work-tree', { encoding: 'utf-8', stdio: 'pipe', ...(cwd ? { cwd } : {}) });
     return true;
   } catch {
     return false;
@@ -58,9 +58,9 @@ export function getGitStatus(): GitStatus {
 /**
  * Check if there are uncommitted changes.
  */
-export function hasUncommittedChanges(): boolean {
+export function hasUncommittedChanges(cwd?: string): boolean {
   try {
-    const status = execSync('git status --porcelain', { encoding: 'utf-8', stdio: 'pipe' });
+    const status = execSync('git status --porcelain', { encoding: 'utf-8', stdio: 'pipe', ...(cwd ? { cwd } : {}) });
     return status.trim().length > 0;
   } catch {
     return false;
@@ -141,16 +141,16 @@ export function getChangedFiles(): string[] {
 
 /**
  * Stash uncommitted changes with a descriptive name.
- * @param name - Name for the stash (e.g., "raf-001-task-3-failed")
+ * @param name - Name for the stash (e.g., "raf-001-task-03-failed")
  * @returns true if stash was created, false otherwise
  */
-export function stashChanges(name: string): boolean {
-  if (!isGitRepo()) {
+export function stashChanges(name: string, cwd?: string): boolean {
+  if (!isGitRepo(cwd)) {
     logger.warn('Not in a git repository, skipping stash');
     return false;
   }
 
-  if (!hasUncommittedChanges()) {
+  if (!hasUncommittedChanges(cwd)) {
     logger.debug('No uncommitted changes to stash');
     return false;
   }
@@ -159,6 +159,7 @@ export function stashChanges(name: string): boolean {
     execSync(`git stash push -m "${name.replace(/"/g, '\\"')}"`, {
       encoding: 'utf-8',
       stdio: 'pipe',
+      ...(cwd ? { cwd } : {}),
     });
     return true;
   } catch (error) {
@@ -171,9 +172,9 @@ export function stashChanges(name: string): boolean {
  * Get the current HEAD commit hash.
  * Returns null if not in a git repo or HEAD doesn't exist.
  */
-export function getHeadCommitHash(): string | null {
+export function getHeadCommitHash(cwd?: string): string | null {
   try {
-    return execSync('git rev-parse HEAD', { encoding: 'utf-8', stdio: 'pipe' }).trim() || null;
+    return execSync('git rev-parse HEAD', { encoding: 'utf-8', stdio: 'pipe', ...(cwd ? { cwd } : {}) }).trim() || null;
   } catch {
     return null;
   }
@@ -214,13 +215,20 @@ export function isFileCommittedInHead(filePath: string): boolean {
 /**
  * Commit planning artifacts (input.md and decisions.md) for a project.
  * Uses commit message format: RAF[NNN] Plan: project-name
+ * For amendments: RAF[NNN] Amend: project-name
  *
  * @param projectPath - Full path to the project folder (e.g., /path/to/RAF/017-decision-vault)
+ * @param options - Optional settings
+ * @param options.cwd - Working directory for git commands (worktree support)
+ * @param options.additionalFiles - Extra file paths to stage (e.g., plan files for amend)
+ * @param options.isAmend - Use "Amend:" prefix instead of "Plan:" in commit message
  * @returns Promise that resolves when commit is complete (or fails silently)
  */
-export async function commitPlanningArtifacts(projectPath: string): Promise<void> {
+export async function commitPlanningArtifacts(projectPath: string, options?: { cwd?: string; additionalFiles?: string[]; isAmend?: boolean }): Promise<void> {
+  const execCwd = options?.cwd;
+
   // Check if we're in a git repository
-  if (!isGitRepo()) {
+  if (!isGitRepo(execCwd)) {
     logger.warn('Not in a git repository, skipping planning artifacts commit');
     return;
   }
@@ -234,25 +242,52 @@ export async function commitPlanningArtifacts(projectPath: string): Promise<void
     return;
   }
 
-  // Build file paths relative to the project folder
+  // Build absolute file paths
   const inputFile = path.join(projectPath, 'input.md');
   const decisionsFile = path.join(projectPath, 'decisions.md');
 
   // Build commit message
-  const commitMessage = `RAF[${projectNumber}] Plan: ${projectName}`;
+  const prefix = options?.isAmend ? 'Amend' : 'Plan';
+  const commitMessage = `RAF[${projectNumber}] ${prefix}: ${projectName}`;
+
+  // Build list of files to stage (absolute paths)
+  const absoluteFiles = [inputFile, decisionsFile, ...(options?.additionalFiles ?? [])];
+
+  // Convert to relative paths when cwd is provided (worktree mode).
+  // Git resolves paths relative to the working directory. Using relative paths
+  // avoids issues with symlink resolution (e.g., /tmp → /private/tmp on macOS)
+  // that can cause absolute paths to not match git's internal worktree paths.
+  const filesToStage = execCwd
+    ? absoluteFiles.map(f => path.relative(execCwd, f))
+    : absoluteFiles;
+
+  // Stage each file individually so one missing file doesn't block the others
+  let stagedCount = 0;
+  for (const file of filesToStage) {
+    try {
+      execSync(`git add -- "${file}"`, {
+        encoding: 'utf-8',
+        stdio: 'pipe',
+        ...(execCwd ? { cwd: execCwd } : {}),
+      });
+      stagedCount++;
+    } catch (error) {
+      const msg = error instanceof Error ? error.message : String(error);
+      logger.warn(`Failed to stage ${file}: ${msg}`);
+    }
+  }
 
-  try {
-    // Stage only the specific files (input.md and decisions.md)
-    // Use --force to add even if in .gitignore, and -- to handle paths with special chars
-    execSync(`git add -- "${inputFile}" "${decisionsFile}"`, {
-      encoding: 'utf-8',
-      stdio: 'pipe',
-    });
+  if (stagedCount === 0) {
+    logger.debug('No files were staged for planning artifacts commit');
+    return;
+  }
 
+  try {
     // Check if there's anything staged to commit
     const stagedStatus = execSync('git diff --cached --name-only', {
       encoding: 'utf-8',
       stdio: 'pipe',
+      ...(execCwd ? { cwd: execCwd } : {}),
     }).trim();
 
     if (!stagedStatus) {
@@ -264,6 +299,7 @@ export async function commitPlanningArtifacts(projectPath: string): Promise<void
     execSync(`git commit -m "${commitMessage.replace(/"/g, '\\"')}"`, {
       encoding: 'utf-8',
       stdio: 'pipe',
+      ...(execCwd ? { cwd: execCwd } : {}),
     });
 
     logger.debug(`Committed planning artifacts: ${commitMessage}`);

package/src/core/project-manager.ts

@@ -11,6 +11,7 @@ import {
   getDecisionsPath,
   getInputPath,
   listProjects,
+  TASK_ID_PATTERN,
 } from '../utils/paths.js';
 import { sanitizeProjectName } from '../utils/validation.js';
 import { logger } from '../utils/logger.js';
@@ -145,7 +146,7 @@ export class ProjectManager {
     const files = fs.readdirSync(outcomesDir).filter((f) => f.endsWith('.md')).sort();
 
     for (const file of files) {
-      const match = file.match(/^(\d{2,3})-/);
+      const match = file.match(new RegExp(`^(${TASK_ID_PATTERN})-`));
       if (match && match[1]) {
         const content = fs.readFileSync(path.join(outcomesDir, file), 'utf-8');
         outcomes.push({ taskId: match[1], content });