fix(chat): preserve continuity while session ids settle

New conversations were crossing a short but important consistency gap.
The route could already point at a newly created session id while the
projects payload had not refreshed yet, and realtime/optimistic messages
could still be keyed under a provisional id. In that window the UI could
stop reading the active session store, briefly render the conversation as
missing, and then repopulate it a moment later.

That same gap also made duplication more likely. Optimistic local user
messages could survive long enough to appear beside the persisted copy,
and finalized assistant streaming rows could sit directly next to the
server-backed assistant message with the same content before realtime state
was cleared. The result was a chat view that felt unstable exactly when a
new session was being created.

This commit makes session-id reconciliation a first-class part of the chat
flow instead of assuming every layer will agree immediately. The session
store now understands canonical session aliases and can migrate one
conversation from a provisional id to the real id without dropping its
in-memory state. The route navigation path can replace the provisional URL
entry instead of stacking it in history, and the project/session selection
logic keeps a synthetic selected session alive long enough for the sidebar
and project payloads to catch up.

The practical goal is to keep one visible conversation throughout the whole
creation lifecycle: no dead window between websocket events and project
refresh, no stale provisional URL after the real id is known, and no extra
optimistic/local bubbles when server history catches up.

src/components/chat/hooks/useChatRealtimeHandlers.ts

@@ -1,7 +1,8 @@
 import { useEffect, useRef } from 'react';
 import type { Dispatch, MutableRefObject, SetStateAction } from 'react';
+
 import { usePaletteOps } from '../../../contexts/PaletteOpsContext';
-import type { PendingPermissionRequest } from '../types/types';
+import type { PendingPermissionRequest, SessionNavigationOptions } from '../types/types';
 import type { Project, ProjectSession, LLMProvider } from '../../../types/app';
 import type { SessionStore, NormalizedMessage } from '../../../stores/useSessionStore';
 
@@ -67,7 +68,7 @@ interface UseChatRealtimeHandlersArgs {
   onSessionProcessing?: (sessionId?: string | null) => void;
   onSessionNotProcessing?: (sessionId?: string | null) => void;
   onReplaceTemporarySession?: (sessionId?: string | null) => void;
-  onNavigateToSession?: (sessionId: string) => void;
+  onNavigateToSession?: (sessionId: string, options?: SessionNavigationOptions) => void;
   onWebSocketReconnect?: () => void;
   sessionStore: SessionStore;
 }
