Skip to content

A desktop coding agent with free access to frontier models.

TypeScript
69.2 KB
Raw Blame
// The session route's data + navigation core: workspace/session loading
// (refreshRouteState + background session fetch), endpoint and opencode
// client resolution, URL-derived selection, redirects (fallback workspace,
// welcome), desktop local-server reconnect, remote
// connection checks, and the route inspector slice. Extracted verbatim from
// session-route.tsx as the final step of its decomposition; the route keeps
// composition, handlers, and JSX.
import { useCallback, useEffect, useMemo, useRef, useState } from "react";
import { useLocation, useNavigate, useParams } from "react-router";
import type { Session } from "@opencode-ai/sdk/v2/client";

import {
  publishInspectorOpencodeClient,
  publishInspectorSlice,
  recordInspectorEvent,
} from "@/app/lib/app-inspector";
import {
  resolveWorkspaceListSelectedId,
  workspaceBootstrap,
  workspaceSetRuntimeActive,
  workspaceSetSelected,
  type OmniRushServerInfo,
  type WorkspaceList,
} from "@/app/lib/desktop";
import { unwrap } from "@/app/lib/opencode";
import { createClientV2 } from "@/app/lib/opencode-v2-adapter";
import { getNativeSession, isMissingSessionError } from "@/app/lib/opencode-session-native";
import { createOmniRushServerClient, OmniRushServerError, type OmniRushServerClient } from "@/app/lib/omnirush-server";
import { isDesktopRuntime } from "@/app/lib/runtime-env";
import { toast } from "@/components/ui/sonner";
import { forgetMissingChatMemory } from "./missing-chat";
import type { ResolvedWorkspaceEndpoint } from "@/app/lib/workspace-endpoint";
import type { WorkspaceConnectionState } from "@/app/types";
import { normalizeDirectoryPath } from "@/app/utils";
import { t } from "@/i18n";
import {
  createWorkspaceServerClientResolver,
  useWorkspaceServerClient,
} from "@/react-app/infra/workspace-server-client";
import {
  diagnoseRemoteWorkspaceTaskLoadFailure,
  getRemoteWorkspaceConnectionKey,
  testRemoteWorkspaceConnection,
} from "@/react-app/domains/workspace/remote-workspace-diagnostics";
import { useLocal } from "@/react-app/kernel/local-provider";
import { useDenAuth } from "@/react-app/domains/cloud/den-auth-provider";
import { useBootState } from "./boot-state";
import {
  ensureDesktopLocalOmniRushConnection,
  shouldAttemptDesktopLocalReconnect,
} from "./desktop-local-omnirush";
import { resolveOmniRushConnection } from "./omnirush-connection";
import {
  commitRouteWorkspaceSelection,
  createRouteRefreshLifecycle,
  createRouteWorkspaceLoadCoalescer,
  mapRouteWorkspaceLoads,
  planRouteConnectionGap,
  planRouteWorkspaceLoads,
  planSessionListReloadAfterReconnect,
  routeWorkspaceSelectionCommitter,
} from "./route-refresh-control";
import {
  classifyRouteSessionReadError,
  describeRouteError,
  listRouteSessions,
  loadRouteSessionWithRetry,
  mapDesktopWorkspace,
  refreshRouteWorkspaceListState,
  sessionListRecoveryDelayMs,
  sessionsAfterListFailure,
  shouldRecheckEmptySessionList,
  stabilizeRouteWorkspaceOrder,
  type RouteSession,
  type RouteWorkspace,
  v2RouteSessionList,
} from "./route-workspaces";
import {
  readActiveWorkspaceId,
  readCachedWorkspaceSessions,
  readWorkspaceOrderIds,
  removeCachedWorkspaceSession,
  writeActiveWorkspaceId,
  writeCachedWorkspaceSessions,
  writeWorkspaceOrderIds,
} from "./session-memory";
import {
  legacySessionRoute,
  mergeWorkspaceRouteSession,
  preserveWorkspaceRouteSession,
  removeSessionFromWorkspaceLists,
  removeWorkspaceRouteSession,
  withoutDeletedSessions,
  sessionIdForLegacyWorkspaceInference,
  automationsRoute,
  dashboardRoute,
  workspaceTasksRoute,
  workspaceExtensionsRoute,
  workspaceSessionRoute,
} from "./workspace-routes";

export type UseWorkspaceRouteStateInput = {
  developerMode: boolean;
  workspaceRoute?: "session" | "automations" | "dashboard" | "apps" | "tasks" | "work";
  /** Invoked when the omnirush-server settings-changed event fires (the route bumps its settings version). */
  onServerSettingsChanged: () => void;
  /** Receives the local omnirush-server host info discovered during refresh. */
  onHostInfo: (info: OmniRushServerInfo | null) => void;
};

type ModernRouteSessionResolution =
  | { key: string; status: "loading" }
  | { key: string; status: "not-found" | "error"; message: string };

/** Hard ceiling for each blocking await of a route refresh. A hung desktop
 * bridge or unresponsive server otherwise leaves `loading` true forever,
 * which the session pane renders as an indefinite loading state. */
const ROUTE_REFRESH_STEP_TIMEOUT_MS = 15_000;
const ROUTE_WORKSPACE_ACTIVATION_SETTLE_MS = 750;

function withRouteRefreshTimeout<T>(promise: Promise<T>, label: string): Promise<T> {
  return new Promise<T>((resolve, reject) => {
    const timer = window.setTimeout(
      () => reject(new Error(`${label} did not respond within ${ROUTE_REFRESH_STEP_TIMEOUT_MS / 1000}s`)),
      ROUTE_REFRESH_STEP_TIMEOUT_MS,
    );
    promise.then(
      (value) => {
        window.clearTimeout(timer);
        resolve(value);
      },
      (error: unknown) => {
        window.clearTimeout(timer);
        reject(error);
      },
    );
  });
}

