Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

89.1 KB
Raw Blame
// oxlint-disable ok/no-physical-direction-utility -- pre-rule backlog — physical margin/padding/inset utilities predate the rule; drain by swapping ml/mr → ms/me, pl/pr → ps/pe, left/right → start/end, then deleting this line. See https://github.com/inkeep/open-knowledge/blob/main/lint-plugins/ok-rules/README.md#no-physical-direction-utility

import type { AttachmentPart, ThreadInfo } from '@inkeep/open-knowledge-core/acp/thread-protocol';
import {
  buildTerminalInputBytes,
  TERMINAL_CLIS,
  type TerminalCli,
} from '@inkeep/open-knowledge-core/handoff';
import type { TerminalPlacement } from '@inkeep/open-knowledge-core/terminal-layout';
import { useLingui } from '@lingui/react/macro';
import { SquareTerminalIcon } from 'lucide-react';
import {
  type CSSProperties,
  lazy,
  type ReactNode,
  type RefObject,
  Suspense,
  useEffect,
  useId,
  useLayoutEffect,
  useRef,
  useState,
} from 'react';
import { createPortal } from 'react-dom';
import { toast } from 'sonner';
import { ChatHistorySideMenuItem } from '@/components/acp/ChatHistorySideMenuItem';
import { RegisteredAgentIcon } from '@/components/acp/RegisteredAgentIcon';
import {
  ThreadHistoryPanel,
  ThreadHistorySearchProvider,
  ThreadHistoryToggle,
} from '@/components/acp/ThreadHistoryPanel';
import { publishReusableSession } from '@/components/reusable-session-store';
import { Button } from '@/components/ui/button';
import { Spinner } from '@/components/ui/spinner';
import { TabsContent } from '@/components/ui/tabs';
import {
  HISTORY_PANEL_WIDTH_PX,
  useHistoryPresentationMode,
} from '@/hooks/use-history-presentation-mode';
import { useActivityClock } from '@/lib/acp/activity-clock';
import { isInAppAgentEnabled } from '@/lib/acp/agent-visibility';
import { detectedHarnessAgents, useAgentCatalogQuery } from '@/lib/acp/catalog';
import { useEnabledOverrides } from '@/lib/acp/enabled-agents';
import { hasInflightThreadLaunch, launchAgentThread } from '@/lib/acp/launch-agent-thread';
import {
  enabledTerminalClis,
  LAUNCHER_KIND_PANE,
  type LauncherSelection,
  resolveLauncherSelection,
} from '@/lib/acp/launcher-selection';
import {
  pickEffectiveDefaultAgent,
  type RegisteredAgent,
  registerAgent,
  useDefaultRegisteredAgent,
  useRegisteredAgents,
} from '@/lib/acp/registered-agents';
import { formatRelativeActivity } from '@/lib/acp/relative-activity';
import {
  getAgentThreadClient,
  useAgentThreadConnection,
  useAgentThreadScope,
  useAgentThreads,
  useAgentThreadUnread,
  useInitialRosterThreadIds,
  useOpenAgentThreadTabs,
} from '@/lib/acp/thread-client';
import {
  isEmptyThreadDraft,
  readThreadDraft,
  stageThreadDraft,
  type ThreadDraftContent,
} from '@/lib/acp/thread-draft-staging';
import { threadHasUserMessage } from '@/lib/acp/thread-event-model';
import { usePreferredSessionSelection } from '@/lib/acp/use-preferred-session-selection';
import type { OkDesktopBridge, OkTerminalRestartSnapshot } from '@/lib/desktop-bridge-types';
import { emitDiagnosticBreadcrumb } from '@/lib/diagnostic-breadcrumb';
import {
  type DockSessionOrder,
  type DockSurface,
  readDockRestoreState,
  readWebDockSessionOrder,
  writeAgentsPanelLevel,
  writeDockSessionOrder,
} from '@/lib/dock-session-persistence';
import { matchesPrimaryModifier, type ShortcutPlatform } from '@/lib/keyboard-shortcuts';
import { subscribeLocalMenuAction } from '@/lib/local-menu-action-bus';
import type { NewSessionChoice } from '@/lib/new-session-choice';
import { isOverlayLayerOpen } from '@/lib/overlay-layers';
import { paneVisibilityStore } from '@/lib/pane-visibility-store';
import { RESTORE_SETTLE_TIMEOUT_MS } from '@/lib/restore-settle-timeout';
import { useChatHistorySide } from '@/lib/sidebar-side-store';
import { usePreferBareTerminal, writePreferBareTerminal } from '@/lib/terminal-new-tab-store';
import {
  parseStickyCliId,
  saveStickyAgent,
  terminalCliId,
  threadAgentId,
  useStickyAgent,
} from '@/lib/unified-agent-store';
import { openAgentSettings } from '@/lib/use-settings-route';
import { cn } from '@/lib/utils';
import { setViewMenuState } from '@/lib/view-menu-state-store';
import type { TerminalLaunchIntent, ThreadLaunchIntent } from './EditorPane';

const ThreadView = lazy(() =>
  import('@/components/acp/ThreadView').then((mod) => ({ default: mod.ThreadView })),
);

import { sendQueuedCommentsInThread, subscribeSendToOpenChat } from '@/comments/open-chat-send';
import { subscribeToPreferredSessionRequests } from './handoff/preferred-session-events';
import { notifySignInTerminalExited } from './handoff/sign-in-terminal-events';
import type { TerminalCommandId } from './handoff/terminal-command-events';
import {
  type ActiveTerminalInputDetail,
  subscribeToActiveTerminalInput,
} from './handoff/terminal-input-events';
import { requestTerminalLaunch } from './handoff/terminal-launch-events';
import { isBracketedPasteEnabled } from './handoff/terminal-paste-mode';
import { TerminalGate } from './TerminalGate';
import { TerminalNewChatButton } from './TerminalNewChatButton';
import {
  type SessionPanelEdge,
  type TerminalTabDescriptor,
  TerminalTabStrip,
} from './TerminalTabStrip';

interface BaseSessionDescriptor {
  readonly id: string;
  readonly ordinal: number;
}
interface TerminalSessionDescriptor extends BaseSessionDescriptor {
  readonly kind: 'terminal';
  readonly launch: TerminalLaunchIntent | null;
  readonly commandId: TerminalCommandId | null;
  readonly title: string | null;
  readonly customLabel: string | null;
  readonly adoptPtyId: string | null;
}
interface ThreadSessionDescriptor extends BaseSessionDescriptor {
  readonly kind: 'thread';
  readonly threadId: string;
}
type SessionDescriptor = TerminalSessionDescriptor | ThreadSessionDescriptor;

type SessionOpenProvenance = 'user' | 'restore-seed';

type AgentPaneLaunchRequest = {
  readonly agent: { source: 'registry' | 'custom'; id: string };
  readonly docName?: string | null;
  readonly titleHint?: string | null;
  readonly attachments?: readonly AttachmentPart[];
} & (
  | { readonly prompt?: string | null; readonly stageDraft?: never }
  | { readonly prompt?: never; readonly stageDraft: string | ThreadDraftContent }
);

type EmptyAgentLaunchState = 'idle' | 'launching' | 'deduped' | 'failed';

function applyReorder(
  current: readonly SessionDescriptor[],
  newOrderIds: readonly string[],
): SessionDescriptor[] | null {
  if (newOrderIds.length !== current.length) return null;
  const byId = new Map(current.map((session) => [session.id, session]));
  const next: SessionDescriptor[] = [];
  for (const id of newOrderIds) {
    const session = byId.get(id);
    if (session == null) return null;
    next.push(session);
  }
  if (next.every((session, index) => session === current[index])) return null;
  return next;
}

function makeSessionId(counter: number): string {
  return `terminal-session-${counter}`;
}

function escapeSelector(id: string): string {
  return typeof CSS !== 'undefined' && CSS.escape ? CSS.escape(id) : id;
}

function terminalSessionFocusSelector(id: string): string {
  return `[data-terminal-session="${escapeSelector(id)}"] .xterm-helper-textarea`;
}

function threadSessionFocusSelector(id: string): string {
  return `[data-session-id="${escapeSelector(id)}"] [data-testid="agent-thread-composer"]`;
}

function focusTerminalSession(id: string): boolean {
  if (id === '') return false;
  const terminal = document.querySelector<HTMLElement>(terminalSessionFocusSelector(id));
  terminal?.focus();
  return terminal != null && document.activeElement === terminal;
}

function threadTabFocusElement(id: string): HTMLElement | null {
  const safeId = typeof CSS !== 'undefined' && CSS.escape ? CSS.escape(id) : id;
  return document.querySelector<HTMLElement>(`[role="tab"][data-tab-id="${safeId}"]`);
}

function focusThreadSession(id: string): boolean {
  if (id === '') return false;
  const composer = document.querySelector<HTMLElement>(threadSessionFocusSelector(id));
  composer?.focus();
  if (composer != null && document.activeElement === composer) return true;
  threadTabFocusElement(id)?.focus();
  return false;
}

function focusSession(session: SessionDescriptor): boolean {
  if (session.kind === 'terminal') return focusTerminalSession(session.id);
  return focusThreadSession(session.id);
}

function fallbackSessionFocusElement(session: SessionDescriptor): HTMLElement | null {
  return session.kind === 'thread' ? threadTabFocusElement(session.id) : null;
}

function focusInsideHost(hostEl: HTMLElement | null): boolean {
  return hostEl?.contains(document.activeElement) ?? false;
}

function focusRemainsUsable(element: Element | null): boolean {
  return (
    element instanceof HTMLElement &&
    element !== document.body &&
    element.isConnected &&
    element.closest('[inert]') == null &&
    element.getClientRects().length > 0
  );
}

function focusAvailableButton(candidate: HTMLButtonElement | null): HTMLButtonElement | null {
  if (
    candidate == null ||
    candidate.disabled ||
    candidate.tabIndex < 0 ||
    !candidate.isConnected ||
    candidate.closest('[aria-disabled="true"], [hidden], [inert], [aria-hidden="true"]') != null
  ) {
    return null;
  }
  let current: HTMLElement | null = candidate;
  while (current != null) {
    const style = window.getComputedStyle(current);
    if (style.display === 'none' || style.visibility === 'hidden') return null;
    current = current.parentElement;
  }
  candidate.focus();
  return document.activeElement === candidate ? candidate : null;
}

function emptyAgentStateFallbackButton(hostEl: HTMLElement): HTMLButtonElement | null {
  return hostEl.querySelector<HTMLButtonElement>('[data-testid="terminal-new-chat"]');
}

export type SessionSurface = 'terminal-dock' | 'agents-panel' | 'terminal-window';

function chordTargetsHost(hostEl: HTMLElement | null, isWindow: boolean): boolean {
  return isWindow || focusInsideHost(hostEl);
}

type ThreadTabState = 'working' | 'needs-you' | 'ready' | 'stopped' | 'closed';

function threadTabState(info: ThreadInfo): ThreadTabState {
  if (info.archived === true) return 'closed';
  switch (info.status) {
    case 'installing':
    case 'spawning':
    case 'authenticating':
    case 'running':
      return 'working';
    case 'auth_required':
    case 'awaiting_permission':
      return 'needs-you';
    case 'ready':
      return 'ready';
    case 'error':
    case 'exited':
      return 'stopped';
    default: {
      const exhaustive: never = info.status;
      return exhaustive;
    }
  }
}

const THREAD_TAB_DOT_CLASSES: Record<ThreadTabState, string> = {
  working: 'bg-info animate-pulse',
  'needs-you': 'bg-warning',
  ready: 'bg-success',
  stopped: 'bg-destructive',
  closed: 'bg-muted-foreground',
};

