Optimistic UI Updates for Instant Feedback

apps/frontend/src/renderer/components/KanbanBoard.tsx

@@ -32,7 +32,7 @@
 import { QueueSettingsModal } from './QueueSettingsModal';
 import { TASK_STATUS_COLUMNS, TASK_STATUS_LABELS } from '../../shared/constants';
 import { cn, shallowEqual } from '../lib/utils';
-import { persistTaskStatus, forceCompleteTask, archiveTasks, useTaskStore } from '../stores/task-store';
+import { persistTaskStatus, forceCompleteTask, archiveTasks, useTaskStore, createOptimisticTaskAction } from '../stores/task-store';
 import { updateProjectSettings, useProjectStore } from '../stores/project-store';
 import { useKanbanSettingsStore, COLLAPSED_COLUMN_WIDTH, DEFAULT_COLUMN_WIDTH, MIN_COLUMN_WIDTH, MAX_COLUMN_WIDTH } from '../stores/kanban-settings-store';
 import { useToast } from '../hooks/use-toast';
@@ -990,27 +990,44 @@
    */
   const handleStatusChange = async (taskId: string, newStatus: TaskStatus, providedTask?: Task) => {
     const task = providedTask || tasks.find(t => t.id === taskId);
-    const result = await persistTaskStatus(taskId, newStatus);
+    if (!task) return;
 
-    if (!result.success) {
-      if (result.worktreeExists) {
-        // Show the worktree cleanup dialog
-        setWorktreeCleanupDialog({
-          open: true,
-          taskId: taskId,
-          taskTitle: task?.title || t('tasks:untitled'),
-          worktreePath: result.worktreePath,
-          isProcessing: false,
-          error: undefined
-        });
-      } else {
-        // Show error toast for other failures
-        toast({
-          title: t('common:errors.operationFailed'),
-          description: result.error || t('common:errors.unknownError'),
-          variant: 'destructive'
-        });
-      }
+    const previousStatus = task.status;
+
+    try {
+      // Optimistic update: immediately update UI
+      await createOptimisticTaskAction(
+        taskId,
+        (t) => ({ status: newStatus }),
+        async () => {
+          // Call backend API
+          const result = await persistTaskStatus(taskId, newStatus);
+          if (!result.success) {
+            if (result.worktreeExists) {
+              // Show worktree cleanup dialog
+              setWorktreeCleanupDialog({
+                open: true,
+                taskId: taskId,
+                taskTitle: task?.title || t('tasks:untitled'),
+                worktreePath: result.worktreePath,
+                isProcessing: false,
+                error: undefined
+              });
+            } else {
+              // Throw to trigger rollback
+              throw new Error(result.error || 'Failed to update task status');
+            }
+          }
+        }
+      );
+    } catch (error) {
+      // Rollback handled by createOptimisticTaskAction
+      // Show error toast
+      toast({
+        title: t('common:errors.operationFailed'),
+        description: error instanceof Error ? error.message : t('common:errors.unknownError'),
+        variant: 'destructive'
+      });
     }
   };
 

apps/frontend/src/renderer/components/TaskCard.tsx

@@ -32,7 +32,8 @@
   JSON_ERROR_PREFIX,
   JSON_ERROR_TITLE_SUFFIX
 } from '../../shared/constants';
-import { startTask, stopTask, checkTaskRunning, recoverStuckTask, isIncompleteHumanReview, archiveTasks } from '../stores/task-store';
+import { startTask, stopTask, checkTaskRunning, recoverStuckTask, isIncompleteHumanReview, archiveTasks, archiveTaskOptimistic } from '../stores/task-store';
+import { useToast } from '../hooks/use-toast';
 import type { Task, TaskCategory, ReviewReason, TaskStatus } from '../../shared/types';
 
 // Module-level visibility change singleton — one listener for all TaskCard instances
@@ -169,6 +170,7 @@
   onToggleSelect
 }: TaskCardProps) {
   const { t } = useTranslation(['tasks', 'errors']);
+  const { toast } = useToast();
   const [isStuck, setIsStuck] = useState(false);
   const [isRecovering, setIsRecovering] = useState(false);
   const stuckCheckRef = useRef<{ timeout: NodeJS.Timeout | null; interval: NodeJS.Timeout | null }>({
@@ -308,14 +310,44 @@
     };
   }, [isRunning, performStuckCheck]);
 