@@ -273,13 +274,53 @@ export function useChatRealtimeHandlers({
           break;
         }
 
-        // Clear pending session
+        const actualSessionId =
+          typeof msg.actualSessionId === 'string' && msg.actualSessionId.trim().length > 0
+            ? msg.actualSessionId
+            : null;
         const pendingSessionId = sessionStorage.getItem('pendingSessionId');
-        if (pendingSessionId && !currentSessionId && msg.exitCode === 0) {
-          const actualId = msg.actualSessionId || pendingSessionId;
-          setCurrentSessionId(actualId);
-          if (msg.actualSessionId) {
-            onNavigateToSession?.(actualId);
+        const completedSuccessfully = msg.exitCode === undefined || msg.exitCode === 0;
+        const isVisibleSession =
+          Boolean(
+            sid
+            && (
+              sid === activeViewSessionId
+              || sid === pendingSessionId
+              || pendingViewSessionRef.current?.sessionId === sid
+            ),
+          );
+
+        if (actualSessionId && sid && actualSessionId !== sid) {
+          sessionStore.replaceSessionId(sid, actualSessionId);
+
+          if (isVisibleSession) {
+            setCurrentSessionId(actualSessionId);
+
+            if (pendingViewSessionRef.current) {
+              const pendingSession = pendingViewSessionRef.current.sessionId;
+              if (!pendingSession || pendingSession === sid) {
+                pendingViewSessionRef.current.sessionId = actualSessionId;
+              }
+            }
+          }
+
+          if (completedSuccessfully && pendingSessionId === sid) {
+            sessionStorage.removeItem('pendingSessionId');
+          }
+
+          if (isVisibleSession) {
+            onNavigateToSession?.(actualSessionId, { replace: true });
+            setTimeout(() => { void paletteOps.refreshProjects(); }, 500);
+          }
+          break;
+        }
+
+        // Clear pending session
+        if (pendingSessionId && !currentSessionId && completedSuccessfully) {
+          const resolvedSessionId = actualSessionId || pendingSessionId;
+          setCurrentSessionId(resolvedSessionId);
+          if (actualSessionId) {
+            onNavigateToSession?.(resolvedSessionId, { replace: true });
           }
           sessionStorage.removeItem('pendingSessionId');
           setTimeout(() => { void paletteOps.refreshProjects(); }, 500);

src/components/chat/hooks/useChatSessionState.ts

@@ -1,11 +1,13 @@
 import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } from 'react';
 import type { MutableRefObject } from 'react';
+
 import { authenticatedFetch } from '../../../utils/api';
-import type { ChatMessage, Provider } from '../types/types';
 import type { Project, ProjectSession, LLMProvider } from '../../../types/app';
-import { createCachedDiffCalculator, type DiffCalculator } from '../utils/messageTransforms';
-import { normalizedToChatMessages } from './useChatMessages';
 import type { SessionStore, NormalizedMessage } from '../../../stores/useSessionStore';
+import type { ChatMessage, Provider } from '../types/types';
+import { createCachedDiffCalculator, type DiffCalculator } from '../utils/messageTransforms';
+
+import { normalizedToChatMessages } from './useChatMessages';
 
 const MESSAGES_PER_PAGE = 20;
 const INITIAL_VISIBLE_MESSAGES = 100;
@@ -211,6 +213,7 @@ export function useChatSessionState({
 
   const activeSessionId = selectedSession?.id || currentSessionId || null;
   const [pendingUserMessage, setPendingUserMessage] = useState<ChatMessage | null>(null);
+  const flushedPendingUserMessageRef = useRef<ChatMessage | null>(null);
 
   // Tell the store which session we're viewing so it only re-renders for this one
   const prevActiveForStoreRef = useRef<string | null>(null);
@@ -219,17 +222,29 @@ export function useChatSessionState({
     sessionStore.setActiveSession(activeSessionId);
   }
 
-  // When a real session ID arrives and we have a pending user message, flush it to the store
-  const prevActiveSessionRef = useRef<string | null>(null);
-  if (activeSessionId && activeSessionId !== prevActiveSessionRef.current && pendingUserMessage) {
+  useEffect(() => {
+    if (!pendingUserMessage) {
+      flushedPendingUserMessageRef.current = null;
+      return;
+    }
+
+    if (!activeSessionId) {
+      return;
+    }
+
+    if (flushedPendingUserMessageRef.current === pendingUserMessage) {
+      return;
+    }
+
     const prov = (localStorage.getItem('selected-provider') as LLMProvider) || 'claude';
     const normalized = chatMessageToNormalized(pendingUserMessage, activeSessionId, prov);
     if (normalized) {
       sessionStore.appendRealtime(activeSessionId, normalized);
     }
+
+    flushedPendingUserMessageRef.current = pendingUserMessage;
     setPendingUserMessage(null);
-  }
-  prevActiveSessionRef.current = activeSessionId;
+  }, [activeSessionId, pendingUserMessage, sessionStore]);
 
   const storeMessages = activeSessionId ? sessionStore.getMessages(activeSessionId) : [];
 

src/components/chat/types/types.ts

@@ -91,6 +91,10 @@ export interface Question {
   multiSelect?: boolean;
 }
 
+export type SessionNavigationOptions = {
+  replace?: boolean;
+};
+
 export interface ChatInterfaceProps {
   selectedProject: Project | null;
   selectedSession: ProjectSession | null;
@@ -105,7 +109,7 @@ export interface ChatInterfaceProps {
   onSessionNotProcessing?: (sessionId?: string | null) => void;
   processingSessions?: Set<string>;
   onReplaceTemporarySession?: (sessionId?: string | null) => void;
-  onNavigateToSession?: (targetSessionId: string) => void;
+  onNavigateToSession?: (targetSessionId: string, options?: SessionNavigationOptions) => void;
   onShowSettings?: () => void;
   autoExpandTools?: boolean;
   showRawParameters?: boolean;