function useThreadTabStatus(info: ThreadInfo): string {
  const { t } = useLingui();
  if (info.archived === true) return t`Not running`;
  switch (info.status) {
    case 'installing':
    case 'spawning':
      return t`Starting`;
    case 'authenticating':
      return t`Signing in`;
    case 'auth_required':
      return t`Needs you to sign in`;
    case 'awaiting_permission':
      return t`Waiting for your approval`;
    case 'running':
      return t`Working`;
    case 'ready':
      return t`Ready`;
    case 'error':
      return t`Something went wrong`;
    case 'exited':
      return t`Stopped`;
    default: {
      const exhaustive: never = info.status;
      return exhaustive;
    }
  }
}

function ThreadTabPeek({
  info,
  threadId,
  label,
}: {
  info: ThreadInfo;
  threadId: string;
  label: string;
}): ReactNode {
  const { t } = useLingui();
  const now = useActivityClock();
  const status = useThreadTabStatus(info);
  const unread = useAgentThreadUnread(threadId);
  const lastActivity = formatRelativeActivity(info.lastActivityAt, now);
  return (
    <span className="flex max-w-64 flex-col gap-0.5 text-start">
      <span className="break-words font-medium">{label}</span>
      <span>{status}</span>
      {unread ? <span>{t`New activity`}</span> : null}
      <span className="opacity-70">{t`Last activity ${lastActivity}`}</span>
    </span>
  );
}

function ThreadTabScreenReaderStatus({
  info,
  threadId,
}: {
  info: ThreadInfo;
  threadId: string;
}): ReactNode {
  const { t } = useLingui();
  const status = useThreadTabStatus(info);
  const unread = useAgentThreadUnread(threadId);
  return unread ? t`, ${status}, new activity` : t`, ${status}`;
}

function terminalTabIcon(): ReactNode {
  return (
    <SquareTerminalIcon className="size-3.5 shrink-0 text-muted-foreground" aria-hidden="true" />
  );
}

const THREAD_TINT_RINGS: readonly string[] = [
  'ring-identity-1/60',
  'ring-identity-2/60',
  'ring-identity-3/60',
  'ring-identity-4/60',
];

function threadTintClass(threadId: string): string {
  let hash = 5381;
  for (let i = 0; i < threadId.length; i++) {
    hash = ((hash << 5) + hash + threadId.charCodeAt(i)) >>> 0;
  }
  return THREAD_TINT_RINGS[hash % THREAD_TINT_RINGS.length] ?? 'ring-transparent';
}

function ThreadTabIcon({
  info,
  threadId,
}: {
  info: ThreadInfo | undefined;
  threadId: string;
}): ReactNode {
  const unread = useAgentThreadUnread(threadId);
  return (
    <span
      className={cn('relative inline-flex shrink-0 rounded-full ring-1', threadTintClass(threadId))}
    >
      <RegisteredAgentIcon
        agentId={info?.agent.id ?? ''}
        iconUrl={info?.agent.iconUrl}
        className="size-3.5"
      />
      {info != null ? (
        <span
          className={cn(
            '-right-0.5 -bottom-0.5 absolute size-1.5 rounded-full ring-1 ring-background',
            THREAD_TAB_DOT_CLASSES[threadTabState(info)],
            unread && threadTabState(info) === 'ready' && 'animate-pulse',
          )}
          data-thread-state={threadTabState(info)}
          aria-hidden="true"
        />
      ) : null}
    </span>
  );
}

interface SessionsHostSharedProps {
  readonly bridge: OkDesktopBridge | null;
  readonly terminalCapable?: boolean;
  readonly terminalPlacement?: TerminalPlacement;
  readonly onTerminalPlacementChange?: (placement: TerminalPlacement) => void;
  readonly terminalRestoreRevealNonce?: number;
  readonly visible: boolean;
  readonly wideVisible?: boolean;
  readonly onVisibleChange: (visible: boolean, reason?: 'session-close') => void;
  readonly onPreferredSessionHostReady?: () => void;
  readonly launch?: TerminalLaunchIntent | null;
  readonly commandLaunch?: { readonly id: TerminalCommandId; readonly nonce: number } | null;
  readonly threadLaunch?: ThreadLaunchIntent | null;
  readonly focusRevealRequestNonce?: number;
  readonly installedClis?: Partial<Record<TerminalCli, boolean>>;
  readonly container: HTMLElement | null;
  readonly isShowing: boolean;
  readonly revealFocusHold?: boolean;
  readonly onRequestEditorFocus: () => void;
}

type SessionsHostProps = SessionsHostSharedProps &
  (
    | {
        readonly surface: Extract<SessionSurface, 'agents-panel'>;
        readonly agentsVisibilityRestoreSettled: boolean;
      }
    | {
        readonly surface: Extract<SessionSurface, 'terminal-dock' | 'terminal-window'>;
        readonly agentsVisibilityRestoreSettled?: never;
      }
  );

const REVEAL_FOCUS_LANDING_TIMEOUT_MS = 5_000;

function closeHistory(
  setOpen: (open: boolean) => void,
  focus: 'always' | 'if-panel-focused' | 'never',
  panelId: string,
  toggleRef: RefObject<HTMLButtonElement | null>,
) {
  const shouldRestoreFocus =
    focus === 'always' ||
    (focus === 'if-panel-focused' &&
      document.getElementById(panelId)?.contains(document.activeElement) === true);
  setOpen(false);
  if (shouldRestoreFocus) queueMicrotask(() => toggleRef.current?.focus());
}

const MAX_HOST_STATE_REPORTS = 20;