-  const handleStartStop = (e: React.MouseEvent) => {
+  const handleStartStop = useCallback(async (e: React.MouseEvent) => {
     e.stopPropagation();
-    if (isRunning && !isStuck) {
-      stopTask(task.id);
-    } else {
-      startTask(task.id);
+
+    // Capture previous status for revert
+    const previousStatus = task.status;
+
+    // Determine new status optimistically
+    const newStatus: TaskStatus = (isRunning && !isStuck) ? 'backlog' : 'in_progress';
+
+    // Apply optimistic update by calling onStatusChange if available
+    // This provides immediate UI feedback
+    if (onStatusChange) {
+      onStatusChange(newStatus);
     }
-  };
+
+    try {
+      // Actually start/stop the task on the backend
+      if (isRunning && !isStuck) {
+        await stopTask(task.id);
+      } else {
+        await startTask(task.id);
+      }
+      // If successful, the optimistic update is now the actual state
+      // The task store will emit updates that sync everything
+    } catch (error) {
+      // Revert optimistic update on failure
+      console.error('[TaskCard] Failed to start/stop task, reverting:', error);
+      if (onStatusChange && previousStatus !== newStatus) {
+        onStatusChange(previousStatus);
+      }
+      // Show error toast
+      toast({
+        title: 'Action Failed',
+        description: `Could not ${isRunning ? 'stop' : 'start'} task. Please try again.`,
+        variant: 'destructive'
+      });
+    }
+  }, [task.id, task.status, isRunning, isStuck, onStatusChange]);
 
   const handleRecover = async (e: React.MouseEvent) => {
     e.stopPropagation();
@@ -330,9 +362,19 @@
 
   const handleArchive = async (e: React.MouseEvent) => {
     e.stopPropagation();
-    const result = await archiveTasks(task.projectId, [task.id]);
-    if (!result.success) {
-      console.error('[TaskCard] Failed to archive task:', task.id, result.error);
+    // Optimistic archive - immediately updates UI with archivedAt timestamp
+    // The archiveTaskOptimistic function handles rollback on error
+    try {
+      await archiveTaskOptimistic(task.projectId, task.id);
+    } catch (error) {
+      // Error is already logged by archiveTaskOptimistic
+      console.error('[TaskCard] Archive failed, UI reverted:', error);
+      // Show error toast
+      toast({
+        title: 'Archive Failed',
+        description: 'Could not archive task. Please try again.',
+        variant: 'destructive'
+      });
     }
   };
 

apps/frontend/src/renderer/stores/task-store.ts

@@ -203,6 +203,120 @@
   }
 }
 
+/**
+ * Creates an optimistic update action for instant UI feedback with automatic revert on error
+ *
+ * This helper follows the pattern from UsageIndicator.tsx:
+ * 1. Capture previous state for potential revert
+ * 2. Apply optimistic update immediately for instant feedback
+ * 3. Execute async operation
+ * 4. Revert to previous state if operation fails
+ *
+ * @param getState - Function to get current state
+ * @param setState - Function to update state
+ * @param optimisticUpdate - Function to calculate optimistic state from current state
+ * @param asyncOperation - The async operation to perform (e.g., API call)
+ * @param onError - Optional custom error handler (default: console.error)
+ * @returns Promise with the result of the async operation
+ *
+ * @example
+ * ```typescript
+ * await createOptimisticAction(
+ *   () => useTaskStore.getState(),
+ *   (state) => useTaskStore.setState(state),
+ *   (state) => ({
+ *     ...state,
+ *     tasks: state.tasks.map(t => t.id === taskId ? { ...t, status: 'done' } : t)
+ *   }),
+ *   async () => {
+ *     await window.electronAPI.updateTaskStatus(taskId, 'done');
+ *   }
+ * );
+ * ```
+ */
+export async function createOptimisticAction<T>(
+  getState: () => T,
+  setState: (state: T | Partial<T>) => void,
+  optimisticUpdate: (currentState: T) => T | Partial<T>,
+  asyncOperation: () => Promise<void>,
+  onError?: (error: Error) => void
+): Promise<void> {
+  // Capture previous state for revert (before any changes)
+  const previousState = getState();
+
+  try {
+    // Calculate and apply optimistic update immediately
+    const optimisticState = optimisticUpdate(previousState);
+    setState(optimisticState);
+
+    // Execute the actual async operation
+    await asyncOperation();
+  } catch (error) {
+    // Revert to captured previous state on error
+    setState(previousState);
+
+    // Call custom error handler or default to console.error
+    if (onError) {
+      onError(error as Error);
+    } else {
+      console.error('[createOptimisticAction] Operation failed, reverted state:', error);
+    }
+
+    // Re-throw for caller to handle if needed
+    throw error;
+  }
+}
+
+/**
+ * Creates an optimistic action specifically for task updates
+ * Convenience wrapper around createOptimisticAction for task-store operations
+ *
+ * @param taskId - The task ID to update
+ * @param optimisticUpdate - Function to calculate optimistic task state
+ * @param asyncOperation - The async operation to perform
+ * @param onError - Optional custom error handler
+ * @returns Promise that resolves when operation completes
+ *
+ * @example
+ * ```typescript
+ * await createOptimisticTaskAction(
+ *   taskId,
+ *   (task) => ({ ...task, status: 'done' }),
+ *   async () => {
+ *     await window.electronAPI.completeTask(taskId);
+ *   }
+ * );
+ * ```
+ */
+export async function createOptimisticTaskAction(
+  taskId: string,
+  optimisticUpdate: (task: Task) => Partial<Task>,
+  asyncOperation: () => Promise<void>,
+  onError?: (error: Error) => void
+): Promise<void> {
+  await createOptimisticAction(
+    () => useTaskStore.getState(),
+    (state) => useTaskStore.setState(state),
+    (state) => {
+      const taskIndex = findTaskIndex(state.tasks, taskId);
+      if (taskIndex === -1) {
+        debugLog('[createOptimisticTaskAction] Task not found:', taskId);
+        return state;
+      }
+
+      const updatedTasks = updateTaskAtIndex(
+        state.tasks,
+        taskIndex,
+        (task) => ({ ...task, ...optimisticUpdate(task) })
+      );
+
+      return { ...state, tasks: updatedTasks };
+    },
+    asyncOperation,
+    onError
+  );
+}
+
 export const useTaskStore = create<TaskState>((set, get) => ({
   tasks: [],
   selectedTaskId: null,
@@ -829,6 +943,64 @@
   window.electronAPI.stopTask(taskId);
 }
 
+/**
+ * Start a task with optimistic UI update
+ * Immediately updates the task status to 'in_progress' before server confirmation,
+ * with automatic rollback on error.
+ *
+ * @param taskId - The task ID to start
+ * @param options - Optional configuration (parallel execution, worker count)
+ * @throws Error if task not found or start operation fails
+ */
+export async function startTaskOptimistic(
+  taskId: string,
+  options?: { parallel?: boolean; workers?: number }
+): Promise<void> {
+  await createOptimisticTaskAction(
+    taskId,
+    (task) => {
+      // Optimistic update: change status to 'in_progress'
+      return {
+        status: 'in_progress' as const,
+      };
+    },
+    async () => {
+      // Call the backend API to start the task
+      await window.electronAPI.startTask(taskId, options);
+    },
+    (error) => {
+      console.error('[startTaskOptimistic] Failed to start task:', error);
+    }
+  );
+}
+
+/**
+ * Stop a task with optimistic UI update
+ * Immediately updates the task status back to 'backlog'
+ * before server confirmation, with automatic rollback on error.
+ *
+ * @param taskId - The task ID to stop
+ * @throws Error if task not found or stop operation fails
+ */
+export async function stopTaskOptimistic(taskId: string): Promise<void> {
+  await createOptimisticTaskAction(
+    taskId,
+    (task) => {
+      // Optimistic update: revert to 'backlog' (most common pre-start status)
+      return {
+        status: 'backlog' as const,
+      };
+    },
+    async () => {
+      // Call the backend API to stop the task
+      await window.electronAPI.stopTask(taskId);
+    },
+    (error) => {
+      console.error('[stopTaskOptimistic] Failed to stop task:', error);
+    }
+  );
+}
+
 /**
  * Submit review for a task
  */
@@ -1061,6 +1233,43 @@
 // Task Creation Draft Management
 // ============================================
 
+/**
+ * Archive a single task with optimistic UI update
+ * Immediately adds archivedAt timestamp before server confirmation,
+ * with automatic rollback on error.
+ *
+ * @param projectId - The project ID
+ * @param taskId - The task ID to archive
+ * @throws Error if task not found or archive operation fails
+ */
+export async function archiveTaskOptimistic(
+  projectId: string,
+  taskId: string
+): Promise<void> {
+  await createOptimisticTaskAction(
+    taskId,
+    (task) => {
+      // Optimistic update: add archivedAt timestamp
+      return {
+        metadata: {
+          ...task.metadata,
+          archivedAt: new Date().toISOString(),
+        },
+      };
+    },
+    async () => {
+      // Call the backend API to archive the task
+      const result = await window.electronAPI.archiveTasks(projectId, [taskId]);
+      if (!result.success) {
+        throw new Error(result.error || 'Failed to archive task');
+      }
+    },
+    (error) => {
+      console.error('[archiveTaskOptimistic] Failed to archive task:', error);
+    }
+  );
+}
+
 const DRAFT_KEY_PREFIX = 'task-creation-draft';
 
 /**