vibeman 0.0.2 → 0.0.5

package/dist/runtime/api/workflows/vibing-orchestrator.js

@@ -1,4 +1,5 @@
 import { EventEmitter } from 'events';
+import { TaskUpdater } from '../tasks/task-updater.js';
 import { QualityPipeline } from './quality-pipeline.js';
 import { DatabaseService } from '../persistence/database-service.js';
 import { log } from '../lib/logger.js';
@@ -8,35 +9,20 @@ import { stripNextInjectedEnv } from '../utils/stripNextEnv.js';
 import { spawn } from 'child_process';
 import { getSettingsService } from '../settings-service.js';
 import { getVibeDir } from '../lib/server/project-root.js';
-// Canonical phase flow and labels for server-driven timeline and placeholders
-// Action phases only; placeholders are created for these
-const PHASE_FLOW = [
-    'implementing',
-    'validating',
-    'ai-reviewing',
-    // Show awaiting-review explicitly in the main flow so the timeline
-    // reflects the human approval step in order
-    'awaiting-review',
-    'merging',
-    'cleaning',
-];
+import { EXTENDED_PHASE_FLOW, EXTENDED_PHASE_LABELS } from './workflow-schema.js';
+import { reduce, computeNextAction } from './workflow-reducer.js';
+import { executeEffects } from './workflow-effects.js';
+import { WorkflowReconciler, HeartbeatTracker, IdempotencyGuard, } from './workflow-reconciler.js';
+// Use unified phase definitions from workflow-schema
+const PHASE_FLOW = EXTENDED_PHASE_FLOW;
+// Extended labels with legacy mappings for timeline display
 const PHASE_LABELS = {
+    ...EXTENDED_PHASE_LABELS,
     draft: 'Workflow started',
     implementing: 'Implementation',
-    implemented: 'Implemented',
     validating: 'Validation',
-    validated: 'Validated',
-    'ai-reviewing': 'AI Review',
-    'ai-reviewed': 'AI Reviewed',
-    'awaiting-review': 'Awaiting Review',
-    paused: 'Paused',
-    approved: 'Approved',
     merging: 'Merge',
-    merged: 'Merged',
-    cleaning: 'Cleaning',
-    cleaned: 'Cleaned',
-    completed: 'Completed',
-    failed: 'Failed',
+    approved: 'Approved',
 };
 // Default config
 const getDefaultConfig = async () => {
@@ -160,12 +146,23 @@ export class VibingOrchestrator extends EventEmitter {
         this.gitService = gitService;
         this.workflows = new Map();
         this.initialized = false;
+        this.activeImprovements = new Map();
+        this.taskImprovementExecutions = new Map();
         this.qualityPipeline = new QualityPipeline();
+        this.taskUpdater = new TaskUpdater();
         // Persist workflows in a JSON file using the generic database service
         const filePath = persistenceDataDir
             ? path.join(persistenceDataDir, 'workflows.json')
-            : path.join(getVibeDir(), 'workflows.json');
+            : path.join(getVibeDir(), '.local/workflows.json');
         this.workflowDB = new DatabaseService(filePath);
+        // Initialize Phase 3: Reliability & Observability components
+        this.heartbeatTracker = new HeartbeatTracker(5 * 60 * 1000); // 5 min stale threshold
+        this.idempotencyGuard = new IdempotencyGuard(60 * 60 * 1000); // 1 hour TTL
+        this.reconciler = new WorkflowReconciler({
+            checkIntervalMs: 60 * 1000, // Check every minute
+            stuckThresholdMs: 30 * 60 * 1000, // 30 min stuck threshold
+            maxReconcileAttempts: 3,
+        }, () => this.getWorkflowSnapshots(), (workflowId, action) => this.handleStuckWorkflow(workflowId, action));
         // Forward execution updates from AgentService so UIs can subscribe via orchestrator
         this.agentService.on('executionUpdated', (update) => {
             this.emit('executionUpdated', update);
@@ -224,12 +221,106 @@ export class VibingOrchestrator extends EventEmitter {
             this.workflows = map;
             log.debug('Loaded existing workflows from disk', { count: this.workflows.size }, 'vibing-orchestrator');
             log.debug('Vibing orchestrator initialized with persisted workflows', undefined, 'vibing-orchestrator');
+            // Start reliability components
+            this.reconciler.start();
+            this.idempotencyGuard.start();
+            log.info('Started workflow reconciler and idempotency guard', {}, 'vibing-orchestrator');
         }
         catch (error) {
             log.warn('Failed to load workflows from disk', error, 'vibing-orchestrator');
         }
         this.initialized = true;
     }
+    /**
+     * Shutdown the orchestrator and cleanup resources
+     */
+    async shutdown() {
+        this.reconciler.stop();
+        this.idempotencyGuard.stop();
+        this.heartbeatTracker.clear();
+        log.info('Vibing orchestrator shutdown complete', {}, 'vibing-orchestrator');
+    }
+    // ============================================================================
+    // PHASE 3: Reliability & Observability Helpers
+    // ============================================================================
+    /**
+     * Get workflow snapshots for reconciler
+     */
+    getWorkflowSnapshots() {
+        const snapshots = [];
+        for (const [id, wf] of this.workflows) {
+            snapshots.push({
+                id,
+                taskId: wf.taskId,
+                phase: wf.phase,
+                lastUpdatedAt: wf.lastUpdatedAt || wf.startTime,
+                terminalStatus: wf.phase === 'failed' ? 'failed' : wf.phase === 'paused' ? 'paused' : null,
+                lastHeartbeat: this.heartbeatTracker.getLastHeartbeat(id),
+                reconcileAttempts: wf.reconcileAttempts,
+            });
+        }
+        return snapshots;
+    }
+    /**
+     * Handle stuck workflow detected by reconciler
+     */
+    async handleStuckWorkflow(workflowId, action) {
+        const wf = this.workflows.get(workflowId);
+        if (!wf)
+            return;
+        log.warn('Handling stuck workflow', { workflowId, action: action.action, reason: action.reason }, 'vibing-orchestrator');
+        // Track reconcile attempts
+        wf.reconcileAttempts = (wf.reconcileAttempts || 0) + 1;
+        switch (action.action) {
+            case 'timeout':
+                // Emit timeout event for UI notification
+                this.emit('workflowTimeout', {
+                    workflowId,
+                    phase: wf.phase,
+                    reason: action.reason,
+                    timestamp: action.timestamp,
+                });
+                break;
+            case 'fail':
+                // Mark workflow as failed after max attempts
+                await this.dispatch(workflowId, { type: 'PAUSE' });
+                wf.error = action.reason;
+                await this.saveWorkflow(wf);
+                this.emit('workflowStuckFailed', {
+                    workflowId,
+                    reason: action.reason,
+                    timestamp: action.timestamp,
+                });
+                break;
+            case 'retry':
+                // Attempt to retry the current phase
+                await this.dispatch(workflowId, { type: 'RETRY' });
+                break;
+            default:
+                break;
+        }
+    }
+    /**
+     * Record heartbeat for active workflow execution
+     */
+    recordHeartbeat(workflowId) {
+        const wf = this.workflows.get(workflowId);
+        if (wf) {
+            this.heartbeatTracker.recordHeartbeat(workflowId, wf.phase);
+        }
+    }
+    /**
+     * Check if reconciler is running
+     */
+    isReconcilerRunning() {
+        return this.reconciler.isRunning();
+    }
+    /**
+     * Get reconcile history for debugging
+     */
+    getReconcileHistory() {
+        return this.reconciler.getReconcileHistory();
+    }
     // Normalize workflow shape so timeline/status writes don't throw
     normalizeWorkflow(wf) {
         const out = { ...wf };
@@ -258,6 +349,240 @@ export class VibingOrchestrator extends EventEmitter {
             out.status = 'draft';
         return out;
     }
+    // ============================================================================
+    // NEW STATE MACHINE: Dispatch & Effect Execution
+    // ============================================================================
+    /**
+     * Convert VibingExecution to WorkflowState for the reducer
+     */
+    toWorkflowState(wf) {
+        // Map legacy phases to new simplified phases
+        // Key insight: checkpoint statuses (implemented, validated, etc.) indicate
+        // the PREVIOUS phase completed, so they map to the NEXT phase
+        const phaseMap = {
+            draft: 'draft',
+            implementing: 'implementing',
+            implemented: 'validating', // implementation done -> ready for validation
+            validating: 'validating',
+            validated: 'approved', // validation done -> ready for approval/review
+            'ai-reviewing': 'approved',
+            'ai-reviewed': 'approved',
+            'awaiting-review': 'approved',
+            approved: 'merging', // approved -> ready for merge
+            merging: 'merging',
+            merged: 'done', // merged -> ready for cleanup/done
+            cleaning: 'done',
+            cleaned: 'done',
+            completed: 'done',
+        };
+        const terminalMap = {
+            failed: 'failed',
+            paused: 'paused',
+        };
+        return {
+            id: wf.id,
+            taskId: wf.taskId,
+            phase: phaseMap[wf.phase] || 'draft',
+            terminalStatus: terminalMap[wf.phase] || null,
+            startTime: wf.startTime,
+            endTime: wf.endTime,
+            lastUpdatedAt: wf.lastUpdatedAt || wf.startTime,
+            attempts: (wf.attempts || {}),
+            executionIds: (wf.executionIds || {}),
+            qualityResults: wf.qualityResults,
+            aiReviewResult: wf.aiReviewResult,
+            links: wf.links || {},
+            error: wf.error,
+            failureContext: wf.failureContext
+                ? {
+                    atPhase: phaseMap[wf.failureContext.atPhase] || 'implementing',
+                    error: wf.failureContext.error,
+                    timestamp: wf.failureContext.timestamp,
+                }
+                : undefined,
+            config: {
+                autoQualityChecks: wf.metadata.autoQualityChecks,
+                requireHumanApproval: wf.metadata.requireHumanApproval,
+                aiCodeReview: wf.metadata.aiCodeReview ?? true,
+                stepByStepMode: wf.metadata.stepByStepMode ?? false,
+                autoCommit: wf.metadata.autoCommit ?? false,
+                createPR: wf.metadata.createPR,
+                autoMerge: wf.metadata.autoMerge,
+                retryPolicy: wf.metadata.retryPolicy || { maxImplementationAttempts: 3 },
+            },
+            rerunContext: wf.rerunContextHistory?.[wf.rerunContextHistory.length - 1]
+                ? {
+                    reason: wf.rerunContextHistory[wf.rerunContextHistory.length - 1].reason,
+                    previousExecutionId: wf.rerunContextHistory[wf.rerunContextHistory.length - 1].previousExecutionId,
+                }
+                : undefined,
+        };
+    }
+    /**
+     * Apply WorkflowState changes back to VibingExecution (for backward compatibility)
+     */
+    applyStateToExecution(wf, state) {
+        const reversePhaseMap = {
+            draft: 'draft',
+            implementing: 'implementing',
+            validating: 'validating',
+            approved: 'awaiting-review',
+            merging: 'merging',
+            done: 'completed',
+        };
+        wf.lastUpdatedAt = state.lastUpdatedAt;
+        wf.error = state.error;
+        wf.endTime = state.endTime;
+        if (state.terminalStatus) {
+            wf.phase = state.terminalStatus;
+            wf.status = state.terminalStatus;
+        }
+        else {
+            wf.phase = reversePhaseMap[state.phase];
+            wf.status = reversePhaseMap[state.phase];
+        }
+        if (state.qualityResults) {
+            wf.qualityResults = state.qualityResults;
+        }
+        if (state.aiReviewResult) {
+            wf.aiReviewResult = state.aiReviewResult;
+        }
+        if (state.links) {
+            wf.links = { ...wf.links, ...state.links };
+        }
+        if (state.failureContext) {
+            wf.failureContext = {
+                atPhase: state.failureContext.atPhase,
+                error: state.failureContext.error,
+                timestamp: state.failureContext.timestamp,
+            };
+        }
+    }
+    /**
+     * Create an EffectContext that binds orchestrator methods
+     */
+    createEffectContext(workflowId, state) {
+        const wf = this.workflows.get(workflowId);
+        return {
+            workflowId,
+            taskId: state.taskId,
+            state,
+            executeImplementation: async (feedback) => {
+                await this.executeImplementation(workflowId, feedback);
+            },
+            executeValidation: async () => {
+                await this.executeValidation(workflowId);
+            },
+            executeAiReview: async () => {
+                await this.executeAiReviewPhase(workflowId);
+            },
+            executeMerge: async () => {
+                await this.executeMerge(workflowId);
+            },
+            executeCleanup: async () => {
+                await this.executeCleanup(workflowId);
+            },
+            stopExecution: async () => {
+                if (wf) {
+                    const executions = this.agentService.getTaskExecutions(wf.taskId) || [];
+                    const running = executions.find((e) => e.status === 'running');
+                    if (running?.id) {
+                        await this.agentService.stopExecution(running.id);
+                    }
+                }
+            },
+            saveWorkflow: async (updatedState) => {
+                if (wf) {
+                    this.applyStateToExecution(wf, updatedState);
+                    await this.saveWorkflow(wf);
+                }
+            },
+            updateTask: async () => {
+                if (wf) {
+                    await this.updateTaskForReviewReadiness(wf);
+                }
+            },
+            emit: (name, payload) => {
+                this.emit(name, { ...payload, workflow: wf });
+            },
+        };
+    }
+    /**
+     * Dispatch an event to the workflow state machine (NEW API)
+     * This is the new way to trigger state transitions.
+     * Uses idempotency guard to prevent duplicate event processing.
+     */
+    async dispatch(workflowId, event) {
+        const wf = this.workflows.get(workflowId);
+        if (!wf) {
+            throw new Error(`Workflow ${workflowId} not found`);
+        }
+        // Generate idempotency key for this event
+        const eventKey = this.idempotencyGuard.generateEventKey(workflowId, event.type, event);
+        // Check if this event was already processed
+        const { skipped } = await this.idempotencyGuard.withIdempotency(eventKey, async () => {
+            const beforePhase = wf.phase;
+            const beforeStatus = wf.status;
+            const timestamp = new Date().toISOString();
+            log.info('Dispatching workflow event', {
+                workflowId,
+                eventType: event.type,
+                currentPhase: beforePhase,
+                currentStatus: beforeStatus,
+            }, 'vibing-orchestrator');
+            const currentState = this.toWorkflowState(wf);
+            const { state: newState, effects } = reduce(currentState, event);
+            // Apply state changes
+            this.applyStateToExecution(wf, newState);
+            // Record event in phase history for audit trail
+            const phaseHistory = wf.phaseHistory || [];
+            phaseHistory.push({
+                from: beforePhase,
+                to: wf.phase,
+                at: timestamp,
+                reason: `Event: ${event.type}`,
+            });
+            wf.phaseHistory = phaseHistory;
+            // Record heartbeat on state change
+            this.heartbeatTracker.recordHeartbeat(workflowId, wf.phase);
+            // Execute effects
+            const context = this.createEffectContext(workflowId, newState);
+            await executeEffects(effects, context);
+            log.info('Workflow event dispatched', {
+                workflowId,
+                eventType: event.type,
+                beforePhase,
+                afterPhase: wf.phase,
+                effectCount: effects.length,
+                effects: effects.map((e) => e.type),
+            }, 'vibing-orchestrator');
+            // Emit a generic event for UI/external listeners
+            this.emit('workflowEventDispatched', {
+                workflowId,
+                event,
+                beforePhase,
+                afterPhase: wf.phase,
+                timestamp,
+                workflow: wf,
+            });
+        });
+        if (skipped) {
+            log.debug('Skipped duplicate workflow event', { workflowId, eventType: event.type }, 'vibing-orchestrator');
+        }
+    }
+    /**
+     * Get the next recommended action for a workflow (uses new state machine)
+     */
+    getNextAction(workflowId) {
+        const wf = this.workflows.get(workflowId);
+        if (!wf)
+            return null;
+        const state = this.toWorkflowState(wf);
+        return computeNextAction(state);
+    }
+    // ============================================================================
+    // END NEW STATE MACHINE
+    // ============================================================================
     /**
      * Execute a task once (no phase management). Optionally associates with a workflow.
      */
@@ -296,6 +621,38 @@ export class VibingOrchestrator extends EventEmitter {
     async listAllExecutions() {
         return await this.agentService.listAllExecutions();
     }
+    async startTaskImprovement(taskId, data, options) {
+        const task = this.taskService.getTask(taskId);
+        if (!task)
+            throw new Error(`Task ${taskId} not found`);
+        const existingExecutionForTask = this.taskImprovementExecutions.get(taskId);
+        if (existingExecutionForTask) {
+            return { executionId: existingExecutionForTask };
+        }
+        const requestedExecution = options?.executionId;
+        if (requestedExecution) {
+            const status = this.agentService.getExecutionStatus(requestedExecution);
+            if (status && ['pending', 'running'].includes(status.status)) {
+                this.taskImprovementExecutions.set(taskId, requestedExecution);
+                return { executionId: requestedExecution };
+            }
+        }
+        const executionId = requestedExecution || generateId('improve');
+        if (this.activeImprovements.has(executionId)) {
+            return { executionId };
+        }
+        this.taskImprovementExecutions.set(taskId, executionId);
+        const job = this.runTaskImprovementPipeline(task, data, executionId, taskId);
+        this.activeImprovements.set(executionId, job);
+        void job.finally(() => {
+            this.activeImprovements.delete(executionId);
+            const current = this.taskImprovementExecutions.get(taskId);
+            if (current === executionId) {
+                this.taskImprovementExecutions.delete(taskId);
+            }
+        });
+        return { executionId };
+    }
     async improveTaskContent(taskId, data, options) {
         const task = this.taskService.getTask(taskId);
         if (!task)
@@ -313,6 +670,71 @@ export class VibingOrchestrator extends EventEmitter {
         }
         return res;
     }
+    async runTaskImprovementPipeline(task, data, executionId, taskId) {
+        const timestamp = () => new Date().toLocaleTimeString();
+        const withLog = (message) => {
+            const baseLogs = this.agentService.getExecutionLogs(executionId) || [];
+            return [...baseLogs, `[${timestamp()}] ${message}`];
+        };
+        const originalSnapshot = JSON.parse(JSON.stringify(task));
+        let updatedTask = null;
+        this.agentService.registerCompletionInterceptor(executionId, async () => true);
+        try {
+            const improvement = await this.agentService.improveTaskContent(task, data, executionId);
+            const updates = {
+                type: improvement.type,
+                priority: improvement.priority,
+                content: improvement.content,
+            };
+            if (improvement.title) {
+                updates.title = improvement.title;
+            }
+            updatedTask = await this.taskService.updateTask(task.id, updates);
+            if (!this.gitService) {
+                throw new Error('Git service unavailable; cannot commit improved task');
+            }
+            const taskFilePath = path.join(getVibeDir(), 'tasks', `${updatedTask.id}.md`);
+            const relativeTaskPath = path.relative(this.gitService.getProjectRoot(), taskFilePath);
+            const commitMessage = `chore(${updatedTask.id.toLowerCase()}): apply AI improvement`;
+            let commitSummary = 'Task improvement saved without committing (no changes detected)';
+            try {
+                const commitInfo = await this.gitService.commitChanges(updatedTask, commitMessage, [
+                    relativeTaskPath,
+                ]);
+                commitSummary = `Task improvement committed (${commitInfo.hash.slice(0, 7)})`;
+            }
+            catch (commitError) {
+                const message = commitError instanceof Error ? commitError.message : String(commitError);
+                if (/nothing to commit|no changes added to commit|working tree clean/i.test(message)) {
+                    commitSummary = 'No file changes detected; commit skipped';
+                }
+                else {
+                    throw new Error(`Failed to commit improved task: ${message}`);
+                }
+            }
+            const completionLogs = withLog('Task file updated with AI improvement').concat(`[${timestamp()}] ${commitSummary}`);
+            await this.agentService.finalizeExecution(executionId, 'completed', undefined, completionLogs);
+        }
+        catch (error) {
+            if (updatedTask) {
+                const revertPayload = { ...originalSnapshot };
+                delete revertPayload.id;
+                try {
+                    await this.taskService.updateTask(task.id, revertPayload);
+                }
+                catch (revertError) {
+                    log.error('Failed to revert task after improvement failure', { taskId, executionId, error: revertError }, 'vibing-orchestrator');
+                }
+            }
+            const message = error instanceof Error ? error.message : String(error);
+            this.agentService.clearCompletionInterceptor(executionId);
+            await this.agentService.finalizeExecution(executionId, 'failed', message, withLog(`Error applying task improvement: ${message}`));
+            log.error('Failed to complete task improvement', { taskId, executionId, error }, 'vibing-orchestrator');
+        }
+        finally {
+            this.agentService.clearCompletionInterceptor(executionId);
+        }
+    }
     async aiReviewCode(taskId, reviewContext, options) {
         const res = await this.agentService.aiReviewCode(taskId, reviewContext, {
             overrides: options?.overrides,
@@ -323,10 +745,12 @@ export class VibingOrchestrator extends EventEmitter {
         if (wfId) {
             const wf = this.workflows.get(wfId);
             if (wf) {
+                const timestamp = new Date().toISOString();
                 wf.metadata = {
                     ...wf.metadata,
-                    aiReviewResult: { ...res, timestamp: new Date().toISOString() },
+                    aiReviewResult: { ...res, timestamp },
                 };
+                wf.aiReviewResult = { ...res, timestamp };
                 // Record execution ID under ai-reviewing for UI/observability
                 if (res?.executionId) {
                     wf.executionIds = wf.executionIds || {};
@@ -474,11 +898,9 @@ export class VibingOrchestrator extends EventEmitter {
             ...workflow.metadata,
             humanCompleted: true,
         };
-        workflow.endTime = new Date().toISOString();
-        await this.transitionToPhase(workflowId, 'completed');
-        this.emit('workflowCompleted', workflow);
+        // Use dispatch for manual completion
+        await this.dispatch(workflowId, { type: 'COMPLETE_MANUAL' });
         log.info('Workflow marked completed by human', { taskId: workflow.taskId }, 'vibing-orchestrator');
-        await this.saveWorkflow(workflow);
     }
     async ensureInitialized() {
         if (!this.initialized) {
@@ -530,12 +952,8 @@ export class VibingOrchestrator extends EventEmitter {
                 log.warn('Failed to stop execution', error, 'vibing-orchestrator');
             }
         }
-        workflow.phase = 'paused';
-        workflow.error = 'Paused by user';
-        workflow.status = 'paused';
-        // Persist the workflow state
-        await this.saveWorkflow(workflow);
-        this.emit('workflowPaused', workflow);
+        // Use dispatch for state transition
+        await this.dispatch(workflowId, { type: 'PAUSE' });
         log.info('Paused workflow', { workflowId }, 'vibing-orchestrator');
     }
     /**
@@ -582,31 +1000,10 @@ export class VibingOrchestrator extends EventEmitter {
         const workflow = this.requireWorkflow(workflowId);
         this.assertPhase(workflow, 'awaiting-review', 'approve');
         // Close the awaiting-review timeline item if present
-        try {
-            const tl = (workflow.timeline || []);
-            for (let i = tl.length - 1; i >= 0; i--) {
-                const t = tl[i];
-                if (t.phase === 'awaiting-review' && !t.placeholder && !t.endTime) {
-                    t.endTime = new Date().toISOString();
-                    break;
-                }
-            }
-            workflow.timeline = this.computeVisibleTimeline(workflow);
-            await this.saveWorkflow(workflow);
-        }
-        catch (err) {
-            log.debug('Failed to finalize awaiting-review timeline item', err, 'vibing-orchestrator');
-        }
-        workflow.status = 'approved';
-        workflow.lastUpdatedAt = new Date().toISOString();
-        await this.transitionToPhase(workflowId, 'approved');
-        await this.saveWorkflow(workflow);
-        if (workflow.metadata.stepByStepMode) {
-            log.info('Manual step mode – approved; waiting for Continue to run merge', { workflowId }, 'vibing-orchestrator');
-        }
-        else {
-            await this.executeMerge(workflowId);
-        }
+        this.closeTimelineItem(workflow, 'awaiting-review');
+        // Use dispatch for state transition - reducer handles status update and effects
+        await this.dispatch(workflowId, { type: 'APPROVE' });
+        log.info('Approved workflow', { workflowId }, 'vibing-orchestrator');
     }
     /**
      * Reject workflow and request changes
@@ -615,24 +1012,29 @@ export class VibingOrchestrator extends EventEmitter {
         const workflow = this.requireWorkflow(workflowId);
         this.assertPhase(workflow, 'awaiting-review', 'reject');
         // Close the awaiting-review timeline item if present
+        this.closeTimelineItem(workflow, 'awaiting-review');
+        // Use dispatch for state transition - reducer handles re-implementation with feedback
+        await this.dispatch(workflowId, { type: 'REJECT', feedback });
+        log.info('Rejected workflow', { workflowId, feedback }, 'vibing-orchestrator');
+    }
+    /**
+     * Helper to close a timeline item by phase
+     */
+    closeTimelineItem(workflow, phase) {
         try {
             const tl = (workflow.timeline || []);
             for (let i = tl.length - 1; i >= 0; i--) {
                 const t = tl[i];
-                if (t.phase === 'awaiting-review' && !t.placeholder && !t.endTime) {
+                if (t.phase === phase && !t.placeholder && !t.endTime) {
                     t.endTime = new Date().toISOString();
                     break;
                 }
             }
             workflow.timeline = this.computeVisibleTimeline(workflow);
-            await this.saveWorkflow(workflow);
         }
         catch (err) {
-            log.debug('Failed to finalize awaiting-review timeline item', err, 'vibing-orchestrator');
+            log.debug(`Failed to finalize ${phase} timeline item`, err, 'vibing-orchestrator');
         }
-        // Return to implementation phase with feedback
-        await this.transitionToPhase(workflowId, 'implementing');
-        await this.executeImplementation(workflowId, feedback);
     }
     /**
      * Get workflow status
@@ -674,17 +1076,17 @@ export class VibingOrchestrator extends EventEmitter {
         return latest;
     }
     /**
-     * Transition workflow to new phase
+     * Update UI phase with proper tracking of lastPhase, phaseHistory, and metrics.
+     * This is for UI-only phases that don't correspond to FSM states.
      */
-    async transitionToPhase(workflowId, newPhase) {
-        const workflow = this.workflows.get(workflowId);
-        if (!workflow)
-            return;
+    updateUIPhase(workflow, newPhase) {
         const oldPhase = workflow.phase;
+        if (oldPhase === newPhase)
+            return;
         workflow.lastPhase = oldPhase;
         workflow.phase = newPhase;
-        const history = workflow.phaseHistory || [];
         const now = new Date().toISOString();
+        const history = workflow.phaseHistory || [];
         history.push({ from: oldPhase, to: newPhase, at: now });
         workflow.phaseHistory = history;
         // Metrics accumulation
@@ -702,9 +1104,74 @@ export class VibingOrchestrator extends EventEmitter {
         }
         workflow.lastUpdatedAt = now;
         workflow.timeline = this.computeVisibleTimeline(workflow);
-        log.info('Workflow phase transition', { workflowId, oldPhase, newPhase }, 'vibing-orchestrator');
-        await this.saveWorkflow(workflow);
-        this.emit('workflowPhaseChanged', { workflowId, oldPhase, newPhase, workflow });
+        this.heartbeatTracker.recordHeartbeat(workflow.id, newPhase);
+        this.emit('workflowPhaseChanged', {
+            workflowId: workflow.id,
+            oldPhase,
+            newPhase,
+            workflow,
+        });
+    }
+    /**
+     * Update task file when workflow becomes ready for review
+     */
+    async updateTaskForReviewReadiness(workflow) {
+        try {
+            const context = this.extractTaskUpdateContext(workflow);
+            await this.taskUpdater.updateTaskForReviewReadiness(workflow.taskId, context);
+            log.info('Task updated for review readiness', { taskId: workflow.taskId, workflowId: workflow.id }, 'vibing-orchestrator');
+        }
+        catch (error) {
+            log.error('Failed to update task for review readiness', { taskId: workflow.taskId, workflowId: workflow.id, error }, 'vibing-orchestrator');
+            // Don't throw - task update failure shouldn't block workflow progression
+        }
+    }
+    /**
+     * Extract context information for task updates
+     */
+    extractTaskUpdateContext(workflow) {
+        const context = {
+            workflowId: workflow.id,
+            phase: workflow.phase,
+            filesModified: [],
+            keyChanges: [],
+            testsAdded: workflow.qualityResults?.details?.tests,
+            testsPassed: workflow.qualityResults?.details?.tests,
+            buildPassed: workflow.qualityResults?.details?.build,
+            qualityChecksPassed: workflow.qualityResults?.overall,
+        };
+        // Extract AI review score if available
+        if (workflow.metadata?.aiReviewResult) {
+            context.aiReviewScore = workflow.metadata.aiReviewResult.qualityScore;
+        }
+        // Extract key changes from implementation attempts
+        const implementingExecutions = workflow.executionIds?.implementing || [];
+        if (implementingExecutions.length > 0) {
+            context.keyChanges = [
+                `Implementation completed in ${implementingExecutions.length} attempt(s)`,
+                'Core task functionality implemented',
+            ];
+        }
+        // Extract file modification info from worktree if available
+        try {
+            const worktree = this.agentService.getWorktreeInfo(workflow.taskId);
+            if (worktree?.path) {
+                context.filesModified = [`Changes made in worktree: ${worktree.branchName}`];
+            }
+        }
+        catch (error) {
+            log.debug('Could not extract worktree info for task update', error, 'vibing-orchestrator');
+        }
+        // Add quality check failures to key changes if any
+        if (workflow.qualityResults?.details) {
+            const failedCategories = Object.entries(workflow.qualityResults.details)
+                .filter(([, passed]) => !passed)
+                .map(([name]) => name);
+            if (failedCategories.length > 0) {
+                context.keyChanges.push(`Quality issues in: ${failedCategories.join(', ')}`);
+            }
+        }
+        return context;
     }
     /**
      * Save workflow to persistence layer
@@ -724,7 +1191,9 @@ export class VibingOrchestrator extends EventEmitter {
         const workflow = this.workflows.get(workflowId);
         if (!workflow)
             return;
-        await this.transitionToPhase(workflowId, 'implementing');
+        // Note: FSM has already transitioned to 'implementing' via START/RETRY event
+        // We only need to update timeline/metrics here for UI observability
+        this.updateUIPhase(workflow, 'implementing');
         try {
             log.info('Implementing task', { taskId: workflow.taskId }, 'vibing-orchestrator');
             // Start task execution with enhanced prompts and workflow context
@@ -737,6 +1206,14 @@ export class VibingOrchestrator extends EventEmitter {
                 (workflow.failureContext?.atPhase
                     ? `Retry after ${workflow.failureContext.atPhase} failure`
                     : undefined);
+            const aiReviewSource = workflow.aiReviewResult || workflow.metadata?.aiReviewResult;
+            const aiReviewContext = aiReviewSource
+                ? {
+                    summary: aiReviewSource.reviewSummary,
+                    recommendations: aiReviewSource.recommendations,
+                    score: aiReviewSource.qualityScore,
+                }
+                : undefined;
             // Prepare to capture executionId from event, then start execution
             const createdPromise = this.waitForExecutionCreated(workflow.taskId, workflowId, 20000);
             // Fire-and-forget; attach catch to prevent unhandled rejection from crashing process
@@ -748,6 +1225,7 @@ export class VibingOrchestrator extends EventEmitter {
                         previousExecutionId: previousExecId,
                         failurePhase: workflow.failureContext?.atPhase,
                         qualityResults: workflow.qualityResults,
+                        aiReview: aiReviewContext,
                         attempt,
                     }
                     : undefined,
@@ -774,17 +1252,16 @@ export class VibingOrchestrator extends EventEmitter {
                 await this.saveWorkflow(workflow);
             }
             log.info('Implementation completed', { taskId: workflow.taskId }, 'vibing-orchestrator');
-            // Update checkpoint status
-            workflow.status = 'implemented';
-            workflow.lastUpdatedAt = new Date().toISOString();
-            await this.saveWorkflow(workflow);
-            await this.transitionToPhase(workflowId, 'implemented');
+            // Dispatch FSM event - reducer handles transition to 'validating' and triggers EXECUTE_VALIDATION effect
+            // In stepByStepMode, the effect is not triggered by reducer, so validation waits for Continue
+            // IMPORTANT: Dispatch before updating UI phase, otherwise toWorkflowState maps 'implemented' -> 'validating'
+            // which causes IMPL_SUCCESS to be an invalid transition (expecting 'implementing' phase)
+            // Note: dispatch already updates the workflow status via applyStateToExecution, so no need to set it again
+            await this.dispatch(workflowId, { type: 'IMPL_SUCCESS', executionId });
             if (workflow.metadata.stepByStepMode) {
                 log.info('Manual step mode – implemented; waiting for Continue to run validation', { workflowId }, 'vibing-orchestrator');
             }
-            else {
-                await this.executeValidation(workflowId);
-            }
+            // Note: In non-stepByStepMode, executeValidation is triggered by reducer's EXECUTE_VALIDATION effect
         }
         catch (error) {
             await this.handlePhaseFailure(workflowId, 'implementing', error);
@@ -792,14 +1269,30 @@ export class VibingOrchestrator extends EventEmitter {
     }
     /**
      * Public: re-run implementation phase on demand
-     * Forces phase to 'implementing' and executes implementation again.
+     * Uses dispatch(RETRY) to transition FSM and trigger implementation via effect.
      */
     async rerunImplementation(workflowId, feedback, providerOverride) {
         const workflow = this.workflows.get(workflowId);
         if (!workflow)
             throw new Error(`Workflow ${workflowId} not found`);
-        await this.transitionToPhase(workflowId, 'implementing');
-        await this.executeImplementation(workflowId, feedback, providerOverride);
+        // Store provider override for the effect to pick up
+        if (providerOverride) {
+            workflow.metadata = workflow.metadata || {};
+            workflow.metadata.aiRoutingOverrides = {
+                ...(workflow.metadata.aiRoutingOverrides || {}),
+                execute_task: providerOverride,
+            };
+        }
+        // Store feedback in failureContext for the implementation to use
+        if (feedback) {
+            workflow.failureContext = {
+                atPhase: workflow.phase,
+                error: feedback,
+                timestamp: new Date().toISOString(),
+            };
+        }
+        // Dispatch RETRY event - reducer handles transition and triggers EXECUTE_IMPLEMENTATION effect
+        await this.dispatch(workflowId, { type: 'RETRY' });
     }
     /**
      * Get previous phase, preferring the phase where failure occurred
@@ -827,8 +1320,8 @@ export class VibingOrchestrator extends EventEmitter {
         await this.resetFromPhase(workflowId, phase);
         switch (phase) {
             case 'implementing':
-                await this.transitionToPhase(workflowId, 'implementing');
-                await this.executeImplementation(workflowId);
+                // Use dispatch(RETRY) to transition FSM and trigger implementation via effect
+                await this.dispatch(workflowId, { type: 'RETRY' });
                 return;
             case 'validating':
                 await this.executeValidation(workflowId);
@@ -851,7 +1344,7 @@ export class VibingOrchestrator extends EventEmitter {
                 return;
             default:
                 // For other phases, restart implementation as a safe default
-                await this.executeImplementation(workflowId);
+                await this.dispatch(workflowId, { type: 'RETRY' });
                 return;
         }
     }
@@ -945,6 +1438,7 @@ export class VibingOrchestrator extends EventEmitter {
                 ...workflow.metadata,
                 aiReviewResult: { ...review, timestamp },
             };
+            workflow.aiReviewResult = { ...review, timestamp };
             // Track execution ID under ai-reviewing for observability
             const executionId = providedExecutionId ?? review?.executionId;
             if (executionId) {
@@ -979,12 +1473,15 @@ export class VibingOrchestrator extends EventEmitter {
     }
     /**
      * Execute AI review as a dedicated phase
+     * Note: 'ai-reviewing' is a UI-only phase for timeline display, not an FSM phase.
+     * FSM remains in 'approved' during AI review.
      */
     async executeAiReviewPhase(workflowId) {
         const workflow = this.workflows.get(workflowId);
         if (!workflow)
             return;
-        await this.transitionToPhase(workflowId, 'ai-reviewing');
+        // Update UI phase for timeline display (FSM stays in 'approved')
+        this.updateUIPhase(workflow, 'ai-reviewing');
         try {
             const attemptList = workflow.executionIds?.['ai-reviewing'] || [];
             const attempt = attemptList.length + 1;
@@ -1051,7 +1548,11 @@ export class VibingOrchestrator extends EventEmitter {
         const workflow = this.workflows.get(workflowId);
         if (!workflow)
             return;
-        await this.transitionToPhase(workflowId, 'awaiting-review');
+        // Update UI phase for timeline display (FSM is in 'approved')
+        // 'awaiting-review' is the UI representation of FSM 'approved' phase
+        this.updateUIPhase(workflow, 'awaiting-review');
+        // Update task file for review readiness
+        await this.updateTaskForReviewReadiness(workflow);
         const hasReal = Array.isArray(workflow.timeline)
             ? workflow.timeline.some((t) => t.phase === 'awaiting-review' && !t.placeholder)
             : false;
@@ -1063,17 +1564,18 @@ export class VibingOrchestrator extends EventEmitter {
                 startTime: new Date().toISOString(),
             });
         }
-        workflow.timeline = this.computeVisibleTimeline(workflow);
         await this.saveWorkflow(workflow);
     }
     /**
      * Execute validation phase with quality checks
+     * Note: FSM has already transitioned to 'validating' via IMPL_SUCCESS event
      */
     async executeValidation(workflowId) {
         const workflow = this.workflows.get(workflowId);
         if (!workflow)
             return;
-        await this.transitionToPhase(workflowId, 'validating');
+        // Update UI phase for timeline display (FSM is already in 'validating')
+        this.updateUIPhase(workflow, 'validating');
         try {
             if (!workflow.metadata.autoQualityChecks) {
                 // TODO implement later
@@ -1088,6 +1590,17 @@ export class VibingOrchestrator extends EventEmitter {
                 workflowId,
                 workingDirectory,
             });
+            const qualityOverride = workflow.metadata?.aiRoutingOverrides?.quality_checks;
+            try {
+                const resolved = await this.agentService.previewProviderForOperation('quality_checks', qualityOverride);
+                const providerLabel = resolved.model
+                    ? `${resolved.provider} (model: ${resolved.model})`
+                    : resolved.provider;
+                await this.agentService.logGenericExecution(execId, `[validation] Using provider: ${providerLabel}`);
+            }
+            catch (err) {
+                log.warn('Failed to resolve quality-check provider', err, 'vibing-orchestrator');
+            }
             workflow.executionIds = workflow.executionIds || {};
             const valList = workflow.executionIds['validating'] || [];
             workflow.executionIds['validating'] = [...valList, execId];
@@ -1156,19 +1669,15 @@ export class VibingOrchestrator extends EventEmitter {
                 return;
             }
             log.info('Quality checks passed', { taskId: workflow.taskId }, 'vibing-orchestrator');
-            // Update checkpoint status
-            await this.transitionToPhase(workflowId, 'validated');
-            workflow.status = 'validated';
-            workflow.lastUpdatedAt = new Date().toISOString();
-            await this.saveWorkflow(workflow);
-            if (workflow.metadata.aiCodeReview) {
-                if (workflow.metadata.stepByStepMode) {
-                    log.info('Manual step mode – waiting for Continue to run AI review', { workflowId }, 'vibing-orchestrator');
-                }
-                else {
-                    await this.executeAiReviewPhase(workflowId);
-                }
+            // Dispatch FSM event - reducer handles transition to 'approved' and may trigger AI review
+            // IMPORTANT: Dispatch before updating UI phase, otherwise toWorkflowState maps 'validated' -> 'approved'
+            // which causes VALID_SUCCESS to be an invalid transition (expecting 'validating' phase)
+            // Note: dispatch already updates the workflow status via applyStateToExecution, so no need to set it again
+            await this.dispatch(workflowId, { type: 'VALID_SUCCESS', results: qualityResults });
+            if (workflow.metadata.stepByStepMode) {
+                log.info('Manual step mode – waiting for Continue to run AI review', { workflowId }, 'vibing-orchestrator');
             }
+            // Note: In non-stepByStepMode with aiCodeReview, executeAiReviewPhase is triggered by reducer's EXECUTE_AI_REVIEW effect
         }
         catch (error) {
             await this.handlePhaseFailure(workflowId, 'validating', error);
@@ -1185,12 +1694,14 @@ export class VibingOrchestrator extends EventEmitter {
     }
     /**
      * Execute merge phase
+     * Note: FSM has already transitioned to 'merging' via APPROVE event
      */
     async executeMerge(workflowId, providerOverride) {
         const workflow = this.workflows.get(workflowId);
         if (!workflow)
             return;
-        await this.transitionToPhase(workflowId, 'merging');
+        // Update UI phase for timeline display (FSM is already in 'merging')
+        this.updateUIPhase(workflow, 'merging');
         let executionId;
         try {
             log.info('AI merging changes', { taskId: workflow.taskId }, 'vibing-orchestrator');
@@ -1227,30 +1738,39 @@ export class VibingOrchestrator extends EventEmitter {
             if (!mergeExec || mergeExec.status !== 'completed') {
                 throw new Error(`AI merge failed: ${mergeExec?.error || 'Unknown error'}`);
             }
+            // Verify merge actually succeeded by checking git state
+            const mergeVerification = await this.verifyMergeSuccess(workflow.taskId, executionId);
+            if (!mergeVerification.success) {
+                throw new Error(`Merge verification failed: ${mergeVerification.error}`);
+            }
             const latest = this.workflows.get(workflowId) || workflow;
             const timeline = (latest.timeline || []);
             const tMerge = timeline.find((t) => t.executionId === executionId);
             if (tMerge) {
                 tMerge.endTime = mergeExec.endTime || new Date().toISOString();
                 tMerge.usage = mergeExec.usage;
+                if (mergeVerification.mergeCommit) {
+                    tMerge.mergeCommit = mergeVerification.mergeCommit;
+                }
                 latest.timeline = this.computeVisibleTimeline(latest);
                 latest.lastUpdatedAt = new Date().toISOString();
                 await this.saveWorkflow(latest);
             }
-            await this.taskService.updateTask(workflow.taskId, { status: 'done' });
-            await this.transitionToPhase(workflowId, 'merged');
-            const mergedWorkflow = this.workflows.get(workflowId);
-            if (mergedWorkflow) {
-                mergedWorkflow.status = 'merged';
-                mergedWorkflow.lastUpdatedAt = new Date().toISOString();
-                await this.saveWorkflow(mergedWorkflow);
+            // Store merge commit in workflow links
+            if (mergeVerification.mergeCommit) {
+                workflow.links = workflow.links || {};
+                workflow.links.mergeCommit = mergeVerification.mergeCommit;
             }
+            await this.taskService.updateTask(workflow.taskId, { status: 'done' });
+            // Dispatch FSM event - reducer handles transition to 'done' and triggers cleanup effect
+            // IMPORTANT: Dispatch before updating UI phase, otherwise toWorkflowState maps 'merged' -> 'done'
+            // which causes MERGE_SUCCESS to be an invalid transition (expecting 'merging' phase)
+            // Note: dispatch already updates the workflow status via applyStateToExecution, so no need to set it again
+            await this.dispatch(workflowId, { type: 'MERGE_SUCCESS' });
             if (workflow.metadata.stepByStepMode) {
                 log.info('Manual step mode – merge completed; waiting for Continue', { workflowId }, 'vibing-orchestrator');
             }
-            else {
-                await this.updateCleanupStatus(workflowId);
-            }
+            // Note: In non-stepByStepMode, executeCleanup is triggered by reducer's EXECUTE_CLEANUP effect
             log.info('Merge completed, ready for cleanup', { taskId: workflow.taskId }, 'vibing-orchestrator');
         }
         catch (error) {
@@ -1271,21 +1791,98 @@ export class VibingOrchestrator extends EventEmitter {
             await this.handlePhaseFailure(workflowId, 'merging', error);
         }
     }
-    async updateCleanupStatus(workflowId) {
-        const workflow = this.workflows.get(workflowId);
-        if (!workflow)
-            return;
-        await this.transitionToPhase(workflowId, 'cleaning');
-        workflow.status = 'cleaning';
-        workflow.lastUpdatedAt = new Date().toISOString();
-        workflow.timeline = this.buildTimeline(workflow, {
-            id: `cleaning:${new Date().toISOString()}`,
-            label: 'Cleaning',
-            phase: 'cleaning',
-            startTime: new Date().toISOString(),
-        });
-        await this.saveWorkflow(workflow);
-        this.emit('workflowUpdated', workflow);
+    /**
+     * Verify that a merge actually succeeded by checking git state
+     */
+    async verifyMergeSuccess(taskId, executionId) {
+        try {
+            const worktree = this.worktreeService.getWorktree(taskId);
+            if (!worktree) {
+                return { success: false, error: 'No worktree found for task' };
+            }
+            const gitService = this.worktreeService.getGitService();
+            const mainRepoPath = gitService.getProjectRoot();
+            // Check 1: Verify we're on the main branch and it's clean
+            const { spawn } = await import('child_process');
+            const execGit = (args, cwd) => {
+                return new Promise((resolve) => {
+                    const child = spawn('git', args, { cwd, stdio: ['ignore', 'pipe', 'pipe'] });
+                    let stdout = '';
+                    let stderr = '';
+                    child.stdout?.on('data', (d) => (stdout += d.toString()));
+                    child.stderr?.on('data', (d) => (stderr += d.toString()));
+                    child.on('close', (code) => resolve({ stdout: stdout.trim(), exitCode: code ?? 1 }));
+                    child.on('error', () => resolve({ stdout: '', exitCode: 1 }));
+                });
+            };
+            // Get current branch in main repo
+            const branchResult = await execGit(['branch', '--show-current'], mainRepoPath);
+            const currentBranch = branchResult.stdout;
+            // Get git status
+            const statusResult = await execGit(['status', '--porcelain'], mainRepoPath);
+            const hasUncommittedChanges = statusResult.stdout.length > 0;
+            // Check if the feature branch commits are in the current branch
+            const featureBranch = worktree.branchName;
+            const logResult = await execGit(['log', '--oneline', '-20', '--grep', featureBranch], mainRepoPath);
+            // Also check for recent merge commits
+            const mergeLogResult = await execGit(['log', '--oneline', '-5', '--merges'], mainRepoPath);
+            // Get the latest commit hash
+            const headResult = await execGit(['rev-parse', 'HEAD'], mainRepoPath);
+            const latestCommit = headResult.stdout;
+            // Parse execution logs to check for MERGE_STATUS
+            let aiReportedSuccess = false;
+            let aiReportedFailure = false;
+            try {
+                const execLogs = await this.agentService.getPersistedExecutionLogs(executionId);
+                const logText = execLogs.logs.map((l) => l.message || '').join('\n');
+                if (logText.includes('MERGE_STATUS: SUCCESS')) {
+                    aiReportedSuccess = true;
+                }
+                if (logText.includes('MERGE_STATUS: FAILED') || logText.includes('unable to proceed')) {
+                    aiReportedFailure = true;
+                }
+            }
+            catch {
+                // Ignore log parsing errors
+            }
+            // Determine success based on multiple signals
+            if (aiReportedFailure) {
+                return { success: false, error: 'AI reported merge failure' };
+            }
+            if (hasUncommittedChanges) {
+                return { success: false, error: 'Main repo has uncommitted changes after merge' };
+            }
+            // Check if we're on main/master and feature branch content was merged
+            const isOnMainBranch = ['main', 'master'].includes(currentBranch);
+            if (!isOnMainBranch && !aiReportedSuccess) {
+                return {
+                    success: false,
+                    error: `Not on main branch after merge (current: ${currentBranch})`,
+                };
+            }
+            // If AI reported success or we detect merge evidence, consider it successful
+            const hasMergeEvidence = mergeLogResult.stdout.includes(featureBranch) ||
+                logResult.stdout.length > 0 ||
+                aiReportedSuccess;
+            if (hasMergeEvidence || aiReportedSuccess) {
+                log.info('Merge verification passed', { taskId, currentBranch, latestCommit, aiReportedSuccess }, 'vibing-orchestrator');
+                return { success: true, mergeCommit: latestCommit };
+            }
+            // Fallback: if status is clean and we're on main, accept it
+            if (isOnMainBranch && !hasUncommittedChanges) {
+                log.info('Merge verification passed (clean state)', { taskId, currentBranch }, 'vibing-orchestrator');
+                return { success: true, mergeCommit: latestCommit };
+            }
+            return {
+                success: false,
+                error: 'Could not verify merge completion - no merge evidence found',
+            };
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            log.error('Merge verification error', { taskId, error: msg }, 'vibing-orchestrator');
+            return { success: false, error: `Verification error: ${msg}` };
+        }
     }
     /**
      * Public: run merge phase on demand
@@ -1299,12 +1896,15 @@ export class VibingOrchestrator extends EventEmitter {
     }
     /**
      * Execute cleanup phase: remove worktree/branch and finalize workflow
+     * Note: FSM has already transitioned to 'done' via MERGE_SUCCESS event
      */
     async executeCleanup(workflowId) {
         const workflow = this.workflows.get(workflowId);
         if (!workflow)
             return;
-        await this.transitionToPhase(workflowId, 'cleaning');
+        // Update UI phase for timeline display
+        workflow.status = 'cleaning';
+        this.updateUIPhase(workflow, 'cleaning');
         try {
             log.info('Cleaning up resources', { taskId: workflow.taskId }, 'vibing-orchestrator');
             // Remove worktree and local branch if present
@@ -1314,12 +1914,14 @@ export class VibingOrchestrator extends EventEmitter {
             catch (err) {
                 log.warn('Cleanup encountered an issue (continuing)', err, 'vibing-orchestrator');
             }
-            // Finalize workflow
+            // Finalize workflow - update UI phases
             workflow.status = 'cleaned';
             workflow.endTime = new Date().toISOString();
-            await this.transitionToPhase(workflowId, 'cleaned');
+            this.updateUIPhase(workflow, 'cleaned');
+            // Dispatch FSM event for cleanup completion
+            await this.dispatch(workflowId, { type: 'CLEAN_SUCCESS' });
             workflow.status = 'completed';
-            workflow.lastUpdatedAt = new Date().toISOString();
+            this.updateUIPhase(workflow, 'completed');
             await this.saveWorkflow(workflow);
             this.emit('workflowCompleted', workflow);
             log.info('Workflow completed', { taskId: workflow.taskId }, 'vibing-orchestrator');
@@ -1332,9 +1934,13 @@ export class VibingOrchestrator extends EventEmitter {
                 error: workflow.error,
                 timestamp: new Date().toISOString(),
             };
-            await this.transitionToPhase(workflowId, 'failed');
+            // Dispatch failure event
+            await this.dispatch(workflowId, {
+                type: 'CLEAN_FAIL',
+                error: workflow.error,
+            });
             workflow.status = 'failed';
-            workflow.lastUpdatedAt = new Date().toISOString();
+            this.updateUIPhase(workflow, 'failed');
             await this.saveWorkflow(workflow);
             this.emit('workflowFailed', workflow);
         }
@@ -1396,11 +2002,13 @@ export class VibingOrchestrator extends EventEmitter {
         const nextPhase = idx >= 0 && idx < ordered.length - 1 ? ordered[idx + 1] : 'completed';
         if (nextPhase && nextPhase !== workflow.phase) {
             log.info('Manually skipping workflow phase', { workflowId, currentPhase: workflow.phase, basePhase, nextPhase }, 'vibing-orchestrator');
-            await this.transitionToPhase(workflowId, nextPhase);
+            // Update UI phase directly for skipping (FSM dispatch may not support all UI phases)
+            this.updateUIPhase(workflow, nextPhase);
+            await this.saveWorkflow(workflow);
             // Immediately kick off the next phase where applicable to make skipping faster
             switch (nextPhase) {
                 case 'implementing':
-                    await this.executeImplementation(workflowId);
+                    await this.dispatch(workflowId, { type: 'RETRY' });
                     break;
                 case 'validating':
                     await this.executeValidation(workflowId);
@@ -1612,32 +2220,32 @@ export class VibingOrchestrator extends EventEmitter {
     }
     /**
      * Continue workflow execution from current state
+     * Uses the new state machine to determine the next action
      */
     async continueWorkflow(workflowId) {
         const workflow = this.workflows.get(workflowId);
         if (!workflow) {
             throw new Error(`Workflow ${workflowId} not found`);
         }
-        log.info('Continuing workflow (status-driven)', { workflowId, phase: workflow.phase, status: workflow.status }, 'vibing-orchestrator');
-        // If failed, prefer immediate retry of implementation
-        if (workflow.phase === 'failed' || workflow.status === 'failed') {
-            if (workflow.metadata.stepByStepMode) {
-                await this.rerunImplementation(workflowId);
-            }
-            else {
-                await this.executeImplementation(workflowId);
-            }
-            return;
-        }
-        // Compute next actionable phase from status/checkpoint
-        const next = this.computeNextActionPhase(workflow);
-        if (!next) {
-            log.info('No actionable next phase (waiting for human or already done)', { workflowId, phase: workflow.phase, status: workflow.status }, 'vibing-orchestrator');
+        // Use new state machine to compute next action
+        const nextAction = this.getNextAction(workflowId);
+        log.info('Continuing workflow (state-machine-driven)', {
+            workflowId,
+            phase: workflow.phase,
+            status: workflow.status,
+            nextAction: nextAction?.action,
+        }, 'vibing-orchestrator');
+        if (!nextAction || nextAction.action === 'none') {
+            log.info('No actionable next step', {
+                workflowId,
+                phase: workflow.phase,
+                reason: nextAction?.action === 'none' ? nextAction.reason : 'null action',
+            }, 'vibing-orchestrator');
             return;
         }
-        switch (next) {
+        switch (nextAction.action) {
             case 'implementing':
-                await this.executeImplementation(workflowId);
+                await this.executeImplementation(workflowId, nextAction.feedback);
                 return;
             case 'validating':
                 await this.executeValidation(workflowId);
@@ -1645,56 +2253,17 @@ export class VibingOrchestrator extends EventEmitter {
             case 'ai-reviewing':
                 await this.executeAiReviewPhase(workflowId);
                 return;
-            case 'awaiting-review':
+            case 'awaiting-approval':
                 await this.executeAwaitingReview(workflowId);
                 return;
             case 'merging':
                 await this.executeMerge(workflowId);
                 return;
-            case 'cleaning':
+            case 'cleanup':
                 await this.executeCleanup(workflowId);
                 return;
             default:
-                throw new Error(`Unsupported next phase computed: ${next}`);
-        }
-    }
-    // Decide next action from status/checkpoint and configuration
-    computeNextActionPhase(workflow) {
-        const status = workflow.status;
-        const cfg = workflow.metadata || {};
-        const requireHuman = !!cfg.requireHumanApproval;
-        const wantsAIReview = !!cfg.aiCodeReview;
-        // If paused, compute by last checkpoint
-        // If failed handling is done earlier
-        switch (status) {
-            case undefined:
-            case 'draft':
-                return 'implementing';
-            case 'implemented':
-                return 'validating';
-            case 'validated':
-                if (wantsAIReview)
-                    return 'ai-reviewing';
-                return requireHuman ? null : 'merging';
-            case 'ai-reviewed':
-                return requireHuman ? null : 'merging';
-            case 'awaiting-review':
-                return null; // wait for approveWorkflow
-            case 'approved':
-                return 'merging';
-            case 'merged':
-                return 'cleaning';
-            case 'cleaned':
-                return 'completed';
-            case 'completed':
-                return null;
-            case 'paused':
-                // Map paused to next by lastPhase or default to implementing
-                return workflow.lastPhase || 'implementing';
-            case 'failed':
-                return 'implementing';
-            default:
-                return null;
+                log.warn('Unknown next action from state machine', { workflowId, action: nextAction.action }, 'vibing-orchestrator');
         }
     }
     // ============ Small helpers to reduce duplication ============
@@ -1778,8 +2347,14 @@ export class VibingOrchestrator extends EventEmitter {
         const max = workflow.metadata.retryPolicy?.maxImplementationAttempts || 0;
         const implementingCount = (workflow.phaseHistory || []).filter((h) => h.to === 'implementing').length;
         if (max > 0 && implementingCount < max) {
-            await this.transitionToPhase(workflowId, 'implementing');
-            await this.executeImplementation(workflowId, reason);
+            // Store reason in failureContext for the implementation to use
+            workflow.failureContext = {
+                atPhase: workflow.phase,
+                error: reason,
+                timestamp: new Date().toISOString(),
+            };
+            // Dispatch RETRY event - reducer handles transition and triggers EXECUTE_IMPLEMENTATION effect
+            await this.dispatch(workflowId, { type: 'RETRY' });
             return true;
         }
         return false;
@@ -1806,12 +2381,31 @@ export class VibingOrchestrator extends EventEmitter {
             }
             await this.saveWorkflow(wf);
         }
-        await this.transitionToPhase(workflowId, 'failed');
+        // Dispatch appropriate failure event based on phase
+        const failEvent = this.getFailEventForPhase(atPhase, msg);
+        if (failEvent) {
+            await this.dispatch(workflowId, failEvent);
+        }
+        // Update UI phase
         workflow.status = 'failed';
-        workflow.lastUpdatedAt = new Date().toISOString();
+        this.updateUIPhase(workflow, 'failed');
         await this.saveWorkflow(workflow);
         this.emit('workflowFailed', workflow);
     }
+    getFailEventForPhase(phase, error) {
+        switch (phase) {
+            case 'implementing':
+                return { type: 'IMPL_FAIL', error, canRetry: false };
+            case 'validating':
+                return { type: 'VALID_FAIL', error };
+            case 'merging':
+                return { type: 'MERGE_FAIL', error };
+            case 'cleaning':
+                return { type: 'CLEAN_FAIL', error };
+            default:
+                return null;
+        }
+    }
     /**
      * Get the agent service instance
      */
@@ -1831,6 +2425,14 @@ function serializeVibe(workflow) {
                 timestamp: new Date(workflow.qualityResults.timestamp).toISOString(),
             }
             : undefined,
+        aiReviewResult: workflow.aiReviewResult
+            ? {
+                ...workflow.aiReviewResult,
+                timestamp: workflow.aiReviewResult.timestamp
+                    ? new Date(workflow.aiReviewResult.timestamp).toISOString()
+                    : undefined,
+            }
+            : undefined,
     };
 }
 async function getDbStats(db) {