@litmers/cursorflow-orchestrator 0.1.18 → 0.1.26

package/src/core/runner.ts

@@ -1,21 +1,30 @@
 /**
  * Core Runner - Execute tasks sequentially in a lane
  * 
- * Adapted from sequential-agent-runner.js
+ * Features:
+ * - Enhanced retry with circuit breaker
+ * - Checkpoint system for recovery
+ * - State validation and repair
+ * - Improved dependency management
  */
 
 import * as fs from 'fs';
 import * as path from 'path';
-import { execSync, spawn, spawnSync } from 'child_process';
+import { spawn, spawnSync } from 'child_process';
 
 import * as git from '../utils/git';
 import * as logger from '../utils/logger';
 import { ensureCursorAgent, checkCursorAuth, printAuthHelp } from '../utils/cursor-agent';
-import { saveState, appendLog, createConversationEntry } from '../utils/state';
+import { saveState, appendLog, createConversationEntry, loadState, validateLaneState, repairLaneState, stateNeedsRecovery } from '../utils/state';
 import { events } from '../utils/events';
 import { loadConfig } from '../utils/config';
 import { registerWebhooks } from '../utils/webhook';
 import { runReviewLoop } from './reviewer';
+import { safeJoin } from '../utils/path';
+import { analyzeFailure, RecoveryAction, logFailure, withRetry } from './failure-policy';
+import { createCheckpoint, getLatestCheckpoint, restoreFromCheckpoint } from '../utils/checkpoint';
+import { waitForTaskDependencies as waitForDeps, DependencyWaitOptions } from '../utils/dependency';
+import { preflightCheck, printPreflightReport } from '../utils/health';
 import { 
   RunnerConfig, 
   Task, 
@@ -24,7 +33,7 @@ import {
   DependencyPolicy, 
   DependencyRequestPlan,
   LaneState
-} from '../utils/types';
+} from '../types';
 
 /**
  * Execute cursor-agent command with timeout and better error handling
@@ -173,19 +182,18 @@ export function validateTaskConfig(config: RunnerConfig): void {
 }
 
 /**
- * Execute cursor-agent command with streaming and better error handling
+ * Internal: Execute cursor-agent command with streaming
  */
