rafcode 2.5.1 → 3.2.1

package/src/core/runner-factory.ts

@@ -0,0 +1,35 @@
+import type { HarnessProvider } from '../types/config.js';
+import type { ICliRunner } from './runner-interface.js';
+import type { RunnerConfig } from './runner-types.js';
+import { ClaudeRunner } from './claude-runner.js';
+import { CodexRunner } from './codex-runner.js';
+
+/**
+ * Create a CLI runner for the given provider configuration.
+ */
+export function createRunner(config: RunnerConfig = {}): ICliRunner {
+  const provider = config.provider ?? 'claude';
+
+  switch (provider) {
+    case 'claude':
+      return new ClaudeRunner(config);
+    case 'codex':
+      return new CodexRunner(config);
+    default:
+      throw new Error(`Unknown provider: ${provider}`);
+  }
+}
+
+/**
+ * Get the binary name for a given provider.
+ */
+export function getProviderBinaryName(provider: HarnessProvider): string {
+  switch (provider) {
+    case 'claude':
+      return 'claude';
+    case 'codex':
+      return 'codex';
+    default:
+      throw new Error(`Unknown provider: ${provider}`);
+  }
+}

package/src/core/runner-interface.ts

@@ -0,0 +1,14 @@
+import type { RunnerOptions, RunResult } from './runner-types.js';
+
+/**
+ * Provider-agnostic CLI runner interface.
+ * Both ClaudeRunner and CodexRunner implement this interface.
+ */
+export interface ICliRunner {
+  runInteractive(systemPrompt: string, userMessage: string, options?: RunnerOptions): Promise<number>;
+  runResume(options?: RunnerOptions): Promise<number>;
+  run(prompt: string, options?: RunnerOptions): Promise<RunResult>;
+  runVerbose(prompt: string, options?: RunnerOptions): Promise<RunResult>;
+  kill(): void;
+  isRunning(): boolean;
+}

package/src/core/runner-types.ts

@@ -0,0 +1,75 @@
+import type { UsageData, HarnessProvider } from '../types/config.js';
+
+/**
+ * Options for a single runner execution (run, runVerbose, runInteractive, etc.).
+ */
+export interface RunnerOptions {
+  /**
+   * Timeout in minutes for this single execution.
+   * Default: 60 minutes.
+   * Each call to run() or runVerbose() gets its own fresh timeout.
+   * Retries get a fresh timeout - elapsed time is NOT accumulated across attempts.
+   */
+  timeout?: number;
+  cwd?: string;
+  /**
+   * Skip permission prompts for file operations.
+   * Only used in interactive mode (runInteractive).
+   */
+  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;
+  };
+  /**
+   * Dynamic verbose display callback. When provided, called for each stream event
+   * to determine whether to write display output to stdout. Overrides the static
+   * verbose parameter in _runStreamJson. Used by the runtime verbose toggle.
+   */
+  verboseCheck?: () => boolean;
+}
+
+/**
+ * Configuration for creating a runner instance.
+ */
+export interface RunnerConfig {
+  /**
+   * Model to use (e.g., opus, sonnet, haiku, gpt-5.4).
+   * Default: provider-specific default.
+   */
+  model?: string;
+  /**
+   * CLI provider to use.
+   * Default: 'claude'.
+   */
+  provider?: HarnessProvider;
+}
+
+/**
+ * Result of a non-interactive runner execution.
+ */
+export interface RunResult {
+  output: string;
+  exitCode: number;
+  timedOut: boolean;
+  contextOverflow: boolean;
+  /** Token usage data from the stream-json result event. */
+  usageData?: UsageData;
+}

package/src/core/shutdown-handler.ts

