From f52e924b5be799bfda7212744a66cd3c0cb6965b Mon Sep 17 00:00:00 2001
From: Dan Shapiro <dan@example.com>
Date: Mon, 18 May 2026 03:23:06 -0700
Subject: [PATCH 1/3] feat: port multi-row tabs setting to main

---
 docs/index.html                               |   3 +
 shared/settings.ts                            |   7 +-
 src/components/TabBar.tsx                     | 141 +++++++---
 src/components/settings/WorkspaceSettings.tsx |   9 +
 src/hooks/useTabBarScroll.ts                  |  21 +-
 src/store/browserPreferencesPersistence.ts    |   1 +
 test/e2e-browser/specs/multirow-tabs.spec.ts  |  39 +++
 .../components/TabBar.multirow.test.tsx       | 240 ++++++++++++++++++
 .../browserPreferencesPersistence.test.ts     |  20 ++
 test/unit/shared/settings.test.ts             |  42 +++
 10 files changed, 473 insertions(+), 50 deletions(-)
 create mode 100644 test/e2e-browser/specs/multirow-tabs.spec.ts
 create mode 100644 test/unit/client/components/TabBar.multirow.test.tsx

diff --git a/docs/index.html b/docs/index.html
index 90206eb5a..68a6ca177 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -97,6 +97,9 @@
   background: hsl(var(--background)); flex-shrink: 0; position: relative; z-index: 20;
   transition: background-color .2s; gap: 2px;
 }