export function SessionsHost({
  bridge,
  terminalCapable = false,
  surface,
  terminalPlacement = 'bottom',
  onTerminalPlacementChange,
  terminalRestoreRevealNonce = 0,
  visible,
  wideVisible = visible,
  onVisibleChange,
  onPreferredSessionHostReady,
  agentsVisibilityRestoreSettled,
  launch = null,
  commandLaunch = null,
  threadLaunch = null,
  focusRevealRequestNonce = 0,
  installedClis,
  container,
  isShowing,
  revealFocusHold = false,
  onRequestEditorFocus,
}: SessionsHostProps) {
  const { t } = useLingui();

  const isWindow = surface === 'terminal-window';
  const hostThreads = surface === 'agents-panel';
  const hostTerminals = !hostThreads;
  const terminalAvailable = hostTerminals && terminalCapable && bridge?.terminal != null;
  const edge: SessionPanelEdge = hostThreads ? 'right' : terminalPlacement;
  const persistSurface: DockSurface = hostThreads ? 'agents' : 'terminal';
  const persistedPanelLevel = hostThreads && wideVisible;
  const persistsOrder = !isWindow;
  const shortcutPlatform: ShortcutPlatform | undefined =
    bridge?.platform === 'darwin'
      ? 'mac'
      : bridge?.platform === 'linux' || bridge?.platform === 'win32'
        ? 'windowsLinux'
        : undefined;

  const [hostEl] = useState<HTMLDivElement | null>(() => {
    if (typeof document === 'undefined') return null;
    const el = document.createElement('div');
    el.className = 'flex min-h-0 flex-1 flex-col overflow-hidden';
    return el;
  });

  const [attachedHostEl, setAttachedHostEl] = useState<HTMLDivElement | null>(null);
  const hostStateReportsRef = useRef(0);

  useLayoutEffect(() => {
    if (hostEl == null) return;
    return () => hostEl.remove();
  }, [hostEl]);

  useLayoutEffect(() => {
    if (hostEl == null || container == null) return;
    if (hostEl.parentElement !== container) container.appendChild(hostEl);
    setAttachedHostEl(hostEl);
  }, [hostEl, container]);

  const [historyOpen, setHistoryOpen] = useState(false);
  const chatHistorySide = useChatHistorySide();
  const { mode: historyMode, remeasure: remeasureHistoryMode } = useHistoryPresentationMode(
    container,
    hostThreads,
  );
  const historyPanelId = useId();
  const historyToggleRef = useRef<HTMLButtonElement>(null);
  const previousHistoryModeRef = useRef(historyMode);

  useLayoutEffect(() => {
    const previousMode = previousHistoryModeRef.current;
    previousHistoryModeRef.current = historyMode;
    if (historyOpen && previousMode === 'docked' && historyMode === 'cover') {
      closeHistory(setHistoryOpen, 'if-panel-focused', historyPanelId, historyToggleRef);
    }
  }, [historyMode, historyOpen, historyPanelId]);
  const canRehydrate = hostTerminals && typeof bridge?.terminal?.list === 'function';
  const restoresDesktopDockOrder =
    hostThreads && typeof bridge?.terminal?.getDockState === 'function';

  const coldSeedTerminal = !canRehydrate && terminalAvailable && visible;

  const [webReloadOrder] = useState<DockSessionOrder | null>(() => {
    if (canRehydrate || !persistsOrder || coldSeedTerminal) return null;
    return typeof bridge?.terminal?.getDockState === 'function'
      ? null
      : readWebDockSessionOrder(persistSurface);
  });
  const reloadOrderRef = useRef<readonly string[]>(webReloadOrder?.order ?? []);
  const pendingActiveKeyRef = useRef<string | null>(webReloadOrder?.activeKey ?? null);
  const [sessions, setSessions] = useState<readonly SessionDescriptor[]>(() =>
    coldSeedTerminal
      ? [
          {
            kind: 'terminal',
            id: makeSessionId(1),
            launch,
            commandId: null,
            title: null,
            customLabel: null,
            ordinal: 1,
            adoptPtyId: null,
          },
        ]
      : [],
  );
  const [activeSessionId, setActiveSessionId] = useState(() =>
    coldSeedTerminal ? makeSessionId(1) : '',
  );
  const [rehydrationSettled, setRehydrationSettled] = useState(
    !canRehydrate && !restoresDesktopDockOrder,
  );
  const rehydratedRef = useRef(false);
  const activeSessionIdRef = useRef(activeSessionId);
  const sessionsRef = useRef(sessions);
  const sessionCounterRef = useRef(coldSeedTerminal ? 1 : 0);
  const lastHandledLaunchNonceRef = useRef<number | null>(
    coldSeedTerminal && launch ? launch.nonce : null,
  );
  const lastHandledThreadNonceRef = useRef<number | null>(null);
  const settingsShownForNonceRef = useRef<number | null>(null);
  const seedOwedRef = useRef(false);
  const seededThreadLaunchRef = useRef<{
    agentKey: string;
    connectionGeneration: number;
  } | null>(null);
  const seededThreadIdRef = useRef<string | null>(null);
  const initialVisibleSeedAttemptedRef = useRef(false);
  const [emptyAgentLaunchState, setEmptyAgentLaunchState] = useState<EmptyAgentLaunchState>('idle');
  const pendingAgentLaunchRequestRef = useRef<AgentPaneLaunchRequest | null>(null);
  const retryAgentLaunchRequestRef = useRef<AgentPaneLaunchRequest | null>(null);
  const emptyAgentActionButtonRef = useRef<HTMLButtonElement>(null);
  const revealFocusRef = useRef<{ pendingThreadId: string | null } | null>(null);
  const revealFocusWasShowingRef = useRef(false);
  const retryFocusRequestedRef = useRef(false);
  const restoreAbandonedRef = useRef(false);
  const restoreUnreadRef = useRef(false);
  const userArrangedRef = useRef(false);
  const rosterPopulatedRef = useRef(false);
  const persistDeclineLoggedRef = useRef(false);
  const persistSuppressedRef = useRef<() => boolean>(() => false);
  const lastHandledCommandNonceRef = useRef<number | null>(null);
  const prevVisibleRef = useRef(isWindow ? false : visible);
  const revealFocusRequestedRef = useRef(false);
  const revealFocusRequestNonceRef = useRef<number | null>(null);
  useLayoutEffect(() => {
    if (revealFocusRequestNonceRef.current === focusRevealRequestNonce) return;
    revealFocusRequestNonceRef.current = focusRevealRequestNonce;
    if (focusRevealRequestNonce > 0) revealFocusRequestedRef.current = true;
  }, [focusRevealRequestNonce]);
  const consumedRestoreRevealNonceRef = useRef(terminalRestoreRevealNonce);
  const ptyIdBySessionRef = useRef(new Map<string, string>());
  const stripLaunchNonceRef = useRef(0);

  const revealFocusHoldRef = useRef(revealFocusHold);
  useLayoutEffect(() => {
    revealFocusHoldRef.current = revealFocusHold;
  }, [revealFocusHold]);

  useLayoutEffect(() => {
    const revealing = isShowing && !revealFocusWasShowingRef.current;
    revealFocusWasShowingRef.current = isShowing;
    if (revealing) revealFocusRef.current = { pendingThreadId: null };
    if (!isShowing) revealFocusRef.current = null;
  }, [isShowing]);

  const openThreadTabs = useOpenAgentThreadTabs();
  const agentThreads = useAgentThreads();
  const threadScope = useAgentThreadScope();
  const threadConnection = useAgentThreadConnection();
  useEffect(() => {
    void threadScope;
    initialVisibleSeedAttemptedRef.current = false;
    pendingAgentLaunchRequestRef.current = null;
    retryAgentLaunchRequestRef.current = null;
    retryFocusRequestedRef.current = false;
    setEmptyAgentLaunchState('idle');
  }, [threadScope]);
  useEffect(() => {
    if (!retryFocusRequestedRef.current) return;
    if (emptyAgentLaunchState !== 'failed' && emptyAgentLaunchState !== 'deduped') return;
    const frame = window.requestAnimationFrame(() => {
      retryFocusRequestedRef.current = false;
      emptyAgentActionButtonRef.current?.focus();
    });
    return () => window.cancelAnimationFrame(frame);
  }, [emptyAgentLaunchState]);
  useEffect(() => {
    if (hostThreads && !visible && historyOpen)
      closeHistory(setHistoryOpen, 'never', historyPanelId, historyToggleRef);
  }, [historyOpen, historyPanelId, hostThreads, visible]);
  const threadConnectionDown = threadConnection === 'connecting' || threadConnection === 'closed';
  const agentCatalog = useAgentCatalogQuery(hostThreads);
  const registeredAgents = useRegisteredAgents();
  const enabledOverrides = useEnabledOverrides();
  const enabledRegisteredAgents = registeredAgents.filter((agent) =>
    isInAppAgentEnabled(enabledOverrides, agent.source, agent.id, true, agent.supported),
  );
  const defaultRegisteredAgent = useDefaultRegisteredAgent();
  const effectiveDefaultAgent = pickEffectiveDefaultAgent(
    enabledRegisteredAgents,
    defaultRegisteredAgent,
  );
  const registeredAgentKeys = new Set(
    registeredAgents.map((agent) => `${agent.source}:${agent.id}`),
  );
  const detectedAgentRegistrationPending = detectedHarnessAgents(
    agentCatalog.data?.agents ?? [],
  ).some((agent) => !registeredAgentKeys.has(`${agent.source}:${agent.id}`));
  const refetchAgentCatalog = () => {
    void agentCatalog.refetch();
  };
  const agentCatalogFailed = agentCatalog.isError;
  const agentOptionsSettled = !agentCatalog.isLoading && !detectedAgentRegistrationPending;
  const liveThreadCount = openThreadTabs.filter((info) => info.archived !== true).length;
  const threadInfoById = new Map(openThreadTabs.map((info) => [info.threadId, info]));
  const openThreadIds = new Set(threadInfoById.keys());

  function selectHistoryThread(threadId: string) {
    noteUserArrangement();
    pendingActiveKeyRef.current = null;
    const openSession = sessionsRef.current.find(
      (session) => session.kind === 'thread' && session.threadId === threadId,
    );
    if (openSession != null) {
      setActiveSessionId(openSession.id);
      queueMicrotask(() => focusSession(openSession));
      return;
    }
    getAgentThreadClient().openArchivedThread(threadId);
  }

  function dismissHistory(reason: 'explicit' | 'selection') {
    closeHistory(
      setHistoryOpen,
      reason === 'explicit' ? 'always' : 'never',
      historyPanelId,
      historyToggleRef,
    );
  }

  function setHistoryOpenForPane(open: boolean) {
    if (open) remeasureHistoryMode();
    setHistoryOpen(open);
  }

  function dismissCoveringHistory() {
    if (hostThreads && historyOpen && historyMode === 'cover')
      closeHistory(setHistoryOpen, 'never', historyPanelId, historyToggleRef);
  }

  function dockPersistSuppressed(): boolean {
    if (!persistsOrder) return true;
    if (!rehydrationSettled) return true;
    if (restoreUnreadRef.current && !userArrangedRef.current) {
      if (!persistDeclineLoggedRef.current) {
        persistDeclineLoggedRef.current = true;
        console.warn(
          `[${hostThreads ? 'agents' : 'terminal'}] dock persistence withheld: the restore did not complete, so the saved tab set is left untouched`,
        );
      }
      return true;
    }
    return false;
  }

  function persistDockOrderNow() {
    if (dockPersistSuppressed()) return;
    const ptyMap = ptyIdBySessionRef.current;
    const order = sessionsRef.current
      .map((session) => computePersistKey(session, ptyMap))
      .filter((key): key is string => key != null);
    const active = sessionsRef.current.find((s) => s.id === activeSessionIdRef.current);
    const activeKey = active != null ? computePersistKey(active, ptyMap) : null;
    const snapshot = buildTerminalRestartSnapshot(sessionsRef.current, activeSessionIdRef.current);
    if (hostThreads) {
      writeDockSessionOrder(bridge, 'agents', { order, activeKey }, snapshot);
      writeAgentsPanelLevel(bridge, wideVisible);
    } else {
      writeDockSessionOrder(bridge, 'terminal', { order, activeKey }, snapshot);
    }
  }

  function setSessionPtyId(id: string, ptyId: string | null) {
    if (ptyId === null) {
      ptyIdBySessionRef.current.delete(id);
      publishReusableSessionFrom(sessionsRef.current, activeSessionIdRef.current);
      return;
    }
    ptyIdBySessionRef.current.set(id, ptyId);
    publishReusableSessionFrom(sessionsRef.current, activeSessionIdRef.current);
    const session = sessionsRef.current.find((s) => s.id === id);
    if (session != null && session.kind === 'terminal') {
      bridge?.terminal?.setMeta?.(ptyId, {
        ordinal: session.ordinal,
        customLabel: session.customLabel,
      });
    }
    persistDockOrderNow();
  }

  function openSession(
    launchForSession: TerminalLaunchIntent | null,
    commandForSession: TerminalCommandId | null = null,
    provenance: SessionOpenProvenance,
  ) {
    if (provenance === 'user') noteUserArrangement();
    pendingActiveKeyRef.current = null;
    sessionCounterRef.current += 1;
    const id = makeSessionId(sessionCounterRef.current);
    setSessions((prev) => [
      ...prev,
      {
        kind: 'terminal',
        id,
        launch: launchForSession,
        commandId: commandForSession,
        title: null,
        customLabel: null,
        ordinal: sessionCounterRef.current,
        adoptPtyId: null,
      },
    ]);
    setActiveSessionId(id);
  }

  const stickyAgentId = useStickyAgent();
  const preferBareTerminal = usePreferBareTerminal();

  const selection = resolveLauncherSelection({
    sticky: stickyAgentId,
    effectiveThreadAgent: effectiveDefaultAgent,
    enabledClis: enabledTerminalClis(enabledOverrides, installedClis ?? {}),
    enabledDesktopTargets: [],
    installedClis: installedClis ?? {},
    terminalAvailable,
    threadsAvailable: hostThreads,
    desktopSelectable: false,
    preferBareTerminal,
    bareTerminalFallback: true,
  });
  const pickedCli = parseStickyCliId(stickyAgentId);
  const newSessionChoice: NewSessionChoice =
    selection.kind === 'thread'
      ? { kind: 'agent', agent: selection.agent }
      : selection.kind === 'cli'
        ? selection.cli === pickedCli
          ? { kind: 'cli', cli: selection.cli }
          : { kind: 'terminal' }
        : selection.kind === 'terminal'
          ? { kind: 'terminal' }
          : { kind: 'agent', agent: null };

  function openNewChatSession(cli: TerminalCli, provenance: SessionOpenProvenance) {
    stripLaunchNonceRef.current += 1;
    openSession({ prompt: null, cli, nonce: stripLaunchNonceRef.current }, null, provenance);
  }

  function launchAgentForPane(
    request: AgentPaneLaunchRequest,
    onCreated?: (info: ThreadInfo) => void,
  ) {
    const {
      agent,
      prompt = null,
      docName = null,
      titleHint = null,
      stageDraft = null,
      attachments,
    } = request;
    const tracksEmptyPane = hostThreads && sessionsRef.current.length === 0;
    const previousPendingRequest = pendingAgentLaunchRequestRef.current;
    if (tracksEmptyPane) {
      pendingAgentLaunchRequestRef.current = request;
      setEmptyAgentLaunchState('launching');
    }
    return launchAgentThread(
      { source: agent.source, id: agent.id },
      prompt,
      docName,
      titleHint,
      stageDraft,
      attachments,
      onCreated,
    ).then((outcome) => {
      if (outcome === 'deduped') {
        toast.error(t`Already starting a chat with this agent — try again in a moment.`);
      }
      if (
        !tracksEmptyPane ||
        sessionsRef.current.length > 0 ||
        pendingAgentLaunchRequestRef.current !== request
      )
        return outcome;
      switch (outcome) {
        case 'failed':
          pendingAgentLaunchRequestRef.current = null;
          retryAgentLaunchRequestRef.current = request;
          setEmptyAgentLaunchState('failed');
          return outcome;
        case 'deduped':
          if (previousPendingRequest !== null) {
            pendingAgentLaunchRequestRef.current = previousPendingRequest;
            setEmptyAgentLaunchState('launching');
          } else {
            pendingAgentLaunchRequestRef.current = null;
            retryAgentLaunchRequestRef.current = request;
            setEmptyAgentLaunchState('deduped');
          }
          return outcome;
        case 'started':
          return outcome;
        default:
          return assertNeverThreadLaunchOutcome(outcome);
      }
    });
  }

  function retryFailedAgentLaunch() {
    dismissCoveringHistory();
    retryFocusRequestedRef.current = true;
    const request = retryAgentLaunchRequestRef.current;
    if (request === null) {
      launchSelectedNewTab();
      return;
    }
    void launchAgentForPane(request);
  }

  function launchSelectedNewTab() {
    dismissCoveringHistory();
    if (newSessionChoice.kind === 'terminal') openSession(null, null, 'user');
    else if (newSessionChoice.kind === 'cli') openNewChatSession(newSessionChoice.cli, 'user');
    else if (newSessionChoice.kind === 'agent' && newSessionChoice.agent != null)
      void launchAgentForPane({ agent: newSessionChoice.agent });
    else openAgentSettings();
  }

  function seedOnReveal(): boolean {
    if (hostThreads) {
      if (newSessionChoice.kind !== 'agent' || newSessionChoice.agent == null) return false;
      const agent = newSessionChoice.agent;
      const seededLaunch = {
        agentKey: `${agent.source}:${agent.id}`,
        connectionGeneration: getAgentThreadClient().getConnectionGeneration(),
      };
      seededThreadIdRef.current = null;
      seededThreadLaunchRef.current = seededLaunch;
      void launchAgentForPane({ agent }, (info) => {
        if (seededThreadLaunchRef.current !== seededLaunch) return;
        seededThreadIdRef.current = info.threadId;
        seededThreadLaunchRef.current = null;
      }).then((outcome) => {
        if (outcome !== 'started' && seededThreadLaunchRef.current === seededLaunch)
          seededThreadLaunchRef.current = null;
      });
      return true;
    }
    if (newSessionChoice.kind === 'terminal') openSession(null, null, 'restore-seed');
    else if (newSessionChoice.kind === 'cli')
      openNewChatSession(newSessionChoice.cli, 'restore-seed');
    return true;
  }

  const askAiSelection = resolveLauncherSelection({
    sticky: stickyAgentId,
    effectiveThreadAgent: effectiveDefaultAgent,
    enabledClis: enabledTerminalClis(enabledOverrides, installedClis ?? {}),
    enabledDesktopTargets: [],
    installedClis: installedClis ?? {},
    terminalAvailable: terminalCapable,
    threadsAvailable: !isWindow,
    desktopSelectable: false,
    preferBareTerminal: false,
    bareTerminalFallback: false,
  });

  const agentsTargetedSelection = resolveLauncherSelection({
    sticky: stickyAgentId,
    effectiveThreadAgent: effectiveDefaultAgent,
    enabledClis: [],
    enabledDesktopTargets: [],
    installedClis: {},
    terminalAvailable: false,
    threadsAvailable: hostThreads,
    desktopSelectable: false,
    preferBareTerminal: false,
    bareTerminalFallback: false,
  });

  const preferredSessionSelection = usePreferredSessionSelection({
    installedClis: installedClis ?? {},
    terminalAvailable: terminalCapable,
    threadsAvailable: !isWindow,
  });

  function claimsSessionKind(kind: LauncherSelection['kind']): boolean {
    if (isWindow) return true;
    return LAUNCHER_KIND_PANE[kind] === (hostThreads ? 'agents' : 'terminal');
  }

  function publishReusableSessionFrom(sessionList: readonly SessionDescriptor[], activeId: string) {
    const active = sessionList.find((s) => s.id === activeId);
    if (active == null) {
      publishReusableSession(persistSurface, null);
      return;
    }
    if (active.kind === 'thread') {
      const info = threadInfoById.get(active.threadId);
      publishReusableSession(persistSurface, {
        id: active.id,
        kind: 'thread',
        label: info?.agent.name ?? t`the open agent`,
        agentId: info?.agent.id ?? '',
        iconUrl: info?.agent.iconUrl,
      });
      return;
    }
    const livePtyId = ptyIdBySessionRef.current.get(active.id);
    const cli = active.launch?.cli;
    if (livePtyId == null || bridge?.terminal == null || cli == null) {
      publishReusableSession(persistSurface, null);
      return;
    }
    publishReusableSession(persistSurface, {
      id: active.id,
      kind: 'terminal',
      label: TERMINAL_CLIS[cli].displayName,
      cli,
    });
  }

  // biome-ignore lint/correctness/useExhaustiveDependencies: publishes from the state it is passed; `openThreadTabs` is a label input, read via threadInfoById
  useEffect(() => {
    publishReusableSessionFrom(sessions, activeSessionId);
  }, [activeSessionId, sessions, openThreadTabs]);

  function requestHostPaneReveal() {
    if (!visible) onVisibleChange(true);
    else if (hostThreads) paneVisibilityStore.request('agents', true);
  }

  function revealForReuse() {
    dismissCoveringHistory();
    requestHostPaneReveal();
  }

  function dispatchAskAi({ text, newTab, submit, target }: ActiveTerminalInputDetail) {
    const selection = target === 'agents' ? agentsTargetedSelection : askAiSelection;
    if (target === 'agents') {
      if (!hostThreads) return;
    } else if (!claimsSessionKind(selection.kind)) return;
    requestHostPaneReveal();
    dismissCoveringHistory();
    const activeId = activeSessionIdRef.current;
    const active = sessionsRef.current.find((s) => s.id === activeId);
    if (!newTab && active != null) {
      if (active.kind === 'thread') {
        stageThreadDraft(active.threadId, text);
        queueMicrotask(() => focusSession(active));
        return;
      }
      const livePtyId = ptyIdBySessionRef.current.get(active.id);
      const terminal = bridge?.terminal;
      if (livePtyId != null && terminal != null && active.launch?.cli != null) {
        terminal.input(
          livePtyId,
          buildTerminalInputBytes(text, isBracketedPasteEnabled(livePtyId)),
        );
        revealForReuse();
        queueMicrotask(() => focusTerminalSession(activeId));
        return;
      }
    }
    if (selection.kind === 'thread') {
      const agent = { source: selection.agent.source, id: selection.agent.id };
      void (submit
        ? launchAgentForPane({ agent, prompt: text })
        : launchAgentForPane({ agent, stageDraft: text }));
    } else if (selection.kind === 'cli') {
      requestTerminalLaunch(text, selection.cli, { stage: !submit });
    } else {
      openAgentSettings();
    }
  }

  function pickNewChatCli(cli: TerminalCli) {
    dismissCoveringHistory();
    writePreferBareTerminal(false);
    saveStickyAgent(terminalCliId(cli));
    openNewChatSession(cli, 'user');
  }

  function pickNewChatTerminal() {
    dismissCoveringHistory();
    writePreferBareTerminal(true);
    openSession(null, null, 'user');
  }

  function unsentActiveThread(): { threadId: string; agent: ThreadInfo['agent'] } | null {
    const active = sessionsRef.current.find((session) => session.id === activeSessionIdRef.current);
    if (active == null || active.kind !== 'thread') return null;
    const info = threadInfoById.get(active.threadId);
    if (info === undefined || info.archived === true) return null;
    const model = getAgentThreadClient().getThreadModel(active.threadId);
    if (model === null) return null;
    if (threadHasUserMessage(model)) return null;
    return { threadId: active.threadId, agent: info.agent };
  }

  function pickNewChatAgent(agent: RegisteredAgent) {
    const unsent = unsentActiveThread();
    if (unsent !== null && switchingThreads.has(unsent.threadId)) return;
    dismissCoveringHistory();
    registerAgent(agent);
    writePreferBareTerminal(false);
    saveStickyAgent(threadAgentId(agent));
    if (unsent === null || (unsent.agent.source === agent.source && unsent.agent.id === agent.id)) {
      void launchAgentForPane({ agent });
      return;
    }
    const draft = readThreadDraft(unsent.threadId);
    if (draft?.uploadsPending === true) {
      void launchAgentForPane({ agent });
      return;
    }
    const request: AgentPaneLaunchRequest =
      draft !== null && !isEmptyThreadDraft(draft) && draft.doc !== null
        ? { agent, stageDraft: { doc: draft.doc, attachments: draft.attachments } }
        : { agent };
    const switchingFrom = unsent.threadId;
    setSwitchingThreads((previous) => new Set(previous).add(switchingFrom));
    void launchAgentForPane(request).then((outcome) => {
      setSwitchingThreads((previous) => {
        if (!previous.has(switchingFrom)) return previous;
        const next = new Set(previous);
        next.delete(switchingFrom);
        return next;
      });
      if (outcome === 'started') getAgentThreadClient().closeThread(switchingFrom);
    });
  }

  function setSessionTitle(id: string, title: string) {
    const next = title.trim() === '' ? null : title.trim();
    setSessions((prev) => {
      if (
        !prev.some(
          (session) => session.id === id && session.kind === 'terminal' && session.title !== next,
        )
      )
        return prev;
      return prev.map((session) =>
        session.id === id && session.kind === 'terminal' ? { ...session, title: next } : session,
      );
    });
  }

  function renameSession(id: string, label: string) {
    const session = sessionsRef.current.find((s) => s.id === id);
    if (session == null) return;
    if (session.kind === 'thread') {
      getAgentThreadClient().renameThread(session.threadId, label);
      return;
    }
    const next = label.trim() === '' ? null : label.trim();
    setSessions((prev) => {
      if (!prev.some((s) => s.id === id && s.kind === 'terminal' && s.customLabel !== next))
        return prev;
      return prev.map((s) =>
        s.id === id && s.kind === 'terminal' ? { ...s, customLabel: next } : s,
      );
    });
    const ptyId = ptyIdBySessionRef.current.get(id);
    if (ptyId != null) bridge?.terminal?.setMeta?.(ptyId, { customLabel: next });
  }

  function sessionLabel(session: SessionDescriptor): string {
    if (session.kind === 'terminal') {
      return session.customLabel ?? session.title ?? t`Terminal ${session.ordinal}`;
    }
    return threadInfoById.get(session.threadId)?.title ?? t`Agent`;
  }

  const dragActiveRef = useRef(false);
  const announcerRef = useRef<HTMLSpanElement>(null);
  const announceTimerRef = useRef<number | null>(null);

  function noteUserArrangement() {
    if (persistDeclineLoggedRef.current) {
      console.warn(
        `[${hostThreads ? 'agents' : 'terminal'}] dock persistence resumed: a user arrangement established the tab set the restore did not`,
      );
    }
    userArrangedRef.current = true;
    persistDeclineLoggedRef.current = false;
  }

  function reorderSessions(newOrderIds: readonly string[]) {
    if (applyReorder(sessionsRef.current, newOrderIds) != null) noteUserArrangement();
    setSessions((prev) => applyReorder(prev, newOrderIds) ?? prev);
    const orderedPtyIds = newOrderIds
      .map((id) => ptyIdBySessionRef.current.get(id))
      .filter((ptyId): ptyId is string => ptyId != null);
    if (orderedPtyIds.length > 0) bridge?.terminal?.setOrder?.(orderedPtyIds);
  }

  function moveActiveSession(
    direction: -1 | 1,
  ): { label: string; position: number; total: number } | null {
    const current = sessionsRef.current;
    const from = current.findIndex((session) => session.id === activeSessionIdRef.current);
    if (from < 0) return null;
    const to = from + direction;
    if (to < 0 || to >= current.length) return null;
    const ids = current.map((session) => session.id);
    const [movedId] = ids.splice(from, 1);
    ids.splice(to, 0, movedId);
    reorderSessions(ids);
    return { label: sessionLabel(current[from]), position: to + 1, total: current.length };
  }
  function launchPreferredSession() {
    if (!claimsSessionKind(preferredSessionSelection.kind)) return;
    requestHostPaneReveal();
    launchSelectedNewTab();
  }

  const noteUserArrangementRef = useRef(noteUserArrangement);
  const moveActiveSessionRef = useRef(moveActiveSession);
  const openSessionRef = useRef(openSession);
  const seedOnRevealRef = useRef(seedOnReveal);
  const launchAgentForPaneRef = useRef(launchAgentForPane);
  const dispatchAskAiRef = useRef(dispatchAskAi);
  const revealForReuseRef = useRef(revealForReuse);
  const launchPreferredSessionRef = useRef(launchPreferredSession);
  const preferredSessionKindRef = useRef(preferredSessionSelection.kind);

  function closeSession(id: string) {
    const current = sessionsRef.current;
    const index = current.findIndex((session) => session.id === id);
    if (index === -1) return;
    noteUserArrangement();
    const session = current[index];
    notifySignInExitOnce(session);
    const isLast = current.length === 1;
    pendingActiveKeyRef.current = null;
    if (id === activeSessionIdRef.current) {
      const neighbor = current[index - 1] ?? current[index + 1];
      const neighborId = neighbor?.id ?? '';
      setActiveSessionId(neighborId);
      if (neighbor != null) queueMicrotask(() => focusSession(neighbor));
    }
    if (session.kind === 'thread') {
      getAgentThreadClient().closeThread(session.threadId);
    } else {
      setSessions(current.filter((s) => s.id !== id));
    }
    if (isLast) {
      onVisibleChange(false, 'session-close');
      onRequestEditorFocus();
    }
  }
  const closeActiveRef = useRef(() => {});
  const signInExitNotifiedRef = useRef(new Set<string>());
  function notifySignInExitOnce(session: (typeof sessionsRef.current)[number] | undefined) {
    if (session == null || session.kind !== 'terminal') return;
    const threadId = session.launch?.signInThreadId;
    if (threadId === undefined || signInExitNotifiedRef.current.has(session.id)) return;
    signInExitNotifiedRef.current.add(session.id);
    notifySignInTerminalExited(threadId);
  }
  const [switchingThreads, setSwitchingThreads] = useState<ReadonlySet<string>>(() => new Set());

  useEffect(() => {
    persistSuppressedRef.current = dockPersistSuppressed;
    openSessionRef.current = openSession;
    seedOnRevealRef.current = seedOnReveal;
    launchAgentForPaneRef.current = launchAgentForPane;
    dispatchAskAiRef.current = dispatchAskAi;
    revealForReuseRef.current = revealForReuse;
    launchPreferredSessionRef.current = launchPreferredSession;
    preferredSessionKindRef.current = preferredSessionSelection.kind;
    noteUserArrangementRef.current = noteUserArrangement;
    moveActiveSessionRef.current = moveActiveSession;
    activeSessionIdRef.current = activeSessionId;
    sessionsRef.current = sessions;
    if (sessions.length > 0) rosterPopulatedRef.current = true;
    closeActiveRef.current = () => {
      const active = sessionsRef.current.find((s) => s.id === activeSessionIdRef.current);
      if (active?.kind === 'terminal') {
        closeSession(active.id);
        return;
      }
      const lastTerminal = [...sessionsRef.current].reverse().find((s) => s.kind === 'terminal');
      if (lastTerminal != null) closeSession(lastTerminal.id);
    };
  });

  useEffect(() => {
    if (sessions.length === 0) return;
    pendingAgentLaunchRequestRef.current = null;
    retryAgentLaunchRequestRef.current = null;
    retryFocusRequestedRef.current = false;
    setEmptyAgentLaunchState('idle');
  }, [sessions.length]);

  const initialRosterThreadIds = useInitialRosterThreadIds();

  useEffect(() => {
    if (!persistsOrder) return;
    if (!rehydrationSettled) return;
    if (persistSuppressedRef.current()) return;
    if (
      hostThreads &&
      sessions.length === 0 &&
      !rosterPopulatedRef.current &&
      (initialRosterThreadIds === null || initialRosterThreadIds.size > 0)
    ) {
      writeAgentsPanelLevel(bridge, persistedPanelLevel);
      return;
    }
    const ptyMap = ptyIdBySessionRef.current;
    const order = sessions
      .map((session) => computePersistKey(session, ptyMap))
      .filter((key): key is string => key != null);
    const active = sessions.find((s) => s.id === activeSessionId);
    const activeKey = active != null ? computePersistKey(active, ptyMap) : null;
    const snapshot = buildTerminalRestartSnapshot(sessions, activeSessionId);
    if (hostThreads) {
      writeDockSessionOrder(bridge, 'agents', { order, activeKey }, snapshot);
      writeAgentsPanelLevel(bridge, persistedPanelLevel);
    } else {
      writeDockSessionOrder(bridge, 'terminal', { order, activeKey }, snapshot);
    }
  }, [
    sessions,
    activeSessionId,
    persistsOrder,
    bridge,
    rehydrationSettled,
    persistedPanelLevel,
    hostThreads,
    initialRosterThreadIds,
  ]);

  useEffect(() => {
    if (!hostThreads) return;
    const openIds = new Set(openThreadTabs.map((info) => info.threadId));
    const current = sessionsRef.current;
    const knownThreadIds = new Set(
      current
        .filter((s): s is ThreadSessionDescriptor => s.kind === 'thread')
        .map((s) => s.threadId),
    );
    const additions: ThreadSessionDescriptor[] = [];
    for (const info of openThreadTabs) {
      if (knownThreadIds.has(info.threadId)) continue;
      sessionCounterRef.current += 1;
      additions.push({
        kind: 'thread',
        id: info.threadId,
        threadId: info.threadId,
        ordinal: sessionCounterRef.current,
      });
    }
    const removedAny = current.some((s) => s.kind === 'thread' && !openIds.has(s.threadId));
    if (additions.length === 0 && !removedAny) return;
    setSessions((prev) => {
      const kept = prev.filter((s) => s.kind !== 'thread' || openIds.has(s.threadId));
      const keptThreadIds = new Set(
        kept
          .filter((s): s is ThreadSessionDescriptor => s.kind === 'thread')
          .map((s) => s.threadId),
      );
      const fresh = additions.filter((a) => !keptThreadIds.has(a.threadId));
      const ptyMap = ptyIdBySessionRef.current;
      const next =
        fresh.length > 0
          ? placeSessionAdditions(kept, fresh, reloadOrderRef.current, (s) =>
              computePersistKey(s, ptyMap),
            )
          : kept;
      if (next.length === prev.length && next.every((s, i) => s === prev[i])) return prev;
      return next;
    });
  }, [openThreadTabs, hostThreads]);

  const prevOpenThreadIdsRef = useRef<readonly string[]>([]);
  useEffect(() => {
    if (!hostThreads) return;
    const ids = openThreadTabs.map((info) => info.threadId);
    const previous = prevOpenThreadIdsRef.current;
    prevOpenThreadIdsRef.current = ids;
    if (pendingActiveKeyRef.current != null) return;
    const added = ids.filter((id) => !previous.includes(id));
    const newest = added[added.length - 1];
    if (newest != null) {
      setActiveSessionId(newest);
      if (revealFocusRef.current != null) {
        revealFocusRef.current.pendingThreadId = newest;
      } else {
        queueMicrotask(() => focusThreadSession(newest));
      }
    }
  }, [openThreadTabs, hostThreads]);

  const liveThreadIds = openThreadTabs
    .filter((info) => info.archived !== true)
    .map((info) => info.threadId);
  const prevLiveThreadIdsRef = useRef<readonly string[]>(
    initialRosterThreadIds === null ? liveThreadIds : [...initialRosterThreadIds],
  );
  const initialRosterWasUnknownRef = useRef(initialRosterThreadIds === null);
  useEffect(() => {
    if (!hostThreads) return;
    if (!agentsVisibilityRestoreSettled) return;
    const previous = prevLiveThreadIdsRef.current;
    prevLiveThreadIdsRef.current = liveThreadIds;
    const rosterWasUnknown = initialRosterWasUnknownRef.current;
    const rosterIsKnown = initialRosterThreadIds !== null;
    initialRosterWasUnknownRef.current = !rosterIsKnown;
    const added =
      rosterWasUnknown && rosterIsKnown
        ? liveThreadIds.filter((id) => !initialRosterThreadIds.has(id))
        : liveThreadIds.filter((id) => !previous.includes(id));
    if (added.length === 0) return;
    const seededLaunch = seededThreadLaunchRef.current;
    const seededThreadId = added.find((id) => {
      if (id === seededThreadIdRef.current) return true;
      if (
        seededLaunch === null ||
        seededLaunch.connectionGeneration !== getAgentThreadClient().getConnectionGeneration()
      )
        return false;
      const info = openThreadTabs.find((thread) => thread.threadId === id);
      return (
        initialRosterThreadIds?.has(id) !== true &&
        info !== undefined &&
        `${info.agent.source}:${info.agent.id}` === seededLaunch.agentKey
      );
    });
    if (seededThreadId !== undefined) {
      seededThreadIdRef.current = seededThreadId;
      seededThreadLaunchRef.current = null;
    }
    if (visible) return;
    const newArrival = added.filter((id) => id !== seededThreadId);
    if (newArrival.length === 0) return;
    const absorbsReloadSnapshot = newArrival.every(
      (id) => initialRosterThreadIds?.has(id) === true,
    );
    if (!absorbsReloadSnapshot) onVisibleChange(true);
  }, [
    liveThreadIds,
    openThreadTabs,
    hostThreads,
    agentsVisibilityRestoreSettled,
    visible,
    initialRosterThreadIds,
    onVisibleChange,
  ]);

  useEffect(() => {
    const pending = pendingActiveKeyRef.current;
    if (pending != null) {
      const ptyMap = ptyIdBySessionRef.current;
      const match = sessions.find((s) => computePersistKey(s, ptyMap) === pending);
      if (match != null) {
        pendingActiveKeyRef.current = null;
        setActiveSessionId(match.id);
        return;
      }
      if (sessions.some((s) => s.id === activeSessionId)) return;
    }
    if (activeSessionId !== '' && sessions.some((s) => s.id === activeSessionId)) return;
    if (sessions.length === 0) {
      if (activeSessionId !== '') setActiveSessionId('');
      return;
    }
    setActiveSessionId(sessions[sessions.length - 1].id);
  }, [sessions, activeSessionId]);

  useEffect(() => {
    if (!rehydrationSettled) return;
    const wasVisible = prevVisibleRef.current;
    prevVisibleRef.current = visible;

    if (launch != null && launch.nonce !== lastHandledLaunchNonceRef.current) {
      lastHandledLaunchNonceRef.current = launch.nonce;
      openSessionRef.current(launch, null, 'user');
      return;
    }
    if (commandLaunch != null && commandLaunch.nonce !== lastHandledCommandNonceRef.current) {
      lastHandledCommandNonceRef.current = commandLaunch.nonce;
      openSessionRef.current(null, commandLaunch.id, 'user');
      return;
    }
    const threadLaunchPending =
      hostThreads &&
      threadLaunch != null &&
      threadLaunch.nonce !== lastHandledThreadNonceRef.current;
    const restoredVisibility =
      hostTerminals && terminalRestoreRevealNonce !== consumedRestoreRevealNonceRef.current;
    if (restoredVisibility) consumedRestoreRevealNonceRef.current = terminalRestoreRevealNonce;
    if (
      visible &&
      !wasVisible &&
      sessions.length === 0 &&
      !threadLaunchPending &&
      !(hostThreads && hasInflightThreadLaunch())
    ) {
      if (restoredVisibility && !restoreAbandonedRef.current) return;
      if (hostThreads) {
        if (initialRosterThreadIds === null) return;
        initialVisibleSeedAttemptedRef.current = true;
        if (openThreadTabs.length > 0) {
          seedOwedRef.current = false;
          return;
        }
      }
      seedOwedRef.current = !seedOnRevealRef.current();
      return;
    }
    if (
      hostThreads &&
      visible &&
      wasVisible &&
      !initialVisibleSeedAttemptedRef.current &&
      initialRosterThreadIds !== null
    ) {
      initialVisibleSeedAttemptedRef.current = true;
      if (
        openThreadTabs.length === 0 &&
        sessions.length === 0 &&
        !threadLaunchPending &&
        !hasInflightThreadLaunch()
      ) {
        seedOwedRef.current = !seedOnRevealRef.current();
      }
      return;
    }
    if (!seedOwedRef.current) return;
    if (
      !visible ||
      sessions.length > 0 ||
      threadLaunchPending ||
      (hostThreads && openThreadTabs.length > 0)
    ) {
      seedOwedRef.current = false;
      return;
    }
    if (hostThreads && effectiveDefaultAgent === null) return;
    if (seedOnRevealRef.current()) seedOwedRef.current = false;
  }, [
    visible,
    launch,
    commandLaunch,
    threadLaunch,
    sessions.length,
    rehydrationSettled,
    hostThreads,
    effectiveDefaultAgent,
    initialRosterThreadIds,
    openThreadTabs.length,
    hostTerminals,
    terminalRestoreRevealNonce,
  ]);

  useEffect(() => {
    if (!hostThreads) return;
    if (threadLaunch == null || threadLaunch.nonce === lastHandledThreadNonceRef.current) return;
    let agent: { source: 'registry' | 'custom'; id: string } | null =
      threadLaunch.agentId === ''
        ? null
        : { source: threadLaunch.agentSource, id: threadLaunch.agentId };
    if (agent === null && effectiveDefaultAgent !== null) {
      agent = { source: effectiveDefaultAgent.source, id: effectiveDefaultAgent.id };
    }
    if (agent === null) {
      if (settingsShownForNonceRef.current !== threadLaunch.nonce) {
        settingsShownForNonceRef.current = threadLaunch.nonce;
        openAgentSettings();
      }
      return;
    }
    lastHandledThreadNonceRef.current = threadLaunch.nonce;
    void launchAgentForPaneRef.current({
      agent,
      prompt: threadLaunch.prompt,
      docName: threadLaunch.docName,
      titleHint: threadLaunch.titleHint,
      attachments: threadLaunch.attachments ?? undefined,
    });
  }, [threadLaunch, hostThreads, effectiveDefaultAgent]);

  useEffect(() => {
    if (!hostTerminals) return;
    if (typeof bridge?.terminal?.list !== 'function') return;
    if (rehydratedRef.current) return;
    rehydratedRef.current = true;
    let cancelled = false;
    let abandoned = false;
    const settle = () => {
      if (!cancelled) setRehydrationSettled(true);
    };
    const restoreDeadline = window.setTimeout(() => {
      abandoned = true;
      console.warn(
        `[terminal] dock restore exceeded its ${RESTORE_SETTLE_TIMEOUT_MS}ms bound; cold-starting instead of waiting`,
      );
      restoreAbandonedRef.current = true;
      restoreUnreadRef.current = true;
      seedOwedRef.current = true;
      settle();
    }, RESTORE_SETTLE_TIMEOUT_MS);
    const finish = () => {
      window.clearTimeout(restoreDeadline);
      if (!abandoned) settle();
    };
    void (async () => {
      try {
        const {
          sessionOrder: persisted,
          terminalSnapshot: restartSnapshot,
          failed: restoreReadFailed,
        } = await readDockRestoreState(bridge, persistSurface);
        if (cancelled || abandoned) return;
        if (restoreReadFailed) restoreUnreadRef.current = true;
        if (persisted != null) {
          reloadOrderRef.current = persisted.order;
          pendingActiveKeyRef.current = persisted.activeKey;
        }
        let survivors:
          | readonly {
              ptyId: string;
              customLabel: string | null;
              ordinal: number | null;
            }[]
          | null = null;
        try {
          survivors = (await bridge.terminal.list()) ?? [];
        } catch (err) {
          restoreUnreadRef.current = true;
          console.error(
            `[terminal] reload session list() failed; the surviving shells are unknown: ${String(err)}`,
          );
        }
        if (cancelled) return;
        if (abandoned) {
          const stranded = (survivors ?? []).map((entry) => entry.ptyId);
          if (stranded.length > 0) {
            console.warn(
              `[terminal] dock restore was abandoned before list() resolved; these PTYs stay running unadopted: ${stranded.join(', ')}`,
            );
          }
          return;
        }
        if (survivors != null && survivors.length > 0) {
          const order = reloadOrderRef.current;
          const rankOf = (ptyId: string) => {
            const i = order.indexOf(ptyId);
            return i === -1 ? Number.POSITIVE_INFINITY : i;
          };
          const recovered: TerminalSessionDescriptor[] = survivors
            .map((entry, index) => ({
              kind: 'terminal' as const,
              commandId: null,
              id: makeSessionId(index + 1),
              launch: null,
              title: null,
              customLabel: entry.customLabel ?? null,
              ordinal: entry.ordinal ?? index + 1,
              adoptPtyId: entry.ptyId,
            }))
            .sort((a, b) => {
              const ra = rankOf(a.adoptPtyId);
              const rb = rankOf(b.adoptPtyId);
              return ra === rb ? 0 : ra - rb;
            });
          sessionCounterRef.current = Math.max(
            recovered.length,
            ...recovered.map((r) => r.ordinal),
          );
          setSessions(recovered);
        } else if (
          survivors != null &&
          restartSnapshot != null &&
          restartSnapshot.tabs.length > 0
        ) {
          const recovered = restartSnapshot.tabs.map((entry, index) => ({
            kind: 'terminal' as const,
            commandId: null,
            id: makeSessionId(index + 1),
            launch: null,
            title: null,
            customLabel: entry.customLabel,
            ordinal: entry.ordinal,
            adoptPtyId: null,
          }));
          sessionCounterRef.current = Math.max(
            recovered.length,
            ...recovered.map((r) => r.ordinal),
          );
          pendingActiveKeyRef.current = null;
          setSessions(recovered);
          const active = recovered.find(
            (session) => session.ordinal === restartSnapshot?.activeOrdinal,
          );
          if (active != null) setActiveSessionId(active.id);
        } else if (survivors != null) {
          restoreAbandonedRef.current = true;
          seedOwedRef.current = true;
        }
        window.setTimeout(() => {
          if (!cancelled) pendingActiveKeyRef.current = null;
        }, 9_000);
        finish();
      } catch (err) {
        restoreUnreadRef.current = true;
        restoreAbandonedRef.current = true;
        seedOwedRef.current = true;
        console.error(
          `[terminal] dock rehydration failed; cold-starting: ${err instanceof Error ? (err.stack ?? err.message) : String(err)}`,
        );
        finish();
      }
    })();
    return () => {
      cancelled = true;
      abandoned = true;
      window.clearTimeout(restoreDeadline);
      rehydratedRef.current = false;
      restoreAbandonedRef.current = false;
      restoreUnreadRef.current = false;
      userArrangedRef.current = false;
      seedOwedRef.current = false;
      persistDeclineLoggedRef.current = false;
    };
  }, [bridge, hostTerminals, persistSurface]);

  useEffect(() => {
    if (canRehydrate || !persistsOrder) return;
    if (typeof bridge?.terminal?.getDockState !== 'function') return;
    let cancelled = false;
    let abandoned = false;
    const settle = () => {
      if (!cancelled) setRehydrationSettled(true);
    };
    const restoreDeadline = window.setTimeout(() => {
      abandoned = true;
      console.warn(
        `[agents] dock order restore exceeded its ${RESTORE_SETTLE_TIMEOUT_MS}ms bound; the saved tab set is left untouched`,
      );
      restoreUnreadRef.current = true;
      settle();
    }, RESTORE_SETTLE_TIMEOUT_MS);
    void readDockRestoreState(bridge, persistSurface)
      .then(({ sessionOrder: persisted, failed: restoreReadFailed }) => {
        if (cancelled || abandoned) return;
        if (restoreReadFailed) restoreUnreadRef.current = true;
        if (persisted != null) {
          reloadOrderRef.current = persisted.order;
          const activationTookOver = pendingActiveKeyRef.current !== null;
          if (!activationTookOver) pendingActiveKeyRef.current = persisted.activeKey;
        }
      })
      .finally(() => {
        window.clearTimeout(restoreDeadline);
        settle();
      });
    return () => {
      cancelled = true;
      window.clearTimeout(restoreDeadline);
      restoreUnreadRef.current = false;
      userArrangedRef.current = false;
      persistDeclineLoggedRef.current = false;
    };
  }, [bridge, canRehydrate, persistsOrder, persistSurface]);

  useEffect(() => {
    if (canRehydrate) return;
    const timer = window.setTimeout(() => {
      pendingActiveKeyRef.current = null;
    }, 9_000);
    return () => window.clearTimeout(timer);
  }, [canRehydrate]);

  useEffect(() => {
    if (!terminalAvailable && !hostThreads) return;
    return subscribeToActiveTerminalInput((detail) => dispatchAskAiRef.current(detail));
  }, [terminalAvailable, hostThreads]);

  useEffect(() => {
    if (!hostThreads) return;
    return subscribeSendToOpenChat(({ threadIds }) => {
      const activeId = activeSessionIdRef.current;
      const active = sessionsRef.current.find((session) => session.id === activeId);
      if (active?.kind !== 'thread') return;
      sendQueuedCommentsInThread(active.threadId, threadIds);
      revealForReuseRef.current();
      queueMicrotask(() => focusSession(active));
    });
  }, [hostThreads]);

  useEffect(() => {
    const unsubscribe = subscribeToPreferredSessionRequests(
      () => launchPreferredSessionRef.current(),
      window,
      () => {
        if (isWindow) return true;
        return (
          LAUNCHER_KIND_PANE[preferredSessionKindRef.current] ===
          (hostThreads ? 'agents' : 'terminal')
        );
      },
    );
    onPreferredSessionHostReady?.();
    return unsubscribe;
  }, [hostThreads, isWindow, onPreferredSessionHostReady]);

  useEffect(() => {
    if (!hostTerminals) return;
    return subscribeLocalMenuAction((action) => {
      if (action === 'new-terminal') {
        if (terminalAvailable) openSessionRef.current(null, null, 'user');
      } else if (action === 'kill-terminal') closeActiveRef.current();
      else if (action === 'close-active-tab-or-window' && isWindow) closeActiveRef.current();
    });
  }, [isWindow, hostTerminals, terminalAvailable]);

  useEffect(() => {
    function onKeyDown(event: KeyboardEvent) {
      if (!matchesPrimaryModifier(event, shortcutPlatform) || event.altKey || event.shiftKey)
        return;
      if (!/^[1-9]$/.test(event.key)) return;
      if (!chordTargetsHost(hostEl, isWindow)) return;
      if (isOverlayLayerOpen()) return;
      const target = sessionsRef.current[Number(event.key) - 1];
      if (target == null) return;
      event.preventDefault();
      event.stopPropagation();
      if (target.id !== activeSessionIdRef.current) noteUserArrangementRef.current();
      setActiveSessionId(target.id);
      queueMicrotask(() => focusSession(target));
    }
    window.addEventListener('keydown', onKeyDown, { capture: true });
    return () => window.removeEventListener('keydown', onKeyDown, { capture: true });
  }, [hostEl, isWindow, shortcutPlatform]);

  useEffect(() => {
    function onKeyDown(event: KeyboardEvent) {
      if (!matchesPrimaryModifier(event, shortcutPlatform) || !event.shiftKey || event.altKey) {
        return;
      }
      const direction = event.key === 'ArrowLeft' ? -1 : event.key === 'ArrowRight' ? 1 : 0;
      if (direction === 0) return;
      if (!chordTargetsHost(hostEl, isWindow)) return;
      if (isOverlayLayerOpen()) return;
      if (dragActiveRef.current) return;
      const target = event.target as HTMLElement | null;
      if (target?.tagName === 'INPUT' || target?.isContentEditable) return;
      const moved = moveActiveSessionRef.current(direction);
      if (moved == null) return;
      event.preventDefault();
      event.stopPropagation();
      const activeId = activeSessionIdRef.current;
      const active = sessionsRef.current.find((s) => s.id === activeId);
      if (active != null) queueMicrotask(() => focusSession(active));
      const message = t`Moved ${moved.label} to position ${moved.position} of ${moved.total}`;
      if (announceTimerRef.current != null) window.clearTimeout(announceTimerRef.current);
      announceTimerRef.current = window.setTimeout(() => {
        announceTimerRef.current = null;
        if (announcerRef.current != null) announcerRef.current.textContent = message;
      }, 60);
    }
    window.addEventListener('keydown', onKeyDown, { capture: true });
    return () => {
      window.removeEventListener('keydown', onKeyDown, { capture: true });
      if (announceTimerRef.current != null) {
        window.clearTimeout(announceTimerRef.current);
        announceTimerRef.current = null;
      }
    };
  }, [hostEl, isWindow, shortcutPlatform, t]);

  useEffect(() => {
    if (!hostTerminals) return;
    const terminalLive = sessions.some((s) => s.kind === 'terminal');
    setViewMenuState({ terminalLive });
    bridge?.editor.notifyViewMenuStateChanged({ terminalLive });
  }, [bridge, sessions, hostTerminals]);

  const focusInsideHostRef = useRef(false);
  useEffect(() => {
    if (hostEl == null) return;
    const syncFocusSnapshot = () => {
      focusInsideHostRef.current = focusInsideHost(hostEl);
    };
    document.addEventListener('focusin', syncFocusSnapshot, true);
    syncFocusSnapshot();
    return () => document.removeEventListener('focusin', syncFocusSnapshot, true);
  }, [hostEl]);
  useLayoutEffect(() => {
    if (isShowing || visible) return;
    if (!focusInsideHostRef.current) return;
    focusInsideHostRef.current = false;
    onRequestEditorFocus();
  }, [isShowing, visible, onRequestEditorFocus]);

  useEffect(() => {
    if (!isShowing || attachedHostEl == null) return;
    const focusOrigin = document.activeElement;
    const focusRevealRequested = revealFocusRequestedRef.current;
    revealFocusRequestedRef.current = false;
    const focusOriginPane =
      focusOrigin instanceof HTMLElement
        ? focusOrigin.getAttribute('data-header-pane-button')
        : null;
    const focusOriginIsOtherPaneButton =
      !focusRevealRequested &&
      hostThreads &&
      focusRemainsUsable(focusOrigin) &&
      focusOriginPane !== null &&
      focusOriginPane !== 'agents';
    if (revealFocusHoldRef.current && focusRemainsUsable(focusOrigin)) {
      revealFocusRef.current = null;
      return;
    }
    const initialTargetId = revealFocusRef.current?.pendingThreadId ?? activeSessionIdRef.current;
    const initialActive = sessionsRef.current.find((s) => s.id === initialTargetId);
    let initialFallbackLanding = false;
    if (initialActive != null) {
      const fallback = fallbackSessionFocusElement(initialActive);
      const preferred = focusSession(initialActive);
      if (preferred) {
        revealFocusRef.current = null;
        return;
      }
      initialFallbackLanding = fallback != null && document.activeElement === fallback;
    }
    const emptySurfaceLanding =
      hostThreads && initialActive == null && !focusOriginIsOtherPaneButton
        ? (focusAvailableButton(emptyAgentActionButtonRef.current) ??
          focusAvailableButton(emptyAgentStateFallbackButton(attachedHostEl)))
        : null;
    revealFocusRef.current = { pendingThreadId: revealFocusRef.current?.pendingThreadId ?? null };
    let landed = focusOriginIsOtherPaneButton || initialFallbackLanding;
    let attemptedFallback: HTMLElement | null = null;
    let retryFrame: number | null = null;
    let retired = false;
    const recordLanding = (event: FocusEvent) => {
      if (event.target === attemptedFallback) landed = true;
    };
    const retryFocus = () => {
      retryFrame = null;
      if (retired) return;
      const targetId = revealFocusRef.current?.pendingThreadId ?? activeSessionIdRef.current;
      const active = sessionsRef.current.find((s) => s.id === targetId);
      if (active == null) return;
      if (
        focusOriginIsOtherPaneButton &&
        document.activeElement === focusOrigin &&
        focusRemainsUsable(focusOrigin)
      ) {
        const revealFocus = revealFocusRef.current;
        if (revealFocus != null) revealFocus.pendingThreadId = active.id;
        landed = true;
        return;
      }
      const focused = document.activeElement;
      const fallback = fallbackSessionFocusElement(active);
      if (
        focused != null &&
        focused !== document.body &&
        focused !== focusOrigin &&
        focused !== fallback &&
        focused !== emptySurfaceLanding
      ) {
        landed = true;
        revealFocusRef.current = null;
        return;
      }
      landed = false;
      attemptedFallback = fallback;
      const preferred = focusSession(active);
      attemptedFallback = null;
      landed = preferred || landed || (fallback != null && document.activeElement === fallback);
      if (preferred) {
        revealFocusRef.current = null;
        observer.disconnect();
      }
    };
    const scheduleRetry = () => {
      if (retired || retryFrame !== null) return;
      retryFrame = window.requestAnimationFrame(retryFocus);
    };
    document.addEventListener('focusin', recordLanding, true);
    const observer = new MutationObserver(() => {
      retryFocus();
      if (!landed) scheduleRetry();
    });
    observer.observe(attachedHostEl, { subtree: true, childList: true });
    scheduleRetry();
    const deadline = window.setTimeout(() => {
      retired = true;
      if (retryFrame != null) window.cancelAnimationFrame(retryFrame);
      retryFrame = null;
      observer.disconnect();
      revealFocusRef.current = null;
      const focusNowhere =
        document.activeElement == null || document.activeElement === document.body;
      const active = sessionsRef.current.find((s) => s.id === activeSessionIdRef.current);
      if (!landed && focusNowhere && active != null) {
        console.warn(
          `[${hostThreads ? 'agents' : 'terminal'}] reveal focus did not land within its ${REVEAL_FOCUS_LANDING_TIMEOUT_MS}ms bound`,
        );
      }
    }, REVEAL_FOCUS_LANDING_TIMEOUT_MS);
    return () => {
      retired = true;
      revealFocusRef.current = null;
      document.removeEventListener('focusin', recordLanding, true);
      observer.disconnect();
      if (retryFrame != null) window.cancelAnimationFrame(retryFrame);
      window.clearTimeout(deadline);
    };
  }, [isShowing, attachedHostEl, hostThreads]);

  const activeThreadIdForView = (() => {
    const active = sessions.find((s) => s.id === activeSessionId);
    return active?.kind === 'thread' ? active.threadId : null;
  })();
  const activeThreadInfoForView =
    activeThreadIdForView !== null ? threadInfoById.get(activeThreadIdForView) : undefined;
  const activeThreadActivityAt = activeThreadInfoForView?.lastActivityAt ?? null;
  const activeThreadStatus = activeThreadInfoForView?.status ?? null;
  const historyCovering = hostThreads && historyOpen && historyMode === 'cover';
  // biome-ignore lint/correctness/useExhaustiveDependencies: `activeThreadActivityAt` and `activeThreadStatus` are not read inside the effect body — they are dep-only, so an incoming activity tick OR a status transition (running → ready without a fresh activityAt) both re-fire the mark-viewed call. Without the status dep, a ready-flip on an unchanged activityAt would leave the tab pulsing forever. Neither trigger marks anything while `historyCovering` holds: a transcript the history cover hides has not been read, so the effect returns before the call and re-fires once the cover lifts.
  useEffect(() => {
    if (!isShowing || historyCovering || activeThreadIdForView === null) return;
    getAgentThreadClient().markThreadViewed(activeThreadIdForView);
  }, [
    activeThreadIdForView,
    activeThreadActivityAt,
    activeThreadStatus,
    historyCovering,
    isShowing,
  ]);

  const tabDescriptors: TerminalTabDescriptor[] = sessions.map((session) => {
    const label = sessionLabel(session);
    if (session.kind === 'terminal') return { id: session.id, label, icon: terminalTabIcon() };
    const info = threadInfoById.get(session.threadId);
    return {
      id: session.id,
      label,
      icon: <ThreadTabIcon info={info} threadId={session.threadId} />,
      tooltip:
        info === undefined ? undefined : (
          <ThreadTabPeek info={info} threadId={session.threadId} label={label} />
        ),
      tooltipDescription:
        info === undefined
          ? undefined
          : (openedAt) => {
              const lastActivity = formatRelativeActivity(info.lastActivityAt, openedAt);
              return t`Last activity ${lastActivity}`;
            },
      srStatus:
        info === undefined ? undefined : (
          <ThreadTabScreenReaderStatus info={info} threadId={session.threadId} />
        ),
    };
  });

  const panelSessions = [...sessions].sort((a, b) => a.ordinal - b.ordinal);

  const agentPickPending = sessions.some(
    (session) =>
      session.id === activeSessionId &&
      session.kind === 'thread' &&
      switchingThreads.has(session.threadId),
  );

  const newButton = (
    <TerminalNewChatButton
      selected={newSessionChoice}
      onLaunchSelected={launchSelectedNewTab}
      showAgents={hostThreads}
      registeredAgents={enabledRegisteredAgents}
      onPickAgent={pickNewChatAgent}
      agentPickPending={agentPickPending}
      onOpenSettings={openAgentSettings}
      liveThreadCount={liveThreadCount}
      showClis={terminalAvailable}
      onPickCli={pickNewChatCli}
      onPickTerminal={pickNewChatTerminal}
      visibleClis={enabledTerminalClis(enabledOverrides, installedClis ?? {})}
    />
  );

  const historyNewButton = hostThreads ? (
    <TerminalNewChatButton
      selected={newSessionChoice}
      onLaunchSelected={launchSelectedNewTab}
      showAgents
      registeredAgents={enabledRegisteredAgents}
      onPickAgent={pickNewChatAgent}
      agentPickPending={agentPickPending}
      onOpenSettings={openAgentSettings}
      liveThreadCount={liveThreadCount}
      showClis={terminalAvailable}
      onPickCli={pickNewChatCli}
      onPickTerminal={pickNewChatTerminal}
      visibleClis={enabledTerminalClis(enabledOverrides, installedClis ?? {})}
      presentation="panel"
    />
  ) : null;

  const historyToggle = hostThreads ? (
    <ThreadHistoryToggle
      open={historyOpen}
      panelId={historyPanelId}
      triggerRef={historyToggleRef}
      onOpenChange={setHistoryOpenForPane}
    />
  ) : null;

  const showStrip = sessions.length > 0 || (visible && !isWindow);

  useEffect(() => {
    if (!hostTerminals) return;
    if (hostStateReportsRef.current >= MAX_HOST_STATE_REPORTS) return;
    hostStateReportsRef.current += 1;
    emitDiagnosticBreadcrumb('ok-terminal-sessions-host-state', {
      surface,
      sessions: sessions.length,
      hostConnected: hostEl?.isConnected === true,
      hasContainer: container != null,
      attached: attachedHostEl != null,
      terminalVisible: visible,
      showStrip,
      tabs: hostEl?.querySelectorAll('[role="tab"]').length ?? 0,
    });
  }, [
    hostTerminals,
    surface,
    sessions.length,
    hostEl,
    container,
    attachedHostEl,
    visible,
    showStrip,
  ]);
  const emptyAgentStatePreview = readEmptyAgentStatePreview();
  const emptyAgentState =
    emptyAgentStatePreview ??
    (initialRosterThreadIds === null || (effectiveDefaultAgent === null && !agentOptionsSettled)
      ? 'loading'
      : effectiveDefaultAgent === null
        ? agentCatalogFailed
          ? 'agents-unavailable'
          : 'no-agents'
        : emptyAgentStateFromLaunchState(emptyAgentLaunchState));
  const showEmptyAgentState =
    hostThreads && (sessions.length === 0 || emptyAgentStatePreview !== null);

  const sessionContent = showEmptyAgentState ? (
    <EmptyAgentSessionsState
      state={emptyAgentState}
      onConfigureAgents={openAgentSettings}
      onRetry={
        emptyAgentState === 'agents-unavailable' ? refetchAgentCatalog : retryFailedAgentLaunch
      }
      actionButtonRef={emptyAgentActionButtonRef}
    />
  ) : sessions.length === 0 ? (
    terminalAvailable ? null : (
      <EmptySessionsState />
    )
  ) : (
    panelSessions.map((session) => (
      <TabsContent
        key={session.id}
        value={session.id}
        forceMount
        data-session-id={session.id}
        {...(session.kind === 'terminal' ? { 'data-terminal-session': session.id } : {})}
        className={cn(
          'm-0 flex min-h-0 flex-1 flex-col overflow-hidden data-[state=inactive]:hidden',
          isWindow && 'px-[22px] pb-[22px]',
        )}
      >
        {session.kind === 'terminal' ? (
          bridge != null && terminalAvailable ? (
            <TerminalGate
              bridge={bridge}
              launch={session.launch}
              commandId={session.commandId}
              adoptPtyId={session.adoptPtyId}
              onPtyId={(ptyId) => setSessionPtyId(session.id, ptyId)}
              onExit={
                session.launch?.signInThreadId === undefined
                  ? undefined
                  : () => notifySignInExitOnce(session)
              }
              onTitleChange={(title) => setSessionTitle(session.id, title)}
              onClose={() => closeSession(session.id)}
            />
          ) : null
        ) : (
          <ThreadPanel
            threadId={session.threadId}
            info={threadInfoById.get(session.threadId)}
            showConnectionBanner={threadConnectionDown && session.id === activeSessionId}
            active={visible && !historyCovering && session.id === activeSessionId}
          />
        )}
      </TabsContent>
    ))
  );

  const historyPanel = historyOpen ? (
    <ThreadHistoryPanel
      threads={agentThreads}
      openThreadIds={openThreadIds}
      activeThreadId={activeThreadIdForView}
      onSelectThread={selectHistoryThread}
      mode={historyMode}
      panelId={historyPanelId}
      onDismiss={dismissHistory}
      newChatControl={historyNewButton}
    />
  ) : null;

  const sessionStrip = (
    <TerminalTabStrip
      sessions={tabDescriptors}
      sessionKind={hostThreads ? 'agent' : 'terminal'}
      activeSessionId={activeSessionId}
      onSelect={(id) => {
        if (id !== activeSessionIdRef.current) noteUserArrangement();
        pendingActiveKeyRef.current = null;
        setActiveSessionId(id);
      }}
      onTabActivate={(id) => {
        const session = sessionsRef.current.find((s) => s.id === id);
        if (session != null) queueMicrotask(() => focusSession(session));
      }}
      newButton={newButton}
      leadingControls={chatHistorySide === 'start' ? historyToggle : null}
      trailingControls={chatHistorySide === 'end' ? historyToggle : null}
      rowMenu={hostThreads ? <ChatHistorySideMenuItem side={chatHistorySide} /> : undefined}
      rowMenuFocusFallback={hostThreads ? historyToggleRef : undefined}
      onClose={closeSession}
      onRename={renameSession}
      onReorder={reorderSessions}
      onDragActiveChange={(active) => {
        dragActiveRef.current = active;
      }}
      edge={edge}
      onPlacementChange={surface === 'terminal-dock' ? onTerminalPlacementChange : undefined}
      draggable={isWindow}
      className="h-full"
    >
      {hostThreads ? (
        <div className="flex min-h-0 min-w-0 flex-1 flex-col overflow-hidden">{sessionContent}</div>
      ) : (
        sessionContent
      )}
    </TerminalTabStrip>
  );

  const historySurface = historyOpen ? (
    <div
      className={cn(
        'z-20 h-full max-w-full bg-sidebar',
        historyMode === 'cover'
          ? 'absolute inset-0 w-full shadow-xl [-webkit-app-region:no-drag]'
          : cn(
              'w-(--history-panel-width) shrink-0',
              chatHistorySide === 'start' ? 'border-e' : 'border-s',
            ),
      )}
      style={
        {
          '--history-panel-width': `${HISTORY_PANEL_WIDTH_PX}px`,
        } as CSSProperties
      }
      data-testid="agent-thread-history-surface"
      data-side={chatHistorySide}
    >
      {historyPanel}
    </div>
  ) : null;

  const sessionViews = showStrip ? (
    hostThreads ? (
      <ThreadHistorySearchProvider scope={threadScope}>
        <div
          className="relative flex h-full min-h-0 min-w-0 overflow-hidden"
          data-testid="agent-panel-layout"
        >
          {chatHistorySide === 'start' ? historySurface : null}
          <div
            className="flex min-h-0 min-w-0 flex-1 flex-col"
            data-testid="agent-panel-session-surface"
            inert={historyCovering ? true : undefined}
          >
            {sessionStrip}
          </div>
          {chatHistorySide === 'end' ? historySurface : null}
        </div>
      </ThreadHistorySearchProvider>
    ) : (
      sessionStrip
    )
  ) : null;

  return (
    <>
      {attachedHostEl != null
        ? createPortal(
            <>
              {sessionViews}
              <span
                ref={announcerRef}
                aria-live="polite"
                aria-atomic="true"
                className="sr-only"
                data-testid="terminal-reorder-announcer"
              />
            </>,
            attachedHostEl,
          )
        : null}
    </>
  );
}

