jettypod 4.4.116 → 4.4.120

package/apps/dashboard/contexts/ClaudeSessionContext.tsx

@@ -1,11 +1,13 @@
 'use client';
 
-import { createContext, useContext, useState, useCallback, useEffect, useRef, type ReactNode } from 'react';
+import { createContext, useContext, useState, useCallback, useEffect, useRef, useMemo, type ReactNode } from 'react';
 import {
   type ClaudeMessage,
   type StreamStatus,
   type StreamState,
+  type QueuedMessage,
 } from '../lib/session-stream-manager';
+import type { AttachedImage } from '../components/ClaudePanelInput';
 import { getRegistry } from '../lib/stream-manager-registry';
 import {
   createSessionRefs,
@@ -21,6 +23,7 @@ import {
 } from '../lib/session-state-machine';
 import { getMessageBuffer } from '../lib/message-buffer';
 import { useToast } from '../components/Toast';
+import { useUsage } from './UsageContext';
 import type { SessionItem } from '../components/SessionList';
 
 // Re-export ClaudeMessage for consumers
@@ -39,67 +42,89 @@ export interface Session {
   narratedMode: boolean;
 }
 
-interface ClaudeSessionContextValue {
-  // Panel state
-  claudePanelOpen: boolean;
-  setClaudePanelOpen: (open: boolean) => void;
+// Split into 3 contexts to prevent unnecessary re-renders:
+// - SessionStateContext: frequently-changing state (messages, status, sessions)
+// - SessionActionsContext: stable callbacks (sendMessage, switchSession, etc.)
+// - SessionPersistenceContext: internal mutation setters (setSessions, etc.)
 
-  // Session state
+interface SessionStateContextValue {
+  claudePanelOpen: boolean;
   sessions: Map<string, Session>;
   activeSessionId: string | null;
   activeSession: Session | null;
-
-  // Standalone sessions
   standaloneSessions: SessionItem[];
-
-  // Stream state (from active session's stream manager)
   messages: ClaudeMessage[];
   status: StreamStatus;
   error: string | null;
   exitCode: number | null;
   canRetry: boolean;
+  queuedMessage: QueuedMessage | null;
   narratedMode: boolean;
-  toggleNarratedMode: () => void;
+  isTabSwitching: boolean;
+}
 
-  // Session actions
-  openSession: (id: string, title: string, type?: string) => void;
+interface SessionActionsContextValue {
+  setClaudePanelOpen: (open: boolean) => void;
+  openSession: (id: string, title: string, type?: string, conversational?: boolean, description?: string | null, initialHidden?: boolean) => void;
   switchSession: (id: string) => void;
   closeSession: (sessionId: string) => void;
   openSessionPanel: () => void;
   createNewSession: () => Promise<void>;
   createAddToBacklogSession: () => Promise<void>;
   createRunScenarioSession: (featureFile: string, scenarioTitle: string) => Promise<void>;
-
-  // Stream actions
-  sendMessage: (message: string) => void;
+  createFixScenarioSession: (featureFile: string, scenarioTitle: string, error: string, failedStep?: string, steps?: string[]) => Promise<void>;
+  createWelcomeSession: () => Promise<void>;
+  sendMessage: (message: string, images?: AttachedImage[]) => void;
   retry: () => void;
   stop: () => void;
+  toggleNarratedMode: () => void;
+}
 
-  // For components that need to set messages directly (e.g., restoring from DB)
+interface SessionPersistenceContextValue {
   setMessages: (messages: ClaudeMessage[]) => void;
   setStatus: (status: StreamStatus) => void;
-
-  // For RealTimeKanbanWrapper to update sessions
   setSessions: React.Dispatch<React.SetStateAction<Map<string, Session>>>;
   setActiveSessionId: (id: string | null) => void;
   setStandaloneSessions: React.Dispatch<React.SetStateAction<SessionItem[]>>;
 }
 
-const ClaudeSessionContext = createContext<ClaudeSessionContextValue | null>(null);
+const SessionStateContext = createContext<SessionStateContextValue | null>(null);
+const SessionActionsContext = createContext<SessionActionsContextValue | null>(null);
+const SessionPersistenceContext = createContext<SessionPersistenceContextValue | null>(null);
 
-export function useClaudeSession() {
-  const context = useContext(ClaudeSessionContext);
-  if (!context) {
-    throw new Error('useClaudeSession must be used within a ClaudeSessionProvider');
-  }
+// Granular hooks — use these for better performance
+export function useSessionState() {
+  const context = useContext(SessionStateContext);
+  if (!context) throw new Error('useSessionState must be used within a ClaudeSessionProvider');
   return context;
 }
 
+export function useSessionActions() {
+  const context = useContext(SessionActionsContext);
+  if (!context) throw new Error('useSessionActions must be used within a ClaudeSessionProvider');
+  return context;
+}
+
+export function useSessionPersistence() {
+  const context = useContext(SessionPersistenceContext);
+  if (!context) throw new Error('useSessionPersistence must be used within a ClaudeSessionProvider');
+  return context;
+}
+
+// Backward-compatible hook — combines all 3 contexts
+export function useClaudeSession() {
+  const state = useSessionState();
+  const actions = useSessionActions();
+  const persistence = useSessionPersistence();
+  return { ...state, ...actions, ...persistence };
+}
+
 const ACTIVE_SESSION_KEY = 'jettypod-active-session-id';
 
 export function ClaudeSessionProvider({ children }: { children: ReactNode }) {
   // Toast for user notifications
   const { showToast } = useToast();
+  const { allowed: usageAllowed, refresh: refreshUsage } = useUsage();
 
   // Get registry singleton (stable across renders)
   const registry = getRegistry();
@@ -172,6 +197,9 @@ export function ClaudeSessionProvider({ children }: { children: ReactNode }) {
   // AbortController for cancelling in-flight historical content fetches (#1000101)
   const contentFetchAbortRef = useRef<AbortController | null>(null);
 
+  // Reactive tab-switching state (exposed to UI so components can suppress flash of empty state)
+  const [isTabSwitching, setIsTabSwitching] = useState(false);
+
   // Force re-render when stream state changes (since stream managers are mutable)
   const [, forceUpdate] = useState({});
 
@@ -193,6 +221,17 @@ export function ClaudeSessionProvider({ children }: { children: ReactNode }) {
           machine.send('CONNECTED');
         } else if (state.status === 'done') {
           machine.send('COMPLETE');
+          // Auto-send queued message after stream completes
+          if (state.queuedMessage) {
+            const streamManager = registry.get(sessionId);
+            if (streamManager && machine.canSend('SEND')) {
+              const { message, images } = state.queuedMessage;
+              streamManager.clearQueuedMessage();
+              machine.send('SEND');
+              setSessionStreaming(sessionRefs, sessionId, true);
+              streamManager.sendMessage(message, images);
+            }
+          }
         } else if (state.status === 'error') {
           machine.send('ERROR');
         } else if (state.status === 'idle' && machine.state !== 'idle') {
@@ -253,11 +292,12 @@ export function ClaudeSessionProvider({ children }: { children: ReactNode }) {
   const getOrCreateStreamManager = useCallback((
     sessionId: string,
     standalone: boolean,
-    onWorkItemCreated?: (workItemId: number, title: string) => void
+    onWorkItemCreated?: (workItemId: number, title: string) => void,
+    conversational?: boolean
   ) => {
     // Registry handles idempotent creation and state change events
     return registry.create(sessionId, {
-      context: { workItemId: sessionId, standalone },
+      context: { workItemId: sessionId, standalone, conversational },
       callbacks: { onWorkItemCreated },
     });
   }, [registry]);
@@ -266,26 +306,29 @@ export function ClaudeSessionProvider({ children }: { children: ReactNode }) {
   // Note: The stream manager already guards on sessionContext.standalone before
   // firing this callback, so we don't need to re-check sessions here (which
   // would fail due to stale closure over the sessions Map).
-  const handleWorkItemCreated = useCallback(async (workItemId: number, title: string) => {
-    // Use sync ref to get current active session (avoids stale closure)
-    const currentActiveId = sessionRefs.activeSessionId.current;
-    if (!currentActiveId) return;
+  const handleWorkItemCreated = useCallback(async (workItemId: number, title: string, sourceSessionId: string) => {
+    // Refresh usage count from local DB (work item now exists in work.db)
+    refreshUsage();
+
+    // Use the source session ID passed by the stream manager — NOT activeSessionId,
+    // which may point to a different tab if the user switched during streaming (#1001272)
+    if (!sourceSessionId) return;
 
     try {
       const response = await fetch('/api/claude/sessions', {
         method: 'PATCH',
         headers: { 'Content-Type': 'application/json' },
         body: JSON.stringify({
-          sessionId: parseInt(currentActiveId, 10),
+          sessionId: parseInt(sourceSessionId, 10),
           workItemId,
         }),
       });
 
-      if (response.ok) {
+      if (response.ok || response.status === 409) {
         const newSessionId = String(workItemId);
 
         // Update stream manager's session context via registry
-        const streamManager = registry.get(currentActiveId);
+        const streamManager = registry.get(sourceSessionId);
         if (streamManager) {
           streamManager.updateSessionContext({
             workItemId: newSessionId,
@@ -295,13 +338,13 @@ export function ClaudeSessionProvider({ children }: { children: ReactNode }) {
 
         // Atomic session update (#1000102): Build new map in one pass
         setSessions(prev => {
-          const session = prev.get(currentActiveId);
+          const session = prev.get(sourceSessionId);
           if (!session) return prev;
 
           // Build new map: copy all except old session, add new session
           const updated = new Map<string, Session>();
           for (const [key, value] of prev) {
-            if (key !== currentActiveId) {
+            if (key !== sourceSessionId) {
               updated.set(key, value);
             }
           }
@@ -319,13 +362,13 @@ export function ClaudeSessionProvider({ children }: { children: ReactNode }) {
 
         // Remove from standalone sessions list
         setStandaloneSessions(prev =>
-          prev.filter(s => s.id !== currentActiveId)
+          prev.filter(s => s.id !== sourceSessionId)
         );
       }
     } catch (err) {
       console.error('Failed to link session to work item:', err);
     }
-  }, [sessionRefs, registry, setActiveSessionId]);
+  }, [registry, setActiveSessionId, refreshUsage]);
 
   // Load persisted sessions from backend on mount
   useEffect(() => {
@@ -397,7 +440,8 @@ export function ClaudeSessionProvider({ children }: { children: ReactNode }) {
               status: 'idle',
               error: null,
               exitCode: null,
-              narratedMode: true,
+              // Welcome session shows static content — detail view shows all messages
+              narratedMode: session.title !== 'Welcome',
               // Stream manager created lazily when session becomes active
             });
           }
@@ -436,7 +480,7 @@ export function ClaudeSessionProvider({ children }: { children: ReactNode }) {
   // Open or create a session for a work item
   // With per-session streams, no need to stop other streams or track ownership
   // Auto-sends an initial message so Claude starts working immediately
-  const openSession = useCallback((id: string, title: string, type?: string) => {
+  const openSession = useCallback((id: string, title: string, type?: string, conversational?: boolean, description?: string | null, initialHidden?: boolean) => {
     if (sessions.has(id)) {
       // Switching to existing session - ensure it has a stream manager
       const session = sessions.get(id)!;
@@ -447,8 +491,13 @@ export function ClaudeSessionProvider({ children }: { children: ReactNode }) {
       return;
     }
 
-    // Create stream manager in registry
-    const streamManager = getOrCreateStreamManager(id, false);
+    // Gate new session creation on usage limits
+    if (!usageAllowed) {
+      return;
+    }
+
+    // Create stream manager in registry — pass conversational flag for skip-delay behavior
+    const streamManager = getOrCreateStreamManager(id, false, undefined, conversational);
     registry.acquire(id);
 
     const newSession: Session = {
@@ -472,12 +521,18 @@ export function ClaudeSessionProvider({ children }: { children: ReactNode }) {
     setClaudePanelOpen(true);
 
     // Auto-send initial message so Claude starts working immediately
-    // sendMessage() handles adding the user message to the stream manager internally
-    const initialMessage = `I'm starting work on ${type || 'work item'} #${id}: ${title}`;
+    // Conversational chores: send description as hidden message so Claude speaks first
+    // Non-conversational: send visible "starting work" message
+    const initialMessage = conversational
+      ? `This is a conversation — no code, no worktrees. Just chat with me naturally.\n\n${description || title}`
+      : `I'm starting work on ${type || 'work item'} #${id}: ${title}`;
     const machine = getStateMachine(id);
     machine.send('SEND');
-    streamManager.sendMessage(initialMessage);
-  }, [sessions, registry, getOrCreateStreamManager, ensureStreamManager, setActiveSessionId, getStateMachine]);
+    streamManager.sendMessage(initialMessage, undefined, (conversational || initialHidden) ? { hidden: true } : undefined);
+
+    // Refresh usage so UI reflects the new session immediately
+    refreshUsage();
+  }, [sessions, registry, getOrCreateStreamManager, ensureStreamManager, setActiveSessionId, getStateMachine, usageAllowed, showToast, refreshUsage]);
 
   // Track target session during async switch operations (for tab-switching UX, not streaming)
   const switchingToRef = useRef<string | null>(null);
@@ -488,8 +543,9 @@ export function ClaudeSessionProvider({ children }: { children: ReactNode }) {
   const switchSession = useCallback(async (id: string) => {
     if (!sessions.has(id)) return;
 
-    // Mark tab switch in progress (sync ref for callbacks)
+    // Mark tab switch in progress (sync ref for callbacks + reactive state for UI)
     sessionRefs.isTabSwitching.set(true);
+    setIsTabSwitching(true);
 
     // Start buffering messages for the previous session to prevent loss
     const previousSessionId = sessionRefs.activeSessionId.current;
@@ -612,36 +668,24 @@ export function ClaudeSessionProvider({ children }: { children: ReactNode }) {
         switchingToRef.current = null;
       }
       sessionRefs.isTabSwitching.set(false);
+      setIsTabSwitching(false);
     }, 100); // 100ms debounce delay
   }, [sessions, sessionRefs, registry, ensureStreamManager, setActiveSessionId, messageBuffer]);
 
   // Close a session
   // With per-session streams, we delete the stream manager from registry when closing
-  const closeSession = useCallback(async (sessionId: string) => {
+  const closeSession = useCallback((sessionId: string) => {
     // Get session to determine API type
     const session = sessions.get(sessionId);
     const sessionType = session?.type || 'standalone';
 
-    // Unpin the session being closed
-    const endpoint = sessionType === 'workitem'
-      ? `/api/claude/${sessionId}/pin`
-      : `/api/claude/sessions/${sessionId}/pin`;
-    fetch(endpoint, { method: 'DELETE' }).catch(() => {});
-
     // Delete stream manager from registry (handles destroy + cleanup)
     registry.delete(sessionId);
 
     // Clear streaming status in sync ref
     setSessionStreaming(sessionRefs, sessionId, false);
 
-    try {
-      await fetch(`/api/claude/sessions?sessionId=${sessionId}&type=${sessionType}`, {
-        method: 'DELETE',
-      });
-    } catch (err) {
-      console.error('[ClaudeSessionContext] Failed to close session:', err);
-    }
-
+    // Update UI state immediately (before any async work)
     setStandaloneSessions(prev => prev.filter(s => s.id !== sessionId));
     setSessions(prev => {
       const updated = new Map(prev);
@@ -665,11 +709,26 @@ export function ClaudeSessionProvider({ children }: { children: ReactNode }) {
         setActiveSessionId(remaining[Math.min(newIndex, remaining.length - 1)]);
       }
     }
+
+    // API cleanup in background (unpin + delete) — UI already updated above
+    const endpoint = sessionType === 'workitem'
+      ? `/api/claude/${sessionId}/pin`
+      : `/api/claude/sessions/${sessionId}/pin`;
+    fetch(endpoint, { method: 'DELETE' }).catch(() => {});
+    fetch(`/api/claude/sessions?sessionId=${sessionId}&type=${sessionType}`, {
+      method: 'DELETE',
+    }).catch(err => {
+      console.error('[ClaudeSessionContext] Failed to close session:', err);
+    });
   }, [activeSessionId, sessions, standaloneSessions, registry, sessionRefs, setActiveSessionId]);
 
   // Create a new standalone session
   // With per-session streams, each new session gets its own stream manager in registry
   const createNewSession = useCallback(async () => {
+    if (!usageAllowed) {
+      return;
+    }
+
     try {
       const response = await fetch('/api/claude/sessions', {
         method: 'POST',
@@ -721,10 +780,13 @@ export function ClaudeSessionProvider({ children }: { children: ReactNode }) {
 
       setActiveSessionId(id);
       setClaudePanelOpen(true);
+
+      // Refresh usage so UI reflects the new session immediately
+      refreshUsage();
     } catch (err) {
       console.error('[ClaudeSessionContext] Failed to create session:', err);
     }
-  }, [showToast, registry, getOrCreateStreamManager, handleWorkItemCreated, setActiveSessionId]);
+  }, [showToast, registry, getOrCreateStreamManager, handleWorkItemCreated, setActiveSessionId, usageAllowed, refreshUsage]);
 
   // Open the session panel (restore last session or create new)
   const openSessionPanel = useCallback(() => {
@@ -743,14 +805,16 @@ export function ClaudeSessionProvider({ children }: { children: ReactNode }) {
       return;
     }
 
-    // No sessions exist - create new standalone session
-    createNewSession();
+    // No sessions exist - create new standalone session (unless over usage limit)
+    if (usageAllowed) {
+      createNewSession();
+    }
     setClaudePanelOpen(true);
-  }, [sessions, switchSession, createNewSession]);
+  }, [sessions, switchSession, createNewSession, usageAllowed]);
 
   // Send message via the active session's stream manager
   // With per-session streams, each session has its own manager - no cross-contamination possible
-  const sendMessage = useCallback((message: string) => {
+  const sendMessage = useCallback((message: string, images?: AttachedImage[]) => {
     // Use sync ref for current active session (avoids stale closure)
     const currentActiveId = sessionRefs.activeSessionId.current;
     if (!currentActiveId) {
@@ -758,29 +822,38 @@ export function ClaudeSessionProvider({ children }: { children: ReactNode }) {
       return;
     }
 
-    // Validate state transition via state machine
     const machine = getStateMachine(currentActiveId);
-    if (!machine.canSend('SEND')) {
-      console.warn(`[ClaudeSessionContext] Cannot send message: invalid state transition from ${machine.state}`);
+
+    // If we can send directly, do so
+    if (machine.canSend('SEND')) {
+      const streamManager = registry.get(currentActiveId);
+      if (!streamManager) {
+        // Lazy create if needed
+        const session = sessions.get(currentActiveId);
+        if (!session) return;
+        const mgr = ensureStreamManager(currentActiveId, session);
+        machine.send('SEND');
+        mgr.sendMessage(message, images);
+        return;
+      }
+
+      machine.send('SEND');
+      setSessionStreaming(sessionRefs, currentActiveId, true);
+      streamManager.sendMessage(message, images);
       return;
     }
 
-    // Get stream manager from registry
-    const streamManager = registry.get(currentActiveId);
-    if (!streamManager) {
-      // Lazy create if needed
-      const session = sessions.get(currentActiveId);
-      if (!session) return;
-      const mgr = ensureStreamManager(currentActiveId, session);
-      machine.send('SEND'); // Transition to connecting
-      mgr.sendMessage(message);
+    // If streaming/connecting, queue the message for later
+    if (machine.canSend('QUEUE')) {
+      const streamManager = registry.get(currentActiveId);
+      if (!streamManager) return;
+
+      machine.send('QUEUE');
+      streamManager.queueMessage(message, images);
       return;
     }
 
-    // Transition state machine and mark as streaming
-    machine.send('SEND');
-    setSessionStreaming(sessionRefs, currentActiveId, true);
-    streamManager.sendMessage(message);
+    console.warn(`[ClaudeSessionContext] Cannot send message: invalid state transition from ${machine.state}`);
   }, [sessionRefs, registry, sessions, ensureStreamManager, getStateMachine]);
 
   // Retry via the active session's stream manager
@@ -825,20 +898,41 @@ export function ClaudeSessionProvider({ children }: { children: ReactNode }) {
     setSessionStreaming(sessionRefs, currentActiveId, false);
   }, [sessionRefs, registry, getStateMachine]);
 
-  // Toggle narrated mode for the active session's stream manager
+  // Toggle narrated mode directly in React state, keeping stream manager in sync
+  // without triggering notifyStateChange (which would overwrite React state with
+  // potentially stale stream manager state — the root cause of the blank chat bug).
   const toggleNarratedMode = useCallback(() => {
     const currentActiveId = sessionRefs.activeSessionId.current;
     if (!currentActiveId) return;
 
-    const streamManager = registry.get(currentActiveId);
-    if (!streamManager) return;
+    setSessions(prev => {
+      const session = prev.get(currentActiveId);
+      if (!session) return prev;
 
-    streamManager.setNarratedMode(!streamManager.narratedMode);
+      const newNarratedMode = !session.narratedMode;
+
+      // Keep stream manager in sync (quiet — no notifyStateChange)
+      const streamManager = registry.get(currentActiveId);
+      if (streamManager) {
+        streamManager.setNarratedModeQuiet(newNarratedMode);
+      }
+
+      const updated = new Map(prev);
+      updated.set(currentActiveId, {
+        ...session,
+        narratedMode: newNarratedMode,
+      });
+      return updated;
+    });
   }, [sessionRefs, registry]);
 
   // Create an "Add to Backlog" session with initial assistant message
   // With per-session streams, each session has its own manager in registry
   const createAddToBacklogSession = useCallback(async () => {
+    if (!usageAllowed) {
+      return;
+    }
+
     try {
       const response = await fetch('/api/claude/sessions', {
         method: 'POST',
@@ -870,7 +964,7 @@ export function ClaudeSessionProvider({ children }: { children: ReactNode }) {
       // Create initial assistant message
       const initialMessage: ClaudeMessage = {
         type: 'assistant',
-        content: 'What should we add to the backlog?',
+        content: 'What should the name of this work item be?',
         timestamp: Date.now(),
       };
 
@@ -899,13 +993,115 @@ export function ClaudeSessionProvider({ children }: { children: ReactNode }) {
 
       setActiveSessionId(id);
       setClaudePanelOpen(true);
+
+      // Refresh usage so UI reflects the new session immediately
+      refreshUsage();
     } catch (err) {
       console.error('[ClaudeSessionContext] Failed to create backlog session:', err);
     }
+  }, [showToast, registry, getOrCreateStreamManager, handleWorkItemCreated, setActiveSessionId, usageAllowed, refreshUsage]);
+
+  // Create a welcome session for blank projects with initial assistant message
+  const createWelcomeSession = useCallback(async () => {
+    try {
+      const response = await fetch('/api/claude/sessions', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ title: 'Welcome' }),
+      });
+
+      if (!response.ok) {
+        const errorData = await response.json();
+        if (errorData.code === 'SESSION_LIMIT_REACHED') {
+          console.warn(`[ClaudeSessionContext] ${errorData.error}`);
+          showToast('Session limit reached. Close existing sessions to create new ones.', 'error');
+        }
+        return;
+      }
+
+      const { id, title } = await response.json();
+
+      setStandaloneSessions(prev => [...prev, {
+        id,
+        title,
+        featureId: null,
+        featureTitle: null,
+      }]);
+
+      const now = Date.now();
+
+      const greetingMessage: ClaudeMessage = {
+        type: 'assistant',
+        content: 'Ahoy. Your project is set up and ready to go.',
+        timestamp: now,
+      };
+
+      const backlogTip: ClaudeMessage = {
+        type: 'gate',
+        gateType: 'tip',
+        gateData: {
+          id: 'tip-backlog',
+          icon: '📋',
+          title: 'The Backlog',
+          body: 'The backlog is where all your work items live.\n\n**Features** — new user-facing capabilities\n**Chores** — technical tasks\n**Bugs** — something broke\n**Epics** — a group of related features and chores',
+        },
+        timestamp: now + 1,
+      };
+
+      const workflowTip: ClaudeMessage = {
+        type: 'gate',
+        gateType: 'tip',
+        gateData: {
+          id: 'tip-workflow',
+          icon: '🔄',
+          title: 'How to Work',
+          body: '**1. Start** — click \'start\' on a work item to open a chat\n**2. Chat** — work through it with Claude\n**3. Close** — close the chat and start what\'s next',
+        },
+        timestamp: now + 2,
+      };
+
+      const ctaMessage: ClaudeMessage = {
+        type: 'assistant',
+        content: 'Close this welcome chat and start your first onboarding chore\u2014**Align on the user journey**.',
+        timestamp: now + 3,
+      };
+
+      const welcomeMessages = [greetingMessage, backlogTip, workflowTip, ctaMessage];
+
+      const streamManager = getOrCreateStreamManager(id, true, handleWorkItemCreated);
+      registry.acquire(id);
+      streamManager.setMessages(welcomeMessages);
+
+      const newSession: Session = {
+        id,
+        title,
+        type: 'standalone',
+        messages: welcomeMessages,
+        status: 'idle',
+        error: null,
+        exitCode: null,
+        narratedMode: false,
+      };
+
+      setSessions(prev => {
+        const updated = new Map(prev);
+        updated.set(id, newSession);
+        return updated;
+      });
+
+      setActiveSessionId(id);
+      setClaudePanelOpen(true);
+    } catch (err) {
+      console.error('[ClaudeSessionContext] Failed to create welcome session:', err);
+    }
   }, [showToast, registry, getOrCreateStreamManager, handleWorkItemCreated, setActiveSessionId]);
 
   // Create a "Run Scenario" session with preloaded cucumber-js command
   const createRunScenarioSession = useCallback(async (featureFile: string, scenarioTitle: string) => {
+    if (!usageAllowed) {
+      return;
+    }
+
     try {
       const sessionTitle = `Run: ${scenarioTitle}`;
       const response = await fetch('/api/claude/sessions', {
@@ -969,11 +1165,112 @@ export function ClaudeSessionProvider({ children }: { children: ReactNode }) {
       const machine = getStateMachine(id);
       machine.send('SEND');
       streamManager.sendMessage(userMessage.content!);
+
+      // Refresh usage so UI reflects the new session immediately
+      refreshUsage();
     } catch (err) {
       console.error('[ClaudeSessionContext] Failed to create run scenario session:', err);
       showToast('Failed to create session. Please try again.', 'error');
     }
-  }, [showToast, registry, getOrCreateStreamManager, handleWorkItemCreated, setActiveSessionId, getStateMachine]);
+  }, [showToast, registry, getOrCreateStreamManager, handleWorkItemCreated, setActiveSessionId, getStateMachine, usageAllowed, refreshUsage]);
+
+  // Create a "Fix Scenario" session with preloaded failure context
+  const createFixScenarioSession = useCallback(async (featureFile: string, scenarioTitle: string, error: string, failedStep?: string, steps?: string[]) => {
+    if (!usageAllowed) {
+      return;
+    }
+
+    try {
+      const sessionTitle = `Fix: ${scenarioTitle}`;
+      const response = await fetch('/api/claude/sessions', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ title: sessionTitle }),
+      });
+
+      if (!response.ok) {
+        const errorData = await response.json();
+        if (errorData.code === 'SESSION_LIMIT_REACHED') {
+          console.warn(`[ClaudeSessionContext] ${errorData.error}`);
+          showToast('Session limit reached. Close existing sessions to create new ones.', 'error');
+        } else {
+          console.error('[ClaudeSessionContext] Failed to create fix scenario session:', errorData.error);
+          showToast('Failed to create session. Please try again.', 'error');
+        }
+        return;
+      }
+
+      const { id, title } = await response.json();
+
+      setStandaloneSessions(prev => [...prev, {
+        id,
+        title,
+        featureId: null,
+        featureTitle: null,
+      }]);
+
+      const promptParts = [
+        'A BDD scenario is failing and needs to be fixed.',
+        '',
+        `**Scenario:** ${scenarioTitle}`,
+        `**Feature file:** ${featureFile}`,
+      ];
+
+      if (failedStep) {
+        promptParts.push(`**Failed step:** ${failedStep}`);
+      }
+
+      promptParts.push('**Error:**', '```', error, '```');
+
+      if (steps && steps.length > 0) {
+        promptParts.push('', '**Scenario steps:**');
+        steps.forEach(step => promptParts.push(`  ${step}`));
+      }
+
+      promptParts.push('', 'Please investigate this failure, identify the root cause, and fix it.');
+
+      const userMessage: ClaudeMessage = {
+        type: 'user',
+        content: promptParts.join('\n'),
+        timestamp: Date.now(),
+      };
+
+      const streamManager = getOrCreateStreamManager(id, true, handleWorkItemCreated);
+      registry.acquire(id);
+      streamManager.setMessages([userMessage]);
+
+      const newSession: Session = {
+        id,
+        title,
+        type: 'standalone',
+        messages: [userMessage],
+        status: 'idle',
+        error: null,
+        exitCode: null,
+        narratedMode: true,
+      };
+
+      setSessions(prev => {
+        const updated = new Map(prev);
+        updated.set(id, newSession);
+        return updated;
+      });
+
+      setActiveSessionId(id);
+      setClaudePanelOpen(true);
+
+      // Auto-send the fix request to Claude
+      const machine = getStateMachine(id);
+      machine.send('SEND');
+      streamManager.sendMessage(userMessage.content!);
+
+      // Refresh usage so UI reflects the new session immediately
+      refreshUsage();
+    } catch (err) {
+      console.error('[ClaudeSessionContext] Failed to create fix scenario session:', err);
+      showToast('Failed to create session. Please try again.', 'error');
+    }
+  }, [showToast, registry, getOrCreateStreamManager, handleWorkItemCreated, setActiveSessionId, getStateMachine, usageAllowed, refreshUsage]);
 
   // Setters for direct manipulation (e.g., restoring from DB)
   // These now work through the registry
@@ -1001,27 +1298,26 @@ export function ClaudeSessionProvider({ children }: { children: ReactNode }) {
   // Get canRetry from registry
   const activeStreamManager = activeSessionId ? registry.get(activeSessionId) : null;
 
-  const value: ClaudeSessionContextValue = {
-    // Panel state
+  // Memoize state context — changes when state values change
+  const stateValue: SessionStateContextValue = useMemo(() => ({
     claudePanelOpen,
-    setClaudePanelOpen,
-
-    // Session state
     sessions,
     activeSessionId,
     activeSession,
     standaloneSessions,
-
-    // Stream state (from active session)
     messages: activeSession?.messages ?? [],
     status: activeSession?.status ?? 'idle',
     error: activeSession?.error ?? null,
     exitCode: activeSession?.exitCode ?? null,
     canRetry: activeStreamManager?.canRetry ?? false,
+    queuedMessage: activeStreamManager?.queuedMessage ?? null,
     narratedMode: activeSession?.narratedMode ?? false,
-    toggleNarratedMode,
+    isTabSwitching,
+  }), [claudePanelOpen, sessions, activeSessionId, activeSession, standaloneSessions, activeStreamManager, isTabSwitching]);
 
-    // Session actions
+  // Memoize actions context — stable callbacks, rarely changes
+  const actionsValue: SessionActionsContextValue = useMemo(() => ({
+    setClaudePanelOpen,
     openSession,
     switchSession,
     closeSession,
@@ -1029,23 +1325,30 @@ export function ClaudeSessionProvider({ children }: { children: ReactNode }) {
     createNewSession,
     createAddToBacklogSession,
     createRunScenarioSession,
-
-    // Stream actions (now go through registry)
+    createFixScenarioSession,
+    createWelcomeSession,
     sendMessage,
     retry,
     stop,
+    toggleNarratedMode,
+  }), [setClaudePanelOpen, openSession, switchSession, closeSession, openSessionPanel, createNewSession, createAddToBacklogSession, createRunScenarioSession, createFixScenarioSession, createWelcomeSession, sendMessage, retry, stop, toggleNarratedMode]);
 
-    // Direct setters (work through registry)
+  // Memoize persistence context — stable setters
+  const persistenceValue: SessionPersistenceContextValue = useMemo(() => ({
     setMessages,
     setStatus,
     setSessions,
     setActiveSessionId,
     setStandaloneSessions,
-  };
+  }), [setMessages, setStatus, setSessions, setActiveSessionId, setStandaloneSessions]);
 
   return (
-    <ClaudeSessionContext.Provider value={value}>
-      {children}
-    </ClaudeSessionContext.Provider>
+    <SessionStateContext.Provider value={stateValue}>
+      <SessionActionsContext.Provider value={actionsValue}>
+        <SessionPersistenceContext.Provider value={persistenceValue}>
+          {children}
+        </SessionPersistenceContext.Provider>
+      </SessionActionsContext.Provider>
+    </SessionStateContext.Provider>
   );
 }