@kabmo-labs/kabmo 0.7.0 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kabmo-labs/kabmo",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Web console and diagnostic workbench for AI coding agents — Elysia + Preact on Bun.",
   "license": "UNLICENSED",
   "author": "Wijanarko Putra Rajeb <wijanarko.rajeb@gmail.com>",
@@ -54,6 +54,7 @@
     "test": "bun test",
     "test:e2e": "playwright test --config tests/e2e/playwright.config.ts",
     "readme:media": "bun run scripts/readme-media.ts",
+    "shell:wordmark": "bun run scripts/shell-wordmark.mjs",
     "typecheck:e2e": "tsc --noEmit -p tests/e2e",
     "publish:plugins": "bash .github/scripts/publish-plugin-packages.sh packages/kabmo-sdk packages/kabmo-ui"
   },

package/src/client/components/common/header-controls/index.tsx

@@ -6,6 +6,8 @@ import { ContextUsageButton } from '@/client/components/common/context-usage-but
 import { HeaderPanelButtons } from '@/client/components/common/header-panel-buttons';
 import { useHeaderEntries } from '@/client/components/common/header-panel-buttons/entries';
 import { HeaderMoreMenu } from '@/client/components/common/header-controls/MoreMenu';
+import { WindowControls } from '@/client/components/common/window-controls';
+import { drawsWindowControls } from '@/client/lib/desktop/titlebar';
 import { useAuthEnabled, useAuthState } from '@/client/hooks/ui/auth';
 import { useViewportAtLeast } from '@/client/hooks/ui/media-query';
 import { withChord } from '@/client/lib/ui/with-chord';