function ThreadPanel({
  threadId,
  info,
  showConnectionBanner,
  active,
}: {
  threadId: string;
  info: ThreadInfo | undefined;
  showConnectionBanner: boolean;
  active: boolean;
}) {
  if (info === undefined) return null;
  return (
    <>
      {showConnectionBanner ? <ThreadConnectionBanner /> : null}
      <Suspense
        fallback={
          <div
            role="status"
            aria-busy="true"
            className="flex min-h-0 flex-1 items-center justify-center text-muted-foreground"
          >
            <Spinner className="size-5" aria-hidden="true" />
          </div>
        }
      >
        <ThreadView key={threadId} info={info} active={active} />
      </Suspense>
    </>
  );
}

function ThreadConnectionBanner() {
  const { t } = useLingui();
  return (
    <div
      className="shrink-0 border-warning/30 border-b bg-warning/5 px-3 py-1 text-warning text-xs"
      data-testid="agent-thread-reconnecting"
    >
      {t`Reconnecting to the agent service…`}
    </div>
  );
}

function EmptySessionsState() {
  const { t } = useLingui();
  return (
    <div
      className="flex min-h-0 flex-1 items-center justify-center px-6 text-center text-muted-foreground text-sm"
      data-testid="sessions-dock-empty"
    >
      {t`Start a chat with the + button, or launch an agent from a page.`}
    </div>
  );
}

