rafcode 1.2.0 → 2.0.0

package/src/core/claude-runner.ts

@@ -1,7 +1,10 @@
+import * as fs from 'node:fs';
 import * as pty from 'node-pty';
 import type { IDisposable } from 'node-pty';
 import { execSync, spawn } from 'node:child_process';
 import { logger } from '../utils/logger.js';
+import { renderStreamEvent } from '../parsers/stream-renderer.js';
+import { getHeadCommitHash, getHeadCommitMessage, isFileCommittedInHead } from './git.js';
 
 function getClaudePath(): string {
   try {
@@ -26,6 +29,27 @@ export interface ClaudeRunnerOptions {
    * Claude will still ask planning interview questions.
    */
   dangerouslySkipPermissions?: boolean;
+  /**
+   * Path to the outcome file. When provided, enables completion detection:
+   * - Monitors stdout for completion markers (<promise>COMPLETE/FAILED</promise>)
+   * - Polls the outcome file for completion markers
+   * When detected, starts a grace period before terminating the process,
+   * allowing time for git commit operations to complete.
+   */
+  outcomeFilePath?: string;
+  /**
+   * Commit verification context. When provided, the grace period will verify
+   * that the expected git commit has been made before terminating.
+   * Only applies when a COMPLETE marker is detected (not FAILED).
+   */
+  commitContext?: {
+    /** HEAD commit hash recorded before task execution began. */
+    preExecutionHead: string;
+    /** Expected commit message prefix (e.g., "RAF[005:01]"). */
+    expectedPrefix: string;
+    /** Path to the outcome file that should be committed. */
+    outcomeFilePath: string;
+  };
 }
 
 export interface ClaudeRunnerConfig {
@@ -50,6 +74,180 @@ const CONTEXT_OVERFLOW_PATTERNS = [
   /context window/i,
 ];
 
+const COMPLETION_MARKER_PATTERN = /<promise>(COMPLETE|FAILED)<\/promise>/i;
+
+/**
+ * Grace period in ms after completion marker is detected before terminating.
+ * Allows time for git commit operations to complete.
+ */
+export const COMPLETION_GRACE_PERIOD_MS = 60_000;
+
+/**
+ * Hard maximum grace period in ms. If the commit hasn't landed by this point,
+ * the process is killed regardless.
+ */
+export const COMPLETION_HARD_MAX_MS = 180_000;
+
+/**
+ * Interval in ms for polling commit verification after the initial grace period expires.
+ */
+export const COMMIT_POLL_INTERVAL_MS = 10_000;
+
+/**
+ * Interval in ms for polling the outcome file for completion markers.
+ */
+export const OUTCOME_POLL_INTERVAL_MS = 5_000;
+
+/**
+ * Context for commit verification during grace period.
+ */
+export interface CommitContext {
+  /** HEAD commit hash recorded before task execution began. */
+  preExecutionHead: string;
+  /** Expected commit message prefix (e.g., "RAF[005:01]"). */
+  expectedPrefix: string;
+  /** Path to the outcome file that should be committed. */
+  outcomeFilePath: string;
+}
+
+/**
+ * Monitors for task completion markers in stdout and outcome files.
+ * When a marker is detected, starts a grace period before killing the process.
+ */
+interface CompletionDetector {
+  /** Check accumulated stdout output for completion markers. */
+  checkOutput(output: string): void;
+  /** Clean up all timers. Must be called when the process exits. */
+  cleanup(): void;
+}
+
+const COMPLETE_MARKER_PATTERN = /<promise>COMPLETE<\/promise>/i;
+
+/**
+ * Verify that the expected commit has been made.
+ * Checks: HEAD changed, commit message matches prefix, outcome file is committed.
+ */
+function verifyCommit(commitContext: CommitContext): boolean {
+  const currentHead = getHeadCommitHash();
+  if (!currentHead || currentHead === commitContext.preExecutionHead) {
+    return false;
+  }
+
+  const message = getHeadCommitMessage();
+  if (!message || !message.startsWith(commitContext.expectedPrefix)) {
+    return false;
+  }
+
+  if (!isFileCommittedInHead(commitContext.outcomeFilePath)) {
+    return false;
+  }
+
+  return true;
+}
+
+function createCompletionDetector(
+  killFn: () => void,
+  outcomeFilePath?: string,
+  commitContext?: CommitContext,
+): CompletionDetector {
+  let graceHandle: ReturnType<typeof setTimeout> | null = null;
+  let commitPollHandle: ReturnType<typeof setInterval> | null = null;
+  let hardMaxHandle: ReturnType<typeof setTimeout> | null = null;
+  let pollHandle: ReturnType<typeof setInterval> | null = null;
+  let initialMtime = 0;
+  let detectedMarkerIsComplete = false;
+
+  // Record initial mtime of outcome file to avoid false positives from previous runs
+  if (outcomeFilePath) {
+    try {
+      if (fs.existsSync(outcomeFilePath)) {
+        initialMtime = fs.statSync(outcomeFilePath).mtimeMs;
+      }
+    } catch {
+      // Ignore stat errors
+    }
+  }
+
+  /**
+   * Called when the initial grace period expires.
+   * If commit verification is needed and the commit hasn't landed yet,
+   * start polling for the commit up to the hard maximum.
+   */
+  function onGracePeriodExpired(): void {
+    if (commitContext && detectedMarkerIsComplete) {
+      // Check if commit already landed
+      if (verifyCommit(commitContext)) {
+        logger.debug('Grace period expired - commit verified, terminating Claude process');
+        killFn();
+        return;
+      }
+
+      // Commit not found yet - extend with polling
+      logger.debug('Grace period expired but commit not verified - extending with polling');
+      const remainingMs = COMPLETION_HARD_MAX_MS - COMPLETION_GRACE_PERIOD_MS;
+
+      hardMaxHandle = setTimeout(() => {
+        logger.warn('Hard maximum grace period reached without commit verification - terminating Claude process');
+        if (commitPollHandle) clearInterval(commitPollHandle);
+        killFn();
+      }, remainingMs);
+
+      commitPollHandle = setInterval(() => {
+        if (commitContext && verifyCommit(commitContext)) {
+          logger.debug('Commit verified during extended grace period - terminating Claude process');
+          if (commitPollHandle) clearInterval(commitPollHandle);
+          if (hardMaxHandle) clearTimeout(hardMaxHandle);
+          killFn();
+        }
+      }, COMMIT_POLL_INTERVAL_MS);
+    } else {
+      // No commit verification needed (FAILED marker or no context) - kill immediately
+      logger.debug('Grace period expired - terminating Claude process');
+      killFn();
+    }
+  }
+
+  function startGracePeriod(markerOutput: string): void {
+    if (graceHandle) return; // Already started
+    detectedMarkerIsComplete = COMPLETE_MARKER_PATTERN.test(markerOutput);
+    logger.debug('Completion marker detected - starting grace period before termination');
+    graceHandle = setTimeout(onGracePeriodExpired, COMPLETION_GRACE_PERIOD_MS);
+  }
+
+  function checkOutput(output: string): void {
+    if (!graceHandle && COMPLETION_MARKER_PATTERN.test(output)) {
+      startGracePeriod(output);
+    }
+  }
+
+  // Start outcome file polling if path provided
+  if (outcomeFilePath) {
+    const filePath = outcomeFilePath;
+    pollHandle = setInterval(() => {
+      try {
+        if (!fs.existsSync(filePath)) return;
+        const stat = fs.statSync(filePath);
+        if (stat.mtimeMs <= initialMtime) return; // File unchanged from before execution
+        const content = fs.readFileSync(filePath, 'utf-8');
+        if (COMPLETION_MARKER_PATTERN.test(content)) {
+          startGracePeriod(content);
+        }
+      } catch {
+        // Ignore read errors - file may be mid-write
+      }
+    }, OUTCOME_POLL_INTERVAL_MS);
+  }
+
+  function cleanup(): void {
+    if (graceHandle) clearTimeout(graceHandle);
+    if (pollHandle) clearInterval(pollHandle);
+    if (commitPollHandle) clearInterval(commitPollHandle);
+    if (hardMaxHandle) clearTimeout(hardMaxHandle);
+  }
+
+  return { checkOutput, cleanup };
+}
+
 export class ClaudeRunner {
   private activeProcess: pty.IPty | null = null;
   private killed = false;
@@ -169,7 +367,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() } = options;
+    const { timeout = 60, cwd = process.cwd(), outcomeFilePath, commitContext } = options;
     // Ensure timeout is a positive number, fallback to 60 minutes
     const validatedTimeout = Number(timeout) > 0 ? Number(timeout) : 60;
     const timeoutMs = validatedTimeout * 60 * 1000;
@@ -213,11 +411,21 @@ export class ClaudeRunner {
         proc.kill('SIGTERM');
       }, timeoutMs);
 
+      // Set up completion detection (stdout marker + outcome file polling)
+      const completionDetector = createCompletionDetector(
+        () => proc.kill('SIGTERM'),
+        outcomeFilePath,
+        commitContext,
+      );
+
       // Collect stdout
       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)) {
@@ -236,6 +444,7 @@ export class ClaudeRunner {
 
       proc.on('close', (exitCode) => {
         clearTimeout(timeoutHandle);
+        completionDetector.cleanup();
         this.activeProcess = null;
 
         if (stderr) {
@@ -254,7 +463,8 @@ export class ClaudeRunner {
 
   /**
    * Run Claude non-interactively with verbose output to stdout.
-   * Uses child_process.spawn with -p flag for prompt (like ralphy).
+   * Uses --output-format stream-json --verbose to get real-time streaming
+   * of tool calls, file operations, and thinking steps.
    *
    * TIMEOUT BEHAVIOR:
    * - The timeout is applied per individual call to this method
@@ -264,7 +474,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() } = options;
+    const { timeout = 60, cwd = process.cwd(), outcomeFilePath, commitContext } = options;
     // Ensure timeout is a positive number, fallback to 60 minutes
     const validatedTimeout = Number(timeout) > 0 ? Number(timeout) : 60;
     const timeoutMs = validatedTimeout * 60 * 1000;
@@ -277,13 +487,13 @@ export class ClaudeRunner {
 
       const claudePath = getClaudePath();
 
-      logger.debug(`Starting Claude execution session (verbose) with model: ${this.model}`);
+      logger.debug(`Starting Claude execution session (verbose/stream-json) with model: ${this.model}`);
       logger.debug(`Prompt length: ${prompt.length}, timeout: ${timeoutMs}ms, cwd: ${cwd}`);
       logger.debug(`Claude path: ${claudePath}`);
 
       logger.debug('Spawning process...');
-      // Use --append-system-prompt to add RAF instructions to system prompt
-      // This gives RAF instructions stronger precedence than passing as user message
+      // Use --output-format stream-json --verbose to get real-time streaming events
+      // including tool calls, file operations, and intermediate output.
       // --dangerously-skip-permissions bypasses interactive prompts
       // -p enables print mode (non-interactive)
       const proc = spawn(claudePath, [
@@ -292,6 +502,9 @@ export class ClaudeRunner {
         this.model,
         '--append-system-prompt',
         prompt,
+        '--output-format',
+        'stream-json',
+        '--verbose',
         '-p',
         'Execute the task as described in the system prompt.',
       ], {
@@ -311,24 +524,52 @@ export class ClaudeRunner {
         proc.kill('SIGTERM');
       }, timeoutMs);
 
-      // Collect and display stdout
+      // Set up completion detection (stdout marker + outcome file polling)
+      const completionDetector = createCompletionDetector(
+        () => proc.kill('SIGTERM'),
+        outcomeFilePath,
+        commitContext,
+      );
+
+      // Buffer for incomplete NDJSON lines (data chunks may split across line boundaries)
+      let lineBuffer = '';
       let dataReceived = false;
+
       proc.stdout.on('data', (data) => {
         if (!dataReceived) {
           logger.debug('First data chunk received');
           dataReceived = true;
         }
-        const text = data.toString();
-        output += text;
-        process.stdout.write(text);
 
-        // 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 { display, textContent } = renderStreamEvent(line);
+
+          if (textContent) {
+            output += 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)) {
+                contextOverflow = true;
+                logger.warn('Context overflow detected');
+                proc.kill('SIGTERM');
+                break;
+              }
+            }
+          }
+
+          if (display) {
+            process.stdout.write(display);
           }
         }
       });
@@ -339,7 +580,19 @@ 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;
+          }
+          if (display) {
+            process.stdout.write(display);
+          }
+        }
+
         clearTimeout(timeoutHandle);
+        completionDetector.cleanup();
         this.activeProcess = null;
         logger.debug(`Claude exited with code ${exitCode}, output length: ${output.length}, timedOut: ${timedOut}, contextOverflow: ${contextOverflow}`);
 

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) {
@@ -167,16 +168,67 @@ 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(cwd?: string): string | null {
+  try {
+    return execSync('git rev-parse HEAD', { encoding: 'utf-8', stdio: 'pipe', ...(cwd ? { cwd } : {}) }).trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Get the current HEAD commit message (first line only).
+ * Returns null if not in a git repo or HEAD doesn't exist.
+ */
+export function getHeadCommitMessage(): string | null {
+  try {
+    return execSync('git log -1 --format=%s', { encoding: 'utf-8', stdio: 'pipe' }).trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Check if a file is tracked in the HEAD commit.
+ * Returns true if the file appears in the latest commit's tree.
+ */
+export function isFileCommittedInHead(filePath: string): boolean {
+  try {
+    // Use git ls-tree to check if the file exists in HEAD
+    // We need the path relative to the repo root
+    const repoRoot = execSync('git rev-parse --show-toplevel', { encoding: 'utf-8', stdio: 'pipe' }).trim();
+    const relativePath = path.relative(repoRoot, path.resolve(filePath));
+    const result = execSync(`git ls-tree HEAD -- "${relativePath.replace(/"/g, '\\"')}"`, {
+      encoding: 'utf-8',
+      stdio: 'pipe',
+    }).trim();
+    return result.length > 0;
+  } catch {
+    return false;
+  }
+}
+
 /**
  * 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;
   }
@@ -190,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) {
@@ -220,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 });