From d0e3e32c6fc50d46287ab2b83458eec3f3f6e831 Mon Sep 17 00:00:00 2001
From: qer <wbxl2000@outlook.com>
Date: Sun, 28 Jun 2026 00:48:31 +0800
Subject: [PATCH] backup: full worktree implementation

---
 apps/kimi-web/src/App.vue                     | 119 +++-
 apps/kimi-web/src/api/daemon/client.ts        |  54 ++
 apps/kimi-web/src/api/daemon/eventReducer.ts  |   5 +-
 apps/kimi-web/src/api/daemon/mappers.ts       |  26 +
 apps/kimi-web/src/api/daemon/wire.ts          |  15 +
 apps/kimi-web/src/api/types.ts                |  36 ++
 apps/kimi-web/src/components/Sidebar.vue      | 499 +++++------------
 .../kimi-web/src/components/WorktreeBoard.vue | 361 +++++++++++++
 .../kimi-web/src/components/WorktreeGroup.vue | 288 ++++++++++
 .../src/components/chat/OpenInMenu.vue        |   3 +
 .../components/dialogs/NewWorktreeDialog.vue  | 249 +++++++++
 .../dialogs/WorktreeCompleteDialog.vue        | 196 +++++++
 .../src/components/dialogs/WorktreeDialog.vue | 433 +++++++++++++++
 .../composables/client/useWorkspaceState.ts   |  88 ++-
 .../src/composables/useKimiWebClient.ts       | 308 ++++++++++-
 apps/kimi-web/src/i18n/locales/en/worktree.ts |  42 ++
 apps/kimi-web/src/i18n/locales/index.ts       |   4 +
 apps/kimi-web/src/i18n/locales/zh/worktree.ts |  41 ++
 apps/kimi-web/src/lib/branchColor.ts          |  22 +
 apps/kimi-web/src/lib/snapshotSync.ts         |  35 ++
 apps/kimi-web/src/lib/worktreeGroups.ts       |  56 ++
 apps/kimi-web/src/types.ts                    |  55 ++
 apps/kimi-web/test/lib-logic.test.ts          | 168 ++++++
 packages/agent-core/src/services/index.ts     |   9 +
 .../src/services/worktree/worktree.ts         |  63 +++
 .../src/services/worktree/worktreeService.ts  | 508 ++++++++++++++++++
 .../test/services/worktree-service.test.ts    | 127 +++++
 packages/protocol/src/error-codes.ts          |   6 +
 packages/protocol/src/events.ts               |  11 +
 packages/protocol/src/index.ts                |   2 +
 packages/protocol/src/rest/worktree.ts        |  80 +++
 packages/protocol/src/worktree.ts             |  38 ++
 .../server/src/routes/registerApiV1Routes.ts  |   5 +
 packages/server/src/routes/worktrees.ts       | 209 +++++++
 .../services/gateway/wsBroadcastService.ts    |   3 +-
 snapshot-sync-logic.html                      | 278 ++++++++++
 worktree-board-layouts.html                   | 233 ++++++++
 worktree-marker-options.html                  | 300 +++++++++++
 worktree-sidebar.html                         | 143 +++++
 worktree-ux-mockups.html                      | 260 +++++++++
 40 files changed, 4954 insertions(+), 424 deletions(-)
 create mode 100644 apps/kimi-web/src/components/WorktreeBoard.vue
 create mode 100644 apps/kimi-web/src/components/WorktreeGroup.vue
 create mode 100644 apps/kimi-web/src/components/dialogs/NewWorktreeDialog.vue
 create mode 100644 apps/kimi-web/src/components/dialogs/WorktreeCompleteDialog.vue
 create mode 100644 apps/kimi-web/src/components/dialogs/WorktreeDialog.vue
 create mode 100644 apps/kimi-web/src/i18n/locales/en/worktree.ts
 create mode 100644 apps/kimi-web/src/i18n/locales/zh/worktree.ts
 create mode 100644 apps/kimi-web/src/lib/branchColor.ts
 create mode 100644 apps/kimi-web/src/lib/snapshotSync.ts
 create mode 100644 apps/kimi-web/src/lib/worktreeGroups.ts
 create mode 100644 packages/agent-core/src/services/worktree/worktree.ts
 create mode 100644 packages/agent-core/src/services/worktree/worktreeService.ts
 create mode 100644 packages/agent-core/test/services/worktree-service.test.ts
 create mode 100644 packages/protocol/src/rest/worktree.ts
 create mode 100644 packages/protocol/src/worktree.ts
 create mode 100644 packages/server/src/routes/worktrees.ts
 create mode 100644 snapshot-sync-logic.html
 create mode 100644 worktree-board-layouts.html
 create mode 100644 worktree-marker-options.html
 create mode 100644 worktree-sidebar.html
 create mode 100644 worktree-ux-mockups.html

diff --git a/apps/kimi-web/src/App.vue b/apps/kimi-web/src/App.vue
index 176910afa..cc9bbb79a 100644
--- a/apps/kimi-web/src/App.vue
+++ b/apps/kimi-web/src/App.vue
@@ -17,6 +17,9 @@ import NewSessionDialog from './components/dialogs/NewSessionDialog.vue';
 import SettingsDialog from './components/settings/SettingsDialog.vue';
 import SessionsDialog from './components/dialogs/SessionsDialog.vue';
 import AddWorkspaceDialog from './components/dialogs/AddWorkspaceDialog.vue';
+import WorktreeBoard from './components/WorktreeBoard.vue';
+import WorktreeCompleteDialog from './components/dialogs/WorktreeCompleteDialog.vue';
+import NewWorktreeDialog from './components/dialogs/NewWorktreeDialog.vue';
 import StatusPanel from './components/chat/StatusPanel.vue';
 import WarningToasts from './components/WarningToasts.vue';
 import MobileTopBar from './components/mobile/MobileTopBar.vue';
@@ -34,6 +37,7 @@ import { useFilePreview, type DetailTarget } from './composables/useFilePreview'
 import { useDetailPanel } from './composables/useDetailPanel';
 import { useIsMobile } from './composables/useIsMobile';
 import type { AppConfig, ThinkingLevel } from './api/types';
+import type { BoardSection, CompleteWorktreeTarget, WorkspaceView } from './types';
 
 const client = useKimiWebClient();
 provide('resolveImage', client.resolveImageUrl);
@@ -214,6 +218,19 @@ const showSessions = ref(false);
 const showAddWorkspace = ref(false);
 const showStatusPanel = ref(false);
 const showSettings = ref(false);
