feat: multi-session tab management with navigation source tracking

[liuyixin-louis]

Summary

Adds browser-style tab management to the chat area. Users can open multiple sessions as tabs, switch between them, and see processing indicators on background tabs.

Core innovation: Introduces sessionNavigationSource tracking ('user-sidebar' | 'user-new-session' | 'system') threaded from useProjectsState through AppContent to MainContent. This allows the tab sync logic to distinguish user-initiated navigation (sidebar click) from system-initiated session ID changes (session-created events), solving the cascade problem where agent responses triggered spurious tab creation.

New files

• src/hooks/useChatTabs.ts — Tab state management hook
• src/components/chat/view/ChatTabBar.tsx — Tab bar UI with processing indicators
• src/components/main-content/view/chatTabSync.ts — Pure function deciding tab action based on navigation source
• src/components/chat/hooks/chatSessionTransition.ts — Determines when to preserve optimistic messages during session ID promotion
• Unit tests — 10 tests covering tab sync, session transition, and tab bar rendering

Modified files

• useProjectsState.ts — Exposes sessionNavigationSource ref
• AppContent.tsx — Threads sessionNavigationSource to MainContent
• MainContent.tsx — Tab bar integration + sync effect using resolveChatTabSyncAction
• useChatSessionState.ts — In-memory message cache (10 entries, LRU eviction) for instant tab switching
• useChatRealtimeHandlers.ts — Cache invalidation on *-complete events

How tab sync works

resolveChatTabSyncAction({navigationSource, nextSessionId, activeChatTabSessionId, ...})
  → 'user-sidebar' + new session    → 'open-tab'
  → 'user-new-session'              → 'open-new-tab'  
  → 'system' (session-created)      → 'update-active-tab-session' (no UI disruption)
  → session already in active tab   → 'skip'

Test plan

• Open project, click session A → single tab visible
• Click session B in sidebar → second tab appears
• Switch between tabs → correct conversation loads (cached = instant)
• Send message in session → agent responds → stays in same tab (no jump)
• Click "New Session" → new tab opens with provider picker
• Close active tab → neighbor activates
• Background tab shows blue pulse while session is processing
• npx tsc --noEmit --skipLibCheck → 0 errors
• Tab-related tests: 10/10 pass
• Pre-existing tests: 49/49 pass (server tests have pre-existing failures unrelated to this PR)

🤖 Generated with Claude Code

[Zhang-Henry]

Code Review

Nice architecture — the pure resolveChatTabSyncAction function is cleanly isolated and well-tested. A few issues to address before merge:

Blockers

1. Duplicate useChatTabs export in src/hooks/useChatTabs.ts — there appear to be two export function useChatTabs() declarations with different signatures. This will fail TS compilation; looks like an unresolved merge artifact. Keep only the version actually consumed by MainContent.

2. sessionNavigationSource is never reset after consumption (useProjectsState.ts + MainContent.tsx sync effect). After the effect reads a 'system' source, nothing clears it, so a subsequent unrelated state change can misclassify as system-driven and suppress tab creation. Make it a one-shot ref that resets to 'user' immediately after resolveChatTabSyncAction is called.

3. "LRU" cache in useChatSessionState.ts is actually FIFO. SESSION_MESSAGE_CACHE_MAX = 10 evicts via Map.keys().next() (insertion order), not recency. A frequently-used tab opened long ago will be evicted before an untouched recent one. Either implement real LRU (delete+set on read to bump recency) or rename and document the FIFO semantics.

4. Incomplete cache invalidation in useChatRealtimeHandlers.ts — invalidation only fires on *-complete events. Missing: message edit / delete / stream-error events. Editing a message in the active tab and switching away/back will show the stale cached version.

Should-fix

5. No keyboard navigation in ChatTabBar.tsx. role="tab"/aria-selected are present, but there are no key handlers for ArrowLeft/Right, Enter/Space, Ctrl+Tab, and no focus management after closing the active tab. Keyboard-only users can't operate the tab bar.

6. docs/plans/2026-04-09-multi-session-tabs.md (454 lines) is a task-list spec, not a design doc — it bloats the PR and will rot. Move to an Issue / project tracker, or trim to a short architecture note.

