@kabmo-labs/kabmo 0.7.0 → 0.9.0

package/src/client/components/layout/desktop-layout/WorkspacePanels.tsx

@@ -13,18 +13,13 @@ import { ResizeHandle } from '@/client/components/layout/desktop-layout/ResizeHa
 import { useAvailableWidth } from '@/client/hooks/workspace/available-width';
 import { useSessionStateContext } from '@/client/hooks/workspace/session-state/context';
 import {
-  DEFAULT_EDITOR_FRACTIONS,
-  DEFAULT_EDITOR_WIDTHS,
   HANDLE_WIDTH,
   MIN_EDITOR_PANEL_WIDTH,
   fillerMinWidth,
-  pairMaxSize,
-  panelFraction,
-  resolvePanelWidth,
   type EditorWidthMode,
   type PanelWidths,
 } from '@/shared/lib/workspace/panel-widths';
-import { DEFAULT_RIGHT_PANEL_FRACTION } from '@/shared/lib/workspace/right-panels';
+import { resolveWorkspacePanelWidths } from '@/shared/lib/workspace/workspace-panel-widths';
 
 const Editor = lazy(() => import('@/client/components/workspace/editor/index').then((m) => ({ default: m.Editor })));
 
@@ -43,6 +38,13 @@ function PanelSuspense({ children }: { children: ReactNode }) {
 interface WorkspacePanelsProps {
   appSettings?: Record<string, any>;
   showEditor: boolean;
+  /**
+   * The chat column is collapsed: the editor's compact/full view took its
+   * width. The chat STAYS MOUNTED (it owns the live stream and the composer)
+   * but is sized to nothing and marked inert, so a run in progress is not
+   * thrown away by widening a document.
+   */
+  chatHidden?: boolean;
   editorPanelRef: RefObject<PanelImperativeHandle | null>;
   showRightPanel: boolean;
   /** A built-in view id or a plugin panel key (`plugin:<id>/<panel>`). */
@@ -78,6 +80,7 @@ export function WorkspacePanels(props: WorkspacePanelsProps) {
   const {
     appSettings,
     showEditor,
+    chatHidden = false,
     editorPanelRef,
     showRightPanel,
     activeRightPanel,
@@ -138,75 +141,27 @@ export function WorkspacePanels(props: WorkspacePanelsProps) {
   // one, which is why a Kabmo without one looks exactly as it did.
   const editorPlugins = usePanelSlotPlugins();
 
-  // Separators present in this group, which also consume width.
-  const handleCount = (showEditor ? 1 : 0) + (showRightPanel ? 1 : 0);
-
-  // The active view's own floor, resolved once here rather than at each use, so
-  // the right panel's floor cannot be computed from different values. A view
-  // that is switched off (or a plugin that has not loaded) has no entry, and the
-  // right panel falls back to the editor's own floor — it renders the notice,
-  // not a view.
-  const rightPanelMin = activePanel?.minWidth ?? MIN_EDITOR_PANEL_WIDTH;
-
-  // The editor and the right panel are a COUPLED pair (see `panel-widths.ts`):
-  // they share `PAIR_MAX_TOTAL_FRACTION` and each is capped by `PAIR_MAX_FRACTION`.
-  // The right panel is resolved first, so it reserves the editor's WANTED share
-  // (the editor has no result yet); the editor then reserves the right panel's
-  // ACTUAL width. That asymmetry is deliberate: an editor asking for more than
-  // its default makes the right panel give way first, and the pair still sums
-  // to the total.
-  const editorFraction = panelFraction(panelWidths[editorWidthMode], DEFAULT_EDITOR_FRACTIONS[editorWidthMode], available);
-  const editorReservePx = available != null && available > 0 ? Math.round(editorFraction * available) : 0;
-
-  // Resolve the RIGHT panel first, then the editor against the width it
-  // actually got. The px order is the other half of the contract: each panel's
-  // group budget is `available − chat floor − the sibling's reserved width −
-  // handles`, so reserving only a sibling's FLOOR (the previous shape) let the
-  // two declared widths sum past the group, and flexbox then shrank BOTH —
-  // measured at 1440 with both open: the editor asked for 507 and rendered 477,
-  // the right panel asked for 245 and rendered 230. The right panel is resolved
-  // first because it is the smaller, view-specific slot: it keeps its own width
-  // and the editor absorbs the remainder.
-  const rightWidth = resolvePanelWidth({
-    stored: panelWidths.right?.[activeRightPanel],
-    defaultFraction: activePanel?.defaultFraction ?? DEFAULT_RIGHT_PANEL_FRACTION,
-    defaultPx: activePanel?.defaultWidth ?? MIN_EDITOR_PANEL_WIDTH,
-    available,
-    min: rightPanelMin,
-    // The pair cap: the right panel may not exceed `total − the editor's wanted share`.
-    pairReservePx: showEditor ? editorReservePx : 0,
-    // The editor renders before the right panel and has not been resolved yet,
-    // so only its floor can be reserved here.
-    siblingWidth: showEditor ? MIN_EDITOR_PANEL_WIDTH : 0,
-    handleCount,
-  });
-
-  const editorWidth = resolvePanelWidth({
-    stored: panelWidths[editorWidthMode],
-    defaultFraction: DEFAULT_EDITOR_FRACTIONS[editorWidthMode],
-    defaultPx: DEFAULT_EDITOR_WIDTHS[editorWidthMode],
-    available,
-    min: MIN_EDITOR_PANEL_WIDTH,
-    // The pair cap: the editor may not exceed `total − the right panel's width`.
-    pairReservePx: showRightPanel ? rightWidth : 0,
-    // The right panel is resolved above; reserve the width it actually took so
-    // the editor's group budget cannot push the pair past the group.
-    siblingWidth: showRightPanel ? rightWidth : 0,
+  // The active view's own floor and defaults are read here and handed to the
+  // resolver: a view that is switched off (or a plugin that has not loaded) has
+  // no entry, and the right panel falls back to the editor's own floor — it
+  // renders the notice, not a view.
+  const {
+    editor: editorWidth,
+    right: rightWidth,
+    editorMax: editorMaxSize,
+    rightMax: rightMaxSize,
+    rightMin: rightPanelMin,
     handleCount,
-  });
-
-  /**
-   * Pair-aware maxima for a DRAG. `resolvePanelWidth` already caps the widths
-   * it hands to `defaultSize`, but a separator drag bypasses it — the resizer
-   * transfers pixels between two panels clamped only by their own `maxSize`.
-   * Without these, dragging the editor wide would push the pair past
-   * `PAIR_MAX_TOTAL_FRACTION`. Each panel's max is its own cap and the pair
-   * total minus the sibling's FLOOR (the sibling gives way down to its minimum
-   * during the drag), so the pair cannot exceed 0.7 by dragging either way.
-   * `undefined` before the group is measured (no cap yet).
-   */
-  const editorMaxSize = pairMaxSize({ available, siblingMin: rightPanelMin, siblingOpen: showRightPanel });
-  const rightMaxSize = pairMaxSize({ available, siblingMin: MIN_EDITOR_PANEL_WIDTH, siblingOpen: showEditor });
+  } = resolveWorkspacePanelWidths({
+      available,
+      panelWidths,
+      editorWidthMode,
+      activeRightPanel,
+      activePanel,
+      showEditor,
+      showRightPanel,
+      chatHidden,
+    });
 
   /**
    * Widths of the fixed panels as they are right now, keyed by slot: the
@@ -222,7 +177,11 @@ export function WorkspacePanels(props: WorkspacePanelsProps) {
     const patch: PanelWidths = {};
     const editor = editorPanelRef.current?.getSize()?.inPixels;
     const right = rightPanelRef.current?.getSize()?.inPixels;
-    if (editor != null && editor > 0) {
+    // With the chat hidden the editor's width is whatever is left over, not a
+    // choice — persisting it would overwrite the width the user set for the
+    // ordinary layout with the one this mode produced. A drag made here still
+    // moves the RIGHT panel, which is the width that was actually chosen.
+    if (!chatHidden && editor != null && editor > 0) {
       patch[editorWidthMode] = { px: Math.round(editor), ...(available ? { fraction: editor / available } : {}) };
     }
     if (right != null && right > 0) {
@@ -250,6 +209,10 @@ export function WorkspacePanels(props: WorkspacePanelsProps) {
         <Panel
           id="center-panel"
           filler
+          // Collapsed — not unmounted — in compact/full view: the chat holds the
+          // live run, the composer draft and the scroll position, and widening a
+          // document must not discard any of them.
+          collapsed={chatHidden}
           minSize={fillerMinWidth({
             available,
             reservedPx:
@@ -258,15 +221,15 @@ export function WorkspacePanels(props: WorkspacePanelsProps) {
               handleCount * HANDLE_WIDTH,
           })}
         >
-          <div className="relative w-full h-full" {...drop.dropProps}>
+          <div className="relative w-full h-full" {...drop.dropProps} {...drop.captureDropProps} inert={chatHidden}>
             <EditorDropOverlay visible={drop.isDragging} />
             <ChatTimeline className="w-full h-full" appSettings={appSettings} onSessionTitle={onSessionTitle} />
           </div>
         </Panel>
 
-        {showEditor && <ResizeHandle />}
+        {showEditor && !chatHidden && <ResizeHandle />}
         <Panel panelRef={editorPanelRef} id="editor-panel" defaultSize={editorWidth} minSize={MIN_EDITOR_PANEL_WIDTH} maxSize={editorMaxSize} collapsed={!showEditor}>
-          <div className="flex w-full h-full" {...drop.dropProps}>
+          <div className="flex w-full h-full" {...drop.dropProps} {...drop.captureDropProps}>
             <EditorDropOverlay visible={drop.isDragging} />
             <EditorPluginRail
               activeKey={activeEditorPanelKey}

package/src/client/components/layout/desktop-layout/index.tsx

@@ -3,8 +3,7 @@ import { useSearchParams } from '@/client/lib/router/search-params';
 import { Group, Panel, type PanelImperativeHandle } from '@/client/components/layout/desktop-layout/resizer';
 import { LeftColumn } from '@/client/components/layout/desktop-layout/LeftColumn';
 import { SettingsModal } from '@/client/components/settings/LazyModal';
-import type { SettingsCategoryId } from '@/shared/types';
-import { activeProjectForSession } from '@/shared/lib/workspace/active-project';
+import { activeProjectForSession, effectiveRootFor } from '@/shared/lib/workspace/active-project';
 import { useFileTabs } from '@/client/hooks/workspace/file-tabs';
 import { useSessionState } from '@/client/hooks/workspace/session-state';
 import { TopNavbar } from '@/client/components/layout/desktop-layout/TopNavbar';
@@ -18,17 +17,17 @@ import { MIN_LEFT_DOCK_PLUGIN_WIDTH } from '@/shared/lib/workspace/left-dock-wid
 import { SESSIONS_VIEW_ID } from '@/shared/lib/workspace/left-dock';
 import { useOpenPanelRequest } from '@/client/hooks/workspace/open-panel';
 import { useLeftDock, useLeftDockWidth } from '@/client/hooks/workspace/left-dock';
+import { useEditorViewLayout } from '@/client/hooks/workspace/editor-view';
 import { useLeftDockView } from '@/client/components/workspace/plugin-panel/catalog';
 import type { EditorWidthMode } from '@/shared/lib/workspace/panel-widths';
-import { useKabmoEvent } from '@/client/hooks/ui/window-event';
+import { useSettingsModal } from '@/client/hooks/ui/settings-modal';
 import { useWorkspaceKeybindings } from '@/client/hooks/workspace/keybindings';
 import { PluginBootstrap } from '@/client/lib/plugins/bootstrap';
 import { useToasts } from '@/client/hooks/ui/toasts';
 import type { EditorDropResult } from '@/client/hooks/editor/use-editor-drop';
 import { ToastStack } from '@/client/components/common/ToastStack';
 import { SessionDeleteModal } from '@/client/components/common/session-delete-modal';
-import { useSessionActions } from '@/client/hooks/workspace/session-actions';
-import { useSessionDelete } from '@/client/hooks/workspace/session-delete';
+import { useNavbarSessionActions } from '@/client/hooks/workspace/navbar-session-actions';
 
 interface DesktopLayoutProps {
   sessionId: string | null;
@@ -71,7 +70,13 @@ export function DesktopLayout({ sessionId, onSwitchToMobile, appSettings = {} }:
     if (folderIdParam) return folders.find(f => String(f.id) === String(folderIdParam)) ?? null;
     return null;
   }, [folders, sessionId, folderIdParam]);
-  const activeProjectPath = activeProject?.project_path ?? null;
+  // A worktree session runs OUTSIDE its folder's project path, so the panels
+  // follow the session's own root — the checkout it left would otherwise be what
+  // Files, Search, Git and the terminal read.
+  const activeProjectPath = useMemo(
+    () => effectiveRootFor(folders, sessionId || '') ?? activeProject?.project_path ?? null,
+    [folders, sessionId, activeProject],
+  );
   const hasActiveContext = !!activeProject;
 
   const handleOpenTab = useCallback(() => {
@@ -106,32 +111,30 @@ export function DesktopLayout({ sessionId, onSwitchToMobile, appSettings = {} }:
     [openedFiles, activeFileId],
   );
 
+  /**
+   * The editor's WIDTH mode (`compact` / `full`), entered from either toolbar.
+   *
+   * It collapses columns around the editor and is resolved here, not in the
+   * panels, because the sidebar is a sibling of the whole workspace group: a
+   * full view that left it standing would not be the width it promises.
+   *
+   * The mode is derived from `showEditor`, so closing the column returns the
+   * chat and the sidebar without writing anything — reopening it comes back to
+   * the width the user chose.
+   */
+  const editorView = useEditorViewLayout(showEditor);
+  const sidebarOpen = showLeftPanel && !editorView.sidebarHidden;
+
   // Width restoration is declarative: each panel's `defaultSize` comes from the
   // remembered width for its current slot and `Panel` adopts a change, so a
   // view switch needs no imperative push and no cached layout can go stale.
 
-  const [settingsOpen, setSettingsOpen] = useState(false);
-  const [settingsCategory, setSettingsCategory] = useState<SettingsCategoryId>('appearance');
-  const [autoOpenAddProvider, setAutoOpenAddProvider] = useState(false);
   const [refreshKey, setRefreshKey] = useState(0);
   const handleRefreshWorkspace = () => setRefreshKey(k => k + 1);
   const [sessionTitle, setSessionTitle] = useState<string | null>(null);
   const streamStatus = useAgentStreamStatus();
+  const settings = useSettingsModal();
 
-  // The navbar's title menu acts on the session on screen. Its row may live in
-  // a folder that is not expanded in the sidebar, so the session is found by id
-  // across every folder rather than by walking the visible list. No row means
-  // nothing to act on — a session the sidebar does not know (a chat running
-  // outside every registered workspace) gets no menu rather than dead items.
-  const activeSession = useMemo(() => {
-    if (!sessionId) return null;
-    for (const folder of folders) {
-      const found = (folder.sessions || []).find((s) => String(s.id) === String(sessionId));
-      if (found) return found;
-    }
-    return null;
-  }, [folders, sessionId]);
-  const sidebar = useSidebarData();
   const { toasts, pushToast, dismissToast } = useToasts();
 
   /**
@@ -143,20 +146,19 @@ export function DesktopLayout({ sessionId, onSwitchToMobile, appSettings = {} }:
     (result: EditorDropResult) => pushToast(result.message, result.ok ? 'success' : 'error'),
     [pushToast],
   );
-  const { handleArchive, handleRename, handleRenameWithAi } = useSessionActions(sidebar.refresh, pushToast);
-  const sessionDelete = useSessionDelete();
-  // A pending `new-…` chat has no transcript anywhere yet, so rename and delete
-  // are refused by the server; the menu hides them the way the sidebar does.
-  const isPendingSession = Boolean(sessionId && sessionId.startsWith('new-'));
-  const sessionActions = activeSession
-    ? {
-        isArchived: activeSession.is_archived === 1,
-        onRename: isPendingSession ? undefined : (name: string) => void handleRename(activeSession, name),
-        onRenameWithAi: isPendingSession ? undefined : () => void handleRenameWithAi(activeSession),
-        onArchive: () => handleArchive(activeSession),
-        onDelete: isPendingSession ? undefined : () => sessionDelete.requestDelete(activeSession),
-      }
-    : undefined;
+  const { menu: sessionActions, sessionDelete } = useNavbarSessionActions(folders, sessionId, pushToast);
+
+  /**
+   * Ask for the sidebar (or put it away).
+   *
+   * Full view hides the sidebar, so asking for it must leave that mode —
+   * otherwise the toggle flips a stored flag the layout is ignoring and the
+   * click does nothing. `compact` is the mode that keeps the wider editor.
+   */
+  const handleToggleLeftPanel = (show: boolean) => {
+    if (show) editorView.revealSidebar();
+    setShowLeftPanel(show);
+  };
 
   // The workspace shortcuts, from the shared keymap so the toggles' tooltips
   // name the bound chord. `⌘S` is absent: the editor owns it, and binding it
@@ -164,26 +166,13 @@ export function DesktopLayout({ sessionId, onSwitchToMobile, appSettings = {} }:
   useWorkspaceKeybindings({
     showEditor,
     editorHasContent,
-    toggleSidebar: () => setShowLeftPanel((previous) => !previous),
+    // Through the handler, not the raw flag: in full view the sidebar is hidden
+    // by the editor's WIDTH mode, so flipping `showLeftPanel` alone would change
+    // a value the layout is ignoring and the chord would do nothing.
+    toggleSidebar: () => handleToggleLeftPanel(!sidebarOpen),
     toggleEditor: () => setUserToggledEditor((previous) => !(previous ?? showEditor)),
     toggleRightPanel: () => setShowRightPanel((previous) => !previous),
-    openSettings: () => {
-      setSettingsCategory('appearance');
-      setAutoOpenAddProvider(false);
-      setSettingsOpen((previous) => !previous);
-    },
-  });
-
-  // Global event listener for settings triggers
-  useKabmoEvent('omp:open-settings', (e) => {
-    const customEvent = e as CustomEvent<{ category?: SettingsCategoryId; autoOpenAdd?: boolean }>;
-    if (customEvent.detail?.category) {
-      setSettingsCategory(customEvent.detail.category);
-    } else {
-      setSettingsCategory('appearance');
-    }
-    setAutoOpenAddProvider(!!customEvent.detail?.autoOpenAdd);
-    setSettingsOpen(true);
+    openSettings: () => (settings.isOpen ? settings.close() : settings.open()),
   });
 
   // Clicking the ACTIVE view on an open panel collapses that panel; any other
@@ -194,7 +183,6 @@ export function DesktopLayout({ sessionId, onSwitchToMobile, appSettings = {} }:
     if (!collapsing) setActiveRightPanel(panel);
   };
 
-  const handleToggleLeftPanel = (show: boolean) => setShowLeftPanel(show);
   const handleToggleRightPanel = () => setShowRightPanel(!showRightPanel);
   const handleToggleEditor = () => setUserToggledEditor(!showEditor);
 
@@ -237,7 +225,7 @@ export function DesktopLayout({ sessionId, onSwitchToMobile, appSettings = {} }:
         >
           <LeftColumn
             panelRef={leftPanelRef}
-            open={showLeftPanel}
+            open={sidebarOpen}
             railEnabled={dock.enabled}
             view={leftView}
             onSelectView={(panel) => {
@@ -245,7 +233,7 @@ export function DesktopLayout({ sessionId, onSwitchToMobile, appSettings = {} }:
               // toggle would hide the rail the user is aiming at, and the dock
               // has its own collapse control in the header.
               setActiveLeftView(panel);
-              if (!showLeftPanel) handleToggleLeftPanel(true);
+              if (!sidebarOpen) handleToggleLeftPanel(true);
             }}
             onCollapse={() => handleToggleLeftPanel(false)}
             width={sidebarWidth}
@@ -266,20 +254,21 @@ export function DesktopLayout({ sessionId, onSwitchToMobile, appSettings = {} }:
               <TopNavbar
                 sessionTitle={sessionTitle}
                 sessionId={sessionId}
-                showLeftPanel={showLeftPanel}
+                showLeftPanel={sidebarOpen}
                 showEditor={showEditor}
                 showRightPanel={showRightPanel}
                 streamStatus={streamStatus}
                 onSwitchToMobile={onSwitchToMobile}
                 onToggleEditor={handleToggleEditor}
                 onToggleRightPanel={handleToggleRightPanel}
-                onToggleLeftPanel={() => handleToggleLeftPanel(!showLeftPanel)}
+                onToggleLeftPanel={() => handleToggleLeftPanel(!sidebarOpen)}
                 sessionActions={sessionActions}
               />
 
               <WorkspacePanels
                 appSettings={appSettings}
                 showEditor={showEditor}
+                chatHidden={editorView.chatHidden}
                 editorPanelRef={editorPanelRef}
                 showRightPanel={showRightPanel}
                 activeRightPanel={activeRightPanel}
@@ -315,15 +304,12 @@ export function DesktopLayout({ sessionId, onSwitchToMobile, appSettings = {} }:
       </div>
 
       {/* Global Desktop Settings Modal */}
-      <SettingsModal 
-        isOpen={settingsOpen} 
-        onClose={() => {
-          setSettingsOpen(false);
-          setAutoOpenAddProvider(false);
-        }} 
-        initialCategory={settingsCategory}
-        autoOpenAddProvider={autoOpenAddProvider}
-        appSettings={appSettings} 
+      <SettingsModal
+        isOpen={settings.isOpen}
+        onClose={settings.close}
+        initialCategory={settings.category}
+        autoOpenAddProvider={settings.autoOpenAddProvider}
+        appSettings={appSettings}
       />
 
       {/* The navbar title menu's delete path and the rename-with-AI refusal

package/src/client/components/layout/desktop-layout/resizer/index.tsx

@@ -212,11 +212,14 @@ export function Panel(props: {
 
   const baseStyle: CSSProperties = filler
     ? {
-        flex: '1 1 0%',
+        // A collapsed filler keeps its DOM (and therefore its state: the chat
+        // owns the live stream and the composer) but takes no width, so the
+        // sibling panels' own widths are the whole row.
+        flex: collapsed ? '0 0 0%' : '1 1 0%',
         // The filler keeps its floor on the group's axis (and none across it,
         // where it is sized by the container): see the group model note above.
-        minWidth: orientation === 'horizontal' ? minPx : 0,
-        minHeight: orientation === 'horizontal' ? 0 : minPx,
+        minWidth: orientation === 'horizontal' ? (collapsed ? 0 : minPx) : 0,
+        minHeight: orientation === 'horizontal' ? 0 : collapsed ? 0 : minPx,
         overflow: 'hidden',
         position: 'relative',
       }

package/src/client/components/layout/session-sidebar/CategoryHeader.tsx

@@ -14,7 +14,9 @@
  * props; this file only decides how the two states look.
  */
 
+import { useState } from 'preact/hooks';
 import { ChevronDown, ChevronRight, MoreHorizontal, Pin, Plus } from 'lucide-preact';
+import { NewWorktreeModal } from '@/client/components/workspace/worktree-modal/index';
 import { SelectionCheckbox } from '@/client/components/common/batch-selection/SelectionCheckbox';
 import { WorkspaceOptionsMenu } from '@/client/components/common/workspace-options-menu';
 import { getProjectIcon } from '@/shared/lib/workspace/project-icon';
@@ -39,6 +41,8 @@ export interface CategoryHeaderProps {
   showMenu: boolean;
   onToggleMenu: () => void;
   onNewSession: () => void;
+  /** Start a chat in a worktree made from this folder. */
+  onNewWorktreeSession?: (folderId: number, worktreePath: string) => void;
   onOpenFolder?: () => void;
   onSelectSessions?: () => void;
   confirmDelete: boolean;
@@ -58,6 +62,7 @@ export function CategoryHeader({
   showMenu,
   onToggleMenu,
   onNewSession,
+  onNewWorktreeSession,
   onOpenFolder,
   onSelectSessions,
   confirmDelete,
@@ -67,6 +72,10 @@ export function CategoryHeader({
   onCancelDelete,
 }: CategoryHeaderProps) {
   const ProjectIcon = getProjectIcon(folder.icon);
+  // The dialog lives here rather than in the page: the row that opens it is this
+  // one, and the folder it belongs to is what the dialog needs.
+  const [worktreeDialogOpen, setWorktreeDialogOpen] = useState(false);
+  const canCreateWorktree = Boolean(onNewWorktreeSession && folder.project_path);
 
   return (
     <div className="group flex items-center justify-between h-7 text-xs font-semibold text-ink px-2 hover:bg-ink/5 rounded-md transition-colors select-none">
@@ -159,6 +168,7 @@ export function CategoryHeader({
                   isPinned={folder.isPinned}
                   onOpenFolder={onOpenFolder}
                   onSelectSessions={onSelectSessions}
+                  onNewWorktree={canCreateWorktree ? () => { onToggleMenu(); setWorktreeDialogOpen(true); } : undefined}
                   confirmDelete={confirmDelete}
                   onPin={onPin}
                   onDelete={onDelete}
@@ -170,6 +180,20 @@ export function CategoryHeader({
           </div>
         </div>
       )}
+
+      {canCreateWorktree && (
+        <NewWorktreeModal
+          isOpen={worktreeDialogOpen}
+          onClose={() => setWorktreeDialogOpen(false)}
+          root={folder.project_path ?? null}
+          folderId={folder.id}
+          folderName={folder.name}
+          onCreated={(created) => {
+            setWorktreeDialogOpen(false);
+            onNewWorktreeSession?.(folder.id, created.path);
+          }}
+        />
+      )}
     </div>
   );
 }

package/src/client/components/layout/session-sidebar/CategoryHeader.worktree.test.tsx

@@ -0,0 +1,126 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The folder header's `New worktree…` entry.
+ *
+ * This row is the ONLY entry point to the dialog on the desktop, and it is
+ * reachable through four components (SessionsView → SessionList → Category →
+ * CategoryHeader). The prop is optional at every hop, so a hop that forgets to
+ * forward it fails silently: the typechecker is satisfied, the menu renders, and
+ * the row is simply absent. Measured — that is exactly how the desktop half
+ * shipped unreachable while the phone's worked.
+ *
+ * The header is mounted directly here, which is the half that can be asserted
+ * cheaply; the assembled path is what `tests/e2e/specs/worktree.e2e.ts` covers.
+ */
+
+import { afterAll, afterEach, beforeAll, describe, expect, test } from 'bun:test';
+import { Window } from 'happy-dom';
+import { h, render } from 'preact';
+import { act } from 'preact/test-utils';
+import { CategoryHeader } from '@/client/components/layout/session-sidebar/CategoryHeader';
+import { installDomGlobals, restoreDomGlobals } from '@/test-support/pristine-globals';
+import type { WorkspaceFolderData } from '@/shared/types';
+
+const folder: WorkspaceFolderData = {
+  id: 7,
+  name: 'kabmo',
+  project_path: '/Users/dev/kabmo',
+  isExpanded: true,
+  hasMore: false,
+  totalSessions: 0,
+  sessions: [],
+};
+
+let host: HTMLElement | null = null;
+
+beforeAll(() => {
+  installDomGlobals(new Window({ url: 'http://localhost' }));
+});
+
+afterEach(() => {
+  if (host) {
+    render(null, host);
+    host.remove();
+    host = null;
+  }
+});
+
+afterAll(() => {
+  restoreDomGlobals();
+});
+
+/** Mount the header with its `⋯` menu already open. */
+function mountHeader(overrides: Partial<Parameters<typeof CategoryHeader>[0]> = {}): HTMLElement {
+  host = document.createElement('div');
+  document.body.appendChild(host);
+  render(
+    h(CategoryHeader, {
+      folder,
+      isOpen: true,
+      onToggleFolder: () => {},
+      checkbox: null,
+      batchActive: false,
+      menuRef: { current: null },
+      showMenu: true,
+      onToggleMenu: () => {},
+      onNewSession: () => {},
+      confirmDelete: false,
+      onPin: () => {},
+      onDelete: () => {},
+      onRequestDelete: () => {},
+      onCancelDelete: () => {},
+      ...overrides,
+    }),
+    host,
+  );
+  return host;
+}
+
+/** The menu's own buttons, by their words. */
+function menuRows(container: HTMLElement): string[] {
+  return [...container.querySelectorAll('button')].map((button) => (button.textContent ?? '').trim()).filter(Boolean);
+}
+
+describe('CategoryHeader worktree entry', () => {
+  test('the menu offers New worktree… when a handler is supplied', () => {
+    const container = mountHeader({ onNewWorktreeSession: () => {} });
+    expect(menuRows(container)).toContain('New worktree…');
+  });
+
+  test('no row without a handler — a folder that cannot create one does not offer it', () => {
+    const container = mountHeader();
+    expect(menuRows(container).some((row) => row.startsWith('New worktree'))).toBe(false);
+  });
+
+  test('a folder with no project path offers nothing: a worktree needs a repository', () => {
+    const container = mountHeader({
+      folder: { ...folder, project_path: null },
+      onNewWorktreeSession: () => {},
+    });
+    expect(menuRows(container).some((row) => row.startsWith('New worktree'))).toBe(false);
+  });
+
+  test('clicking it opens the dialog, closed on its own name field', async () => {
+    const container = mountHeader({ onNewWorktreeSession: () => {} });
+    const row = [...container.querySelectorAll('button')].find(
+      (button) => (button.textContent ?? '').trim() === 'New worktree…',
+    );
+    if (!row) throw new Error('no New worktree row rendered');
+
+    await act(async () => {
+      row.click();
+    });
+
+    // The dialog names the project it will branch from, and starts on a
+    // generated branch with its folder following it.
+    const text = (document.body.textContent ?? '').replace(/\s+/g, ' ');
+    expect(text).toContain('Start from');
+    expect(text).toContain('kabmo');
+    const branch = (document.body.querySelector('input') as HTMLInputElement | null)?.value ?? '';
+    expect(branch).toMatch(/^wt\/[a-z]+-[a-z]+$/);
+  });
+});

package/src/client/components/layout/session-sidebar/CategoryItem.tsx

@@ -24,6 +24,7 @@ export function Category({
   activeSessionId, 
   onSelectSession,
   onNewSessionForFolder,
+  onNewWorktreeSession,
   forceExpanded = false,
   showArchived = false,
   sessionStatus = {},
@@ -36,6 +37,7 @@ export function Category({
   activeSessionId: number | string | null;
   onSelectSession: (id: number | string) => void;
   onNewSessionForFolder: (id: number) => void;
+  onNewWorktreeSession?: (folderId: number, worktreePath: string) => void;
   forceExpanded?: boolean;
   showArchived?: boolean;
   sessionStatus?: Record<string, 'stream' | 'finish' | 'abort'>;
@@ -172,6 +174,7 @@ export function Category({
         showMenu={showMenu}
         onToggleMenu={() => setShowMenu(!showMenu)}
         onNewSession={() => onNewSessionForFolder(folder.id)}
+        onNewWorktreeSession={onNewWorktreeSession}
         onOpenFolder={onOpenFolder}
         onSelectSessions={
           onStartSessionSelection
@@ -211,6 +214,7 @@ export function Category({
                   isArchived={session.is_archived === 1}
                   status={sessionStatus[sessionKey]}
                   awaitingInput={Boolean(session.awaitingInput)}
+                  worktree={session.worktree}
                   timeAgo={relativeTimeAgo(session.updated_at ?? session.created_at)}
                   onClick={() => onSelectSession(session.id)}
                   onArchive={() => handleArchive(session)}