function EmptyAgentSessionsState({
  state,
  onConfigureAgents,
  onRetry,
  actionButtonRef,
}: {
  state: EmptyAgentState;
  onConfigureAgents: () => void;
  onRetry: () => void;
  actionButtonRef: RefObject<HTMLButtonElement | null>;
}) {
  const { t } = useLingui();
  let content: ReactNode;
  switch (state) {
    case 'idle':
      content = null;
      break;
    case 'loading':
    case 'starting':
      content = (
        <div
          role="status"
          aria-busy="true"
          className="flex items-center gap-2"
          data-testid="sessions-dock-loading"
        >
          <span aria-hidden="true">
            <Spinner className="size-4" />
          </span>
          <span>{state === 'loading' ? t`Loading agents…` : t`Starting the agent…`}</span>
        </div>
      );
      break;
    case 'no-agents':
      content = (
        <div className="flex flex-col items-center gap-2" data-testid="sessions-dock-no-agents">
          <p>{t`No agents enabled.`}</p>
          <Button ref={actionButtonRef} type="button" size="sm" onClick={onConfigureAgents}>
            {t`Configure agents`}
          </Button>
        </div>
      );
      break;
    case 'agents-unavailable':
      content = (
        <div
          className="flex flex-col items-center gap-2"
          data-testid="sessions-dock-agents-unavailable"
        >
          <p>{t`Couldn't load your agents.`}</p>
          <Button ref={actionButtonRef} type="button" size="sm" onClick={onRetry}>
            {t`Try again`}
          </Button>
        </div>
      );
      break;
    case 'failed':
      content = (
        <div className="flex flex-col items-center gap-2" data-testid="sessions-dock-launch-failed">
          <p>{t`Couldn't start the agent thread.`}</p>
          <Button ref={actionButtonRef} type="button" size="sm" onClick={onRetry}>
            {t`Try again`}
          </Button>
        </div>
      );
      break;
    case 'deduped':
      content = (
        <div
          className="flex flex-col items-center gap-2"
          data-testid="sessions-dock-launch-deduped"
        >
          <p>{t`Already starting a chat with this agent — try again in a moment.`}</p>
          <Button ref={actionButtonRef} type="button" size="sm" onClick={onRetry}>
            {t`Try again`}
          </Button>
        </div>
      );
      break;
    default:
      content = assertNeverEmptyAgentState(state);
  }
  return (
    <div
      className="flex min-h-0 flex-1 items-center justify-center px-6 text-center text-muted-foreground text-sm"
      data-testid="sessions-dock-empty"
    >
      {content}
    </div>
  );
}

