rafcode 2.3.0 → 2.4.1-0

package/src/commands/do.ts

@@ -13,7 +13,9 @@ import { getRafDir, extractProjectNumber, extractProjectName, extractTaskNameFro
 import { pickPendingProject, getPendingProjects, getPendingWorktreeProjects } from '../ui/project-picker.js';
 import type { PendingProjectInfo } from '../ui/project-picker.js';
 import { logger } from '../utils/logger.js';
-import { getConfig, getEffort, getWorktreeDefault, getModel, getModelShortName } from '../utils/config.js';
+import { getConfig, getWorktreeDefault, getModel, getModelShortName, resolveFullModelId, getSyncMainBranch, resolveEffortToModel, applyModelCeiling, getShowRateLimitEstimate, getShowCacheTokens } from '../utils/config.js';
+import type { PlanFrontmatter } from '../utils/frontmatter.js';
+import { getVersion } from '../utils/version.js';
 import { createTaskTimer, formatElapsedTime } from '../utils/timer.js';
 import { createStatusLine } from '../utils/status-line.js';
 import {
@@ -49,6 +51,10 @@ import {
   mergeWorktreeBranch,
   removeWorktree,
   resolveWorktreeProjectByIdentifier,
+  pushMainBranch,
+  pullMainBranch,
+  detectMainBranch,
+  rebaseOntoMain,
 } from '../core/worktree.js';
 import { createPullRequest, prPreflight } from '../core/pull-request.js';
 import type { DoCommandOptions } from '../types/config.js';
@@ -61,6 +67,74 @@ import type { DoCommandOptions } from '../types/config.js';
  */
 export type PostExecutionAction = 'merge' | 'pr' | 'leave';
 
+/**
+ * Result of resolving a task's model from frontmatter.
+ */
+interface TaskModelResolution {
+  /** The resolved model (after ceiling is applied). */
+  model: string;
+  /** Whether a warning should be logged about missing frontmatter. */
+  missingFrontmatter: boolean;
+  /** Frontmatter parsing warnings to log. */
+  warnings: string[];
+}
+
+/**
+ * Resolve the execution model for a task from its frontmatter metadata.
+ *
+ * Resolution order:
+ * 1. Explicit `model` in frontmatter (subject to ceiling)
+ * 2. `effort` in frontmatter resolved via effortMapping (subject to ceiling)
+ * 3. Fallback to models.execute (the ceiling, with a warning)
+ *
+ * @param frontmatter - Parsed frontmatter from the plan file
+ * @param frontmatterWarnings - Warnings from frontmatter parsing
+ * @param ceilingModel - The ceiling model (usually models.execute from config)
+ * @param isRetry - Whether this is a retry attempt (escalates to ceiling)
+ */
+function resolveTaskModel(
+  frontmatter: PlanFrontmatter | undefined,
+  frontmatterWarnings: string[] | undefined,
+  ceilingModel: string,
+  isRetry: boolean,
+): TaskModelResolution {
+  const warnings = frontmatterWarnings ? [...frontmatterWarnings] : [];
+
+  // Retry escalation: always use the ceiling model on retry
+  if (isRetry) {
+    return { model: ceilingModel, missingFrontmatter: false, warnings };
+  }
+
+  // No frontmatter - fallback to ceiling with warning
+  if (!frontmatter) {
+    return {
+      model: ceilingModel,
+      missingFrontmatter: true,
+      warnings,
+    };
+  }
+
+  // Explicit model in frontmatter - apply ceiling
+  if (frontmatter.model) {
+    const model = applyModelCeiling(frontmatter.model, ceilingModel);
+    return { model, missingFrontmatter: false, warnings };
+  }
+
+  // Effort-based resolution - apply ceiling
+  if (frontmatter.effort) {
+    const mappedModel = resolveEffortToModel(frontmatter.effort);
+    const model = applyModelCeiling(mappedModel, ceilingModel);
+    return { model, missingFrontmatter: false, warnings };
+  }
+
+  // Frontmatter present but no effort or model - fallback to ceiling with warning
+  return {
+    model: ceilingModel,
+    missingFrontmatter: true,
+    warnings,
+  };
+}
+
 /**
  * Format failure history for console output.
  * Shows attempts that failed before eventual success or final failure.
@@ -152,6 +226,7 @@ async function runDoCommand(projectIdentifierArg: string | undefined, options: D
   // Variables for worktree context (set when --worktree is used)
   let worktreeRoot: string | undefined;
   let originalBranch: string | undefined;
+  let mainBranchName: string | null = null;
 
   if (worktreeMode) {
     // Validate git repo
@@ -166,6 +241,19 @@ async function runDoCommand(projectIdentifierArg: string | undefined, options: D
     // Record original branch before any worktree operations
     originalBranch = getCurrentBranch() ?? undefined;
 
+    // Sync main branch before worktree operations (if enabled)
+    if (getSyncMainBranch()) {
+      const syncResult = pullMainBranch();
+      mainBranchName = syncResult.mainBranch;
+      if (syncResult.success) {
+        if (syncResult.hadChanges) {
+          logger.info(`Synced ${syncResult.mainBranch} from remote`);
+        }
+      } else {
+        logger.warn(`Could not sync main branch: ${syncResult.error}`);
+      }
+    }
+
     if (!projectIdentifier) {
       // Auto-discovery flow
       const selected = await discoverAndPickWorktreeProject(repoBasename, rafDir, rafRelativePath);
@@ -378,6 +466,20 @@ async function runDoCommand(projectIdentifierArg: string | undefined, options: D
       }
       throw error;
     }
+
+    // Rebase worktree branch onto main before execution (if sync is enabled)
+    if (getSyncMainBranch()) {
+      const mainBranch = mainBranchName ?? detectMainBranch();
+      if (mainBranch) {
+        const rebaseResult = rebaseOntoMain(mainBranch, worktreeRoot);
+        if (rebaseResult.success) {
+          logger.info(`Rebased onto ${mainBranch}`);
+        } else {
+          logger.warn(`Could not rebase onto ${mainBranch}: ${rebaseResult.error}`);
+          logger.warn('Continuing with current branch state.');
+        }
+      }
+    }
   }
 
   // Execute project
@@ -394,7 +496,6 @@ async function runDoCommand(projectIdentifierArg: string | undefined, options: D
         force,
         maxRetries,
         autoCommit,
-        showModel: true,
         model,
         worktreeCwd: worktreeRoot,
       }
@@ -500,6 +601,19 @@ async function executePostAction(
 
     case 'pr': {
       logger.newline();
+
+      // Push main branch to remote before PR creation (if enabled)
+      if (getSyncMainBranch()) {
+        const syncResult = pushMainBranch();
+        if (syncResult.success) {
+          if (syncResult.hadChanges) {
+            logger.info(`Pushed ${syncResult.mainBranch} to remote`);
+          }
+        } else {
+          logger.warn(`Could not push main branch: ${syncResult.error}`);
+        }
+      }
+
       logger.info(`Creating PR for branch "${worktreeBranch}"...`);
 
       const prResult = await createPullRequest(worktreeBranch, projectPath, { cwd: worktreeRoot });
@@ -658,7 +772,6 @@ interface SingleProjectOptions {
   force: boolean;
   maxRetries: number;
   autoCommit: boolean;
-  showModel: boolean;
   model: string;
   /** Worktree root directory. When set, Claude runs with cwd in the worktree. */
   worktreeCwd?: string;
@@ -669,7 +782,7 @@ async function executeSingleProject(
   projectName: string,
   options: SingleProjectOptions
 ): Promise<ProjectExecutionResult> {
-  const { timeout, verbose, debug, force, maxRetries, autoCommit, showModel, model, worktreeCwd } = options;
+  const { timeout, verbose, debug, force, maxRetries, autoCommit, model, worktreeCwd } = options;
 
   if (!validatePlansExist(projectPath)) {
     return {
@@ -709,11 +822,12 @@ async function executeSingleProject(
       : state.tasks.filter((t) => t.status !== 'completed').map((t) => t.id)
   );
 
-  // Set up shutdown handler
-  const claudeRunner = new ClaudeRunner({ model });
+  // Set up shutdown handler - we'll register runners dynamically per-task
   const projectManager = new ProjectManager();
   shutdownHandler.init();
-  shutdownHandler.registerClaudeRunner(claudeRunner);
+
+  // The ceiling model for all tasks (can be overridden per-task, subject to this ceiling)
+  const ceilingModel = model;
 
   // Initialize token tracker for usage reporting
   const tokenTracker = new TokenTracker();
@@ -725,15 +839,13 @@ async function executeSingleProject(
   // Start project timer
   const projectStartTime = Date.now();
 
+  // Resolve and display version + ceiling model info (before any tasks run)
+  const fullCeilingModelId = resolveFullModelId(ceilingModel);
+  logger.dim(`RAF v${getVersion()} | Ceiling: ${fullCeilingModelId}`);
+
   if (verbose) {
     logger.info(`Executing project: ${projectName}`);
     logger.info(`Tasks: ${state.tasks.length}, Task timeout: ${timeout} minutes`);
-
-    // Log Claude model name
-    if (showModel && model) {
-      logger.info(`Using model: ${model}`);
-    }
-
     logger.newline();
   } else {
     // Minimal mode: show project header
@@ -923,16 +1035,45 @@ async function executeSingleProject(
     });
     timer.start();
 
+    // Log frontmatter warnings once before the retry loop
+    if (task.frontmatterWarnings && task.frontmatterWarnings.length > 0) {
+      for (const warning of task.frontmatterWarnings) {
+        logger.warn(`  Frontmatter warning: ${warning}`);
+      }
+    }
+
     while (!success && attempts < maxRetries) {
       attempts++;
+      const isRetry = attempts > 1;
+
+      // Resolve the model for this attempt (escalates to ceiling on retry)
+      const modelResolution = resolveTaskModel(
+        task.frontmatter,
+        undefined, // warnings already logged above
+        ceilingModel,
+        isRetry,
+      );
+
+      // Log missing frontmatter warning on first attempt only
+      if (!isRetry && modelResolution.missingFrontmatter) {
+        logger.warn(`  No effort frontmatter found — using ceiling model`);
+      }
+
+      // Create a runner for this attempt's model
+      const taskRunner = new ClaudeRunner({ model: modelResolution.model });
+      shutdownHandler.registerClaudeRunner(taskRunner);
 
-      if (verbose && attempts > 1) {
-        logger.info(`  Retry ${attempts}/${maxRetries} for task ${taskLabel}...`);
+      if (verbose && isRetry) {
+        const retryModel = resolveFullModelId(modelResolution.model);
+        logger.info(`  Retry ${attempts}/${maxRetries} for task ${taskLabel} (model: ${retryModel})...`);
+      } else if (verbose && !isRetry) {
+        const taskModel = resolveFullModelId(modelResolution.model);
+        logger.info(`  Model: ${taskModel}`);
       }
 
       // Build execution prompt (inside loop to include retry context on retries)
       // Check if previous outcome file exists for retry context
-      const previousOutcomeFileForRetry = attempts > 1 && fs.existsSync(outcomeFilePath)
+      const previousOutcomeFileForRetry = isRetry && fs.existsSync(outcomeFilePath)
         ? outcomeFilePath
         : undefined;
 
@@ -961,18 +1102,16 @@ async function executeSingleProject(
       } : undefined;
 
       // Run Claude (use worktree root as cwd if in worktree mode)
-      const executeEffort = getEffort('execute');
       const runnerOptions = {
         timeout,
         outcomeFilePath,
         commitContext,
         cwd: worktreeCwd,
-        effortLevel: executeEffort,
         verboseCheck: () => verboseToggle.isVerbose,
       };
       const result = verbose
-        ? await claudeRunner.runVerbose(prompt, runnerOptions)
-        : await claudeRunner.run(prompt, runnerOptions);
+        ? await taskRunner.runVerbose(prompt, runnerOptions)
+        : await taskRunner.run(prompt, runnerOptions);
 
       lastOutput = result.output;
       if (result.usageData) {
@@ -1096,7 +1235,12 @@ Task completed. No detailed report provided.
       // Track and display token usage for this task
       if (attemptUsageData.length > 0) {
         const entry = tokenTracker.addTask(task.id, attemptUsageData);
-        logger.dim(formatTaskTokenSummary(entry, (u) => tokenTracker.calculateCost(u)));
+        const taskRateLimitPct = tokenTracker.getCumulativeRateLimitPercentage();
+        logger.dim(formatTaskTokenSummary(entry, (u) => tokenTracker.calculateCost(u), {
+          showCacheTokens: getShowCacheTokens(),
+          showRateLimitEstimate: getShowRateLimitEstimate(),
+          rateLimitPercentage: taskRateLimitPct,
+        }));
       }
 
       completedInSession.add(task.id);
@@ -1124,7 +1268,12 @@ Task completed. No detailed report provided.
       // Track token usage even for failed tasks (partial data still useful for totals)
       if (attemptUsageData.length > 0) {
         const entry = tokenTracker.addTask(task.id, attemptUsageData);
-        logger.dim(formatTaskTokenSummary(entry, (u) => tokenTracker.calculateCost(u)));
+        const taskRateLimitPct = tokenTracker.getCumulativeRateLimitPercentage();
+        logger.dim(formatTaskTokenSummary(entry, (u) => tokenTracker.calculateCost(u), {
+          showCacheTokens: getShowCacheTokens(),
+          showRateLimitEstimate: getShowRateLimitEstimate(),
+          rateLimitPercentage: taskRateLimitPct,
+        }));
       }
 
       // Analyze failure and generate structured report
@@ -1237,7 +1386,12 @@ ${stashName ? `- Stash: ${stashName}` : ''}
   if (trackerEntries.length > 0) {
     logger.newline();
     const totals = tokenTracker.getTotals();
-    logger.dim(formatTokenTotalSummary(totals.usage, totals.cost));
+    const totalRateLimitPct = tokenTracker.getCumulativeRateLimitPercentage();
+    logger.dim(formatTokenTotalSummary(totals.usage, totals.cost, {
+      showCacheTokens: getShowCacheTokens(),
+      showRateLimitEstimate: getShowRateLimitEstimate(),
+      rateLimitPercentage: totalRateLimitPct,
+    }));
   }
 
   // Show retry history for tasks that had failures (even if eventually successful)

package/src/commands/plan.ts

@@ -15,7 +15,7 @@ import {
   resolveModelOption,
 } from '../utils/validation.js';
 import { logger } from '../utils/logger.js';
-import { getWorktreeDefault, getModel, getModelShortName } from '../utils/config.js';
+import { getWorktreeDefault, getModel, getModelShortName, getSyncMainBranch } from '../utils/config.js';
 import { generateProjectNames } from '../utils/name-generator.js';
 import { pickProjectName } from '../ui/name-picker.js';
 import {
@@ -48,6 +48,7 @@ import {
   validateWorktree,
   removeWorktree,
   computeWorktreeBaseDir,
+  pullMainBranch,
 } from '../core/worktree.js';
 
 interface PlanCommandOptions {
@@ -185,6 +186,18 @@ async function runPlanCommand(projectName?: string, model?: string, autoMode: bo
     const repoRoot = getRepoRoot()!;
     const rafDir = getRafDir();
 
+    // Sync main branch before creating worktree (if enabled)
+    if (getSyncMainBranch()) {
+      const syncResult = pullMainBranch();
+      if (syncResult.success) {
+        if (syncResult.hadChanges) {
+          logger.info(`Synced ${syncResult.mainBranch} from remote`);
+        }
+      } else {
+        logger.warn(`Could not sync main branch: ${syncResult.error}`);
+      }
+    }
+
     // Compute project number from main repo's RAF directory
     const projectNumber = getNextProjectNumber(rafDir);
     const sanitizedName = sanitizeProjectName(finalProjectName);
@@ -412,6 +425,18 @@ async function runAmendCommand(identifier: string, model?: string, autoMode: boo
         logger.info(`Recreated worktree from branch: ${folderName}`);
       } else {
         // No branch — create fresh worktree and copy project files
+        // Sync main branch before creating worktree (if enabled)
+        if (getSyncMainBranch()) {
+          const syncResult = pullMainBranch();
+          if (syncResult.success) {
+            if (syncResult.hadChanges) {
+              logger.info(`Synced ${syncResult.mainBranch} from remote`);
+            }
+          } else {
+            logger.warn(`Could not sync main branch: ${syncResult.error}`);
+          }
+        }
+
         const result = createWorktree(repoBasename, folderName);
         if (!result.success) {
           logger.error(`Failed to create worktree: ${result.error}`);
@@ -602,11 +627,9 @@ async function runAmendCommand(identifier: string, model?: string, autoMode: boo
         logger.info(`  - plans/${planFile}`);
       }
 
-      // Commit planning artifacts (input.md, decisions.md, and new plan files)
-      const newPlanPaths = newPlanFiles.map(f => path.join(plansDir, f));
+      // Commit planning artifacts (input.md, decisions.md only — plan files committed during execution)
       await commitPlanningArtifacts(projectPath, {
         cwd: worktreePath ?? undefined,
-        additionalFiles: newPlanPaths,
         isAmend: true,
       });
 

package/src/core/claude-runner.ts

@@ -6,12 +6,11 @@ import { logger } from '../utils/logger.js';
 import { renderStreamEvent } from '../parsers/stream-renderer.js';
 import type { UsageData } from '../types/config.js';
 import { getHeadCommitHash, getHeadCommitMessage, isFileCommittedInHead } from './git.js';
-import { getClaudeCommand, getModel } from '../utils/config.js';
+import { getModel } from '../utils/config.js';
 
 function getClaudePath(): string {
-  const cmd = getClaudeCommand();
   try {
-    return execSync(`which ${cmd}`, { encoding: 'utf-8' }).trim();
+    return execSync('which claude', { encoding: 'utf-8' }).trim();
   } catch {
     throw new Error('Claude CLI not found. Please ensure it is installed and in your PATH.');
   }
@@ -53,12 +52,6 @@ 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';
   /**
    * Dynamic verbose display callback. When provided, called for each stream event
    * to determine whether to write display output to stdout. Overrides the static
@@ -415,7 +408,7 @@ export class ClaudeRunner {
     options: ClaudeRunnerOptions,
     verbose: boolean,
   ): Promise<RunResult> {
-    const { timeout = 60, cwd = process.cwd(), outcomeFilePath, commitContext, effortLevel, verboseCheck } = options;
+    const { timeout = 60, cwd = process.cwd(), outcomeFilePath, commitContext, verboseCheck } = options;
     // Ensure timeout is a positive number, fallback to 60 minutes
     const validatedTimeout = Number(timeout) > 0 ? Number(timeout) : 60;
     const timeoutMs = validatedTimeout * 60 * 1000;
@@ -437,11 +430,6 @@ 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 token usage in the result event.
@@ -460,7 +448,7 @@ export class ClaudeRunner {
         'Execute the task as described in the system prompt.',
       ], {
         cwd,
-        env,
+        env: process.env,
         stdio: ['ignore', 'pipe', 'pipe'], // no stdin needed
       });
 

package/src/core/failure-analyzer.ts

@@ -1,6 +1,6 @@
 import { spawn } from 'node:child_process';
 import { execSync } from 'node:child_process';
-import { getModel, getClaudeCommand } from '../utils/config.js';
+import { getModel } from '../utils/config.js';
 
 /**
  * Failure types that can be detected programmatically without using the API.
@@ -213,9 +213,8 @@ function extractRelevantOutput(output: string, maxLines: number): string {
  * Get the path to Claude CLI.
  */
 function getClaudePath(): string {
-  const cmd = getClaudeCommand();
   try {
-    return execSync(`which ${cmd}`, { encoding: 'utf-8' }).trim();
+    return execSync('which claude', { encoding: 'utf-8' }).trim();
   } catch {
     throw new Error('Claude CLI not found. Please ensure it is installed and in your PATH.');
   }
@@ -312,6 +311,7 @@ Respond with ONLY a markdown report in this exact format:
     const failureModel = getModel('failureAnalysis');
     const proc = spawn(claudePath, [
       '--model', failureModel,
+      '--no-session-persistence',
       '--dangerously-skip-permissions',
       '-p',
       prompt,

package/src/core/pull-request.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 { getModel, getClaudeCommand, getModelShortName } from '../utils/config.js';
+import { getModel, getModelShortName } from '../utils/config.js';
 import { extractProjectName, getInputPath, getDecisionsPath, getOutcomesDir, TASK_ID_PATTERN } from '../utils/paths.js';
 
 export interface PrCreateResult {
@@ -354,10 +354,9 @@ export function filterClaudeOutput(output: string): string {
  * Call Claude to generate a PR body.
  */
 async function callClaudeForPrBody(prompt: string, timeoutMs: number): Promise<string> {
-  const cmd = getClaudeCommand();
   let claudePath: string;
   try {
-    claudePath = execSync(`which ${cmd}`, { encoding: 'utf-8', stdio: 'pipe' }).trim();
+    claudePath = execSync('which claude', { encoding: 'utf-8', stdio: 'pipe' }).trim();
   } catch {
     throw new Error('Claude CLI not found');
   }
@@ -369,6 +368,7 @@ async function callClaudeForPrBody(prompt: string, timeoutMs: number): Promise<s
     const prModel = getModel('prGeneration');
     const proc = spawn(claudePath, [
       '--model', prModel,
+      '--no-session-persistence',
       '--dangerously-skip-permissions',
       '-p',
       prompt,

package/src/core/state-derivation.ts

@@ -1,6 +1,7 @@
 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 { parsePlanFrontmatter, type PlanFrontmatter } from '../utils/frontmatter.js';
 
 export type DerivedTaskStatus = 'pending' | 'completed' | 'failed' | 'blocked';
 
@@ -16,6 +17,10 @@ export interface DerivedTask {
   planFile: string;
   status: DerivedTaskStatus;
   dependencies: string[];
+  /** Frontmatter metadata parsed from the plan file. */
+  frontmatter?: PlanFrontmatter;
+  /** Warnings from frontmatter parsing. */
+  frontmatterWarnings?: string[];
 }
 
 export interface DerivedProjectState {
@@ -218,23 +223,34 @@ export function deriveProjectState(projectPath: string): DerivedProjectState {
     }
   }
 
-  // First pass: Match plan files to outcomes and parse dependencies
+  // First pass: Match plan files to outcomes and parse dependencies + frontmatter
   for (const planFile of planFiles) {
     const match = planFile.match(new RegExp(`^(${TASK_ID_PATTERN})-(.+)\\.md$`));
     if (match && match[1]) {
       const taskId = match[1];
       const status = outcomeStatuses.get(taskId) ?? 'pending';
 
-      // Read plan file to extract dependencies
+      // Read plan file to extract dependencies and frontmatter
       const planContent = fs.readFileSync(path.join(plansDir, planFile), 'utf-8');
       const dependencies = parseDependencies(planContent);
+      const frontmatterResult = parsePlanFrontmatter(planContent);
 
-      tasks.push({
+      const task: DerivedTask = {
         id: taskId,
         planFile: path.join('plans', planFile),
         status,
         dependencies,
-      });
+      };
+
+      // Only add frontmatter if valid metadata was found
+      if (frontmatterResult.hasFrontmatter) {
+        task.frontmatter = frontmatterResult.frontmatter;
+      }
+      if (frontmatterResult.warnings.length > 0) {
+        task.frontmatterWarnings = frontmatterResult.warnings;
+      }
+
+      tasks.push(task);
     }
   }