feat: add project-grouped agent fetch with checkout-lite placement

2026-02-09 15:44:58 +07:00
parent 8403ece4ed
commit 1810ace233
13 changed files with 1063 additions and 117 deletions
@@ -0,0 +1,137 @@
+import { useEffect, useRef } from "react";
+import { Animated, View, type StyleProp, type ViewStyle } from "react-native";
+import { StyleSheet } from "react-native-unistyles";
+
+function SkeletonPulse({
+  pulse,
+  style,
+}: {
+  pulse: Animated.Value;
+  style: StyleProp<ViewStyle>;
+}) {
+  const opacity = pulse.interpolate({
+    inputRange: [0, 1],
+    outputRange: [0.45, 0.95],
+  });
+
+  return <Animated.View style={[style, { opacity }]} />;
+}
+
+export function SidebarAgentListSkeleton() {
+  const pulse = useRef(new Animated.Value(0)).current;
+
+  useEffect(() => {
+    const animation = Animated.loop(
+      Animated.sequence([
+        Animated.timing(pulse, {
+          toValue: 1,
+          duration: 850,
+          useNativeDriver: true,
+        }),
+        Animated.timing(pulse, {
+          toValue: 0,
+          duration: 850,
+          useNativeDriver: true,
+        }),
+      ])
+    );
+
+    animation.start();
+    return () => animation.stop();
+  }, [pulse]);
+
+  return (
+    <View style={styles.container}>
+      {Array.from({ length: 4 }).map((_, sectionIdx) => (
+        <View key={`skeleton-section-${sectionIdx}`} style={styles.section}>
+          <View style={styles.sectionHeader}>
+            <SkeletonPulse pulse={pulse} style={styles.projectIcon} />
+            <SkeletonPulse pulse={pulse} style={styles.sectionTitle} />
+          </View>
+
+          <View style={styles.rows}>
+            {Array.from({ length: 3 }).map((__, rowIdx) => (
+              <View key={`skeleton-row-${sectionIdx}-${rowIdx}`} style={styles.row}>
+                <SkeletonPulse pulse={pulse} style={styles.rowDot} />
+                <View style={styles.rowText}>
+                  <SkeletonPulse pulse={pulse} style={styles.rowTitle} />
+                </View>
+                <SkeletonPulse pulse={pulse} style={styles.rowBadge} />
+              </View>
+            ))}
+          </View>
+        </View>
+      ))}
+    </View>
+  );
+}
+
+const styles = StyleSheet.create((theme) => ({
+  container: {
+    flex: 1,
+    paddingHorizontal: theme.spacing[4],
+    paddingVertical: theme.spacing[3],
+    gap: theme.spacing[4],
+  },
+  section: {
+    gap: theme.spacing[2],
+  },
+  sectionHeader: {
+    flexDirection: "row",
+    alignItems: "center",
+    gap: theme.spacing[2],
+  },
+  projectIcon: {
+    width: 16,
+    height: 16,
+    borderRadius: theme.borderRadius.sm,
+    backgroundColor: theme.colors.surface2,
+    shadowColor: theme.colors.foreground,
+    shadowOpacity: 0.18,
+    shadowRadius: 8,
+    shadowOffset: { width: 0, height: 0 },
+  },
+  sectionTitle: {
+    width: "52%",
+    height: 12,
+    borderRadius: theme.borderRadius.sm,
+    backgroundColor: theme.colors.surface2,
+    shadowColor: theme.colors.foreground,
+    shadowOpacity: 0.12,
+    shadowRadius: 8,
+    shadowOffset: { width: 0, height: 0 },
+  },
+  rows: {
+    gap: theme.spacing[1],
+  },
+  row: {
+    flexDirection: "row",
+    alignItems: "center",
+    gap: theme.spacing[2],
+    paddingVertical: theme.spacing[2],
+    paddingHorizontal: theme.spacing[2],
+    borderRadius: theme.borderRadius.md,
+    backgroundColor: theme.colors.surface1,
+  },
+  rowDot: {
+    width: 8,
+    height: 8,
+    borderRadius: theme.borderRadius.full,
+    backgroundColor: theme.colors.surface3,
+  },
+  rowText: {
+    flex: 1,
+  },
+  rowTitle: {
+    width: "70%",
+    height: 10,
+    borderRadius: theme.borderRadius.sm,
+    backgroundColor: theme.colors.surface3,
+  },
+  rowBadge: {
+    width: 46,
+    height: 18,
+    borderRadius: theme.borderRadius.full,
+    backgroundColor: theme.colors.surface3,
+  },
+}));
@@ -19,7 +19,6 @@ import {
 import { router, usePathname } from "expo-router";
 import { StyleSheet, useUnistyles } from "react-native-unistyles";
 import { type GestureType } from "react-native-gesture-handler";
-import { useQueryClient } from "@tanstack/react-query";
 import { Archive, ChevronDown, ChevronRight, Plus } from "lucide-react-native";
 import {
  DraggableList,
@@ -28,11 +27,6 @@ import {
 import { parseRepoNameFromRemoteUrl, parseRepoShortNameFromRemoteUrl } from "@/utils/agent-grouping";
 import { type AggregatedAgent } from "@/hooks/use-aggregated-agents";
 import { useSessionStore } from "@/stores/session-store";
-import {
-  CHECKOUT_STATUS_STALE_TIME,
-  checkoutStatusQueryKey,
-  useCheckoutStatusCacheOnly,
-} from "@/hooks/use-checkout-status-query";
 import {
  buildAgentNavigationKey,
  startNavigationTiming,
@@ -41,7 +35,10 @@ import {
  useSectionOrderStore,
 } from "@/stores/section-order-store";
 import { useProjectIconQuery } from "@/hooks/use-project-icon-query";
-import { useSidebarAgentSections, type SidebarSectionData } from "@/hooks/use-sidebar-agent-sections";
+import {
+  type SidebarCheckoutLite,
+  type SidebarSectionData,
+} from "@/hooks/use-sidebar-agents-grouped";
 import { useSidebarCollapsedSectionsStore } from "@/stores/sidebar-collapsed-sections-store";
 import { useKeyboardNavStore } from "@/stores/keyboard-nav-store";
 import { getIsTauri } from "@/constants/layout";
@@ -49,8 +46,9 @@ import { AgentStatusDot } from "@/components/agent-status-dot";

 type SectionData = SidebarSectionData;

-interface GroupedAgentListProps {
-  agents: AggregatedAgent[];
+interface SidebarAgentListProps {
+  sections: SidebarSectionData[];
+  checkoutByAgentKey: Map<string, SidebarCheckoutLite>;
  isRefreshing?: boolean;
  onRefresh?: () => void;
  selectedAgentId?: string;
@@ -62,6 +60,7 @@ interface GroupedAgentListProps {

 interface SectionHeaderProps {
  section: SectionData;
+  checkout: SidebarCheckoutLite | null;
  isCollapsed: boolean;
  onToggle: () => void;
  onCreateAgent: (workingDir: string) => void;
@@ -71,6 +70,7 @@ interface SectionHeaderProps {

 function SectionHeader({
  section,
+  checkout,
  isCollapsed,
  onToggle,
  onCreateAgent,
@@ -80,13 +80,6 @@ function SectionHeader({
  const { theme } = useUnistyles();
  const [isHovered, setIsHovered] = useState(false);

-  // For project sections, try to get repo name from checkout status
-  const checkoutQuery = useCheckoutStatusCacheOnly({
-    serverId: section.firstAgentServerId ?? "",
-    cwd: section.workingDir ?? "",
-  });
-  const checkout = checkoutQuery.data ?? null;
-
  // Get project icon
  const iconQuery = useProjectIconQuery({
    serverId: section.firstAgentServerId ?? "",
@@ -185,8 +178,9 @@ function SectionHeader({
  );
 }

-interface GroupedAgentRowProps {
+interface SidebarAgentRowProps {
  agent: AggregatedAgent;
+  checkout: SidebarCheckoutLite | null;
  isSelected: boolean;
  shortcutNumber: number | null;
  onPress: () => void;
@@ -194,14 +188,15 @@ interface GroupedAgentRowProps {
  onArchive: (e: { stopPropagation: () => void }) => void;
 }

-function GroupedAgentRow({
+function SidebarAgentRow({
  agent,
+  checkout,
  isSelected,
  shortcutNumber,
  onPress,
  onLongPress,
  onArchive,
-}: GroupedAgentRowProps) {
+}: SidebarAgentRowProps) {
  const { theme } = useUnistyles();
  const [isHovered, setIsHovered] = useState(false);
  const [isArchiveHovered, setIsArchiveHovered] = useState(false);
@@ -233,17 +228,10 @@ function GroupedAgentRow({
      setIsArchiveConfirmVisible(false);
    }, 50);
  }, [clearHoverOutTimeout]);
-
-  const checkoutQuery = useCheckoutStatusCacheOnly({
-    serverId: agent.serverId,
-    cwd: agent.cwd,
-  });
-  const checkout = checkoutQuery.data ?? null;
  const activeBranchLabel = checkout?.isGit
    ? ((checkout.currentBranch && checkout.currentBranch !== "HEAD"
        ? checkout.currentBranch
        : null) ??
-      checkout.baseRef ??
      "git")
    : null;

@@ -355,18 +343,18 @@ function GroupedAgentRow({
  );
 }

-export function GroupedAgentList({
-  agents,
+export function SidebarAgentList({
+  sections,
+  checkoutByAgentKey,
  isRefreshing = false,
  onRefresh,
  selectedAgentId,
  onAgentSelect,
  listFooterComponent,
  parentGestureRef,
-}: GroupedAgentListProps) {
+}: SidebarAgentListProps) {
  const { theme } = useUnistyles();
  const pathname = usePathname();
-  const queryClient = useQueryClient();
  const insets = useSafeAreaInsets();
  const [actionAgent, setActionAgent] = useState<AggregatedAgent | null>(null);

@@ -448,43 +436,9 @@ export function GroupedAgentList({
    [onAgentSelect]
  );

-  // Prefetch checkout status for all agents in the sidebar.
-  // The sidebar shows a limited number of agents, so we fetch all of them upfront
-  // to ensure project grouping (by remote URL) is stable from the start.
-  useEffect(() => {
-    for (const agent of agents) {
-      const session = useSessionStore.getState().sessions[agent.serverId];
-      const client = session?.client ?? null;
-      const isConnected = session?.connection.isConnected ?? false;
-      if (!client || !isConnected) {
-        continue;
-      }
-
-      const queryKey = checkoutStatusQueryKey(agent.serverId, agent.cwd);
-      const queryState = queryClient.getQueryState(queryKey);
-      const isFetching = queryState?.fetchStatus === "fetching";
-      const isFresh =
-        typeof queryState?.dataUpdatedAt === "number" &&
-        Date.now() - queryState.dataUpdatedAt < CHECKOUT_STATUS_STALE_TIME;
-      if (isFetching || isFresh) {
-        continue;
-      }
-
-      void queryClient.prefetchQuery({
-        queryKey,
-        queryFn: async () => await client.getCheckoutStatus(agent.cwd),
-        staleTime: CHECKOUT_STATUS_STALE_TIME,
-      }).catch((error) => {
-        console.warn("[checkout_status] prefetch failed", error);
-      });
-    }
-  }, [agents, queryClient]);
-
  // Section order from store
  const setProjectOrder = useSectionOrderStore((state) => state.setProjectOrder);

-  const sections: SectionData[] = useSidebarAgentSections(agents);
-
  const handleDragEnd = useCallback(
    (newData: SectionData[]) => {
      const newOrder = newData.map((section) => section.projectKey);
@@ -510,11 +464,19 @@ export function GroupedAgentList({
  const renderSection = useCallback(
    ({ item: section, drag, isActive }: DraggableRenderItemInfo<SectionData>) => {
      const isCollapsed = collapsedProjectKeys.has(section.projectKey);
+      const firstAgent = section.agents[0];
+      const firstAgentKey = firstAgent
+        ? `${firstAgent.serverId}:${firstAgent.id}`
+        : null;
+      const firstAgentCheckout = firstAgentKey
+        ? (checkoutByAgentKey.get(firstAgentKey) ?? null)
+        : null;

      return (
        <View style={[styles.sectionContainer, isActive && styles.sectionDragging]}>
          <SectionHeader
            section={section}
+            checkout={firstAgentCheckout}
            isCollapsed={isCollapsed}
            onToggle={() => toggleProjectCollapsed(section.projectKey)}
            onCreateAgent={handleCreateAgentInProject}
@@ -523,9 +485,12 @@ export function GroupedAgentList({
          />
          {!isCollapsed &&
            section.agents.map((agent) => (
-              <GroupedAgentRow
+              <SidebarAgentRow
                key={`${agent.serverId}:${agent.id}`}
                agent={agent}
+                checkout={
+                  checkoutByAgentKey.get(`${agent.serverId}:${agent.id}`) ?? null
+                }
                isSelected={selectedAgentId === `${agent.serverId}:${agent.id}`}
                shortcutNumber={
                  showShortcutBadges
@@ -546,6 +511,7 @@ export function GroupedAgentList({
      handleAgentPress,
      handleArchiveAgent,
      handleCreateAgentInProject,
+      checkoutByAgentKey,
      selectedAgentId,
      showShortcutBadges,
      shortcutIndexByAgentKey,
@@ -12,17 +12,16 @@ import { StyleSheet, UnistylesRuntime, useUnistyles } from "react-native-unistyl
 import { Plus, Settings, Users } from "lucide-react-native";
 import { router } from "expo-router";
 import { usePanelStore } from "@/stores/panel-store";
-import { GroupedAgentList } from "./grouped-agent-list";
-import { useAggregatedAgents } from "@/hooks/use-aggregated-agents";
+import { SidebarAgentList } from "./sidebar-agent-list";
+import { SidebarAgentListSkeleton } from "./sidebar-agent-list-skeleton";
+import { useSidebarAgentsGrouped } from "@/hooks/use-sidebar-agents-grouped";
 import { useSidebarAnimation } from "@/contexts/sidebar-animation-context";
 import { useTauriDragHandlers, useTrafficLightPadding } from "@/utils/tauri-window";
-import { useSidebarAgentSections } from "@/hooks/use-sidebar-agent-sections";
 import { useSidebarCollapsedSectionsStore } from "@/stores/sidebar-collapsed-sections-store";
 import { useKeyboardNavStore } from "@/stores/keyboard-nav-store";
 import { deriveSidebarShortcutAgentKeys } from "@/utils/sidebar-shortcuts";

 const DESKTOP_SIDEBAR_WIDTH = 320;
-const SIDEBAR_AGENT_LIMIT = 50; // temporary for screenshots

 interface SlidingSidebarProps {
  selectedAgentId?: string;
@@ -40,7 +39,13 @@ export function SlidingSidebar({ selectedAgentId }: SlidingSidebarProps) {
  // Derive isOpen from the unified panel state
  const isOpen = isMobile ? mobileView === "agent-list" : desktopAgentListOpen;

-  const { agents, isRevalidating, refreshAll } = useAggregatedAgents();
+  const {
+    sections,
+    checkoutByAgentKey,
+    isInitialLoad,
+    isRevalidating,
+    refreshAll,
+  } = useSidebarAgentsGrouped({ isOpen });
  const {
    translateX,
    backdropOpacity,
@@ -68,21 +73,11 @@ export function SlidingSidebar({ selectedAgentId }: SlidingSidebarProps) {
    }
  }, [isRevalidating, isManualRefresh]);

-  const sortedAgents = useMemo(() => {
-    return [...agents].sort((a, b) => {
-      if (a.requiresAttention && !b.requiresAttention) return -1;
-      if (!a.requiresAttention && b.requiresAttention) return 1;
-      return 0;
-    });
-  }, [agents]);
-
-  // Pass all agents to grouping, limit is applied inside groupAgents per-project
-  const sidebarSections = useSidebarAgentSections(sortedAgents);
  const collapsedProjectKeys = useSidebarCollapsedSectionsStore((s) => s.collapsedProjectKeys);
  const setSidebarShortcutAgentKeys = useKeyboardNavStore((s) => s.setSidebarShortcutAgentKeys);
  const sidebarShortcutAgentKeys = useMemo(() => {
-    return deriveSidebarShortcutAgentKeys(sidebarSections, collapsedProjectKeys, 9);
-  }, [collapsedProjectKeys, sidebarSections]);
+    return deriveSidebarShortcutAgentKeys(sections, collapsedProjectKeys, 9);
+  }, [collapsedProjectKeys, sections]);

  useEffect(() => {
    setSidebarShortcutAgentKeys(sidebarShortcutAgentKeys);
@@ -226,14 +221,19 @@ export function SlidingSidebar({ selectedAgentId }: SlidingSidebarProps) {
              </View>

              {/* Middle: scrollable agent list */}
-              <GroupedAgentList
-                agents={sortedAgents}
-                isRefreshing={isManualRefresh && isRevalidating}
-                onRefresh={handleRefresh}
-                selectedAgentId={selectedAgentId}
-                onAgentSelect={handleAgentSelectMobile}
-                parentGestureRef={closeGestureRef}
-              />
+              {isInitialLoad ? (
+                <SidebarAgentListSkeleton />
+              ) : (
+                <SidebarAgentList
+                  sections={sections}
+                  checkoutByAgentKey={checkoutByAgentKey}
+                  isRefreshing={isManualRefresh && isRevalidating}
+                  onRefresh={handleRefresh}
+                  selectedAgentId={selectedAgentId}
+                  onAgentSelect={handleAgentSelectMobile}
+                  parentGestureRef={closeGestureRef}
+                />
+              )}

              {/* Footer */}
              <View style={styles.sidebarFooter}>
@@ -301,12 +301,17 @@ export function SlidingSidebar({ selectedAgentId }: SlidingSidebarProps) {
      </View>

      {/* Middle: scrollable agent list */}
-      <GroupedAgentList
-        agents={sortedAgents}
-        isRefreshing={isManualRefresh && isRevalidating}
-        onRefresh={handleRefresh}
-        selectedAgentId={selectedAgentId}
-      />
+      {isInitialLoad ? (
+        <SidebarAgentListSkeleton />
+      ) : (
+        <SidebarAgentList
+          sections={sections}
+          checkoutByAgentKey={checkoutByAgentKey}
+          isRefreshing={isManualRefresh && isRevalidating}
+          onRefresh={handleRefresh}
+          selectedAgentId={selectedAgentId}
+        />
+      )}

      {/* Footer */}
      <View style={styles.sidebarFooter}>
@@ -237,6 +237,7 @@ function normalizeAgentSnapshot(
    attentionTimestamp,
    archivedAt,
    labels: snapshot.labels,
+    projectPlacement: null,
  };
 }

@@ -557,7 +558,10 @@ export function SessionProvider({
        return;
      }

-      const agent = normalizeAgentSnapshot(update.agent, serverId);
+      const agent = {
+        ...normalizeAgentSnapshot(update.agent, serverId),
+        projectPlacement: update.project,
+      };

      console.log("[Session] Agent update:", agent.id, agent.status);

@@ -0,0 +1,307 @@
+import { useCallback, useEffect, useMemo } from "react";
+import { useQueries, useQueryClient } from "@tanstack/react-query";
+import { useShallow } from "zustand/shallow";
+import { useDaemonConnections } from "@/contexts/daemon-connections-context";
+import { useSessionStore, type Agent } from "@/stores/session-store";
+import type { AggregatedAgent } from "@/hooks/use-aggregated-agents";
+import { normalizeAgentSnapshot } from "@/utils/agent-snapshots";
+import {
+  deriveProjectKey,
+  deriveProjectName,
+} from "@/utils/agent-grouping";
+import {
+  useSectionOrderStore,
+  sortProjectsByStoredOrder,
+} from "@/stores/section-order-store";
+import type { FetchAgentsGroupedByProjectResponseMessage } from "@server/shared/messages";
+
+const SIDEBAR_GROUPS_STALE_TIME = 15_000;
+const SIDEBAR_GROUPS_REFETCH_INTERVAL = 10_000;
+const MAX_AGENTS_PER_PROJECT = 5;
+
+type SidebarGroupsPayload = FetchAgentsGroupedByProjectResponseMessage["payload"];
+export type SidebarCheckoutLite =
+  SidebarGroupsPayload["groups"][number]["agents"][number]["checkout"];
+type MutableSidebarGroup = {
+  projectKey: string;
+  projectName: string;
+  agents: AggregatedAgent[];
+};
+
+export interface SidebarSectionData {
+  key: string;
+  projectKey: string;
+  title: string;
+  agents: AggregatedAgent[];
+  firstAgentServerId?: string;
+  firstAgentId?: string;
+  workingDir?: string;
+}
+
+export interface SidebarAgentsGroupedResult {
+  sections: SidebarSectionData[];
+  checkoutByAgentKey: Map<string, SidebarCheckoutLite>;
+  isLoading: boolean;
+  isInitialLoad: boolean;
+  isRevalidating: boolean;
+  refreshAll: () => void;
+}
+
+function toAggregatedAgent(params: {
+  source: Agent | ReturnType<typeof normalizeAgentSnapshot>;
+  serverId: string;
+  serverLabel: string;
+}): AggregatedAgent {
+  const source = params.source;
+  return {
+    id: source.id,
+    serverId: params.serverId,
+    serverLabel: params.serverLabel,
+    title: source.title ?? null,
+    status: source.status,
+    lastActivityAt: source.lastActivityAt,
+    cwd: source.cwd,
+    provider: source.provider,
+    requiresAttention: source.requiresAttention,
+    attentionReason: source.attentionReason,
+    attentionTimestamp: source.attentionTimestamp ?? null,
+    archivedAt: source.archivedAt ?? null,
+    labels: source.labels,
+  };
+}
+
+export function useSidebarAgentsGrouped(options?: {
+  isOpen?: boolean;
+}): SidebarAgentsGroupedResult {
+  const { connectionStates } = useDaemonConnections();
+  const queryClient = useQueryClient();
+  const isOpen = options?.isOpen ?? true;
+
+  const sessionClients = useSessionStore(
+    useShallow((state) => {
+      const result: Record<
+        string,
+        NonNullable<typeof state.sessions[string]["client"]> | null
+      > = {};
+      for (const [serverId, session] of Object.entries(state.sessions)) {
+        result[serverId] = session.client ?? null;
+      }
+      return result;
+    })
+  );
+
+  const sessionAgents = useSessionStore(
+    useShallow((state) => {
+      const result: Record<string, Map<string, Agent> | undefined> = {};
+      for (const [serverId, session] of Object.entries(state.sessions)) {
+        result[serverId] = session.agents;
+      }
+      return result;
+    })
+  );
+
+  const sessionConnections = useSessionStore(
+    useShallow((state) => {
+      const result: Record<string, boolean> = {};
+      for (const [serverId, session] of Object.entries(state.sessions)) {
+        result[serverId] = session.connection.isConnected;
+      }
+      return result;
+    })
+  );
+
+  const serverEntries = useMemo(
+    () =>
+      Object.keys(sessionClients).map((serverId) => ({
+        serverId,
+        client: sessionClients[serverId] ?? null,
+        isConnected: sessionConnections[serverId] ?? false,
+      })),
+    [sessionClients, sessionConnections]
+  );
+
+  const groupedQueries = useQueries({
+    queries: serverEntries.map(({ serverId, client, isConnected }) => ({
+      queryKey: ["sidebarAgentsGrouped", serverId] as const,
+      queryFn: async () => {
+        if (!client) {
+          throw new Error("Daemon client not available");
+        }
+        return await client.fetchAgentsGroupedByProject({
+          filter: { labels: { ui: "true" } },
+        });
+      },
+      enabled: Boolean(client) && isConnected,
+      staleTime: SIDEBAR_GROUPS_STALE_TIME,
+      refetchInterval: isOpen ? SIDEBAR_GROUPS_REFETCH_INTERVAL : false,
+      refetchIntervalInBackground: isOpen,
+      refetchOnMount: "always" as const,
+    })),
+  });
+
+  const projectOrder = useSectionOrderStore((state) => state.projectOrder);
+  const setProjectOrder = useSectionOrderStore((state) => state.setProjectOrder);
+
+  const { sections, checkoutByAgentKey, hasAnyData } = useMemo(() => {
+    const groupsByKey = new Map<string, MutableSidebarGroup>();
+    const checkoutLookup = new Map<string, SidebarCheckoutLite>();
+    const seenAgentKeys = new Set<string>();
+    const groupedFetchReadyByServer = new Map<string, boolean>();
+
+    for (let idx = 0; idx < serverEntries.length; idx++) {
+      const { serverId } = serverEntries[idx] ?? {};
+      if (!serverId) {
+        continue;
+      }
+      groupedFetchReadyByServer.set(serverId, groupedQueries[idx]?.isFetched ?? false);
+      const payload = groupedQueries[idx]?.data as SidebarGroupsPayload | undefined;
+      if (!payload) {
+        continue;
+      }
+      const serverLabel = connectionStates.get(serverId)?.daemon.label ?? serverId;
+      const liveAgents = sessionAgents[serverId];
+
+      for (const group of payload.groups) {
+        const existing: MutableSidebarGroup =
+          groupsByKey.get(group.projectKey) ??
+          {
+            projectKey: group.projectKey,
+            projectName: group.projectName,
+            agents: [],
+          };
+
+        for (const entry of group.agents) {
+          const normalized = normalizeAgentSnapshot(entry.agent, serverId);
+          const live = liveAgents?.get(entry.agent.id);
+          const nextAgent = toAggregatedAgent({
+            source: live ?? normalized,
+            serverId,
+            serverLabel,
+          });
+          if (nextAgent.archivedAt) {
+            continue;
+          }
+
+          const agentKey = `${serverId}:${entry.agent.id}`;
+          seenAgentKeys.add(agentKey);
+          checkoutLookup.set(agentKey, live?.projectPlacement?.checkout ?? entry.checkout);
+          existing.agents.push(nextAgent);
+        }
+
+        groupsByKey.set(group.projectKey, existing);
+      }
+    }
+
+    for (const { serverId } of serverEntries) {
+      if (!groupedFetchReadyByServer.get(serverId)) {
+        continue;
+      }
+      const serverLabel = connectionStates.get(serverId)?.daemon.label ?? serverId;
+      const liveAgents = sessionAgents[serverId];
+      if (!liveAgents) {
+        continue;
+      }
+
+      for (const live of liveAgents.values()) {
+        if (live.archivedAt || live.labels.ui !== "true") {
+          continue;
+        }
+        const agentKey = `${serverId}:${live.id}`;
+        if (seenAgentKeys.has(agentKey)) {
+          continue;
+        }
+
+        const livePlacement = live.projectPlacement;
+        const projectKey = livePlacement?.projectKey ?? deriveProjectKey(live.cwd);
+        const existing: MutableSidebarGroup =
+          groupsByKey.get(projectKey) ??
+          {
+            projectKey,
+            projectName: livePlacement?.projectName ?? deriveProjectName(projectKey),
+            agents: [],
+          };
+        existing.agents.push(
+          toAggregatedAgent({
+            source: live,
+            serverId,
+            serverLabel,
+          })
+        );
+        if (livePlacement) {
+          checkoutLookup.set(agentKey, livePlacement.checkout);
+        }
+        groupsByKey.set(projectKey, existing);
+      }
+    }
+
+    const sortedGroups = Array.from(groupsByKey.values())
+      .map((group) => {
+        const agents = [...group.agents].sort(
+          (left, right) =>
+            right.lastActivityAt.getTime() - left.lastActivityAt.getTime()
+        );
+        return {
+          ...group,
+          agents: agents.slice(0, MAX_AGENTS_PER_PROJECT),
+        };
+      })
+      .filter((group) => group.agents.length > 0)
+      .sort((left, right) => {
+        const leftRecent = left.agents[0]?.lastActivityAt.getTime() ?? 0;
+        const rightRecent = right.agents[0]?.lastActivityAt.getTime() ?? 0;
+        return rightRecent - leftRecent;
+      });
+
+    const orderedGroups = sortProjectsByStoredOrder(sortedGroups, projectOrder);
+    const nextSections = orderedGroups.map((group) => {
+      const firstAgent = group.agents[0];
+      return {
+        key: `project:${group.projectKey}`,
+        projectKey: group.projectKey,
+        title: group.projectName,
+        agents: group.agents,
+        firstAgentServerId: firstAgent?.serverId,
+        firstAgentId: firstAgent?.id,
+        workingDir: firstAgent?.cwd,
+      };
+    });
+
+    return {
+      sections: nextSections,
+      checkoutByAgentKey: checkoutLookup,
+      hasAnyData: nextSections.length > 0,
+    };
+  }, [serverEntries, groupedQueries, connectionStates, sessionAgents, projectOrder]);
+
+  useEffect(() => {
+    const currentKeys = sections.map((section) => section.projectKey);
+    const storedKeys = new Set(projectOrder);
+    const newKeys = currentKeys.filter((key) => !storedKeys.has(key));
+    if (newKeys.length > 0) {
+      setProjectOrder([...projectOrder, ...newKeys]);
+    }
+  }, [sections, projectOrder, setProjectOrder]);
+
+  const refreshAll = useCallback(() => {
+    for (const { serverId } of serverEntries) {
+      void queryClient.invalidateQueries({
+        queryKey: ["sidebarAgentsGrouped", serverId],
+      });
+    }
+  }, [queryClient, serverEntries]);
+
+  const isFetching = groupedQueries.some(
+    (query) => query.isPending || query.isFetching
+  );
+  const isInitialLoad = isFetching && !hasAnyData;
+  const isRevalidating = isFetching && hasAnyData;
+
+  return {
+    sections,
+    checkoutByAgentKey,
+    isLoading: isFetching,
+    isInitialLoad,
+    isRevalidating,
+    refreshAll,
+  };
+}
@@ -17,7 +17,11 @@ import type {
  AgentUsage,
  AgentPersistenceHandle,
 } from "@server/server/agent/agent-sdk-types";
-import type { FileDownloadTokenResponse, GitSetupOptions } from "@server/shared/messages";
+import type {
+  FileDownloadTokenResponse,
+  GitSetupOptions,
+  ProjectPlacementPayload,
+} from "@server/shared/messages";
 import { isPerfLoggingEnabled, measurePayload, perfLog } from "@/utils/perf";

 // Re-export types that were in session-context
@@ -95,6 +99,7 @@ export interface Agent {
  attentionTimestamp?: Date | null;
  archivedAt?: Date | null;
  labels: Record<string, string>;
+  projectPlacement?: ProjectPlacementPayload | null;
 }

 export type ExplorerEntryKind = "file" | "directory";