type EmptyAgentState =
  | 'idle'
  | 'loading'
  | 'starting'
  | 'deduped'
  | 'no-agents'
  | 'agents-unavailable'
  | 'failed';

const EMPTY_AGENT_STATES: readonly EmptyAgentState[] = [
  'loading',
  'starting',
  'deduped',
  'no-agents',
  'agents-unavailable',
  'failed',
];

function readEmptyAgentStatePreview(): EmptyAgentState | null {
  if (!import.meta.env.DEV || typeof window === 'undefined') return null;
  const state = new URLSearchParams(window.location.search).get('preview-agent-empty');
  return EMPTY_AGENT_STATES.find((candidate) => candidate === state) ?? null;
}

function assertNeverThreadLaunchOutcome(outcome: never): never {
  throw new Error(`unhandled thread launch outcome: ${String(outcome)}`);
}

function assertNeverEmptyAgentState(state: never): never {
  throw new Error(`unhandled empty agent state: ${String(state)}`);
}

function emptyAgentStateFromLaunchState(state: EmptyAgentLaunchState): EmptyAgentState {
  switch (state) {
    case 'idle':
      return 'idle';
    case 'launching':
      return 'starting';
    case 'deduped':
      return 'deduped';
    case 'failed':
      return 'failed';
    default:
      return assertNeverEmptyAgentLaunchState(state);
  }
}

