From b80ebc59657cf417a7cbd21002efdee05b733da0 Mon Sep 17 00:00:00 2001
From: gaius-codius <maher@najemft.com>
Date: Wed, 18 Feb 2026 12:49:33 +0000
Subject: [PATCH 01/27] feat(web): add theme selector with Catpuccin as
 optional theme

Restore the original dark theme as default and offer Catpuccin Mocha
as an opt-in theme. Add a manual theme toggle in Settings > Display
with System, Light, Dark, and Catpuccin options. Theme persists via
localStorage and syncs across tabs.
---
 web/src/hooks/useTheme.ts         | 173 +++++++++++++++++++++---------
 web/src/index.css                 | 107 +++++++++++++++++-
 web/src/lib/locales/en.ts         |   5 +
 web/src/lib/locales/zh-CN.ts      |   5 +
 web/src/main.tsx                  |   2 +
 web/src/routes/settings/index.tsx |  71 +++++++++++-
 6 files changed, 306 insertions(+), 57 deletions(-)

diff --git a/web/src/hooks/useTheme.ts b/web/src/hooks/useTheme.ts
index 25457ca99..73c0b336e 100644
--- a/web/src/hooks/useTheme.ts
+++ b/web/src/hooks/useTheme.ts
@@ -1,28 +1,72 @@
-import { useSyncExternalStore } from 'react'
+import { useCallback, useEffect, useLayoutEffect, useState } from 'react'
 import { getTelegramWebApp } from './useTelegram'
 
-type ColorScheme = 'light' | 'dark'
+export type ThemePreference = 'system' | 'light' | 'dark' | 'catpuccin'
+type ResolvedTheme = 'light' | 'dark' | 'catpuccin'
 
-function getColorScheme(): ColorScheme {
+const STORAGE_KEY = 'hapi-theme'
+
+function isBrowser(): boolean {
+    return typeof window !== 'undefined' && typeof document !== 'undefined'
+}
+
+const useIsomorphicLayoutEffect = isBrowser() ? useLayoutEffect : useEffect
+
+function safeGetItem(key: string): string | null {
+    if (!isBrowser()) return null
+    try {
+        return localStorage.getItem(key)
+    } catch {
+        return null
+    }
+}
+
+function safeSetItem(key: string, value: string): void {
+    if (!isBrowser()) return
+    try {
+        localStorage.setItem(key, value)
+    } catch {
+        // Ignore storage errors
+    }
+}
+
+function safeRemoveItem(key: string): void {
+    if (!isBrowser()) return
+    try {
+        localStorage.removeItem(key)
+    } catch {
+        // Ignore storage errors
+    }
+}
+
+function parseThemePreference(raw: string | null): ThemePreference {
+    if (raw === 'light' || raw === 'dark' || raw === 'catpuccin') return raw
+    return 'system'
+}
+
+function getSystemColorScheme(): 'light' | 'dark' {
     const tg = getTelegramWebApp()
     if (tg?.colorScheme) {
         return tg.colorScheme === 'dark' ? 'dark' : 'light'
     }
-
-    // Fallback to system preference for browser environment
-    if (typeof window !== 'undefined' && window.matchMedia) {
+    if (isBrowser() && window.matchMedia) {
         return window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light'
     }
-
     return 'light'
 }
 
-function isIOS(): boolean {
-    return /iPad|iPhone|iPod/.test(navigator.userAgent)
+function resolveTheme(pref: ThemePreference): ResolvedTheme {
+    if (pref === 'system') return getSystemColorScheme()
+    return pref
+}
+
+function applyTheme(theme: ResolvedTheme): void {
+    if (!isBrowser()) return
+    document.documentElement.setAttribute('data-theme', theme)
 }
 
-function applyTheme(scheme: ColorScheme): void {
-    document.documentElement.setAttribute('data-theme', scheme)
+function isIOS(): boolean {
+    return /iPad|iPhone|iPod/.test(navigator.userAgent)
 }
 
 function applyPlatform(): void {
@@ -31,59 +75,84 @@ function applyPlatform(): void {
     }
 }
 
-// External store for theme state
-let currentScheme: ColorScheme = getColorScheme()
-const listeners = new Set<() => void>()
-
-// Apply theme immediately at module load (before React renders)
-applyTheme(currentScheme)
-
-function subscribe(callback: () => void): () => void {
-    listeners.add(callback)
-    return () => listeners.delete(callback)
+function getInitialPreference(): ThemePreference {
+    return parseThemePreference(safeGetItem(STORAGE_KEY))
 }
 
-function getSnapshot(): ColorScheme {
-    return currentScheme
+export function initializeTheme(): void {
+    applyPlatform()
+    applyTheme(resolveTheme(getInitialPreference()))
 }
 
-function updateScheme(): void {
-    const newScheme = getColorScheme()
-    if (newScheme !== currentScheme) {
-        currentScheme = newScheme
-        applyTheme(newScheme)
-        listeners.forEach((cb) => cb())
-    }
+export function getThemeOptions(): ReadonlyArray<{ value: ThemePreference; label: string }> {
+    return [
+        { value: 'system', label: 'system' },
+        { value: 'light', label: 'light' },
+        { value: 'dark', label: 'dark' },
+        { value: 'catpuccin', label: 'catpuccin' },
+    ]
 }
 
-// Track if theme listeners have been set up
-let listenersInitialized = false
+export function useTheme(): {
+    themePreference: ThemePreference
+    setThemePreference: (pref: ThemePreference) => void
+    isDark: boolean
+} {
+    const [themePreference, setThemePreferenceState] = useState<ThemePreference>(getInitialPreference)
 
-export function useTheme(): { colorScheme: ColorScheme; isDark: boolean } {
-    const colorScheme = useSyncExternalStore(subscribe, getSnapshot, getSnapshot)
+    const resolved = resolveTheme(themePreference)
 
-    return {
-        colorScheme,
-        isDark: colorScheme === 'dark',
-    }
-}
+    useIsomorphicLayoutEffect(() => {
+        applyTheme(resolved)
+    }, [resolved])
 
-// Call this once at app startup to ensure theme is applied and listeners attached
-export function initializeTheme(): void {
-    currentScheme = getColorScheme()
-    applyTheme(currentScheme)
+    // Listen for system color scheme changes (only matters when pref is 'system')
+    useEffect(() => {
+        if (themePreference !== 'system') return undefined
 
-    // Set up listeners only once (after SDK may have loaded)
-    if (!listenersInitialized) {
-        listenersInitialized = true
         const tg = getTelegramWebApp()
         if (tg?.onEvent) {
-            // Telegram theme changes
-            tg.onEvent('themeChanged', updateScheme)
-        } else if (typeof window !== 'undefined' && window.matchMedia) {
-            // Browser system preference changes
-            const mediaQuery = window.matchMedia('(prefers-color-scheme: dark)')
-            mediaQuery.addEventListener('change', updateScheme)
+            const handler = () => applyTheme(resolveTheme('system'))
+            tg.onEvent('themeChanged', handler)
+            return () => tg.offEvent?.('themeChanged', handler)
         }
+
+        if (isBrowser() && window.matchMedia) {
+            const mq = window.matchMedia('(prefers-color-scheme: dark)')
+            const handler = () => applyTheme(resolveTheme('system'))
+            mq.addEventListener('change', handler)
+            return () => mq.removeEventListener('change', handler)
+        }
+
+        return undefined
+    }, [themePreference])
+
+    // Cross-tab sync
+    useEffect(() => {
+        if (!isBrowser()) return
+
+        const onStorage = (event: StorageEvent) => {
+            if (event.key !== STORAGE_KEY) return
+            const next = parseThemePreference(event.newValue)
+            setThemePreferenceState(next)
+        }
+
+        window.addEventListener('storage', onStorage)
+        return () => window.removeEventListener('storage', onStorage)
+    }, [])
+
+    const setThemePreference = useCallback((pref: ThemePreference) => {
+        setThemePreferenceState(pref)
+        if (pref === 'system') {
+            safeRemoveItem(STORAGE_KEY)
+        } else {
+            safeSetItem(STORAGE_KEY, pref)
+        }
+    }, [])
+
+    return {
+        themePreference,
+        setThemePreference,
+        isDark: resolved !== 'light',
     }
 }
diff --git a/web/src/index.css b/web/src/index.css
index d74b031bd..76d1c50fb 100644
--- a/web/src/index.css
+++ b/web/src/index.css
@@ -11,6 +11,7 @@
     --app-banner-bg: var(--tg-theme-button-color, #111827);
     --app-banner-text: var(--tg-theme-button-text-color, #ffffff);
     --app-secondary-bg: var(--tg-theme-secondary-bg-color, #f3f4f6);
+    --app-selected-bg: rgba(59, 130, 246, 0.08);
 
     /* Theme-aware colors (light mode defaults) */
     --app-border: rgba(0, 0, 0, 0.1);
@@ -33,6 +34,9 @@
     --app-git-untracked-color: #8E8E93;
 
     /* Badge colors (light) */
+    --app-badge-info-bg: rgba(59, 130, 246, 0.15);
+    --app-badge-info-text: #1d4ed8;
+    --app-badge-info-border: rgba(59, 130, 246, 0.25);
     --app-badge-warning-bg: rgba(245, 158, 11, 0.2);
     --app-badge-warning-text: #b45309;
     --app-badge-warning-border: rgba(245, 158, 11, 0.3);
@@ -43,6 +47,22 @@
     --app-badge-error-text: #b91c1c;
     --app-badge-error-border: rgba(239, 68, 68, 0.3);
 
+    --app-perm-warning: #c2410c;
+
+    /* Agent flavor colors (light) */
+    --app-flavor-claude: #92400e;
+    --app-flavor-claude-bg: rgba(245, 158, 11, 0.12);
+    --app-flavor-claude-border: rgba(245, 158, 11, 0.25);
+    --app-flavor-codex: #065f46;
+    --app-flavor-codex-bg: rgba(16, 185, 129, 0.12);
+    --app-flavor-codex-border: rgba(16, 185, 129, 0.25);
+    --app-flavor-gemini: #1e40af;
+    --app-flavor-gemini-bg: rgba(59, 130, 246, 0.12);
+    --app-flavor-gemini-border: rgba(59, 130, 246, 0.25);
+    --app-flavor-opencode: #5b21b6;
+    --app-flavor-opencode-bg: rgba(139, 92, 246, 0.12);
+    --app-flavor-opencode-border: rgba(139, 92, 246, 0.25);
+
     --app-font-scale: 1;
 }
 
@@ -57,6 +77,7 @@
     --app-banner-bg: var(--tg-theme-button-color, #3A3A3C);
     --app-banner-text: var(--tg-theme-button-text-color, #ffffff);
     --app-secondary-bg: var(--tg-theme-secondary-bg-color, #2C2C2E);
+    --app-selected-bg: rgba(59, 130, 246, 0.08);
 
     --app-border: rgba(255, 255, 255, 0.1);
     --app-divider: rgba(255, 255, 255, 0.08);
@@ -78,6 +99,9 @@
     --app-git-untracked-color: #9ca3af;
 
     /* Badge colors (dark) */
+    --app-badge-info-bg: rgba(96, 165, 250, 0.2);
+    --app-badge-info-text: #60a5fa;
+    --app-badge-info-border: rgba(96, 165, 250, 0.3);
     --app-badge-warning-bg: rgba(251, 191, 36, 0.2);
     --app-badge-warning-text: #fbbf24;
     --app-badge-warning-border: rgba(251, 191, 36, 0.3);
@@ -87,6 +111,85 @@
     --app-badge-error-bg: rgba(248, 113, 113, 0.2);
     --app-badge-error-text: #fca5a5;
     --app-badge-error-border: rgba(248, 113, 113, 0.35);
+
+    --app-perm-warning: #fb923c;
+
+    /* Agent flavor colors (dark) */
+    --app-flavor-claude: #fbbf24;
+    --app-flavor-claude-bg: rgba(245, 158, 11, 0.12);
+    --app-flavor-claude-border: rgba(245, 158, 11, 0.25);
+    --app-flavor-codex: #34d399;
+    --app-flavor-codex-bg: rgba(16, 185, 129, 0.12);
+    --app-flavor-codex-border: rgba(16, 185, 129, 0.25);
+    --app-flavor-gemini: #60a5fa;
+    --app-flavor-gemini-bg: rgba(59, 130, 246, 0.12);
+    --app-flavor-gemini-border: rgba(59, 130, 246, 0.25);
+    --app-flavor-opencode: #a78bfa;
+    --app-flavor-opencode-bg: rgba(139, 92, 246, 0.12);
+    --app-flavor-opencode-border: rgba(139, 92, 246, 0.25);
+}
+
+[data-theme="catpuccin"] {
+    /* Primary colors — Catpuccin Mocha */
+    --app-bg: #1e1e2e;
+    --app-fg: #cdd6f4;
+    --app-hint: #6c7086;
+    --app-link: #cdd6f4;
+    --app-button: #cdd6f4;
+    --app-button-text: #1e1e2e;
+    --app-banner-bg: #313244;
+    --app-banner-text: #cdd6f4;
+    --app-secondary-bg: #313244;
+    --app-selected-bg: rgba(137, 180, 250, 0.06);
+
+    --app-border: rgba(255, 255, 255, 0.1);
+    --app-divider: rgba(255, 255, 255, 0.08);
+    --app-subtle-bg: rgba(255, 255, 255, 0.05);
+    --app-code-bg: #282c34;
+    --app-inline-code-bg: rgba(255, 255, 255, 0.1);
+
+    /* Diff colors (dark) */
+    --app-diff-added-bg: #0d2e1f;
+    --app-diff-added-text: #c9d1d9;
+    --app-diff-removed-bg: #3f1b23;
+    --app-diff-removed-text: #c9d1d9;
+
+    /* Git status colors */
+    --app-git-staged-color: #a6e3a1;
+    --app-git-unstaged-color: #fab387;
+    --app-git-deleted-color: #f38ba8;
+    --app-git-renamed-color: #89b4fa;
+    --app-git-untracked-color: #6c7086;
+
+    /* Badge colors — Catpuccin Mocha */
+    --app-badge-info-bg: rgba(137, 180, 250, 0.12);
+    --app-badge-info-text: #89b4fa;
+    --app-badge-info-border: rgba(137, 180, 250, 0.22);
+    --app-badge-warning-bg: rgba(250, 179, 135, 0.15);
+    --app-badge-warning-text: #fab387;
+    --app-badge-warning-border: rgba(250, 179, 135, 0.25);
+    --app-badge-success-bg: rgba(166, 227, 161, 0.15);
+    --app-badge-success-text: #a6e3a1;
+    --app-badge-success-border: rgba(166, 227, 161, 0.25);
+    --app-badge-error-bg: rgba(243, 139, 168, 0.15);
+    --app-badge-error-text: #f38ba8;
+    --app-badge-error-border: rgba(243, 139, 168, 0.25);
+
+    --app-perm-warning: #fab387;
+
+    /* Agent flavor colors — Catpuccin Mocha */
+    --app-flavor-claude: #fab387;
+    --app-flavor-claude-bg: rgba(250, 179, 135, 0.10);
+    --app-flavor-claude-border: rgba(250, 179, 135, 0.20);
+    --app-flavor-codex: #a6e3a1;
+    --app-flavor-codex-bg: rgba(166, 227, 161, 0.10);
+    --app-flavor-codex-border: rgba(166, 227, 161, 0.20);
+    --app-flavor-gemini: #74c7ec;
+    --app-flavor-gemini-bg: rgba(116, 199, 236, 0.10);
+    --app-flavor-gemini-border: rgba(116, 199, 236, 0.20);
+    --app-flavor-opencode: #cba6f7;
+    --app-flavor-opencode-bg: rgba(203, 166, 247, 0.10);
+    --app-flavor-opencode-border: rgba(203, 166, 247, 0.20);
 }
 
 html {
@@ -167,7 +270,9 @@ body {
 }
 
 html[data-theme="dark"] .shiki,
-html[data-theme="dark"] .shiki span {
+html[data-theme="dark"] .shiki span,
+html[data-theme="catpuccin"] .shiki,
+html[data-theme="catpuccin"] .shiki span {
     color: var(--shiki-dark) !important;
     font-style: var(--shiki-dark-font-style) !important;
     font-weight: var(--shiki-dark-font-weight) !important;
diff --git a/web/src/lib/locales/en.ts b/web/src/lib/locales/en.ts
index 832756124..be75d3ef8 100644
--- a/web/src/lib/locales/en.ts
+++ b/web/src/lib/locales/en.ts
@@ -241,6 +241,11 @@ export default {
   'settings.language.title': 'Language',
   'settings.language.label': 'Language',
   'settings.display.title': 'Display',
+  'settings.display.theme': 'Theme',
+  'settings.display.theme.system': 'System',
+  'settings.display.theme.light': 'Light',
+  'settings.display.theme.dark': 'Dark',
+  'settings.display.theme.catpuccin': 'Catpuccin',
   'settings.display.fontSize': 'Font Size',
   'settings.voice.title': 'Voice Assistant',
   'settings.voice.language': 'Voice Language',
diff --git a/web/src/lib/locales/zh-CN.ts b/web/src/lib/locales/zh-CN.ts
index 48c75d513..141a46d31 100644
--- a/web/src/lib/locales/zh-CN.ts
+++ b/web/src/lib/locales/zh-CN.ts
@@ -243,6 +243,11 @@ export default {
   'settings.language.title': '语言',
   'settings.language.label': '语言',
   'settings.display.title': '显示',
+  'settings.display.theme': '主题',
+  'settings.display.theme.system': '跟随系统',
+  'settings.display.theme.light': '浅色',
+  'settings.display.theme.dark': '深色',
+  'settings.display.theme.catpuccin': 'Catpuccin',
   'settings.display.fontSize': '字体大小',
   'settings.voice.title': '语音助手',
   'settings.voice.language': '语音语言',
diff --git a/web/src/main.tsx b/web/src/main.tsx
index b88697c06..3eba2a1f6 100644
--- a/web/src/main.tsx
+++ b/web/src/main.tsx
@@ -6,6 +6,7 @@ import { RouterProvider, createMemoryHistory } from '@tanstack/react-router'
 import './index.css'
 import { registerSW } from 'virtual:pwa-register'
 import { initializeFontScale } from '@/hooks/useFontScale'
+import { initializeTheme } from '@/hooks/useTheme'
 import { getTelegramWebApp, isTelegramEnvironment, loadTelegramSdk } from './hooks/useTelegram'
 import { queryClient } from './lib/query-client'
 import { createAppRouter } from './router'
@@ -34,6 +35,7 @@ function getInitialPath(): string {
 
 async function bootstrap() {
     initializeFontScale()
+    initializeTheme()
 
     // Only load Telegram SDK in Telegram environment (with 3s timeout)
     const isTelegram = isTelegramEnvironment()
diff --git a/web/src/routes/settings/index.tsx b/web/src/routes/settings/index.tsx
index 0396064e5..1403b90df 100644
--- a/web/src/routes/settings/index.tsx
+++ b/web/src/routes/settings/index.tsx
@@ -3,6 +3,7 @@ import { useTranslation, type Locale } from '@/lib/use-translation'
 import { useAppGoBack } from '@/hooks/useAppGoBack'
 import { getElevenLabsSupportedLanguages, getLanguageDisplayName, type Language } from '@/lib/languages'
 import { getFontScaleOptions, useFontScale, type FontScale } from '@/hooks/useFontScale'
+import { getThemeOptions, useTheme, type ThemePreference } from '@/hooks/useTheme'
 import { PROTOCOL_VERSION } from '@hapi/protocol'
 
 const locales: { value: Locale; nativeLabel: string }[] = [
@@ -73,20 +74,25 @@ export default function SettingsPage() {
     const { t, locale, setLocale } = useTranslation()
     const goBack = useAppGoBack()
     const [isOpen, setIsOpen] = useState(false)
+    const [isThemeOpen, setIsThemeOpen] = useState(false)
     const [isFontOpen, setIsFontOpen] = useState(false)
     const [isVoiceOpen, setIsVoiceOpen] = useState(false)
     const containerRef = useRef<HTMLDivElement>(null)
+    const themeContainerRef = useRef<HTMLDivElement>(null)
     const fontContainerRef = useRef<HTMLDivElement>(null)
     const voiceContainerRef = useRef<HTMLDivElement>(null)
     const { fontScale, setFontScale } = useFontScale()
+    const { themePreference, setThemePreference } = useTheme()
 
     // Voice language state - read from localStorage
     const [voiceLanguage, setVoiceLanguage] = useState<string | null>(() => {
         return localStorage.getItem('hapi-voice-lang')
     })
 
+    const themeOptions = getThemeOptions()
     const fontScaleOptions = getFontScaleOptions()
     const currentLocale = locales.find((loc) => loc.value === locale)
+    const currentThemeLabel = t(`settings.display.theme.${themePreference}`)
     const currentFontScaleLabel = fontScaleOptions.find((opt) => opt.value === fontScale)?.label ?? '100%'
     const currentVoiceLanguage = voiceLanguages.find((lang) => lang.code === voiceLanguage)
 
@@ -95,6 +101,11 @@ export default function SettingsPage() {
         setIsOpen(false)
     }
 
+    const handleThemeChange = (newTheme: ThemePreference) => {
+        setThemePreference(newTheme)
+        setIsThemeOpen(false)
+    }
+
     const handleFontScaleChange = (newScale: FontScale) => {
         setFontScale(newScale)
         setIsFontOpen(false)
@@ -112,12 +123,15 @@ export default function SettingsPage() {
 
     // Close dropdown when clicking outside
     useEffect(() => {
-        if (!isOpen && !isFontOpen && !isVoiceOpen) return
+        if (!isOpen && !isThemeOpen && !isFontOpen && !isVoiceOpen) return
 
         const handleClickOutside = (event: MouseEvent) => {
             if (isOpen && containerRef.current && !containerRef.current.contains(event.target as Node)) {
                 setIsOpen(false)
             }
+            if (isThemeOpen && themeContainerRef.current && !themeContainerRef.current.contains(event.target as Node)) {
+                setIsThemeOpen(false)
+            }
             if (isFontOpen && fontContainerRef.current && !fontContainerRef.current.contains(event.target as Node)) {
                 setIsFontOpen(false)
             }
@@ -128,15 +142,16 @@ export default function SettingsPage() {
 
         document.addEventListener('mousedown', handleClickOutside)
         return () => document.removeEventListener('mousedown', handleClickOutside)
-    }, [isOpen, isFontOpen, isVoiceOpen])
+    }, [isOpen, isThemeOpen, isFontOpen, isVoiceOpen])
 
     // Close on escape key
     useEffect(() => {
-        if (!isOpen && !isFontOpen && !isVoiceOpen) return
+        if (!isOpen && !isThemeOpen && !isFontOpen && !isVoiceOpen) return
 
         const handleEscape = (event: KeyboardEvent) => {
             if (event.key === 'Escape') {
                 setIsOpen(false)
+                setIsThemeOpen(false)
                 setIsFontOpen(false)
                 setIsVoiceOpen(false)
             }
@@ -144,7 +159,7 @@ export default function SettingsPage() {
 
         document.addEventListener('keydown', handleEscape)
         return () => document.removeEventListener('keydown', handleEscape)
-    }, [isOpen, isFontOpen, isVoiceOpen])
+    }, [isOpen, isThemeOpen, isFontOpen, isVoiceOpen])
 
     return (
         <div className="flex h-full flex-col">
@@ -223,6 +238,54 @@ export default function SettingsPage() {
                         <div className="px-3 py-2 text-xs font-semibold text-[var(--app-hint)] uppercase tracking-wide">
                             {t('settings.display.title')}
                         </div>
+                        <div ref={themeContainerRef} className="relative">
+                            <button
+                                type="button"
+                                onClick={() => setIsThemeOpen(!isThemeOpen)}
+                                className="flex w-full items-center justify-between px-3 py-3 text-left transition-colors hover:bg-[var(--app-subtle-bg)]"
+                                aria-expanded={isThemeOpen}
+                                aria-haspopup="listbox"
+                            >
+                                <span className="text-[var(--app-fg)]">{t('settings.display.theme')}</span>
+                                <span className="flex items-center gap-1 text-[var(--app-hint)]">
+                                    <span>{currentThemeLabel}</span>
+                                    <ChevronDownIcon className={`transition-transform ${isThemeOpen ? 'rotate-180' : ''}`} />
+                                </span>
+                            </button>
+
+                            {isThemeOpen && (
+                                <div
+                                    className="absolute right-3 top-full mt-1 min-w-[160px] rounded-lg border border-[var(--app-border)] bg-[var(--app-bg)] shadow-lg overflow-hidden z-50"
+                                    role="listbox"
+                                    aria-label={t('settings.display.theme')}
+                                >
+                                    {themeOptions.map((opt) => {
+                                        const isSelected = themePreference === opt.value
+                                        return (
+                                            <button
+                                                key={opt.value}
+                                                type="button"
+                                                role="option"
+                                                aria-selected={isSelected}
+                                                onClick={() => handleThemeChange(opt.value)}
+                                                className={`flex items-center justify-between w-full px-3 py-2 text-base text-left transition-colors ${
+                                                    isSelected
+                                                        ? 'text-[var(--app-link)] bg-[var(--app-subtle-bg)]'
+                                                        : 'text-[var(--app-fg)] hover:bg-[var(--app-subtle-bg)]'
+                                                }`}
+                                            >
+                                                <span>{t(`settings.display.theme.${opt.value}`)}</span>
+                                                {isSelected && (
+                                                    <span className="ml-2 text-[var(--app-link)]">
+                                                        <CheckIcon />
+                                                    </span>
+                                                )}
+                                            </button>
+                                        )
+                                    })}
+                                </div>
+                            )}
+                        </div>
                         <div ref={fontContainerRef} className="relative">
                             <button
                                 type="button"

From 67339d473b4b5785613d1acd521b164a616ae25b Mon Sep 17 00:00:00 2001
From: gaius-codius <maher@najemft.com>
Date: Wed, 18 Feb 2026 13:57:26 +0000
Subject: [PATCH 02/27] feat(web): add Gaius theme with Roman-inspired palette
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add Gaius Light (warm pearl) and Gaius Dark (deep slate) themes using
classical Roman pigments — cinnabar red, verdigris green, lapis blue,
and aureus gold — rendered in a modern contemporary style. Includes
auto-switching Gaius option that follows system preference.
---
 web/src/hooks/useTheme.ts    |  20 +++---
 web/src/index.css            | 132 ++++++++++++++++++++++++++++++++++-
 web/src/lib/locales/en.ts    |   3 +
 web/src/lib/locales/zh-CN.ts |   3 +
 4 files changed, 149 insertions(+), 9 deletions(-)

diff --git a/web/src/hooks/useTheme.ts b/web/src/hooks/useTheme.ts
index 73c0b336e..a129770c9 100644
--- a/web/src/hooks/useTheme.ts
+++ b/web/src/hooks/useTheme.ts
@@ -1,8 +1,8 @@
 import { useCallback, useEffect, useLayoutEffect, useState } from 'react'
 import { getTelegramWebApp } from './useTelegram'
 
-export type ThemePreference = 'system' | 'light' | 'dark' | 'catpuccin'
-type ResolvedTheme = 'light' | 'dark' | 'catpuccin'
+export type ThemePreference = 'system' | 'light' | 'dark' | 'catpuccin' | 'gaius' | 'gaius-light' | 'gaius-dark'
+type ResolvedTheme = 'light' | 'dark' | 'catpuccin' | 'gaius-light' | 'gaius-dark'
 
 const STORAGE_KEY = 'hapi-theme'
 
@@ -40,7 +40,7 @@ function safeRemoveItem(key: string): void {
 }
 
 function parseThemePreference(raw: string | null): ThemePreference {
-    if (raw === 'light' || raw === 'dark' || raw === 'catpuccin') return raw
+    if (raw === 'light' || raw === 'dark' || raw === 'catpuccin' || raw === 'gaius' || raw === 'gaius-light' || raw === 'gaius-dark') return raw
     return 'system'
 }
 
@@ -57,6 +57,7 @@ function getSystemColorScheme(): 'light' | 'dark' {
 
 function resolveTheme(pref: ThemePreference): ResolvedTheme {
     if (pref === 'system') return getSystemColorScheme()
+    if (pref === 'gaius') return getSystemColorScheme() === 'dark' ? 'gaius-dark' : 'gaius-light'
     return pref
 }
 
@@ -90,6 +91,9 @@ export function getThemeOptions(): ReadonlyArray<{ value: ThemePreference; label
         { value: 'light', label: 'light' },
         { value: 'dark', label: 'dark' },
         { value: 'catpuccin', label: 'catpuccin' },
+        { value: 'gaius', label: 'gaius' },
+        { value: 'gaius-light', label: 'gaius-light' },
+        { value: 'gaius-dark', label: 'gaius-dark' },
     ]
 }
 
@@ -106,20 +110,20 @@ export function useTheme(): {
         applyTheme(resolved)
     }, [resolved])
 
-    // Listen for system color scheme changes (only matters when pref is 'system')
+    // Listen for system color scheme changes (matters when pref is 'system' or 'gaius')
     useEffect(() => {
-        if (themePreference !== 'system') return undefined
+        if (themePreference !== 'system' && themePreference !== 'gaius') return undefined
 
         const tg = getTelegramWebApp()
         if (tg?.onEvent) {
-            const handler = () => applyTheme(resolveTheme('system'))
+            const handler = () => applyTheme(resolveTheme(themePreference))
             tg.onEvent('themeChanged', handler)
             return () => tg.offEvent?.('themeChanged', handler)
         }
 
         if (isBrowser() && window.matchMedia) {
             const mq = window.matchMedia('(prefers-color-scheme: dark)')
-            const handler = () => applyTheme(resolveTheme('system'))
+            const handler = () => applyTheme(resolveTheme(themePreference))
             mq.addEventListener('change', handler)
             return () => mq.removeEventListener('change', handler)
         }
@@ -153,6 +157,6 @@ export function useTheme(): {
     return {
         themePreference,
         setThemePreference,
-        isDark: resolved !== 'light',
+        isDark: resolved !== 'light' && resolved !== 'gaius-light',
     }
 }
diff --git a/web/src/index.css b/web/src/index.css
index 76d1c50fb..21ac74356 100644
--- a/web/src/index.css
+++ b/web/src/index.css
@@ -192,6 +192,134 @@
     --app-flavor-opencode-border: rgba(203, 166, 247, 0.20);
 }
 
+[data-theme="gaius-light"] {
+    /* Primary — warm pearl base */
+    --app-bg: #f8f5f2;
+    --app-fg: #2a2832;
+    --app-hint: #85808a;
+    --app-link: #b04440;
+    --app-button: #2a2832;
+    --app-button-text: #f8f5f2;
+    --app-banner-bg: #eceae6;
+    --app-banner-text: #2a2832;
+    --app-secondary-bg: #f0ede9;
+    --app-selected-bg: rgba(176, 68, 64, 0.06);
+
+    /* Overlays */
+    --app-border: rgba(42, 40, 50, 0.10);
+    --app-divider: rgba(42, 40, 50, 0.07);
+    --app-subtle-bg: rgba(42, 40, 50, 0.03);
+    --app-code-bg: #f0ede8;
+    --app-inline-code-bg: rgba(42, 40, 50, 0.05);
+
+    /* Diffs — verdigris added, cinnabar removed */
+    --app-diff-added-bg: #e4edd8;
+    --app-diff-added-text: #2a2832;
+    --app-diff-removed-bg: #f2dcd8;
+    --app-diff-removed-text: #2a2832;
+
+    /* Git status */
+    --app-git-staged-color: #3a7868;
+    --app-git-unstaged-color: #b07830;
+    --app-git-deleted-color: #b84440;
+    --app-git-renamed-color: #4068a0;
+    --app-git-untracked-color: #85808a;
+
+    /* Badges — lapis, gold, verdigris, cinnabar */
+    --app-badge-info-bg: rgba(64, 104, 160, 0.10);
+    --app-badge-info-text: #3a5888;
+    --app-badge-info-border: rgba(64, 104, 160, 0.20);
+    --app-badge-warning-bg: rgba(176, 120, 48, 0.12);
+    --app-badge-warning-text: #8a5820;
+    --app-badge-warning-border: rgba(176, 120, 48, 0.22);
+    --app-badge-success-bg: rgba(58, 120, 104, 0.10);
+    --app-badge-success-text: #2a6858;
+    --app-badge-success-border: rgba(58, 120, 104, 0.20);
+    --app-badge-error-bg: rgba(184, 68, 64, 0.10);
+    --app-badge-error-text: #983838;
+    --app-badge-error-border: rgba(184, 68, 64, 0.20);
+
+    --app-perm-warning: #b84430;
+
+    /* Agent flavors — cinnabar, verdigris, lapis, violet */
+    --app-flavor-claude: #a04038;
+    --app-flavor-claude-bg: rgba(160, 64, 56, 0.08);
+    --app-flavor-claude-border: rgba(160, 64, 56, 0.18);
+    --app-flavor-codex: #2a6858;
+    --app-flavor-codex-bg: rgba(42, 104, 88, 0.08);
+    --app-flavor-codex-border: rgba(42, 104, 88, 0.18);
+    --app-flavor-gemini: #3a5888;
+    --app-flavor-gemini-bg: rgba(58, 88, 136, 0.08);
+    --app-flavor-gemini-border: rgba(58, 88, 136, 0.18);
+    --app-flavor-opencode: #6a5090;
+    --app-flavor-opencode-bg: rgba(106, 80, 144, 0.08);
+    --app-flavor-opencode-border: rgba(106, 80, 144, 0.18);
+}
+
+[data-theme="gaius-dark"] {
+    /* Primary — deep slate base */
+    --app-bg: #1e1d22;
+    --app-fg: #e6e3de;
+    --app-hint: #88848e;
+    --app-link: #d06058;
+    --app-button: #e6e3de;
+    --app-button-text: #1e1d22;
+    --app-banner-bg: #2a2930;
+    --app-banner-text: #e6e3de;
+    --app-secondary-bg: #252428;
+    --app-selected-bg: rgba(208, 96, 88, 0.06);
+
+    /* Overlays */
+    --app-border: rgba(230, 227, 222, 0.08);
+    --app-divider: rgba(230, 227, 222, 0.06);
+    --app-subtle-bg: rgba(230, 227, 222, 0.04);
+    --app-code-bg: #252430;
+    --app-inline-code-bg: rgba(230, 227, 222, 0.07);
+
+    /* Diffs */
+    --app-diff-added-bg: rgba(80, 150, 130, 0.12);
+    --app-diff-added-text: #d8d5d0;
+    --app-diff-removed-bg: rgba(200, 80, 70, 0.12);
+    --app-diff-removed-text: #d8d5d0;
+
+    /* Git status */
+    --app-git-staged-color: #68b8a0;
+    --app-git-unstaged-color: #d0a060;
+    --app-git-deleted-color: #d87068;
+    --app-git-renamed-color: #6890c8;
+    --app-git-untracked-color: #88848e;
+
+    /* Badges */
+    --app-badge-info-bg: rgba(104, 144, 200, 0.12);
+    --app-badge-info-text: #6890c8;
+    --app-badge-info-border: rgba(104, 144, 200, 0.20);
+    --app-badge-warning-bg: rgba(208, 160, 96, 0.15);
+    --app-badge-warning-text: #d0a060;
+    --app-badge-warning-border: rgba(208, 160, 96, 0.25);
+    --app-badge-success-bg: rgba(104, 184, 160, 0.10);
+    --app-badge-success-text: #68b8a0;
+    --app-badge-success-border: rgba(104, 184, 160, 0.20);
+    --app-badge-error-bg: rgba(216, 112, 104, 0.12);
+    --app-badge-error-text: #d87068;
+    --app-badge-error-border: rgba(216, 112, 104, 0.22);
+
+    --app-perm-warning: #d08050;
+
+    /* Agent flavors */
+    --app-flavor-claude: #d08858;
+    --app-flavor-claude-bg: rgba(208, 136, 88, 0.10);
+    --app-flavor-claude-border: rgba(208, 136, 88, 0.20);
+    --app-flavor-codex: #68b8a0;
+    --app-flavor-codex-bg: rgba(104, 184, 160, 0.10);
+    --app-flavor-codex-border: rgba(104, 184, 160, 0.20);
+    --app-flavor-gemini: #6890c8;
+    --app-flavor-gemini-bg: rgba(104, 144, 200, 0.10);
+    --app-flavor-gemini-border: rgba(104, 144, 200, 0.20);
+    --app-flavor-opencode: #a088c0;
+    --app-flavor-opencode-bg: rgba(160, 136, 192, 0.10);
+    --app-flavor-opencode-border: rgba(160, 136, 192, 0.20);
+}
+
 html {
     font-size: calc(100% * var(--app-font-scale, 1));
 }
@@ -272,7 +400,9 @@ body {
 html[data-theme="dark"] .shiki,
 html[data-theme="dark"] .shiki span,
 html[data-theme="catpuccin"] .shiki,
-html[data-theme="catpuccin"] .shiki span {
+html[data-theme="catpuccin"] .shiki span,
+html[data-theme="gaius-dark"] .shiki,
+html[data-theme="gaius-dark"] .shiki span {
     color: var(--shiki-dark) !important;
     font-style: var(--shiki-dark-font-style) !important;
     font-weight: var(--shiki-dark-font-weight) !important;
diff --git a/web/src/lib/locales/en.ts b/web/src/lib/locales/en.ts
index be75d3ef8..e71b98d70 100644
--- a/web/src/lib/locales/en.ts
+++ b/web/src/lib/locales/en.ts
@@ -246,6 +246,9 @@ export default {
   'settings.display.theme.light': 'Light',
   'settings.display.theme.dark': 'Dark',
   'settings.display.theme.catpuccin': 'Catpuccin',
+  'settings.display.theme.gaius': 'Gaius',
+  'settings.display.theme.gaius-light': 'Gaius Light',
+  'settings.display.theme.gaius-dark': 'Gaius Dark',
   'settings.display.fontSize': 'Font Size',
   'settings.voice.title': 'Voice Assistant',
   'settings.voice.language': 'Voice Language',
diff --git a/web/src/lib/locales/zh-CN.ts b/web/src/lib/locales/zh-CN.ts
index 141a46d31..403fe7814 100644
--- a/web/src/lib/locales/zh-CN.ts
+++ b/web/src/lib/locales/zh-CN.ts
@@ -248,6 +248,9 @@ export default {
   'settings.display.theme.light': '浅色',
   'settings.display.theme.dark': '深色',
   'settings.display.theme.catpuccin': 'Catpuccin',
+  'settings.display.theme.gaius': 'Gaius',
+  'settings.display.theme.gaius-light': 'Gaius 浅色',
+  'settings.display.theme.gaius-dark': 'Gaius 深色',
   'settings.display.fontSize': '字体大小',
   'settings.voice.title': '语音助手',
   'settings.voice.language': '语音语言',

From 7087fbe05c80ae4a0de7587fa0ac358e1553c0bb Mon Sep 17 00:00:00 2001
From: gaius-codius <maher@najemft.com>
Date: Wed, 18 Feb 2026 14:24:19 +0000
Subject: [PATCH 03/27] fix(web): improve clipboard reliability and terminal
 paste fallback

---
 web/src/lib/clipboard.ts             |  64 +++++++++++++++-
 web/src/lib/locales/en.ts            |   4 +
 web/src/lib/locales/zh-CN.ts         |   4 +
 web/src/routes/sessions/terminal.tsx | 107 +++++++++++++++++++++++++++
 4 files changed, 175 insertions(+), 4 deletions(-)

diff --git a/web/src/lib/clipboard.ts b/web/src/lib/clipboard.ts
index 79dc74b73..38a29e87b 100644
--- a/web/src/lib/clipboard.ts
+++ b/web/src/lib/clipboard.ts
@@ -1,6 +1,62 @@
-export function safeCopyToClipboard(text: string): Promise<void> {
-    if (navigator.clipboard?.writeText) {
-        return navigator.clipboard.writeText(text)
+function copyWithExecCommand(text: string): boolean {
+    if (typeof document === 'undefined' || !document.body) {
+        return false
     }
-    return Promise.reject(new Error('Clipboard API not available'))
+
+    const textarea = document.createElement('textarea')
+    textarea.value = text
+    textarea.setAttribute('readonly', 'true')
+    textarea.style.position = 'fixed'
+    textarea.style.top = '0'
+    textarea.style.left = '0'
+    textarea.style.width = '1px'
+    textarea.style.height = '1px'
+    textarea.style.padding = '0'
+    textarea.style.border = '0'
+    textarea.style.opacity = '0'
+    textarea.style.pointerEvents = 'none'
+
+    const activeElement = document.activeElement instanceof HTMLElement ? document.activeElement : null
+    const selection = document.getSelection()
+    const previousRange = selection && selection.rangeCount > 0 ? selection.getRangeAt(0) : null
+
+    document.body.appendChild(textarea)
+    textarea.focus()
+    textarea.select()
+    textarea.setSelectionRange(0, textarea.value.length)
+
+    let copied = false
+    try {
+        copied = document.execCommand('copy')
+    } catch {
+        copied = false
+    } finally {
+        document.body.removeChild(textarea)
+        if (selection) {
+            selection.removeAllRanges()
+            if (previousRange) {
+                selection.addRange(previousRange)
+            }
+        }
+        activeElement?.focus()
+    }
+
+    return copied
+}
+
+export async function safeCopyToClipboard(text: string): Promise<void> {
+    if (typeof navigator !== 'undefined' && navigator.clipboard?.writeText) {
+        try {
+            await navigator.clipboard.writeText(text)
+            return
+        } catch {
+            // Fall through to legacy copy strategy.
+        }
+    }
+
+    if (copyWithExecCommand(text)) {
+        return
+    }
+
+    throw new Error('Copy to clipboard failed')
 }
diff --git a/web/src/lib/locales/en.ts b/web/src/lib/locales/en.ts
index 832756124..342ac5c45 100644
--- a/web/src/lib/locales/en.ts
+++ b/web/src/lib/locales/en.ts
@@ -88,6 +88,7 @@ export default {
   'button.close': 'Close',
   'button.dismiss': 'Dismiss',
   'button.copy': 'Copy',
+  'button.paste': 'Paste',
 
   // New session form
   'newSession.machine': 'Machine',
@@ -136,6 +137,9 @@ export default {
   'terminal.commandArgs': 'Command args',
   'terminal.stdout': 'Stdout',
   'terminal.stderr': 'Stderr',
+  'terminal.paste.fallbackTitle': 'Paste input',
+  'terminal.paste.fallbackDescription': 'Clipboard read is unavailable. Paste your text below.',
+  'terminal.paste.placeholder': 'Paste terminal input here…',
 
   // Code block
   'code.copy': 'Copy',
diff --git a/web/src/lib/locales/zh-CN.ts b/web/src/lib/locales/zh-CN.ts
index 48c75d513..33e5b1f38 100644
--- a/web/src/lib/locales/zh-CN.ts
+++ b/web/src/lib/locales/zh-CN.ts
@@ -90,6 +90,7 @@ export default {
   'button.close': '关闭',
   'button.dismiss': '忽略',
   'button.copy': '复制',
+  'button.paste': '粘贴',
 
   // New session form
   'newSession.machine': '机器',
@@ -138,6 +139,9 @@ export default {
   'terminal.commandArgs': '命令参数',
   'terminal.stdout': '标准输出',
   'terminal.stderr': '标准错误',
+  'terminal.paste.fallbackTitle': '粘贴输入',
+  'terminal.paste.fallbackDescription': '无法读取剪贴板，请在下方粘贴文本。',
+  'terminal.paste.placeholder': '在此粘贴终端输入…',
 
   // Code block
   'code.copy': '复制',
diff --git a/web/src/routes/sessions/terminal.tsx b/web/src/routes/sessions/terminal.tsx
index 5ccc9fe40..a5b2f0269 100644
--- a/web/src/routes/sessions/terminal.tsx
+++ b/web/src/routes/sessions/terminal.tsx
@@ -7,8 +7,17 @@ import { useAppGoBack } from '@/hooks/useAppGoBack'
 import { useSession } from '@/hooks/queries/useSession'
 import { useTerminalSocket } from '@/hooks/useTerminalSocket'
 import { useLongPress } from '@/hooks/useLongPress'
+import { useTranslation } from '@/lib/use-translation'
 import { TerminalView } from '@/components/Terminal/TerminalView'
 import { LoadingState } from '@/components/LoadingState'
+import { Button } from '@/components/ui/button'
+import {
+    Dialog,
+    DialogContent,
+    DialogDescription,
+    DialogHeader,
+    DialogTitle
+} from '@/components/ui/dialog'
 function BackIcon() {
     return (
         <svg
@@ -170,6 +179,7 @@ function QuickKeyButton(props: {
 }
 
 export default function TerminalPage() {
+    const { t } = useTranslation()
     const { sessionId } = useParams({ from: '/sessions/$sessionId/terminal' })
     const { api, token, baseUrl } = useAppContext()
     const goBack = useAppGoBack()
@@ -188,6 +198,8 @@ export default function TerminalPage() {
     const [exitInfo, setExitInfo] = useState<{ code: number | null; signal: string | null } | null>(null)
     const [ctrlActive, setCtrlActive] = useState(false)
     const [altActive, setAltActive] = useState(false)
+    const [pasteDialogOpen, setPasteDialogOpen] = useState(false)
+    const [manualPasteText, setManualPasteText] = useState('')
 
     const {
         state: terminalState,
@@ -312,6 +324,45 @@ export default function TerminalPage() {
     }, [terminalState.status])
 
     const quickInputDisabled = !session?.active || terminalState.status !== 'connected'
+    const writePlainInput = useCallback((text: string) => {
+        if (!text || quickInputDisabled) {
+            return false
+        }
+        write(text)
+        resetModifiers()
+        terminalRef.current?.focus()
+        return true
+    }, [quickInputDisabled, write, resetModifiers])
+
+    const handlePasteAction = useCallback(async () => {
+        if (quickInputDisabled) {
+            return
+        }
+        const readClipboard = navigator.clipboard?.readText
+        if (readClipboard) {
+            try {
+                const clipboardText = await readClipboard.call(navigator.clipboard)
+                if (writePlainInput(clipboardText)) {
+                    return
+                }
+            } catch {
+                // Fall through to manual paste modal.
+            }
+        }
+        setManualPasteText('')
+        setPasteDialogOpen(true)
+    }, [quickInputDisabled, writePlainInput])
+
+    const handleManualPasteSubmit = useCallback(() => {
+        if (!manualPasteText.trim()) {
+            return
+        }
+        if (writePlainInput(manualPasteText)) {
+            setPasteDialogOpen(false)
+            setManualPasteText('')
+        }
+    }, [manualPasteText, writePlainInput])
+
     const handleQuickInput = useCallback(
         (sequence: string) => {
             if (quickInputDisabled) {
@@ -406,6 +457,16 @@ export default function TerminalPage() {
             <div className="bg-[var(--app-bg)] border-t border-[var(--app-border)] pb-[env(safe-area-inset-bottom)]">
                 <div className="mx-auto w-full max-w-content px-3">
                     <div className="flex flex-col gap-2 py-2">
+                        <button
+                            type="button"
+                            onClick={() => {
+                                void handlePasteAction()
+                            }}
+                            disabled={quickInputDisabled}
+                            className="w-full rounded-md border border-[var(--app-border)] bg-[var(--app-secondary-bg)] px-3 py-2 text-sm font-medium text-[var(--app-fg)] transition-colors hover:bg-[var(--app-subtle-bg)] focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--app-button)] disabled:cursor-not-allowed disabled:opacity-50"
+                        >
+                            {t('button.paste')}
+                        </button>
                         {QUICK_INPUT_ROWS.map((row, rowIndex) => (
                             <div
                                 key={`terminal-quick-row-${rowIndex}`}
@@ -432,6 +493,52 @@ export default function TerminalPage() {
                     </div>
                 </div>
             </div>
+
+            <Dialog
+                open={pasteDialogOpen}
+                onOpenChange={(open) => {
+                    setPasteDialogOpen(open)
+                    if (!open) {
+                        setManualPasteText('')
+                    }
+                }}
+            >
+                <DialogContent className="max-w-md">
+                    <DialogHeader>
+                        <DialogTitle>{t('terminal.paste.fallbackTitle')}</DialogTitle>
+                        <DialogDescription>
+                            {t('terminal.paste.fallbackDescription')}
+                        </DialogDescription>
+                    </DialogHeader>
+                    <textarea
+                        value={manualPasteText}
+                        onChange={(event) => setManualPasteText(event.target.value)}
+                        placeholder={t('terminal.paste.placeholder')}
+                        className="mt-2 min-h-32 w-full resize-y rounded-md border border-[var(--app-border)] bg-[var(--app-bg)] p-2 text-sm focus:outline-none focus:ring-2 focus:ring-[var(--app-link)]"
+                        autoCapitalize="none"
+                        autoCorrect="off"
+                    />
+                    <div className="mt-3 flex justify-end gap-2">
+                        <Button
+                            type="button"
+                            variant="secondary"
+                            onClick={() => {
+                                setPasteDialogOpen(false)
+                                setManualPasteText('')
+                            }}
+                        >
+                            {t('button.cancel')}
+                        </Button>
+                        <Button
+                            type="button"
+                            onClick={handleManualPasteSubmit}
+                            disabled={!manualPasteText.trim()}
+                        >
+                            {t('button.paste')}
+                        </Button>
+                    </div>
+                </DialogContent>
+            </Dialog>
         </div>
     )
 }

From cb399fb47618f1cfb27ee63340ffc3b145dc40bb Mon Sep 17 00:00:00 2001
From: gaius-codius <maher@najemft.com>
Date: Wed, 18 Feb 2026 08:49:35 +0000
Subject: [PATCH 04/27] fix(web): skip paste fallback dialog when clipboard is
 empty

---
 web/src/routes/sessions/terminal.tsx | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/web/src/routes/sessions/terminal.tsx b/web/src/routes/sessions/terminal.tsx
index a5b2f0269..0aba34b6e 100644
--- a/web/src/routes/sessions/terminal.tsx
+++ b/web/src/routes/sessions/terminal.tsx
@@ -342,6 +342,9 @@ export default function TerminalPage() {
         if (readClipboard) {
             try {
                 const clipboardText = await readClipboard.call(navigator.clipboard)
+                if (!clipboardText) {
+                    return
+                }
                 if (writePlainInput(clipboardText)) {
                     return
                 }

From cf7a7c1c2b21bb13a3e16ba5848d41938a21bba9 Mon Sep 17 00:00:00 2001
From: gaius-codius <maher@najemft.com>
Date: Wed, 18 Feb 2026 14:24:40 +0000
Subject: [PATCH 05/27] fix(web): move file content copy action into file
 viewer

---
 web/src/routes/sessions/file.tsx | 39 +++++++++++++++++++++++++++-----
 1 file changed, 33 insertions(+), 6 deletions(-)

diff --git a/web/src/routes/sessions/file.tsx b/web/src/routes/sessions/file.tsx
index 179a29b14..dd3a96bb6 100644
--- a/web/src/routes/sessions/file.tsx
+++ b/web/src/routes/sessions/file.tsx
@@ -11,6 +11,8 @@ import { queryKeys } from '@/lib/query-keys'
 import { langAlias, useShikiHighlighter } from '@/lib/shiki'
 import { decodeBase64 } from '@/lib/utils'
 
+const MAX_COPYABLE_FILE_BYTES = 1_000_000
+
 function decodePath(value: string): string {
     if (!value) return ''
     const decoded = decodeBase64(value)
@@ -94,6 +96,10 @@ function resolveLanguage(path: string): string | undefined {
     return langAlias[ext] ?? ext
 }
 
+function getUtf8ByteLength(value: string): number {
+    return new TextEncoder().encode(value).length
+}
+
 function isBinaryContent(content: string): boolean {
     if (!content) return false
     if (content.includes('\0')) return true
@@ -112,7 +118,8 @@ function extractCommandError(result: GitCommandResponse | undefined): string | n
 
 export default function FilePage() {
     const { api } = useAppContext()
-    const { copied, copy } = useCopyToClipboard()
+    const { copied: pathCopied, copy: copyPath } = useCopyToClipboard()
+    const { copied: contentCopied, copy: copyContent } = useCopyToClipboard()
     const goBack = useAppGoBack()
     const { sessionId } = useParams({ from: '/sessions/$sessionId/file' })
     const search = useSearch({ from: '/sessions/$sessionId/file' })
@@ -160,6 +167,14 @@ export default function FilePage() {
 
     const language = useMemo(() => resolveLanguage(filePath), [filePath])
     const highlighted = useShikiHighlighter(decodedContent, language)
+    const contentSizeBytes = useMemo(
+        () => (decodedContent ? getUtf8ByteLength(decodedContent) : 0),
+        [decodedContent]
+    )
+    const canCopyContent = fileContentResult?.success === true
+        && !binaryFile
+        && decodedContent.length > 0
+        && contentSizeBytes <= MAX_COPYABLE_FILE_BYTES
 
     const [displayMode, setDisplayMode] = useState<'diff' | 'file'>('diff')
 
@@ -204,11 +219,11 @@ export default function FilePage() {
                     <span className="min-w-0 flex-1 truncate text-xs text-[var(--app-hint)]">{filePath}</span>
                     <button
                         type="button"
-                        onClick={() => copy(filePath)}
+                        onClick={() => copyPath(filePath)}
                         className="shrink-0 rounded p-1 text-[var(--app-hint)] hover:bg-[var(--app-subtle-bg)] hover:text-[var(--app-fg)] transition-colors"
                         title="Copy path"
                     >
-                        {copied ? <CheckIcon className="h-3.5 w-3.5" /> : <CopyIcon className="h-3.5 w-3.5" />}
+                        {pathCopied ? <CheckIcon className="h-3.5 w-3.5" /> : <CopyIcon className="h-3.5 w-3.5" />}
                     </button>
                 </div>
             </div>
@@ -257,9 +272,21 @@ export default function FilePage() {
                         <div className="text-sm text-[var(--app-hint)]">{diffError}</div>
                     ) : displayMode === 'file' ? (
                         decodedContent ? (
-                            <pre className="shiki overflow-auto rounded-md bg-[var(--app-code-bg)] p-3 text-xs font-mono">
-                                <code>{highlighted ?? decodedContent}</code>
-                            </pre>
+                            <div className="relative">
+                                {canCopyContent ? (
+                                    <button
+                                        type="button"
+                                        onClick={() => copyContent(decodedContent)}
+                                        className="absolute right-2 top-2 z-10 rounded p-1 text-[var(--app-hint)] hover:bg-[var(--app-subtle-bg)] hover:text-[var(--app-fg)] transition-colors"
+                                        title="Copy file content"
+                                    >
+                                        {contentCopied ? <CheckIcon className="h-3.5 w-3.5" /> : <CopyIcon className="h-3.5 w-3.5" />}
+                                    </button>
+                                ) : null}
+                                <pre className="shiki overflow-auto rounded-md bg-[var(--app-code-bg)] p-3 pr-8 text-xs font-mono">
+                                    <code>{highlighted ?? decodedContent}</code>
+                                </pre>
+                            </div>
                         ) : (
                             <div className="text-sm text-[var(--app-hint)]">File is empty.</div>
                         )

From 50501c39cefeb7d35bd3c39bbf78a1724bd2427a Mon Sep 17 00:00:00 2001
From: gaius-codius <maher@najemft.com>
Date: Wed, 18 Feb 2026 14:24:48 +0000
Subject: [PATCH 06/27] feat(web): group sessions by machine and directory in
 sidebar

---
 web/src/components/SessionList.tsx | 94 +++++++++++++++++++++---------
 web/src/router.tsx                 | 24 +++++++-
 2 files changed, 88 insertions(+), 30 deletions(-)

diff --git a/web/src/components/SessionList.tsx b/web/src/components/SessionList.tsx
index 69c71c37b..04c2adbfd 100644
--- a/web/src/components/SessionList.tsx
+++ b/web/src/components/SessionList.tsx
@@ -10,8 +10,10 @@ import { ConfirmDialog } from '@/components/ui/ConfirmDialog'
 import { useTranslation } from '@/lib/use-translation'
 
 type SessionGroup = {
+    key: string
     directory: string
     displayName: string
+    machineId: string | null
     sessions: SessionSummary[]
     latestUpdatedAt: number
     hasActiveSession: boolean
@@ -26,32 +28,46 @@ function getGroupDisplayName(directory: string): string {
 }
 
 function groupSessionsByDirectory(sessions: SessionSummary[]): SessionGroup[] {
-    const groups = new Map<string, SessionSummary[]>()
+    const groups = new Map<string, { directory: string; machineId: string | null; sessions: SessionSummary[] }>()
 
     sessions.forEach(session => {
         const path = session.metadata?.worktree?.basePath ?? session.metadata?.path ?? 'Other'
-        if (!groups.has(path)) {
-            groups.set(path, [])
+        const machineId = session.metadata?.machineId ?? null
+        const key = `${machineId ?? '__unknown__'}::${path}`
+        if (!groups.has(key)) {
+            groups.set(key, {
+                directory: path,
+                machineId,
+                sessions: []
+            })
         }
-        groups.get(path)!.push(session)
+        groups.get(key)!.sessions.push(session)
     })
 
     return Array.from(groups.entries())
-        .map(([directory, groupSessions]) => {
-            const sortedSessions = [...groupSessions].sort((a, b) => {
+        .map(([key, group]) => {
+            const sortedSessions = [...group.sessions].sort((a, b) => {
                 const rankA = a.active ? (a.pendingRequestsCount > 0 ? 0 : 1) : 2
                 const rankB = b.active ? (b.pendingRequestsCount > 0 ? 0 : 1) : 2
                 if (rankA !== rankB) return rankA - rankB
                 return b.updatedAt - a.updatedAt
             })
-            const latestUpdatedAt = groupSessions.reduce(
+            const latestUpdatedAt = group.sessions.reduce(
                 (max, s) => (s.updatedAt > max ? s.updatedAt : max),
                 -Infinity
             )
-            const hasActiveSession = groupSessions.some(s => s.active)
-            const displayName = getGroupDisplayName(directory)
+            const hasActiveSession = group.sessions.some(s => s.active)
+            const displayName = getGroupDisplayName(group.directory)
 
-            return { directory, displayName, sessions: sortedSessions, latestUpdatedAt, hasActiveSession }
+            return {
+                key,
+                directory: group.directory,
+                displayName,
+                machineId: group.machineId,
+                sessions: sortedSessions,
+                latestUpdatedAt,
+                hasActiveSession
+            }
         })
         .sort((a, b) => {
             if (a.hasActiveSession !== b.hasActiveSession) {
@@ -166,10 +182,11 @@ function SessionItem(props: {
     onSelect: (sessionId: string) => void
     showPath?: boolean
     api: ApiClient | null
+    machineLabel: string
     selected?: boolean
 }) {
     const { t } = useTranslation()
-    const { session: s, onSelect, showPath = true, api, selected = false } = props
+    const { session: s, onSelect, showPath = true, api, machineLabel, selected = false } = props
     const { haptic } = usePlatform()
     const [menuOpen, setMenuOpen] = useState(false)
     const [menuAnchorPoint, setMenuAnchorPoint] = useState<{ x: number; y: number }>({ x: 0, y: 0 })
@@ -253,6 +270,7 @@ function SessionItem(props: {
                     </div>
                 ) : null}
                 <div className="flex flex-wrap items-center gap-x-3 gap-y-1 text-xs text-[var(--app-hint)]">
+                    <span>{t('misc.machine')}: {machineLabel}</span>
                     <span className="inline-flex items-center gap-2">
                         <span className="flex h-4 w-4 items-center justify-center" aria-hidden="true">
                             ❖
@@ -319,10 +337,11 @@ export function SessionList(props: {
     isLoading: boolean
     renderHeader?: boolean
     api: ApiClient | null
+    machineLabelsById?: Record<string, string>
     selectedSessionId?: string | null
 }) {
     const { t } = useTranslation()
-    const { renderHeader = true, api, selectedSessionId } = props
+    const { renderHeader = true, api, selectedSessionId, machineLabelsById = {} } = props
     const groups = useMemo(
         () => groupSessionsByDirectory(props.sessions),
         [props.sessions]
@@ -330,16 +349,25 @@ export function SessionList(props: {
     const [collapseOverrides, setCollapseOverrides] = useState<Map<string, boolean>>(
         () => new Map()
     )
+    const resolveMachineLabel = (machineId: string | null): string => {
+        if (machineId && machineLabelsById[machineId]) {
+            return machineLabelsById[machineId]
+        }
+        if (machineId) {
+            return machineId.slice(0, 8)
+        }
+        return t('machine.unknown')
+    }
     const isGroupCollapsed = (group: SessionGroup): boolean => {
-        const override = collapseOverrides.get(group.directory)
+        const override = collapseOverrides.get(group.key)
         if (override !== undefined) return override
         return !group.hasActiveSession
     }
 
-    const toggleGroup = (directory: string, isCollapsed: boolean) => {
+    const toggleGroup = (groupKey: string, isCollapsed: boolean) => {
         setCollapseOverrides(prev => {
             const next = new Map(prev)
-            next.set(directory, !isCollapsed)
+            next.set(groupKey, !isCollapsed)
             return next
         })
     }
@@ -348,11 +376,11 @@ export function SessionList(props: {
         setCollapseOverrides(prev => {
             if (prev.size === 0) return prev
             const next = new Map(prev)
-            const knownGroups = new Set(groups.map(group => group.directory))
+            const knownGroups = new Set(groups.map(group => group.key))
             let changed = false
-            for (const directory of next.keys()) {
-                if (!knownGroups.has(directory)) {
-                    next.delete(directory)
+            for (const groupKey of next.keys()) {
+                if (!knownGroups.has(groupKey)) {
+                    next.delete(groupKey)
                     changed = true
                 }
             }
@@ -381,25 +409,34 @@ export function SessionList(props: {
             <div className="flex flex-col">
                 {groups.map((group) => {
                     const isCollapsed = isGroupCollapsed(group)
+                    const groupMachineLabel = resolveMachineLabel(group.machineId)
                     return (
-                        <div key={group.directory}>
+                        <div key={group.key}>
                             <button
                                 type="button"
-                                onClick={() => toggleGroup(group.directory, isCollapsed)}
-                                className="sticky top-0 z-10 flex w-full items-center gap-2 px-3 py-2 text-left bg-[var(--app-bg)] border-b border-[var(--app-divider)] transition-colors hover:bg-[var(--app-secondary-bg)]"
+                                onClick={() => toggleGroup(group.key, isCollapsed)}
+                                className="sticky top-0 z-10 flex w-full flex-col gap-1.5 px-3 py-2 text-left bg-[var(--app-secondary-bg)] border-b border-[var(--app-border)] transition-colors hover:bg-[var(--app-subtle-bg)]"
                             >
-                                <ChevronIcon
-                                    className="h-4 w-4 text-[var(--app-hint)]"
-                                    collapsed={isCollapsed}
-                                />
-                                <div className="flex items-center gap-2 min-w-0 flex-1">
-                                    <span className="font-medium text-base break-words" title={group.directory}>
+                                <div className="flex items-center gap-2 min-w-0 w-full">
+                                    <ChevronIcon
+                                        className="h-4 w-4 text-[var(--app-hint)]"
+                                        collapsed={isCollapsed}
+                                    />
+                                    <span className="font-semibold text-sm break-words" title={group.directory}>
                                         {group.displayName}
                                     </span>
                                     <span className="shrink-0 text-xs text-[var(--app-hint)]">
                                         ({group.sessions.length})
                                     </span>
                                 </div>
+                                <div className="flex min-w-0 w-full flex-wrap items-center gap-2 text-xs text-[var(--app-hint)]">
+                                    <span className="inline-flex items-center rounded border border-[var(--app-border)] bg-[var(--app-bg)] px-2 py-0.5">
+                                        {t('misc.machine')}: {groupMachineLabel}
+                                    </span>
+                                    <span className="truncate" title={group.directory}>
+                                        {group.directory}
+                                    </span>
+                                </div>
                             </button>
                             {!isCollapsed ? (
                                 <div className="flex flex-col divide-y divide-[var(--app-divider)] border-b border-[var(--app-divider)]">
@@ -410,6 +447,7 @@ export function SessionList(props: {
                                             onSelect={props.onSelect}
                                             showPath={false}
                                             api={api}
+                                            machineLabel={resolveMachineLabel(s.metadata?.machineId ?? null)}
                                             selected={s.id === selectedSessionId}
                                         />
                                     ))}
diff --git a/web/src/router.tsx b/web/src/router.tsx
index 0dd3ad155..3aec839f4 100644
--- a/web/src/router.tsx
+++ b/web/src/router.tsx
@@ -1,4 +1,4 @@
-import { useCallback } from 'react'
+import { useCallback, useMemo } from 'react'
 import { useQueryClient } from '@tanstack/react-query'
 import {
     Navigate,
@@ -30,6 +30,7 @@ import { queryKeys } from '@/lib/query-keys'
 import { useToast } from '@/lib/toast-context'
 import { useTranslation } from '@/lib/use-translation'
 import { fetchLatestMessages, seedMessageWindowFromSession } from '@/lib/message-window-store'
+import type { Machine } from '@/types/api'
 import FilesPage from '@/routes/sessions/files'
 import FilePage from '@/routes/sessions/file'
 import TerminalPage from '@/routes/sessions/terminal'
@@ -94,6 +95,12 @@ function SettingsIcon(props: { className?: string }) {
     )
 }
 
+function getMachineTitle(machine: Machine): string {
+    if (machine.metadata?.displayName) return machine.metadata.displayName
+    if (machine.metadata?.host) return machine.metadata.host
+    return machine.id.slice(0, 8)
+}
+
 function SessionsPage() {
     const { api } = useAppContext()
     const navigate = useNavigate()
@@ -101,12 +108,24 @@ function SessionsPage() {
     const matchRoute = useMatchRoute()
     const { t } = useTranslation()
     const { sessions, isLoading, error, refetch } = useSessions(api)
+    const { machines } = useMachines(api, true)
 
     const handleRefresh = useCallback(() => {
         void refetch()
     }, [refetch])
 
-    const projectCount = new Set(sessions.map(s => s.metadata?.worktree?.basePath ?? s.metadata?.path ?? 'Other')).size
+    const projectCount = new Set(sessions.map(s => {
+        const path = s.metadata?.worktree?.basePath ?? s.metadata?.path ?? 'Other'
+        const machineId = s.metadata?.machineId ?? '__unknown__'
+        return `${machineId}::${path}`
+    })).size
+    const machineLabelsById = useMemo(() => {
+        const labels: Record<string, string> = {}
+        for (const machine of machines) {
+            labels[machine.id] = getMachineTitle(machine)
+        }
+        return labels
+    }, [machines])
     const sessionMatch = matchRoute({ to: '/sessions/$sessionId', fuzzy: true })
     const selectedSessionId = sessionMatch && sessionMatch.sessionId !== 'new' ? sessionMatch.sessionId : null
     const isSessionsIndex = pathname === '/sessions' || pathname === '/sessions/'
@@ -160,6 +179,7 @@ function SessionsPage() {
                         isLoading={isLoading}
                         renderHeader={false}
                         api={api}
+                        machineLabelsById={machineLabelsById}
                     />
                 </div>
             </div>

From 65caf1277ff31e6d62b9da865a44f6b96de2177b Mon Sep 17 00:00:00 2001
From: gaius-codius <maher@najemft.com>
Date: Wed, 18 Feb 2026 14:24:48 +0000
Subject: [PATCH 07/27] fix(web): simplify session context labels in list

---
 web/src/components/SessionList.tsx | 7 ++-----
 1 file changed, 2 insertions(+), 5 deletions(-)

diff --git a/web/src/components/SessionList.tsx b/web/src/components/SessionList.tsx
index 04c2adbfd..4f101a6a9 100644
--- a/web/src/components/SessionList.tsx
+++ b/web/src/components/SessionList.tsx
@@ -182,11 +182,10 @@ function SessionItem(props: {
     onSelect: (sessionId: string) => void
     showPath?: boolean
     api: ApiClient | null
-    machineLabel: string
     selected?: boolean
 }) {
     const { t } = useTranslation()
-    const { session: s, onSelect, showPath = true, api, machineLabel, selected = false } = props
+    const { session: s, onSelect, showPath = true, api, selected = false } = props
     const { haptic } = usePlatform()
     const [menuOpen, setMenuOpen] = useState(false)
     const [menuAnchorPoint, setMenuAnchorPoint] = useState<{ x: number; y: number }>({ x: 0, y: 0 })
@@ -270,7 +269,6 @@ function SessionItem(props: {
                     </div>
                 ) : null}
                 <div className="flex flex-wrap items-center gap-x-3 gap-y-1 text-xs text-[var(--app-hint)]">
-                    <span>{t('misc.machine')}: {machineLabel}</span>
                     <span className="inline-flex items-center gap-2">
                         <span className="flex h-4 w-4 items-center justify-center" aria-hidden="true">
                             ❖
@@ -431,7 +429,7 @@ export function SessionList(props: {
                                 </div>
                                 <div className="flex min-w-0 w-full flex-wrap items-center gap-2 text-xs text-[var(--app-hint)]">
                                     <span className="inline-flex items-center rounded border border-[var(--app-border)] bg-[var(--app-bg)] px-2 py-0.5">
-                                        {t('misc.machine')}: {groupMachineLabel}
+                                        {groupMachineLabel}
                                     </span>
                                     <span className="truncate" title={group.directory}>
                                         {group.directory}
@@ -447,7 +445,6 @@ export function SessionList(props: {
                                             onSelect={props.onSelect}
                                             showPath={false}
                                             api={api}
-                                            machineLabel={resolveMachineLabel(s.metadata?.machineId ?? null)}
                                             selected={s.id === selectedSessionId}
                                         />
                                     ))}

From f93a4996dff2a53898340f53da09b3c6cdafe964 Mon Sep 17 00:00:00 2001
From: gaius-codius <maher@najemft.com>
Date: Wed, 18 Feb 2026 12:49:25 +0000
Subject: [PATCH 08/27] feat(web): improve session list badges and permission
 mode display

Add permissionMode to SessionSummary, show permission mode and flavor
badges in session header and list with theme-aware colors.
---
 shared/src/sessionSummary.ts         |  4 +-
 web/src/components/SessionHeader.tsx | 53 +++++++++++++---
 web/src/components/SessionList.tsx   | 94 +++++++++++++++++++++-------
 web/src/lib/agentFlavorUtils.ts      | 78 +++++++++++++++++++++++
 4 files changed, 197 insertions(+), 32 deletions(-)

diff --git a/shared/src/sessionSummary.ts b/shared/src/sessionSummary.ts
index 4b693ada7..fd5096dc6 100644
--- a/shared/src/sessionSummary.ts
+++ b/shared/src/sessionSummary.ts
@@ -1,4 +1,4 @@
-import type { ModelMode } from './modes'
+import type { ModelMode, PermissionMode } from './modes'
 import type { Session, WorktreeMetadata } from './schemas'
 
 export type SessionSummaryMetadata = {
@@ -19,6 +19,7 @@ export type SessionSummary = {
     metadata: SessionSummaryMetadata | null
     todoProgress: { completed: number; total: number } | null
     pendingRequestsCount: number
+    permissionMode?: PermissionMode
     modelMode?: ModelMode
 }
 
@@ -48,6 +49,7 @@ export function toSessionSummary(session: Session): SessionSummary {
         metadata,
         todoProgress,
         pendingRequestsCount,
+        permissionMode: session.permissionMode,
         modelMode: session.modelMode
     }
 }
diff --git a/web/src/components/SessionHeader.tsx b/web/src/components/SessionHeader.tsx
index 3728b2670..4fbb24828 100644
--- a/web/src/components/SessionHeader.tsx
+++ b/web/src/components/SessionHeader.tsx
@@ -1,12 +1,14 @@
 import { useId, useMemo, useRef, useState } from 'react'
 import type { Session } from '@/types/api'
 import type { ApiClient } from '@/api/client'
+import { getPermissionModeLabel, getPermissionModeTone, isPermissionModeAllowedForFlavor } from '@hapi/protocol'
 import { isTelegramApp } from '@/hooks/useTelegram'
 import { useSessionActions } from '@/hooks/mutations/useSessionActions'
 import { SessionActionMenu } from '@/components/SessionActionMenu'
 import { RenameSessionDialog } from '@/components/RenameSessionDialog'
 import { ConfirmDialog } from '@/components/ui/ConfirmDialog'
 import { useTranslation } from '@/lib/use-translation'
+import { getFlavorBadgeClass, PERMISSION_TONE_BADGE } from '@/lib/agentFlavorUtils'
 
 function getSessionTitle(session: Session): string {
     if (session.metadata?.name) {
@@ -128,21 +130,52 @@ export function SessionHeader(props: {
                         </svg>
                     </button>
 
-                    {/* Session info - two lines: title and path */}
+                    {/* Session info - two lines: title and badges */}
                     <div className="min-w-0 flex-1">
                         <div className="truncate font-semibold">
                             {title}
                         </div>
-                        <div className="flex flex-wrap items-center gap-x-3 gap-y-0.5 text-xs text-[var(--app-hint)]">
-                            <span className="inline-flex items-center gap-1">
-                                <span aria-hidden="true">❖</span>
-                                {session.metadata?.flavor?.trim() || 'unknown'}
-                            </span>
-                            <span>
-                                {t('session.item.modelMode')}: {session.modelMode || 'default'}
-                            </span>
+                        <div className="flex flex-wrap items-center gap-1.5 pt-1 text-xs">
+                            {(() => {
+                                const flavor = session.metadata?.flavor?.trim() ?? null
+                                const flavorBadge = getFlavorBadgeClass(flavor)
+                                const label = flavor || 'unknown'
+                                return (
+                                    <span className={`inline-flex items-center rounded-full border px-2 py-0.5 font-medium ${flavorBadge}`}>
+                                        {label}
+                                    </span>
+                                )
+                            })()}
+                            {(() => {
+                                const flavor = session.metadata?.flavor?.trim() ?? null
+                                const permMode = session.permissionMode
+                                    && session.permissionMode !== 'default'
+                                    && isPermissionModeAllowedForFlavor(session.permissionMode, flavor)
+                                    ? session.permissionMode
+                                    : null
+                                if (!permMode) return null
+                                const label = getPermissionModeLabel(permMode).toLowerCase()
+                                const tone = getPermissionModeTone(permMode)
+                                const badgeClass = PERMISSION_TONE_BADGE[tone]
+                                return (
+                                    <span className={`inline-flex items-center rounded-full border px-2 py-0.5 font-medium ${badgeClass}`}>
+                                        {label}
+                                    </span>
+                                )
+                            })()}
+                            {(() => {
+                                const flav = session.metadata?.flavor?.trim() ?? null
+                                if (flav && flav !== 'claude') return null
+                                return (
+                                    <span className="inline-flex items-center rounded-full border border-[var(--app-border)] bg-[var(--app-subtle-bg)] px-2 py-0.5 font-medium text-[var(--app-fg)]">
+                                        {session.modelMode || 'default'}
+                                    </span>
+                                )
+                            })()}
                             {worktreeBranch ? (
-                                <span>{t('session.item.worktree')}: {worktreeBranch}</span>
+                                <span className="inline-flex items-center rounded-full border border-[var(--app-border)] bg-[var(--app-subtle-bg)] px-2 py-0.5 text-[var(--app-hint)]">
+                                    {worktreeBranch}
+                                </span>
                             ) : null}
                         </div>
                     </div>
diff --git a/web/src/components/SessionList.tsx b/web/src/components/SessionList.tsx
index 4f101a6a9..115a34f75 100644
--- a/web/src/components/SessionList.tsx
+++ b/web/src/components/SessionList.tsx
@@ -1,6 +1,7 @@
 import { useEffect, useMemo, useState } from 'react'
 import type { SessionSummary } from '@/types/api'
 import type { ApiClient } from '@/api/client'
+import { getPermissionModeLabel, getPermissionModeTone, isPermissionModeAllowedForFlavor } from '@hapi/protocol'
 import { useLongPress } from '@/hooks/useLongPress'
 import { usePlatform } from '@/hooks/usePlatform'
 import { useSessionActions } from '@/hooks/mutations/useSessionActions'
@@ -8,6 +9,7 @@ import { SessionActionMenu } from '@/components/SessionActionMenu'
 import { RenameSessionDialog } from '@/components/RenameSessionDialog'
 import { ConfirmDialog } from '@/components/ui/ConfirmDialog'
 import { useTranslation } from '@/lib/use-translation'
+import { getFlavorTextClass, PERMISSION_TONE_TEXT } from '@/lib/agentFlavorUtils'
 
 type SessionGroup = {
     key: string
@@ -163,6 +165,27 @@ function getAgentLabel(session: SessionSummary): string {
     return 'unknown'
 }
 
+function MachineIcon(props: { className?: string }) {
+    return (
+        <svg
+            xmlns="http://www.w3.org/2000/svg"
+            width="14"
+            height="14"
+            viewBox="0 0 24 24"
+            fill="none"
+            stroke="currentColor"
+            strokeWidth="2"
+            strokeLinecap="round"
+            strokeLinejoin="round"
+            className={props.className}
+        >
+            <rect x="2" y="3" width="20" height="14" rx="2" />
+            <line x1="8" y1="21" x2="16" y2="21" />
+            <line x1="12" y1="17" x2="12" y2="21" />
+        </svg>
+    )
+}
+
 function formatRelativeTime(value: number, t: (key: string, params?: Record<string, string | number>) => string): string | null {
     const ms = value < 1_000_000_000_000 ? value * 1000 : value
     if (!Number.isFinite(ms)) return null
@@ -217,20 +240,33 @@ function SessionItem(props: {
     const statusDotClass = s.active
         ? (s.thinking ? 'bg-[#007AFF]' : 'bg-[var(--app-badge-success-text)]')
         : 'bg-[var(--app-hint)]'
+
+    const flavor = s.metadata?.flavor?.trim() ?? null
+    const flavorTextClass = getFlavorTextClass(flavor)
+
+    const permMode = s.permissionMode
+        && s.permissionMode !== 'default'
+        && isPermissionModeAllowedForFlavor(s.permissionMode, flavor)
+        ? s.permissionMode
+        : null
+    const permLabel = permMode ? getPermissionModeLabel(permMode).toLowerCase() : null
+    const permTone = permMode ? getPermissionModeTone(permMode) : null
+    const permTextClass = permTone ? PERMISSION_TONE_TEXT[permTone] : ''
+
     return (
         <>
             <button
                 type="button"
                 {...longPressHandlers}
-                className={`session-list-item flex w-full flex-col gap-1.5 px-3 py-3 text-left transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--app-link)] select-none ${selected ? 'bg-[var(--app-secondary-bg)]' : ''}`}
+                className={`session-list-item flex w-full flex-col gap-1.5 pl-5 pr-3 py-3 text-left transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--app-link)] select-none ${selected ? 'bg-[var(--app-selected-bg)]' : ''}`}
                 style={{ WebkitTouchCallout: 'none' }}
                 aria-current={selected ? 'page' : undefined}
             >
                 <div className="flex items-center justify-between gap-3">
                     <div className="flex items-center gap-2 min-w-0">
-                        <span className="flex h-4 w-4 items-center justify-center" aria-hidden="true">
+                        <span className="flex h-4 w-4 items-center justify-center shrink-0" aria-hidden="true">
                             <span
-                                className={`h-2 w-2 rounded-full ${statusDotClass}`}
+                                className={`h-2 w-2 rounded-full ${statusDotClass} ${s.thinking ? 'animate-pulse' : ''}`}
                             />
                         </span>
                         <div className="truncate text-base font-medium">
@@ -239,7 +275,7 @@ function SessionItem(props: {
                     </div>
                     <div className="flex items-center gap-2 shrink-0 text-xs">
                         {s.thinking ? (
-                            <span className="text-[#007AFF] animate-pulse">
+                            <span className="inline-flex items-center rounded-full bg-[rgba(0,122,255,0.12)] px-2 py-0.5 text-[#007AFF] animate-pulse font-medium">
                                 {t('session.item.thinking')}
                             </span>
                         ) : null}
@@ -254,7 +290,7 @@ function SessionItem(props: {
                             )
                         })()}
                         {s.pendingRequestsCount > 0 ? (
-                            <span className="text-[var(--app-badge-warning-text)]">
+                            <span className="inline-flex items-center rounded-full border border-[var(--app-badge-warning-border)] bg-[var(--app-badge-warning-bg)] px-2 py-0.5 font-medium text-[var(--app-badge-warning-text)]">
                                 {t('session.item.pending')} {s.pendingRequestsCount}
                             </span>
                         ) : null}
@@ -268,16 +304,31 @@ function SessionItem(props: {
                         {s.metadata?.path ?? s.id}
                     </div>
                 ) : null}
-                <div className="flex flex-wrap items-center gap-x-3 gap-y-1 text-xs text-[var(--app-hint)]">
-                    <span className="inline-flex items-center gap-2">
-                        <span className="flex h-4 w-4 items-center justify-center" aria-hidden="true">
-                            ❖
-                        </span>
+                <div className="flex flex-wrap items-center gap-1 text-xs">
+                    <span className={`font-medium ${flavorTextClass}`}>
                         {getAgentLabel(s)}
                     </span>
-                    <span>{t('session.item.modelMode')}: {s.modelMode || 'default'}</span>
+                    {permMode && permLabel ? (
+                        <>
+                            <span className="text-[var(--app-hint)]">&middot;</span>
+                            <span className={`font-medium ${permTextClass}`}>{permLabel}</span>
+                        </>
+                    ) : null}
+                    {flavor === 'claude' || !flavor ? (
+                        <>
+                            <span className="text-[var(--app-hint)]">&middot;</span>
+                            <span className="text-[var(--app-hint)]">
+                                {s.modelMode || 'default'}
+                            </span>
+                        </>
+                    ) : null}
                     {s.metadata?.worktree?.branch ? (
-                        <span>{t('session.item.worktree')}: {s.metadata.worktree.branch}</span>
+                        <>
+                            <span className="text-[var(--app-hint)]">&middot;</span>
+                            <span className="text-[var(--app-hint)]">
+                                {s.metadata.worktree.branch}
+                            </span>
+                        </>
                     ) : null}
                 </div>
             </button>
@@ -409,26 +460,27 @@ export function SessionList(props: {
                     const isCollapsed = isGroupCollapsed(group)
                     const groupMachineLabel = resolveMachineLabel(group.machineId)
                     return (
-                        <div key={group.key}>
+                        <div key={group.key} className="mt-2 first:mt-0">
                             <button
                                 type="button"
                                 onClick={() => toggleGroup(group.key, isCollapsed)}
-                                className="sticky top-0 z-10 flex w-full flex-col gap-1.5 px-3 py-2 text-left bg-[var(--app-secondary-bg)] border-b border-[var(--app-border)] transition-colors hover:bg-[var(--app-subtle-bg)]"
+                                className="sticky top-0 z-10 flex w-full flex-col gap-1 px-3 py-2.5 text-left bg-[var(--app-secondary-bg)] border-b border-[var(--app-border)] border-l-[3px] border-l-[var(--app-hint)] transition-colors hover:bg-[var(--app-subtle-bg)]"
                             >
                                 <div className="flex items-center gap-2 min-w-0 w-full">
                                     <ChevronIcon
-                                        className="h-4 w-4 text-[var(--app-hint)]"
+                                        className="h-4 w-4 text-[var(--app-hint)] shrink-0"
                                         collapsed={isCollapsed}
                                     />
-                                    <span className="font-semibold text-sm break-words" title={group.directory}>
+                                    <span className="font-semibold text-sm break-words min-w-0" title={group.directory}>
                                         {group.displayName}
                                     </span>
-                                    <span className="shrink-0 text-xs text-[var(--app-hint)]">
-                                        ({group.sessions.length})
+                                    <span className="shrink-0 rounded-full bg-[var(--app-subtle-bg)] px-1.5 py-0.5 text-[10px] font-medium text-[var(--app-hint)]">
+                                        {group.sessions.length}
                                     </span>
                                 </div>
-                                <div className="flex min-w-0 w-full flex-wrap items-center gap-2 text-xs text-[var(--app-hint)]">
-                                    <span className="inline-flex items-center rounded border border-[var(--app-border)] bg-[var(--app-bg)] px-2 py-0.5">
+                                <div className="flex min-w-0 w-full flex-wrap items-center gap-2 pl-6 text-xs text-[var(--app-hint)]">
+                                    <span className="inline-flex items-center gap-1 rounded border border-[var(--app-border)] bg-[var(--app-bg)] px-2 py-0.5">
+                                        <MachineIcon className="h-3 w-3 shrink-0" />
                                         {groupMachineLabel}
                                     </span>
                                     <span className="truncate" title={group.directory}>
@@ -437,7 +489,7 @@ export function SessionList(props: {
                                 </div>
                             </button>
                             {!isCollapsed ? (
-                                <div className="flex flex-col divide-y divide-[var(--app-divider)] border-b border-[var(--app-divider)]">
+                                <div className="flex flex-col divide-y divide-[var(--app-divider)] border-b border-[var(--app-divider)] border-l border-l-[var(--app-divider)]">
                                     {group.sessions.map((s) => (
                                         <SessionItem
                                             key={s.id}
diff --git a/web/src/lib/agentFlavorUtils.ts b/web/src/lib/agentFlavorUtils.ts
index d190e38c9..8827d4791 100644
--- a/web/src/lib/agentFlavorUtils.ts
+++ b/web/src/lib/agentFlavorUtils.ts
@@ -1,3 +1,19 @@
+import type { PermissionModeTone } from '@hapi/protocol'
+
+export const PERMISSION_TONE_BADGE: Record<PermissionModeTone, string> = {
+    neutral: 'text-[var(--app-fg)] bg-[var(--app-subtle-bg)] border-[var(--app-border)]',
+    info: 'text-[var(--app-badge-info-text)] bg-[var(--app-badge-info-bg)] border-[var(--app-badge-info-border)]',
+    warning: 'text-[var(--app-perm-warning)] bg-[var(--app-badge-warning-bg)] border-[var(--app-badge-warning-border)]',
+    danger: 'text-[var(--app-badge-error-text)] bg-[var(--app-badge-error-bg)] border-[var(--app-badge-error-border)]'
+}
+
+export const PERMISSION_TONE_TEXT: Record<PermissionModeTone, string> = {
+    neutral: 'text-[var(--app-fg)]',
+    info: 'text-[var(--app-badge-info-text)]',
+    warning: 'text-[var(--app-perm-warning)]',
+    danger: 'text-[var(--app-badge-error-text)]'
+}
+
 export function isCodexFamilyFlavor(flavor?: string | null): boolean {
     return flavor === 'codex' || flavor === 'gemini' || flavor === 'opencode'
 }
@@ -9,3 +25,65 @@ export function isClaudeFlavor(flavor?: string | null): boolean {
 export function isKnownFlavor(flavor?: string | null): boolean {
     return isClaudeFlavor(flavor) || isCodexFamilyFlavor(flavor)
 }
+
+type FlavorColors = {
+    text: string
+    bg: string
+    border: string
+}
+
+const FLAVOR_COLORS: Record<string, FlavorColors> = {
+    claude: {
+        text: 'text-[var(--app-flavor-claude)]',
+        bg: 'bg-[var(--app-flavor-claude-bg)]',
+        border: 'border-[var(--app-flavor-claude-border)]'
+    },
+    codex: {
+        text: 'text-[var(--app-flavor-codex)]',
+        bg: 'bg-[var(--app-flavor-codex-bg)]',
+        border: 'border-[var(--app-flavor-codex-border)]'
+    },
+    gemini: {
+        text: 'text-[var(--app-flavor-gemini)]',
+        bg: 'bg-[var(--app-flavor-gemini-bg)]',
+        border: 'border-[var(--app-flavor-gemini-border)]'
+    },
+    opencode: {
+        text: 'text-[var(--app-flavor-opencode)]',
+        bg: 'bg-[var(--app-flavor-opencode-bg)]',
+        border: 'border-[var(--app-flavor-opencode-border)]'
+    }
+}
+
+const DEFAULT_FLAVOR_COLORS: FlavorColors = {
+    text: 'text-[var(--app-hint)]',
+    bg: 'bg-[var(--app-subtle-bg)]',
+    border: 'border-[var(--app-border)]'
+}
+
+export function getFlavorColors(flavor?: string | null): FlavorColors {
+    const key = flavor?.trim()
+    if (key && FLAVOR_COLORS[key]) return FLAVOR_COLORS[key]
+    return DEFAULT_FLAVOR_COLORS
+}
+
+export function getFlavorBadgeClass(flavor?: string | null): string {
+    const colors = getFlavorColors(flavor)
+    return `${colors.text} ${colors.bg} ${colors.border}`
+}
+
+export function getFlavorTextClass(flavor?: string | null): string {
+    const colors = getFlavorColors(flavor)
+    return colors.text
+}
+
+export function getFlavorDotClass(flavor?: string | null): string {
+    const key = flavor?.trim()
+    switch (key) {
+        case 'claude': return 'bg-[var(--app-flavor-claude)]'
+        case 'codex': return 'bg-[var(--app-flavor-codex)]'
+        case 'gemini': return 'bg-[var(--app-flavor-gemini)]'
+        case 'opencode': return 'bg-[var(--app-flavor-opencode)]'
+        default: return 'bg-[var(--app-hint)]'
+    }
+}

From 7ec4cd751facf1de0eda674184537ead0ec8f324 Mon Sep 17 00:00:00 2001
From: gaius-codius <maher@najemft.com>
Date: Wed, 18 Feb 2026 15:04:38 +0000
Subject: [PATCH 09/27] fix(web): harden theme platform detection and theme
 label copy

---
 web/src/hooks/useTheme.ts    | 1 +
 web/src/lib/locales/en.ts    | 2 +-
 web/src/lib/locales/zh-CN.ts | 2 +-
 3 files changed, 3 insertions(+), 2 deletions(-)

diff --git a/web/src/hooks/useTheme.ts b/web/src/hooks/useTheme.ts
index a129770c9..e5fde3d8b 100644
--- a/web/src/hooks/useTheme.ts
+++ b/web/src/hooks/useTheme.ts
@@ -67,6 +67,7 @@ function applyTheme(theme: ResolvedTheme): void {
 }
 
 function isIOS(): boolean {
+    if (typeof navigator === 'undefined') return false
     return /iPad|iPhone|iPod/.test(navigator.userAgent)
 }
 
diff --git a/web/src/lib/locales/en.ts b/web/src/lib/locales/en.ts
index e71b98d70..5a865d918 100644
--- a/web/src/lib/locales/en.ts
+++ b/web/src/lib/locales/en.ts
@@ -245,7 +245,7 @@ export default {
   'settings.display.theme.system': 'System',
   'settings.display.theme.light': 'Light',
   'settings.display.theme.dark': 'Dark',
-  'settings.display.theme.catpuccin': 'Catpuccin',
+  'settings.display.theme.catpuccin': 'Catppuccin',
   'settings.display.theme.gaius': 'Gaius',
   'settings.display.theme.gaius-light': 'Gaius Light',
   'settings.display.theme.gaius-dark': 'Gaius Dark',
diff --git a/web/src/lib/locales/zh-CN.ts b/web/src/lib/locales/zh-CN.ts
index 403fe7814..c25b3e4bc 100644
--- a/web/src/lib/locales/zh-CN.ts
+++ b/web/src/lib/locales/zh-CN.ts
@@ -247,7 +247,7 @@ export default {
   'settings.display.theme.system': '跟随系统',
   'settings.display.theme.light': '浅色',
   'settings.display.theme.dark': '深色',
-  'settings.display.theme.catpuccin': 'Catpuccin',
+  'settings.display.theme.catpuccin': 'Catppuccin',
   'settings.display.theme.gaius': 'Gaius',
   'settings.display.theme.gaius-light': 'Gaius 浅色',
   'settings.display.theme.gaius-dark': 'Gaius 深色',

From afa34b2c33bcdb6ff9d7dc3476a27ab8485b4df5 Mon Sep 17 00:00:00 2001
From: gaius-codius <maher@najemft.com>
Date: Wed, 18 Feb 2026 15:05:34 +0000
Subject: [PATCH 10/27] refactor(web): simplify session badge rendering logic

---
 web/src/components/SessionHeader.tsx | 62 ++++++++++++----------------
 web/src/components/SessionList.tsx   | 17 ++++----
 2 files changed, 33 insertions(+), 46 deletions(-)

diff --git a/web/src/components/SessionHeader.tsx b/web/src/components/SessionHeader.tsx
index 4fbb24828..21b8f23a4 100644
--- a/web/src/components/SessionHeader.tsx
+++ b/web/src/components/SessionHeader.tsx
@@ -72,6 +72,19 @@ export function SessionHeader(props: {
     const { session, api, onSessionDeleted } = props
     const title = useMemo(() => getSessionTitle(session), [session])
     const worktreeBranch = session.metadata?.worktree?.branch
+    const flavor = session.metadata?.flavor?.trim() ?? null
+    const flavorLabel = flavor || 'unknown'
+    const flavorBadgeClass = getFlavorBadgeClass(flavor)
+    const permMode = session.permissionMode
+        && session.permissionMode !== 'default'
+        && isPermissionModeAllowedForFlavor(session.permissionMode, flavor)
+        ? session.permissionMode
+        : null
+    const permissionLabel = permMode ? getPermissionModeLabel(permMode).toLowerCase() : null
+    const permissionBadgeClass = permMode
+        ? PERMISSION_TONE_BADGE[getPermissionModeTone(permMode)]
+        : null
+    const showModelModeBadge = !flavor || flavor === 'claude'
 
     const [menuOpen, setMenuOpen] = useState(false)
     const [menuAnchorPoint, setMenuAnchorPoint] = useState<{ x: number; y: number }>({ x: 0, y: 0 })
@@ -136,42 +149,19 @@ export function SessionHeader(props: {
                             {title}
                         </div>
                         <div className="flex flex-wrap items-center gap-1.5 pt-1 text-xs">
-                            {(() => {
-                                const flavor = session.metadata?.flavor?.trim() ?? null
-                                const flavorBadge = getFlavorBadgeClass(flavor)
-                                const label = flavor || 'unknown'
-                                return (
-                                    <span className={`inline-flex items-center rounded-full border px-2 py-0.5 font-medium ${flavorBadge}`}>
-                                        {label}
-                                    </span>
-                                )
-                            })()}
-                            {(() => {
-                                const flavor = session.metadata?.flavor?.trim() ?? null
-                                const permMode = session.permissionMode
-                                    && session.permissionMode !== 'default'
-                                    && isPermissionModeAllowedForFlavor(session.permissionMode, flavor)
-                                    ? session.permissionMode
-                                    : null
-                                if (!permMode) return null
-                                const label = getPermissionModeLabel(permMode).toLowerCase()
-                                const tone = getPermissionModeTone(permMode)
-                                const badgeClass = PERMISSION_TONE_BADGE[tone]
-                                return (
-                                    <span className={`inline-flex items-center rounded-full border px-2 py-0.5 font-medium ${badgeClass}`}>
-                                        {label}
-                                    </span>
-                                )
-                            })()}
-                            {(() => {
-                                const flav = session.metadata?.flavor?.trim() ?? null
-                                if (flav && flav !== 'claude') return null
-                                return (
-                                    <span className="inline-flex items-center rounded-full border border-[var(--app-border)] bg-[var(--app-subtle-bg)] px-2 py-0.5 font-medium text-[var(--app-fg)]">
-                                        {session.modelMode || 'default'}
-                                    </span>
-                                )
-                            })()}
+                            <span className={`inline-flex items-center rounded-full border px-2 py-0.5 font-medium ${flavorBadgeClass}`}>
+                                {flavorLabel}
+                            </span>
+                            {permissionLabel && permissionBadgeClass ? (
+                                <span className={`inline-flex items-center rounded-full border px-2 py-0.5 font-medium ${permissionBadgeClass}`}>
+                                    {permissionLabel}
+                                </span>
+                            ) : null}
+                            {showModelModeBadge ? (
+                                <span className="inline-flex items-center rounded-full border border-[var(--app-border)] bg-[var(--app-subtle-bg)] px-2 py-0.5 font-medium text-[var(--app-fg)]">
+                                    {session.modelMode || 'default'}
+                                </span>
+                            ) : null}
                             {worktreeBranch ? (
                                 <span className="inline-flex items-center rounded-full border border-[var(--app-border)] bg-[var(--app-subtle-bg)] px-2 py-0.5 text-[var(--app-hint)]">
                                     {worktreeBranch}
diff --git a/web/src/components/SessionList.tsx b/web/src/components/SessionList.tsx
index 115a34f75..428e5d47b 100644
--- a/web/src/components/SessionList.tsx
+++ b/web/src/components/SessionList.tsx
@@ -252,6 +252,7 @@ function SessionItem(props: {
     const permLabel = permMode ? getPermissionModeLabel(permMode).toLowerCase() : null
     const permTone = permMode ? getPermissionModeTone(permMode) : null
     const permTextClass = permTone ? PERMISSION_TONE_TEXT[permTone] : ''
+    const todoProgress = getTodoProgress(s)
 
     return (
         <>
@@ -279,16 +280,12 @@ function SessionItem(props: {
                                 {t('session.item.thinking')}
                             </span>
                         ) : null}
-                        {(() => {
-                            const progress = getTodoProgress(s)
-                            if (!progress) return null
-                            return (
-                                <span className="flex items-center gap-1 text-[var(--app-hint)]">
-                                    <BulbIcon className="h-3 w-3" />
-                                    {progress.completed}/{progress.total}
-                                </span>
-                            )
-                        })()}
+                        {todoProgress ? (
+                            <span className="flex items-center gap-1 text-[var(--app-hint)]">
+                                <BulbIcon className="h-3 w-3" />
+                                {todoProgress.completed}/{todoProgress.total}
+                            </span>
+                        ) : null}
                         {s.pendingRequestsCount > 0 ? (
                             <span className="inline-flex items-center rounded-full border border-[var(--app-badge-warning-border)] bg-[var(--app-badge-warning-bg)] px-2 py-0.5 font-medium text-[var(--app-badge-warning-text)]">
                                 {t('session.item.pending')} {s.pendingRequestsCount}

From b3a31ad973d18d6a849ce1211e5910264f06591a Mon Sep 17 00:00:00 2001
From: gaius-codius <maher@najemft.com>
Date: Wed, 18 Feb 2026 21:51:51 +0000
Subject: [PATCH 11/27] test(web): cover theme preference resolution and
 persistence

---
 web/src/hooks/useTheme.test.ts | 103 +++++++++++++++++++++++++++++++++
 1 file changed, 103 insertions(+)
 create mode 100644 web/src/hooks/useTheme.test.ts

diff --git a/web/src/hooks/useTheme.test.ts b/web/src/hooks/useTheme.test.ts
new file mode 100644
index 000000000..478ef9671
--- /dev/null
+++ b/web/src/hooks/useTheme.test.ts
@@ -0,0 +1,103 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { act, renderHook } from '@testing-library/react'
+import { initializeTheme, useTheme } from './useTheme'
+
+vi.mock('./useTelegram', () => ({
+    getTelegramWebApp: vi.fn(() => null)
+}))
+
+function createMatchMediaStub(initialDark = false) {
+    const listeners = new Set<EventListenerOrEventListenerObject>()
+    const mediaQuery = {
+        media: '(prefers-color-scheme: dark)',
+        matches: initialDark,
+        onchange: null,
+        addEventListener: (_type: string, listener: EventListenerOrEventListenerObject) => {
+            listeners.add(listener)
+        },
+        removeEventListener: (_type: string, listener: EventListenerOrEventListenerObject) => {
+            listeners.delete(listener)
+        },
+        dispatchEvent: () => true,
+        addListener: () => {},
+        removeListener: () => {},
+    } as MediaQueryList
+
+    const setDark = (next: boolean) => {
+        ;(mediaQuery as { matches: boolean }).matches = next
+        const event = { matches: next } as MediaQueryListEvent
+        listeners.forEach((listener) => {
+            if (typeof listener === 'function') {
+                listener.call(mediaQuery, event)
+                return
+            }
+            listener.handleEvent(event)
+        })
+    }
+
+    return { mediaQuery, setDark }
+}
+
+describe('useTheme', () => {
+    beforeEach(() => {
+        localStorage.clear()
+        document.documentElement.removeAttribute('data-theme')
+    })
+
+    it('initializeTheme applies stored theme preference', () => {
+        const { mediaQuery } = createMatchMediaStub(false)
+        Object.defineProperty(window, 'matchMedia', {
+            writable: true,
+            value: vi.fn(() => mediaQuery)
+        })
+        localStorage.setItem('hapi-theme', 'catpuccin')
+
+        initializeTheme()
+
+        expect(document.documentElement.getAttribute('data-theme')).toBe('catpuccin')
+    })
+
+    it('initializeTheme resolves gaius against system scheme', () => {
+        const { mediaQuery } = createMatchMediaStub(true)
+        Object.defineProperty(window, 'matchMedia', {
+            writable: true,
+            value: vi.fn(() => mediaQuery)
+        })
+        localStorage.setItem('hapi-theme', 'gaius')
+
+        initializeTheme()
+
+        expect(document.documentElement.getAttribute('data-theme')).toBe('gaius-dark')
+    })
+
+    it('persists and clears theme preference from hook setter', () => {
+        const { mediaQuery } = createMatchMediaStub(false)
+        Object.defineProperty(window, 'matchMedia', {
+            writable: true,
+            value: vi.fn(() => mediaQuery)
+        })
+
+        const { result } = renderHook(() => useTheme())
+        act(() => result.current.setThemePreference('dark'))
+        expect(localStorage.getItem('hapi-theme')).toBe('dark')
+        expect(document.documentElement.getAttribute('data-theme')).toBe('dark')
+
+        act(() => result.current.setThemePreference('system'))
+        expect(localStorage.getItem('hapi-theme')).toBeNull()
+    })
+
+    it('updates resolved gaius theme when system preference changes', () => {
+        const { mediaQuery, setDark } = createMatchMediaStub(false)
+        Object.defineProperty(window, 'matchMedia', {
+            writable: true,
+            value: vi.fn(() => mediaQuery)
+        })
+        localStorage.setItem('hapi-theme', 'gaius')
+
+        renderHook(() => useTheme())
+        expect(document.documentElement.getAttribute('data-theme')).toBe('gaius-light')
+
+        act(() => setDark(true))
+        expect(document.documentElement.getAttribute('data-theme')).toBe('gaius-dark')
+    })
+})

From 55bcb88b30d5c29a34e1ee9019b1bb64b4dd3b33 Mon Sep 17 00:00:00 2001
From: gaius-codius <maher@najemft.com>
Date: Wed, 18 Feb 2026 21:53:46 +0000
Subject: [PATCH 12/27] test(web): add clipboard fallback and terminal paste
 coverage

---
 web/src/lib/clipboard.test.ts             |  56 ++++++++++++
 web/src/routes/sessions/terminal.test.tsx | 100 ++++++++++++++++++++++
 2 files changed, 156 insertions(+)
 create mode 100644 web/src/lib/clipboard.test.ts
 create mode 100644 web/src/routes/sessions/terminal.test.tsx

diff --git a/web/src/lib/clipboard.test.ts b/web/src/lib/clipboard.test.ts
new file mode 100644
index 000000000..2a28276c9
--- /dev/null
+++ b/web/src/lib/clipboard.test.ts
@@ -0,0 +1,56 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { safeCopyToClipboard } from './clipboard'
+
+describe('safeCopyToClipboard', () => {
+    beforeEach(() => {
+        vi.restoreAllMocks()
+        Object.defineProperty(document, 'execCommand', {
+            configurable: true,
+            writable: true,
+            value: vi.fn(() => false)
+        })
+    })
+
+    it('uses navigator clipboard writeText when available', async () => {
+        const writeText = vi.fn(async () => {})
+        Object.defineProperty(navigator, 'clipboard', {
+            configurable: true,
+            value: { writeText }
+        })
+        const execCommand = vi.mocked(document.execCommand)
+        execCommand.mockReturnValue(true)
+
+        await safeCopyToClipboard('hello')
+
+        expect(writeText).toHaveBeenCalledWith('hello')
+        expect(execCommand).not.toHaveBeenCalled()
+    })
+
+    it('falls back to execCommand when clipboard api write fails', async () => {
+        const writeText = vi.fn(async () => {
+            throw new Error('clipboard denied')
+        })
+        Object.defineProperty(navigator, 'clipboard', {
+            configurable: true,
+            value: { writeText }
+        })
+        const execCommand = vi.mocked(document.execCommand)
+        execCommand.mockReturnValue(true)
+
+        await safeCopyToClipboard('fallback')
+
+        expect(writeText).toHaveBeenCalledWith('fallback')
+        expect(execCommand).toHaveBeenCalledWith('copy')
+    })
+
+    it('throws when both modern and legacy copy strategies fail', async () => {
+        Object.defineProperty(navigator, 'clipboard', {
+            configurable: true,
+            value: undefined
+        })
+        const execCommand = vi.mocked(document.execCommand)
+        execCommand.mockReturnValue(false)
+
+        await expect(safeCopyToClipboard('x')).rejects.toThrow('Copy to clipboard failed')
+    })
+})
diff --git a/web/src/routes/sessions/terminal.test.tsx b/web/src/routes/sessions/terminal.test.tsx
new file mode 100644
index 000000000..2f294342e
--- /dev/null
+++ b/web/src/routes/sessions/terminal.test.tsx
@@ -0,0 +1,100 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { fireEvent, render, screen, waitFor } from '@testing-library/react'
+import { I18nProvider } from '@/lib/i18n-context'
+import TerminalPage from './terminal'
+
+const writeMock = vi.fn()
+
+vi.mock('@tanstack/react-router', () => ({
+    useParams: () => ({ sessionId: 'session-1' })
+}))
+
+vi.mock('@/lib/app-context', () => ({
+    useAppContext: () => ({
+        api: null,
+        token: 'test-token',
+        baseUrl: 'http://localhost:3000'
+    })
+}))
+
+vi.mock('@/hooks/useAppGoBack', () => ({
+    useAppGoBack: () => vi.fn()
+}))
+
+vi.mock('@/hooks/queries/useSession', () => ({
+    useSession: () => ({
+        session: {
+            id: 'session-1',
+            active: true,
+            metadata: { path: '/tmp/project' }
+        }
+    })
+}))
+
+vi.mock('@/hooks/useTerminalSocket', () => ({
+    useTerminalSocket: () => ({
+        state: { status: 'connected' as const },
+        connect: vi.fn(),
+        write: writeMock,
+        resize: vi.fn(),
+        disconnect: vi.fn(),
+        onOutput: vi.fn(),
+        onExit: vi.fn()
+    })
+}))
+
+vi.mock('@/hooks/useLongPress', () => ({
+    useLongPress: ({ onClick }: { onClick: () => void }) => ({
+        onClick
+    })
+}))
+
+vi.mock('@/components/Terminal/TerminalView', () => ({
+    TerminalView: () => <div data-testid="terminal-view" />
+}))
+
+function renderWithProviders() {
+    return render(
+        <I18nProvider>
+            <TerminalPage />
+        </I18nProvider>
+    )
+}
+
+describe('TerminalPage paste behavior', () => {
+    beforeEach(() => {
+        vi.clearAllMocks()
+    })
+
+    it('does not open manual paste dialog when clipboard text is empty', async () => {
+        const readText = vi.fn(async () => '')
+        Object.defineProperty(navigator, 'clipboard', {
+            configurable: true,
+            value: { readText }
+        })
+
+        renderWithProviders()
+        fireEvent.click(screen.getAllByRole('button', { name: 'Paste' })[0])
+
+        await waitFor(() => {
+            expect(readText).toHaveBeenCalledTimes(1)
+        })
+        expect(writeMock).not.toHaveBeenCalled()
+        expect(screen.queryByText('Paste input')).not.toBeInTheDocument()
+    })
+
+    it('opens manual paste dialog when clipboard read fails', async () => {
+        const readText = vi.fn(async () => {
+            throw new Error('blocked')
+        })
+        Object.defineProperty(navigator, 'clipboard', {
+            configurable: true,
+            value: { readText }
+        })
+
+        renderWithProviders()
+        fireEvent.click(screen.getAllByRole('button', { name: 'Paste' })[0])
+
+        expect(await screen.findByText('Paste input')).toBeInTheDocument()
+    })
+})

From 6d22b95bc33d03f6ef99d6a25ed345e75750c0bc Mon Sep 17 00:00:00 2001
From: gaius-codius <maher@najemft.com>
Date: Wed, 18 Feb 2026 21:55:08 +0000
Subject: [PATCH 13/27] test(web): verify machine grouping and permission-mode
 badges

---
 web/src/components/SessionList.test.tsx | 117 ++++++++++++++++++++++++
 1 file changed, 117 insertions(+)
 create mode 100644 web/src/components/SessionList.test.tsx

diff --git a/web/src/components/SessionList.test.tsx b/web/src/components/SessionList.test.tsx
new file mode 100644
index 000000000..6660eba92
--- /dev/null
+++ b/web/src/components/SessionList.test.tsx
@@ -0,0 +1,117 @@
+import { describe, expect, it, vi } from 'vitest'
+import { render, screen } from '@testing-library/react'
+import type { SessionSummary } from '@/types/api'
+import { I18nProvider } from '@/lib/i18n-context'
+import { SessionList } from './SessionList'
+
+vi.mock('@/hooks/useLongPress', () => ({
+    useLongPress: ({ onClick }: { onClick: () => void }) => ({ onClick })
+}))
+
+vi.mock('@/hooks/usePlatform', () => ({
+    usePlatform: () => ({ haptic: { impact: vi.fn() } })
+}))
+
+vi.mock('@/hooks/mutations/useSessionActions', () => ({
+    useSessionActions: () => ({
+        archiveSession: vi.fn(),
+        renameSession: vi.fn(),
+        deleteSession: vi.fn(),
+        isPending: false
+    })
+}))
+
+vi.mock('@/components/SessionActionMenu', () => ({
+    SessionActionMenu: () => null
+}))
+
+vi.mock('@/components/RenameSessionDialog', () => ({
+    RenameSessionDialog: () => null
+}))
+
+vi.mock('@/components/ui/ConfirmDialog', () => ({
+    ConfirmDialog: () => null
+}))
+
+function makeSession(overrides: Partial<SessionSummary>): SessionSummary {
+    const id = overrides.id ?? 'session-1'
+    return {
+        id,
+        active: overrides.active ?? true,
+        thinking: overrides.thinking ?? false,
+        activeAt: overrides.activeAt ?? 1,
+        updatedAt: overrides.updatedAt ?? 1,
+        metadata: overrides.metadata ?? {
+            name: id,
+            path: '/repo/app',
+            machineId: 'machine-1',
+            flavor: 'claude',
+            summary: { text: id }
+        },
+        todoProgress: overrides.todoProgress ?? null,
+        pendingRequestsCount: overrides.pendingRequestsCount ?? 0,
+        permissionMode: overrides.permissionMode,
+        modelMode: overrides.modelMode
+    }
+}
+
+function renderList(sessions: SessionSummary[], machineLabelsById?: Record<string, string>) {
+    return render(
+        <I18nProvider>
+            <SessionList
+                sessions={sessions}
+                onSelect={vi.fn()}
+                onNewSession={vi.fn()}
+                onRefresh={vi.fn()}
+                isLoading={false}
+                renderHeader={false}
+                api={null}
+                machineLabelsById={machineLabelsById}
+            />
+        </I18nProvider>
+    )
+}
+
+describe('SessionList', () => {
+    it('groups sessions by machine and directory', () => {
+        const sessions = [
+            makeSession({
+                id: 's1',
+                metadata: { path: '/repo/app', machineId: 'm1', flavor: 'claude' },
+                updatedAt: 100
+            }),
+            makeSession({
+                id: 's2',
+                metadata: { path: '/repo/app', machineId: 'm2', flavor: 'claude' },
+                updatedAt: 90
+            })
+        ]
+
+        renderList(sessions, { m1: 'Laptop', m2: 'Server' })
+
+        expect(screen.getByText('Laptop')).toBeInTheDocument()
+        expect(screen.getByText('Server')).toBeInTheDocument()
+    })
+
+    it('shows permission badge only when mode allowed for flavor', () => {
+        const sessions = [
+            makeSession({
+                id: 'claude-plan',
+                metadata: { path: '/repo/claude', machineId: 'm1', flavor: 'claude' },
+                permissionMode: 'plan'
+            }),
+            makeSession({
+                id: 'codex-plan',
+                metadata: { path: '/repo/codex', machineId: 'm1', flavor: 'codex' },
+                permissionMode: 'plan'
+            })
+        ]
+
+        renderList(sessions, { m1: 'Laptop' })
+
+        expect(screen.getByText('plan mode')).toBeInTheDocument()
+        const codexRow = screen.getAllByText('codex')[0]?.closest('button')
+        expect(codexRow).toBeTruthy()
+        expect(codexRow?.textContent?.toLowerCase()).not.toContain('plan mode')
+    })
+})

From 8423d823063479595d8fbc061956c2de4a0d46f0 Mon Sep 17 00:00:00 2001
From: gaius-codius <maher@najemft.com>
Date: Wed, 18 Feb 2026 23:50:50 +0000
Subject: [PATCH 14/27] fix(web): keep theme reactivity active outside settings
 page

---
 web/src/App.tsx                |   3 +-
 web/src/hooks/useTheme.test.ts |  36 +++++++++
 web/src/hooks/useTheme.ts      | 136 +++++++++++++++++++++++----------
 3 files changed, 133 insertions(+), 42 deletions(-)

diff --git a/web/src/App.tsx b/web/src/App.tsx
index 1a038f6cb..3d4984056 100644
--- a/web/src/App.tsx
+++ b/web/src/App.tsx
@@ -2,7 +2,7 @@ import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
 import { Outlet, useLocation, useMatchRoute, useRouter } from '@tanstack/react-router'
 import { useQueryClient } from '@tanstack/react-query'
 import { getTelegramWebApp, isTelegramApp } from '@/hooks/useTelegram'
-import { initializeTheme } from '@/hooks/useTheme'
+import { initializeTheme, useTheme } from '@/hooks/useTheme'
 import { useAuth } from '@/hooks/useAuth'
 import { useAuthSource } from '@/hooks/useAuthSource'
 import { useServerUrl } from '@/hooks/useServerUrl'
@@ -41,6 +41,7 @@ export function App() {
 }
 
 function AppInner() {
+    useTheme()
     const { t } = useTranslation()
     const { serverUrl, baseUrl, setServerUrl, clearServerUrl } = useServerUrl()
     const { authSource, isLoading: isAuthSourceLoading, setAccessToken } = useAuthSource(baseUrl)
diff --git a/web/src/hooks/useTheme.test.ts b/web/src/hooks/useTheme.test.ts
index 478ef9671..b4025491d 100644
--- a/web/src/hooks/useTheme.test.ts
+++ b/web/src/hooks/useTheme.test.ts
@@ -42,6 +42,11 @@ describe('useTheme', () => {
     beforeEach(() => {
         localStorage.clear()
         document.documentElement.removeAttribute('data-theme')
+        const { mediaQuery } = createMatchMediaStub(false)
+        Object.defineProperty(window, 'matchMedia', {
+            writable: true,
+            value: vi.fn(() => mediaQuery)
+        })
     })
 
     it('initializeTheme applies stored theme preference', () => {
@@ -70,6 +75,21 @@ describe('useTheme', () => {
         expect(document.documentElement.getAttribute('data-theme')).toBe('gaius-dark')
     })
 
+    it('initializeTheme keeps system theme reactive without mounted hook', () => {
+        const { mediaQuery, setDark } = createMatchMediaStub(false)
+        Object.defineProperty(window, 'matchMedia', {
+            writable: true,
+            value: vi.fn(() => mediaQuery)
+        })
+        localStorage.removeItem('hapi-theme')
+
+        initializeTheme()
+        expect(document.documentElement.getAttribute('data-theme')).toBe('light')
+
+        act(() => setDark(true))
+        expect(document.documentElement.getAttribute('data-theme')).toBe('dark')
+    })
+
     it('persists and clears theme preference from hook setter', () => {
         const { mediaQuery } = createMatchMediaStub(false)
         Object.defineProperty(window, 'matchMedia', {
@@ -94,10 +114,26 @@ describe('useTheme', () => {
         })
         localStorage.setItem('hapi-theme', 'gaius')
 
+        initializeTheme()
         renderHook(() => useTheme())
         expect(document.documentElement.getAttribute('data-theme')).toBe('gaius-light')
 
         act(() => setDark(true))
         expect(document.documentElement.getAttribute('data-theme')).toBe('gaius-dark')
     })
+
+    it('shares theme preference state across hook consumers', () => {
+        const { mediaQuery } = createMatchMediaStub(false)
+        Object.defineProperty(window, 'matchMedia', {
+            writable: true,
+            value: vi.fn(() => mediaQuery)
+        })
+        initializeTheme()
+
+        const first = renderHook(() => useTheme())
+        const second = renderHook(() => useTheme())
+
+        act(() => first.result.current.setThemePreference('dark'))
+        expect(second.result.current.themePreference).toBe('dark')
+    })
 })
diff --git a/web/src/hooks/useTheme.ts b/web/src/hooks/useTheme.ts
index e5fde3d8b..0f3c4a873 100644
--- a/web/src/hooks/useTheme.ts
+++ b/web/src/hooks/useTheme.ts
@@ -1,4 +1,4 @@
-import { useCallback, useEffect, useLayoutEffect, useState } from 'react'
+import { useCallback, useEffect, useLayoutEffect, useSyncExternalStore } from 'react'
 import { getTelegramWebApp } from './useTelegram'
 
 export type ThemePreference = 'system' | 'light' | 'dark' | 'catpuccin' | 'gaius' | 'gaius-light' | 'gaius-dark'
@@ -81,9 +81,90 @@ function getInitialPreference(): ThemePreference {
     return parseThemePreference(safeGetItem(STORAGE_KEY))
 }
 
+function isSystemLinkedPreference(pref: ThemePreference): boolean {
+    return pref === 'system' || pref === 'gaius'
+}
+
+let themePreferenceState: ThemePreference = getInitialPreference()
+const themeSubscribers = new Set<() => void>()
+let storageSyncInitialized = false
+let mediaQueryListenerInitialized = false
+let telegramThemeListenerInitialized = false
+let mediaQueryList: MediaQueryList | null = null
+
+function notifyThemeSubscribers(): void {
+    themeSubscribers.forEach((subscriber) => subscriber())
+}
+
+function applyThemePreference(pref: ThemePreference): void {
+    themePreferenceState = pref
+    applyTheme(resolveTheme(pref))
+}
+
+function persistThemePreference(pref: ThemePreference): void {
+    if (pref === 'system') {
+        safeRemoveItem(STORAGE_KEY)
+        return
+    }
+    safeSetItem(STORAGE_KEY, pref)
+}
+
+function setThemePreferenceState(pref: ThemePreference, options?: { persist?: boolean }): void {
+    const previous = themePreferenceState
+    applyThemePreference(pref)
+    if (options?.persist !== false) {
+        persistThemePreference(pref)
+    }
+    if (previous !== pref) {
+        notifyThemeSubscribers()
+    }
+}
+
+function onSystemThemeChanged(): void {
+    if (!isSystemLinkedPreference(themePreferenceState)) {
+        return
+    }
+    applyTheme(resolveTheme(themePreferenceState))
+    notifyThemeSubscribers()
+}
+
+function ensureThemeListeners(): void {
+    if (!isBrowser()) return
+
+    if (!storageSyncInitialized) {
+        const onStorage = (event: StorageEvent) => {
+            if (event.key !== STORAGE_KEY) return
+            const next = parseThemePreference(event.newValue)
+            setThemePreferenceState(next, { persist: false })
+        }
+        window.addEventListener('storage', onStorage)
+        storageSyncInitialized = true
+    }
+
+    if (window.matchMedia) {
+        const nextMediaQuery = window.matchMedia('(prefers-color-scheme: dark)')
+        if (!mediaQueryListenerInitialized || mediaQueryList !== nextMediaQuery) {
+            mediaQueryList?.removeEventListener('change', onSystemThemeChanged)
+            nextMediaQuery.addEventListener('change', onSystemThemeChanged)
+            mediaQueryList = nextMediaQuery
+            mediaQueryListenerInitialized = true
+        }
+    }
+
+    if (!telegramThemeListenerInitialized) {
+        const tg = getTelegramWebApp()
+        if (tg?.onEvent) {
+            tg.onEvent('themeChanged', onSystemThemeChanged)
+            telegramThemeListenerInitialized = true
+        }
+    }
+}
+
 export function initializeTheme(): void {
+    themePreferenceState = getInitialPreference()
     applyPlatform()
-    applyTheme(resolveTheme(getInitialPreference()))
+    applyTheme(resolveTheme(themePreferenceState))
+    ensureThemeListeners()
 }
 
 export function getThemeOptions(): ReadonlyArray<{ value: ThemePreference; label: string }> {
@@ -103,56 +184,29 @@ export function useTheme(): {
     setThemePreference: (pref: ThemePreference) => void
     isDark: boolean
 } {
-    const [themePreference, setThemePreferenceState] = useState<ThemePreference>(getInitialPreference)
-
+    const themePreference = useSyncExternalStore(
+        (subscriber) => {
+            ensureThemeListeners()
+            themeSubscribers.add(subscriber)
+            return () => {
+                themeSubscribers.delete(subscriber)
+            }
+        },
+        () => themePreferenceState,
+        () => themePreferenceState
+    )
     const resolved = resolveTheme(themePreference)
 
     useIsomorphicLayoutEffect(() => {
         applyTheme(resolved)
     }, [resolved])
 
-    // Listen for system color scheme changes (matters when pref is 'system' or 'gaius')
-    useEffect(() => {
-        if (themePreference !== 'system' && themePreference !== 'gaius') return undefined
-
-        const tg = getTelegramWebApp()
-        if (tg?.onEvent) {
-            const handler = () => applyTheme(resolveTheme(themePreference))
-            tg.onEvent('themeChanged', handler)
-            return () => tg.offEvent?.('themeChanged', handler)
-        }
-
-        if (isBrowser() && window.matchMedia) {
-            const mq = window.matchMedia('(prefers-color-scheme: dark)')
-            const handler = () => applyTheme(resolveTheme(themePreference))
-            mq.addEventListener('change', handler)
-            return () => mq.removeEventListener('change', handler)
-        }
-
-        return undefined
-    }, [themePreference])
-
-    // Cross-tab sync
     useEffect(() => {
-        if (!isBrowser()) return
-
-        const onStorage = (event: StorageEvent) => {
-            if (event.key !== STORAGE_KEY) return
-            const next = parseThemePreference(event.newValue)
-            setThemePreferenceState(next)
-        }
-
-        window.addEventListener('storage', onStorage)
-        return () => window.removeEventListener('storage', onStorage)
+        ensureThemeListeners()
     }, [])
 
     const setThemePreference = useCallback((pref: ThemePreference) => {
         setThemePreferenceState(pref)
-        if (pref === 'system') {
-            safeRemoveItem(STORAGE_KEY)
-        } else {
-            safeSetItem(STORAGE_KEY, pref)
-        }
     }, [])
 
     return {

From 06028693bc78f8b770839f0ee95437b830653474 Mon Sep 17 00:00:00 2001
From: gaius-codius <maher@najemft.com>
Date: Thu, 19 Feb 2026 04:05:34 +0000
Subject: [PATCH 15/27] fix(web): add baseline badge and flavor color tokens
 for session UI

---
 web/src/index.css | 40 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 40 insertions(+)

diff --git a/web/src/index.css b/web/src/index.css
index d74b031bd..f421e8e6e 100644
--- a/web/src/index.css
+++ b/web/src/index.css
@@ -11,6 +11,7 @@
     --app-banner-bg: var(--tg-theme-button-color, #111827);
     --app-banner-text: var(--tg-theme-button-text-color, #ffffff);
     --app-secondary-bg: var(--tg-theme-secondary-bg-color, #f3f4f6);
+    --app-selected-bg: rgba(59, 130, 246, 0.08);
 
     /* Theme-aware colors (light mode defaults) */
     --app-border: rgba(0, 0, 0, 0.1);
@@ -33,6 +34,9 @@
     --app-git-untracked-color: #8E8E93;
 
     /* Badge colors (light) */
+    --app-badge-info-bg: rgba(59, 130, 246, 0.15);
+    --app-badge-info-text: #1d4ed8;
+    --app-badge-info-border: rgba(59, 130, 246, 0.25);
     --app-badge-warning-bg: rgba(245, 158, 11, 0.2);
     --app-badge-warning-text: #b45309;
     --app-badge-warning-border: rgba(245, 158, 11, 0.3);
@@ -43,6 +47,22 @@
     --app-badge-error-text: #b91c1c;
     --app-badge-error-border: rgba(239, 68, 68, 0.3);
 
+    --app-perm-warning: #c2410c;
+
+    /* Agent flavor colors (light) */
+    --app-flavor-claude: #92400e;
+    --app-flavor-claude-bg: rgba(245, 158, 11, 0.12);
+    --app-flavor-claude-border: rgba(245, 158, 11, 0.25);
+    --app-flavor-codex: #065f46;
+    --app-flavor-codex-bg: rgba(16, 185, 129, 0.12);
+    --app-flavor-codex-border: rgba(16, 185, 129, 0.25);
+    --app-flavor-gemini: #1e40af;
+    --app-flavor-gemini-bg: rgba(59, 130, 246, 0.12);
+    --app-flavor-gemini-border: rgba(59, 130, 246, 0.25);
+    --app-flavor-opencode: #5b21b6;
+    --app-flavor-opencode-bg: rgba(139, 92, 246, 0.12);
+    --app-flavor-opencode-border: rgba(139, 92, 246, 0.25);
+
     --app-font-scale: 1;
 }
 
@@ -57,6 +77,7 @@
     --app-banner-bg: var(--tg-theme-button-color, #3A3A3C);
     --app-banner-text: var(--tg-theme-button-text-color, #ffffff);
     --app-secondary-bg: var(--tg-theme-secondary-bg-color, #2C2C2E);
+    --app-selected-bg: rgba(59, 130, 246, 0.08);
 
     --app-border: rgba(255, 255, 255, 0.1);
     --app-divider: rgba(255, 255, 255, 0.08);
@@ -78,6 +99,9 @@
     --app-git-untracked-color: #9ca3af;
 
     /* Badge colors (dark) */
+    --app-badge-info-bg: rgba(96, 165, 250, 0.2);
+    --app-badge-info-text: #60a5fa;
+    --app-badge-info-border: rgba(96, 165, 250, 0.3);
     --app-badge-warning-bg: rgba(251, 191, 36, 0.2);
     --app-badge-warning-text: #fbbf24;
     --app-badge-warning-border: rgba(251, 191, 36, 0.3);
@@ -87,6 +111,22 @@
     --app-badge-error-bg: rgba(248, 113, 113, 0.2);
     --app-badge-error-text: #fca5a5;
     --app-badge-error-border: rgba(248, 113, 113, 0.35);
+
+    --app-perm-warning: #fb923c;
+
+    /* Agent flavor colors (dark) */
+    --app-flavor-claude: #fbbf24;
+    --app-flavor-claude-bg: rgba(245, 158, 11, 0.12);
+    --app-flavor-claude-border: rgba(245, 158, 11, 0.25);
+    --app-flavor-codex: #34d399;
+    --app-flavor-codex-bg: rgba(16, 185, 129, 0.12);
+    --app-flavor-codex-border: rgba(16, 185, 129, 0.25);
+    --app-flavor-gemini: #60a5fa;
+    --app-flavor-gemini-bg: rgba(59, 130, 246, 0.12);
+    --app-flavor-gemini-border: rgba(59, 130, 246, 0.25);
+    --app-flavor-opencode: #a78bfa;
+    --app-flavor-opencode-bg: rgba(139, 92, 246, 0.12);
+    --app-flavor-opencode-border: rgba(139, 92, 246, 0.25);
 }
 
 html {

From e67109482acbbb6f993671f5067e9a38d4efcb83 Mon Sep 17 00:00:00 2001
From: gaius-codius <maher@najemft.com>
Date: Thu, 19 Feb 2026 04:06:19 +0000
Subject: [PATCH 16/27] chore(web): keep session-ui color token baseline in
 session-ui PR

---
 web/src/index.css | 40 ----------------------------------------
 1 file changed, 40 deletions(-)

diff --git a/web/src/index.css b/web/src/index.css
index 21ac74356..8afded615 100644
--- a/web/src/index.css
+++ b/web/src/index.css
@@ -11,7 +11,6 @@
     --app-banner-bg: var(--tg-theme-button-color, #111827);
     --app-banner-text: var(--tg-theme-button-text-color, #ffffff);
     --app-secondary-bg: var(--tg-theme-secondary-bg-color, #f3f4f6);
-    --app-selected-bg: rgba(59, 130, 246, 0.08);
 
     /* Theme-aware colors (light mode defaults) */
     --app-border: rgba(0, 0, 0, 0.1);
@@ -34,9 +33,6 @@
     --app-git-untracked-color: #8E8E93;
 
     /* Badge colors (light) */
-    --app-badge-info-bg: rgba(59, 130, 246, 0.15);
-    --app-badge-info-text: #1d4ed8;
-    --app-badge-info-border: rgba(59, 130, 246, 0.25);
     --app-badge-warning-bg: rgba(245, 158, 11, 0.2);
     --app-badge-warning-text: #b45309;
     --app-badge-warning-border: rgba(245, 158, 11, 0.3);
@@ -47,22 +43,6 @@
     --app-badge-error-text: #b91c1c;
     --app-badge-error-border: rgba(239, 68, 68, 0.3);
 
-    --app-perm-warning: #c2410c;
-
-    /* Agent flavor colors (light) */
-    --app-flavor-claude: #92400e;
-    --app-flavor-claude-bg: rgba(245, 158, 11, 0.12);
-    --app-flavor-claude-border: rgba(245, 158, 11, 0.25);
-    --app-flavor-codex: #065f46;
-    --app-flavor-codex-bg: rgba(16, 185, 129, 0.12);
-    --app-flavor-codex-border: rgba(16, 185, 129, 0.25);
-    --app-flavor-gemini: #1e40af;
-    --app-flavor-gemini-bg: rgba(59, 130, 246, 0.12);
-    --app-flavor-gemini-border: rgba(59, 130, 246, 0.25);
-    --app-flavor-opencode: #5b21b6;
-    --app-flavor-opencode-bg: rgba(139, 92, 246, 0.12);
-    --app-flavor-opencode-border: rgba(139, 92, 246, 0.25);
-
     --app-font-scale: 1;
 }
 
@@ -77,7 +57,6 @@
     --app-banner-bg: var(--tg-theme-button-color, #3A3A3C);
     --app-banner-text: var(--tg-theme-button-text-color, #ffffff);
     --app-secondary-bg: var(--tg-theme-secondary-bg-color, #2C2C2E);
-    --app-selected-bg: rgba(59, 130, 246, 0.08);
 
     --app-border: rgba(255, 255, 255, 0.1);
     --app-divider: rgba(255, 255, 255, 0.08);
@@ -99,9 +78,6 @@
     --app-git-untracked-color: #9ca3af;
 
     /* Badge colors (dark) */
-    --app-badge-info-bg: rgba(96, 165, 250, 0.2);
-    --app-badge-info-text: #60a5fa;
-    --app-badge-info-border: rgba(96, 165, 250, 0.3);
     --app-badge-warning-bg: rgba(251, 191, 36, 0.2);
     --app-badge-warning-text: #fbbf24;
     --app-badge-warning-border: rgba(251, 191, 36, 0.3);
@@ -111,22 +87,6 @@
     --app-badge-error-bg: rgba(248, 113, 113, 0.2);
     --app-badge-error-text: #fca5a5;
     --app-badge-error-border: rgba(248, 113, 113, 0.35);
-
-    --app-perm-warning: #fb923c;
-
-    /* Agent flavor colors (dark) */
-    --app-flavor-claude: #fbbf24;
-    --app-flavor-claude-bg: rgba(245, 158, 11, 0.12);
-    --app-flavor-claude-border: rgba(245, 158, 11, 0.25);
-    --app-flavor-codex: #34d399;
-    --app-flavor-codex-bg: rgba(16, 185, 129, 0.12);
-    --app-flavor-codex-border: rgba(16, 185, 129, 0.25);
-    --app-flavor-gemini: #60a5fa;
-    --app-flavor-gemini-bg: rgba(59, 130, 246, 0.12);
-    --app-flavor-gemini-border: rgba(59, 130, 246, 0.25);
-    --app-flavor-opencode: #a78bfa;
-    --app-flavor-opencode-bg: rgba(139, 92, 246, 0.12);
-    --app-flavor-opencode-border: rgba(139, 92, 246, 0.25);
 }
 
 [data-theme="catpuccin"] {

From 87522d2443962a756f4ff534c49e13f602b48271 Mon Sep 17 00:00:00 2001
From: gaius-codius <maher@najemft.com>
Date: Thu, 19 Feb 2026 11:36:21 +0000
Subject: [PATCH 17/27] docs: add local fork install/update workflow and helper
 script

---
 LOCAL_FORK_WORKFLOW.md       | 112 +++++++++++++++++++++++++++++++++++
 scripts/update-local-hapi.sh | 102 +++++++++++++++++++++++++++++++
 2 files changed, 214 insertions(+)
 create mode 100644 LOCAL_FORK_WORKFLOW.md
 create mode 100755 scripts/update-local-hapi.sh

diff --git a/LOCAL_FORK_WORKFLOW.md b/LOCAL_FORK_WORKFLOW.md
new file mode 100644
index 000000000..56031d51e
--- /dev/null
+++ b/LOCAL_FORK_WORKFLOW.md
@@ -0,0 +1,112 @@
+# Local Fork Workflow (copy/paste friendly)
+
+Use this when you want to run **your forked HAPI build** locally and keep it updated with `tiann/hapi`.
+
+Current remote layout in this repo:
+
+- `origin` = upstream (`https://github.com/tiann/hapi.git`)
+- `fork` = your fork (`https://github.com/gaius-codius/hapi.git`)
+
+---
+
+## 1) One-time switch from RPM to your local fork build
+
+```bash
+# from anywhere
+which hapi
+rpm -qf "$(which hapi)"
+sudo dnf remove hapi     # or: sudo rpm -e <exact-package-name>
+hash -r
+
+# from repo root
+cd /home/gretus/code/hapi
+git checkout main
+bun install
+bun run build:single-exe
+
+# install your built binary to user path
+install -Dm755 cli/dist-exe/bun-linux-x64/hapi ~/.local/bin/hapi
+hash -r
+
+# verify
+which hapi
+hapi --version
+```
+
+If `~/.local/bin` not in PATH, add it:
+
+```bash
+echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
+source ~/.bashrc
+```
+
+---
+
+## 2) Manual ongoing update flow
+
+```bash
+cd /home/gretus/code/hapi
+git checkout main
+git fetch origin fork
+git merge origin/main
+bun install
+bun run build:single-exe
+install -Dm755 cli/dist-exe/bun-linux-x64/hapi ~/.local/bin/hapi
+git push fork main
+```
+
+Optional extra validation before build:
+
+```bash
+bun run typecheck
+bun run test:web
+```
+
+---
+
+## 3) Scripted ongoing update flow (recommended)
+
+Script added at:
+
+```text
+scripts/update-local-hapi.sh
+```
+
+Make executable once:
+
+```bash
+cd /home/gretus/code/hapi
+chmod +x scripts/update-local-hapi.sh
+```
+
+Run it:
+
+```bash
+cd /home/gretus/code/hapi
+./scripts/update-local-hapi.sh
+```
+
+Run with validation:
+
+```bash
+cd /home/gretus/code/hapi
+RUN_TESTS=1 ./scripts/update-local-hapi.sh
+```
+
+Optional env overrides:
+
+```bash
+UPSTREAM_REMOTE=origin FORK_REMOTE=fork MAIN_BRANCH=main INSTALL_DIR="$HOME/.local/bin" ./scripts/update-local-hapi.sh
+```
+
+---
+
+## 4) Quick checks
+
+```bash
+git remote -v
+git status -sb
+which hapi
+hapi --version
+```
+
diff --git a/scripts/update-local-hapi.sh b/scripts/update-local-hapi.sh
new file mode 100755
index 000000000..76ce4fa4d
--- /dev/null
+++ b/scripts/update-local-hapi.sh
@@ -0,0 +1,102 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Keep local forked main updated from upstream, build, install local binary, push fork.
+#
+# Defaults match this repo's current remote layout:
+# - origin = upstream (tiann/hapi)
+# - fork   = your fork
+#
+# Optional env overrides:
+#   UPSTREAM_REMOTE=origin
+#   FORK_REMOTE=fork
+#   MAIN_BRANCH=main
+#   INSTALL_DIR=$HOME/.local/bin
+#   RUN_TESTS=0   # set to 1 to run typecheck + web tests before build
+
+UPSTREAM_REMOTE="${UPSTREAM_REMOTE:-origin}"
+FORK_REMOTE="${FORK_REMOTE:-fork}"
+MAIN_BRANCH="${MAIN_BRANCH:-main}"
+INSTALL_DIR="${INSTALL_DIR:-$HOME/.local/bin}"
+RUN_TESTS="${RUN_TESTS:-0}"
+
+require_cmd() {
+    if ! command -v "$1" >/dev/null 2>&1; then
+        echo "error: missing required command: $1" >&2
+        exit 1
+    fi
+}
+
+detect_target() {
+    local os arch
+    os="$(uname -s | tr '[:upper:]' '[:lower:]')"
+    arch="$(uname -m)"
+
+    case "${os}-${arch}" in
+        linux-x86_64) echo "bun-linux-x64" ;;
+        linux-aarch64|linux-arm64) echo "bun-linux-arm64" ;;
+        darwin-x86_64) echo "bun-darwin-x64" ;;
+        darwin-arm64) echo "bun-darwin-arm64" ;;
+        *)
+            echo "error: unsupported platform: ${os}-${arch}" >&2
+            echo "supported: linux/darwin on x64/arm64" >&2
+            exit 1
+            ;;
+    esac
+}
+
+require_cmd git
+require_cmd bun
+require_cmd install
+
+if ! git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+    echo "error: run this script inside the hapi git repo" >&2
+    exit 1
+fi
+
+if ! git diff --quiet || ! git diff --cached --quiet; then
+    echo "error: working tree not clean; commit/stash first" >&2
+    exit 1
+fi
+
+echo "==> checkout ${MAIN_BRANCH}"
+git checkout "${MAIN_BRANCH}"
+
+echo "==> fetch remotes"
+git fetch "${UPSTREAM_REMOTE}" "${MAIN_BRANCH}"
+git fetch "${FORK_REMOTE}" "${MAIN_BRANCH}" || true
+
+echo "==> merge upstream changes"
+git merge --ff-only "${UPSTREAM_REMOTE}/${MAIN_BRANCH}"
+
+echo "==> install dependencies"
+bun install
+
+if [[ "${RUN_TESTS}" == "1" ]]; then
+    echo "==> run validation"
+    bun run typecheck
+    bun run test:web
+fi
+
+echo "==> build single binary"
+bun run build:single-exe
+
+target="$(detect_target)"
+binary_path="cli/dist-exe/${target}/hapi"
+
+if [[ ! -x "${binary_path}" ]]; then
+    echo "error: built binary not found: ${binary_path}" >&2
+    exit 1
+fi
+
+echo "==> install binary to ${INSTALL_DIR}/hapi"
+mkdir -p "${INSTALL_DIR}"
+install -m755 "${binary_path}" "${INSTALL_DIR}/hapi"
+
+echo "==> push ${MAIN_BRANCH} to fork"
+git push "${FORK_REMOTE}" "${MAIN_BRANCH}:${MAIN_BRANCH}"
+
+echo ""
+echo "done."
+echo "binary: ${INSTALL_DIR}/hapi"
+echo "version: $("${INSTALL_DIR}/hapi" --version || true)"

From d70f93cbf9700492b8e970af579c91785093f7a8 Mon Sep 17 00:00:00 2001
From: gaius-codius <maher@najemft.com>
Date: Thu, 19 Feb 2026 13:56:51 +0000
Subject: [PATCH 18/27] web: improve voice mic error handling; checkpoint
 current repo changes

---
 ._LOCAL_FORK_WORKFLOW.md                      | Bin 0 -> 4096 bytes
 ._LOCAL_FORK_WORKFLOW.md.sb-b154ab4b-8zGe5O   | Bin 0 -> 4096 bytes
 bun.lock                                      |   2 +
 docs/GAIUS_THEME.md                           | 365 ++++++++++++++++++
 .../LOCAL_FORK_WORKFLOW.md                    |  10 +-
 scripts/update-local-hapi.sh                  |   2 +-
 web/src/realtime/RealtimeVoiceSession.tsx     |  69 +++-
 7 files changed, 432 insertions(+), 16 deletions(-)
 create mode 100755 ._LOCAL_FORK_WORKFLOW.md
 create mode 100755 ._LOCAL_FORK_WORKFLOW.md.sb-b154ab4b-8zGe5O
 create mode 100644 docs/GAIUS_THEME.md
 rename LOCAL_FORK_WORKFLOW.md => docs/LOCAL_FORK_WORKFLOW.md (86%)
 mode change 100644 => 100755

diff --git a/._LOCAL_FORK_WORKFLOW.md b/._LOCAL_FORK_WORKFLOW.md
new file mode 100755
index 0000000000000000000000000000000000000000..218c9ef0bdc8c55f9c054ebec9d2019fac08f674
GIT binary patch
literal 4096
zcmZQz6=P>$Vqox1Ojhs@R)|o50+1L3ClDJkFz{^v(m+1nBL)UWIUt(=a103vf+zv$
zVE6;Xv(dCLL&don7(|ovbM+Dn3UX5Q3X1Z}Qu7k?l2d`wjO;){97VpcG_fc#uOu@M
zEDv%?B?E&wLVs>*Nn%Q3NupJ@uZvG&Qff|ono)6*QDw1FdWCsGzEMu4iCJ1wdXiCY
z0Z=0YBNKz&w<D8h3$K`BU|?ZnZDwf+lr}T4_Dw9xc1_7FvHm2aVzDj#-^0M>@Rixg
z)?vooXZM8j&ij!qeSOD<&Wugdy!8byv@7SvnfESPa=B@P$+5#nXGqpHb{CX=SkmqG
z_K&{H((BPY9{U!5&aY(Sxv45}+;>`Nvgdt{+gHCnn0aAsMhe#wD+Np8#naVwm`iV`
z?`@gaWtX?18R)uEFd71*Aut*OqaiRF0;3@?8UmvsFd71*Aut*Oqai?Q2rvRQfG`-y
zg=AzFD-@*`=a&{Grz)i77iBAC=9Q!ZyOsHQi8(oy3OT81B??J7iFw(;zA#kRkfu=m
M5BG`;gWUiB0OFyDzW@LL

literal 0
HcmV?d00001

diff --git a/._LOCAL_FORK_WORKFLOW.md.sb-b154ab4b-8zGe5O b/._LOCAL_FORK_WORKFLOW.md.sb-b154ab4b-8zGe5O
new file mode 100755
index 0000000000000000000000000000000000000000..cc19a722e55fa1a3be0b1fe9802313cb0a23da10
GIT binary patch
literal 4096
zcmZQz6=P>$Vqox1Ojhs@R)|o50+1L3ClDJkFz{^v(m+1nBL)UWIUt(=a103vf+zv$
zU^oE8(hxqJ1etyShy@rJq>}S<^%4sTa#Hnj5{pYpi&Ill5=&B*1A?KdF92z71_n`t
zx`Lwovedl9yyR4d{hy{~g4DGXr|^PkMka=G2dhG+Zzl~w+)*$Z0;3@?8UmvsFd71*
zAut*OqaiRF0;3@?8UmvsFoHsW5$IPC1_QZ}jLc$%qSWI2(xT*4g|z&lY=z9clGMDC
n%>2B>oSaI9oYb@ug`}Lsylh}!7^-VXQ>gxjdqsvp?*D%PU+Ol9

literal 0
HcmV?d00001

diff --git a/bun.lock b/bun.lock
index 0ed85e8c3..6dd484e38 100644
--- a/bun.lock
+++ b/bun.lock
@@ -882,6 +882,8 @@
 
     "@twsxtd/hapi-linux-x64": ["@twsxtd/hapi-linux-x64@0.15.2", "", { "os": "linux", "cpu": "x64", "bin": { "hapi": "bin/hapi" } }, "sha512-wwQM88HATws1quf94M6D4rbkWXNVfIcAMA2WKae+i8/be2vvAi8uuvfV7HHqsqeozUmMJ3NEC6zKYhEtlmMuoA=="],
 
+    "@twsxtd/hapi-win32-x64": ["@twsxtd/hapi-win32-x64@0.15.2", "", { "os": "win32", "cpu": "x64", "bin": { "hapi": "bin/hapi.exe" } }, "sha512-vuQH9INKvqwVZ9JphUmEyzKz6zWxHy3GE4j0mDqTulO234nGEhljkN3Qod0d7bLVncmO53zSMcm+ahwZ3qL4OA=="],
+
     "@types/aria-query": ["@types/aria-query@5.0.4", "", {}, "sha512-rfT93uj5s0PRL7EzccGMs3brplhcrghnDoV26NqKhCAS1hVo+WdNsPvE/yb6ilfr5hi2MEk6d5EWJTKdxg8jVw=="],
 
     "@types/babel__core": ["@types/babel__core@7.20.5", "", { "dependencies": { "@babel/parser": "^7.20.7", "@babel/types": "^7.20.7", "@types/babel__generator": "*", "@types/babel__template": "*", "@types/babel__traverse": "*" } }, "sha512-qoQprZvz5wQFJwMDqeseRXWv3rqMvhgpbXFfVyWhbx9X47POIA6i/+dXefEmZKoAgOaTdaIgNSMqMIU61yRyzA=="],
diff --git a/docs/GAIUS_THEME.md b/docs/GAIUS_THEME.md
new file mode 100644
index 000000000..f11c84762
--- /dev/null
+++ b/docs/GAIUS_THEME.md
@@ -0,0 +1,365 @@
+# Gaius Theme
+
+A warm, earthy color theme inspired by historical pigments. Ships with light and dark variants.
+
+## Design Philosophy
+
+Warm, sophisticated palette built around five named historical pigments. Light variant uses a warm pearl base; dark variant uses a deep slate base. Both maintain visual hierarchy with carefully calibrated opacity overlays for subtle UI layering.
+
+## Color Palette
+
+| Pigment | Light | Dark | Usage |
+|---|---|---|---|
+| **Cinnabar** | `#b04440` | `#d06058` | Links, errors, destructive actions |
+| **Verdigris** | `#3a7868` | `#68b8a0` | Success, positive states |
+| **Lapis** | `#4068a0` | `#6890c8` | Info, neutral highlights |
+| **Gold** | `#b07830` | `#d0a060` | Warnings |
+| **Violet** | `#6a5090` | `#a088c0` | Accent, secondary highlights |
+
+---
+
+## Gaius Light
+
+Base: `#f8f5f2` (warm pearl) / Text: `#2a2832` (dark slate)
+
+### Core
+
+| Token | Value | Description |
+|---|---|---|
+| `--app-bg` | `#f8f5f2` | Background |
+| `--app-fg` | `#2a2832` | Text |
+| `--app-hint` | `#85808a` | Muted/secondary text |
+| `--app-link` | `#b04440` | Links (cinnabar) |
+| `--app-button` | `#2a2832` | Button background |
+| `--app-button-text` | `#f8f5f2` | Button text |
+| `--app-banner-bg` | `#eceae6` | Banner background |
+| `--app-banner-text` | `#2a2832` | Banner text |
+| `--app-secondary-bg` | `#f0ede9` | Secondary background |
+
+### Surfaces & Borders
+
+| Token | Value |
+|---|---|
+| `--app-border` | `rgba(42, 40, 50, 0.10)` |
+| `--app-divider` | `rgba(42, 40, 50, 0.07)` |
+| `--app-subtle-bg` | `rgba(42, 40, 50, 0.03)` |
+| `--app-code-bg` | `#f0ede8` |
+| `--app-inline-code-bg` | `rgba(42, 40, 50, 0.05)` |
+| `--app-selected-bg` | `rgba(176, 68, 64, 0.06)` |
+
+### Diff
+
+| Token | Value |
+|---|---|
+| `--app-diff-added-bg` | `#e4edd8` |
+| `--app-diff-added-text` | `#2a2832` |
+| `--app-diff-removed-bg` | `#f2dcd8` |
+| `--app-diff-removed-text` | `#2a2832` |
+
+### Status Colors
+
+| Token | Value | Pigment |
+|---|---|---|
+| `--app-git-staged-color` | `#3a7868` | Verdigris |
+| `--app-git-unstaged-color` | `#b07830` | Gold |
+| `--app-git-deleted-color` | `#b84440` | Cinnabar |
+| `--app-git-renamed-color` | `#4068a0` | Lapis |
+| `--app-git-untracked-color` | `#85808a` | Muted |
+
+### Badges
+
+| Type | Background | Text | Border |
+|---|---|---|---|
+| Info | `rgba(64, 104, 160, 0.10)` | `#3a5888` | `rgba(64, 104, 160, 0.20)` |
+| Warning | `rgba(176, 120, 48, 0.12)` | `#8a5820` | `rgba(176, 120, 48, 0.22)` |
+| Success | `rgba(58, 120, 104, 0.10)` | `#2a6858` | `rgba(58, 120, 104, 0.20)` |
+| Error | `rgba(184, 68, 64, 0.10)` | `#983838` | `rgba(184, 68, 64, 0.20)` |
+
+### Brand/Flavor Accents
+
+| Name | Color | Background | Border |
+|---|---|---|---|
+| Claude | `#a04038` | `rgba(160, 64, 56, 0.08)` | `rgba(160, 64, 56, 0.18)` |
+| Codex | `#2a6858` | `rgba(42, 104, 88, 0.08)` | `rgba(42, 104, 88, 0.18)` |
+| Gemini | `#3a5888` | `rgba(58, 88, 136, 0.08)` | `rgba(58, 88, 136, 0.18)` |
+| OpenCode | `#6a5090` | `rgba(106, 80, 144, 0.08)` | `rgba(106, 80, 144, 0.18)` |
+
+### Misc
+
+| Token | Value |
+|---|---|
+| `--app-perm-warning` | `#b84430` |
+
+---
+
+## Gaius Dark
+
+Base: `#1e1d22` (deep slate) / Text: `#e6e3de` (light cream)
+
+### Core
+
+| Token | Value | Description |
+|---|---|---|
+| `--app-bg` | `#1e1d22` | Background |
+| `--app-fg` | `#e6e3de` | Text |
+| `--app-hint` | `#88848e` | Muted/secondary text |
+| `--app-link` | `#d06058` | Links (coral) |
+| `--app-button` | `#e6e3de` | Button background |
+| `--app-button-text` | `#1e1d22` | Button text |
+| `--app-banner-bg` | `#2a2930` | Banner background |
+| `--app-banner-text` | `#e6e3de` | Banner text |
+| `--app-secondary-bg` | `#252428` | Secondary background |
+
+### Surfaces & Borders
+
+| Token | Value |
+|---|---|
+| `--app-border` | `rgba(230, 227, 222, 0.08)` |
+| `--app-divider` | `rgba(230, 227, 222, 0.06)` |
+| `--app-subtle-bg` | `rgba(230, 227, 222, 0.04)` |
+| `--app-code-bg` | `#252430` |
+| `--app-inline-code-bg` | `rgba(230, 227, 222, 0.07)` |
+| `--app-selected-bg` | `rgba(208, 96, 88, 0.06)` |
+
+### Diff
+
+| Token | Value |
+|---|---|
+| `--app-diff-added-bg` | `rgba(80, 150, 130, 0.12)` |
+| `--app-diff-added-text` | `#d8d5d0` |
+| `--app-diff-removed-bg` | `rgba(200, 80, 70, 0.12)` |
+| `--app-diff-removed-text` | `#d8d5d0` |
+
+### Status Colors
+
+| Token | Value |
+|---|---|
+| `--app-git-staged-color` | `#68b8a0` |
+| `--app-git-unstaged-color` | `#d0a060` |
+| `--app-git-deleted-color` | `#d87068` |
+| `--app-git-renamed-color` | `#6890c8` |
+| `--app-git-untracked-color` | `#88848e` |
+
+### Badges
+
+| Type | Background | Text | Border |
+|---|---|---|---|
+| Info | `rgba(104, 144, 200, 0.12)` | `#6890c8` | `rgba(104, 144, 200, 0.20)` |
+| Warning | `rgba(208, 160, 96, 0.15)` | `#d0a060` | `rgba(208, 160, 96, 0.25)` |
+| Success | `rgba(104, 184, 160, 0.10)` | `#68b8a0` | `rgba(104, 184, 160, 0.20)` |
+| Error | `rgba(216, 112, 104, 0.12)` | `#d87068` | `rgba(216, 112, 104, 0.22)` |
+
+### Brand/Flavor Accents
+
+| Name | Color | Background | Border |
+|---|---|---|---|
+| Claude | `#d08858` | `rgba(208, 136, 88, 0.10)` | `rgba(208, 136, 88, 0.20)` |
+| Codex | `#68b8a0` | `rgba(104, 184, 160, 0.10)` | `rgba(104, 184, 160, 0.20)` |
+| Gemini | `#6890c8` | `rgba(104, 144, 200, 0.10)` | `rgba(104, 144, 200, 0.20)` |
+| OpenCode | `#a088c0` | `rgba(160, 136, 192, 0.10)` | `rgba(160, 136, 192, 0.20)` |
+
+### Misc
+
+| Token | Value |
+|---|---|
+| `--app-perm-warning` | `#d08050` |
+
+---
+
+## Raw CSS
+
+Copy-paste ready for use in other projects. Apply via `data-theme` attribute on a root element.
+
+### Gaius Light
+
+```css
+[data-theme="gaius-light"] {
+    /* Primary — warm pearl base */
+    --app-bg: #f8f5f2;
+    --app-fg: #2a2832;
+    --app-hint: #85808a;
+    --app-link: #b04440;
+    --app-button: #2a2832;
+    --app-button-text: #f8f5f2;
+    --app-banner-bg: #eceae6;
+    --app-banner-text: #2a2832;
+    --app-secondary-bg: #f0ede9;
+    --app-selected-bg: rgba(176, 68, 64, 0.06);
+
+    /* Overlays */
+    --app-border: rgba(42, 40, 50, 0.10);
+    --app-divider: rgba(42, 40, 50, 0.07);
+    --app-subtle-bg: rgba(42, 40, 50, 0.03);
+    --app-code-bg: #f0ede8;
+    --app-inline-code-bg: rgba(42, 40, 50, 0.05);
+
+    /* Diffs — verdigris added, cinnabar removed */
+    --app-diff-added-bg: #e4edd8;
+    --app-diff-added-text: #2a2832;
+    --app-diff-removed-bg: #f2dcd8;
+    --app-diff-removed-text: #2a2832;
+
+    /* Git status */
+    --app-git-staged-color: #3a7868;
+    --app-git-unstaged-color: #b07830;
+    --app-git-deleted-color: #b84440;
+    --app-git-renamed-color: #4068a0;
+    --app-git-untracked-color: #85808a;
+
+    /* Badges — lapis, gold, verdigris, cinnabar */
+    --app-badge-info-bg: rgba(64, 104, 160, 0.10);
+    --app-badge-info-text: #3a5888;
+    --app-badge-info-border: rgba(64, 104, 160, 0.20);
+    --app-badge-warning-bg: rgba(176, 120, 48, 0.12);
+    --app-badge-warning-text: #8a5820;
+    --app-badge-warning-border: rgba(176, 120, 48, 0.22);
+    --app-badge-success-bg: rgba(58, 120, 104, 0.10);
+    --app-badge-success-text: #2a6858;
+    --app-badge-success-border: rgba(58, 120, 104, 0.20);
+    --app-badge-error-bg: rgba(184, 68, 64, 0.10);
+    --app-badge-error-text: #983838;
+    --app-badge-error-border: rgba(184, 68, 64, 0.20);
+
+    --app-perm-warning: #b84430;
+
+    /* Agent flavors — cinnabar, verdigris, lapis, violet */
+    --app-flavor-claude: #a04038;
+    --app-flavor-claude-bg: rgba(160, 64, 56, 0.08);
+    --app-flavor-claude-border: rgba(160, 64, 56, 0.18);
+    --app-flavor-codex: #2a6858;
+    --app-flavor-codex-bg: rgba(42, 104, 88, 0.08);
+    --app-flavor-codex-border: rgba(42, 104, 88, 0.18);
+    --app-flavor-gemini: #3a5888;
+    --app-flavor-gemini-bg: rgba(58, 88, 136, 0.08);
+    --app-flavor-gemini-border: rgba(58, 88, 136, 0.18);
+    --app-flavor-opencode: #6a5090;
+    --app-flavor-opencode-bg: rgba(106, 80, 144, 0.08);
+    --app-flavor-opencode-border: rgba(106, 80, 144, 0.18);
+}
+```
+
+### Gaius Dark
+
+```css
+[data-theme="gaius-dark"] {
+    /* Primary — deep slate base */
+    --app-bg: #1e1d22;
+    --app-fg: #e6e3de;
+    --app-hint: #88848e;
+    --app-link: #d06058;
+    --app-button: #e6e3de;
+    --app-button-text: #1e1d22;
+    --app-banner-bg: #2a2930;
+    --app-banner-text: #e6e3de;
+    --app-secondary-bg: #252428;
+    --app-selected-bg: rgba(208, 96, 88, 0.06);
+
+    /* Overlays */
+    --app-border: rgba(230, 227, 222, 0.08);
+    --app-divider: rgba(230, 227, 222, 0.06);
+    --app-subtle-bg: rgba(230, 227, 222, 0.04);
+    --app-code-bg: #252430;
+    --app-inline-code-bg: rgba(230, 227, 222, 0.07);
+
+    /* Diffs */
+    --app-diff-added-bg: rgba(80, 150, 130, 0.12);
+    --app-diff-added-text: #d8d5d0;
+    --app-diff-removed-bg: rgba(200, 80, 70, 0.12);
+    --app-diff-removed-text: #d8d5d0;
+
+    /* Git status */
+    --app-git-staged-color: #68b8a0;
+    --app-git-unstaged-color: #d0a060;
+    --app-git-deleted-color: #d87068;
+    --app-git-renamed-color: #6890c8;
+    --app-git-untracked-color: #88848e;
+
+    /* Badges */
+    --app-badge-info-bg: rgba(104, 144, 200, 0.12);
+    --app-badge-info-text: #6890c8;
+    --app-badge-info-border: rgba(104, 144, 200, 0.20);
+    --app-badge-warning-bg: rgba(208, 160, 96, 0.15);
+    --app-badge-warning-text: #d0a060;
+    --app-badge-warning-border: rgba(208, 160, 96, 0.25);
+    --app-badge-success-bg: rgba(104, 184, 160, 0.10);
+    --app-badge-success-text: #68b8a0;
+    --app-badge-success-border: rgba(104, 184, 160, 0.20);
+    --app-badge-error-bg: rgba(216, 112, 104, 0.12);
+    --app-badge-error-text: #d87068;
+    --app-badge-error-border: rgba(216, 112, 104, 0.22);
+
+    --app-perm-warning: #d08050;
+
+    /* Agent flavors */
+    --app-flavor-claude: #d08858;
+    --app-flavor-claude-bg: rgba(208, 136, 88, 0.10);
+    --app-flavor-claude-border: rgba(208, 136, 88, 0.20);
+    --app-flavor-codex: #68b8a0;
+    --app-flavor-codex-bg: rgba(104, 184, 160, 0.10);
+    --app-flavor-codex-border: rgba(104, 184, 160, 0.20);
+    --app-flavor-gemini: #6890c8;
+    --app-flavor-gemini-bg: rgba(104, 144, 200, 0.10);
+    --app-flavor-gemini-border: rgba(104, 144, 200, 0.20);
+    --app-flavor-opencode: #a088c0;
+    --app-flavor-opencode-bg: rgba(160, 136, 192, 0.10);
+    --app-flavor-opencode-border: rgba(160, 136, 192, 0.20);
+}
+```
+
+---
+
+## Token Reference
+
+Full list of CSS custom properties used:
+
+```
+--app-bg
+--app-fg
+--app-hint
+--app-link
+--app-button
+--app-button-text
+--app-banner-bg
+--app-banner-text
+--app-secondary-bg
+--app-selected-bg
+--app-border
+--app-divider
+--app-subtle-bg
+--app-code-bg
+--app-inline-code-bg
+--app-diff-added-bg
+--app-diff-added-text
+--app-diff-removed-bg
+--app-diff-removed-text
+--app-git-staged-color
+--app-git-unstaged-color
+--app-git-deleted-color
+--app-git-renamed-color
+--app-git-untracked-color
+--app-badge-info-bg
+--app-badge-info-text
+--app-badge-info-border
+--app-badge-warning-bg
+--app-badge-warning-text
+--app-badge-warning-border
+--app-badge-success-bg
+--app-badge-success-text
+--app-badge-success-border
+--app-badge-error-bg
+--app-badge-error-text
+--app-badge-error-border
+--app-flavor-claude
+--app-flavor-claude-bg
+--app-flavor-claude-border
+--app-flavor-codex
+--app-flavor-codex-bg
+--app-flavor-codex-border
+--app-flavor-gemini
+--app-flavor-gemini-bg
+--app-flavor-gemini-border
+--app-flavor-opencode
+--app-flavor-opencode-bg
+--app-flavor-opencode-border
+--app-perm-warning
+```
diff --git a/LOCAL_FORK_WORKFLOW.md b/docs/LOCAL_FORK_WORKFLOW.md
old mode 100644
new mode 100755
similarity index 86%
rename from LOCAL_FORK_WORKFLOW.md
rename to docs/LOCAL_FORK_WORKFLOW.md
index 56031d51e..4b2057c5f
--- a/LOCAL_FORK_WORKFLOW.md
+++ b/docs/LOCAL_FORK_WORKFLOW.md
@@ -9,13 +9,13 @@ Current remote layout in this repo:
 
 ---
 
-## 1) One-time switch from RPM to your local fork build
+## 1) One-time switch from global npm package to your local fork build
 
 ```bash
 # from anywhere
 which hapi
-rpm -qf "$(which hapi)"
-sudo dnf remove hapi     # or: sudo rpm -e <exact-package-name>
+npm list -g @twsxtd/hapi
+npm uninstall -g @twsxtd/hapi
 hash -r
 
 # from repo root
@@ -47,7 +47,8 @@ source ~/.bashrc
 ```bash
 cd /home/gretus/code/hapi
 git checkout main
-git fetch origin fork
+git fetch origin
+git fetch fork
 git merge origin/main
 bun install
 bun run build:single-exe
@@ -110,3 +111,4 @@ which hapi
 hapi --version
 ```
 
+Going forward, run ./scripts/update-local-hapi.sh from the repo root to pull upstream changes, rebuild, and reinstall.
\ No newline at end of file
diff --git a/scripts/update-local-hapi.sh b/scripts/update-local-hapi.sh
index 76ce4fa4d..4750533c1 100755
--- a/scripts/update-local-hapi.sh
+++ b/scripts/update-local-hapi.sh
@@ -67,7 +67,7 @@ git fetch "${UPSTREAM_REMOTE}" "${MAIN_BRANCH}"
 git fetch "${FORK_REMOTE}" "${MAIN_BRANCH}" || true
 
 echo "==> merge upstream changes"
-git merge --ff-only "${UPSTREAM_REMOTE}/${MAIN_BRANCH}"
+git merge "${UPSTREAM_REMOTE}/${MAIN_BRANCH}"
 
 echo "==> install dependencies"
 bun install
diff --git a/web/src/realtime/RealtimeVoiceSession.tsx b/web/src/realtime/RealtimeVoiceSession.tsx
index fff9b7b44..f13b428ae 100644
--- a/web/src/realtime/RealtimeVoiceSession.tsx
+++ b/web/src/realtime/RealtimeVoiceSession.tsx
@@ -16,6 +16,54 @@ let conversationInstance: ReturnType<typeof useConversation> | null = null
 // Store reference for status updates
 let statusCallback: StatusCallback | null = null
 
+function getErrorName(error: unknown): string | null {
+    if (!error || typeof error !== 'object') return null
+    const maybeName = (error as { name?: unknown }).name
+    return typeof maybeName === 'string' ? maybeName : null
+}
+
+function resolveVoiceErrorMessage(error: unknown): string {
+    const name = getErrorName(error)
+    const rawMessage = error instanceof Error
+        ? error.message
+        : (typeof error === 'string' ? error : '')
+    const message = rawMessage.toLowerCase()
+
+    if (
+        name === 'NotAllowedError'
+        || name === 'PermissionDeniedError'
+        || message.includes('permission')
+        || message.includes('not allowed')
+        || message.includes('not granted')
+        || message.includes('denied')
+    ) {
+        return 'Microphone permission denied'
+    }
+
+    if (name === 'NotFoundError' || name === 'DevicesNotFoundError') {
+        return 'No microphone found'
+    }
+
+    if (name === 'NotReadableError' || name === 'TrackStartError') {
+        return 'Microphone is busy in another app'
+    }
+
+    if (
+        name === 'SecurityError'
+        || message.includes('secure context')
+        || message.includes('https')
+        || message.includes('insecure')
+    ) {
+        return 'Microphone requires HTTPS (or localhost)'
+    }
+
+    if (rawMessage.trim().length > 0) {
+        return rawMessage
+    }
+
+    return 'Failed to start voice session'
+}
+
 // Global voice session implementation
 class RealtimeVoiceSessionImpl implements VoiceSession {
     private api: ApiClient
@@ -34,16 +82,15 @@ class RealtimeVoiceSessionImpl implements VoiceSession {
 
         statusCallback?.('connecting')
 
-        // Request microphone permission first
-        let permissionStream: MediaStream | null = null
-        try {
-            permissionStream = await navigator.mediaDevices.getUserMedia({ audio: true })
-        } catch (error) {
-            console.error('[Voice] Failed to get microphone permission:', error)
-            statusCallback?.('error', 'Microphone permission denied')
+        if (!window.isSecureContext || !navigator.mediaDevices?.getUserMedia) {
+            const error = new Error(
+                !window.isSecureContext
+                    ? 'Microphone requires HTTPS (or localhost)'
+                    : 'Microphone is not available in this browser'
+            )
+            console.error('[Voice] Microphone unavailable:', error)
+            statusCallback?.('error', error.message)
             throw error
-        } finally {
-            permissionStream?.getTracks().forEach((track) => track.stop())
         }
 
         // Fetch conversation token from server
@@ -85,7 +132,7 @@ class RealtimeVoiceSessionImpl implements VoiceSession {
             }
         } catch (error) {
             console.error('[Voice] Failed to start realtime session:', error)
-            statusCallback?.('error', 'Failed to start voice session')
+            statusCallback?.('error', resolveVoiceErrorMessage(error))
             throw error
         }
     }
@@ -185,7 +232,7 @@ export function RealtimeVoiceSession({
 
     const handleError = useCallback((error: unknown) => {
         if (DEBUG) console.error('[Voice] Realtime error:', error)
-        const errorMessage = error instanceof Error ? error.message : 'Connection error'
+        const errorMessage = resolveVoiceErrorMessage(error)
         onStatusChange?.('error', errorMessage)
     }, [onStatusChange])
 

From 7e03f6e46496e102da8d7606700b57409b8ba34c Mon Sep 17 00:00:00 2001
From: gaius-codius <maher@najemft.com>
Date: Sat, 21 Feb 2026 00:34:11 +0000
Subject: [PATCH 19/27] fix: isolate runner integration test to prevent killing
 production runner

The runner integration test was calling stopRunner() which reads the real
~/.hapi/runner.state.json and kills whatever runner it finds. This caused
the production/systemd runner to die whenever tests were executed.

Fix by redirecting all test runner state to a temp directory under /tmp/
and passing HAPI_HOME env to all spawned child processes. Also add
rebuild-and-restart script and bump PWA cache size limit for builds.
---
 cli/src/runner/runner.integration.test.ts | 98 +++++++++++++++++++----
 scripts/rebuild-and-restart.sh            | 79 ++++++++++++++++++
 web/vite.config.ts                        |  3 +-
 3 files changed, 162 insertions(+), 18 deletions(-)
 create mode 100755 scripts/rebuild-and-restart.sh

diff --git a/cli/src/runner/runner.integration.test.ts b/cli/src/runner/runner.integration.test.ts
index 94c3f48ae..77fa1d6a0 100644
--- a/cli/src/runner/runner.integration.test.ts
+++ b/cli/src/runner/runner.integration.test.ts
@@ -15,17 +15,18 @@
  * - CLI_API_TOKEN=... (must match the hub)
  */
 
-import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { describe, it, expect, beforeAll, afterAll, beforeEach, afterEach } from 'vitest';
 import { execSync, spawn } from 'child_process';
-import { existsSync, unlinkSync, readFileSync, writeFileSync, readdirSync } from 'fs';
+import { existsSync, unlinkSync, readFileSync, writeFileSync, readdirSync, mkdirSync, cpSync, rmSync } from 'fs';
+import { tmpdir } from 'os';
 import path, { join } from 'path';
 import { configuration } from '@/configuration';
-import { 
-  listRunnerSessions, 
-  stopRunnerSession, 
-  spawnRunnerSession, 
-  stopRunnerHttp, 
-  notifyRunnerSessionStarted, 
+import {
+  listRunnerSessions,
+  stopRunnerSession,
+  spawnRunnerSession,
+  stopRunnerHttp,
+  notifyRunnerSessionStarted,
   stopRunner
 } from '@/runner/controlClient';
 import { readRunnerState, clearRunnerState } from '@/persistence';
@@ -34,6 +35,55 @@ import { spawnHappyCLI } from '@/utils/spawnHappyCLI';
 import { getLatestRunnerLog } from '@/ui/logger';
 import { isProcessAlive, isWindows, killProcess, killProcessByChildProcess } from '@/utils/process';
 
+// --- Test isolation: use a temp HAPI_HOME so tests never touch the real runner ---
+
+const testHapiHome = join(tmpdir(), `hapi-runner-test-${process.pid}-${Date.now()}`);
+const testEnv = { ...process.env, HAPI_HOME: testHapiHome };
+
+// Override the singleton configuration paths before any test runs.
+// The spawned child processes get isolation via the HAPI_HOME env var.
+function installTestHapiHome(): { originals: Record<string, string> } {
+  mkdirSync(testHapiHome, { recursive: true });
+  mkdirSync(join(testHapiHome, 'logs'), { recursive: true });
+
+  // Copy settings.json so the runner can auth with the hub
+  const realSettings = join(configuration.happyHomeDir, 'settings.json');
+  if (existsSync(realSettings)) {
+    cpSync(realSettings, join(testHapiHome, 'settings.json'));
+  }
+
+  const props = [
+    'happyHomeDir',
+    'logsDir',
+    'settingsFile',
+    'privateKeyFile',
+    'runnerStateFile',
+    'runnerLockFile',
+  ] as const;
+
+  const originals: Record<string, string> = {};
+  for (const prop of props) {
+    originals[prop] = (configuration as any)[prop];
+  }
+
+  // Redirect configuration paths to the temp dir
+  Object.defineProperty(configuration, 'happyHomeDir', { value: testHapiHome, configurable: true });
+  Object.defineProperty(configuration, 'logsDir', { value: join(testHapiHome, 'logs'), configurable: true });
+  Object.defineProperty(configuration, 'settingsFile', { value: join(testHapiHome, 'settings.json'), configurable: true });
+  Object.defineProperty(configuration, 'privateKeyFile', { value: join(testHapiHome, 'access.key'), configurable: true });
+  Object.defineProperty(configuration, 'runnerStateFile', { value: join(testHapiHome, 'runner.state.json'), configurable: true });
+  Object.defineProperty(configuration, 'runnerLockFile', { value: join(testHapiHome, 'runner.state.json.lock'), configurable: true });
+
+  return { originals };
+}
+
+function uninstallTestHapiHome(originals: Record<string, string>): void {
+  for (const [prop, value] of Object.entries(originals)) {
+    Object.defineProperty(configuration, prop, { value, configurable: true });
+  }
+  try { rmSync(testHapiHome, { recursive: true, force: true }); } catch { /* best effort */ }
+}
+
 // Utility to wait for condition
 async function waitFor(
   condition: () => Promise<boolean>,
@@ -80,23 +130,36 @@ async function isServerHealthy(): Promise<boolean> {
 
 describe.skipIf(!await isServerHealthy())('Runner Integration Tests', { timeout: 20_000 }, () => {
   let runnerPid: number;
+  let savedOriginals: Record<string, string>;
+
+  beforeAll(() => {
+    const { originals } = installTestHapiHome();
+    savedOriginals = originals;
+    console.log(`[TEST] Using isolated HAPI_HOME: ${testHapiHome}`);
+  });
+
+  afterAll(async () => {
+    // Make sure the test runner is dead before restoring
+    await stopRunner();
+    uninstallTestHapiHome(savedOriginals);
+  });
 
   beforeEach(async () => {
-    // First ensure no runner is running by checking PID in metadata file
+    // First ensure no test runner is running by checking PID in metadata file
     await stopRunner()
-    
-    // Start fresh runner for this test
-    // This will return and start a background process - we don't need to wait for it
+
+    // Start fresh runner for this test, using isolated HAPI_HOME
     void spawnHappyCLI(['runner', 'start'], {
-      stdio: 'ignore'
+      stdio: 'ignore',
+      env: testEnv
     });
-    
+
     // Wait for runner to write its state file (it needs to auth, setup, and start server)
     await waitFor(async () => {
       const state = await readRunnerState();
       return state !== null;
     }, 10_000, 250); // Wait up to 10 seconds, checking every 250ms
-    
+
     const runnerState = await readRunnerState();
     if (!runnerState) {
       throw new Error('Runner failed to start within timeout');
@@ -200,7 +263,8 @@ describe.skipIf(!await isServerHealthy())('Runner Integration Tests', { timeout:
     ], {
       cwd: '/tmp',
       detached: true,
-      stdio: 'ignore'
+      stdio: 'ignore',
+      env: testEnv
     });
     if (!terminalHappyProcess || !terminalHappyProcess.pid) {
       throw new Error('Failed to spawn terminal hapi process');
@@ -259,7 +323,7 @@ describe.skipIf(!await isServerHealthy())('Runner Integration Tests', { timeout:
     // Try to start another runner
     const secondChild = spawn('bun', ['src/index.ts', 'runner', 'start-sync'], {
       cwd: process.cwd(),
-      env: process.env,
+      env: testEnv,
       stdio: ['ignore', 'pipe', 'pipe']
     });
 
diff --git a/scripts/rebuild-and-restart.sh b/scripts/rebuild-and-restart.sh
new file mode 100755
index 000000000..41715edf0
--- /dev/null
+++ b/scripts/rebuild-and-restart.sh
@@ -0,0 +1,79 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Rebuild from current branch, install binary, restart systemd services.
+#
+# Usage:
+#   ./scripts/rebuild-and-restart.sh          # full rebuild (web + cli)
+#   ./scripts/rebuild-and-restart.sh --quick   # skip web rebuild if dist/ exists
+#
+# Optional env overrides:
+#   INSTALL_DIR=$HOME/.local/bin
+
+INSTALL_DIR="${INSTALL_DIR:-$HOME/.local/bin}"
+QUICK=0
+
+for arg in "$@"; do
+    case "$arg" in
+        --quick) QUICK=1 ;;
+        *) echo "unknown flag: $arg" >&2; exit 1 ;;
+    esac
+done
+
+REPO_ROOT="$(git -C "$(dirname "$0")" rev-parse --show-toplevel)"
+cd "$REPO_ROOT"
+
+detect_target() {
+    local os arch
+    os="$(uname -s | tr '[:upper:]' '[:lower:]')"
+    arch="$(uname -m)"
+    case "${os}-${arch}" in
+        linux-x86_64)              echo "bun-linux-x64" ;;
+        linux-aarch64|linux-arm64) echo "bun-linux-arm64" ;;
+        darwin-x86_64)             echo "bun-darwin-x64" ;;
+        darwin-arm64)              echo "bun-darwin-arm64" ;;
+        *)
+            echo "error: unsupported platform: ${os}-${arch}" >&2
+            exit 1
+            ;;
+    esac
+}
+
+target="$(detect_target)"
+branch="$(git branch --show-current)"
+echo "==> rebuilding from branch: ${branch}"
+
+if [[ "$QUICK" == "1" ]] && [[ -f "web/dist/index.html" ]]; then
+    echo "==> --quick: skipping web build (using existing dist/)"
+else
+    echo "==> building web"
+    bun run build:web
+fi
+
+echo "==> generating embedded web assets"
+(cd hub && bun run generate:embedded-web-assets)
+
+echo "==> building executable"
+(cd cli && bun run build:exe:allinone)
+
+binary_path="cli/dist-exe/${target}/hapi"
+if [[ ! -x "$binary_path" ]]; then
+    echo "error: binary not found: ${binary_path}" >&2
+    exit 1
+fi
+
+echo "==> installing to ${INSTALL_DIR}/hapi"
+mkdir -p "$INSTALL_DIR"
+install -m755 "$binary_path" "${INSTALL_DIR}/hapi"
+
+echo "==> restarting services"
+systemctl --user restart hapi-hub.service
+sleep 2
+systemctl --user restart hapi-runner.service
+
+echo ""
+echo "done."
+echo "binary:  ${INSTALL_DIR}/hapi"
+echo "version: $("${INSTALL_DIR}/hapi" --version 2>/dev/null || echo 'unknown')"
+echo "hub:     $(systemctl --user is-active hapi-hub.service)"
+echo "runner:  $(systemctl --user is-active hapi-runner.service)"
diff --git a/web/vite.config.ts b/web/vite.config.ts
index 0e328a04b..acca8fca6 100644
--- a/web/vite.config.ts
+++ b/web/vite.config.ts
@@ -68,7 +68,8 @@ export default defineConfig({
                 ]
             },
             injectManifest: {
-                globPatterns: ['**/*.{js,css,html,ico,png,svg,woff,woff2}']
+                globPatterns: ['**/*.{js,css,html,ico,png,svg,woff,woff2}'],
+                maximumFileSizeToCacheInBytes: 3 * 1024 * 1024
             },
             devOptions: {
                 enabled: true,

From e0cb86d0804b5fabbe9bffe0c9343f165901d8ec Mon Sep 17 00:00:00 2001
From: gaius-codius <maher@najemft.com>
Date: Sat, 21 Feb 2026 00:36:46 +0000
Subject: [PATCH 20/27] feat: persist session sort mode and manual ordering in
 hub

---
 hub/src/sse/sseManager.test.ts                |  28 ++
 hub/src/sse/sseManager.ts                     |   4 +
 hub/src/store/index.ts                        |  69 +++-
 .../store/sessionSortPreferenceStore.test.ts  |  88 +++++
 hub/src/store/sessionSortPreferenceStore.ts   |  29 ++
 hub/src/store/sessionSortPreferences.ts       | 145 ++++++++
 hub/src/store/types.ts                        |  17 +
 hub/src/sync/syncEngine.ts                    |  75 +++-
 hub/src/web/routes/preferences.test.ts        | 217 ++++++++++++
 hub/src/web/routes/preferences.ts             |  59 ++++
 hub/src/web/server.ts                         |   4 +-
 shared/src/schemas.ts                         |  26 ++
 shared/src/types.ts                           |   3 +
 web/src/App.tsx                               |   1 +
 web/src/api/client.ts                         |  43 ++-
 web/src/components/GroupActionMenu.tsx        | 227 +++++++++++++
 web/src/components/SessionActionMenu.tsx      |  94 +++++
 web/src/components/SessionList.test.tsx       |  91 ++++-
 web/src/components/SessionList.tsx            | 321 +++++++++++++++---
 .../mutations/useSessionSortPreference.ts     |  68 ++++
 .../queries/useSessionSortPreference.test.tsx |  60 ++++
 .../hooks/queries/useSessionSortPreference.ts |  41 +++
 web/src/hooks/useSSE.ts                       |   4 +
 web/src/lib/locales/en.ts                     |   7 +
 web/src/lib/locales/zh-CN.ts                  |   7 +
 web/src/lib/query-keys.ts                     |   1 +
 web/src/lib/sessionSortOrder.test.ts          | 112 ++++++
 web/src/lib/sessionSortOrder.ts               | 158 +++++++++
 web/src/router.tsx                            |  85 ++++-
 web/src/types/api.ts                          |  20 ++
 30 files changed, 2052 insertions(+), 52 deletions(-)
 create mode 100644 hub/src/store/sessionSortPreferenceStore.test.ts
 create mode 100644 hub/src/store/sessionSortPreferenceStore.ts
 create mode 100644 hub/src/store/sessionSortPreferences.ts
 create mode 100644 hub/src/web/routes/preferences.test.ts
 create mode 100644 hub/src/web/routes/preferences.ts
 create mode 100644 web/src/components/GroupActionMenu.tsx
 create mode 100644 web/src/hooks/mutations/useSessionSortPreference.ts
 create mode 100644 web/src/hooks/queries/useSessionSortPreference.test.tsx
 create mode 100644 web/src/hooks/queries/useSessionSortPreference.ts
 create mode 100644 web/src/lib/sessionSortOrder.test.ts
 create mode 100644 web/src/lib/sessionSortOrder.ts

diff --git a/hub/src/sse/sseManager.test.ts b/hub/src/sse/sseManager.test.ts
index 209c278f8..8f582105a 100644
--- a/hub/src/sse/sseManager.test.ts
+++ b/hub/src/sse/sseManager.test.ts
@@ -118,4 +118,32 @@ describe('SSEManager namespace filtering', () => {
         expect(received).toHaveLength(1)
         expect(received[0]?.id).toBe('visible')
     })
+
+    it('broadcasts session sort preference updates to namespace even with session-scoped subscription', () => {
+        const manager = new SSEManager(0, new VisibilityTracker())
+        const received: SyncEvent[] = []
+
+        manager.subscribe({
+            id: 'alpha-session',
+            namespace: 'alpha',
+            all: false,
+            sessionId: 'session-1',
+            send: (event) => {
+                received.push(event)
+            },
+            sendHeartbeat: () => {}
+        })
+
+        manager.broadcast({
+            type: 'session-sort-preference-updated',
+            namespace: 'alpha',
+            data: {
+                userId: 1,
+                version: 2
+            }
+        })
+
+        expect(received).toHaveLength(1)
+        expect(received[0]?.type).toBe('session-sort-preference-updated')
+    })
 })
diff --git a/hub/src/sse/sseManager.ts b/hub/src/sse/sseManager.ts
index 2bd267b9d..69d9c1f44 100644
--- a/hub/src/sse/sseManager.ts
+++ b/hub/src/sse/sseManager.ts
@@ -163,6 +163,10 @@ export class SSEManager {
             return true
         }
 
+        if (event.type === 'session-sort-preference-updated') {
+            return true
+        }
+
         if (connection.all) {
             return true
         }
diff --git a/hub/src/store/index.ts b/hub/src/store/index.ts
index 94e596752..f8c8f0489 100644
--- a/hub/src/store/index.ts
+++ b/hub/src/store/index.ts
@@ -5,6 +5,7 @@ import { dirname } from 'node:path'
 import { MachineStore } from './machineStore'
 import { MessageStore } from './messageStore'
 import { PushStore } from './pushStore'
+import { SessionSortPreferenceStore } from './sessionSortPreferenceStore'
 import { SessionStore } from './sessionStore'
 import { UserStore } from './userStore'
 
@@ -13,22 +14,26 @@ export type {
     StoredMessage,
     StoredPushSubscription,
     StoredSession,
+    StoredSessionSortPreference,
     StoredUser,
+    SessionSortPreferenceUpdateResult,
     VersionedUpdateResult
 } from './types'
 export { MachineStore } from './machineStore'
 export { MessageStore } from './messageStore'
 export { PushStore } from './pushStore'
+export { SessionSortPreferenceStore } from './sessionSortPreferenceStore'
 export { SessionStore } from './sessionStore'
 export { UserStore } from './userStore'
 
-const SCHEMA_VERSION: number = 3
+const SCHEMA_VERSION: number = 4
 const REQUIRED_TABLES = [
     'sessions',
     'machines',
     'messages',
     'users',
-    'push_subscriptions'
+    'push_subscriptions',
+    'session_sort_preferences'
 ] as const
 
 export class Store {
@@ -40,6 +45,7 @@ export class Store {
     readonly messages: MessageStore
     readonly users: UserStore
     readonly push: PushStore
+    readonly sessionSortPreferences: SessionSortPreferenceStore
 
     constructor(dbPath: string) {
         this.dbPath = dbPath
@@ -81,6 +87,7 @@ export class Store {
         this.messages = new MessageStore(this.db)
         this.users = new UserStore(this.db)
         this.push = new PushStore(this.db)
+        this.sessionSortPreferences = new SessionSortPreferenceStore(this.db)
     }
 
     private initSchema(): void {
@@ -98,14 +105,38 @@ export class Store {
             return
         }
 
-        if (currentVersion === 1 && SCHEMA_VERSION === 2) {
+        if (currentVersion === 1 && SCHEMA_VERSION >= 2) {
             this.migrateFromV1ToV2()
+            if (SCHEMA_VERSION === 2) {
+                this.setUserVersion(SCHEMA_VERSION)
+                return
+            }
+
+            this.migrateFromV2ToV3()
+            if (SCHEMA_VERSION === 3) {
+                this.setUserVersion(SCHEMA_VERSION)
+                return
+            }
+
+            this.migrateFromV3ToV4()
             this.setUserVersion(SCHEMA_VERSION)
             return
         }
 
-        if (currentVersion === 2 && SCHEMA_VERSION === 3) {
+        if (currentVersion === 2 && SCHEMA_VERSION >= 3) {
             this.migrateFromV2ToV3()
+            if (SCHEMA_VERSION === 3) {
+                this.setUserVersion(SCHEMA_VERSION)
+                return
+            }
+
+            this.migrateFromV3ToV4()
+            this.setUserVersion(SCHEMA_VERSION)
+            return
+        }
+
+        if (currentVersion === 3 && SCHEMA_VERSION >= 4) {
+            this.migrateFromV3ToV4()
             this.setUserVersion(SCHEMA_VERSION)
             return
         }
@@ -187,6 +218,19 @@ export class Store {
                 UNIQUE(namespace, endpoint)
             );
             CREATE INDEX IF NOT EXISTS idx_push_subscriptions_namespace ON push_subscriptions(namespace);
+
+            CREATE TABLE IF NOT EXISTS session_sort_preferences (
+                user_id INTEGER NOT NULL,
+                namespace TEXT NOT NULL,
+                sort_mode TEXT NOT NULL DEFAULT 'auto',
+                manual_order TEXT NOT NULL DEFAULT '{"groupOrder":[],"sessionOrder":{}}',
+                version INTEGER NOT NULL DEFAULT 1,
+                created_at INTEGER NOT NULL,
+                updated_at INTEGER NOT NULL,
+                PRIMARY KEY (user_id, namespace)
+            );
+            CREATE INDEX IF NOT EXISTS idx_session_sort_preferences_namespace
+                ON session_sort_preferences(namespace);
         `)
     }
 
@@ -280,6 +324,23 @@ export class Store {
         return
     }
 
+    private migrateFromV3ToV4(): void {
+        this.db.exec(`
+            CREATE TABLE IF NOT EXISTS session_sort_preferences (
+                user_id INTEGER NOT NULL,
+                namespace TEXT NOT NULL,
+                sort_mode TEXT NOT NULL DEFAULT 'auto',
+                manual_order TEXT NOT NULL DEFAULT '{"groupOrder":[],"sessionOrder":{}}',
+                version INTEGER NOT NULL DEFAULT 1,
+                created_at INTEGER NOT NULL,
+                updated_at INTEGER NOT NULL,
+                PRIMARY KEY (user_id, namespace)
+            );
+            CREATE INDEX IF NOT EXISTS idx_session_sort_preferences_namespace
+                ON session_sort_preferences(namespace);
+        `)
+    }
+
     private getMachineColumnNames(): Set<string> {
         const rows = this.db.prepare('PRAGMA table_info(machines)').all() as Array<{ name: string }>
         return new Set(rows.map((row) => row.name))
diff --git a/hub/src/store/sessionSortPreferenceStore.test.ts b/hub/src/store/sessionSortPreferenceStore.test.ts
new file mode 100644
index 000000000..a889e0971
--- /dev/null
+++ b/hub/src/store/sessionSortPreferenceStore.test.ts
@@ -0,0 +1,88 @@
+import { describe, expect, it } from 'bun:test'
+
+import { Store } from './index'
+
+describe('SessionSortPreferenceStore', () => {
+    it('returns default preference when no row exists', () => {
+        const store = new Store(':memory:')
+
+        const preference = store.sessionSortPreferences.getByUser(1, 'alpha')
+
+        expect(preference.sortMode).toBe('auto')
+        expect(preference.manualOrder).toEqual({ groupOrder: [], sessionOrder: {} })
+        expect(preference.version).toBe(1)
+        expect(preference.updatedAt).toBe(0)
+    })
+
+    it('persists preference updates for user and namespace', () => {
+        const store = new Store(':memory:')
+
+        const result = store.sessionSortPreferences.upsertByUser(
+            1,
+            'alpha',
+            {
+                sortMode: 'manual',
+                manualOrder: {
+                    groupOrder: ['m1::/repo/app'],
+                    sessionOrder: {
+                        'm1::/repo/app': ['session-1']
+                    }
+                }
+            },
+            1
+        )
+
+        expect(result.result).toBe('success')
+        if (result.result !== 'success') {
+            return
+        }
+        expect(result.preference.version).toBe(2)
+
+        const stored = store.sessionSortPreferences.getByUser(1, 'alpha')
+        expect(stored.sortMode).toBe('manual')
+        expect(stored.manualOrder.groupOrder).toEqual(['m1::/repo/app'])
+        expect(stored.manualOrder.sessionOrder['m1::/repo/app']).toEqual(['session-1'])
+        expect(stored.version).toBe(2)
+        expect(stored.updatedAt).toBeGreaterThan(0)
+    })
+
+    it('returns version mismatch with latest preference', () => {
+        const store = new Store(':memory:')
+
+        store.sessionSortPreferences.upsertByUser(
+            1,
+            'alpha',
+            {
+                sortMode: 'manual',
+                manualOrder: {
+                    groupOrder: ['m1::/repo/app'],
+                    sessionOrder: {
+                        'm1::/repo/app': ['session-1']
+                    }
+                }
+            },
+            1
+        )
+
+        const mismatch = store.sessionSortPreferences.upsertByUser(
+            1,
+            'alpha',
+            {
+                sortMode: 'auto',
+                manualOrder: {
+                    groupOrder: [],
+                    sessionOrder: {}
+                }
+            },
+            1
+        )
+
+        expect(mismatch.result).toBe('version-mismatch')
+        if (mismatch.result !== 'version-mismatch') {
+            return
+        }
+
+        expect(mismatch.preference.sortMode).toBe('manual')
+        expect(mismatch.preference.version).toBe(2)
+    })
+})
diff --git a/hub/src/store/sessionSortPreferenceStore.ts b/hub/src/store/sessionSortPreferenceStore.ts
new file mode 100644
index 000000000..4786c4991
--- /dev/null
+++ b/hub/src/store/sessionSortPreferenceStore.ts
@@ -0,0 +1,29 @@
+import type { Database } from 'bun:sqlite'
+import type { SessionManualOrder, SessionSortMode } from '@hapi/protocol/types'
+
+import type { SessionSortPreferenceUpdateResult, StoredSessionSortPreference } from './types'
+import { getSessionSortPreferenceByUser, upsertSessionSortPreferenceByUser } from './sessionSortPreferences'
+
+export class SessionSortPreferenceStore {
+    private readonly db: Database
+
+    constructor(db: Database) {
+        this.db = db
+    }
+
+    getByUser(userId: number, namespace: string): StoredSessionSortPreference {
+        return getSessionSortPreferenceByUser(this.db, userId, namespace)
+    }
+
+    upsertByUser(
+        userId: number,
+        namespace: string,
+        preference: {
+            sortMode: SessionSortMode
+            manualOrder: SessionManualOrder
+        },
+        expectedVersion?: number
+    ): SessionSortPreferenceUpdateResult {
+        return upsertSessionSortPreferenceByUser(this.db, userId, namespace, preference, expectedVersion)
+    }
+}
diff --git a/hub/src/store/sessionSortPreferences.ts b/hub/src/store/sessionSortPreferences.ts
new file mode 100644
index 000000000..f93b725dc
--- /dev/null
+++ b/hub/src/store/sessionSortPreferences.ts
@@ -0,0 +1,145 @@
+import type { Database } from 'bun:sqlite'
+import { SessionManualOrderSchema, type SessionManualOrder, type SessionSortMode } from '@hapi/protocol/schemas'
+
+import type { SessionSortPreferenceUpdateResult, StoredSessionSortPreference } from './types'
+import { safeJsonParse } from './json'
+
+const EMPTY_MANUAL_ORDER: SessionManualOrder = {
+    groupOrder: [],
+    sessionOrder: {}
+}
+
+type DbSessionSortPreferenceRow = {
+    user_id: number
+    namespace: string
+    sort_mode: string
+    manual_order: string
+    version: number
+    created_at: number
+    updated_at: number
+}
+
+function normalizeSortMode(value: string): SessionSortMode {
+    return value === 'manual' ? 'manual' : 'auto'
+}
+
+function normalizeManualOrder(value: unknown): SessionManualOrder {
+    const parsed = SessionManualOrderSchema.safeParse(value)
+    if (parsed.success) {
+        return parsed.data
+    }
+
+    return {
+        groupOrder: [],
+        sessionOrder: {}
+    }
+}
+
+function toStoredSessionSortPreference(row: DbSessionSortPreferenceRow): StoredSessionSortPreference {
+    return {
+        userId: row.user_id,
+        namespace: row.namespace,
+        sortMode: normalizeSortMode(row.sort_mode),
+        manualOrder: normalizeManualOrder(safeJsonParse(row.manual_order)),
+        version: Math.max(1, row.version),
+        createdAt: row.created_at,
+        updatedAt: row.updated_at
+    }
+}
+
+function getDefaultSessionSortPreference(userId: number, namespace: string): StoredSessionSortPreference {
+    return {
+        userId,
+        namespace,
+        sortMode: 'auto',
+        manualOrder: EMPTY_MANUAL_ORDER,
+        version: 1,
+        createdAt: 0,
+        updatedAt: 0
+    }
+}
+
+export function getSessionSortPreferenceByUser(
+    db: Database,
+    userId: number,
+    namespace: string
+): StoredSessionSortPreference {
+    const row = db.prepare(
+        'SELECT * FROM session_sort_preferences WHERE user_id = ? AND namespace = ? LIMIT 1'
+    ).get(userId, namespace) as DbSessionSortPreferenceRow | undefined
+
+    if (!row) {
+        return getDefaultSessionSortPreference(userId, namespace)
+    }
+
+    return toStoredSessionSortPreference(row)
+}
+
+export function upsertSessionSortPreferenceByUser(
+    db: Database,
+    userId: number,
+    namespace: string,
+    preference: {
+        sortMode: SessionSortMode
+        manualOrder: SessionManualOrder
+    },
+    expectedVersion?: number
+): SessionSortPreferenceUpdateResult {
+    try {
+        const current = getSessionSortPreferenceByUser(db, userId, namespace)
+        if (expectedVersion !== undefined && expectedVersion !== current.version) {
+            return {
+                result: 'version-mismatch',
+                preference: current
+            }
+        }
+
+        const now = Date.now()
+        const nextVersion = current.version + 1
+        const manualOrderJson = JSON.stringify(preference.manualOrder)
+
+        db.prepare(`
+            INSERT INTO session_sort_preferences (
+                user_id,
+                namespace,
+                sort_mode,
+                manual_order,
+                version,
+                created_at,
+                updated_at
+            ) VALUES (
+                @user_id,
+                @namespace,
+                @sort_mode,
+                @manual_order,
+                @version,
+                @created_at,
+                @updated_at
+            )
+            ON CONFLICT(user_id, namespace)
+            DO UPDATE SET
+                sort_mode = excluded.sort_mode,
+                manual_order = excluded.manual_order,
+                version = excluded.version,
+                updated_at = excluded.updated_at
+        `).run({
+            user_id: userId,
+            namespace,
+            sort_mode: preference.sortMode,
+            manual_order: manualOrderJson,
+            version: nextVersion,
+            created_at: current.createdAt || now,
+            updated_at: now
+        })
+
+        const updated = getSessionSortPreferenceByUser(db, userId, namespace)
+        return {
+            result: 'success',
+            preference: updated
+        }
+    } catch {
+        return {
+            result: 'error'
+        }
+    }
+}
diff --git a/hub/src/store/types.ts b/hub/src/store/types.ts
index 9ef422ac3..fbbb4604b 100644
--- a/hub/src/store/types.ts
+++ b/hub/src/store/types.ts
@@ -1,3 +1,5 @@
+import type { SessionManualOrder, SessionSortMode } from '@hapi/protocol/types'
+
 export type StoredSession = {
     id: string
     tag: string | null
@@ -56,6 +58,21 @@ export type StoredPushSubscription = {
     createdAt: number
 }
 
+export type StoredSessionSortPreference = {
+    userId: number
+    namespace: string
+    sortMode: SessionSortMode
+    manualOrder: SessionManualOrder
+    version: number
+    createdAt: number
+    updatedAt: number
+}
+
+export type SessionSortPreferenceUpdateResult =
+    | { result: 'success'; preference: StoredSessionSortPreference }
+    | { result: 'version-mismatch'; preference: StoredSessionSortPreference }
+    | { result: 'error' }
+
 export type VersionedUpdateResult<T> =
     | { result: 'success'; version: number; value: T }
     | { result: 'version-mismatch'; version: number; value: T }
diff --git a/hub/src/sync/syncEngine.ts b/hub/src/sync/syncEngine.ts
index 1ab46e65f..45e9824e5 100644
--- a/hub/src/sync/syncEngine.ts
+++ b/hub/src/sync/syncEngine.ts
@@ -7,7 +7,16 @@
  * - No E2E encryption; data is stored as JSON in SQLite
  */
 
-import type { DecryptedMessage, ModelMode, PermissionMode, Session, SyncEvent } from '@hapi/protocol/types'
+import type {
+    DecryptedMessage,
+    ModelMode,
+    PermissionMode,
+    Session,
+    SessionManualOrder,
+    SessionSortMode,
+    SessionSortPreference,
+    SyncEvent
+} from '@hapi/protocol/types'
 import type { Server } from 'socket.io'
 import type { Store } from '../store'
 import type { RpcRegistry } from '../socket/rpcRegistry'
@@ -42,7 +51,13 @@ export type ResumeSessionResult =
     | { type: 'success'; sessionId: string }
     | { type: 'error'; message: string; code: 'session_not_found' | 'access_denied' | 'no_machine_online' | 'resume_unavailable' | 'resume_failed' }
 
+export type SetSessionSortPreferenceResult =
+    | { result: 'success'; preference: SessionSortPreference }
+    | { result: 'version-mismatch'; preference: SessionSortPreference }
+    | { result: 'error' }
+
 export class SyncEngine {
+    private readonly store: Store
     private readonly eventPublisher: EventPublisher
     private readonly sessionCache: SessionCache
     private readonly machineCache: MachineCache
@@ -56,6 +71,7 @@ export class SyncEngine {
         rpcRegistry: RpcRegistry,
         sseManager: SSEManager
     ) {
+        this.store = store
         this.eventPublisher = new EventPublisher(sseManager, (event) => this.resolveNamespace(event))
         this.sessionCache = new SessionCache(store, this.eventPublisher)
         this.machineCache = new MachineCache(store, this.eventPublisher)
@@ -97,6 +113,63 @@ export class SyncEngine {
         return this.sessionCache.getSessionsByNamespace(namespace)
     }
 
+    getSessionSortPreference(userId: number, namespace: string): SessionSortPreference {
+        const preference = this.store.sessionSortPreferences.getByUser(userId, namespace)
+        return {
+            sortMode: preference.sortMode,
+            manualOrder: preference.manualOrder,
+            version: preference.version,
+            updatedAt: preference.updatedAt
+        }
+    }
+
+    setSessionSortPreference(
+        userId: number,
+        namespace: string,
+        input: {
+            sortMode: SessionSortMode
+            manualOrder: SessionManualOrder
+            expectedVersion?: number
+        }
+    ): SetSessionSortPreferenceResult {
+        const result = this.store.sessionSortPreferences.upsertByUser(
+            userId,
+            namespace,
+            {
+                sortMode: input.sortMode,
+                manualOrder: input.manualOrder
+            },
+            input.expectedVersion
+        )
+
+        if (result.result === 'error') {
+            return { result: 'error' }
+        }
+
+        const preference: SessionSortPreference = {
+            sortMode: result.preference.sortMode,
+            manualOrder: result.preference.manualOrder,
+            version: result.preference.version,
+            updatedAt: result.preference.updatedAt
+        }
+
+        if (result.result === 'success') {
+            this.eventPublisher.emit({
+                type: 'session-sort-preference-updated',
+                namespace,
+                data: {
+                    userId,
+                    version: preference.version
+                }
+            })
+        }
+
+        return {
+            result: result.result,
+            preference
+        }
+    }
+
     getSession(sessionId: string): Session | undefined {
         return this.sessionCache.getSession(sessionId) ?? this.sessionCache.refreshSession(sessionId) ?? undefined
     }
diff --git a/hub/src/web/routes/preferences.test.ts b/hub/src/web/routes/preferences.test.ts
new file mode 100644
index 000000000..b4ce14b13
--- /dev/null
+++ b/hub/src/web/routes/preferences.test.ts
@@ -0,0 +1,217 @@
+import { describe, expect, it } from 'bun:test'
+import { Hono } from 'hono'
+
+import type { SetSessionSortPreferenceResult, SyncEngine } from '../../sync/syncEngine'
+import type { WebAppEnv } from '../middleware/auth'
+import { createPreferencesRoutes } from './preferences'
+
+function createApp(options: {
+    userId: number
+    namespace: string
+    engine: SyncEngine
+}): Hono<WebAppEnv> {
+    const app = new Hono<WebAppEnv>()
+
+    app.use('/api/*', async (c, next) => {
+        c.set('userId', options.userId)
+        c.set('namespace', options.namespace)
+        await next()
+    })
+
+    app.route('/api', createPreferencesRoutes(() => options.engine))
+    return app
+}
+
+describe('preferences routes', () => {
+    it('GET returns sort preference for authenticated user and namespace', async () => {
+        const captured: { userId?: number; namespace?: string } = {}
+        const engine = {
+            getSessionSortPreference: (userId: number, namespace: string) => {
+                captured.userId = userId
+                captured.namespace = namespace
+                return {
+                    sortMode: 'auto',
+                    manualOrder: {
+                        groupOrder: [],
+                        sessionOrder: {}
+                    },
+                    version: 1,
+                    updatedAt: 0
+                }
+            }
+        } as unknown as SyncEngine
+
+        const app = createApp({ userId: 7, namespace: 'alpha', engine })
+        const response = await app.request('http://localhost/api/preferences/session-sort')
+
+        expect(response.status).toBe(200)
+        const json = await response.json() as {
+            preference: {
+                sortMode: string
+                version: number
+            }
+        }
+        expect(json.preference.sortMode).toBe('auto')
+        expect(json.preference.version).toBe(1)
+        expect(captured).toEqual({ userId: 7, namespace: 'alpha' })
+    })
+
+    it('PUT persists preference and returns updated snapshot', async () => {
+        const engine = {
+            setSessionSortPreference: () => ({
+                result: 'success',
+                preference: {
+                    sortMode: 'manual',
+                    manualOrder: {
+                        groupOrder: ['m1::/repo/app'],
+                        sessionOrder: {
+                            'm1::/repo/app': ['session-1']
+                        }
+                    },
+                    version: 2,
+                    updatedAt: 100
+                }
+            } satisfies SetSessionSortPreferenceResult)
+        } as unknown as SyncEngine
+
+        const app = createApp({ userId: 9, namespace: 'beta', engine })
+
+        const response = await app.request('http://localhost/api/preferences/session-sort', {
+            method: 'PUT',
+            headers: {
+                'content-type': 'application/json'
+            },
+            body: JSON.stringify({
+                sortMode: 'manual',
+                manualOrder: {
+                    groupOrder: ['m1::/repo/app'],
+                    sessionOrder: {
+                        'm1::/repo/app': ['session-1']
+                    }
+                },
+                expectedVersion: 1
+            })
+        })
+
+        expect(response.status).toBe(200)
+        const json = await response.json() as {
+            preference: {
+                sortMode: string
+                version: number
+            }
+        }
+        expect(json.preference.sortMode).toBe('manual')
+        expect(json.preference.version).toBe(2)
+    })
+
+    it('PUT returns 409 and latest preference on version mismatch', async () => {
+        const engine = {
+            setSessionSortPreference: () => ({
+                result: 'version-mismatch',
+                preference: {
+                    sortMode: 'manual',
+                    manualOrder: {
+                        groupOrder: ['m1::/repo/app'],
+                        sessionOrder: {
+                            'm1::/repo/app': ['session-1']
+                        }
+                    },
+                    version: 3,
+                    updatedAt: 200
+                }
+            } satisfies SetSessionSortPreferenceResult)
+        } as unknown as SyncEngine
+
+        const app = createApp({ userId: 1, namespace: 'alpha', engine })
+
+        const response = await app.request('http://localhost/api/preferences/session-sort', {
+            method: 'PUT',
+            headers: {
+                'content-type': 'application/json'
+            },
+            body: JSON.stringify({
+                sortMode: 'manual',
+                manualOrder: {
+                    groupOrder: [],
+                    sessionOrder: {}
+                },
+                expectedVersion: 1
+            })
+        })
+
+        expect(response.status).toBe(409)
+        const json = await response.json() as {
+            error: string
+            preference: {
+                version: number
+            }
+        }
+        expect(json.error).toBe('version_mismatch')
+        expect(json.preference.version).toBe(3)
+    })
+
+    it('PUT validates body', async () => {
+        const engine = {
+            setSessionSortPreference: () => ({ result: 'error' })
+        } as unknown as SyncEngine
+        const app = createApp({ userId: 1, namespace: 'alpha', engine })
+
+        const response = await app.request('http://localhost/api/preferences/session-sort', {
+            method: 'PUT',
+            headers: {
+                'content-type': 'application/json'
+            },
+            body: JSON.stringify({
+                sortMode: 'manual',
+                expectedVersion: 0
+            })
+        })
+
+        expect(response.status).toBe(400)
+    })
+
+    it('PUT uses auth scope from middleware', async () => {
+        const captured: {
+            userId?: number
+            namespace?: string
+        } = {}
+        const engine = {
+            setSessionSortPreference: (userId: number, namespace: string) => {
+                captured.userId = userId
+                captured.namespace = namespace
+                return {
+                    result: 'success',
+                    preference: {
+                        sortMode: 'auto',
+                        manualOrder: {
+                            groupOrder: [],
+                            sessionOrder: {}
+                        },
+                        version: 2,
+                        updatedAt: 0
+                    }
+                } satisfies SetSessionSortPreferenceResult
+            }
+        } as unknown as SyncEngine
+
+        const app = createApp({ userId: 99, namespace: 'team-1', engine })
+
+        const response = await app.request('http://localhost/api/preferences/session-sort', {
+            method: 'PUT',
+            headers: {
+                'content-type': 'application/json'
+            },
+            body: JSON.stringify({
+                sortMode: 'auto',
+                manualOrder: {
+                    groupOrder: [],
+                    sessionOrder: {}
+                },
+                expectedVersion: 1
+            })
+        })
+
+        expect(response.status).toBe(200)
+        expect(captured).toEqual({ userId: 99, namespace: 'team-1' })
+    })
+})
diff --git a/hub/src/web/routes/preferences.ts b/hub/src/web/routes/preferences.ts
new file mode 100644
index 000000000..672654ccf
--- /dev/null
+++ b/hub/src/web/routes/preferences.ts
@@ -0,0 +1,59 @@
+import { SessionManualOrderSchema, SessionSortModeSchema } from '@hapi/protocol/schemas'
+import { Hono } from 'hono'
+import { z } from 'zod'
+
+import type { SyncEngine } from '../../sync/syncEngine'
+import type { WebAppEnv } from '../middleware/auth'
+import { requireSyncEngine } from './guards'
+
+const setSessionSortPreferenceSchema = z.object({
+    sortMode: SessionSortModeSchema,
+    manualOrder: SessionManualOrderSchema,
+    expectedVersion: z.number().int().positive().optional()
+})
+
+export function createPreferencesRoutes(getSyncEngine: () => SyncEngine | null): Hono<WebAppEnv> {
+    const app = new Hono<WebAppEnv>()
+
+    app.get('/preferences/session-sort', (c) => {
+        const engine = requireSyncEngine(c, getSyncEngine)
+        if (engine instanceof Response) {
+            return engine
+        }
+
+        const userId = c.get('userId')
+        const namespace = c.get('namespace')
+        const preference = engine.getSessionSortPreference(userId, namespace)
+
+        return c.json({ preference })
+    })
+
+    app.put('/preferences/session-sort', async (c) => {
+        const engine = requireSyncEngine(c, getSyncEngine)
+        if (engine instanceof Response) {
+            return engine
+        }
+
+        const body = await c.req.json().catch(() => null)
+        const parsed = setSessionSortPreferenceSchema.safeParse(body)
+        if (!parsed.success) {
+            return c.json({ error: 'Invalid body' }, 400)
+        }
+
+        const userId = c.get('userId')
+        const namespace = c.get('namespace')
+        const result = engine.setSessionSortPreference(userId, namespace, parsed.data)
+
+        if (result.result === 'error') {
+            return c.json({ error: 'Failed to save session sort preference' }, 500)
+        }
+
+        if (result.result === 'version-mismatch') {
+            return c.json({ error: 'version_mismatch', preference: result.preference }, 409)
+        }
+
+        return c.json({ preference: result.preference })
+    })
+
+    return app
+}
diff --git a/hub/src/web/server.ts b/hub/src/web/server.ts
index 08800fc72..4f5137b12 100644
--- a/hub/src/web/server.ts
+++ b/hub/src/web/server.ts
@@ -18,6 +18,7 @@ import { createMachinesRoutes } from './routes/machines'
 import { createGitRoutes } from './routes/git'
 import { createCliRoutes } from './routes/cli'
 import { createPushRoutes } from './routes/push'
+import { createPreferencesRoutes } from './routes/preferences'
 import { createVoiceRoutes } from './routes/voice'
 import type { SSEManager } from '../sse/sseManager'
 import type { VisibilityTracker } from '../visibility/visibilityTracker'
@@ -77,7 +78,7 @@ function createWebApp(options: {
     const corsOriginOption = corsOrigins.includes('*') ? '*' : corsOrigins
     const corsMiddleware = cors({
         origin: corsOriginOption,
-        allowMethods: ['GET', 'POST', 'DELETE', 'OPTIONS'],
+        allowMethods: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS'],
         allowHeaders: ['authorization', 'content-type']
     })
     app.use('/api/*', corsMiddleware)
@@ -96,6 +97,7 @@ function createWebApp(options: {
     app.route('/api', createMachinesRoutes(options.getSyncEngine))
     app.route('/api', createGitRoutes(options.getSyncEngine))
     app.route('/api', createPushRoutes(options.store, options.vapidPublicKey))
+    app.route('/api', createPreferencesRoutes(options.getSyncEngine))
     app.route('/api', createVoiceRoutes())
 
     // Skip static serving in relay mode, show helpful message on root
diff --git a/shared/src/schemas.ts b/shared/src/schemas.ts
index 30e96dc4b..9efe85b5f 100644
--- a/shared/src/schemas.ts
+++ b/shared/src/schemas.ts
@@ -3,6 +3,25 @@ import { MODEL_MODES, PERMISSION_MODES } from './modes'
 
 export const PermissionModeSchema = z.enum(PERMISSION_MODES)
 export const ModelModeSchema = z.enum(MODEL_MODES)
+export const SessionSortModeSchema = z.enum(['auto', 'manual'])
+
+export type SessionSortMode = z.infer<typeof SessionSortModeSchema>
+
+export const SessionManualOrderSchema = z.object({
+    groupOrder: z.array(z.string()),
+    sessionOrder: z.record(z.string(), z.array(z.string()))
+}).strict()
+
+export type SessionManualOrder = z.infer<typeof SessionManualOrderSchema>
+
+export const SessionSortPreferenceSchema = z.object({
+    sortMode: SessionSortModeSchema,
+    manualOrder: SessionManualOrderSchema,
+    version: z.number().int().positive(),
+    updatedAt: z.number().int().nonnegative()
+}).strict()
+
+export type SessionSortPreference = z.infer<typeof SessionSortPreferenceSchema>
 
 const MetadataSummarySchema = z.object({
     text: z.string(),
@@ -187,6 +206,13 @@ export const SyncEventSchema = z.discriminatedUnion('type', [
             status: z.string(),
             subscriptionId: z.string().optional()
         }).optional()
+    }),
+    SessionEventBaseSchema.extend({
+        type: z.literal('session-sort-preference-updated'),
+        data: z.object({
+            userId: z.number().int().nonnegative(),
+            version: z.number().int().positive()
+        })
     })
 ])
 
diff --git a/shared/src/types.ts b/shared/src/types.ts
index 1a885f1ae..b69d96357 100644
--- a/shared/src/types.ts
+++ b/shared/src/types.ts
@@ -5,6 +5,9 @@ export type {
     AttachmentMetadata,
     DecryptedMessage,
     Metadata,
+    SessionManualOrder,
+    SessionSortMode,
+    SessionSortPreference,
     Session,
     SyncEvent,
     TodoItem,
diff --git a/web/src/App.tsx b/web/src/App.tsx
index 3d4984056..053466677 100644
--- a/web/src/App.tsx
+++ b/web/src/App.tsx
@@ -196,6 +196,7 @@ function AppInner() {
             startSync()
         }
         const invalidations = [
+            queryClient.invalidateQueries({ queryKey: queryKeys.sessionSortPreference }),
             queryClient.invalidateQueries({ queryKey: queryKeys.sessions }),
             ...(selectedSessionId ? [
                 queryClient.invalidateQueries({ queryKey: queryKeys.session(selectedSessionId) })
diff --git a/web/src/api/client.ts b/web/src/api/client.ts
index 347e78f18..44a9ee375 100644
--- a/web/src/api/client.ts
+++ b/web/src/api/client.ts
@@ -14,6 +14,9 @@ import type {
     PushSubscriptionPayload,
     PushUnsubscribePayload,
     PushVapidPublicKeyResponse,
+    SessionSortPreferenceResponse,
+    SetSessionSortPreferencePayload,
+    SetSessionSortPreferenceResult,
     SlashCommandsResponse,
     SkillsResponse,
     SpawnResponse,
@@ -116,7 +119,9 @@ export class ApiClient {
 
         if (!res.ok) {
             const body = await res.text().catch(() => '')
-            throw new Error(`HTTP ${res.status} ${res.statusText}: ${body}`)
+            const code = parseErrorCode(body)
+            const detail = body ? `: ${body}` : ''
+            throw new ApiError(`HTTP ${res.status} ${res.statusText}${detail}`, res.status, code, body || undefined)
         }
 
         return await res.json() as T
@@ -160,6 +165,42 @@ export class ApiClient {
         return await this.request<SessionsResponse>('/api/sessions')
     }
 
+    async getSessionSortPreference(): Promise<SessionSortPreferenceResponse> {
+        return await this.request<SessionSortPreferenceResponse>('/api/preferences/session-sort')
+    }
+
+    async setSessionSortPreference(
+        payload: SetSessionSortPreferencePayload
+    ): Promise<SetSessionSortPreferenceResult> {
+        try {
+            const response = await this.request<SessionSortPreferenceResponse>('/api/preferences/session-sort', {
+                method: 'PUT',
+                body: JSON.stringify(payload)
+            })
+            return {
+                status: 'success',
+                preference: response.preference
+            }
+        } catch (error) {
+            if (!(error instanceof ApiError) || error.status !== 409 || !error.body) {
+                throw error
+            }
+
+            try {
+                const parsed = JSON.parse(error.body) as { error?: string; preference?: SessionSortPreferenceResponse['preference'] }
+                if (parsed.error === 'version_mismatch' && parsed.preference) {
+                    return {
+                        status: 'version-mismatch',
+                        preference: parsed.preference
+                    }
+                }
+            } catch {
+            }
+
+            throw error
+        }
+    }
+
     async getPushVapidPublicKey(): Promise<PushVapidPublicKeyResponse> {
         return await this.request<PushVapidPublicKeyResponse>('/api/push/vapid-public-key')
     }
diff --git a/web/src/components/GroupActionMenu.tsx b/web/src/components/GroupActionMenu.tsx
new file mode 100644
index 000000000..33c8e5f99
--- /dev/null
+++ b/web/src/components/GroupActionMenu.tsx
@@ -0,0 +1,227 @@
+import {
+    useCallback,
+    useEffect,
+    useId,
+    useLayoutEffect,
+    useRef,
+    useState,
+    type CSSProperties
+} from 'react'
+
+import { useTranslation } from '@/lib/use-translation'
+
+type GroupActionMenuProps = {
+    isOpen: boolean
+    onClose: () => void
+    onMoveUp: () => void
+    onMoveDown: () => void
+    canMoveUp: boolean
+    canMoveDown: boolean
+    anchorPoint: { x: number; y: number }
+    menuId?: string
+}
+
+type MenuPosition = {
+    top: number
+    left: number
+    transformOrigin: string
+}
+
+function ArrowUpIcon(props: { className?: string }) {
+    return (
+        <svg
+            xmlns="http://www.w3.org/2000/svg"
+            width="18"
+            height="18"
+            viewBox="0 0 24 24"
+            fill="none"
+            stroke="currentColor"
+            strokeWidth="2"
+            strokeLinecap="round"
+            strokeLinejoin="round"
+            className={props.className}
+        >
+            <path d="m5 12 7-7 7 7" />
+            <path d="M12 19V6" />
+        </svg>
+    )
+}
+
+function ArrowDownIcon(props: { className?: string }) {
+    return (
+        <svg
+            xmlns="http://www.w3.org/2000/svg"
+            width="18"
+            height="18"
+            viewBox="0 0 24 24"
+            fill="none"
+            stroke="currentColor"
+            strokeWidth="2"
+            strokeLinecap="round"
+            strokeLinejoin="round"
+            className={props.className}
+        >
+            <path d="m19 12-7 7-7-7" />
+            <path d="M12 5v13" />
+        </svg>
+    )
+}
+
+export function GroupActionMenu(props: GroupActionMenuProps) {
+    const { t } = useTranslation()
+    const {
+        isOpen,
+        onClose,
+        onMoveUp,
+        onMoveDown,
+        canMoveUp,
+        canMoveDown,
+        anchorPoint,
+        menuId
+    } = props
+    const menuRef = useRef<HTMLDivElement | null>(null)
+    const [menuPosition, setMenuPosition] = useState<MenuPosition | null>(null)
+    const internalId = useId()
+    const resolvedMenuId = menuId ?? `group-action-menu-${internalId}`
+    const headingId = `${resolvedMenuId}-heading`
+
+    const updatePosition = useCallback(() => {
+        const menuEl = menuRef.current
+        if (!menuEl) return
+
+        const menuRect = menuEl.getBoundingClientRect()
+        const viewportWidth = window.innerWidth
+        const viewportHeight = window.innerHeight
+        const padding = 8
+        const gap = 8
+
+        const spaceBelow = viewportHeight - anchorPoint.y
+        const spaceAbove = anchorPoint.y
+        const openAbove = spaceBelow < menuRect.height + gap && spaceAbove > spaceBelow
+
+        let top = openAbove ? anchorPoint.y - menuRect.height - gap : anchorPoint.y + gap
+        let left = anchorPoint.x - menuRect.width / 2
+        const transformOrigin = openAbove ? 'bottom center' : 'top center'
+
+        top = Math.min(Math.max(top, padding), viewportHeight - menuRect.height - padding)
+        left = Math.min(Math.max(left, padding), viewportWidth - menuRect.width - padding)
+
+        setMenuPosition({ top, left, transformOrigin })
+    }, [anchorPoint])
+
+    useLayoutEffect(() => {
+        if (!isOpen) return
+        updatePosition()
+    }, [isOpen, updatePosition])
+
+    useEffect(() => {
+        if (!isOpen) {
+            setMenuPosition(null)
+            return
+        }
+
+        const handlePointerDown = (event: PointerEvent) => {
+            const target = event.target as Node
+            if (menuRef.current?.contains(target)) return
+            onClose()
+        }
+
+        const handleKeyDown = (event: KeyboardEvent) => {
+            if (event.key === 'Escape') {
+                onClose()
+            }
+        }
+
+        const handleReflow = () => {
+            updatePosition()
+        }
+
+        document.addEventListener('pointerdown', handlePointerDown)
+        document.addEventListener('keydown', handleKeyDown)
+        window.addEventListener('resize', handleReflow)
+        window.addEventListener('scroll', handleReflow, true)
+
+        return () => {
+            document.removeEventListener('pointerdown', handlePointerDown)
+            document.removeEventListener('keydown', handleKeyDown)
+            window.removeEventListener('resize', handleReflow)
+            window.removeEventListener('scroll', handleReflow, true)
+        }
+    }, [isOpen, onClose, updatePosition])
+
+    useEffect(() => {
+        if (!isOpen) return
+
+        const frame = window.requestAnimationFrame(() => {
+            const firstItem = menuRef.current?.querySelector<HTMLElement>('[role="menuitem"]')
+            firstItem?.focus()
+        })
+
+        return () => window.cancelAnimationFrame(frame)
+    }, [isOpen])
+
+    if (!isOpen) return null
+
+    const menuStyle: CSSProperties | undefined = menuPosition
+        ? {
+            top: menuPosition.top,
+            left: menuPosition.left,
+            transformOrigin: menuPosition.transformOrigin
+        }
+        : undefined
+
+    const baseItemClassName =
+        'flex w-full items-center gap-3 rounded-md px-3 py-2 text-left text-base transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--app-link)]'
+
+    return (
+        <div
+            ref={menuRef}
+            className="fixed z-50 min-w-[200px] rounded-lg border border-[var(--app-border)] bg-[var(--app-bg)] p-1 shadow-lg animate-menu-pop"
+            style={menuStyle}
+        >
+            <div
+                id={headingId}
+                className="px-3 py-1.5 text-[10px] font-semibold uppercase tracking-wide text-[var(--app-hint)]"
+            >
+                {t('group.more')}
+            </div>
+            <div
+                id={resolvedMenuId}
+                role="menu"
+                aria-labelledby={headingId}
+                className="flex flex-col gap-1"
+            >
+                <button
+                    type="button"
+                    role="menuitem"
+                    className={`${baseItemClassName} ${canMoveUp ? 'hover:bg-[var(--app-subtle-bg)]' : 'opacity-40 cursor-default'}`}
+                    onClick={() => {
+                        if (!canMoveUp) return
+                        onClose()
+                        onMoveUp()
+                    }}
+                    disabled={!canMoveUp}
+                    aria-disabled={!canMoveUp}
+                >
+                    <ArrowUpIcon className="text-[var(--app-hint)]" />
+                    {t('group.action.moveUp')}
+                </button>
+                <button
+                    type="button"
+                    role="menuitem"
+                    className={`${baseItemClassName} ${canMoveDown ? 'hover:bg-[var(--app-subtle-bg)]' : 'opacity-40 cursor-default'}`}
+                    onClick={() => {
+                        if (!canMoveDown) return
+                        onClose()
+                        onMoveDown()
+                    }}
+                    disabled={!canMoveDown}
+                    aria-disabled={!canMoveDown}
+                >
+                    <ArrowDownIcon className="text-[var(--app-hint)]" />
+                    {t('group.action.moveDown')}
+                </button>
+            </div>
+        </div>
+    )
+}
diff --git a/web/src/components/SessionActionMenu.tsx b/web/src/components/SessionActionMenu.tsx
index 88d6ab97c..87b01f19a 100644
--- a/web/src/components/SessionActionMenu.tsx
+++ b/web/src/components/SessionActionMenu.tsx
@@ -13,6 +13,11 @@ type SessionActionMenuProps = {
     isOpen: boolean
     onClose: () => void
     sessionActive: boolean
+    manualMode?: boolean
+    onMoveUp?: () => void
+    onMoveDown?: () => void
+    canMoveUp?: boolean
+    canMoveDown?: boolean
     onRename: () => void
     onArchive: () => void
     onDelete: () => void
@@ -84,6 +89,46 @@ function TrashIcon(props: { className?: string }) {
     )
 }
 
+function ArrowUpIcon(props: { className?: string }) {
+    return (
+        <svg
+            xmlns="http://www.w3.org/2000/svg"
+            width="18"
+            height="18"
+            viewBox="0 0 24 24"
+            fill="none"
+            stroke="currentColor"
+            strokeWidth="2"
+            strokeLinecap="round"
+            strokeLinejoin="round"
+            className={props.className}
+        >
+            <path d="m5 12 7-7 7 7" />
+            <path d="M12 19V6" />
+        </svg>
+    )
+}
+
+function ArrowDownIcon(props: { className?: string }) {
+    return (
+        <svg
+            xmlns="http://www.w3.org/2000/svg"
+            width="18"
+            height="18"
+            viewBox="0 0 24 24"
+            fill="none"
+            stroke="currentColor"
+            strokeWidth="2"
+            strokeLinecap="round"
+            strokeLinejoin="round"
+            className={props.className}
+        >
+            <path d="m19 12-7 7-7-7" />
+            <path d="M12 5v13" />
+        </svg>
+    )
+}
+
 type MenuPosition = {
     top: number
     left: number
@@ -96,6 +141,11 @@ export function SessionActionMenu(props: SessionActionMenuProps) {
         isOpen,
         onClose,
         sessionActive,
+        manualMode = false,
+        onMoveUp,
+        onMoveDown,
+        canMoveUp = false,
+        canMoveDown = false,
         onRename,
         onArchive,
         onDelete,
@@ -123,6 +173,22 @@ export function SessionActionMenu(props: SessionActionMenuProps) {
         onDelete()
     }
 
+    const handleMoveUp = () => {
+        if (!canMoveUp || !onMoveUp) {
+            return
+        }
+        onClose()
+        onMoveUp()
+    }
+
+    const handleMoveDown = () => {
+        if (!canMoveDown || !onMoveDown) {
+            return
+        }
+        onClose()
+        onMoveDown()
+    }
+
     const updatePosition = useCallback(() => {
         const menuEl = menuRef.current
         if (!menuEl) return
@@ -229,6 +295,34 @@ export function SessionActionMenu(props: SessionActionMenuProps) {
                 aria-labelledby={headingId}
                 className="flex flex-col gap-1"
             >
+                {manualMode ? (
+                    <>
+                        <button
+                            type="button"
+                            role="menuitem"
+                            className={`${baseItemClassName} ${canMoveUp ? 'hover:bg-[var(--app-subtle-bg)]' : 'opacity-40 cursor-default'}`}
+                            onClick={handleMoveUp}
+                            disabled={!canMoveUp}
+                            aria-disabled={!canMoveUp}
+                        >
+                            <ArrowUpIcon className="text-[var(--app-hint)]" />
+                            {t('session.action.moveUp')}
+                        </button>
+                        <button
+                            type="button"
+                            role="menuitem"
+                            className={`${baseItemClassName} ${canMoveDown ? 'hover:bg-[var(--app-subtle-bg)]' : 'opacity-40 cursor-default'}`}
+                            onClick={handleMoveDown}
+                            disabled={!canMoveDown}
+                            aria-disabled={!canMoveDown}
+                        >
+                            <ArrowDownIcon className="text-[var(--app-hint)]" />
+                            {t('session.action.moveDown')}
+                        </button>
+                        <div className="h-px bg-[var(--app-divider)] mx-2" />
+                    </>
+                ) : null}
+
                 <button
                     type="button"
                     role="menuitem"
diff --git a/web/src/components/SessionList.test.tsx b/web/src/components/SessionList.test.tsx
index 6660eba92..9a7251147 100644
--- a/web/src/components/SessionList.test.tsx
+++ b/web/src/components/SessionList.test.tsx
@@ -3,6 +3,8 @@ import { render, screen } from '@testing-library/react'
 import type { SessionSummary } from '@/types/api'
 import { I18nProvider } from '@/lib/i18n-context'
 import { SessionList } from './SessionList'
+import { useSessionSortPreference } from '@/hooks/queries/useSessionSortPreference'
+import { useSessionSortPreferenceMutation } from '@/hooks/mutations/useSessionSortPreference'
 
 vi.mock('@/hooks/useLongPress', () => ({
     useLongPress: ({ onClick }: { onClick: () => void }) => ({ onClick })
@@ -21,6 +23,27 @@ vi.mock('@/hooks/mutations/useSessionActions', () => ({
     })
 }))
 
+vi.mock('@/hooks/queries/useSessionSortPreference', () => ({
+    useSessionSortPreference: vi.fn(() => ({
+        preference: {
+            sortMode: 'auto',
+            manualOrder: {
+                groupOrder: [],
+                sessionOrder: {}
+            },
+            version: 1,
+            updatedAt: 0
+        }
+    }))
+}))
+
+vi.mock('@/hooks/mutations/useSessionSortPreference', () => ({
+    useSessionSortPreferenceMutation: vi.fn(() => ({
+        setSessionSortPreference: vi.fn(),
+        isPending: false
+    }))
+}))
+
 vi.mock('@/components/SessionActionMenu', () => ({
     SessionActionMenu: () => null
 }))
@@ -55,7 +78,11 @@ function makeSession(overrides: Partial<SessionSummary>): SessionSummary {
     }
 }
 
-function renderList(sessions: SessionSummary[], machineLabelsById?: Record<string, string>) {
+function renderList(
+    sessions: SessionSummary[],
+    machineLabelsById?: Record<string, string>,
+    options?: { renderHeader?: boolean }
+) {
     return render(
         <I18nProvider>
             <SessionList
@@ -64,7 +91,7 @@ function renderList(sessions: SessionSummary[], machineLabelsById?: Record<strin
                 onNewSession={vi.fn()}
                 onRefresh={vi.fn()}
                 isLoading={false}
-                renderHeader={false}
+                renderHeader={options?.renderHeader ?? false}
                 api={null}
                 machineLabelsById={machineLabelsById}
             />
@@ -73,6 +100,12 @@ function renderList(sessions: SessionSummary[], machineLabelsById?: Record<strin
 }
 
 describe('SessionList', () => {
+    it('shows sort toggle title in header', () => {
+        renderList([], {}, { renderHeader: true })
+
+        expect(screen.getByTitle('Sort: automatic')).toBeInTheDocument()
+    })
+
     it('groups sessions by machine and directory', () => {
         const sessions = [
             makeSession({
@@ -114,4 +147,58 @@ describe('SessionList', () => {
         expect(codexRow).toBeTruthy()
         expect(codexRow?.textContent?.toLowerCase()).not.toContain('plan mode')
     })
+
+    it('renders sessions using backend manual order', () => {
+        vi.mocked(useSessionSortPreference).mockReturnValue({
+            preference: {
+                sortMode: 'manual',
+                manualOrder: {
+                    groupOrder: ['m1::/repo/app'],
+                    sessionOrder: {
+                        'm1::/repo/app': ['s2', 's1']
+                    }
+                },
+                version: 3,
+                updatedAt: 100
+            },
+            isLoading: false,
+            error: null,
+            refetch: vi.fn()
+        })
+        vi.mocked(useSessionSortPreferenceMutation).mockReturnValue({
+            setSessionSortPreference: vi.fn(),
+            isPending: false
+        })
+
+        const sessions = [
+            makeSession({
+                id: 's1',
+                metadata: {
+                    path: '/repo/app',
+                    machineId: 'm1',
+                    flavor: 'claude',
+                    name: 'Alpha',
+                    summary: { text: 'Alpha summary' }
+                },
+                updatedAt: 200
+            }),
+            makeSession({
+                id: 's2',
+                metadata: {
+                    path: '/repo/app',
+                    machineId: 'm1',
+                    flavor: 'claude',
+                    name: 'Beta',
+                    summary: { text: 'Beta summary' }
+                },
+                updatedAt: 100
+            })
+        ]
+
+        const { container } = renderList(sessions, { m1: 'Laptop' })
+
+        const items = Array.from(container.querySelectorAll<HTMLButtonElement>('.session-list-item'))
+        expect(items[0]?.textContent).toContain('Beta')
+        expect(items[1]?.textContent).toContain('Alpha')
+    })
 })
diff --git a/web/src/components/SessionList.tsx b/web/src/components/SessionList.tsx
index 428e5d47b..58072395e 100644
--- a/web/src/components/SessionList.tsx
+++ b/web/src/components/SessionList.tsx
@@ -5,9 +5,19 @@ import { getPermissionModeLabel, getPermissionModeTone, isPermissionModeAllowedF
 import { useLongPress } from '@/hooks/useLongPress'
 import { usePlatform } from '@/hooks/usePlatform'
 import { useSessionActions } from '@/hooks/mutations/useSessionActions'
+import { useSessionSortPreferenceMutation } from '@/hooks/mutations/useSessionSortPreference'
+import { useSessionSortPreference } from '@/hooks/queries/useSessionSortPreference'
 import { SessionActionMenu } from '@/components/SessionActionMenu'
+import { GroupActionMenu } from '@/components/GroupActionMenu'
 import { RenameSessionDialog } from '@/components/RenameSessionDialog'
 import { ConfirmDialog } from '@/components/ui/ConfirmDialog'
+import {
+    applyManualOrder,
+    moveGroup,
+    moveSession,
+    reconcileManualOrder,
+    snapshotManualOrder
+} from '@/lib/sessionSortOrder'
 import { useTranslation } from '@/lib/use-translation'
 import { getFlavorTextClass, PERMISSION_TONE_TEXT } from '@/lib/agentFlavorUtils'
 
@@ -29,7 +39,7 @@ function getGroupDisplayName(directory: string): string {
     return `${parts[parts.length - 2]}/${parts[parts.length - 1]}`
 }
 
-function groupSessionsByDirectory(sessions: SessionSummary[]): SessionGroup[] {
+export function groupSessionsByDirectory(sessions: SessionSummary[]): SessionGroup[] {
     const groups = new Map<string, { directory: string; machineId: string | null; sessions: SessionSummary[] }>()
 
     sessions.forEach(session => {
@@ -99,6 +109,51 @@ function PlusIcon(props: { className?: string }) {
     )
 }
 
+function SortIcon(props: { className?: string }) {
+    return (
+        <svg
+            xmlns="http://www.w3.org/2000/svg"
+            width="24"
+            height="24"
+            viewBox="0 0 24 24"
+            fill="none"
+            stroke="currentColor"
+            strokeWidth="2"
+            strokeLinecap="round"
+            strokeLinejoin="round"
+            className={props.className}
+        >
+            <path d="M11 5h10" />
+            <path d="M11 9h7" />
+            <path d="M11 13h4" />
+            <path d="m3 17 3 3 3-3" />
+            <path d="M6 4v16" />
+        </svg>
+    )
+}
+
+function PinIcon(props: { className?: string }) {
+    return (
+        <svg
+            xmlns="http://www.w3.org/2000/svg"
+            width="24"
+            height="24"
+            viewBox="0 0 24 24"
+            fill="none"
+            stroke="currentColor"
+            strokeWidth="2"
+            strokeLinecap="round"
+            strokeLinejoin="round"
+            className={props.className}
+        >
+            <path d="M12 17v5" />
+            <path d="m7 6 10 0-3 5v3l-4 0v-3Z" />
+            <path d="m5 6 2-2" />
+            <path d="m17 6 2-2" />
+        </svg>
+    )
+}
+
 function BulbIcon(props: { className?: string }) {
     return (
         <svg
@@ -206,9 +261,25 @@ function SessionItem(props: {
     showPath?: boolean
     api: ApiClient | null
     selected?: boolean
+    manualMode?: boolean
+    onMoveUp?: () => void
+    onMoveDown?: () => void
+    canMoveUp?: boolean
+    canMoveDown?: boolean
 }) {
     const { t } = useTranslation()
-    const { session: s, onSelect, showPath = true, api, selected = false } = props
+    const {
+        session: s,
+        onSelect,
+        showPath = true,
+        api,
+        selected = false,
+        manualMode = false,
+        onMoveUp,
+        onMoveDown,
+        canMoveUp = false,
+        canMoveDown = false
+    } = props
     const { haptic } = usePlatform()
     const [menuOpen, setMenuOpen] = useState(false)
     const [menuAnchorPoint, setMenuAnchorPoint] = useState<{ x: number; y: number }>({ x: 0, y: 0 })
@@ -334,6 +405,11 @@ function SessionItem(props: {
                 isOpen={menuOpen}
                 onClose={() => setMenuOpen(false)}
                 sessionActive={s.active}
+                manualMode={manualMode}
+                onMoveUp={onMoveUp}
+                onMoveDown={onMoveDown}
+                canMoveUp={canMoveUp}
+                canMoveDown={canMoveDown}
                 onRename={() => setRenameOpen(true)}
                 onArchive={() => setArchiveOpen(true)}
                 onDelete={() => setDeleteOpen(true)}
@@ -375,6 +451,59 @@ function SessionItem(props: {
     )
 }
 
+function GroupHeader(props: {
+    group: SessionGroup
+    isCollapsed: boolean
+    machineLabel: string
+    manualMode: boolean
+    onToggle: () => void
+    onLongPressMenu: (groupKey: string, point: { x: number; y: number }) => void
+}) {
+    const { haptic } = usePlatform()
+    const longPressHandlers = useLongPress({
+        onLongPress: (point) => {
+            if (!props.manualMode) {
+                return
+            }
+            haptic.impact('medium')
+            props.onLongPressMenu(props.group.key, point)
+        },
+        onClick: props.onToggle,
+        threshold: 500
+    })
+
+    return (
+        <button
+            type="button"
+            {...longPressHandlers}
+            className="sticky top-0 z-10 flex w-full flex-col gap-1 px-3 py-2.5 text-left bg-[var(--app-secondary-bg)] border-b border-[var(--app-border)] border-l-[3px] border-l-[var(--app-hint)] transition-colors hover:bg-[var(--app-subtle-bg)]"
+            style={{ WebkitTouchCallout: 'none' }}
+        >
+            <div className="flex items-center gap-2 min-w-0 w-full">
+                <ChevronIcon
+                    className="h-4 w-4 text-[var(--app-hint)] shrink-0"
+                    collapsed={props.isCollapsed}
+                />
+                <span className="font-semibold text-sm break-words min-w-0" title={props.group.directory}>
+                    {props.group.displayName}
+                </span>
+                <span className="shrink-0 rounded-full bg-[var(--app-subtle-bg)] px-1.5 py-0.5 text-[10px] font-medium text-[var(--app-hint)]">
+                    {props.group.sessions.length}
+                </span>
+            </div>
+            <div className="flex min-w-0 w-full flex-wrap items-center gap-2 pl-6 text-xs text-[var(--app-hint)]">
+                <span className="inline-flex items-center gap-1 rounded border border-[var(--app-border)] bg-[var(--app-bg)] px-2 py-0.5">
+                    <MachineIcon className="h-3 w-3 shrink-0" />
+                    {props.machineLabel}
+                </span>
+                <span className="truncate" title={props.group.directory}>
+                    {props.group.directory}
+                </span>
+            </div>
+        </button>
+    )
+}
+
 export function SessionList(props: {
     sessions: SessionSummary[]
     onSelect: (sessionId: string) => void
@@ -388,13 +517,90 @@ export function SessionList(props: {
 }) {
     const { t } = useTranslation()
     const { renderHeader = true, api, selectedSessionId, machineLabelsById = {} } = props
+    const { preference } = useSessionSortPreference(api)
+    const { setSessionSortPreference, isPending: isSortPreferencePending } = useSessionSortPreferenceMutation(api)
+    const sortMode = preference.sortMode
     const groups = useMemo(
         () => groupSessionsByDirectory(props.sessions),
         [props.sessions]
     )
+    const reconciledManualOrder = useMemo(
+        () => reconcileManualOrder(groups, preference.manualOrder),
+        [groups, preference.manualOrder]
+    )
+    const orderedGroups = useMemo(
+        () => (sortMode === 'manual' ? applyManualOrder(groups, reconciledManualOrder) : groups),
+        [groups, reconciledManualOrder, sortMode]
+    )
     const [collapseOverrides, setCollapseOverrides] = useState<Map<string, boolean>>(
         () => new Map()
     )
+    const [groupMenuOpen, setGroupMenuOpen] = useState(false)
+    const [groupMenuAnchor, setGroupMenuAnchor] = useState<{ x: number; y: number }>({ x: 0, y: 0 })
+    const [groupMenuKey, setGroupMenuKey] = useState<string | null>(null)
+
+    const persistSortPreference = (nextSortMode: 'auto' | 'manual', nextManualOrder = reconciledManualOrder) => {
+        if (!api) {
+            return
+        }
+
+        void setSessionSortPreference({
+            sortMode: nextSortMode,
+            manualOrder: nextManualOrder,
+            expectedVersion: preference.version
+        }).catch((error) => {
+            console.error('Failed to persist session sort preference:', error)
+        })
+    }
+
+    const toggleSortMode = () => {
+        if (sortMode === 'auto') {
+            const snapshot = snapshotManualOrder(groups)
+            persistSortPreference('manual', snapshot)
+            return
+        }
+
+        persistSortPreference('auto', reconciledManualOrder)
+    }
+
+    const moveGroupInPreference = (groupKey: string, direction: 'up' | 'down') => {
+        if (sortMode !== 'manual') {
+            return
+        }
+        const normalized = reconcileManualOrder(orderedGroups, preference.manualOrder)
+        const nextManualOrder = moveGroup(normalized, groupKey, direction)
+        if (nextManualOrder === normalized) {
+            return
+        }
+        persistSortPreference('manual', nextManualOrder)
+    }
+
+    const moveSessionInPreference = (groupKey: string, sessionId: string, direction: 'up' | 'down') => {
+        if (sortMode !== 'manual') {
+            return
+        }
+        const normalized = reconcileManualOrder(orderedGroups, preference.manualOrder)
+        const nextManualOrder = moveSession(normalized, groupKey, sessionId, direction)
+        if (nextManualOrder === normalized) {
+            return
+        }
+        persistSortPreference('manual', nextManualOrder)
+    }
+
+    const openGroupActionMenu = (groupKey: string, point: { x: number; y: number }) => {
+        setGroupMenuKey(groupKey)
+        setGroupMenuAnchor(point)
+        setGroupMenuOpen(true)
+    }
+
+    const closeGroupActionMenu = () => {
+        setGroupMenuOpen(false)
+    }
+
+    const groupMenuIndex = groupMenuKey ? orderedGroups.findIndex((group) => group.key === groupMenuKey) : -1
+    const canMoveGroupUp = groupMenuIndex > 0
+    const canMoveGroupDown = groupMenuIndex >= 0 && groupMenuIndex < orderedGroups.length - 1
+
     const resolveMachineLabel = (machineId: string | null): string => {
         if (machineId && machineLabelsById[machineId]) {
             return machineLabelsById[machineId]
@@ -422,7 +628,7 @@ export function SessionList(props: {
         setCollapseOverrides(prev => {
             if (prev.size === 0) return prev
             const next = new Map(prev)
-            const knownGroups = new Set(groups.map(group => group.key))
+            const knownGroups = new Set(orderedGroups.map(group => group.key))
             let changed = false
             for (const groupKey of next.keys()) {
                 if (!knownGroups.has(groupKey)) {
@@ -432,62 +638,68 @@ export function SessionList(props: {
             }
             return changed ? next : prev
         })
-    }, [groups])
+    }, [orderedGroups])
+
+    useEffect(() => {
+        if (!groupMenuKey) {
+            return
+        }
+
+        if (!orderedGroups.some((group) => group.key === groupMenuKey)) {
+            setGroupMenuOpen(false)
+            setGroupMenuKey(null)
+        }
+    }, [groupMenuKey, orderedGroups])
 
     return (
         <div className="mx-auto w-full max-w-content flex flex-col">
             {renderHeader ? (
                 <div className="flex items-center justify-between px-3 py-1">
                     <div className="text-xs text-[var(--app-hint)]">
-                        {t('sessions.count', { n: props.sessions.length, m: groups.length })}
+                        {t('sessions.count', { n: props.sessions.length, m: orderedGroups.length })}
+                    </div>
+                    <div className="flex items-center gap-1">
+                        <button
+                            type="button"
+                            onClick={toggleSortMode}
+                            className="p-1.5 rounded-full text-[var(--app-hint)] hover:text-[var(--app-link)] transition-colors disabled:opacity-50 disabled:cursor-not-allowed"
+                            title={t(sortMode === 'auto' ? 'sessions.sort.auto' : 'sessions.sort.manual')}
+                            aria-pressed={sortMode === 'manual'}
+                            disabled={isSortPreferencePending}
+                        >
+                            {sortMode === 'auto'
+                                ? <SortIcon className="h-4 w-4" />
+                                : <PinIcon className="h-4 w-4" />}
+                        </button>
+                        <button
+                            type="button"
+                            onClick={props.onNewSession}
+                            className="session-list-new-button p-1.5 rounded-full text-[var(--app-link)] transition-colors"
+                            title={t('sessions.new')}
+                        >
+                            <PlusIcon className="h-5 w-5" />
+                        </button>
                     </div>
-                    <button
-                        type="button"
-                        onClick={props.onNewSession}
-                        className="session-list-new-button p-1.5 rounded-full text-[var(--app-link)] transition-colors"
-                        title={t('sessions.new')}
-                    >
-                        <PlusIcon className="h-5 w-5" />
-                    </button>
                 </div>
             ) : null}
 
             <div className="flex flex-col">
-                {groups.map((group) => {
+                {orderedGroups.map((group) => {
                     const isCollapsed = isGroupCollapsed(group)
                     const groupMachineLabel = resolveMachineLabel(group.machineId)
                     return (
                         <div key={group.key} className="mt-2 first:mt-0">
-                            <button
-                                type="button"
-                                onClick={() => toggleGroup(group.key, isCollapsed)}
-                                className="sticky top-0 z-10 flex w-full flex-col gap-1 px-3 py-2.5 text-left bg-[var(--app-secondary-bg)] border-b border-[var(--app-border)] border-l-[3px] border-l-[var(--app-hint)] transition-colors hover:bg-[var(--app-subtle-bg)]"
-                            >
-                                <div className="flex items-center gap-2 min-w-0 w-full">
-                                    <ChevronIcon
-                                        className="h-4 w-4 text-[var(--app-hint)] shrink-0"
-                                        collapsed={isCollapsed}
-                                    />
-                                    <span className="font-semibold text-sm break-words min-w-0" title={group.directory}>
-                                        {group.displayName}
-                                    </span>
-                                    <span className="shrink-0 rounded-full bg-[var(--app-subtle-bg)] px-1.5 py-0.5 text-[10px] font-medium text-[var(--app-hint)]">
-                                        {group.sessions.length}
-                                    </span>
-                                </div>
-                                <div className="flex min-w-0 w-full flex-wrap items-center gap-2 pl-6 text-xs text-[var(--app-hint)]">
-                                    <span className="inline-flex items-center gap-1 rounded border border-[var(--app-border)] bg-[var(--app-bg)] px-2 py-0.5">
-                                        <MachineIcon className="h-3 w-3 shrink-0" />
-                                        {groupMachineLabel}
-                                    </span>
-                                    <span className="truncate" title={group.directory}>
-                                        {group.directory}
-                                    </span>
-                                </div>
-                            </button>
+                            <GroupHeader
+                                group={group}
+                                isCollapsed={isCollapsed}
+                                machineLabel={groupMachineLabel}
+                                manualMode={sortMode === 'manual'}
+                                onToggle={() => toggleGroup(group.key, isCollapsed)}
+                                onLongPressMenu={openGroupActionMenu}
+                            />
                             {!isCollapsed ? (
                                 <div className="flex flex-col divide-y divide-[var(--app-divider)] border-b border-[var(--app-divider)] border-l border-l-[var(--app-divider)]">
-                                    {group.sessions.map((s) => (
+                                    {group.sessions.map((s, index) => (
                                         <SessionItem
                                             key={s.id}
                                             session={s}
@@ -495,6 +707,11 @@ export function SessionList(props: {
                                             showPath={false}
                                             api={api}
                                             selected={s.id === selectedSessionId}
+                                            manualMode={sortMode === 'manual'}
+                                            onMoveUp={() => moveSessionInPreference(group.key, s.id, 'up')}
+                                            onMoveDown={() => moveSessionInPreference(group.key, s.id, 'down')}
+                                            canMoveUp={index > 0}
+                                            canMoveDown={index < group.sessions.length - 1}
                                         />
                                     ))}
                                 </div>
@@ -503,6 +720,26 @@ export function SessionList(props: {
                     )
                 })}
             </div>
+
+            <GroupActionMenu
+                isOpen={groupMenuOpen && Boolean(groupMenuKey) && sortMode === 'manual'}
+                onClose={closeGroupActionMenu}
+                onMoveUp={() => {
+                    if (!groupMenuKey) {
+                        return
+                    }
+                    moveGroupInPreference(groupMenuKey, 'up')
+                }}
+                onMoveDown={() => {
+                    if (!groupMenuKey) {
+                        return
+                    }
+                    moveGroupInPreference(groupMenuKey, 'down')
+                }}
+                canMoveUp={canMoveGroupUp}
+                canMoveDown={canMoveGroupDown}
+                anchorPoint={groupMenuAnchor}
+            />
         </div>
     )
 }
diff --git a/web/src/hooks/mutations/useSessionSortPreference.ts b/web/src/hooks/mutations/useSessionSortPreference.ts
new file mode 100644
index 000000000..c315a0d27
--- /dev/null
+++ b/web/src/hooks/mutations/useSessionSortPreference.ts
@@ -0,0 +1,68 @@
+import { useMutation, useQueryClient } from '@tanstack/react-query'
+
+import type { ApiClient } from '@/api/client'
+import type {
+    SessionSortPreference,
+    SessionSortPreferenceResponse,
+    SetSessionSortPreferencePayload,
+    SetSessionSortPreferenceResult
+} from '@/types/api'
+import { queryKeys } from '@/lib/query-keys'
+
+export function useSessionSortPreferenceMutation(api: ApiClient | null): {
+    setSessionSortPreference: (payload: SetSessionSortPreferencePayload) => Promise<SetSessionSortPreferenceResult>
+    isPending: boolean
+} {
+    const queryClient = useQueryClient()
+
+    const mutation = useMutation({
+        mutationFn: async (payload: SetSessionSortPreferencePayload) => {
+            if (!api) {
+                throw new Error('API unavailable')
+            }
+
+            return await api.setSessionSortPreference(payload)
+        },
+        onMutate: async (payload) => {
+            await queryClient.cancelQueries({ queryKey: queryKeys.sessionSortPreference })
+            const previous = queryClient.getQueryData<SessionSortPreferenceResponse>(queryKeys.sessionSortPreference)
+
+            const previousPreference = previous?.preference
+            if (previousPreference) {
+                const optimisticPreference: SessionSortPreference = {
+                    sortMode: payload.sortMode,
+                    manualOrder: payload.manualOrder,
+                    version: payload.expectedVersion !== undefined
+                        ? payload.expectedVersion + 1
+                        : previousPreference.version + 1,
+                    updatedAt: Date.now()
+                }
+
+                queryClient.setQueryData<SessionSortPreferenceResponse>(
+                    queryKeys.sessionSortPreference,
+                    { preference: optimisticPreference }
+                )
+            }
+
+            return { previous }
+        },
+        onError: (_error, _payload, context) => {
+            if (context?.previous) {
+                queryClient.setQueryData(queryKeys.sessionSortPreference, context.previous)
+            }
+        },
+        onSuccess: (result) => {
+            queryClient.setQueryData<SessionSortPreferenceResponse>(
+                queryKeys.sessionSortPreference,
+                {
+                    preference: result.preference
+                }
+            )
+        }
+    })
+
+    return {
+        setSessionSortPreference: mutation.mutateAsync,
+        isPending: mutation.isPending
+    }
+}
diff --git a/web/src/hooks/queries/useSessionSortPreference.test.tsx b/web/src/hooks/queries/useSessionSortPreference.test.tsx
new file mode 100644
index 000000000..29741446e
--- /dev/null
+++ b/web/src/hooks/queries/useSessionSortPreference.test.tsx
@@ -0,0 +1,60 @@
+import { describe, expect, it, vi } from 'vitest'
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+import { renderHook, waitFor } from '@testing-library/react'
+import type { ReactNode } from 'react'
+
+import { useSessionSortPreference } from './useSessionSortPreference'
+
+function createWrapper(queryClient: QueryClient) {
+    return function Wrapper(props: { children: ReactNode }) {
+        return (
+            <QueryClientProvider client={queryClient}>
+                {props.children}
+            </QueryClientProvider>
+        )
+    }
+}
+
+describe('useSessionSortPreference', () => {
+    it('loads preference from API', async () => {
+        const queryClient = new QueryClient()
+        const api = {
+            getSessionSortPreference: vi.fn(async () => ({
+                preference: {
+                    sortMode: 'manual',
+                    manualOrder: {
+                        groupOrder: ['group-a'],
+                        sessionOrder: {
+                            'group-a': ['session-1']
+                        }
+                    },
+                    version: 3,
+                    updatedAt: 123
+                }
+            }))
+        }
+
+        const { result } = renderHook(() => useSessionSortPreference(api as never), {
+            wrapper: createWrapper(queryClient)
+        })
+
+        await waitFor(() => {
+            expect(result.current.isLoading).toBe(false)
+        })
+
+        expect(result.current.preference.sortMode).toBe('manual')
+        expect(result.current.preference.version).toBe(3)
+        expect(api.getSessionSortPreference).toHaveBeenCalledTimes(1)
+    })
+
+    it('returns defaults when API not available', () => {
+        const queryClient = new QueryClient()
+
+        const { result } = renderHook(() => useSessionSortPreference(null), {
+            wrapper: createWrapper(queryClient)
+        })
+
+        expect(result.current.preference.sortMode).toBe('auto')
+        expect(result.current.preference.manualOrder.groupOrder).toEqual([])
+    })
+})
diff --git a/web/src/hooks/queries/useSessionSortPreference.ts b/web/src/hooks/queries/useSessionSortPreference.ts
new file mode 100644
index 000000000..2b6cbf50a
--- /dev/null
+++ b/web/src/hooks/queries/useSessionSortPreference.ts
@@ -0,0 +1,41 @@
+import { useQuery } from '@tanstack/react-query'
+
+import type { ApiClient } from '@/api/client'
+import type { SessionSortPreference } from '@/types/api'
+import { queryKeys } from '@/lib/query-keys'
+
+const DEFAULT_SORT_PREFERENCE: SessionSortPreference = {
+    sortMode: 'auto',
+    manualOrder: {
+        groupOrder: [],
+        sessionOrder: {}
+    },
+    version: 1,
+    updatedAt: 0
+}
+
+export function useSessionSortPreference(api: ApiClient | null): {
+    preference: SessionSortPreference
+    isLoading: boolean
+    error: string | null
+    refetch: () => Promise<unknown>
+} {
+    const query = useQuery({
+        queryKey: queryKeys.sessionSortPreference,
+        queryFn: async () => {
+            if (!api) {
+                throw new Error('API unavailable')
+            }
+
+            return await api.getSessionSortPreference()
+        },
+        enabled: Boolean(api)
+    })
+
+    return {
+        preference: query.data?.preference ?? DEFAULT_SORT_PREFERENCE,
+        isLoading: query.isLoading,
+        error: query.error instanceof Error ? query.error.message : query.error ? 'Failed to load session sort preference' : null,
+        refetch: query.refetch
+    }
+}
diff --git a/web/src/hooks/useSSE.ts b/web/src/hooks/useSSE.ts
index b28639a17..ab27e235d 100644
--- a/web/src/hooks/useSSE.ts
+++ b/web/src/hooks/useSSE.ts
@@ -147,6 +147,10 @@ export function useSSE(options: {
                 void queryClient.invalidateQueries({ queryKey: queryKeys.machines })
             }
 
+            if (event.type === 'session-sort-preference-updated') {
+                void queryClient.invalidateQueries({ queryKey: queryKeys.sessionSortPreference })
+            }
+
             onEventRef.current(event)
         }
 
diff --git a/web/src/lib/locales/en.ts b/web/src/lib/locales/en.ts
index 3e7d96991..55070b3cf 100644
--- a/web/src/lib/locales/en.ts
+++ b/web/src/lib/locales/en.ts
@@ -41,6 +41,8 @@ export default {
   // Sessions page
   'sessions.count': '{n} sessions in {m} projects',
   'sessions.new': 'New Session',
+  'sessions.sort.auto': 'Sort: automatic',
+  'sessions.sort.manual': 'Sort: manual',
 
   // Session list
   'session.item.path': 'path',
@@ -64,6 +66,11 @@ export default {
   'session.action.archive': 'Archive',
   'session.action.delete': 'Delete',
   'session.action.copy': 'Copy',
+  'session.action.moveUp': 'Move Up',
+  'session.action.moveDown': 'Move Down',
+  'group.more': 'Group actions',
+  'group.action.moveUp': 'Move Up',
+  'group.action.moveDown': 'Move Down',
 
   // Dialogs
   'dialog.rename.title': 'Rename Session',
diff --git a/web/src/lib/locales/zh-CN.ts b/web/src/lib/locales/zh-CN.ts
index 5b407b9ea..b2cfe5337 100644
--- a/web/src/lib/locales/zh-CN.ts
+++ b/web/src/lib/locales/zh-CN.ts
@@ -41,6 +41,8 @@ export default {
   // Sessions page
   'sessions.count': '{n} 个会话，{m} 个项目',
   'sessions.new': '新建会话',
+  'sessions.sort.auto': '排序：自动',
+  'sessions.sort.manual': '排序：手动',
 
   // Session list
   'session.item.path': '路径',
@@ -64,6 +66,11 @@ export default {
   'session.action.archive': '归档',
   'session.action.delete': '删除',
   'session.action.copy': '复制',
+  'session.action.moveUp': '上移',
+  'session.action.moveDown': '下移',
+  'group.more': '分组操作',
+  'group.action.moveUp': '上移',
+  'group.action.moveDown': '下移',
 
   // Dialogs
   'dialog.rename.title': '重命名会话',
diff --git a/web/src/lib/query-keys.ts b/web/src/lib/query-keys.ts
index a00b5512b..7cfe79326 100644
--- a/web/src/lib/query-keys.ts
+++ b/web/src/lib/query-keys.ts
@@ -15,4 +15,5 @@ export const queryKeys = {
     ] as const,
     slashCommands: (sessionId: string) => ['slash-commands', sessionId] as const,
     skills: (sessionId: string) => ['skills', sessionId] as const,
+    sessionSortPreference: ['session-sort-preference'] as const,
 }
diff --git a/web/src/lib/sessionSortOrder.test.ts b/web/src/lib/sessionSortOrder.test.ts
new file mode 100644
index 000000000..55b54aa08
--- /dev/null
+++ b/web/src/lib/sessionSortOrder.test.ts
@@ -0,0 +1,112 @@
+import { describe, expect, it } from 'vitest'
+
+import {
+    applyManualOrder,
+    moveGroup,
+    moveSession,
+    reconcileManualOrder,
+    snapshotManualOrder
+} from './sessionSortOrder'
+
+type TestSession = {
+    id: string
+}
+
+type TestGroup = {
+    key: string
+    sessions: TestSession[]
+}
+
+function makeGroups(): TestGroup[] {
+    return [
+        {
+            key: 'group-a',
+            sessions: [{ id: 'a1' }, { id: 'a2' }]
+        },
+        {
+            key: 'group-b',
+            sessions: [{ id: 'b1' }, { id: 'b2' }]
+        }
+    ]
+}
+
+describe('sessionSortOrder', () => {
+    it('captures snapshot for groups and sessions', () => {
+        const groups = makeGroups()
+        const snapshot = snapshotManualOrder(groups)
+
+        expect(snapshot.groupOrder).toEqual(['group-a', 'group-b'])
+        expect(snapshot.sessionOrder['group-a']).toEqual(['a1', 'a2'])
+        expect(snapshot.sessionOrder['group-b']).toEqual(['b1', 'b2'])
+    })
+
+    it('reconciles stale ids and appends unknown items to bottom', () => {
+        const groups: TestGroup[] = [
+            {
+                key: 'group-b',
+                sessions: [{ id: 'b2' }, { id: 'b3' }]
+            },
+            {
+                key: 'group-c',
+                sessions: [{ id: 'c1' }]
+            }
+        ]
+
+        const reconciled = reconcileManualOrder(groups, {
+            groupOrder: ['group-a', 'group-b'],
+            sessionOrder: {
+                'group-b': ['b1', 'b2']
+            }
+        })
+
+        expect(reconciled.groupOrder).toEqual(['group-b', 'group-c'])
+        expect(reconciled.sessionOrder['group-b']).toEqual(['b2', 'b3'])
+        expect(reconciled.sessionOrder['group-c']).toEqual(['c1'])
+    })
+
+    it('applies manual order to groups and sessions', () => {
+        const groups = makeGroups()
+        const ordered = applyManualOrder(groups, {
+            groupOrder: ['group-b', 'group-a'],
+            sessionOrder: {
+                'group-a': ['a2', 'a1'],
+                'group-b': ['b2', 'b1']
+            }
+        })
+
+        expect(ordered.map((group) => group.key)).toEqual(['group-b', 'group-a'])
+        expect(ordered[0]?.sessions.map((session) => session.id)).toEqual(['b2', 'b1'])
+        expect(ordered[1]?.sessions.map((session) => session.id)).toEqual(['a2', 'a1'])
+    })
+
+    it('moves groups up and down', () => {
+        const base = {
+            groupOrder: ['group-a', 'group-b', 'group-c'],
+            sessionOrder: {}
+        }
+
+        const movedDown = moveGroup(base, 'group-b', 'down')
+        expect(movedDown.groupOrder).toEqual(['group-a', 'group-c', 'group-b'])
+
+        const movedUp = moveGroup(base, 'group-b', 'up')
+        expect(movedUp.groupOrder).toEqual(['group-b', 'group-a', 'group-c'])
+
+        const boundary = moveGroup(base, 'group-a', 'up')
+        expect(boundary).toBe(base)
+    })
+
+    it('moves sessions within the same group', () => {
+        const base = {
+            groupOrder: ['group-a'],
+            sessionOrder: {
+                'group-a': ['a1', 'a2', 'a3']
+            }
+        }
+
+        const moved = moveSession(base, 'group-a', 'a2', 'down')
+        expect(moved.sessionOrder['group-a']).toEqual(['a1', 'a3', 'a2'])
+
+        const boundary = moveSession(base, 'group-a', 'a1', 'up')
+        expect(boundary).toBe(base)
+    })
+})
diff --git a/web/src/lib/sessionSortOrder.ts b/web/src/lib/sessionSortOrder.ts
new file mode 100644
index 000000000..77a799900
--- /dev/null
+++ b/web/src/lib/sessionSortOrder.ts
@@ -0,0 +1,158 @@
+import type { SessionManualOrder } from '@/types/api'
+
+type Direction = 'up' | 'down'
+
+type SortableSession = {
+    id: string
+}
+
+type SortableGroup<TSession extends SortableSession = SortableSession> = {
+    key: string
+    sessions: TSession[]
+}
+
+export function createEmptyManualOrder(): SessionManualOrder {
+    return {
+        groupOrder: [],
+        sessionOrder: {}
+    }
+}
+
+export function snapshotManualOrder<TSession extends SortableSession, TGroup extends SortableGroup<TSession>>(
+    groups: TGroup[]
+): SessionManualOrder {
+    const groupOrder = groups.map((group) => group.key)
+    const sessionOrder: Record<string, string[]> = {}
+
+    for (const group of groups) {
+        sessionOrder[group.key] = group.sessions.map((session) => session.id)
+    }
+
+    return {
+        groupOrder,
+        sessionOrder
+    }
+}
+
+export function reconcileManualOrder<TSession extends SortableSession, TGroup extends SortableGroup<TSession>>(
+    groups: TGroup[],
+    manualOrder: SessionManualOrder
+): SessionManualOrder {
+    const currentGroupKeys = groups.map((group) => group.key)
+    const currentGroupKeySet = new Set(currentGroupKeys)
+
+    const knownGroups = manualOrder.groupOrder.filter((groupKey) => currentGroupKeySet.has(groupKey))
+    const knownGroupSet = new Set(knownGroups)
+    const appendedGroups = currentGroupKeys.filter((groupKey) => !knownGroupSet.has(groupKey))
+
+    const sessionOrder: Record<string, string[]> = {}
+
+    for (const group of groups) {
+        const currentSessionIds = group.sessions.map((session) => session.id)
+        const currentSessionSet = new Set(currentSessionIds)
+        const storedSessionOrder = manualOrder.sessionOrder[group.key] ?? []
+        const knownSessions = storedSessionOrder.filter((sessionId) => currentSessionSet.has(sessionId))
+        const knownSessionSet = new Set(knownSessions)
+        const appendedSessions = currentSessionIds.filter((sessionId) => !knownSessionSet.has(sessionId))
+
+        sessionOrder[group.key] = [...knownSessions, ...appendedSessions]
+    }
+
+    return {
+        groupOrder: [...knownGroups, ...appendedGroups],
+        sessionOrder
+    }
+}
+
+export function applyManualOrder<TSession extends SortableSession, TGroup extends SortableGroup<TSession>>(
+    groups: TGroup[],
+    manualOrder: SessionManualOrder
+): TGroup[] {
+    const reconciled = reconcileManualOrder(groups, manualOrder)
+    const groupIndex = new Map(reconciled.groupOrder.map((groupKey, index) => [groupKey, index]))
+
+    return [...groups]
+        .sort((groupA, groupB) => {
+            const indexA = groupIndex.get(groupA.key) ?? Number.MAX_SAFE_INTEGER
+            const indexB = groupIndex.get(groupB.key) ?? Number.MAX_SAFE_INTEGER
+            return indexA - indexB
+        })
+        .map((group) => {
+            const order = reconciled.sessionOrder[group.key] ?? []
+            const sessionIndex = new Map(order.map((sessionId, index) => [sessionId, index]))
+            const sessions = [...group.sessions].sort((sessionA, sessionB) => {
+                const indexA = sessionIndex.get(sessionA.id) ?? Number.MAX_SAFE_INTEGER
+                const indexB = sessionIndex.get(sessionB.id) ?? Number.MAX_SAFE_INTEGER
+                return indexA - indexB
+            })
+
+            return {
+                ...group,
+                sessions
+            }
+        })
+}
+
+function swapAdjacent<T>(items: T[], index: number, direction: Direction): T[] {
+    const targetIndex = direction === 'up' ? index - 1 : index + 1
+    if (targetIndex < 0 || targetIndex >= items.length) {
+        return items
+    }
+
+    const next = [...items]
+    const current = next[index]
+    next[index] = next[targetIndex] as T
+    next[targetIndex] = current as T
+    return next
+}
+
+export function moveGroup(
+    manualOrder: SessionManualOrder,
+    groupKey: string,
+    direction: Direction
+): SessionManualOrder {
+    const currentIndex = manualOrder.groupOrder.indexOf(groupKey)
+    if (currentIndex === -1) {
+        return manualOrder
+    }
+
+    const nextGroupOrder = swapAdjacent(manualOrder.groupOrder, currentIndex, direction)
+    if (nextGroupOrder === manualOrder.groupOrder) {
+        return manualOrder
+    }
+
+    return {
+        groupOrder: nextGroupOrder,
+        sessionOrder: { ...manualOrder.sessionOrder }
+    }
+}
+
+export function moveSession(
+    manualOrder: SessionManualOrder,
+    groupKey: string,
+    sessionId: string,
+    direction: Direction
+): SessionManualOrder {
+    const currentOrder = manualOrder.sessionOrder[groupKey]
+    if (!currentOrder || currentOrder.length === 0) {
+        return manualOrder
+    }
+
+    const currentIndex = currentOrder.indexOf(sessionId)
+    if (currentIndex === -1) {
+        return manualOrder
+    }
+
+    const nextOrder = swapAdjacent(currentOrder, currentIndex, direction)
+    if (nextOrder === currentOrder) {
+        return manualOrder
+    }
+
+    return {
+        groupOrder: [...manualOrder.groupOrder],
+        sessionOrder: {
+            ...manualOrder.sessionOrder,
+            [groupKey]: nextOrder
+        }
+    }
+}
diff --git a/web/src/router.tsx b/web/src/router.tsx
index 3aec839f4..af23fec5b 100644
--- a/web/src/router.tsx
+++ b/web/src/router.tsx
@@ -13,7 +13,7 @@ import {
 } from '@tanstack/react-router'
 import { App } from '@/App'
 import { SessionChat } from '@/components/SessionChat'
-import { SessionList } from '@/components/SessionList'
+import { SessionList, groupSessionsByDirectory } from '@/components/SessionList'
 import { NewSession } from '@/components/NewSession'
 import { LoadingState } from '@/components/LoadingState'
 import { useAppContext } from '@/lib/app-context'
@@ -23,9 +23,12 @@ import { useMessages } from '@/hooks/queries/useMessages'
 import { useMachines } from '@/hooks/queries/useMachines'
 import { useSession } from '@/hooks/queries/useSession'
 import { useSessions } from '@/hooks/queries/useSessions'
+import { useSessionSortPreference } from '@/hooks/queries/useSessionSortPreference'
 import { useSlashCommands } from '@/hooks/queries/useSlashCommands'
 import { useSkills } from '@/hooks/queries/useSkills'
 import { useSendMessage } from '@/hooks/mutations/useSendMessage'
+import { useSessionSortPreferenceMutation } from '@/hooks/mutations/useSessionSortPreference'
+import { snapshotManualOrder } from '@/lib/sessionSortOrder'
 import { queryKeys } from '@/lib/query-keys'
 import { useToast } from '@/lib/toast-context'
 import { useTranslation } from '@/lib/use-translation'
@@ -75,6 +78,51 @@ function PlusIcon(props: { className?: string }) {
     )
 }
 
+function SortIcon(props: { className?: string }) {
+    return (
+        <svg
+            xmlns="http://www.w3.org/2000/svg"
+            width="24"
+            height="24"
+            viewBox="0 0 24 24"
+            fill="none"
+            stroke="currentColor"
+            strokeWidth="2"
+            strokeLinecap="round"
+            strokeLinejoin="round"
+            className={props.className}
+        >
+            <path d="M11 5h10" />
+            <path d="M11 9h7" />
+            <path d="M11 13h4" />
+            <path d="m3 17 3 3 3-3" />
+            <path d="M6 4v16" />
+        </svg>
+    )
+}
+
+function PinIcon(props: { className?: string }) {
+    return (
+        <svg
+            xmlns="http://www.w3.org/2000/svg"
+            width="24"
+            height="24"
+            viewBox="0 0 24 24"
+            fill="none"
+            stroke="currentColor"
+            strokeWidth="2"
+            strokeLinecap="round"
+            strokeLinejoin="round"
+            className={props.className}
+        >
+            <path d="M12 17v5" />
+            <path d="m7 6 10 0-3 5v3l-4 0v-3Z" />
+            <path d="m5 6 2-2" />
+            <path d="m17 6 2-2" />
+        </svg>
+    )
+}
+
 function SettingsIcon(props: { className?: string }) {
     return (
         <svg
@@ -108,6 +156,8 @@ function SessionsPage() {
     const matchRoute = useMatchRoute()
     const { t } = useTranslation()
     const { sessions, isLoading, error, refetch } = useSessions(api)
+    const { preference } = useSessionSortPreference(api)
+    const { setSessionSortPreference, isPending: isSortPreferencePending } = useSessionSortPreferenceMutation(api)
     const { machines } = useMachines(api, true)
 
     const handleRefresh = useCallback(() => {
@@ -119,6 +169,7 @@ function SessionsPage() {
         const machineId = s.metadata?.machineId ?? '__unknown__'
         return `${machineId}::${path}`
     })).size
+    const groups = useMemo(() => groupSessionsByDirectory(sessions), [sessions])
     const machineLabelsById = useMemo(() => {
         const labels: Record<string, string> = {}
         for (const machine of machines) {
@@ -126,6 +177,26 @@ function SessionsPage() {
         }
         return labels
     }, [machines])
+    const handleToggleSortMode = useCallback(() => {
+        if (!api) {
+            return
+        }
+
+        if (preference.sortMode === 'auto') {
+            void setSessionSortPreference({
+                sortMode: 'manual',
+                manualOrder: snapshotManualOrder(groups),
+                expectedVersion: preference.version
+            })
+            return
+        }
+
+        void setSessionSortPreference({
+            sortMode: 'auto',
+            manualOrder: preference.manualOrder,
+            expectedVersion: preference.version
+        })
+    }, [api, groups, preference.manualOrder, preference.sortMode, preference.version, setSessionSortPreference])
     const sessionMatch = matchRoute({ to: '/sessions/$sessionId', fuzzy: true })
     const selectedSessionId = sessionMatch && sessionMatch.sessionId !== 'new' ? sessionMatch.sessionId : null
     const isSessionsIndex = pathname === '/sessions' || pathname === '/sessions/'
@@ -149,6 +220,18 @@ function SessionsPage() {
                             >
                                 <SettingsIcon className="h-5 w-5" />
                             </button>
+                            <button
+                                type="button"
+                                onClick={handleToggleSortMode}
+                                className="p-1.5 rounded-full text-[var(--app-hint)] hover:text-[var(--app-link)] transition-colors disabled:opacity-50 disabled:cursor-not-allowed"
+                                title={t(preference.sortMode === 'auto' ? 'sessions.sort.auto' : 'sessions.sort.manual')}
+                                aria-pressed={preference.sortMode === 'manual'}
+                                disabled={isSortPreferencePending}
+                            >
+                                {preference.sortMode === 'auto'
+                                    ? <SortIcon className="h-4 w-4" />
+                                    : <PinIcon className="h-4 w-4" />}
+                            </button>
                             <button
                                 type="button"
                                 onClick={() => navigate({ to: '/sessions/new' })}
diff --git a/web/src/types/api.ts b/web/src/types/api.ts
index 278a49bf2..aff2e54d2 100644
--- a/web/src/types/api.ts
+++ b/web/src/types/api.ts
@@ -1,5 +1,8 @@
 import type {
     DecryptedMessage as ProtocolDecryptedMessage,
+    SessionManualOrder,
+    SessionSortMode,
+    SessionSortPreference,
     Session,
     SessionSummary,
     SyncEvent as ProtocolSyncEvent,
@@ -11,6 +14,9 @@ export type {
     AttachmentMetadata,
     ModelMode,
     PermissionMode,
+    SessionManualOrder,
+    SessionSortMode,
+    SessionSortPreference,
     Session,
     SessionSummary,
     SessionSummaryMetadata,
@@ -191,6 +197,20 @@ export type PushVapidPublicKeyResponse = {
     publicKey: string
 }
 
+export type SessionSortPreferenceResponse = {
+    preference: SessionSortPreference
+}
+
+export type SetSessionSortPreferencePayload = {
+    sortMode: SessionSortMode
+    manualOrder: SessionManualOrder
+    expectedVersion?: number
+}
+
+export type SetSessionSortPreferenceResult =
+    | { status: 'success'; preference: SessionSortPreference }
+    | { status: 'version-mismatch'; preference: SessionSortPreference }
+
 export type VisibilityPayload = {
     subscriptionId: string
     visibility: 'visible' | 'hidden'

From 950473835172354a8ab598b2e5bd6b4ae720ce46 Mon Sep 17 00:00:00 2001
From: gaius-codius <maher@najemft.com>
Date: Sat, 21 Feb 2026 01:27:15 +0000
Subject: [PATCH 21/27] fix: address PR review findings for session sort
 feature

- Remove macOS resource fork files, add ._* to .gitignore
- Add error logging in upsert catch block (sessionSortPreferences.ts)
- Fix GroupActionMenu/SessionActionMenu focus targeting disabled buttons
- Add .max() constraints to SessionManualOrderSchema arrays
- Extract duplicate sort toggle logic into shared useSortToggle hook
- Fix redundant reconcileManualOrder calls (applyManualOrder now takes
  pre-reconciled order)
- Extract duplicate SVG icons to shared SortIcons.tsx
- Remove unused createEmptyManualOrder export
- Add userId scoping to SSE session-sort-preference-updated broadcast
- Wrap runner integration test afterAll in try/finally
- Add ArrowUp/ArrowDown keyboard navigation to GroupActionMenu
- Add useSessionSortPreferenceMutation tests (optimistic update,
  rollback, API unavailable)

via [HAPI](https://hapi.run)
---
 ._LOCAL_FORK_WORKFLOW.md                      | Bin 4096 -> 0 bytes
 ._LOCAL_FORK_WORKFLOW.md.sb-b154ab4b-8zGe5O   | Bin 4096 -> 0 bytes
 .gitignore                                    |   4 +
 cli/src/runner/runner.integration.test.ts     |   8 +-
 hub/src/sse/sseManager.test.ts                |  41 ++++++
 hub/src/sse/sseManager.ts                     |   6 +-
 hub/src/store/sessionSortPreferences.ts       |   3 +-
 hub/src/web/routes/events.ts                  |   3 +
 shared/src/schemas.ts                         |   4 +-
 web/src/components/GroupActionMenu.tsx        |  56 +++-----
 web/src/components/SessionActionMenu.tsx      |  43 +-----
 web/src/components/SessionList.tsx            | 123 ++---------------
 web/src/components/icons/SortIcons.tsx        |  84 ++++++++++++
 .../useSessionSortPreference.test.tsx         | 124 ++++++++++++++++++
 web/src/hooks/useSortToggle.ts                |  80 +++++++++++
 web/src/lib/sessionSortOrder.ts               |  14 +-
 web/src/router.tsx                            |  81 +-----------
 17 files changed, 387 insertions(+), 287 deletions(-)
 delete mode 100755 ._LOCAL_FORK_WORKFLOW.md
 delete mode 100755 ._LOCAL_FORK_WORKFLOW.md.sb-b154ab4b-8zGe5O
 create mode 100644 web/src/components/icons/SortIcons.tsx
 create mode 100644 web/src/hooks/mutations/useSessionSortPreference.test.tsx
 create mode 100644 web/src/hooks/useSortToggle.ts

diff --git a/._LOCAL_FORK_WORKFLOW.md b/._LOCAL_FORK_WORKFLOW.md
deleted file mode 100755
index 218c9ef0bdc8c55f9c054ebec9d2019fac08f674..0000000000000000000000000000000000000000
GIT binary patch
literal 0
HcmV?d00001

literal 4096
zcmZQz6=P>$Vqox1Ojhs@R)|o50+1L3ClDJkFz{^v(m+1nBL)UWIUt(=a103vf+zv$
zVE6;Xv(dCLL&don7(|ovbM+Dn3UX5Q3X1Z}Qu7k?l2d`wjO;){97VpcG_fc#uOu@M
zEDv%?B?E&wLVs>*Nn%Q3NupJ@uZvG&Qff|ono)6*QDw1FdWCsGzEMu4iCJ1wdXiCY
z0Z=0YBNKz&w<D8h3$K`BU|?ZnZDwf+lr}T4_Dw9xc1_7FvHm2aVzDj#-^0M>@Rixg
z)?vooXZM8j&ij!qeSOD<&Wugdy!8byv@7SvnfESPa=B@P$+5#nXGqpHb{CX=SkmqG
z_K&{H((BPY9{U!5&aY(Sxv45}+;>`Nvgdt{+gHCnn0aAsMhe#wD+Np8#naVwm`iV`
z?`@gaWtX?18R)uEFd71*Aut*OqaiRF0;3@?8UmvsFd71*Aut*Oqai?Q2rvRQfG`-y
zg=AzFD-@*`=a&{Grz)i77iBAC=9Q!ZyOsHQi8(oy3OT81B??J7iFw(;zA#kRkfu=m
M5BG`;gWUiB0OFyDzW@LL

diff --git a/._LOCAL_FORK_WORKFLOW.md.sb-b154ab4b-8zGe5O b/._LOCAL_FORK_WORKFLOW.md.sb-b154ab4b-8zGe5O
deleted file mode 100755
index cc19a722e55fa1a3be0b1fe9802313cb0a23da10..0000000000000000000000000000000000000000
GIT binary patch
literal 0
HcmV?d00001

literal 4096
zcmZQz6=P>$Vqox1Ojhs@R)|o50+1L3ClDJkFz{^v(m+1nBL)UWIUt(=a103vf+zv$
zU^oE8(hxqJ1etyShy@rJq>}S<^%4sTa#Hnj5{pYpi&Ill5=&B*1A?KdF92z71_n`t
zx`Lwovedl9yyR4d{hy{~g4DGXr|^PkMka=G2dhG+Zzl~w+)*$Z0;3@?8UmvsFd71*
zAut*OqaiRF0;3@?8UmvsFoHsW5$IPC1_QZ}jLc$%qSWI2(xT*4g|z&lY=z9clGMDC
n%>2B>oSaI9oYb@ug`}Lsylh}!7^-VXQ>gxjdqsvp?*D%PU+Ol9

diff --git a/.gitignore b/.gitignore
index 40f16eed5..0d2767199 100644
--- a/.gitignore
+++ b/.gitignore
@@ -28,6 +28,7 @@ coverage/
 
 # OS / IDE
 **/.DS_Store
+**/._*
 .idea/
 .vscode/
 **/*.swp
@@ -37,6 +38,9 @@ coverage/
 .claude/settings.local.json
 localdocs/
 execplan/
+docs/plans/
+docs/LOCAL_FORK_WORKFLOW.md
+docs/GAIUS_THEME.md
 
 # Generated npm bundle output (local)
 cli/npm/main/
diff --git a/cli/src/runner/runner.integration.test.ts b/cli/src/runner/runner.integration.test.ts
index 77fa1d6a0..1a4108d19 100644
--- a/cli/src/runner/runner.integration.test.ts
+++ b/cli/src/runner/runner.integration.test.ts
@@ -139,9 +139,11 @@ describe.skipIf(!await isServerHealthy())('Runner Integration Tests', { timeout:
   });
 
   afterAll(async () => {
-    // Make sure the test runner is dead before restoring
-    await stopRunner();
-    uninstallTestHapiHome(savedOriginals);
+    try {
+      await stopRunner();
+    } finally {
+      uninstallTestHapiHome(savedOriginals);
+    }
   });
 
   beforeEach(async () => {
diff --git a/hub/src/sse/sseManager.test.ts b/hub/src/sse/sseManager.test.ts
index 8f582105a..2ccb85b8e 100644
--- a/hub/src/sse/sseManager.test.ts
+++ b/hub/src/sse/sseManager.test.ts
@@ -126,6 +126,7 @@ describe('SSEManager namespace filtering', () => {
         manager.subscribe({
             id: 'alpha-session',
             namespace: 'alpha',
+            userId: 1,
             all: false,
             sessionId: 'session-1',
             send: (event) => {
@@ -146,4 +147,44 @@ describe('SSEManager namespace filtering', () => {
         expect(received).toHaveLength(1)
         expect(received[0]?.type).toBe('session-sort-preference-updated')
     })
+
+    it('filters session sort preference updates by userId', () => {
+        const manager = new SSEManager(0, new VisibilityTracker())
+        const receivedUser1: SyncEvent[] = []
+        const receivedUser2: SyncEvent[] = []
+
+        manager.subscribe({
+            id: 'user1-conn',
+            namespace: 'alpha',
+            userId: 1,
+            all: true,
+            send: (event) => {
+                receivedUser1.push(event)
+            },
+            sendHeartbeat: () => {}
+        })
+
+        manager.subscribe({
+            id: 'user2-conn',
+            namespace: 'alpha',
+            userId: 2,
+            all: true,
+            send: (event) => {
+                receivedUser2.push(event)
+            },
+            sendHeartbeat: () => {}
+        })
+
+        manager.broadcast({
+            type: 'session-sort-preference-updated',
+            namespace: 'alpha',
+            data: {
+                userId: 1,
+                version: 3
+            }
+        })
+
+        expect(receivedUser1).toHaveLength(1)
+        expect(receivedUser2).toHaveLength(0)
+    })
 })
diff --git a/hub/src/sse/sseManager.ts b/hub/src/sse/sseManager.ts
index 69d9c1f44..87069452f 100644
--- a/hub/src/sse/sseManager.ts
+++ b/hub/src/sse/sseManager.ts
@@ -5,6 +5,7 @@ import type { VisibilityTracker } from '../visibility/visibilityTracker'
 export type SSESubscription = {
     id: string
     namespace: string
+    userId: number | null
     all: boolean
     sessionId: string | null
     machineId: string | null
@@ -29,6 +30,7 @@ export class SSEManager {
     subscribe(options: {
         id: string
         namespace: string
+        userId?: number | null
         all?: boolean
         sessionId?: string | null
         machineId?: string | null
@@ -39,6 +41,7 @@ export class SSEManager {
         const subscription: SSEConnection = {
             id: options.id,
             namespace: options.namespace,
+            userId: options.userId ?? null,
             all: Boolean(options.all),
             sessionId: options.sessionId ?? null,
             machineId: options.machineId ?? null,
@@ -56,6 +59,7 @@ export class SSEManager {
         return {
             id: subscription.id,
             namespace: subscription.namespace,
+            userId: subscription.userId,
             all: subscription.all,
             sessionId: subscription.sessionId,
             machineId: subscription.machineId
@@ -164,7 +168,7 @@ export class SSEManager {
         }
 
         if (event.type === 'session-sort-preference-updated') {
-            return true
+            return connection.userId === null || connection.userId === event.data.userId
         }
 
         if (connection.all) {
diff --git a/hub/src/store/sessionSortPreferences.ts b/hub/src/store/sessionSortPreferences.ts
index f93b725dc..575c34b7d 100644
--- a/hub/src/store/sessionSortPreferences.ts
+++ b/hub/src/store/sessionSortPreferences.ts
@@ -137,7 +137,8 @@ export function upsertSessionSortPreferenceByUser(
             result: 'success',
             preference: updated
         }
-    } catch {
+    } catch (error) {
+        console.error('Failed to upsert session sort preference:', error)
         return {
             result: 'error'
         }
diff --git a/hub/src/web/routes/events.ts b/hub/src/web/routes/events.ts
index 6da4cfe61..9a9a19b51 100644
--- a/hub/src/web/routes/events.ts
+++ b/hub/src/web/routes/events.ts
@@ -77,10 +77,13 @@ export function createEventsRoutes(
             }
         }
 
+        const userId = c.get('userId')
+
         return streamSSE(c, async (stream) => {
             manager.subscribe({
                 id: subscriptionId,
                 namespace,
+                userId,
                 all,
                 sessionId: resolvedSessionId,
                 machineId,
diff --git a/shared/src/schemas.ts b/shared/src/schemas.ts
index 9efe85b5f..37c026f5f 100644
--- a/shared/src/schemas.ts
+++ b/shared/src/schemas.ts
@@ -8,8 +8,8 @@ export const SessionSortModeSchema = z.enum(['auto', 'manual'])
 export type SessionSortMode = z.infer<typeof SessionSortModeSchema>
 
 export const SessionManualOrderSchema = z.object({
-    groupOrder: z.array(z.string()),
-    sessionOrder: z.record(z.string(), z.array(z.string()))
+    groupOrder: z.array(z.string().max(256)).max(500),
+    sessionOrder: z.record(z.string().max(256), z.array(z.string().max(128)).max(200))
 }).strict()
 
 export type SessionManualOrder = z.infer<typeof SessionManualOrderSchema>
diff --git a/web/src/components/GroupActionMenu.tsx b/web/src/components/GroupActionMenu.tsx
index 33c8e5f99..91cfc98d8 100644
--- a/web/src/components/GroupActionMenu.tsx
+++ b/web/src/components/GroupActionMenu.tsx
@@ -8,6 +8,7 @@ import {
     type CSSProperties
 } from 'react'
 
+import { ArrowUpIcon, ArrowDownIcon } from '@/components/icons/SortIcons'
 import { useTranslation } from '@/lib/use-translation'
 
 type GroupActionMenuProps = {
@@ -27,46 +28,6 @@ type MenuPosition = {
     transformOrigin: string
 }
 
-function ArrowUpIcon(props: { className?: string }) {
-    return (
-        <svg
-            xmlns="http://www.w3.org/2000/svg"
-            width="18"
-            height="18"
-            viewBox="0 0 24 24"
-            fill="none"
-            stroke="currentColor"
-            strokeWidth="2"
-            strokeLinecap="round"
-            strokeLinejoin="round"
-            className={props.className}
-        >
-            <path d="m5 12 7-7 7 7" />
-            <path d="M12 19V6" />
-        </svg>
-    )
-}
-
-function ArrowDownIcon(props: { className?: string }) {
-    return (
-        <svg
-            xmlns="http://www.w3.org/2000/svg"
-            width="18"
-            height="18"
-            viewBox="0 0 24 24"
-            fill="none"
-            stroke="currentColor"
-            strokeWidth="2"
-            strokeLinecap="round"
-            strokeLinejoin="round"
-            className={props.className}
-        >
-            <path d="m19 12-7 7-7-7" />
-            <path d="M12 5v13" />
-        </svg>
-    )
-}
-
 export function GroupActionMenu(props: GroupActionMenuProps) {
     const { t } = useTranslation()
     const {
@@ -129,6 +90,19 @@ export function GroupActionMenu(props: GroupActionMenuProps) {
         const handleKeyDown = (event: KeyboardEvent) => {
             if (event.key === 'Escape') {
                 onClose()
+                return
+            }
+
+            if (event.key === 'ArrowDown' || event.key === 'ArrowUp') {
+                event.preventDefault()
+                const items = menuRef.current?.querySelectorAll<HTMLElement>('[role="menuitem"]:not([disabled])')
+                if (!items || items.length === 0) return
+                const current = document.activeElement as HTMLElement
+                const index = Array.from(items).indexOf(current)
+                const next = event.key === 'ArrowDown'
+                    ? items[(index + 1) % items.length]
+                    : items[(index - 1 + items.length) % items.length]
+                next?.focus()
             }
         }
 
@@ -153,7 +127,7 @@ export function GroupActionMenu(props: GroupActionMenuProps) {
         if (!isOpen) return
 
         const frame = window.requestAnimationFrame(() => {
-            const firstItem = menuRef.current?.querySelector<HTMLElement>('[role="menuitem"]')
+            const firstItem = menuRef.current?.querySelector<HTMLElement>('[role="menuitem"]:not([disabled])')
             firstItem?.focus()
         })
 
diff --git a/web/src/components/SessionActionMenu.tsx b/web/src/components/SessionActionMenu.tsx
index 87b01f19a..abe01774c 100644
--- a/web/src/components/SessionActionMenu.tsx
+++ b/web/src/components/SessionActionMenu.tsx
@@ -7,6 +7,7 @@ import {
     useState,
     type CSSProperties
 } from 'react'
+import { ArrowUpIcon, ArrowDownIcon } from '@/components/icons/SortIcons'
 import { useTranslation } from '@/lib/use-translation'
 
 type SessionActionMenuProps = {
@@ -89,46 +90,6 @@ function TrashIcon(props: { className?: string }) {
     )
 }
 
-function ArrowUpIcon(props: { className?: string }) {
-    return (
-        <svg
-            xmlns="http://www.w3.org/2000/svg"
-            width="18"
-            height="18"
-            viewBox="0 0 24 24"
-            fill="none"
-            stroke="currentColor"
-            strokeWidth="2"
-            strokeLinecap="round"
-            strokeLinejoin="round"
-            className={props.className}
-        >
-            <path d="m5 12 7-7 7 7" />
-            <path d="M12 19V6" />
-        </svg>
-    )
-}
-
-function ArrowDownIcon(props: { className?: string }) {
-    return (
-        <svg
-            xmlns="http://www.w3.org/2000/svg"
-            width="18"
-            height="18"
-            viewBox="0 0 24 24"
-            fill="none"
-            stroke="currentColor"
-            strokeWidth="2"
-            strokeLinecap="round"
-            strokeLinejoin="round"
-            className={props.className}
-        >
-            <path d="m19 12-7 7-7-7" />
-            <path d="M12 5v13" />
-        </svg>
-    )
-}
-
 type MenuPosition = {
     top: number
     left: number
@@ -257,7 +218,7 @@ export function SessionActionMenu(props: SessionActionMenuProps) {
         if (!isOpen) return
 
         const frame = window.requestAnimationFrame(() => {
-            const firstItem = menuRef.current?.querySelector<HTMLElement>('[role="menuitem"]')
+            const firstItem = menuRef.current?.querySelector<HTMLElement>('[role="menuitem"]:not([disabled])')
             firstItem?.focus()
         })
 
diff --git a/web/src/components/SessionList.tsx b/web/src/components/SessionList.tsx
index 58072395e..f0d731551 100644
--- a/web/src/components/SessionList.tsx
+++ b/web/src/components/SessionList.tsx
@@ -5,19 +5,12 @@ import { getPermissionModeLabel, getPermissionModeTone, isPermissionModeAllowedF
 import { useLongPress } from '@/hooks/useLongPress'
 import { usePlatform } from '@/hooks/usePlatform'
 import { useSessionActions } from '@/hooks/mutations/useSessionActions'
-import { useSessionSortPreferenceMutation } from '@/hooks/mutations/useSessionSortPreference'
-import { useSessionSortPreference } from '@/hooks/queries/useSessionSortPreference'
+import { useSortToggle } from '@/hooks/useSortToggle'
+import { SortIcon, PinIcon } from '@/components/icons/SortIcons'
 import { SessionActionMenu } from '@/components/SessionActionMenu'
 import { GroupActionMenu } from '@/components/GroupActionMenu'
 import { RenameSessionDialog } from '@/components/RenameSessionDialog'
 import { ConfirmDialog } from '@/components/ui/ConfirmDialog'
-import {
-    applyManualOrder,
-    moveGroup,
-    moveSession,
-    reconcileManualOrder,
-    snapshotManualOrder
-} from '@/lib/sessionSortOrder'
 import { useTranslation } from '@/lib/use-translation'
 import { getFlavorTextClass, PERMISSION_TONE_TEXT } from '@/lib/agentFlavorUtils'
 
@@ -109,51 +102,6 @@ function PlusIcon(props: { className?: string }) {
     )
 }
 
-function SortIcon(props: { className?: string }) {
-    return (
-        <svg
-            xmlns="http://www.w3.org/2000/svg"
-            width="24"
-            height="24"
-            viewBox="0 0 24 24"
-            fill="none"
-            stroke="currentColor"
-            strokeWidth="2"
-            strokeLinecap="round"
-            strokeLinejoin="round"
-            className={props.className}
-        >
-            <path d="M11 5h10" />
-            <path d="M11 9h7" />
-            <path d="M11 13h4" />
-            <path d="m3 17 3 3 3-3" />
-            <path d="M6 4v16" />
-        </svg>
-    )
-}
-
-function PinIcon(props: { className?: string }) {
-    return (
-        <svg
-            xmlns="http://www.w3.org/2000/svg"
-            width="24"
-            height="24"
-            viewBox="0 0 24 24"
-            fill="none"
-            stroke="currentColor"
-            strokeWidth="2"
-            strokeLinecap="round"
-            strokeLinejoin="round"
-            className={props.className}
-        >
-            <path d="M12 17v5" />
-            <path d="m7 6 10 0-3 5v3l-4 0v-3Z" />
-            <path d="m5 6 2-2" />
-            <path d="m17 6 2-2" />
-        </svg>
-    )
-}
-
 function BulbIcon(props: { className?: string }) {
     return (
         <svg
@@ -517,21 +465,18 @@ export function SessionList(props: {
 }) {
     const { t } = useTranslation()
     const { renderHeader = true, api, selectedSessionId, machineLabelsById = {} } = props
-    const { preference } = useSessionSortPreference(api)
-    const { setSessionSortPreference, isPending: isSortPreferencePending } = useSessionSortPreferenceMutation(api)
-    const sortMode = preference.sortMode
     const groups = useMemo(
         () => groupSessionsByDirectory(props.sessions),
         [props.sessions]
     )
-    const reconciledManualOrder = useMemo(
-        () => reconcileManualOrder(groups, preference.manualOrder),
-        [groups, preference.manualOrder]
-    )
-    const orderedGroups = useMemo(
-        () => (sortMode === 'manual' ? applyManualOrder(groups, reconciledManualOrder) : groups),
-        [groups, reconciledManualOrder, sortMode]
-    )
+    const {
+        sortMode,
+        orderedGroups,
+        isSortPreferencePending,
+        toggleSortMode,
+        moveGroupInPreference,
+        moveSessionInPreference
+    } = useSortToggle(api, groups)
     const [collapseOverrides, setCollapseOverrides] = useState<Map<string, boolean>>(
         () => new Map()
     )
@@ -539,54 +484,6 @@ export function SessionList(props: {
     const [groupMenuAnchor, setGroupMenuAnchor] = useState<{ x: number; y: number }>({ x: 0, y: 0 })
     const [groupMenuKey, setGroupMenuKey] = useState<string | null>(null)
 
-    const persistSortPreference = (nextSortMode: 'auto' | 'manual', nextManualOrder = reconciledManualOrder) => {
-        if (!api) {
-            return
-        }
-
-        void setSessionSortPreference({
-            sortMode: nextSortMode,
-            manualOrder: nextManualOrder,
-            expectedVersion: preference.version
-        }).catch((error) => {
-            console.error('Failed to persist session sort preference:', error)
-        })
-    }
-
-    const toggleSortMode = () => {
-        if (sortMode === 'auto') {
-            const snapshot = snapshotManualOrder(groups)
-            persistSortPreference('manual', snapshot)
-            return
-        }
-
-        persistSortPreference('auto', reconciledManualOrder)
-    }
-
-    const moveGroupInPreference = (groupKey: string, direction: 'up' | 'down') => {
-        if (sortMode !== 'manual') {
-            return
-        }
-        const normalized = reconcileManualOrder(orderedGroups, preference.manualOrder)
-        const nextManualOrder = moveGroup(normalized, groupKey, direction)
-        if (nextManualOrder === normalized) {
-            return
-        }
-        persistSortPreference('manual', nextManualOrder)
-    }
-
-    const moveSessionInPreference = (groupKey: string, sessionId: string, direction: 'up' | 'down') => {
-        if (sortMode !== 'manual') {
-            return
-        }
-        const normalized = reconcileManualOrder(orderedGroups, preference.manualOrder)
-        const nextManualOrder = moveSession(normalized, groupKey, sessionId, direction)
-        if (nextManualOrder === normalized) {
-            return
-        }
-        persistSortPreference('manual', nextManualOrder)
-    }
-
     const openGroupActionMenu = (groupKey: string, point: { x: number; y: number }) => {
         setGroupMenuKey(groupKey)
         setGroupMenuAnchor(point)
diff --git a/web/src/components/icons/SortIcons.tsx b/web/src/components/icons/SortIcons.tsx
new file mode 100644
index 000000000..92928ed86
--- /dev/null
+++ b/web/src/components/icons/SortIcons.tsx
@@ -0,0 +1,84 @@
+export function SortIcon(props: { className?: string }) {
+    return (
+        <svg
+            xmlns="http://www.w3.org/2000/svg"
+            width="24"
+            height="24"
+            viewBox="0 0 24 24"
+            fill="none"
+            stroke="currentColor"
+            strokeWidth="2"
+            strokeLinecap="round"
+            strokeLinejoin="round"
+            className={props.className}
+        >
+            <path d="M11 5h10" />
+            <path d="M11 9h7" />
+            <path d="M11 13h4" />
+            <path d="m3 17 3 3 3-3" />
+            <path d="M6 4v16" />
+        </svg>
+    )
+}
+
+export function PinIcon(props: { className?: string }) {
+    return (
+        <svg
+            xmlns="http://www.w3.org/2000/svg"
+            width="24"
+            height="24"
+            viewBox="0 0 24 24"
+            fill="none"
+            stroke="currentColor"
+            strokeWidth="2"
+            strokeLinecap="round"
+            strokeLinejoin="round"
+            className={props.className}
+        >
+            <path d="M12 17v5" />
+            <path d="m7 6 10 0-3 5v3l-4 0v-3Z" />
+            <path d="m5 6 2-2" />
+            <path d="m17 6 2-2" />
+        </svg>
+    )
+}
+
+export function ArrowUpIcon(props: { className?: string }) {
+    return (
+        <svg
+            xmlns="http://www.w3.org/2000/svg"
+            width="18"
+            height="18"
+            viewBox="0 0 24 24"
+            fill="none"
+            stroke="currentColor"
+            strokeWidth="2"
+            strokeLinecap="round"
+            strokeLinejoin="round"
+            className={props.className}
+        >
+            <path d="m5 12 7-7 7 7" />
+            <path d="M12 19V6" />
+        </svg>
+    )
+}
+
+export function ArrowDownIcon(props: { className?: string }) {
+    return (
+        <svg
+            xmlns="http://www.w3.org/2000/svg"
+            width="18"
+            height="18"
+            viewBox="0 0 24 24"
+            fill="none"
+            stroke="currentColor"
+            strokeWidth="2"
+            strokeLinecap="round"
+            strokeLinejoin="round"
+            className={props.className}
+        >
+            <path d="m19 12-7 7-7-7" />
+            <path d="M12 5v13" />
+        </svg>
+    )
+}
diff --git a/web/src/hooks/mutations/useSessionSortPreference.test.tsx b/web/src/hooks/mutations/useSessionSortPreference.test.tsx
new file mode 100644
index 000000000..aebe043fc
--- /dev/null
+++ b/web/src/hooks/mutations/useSessionSortPreference.test.tsx
@@ -0,0 +1,124 @@
+import { describe, expect, it, vi } from 'vitest'
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+import { renderHook, waitFor, act } from '@testing-library/react'
+import type { ReactNode } from 'react'
+
+import { useSessionSortPreferenceMutation } from './useSessionSortPreference'
+import { queryKeys } from '@/lib/query-keys'
+import type { SessionSortPreferenceResponse } from '@/types/api'
+
+function createWrapper(queryClient: QueryClient) {
+    return function Wrapper(props: { children: ReactNode }) {
+        return (
+            <QueryClientProvider client={queryClient}>
+                {props.children}
+            </QueryClientProvider>
+        )
+    }
+}
+
+describe('useSessionSortPreferenceMutation', () => {
+    it('updates cache optimistically on mutate', async () => {
+        const queryClient = new QueryClient()
+        const serverPreference = {
+            sortMode: 'manual' as const,
+            manualOrder: { groupOrder: ['g1'], sessionOrder: { g1: ['s1'] } },
+            version: 3,
+            updatedAt: 999
+        }
+        const api = {
+            setSessionSortPreference: vi.fn(async () => ({
+                status: 'success' as const,
+                preference: serverPreference
+            }))
+        }
+
+        queryClient.setQueryData<SessionSortPreferenceResponse>(
+            queryKeys.sessionSortPreference,
+            {
+                preference: {
+                    sortMode: 'auto',
+                    manualOrder: { groupOrder: [], sessionOrder: {} },
+                    version: 2,
+                    updatedAt: 100
+                }
+            }
+        )
+
+        const { result } = renderHook(() => useSessionSortPreferenceMutation(api as never), {
+            wrapper: createWrapper(queryClient)
+        })
+
+        await act(async () => {
+            await result.current.setSessionSortPreference({
+                sortMode: 'manual',
+                manualOrder: { groupOrder: ['g1'], sessionOrder: { g1: ['s1'] } },
+                expectedVersion: 2
+            })
+        })
+
+        const cached = queryClient.getQueryData<SessionSortPreferenceResponse>(queryKeys.sessionSortPreference)
+        expect(cached?.preference.sortMode).toBe('manual')
+        expect(cached?.preference.version).toBe(3)
+    })
+
+    it('rolls back cache on error', async () => {
+        const queryClient = new QueryClient()
+        const api = {
+            setSessionSortPreference: vi.fn(async () => {
+                throw new Error('Network error')
+            })
+        }
+
+        queryClient.setQueryData<SessionSortPreferenceResponse>(
+            queryKeys.sessionSortPreference,
+            {
+                preference: {
+                    sortMode: 'auto',
+                    manualOrder: { groupOrder: [], sessionOrder: {} },
+                    version: 1,
+                    updatedAt: 100
+                }
+            }
+        )
+
+        const { result } = renderHook(() => useSessionSortPreferenceMutation(api as never), {
+            wrapper: createWrapper(queryClient)
+        })
+
+        await act(async () => {
+            try {
+                await result.current.setSessionSortPreference({
+                    sortMode: 'manual',
+                    manualOrder: { groupOrder: ['g1'], sessionOrder: {} },
+                    expectedVersion: 1
+                })
+            } catch {
+                // expected
+            }
+        })
+
+        await waitFor(() => {
+            const cached = queryClient.getQueryData<SessionSortPreferenceResponse>(queryKeys.sessionSortPreference)
+            expect(cached?.preference.sortMode).toBe('auto')
+            expect(cached?.preference.version).toBe(1)
+        })
+    })
+
+    it('throws when API is not available', async () => {
+        const queryClient = new QueryClient()
+
+        const { result } = renderHook(() => useSessionSortPreferenceMutation(null), {
+            wrapper: createWrapper(queryClient)
+        })
+
+        await expect(
+            act(async () => {
+                await result.current.setSessionSortPreference({
+                    sortMode: 'manual',
+                    manualOrder: { groupOrder: [], sessionOrder: {} }
+                })
+            })
+        ).rejects.toThrow('API unavailable')
+    })
+})
diff --git a/web/src/hooks/useSortToggle.ts b/web/src/hooks/useSortToggle.ts
new file mode 100644
index 000000000..821db3bd8
--- /dev/null
+++ b/web/src/hooks/useSortToggle.ts
@@ -0,0 +1,80 @@
+import { useMemo } from 'react'
+
+import type { ApiClient } from '@/api/client'
+import type { SessionManualOrder } from '@/types/api'
+import { useSessionSortPreference } from '@/hooks/queries/useSessionSortPreference'
+import { useSessionSortPreferenceMutation } from '@/hooks/mutations/useSessionSortPreference'
+import {
+    reconcileManualOrder,
+    snapshotManualOrder,
+    applyManualOrder,
+    moveGroup,
+    moveSession,
+} from '@/lib/sessionSortOrder'
+
+type SortableSession = { id: string }
+type SortableGroup<TSession extends SortableSession = SortableSession> = {
+    key: string
+    sessions: TSession[]
+}
+
+export function useSortToggle<
+    TSession extends SortableSession,
+    TGroup extends SortableGroup<TSession>
+>(api: ApiClient | null, groups: TGroup[]) {
+    const { preference } = useSessionSortPreference(api)
+    const { setSessionSortPreference, isPending: isSortPreferencePending } = useSessionSortPreferenceMutation(api)
+    const sortMode = preference.sortMode
+
+    const reconciledManualOrder = useMemo(
+        () => reconcileManualOrder(groups, preference.manualOrder),
+        [groups, preference.manualOrder]
+    )
+
+    const orderedGroups = useMemo(
+        () => (sortMode === 'manual' ? applyManualOrder(groups, reconciledManualOrder) : groups),
+        [groups, reconciledManualOrder, sortMode]
+    )
+
+    const persistSortPreference = (nextSortMode: 'auto' | 'manual', nextManualOrder: SessionManualOrder = reconciledManualOrder) => {
+        if (!api) return
+        void setSessionSortPreference({
+            sortMode: nextSortMode,
+            manualOrder: nextManualOrder,
+            expectedVersion: preference.version
+        }).catch((error) => {
+            console.error('Failed to persist session sort preference:', error)
+        })
+    }
+
+    const toggleSortMode = () => {
+        if (sortMode === 'auto') {
+            persistSortPreference('manual', snapshotManualOrder(groups))
+            return
+        }
+        persistSortPreference('auto', reconciledManualOrder)
+    }
+
+    const moveGroupInPreference = (groupKey: string, direction: 'up' | 'down') => {
+        if (sortMode !== 'manual') return
+        const nextManualOrder = moveGroup(reconciledManualOrder, groupKey, direction)
+        if (nextManualOrder === reconciledManualOrder) return
+        persistSortPreference('manual', nextManualOrder)
+    }
+
+    const moveSessionInPreference = (groupKey: string, sessionId: string, direction: 'up' | 'down') => {
+        if (sortMode !== 'manual') return
+        const nextManualOrder = moveSession(reconciledManualOrder, groupKey, sessionId, direction)
+        if (nextManualOrder === reconciledManualOrder) return
+        persistSortPreference('manual', nextManualOrder)
+    }
+
+    return {
+        sortMode,
+        orderedGroups,
+        isSortPreferencePending,
+        toggleSortMode,
+        moveGroupInPreference,
+        moveSessionInPreference,
+    }
+}
diff --git a/web/src/lib/sessionSortOrder.ts b/web/src/lib/sessionSortOrder.ts
index 77a799900..dee79d45f 100644
--- a/web/src/lib/sessionSortOrder.ts
+++ b/web/src/lib/sessionSortOrder.ts
@@ -11,13 +11,6 @@ type SortableGroup<TSession extends SortableSession = SortableSession> = {
     sessions: TSession[]
 }
 
-export function createEmptyManualOrder(): SessionManualOrder {
-    return {
-        groupOrder: [],
-        sessionOrder: {}
-    }
-}
-
 export function snapshotManualOrder<TSession extends SortableSession, TGroup extends SortableGroup<TSession>>(
     groups: TGroup[]
 ): SessionManualOrder {
@@ -66,10 +59,9 @@ export function reconcileManualOrder<TSession extends SortableSession, TGroup ex
 
 export function applyManualOrder<TSession extends SortableSession, TGroup extends SortableGroup<TSession>>(
     groups: TGroup[],
-    manualOrder: SessionManualOrder
+    reconciledOrder: SessionManualOrder
 ): TGroup[] {
-    const reconciled = reconcileManualOrder(groups, manualOrder)
-    const groupIndex = new Map(reconciled.groupOrder.map((groupKey, index) => [groupKey, index]))
+    const groupIndex = new Map(reconciledOrder.groupOrder.map((groupKey, index) => [groupKey, index]))
 
     return [...groups]
         .sort((groupA, groupB) => {
@@ -78,7 +70,7 @@ export function applyManualOrder<TSession extends SortableSession, TGroup extend
             return indexA - indexB
         })
         .map((group) => {
-            const order = reconciled.sessionOrder[group.key] ?? []
+            const order = reconciledOrder.sessionOrder[group.key] ?? []
             const sessionIndex = new Map(order.map((sessionId, index) => [sessionId, index]))
             const sessions = [...group.sessions].sort((sessionA, sessionB) => {
                 const indexA = sessionIndex.get(sessionA.id) ?? Number.MAX_SAFE_INTEGER
diff --git a/web/src/router.tsx b/web/src/router.tsx
index af23fec5b..36c99ebd7 100644
--- a/web/src/router.tsx
+++ b/web/src/router.tsx
@@ -12,6 +12,7 @@ import {
     useParams,
 } from '@tanstack/react-router'
 import { App } from '@/App'
+import { SortIcon, PinIcon } from '@/components/icons/SortIcons'
 import { SessionChat } from '@/components/SessionChat'
 import { SessionList, groupSessionsByDirectory } from '@/components/SessionList'
 import { NewSession } from '@/components/NewSession'
@@ -23,12 +24,10 @@ import { useMessages } from '@/hooks/queries/useMessages'
 import { useMachines } from '@/hooks/queries/useMachines'
 import { useSession } from '@/hooks/queries/useSession'
 import { useSessions } from '@/hooks/queries/useSessions'
-import { useSessionSortPreference } from '@/hooks/queries/useSessionSortPreference'
 import { useSlashCommands } from '@/hooks/queries/useSlashCommands'
 import { useSkills } from '@/hooks/queries/useSkills'
 import { useSendMessage } from '@/hooks/mutations/useSendMessage'
-import { useSessionSortPreferenceMutation } from '@/hooks/mutations/useSessionSortPreference'
-import { snapshotManualOrder } from '@/lib/sessionSortOrder'
+import { useSortToggle } from '@/hooks/useSortToggle'
 import { queryKeys } from '@/lib/query-keys'
 import { useToast } from '@/lib/toast-context'
 import { useTranslation } from '@/lib/use-translation'
@@ -78,51 +77,6 @@ function PlusIcon(props: { className?: string }) {
     )
 }
 
-function SortIcon(props: { className?: string }) {
-    return (
-        <svg
-            xmlns="http://www.w3.org/2000/svg"
-            width="24"
-            height="24"
-            viewBox="0 0 24 24"
-            fill="none"
-            stroke="currentColor"
-            strokeWidth="2"
-            strokeLinecap="round"
-            strokeLinejoin="round"
-            className={props.className}
-        >
-            <path d="M11 5h10" />
-            <path d="M11 9h7" />
-            <path d="M11 13h4" />
-            <path d="m3 17 3 3 3-3" />
-            <path d="M6 4v16" />
-        </svg>
-    )
-}
-
-function PinIcon(props: { className?: string }) {
-    return (
-        <svg
-            xmlns="http://www.w3.org/2000/svg"
-            width="24"
-            height="24"
-            viewBox="0 0 24 24"
-            fill="none"
-            stroke="currentColor"
-            strokeWidth="2"
-            strokeLinecap="round"
-            strokeLinejoin="round"
-            className={props.className}
-        >
-            <path d="M12 17v5" />
-            <path d="m7 6 10 0-3 5v3l-4 0v-3Z" />
-            <path d="m5 6 2-2" />
-            <path d="m17 6 2-2" />
-        </svg>
-    )
-}
-
 function SettingsIcon(props: { className?: string }) {
     return (
         <svg
@@ -156,8 +110,6 @@ function SessionsPage() {
     const matchRoute = useMatchRoute()
     const { t } = useTranslation()
     const { sessions, isLoading, error, refetch } = useSessions(api)
-    const { preference } = useSessionSortPreference(api)
-    const { setSessionSortPreference, isPending: isSortPreferencePending } = useSessionSortPreferenceMutation(api)
     const { machines } = useMachines(api, true)
 
     const handleRefresh = useCallback(() => {
@@ -170,6 +122,7 @@ function SessionsPage() {
         return `${machineId}::${path}`
     })).size
     const groups = useMemo(() => groupSessionsByDirectory(sessions), [sessions])
+    const { sortMode, isSortPreferencePending, toggleSortMode } = useSortToggle(api, groups)
     const machineLabelsById = useMemo(() => {
         const labels: Record<string, string> = {}
         for (const machine of machines) {
@@ -177,26 +130,6 @@ function SessionsPage() {
         }
         return labels
     }, [machines])
-    const handleToggleSortMode = useCallback(() => {
-        if (!api) {
-            return
-        }
-
-        if (preference.sortMode === 'auto') {
-            void setSessionSortPreference({
-                sortMode: 'manual',
-                manualOrder: snapshotManualOrder(groups),
-                expectedVersion: preference.version
-            })
-            return
-        }
-
-        void setSessionSortPreference({
-            sortMode: 'auto',
-            manualOrder: preference.manualOrder,
-            expectedVersion: preference.version
-        })
-    }, [api, groups, preference.manualOrder, preference.sortMode, preference.version, setSessionSortPreference])
     const sessionMatch = matchRoute({ to: '/sessions/$sessionId', fuzzy: true })
     const selectedSessionId = sessionMatch && sessionMatch.sessionId !== 'new' ? sessionMatch.sessionId : null
     const isSessionsIndex = pathname === '/sessions' || pathname === '/sessions/'
@@ -222,13 +155,13 @@ function SessionsPage() {
                             </button>
                             <button
                                 type="button"
-                                onClick={handleToggleSortMode}
+                                onClick={toggleSortMode}
                                 className="p-1.5 rounded-full text-[var(--app-hint)] hover:text-[var(--app-link)] transition-colors disabled:opacity-50 disabled:cursor-not-allowed"
-                                title={t(preference.sortMode === 'auto' ? 'sessions.sort.auto' : 'sessions.sort.manual')}
-                                aria-pressed={preference.sortMode === 'manual'}
+                                title={t(sortMode === 'auto' ? 'sessions.sort.auto' : 'sessions.sort.manual')}
+                                aria-pressed={sortMode === 'manual'}
                                 disabled={isSortPreferencePending}
                             >
-                                {preference.sortMode === 'auto'
+                                {sortMode === 'auto'
                                     ? <SortIcon className="h-4 w-4" />
                                     : <PinIcon className="h-4 w-4" />}
                             </button>

From 92fca82e97eea933b1803fdb144426e67260678b Mon Sep 17 00:00:00 2001
From: gaius-codius <maher@najemft.com>
Date: Sat, 21 Feb 2026 10:36:10 +0000
Subject: [PATCH 22/27] test(web): add playwright e2e coverage for session sort
 backend

---
 bun.lock                                 |   9 +
 package.json                             |   2 +
 web/.gitignore                           |   2 +
 web/README.md                            |  32 +++
 web/e2e/session-sort.backend.e2e.spec.ts | 289 +++++++++++++++++++++++
 web/package.json                         |   6 +-
 web/playwright.config.ts                 |  37 +++
 7 files changed, 376 insertions(+), 1 deletion(-)
 create mode 100644 web/e2e/session-sort.backend.e2e.spec.ts
 create mode 100644 web/playwright.config.ts

diff --git a/bun.lock b/bun.lock
index 6dd484e38..4434b1131 100644
--- a/bun.lock
+++ b/bun.lock
@@ -122,6 +122,7 @@
         "workbox-window": "^7.4.0",
       },
       "devDependencies": {
+        "@playwright/test": "^1.52.0",
         "@tailwindcss/postcss": "^4.1.18",
         "@testing-library/jest-dom": "^6.6.3",
         "@testing-library/react": "^16.3.0",
@@ -624,6 +625,8 @@
 
     "@pinojs/redact": ["@pinojs/redact@0.4.0", "", {}, "sha512-k2ENnmBugE/rzQfEcdWHcCY+/FM3VLzH9cYEsbdsoqrvzAKRhUZeRNhAZvB8OitQJ1TBed3yqWtdjzS6wJKBwg=="],
 
+    "@playwright/test": ["@playwright/test@1.58.2", "", { "dependencies": { "playwright": "1.58.2" }, "bin": { "playwright": "cli.js" } }, "sha512-akea+6bHYBBfA9uQqSYmlJXn61cTa+jbO87xVLCWbTqbWadRVmhxlXATaOjOgcBaWU4ePo0wB41KMFv3o35IXA=="],
+
     "@radix-ui/number": ["@radix-ui/number@1.1.1", "", {}, "sha512-MkKCwxlXTgz6CFoJx3pCwn07GKp36+aZyu/u2Ln2VrA5DcdyCZkASEDBTd8x5whTQQL5CiYf4prXKLcgQdv29g=="],
 
     "@radix-ui/primitive": ["@radix-ui/primitive@1.1.3", "", {}, "sha512-JTF99U/6XIjCBo0wqkU5sK10glYe27MRRsfwoiq5zzOEZLHU3A3KCMa5X/azekYRCJ0HlwI0crAXS/5dEHTzDg=="],
@@ -2100,6 +2103,10 @@
 
     "pkg-types": ["pkg-types@1.3.1", "", { "dependencies": { "confbox": "^0.1.8", "mlly": "^1.7.4", "pathe": "^2.0.1" } }, "sha512-/Jm5M4RvtBFVkKWRu2BLUTNP8/M2a+UwuAX+ae4770q1qVGtfjG+WTCupoZixokjmHiry8uI+dlY8KXYV5HVVQ=="],
 
+    "playwright": ["playwright@1.58.2", "", { "dependencies": { "playwright-core": "1.58.2" }, "optionalDependencies": { "fsevents": "2.3.2" }, "bin": { "playwright": "cli.js" } }, "sha512-vA30H8Nvkq/cPBnNw4Q8TWz1EJyqgpuinBcHET0YVJVFldr8JDNiU9LaWAE1KqSkRYazuaBhTpB5ZzShOezQ6A=="],
+
+    "playwright-core": ["playwright-core@1.58.2", "", { "bin": { "playwright-core": "cli.js" } }, "sha512-yZkEtftgwS8CsfYo7nm0KE8jsvm6i/PTgVtB8DL726wNf6H2IMsDuxCpJj59KDaxCtSnrWan2AeDqM7JBaultg=="],
+
     "pngjs": ["pngjs@5.0.0", "", {}, "sha512-40QW5YalBNfQo5yRYmiw7Yz6TKKVr3h6970B2YE+3fQpsWcrbj1PzJgxeJ19DRQjhMbKPIuMY8rFaXc8moolVw=="],
 
     "pnpm": ["pnpm@10.27.0", "", { "bin": { "pnpm": "bin/pnpm.cjs", "pnpx": "bin/pnpx.cjs" } }, "sha512-ctaZ2haxF5wUup5k3HHJpAmIy9xlwmTLDkidt96RfyDc9NZNhyNiXylpulLUt+KhFwaC2awqXcrqq3MrfhbwSg=="],
@@ -2978,6 +2985,8 @@
 
     "path-scurry/lru-cache": ["lru-cache@11.2.4", "", {}, "sha512-B5Y16Jr9LB9dHVkh6ZevG+vAbOsNOYCX+sXvFWFu7B3Iz5mijW3zdbMyhsh8ANd2mSWBYdJgnqi+mL7/LrOPYg=="],
 
+    "playwright/fsevents": ["fsevents@2.3.2", "", { "os": "darwin" }, "sha512-xiqMQR4xAeHTuB9uWm+fFRcIOgKBMiOBP+eXiyT7jsgVCq1bkVygt00oASowB7EdtpOHaaPgKt812P9ab+DDKA=="],
+
     "postcss/nanoid": ["nanoid@3.3.11", "", { "bin": { "nanoid": "bin/nanoid.cjs" } }, "sha512-N8SpfPUnUp1bK+PMYW8qSWdl9U+wwNWI4QKxOYDy9JAro3WMX7p2OeVRF9v+347pnakNevPmiHhNmZ2HbFA76w=="],
 
     "pretty-format/ansi-regex": ["ansi-regex@5.0.1", "", {}, "sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ=="],
diff --git a/package.json b/package.json
index 8cc9e91a7..6d3f7b88d 100644
--- a/package.json
+++ b/package.json
@@ -22,6 +22,8 @@
         "test:cli": "cd cli && bun run test",
         "test:hub": "cd hub && bun run test",
         "test:web": "cd web && bun run test",
+        "test:e2e:web": "cd web && bun run test:e2e",
+        "test:e2e:web:session-sort": "cd web && bun run test:e2e:session-sort",
         "clean-session": "bun run hub/scripts/cleanup-sessions.ts",
         "release-all": "cd cli && bun run release-all"
     },
diff --git a/web/.gitignore b/web/.gitignore
index 9ba881afd..670b52ffe 100644
--- a/web/.gitignore
+++ b/web/.gitignore
@@ -1,3 +1,5 @@
 node_modules/
 dist/
 dev-dist/
+playwright-report/
+test-results/
diff --git a/web/README.md b/web/README.md
index 199a09134..1bce212fc 100644
--- a/web/README.md
+++ b/web/README.md
@@ -140,6 +140,38 @@ bun run build:web
 
 The built assets land in `web/dist` and are served by hapi-hub. The single executable can embed these assets.
 
+## E2E (Playwright)
+
+Session-sort backend persistence has Playwright coverage in:
+
+- `web/e2e/session-sort.backend.e2e.spec.ts`
+
+Install browser once:
+
+```bash
+cd web
+bun run test:e2e:install
+```
+
+Run all Playwright tests:
+
+```bash
+cd web
+bun run test:e2e
+```
+
+Run only session-sort flow:
+
+```bash
+cd web
+bun run test:e2e:session-sort
+```
+
+Notes:
+
+- Seeded CLI sessions in these tests must include `metadata.host`; otherwise metadata schema parsing can drop fields and UI grouping/selectors become unstable.
+- `page.reload({ waitUntil: 'networkidle' })` can hang when SSE stays active. Prefer `waitUntil: 'domcontentloaded'` for authenticated app reload assertions.
+
 ## Standalone hosting
 
 You can host `web/dist` on a static host (GitHub Pages, Cloudflare Pages) and point it at any hapi hub:
diff --git a/web/e2e/session-sort.backend.e2e.spec.ts b/web/e2e/session-sort.backend.e2e.spec.ts
new file mode 100644
index 000000000..e9d1869c1
--- /dev/null
+++ b/web/e2e/session-sort.backend.e2e.spec.ts
@@ -0,0 +1,289 @@
+import { expect, test, type Page } from '@playwright/test'
+
+const BASE_URL = process.env.HAPI_E2E_BASE_URL ?? 'http://127.0.0.1:3906'
+const BASE_TOKEN = process.env.HAPI_E2E_CLI_TOKEN ?? 'pw-test-token'
+const RUN_ID = process.env.HAPI_E2E_RUN_ID ?? `${Date.now()}-${Math.random().toString(36).slice(2, 8)}`
+
+function token(namespaceSuffix: string): string {
+    return `${BASE_TOKEN}:session-sort-${RUN_ID}-${namespaceSuffix}`
+}
+
+async function login(page: Page, accessToken: string): Promise<void> {
+    await page.goto(BASE_URL, { waitUntil: 'networkidle' })
+    await page.getByPlaceholder('Access token').fill(accessToken)
+    await page.getByRole('button', { name: 'Sign In' }).click()
+    await expect(page.getByText(/sessions in .* projects/i)).toBeVisible({ timeout: 15_000 })
+}
+
+async function expandAllGroups(page: Page): Promise<void> {
+    const headers = page.locator('button').filter({ has: page.locator('span.font-semibold') })
+    const count = await headers.count()
+    for (let i = 0; i < count; i += 1) {
+        await headers.nth(i).click()
+    }
+    await expect(page.locator('.session-list-item').first()).toBeVisible({ timeout: 10_000 })
+}
+
+async function sessionRowTexts(page: Page): Promise<string[]> {
+    return page.locator('.session-list-item').allTextContents()
+}
+
+function findIndex(rows: string[], text: string): number {
+    return rows.findIndex((row) => row.includes(text))
+}
+
+async function authJwt(accessToken: string): Promise<string> {
+    const response = await fetch(`${BASE_URL}/api/auth`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ accessToken })
+    })
+    expect(response.status).toBe(200)
+    const json = await response.json() as { token: string }
+    return json.token
+}
+
+type SessionSortPreference = {
+    sortMode: 'auto' | 'manual'
+    manualOrder: {
+        groupOrder: string[]
+        sessionOrder: Record<string, string[]>
+    }
+    version: number
+}
+
+async function getPreference(jwt: string): Promise<SessionSortPreference> {
+    const response = await fetch(`${BASE_URL}/api/preferences/session-sort`, {
+        headers: { authorization: `Bearer ${jwt}` }
+    })
+    expect(response.status).toBe(200)
+    const json = await response.json() as { preference: SessionSortPreference }
+    return json.preference
+}
+
+async function putPreference(
+    jwt: string,
+    payload: {
+        sortMode: 'auto' | 'manual'
+        manualOrder: {
+            groupOrder: string[]
+            sessionOrder: Record<string, string[]>
+        }
+        expectedVersion?: number
+    }
+): Promise<{ status: number; json: unknown }> {
+    const response = await fetch(`${BASE_URL}/api/preferences/session-sort`, {
+        method: 'PUT',
+        headers: {
+            authorization: `Bearer ${jwt}`,
+            'content-type': 'application/json'
+        },
+        body: JSON.stringify(payload)
+    })
+    const json = await response.json().catch(() => ({}))
+    return { status: response.status, json }
+}
+
+async function createCliSession(
+    accessToken: string,
+    tag: string,
+    name: string,
+    path: string,
+    machineId: string
+): Promise<void> {
+    const response = await fetch(`${BASE_URL}/cli/sessions`, {
+        method: 'POST',
+        headers: {
+            authorization: `Bearer ${accessToken}`,
+            'content-type': 'application/json'
+        },
+        body: JSON.stringify({
+            tag,
+            metadata: {
+                name,
+                path,
+                host: 'pw-host',
+                machineId,
+                flavor: 'claude'
+            },
+            agentState: null
+        })
+    })
+    expect(response.status).toBe(200)
+}
+
+async function seedBaseSessions(accessToken: string): Promise<void> {
+    await createCliSession(accessToken, 's-alpha', 'Alpha', '/work/repo/a', 'm1')
+    await createCliSession(accessToken, 's-beta', 'Beta', '/work/repo/a', 'm1')
+    await createCliSession(accessToken, 's-gamma', 'Gamma', '/work/repo/b', 'm1')
+    await createCliSession(accessToken, 's-delta', 'Delta', '/work/repo/b', 'm1')
+}
+
+async function resetPreferenceToAuto(accessToken: string): Promise<void> {
+    const jwt = await authJwt(accessToken)
+    const preference = await getPreference(jwt)
+    const result = await putPreference(jwt, {
+        sortMode: 'auto',
+        manualOrder: {
+            groupOrder: [],
+            sessionOrder: {}
+        },
+        expectedVersion: preference.version
+    })
+    expect(result.status).toBe(200)
+}
+
+async function bootstrapNamespace(accessToken: string): Promise<void> {
+    await seedBaseSessions(accessToken)
+    await resetPreferenceToAuto(accessToken)
+}
+
+test.describe.configure({ mode: 'serial' })
+test.setTimeout(180_000)
+
+test('session sort: manual mode UI flow + persistence + stale IDs + new session append', async ({ page }) => {
+    const accessToken = token('manual')
+    await bootstrapNamespace(accessToken)
+
+    await login(page, accessToken)
+    await expandAllGroups(page)
+
+    await expect(page.locator('button[title="Sort: automatic"]')).toBeVisible()
+    await page.locator('button[title="Sort: automatic"]').click()
+    await expect(page.locator('button[title="Sort: manual"]')).toBeVisible()
+
+    const alphaRow = page.locator('.session-list-item', { hasText: 'Alpha' }).first()
+    await alphaRow.click({ button: 'right' })
+    await page.getByRole('menuitem', { name: 'Move Up' }).click()
+
+    const afterMoveRows = await sessionRowTexts(page)
+    expect(findIndex(afterMoveRows, 'Alpha')).toBeLessThan(findIndex(afterMoveRows, 'Beta'))
+
+    await page.locator('.session-list-item', { hasText: 'Alpha' }).first().click({ button: 'right' })
+    await expect(page.getByRole('menuitem', { name: 'Move Up' })).toBeDisabled()
+    await page.keyboard.press('Escape')
+
+    const initialHeaders = await page.locator('span.font-semibold').allTextContents()
+    const initialGroups = initialHeaders.filter((text) => text.includes('repo/'))
+    expect(initialGroups.length).toBeGreaterThan(1)
+    const movedGroup = initialGroups[1]
+
+    const movedGroupHeader = page.locator('button', {
+        has: page.locator('span.font-semibold', { hasText: movedGroup })
+    }).first()
+    await movedGroupHeader.click({ button: 'right' })
+    await page.getByRole('menuitem', { name: 'Move Up' }).click()
+
+    await expect.poll(async () => {
+        const headers = await page.locator('span.font-semibold').allTextContents()
+        const groupNames = headers.filter((text) => text.includes('repo/'))
+        return groupNames[0] ?? ''
+    }).toBe(movedGroup)
+
+    await page.reload({ waitUntil: 'domcontentloaded' })
+    await expect(page.locator('button[title="Sort: manual"]')).toBeVisible({ timeout: 15_000 })
+    await expandAllGroups(page)
+
+    const afterReloadRows = await sessionRowTexts(page)
+    expect(findIndex(afterReloadRows, 'Alpha')).toBeLessThan(findIndex(afterReloadRows, 'Beta'))
+
+    const jwt = await authJwt(accessToken)
+    const preference = await getPreference(jwt)
+    const stalePut = await putPreference(jwt, {
+        sortMode: 'manual',
+        expectedVersion: preference.version,
+        manualOrder: {
+            groupOrder: ['fake-group', ...preference.manualOrder.groupOrder],
+            sessionOrder: {
+                ...preference.manualOrder.sessionOrder,
+                'fake-group': ['fake-session']
+            }
+        }
+    })
+    expect(stalePut.status).toBe(200)
+
+    await expect(page.locator('.session-list-item', { hasText: 'Alpha' }).first()).toBeVisible({ timeout: 15_000 })
+    await expect(page.locator('.session-list-item', { hasText: 'Beta' }).first()).toBeVisible()
+
+    await createCliSession(accessToken, 's-epsilon', 'Epsilon', '/work/repo/a', 'm1')
+
+    await expect(page.locator('.session-list-item', { hasText: 'Epsilon' }).first()).toBeVisible({ timeout: 15_000 })
+    const withNewRows = await sessionRowTexts(page)
+    const alphaIndex = findIndex(withNewRows, 'Alpha')
+    const betaIndex = findIndex(withNewRows, 'Beta')
+    const epsilonIndex = findIndex(withNewRows, 'Epsilon')
+    expect(epsilonIndex).toBeGreaterThan(alphaIndex)
+    expect(epsilonIndex).toBeGreaterThan(betaIndex)
+})
+
+test('session sort: SSE sync across two clients', async ({ browser }) => {
+    const accessToken = token('sse')
+    await bootstrapNamespace(accessToken)
+    await createCliSession(accessToken, 's-epsilon', 'Epsilon', '/work/repo/a', 'm1')
+
+    const contextA = await browser.newContext()
+    const contextB = await browser.newContext()
+    const pageA = await contextA.newPage()
+    const pageB = await contextB.newPage()
+
+    await login(pageA, accessToken)
+    await login(pageB, accessToken)
+    await expandAllGroups(pageA)
+    await expandAllGroups(pageB)
+
+    await pageA.locator('button[title="Sort: automatic"]').click()
+    await expect(pageA.locator('button[title="Sort: manual"]')).toBeVisible()
+    await expect(pageB.locator('button[title="Sort: manual"]')).toBeVisible({ timeout: 15_000 })
+
+    const beforeRows = await sessionRowTexts(pageA)
+    const repoAOrder = ['Alpha', 'Beta', 'Epsilon']
+        .map((name) => ({ name, index: findIndex(beforeRows, name) }))
+        .filter((entry) => entry.index >= 0)
+        .sort((a, b) => a.index - b.index)
+    expect(repoAOrder.length).toBeGreaterThan(1)
+
+    const moveTarget = repoAOrder[1]
+    const expectedAbove = repoAOrder[0]
+
+    await pageA.locator('.session-list-item', { hasText: moveTarget.name }).first().click({ button: 'right' })
+    await pageA.getByRole('menuitem', { name: 'Move Up' }).click()
+
+    await expect.poll(async () => {
+        const rows = await sessionRowTexts(pageB)
+        return {
+            moved: findIndex(rows, moveTarget.name),
+            above: findIndex(rows, expectedAbove.name)
+        }
+    }, { timeout: 20_000 }).toEqual(expect.objectContaining({
+        moved: expect.any(Number),
+        above: expect.any(Number)
+    }))
+
+    const rowsB = await sessionRowTexts(pageB)
+    expect(findIndex(rowsB, moveTarget.name)).toBeLessThan(findIndex(rowsB, expectedAbove.name))
+
+    await contextA.close()
+    await contextB.close()
+})
+
+test('session sort: API conflict path returns 409 version_mismatch', async () => {
+    const accessToken = token('conflict')
+    await bootstrapNamespace(accessToken)
+
+    const jwt = await authJwt(accessToken)
+    const preference = await getPreference(jwt)
+
+    const payload = {
+        sortMode: preference.sortMode,
+        manualOrder: preference.manualOrder,
+        expectedVersion: preference.version
+    }
+
+    const first = await putPreference(jwt, payload)
+    expect(first.status).toBe(200)
+
+    const second = await putPreference(jwt, payload)
+    expect(second.status).toBe(409)
+    expect((second.json as { error?: string }).error).toBe('version_mismatch')
+    expect(((second.json as { preference: SessionSortPreference }).preference.version)).toBeGreaterThan(preference.version)
+})
diff --git a/web/package.json b/web/package.json
index e22d39631..9f82a8754 100644
--- a/web/package.json
+++ b/web/package.json
@@ -9,7 +9,10 @@
         "build": "vite build && cp dist/index.html dist/404.html",
         "typecheck": "tsc --noEmit",
         "preview": "vite preview",
-        "test": "vitest run"
+        "test": "vitest run",
+        "test:e2e": "BUN_BIN=${BUN_BIN:-$(command -v bun || echo $HOME/.bun/bin/bun)} playwright test --config=playwright.config.ts",
+        "test:e2e:session-sort": "BUN_BIN=${BUN_BIN:-$(command -v bun || echo $HOME/.bun/bin/bun)} playwright test --config=playwright.config.ts --grep \"session sort\"",
+        "test:e2e:install": "playwright install chromium"
     },
     "dependencies": {
         "@assistant-ui/react": "^0.11.53",
@@ -44,6 +47,7 @@
         "workbox-window": "^7.4.0"
     },
     "devDependencies": {
+        "@playwright/test": "^1.52.0",
         "@testing-library/jest-dom": "^6.6.3",
         "@testing-library/react": "^16.3.0",
         "@types/react": "^19.2.7",
diff --git a/web/playwright.config.ts b/web/playwright.config.ts
new file mode 100644
index 000000000..178ec7108
--- /dev/null
+++ b/web/playwright.config.ts
@@ -0,0 +1,37 @@
+import { defineConfig, devices } from '@playwright/test'
+
+const port = Number(process.env.HAPI_E2E_PORT ?? '3906')
+const baseUrl = process.env.HAPI_E2E_BASE_URL ?? `http://127.0.0.1:${port}`
+const hapiHome = process.env.HAPI_E2E_HAPI_HOME ?? `/tmp/hapi-playwright-session-sort-${port}`
+const cliApiToken = process.env.HAPI_E2E_CLI_TOKEN ?? 'pw-test-token'
+const bunBin = process.env.BUN_BIN ?? 'bun'
+
+export default defineConfig({
+    testDir: './e2e',
+    timeout: 180_000,
+    expect: {
+        timeout: 20_000
+    },
+    fullyParallel: false,
+    forbidOnly: !!process.env.CI,
+    retries: process.env.CI ? 1 : 0,
+    workers: 1,
+    reporter: process.env.CI ? [['github'], ['line']] : 'line',
+    use: {
+        baseURL: baseUrl,
+        trace: 'on-first-retry',
+        locale: 'en-US'
+    },
+    projects: [
+        {
+            name: 'chromium',
+            use: { ...devices['Desktop Chrome'] }
+        }
+    ],
+    webServer: {
+        command: `${bunBin} run build && rm -rf "${hapiHome}" && mkdir -p "${hapiHome}" && CLI_API_TOKEN=${cliApiToken} HAPI_HOME="${hapiHome}" HAPI_LISTEN_HOST=127.0.0.1 HAPI_LISTEN_PORT=${port} ${bunBin} run --cwd ../hub src/index.ts`,
+        url: `${baseUrl}/health`,
+        timeout: 120_000,
+        reuseExistingServer: false
+    }
+})

From ca3b5a583007b0200b35dc368d94ec9ad39d92d0 Mon Sep 17 00:00:00 2001
From: gaius-codius <206332531+gaius-codius@users.noreply.github.com>
Date: Tue, 7 Apr 2026 05:42:32 +0000
Subject: [PATCH 23/27] feat(web): polish session list, header, and new-session
 UX

---
 hub/src/sync/sessionCache.ts                  |  16 +-
 hub/src/sync/syncEngine.ts                    |  25 +-
 package.json                                  |   1 +
 shared/src/modes.ts                           |  36 +++
 shared/src/schemas.ts                         |   7 +-
 shared/src/sessionSummary.ts                  |   7 +-
 shared/src/types.ts                           |   2 +
 web/e2e/session-metadata.ui.e2e.spec.ts       |  82 +++++
 web/package.json                              |   5 +-
 web/playwright.config.ts                      |  37 +++
 .../components/NewSession/ActionButtons.tsx   |   2 +-
 web/src/components/SessionActionMenu.tsx      |   2 +-
 web/src/components/SessionHeader.test.tsx     | 143 +++++++++
 web/src/components/SessionHeader.tsx          |  54 ++--
 web/src/components/SessionList.test.tsx       | 136 ++++++++
 web/src/components/SessionList.tsx            | 270 +++++++++-------
 web/src/hooks/useLongPress.ts                 |  54 ++--
 web/src/index.css                             | 301 ++++++++++++++++--
 web/src/lib/agentFlavorUtils.test.ts          |  50 +++
 web/src/lib/agentFlavorUtils.ts               |  43 ++-
 web/src/lib/locales/en.ts                     |   8 +
 web/src/lib/locales/zh-CN.ts                  |   8 +
 web/src/router.tsx                            |  17 +-
 web/src/types/api.ts                          |   1 +
 24 files changed, 1089 insertions(+), 218 deletions(-)
 create mode 100644 web/e2e/session-metadata.ui.e2e.spec.ts
 create mode 100644 web/playwright.config.ts
 create mode 100644 web/src/components/SessionHeader.test.tsx
 create mode 100644 web/src/components/SessionList.test.tsx
 create mode 100644 web/src/lib/agentFlavorUtils.test.ts

diff --git a/hub/src/sync/sessionCache.ts b/hub/src/sync/sessionCache.ts
index 618447c7d..c1a45d158 100644
--- a/hub/src/sync/sessionCache.ts
+++ b/hub/src/sync/sessionCache.ts
@@ -136,7 +136,8 @@ export class SessionCache {
             model: stored.model,
             effort: stored.effort,
             permissionMode: existing?.permissionMode,
-            collaborationMode: existing?.collaborationMode
+            collaborationMode: existing?.collaborationMode,
+            modelMode: existing?.modelMode
         }
 
         this.sessions.set(sessionId, session)
@@ -160,6 +161,7 @@ export class SessionCache {
         model?: string | null
         effort?: string | null
         collaborationMode?: CodexCollaborationMode
+        modelMode?: Session['modelMode']
     }): void {
         const t = clampAliveTime(payload.time)
         if (!t) return
@@ -173,6 +175,7 @@ export class SessionCache {
         const previousModel = session.model
         const previousEffort = session.effort
         const previousCollaborationMode = session.collaborationMode
+        const previousModelMode = session.modelMode
 
         session.active = true
         session.activeAt = Math.max(session.activeAt, t)
@@ -200,6 +203,9 @@ export class SessionCache {
         if (payload.collaborationMode !== undefined) {
             session.collaborationMode = payload.collaborationMode
         }
+        if (payload.modelMode !== undefined) {
+            session.modelMode = payload.modelMode
+        }
 
         const now = Date.now()
         const lastBroadcastAt = this.lastBroadcastAtBySessionId.get(session.id) ?? 0
@@ -207,6 +213,7 @@ export class SessionCache {
             || previousModel !== session.model
             || previousEffort !== session.effort
             || previousCollaborationMode !== session.collaborationMode
+            || previousModelMode !== session.modelMode
         const shouldBroadcast = (!wasActive && session.active)
             || (wasThinking !== session.thinking)
             || modeChanged
@@ -224,7 +231,8 @@ export class SessionCache {
                     permissionMode: session.permissionMode,
                     model: session.model,
                     effort: session.effort,
-                    collaborationMode: session.collaborationMode
+                    collaborationMode: session.collaborationMode,
+                    modelMode: session.modelMode
                 }
             })
         }
@@ -266,6 +274,7 @@ export class SessionCache {
             model?: string | null
             effort?: string | null
             collaborationMode?: CodexCollaborationMode
+            modelMode?: Session['modelMode']
         }
     ): void {
         const session = this.sessions.get(sessionId) ?? this.refreshSession(sessionId)
@@ -301,6 +310,9 @@ export class SessionCache {
         if (config.collaborationMode !== undefined) {
             session.collaborationMode = config.collaborationMode
         }
+        if (config.modelMode !== undefined) {
+            session.modelMode = config.modelMode
+        }
 
         this.publisher.emit({ type: 'session-updated', sessionId, data: session })
     }
diff --git a/hub/src/sync/syncEngine.ts b/hub/src/sync/syncEngine.ts
index 6b5be2f1c..7e27fcf99 100644
--- a/hub/src/sync/syncEngine.ts
+++ b/hub/src/sync/syncEngine.ts
@@ -7,7 +7,13 @@
  * - No E2E encryption; data is stored as JSON in SQLite
  */
 
-import type { CodexCollaborationMode, DecryptedMessage, PermissionMode, Session, SyncEvent } from '@hapi/protocol/types'
+import type {
+    CodexCollaborationMode,
+    DecryptedMessage,
+    PermissionMode,
+    Session,
+    SyncEvent
+} from '@hapi/protocol/types'
 import type { Server } from 'socket.io'
 import type { Store } from '../store'
 import type { RpcRegistry } from '../socket/rpcRegistry'
@@ -42,6 +48,7 @@ export type ResumeSessionResult =
     | { type: 'success'; sessionId: string }
     | { type: 'error'; message: string; code: 'session_not_found' | 'access_denied' | 'no_machine_online' | 'resume_unavailable' | 'resume_failed' }
 
+
 export class SyncEngine {
     private readonly eventPublisher: EventPublisher
     private readonly sessionCache: SessionCache
@@ -97,6 +104,7 @@ export class SyncEngine {
         return this.sessionCache.getSessionsByNamespace(namespace)
     }
 
+
     getSession(sessionId: string): Session | undefined {
         return this.sessionCache.getSession(sessionId) ?? this.sessionCache.refreshSession(sessionId) ?? undefined
     }
@@ -190,6 +198,7 @@ export class SyncEngine {
         model?: string | null
         effort?: string | null
         collaborationMode?: CodexCollaborationMode
+        modelMode?: Session['modelMode']
     }): void {
         this.sessionCache.handleSessionAlive(payload)
     }
@@ -293,9 +302,16 @@ export class SyncEngine {
             model?: string | null
             effort?: string | null
             collaborationMode?: CodexCollaborationMode
+            modelMode?: Session['modelMode']
         }
     ): Promise<void> {
-        const result = await this.rpcGateway.requestSessionConfig(sessionId, config)
+        const rpcConfig = {
+            permissionMode: config.permissionMode,
+            model: config.model,
+            effort: config.effort,
+            collaborationMode: config.collaborationMode
+        }
+        const result = await this.rpcGateway.requestSessionConfig(sessionId, rpcConfig)
         if (!result || typeof result !== 'object') {
             throw new Error('Invalid response from session config RPC')
         }
@@ -312,7 +328,10 @@ export class SyncEngine {
             throw new Error('Missing applied session config')
         }
 
-        this.sessionCache.applySessionConfig(sessionId, applied)
+        this.sessionCache.applySessionConfig(sessionId, {
+            ...applied,
+            modelMode: config.modelMode
+        })
     }
 
     async spawnSession(
diff --git a/package.json b/package.json
index 8cc9e91a7..8c0b05347 100644
--- a/package.json
+++ b/package.json
@@ -22,6 +22,7 @@
         "test:cli": "cd cli && bun run test",
         "test:hub": "cd hub && bun run test",
         "test:web": "cd web && bun run test",
+        "test:e2e:web": "cd web && bun run test:e2e",
         "clean-session": "bun run hub/scripts/cleanup-sessions.ts",
         "release-all": "cd cli && bun run release-all"
     },
diff --git a/shared/src/modes.ts b/shared/src/modes.ts
index 76b0fb00c..c3d1068b9 100644
--- a/shared/src/modes.ts
+++ b/shared/src/modes.ts
@@ -35,6 +35,9 @@ export const PERMISSION_MODES = [
 ] as const
 export type PermissionMode = typeof PERMISSION_MODES[number]
 
+export const MODEL_MODES = ['default', 'sonnet', 'opus'] as const
+export type ModelMode = typeof MODEL_MODES[number]
+
 export const CLAUDE_MODEL_PRESETS = ['sonnet', 'sonnet[1m]', 'opus', 'opus[1m]'] as const
 export type ClaudeModelPreset = typeof CLAUDE_MODEL_PRESETS[number]
 
@@ -82,6 +85,11 @@ export type PermissionModeOption = {
     tone: PermissionModeTone
 }
 
+export type ModelModeOption = {
+    mode: ModelMode
+    label: string
+}
+
 export type CodexCollaborationModeOption = {
     mode: CodexCollaborationMode
     label: string
@@ -94,6 +102,12 @@ export const CLAUDE_MODEL_LABELS: Record<ClaudeModelPreset, string> = {
     'opus[1m]': 'Opus 1M'
 }
 
+export const MODEL_MODE_LABELS: Record<ModelMode, string> = {
+    default: 'Default',
+    sonnet: 'Sonnet',
+    opus: 'Opus'
+}
+
 export const CODEX_COLLABORATION_MODE_LABELS: Record<CodexCollaborationMode, string> = {
     default: 'Default',
     plan: 'Plan'
@@ -152,6 +166,28 @@ export function isPermissionModeAllowedForFlavor(mode: PermissionMode, flavor?:
     return getPermissionModesForFlavor(flavor).includes(mode)
 }
 
+export function getModelModesForFlavor(flavor?: string | null): readonly ModelMode[] {
+    if (flavor === 'codex' || flavor === 'gemini' || flavor === 'opencode' || flavor === 'cursor') {
+        return []
+    }
+    return MODEL_MODES
+}
+
+export function isModelModeAllowedForFlavor(mode: ModelMode, flavor?: string | null): boolean {
+    return getModelModesForFlavor(flavor).includes(mode)
+}
+
+export function getModelModeLabel(mode: ModelMode): string {
+    return MODEL_MODE_LABELS[mode]
+}
+
+export function getModelModeOptionsForFlavor(flavor?: string | null): ModelModeOption[] {
+    return getModelModesForFlavor(flavor).map((mode) => ({
+        mode,
+        label: getModelModeLabel(mode)
+    }))
+}
+
 export function getCodexCollaborationModeOptions(): CodexCollaborationModeOption[] {
     return CODEX_COLLABORATION_MODES.map((mode) => ({
         mode,
diff --git a/shared/src/schemas.ts b/shared/src/schemas.ts
index 52ec83737..a0b696e0d 100644
--- a/shared/src/schemas.ts
+++ b/shared/src/schemas.ts
@@ -1,9 +1,9 @@
 import { z } from 'zod'
-import { CODEX_COLLABORATION_MODES, PERMISSION_MODES } from './modes'
+import { CODEX_COLLABORATION_MODES, MODEL_MODES, PERMISSION_MODES } from './modes'
 
 export const PermissionModeSchema = z.enum(PERMISSION_MODES)
+export const ModelModeSchema = z.enum(MODEL_MODES)
 export const CodexCollaborationModeSchema = z.enum(CODEX_COLLABORATION_MODES)
-
 const MetadataSummarySchema = z.object({
     text: z.string(),
     updatedAt: z.number()
@@ -177,6 +177,7 @@ export const SessionSchema = z.object({
     model: z.string().nullable(),
     effort: z.string().nullable(),
     permissionMode: PermissionModeSchema.optional(),
+    modelMode: ModelModeSchema.optional(),
     collaborationMode: CodexCollaborationModeSchema.optional()
 })
 
@@ -236,7 +237,7 @@ export const SyncEventSchema = z.discriminatedUnion('type', [
             status: z.string(),
             subscriptionId: z.string().optional()
         }).optional()
-    })
+    }),
 ])
 
 export type SyncEvent = z.infer<typeof SyncEventSchema>
diff --git a/shared/src/sessionSummary.ts b/shared/src/sessionSummary.ts
index e717a57dd..51d93aae1 100644
--- a/shared/src/sessionSummary.ts
+++ b/shared/src/sessionSummary.ts
@@ -1,3 +1,4 @@
+import type { ModelMode, PermissionMode } from './modes'
 import type { Session, WorktreeMetadata } from './schemas'
 
 export type SessionSummaryMetadata = {
@@ -20,6 +21,8 @@ export type SessionSummary = {
     pendingRequestsCount: number
     model: string | null
     effort: string | null
+    permissionMode?: PermissionMode
+    modelMode?: ModelMode
 }
 
 export function toSessionSummary(session: Session): SessionSummary {
@@ -49,6 +52,8 @@ export function toSessionSummary(session: Session): SessionSummary {
         todoProgress,
         pendingRequestsCount,
         model: session.model,
-        effort: session.effort
+        effort: session.effort,
+        permissionMode: session.permissionMode,
+        modelMode: session.modelMode
     }
 }
diff --git a/shared/src/types.ts b/shared/src/types.ts
index 37333a60e..1d6466580 100644
--- a/shared/src/types.ts
+++ b/shared/src/types.ts
@@ -28,6 +28,8 @@ export type {
     GeminiPermissionMode,
     OpencodePermissionMode,
     ClaudeModelPreset,
+    ModelMode,
+    ModelModeOption,
     PermissionMode,
     PermissionModeOption,
     PermissionModeTone
diff --git a/web/e2e/session-metadata.ui.e2e.spec.ts b/web/e2e/session-metadata.ui.e2e.spec.ts
new file mode 100644
index 000000000..887c48965
--- /dev/null
+++ b/web/e2e/session-metadata.ui.e2e.spec.ts
@@ -0,0 +1,82 @@
+import { expect, test, type Page } from '@playwright/test'
+
+const BASE_URL = process.env.HAPI_E2E_BASE_URL ?? 'http://127.0.0.1:3906'
+const BASE_TOKEN = process.env.HAPI_E2E_CLI_TOKEN ?? 'pw-test-token'
+const RUN_ID = process.env.HAPI_E2E_RUN_ID ?? `${Date.now()}-${Math.random().toString(36).slice(2, 8)}`
+
+function token(namespaceSuffix: string): string {
+    return `${BASE_TOKEN}:session-metadata-${RUN_ID}-${namespaceSuffix}`
+}
+
+async function login(page: Page, accessToken: string): Promise<void> {
+    await page.goto(BASE_URL, { waitUntil: 'networkidle' })
+    await page.getByPlaceholder('Access token').fill(accessToken)
+    await page.getByRole('button', { name: 'Sign In' }).click()
+    await expect(page.getByText(/sessions in .* projects/i)).toBeVisible({ timeout: 15_000 })
+}
+
+async function createCliSession(
+    accessToken: string,
+    tag: string,
+    name: string,
+    path: string,
+    machineId: string
+): Promise<string> {
+    const response = await fetch(`${BASE_URL}/cli/sessions`, {
+        method: 'POST',
+        headers: {
+            authorization: `Bearer ${accessToken}`,
+            'content-type': 'application/json'
+        },
+        body: JSON.stringify({
+            tag,
+            metadata: {
+                name,
+                path,
+                host: 'pw-host',
+                machineId,
+                flavor: 'codex',
+                worktree: {
+                    basePath: '/work/repo',
+                    branch: 'feature/chips',
+                    name: 'feature-chips'
+                }
+            },
+            agentState: null,
+            model: 'gpt-5.4',
+            effort: 'very-high'
+        })
+    })
+    expect(response.status).toBe(200)
+    const json = await response.json() as { session: { id: string } }
+    return json.session.id
+}
+
+test('session metadata chips render in list and header', async ({ page }) => {
+    const accessToken = token('chips')
+
+    const activeSessionId = await createCliSession(accessToken, 's-active', 'Active Session', '/work/repo/project-a', 'm1')
+    await createCliSession(accessToken, 's-inactive', 'Inactive Session', '/work/repo/project-a', 'm1')
+
+    await login(page, accessToken)
+
+    await page.getByRole('button', {
+        name: /work\/repo/i
+    }).first().click()
+
+    const activeRow = page.locator('.session-list-item', { hasText: 'Active Session' }).first()
+    await expect(activeRow).toContainText('codex')
+    await expect(activeRow).toContainText('gpt-5.4')
+    await expect(activeRow).toContainText('feature/chips')
+
+    await page.goto(`${BASE_URL}/sessions/${activeSessionId}`, { waitUntil: 'domcontentloaded' })
+
+    const headerTitle = page.locator('div.truncate.font-semibold').first()
+    await expect(headerTitle).toHaveText('Active Session')
+
+    const headerMeta = headerTitle.locator('xpath=following-sibling::div[1]')
+    await expect(headerMeta).toContainText('codex')
+    await expect(headerMeta).toContainText('gpt-5.4')
+    await expect(headerMeta).toContainText('Very High')
+    await expect(headerMeta).toContainText('feature/chips')
+})
diff --git a/web/package.json b/web/package.json
index e22d39631..e719e5eb4 100644
--- a/web/package.json
+++ b/web/package.json
@@ -9,7 +9,9 @@
         "build": "vite build && cp dist/index.html dist/404.html",
         "typecheck": "tsc --noEmit",
         "preview": "vite preview",
-        "test": "vitest run"
+        "test": "vitest run",
+        "test:e2e": "BUN_BIN=${BUN_BIN:-$(command -v bun || echo $HOME/.bun/bin/bun)} playwright test --config=playwright.config.ts",
+        "test:e2e:install": "playwright install chromium"
     },
     "dependencies": {
         "@assistant-ui/react": "^0.11.53",
@@ -44,6 +46,7 @@
         "workbox-window": "^7.4.0"
     },
     "devDependencies": {
+        "@playwright/test": "^1.52.0",
         "@testing-library/jest-dom": "^6.6.3",
         "@testing-library/react": "^16.3.0",
         "@types/react": "^19.2.7",
diff --git a/web/playwright.config.ts b/web/playwright.config.ts
new file mode 100644
index 000000000..531209ce3
--- /dev/null
+++ b/web/playwright.config.ts
@@ -0,0 +1,37 @@
+import { defineConfig, devices } from '@playwright/test'
+
+const port = Number(process.env.HAPI_E2E_PORT ?? '3906')
+const baseUrl = process.env.HAPI_E2E_BASE_URL ?? `http://127.0.0.1:${port}`
+const hapiHome = process.env.HAPI_E2E_HAPI_HOME ?? `/tmp/hapi-playwright-${port}`
+const cliApiToken = process.env.HAPI_E2E_CLI_TOKEN ?? 'pw-test-token'
+const bunBin = process.env.BUN_BIN ?? 'bun'
+
+export default defineConfig({
+    testDir: './e2e',
+    timeout: 180_000,
+    expect: {
+        timeout: 20_000
+    },
+    fullyParallel: false,
+    forbidOnly: !!process.env.CI,
+    retries: process.env.CI ? 1 : 0,
+    workers: 1,
+    reporter: process.env.CI ? [['github'], ['line']] : 'line',
+    use: {
+        baseURL: baseUrl,
+        trace: 'on-first-retry',
+        locale: 'en-US'
+    },
+    projects: [
+        {
+            name: 'chromium',
+            use: { ...devices['Desktop Chrome'] }
+        }
+    ],
+    webServer: {
+        command: `${bunBin} run build && rm -rf "${hapiHome}" && mkdir -p "${hapiHome}" && CLI_API_TOKEN=${cliApiToken} HAPI_HOME="${hapiHome}" HAPI_LISTEN_HOST=127.0.0.1 HAPI_LISTEN_PORT=${port} ${bunBin} run --cwd ../hub src/index.ts`,
+        url: `${baseUrl}/health`,
+        timeout: 120_000,
+        reuseExistingServer: false
+    }
+})
diff --git a/web/src/components/NewSession/ActionButtons.tsx b/web/src/components/NewSession/ActionButtons.tsx
index 00b6b9f81..72292b247 100644
--- a/web/src/components/NewSession/ActionButtons.tsx
+++ b/web/src/components/NewSession/ActionButtons.tsx
@@ -13,7 +13,7 @@ export function ActionButtons(props: {
     const { t } = useTranslation()
 
     return (
-        <div className="flex gap-2 px-3 pt-3 pb-[calc(env(safe-area-inset-bottom)+1rem)]">
+        <div className="sticky bottom-0 z-10 flex gap-2 border-t border-[var(--app-divider)] bg-[var(--app-bg)] px-3 pt-3 pb-[calc(env(safe-area-inset-bottom)+1rem)] shadow-[0_-8px_24px_rgba(0,0,0,0.06)]">
             <Button
                 variant="secondary"
                 onClick={props.onCancel}
diff --git a/web/src/components/SessionActionMenu.tsx b/web/src/components/SessionActionMenu.tsx
index 88d6ab97c..4a4574803 100644
--- a/web/src/components/SessionActionMenu.tsx
+++ b/web/src/components/SessionActionMenu.tsx
@@ -191,7 +191,7 @@ export function SessionActionMenu(props: SessionActionMenuProps) {
         if (!isOpen) return
 
         const frame = window.requestAnimationFrame(() => {
-            const firstItem = menuRef.current?.querySelector<HTMLElement>('[role="menuitem"]')
+            const firstItem = menuRef.current?.querySelector<HTMLElement>('[role="menuitem"]:not([disabled])')
             firstItem?.focus()
         })
 
diff --git a/web/src/components/SessionHeader.test.tsx b/web/src/components/SessionHeader.test.tsx
new file mode 100644
index 000000000..0fdc7da9e
--- /dev/null
+++ b/web/src/components/SessionHeader.test.tsx
@@ -0,0 +1,143 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { renderToStaticMarkup } from 'react-dom/server'
+import { I18nProvider } from '@/lib/i18n-context'
+import { SessionHeader } from './SessionHeader'
+
+vi.mock('@/hooks/useTelegram', () => ({
+    isTelegramApp: vi.fn(() => false)
+}))
+
+vi.mock('@/hooks/mutations/useSessionActions', () => ({
+    useSessionActions: () => ({
+        archiveSession: vi.fn(),
+        renameSession: vi.fn(),
+        deleteSession: vi.fn(),
+        isPending: false
+    })
+}))
+
+vi.mock('@/components/SessionActionMenu', () => ({
+    SessionActionMenu: () => null
+}))
+
+vi.mock('@/components/RenameSessionDialog', () => ({
+    RenameSessionDialog: () => null
+}))
+
+vi.mock('@/components/ui/ConfirmDialog', () => ({
+    ConfirmDialog: () => null
+}))
+
+function renderHeader(sessionOverrides: Record<string, unknown> = {}) {
+    const session = {
+        id: '1234567890abcdef',
+        active: true,
+        createdAt: 0,
+        updatedAt: 0,
+        activeAt: 0,
+        seq: 0,
+        namespace: 'default',
+        metadataVersion: 0,
+        agentStateVersion: 0,
+        thinking: false,
+        thinkingAt: 0,
+        metadata: {
+            name: 'Named Session',
+            path: '/workspace/project-name',
+            flavor: 'codex',
+            worktree: { branch: 'feature/chips', basePath: '/workspace/project-name' }
+        },
+        model: 'gpt-5.4',
+        effort: 'very-high',
+        permissionMode: 'yolo',
+        collaborationMode: 'default',
+        agentState: null,
+        ...sessionOverrides
+    }
+
+    return renderToStaticMarkup(
+        <I18nProvider>
+            <SessionHeader
+                session={session as never}
+                onBack={vi.fn()}
+                onViewFiles={vi.fn()}
+                api={null}
+            />
+        </I18nProvider>
+    )
+}
+
+describe('SessionHeader', () => {
+    beforeEach(() => {
+        vi.clearAllMocks()
+        const localStorageMock = {
+            getItem: vi.fn(() => 'en'),
+            setItem: vi.fn(),
+            removeItem: vi.fn()
+        }
+        Object.defineProperty(window, 'localStorage', { value: localStorageMock, configurable: true })
+    })
+
+    it('renders full metadata chips', () => {
+        const markup = renderHeader()
+        expect(markup).toContain('Named Session')
+        expect(markup).toContain('codex')
+        expect(markup).toContain('gpt-5.4')
+        expect(markup).toContain('Very High')
+        expect(markup).toContain('Yolo')
+        expect(markup).toContain('feature/chips')
+        expect(markup).toContain('text-[var(--app-flavor-codex-text)] font-medium')
+        expect(markup).toContain('text-[var(--app-hint)] opacity-40')
+    })
+
+    it('hides effort when absent', () => {
+        const markup = renderHeader({ effort: null })
+        expect(markup).not.toContain('Very High')
+    })
+
+    it('hides permission mode when default', () => {
+        const markup = renderHeader({ permissionMode: 'default' })
+        expect(markup).not.toContain('Yolo')
+    })
+
+    it('hides worktree when absent', () => {
+        const markup = renderHeader({
+            metadata: {
+                name: 'Named Session',
+                path: '/workspace/project-name',
+                flavor: 'codex'
+            }
+        })
+        expect(markup).not.toContain('feature/chips')
+    })
+
+    it('falls back to the path basename for the title', () => {
+        const markup = renderHeader({
+            metadata: {
+                path: '/workspace/path-title',
+                flavor: 'codex'
+            }
+        })
+        expect(markup).toContain('path-title')
+    })
+
+    it('falls back to the short id when no path or summary exists', () => {
+        const markup = renderHeader({
+            id: 'abcdef1234567890',
+            metadata: null
+        })
+        expect(markup).toContain('abcdef12')
+    })
+
+    it('uses hint styling for unknown flavors', () => {
+        const markup = renderHeader({
+            metadata: {
+                name: 'Mystery Session',
+                path: '/workspace/mystery',
+                flavor: 'mystery'
+            }
+        })
+        expect(markup).toContain('mystery')
+        expect(markup).toContain('text-[var(--app-hint)] font-medium')
+    })
+})
diff --git a/web/src/components/SessionHeader.tsx b/web/src/components/SessionHeader.tsx
index 1d3f8bd84..416f5a9ff 100644
--- a/web/src/components/SessionHeader.tsx
+++ b/web/src/components/SessionHeader.tsx
@@ -1,4 +1,5 @@
-import { useId, useMemo, useRef, useState } from 'react'
+import { Fragment, type ReactNode, useId, useMemo, useRef, useState } from 'react'
+import { getPermissionModeLabel, isPermissionModeAllowedForFlavor } from '@hapi/protocol'
 import type { Session } from '@/types/api'
 import type { ApiClient } from '@/api/client'
 import { isTelegramApp } from '@/hooks/useTelegram'
@@ -6,6 +7,7 @@ import { useSessionActions } from '@/hooks/mutations/useSessionActions'
 import { SessionActionMenu } from '@/components/SessionActionMenu'
 import { RenameSessionDialog } from '@/components/RenameSessionDialog'
 import { ConfirmDialog } from '@/components/ui/ConfirmDialog'
+import { formatEffortLabel, getFlavorTextClass, META_DOT_SEPARATOR_CLASS } from '@/lib/agentFlavorUtils'
 import { getSessionModelLabel } from '@/lib/sessionModelLabel'
 import { useTranslation } from '@/lib/use-translation'
 
@@ -70,8 +72,25 @@ export function SessionHeader(props: {
     const { t } = useTranslation()
     const { session, api, onSessionDeleted } = props
     const title = useMemo(() => getSessionTitle(session), [session])
+    const flavor = session.metadata?.flavor?.trim() ?? null
     const worktreeBranch = session.metadata?.worktree?.branch
     const modelLabel = getSessionModelLabel(session)
+    const flavorLabel = flavor?.toLowerCase() || 'unknown'
+    const effortLabel = formatEffortLabel(session.effort)
+    const permissionMode = session.permissionMode
+        && session.permissionMode !== 'default'
+        && isPermissionModeAllowedForFlavor(session.permissionMode, flavor)
+        ? getPermissionModeLabel(session.permissionMode)
+        : null
+    const metadataItems = [
+        <span key="flavor" className={getFlavorTextClass(flavor)}>
+            {flavorLabel}
+        </span>,
+        modelLabel ? <span key="model">{modelLabel.value}</span> : null,
+        effortLabel ? <span key="effort">{effortLabel}</span> : null,
+        permissionMode ? <span key="permission">{permissionMode}</span> : null,
+        worktreeBranch ? <span key="worktree">{worktreeBranch}</span> : null
+    ].filter(Boolean) as ReactNode[]
 
     const [menuOpen, setMenuOpen] = useState(false)
     const [menuAnchorPoint, setMenuAnchorPoint] = useState<{ x: number; y: number }>({ x: 0, y: 0 })
@@ -100,7 +119,6 @@ export function SessionHeader(props: {
         setMenuOpen((open) => !open)
     }
 
-    // In Telegram, don't render header (Telegram provides its own)
     if (isTelegramApp()) {
         return null
     }
@@ -108,12 +126,11 @@ export function SessionHeader(props: {
     return (
         <>
             <div className="bg-[var(--app-bg)] pt-[env(safe-area-inset-top)]">
-                <div className="mx-auto w-full max-w-content flex items-center gap-2 p-3">
-                    {/* Back button */}
+                <div className="mx-auto flex w-full max-w-content items-start gap-2 p-3">
                     <button
                         type="button"
                         onClick={props.onBack}
-                        className="flex h-8 w-8 items-center justify-center rounded-full text-[var(--app-hint)] transition-colors hover:bg-[var(--app-secondary-bg)] hover:text-[var(--app-fg)]"
+                        className="flex h-8 w-8 self-start items-center justify-center rounded-full text-[var(--app-hint)] transition-colors hover:bg-[var(--app-secondary-bg)] hover:text-[var(--app-fg)]"
                     >
                         <svg
                             xmlns="http://www.w3.org/2000/svg"
@@ -130,24 +147,19 @@ export function SessionHeader(props: {
                         </svg>
                     </button>
 
-                    {/* Session info - two lines: title and path */}
                     <div className="min-w-0 flex-1">
                         <div className="truncate font-semibold">
                             {title}
                         </div>
-                        <div className="flex flex-wrap items-center gap-x-3 gap-y-0.5 text-xs text-[var(--app-hint)]">
-                            <span className="inline-flex items-center gap-1">
-                                <span aria-hidden="true">❖</span>
-                                {session.metadata?.flavor?.trim() || 'unknown'}
-                            </span>
-                            {modelLabel ? (
-                                <span>
-                                    {t(modelLabel.key)}: {modelLabel.value}
-                                </span>
-                            ) : null}
-                            {worktreeBranch ? (
-                                <span>{t('session.item.worktree')}: {worktreeBranch}</span>
-                            ) : null}
+                        <div className="flex flex-wrap items-center gap-x-2 gap-y-0.5 text-xs text-[var(--app-hint)]">
+                            {metadataItems.map((item, index) => (
+                                <Fragment key={index}>
+                                    {index > 0 ? (
+                                        <span aria-hidden="true" className={META_DOT_SEPARATOR_CLASS}>·</span>
+                                    ) : null}
+                                    {item}
+                                </Fragment>
+                            ))}
                         </div>
                     </div>
 
@@ -155,7 +167,7 @@ export function SessionHeader(props: {
                         <button
                             type="button"
                             onClick={props.onViewFiles}
-                            className="flex h-8 w-8 items-center justify-center rounded-full text-[var(--app-hint)] transition-colors hover:bg-[var(--app-secondary-bg)] hover:text-[var(--app-fg)]"
+                            className="flex h-8 w-8 self-start items-center justify-center rounded-full text-[var(--app-hint)] transition-colors hover:bg-[var(--app-secondary-bg)] hover:text-[var(--app-fg)]"
                             title={t('session.title')}
                         >
                             <FilesIcon />
@@ -170,7 +182,7 @@ export function SessionHeader(props: {
                         aria-haspopup="menu"
                         aria-expanded={menuOpen}
                         aria-controls={menuOpen ? menuId : undefined}
-                        className="flex h-8 w-8 items-center justify-center rounded-full text-[var(--app-hint)] transition-colors hover:bg-[var(--app-secondary-bg)] hover:text-[var(--app-fg)]"
+                        className="flex h-8 w-8 self-start items-center justify-center rounded-full text-[var(--app-hint)] transition-colors hover:bg-[var(--app-secondary-bg)] hover:text-[var(--app-fg)]"
                         title={t('session.more')}
                     >
                         <MoreVerticalIcon />
diff --git a/web/src/components/SessionList.test.tsx b/web/src/components/SessionList.test.tsx
new file mode 100644
index 000000000..0e64fcf70
--- /dev/null
+++ b/web/src/components/SessionList.test.tsx
@@ -0,0 +1,136 @@
+import { describe, expect, it } from 'vitest'
+import type { SessionSummary } from '@/types/api'
+import { UNKNOWN_MACHINE_ID, groupSessionsByDirectory } from './SessionList'
+
+function makeSession(overrides: Partial<SessionSummary> = {}): SessionSummary {
+    return {
+        id: 'session-1',
+        active: false,
+        thinking: false,
+        activeAt: 0,
+        updatedAt: 0,
+        metadata: {
+            path: '/workspace/project',
+            machineId: 'machine-a'
+        },
+        todoProgress: null,
+        pendingRequestsCount: 0,
+        model: null,
+        effort: null,
+        ...overrides
+    }
+}
+
+describe('groupSessionsByDirectory', () => {
+    it('groups by machine and directory', () => {
+        const groups = groupSessionsByDirectory([
+            makeSession({ id: 'session-a', metadata: { path: '/workspace/project', machineId: 'machine-a' } }),
+            makeSession({ id: 'session-b', metadata: { path: '/workspace/project', machineId: 'machine-b' } })
+        ])
+
+        expect(groups).toHaveLength(2)
+        expect(groups.map(group => group.key)).toEqual([
+            'machine-a::/workspace/project',
+            'machine-b::/workspace/project'
+        ])
+    })
+
+    it('sorts active sessions before inactive sessions within a group', () => {
+        const [group] = groupSessionsByDirectory([
+            makeSession({ id: 'inactive', active: false, updatedAt: 20 }),
+            makeSession({ id: 'active', active: true, updatedAt: 10 })
+        ])
+
+        expect(group.sessions.map(session => session.id)).toEqual(['active', 'inactive'])
+    })
+
+    it('ranks active sessions with pending requests ahead of other active sessions', () => {
+        const [group] = groupSessionsByDirectory([
+            makeSession({ id: 'active-no-pending', active: true, updatedAt: 30, pendingRequestsCount: 0 }),
+            makeSession({ id: 'active-pending', active: true, updatedAt: 10, pendingRequestsCount: 2 })
+        ])
+
+        expect(group.sessions.map(session => session.id)).toEqual(['active-pending', 'active-no-pending'])
+    })
+
+    it('sorts groups with active sessions ahead of inactive groups', () => {
+        const groups = groupSessionsByDirectory([
+            makeSession({
+                id: 'inactive-group',
+                updatedAt: 100,
+                metadata: { path: '/workspace/inactive', machineId: 'machine-a' }
+            }),
+            makeSession({
+                id: 'active-group',
+                active: true,
+                updatedAt: 10,
+                metadata: { path: '/workspace/active', machineId: 'machine-a' }
+            })
+        ])
+
+        expect(groups.map(group => group.directory)).toEqual([
+            '/workspace/active',
+            '/workspace/inactive'
+        ])
+    })
+
+    it('groups worktree sessions by basePath', () => {
+        const [group] = groupSessionsByDirectory([
+            makeSession({
+                id: 'worktree-a',
+                metadata: {
+                    path: '/workspace/project-worktrees/feature-a',
+                    machineId: 'machine-a',
+                    worktree: {
+                        branch: 'feature-a',
+                        basePath: '/workspace/project',
+                        name: 'feature-a'
+                    }
+                }
+            }),
+            makeSession({
+                id: 'worktree-b',
+                metadata: {
+                    path: '/workspace/project-worktrees/feature-b',
+                    machineId: 'machine-a',
+                    worktree: {
+                        branch: 'feature-b',
+                        basePath: '/workspace/project',
+                        name: 'feature-b'
+                    }
+                }
+            })
+        ])
+
+        expect(group.directory).toBe('/workspace/project')
+        expect(group.key).toBe('machine-a::/workspace/project')
+        expect(group.sessions).toHaveLength(2)
+    })
+
+    it('uses the Other fallback when path metadata is missing', () => {
+        const [group] = groupSessionsByDirectory([
+            makeSession({
+                id: 'no-path',
+                metadata: {
+                    machineId: undefined
+                } as SessionSummary['metadata']
+            })
+        ])
+
+        expect(group.directory).toBe('Other')
+        expect(group.key).toBe(`${UNKNOWN_MACHINE_ID}::Other`)
+    })
+
+    it('derives compact display names from the directory path', () => {
+        const [group] = groupSessionsByDirectory([
+            makeSession({
+                metadata: {
+                    path: '/Users/dev/projects/hapi',
+                    machineId: 'machine-a'
+                }
+            })
+        ])
+
+        expect(group.displayName).toBe('projects/hapi')
+    })
+})
diff --git a/web/src/components/SessionList.tsx b/web/src/components/SessionList.tsx
index 8abb19343..744bd1a60 100644
--- a/web/src/components/SessionList.tsx
+++ b/web/src/components/SessionList.tsx
@@ -1,4 +1,4 @@
-import { useEffect, useMemo, useState } from 'react'
+import { Fragment, type ReactNode, useEffect, useMemo, useRef, useState } from 'react'
 import type { SessionSummary } from '@/types/api'
 import type { ApiClient } from '@/api/client'
 import { useLongPress } from '@/hooks/useLongPress'
@@ -7,6 +7,12 @@ import { useSessionActions } from '@/hooks/mutations/useSessionActions'
 import { SessionActionMenu } from '@/components/SessionActionMenu'
 import { RenameSessionDialog } from '@/components/RenameSessionDialog'
 import { ConfirmDialog } from '@/components/ui/ConfirmDialog'
+import {
+    getFlavorTextClass,
+    META_DOT_SEPARATOR_CLASS,
+    SESSION_ACTIVITY_BADGE,
+    SESSION_PENDING_BADGE
+} from '@/lib/agentFlavorUtils'
 import { getSessionModelLabel } from '@/lib/sessionModelLabel'
 import { useTranslation } from '@/lib/use-translation'
 
@@ -30,7 +36,7 @@ function getGroupDisplayName(directory: string): string {
 
 export const UNKNOWN_MACHINE_ID = '__unknown__'
 
-function groupSessionsByDirectory(sessions: SessionSummary[]): SessionGroup[] {
+export function groupSessionsByDirectory(sessions: SessionSummary[]): SessionGroup[] {
     const groups = new Map<string, { directory: string; machineId: string | null; sessions: SessionSummary[] }>()
 
     sessions.forEach(session => {
@@ -100,42 +106,42 @@ function PlusIcon(props: { className?: string }) {
     )
 }
 
-function BulbIcon(props: { className?: string }) {
+function ChevronIcon(props: { className?: string; collapsed?: boolean }) {
     return (
         <svg
             xmlns="http://www.w3.org/2000/svg"
-            width="24"
-            height="24"
+            width="16"
+            height="16"
             viewBox="0 0 24 24"
             fill="none"
             stroke="currentColor"
             strokeWidth="2"
             strokeLinecap="round"
             strokeLinejoin="round"
-            className={props.className}
+            className={`${props.className ?? ''} transition-transform duration-200 ${props.collapsed ? '' : 'rotate-90'}`}
         >
-            <path d="M9 18h6" />
-            <path d="M10 22h4" />
-            <path d="M12 2a7 7 0 0 0-4 12c.6.6 1 1.2 1 2h6c0-.8.4-1.4 1-2a7 7 0 0 0-4-12Z" />
+            <polyline points="9 18 15 12 9 6" />
         </svg>
     )
 }
 
-function ChevronIcon(props: { className?: string; collapsed?: boolean }) {
+function MachineIcon(props: { className?: string }) {
     return (
         <svg
             xmlns="http://www.w3.org/2000/svg"
-            width="16"
-            height="16"
+            width="14"
+            height="14"
             viewBox="0 0 24 24"
             fill="none"
             stroke="currentColor"
             strokeWidth="2"
             strokeLinecap="round"
             strokeLinejoin="round"
-            className={`${props.className ?? ''} transition-transform duration-200 ${props.collapsed ? '' : 'rotate-90'}`}
+            className={props.className}
         >
-            <polyline points="9 18 15 12 9 6" />
+            <rect x="2" y="3" width="20" height="14" rx="2" />
+            <line x1="8" y1="21" x2="16" y2="21" />
+            <line x1="12" y1="17" x2="12" y2="21" />
         </svg>
     )
 }
@@ -162,31 +168,10 @@ function getTodoProgress(session: SessionSummary): { completed: number; total: n
 
 function getAgentLabel(session: SessionSummary): string {
     const flavor = session.metadata?.flavor?.trim()
-    if (flavor) return flavor
+    if (flavor) return flavor.toLowerCase()
     return 'unknown'
 }
 
-function MachineIcon(props: { className?: string }) {
-    return (
-        <svg
-            xmlns="http://www.w3.org/2000/svg"
-            width="14"
-            height="14"
-            viewBox="0 0 24 24"
-            fill="none"
-            stroke="currentColor"
-            strokeWidth="2"
-            strokeLinecap="round"
-            strokeLinejoin="round"
-            className={props.className}
-        >
-            <rect x="2" y="3" width="20" height="14" rx="2" />
-            <line x1="8" y1="21" x2="16" y2="21" />
-            <line x1="12" y1="17" x2="12" y2="21" />
-        </svg>
-    )
-}
-
 function formatRelativeTime(value: number, t: (key: string, params?: Record<string, string | number>) => string): string | null {
     const ms = value < 1_000_000_000_000 ? value * 1000 : value
     if (!Number.isFinite(ms)) return null
@@ -204,12 +189,18 @@ function formatRelativeTime(value: number, t: (key: string, params?: Record<stri
 function SessionItem(props: {
     session: SessionSummary
     onSelect: (sessionId: string) => void
-    showPath?: boolean
     api: ApiClient | null
     selected?: boolean
+    animateEnter?: boolean
 }) {
     const { t } = useTranslation()
-    const { session: s, onSelect, showPath = true, api, selected = false } = props
+    const {
+        session: s,
+        onSelect,
+        api,
+        selected = false,
+        animateEnter = false
+    } = props
     const { haptic } = usePlatform()
     const [menuOpen, setMenuOpen] = useState(false)
     const [menuAnchorPoint, setMenuAnchorPoint] = useState<{ x: number; y: number }>({ x: 0, y: 0 })
@@ -239,71 +230,69 @@ function SessionItem(props: {
 
     const sessionName = getSessionTitle(s)
     const modelLabel = getSessionModelLabel(s)
+    const agentLabel = getAgentLabel(s)
     const statusDotClass = s.active
-        ? (s.thinking ? 'bg-[#007AFF]' : 'bg-[var(--app-badge-success-text)]')
+        ? (s.thinking ? 'bg-[var(--app-badge-info-text)]' : 'bg-[var(--app-badge-success-text)]')
         : 'bg-[var(--app-hint)]'
     const todoProgress = getTodoProgress(s)
+    const inactiveClass = s.active ? '' : 'opacity-[0.55]'
+    const metadataItems = [
+        <span key="flavor" className={getFlavorTextClass(s.metadata?.flavor)}>
+            {agentLabel}
+        </span>,
+        modelLabel ? <span key="model">{modelLabel.value}</span> : null,
+        s.metadata?.worktree?.branch ? <span key="worktree">{s.metadata.worktree.branch}</span> : null,
+        todoProgress ? <span key="todo">{todoProgress.completed}/{todoProgress.total}</span> : null
+    ].filter(Boolean) as ReactNode[]
+
     return (
         <>
             <button
                 type="button"
                 {...longPressHandlers}
-                className={`session-list-item flex w-full flex-col gap-1.5 px-3 py-3 text-left transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--app-link)] select-none ${selected ? 'bg-[var(--app-secondary-bg)]' : ''}`}
+                className={`session-list-item flex w-full flex-col gap-2 px-3 py-3 text-left transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--app-link)] select-none ${selected ? 'bg-[var(--app-secondary-bg)]' : ''} ${animateEnter ? 'animate-session-enter' : ''}`}
                 style={{ WebkitTouchCallout: 'none' }}
                 aria-current={selected ? 'page' : undefined}
             >
-                <div className="flex items-center justify-between gap-3">
-                    <div className="flex items-center gap-2 min-w-0">
+                <div className="flex items-start justify-between gap-3">
+                    <div className="flex min-w-0 items-start gap-2">
                         <span className="flex h-4 w-4 items-center justify-center" aria-hidden="true">
-                            <span
-                                className={`h-2 w-2 rounded-full ${statusDotClass}`}
-                            />
+                            <span className={`h-2 w-2 rounded-full ${statusDotClass}`} />
                         </span>
-                        <div className="truncate text-base font-medium">
-                            {sessionName}
+                        <div className={`min-w-0 ${inactiveClass}`}>
+                            <div className="truncate text-base font-medium">
+                                {sessionName}
+                            </div>
                         </div>
                     </div>
-                    <div className="flex items-center gap-2 shrink-0 text-xs">
+                    <div className="shrink-0 pt-0.5 text-xs text-[var(--app-hint)]">
+                        {formatRelativeTime(s.updatedAt, t)}
+                    </div>
+                </div>
+                {(metadataItems.length > 0 || s.thinking || s.pendingRequestsCount > 0) ? (
+                    <div className="flex flex-wrap items-center gap-x-2 gap-y-1 pl-6 text-xs text-[var(--app-hint)]">
+                        <div className={`inline-flex min-w-0 flex-wrap items-center gap-x-2 gap-y-1 ${inactiveClass}`}>
+                            {metadataItems.map((item, index) => (
+                                <Fragment key={index}>
+                                    {index > 0 ? (
+                                        <span aria-hidden="true" className={META_DOT_SEPARATOR_CLASS}>·</span>
+                                    ) : null}
+                                    {item}
+                                </Fragment>
+                            ))}
+                        </div>
                         {s.thinking ? (
-                            <span className="text-[#007AFF] animate-pulse">
+                            <span className={SESSION_ACTIVITY_BADGE}>
                                 {t('session.item.thinking')}
                             </span>
                         ) : null}
-                        {todoProgress ? (
-                            <span className="flex items-center gap-1 text-[var(--app-hint)]">
-                                <BulbIcon className="h-3 w-3" />
-                                {todoProgress.completed}/{todoProgress.total}
-                            </span>
-                        ) : null}
                         {s.pendingRequestsCount > 0 ? (
-                            <span className="text-[var(--app-badge-warning-text)]">
+                            <span className={SESSION_PENDING_BADGE}>
                                 {t('session.item.pending')} {s.pendingRequestsCount}
                             </span>
                         ) : null}
-                        <span className="text-[var(--app-hint)]">
-                            {formatRelativeTime(s.updatedAt, t)}
-                        </span>
-                    </div>
-                </div>
-                {showPath ? (
-                    <div className="truncate text-xs text-[var(--app-hint)]">
-                        {s.metadata?.path ?? s.id}
                     </div>
                 ) : null}
-                <div className="flex flex-wrap items-center gap-x-3 gap-y-1 text-xs text-[var(--app-hint)]">
-                    <span className="inline-flex items-center gap-2">
-                        <span className="flex h-4 w-4 items-center justify-center" aria-hidden="true">
-                            ❖
-                        </span>
-                        {getAgentLabel(s)}
-                    </span>
-                    {modelLabel ? (
-                        <span>{t(modelLabel.key)}: {modelLabel.value}</span>
-                    ) : null}
-                    {s.metadata?.worktree?.branch ? (
-                        <span>{t('session.item.worktree')}: {s.metadata.worktree.branch}</span>
-                    ) : null}
-                </div>
             </button>
 
             <SessionActionMenu
@@ -351,6 +340,54 @@ function SessionItem(props: {
     )
 }
 
+function GroupHeader(props: {
+    group: SessionGroup
+    isCollapsed: boolean
+    machineLabel: string
+    onToggle: () => void
+}) {
+    const { haptic } = usePlatform()
+    const longPressHandlers = useLongPress({
+        onLongPress: () => {
+            haptic.impact('medium')
+        },
+        onClick: props.onToggle,
+        threshold: 500
+    })
+
+    return (
+        <button
+            type="button"
+            {...longPressHandlers}
+            aria-expanded={!props.isCollapsed}
+            className="sticky top-0 z-10 flex w-full flex-col gap-1 border-b border-[var(--app-divider)] bg-[var(--app-bg)] px-3 py-2.5 text-left transition-colors hover:bg-[var(--app-subtle-bg)]"
+            style={{ WebkitTouchCallout: 'none' }}
+        >
+            <div className="flex min-w-0 w-full items-center gap-2">
+                <ChevronIcon
+                    className="h-4 w-4 shrink-0 text-[var(--app-hint)]"
+                    collapsed={props.isCollapsed}
+                />
+                <span className="min-w-0 break-words text-sm font-semibold" title={props.group.directory}>
+                    {props.group.displayName}
+                </span>
+                <span className="shrink-0 text-xs text-[var(--app-hint)]">
+                    ({props.group.sessions.length})
+                </span>
+            </div>
+            <div className="flex min-w-0 w-full flex-wrap items-center gap-2 pl-6 text-xs text-[var(--app-hint)]">
+                <span className="inline-flex items-center gap-1 rounded-full border border-[var(--app-divider)] bg-[var(--app-bg)] px-2 py-0.5">
+                    <MachineIcon className="h-3 w-3 shrink-0" />
+                    {props.machineLabel}
+                </span>
+                <span className="min-w-0 flex-1 truncate" title={props.group.directory}>
+                    {props.group.directory}
+                </span>
+            </div>
+        </button>
+    )
+}
+
 export function SessionList(props: {
     sessions: SessionSummary[]
     onSelect: (sessionId: string) => void
@@ -363,14 +400,31 @@ export function SessionList(props: {
     selectedSessionId?: string | null
 }) {
     const { t } = useTranslation()
-    const { renderHeader = true, api, selectedSessionId, machineLabelsById = {} } = props
+    const {
+        renderHeader = true,
+        api,
+        selectedSessionId,
+        machineLabelsById = {}
+    } = props
     const groups = useMemo(
         () => groupSessionsByDirectory(props.sessions),
         [props.sessions]
     )
+    const displayGroups = groups
+    const knownSessionIdsRef = useRef<Set<string>>(new Set(props.sessions.map(session => session.id)))
     const [collapseOverrides, setCollapseOverrides] = useState<Map<string, boolean>>(
         () => new Map()
     )
+    const enteringSessionIds = useMemo(() => {
+        const entering = new Set<string>()
+        props.sessions.forEach(session => {
+            if (!knownSessionIdsRef.current.has(session.id)) {
+                entering.add(session.id)
+            }
+        })
+        return entering
+    }, [props.sessions])
+
     const isGroupCollapsed = (group: SessionGroup): boolean => {
         const override = collapseOverrides.get(group.key)
         if (override !== undefined) return override
@@ -401,7 +455,7 @@ export function SessionList(props: {
     useEffect(() => {
         if (!selectedSessionId) return
         setCollapseOverrides(prev => {
-            const group = groups.find(g =>
+            const group = displayGroups.find(g =>
                 g.sessions.some(s => s.id === selectedSessionId)
             )
             if (!group || !prev.has(group.key) || !prev.get(group.key)) return prev
@@ -409,13 +463,13 @@ export function SessionList(props: {
             next.delete(group.key)
             return next
         })
-    }, [selectedSessionId, groups])
+    }, [selectedSessionId, displayGroups])
 
     useEffect(() => {
         setCollapseOverrides(prev => {
             if (prev.size === 0) return prev
             const next = new Map(prev)
-            const knownGroups = new Set(groups.map(group => group.key))
+            const knownGroups = new Set(displayGroups.map(group => group.key))
             let changed = false
             for (const groupKey of next.keys()) {
                 if (!knownGroups.has(groupKey)) {
@@ -425,19 +479,25 @@ export function SessionList(props: {
             }
             return changed ? next : prev
         })
-    }, [groups])
+    }, [displayGroups])
+
+    useEffect(() => {
+        props.sessions.forEach(session => {
+            knownSessionIdsRef.current.add(session.id)
+        })
+    }, [props.sessions])
 
     return (
         <div className="mx-auto w-full max-w-content flex flex-col">
             {renderHeader ? (
                 <div className="flex items-center justify-between px-3 py-1">
                     <div className="text-xs text-[var(--app-hint)]">
-                        {t('sessions.count', { n: props.sessions.length, m: groups.length })}
+                        {t('sessions.count', { n: props.sessions.length, m: displayGroups.length })}
                     </div>
                     <button
                         type="button"
                         onClick={props.onNewSession}
-                        className="session-list-new-button p-1.5 rounded-full text-[var(--app-link)] transition-colors"
+                        className="session-list-new-button rounded-full p-1.5 text-[var(--app-link)] transition-colors"
                         title={t('sessions.new')}
                     >
                         <PlusIcon className="h-5 w-5" />
@@ -446,48 +506,27 @@ export function SessionList(props: {
             ) : null}
 
             <div className="flex flex-col">
-                {groups.map((group) => {
+                {displayGroups.map((group) => {
                     const isCollapsed = isGroupCollapsed(group)
                     const machineLabel = resolveMachineLabel(group.machineId)
                     return (
                         <div key={group.key} className="mt-2 first:mt-0">
-                            <button
-                                type="button"
-                                onClick={() => toggleGroup(group.key, isCollapsed)}
-                                className="sticky top-0 z-10 flex w-full flex-col gap-1 px-3 py-2.5 text-left bg-[var(--app-secondary-bg)] border-b border-[var(--app-border)] border-l-[3px] border-l-[var(--app-hint)] transition-colors hover:bg-[var(--app-subtle-bg)]"
-                            >
-                                <div className="flex items-center gap-2 min-w-0 w-full">
-                                    <ChevronIcon
-                                        className="h-4 w-4 text-[var(--app-hint)] shrink-0"
-                                        collapsed={isCollapsed}
-                                    />
-                                    <span className="font-semibold text-sm break-words min-w-0" title={group.directory}>
-                                        {group.displayName}
-                                    </span>
-                                    <span className="shrink-0 rounded-full bg-[var(--app-subtle-bg)] px-1.5 py-0.5 text-[10px] font-medium text-[var(--app-hint)]">
-                                        {group.sessions.length}
-                                    </span>
-                                </div>
-                                <div className="flex min-w-0 w-full flex-wrap items-center gap-2 pl-6 text-xs text-[var(--app-hint)]">
-                                    <span className="inline-flex items-center gap-1 rounded border border-[var(--app-border)] bg-[var(--app-bg)] px-2 py-0.5">
-                                        <MachineIcon className="h-3 w-3 shrink-0" />
-                                        {machineLabel}
-                                    </span>
-                                    <span className="min-w-0 flex-1 truncate" title={group.directory}>
-                                        {group.directory}
-                                    </span>
-                                </div>
-                            </button>
+                            <GroupHeader
+                                group={group}
+                                isCollapsed={isCollapsed}
+                                machineLabel={machineLabel}
+                                onToggle={() => toggleGroup(group.key, isCollapsed)}
+                            />
                             {!isCollapsed ? (
                                 <div className="flex flex-col divide-y divide-[var(--app-divider)] border-b border-[var(--app-divider)] border-l border-l-[var(--app-divider)]">
-                                    {group.sessions.map((s) => (
+                                    {group.sessions.map((s, index) => (
                                         <SessionItem
                                             key={s.id}
                                             session={s}
                                             onSelect={props.onSelect}
-                                            showPath={false}
                                             api={api}
                                             selected={s.id === selectedSessionId}
+                                            animateEnter={enteringSessionIds.has(s.id)}
                                         />
                                     ))}
                                 </div>
@@ -496,6 +535,7 @@ export function SessionList(props: {
                     )
                 })}
             </div>
+
         </div>
     )
 }
diff --git a/web/src/hooks/useLongPress.ts b/web/src/hooks/useLongPress.ts
index 5673b2d7d..ffeb81399 100644
--- a/web/src/hooks/useLongPress.ts
+++ b/web/src/hooks/useLongPress.ts
@@ -9,12 +9,10 @@ type UseLongPressOptions = {
 }
 
 type UseLongPressHandlers = {
-    onMouseDown: React.MouseEventHandler
-    onMouseUp: React.MouseEventHandler
-    onMouseLeave: React.MouseEventHandler
-    onTouchStart: React.TouchEventHandler
-    onTouchEnd: React.TouchEventHandler
-    onTouchMove: React.TouchEventHandler
+    onPointerDown: React.PointerEventHandler
+    onPointerUp: React.PointerEventHandler
+    onPointerLeave: React.PointerEventHandler
+    onPointerCancel: React.PointerEventHandler
     onContextMenu: React.MouseEventHandler
     onKeyDown: React.KeyboardEventHandler
 }
@@ -24,7 +22,6 @@ export function useLongPress(options: UseLongPressOptions): UseLongPressHandlers
 
     const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null)
     const isLongPressRef = useRef(false)
-    const touchMoved = useRef(false)
     const pressPointRef = useRef<{ x: number; y: number }>({ x: 0, y: 0 })
 
     const clearTimer = useCallback(() => {
@@ -39,7 +36,6 @@ export function useLongPress(options: UseLongPressOptions): UseLongPressHandlers
 
         clearTimer()
         isLongPressRef.current = false
-        touchMoved.current = false
         pressPointRef.current = { x: clientX, y: clientY }
 
         timerRef.current = setTimeout(() => {
@@ -51,44 +47,34 @@ export function useLongPress(options: UseLongPressOptions): UseLongPressHandlers
     const handleEnd = useCallback((shouldTriggerClick: boolean) => {
         clearTimer()
 
-        if (shouldTriggerClick && !isLongPressRef.current && !touchMoved.current && onClick) {
+        if (shouldTriggerClick && !isLongPressRef.current && onClick) {
             onClick()
         }
 
         isLongPressRef.current = false
-        touchMoved.current = false
     }, [clearTimer, onClick])
 
-    const onMouseDown = useCallback<React.MouseEventHandler>((e) => {
-        if (e.button !== 0) return
+    const onPointerDown = useCallback<React.PointerEventHandler>((e) => {
+        if (!e.isPrimary) return
+        if (e.pointerType === 'mouse' && e.button !== 0) return
         startTimer(e.clientX, e.clientY)
     }, [startTimer])
 
-    const onMouseUp = useCallback<React.MouseEventHandler>(() => {
+    const onPointerUp = useCallback<React.PointerEventHandler>((e) => {
+        if (!e.isPrimary) return
         handleEnd(!isLongPressRef.current)
     }, [handleEnd])
 
-    const onMouseLeave = useCallback<React.MouseEventHandler>(() => {
+    const onPointerLeave = useCallback<React.PointerEventHandler>((e) => {
+        if (!e.isPrimary) return
         handleEnd(false)
     }, [handleEnd])
 
-    const onTouchStart = useCallback<React.TouchEventHandler>((e) => {
-        const touch = e.touches[0]
-        startTimer(touch.clientX, touch.clientY)
-    }, [startTimer])
-
-    const onTouchEnd = useCallback<React.TouchEventHandler>((e) => {
-        if (isLongPressRef.current) {
-            e.preventDefault()
-        }
-        handleEnd(!isLongPressRef.current)
+    const onPointerCancel = useCallback<React.PointerEventHandler>((e) => {
+        if (!e.isPrimary) return
+        handleEnd(false)
     }, [handleEnd])
 
-    const onTouchMove = useCallback<React.TouchEventHandler>(() => {
-        touchMoved.current = true
-        clearTimer()
-    }, [clearTimer])
-
     const onContextMenu = useCallback<React.MouseEventHandler>((e) => {
         if (!disabled) {
             e.preventDefault()
@@ -107,12 +93,10 @@ export function useLongPress(options: UseLongPressOptions): UseLongPressHandlers
     }, [disabled, onClick])
 
     return {
-        onMouseDown,
-        onMouseUp,
-        onMouseLeave,
-        onTouchStart,
-        onTouchEnd,
-        onTouchMove,
+        onPointerDown,
+        onPointerUp,
+        onPointerLeave,
+        onPointerCancel,
         onContextMenu,
         onKeyDown
     }
diff --git a/web/src/index.css b/web/src/index.css
index 41bc44877..744c279d4 100644
--- a/web/src/index.css
+++ b/web/src/index.css
@@ -33,6 +33,9 @@
     --app-git-untracked-color: #8E8E93;
 
     /* Badge colors (light) */
+    --app-badge-info-bg: rgba(59, 130, 246, 0.12);
+    --app-badge-info-text: #1d4ed8;
+    --app-badge-info-border: rgba(59, 130, 246, 0.22);
     --app-badge-warning-bg: rgba(245, 158, 11, 0.2);
     --app-badge-warning-text: #b45309;
     --app-badge-warning-border: rgba(245, 158, 11, 0.3);
@@ -43,6 +46,26 @@
     --app-badge-error-text: #b91c1c;
     --app-badge-error-border: rgba(239, 68, 68, 0.3);
 
+    --app-flavor-claude: #b45309;
+    --app-flavor-claude-bg: rgba(245, 158, 11, 0.12);
+    --app-flavor-claude-text: #b45309;
+    --app-flavor-claude-border: rgba(245, 158, 11, 0.24);
+    --app-flavor-codex: #1d4ed8;
+    --app-flavor-codex-bg: rgba(59, 130, 246, 0.12);
+    --app-flavor-codex-text: #1d4ed8;
+    --app-flavor-codex-border: rgba(59, 130, 246, 0.24);
+    --app-flavor-gemini: #6d28d9;
+    --app-flavor-gemini-bg: rgba(139, 92, 246, 0.12);
+    --app-flavor-gemini-text: #6d28d9;
+    --app-flavor-gemini-border: rgba(139, 92, 246, 0.24);
+    --app-flavor-opencode: #047857;
+    --app-flavor-opencode-bg: rgba(16, 185, 129, 0.12);
+    --app-flavor-opencode-text: #047857;
+    --app-flavor-opencode-border: rgba(16, 185, 129, 0.24);
+    --app-flavor-cursor-bg: rgba(100, 116, 139, 0.12);
+    --app-flavor-cursor-text: #475569;
+    --app-flavor-cursor-border: rgba(100, 116, 139, 0.24);
+
     --app-font-scale: 1;
 }
 
@@ -78,6 +101,9 @@
     --app-git-untracked-color: #9ca3af;
 
     /* Badge colors (dark) */
+    --app-badge-info-bg: rgba(96, 165, 250, 0.18);
+    --app-badge-info-text: #93c5fd;
+    --app-badge-info-border: rgba(96, 165, 250, 0.28);
     --app-badge-warning-bg: rgba(251, 191, 36, 0.2);
     --app-badge-warning-text: #fbbf24;
     --app-badge-warning-border: rgba(251, 191, 36, 0.3);
@@ -87,6 +113,226 @@
     --app-badge-error-bg: rgba(248, 113, 113, 0.2);
     --app-badge-error-text: #fca5a5;
     --app-badge-error-border: rgba(248, 113, 113, 0.35);
+
+    --app-flavor-claude: #fcd34d;
+    --app-flavor-claude-bg: rgba(251, 191, 36, 0.16);
+    --app-flavor-claude-text: #fcd34d;
+    --app-flavor-claude-border: rgba(251, 191, 36, 0.28);
+    --app-flavor-codex: #93c5fd;
+    --app-flavor-codex-bg: rgba(96, 165, 250, 0.16);
+    --app-flavor-codex-text: #93c5fd;
+    --app-flavor-codex-border: rgba(96, 165, 250, 0.28);
+    --app-flavor-gemini: #c4b5fd;
+    --app-flavor-gemini-bg: rgba(167, 139, 250, 0.16);
+    --app-flavor-gemini-text: #c4b5fd;
+    --app-flavor-gemini-border: rgba(167, 139, 250, 0.28);
+    --app-flavor-opencode: #6ee7b7;
+    --app-flavor-opencode-bg: rgba(52, 211, 153, 0.16);
+    --app-flavor-opencode-text: #6ee7b7;
+    --app-flavor-opencode-border: rgba(52, 211, 153, 0.28);
+    --app-flavor-cursor-bg: rgba(148, 163, 184, 0.16);
+    --app-flavor-cursor-text: #cbd5e1;
+    --app-flavor-cursor-border: rgba(148, 163, 184, 0.28);
+}
+
+[data-theme="catpuccin"] {
+    /* Primary colors — Catpuccin Mocha */
+    --app-bg: #1e1e2e;
+    --app-fg: #cdd6f4;
+    --app-hint: #6c7086;
+    --app-link: #cdd6f4;
+    --app-button: #cdd6f4;
+    --app-button-text: #1e1e2e;
+    --app-banner-bg: #313244;
+    --app-banner-text: #cdd6f4;
+    --app-secondary-bg: #313244;
+
+    --app-border: rgba(255, 255, 255, 0.1);
+    --app-divider: rgba(255, 255, 255, 0.08);
+    --app-subtle-bg: rgba(255, 255, 255, 0.05);
+    --app-code-bg: #282c34;
+    --app-inline-code-bg: rgba(255, 255, 255, 0.1);
+
+    /* Diff colors (dark) */
+    --app-diff-added-bg: #0d2e1f;
+    --app-diff-added-text: #c9d1d9;
+    --app-diff-removed-bg: #3f1b23;
+    --app-diff-removed-text: #c9d1d9;
+
+    /* Git status colors */
+    --app-git-staged-color: #a6e3a1;
+    --app-git-unstaged-color: #fab387;
+    --app-git-deleted-color: #f38ba8;
+    --app-git-renamed-color: #89b4fa;
+    --app-git-untracked-color: #6c7086;
+
+    /* Badge colors — Catpuccin Mocha */
+    --app-badge-info-bg: rgba(137, 180, 250, 0.12);
+    --app-badge-info-text: #89b4fa;
+    --app-badge-info-border: rgba(137, 180, 250, 0.22);
+    --app-badge-warning-bg: rgba(250, 179, 135, 0.15);
+    --app-badge-warning-text: #fab387;
+    --app-badge-warning-border: rgba(250, 179, 135, 0.25);
+    --app-badge-success-bg: rgba(166, 227, 161, 0.15);
+    --app-badge-success-text: #a6e3a1;
+    --app-badge-success-border: rgba(166, 227, 161, 0.25);
+    --app-badge-error-bg: rgba(243, 139, 168, 0.15);
+    --app-badge-error-text: #f38ba8;
+    --app-badge-error-border: rgba(243, 139, 168, 0.25);
+
+    --app-flavor-claude: #fab387;
+    --app-flavor-claude-bg: rgba(250, 179, 135, 0.10);
+    --app-flavor-claude-text: #fab387;
+    --app-flavor-claude-border: rgba(250, 179, 135, 0.20);
+    --app-flavor-codex: #a6e3a1;
+    --app-flavor-codex-bg: rgba(166, 227, 161, 0.10);
+    --app-flavor-codex-text: #a6e3a1;
+    --app-flavor-codex-border: rgba(166, 227, 161, 0.20);
+    --app-flavor-gemini: #74c7ec;
+    --app-flavor-gemini-bg: rgba(116, 199, 236, 0.10);
+    --app-flavor-gemini-text: #74c7ec;
+    --app-flavor-gemini-border: rgba(116, 199, 236, 0.20);
+    --app-flavor-opencode: #cba6f7;
+    --app-flavor-opencode-bg: rgba(203, 166, 247, 0.10);
+    --app-flavor-opencode-text: #cba6f7;
+    --app-flavor-opencode-border: rgba(203, 166, 247, 0.20);
+    --app-flavor-cursor-bg: rgba(186, 194, 222, 0.10);
+    --app-flavor-cursor-text: #bac2de;
+    --app-flavor-cursor-border: rgba(186, 194, 222, 0.20);
+}
+
+[data-theme="gaius-light"] {
+    /* Primary — warm pearl base */
+    --app-bg: #f8f5f2;
+    --app-fg: #2a2832;
+    --app-hint: #85808a;
+    --app-link: #b04440;
+    --app-button: #2a2832;
+    --app-button-text: #f8f5f2;
+    --app-banner-bg: #eceae6;
+    --app-banner-text: #2a2832;
+    --app-secondary-bg: #f0ede9;
+
+    /* Overlays */
+    --app-border: rgba(42, 40, 50, 0.10);
+    --app-divider: rgba(42, 40, 50, 0.07);
+    --app-subtle-bg: rgba(42, 40, 50, 0.03);
+    --app-code-bg: #f0ede8;
+    --app-inline-code-bg: rgba(42, 40, 50, 0.05);
+
+    /* Diffs — verdigris added, cinnabar removed */
+    --app-diff-added-bg: #e4edd8;
+    --app-diff-added-text: #2a2832;
+    --app-diff-removed-bg: #f2dcd8;
+    --app-diff-removed-text: #2a2832;
+
+    /* Git status */
+    --app-git-staged-color: #3a7868;
+    --app-git-unstaged-color: #b07830;
+    --app-git-deleted-color: #b84440;
+    --app-git-renamed-color: #4068a0;
+    --app-git-untracked-color: #85808a;
+
+    /* Badges — lapis, gold, verdigris, cinnabar */
+    --app-badge-info-bg: rgba(64, 104, 160, 0.10);
+    --app-badge-info-text: #3a5888;
+    --app-badge-info-border: rgba(64, 104, 160, 0.20);
+    --app-badge-warning-bg: rgba(176, 120, 48, 0.12);
+    --app-badge-warning-text: #8a5820;
+    --app-badge-warning-border: rgba(176, 120, 48, 0.22);
+    --app-badge-success-bg: rgba(58, 120, 104, 0.10);
+    --app-badge-success-text: #2a6858;
+    --app-badge-success-border: rgba(58, 120, 104, 0.20);
+    --app-badge-error-bg: rgba(184, 68, 64, 0.10);
+    --app-badge-error-text: #983838;
+    --app-badge-error-border: rgba(184, 68, 64, 0.20);
+
+    --app-flavor-claude: #a04038;
+    --app-flavor-claude-bg: rgba(160, 64, 56, 0.08);
+    --app-flavor-claude-text: #a04038;
+    --app-flavor-claude-border: rgba(160, 64, 56, 0.18);
+    --app-flavor-codex: #2a6858;
+    --app-flavor-codex-bg: rgba(42, 104, 88, 0.08);
+    --app-flavor-codex-text: #2a6858;
+    --app-flavor-codex-border: rgba(42, 104, 88, 0.18);
+    --app-flavor-gemini: #3a5888;
+    --app-flavor-gemini-bg: rgba(58, 88, 136, 0.08);
+    --app-flavor-gemini-text: #3a5888;
+    --app-flavor-gemini-border: rgba(58, 88, 136, 0.18);
+    --app-flavor-opencode: #6a5090;
+    --app-flavor-opencode-bg: rgba(106, 80, 144, 0.08);
+    --app-flavor-opencode-text: #6a5090;
+    --app-flavor-opencode-border: rgba(106, 80, 144, 0.18);
+    --app-flavor-cursor-bg: rgba(106, 104, 116, 0.08);
+    --app-flavor-cursor-text: #6a6874;
+    --app-flavor-cursor-border: rgba(106, 104, 116, 0.18);
+}
+
+[data-theme="gaius-dark"] {
+    /* Primary — deep slate base */
+    --app-bg: #1e1d22;
+    --app-fg: #e6e3de;
+    --app-hint: #88848e;
+    --app-link: #d06058;
+    --app-button: #e6e3de;
+    --app-button-text: #1e1d22;
+    --app-banner-bg: #2a2930;
+    --app-banner-text: #e6e3de;
+    --app-secondary-bg: #252428;
+
+    /* Overlays */
+    --app-border: rgba(230, 227, 222, 0.08);
+    --app-divider: rgba(230, 227, 222, 0.06);
+    --app-subtle-bg: rgba(230, 227, 222, 0.04);
+    --app-code-bg: #252430;
+    --app-inline-code-bg: rgba(230, 227, 222, 0.07);
+
+    /* Diffs */
+    --app-diff-added-bg: rgba(80, 150, 130, 0.12);
+    --app-diff-added-text: #d8d5d0;
+    --app-diff-removed-bg: rgba(200, 80, 70, 0.12);
+    --app-diff-removed-text: #d8d5d0;
+
+    /* Git status */
+    --app-git-staged-color: #68b8a0;
+    --app-git-unstaged-color: #d0a060;
+    --app-git-deleted-color: #d87068;
+    --app-git-renamed-color: #6890c8;
+    --app-git-untracked-color: #88848e;
+
+    /* Badges */
+    --app-badge-info-bg: rgba(104, 144, 200, 0.12);
+    --app-badge-info-text: #6890c8;
+    --app-badge-info-border: rgba(104, 144, 200, 0.20);
+    --app-badge-warning-bg: rgba(208, 160, 96, 0.15);
+    --app-badge-warning-text: #d0a060;
+    --app-badge-warning-border: rgba(208, 160, 96, 0.25);
+    --app-badge-success-bg: rgba(104, 184, 160, 0.10);
+    --app-badge-success-text: #68b8a0;
+    --app-badge-success-border: rgba(104, 184, 160, 0.20);
+    --app-badge-error-bg: rgba(216, 112, 104, 0.12);
+    --app-badge-error-text: #d87068;
+    --app-badge-error-border: rgba(216, 112, 104, 0.22);
+
+    --app-flavor-claude: #d08858;
+    --app-flavor-claude-bg: rgba(208, 136, 88, 0.10);
+    --app-flavor-claude-text: #d08858;
+    --app-flavor-claude-border: rgba(208, 136, 88, 0.20);
+    --app-flavor-codex: #68b8a0;
+    --app-flavor-codex-bg: rgba(104, 184, 160, 0.10);
+    --app-flavor-codex-text: #68b8a0;
+    --app-flavor-codex-border: rgba(104, 184, 160, 0.20);
+    --app-flavor-gemini: #6890c8;
+    --app-flavor-gemini-bg: rgba(104, 144, 200, 0.10);
+    --app-flavor-gemini-text: #6890c8;
+    --app-flavor-gemini-border: rgba(104, 144, 200, 0.20);
+    --app-flavor-opencode: #a088c0;
+    --app-flavor-opencode-bg: rgba(160, 136, 192, 0.10);
+    --app-flavor-opencode-text: #a088c0;
+    --app-flavor-opencode-border: rgba(160, 136, 192, 0.20);
+    --app-flavor-cursor-bg: rgba(176, 172, 182, 0.10);
+    --app-flavor-cursor-text: #b0acb6;
+    --app-flavor-cursor-border: rgba(176, 172, 182, 0.20);
 }
 
 html {
@@ -98,22 +344,12 @@ body {
     height: 100vh;
     height: 100dvh;
     height: var(--tg-viewport-stable-height, 100dvh);
+    overflow: hidden;
     touch-action: pan-x pan-y;
     overscroll-behavior: none;
     -webkit-text-size-adjust: 100%;
 }
 
-html[data-telegram-app="true"],
-html[data-telegram-app="true"] body {
-    overflow: hidden;
-}
-
-html:not([data-telegram-app="true"]),
-html:not([data-telegram-app="true"]) body {
-    overflow-x: hidden;
-    overflow-y: auto;
-}
-
 body {
     font-size: 1rem;
     background: var(--app-bg);
@@ -149,16 +385,6 @@ body {
     }
 }
 
-/*
- * content-visibility: auto lets the browser skip layout/paint for messages
- * scrolled out of the viewport. Big win on Windows with long conversations (#310).
- * contain-intrinsic-size gives a rough height hint so scrollbar doesn't jump.
- */
-.happy-thread-messages > * {
-    content-visibility: auto;
-    contain-intrinsic-size: auto 80px;
-}
-
 /* Markdown styles */
 .markdown-content a { color: var(--app-link); text-decoration: underline; }
 .markdown-content code { background: var(--app-inline-code-bg); padding: 0.1em 0.3em; border-radius: 4px; font-size: 0.9em; }
@@ -194,7 +420,11 @@ body {
 }
 
 html[data-theme="dark"] .shiki,
-html[data-theme="dark"] .shiki span {
+html[data-theme="dark"] .shiki span,
+html[data-theme="catpuccin"] .shiki,
+html[data-theme="catpuccin"] .shiki span,
+html[data-theme="gaius-dark"] .shiki,
+html[data-theme="gaius-dark"] .shiki span {
     color: var(--shiki-dark) !important;
     font-style: var(--shiki-dark-font-style) !important;
     font-weight: var(--shiki-dark-font-weight) !important;
@@ -292,6 +522,33 @@ html[data-theme="dark"] .shiki span {
   animation: bounce-in 0.3s ease-out;
 }
 
+/* Session list item enter animation */
+@keyframes session-enter {
+  from {
+    opacity: 0;
+    transform: translateY(6px);
+  }
+  to {
+    opacity: 1;
+    transform: translateY(0);
+  }
+}
+
+.animate-session-enter {
+  animation: session-enter 0.2s ease-out;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .animate-session-enter {
+    animation: none;
+  }
+
+  .animate-session-enter {
+    opacity: 1;
+    transform: none;
+  }
+}
+
 /* ReactQueryDevtools button - move to middle-right to avoid blocking UI */
 .tsqd-open-btn-container {
   bottom: 50% !important;
diff --git a/web/src/lib/agentFlavorUtils.test.ts b/web/src/lib/agentFlavorUtils.test.ts
new file mode 100644
index 000000000..689d6612d
--- /dev/null
+++ b/web/src/lib/agentFlavorUtils.test.ts
@@ -0,0 +1,50 @@
+import { describe, expect, it } from 'vitest'
+import {
+    formatEffortLabel,
+    getFlavorTextClass,
+    META_DOT_SEPARATOR_CLASS
+} from './agentFlavorUtils'
+
+describe('getFlavorTextClass', () => {
+    it.each([
+        ['claude', 'text-[var(--app-flavor-claude-text)] font-medium'],
+        ['codex', 'text-[var(--app-flavor-codex-text)] font-medium'],
+        ['gemini', 'text-[var(--app-flavor-gemini-text)] font-medium'],
+        ['opencode', 'text-[var(--app-flavor-opencode-text)] font-medium'],
+        ['cursor', 'text-[var(--app-flavor-cursor-text)] font-medium']
+    ])('returns flavor class for %s', (flavor, expected) => {
+        expect(getFlavorTextClass(flavor)).toBe(expected)
+    })
+
+    it('falls back for unknown flavors', () => {
+        expect(getFlavorTextClass('mystery')).toBe('text-[var(--app-hint)] font-medium')
+    })
+
+    it('falls back for nullish values', () => {
+        expect(getFlavorTextClass(null)).toBe('text-[var(--app-hint)] font-medium')
+        expect(getFlavorTextClass(undefined)).toBe('text-[var(--app-hint)] font-medium')
+    })
+
+    it('normalizes whitespace and casing', () => {
+        expect(getFlavorTextClass('  CoDeX  ')).toBe('text-[var(--app-flavor-codex-text)] font-medium')
+    })
+})
+
+describe('formatEffortLabel', () => {
+    it('returns null for nullish and blank values', () => {
+        expect(formatEffortLabel(null)).toBeNull()
+        expect(formatEffortLabel('')).toBeNull()
+        expect(formatEffortLabel('   ')).toBeNull()
+    })
+
+    it('title-cases segmented effort labels', () => {
+        expect(formatEffortLabel('very-high')).toBe('Very High')
+        expect(formatEffortLabel('max_reasoning effort')).toBe('Max Reasoning Effort')
+    })
+})
+
+describe('META_DOT_SEPARATOR_CLASS', () => {
+    it('exports the expected separator class', () => {
+        expect(META_DOT_SEPARATOR_CLASS).toBe('text-[var(--app-hint)] opacity-40')
+    })
+})
diff --git a/web/src/lib/agentFlavorUtils.ts b/web/src/lib/agentFlavorUtils.ts
index d835b3505..b2e463e50 100644
--- a/web/src/lib/agentFlavorUtils.ts
+++ b/web/src/lib/agentFlavorUtils.ts
@@ -1,19 +1,56 @@
+function normalizeFlavor(flavor?: string | null): string | null {
+    const normalized = flavor?.trim().toLowerCase()
+    return normalized || null
+}
+
+const SESSION_META_BADGE_BASE = 'inline-flex items-center gap-1 rounded-full border px-2 py-0.5 font-medium leading-none'
+
+export const SESSION_ACTIVITY_BADGE = `${SESSION_META_BADGE_BASE} border-[var(--app-badge-info-border)] bg-[var(--app-badge-info-bg)] text-[var(--app-badge-info-text)]`
+export const SESSION_PENDING_BADGE = `${SESSION_META_BADGE_BASE} border-[var(--app-badge-warning-border)] bg-[var(--app-badge-warning-bg)] text-[var(--app-badge-warning-text)]`
+
 export function isCodexFamilyFlavor(flavor?: string | null): boolean {
-    return flavor === 'codex' || flavor === 'gemini' || flavor === 'opencode'
+    const normalized = normalizeFlavor(flavor)
+    return normalized === 'codex' || normalized === 'gemini' || normalized === 'opencode'
 }
 
 export function isClaudeFlavor(flavor?: string | null): boolean {
-    return flavor === 'claude'
+    return normalizeFlavor(flavor) === 'claude'
 }
 
 export function isCursorFlavor(flavor?: string | null): boolean {
-    return flavor === 'cursor'
+    return normalizeFlavor(flavor) === 'cursor'
 }
 
 export function isKnownFlavor(flavor?: string | null): boolean {
     return isClaudeFlavor(flavor) || isCodexFamilyFlavor(flavor) || isCursorFlavor(flavor)
 }
 
+const FLAVOR_TEXT_CLASSES: Record<string, string> = {
+    claude: 'text-[var(--app-flavor-claude-text)] font-medium',
+    codex: 'text-[var(--app-flavor-codex-text)] font-medium',
+    gemini: 'text-[var(--app-flavor-gemini-text)] font-medium',
+    opencode: 'text-[var(--app-flavor-opencode-text)] font-medium',
+    cursor: 'text-[var(--app-flavor-cursor-text)] font-medium'
+}
+
+export function getFlavorTextClass(flavor?: string | null): string {
+    const normalized = normalizeFlavor(flavor)
+    return normalized ? (FLAVOR_TEXT_CLASSES[normalized] ?? 'text-[var(--app-hint)] font-medium') : 'text-[var(--app-hint)] font-medium'
+}
+
+export const META_DOT_SEPARATOR_CLASS = 'text-[var(--app-hint)] opacity-40'
+
+export function formatEffortLabel(effort?: string | null): string | null {
+    const normalized = effort?.trim()
+    if (!normalized) return null
+
+    return normalized
+        .split(/[-_\s]+/)
+        .filter(Boolean)
+        .map(part => part.charAt(0).toUpperCase() + part.slice(1))
+        .join(' ')
+}
+
 export function supportsModelChange(flavor?: string | null): boolean {
     return flavor === 'claude' || flavor === 'gemini'
 }
diff --git a/web/src/lib/locales/en.ts b/web/src/lib/locales/en.ts
index f26126109..b90f8eb6c 100644
--- a/web/src/lib/locales/en.ts
+++ b/web/src/lib/locales/en.ts
@@ -257,6 +257,14 @@ export default {
   'settings.language.title': 'Language',
   'settings.language.label': 'Language',
   'settings.display.title': 'Display',
+  'settings.display.theme': 'Theme',
+  'settings.display.theme.system': 'System',
+  'settings.display.theme.light': 'Light',
+  'settings.display.theme.dark': 'Dark',
+  'settings.display.theme.catpuccin': 'Catppuccin',
+  'settings.display.theme.gaius': 'Gaius',
+  'settings.display.theme.gaius-light': 'Gaius Light',
+  'settings.display.theme.gaius-dark': 'Gaius Dark',
   'settings.display.appearance': 'Appearance',
   'settings.display.appearance.system': 'Follow System',
   'settings.display.appearance.dark': 'Dark',
diff --git a/web/src/lib/locales/zh-CN.ts b/web/src/lib/locales/zh-CN.ts
index ea220f5a7..d024d6381 100644
--- a/web/src/lib/locales/zh-CN.ts
+++ b/web/src/lib/locales/zh-CN.ts
@@ -259,6 +259,14 @@ export default {
   'settings.language.title': '语言',
   'settings.language.label': '语言',
   'settings.display.title': '显示',
+  'settings.display.theme': '主题',
+  'settings.display.theme.system': '跟随系统',
+  'settings.display.theme.light': '浅色',
+  'settings.display.theme.dark': '深色',
+  'settings.display.theme.catpuccin': 'Catppuccin',
+  'settings.display.theme.gaius': 'Gaius',
+  'settings.display.theme.gaius-light': 'Gaius 浅色',
+  'settings.display.theme.gaius-dark': 'Gaius 深色',
   'settings.display.appearance': '外观',
   'settings.display.appearance.system': '跟随系统',
   'settings.display.appearance.dark': '深色',
diff --git a/web/src/router.tsx b/web/src/router.tsx
index 7527abcdd..b78f50ef9 100644
--- a/web/src/router.tsx
+++ b/web/src/router.tsx
@@ -114,9 +114,11 @@ function SessionsPage() {
         void refetch()
     }, [refetch])
 
-    const projectCount = useMemo(() => new Set(sessions.map(s =>
-        s.metadata?.worktree?.basePath ?? s.metadata?.path ?? 'Other'
-    )).size, [sessions])
+    const projectCount = useMemo(() => new Set(sessions.map(s => {
+        const path = s.metadata?.worktree?.basePath ?? s.metadata?.path ?? 'Other'
+        const machineId = s.metadata?.machineId ?? '__unknown__'
+        return `${machineId}::${path}`
+    })).size, [sessions])
     const machineLabelsById = useMemo(() => {
         const labels: Record<string, string> = {}
         for (const machine of machines) {
@@ -159,7 +161,7 @@ function SessionsPage() {
                     </div>
                 </div>
 
-                <div className="app-scroll-y flex-1 min-h-0 desktop-scrollbar-left">
+                <div className="flex-1 min-h-0 overflow-y-auto desktop-scrollbar-left">
                     {error ? (
                         <div className="mx-auto w-full max-w-content px-3 py-2">
                             <div className="text-sm text-red-600">{error}</div>
@@ -285,7 +287,6 @@ function SessionPage() {
     // Get agent type from session metadata for slash commands
     const agentType = session?.metadata?.flavor ?? 'claude'
     const {
-        commands: slashCommands,
         getSuggestions: getSlashSuggestions,
     } = useSlashCommands(api, sessionId, agentType)
     const {
@@ -332,7 +333,6 @@ function SessionPage() {
             onAtBottomChange={setAtBottom}
             onRetryMessage={retryMessage}
             autocompleteSuggestions={getAutocompleteSuggestions}
-            availableSlashCommands={slashCommands}
         />
     )
 }
@@ -386,10 +386,7 @@ function NewSessionPage() {
                 <div className="flex-1 font-semibold">{t('newSession.title')}</div>
             </div>
 
-            <div
-                className="app-scroll-y flex-1 min-h-0"
-                style={{ paddingBottom: 'calc(var(--app-floating-bottom-offset, 0px) + env(safe-area-inset-bottom))' }}
-            >
+            <div className="app-scroll-y flex-1 min-h-0">
                 {machinesError ? (
                     <div className="p-3 text-sm text-red-600">
                         {machinesError}
diff --git a/web/src/types/api.ts b/web/src/types/api.ts
index 0a2b01b14..e8cb24190 100644
--- a/web/src/types/api.ts
+++ b/web/src/types/api.ts
@@ -212,6 +212,7 @@ export type PushVapidPublicKeyResponse = {
     publicKey: string
 }
 
+
 export type VisibilityPayload = {
     subscriptionId: string
     visibility: 'visible' | 'hidden'

From 46553476226e13a4dc11aee52c8d705b02f28bf2 Mon Sep 17 00:00:00 2001
From: gaius-codius <206332531+gaius-codius@users.noreply.github.com>
Date: Tue, 7 Apr 2026 09:34:09 +0000
Subject: [PATCH 24/27] fix: address PR review follow-ups

---
 .../socket/handlers/cli/sessionHandlers.ts    | 24 +++++++++++++++----
 hub/src/sync/syncEngine.ts                    |  3 +++
 web/playwright.config.ts                      | 19 ++++++++++++++-
 web/src/components/SessionList.tsx            | 13 ++++------
 web/src/hooks/useLongPress.ts                 | 21 +++++++++++++++-
 web/src/index.css                             | 13 +++++++---
 6 files changed, 76 insertions(+), 17 deletions(-)

diff --git a/hub/src/socket/handlers/cli/sessionHandlers.ts b/hub/src/socket/handlers/cli/sessionHandlers.ts
index 67ec014b7..50c43ed7b 100644
--- a/hub/src/socket/handlers/cli/sessionHandlers.ts
+++ b/hub/src/socket/handlers/cli/sessionHandlers.ts
@@ -1,4 +1,5 @@
 import type { ClientToServerEvents } from '@hapi/protocol'
+import { CodexCollaborationModeSchema, ModelModeSchema, PermissionModeSchema } from '@hapi/protocol/schemas'
 import { z } from 'zod'
 import { randomUUID } from 'node:crypto'
 import type { CodexCollaborationMode, PermissionMode } from '@hapi/protocol/types'
@@ -18,6 +19,7 @@ type SessionAlivePayload = {
     model?: string | null
     effort?: string | null
     collaborationMode?: CodexCollaborationMode
+    modelMode?: import('@hapi/protocol/types').ModelMode
 }
 
 type SessionEndPayload = {
@@ -50,6 +52,18 @@ const updateStateSchema = z.object({
     agentState: z.unknown().nullable()
 })
 
+const sessionAliveSchema = z.object({
+    sid: z.string(),
+    time: z.number(),
+    thinking: z.boolean().optional(),
+    mode: z.enum(['local', 'remote']).optional(),
+    permissionMode: PermissionModeSchema.optional(),
+    model: z.string().nullable().optional(),
+    effort: z.string().nullable().optional(),
+    collaborationMode: CodexCollaborationModeSchema.optional(),
+    modelMode: ModelModeSchema.optional()
+})
+
 export type SessionHandlersDeps = {
     store: Store
     resolveSessionAccess: ResolveSessionAccess
@@ -235,15 +249,17 @@ export function registerSessionHandlers(socket: CliSocketWithData, deps: Session
     socket.on('update-state', handleUpdateState)
 
     socket.on('session-alive', (data: SessionAlivePayload) => {
-        if (!data || typeof data.sid !== 'string' || typeof data.time !== 'number') {
+        const parsed = sessionAliveSchema.safeParse(data)
+        if (!parsed.success) {
             return
         }
-        const sessionAccess = resolveSessionAccess(data.sid)
+        const payload = parsed.data
+        const sessionAccess = resolveSessionAccess(payload.sid)
         if (!sessionAccess.ok) {
-            emitAccessError('session', data.sid, sessionAccess.reason)
+            emitAccessError('session', payload.sid, sessionAccess.reason)
             return
         }
-        onSessionAlive?.(data)
+        onSessionAlive?.(payload)
     })
 
     socket.on('session-end', (data: SessionEndPayload) => {
diff --git a/hub/src/sync/syncEngine.ts b/hub/src/sync/syncEngine.ts
index 7e27fcf99..ef8ee69f6 100644
--- a/hub/src/sync/syncEngine.ts
+++ b/hub/src/sync/syncEngine.ts
@@ -305,6 +305,9 @@ export class SyncEngine {
             modelMode?: Session['modelMode']
         }
     ): Promise<void> {
+        // modelMode is currently hub-managed metadata only. CLI agents do not yet
+        // accept it through set-session-config RPC, so we apply the validated value
+        // locally after the agent acknowledges the rest of the config.
         const rpcConfig = {
             permissionMode: config.permissionMode,
             model: config.model,
diff --git a/web/playwright.config.ts b/web/playwright.config.ts
index 531209ce3..b19469a85 100644
--- a/web/playwright.config.ts
+++ b/web/playwright.config.ts
@@ -6,6 +6,23 @@ const hapiHome = process.env.HAPI_E2E_HAPI_HOME ?? `/tmp/hapi-playwright-${port}
 const cliApiToken = process.env.HAPI_E2E_CLI_TOKEN ?? 'pw-test-token'
 const bunBin = process.env.BUN_BIN ?? 'bun'
 
+function shellQuote(value: string): string {
+    return `'${value.replace(/'/g, `'\"'\"'`)}'`
+}
+
+const buildCommand = [
+    `${shellQuote(bunBin)} run build`,
+    `rm -rf ${shellQuote(hapiHome)}`,
+    `mkdir -p ${shellQuote(hapiHome)}`,
+    [
+        `CLI_API_TOKEN=${shellQuote(cliApiToken)}`,
+        `HAPI_HOME=${shellQuote(hapiHome)}`,
+        'HAPI_LISTEN_HOST=127.0.0.1',
+        `HAPI_LISTEN_PORT=${port}`,
+        `${shellQuote(bunBin)} run --cwd ../hub src/index.ts`
+    ].join(' ')
+].join(' && ')
+
 export default defineConfig({
     testDir: './e2e',
     timeout: 180_000,
@@ -29,7 +46,7 @@ export default defineConfig({
         }
     ],
     webServer: {
-        command: `${bunBin} run build && rm -rf "${hapiHome}" && mkdir -p "${hapiHome}" && CLI_API_TOKEN=${cliApiToken} HAPI_HOME="${hapiHome}" HAPI_LISTEN_HOST=127.0.0.1 HAPI_LISTEN_PORT=${port} ${bunBin} run --cwd ../hub src/index.ts`,
+        command: buildCommand,
         url: `${baseUrl}/health`,
         timeout: 120_000,
         reuseExistingServer: false
diff --git a/web/src/components/SessionList.tsx b/web/src/components/SessionList.tsx
index 744bd1a60..794a2a456 100644
--- a/web/src/components/SessionList.tsx
+++ b/web/src/components/SessionList.tsx
@@ -417,11 +417,14 @@ export function SessionList(props: {
     )
     const enteringSessionIds = useMemo(() => {
         const entering = new Set<string>()
+        const nextKnownSessionIds = new Set(knownSessionIdsRef.current)
         props.sessions.forEach(session => {
-            if (!knownSessionIdsRef.current.has(session.id)) {
+            if (!nextKnownSessionIds.has(session.id)) {
                 entering.add(session.id)
             }
+            nextKnownSessionIds.add(session.id)
         })
+        knownSessionIdsRef.current = nextKnownSessionIds
         return entering
     }, [props.sessions])
 
@@ -481,12 +484,6 @@ export function SessionList(props: {
         })
     }, [displayGroups])
 
-    useEffect(() => {
-        props.sessions.forEach(session => {
-            knownSessionIdsRef.current.add(session.id)
-        })
-    }, [props.sessions])
-
     return (
         <div className="mx-auto w-full max-w-content flex flex-col">
             {renderHeader ? (
@@ -519,7 +516,7 @@ export function SessionList(props: {
                             />
                             {!isCollapsed ? (
                                 <div className="flex flex-col divide-y divide-[var(--app-divider)] border-b border-[var(--app-divider)] border-l border-l-[var(--app-divider)]">
-                                    {group.sessions.map((s, index) => (
+                                    {group.sessions.map((s) => (
                                         <SessionItem
                                             key={s.id}
                                             session={s}
diff --git a/web/src/hooks/useLongPress.ts b/web/src/hooks/useLongPress.ts
index ffeb81399..ec65f7882 100644
--- a/web/src/hooks/useLongPress.ts
+++ b/web/src/hooks/useLongPress.ts
@@ -10,6 +10,7 @@ type UseLongPressOptions = {
 
 type UseLongPressHandlers = {
     onPointerDown: React.PointerEventHandler
+    onPointerMove: React.PointerEventHandler
     onPointerUp: React.PointerEventHandler
     onPointerLeave: React.PointerEventHandler
     onPointerCancel: React.PointerEventHandler
@@ -23,6 +24,8 @@ export function useLongPress(options: UseLongPressOptions): UseLongPressHandlers
     const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null)
     const isLongPressRef = useRef(false)
     const pressPointRef = useRef<{ x: number; y: number }>({ x: 0, y: 0 })
+    const movedBeyondThresholdRef = useRef(false)
+    const moveThresholdPx = 8
 
     const clearTimer = useCallback(() => {
         if (timerRef.current) {
@@ -36,6 +39,7 @@ export function useLongPress(options: UseLongPressOptions): UseLongPressHandlers
 
         clearTimer()
         isLongPressRef.current = false
+        movedBeyondThresholdRef.current = false
         pressPointRef.current = { x: clientX, y: clientY }
 
         timerRef.current = setTimeout(() => {
@@ -52,6 +56,7 @@ export function useLongPress(options: UseLongPressOptions): UseLongPressHandlers
         }
 
         isLongPressRef.current = false
+        movedBeyondThresholdRef.current = false
     }, [clearTimer, onClick])
 
     const onPointerDown = useCallback<React.PointerEventHandler>((e) => {
@@ -60,9 +65,22 @@ export function useLongPress(options: UseLongPressOptions): UseLongPressHandlers
         startTimer(e.clientX, e.clientY)
     }, [startTimer])
 
+    const onPointerMove = useCallback<React.PointerEventHandler>((e) => {
+        if (!e.isPrimary || movedBeyondThresholdRef.current) return
+
+        const dx = e.clientX - pressPointRef.current.x
+        const dy = e.clientY - pressPointRef.current.y
+        if (Math.hypot(dx, dy) < moveThresholdPx) {
+            return
+        }
+
+        movedBeyondThresholdRef.current = true
+        clearTimer()
+    }, [clearTimer])
+
     const onPointerUp = useCallback<React.PointerEventHandler>((e) => {
         if (!e.isPrimary) return
-        handleEnd(!isLongPressRef.current)
+        handleEnd(!isLongPressRef.current && !movedBeyondThresholdRef.current)
     }, [handleEnd])
 
     const onPointerLeave = useCallback<React.PointerEventHandler>((e) => {
@@ -94,6 +112,7 @@ export function useLongPress(options: UseLongPressOptions): UseLongPressHandlers
 
     return {
         onPointerDown,
+        onPointerMove,
         onPointerUp,
         onPointerLeave,
         onPointerCancel,
diff --git a/web/src/index.css b/web/src/index.css
index 744c279d4..8252547c4 100644
--- a/web/src/index.css
+++ b/web/src/index.css
@@ -385,6 +385,16 @@ body {
     }
 }
 
+/*
+ * content-visibility: auto lets the browser skip layout/paint for messages
+ * scrolled out of the viewport. Big win on Windows with long conversations (#310).
+ * contain-intrinsic-size gives a rough height hint so scrollbar doesn't jump.
+ */
+.happy-thread-messages > * {
+    content-visibility: auto;
+    contain-intrinsic-size: auto 80px;
+}
+
 /* Markdown styles */
 .markdown-content a { color: var(--app-link); text-decoration: underline; }
 .markdown-content code { background: var(--app-inline-code-bg); padding: 0.1em 0.3em; border-radius: 4px; font-size: 0.9em; }
@@ -541,9 +551,6 @@ html[data-theme="gaius-dark"] .shiki span {
 @media (prefers-reduced-motion: reduce) {
   .animate-session-enter {
     animation: none;
-  }
-
-  .animate-session-enter {
     opacity: 1;
     transform: none;
   }

From 6524779d8364139202de56f89aaa357cc98db35a Mon Sep 17 00:00:00 2001
From: gaius-codius <206332531+gaius-codius@users.noreply.github.com>
Date: Tue, 14 Apr 2026 22:14:07 +0000
Subject: [PATCH 25/27] chore: remove out-of-scope theme definitions
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Strip catpuccin, gaius-light, and gaius-dark theme blocks from CSS
and locale files — these belong in a separate theming PR.

via [HAPI](https://hapi.run)
---
 web/src/index.css            | 206 +----------------------------------
 web/src/lib/locales/en.ts    |   8 --
 web/src/lib/locales/zh-CN.ts |   8 --
 3 files changed, 1 insertion(+), 221 deletions(-)

diff --git a/web/src/index.css b/web/src/index.css
index 8252547c4..5bcc9bd2f 100644
--- a/web/src/index.css
+++ b/web/src/index.css
@@ -135,206 +135,6 @@
     --app-flavor-cursor-border: rgba(148, 163, 184, 0.28);
 }
 
-[data-theme="catpuccin"] {
-    /* Primary colors — Catpuccin Mocha */
-    --app-bg: #1e1e2e;
-    --app-fg: #cdd6f4;
-    --app-hint: #6c7086;
-    --app-link: #cdd6f4;
-    --app-button: #cdd6f4;
-    --app-button-text: #1e1e2e;
-    --app-banner-bg: #313244;
-    --app-banner-text: #cdd6f4;
-    --app-secondary-bg: #313244;
-
-    --app-border: rgba(255, 255, 255, 0.1);
-    --app-divider: rgba(255, 255, 255, 0.08);
-    --app-subtle-bg: rgba(255, 255, 255, 0.05);
-    --app-code-bg: #282c34;
-    --app-inline-code-bg: rgba(255, 255, 255, 0.1);
-
-    /* Diff colors (dark) */
-    --app-diff-added-bg: #0d2e1f;
-    --app-diff-added-text: #c9d1d9;
-    --app-diff-removed-bg: #3f1b23;
-    --app-diff-removed-text: #c9d1d9;
-
-    /* Git status colors */
-    --app-git-staged-color: #a6e3a1;
-    --app-git-unstaged-color: #fab387;
-    --app-git-deleted-color: #f38ba8;
-    --app-git-renamed-color: #89b4fa;
-    --app-git-untracked-color: #6c7086;
-
-    /* Badge colors — Catpuccin Mocha */
-    --app-badge-info-bg: rgba(137, 180, 250, 0.12);
-    --app-badge-info-text: #89b4fa;
-    --app-badge-info-border: rgba(137, 180, 250, 0.22);
-    --app-badge-warning-bg: rgba(250, 179, 135, 0.15);
-    --app-badge-warning-text: #fab387;
-    --app-badge-warning-border: rgba(250, 179, 135, 0.25);
-    --app-badge-success-bg: rgba(166, 227, 161, 0.15);
-    --app-badge-success-text: #a6e3a1;
-    --app-badge-success-border: rgba(166, 227, 161, 0.25);
-    --app-badge-error-bg: rgba(243, 139, 168, 0.15);
-    --app-badge-error-text: #f38ba8;
-    --app-badge-error-border: rgba(243, 139, 168, 0.25);
-
-    --app-flavor-claude: #fab387;
-    --app-flavor-claude-bg: rgba(250, 179, 135, 0.10);
-    --app-flavor-claude-text: #fab387;
-    --app-flavor-claude-border: rgba(250, 179, 135, 0.20);
-    --app-flavor-codex: #a6e3a1;
-    --app-flavor-codex-bg: rgba(166, 227, 161, 0.10);
-    --app-flavor-codex-text: #a6e3a1;
-    --app-flavor-codex-border: rgba(166, 227, 161, 0.20);
-    --app-flavor-gemini: #74c7ec;
-    --app-flavor-gemini-bg: rgba(116, 199, 236, 0.10);
-    --app-flavor-gemini-text: #74c7ec;
-    --app-flavor-gemini-border: rgba(116, 199, 236, 0.20);
-    --app-flavor-opencode: #cba6f7;
-    --app-flavor-opencode-bg: rgba(203, 166, 247, 0.10);
-    --app-flavor-opencode-text: #cba6f7;
-    --app-flavor-opencode-border: rgba(203, 166, 247, 0.20);
-    --app-flavor-cursor-bg: rgba(186, 194, 222, 0.10);
-    --app-flavor-cursor-text: #bac2de;
-    --app-flavor-cursor-border: rgba(186, 194, 222, 0.20);
-}
-
-[data-theme="gaius-light"] {
-    /* Primary — warm pearl base */
-    --app-bg: #f8f5f2;
-    --app-fg: #2a2832;
-    --app-hint: #85808a;
-    --app-link: #b04440;
-    --app-button: #2a2832;
-    --app-button-text: #f8f5f2;
-    --app-banner-bg: #eceae6;
-    --app-banner-text: #2a2832;
-    --app-secondary-bg: #f0ede9;
-
-    /* Overlays */
-    --app-border: rgba(42, 40, 50, 0.10);
-    --app-divider: rgba(42, 40, 50, 0.07);
-    --app-subtle-bg: rgba(42, 40, 50, 0.03);
-    --app-code-bg: #f0ede8;
-    --app-inline-code-bg: rgba(42, 40, 50, 0.05);
-
-    /* Diffs — verdigris added, cinnabar removed */
-    --app-diff-added-bg: #e4edd8;
-    --app-diff-added-text: #2a2832;
-    --app-diff-removed-bg: #f2dcd8;
-    --app-diff-removed-text: #2a2832;
-
-    /* Git status */
-    --app-git-staged-color: #3a7868;
-    --app-git-unstaged-color: #b07830;
-    --app-git-deleted-color: #b84440;
-    --app-git-renamed-color: #4068a0;
-    --app-git-untracked-color: #85808a;
-
-    /* Badges — lapis, gold, verdigris, cinnabar */
-    --app-badge-info-bg: rgba(64, 104, 160, 0.10);
-    --app-badge-info-text: #3a5888;
-    --app-badge-info-border: rgba(64, 104, 160, 0.20);
-    --app-badge-warning-bg: rgba(176, 120, 48, 0.12);
-    --app-badge-warning-text: #8a5820;
-    --app-badge-warning-border: rgba(176, 120, 48, 0.22);
-    --app-badge-success-bg: rgba(58, 120, 104, 0.10);
-    --app-badge-success-text: #2a6858;
-    --app-badge-success-border: rgba(58, 120, 104, 0.20);
-    --app-badge-error-bg: rgba(184, 68, 64, 0.10);
-    --app-badge-error-text: #983838;
-    --app-badge-error-border: rgba(184, 68, 64, 0.20);
-
-    --app-flavor-claude: #a04038;
-    --app-flavor-claude-bg: rgba(160, 64, 56, 0.08);
-    --app-flavor-claude-text: #a04038;
-    --app-flavor-claude-border: rgba(160, 64, 56, 0.18);
-    --app-flavor-codex: #2a6858;
-    --app-flavor-codex-bg: rgba(42, 104, 88, 0.08);
-    --app-flavor-codex-text: #2a6858;
-    --app-flavor-codex-border: rgba(42, 104, 88, 0.18);
-    --app-flavor-gemini: #3a5888;
-    --app-flavor-gemini-bg: rgba(58, 88, 136, 0.08);
-    --app-flavor-gemini-text: #3a5888;
-    --app-flavor-gemini-border: rgba(58, 88, 136, 0.18);
-    --app-flavor-opencode: #6a5090;
-    --app-flavor-opencode-bg: rgba(106, 80, 144, 0.08);
-    --app-flavor-opencode-text: #6a5090;
-    --app-flavor-opencode-border: rgba(106, 80, 144, 0.18);
-    --app-flavor-cursor-bg: rgba(106, 104, 116, 0.08);
-    --app-flavor-cursor-text: #6a6874;
-    --app-flavor-cursor-border: rgba(106, 104, 116, 0.18);
-}
-
-[data-theme="gaius-dark"] {
-    /* Primary — deep slate base */
-    --app-bg: #1e1d22;
-    --app-fg: #e6e3de;
-    --app-hint: #88848e;
-    --app-link: #d06058;
-    --app-button: #e6e3de;
-    --app-button-text: #1e1d22;
-    --app-banner-bg: #2a2930;
-    --app-banner-text: #e6e3de;
-    --app-secondary-bg: #252428;
-
-    /* Overlays */
-    --app-border: rgba(230, 227, 222, 0.08);
-    --app-divider: rgba(230, 227, 222, 0.06);
-    --app-subtle-bg: rgba(230, 227, 222, 0.04);
-    --app-code-bg: #252430;
-    --app-inline-code-bg: rgba(230, 227, 222, 0.07);
-
-    /* Diffs */
-    --app-diff-added-bg: rgba(80, 150, 130, 0.12);
-    --app-diff-added-text: #d8d5d0;
-    --app-diff-removed-bg: rgba(200, 80, 70, 0.12);
-    --app-diff-removed-text: #d8d5d0;
-
-    /* Git status */
-    --app-git-staged-color: #68b8a0;
-    --app-git-unstaged-color: #d0a060;
-    --app-git-deleted-color: #d87068;
-    --app-git-renamed-color: #6890c8;
-    --app-git-untracked-color: #88848e;
-
-    /* Badges */
-    --app-badge-info-bg: rgba(104, 144, 200, 0.12);
-    --app-badge-info-text: #6890c8;
-    --app-badge-info-border: rgba(104, 144, 200, 0.20);
-    --app-badge-warning-bg: rgba(208, 160, 96, 0.15);
-    --app-badge-warning-text: #d0a060;
-    --app-badge-warning-border: rgba(208, 160, 96, 0.25);
-    --app-badge-success-bg: rgba(104, 184, 160, 0.10);
-    --app-badge-success-text: #68b8a0;
-    --app-badge-success-border: rgba(104, 184, 160, 0.20);
-    --app-badge-error-bg: rgba(216, 112, 104, 0.12);
-    --app-badge-error-text: #d87068;
-    --app-badge-error-border: rgba(216, 112, 104, 0.22);
-
-    --app-flavor-claude: #d08858;
-    --app-flavor-claude-bg: rgba(208, 136, 88, 0.10);
-    --app-flavor-claude-text: #d08858;
-    --app-flavor-claude-border: rgba(208, 136, 88, 0.20);
-    --app-flavor-codex: #68b8a0;
-    --app-flavor-codex-bg: rgba(104, 184, 160, 0.10);
-    --app-flavor-codex-text: #68b8a0;
-    --app-flavor-codex-border: rgba(104, 184, 160, 0.20);
-    --app-flavor-gemini: #6890c8;
-    --app-flavor-gemini-bg: rgba(104, 144, 200, 0.10);
-    --app-flavor-gemini-text: #6890c8;
-    --app-flavor-gemini-border: rgba(104, 144, 200, 0.20);
-    --app-flavor-opencode: #a088c0;
-    --app-flavor-opencode-bg: rgba(160, 136, 192, 0.10);
-    --app-flavor-opencode-text: #a088c0;
-    --app-flavor-opencode-border: rgba(160, 136, 192, 0.20);
-    --app-flavor-cursor-bg: rgba(176, 172, 182, 0.10);
-    --app-flavor-cursor-text: #b0acb6;
-    --app-flavor-cursor-border: rgba(176, 172, 182, 0.20);
-}
-
 html {
     font-size: calc(100% * var(--app-font-scale, 1));
 }
@@ -430,11 +230,7 @@ body {
 }
 
 html[data-theme="dark"] .shiki,
-html[data-theme="dark"] .shiki span,
-html[data-theme="catpuccin"] .shiki,
-html[data-theme="catpuccin"] .shiki span,
-html[data-theme="gaius-dark"] .shiki,
-html[data-theme="gaius-dark"] .shiki span {
+html[data-theme="dark"] .shiki span {
     color: var(--shiki-dark) !important;
     font-style: var(--shiki-dark-font-style) !important;
     font-weight: var(--shiki-dark-font-weight) !important;
diff --git a/web/src/lib/locales/en.ts b/web/src/lib/locales/en.ts
index b90f8eb6c..f26126109 100644
--- a/web/src/lib/locales/en.ts
+++ b/web/src/lib/locales/en.ts
@@ -257,14 +257,6 @@ export default {
   'settings.language.title': 'Language',
   'settings.language.label': 'Language',
   'settings.display.title': 'Display',
-  'settings.display.theme': 'Theme',
-  'settings.display.theme.system': 'System',
-  'settings.display.theme.light': 'Light',
-  'settings.display.theme.dark': 'Dark',
-  'settings.display.theme.catpuccin': 'Catppuccin',
-  'settings.display.theme.gaius': 'Gaius',
-  'settings.display.theme.gaius-light': 'Gaius Light',
-  'settings.display.theme.gaius-dark': 'Gaius Dark',
   'settings.display.appearance': 'Appearance',
   'settings.display.appearance.system': 'Follow System',
   'settings.display.appearance.dark': 'Dark',
diff --git a/web/src/lib/locales/zh-CN.ts b/web/src/lib/locales/zh-CN.ts
index d024d6381..ea220f5a7 100644
--- a/web/src/lib/locales/zh-CN.ts
+++ b/web/src/lib/locales/zh-CN.ts
@@ -259,14 +259,6 @@ export default {
   'settings.language.title': '语言',
   'settings.language.label': '语言',
   'settings.display.title': '显示',
-  'settings.display.theme': '主题',
-  'settings.display.theme.system': '跟随系统',
-  'settings.display.theme.light': '浅色',
-  'settings.display.theme.dark': '深色',
-  'settings.display.theme.catpuccin': 'Catppuccin',
-  'settings.display.theme.gaius': 'Gaius',
-  'settings.display.theme.gaius-light': 'Gaius 浅色',
-  'settings.display.theme.gaius-dark': 'Gaius 深色',
   'settings.display.appearance': '外观',
   'settings.display.appearance.system': '跟随系统',
   'settings.display.appearance.dark': '深色',

From c9d5660b0b0467f06bb9a75387e681252db3cb18 Mon Sep 17 00:00:00 2001
From: gaius-codius <206332531+gaius-codius@users.noreply.github.com>
Date: Sun, 19 Apr 2026 12:00:40 +0000
Subject: [PATCH 26/27] chore: sync branch with main and refresh lockfile

---
 bun.lock                             |  4 +-
 hub/src/sync/syncEngine.ts           | 66 ++++++++++++++++++++++++++--
 shared/src/schemas.ts                | 27 ++++++++++++
 web/src/components/SessionHeader.tsx |  2 -
 web/src/components/SessionList.tsx   | 50 +++++----------------
 web/src/index.css                    |  8 +---
 web/src/router.tsx                   | 33 +++++---------
 web/src/types/api.ts                 | 13 ++++++
 8 files changed, 129 insertions(+), 74 deletions(-)

diff --git a/bun.lock b/bun.lock
index caa5d8187..bc1f24036 100644
--- a/bun.lock
+++ b/bun.lock
@@ -883,7 +883,9 @@
 
     "@twsxtd/hapi-linux-arm64": ["@twsxtd/hapi-linux-arm64@0.16.5", "", { "os": "linux", "cpu": "arm64", "bin": { "hapi": "bin/hapi" } }, "sha512-UlYpOd89C3ePAiy/6Zcz9NziN2vFIEMipBeS0mb6s4U7qP3Um6E4BwoKIUhIlriy8RxyZxRvXq1EtMxECh6M+g=="],
 
-    "@twsxtd/hapi-win32-x64": ["@twsxtd/hapi-win32-x64@0.15.2", "", { "os": "win32", "cpu": "x64", "bin": { "hapi": "bin/hapi.exe" } }, "sha512-vuQH9INKvqwVZ9JphUmEyzKz6zWxHy3GE4j0mDqTulO234nGEhljkN3Qod0d7bLVncmO53zSMcm+ahwZ3qL4OA=="],
+    "@twsxtd/hapi-linux-x64": ["@twsxtd/hapi-linux-x64@0.16.5", "", { "os": "linux", "cpu": "x64", "bin": { "hapi": "bin/hapi" } }, "sha512-Cdo2B/BCnDJRkkGHxMo8UVVcKXJyuS7bnr+JtJL4f6kp7o8T2T9o/85S05Z/TF8k5dAxz2Np8rpJgmhBd/1boA=="],
+
+    "@twsxtd/hapi-win32-x64": ["@twsxtd/hapi-win32-x64@0.16.5", "", { "os": "win32", "cpu": "x64", "bin": { "hapi": "bin/hapi.exe" } }, "sha512-jnl5zxT2AIslIy2X9jYklTUIob/Om8RlPIx2QbobkYP5+mMpPWUpJsBFx1NdN8FDMApcVQ/tqh6v2d72m16rDA=="],
 
     "@types/aria-query": ["@types/aria-query@5.0.4", "", {}, "sha512-rfT93uj5s0PRL7EzccGMs3brplhcrghnDoV26NqKhCAS1hVo+WdNsPvE/yb6ilfr5hi2MEk6d5EWJTKdxg8jVw=="],
 
diff --git a/hub/src/sync/syncEngine.ts b/hub/src/sync/syncEngine.ts
index 0efe6144b..77e147b54 100644
--- a/hub/src/sync/syncEngine.ts
+++ b/hub/src/sync/syncEngine.ts
@@ -12,6 +12,9 @@ import type {
     DecryptedMessage,
     PermissionMode,
     Session,
+    SessionManualOrder,
+    SessionSortMode,
+    SessionSortPreference,
     SyncEvent
 } from '@hapi/protocol/types'
 import type { Server } from 'socket.io'
@@ -48,6 +51,10 @@ export type ResumeSessionResult =
     | { type: 'success'; sessionId: string }
     | { type: 'error'; message: string; code: 'session_not_found' | 'access_denied' | 'no_machine_online' | 'resume_unavailable' | 'resume_failed' }
 
+export type SetSessionSortPreferenceResult =
+    | { result: 'success'; preference: SessionSortPreference }
+    | { result: 'version-mismatch'; preference: SessionSortPreference }
+    | { result: 'error' }
 
 export class SyncEngine {
     private readonly store: Store
@@ -106,6 +113,62 @@ export class SyncEngine {
         return this.sessionCache.getSessionsByNamespace(namespace)
     }
 
+    getSessionSortPreference(userId: number, namespace: string): SessionSortPreference {
+        const preference = this.store.sessionSortPreferences.getByUser(userId, namespace)
+        return {
+            sortMode: preference.sortMode,
+            manualOrder: preference.manualOrder,
+            version: preference.version,
+            updatedAt: preference.updatedAt
+        }
+    }
+
+    setSessionSortPreference(
+        userId: number,
+        namespace: string,
+        input: {
+            sortMode: SessionSortMode
+            manualOrder: SessionManualOrder
+            expectedVersion?: number
+        }
+    ): SetSessionSortPreferenceResult {
+        const result = this.store.sessionSortPreferences.upsertByUser(
+            userId,
+            namespace,
+            {
+                sortMode: input.sortMode,
+                manualOrder: input.manualOrder
+            },
+            input.expectedVersion
+        )
+
+        if (result.result === 'error') {
+            return { result: 'error' }
+        }
+
+        const preference: SessionSortPreference = {
+            sortMode: result.preference.sortMode,
+            manualOrder: result.preference.manualOrder,
+            version: result.preference.version,
+            updatedAt: result.preference.updatedAt
+        }
+
+        if (result.result === 'success') {
+            this.eventPublisher.emit({
+                type: 'session-sort-preference-updated',
+                namespace,
+                data: {
+                    userId,
+                    version: preference.version
+                }
+            })
+        }
+
+        return {
+            result: result.result,
+            preference
+        }
+    }
 
     getSession(sessionId: string): Session | undefined {
         return this.sessionCache.getSession(sessionId) ?? this.sessionCache.refreshSession(sessionId) ?? undefined
@@ -307,9 +370,6 @@ export class SyncEngine {
             modelMode?: Session['modelMode']
         }
     ): Promise<void> {
-        // modelMode is currently hub-managed metadata only. CLI agents do not yet
-        // accept it through set-session-config RPC, so we apply the validated value
-        // locally after the agent acknowledges the rest of the config.
         const rpcConfig = {
             permissionMode: config.permissionMode,
             model: config.model,
diff --git a/shared/src/schemas.ts b/shared/src/schemas.ts
index a0b696e0d..d630942b1 100644
--- a/shared/src/schemas.ts
+++ b/shared/src/schemas.ts
@@ -4,6 +4,26 @@ import { CODEX_COLLABORATION_MODES, MODEL_MODES, PERMISSION_MODES } from './mode
 export const PermissionModeSchema = z.enum(PERMISSION_MODES)
 export const ModelModeSchema = z.enum(MODEL_MODES)
 export const CodexCollaborationModeSchema = z.enum(CODEX_COLLABORATION_MODES)
+export const SessionSortModeSchema = z.enum(['auto', 'manual'])
+
+export type SessionSortMode = z.infer<typeof SessionSortModeSchema>
+
+export const SessionManualOrderSchema = z.object({
+    groupOrder: z.array(z.string().max(256)).max(500),
+    sessionOrder: z.record(z.string().max(256), z.array(z.string().max(128)).max(200))
+}).strict()
+
+export type SessionManualOrder = z.infer<typeof SessionManualOrderSchema>
+
+export const SessionSortPreferenceSchema = z.object({
+    sortMode: SessionSortModeSchema,
+    manualOrder: SessionManualOrderSchema,
+    version: z.number().int().positive(),
+    updatedAt: z.number().int().nonnegative()
+}).strict()
+
+export type SessionSortPreference = z.infer<typeof SessionSortPreferenceSchema>
+
 const MetadataSummarySchema = z.object({
     text: z.string(),
     updatedAt: z.number()
@@ -238,6 +258,13 @@ export const SyncEventSchema = z.discriminatedUnion('type', [
             subscriptionId: z.string().optional()
         }).optional()
     }),
+    SessionEventBaseSchema.extend({
+        type: z.literal('session-sort-preference-updated'),
+        data: z.object({
+            userId: z.number().int().nonnegative(),
+            version: z.number().int().positive()
+        })
+    })
 ])
 
 export type SyncEvent = z.infer<typeof SyncEventSchema>
diff --git a/web/src/components/SessionHeader.tsx b/web/src/components/SessionHeader.tsx
index 68147f31e..416f5a9ff 100644
--- a/web/src/components/SessionHeader.tsx
+++ b/web/src/components/SessionHeader.tsx
@@ -2,7 +2,6 @@ import { Fragment, type ReactNode, useId, useMemo, useRef, useState } from 'reac
 import { getPermissionModeLabel, isPermissionModeAllowedForFlavor } from '@hapi/protocol'
 import type { Session } from '@/types/api'
 import type { ApiClient } from '@/api/client'
-import { getPermissionModeLabel, getPermissionModeTone, isPermissionModeAllowedForFlavor } from '@hapi/protocol'
 import { isTelegramApp } from '@/hooks/useTelegram'
 import { useSessionActions } from '@/hooks/mutations/useSessionActions'
 import { SessionActionMenu } from '@/components/SessionActionMenu'
@@ -11,7 +10,6 @@ import { ConfirmDialog } from '@/components/ui/ConfirmDialog'
 import { formatEffortLabel, getFlavorTextClass, META_DOT_SEPARATOR_CLASS } from '@/lib/agentFlavorUtils'
 import { getSessionModelLabel } from '@/lib/sessionModelLabel'
 import { useTranslation } from '@/lib/use-translation'
-import { getFlavorBadgeClass, PERMISSION_TONE_BADGE } from '@/lib/agentFlavorUtils'
 
 function getSessionTitle(session: Session): string {
     if (session.metadata?.name) {
diff --git a/web/src/components/SessionList.tsx b/web/src/components/SessionList.tsx
index 40249859a..794a2a456 100644
--- a/web/src/components/SessionList.tsx
+++ b/web/src/components/SessionList.tsx
@@ -1,14 +1,10 @@
 import { Fragment, type ReactNode, useEffect, useMemo, useRef, useState } from 'react'
 import type { SessionSummary } from '@/types/api'
 import type { ApiClient } from '@/api/client'
-import { getPermissionModeLabel, getPermissionModeTone, isPermissionModeAllowedForFlavor } from '@hapi/protocol'
 import { useLongPress } from '@/hooks/useLongPress'
 import { usePlatform } from '@/hooks/usePlatform'
 import { useSessionActions } from '@/hooks/mutations/useSessionActions'
-import { useSortToggle } from '@/hooks/useSortToggle'
-import { SortIcon, PinIcon } from '@/components/icons/SortIcons'
 import { SessionActionMenu } from '@/components/SessionActionMenu'
-import { GroupActionMenu } from '@/components/GroupActionMenu'
 import { RenameSessionDialog } from '@/components/RenameSessionDialog'
 import { ConfirmDialog } from '@/components/ui/ConfirmDialog'
 import {
@@ -19,7 +15,6 @@ import {
 } from '@/lib/agentFlavorUtils'
 import { getSessionModelLabel } from '@/lib/sessionModelLabel'
 import { useTranslation } from '@/lib/use-translation'
-import { getFlavorTextClass, PERMISSION_TONE_TEXT } from '@/lib/agentFlavorUtils'
 
 type SessionGroup = {
     key: string
@@ -47,7 +42,7 @@ export function groupSessionsByDirectory(sessions: SessionSummary[]): SessionGro
     sessions.forEach(session => {
         const path = session.metadata?.worktree?.basePath ?? session.metadata?.path ?? 'Other'
         const machineId = session.metadata?.machineId ?? null
-        const key = `${machineId ?? '__unknown__'}::${path}`
+        const key = `${machineId ?? UNKNOWN_MACHINE_ID}::${path}`
         if (!groups.has(key)) {
             groups.set(key, {
                 directory: path,
@@ -239,18 +234,6 @@ function SessionItem(props: {
     const statusDotClass = s.active
         ? (s.thinking ? 'bg-[var(--app-badge-info-text)]' : 'bg-[var(--app-badge-success-text)]')
         : 'bg-[var(--app-hint)]'
-
-    const flavor = s.metadata?.flavor?.trim() ?? null
-    const flavorTextClass = getFlavorTextClass(flavor)
-
-    const permMode = s.permissionMode
-        && s.permissionMode !== 'default'
-        && isPermissionModeAllowedForFlavor(s.permissionMode, flavor)
-        ? s.permissionMode
-        : null
-    const permLabel = permMode ? getPermissionModeLabel(permMode).toLowerCase() : null
-    const permTone = permMode ? getPermissionModeTone(permMode) : null
-    const permTextClass = permTone ? PERMISSION_TONE_TEXT[permTone] : ''
     const todoProgress = getTodoProgress(s)
     const inactiveClass = s.active ? '' : 'opacity-[0.55]'
     const metadataItems = [
@@ -316,11 +299,6 @@ function SessionItem(props: {
                 isOpen={menuOpen}
                 onClose={() => setMenuOpen(false)}
                 sessionActive={s.active}
-                manualMode={manualMode}
-                onMoveUp={onMoveUp}
-                onMoveDown={onMoveDown}
-                canMoveUp={canMoveUp}
-                canMoveDown={canMoveDown}
                 onRename={() => setRenameOpen(true)}
                 onArchive={() => setArchiveOpen(true)}
                 onDelete={() => setDeleteOpen(true)}
@@ -459,14 +437,14 @@ export function SessionList(props: {
         return !group.hasActiveSession && !hasSelectedSession
     }
 
-    const closeGroupActionMenu = () => {
-        setGroupMenuOpen(false)
+    const toggleGroup = (groupKey: string, isCollapsed: boolean) => {
+        setCollapseOverrides(prev => {
+            const next = new Map(prev)
+            next.set(groupKey, !isCollapsed)
+            return next
+        })
     }
 
-    const groupMenuIndex = groupMenuKey ? orderedGroups.findIndex((group) => group.key === groupMenuKey) : -1
-    const canMoveGroupUp = groupMenuIndex > 0
-    const canMoveGroupDown = groupMenuIndex >= 0 && groupMenuIndex < orderedGroups.length - 1
-
     const resolveMachineLabel = (machineId: string | null): string => {
         if (machineId && machineLabelsById[machineId]) {
             return machineLabelsById[machineId]
@@ -476,20 +454,16 @@ export function SessionList(props: {
         }
         return t('machine.unknown')
     }
-    const isGroupCollapsed = (group: SessionGroup): boolean => {
-        const override = collapseOverrides.get(group.key)
-        if (override !== undefined) return override
-        return !group.hasActiveSession
-    }
 
-    const toggleGroup = (groupKey: string, isCollapsed: boolean) => {
+    useEffect(() => {
+        if (!selectedSessionId) return
         setCollapseOverrides(prev => {
             const group = displayGroups.find(g =>
                 g.sessions.some(s => s.id === selectedSessionId)
             )
             if (!group || !prev.has(group.key) || !prev.get(group.key)) return prev
             const next = new Map(prev)
-            next.set(groupKey, !isCollapsed)
+            next.delete(group.key)
             return next
         })
     }, [selectedSessionId, displayGroups])
@@ -531,7 +505,7 @@ export function SessionList(props: {
             <div className="flex flex-col">
                 {displayGroups.map((group) => {
                     const isCollapsed = isGroupCollapsed(group)
-                    const groupMachineLabel = resolveMachineLabel(group.machineId)
+                    const machineLabel = resolveMachineLabel(group.machineId)
                     return (
                         <div key={group.key} className="mt-2 first:mt-0">
                             <GroupHeader
@@ -542,7 +516,7 @@ export function SessionList(props: {
                             />
                             {!isCollapsed ? (
                                 <div className="flex flex-col divide-y divide-[var(--app-divider)] border-b border-[var(--app-divider)] border-l border-l-[var(--app-divider)]">
-                                    {group.sessions.map((s, index) => (
+                                    {group.sessions.map((s) => (
                                         <SessionItem
                                             key={s.id}
                                             session={s}
diff --git a/web/src/index.css b/web/src/index.css
index 6caaa43b6..5bcc9bd2f 100644
--- a/web/src/index.css
+++ b/web/src/index.css
@@ -11,7 +11,6 @@
     --app-banner-bg: var(--tg-theme-button-color, #111827);
     --app-banner-text: var(--tg-theme-button-text-color, #ffffff);
     --app-secondary-bg: var(--tg-theme-secondary-bg-color, #f3f4f6);
-    --app-selected-bg: rgba(59, 130, 246, 0.08);
 
     /* Theme-aware colors (light mode defaults) */
     --app-border: rgba(0, 0, 0, 0.1);
@@ -81,7 +80,6 @@
     --app-banner-bg: var(--tg-theme-button-color, #3A3A3C);
     --app-banner-text: var(--tg-theme-button-text-color, #ffffff);
     --app-secondary-bg: var(--tg-theme-secondary-bg-color, #2C2C2E);
-    --app-selected-bg: rgba(59, 130, 246, 0.08);
 
     --app-border: rgba(255, 255, 255, 0.1);
     --app-divider: rgba(255, 255, 255, 0.08);
@@ -232,11 +230,7 @@ body {
 }
 
 html[data-theme="dark"] .shiki,
-html[data-theme="dark"] .shiki span,
-html[data-theme="catpuccin"] .shiki,
-html[data-theme="catpuccin"] .shiki span,
-html[data-theme="gaius-dark"] .shiki,
-html[data-theme="gaius-dark"] .shiki span {
+html[data-theme="dark"] .shiki span {
     color: var(--shiki-dark) !important;
     font-style: var(--shiki-dark-font-style) !important;
     font-weight: var(--shiki-dark-font-weight) !important;
diff --git a/web/src/router.tsx b/web/src/router.tsx
index 6bf0f3293..b78f50ef9 100644
--- a/web/src/router.tsx
+++ b/web/src/router.tsx
@@ -12,9 +12,8 @@ import {
     useParams,
 } from '@tanstack/react-router'
 import { App } from '@/App'
-import { SortIcon, PinIcon } from '@/components/icons/SortIcons'
 import { SessionChat } from '@/components/SessionChat'
-import { SessionList, groupSessionsByDirectory } from '@/components/SessionList'
+import { SessionList } from '@/components/SessionList'
 import { NewSession } from '@/components/NewSession'
 import { LoadingState } from '@/components/LoadingState'
 import { useAppContext } from '@/lib/app-context'
@@ -27,7 +26,6 @@ import { useSessions } from '@/hooks/queries/useSessions'
 import { useSlashCommands } from '@/hooks/queries/useSlashCommands'
 import { useSkills } from '@/hooks/queries/useSkills'
 import { useSendMessage } from '@/hooks/mutations/useSendMessage'
-import { useSortToggle } from '@/hooks/useSortToggle'
 import { queryKeys } from '@/lib/query-keys'
 import { useToast } from '@/lib/toast-context'
 import { useTranslation } from '@/lib/use-translation'
@@ -151,18 +149,6 @@ function SessionsPage() {
                             >
                                 <SettingsIcon className="h-5 w-5" />
                             </button>
-                            <button
-                                type="button"
-                                onClick={toggleSortMode}
-                                className="p-1.5 rounded-full text-[var(--app-hint)] hover:text-[var(--app-link)] transition-colors disabled:opacity-50 disabled:cursor-not-allowed"
-                                title={t(sortMode === 'auto' ? 'sessions.sort.auto' : 'sessions.sort.manual')}
-                                aria-pressed={sortMode === 'manual'}
-                                disabled={isSortPreferencePending}
-                            >
-                                {sortMode === 'auto'
-                                    ? <SortIcon className="h-4 w-4" />
-                                    : <PinIcon className="h-4 w-4" />}
-                            </button>
                             <button
                                 type="button"
                                 onClick={() => navigate({ to: '/sessions/new' })}
@@ -386,7 +372,7 @@ function NewSessionPage() {
     }, [navigate, queryClient])
 
     return (
-        <div className="flex-1 overflow-y-auto">
+        <div className="flex h-full min-h-0 flex-col">
             <div className="flex items-center gap-2 border-b border-[var(--app-border)] bg-[var(--app-bg)] p-3 pt-[calc(0.75rem+env(safe-area-inset-top))]">
                 {!isTelegramApp() && (
                     <button
@@ -407,13 +393,14 @@ function NewSessionPage() {
                     </div>
                 ) : null}
 
-            <NewSession
-                api={api}
-                machines={machines}
-                isLoading={machinesLoading}
-                onCancel={handleCancel}
-                onSuccess={handleSuccess}
-            />
+                <NewSession
+                    api={api}
+                    machines={machines}
+                    isLoading={machinesLoading}
+                    onCancel={handleCancel}
+                    onSuccess={handleSuccess}
+                />
+            </div>
         </div>
     )
 }
diff --git a/web/src/types/api.ts b/web/src/types/api.ts
index 738991ceb..29dc5e53e 100644
--- a/web/src/types/api.ts
+++ b/web/src/types/api.ts
@@ -218,6 +218,19 @@ export type PushVapidPublicKeyResponse = {
     publicKey: string
 }
 
+export type SessionSortPreferenceResponse = {
+    preference: SessionSortPreference
+}
+
+export type SetSessionSortPreferencePayload = {
+    sortMode: SessionSortMode
+    manualOrder: SessionManualOrder
+    expectedVersion?: number
+}
+
+export type SetSessionSortPreferenceResult =
+    | { status: 'success'; preference: SessionSortPreference }
+    | { status: 'version-mismatch'; preference: SessionSortPreference }
 
 export type VisibilityPayload = {
     subscriptionId: string

From 156c907e0ed85665bb19592fee53a581b96dece4 Mon Sep 17 00:00:00 2001
From: gaius-codius <206332531+gaius-codius@users.noreply.github.com>
Date: Sun, 19 Apr 2026 12:35:59 +0000
Subject: [PATCH 27/27] fix: address PR #4 review findings

- normalize flavor in supportsModelChange and add coverage
- tighten sessionAliveSchema bounds (sid, time, model, effort)
- replace inline ModelMode import with named type import
- add useLongPress unit tests (pointer gating, threshold, keyboard)
- add positive assertions alongside SessionHeader negative checks
- decouple e2e login wait from English copy
- document session-metadata e2e spec and shared env knobs
- note session-alive payload validation in hub README
---
 hub/README.md                                 |   2 +-
 .../socket/handlers/cli/sessionHandlers.ts    |  12 +-
 web/README.md                                 |   7 +-
 web/e2e/session-metadata.ui.e2e.spec.ts       |   3 +-
 web/src/components/SessionHeader.test.tsx     |   4 +
 web/src/hooks/useLongPress.test.ts            | 204 ++++++++++++++++++
 web/src/lib/agentFlavorUtils.test.ts          |  24 ++-
 web/src/lib/agentFlavorUtils.ts               |   3 +-
 8 files changed, 247 insertions(+), 12 deletions(-)
 create mode 100644 web/src/hooks/useLongPress.test.ts

diff --git a/hub/README.md b/hub/README.md
index faed72973..8bef705f9 100644
--- a/hub/README.md
+++ b/hub/README.md
@@ -151,7 +151,7 @@ Namespace: `/cli`
 - `message` - Send message to session.
 - `update-metadata` - Update session metadata.
 - `update-state` - Update agent state.
-- `session-alive` - Keep session active.
+- `session-alive` - Keep session active. Payloads are validated against the shared protocol schemas; unknown `permissionMode`, `modelMode`, or `collaborationMode` values and out-of-range `sid`/`time` values cause the heartbeat to be dropped. Forked or older CLIs emitting non-standard values must upgrade.
 - `session-end` - Mark session ended.
 - `machine-alive` - Keep machine online.
 - `rpc-register` - Register RPC handler.
diff --git a/hub/src/socket/handlers/cli/sessionHandlers.ts b/hub/src/socket/handlers/cli/sessionHandlers.ts
index 50c43ed7b..845ef7a6c 100644
--- a/hub/src/socket/handlers/cli/sessionHandlers.ts
+++ b/hub/src/socket/handlers/cli/sessionHandlers.ts
@@ -2,7 +2,7 @@ import type { ClientToServerEvents } from '@hapi/protocol'
 import { CodexCollaborationModeSchema, ModelModeSchema, PermissionModeSchema } from '@hapi/protocol/schemas'
 import { z } from 'zod'
 import { randomUUID } from 'node:crypto'
-import type { CodexCollaborationMode, PermissionMode } from '@hapi/protocol/types'
+import type { CodexCollaborationMode, ModelMode, PermissionMode } from '@hapi/protocol/types'
 import type { Store, StoredSession } from '../../../store'
 import type { SyncEvent } from '../../../sync/syncEngine'
 import { extractTodoWriteTodosFromMessageContent } from '../../../sync/todos'
@@ -19,7 +19,7 @@ type SessionAlivePayload = {
     model?: string | null
     effort?: string | null
     collaborationMode?: CodexCollaborationMode
-    modelMode?: import('@hapi/protocol/types').ModelMode
+    modelMode?: ModelMode
 }
 
 type SessionEndPayload = {
@@ -53,13 +53,13 @@ const updateStateSchema = z.object({
 })
 
 const sessionAliveSchema = z.object({
-    sid: z.string(),
-    time: z.number(),
+    sid: z.string().min(1).max(128),
+    time: z.number().finite().nonnegative(),
     thinking: z.boolean().optional(),
     mode: z.enum(['local', 'remote']).optional(),
     permissionMode: PermissionModeSchema.optional(),
-    model: z.string().nullable().optional(),
-    effort: z.string().nullable().optional(),
+    model: z.string().max(256).nullable().optional(),
+    effort: z.string().max(64).nullable().optional(),
     collaborationMode: CodexCollaborationModeSchema.optional(),
     modelMode: ModelModeSchema.optional()
 })
diff --git a/web/README.md b/web/README.md
index efca3a36a..037dcf3c9 100644
--- a/web/README.md
+++ b/web/README.md
@@ -142,9 +142,12 @@ The built assets land in `web/dist` and are served by hapi-hub. The single execu
 
 ## E2E (Playwright)
 
-Session-sort backend persistence has Playwright coverage in:
+Playwright covers:
 
-- `web/e2e/session-sort.backend.e2e.spec.ts`
+- `web/e2e/session-sort.backend.e2e.spec.ts` — session-sort backend persistence.
+- `web/e2e/session-metadata.ui.e2e.spec.ts` — session list and header metadata chip rendering.
+
+Shared env knobs: `HAPI_E2E_BASE_URL` (default `http://127.0.0.1:3906`), `HAPI_E2E_CLI_TOKEN` (default `pw-test-token`), and `HAPI_E2E_RUN_ID` (defaults to a random suffix) namespace test sessions across runs.
 
 Install browser once:
 
diff --git a/web/e2e/session-metadata.ui.e2e.spec.ts b/web/e2e/session-metadata.ui.e2e.spec.ts
index 887c48965..9df48c4f5 100644
--- a/web/e2e/session-metadata.ui.e2e.spec.ts
+++ b/web/e2e/session-metadata.ui.e2e.spec.ts
@@ -12,7 +12,8 @@ async function login(page: Page, accessToken: string): Promise<void> {
     await page.goto(BASE_URL, { waitUntil: 'networkidle' })
     await page.getByPlaceholder('Access token').fill(accessToken)
     await page.getByRole('button', { name: 'Sign In' }).click()
-    await expect(page.getByText(/sessions in .* projects/i)).toBeVisible({ timeout: 15_000 })
+    await expect(page.getByPlaceholder('Access token')).toHaveCount(0, { timeout: 15_000 })
+    await expect(page.locator('.session-list-item').first()).toBeVisible({ timeout: 15_000 })
 }
 
 async function createCliSession(
diff --git a/web/src/components/SessionHeader.test.tsx b/web/src/components/SessionHeader.test.tsx
index 0fdc7da9e..9cab6f28d 100644
--- a/web/src/components/SessionHeader.test.tsx
+++ b/web/src/components/SessionHeader.test.tsx
@@ -93,11 +93,15 @@ describe('SessionHeader', () => {
     it('hides effort when absent', () => {
         const markup = renderHeader({ effort: null })
         expect(markup).not.toContain('Very High')
+        expect(markup).toContain('Named Session')
+        expect(markup).toContain('gpt-5.4')
     })
 
     it('hides permission mode when default', () => {
         const markup = renderHeader({ permissionMode: 'default' })
         expect(markup).not.toContain('Yolo')
+        expect(markup).toContain('Named Session')
+        expect(markup).toContain('codex')
     })
 
     it('hides worktree when absent', () => {
diff --git a/web/src/hooks/useLongPress.test.ts b/web/src/hooks/useLongPress.test.ts
new file mode 100644
index 000000000..1c0a3146f
--- /dev/null
+++ b/web/src/hooks/useLongPress.test.ts
@@ -0,0 +1,204 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { act, renderHook } from '@testing-library/react'
+import type React from 'react'
+import { useLongPress } from './useLongPress'
+
+function pointerEvent(init: Partial<{
+    isPrimary: boolean
+    pointerType: 'mouse' | 'touch' | 'pen'
+    button: number
+    clientX: number
+    clientY: number
+}> = {}): React.PointerEvent {
+    return {
+        isPrimary: init.isPrimary ?? true,
+        pointerType: init.pointerType ?? 'touch',
+        button: init.button ?? 0,
+        clientX: init.clientX ?? 0,
+        clientY: init.clientY ?? 0
+    } as unknown as React.PointerEvent
+}
+
+describe('useLongPress', () => {
+    beforeEach(() => {
+        vi.useFakeTimers()
+    })
+
+    afterEach(() => {
+        vi.useRealTimers()
+    })
+
+    it('fires onLongPress after the threshold elapses', () => {
+        const onLongPress = vi.fn()
+        const onClick = vi.fn()
+        const { result } = renderHook(() =>
+            useLongPress({ onLongPress, onClick, threshold: 500 })
+        )
+
+        act(() => {
+            result.current.onPointerDown(pointerEvent({ clientX: 10, clientY: 20 }))
+        })
+        act(() => {
+            vi.advanceTimersByTime(500)
+        })
+
+        expect(onLongPress).toHaveBeenCalledWith({ x: 10, y: 20 })
+        expect(onClick).not.toHaveBeenCalled()
+    })
+
+    it('fires onClick on pointer up before the threshold', () => {
+        const onLongPress = vi.fn()
+        const onClick = vi.fn()
+        const { result } = renderHook(() =>
+            useLongPress({ onLongPress, onClick, threshold: 500 })
+        )
+
+        act(() => {
+            result.current.onPointerDown(pointerEvent())
+            result.current.onPointerUp(pointerEvent())
+        })
+
+        expect(onClick).toHaveBeenCalledTimes(1)
+        expect(onLongPress).not.toHaveBeenCalled()
+    })
+
+    it('cancels the timer and suppresses click when movement exceeds the threshold', () => {
+        const onLongPress = vi.fn()
+        const onClick = vi.fn()
+        const { result } = renderHook(() =>
+            useLongPress({ onLongPress, onClick, threshold: 500 })
+        )
+
+        act(() => {
+            result.current.onPointerDown(pointerEvent({ clientX: 0, clientY: 0 }))
+            result.current.onPointerMove(pointerEvent({ clientX: 20, clientY: 0 }))
+        })
+        act(() => {
+            vi.advanceTimersByTime(500)
+        })
+        act(() => {
+            result.current.onPointerUp(pointerEvent({ clientX: 20, clientY: 0 }))
+        })
+
+        expect(onLongPress).not.toHaveBeenCalled()
+        expect(onClick).not.toHaveBeenCalled()
+    })
+
+    it('ignores sub-threshold movement', () => {
+        const onLongPress = vi.fn()
+        const onClick = vi.fn()
+        const { result } = renderHook(() =>
+            useLongPress({ onLongPress, onClick, threshold: 500 })
+        )
+
+        act(() => {
+            result.current.onPointerDown(pointerEvent({ clientX: 0, clientY: 0 }))
+            result.current.onPointerMove(pointerEvent({ clientX: 3, clientY: 2 }))
+        })
+        act(() => {
+            vi.advanceTimersByTime(500)
+        })
+
+        expect(onLongPress).toHaveBeenCalledTimes(1)
+    })
+
+    it('ignores non-primary pointers and non-left mouse buttons', () => {
+        const onLongPress = vi.fn()
+        const { result } = renderHook(() =>
+            useLongPress({ onLongPress, threshold: 500 })
+        )
+
+        act(() => {
+            result.current.onPointerDown(pointerEvent({ isPrimary: false }))
+            result.current.onPointerDown(pointerEvent({ pointerType: 'mouse', button: 2 }))
+        })
+        act(() => {
+            vi.advanceTimersByTime(500)
+        })
+
+        expect(onLongPress).not.toHaveBeenCalled()
+    })
+
+    it('does not start the long-press timer when disabled', () => {
+        const onLongPress = vi.fn()
+        const { result } = renderHook(() =>
+            useLongPress({ onLongPress, threshold: 500, disabled: true })
+        )
+
+        act(() => {
+            result.current.onPointerDown(pointerEvent())
+        })
+        act(() => {
+            vi.advanceTimersByTime(1_000)
+        })
+
+        expect(onLongPress).not.toHaveBeenCalled()
+    })
+
+    it('ignores keyboard activation when disabled', () => {
+        const onClick = vi.fn()
+        const { result } = renderHook(() =>
+            useLongPress({ onLongPress: vi.fn(), onClick, disabled: true })
+        )
+
+        const preventDefault = vi.fn()
+        const enter = { key: 'Enter', preventDefault } as unknown as React.KeyboardEvent
+
+        act(() => {
+            result.current.onKeyDown(enter)
+        })
+
+        expect(onClick).not.toHaveBeenCalled()
+        expect(preventDefault).not.toHaveBeenCalled()
+    })
+
+    it('cancels on pointer cancel and pointer leave', () => {
+        const onLongPress = vi.fn()
+        const onClick = vi.fn()
+        const { result } = renderHook(() =>
+            useLongPress({ onLongPress, onClick, threshold: 500 })
+        )
+
+        act(() => {
+            result.current.onPointerDown(pointerEvent())
+            result.current.onPointerCancel(pointerEvent())
+        })
+        act(() => {
+            vi.advanceTimersByTime(500)
+        })
+
+        expect(onLongPress).not.toHaveBeenCalled()
+        expect(onClick).not.toHaveBeenCalled()
+
+        act(() => {
+            result.current.onPointerDown(pointerEvent())
+            result.current.onPointerLeave(pointerEvent())
+        })
+        act(() => {
+            vi.advanceTimersByTime(500)
+        })
+
+        expect(onLongPress).not.toHaveBeenCalled()
+        expect(onClick).not.toHaveBeenCalled()
+    })
+
+    it('triggers onClick on Enter and Space keys', () => {
+        const onLongPress = vi.fn()
+        const onClick = vi.fn()
+        const { result } = renderHook(() =>
+            useLongPress({ onLongPress, onClick })
+        )
+
+        const preventDefault = vi.fn()
+        const enter = { key: 'Enter', preventDefault } as unknown as React.KeyboardEvent
+        const space = { key: ' ', preventDefault } as unknown as React.KeyboardEvent
+
+        act(() => {
+            result.current.onKeyDown(enter)
+            result.current.onKeyDown(space)
+        })
+
+        expect(onClick).toHaveBeenCalledTimes(2)
+        expect(preventDefault).toHaveBeenCalledTimes(2)
+    })
+})
diff --git a/web/src/lib/agentFlavorUtils.test.ts b/web/src/lib/agentFlavorUtils.test.ts
index 689d6612d..cdc6cbbc9 100644
--- a/web/src/lib/agentFlavorUtils.test.ts
+++ b/web/src/lib/agentFlavorUtils.test.ts
@@ -2,7 +2,8 @@ import { describe, expect, it } from 'vitest'
 import {
     formatEffortLabel,
     getFlavorTextClass,
-    META_DOT_SEPARATOR_CLASS
+    META_DOT_SEPARATOR_CLASS,
+    supportsModelChange
 } from './agentFlavorUtils'
 
 describe('getFlavorTextClass', () => {
@@ -48,3 +49,24 @@ describe('META_DOT_SEPARATOR_CLASS', () => {
         expect(META_DOT_SEPARATOR_CLASS).toBe('text-[var(--app-hint)] opacity-40')
     })
 })
+
+describe('supportsModelChange', () => {
+    it.each(['claude', 'gemini'])('returns true for %s', (flavor) => {
+        expect(supportsModelChange(flavor)).toBe(true)
+    })
+
+    it.each(['codex', 'cursor', 'opencode', 'mystery'])('returns false for %s', (flavor) => {
+        expect(supportsModelChange(flavor)).toBe(false)
+    })
+
+    it('returns false for nullish values', () => {
+        expect(supportsModelChange(null)).toBe(false)
+        expect(supportsModelChange(undefined)).toBe(false)
+        expect(supportsModelChange('')).toBe(false)
+    })
+
+    it('normalizes whitespace and casing', () => {
+        expect(supportsModelChange('  Claude  ')).toBe(true)
+        expect(supportsModelChange('GEMINI')).toBe(true)
+    })
+})
diff --git a/web/src/lib/agentFlavorUtils.ts b/web/src/lib/agentFlavorUtils.ts
index b2e463e50..52cfa640c 100644
--- a/web/src/lib/agentFlavorUtils.ts
+++ b/web/src/lib/agentFlavorUtils.ts
@@ -52,5 +52,6 @@ export function formatEffortLabel(effort?: string | null): string | null {
 }
 
 export function supportsModelChange(flavor?: string | null): boolean {
-    return flavor === 'claude' || flavor === 'gemini'
+    const normalized = normalizeFlavor(flavor)
+    return normalized === 'claude' || normalized === 'gemini'
 }