-export async function cursorAgentSend({ workspaceDir, chatId, prompt, model, signalDir, timeout, enableIntervention, outputFormat }: { 
+async function cursorAgentSendRaw({ workspaceDir, chatId, prompt, model, signalDir, timeout, enableIntervention, outputFormat, taskName }: { 
   workspaceDir: string; 
   chatId: string; 
   prompt: string; 
   model?: string; 
   signalDir?: string;
   timeout?: number;
-  /** Enable stdin piping for intervention feature (may cause buffering issues on some systems) */
   enableIntervention?: boolean;
-  /** Output format for cursor-agent (default: 'stream-json') */
   outputFormat?: 'stream-json' | 'json' | 'plain';
+  taskName?: string;
 }): Promise<AgentSendResult> {
   // Use stream-json format for structured output with tool calls and results
   const format = outputFormat || 'stream-json';
@@ -201,24 +209,15 @@ export async function cursorAgentSend({ workspaceDir, chatId, prompt, model, sig
   ];
   
   const timeoutMs = timeout || DEFAULT_TIMEOUT_MS;
-  logger.info(`Executing cursor-agent... (timeout: ${Math.round(timeoutMs / 1000)}s)`);
   
   // Determine stdio mode based on intervention setting
-  // When intervention is enabled, we pipe stdin for message injection
-  // When disabled (default), we ignore stdin to avoid buffering issues
   const stdinMode = enableIntervention ? 'pipe' : 'ignore';
   
-  if (enableIntervention) {
-    logger.info('Intervention mode enabled (stdin piped)');
-  }
-  
   return new Promise((resolve) => {
     // Build environment, preserving user's NODE_OPTIONS but disabling problematic flags
     const childEnv = { ...process.env };
     
-    // Only filter out specific problematic NODE_OPTIONS, don't clear entirely
     if (childEnv.NODE_OPTIONS) {
-      // Remove flags that might interfere with cursor-agent
       const filtered = childEnv.NODE_OPTIONS
         .split(' ')
         .filter(opt => !opt.includes('--inspect') && !opt.includes('--debug'))
@@ -226,7 +225,6 @@ export async function cursorAgentSend({ workspaceDir, chatId, prompt, model, sig
       childEnv.NODE_OPTIONS = filtered;
     }
     
-    // Disable Python buffering in case cursor-agent uses Python
     childEnv.PYTHONUNBUFFERED = '1';
     
     const child = spawn('cursor-agent', args, {
@@ -234,18 +232,15 @@ export async function cursorAgentSend({ workspaceDir, chatId, prompt, model, sig
       env: childEnv,
     });
 
-    logger.info(`Executing cursor-agent... (timeout: ${Math.round(timeoutMs / 1000)}s)`);
-
-    // Save PID to state if possible (avoid TOCTOU by reading directly)
+    // Save PID to state if possible
     if (child.pid && signalDir) {
       try {
-        const statePath = path.join(signalDir, 'state.json');
-        // Read directly without existence check to avoid race condition
+        const statePath = safeJoin(signalDir, 'state.json');
         const state = JSON.parse(fs.readFileSync(statePath, 'utf8'));
         state.pid = child.pid;
         fs.writeFileSync(statePath, JSON.stringify(state, null, 2));
       } catch {
-        // Best effort - file may not exist yet
+        // Best effort
       }
     }
 
@@ -253,24 +248,23 @@ export async function cursorAgentSend({ workspaceDir, chatId, prompt, model, sig
     let fullStderr = '';
     let timeoutHandle: NodeJS.Timeout;
 
-    // Heartbeat logging to show progress
+    // Heartbeat logging
     let lastHeartbeat = Date.now();
     let bytesReceived = 0;
+    const startTime = Date.now();
     const heartbeatInterval = setInterval(() => {
-      const elapsed = Math.round((Date.now() - lastHeartbeat) / 1000);
       const totalElapsed = Math.round((Date.now() - startTime) / 1000);
-      logger.info(`⏱ Heartbeat: ${totalElapsed}s elapsed, ${bytesReceived} bytes received`);
+      // Output without timestamp - orchestrator will add it
+      console.log(`⏱ Heartbeat: ${totalElapsed}s elapsed, ${bytesReceived} bytes received`);
     }, HEARTBEAT_INTERVAL_MS);
-    const startTime = Date.now();
 
-    // Watch for "intervention.txt" or "timeout.txt" signal files
+    // Signal watchers (intervention, timeout)
     const interventionPath = signalDir ? path.join(signalDir, 'intervention.txt') : null;
     const timeoutPath = signalDir ? path.join(signalDir, 'timeout.txt') : null;
     let signalWatcher: fs.FSWatcher | null = null;
 
     if (signalDir && fs.existsSync(signalDir)) {
       signalWatcher = fs.watch(signalDir, (event, filename) => {
-        // Handle intervention
         if (filename === 'intervention.txt' && interventionPath && fs.existsSync(interventionPath)) {
           try {
             const message = fs.readFileSync(interventionPath, 'utf8').trim();
@@ -278,59 +272,48 @@ export async function cursorAgentSend({ workspaceDir, chatId, prompt, model, sig
               if (enableIntervention && child.stdin) {
                 logger.info(`Injecting intervention: ${message}`);
                 child.stdin.write(message + '\n');
+                
+                // Log to conversation history for visibility in monitor/logs
+                if (signalDir) {
+                  const convoPath = path.join(signalDir, 'conversation.jsonl');
+                  appendLog(convoPath, createConversationEntry('intervention', `[HUMAN INTERVENTION]: ${message}`, {
+                    task: taskName || 'AGENT_TURN',
+                    model: 'manual'
+                  }));
+                }
               } else {
                 logger.warn(`Intervention requested but stdin not available: ${message}`);
-                logger.warn('To enable intervention, set enableIntervention: true in config');
               }
-              fs.unlinkSync(interventionPath); // Clear it
+              fs.unlinkSync(interventionPath);
             }
-          } catch (e) {
-            logger.warn('Failed to read intervention file');
-          }
+          } catch {}
         }
         
-        // Handle dynamic timeout update
         if (filename === 'timeout.txt' && timeoutPath && fs.existsSync(timeoutPath)) {
           try {
             const newTimeoutStr = fs.readFileSync(timeoutPath, 'utf8').trim();
             const newTimeoutMs = parseInt(newTimeoutStr);
-            
             if (!isNaN(newTimeoutMs) && newTimeoutMs > 0) {
               logger.info(`⏱ Dynamic timeout update: ${Math.round(newTimeoutMs / 1000)}s`);
-              
-              // Clear old timeout
               if (timeoutHandle) clearTimeout(timeoutHandle);
-              
-              // Set new timeout based on total elapsed time
               const elapsed = Date.now() - startTime;
               const remaining = Math.max(1000, newTimeoutMs - elapsed);
-              
               timeoutHandle = setTimeout(() => {
                 clearInterval(heartbeatInterval);
                 child.kill();
-                const totalSec = Math.round(newTimeoutMs / 1000);
-                resolve({
-                  ok: false,
-                  exitCode: -1,
-                  error: `cursor-agent timed out after updated limit of ${totalSec} seconds.`,
-                });
+                resolve({ ok: false, exitCode: -1, error: `cursor-agent timed out after updated limit.` });
               }, remaining);
-              
-              fs.unlinkSync(timeoutPath); // Clear it
+              fs.unlinkSync(timeoutPath);
             }
-          } catch (e) {
-            logger.warn('Failed to read timeout update file');
-          }
+          } catch {}
         }
       });
     }
 
     if (child.stdout) {
       child.stdout.on('data', (data) => {
-        const str = data.toString();
-        fullStdout += str;
+        fullStdout += data.toString();
         bytesReceived += data.length;
-        // Also pipe to our own stdout so it goes to terminal.log
         process.stdout.write(data);
       });
     }
@@ -338,7 +321,6 @@ export async function cursorAgentSend({ workspaceDir, chatId, prompt, model, sig
     if (child.stderr) {
       child.stderr.on('data', (data) => {
         fullStderr += data.toString();
-        // Pipe to our own stderr so it goes to terminal.log
         process.stderr.write(data);
       });
     }
@@ -346,11 +328,10 @@ export async function cursorAgentSend({ workspaceDir, chatId, prompt, model, sig
     timeoutHandle = setTimeout(() => {
       clearInterval(heartbeatInterval);
       child.kill();
-      const timeoutSec = Math.round(timeoutMs / 1000);
       resolve({
         ok: false,
         exitCode: -1,
-        error: `cursor-agent timed out after ${timeoutSec} seconds. The LLM request may be taking too long or there may be network issues.`,
+        error: `cursor-agent timed out after ${Math.round(timeoutMs / 1000)} seconds.`,
       });
     }, timeoutMs);
 
@@ -363,21 +344,7 @@ export async function cursorAgentSend({ workspaceDir, chatId, prompt, model, sig
       
       if (code !== 0 || !json || json.type !== 'result') {
         let errorMsg = fullStderr.trim() || fullStdout.trim() || `exit=${code}`;
-        
-        // Check for common errors
-        if (errorMsg.includes('not authenticated') || errorMsg.includes('login') || errorMsg.includes('auth')) {
-          errorMsg = 'Authentication error. Please sign in to Cursor IDE.';
-        } else if (errorMsg.includes('rate limit') || errorMsg.includes('quota')) {
-          errorMsg = 'API rate limit or quota exceeded.';
-        } else if (errorMsg.includes('model')) {
-          errorMsg = `Model error (requested: ${model || 'default'}). Check your subscription.`;
-        }
-        
-        resolve({
-          ok: false,
-          exitCode: code ?? -1,
-          error: errorMsg,
-        });
+        resolve({ ok: false, exitCode: code ?? -1, error: errorMsg });
       } else {
         resolve({
           ok: !json.is_error,
@@ -391,15 +358,35 @@ export async function cursorAgentSend({ workspaceDir, chatId, prompt, model, sig
     child.on('error', (err) => {
       clearTimeout(timeoutHandle);
       clearInterval(heartbeatInterval);
-      resolve({
-        ok: false,
-        exitCode: -1,
-        error: `Failed to start cursor-agent: ${err.message}`,
-      });
+      resolve({ ok: false, exitCode: -1, error: `Failed to start cursor-agent: ${err.message}` });
     });
   });
 }
 
+/**
+ * Execute cursor-agent command with retries for transient errors
+ */
+export async function cursorAgentSend(options: { 
+  workspaceDir: string; 
+  chatId: string; 
+  prompt: string; 
+  model?: string; 
+  signalDir?: string;
+  timeout?: number;
+  enableIntervention?: boolean;
+  outputFormat?: 'stream-json' | 'json' | 'plain';
+  taskName?: string;
+}): Promise<AgentSendResult> {
+  const laneName = options.signalDir ? path.basename(path.dirname(options.signalDir)) : 'agent';
+  
+  return withRetry(
+    laneName,
+    () => cursorAgentSendRaw(options),
+    (res) => ({ ok: res.ok, error: res.error }),
+    { maxRetries: 3 }
+  );
+}
+
 /**
  * Extract dependency change request from agent response
  */
@@ -430,33 +417,155 @@ export function extractDependencyRequest(text: string): { required: boolean; pla
 }
 
 /**
- * Wrap prompt with dependency policy
+ * Inter-task state file name
+ */
+const LANE_STATE_FILE = '_cursorflow/lane-state.json';
+
+/**
+ * Dependency request file name - agent writes here when dependency changes are needed
  */
-export function wrapPromptForDependencyPolicy(prompt: string, policy: DependencyPolicy, options: { noGit?: boolean } = {}): string {
-  const { noGit = false } = options;
+const DEPENDENCY_REQUEST_FILE = '_cursorflow/dependency-request.json';
+
+/**
+ * Read dependency request from file if it exists
+ */
+export function readDependencyRequestFile(worktreeDir: string): { required: boolean; plan?: DependencyRequestPlan } {
+  const filePath = safeJoin(worktreeDir, DEPENDENCY_REQUEST_FILE);
+  
+  if (!fs.existsSync(filePath)) {
+    return { required: false };
+  }
   
-  if (policy.allowDependencyChange && !policy.lockfileReadOnly && !noGit) {
+  try {
+    const content = fs.readFileSync(filePath, 'utf8');
+    const plan = JSON.parse(content) as DependencyRequestPlan;
+    
+    // Validate required fields
+    if (plan.reason && Array.isArray(plan.commands) && plan.commands.length > 0) {
+      logger.info(`📦 Dependency request file detected: ${filePath}`);
+      return { required: true, plan };
+    }
+    
+    logger.warn(`Invalid dependency request file format: ${filePath}`);
+    return { required: false };
+  } catch (e) {
+    logger.warn(`Failed to parse dependency request file: ${e}`);
+    return { required: false };
+  }
+}
+
+/**
+ * Clear dependency request file after processing
+ */
+export function clearDependencyRequestFile(worktreeDir: string): void {
+  const filePath = safeJoin(worktreeDir, DEPENDENCY_REQUEST_FILE);
+  
+  if (fs.existsSync(filePath)) {
+    try {
+      fs.unlinkSync(filePath);
+      logger.info(`🗑️ Cleared dependency request file: ${filePath}`);
+    } catch (e) {
+      logger.warn(`Failed to clear dependency request file: ${e}`);
+    }
+  }
+}
+
+/**
+ * Wrap prompt with dependency policy instructions (legacy, used by tests)
+ */
+export function wrapPromptForDependencyPolicy(prompt: string, policy: DependencyPolicy): string {
+  if (policy.allowDependencyChange && !policy.lockfileReadOnly) {
     return prompt;
   }
   
-  let rules = '# Dependency Policy (MUST FOLLOW)\n\nYou are running in a restricted lane.\n\n';
+  let wrapped = `### 📦 Dependency Policy\n`;
+  wrapped += `- allowDependencyChange: ${policy.allowDependencyChange}\n`;
+  wrapped += `- lockfileReadOnly: ${policy.lockfileReadOnly}\n\n`;
+  wrapped += prompt;
   
-  rules += `- allowDependencyChange: ${policy.allowDependencyChange}\n`;
-  rules += `- lockfileReadOnly: ${policy.lockfileReadOnly}\n`;
+  return wrapped;
+}
+
+/**
+ * Wrap prompt with global context, dependency policy, and worktree instructions
+ */
+export function wrapPrompt(
+  prompt: string, 
+  config: RunnerConfig, 
+  options: { 
+    noGit?: boolean; 
+    isWorktree?: boolean;
+    previousState?: string | null;
+  } = {}
+): string {
+  const { noGit = false, isWorktree = true, previousState = null } = options;
+  
+  // 1. PREFIX: Environment & Worktree context
+  let wrapped = `### 🛠 Environment & Context\n`;
+  wrapped += `- **Workspace**: 당신은 독립된 **Git 워크트리** (프로젝트 루트)에서 작업 중입니다.\n`;
+  wrapped += `- **Path Rule**: 모든 파일 참조 및 터미널 명령어는 **현재 디렉토리(./)**를 기준으로 하세요.\n`;
+  
+  if (isWorktree) {
+    wrapped += `- **File Availability**: Git 추적 파일만 존재합니다. (node_modules, .env 등은 기본적으로 없음)\n`;
+  }
+
+  // 2. Previous Task State (if available)
+  if (previousState) {
+    wrapped += `\n### 💡 Previous Task State\n`;
+    wrapped += `이전 태스크에서 전달된 상태 정보입니다:\n`;
+    wrapped += `\`\`\`json\n${previousState}\n\`\`\`\n`;
+  }
+  
+  // 3. Dependency Policy (Integrated)
+  const policy = config.dependencyPolicy;
+  wrapped += `\n### 📦 Dependency Policy\n`;
+  wrapped += `- allowDependencyChange: ${policy.allowDependencyChange}\n`;
+  wrapped += `- lockfileReadOnly: ${policy.lockfileReadOnly}\n`;
   
   if (noGit) {
-    rules += '- NO_GIT_MODE: Git is disabled. DO NOT run any git commands (commit, push, etc.). Just edit files.\n';
+    wrapped += `- NO_GIT_MODE: Git 명령어를 사용하지 마세요. 파일 수정만 가능합니다.\n`;
   }
+
+  wrapped += `\n**📦 Dependency Change Rules:**\n`;
+  wrapped += `1. 코드를 수정하기 전, 의존성 변경이 필요한지 **먼저** 판단하세요.\n`;
+  wrapped += `2. 의존성 변경이 필요하다면:\n`;
+  wrapped += `   - **다른 파일을 절대 수정하지 마세요.**\n`;
+  wrapped += `   - 아래 JSON을 \`./${DEPENDENCY_REQUEST_FILE}\` 파일에 저장하세요:\n`;
+  wrapped += `     \`\`\`json\n`;
+  wrapped += `     {\n`;
+  wrapped += `       "reason": "왜 이 의존성이 필요한지 설명",\n`;
+  wrapped += `       "changes": ["add lodash@^4.17.21", "remove unused-pkg"],\n`;
+  wrapped += `       "commands": ["pnpm add lodash@^4.17.21", "pnpm remove unused-pkg"],\n`;
+  wrapped += `       "notes": "추가 참고사항 (선택)"  \n`;
+  wrapped += `     }\n`;
+  wrapped += `     \`\`\`\n`;
+  wrapped += `   - 파일 저장 후 **즉시 작업을 종료**하세요. 오케스트레이터가 처리합니다.\n`;
+  wrapped += `3. 의존성 변경이 불필요하면 바로 본 작업을 진행하세요.\n`;
+
+  wrapped += `\n---\n\n${prompt}\n\n---\n`;
+
+  // 4. SUFFIX: Task Completion & Git Requirements
+  wrapped += `\n### 📝 Task Completion Requirements\n`;
+  wrapped += `**반드시 다음 순서로 작업을 마무리하세요:**\n\n`;
   
-  rules += '\nRules:\n';
-  rules += '- BEFORE making any code changes, decide whether dependency changes are required.\n';
-  rules += '- If dependency changes are required, DO NOT change any files. Instead reply with:\n\n';
-  rules += 'DEPENDENCY_CHANGE_REQUIRED\n';
-  rules += '```json\n{ "reason": "...", "changes": [...], "commands": ["pnpm add ..."], "notes": "..." }\n```\n\n';
-  rules += 'Then STOP.\n';
-  rules += '- If dependency changes are NOT required, proceed normally.\n';
+  if (!noGit) {
+    wrapped += `1. **Git Commit & Push** (필수!):\n`;
+    wrapped += `   \`\`\`bash\n`;
+    wrapped += `   git add -A\n`;
+    wrapped += `   git commit -m "feat: <작업 내용 요약>"\n`;
+    wrapped += `   git push origin HEAD\n`;
+    wrapped += `   \`\`\`\n`;
+    wrapped += `   ⚠️ 커밋과 푸시 없이 작업을 종료하면 변경사항이 손실됩니다!\n\n`;
+  }
   
-  return `${rules}\n---\n\n${prompt}`;
+  wrapped += `2. **State Passing**: 다음 태스크로 전달할 정보가 있다면 \`./${LANE_STATE_FILE}\`에 JSON으로 저장하세요.\n\n`;
+  wrapped += `3. **Summary**: 작업 완료 후 다음을 요약해 주세요:\n`;
+  wrapped += `   - 생성/수정된 파일 목록\n`;
+  wrapped += `   - 주요 변경 사항\n`;
+  wrapped += `   - 커밋 해시 (git log --oneline -1)\n\n`;
+  wrapped += `4. 지시된 문서(docs/...)를 찾을 수 없다면 즉시 보고하세요.\n`;
+
+  return wrapped;
 }
 
 /**
@@ -474,7 +583,7 @@ export function applyDependencyFilePermissions(worktreeDir: string, policy: Depe
   }
   
   for (const file of targets) {
-    const filePath = path.join(worktreeDir, file);
+    const filePath = safeJoin(worktreeDir, file);
     if (!fs.existsSync(filePath)) continue;
     
     try {
@@ -489,49 +598,38 @@ export function applyDependencyFilePermissions(worktreeDir: string, policy: Depe
 
 /**
  * Wait for task-level dependencies to be completed by other lanes
+ * Now uses the enhanced dependency module with timeout support
  */
-export async function waitForTaskDependencies(deps: string[], runDir: string): Promise<void> {
+export async function waitForTaskDependencies(
+  deps: string[], 
+  runDir: string,
+  options: DependencyWaitOptions = {}
+): Promise<void> {
   if (!deps || deps.length === 0) return;
 
   const lanesRoot = path.dirname(runDir);
-  const pendingDeps = new Set(deps);
-
-  logger.info(`Waiting for task dependencies: ${deps.join(', ')}`);
-
-  while (pendingDeps.size > 0) {
-    for (const dep of pendingDeps) {
-      const [laneName, taskName] = dep.split(':');
-      if (!laneName || !taskName) {
-        logger.warn(`Invalid dependency format: ${dep}. Expected "lane:task"`);
-        pendingDeps.delete(dep);
-        continue;
-      }
-
-      const depStatePath = path.join(lanesRoot, laneName, 'state.json');
-      if (fs.existsSync(depStatePath)) {
-        try {
-          const state = JSON.parse(fs.readFileSync(depStatePath, 'utf8')) as LaneState;
-          if (state.completedTasks && state.completedTasks.includes(taskName)) {
-            logger.info(`✓ Dependency met: ${dep}`);
-            pendingDeps.delete(dep);
-          } else if (state.status === 'failed') {
-            throw new Error(`Dependency failed: ${dep} (Lane ${laneName} failed)`);
-          }
-        } catch (e: any) {
-          if (e.message.includes('Dependency failed')) throw e;
-          // Ignore parse errors, file might be being written
-        }
+  
+  const result = await waitForDeps(deps, lanesRoot, {
+    timeoutMs: options.timeoutMs || 30 * 60 * 1000, // 30 minutes default
+    pollIntervalMs: options.pollIntervalMs || 5000,
+    onTimeout: options.onTimeout || 'fail',
+    onProgress: (pending, completed) => {
+      if (completed.length > 0) {
+        logger.info(`Dependencies progress: ${completed.length}/${deps.length} completed`);
       }
+    },
+  });
+  
+  if (!result.success) {
+    if (result.timedOut) {
+      throw new Error(`Dependency wait timed out after ${Math.round(result.elapsedMs / 1000)}s. Pending: ${result.failedDependencies.join(', ')}`);
     }
-
-    if (pendingDeps.size > 0) {
-      await new Promise(resolve => setTimeout(resolve, 5000)); // Poll every 5 seconds
-    }
+    throw new Error(`Dependencies failed: ${result.failedDependencies.join(', ')}`);
   }
 }
 
 /**
- * Merge branches from dependency lanes
+ * Merge branches from dependency lanes with safe merge
  */
 export async function mergeDependencyBranches(deps: string[], runDir: string, worktreeDir: string): Promise<void> {
   if (!deps || deps.length === 0) return;
@@ -540,25 +638,38 @@ export async function mergeDependencyBranches(deps: string[], runDir: string, wo
   const lanesToMerge = new Set(deps.map(d => d.split(':')[0]!));
 
   for (const laneName of lanesToMerge) {
-    const depStatePath = path.join(lanesRoot, laneName, 'state.json');
+    const depStatePath = safeJoin(lanesRoot, laneName, 'state.json');
     if (!fs.existsSync(depStatePath)) continue;
 
     try {
-      const state = JSON.parse(fs.readFileSync(depStatePath, 'utf8')) as LaneState;
-      if (state.pipelineBranch) {
-        logger.info(`Merging branch from ${laneName}: ${state.pipelineBranch}`);
-        
-        // Ensure we have the latest
-        git.runGit(['fetch', 'origin', state.pipelineBranch], { cwd: worktreeDir, silent: true });
-        
-        git.merge(state.pipelineBranch, {
-          cwd: worktreeDir,
-          noFf: true,
-          message: `chore: merge task dependency from ${laneName}`
-        });
+      const state = loadState<LaneState>(depStatePath);
+      if (!state?.pipelineBranch) continue;
+      
+      logger.info(`Merging branch from ${laneName}: ${state.pipelineBranch}`);
+      
+      // Ensure we have the latest
+      git.runGit(['fetch', 'origin', state.pipelineBranch], { cwd: worktreeDir, silent: true });
+      
+      // Use safe merge with conflict detection
+      const mergeResult = git.safeMerge(state.pipelineBranch, {
+        cwd: worktreeDir,
+        noFf: true,
+        message: `chore: merge task dependency from ${laneName}`,
+        abortOnConflict: true,
+      });
+      
+      if (!mergeResult.success) {
+        if (mergeResult.conflict) {
+          logger.error(`Merge conflict with ${laneName}: ${mergeResult.conflictingFiles.join(', ')}`);
+          throw new Error(`Merge conflict: ${mergeResult.conflictingFiles.join(', ')}`);
+        }
+        throw new Error(mergeResult.error || 'Merge failed');
       }
+      
+      logger.success(`✓ Merged ${laneName}`);
     } catch (e) {
       logger.error(`Failed to merge branch from ${laneName}: ${e}`);
+      throw e;
     }
   }
 }
@@ -589,7 +700,7 @@ export async function runTask({
 }): Promise<TaskExecutionResult> {
   const model = task.model || config.model || 'sonnet-4.5';
   const timeout = task.timeout || config.timeout;
-  const convoPath = path.join(runDir, 'conversation.jsonl');
+  const convoPath = safeJoin(runDir, 'conversation.jsonl');
   
   logger.section(`[${index + 1}/${config.tasks.length}] ${task.name}`);
   logger.info(`Model: ${model}`);
@@ -613,10 +724,27 @@ export async function runTask({
   // Apply dependency permissions
   applyDependencyFilePermissions(worktreeDir, config.dependencyPolicy);
   
-  // Run prompt
-  const prompt1 = wrapPromptForDependencyPolicy(task.prompt, config.dependencyPolicy, { noGit });
+  // Read previous task state if available
+  let previousState: string | null = null;
+  const stateFilePath = safeJoin(worktreeDir, LANE_STATE_FILE);
+  if (fs.existsSync(stateFilePath)) {
+    try {
+      previousState = fs.readFileSync(stateFilePath, 'utf8');
+      logger.info('Loaded previous task state from _cursorflow/lane-state.json');
+    } catch (e) {
+      logger.warn(`Failed to read inter-task state: ${e}`);
+    }
+  }
+
+  // Wrap prompt with context, previous state, and completion instructions
+  const wrappedPrompt = wrapPrompt(task.prompt, config, { 
+    noGit, 
+    isWorktree: !noGit,
+    previousState
+  });
   
-  appendLog(convoPath, createConversationEntry('user', prompt1, {
+  // Log ONLY the original prompt to keep logs clean
+  appendLog(convoPath, createConversationEntry('user', task.prompt, {
     task: task.name,
     model,
   }));
@@ -626,18 +754,19 @@ export async function runTask({
   events.emit('agent.prompt_sent', {
     taskName: task.name,
     model,
-    promptLength: prompt1.length,
+    promptLength: wrappedPrompt.length,
   });
 
   const r1 = await cursorAgentSend({
     workspaceDir: worktreeDir,
     chatId,
-    prompt: prompt1,
+    prompt: wrappedPrompt,
     model,
     signalDir: runDir,
     timeout,
     enableIntervention: config.enableIntervention,
     outputFormat: config.agentOutputFormat,
+    taskName: task.name,
   });
   
   const duration = Date.now() - startTime;
@@ -668,15 +797,31 @@ export async function runTask({
     };
   }
   
-  // Check for dependency request
-  const depReq = extractDependencyRequest(r1.resultText || '');
-  if (depReq.required && !config.dependencyPolicy.allowDependencyChange) {
-    return {
-      taskName: task.name,
-      taskBranch,
-      status: 'BLOCKED_DEPENDENCY',
-      dependencyRequest: depReq.plan || null,
-    };
+  // Check for dependency request (file-based takes priority, then text-based)
+  const fileDepReq = readDependencyRequestFile(worktreeDir);
+  const textDepReq = extractDependencyRequest(r1.resultText || '');
+  
+  // Determine which request to use (file-based is preferred as it's more structured)
+  const depReq = fileDepReq.required ? fileDepReq : textDepReq;
+  
+  if (depReq.required) {
+    logger.info(`📦 Dependency change requested: ${depReq.plan?.reason || 'No reason provided'}`);
+    
+    if (depReq.plan) {
+      logger.info(`   Commands: ${depReq.plan.commands.join(', ')}`);
+    }
+    
+    if (!config.dependencyPolicy.allowDependencyChange) {
+      // Clear the file so it doesn't persist after resolution
+      clearDependencyRequestFile(worktreeDir);
+      
+      return {
+        taskName: task.name,
+        taskBranch,
+        status: 'BLOCKED_DEPENDENCY',
+        dependencyRequest: depReq.plan || null,
+      };
+    }
   }
   
   // Push task branch (skip in noGit mode)
@@ -731,7 +876,7 @@ export async function runTask({
 /**
  * Run all tasks in sequence
  */
-export async function runTasks(tasksFile: string, config: RunnerConfig, runDir: string, options: { startIndex?: number; noGit?: boolean } = {}): Promise<TaskExecutionResult[]> {
+export async function runTasks(tasksFile: string, config: RunnerConfig, runDir: string, options: { startIndex?: number; noGit?: boolean; skipPreflight?: boolean } = {}): Promise<TaskExecutionResult[]> {
   const startIndex = options.startIndex || 0;
   const noGit = options.noGit || config.noGit || false;
   
@@ -750,6 +895,33 @@ export async function runTasks(tasksFile: string, config: RunnerConfig, runDir:
     throw validationError;
   }
   
+  // Run preflight checks (can be skipped for resume)
+  if (!options.skipPreflight && startIndex === 0) {
+    logger.info('Running preflight checks...');
+    const preflight = await preflightCheck({
+      requireRemote: !noGit,
+      requireAuth: true,
+    });
+    
+    if (!preflight.canProceed) {
+      printPreflightReport(preflight);
+      throw new Error('Preflight check failed. Please fix the blockers above.');
+    }
+    
+    if (preflight.warnings.length > 0) {
+      for (const warning of preflight.warnings) {
+        logger.warn(`⚠️  ${warning}`);
+      }
+    }
+    
+    logger.success('✓ Preflight checks passed');
+  }
+  
+  // Warn if baseBranch is set in config (it will be ignored)
+  if (config.baseBranch) {
+    logger.warn(`⚠️  config.baseBranch="${config.baseBranch}" will be ignored. Using current branch instead.`);
+  }
+  
   // Ensure cursor-agent is installed
   ensureCursorAgent();
   
@@ -778,26 +950,58 @@ export async function runTasks(tasksFile: string, config: RunnerConfig, runDir:
   logger.success('✓ Cursor authentication OK');
   
   // In noGit mode, we don't need repoRoot - use current directory
-  const repoRoot = noGit ? process.cwd() : git.getRepoRoot();
+  const repoRoot = noGit ? process.cwd() : git.getMainRepoRoot();
+  
+  // ALWAYS use current branch as base - ignore config.baseBranch
+  // This ensures dependency structure is maintained in the worktree
+  const currentBranch = noGit ? 'main' : git.getCurrentBranch(repoRoot);
+  logger.info(`📍 Base branch: ${currentBranch} (current branch)`);
   
   // Load existing state if resuming
-  const statePath = path.join(runDir, 'state.json');
+  const statePath = safeJoin(runDir, 'state.json');
   let state: LaneState | null = null;
   
   if (fs.existsSync(statePath)) {
-    try {
-      state = JSON.parse(fs.readFileSync(statePath, 'utf8'));
-    } catch (e) {
-      logger.warn(`Failed to load existing state from ${statePath}: ${e}`);
+    // Check if state needs recovery
+    if (stateNeedsRecovery(statePath)) {
+      logger.warn('State file indicates incomplete previous run. Attempting recovery...');
+      const repairedState = repairLaneState(statePath);
+      if (repairedState) {
+        state = repairedState;
+        logger.success('✓ State recovered');
+      } else {
+        logger.warn('Could not recover state. Starting fresh.');
+      }
+    } else {
+      state = loadState<LaneState>(statePath);
+      
+      // Validate loaded state
+      if (state) {
+        const validation = validateLaneState(statePath, {
+          checkWorktree: !noGit,
+          checkBranch: !noGit,
+          autoRepair: true,
+        });
+        
+        if (!validation.valid) {
+          logger.warn(`State validation issues: ${validation.issues.join(', ')}`);
+          if (validation.repaired) {
+            logger.info('State was auto-repaired');
+            state = validation.repairedState || state;
+          }
+        }
+      }
     }
   }
   
   const randomSuffix = Math.random().toString(36).substring(2, 7);
   const pipelineBranch = state?.pipelineBranch || config.pipelineBranch || `${config.branchPrefix || 'cursorflow/'}${Date.now().toString(36)}-${randomSuffix}`;
+  
   // In noGit mode, use a simple local directory instead of worktree
-  const worktreeDir = state?.worktreeDir || (noGit 
-    ? path.join(repoRoot, config.worktreeRoot || '_cursorflow/workdir', pipelineBranch.replace(/\//g, '-'))
-    : path.join(repoRoot, config.worktreeRoot || '_cursorflow/worktrees', pipelineBranch));
+  // Flatten the path by replacing slashes with hyphens to avoid race conditions in parent directory creation
+  const worktreeDir = state?.worktreeDir || config.worktreeDir || (noGit 
+    ? safeJoin(repoRoot, config.worktreeRoot || '_cursorflow/workdir', pipelineBranch.replace(/\//g, '-'))
+    : safeJoin(repoRoot, config.worktreeRoot || '_cursorflow/worktrees', pipelineBranch.replace(/\//g, '-')));
   
   if (startIndex === 0) {
     logger.section('🚀 Starting Pipeline');
@@ -816,10 +1020,38 @@ export async function runTasks(tasksFile: string, config: RunnerConfig, runDir:
       logger.info(`Creating work directory: ${worktreeDir}`);
       fs.mkdirSync(worktreeDir, { recursive: true });
     } else {
-      git.createWorktree(worktreeDir, pipelineBranch, { 
-        baseBranch: config.baseBranch || 'main',
-        cwd: repoRoot,
-      });
+      // Use a simple retry mechanism for Git worktree creation to handle potential race conditions
+      let retries = 3;
+      let lastError: Error | null = null;
+      
+      while (retries > 0) {
+        try {
+          // Ensure parent directory exists before calling git worktree
+          const worktreeParent = path.dirname(worktreeDir);
+          if (!fs.existsSync(worktreeParent)) {
+            fs.mkdirSync(worktreeParent, { recursive: true });
+          }
+
+          // Always use the current branch (already captured at start) as the base branch
+          git.createWorktree(worktreeDir, pipelineBranch, { 
+            baseBranch: currentBranch,
+            cwd: repoRoot,
+          });
+          break; // Success
+        } catch (e: any) {
+          lastError = e;
+          retries--;
+          if (retries > 0) {
+            const delay = Math.floor(Math.random() * 1000) + 500;
+            logger.warn(`Worktree creation failed, retrying in ${delay}ms... (${retries} retries left)`);
+            await new Promise(resolve => setTimeout(resolve, delay));
+          }
+        }
+      }
+      
+      if (retries === 0 && lastError) {
+        throw new Error(`Failed to create Git worktree after retries: ${lastError.message}`);
+      }
     }
   } else if (!noGit) {
     // If it exists but we are in Git mode, ensure it's actually a worktree and on the right branch
@@ -858,6 +1090,9 @@ export async function runTasks(tasksFile: string, config: RunnerConfig, runDir:
     state.status = 'running';
     state.error = null;
     state.dependencyRequest = null;
+    state.pipelineBranch = pipelineBranch;
+    state.worktreeDir = worktreeDir;
+    state.label = state.label || pipelineBranch;
     state.dependsOn = config.dependsOn || [];
     state.completedTasks = state.completedTasks || [];
   }
@@ -872,8 +1107,8 @@ export async function runTasks(tasksFile: string, config: RunnerConfig, runDir:
     const lanesRoot = path.dirname(runDir);
     
     for (const depName of config.dependsOn) {
-      const depRunDir = path.join(lanesRoot, depName);
-      const depStatePath = path.join(depRunDir, 'state.json');
+      const depRunDir = path.join(lanesRoot, depName); // nosemgrep
+      const depStatePath = path.join(depRunDir, 'state.json'); // nosemgrep
       
       if (!fs.existsSync(depStatePath)) {
         logger.warn(`Dependency state not found for ${depName} at ${depStatePath}`);
@@ -919,8 +1154,8 @@ export async function runTasks(tasksFile: string, config: RunnerConfig, runDir:
     const lanesRoot = path.dirname(runDir);
     
     for (const depName of config.dependsOn) {
-      const depRunDir = path.join(lanesRoot, depName);
-      const depStatePath = path.join(depRunDir, 'state.json');
+      const depRunDir = safeJoin(lanesRoot, depName);
+      const depStatePath = safeJoin(depRunDir, 'state.json');
       
       if (!fs.existsSync(depStatePath)) {
         continue;
@@ -939,8 +1174,8 @@ export async function runTasks(tasksFile: string, config: RunnerConfig, runDir:
             for (const entry of entries) {
               if (entry.name === '.git' || entry.name === '_cursorflow' || entry.name === 'node_modules') continue;
               
-              const srcPath = path.join(src, entry.name);
-              const destPath = path.join(dest, entry.name);
+              const srcPath = safeJoin(src, entry.name);
+              const destPath = safeJoin(dest, entry.name);
               
               if (entry.isDirectory()) {
                 copyFiles(srcPath, destPath);
@@ -960,11 +1195,22 @@ export async function runTasks(tasksFile: string, config: RunnerConfig, runDir:
   
   // Run tasks
   const results: TaskExecutionResult[] = [];
+  const laneName = state.label || path.basename(runDir);
   
   for (let i = startIndex; i < config.tasks.length; i++) {
     const task = config.tasks[i]!;
     const taskBranch = `${pipelineBranch}--${String(i + 1).padStart(2, '0')}-${task.name}`;
 
+    // Create checkpoint before each task
+    try {
+      await createCheckpoint(laneName, runDir, noGit ? null : worktreeDir, {
+        description: `Before task ${i + 1}: ${task.name}`,
+        maxCheckpoints: 5,
+      });
+    } catch (e: any) {
+      logger.warn(`Failed to create checkpoint: ${e.message}`);
+    }
+
     // Handle task-level dependencies
     if (task.dependsOn && task.dependsOn.length > 0) {
       state.status = 'waiting';
@@ -972,7 +1218,11 @@ export async function runTasks(tasksFile: string, config: RunnerConfig, runDir:
       saveState(statePath, state);
 
       try {
-        await waitForTaskDependencies(task.dependsOn, runDir);
+        // Use enhanced dependency wait with timeout
+        await waitForTaskDependencies(task.dependsOn, runDir, {
+          timeoutMs: config.timeout || 30 * 60 * 1000,
+          onTimeout: 'fail',
+        });
         
         if (!noGit) {
           await mergeDependencyBranches(task.dependsOn, runDir, worktreeDir);
@@ -987,6 +1237,14 @@ export async function runTasks(tasksFile: string, config: RunnerConfig, runDir:
         state.error = e.message;
         saveState(statePath, state);
         logger.error(`Task dependency wait/merge failed: ${e.message}`);
+        
+        // Try to restore from checkpoint
+        const latestCheckpoint = getLatestCheckpoint(runDir);
+        if (latestCheckpoint) {
+          logger.info(`💾 Checkpoint available: ${latestCheckpoint.id}`);
+          logger.info(`   Resume with: cursorflow resume --checkpoint ${latestCheckpoint.id}`);
+        }
+        
         process.exit(1);
       }
     }
@@ -1072,7 +1330,7 @@ export async function runTasks(tasksFile: string, config: RunnerConfig, runDir:
         
         if (entry.isDirectory()) {
           stats.dirs++;
-          const sub = getFileSummary(path.join(dir, entry.name));
+          const sub = getFileSummary(safeJoin(dir, entry.name));
           stats.files += sub.files;
           stats.dirs += sub.dirs;
         } else {
@@ -1086,7 +1344,8 @@ export async function runTasks(tasksFile: string, config: RunnerConfig, runDir:
     logger.info(`Final Workspace Summary (noGit): ${summary.files} files, ${summary.dirs} directories created/modified`);
   } else {
     try {
-      const stats = git.runGit(['diff', '--stat', config.baseBranch || 'main', pipelineBranch], { cwd: repoRoot, silent: true });
+      // Always use current branch for comparison (already captured at start)
+      const stats = git.runGit(['diff', '--stat', currentBranch, pipelineBranch], { cwd: repoRoot, silent: true });
       if (stats) {
         logger.info('Final Workspace Summary (Git):\n' + stats);
       }
@@ -1114,11 +1373,13 @@ if (require.main === module) {
   const runDirIdx = args.indexOf('--run-dir');
   const startIdxIdx = args.indexOf('--start-index');
   const pipelineBranchIdx = args.indexOf('--pipeline-branch');
+  const worktreeDirIdx = args.indexOf('--worktree-dir');
   const noGit = args.includes('--no-git');
   
   const runDir = runDirIdx >= 0 ? args[runDirIdx + 1]! : '.';
   const startIndex = startIdxIdx >= 0 ? parseInt(args[startIdxIdx + 1] || '0') : 0;
   const forcedPipelineBranch = pipelineBranchIdx >= 0 ? args[pipelineBranchIdx + 1] : null;
+  const forcedWorktreeDir = worktreeDirIdx >= 0 ? args[worktreeDirIdx + 1] : null;
 
   // Extract runId from runDir (format: .../runs/run-123/lanes/lane-name)
   const parts = runDir.split(path.sep);
@@ -1150,6 +1411,9 @@ if (require.main === module) {
     if (forcedPipelineBranch) {
       config.pipelineBranch = forcedPipelineBranch;
     }
+    if (forcedWorktreeDir) {
+      config.worktreeDir = forcedWorktreeDir;
+    }
   } catch (error: any) {
     console.error(`Failed to load tasks file: ${error.message}`);
     process.exit(1);