function assertNeverEmptyAgentLaunchState(state: never): never {
  throw new Error(`unhandled empty agent launch state: ${String(state)}`);
}

function computePersistKey(
  session: SessionDescriptor,
  ptyMap: ReadonlyMap<string, string>,
): string | null {
  if (session.kind === 'thread') return session.threadId;
  return session.adoptPtyId ?? ptyMap.get(session.id) ?? null;
}

function buildTerminalRestartSnapshot(
  sessions: readonly SessionDescriptor[],
  activeSessionId: string,
): OkTerminalRestartSnapshot {
  const terminals = sessions.filter(
    (session): session is TerminalSessionDescriptor => session.kind === 'terminal',
  );
  const active = terminals.find((session) => session.id === activeSessionId);
  return {
    tabs: terminals.map((session) => ({
      ordinal: session.ordinal,
      customLabel: session.customLabel,
    })),
    activeOrdinal: active?.ordinal ?? null,
  };
}

function placeSessionAdditions<T extends { readonly id: string }>(
  kept: readonly T[],
  additions: readonly T[],
  order: readonly string[],
  keyOf: (session: T) => string | null,
): T[] {
  const rankOf = (session: T): number => {
    const key = keyOf(session);
    if (key == null) return Number.POSITIVE_INFINITY;
    const i = order.indexOf(key);
    return i === -1 ? Number.POSITIVE_INFINITY : i;
  };
  const result = [...kept];
  for (const addition of additions) {
    const addRank = rankOf(addition);
    if (addRank === Number.POSITIVE_INFINITY) {
      result.push(addition);
      continue;
    }
    let insertAt = result.length;
    for (let i = 0; i < result.length; i++) {
      if (rankOf(result[i]) > addRank) {
        insertAt = i;
        break;
      }
    }
    result.splice(insertAt, 0, addition);
  }
  return result;
}