zidane-ui 9.1.1 → 9.1.3

package/src/chat/headless/sidebar/directory.ts

@@ -1,1046 +0,0 @@
-/**
- * The session directory: every host's sessions as the sidebar lists them,
- * kept current outside React.
- *
- * - Listing: one read per host (this machine plus each remote host) under
- *   the shown archive filter. Reads are versioned: only the newest refresh
- *   lands, and a host's own older answer never overwrites a newer one.
- * - Run state: a refresh reconciles the rows' status with the stream store
- *   (a running row marks the session running, an idle one confirmed by the
- *   host clears a run this client missed the end of) unless a stream signal
- *   moved the run state while the refresh was in flight.
- * - Live: a debounced change signal re-reads the hosts it touched; a run end
- *   re-reads its host and leaves a notification on a session not open; a
- *   runtime switch drops every stream; a reconnect (runtime or the open
- *   session's server) re-reads the open transcript when no run streams it.
- * - Prewarm: the transcripts around the open session load in idle time.
- * - Spaces: the shown space (kept by the views store), the slide direction of
- *   the last switch, following the open session to its space, and reopening
- *   the conversation last open in a space when switching back to it.
- * - Actions: create (in the shown space), rename, optimistic favorite,
- *   archive, move to a space (a session or a whole project), delete.
- * - Extensions: the spaces they add join the user's (`query.ts`), facets
- *   pushed by the host land on their rows, and the switcher keeps its own
- *   order and hidden spaces; the current view can be saved as a space (its
- *   query built by `viewQuery`, checked before it is stored). Facet pushes
- *   arriving together land in one state change.
- *
- * Generic over the app's row type and its transcript page type, so an app
- * keeps its own branded session keys.
- */
-import {
-  activeSpaceOf,
-  DEFAULT_SPACE_ID,
-  normalizeSpaces,
-  projectNameOf,
-  resolveSessionSpace,
-  SessionQueryError,
-  sessionDirLabel,
-  viewQuery,
-  type QueryBound,
-} from 'zidane/chat/pure';
-
-import { constant, writable, type Readable } from '../store';
-import { createNotificationStore, type SessionNotificationStore } from './notifications';
-import {
-  filterQueryOf,
-  filtersForSpace,
-  mergeSidebarSpaces,
-  NO_SIDEBAR_CONTRIBUTIONS,
-  resolveGrouping,
-  resolveSort,
-  spaceMembership,
-  switcherSpaces,
-  type SidebarContributions,
-  type SidebarSpace,
-} from './query';
-import { isProjectMember } from './rows';
-import { VIEW_CHOICE, type SessionActivityFilter, type SessionArchiveFilter, type SidebarListSession } from './types';
-import { DEFAULT_SIDEBAR_VIEW, type SidebarViews } from './view';
-
-/** A project as one space lists it: its path (`projectPathOf`), the host it is on, the space. */
-export interface ProjectInSpace {
-  /** The project's folder (`projectPathOf`). */
-  path: string;
-  /** A remote host's id; absent for this machine. */
-  hostId?: string;
-  /** The space it is listed in (an unknown or absent id is the default space). */
-  spaceId?: string;
-  /** Its repository, when its group also lists the repository's sessions on other machines (`isProjectMember`). */
-  repoKey?: string;
-}
-
-/** What deleting a session did with its environment. */
-export type SessionRemoval = { kept: false } | { kept: true; reason?: string };
-
-/** The sessions transport the directory reads and acts through (`ChatHost.sessions`). */
-export interface SessionDirectorySource<S extends SidebarListSession, C = unknown> {
-  /** One host's sessions under the archive filter; `hostId` absent = this machine. */
-  query(filter: { archive: SessionArchiveFilter; hostId?: string }): Promise<readonly S[]>;
-  /** Creates a session and resolves with its row. */
-  create?(input: C): Promise<S>;
-  /** Sets a session's title. */
-  rename?(sessionId: S['id'], title: string): Promise<void>;
-  /** Stars or unstars a session. */
-  setFavorite?(sessionId: S['id'], favorite: boolean): Promise<void>;
-  /** Archives or restores a session. */
-  setArchived?(sessionId: S['id'], archived: boolean): Promise<void>;
-  /** Moves a session to a space. */
-  setSpace?(sessionId: S['id'], spaceId: string): Promise<void>;
-  /** Resolves to `{ kept: true }` when the session's environment stayed on disk. */
-  remove?(sessionId: S['id']): Promise<void | SessionRemoval>;
-  /** Fires (possibly in bursts) with a session whose row changed. */
-  onChanged?(listener: (sessionId: S['id']) => void): () => void;
-  /**
-   * Fires with a session's facets when the extensions computed new ones (`sessions:facets`): every
-   * value, keyed `<extensionId>.<key>`. Absent: facets change only with a re-read.
-   */
-  onFacets?(listener: (sessionId: S['id'], facets: Readonly<Record<string, unknown>>) => void): () => void;
-}
-
-/** The slice of the session stream store the directory keeps in step. */
-export interface SessionDirectoryStreams<K extends string, P> {
-  /** A snapshot of the run state; the returned check says whether it still holds. */
-  captureRunState(): () => boolean;
-  /** A row says the session runs: show it running. */
-  markRunning(sessionId: K): void;
-  /** The host confirmed the session is idle: end a run whose end was missed. */
-  confirmIdle(sessionId: K): void;
-  /** Whether a run streams for the session here. */
-  peekRunning(sessionId: K | null): boolean;
-  /** The session's run counter (bumps on every run start). */
-  peekRunSeq(sessionId: K | null): number;
-  /** The session's transcript is cached. */
-  hasEvents(sessionId: K): boolean;
-  /** Cache a loaded transcript page. */
-  setEventsPage(sessionId: K, page: P): void;
-  /** Drop every cached transcript except these. */
-  evictExcept(keep: ReadonlySet<K>): void;
-  /** Drop every stream (a runtime switch). */
-  dropAll(): void;
-  /** Drop one session's stream (deleted). */
-  reset(sessionId: K): void;
-}
-
-/** A remote host as the directory follows it. */
-export interface DirectoryServer {
-  /** The host id rows carry as `hostId`. */
-  id: string;
-  /** Its connection status (`connected` when reachable). */
-  status: string;
-}
-
-/** The settings the directory reads. */
-export interface DirectorySettings {
-  /** Spaces are on. */
-  spaces: boolean;
-  /** The settings' space list as stored (normalized here). */
-  spaceList: unknown;
-  /** The orchestration main session is listed. */
-  orchestration: boolean;
-}
-
-/** Options of {@link createSessionDirectory}: the ports it reads and acts through. */
-export interface SessionDirectoryOptions<S extends SidebarListSession, P, C = unknown> {
-  /** The sessions transport (`ChatHost.sessions`). */
-  sessions: SessionDirectorySource<S, C>;
-  /** The stream store it keeps in step. */
-  streams: SessionDirectoryStreams<S['id'], P>;
-  /** Load a session's latest transcript page. */
-  loadEvents(sessionId: S['id'], options?: { prewarm?: boolean }): Promise<P>;
-  /** Ask whether a session runs; `false` only when the host is sure it doesn't. */
-  isRunning(sessionId: S['id']): Promise<boolean | null | undefined>;
-  /** The remote hosts listed next to this machine. */
-  servers: Readable<readonly DirectoryServer[]>;
-  /** Spaces and orchestration settings. */
-  settings: Readable<DirectorySettings>;
-  /** The views and the shown space. */
-  views: SidebarViews;
-  /** The archive filter the list shows (the shown space's view). */
-  archive?: SessionArchiveFilter;
-  /** Live signals; each one left out is not followed. */
-  signals?: {
-    /** A run ended. */
-    onRunEnd?(listener: (sessionId: S['id'], ok: boolean) => void): () => void;
-    /** The runtime connected or disconnected (a daemon, a server connection). */
-    onRuntime?(listener: (connected: boolean) => void): () => void;
-    /** A remote host was removed, with the sessions it held and the words to show. */
-    onHostRemoved?(
-      listener: (removed: { hostId: string; sessionIds: readonly S['id'][]; notice: string | null }) => void,
-    ): () => void;
-  };
-  /** The remote host a session lives on, `null` on this machine. */
-  serverOf(sessionId: S['id']): string | null;
-  /** Session keys kept in the transcript cache besides the prewarmed ones (`pinnedSessions`). */
-  pinned?: () => Iterable<S['id']>;
-  /** A window that only ever shows this session (its other sessions are never opened). */
-  pinnedSession?: S['id'] | null;
-  /** Schedules prewarm reads; defaults to `requestIdleCallback` with a timer fallback. */
-  idle?: { request(run: () => void): number; cancel(handle: number): void };
-  /** Debounce of change signals. Defaults to 300 ms. */
-  changedDebounceMs?: number;
-  /** A refresh is about to list these rows (an app's per-row bookkeeping, before they render). */
-  onListed?(rows: readonly S[]): void;
-  /** A session was deleted: drop what the app keeps for it (panels, layouts). */
-  onRemoved?(sessionId: S['id']): void;
-  /** A refresh failed. */
-  onError?(error: unknown): void;
-  /**
-   * What the extensions contribute to the sidebar (`sidebarContributionsOf(host.items)`). An app whose
-   * extensions host comes later attaches it then (`attachContributions`).
-   */
-  contributions?: Readable<SidebarContributions>;
-  /** Adds a space to the user's list (the settings' `spaceList`). Absent: a view can't be saved as a space. */
-  saveSpace?(space: SidebarSpace): Promise<void>;
-}
-
-/** The directory's state as one snapshot: a new object whenever any field changes. */
-export interface SessionDirectoryState<S extends SidebarListSession> {
-  /** Every listed session, unfiltered (the archive filter is the host's). */
-  allSessions: readonly S[];
-  /** The open session. */
-  activeSessionId: S['id'] | null;
-  /** Spaces are on. */
-  spacesOn: boolean;
-  /** Every space, the default one always present: the user's in order, then the extensions'. */
-  spaces: readonly SidebarSpace[];
-  /** The spaces the switcher shows, in its order (the user's arrangement on top of `spaces`). */
-  switcherSpaces: readonly SidebarSpace[];
-  /**
-   * The spaces the user hid from the switcher on this device (`setSpaceHidden`), in `spaces` order:
-   * what the switcher's Hidden spaces menu offers to show again. A space hidden in the settings'
-   * space list (`hidden: true`) is not in it: the settings show it again.
-   */
-  hiddenSpaces: readonly SidebarSpace[];
-  /** The space shown (the default one while spaces are off). */
-  activeSpace: SidebarSpace;
-  /** What the extensions contribute to the sidebar. */
-  contributions: SidebarContributions;
-  /** The last space switch, for the list's slide. */
-  spaceSlide: { spaceId: string; direction: 'next' | 'prev' } | null;
-  /** Why the open session closed (its host was removed), until dismissed or another opens. */
-  hostNotice: string | null;
-}
-
-/** The session directory: its state, notifications and views, and the actions on them. */
-export interface SessionDirectory<S extends SidebarListSession, C = unknown> {
-  /** The state, one snapshot per change. */
-  state: Readable<SessionDirectoryState<S>>;
-  /** What finished runs left on sessions not open. */
-  notifications: SessionNotificationStore;
-  /** The views and the shown space. */
-  views: SidebarViews;
-  /** Start following hosts, signals and settings; returns the stop. */
-  start(): () => void;
-  /** Re-read every host. */
-  refresh(): Promise<void>;
-  /** The list's archive filter changed (re-reads when it did). */
-  setArchive(archive: SessionArchiveFilter): void;
-  /** Open a session (or none) and clear its notification and the host notice. */
-  select(sessionId: S['id'] | null): void;
-  /** Set the open session without clearing anything (window routing, deletes). */
-  setActive(sessionId: S['id'] | null | ((current: S['id'] | null) => S['id'] | null)): void;
-  /** Hides the host notice. */
-  dismissHostNotice(): void;
-  /** Create a session in the shown space (unless the input names one) and list it. */
-  create(input: C & { spaceId?: string }): Promise<S>;
-  /** Renames a session, then re-reads. */
-  rename(sessionId: S['id'], title: string): Promise<void>;
-  /** Stars or unstars a session at once; a failed write puts it back. */
-  setFavorite(sessionId: S['id'], favorite: boolean): Promise<void>;
-  /** Archives or restores a session, then re-reads. */
-  setArchived(sessionId: S['id'], archived: boolean): Promise<void>;
-  /** Archives sessions, then re-reads once. */
-  archiveMany(sessionIds: readonly S['id'][]): Promise<void>;
-  /** Delete one session without re-reading; the caller refreshes. */
-  drop(sessionId: S['id']): Promise<SessionRemoval>;
-  /** Delete sessions, then re-read; resolves to how many kept their environment. */
-  removeMany(sessionIds: readonly S['id'][]): Promise<{ kept: number; reason?: string }>;
-  /**
-   * Shows another space and reopens the conversation last open there, when it is still listed in it;
-   * else the open session closes when it belongs elsewhere.
-   */
-  setActiveSpace(spaceId: string): void;
-  /** Step to the next or previous space, wrapping at either end; false with spaces off or only one space. */
-  stepSpace(delta: 1 | -1): boolean;
-  /** Moves a session to a space, then re-reads. */
-  setSessionSpace(sessionId: S['id'], spaceId: string): Promise<void>;
-  /** Hides a space from the switcher or shows it again; hiding the shown space shows the default one. */
-  setSpaceHidden(spaceId: string, hidden: boolean): void;
-  /** Moves a space one place left (-1) or right (1) in the switcher. */
-  moveSpace(spaceId: string, delta: 1 | -1): void;
-  /** Follow an extensions host's sidebar contributions from now on (replacing any); returns the detach. */
-  attachContributions(contributions: Readable<SidebarContributions>): () => void;
-  /**
-   * Saves the shown space's view as a new user space (its query, grouping and sort) and shows it.
-   * The query is `viewQuery`'s (`zidane/chat/pure`): the space's membership, then the project,
-   * activity, agent and contributed filters. Rejects with a `SessionQueryError` (nothing saved)
-   * when that query is not valid (too deep, too many nodes or values), and with `saveSpace`'s error.
-   * Undefined without `saveSpace`. The sidebar's `useSaveViewAsSpace` names the space and words a failure.
-   */
-  saveViewAsSpace?: (name: string) => Promise<SidebarSpace>;
-  /** A project's sessions in its space (every archive state), read fresh from its host. */
-  listProjectSessions(project: ProjectInSpace): Promise<S[]>;
-  /** Move a project's sessions to another space; resolves to how many moved. */
-  setProjectSpace(project: ProjectInSpace, spaceId: string): Promise<number>;
-}
-
-const PREWARM_FULL_THRESHOLD = 12;
-const PREWARM_WINDOW_RADIUS = 6;
-
-const defaultIdle = {
-  request(run: () => void): number {
-    if (typeof requestIdleCallback === 'function') return requestIdleCallback(() => run());
-    return setTimeout(run, 150) as unknown as number;
-  },
-  cancel(handle: number): void {
-    if (typeof cancelIdleCallback === 'function') cancelIdleCallback(handle);
-    else clearTimeout(handle);
-  },
-};
-
-/**
- * The directory over the app's ports; nothing runs until `start()`.
- *
- * @param options - The transport, stream store, settings, views and signals.
- */
-export function createSessionDirectory<S extends SidebarListSession, P, C = unknown>(
-  options: SessionDirectoryOptions<S, P, C>,
-): SessionDirectory<S, C> {
-  type K = S['id'];
-  const { sessions, streams, views } = options;
-  const idle = options.idle ?? defaultIdle;
-  const debounceMs = options.changedDebounceMs ?? 300;
-  const pinnedSession = options.pinnedSession ?? null;
-  const notifications = createNotificationStore();
-
-  let contributionsStore: Readable<SidebarContributions> = options.contributions ?? constant(NO_SIDEBAR_CONTRIBUTIONS);
-  /** Swaps the contributions store while started (set by `start`). */
-  let followContributions: ((next: Readable<SidebarContributions>) => void) | null = null;
-
-  // One merged list per settings list and extension spaces, so an unchanged input keeps every space object.
-  let mergedFrom: { list: unknown; extension: SidebarContributions['spaces'] } | null = null;
-  let merged: readonly SidebarSpace[] = [];
-  let switcherFrom: { spaces: readonly SidebarSpace[]; prefs: unknown } | null = null;
-  let switcher: readonly SidebarSpace[] = [];
-  let hiddenSpaces: readonly SidebarSpace[] = [];
-  const spacesFrom = (settings: DirectorySettings, spaceId: string) => {
-    const spacesOn = settings.spaces;
-    const contributions = contributionsStore.get();
-    if (!mergedFrom || mergedFrom.list !== settings.spaceList || mergedFrom.extension !== contributions.spaces) {
-      mergedFrom = { list: settings.spaceList, extension: contributions.spaces };
-      merged = mergeSidebarSpaces(normalizeSpaces(settings.spaceList), settings.spaceList, contributions.spaces);
-    }
-    const spaces = merged;
-    const prefs = views.switcher.get();
-    if (!switcherFrom || switcherFrom.spaces !== spaces || switcherFrom.prefs !== prefs) {
-      switcherFrom = { spaces, prefs };
-      switcher = switcherSpaces(spaces, prefs);
-      const hidden = new Set(prefs.hidden);
-      hiddenSpaces = spaces.filter((s) => s.id !== DEFAULT_SPACE_ID && hidden.has(s.id));
-    }
-    return {
-      spacesOn,
-      spaces,
-      switcherSpaces: switcher,
-      hiddenSpaces,
-      contributions,
-      activeSpace: activeSpaceOf(spaces, spacesOn ? spaceId : DEFAULT_SPACE_ID) as SidebarSpace,
-    };
-  };
-
-  const initialSpaces = spacesFrom(options.settings.get(), views.space.get());
-  const state = writable<SessionDirectoryState<S>>({
-    allSessions: [],
-    activeSessionId: pinnedSession,
-    ...initialSpaces,
-    spaceSlide: null,
-    hostNotice: null,
-  });
-  const patch = (next: Partial<SessionDirectoryState<S>>) => {
-    const current = state.get();
-    if ((Object.keys(next) as (keyof SessionDirectoryState<S>)[]).every((k) => Object.is(current[k], next[k]))) return;
-    state.set({ ...current, ...next });
-  };
-
-  let archive: SessionArchiveFilter = options.archive ?? 'active';
-  let refreshVersion = 0;
-  const hostLists = new Map<string, readonly S[]>();
-  const hostReads = new Map<string, number>();
-
-  const refreshHosts = async (only?: ReadonlySet<string>): Promise<void> => {
-    const version = ++refreshVersion;
-    const unchanged = streams.captureRunState();
-    const filter = archive;
-    try {
-      // '' is this machine; a host dropped from the list leaves with its rows.
-      const hosts = ['', ...options.servers.get().map((host) => host.id)];
-      await Promise.all(
-        hosts
-          .filter((host) => !only || only.has(host) || !hostLists.has(host))
-          .map(async (host) => {
-            const read = (hostReads.get(host) ?? 0) + 1;
-            hostReads.set(host, read);
-            const rows = host
-              ? await sessions.query({ archive: filter, hostId: host }).catch(() => [] as readonly S[])
-              : await sessions.query({ archive: filter });
-            if (hostReads.get(host) === read) hostLists.set(host, rows);
-          }),
-      );
-      // A newer refresh owns the host list: pruning by this one's older list would drop a host it just read.
-      if (version !== refreshVersion) return;
-      for (const host of hostLists.keys()) {
-        if (!hosts.includes(host)) hostLists.delete(host);
-      }
-      const next = hosts.flatMap((host) => hostLists.get(host) ?? []);
-      // A row the stream store thinks runs but the host lists idle: ask whether it really stopped.
-      const idleRows = await Promise.all(
-        next.map(async (row) => {
-          if (row.status === 'running' || !streams.peekRunning(row.id)) return false;
-          return Promise.resolve(options.isRunning(row.id))
-            .then((running) => running === false)
-            .catch(() => false);
-        }),
-      );
-      if (version !== refreshVersion) return;
-      const runStateStable = unchanged();
-      options.onListed?.(next);
-      patch({ allSessions: next });
-      // A signal moved the run state while this read was in flight: its rows are older than the signal.
-      if (!runStateStable) return;
-      for (const [index, row] of next.entries()) {
-        if (row.status === 'running') streams.markRunning(row.id);
-        else if (idleRows[index]) streams.confirmIdle(row.id);
-      }
-      const active = state.get().activeSessionId;
-      if (active && next.some((row, index) => row.id === active && idleRows[index])) {
-        const stillIdle = streams.captureRunState();
-        const page = await options.loadEvents(active);
-        if (
-          version === refreshVersion &&
-          stillIdle() &&
-          state.get().activeSessionId === active &&
-          !streams.peekRunning(active)
-        ) {
-          streams.setEventsPage(active, page);
-        }
-      }
-    } catch (err) {
-      options.onError?.(err);
-    }
-  };
-  const refresh = () => refreshHosts();
-
-  const reconvergeActiveTranscript = () => {
-    const active = state.get().activeSessionId;
-    // A streaming run owns the transcript; a reload would race it.
-    if (
-      !active ||
-      streams.peekRunning(active) ||
-      state.get().allSessions.some((s) => s.id === active && s.status === 'running')
-    ) {
-      return;
-    }
-    const runSeqAtKickoff = streams.peekRunSeq(active);
-    options
-      .loadEvents(active)
-      .then((events) => {
-        if (
-          state.get().activeSessionId === active &&
-          !streams.peekRunning(active) &&
-          streams.peekRunSeq(active) === runSeqAtKickoff
-        ) {
-          streams.setEventsPage(active, events);
-        }
-      })
-      .catch(() => undefined);
-  };
-
-  const setActive: SessionDirectory<S, C>['setActive'] = (next) => {
-    const current = state.get().activeSessionId;
-    patch({ activeSessionId: typeof next === 'function' ? next(current) : next });
-  };
-
-  const select = (sessionId: K | null) => {
-    setActive(sessionId);
-    if (sessionId) {
-      notifications.clear(sessionId);
-      patch({ hostNotice: null });
-    }
-  };
-
-  // Prewarm: the transcripts around the open session, one per idle slot.
-  let stopPrewarm: (() => void) | null = null;
-  const prewarm = () => {
-    stopPrewarm?.();
-    stopPrewarm = null;
-    const { allSessions: raw, activeSessionId } = state.get();
-    if (raw.length === 0) return;
-    let candidates: readonly S[];
-    if (raw.length <= PREWARM_FULL_THRESHOLD) {
-      candidates = raw;
-    } else {
-      const anchor = activeSessionId ? raw.findIndex((s) => s.id === activeSessionId) : -1;
-      const center = anchor === -1 ? 0 : anchor;
-      const start = Math.max(0, center - PREWARM_WINDOW_RADIUS);
-      const end = Math.min(raw.length, center + PREWARM_WINDOW_RADIUS + 1);
-      candidates = raw.slice(start, end);
-    }
-    // The cache keeps the window, the open session and the pinned ones; the rest go.
-    const keep = new Set<K>(candidates.map((s) => s.id));
-    if (activeSessionId) keep.add(activeSessionId);
-    for (const key of options.pinned?.() ?? []) keep.add(key);
-    streams.evictExcept(keep);
-    const targets = candidates.filter((session) => !streams.hasEvents(session.id));
-    if (targets.length === 0) return;
-    let cancelled = false;
-    let handle: number | undefined;
-    const pump = (index: number): void => {
-      if (cancelled || index >= targets.length) return;
-      handle = idle.request(() => {
-        if (cancelled) return;
-        const session = targets[index]!;
-        const next = (): void => pump(index + 1);
-        if (streams.hasEvents(session.id)) {
-          next();
-          return;
-        }
-        options
-          .loadEvents(session.id, { prewarm: true })
-          .then((events) => {
-            if (cancelled) return;
-            if (!streams.hasEvents(session.id)) streams.setEventsPage(session.id, events);
-          })
-          .catch(() => {
-            /* prewarm is best-effort */
-          })
-          .finally(next);
-      });
-    };
-    pump(0);
-    stopPrewarm = () => {
-      cancelled = true;
-      if (handle !== undefined) idle.cancel(handle);
-    };
-  };
-
-  /** `direction`: the way the list slides; by default the switcher's order (a wrapping step overrides it). */
-  const showSpace = (spaceId: string, direction?: 'next' | 'prev') => {
-    const { spaces, switcherSpaces: order, activeSpace, allSessions, activeSessionId, spacesOn } = state.get();
-    const from = order.findIndex((s) => s.id === activeSpace.id);
-    const to = order.findIndex((s) => s.id === spaceId);
-    patch({
-      spaceSlide:
-        from !== -1 && to !== -1 && from !== to
-          ? { spaceId, direction: direction ?? (to > from ? 'next' : 'prev') }
-          : null,
-    });
-    const space = spaces.find((s) => s.id === spaceId) ?? activeSpaceOf(spaces, spaceId);
-    const inSpace = spaceMembership<S>(space, spaces, true);
-    const belongs = (s: S) => !s.isMain && (!spacesOn || !inSpace || inSpace(s));
-    // The conversation last open there, when it is still listed and still in that space.
-    const rememberedId = pinnedSession ? null : views.lastSessionOf(spaceId);
-    const remembered = rememberedId ? allSessions.find((s) => s.id === rememberedId && belongs(s)) : undefined;
-    // Else the open session stays open only when it belongs to the new space (closed first, so the
-    // sidebar doesn't follow it back).
-    const open = allSessions.find((s) => s.id === activeSessionId);
-    // Opened before the switch, so the sidebar's follow lands on the new space, not the old.
-    if (remembered) select(remembered.id);
-    else if (open && !open.isMain && !belongs(open)) setActive(null);
-    views.setSpace(spaceId);
-  };
-  const setActiveSpace = (spaceId: string) => showSpace(spaceId);
-
-  const listProjectSessions = async (project: ProjectInSpace): Promise<S[]> => {
-    if (!project.path) return [];
-    const { spaces } = state.get();
-    const from = resolveSessionSpace(project.spaceId, spaces);
-    // A repository's group spans machines: read every host. Otherwise only the project's own.
-    const hosts = project.repoKey ? ['', ...options.servers.get().map((host) => host.id)] : [project.hostId ?? ''];
-    const all = (
-      await Promise.all(
-        hosts.map((host) =>
-          host
-            ? sessions.query({ archive: 'all', hostId: host }).catch(() => [] as readonly S[])
-            : sessions.query({ archive: 'all' }),
-        ),
-      )
-    ).flat();
-    return all.filter(
-      (s) => !s.isMain && isProjectMember(s, project) && resolveSessionSpace(s.spaceId, spaces) === from,
-    );
-  };
-
-  const drop = async (sessionId: K): Promise<SessionRemoval> => {
-    const removed = await sessions.remove?.(sessionId);
-    streams.reset(sessionId);
-    options.onRemoved?.(sessionId);
-    views.forgetSession(sessionId);
-    setActive((current) => (current === sessionId ? null : current));
-    notifications.clear(sessionId);
-    return removed && removed.kept ? removed : { kept: false };
-  };
-
-  /** Keep derived state in step with the settings, the space and the rows. */
-  const reconcile = () => {
-    const settings = options.settings.get();
-    const spaces = spacesFrom(settings, views.space.get());
-    patch(spaces);
-    const { allSessions, activeSessionId, activeSpace, spacesOn } = state.get();
-    const shown = spaceMembership<S>(activeSpace, spaces.spaces, spacesOn);
-    const open = allSessions.find((s) => s.id === activeSessionId);
-    // Orchestration off: the main session is unlisted, so it can't stay open.
-    if (!settings.orchestration && open?.isMain) {
-      setActive(null);
-      return;
-    }
-    // Open a session from another space (a link, the palette): the sidebar follows it there.
-    if (spacesOn && !pinnedSession && open && !open.isMain) {
-      // A query space that lists it (not its own) keeps showing it.
-      if (activeSpace.query && shown?.(open)) {
-        views.rememberSession(activeSpace.id, open.id);
-        return;
-      }
-      const home = resolveSessionSpace(open.spaceId, spaces.spaces);
-      if (home !== activeSpace.id) views.setSpace(home);
-      views.rememberSession(home, open.id);
-    }
-  };
-
-  return {
-    state,
-    notifications,
-    views,
-    start() {
-      const offs: (() => void)[] = [];
-      let lastRows = state.get().allSessions;
-      let lastActive = state.get().activeSessionId;
-      offs.push(
-        state.subscribe(() => {
-          const { allSessions, activeSessionId } = state.get();
-          if (allSessions === lastRows && activeSessionId === lastActive) return;
-          lastRows = allSessions;
-          lastActive = activeSessionId;
-          reconcile();
-          prewarm();
-        }),
-      );
-      offs.push(options.settings.subscribe(reconcile));
-      offs.push(views.space.subscribe(reconcile));
-      offs.push(views.switcher.subscribe(reconcile));
-      let offContributions = contributionsStore.subscribe(reconcile);
-      offs.push(() => offContributions());
-      followContributions = (next) => {
-        offContributions();
-        contributionsStore = next;
-        offContributions = next.subscribe(reconcile);
-        reconcile();
-      };
-
-      if (sessions.onFacets) {
-        // Pushes arriving together (a refresh computes many sessions) land in one state change.
-        let pending: Map<string, Readonly<Record<string, unknown>>> | null = null;
-        let stopped = false;
-        const flush = () => {
-          const batch = pending;
-          pending = null;
-          if (stopped || !batch) return;
-          const rows = state.get().allSessions;
-          if (!rows.some((s) => batch.has(s.id))) return;
-          patch({ allSessions: rows.map((s) => (batch.has(s.id) ? { ...s, facets: batch.get(s.id)! } : s)) });
-        };
-        const off = sessions.onFacets((sessionId, facets) => {
-          if (!pending) {
-            pending = new Map();
-            queueMicrotask(flush);
-          }
-          pending.set(sessionId, facets);
-        });
-        offs.push(() => {
-          stopped = true;
-          off();
-        });
-      }
-
-      let serversKey = options.servers
-        .get()
-        .map((host) => `${host.id}:${host.status}`)
-        .join('|');
-      let lastActiveServer: { id: string | null; status: string | undefined } = { id: null, status: undefined };
-      const followActiveServer = () => {
-        const active = state.get().activeSessionId;
-        const id = active ? options.serverOf(active) : null;
-        const status = id ? options.servers.get().find((host) => host.id === id)?.status : undefined;
-        const last = lastActiveServer;
-        lastActiveServer = { id, status };
-        // The open session's server came back: its transcript may have moved on.
-        const reconnected =
-          id !== null &&
-          last.id === id &&
-          last.status !== undefined &&
-          last.status !== 'connected' &&
-          status === 'connected';
-        if (reconnected) reconvergeActiveTranscript();
-      };
-      followActiveServer();
-      offs.push(state.subscribe(followActiveServer));
-      offs.push(
-        options.servers.subscribe(() => {
-          followActiveServer();
-          const key = options.servers
-            .get()
-            .map((host) => `${host.id}:${host.status}`)
-            .join('|');
-          if (key === serversKey) return;
-          serversKey = key;
-          void refresh();
-        }),
-      );
-
-      // Runtime switch (daemon on / off): every stream belongs to the old runtime.
-      let runtime: boolean | null = null;
-      const onRuntime = options.signals?.onRuntime;
-      if (onRuntime) {
-        offs.push(
-          onRuntime((connected) => {
-            const previous = runtime;
-            runtime = connected;
-            if (previous === null || previous === connected) return;
-            streams.dropAll();
-            void refresh();
-          }),
-        );
-        offs.push(
-          onRuntime((connected) => {
-            if (!connected) return;
-            void refresh();
-            reconvergeActiveTranscript();
-          }),
-        );
-      }
-
-      const onRunEnd = options.signals?.onRunEnd;
-      if (onRunEnd) {
-        offs.push(
-          onRunEnd((sessionId, ok) => {
-            void refreshHosts(new Set([options.serverOf(sessionId) ?? '']));
-            if (sessionId === state.get().activeSessionId) return;
-            notifications.set(sessionId, ok ? 'completed' : 'error');
-          }),
-        );
-      }
-
-      const onHostRemoved = options.signals?.onHostRemoved;
-      if (onHostRemoved) {
-        offs.push(
-          onHostRemoved(({ hostId, sessionIds, notice }) => {
-            const active = state.get().activeSessionId;
-            if (active && (options.serverOf(active) === hostId || sessionIds.includes(active))) {
-              setActive(null);
-              patch({ hostNotice: notice });
-            }
-            void refresh();
-          }),
-        );
-      }
-
-      if (sessions.onChanged) {
-        let timer: ReturnType<typeof setTimeout> | null = null;
-        let activeTouched = false;
-        let touched = new Set<string>();
-        const off = sessions.onChanged((sessionId) => {
-          activeTouched ||= sessionId === state.get().activeSessionId;
-          touched.add(options.serverOf(sessionId) ?? '');
-          if (timer !== null) clearTimeout(timer);
-          timer = setTimeout(() => {
-            timer = null;
-            const hosts = touched;
-            touched = new Set();
-            void refreshHosts(hosts);
-            if (activeTouched) {
-              activeTouched = false;
-              reconvergeActiveTranscript();
-            }
-          }, debounceMs);
-        });
-        offs.push(() => {
-          off();
-          if (timer !== null) clearTimeout(timer);
-        });
-      }
-
-      void refresh();
-      return () => {
-        for (const off of offs.splice(0).reverse()) off();
-        followContributions = null;
-        stopPrewarm?.();
-        stopPrewarm = null;
-      };
-    },
-    refresh,
-    setArchive(next) {
-      if (next === archive) return;
-      archive = next;
-      void refresh();
-    },
-    select,
-    setActive,
-    dismissHostNotice: () => patch({ hostNotice: null }),
-    async create(input) {
-      const { spacesOn, activeSpace } = state.get();
-      const withSpace = spacesOn && input.spaceId === undefined ? { ...input, spaceId: activeSpace.id } : input;
-      if (!sessions.create) throw new Error('This host cannot create sessions.');
-      const created = await sessions.create(withSpace);
-      return created;
-    },
-    async rename(sessionId, title) {
-      await sessions.rename?.(sessionId, title);
-      await refresh();
-    },
-    async setFavorite(sessionId, favorite) {
-      // Optimistic: the star moves now; a failed write puts it back.
-      const flip = (value: boolean) => {
-        refreshVersion += 1;
-        patch({
-          allSessions: state.get().allSessions.map((s) => (s.id === sessionId ? { ...s, favorite: value } : s)),
-        });
-      };
-      flip(favorite);
-      try {
-        await sessions.setFavorite?.(sessionId, favorite);
-      } catch (err) {
-        flip(!favorite);
-        throw err;
-      }
-      await refresh();
-    },
-    async setArchived(sessionId, archived) {
-      await sessions.setArchived?.(sessionId, archived);
-      await refresh();
-    },
-    async archiveMany(sessionIds) {
-      try {
-        for (const id of sessionIds) await sessions.setArchived?.(id, true);
-      } finally {
-        await refresh();
-      }
-    },
-    drop,
-    async removeMany(sessionIds) {
-      let kept = 0;
-      let reason: string | undefined;
-      try {
-        for (const id of sessionIds) {
-          const result = await drop(id);
-          if (result.kept) {
-            kept += 1;
-            reason ??= result.reason;
-          }
-        }
-      } finally {
-        await refresh();
-      }
-      return reason ? { kept, reason } : { kept };
-    },
-    setActiveSpace,
-    stepSpace(delta) {
-      const { spacesOn, switcherSpaces: spaces, activeSpace } = state.get();
-      if (!spacesOn || spaces.length < 2) return false;
-      const at = spaces.findIndex((s) => s.id === activeSpace.id);
-      // Wraps: past the last space comes the first, and before the first the last.
-      const next = spaces[(at + delta + spaces.length) % spaces.length]!;
-      showSpace(next.id, delta === 1 ? 'next' : 'prev');
-      return true;
-    },
-    async setSessionSpace(sessionId, spaceId) {
-      await sessions.setSpace?.(sessionId, spaceId);
-      views.forgetSession(sessionId, spaceId);
-      await refresh();
-    },
-    setSpaceHidden(spaceId, hidden) {
-      if (spaceId === DEFAULT_SPACE_ID) return;
-      const prefs = views.switcher.get();
-      const rest = prefs.hidden.filter((id) => id !== spaceId);
-      views.setSwitcher({ ...prefs, hidden: hidden ? [...rest, spaceId] : rest });
-      if (hidden && state.get().activeSpace.id === spaceId) showSpace(DEFAULT_SPACE_ID);
-    },
-    moveSpace(spaceId, delta) {
-      const order = state.get().switcherSpaces.map((s) => s.id);
-      const at = order.indexOf(spaceId);
-      const to = at + delta;
-      if (at === -1 || to < 0 || to >= order.length) return;
-      order.splice(at, 1);
-      order.splice(to, 0, spaceId);
-      // Hidden spaces keep their place in the stored order, after the shown ones.
-      const prefs = views.switcher.get();
-      const kept = prefs.order.filter((id) => !order.includes(id));
-      views.setSwitcher({ ...prefs, order: [...order, ...kept] });
-    },
-    attachContributions(next) {
-      if (followContributions) followContributions(next);
-      else {
-        contributionsStore = next;
-        reconcile();
-      }
-      return () => {
-        if (contributionsStore !== next) return;
-        const none = constant(NO_SIDEBAR_CONTRIBUTIONS);
-        if (followContributions) followContributions(none);
-        else {
-          contributionsStore = none;
-          reconcile();
-        }
-      };
-    },
-    ...(options.saveSpace
-      ? {
-          saveViewAsSpace: async (name: string) => {
-            const { activeSpace, spaces, spacesOn, contributions } = state.get();
-            const view = views.viewOf(activeSpace.id);
-            const grouping = resolveGrouping(view, activeSpace, contributions.groups);
-            const sort = resolveSort(view, activeSpace, contributions.sorts);
-            const values = view.extension?.filters ?? {};
-            const filters = filtersForSpace(contributions.filters, activeSpace.id).flatMap(({ item }) => {
-              const query = filterQueryOf(item, values[item.id]);
-              return query ? [query] : [];
-            });
-            // The archive axis stays the new space's view's own (copied below), not part of its query.
-            const result = viewQuery({
-              space: spacesOn
-                ? { id: activeSpace.id, ...(activeSpace.query ? { query: activeSpace.query } : {}) }
-                : null,
-              view: {
-                project: view.project,
-                agent: view.agent ?? null,
-                ...(view.activity !== 'all' ? { updatedSince: ACTIVITY_BOUND[view.activity] } : {}),
-                filters,
-              },
-              knownSpaceIds: spaces.map((s) => s.id),
-            });
-            if (result.issues) throw new SessionQueryError(result.issues);
-            const taken = new Set(spaces.map((s) => s.id));
-            let n = 1;
-            while (taken.has(`view-${n}`)) n += 1;
-            const space: SidebarSpace = {
-              id: `view-${n}`,
-              name,
-              query: result.query,
-              ...(grouping.kind === 'query' ? { groupBy: grouping.groupBy } : {}),
-              ...(sort ? { sortBy: [...sort] } : {}),
-            };
-            await options.saveSpace!(space);
-            // The new space starts on the view's built-in axes; its filters are in its query now.
-            const { agent: _agent, extension: _extension, ...axes } = { ...DEFAULT_SIDEBAR_VIEW, ...view };
-            views.patch(space.id, {
-              ...axes,
-              project: null,
-              activity: 'all',
-              extension: { filters: {}, ...(grouping.kind === 'builtin' ? { group: VIEW_CHOICE } : {}) },
-            });
-            showSpace(space.id);
-            return space;
-          },
-        }
-      : {}),
-    listProjectSessions,
-    async setProjectSpace(project, spaceId) {
-      const members = await listProjectSessions(project);
-      for (const member of members) {
-        await sessions.setSpace?.(member.id, spaceId);
-        views.forgetSession(member.id, spaceId);
-      }
-      await refresh();
-      return members.length;
-    },
-  };
-}
-
-/** The activity axis as a relative `updatedAt` bound, for a saved view's query. */
-const ACTIVITY_BOUND: Record<Exclude<SessionActivityFilter, 'all'>, QueryBound> = {
-  '1d': '-1d',
-  '3d': '-3d',
-  '7d': '-7d',
-  '30d': '-30d',
-};
-
-const ACTIVITY_FILTER_MS: Record<Exclude<SessionActivityFilter, 'all'>, number> = {
-  '1d': 24 * 60 * 60 * 1000,
-  '3d': 3 * 24 * 60 * 60 * 1000,
-  '7d': 7 * 24 * 60 * 60 * 1000,
-  '30d': 30 * 24 * 60 * 60 * 1000,
-};
-
-/**
- * The project filter's key for a session: its folder's name, as a query's
- * `projectName` reads it (`projectNameOf`: `/` and `\` both separate), so a
- * view saved from the filter matches the same sessions.
- *
- * @param session - Its folder and project root.
- */
-export function projectKeyOf(session: Pick<SidebarListSession, 'projectRoot' | 'cwd'>): string {
-  return projectNameOf({ projectRoot: session.projectRoot ?? null, cwd: session.cwd }) ?? '';
-}
-
-/**
- * Every project the sessions belong to, by folder name, sorted.
- *
- * @param sessions - The listed sessions.
- */
-export function availableProjectsOf(sessions: readonly SidebarListSession[]): string[] {
-  const seen = new Set<string>();
-  for (const s of sessions) {
-    const key = projectKeyOf(s);
-    if (key) seen.add(key);
-  }
-  return Array.from(seen).sort();
-}
-
-/** How a reference names a session: its title, and its folder's name when it has one. */
-export interface SessionRef {
-  /** The session's title. */
-  title: string;
-  /** Directory basename — the sidebar's project label. Absent for a directory-less session. */
-  dir?: string;
-}
-
-/**
- * Each session's {@link SessionRef}, by id.
- *
- * @param sessions - The listed sessions.
- */
-export function sessionRefsOf(sessions: readonly SidebarListSession[]): Map<string, SessionRef> {
-  return new Map(
-    sessions.map((s) => {
-      const dir = sessionDirLabel(s.projectRoot);
-      return [s.id, dir ? { title: s.title, dir } : { title: s.title }];
-    }),
-  );
-}
-
-/**
- * The sessions the list shows: the space's (a remote session without a space
- * shows in every space), then the project and activity filters. The same
- * array when nothing filters.
- *
- * @param sessions - Every listed session.
- * @param filter - The space predicate (`null`: spaces off), the project and activity axes.
- */
-export function filterDirectorySessions<S extends SidebarListSession>(
-  sessions: readonly S[],
-  filter: {
-    inSpace: ((session: S) => boolean) | null;
-    project: string | null;
-    activity: SessionActivityFilter;
-    now?: number;
-  },
-): readonly S[] {
-  const { inSpace, project, activity } = filter;
-  if (project === null && activity === 'all' && inSpace === null) return sessions;
-  const cutoff = activity === 'all' ? 0 : (filter.now ?? Date.now()) - ACTIVITY_FILTER_MS[activity];
-  return sessions.filter((s) => {
-    if (inSpace && !inSpace(s) && !(s.hostId && !s.spaceId)) return false;
-    if (project !== null && projectKeyOf(s) !== project) return false;
-    if (cutoff > 0 && s.updatedAt < cutoff) return false;
-    return true;
-  });
-}