jettypod 4.4.118 → 4.4.121

package/apps/dashboard/components/RealTimeKanbanWrapper.tsx

@@ -1,22 +1,20 @@
-'use client';
-
-import { useState, useCallback, useEffect, useRef } from 'react';
+import { useState, useCallback, useEffect, useRef, useMemo, startTransition } from 'react';
+import { useSearchParams, useNavigate } from 'react-router-dom';
 import { KanbanBoard } from './KanbanBoard';
+import { OnboardingWelcome } from './OnboardingWelcome';
 import { useToast } from './Toast';
 import { useWebSocket, type WebSocketMessage } from '../hooks/useWebSocket';
-import { useClaudeSession } from '../contexts/ClaudeSessionContext';
+import { useSessionState, useSessionActions, useSessionPersistence } from '../contexts/ClaudeSessionContext';
 import { useConnectionStatus } from '../contexts/ConnectionStatusContext';
 import { useUsage } from '../contexts/UsageContext';
-import { UpgradeBanner } from './UpgradeBanner';
-import type { InFlightItem, KanbanGroup, WorkItem } from '@/lib/db';
-import { UndoStack, type UndoAction } from '@/lib/undoStack';
+import type { InFlightItem, KanbanGroup } from '@/lib/db';
+import { invoke } from '@/lib/tauri';
+import { dataBridge, invalidateKanbanCache, isLocalMutationRecent, markLocalMutation, patchKanbanItem } from '@/lib/data-bridge';
 import { getRegistry } from '@/lib/stream-manager-registry';