+.tabbar.multirow {
+  height: auto; max-height: 128px; flex-wrap: wrap; overflow-y: auto;
+}
 .tabbar::after {
   content: ''; position: absolute; inset: auto 0 0 0; height: 1px;
   background: hsl(var(--muted-foreground) / .45); z-index: 0;
diff --git a/shared/settings.ts b/shared/settings.ts
index 71ce9532d..928c4c1a3 100644
--- a/shared/settings.ts
+++ b/shared/settings.ts
@@ -53,7 +53,7 @@ const TERMINAL_LOCAL_KEYS = [
   'osc52Clipboard',
   'renderer',
 ] as const
-const PANES_LOCAL_KEYS = ['snapThreshold', 'iconsOnTabs', 'tabAttentionStyle', 'attentionDismiss', 'sessionOpenMode'] as const
+const PANES_LOCAL_KEYS = ['snapThreshold', 'iconsOnTabs', 'tabAttentionStyle', 'attentionDismiss', 'sessionOpenMode', 'multirowTabs'] as const
 const SIDEBAR_LOCAL_KEYS = [
   'sortMode',
   'worktreeGrouping',
@@ -178,6 +178,7 @@ export type LocalSettings = {
     tabAttentionStyle: TabAttentionStyle
     attentionDismiss: AttentionDismiss
     sessionOpenMode: SessionOpenMode
+    multirowTabs: boolean
   }
   sidebar: {
     sortMode: SidebarSortMode
@@ -435,6 +436,9 @@ function normalizeExtractedLocalSeed(patch: Record<string, unknown>): LocalSetti
     if (SessionOpenModeSchema.safeParse(patch.panes.sessionOpenMode).success) {
       panes.sessionOpenMode = patch.panes.sessionOpenMode as SessionOpenMode
     }
+    if (typeof patch.panes.multirowTabs === 'boolean') {
+      panes.multirowTabs = patch.panes.multirowTabs as boolean
+    }
     if (Object.keys(panes).length > 0) {
       normalized.panes = panes
     }
@@ -723,6 +727,7 @@ export const defaultLocalSettings: LocalSettings = {
     tabAttentionStyle: 'highlight',
     attentionDismiss: 'click',
     sessionOpenMode: 'tab',
+    multirowTabs: false,
   },
   sidebar: {
     sortMode: 'activity',
diff --git a/src/components/TabBar.tsx b/src/components/TabBar.tsx
index 2d170f67b..e68386ec6 100644
--- a/src/components/TabBar.tsx
+++ b/src/components/TabBar.tsx
@@ -7,7 +7,7 @@ import { getWsClient } from '@/lib/ws-client'
 import { getTabDisplayTitle } from '@/lib/tab-title'
 import { collectPaneEntries, collectTerminalIds } from '@/lib/pane-utils'
 import { getBusyPaneIdsForTab } from '@/lib/pane-activity'
-import { useCallback, useEffect, useMemo, useState } from 'react'
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
 import { useTabBarScroll } from '@/hooks/useTabBarScroll'
 import TabItem from './TabItem'
 import { cancelCodingCliRequest } from '@/store/codingCliSlice'
@@ -17,6 +17,7 @@ import { TabSwitcher } from './TabSwitcher'
 import {
   DndContext,
   closestCenter,
+  rectIntersection,
   KeyboardSensor,
   PointerSensor,
   TouchSensor,
@@ -30,9 +31,10 @@ import {
   SortableContext,
   sortableKeyboardCoordinates,
   horizontalListSortingStrategy,
+  rectSortingStrategy,
   useSortable,
 } from '@dnd-kit/sortable'
-import { CSS } from '@dnd-kit/utilities'
+import { CSS as DndCSS } from '@dnd-kit/utilities'
 import type { Tab, TabAttentionStyle } from '@/store/types'
 import type { PaneContent, PaneNode } from '@/store/paneTypes'
 import type { ChatSessionState } from '@/store/agentChatTypes'
@@ -40,6 +42,13 @@ import type { PaneRuntimeActivityRecord } from '@/store/paneRuntimeActivitySlice
 import { ContextIds } from '@/components/context-menu/context-menu-constants'
 import { applyTabRename } from '@/store/titleSync'
 
+function escapeSelector(id: string): string {
+  if (typeof CSS !== 'undefined' && typeof CSS.escape === 'function') {
+    return CSS.escape(id)
+  }
+  return id.replace(/(["\\])/g, '\\$1')
+}
+
 interface SortableTabProps {
   tab: Tab
   displayTitle: string
@@ -90,7 +99,7 @@ function SortableTab({
   } = useSortable({ id: tab.id })
 
   const style = {
-    transform: CSS.Transform.toString(transform),
+    transform: DndCSS.Transform.toString(transform),
     transition: transition || 'transform 150ms ease',
   }
 
@@ -161,6 +170,7 @@ export default function TabBar({ sidebarCollapsed, onToggleSidebar }: TabBarProp
   const attentionDismiss = useAppSelector((s) => s.settings?.settings?.panes?.attentionDismiss ?? 'click')
   const iconsOnTabs = useAppSelector((s) => s.settings?.settings?.panes?.iconsOnTabs ?? true)
   const tabAttentionStyle = useAppSelector((s) => s.settings?.settings?.panes?.tabAttentionStyle ?? 'highlight')
+  const multirowTabs = useAppSelector((s) => s.settings?.settings?.panes?.multirowTabs ?? false)
   const extensions = useAppSelector((s) => s.extensions?.entries)
 
   const ws = useMemo(() => getWsClient(), [])
@@ -369,11 +379,47 @@ export default function TabBar({ sidebarCollapsed, onToggleSidebar }: TabBarProp
     callbackRef,
     canScrollLeft,
     canScrollRight,
+    scrollToTab,
     handleArrowClick,
     startHoldScroll,
     stopHoldScroll,
     cancelHoldScroll,
-  } = useTabBarScroll(activeTabId, tabs.length)
+  } = useTabBarScroll(activeTabId, tabs.length, multirowTabs)
+
+  // Container ref for multirow auto-scroll (scoped, not global DOM query)
+  const multirowContainerRef = useRef<HTMLDivElement | null>(null)
+  const combinedRef = useCallback((node: HTMLDivElement | null) => {
+    callbackRef(node)
+    multirowContainerRef.current = node
+  }, [callbackRef])
+
+  // Container-scoped scroll for active tab in multirow mode (vertical)
+  useEffect(() => {
+    if (!multirowTabs || !activeTabId) return
+    const container = multirowContainerRef.current
+    if (!container) return
+    const tabEl = container.querySelector(`[data-tab-id="${escapeSelector(activeTabId)}"]`) as HTMLElement | null
+    if (!tabEl) return
+    const containerRect = container.getBoundingClientRect()
+    const tabRect = tabEl.getBoundingClientRect()
+    // Only scroll if tab is outside the visible area
+    if (tabRect.top < containerRect.top || tabRect.bottom > containerRect.bottom) {
+      const offset = tabRect.top - containerRect.top - (containerRect.height / 2) + (tabRect.height / 2)
+      container.scrollBy({ top: offset, behavior: 'smooth' })
+    }
+  }, [activeTabId, multirowTabs])
+
+  // Re-fire horizontal scroll when transitioning from multirow to single-row
+  const prevMultirowRef = useRef(multirowTabs)
+  useEffect(() => {
+    let raf: number | null = null
+    if (prevMultirowRef.current && !multirowTabs && activeTabId) {
+      // Defer to next frame so the DOM has re-rendered with single-row layout
+      raf = requestAnimationFrame(() => scrollToTab(activeTabId))
+    }
+    prevMultirowRef.current = multirowTabs
+    return () => { if (raf !== null) cancelAnimationFrame(raf) }
+  }, [multirowTabs, activeTabId, scrollToTab])
 
   const activeTab = activeId ? tabs.find((t: Tab) => t.id === activeId) : null
 
@@ -395,43 +441,54 @@ export default function TabBar({ sidebarCollapsed, onToggleSidebar }: TabBarProp
   }
 
   return (
-    <div className="relative z-20 h-12 md:h-10 shrink-0 flex items-end px-2 bg-background" data-context={ContextIds.Global}>
+    <div className={cn(
+      "relative z-20 shrink-0 flex items-end px-2 bg-background",
+      multirowTabs ? "h-auto" : "h-12 md:h-10"
+    )} data-context={ContextIds.Global}>
       <div
         className="pointer-events-none absolute inset-x-0 bottom-0 h-px bg-muted-foreground/45"
         aria-hidden="true"
       />
       <DndContext
         sensors={sensors}
-        collisionDetection={closestCenter}
+        collisionDetection={multirowTabs ? rectIntersection : closestCenter}
         onDragStart={handleDragStart}
         onDragEnd={handleDragEnd}
       >
         <SortableContext
           items={tabs.map((t: Tab) => t.id)}
-          strategy={horizontalListSortingStrategy}
+          strategy={multirowTabs ? rectSortingStrategy : horizontalListSortingStrategy}
         >
           {/* Left scroll arrow -- flex sibling alongside the scroll container */}
-          <button
-            className={cn(
-              'flex-shrink-0 w-7 h-8 flex items-center justify-center rounded-md text-muted-foreground hover:text-foreground hover:bg-muted/30 transition-all duration-150',
-              canScrollLeft ? 'opacity-100' : 'opacity-0 pointer-events-none',
-            )}
-            aria-label="Scroll tabs left"
-            aria-hidden={canScrollLeft ? undefined : true}
-            tabIndex={canScrollLeft ? 0 : -1}
-            onClick={() => handleArrowClick('left')}
-            onPointerDown={() => startHoldScroll('left')}
-            onPointerUp={stopHoldScroll}
-            onPointerLeave={cancelHoldScroll}
-            onPointerCancel={cancelHoldScroll}
-          >
-            <ChevronLeft className="h-4 w-4" />
-          </button>
+          {!multirowTabs && (
+            <button
+              className={cn(
+                'flex-shrink-0 w-7 h-8 flex items-center justify-center rounded-md text-muted-foreground hover:text-foreground hover:bg-muted/30 transition-all duration-150',
+                canScrollLeft ? 'opacity-100' : 'opacity-0 pointer-events-none',
+              )}
+              aria-label="Scroll tabs left"
+              aria-hidden={canScrollLeft ? undefined : true}
+              tabIndex={canScrollLeft ? 0 : -1}
+              onClick={() => handleArrowClick('left')}
+              onPointerDown={() => startHoldScroll('left')}
+              onPointerUp={stopHoldScroll}
+              onPointerLeave={cancelHoldScroll}
+              onPointerCancel={cancelHoldScroll}
+            >
+              <ChevronLeft className="h-4 w-4" />
+            </button>
+          )}
 
           {/* Scrollable tab strip */}
           <div
-            ref={callbackRef}
-            className="flex items-end gap-0.5 overflow-x-auto overflow-y-hidden scrollbar-none pt-px flex-1 min-w-0"
+            ref={combinedRef}
+            data-testid="tab-strip"
+            className={cn(
+              "flex items-end gap-0.5 pt-px flex-1 min-w-0",
+              multirowTabs
+                ? "flex-wrap max-h-32 overflow-y-auto"
+                : "overflow-x-auto overflow-y-hidden scrollbar-none"
+            )}
           >
             {sidebarCollapsed && onToggleSidebar && (
               <button
@@ -447,22 +504,24 @@ export default function TabBar({ sidebarCollapsed, onToggleSidebar }: TabBarProp
           </div>
 
           {/* Right scroll arrow -- flex sibling alongside the scroll container */}
-          <button
-            className={cn(
-              'flex-shrink-0 w-7 h-8 flex items-center justify-center rounded-md text-muted-foreground hover:text-foreground hover:bg-muted/30 transition-all duration-150',
-              canScrollRight ? 'opacity-100' : 'opacity-0 pointer-events-none',
-            )}
-            aria-label="Scroll tabs right"
-            aria-hidden={canScrollRight ? undefined : true}
-            tabIndex={canScrollRight ? 0 : -1}
-            onClick={() => handleArrowClick('right')}
-            onPointerDown={() => startHoldScroll('right')}
-            onPointerUp={stopHoldScroll}
-            onPointerLeave={cancelHoldScroll}
-            onPointerCancel={cancelHoldScroll}
-          >
-            <ChevronRight className="h-4 w-4" />
-          </button>
+          {!multirowTabs && (
+            <button
+              className={cn(
+                'flex-shrink-0 w-7 h-8 flex items-center justify-center rounded-md text-muted-foreground hover:text-foreground hover:bg-muted/30 transition-all duration-150',
+                canScrollRight ? 'opacity-100' : 'opacity-0 pointer-events-none',
+              )}
+              aria-label="Scroll tabs right"
+              aria-hidden={canScrollRight ? undefined : true}
+              tabIndex={canScrollRight ? 0 : -1}
+              onClick={() => handleArrowClick('right')}
+              onPointerDown={() => startHoldScroll('right')}
+              onPointerUp={stopHoldScroll}
+              onPointerLeave={cancelHoldScroll}
+              onPointerCancel={cancelHoldScroll}
+            >
+              <ChevronRight className="h-4 w-4" />
+            </button>
+          )}
         </SortableContext>
 
         {/* Pinned + button -- outside the scrollable area */}
diff --git a/src/components/settings/WorkspaceSettings.tsx b/src/components/settings/WorkspaceSettings.tsx
index afc1edf61..8f2da4322 100644
--- a/src/components/settings/WorkspaceSettings.tsx
+++ b/src/components/settings/WorkspaceSettings.tsx
@@ -211,6 +211,15 @@ export default function WorkspaceSettings({
           />
         </SettingsRow>
 
+        <SettingsRow label="Multi-row tabs" description="Show tabs in multiple rows instead of a single scrollable row.">
+          <Toggle
+            checked={settings.panes?.multirowTabs ?? false}
+            onChange={(checked) => {
+              applyLocalSetting({ panes: { multirowTabs: checked } })
+            }}
+          />
+        </SettingsRow>
+
         <SettingsRow label="Tab completion indicator">
           <SegmentedControl
             value={settings.panes?.tabAttentionStyle ?? 'highlight'}
diff --git a/src/hooks/useTabBarScroll.ts b/src/hooks/useTabBarScroll.ts
index a0e1a2357..57dc7ac11 100644
--- a/src/hooks/useTabBarScroll.ts
+++ b/src/hooks/useTabBarScroll.ts
@@ -22,7 +22,7 @@ interface TabBarScrollResult extends TabBarScrollState {
 const SCROLL_THRESHOLD = 2 // px tolerance for scroll boundary detection
 const HOLD_SCROLL_SPEED = 4 // px per frame (~240px/s at 60fps)
 
-export function useTabBarScroll(activeTabId: string | null, tabCount: number): TabBarScrollResult {
+export function useTabBarScroll(activeTabId: string | null, tabCount: number, disabled = false): TabBarScrollResult {
   const nodeRef = useRef<HTMLDivElement | null>(null)
   const cleanupRef = useRef<(() => void) | null>(null)
   const holdRafRef = useRef<number | null>(null)
@@ -34,15 +34,20 @@ export function useTabBarScroll(activeTabId: string | null, tabCount: number): T
 
   const updateOverflow = useCallback((el: HTMLDivElement | null) => {
     if (!el) {
-      setOverflow({ canScrollLeft: false, canScrollRight: false })
+      setOverflow(prev =>
+        (prev.canScrollLeft === false && prev.canScrollRight === false) ? prev : { canScrollLeft: false, canScrollRight: false }
+      )
       return
     }
 
     const { scrollLeft, scrollWidth, clientWidth } = el
-    setOverflow({
-      canScrollLeft: scrollLeft > SCROLL_THRESHOLD,
-      canScrollRight: scrollLeft + clientWidth < scrollWidth - SCROLL_THRESHOLD,
-    })
+    const canScrollLeft = scrollLeft > SCROLL_THRESHOLD
+    const canScrollRight = scrollLeft + clientWidth < scrollWidth - SCROLL_THRESHOLD
+    setOverflow(prev =>
+      (prev.canScrollLeft === canScrollLeft && prev.canScrollRight === canScrollRight)
+        ? prev
+        : { canScrollLeft, canScrollRight }
+    )
   }, [])
 
   const callbackRef = useCallback((node: HTMLDivElement | null) => {
@@ -54,7 +59,7 @@ export function useTabBarScroll(activeTabId: string | null, tabCount: number): T
 
     nodeRef.current = node
 
-    if (!node) {
+    if (!node || disabled) {
       updateOverflow(null)
       return
     }
@@ -83,7 +88,7 @@ export function useTabBarScroll(activeTabId: string | null, tabCount: number): T
 
     // Initial overflow check
     updateOverflow(node)
-  }, [updateOverflow])
+  }, [updateOverflow, disabled])
 
   // Clean up on unmount
   useEffect(() => {
diff --git a/src/store/browserPreferencesPersistence.ts b/src/store/browserPreferencesPersistence.ts
index 124725b42..96bcfa987 100644
--- a/src/store/browserPreferencesPersistence.ts
+++ b/src/store/browserPreferencesPersistence.ts
@@ -109,6 +109,7 @@ export function buildLocalSettingsPatch(localSettings: LocalSettings): LocalSett
   assignChangedScalar(panes, localSettings.panes, defaultLocalSettings.panes, 'tabAttentionStyle')
   assignChangedScalar(panes, localSettings.panes, defaultLocalSettings.panes, 'attentionDismiss')
   assignChangedScalar(panes, localSettings.panes, defaultLocalSettings.panes, 'sessionOpenMode')
+  assignChangedScalar(panes, localSettings.panes, defaultLocalSettings.panes, 'multirowTabs')
   if (Object.keys(panes).length > 0) {
     patch.panes = panes
   }
diff --git a/test/e2e-browser/specs/multirow-tabs.spec.ts b/test/e2e-browser/specs/multirow-tabs.spec.ts
new file mode 100644
index 000000000..996639c07
--- /dev/null
+++ b/test/e2e-browser/specs/multirow-tabs.spec.ts
@@ -0,0 +1,39 @@
+import { test, expect } from '../helpers/fixtures.js'
+
+test.describe('Multi-row tabs', () => {
+  async function openSettings(page: any) {
+    await page.getByRole('button', { name: /settings/i }).click()
+    await expect(page.getByRole('tab', { name: /^Appearance$/i })).toBeVisible({ timeout: 10_000 })
+  }
+
+  test('enables multi-row tabs via settings toggle', async ({ freshellPage: page }) => {
+    await openSettings(page)
+
+    const toggle = page.getByRole('switch', { name: /multi-row tabs/i })
+    await expect(toggle).toBeVisible({ timeout: 5_000 })
+    await expect(toggle).not.toBeChecked()
+    await toggle.click()
+    await expect(toggle).toBeChecked()
+  })
+
+  test('multi-row mode applies flex-wrap to tab strip', async ({ freshellPage: page }) => {
+    await page.evaluate(() => {
+      window.__FRESHELL_TEST_HARNESS__?.dispatch({
+        type: 'settings/updateSettingsLocal',
+        payload: { panes: { multirowTabs: true } },
+      })
+    })
+
+    const tabStrip = page.getByTestId('tab-strip')
+    await expect(tabStrip).toBeVisible({ timeout: 5_000 })
+    await expect(tabStrip).toHaveClass(/flex-wrap/)
+    await expect(tabStrip).toHaveClass(/max-h-32/)
+  })
+
+  test('single-row mode uses overflow-x-auto', async ({ freshellPage: page }) => {
+    const tabStrip = page.getByTestId('tab-strip')
+    await expect(tabStrip).toBeVisible({ timeout: 5_000 })
+    await expect(tabStrip).toHaveClass(/overflow-x-auto/)
+    await expect(tabStrip).not.toHaveClass(/flex-wrap/)
+  })
+})
diff --git a/test/unit/client/components/TabBar.multirow.test.tsx b/test/unit/client/components/TabBar.multirow.test.tsx
new file mode 100644
index 000000000..b69fc4270
--- /dev/null
+++ b/test/unit/client/components/TabBar.multirow.test.tsx
@@ -0,0 +1,240 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import { render, screen, cleanup } from '@testing-library/react'
+import { configureStore } from '@reduxjs/toolkit'
+import { Provider } from 'react-redux'
+import TabBar from '@/components/TabBar'
+import tabsReducer from '@/store/tabsSlice'
+import codingCliReducer from '@/store/codingCliSlice'
+import codexActivityReducer from '@/store/codexActivitySlice'
+import opencodeActivityReducer from '@/store/opencodeActivitySlice'
+import panesReducer from '@/store/panesSlice'
+import settingsReducer, { defaultSettings } from '@/store/settingsSlice'
+import turnCompletionReducer from '@/store/turnCompletionSlice'
+import type { Tab } from '@/store/types'
+import {
+  composeResolvedSettings,
+  createDefaultServerSettings,
+  resolveLocalSettings,
+} from '@shared/settings'
+
+vi.mock('@/lib/ws-client', () => ({
+  getWsClient: () => ({ send: vi.fn() }),
+}))
+
+vi.mock('lucide-react', () => ({
+  X: ({ className }: { className?: string }) => <svg data-testid="x-icon" className={className} />,
+  Plus: ({ className }: { className?: string }) => <svg data-testid="plus-icon" className={className} />,
+  Circle: ({ className }: { className?: string }) => <svg data-testid="circle-icon" className={className} />,
+  ChevronDown: ({ className }: { className?: string }) => <svg data-testid="chevron-down-icon" className={className} />,
+  ChevronLeft: ({ className }: { className?: string }) => <svg data-testid="chevron-left-icon" className={className} />,
+  ChevronRight: ({ className }: { className?: string }) => <svg data-testid="chevron-right-icon" className={className} />,
+  Terminal: ({ className }: { className?: string }) => <svg data-testid="terminal-icon" className={className} />,
+  MessageSquare: ({ className }: { className?: string }) => <svg data-testid="message-square-icon" className={className} />,
+  PanelLeft: ({ className }: { className?: string }) => <svg data-testid="panel-left-icon" className={className} />,
+}))
+
+vi.mock('@/components/icons/PaneIcon', () => ({
+  default: ({ content, className }: any) => (
+    <svg data-testid="pane-icon" data-content-kind={content?.kind} data-content-mode={content?.mode} className={className} />
+  ),
+}))
+
+function createTab(overrides: Partial<Tab> = {}): Tab {
+  return {
+    id: `tab-${Math.random().toString(36).slice(2)}`,
+    createRequestId: 'req-1',
+    title: 'Terminal 1',
+    status: 'running',
+    mode: 'shell',
+    shell: 'system',
+    createdAt: Date.now(),
+    ...overrides,
+  }
+}
+
+function createStore(options: { tabs: Tab[]; activeTabId: string | null; multirowTabs?: boolean }) {
+  const localSettings = resolveLocalSettings(
+    options.multirowTabs ? { panes: { multirowTabs: true } } : undefined,
+  )
+  const serverSettings = createDefaultServerSettings({
+    loggingDebug: defaultSettings.logging.debug,
+  })
+
+  return configureStore({
+    reducer: {
+      tabs: tabsReducer,
+      codingCli: codingCliReducer,
+      codexActivity: codexActivityReducer,
+      opencodeActivity: opencodeActivityReducer,
+      panes: panesReducer,
+      settings: settingsReducer,
+      turnCompletion: turnCompletionReducer,
+    },
+    preloadedState: {
+      tabs: { tabs: options.tabs, activeTabId: options.activeTabId, renameRequestTabId: null },
+      codingCli: { sessions: {}, pendingRequests: {} },
+      codexActivity: { byTerminalId: {}, lastSnapshotSeq: 0, liveMutationSeqByTerminalId: {}, removedMutationSeqByTerminalId: {} },
+      opencodeActivity: { byTerminalId: {}, lastSnapshotSeq: 0, liveMutationSeqByTerminalId: {}, removedMutationSeqByTerminalId: {} },
+      panes: { layouts: {}, activePane: {}, paneTitles: {} },
+      settings: {
+        serverSettings,
+        localSettings,
+        settings: composeResolvedSettings(serverSettings, localSettings),
+        loaded: true,
+      },
+      turnCompletion: { seq: 0, lastEvent: null, pendingEvents: [], attentionByTab: {} },
+    },
+  })
+}
+
+function renderWithStore(ui: React.ReactElement, store: ReturnType<typeof createStore>) {
+  return render(<Provider store={store}>{ui}</Provider>)
+}
+
+beforeEach(() => {
+  vi.clearAllMocks()
+})
+
+afterEach(() => cleanup())
+
+describe('TabBar multirow tabs', () => {
+  it('uses flex-wrap on the tab strip container when multirowTabs is enabled', () => {
+    const tab = createTab({ id: 'tab-1' })
+    const store = createStore({ tabs: [tab], activeTabId: 'tab-1', multirowTabs: true })
+    const { container } = renderWithStore(<TabBar />, store)
+
+    const flexWrap = container.querySelector('.flex-wrap')
+    expect(flexWrap).not.toBeNull()
+  })
+
+  it('does not use flex-wrap when multirowTabs is disabled (default)', () => {
+    const tab = createTab({ id: 'tab-1' })
+    const store = createStore({ tabs: [tab], activeTabId: 'tab-1', multirowTabs: false })
+    const { container } = renderWithStore(<TabBar />, store)
+
+    const flexWrap = container.querySelector('.flex-wrap')
+    expect(flexWrap).toBeNull()
+  })
+
+  it('uses overflow-x-auto when multirowTabs is disabled (default)', () => {
+    const tab = createTab({ id: 'tab-1' })
+    const store = createStore({ tabs: [tab], activeTabId: 'tab-1', multirowTabs: false })
+    const { container } = renderWithStore(<TabBar />, store)
+
+    const scrollContainer = container.querySelector('.overflow-x-auto')
+    expect(scrollContainer).not.toBeNull()
+  })
+
+  it('does not render scroll arrow buttons when multirowTabs is enabled', () => {
+    const tab = createTab({ id: 'tab-1' })
+    const store = createStore({ tabs: [tab], activeTabId: 'tab-1', multirowTabs: true })
+    renderWithStore(<TabBar />, store)
+
+    const leftBtn = screen.queryByLabelText('Scroll tabs left')
+    const rightBtn = screen.queryByLabelText('Scroll tabs right')
+    expect(leftBtn).toBeNull()
+    expect(rightBtn).toBeNull()
+  })
+
+  it('renders scroll arrow buttons when multirowTabs is disabled', () => {
+    const tab = createTab({ id: 'tab-1' })
+    const store = createStore({ tabs: [tab], activeTabId: 'tab-1', multirowTabs: false })
+    renderWithStore(<TabBar />, store)
+
+    const leftBtn = screen.getByLabelText('Scroll tabs left')
+    const rightBtn = screen.getByLabelText('Scroll tabs right')
+    expect(leftBtn).toBeInTheDocument()
+    expect(rightBtn).toBeInTheDocument()
+  })
+
+  it('applies h-auto to the outer wrapper and max-h-32 to the tab strip when multirowTabs is enabled', () => {
+    const tab = createTab({ id: 'tab-1' })
+    const store = createStore({ tabs: [tab], activeTabId: 'tab-1', multirowTabs: true })
+    const { container } = renderWithStore(<TabBar />, store)
+
+    const wrapper = container.firstElementChild as HTMLElement
+    expect(wrapper.className).toContain('h-auto')
+    expect(wrapper.className).not.toContain('h-12')
+
+    const tabStrip = container.querySelector('.flex-wrap')
+    expect(tabStrip).not.toBeNull()
+    expect(tabStrip!.className).toContain('max-h-32')
+  })
+
+  it('applies fixed height to the outer wrapper when multirowTabs is disabled', () => {
+    const tab = createTab({ id: 'tab-1' })
+    const store = createStore({ tabs: [tab], activeTabId: 'tab-1', multirowTabs: false })
+    const { container } = renderWithStore(<TabBar />, store)
+
+    const wrapper = container.firstElementChild as HTMLElement
+    expect(wrapper.className).toContain('h-12')
+    expect(wrapper.className).not.toContain('h-auto')
+  })
+
+  it('still renders all tabs when multirowTabs is enabled', () => {
+    const tabs = [
+      createTab({ id: 'tab-1', title: 'Tab 1' }),
+      createTab({ id: 'tab-2', title: 'Tab 2' }),
+      createTab({ id: 'tab-3', title: 'Tab 3' }),
+    ]
+    const store = createStore({ tabs, activeTabId: 'tab-1', multirowTabs: true })
+    renderWithStore(<TabBar />, store)
+
+    expect(screen.getByText('Tab 1')).toBeInTheDocument()
+    expect(screen.getByText('Tab 2')).toBeInTheDocument()
+    expect(screen.getByText('Tab 3')).toBeInTheDocument()
+  })
+
+  it('still renders the + new tab button when multirowTabs is enabled', () => {
+    const tab = createTab({ id: 'tab-1' })
+    const store = createStore({ tabs: [tab], activeTabId: 'tab-1', multirowTabs: true })
+    renderWithStore(<TabBar />, store)
+
+    const addButton = screen.getByRole('button', { name: 'New shell tab' })
+    expect(addButton).toBeInTheDocument()
+  })
+
+  it('does not use overflow-y-auto on the tab strip when multirowTabs is disabled', () => {
+    const tab = createTab({ id: 'tab-1' })
+    const store = createStore({ tabs: [tab], activeTabId: 'tab-1', multirowTabs: false })
+    const { container } = renderWithStore(<TabBar />, store)
+
+    const scrollContainer = container.querySelector('.overflow-x-auto')
+    expect(scrollContainer).not.toBeNull()
+    expect(scrollContainer!.className).not.toContain('overflow-y-auto')
+  })
+
+  it('uses overflow-y-auto on the tab strip when multirowTabs is enabled', () => {
+    const tab = createTab({ id: 'tab-1' })
+    const store = createStore({ tabs: [tab], activeTabId: 'tab-1', multirowTabs: true })
+    const { container } = renderWithStore(<TabBar />, store)
+
+    const flexWrap = container.querySelector('.flex-wrap')
+    expect(flexWrap).not.toBeNull()
+    expect(flexWrap!.className).toContain('overflow-y-auto')
+  })
+
+  it('does not apply overflow-x-hidden to the tab strip when multirowTabs is enabled', () => {
+    const tab = createTab({ id: 'tab-1' })
+    const store = createStore({ tabs: [tab], activeTabId: 'tab-1', multirowTabs: true })
+    const { container } = renderWithStore(<TabBar />, store)
+
+    const flexWrap = container.querySelector('.flex-wrap')
+    expect(flexWrap).not.toBeNull()
+    expect(flexWrap!.className).not.toContain('overflow-x-hidden')
+  })
+
+  it('keeps the sidebar reopen control inside the wrapped tab strip in multirow mode', () => {
+    const tab = createTab({ id: 'tab-1' })
+    const store = createStore({ tabs: [tab], activeTabId: 'tab-1', multirowTabs: true })
+    const { container } = renderWithStore(
+      <TabBar sidebarCollapsed={true} onToggleSidebar={() => {}} />,
+      store,
+    )
+
+    const tabStrip = container.querySelector('[data-testid="tab-strip"]')
+    const button = screen.getByRole('button', { name: 'Show sidebar' })
+    expect(tabStrip).not.toBeNull()
+    expect(tabStrip).toContainElement(button)
+  })
+})
diff --git a/test/unit/client/store/browserPreferencesPersistence.test.ts b/test/unit/client/store/browserPreferencesPersistence.test.ts
index 804e3af5f..2590fff63 100644
--- a/test/unit/client/store/browserPreferencesPersistence.test.ts
+++ b/test/unit/client/store/browserPreferencesPersistence.test.ts
@@ -64,6 +64,26 @@ describe('browserPreferencesPersistence', () => {
     })
   })
 
+  it('persists multirowTabs when enabled locally', () => {
+    const store = createStore()
+
+    store.dispatch(updateSettingsLocal({
+      panes: {
+        multirowTabs: true,
+      },
+    }))
+
+    vi.advanceTimersByTime(BROWSER_PREFERENCES_PERSIST_DEBOUNCE_MS)
+
+    expect(JSON.parse(localStorage.getItem(BROWSER_PREFERENCES_STORAGE_KEY) || '{}')).toEqual({
+      settings: {
+        panes: {
+          multirowTabs: true,
+        },
+      },
+    })
+  })
+
   it('debounces updateSettingsLocal writes and flushes them on pagehide', () => {
     const store = createStore()
 
diff --git a/test/unit/shared/settings.test.ts b/test/unit/shared/settings.test.ts
index 6ae7eeafc..46f1f4bb6 100644
--- a/test/unit/shared/settings.test.ts
+++ b/test/unit/shared/settings.test.ts
@@ -310,4 +310,46 @@ describe('shared settings contract', () => {
       },
     })
   })
+
+  it('defaults multirowTabs to false in resolved local settings', () => {
+    expect(resolveLocalSettings(undefined).panes.multirowTabs).toBe(false)
+  })
+
+  it('accepts multirowTabs boolean in local settings patch', () => {
+    const resolved = resolveLocalSettings({ panes: { multirowTabs: true } })
+    expect(resolved.panes.multirowTabs).toBe(true)
+  })
+
+  it('preserves multirowTabs when extracting legacy local settings seed', () => {
+    expect(extractLegacyLocalSettingsSeed({
+      panes: {
+        multirowTabs: true,
+      },
+    } as Record<string, unknown>)).toEqual({
+      panes: {
+        multirowTabs: true,
+      },
+    })
+  })
+
+  it('rejects non-boolean multirowTabs in legacy seed extraction', () => {
+    expect(extractLegacyLocalSettingsSeed({
+      panes: {
+        multirowTabs: 'yes',
+      },
+    } as Record<string, unknown>)).toEqual(undefined)
+  })
+
+  it('includes multirowTabs in composed resolved settings', () => {
+    const resolved = composeResolvedSettings(
+      createDefaultServerSettings({ loggingDebug: false }),
+      resolveLocalSettings({ panes: { multirowTabs: true } }),
+    )
+    expect(resolved.panes.multirowTabs).toBe(true)
+  })
+
+  it('rejects multirowTabs in server patch schema', () => {
+    const schema = buildServerSettingsPatchSchema()
+    expect(schema.safeParse({ panes: { multirowTabs: true } }).success).toBe(false)
+  })
 })

From 95bbf1c26ad48f70ca5e67a0260e1d6aeda8f9cf Mon Sep 17 00:00:00 2001
From: Dan Shapiro <dan@example.com>
Date: Mon, 18 May 2026 04:19:30 -0700
Subject: [PATCH 2/3] fix: align multi-row tab parity with dev

---
 src/components/TabBar.tsx                     | 64 +++++++++----------
 .../browserPreferencesPersistence.test.ts     | 20 ------
 2 files changed, 32 insertions(+), 52 deletions(-)

diff --git a/src/components/TabBar.tsx b/src/components/TabBar.tsx
index e68386ec6..88278630a 100644
--- a/src/components/TabBar.tsx
+++ b/src/components/TabBar.tsx
@@ -461,22 +461,22 @@ export default function TabBar({ sidebarCollapsed, onToggleSidebar }: TabBarProp
         >
           {/* Left scroll arrow -- flex sibling alongside the scroll container */}
           {!multirowTabs && (
-            <button
-              className={cn(
-                'flex-shrink-0 w-7 h-8 flex items-center justify-center rounded-md text-muted-foreground hover:text-foreground hover:bg-muted/30 transition-all duration-150',
-                canScrollLeft ? 'opacity-100' : 'opacity-0 pointer-events-none',
-              )}
-              aria-label="Scroll tabs left"
-              aria-hidden={canScrollLeft ? undefined : true}
-              tabIndex={canScrollLeft ? 0 : -1}
-              onClick={() => handleArrowClick('left')}
-              onPointerDown={() => startHoldScroll('left')}
-              onPointerUp={stopHoldScroll}
-              onPointerLeave={cancelHoldScroll}
-              onPointerCancel={cancelHoldScroll}
-            >
-              <ChevronLeft className="h-4 w-4" />
-            </button>
+          <button
+            className={cn(
+              'flex-shrink-0 w-7 h-8 flex items-center justify-center rounded-md text-muted-foreground hover:text-foreground hover:bg-muted/30 transition-all duration-150',
+              canScrollLeft ? 'opacity-100' : 'opacity-0 pointer-events-none',
+            )}
+            aria-label="Scroll tabs left"
+            aria-hidden={canScrollLeft ? undefined : true}
+            tabIndex={canScrollLeft ? 0 : -1}
+            onClick={() => handleArrowClick('left')}
+            onPointerDown={() => startHoldScroll('left')}
+            onPointerUp={stopHoldScroll}
+            onPointerLeave={cancelHoldScroll}
+            onPointerCancel={cancelHoldScroll}
+          >
+            <ChevronLeft className="h-4 w-4" />
+          </button>
           )}
 
           {/* Scrollable tab strip */}
@@ -505,22 +505,22 @@ export default function TabBar({ sidebarCollapsed, onToggleSidebar }: TabBarProp
 
           {/* Right scroll arrow -- flex sibling alongside the scroll container */}
           {!multirowTabs && (
-            <button
-              className={cn(
-                'flex-shrink-0 w-7 h-8 flex items-center justify-center rounded-md text-muted-foreground hover:text-foreground hover:bg-muted/30 transition-all duration-150',
-                canScrollRight ? 'opacity-100' : 'opacity-0 pointer-events-none',
-              )}
-              aria-label="Scroll tabs right"
-              aria-hidden={canScrollRight ? undefined : true}
-              tabIndex={canScrollRight ? 0 : -1}
-              onClick={() => handleArrowClick('right')}
-              onPointerDown={() => startHoldScroll('right')}
-              onPointerUp={stopHoldScroll}
-              onPointerLeave={cancelHoldScroll}
-              onPointerCancel={cancelHoldScroll}
-            >
-              <ChevronRight className="h-4 w-4" />
-            </button>
+          <button
+            className={cn(
+              'flex-shrink-0 w-7 h-8 flex items-center justify-center rounded-md text-muted-foreground hover:text-foreground hover:bg-muted/30 transition-all duration-150',
+              canScrollRight ? 'opacity-100' : 'opacity-0 pointer-events-none',
+            )}
+            aria-label="Scroll tabs right"
+            aria-hidden={canScrollRight ? undefined : true}
+            tabIndex={canScrollRight ? 0 : -1}
+            onClick={() => handleArrowClick('right')}
+            onPointerDown={() => startHoldScroll('right')}
+            onPointerUp={stopHoldScroll}
+            onPointerLeave={cancelHoldScroll}
+            onPointerCancel={cancelHoldScroll}
+          >
+            <ChevronRight className="h-4 w-4" />
+          </button>
           )}
         </SortableContext>
 
diff --git a/test/unit/client/store/browserPreferencesPersistence.test.ts b/test/unit/client/store/browserPreferencesPersistence.test.ts
index 2590fff63..804e3af5f 100644
--- a/test/unit/client/store/browserPreferencesPersistence.test.ts
+++ b/test/unit/client/store/browserPreferencesPersistence.test.ts
@@ -64,26 +64,6 @@ describe('browserPreferencesPersistence', () => {
     })
   })
 
-  it('persists multirowTabs when enabled locally', () => {
-    const store = createStore()
-
-    store.dispatch(updateSettingsLocal({
-      panes: {
-        multirowTabs: true,
-      },
-    }))
-
-    vi.advanceTimersByTime(BROWSER_PREFERENCES_PERSIST_DEBOUNCE_MS)
-
-    expect(JSON.parse(localStorage.getItem(BROWSER_PREFERENCES_STORAGE_KEY) || '{}')).toEqual({
-      settings: {
-        panes: {
-          multirowTabs: true,
-        },
-      },
-    })
-  })
-
   it('debounces updateSettingsLocal writes and flushes them on pagehide', () => {
     const store = createStore()
 

From fc11d444e2ae13da6f4a2c860a1d23ec763c0772 Mon Sep 17 00:00:00 2001
From: Dan Shapiro <dan@example.com>
Date: Mon, 18 May 2026 04:30:40 -0700
Subject: [PATCH 3/3] fix: keep multi-row sidebar reopen slot compact

---
 src/components/TabBar.tsx                     | 28 ++++++++++++-------
 .../components/TabBar.multirow.test.tsx       |  9 +++---
 2 files changed, 22 insertions(+), 15 deletions(-)

diff --git a/src/components/TabBar.tsx b/src/components/TabBar.tsx
index 88278630a..61defeaa2 100644
--- a/src/components/TabBar.tsx
+++ b/src/components/TabBar.tsx
@@ -449,6 +449,24 @@ export default function TabBar({ sidebarCollapsed, onToggleSidebar }: TabBarProp
         className="pointer-events-none absolute inset-x-0 bottom-0 h-px bg-muted-foreground/45"
         aria-hidden="true"
       />
+      {sidebarCollapsed && onToggleSidebar && (
+        <div
+          className={cn(
+            "flex-shrink-0 w-10 flex items-end justify-center pb-1",
+            !multirowTabs && "h-full"
+          )}
+          data-testid="desktop-sidebar-reopen-slot"
+        >
+          <button
+            className="p-1 min-h-11 min-w-11 md:h-8 md:w-8 md:min-h-0 md:min-w-0 flex items-center justify-center rounded-md text-muted-foreground hover:text-foreground hover:bg-muted/30 transition-colors"
+            title="Show sidebar"
+            aria-label="Show sidebar"
+            onClick={onToggleSidebar}
+          >
+            <PanelLeft className="h-3.5 w-3.5" />
+          </button>
+        </div>
+      )}
       <DndContext
         sensors={sensors}
         collisionDetection={multirowTabs ? rectIntersection : closestCenter}
@@ -490,16 +508,6 @@ export default function TabBar({ sidebarCollapsed, onToggleSidebar }: TabBarProp
                 : "overflow-x-auto overflow-y-hidden scrollbar-none"
             )}
           >
-            {sidebarCollapsed && onToggleSidebar && (
-              <button
-                className="flex-shrink-0 mb-1 p-1 min-h-11 min-w-11 md:min-h-0 md:min-w-0 flex items-center justify-center rounded-md text-muted-foreground hover:text-foreground hover:bg-muted/30 transition-colors"
-                title="Show sidebar"
-                aria-label="Show sidebar"
-                onClick={onToggleSidebar}
-              >
-                <PanelLeft className="h-3.5 w-3.5" />
-              </button>
-            )}
             {tabs.map(renderSortableTab)}
           </div>
 
diff --git a/test/unit/client/components/TabBar.multirow.test.tsx b/test/unit/client/components/TabBar.multirow.test.tsx
index b69fc4270..ac0617655 100644
--- a/test/unit/client/components/TabBar.multirow.test.tsx
+++ b/test/unit/client/components/TabBar.multirow.test.tsx
@@ -224,7 +224,7 @@ describe('TabBar multirow tabs', () => {
     expect(flexWrap!.className).not.toContain('overflow-x-hidden')
   })
 
-  it('keeps the sidebar reopen control inside the wrapped tab strip in multirow mode', () => {
+  it('does not apply h-full to sidebar reopen slot in multirow mode', () => {
     const tab = createTab({ id: 'tab-1' })
     const store = createStore({ tabs: [tab], activeTabId: 'tab-1', multirowTabs: true })
     const { container } = renderWithStore(
@@ -232,9 +232,8 @@ describe('TabBar multirow tabs', () => {
       store,
     )
 
-    const tabStrip = container.querySelector('[data-testid="tab-strip"]')
-    const button = screen.getByRole('button', { name: 'Show sidebar' })
-    expect(tabStrip).not.toBeNull()
-    expect(tabStrip).toContainElement(button)
+    const slot = container.querySelector('[data-testid="desktop-sidebar-reopen-slot"]')
+    expect(slot).not.toBeNull()
+    expect(slot!.className).not.toContain('h-full')
   })
 })