From 95bbc98481c7fa70da41c7a0e6184cda2c2069ec Mon Sep 17 00:00:00 2001
From: TheIcarusWings <10465470+TheIcarusWings@users.noreply.github.com>
Date: Sat, 13 Jun 2026 15:08:34 +0100
Subject: [PATCH 1/4] feat(sidebar): add user-defined thread folders

Add collapsible, per-project folders to organize sidebar threads, with
drag-and-drop (including multi-select moves), inline rename, and manual
ordering of folders and of threads within a folder. State is client-only
in useUiStateStore (localStorage); a thread belongs to at most one folder;
ungrouped threads render below folders and remain sort-ordered.

- uiStateStore: ThreadGroup model + reducers (create/rename/delete/move/
  reorder/toggle), derived threadKey->groupId index, persistence
  round-trip, and syncThreadGroups orphan GC against the live snapshot.
- sidebarThreadGrouping.ts: pure buildGroupedThreadLayout helper (+ tests).
- SidebarThreadGroupRow.tsx: collapsible folder header that is both a
  sortable item and a drop target, with inline rename.
- Sidebar.tsx: per-project DnD context, sortable thread rows with
  click-vs-drag guards, folder section rendering, pagination of the
  ungrouped list only, and context-menu CRUD (project header, multi-select,
  per-thread "Move to folder").
- service.ts: garbage-collect folder state when threads/projects disappear.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 apps/web/src/components/Sidebar.tsx           | 707 +++++++++++++++---
 .../src/components/SidebarThreadGroupRow.tsx  | 141 ++++
 apps/web/src/environments/runtime/service.ts  |  17 +
 apps/web/src/sidebarThreadGrouping.test.ts    | 116 +++
 apps/web/src/sidebarThreadGrouping.ts         |  72 ++
 apps/web/src/uiStateStore.test.ts             | 172 +++++
 apps/web/src/uiStateStore.ts                  | 451 ++++++++++-
 7 files changed, 1569 insertions(+), 107 deletions(-)
 create mode 100644 apps/web/src/components/SidebarThreadGroupRow.tsx
 create mode 100644 apps/web/src/sidebarThreadGrouping.test.ts
 create mode 100644 apps/web/src/sidebarThreadGrouping.ts