7. Hard-coded 'new-session-' prefix in chatTabSync.ts (isTemporarySessionId) is fragile. Expose the prefix as a shared constant from wherever temp session IDs are generated.

Nits

• activeTabIdRef is declared in useChatTabs.ts but never used — dead code.
• Cache value types in useChatSessionState.ts use any[] / any — tighten to ChatMessage[] and the actual token usage type.
• Tab titles don't sync if a session is renamed server-side; document the limitation or subscribe to rename events.

Tests

The 10 unit tests cover the pure decision function well, but missing: race between session-created and user sidebar click, cache invalidation on edits/deletes, and keyboard navigation on ChatTabBar.

Overall the design is sound — mainly asking for the blockers above to be fixed before merge.

[liuyixin-louis]

Review Fixes Applied

Pushed feeab4d addressing all blockers from @Zhang-Henry's review:

Blockers Fixed

• B1 (duplicate export): Confirmed not present — only one useChatTabs export exists. Likely a diff rendering artifact.

• B2 (sessionNavigationSource never reset): Added resetSessionNavigationSource callback from useProjectsState, threaded through AppContent → MainContent. Called immediately after resolveChatTabSyncAction() consumes the value, preventing stale 'system' classification on subsequent state changes.

• B3 (FIFO → LRU cache): getCachedSessionMessages() now does delete + set on cache hit to bump the entry to most-recent position in Map iteration order. Frequently-used tabs stay cached.

• B4 (incomplete cache invalidation): Added invalidateSessionMessageCache() calls in all error handlers: claude-error, gemini-error, openrouter-error, localgpu-error, cursor-error, codex-error — same pattern as the *-complete handlers.

Additional Bug Fix

• [+] New Tab button: Was showing stale conversation instead of provider picker. Root cause: openNewTab() only updated tab state but didn't trigger the session lifecycle reset. Fix: [+] now calls onNewSession(selectedProject) (the existing handleNewSession from useProjectsState) which properly clears selectedSession, resets provider state, and navigates to /. Tab creation happens after state is clean.

• chatTabSync duplicate prevention: Added guard so when active tab already has sessionId === null, a nextSessionId: null event returns 'noop' instead of 'open-new-tab'.

Nits

• activeTabIdRef dead code — already removed in prior commit
• Should-fix items (keyboard nav, spec doc trim, shared constant) deferred to follow-up

Verification

• npx tsc --noEmit --skipLibCheck → 0 errors
• Component tests: 31/31 pass
• Manual testing: tab switching, [+] new tab, sending messages, background tab indicators all working

[Zhang-Henry]

Rebase needed before merge

fa69ddb 已推送，清掉了 review 里两处残余：

• 删除 useChatTabs.closeTab 里未读取的 pendingNavRef（死代码）
• ChatTabBar 的三个 <button> 补齐 type="button" + [+] 加 aria-label

验证：npx tsc --noEmit --skipLibCheck → 0 errors，tab 相关 10/10 tests pass。

但目前合不了：本分支落后 main 37 个 commit，冲突集中在 session lifecycle 核心文件：

• src/components/chat/hooks/useChatSessionState.ts — main 上已将 provider resolve 逻辑重构为 resolveSessionProviderForLoad，需要和本 PR 新增的 shouldPreserveOptimisticMessagesOnSessionSelect 重新交织
• src/components/main-content/view/MainContent.tsx — main 经历了 Topic/upstream session lifecycle 20260412 #167 revert 与 reapply（Revert "Topic/upstream session lifecycle 20260412" #169 / 1f20543），tab sync effect 需要放在新的 session lifecycle 之上重新评估

这些冲突不是机械性的，建议由熟悉本 PR 意图的作者来 rebase。

@liuyixin-louis 麻烦 rebase 到最新的 main 并解决冲突，然后 re-request @Zhang-Henry 复审。rebase 后若 tab sync 的行为有任何偏移，请同步更新 chatTabSync.test.ts / chatSessionTransition.test.ts。

[liuyixin-louis]

Superseded by #174 — clean rebase on latest main with all review fixes applied.