+const mainView = ref<'chat' | 'board'>('chat');
+const boardLoading = ref(false);
+// Global board: one section per git workspace, each carrying its worktrees and
+// sessions. Recomputed reactively as worktrees load or change.
+const boardSections = computed<BoardSection[]>(() =>
+  client.workspacesView.value
+    .filter((ws) => ws.isGitRepo === true)
+    .map((ws) => ({
+      workspace: ws,
+      worktrees: client.worktreesByWorkspace.value[ws.id] ?? [],
+      sessions: client.workspaceGroups.value.find((g) => g.workspace.id === ws.id)?.sessions ?? [],
+    })),
+);
 
 type SubmitPayload = {
   text: string;
@@ -235,6 +252,7 @@ const anyOverlayOpen = computed<boolean>(() =>
   showStatusPanel.value ||
   showSettings.value ||
   showOnboarding.value ||
+  showNewWorktree.value ||
   showMobileSwitcher.value ||
   showMobileSettings.value,
 );
@@ -500,6 +518,63 @@ function handleCreateSessionInWorkspace(workspaceId: string): void {
 function openPr(url: string): void {
   if (url) window.open(url, '_blank', 'noopener');
 }
+
+// Sidebar worktree button (per-workspace) also opens the global board.
+function handleManageWorktrees(_workspace: WorkspaceView): void {
+  void openGlobalBoard();
+}
+
+// Open the global worktree board: load worktrees for every git workspace, then
+// show the board. Per-worktree loads are independent and best-effort.
+async function openGlobalBoard(): Promise<void> {
+  mainView.value = 'board';
+  boardLoading.value = true;
+  try {
+    const gitWs = client.workspacesView.value.filter((w) => w.isGitRepo === true);
+    await Promise.allSettled(gitWs.map((w) => client.loadWorktrees(w.id)));
+  } finally {
+    boardLoading.value = false;
+  }
+}
+
+// Board "+ session" on a column: open a draft session scoped to that worktree,
+// then return to the chat so the user can type the first message.
+function handleOpenWorktreeFromBoard(workspaceId: string, path: string): void {
+  client.openWorkspaceDraft(workspaceId, path);
+  mainView.value = 'chat';
+}
+
+// Sidebar "+ session" on a worktree group: open a draft session scoped to that
+// worktree checkout. The chat is already showing, so no view switch is needed.
+function handleNewSessionInWorktree(workspaceId: string, path: string): void {
+  client.openWorkspaceDraft(workspaceId, path);
+}
+
+// Open a worktree folder in an external application (Cursor, VS Code, Finder, etc.).
+function handleOpenWorktreeInApp(workspaceId: string, path: string, appId: string): void {
+  void client.openWorktreeInApp(workspaceId, appId, path);
+}
+
+// "Complete" a worktree — opens a confirmation dialog; the dialog itself calls
+// removeWorktree and reports errors, then closes on success.
+const completeTarget = ref<CompleteWorktreeTarget | null>(null);
+
+function handleCompleteWorktree(target: CompleteWorktreeTarget): void {
+  completeTarget.value = target;
+}
+
+// Quick-create a worktree and jump straight into a draft session in it.
+const showNewWorktree = ref(false);
+
+function handleOpenNewWorktree(): void {
+  showNewWorktree.value = true;
+}
+
+function handleNewWorktreeCreated(workspaceId: string, path: string): void {
+  showNewWorktree.value = false;
+  mainView.value = 'chat';
+  client.openWorkspaceDraft(workspaceId, path);
+}
 </script>
 
 <template>
@@ -546,11 +621,12 @@ function openPr(url: string): void {
         :active-workspace="client.visibleWorkspace.value"
         :active-workspace-id="client.activeWorkspaceId.value"
         :sessions="client.sessionsForView.value"
-        :groups="client.workspaceGroups.value"
+        :groups="client.worktreeGroups.value"
         :active-id="client.activeSessionId.value"
         :attention-by-session="client.attentionBySession.value"
         :pending-by-session="client.pendingBySession.value"
         :unread-by-session="client.unreadBySession.value"
+        :available-open-in-apps="client.availableOpenInApps.value"
         @select="client.selectSession($event)"
         @create="handleCreateSession"
         @create-in-workspace="handleCreateSessionInWorkspace($event)"
@@ -562,6 +638,13 @@ function openPr(url: string): void {
         @rename-workspace="(id, name) => client.renameWorkspace(id, name)"
         @delete-workspace="(id) => client.deleteWorkspace(id)"
         @reorder-workspaces="client.reorderWorkspaces($event)"
+        @manage-worktrees="handleManageWorktrees"
+        @open-pr="openPr"
+        @open-board="openGlobalBoard"
+        @open-new-worktree="handleOpenNewWorktree"
+        @open-worktree="(wsId, path) => handleNewSessionInWorktree(wsId, path)"
+        @complete-worktree="handleCompleteWorktree"
+        @open-in-app="(wsId, path, appId) => handleOpenWorktreeInApp(wsId, path, appId)"
         @select-workspaces="handleSelectWorkspaces"
         @open-settings="showSettings = true"
         @collapse="toggleSidebarCollapse"
@@ -604,8 +687,25 @@ function openPr(url: string): void {
       @open-settings="showMobileSettings = true"
     />
 
+    <WorktreeBoard
+      v-if="mainView === 'board'"
+      :sections="boardSections"
+      :active-session-id="client.activeSessionId.value"
+      :pending-by-session="client.pendingBySession.value"
+      :unread-by-session="client.unreadBySession.value"
+      :loading="boardLoading"
+      :available-open-in-apps="client.availableOpenInApps.value"
+      @back="mainView = 'chat'"
+      @select-session="client.selectSession($event); mainView = 'chat'"
+      @open-worktree="(wsId, path) => handleOpenWorktreeFromBoard(wsId, path)"
+      @complete="handleCompleteWorktree"
+      @open-new-worktree="handleOpenNewWorktree"
+      @open-pr="openPr"
+      @open-in-app="(wsId, path, appId) => handleOpenWorktreeInApp(wsId, path, appId)"
+    />
+
     <ConversationPane
-      v-if="!hasMultiSelect"
+      v-else-if="!hasMultiSelect"
       ref="conversationPaneRef"
       :mobile="isMobile"
       :modern="client.theme.value === 'modern' || client.theme.value === 'kimi'"
@@ -862,6 +962,21 @@ function openPr(url: string): void {
       @close="handleCloseAddWorkspace"
     />
 
+    <WorktreeCompleteDialog
+      :target="completeTarget"
+      :remove-worktree="client.removeWorktree"
+      @cancel="completeTarget = null"
+    />
+
+    <NewWorktreeDialog
+      v-if="showNewWorktree"
+      :workspaces="client.workspacesView.value"
+      :default-workspace-id="client.activeWorkspaceId.value"
+      :create-worktree="client.createWorktree"
+      @created="(wsId, path) => handleNewWorktreeCreated(wsId, path)"
+      @cancel="showNewWorktree = false"
+    />
+
     <!-- Global connecting splash on first load (until the daemon round-trips) -->
     <Transition name="gload-fade">
       <GlobalLoading v-if="!client.initialized.value" />
diff --git a/apps/kimi-web/src/api/daemon/client.ts b/apps/kimi-web/src/api/daemon/client.ts
index 691bc85d6..ddf4d7ee7 100644
--- a/apps/kimi-web/src/api/daemon/client.ts
+++ b/apps/kimi-web/src/api/daemon/client.ts
@@ -20,6 +20,7 @@ import type {
   AppTaskStatus,
   AppTerminal,
   AppWorkspace,
+  AppWorktree,
   ApprovalResponse,
   FsBrowseResult,
   FsEntry,
@@ -50,6 +51,7 @@ import {
   toWireQuestionResponse,
   toWireSessionStatus,
   toAppWorkspace,
+  toAppWorktree,
   wireEventSeq,
   wireEventSessionId,
 } from './mappers';
@@ -79,6 +81,7 @@ import type {
   WireSessionRuntimeStatus,
   WireSessionSnapshot,
   WireWorkspace,
+  WireWorktree,
   WireLogoutResult,
 } from './wire';
 import { DaemonEventSocket } from './ws';
@@ -985,6 +988,57 @@ export class DaemonKimiWebApi implements KimiWebApi {
     await this.http.delete(`/workspaces/${encodeURIComponent(id)}`);
   }
 
+  // -------------------------------------------------------------------------
+  // Worktrees — git worktrees of a workspace repository
+  // -------------------------------------------------------------------------
+
+  async listWorktrees(workspaceId: string): Promise<AppWorktree[]> {
+    const data = await this.http.get<{ worktrees: WireWorktree[] }>(
+      `/workspaces/${encodeURIComponent(workspaceId)}/worktrees`,
+    );
+    return (data.worktrees ?? []).map(toAppWorktree);
+  }
+
+  async createWorktree(
+    workspaceId: string,
+    input?: { branch?: string; baseRef?: string; path?: string },
+  ): Promise<AppWorktree> {
+    const body: Record<string, unknown> = {};
+    if (input?.branch !== undefined) body['branch'] = input.branch;
+    if (input?.baseRef !== undefined) body['base_ref'] = input.baseRef;
+    if (input?.path !== undefined) body['path'] = input.path;
+    const data = await this.http.post<WireWorktree>(
+      `/workspaces/${encodeURIComponent(workspaceId)}/worktrees`,
+      body,
+    );
+    return toAppWorktree(data);
+  }
+
+  async removeWorktree(
+    workspaceId: string,
+    input: { path: string; force?: boolean; deleteBranch?: boolean },
+  ): Promise<{ removed: true }> {
+    const body: Record<string, unknown> = { path: input.path };
+    if (input.force !== undefined) body['force'] = input.force;
+    if (input.deleteBranch !== undefined) body['delete_branch'] = input.deleteBranch;
+    await this.http.post<{ removed: true }>(
+      `/workspaces/${encodeURIComponent(workspaceId)}/worktrees/remove`,
+      body,
+    );
+    return { removed: true };
+  }
+
+  async openWorktreeInApp(
+    workspaceId: string,
+    appId: string,
+    path: string,
+  ): Promise<void> {
+    await this.http.post<{ opened: true }>(
+      `/workspaces/${encodeURIComponent(workspaceId)}/worktrees/open-in`,
+      { app_id: appId, path },
+    );
+  }
+
   /**
    * Browse directories under `path` (defaults to $HOME on the daemon).
    * PRESUMED — GET /api/v1/fs:browse?path=. On error returns an empty path so
diff --git a/apps/kimi-web/src/api/daemon/eventReducer.ts b/apps/kimi-web/src/api/daemon/eventReducer.ts
index 44f43e709..8dcbc38ec 100644
--- a/apps/kimi-web/src/api/daemon/eventReducer.ts
+++ b/apps/kimi-web/src/api/daemon/eventReducer.ts
@@ -589,11 +589,12 @@ export function reduceAppEvent(
       break;
     }
 
-    // Workspace lifecycle events are handled in the composable (rawState), not
-    // here — listed explicitly to keep the switch exhaustive.
+    // Workspace + worktree lifecycle events are handled in the composable
+    // (rawState), not here — listed explicitly to keep the switch exhaustive.
     case 'workspaceCreated':
     case 'workspaceUpdated':
     case 'workspaceDeleted':
+    case 'worktreeChanged':
       break;
 
     default: {
diff --git a/apps/kimi-web/src/api/daemon/mappers.ts b/apps/kimi-web/src/api/daemon/mappers.ts
index 2170bef43..a29472250 100644
--- a/apps/kimi-web/src/api/daemon/mappers.ts
+++ b/apps/kimi-web/src/api/daemon/mappers.ts
@@ -20,6 +20,7 @@ import type {
   AppTask,
   AppTaskStatus,
   AppWorkspace,
+  AppWorktree,
   ApprovalResponse,
   ImageSource,
   PromptSubmission,
@@ -49,6 +50,7 @@ import type {
   WireSessionStatus,
   WireSessionUsage,
   WireWorkspace,
+  WireWorktree,
   WireEvent,
   WireConfig,
 } from './wire';
@@ -125,6 +127,22 @@ export function toAppWorkspace(wire: WireWorkspace): AppWorkspace {
   };
 }
 
+export function toAppWorktree(wire: WireWorktree): AppWorktree {
+  return {
+    path: wire.path,
+    branch: wire.branch,
+    head: wire.head,
+    isMain: wire.is_main,
+    locked: wire.locked,
+    prunable: wire.prunable,
+    dirty: wire.dirty,
+    ahead: wire.ahead,
+    behind: wire.behind,
+    sessionId: wire.session_id,
+    pullRequest: wire.pull_request ?? null,
+  };
+}
+
 // ---------------------------------------------------------------------------
 // Message mappers
 // ---------------------------------------------------------------------------
@@ -508,6 +526,14 @@ export function toAppEvent(wire: WireEvent): AppEvent {
         root: w.payload.root,
       };
 
+    case 'event.worktree.changed':
+      return {
+        type: 'worktreeChanged',
+        workspaceId: w.payload.workspace_id,
+        path: w.payload.path,
+        change: w.payload.change,
+      };
+
     case 'event.session.status_changed':
       return {
         type: 'sessionStatusChanged',
diff --git a/apps/kimi-web/src/api/daemon/wire.ts b/apps/kimi-web/src/api/daemon/wire.ts
index 314cb96cf..f5963f104 100644
--- a/apps/kimi-web/src/api/daemon/wire.ts
+++ b/apps/kimi-web/src/api/daemon/wire.ts
@@ -136,6 +136,21 @@ export interface WireWorkspace {
   session_count: number;
 }
 
+/** A git worktree of a workspace repository (snake_case wire DTO). */
+export interface WireWorktree {
+  path: string;
+  branch: string;
+  head: string;
+  is_main: boolean;
+  locked: boolean;
+  prunable: boolean;
+  dirty: boolean;
+  ahead: number;
+  behind: number;
+  session_id: string | null;
+  pull_request: { number: number; state: string; url: string } | null;
+}
+
 export interface WireFsBrowseEntry {
   name: string;
   path: string;
diff --git a/apps/kimi-web/src/api/types.ts b/apps/kimi-web/src/api/types.ts
index ad52b6e0d..e0c231303 100644
--- a/apps/kimi-web/src/api/types.ts
+++ b/apps/kimi-web/src/api/types.ts
@@ -134,6 +134,28 @@ export interface FsBrowseEntry {
   branch?: string;
 }
 
+/** A git worktree belonging to a workspace's repository. */
+export interface AppWorktree {
+  /** Absolute path of the worktree checkout. */
+  path: string;
+  /** Current branch name (empty when detached / no commits). */
+  branch: string;
+  /** HEAD commit SHA. */
+  head: string;
+  /** True for the primary (main) checkout of the repository. */
+  isMain: boolean;
+  locked: boolean;
+  prunable: boolean;
+  /** True when the worktree has uncommitted changes. */
+  dirty: boolean;
+  ahead: number;
+  behind: number;
+  /** Id of a session whose cwd falls inside this worktree, if any. */
+  sessionId: string | null;
+  /** GitHub pull request for the current branch, when known. */
+  pullRequest: { number: number; state: string; url: string } | null;
+}
+
 export interface FsBrowseResult {
   path: string;
   parent: string | null;
@@ -391,6 +413,7 @@ export type AppEvent =
   | { type: 'workspaceCreated'; workspace: AppWorkspace }
   | { type: 'workspaceUpdated'; workspace: AppWorkspace }
   | { type: 'workspaceDeleted'; workspaceId: string; root: string }
+  | { type: 'worktreeChanged'; workspaceId: string; path?: string; change: 'created' | 'removed' }
   | { type: 'sessionUpdated'; session: AppSession; changedFields: string[] }
   | { type: 'sessionDeleted'; sessionId: string }
   | { type: 'sessionStatusChanged'; sessionId: string; status: AppSessionStatus; previousStatus: AppSessionStatus; currentPromptId?: string }
@@ -666,6 +689,19 @@ export interface KimiWebApi {
   browseFs(path?: string): Promise<FsBrowseResult>;
   getFsHome(): Promise<{ home: string; recentRoots: string[] }>;
 
+  // Worktrees — git worktrees of a workspace repository
+  listWorktrees(workspaceId: string): Promise<AppWorktree[]>;
+  createWorktree(
+    workspaceId: string,
+    input?: { branch?: string; baseRef?: string; path?: string },
+  ): Promise<AppWorktree>;
+  removeWorktree(
+    workspaceId: string,
+    input: { path: string; force?: boolean; deleteBranch?: boolean },
+  ): Promise<{ removed: true }>;
+  /** Open a worktree folder in an external application (Cursor, VS Code, Finder, etc.). */
+  openWorktreeInApp(workspaceId: string, appId: string, path: string): Promise<void>;
+
   // PRESUMED — not in current daemon docs; isolated in adapter, swap when backend defines them.
   listModels(): Promise<AppModel[]>;
   listProviders(): Promise<AppProvider[]>;
diff --git a/apps/kimi-web/src/components/Sidebar.vue b/apps/kimi-web/src/components/Sidebar.vue
index b3ec0f0b4..81343f654 100644
--- a/apps/kimi-web/src/components/Sidebar.vue
+++ b/apps/kimi-web/src/components/Sidebar.vue
@@ -3,15 +3,13 @@
      The old workspace rail and workspace tabs have been removed;
      workspace switching, folding and renaming all live in the group header. -->
 <script setup lang="ts">
-import { computed, nextTick, onBeforeUnmount, ref } from 'vue';
+import { computed, ref } from 'vue';
 import { useI18n } from 'vue-i18n';
 import { serverEndpointLabel } from '../api/config';
-import { copyTextToClipboard } from '../lib/clipboard';
 import { loadCollapsedWorkspaces, saveCollapsedWorkspaces } from '../lib/storage';
-import { moveInOrder, type DropPosition } from '../lib/workspaceOrder';
-import type { Session, WorkspaceGroup as WorkspaceGroupType, WorkspaceView } from '../types';
+import type { CompleteWorktreeTarget, Session, WorkspaceView, WorktreeGroup as WorktreeGroupType } from '../types';
 import SessionRow from './SessionRow.vue';
-import WorkspaceGroup from './WorkspaceGroup.vue';
+import WorktreeGroup from './WorktreeGroup.vue';
 
 const { t } = useI18n();
 
@@ -26,7 +24,7 @@ const props = withDefaults(
     activeWorkspace: WorkspaceView | null;
     activeWorkspaceId: string | null;
     sessions: Session[];
-    groups: WorkspaceGroupType[];
+    groups: WorktreeGroupType[];
     activeId: string;
     attentionBySession?: Record<string, number>;
     /** Per-session pending counts split by kind, for the coloured tags. */
@@ -34,6 +32,8 @@ const props = withDefaults(
     unreadBySession?: Record<string, boolean>;
     /** Width (px) of the session column, driven by the App resize handle. */
     colWidth?: number;
+    /** Installed external-app IDs from the daemon; forwarded to each group's open-in menu. */
+    availableOpenInApps?: string[];
   }>(),
   {
     activeWorkspace: null,
@@ -58,6 +58,15 @@ const emit = defineEmits<{
   renameWorkspace: [id: string, name: string];
   deleteWorkspace: [id: string];
   reorderWorkspaces: [ids: string[]];
+  manageWorktrees: [workspace: WorkspaceView];
+  openPr: [url: string];
+  openBoard: [];
+  openNewWorktree: [];
+  /** Open a draft session scoped to a worktree checkout (sidebar "+ session"). */
+  openWorktree: [workspaceId: string, path: string];
+  completeWorktree: [target: CompleteWorktreeTarget];
+  /** Open a worktree folder in an external application. */
+  openInApp: [workspaceId: string, path: string, appId: string];
   openSettings: [];
   collapse: [];
 }>();
@@ -113,54 +122,6 @@ function toggleCollapse(id: string): void {
   saveCollapsedWorkspaces(next);
 }
 
-// ---------------------------------------------------------------------------
-// Workspace drag-to-reorder
-// ---------------------------------------------------------------------------
-// The header of each group is the drag handle (see WorkspaceGroup). We track
-// which group is being dragged and where the insertion marker sits (before or
-// after the group under the pointer), then on drop we emit the new id order
-// upward — the parent persists it and the computed `groups` re-sorts. Using the
-// pointer's position within the target (top half = before, bottom half = after)
-// is what lets a workspace be dropped at the very bottom of the list.
-const draggingWsId = ref<string | null>(null);
-const dragOver = ref<{ id: string; position: DropPosition } | null>(null);
-
-function onWsDragstart(id: string): void {
-  draggingWsId.value = id;
-}
-
-function onWsDragend(): void {
-  draggingWsId.value = null;
-  dragOver.value = null;
-}
-
-function dropPosition(event: DragEvent): DropPosition {
-  const rect = (event.currentTarget as HTMLElement).getBoundingClientRect();
-  return event.clientY < rect.top + rect.height / 2 ? 'before' : 'after';
-}
-
-function onGroupDragOver(event: DragEvent, targetId: string): void {
-  if (draggingWsId.value === null || draggingWsId.value === targetId) return;
-  event.preventDefault();
-  if (event.dataTransfer) event.dataTransfer.dropEffect = 'move';
-  dragOver.value = { id: targetId, position: dropPosition(event) };
-}
-
-function onGroupDrop(targetId: string): void {
-  const fromId = draggingWsId.value;
-  const position = dragOver.value?.id === targetId ? dragOver.value.position : 'before';
-  dragOver.value = null;
-  draggingWsId.value = null;
-  if (!fromId || fromId === targetId) return;
-  const next = moveInOrder(
-    props.groups.map((g) => g.workspace.id),
-    fromId,
-    targetId,
-    position,
-  );
-  emit('reorderWorkspaces', next);
-}
-
 // ---------------------------------------------------------------------------
 // Session list truncation per workspace
 // ---------------------------------------------------------------------------
@@ -192,242 +153,14 @@ function visibleSessions(sessions: Session[], expanded: boolean, activeId?: stri
   return visible;
 }
 
-// ---------------------------------------------------------------------------
-// Shift-multi-select workspaces
-// ---------------------------------------------------------------------------
-const selectedIds = ref<Set<string>>(new Set());
-
-function handleGhClick(wsId: string, e: MouseEvent): void {
-  if (e.shiftKey) {
-    e.stopPropagation();
-    const next = new Set(selectedIds.value);
-    if (next.has(wsId)) next.delete(wsId);
-    else next.add(wsId);
-    selectedIds.value = next;
-    emit('selectWorkspaces', Array.from(next));
-    return;
-  }
-  // Normal click: clear multi-selection then toggle collapse
-  selectedIds.value = new Set();
-  emit('selectWorkspaces', []);
-  toggleCollapse(wsId);
-}
+// Active worktree groups (running / awaiting input) float above the rest.
+const activeGroups = computed(() => props.groups.filter((g) => g.hasRunning || g.hasPending));
+const idleGroups = computed(() => props.groups.filter((g) => !g.hasRunning && !g.hasPending));
 
 function onSelectSession(sessionId: string): void {
-  selectedIds.value = new Set();
-  emit('selectWorkspaces', []);
   emit('select', sessionId);
 }
 
-// ---------------------------------------------------------------------------
-// Rename workspace (inline, like SessionRow)
-// ---------------------------------------------------------------------------
-const renamingId = ref<string | null>(null);
-const renameValue = ref('');
-const renameInputRef = ref<HTMLInputElement | null>(null);
-
-// Hand the rename-input ref OBJECT (not its unwrapped value) down to
-// WorkspaceGroup: top-level refs are auto-unwrapped in templates, so a getter
-// keeps the ref intact. The child writes its input element back, and Sidebar
-// keeps owning focus (startRenameWorkspace focuses it on nextTick).
-function getRenameInputRef() {
-  return renameInputRef;
-}
-
-function startRenameWorkspace(id: string, name: string): void {
-  renamingId.value = id;
-  renameValue.value = name;
-  void nextTick().then(() => renameInputRef.value?.focus());
-}
-
-function confirmRenameWorkspace(): void {
-  const id = renamingId.value;
-  const name = renameValue.value.trim();
-  if (id && name) {
-    emit('renameWorkspace', id, name);
-  }
-  renamingId.value = null;
-}
-
-function cancelRenameWorkspace(): void {
-  renamingId.value = null;
-}
-
-function onUpdateRenameValue(value: string): void {
-  renameValue.value = value;
-}
-
-// ---------------------------------------------------------------------------
-// Workspace right-click menu (copy path, rename)
-// ---------------------------------------------------------------------------
-const ghMenuOpen = ref(false);
-const ghMenuTarget = ref<WorkspaceView | null>(null);
-const ghMenuStyle = ref<Record<string, string>>({});
-const ghMenuRef = ref<HTMLElement | null>(null);
-
-function onGhMenuDocClick(e: MouseEvent): void {
-  if (ghMenuRef.value && !ghMenuRef.value.contains(e.target as Node)) {
-    closeGhMenu();
-  }
-}
-
-function openGhMenu(ws: WorkspaceView, e: MouseEvent): void {
-  if (e.shiftKey) {
-    // shift+right-click = multi-select (same as shift+click)
-    e.stopPropagation();
-    const next = new Set(selectedIds.value);
-    if (next.has(ws.id)) next.delete(ws.id);
-    else next.add(ws.id);
-    selectedIds.value = next;
-    emit('selectWorkspaces', Array.from(next));
-    return;
-  }
-  e.preventDefault();
-  e.stopPropagation();
-  ghMenuTarget.value = ws;
-  ghMenuStyle.value = {
-    top: `${e.clientY}px`,
-    left: `${e.clientX}px`,
-  };
-  ghMenuOpen.value = true;
-  document.addEventListener('mousedown', onGhMenuDocClick, true);
-}
-
-function closeGhMenu(): void {
-  ghMenuOpen.value = false;
-  document.removeEventListener('mousedown', onGhMenuDocClick, true);
-  ghMenuTarget.value = null;
-  disarmDeleteWs();
-}
-
-function copyPathFromMenu(): void {
-  if (ghMenuTarget.value) {
-    void copyTextToClipboard(ghMenuTarget.value.root);
-  }
-  closeGhMenu();
-}
-
-function startRenameFromMenu(): void {
-  if (ghMenuTarget.value) {
-    startRenameWorkspace(ghMenuTarget.value.id, ghMenuTarget.value.name);
-  }
-  closeGhMenu();
-}
-
-function deleteFromMenu(): void {
-  const ws = ghMenuTarget.value;
-  if (!ws) return;
-  if (!armDeleteWs(ws.id)) return; // first click arms ("confirm?"), keep menu open
-  emit('deleteWorkspace', ws.id);
-  closeGhMenu();
-}
-
-// ---------------------------------------------------------------------------
-// Two-step workspace delete (shared by the kebab menu and the context menu):
-// the first click arms the item — it turns into a "confirm" label — and a
-// second click within 2.5s actually deletes; otherwise the item reverts.
-// ---------------------------------------------------------------------------
-const deleteArmedWsId = ref<string | null>(null);
-let deleteArmTimer: ReturnType<typeof setTimeout> | undefined;
-
-function disarmDeleteWs(): void {
-  clearTimeout(deleteArmTimer);
-  deleteArmedWsId.value = null;
-}
-
-/** Returns true when the delete is confirmed (second click while armed). */
-function armDeleteWs(id: string): boolean {
-  if (deleteArmedWsId.value === id) {
-    disarmDeleteWs();
-    return true;
-  }
-  clearTimeout(deleteArmTimer);
-  deleteArmedWsId.value = id;
-  deleteArmTimer = setTimeout(() => {
-    deleteArmedWsId.value = null;
-  }, 2500);
-  return false;
-}
-
-// ---------------------------------------------------------------------------
-// Workspace inline more-menu (kebab, hover-triggered). Rendered position:fixed
-// and anchored to the ⋯ button so the scrolling session list can't clip it;
-// it doesn't follow the anchor, so scroll/resize simply close it.
-// ---------------------------------------------------------------------------
-const wsMenuOpenId = ref<string | null>(null);
-const wsMenuTarget = ref<WorkspaceView | null>(null);
-const wsMenuStyle = ref<Record<string, string>>({});
-const wsMenuRef = ref<HTMLElement | null>(null);
-
-function onWsMenuDocClick(e: MouseEvent): void {
-  const target = e.target as Element;
-  if (target.closest('.gh-more') || target.closest('.ws-menu')) return;
-  closeWsMenu();
-}
-
-async function toggleWsMenu(ws: WorkspaceView, e: MouseEvent): Promise<void> {
-  if (wsMenuOpenId.value === ws.id) {
-    closeWsMenu();
-    return;
-  }
-  const btn = e.currentTarget as HTMLElement;
-  wsMenuTarget.value = ws;
-  wsMenuOpenId.value = ws.id;
-  document.addEventListener('mousedown', onWsMenuDocClick);
-  document.addEventListener('scroll', closeWsMenu, true);
-  window.addEventListener('resize', closeWsMenu);
-  await nextTick();
-  const menu = wsMenuRef.value;
-  const r = btn.getBoundingClientRect();
-  const gap = 4;
-  const margin = 8;
-  const menuH = menu?.offsetHeight ?? 0;
-  const menuW = menu?.offsetWidth ?? 0;
-  let top = r.bottom + gap;
-  if (top + menuH > window.innerHeight - margin) {
-    top = Math.max(margin, r.top - menuH - gap);
-  }
-  let left = r.right - menuW;
-  if (left < margin) left = margin;
-  wsMenuStyle.value = {
-    top: `${Math.round(top)}px`,
-    left: `${Math.round(left)}px`,
-  };
-}
-
-function closeWsMenu(): void {
-  wsMenuOpenId.value = null;
-  wsMenuTarget.value = null;
-  disarmDeleteWs();
-  document.removeEventListener('mousedown', onWsMenuDocClick);
-  document.removeEventListener('scroll', closeWsMenu, true);
-  window.removeEventListener('resize', closeWsMenu);
-}
-
-function copyWsPath(ws: WorkspaceView): void {
-  void copyTextToClipboard(ws.root);
-  closeWsMenu();
-}
-
-function startRenameWs(ws: WorkspaceView): void {
-  startRenameWorkspace(ws.id, ws.name);
-  closeWsMenu();
-}
-
-function deleteWs(ws: WorkspaceView): void {
-  if (!armDeleteWs(ws.id)) return; // first click arms ("confirm?"), keep menu open
-  emit('deleteWorkspace', ws.id);
-  closeWsMenu();
-}
-
-onBeforeUnmount(() => {
-  document.removeEventListener('mousedown', onGhMenuDocClick, true);
-  document.removeEventListener('mousedown', onWsMenuDocClick);
-  document.removeEventListener('scroll', closeWsMenu, true);
-  window.removeEventListener('resize', closeWsMenu);
-  clearTimeout(deleteArmTimer);
-});
-
 // Logo easter-egg: clicking the Kimi mark plays one quick blink. It's a one-shot
 // animation — force a reflow so rapid clicks restart it, then drop the class so
 // the idle look/blink loop resumes.
@@ -533,6 +266,33 @@ function blinkOnce(): void {
           </svg>
           <span>{{ t('sidebar.newChat') }}</span>
         </button>
+        <button
+          type="button"
+          class="btn-board"
+          :title="t('worktree.boardTitle')"
+          :aria-label="t('worktree.boardTitle')"
+          @click.stop="emit('openBoard')"
+        >
+          <svg viewBox="0 0 16 16" width="16" height="16" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
+            <rect x="1.5" y="2.5" width="3.5" height="11" rx="1"/>
+            <rect x="6.25" y="2.5" width="3.5" height="7" rx="1"/>
+            <rect x="11" y="2.5" width="3.5" height="9" rx="1"/>
+          </svg>
+        </button>
+        <button
+          type="button"
+          class="btn-new-wt"
+          :title="t('worktree.newTitle')"
+          :aria-label="t('worktree.newTitle')"
+          @click.stop="emit('openNewWorktree')"
+        >
+          <svg viewBox="0 0 16 16" width="16" height="16" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
+            <circle cx="4.5" cy="3.5" r="1.6"/>
+            <circle cx="4.5" cy="12.5" r="1.6"/>
+            <path d="M4.5 5.1v5.8M4.5 5.1c0 2.6 1.6 4.2 4.2 4.2h2"/>
+            <path d="M12.5 5v5M10 7.5h5"/>
+          </svg>
+        </button>
         <button
           v-if="showNewWorkspaceButton"
           type="button"
@@ -575,96 +335,58 @@ function blinkOnce(): void {
         <!-- Empty state — only when no workspace is registered at all; empty
              workspaces still render their group header (with the + button). -->
         <div v-if="groups.length === 0" class="empty">
-          {{ t('workspace.noWorkspace') }}
+          {{ t('sidebar.noSessions') }}
         </div>
 
         <template v-else>
-          <div
-            v-for="g in groups"
-            :key="g.workspace.id"
-            class="ws-drop-target"
-            :class="{
-              'drop-before': dragOver?.id === g.workspace.id && dragOver.position === 'before',
-              'drop-after': dragOver?.id === g.workspace.id && dragOver.position === 'after',
-            }"
-            @dragover="onGroupDragOver($event, g.workspace.id)"
-            @drop="onGroupDrop(g.workspace.id)"
-          >
-            <WorkspaceGroup
-              :group="g"
-              :active-workspace-id="activeWorkspaceId"
-              :active-id="activeId"
-              :selected-ids="selectedIds"
-              :renaming-id="renamingId"
-              :rename-value="renameValue"
-              :rename-input-ref="getRenameInputRef()"
-              :pending-by-session="pendingBySession"
-              :unread-by-session="unreadBySession"
-              :ws-menu-open-id="wsMenuOpenId"
-              :dragging="draggingWsId === g.workspace.id"
-              :is-collapsed="isCollapsed"
-              :is-expanded="isExpanded"
-              :visible-sessions="visibleSessions"
-              @group-click="handleGhClick"
-              @group-contextmenu="openGhMenu"
-              @toggle-ws-menu="toggleWsMenu"
-              @create-in-workspace="(id) => emit('createInWorkspace', id)"
-              @select-session="onSelectSession"
-              @rename-session="(id, title) => emit('rename', id, title)"
-              @archive-session="(id) => emit('archive', id)"
-              @fork-session="(id) => emit('fork', id)"
-              @toggle-expand="toggleExpand"
-              @confirm-rename="confirmRenameWorkspace"
-              @cancel-rename="cancelRenameWorkspace"
-              @update-rename-value="onUpdateRenameValue"
-              @ws-dragstart="onWsDragstart"
-              @ws-dragend="onWsDragend"
-            />
-          </div>
+          <WorktreeGroup
+            v-for="g in activeGroups"
+            :key="g.key"
+            :group="g"
+            :active-id="activeId"
+            :pending-by-session="pendingBySession"
+            :unread-by-session="unreadBySession"
+            :is-collapsed="isCollapsed(g.key)"
+            :is-expanded="isExpanded(g.key)"
+            :visible-sessions="visibleSessions"
+            :available-open-in-apps="availableOpenInApps"
+            @select-session="onSelectSession"
+            @rename-session="(id, title) => emit('rename', id, title)"
+            @archive-session="(id) => emit('archive', id)"
+            @fork-session="(id) => emit('fork', id)"
+            @open-pr="(url) => emit('openPr', url)"
+            @new-session="(wsId, path) => emit('openWorktree', wsId, path)"
+            @complete="(target) => emit('completeWorktree', target)"
+            @open-in-app="(wsId, path, appId) => emit('openInApp', wsId, path, appId)"
+            @toggle-collapse="toggleCollapse"
+            @toggle-expand="toggleExpand"
+          />
+          <div v-if="activeGroups.length > 0 && idleGroups.length > 0" class="sec-divider" />
+          <WorktreeGroup
+            v-for="g in idleGroups"
+            :key="g.key"
+            :group="g"
+            :active-id="activeId"
+            :pending-by-session="pendingBySession"
+            :unread-by-session="unreadBySession"
+            :is-collapsed="isCollapsed(g.key)"
+            :is-expanded="isExpanded(g.key)"
+            :visible-sessions="visibleSessions"
+            :available-open-in-apps="availableOpenInApps"
+            @select-session="onSelectSession"
+            @rename-session="(id, title) => emit('rename', id, title)"
+            @archive-session="(id) => emit('archive', id)"
+            @fork-session="(id) => emit('fork', id)"
+            @open-pr="(url) => emit('openPr', url)"
+            @new-session="(wsId, path) => emit('openWorktree', wsId, path)"
+            @complete="(target) => emit('completeWorktree', target)"
+            @open-in-app="(wsId, path, appId) => emit('openInApp', wsId, path, appId)"
+            @toggle-collapse="toggleCollapse"
+            @toggle-expand="toggleExpand"
+          />
         </template>
       </div>
     </div>
-
-    <!-- Workspace right-click menu (position:fixed) -->
-    <div
-      v-if="ghMenuOpen"
-      ref="ghMenuRef"
-      class="gh-menu"
-      :style="ghMenuStyle"
-      @click.stop
-    >
-      <button type="button" class="ghm-item" @click="copyPathFromMenu">
-        {{ t('sidebar.copyPath') }}
-      </button>
-      <button type="button" class="ghm-item" @click="startRenameFromMenu">
-        {{ t('sidebar.rename') }}
-      </button>
-      <button type="button" class="ghm-item del" @click="deleteFromMenu">
-        {{ ghMenuTarget && deleteArmedWsId === ghMenuTarget.id ? t('sidebar.confirm') : t('sidebar.removeWorkspace') }}
-      </button>
-    </div>
-
-    <!-- Workspace kebab menu (position:fixed, anchored to the ⋯ button so the
-         scrolling session list cannot clip it) -->
-    <div
-      v-if="wsMenuOpenId !== null && wsMenuTarget"
-      ref="wsMenuRef"
-      class="ws-menu"
-      :style="wsMenuStyle"
-      @click.stop
-    >
-      <button class="ws-menu-item" @click.stop="copyWsPath(wsMenuTarget)">
-        {{ t('sidebar.copyPath') }}
-      </button>
-      <div class="ws-menu-divider" />
-      <button class="ws-menu-item" @click.stop="startRenameWs(wsMenuTarget)">
-        {{ t('sidebar.rename') }}
-      </button>
-      <div class="ws-menu-divider" />
-      <button class="ws-menu-item del" @click.stop="deleteWs(wsMenuTarget)">
-        {{ deleteArmedWsId === wsMenuTarget.id ? t('sidebar.confirm') : t('sidebar.removeWorkspace') }}
-      </button>
-    </div>
   </aside>
 </template>
 
@@ -833,6 +555,34 @@ function blinkOnce(): void {
   border-color: var(--bd);
   color: var(--dim);
 }
+.btn-board {
+  flex: none;
+  justify-content: center;
+  aspect-ratio: 1;
+  padding: 9px 10px;
+  color: var(--muted);
+  background: transparent;
+  border: 1px solid var(--line);
+}
+.btn-board:hover {
+  background: var(--panel);
+  border-color: var(--bd);
+  color: var(--blue);
+}
+.btn-new-wt {
+  flex: none;
+  justify-content: center;
+  aspect-ratio: 1;
+  padding: 9px 10px;
+  color: var(--muted);
+  background: transparent;
+  border: 1px solid var(--line);
+}
+.btn-new-wt:hover {
+  background: var(--panel);
+  border-color: var(--bd);
+  color: var(--blue);
+}
 
 /* Session search */
 .search {
@@ -902,12 +652,6 @@ function blinkOnce(): void {
 }
 .sessions::-webkit-scrollbar-thumb:hover { background: var(--bd); }
 
-/* Workspace drag-to-reorder: a line at the top (drop-before) or bottom
-   (drop-after) of the group under the cursor marks where the dragged workspace
-   will land. Inset shadows avoid layout shift. */
-.ws-drop-target.drop-before { box-shadow: inset 0 2px 0 var(--blue); }
-.ws-drop-target.drop-after { box-shadow: inset 0 -2px 0 var(--blue); }
-
 .empty {
   padding: 24px 12px;
   text-align: center;
@@ -915,6 +659,11 @@ function blinkOnce(): void {
   font-size: calc(var(--ui-font-size) - 3px);
   line-height: 1.6;
 }
+.sec-divider {
+  height: 1px;
+  background: var(--line);
+  margin: 6px 12px;
+}
 
 /* Workspace kebab dropdown menu — fixed so the scroll container can't clip it;
    anchored to the ⋯ trigger from toggleWsMenu(). */
diff --git a/apps/kimi-web/src/components/WorktreeBoard.vue b/apps/kimi-web/src/components/WorktreeBoard.vue
new file mode 100644
index 000000000..a90f2d7bd
--- /dev/null
+++ b/apps/kimi-web/src/components/WorktreeBoard.vue
@@ -0,0 +1,361 @@
+<!-- apps/kimi-web/src/components/WorktreeBoard.vue -->
+<!-- Global worktree board: every worktree across all git workspaces is a
+     column in an auto-filling grid, sorted so active worktrees come first.
+     The repo is shown as a secondary label on each column (workspace is no
+     longer a grouping level, matching the worktree-centric sidebar). -->
+<script setup lang="ts">
+import { computed } from 'vue';
+import { useI18n } from 'vue-i18n';
+import type { AppWorktree } from '../api/types';
+import type { BoardSection, CompleteWorktreeTarget, Session, WorkspaceView } from '../types';
+import { branchColor } from '../lib/branchColor';
+import OpenInMenu from './chat/OpenInMenu.vue';
+
+const { t } = useI18n();
+
+const props = defineProps<{
+  sections: BoardSection[];
+  activeSessionId: string | null;
+  pendingBySession: Record<string, { approvals: number; questions: number }>;
+  unreadBySession: Record<string, boolean>;
+  loading?: boolean;
+  /** Installed external-app IDs from the daemon; forwarded to the open-in menu. */
+  availableOpenInApps?: string[];
+}>();
+
+const emit = defineEmits<{
+  back: [];
+  selectSession: [sessionId: string];
+  /** Open a (draft) session scoped to a worktree path in a workspace. */
+  openWorktree: [workspaceId: string, path: string];
+  openPr: [url: string];
+  complete: [target: CompleteWorktreeTarget];
+  openNewWorktree: [];
+  /** Open a worktree folder in an external application. */
+  openInApp: [workspaceId: string, path: string, appId: string];
+}>();
+
+interface FlatColumn {
+  workspace: WorkspaceView;
+  worktree: AppWorktree;
+  sessions: Session[];
+  hasRunning: boolean;
+  hasPending: boolean;
+  latestAt: number;
+}
+
+function columnsFor(section: BoardSection): { worktree: AppWorktree; sessions: Session[] }[] {
+  const wts = [...section.worktrees].toSorted((a, b) => {
+    if (a.isMain !== b.isMain) return a.isMain ? -1 : 1;
+    return a.branch.localeCompare(b.branch);
+  });
+  const used = new Set<string>();
+  const cols: { worktree: AppWorktree; sessions: Session[] }[] = wts.map((worktree) => {
+    const ss = section.sessions.filter((s) => {
+      if (s.branch === worktree.branch) {
+        used.add(s.id);
+        return true;
+      }
+      return false;
+    });
+    return { worktree, sessions: ss };
+  });
+  // Unassigned sessions (branch not matched to any worktree) fall into main.
+  const unassigned = section.sessions.filter((s) => !used.has(s.id));
+  if (unassigned.length > 0) {
+    const main = cols.find((c) => c.worktree.isMain);
+    if (main) main.sessions = [...main.sessions, ...unassigned];
+  }
+  return cols;
+}
+
+const BUCKET_MS = 30_000;
+const columns = computed<FlatColumn[]>(() => {
+  const flat: FlatColumn[] = [];
+  for (const section of props.sections) {
+    for (const col of columnsFor(section)) {
+      const sessions = [...col.sessions].toSorted(
+        (a, b) => new Date(b.updatedAt ?? 0).getTime() - new Date(a.updatedAt ?? 0).getTime(),
+      );
+      const hasRunning = sessions.some((s) => s.busy);
+      const hasPending = sessions.some(
+        (s) => s.status === 'awaitingApproval' || s.status === 'awaitingQuestion',
+      );
+      const latestAt = sessions.reduce(
+        (m, s) => Math.max(m, s.updatedAt ? new Date(s.updatedAt).getTime() : 0),
+        0,
+      );
+      flat.push({
+        workspace: section.workspace,
+        worktree: col.worktree,
+        sessions,
+        hasRunning,
+        hasPending,
+        latestAt,
+      });
+    }
+  }
+  flat.sort((a, b) => {
+    const aa = a.hasRunning || a.hasPending ? 1 : 0;
+    const bb = b.hasRunning || b.hasPending ? 1 : 0;
+    if (aa !== bb) return bb - aa;
+    const ba = Math.floor(b.latestAt / BUCKET_MS);
+    const bk = Math.floor(a.latestAt / BUCKET_MS);
+    if (ba !== bk) return ba - bk;
+    const ka = `${a.workspace.id}:${a.worktree.branch}`;
+    const kb = `${b.workspace.id}:${b.worktree.branch}`;
+    return ka.localeCompare(kb);
+  });
+  return flat;
+});
+
+function attention(col: FlatColumn): 'running' | 'pending' | null {
+  if (col.hasRunning) return 'running';
+  if (col.hasPending) return 'pending';
+  return null;
+}
+
+function branchLabel(w: AppWorktree): string {
+  if (w.branch.length > 0) return w.branch;
+  if (w.head.length > 0) return w.head.slice(0, 7);
+  return t('worktree.detached');
+}
+
+function completeTarget(col: FlatColumn): CompleteWorktreeTarget {
+  return {
+    workspaceId: col.workspace.id,
+    path: col.worktree.path,
+    branch: col.worktree.branch,
+    dirty: col.worktree.dirty,
+    sessionCount: col.sessions.length,
+    isMain: col.worktree.isMain,
+  };
+}
+</script>
+
+<template>
+  <div class="board">
+    <div class="topbar">
+      <button class="back" :title="t('worktree.close')" @click="emit('back')">‹</button>
+      <span class="title">{{ t('worktree.boardTitle') }}</span>
+      <span class="spacer" />
+      <button class="btn-primary" @click="emit('openNewWorktree')">+ {{ t('worktree.create') }}</button>
+    </div>
+
+    <div v-if="loading" class="loading">{{ t('worktree.loading') }}</div>
+
+    <div v-else class="grid">
+      <div
+        v-for="col in columns"
+        :key="`${col.workspace.id}:${col.worktree.path}`"
+        class="col"
+        :style="col.worktree.branch ? { '--c': branchColor(col.worktree.branch) } : undefined"
+      >
+        <div class="col-head">
+          <div class="col-label">
+            <span class="br" :title="col.worktree.path">{{ branchLabel(col.worktree) }}</span>
+            <span class="ws" :title="col.workspace.root">{{ col.workspace.name }}</span>
+            <span v-if="col.worktree.isMain" class="badge">{{ t('worktree.main') }}</span>
+          </div>
+          <button
+            v-if="col.worktree.pullRequest"
+            class="pr"
+            :class="`pr-${col.worktree.pullRequest.state}`"
+            :title="col.worktree.pullRequest.url"
+            @click.stop="col.worktree.pullRequest && emit('openPr', col.worktree.pullRequest.url)"
+          >#{{ col.worktree.pullRequest.number }}</button>
+          <span
+            v-if="attention(col)"
+            class="attn"
+            :class="`attn-${attention(col)}`"
+          />
+          <span class="count">{{ col.sessions.length }}</span>
+        </div>
+        <div class="col-meta">
+          <span v-if="col.worktree.dirty">{{ t('worktree.dirty') }}</span>
+          <span v-if="col.worktree.ahead > 0">↑{{ col.worktree.ahead }}</span>
+          <span v-if="col.worktree.behind > 0">↓{{ col.worktree.behind }}</span>
+          <span v-if="!col.worktree.dirty && col.worktree.ahead === 0 && col.worktree.behind === 0">{{ t('worktree.clean') }}</span>
+        </div>
+
+        <div class="col-body">
+          <div
+            v-for="s in col.sessions"
+            :key="s.id"
+            class="sess-card"
+            :class="{ on: s.id === activeSessionId }"
+            @click="emit('selectSession', s.id)"
+          >
+            <div class="tline">
+              <span v-if="s.busy" class="spin" />
+              <span v-else-if="unreadBySession[s.id]" class="unread" />
+              <span class="t">{{ s.title }}</span>
+            </div>
+            <div v-if="s.lastPrompt" class="preview">{{ s.lastPrompt }}</div>
+            <div class="foot">
+              <span class="time">{{ s.time }}</span>
+              <span v-if="(pendingBySession[s.id]?.questions ?? 0) > 0 || s.status === 'awaitingQuestion'" class="tag tag-ask">{{ t('workspace.awaitingAnswer') }}</span>
+              <span v-if="(pendingBySession[s.id]?.approvals ?? 0) > 0 || s.status === 'awaitingApproval'" class="tag tag-approve">{{ t('workspace.awaitingPermission') }}</span>
+            </div>
+          </div>
+          <div v-if="col.sessions.length === 0" class="empty">{{ t('worktree.noSessions') }}</div>
+        </div>
+
+        <div class="col-foot">
+          <button
+            class="add"
+            @click="emit('openWorktree', col.workspace.id, col.worktree.path)"
+          >+ session</button>
+          <OpenInMenu
+            compact
+            :work-dir="col.worktree.path"
+            :available-apps="availableOpenInApps"
+            @open-in-app="(appId) => emit('openInApp', col.workspace.id, col.worktree.path, appId)"
+          />
+          <button
+            v-if="!col.worktree.isMain"
+            class="del"
+            @click="emit('complete', completeTarget(col))"
+          >{{ t('worktree.complete') }}</button>
+        </div>
+      </div>
+
+      <div v-if="columns.length === 0" class="empty-all">{{ t('worktree.noGitWorkspaces') }}</div>
+    </div>
+  </div>
+</template>
+
+<style scoped>
+.board {
+  display: flex;
+  flex-direction: column;
+  height: 100%;
+  background: var(--panel);
+  color: var(--text);
+  font-family: var(--mono);
+  overflow: hidden;
+}
+.topbar {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  padding: 12px 18px;
+  border-bottom: 1px solid var(--line);
+  background: var(--bg);
+  flex: none;
+}
+.back {
+  background: none;
+  border: 1px solid var(--line);
+  border-radius: 7px;
+  color: var(--dim);
+  cursor: pointer;
+  font-size: 18px;
+  line-height: 1;
+  width: 28px;
+  height: 28px;
+  flex: none;
+}
+.back:hover { color: var(--ink); background: var(--panel2); }
+.title { font-size: 16px; font-weight: 600; color: var(--ink); }
+.spacer { flex: 1; }
+.btn-primary {
+  background: var(--blue);
+  color: #fff;
+  border: none;
+  border-radius: 6px;
+  padding: 6px 12px;
+  font-family: var(--mono);
+  font-size: var(--ui-font-size);
+  cursor: pointer;
+  white-space: nowrap;
+}
+.btn-primary:hover { background: var(--blue2); }
+.loading { padding: 40px; color: var(--faint); text-align: center; }
+.empty-all { padding: 40px; color: var(--faint); text-align: center; grid-column: 1 / -1; }
+
+.grid {
+  flex: 1;
+  min-height: 0;
+  overflow-y: auto;
+  padding: 16px 18px;
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(290px, 1fr));
+  gap: 14px;
+  align-items: start;
+  align-content: start;
+}
+.col {
+  background: var(--bg);
+  border: 1px solid var(--line);
+  border-top: 3px solid var(--c, var(--line));
+  border-radius: 10px;
+  display: flex;
+  flex-direction: column;
+  max-height: 60vh;
+  box-shadow: 0 2px 10px rgba(20, 23, 28, 0.05);
+}
+.col-head {
+  display: flex;
+  align-items: center;
+  gap: 7px;
+  padding: 11px 13px 4px;
+  min-width: 0;
+  flex: none;
+}
+/* Left cluster (branch + workspace + badge): fills the column header so the
+   branch name uses every pixel not taken by the PR / attention / count on the
+   right — mirroring the sidebar group header. The workspace name is capped and
+   shrinks first since the branch is the primary label. */
+.col-label {
+  display: flex;
+  align-items: center;
+  gap: 7px;
+  flex: 1 1 auto;
+  min-width: 0;
+}
+.br { color: var(--c, var(--dim)); font-weight: 600; font-size: 14px; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; flex: 1 1 auto; min-width: 0; }
+.ws { color: var(--faint); font-size: 11px; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; flex: 0 1 auto; min-width: 0; max-width: 40%; }
+.badge { font-size: 11px; color: var(--faint); border: 1px solid var(--line); border-radius: 8px; padding: 0 5px; flex: none; }
+.pr {
+  flex: none; border: 1px solid transparent; border-radius: 9px; padding: 0 6px; height: 18px; line-height: 16px;
+  font-size: 12px; background: transparent; cursor: pointer; font-family: var(--mono);
+}
+.pr-open { color: var(--ok); border-color: color-mix(in srgb, var(--ok) 38%, var(--bg)); }
+.pr-merged { color: #8957e5; border-color: color-mix(in srgb, #8957e5 38%, var(--bg)); }
+.attn { flex: none; width: 7px; height: 7px; border-radius: 50%; }
+.attn-running { background: var(--ok); box-shadow: 0 0 0 3px color-mix(in srgb, var(--ok) 18%, transparent); }
+.attn-pending { background: var(--warn); box-shadow: 0 0 0 3px color-mix(in srgb, var(--warn) 18%, transparent); }
+.count { color: var(--faint); font-size: 12px; flex: none; }
+.col-meta { display: flex; gap: 8px; padding: 0 13px 8px; font-size: 11px; color: var(--muted); flex: none; }
+
+.col-body { padding: 4px 9px 9px; overflow-y: auto; display: flex; flex-direction: column; gap: 8px; min-height: 0; }
+.sess-card {
+  background: var(--bg);
+  border: 1px solid var(--line);
+  border-radius: 9px;
+  padding: 10px 11px;
+  cursor: pointer;
+  transition: border-color .12s, box-shadow .12s, transform .12s;
+}
+.sess-card:hover { border-color: var(--blue); box-shadow: 0 4px 12px rgba(20, 23, 28, 0.08); transform: translateY(-1px); }
+.sess-card.on { border-color: var(--blue); box-shadow: inset 0 0 0 1px var(--bd); }
+.tline { display: flex; align-items: center; gap: 6px; }
+.t { flex: 1; min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; color: var(--ink); font-weight: 500; font-size: 13px; }
+.spin { width: 12px; height: 12px; border: 2px solid var(--line); border-top-color: var(--blue); border-radius: 50%; animation: sp .8s linear infinite; flex: none; }
+@keyframes sp { to { transform: rotate(360deg); } }
+.unread { width: 7px; height: 7px; border-radius: 50%; background: var(--blue); flex: none; }
+.preview { color: var(--muted); font-size: 11px; margin-top: 5px; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.foot { display: flex; align-items: center; gap: 6px; margin-top: 7px; }
+.time { color: var(--faint); font-size: 11px; margin-right: auto; }
+.tag { flex: none; height: 18px; border-radius: 9px; padding: 0 6px; line-height: 18px; font-size: 11px; border: 1px solid transparent; }
+.tag-ask { background: var(--soft); color: var(--blue2); border-color: var(--bd); }
+.tag-approve { background: color-mix(in srgb, var(--warn) 16%, var(--bg)); color: var(--warn); border-color: color-mix(in srgb, var(--warn) 38%, var(--bg)); }
+.empty { color: var(--faint); font-size: 11px; text-align: center; padding: 14px 0; }
+
+.col-foot { padding: 9px; border-top: 1px solid var(--line); flex: none; display: flex; gap: 6px; align-items: center; }
+.add { flex: 1; text-align: center; color: var(--faint); font-size: 12px; padding: 6px; border: 1px dashed var(--line); border-radius: 8px; cursor: pointer; background: transparent; font-family: var(--mono); }
+.add:hover { color: var(--blue); border-color: var(--blue); }
+.del { background: none; border: none; color: var(--faint); cursor: pointer; font-family: var(--mono); font-size: 11px; padding: 4px 6px; border-radius: 6px; }
+.del:hover { color: var(--err); background: var(--panel2); }
+</style>
diff --git a/apps/kimi-web/src/components/WorktreeGroup.vue b/apps/kimi-web/src/components/WorktreeGroup.vue
new file mode 100644
index 000000000..9b511f007
--- /dev/null
+++ b/apps/kimi-web/src/components/WorktreeGroup.vue
@@ -0,0 +1,288 @@
+<!-- apps/kimi-web/src/components/WorktreeGroup.vue -->
+<!-- One worktree group in the worktree-centric sidebar: a header (branch +
+     repo + PR + live indicator) and that worktree's session rows (with
+     show-more truncation). Read-only header — management lives in the board. -->
+<script setup lang="ts">
+import { computed } from 'vue';
+import { useI18n } from 'vue-i18n';
+import type { CompleteWorktreeTarget, Session, WorktreeGroup } from '../types';
+import SessionRow from './SessionRow.vue';
+import OpenInMenu from './chat/OpenInMenu.vue';
+import { branchColor } from '../lib/branchColor';
+
+const { t } = useI18n();
+
+const props = defineProps<{
+  group: WorktreeGroup;
+  activeId: string;
+  pendingBySession: Record<string, { approvals: number; questions: number }>;
+  unreadBySession: Record<string, boolean>;
+  isCollapsed: boolean;
+  isExpanded: boolean;
+  visibleSessions: (sessions: Session[], expanded: boolean, activeId?: string) => Session[];
+  /** Installed external-app IDs from the daemon; forwarded to the open-in menu. */
+  availableOpenInApps?: string[];
+}>();
+
+const emit = defineEmits<{
+  selectSession: [id: string];
+  renameSession: [id: string, title: string];
+  archiveSession: [id: string];
+  forkSession: [id: string];
+  openPr: [url: string];
+  /** Open a draft session scoped to this worktree's checkout path. */
+  newSession: [workspaceId: string, path: string];
+  complete: [target: CompleteWorktreeTarget];
+  toggleCollapse: [key: string];
+  toggleExpand: [key: string];
+  /** Open this worktree folder in an external application. */
+  openInApp: [workspaceId: string, path: string, appId: string];
+}>();
+
+function completeTarget(): CompleteWorktreeTarget {
+  return {
+    workspaceId: props.group.workspaceId,
+    path: props.group.path,
+    branch: props.group.branch,
+    dirty: props.group.dirty,
+    sessionCount: props.group.sessions.length,
+    isMain: props.group.isMain,
+  };
+}
+
+const rows = computed<Session[]>(() =>
+  props.visibleSessions(props.group.sessions, props.isExpanded, props.activeId),
+);
+const hasMore = computed(
+  () =>
+    !props.isExpanded &&
+    props.visibleSessions(props.group.sessions, false, props.activeId).length <
+      props.group.sessions.length,
+);
+const moreCount = computed(
+  () =>
+    props.group.sessions.length -
+    props.visibleSessions(props.group.sessions, false, props.activeId).length,
+);
+
+// Color key: branch when known, otherwise the repo name (so the dot still has a stable color).
+const colorKey = computed(() => props.group.branch || props.group.workspaceName);
+// Group-level attention: running wins, otherwise awaiting-input, otherwise none.
+const attention = computed<'running' | 'pending' | null>(() => {
+  if (props.group.hasRunning) return 'running';
+  if (props.group.hasPending) return 'pending';
+  return null;
+});
+</script>
+
+<template>
+  <div class="wg" :class="{ 'is-empty': group.sessions.length === 0 }" :style="{ '--c': branchColor(colorKey) }">
+    <div class="wg-head" @click="emit('toggleCollapse', group.key)">
+      <div class="wg-label">
+        <span class="repo" :title="group.workspaceName">{{ group.workspaceName }}</span>
+        <template v-if="group.branch">
+          <span class="sep">›</span>
+          <span class="br" :title="group.branch">{{ group.branch }}</span>
+        </template>
+        <span v-if="group.isMain" class="badge">{{ t('worktree.main') }}</span>
+      </div>
+      <button
+        v-if="group.pullRequest"
+        class="pr"
+        :class="`pr-${group.pullRequest.state}`"
+        :title="group.pullRequest.url"
+        @click.stop="group.pullRequest && emit('openPr', group.pullRequest.url)"
+      >#{{ group.pullRequest.number }}</button>
+      <button
+        class="new-session-btn"
+        :title="t('worktree.newSessionHere')"
+        :aria-label="t('worktree.newSessionHere')"
+        @click.stop="emit('newSession', group.workspaceId, group.path)"
+      >+ session</button>
+      <button
+        v-if="!group.isMain"
+        class="complete-btn"
+        :title="t('worktree.complete')"
+        @click.stop="emit('complete', completeTarget())"
+      >{{ t('worktree.complete') }}</button>
+      <span class="open-in-wrap" @click.stop>
+        <OpenInMenu
+          compact
+          :work-dir="group.path"
+          :available-apps="availableOpenInApps"
+          @open-in-app="(appId) => emit('openInApp', group.workspaceId, group.path, appId)"
+        />
+      </span>
+      <span
+        v-if="attention"
+        class="attn"
+        :class="`attn-${attention}`"
+        :title="attention === 'running' ? t('worktree.live') : t('worktree.pending')"
+      />
+    </div>
+
+    <template v-if="!isCollapsed">
+      <SessionRow
+        v-for="s in rows"
+        :key="s.id"
+        :session="s"
+        :active="s.id === activeId"
+        :approval-count="pendingBySession[s.id]?.approvals ?? 0"
+        :question-count="pendingBySession[s.id]?.questions ?? 0"
+        :unread="unreadBySession[s.id] ?? false"
+        @select="emit('selectSession', $event)"
+        @rename="(id, title) => emit('renameSession', id, title)"
+        @archive="emit('archiveSession', $event)"
+        @fork="emit('forkSession', $event)"
+      />
+
+      <button v-if="hasMore" class="show-more" @click.stop="emit('toggleExpand', group.key)">
+        {{ t('sidebar.showMore', { count: moreCount }) }}
+      </button>
+    </template>
+  </div>
+</template>
+
+<style scoped>
+.wg { padding: 4px 0; }
+.wg + .wg { border-top: 1px solid var(--line); }
+.wg-head {
+  display: flex;
+  align-items: center;
+  gap: 7px;
+  padding: 7px var(--sb-pad-x, 12px) 4px;
+  min-width: 0;
+  cursor: pointer;
+}
+.wg-head:hover { background: var(--panel2); }
+/* Left cluster (repo › branch [badge]): grows to fill the header so the branch
+   can use every pixel not taken by the right-side buttons — keeping branch
+   names as fully visible as the sidebar width allows. The repo name is capped
+   and shrinks first, since the branch is the key label in this view. */
+.wg-label {
+  display: flex;
+  align-items: center;
+  gap: 7px;
+  flex: 1 1 auto;
+  min-width: 0;
+}
+.repo {
+  flex: 0 1 auto;
+  max-width: 40%;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  color: var(--ink);
+  font-weight: 500;
+  font-size: var(--ui-font-size-sm);
+  font-family: var(--mono);
+}
+.sep {
+  flex: none;
+  color: var(--faint);
+  font-size: var(--ui-font-size-sm);
+}
+.br {
+  flex: 1 1 auto;
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  color: var(--c);
+  font-weight: 600;
+  font-size: var(--ui-font-size-sm);
+  font-family: var(--mono);
+}
+.badge {
+  flex: none;
+  font-size: var(--ui-font-size-xs);
+  color: var(--faint);
+  border: 1px solid var(--line);
+  border-radius: 8px;
+  padding: 0 5px;
+  line-height: 14px;
+}
+.attn {
+  flex: none;
+  width: 7px;
+  height: 7px;
+  border-radius: 50%;
+}
+.attn-running {
+  background: var(--ok);
+  box-shadow: 0 0 0 3px color-mix(in srgb, var(--ok) 18%, transparent);
+}
+.attn-pending {
+  background: var(--warn);
+  box-shadow: 0 0 0 3px color-mix(in srgb, var(--warn) 18%, transparent);
+}
+.complete-btn {
+  display: none;
+  flex: none;
+  background: none;
+  border: 1px solid var(--line);
+  border-radius: 6px;
+  color: var(--muted);
+  font-family: var(--mono);
+  font-size: var(--ui-font-size-xs);
+  padding: 0 7px;
+  line-height: 14px;
+  cursor: pointer;
+}
+.wg-head:hover .complete-btn { display: inline-flex; }
+.complete-btn:hover { color: var(--err); border-color: var(--err); }
+.new-session-btn {
+  display: none;
+  flex: none;
+  background: none;
+  border: 1px dashed var(--line);
+  border-radius: 6px;
+  color: var(--muted);
+  font-family: var(--mono);
+  font-size: var(--ui-font-size-xs);
+  padding: 0 7px;
+  line-height: 14px;
+  cursor: pointer;
+}
+/* Show on hover for populated groups; always show for empty worktrees so a
+   freshly-created checkout advertises how to start a session in it. */
+.wg-head:hover .new-session-btn,
+.wg.is-empty .new-session-btn { display: inline-flex; }
+.new-session-btn:hover { color: var(--blue); border-color: var(--blue); }
+.open-in-wrap {
+  display: none;
+  flex: none;
+  align-items: center;
+}
+.wg-head:hover .open-in-wrap,
+.wg.is-empty .open-in-wrap { display: inline-flex; }
+.pr {
+  flex: none;
+  border: 1px solid transparent;
+  border-radius: 9px;
+  padding: 0 6px;
+  height: 18px;
+  line-height: 16px;
+  font-size: 12px;
+  background: transparent;
+  cursor: pointer;
+  font-family: var(--mono);
+}
+.pr-open { color: var(--ok); border-color: color-mix(in srgb, var(--ok) 38%, var(--bg)); }
+.pr-merged { color: #8957e5; border-color: color-mix(in srgb, #8957e5 38%, var(--bg)); }
+.pr-closed { color: var(--err); border-color: color-mix(in srgb, var(--err) 38%, var(--bg)); }
+
+.show-more {
+  display: block;
+  width: 100%;
+  padding: 5px 10px 6px calc(var(--sb-pad-x, 12px) + 30px);
+  background: none;
+  border: none;
+  color: var(--dim);
+  font-size: calc(var(--ui-font-size) - 1.5px);
+  font-family: var(--mono);
+  cursor: pointer;
+  text-align: left;
+}
+.show-more:hover { color: var(--blue2); background: var(--soft); }
+</style>
diff --git a/apps/kimi-web/src/components/chat/OpenInMenu.vue b/apps/kimi-web/src/components/chat/OpenInMenu.vue
index d210a8616..3e61aa1fd 100644
--- a/apps/kimi-web/src/components/chat/OpenInMenu.vue
+++ b/apps/kimi-web/src/components/chat/OpenInMenu.vue
@@ -14,6 +14,8 @@ const props = defineProps<{
   workDir?: string;
   /** Installed app IDs from the daemon; when empty/unset the menu falls back to platform defaults. */
   availableApps?: string[];
+  /** Hide the path label and render only the quick-open + caret (for tight layouts). */
+  compact?: boolean;
 }>();
 
 const emit = defineEmits<{
@@ -175,6 +177,7 @@ async function copyPath(): Promise<void> {
 <template>
   <div v-if="isMac" class="open-group">
     <span
+      v-if="!compact"
       class="open-label"
       :class="{ muted: !hasWorkDir }"
       :title="workDir ?? ''"
diff --git a/apps/kimi-web/src/components/dialogs/NewWorktreeDialog.vue b/apps/kimi-web/src/components/dialogs/NewWorktreeDialog.vue
new file mode 100644
index 000000000..9f5f76dc3
--- /dev/null
+++ b/apps/kimi-web/src/components/dialogs/NewWorktreeDialog.vue
@@ -0,0 +1,249 @@
+<!-- apps/kimi-web/src/components/dialogs/NewWorktreeDialog.vue -->
+<!-- Quick-create a git worktree: pick a workspace, optionally name the branch,
+     then jump straight into a draft session in the new worktree. -->
+<script setup lang="ts">
+import { computed, ref, watch } from 'vue';
+import { useI18n } from 'vue-i18n';
+import type { WorkspaceView } from '../../types';
+
+const { t } = useI18n();
+
+const props = defineProps<{
+  workspaces: WorkspaceView[];
+  defaultWorkspaceId: string | null;
+  createWorktree: (
+    workspaceId: string,
+    input?: { branch?: string },
+  ) => Promise<{ path: string }>;
+}>();
+
+const emit = defineEmits<{
+  created: [workspaceId: string, path: string];
+  cancel: [];
+}>();
+
+const gitWorkspaces = computed(() =>
+  props.workspaces
+    .filter((w) => w.isGitRepo)
+    .toSorted((a, b) => (b.sessionCount - a.sessionCount) || a.name.localeCompare(b.name)),
+);
+const workspaceId = ref<string | null>(null);
+const branch = ref('');
+const loading = ref(false);
+const error = ref<string | null>(null);
+
+watch(
+  () => [props.defaultWorkspaceId, props.workspaces],
+  () => {
+    const list = gitWorkspaces.value;
+    // Preserve a manual selection as long as it still points to a valid
+    // workspace. `props.workspaces` recomputes continuously while a session is
+    // running, so re-syncing on every change would clobber the user's pick and
+    // pin the field back to the active session's workspace.
+    if (workspaceId.value !== null && list.some((w) => w.id === workspaceId.value)) {
+      return;
+    }
+    const def = props.defaultWorkspaceId;
+    workspaceId.value =
+      def !== null && list.some((w) => w.id === def) ? def : (list[0]?.id ?? null);
+  },
+  { immediate: true },
+);
+
+function onBackdrop(e: MouseEvent): void {
+  if (e.target === e.currentTarget && !loading.value) emit('cancel');
+}
+function onKeydown(e: KeyboardEvent): void {
+  if (e.key === 'Escape' && !loading.value) emit('cancel');
+}
+
+async function onCreate(): Promise<void> {
+  const wsId = workspaceId.value;
+  if (!wsId || loading.value) return;
+  loading.value = true;
+  error.value = null;
+  try {
+    const name = branch.value.trim();
+    const created = await props.createWorktree(wsId, name.length > 0 ? { branch: name } : undefined);
+    emit('created', wsId, created.path);
+  } catch (error_) {
+    error.value = error_ instanceof Error ? error_.message : String(error_);
+  } finally {
+    loading.value = false;
+  }
+}
+</script>
+
+<template>
+  <div class="backdrop" @mousedown="onBackdrop" @keydown="onKeydown" tabindex="-1">
+    <div class="dialog" role="dialog" :aria-label="t('worktree.newTitle')">
+      <div class="head">
+        <span class="title">{{ t('worktree.newTitle') }}</span>
+      </div>
+
+      <div class="body">
+        <div class="field">
+          <span class="label">{{ t('worktree.newWorkspace') }}</span>
+          <div class="ws-list">
+            <button
+              v-for="w in gitWorkspaces"
+              :key="w.id"
+              type="button"
+              class="ws-row"
+              :class="{ on: w.id === workspaceId }"
+              :disabled="loading"
+              @click="workspaceId = w.id"
+            >
+              <span class="ws-name">{{ w.name }}</span>
+              <span v-if="w.sessionCount > 0" class="ws-count">{{ w.sessionCount }}</span>
+              <span class="ws-path">{{ w.shortPath || w.root }}</span>
+            </button>
+            <div v-if="gitWorkspaces.length === 0" class="ws-empty">{{ t('worktree.noGitWorkspaces') }}</div>
+          </div>
+        </div>
+
+        <label class="field">
+          <span class="label">{{ t('worktree.branchPlaceholder') }}</span>
+          <input
+            v-model="branch"
+            class="input"
+            type="text"
+            :placeholder="t('worktree.newBranchHint')"
+            :disabled="loading"
+            @keydown.enter="onCreate"
+          />
+        </label>
+
+        <div v-if="error" class="err">{{ error }}</div>
+      </div>
+
+      <div class="foot">
+        <button class="btn-ghost" :disabled="loading" @click="emit('cancel')">{{ t('worktree.cancel') }}</button>
+        <button class="btn-primary" :disabled="loading || !workspaceId || gitWorkspaces.length === 0" @click="onCreate">
+          {{ loading ? t('worktree.creating') : t('worktree.create') }}
+        </button>
+      </div>
+    </div>
+  </div>
+</template>
+
+<style scoped>
+.backdrop {
+  position: fixed;
+  inset: 0;
+  background: rgba(0, 0, 0, 0.32);
+  display: flex;
+  align-items: flex-start;
+  justify-content: center;
+  padding-top: 14vh;
+  z-index: 120;
+  outline: none;
+}
+.dialog {
+  width: min(560px, 92vw);
+  background: var(--bg);
+  border: 1px solid var(--line);
+  border-radius: 10px;
+  box-shadow: 0 12px 40px rgba(0, 0, 0, 0.18);
+  font-family: var(--mono);
+  color: var(--ink);
+  overflow: hidden;
+}
+.head { padding: 14px 16px; border-bottom: 1px solid var(--line); }
+.title { font-size: var(--ui-font-size); font-weight: 600; }
+.body { padding: 14px 16px; display: flex; flex-direction: column; gap: 12px; }
+.field { display: flex; flex-direction: column; gap: 6px; }
+.label { font-size: var(--ui-font-size-xs); color: var(--muted); }
+.ws-list {
+  border: 1px solid var(--line);
+  border-radius: 8px;
+  max-height: 220px;
+  overflow-y: auto;
+  display: flex;
+  flex-direction: column;
+}
+.ws-row {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  width: 100%;
+  padding: 8px 11px;
+  background: transparent;
+  border: none;
+  border-bottom: 1px solid var(--line);
+  color: var(--text);
+  font-family: var(--mono);
+  text-align: left;
+  cursor: pointer;
+}
+.ws-row:last-child { border-bottom: none; }
+.ws-row:hover { background: var(--panel2); }
+.ws-row.on {
+  background: var(--soft);
+  box-shadow: inset 0 0 0 1px var(--bd);
+}
+.ws-row:disabled { opacity: 0.6; cursor: default; }
+.ws-name { color: var(--ink); font-weight: 500; font-size: var(--ui-font-size); flex: none; }
+.ws-count {
+  flex: none;
+  font-size: var(--ui-font-size-xs);
+  color: var(--faint);
+  border: 1px solid var(--line);
+  border-radius: 8px;
+  padding: 0 5px;
+  line-height: 16px;
+}
+.ws-path {
+  margin-left: auto;
+  color: var(--faint);
+  font-size: var(--ui-font-size-xs);
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  min-width: 0;
+}
+.ws-empty { padding: 14px 11px; color: var(--faint); font-size: var(--ui-font-size-xs); }
+.input {
+  font-family: var(--mono);
+  font-size: var(--ui-font-size);
+  color: var(--ink);
+  background: var(--bg);
+  border: 1px solid var(--line);
+  border-radius: 6px;
+  padding: 6px 8px;
+  outline: none;
+  width: 100%;
+}
+.input:focus { border-color: var(--blue); }
+.err { color: var(--err); font-size: var(--ui-font-size-xs); word-break: break-word; }
+.foot {
+  display: flex;
+  justify-content: flex-end;
+  gap: 8px;
+  padding: 12px 16px;
+  border-top: 1px solid var(--line);
+}
+.btn-ghost {
+  background: none;
+  border: 1px solid var(--line);
+  border-radius: 6px;
+  color: var(--dim);
+  font-family: var(--mono);
+  font-size: var(--ui-font-size);
+  padding: 6px 14px;
+  cursor: pointer;
+}
+.btn-ghost:hover { color: var(--ink); background: var(--panel2); }
+.btn-primary {
+  background: var(--blue);
+  color: #fff;
+  border: none;
+  border-radius: 6px;
+  font-family: var(--mono);
+  font-size: var(--ui-font-size);
+  padding: 6px 14px;
+  cursor: pointer;
+}
+.btn-primary:disabled { opacity: 0.6; cursor: default; }
+.btn-primary:not(:disabled):hover { background: var(--blue2); }
+</style>
diff --git a/apps/kimi-web/src/components/dialogs/WorktreeCompleteDialog.vue b/apps/kimi-web/src/components/dialogs/WorktreeCompleteDialog.vue
new file mode 100644
index 000000000..dfd8c2b9e
--- /dev/null
+++ b/apps/kimi-web/src/components/dialogs/WorktreeCompleteDialog.vue
@@ -0,0 +1,196 @@
+<!-- apps/kimi-web/src/components/dialogs/WorktreeCompleteDialog.vue -->
+<!-- Confirmation modal for "completing" a worktree: the daemon deletes the
+     worktree directory (git worktree remove), so this confirms a destructive
+     action and optionally deletes the branch too. -->
+<script setup lang="ts">
+import { ref, watch } from 'vue';
+import { useI18n } from 'vue-i18n';
+import type { CompleteWorktreeTarget } from '../../types';
+
+const { t } = useI18n();
+
+const props = defineProps<{
+  target: CompleteWorktreeTarget | null;
+  removeWorktree: (
+    workspaceId: string,
+    input: { path: string; force?: boolean; deleteBranch?: boolean },
+  ) => Promise<void>;
+}>();
+
+const emit = defineEmits<{
+  cancel: [];
+}>();
+
+const deleteBranch = ref(false);
+const loading = ref(false);
+const error = ref<string | null>(null);
+
+// Reset state whenever the target changes.
+watch(
+  () => props.target?.path,
+  () => {
+    deleteBranch.value = false;
+    loading.value = false;
+    error.value = null;
+  },
+);
+
+function onBackdrop(e: MouseEvent): void {
+  if (e.target === e.currentTarget && !loading.value) emit('cancel');
+}
+function onKeydown(e: KeyboardEvent): void {
+  if (e.key === 'Escape' && !loading.value) emit('cancel');
+}
+
+async function onConfirm(): Promise<void> {
+  const target = props.target;
+  if (!target || loading.value) return;
+  loading.value = true;
+  error.value = null;
+  try {
+    await props.removeWorktree(target.workspaceId, {
+      path: target.path,
+      force: target.dirty,
+      deleteBranch: deleteBranch.value,
+    });
+    emit('cancel');
+  } catch (error_) {
+    error.value = error_ instanceof Error ? error_.message : String(error_);
+  } finally {
+    loading.value = false;
+  }
+}
+</script>
+
+<template>
+  <div
+    v-if="target"
+    class="backdrop"
+    @mousedown="onBackdrop"
+    @keydown="onKeydown"
+    tabindex="-1"
+  >
+    <div class="dialog" role="dialog" :aria-label="t('worktree.completeTitle')">
+      <div class="head">
+        <span class="title">{{ t('worktree.completeTitle', { branch: target.branch || target.path }) }}</span>
+      </div>
+
+      <div class="body">
+        <p class="lead">{{ t('worktree.completeLead') }}</p>
+        <div class="path" :title="target.path">{{ target.path }}</div>
+
+        <div v-if="target.dirty" class="warn">
+          {{ t('worktree.completeDirty') }}
+        </div>
+        <div v-if="target.sessionCount > 0" class="note">
+          {{ t('worktree.completeSessions', { count: target.sessionCount }) }}
+        </div>
+
+        <label class="check">
+          <input v-model="deleteBranch" type="checkbox" :disabled="loading" />
+          <span>{{ t('worktree.completeDeleteBranch', { branch: target.branch }) }}</span>
+        </label>
+
+        <div v-if="error" class="err">{{ error }}</div>
+      </div>
+
+      <div class="foot">
+        <button class="btn-ghost" :disabled="loading" @click="emit('cancel')">{{ t('worktree.cancel') }}</button>
+        <button class="btn-danger" :disabled="loading" @click="onConfirm">
+          {{ loading ? t('worktree.completing') : t('worktree.completeConfirm') }}
+        </button>
+      </div>
+    </div>
+  </div>
+</template>
+
+<style scoped>
+.backdrop {
+  position: fixed;
+  inset: 0;
+  background: rgba(0, 0, 0, 0.32);
+  display: flex;
+  align-items: flex-start;
+  justify-content: center;
+  padding-top: 14vh;
+  z-index: 120;
+  outline: none;
+}
+.dialog {
+  width: min(460px, 92vw);
+  background: var(--bg);
+  border: 1px solid var(--line);
+  border-radius: 10px;
+  box-shadow: 0 12px 40px rgba(0, 0, 0, 0.18);
+  font-family: var(--mono);
+  color: var(--ink);
+  overflow: hidden;
+}
+.head {
+  padding: 14px 16px;
+  border-bottom: 1px solid var(--line);
+}
+.title { font-size: var(--ui-font-size); font-weight: 600; }
+.body { padding: 14px 16px; display: flex; flex-direction: column; gap: 10px; }
+.lead { margin: 0; color: var(--text); font-size: var(--ui-font-size); }
+.path {
+  font-size: var(--ui-font-size-xs);
+  color: var(--dim);
+  background: var(--panel2);
+  border: 1px solid var(--line);
+  border-radius: 6px;
+  padding: 6px 8px;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+.warn {
+  color: var(--warn);
+  font-size: var(--ui-font-size-xs);
+  background: color-mix(in srgb, var(--warn) 10%, var(--bg));
+  border: 1px solid color-mix(in srgb, var(--warn) 30%, var(--bg));
+  border-radius: 6px;
+  padding: 6px 8px;
+}
+.note { color: var(--muted); font-size: var(--ui-font-size-xs); }
+.err { color: var(--err); font-size: var(--ui-font-size-xs); word-break: break-word; }
+.check {
+  display: inline-flex;
+  align-items: center;
+  gap: 7px;
+  font-size: var(--ui-font-size-xs);
+  color: var(--text);
+  cursor: pointer;
+  margin-top: 2px;
+}
+.check input { margin: 0; }
+.foot {
+  display: flex;
+  justify-content: flex-end;
+  gap: 8px;
+  padding: 12px 16px;
+  border-top: 1px solid var(--line);
+}
+.btn-ghost {
+  background: none;
+  border: 1px solid var(--line);
+  border-radius: 6px;
+  color: var(--dim);
+  font-family: var(--mono);
+  font-size: var(--ui-font-size);
+  padding: 6px 14px;
+  cursor: pointer;
+}
+.btn-ghost:hover { color: var(--ink); background: var(--panel2); }
+.btn-danger {
+  background: var(--err);
+  color: #fff;
+  border: none;
+  border-radius: 6px;
+  font-family: var(--mono);
+  font-size: var(--ui-font-size);
+  padding: 6px 14px;
+  cursor: pointer;
+}
+.btn-danger:hover { opacity: 0.9; }
+</style>
diff --git a/apps/kimi-web/src/components/dialogs/WorktreeDialog.vue b/apps/kimi-web/src/components/dialogs/WorktreeDialog.vue
new file mode 100644
index 000000000..4685fcf35
--- /dev/null
+++ b/apps/kimi-web/src/components/dialogs/WorktreeDialog.vue
@@ -0,0 +1,433 @@
+<!-- apps/kimi-web/src/components/dialogs/WorktreeDialog.vue -->
+<!-- Manage git worktrees of a workspace: list, create, and remove worktrees, -->
+<!-- and jump into a session bound to each one. The parent owns the actual -->
+<!-- daemon calls + navigation; this dialog renders state and emits intents. -->
+<script setup lang="ts">
+import { computed, ref } from 'vue';
+import { useI18n } from 'vue-i18n';
+import type { AppWorktree } from '../../api/types';
+import type { Session, WorkspaceView } from '../../types';
+import { branchColor } from '../../lib/branchColor';
+
+const { t } = useI18n();
+
+const props = defineProps<{
+  workspace: WorkspaceView;
+  worktrees: AppWorktree[];
+  /** Sessions belonging to this workspace, used to resolve linked-session titles. */
+  sessions: Session[];
+  createWorktree: (
+    workspaceId: string,
+    input?: { branch?: string; baseRef?: string; path?: string },
+  ) => Promise<AppWorktree>;
+  removeWorktree: (
+    workspaceId: string,
+    input: { path: string; force?: boolean; deleteBranch?: boolean },
+  ) => Promise<void>;
+}>();
+
+const emit = defineEmits<{
+  close: [];
+  /** Open a (draft) session scoped to the given worktree path. */
+  openWorktree: [path: string];
+  /** Select an already-linked session. */
+  selectSession: [sessionId: string];
+  /** Open a PR URL (handled by the parent, consistent with ChatHeader). */
+  openPr: [url: string];
+}>();
+
+const branch = ref('');
+const creating = ref(false);
+const error = ref<string | null>(null);
+// Per-row remove state: path → 'confirming' (first click) | 'busy'.
+const removing = ref<Record<string, 'confirming' | 'busy'>>({});
+
+const sessionById = computed(() => {
+  const m = new Map<string, Session>();
+  for (const s of props.sessions) m.set(s.id, s);
+  return m;
+});
+
+const sorted = computed<AppWorktree[]>(() =>
+  [...props.worktrees].toSorted((a, b) => {
+    if (a.isMain !== b.isMain) return a.isMain ? -1 : 1;
+    return a.branch.localeCompare(b.branch);
+  }),
+);
+
+const secondary = computed(() => sorted.value.filter((w) => !w.isMain));
+
+function branchLabel(w: AppWorktree): string {
+  if (w.branch.length > 0) return w.branch;
+  if (w.head.length > 0) return w.head.slice(0, 7);
+  return t('worktree.detached');
+}
+
+function sessionTitle(sessionId: string | null): string | null {
+  if (sessionId === null) return null;
+  return sessionById.value.get(sessionId)?.title ?? null;
+}
+
+async function onCreate(): Promise<void> {
+  if (creating.value) return;
+  creating.value = true;
+  error.value = null;
+  try {
+    const name = branch.value.trim();
+    const created = await props.createWorktree(
+      props.workspace.id,
+      name.length > 0 ? { branch: name } : undefined,
+    );
+    branch.value = '';
+    emit('openWorktree', created.path);
+  } catch (error_) {
+    error.value = error_ instanceof Error ? error_.message : String(error_);
+  } finally {
+    creating.value = false;
+  }
+}
+
+async function onRemove(w: AppWorktree): Promise<void> {
+  const state = removing.value[w.path];
+  // First click asks for confirmation, especially when dirty or linked.
+  if (state !== 'confirming') {
+    removing.value = { ...removing.value, [w.path]: 'confirming' };
+    return;
+  }
+  removing.value = { ...removing.value, [w.path]: 'busy' };
+  error.value = null;
+  try {
+    await props.removeWorktree(props.workspace.id, { path: w.path, force: w.dirty });
+    const next = { ...removing.value };
+    delete next[w.path];
+    removing.value = next;
+  } catch (error_) {
+    error.value = error_ instanceof Error ? error_.message : String(error_);
+    removing.value = { ...removing.value, [w.path]: 'confirming' };
+  }
+}
+
+function cancelRemove(path: string): void {
+  const next = { ...removing.value };
+  delete next[path];
+  removing.value = next;
+}
+</script>
+
+<template>
+  <div class="backdrop" @click.self="emit('close')">
+    <div class="dialog" role="dialog" :aria-label="t('worktree.title')">
+      <div class="head">
+        <span class="title">{{ t('worktree.title') }}</span>
+        <span class="sub">{{ workspace.name }}</span>
+        <button class="x" :title="t('worktree.close')" @click="emit('close')">×</button>
+      </div>
+
+      <!-- Create -->
+      <div class="create">
+        <input
+          v-model="branch"
+          class="branch-input"
+          type="text"
+          :placeholder="t('worktree.branchPlaceholder')"
+          :disabled="creating"
+          @keydown.enter="onCreate"
+        />
+        <button class="btn-primary" :disabled="creating" @click="onCreate">
+          {{ creating ? t('worktree.creating') : t('worktree.create') }}
+        </button>
+      </div>
+      <div class="hint">{{ t('worktree.createHint') }}</div>
+
+      <div v-if="error" class="err">{{ error }}</div>
+
+      <!-- List -->
+      <div class="list">
+        <div v-if="sorted.length === 0" class="empty">{{ t('worktree.empty') }}</div>
+
+        <div
+          v-for="w in sorted"
+          :key="w.path"
+          class="row"
+          :class="{ main: w.isMain }"
+        >
+          <div class="row-top">
+            <span
+              class="br-dot"
+              :style="{ background: branchColor(branchLabel(w)) }"
+              :title="w.path"
+            />
+            <span class="br" :title="w.path">{{ branchLabel(w) }}</span>
+            <span v-if="w.isMain" class="badge">{{ t('worktree.main') }}</span>
+            <span
+              v-if="w.dirty"
+              class="badge badge-dirty"
+              :title="t('worktree.dirtyTitle')"
+            >{{ t('worktree.dirty') }}</span>
+            <span v-if="w.ahead > 0" class="delta">↑{{ w.ahead }}</span>
+            <span v-if="w.behind > 0" class="delta">↓{{ w.behind }}</span>
+
+            <button
+              v-if="w.pullRequest"
+              class="pr"
+              :class="`pr-${w.pullRequest.state}`"
+              :title="w.pullRequest.url"
+              @click="emit('openPr', w.pullRequest.url)"
+            >#{{ w.pullRequest.number }}</button>
+
+            <span class="spacer" />
+
+            <!-- Actions -->
+            <template v-if="removing[w.path] === 'confirming'">
+              <span class="confirm-label">{{ t('worktree.removeConfirm') }}</span>
+              <button class="btn-danger" @click="onRemove(w)">{{ t('worktree.confirm') }}</button>
+              <button class="btn-ghost" @click="cancelRemove(w.path)">{{ t('worktree.cancel') }}</button>
+            </template>
+            <template v-else>
+              <button
+                v-if="w.sessionId"
+                class="btn-ghost"
+                :title="sessionTitle(w.sessionId) ?? ''"
+                @click="emit('selectSession', w.sessionId!)"
+              >{{ t('worktree.openSession') }}</button>
+              <button
+                v-else-if="!w.isMain"
+                class="btn-ghost"
+                @click="emit('openWorktree', w.path)"
+              >{{ t('worktree.newSessionHere') }}</button>
+              <button
+                v-if="!w.isMain"
+                class="btn-ghost btn-del"
+                :disabled="removing[w.path] === 'busy'"
+                @click="onRemove(w)"
+              >{{ t('worktree.remove') }}</button>
+            </template>
+          </div>
+
+          <div v-if="sessionTitle(w.sessionId)" class="row-sub">
+            {{ t('worktree.linkedTo') }}: {{ sessionTitle(w.sessionId) }}
+          </div>
+        </div>
+      </div>
+
+      <div v-if="secondary.length === 0 && sorted.length > 0" class="foot">
+        {{ t('worktree.onlyMain') }}
+      </div>
+    </div>
+  </div>
+</template>
+
+<style scoped>
+.backdrop {
+  position: fixed;
+  inset: 0;
+  background: rgba(0, 0, 0, 0.32);
+  display: flex;
+  align-items: flex-start;
+  justify-content: center;
+  padding-top: 8vh;
+  z-index: 100;
+}
+.dialog {
+  width: min(620px, 92vw);
+  max-height: 80vh;
+  display: flex;
+  flex-direction: column;
+  background: var(--bg);
+  border: 1px solid var(--line);
+  border-radius: 8px;
+  box-shadow: 0 12px 40px rgba(0, 0, 0, 0.18);
+  font-family: var(--mono);
+  color: var(--ink);
+}
+.head {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  padding: 12px 14px;
+  border-bottom: 1px solid var(--line);
+}
+.title {
+  font-size: var(--ui-font-size);
+  font-weight: 600;
+}
+.sub {
+  color: var(--faint);
+  font-size: var(--ui-font-size-xs);
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+.x {
+  margin-left: auto;
+  background: none;
+  border: none;
+  color: var(--muted);
+  cursor: pointer;
+  font-size: 18px;
+  line-height: 1;
+  padding: 2px 6px;
+  border-radius: 4px;
+}
+.x:hover { color: var(--ink); background: var(--panel2); }
+
+.create {
+  display: flex;
+  gap: 8px;
+  padding: 12px 14px 4px;
+}
+.branch-input {
+  flex: 1;
+  min-width: 0;
+  font-family: var(--mono);
+  font-size: var(--ui-font-size);
+  color: var(--ink);
+  background: var(--bg);
+  border: 1px solid var(--line);
+  border-radius: 4px;
+  padding: 5px 8px;
+  outline: none;
+}
+.branch-input:focus { border-color: var(--blue); }
+.btn-primary {
+  background: var(--blue);
+  color: #fff;
+  border: none;
+  border-radius: 4px;
+  padding: 5px 12px;
+  font-family: var(--mono);
+  font-size: var(--ui-font-size);
+  cursor: pointer;
+  white-space: nowrap;
+}
+.btn-primary:disabled { opacity: 0.6; cursor: default; }
+.btn-primary:not(:disabled):hover { opacity: 0.9; }
+
+.hint {
+  padding: 2px 14px 8px;
+  color: var(--faint);
+  font-size: var(--ui-font-size-xs);
+}
+.err {
+  margin: 0 14px 8px;
+  color: var(--err);
+  font-size: var(--ui-font-size-xs);
+  word-break: break-word;
+}
+
+.list {
+  overflow-y: auto;
+  padding: 4px 14px 12px;
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+}
+.empty {
+  color: var(--faint);
+  font-size: var(--ui-font-size-xs);
+  padding: 12px 0;
+}
+.row {
+  border: 1px solid var(--line);
+  border-radius: 6px;
+  padding: 7px 9px;
+}
+.row.main { background: var(--soft); }
+.row-top {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  min-width: 0;
+}
+.br-dot {
+  flex: none;
+  width: 8px;
+  height: 8px;
+  border-radius: 50%;
+}
+.br {
+  font-size: var(--ui-font-size);
+  font-weight: 500;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  max-width: 38%;
+}
+.badge {
+  flex: none;
+  font-size: var(--ui-font-size-xs);
+  color: var(--muted);
+  border: 1px solid var(--line);
+  border-radius: 8px;
+  padding: 0 6px;
+  line-height: 16px;
+}
+.badge-dirty {
+  color: var(--warn);
+  border-color: color-mix(in srgb, var(--warn) 38%, var(--bg));
+}
+.delta {
+  flex: none;
+  color: var(--faint);
+  font-size: var(--ui-font-size-xs);
+}
+.pr {
+  flex: none;
+  border: 1px solid transparent;
+  border-radius: 8px;
+  padding: 0 6px;
+  line-height: 16px;
+  font-family: var(--mono);
+  font-size: var(--ui-font-size-xs);
+  cursor: pointer;
+  background: transparent;
+}
+.pr-open { color: var(--ok); border-color: color-mix(in srgb, var(--ok) 38%, var(--bg)); }
+.pr-merged { color: #8957e5; border-color: color-mix(in srgb, #8957e5 38%, var(--bg)); }
+.pr-closed { color: var(--err); border-color: color-mix(in srgb, var(--err) 38%, var(--bg)); }
+.spacer { flex: 1; }
+
+.btn-ghost {
+  flex: none;
+  background: none;
+  border: 1px solid var(--line);
+  border-radius: 4px;
+  color: var(--dim);
+  font-family: var(--mono);
+  font-size: var(--ui-font-size-xs);
+  padding: 2px 8px;
+  cursor: pointer;
+  white-space: nowrap;
+}
+.btn-ghost:hover { color: var(--ink); background: var(--panel2); }
+.btn-ghost:disabled { opacity: 0.6; cursor: default; }
+.btn-del:hover { color: var(--err); }
+.btn-danger {
+  flex: none;
+  background: var(--err);
+  color: var(--bg);
+  border: none;
+  border-radius: 4px;
+  font-family: var(--mono);
+  font-size: var(--ui-font-size-xs);
+  padding: 2px 8px;
+  cursor: pointer;
+}
+.confirm-label {
+  color: var(--err);
+  font-size: var(--ui-font-size-xs);
+}
+.row-sub {
+  margin-top: 4px;
+  color: var(--faint);
+  font-size: var(--ui-font-size-xs);
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+.foot {
+  padding: 0 14px 12px;
+  color: var(--faint);
+  font-size: var(--ui-font-size-xs);
+}
+</style>
diff --git a/apps/kimi-web/src/composables/client/useWorkspaceState.ts b/apps/kimi-web/src/composables/client/useWorkspaceState.ts
index 89a7137a2..3bab31e08 100644
--- a/apps/kimi-web/src/composables/client/useWorkspaceState.ts
+++ b/apps/kimi-web/src/composables/client/useWorkspaceState.ts
@@ -480,11 +480,31 @@ export function useWorkspaceState(rawState: ExtendedState, deps: UseWorkspaceSta
 
   /** Enter the "new session draft" state for a workspace: select it, clear the
    *  active session, and show the onboarding composer. No backend session is
-   *  created until the user sends the first message. */
-  function openWorkspaceDraft(workspaceId: string): void {
+   *  created until the user sends the first message. When `cwd` is provided
+   *  (e.g. a worktree path), the next session created in this workspace uses
+   *  it as its working directory instead of the workspace root. */
+  function openWorkspaceDraft(workspaceId: string, cwd?: string): void {
     selectWorkspace(workspaceId);
     clearActiveSession();
     clearFileDiff();
+    if (cwd !== undefined && cwd.length > 0) {
+      rawState.draftCwdByWorkspace = { ...rawState.draftCwdByWorkspace, [workspaceId]: cwd };
+    } else if (workspaceId in rawState.draftCwdByWorkspace) {
+      const next = { ...rawState.draftCwdByWorkspace };
+      delete next[workspaceId];
+      rawState.draftCwdByWorkspace = next;
+    }
+  }
+
+  /** Consume (and clear) any pending draft cwd for a workspace. Returns
+   *  undefined when none is pending, so callers fall back to the root. */
+  function takeDraftCwd(workspaceId: string): string | undefined {
+    const cwd = rawState.draftCwdByWorkspace[workspaceId];
+    if (cwd === undefined) return undefined;
+    const next = { ...rawState.draftCwdByWorkspace };
+    delete next[workspaceId];
+    rawState.draftCwdByWorkspace = next;
+    return cwd;
   }
 
   /**
@@ -497,21 +517,34 @@ export function useWorkspaceState(rawState: ExtendedState, deps: UseWorkspaceSta
     if (!ws) return undefined;
     try {
       const api = getKimiWebApi();
+      const draftCwd = takeDraftCwd(workspaceId);
       let workspaceIdForCreate: string | undefined;
-      let cwdForCreate = ws.root;
-      try {
-        const registered = await api.addWorkspace({ root: ws.root });
-        workspaceIdForCreate = registered.id;
-        cwdForCreate = registered.root;
-        upsertWorkspacePreserveOrder(registered);
-      } catch {
-        // Older daemons may not have /workspaces. In that mode, sending a local
-        // path-like workspace id as workspace_id would fail validation, so use
-        // metadata.cwd only.
+      let cwdForCreate: string;
+      if (draftCwd !== undefined) {
+        // Worktree session: the daemon ties workspace_id to cwd, so send cwd
+        // only and let it derive the workspace. The UI folds the session back
+        // under this launching workspace (see owningWorkspaceRoot).
+        cwdForCreate = draftCwd;
+      } else {
+        cwdForCreate = ws.root;
+        try {
+          const registered = await api.addWorkspace({ root: ws.root });
+          workspaceIdForCreate = registered.id;
+          cwdForCreate = registered.root;
+          upsertWorkspacePreserveOrder(registered);
+        } catch {
+          // Older daemons may not have /workspaces. In that mode, sending a
+          // local path-like workspace id as workspace_id would fail validation,
+          // so use metadata.cwd only.
+        }
       }
       const session = await api.createSession({ workspaceId: workspaceIdForCreate, cwd: cwdForCreate });
       upsertSessionFront(session);
-      selectWorkspace(session.workspaceId ?? workspaceIdForCreate ?? workspaceId);
+      selectWorkspace(
+        draftCwd !== undefined
+          ? workspaceId
+          : (session.workspaceId ?? workspaceIdForCreate ?? workspaceId),
+      );
       // Locally created sessions start empty; trust that so the empty-composer
       // renders immediately instead of flashing a loading state.
       sessionsKnownEmpty.add(session.id);
@@ -537,15 +570,22 @@ export function useWorkspaceState(rawState: ExtendedState, deps: UseWorkspaceSta
     if (!ws) return;
     try {
       const api = getKimiWebApi();
+      const draftCwd = takeDraftCwd(workspaceId);
       let workspaceIdForCreate: string | undefined;
-      let cwdForCreate = ws.root;
-      try {
-        const registered = await api.addWorkspace({ root: ws.root });
-        workspaceIdForCreate = registered.id;
-        cwdForCreate = registered.root;
-        upsertWorkspacePreserveOrder(registered);
-      } catch {
-        // Older daemons may not have /workspaces.
+      let cwdForCreate: string;
+      if (draftCwd !== undefined) {
+        // Worktree session: send cwd only (see createSessionInWorkspace).
+        cwdForCreate = draftCwd;
+      } else {
+        cwdForCreate = ws.root;
+        try {
+          const registered = await api.addWorkspace({ root: ws.root });
+          workspaceIdForCreate = registered.id;
+          cwdForCreate = registered.root;
+          upsertWorkspacePreserveOrder(registered);
+        } catch {
+          // Older daemons may not have /workspaces.
+        }
       }
       const draftPick = modelProvider.draftModel.value ?? undefined;
       const session = await api.createSession({
@@ -561,7 +601,11 @@ export function useWorkspaceState(rawState: ExtendedState, deps: UseWorkspaceSta
           ? { ...session, model: draftPick }
           : session;
       upsertSessionFront(created);
-      selectWorkspace(session.workspaceId ?? workspaceIdForCreate ?? workspaceId);
+      selectWorkspace(
+        draftCwd !== undefined
+          ? workspaceId
+          : (session.workspaceId ?? workspaceIdForCreate ?? workspaceId),
+      );
       // NOTE: do NOT mark this session known-empty. Unlike "open a new empty
       // session" (createSession), here we immediately send a prompt: keeping
       // sessionLoading=true through the snapshot avoids flashing the empty-session
diff --git a/apps/kimi-web/src/composables/useKimiWebClient.ts b/apps/kimi-web/src/composables/useKimiWebClient.ts
index 9f519dc65..b0b0179c6 100644
--- a/apps/kimi-web/src/composables/useKimiWebClient.ts
+++ b/apps/kimi-web/src/composables/useKimiWebClient.ts
@@ -7,6 +7,8 @@ import { i18n } from '../i18n';
 import { getKimiWebApi } from '../api';
 import { isDaemonApiError, isDaemonNetworkError } from '../api/errors';
 import { reconcileWorkspaceOrder, sortByWorkspaceOrder } from '../lib/workspaceOrder';
+import { mergeWorktreeGroups } from '../lib/worktreeGroups';
+import { createCoalescedAsyncRunner } from '../lib/snapshotSync';
 import {
   loadUnread,
   loadWorkspaceOrder,
@@ -42,6 +44,7 @@ import type {
   AppTask,
   AppWarning,
   AppWorkspace,
+  AppWorktree,
   ApprovalDecision,
   KimiEventConnection,
   ThinkingLevel,
@@ -72,6 +75,7 @@ import type {
   Workspace,
   WorkspaceGroup,
   WorkspaceView,
+  WorktreeGroup,
 } from '../types';
 
 // ---------------------------------------------------------------------------
@@ -295,6 +299,11 @@ export interface ExtendedState extends KimiClientState {
   activeWorkspaceId: string | null;
   fsHome: string | null;
   recentRoots: string[];
+  /** Git worktrees per workspace id, loaded on demand for the worktree panel. */
+  worktreesByWorkspace: Record<string, AppWorktree[]>;
+  /** Pending draft cwd for a workspace (e.g. a just-created worktree path).
+   *  Consumed by the next session created in that workspace, then cleared. */
+  draftCwdByWorkspace: Record<string, string>;
   // Root paths the user removed from the sidebar (see HIDDEN_WORKSPACES_KEY).
   hiddenWorkspaceRoots: string[];
   /** Installed external apps that can be used with "Open in app". */
@@ -340,6 +349,8 @@ const rawState: ExtendedState = reactive({
   activeWorkspaceId: loadActiveWorkspaceFromStorage(),
   fsHome: null,
   recentRoots: [],
+  worktreesByWorkspace: {},
+  draftCwdByWorkspace: {},
   hiddenWorkspaceRoots: loadHiddenWorkspacesFromStorage(),
   availableOpenInApps: [],
   config: null,
@@ -685,6 +696,13 @@ function connectEventsIfNeeded(): void {
         return;
       }
 
+      // Worktree lifecycle events are global too — refresh that workspace's
+      // worktree list so the panel stays in sync across clients.
+      if (appEvent.type === 'worktreeChanged') {
+        void loadWorktrees(appEvent.workspaceId, { silent: true });
+        return;
+      }
+
       // meta carries wire-level seq/sessionId so the reducer can advance
       // lastSeqBySession[sessionId] = seq. Compaction completion appends a
       // persistent divider marker in the reducer (TUI parity: the scrollback
@@ -747,7 +765,7 @@ function connectEventsIfNeeded(): void {
       // returns the authoritative {asOfSeq, epoch} and re-subscribes.
       if (epoch !== undefined) epochBySession[sessionId] = epoch;
       void currentSeq;
-      void syncSessionFromSnapshot(sessionId);
+      snapshotSyncRunner.request(sessionId);
     },
 
     onError(_code: number, msg: string, _fatal: boolean) {
@@ -1009,6 +1027,8 @@ async function syncSessionFromSnapshot(sessionId: string): Promise<SyncSessionRe
   }
 }
 
+const snapshotSyncRunner = createCoalescedAsyncRunner(syncSessionFromSnapshot);
+
 function hasLoadedMessages(sessionId: string): boolean {
   return Object.prototype.hasOwnProperty.call(rawState.messagesBySession, sessionId);
 }
@@ -1621,13 +1641,30 @@ const changesByPath = computed<Record<string, string>>(() => {
 // Workspace view-model
 // ---------------------------------------------------------------------------
 
+/**
+ * Map a session cwd to the workspace root that "owns" it. A worktree checkout
+ * lives at `<root>/.worktrees/<branch>`; such a cwd is owned by the main
+ * workspace root, so its sessions group under the main workspace instead of
+ * spawning a separate derived workspace. Returns the cwd unchanged when no
+ * registered workspace owns it.
+ */
+function owningWorkspaceRoot(cwd: string): string {
+  for (const w of rawState.workspaces) {
+    if (cwd === w.root) return w.root;
+    const prefix = w.root.replace(/\/+$/, '') + '/.worktrees/';
+    if (cwd.startsWith(prefix)) return w.root;
+  }
+  return cwd;
+}
+
 /**
  * The workspace id a session belongs to: prefer the daemon-provided
  * session.workspaceId; otherwise map by cwd (in derived/fallback mode the
  * workspace id IS the cwd).
  */
 function workspaceIdForSession(s: { workspaceId?: string; cwd: string }): string {
-  return rawState.workspaces.find((w) => w.root === s.cwd)?.id ?? s.workspaceId ?? s.cwd;
+  const root = owningWorkspaceRoot(s.cwd);
+  return rawState.workspaces.find((w) => w.root === root)?.id ?? s.workspaceId ?? s.cwd;
 }
 
 /**
@@ -1644,9 +1681,10 @@ const mergedWorkspaces = computed<AppWorkspace[]>(() => {
     if (hidden.has(w.root)) continue;
     byRoot.set(w.root, { ...w });
   }
-  // Derive from sessions for any cwd without a real workspace.
+  // Derive from sessions for any cwd without a real workspace. Worktree cwds
+  // fold into their owning workspace root so they don't spawn a separate group.
   for (const s of rawState.sessions) {
-    const root = s.cwd;
+    const root = owningWorkspaceRoot(s.cwd);
     if (!root) continue;
     if (hidden.has(root)) continue; // removed from the sidebar — keep it hidden
     if (!byRoot.has(root)) {
@@ -1735,6 +1773,7 @@ const workspacesView = computed<WorkspaceView[]>(() => {
     root: w.root,
     shortPath: shortenHome(w.root, rawState.fsHome),
     branch: w.branch,
+    isGitRepo: w.isGitRepo,
     sessionCount: w.sessionCount,
   }));
   return sortByWorkspaceOrder(views, workspaceOrder.value);
@@ -1757,8 +1796,25 @@ const visibleWorkspace = computed<WorkspaceView | null>(() => {
   return workspacesView.value.find((w) => w.id === id) ?? null;
 });
 
+/** Build a sidebar Session view from an AppSession, enriching it with the
+ *  cached git status (branch + PR) when available. */
+function toSessionView(s: AppSession): Session {
+  const g = rawState.gitStatusBySession[s.id];
+  return {
+    id: s.id,
+    title: s.title,
+    time: formatTime(s.updatedAt, s.status),
+    status: s.status,
+    busy: isSessionEffectivelyRunning(s.id),
+    updatedAt: s.updatedAt,
+    lastPrompt: s.lastPrompt,
+    branch: g?.branch && g.branch.length > 0 ? g.branch : undefined,
+    pullRequest: g?.pullRequest,
+  };
+}
+
 /**
- * All sessions for the sidebar (grouped by workspace via workspaceGroups).
+ * All sessions for the sidebar (flat list used by search / mobile switcher).
  */
 const sessionsForView = computed<Session[]>(() => {
   void sessionTimeClock.value;
@@ -1769,14 +1825,7 @@ const sessionsForView = computed<Session[]>(() => {
   // and sidebar search can't resurrect sessions from a removed workspace.
   return rawState.sessions
     .filter((s) => !s.parentSessionId && visibleWorkspaceIds.has(workspaceIdForSession(s)))
-    .map((s) => ({
-      id: s.id,
-      title: s.title,
-      time: formatTime(s.updatedAt, s.status),
-      status: s.status,
-      busy: isSessionEffectivelyRunning(s.id),
-      lastPrompt: s.lastPrompt,
-    }));
+    .map(toSessionView);
 });
 
 /** Per-workspace groups for the 'all workspaces' scope. */
@@ -1788,16 +1837,8 @@ const workspaceGroups = computed<WorkspaceGroup[]>(() => {
   )) {
     if (s.parentSessionId) continue; // child sessions stay out of the list
     const wid = workspaceIdForSession(s);
-    const view: Session = {
-      id: s.id,
-      title: s.title,
-      time: formatTime(s.updatedAt, s.status),
-      status: s.status,
-      busy: isSessionEffectivelyRunning(s.id),
-      updatedAt: s.updatedAt,
-    };
     const list = byId.get(wid) ?? [];
-    list.push(view);
+    list.push(toSessionView(s));
     byId.set(wid, list);
   }
   return workspacesView.value.map((w) => ({
@@ -1816,6 +1857,89 @@ function reorderWorkspaces(ids: string[]): void {
   saveWorkspaceOrder(ids);
 }
 
+/**
+ * Worktree-centric groups for the sidebar. Sessions are grouped by
+ * (workspace + branch) — each group is one worktree checkout of a repo — then
+ * merged with the workspace's known git worktrees so empty checkouts still show
+ * up. Groups are sorted so those with running / awaiting-input sessions float
+ * to the top, then by most recent activity. Sessions whose branch isn't known
+ * yet (git status still loading) fall into a per-workspace "pending" group.
+ */
+const worktreeGroups = computed<WorktreeGroup[]>(() => {
+  void sessionTimeClock.value;
+  const wsById = new Map(workspacesView.value.map((w) => [w.id, w]));
+  const visibleWorkspaceIds = new Set(workspacesView.value.map((w) => w.id));
+  const byKey = new Map<
+    string,
+    { ws: WorkspaceView | undefined; branch: string; sessions: Session[]; cwd: string; dirty: boolean }
+  >();
+  for (const s of rawState.sessions) {
+    if (s.parentSessionId) continue;
+    const wid = workspaceIdForSession(s);
+    if (!visibleWorkspaceIds.has(wid)) continue;
+    const g = rawState.gitStatusBySession[s.id];
+    const branch = g?.branch && g.branch.length > 0 ? g.branch : '';
+    const key = `${wid}:${branch}`;
+    let entry = byKey.get(key);
+    if (entry === undefined) {
+      entry = { ws: wsById.get(wid), branch, sessions: [], cwd: s.cwd, dirty: false };
+      byKey.set(key, entry);
+    }
+    entry.sessions.push(toSessionView(s));
+    if (g !== undefined && Object.keys(g.entries).length > 0) entry.dirty = true;
+  }
+  const groups: WorktreeGroup[] = [];
+  for (const [key, entry] of byKey) {
+    const ws = entry.ws;
+    const sessions = entry.sessions.toSorted(
+      (a, b) => new Date(b.updatedAt ?? 0).getTime() - new Date(a.updatedAt ?? 0).getTime(),
+    );
+    const hasRunning = sessions.some((s) => s.busy);
+    const hasPending = sessions.some(
+      (s) => s.status === 'awaitingApproval' || s.status === 'awaitingQuestion',
+    );
+    const latestAt = sessions.reduce(
+      (m, s) => Math.max(m, s.updatedAt ? new Date(s.updatedAt).getTime() : 0),
+      0,
+    );
+    const pullRequest =
+      sessions.find((s) => s.pullRequest !== null && s.pullRequest !== undefined)?.pullRequest ?? null;
+    groups.push({
+      key,
+      workspaceId: ws?.id ?? '',
+      workspaceName: ws?.name ?? '',
+      branch: entry.branch,
+      isMain: entry.branch !== '' && ws?.branch === entry.branch,
+      path: entry.cwd,
+      dirty: entry.dirty,
+      pullRequest,
+      sessions,
+      hasRunning,
+      hasPending,
+      latestAt,
+    });
+  }
+  // Merge in known git worktrees so checkouts without any sessions still show
+  // up in the sidebar (and can be opened) instead of only appearing on the
+  // board. Done before sorting so empty groups land in the idle/recency order.
+  const merged = mergeWorktreeGroups(groups, workspacesView.value, rawState.worktreesByWorkspace);
+  // Sort active groups first, then by recency bucketed into 30s windows, then
+  // by stable key. The bucket keeps two actively-updating groups from swapping
+  // back and forth on every new message (sub-30s changes land in the same
+  // bucket and fall through to the stable key order).
+  const BUCKET_MS = 30_000;
+  merged.sort((a, b) => {
+    const aa = a.hasRunning || a.hasPending ? 1 : 0;
+    const bb = b.hasRunning || b.hasPending ? 1 : 0;
+    if (aa !== bb) return bb - aa;
+    const ba = Math.floor(b.latestAt / BUCKET_MS);
+    const bk = Math.floor(a.latestAt / BUCKET_MS);
+    if (ba !== bk) return ba - bk;
+    return a.key.localeCompare(b.key);
+  });
+  return merged;
+});
+
 /**
  * Per-session pending-attention count = pending approvals + pending questions.
  * For the active session this is live (driven by WS events). Other sessions
@@ -2006,6 +2130,140 @@ function onSessionIdle(sid: string, status: 'idle' | 'aborted'): void {
   }
 }
 
+// ---------------------------------------------------------------------------
+// Worktrees — git worktrees of a workspace repository. State lives in
+// rawState.worktreesByWorkspace and is loaded on demand for the panel; a
+// background refresh runs when the daemon broadcasts worktree.changed.
+// ---------------------------------------------------------------------------
+
+const worktreesByWorkspace = computed(() => rawState.worktreesByWorkspace);
+
+async function loadWorktrees(
+  workspaceId: string,
+  opts?: { silent?: boolean },
+): Promise<AppWorktree[]> {
+  try {
+    const api = getKimiWebApi();
+    const items = await api.listWorktrees(workspaceId);
+    rawState.worktreesByWorkspace = {
+      ...rawState.worktreesByWorkspace,
+      [workspaceId]: items,
+    };
+    return items;
+  } catch (error) {
+    if (opts?.silent === true) return rawState.worktreesByWorkspace[workspaceId] ?? [];
+    throw error;
+  }
+}
+
+async function createWorktree(
+  workspaceId: string,
+  input?: { branch?: string; baseRef?: string; path?: string },
+): Promise<AppWorktree> {
+  const api = getKimiWebApi();
+  const created = await api.createWorktree(workspaceId, input);
+  // Re-list so enrichment (session correlation, dirty, PR) is authoritative.
+  void loadWorktrees(workspaceId, { silent: true });
+  return created;
+}
+
+async function removeWorktree(
+  workspaceId: string,
+  input: { path: string; force?: boolean; deleteBranch?: boolean },
+): Promise<void> {
+  const api = getKimiWebApi();
+  await api.removeWorktree(workspaceId, input);
+  const next = (rawState.worktreesByWorkspace[workspaceId] ?? []).filter(
+    (w) => w.path !== input.path,
+  );
+  rawState.worktreesByWorkspace = { ...rawState.worktreesByWorkspace, [workspaceId]: next };
+}
+
+async function openWorktreeInApp(
+  workspaceId: string,
+  appId: string,
+  path: string,
+): Promise<void> {
+  try {
+    await getKimiWebApi().openWorktreeInApp(workspaceId, appId, path);
+  } catch (err) {
+    pushOperationFailure('openWorktreeInApp', err);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Git status for listed sessions — the sidebar rows show branch + PR chips,
+// but git status is only fetched for the active session by default. Load it
+// (once, cached) for every session currently listed so the chips populate.
+// Concurrency is bounded to avoid stampeding the daemon.
+// ---------------------------------------------------------------------------
+
+const GIT_STATUS_CONCURRENCY = 4;
+
+async function loadGitStatusForSessions(ids: string[]): Promise<void> {
+  const pending = Array.from(new Set(ids)).filter(
+    (id) => !(id in rawState.gitStatusBySession),
+  );
+  if (pending.length === 0) return;
+  const queue = [...pending];
+  const worker = async (): Promise<void> => {
+    for (;;) {
+      const id = queue.shift();
+      if (id === undefined) return;
+      try {
+        const result = await getKimiWebApi().getGitStatus(id);
+        rawState.gitStatusBySession = { ...rawState.gitStatusBySession, [id]: result };
+      } catch {
+        // Stale / non-git sessions may fail — leave uncached, no crash.
+      }
+    }
+  };
+  await Promise.all(
+    Array.from({ length: Math.min(GIT_STATUS_CONCURRENCY, queue.length) }, worker),
+  );
+}
+
+const listedSessionIds = computed(() =>
+  workspaceGroups.value.flatMap((g) => g.sessions.map((s) => s.id)).join(','),
+);
+
+watch(
+  listedSessionIds,
+  () => {
+    const ids = workspaceGroups.value.flatMap((g) => g.sessions.map((s) => s.id));
+    void loadGitStatusForSessions(ids);
+  },
+  { immediate: true },
+);
+
+// Load git worktrees for every git workspace once (cached per workspace), so the
+// worktree-centric sidebar can show checkouts that have no sessions yet — not
+// just the ones already backing a session. Re-runs when the set of git
+// workspaces changes (e.g. a repo workspace is added).
+const loadedWorktreeWorkspaceIds = new Set<string>();
+const gitWorkspaceIdsKey = computed(() =>
+  workspacesView.value
+    .filter((w) => w.isGitRepo === true)
+    .map((w) => w.id)
+    .join(','),
+);
+
+watch(
+  gitWorkspaceIdsKey,
+  () => {
+    for (const w of workspacesView.value) {
+      if (w.isGitRepo !== true) continue;
+      if (loadedWorktreeWorkspaceIds.has(w.id)) continue;
+      loadedWorktreeWorkspaceIds.add(w.id);
+      void loadWorktrees(w.id, { silent: true }).catch(() => {
+        // Allow a retry on the next change if the load failed.
+        loadedWorktreeWorkspaceIds.delete(w.id);
+      });
+    }
+  },
+  { immediate: true },
+);
+
 // ---------------------------------------------------------------------------
 // Composable return
 // ---------------------------------------------------------------------------
@@ -2025,11 +2283,13 @@ export function useKimiWebClient() {
     activeWorkspaceId,
     sessionsForView,
     workspaceGroups,
+    worktreeGroups,
     attentionBySession,
     pendingBySession,
     attentionByWorkspace,
     unreadBySession,
     recentRoots,
+    worktreesByWorkspace,
 
     turns,
     tasks,
@@ -2117,6 +2377,10 @@ export function useKimiWebClient() {
     addWorkspaceByPath: workspaceState.addWorkspaceByPath,
     browseFs: workspaceState.browseFs,
     getFsHome: workspaceState.getFsHome,
+    loadWorktrees,
+    createWorktree,
+    removeWorktree,
+    openWorktreeInApp,
 
     sendPrompt: workspaceState.sendPrompt,
     steerPrompt: workspaceState.steerPrompt,
diff --git a/apps/kimi-web/src/i18n/locales/en/worktree.ts b/apps/kimi-web/src/i18n/locales/en/worktree.ts
new file mode 100644
index 000000000..9ed3e9fe2
--- /dev/null
+++ b/apps/kimi-web/src/i18n/locales/en/worktree.ts
@@ -0,0 +1,42 @@
+export default {
+  title: 'Worktrees',
+  boardTitle: 'Worktrees',
+  boardHint: 'All workspaces',
+  close: 'Close',
+  manage: 'Manage worktrees',
+  branchPlaceholder: 'Branch name (optional)',
+  create: 'New worktree',
+  newTitle: 'New worktree',
+  newWorkspace: 'Workspace',
+  newBranchHint: 'Branch name (optional, auto if empty)',
+  creating: 'Creating…',
+  createHint:
+    'Creates an isolated git worktree and opens a session in it. You may need to install dependencies and copy .env in the new checkout.',
+  empty: 'No worktrees yet.',
+  onlyMain: 'No linked worktrees yet — create one to isolate a session on its own branch.',
+  main: 'main',
+  live: 'A session is running in this worktree',
+  pending: 'A session is waiting for your input',
+  dirty: 'dirty',
+  clean: 'clean',
+  dirtyTitle: 'This worktree has uncommitted changes',
+  detached: 'detached',
+  loading: 'Loading worktrees…',
+  noSessions: 'No sessions yet',
+  noGitWorkspaces: 'No git workspaces yet. Add a git repository as a workspace first.',
+  removeConfirm: 'Remove?',
+  confirm: 'Confirm',
+  cancel: 'Cancel',
+  complete: 'Complete',
+  completeTitle: 'Complete worktree',
+  completeLead: 'This will delete the worktree directory:',
+  completeDirty: 'This worktree has uncommitted changes that will be lost.',
+  completeSessions: '{count} session(s) use this worktree; their history is kept.',
+  completeDeleteBranch: 'Also delete branch {branch}',
+  completeConfirm: 'Confirm complete',
+  completing: 'Completing…',
+  openSession: 'Open session',
+  newSessionHere: 'New session here',
+  remove: 'Remove',
+  linkedTo: 'Session',
+} as const;
diff --git a/apps/kimi-web/src/i18n/locales/index.ts b/apps/kimi-web/src/i18n/locales/index.ts
index 55842eb79..a86c23dc2 100644
--- a/apps/kimi-web/src/i18n/locales/index.ts
+++ b/apps/kimi-web/src/i18n/locales/index.ts
@@ -24,6 +24,7 @@ import en_tools from './en/tools';
 import en_layout from './en/layout';
 import en_mobile from './en/mobile';
 import en_theme from './en/theme';
+import en_worktree from './en/worktree';
 
 import zh_common from './zh/common';
 import zh_app from './zh/app';
@@ -51,6 +52,7 @@ import zh_tools from './zh/tools';
 import zh_layout from './zh/layout';
 import zh_mobile from './zh/mobile';
 import zh_theme from './zh/theme';
+import zh_worktree from './zh/worktree';
 import en_onboarding from './en/onboarding';
 import zh_onboarding from './zh/onboarding';
 import en_settings from './en/settings';
@@ -88,6 +90,7 @@ export const messages = {
     layout: en_layout,
     mobile: en_mobile,
     theme: en_theme,
+    worktree: en_worktree,
     onboarding: en_onboarding,
     settings: en_settings,
     header: en_header,
@@ -120,6 +123,7 @@ export const messages = {
     layout: zh_layout,
     mobile: zh_mobile,
     theme: zh_theme,
+    worktree: zh_worktree,
     onboarding: zh_onboarding,
     settings: zh_settings,
     header: zh_header,
diff --git a/apps/kimi-web/src/i18n/locales/zh/worktree.ts b/apps/kimi-web/src/i18n/locales/zh/worktree.ts
new file mode 100644
index 000000000..43e601b6e
--- /dev/null
+++ b/apps/kimi-web/src/i18n/locales/zh/worktree.ts
@@ -0,0 +1,41 @@
+export default {
+  title: 'Worktree 管理',
+  boardTitle: 'Worktree 看板',
+  boardHint: '全部 workspace',
+  close: '关闭',
+  manage: '管理 worktree',
+  branchPlaceholder: '分支名（可选）',
+  create: '新建 worktree',
+  newTitle: '新建 worktree',
+  newWorkspace: 'Workspace',
+  newBranchHint: '分支名（可选，留空自动命名）',
+  creating: '创建中…',
+  createHint: '创建一个独立的 git worktree 并在其中打开 session。新检出中可能需要重新安装依赖并复制 .env。',
+  empty: '暂无 worktree。',
+  onlyMain: '还没有关联的 worktree —— 创建一个可让 session 在独立分支上隔离开发。',
+  main: '主目录',
+  live: '该 worktree 有 session 运行中',
+  pending: '该 worktree 有 session 等待你的输入',
+  dirty: '有改动',
+  clean: '干净',
+  dirtyTitle: '该 worktree 有未提交的改动',
+  detached: '游离 HEAD',
+  loading: '正在加载 worktree…',
+  noSessions: '暂无 session',
+  noGitWorkspaces: '暂无 git workspace，请先添加一个 git 仓库作为 workspace。',
+  removeConfirm: '确认删除？',
+  confirm: '确认',
+  cancel: '取消',
+  complete: '完成',
+  completeTitle: '完成 worktree',
+  completeLead: '将删除该 worktree 目录：',
+  completeDirty: '该 worktree 有未提交的改动，将丢失。',
+  completeSessions: '{count} 个 session 使用该 worktree，对话历史会保留。',
+  completeDeleteBranch: '同时删除分支 {branch}',
+  completeConfirm: '确认完成',
+  completing: '完成中…',
+  openSession: '打开 session',
+  newSessionHere: '在此新建 session',
+  remove: '删除',
+  linkedTo: '关联 session',
+} as const;
diff --git a/apps/kimi-web/src/lib/branchColor.ts b/apps/kimi-web/src/lib/branchColor.ts
new file mode 100644
index 000000000..5a5c0fe47
--- /dev/null
+++ b/apps/kimi-web/src/lib/branchColor.ts
@@ -0,0 +1,22 @@
+// apps/kimi-web/src/lib/branchColor.ts
+// Map a git branch name to a stable accent color used to mark its worktree
+// group in the sidebar.
+//
+// The palette is generated in OKLCH with a FIXED lightness and chroma, and only
+// the hue varies. That keeps every swatch the same perceived brightness/weight
+// (so no color feels louder than another) while the hue gives clear
+// distinguishability between worktrees. The pure-red hue range (0–40°) is
+// skipped so a worktree never reads as "error red".
+
+const LIGHTNESS = 0.6;
+const CHROMA = 0.17;
+// Hue is in [40, 360): the 0–40° range (pure red) is excluded.
+const HUE_MIN = 40;
+const HUE_SPAN = 320;
+
+export function branchColor(branch: string): string {
+  let h = 0;
+  for (let i = 0; i < branch.length; i++) h = (h * 31 + (branch.codePointAt(i) ?? 0)) % 2147483647;
+  const hue = HUE_MIN + (h % HUE_SPAN);
+  return `oklch(${LIGHTNESS} ${CHROMA} ${hue})`;
+}
diff --git a/apps/kimi-web/src/lib/snapshotSync.ts b/apps/kimi-web/src/lib/snapshotSync.ts
new file mode 100644
index 000000000..e2c4b13cb
--- /dev/null
+++ b/apps/kimi-web/src/lib/snapshotSync.ts
@@ -0,0 +1,35 @@
+export interface CoalescedAsyncRunner<T> {
+  run(key: string): Promise<T>;
+  request(key: string): void;
+}
+
+export function createCoalescedAsyncRunner<T>(
+  fn: (key: string) => Promise<T>,
+): CoalescedAsyncRunner<T> {
+  const inFlight = new Map<string, Promise<T>>();
+  const queued = new Set<string>();
+
+  function run(key: string): Promise<T> {
+    const existing = inFlight.get(key);
+    if (existing !== undefined) return existing;
+
+    const promise = (async () => fn(key))().finally(() => {
+      inFlight.delete(key);
+      if (queued.delete(key)) {
+        void run(key);
+      }
+    });
+    inFlight.set(key, promise);
+    return promise;
+  }
+
+  function request(key: string): void {
+    if (inFlight.has(key)) {
+      queued.add(key);
+      return;
+    }
+    void run(key);
+  }
+
+  return { run, request };
+}
diff --git a/apps/kimi-web/src/lib/worktreeGroups.ts b/apps/kimi-web/src/lib/worktreeGroups.ts
new file mode 100644
index 000000000..f0cac9456
--- /dev/null
+++ b/apps/kimi-web/src/lib/worktreeGroups.ts
@@ -0,0 +1,56 @@
+// apps/kimi-web/src/lib/worktreeGroups.ts
+// Pure helpers for the worktree-centric sidebar groups.
+
+import type { AppWorktree } from '../api/types';
+import type { WorktreeGroup, WorkspaceView } from '../types';
+
+/**
+ * Merge known git worktrees into the session-derived sidebar groups so a
+ * worktree checkout appears in the worktree-centric sidebar even before it has
+ * any sessions — otherwise a freshly-created (or long-idle) worktree is only
+ * visible on the board and can't be opened from the sidebar. Existing session
+ * groups pick up authoritative worktree metadata (path, isMain, dirty, PR).
+ * Non-git workspaces, and workspaces whose worktrees haven't loaded yet, are
+ * left untouched. Pure: the input array and its group objects are not mutated.
+ */
+export function mergeWorktreeGroups(
+  groups: WorktreeGroup[],
+  workspaces: WorkspaceView[],
+  worktreesByWorkspace: Record<string, AppWorktree[]>,
+): WorktreeGroup[] {
+  const result = new Map<string, WorktreeGroup>(groups.map((g) => [g.key, g]));
+  for (const ws of workspaces) {
+    if (ws.isGitRepo !== true) continue;
+    const worktrees = worktreesByWorkspace[ws.id];
+    if (worktrees === undefined) continue;
+    for (const wt of worktrees) {
+      const key = `${ws.id}:${wt.branch}`;
+      const existing = result.get(key);
+      if (existing !== undefined) {
+        result.set(key, {
+          ...existing,
+          path: wt.path,
+          isMain: wt.isMain,
+          dirty: existing.dirty || wt.dirty,
+          pullRequest: existing.pullRequest ?? wt.pullRequest,
+        });
+        continue;
+      }
+      result.set(key, {
+        key,
+        workspaceId: ws.id,
+        workspaceName: ws.name,
+        branch: wt.branch,
+        isMain: wt.isMain,
+        path: wt.path,
+        dirty: wt.dirty,
+        pullRequest: wt.pullRequest,
+        sessions: [],
+        hasRunning: false,
+        hasPending: false,
+        latestAt: 0,
+      });
+    }
+  }
+  return [...result.values()];
+}
diff --git a/apps/kimi-web/src/types.ts b/apps/kimi-web/src/types.ts
index aeaafc3ee..b4049113f 100644
--- a/apps/kimi-web/src/types.ts
+++ b/apps/kimi-web/src/types.ts
@@ -38,6 +38,12 @@ export interface Session {
   updatedAt?: string;
   /** Text of the most recent user prompt, used by sidebar search. */
   lastPrompt?: string;
+  /** Current git branch, when known (populated for visible sessions). */
+  branch?: string;
+  /** GitHub pull request for the current branch, when known. */
+  pullRequest?: { number: number; state: string; url: string } | null;
+  /** True when the session's cwd is a linked worktree (not the main checkout). */
+  isWorktree?: boolean;
 }
 
 export interface Workspace {
@@ -59,6 +65,8 @@ export interface WorkspaceView {
   shortPath: string;
   /** Current branch, when known. */
   branch?: string;
+  /** Whether the workspace root is inside a git repository. */
+  isGitRepo?: boolean;
   /** Number of sessions in this workspace. */
   sessionCount: number;
 }
@@ -72,6 +80,53 @@ export interface WorkspaceGroup {
   sessions: Session[];
 }
 
+/**
+ * One worktree group for the worktree-centric sidebar: a branch checkout of a
+ * repo, with its sessions. Active groups (running / awaiting input) sort to
+ * the top.
+ */
+export interface WorktreeGroup {
+  /** Stable key: `<workspaceId>:<branch>`. */
+  key: string;
+  workspaceId: string;
+  /** Repo / workspace display name. */
+  workspaceName: string;
+  /** Branch name. Empty when git status hasn't loaded yet. */
+  branch: string;
+  /** True for the main checkout of the repo. */
+  isMain: boolean;
+  /** Absolute path of the worktree checkout (from a member session's cwd). */
+  path: string;
+  /** True when the worktree has uncommitted changes. */
+  dirty: boolean;
+  pullRequest: { number: number; state: string; url: string } | null;
+  sessions: Session[];
+  /** True when any session in the group is running. */
+  hasRunning: boolean;
+  /** True when any session is awaiting approval / a question answer. */
+  hasPending: boolean;
+  /** Most recent session activity (ms epoch), used for sorting. */
+  latestAt: number;
+}
+
+/** One workspace section of the global worktree board: the workspace, its
+ *  git worktrees, and its sessions (grouped into columns by the board). */
+export interface BoardSection {
+  workspace: WorkspaceView;
+  worktrees: import('./api/types').AppWorktree[];
+  sessions: Session[];
+}
+
+/** Target of the "complete worktree" confirmation dialog. */
+export interface CompleteWorktreeTarget {
+  workspaceId: string;
+  path: string;
+  branch: string;
+  dirty: boolean;
+  sessionCount: number;
+  isMain: boolean;
+}
+
 /** Sidebar session-list scope: only the active workspace, or all workspaces. */
 export type WorkspaceScope = 'current' | 'all';
 
diff --git a/apps/kimi-web/test/lib-logic.test.ts b/apps/kimi-web/test/lib-logic.test.ts
index 02a2392b8..1d274e7c6 100644
--- a/apps/kimi-web/test/lib-logic.test.ts
+++ b/apps/kimi-web/test/lib-logic.test.ts
@@ -6,6 +6,10 @@ import {
 } from '../src/lib/filePathLinks';
 import { parseDiff } from '../src/lib/parseDiff';
 import { normalizeToolName, toolSummary } from '../src/lib/toolMeta';
+import { mergeWorktreeGroups } from '../src/lib/worktreeGroups';
+import { createCoalescedAsyncRunner } from '../src/lib/snapshotSync';
+import type { AppWorktree } from '../src/api/types';
+import type { WorktreeGroup, WorkspaceView } from '../src/types';
 
 describe('parseDiff', () => {
   it('parses multiple files and keeps hunk line numbers', () => {
@@ -76,3 +80,167 @@ describe('toolMeta', () => {
     ).toBe('example.com/path');
   });
 });
+
+function workspace(id: string, isGitRepo: boolean): WorkspaceView {
+  return {
+    id,
+    name: `repo-${id}`,
+    root: `/repos/${id}`,
+    shortPath: `~/repos/${id}`,
+    sessionCount: 0,
+    isGitRepo,
+  };
+}
+
+function worktree(branch: string, overrides: Partial<AppWorktree> = {}): AppWorktree {
+  return {
+    path: `/repos/wt-${branch || 'detached'}`,
+    branch,
+    head: 'abc123',
+    isMain: false,
+    locked: false,
+    prunable: false,
+    dirty: false,
+    ahead: 0,
+    behind: 0,
+    sessionId: null,
+    pullRequest: null,
+    ...overrides,
+  };
+}
+
+function group(key: string, overrides: Partial<WorktreeGroup> = {}): WorktreeGroup {
+  return {
+    key,
+    workspaceId: key.split(':')[0] ?? '',
+    workspaceName: 'repo',
+    branch: key.split(':')[1] ?? '',
+    isMain: false,
+    path: '/repos/session-cwd',
+    dirty: false,
+    pullRequest: null,
+    sessions: [],
+    hasRunning: false,
+    hasPending: false,
+    latestAt: 100,
+    ...overrides,
+  };
+}
+
+describe('mergeWorktreeGroups', () => {
+  it('adds an empty worktree as a sidebar group so it can be opened', () => {
+    const ws = workspace('w1', true);
+    const result = mergeWorktreeGroups([], [ws], {
+      w1: [worktree('feature', { isMain: false, pullRequest: { number: 7, state: 'open', url: 'u' } })],
+    });
+    expect(result).toHaveLength(1);
+    expect(result[0]).toMatchObject({
+      key: 'w1:feature',
+      workspaceId: 'w1',
+      branch: 'feature',
+      isMain: false,
+      path: '/repos/wt-feature',
+      sessions: [],
+      hasRunning: false,
+      hasPending: false,
+      latestAt: 0,
+      pullRequest: { number: 7, state: 'open', url: 'u' },
+    });
+  });
+
+  it('enriches an existing session group instead of duplicating it', () => {
+    const ws = workspace('w1', true);
+    const existing = group('w1:main', { path: '/old', dirty: false, pullRequest: null });
+    const result = mergeWorktreeGroups([existing], [ws], {
+      w1: [worktree('main', { isMain: true, dirty: true, path: '/repos/main' })],
+    });
+    expect(result).toHaveLength(1);
+    expect(result[0]).toMatchObject({
+      key: 'w1:main',
+      path: '/repos/main',
+      isMain: true,
+      dirty: true,
+      latestAt: 100,
+    });
+  });
+
+  it('keeps a session-derived pull request when the worktree has none', () => {
+    const ws = workspace('w1', true);
+    const pr = { number: 3, state: 'open', url: 'pr' };
+    const existing = group('w1:main', { pullRequest: pr });
+    const result = mergeWorktreeGroups([existing], [ws], {
+      w1: [worktree('main', { pullRequest: null })],
+    });
+    expect(result[0]?.pullRequest).toBe(pr);
+  });
+
+  it('ignores non-git workspaces and workspaces whose worktrees are not loaded', () => {
+    const nonGit = workspace('w2', false);
+    const gitNotLoaded = workspace('w3', true);
+    const result = mergeWorktreeGroups([], [nonGit, gitNotLoaded], {
+      // w3 intentionally absent → not loaded yet
+      w2: [worktree('x')],
+    });
+    expect(result).toHaveLength(0);
+  });
+
+  it('does not mutate the input groups or array', () => {
+    const ws = workspace('w1', true);
+    const existing = group('w1:main', { path: '/old', dirty: false });
+    const groups = [existing];
+    const result = mergeWorktreeGroups(groups, [ws], {
+      w1: [worktree('main', { path: '/new', dirty: true })],
+    });
+    expect(result).not.toBe(groups);
+    expect(existing.path).toBe('/old');
+    expect(existing.dirty).toBe(false);
+  });
+});
+
+describe('createCoalescedAsyncRunner', () => {
+  it('reuses the in-flight promise for the same key', async () => {
+    let runs = 0;
+    let resolveRun!: () => void;
+    const runner = createCoalescedAsyncRunner(async (_key: string) => {
+      runs += 1;
+      await new Promise<void>((resolve) => {
+        resolveRun = resolve;
+      });
+      return runs;
+    });
+
+    const first = runner.run('session-a');
+    const second = runner.run('session-a');
+
+    expect(runs).toBe(1);
+    resolveRun();
+    await expect(Promise.all([first, second])).resolves.toEqual([1, 1]);
+    expect(runs).toBe(1);
+  });
+
+  it('queues at most one rerun requested while a run is in flight', async () => {
+    let runs = 0;
+    const resolvers: Array<() => void> = [];
+    const runner = createCoalescedAsyncRunner(async (_key: string) => {
+      runs += 1;
+      await new Promise<void>((resolve) => {
+        resolvers.push(resolve);
+      });
+      return runs;
+    });
+
+    const first = runner.run('session-a');
+    runner.request('session-a');
+    runner.request('session-a');
+    expect(runs).toBe(1);
+
+    resolvers[0]!();
+    await first;
+    await Promise.resolve();
+
+    expect(runs).toBe(2);
+    resolvers[1]!();
+    await Promise.resolve();
+    expect(runs).toBe(2);
+  });
+});
diff --git a/packages/agent-core/src/services/index.ts b/packages/agent-core/src/services/index.ts
index a76c6d95c..17f2e1f51 100644
--- a/packages/agent-core/src/services/index.ts
+++ b/packages/agent-core/src/services/index.ts
@@ -96,6 +96,15 @@ export {
 } from './workspace/workspaceFs';
 export { WorkspaceFsService } from './workspace/workspaceFsService';
 
+export {
+  IWorktreeService,
+  WorktreeError,
+  WorktreeGitUnavailableError,
+  WorktreeNotFoundError,
+  WorktreeConflictError,
+} from './worktree/worktree';
+export { WorktreeService } from './worktree/worktreeService';
+
 export {
   IAuthSummaryService,
   AuthProvisioningRequiredError,
diff --git a/packages/agent-core/src/services/worktree/worktree.ts b/packages/agent-core/src/services/worktree/worktree.ts
new file mode 100644
index 000000000..174b77a06
--- /dev/null
+++ b/packages/agent-core/src/services/worktree/worktree.ts
@@ -0,0 +1,63 @@
+import { createDecorator } from '../../di';
+import type { IDisposable } from '../../di';
+import type {
+  CreateWorktreeRequest,
+  RemoveWorktreeRequest,
+  Worktree,
+} from '@moonshot-ai/protocol';
+
+/** Base error for all worktree operations. */
+export class WorktreeError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'WorktreeError';
+  }
+}
+
+/** The workspace root is not a git repository (or git is unavailable). */
+export class WorktreeGitUnavailableError extends WorktreeError {
+  readonly cwd: string;
+  constructor(cwd: string, detail: string) {
+    super(`git unavailable at ${cwd}: ${detail}`);
+    this.name = 'WorktreeGitUnavailableError';
+    this.cwd = cwd;
+  }
+}
+
+/** The target worktree (by path) does not exist in this repository. */
+export class WorktreeNotFoundError extends WorktreeError {
+  readonly worktreePath: string;
+  constructor(worktreePath: string) {
+    super(`worktree not found: ${worktreePath}`);
+    this.name = 'WorktreeNotFoundError';
+    this.worktreePath = worktreePath;
+  }
+}
+
+/**
+ * The operation conflicts with git state: branch already checked out in another
+ * worktree, target path already exists, or the worktree has uncommitted changes
+ * on a non-forced remove.
+ */
+export class WorktreeConflictError extends WorktreeError {
+  constructor(message: string) {
+    super(message);
+    this.name = 'WorktreeConflictError';
+  }
+}
+
+export interface IWorktreeService extends IDisposable {
+  readonly _serviceBrand: undefined;
+
+  /** List all worktrees of the workspace's repository, enriched with status. */
+  list(workspaceId: string): Promise<Worktree[]>;
+
+  /** Create a new worktree (and branch) off the workspace's repository. */
+  create(workspaceId: string, req: CreateWorktreeRequest): Promise<Worktree>;
+
+  /** Remove a worktree. Optionally force-remove and/or delete its branch. */
+  remove(workspaceId: string, req: RemoveWorktreeRequest): Promise<void>;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-redeclare
+export const IWorktreeService = createDecorator<IWorktreeService>('worktreeService');
diff --git a/packages/agent-core/src/services/worktree/worktreeService.ts b/packages/agent-core/src/services/worktree/worktreeService.ts
new file mode 100644
index 000000000..77213affd
--- /dev/null
+++ b/packages/agent-core/src/services/worktree/worktreeService.ts
@@ -0,0 +1,508 @@
+import { spawn } from 'node:child_process';
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+
+import { Disposable, InstantiationType, registerSingleton } from '../../di';
+import type {
+  CreateWorktreeRequest,
+  FsPullRequest,
+  RemoveWorktreeRequest,
+  Worktree,
+} from '@moonshot-ai/protocol';
+import { IEventService } from '../event/event';
+import { parsePorcelain } from '../fs/fsGit';
+import { ISessionService } from '../session/session';
+import { IWorkspaceRegistry } from '../workspace/workspaceRegistry';
+
+import {
+  IWorktreeService,
+  WorktreeConflictError,
+  WorktreeError,
+  WorktreeGitUnavailableError,
+  WorktreeNotFoundError,
+} from './worktree';
+
+const PR_SPAWN_TIMEOUT_MS = 5_000;
+const PULL_REQUEST_TTL_MS = 60_000;
+const GIT_SPAWN_TIMEOUT_MS = 15_000;
+
+interface RawWorktree {
+  readonly path: string;
+  readonly head: string;
+  readonly branch: string;
+  readonly bare: boolean;
+  readonly locked: boolean;
+  readonly prunable: boolean;
+  readonly isMain: boolean;
+}
+
+export class WorktreeService extends Disposable implements IWorktreeService {
+  readonly _serviceBrand: undefined;
+
+  private readonly pullRequestCache = new Map<
+    string,
+    { value: FsPullRequest | null; fetchedAt: number }
+  >();
+
+  constructor(
+    @IWorkspaceRegistry private readonly workspaces: IWorkspaceRegistry,
+    @ISessionService private readonly sessions: ISessionService,
+    @IEventService private readonly eventService: IEventService,
+  ) {
+    super();
+  }
+
+  async list(workspaceId: string): Promise<Worktree[]> {
+    const root = await this.workspaces.resolveRoot(workspaceId);
+    await this.assertGitRepo(root);
+    const realRoot = await this.requireRealRoot(root);
+    const rawList = await this.listRaw(root);
+    const sessionMap = await this.buildSessionMap();
+    return Promise.all(
+      rawList.map((raw) => this.enrich(raw, realRoot, sessionMap)),
+    );
+  }
+
+  async create(workspaceId: string, req: CreateWorktreeRequest): Promise<Worktree> {
+    const root = await this.workspaces.resolveRoot(workspaceId);
+    await this.assertGitRepo(root);
+    const realRoot = await this.requireRealRoot(root);
+
+    const branch = req.branch?.trim() || defaultBranchName();
+    validateBranchName(branch);
+
+    const targetPath = await this.resolveTargetPath(realRoot, branch, req.path);
+    const base = req.base_ref?.trim() || (await this.resolveBase(realRoot));
+
+    const res = await runCommand(
+      'git',
+      ['worktree', 'add', '-b', branch, targetPath, base],
+      realRoot,
+      { timeoutMs: GIT_SPAWN_TIMEOUT_MS },
+    );
+    if (res.exitCode !== 0) {
+      throw new WorktreeConflictError(
+        res.stderr.trim() || `git worktree add exit ${res.exitCode}`,
+      );
+    }
+
+    this.publish(workspaceId, targetPath, 'created');
+
+    // Re-read the just-created worktree. A brand-new worktree has no session
+    // yet, so session correlation is intentionally skipped (empty map).
+    const rawList = await this.listRaw(realRoot);
+    const created = rawList.find((w) => path.resolve(w.path) === targetPath);
+    if (created === undefined) {
+      throw new WorktreeError(`worktree created but not listed: ${targetPath}`);
+    }
+    return this.enrich(created, realRoot, new Map());
+  }
+
+  async remove(workspaceId: string, req: RemoveWorktreeRequest): Promise<void> {
+    const root = await this.workspaces.resolveRoot(workspaceId);
+    const realRoot = await this.requireRealRoot(root);
+    const targetPath = path.resolve(req.path);
+
+    const rawList = await this.listRaw(realRoot);
+    const match = rawList.find((w) => path.resolve(w.path) === targetPath);
+    if (match === undefined) {
+      throw new WorktreeNotFoundError(req.path);
+    }
+    if (match.isMain) {
+      throw new WorktreeConflictError('cannot remove the main worktree');
+    }
+
+    const args = ['worktree', 'remove'];
+    if (req.force === true) args.push('--force');
+    args.push(targetPath);
+    const res = await runCommand('git', args, realRoot, {
+      timeoutMs: GIT_SPAWN_TIMEOUT_MS,
+    });
+    if (res.exitCode !== 0) {
+      throw new WorktreeConflictError(
+        res.stderr.trim() || `git worktree remove exit ${res.exitCode}`,
+      );
+    }
+
+    if (req.delete_branch === true && match.branch.length > 0) {
+      // Best-effort: the branch may legitimately be gone already; ignore errors.
+      await runCommand('git', ['branch', '-D', match.branch], realRoot, {
+        timeoutMs: GIT_SPAWN_TIMEOUT_MS,
+      });
+    }
+
+    this.publish(workspaceId, targetPath, 'removed');
+  }
+
+  private async assertGitRepo(root: string): Promise<void> {
+    const res = await runCommand(
+      'git',
+      ['rev-parse', '--is-inside-work-tree'],
+      root,
+      { timeoutMs: GIT_SPAWN_TIMEOUT_MS },
+    );
+    if (res.exitCode !== 0 || res.stdout.trim() !== 'true') {
+      throw new WorktreeGitUnavailableError(
+        root,
+        res.stderr.trim() || `git rev-parse exit ${res.exitCode}`,
+      );
+    }
+  }
+
+  private async requireRealRoot(root: string): Promise<string> {
+    const rp = await realpathSafe(root);
+    if (rp === null) {
+      throw new WorktreeError(`workspace root does not exist: ${root}`);
+    }
+    return rp;
+  }
+
+  private async listRaw(root: string): Promise<RawWorktree[]> {
+    const res = await runCommand(
+      'git',
+      ['worktree', 'list', '--porcelain'],
+      root,
+      { timeoutMs: GIT_SPAWN_TIMEOUT_MS },
+    );
+    if (res.exitCode !== 0) {
+      throw new WorktreeGitUnavailableError(
+        root,
+        res.stderr.trim() || `git worktree list exit ${res.exitCode}`,
+      );
+    }
+    return parseWorktreeList(res.stdout);
+  }
+
+  private async enrich(
+    raw: RawWorktree,
+    realRoot: string,
+    sessionMap: Map<string, string>,
+  ): Promise<Worktree> {
+    const realPath = (await realpathSafe(raw.path)) ?? path.resolve(raw.path);
+
+    let dirty = false;
+    let ahead = 0;
+    let behind = 0;
+    if (!raw.prunable) {
+      const statusRes = await runCommand(
+        'git',
+        ['status', '--porcelain=v1', '--branch'],
+        realPath,
+        { timeoutMs: GIT_SPAWN_TIMEOUT_MS },
+      );
+      if (statusRes.exitCode === 0) {
+        const parsed = parsePorcelain(statusRes.stdout, undefined);
+        ahead = parsed.ahead;
+        behind = parsed.behind;
+        dirty = Object.keys(parsed.entries).length > 0;
+      }
+    }
+
+    const pullRequest = raw.prunable ? null : await this.readPullRequest(realPath);
+    const sessionId = matchSession(realPath, sessionMap);
+
+    return {
+      path: raw.path,
+      branch: raw.branch,
+      head: raw.head,
+      is_main: realPath === realRoot,
+      locked: raw.locked,
+      prunable: raw.prunable,
+      dirty,
+      ahead,
+      behind,
+      session_id: sessionId,
+      pull_request: pullRequest,
+    };
+  }
+
+  private async resolveBase(realRoot: string): Promise<string> {
+    const res = await runCommand(
+      'git',
+      ['symbolic-ref', '--quiet', 'refs/remotes/origin/HEAD'],
+      realRoot,
+      { timeoutMs: GIT_SPAWN_TIMEOUT_MS },
+    );
+    const ref = res.stdout.trim();
+    if (res.exitCode === 0 && ref.length > 0) {
+      // e.g. "refs/remotes/origin/main" → "origin/main", a valid start point
+      // for `git worktree add -b <branch> <path> <base>`.
+      return ref.replace(/^refs\/remotes\//, '');
+    }
+    return 'HEAD';
+  }
+
+  private async resolveTargetPath(
+    realRoot: string,
+    branch: string,
+    customPath: string | undefined,
+  ): Promise<string> {
+    if (customPath !== undefined && customPath.trim().length > 0) {
+      const resolved = path.resolve(customPath.trim());
+      assertInsideRoot(resolved, realRoot);
+      await assertNotExists(resolved);
+      return resolved;
+    }
+
+    const base = path.join(realRoot, '.worktrees', slugify(branch));
+    let candidate = base;
+    for (let i = 2; i <= 20; i++) {
+      if (!(await pathExists(candidate))) return candidate;
+      candidate = `${base}-${i}`;
+    }
+    throw new WorktreeConflictError(
+      `worktree path already exists: ${base} (and numbered suffixes)`,
+    );
+  }
+
+  private async buildSessionMap(): Promise<Map<string, string>> {
+    const map = new Map<string, string>();
+    let afterId: string | undefined;
+    for (;;) {
+      const page = await this.sessions.list(
+        afterId === undefined ? { page_size: 100 } : { page_size: 100, after_id: afterId },
+      );
+      for (const s of page.items) {
+        const cwd = s.metadata?.cwd;
+        if (typeof cwd === 'string' && cwd.length > 0) {
+          const rp = await realpathSafe(cwd);
+          if (rp !== null && !map.has(rp)) map.set(rp, s.id);
+        }
+      }
+      if (!page.has_more || page.items.length === 0) break;
+      afterId = page.items[page.items.length - 1]?.id;
+      if (afterId === undefined) break;
+    }
+    return map;
+  }
+
+  private async readPullRequest(cwd: string): Promise<FsPullRequest | null> {
+    const cached = this.pullRequestCache.get(cwd);
+    const now = Date.now();
+    if (cached !== undefined && now - cached.fetchedAt < PULL_REQUEST_TTL_MS) {
+      return cached.value;
+    }
+    const res = await runCommand(
+      'gh',
+      ['pr', 'view', '--json', 'number,url,state'],
+      cwd,
+      {
+        timeoutMs: PR_SPAWN_TIMEOUT_MS,
+        env: { GH_NO_UPDATE_NOTIFIER: '1', GH_PROMPT_DISABLED: '1' },
+      },
+    );
+    const value = res.exitCode === 0 ? parsePullRequest(res.stdout) : null;
+    this.pullRequestCache.set(cwd, { value, fetchedAt: now });
+    return value;
+  }
+
+  private publish(
+    workspaceId: string,
+    worktreePath: string,
+    change: 'created' | 'removed',
+  ): void {
+    this.eventService.publish({
+      agentId: 'main',
+      sessionId: '__global__',
+      type: 'event.worktree.changed',
+      workspace_id: workspaceId,
+      path: worktreePath,
+      change,
+    });
+  }
+}
+
+function matchSession(realPath: string, sessionMap: Map<string, string>): string | null {
+  const exact = sessionMap.get(realPath);
+  if (exact !== undefined) return exact;
+  const prefix = realPath.endsWith(path.sep) ? realPath : realPath + path.sep;
+  for (const [cwd, id] of sessionMap) {
+    if (cwd.startsWith(prefix)) return id;
+  }
+  return null;
+}
+
+function parseWorktreeList(stdout: string): RawWorktree[] {
+  const result: RawWorktree[] = [];
+  for (const block of stdout.split(/\n[ \t]*\n/)) {
+    const lines = block.split('\n').filter((l) => l.length > 0);
+    if (lines.length === 0) continue;
+    let worktreePath = '';
+    let head = '';
+    let branch = '';
+    let bare = false;
+    let locked = false;
+    let prunable = false;
+    let detached = false;
+    for (const line of lines) {
+      if (line.startsWith('worktree ')) worktreePath = line.slice('worktree '.length);
+      else if (line.startsWith('HEAD ')) head = line.slice('HEAD '.length).trim();
+      else if (line.startsWith('branch ')) branch = line.slice('branch '.length).trim();
+      else if (line === 'bare') bare = true;
+      else if (line === 'detached') detached = true;
+      else if (line.startsWith('locked')) locked = true;
+      else if (line.startsWith('prunable')) prunable = true;
+    }
+    if (worktreePath.length === 0) continue;
+    if (branch.startsWith('refs/heads/')) branch = branch.slice('refs/heads/'.length);
+    if (detached) branch = '';
+    result.push({
+      path: worktreePath,
+      head,
+      branch,
+      bare,
+      locked,
+      prunable,
+      isMain: result.length === 0,
+    });
+  }
+  return result;
+}
+
+function validateBranchName(branch: string): void {
+  if (branch.length === 0 || branch.length > 200) {
+    throw new WorktreeError('invalid branch name length');
+  }
+  if (/\s/.test(branch) || branch.includes('..') || branch.startsWith('-')) {
+    throw new WorktreeError(`invalid branch name: ${branch}`);
+  }
+}
+
+function defaultBranchName(): string {
+  const d = new Date();
+  const pad = (n: number) => String(n).padStart(2, '0');
+  const stamp = `${d.getFullYear()}${pad(d.getMonth() + 1)}${pad(d.getDate())}-${pad(d.getHours())}${pad(d.getMinutes())}${pad(d.getSeconds())}`;
+  return `worktree/${stamp}`;
+}
+
+function slugify(branch: string): string {
+  return branch.replaceAll(/[^A-Za-z0-9._-]+/g, '-').replaceAll(/^-+|-+$/g, '').slice(0, 80) || 'worktree';
+}
+
+function assertInsideRoot(target: string, realRoot: string): void {
+  const prefix = realRoot.endsWith(path.sep) ? realRoot : realRoot + path.sep;
+  if (target !== realRoot && !target.startsWith(prefix)) {
+    throw new WorktreeError(`worktree path escapes repository root: ${target}`);
+  }
+}
+
+async function assertNotExists(p: string): Promise<void> {
+  if (await pathExists(p)) {
+    throw new WorktreeConflictError(`path already exists: ${p}`);
+  }
+}
+
+async function pathExists(p: string): Promise<boolean> {
+  try {
+    await fs.stat(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function realpathSafe(p: string): Promise<string | null> {
+  try {
+    return await fs.realpath(p);
+  } catch {
+    return null;
+  }
+}
+
+interface RunResult {
+  readonly exitCode: number;
+  readonly stdout: string;
+  readonly stderr: string;
+}
+
+interface RunCommandOptions {
+  readonly timeoutMs?: number;
+  readonly env?: NodeJS.ProcessEnv;
+}
+
+async function runCommand(
+  cmd: string,
+  args: readonly string[],
+  cwd: string,
+  options: RunCommandOptions = {},
+): Promise<RunResult> {
+  return new Promise<RunResult>((resolve) => {
+    const child = spawn(cmd, args, {
+      cwd,
+      stdio: ['ignore', 'pipe', 'pipe'],
+      env: options.env ? { ...process.env, ...options.env } : process.env,
+      windowsHide: true,
+    });
+    let stdout = '';
+    let stderr = '';
+    let settled = false;
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const finish = (result: RunResult) => {
+      if (settled) return;
+      settled = true;
+      if (timer !== undefined) clearTimeout(timer);
+      resolve(result);
+    };
+    if (options.timeoutMs !== undefined) {
+      timer = setTimeout(() => {
+        child.kill();
+        finish({ exitCode: -1, stdout, stderr });
+      }, options.timeoutMs);
+      timer.unref?.();
+    }
+    child.stdout.setEncoding('utf-8');
+    child.stderr.setEncoding('utf-8');
+    child.stdout.on('data', (c: string) => {
+      stdout += c;
+    });
+    child.stderr.on('data', (c: string) => {
+      stderr += c;
+    });
+    child.once('error', () => {
+      finish({ exitCode: -1, stdout, stderr });
+    });
+    child.once('close', (code) => {
+      finish({ exitCode: code ?? -1, stdout, stderr });
+    });
+  });
+}
+
+function parsePullRequest(stdout: string): FsPullRequest | null {
+  let raw: unknown;
+  try {
+    raw = JSON.parse(stdout);
+  } catch {
+    return null;
+  }
+  if (typeof raw !== 'object' || raw === null) return null;
+  const record = raw as Record<string, unknown>;
+  const number = record['number'];
+  const url = record['url'];
+  const state = record['state'];
+  if (typeof number !== 'number' || !Number.isInteger(number) || number <= 0) return null;
+  if (typeof url !== 'string' || !isSafeHttpUrl(url)) return null;
+  if (typeof state !== 'string') return null;
+  const normalized = state.toLowerCase();
+  if (normalized !== 'open' && normalized !== 'merged' && normalized !== 'closed') return null;
+  return { number, state: normalized, url };
+}
+
+function isSafeHttpUrl(value: string): boolean {
+  if (hasControlChars(value)) return false;
+  try {
+    const url = new URL(value);
+    return url.protocol === 'https:' || url.protocol === 'http:';
+  } catch {
+    return false;
+  }
+}
+
+function hasControlChars(value: string): boolean {
+  for (const char of value) {
+    const code = char.codePointAt(0) ?? 0;
+    if (code <= 0x1f || code === 0x7f) return true;
+  }
+  return false;
+}
+
+registerSingleton(IWorktreeService, WorktreeService, InstantiationType.Delayed);
diff --git a/packages/agent-core/test/services/worktree-service.test.ts b/packages/agent-core/test/services/worktree-service.test.ts
new file mode 100644
index 000000000..4bf06970a
--- /dev/null
+++ b/packages/agent-core/test/services/worktree-service.test.ts
@@ -0,0 +1,127 @@
+import { execFileSync } from 'node:child_process';
+import { promises as fs } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import type { IEventService, ISessionService, IWorkspaceRegistry } from '../../src/services';
+import {
+  WorktreeConflictError,
+  WorktreeGitUnavailableError,
+  WorktreeService,
+} from '../../src/services';
+
+function git(cwd: string, ...args: string[]): void {
+  execFileSync('git', args, { cwd, stdio: 'pipe' });
+}
+
+async function makeRepo(): Promise<string> {
+  const root = await fs.mkdtemp(path.join(os.tmpdir(), 'worktree-test-'));
+  git(root, 'init');
+  git(root, 'config', 'user.email', 'test@example.com');
+  git(root, 'config', 'user.name', 'Test');
+  await fs.writeFile(path.join(root, 'README.md'), 'hello\n');
+  git(root, 'add', '.');
+  git(root, 'commit', '-m', 'init');
+  return root;
+}
+
+let sessionItems: Array<{ id: string; metadata: { cwd: string } }> = [];
+let published: Array<{ type: string; change: string }> = [];
+
+function buildService(root: string): WorktreeService {
+  const workspaces = {
+    resolveRoot: vi.fn().mockResolvedValue(root),
+  } as unknown as IWorkspaceRegistry;
+  const sessions = {
+    list: vi.fn().mockImplementation(async () => ({
+      items: sessionItems,
+      has_more: false,
+    })),
+  } as unknown as ISessionService;
+  const eventService = {
+    publish: vi.fn((e: { type: string; change: string }) => {
+      published.push({ type: e.type, change: e.change });
+    }),
+  } as unknown as IEventService;
+  return new WorktreeService(workspaces, sessions, eventService);
+}
+
+let root: string;
+
+beforeEach(async () => {
+  root = await makeRepo();
+  sessionItems = [];
+  published = [];
+});
+
+afterEach(async () => {
+  if (root !== undefined) {
+    await fs.rm(root, { recursive: true, force: true });
+  }
+});
+
+describe('WorktreeService', () => {
+  it('lists the main worktree on a fresh repo', async () => {
+    const service = buildService(root);
+    const list = await service.list('ws');
+    expect(list).toHaveLength(1);
+    expect(list[0]?.is_main).toBe(true);
+    expect(list[0]?.session_id).toBeNull();
+    expect(list[0]?.pull_request).toBeNull();
+  });
+
+  it('creates a worktree and lists it as non-main', async () => {
+    const service = buildService(root);
+    const created = await service.create('ws', { branch: 'feat-x' });
+    expect(created.branch).toBe('feat-x');
+    expect(created.is_main).toBe(false);
+    expect(created.dirty).toBe(false);
+    expect(created.path).toContain('.worktrees');
+
+    const list = await service.list('ws');
+    expect(list).toHaveLength(2);
+    expect(list.some((w) => w.branch === 'feat-x' && !w.is_main)).toBe(true);
+    expect(published).toContainEqual({ type: 'event.worktree.changed', change: 'created' });
+  });
+
+  it('correlates a session whose cwd is the worktree path', async () => {
+    const service = buildService(root);
+    const created = await service.create('ws', { branch: 'feat-y' });
+    sessionItems = [{ id: 'sess-1', metadata: { cwd: created.path } }];
+
+    const list = await service.list('ws');
+    const match = list.find((w) => w.branch === 'feat-y');
+    expect(match?.session_id).toBe('sess-1');
+  });
+
+  it('removes a worktree', async () => {
+    const service = buildService(root);
+    const created = await service.create('ws', { branch: 'feat-z' });
+    await service.remove('ws', { path: created.path });
+    const list = await service.list('ws');
+    expect(list).toHaveLength(1);
+    expect(published).toContainEqual({ type: 'event.worktree.changed', change: 'removed' });
+  });
+
+  it('refuses to remove the main worktree', async () => {
+    const service = buildService(root);
+    const list = await service.list('ws');
+    const main = list[0];
+    if (main === undefined) throw new Error('missing main');
+    await expect(service.remove('ws', { path: main.path })).rejects.toBeInstanceOf(
+      WorktreeConflictError,
+    );
+  });
+
+  it('throws git-unavailable for a non-git directory', async () => {
+    const notGit = await fs.mkdtemp(path.join(os.tmpdir(), 'worktree-nogit-'));
+    try {
+      const service = buildService(notGit);
+      await expect(service.list('ws')).rejects.toBeInstanceOf(WorktreeGitUnavailableError);
+    } finally {
+      await fs.rm(notGit, { recursive: true, force: true });
+    }
+  });
+});
diff --git a/packages/protocol/src/error-codes.ts b/packages/protocol/src/error-codes.ts
index 9205830f1..add956b0f 100644
--- a/packages/protocol/src/error-codes.ts
+++ b/packages/protocol/src/error-codes.ts
@@ -57,6 +57,8 @@ export const ErrorCode = {
   TERMINAL_NOT_FOUND: 40414,
   /** skill_name 不存在 */
   SKILL_NOT_FOUND: 40415,
+  /** worktree path 不存在 */
+  WORKTREE_NOT_FOUND: 40416,
 
   /** session 有正在进行的 prompt，拒绝新请求 */
   SESSION_BUSY: 40901,
@@ -82,6 +84,8 @@ export const ErrorCode = {
   SESSION_UNDO_UNAVAILABLE: 40911,
   /** skill 存在但类型不支持用户激活（如 reference 类型） */
   SKILL_NOT_ACTIVATABLE: 40912,
+  /** worktree 操作冲突（分支已被占用、worktree 有未提交改动等） */
+  WORKTREE_CONFLICT: 40920,
 
   /** 当前会话已存在活跃 goal */
   GOAL_ALREADY_EXISTS: 40913,
@@ -170,6 +174,7 @@ export const ErrorCodeReason: Readonly<Record<ErrorCode, string>> = {
   [ErrorCode.MODEL_NOT_FOUND]: 'model.not_found',
   [ErrorCode.TERMINAL_NOT_FOUND]: 'terminal.not_found',
   [ErrorCode.SKILL_NOT_FOUND]: 'skill.not_found',
+  [ErrorCode.WORKTREE_NOT_FOUND]: 'worktree.not_found',
 
   [ErrorCode.SESSION_BUSY]: 'session.busy',
   [ErrorCode.APPROVAL_ALREADY_RESOLVED]: 'approval.already_resolved',
@@ -183,6 +188,7 @@ export const ErrorCodeReason: Readonly<Record<ErrorCode, string>> = {
   [ErrorCode.COMPACTION_UNABLE]: 'compaction.unable',
   [ErrorCode.SESSION_UNDO_UNAVAILABLE]: 'session.undo_unavailable',
   [ErrorCode.SKILL_NOT_ACTIVATABLE]: 'skill.not_activatable',
+  [ErrorCode.WORKTREE_CONFLICT]: 'worktree.conflict',
 
   [ErrorCode.GOAL_ALREADY_EXISTS]: 'goal.already_exists',
   [ErrorCode.GOAL_NOT_FOUND]: 'goal.not_found',
diff --git a/packages/protocol/src/events.ts b/packages/protocol/src/events.ts
index 52e9f5afb..4d45324fe 100644
--- a/packages/protocol/src/events.ts
+++ b/packages/protocol/src/events.ts
@@ -333,6 +333,16 @@ export interface WorkspaceDeletedEvent {
   readonly root: string;
 }
 
+export interface WorktreeChangedEvent {
+  readonly type: 'event.worktree.changed';
+  /** Workspace whose repository's worktree set changed. */
+  readonly workspace_id: string;
+  /** Absolute path of the affected worktree, when applicable. */
+  readonly path?: string;
+  /** Why the change happened. */
+  readonly change: 'created' | 'removed';
+}
+
 export interface SessionStatusChangedEvent {
   readonly type: 'event.session.status_changed';
   readonly status: SessionStatus;
@@ -595,6 +605,7 @@ export type AgentEvent =
   | WorkspaceCreatedEvent
   | WorkspaceUpdatedEvent
   | WorkspaceDeletedEvent
+  | WorktreeChangedEvent
   | SessionStatusChangedEvent
   | ConfigChangedEvent
   | GoalUpdatedEvent
diff --git a/packages/protocol/src/index.ts b/packages/protocol/src/index.ts
index accd02078..4f71a7f37 100644
--- a/packages/protocol/src/index.ts
+++ b/packages/protocol/src/index.ts
@@ -10,6 +10,7 @@ export * from './asyncapi';
 
 export * from './session';
 export * from './workspace';
+export * from './worktree';
 export * from './message';
 export * from './approval';
 export * from './question';
@@ -26,6 +27,7 @@ export * from './rest/oauth';
 export * from './rest/session';
 export * from './rest/snapshot';
 export * from './rest/workspace';
+export * from './rest/worktree';
 export * from './rest/fsBrowse';
 export * from './rest/message';
 export * from './rest/prompt';
diff --git a/packages/protocol/src/rest/worktree.ts b/packages/protocol/src/rest/worktree.ts
new file mode 100644
index 000000000..5cb226fc2
--- /dev/null
+++ b/packages/protocol/src/rest/worktree.ts
@@ -0,0 +1,80 @@
+/**
+ *   GET    /v1/workspaces/{workspace_id}/worktrees            → ListWorktreesResponse { worktrees }
+ *   POST   /v1/workspaces/{workspace_id}/worktrees            body: CreateWorktreeRequest      → Worktree
+ *   POST   /v1/workspaces/{workspace_id}/worktrees/remove     body: RemoveWorktreeRequest      → { removed: true }
+ *   POST   /v1/workspaces/{workspace_id}/worktrees/open-in    body: OpenWorktreeInAppRequest   → { opened: true }
+ *
+ * Errors:
+ *   - 40001 validation.failed        (bad branch name, path escapes repo, etc.)
+ *   - 40410 workspace.not_found      (unknown workspace_id)
+ *   - 40416 worktree.not_found       (remove/open target missing)
+ *   - 40908 fs.git_unavailable       (workspace root is not a git repository)
+ *   - 40913 worktree.conflict        (branch already in use, worktree dirty on remove, etc.)
+ */
+
+import { z } from 'zod';
+
+import { worktreeSchema } from '../worktree';
+
+export const listWorktreesResponseSchema = z.object({
+  worktrees: z.array(worktreeSchema),
+});
+export type ListWorktreesResponse = z.infer<typeof listWorktreesResponseSchema>;
+
+export const createWorktreeRequestSchema = z.object({
+  /** New branch name to create. Defaults to a slug derived from the path or a timestamp. */
+  branch: z.string().min(1).max(200).optional(),
+  /**
+   * Base ref to branch from. Defaults to the remote default branch
+   * (`origin/HEAD`); when no remote is available the caller should fall back
+   * to the local `HEAD`.
+   */
+  base_ref: z.string().min(1).max(200).optional(),
+  /**
+   * Absolute path for the new worktree. Defaults to `<repo>/.worktrees/<slug>`.
+   * Must not already exist and must not escape the repository's parent area.
+   */
+  path: z.string().min(1).optional(),
+});
+export type CreateWorktreeRequest = z.infer<typeof createWorktreeRequestSchema>;
+
+export const createWorktreeResponseSchema = worktreeSchema;
+export type CreateWorktreeResponse = z.infer<typeof createWorktreeResponseSchema>;
+
+export const removeWorktreeRequestSchema = z.object({
+  /** Absolute path of the worktree to remove. */
+  path: z.string().min(1),
+  /** Force removal even when the worktree has uncommitted changes. */
+  force: z.boolean().optional(),
+  /** Also delete the associated branch after removing the worktree. */
+  delete_branch: z.boolean().optional(),
+});
+export type RemoveWorktreeRequest = z.infer<typeof removeWorktreeRequestSchema>;
+
+export const removeWorktreeResponseSchema = z.object({
+  removed: z.literal(true),
+});
+export type RemoveWorktreeResponse = z.infer<typeof removeWorktreeResponseSchema>;
+
+/** External applications a worktree folder can be opened in. Mirrors `fsOpenInAppIdSchema`. */
+export const openWorktreeInAppIdSchema = z.enum([
+  'finder',
+  'cursor',
+  'vscode',
+  'iterm',
+  'terminal',
+]);
+export type OpenWorktreeInAppId = z.infer<typeof openWorktreeInAppIdSchema>;
+
+export const openWorktreeInAppRequestSchema = z.object({
+  /** External application to open the worktree folder in. */
+  app_id: openWorktreeInAppIdSchema,
+  /** Absolute path of the worktree to open. Must belong to the workspace. */
+  path: z.string().min(1),
+});
+export type OpenWorktreeInAppRequest = z.infer<typeof openWorktreeInAppRequestSchema>;
+
+export const openWorktreeInAppResponseSchema = z.object({
+  opened: z.literal(true),
+});
+export type OpenWorktreeInAppResponse = z.infer<typeof openWorktreeInAppResponseSchema>;
diff --git a/packages/protocol/src/worktree.ts b/packages/protocol/src/worktree.ts
new file mode 100644
index 000000000..863e02ebb
--- /dev/null
+++ b/packages/protocol/src/worktree.ts
@@ -0,0 +1,38 @@
+import { z } from 'zod';
+
+import { fsPullRequestSchema } from './rest/fs';
+
+/**
+ * A single git worktree belonging to a workspace's repository. Worktrees are
+ * not persisted by us — `git worktree list --porcelain` is the source of truth.
+ * The enrichment fields (dirty / ahead / behind / session_id / pull_request)
+ * are best-effort: they degrade to false / null when the underlying git or
+ * `gh` call fails, and never fail the request on their own.
+ */
+export const worktreeSchema = z.object({
+  /** Absolute path of the worktree checkout. */
+  path: z.string().min(1),
+  /** Current branch name. Empty string when detached or no commits yet. */
+  branch: z.string(),
+  /** HEAD commit SHA. Empty string when the worktree has no commits. */
+  head: z.string(),
+  /** True for the primary (main) checkout of the repository. */
+  is_main: z.boolean(),
+  /** True when the worktree is locked (`git worktree lock`). */
+  locked: z.boolean(),
+  /** True when the worktree is prunable (e.g. its directory is missing). */
+  prunable: z.boolean(),
+
+  /** True when the worktree has uncommitted changes (including untracked). */
+  dirty: z.boolean(),
+  /** Commits ahead of the upstream tracking branch (0 when none). */
+  ahead: z.number().int().nonnegative(),
+  /** Commits behind the upstream tracking branch (0 when none). */
+  behind: z.number().int().nonnegative(),
+  /** Id of a session whose cwd falls inside this worktree, if any. */
+  session_id: z.string().nullable(),
+  /** GitHub pull request for the current branch, looked up via `gh pr view`. */
+  pull_request: fsPullRequestSchema.nullable(),
+});
+
+export type Worktree = z.infer<typeof worktreeSchema>;
diff --git a/packages/server/src/routes/registerApiV1Routes.ts b/packages/server/src/routes/registerApiV1Routes.ts
index c710641ea..c8df1bb7c 100644
--- a/packages/server/src/routes/registerApiV1Routes.ts
+++ b/packages/server/src/routes/registerApiV1Routes.ts
@@ -24,6 +24,7 @@ import { registerTerminalsRoutes } from './terminals';
 import { registerToolsRoutes } from './tools';
 import { registerWorkspaceFsRoutes } from './workspaceFs';
 import { registerWorkspacesRoutes } from './workspaces';
+import { registerWorktreesRoutes } from './worktrees';
 
 interface ApiV1AppHost {
   register(
@@ -108,6 +109,10 @@ export async function registerApiV1Routes(
       apiV1 as unknown as Parameters<typeof registerWorkspaceFsRoutes>[0],
       ix,
     );
+    registerWorktreesRoutes(
+      apiV1 as unknown as Parameters<typeof registerWorktreesRoutes>[0],
+      ix,
+    );
 
     if (opts.debugEndpoints === true) {
       registerDebugRoutes(
diff --git a/packages/server/src/routes/worktrees.ts b/packages/server/src/routes/worktrees.ts
new file mode 100644
index 000000000..78d11a738
--- /dev/null
+++ b/packages/server/src/routes/worktrees.ts
@@ -0,0 +1,209 @@
+import {
+  ErrorCode,
+  createWorktreeRequestSchema,
+  createWorktreeResponseSchema,
+  listWorktreesResponseSchema,
+  openWorktreeInAppRequestSchema,
+  openWorktreeInAppResponseSchema,
+  removeWorktreeRequestSchema,
+  removeWorktreeResponseSchema,
+  workspaceIdParamSchema,
+} from '@moonshot-ai/protocol';
+
+import {
+  IWorktreeService,
+  WorktreeConflictError,
+  WorktreeError,
+  WorktreeGitUnavailableError,
+  WorktreeNotFoundError,
+  WorkspaceNotFoundError,
+  type IInstantiationService,
+} from '@moonshot-ai/agent-core';
+
+import { errEnvelope, okEnvelope } from '../envelope';
+import { launchDetached, openInAppCommandFor } from '../lib/fileLaunch';
+import { defineRoute } from '../middleware/defineRoute';
+
+interface WorktreeRouteHost {
+  get(
+    path: string,
+    options: { preHandler: unknown[]; schema?: Record<string, unknown> } | undefined,
+    handler: (
+      req: { id: string; params: unknown },
+      reply: { send(payload: unknown): unknown },
+    ) => Promise<void> | void,
+  ): unknown;
+  post(
+    path: string,
+    options: { preHandler: unknown[]; schema?: Record<string, unknown> },
+    handler: (
+      req: { id: string; body: unknown; params: unknown },
+      reply: { send(payload: unknown): unknown },
+    ) => Promise<void> | void,
+  ): unknown;
+}
+
+export function registerWorktreesRoutes(
+  app: WorktreeRouteHost,
+  ix: IInstantiationService,
+): void {
+  const listRoute = defineRoute(
+    {
+      method: 'GET',
+      path: '/workspaces/{workspace_id}/worktrees',
+      params: workspaceIdParamSchema,
+      success: { data: listWorktreesResponseSchema },
+      description: 'List git worktrees of a workspace repository',
+      tags: ['worktrees'],
+    },
+    async (req, reply) => {
+      try {
+        const worktrees = await ix.invokeFunction((a) =>
+          a.get(IWorktreeService).list(req.params.workspace_id),
+        );
+        reply.send(okEnvelope({ worktrees }, req.id));
+      } catch (err) {
+        sendMappedError(reply, req.id, err);
+      }
+    },
+  );
+
+  app.get(
+    listRoute.path,
+    listRoute.options,
+    listRoute.handler as Parameters<WorktreeRouteHost['get']>[2],
+  );
+
+  const createRoute = defineRoute(
+    {
+      method: 'POST',
+      path: '/workspaces/{workspace_id}/worktrees',
+      params: workspaceIdParamSchema,
+      body: createWorktreeRequestSchema,
+      success: { data: createWorktreeResponseSchema },
+      description: 'Create a git worktree (and branch) in a workspace repository',
+      tags: ['worktrees'],
+    },
+    async (req, reply) => {
+      try {
+        const worktree = await ix.invokeFunction((a) =>
+          a.get(IWorktreeService).create(req.params.workspace_id, req.body),
+        );
+        reply.send(okEnvelope(worktree, req.id));
+      } catch (err) {
+        sendMappedError(reply, req.id, err);
+      }
+    },
+  );
+
+  app.post(
+    createRoute.path,
+    createRoute.options,
+    createRoute.handler as Parameters<WorktreeRouteHost['post']>[2],
+  );
+
+  const removeRoute = defineRoute(
+    {
+      method: 'POST',
+      path: '/workspaces/{workspace_id}/worktrees/remove',
+      params: workspaceIdParamSchema,
+      body: removeWorktreeRequestSchema,
+      success: { data: removeWorktreeResponseSchema },
+      description: 'Remove a git worktree from a workspace repository',
+      tags: ['worktrees'],
+    },
+    async (req, reply) => {
+      try {
+        await ix.invokeFunction((a) =>
+          a.get(IWorktreeService).remove(req.params.workspace_id, req.body),
+        );
+        reply.send(okEnvelope({ removed: true as const }, req.id));
+      } catch (err) {
+        sendMappedError(reply, req.id, err);
+      }
+    },
+  );
+
+  app.post(
+    removeRoute.path,
+    removeRoute.options,
+    removeRoute.handler as Parameters<WorktreeRouteHost['post']>[2],
+  );
+
+  const openInRoute = defineRoute(
+    {
+      method: 'POST',
+      path: '/workspaces/{workspace_id}/worktrees/open-in',
+      params: workspaceIdParamSchema,
+      body: openWorktreeInAppRequestSchema,
+      success: { data: openWorktreeInAppResponseSchema },
+      description: 'Open a worktree folder in an external application (Cursor, VS Code, Finder, etc.)',
+      tags: ['worktrees'],
+    },
+    async (req, reply) => {
+      let targetPath: string;
+      try {
+        const worktrees = await ix.invokeFunction((a) =>
+          a.get(IWorktreeService).list(req.params.workspace_id),
+        );
+        const target = worktrees.find((w) => w.path === req.body.path);
+        if (!target) {
+          throw new WorktreeNotFoundError(req.body.path);
+        }
+        targetPath = target.path;
+      } catch (err) {
+        sendMappedError(reply, req.id, err);
+        return;
+      }
+      try {
+        await launchDetached(
+          openInAppCommandFor(req.body.app_id, targetPath, { isDirectory: true }),
+        );
+      } catch (err) {
+        reply.send(
+          errEnvelope(
+            ErrorCode.INTERNAL_ERROR,
+            `failed to open in ${req.body.app_id}: ${err instanceof Error ? err.message : String(err)}`,
+            req.id,
+          ),
+        );
+        return;
+      }
+      reply.send(okEnvelope({ opened: true as const }, req.id));
+    },
+  );
+
+  app.post(
+    openInRoute.path,
+    openInRoute.options,
+    openInRoute.handler as Parameters<WorktreeRouteHost['post']>[2],
+  );
+}
+
+function sendMappedError(
+  reply: { send(payload: unknown): unknown },
+  requestId: string,
+  err: unknown,
+): void {
+  if (err instanceof WorkspaceNotFoundError) {
+    reply.send(errEnvelope(ErrorCode.WORKSPACE_NOT_FOUND, err.message, requestId));
+    return;
+  }
+  if (err instanceof WorktreeGitUnavailableError) {
+    reply.send(errEnvelope(ErrorCode.FS_GIT_UNAVAILABLE, err.message, requestId));
+    return;
+  }
+  if (err instanceof WorktreeNotFoundError) {
+    reply.send(errEnvelope(ErrorCode.WORKTREE_NOT_FOUND, err.message, requestId));
+    return;
+  }
+  if (err instanceof WorktreeConflictError) {
+    reply.send(errEnvelope(ErrorCode.WORKTREE_CONFLICT, err.message, requestId));
+    return;
+  }
+  if (err instanceof WorktreeError) {
+    reply.send(errEnvelope(ErrorCode.VALIDATION_FAILED, err.message, requestId));
+    return;
+  }
+  throw err;
+}
diff --git a/packages/server/src/services/gateway/wsBroadcastService.ts b/packages/server/src/services/gateway/wsBroadcastService.ts
index b2e969bab..804cdf3fd 100644
--- a/packages/server/src/services/gateway/wsBroadcastService.ts
+++ b/packages/server/src/services/gateway/wsBroadcastService.ts
@@ -245,7 +245,8 @@ function isGlobalSessionEvent(type: string): boolean {
     // the '__global__' watermark and fan out to every connection.
     type === 'event.workspace.created' ||
     type === 'event.workspace.updated' ||
-    type === 'event.workspace.deleted'
+    type === 'event.workspace.deleted' ||
+    type === 'event.worktree.changed'
   );
 }
 
diff --git a/snapshot-sync-logic.html b/snapshot-sync-logic.html
new file mode 100644
index 000000000..75b9637e9
--- /dev/null
+++ b/snapshot-sync-logic.html
@@ -0,0 +1,278 @@
+<!doctype html>
+<html lang="zh-CN">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>Kimi Code Web 消息同步逻辑形状</title>
+  <style>
+    :root {
+      --bg: #0f1115;
+      --panel: #171a21;
+      --panel2: #1e2230;
+      --text: #e7eaf0;
+      --muted: #a7b0c0;
+      --line: #343b4d;
+      --blue: #6aa6ff;
+      --green: #61d095;
+      --yellow: #f2c14e;
+      --red: #ff7a7a;
+      --purple: #b39dff;
+    }
+    * { box-sizing: border-box; }
+    body {
+      margin: 0;
+      background: var(--bg);
+      color: var(--text);
+      font-family: ui-sans-serif, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+      line-height: 1.65;
+    }
+    header {
+      padding: 40px 24px 24px;
+      border-bottom: 1px solid var(--line);
+      background: linear-gradient(180deg, #151a24 0%, var(--bg) 100%);
+    }
+    h1 { margin: 0 0 8px; font-size: 28px; }
+    h2 { margin: 34px 0 12px; font-size: 22px; }
+    h3 { margin: 22px 0 8px; font-size: 17px; }
+    p { margin: 8px 0; }
+    main { max-width: 1120px; margin: 0 auto; padding: 26px 24px 60px; }
+    .subtitle { color: var(--muted); max-width: 820px; }
+    .card {
+      background: var(--panel);
+      border: 1px solid var(--line);
+      border-radius: 14px;
+      padding: 18px;
+      margin: 14px 0;
+    }
+    .grid { display: grid; grid-template-columns: repeat(12, 1fr); gap: 12px; }
+    .span4 { grid-column: span 4; }
+    .span6 { grid-column: span 6; }
+    .span12 { grid-column: span 12; }
+    .box {
+      border: 1px solid var(--line);
+      background: var(--panel2);
+      border-radius: 12px;
+      padding: 12px 14px;
+      min-height: 74px;
+    }
+    .box b { display: block; margin-bottom: 4px; }
+    .box span { color: var(--muted); font-size: 14px; }
+    .arrow { text-align: center; color: var(--muted); font-size: 22px; margin: 6px 0; }
+    .pill {
+      display: inline-block;
+      border-radius: 999px;
+      padding: 2px 9px;
+      font-size: 12px;
+      margin-right: 6px;
+      border: 1px solid var(--line);
+      color: var(--text);
+      white-space: nowrap;
+    }
+    .rest { background: rgba(106,166,255,.14); border-color: rgba(106,166,255,.4); }
+    .ws { background: rgba(97,208,149,.14); border-color: rgba(97,208,149,.4); }
+    .bus { background: rgba(179,157,255,.14); border-color: rgba(179,157,255,.4); }
+    .state { background: rgba(242,193,78,.14); border-color: rgba(242,193,78,.4); }
+    .bad { background: rgba(255,122,122,.14); border-color: rgba(255,122,122,.4); }
+    code, pre {
+      font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;
+    }
+    pre {
+      overflow-x: auto;
+      background: #0b0d12;
+      border: 1px solid var(--line);
+      border-radius: 12px;
+      padding: 14px;
+      color: #d7e0ee;
+      font-size: 13px;
+    }
+    ul { margin: 8px 0 8px 20px; padding: 0; }
+    li { margin: 4px 0; }
+    .muted { color: var(--muted); }
+    .timeline {
+      border-left: 2px solid var(--line);
+      margin-left: 10px;
+      padding-left: 18px;
+    }
+    .timeline div { margin: 12px 0; position: relative; }
+    .timeline div::before {
+      content: "";
+      position: absolute;
+      left: -25px;
+      top: 7px;
+      width: 10px;
+      height: 10px;
+      border-radius: 50%;
+      background: var(--blue);
+    }
+    .ok::before { background: var(--green) !important; }
+    .warn::before { background: var(--yellow) !important; }
+    .badstep::before { background: var(--red) !important; }
+    @media (max-width: 820px) {
+      .span4, .span6 { grid-column: span 12; }
+    }
+  </style>
+</head>
+<body>
+  <header>
+    <h1>Kimi Code Web 消息同步逻辑形状</h1>
+    <div class="subtitle">这份图说明 Web UI 如何通过 REST snapshot + WebSocket 增量事件来显示消息，以及为什么会出现短时间多次 <code>resync_required</code> / snapshot 请求风暴。</div>
+  </header>
+
+  <main>
+    <section class="card">
+      <h2>0. 图例</h2>
+      <p>
+        <span class="pill rest">REST</span> HTTP 请求/响应，例如 <code>GET /snapshot</code>、<code>POST /prompts</code>。
+      </p>
+      <p>
+        <span class="pill ws">WebSocket</span> 长连接，服务端把事件增量推给前端。
+      </p>
+      <p>
+        <span class="pill bus">Event Bus</span> agent-core 内部事件总线，所有会话事件都先进入这里。
+      </p>
+      <p>
+        <span class="pill state">Client State</span> 前端 composable 里的响应式状态，驱动 UI 渲染。
+      </p>
+    </section>
+
+    <section class="card">
+      <h2>1. 总体组件</h2>
+      <div class="grid">
+        <div class="box span4">
+          <b>Browser UI</b>
+          <span>Vue 组件、会话列表、聊天面板、输入框。</span>
+        </div>
+        <div class="box span4">
+          <b>useKimiWebClient</b>
+          <span>前端状态中枢：保存 sessions、messages、lastSeq、epoch、WS connection。</span>
+        </div>
+        <div class="box span4">
+          <b>Daemon API Client</b>
+          <span>REST client + WebSocket client，负责和本地 server 通信。</span>
+        </div>
+        <div class="arrow span12">↓ HTTP / WS</div>
+        <div class="box span4">
+          <b>REST Routes</b>
+          <span><code>/snapshot</code>、<code>/prompts</code> 等。</span>
+        </div>
+        <div class="box span4">
+          <b>WSBroadcastService</b>
+          <span>把事件总线事件转成 WS frame，并维护 per-session seq / epoch。</span>
+        </div>
+        <div class="box span4">
+          <b>SessionEventJournal</b>
+          <span>每个 session 一个 JSONL journal，记录 durable events 和 seq。</span>
+        </div>
+      </div>
+    </section>
+
+    <section class="card">
+      <h2>2. 打开一个 session：snapshot 全量同步</h2>
+      <pre>selectSession(sessionId)
+  └─ syncSessionFromSnapshot(sessionId)
+      ├─ GET /api/v1/sessions/{id}/snapshot
+      ├─ SnapshotService 读取 SessionStore / state.json / wire.jsonl
+      ├─ WSBroadcastService.getSnapshotState() 返回当前 seq / epoch / inFlightTurn
+      ├─ 前端写入 messages / approvals / questions / lastSeq / epoch
+      ├─ eventConn.seedSnapshot(...) 恢复正在进行的 turn
+      └─ eventConn.subscribe({ seq: as_of_seq, epoch })</pre>
+      <p class="muted">关键点：snapshot 是“当前水位的全量状态”，WebSocket 负责从这个水位之后开始增量同步。</p>
+    </section>
+
+    <section class="card">
+      <h2>3. 接收实时消息：WebSocket 增量事件</h2>
+      <pre>agent-core 内部产生事件
+  └─ IEventService.publish(event)
+      └─ WSBroadcastService
+          ├─ durable event：分配 seq，写入 journal，加入内存 tail
+          ├─ volatile event：不分配新 seq，只带当前 watermark 直接广播
+          └─ 对订阅了该 session 的 WS 连接 fan-out</pre>
+      <p>前端收到 WS frame 后：</p>
+      <pre>DaemonEventSocket
+  └─ classifyFrame / agentEventProjector / eventReducer
+      └─ 更新 rawState.messagesBySession / lastSeqBySession / status
+          └─ Vue 组件重新渲染</pre>
+      <p class="muted">durable event 推进 <code>lastSeq</code>；volatile delta（如 thinking.delta）用于实时显示，不推进 durable seq。</p>
+    </section>
+
+    <section class="card">
+      <h2>4. 发送消息：从输入框到事件流</h2>
+      <pre>Composer 提交 prompt
+  └─ POST /api/v1/sessions/{id}/prompts
+      └─ agent-core 开始处理
+          └─ 产生 message.created / turn.started / assistant.delta / tool.* / turn.ended 等事件
+              └─ 这些事件重新进入 Event Bus → WSBroadcast → WebSocket → 前端渲染</pre>
+      <p class="muted">所以“发送消息”的写入路径是 REST；发送之后看到的过程和结果，主要通过 WebSocket 事件流回来。</p>
+    </section>
+
+    <section class="card">
+      <h2>5. 什么时候会 <code>resync_required</code>？</h2>
+      <p>客户端 subscribe / client_hello 会带上自己的同步游标：</p>
+      <pre>{ seq: lastSeq, epoch: lastEpoch }</pre>
+      <p>服务端在 <code>getBufferedSince()</code> 里判断能不能继续增量回放：</p>
+      <ul>
+        <li><b>epoch 不一致</b>：客户端拿着旧 journal 的 epoch，必须重建。</li>
+        <li><b>客户端 seq 比服务端还新</b>：cursor 不可信，强制重建。</li>
+        <li><b>落后超过 1000 条 durable events</b>：回放成本太高，改用 snapshot 重建。</li>
+      </ul>
+      <pre>subscribe(cursor)
+  └─ syncSessions()
+      ├─ 先把订阅注册上（live events 可以立刻流过来）
+      └─ getBufferedSince(cursor)
+          ├─ 可回放：发送漏掉的 durable events
+          └─ 不可回放：发送 resync_required</pre>
+    </section>
+
+    <section class="card">
+      <h2>6. 实际运行形状：为什么会短时间多个 resync？</h2>
+      <p>正常应该是：</p>
+      <pre>subscribe(old cursor) → resync_required → snapshot → subscribe(new cursor)</pre>
+      <p>但前端有多条路径都会触发 subscribe，并且可能都使用旧 cursor：</p>
+      <ul>
+        <li>切回 session 时重新订阅；</li>
+        <li>WebSocket 断线重连后重新 client_hello；</li>
+        <li>路由 popstate / active session 变化；</li>
+        <li>上一次 snapshot 还没回来时，又有别的路径触发 subscribe。</li>
+      </ul>
+      <div class="timeline">
+        <div class="warn">1. 切回 running session，前端用旧 <code>lastSeq</code> subscribe。</div>
+        <div class="warn">2. 服务端发现落后太多，回 <code>resync_required</code>。</div>
+        <div>3. 旧前端开始 <code>GET /snapshot</code>。</div>
+        <div class="badstep">4. snapshot 还没回来，另一条路径又带着旧 cursor subscribe。</div>
+        <div class="badstep">5. 服务端再次回 <code>resync_required</code>。</div>
+        <div class="badstep">6. 旧前端再次 <code>GET /snapshot</code>，形成并发/堆积。</div>
+      </div>
+      <p class="muted">所以问题不是“单个 snapshot 慢”，而是多个旧 cursor 订阅触发多个 resync，多个 resync 又触发多个 snapshot。</p>
+    </section>
+
+    <section class="card">
+      <h2>7. 修复后的形状：coalesced snapshot sync</h2>
+      <p>修复加入了一个按 session 去重的 runner：</p>
+      <pre>createCoalescedAsyncRunner(syncSessionFromSnapshot)</pre>
+      <p>规则：</p>
+      <ul>
+        <li>同一个 session 已有 snapshot 在加载：不重复发起。</li>
+        <li>加载期间又来 resync：只记录“需要再跑一次”。</li>
+        <li>当前加载完成后：最多再补跑一次，拿最新状态。</li>
+      </ul>
+      <div class="timeline">
+        <div class="ok">resync_required A → 开始 snapshot #1</div>
+        <div class="ok">resync_required B → snapshot #1 还在跑，只排队一次</div>
+        <div class="ok">resync_required C → 不重复排队</div>
+        <div class="ok">snapshot #1 完成 → 再跑 snapshot #2，拿到最新水位</div>
+      </div>
+      <p class="muted">结果：最多只有 1 个 in-flight snapshot + 1 个 queued rerun，不会再出现请求风暴。</p>
+    </section>
+
+    <section class="card">
+      <h2>8. 一句话总结</h2>
+      <p>
+        <b>snapshot 是“全量重建”，WebSocket 是“增量同步”。</b>
+        当客户端 cursor 过期或落后太多时，服务端会发 <code>resync_required</code> 让前端重新 snapshot。
+        旧前端没有对同 session 的 snapshot 去重，所以短时间多次 resync 会放大成并发 snapshot 请求风暴；
+        修复后同 session 的 snapshot sync 被串行化，并最多保留一次后续刷新。
+      </p>
+    </section>
+  </main>
+</body>
+</html>
diff --git a/worktree-board-layouts.html b/worktree-board-layouts.html
new file mode 100644
index 000000000..be8295c36
--- /dev/null
+++ b/worktree-board-layouts.html
@@ -0,0 +1,233 @@
+<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+<meta charset="UTF-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1.0" />
+<title>看板布局方案 · kimi-web</title>
+<style>
+  :root {
+    --ink: #14171c; --text: #262626; --dim: #595959; --muted: #8a8a8a; --faint: #b5b5b5;
+    --line: #e7eaee; --line2: #eef1f4; --panel: #fafbfc; --panel2: #f3f5f8; --bg: #ffffff;
+    --blue: #1783ff; --blue2: #0f6fe0; --soft: #e8f3ff; --bd: #cfe6ff;
+    --ok: #0e7a38; --warn: #92660a; --err: #b91c1c;
+    --mono: "JetBrains Mono", ui-monospace, "SF Mono", Menlo, Consolas, monospace;
+    --ui: 14px; --sh: 0 4px 16px rgba(20, 23, 28, 0.08);
+  }
+  [data-dark] {
+    --ink: #e8eaed; --text: #c9cdd4; --dim: #9aa0a8; --muted: #727983; --faint: #525960;
+    --line: #2d333b; --line2: #22272e; --panel: #1c2128; --panel2: #161b22; --bg: #0d1117;
+    --blue: #58a6ff; --blue2: #79b8ff; --soft: #1f2937; --bd: #1f6feb;
+    --ok: #3fb950; --warn: #d29922; --err: #f85149;
+    --sh: 0 6px 20px rgba(0,0,0,0.35);
+  }
+  * { box-sizing: border-box; }
+  body { margin: 0; background: var(--panel); color: var(--text); font-family: var(--mono); font-size: var(--ui); line-height: 1.5; -webkit-font-smoothing: antialiased; }
+  header { padding: 16px 28px; border-bottom: 1px solid var(--line); background: var(--bg); position: sticky; top: 0; z-index: 50; display: flex; align-items: center; gap: 14px; flex-wrap: wrap; }
+  header h1 { font-size: 16px; margin: 0; color: var(--ink); font-weight: 600; }
+  header nav { display: flex; gap: 6px; margin-left: 4px; flex-wrap: wrap; }
+  header nav a { color: var(--dim); text-decoration: none; font-size: 12px; padding: 4px 10px; border: 1px solid var(--line); border-radius: 7px; }
+  header nav a:hover { color: var(--ink); border-color: var(--blue); }
+  .toggle { margin-left: auto; background: var(--panel2); color: var(--ink); border: 1px solid var(--line); border-radius: 8px; padding: 6px 12px; font-family: var(--mono); font-size: 12px; cursor: pointer; }
+  .toggle:hover { border-color: var(--blue); }
+
+  section { padding: 26px 28px; border-bottom: 1px solid var(--line); }
+  section h2 { font-size: 17px; color: var(--ink); margin: 0 0 4px; }
+  section .desc { color: var(--muted); font-size: 12px; margin: 0 0 16px; max-width: 820px; }
+  .frame { background: var(--bg); border: 1px solid var(--line); border-radius: 12px; padding: 14px; box-shadow: var(--sh); }
+
+  /* shared bits */
+  .pr { flex: none; border: 1px solid transparent; border-radius: 9px; padding: 0 6px; height: 18px; line-height: 16px; font-size: 12px; background: transparent; font-family: var(--mono); display: inline-flex; align-items: center; }
+  .pr-open { color: var(--ok); border-color: color-mix(in srgb, var(--ok) 38%, var(--bg)); }
+  .pr-merged { color: #8957e5; border-color: color-mix(in srgb, #8957e5 38%, var(--bg)); }
+  .tag { flex: none; height: 18px; border-radius: 9px; padding: 0 6px; line-height: 18px; font-size: 11px; display: inline-flex; align-items: center; border: 1px solid transparent; }
+  .tag-approve { background: color-mix(in srgb, var(--warn) 16%, var(--bg)); color: var(--warn); border-color: color-mix(in srgb, var(--warn) 38%, var(--bg)); }
+  .spin { width: 12px; height: 12px; border: 2px solid var(--line); border-top-color: var(--blue); border-radius: 50%; animation: sp .8s linear infinite; flex: none; }
+  @keyframes sp { to { transform: rotate(360deg); } }
+  .unread { width: 7px; height: 7px; border-radius: 50%; background: var(--blue); flex: none; }
+  .badge { font-size: 11px; color: var(--faint); border: 1px solid var(--line); border-radius: 8px; padding: 0 5px; }
+  .mini { font-size: 11px; color: var(--muted); }
+  .card-sess { background: var(--bg); border: 1px solid var(--line); border-radius: 8px; padding: 9px 10px; cursor: pointer; transition: border-color .12s, box-shadow .12s; }
+  .card-sess:hover { border-color: var(--blue); box-shadow: var(--sh); }
+  .card-sess .tline { display: flex; align-items: center; gap: 6px; }
+  .card-sess .t { flex: 1; min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; color: var(--ink); font-weight: 500; font-size: 13px; }
+  .card-sess .meta { display: flex; align-items: center; gap: 6px; margin-top: 6px; }
+  .card-sess .time { color: var(--faint); font-size: 11px; margin-right: auto; }
+
+  /* ===== V1 自动填充列（扁平，所有 worktree 平铺成列，自动换行填满） ===== */
+  .v1 { display: grid; grid-template-columns: repeat(auto-fill, minmax(250px, 1fr)); gap: 14px; align-items: start; }
+  .v1 .col { border: 1px solid var(--line); border-top: 3px solid var(--c); border-radius: 10px; overflow: hidden; background: var(--bg); }
+  .v1 .col-head { padding: 10px 12px; border-bottom: 1px solid var(--line); }
+  .v1 .col-head .br { color: var(--c); font-weight: 600; font-size: 13px; display: flex; align-items: center; gap: 6px; }
+  .v1 .col-head .ws { color: var(--faint); font-size: 11px; margin-top: 3px; }
+  .v1 .col-body { padding: 8px; display: flex; flex-direction: column; gap: 8px; }
+  .v1 .col-foot { padding: 8px; border-top: 1px solid var(--line); }
+  .add { width: 100%; text-align: center; color: var(--faint); font-size: 12px; padding: 6px; border: 1px dashed var(--line); border-radius: 8px; background: transparent; font-family: var(--mono); }
+
+  /* ===== V2 卡片画廊（每个 worktree 一张卡，2D 网格填满） ===== */
+  .v2 { display: grid; grid-template-columns: repeat(auto-fill, minmax(300px, 1fr)); gap: 16px; }
+  .v2 .g { border: 1px solid var(--line); border-left: 4px solid var(--c); border-radius: 10px; padding: 12px 13px; background: var(--bg); }
+  .v2 .g .head { display: flex; align-items: center; gap: 7px; }
+  .v2 .g .br { color: var(--c); font-weight: 600; font-size: 14px; }
+  .v2 .g .ws { color: var(--faint); font-size: 11px; }
+  .v2 .g .stat { display: flex; gap: 8px; margin: 8px 0; font-size: 11px; color: var(--muted); }
+  .v2 .g .sess { display: flex; flex-direction: column; gap: 5px; border-top: 1px solid var(--line); padding-top: 8px; }
+  .v2 .g .sr { display: flex; align-items: center; gap: 7px; padding: 5px 4px; border-radius: 6px; cursor: pointer; }
+  .v2 .g .sr:hover { background: var(--panel2); }
+  .v2 .g .sr .t { flex: 1; min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; color: var(--ink); font-size: 13px; }
+  .v2 .g .sr .time { color: var(--faint); font-size: 11px; }
+
+  /* ===== V3 泳道（每个 workspace 一条横向泳道，宽度填满） ===== */
+  .v3 { display: flex; flex-direction: column; gap: 12px; }
+  .v3 .lane { border: 1px solid var(--line); border-radius: 10px; overflow: hidden; background: var(--bg); }
+  .v3 .lane-head { padding: 8px 13px; border-bottom: 1px solid var(--line); font-weight: 600; color: var(--ink); font-size: 13px; display: flex; align-items: center; gap: 8px; }
+  .v3 .lane-head .path { color: var(--faint); font-size: 11px; font-weight: 400; }
+  .v3 .lane-body { display: grid; grid-template-columns: repeat(auto-fill, minmax(230px, 1fr)); gap: 10px; padding: 10px; }
+  .v3 .cell { border: 1px solid var(--line); border-top: 3px solid var(--c); border-radius: 8px; padding: 9px 10px; }
+  .v3 .cell .br { color: var(--c); font-weight: 600; font-size: 12px; display: flex; align-items: center; gap: 6px; }
+  .v3 .cell .sess { display: flex; flex-direction: column; gap: 5px; margin-top: 7px; }
+  .v3 .cell .sr { display: flex; align-items: center; gap: 6px; font-size: 12px; color: var(--ink); }
+  .v3 .cell .sr .t { flex: 1; min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+
+  /* ===== V4 紧凑表格（每行一个 worktree，最密） ===== */
+  .v4 { width: 100%; border-collapse: collapse; }
+  .v4 th { text-align: left; font-size: 11px; color: var(--faint); font-weight: 500; padding: 8px 10px; border-bottom: 1px solid var(--line); }
+  .v4 td { padding: 9px 10px; border-bottom: 1px solid var(--line); vertical-align: middle; font-size: 13px; }
+  .v4 tr:hover td { background: var(--panel2); }
+  .v4 .br { color: var(--c); font-weight: 600; display: flex; align-items: center; gap: 6px; }
+  .v4 .dot { width: 8px; height: 8px; border-radius: 50%; background: var(--c); flex: none; }
+  .v4 .ws { color: var(--dim); }
+  .v4 .sess { display: flex; flex-direction: column; gap: 3px; }
+  .v4 .sess .sr { display: flex; align-items: center; gap: 6px; font-size: 12px; color: var(--ink); }
+  .v4 .act { color: var(--blue); cursor: pointer; font-size: 12px; }
+
+  /* ===== V5 大列（更宽更饱满的列，session 卡信息更全） ===== */
+  .v5 { display: grid; grid-template-columns: repeat(auto-fill, minmax(380px, 1fr)); gap: 16px; align-items: start; }
+  .v5 .col { border: 1px solid var(--line); border-top: 3px solid var(--c); border-radius: 10px; overflow: hidden; background: var(--bg); }
+  .v5 .col-head { padding: 12px 14px; border-bottom: 1px solid var(--line); }
+  .v5 .col-head .br { color: var(--c); font-weight: 600; font-size: 15px; display: flex; align-items: center; gap: 7px; }
+  .v5 .col-head .ws { color: var(--faint); font-size: 11px; margin-top: 4px; }
+  .v5 .col-body { padding: 10px; display: flex; flex-direction: column; gap: 9px; }
+  .v5 .card-sess { padding: 11px 12px; }
+  .v5 .card-sess .preview { color: var(--muted); font-size: 11px; margin-top: 5px; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+</style>
+</head>
+<body>
+<header>
+  <h1>看板布局方案</h1>
+  <nav>
+    <a href="#v1">V1 · 自动填充列</a>
+    <a href="#v2">V2 · 卡片画廊</a>
+    <a href="#v3">V3 · 泳道</a>
+    <a href="#v4">V4 · 紧凑表格</a>
+    <a href="#v5">V5 · 大列</a>
+  </nav>
+  <button class="toggle" id="toggle">切换暗色</button>
+</header>
+
+<!-- V1 -->
+<section id="v1">
+  <h2>V1 · 自动填充列（扁平）</h2>
+  <p class="desc">所有 worktree（跨 workspace）平铺成列，按宽度自动换行填满。每列标题带 workspace 名。比「按 workspace 分段堆叠」更满，没有右侧大片空白。</p>
+  <div class="frame">
+    <div class="v1">
+      <div class="col" style="--c:oklch(0.6 0.17 250)"><div class="col-head"><div class="br">main <span class="badge">main</span></div><div class="ws">kimi-code-web</div></div><div class="col-body"><div class="card-sess"><div class="tline"><span class="spin"></span><span class="t">Refactor auth middleware</span></div><div class="meta"><span class="time">now</span></div></div></div><div class="col-foot"><button class="add">+ session</button></div></div>
+      <div class="col" style="--c:oklch(0.6 0.17 150)"><div class="col-head"><div class="br">feat-login <span class="pr pr-open">#12</span></div><div class="ws">kimi-code-web</div></div><div class="col-body"><div class="card-sess"><div class="tline"><span class="unread"></span><span class="t">Add login flow</span></div><div class="meta"><span class="time">3m</span></div></div><div class="card-sess"><div class="tline"><span class="t">Fix login redirect</span></div><div class="meta"><span class="time">12m</span></div></div></div><div class="col-foot"><button class="add">+ session</button></div></div>
+      <div class="col" style="--c:oklch(0.6 0.17 300)"><div class="col-head"><div class="br">fix-perf <span class="pr pr-merged">#8</span></div><div class="ws">kimi-code-web</div></div><div class="col-body"><div class="card-sess"><div class="tline"><span class="t">Optimize dashboard query</span><span class="tag tag-approve">Approve</span></div><div class="meta"><span class="time">28m</span></div></div></div><div class="col-foot"><button class="add">+ session</button></div></div>
+      <div class="col" style="--c:oklch(0.6 0.17 70)"><div class="col-head"><div class="br">docs</div><div class="ws">kimi-code-web</div></div><div class="col-body"><div class="card-sess"><div class="tline"><span class="t">Update API docs</span></div><div class="meta"><span class="time">1h</span></div></div></div><div class="col-foot"><button class="add">+ session</button></div></div>
+      <div class="col" style="--c:oklch(0.6 0.17 220)"><div class="col-head"><div class="br">main <span class="badge">main</span></div><div class="ws">kimi-server</div></div><div class="col-body"><div class="card-sess"><div class="tline"><span class="t">Graceful shutdown</span></div><div class="meta"><span class="time">2h</span></div></div></div><div class="col-foot"><button class="add">+ session</button></div></div>
+      <div class="col" style="--c:oklch(0.6 0.17 110)"><div class="col-head"><div class="br">feat-cache <span class="pr pr-open">#5</span></div><div class="ws">kimi-server</div></div><div class="col-body"><div class="card-sess"><div class="tline"><span class="t">Add Redis cache</span></div><div class="meta"><span class="time">40m</span></div></div></div><div class="col-foot"><button class="add">+ session</button></div></div>
+      <div class="col" style="--c:oklch(0.6 0.17 330)"><div class="col-head"><div class="br">fix-race</div><div class="ws">kimi-server</div></div><div class="col-body"><div class="card-sess"><div class="tline"><span class="t">Fix race in worker</span></div><div class="meta"><span class="time">5h</span></div></div></div><div class="col-foot"><button class="add">+ session</button></div></div>
+    </div>
+  </div>
+</section>
+
+<!-- V2 -->
+<section id="v2">
+  <h2>V2 · 卡片画廊</h2>
+  <p class="desc">每个 worktree 一张卡，2D 网格填满整个区域。卡里顶部是分支/PR/状态，下面是该 worktree 的 session 紧凑列表。最「满」，信息密度高。</p>
+  <div class="frame">
+    <div class="v2">
+      <div class="g" style="--c:oklch(0.6 0.17 250)"><div class="head"><span class="br">main</span><span class="badge">main</span><span class="ws">kimi-code-web</span></div><div class="stat"><span>clean</span><span>·</span><span>1 session</span></div><div class="sess"><div class="sr"><span class="spin"></span><span class="t">Refactor auth middleware</span><span class="time">now</span></div></div></div>
+      <div class="g" style="--c:oklch(0.6 0.17 150)"><div class="head"><span class="br">feat-login</span><span class="pr pr-open">#12</span><span class="ws">kimi-code-web</span></div><div class="stat"><span>dirty · 3 files</span><span>·</span><span>↑2</span></div><div class="sess"><div class="sr"><span class="unread"></span><span class="t">Add login flow</span><span class="time">3m</span></div><div class="sr"><span class="t">Fix login redirect</span><span class="time">12m</span></div></div></div>
+      <div class="g" style="--c:oklch(0.6 0.17 300)"><div class="head"><span class="br">fix-perf</span><span class="pr pr-merged">#8</span><span class="ws">kimi-code-web</span></div><div class="stat"><span>clean</span></div><div class="sess"><div class="sr"><span class="t">Optimize dashboard query</span><span class="tag tag-approve">Approve</span><span class="time">28m</span></div></div></div>
+      <div class="g" style="--c:oklch(0.6 0.17 70)"><div class="head"><span class="br">docs</span><span class="ws">kimi-code-web</span></div><div class="stat"><span>dirty · 1 file</span></div><div class="sess"><div class="sr"><span class="t">Update API docs</span><span class="time">1h</span></div></div></div>
+      <div class="g" style="--c:oklch(0.6 0.17 220)"><div class="head"><span class="br">main</span><span class="badge">main</span><span class="ws">kimi-server</span></div><div class="stat"><span>clean</span></div><div class="sess"><div class="sr"><span class="t">Graceful shutdown</span><span class="time">2h</span></div></div></div>
+      <div class="g" style="--c:oklch(0.6 0.17 110)"><div class="head"><span class="br">feat-cache</span><span class="pr pr-open">#5</span><span class="ws">kimi-server</span></div><div class="stat"><span>dirty · 2 files</span></div><div class="sess"><div class="sr"><span class="t">Add Redis cache</span><span class="time">40m</span></div></div></div>
+      <div class="g" style="--c:oklch(0.6 0.17 330)"><div class="head"><span class="br">fix-race</span><span class="ws">kimi-server</span></div><div class="stat"><span>clean</span></div><div class="sess"><div class="sr"><span class="t">Fix race in worker</span><span class="time">5h</span></div></div></div>
+    </div>
+  </div>
+</section>
+
+<!-- V3 -->
+<section id="v3">
+  <h2>V3 · 泳道（每个 workspace 一条）</h2>
+  <p class="desc">每个 workspace 一条横向泳道，宽度填满；泳道内 worktree 单元格自动换行。既保留 workspace 分组，又填满宽度，不会像「分段堆叠窄列」那样空。</p>
+  <div class="frame">
+    <div class="v3">
+      <div class="lane">
+        <div class="lane-head">kimi-code-web <span class="path">~/code/kimi-code-web</span></div>
+        <div class="lane-body">
+          <div class="cell" style="--c:oklch(0.6 0.17 250)"><div class="br">main <span class="badge">main</span></div><div class="sess"><div class="sr"><span class="spin"></span><span class="t">Refactor auth middleware</span></div></div></div>
+          <div class="cell" style="--c:oklch(0.6 0.17 150)"><div class="br">feat-login <span class="pr pr-open">#12</span></div><div class="sess"><div class="sr"><span class="unread"></span><span class="t">Add login flow</span></div><div class="sr"><span class="t">Fix login redirect</span></div></div></div>
+          <div class="cell" style="--c:oklch(0.6 0.17 300)"><div class="br">fix-perf <span class="pr pr-merged">#8</span></div><div class="sess"><div class="sr"><span class="t">Optimize dashboard query</span><span class="tag tag-approve">Approve</span></div></div></div>
+          <div class="cell" style="--c:oklch(0.6 0.17 70)"><div class="br">docs</div><div class="sess"><div class="sr"><span class="t">Update API docs</span></div></div></div>
+        </div>
+      </div>
+      <div class="lane">
+        <div class="lane-head">kimi-server <span class="path">~/code/kimi-server</span></div>
+        <div class="lane-body">
+          <div class="cell" style="--c:oklch(0.6 0.17 220)"><div class="br">main <span class="badge">main</span></div><div class="sess"><div class="sr"><span class="t">Graceful shutdown</span></div></div></div>
+          <div class="cell" style="--c:oklch(0.6 0.17 110)"><div class="br">feat-cache <span class="pr pr-open">#5</span></div><div class="sess"><div class="sr"><span class="t">Add Redis cache</span></div></div></div>
+          <div class="cell" style="--c:oklch(0.6 0.17 330)"><div class="br">fix-race</div><div class="sess"><div class="sr"><span class="t">Fix race in worker</span></div></div></div>
+        </div>
+      </div>
+    </div>
+  </div>
+</section>
+
+<!-- V4 -->
+<section id="v4">
+  <h2>V4 · 紧凑表格</h2>
+  <p class="desc">每行一个 worktree，最密、最不空。列：分支 / workspace / PR / 状态 / session / 操作。适合 worktree 很多时快速扫描。</p>
+  <div class="frame">
+    <table class="v4">
+      <thead><tr><th>分支</th><th>workspace</th><th>PR</th><th>状态</th><th>session</th><th></th></tr></thead>
+      <tbody>
+        <tr style="--c:oklch(0.6 0.17 250)"><td><span class="br"><span class="dot"></span>main <span class="badge">main</span></span></td><td class="ws">kimi-code-web</td><td></td><td class="mini">clean</td><td><div class="sess"><div class="sr"><span class="spin"></span>Refactor auth middleware</div></div></td><td><span class="act">+ session</span></td></tr>
+        <tr style="--c:oklch(0.6 0.17 150)"><td><span class="br"><span class="dot"></span>feat-login</span></td><td class="ws">kimi-code-web</td><td><span class="pr pr-open">#12</span></td><td class="mini">dirty · 3 · ↑2</td><td><div class="sess"><div class="sr"><span class="unread"></span>Add login flow</div><div class="sr">Fix login redirect</div></div></td><td><span class="act">+ session</span></td></tr>
+        <tr style="--c:oklch(0.6 0.17 300)"><td><span class="br"><span class="dot"></span>fix-perf</span></td><td class="ws">kimi-code-web</td><td><span class="pr pr-merged">#8</span></td><td class="mini">clean</td><td><div class="sess"><div class="sr">Optimize dashboard query <span class="tag tag-approve">Approve</span></div></div></td><td><span class="act">+ session</span></td></tr>
+        <tr style="--c:oklch(0.6 0.17 70)"><td><span class="br"><span class="dot"></span>docs</span></td><td class="ws">kimi-code-web</td><td></td><td class="mini">dirty · 1</td><td><div class="sess"><div class="sr">Update API docs</div></div></td><td><span class="act">+ session</span></td></tr>
+        <tr style="--c:oklch(0.6 0.17 220)"><td><span class="br"><span class="dot"></span>main <span class="badge">main</span></span></td><td class="ws">kimi-server</td><td></td><td class="mini">clean</td><td><div class="sess"><div class="sr">Graceful shutdown</div></div></td><td><span class="act">+ session</span></td></tr>
+        <tr style="--c:oklch(0.6 0.17 110)"><td><span class="br"><span class="dot"></span>feat-cache</span></td><td class="ws">kimi-server</td><td><span class="pr pr-open">#5</span></td><td class="mini">dirty · 2</td><td><div class="sess"><div class="sr">Add Redis cache</div></div></td><td><span class="act">+ session</span></td></tr>
+        <tr style="--c:oklch(0.6 0.17 330)"><td><span class="br"><span class="dot"></span>fix-race</span></td><td class="ws">kimi-server</td><td></td><td class="mini">clean</td><td><div class="sess"><div class="sr">Fix race in worker</div></div></td><td><span class="act">+ session</span></td></tr>
+      </tbody>
+    </table>
+  </div>
+</section>
+
+<!-- V5 -->
+<section id="v5">
+  <h2>V5 · 大列（更宽更饱满）</h2>
+  <p class="desc">更宽的列（约 380px），session 卡信息更全（带最后一条 prompt 预览），列数少一些但每列更饱满，减少「很多小空列」的感觉。</p>
+  <div class="frame">
+    <div class="v5">
+      <div class="col" style="--c:oklch(0.6 0.17 250)"><div class="col-head"><div class="br">main <span class="badge">main</span></div><div class="ws">kimi-code-web</div></div><div class="col-body"><div class="card-sess"><div class="tline"><span class="spin"></span><span class="t">Refactor auth middleware</span></div><div class="preview">正在编辑 src/auth.ts …</div><div class="meta"><span class="time">now</span></div></div></div></div>
+      <div class="col" style="--c:oklch(0.6 0.17 150)"><div class="col-head"><div class="br">feat-login <span class="pr pr-open">#12</span></div><div class="ws">kimi-code-web</div></div><div class="col-body"><div class="card-sess"><div class="tline"><span class="unread"></span><span class="t">Add login flow</span></div><div class="preview">完成 OAuth 回调处理</div><div class="meta"><span class="time">3m</span></div></div><div class="card-sess"><div class="tline"><span class="t">Fix login redirect</span></div><div class="preview">redirect_uri 白名单</div><div class="meta"><span class="time">12m</span></div></div></div></div>
+      <div class="col" style="--c:oklch(0.6 0.17 300)"><div class="col-head"><div class="br">fix-perf <span class="pr pr-merged">#8</span></div><div class="ws">kimi-code-web</div></div><div class="col-body"><div class="card-sess"><div class="tline"><span class="t">Optimize dashboard query</span><span class="tag tag-approve">Approve</span></div><div class="preview">需要审批: prisma migrate</div><div class="meta"><span class="time">28m</span></div></div></div></div>
+      <div class="col" style="--c:oklch(0.6 0.17 70)"><div class="col-head"><div class="br">docs</div><div class="ws">kimi-code-web</div></div><div class="col-body"><div class="card-sess"><div class="tline"><span class="t">Update API docs</span></div><div class="preview">补充 worktree 端点说明</div><div class="meta"><span class="time">1h</span></div></div></div></div>
+      <div class="col" style="--c:oklch(0.6 0.17 220)"><div class="col-head"><div class="br">main <span class="badge">main</span></div><div class="ws">kimi-server</div></div><div class="col-body"><div class="card-sess"><div class="tline"><span class="t">Graceful shutdown</span></div><div class="preview">SIGTERM 处理</div><div class="meta"><span class="time">2h</span></div></div></div></div>
+      <div class="col" style="--c:oklch(0.6 0.17 110)"><div class="col-head"><div class="br">feat-cache <span class="pr pr-open">#5</span></div><div class="ws">kimi-server</div></div><div class="col-body"><div class="card-sess"><div class="tline"><span class="t">Add Redis cache</span></div><div class="preview">cache-aside 策略</div><div class="meta"><span class="time">40m</span></div></div></div></div>
+    </div>
+  </div>
+</section>
+
+<script>
+  const root = document.documentElement;
+  document.getElementById('toggle').addEventListener('click', (e) => {
+    const dark = root.hasAttribute('data-dark');
+    if (dark) { root.removeAttribute('data-dark'); e.target.textContent = '切换暗色'; }
+    else { root.setAttribute('data-dark', ''); e.target.textContent = '切换亮色'; }
+  });
+</script>
+</body>
+</html>
diff --git a/worktree-marker-options.html b/worktree-marker-options.html
new file mode 100644
index 000000000..92d0faa8e
--- /dev/null
+++ b/worktree-marker-options.html
@@ -0,0 +1,300 @@
+<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+<meta charset="UTF-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1.0" />
+<title>Session 颜色标记方案对比 · kimi-web</title>
+<style>
+  :root {
+    --ink: #14171c; --text: #262626; --dim: #595959; --muted: #8a8a8a; --faint: #b5b5b5;
+    --line: #e7eaee; --line2: #eef1f4; --panel: #fafbfc; --panel2: #f3f5f8; --bg: #ffffff;
+    --blue: #1783ff; --blue2: #0f6fe0; --soft: #e8f3ff; --bd: #cfe6ff;
+    --ok: #0e7a38; --warn: #92660a; --err: #b91c1c;
+    --mono: "JetBrains Mono", ui-monospace, "SF Mono", Menlo, Consolas, monospace;
+    --ui: 14px;
+  }
+  [data-dark] {
+    --ink: #e8eaed; --text: #c9cdd4; --dim: #9aa0a8; --muted: #727983; --faint: #525960;
+    --line: #2d333b; --line2: #22272e; --panel: #1c2128; --panel2: #161b22; --bg: #0d1117;
+    --blue: #58a6ff; --blue2: #79b8ff; --soft: #1f2937; --bd: #1f6feb;
+    --ok: #3fb950; --warn: #d29922; --err: #f85149;
+  }
+
+  * { box-sizing: border-box; }
+  body {
+    margin: 0; background: var(--panel); color: var(--text);
+    font-family: var(--mono); font-size: var(--ui); line-height: 1.5;
+    -webkit-font-smoothing: antialiased;
+    transition: background .2s, color .2s;
+  }
+  header {
+    padding: 22px 28px 14px; border-bottom: 1px solid var(--line);
+    display: flex; align-items: center; gap: 16px; background: var(--bg);
+    position: sticky; top: 0; z-index: 10;
+  }
+  header h1 { font-size: 16px; margin: 0; color: var(--ink); font-weight: 600; }
+  header p { margin: 0; color: var(--muted); font-size: 12px; }
+  .toggle {
+    margin-left: auto; background: var(--panel2); color: var(--ink); border: 1px solid var(--line);
+    border-radius: 8px; padding: 6px 12px; font-family: var(--mono); font-size: 12px; cursor: pointer;
+  }
+  .toggle:hover { border-color: var(--blue); }
+
+  .grid {
+    display: grid; grid-template-columns: repeat(auto-fill, minmax(300px, 1fr));
+    gap: 18px; padding: 22px 28px 40px;
+  }
+  .card { display: flex; flex-direction: column; }
+  .card .meta { margin-bottom: 8px; }
+  .card .meta h2 { font-size: 13px; margin: 0 0 2px; color: var(--ink); font-weight: 600; }
+  .card .meta h2 .no { color: var(--blue); margin-right: 6px; }
+  .card .meta p { font-size: 11px; color: var(--muted); margin: 0; }
+
+  /* ---- the mini sidebar ---- */
+  .side {
+    border: 1px solid var(--line); border-radius: 10px; background: var(--bg);
+    overflow: hidden; padding-bottom: 8px;
+  }
+  .gh { padding: 10px 12px 4px; }
+  .gh-top { display: flex; align-items: center; gap: 6px; }
+  .gh-folder { color: var(--muted); flex: none; }
+  .gh-name { flex: 1; font-weight: 500; color: var(--ink); overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+  .gh-add { color: var(--faint); flex: none; }
+  .gh-path { color: var(--faint); font-size: 12px; padding-left: 22px; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+
+  /* ---- base session row ---- */
+  .se {
+    display: flex; align-items: center; gap: 6px; padding: 7px 12px; cursor: pointer;
+    position: relative; color: var(--text);
+  }
+  .se:hover { background: var(--panel2); }
+  .lead { width: 16px; flex: none; display: inline-flex; align-items: center; justify-content: center; }
+  .spin { width: 12px; height: 12px; border: 2px solid var(--line); border-top-color: var(--blue); border-radius: 50%; animation: sp .8s linear infinite; }
+  @keyframes sp { to { transform: rotate(360deg); } }
+  .unread { width: 7px; height: 7px; border-radius: 50%; background: var(--blue); }
+  .t { flex: 1; min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; color: var(--ink); }
+  .ts { color: var(--muted); font-size: 11px; flex: none; }
+  .se:hover .ts { display: none; }
+  .pr {
+    flex: none; border: 1px solid transparent; border-radius: 9px; padding: 0 6px; height: 18px; line-height: 16px;
+    font-size: 12px; background: transparent; cursor: pointer; font-family: var(--mono);
+  }
+  .pr-open { color: var(--ok); border-color: color-mix(in srgb, var(--ok) 38%, var(--bg)); }
+  .pr-merged { color: #8957e5; border-color: color-mix(in srgb, #8957e5 38%, var(--bg)); }
+  .tag { flex: none; height: 18px; border-radius: 9px; padding: 0 6px; line-height: 18px; font-size: 12px;
+    background: color-mix(in srgb, var(--warn) 16%, var(--bg)); color: var(--warn); border: 1px solid color-mix(in srgb, var(--warn) 38%, var(--bg)); }
+
+  /* per-row color variable */
+  .se { --c: transparent; }
+
+  /* ===== A: leading dot ===== */
+  .A .dot { width: 8px; height: 8px; border-radius: 50%; flex: none; background: var(--c); }
+
+  /* ===== B: left bar ===== */
+  .B .se { border-left: 3px solid var(--c); padding-left: 9px; }
+  .B .se.on { background: color-mix(in srgb, var(--c) 8%, transparent); }
+
+  /* ===== C: row tint ===== */
+  .C .se { background: color-mix(in srgb, var(--c) 7%, transparent); }
+  .C .se:hover { background: color-mix(in srgb, var(--c) 13%, transparent); }
+  .C .se.on { background: color-mix(in srgb, var(--c) 18%, transparent); }
+
+  /* ===== D: colored pill ===== */
+  .D .pill {
+    flex: none; max-width: 40%; overflow: hidden; text-overflow: ellipsis; white-space: nowrap;
+    background: var(--c); color: #fff; border-radius: 8px; padding: 0 7px; height: 18px; line-height: 18px; font-size: 11px;
+  }
+  [data-dark] .D .pill { color: #0d1117; }
+
+  /* ===== E: initial badge ===== */
+  .E .badge {
+    flex: none; width: 18px; height: 18px; border-radius: 5px; background: var(--c); color: #fff;
+    font-size: 10px; font-weight: 600; display: inline-flex; align-items: center; justify-content: center;
+  }
+  [data-dark] .E .badge { color: #0d1117; }
+
+  /* ===== F: wide gutter strip ===== */
+  .F .se { box-shadow: inset 6px 0 0 var(--c); padding-left: 14px; }
+  .F .se.on { background: color-mix(in srgb, var(--c) 8%, transparent); }
+
+  /* ===== G: two-line ===== */
+  .G .se { align-items: flex-start; padding-top: 8px; padding-bottom: 8px; }
+  .G .col { flex: 1; min-width: 0; display: flex; flex-direction: column; gap: 2px; }
+  .G .tline { display: flex; align-items: center; gap: 6px; }
+  .G .sub { display: flex; align-items: center; gap: 5px; padding-left: 22px; }
+  .G .dot { width: 7px; height: 7px; border-radius: 50%; background: var(--c); flex: none; }
+  .G .brname { color: var(--muted); font-size: 11px; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+
+  /* ===== H: right tab ===== */
+  .H .se::after {
+    content: ""; position: absolute; right: 0; top: 7px; bottom: 7px; width: 4px; border-radius: 3px; background: var(--c);
+  }
+  .H .se.on { background: color-mix(in srgb, var(--c) 7%, transparent); }
+
+  /* ===== I: grouped under labeled dividers (lightweight, no card) ===== */
+  .I .grp { margin-top: 8px; }
+  .I .grp:first-child { margin-top: 0; }
+  .I .grp-h { display: flex; align-items: center; gap: 6px; padding: 3px 12px 3px 34px; background: none; border: none; font-size: 12px; color: var(--c); font-weight: 600; }
+  .I .grp-h .ln { flex: 1; height: 1px; background: color-mix(in srgb, var(--c) 45%, var(--line)); }
+  .I .grp-h .badge { font-size: 11px; color: var(--faint); border: 1px solid var(--line); border-radius: 8px; padding: 0 5px; line-height: 14px; font-weight: 400; }
+  .I .se { padding-left: 12px; padding-right: 12px; }
+
+  /* legend */
+  .legend { padding: 0 28px 30px; color: var(--muted); font-size: 12px; }
+  .legend .sw { display: inline-flex; align-items: center; gap: 6px; margin-right: 16px; }
+  .legend .sw i { width: 9px; height: 9px; border-radius: 50%; display: inline-block; }
+</style>
+</head>
+<body>
+<header>
+  <div>
+    <h1>Session 颜色标记方案对比</h1>
+    <p>同一组 session、同一组 worktree/分支，用 9 种方式标记。颜色由分支名派生（同色 = 同一 worktree）。</p>
+  </div>
+  <button class="toggle" id="toggle">切换暗色</button>
+</header>
+
+<div class="grid">
+
+  <!-- A -->
+  <div class="card">
+    <div class="meta"><h2><span class="no">A</span>标题前彩色圆点</h2><p>最小侵入，标题对齐稳定；颜色信息量最小。</p></div>
+    <div class="side A">
+      <div class="gh"><div class="gh-top"><span class="gh-folder">▾</span><span class="gh-name">kimi-code-web</span><span class="gh-add">＋</span></div><div class="gh-path">~/code/kimi-code-web</div></div>
+      <div class="se on" style="--c:#1783ff"><span class="lead"><span class="spin"></span></span><span class="dot"></span><span class="t">Refactor auth middleware</span></div>
+      <div class="se" style="--c:#2e7d32"><span class="lead"><span class="unread"></span></span><span class="dot"></span><span class="t">Add login flow</span><span class="pr pr-open">#12</span></div>
+      <div class="se" style="--c:#2e7d32"><span class="lead"></span><span class="dot"></span><span class="t">Fix login redirect</span></div>
+      <div class="se" style="--c:#c62828"><span class="lead"></span><span class="dot"></span><span class="t">Optimize dashboard query</span><span class="tag">Approve</span><span class="pr pr-merged">#8</span></div>
+      <div class="se" style="--c:#6a1b9a"><span class="lead"></span><span class="dot"></span><span class="t">Update API docs</span></div>
+    </div>
+  </div>
+
+  <!-- B -->
+  <div class="card">
+    <div class="meta"><h2><span class="no">B</span>左侧彩色竖条</h2><p>整行左边一条色带，分组感强、识别快。</p></div>
+    <div class="side B">
+      <div class="gh"><div class="gh-top"><span class="gh-folder">▾</span><span class="gh-name">kimi-code-web</span><span class="gh-add">＋</span></div><div class="gh-path">~/code/kimi-code-web</div></div>
+      <div class="se on" style="--c:#1783ff"><span class="lead"><span class="spin"></span></span><span class="t">Refactor auth middleware</span></div>
+      <div class="se" style="--c:#2e7d32"><span class="lead"><span class="unread"></span></span><span class="t">Add login flow</span><span class="pr pr-open">#12</span></div>
+      <div class="se" style="--c:#2e7d32"><span class="lead"></span><span class="t">Fix login redirect</span></div>
+      <div class="se" style="--c:#c62828"><span class="lead"></span><span class="t">Optimize dashboard query</span><span class="tag">Approve</span><span class="pr pr-merged">#8</span></div>
+      <div class="se" style="--c:#6a1b9a"><span class="lead"></span><span class="t">Update API docs</span></div>
+    </div>
+  </div>
+
+  <!-- C -->
+  <div class="card">
+    <div class="meta"><h2><span class="no">C</span>整行浅色着色</h2><p>整行染上分支色的浅色，分组最强；颜色多时会显花。</p></div>
+    <div class="side C">
+      <div class="gh"><div class="gh-top"><span class="gh-folder">▾</span><span class="gh-name">kimi-code-web</span><span class="gh-add">＋</span></div><div class="gh-path">~/code/kimi-code-web</div></div>
+      <div class="se on" style="--c:#1783ff"><span class="lead"><span class="spin"></span></span><span class="t">Refactor auth middleware</span></div>
+      <div class="se" style="--c:#2e7d32"><span class="lead"><span class="unread"></span></span><span class="t">Add login flow</span><span class="pr pr-open">#12</span></div>
+      <div class="se" style="--c:#2e7d32"><span class="lead"></span><span class="t">Fix login redirect</span></div>
+      <div class="se" style="--c:#c62828"><span class="lead"></span><span class="t">Optimize dashboard query</span><span class="tag">Approve</span><span class="pr pr-merged">#8</span></div>
+      <div class="se" style="--c:#6a1b9a"><span class="lead"></span><span class="t">Update API docs</span></div>
+    </div>
+  </div>
+
+  <!-- D -->
+  <div class="card">
+    <div class="meta"><h2><span class="no">D</span>彩色分支胶囊</h2><p>分支名做成彩色胶囊，可读分支名；占空间、长名会截断。</p></div>
+    <div class="side D">
+      <div class="gh"><div class="gh-top"><span class="gh-folder">▾</span><span class="gh-name">kimi-code-web</span><span class="gh-add">＋</span></div><div class="gh-path">~/code/kimi-code-web</div></div>
+      <div class="se on" style="--c:#1783ff"><span class="lead"><span class="spin"></span></span><span class="t">Refactor auth middleware</span><span class="pill">main</span></div>
+      <div class="se" style="--c:#2e7d32"><span class="lead"><span class="unread"></span></span><span class="t">Add login flow</span><span class="pill">feat-login</span><span class="pr pr-open">#12</span></div>
+      <div class="se" style="--c:#2e7d32"><span class="lead"></span><span class="t">Fix login redirect</span><span class="pill">feat-login</span></div>
+      <div class="se" style="--c:#c62828"><span class="lead"></span><span class="t">Optimize dashboard query</span><span class="pill">fix-perf</span><span class="tag">Approve</span><span class="pr pr-merged">#8</span></div>
+      <div class="se" style="--c:#6a1b9a"><span class="lead"></span><span class="t">Update API docs</span><span class="pill">docs</span></div>
+    </div>
+  </div>
+
+  <!-- E -->
+  <div class="card">
+    <div class="meta"><h2><span class="no">E</span>分支首字母徽章</h2><p>彩色方块 + 分支首字母，紧凑且有字符提示；首字母会撞。</p></div>
+    <div class="side E">
+      <div class="gh"><div class="gh-top"><span class="gh-folder">▾</span><span class="gh-name">kimi-code-web</span><span class="gh-add">＋</span></div><div class="gh-path">~/code/kimi-code-web</div></div>
+      <div class="se on" style="--c:#1783ff"><span class="badge">M</span><span class="t">Refactor auth middleware</span><span class="lead"><span class="spin"></span></span></div>
+      <div class="se" style="--c:#2e7d32"><span class="badge">F</span><span class="t">Add login flow</span><span class="lead"><span class="unread"></span></span><span class="pr pr-open">#12</span></div>
+      <div class="se" style="--c:#2e7d32"><span class="badge">F</span><span class="t">Fix login redirect</span></div>
+      <div class="se" style="--c:#c62828"><span class="badge">F</span><span class="t">Optimize dashboard query</span><span class="tag">Approve</span><span class="pr pr-merged">#8</span></div>
+      <div class="se" style="--c:#6a1b9a"><span class="badge">D</span><span class="t">Update API docs</span></div>
+    </div>
+  </div>
+
+  <!-- F -->
+  <div class="card">
+    <div class="meta"><h2><span class="no">F</span>宽左侧色带</h2><p>更粗的左侧色带（inset shadow），比 B 更醒目。</p></div>
+    <div class="side F">
+      <div class="gh"><div class="gh-top"><span class="gh-folder">▾</span><span class="gh-name">kimi-code-web</span><span class="gh-add">＋</span></div><div class="gh-path">~/code/kimi-code-web</div></div>
+      <div class="se on" style="--c:#1783ff"><span class="lead"><span class="spin"></span></span><span class="t">Refactor auth middleware</span></div>
+      <div class="se" style="--c:#2e7d32"><span class="lead"><span class="unread"></span></span><span class="t">Add login flow</span><span class="pr pr-open">#12</span></div>
+      <div class="se" style="--c:#2e7d32"><span class="lead"></span><span class="t">Fix login redirect</span></div>
+      <div class="se" style="--c:#c62828"><span class="lead"></span><span class="t">Optimize dashboard query</span><span class="tag">Approve</span><span class="pr pr-merged">#8</span></div>
+      <div class="se" style="--c:#6a1b9a"><span class="lead"></span><span class="t">Update API docs</span></div>
+    </div>
+  </div>
+
+  <!-- G -->
+  <div class="card">
+    <div class="meta"><h2><span class="no">G</span>双行：圆点 + 分支小字</h2><p>标题下面一行小字分支名 + 圆点，信息全；行变高。</p></div>
+    <div class="side G">
+      <div class="gh"><div class="gh-top"><span class="gh-folder">▾</span><span class="gh-name">kimi-code-web</span><span class="gh-add">＋</span></div><div class="gh-path">~/code/kimi-code-web</div></div>
+      <div class="se on" style="--c:#1783ff"><span class="lead"><span class="spin"></span></span><div class="col"><div class="tline"><span class="t">Refactor auth middleware</span></div><div class="sub"><span class="dot"></span><span class="brname">main</span></div></div></div>
+      <div class="se" style="--c:#2e7d32"><span class="lead"><span class="unread"></span></span><div class="col"><div class="tline"><span class="t">Add login flow</span><span class="pr pr-open">#12</span></div><div class="sub"><span class="dot"></span><span class="brname">feat-login</span></div></div></div>
+      <div class="se" style="--c:#2e7d32"><span class="lead"></span><div class="col"><div class="tline"><span class="t">Fix login redirect</span></div><div class="sub"><span class="dot"></span><span class="brname">feat-login</span></div></div></div>
+      <div class="se" style="--c:#c62828"><span class="lead"></span><div class="col"><div class="tline"><span class="t">Optimize dashboard query</span><span class="tag">Approve</span><span class="pr pr-merged">#8</span></div><div class="sub"><span class="dot"></span><span class="brname">fix-perf</span></div></div></div>
+      <div class="se" style="--c:#6a1b9a"><span class="lead"></span><div class="col"><div class="tline"><span class="t">Update API docs</span></div><div class="sub"><span class="dot"></span><span class="brname">docs</span></div></div></div>
+    </div>
+  </div>
+
+  <!-- H -->
+  <div class="card">
+    <div class="meta"><h2><span class="no">H</span>右侧彩色小 tab</h2><p>右侧一条小色块，不挤标题；hover 时才明显的克制方案。</p></div>
+    <div class="side H">
+      <div class="gh"><div class="gh-top"><span class="gh-folder">▾</span><span class="gh-name">kimi-code-web</span><span class="gh-add">＋</span></div><div class="gh-path">~/code/kimi-code-web</div></div>
+      <div class="se on" style="--c:#1783ff"><span class="lead"><span class="spin"></span></span><span class="t">Refactor auth middleware</span></div>
+      <div class="se" style="--c:#2e7d32"><span class="lead"><span class="unread"></span></span><span class="t">Add login flow</span><span class="pr pr-open">#12</span></div>
+      <div class="se" style="--c:#2e7d32"><span class="lead"></span><span class="t">Fix login redirect</span></div>
+      <div class="se" style="--c:#c62828"><span class="lead"></span><span class="t">Optimize dashboard query</span><span class="tag">Approve</span><span class="pr pr-merged">#8</span></div>
+      <div class="se" style="--c:#6a1b9a"><span class="lead"></span><span class="t">Update API docs</span></div>
+    </div>
+  </div>
+
+  <!-- I -->
+  <div class="card">
+    <div class="meta"><h2><span class="no">I</span>按 worktree 分组（细分隔线 + 等明度区分色）</h2><p>每组一条带分支名的小标题 + 尾部细线，颜色用 OKLCH 固定明度/彩度、只变色调：亮度一致、区分度大、无纯红。session 行保持干净。</p></div>
+    <div class="side I">
+      <div class="gh"><div class="gh-top"><span class="gh-folder">▾</span><span class="gh-name">kimi-code-web</span><span class="gh-add">＋</span></div><div class="gh-path">~/code/kimi-code-web</div></div>
+      <div class="grp" style="--c:oklch(0.6 0.17 250)"><div class="grp-h">main<span class="badge">main</span><span class="ln"></span></div>
+        <div class="se on"><span class="lead"><span class="spin"></span></span><span class="t">Refactor auth middleware</span></div></div>
+      <div class="grp" style="--c:oklch(0.6 0.17 150)"><div class="grp-h">feat-login<span class="ln"></span><span class="pr pr-open">#12</span></div>
+        <div class="se"><span class="lead"><span class="unread"></span></span><span class="t">Add login flow</span></div>
+        <div class="se"><span class="lead"></span><span class="t">Fix login redirect</span></div></div>
+      <div class="grp" style="--c:oklch(0.6 0.17 300)"><div class="grp-h">fix-perf<span class="ln"></span><span class="pr pr-merged">#8</span></div>
+        <div class="se"><span class="lead"></span><span class="t">Optimize dashboard query</span><span class="tag">Approve</span></div></div>
+      <div class="grp" style="--c:oklch(0.6 0.17 70)"><div class="grp-h">docs<span class="ln"></span></div>
+        <div class="se"><span class="lead"></span><span class="t">Update API docs</span></div></div>
+    </div>
+  </div>
+
+</div>
+
+<div class="legend">
+  <strong style="color:var(--ink)">颜色图例（OKLCH 等明度 / 等彩度，仅变色调，无纯红）：</strong>
+  <span class="sw"><i style="background:oklch(0.6 0.17 250)"></i>main</span>
+  <span class="sw"><i style="background:oklch(0.6 0.17 150)"></i>feat-login（2 个 session 同色）</span>
+  <span class="sw"><i style="background:oklch(0.6 0.17 300)"></i>fix-perf</span>
+  <span class="sw"><i style="background:oklch(0.6 0.17 70)"></i>docs</span>
+</div>
+
+<script>
+  const root = document.documentElement;
+  const btn = document.getElementById('toggle');
+  btn.addEventListener('click', () => {
+    const dark = root.hasAttribute('data-dark');
+    if (dark) { root.removeAttribute('data-dark'); btn.textContent = '切换暗色'; }
+    else { root.setAttribute('data-dark', ''); btn.textContent = '切换亮色'; }
+  });
+</script>
+</body>
+</html>
diff --git a/worktree-sidebar.html b/worktree-sidebar.html
new file mode 100644
index 000000000..70e13f499
--- /dev/null
+++ b/worktree-sidebar.html
@@ -0,0 +1,143 @@
+<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+<meta charset="UTF-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1.0" />
+<title>侧边栏 · worktree 维度 · kimi-web</title>
+<style>
+  :root {
+    --ink: #14171c; --text: #262626; --dim: #595959; --muted: #8a8a8a; --faint: #b5b5b5;
+    --line: #e7eaee; --line2: #eef1f4; --panel: #fafbfc; --panel2: #f3f5f8; --bg: #ffffff;
+    --blue: #1783ff; --blue2: #0f6fe0; --soft: #e8f3ff; --bd: #cfe6ff;
+    --ok: #0e7a38; --warn: #92660a; --err: #b91c1c;
+    --mono: "JetBrains Mono", ui-monospace, "SF Mono", Menlo, Consolas, monospace;
+    --ui: 14px;
+  }
+  [data-dark] {
+    --ink: #e8eaed; --text: #c9cdd4; --dim: #9aa0a8; --muted: #727983; --faint: #525960;
+    --line: #2d333b; --line2: #22272e; --panel: #1c2128; --panel2: #161b22; --bg: #0d1117;
+    --blue: #58a6ff; --blue2: #79b8ff; --soft: #1f2937; --bd: #1f6feb;
+    --ok: #3fb950; --warn: #d29922; --err: #f85149;
+  }
+  * { box-sizing: border-box; }
+  body { margin: 0; background: var(--panel); color: var(--text); font-family: var(--mono); font-size: var(--ui); line-height: 1.5; -webkit-font-smoothing: antialiased; }
+  header { padding: 16px 28px; border-bottom: 1px solid var(--line); background: var(--bg); display: flex; align-items: center; gap: 14px; }
+  header h1 { font-size: 16px; margin: 0; color: var(--ink); font-weight: 600; }
+  header p { margin: 0; color: var(--muted); font-size: 12px; }
+  .toggle { margin-left: auto; background: var(--panel2); color: var(--ink); border: 1px solid var(--line); border-radius: 8px; padding: 6px 12px; font-family: var(--mono); font-size: 12px; cursor: pointer; }
+  .wrap { display: flex; gap: 28px; padding: 28px; align-items: flex-start; flex-wrap: wrap; }
+
+  /* sidebar shell */
+  .side { width: 300px; background: var(--bg); border: 1px solid var(--line); border-radius: 12px; overflow: hidden; }
+  .side-head { padding: 12px 12px 8px; border-bottom: 1px solid var(--line); display: flex; gap: 8px; }
+  .btn-new { flex: 1; display: inline-flex; align-items: center; gap: 8px; padding: 9px 10px; border: 1px solid var(--line); border-radius: 8px; background: transparent; color: var(--dim); font-family: var(--mono); font-size: 13px; cursor: pointer; }
+  .btn-icon { flex: none; width: 38px; justify-content: center; }
+  .btn-new:hover { background: var(--panel2); border-color: var(--bd); color: var(--ink); }
+  .label { font-size: 11px; color: var(--faint); padding: 10px 14px 4px; }
+  .divider { height: 1px; background: var(--line); margin: 6px 12px; }
+
+  .pr { flex: none; border: 1px solid transparent; border-radius: 9px; padding: 0 6px; height: 18px; line-height: 16px; font-size: 12px; background: transparent; font-family: var(--mono); display: inline-flex; align-items: center; }
+  .pr-open { color: var(--ok); border-color: color-mix(in srgb, var(--ok) 38%, var(--bg)); }
+  .pr-merged { color: #8957e5; border-color: color-mix(in srgb, #8957e5 38%, var(--bg)); }
+  .tag { flex: none; height: 18px; border-radius: 9px; padding: 0 6px; line-height: 18px; font-size: 11px; display: inline-flex; align-items: center; border: 1px solid transparent; }
+  .tag-ask { background: var(--soft); color: var(--blue2); border-color: var(--bd); }
+  .tag-approve { background: color-mix(in srgb, var(--warn) 16%, var(--bg)); color: var(--warn); border-color: color-mix(in srgb, var(--warn) 38%, var(--bg)); }
+  .spin { width: 12px; height: 12px; border: 2px solid var(--line); border-top-color: var(--blue); border-radius: 50%; animation: sp .8s linear infinite; flex: none; }
+  @keyframes sp { to { transform: rotate(360deg); } }
+  .unread { width: 7px; height: 7px; border-radius: 50%; background: var(--blue); flex: none; }
+
+  /* ===== worktree-centric group ===== */
+  .wg { padding: 6px 0; }
+  .wg + .wg { border-top: 1px solid var(--line); }
+  .wg-head { display: flex; align-items: center; gap: 7px; padding: 7px 12px 4px; }
+  .wg-head .dot { width: 9px; height: 9px; border-radius: 50%; background: var(--c); flex: none; }
+  .wg-head .repo { color: var(--ink); font-weight: 500; font-size: 13px; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+  .wg-head .sep { color: var(--faint); font-size: 13px; }
+  .wg-head .br { color: var(--c); font-weight: 600; font-size: 13px; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+  .wg-head .spacer { flex: 1; }
+  .wg-head .attn { width: 7px; height: 7px; border-radius: 50%; flex: none; }
+  .wg-head .attn-running { background: var(--ok); box-shadow: 0 0 0 3px color-mix(in srgb, var(--ok) 18%, transparent); }
+  .wg-head .attn-pending { background: var(--warn); box-shadow: 0 0 0 3px color-mix(in srgb, var(--warn) 18%, transparent); }
+  .wg-row { display: flex; align-items: center; gap: 6px; padding: 6px 12px 6px 30px; cursor: pointer; }
+  .wg-row:hover { background: var(--panel2); }
+  .wg-row.on { background: color-mix(in srgb, var(--blue) 7%, transparent); }
+  .wg-row .t { flex: 1; min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; color: var(--ink); font-size: 13px; }
+  .wg-row .time { color: var(--muted); font-size: 11px; }
+  .wg-row:hover .time { display: none; }
+
+  .note { max-width: 340px; color: var(--muted); font-size: 12px; line-height: 1.7; }
+  .note h3 { color: var(--ink); font-size: 14px; margin: 0 0 8px; }
+  .note code { background: var(--panel2); padding: 1px 5px; border-radius: 4px; }
+</style>
+</head>
+<body>
+<header>
+  <h1>侧边栏 · 按 worktree 维度组织</h1>
+  <p>顶层 = worktree（分支 + 所属 repo），活跃的排在最前；workspace 不再作为分组。</p>
+  <button class="toggle" id="toggle">切换暗色</button>
+</header>
+
+<div class="wrap">
+  <div class="side">
+    <div class="side-head">
+      <button class="btn-new">＋ New Chat</button>
+      <button class="btn-new btn-icon" title="Worktree 看板">▦</button>
+    </div>
+
+    <!-- active worktrees -->
+    <div class="wg" style="--c:oklch(0.6 0.17 150)">
+      <div class="wg-head"><span class="repo">kimi-code-web</span><span class="sep">›</span><span class="br">feat-login</span><span class="spacer"></span><span class="pr pr-open">#12</span><span class="attn attn-running" title="有 session 运行中"></span></div>
+      <div class="wg-row on"><span class="spin"></span><span class="t">Add login flow</span><span class="time">now</span></div>
+      <div class="wg-row"><span class="t">Fix login redirect</span><span class="time">12m</span></div>
+    </div>
+
+    <div class="wg" style="--c:oklch(0.6 0.17 110)">
+      <div class="wg-head"><span class="repo">kimi-server</span><span class="sep">›</span><span class="br">feat-cache</span><span class="spacer"></span><span class="pr pr-open">#5</span><span class="attn attn-pending" title="有 session 等待输入"></span></div>
+      <div class="wg-row"><span class="unread"></span><span class="t">Add Redis cache</span><span class="tag tag-ask">Answer</span><span class="time">3m</span></div>
+    </div>
+
+    <div class="divider"></div>
+
+    <!-- idle worktrees -->
+    <div class="wg" style="--c:oklch(0.6 0.17 300)">
+      <div class="wg-head"><span class="repo">kimi-code-web</span><span class="sep">›</span><span class="br">fix-perf</span><span class="spacer"></span><span class="pr pr-merged">#8</span></div>
+      <div class="wg-row"><span class="t">Optimize dashboard query</span><span class="tag tag-approve">Approve</span><span class="time">28m</span></div>
+    </div>
+
+    <div class="wg" style="--c:oklch(0.6 0.17 70)">
+      <div class="wg-head"><span class="repo">kimi-code-web</span><span class="sep">›</span><span class="br">docs</span><span class="spacer"></span></div>
+      <div class="wg-row"><span class="t">Update API docs</span><span class="time">1h</span></div>
+    </div>
+
+    <div class="wg" style="--c:oklch(0.6 0.17 250)">
+      <div class="wg-head"><span class="repo">kimi-code-web</span><span class="sep">›</span><span class="br">main</span><span class="spacer"></span></div>
+      <div class="wg-row"><span class="t">Refactor auth middleware</span><span class="time">2h</span></div>
+    </div>
+
+    <div class="wg" style="--c:oklch(0.6 0.17 330)">
+      <div class="wg-head"><span class="repo">kimi-server</span><span class="sep">›</span><span class="br">fix-race</span><span class="spacer"></span></div>
+      <div class="wg-row"><span class="t">Fix race in worker</span><span class="time">5h</span></div>
+    </div>
+  </div>
+
+  <div class="note">
+    <h3>设计要点</h3>
+    <p>· 顶层每一项是一个 <b>worktree</b>（<code>分支名 + 所属 repo</code>），不再是 workspace。</p>
+    <p>· 排序：有运行中 / 待处理 session 的 worktree 归到「活跃」区置顶；其余按最近 session 时间倒序。</p>
+    <p>· 每个 worktree 头部显示 <b>分支 + repo + PR</b>，颜色圆点来自分支（等明度）；有运行 session 时多一个绿色 live 点。</p>
+    <p>· main checkout 也作为一个 worktree 项（分支 <code>main</code>），但默认排在活跃 worktree 之后。</p>
+    <p>· 这是「合二为一」：workspace 退化为 worktree 头上的 repo 小字，侧边栏只剩 worktree 这一层。</p>
+    <p>· 非 git / 还没识别出分支的 session 可放在末尾一个「未归类」组。</p>
+  </div>
+</div>
+
+<script>
+  const root = document.documentElement;
+  document.getElementById('toggle').addEventListener('click', (e) => {
+    const dark = root.hasAttribute('data-dark');
+    if (dark) { root.removeAttribute('data-dark'); e.target.textContent = '切换暗色'; }
+    else { root.setAttribute('data-dark', ''); e.target.textContent = '切换亮色'; }
+  });
+</script>
+</body>
+</html>
diff --git a/worktree-ux-mockups.html b/worktree-ux-mockups.html
new file mode 100644
index 000000000..e5d6f6185
--- /dev/null
+++ b/worktree-ux-mockups.html
@@ -0,0 +1,260 @@
+<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+<meta charset="UTF-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1.0" />
+<title>Worktree UX 方案 · kimi-web</title>
+<style>
+  :root {
+    --ink: #14171c; --text: #262626; --dim: #595959; --muted: #8a8a8a; --faint: #b5b5b5;
+    --line: #e7eaee; --line2: #eef1f4; --panel: #fafbfc; --panel2: #f3f5f8; --bg: #ffffff;
+    --blue: #1783ff; --blue2: #0f6fe0; --soft: #e8f3ff; --bd: #cfe6ff;
+    --ok: #0e7a38; --warn: #92660a; --err: #b91c1c;
+    --mono: "JetBrains Mono", ui-monospace, "SF Mono", Menlo, Consolas, monospace;
+    --ui: 14px; --sh: 0 4px 16px rgba(20, 23, 28, 0.08);
+  }
+  [data-dark] {
+    --ink: #e8eaed; --text: #c9cdd4; --dim: #9aa0a8; --muted: #727983; --faint: #525960;
+    --line: #2d333b; --line2: #22272e; --panel: #1c2128; --panel2: #161b22; --bg: #0d1117;
+    --blue: #58a6ff; --blue2: #79b8ff; --soft: #1f2937; --bd: #1f6feb;
+    --ok: #3fb950; --warn: #d29922; --err: #f85149;
+    --sh: 0 6px 20px rgba(0,0,0,0.35);
+  }
+  * { box-sizing: border-box; }
+  body { margin: 0; background: var(--panel); color: var(--text); font-family: var(--mono); font-size: var(--ui); line-height: 1.5; -webkit-font-smoothing: antialiased; }
+  header { padding: 18px 28px; border-bottom: 1px solid var(--line); background: var(--bg); position: sticky; top: 0; z-index: 50; display: flex; align-items: center; gap: 14px; }
+  header h1 { font-size: 16px; margin: 0; color: var(--ink); font-weight: 600; }
+  header nav { display: flex; gap: 6px; margin-left: 8px; }
+  header nav a { color: var(--dim); text-decoration: none; font-size: 12px; padding: 4px 10px; border: 1px solid var(--line); border-radius: 7px; }
+  header nav a:hover { color: var(--ink); border-color: var(--blue); }
+  .toggle { margin-left: auto; background: var(--panel2); color: var(--ink); border: 1px solid var(--line); border-radius: 8px; padding: 6px 12px; font-family: var(--mono); font-size: 12px; cursor: pointer; }
+  .toggle:hover { border-color: var(--blue); }
+
+  section { padding: 28px; border-bottom: 1px solid var(--line); }
+  section h2 { font-size: 18px; color: var(--ink); margin: 0 0 4px; }
+  section .desc { color: var(--muted); font-size: 12px; margin: 0 0 18px; max-width: 720px; }
+
+  /* shared bits */
+  .pr { flex: none; border: 1px solid transparent; border-radius: 9px; padding: 0 6px; height: 18px; line-height: 16px; font-size: 12px; background: transparent; cursor: pointer; font-family: var(--mono); }
+  .pr-open { color: var(--ok); border-color: color-mix(in srgb, var(--ok) 38%, var(--bg)); }
+  .pr-merged { color: #8957e5; border-color: color-mix(in srgb, #8957e5 38%, var(--bg)); }
+  .tag { flex: none; height: 18px; border-radius: 9px; padding: 0 6px; line-height: 18px; font-size: 12px; background: color-mix(in srgb, var(--warn) 16%, var(--bg)); color: var(--warn); border: 1px solid color-mix(in srgb, var(--warn) 38%, var(--bg)); }
+  .spin { width: 12px; height: 12px; border: 2px solid var(--line); border-top-color: var(--blue); border-radius: 50%; animation: sp .8s linear infinite; flex: none; }
+  @keyframes sp { to { transform: rotate(360deg); } }
+  .unread { width: 7px; height: 7px; border-radius: 50%; background: var(--blue); flex: none; }
+  .btn { font-family: var(--mono); font-size: 12px; border: 1px solid var(--line); background: var(--bg); color: var(--dim); border-radius: 7px; padding: 5px 11px; cursor: pointer; }
+  .btn:hover { color: var(--ink); background: var(--panel2); }
+  .btn.primary { background: var(--blue); color: #fff; border-color: var(--blue); }
+  .btn.primary:hover { background: var(--blue2); }
+  .bar { display: flex; align-items: center; gap: 10px; margin-bottom: 16px; }
+  .bar h3 { font-size: 14px; color: var(--ink); margin: 0; font-weight: 600; }
+
+  /* ============ A: Kanban ============ */
+  .board { display: flex; gap: 14px; overflow-x: auto; padding-bottom: 10px; }
+  .col { width: 284px; flex: none; background: var(--bg); border: 1px solid var(--line); border-radius: 12px; display: flex; flex-direction: column; max-height: 66vh; box-shadow: var(--sh); }
+  .col-head { padding: 11px 13px; border-bottom: 1px solid var(--line); }
+  .col-head .row1 { display: flex; align-items: center; gap: 7px; }
+  .col-head .br { color: var(--c); font-weight: 600; font-size: 14px; }
+  .col-head .badge { font-size: 11px; color: var(--faint); border: 1px solid var(--line); border-radius: 8px; padding: 0 5px; }
+  .col-head .meta { display: flex; gap: 8px; margin-top: 6px; font-size: 11px; color: var(--muted); }
+  .col-head .count { margin-left: auto; color: var(--faint); font-size: 12px; }
+  .col-body { padding: 9px; overflow-y: auto; display: flex; flex-direction: column; gap: 8px; }
+  .sess-card { background: var(--bg); border: 1px solid var(--line); border-radius: 9px; padding: 10px 11px; cursor: pointer; transition: border-color .12s, box-shadow .12s, transform .12s; }
+  .sess-card:hover { border-color: var(--blue); box-shadow: var(--sh); transform: translateY(-1px); }
+  .sess-card.on { border-color: var(--blue); box-shadow: inset 0 0 0 1px var(--bd); }
+  .sess-card .tline { display: flex; align-items: center; gap: 6px; }
+  .sess-card .t { flex: 1; min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; color: var(--ink); font-weight: 500; font-size: 13px; }
+  .sess-card .preview { color: var(--muted); font-size: 11px; margin-top: 5px; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+  .sess-card .foot { display: flex; align-items: center; gap: 6px; margin-top: 7px; }
+  .sess-card .time { color: var(--faint); font-size: 11px; }
+  .col-foot { padding: 9px; border-top: 1px solid var(--line); }
+  .col-foot .add { width: 100%; text-align: center; color: var(--faint); font-size: 12px; padding: 6px; border: 1px dashed var(--line); border-radius: 8px; cursor: pointer; background: transparent; font-family: var(--mono); }
+  .col-foot .add:hover { color: var(--blue); border-color: var(--blue); }
+
+  /* ============ B: Dashboard ============ */
+  .dash { display: grid; grid-template-columns: repeat(auto-fill, minmax(420px, 1fr)); gap: 16px; }
+  .wtc { background: var(--bg); border: 1px solid var(--line); border-radius: 12px; overflow: hidden; box-shadow: var(--sh); }
+  .wtc .head { padding: 12px 15px; border-bottom: 1px solid var(--line); display: flex; align-items: center; gap: 9px; }
+  .wtc .head .br { color: var(--c); font-weight: 600; font-size: 15px; }
+  .wtc .head .path { color: var(--faint); font-size: 11px; margin-left: auto; }
+  .wtc .stat { display: flex; gap: 8px; padding: 8px 15px; border-bottom: 1px solid var(--line); font-size: 11px; color: var(--muted); }
+  .wtc .stat b { color: var(--dim); font-weight: 500; }
+  .wtc .body { padding: 4px 0; }
+  .wtc .sess-row { display: flex; align-items: center; gap: 8px; padding: 8px 15px; cursor: pointer; }
+  .wtc .sess-row:hover { background: var(--panel2); }
+  .wtc .sess-row .t { flex: 1; min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; color: var(--ink); }
+  .wtc .sess-row .time { color: var(--faint); font-size: 11px; }
+  .wtc .foot { padding: 9px 15px; border-top: 1px solid var(--line); display: flex; gap: 8px; }
+  .wtc .empty { padding: 14px 15px; color: var(--faint); font-size: 12px; }
+
+  /* ============ C: Chat header clickable workspace ============ */
+  .phone { border: 1px solid var(--line); border-radius: 12px; overflow: hidden; background: var(--bg); box-shadow: var(--sh); max-width: 760px; }
+  .chat-head { display: flex; align-items: center; gap: 12px; padding: 11px 16px; border-bottom: 1px solid var(--line); position: relative; }
+  .chat-head .title { font-weight: 500; color: var(--ink); font-size: 14px; }
+  .ws-chip { display: inline-flex; align-items: center; gap: 6px; padding: 3px 10px; border: 1px solid var(--line); border-radius: 8px; color: var(--c); cursor: pointer; font-size: 12px; font-weight: 500; background: var(--bg); }
+  .ws-chip:hover { border-color: var(--c); background: var(--panel2); }
+  .ws-chip .caret { color: var(--muted); font-size: 10px; }
+  .ws-chip .pr { margin-left: 2px; }
+  .ws-pop { position: absolute; top: 44px; left: 16px; width: 280px; background: var(--bg); border: 1px solid var(--line); border-radius: 10px; box-shadow: var(--sh); overflow: hidden; display: none; z-index: 20; }
+  .ws-pop.open { display: block; }
+  .ws-pop .sec { padding: 6px 0; }
+  .ws-pop .sec + .sec { border-top: 1px solid var(--line); }
+  .ws-pop .item { display: flex; align-items: center; gap: 8px; padding: 7px 13px; cursor: pointer; font-size: 12px; color: var(--text); }
+  .ws-pop .item:hover { background: var(--panel2); }
+  .ws-pop .item .brname { color: var(--c); font-weight: 500; }
+  .ws-pop .item .muted { color: var(--muted); margin-left: auto; font-size: 11px; }
+  .ws-pop .head-lbl { padding: 4px 13px; color: var(--faint); font-size: 11px; }
+  .chat-body { padding: 26px 20px; color: var(--faint); font-size: 12px; min-height: 160px; }
+  .hint { margin-top: 14px; color: var(--muted); font-size: 12px; }
+  .hint b { color: var(--dim); }
+</style>
+</head>
+<body>
+<header>
+  <h1>Worktree UX 方案</h1>
+  <nav>
+    <a href="#kanban">A · 看板</a>
+    <a href="#dashboard">B · Worktrees 面板</a>
+    <a href="#chat">C · Chat 标题区可点击</a>
+  </nav>
+  <button class="toggle" id="toggle">切换暗色</button>
+</header>
+
+<!-- ============ A: Kanban ============ -->
+<section id="kanban">
+  <h2>A · 看板（Kanban）</h2>
+  <p class="desc">列 = worktree，卡片 = session。最适合「同时跑很多并行任务、一眼看进度、拖拽流转」。每列头部固定展示分支 / main 标记 / PR / 状态 / session 数。</p>
+  <div class="bar">
+    <h3>kimi-code-web</h3>
+    <button class="btn primary">+ New worktree</button>
+  </div>
+  <div class="board">
+    <div class="col" style="--c:oklch(0.6 0.17 250)">
+      <div class="col-head"><div class="row1"><span class="br">main</span><span class="badge">main</span><span class="count">1</span></div><div class="meta"><span>clean</span></div></div>
+      <div class="col-body">
+        <div class="sess-card on"><div class="tline"><span class="spin"></span><span class="t">Refactor auth middleware</span></div><div class="preview">正在编辑 src/auth.ts …</div><div class="foot"><span class="time">now</span></div></div>
+      </div>
+      <div class="col-foot"><button class="add">+ session</button></div>
+    </div>
+
+    <div class="col" style="--c:oklch(0.6 0.17 150)">
+      <div class="col-head"><div class="row1"><span class="br">feat-login</span><span class="pr pr-open">#12</span><span class="count">2</span></div><div class="meta"><span>dirty · 3 files</span><span>↑2</span></div></div>
+      <div class="col-body">
+        <div class="sess-card"><div class="tline"><span class="unread"></span><span class="t">Add login flow</span></div><div class="preview">完成 OAuth 回调处理</div><div class="foot"><span class="time">3m</span></div></div>
+        <div class="sess-card"><div class="tline"><span class="t">Fix login redirect</span></div><div class="preview">redirect_uri 白名单</div><div class="foot"><span class="time">12m</span></div></div>
+      </div>
+      <div class="col-foot"><button class="add">+ session</button></div>
+    </div>
+
+    <div class="col" style="--c:oklch(0.6 0.17 300)">
+      <div class="col-head"><div class="row1"><span class="br">fix-perf</span><span class="pr pr-merged">#8</span><span class="count">1</span></div><div class="meta"><span>clean</span></div></div>
+      <div class="col-body">
+        <div class="sess-card"><div class="tline"><span class="t">Optimize dashboard query</span><span class="tag">Approve</span></div><div class="preview">需要审批: prisma migrate</div><div class="foot"><span class="time">28m</span></div></div>
+      </div>
+      <div class="col-foot"><button class="add">+ session</button></div>
+    </div>
+
+    <div class="col" style="--c:oklch(0.6 0.17 70)">
+      <div class="col-head"><div class="row1"><span class="br">docs</span><span class="count">1</span></div><div class="meta"><span>dirty · 1 file</span></div></div>
+      <div class="col-body">
+        <div class="sess-card"><div class="tline"><span class="t">Update API docs</span></div><div class="preview">补充 worktree 端点说明</div><div class="foot"><span class="time">1h</span></div></div>
+      </div>
+      <div class="col-foot"><button class="add">+ session</button></div>
+    </div>
+  </div>
+</section>
+
+<!-- ============ B: Dashboard ============ -->
+<section id="dashboard">
+  <h2>B · Worktrees 面板（dashboard / rich list）</h2>
+  <p class="desc">全宽一个页面，每个 worktree 一张卡片，里面展开它的 session、分支 / PR / 脏净 / ahead-behind / 路径 / 操作。侧边栏只做轻量切换。比看板轻、更直接，不一定要拖拽。</p>
+  <div class="bar">
+    <h3>Worktrees · kimi-code-web</h3>
+    <button class="btn primary">+ New worktree</button>
+  </div>
+  <div class="dash">
+
+    <div class="wtc" style="--c:oklch(0.6 0.17 250)">
+      <div class="head"><span class="br">main</span><span class="badge" style="font-size:11px;color:var(--faint);border:1px solid var(--line);border-radius:8px;padding:0 5px;">main</span><span class="path">~/code/kimi-code-web</span></div>
+      <div class="stat"><span><b>clean</b></span><span>·</span><span>1 session</span></div>
+      <div class="body">
+        <div class="sess-row"><span class="spin"></span><span class="t">Refactor auth middleware</span><span class="time">now</span></div>
+      </div>
+      <div class="foot"><button class="btn">New session here</button></div>
+    </div>
+
+    <div class="wtc" style="--c:oklch(0.6 0.17 150)">
+      <div class="head"><span class="br">feat-login</span><span class="pr pr-open">#12</span><span class="path">.worktrees/feat-login</span></div>
+      <div class="stat"><span><b>dirty</b> · 3 files</span><span>·</span><span>↑2 ahead</span><span>·</span><span>2 sessions</span></div>
+      <div class="body">
+        <div class="sess-row"><span class="unread"></span><span class="t">Add login flow</span><span class="time">3m</span></div>
+        <div class="sess-row"><span class="t">Fix login redirect</span><span class="time">12m</span></div>
+      </div>
+      <div class="foot"><button class="btn">New session here</button><button class="btn">Push</button><button class="btn">Delete</button></div>
+    </div>
+
+    <div class="wtc" style="--c:oklch(0.6 0.17 300)">
+      <div class="head"><span class="br">fix-perf</span><span class="pr pr-merged">#8</span><span class="path">.worktrees/fix-perf</span></div>
+      <div class="stat"><span><b>clean</b></span><span>·</span><span>merged</span><span>·</span><span>1 session</span></div>
+      <div class="body">
+        <div class="sess-row"><span class="t">Optimize dashboard query</span><span class="tag">Approve</span><span class="time">28m</span></div>
+      </div>
+      <div class="foot"><button class="btn">New session here</button><button class="btn">Delete</button></div>
+    </div>
+
+    <div class="wtc" style="--c:oklch(0.6 0.17 70)">
+      <div class="head"><span class="br">docs</span><span class="path">.worktrees/docs</span></div>
+      <div class="stat"><span><b>dirty</b> · 1 file</span><span>·</span><span>1 session</span></div>
+      <div class="body">
+        <div class="sess-row"><span class="t">Update API docs</span><span class="time">1h</span></div>
+      </div>
+      <div class="foot"><button class="btn">New session here</button><button class="btn">Delete</button></div>
+    </div>
+
+  </div>
+</section>
+
+<!-- ============ C: Chat header clickable ============ -->
+<section id="chat">
+  <h2>C · Chat 标题区的 workspace 可点击</h2>
+  <p class="desc">当前 session 所在 worktree 在 chat 标题区其实是一个「闲置」的入口。把它做成可点击的 chip：点击展开一个快捷菜单（查看全部 worktree / 切换 worktree / 新建 worktree / 打开 PR）。让「当前 session 属于哪个 worktree」既是展示，也是入口。</p>
+  <div class="phone">
+    <div class="chat-head">
+      <span class="title">Fix login redirect</span>
+      <span class="ws-chip" id="wsChip" style="--c:oklch(0.6 0.17 150)">⎇ feat-login<span class="pr pr-open">#12</span><span class="caret">▾</span></span>
+      <div class="ws-pop" id="wsPop">
+        <div class="sec">
+          <div class="head-lbl">当前 worktree</div>
+          <div class="item"><span class="brname">feat-login</span><span class="pr pr-open">#12</span></div>
+        </div>
+        <div class="sec">
+          <div class="head-lbl">切换 worktree</div>
+          <div class="item" style="--c:oklch(0.6 0.17 250)"><span class="brname">main</span><span class="muted">1 session</span></div>
+          <div class="item" style="--c:oklch(0.6 0.17 300)"><span class="brname">fix-perf</span><span class="pr pr-merged">#8</span></div>
+          <div class="item" style="--c:oklch(0.6 0.17 70)"><span class="brname">docs</span><span class="muted">1 session</span></div>
+        </div>
+        <div class="sec">
+          <div class="item">＋ New worktree</div>
+          <div class="item">⊞ 查看全部 worktree</div>
+        </div>
+      </div>
+    </div>
+    <div class="chat-body">… conversation …</div>
+  </div>
+  <p class="hint">提示：点上面标题区的 <b>⎇ feat-login ▾</b> chip，会弹出快捷菜单（这个 demo 里真的可点）。</p>
+</section>
+
+<script>
+  const root = document.documentElement;
+  document.getElementById('toggle').addEventListener('click', (e) => {
+    const dark = root.hasAttribute('data-dark');
+    if (dark) { root.removeAttribute('data-dark'); e.target.textContent = '切换暗色'; }
+    else { root.setAttribute('data-dark', ''); e.target.textContent = '切换亮色'; }
+  });
+  const chip = document.getElementById('wsChip');
+  const pop = document.getElementById('wsPop');
+  chip.addEventListener('click', (e) => { e.stopPropagation(); pop.classList.toggle('open'); });
+  document.addEventListener('click', () => pop.classList.remove('open'));
+</script>
+</body>
+</html>