@@ -111,7 +113,17 @@ export function HeaderControls({
   const headerEntries = useHeaderEntries(layout);
 
   return (
-    <div className="flex items-center space-x-1">
+    // `titlebar-no-drag` belongs HERE, on the cluster's own root, not on each
+    // call site. `app-region` INHERITS (WebView2's own spec says so, and
+    // Chromium 152 began enforcing it), so a header that marks itself a drag
+    // region makes every descendant a drag handle unless something below it
+    // says otherwise — a control inside one is unclickable, silently. The
+    // desktop navbar wrapped this cluster in a `titlebar-no-drag` div and the
+    // PHONE's header did not, so on Windows every control in a phone-width
+    // window (reload, context, sign out, the right panel, `⋯`) swallowed its
+    // own click. Stating it on the cluster is what makes the next layout that
+    // draws it correct by construction.
+    <div className="flex items-center space-x-1 titlebar-no-drag">
       {layout === 'desktop' && <PWAInstallButton />}
       <HeaderPanelButtons layout={layout} entries={headerEntries.inline} />
       {/* The cluster's ORDER is fixed; what changes on a narrow phone is that
@@ -169,6 +181,17 @@ export function HeaderControls({
           <Smartphone size={size} />
         </button>
       )}
+      {/* The Windows and Linux shells draw no caption buttons of their own —
+          their webview is the whole window — so the PAGE owns minimise,
+          maximise and close. This lives in the shared cluster rather than in
+          the desktop navbar for a measured reason: a desktop shell window can
+          be NARROWER than the layout breakpoint (`App` switches to the mobile
+          layout below 768px, and all three shells allow a 720px window), and
+          the phone header drew no window controls at all. A user who shrank
+          the window lost close/minimise/maximise entirely, with no title bar
+          behind them to fall back on. macOS never reaches this branch: its
+          traffic lights are the system's, so `drawsWindowControls` is false. */}
+      {drawsWindowControls() && <WindowControls />}
     </div>
   );
 }

package/src/client/components/common/header-controls/shell-chrome.test.tsx

@@ -0,0 +1,272 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The shell chrome the shared cluster must carry, on BOTH layouts.
+ *
+ * Two bugs reached a user, and both are invisible in a browser:
+ *
+ * 1. **`app-region` inherits.** WebView2's own spec says the property inherits,
+ *    and Chromium 152 began enforcing it. So a header marked `app-region: drag`
+ *    turns every descendant into a drag handle — and a drag handle swallows the
+ *    click, silently. The desktop navbar wrapped this cluster in a
+ *    `titlebar-no-drag` div and the PHONE's header did not, so on Windows every
+ *    control in a phone-width window (reload, context, sign out, the right
+ *    panel, `⋯`) looked right and did nothing.
+ * 2. **The page-drawn caption buttons lived in one layout.** A desktop shell
+ *    window can be narrower than `App`'s 768px breakpoint — all three shells
+ *    allow a 720px window — so a Windows/Linux window resized down switches to
+ *    the phone layout, which drew no close/minimise/maximise at all and had no
+ *    native title bar behind them.
+ *
+ * Both are asserted on the RENDERED tree, because both were a call site's
+ * omission: a test reading the component's source would have passed while the
+ * phone stayed broken. macOS is covered too — it keeps its own traffic lights,
+ * so the page must draw no second set.
+ */
+
+import { afterAll, afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { Window } from 'happy-dom';
+import { h, render } from 'preact';
+import { act } from 'preact/test-utils';
+import { definePluginApp } from '@kabmo-labs/kabmo-sdk/app';
+import { HeaderControls } from '@/client/components/common/header-controls';
+import { SessionStateProvider } from '@/client/components/common/session-state-provider/index';
+import { registerPluginBundle, resetPluginSlots } from '@/client/lib/plugins/slots';
+import { primeAuthState } from '@/client/hooks/ui/auth';
+import { resetRealtimeClient } from '@/shared/lib/realtime/client';
+import { invalidateModelsCache } from '@/shared/lib/models/client';
+import { sessionTelemetryTopic, TOPIC_PANELS } from '@/shared/lib/realtime/protocol';
+import type { PanelRegistryPayload, SessionContextTelemetry } from '@/shared/types';
+import { startRealtimeTestServer, type RealtimeTestServer } from '@/test-support/realtime-server';
+import { installDomGlobals, pristineWebSocket, restoreDomGlobals } from '@/test-support/pristine-globals';
+import type { TopicResolver } from '@/server/lib/realtime/hub.server';
+
+const SESSION = 'session-shell-chrome';
+const nativeFetch = Bun.fetch;
+const Noop = () => null;
+
+let container: HTMLElement;
+let server: RealtimeTestServer;
+
+const PANELS: PanelRegistryPayload = {
+  panels: [{ pluginId: 'demo', name: 'Demo', version: '1.0.0', appUrl: '/api/panels/bundle/demo.js' }],
+  marketplaces: [],
+  errors: [],
+  plugins: [{ pluginId: 'demo', name: 'Demo', version: '1.0.0', isPackage: true, built: true, enabled: true, bundled: false, gitOrigin: null }],
+  catalog: [],
+  disabledPanels: [],
+  gitStatus: {},
+  autoUpdate: false,
+  syncBlocked: {},
+};
+
+function telemetry(): SessionContextTelemetry {
+  return {
+    sessionId: SESSION,
+    sessionTitle: 'Shell',
+    modelId: 'kenari/deepseek-v4-1-flash',
+    modelName: 'deepseek-v4-1-flash',
+    timestamp: 'today',
+    contextUsed: 12_000,
+    contextLimit: 100_000,
+    contextPercent: 12,
+    messagesCount: 3,
+    userCount: 1,
+    assistantCount: 2,
+    totalCost: 0.01,
+    costFormatted: '$0.01',
+    cacheHitAverage: 90,
+    lastMessage: { input: 10, output: 4, reasoning: 0, cacheRead: 2, cacheWrite: 0, cacheHitPercent: 16.6 },
+    distribution: { userTokens: 1, userPercent: 25, assistantTokens: 1, assistantPercent: 25, toolTokens: 1, toolPercent: 25, otherTokens: 1, otherPercent: 25 },
+    rawMessages: [],
+  };
+}
+
+/** The shell's two globals, which the DOM's own `window` type does not declare. */
+type Shell = {
+  __kabmoCall?: (method: string, params?: Record<string, unknown>) => Promise<unknown>;
+  __kabmoDesktop?: Record<string, unknown>;
+};
+
+
+const WINDOWS = { platform: 'windows', shellVersion: '0.1.0', overlayTitlebar: true, windowControls: true };
+const MACOS = { platform: 'macos', shellVersion: '0.1.0', overlayTitlebar: true, trafficLightInset: '5rem' };
+
+/** Install a shell identity for one case; `afterEach` removes it. */
+function withShell(identity: Record<string, unknown> | null) {
+  // The shell's globals are not in the DOM's `window` type; one cast, at the seam.
+  const shell = window as unknown as Shell;
+  shell.__kabmoCall = async () => null;
+  if (identity) shell.__kabmoDesktop = identity;
+  else delete shell.__kabmoDesktop;
+}
+
+beforeEach(async () => {
+  invalidateModelsCache();
+  const panels: TopicResolver = async () => PANELS;
+  const telemetryTopic: TopicResolver = async () => telemetry();
+  server = await startRealtimeTestServer(new Map<string, TopicResolver>([
+    [TOPIC_PANELS, panels],
+    [sessionTelemetryTopic(SESSION), telemetryTopic],
+  ]));
+  installDomGlobals(new Window({ url: `http://127.0.0.1:${server.port}` }));
+  const target = globalThis as unknown as Record<string, unknown>;
+  target.WebSocket = pristineWebSocket;
+  target.fetch = async (input: unknown) => {
+    const json = (body: unknown) => new Response(JSON.stringify(body), {
+      status: 200,
+      headers: { 'content-type': 'application/json' },
+    });
+    const url = String(input);
+    if (url.includes('/api/sessions/')) return json({ state: {} });
+    if (url.includes('/api/telemetry/context')) return json({ telemetry: telemetry() });
+    if (url.includes('/api/models')) return json({ modelList: [], connectedProviders: [] });
+    return json({});
+  };
+  resetPluginSlots();
+  registerPluginBundle('demo', {
+    default: definePluginApp((app) => app.headerPanel({ id: 'h', title: 'Demo Stats', component: Noop })),
+  });
+  primeAuthState(true, true);
+});
+
+afterEach(() => {
+  if (container) {
+    render(null, container);
+    container.remove();
+  }
+  resetPluginSlots();
+  resetRealtimeClient();
+  server?.stop();
+  (globalThis as unknown as Record<string, unknown>).fetch = nativeFetch;
+  const shell = window as unknown as Shell;
+  delete shell.__kabmoDesktop;
+  delete shell.__kabmoCall;
+});
+
+afterAll(() => {
+  restoreDomGlobals();
+});
+
+async function settle(): Promise<void> {
+  await server.waitForTopic(TOPIC_PANELS, (value) => value !== null);
+  await server.waitForTopic(sessionTelemetryTopic(SESSION), (value) => value !== null);
+  for (let i = 0; i < 10; i += 1) await act(async () => {});
+}
+
+/** Every control in the cluster, by its accessible name. */
+function controlNames(): string[] {
+  const names: string[] = [];
+  for (const element of container.querySelectorAll('button, [title]')) {
+    const label = element.getAttribute('aria-label') ?? element.getAttribute('title') ?? '';
+    names.push(label.replace(/ \([^)]*\)$/, ''));
+  }
+  return names;
+}
+
+async function mount(layout: 'desktop' | 'mobile', width: number): Promise<void> {
+  Object.defineProperty(window, 'innerWidth', { value: width, configurable: true, writable: true });
+  container = document.createElement('div');
+  document.body.appendChild(container);
+  await act(async () => {
+    render(
+      h(SessionStateProvider, {
+        sessionId: SESSION,
+        children: h(HeaderControls, {
+          layout,
+          sessionId: SESSION,
+          showRightPanel: layout === 'desktop',
+          onToggleRightPanel: () => {},
+        }),
+      }),
+      container,
+    );
+  });
+  await settle();
+}
+
+function unmount(): void {
+  render(null, container);
+  container.remove();
+  container = undefined as unknown as HTMLElement;
+}
+
+/** A desktop shell window is allowed to be 720px — below the 768px breakpoint. */
+const SHELL_MIN_WIDTH = 720;
+const PHONE_WIDTH = 390;
+
+describe('shell chrome', () => {
+  test('the cluster marks itself no-drag on both layouts', async () => {
+    for (const [layout, width] of [['desktop', 1024], ['mobile', PHONE_WIDTH]] as const) {
+      await mount(layout, width);
+      const root = container.firstElementChild as HTMLElement;
+      expect(root.className).toContain('titlebar-no-drag');
+      unmount();
+    }
+  });
+
+  test('a Windows shell draws the caption buttons on both layouts', async () => {
+    withShell(WINDOWS);
+    for (const [layout, width] of [['desktop', 1024], ['mobile', PHONE_WIDTH]] as const) {
+      await mount(layout, width);
+      const names = controlNames();
+      expect(names).toContain('Minimize');
+      expect(names).toContain('Maximize');
+      expect(names).toContain('Close');
+      unmount();
+    }
+  });
+
+  /**
+   * The case the bug was actually reported for: a Windows window at the shell's
+   * own minimum width, which the app renders with the PHONE layout.
+   */
+  test('a Windows window at its minimum width still has its caption buttons', async () => {
+    withShell(WINDOWS);
+    await mount('mobile', SHELL_MIN_WIDTH);
+    const names = controlNames();
+    expect(names).toContain('Close');
+    expect(names).toContain('Minimize');
+  });
+
+  test('a macOS shell draws no caption buttons of its own', async () => {
+    withShell(MACOS);
+    await mount('desktop', 1024);
+    const names = controlNames();
+    expect(names).not.toContain('Minimize');
+    expect(names).not.toContain('Close');
+  });
+
+  /** A browser tab has no shell, so a caption button would be a dead control. */
+  test('a browser draws no caption buttons', async () => {
+    withShell(null);
+    await mount('desktop', 1024);
+    expect(controlNames()).not.toContain('Close');
+  });
+
+  /**
+   * The caption buttons issue the shell's own verbs, from the phone layout too.
+   *
+   * A button that reaches the DOM but never calls the bridge is the same dead
+   * control in a different disguise.
+   */
+  test('a caption click reaches the bridge from the phone layout', async () => {
+    const calls: string[] = [];
+    withShell(WINDOWS);
+    ;(window as unknown as Shell).__kabmoCall = async (method) => {
+      calls.push(method);
+      return null;
+    };
+    await mount('mobile', PHONE_WIDTH);
+    const close = Array.from(container.querySelectorAll('button'))
+      .find((button) => button.getAttribute('aria-label') === 'Close') as HTMLElement;
+    expect(close).toBeTruthy();
+    await act(async () => {
+      close.click();
+    });
+    expect(calls).toContain('window_close');
+  });
+});

package/src/client/components/common/workspace-options-menu/index.tsx

@@ -13,7 +13,7 @@
  * source of truth.
  */
 
-import { FolderOpen, ListChecks, Pin, PinOff, Trash2 } from 'lucide-preact';
+import { FolderOpen, GitBranch, ListChecks, Pin, PinOff, Trash2 } from 'lucide-preact';
 
 interface WorkspaceOptionsMenuProps {
   variant: 'desktop' | 'mobile';
@@ -23,6 +23,12 @@ interface WorkspaceOptionsMenuProps {
   onOpenFolder?: () => void;
   /** Enter the session batch-selection mode scoped to this workspace. */
   onSelectSessions?: () => void;
+  /**
+   * Open the New worktree dialog for this workspace. Offered only for a folder
+   * bound to a repository: a worktree needs one, and a row that opens a dialog
+   * which can only refuse is a row that teaches the user nothing.
+   */
+  onNewWorktree?: () => void;
   confirmDelete: boolean;
   onPin: () => void;
   onDelete: () => void;
@@ -35,6 +41,7 @@ export function WorkspaceOptionsMenu({
   isPinned = false,
   onOpenFolder,
   onSelectSessions,
+  onNewWorktree,
   confirmDelete,
   onPin,
   onDelete,
@@ -71,6 +78,12 @@ export function WorkspaceOptionsMenu({
             <span>Select sessions</span>
           </button>
         )}
+        {onNewWorktree && (
+          <button type="button" onClick={onNewWorktree} className="w-full text-left px-3 py-2 hover:bg-ink/5 text-ink/80 flex items-center space-x-2">
+            <GitBranch size={13} />
+            <span>New worktree…</span>
+          </button>
+        )}
         <button type="button" onClick={onRequestDelete} className="w-full text-left px-3 py-2 hover:bg-error/10 text-error flex items-center space-x-2">
           <Trash2 size={13} />
           <span>Delete Workspace</span>
@@ -105,6 +118,11 @@ export function WorkspaceOptionsMenu({
           <ListChecks size={12} /><span>Select sessions</span>
         </button>
       )}
+      {onNewWorktree && (
+        <button type="button" onClick={onNewWorktree} className="w-full text-left px-3 py-1.5 hover:bg-ink/5 cursor-pointer flex items-center space-x-2 text-ink/80">
+          <GitBranch size={12} /><span>New worktree…</span>
+        </button>
+      )}
       <button type="button" onClick={onRequestDelete} className="w-full text-left px-3 py-1.5 hover:bg-ink/5 cursor-pointer flex items-center space-x-2 text-error">
         <Trash2 size={12} /><span>Delete Workspace</span>
       </button>

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

@@ -12,8 +12,7 @@ import { titlebarPaddingLeft, titlebarPaddingRight } from '@/shared/lib/ui/title
 import { ServerSwitcher } from '@/client/components/common/server-switcher';
 import { useDesktopServers } from '@/client/hooks/desktop/servers';
 import { isDesktopShell } from '@/client/lib/desktop/bridge';
-import { dragRegionProps, drawsWindowControls, titlebarInsetLeft } from '@/client/lib/desktop/titlebar';
-import { WindowControls } from '@/client/components/common/window-controls';
+import { dragRegionProps, titlebarInsetLeft } from '@/client/lib/desktop/titlebar';
 import { useOnClickOutside } from '@/client/hooks/ui/on-click-outside';
 
 interface TopNavbarProps {
@@ -203,10 +202,10 @@ export function TopNavbar({
           onToggleEditor={onToggleEditor}
           onSwitchToMobile={onSwitchToMobile}
         />
-        {/* The Windows shell is borderless and its webview is an HWND, so the
-            system's caption buttons cannot be drawn over it — the page owns
-            them there. Absent on macOS, whose traffic lights are the system's. */}
-        {drawsWindowControls() && <WindowControls />}
+        {/* The Windows/Linux caption buttons come from `HeaderControls` itself:
+            a desktop shell window can be narrower than the mobile breakpoint,
+            so the phone header has to draw them too — and a control that only
+            one layout renders is a control the other layout's window loses. */}
       </div>
 
       {menu.anchor && sessionActions && (

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

@@ -4,7 +4,7 @@ import { Group, Panel, type PanelImperativeHandle } from '@/client/components/la
 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';
@@ -71,7 +71,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(() => {

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)}