-
-interface KanbanData {
-  inFlight: InFlightItem[];
-  backlog: Map<string, KanbanGroup>;
-  done: Map<string, KanbanGroup>;
-}
+import { getWebSocketUrl } from '@/lib/utils';
+import { type KanbanData, findItemById, getOnboardingItems, buildStatusMap, buildModeMap, applyStatusChange, applyTitleChange, applyOrderChange, applyEpicAssign } from '@/lib/kanban-utils';
+import { useKanbanUndo } from '../hooks/useKanbanUndo';
+import { useKanbanAnimation } from '../hooks/useKanbanAnimation';
 
 interface RealTimeKanbanWrapperProps {
   initialData: {
@@ -28,133 +26,81 @@ interface RealTimeKanbanWrapperProps {
   projectPath?: string;
 }
 
-// Helper to find item by ID in the kanban data
-function findItemById(data: KanbanData, id: number): { item: InFlightItem; status: string } | null {
-  // Check in-flight (status: in_progress)
-  const inFlightItem = data.inFlight.find(item => item.id === id);
-  if (inFlightItem) return { item: inFlightItem, status: 'in_progress' };
-
-  // Check backlog groups
-  for (const group of data.backlog.values()) {
-    const backlogItem = group.items.find(item => item.id === id);
-    if (backlogItem) return { item: backlogItem as InFlightItem, status: 'backlog' };
-  }
-
-  // Check done groups
-  for (const group of data.done.values()) {
-    const doneItem = group.items.find(item => item.id === id);
-    if (doneItem) return { item: doneItem as InFlightItem, status: 'done' };
-  }
-
-  return null;
-}
-
 // Component uses context providers from AppShell (ToastProvider, ClaudeSessionProvider)
 // DO NOT wrap with duplicate providers - it creates isolated context state
 export function RealTimeKanbanWrapper({ initialData, isBlank, projectPath }: RealTimeKanbanWrapperProps) {
+  const [searchParams] = useSearchParams();
+  const navigate = useNavigate();
   const { showToast } = useToast();
   const { allowed: usageAllowed } = useUsage();
-  const [data, setData] = useState<KanbanData>(() => ({
-    inFlight: initialData.inFlight,
-    backlog: new Map(initialData.backlog),
-    done: new Map(initialData.done),
-  }));
-  const [statusError, setStatusError] = useState<string | null>(null);
-
-  // Use ClaudeSessionContext for session state and actions
-  // Note: ClaudePanel is rendered by AppShell, which handles most session UI
-  // This component only needs session state for KanbanBoard integration
-  const {
-    setClaudePanelOpen,
-    sessions,
-    setSessions,
-    standaloneSessions,
-    openSession,
-    switchSession,
-    createAddToBacklogSession,
-    createWelcomeSession,
-  } = useClaudeSession();
-
-  // Auto-open welcome session for blank projects (once per project lifetime)
-  const welcomeTriggeredRef = useRef(false);
-  useEffect(() => {
-    if (isBlank && !welcomeTriggeredRef.current) {
-      try {
-        const welcomeKey = `jettypod-welcome-shown-${projectPath || 'default'}`;
-        if (localStorage.getItem(welcomeKey)) return;
-        welcomeTriggeredRef.current = true;
-        localStorage.setItem(welcomeKey, 'true');
-      } catch {
-        // localStorage unavailable (private browsing, full storage) — proceed anyway
-        welcomeTriggeredRef.current = true;
-      }
-      createWelcomeSession().catch((err) => {
-        console.error('[RealTimeKanbanWrapper] Welcome session failed:', err);
-      });
-    }
-  }, [isBlank, createWelcomeSession]);
-
-  // Undo/redo stack - created once per component instance
-  const [undoStack] = useState(() => new UndoStack());
-  const [undoRedoVersion, setUndoRedoVersion] = useState(0); // Force re-render on stack changes
-
-  // External completion animation state
-  const [externalAnimatingItemId, setExternalAnimatingItemId] = useState<number | null>(null);
-  const pendingDataRef = useRef<KanbanData | null>(null);
-
-  // Track items animated internally so WebSocket handler skips them
-  const lastInternallyAnimatedIdRef = useRef<number | null>(null);
-
-  // Build a status map from kanban data (item id -> status string)
-  const buildStatusMap = useCallback((kanbanData: KanbanData): Map<number, string> => {
-    const map = new Map<number, string>();
-    for (const item of kanbanData.inFlight) {
-      map.set(item.id, item.status);
+  const [data, setData] = useState<KanbanData>(() => {
+    const inFlight = initialData.inFlight;
+    const backlog = new Map(initialData.backlog);
+    const done = new Map(initialData.done);
+    // Build lookup maps for initial data
+    const itemMap = new Map<number, InFlightItem>();
+    const statusMap = new Map<number, string>();
+    for (const item of inFlight) {
+      itemMap.set(item.id, item);
+      statusMap.set(item.id, item.status);
     }
-    for (const group of kanbanData.backlog.values()) {
+    for (const group of backlog.values()) {
       for (const item of group.items) {
-        map.set(item.id, item.status);
+        itemMap.set(item.id, item as InFlightItem);
+        statusMap.set(item.id, item.status);
       }
     }
-    for (const group of kanbanData.done.values()) {
+    for (const group of done.values()) {
       for (const item of group.items) {
-        map.set(item.id, item.status);
+        itemMap.set(item.id, item as InFlightItem);
+        statusMap.set(item.id, item.status);
       }
     }
-    return map;
-  }, []);
+    return { inFlight, backlog, done, itemMap, statusMap };
+  });
+  const [statusError, setStatusError] = useState<string | null>(null);
 
-  // Build a mode map from kanban data (feature id -> mode) for detecting mode transitions
-  const buildModeMap = useCallback((kanbanData: KanbanData): Map<number, string | null> => {
-    const map = new Map<number, string | null>();
-    const collectFeatures = (items: WorkItem[]) => {
-      for (const item of items) {
-        if (item.type === 'feature') {
-          map.set(item.id, item.mode);
-        }
-      }
-    };
-    collectFeatures(kanbanData.inFlight);
-    for (const group of kanbanData.backlog.values()) collectFeatures(group.items);
-    for (const group of kanbanData.done.values()) collectFeatures(group.items);
-    return map;
-  }, []);
+  // Ref to latest data — lets callbacks read current data without closing over it,
+  // keeping function references stable across data changes (preserves memo on cards)
+  const dataRef = useRef(data);
+  useEffect(() => { dataRef.current = data; }, [data]);
+
+  // Use ClaudeSessionContext for session state and actions
+  const { sessions, standaloneSessions } = useSessionState();
+  const { setClaudePanelOpen, openSession, switchSession, closeSession, createAddToBacklogSession, sendMessage } = useSessionActions();
+  const { setSessions } = useSessionPersistence();
+
+  // Stable set of active session IDs — only changes when sessions are added/removed,
+  // not when session metadata updates. Prevents busting React.memo on all EpicGroups.
+  const activeSessionIds = useMemo(() => new Set(sessions.keys()), [sessions]);
+
+  // Onboarding state: show OnboardingWelcome instead of KanbanBoard for blank projects
+  const [showOnboarding, setShowOnboarding] = useState(!!isBlank);
+  const onboardingItems = useMemo(() => getOnboardingItems(data), [data]);
+
+  // Animation state
+  const {
+    externalAnimatingItemId,
+    setExternalAnimatingItemId,
+    pendingDataRef,
+    lastInternallyAnimatedIdRef,
+    handleExternalAnimationComplete: rawHandleExternalAnimationComplete,
+  } = useKanbanAnimation();
+
+  // Wrap animation complete to apply pending data
+  const handleExternalAnimationComplete = useCallback(() => {
+    const pending = rawHandleExternalAnimationComplete();
+    if (pending) {
+      startTransition(() => setData(pending));
+    }
+  }, [rawHandleExternalAnimationComplete]);
 
   // Track previous mode per feature to detect transitions
-  // Initialized lazily on first use (ref starts null, populated on first db_change)
   const previousModeMapRef = useRef<Map<number, string | null> | null>(null);
 
-  const refreshData = useCallback(async (): Promise<KanbanData> => {
-    const kanbanResponse = await fetch('/api/kanban');
-    const newData = await kanbanResponse.json();
-    const kanbanData: KanbanData = {
-      inFlight: newData.inFlight,
-      backlog: new Map(newData.backlog),
-      done: new Map(newData.done),
-    };
-    setData(kanbanData);
-    return kanbanData;
-  }, []);
+  // Debounce + abort for WS-triggered kanban fetches
+  const dbChangeTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const kanbanFetchAbortRef = useRef<AbortController | null>(null);
 
   // Sync session titles with work item titles from kanban data
   const syncSessionTitles = useCallback((kanbanData: KanbanData) => {
@@ -163,10 +109,8 @@ export function RealTimeKanbanWrapper({ initialData, isBlank, projectPath }: Rea
       let hasChanges = false;
 
       for (const [sessionId, session] of updated.entries()) {
-        // Skip standalone sessions (they're not tied to work items)
         if (standaloneSessions.some(s => s.id === sessionId)) continue;
 
-        // Find the work item in kanban data
         const workItemId = parseInt(sessionId, 10);
         if (isNaN(workItemId)) continue;
 
@@ -181,322 +125,370 @@ export function RealTimeKanbanWrapper({ initialData, isBlank, projectPath }: Rea
     });
   }, [standaloneSessions]);
 
-  const handleMessage = useCallback(async (message: WebSocketMessage) => {
-    if (message.type === 'db_change') {
-      // Snapshot current statuses before fetching new data
-      const oldStatusMap = buildStatusMap(data);
-
-      // Snapshot the internally-animated ID BEFORE the async fetch.
-      // handleStatusChange may clear this ref while our fetch is in flight,
-      // so we must capture it synchronously when the message arrives.
-      const internallyAnimatedId = lastInternallyAnimatedIdRef.current;
-
-      // Fetch new data without applying it yet
-      const kanbanResponse = await fetch('/api/kanban');
-      const rawData = await kanbanResponse.json();
-      const newKanbanData: KanbanData = {
-        inFlight: rawData.inFlight,
-        backlog: new Map(rawData.backlog),
-        done: new Map(rawData.done),
-      };
-      const newStatusMap = buildStatusMap(newKanbanData);
-
-      // Detect feature mode changes and inject gate cards into active sessions
-      const newModeMap = buildModeMap(newKanbanData);
-      if (previousModeMapRef.current) {
-        const registry = getRegistry();
-        for (const [featureId, newMode] of newModeMap) {
-          const oldMode = previousModeMapRef.current.get(featureId);
-          if (newMode && newMode !== oldMode) {
-            // Feature mode changed — inject gate into its session if active
-            const sessionId = String(featureId);
-            const streamManager = registry.get(sessionId);
-            if (streamManager) {
-              streamManager.injectGate(`mode-${newMode}-start`);
-            }
-          }
-        }
-      }
-      previousModeMapRef.current = newModeMap;
-
-      // Check if any item transitioned to done externally
-      let newlyDoneItemId: number | null = null;
-      for (const [id, newStatus] of newStatusMap) {
-        const oldStatus = oldStatusMap.get(id);
-        if (newStatus === 'done' && oldStatus && oldStatus !== 'done') {
-          newlyDoneItemId = id;
-          break; // Animate one at a time
-        }
-      }
-
-      if (newlyDoneItemId !== null && externalAnimatingItemId === null) {
-        // Skip if this item was just animated internally (UI-driven completion).
-        // We check the snapshot taken before the async fetch, not the current ref,
-        // because handleStatusChange clears the ref after refreshData completes —
-        // which can happen while our fetch is still in flight.
-        if (internallyAnimatedId === newlyDoneItemId) {
-          setData(newKanbanData);
-          syncSessionTitles(newKanbanData);
-          return;
-        }
-        // Hold new data, play animation on the old data first
-        pendingDataRef.current = newKanbanData;
-        setExternalAnimatingItemId(newlyDoneItemId);
-        syncSessionTitles(newKanbanData);
-      } else {
-        // No external completion to animate - apply data immediately
-        setData(newKanbanData);
-        syncSessionTitles(newKanbanData);
-      }
-    }
-  }, [data, buildStatusMap, buildModeMap, syncSessionTitles, externalAnimatingItemId]);
-
-  const handleTitleSave = useCallback(async (id: number, newTitle: string) => {
-    await fetch(`/api/work/${id}/title`, {
-      method: 'PATCH',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ title: newTitle }),
-    });
-    await refreshData();
-  }, [refreshData]);
+  // Undo/redo — use ref to break circular dependency with handleStatusChange
+  const pushActionRef = useRef<ReturnType<typeof useKanbanUndo>['pushAction']>(() => {});
 
   const handleStatusChange = useCallback(async (id: number, newStatus: string, skipUndo = false): Promise<{ success: boolean; notFound?: boolean }> => {
     setStatusError(null);
 
-    // Find the item to get its current status and title before the change
-    const found = findItemById(data, id);
+    const found = findItemById(dataRef.current, id);
     const previousStatus = found?.status;
     const itemTitle = found?.item.title ?? `Item #${id}`;
 
-    try {
-      // Track internally-animated items so WebSocket handler skips the duplicate animation
-      if (newStatus === 'done') {
-        lastInternallyAnimatedIdRef.current = id;
-      }
+    if (newStatus === 'done') {
+      lastInternallyAnimatedIdRef.current = id;
+    }
 
-      const response = await fetch(`/api/work/${id}/status`, {
-        method: 'PATCH',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({ status: newStatus }),
+    // Optimistic: update UI immediately, suppress WS refetches during IPC
+    startTransition(() => setData(prev => applyStatusChange(prev, id, newStatus)));
+    markLocalMutation();
+
+    if (!skipUndo && previousStatus && previousStatus !== newStatus) {
+      pushActionRef.current({
+        type: 'status_change',
+        itemId: id,
+        itemTitle,
+        before: previousStatus,
+        after: newStatus,
+        timestamp: Date.now(),
       });
-      if (!response.ok) {
-        if (response.status === 404) {
-          setStatusError('Item no longer exists');
-          await refreshData();
-          return { success: false, notFound: true };
-        } else {
-          setStatusError('Failed to update status');
-          await refreshData();
-          return { success: false };
-        }
-      }
+    }
 
-      // Push to undo stack if this is a user-initiated change (not undo/redo)
-      if (!skipUndo && previousStatus && previousStatus !== newStatus) {
-        undoStack.push({
-          type: 'status_change',
-          itemId: id,
-          itemTitle,
-          before: previousStatus,
-          after: newStatus,
-        });
-        setUndoRedoVersion(v => v + 1); // Trigger re-render
+    // Fire IPC in background
+    try {
+      const success = await dataBridge.updateStatus(id, newStatus);
+      if (!success) {
+        // Rollback with reverse mutation
+        startTransition(() => setData(prev => applyStatusChange(prev, id, previousStatus ?? 'backlog')));
+        setStatusError('Failed to update status');
+        return { success: false };
       }
-
-      await refreshData();
-      // Clear the internal animation guard after data is refreshed.
-      // This ensures all WebSocket db_change messages from this write are ignored.
       if (newStatus === 'done') {
         lastInternallyAnimatedIdRef.current = null;
       }
       return { success: true };
-    } catch {
-      setStatusError('Failed to update status');
+    } catch (err) {
+      // Rollback with reverse mutation
+      startTransition(() => setData(prev => applyStatusChange(prev, id, previousStatus ?? 'backlog')));
+      const msg = err instanceof Error ? err.message : String(err);
+      console.error('Status update failed:', msg);
+      setStatusError(`Failed to update status: ${msg}`);
       return { success: false };
     }
-  }, [refreshData, data, undoStack]);
+  }, [lastInternallyAnimatedIdRef]);
 
-  const handleReject = useCallback(async (id: number, reason: string) => {
-    setStatusError(null);
+  const { pushAction, handleUndo, handleRedo, canUndo, canRedo } = useKanbanUndo({
+    onStatusChange: handleStatusChange,
+    showToast,
+  });
+  useEffect(() => { pushActionRef.current = pushAction; }, [pushAction]);
 
-    const found = findItemById(data, id);
-    const previousStatus = found?.status;
-    const itemTitle = found?.item.title ?? `Item #${id}`;
+  // Full refetch handler — shared between db_change and db_delta fallback
+  const doFullRefetch = useCallback(async () => {
+    if (isLocalMutationRecent()) return;
+
+    const oldStatusMap = buildStatusMap(dataRef.current);
+    const internallyAnimatedId = lastInternallyAnimatedIdRef.current;
+
+    invalidateKanbanCache();
 
+    let newKanbanData: KanbanData;
     try {
-      const response = await fetch(`/api/work/${id}/status`, {
-        method: 'PATCH',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({ status: 'in_progress', rejectionReason: reason }),
-      });
-      if (!response.ok) {
-        setStatusError('Failed to reject item');
-        return;
-      }
+      newKanbanData = await dataBridge.getKanbanData();
+    } catch (e: unknown) {
+      console.error('Failed to refresh kanban data:', e);
+      return;
+    }
 
-      // Push to undo stack
-      if (previousStatus && previousStatus !== 'in_progress') {
-        undoStack.push({
-          type: 'status_change',
-          itemId: id,
-          itemTitle,
-          before: previousStatus,
-          after: 'in_progress',
-        });
-        setUndoRedoVersion(v => v + 1);
+    if (newKanbanData === dataRef.current) return;
+
+    const newStatusMap = buildStatusMap(newKanbanData);
+
+    // Detect feature mode changes and inject gate cards into active sessions
+    const newModeMap = buildModeMap(newKanbanData);
+    if (previousModeMapRef.current) {
+      const registry = getRegistry();
+      for (const [featureId, newMode] of newModeMap) {
+        const oldMode = previousModeMapRef.current.get(featureId);
+        if (newMode && newMode !== oldMode) {
+          const sessionId = String(featureId);
+          const streamManager = registry.get(sessionId);
+          if (streamManager) {
+            streamManager.injectGate(`mode-${newMode}-start`);
+          }
+        }
+      }
+    }
+    previousModeMapRef.current = newModeMap;
+
+    // Check if any item transitioned to done externally
+    let newlyDoneItemId: number | null = null;
+    for (const [id, newStatus] of newStatusMap) {
+      const oldStatus = oldStatusMap.get(id);
+      if (newStatus === 'done' && oldStatus && oldStatus !== 'done') {
+        newlyDoneItemId = id;
+        break;
       }
-
-      await refreshData();
-      showToast(`Rejected: "${itemTitle}" — ${reason}`);
-    } catch {
-      setStatusError('Failed to reject item');
     }
-  }, [refreshData, data, undoStack, showToast]);
 
-  const handleOrderChange = useCallback(async (id: number, newOrder: number) => {
-    try {
-      const response = await fetch(`/api/work/${id}/order`, {
-        method: 'PATCH',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({ display_order: newOrder }),
-      });
-      if (!response.ok) {
-        throw new Error('Failed to update order');
+    if (newlyDoneItemId !== null && externalAnimatingItemId === null) {
+      if (internallyAnimatedId === newlyDoneItemId) {
+        startTransition(() => setData(newKanbanData));
+        syncSessionTitles(newKanbanData);
+        return;
       }
-      await refreshData();
-    } catch (error) {
-      const errorMessage = error instanceof Error ? error.message : 'Failed to reorder item';
-      showToast(errorMessage, 'error');
+      pendingDataRef.current = newKanbanData;
+      setExternalAnimatingItemId(newlyDoneItemId);
+      syncSessionTitles(newKanbanData);
+    } else {
+      startTransition(() => setData(newKanbanData));
+      syncSessionTitles(newKanbanData);
+    }
+  }, [syncSessionTitles, externalAnimatingItemId, lastInternallyAnimatedIdRef, pendingDataRef, setExternalAnimatingItemId]);
+
+  const handleMessage = useCallback((message: WebSocketMessage) => {
+    // ---- Delta updates (from SQLite update_hook via Tauri IPC writes) ----
+    if (message.type === 'db_delta' && message.table === 'work_items' && message.rowid != null) {
+      if (isLocalMutationRecent()) return;
+
+      // For updates to existing items, try a targeted single-item patch.
+      // For inserts/deletes or non-work_items tables, fall back to full refetch.
+      if (message.action === 'update') {
+        // Debounce rapid deltas (e.g., batch display_order updates)
+        if (dbChangeTimerRef.current) clearTimeout(dbChangeTimerRef.current);
+        dbChangeTimerRef.current = setTimeout(async () => {
+          if (isLocalMutationRecent()) return;
+          const patched = await patchKanbanItem(message.rowid!);
+          if (patched) {
+            // Successfully patched — apply without full refetch
+            if (patched !== dataRef.current) {
+              startTransition(() => setData(patched));
+              syncSessionTitles(patched);
+            }
+          } else {
+            // Patch failed (status changed, item not in cache) — full refetch
+            await doFullRefetch();
+          }
+        }, 50);
+      } else {
+        // Insert or delete — full refetch (these are infrequent)
+        if (dbChangeTimerRef.current) clearTimeout(dbChangeTimerRef.current);
+        dbChangeTimerRef.current = setTimeout(() => {
+          if (isLocalMutationRecent()) return;
+          doFullRefetch();
+        }, 150);
+      }
+      return;
     }
-  }, [refreshData, showToast]);
 
-  const handleEpicAssign = useCallback(async (id: number, epicId: number | null) => {
-    try {
-      await fetch(`/api/work/${id}/epic`, {
-        method: 'PATCH',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({ epic_id: epicId }),
-      });
-      await refreshData();
-    } catch {
-      showToast('Failed to assign epic', 'error');
+    // ---- Full refetch fallback (from file mtime polling — external writes) ----
+    if (message.type === 'db_change') {
+      if (isLocalMutationRecent()) return;
+      if (dbChangeTimerRef.current) clearTimeout(dbChangeTimerRef.current);
+      dbChangeTimerRef.current = setTimeout(() => {
+        if (isLocalMutationRecent()) return;
+        doFullRefetch();
+      }, 150);
     }
-  }, [refreshData, showToast]);
+  }, [syncSessionTitles, doFullRefetch]);
 
-  // Error handler for drag-and-drop operations
-  const handleDragError = useCallback((message: string) => {
-    showToast(message, 'error');
-  }, [showToast]);
+  const handleTitleSave = useCallback(async (id: number, newTitle: string) => {
+    const previousTitle = dataRef.current.itemMap.get(id)?.title ?? '';
 
-  // Helper to format status for display
-  const formatStatus = (status: string): string => {
-    switch (status) {
-      case 'in_progress': return 'In Flight';
-      case 'backlog': return 'Backlog';
-      case 'done': return 'Done';
-      default: return status;
-    }
-  };
+    // Optimistic: update UI immediately, suppress WS refetches during IPC
+    startTransition(() => setData(prev => applyTitleChange(prev, id, newTitle)));
+    markLocalMutation();
 
-  // Undo the most recent status change
-  const handleUndo = useCallback(async (): Promise<UndoAction | null> => {
-    const action = undoStack.undo();
-    if (!action) return null;
-
-    // Revert the status change (skipUndo=true to prevent adding to undo stack)
-    const result = await handleStatusChange(action.itemId, action.before, true);
-    setUndoRedoVersion(v => v + 1);
-
-    if (result.notFound) {
-      // Item was deleted - show error toast (statusError already set by handleStatusChange)
-      // The action is already removed from undo stack and won't be in redo stack
-      // because we didn't push it back - just leave it removed
-      showToast(`Item no longer exists: "${action.itemTitle}" was deleted`, 'error');
-      return null;
+    try {
+      await dataBridge.updateTitle(id, newTitle);
+    } catch {
+      // Rollback
+      startTransition(() => setData(prev => applyTitleChange(prev, id, previousTitle)));
     }
+  }, []);
+
+  const handleReject = useCallback(async (id: number, reason: string) => {
+    setStatusError(null);
 
-    if (!result.success) {
-      // Other error - push action back to undo stack so user can retry
-      undoStack.push({
-        type: action.type,
-        itemId: action.itemId,
-        itemTitle: action.itemTitle,
-        before: action.after, // Swap because we want to retry undoing
-        after: action.before,
+    const found = findItemById(dataRef.current, id);
+    const previousStatus = found?.status;
+    const itemTitle = found?.item.title ?? `Item #${id}`;
+
+    // Optimistic: move to in_progress with rejection info immediately, suppress WS refetches during IPC
+    startTransition(() => setData(prev => applyStatusChange(prev, id, 'in_progress', { reason })));
+    markLocalMutation();
+
+    if (previousStatus && previousStatus !== 'in_progress') {
+      pushAction({
+        type: 'status_change',
+        itemId: id,
+        itemTitle,
+        before: previousStatus,
+        after: 'in_progress',
+        timestamp: Date.now(),
       });
-      return null;
     }
 
-    // Show success toast notification
-    showToast(`Undone: "${action.itemTitle}" moved back to ${formatStatus(action.before)}`);
+    showToast(`Rejected: "${itemTitle}" — ${reason}`);
 
-    return action;
-  }, [undoStack, handleStatusChange, showToast]);
+    // Open chat session for the rejected item so Claude can address the rejection
+    const sessionId = String(id);
+    const itemType = found?.item.type ?? 'chore';
+    openSession(sessionId, itemTitle, itemType, false, null, true);
 
-  // Redo the most recently undone status change
-  const handleRedo = useCallback(async (): Promise<UndoAction | null> => {
-    const action = undoStack.redo();
-    if (!action) return null;
+    // Inject rejection gate and send reason to Claude
+    setTimeout(() => {
+      const registry = getRegistry();
+      const streamManager = registry.get(sessionId);
+      if (streamManager) {
+        streamManager.injectGate('rejection', { reason });
+      }
+      sendMessage(reason);
+    }, 0);
 
-    // Re-apply the status change (skipUndo=true to prevent adding to undo stack)
-    const result = await handleStatusChange(action.itemId, action.after, true);
-    setUndoRedoVersion(v => v + 1);
+    // Fire IPC in background
+    try {
+      const success = await dataBridge.updateStatus(id, 'in_progress', reason);
+      if (!success) {
+        // Rollback
+        startTransition(() => setData(prev => applyStatusChange(prev, id, previousStatus ?? 'backlog')));
+        setStatusError('Failed to reject item');
+        return;
+      }
 
-    if (result.notFound) {
-      // Item was deleted - show error toast
-      showToast(`Item no longer exists: "${action.itemTitle}" was deleted`, 'error');
-      return null;
+      // Load existing conversation + persisted rejection gate from DB into stream manager.
+      // Fire-and-forget — don't block the rejection flow on content loading.
+      void (async () => {
+        try {
+          const registry = getRegistry();
+          const mgr = registry.get(sessionId);
+          if (mgr && mgr.status !== 'streaming' && mgr.messages.length === 0) {
+            const content = await invoke<string>('db_get_session_content', { id: parseInt(sessionId, 10) });
+            if (content) {
+              try {
+                const parsed = JSON.parse(content);
+                if (Array.isArray(parsed) && parsed.length > 0) {
+                  mgr.setMessages(parsed);
+                }
+              } catch {
+                // Content wasn't JSON array — ignore
+              }
+            }
+          }
+        } catch {
+          // Content loading failed — gate was still persisted to DB, will show on next refresh
+        }
+      })();
+    } catch (err) {
+      // Rollback
+      startTransition(() => setData(prev => applyStatusChange(prev, id, previousStatus ?? 'backlog')));
+      const msg = err instanceof Error ? err.message : String(err);
+      console.error('Reject failed:', msg);
+      setStatusError(`Failed to reject item: ${msg}`);
     }
+  }, [pushAction, showToast, openSession, sendMessage]);
 
-    if (!result.success) {
-      // Other error - push action back to redo stack so user can retry
-      // Note: This is a simplification; in production you might want more sophisticated retry logic
-      return null;
-    }
+  const handleOrderChange = useCallback(async (id: number, newOrder: number) => {
+    const item = dataRef.current.itemMap.get(id);
+    // Use effective display_order for rollback — null maps to id*10 in sort
+    // comparators, so use that same value to preserve original position on failure.
+    const previousOrder = item?.display_order ?? (item ? item.id * 10 : 0);
 
-    // Show success toast notification
-    showToast(`Redone: "${action.itemTitle}" moved to ${formatStatus(action.after)}`);
+    // Optimistic: update order immediately, suppress WS refetches during IPC
+    startTransition(() => setData(prev => applyOrderChange(prev, id, newOrder)));
+    markLocalMutation();
+
+    try {
+      await dataBridge.updateDisplayOrders([[id, newOrder]]);
+    } catch (error) {
+      // Rollback
+      startTransition(() => setData(prev => applyOrderChange(prev, id, previousOrder)));
+      const errorMessage = error instanceof Error ? error.message : 'Failed to reorder item';
+      showToast(errorMessage, 'error');
+    }
+  }, [showToast]);
 
-    return action;
-  }, [undoStack, handleStatusChange, showToast]);
+  const handleEpicAssign = useCallback(async (id: number, epicId: number | null) => {
+    const previousEpicId = dataRef.current.itemMap.get(id)?.parent_id ?? null;
 
-  // Expose undo stack state
-  const canUndo = undoStack.canUndo();
-  const canRedo = undoStack.canRedo();
+    // Optimistic: move between epic groups immediately, suppress WS refetches during IPC
+    startTransition(() => setData(prev => applyEpicAssign(prev, id, epicId)));
+    markLocalMutation();
 
-  // Called when external completion animation finishes - apply the pending data
-  const handleExternalAnimationComplete = useCallback(() => {
-    setExternalAnimatingItemId(null);
-    if (pendingDataRef.current) {
-      setData(pendingDataRef.current);
-      pendingDataRef.current = null;
+    try {
+      await invoke('db_assign_epic', { id, epicId });
+      invalidateKanbanCache();
+    } catch {
+      // Rollback
+      startTransition(() => setData(prev => applyEpicAssign(prev, id, previousEpicId)));
+      showToast('Failed to assign epic', 'error');
     }
-  }, []);
+  }, [showToast]);
 
-  // Claude panel handlers - multi-session support
+  const handleDragError = useCallback((message: string) => {
+    showToast(message, 'error');
+  }, [showToast]);
+
+  // Claude panel handlers
   const handleTriggerClaude = useCallback((id: number, title: string, type: string, conversational?: boolean, description?: string | null) => {
-    // Use context's openSession - handles existing session check, creation, and streaming
     openSession(String(id), title, type, conversational, description);
   }, [openSession]);
 
-  // Open an existing session (for card icon click)
   const handleOpenSession = useCallback(async (id: string) => {
-    // Use context's switchSession to load content, then open panel
     await switchSession(id);
     setClaudePanelOpen(true);
   }, [switchSession, setClaudePanelOpen]);
 
-  // Add to backlog handler - uses context's specialized method
+  const handleCloseSession = useCallback((id: string) => {
+    closeSession(id);
+  }, [closeSession]);
+
+  const handleRestart = useCallback((id: number) => {
+    const found = findItemById(dataRef.current, id);
+    if (!found) return;
+
+    const sessionId = String(id);
+    const itemTitle = found.item.title ?? `Item #${id}`;
+    const itemType = found.item.type ?? 'chore';
+    const reason = found.item.rejection_reason;
+    if (!reason) return;
+
+    openSession(sessionId, itemTitle, itemType);
+
+    setTimeout(() => {
+      const registry = getRegistry();
+      const streamManager = registry.get(sessionId);
+      if (streamManager) {
+        streamManager.injectGate('rejection', { reason });
+      }
+      sendMessage(reason);
+    }, 0);
+  }, [openSession, sendMessage]);
+
   const handleAddToBacklog = useCallback(async () => {
     await createAddToBacklogSession();
   }, [createAddToBacklogSession]);
 
-  const wsUrl = typeof window !== 'undefined'
-    ? `ws://${window.location.hostname}:47808`
-    : 'ws://localhost:47808';
+  // Onboarding: when user clicks start on first chore, transition to normal view
+  const handleStartOnboardingChore = useCallback(async (id: number, title: string) => {
+    await handleStatusChange(id, 'in_progress');
+    const found = findItemById(dataRef.current, id);
+    const type = found?.item.type ?? 'chore';
+    const description = found?.item.description ?? null;
+    openSession(String(id), title, type, true, description);
+    setShowOnboarding(false);
+  }, [handleStatusChange, openSession]);
+
+  // Cleanup debounce timer and in-flight fetch on unmount
+  useEffect(() => {
+    return () => {
+      if (dbChangeTimerRef.current) clearTimeout(dbChangeTimerRef.current);
+      if (kanbanFetchAbortRef.current) kanbanFetchAbortRef.current.abort();
+    };
+  }, []);
 
   const { isConnected, isReconnecting } = useWebSocket({
-    url: wsUrl,
+    url: getWebSocketUrl(),
     onMessage: handleMessage,
   });
 
@@ -507,13 +499,33 @@ export function RealTimeKanbanWrapper({ initialData, isBlank, projectPath }: Rea
     setConnectionStatus(status);
   }, [isConnected, isReconnecting, setConnectionStatus]);
 
+  // Handle rejection from detail page — open chat session for the rejected item
+  useEffect(() => {
+    const rejectedId = searchParams.get('rejected');
+    const reason = searchParams.get('reason');
+    if (!rejectedId || !reason) return;
+
+    // Clean the URL immediately
+    navigate('/', { replace: true });
+
+    const found = findItemById(dataRef.current, parseInt(rejectedId, 10));
+    const itemTitle = found?.item.title ?? `Item #${rejectedId}`;
+    const itemType = found?.item.type ?? 'chore';
+
+    openSession(rejectedId, itemTitle, itemType, false, null, true);
+
+    setTimeout(() => {
+      const registry = getRegistry();
+      const streamManager = registry.get(rejectedId);
+      if (streamManager) {
+        streamManager.injectGate('rejection', { reason });
+      }
+      sendMessage(reason);
+    }, 0);
+  }, [searchParams, navigate, openSession, sendMessage]);
+
   return (
-    <div className="h-full flex flex-col">
-      {/* Usage Limit Banner */}
-      <div className="px-4 pt-2">
-        <UpgradeBanner />
-      </div>
-      {/* Status Error Display */}
+    <div className="flex flex-col min-h-0">
       {statusError && (
         <div
           className="mb-4 p-3 bg-red-100 dark:bg-red-900/30 text-red-700 dark:text-red-300 rounded-lg flex items-center justify-between flex-shrink-0"
@@ -529,19 +541,27 @@ export function RealTimeKanbanWrapper({ initialData, isBlank, projectPath }: Rea
           </button>
         </div>
       )}
-      <div className="flex-1 min-h-0">
+      {showOnboarding ? (
+        <OnboardingWelcome
+          onboardingItems={onboardingItems}
+          onStartChore={handleStartOnboardingChore}
+        />
+      ) : (
         <KanbanBoard
           inFlight={data.inFlight}
           backlog={data.backlog}
           done={data.done}
+          itemStatusMap={data.statusMap}
           onTitleSave={handleTitleSave}
           onStatusChange={handleStatusChange}
           onReject={handleReject}
+          onRestart={handleRestart}
           onOrderChange={handleOrderChange}
           onEpicAssign={handleEpicAssign}
           onTriggerClaude={handleTriggerClaude}
           onOpenSession={handleOpenSession}
-          activeSessions={sessions}
+          onCloseSession={handleCloseSession}
+          activeSessionIds={activeSessionIds}
           onUndo={handleUndo}
           onRedo={handleRedo}
           canUndo={canUndo}
@@ -551,10 +571,8 @@ export function RealTimeKanbanWrapper({ initialData, isBlank, projectPath }: Rea
           usageAllowed={usageAllowed}
           externalAnimatingItemId={externalAnimatingItemId}
           onExternalAnimationComplete={handleExternalAnimationComplete}
-          isBlank={isBlank}
         />
-      </div>
-      {/* ClaudePanel is rendered by AppShell - DO NOT duplicate here */}
+      )}
     </div>
   );
 }