export function useWorkspaceRouteState(input: UseWorkspaceRouteStateInput) {
  const { developerMode, onServerSettingsChanged, onHostInfo, workspaceRoute = "session" } = input;
  const navigate = useNavigate();
  const location = useLocation();
  const local = useLocal();
  const denAuth = useDenAuth();
  const params = useParams<{ workspaceId?: string; sessionId?: string }>();
  const routeWorkspaceId = params.workspaceId?.trim() || "";
  const selectedSessionId = params.sessionId?.trim() || null;
  const extensionsRouteActive = /^\/(?:workspace\/[^/]+\/)?extensions(?:\/|$)/.test(location.pathname);
  const extensionsRoutePath = extensionsRouteActive
    ? location.pathname
      .replace(/^\/workspace\/[^/]+\/extensions\/?/, "")
      .replace(/^\/extensions\/?/, "")
      .replace(/^\/+|\/+$/g, "")
    : "";
  const workspaceInferenceSessionId = sessionIdForLegacyWorkspaceInference(routeWorkspaceId, selectedSessionId);
  const legacyWorkspaceInferenceKey = routeWorkspaceId ? "" : workspaceInferenceSessionId;
  const routeWorkspaceIdRef = useRef(routeWorkspaceId);
  routeWorkspaceIdRef.current = routeWorkspaceId;
  const workspaceInferenceSessionIdRef = useRef(workspaceInferenceSessionId);
  workspaceInferenceSessionIdRef.current = workspaceInferenceSessionId;
  const navigateToWorkspaceSession = useCallback((workspaceId: string, sessionId?: string | null, options?: { replace?: boolean }) => {
    const id = workspaceId.trim();
    if (!id) {
      navigate(legacySessionRoute(sessionId), options);
      return;
    }
    navigate(workspaceSessionRoute(id, sessionId), options);
  }, [navigate]);
  const normalizeWorkspaceRoute = useCallback((workspaceId: string, sessionId?: string | null, options?: { replace?: boolean }) => {
    if (extensionsRouteActive) {
      navigate(workspaceExtensionsRoute(workspaceId, extensionsRoutePath), options);
      return;
    }
    if (workspaceRoute === "automations") {
      if (/^\/automations(?:\/|$)/.test(location.pathname)) return;
      navigate(automationsRoute(), options);
      return;
    }
    if (workspaceRoute === "apps") {
      if (/^(?:\/apps|\/dashboard\/apps)(?:\/|$)/.test(location.pathname)) return;
      navigate("/apps", options);
      return;
    }
    if (workspaceRoute === "dashboard") {
      if (/^\/dashboard(?:\/|$)/.test(location.pathname)) return;
      navigate(dashboardRoute(), options);
      return;
    }
    // Work mode's home and Connectors page (domains/work) belong to no project route.
    if (workspaceRoute === "work") {
      if (/^\/work(?:\/|$)/.test(location.pathname)) return;
      navigate("/work", options);
      return;
    }
    if (workspaceRoute === "tasks") {
      navigate(workspaceTasksRoute(workspaceId), options);
      return;
    }
    navigateToWorkspaceSession(workspaceId, sessionId, options);
  }, [extensionsRouteActive, extensionsRoutePath, location.pathname, navigate, navigateToWorkspaceSession, workspaceRoute]);

  const {
    markRouteReady: markBootRouteReady,
    phase: bootPhase,
    routeReady: bootRouteReady,
  } = useBootState();
  const [loading, setLoading] = useState(true);
  const [client, setClient] = useState<OmniRushServerClient | null>(null);
  const [baseUrl, setBaseUrl] = useState("");
  const [token, setToken] = useState("");
  // The app ships only the 2.x engine: chats route there until a server says otherwise.
  const [engineV2ChatRouting, setEngineV2ChatRouting] = useState(true);
  const [engineRoutingReady, setEngineRoutingReady] = useState(false);
  const engineV2ChatRoutingRef = useRef(engineV2ChatRouting);
  engineV2ChatRoutingRef.current = engineV2ChatRouting;
  const previousEngineV2ChatRoutingRef = useRef<boolean | null>(null);
  const [workspaces, setWorkspaces] = useState<RouteWorkspace[]>([]);
  const [workspaceOrderIds, setWorkspaceOrderIds] = useState<string[]>(() => readWorkspaceOrderIds());
  const [sessionsByWorkspaceId, setSessionsByWorkspaceId] = useState<Record<string, RouteSession[]>>({});
  const [errorsByWorkspaceId, setErrorsByWorkspaceId] = useState<Record<string, string | null>>({});
  // Session-list load failures, kept apart from errorsByWorkspaceId: a list
  // that failed to load must not disable the workspace's composer or client.
  const [sessionListErrorsByWorkspaceId, setSessionListErrorsByWorkspaceId] = useState<Record<string, string | null>>({});
  const [workspaceConnectionOverrides, setWorkspaceConnectionOverrides] = useState<Record<string, WorkspaceConnectionState>>({});
  const [routeError, setRouteError] = useState<string | null>(null);
  // True while the desktop local server has not (re)published a usable base
  // URL/token — a restart or boot gap. The route retains its last usable
  // connection state during this window instead of clearing it.
  const [connectionPending, setConnectionPending] = useState(false);
  const [modernRouteSessionResolution, setModernRouteSessionResolution] = useState<ModernRouteSessionResolution | null>(null);
  const [routeRefreshVersion, setRouteRefreshVersion] = useState(0);
  const [legacySelectedWorkspaceId, setLegacySelectedWorkspaceId] = useState<string>(() => readActiveWorkspaceId() ?? "");
  const selectedWorkspaceId = routeWorkspaceId || legacySelectedWorkspaceId;
  const selectedWorkspaceIdRef = useRef(selectedWorkspaceId);
  selectedWorkspaceIdRef.current = selectedWorkspaceId;
  const selectedSessionIdRef = useRef(selectedSessionId);
  selectedSessionIdRef.current = selectedSessionId;
  const selectedWorkspace = useMemo(
    () => workspaces.find((workspace) => workspace.id === selectedWorkspaceId) ?? (selectedWorkspaceId ? null : workspaces[0] ?? null),
    [selectedWorkspaceId, workspaces],
  );
  // Workspace-scoped API calls (sessions, events, activate, opencode/*) must
  // hit the worker that owns the workspace, not the user's local server. The
  // single source of truth for that routing is `resolveWorkspaceEndpoint`.
  //
  // We refresh the memoized endpoint resolver behind a ref so the
  // `endpointForWorkspace` callback stays permanently stable. Otherwise it
  // would change on every `setBaseUrl`/`setToken`, which used to cascade up
  // through `loadWorkspaceSessionsInBackground` and `refreshRouteState` and
  // produce a tight render-refresh-setWorkspaces loop.
  const currentWorkspaceServerClientResolver = useMemo(
    () => createWorkspaceServerClientResolver({ baseUrl, token }),
    [baseUrl, token],
  );
  const workspaceServerClientResolverRef = useRef(currentWorkspaceServerClientResolver);
  workspaceServerClientResolverRef.current = currentWorkspaceServerClientResolver;
  const updateLocalServer = useCallback((next: { baseUrl: string; token: string }) => {
    const resolver = createWorkspaceServerClientResolver(next);
    workspaceServerClientResolverRef.current = resolver;
    return resolver;
  }, []);
  const endpointForWorkspace = useCallback(
    (workspace: RouteWorkspace | null | undefined): ResolvedWorkspaceEndpoint | null =>
      workspaceServerClientResolverRef.current(workspace),
    [],
  );
  const refreshLifecycleRef = useRef(createRouteRefreshLifecycle());
  const workspacesRef = useRef<RouteWorkspace[]>([]);
  const workspaceOrderIdsRef = useRef(workspaceOrderIds);
  const remoteWorkspaceCheckRunRef = useRef<Record<string, string>>({});
  const remoteWorkspaceCheckRunCounterRef = useRef(0);
  const sessionsByWorkspaceIdRef = useRef<Record<string, RouteSession[]>>({});
  const pendingCreatedSessionIdsRef = useRef<Record<string, Record<string, number>>>({});
  // Sessions deleted in this window. A list load that started before the
  // delete (a coalesced reload hands its caller that same load) still
  // carries them; they never come back into the sidebar from it.
  const deletedSessionIdsRef = useRef(new Set<string>());
  const hydratedRouteSessionIdsRef = useRef<Record<string, string>>({});
  const startupRetryTimerRef = useRef<number | null>(null);
  const [retryingWorkspaceIds, setRetryingWorkspaceIds] = useState<string[]>([]);
  const reconnectAttemptedWorkspaceIdRef = useRef("");
  const backgroundSessionLoadCoalescerRef = useRef(createRouteWorkspaceLoadCoalescer());
  const loadedWorkspaceIdsRef = useRef(new Set<string>());
  // Per-workspace automatic reload after a session list failed to load.
  const sessionListRecoveryRef = useRef<Record<string, { timer: number | null; round: number }>>({});
  // Workspaces whose sidebar list came from a successful load in this window.
  const listedWorkspaceIdsRef = useRef(new Set<string>());
  // Consecutive empty lists per workspace that were not yet trusted over the
  // sessions the sidebar already knew for it.
  const emptyListRechecksRef = useRef<Record<string, number>>({});
  // The built-in server connection the session lists were last loaded
  // against, and whether a connection gap (server restart) happened since.
  const lastConnectionKeyRef = useRef("");
  const connectionGapSeenRef = useRef(false);
  const serverActiveWorkspaceIdRef = useRef("");
  const workspaceSelectionCommitTimerRef = useRef<number | null>(null);
  const commitStableWorkspaceOrder = useCallback((nextWorkspaces: RouteWorkspace[]) => {
    const currentOrderIds = workspaceOrderIdsRef.current;
    const stable = stabilizeRouteWorkspaceOrder(nextWorkspaces, currentOrderIds);
    const orderChanged = stable.orderIds.length !== currentOrderIds.length
      || stable.orderIds.some((id, index) => id !== currentOrderIds[index]);

    if (orderChanged) {
      workspaceOrderIdsRef.current = stable.orderIds;
      setWorkspaceOrderIds(stable.orderIds);
      writeWorkspaceOrderIds(stable.orderIds);
    }

    return stable.workspaces;
  }, []);
  const rememberPendingCreatedSession = useCallback((workspaceId: string, sessionId: string) => {
    const id = sessionId.trim();
    if (!workspaceId || !id) return;
    pendingCreatedSessionIdsRef.current[workspaceId] = {
      ...(pendingCreatedSessionIdsRef.current[workspaceId] ?? {}),
      [id]: Date.now(),
    };
  }, []);
  const mergeFetchedSessionsWithPending = useCallback((workspaceId: string, listed: RouteSession[], current: RouteSession[]) => {
    const fetched = withoutDeletedSessions(listed, deletedSessionIdsRef.current);
    const pending = pendingCreatedSessionIdsRef.current[workspaceId];
    let merged = fetched;
    if (pending) {
      const now = Date.now();
      const fetchedIds = new Set(fetched.flatMap((session) => session?.id ? [String(session.id)] : []));
      const pendingIds = Object.keys(pending);

      for (const id of pendingIds) {
        if (fetchedIds.has(id)) {
          delete pending[id];
        }
      }

      const preserved = current.filter((session) => {
        const id = String(session?.id ?? "");
        if (!id || fetchedIds.has(id)) return false;
        const createdAt = pending[id];
        if (typeof createdAt !== "number") return false;
        if (now - createdAt > 30_000) {
          delete pending[id];
          return false;
        }
        return true;
      });

      if (Object.keys(pending).length === 0) {
        delete pendingCreatedSessionIdsRef.current[workspaceId];
      }

      if (preserved.length > 0) merged = [...preserved, ...fetched];
    }

    const hydratedSessionId = hydratedRouteSessionIdsRef.current[workspaceId];
    if (hydratedSessionId && fetched.some((session) => session.id === hydratedSessionId)) {
      delete hydratedRouteSessionIdsRef.current[workspaceId];
      return merged;
    }
    return preserveWorkspaceRouteSession(
      merged,
      current,
      hydratedSessionId,
    );
  }, []);
  const clearSessionListRecovery = useCallback((workspaceId: string) => {
    const entry = sessionListRecoveryRef.current[workspaceId];
    if (!entry) return;
    if (entry.timer !== null) window.clearTimeout(entry.timer);
    delete sessionListRecoveryRef.current[workspaceId];
  }, []);
  // A list that failed to load keeps the sessions the sidebar already shows;
  // with none, it falls back to the last list saved for this workspace.
  const keepKnownSessionsAfterListFailure = useCallback((workspaceId: string) => {
    const current = sessionsByWorkspaceIdRef.current;
    const currentItems = current[workspaceId] ?? [];
    const currentIsListed = listedWorkspaceIdsRef.current.has(workspaceId);
    if (currentIsListed && currentItems.length > 0) return;
    const sessions = sessionsAfterListFailure({
      current: currentItems,
      cached: readCachedWorkspaceSessions(workspaceId) as RouteSession[] | null,
      currentIsListed,
    });
    if (sessions.length === currentItems.length) return;
    const next = { ...current, [workspaceId]: sessions };
    sessionsByWorkspaceIdRef.current = next;
    setSessionsByWorkspaceId(next);
  }, []);
  const loadWorkspaceSessionsInBackground = useCallback(
    async (workspaces: RouteWorkspace[]) => {
      const MAX_ATTEMPTS = 6;
      const backoffMs = (attempt: number) => Math.min(500 * Math.pow(2, attempt), 4_000);

      const scheduleRecovery = (workspaceId: string) => {
        const entry = sessionListRecoveryRef.current[workspaceId] ?? { timer: null, round: 0 };
        sessionListRecoveryRef.current[workspaceId] = entry;
        if (entry.timer !== null) return;
        const delayMs = sessionListRecoveryDelayMs(entry.round);
        entry.round += 1;
        entry.timer = window.setTimeout(() => {
          entry.timer = null;
          const workspace = workspacesRef.current.find((item) => item.id === workspaceId);
          if (!workspace) {
            delete sessionListRecoveryRef.current[workspaceId];
            return;
          }
          void backgroundSessionLoadCoalescerRef.current.run(workspaceId, () => fetchWithRetries(workspace, 0));
        }, delayMs);
      };

      const fetchWithRetries = async (workspace: RouteWorkspace, attempt: number): Promise<void> => {
        const isRemoteOmniRushWorkspace = workspace.workspaceType === "remote" && workspace.remoteType !== "opencode";
        const endpoint = endpointForWorkspace(workspace);
        if (!endpoint) {
          if (workspace.workspaceType === "remote") {
            const message = "Remote worker URL is missing. Edit connection and add a server URL.";
            setErrorsByWorkspaceId((current) => ({ ...current, [workspace.id]: message }));
            setWorkspaceConnectionOverrides((current) => ({
              ...current,
              [workspace.id]: {
                status: "error",
                message,
                checkedAt: Date.now(),
              },
            }));
            setRetryingWorkspaceIds((current) =>
              current.includes(workspace.id) ? current.filter((id) => id !== workspace.id) : current,
            );
          } else if (sessionListRecoveryRef.current[workspace.id]) {
            // The built-in server is between restarts; keep the reload alive.
            scheduleRecovery(workspace.id);
          }
          return;
        }
        if (isRemoteOmniRushWorkspace) {
          setWorkspaceConnectionOverrides((current) => ({
            ...current,
            [workspace.id]: {
              status: "connecting",
              message: t("workspace_list.loading_remote_tasks"),
              checkedAt: null,
            },
          }));
        }
        try {
          // The sidebar lists from whichever engine chat is routed to.
          const usesV2List = workspace.workspaceType !== "remote" && engineV2ChatRoutingRef.current;
          const fetchedItems = usesV2List
            ? await listRouteSessions(endpoint, v2RouteSessionList, workspace.path ?? "")
            : await listRouteSessions(endpoint);
          const workspaceRoot = normalizeDirectoryPath(workspace.path ?? "");
          // The local server already scopes the list to this folder (the 2.x
          // list is scoped in v2RouteSessionList), also under its real path
          // (symlink, junction, subst drive), which this string compare would
          // drop. Remote lists still need the filter.
          const serverScoped = workspace.workspaceType !== "remote";
          const items = workspaceRoot && !isRemoteOmniRushWorkspace && !serverScoped
            ? fetchedItems.filter((session) =>
                normalizeDirectoryPath(session?.directory ?? "") === workspaceRoot,
              )
            : fetchedItems;
          if (workspace.workspaceType !== "remote") {
            const currentItems = sessionsByWorkspaceIdRef.current[workspace.id] ?? [];
            const currentIsListed = listedWorkspaceIdsRef.current.has(workspace.id);
            const known = currentIsListed
              ? currentItems
              : sessionsAfterListFailure({
                  current: currentItems,
                  cached: readCachedWorkspaceSessions(workspace.id) as RouteSession[] | null,
                  currentIsListed,
                });
            const recheckCount = emptyListRechecksRef.current[workspace.id] ?? 0;
            if (shouldRecheckEmptySessionList({ fetchedCount: items.length, knownCount: known.length, recheckCount })) {
              // The list answered but holds none of the sessions this
              // workspace is known to have. Keep showing them and ask again
              // on the recovery schedule; only a repeated empty answer
              // replaces them. It does not count as loaded, so a reconnect
              // refresh asks again too.
              emptyListRechecksRef.current[workspace.id] = recheckCount + 1;
              console.warn("[session-route] session list came back empty; keeping known sessions", {
                workspaceId: workspace.id,
                knownSessions: known.length,
                recheck: recheckCount + 1,
              });
              recordInspectorEvent("route.session_list.empty_recheck", {
                workspaceId: workspace.id,
                knownSessions: known.length,
                recheck: recheckCount + 1,
              });
              keepKnownSessionsAfterListFailure(workspace.id);
              loadedWorkspaceIdsRef.current.delete(workspace.id);
              setSessionListErrorsByWorkspaceId((current) => {
                if (!current[workspace.id]) return current;
                const next = { ...current };
                delete next[workspace.id];
                return next;
              });
              setRetryingWorkspaceIds((current) =>
                current.includes(workspace.id) ? current.filter((id) => id !== workspace.id) : current,
              );
              scheduleRecovery(workspace.id);
              return;
            }
            delete emptyListRechecksRef.current[workspace.id];
          }
          const current = sessionsByWorkspaceIdRef.current;
          const nextItems = mergeFetchedSessionsWithPending(workspace.id, items, current[workspace.id] ?? []);
          const next = { ...current, [workspace.id]: nextItems };
          sessionsByWorkspaceIdRef.current = next;
          setSessionsByWorkspaceId(next);
          loadedWorkspaceIdsRef.current.add(workspace.id);
          listedWorkspaceIdsRef.current.add(workspace.id);
          if (workspace.workspaceType !== "remote") writeCachedWorkspaceSessions(workspace.id, nextItems);
          clearSessionListRecovery(workspace.id);
          setSessionListErrorsByWorkspaceId((current) => {
            if (!current[workspace.id]) return current;
            const next = { ...current };
            delete next[workspace.id];
            return next;
          });
          setErrorsByWorkspaceId((current) => ({ ...current, [workspace.id]: null }));
          setWorkspaceConnectionOverrides((current) => {
            if (isRemoteOmniRushWorkspace) {
              return {
                ...current,
                [workspace.id]: {
                  status: "connected",
                  message: items.length > 0
                    ? t("workspace_list.connected_loaded_tasks", { count: items.length })
                    : t("workspace.connected_no_tasks"),
                  checkedAt: Date.now(),
                },
              };
            }
            if (current[workspace.id]?.status !== "error") return current;
            const next = { ...current };
            delete next[workspace.id];
            return next;
          });
          setRetryingWorkspaceIds((current) =>
            current.includes(workspace.id) ? current.filter((id) => id !== workspace.id) : current,
          );
          // When a workspace returns zero sessions during the initial batch
          // load, OpenCode may still be warming up its index.  Schedule a
          // single delayed retry so the sidebar doesn't stay permanently
          // empty while the managed engine finishes starting.
          if (items.length === 0 && attempt === 0) {
            window.setTimeout(() => {
              if (backgroundSessionLoadCoalescerRef.current.isInFlight(workspace.id)) return;
              void backgroundSessionLoadCoalescerRef.current.run(
                workspace.id,
                () => fetchWithRetries(workspace, 1),
              );
            }, 3_000);
          }
        } catch (error) {
          const message = error instanceof Error ? error.message : t("app.unknown_error");
          // The first cold call to OpenCode's /session endpoint often hits
          // the 12s server timeout while the daemon finishes warming up
          // its index. Retry silently with backoff until we get a response
          // or run out of attempts — the sidebar keeps its "loading" state
          // in the meantime instead of flashing "error" next to the
          // workspace name.
          if (attempt + 1 < MAX_ATTEMPTS && classifyRouteSessionReadError(error) === "retryable") {
            if (workspace.workspaceType !== "remote") keepKnownSessionsAfterListFailure(workspace.id);
            await new Promise((r) => window.setTimeout(r, backoffMs(attempt)));
            await fetchWithRetries(workspace, attempt + 1);
            return;
          }
          // Final failure: keep local workspace startup quiet, but give
          // remote workers a precise endpoint/token/workspace diagnostic.
          if (workspace.workspaceType === "remote") {
            const connectionState = await diagnoseRemoteWorkspaceTaskLoadFailure(workspace, message);
            setErrorsByWorkspaceId((current) => ({
              ...current,
              [workspace.id]: connectionState.message ?? "Remote worker connection failed.",
            }));
            setWorkspaceConnectionOverrides((current) => {
              return {
                ...current,
                [workspace.id]: connectionState,
              };
            });
          } else {
            // Never let a failed list read as "No tasks yet": keep the known
            // sessions, flag the group, and reload it again later. A later
            // route refresh (reconnect, restart) also reloads it because it
            // no longer counts as loaded.
            console.warn("[session-route] session list failed to load", { workspaceId: workspace.id, message });
            recordInspectorEvent("route.session_list.error", { workspaceId: workspace.id, message });
            keepKnownSessionsAfterListFailure(workspace.id);
            loadedWorkspaceIdsRef.current.delete(workspace.id);
            setSessionListErrorsByWorkspaceId((current) =>
              current[workspace.id] === message ? current : { ...current, [workspace.id]: message },
            );
            scheduleRecovery(workspace.id);
          }
          setRetryingWorkspaceIds((current) =>
            current.includes(workspace.id) ? current.filter((id) => id !== workspace.id) : current,
          );
        }
      };

      await mapRouteWorkspaceLoads(workspaces, (workspace) =>
        backgroundSessionLoadCoalescerRef.current.run(
          workspace.id,
          () => fetchWithRetries(workspace, 0),
        ),
      );
    },
    [clearSessionListRecovery, endpointForWorkspace, keepKnownSessionsAfterListFailure, mergeFetchedSessionsWithPending],
  );
  const reloadWorkspaceSessions = useCallback(async (workspaceId: string): Promise<void> => {
    const workspace = workspacesRef.current.find((item) => item.id === workspaceId);
    if (!workspace) return;
    loadedWorkspaceIdsRef.current.delete(workspaceId);
    await loadWorkspaceSessionsInBackground([workspace]);
  }, [loadWorkspaceSessionsInBackground]);
  /** The sidebar's "Retry" on a workspace whose task list could not be loaded. */
  const retryWorkspaceSessions = useCallback((workspaceId: string) => {
    clearSessionListRecovery(workspaceId);
    setRetryingWorkspaceIds((current) => current.includes(workspaceId) ? current : [...current, workspaceId]);
    void reloadWorkspaceSessions(workspaceId);
  }, [clearSessionListRecovery, reloadWorkspaceSessions]);
  useEffect(() => () => {
    for (const entry of Object.values(sessionListRecoveryRef.current)) {
      if (entry.timer !== null) window.clearTimeout(entry.timer);
    }
    sessionListRecoveryRef.current = {};
  }, []);
  const workspaceSelectionCommitRef = useRef<(workspaceId: string) => Promise<void>>(async () => undefined);
  workspaceSelectionCommitRef.current = async (workspaceId) => {
    await commitRouteWorkspaceSelection({
      workspaceId,
      desktopRuntime: isDesktopRuntime(),
      setDesktopSelected: workspaceSetSelected,
      setDesktopRuntimeActive: workspaceSetRuntimeActive,
      activateWorkspace: async (selectedId) => {
        const workspace = workspacesRef.current.find((item) => item.id === selectedId) ?? null;
        const endpoint = endpointForWorkspace(workspace);
        if (!endpoint) throw new Error(`Workspace endpoint unavailable for ${selectedId}.`);
        if (workspace?.workspaceType === "local" && serverActiveWorkspaceIdRef.current === selectedId) return;
        await endpoint.client.activateWorkspace(endpoint.workspaceId, { persist: true });
        if (workspace?.workspaceType === "local") serverActiveWorkspaceIdRef.current = selectedId;
      },
    });
  };

  const refreshRouteState = useCallback(async (options?: { supersede?: boolean }) => {
    // Dedupe: if a refresh is already running, skip this call. Fast workspace
    // switches used to fire 5-6 overlapping refreshRouteState() calls which
    // each fetched workspaces + sessions for every workspace. That workload
    // multiplied quickly on the event loop and caused the UI to freeze.
    // Callers reacting to changed connection info pass `supersede` instead of
    // resetting the in-flight guard: the running attempt goes stale (its
    // remaining writes are discarded) rather than racing the new one.
    const attempt = refreshLifecycleRef.current.begin(options);
    if (!attempt) return;
    setLoading(true);
    setRouteError(null);
    let desktopList: WorkspaceList | null = null;
    let desktopWorkspaces = workspacesRef.current;
    let routeReadyAfterRefresh = true;
    try {
      if (isDesktopRuntime()) {
        try {
          desktopList = await withRouteRefreshTimeout(workspaceBootstrap(), "Desktop workspace bootstrap") as WorkspaceList;
          desktopWorkspaces = (desktopList.workspaces ?? []).map(mapDesktopWorkspace);
        } catch (error) {
          const message = describeRouteError(error);
          console.error("[session-route] workspaceBootstrap failed", error);
          recordInspectorEvent("route.workspace_bootstrap.error", {
            route: "session",
            message,
            preservedWorkspaceCount: workspacesRef.current.length,
          });
          desktopWorkspaces = workspacesRef.current;
        }
      }
      if (!attempt.isCurrent()) return;

      const { normalizedBaseUrl, resolvedToken, resolvedHostToken, hostInfo } = await withRouteRefreshTimeout(
        resolveOmniRushConnection(),
        "omnirush.ai server connection",
      );
      if (!attempt.isCurrent()) return;
      if (!normalizedBaseUrl || !resolvedToken) {
        const gapPlan = planRouteConnectionGap({ desktopRuntime: isDesktopRuntime() });
        routeReadyAfterRefresh = gapPlan.markRouteReady;
        if (gapPlan.retainExistingState) {
          // Transient desktop gap: the local server is booting or restarting
          // (app update, remote-access toggle, slow cold start) and has not
          // republished its ephemeral base URL/tokens yet. Retain the
          // workspaces, session lists, and host info as display state, but
          // quarantine the live connection: the previous loopback port is no
          // longer owned by our server, and a request there would hand the
          // stale bearer token to whatever process binds the freed port.
          // Boot or the reconnect effect publishes fresh info and supersedes
          // this refresh. Only seed workspaces when the route has none so a
          // fresh renderer still shows the sidebar under the boot overlay.
          setConnectionPending(true);
          connectionGapSeenRef.current = true;
          updateLocalServer({ baseUrl: "", token: "" });
          setClient(null);
          setBaseUrl("");
          setToken("");
          if (workspacesRef.current.length === 0 && desktopWorkspaces.length > 0) {
            const orderedDesktopWorkspaces = commitStableWorkspaceOrder(desktopWorkspaces);
            setWorkspaces(orderedDesktopWorkspaces);
            setLegacySelectedWorkspaceId(
              (current) => current || resolveWorkspaceListSelectedId(desktopList) || orderedDesktopWorkspaces[0]?.id || "",
            );
          }
          return;
        }
        onHostInfo(hostInfo);
        connectionGapSeenRef.current = true;
        // Keep the workspace endpoint resolver in lockstep with the disconnected state.
        // Otherwise a previously-cached baseUrl/token would still resolve a
        // (now invalid) endpoint for any callback that consults the resolver ref.
        updateLocalServer({ baseUrl: "", token: "" });
        setClient(null);
        setBaseUrl("");
        setToken("");
        const orderedDesktopWorkspaces = commitStableWorkspaceOrder(desktopWorkspaces);
        setWorkspaces(orderedDesktopWorkspaces);
        sessionsByWorkspaceIdRef.current = {};
        setSessionsByWorkspaceId({});
        setErrorsByWorkspaceId({});
        setLegacySelectedWorkspaceId(resolveWorkspaceListSelectedId(desktopList) || orderedDesktopWorkspaces[0]?.id || "");
        return;
      }
      onHostInfo(hostInfo);

      // Update the local-server resolver synchronously, BEFORE we kick off any
      // workspace-scoped requests below. `endpointForWorkspace` reads from
      // this resolver synchronously; the render that mirrors `[baseUrl,
      // token]` into the resolver doesn't run until after the next React commit,
      // which is too late for the `loadWorkspaceSessionsInBackground` call
      // later in this function. Stale ref => `resolveWorkspaceEndpoint` returns null for
      // local workspaces => sidebar gets stuck in "loading" forever.
      updateLocalServer({ baseUrl: normalizedBaseUrl, token: resolvedToken });

      const omnirushClient = createOmniRushServerClient({
        baseUrl: normalizedBaseUrl,
        token: resolvedToken,
        hostToken: resolvedHostToken || undefined,
      });
      const workspaceListState = await refreshRouteWorkspaceListState({
        load: () => withRouteRefreshTimeout(omnirushClient.listWorkspaces(), "Workspace list"),
        desktopWorkspaces,
        previousWorkspaces: workspacesRef.current,
        orderIds: workspaceOrderIdsRef.current,
        retryDelaysMs: [250, 750, 1_500],
      });
      if (!attempt.isCurrent()) return;
      if (!workspaceListState.usable || workspaceListState.error) {
        const message = workspaceListState.error
          ? describeRouteError(workspaceListState.error)
          : "Workspace list response did not include items.";
        console.warn("[session-route] workspace list degraded", workspaceListState.error ?? message);
        recordInspectorEvent("route.workspace_list.degraded", {
          route: "session",
          message,
          preservedWorkspaceCount: workspacesRef.current.length,
        });
        setRouteError(message);
      }
      const nextWorkspaces = commitStableWorkspaceOrder(workspaceListState.workspaces);
      serverActiveWorkspaceIdRef.current = workspaceListState.activeId ?? "";

      // A restarted built-in server (new URL/token, or a gap since the last
      // connection) answers for every local workspace afresh: lists loaded or
      // failed against the old one are fetched again. Groups that already
      // show sessions reload silently.
      const connectionKey = `${normalizedBaseUrl}\n${resolvedToken}`;
      const reconnectReloadIds = planSessionListReloadAfterReconnect({
        previousConnectionKey: lastConnectionKeyRef.current,
        nextConnectionKey: connectionKey,
        connectionGapSeen: connectionGapSeenRef.current,
        workspaces: nextWorkspaces,
      });
      lastConnectionKeyRef.current = connectionKey;
      connectionGapSeenRef.current = false;
      for (const workspaceId of reconnectReloadIds) loadedWorkspaceIdsRef.current.delete(workspaceId);
      const silentReloadIds = new Set(
        reconnectReloadIds.filter((workspaceId) => (sessionsByWorkspaceIdRef.current[workspaceId]?.length ?? 0) > 0),
      );
      if (reconnectReloadIds.length > 0) {
        recordInspectorEvent("route.session_list.reload_after_reconnect", { workspaces: reconnectReloadIds.length });
      }

      // Preserve any sessions we already have cached so switching routes
      // doesn't erase the sidebar while we refetch.
      const alreadyLoadedWorkspaceIds = new Set(loadedWorkspaceIdsRef.current);
      const cachedEntries = nextWorkspaces.map((workspace) => ({
        workspaceId: workspace.id,
        sessions: sessionsByWorkspaceIdRef.current[workspace.id] ?? [],
      }));
      // Prefer, in order: the URL-selected workspace (if it owns the session),
      // the user's last-active workspace from localStorage, the desktop's
      // activeId, the server's activeId, then the first known workspace.
      const persistedActiveId = readActiveWorkspaceId();
      let nextWorkspaceId =
        (routeWorkspaceIdRef.current && nextWorkspaces.some((w) => w.id === routeWorkspaceIdRef.current)
          ? routeWorkspaceIdRef.current
          : "") ||
        (persistedActiveId && nextWorkspaces.some((w) => w.id === persistedActiveId)
          ? persistedActiveId
          : "") ||
        resolveWorkspaceListSelectedId(desktopList) ||
        workspaceListState.activeId ||
        nextWorkspaces[0]?.id ||
        "";
      if (workspaceInferenceSessionIdRef.current) {
        const match = cachedEntries.find((entry) =>
          entry.sessions.some((session) => session?.id === workspaceInferenceSessionIdRef.current),
        );
        if (match?.workspaceId) nextWorkspaceId = match.workspaceId;
      }
      const backgroundWorkspaceIds = planRouteWorkspaceLoads(
        nextWorkspaces.map((workspace) => workspace.id),
        nextWorkspaceId,
        alreadyLoadedWorkspaceIds,
      );

      updateLocalServer({ baseUrl: normalizedBaseUrl, token: resolvedToken });

      setConnectionPending(false);
      setClient(omnirushClient);
      setBaseUrl(normalizedBaseUrl);
      setToken(resolvedToken);
      setWorkspaces(nextWorkspaces);
      const nextSessionsByWorkspaceId = Object.fromEntries(cachedEntries.map((entry) => [entry.workspaceId, entry.sessions]));
      sessionsByWorkspaceIdRef.current = nextSessionsByWorkspaceId;
      setSessionsByWorkspaceId(nextSessionsByWorkspaceId);
      setErrorsByWorkspaceId((previous) => {
        const next: Record<string, string | null> = {};
        for (const workspace of nextWorkspaces) {
          next[workspace.id] = previous[workspace.id] ?? null;
        }
        return next;
      });
      setRetryingWorkspaceIds(backgroundWorkspaceIds.filter((workspaceId) => !silentReloadIds.has(workspaceId)));
      setLegacySelectedWorkspaceId(nextWorkspaceId);
      writeActiveWorkspaceId(nextWorkspaceId || null);
      recordInspectorEvent("route.refresh.complete", {
        workspaces: nextWorkspaces.length,
        selectedWorkspaceId: nextWorkspaceId,
        errors: {},
      });

      // Session list comes from OpenCode's index and can be slow on cold
      // boot. Kick it off in the background instead of blocking the route
      // so the UI is interactive immediately; the sidebar shows a
      // loading state per-workspace until the list arrives.
      const backgroundWorkspaces = nextWorkspaces.filter((workspace) => backgroundWorkspaceIds.includes(workspace.id));
      if (backgroundWorkspaces.length > 0) {
        void loadWorkspaceSessionsInBackground(backgroundWorkspaces);
      }
    } catch (error) {
      if (!attempt.isCurrent()) return;
      const message = describeRouteError(error);
      console.error("[session-route] refreshRouteState failed", error);
      recordInspectorEvent("route.refresh.error", {
        route: "session",
        message,
        preservedWorkspaceCount: desktopWorkspaces.length,
      });
      setRouteError(message);
      if (desktopWorkspaces.length > 0) {
        const orderedDesktopWorkspaces = commitStableWorkspaceOrder(desktopWorkspaces);
        setWorkspaces(orderedDesktopWorkspaces);
        setLegacySelectedWorkspaceId((current) =>
          current || resolveWorkspaceListSelectedId(desktopList) || orderedDesktopWorkspaces[0]?.id || "",
        );
      }
    } finally {
      attempt.finish();
      // A superseded attempt changes nothing here: the newer attempt owns
      // loading, the refresh version, and boot-overlay readiness.
      if (attempt.isCurrent()) {
        setLoading(false);
        setRouteRefreshVersion((current) => current + 1);
        // Tell the boot overlay the first route data load has completed so
        // the overlay dismisses after BOTH the desktop boot and the workspace
        // list/sessions are ready. A transient desktop connection gap does
        // not count: the overlay must outlast the restart recovery.
        if (routeReadyAfterRefresh) {
          markBootRouteReady();
        }
      }
    }
  }, [commitStableWorkspaceOrder, legacyWorkspaceInferenceKey, loadWorkspaceSessionsInBackground, markBootRouteReady, updateLocalServer]);

  const routeWorkspaceKnown = Boolean(
    routeWorkspaceId && workspaces.some((workspace) => workspace.id === routeWorkspaceId),
  );
  useEffect(() => {
    if (workspaceSelectionCommitTimerRef.current !== null) {
      window.clearTimeout(workspaceSelectionCommitTimerRef.current);
      workspaceSelectionCommitTimerRef.current = null;
    }
    if (!routeWorkspaceId) return;

    // The URL is the user's newest selection. Persist it synchronously so a
    // slow refresh or activation can never leave storage on an older route.
    setLegacySelectedWorkspaceId(routeWorkspaceId);
    writeActiveWorkspaceId(routeWorkspaceId);
    if (!routeWorkspaceKnown) return;

    workspaceSelectionCommitTimerRef.current = window.setTimeout(() => {
      workspaceSelectionCommitTimerRef.current = null;
      routeWorkspaceSelectionCommitter.request(
        routeWorkspaceId,
        (workspaceId) => workspaceSelectionCommitRef.current(workspaceId),
      );
    }, ROUTE_WORKSPACE_ACTIVATION_SETTLE_MS);
    // On navigation only the routed workspace needs a load: boot already
    // scheduled background loads for every other unloaded workspace. The
    // routed one is refetched even when it loaded before — a non-selected
    // workspace receives no engine events, so sessions created outside this
    // window (agents, other clients) only reach its list through a refetch.
    // A first load shows the loading indicator; a refresh stays silent so the
    // existing rows and the New task control never flicker.
    const workspace = workspacesRef.current.find((item) => item.id === routeWorkspaceId);
    if (workspace) {
      if (!loadedWorkspaceIdsRef.current.has(workspace.id)) {
        setRetryingWorkspaceIds((current) => Array.from(new Set([...current, workspace.id])));
      }
      void loadWorkspaceSessionsInBackground([workspace]);
    }
    return () => {
      if (workspaceSelectionCommitTimerRef.current === null) return;
      window.clearTimeout(workspaceSelectionCommitTimerRef.current);
      workspaceSelectionCommitTimerRef.current = null;
    };
  }, [loadWorkspaceSessionsInBackground, routeWorkspaceId, routeWorkspaceKnown]);
  const handleRuntimeSessionUpdated = useCallback((update: { sessionId: string; info: Record<string, unknown> }) => {
    if (!selectedWorkspaceId) return;
    setSessionsByWorkspaceId((current) => {
      const list = current[selectedWorkspaceId] ?? [];
      const index = list.findIndex((session) => session?.id === update.sessionId);
      if (index < 0) return current;
      const nextSession = { ...list[index], ...update.info, id: update.sessionId };
      if (JSON.stringify(nextSession) === JSON.stringify(list[index])) return current;
      const nextList = [...list];
      nextList[index] = nextSession;
      const next = { ...current, [selectedWorkspaceId]: nextList };
      sessionsByWorkspaceIdRef.current = next;
      return next;
    });
  }, [selectedWorkspaceId]);
  const handleRuntimeSessionCreated = useCallback((session: Session) => {
    if (!selectedWorkspaceId) return;
    const workspace = workspacesRef.current.find((item) => item.id === selectedWorkspaceId);
    if (workspace?.path && normalizeDirectoryPath(session.directory) !== normalizeDirectoryPath(workspace.path)) return;
    rememberPendingCreatedSession(selectedWorkspaceId, session.id);
    setSessionsByWorkspaceId((current) => {
      const list = current[selectedWorkspaceId] ?? [];
      const nextList = mergeWorkspaceRouteSession(list, session);
      if (nextList === list) return current;
      const next = { ...current, [selectedWorkspaceId]: nextList };
      sessionsByWorkspaceIdRef.current = next;
      return next;
    });
  }, [rememberPendingCreatedSession, selectedWorkspaceId]);
  /**
   * A deleted session leaves every sidebar list, the saved lists and any
   * pending-created overlay at once, whichever workspace lists it: the delete
   * may have gone through another workspace's engine, whose event the
   * owning workspace never receives.
   */
  const forgetDeletedSession = useCallback((sessionId: string) => {
    const id = sessionId.trim();
    if (!id) return;
    deletedSessionIdsRef.current.add(id);
    for (const pending of Object.values(pendingCreatedSessionIdsRef.current)) delete pending[id];
    const { lists, workspaceIds } = removeSessionFromWorkspaceLists(sessionsByWorkspaceIdRef.current, id);
    for (const workspaceId of new Set([...workspaceIds, selectedWorkspaceId])) removeCachedWorkspaceSession(workspaceId, id);
    if (workspaceIds.length === 0) return;
    sessionsByWorkspaceIdRef.current = lists;
    setSessionsByWorkspaceId(lists);
  }, [selectedWorkspaceId]);
  const handleRuntimeSessionDeleted = forgetDeletedSession;
  /**
   * The engine confirmed this workspace has no such chat. Drop it from the
   * sidebar, the saved list, the remembered chat and the tabs, and move off it
   * when it is the open chat, instead of a dead-end "not found" page. Unlike a
   * delete it is not blocked from coming back: a chat still being carried
   * over from the earlier engine shows up again on a later list.
   */
  const forgetMissingSession = useCallback((workspaceId: string, sessionId: string) => {
    const wsId = workspaceId.trim();
    const id = sessionId.trim();
    if (!wsId || !id) return;
    const pending = pendingCreatedSessionIdsRef.current[wsId];
    if (pending) delete pending[id];
    if (hydratedRouteSessionIdsRef.current[wsId] === id) delete hydratedRouteSessionIdsRef.current[wsId];
    const current = sessionsByWorkspaceIdRef.current;
    const list = current[wsId] ?? [];
    const nextList = removeWorkspaceRouteSession(list, id);
    if (nextList !== list) {
      const next = { ...current, [wsId]: nextList };
      sessionsByWorkspaceIdRef.current = next;
      setSessionsByWorkspaceId(next);
    }
    forgetMissingChatMemory({ workspaceId: wsId, sessionId: id });
    recordInspectorEvent("route.session.missing", { workspaceId: wsId, sessionId: id });
    if (wsId === selectedWorkspaceIdRef.current && id === selectedSessionIdRef.current) {
      navigateToWorkspaceSession(wsId, null, { replace: true });
    }
    toast.info(t("session.missing_chat_title"), {
      id: `missing-chat:${id}`,
      description: t("session.missing_chat_description"),
    });
  }, [navigateToWorkspaceSession]);
  const forgetMissingSessionRef = useRef(forgetMissingSession);
  forgetMissingSessionRef.current = forgetMissingSession;

  useEffect(() => {
    workspacesRef.current = workspaces;
  }, [workspaces]);

  useEffect(() => {
    workspaceOrderIdsRef.current = workspaceOrderIds;
  }, [workspaceOrderIds]);

  useEffect(() => {
    const activeWorkspaceIds = new Set(workspaces.map((workspace) => workspace.id));
    setWorkspaceConnectionOverrides((current) => {
      let changed = false;
      const next: Record<string, WorkspaceConnectionState> = {};
      for (const [workspaceId, state] of Object.entries(current)) {
        if (activeWorkspaceIds.has(workspaceId)) {
          next[workspaceId] = state;
        } else {
          changed = true;
        }
      }
      return changed ? next : current;
    });
  }, [workspaces]);

  useEffect(() => {
    sessionsByWorkspaceIdRef.current = sessionsByWorkspaceId;
  }, [sessionsByWorkspaceId]);

  const handleRemoteWorkspaceConnectionSaved = useCallback(
    async (workspaceId: string) => {
      delete remoteWorkspaceCheckRunRef.current[workspaceId];
      setWorkspaceConnectionOverrides((current) => {
        const next = { ...current };
        delete next[workspaceId];
        return next;
      });
      setErrorsByWorkspaceId((current) => ({ ...current, [workspaceId]: null }));
      setRetryingWorkspaceIds((current) => current.filter((id) => id !== workspaceId));
      await refreshRouteState();
    },
    [refreshRouteState],
  );

  useEffect(() => {
    let cancelled = false;

    void (async () => {
      try {
        if (cancelled) return;
        await refreshRouteState();
      } finally {
        if (cancelled) return;
      }
    })();

    const handleSettingsChange = () => {
      onServerSettingsChanged();
      // Fresh connection info was published (boot, restart, or reconnect).
      // Supersede any in-flight refresh — including one stuck mid-flight
      // (e.g. macOS backgrounded the webview and never let a fetch resolve) —
      // so its stale resolution cannot overwrite the new connection state.
      void refreshRouteState({ supersede: true });
    };
    window.addEventListener("omnirush-server-settings-changed", handleSettingsChange);

    // Also retry on visibility flip independently — even when nobody else
    // dispatches the settings event.
    const handleVisibility = () => {
      if (typeof document === "undefined") return;
      if (document.visibilityState !== "visible") return;
      void refreshRouteState({ supersede: true });
    };
    if (typeof document !== "undefined") {
      document.addEventListener("visibilitychange", handleVisibility);
    }

    return () => {
      cancelled = true;
      if (startupRetryTimerRef.current !== null) {
        window.clearTimeout(startupRetryTimerRef.current);
        startupRetryTimerRef.current = null;
      }
      window.removeEventListener("omnirush-server-settings-changed", handleSettingsChange);
      if (typeof document !== "undefined") {
        document.removeEventListener("visibilitychange", handleVisibility);
      }
    };
  }, [refreshRouteState]);

  // Inspector wiring: publish the route's current state so an external
  // operator (or an AI driver using browser tools) can call
  // `window.__omnirush.snapshot()` or `window.__omnirush.slice("route")` and
  // see workspaces / sessions / connection info without walking the DOM.
  useEffect(() => {
    const dispose = publishInspectorSlice("route", () => ({
      loading,
      retryingWorkspaceIds,
      baseUrl,
      tokenPresent: token.length > 0,
      connected: Boolean(client),
      connectionPending,
      routeError,
      selectedSessionId,
      selectedWorkspaceId,
      persistedActiveWorkspaceId: readActiveWorkspaceId(),
      workspaces: workspaces.map((workspace) => ({
        id: workspace.id,
        displayNameResolved: workspace.displayNameResolved,
        workspaceType: workspace.workspaceType,
        path: workspace.path,
        sessionCount: (sessionsByWorkspaceId[workspace.id] ?? []).length,
        loading: retryingWorkspaceIds.includes(workspace.id),
        error: errorsByWorkspaceId[workspace.id] ?? null,
      })),
      sessionsByWorkspaceId: Object.fromEntries(
        Object.entries(sessionsByWorkspaceId).map(([wsId, items]) => [
          wsId,
          (items ?? []).map((session) => ({
            id: session?.id ?? null,
            title: session?.title ?? null,
            directory: session?.directory ?? null,
          })),
        ]),
      ),
    }));
    return dispose;
  }, [
    baseUrl,
    client,
    connectionPending,
    errorsByWorkspaceId,
    loading,
    retryingWorkspaceIds,
    selectedSessionId,
    selectedWorkspaceId,
    routeError,
    sessionsByWorkspaceId,
    token,
    workspaces,
  ]);

  // Once workspaces are loaded, normalize the URL onto the active workspace.
  // Deliberately no last-session restore here: a fresh app load with no
  // session in the URL lands on the empty "new task" state instead of
  // jumping back into the previously opened session.
  useEffect(() => {
    if (loading) return;
    if (routeWorkspaceId && workspaces.length > 0 && !workspaces.some((workspace) => workspace.id === routeWorkspaceId)) {
      const fallbackWorkspaceId = workspaces.some((workspace) => workspace.id === legacySelectedWorkspaceId)
        ? legacySelectedWorkspaceId
        : workspaces[0]?.id || "";
      if (fallbackWorkspaceId) {
        normalizeWorkspaceRoute(fallbackWorkspaceId, selectedSessionId, { replace: true });
      }
      return;
    }
    if (!routeWorkspaceId && selectedWorkspaceId) {
      normalizeWorkspaceRoute(selectedWorkspaceId, selectedSessionId, { replace: true });
    }
  }, [
    extensionsRouteActive,
    extensionsRoutePath,
    loading,
    legacySelectedWorkspaceId,
    normalizeWorkspaceRoute,
    routeWorkspaceId,
    selectedSessionId,
    selectedWorkspaceId,
    workspaces,
  ]);

  // Desktop starts in the normal task UI; deployment sign-in and activation
  // gates are owned by the app root. Keep the non-desktop welcome path.
  useEffect(() => {
    if (isDesktopRuntime()) return;
    if (loading) return;
    if (workspaces.length > 0) return;
    if (local.prefs.hasCompletedOnboarding) return;
    if (denAuth.status === "checking") return;
    if (denAuth.isSignedIn) return;
    navigate("/welcome", { replace: true });
  }, [denAuth.isSignedIn, denAuth.status, loading, local.prefs.hasCompletedOnboarding, navigate, workspaces.length]);

  // NOTE: Blueprint seeding was removed from the route.
  // It was firing `materializeBlueprintSessions` + a session re-fetch on every
  // workspace change, which cascaded setState updates and froze the UI after
  // a few rapid switches. Empty workspaces now simply show "No tasks yet." and
  // the user creates their first session explicitly via "New task". Seeding
  // can be reintroduced later as a one-shot triggered from a button or from
  // the onboarding flow, not from the route effect loop.
  useEffect(() => {
    if (client && !connectionPending) {
      reconnectAttemptedWorkspaceIdRef.current = "";
    }
    if (
      !shouldAttemptDesktopLocalReconnect({
        desktopRuntime: isDesktopRuntime(),
        bootPhase,
        bootRouteReady,
        routeLoading: loading,
        hasClient: Boolean(client),
        connectionPending,
        workspaceType: selectedWorkspace?.workspaceType ?? null,
      })
    ) {
      return;
    }
    if (!selectedWorkspace) return;
    const workspaceId = selectedWorkspace.id?.trim() ?? "";
    if (!workspaceId || reconnectAttemptedWorkspaceIdRef.current === workspaceId) return;
    reconnectAttemptedWorkspaceIdRef.current = workspaceId;

    void ensureDesktopLocalOmniRushConnection({
      route: "session",
      workspace: selectedWorkspace,
      allWorkspaces: workspaces,
    }).catch((error) => {
      const message = error instanceof Error ? error.message : describeRouteError(error);
      setRouteError(message);
      // Recovery definitively failed. Release the boot overlay so the
      // retained route (with this error surfaced) is visible instead of the
      // overlay wedging forever.
      markBootRouteReady();
    });
  }, [bootPhase, bootRouteReady, client, connectionPending, loading, markBootRouteReady, selectedWorkspace, workspaces]);

  const selectedWorkspaceRoot = selectedWorkspace?.path?.trim() || "";
  // Single source of truth for the selected workspace's server URL/token/id.
  // For remote workspaces this is the worker that owns the workspace; for
  // local workspaces it's the user's local omnirush.ai server.
  const selectedWorkspaceEndpoint = useWorkspaceServerClient(selectedWorkspace, { baseUrl, token });
  const selectedWorkspaceServerToken = selectedWorkspaceEndpoint?.token ?? "";
  const defaultOpencodeBaseUrl = selectedWorkspaceEndpoint?.opencodeBaseUrl ?? "";
  const opencode2BaseUrl = selectedWorkspaceEndpoint ? `${selectedWorkspaceEndpoint.mountedBaseUrl}/opencode2` : "";
  const routingServerUrl = selectedWorkspaceEndpoint?.baseUrl ?? "";
  const routingServerToken = selectedWorkspaceEndpoint?.token ?? "";
  useEffect(() => {
    if (!routingServerUrl || !routingServerToken) {
      setEngineV2ChatRouting(true);
      return;
    }
    const omnirushClient = createOmniRushServerClient({ baseUrl: routingServerUrl, token: routingServerToken });
    let cancelled = false;
    const refresh = async () => {
      try {
        const status = await omnirushClient.getEngineV2PreviewStatus();
        if (!cancelled) {
          setEngineV2ChatRouting(status.enabled && status.chatRouting);
          setEngineRoutingReady(true);
        }
      } catch (error) {
        if (cancelled) return;
        // Older servers do not expose the preview endpoint and use v1.
        if (error instanceof OmniRushServerError && error.status === 404) {
          setEngineV2ChatRouting(false);
          setEngineRoutingReady(true);
        }
        console.warn("[opencode-v2] failed to read chat routing status; retaining the current engine", error);
      }
    };
    setEngineV2ChatRouting(true);
    setEngineRoutingReady(false);
    void refresh();
    window.addEventListener("omnirush-server-settings-changed", refresh);
    const interval = window.setInterval(() => { void refresh(); }, 15_000);
    return () => {
      cancelled = true;
      window.clearInterval(interval);
      window.removeEventListener("omnirush-server-settings-changed", refresh);
    };
  }, [routingServerUrl, routingServerToken]);
  useEffect(() => {
    const previous = previousEngineV2ChatRoutingRef.current;
    previousEngineV2ChatRoutingRef.current = engineV2ChatRouting;
    if (previous === null || previous === engineV2ChatRouting || !selectedWorkspaceId) return;
    void reloadWorkspaceSessions(selectedWorkspaceId);
  }, [engineV2ChatRouting, reloadWorkspaceSessions, selectedWorkspaceId]);
  const opencodeBaseUrl = engineV2ChatRouting ? opencode2BaseUrl : defaultOpencodeBaseUrl;
  const selectedWorkspaceError = errorsByWorkspaceId[selectedWorkspaceId] ?? null;
  const selectedSessionKnown = Boolean(
    selectedSessionId &&
      (sessionsByWorkspaceId[selectedWorkspaceId] ?? []).some((session) => session?.id === selectedSessionId),
  );
  const modernRouteSessionLoadKey = routeWorkspaceId && selectedSessionId && selectedWorkspace && selectedWorkspaceEndpoint
    ? JSON.stringify([
        routeWorkspaceId,
        selectedSessionId,
        selectedWorkspaceEndpoint.baseUrl,
        selectedWorkspaceEndpoint.workspaceId,
        selectedWorkspaceEndpoint.token,
        routeRefreshVersion,
        engineV2ChatRouting,
        engineRoutingReady,
      ])
    : "";
  const modernRouteSessionLoadPending = Boolean(
    modernRouteSessionLoadKey &&
      !selectedSessionKnown &&
      (modernRouteSessionResolution?.key !== modernRouteSessionLoadKey || modernRouteSessionResolution.status === "loading"),
  );
  const activeModernRouteSessionResolution = modernRouteSessionResolution?.key === modernRouteSessionLoadKey
    ? modernRouteSessionResolution
    : null;
  const selectedWorkspaceIsLoading = retryingWorkspaceIds.includes(selectedWorkspaceId) || modernRouteSessionLoadPending;
  useEffect(() => {
    const stale = Object.entries(hydratedRouteSessionIdsRef.current).filter(
      ([workspaceId, sessionId]) => workspaceId !== selectedWorkspaceId || sessionId !== selectedSessionId,
    );
    if (stale.length === 0) return;
    for (const [workspaceId] of stale) delete hydratedRouteSessionIdsRef.current[workspaceId];
    setSessionsByWorkspaceId((current) => {
      let next = current;
      for (const [workspaceId, sessionId] of stale) {
        const items = current[workspaceId] ?? [];
        const filtered = removeWorkspaceRouteSession(items, sessionId);
        if (filtered === items) continue;
        if (next === current) next = { ...current };
        next[workspaceId] = filtered;
      }
      if (next !== current) sessionsByWorkspaceIdRef.current = next;
      return next;
    });
  }, [selectedSessionId, selectedWorkspaceId]);
  useEffect(() => {
    if (!engineRoutingReady || !modernRouteSessionLoadKey || !selectedWorkspaceEndpoint || !selectedSessionId) {
      setModernRouteSessionResolution(null);
      return;
    }
    if (selectedSessionKnown) {
      setModernRouteSessionResolution(null);
      return;
    }
    let cancelled = false;
    setModernRouteSessionResolution({ key: modernRouteSessionLoadKey, status: "loading" });

    const hydrateSelectedSession = async () => {
      const outcome = await loadRouteSessionWithRetry({
        isCancelled: () => cancelled,
        load: async () => engineV2ChatRouting
          ? unwrap(await createClientV2(opencode2BaseUrl, selectedWorkspaceRoot || undefined, {
              token: selectedWorkspaceServerToken,
            }).session.get({ sessionID: selectedSessionId }))
          : await getNativeSession(selectedWorkspaceEndpoint, selectedSessionId),
      });
      if (cancelled || outcome.status === "cancelled") return;
      if (outcome.status === "not-found" && isMissingSessionError(outcome.error)) {
        setModernRouteSessionResolution(null);
        forgetMissingSessionRef.current(selectedWorkspaceId, selectedSessionId);
        return;
      }
      if (outcome.status !== "loaded") {
        setModernRouteSessionResolution({
          key: modernRouteSessionLoadKey,
          status: outcome.status,
          message: outcome.message,
        });
        return;
      }
      const session = outcome.value;
      if (session.id !== selectedSessionId) {
        setModernRouteSessionResolution({
          key: modernRouteSessionLoadKey,
          status: "error",
          message: "The server returned a different session.",
        });
        return;
      }
      setSessionsByWorkspaceId((current) => {
        const currentItems = current[selectedWorkspaceId] ?? [];
        if (currentItems.some((session) => session.id === selectedSessionId)) {
          delete hydratedRouteSessionIdsRef.current[selectedWorkspaceId];
          return current;
        }
        hydratedRouteSessionIdsRef.current[selectedWorkspaceId] = selectedSessionId;
        const nextItems = mergeWorkspaceRouteSession(currentItems, session);
        const next = { ...current, [selectedWorkspaceId]: nextItems };
        sessionsByWorkspaceIdRef.current = next;
        return next;
      });
      setErrorsByWorkspaceId((current) => ({ ...current, [selectedWorkspaceId]: null }));
      setModernRouteSessionResolution(null);
    };

    void hydrateSelectedSession();

    return () => {
      cancelled = true;
    };
  }, [modernRouteSessionLoadKey, selectedSessionId, selectedSessionKnown, selectedWorkspaceId]);
  const routeNotFoundMessage = (() => {
    if (loading) return null;
    if (routeWorkspaceId && !selectedWorkspace) {
      return "Workspace was not found. Select a new workspace from the sidebar.";
    }
    if (selectedSessionId && !selectedSessionKnown && activeModernRouteSessionResolution?.status === "not-found") {
      return "Session was not found. Select a new session from the sidebar.";
    }
    if (selectedSessionId && !selectedSessionKnown && activeModernRouteSessionResolution?.status === "error") {
      return `Session could not be loaded. ${activeModernRouteSessionResolution.message}`;
    }
    return null;
  })();
  // Boot-level loading blocks the whole UI. Session-list retries only fill the
  // sidebar; they must not gate the composer/New task.
  const effectiveLoading = loading;

  const opencodeClient = useMemo(
    () =>
      engineRoutingReady && opencodeBaseUrl && selectedWorkspaceServerToken && !selectedWorkspaceError
        ? createClientV2(opencodeBaseUrl, selectedWorkspaceRoot || undefined, {
            token: selectedWorkspaceServerToken,
          })
        : null,
    [engineRoutingReady, opencodeBaseUrl, selectedWorkspaceError, selectedWorkspaceRoot, selectedWorkspaceServerToken],
  );
  useEffect(() => {
    if (!developerMode || !opencodeClient) return;
    return publishInspectorOpencodeClient(opencodeClient);
  }, [developerMode, opencodeClient]);
  const runRemoteWorkspaceConnectionCheck = useCallback(
    async (workspaceId: string, mode: "test" | "recover") => {
      const workspace = workspacesRef.current.find((item) => item.id === workspaceId);
      if (!workspace || workspace.workspaceType !== "remote") return false;
      const connectionKey = getRemoteWorkspaceConnectionKey(workspace);
      remoteWorkspaceCheckRunCounterRef.current += 1;
      const runId = String(remoteWorkspaceCheckRunCounterRef.current);
      remoteWorkspaceCheckRunRef.current[workspaceId] = runId;

      setWorkspaceConnectionOverrides((current) => ({
        ...current,
        [workspaceId]: {
          status: "connecting",
          message: t("config.testing_connection"),
          checkedAt: null,
        },
      }));

      const result = await testRemoteWorkspaceConnection(workspace);
      const currentWorkspace = workspacesRef.current.find((item) => item.id === workspaceId);
      if (
        remoteWorkspaceCheckRunRef.current[workspaceId] !== runId ||
        !currentWorkspace ||
        getRemoteWorkspaceConnectionKey(currentWorkspace) !== connectionKey
      ) {
        if (remoteWorkspaceCheckRunRef.current[workspaceId] === runId) {
          delete remoteWorkspaceCheckRunRef.current[workspaceId];
        }
        return false;
      }
      setWorkspaceConnectionOverrides((current) => ({
        ...current,
        [workspaceId]: result.state,
      }));

      if (!result.ok) {
        setErrorsByWorkspaceId((current) => ({
          ...current,
          [workspaceId]: result.state.message ?? "Remote worker connection failed.",
        }));
        if (remoteWorkspaceCheckRunRef.current[workspaceId] === runId) {
          delete remoteWorkspaceCheckRunRef.current[workspaceId];
        }
        return false;
      }

      setErrorsByWorkspaceId((current) => ({ ...current, [workspaceId]: null }));
      setRetryingWorkspaceIds((current) => current.filter((id) => id !== workspaceId));
      if (mode === "recover") {
        await refreshRouteState();
      }
      if (remoteWorkspaceCheckRunRef.current[workspaceId] === runId) {
        delete remoteWorkspaceCheckRunRef.current[workspaceId];
      }
      return true;
    },
    [refreshRouteState],
  );

  return {
    navigateToWorkspaceSession,
    routeWorkspaceId,
    selectedSessionId,
    loading,
    effectiveLoading,
    client,
    baseUrl,
    token,
    workspaces,
    setWorkspaces,
    workspacesRef,
    workspaceOrderIds,
    setWorkspaceOrderIds,
    workspaceOrderIdsRef,
    sessionsByWorkspaceId,
    setSessionsByWorkspaceId,
    sessionsByWorkspaceIdRef,
    errorsByWorkspaceId,
    setErrorsByWorkspaceId,
    sessionListErrorsByWorkspaceId,
    workspaceConnectionOverrides,
    routeError,
    setRouteError,
    legacySelectedWorkspaceId,
    setLegacySelectedWorkspaceId,
    retryingWorkspaceIds,
    setRetryingWorkspaceIds,
    startupRetryTimerRef,
    selectedWorkspaceId,
    selectedWorkspace,
    selectedWorkspaceRoot,
    selectedWorkspaceEndpoint,
    selectedWorkspaceServerToken,
    opencodeBaseUrl,
    opencodeClient,
    selectedWorkspaceIsLoading,
    selectedWorkspaceError,
    routeNotFoundMessage,
    endpointForWorkspace,
    refreshRouteState,
    reloadWorkspaceSessions,
    retryWorkspaceSessions,
    loadWorkspaceSessionsInBackground,
    rememberPendingCreatedSession,
    handleRuntimeSessionCreated,
    handleRuntimeSessionUpdated,
    handleRuntimeSessionDeleted,
    forgetDeletedSession,
    forgetMissingSession,
    handleRemoteWorkspaceConnectionSaved,
    runRemoteWorkspaceConnectionCheck,
  };
}