@@ -1,18 +1,25 @@
-import { ClaudeRunner } from './claude-runner.js';
+import type { ICliRunner } from './runner-interface.js';
 import { logger } from '../utils/logger.js';
 
 type CleanupCallback = () => void | Promise<void>;
 
 class ShutdownHandler {
-  private claudeRunner: ClaudeRunner | null = null;
+  private runner: ICliRunner | null = null;
   private cleanupCallbacks: CleanupCallback[] = [];
   private isShuttingDown = false;
 
   /**
-   * Register a Claude runner to be killed on shutdown.
+   * Register a CLI runner to be killed on shutdown.
    */
-  registerClaudeRunner(runner: ClaudeRunner): void {
-    this.claudeRunner = runner;
+  registerRunner(runner: ICliRunner): void {
+    this.runner = runner;
+  }
+
+  /**
+   * @deprecated Use registerRunner instead.
+   */
+  registerClaudeRunner(runner: ICliRunner): void {
+    this.registerRunner(runner);
   }
 
   /**
@@ -54,10 +61,10 @@ class ShutdownHandler {
     this.isShuttingDown = true;
     logger.info(`\nReceived ${signal}, shutting down gracefully...`);
 
-    // Kill Claude process if running
-    if (this.claudeRunner?.isRunning()) {
-      logger.debug('Killing Claude process...');
-      this.claudeRunner.kill();
+    // Kill runner process if running
+    if (this.runner?.isRunning()) {
+      logger.debug('Killing runner process...');
+      this.runner.kill();
     }
 
     // Run cleanup callbacks
@@ -85,7 +92,7 @@ class ShutdownHandler {
    * Clear registrations (useful for testing).
    */
   clear(): void {
-    this.claudeRunner = null;
+    this.runner = null;
     this.cleanupCallbacks = [];
   }
 }

package/src/core/state-derivation.ts

@@ -1,6 +1,6 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
-import { getPlansDir, getOutcomesDir, getInputPath, decodeBase26, TASK_ID_PATTERN } from '../utils/paths.js';
+import { getPlansDir, getOutcomesDir, getInputPath, TASK_ID_PATTERN, numericFileSort } from '../utils/paths.js';
 import { parsePlanFrontmatter, type PlanFrontmatter } from '../utils/frontmatter.js';
 
 export type DerivedTaskStatus = 'pending' | 'completed' | 'failed' | 'blocked';
@@ -44,7 +44,7 @@ export interface DerivedStats {
 
 /**
  * Discover all projects in the RAF directory.
- * Projects are directories matching the pattern XXXXXX-project-name (6-char base26 prefix).
+ * Projects are directories matching the pattern N-project-name (numeric prefix).
  */
 export function discoverProjects(rafDir: string): DiscoveredProject[] {
   if (!fs.existsSync(rafDir)) {
@@ -56,16 +56,13 @@ export function discoverProjects(rafDir: string): DiscoveredProject[] {
 
   for (const entry of entries) {
     if (entry.isDirectory()) {
-      const match = entry.name.match(/^([a-z]{6})-(.+)$/i);
+      const match = entry.name.match(/^(\d+)-(.+)$/);
       if (match && match[1] && match[2]) {
-        const decoded = decodeBase26(match[1].toLowerCase());
-        if (decoded !== null) {
-          projects.push({
-            number: decoded,
-            name: match[2],
-            path: path.join(rafDir, entry.name),
-          });
-        }
+        projects.push({
+          number: parseInt(match[1], 10),
+          name: match[2],
+          path: path.join(rafDir, entry.name),
+        });
       }
     }
   }
@@ -89,7 +86,7 @@ export function parseDependencies(content: string): string[] {
     return [];
   }
 
-  // Parse comma-separated task IDs (2-char base36)
+  // Parse comma-separated numeric task IDs
   const taskIdRegex = new RegExp(`^${TASK_ID_PATTERN}$`);
   return dependenciesLine
     .split(',')
@@ -184,7 +181,7 @@ export function deriveProjectStatus(
 /**
  * Derive project state from the folder structure.
  * Scans plans/ for plan files and outcomes/ for outcome files.
- * Matches them by task ID (2-char base36 prefix for tasks) and determines status.
+ * Matches them by task ID (numeric prefix for tasks) and determines status.
  * Also parses dependencies and derives blocked status.
  */
 export function deriveProjectState(projectPath: string): DerivedProjectState {
@@ -201,14 +198,14 @@ export function deriveProjectState(projectPath: string): DerivedProjectState {
 
   const planFiles = fs.readdirSync(plansDir)
     .filter((f) => f.endsWith('.md'))
-    .sort();
+    .sort(numericFileSort);
 
   // Build a map of outcome statuses
   const outcomeStatuses = new Map<string, DerivedTaskStatus>();
   if (fs.existsSync(outcomesDir)) {
     const outcomeFiles = fs.readdirSync(outcomesDir)
       .filter((f) => f.endsWith('.md'))
-      .sort();
+      .sort(numericFileSort);
 
     for (const outcomeFile of outcomeFiles) {
       const match = outcomeFile.match(new RegExp(`^(${TASK_ID_PATTERN})-`));

package/src/core/worktree.ts

@@ -3,7 +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';
+import { extractProjectNumber, extractProjectName, parseProjectPrefix } from '../utils/paths.js';
 
 export interface WorktreeCreateResult {
   success: boolean;
@@ -368,7 +368,7 @@ export interface WorktreeProjectResolution {
  * 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)
+ * 2. Numeric prefix match (e.g., "3" matches "3-auth-system")
  * 3. Project name match (the portion after the prefix)
  *
  * @param repoBasename - The basename of the current git repo
@@ -394,20 +394,18 @@ export function resolveWorktreeProjectByIdentifier(
     }
   }
 
-  // 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),
-            };
-          }
+  // 2. Numeric prefix match
+  const targetNumber = parseProjectPrefix(identifier);
+  if (targetNumber !== null) {
+    for (const dir of wtProjectDirs) {
+      const prefix = extractProjectNumber(dir);
+      if (prefix) {
+        const dirNumber = parseProjectPrefix(prefix);
+        if (dirNumber === targetNumber) {
+          return {
+            folder: dir,
+            worktreeRoot: computeWorktreePath(repoBasename, dir),
+          };
         }
       }
     }

package/src/index.ts

@@ -11,7 +11,7 @@ const program = new Command();
 
 program
   .name('raf')
-  .description('RAF - Automated Task Planning & Execution with Claude Code')
+  .description('RAF - Automated Task Planning & Execution')
   .version(getVersion());
 
 program.addCommand(createPlanCommand());

package/src/parsers/codex-stream-renderer.ts

@@ -0,0 +1,210 @@
+/**
+ * Renders JSONL events from Codex CLI into human-readable verbose output.
+ *
+ * Codex CLI (`codex exec --json`) emits one JSON object per line with event types:
+ * - AgentMessage: Text content from the agent
+ * - CommandExecution: Shell command execution (command + exit code)
+ * - FileChange: File modification (path + change kind)
+ * - McpToolCall: MCP tool invocation
+ * - TodoList: Task tracking (skipped)
+ */
+
+import type { RenderResult } from './stream-renderer.js';
+
+export interface CodexEvent {
+  type: string;
+  /** Claude flat-format fields (AgentMessage) */
+  content?: string;
+  /** Claude flat-format fields (CommandExecution) */
+  command?: string;
+  exit_code?: number;
+  /** Claude flat-format fields (FileChange) */
+  file_path?: string;
+  change_kind?: string;
+  /** Claude flat-format fields (McpToolCall) */
+  tool_name?: string;
+  server_name?: string;
+  /** Real Codex nested item (for item.completed / item.started) */
+  item?: {
+    type: string;
+    text?: string;
+    command?: string;
+    exit_code?: number;
+    path?: string;
+    change_kind?: string;
+  };
+  /** Error message (for error / turn.failed events) */
+  message?: string;
+  /** Usage data (for turn.completed events) */
+  usage?: {
+    input_tokens?: number;
+    output_tokens?: number;
+    total_tokens?: number;
+  };
+}
+
+function truncate(text: string, maxLen: number): string {
+  if (text.length <= maxLen) return text;
+  return text.substring(0, maxLen - 3) + '...';
+}
+
+/**
+ * Parse and render a single JSONL line from Codex CLI output.
+ * Returns the same RenderResult interface as Claude's stream renderer.
+ */
+export function renderCodexStreamEvent(line: string): RenderResult {
+  if (!line.trim()) {
+    return { display: '', textContent: '' };
+  }
+
+  let event: CodexEvent;
+  try {
+    event = JSON.parse(line) as CodexEvent;
+  } catch {
+    // Not valid JSON - pass through raw
+    return { display: line + '\n', textContent: line };
+  }
+
+  switch (event.type) {
+    case 'AgentMessage':
+      return renderAgentMessage(event);
+
+    case 'CommandExecution':
+      return renderCommandExecution(event);
+
+    case 'FileChange':
+      return renderFileChange(event);
+
+    case 'McpToolCall':
+      return renderMcpToolCall(event);
+
+    case 'TodoList':
+      // Skip todo list events - minimal noise
+      return { display: '', textContent: '' };
+
+    // Real Codex CLI event types (nested format)
+    case 'item.completed':
+      return renderItemCompleted(event);
+
+    case 'item.started':
+      // Skip started events — we render on completion
+      return { display: '', textContent: '' };
+
+    case 'turn.completed':
+      return renderTurnCompleted(event);
+
+    case 'error':
+      return renderError(event);
+
+    case 'turn.failed':
+      return renderTurnFailed(event);
+
+    default:
+      // Skip unknown event types gracefully
+      return { display: '', textContent: '' };
+  }
+}
+
+function renderAgentMessage(event: CodexEvent): RenderResult {
+  const text = event.content ?? '';
+  return {
+    display: text ? text + '\n' : '',
+    textContent: text,
+  };
+}
+
+function renderCommandExecution(event: CodexEvent): RenderResult {
+  const cmd = event.command ?? '';
+  const exitCode = event.exit_code ?? 0;
+  const status = exitCode === 0 ? '✓' : `✗ exit ${exitCode}`;
+  return {
+    display: `  → Running: ${truncate(cmd, 120)} [${status}]\n`,
+    textContent: '',
+  };
+}
+
+function renderFileChange(event: CodexEvent): RenderResult {
+  const filePath = event.file_path ?? 'unknown';
+  const kind = event.change_kind ?? 'modified';
+  return {
+    display: `  → File ${kind}: ${filePath}\n`,
+    textContent: '',
+  };
+}
+
+function renderMcpToolCall(event: CodexEvent): RenderResult {
+  const tool = event.tool_name ?? 'unknown';
+  const server = event.server_name ? ` (${event.server_name})` : '';
+  return {
+    display: `  → MCP tool: ${tool}${server}\n`,
+    textContent: '',
+  };
+}
+
+// --- Real Codex CLI event handlers (nested format) ---
+
+function renderItemCompleted(event: CodexEvent): RenderResult {
+  const item = event.item;
+  if (!item) return { display: '', textContent: '' };
+
+  switch (item.type) {
+    case 'agent_message': {
+      const text = item.text ?? '';
+      return {
+        display: text ? text + '\n' : '',
+        textContent: text,
+      };
+    }
+    case 'command_execution': {
+      const cmd = item.command ?? '';
+      const exitCode = item.exit_code ?? 0;
+      const status = exitCode === 0 ? '✓' : `✗ exit ${exitCode}`;
+      return {
+        display: `  → Running: ${truncate(cmd, 120)} [${status}]\n`,
+        textContent: '',
+      };
+    }
+    case 'file_change': {
+      const filePath = item.path ?? 'unknown';
+      const kind = item.change_kind ?? 'modified';
+      return {
+        display: `  → File ${kind}: ${filePath}\n`,
+        textContent: '',
+      };
+    }
+    default:
+      return { display: '', textContent: '' };
+  }
+}
+
+function renderTurnCompleted(event: CodexEvent): RenderResult {
+  if (event.usage) {
+    const { input_tokens, output_tokens } = event.usage;
+    const parts: string[] = [];
+    if (input_tokens) parts.push(`in: ${input_tokens}`);
+    if (output_tokens) parts.push(`out: ${output_tokens}`);
+    if (parts.length > 0) {
+      return {
+        display: `  → Usage: ${parts.join(', ')}\n`,
+        textContent: '',
+      };
+    }
+  }
+  return { display: '', textContent: '' };
+}
+
+function renderError(event: CodexEvent): RenderResult {
+  const msg = event.message ?? 'Unknown error';
+  return {
+    display: `  ✗ Error: ${msg}\n`,
+    textContent: msg,
+  };
+}
+
+function renderTurnFailed(event: CodexEvent): RenderResult {
+  const msg = event.message ?? 'Turn failed';
+  return {
+    display: `  ✗ Failed: ${msg}\n`,
+    textContent: msg,
+  };
+}

package/src/parsers/output-parser.ts

@@ -19,7 +19,7 @@ const CONTEXT_OVERFLOW_PATTERNS = [
 ];
 
 /**
- * Parse Claude's output to determine task result.
+ * Parse the LLM's output to determine task result.
  */
 export function parseOutput(output: string): ParsedOutput {
   const result: ParsedOutput = {
@@ -120,7 +120,7 @@ export function isRetryableFailure(parsed: ParsedOutput): boolean {
 }
 
 /**
- * Extract a summary from Claude's output for the outcome file.
+ * Extract a summary from the LLM's output for the outcome file.
  */
 export function extractSummary(output: string): string {
   // Remove ANSI codes

package/src/parsers/stream-renderer.ts

@@ -3,7 +3,7 @@
  *
  * Event types from `claude -p --output-format stream-json --verbose`:
  * - system (init): Session initialization info
- * - assistant: Claude's response with text or tool_use content blocks
+ * - assistant: LLM response with text or tool_use content blocks
  * - user: Tool results (tool_result content blocks)
  * - result: Final result with success/failure status and token usage
  */

package/src/prompts/amend.ts

@@ -6,7 +6,6 @@ export interface AmendPromptParams {
   existingTasks: Array<DerivedTask & { taskName: string }>;
   nextTaskNumber: number;
   newTaskDescription: string;
-  worktreeMode?: boolean;
 }
 
 export interface AmendPromptResult {
@@ -17,7 +16,7 @@ export interface AmendPromptResult {
 /**
  * Generate a prompt for amending an existing project with new tasks.
  * - systemPrompt: Amendment mode conventions, existing tasks context (via --append-system-prompt)
- * - userMessage: Reference to input.md and new task description (via positional argument, triggers Claude to start)
+ * - userMessage: Reference to input.md and new task description (via positional argument, triggers the LLM to start)
  */
 export function getAmendPrompt(params: AmendPromptParams): AmendPromptResult {
   const {
@@ -25,9 +24,7 @@ export function getAmendPrompt(params: AmendPromptParams): AmendPromptResult {
     existingTasks,
     nextTaskNumber,
     newTaskDescription,
-    worktreeMode,
   } = params;
-  const worktreeFlag = worktreeMode ? ' --worktree' : '';
 
   const existingTasksSummary = existingTasks
     .map((task) => {
@@ -153,7 +150,7 @@ effort: medium
 
 ## Dependencies
 [Optional section - omit if task has no dependencies]
-[Comma-separated list of task IDs this task depends on, e.g., "01, 02"]
+[Comma-separated list of task IDs this task depends on, e.g., "1, 2"]
 [If a dependency fails, this task will be automatically blocked]
 
 ## Requirements
@@ -180,7 +177,7 @@ effort: medium
 
 ### Frontmatter Requirements
 
-The \`effort\` field is REQUIRED in every plan file. It indicates task complexity and determines which Claude model will execute the task:
+The \`effort\` field is REQUIRED in every plan file. It indicates task complexity and determines which model will execute the task:
 - \`effort: low\` — Trivial/mechanical changes, simple one-file edits, config changes
 - \`effort: medium\` — Well-scoped feature work, bug fixes with clear plans, multi-file changes following existing patterns
 - \`effort: high\` — Architectural changes, complex logic, tasks requiring deep codebase understanding
@@ -201,8 +198,8 @@ This is rarely needed — prefer using the \`effort\` label so the user's config
 After creating all new plan files:
 1. Provide a summary of:
    - The new tasks you've created, including the effort level for each task. Example format:
-     - Task 02: add-caching (effort: medium)
-     - Task 03: update-docs (effort: low)
+     - Task 2: add-caching (effort: medium)
+     - Task 3: update-docs (effort: low)
    - How they relate to existing tasks
    - Total task count in the project
 2. Display this exit message to the user:
@@ -210,7 +207,7 @@ After creating all new plan files:
 \`\`\`
 Planning complete! To exit this session and run your tasks:
   1. Press Ctrl-C twice to exit
-  2. Then run: raf do <project>${worktreeFlag}
+  2. Then run: raf do <project>
 \`\`\`
 
 ## Important Rules
@@ -221,7 +218,7 @@ Planning complete! To exit this session and run your tasks:
 4. New tasks start from number ${encodeTaskId(nextTaskNumber)}
 5. Use descriptive, kebab-case names for plan files
 6. Each plan should be self-contained with all context needed
-7. Specify task dependencies using the ## Dependencies section with task IDs only (e.g., "01, 02")
+7. Specify task dependencies using the ## Dependencies section with task IDs only (e.g., "1, 2")
 8. Tasks without dependencies should omit the Dependencies section entirely
 9. Be specific - vague plans lead to poor execution
 10. ALWAYS include the \`effort\` frontmatter field in every plan file — assess each task's complexity