diff --git a/apps/web/src/components/Sidebar.tsx b/apps/web/src/components/Sidebar.tsx
index 67b575e4b46..90c50f0214d 100644
--- a/apps/web/src/components/Sidebar.tsx
+++ b/apps/web/src/components/Sidebar.tsx
@@ -26,10 +26,12 @@ import {
   DndContext,
   type DragCancelEvent,
   type CollisionDetection,
+  DragOverlay,
   PointerSensor,
   type DragStartEvent,
   closestCorners,
   pointerWithin,
+  useDroppable,
   useSensor,
   useSensors,
   type DragEndEvent,
@@ -77,7 +79,13 @@ import {
 import { selectThreadTerminalUiState, useTerminalUiStateStore } from "../terminalUiStateStore";
 import { useThreadRunningTerminalIds } from "../terminalSessionState";
 import { useThreadDiscoveredPorts } from "../portDiscoveryState";
-import { useUiStateStore } from "../uiStateStore";
+import { newThreadGroupId, useUiStateStore } from "../uiStateStore";
+import {
+  buildGroupedThreadLayout,
+  type ThreadGroupSection,
+  threadKeyOf,
+} from "../sidebarThreadGrouping";
+import SidebarThreadGroupRow, { groupHeaderDndId } from "./SidebarThreadGroupRow";
 import {
   resolveShortcutCommand,
   shortcutLabelForCommand,
@@ -215,6 +223,8 @@ const SIDEBAR_LIST_ANIMATION_OPTIONS = {
   easing: "ease-out",
 } as const;
 const EMPTY_THREAD_JUMP_LABELS = new Map<string, string>();
+// Stable empty array so per-project folder-order selectors don't churn renders.
+const EMPTY_STRING_ARRAY: readonly string[] = [];
 const PROJECT_GROUPING_MODE_LABELS: Record<SidebarProjectGroupingMode, string> = {
   repository: "Group by repository",
   repository_path: "Group by repository path",
@@ -317,6 +327,8 @@ interface SidebarThreadRowProps {
   cancelRename: () => void;
   attemptArchiveThread: (threadRef: ScopedThreadRef) => Promise<void>;
   openPrLink: (event: React.MouseEvent<HTMLElement>, prUrl: string) => void;
+  threadDragInProgressRef: React.RefObject<boolean>;
+  suppressThreadClickAfterDragRef: React.RefObject<boolean>;
 }
 
 const SidebarThreadRow = memo(function SidebarThreadRow(props: SidebarThreadRowProps) {
@@ -343,9 +355,22 @@ const SidebarThreadRow = memo(function SidebarThreadRow(props: SidebarThreadRowP
     attemptArchiveThread,
     openPrLink,
     thread,
+    threadDragInProgressRef,
+    suppressThreadClickAfterDragRef,
   } = props;
   const threadRef = scopeThreadRef(thread.environmentId, thread.id);
   const threadKey = scopedThreadKey(threadRef);
+  const isRenamingThisRow = renamingThreadKey === threadKey;
+  const {
+    attributes: dragAttributes,
+    listeners: dragListeners,
+    setNodeRef: setDragNodeRef,
+    transform: dragTransform,
+    transition: dragTransition,
+    isDragging,
+  } = useSortable({ id: threadKey, disabled: isRenamingThisRow });
+  // Suppress drag listeners while renaming so typing never starts a drag.
+  const rowDragHandleProps = isRenamingThisRow ? {} : { ...dragAttributes, ...dragListeners };
   const lastVisitedAt = useUiStateStore((state) => state.threadLastVisitedAtById[threadKey]);
   const isSelected = useThreadSelectionStore((state) => state.selectedThreadKeys.has(threadKey));
   const runningTerminalIds = useThreadRunningTerminalIds({
@@ -422,9 +447,28 @@ const SidebarThreadRow = memo(function SidebarThreadRow(props: SidebarThreadRowP
   );
   const handleRowClick = useCallback(
     (event: React.MouseEvent) => {
+      // Mirror the project drag-vs-click guards: a drag in flight, or the
+      // trailing click dnd-kit emits after a drop, must not navigate/select.
+      if (threadDragInProgressRef.current) {
+        event.preventDefault();
+        event.stopPropagation();
+        return;
+      }
+      if (suppressThreadClickAfterDragRef.current) {
+        suppressThreadClickAfterDragRef.current = false;
+        event.preventDefault();
+        event.stopPropagation();
+        return;
+      }
       handleThreadClick(event, threadRef, orderedProjectThreadKeys);
     },
-    [handleThreadClick, orderedProjectThreadKeys, threadRef],
+    [
+      handleThreadClick,
+      orderedProjectThreadKeys,
+      suppressThreadClickAfterDragRef,
+      threadDragInProgressRef,
+      threadRef,
+    ],
   );
   const handleOpenDiscoveredPort = useCallback(
     (event: React.MouseEvent<HTMLButtonElement>) => {
@@ -561,7 +605,9 @@ const SidebarThreadRow = memo(function SidebarThreadRow(props: SidebarThreadRowP
 
   return (
     <SidebarMenuSubItem
-      className="w-full"
+      ref={setDragNodeRef}
+      style={{ transform: CSS.Translate.toString(dragTransform), transition: dragTransition }}
+      className={`w-full ${isDragging ? "z-20 opacity-80" : ""}`}
       data-thread-item
       onMouseLeave={handleMouseLeave}
       onBlurCapture={handleBlurCapture}
@@ -578,6 +624,7 @@ const SidebarThreadRow = memo(function SidebarThreadRow(props: SidebarThreadRowP
         onClick={handleRowClick}
         onKeyDown={handleRowKeyDown}
         onContextMenu={handleRowContextMenu}
+        {...rowDragHandleProps}
       >
         <div className="flex min-w-0 flex-1 items-center gap-1.5 text-left">
           {prStatus && (
@@ -772,13 +819,36 @@ const SidebarThreadRow = memo(function SidebarThreadRow(props: SidebarThreadRowP
   );
 });
 
+/** dnd id for the per-project "drop here to remove from folder" zone. */
+function ungroupedDropId(projectKey: string): string {
+  return `ungrouped:${projectKey}`;
+}
+
+/** A drop target shown during a drag for moving a thread out of any folder. */
+function UngroupedDropZone({ projectKey }: { projectKey: string }) {
+  const { setNodeRef, isOver } = useDroppable({ id: ungroupedDropId(projectKey) });
+  return (
+    <SidebarMenuSubItem ref={setNodeRef} className="w-full" data-thread-selection-safe>
+      <div
+        className={`flex h-6 w-full translate-x-0 items-center rounded px-2 text-left text-[10px] text-muted-foreground/50 ${
+          isOver ? "bg-accent/60 ring-1 ring-primary/50" : "border border-dashed border-border/60"
+        }`}
+      >
+        Remove from folder
+      </div>
+    </SidebarMenuSubItem>
+  );
+}
+
 interface SidebarProjectThreadListProps {
   projectKey: string;
   projectExpanded: boolean;
   hasOverflowingThreads: boolean;
   hiddenThreadStatus: ThreadStatusPill | null;
   orderedProjectThreadKeys: readonly string[];
-  renderedThreads: readonly SidebarThreadSummary[];
+  pinnedCollapsedThread: SidebarThreadSummary | null;
+  sections: readonly ThreadGroupSection[];
+  ungroupedRenderedThreads: readonly SidebarThreadSummary[];
   showEmptyThreadState: boolean;
   shouldShowThreadPanel: boolean;
   isThreadListExpanded: boolean;
@@ -817,6 +887,23 @@ interface SidebarProjectThreadListProps {
   openPrLink: (event: React.MouseEvent<HTMLElement>, prUrl: string) => void;
   expandThreadListForProject: (projectKey: string) => void;
   collapseThreadListForProject: (projectKey: string) => void;
+  // Folder header wiring.
+  renamingGroupId: string | null;
+  renamingGroupTitle: string;
+  setRenamingGroupTitle: (title: string) => void;
+  onToggleGroup: (groupId: string) => void;
+  onGroupContextMenu: (groupId: string, position: { x: number; y: number }) => void;
+  commitGroupRename: (groupId: string) => void;
+  cancelGroupRename: () => void;
+  // Thread/folder drag-and-drop wiring.
+  dndSensors: ReturnType<typeof useSensors>;
+  dndCollisionDetection: CollisionDetection;
+  onThreadDragStart: (event: DragStartEvent) => void;
+  onThreadDragEnd: (event: DragEndEvent) => void;
+  onThreadDragCancel: (event: DragCancelEvent) => void;
+  activeDragLabel: string | null;
+  threadDragInProgressRef: React.RefObject<boolean>;
+  suppressThreadClickAfterDragRef: React.RefObject<boolean>;
 }
 
 const SidebarProjectThreadList = memo(function SidebarProjectThreadList(
@@ -828,7 +915,9 @@ const SidebarProjectThreadList = memo(function SidebarProjectThreadList(
     hasOverflowingThreads,
     hiddenThreadStatus,
     orderedProjectThreadKeys,
-    renderedThreads,
+    pinnedCollapsedThread,
+    sections,
+    ungroupedRenderedThreads,
     showEmptyThreadState,
     shouldShowThreadPanel,
     isThreadListExpanded,
@@ -856,92 +945,221 @@ const SidebarProjectThreadList = memo(function SidebarProjectThreadList(
     openPrLink,
     expandThreadListForProject,
     collapseThreadListForProject,
+    renamingGroupId,
+    renamingGroupTitle,
+    setRenamingGroupTitle,
+    onToggleGroup,
+    onGroupContextMenu,
+    commitGroupRename,
+    cancelGroupRename,
+    dndSensors,
+    dndCollisionDetection,
+    onThreadDragStart,
+    onThreadDragEnd,
+    onThreadDragCancel,
+    activeDragLabel,
+    threadDragInProgressRef,
+    suppressThreadClickAfterDragRef,
   } = props;
   const showMoreButtonRender = useMemo(() => <button type="button" />, []);
   const showLessButtonRender = useMemo(() => <button type="button" />, []);
 
+  const renderThreadRow = useCallback(
+    (thread: SidebarThreadSummary) => {
+      const threadKey = scopedThreadKey(scopeThreadRef(thread.environmentId, thread.id));
+      return (
+        <SidebarThreadRow
+          key={threadKey}
+          thread={thread}
+          projectCwd={projectCwd}
+          orderedProjectThreadKeys={orderedProjectThreadKeys}
+          isActive={activeRouteThreadKey === threadKey}
+          jumpLabel={threadJumpLabelByKey.get(threadKey) ?? null}
+          appSettingsConfirmThreadArchive={appSettingsConfirmThreadArchive}
+          renamingThreadKey={renamingThreadKey}
+          renamingTitle={renamingTitle}
+          setRenamingTitle={setRenamingTitle}
+          renamingInputRef={renamingInputRef}
+          renamingCommittedRef={renamingCommittedRef}
+          confirmingArchiveThreadKey={confirmingArchiveThreadKey}
+          setConfirmingArchiveThreadKey={setConfirmingArchiveThreadKey}
+          confirmArchiveButtonRefs={confirmArchiveButtonRefs}
+          handleThreadClick={handleThreadClick}
+          navigateToThread={navigateToThread}
+          handleMultiSelectContextMenu={handleMultiSelectContextMenu}
+          handleThreadContextMenu={handleThreadContextMenu}
+          clearSelection={clearSelection}
+          commitRename={commitRename}
+          cancelRename={cancelRename}
+          attemptArchiveThread={attemptArchiveThread}
+          openPrLink={openPrLink}
+          threadDragInProgressRef={threadDragInProgressRef}
+          suppressThreadClickAfterDragRef={suppressThreadClickAfterDragRef}
+        />
+      );
+    },
+    [
+      activeRouteThreadKey,
+      appSettingsConfirmThreadArchive,
+      attemptArchiveThread,
+      cancelRename,
+      clearSelection,
+      commitRename,
+      confirmArchiveButtonRefs,
+      confirmingArchiveThreadKey,
+      handleMultiSelectContextMenu,
+      handleThreadClick,
+      handleThreadContextMenu,
+      navigateToThread,
+      openPrLink,
+      orderedProjectThreadKeys,
+      projectCwd,
+      renamingCommittedRef,
+      renamingInputRef,
+      renamingThreadKey,
+      renamingTitle,
+      setConfirmingArchiveThreadKey,
+      setRenamingTitle,
+      suppressThreadClickAfterDragRef,
+      threadDragInProgressRef,
+      threadJumpLabelByKey,
+    ],
+  );
+
   return (
-    <SidebarMenuSub
-      ref={attachThreadListAutoAnimateRef}
-      className="mx-0.5 my-0 w-full translate-x-0 gap-0.5 overflow-hidden px-1 py-0 sm:mx-1 sm:px-1.5"
+    <DndContext
+      sensors={dndSensors}
+      collisionDetection={dndCollisionDetection}
+      modifiers={[restrictToVerticalAxis, restrictToFirstScrollableAncestor]}
+      onDragStart={onThreadDragStart}
+      onDragEnd={onThreadDragEnd}
+      onDragCancel={onThreadDragCancel}
     >
-      {shouldShowThreadPanel && showEmptyThreadState ? (
-        <SidebarMenuSubItem className="w-full" data-thread-selection-safe>
-          <div
-            data-thread-selection-safe
-            className="flex h-6 w-full translate-x-0 items-center px-2 text-left text-[10px] text-muted-foreground/60"
+      <SidebarMenuSub
+        ref={attachThreadListAutoAnimateRef}
+        className="mx-0.5 my-0 w-full translate-x-0 gap-0.5 overflow-hidden px-1 py-0 sm:mx-1 sm:px-1.5"
+      >
+        {shouldShowThreadPanel && showEmptyThreadState ? (
+          <SidebarMenuSubItem className="w-full" data-thread-selection-safe>
+            <div
+              data-thread-selection-safe
+              className="flex h-6 w-full translate-x-0 items-center px-2 text-left text-[10px] text-muted-foreground/60"
+            >
+              <span>No threads yet</span>
+            </div>
+          </SidebarMenuSubItem>
+        ) : null}
+
+        {/* Collapsed project: pin only the active thread, with no folder chrome. */}
+        {!projectExpanded && pinnedCollapsedThread ? (
+          <SortableContext
+            items={[
+              scopedThreadKey(
+                scopeThreadRef(pinnedCollapsedThread.environmentId, pinnedCollapsedThread.id),
+              ),
+            ]}
+            strategy={verticalListSortingStrategy}
           >
-            <span>No threads yet</span>
-          </div>
-        </SidebarMenuSubItem>
-      ) : null}
-      {shouldShowThreadPanel &&
-        renderedThreads.map((thread) => {
-          const threadKey = scopedThreadKey(scopeThreadRef(thread.environmentId, thread.id));
-          return (
-            <SidebarThreadRow
-              key={threadKey}
-              thread={thread}
-              projectCwd={projectCwd}
-              orderedProjectThreadKeys={orderedProjectThreadKeys}
-              isActive={activeRouteThreadKey === threadKey}
-              jumpLabel={threadJumpLabelByKey.get(threadKey) ?? null}
-              appSettingsConfirmThreadArchive={appSettingsConfirmThreadArchive}
-              renamingThreadKey={renamingThreadKey}
-              renamingTitle={renamingTitle}
-              setRenamingTitle={setRenamingTitle}
-              renamingInputRef={renamingInputRef}
-              renamingCommittedRef={renamingCommittedRef}
-              confirmingArchiveThreadKey={confirmingArchiveThreadKey}
-              setConfirmingArchiveThreadKey={setConfirmingArchiveThreadKey}
-              confirmArchiveButtonRefs={confirmArchiveButtonRefs}
-              handleThreadClick={handleThreadClick}
-              navigateToThread={navigateToThread}
-              handleMultiSelectContextMenu={handleMultiSelectContextMenu}
-              handleThreadContextMenu={handleThreadContextMenu}
-              clearSelection={clearSelection}
-              commitRename={commitRename}
-              cancelRename={cancelRename}
-              attemptArchiveThread={attemptArchiveThread}
-              openPrLink={openPrLink}
-            />
-          );
-        })}
+            {renderThreadRow(pinnedCollapsedThread)}
+          </SortableContext>
+        ) : null}
+
+        {projectExpanded ? (
+          <>
+            {/* Folder sections (always rendered in full); headers are sortable. */}
+            <SortableContext
+              items={sections.map((section) => groupHeaderDndId(section.group.id))}
+              strategy={verticalListSortingStrategy}
+            >
+              {sections.map((section) => (
+                <React.Fragment key={section.group.id}>
+                  <SidebarThreadGroupRow
+                    group={section.group}
+                    threadCount={section.threads.length}
+                    expanded={section.expanded}
+                    isRenaming={renamingGroupId === section.group.id}
+                    renamingTitle={renamingGroupTitle}
+                    setRenamingTitle={setRenamingGroupTitle}
+                    onToggle={onToggleGroup}
+                    onContextMenu={onGroupContextMenu}
+                    commitRename={commitGroupRename}
+                    cancelRename={cancelGroupRename}
+                  />
+                  {section.expanded ? (
+                    <SortableContext
+                      items={section.threads.map((thread) =>
+                        scopedThreadKey(scopeThreadRef(thread.environmentId, thread.id)),
+                      )}
+                      strategy={verticalListSortingStrategy}
+                    >
+                      {section.threads.map((thread) => renderThreadRow(thread))}
+                    </SortableContext>
+                  ) : null}
+                </React.Fragment>
+              ))}
+            </SortableContext>
+
+            {/* Ungrouped threads (preview-capped). */}
+            <SortableContext
+              items={ungroupedRenderedThreads.map((thread) =>
+                scopedThreadKey(scopeThreadRef(thread.environmentId, thread.id)),
+              )}
+              strategy={verticalListSortingStrategy}
+            >
+              {ungroupedRenderedThreads.map((thread) => renderThreadRow(thread))}
+            </SortableContext>
 
-      {projectExpanded && hasOverflowingThreads && !isThreadListExpanded && (
-        <SidebarMenuSubItem className="w-full">
-          <SidebarMenuSubButton
-            render={showMoreButtonRender}
-            data-thread-selection-safe
-            size="sm"
-            className="h-6 w-full translate-x-0 justify-start px-2 text-left text-[10px] text-muted-foreground/60 hover:bg-accent hover:text-muted-foreground/80"
-            onClick={() => {
-              expandThreadListForProject(projectKey);
-            }}
-          >
-            <span className="flex min-w-0 flex-1 items-center gap-2">
-              {hiddenThreadStatus && <ThreadStatusLabel status={hiddenThreadStatus} compact />}
-              <span>Show more</span>
-            </span>
-          </SidebarMenuSubButton>
-        </SidebarMenuSubItem>
-      )}
-      {projectExpanded && hasOverflowingThreads && isThreadListExpanded && (
-        <SidebarMenuSubItem className="w-full">
-          <SidebarMenuSubButton
-            render={showLessButtonRender}
-            data-thread-selection-safe
-            size="sm"
-            className="h-6 w-full translate-x-0 justify-start px-2 text-left text-[10px] text-muted-foreground/60 hover:bg-accent hover:text-muted-foreground/80"
-            onClick={() => {
-              collapseThreadListForProject(projectKey);
-            }}
-          >
-            <span>Show less</span>
-          </SidebarMenuSubButton>
-        </SidebarMenuSubItem>
-      )}
-    </SidebarMenuSub>
+            {/* Drop-out target appears only while dragging and when folders exist. */}
+            {activeDragLabel !== null && sections.length > 0 ? (
+              <UngroupedDropZone projectKey={projectKey} />
+            ) : null}
+
+            {hasOverflowingThreads && !isThreadListExpanded && (
+              <SidebarMenuSubItem className="w-full">
+                <SidebarMenuSubButton
+                  render={showMoreButtonRender}
+                  data-thread-selection-safe
+                  size="sm"
+                  className="h-6 w-full translate-x-0 justify-start px-2 text-left text-[10px] text-muted-foreground/60 hover:bg-accent hover:text-muted-foreground/80"
+                  onClick={() => {
+                    expandThreadListForProject(projectKey);
+                  }}
+                >
+                  <span className="flex min-w-0 flex-1 items-center gap-2">
+                    {hiddenThreadStatus && (
+                      <ThreadStatusLabel status={hiddenThreadStatus} compact />
+                    )}
+                    <span>Show more</span>
+                  </span>
+                </SidebarMenuSubButton>
+              </SidebarMenuSubItem>
+            )}
+            {hasOverflowingThreads && isThreadListExpanded && (
+              <SidebarMenuSubItem className="w-full">
+                <SidebarMenuSubButton
+                  render={showLessButtonRender}
+                  data-thread-selection-safe
+                  size="sm"
+                  className="h-6 w-full translate-x-0 justify-start px-2 text-left text-[10px] text-muted-foreground/60 hover:bg-accent hover:text-muted-foreground/80"
+                  onClick={() => {
+                    collapseThreadListForProject(projectKey);
+                  }}
+                >
+                  <span>Show less</span>
+                </SidebarMenuSubButton>
+              </SidebarMenuSubItem>
+            )}
+          </>
+        ) : null}
+      </SidebarMenuSub>
+      <DragOverlay>
+        {activeDragLabel !== null ? (
+          <div className="pointer-events-none rounded-md border border-border bg-popover px-2 py-1 text-xs text-foreground shadow-md">
+            {activeDragLabel}
+          </div>
+        ) : null}
+      </DragOverlay>
+    </DndContext>
   );
 });
 
@@ -1004,6 +1222,12 @@ const SidebarProjectItem = memo(function SidebarProjectItem(props: SidebarProjec
   const { isMobile, setOpenMobile } = useSidebar();
   const markThreadUnread = useUiStateStore((state) => state.markThreadUnread);
   const toggleProject = useUiStateStore((state) => state.toggleProject);
+  const moveThreadsToGroup = useUiStateStore((state) => state.moveThreadsToGroup);
+  const reorderThreadGroupsAction = useUiStateStore((state) => state.reorderThreadGroups);
+  const toggleThreadGroup = useUiStateStore((state) => state.toggleThreadGroup);
+  const createThreadGroup = useUiStateStore((state) => state.createThreadGroup);
+  const renameThreadGroupAction = useUiStateStore((state) => state.renameThreadGroup);
+  const deleteThreadGroup = useUiStateStore((state) => state.deleteThreadGroup);
   const toggleThreadSelection = useThreadSelectionStore((state) => state.toggleThread);
   const rangeSelectTo = useThreadSelectionStore((state) => state.rangeSelectTo);
   const clearSelection = useThreadSelectionStore((state) => state.clearSelection);
@@ -1125,6 +1349,13 @@ const SidebarProjectItem = memo(function SidebarProjectItem(props: SidebarProjec
   const renamingCommittedRef = useRef(false);
   const renamingInputRef = useRef<HTMLInputElement | null>(null);
   const confirmArchiveButtonRefs = useRef(new Map<string, HTMLButtonElement>());
+  // Folder (thread group) inline-rename + drag-and-drop state.
+  const [renamingGroupId, setRenamingGroupId] = useState<string | null>(null);
+  const [renamingGroupTitle, setRenamingGroupTitle] = useState("");
+  const [activeDragLabel, setActiveDragLabel] = useState<string | null>(null);
+  const threadDragInProgressRef = useRef(false);
+  const suppressThreadClickAfterDragRef = useRef(false);
+  const suppressGroupClickAfterDragRef = useRef(false);
   const memberProjectByScopedKey = useMemo(
     () =>
       new Map(
@@ -1151,7 +1382,18 @@ const SidebarProjectItem = memo(function SidebarProjectItem(props: SidebarProjec
     return counts;
   }, [memberProjectByScopedKey, project.memberProjects, projectThreads]);
 
-  const { projectStatus, visibleProjectThreads, orderedProjectThreadKeys } = useMemo(() => {
+  // Custom thread folders (client-only). Whole-map subscriptions are fine here:
+  // folder mutations are user-driven and rare. buildGroupedThreadLayout scopes
+  // by projectKey, so passing the full maps is correct.
+  const threadGroupsById = useUiStateStore((state) => state.threadGroupsById);
+  const threadGroupExpandedById = useUiStateStore((state) => state.threadGroupExpandedById);
+  const threadGroupOrderForProject = useUiStateStore(
+    useShallow(
+      (state) => state.threadGroupOrderByProjectKey[project.projectKey] ?? EMPTY_STRING_ARRAY,
+    ),
+  );
+
+  const { projectStatus, visibleProjectThreads } = useMemo(() => {
     const lastVisitedAtByThreadKey = new Map(
       projectThreads.map((thread, index) => [
         scopedThreadKey(scopeThreadRef(thread.environmentId, thread.id)),
@@ -1177,9 +1419,6 @@ const SidebarProjectItem = memo(function SidebarProjectItem(props: SidebarProjec
       visibleProjectThreads.map((thread) => resolveProjectThreadStatus(thread)),
     );
     return {
-      orderedProjectThreadKeys: visibleProjectThreads.map((thread) =>
-        scopedThreadKey(scopeThreadRef(thread.environmentId, thread.id)),
-      ),
       projectStatus,
       visibleProjectThreads,
     };
@@ -1199,9 +1438,11 @@ const SidebarProjectItem = memo(function SidebarProjectItem(props: SidebarProjec
   }, [activeRouteThreadKey, projectExpanded, visibleProjectThreads]);
 
   const {
+    sections,
+    ungroupedRenderedThreads,
+    orderedRenderedThreadKeys,
     hasOverflowingThreads,
     hiddenThreadStatus,
-    renderedThreads,
     showEmptyThreadState,
     shouldShowThreadPanel,
   } = useMemo(() => {
@@ -1222,40 +1463,60 @@ const SidebarProjectItem = memo(function SidebarProjectItem(props: SidebarProjec
         },
       });
     };
-    const hasOverflowingThreads = visibleProjectThreads.length > sidebarThreadPreviewCount;
-    const previewThreads =
+
+    const layout = buildGroupedThreadLayout({
+      visibleProjectThreads,
+      projectKey: project.projectKey,
+      groups: threadGroupsById,
+      groupOrder: threadGroupOrderForProject,
+      groupExpandedById: threadGroupExpandedById,
+    });
+
+    // Pagination caps ONLY the ungrouped list; folder sections always render in
+    // full so a curated folder is never partially hidden behind "Show more".
+    const ungrouped = layout.ungroupedThreads;
+    const hasOverflowingThreads = ungrouped.length > sidebarThreadPreviewCount;
+    const ungroupedRenderedThreads =
       isThreadListExpanded || !hasOverflowingThreads
-        ? visibleProjectThreads
-        : visibleProjectThreads.slice(0, sidebarThreadPreviewCount);
-    const visibleThreadKeys = new Set(
-      [...previewThreads, ...(pinnedCollapsedThread ? [pinnedCollapsedThread] : [])].map((thread) =>
-        scopedThreadKey(scopeThreadRef(thread.environmentId, thread.id)),
+        ? ungrouped
+        : ungrouped.slice(0, sidebarThreadPreviewCount);
+
+    // Flattened visual order of the currently-rendered rows, used for
+    // shift-range selection and keyboard jump indices. Collapsed folders and
+    // capped overflow rows are not rendered, so they are not selectable.
+    const orderedRenderedThreadKeys = [
+      ...layout.sections.flatMap((section) =>
+        section.expanded ? section.threads.map(threadKeyOf) : [],
       ),
-    );
-    const renderedThreads = pinnedCollapsedThread
-      ? [pinnedCollapsedThread]
-      : visibleProjectThreads.filter((thread) =>
-          visibleThreadKeys.has(scopedThreadKey(scopeThreadRef(thread.environmentId, thread.id))),
-        );
+      ...ungroupedRenderedThreads.map(threadKeyOf),
+    ];
+
+    const renderedKeySet = new Set(orderedRenderedThreadKeys);
     const hiddenThreads = visibleProjectThreads.filter(
-      (thread) =>
-        !visibleThreadKeys.has(scopedThreadKey(scopeThreadRef(thread.environmentId, thread.id))),
+      (thread) => !renderedKeySet.has(threadKeyOf(thread)),
     );
+
     return {
+      sections: layout.sections,
+      ungroupedRenderedThreads,
+      orderedRenderedThreadKeys,
       hasOverflowingThreads,
       hiddenThreadStatus: resolveProjectStatusIndicator(
         hiddenThreads.map((thread) => resolveProjectThreadStatus(thread)),
       ),
-      renderedThreads,
       showEmptyThreadState: projectExpanded && visibleProjectThreads.length === 0,
       shouldShowThreadPanel: projectExpanded || pinnedCollapsedThread !== null,
     };
   }, [
     isThreadListExpanded,
     pinnedCollapsedThread,
+    project.projectKey,
     projectExpanded,
     projectThreads,
     sidebarThreadPreviewCount,
+    threadGroupExpandedById,
+    threadGroupOrderForProject,
+    threadGroupsById,
     threadLastVisitedAts,
     visibleProjectThreads,
   ]);
@@ -1556,6 +1817,7 @@ const SidebarProjectItem = memo(function SidebarProjectItem(props: SidebarProjec
           [
             buildTargetedItem("rename", "Rename"),
             buildTargetedItem("grouping", "Group into..."),
+            { id: "new-folder", label: "New thread folder…" },
             buildTargetedItem("copy-path", "Copy Path"),
             buildTargetedItem("delete", "Remove", {
               destructive: true,
@@ -1571,16 +1833,26 @@ const SidebarProjectItem = memo(function SidebarProjectItem(props: SidebarProjec
           return;
         }
 
+        if (clicked === "new-folder") {
+          const id = newThreadGroupId();
+          createThreadGroup({ projectKey: project.projectKey, id, name: "New folder" });
+          setRenamingGroupId(id);
+          setRenamingGroupTitle("New folder");
+          return;
+        }
+
         await actionHandlers.get(clicked)?.();
       })();
     },
     [
       copyPathToClipboard,
+      createThreadGroup,
       handleRemoveProject,
       openProjectGroupingDialog,
       openProjectRenameDialog,
       project.groupedProjectCount,
       project.memberProjects,
+      project.projectKey,
       suppressProjectClickForContextMenuRef,
     ],
   );
@@ -1649,6 +1921,42 @@ const SidebarProjectItem = memo(function SidebarProjectItem(props: SidebarProjec
     ],
   );
 
+  // Children for a "Move to folder" context-submenu: existing folders for this
+  // project, plus "New folder…" and "Remove from folder". Leaf ids are
+  // "move:<groupId>", "move:__new__", "move:__none__".
+  const buildFolderMenuChildren = useCallback((): ContextMenuItem<string>[] => {
+    const state = useUiStateStore.getState();
+    const order = state.threadGroupOrderByProjectKey[project.projectKey] ?? [];
+    const folderItems = order.flatMap<ContextMenuItem<string>>((groupId) => {
+      const group = state.threadGroupsById[groupId];
+      return group ? [{ id: `move:${groupId}`, label: group.name }] : [];
+    });
+    return [
+      ...folderItems,
+      { id: "move:__new__", label: "New folder…" },
+      { id: "move:__none__", label: "Remove from folder" },
+    ];
+  }, [project.projectKey]);
+
+  const applyFolderMove = useCallback(
+    (clickedId: string, threadKeys: readonly string[]) => {
+      const target = clickedId.slice("move:".length);
+      if (target === "__new__") {
+        const id = newThreadGroupId();
+        createThreadGroup({ projectKey: project.projectKey, id, name: "New folder", threadKeys });
+        setRenamingGroupId(id);
+        setRenamingGroupTitle("New folder");
+        return;
+      }
+      if (target === "__none__") {
+        moveThreadsToGroup(threadKeys, null);
+        return;
+      }
+      moveThreadsToGroup(threadKeys, target, null);
+    },
+    [createThreadGroup, moveThreadsToGroup, project.projectKey],
+  );
+
   const handleMultiSelectContextMenu = useCallback(
     async (position: { x: number; y: number }) => {
       const api = readLocalApi();
@@ -1660,6 +1968,11 @@ const SidebarProjectItem = memo(function SidebarProjectItem(props: SidebarProjec
       const clicked = await api.contextMenu.show(
         [
           { id: "mark-unread", label: `Mark unread (${count})` },
+          {
+            id: "move-submenu",
+            label: `Move ${count} to folder`,
+            children: buildFolderMenuChildren(),
+          },
           { id: "delete", label: `Delete (${count})`, destructive: true },
         ],
         position,
@@ -1674,6 +1987,12 @@ const SidebarProjectItem = memo(function SidebarProjectItem(props: SidebarProjec
         return;
       }
 
+      if (clicked && clicked.startsWith("move:")) {
+        applyFolderMove(clicked, threadKeys);
+        clearSelection();
+        return;
+      }
+
       if (clicked !== "delete") return;
 
       if (appSettingsConfirmThreadDelete) {
@@ -1698,6 +2017,8 @@ const SidebarProjectItem = memo(function SidebarProjectItem(props: SidebarProjec
     },
     [
       appSettingsConfirmThreadDelete,
+      applyFolderMove,
+      buildFolderMenuChildren,
       clearSelection,
       deleteThread,
       markThreadUnread,
@@ -1971,6 +2292,7 @@ const SidebarProjectItem = memo(function SidebarProjectItem(props: SidebarProjec
         [
           { id: "rename", label: "Rename thread" },
           { id: "mark-unread", label: "Mark unread" },
+          { id: "move-submenu", label: "Move to folder", children: buildFolderMenuChildren() },
           { id: "copy-path", label: "Copy Path" },
           { id: "copy-thread-id", label: "Copy Thread ID" },
           { id: "delete", label: "Delete", destructive: true, icon: "trash" },
@@ -1985,6 +2307,11 @@ const SidebarProjectItem = memo(function SidebarProjectItem(props: SidebarProjec
         return;
       }
 
+      if (clicked && clicked.startsWith("move:")) {
+        applyFolderMove(clicked, [threadKey]);
+        return;
+      }
+
       if (clicked === "mark-unread") {
         markThreadUnread(threadKey, thread.latestTurn?.completedAt);
         return;
@@ -2023,6 +2350,8 @@ const SidebarProjectItem = memo(function SidebarProjectItem(props: SidebarProjec
     },
     [
       appSettingsConfirmThreadDelete,
+      applyFolderMove,
+      buildFolderMenuChildren,
       copyPathToClipboard,
       copyThreadIdToClipboard,
       deleteThread,
@@ -2032,6 +2361,155 @@ const SidebarProjectItem = memo(function SidebarProjectItem(props: SidebarProjec
     ],
   );
 
+  // ---- Folder (thread group) handlers --------------------------------------
+
+  const handleToggleGroup = useCallback(
+    (groupId: string) => {
+      if (suppressGroupClickAfterDragRef.current) {
+        suppressGroupClickAfterDragRef.current = false;
+        return;
+      }
+      toggleThreadGroup(groupId);
+    },
+    [toggleThreadGroup],
+  );
+
+  const commitGroupRename = useCallback(
+    (groupId: string) => {
+      renameThreadGroupAction(groupId, renamingGroupTitle);
+      setRenamingGroupId(null);
+    },
+    [renameThreadGroupAction, renamingGroupTitle],
+  );
+
+  const cancelGroupRename = useCallback(() => {
+    setRenamingGroupId(null);
+  }, []);
+
+  const startGroupRename = useCallback((groupId: string, currentName: string) => {
+    setRenamingGroupId(groupId);
+    setRenamingGroupTitle(currentName);
+  }, []);
+
+  const handleGroupContextMenu = useCallback(
+    (groupId: string, position: { x: number; y: number }) => {
+      void (async () => {
+        const api = readLocalApi();
+        if (!api) return;
+        const group = useUiStateStore.getState().threadGroupsById[groupId];
+        if (!group) return;
+        const clicked = await api.contextMenu.show(
+          [
+            { id: "rename", label: "Rename folder" },
+            { id: "delete", label: "Delete folder", destructive: true, icon: "trash" },
+          ],
+          position,
+        );
+        if (clicked === "rename") {
+          startGroupRename(groupId, group.name);
+          return;
+        }
+        if (clicked === "delete") {
+          deleteThreadGroup(groupId);
+        }
+      })();
+    },
+    [deleteThreadGroup, startGroupRename],
+  );
+
+  // Move the dragged thread(s) — honouring an active multi-selection scoped to
+  // this project — by reading the latest selection at drag time.
+  const resolveDraggedThreadKeys = useCallback(
+    (activeKey: string) => {
+      const selected = useThreadSelectionStore.getState().selectedThreadKeys;
+      if (!selected.has(activeKey)) {
+        return [activeKey];
+      }
+      return orderedRenderedThreadKeys.filter((key) => selected.has(key));
+    },
+    [orderedRenderedThreadKeys],
+  );
+
+  const handleThreadDragStart = useCallback(
+    (event: DragStartEvent) => {
+      const activeId = String(event.active.id);
+      threadDragInProgressRef.current = true;
+      if (activeId.startsWith("group-header:")) {
+        suppressGroupClickAfterDragRef.current = true;
+        setActiveDragLabel(null);
+        return;
+      }
+      suppressThreadClickAfterDragRef.current = true;
+      const draggedKeys = resolveDraggedThreadKeys(activeId);
+      if (draggedKeys.length > 1) {
+        setActiveDragLabel(`${draggedKeys.length} threads`);
+      } else {
+        setActiveDragLabel(sidebarThreadByKeyRef.current.get(activeId)?.title ?? "Thread");
+      }
+    },
+    [resolveDraggedThreadKeys],
+  );
+
+  const handleThreadDragCancel = useCallback((_event: DragCancelEvent) => {
+    threadDragInProgressRef.current = false;
+    setActiveDragLabel(null);
+  }, []);
+
+  const handleThreadDragEnd = useCallback(
+    (event: DragEndEvent) => {
+      threadDragInProgressRef.current = false;
+      setActiveDragLabel(null);
+      const { active, over } = event;
+      if (!over) return;
+      const activeId = String(active.id);
+      const overId = String(over.id);
+      const headerPrefix = "group-header:";
+
+      // Folder reorder.
+      if (activeId.startsWith(headerPrefix)) {
+        if (!overId.startsWith(headerPrefix)) return;
+        const draggedGroupId = activeId.slice(headerPrefix.length);
+        const overGroupId = overId.slice(headerPrefix.length);
+        if (draggedGroupId !== overGroupId) {
+          reorderThreadGroupsAction(project.projectKey, draggedGroupId, overGroupId);
+        }
+        return;
+      }
+
+      // Thread move / reorder.
+      const draggedKeys = resolveDraggedThreadKeys(activeId);
+      if (draggedKeys.length === 0) return;
+
+      if (overId === ungroupedDropId(project.projectKey)) {
+        moveThreadsToGroup(draggedKeys, null);
+        return;
+      }
+      if (overId.startsWith(headerPrefix)) {
+        moveThreadsToGroup(draggedKeys, overId.slice(headerPrefix.length), null);
+        return;
+      }
+      // Dropped onto another thread row: target that row's folder (or ungrouped).
+      const overGroupId = useUiStateStore.getState().groupIdByThreadKey[overId] ?? null;
+      if (overGroupId === null) {
+        moveThreadsToGroup(draggedKeys, null);
+      } else {
+        moveThreadsToGroup(draggedKeys, overGroupId, overId);
+      }
+    },
+    [moveThreadsToGroup, project.projectKey, reorderThreadGroupsAction, resolveDraggedThreadKeys],
+  );
+
+  const threadDnDSensors = useSensors(
+    useSensor(PointerSensor, { activationConstraint: { distance: 6 } }),
+  );
+  const threadCollisionDetection = useCallback<CollisionDetection>((args) => {
+    const pointerCollisions = pointerWithin(args);
+    if (pointerCollisions.length > 0) {
+      return pointerCollisions;
+    }
+    return closestCorners(args);
+  }, []);
+
   return (
     <>
       <div className="group/project-header relative">
@@ -2139,8 +2617,10 @@ const SidebarProjectItem = memo(function SidebarProjectItem(props: SidebarProjec
         projectExpanded={projectExpanded}
         hasOverflowingThreads={hasOverflowingThreads}
         hiddenThreadStatus={hiddenThreadStatus}
-        orderedProjectThreadKeys={orderedProjectThreadKeys}
-        renderedThreads={renderedThreads}
+        orderedProjectThreadKeys={orderedRenderedThreadKeys}
+        pinnedCollapsedThread={pinnedCollapsedThread}
+        sections={sections}
+        ungroupedRenderedThreads={ungroupedRenderedThreads}
         showEmptyThreadState={showEmptyThreadState}
         shouldShowThreadPanel={shouldShowThreadPanel}
         isThreadListExpanded={isThreadListExpanded}
@@ -2168,6 +2648,21 @@ const SidebarProjectItem = memo(function SidebarProjectItem(props: SidebarProjec
         openPrLink={openPrLink}
         expandThreadListForProject={expandThreadListForProject}
         collapseThreadListForProject={collapseThreadListForProject}
+        renamingGroupId={renamingGroupId}
+        renamingGroupTitle={renamingGroupTitle}
+        setRenamingGroupTitle={setRenamingGroupTitle}
+        onToggleGroup={handleToggleGroup}
+        onGroupContextMenu={handleGroupContextMenu}
+        commitGroupRename={commitGroupRename}
+        cancelGroupRename={cancelGroupRename}
+        dndSensors={threadDnDSensors}
+        dndCollisionDetection={threadCollisionDetection}
+        onThreadDragStart={handleThreadDragStart}
+        onThreadDragEnd={handleThreadDragEnd}
+        onThreadDragCancel={handleThreadDragCancel}
+        activeDragLabel={activeDragLabel}
+        threadDragInProgressRef={threadDragInProgressRef}
+        suppressThreadClickAfterDragRef={suppressThreadClickAfterDragRef}
       />
 
       <Dialog
diff --git a/apps/web/src/components/SidebarThreadGroupRow.tsx b/apps/web/src/components/SidebarThreadGroupRow.tsx
new file mode 100644
index 00000000000..7f1831c9ac9
--- /dev/null
+++ b/apps/web/src/components/SidebarThreadGroupRow.tsx
@@ -0,0 +1,141 @@
+import { useSortable } from "@dnd-kit/sortable";
+import { CSS } from "@dnd-kit/utilities";
+import { ChevronRightIcon, FolderIcon } from "lucide-react";
+import { memo, useCallback, useMemo } from "react";
+
+import { SidebarMenuSubButton, SidebarMenuSubItem } from "./ui/sidebar";
+import type { ThreadGroup } from "../uiStateStore";
+
+/** dnd id namespace for a folder header (distinct from thread-row ids = threadKeys). */
+export function groupHeaderDndId(groupId: string): string {
+  return `group-header:${groupId}`;
+}
+
+interface SidebarThreadGroupRowProps {
+  group: ThreadGroup;
+  threadCount: number;
+  expanded: boolean;
+  isRenaming: boolean;
+  renamingTitle: string;
+  setRenamingTitle: (title: string) => void;
+  onToggle: (groupId: string) => void;
+  onContextMenu: (groupId: string, position: { x: number; y: number }) => void;
+  commitRename: (groupId: string) => void;
+  cancelRename: () => void;
+}
+
+const SidebarThreadGroupRow = memo(function SidebarThreadGroupRow(
+  props: SidebarThreadGroupRowProps,
+) {
+  const {
+    group,
+    threadCount,
+    expanded,
+    isRenaming,
+    renamingTitle,
+    setRenamingTitle,
+    onToggle,
+    onContextMenu,
+    commitRename,
+    cancelRename,
+  } = props;
+
+  const { attributes, listeners, setNodeRef, transform, transition, isDragging, isOver } =
+    useSortable({ id: groupHeaderDndId(group.id), disabled: isRenaming });
+
+  const headerButtonRender = useMemo(() => <div role="button" tabIndex={0} />, []);
+  // Drag listeners are suppressed while renaming so typing in the input never
+  // initiates a folder drag.
+  const dragHandleProps = isRenaming ? {} : { ...attributes, ...listeners };
+
+  const handleClick = useCallback(() => {
+    onToggle(group.id);
+  }, [group.id, onToggle]);
+
+  const handleKeyDown = useCallback(
+    (event: React.KeyboardEvent) => {
+      if (event.key !== "Enter" && event.key !== " ") return;
+      event.preventDefault();
+      onToggle(group.id);
+    },
+    [group.id, onToggle],
+  );
+
+  const handleContextMenu = useCallback(
+    (event: React.MouseEvent) => {
+      event.preventDefault();
+      onContextMenu(group.id, { x: event.clientX, y: event.clientY });
+    },
+    [group.id, onContextMenu],
+  );
+
+  const handleRenameRef = useCallback((element: HTMLInputElement | null) => {
+    if (element) {
+      element.focus();
+      element.select();
+    }
+  }, []);
+
+  const handleRenameKeyDown = useCallback(
+    (event: React.KeyboardEvent<HTMLInputElement>) => {
+      event.stopPropagation();
+      if (event.key === "Enter") {
+        event.preventDefault();
+        commitRename(group.id);
+      } else if (event.key === "Escape") {
+        event.preventDefault();
+        cancelRename();
+      }
+    },
+    [cancelRename, commitRename, group.id],
+  );
+
+  return (
+    <SidebarMenuSubItem
+      ref={setNodeRef}
+      style={{ transform: CSS.Translate.toString(transform), transition }}
+      className={`w-full ${isDragging ? "z-20 opacity-80" : ""}`}
+      data-thread-group-item
+      data-thread-selection-safe
+    >
+      <SidebarMenuSubButton
+        render={headerButtonRender}
+        size="sm"
+        data-thread-selection-safe
+        data-testid={`thread-group-${group.id}`}
+        className={`h-6 w-full translate-x-0 cursor-pointer justify-start gap-1.5 px-1.5 text-left text-[11px] font-medium text-muted-foreground/80 hover:bg-accent hover:text-foreground ${
+          isOver ? "ring-1 ring-primary/50" : ""
+        }`}
+        onClick={handleClick}
+        onKeyDown={handleKeyDown}
+        onContextMenu={handleContextMenu}
+        {...dragHandleProps}
+      >
+        <ChevronRightIcon
+          className={`-ml-0.5 size-3 shrink-0 text-muted-foreground/60 transition-transform duration-150 ${
+            expanded ? "rotate-90" : ""
+          }`}
+        />
+        <FolderIcon className="size-3 shrink-0 text-muted-foreground/50" />
+        {isRenaming ? (
+          <input
+            ref={handleRenameRef}
+            className="min-w-0 flex-1 truncate rounded border border-ring bg-transparent px-0.5 text-[11px] outline-none"
+            value={renamingTitle}
+            onChange={(event) => setRenamingTitle(event.target.value)}
+            onKeyDown={handleRenameKeyDown}
+            onBlur={() => commitRename(group.id)}
+            onClick={(event) => event.stopPropagation()}
+          />
+        ) : (
+          <span className="min-w-0 flex-1 truncate">{group.name}</span>
+        )}
+        <span className="ml-auto shrink-0 tabular-nums text-[10px] text-muted-foreground/40">
+          {threadCount}
+        </span>
+      </SidebarMenuSubButton>
+    </SidebarMenuSubItem>
+  );
+});
+
+export default SidebarThreadGroupRow;
diff --git a/apps/web/src/environments/runtime/service.ts b/apps/web/src/environments/runtime/service.ts
index e9a4389764b..b8b094d0722 100644
--- a/apps/web/src/environments/runtime/service.ts
+++ b/apps/web/src/environments/runtime/service.ts
@@ -969,9 +969,26 @@ function syncThreadUiFromStore() {
   );
 }
 
+function syncThreadGroupsFromStore() {
+  const state = useStore.getState();
+  const clientSettings = getClientSettings();
+  const liveThreadKeys = new Set(
+    selectThreadsAcrossEnvironments(state).map((thread) =>
+      scopedThreadKey(scopeThreadRef(thread.environmentId, thread.id)),
+    ),
+  );
+  const liveProjectKeys = new Set(
+    selectProjectsAcrossEnvironments(state).map((project) =>
+      deriveLogicalProjectKeyFromSettings(project, clientSettings),
+    ),
+  );
+  useUiStateStore.getState().syncThreadGroups({ liveThreadKeys, liveProjectKeys });
+}
+
 function reconcileSnapshotDerivedState() {
   syncProjectUiFromStore();
   syncThreadUiFromStore();
+  syncThreadGroupsFromStore();
 
   const threads = selectThreadsAcrossEnvironments(useStore.getState());
   const activeThreadKeys = collectActiveTerminalUiThreadKeys({
diff --git a/apps/web/src/sidebarThreadGrouping.test.ts b/apps/web/src/sidebarThreadGrouping.test.ts
new file mode 100644
index 00000000000..70552c8bb95
--- /dev/null
+++ b/apps/web/src/sidebarThreadGrouping.test.ts
@@ -0,0 +1,116 @@
+import { EnvironmentId, ProjectId, ThreadId } from "@t3tools/contracts";
+import { describe, expect, it } from "vite-plus/test";
+
+import { buildGroupedThreadLayout, threadKeyOf } from "./sidebarThreadGrouping";
+import type { ThreadGroup } from "./uiStateStore";
+import type { SidebarThreadSummary } from "./types";
+
+const ENV = EnvironmentId.make("env-1");
+const PROJ = ProjectId.make("proj-1");
+
+function makeThread(id: string): SidebarThreadSummary {
+  return {
+    id: ThreadId.make(id),
+    environmentId: ENV,
+    projectId: PROJ,
+    title: id,
+    interactionMode: "default",
+    session: null,
+    createdAt: "2026-06-13T00:00:00.000Z",
+    archivedAt: null,
+    latestTurn: null,
+    branch: null,
+    worktreePath: null,
+    latestUserMessageAt: null,
+    hasPendingApprovals: false,
+    hasPendingUserInput: false,
+    hasActionableProposedPlan: false,
+  };
+}
+
+function group(id: string, threads: SidebarThreadSummary[]): ThreadGroup {
+  return { id, projectKey: "pk", name: id, threadKeys: threads.map(threadKeyOf) };
+}
+
+describe("buildGroupedThreadLayout", () => {
+  const t1 = makeThread("t1");
+  const t2 = makeThread("t2");
+  const t3 = makeThread("t3");
+  const t4 = makeThread("t4");
+
+  it("splits threads into folder sections (in folder order) plus ungrouped", () => {
+    const g1 = group("g1", [t2]);
+    const g2 = group("g2", [t3]);
+    const layout = buildGroupedThreadLayout({
+      visibleProjectThreads: [t1, t2, t3, t4],
+      projectKey: "pk",
+      groups: { g1, g2 },
+      groupOrder: ["g2", "g1"],
+      groupExpandedById: {},
+    });
+
+    expect(layout.sections.map((s) => s.group.id)).toEqual(["g2", "g1"]);
+    expect(layout.sections[0]!.threads).toEqual([t3]);
+    expect(layout.sections[1]!.threads).toEqual([t2]);
+    expect(layout.ungroupedThreads).toEqual([t1, t4]);
+  });
+
+  it("orders threads within a folder by the folder's threadKeys, not sort order", () => {
+    const g1: ThreadGroup = {
+      id: "g1",
+      projectKey: "pk",
+      name: "g1",
+      threadKeys: [threadKeyOf(t3), threadKeyOf(t1)],
+    };
+    const layout = buildGroupedThreadLayout({
+      visibleProjectThreads: [t1, t2, t3],
+      projectKey: "pk",
+      groups: { g1 },
+      groupOrder: ["g1"],
+      groupExpandedById: {},
+    });
+    expect(layout.sections[0]!.threads).toEqual([t3, t1]);
+    expect(layout.ungroupedThreads).toEqual([t2]);
+  });
+
+  it("defaults a folder to expanded and honours an explicit collapse", () => {
+    const g1 = group("g1", [t1]);
+    const layout = buildGroupedThreadLayout({
+      visibleProjectThreads: [t1],
+      projectKey: "pk",
+      groups: { g1 },
+      groupOrder: ["g1"],
+      groupExpandedById: { g1: false },
+    });
+    expect(layout.sections[0]!.expanded).toBe(false);
+  });
+
+  it("ignores folders from a different project and threads no longer visible", () => {
+    const sameProject = group("g1", [t1]);
+    const otherProject: ThreadGroup = {
+      id: "g2",
+      projectKey: "other",
+      name: "g2",
+      threadKeys: [threadKeyOf(t2)],
+    };
+    // g1 references t4, which is not in the visible set -> contributes no row.
+    const staleMember: ThreadGroup = {
+      id: "g3",
+      projectKey: "pk",
+      name: "g3",
+      threadKeys: [threadKeyOf(t4)],
+    };
+    const layout = buildGroupedThreadLayout({
+      visibleProjectThreads: [t1, t2],
+      projectKey: "pk",
+      groups: { g1: sameProject, g2: otherProject, g3: staleMember },
+      groupOrder: ["g1", "g2", "g3"],
+      groupExpandedById: {},
+    });
+
+    expect(layout.sections.map((s) => s.group.id)).toEqual(["g1", "g3"]);
+    expect(layout.sections.find((s) => s.group.id === "g3")!.threads).toEqual([]);
+    // t2 belongs to a folder scoped to another project, so it stays ungrouped here.
+    expect(layout.ungroupedThreads).toEqual([t2]);
+  });
+});
diff --git a/apps/web/src/sidebarThreadGrouping.ts b/apps/web/src/sidebarThreadGrouping.ts
new file mode 100644
index 00000000000..d86f6b074eb
--- /dev/null
+++ b/apps/web/src/sidebarThreadGrouping.ts
@@ -0,0 +1,72 @@
+import { scopedThreadKey, scopeThreadRef } from "@t3tools/client-runtime";
+
+import type { ThreadGroup } from "./uiStateStore";
+import type { SidebarThreadSummary } from "./types";
+
+/** A folder plus the visible threads it currently holds, in folder order. */
+export interface ThreadGroupSection {
+  group: ThreadGroup;
+  threads: SidebarThreadSummary[];
+  expanded: boolean;
+}
+
+export interface GroupedThreadLayout {
+  /** Folder sections in the project's folder order. */
+  sections: ThreadGroupSection[];
+  /** Threads not in any folder, preserving the input sort order. */
+  ungroupedThreads: SidebarThreadSummary[];
+}
+
+export function threadKeyOf(thread: SidebarThreadSummary): string {
+  return scopedThreadKey(scopeThreadRef(thread.environmentId, thread.id));
+}
+
+/**
+ * Split a project's (already sorted, non-archived) threads into ordered folder
+ * sections plus the remaining ungrouped threads. Pure: no store access, so it is
+ * straightforward to unit test. Folders that reference threads not present in
+ * `visibleProjectThreads` simply render fewer rows; threads in no folder fall
+ * through to `ungroupedThreads`.
+ */
+export function buildGroupedThreadLayout(input: {
+  visibleProjectThreads: readonly SidebarThreadSummary[];
+  projectKey: string;
+  groups: Record<string, ThreadGroup>;
+  groupOrder: readonly string[];
+  groupExpandedById: Record<string, boolean>;
+}): GroupedThreadLayout {
+  const { visibleProjectThreads, projectKey, groups, groupOrder, groupExpandedById } = input;
+
+  const threadByKey = new Map<string, SidebarThreadSummary>();
+  for (const thread of visibleProjectThreads) {
+    threadByKey.set(threadKeyOf(thread), thread);
+  }
+
+  const claimed = new Set<string>();
+  const sections: ThreadGroupSection[] = [];
+  for (const groupId of groupOrder) {
+    const group = groups[groupId];
+    if (!group || group.projectKey !== projectKey) {
+      continue;
+    }
+    const threads: SidebarThreadSummary[] = [];
+    for (const threadKey of group.threadKeys) {
+      const thread = threadByKey.get(threadKey);
+      if (thread) {
+        threads.push(thread);
+        claimed.add(threadKey);
+      }
+    }
+    sections.push({
+      group,
+      threads,
+      expanded: groupExpandedById[groupId] ?? true,
+    });
+  }
+
+  const ungroupedThreads = visibleProjectThreads.filter(
+    (thread) => !claimed.has(threadKeyOf(thread)),
+  );
+
+  return { sections, ungroupedThreads };
+}
diff --git a/apps/web/src/uiStateStore.test.ts b/apps/web/src/uiStateStore.test.ts
index c6f445b0c32..ce206218927 100644
--- a/apps/web/src/uiStateStore.test.ts
+++ b/apps/web/src/uiStateStore.test.ts
@@ -3,18 +3,27 @@ import { afterEach, beforeEach, describe, expect, it, vi } from "vite-plus/test"
 
 import {
   clearThreadUi,
+  createThreadGroup,
+  deleteThreadGroup,
   hydratePersistedProjectState,
   markThreadVisited,
   markThreadUnread,
+  moveThreadsToGroup,
   PERSISTED_STATE_KEY,
   type PersistedUiState,
   persistState,
+  renameThreadGroup,
   reorderProjects,
+  reorderThreadGroups,
+  sanitizePersistedThreadGroups,
   setDefaultAdvertisedEndpointKey,
   setProjectExpanded,
   setThreadChangedFilesExpanded,
+  setThreadGroupExpanded,
   syncProjects,
+  syncThreadGroups,
   syncThreads,
+  toggleThreadGroup,
   type UiState,
 } from "./uiStateStore";
 
@@ -25,6 +34,10 @@ function makeUiState(overrides: Partial<UiState> = {}): UiState {
     threadLastVisitedAtById: {},
     threadChangedFilesExpandedById: {},
     defaultAdvertisedEndpointKey: null,
+    threadGroupsById: {},
+    threadGroupOrderByProjectKey: {},
+    threadGroupExpandedById: {},
+    groupIdByThreadKey: {},
     ...overrides,
   };
 }
@@ -445,6 +458,140 @@ describe("uiStateStore pure functions", () => {
   });
 });
 
+describe("uiStateStore thread folders", () => {
+  const P = "proj-A";
+
+  it("createThreadGroup registers the folder and appends to project order", () => {
+    const next = createThreadGroup(makeUiState(), { projectKey: P, id: "g1", name: "Experiments" });
+
+    expect(next.threadGroupsById.g1).toEqual({
+      id: "g1",
+      projectKey: P,
+      name: "Experiments",
+      threadKeys: [],
+    });
+    expect(next.threadGroupOrderByProjectKey[P]).toEqual(["g1"]);
+  });
+
+  it("createThreadGroup with members removes them from prior folders and indexes them", () => {
+    let state = createThreadGroup(makeUiState(), { projectKey: P, id: "g1", name: "A" });
+    state = moveThreadsToGroup(state, ["t1", "t2"], "g1");
+    state = createThreadGroup(state, {
+      projectKey: P,
+      id: "g2",
+      name: "B",
+      threadKeys: ["t2", "t3"],
+    });
+
+    expect(state.threadGroupsById.g1!.threadKeys).toEqual(["t1"]);
+    expect(state.threadGroupsById.g2!.threadKeys).toEqual(["t2", "t3"]);
+    expect(state.groupIdByThreadKey).toEqual({ t1: "g1", t2: "g2", t3: "g2" });
+  });
+
+  it("moveThreadsToGroup is a single-folder move (at most one folder per thread)", () => {
+    let state = createThreadGroup(makeUiState(), { projectKey: P, id: "g1", name: "A" });
+    state = createThreadGroup(state, { projectKey: P, id: "g2", name: "B" });
+    state = moveThreadsToGroup(state, ["t1"], "g1");
+    state = moveThreadsToGroup(state, ["t1"], "g2");
+
+    expect(state.threadGroupsById.g1!.threadKeys).toEqual([]);
+    expect(state.threadGroupsById.g2!.threadKeys).toEqual(["t1"]);
+    expect(state.groupIdByThreadKey.t1).toBe("g2");
+  });
+
+  it("moveThreadsToGroup inserts before the target thread for ordering", () => {
+    let state = createThreadGroup(makeUiState(), {
+      projectKey: P,
+      id: "g1",
+      name: "A",
+      threadKeys: ["t1", "t2", "t3"],
+    });
+    state = moveThreadsToGroup(state, ["t3"], "g1", "t1");
+
+    expect(state.threadGroupsById.g1!.threadKeys).toEqual(["t3", "t1", "t2"]);
+  });
+
+  it("moveThreadsToGroup with null target removes membership (back to ungrouped)", () => {
+    let state = createThreadGroup(makeUiState(), {
+      projectKey: P,
+      id: "g1",
+      name: "A",
+      threadKeys: ["t1", "t2"],
+    });
+    state = moveThreadsToGroup(state, ["t1"], null);
+
+    expect(state.threadGroupsById.g1!.threadKeys).toEqual(["t2"]);
+    expect(state.groupIdByThreadKey).toEqual({ t2: "g1" });
+  });
+
+  it("deleteThreadGroup returns members to ungrouped and drops order/expanded entries", () => {
+    let state = createThreadGroup(makeUiState(), {
+      projectKey: P,
+      id: "g1",
+      name: "A",
+      threadKeys: ["t1"],
+    });
+    state = setThreadGroupExpanded(state, "g1", false);
+    state = deleteThreadGroup(state, "g1");
+
+    expect(state.threadGroupsById).toEqual({});
+    expect(state.threadGroupOrderByProjectKey).toEqual({});
+    expect(state.threadGroupExpandedById).toEqual({});
+    expect(state.groupIdByThreadKey).toEqual({});
+  });
+
+  it("renameThreadGroup trims and ignores empty names", () => {
+    let state = createThreadGroup(makeUiState(), { projectKey: P, id: "g1", name: "A" });
+    state = renameThreadGroup(state, "g1", "  PRs in review  ");
+    expect(state.threadGroupsById.g1!.name).toBe("PRs in review");
+    expect(renameThreadGroup(state, "g1", "   ")).toBe(state);
+  });
+
+  it("toggleThreadGroup flips collapse, defaulting to expanded", () => {
+    let state = createThreadGroup(makeUiState(), { projectKey: P, id: "g1", name: "A" });
+    state = toggleThreadGroup(state, "g1");
+    expect(state.threadGroupExpandedById.g1).toBe(false);
+    state = toggleThreadGroup(state, "g1");
+    expect(state.threadGroupExpandedById.g1).toBe(true);
+  });
+
+  it("reorderThreadGroups moves a folder before another within the project", () => {
+    let state = createThreadGroup(makeUiState(), { projectKey: P, id: "g1", name: "A" });
+    state = createThreadGroup(state, { projectKey: P, id: "g2", name: "B" });
+    state = createThreadGroup(state, { projectKey: P, id: "g3", name: "C" });
+    state = reorderThreadGroups(state, P, "g3", "g1");
+    expect(state.threadGroupOrderByProjectKey[P]).toEqual(["g3", "g1", "g2"]);
+  });
+
+  it("syncThreadGroups prunes dead threads and drops empty folders in dead projects", () => {
+    let state = createThreadGroup(makeUiState(), {
+      projectKey: P,
+      id: "g1",
+      name: "A",
+      threadKeys: ["t1", "t2"],
+    });
+    state = createThreadGroup(state, { projectKey: "dead-proj", id: "g2", name: "B" });
+
+    const next = syncThreadGroups(state, {
+      liveThreadKeys: new Set(["t1"]),
+      liveProjectKeys: new Set([P]),
+    });
+
+    expect(next.threadGroupsById.g1!.threadKeys).toEqual(["t1"]);
+    expect(next.threadGroupsById.g2).toBeUndefined();
+    expect(next.groupIdByThreadKey).toEqual({ t1: "g1" });
+  });
+
+  it("syncThreadGroups keeps empty folders that belong to a live project", () => {
+    const state = createThreadGroup(makeUiState(), { projectKey: P, id: "g1", name: "A" });
+    const next = syncThreadGroups(state, {
+      liveThreadKeys: new Set<string>(),
+      liveProjectKeys: new Set([P]),
+    });
+    expect(next).toBe(state);
+  });
+});
+
 function createLocalStorageStub(): Storage {
   const store = new Map<string, string>();
   return {
@@ -607,4 +754,29 @@ describe("uiStateStore persistence round-trip", () => {
 
     expect(rehydrated.projectExpandedById[nextLogicalKey]).toBe(false);
   });
+
+  it("round-trips thread folders (membership, order, collapse) across restart", () => {
+    let state = createThreadGroup(makeUiState(), {
+      projectKey: "proj-A",
+      id: "g1",
+      name: "PRs in review",
+      threadKeys: ["env:t1", "env:t2"],
+    });
+    state = createThreadGroup(state, { projectKey: "proj-A", id: "g2", name: "Experiments" });
+    state = reorderThreadGroups(state, "proj-A", "g2", "g1");
+    state = setThreadGroupExpanded(state, "g1", false);
+    persistState(state);
+
+    const persisted = JSON.parse(
+      localStorageStub.getItem(PERSISTED_STATE_KEY) ?? "{}",
+    ) as PersistedUiState;
+    expect(persisted.threadGroupOrderByProjectKey).toEqual({ "proj-A": ["g2", "g1"] });
+    expect(persisted.collapsedThreadGroupIds).toEqual(["g1"]);
+
+    const rehydrated = sanitizePersistedThreadGroups(persisted);
+    expect(rehydrated.threadGroupsById.g1!.threadKeys).toEqual(["env:t1", "env:t2"]);
+    expect(rehydrated.threadGroupOrderByProjectKey).toEqual({ "proj-A": ["g2", "g1"] });
+    expect(rehydrated.threadGroupExpandedById).toEqual({ g1: false });
+    expect(rehydrated.groupIdByThreadKey).toEqual({ "env:t1": "g1", "env:t2": "g1" });
+  });
 });
diff --git a/apps/web/src/uiStateStore.ts b/apps/web/src/uiStateStore.ts
index f16495bed7f..f6cda0ad1f5 100644
--- a/apps/web/src/uiStateStore.ts
+++ b/apps/web/src/uiStateStore.ts
@@ -1,6 +1,8 @@
 import { Debouncer } from "@tanstack/react-pacer";
 import { create } from "zustand";
 
+import { randomUUID } from "./lib/utils";
+
 export const PERSISTED_STATE_KEY = "t3code:ui-state:v1";
 const LEGACY_PERSISTED_STATE_KEYS = [
   "t3code:renderer-state:v8",
@@ -21,6 +23,9 @@ export interface PersistedUiState {
   projectOrderCwds?: string[];
   defaultAdvertisedEndpointKey?: string | null;
   threadChangedFilesExpandedById?: Record<string, Record<string, boolean>>;
+  threadGroups?: Array<{ id: string; projectKey: string; name: string; threadKeys: string[] }>;
+  threadGroupOrderByProjectKey?: Record<string, string[]>;
+  collapsedThreadGroupIds?: string[];
 }
 
 export interface UiProjectState {
@@ -28,6 +33,32 @@ export interface UiProjectState {
   projectOrder: string[];
 }
 
+/**
+ * A user-defined, client-only folder that groups a single project's threads in
+ * the sidebar. Membership and within-folder order are both represented by the
+ * ordered `threadKeys` array (the single source of truth). Folders are scoped to
+ * one logical project via `projectKey`.
+ */
+export interface ThreadGroup {
+  /** Stable generated id (see newThreadGroupId); never derived from contents. */
+  id: string;
+  /** Logical project key the folder lives under (same space as projectExpandedById). */
+  projectKey: string;
+  name: string;
+  /** Ordered membership; the array order is the within-folder display order. */
+  threadKeys: string[];
+}
+
+export interface UiGroupState {
+  threadGroupsById: Record<string, ThreadGroup>;
+  /** Ordered folder ids per logical project key. */
+  threadGroupOrderByProjectKey: Record<string, string[]>;
+  /** Folder collapse state. Absent id defaults to expanded, like projectExpandedById. */
+  threadGroupExpandedById: Record<string, boolean>;
+  /** Derived reverse index (threadKey -> groupId). Rebuilt on mutation; not persisted. */
+  groupIdByThreadKey: Record<string, string>;
+}
+
 export interface UiThreadState {
   threadLastVisitedAtById: Record<string, string>;
   threadChangedFilesExpandedById: Record<string, Record<string, boolean>>;
@@ -37,7 +68,7 @@ export interface UiEndpointState {
   defaultAdvertisedEndpointKey: string | null;
 }
 
-export interface UiState extends UiProjectState, UiThreadState, UiEndpointState {}
+export interface UiState extends UiProjectState, UiThreadState, UiEndpointState, UiGroupState {}
 
 export interface SyncProjectInput {
   /** Physical project key (env + cwd). Used for manual sort order. */
@@ -58,6 +89,10 @@ const initialState: UiState = {
   threadLastVisitedAtById: {},
   threadChangedFilesExpandedById: {},
   defaultAdvertisedEndpointKey: null,
+  threadGroupsById: {},
+  threadGroupOrderByProjectKey: {},
+  threadGroupExpandedById: {},
+  groupIdByThreadKey: {},
 };
 
 const persistedCollapsedProjectCwds = new Set<string>();
@@ -103,6 +138,7 @@ function readPersistedState(): UiState {
       threadChangedFilesExpandedById: sanitizePersistedThreadChangedFilesExpanded(
         parsed.threadChangedFilesExpandedById,
       ),
+      ...sanitizePersistedThreadGroups(parsed),
     };
   } catch {
     return initialState;
@@ -137,6 +173,121 @@ function sanitizePersistedThreadChangedFilesExpanded(
   return nextState;
 }
 
+/** Recompute the derived threadKey -> groupId reverse index from scratch. */
+function rebuildGroupIndex(groups: Record<string, ThreadGroup>): Record<string, string> {
+  const index: Record<string, string> = {};
+  for (const group of Object.values(groups)) {
+    for (const threadKey of group.threadKeys) {
+      index[threadKey] = group.id;
+    }
+  }
+  return index;
+}
+
+/** Drop the given threadKeys from every folder. Returns the same map if unchanged. */
+function removeThreadKeysFromGroups(
+  groups: Record<string, ThreadGroup>,
+  threadKeys: ReadonlySet<string>,
+): Record<string, ThreadGroup> {
+  let changed = false;
+  const next: Record<string, ThreadGroup> = {};
+  for (const [id, group] of Object.entries(groups)) {
+    const filtered = group.threadKeys.filter((key) => !threadKeys.has(key));
+    if (filtered.length !== group.threadKeys.length) {
+      changed = true;
+      next[id] = { ...group, threadKeys: filtered };
+    } else {
+      next[id] = group;
+    }
+  }
+  return changed ? next : groups;
+}
+
+function dedupePreserveOrder(keys: readonly string[]): string[] {
+  const seen = new Set<string>();
+  const result: string[] = [];
+  for (const key of keys) {
+    if (!seen.has(key)) {
+      seen.add(key);
+      result.push(key);
+    }
+  }
+  return result;
+}
+
+export function sanitizePersistedThreadGroups(
+  parsed: PersistedUiState,
+): Pick<
+  UiState,
+  | "threadGroupsById"
+  | "threadGroupOrderByProjectKey"
+  | "threadGroupExpandedById"
+  | "groupIdByThreadKey"
+> {
+  const threadGroupsById: Record<string, ThreadGroup> = {};
+  for (const raw of parsed.threadGroups ?? []) {
+    if (
+      !raw ||
+      typeof raw !== "object" ||
+      typeof raw.id !== "string" ||
+      raw.id.length === 0 ||
+      typeof raw.projectKey !== "string" ||
+      raw.projectKey.length === 0 ||
+      typeof raw.name !== "string"
+    ) {
+      continue;
+    }
+    const threadKeys = Array.isArray(raw.threadKeys)
+      ? dedupePreserveOrder(
+          raw.threadKeys.filter((key): key is string => typeof key === "string" && key.length > 0),
+        )
+      : [];
+    threadGroupsById[raw.id] = {
+      id: raw.id,
+      projectKey: raw.projectKey,
+      name: raw.name,
+      threadKeys,
+    };
+  }
+
+  const threadGroupOrderByProjectKey: Record<string, string[]> = {};
+  for (const [projectKey, order] of Object.entries(parsed.threadGroupOrderByProjectKey ?? {})) {
+    if (typeof projectKey !== "string" || !Array.isArray(order)) {
+      continue;
+    }
+    const filtered = dedupePreserveOrder(
+      order.filter((id): id is string => typeof id === "string" && id in threadGroupsById),
+    );
+    if (filtered.length > 0) {
+      threadGroupOrderByProjectKey[projectKey] = filtered;
+    }
+  }
+  // Defensively append any folder missing from its project's order list.
+  for (const group of Object.values(threadGroupsById)) {
+    const order = threadGroupOrderByProjectKey[group.projectKey] ?? [];
+    if (!order.includes(group.id)) {
+      threadGroupOrderByProjectKey[group.projectKey] = [...order, group.id];
+    }
+  }
+
+  const collapsed = new Set(
+    (parsed.collapsedThreadGroupIds ?? []).filter((id): id is string => typeof id === "string"),
+  );
+  const threadGroupExpandedById: Record<string, boolean> = {};
+  for (const id of Object.keys(threadGroupsById)) {
+    if (collapsed.has(id)) {
+      threadGroupExpandedById[id] = false;
+    }
+  }
+
+  return {
+    threadGroupsById,
+    threadGroupOrderByProjectKey,
+    threadGroupExpandedById,
+    groupIdByThreadKey: rebuildGroupIndex(threadGroupsById),
+  };
+}
+
 export function hydratePersistedProjectState(parsed: PersistedUiState): void {
   persistedCollapsedProjectCwds.clear();
   persistedExpandedProjectCwds.clear();
@@ -187,6 +338,15 @@ export function persistState(state: UiState): void {
         return Object.keys(nextTurns).length > 0 ? [[threadId, nextTurns]] : [];
       }),
     );
+    const threadGroups = Object.values(state.threadGroupsById).map((group) => ({
+      id: group.id,
+      projectKey: group.projectKey,
+      name: group.name,
+      threadKeys: group.threadKeys,
+    }));
+    const collapsedThreadGroupIds = Object.entries(state.threadGroupExpandedById)
+      .filter(([, expanded]) => !expanded)
+      .map(([id]) => id);
     window.localStorage.setItem(
       PERSISTED_STATE_KEY,
       JSON.stringify({
@@ -195,6 +355,9 @@ export function persistState(state: UiState): void {
         projectOrderCwds,
         defaultAdvertisedEndpointKey: state.defaultAdvertisedEndpointKey,
         threadChangedFilesExpandedById,
+        threadGroups,
+        threadGroupOrderByProjectKey: state.threadGroupOrderByProjectKey,
+        collapsedThreadGroupIds,
       } satisfies PersistedUiState),
     );
     if (!legacyKeysCleanedUp) {
@@ -633,6 +796,261 @@ export function reorderProjects(
   };
 }
 
+/** Generate a stable, unique thread-folder id. */
+export function newThreadGroupId(): string {
+  return `grp_${randomUUID()}`;
+}
+
+export function createThreadGroup(
+  state: UiState,
+  args: { projectKey: string; id: string; name: string; threadKeys?: readonly string[] },
+): UiState {
+  const { projectKey, id, name } = args;
+  if (id in state.threadGroupsById) {
+    return state;
+  }
+  const memberKeys = dedupePreserveOrder(args.threadKeys ?? []);
+  const groupsWithoutMembers =
+    memberKeys.length > 0
+      ? removeThreadKeysFromGroups(state.threadGroupsById, new Set(memberKeys))
+      : state.threadGroupsById;
+  const nextGroups: Record<string, ThreadGroup> = {
+    ...groupsWithoutMembers,
+    [id]: { id, projectKey, name, threadKeys: memberKeys },
+  };
+  const order = state.threadGroupOrderByProjectKey[projectKey] ?? [];
+  return {
+    ...state,
+    threadGroupsById: nextGroups,
+    threadGroupOrderByProjectKey: {
+      ...state.threadGroupOrderByProjectKey,
+      [projectKey]: [...order, id],
+    },
+    groupIdByThreadKey: rebuildGroupIndex(nextGroups),
+  };
+}
+
+export function renameThreadGroup(state: UiState, groupId: string, name: string): UiState {
+  const group = state.threadGroupsById[groupId];
+  const trimmed = name.trim();
+  if (!group || trimmed.length === 0 || group.name === trimmed) {
+    return state;
+  }
+  return {
+    ...state,
+    threadGroupsById: {
+      ...state.threadGroupsById,
+      [groupId]: { ...group, name: trimmed },
+    },
+  };
+}
+
+export function deleteThreadGroup(state: UiState, groupId: string): UiState {
+  const group = state.threadGroupsById[groupId];
+  if (!group) {
+    return state;
+  }
+  const nextGroups = { ...state.threadGroupsById };
+  delete nextGroups[groupId];
+
+  const nextOrderByProject = { ...state.threadGroupOrderByProjectKey };
+  const order = nextOrderByProject[group.projectKey];
+  if (order) {
+    const filtered = order.filter((id) => id !== groupId);
+    if (filtered.length > 0) {
+      nextOrderByProject[group.projectKey] = filtered;
+    } else {
+      delete nextOrderByProject[group.projectKey];
+    }
+  }
+
+  const nextExpanded = { ...state.threadGroupExpandedById };
+  delete nextExpanded[groupId];
+
+  return {
+    ...state,
+    threadGroupsById: nextGroups,
+    threadGroupOrderByProjectKey: nextOrderByProject,
+    threadGroupExpandedById: nextExpanded,
+    groupIdByThreadKey: rebuildGroupIndex(nextGroups),
+  };
+}
+
+export function toggleThreadGroup(state: UiState, groupId: string): UiState {
+  if (!(groupId in state.threadGroupsById)) {
+    return state;
+  }
+  const expanded = state.threadGroupExpandedById[groupId] ?? true;
+  return {
+    ...state,
+    threadGroupExpandedById: {
+      ...state.threadGroupExpandedById,
+      [groupId]: !expanded,
+    },
+  };
+}
+
+export function setThreadGroupExpanded(
+  state: UiState,
+  groupId: string,
+  expanded: boolean,
+): UiState {
+  if (
+    !(groupId in state.threadGroupsById) ||
+    (state.threadGroupExpandedById[groupId] ?? true) === expanded
+  ) {
+    return state;
+  }
+  return {
+    ...state,
+    threadGroupExpandedById: {
+      ...state.threadGroupExpandedById,
+      [groupId]: expanded,
+    },
+  };
+}
+
+/**
+ * Move one or more threads into a folder (or out to ungrouped when
+ * targetGroupId is null). Also performs intra-folder reordering: each thread is
+ * first removed from whatever folder holds it, then inserted into the target at
+ * `beforeThreadKey` (or appended when null/absent). Mirrors reorderProjects in
+ * taking an array so multi-select moves work in one call.
+ */
+export function moveThreadsToGroup(
+  state: UiState,
+  threadKeys: readonly string[],
+  targetGroupId: string | null,
+  beforeThreadKey?: string | null,
+): UiState {
+  if (threadKeys.length === 0) {
+    return state;
+  }
+  if (targetGroupId !== null && !(targetGroupId in state.threadGroupsById)) {
+    return state;
+  }
+  const movingKeys = dedupePreserveOrder(threadKeys);
+  const movingSet = new Set(movingKeys);
+  const groupsAfterRemoval = removeThreadKeysFromGroups(state.threadGroupsById, movingSet);
+
+  let nextGroups = groupsAfterRemoval;
+  if (targetGroupId !== null) {
+    const target = groupsAfterRemoval[targetGroupId]!;
+    const insertAt =
+      beforeThreadKey != null
+        ? (() => {
+            const idx = target.threadKeys.indexOf(beforeThreadKey);
+            return idx < 0 ? target.threadKeys.length : idx;
+          })()
+        : target.threadKeys.length;
+    const nextThreadKeys = [
+      ...target.threadKeys.slice(0, insertAt),
+      ...movingKeys,
+      ...target.threadKeys.slice(insertAt),
+    ];
+    nextGroups = {
+      ...groupsAfterRemoval,
+      [targetGroupId]: { ...target, threadKeys: nextThreadKeys },
+    };
+  }
+
+  if (nextGroups === state.threadGroupsById) {
+    return state;
+  }
+  return {
+    ...state,
+    threadGroupsById: nextGroups,
+    groupIdByThreadKey: rebuildGroupIndex(nextGroups),
+  };
+}
+
+/** Reorder a folder within its project's folder list, inserting before overGroupId. */
+export function reorderThreadGroups(
+  state: UiState,
+  projectKey: string,
+  draggedGroupId: string,
+  overGroupId: string,
+): UiState {
+  if (draggedGroupId === overGroupId) {
+    return state;
+  }
+  const order = state.threadGroupOrderByProjectKey[projectKey];
+  if (!order) {
+    return state;
+  }
+  const fromIndex = order.indexOf(draggedGroupId);
+  const toIndex = order.indexOf(overGroupId);
+  if (fromIndex < 0 || toIndex < 0) {
+    return state;
+  }
+  const next = [...order];
+  next.splice(fromIndex, 1);
+  const insertAt = next.indexOf(overGroupId);
+  next.splice(insertAt, 0, draggedGroupId);
+  return {
+    ...state,
+    threadGroupOrderByProjectKey: {
+      ...state.threadGroupOrderByProjectKey,
+      [projectKey]: next,
+    },
+  };
+}
+
+/**
+ * Garbage-collect folder state against the live snapshot: drop memberships for
+ * threads that no longer exist, and drop folders that have become empty AND
+ * whose project is no longer rendered. Empty folders in a live project are kept
+ * (a freshly-created folder must survive). Folders whose projectKey is stale but
+ * still hold live members are left intact (their members fall back to ungrouped
+ * until the project reappears) — see the projectKey-stability note in the plan.
+ */
+export function syncThreadGroups(
+  state: UiState,
+  args: { liveThreadKeys: ReadonlySet<string>; liveProjectKeys: ReadonlySet<string> },
+): UiState {
+  const { liveThreadKeys, liveProjectKeys } = args;
+  let changed = false;
+  const nextGroups: Record<string, ThreadGroup> = {};
+  for (const [id, group] of Object.entries(state.threadGroupsById)) {
+    const prunedKeys = group.threadKeys.filter((key) => liveThreadKeys.has(key));
+    const projectLive = liveProjectKeys.has(group.projectKey);
+    if (prunedKeys.length === 0 && !projectLive) {
+      changed = true;
+      continue;
+    }
+    if (prunedKeys.length !== group.threadKeys.length) {
+      changed = true;
+      nextGroups[id] = { ...group, threadKeys: prunedKeys };
+    } else {
+      nextGroups[id] = group;
+    }
+  }
+  if (!changed) {
+    return state;
+  }
+
+  const nextOrderByProject: Record<string, string[]> = {};
+  for (const [projectKey, order] of Object.entries(state.threadGroupOrderByProjectKey)) {
+    const filtered = order.filter((id) => id in nextGroups);
+    if (filtered.length > 0) {
+      nextOrderByProject[projectKey] = filtered;
+    }
+  }
+  const nextExpanded: Record<string, boolean> = {};
+  for (const [id, expanded] of Object.entries(state.threadGroupExpandedById)) {
+    if (id in nextGroups) {
+      nextExpanded[id] = expanded;
+    }
+  }
+  return {
+    ...state,
+    threadGroupsById: nextGroups,
+    threadGroupOrderByProjectKey: nextOrderByProject,
+    threadGroupExpandedById: nextExpanded,
+    groupIdByThreadKey: rebuildGroupIndex(nextGroups),
+  };
+}
+
 interface UiStateStore extends UiState {
   syncProjects: (projects: readonly SyncProjectInput[]) => void;
   syncThreads: (threads: readonly SyncThreadInput[]) => void;
@@ -647,6 +1065,26 @@ interface UiStateStore extends UiState {
     draggedProjectIds: readonly string[],
     targetProjectIds: readonly string[],
   ) => void;
+  createThreadGroup: (args: {
+    projectKey: string;
+    id: string;
+    name: string;
+    threadKeys?: readonly string[];
+  }) => void;
+  renameThreadGroup: (groupId: string, name: string) => void;
+  deleteThreadGroup: (groupId: string) => void;
+  toggleThreadGroup: (groupId: string) => void;
+  setThreadGroupExpanded: (groupId: string, expanded: boolean) => void;
+  moveThreadsToGroup: (
+    threadKeys: readonly string[],
+    targetGroupId: string | null,
+    beforeThreadKey?: string | null,
+  ) => void;
+  reorderThreadGroups: (projectKey: string, draggedGroupId: string, overGroupId: string) => void;
+  syncThreadGroups: (args: {
+    liveThreadKeys: ReadonlySet<string>;
+    liveProjectKeys: ReadonlySet<string>;
+  }) => void;
 }
 
 export const useUiStateStore = create<UiStateStore>((set) => ({
@@ -667,6 +1105,17 @@ export const useUiStateStore = create<UiStateStore>((set) => ({
     set((state) => setProjectExpanded(state, projectId, expanded)),
   reorderProjects: (draggedProjectIds, targetProjectIds) =>
     set((state) => reorderProjects(state, draggedProjectIds, targetProjectIds)),
+  createThreadGroup: (args) => set((state) => createThreadGroup(state, args)),
+  renameThreadGroup: (groupId, name) => set((state) => renameThreadGroup(state, groupId, name)),
+  deleteThreadGroup: (groupId) => set((state) => deleteThreadGroup(state, groupId)),
+  toggleThreadGroup: (groupId) => set((state) => toggleThreadGroup(state, groupId)),
+  setThreadGroupExpanded: (groupId, expanded) =>
+    set((state) => setThreadGroupExpanded(state, groupId, expanded)),
+  moveThreadsToGroup: (threadKeys, targetGroupId, beforeThreadKey) =>
+    set((state) => moveThreadsToGroup(state, threadKeys, targetGroupId, beforeThreadKey)),
+  reorderThreadGroups: (projectKey, draggedGroupId, overGroupId) =>
+    set((state) => reorderThreadGroups(state, projectKey, draggedGroupId, overGroupId)),
+  syncThreadGroups: (args) => set((state) => syncThreadGroups(state, args)),
 }));
 
 useUiStateStore.subscribe((state) => debouncedPersistState.maybeExecute(state));

From b7e73e166bb5af8df239956f61376c463a1c1a89 Mon Sep 17 00:00:00 2001
From: TheIcarusWings <10465470+TheIcarusWings@users.noreply.github.com>
Date: Sat, 13 Jun 2026 15:32:30 +0100
Subject: [PATCH 2/4] fix(sidebar): indent threads inside folders with a guide
 line

Folder-member rows now render inset with a left vertical guide so the
nesting under a folder header is visually obvious; ungrouped and
collapsed-pinned threads stay flush.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 apps/web/src/components/Sidebar.tsx | 12 +++++++++---
 1 file changed, 9 insertions(+), 3 deletions(-)

diff --git a/apps/web/src/components/Sidebar.tsx b/apps/web/src/components/Sidebar.tsx
index 90c50f0214d..d98d487389f 100644
--- a/apps/web/src/components/Sidebar.tsx
+++ b/apps/web/src/components/Sidebar.tsx
@@ -329,6 +329,8 @@ interface SidebarThreadRowProps {
   openPrLink: (event: React.MouseEvent<HTMLElement>, prUrl: string) => void;
   threadDragInProgressRef: React.RefObject<boolean>;
   suppressThreadClickAfterDragRef: React.RefObject<boolean>;
+  /** When true the row sits inside a folder and is inset with a guide line. */
+  indented?: boolean;
 }
 
 const SidebarThreadRow = memo(function SidebarThreadRow(props: SidebarThreadRowProps) {
@@ -357,6 +359,7 @@ const SidebarThreadRow = memo(function SidebarThreadRow(props: SidebarThreadRowP
     thread,
     threadDragInProgressRef,
     suppressThreadClickAfterDragRef,
+    indented = false,
   } = props;
   const threadRef = scopeThreadRef(thread.environmentId, thread.id);
   const threadKey = scopedThreadKey(threadRef);
@@ -607,7 +610,9 @@ const SidebarThreadRow = memo(function SidebarThreadRow(props: SidebarThreadRowP
     <SidebarMenuSubItem
       ref={setDragNodeRef}
       style={{ transform: CSS.Translate.toString(dragTransform), transition: dragTransition }}
-      className={`w-full ${isDragging ? "z-20 opacity-80" : ""}`}
+      className={`w-full ${
+        indented ? "ml-3 border-l border-border/70 pl-2" : ""
+      } ${isDragging ? "z-20 opacity-80" : ""}`}
       data-thread-item
       onMouseLeave={handleMouseLeave}
       onBlurCapture={handleBlurCapture}
@@ -965,12 +970,13 @@ const SidebarProjectThreadList = memo(function SidebarProjectThreadList(
   const showLessButtonRender = useMemo(() => <button type="button" />, []);
 
   const renderThreadRow = useCallback(
-    (thread: SidebarThreadSummary) => {
+    (thread: SidebarThreadSummary, indented = false) => {
       const threadKey = scopedThreadKey(scopeThreadRef(thread.environmentId, thread.id));
       return (
         <SidebarThreadRow
           key={threadKey}
           thread={thread}
+          indented={indented}
           projectCwd={projectCwd}
           orderedProjectThreadKeys={orderedProjectThreadKeys}
           isActive={activeRouteThreadKey === threadKey}
@@ -1092,7 +1098,7 @@ const SidebarProjectThreadList = memo(function SidebarProjectThreadList(
                       )}
                       strategy={verticalListSortingStrategy}
                     >
-                      {section.threads.map((thread) => renderThreadRow(thread))}
+                      {section.threads.map((thread) => renderThreadRow(thread, true))}
                     </SortableContext>
                   ) : null}
                 </React.Fragment>

From 708f2a53bb761221f57ba54377b5ad2223d13621 Mon Sep 17 00:00:00 2001
From: TheIcarusWings <10465470+TheIcarusWings@users.noreply.github.com>
Date: Sun, 14 Jun 2026 11:24:14 +0100
Subject: [PATCH 3/4] fix(sidebar): address review findings for thread folders

- Keyboard jump labels now mirror the folder layout (expanded sections then
  preview-capped ungrouped), so labels match the rendered rows.
- Drag and the multi-select "Move to folder" menu now act on the same
  project-scoped selection (includes off-screen selected rows; ignores other
  projects' threads), keeping the two paths consistent.
- handleThreadDragEnd no-ops when dropped on itself (no spurious reorder).
- handleThreadDragCancel clears the click-suppression flags so the next click
  after a cancelled drag isn't swallowed.
- Collapsed project exposes only the pinned thread as its selectable order.
- Folder rename: Escape no longer commits via the input's onBlur.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 apps/web/src/components/Sidebar.tsx           | 114 ++++++++++++++----
 .../src/components/SidebarThreadGroupRow.tsx  |  17 ++-
 2 files changed, 105 insertions(+), 26 deletions(-)

diff --git a/apps/web/src/components/Sidebar.tsx b/apps/web/src/components/Sidebar.tsx
index d98d487389f..f93e06766df 100644
--- a/apps/web/src/components/Sidebar.tsx
+++ b/apps/web/src/components/Sidebar.tsx
@@ -1488,14 +1488,20 @@ const SidebarProjectItem = memo(function SidebarProjectItem(props: SidebarProjec
         : ungrouped.slice(0, sidebarThreadPreviewCount);
 
     // Flattened visual order of the currently-rendered rows, used for
-    // shift-range selection and keyboard jump indices. Collapsed folders and
-    // capped overflow rows are not rendered, so they are not selectable.
-    const orderedRenderedThreadKeys = [
-      ...layout.sections.flatMap((section) =>
-        section.expanded ? section.threads.map(threadKeyOf) : [],
-      ),
-      ...ungroupedRenderedThreads.map(threadKeyOf),
-    ];
+    // shift-range selection and keyboard jump indices. Must mirror exactly what
+    // SidebarProjectThreadList renders: when the project is collapsed only the
+    // pinned active thread shows; otherwise expanded folders then capped
+    // ungrouped rows (collapsed folders / capped overflow are not selectable).
+    const orderedRenderedThreadKeys = !projectExpanded
+      ? pinnedCollapsedThread
+        ? [threadKeyOf(pinnedCollapsedThread)]
+        : []
+      : [
+          ...layout.sections.flatMap((section) =>
+            section.expanded ? section.threads.map(threadKeyOf) : [],
+          ),
+          ...ungroupedRenderedThreads.map(threadKeyOf),
+        ];
 
     const renderedKeySet = new Set(orderedRenderedThreadKeys);
     const hiddenThreads = visibleProjectThreads.filter(
@@ -1970,15 +1976,28 @@ const SidebarProjectItem = memo(function SidebarProjectItem(props: SidebarProjec
       const threadKeys = [...useThreadSelectionStore.getState().selectedThreadKeys];
       if (threadKeys.length === 0) return;
       const count = threadKeys.length;
+      // Folder moves are project-scoped (folders belong to one project), so only
+      // offer/act on selected threads that live in THIS project. Mark-unread and
+      // delete still apply to the whole selection.
+      const projectThreadKeys = new Set(
+        visibleProjectThreads.map((thread) =>
+          scopedThreadKey(scopeThreadRef(thread.environmentId, thread.id)),
+        ),
+      );
+      const moveableKeys = threadKeys.filter((key) => projectThreadKeys.has(key));
 
       const clicked = await api.contextMenu.show(
         [
           { id: "mark-unread", label: `Mark unread (${count})` },
-          {
-            id: "move-submenu",
-            label: `Move ${count} to folder`,
-            children: buildFolderMenuChildren(),
-          },
+          ...(moveableKeys.length > 0
+            ? [
+                {
+                  id: "move-submenu",
+                  label: `Move ${moveableKeys.length} to folder`,
+                  children: buildFolderMenuChildren(),
+                },
+              ]
+            : []),
           { id: "delete", label: `Delete (${count})`, destructive: true },
         ],
         position,
@@ -1994,7 +2013,9 @@ const SidebarProjectItem = memo(function SidebarProjectItem(props: SidebarProjec
       }
 
       if (clicked && clicked.startsWith("move:")) {
-        applyFolderMove(clicked, threadKeys);
+        if (moveableKeys.length > 0) {
+          applyFolderMove(clicked, moveableKeys);
+        }
         clearSelection();
         return;
       }
@@ -2029,6 +2050,7 @@ const SidebarProjectItem = memo(function SidebarProjectItem(props: SidebarProjec
       deleteThread,
       markThreadUnread,
       removeFromSelection,
+      visibleProjectThreads,
     ],
   );
 
@@ -2431,9 +2453,16 @@ const SidebarProjectItem = memo(function SidebarProjectItem(props: SidebarProjec
       if (!selected.has(activeKey)) {
         return [activeKey];
       }
-      return orderedRenderedThreadKeys.filter((key) => selected.has(key));
+      // Move every selected thread in THIS project (including ones scrolled out
+      // of view in collapsed folders / overflow), ordered by the project's full
+      // thread order. Scoping to this project keeps it consistent with the
+      // "Move to folder" menu and avoids dangling memberships from other
+      // projects' threads pointing at this project's folder.
+      return visibleProjectThreads
+        .map((thread) => scopedThreadKey(scopeThreadRef(thread.environmentId, thread.id)))
+        .filter((key) => selected.has(key));
     },
-    [orderedRenderedThreadKeys],
+    [visibleProjectThreads],
   );
 
   const handleThreadDragStart = useCallback(
@@ -2458,6 +2487,10 @@ const SidebarProjectItem = memo(function SidebarProjectItem(props: SidebarProjec
 
   const handleThreadDragCancel = useCallback((_event: DragCancelEvent) => {
     threadDragInProgressRef.current = false;
+    // Clear the click-suppression flags set on drag start, otherwise the next
+    // click on the row/header after a cancelled drag is swallowed.
+    suppressThreadClickAfterDragRef.current = false;
+    suppressGroupClickAfterDragRef.current = false;
     setActiveDragLabel(null);
   }, []);
 
@@ -2469,6 +2502,8 @@ const SidebarProjectItem = memo(function SidebarProjectItem(props: SidebarProjec
       if (!over) return;
       const activeId = String(active.id);
       const overId = String(over.id);
+      // Dropped on itself: nothing to move or reorder.
+      if (activeId === overId) return;
       const headerPrefix = "group-header:";
 
       // Folder reorder.
@@ -3353,6 +3388,11 @@ export default function Sidebar() {
   const projects = useStore(useShallow(selectProjectsAcrossEnvironments));
   const sidebarThreads = useStore(useShallow(selectSidebarThreadsAcrossEnvironments));
   const projectExpandedById = useUiStateStore((store) => store.projectExpandedById);
+  const threadGroupsById = useUiStateStore((store) => store.threadGroupsById);
+  const threadGroupExpandedById = useUiStateStore((store) => store.threadGroupExpandedById);
+  const threadGroupOrderByProjectKey = useUiStateStore(
+    (store) => store.threadGroupOrderByProjectKey,
+  );
   const projectOrder = useUiStateStore((store) => store.projectOrder);
   const reorderProjects = useUiStateStore((store) => store.reorderProjects);
   const navigate = useNavigate();
@@ -3656,16 +3696,39 @@ export default function Sidebar() {
         if (!shouldShowThreadPanel) {
           return [];
         }
+        // Collapsed project: only the pinned active thread renders.
+        if (!projectExpanded) {
+          return pinnedCollapsedThread
+            ? [
+                scopedThreadKey(
+                  scopeThreadRef(pinnedCollapsedThread.environmentId, pinnedCollapsedThread.id),
+                ),
+              ]
+            : [];
+        }
+        // Expanded: mirror SidebarProjectItem's rendered order exactly — expanded
+        // folder sections first, then the preview-capped ungrouped list — so jump
+        // labels line up with what is actually on screen.
         const isThreadListExpanded = expandedThreadListsByProject.has(project.projectKey);
-        const hasOverflowingThreads = projectThreads.length > sidebarThreadPreviewCount;
-        const previewThreads =
+        const layout = buildGroupedThreadLayout({
+          visibleProjectThreads: projectThreads,
+          projectKey: project.projectKey,
+          groups: threadGroupsById,
+          groupOrder: threadGroupOrderByProjectKey[project.projectKey] ?? EMPTY_STRING_ARRAY,
+          groupExpandedById: threadGroupExpandedById,
+        });
+        const ungrouped = layout.ungroupedThreads;
+        const hasOverflowingThreads = ungrouped.length > sidebarThreadPreviewCount;
+        const ungroupedRendered =
           isThreadListExpanded || !hasOverflowingThreads
-            ? projectThreads
-            : projectThreads.slice(0, sidebarThreadPreviewCount);
-        const renderedThreads = pinnedCollapsedThread ? [pinnedCollapsedThread] : previewThreads;
-        return renderedThreads.map((thread) =>
-          scopedThreadKey(scopeThreadRef(thread.environmentId, thread.id)),
-        );
+            ? ungrouped
+            : ungrouped.slice(0, sidebarThreadPreviewCount);
+        return [
+          ...layout.sections.flatMap((section) =>
+            section.expanded ? section.threads.map(threadKeyOf) : [],
+          ),
+          ...ungroupedRendered.map(threadKeyOf),
+        ];
       }),
     [
       sidebarThreadSortOrder,
@@ -3675,6 +3738,9 @@ export default function Sidebar() {
       routeThreadKey,
       sortedProjects,
       threadsByProjectKey,
+      threadGroupsById,
+      threadGroupExpandedById,
+      threadGroupOrderByProjectKey,
     ],
   );
   const threadJumpCommandByKey = useMemo(() => {
diff --git a/apps/web/src/components/SidebarThreadGroupRow.tsx b/apps/web/src/components/SidebarThreadGroupRow.tsx
index 7f1831c9ac9..ba3e15ab20e 100644
--- a/apps/web/src/components/SidebarThreadGroupRow.tsx
+++ b/apps/web/src/components/SidebarThreadGroupRow.tsx
@@ -1,7 +1,7 @@
 import { useSortable } from "@dnd-kit/sortable";
 import { CSS } from "@dnd-kit/utilities";
 import { ChevronRightIcon, FolderIcon } from "lucide-react";
-import { memo, useCallback, useMemo } from "react";
+import { memo, useCallback, useMemo, useRef } from "react";
 
 import { SidebarMenuSubButton, SidebarMenuSubItem } from "./ui/sidebar";
 import type { ThreadGroup } from "../uiStateStore";
@@ -69,8 +69,13 @@ const SidebarThreadGroupRow = memo(function SidebarThreadGroupRow(
     [group.id, onContextMenu],
   );
 
+  // Guards the input's onBlur from re-committing after Enter/Escape already
+  // resolved the rename (otherwise Escape cancels then blur silently commits).
+  const renameResolvedRef = useRef(false);
+
   const handleRenameRef = useCallback((element: HTMLInputElement | null) => {
     if (element) {
+      renameResolvedRef.current = false;
       element.focus();
       element.select();
     }
@@ -81,15 +86,23 @@ const SidebarThreadGroupRow = memo(function SidebarThreadGroupRow(
       event.stopPropagation();
       if (event.key === "Enter") {
         event.preventDefault();
+        renameResolvedRef.current = true;
         commitRename(group.id);
       } else if (event.key === "Escape") {
         event.preventDefault();
+        renameResolvedRef.current = true;
         cancelRename();
       }
     },
     [cancelRename, commitRename, group.id],
   );
 
+  const handleRenameBlur = useCallback(() => {
+    if (!renameResolvedRef.current) {
+      commitRename(group.id);
+    }
+  }, [commitRename, group.id]);
+
   return (
     <SidebarMenuSubItem
       ref={setNodeRef}
@@ -124,7 +137,7 @@ const SidebarThreadGroupRow = memo(function SidebarThreadGroupRow(
             value={renamingTitle}
             onChange={(event) => setRenamingTitle(event.target.value)}
             onKeyDown={handleRenameKeyDown}
-            onBlur={() => commitRename(group.id)}
+            onBlur={handleRenameBlur}
             onClick={(event) => event.stopPropagation()}
           />
         ) : (

From b9549890a17caafcfd091824a25cd217ecaabd93 Mon Sep 17 00:00:00 2001
From: TheIcarusWings <10465470+TheIcarusWings@users.noreply.github.com>
Date: Sun, 14 Jun 2026 11:31:15 +0100
Subject: [PATCH 4/4] fix(sidebar): preserve in-folder order for multi-thread
 drag

resolveDraggedThreadKeys now orders the dragged selection by the folder-aware
layout (folder members in their in-folder order, ungrouped in sort order)
instead of raw sidebar sort order, so multi-dragging grouped threads keeps
their order. Still includes off-screen selected rows and stays project-scoped.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 apps/web/src/components/Sidebar.tsx | 26 ++++++++++++++++++--------
 1 file changed, 18 insertions(+), 8 deletions(-)

diff --git a/apps/web/src/components/Sidebar.tsx b/apps/web/src/components/Sidebar.tsx
index f93e06766df..0b93be24b32 100644
--- a/apps/web/src/components/Sidebar.tsx
+++ b/apps/web/src/components/Sidebar.tsx
@@ -1447,6 +1447,7 @@ const SidebarProjectItem = memo(function SidebarProjectItem(props: SidebarProjec
     sections,
     ungroupedRenderedThreads,
     orderedRenderedThreadKeys,
+    orderedAllThreadKeys,
     hasOverflowingThreads,
     hiddenThreadStatus,
     showEmptyThreadState,
@@ -1508,10 +1509,20 @@ const SidebarProjectItem = memo(function SidebarProjectItem(props: SidebarProjec
       (thread) => !renderedKeySet.has(threadKeyOf(thread)),
     );
 
+    // Full layout-ordered key list for THIS project (folder members in folder
+    // order, then ungrouped in sort order), including rows that are off-screen
+    // in collapsed folders or past the preview cap. Used to order multi-drag
+    // moves so a dragged selection keeps its in-folder order.
+    const orderedAllThreadKeys = [
+      ...layout.sections.flatMap((section) => section.threads.map(threadKeyOf)),
+      ...layout.ungroupedThreads.map(threadKeyOf),
+    ];
+
     return {
       sections: layout.sections,
       ungroupedRenderedThreads,
       orderedRenderedThreadKeys,
+      orderedAllThreadKeys,
       hasOverflowingThreads,
       hiddenThreadStatus: resolveProjectStatusIndicator(
         hiddenThreads.map((thread) => resolveProjectThreadStatus(thread)),
@@ -2454,15 +2465,14 @@ const SidebarProjectItem = memo(function SidebarProjectItem(props: SidebarProjec
         return [activeKey];
       }
       // Move every selected thread in THIS project (including ones scrolled out
-      // of view in collapsed folders / overflow), ordered by the project's full
-      // thread order. Scoping to this project keeps it consistent with the
-      // "Move to folder" menu and avoids dangling memberships from other
-      // projects' threads pointing at this project's folder.
-      return visibleProjectThreads
-        .map((thread) => scopedThreadKey(scopeThreadRef(thread.environmentId, thread.id)))
-        .filter((key) => selected.has(key));
+      // of view in collapsed folders / overflow), ordered by the folder-aware
+      // layout order (folder members keep their in-folder order; ungrouped follow
+      // sort order). Scoping to this project keeps it consistent with the "Move
+      // to folder" menu and avoids dangling memberships from other projects'
+      // threads pointing at this project's folder.
+      return orderedAllThreadKeys.filter((key) => selected.has(key));
     },
-    [visibleProjectThreads],
+    [orderedAllThreadKeys],
   );
 
   const handleThreadDragStart = useCallback(