Skip to content

Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure

TypeScript
78.8 KB
Raw Blame
import { type MutableRefObject, useCallback, useEffect, useMemo, useRef, useState } from 'react'
import { makeTaskKey } from '@contexts/AgentTaskTrackerContext'
import { byUpdatedDesc, mergeByUpdatedDesc, mergeCatalogPage } from '@lib/catalogMerge'
import { agentChatPlaceholder, remotePlaceholder } from '@lib/chatTitle'
import type { PendingRename } from '@lib/resolveSessionTitle'
import type {
  ChatAuthorityScope,
  ChatDeleteFence,
  ChatIndex,
  ChatMetadata,
  SessionsListResult,
} from '../../../../src/types'
import {
  httpErrorStatus,
  isAuthorizationError,
  isConfirmedHostAccessRevoked,
  isHostAvailabilityError,
  isHttpServerError,
  isInvalidSessionsCursorError,
  isNetworkError,
} from '../../lib/format'
import { scheduleAfterFirstPaint } from '../scheduleAfterFirstPaint'
import { nextCatalogSequence, type useChatStore } from '../useChatStore'
import { type SessionFsmEvent, type SessionFsmStore, seedSessionSnapshots } from './sessionFsm'

const SESSION_CATALOG_PAGE_LIMIT = 50

/** A catalog page and the sequence number of the request that produced it. */
type IssuedCatalogPage = Awaited<ReturnType<ReturnType<typeof useChatStore>['listSessions']>>

async function readSessionCatalog(
  chatStore: ReturnType<typeof useChatStore>,
  agentRef: string,
  query: Parameters<ReturnType<typeof useChatStore>['listSessions']>[1],
  options: { force?: boolean } = {}
): Promise<IssuedCatalogPage> {
  try {
    return await chatStore.listSessions(agentRef, query, options)
  } catch (error) {
    // listSessions in the main process already refreshes an expired RPC token
    // and retries once on 401. A second uncached read also distinguishes a
    // catalog-specific denial from loss of Host authority.
    if (!isAuthorizationError(error) || isConfirmedHostAccessRevoked(error)) throw error
    return chatStore.listSessions(agentRef, query, { force: true })
  }
}

// R1-M1: an 'offline' pending rename (a genuine network / 5xx failure) retries on
// its own Host's listSessions polls and on every `window 'online'` event; another
// Host's poll does not spend its budget. A deterministic 5xx
// / 501 would otherwise re-issue the PATCH forever, so cap the auto-retries per
// entry: 5 rides out a transient blip and a few poll cycles before giving up,
// while keeping the request volume bounded. Only 'offline' failures count toward
// this budget — a 404 ('in-flight', waiting for the session to materialize) is a
// wait, not a failure, and is bounded instead by the flush gate (it only retries
// when a poll reports its session present), so a never-materializing session
// simply stops PATCHing without ever exhausting a budget. On exhaustion the
// optimistic local title is KEPT (no rollback, no more PATCH); an explicit fresh
// user rename replaces the entry and starts a new budget.
export const MAX_RENAME_SYNC_ATTEMPTS = 5

/**
 * useChatListController (spec-v2 §4.4) — owns the whole sidebar chat-list
 * subsystem extracted from the god-hook:
 *
 *  - the per-agent `chatList` (+ `chatListLoading`) for the SELECTED agent and
 *    its loader (`loadChatList`, which seeds the badge FSM via SERVER_SNAPSHOT);
 *  - the cross-agent "Latest sessions" list (`latestChatSessions`) and its own
 *    periodic loader;
 *  - the pending per-agent chat selection ref consumed by the parent's
 *    agent-selection effect;
 *  - chat CRUD (create / rename / delete) and the narrow mutation API the
 *    parent's remaining flows (reconciler branches, unread effects, switchToChat,
 *    sendAgentMessage, the agent-selection effect) call to keep both lists in
 *    sync.
 *
 * Design (Fase 5d): the controller is the SINGLE owner of both lists' STATE and
 * exposes semantic imperative operations (never a raw `setChatList`). The
 * active-chat flows stay in the parent and call these ops. The few parent-side
 * concerns the CRUD needs (switchToChat, scrollChatToBottom, dispatchSession,
 * clearComposerDraft, the live activeChatId) are injected through a stable
 * `host` ref the parent fills each render — the same ref-indirection idiom the
 * god-hook already uses for its live callbacks.
 */

export interface SidebarChatEntry extends ChatMetadata {
  remote?: boolean
}

/** Cross-agent sidebar entry (dev's `latestChatSessions`): a chat plus its owning agent. */
export interface LatestSidebarChatEntry extends SidebarChatEntry {
  agentRef: string
}

/** The pending selection requested for an agent before its chats have loaded. */
export type PendingChatSelection =
  | { mode: 'latest'; chatId: null }
  | { mode: 'none'; chatId: null }
  | { mode: 'specific'; chatId: string; title?: string; isRemote?: boolean }

/**
 * Parent-owned collaborators the CRUD flows need. The parent fills this ref each
 * render (after switchToChat & friends are defined) so the controller's stable
 * callbacks always reach the latest closures without recreating themselves.
 */
export interface ChatListControllerHost {
  switchToChat: (
    agentRef: string,
    chatId: string,
    options?: { onCurrentError?: (error: unknown) => void }
  ) => Promise<void>
  beginSelectionIntent: () => number
  getSelectionIntentRevision: () => number
  clearPendingSelection: (agentRef: string, preserveSpecificChatId?: string) => void
  clearActiveChat: () => void
  scrollChatToBottom: () => void
  dispatchSession: (chatKey: string, event: SessionFsmEvent) => void
  clearComposerDraft: (chatId: string) => void
  getActiveChatId: () => string | null
  /** True while a chat switch is unconfirmed: its history is loading, or a remembered transcript is shown before its last-active write settles. */
  getChatSwitchInFlight: () => boolean
  getAutoSelectedChatId: () => string | null
  markAutoSelectedChat: (chatId: string | null) => void
  shouldAutoSelectLatest: () => boolean
  /**
   * Transient feedback for a rename that genuinely failed (spec 15 §2.5). The
   * parent owns the toast stack; the controller reaches it through this ref
   * rather than taking `pushToast` as a param (its callers don't have it).
   */
  pushToast: (message: string, tone: 'success' | 'error' | 'info') => void
  /** The catalog display name for an agent reference, used in user-facing copy. */
  agentDisplayName: (agentRef: string) => string
}

interface UseChatListControllerParams {
  selectedAgent: string | null
  agentNames: string[]
  isAuthenticated: boolean
  scopeKey: string
  /**
   * The USER portion of the scope (`currentUserId ?? 'unknown-user'`), passed
   * explicitly rather than split from `scopeKey` (which is `${userId}:${teamId}`).
   * The pending-rename queue is per-user (sessions are keyed by userId server-side),
   * so it must be dropped when the user identity changes but PRESERVED across a
   * team-switch of the same user — see the teardown effect below.
   */
  authUserKey: string
  authorityScope: ChatAuthorityScope
  loadMenuData: boolean
  chatStore: ReturnType<typeof useChatStore>
  fsm: SessionFsmStore
  host: MutableRefObject<ChatListControllerHost | null>
  isHostAccessBlocked: (agentRef: string) => boolean
  getHostAuthorityEpoch: (agentRef: string) => number
  /** Changes whenever `isHostAccessBlocked` may answer differently. */
  hostAuthorityRevision: number
  onHostAccessRevoked: (agentRef: string) => void
  onHostAuthorityUncertain: (agentRef: string) => void
}

function sortableTimestamp(value: string): number {
  const timestamp = Date.parse(value)
  return Number.isFinite(timestamp) ? timestamp : 0
}

const byLastActivityDesc = (a: { lastActivityAt: string }, b: { lastActivityAt: string }) =>
  sortableTimestamp(b.lastActivityAt) - sortableTimestamp(a.lastActivityAt)

/**
 * A load-more failure the same cursor can never recover from: any client error
 * other than an authorization status (handled as authority), a request timeout
 * or a rate limit (both retryable, RFC 9110), plus the main process's own
 * status-less cursor refusal. Re-sending the cursor after a 400/404/409/410
 * only repeats the rejection, so the page chain ends here.
 */
function isTerminalCatalogCursorError(error: unknown): boolean {
  const status = httpErrorStatus(error)
  if (status === undefined) return isInvalidSessionsCursorError(error)
  return (
    status >= 400 &&
    status < 500 &&
    status !== 401 &&
    status !== 403 &&
    status !== 408 &&
    status !== 429
  )
}

function isCatalogOutageError(error: unknown): boolean {
  if (isHostAvailabilityError(error)) return false
  const status = httpErrorStatus(error)
  if (status !== undefined) return isHttpServerError(error)
  return isNetworkError(error)
}

/**
 * Classify a failed rename RPC for the pending-rename queue (spec 15 §2.5). The
 * HTTP status rides the error message as `(NNN)` (see rpcProxyClient.renameSession
 * — the raw title is never in the message). A missing status (a bare transport
 * error) is treated as a network failure.
 *  - 'not-found' (404): session not materialized server-side yet → keep pending,
 *    retry once it appears in listSessions. NOT an error; no rollback.
 *  - 'client-error' (other 4xx, such as 400 invalid title): a genuine rejection
 *    → roll the optimistic title back and toast. Authorization failures are
 *    handled separately because a generic 401/403 does not prove revocation.
 *  - 'network' (5xx / no status): transient → queue offline, retry on reconnect.
 */
function classifyRenameError(error: unknown): 'not-found' | 'client-error' | 'network' {
  const message = error instanceof Error ? error.message : String(error)
  const match = message.match(/\((\d{3})\)/)
  const status = match ? Number(match[1]) : null
  if (status === 404) return 'not-found'
  if (status === 401 || status === 403) return 'network'
  if (status !== null && status >= 400 && status < 500) return 'client-error'
  return 'network'
}

function dedupeSidebarChats<T extends SidebarChatEntry>(chats: T[]): T[] {
  const seen = new Set<string>()
  return chats.filter(chat => {
    if (seen.has(chat.id)) return false
    seen.add(chat.id)
    return true
  })
}

function knownServerMessageCount(session: SessionsListResult['items'][number]): number {
  const count = session.messageCount
  return typeof count === 'number' && Number.isFinite(count) ? Math.max(0, Math.floor(count)) : 0
}

/** A cross-agent catalog session tagged with the agent whose page reported it. */
type LatestCatalogSession = SessionsListResult['items'][number] & { agentRef: string }

/** One user rename waiting for the server (spec 15 §2.5). */
type PendingRenameEntry = {
  agentRef: string
  chatId: string
  title: string
  // Title BEFORE the first rename of the current pending chain (the last
  // non-pending value) — the rollback target. Preserved across a re-rename
  // so a rollback never restores an unconfirmed optimistic title (FIX 2).
  previousTitle: string
  state: PendingRename
  // A PATCH for this exact entry is in flight right now (FIX 1), or the local
  // write that precedes the first PATCH has not finished. Distinct from `state`
  // (the durable 'in-flight'/'offline' pending kind): this gates re-entrancy so
  // a flush poll never fires a duplicate or early PATCH.
  sending: boolean
  // R1-M1: count of GENUINE ('offline' network / 5xx) failed sync attempts
  // for THIS entry (never reset while the entry lives). A 404 ('in-flight')
  // does NOT increment it — that is a wait for materialization, not a
  // failure. Drives the retry budget above.
  failureCount: number
  // R1-M1: budget exhausted — keep the optimistic local title but stop
  // auto-retrying on polls/online. Only 'offline' entries can reach this;
  // a fresh user rename makes a new entry.
  retriesExhausted: boolean
  // The entry has left the queue for good (confirmed, rejected or revoked),
  // whether or not it was still the current entry for its key.
  settled: boolean
}

/** The selected agent's sidebar: entries keyed by chat id, "Chat <id>" placeholder. */
function mergeSelectedAgentCatalogPage(
  cached: SidebarChatEntry[],
  sessions: SessionsListResult['items'],
  renameStateFor: (chatId: string) => PendingRename
): SidebarChatEntry[] {
  return mergeCatalogPage<SidebarChatEntry, SessionsListResult['items'][number]>({
    cached,
    sessions,
    entryKey: entry => entry.id,
    sessionKey: session => session.chatId,
    entryPendingRename: entry => renameStateFor(entry.id),
    sessionPendingRename: session => renameStateFor(session.chatId),
    placeholderFor: agentChatPlaceholder,
    serverOnlyEntry: (session, title) => ({
      id: session.chatId,
      title,
      createdAt: session.lastActivityAt,
      updatedAt: session.lastActivityAt,
      // Older hosts omit messageCount. Keep that unknown value at zero instead
      // of fabricating two messages per turn and overstating Activity totals
      // when tool/system messages vary by session.
      messageCount: knownServerMessageCount(session),
      remote: true,
    }),
  })
}

function sameAuthorityScope(left: ChatAuthorityScope, right: ChatAuthorityScope): boolean {
  return (
    left.environmentKey === right.environmentKey &&
    left.userId === right.userId &&
    left.teamId === right.teamId
  )
}

/**
 * The identity a local deletion is bound to, identical to main's
 * `sameChatDeletionIdentity`: environment + user. The team is not part of it,
 * so a confirmed deletion keeps holding after a team switch.
 */
function sameChatDeletionIdentity(left: ChatAuthorityScope, right: ChatAuthorityScope): boolean {
  return left.environmentKey === right.environmentKey && left.userId === right.userId
}

export function deletedChatIdsForScope(index: ChatIndex, scope: ChatAuthorityScope): string[] {
  return [
    ...new Set(
      (index.deletedChatTombstones ?? [])
        .filter(tombstone => sameChatDeletionIdentity(tombstone.authorityScope, scope))
        .map(tombstone => tombstone.chatId)
    ),
  ]
}

export function useChatListController({
  selectedAgent,
  agentNames,
  isAuthenticated,
  scopeKey,
  authUserKey,
  authorityScope,
  loadMenuData,
  chatStore,
  fsm,
  host,
  isHostAccessBlocked,
  getHostAuthorityEpoch,
  hostAuthorityRevision,
  onHostAccessRevoked,
  onHostAuthorityUncertain,
}: UseChatListControllerParams) {
  // Per-agent list for the SELECTED agent (the sidebar's chat list).
  const [chatList, setChatList] = useState<SidebarChatEntry[]>([])
  const [chatListLoading, setChatListLoading] = useState(false)
  const [chatListMoreLoading, setChatListMoreLoading] = useState(false)
  const [chatListHasMoreRemoteSessions, setChatListHasMoreRemoteSessions] = useState(false)
  // Cross-agent "Latest sessions" list (badges live in the FSM, seeded below).
  const [latestChatSessions, setLatestChatSessions] = useState<LatestSidebarChatEntry[]>([])
  const [latestChatSessionsLoading, setLatestChatSessionsLoading] = useState(false)
  const catalogOfflineByAgentRef = useRef(new Set<string>())
  const catalogOfflineToastShownRef = useRef(false)
  const catalogOfflineToastQueuedRef = useRef(false)
  const catalogOfflineToastTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null)
  const [latestCatalogMutationRevision, setLatestCatalogMutationRevision] = useState(0)
  // Selection requested for an agent before its chats have loaded, consumed by
  // the parent's agent-selection effect. Ref (not state): imperative, per-agent.
  const pendingChatSelectionByAgentRef = useRef<Record<string, PendingChatSelection>>({})
  const suppressAutoSelectionByAgentRef = useRef<Map<string, number>>(new Map())
  const suppressAutoSelectionSequenceRef = useRef(0)
  const chatListNextCursorByAgentRef = useRef<Record<string, string | null | undefined>>({})
  const chatListLoadingMoreByAgentRef = useRef<Set<string>>(new Set())
  const deletedChatIdsByAgentRef = useRef(new Map<string, Set<string>>())
  const requestGenerationRef = useRef(0)
  const authorityScopeGenerationRef = useRef(0)
  const agentNamesRef = useRef(agentNames)
  agentNamesRef.current = agentNames
  const agentNamesKey = agentNames.join('\n')
  const currentAuthorityScopeRef = useRef(`${isAuthenticated}:${scopeKey}`)
  currentAuthorityScopeRef.current = `${isAuthenticated}:${scopeKey}`

  // Spec 15 §2.5 (B21) — pending-rename queue. A user rename is optimistic-local
  // first, then synced by RPC; while unconfirmed the local title wins over the
  // server (§2.2 cases E/F). Kept in a ref (NOT on the persisted ChatMetadata):
  // it must live in memory only and survive list rebuilds + retries. Keyed by
  // `${agentRef}:${chatId}`. `state` maps directly to `resolveSessionTitle`'s
  // `pendingRename`: 'in-flight' (PATCH sent / awaiting the session to exist
  // server-side after a 404) or 'offline' (network failure, retry on reconnect).
  const pendingRenamesRef = useRef<Map<string, PendingRenameEntry>>(new Map())
  // When each chat's latest rename left the queue, on the catalog clock
  // (`nextCatalogSequence`). A catalog page requested before that moment may
  // still carry the title the rename replaced (#1091 A21).
  const renameSettledSeqRef = useRef(new Map<string, number>())

  const pendingRenameKey = (agentRef: string, chatId: string): string => `${agentRef}:${chatId}`
  const authUserKeyRef = useRef(authUserKey)

  useEffect(() => {
    authUserKeyRef.current = authUserKey
  }, [authUserKey])

  /**
   * Takes `entry` out of the queue. Only the key's current entry deletes the key
   * and stamps the settle time; a superseded entry is only marked settled, and
   * the current entry's own settle stamps the key later. Returns whether `entry`
   * was current.
   */
  const settlePendingRename = useCallback((key: string, entry: PendingRenameEntry): boolean => {
    entry.settled = true
    if (pendingRenamesRef.current.get(key) !== entry) return false
    pendingRenamesRef.current.delete(key)
    renameSettledSeqRef.current.set(key, nextCatalogSequence())
    return true
  }, [])

  /**
   * The rename state a catalog page must respect for one chat (§2.2 E/F): a
   * pending rename's own state; 'in-flight' when the page was requested before
   * the chat's last rename settled (its title may predate the rename, so the
   * local title keeps winning); otherwise 'none'. `issueSeq` undefined means the
   * page's request time is unknown, which is treated as before the settle.
   */
  const catalogTitleRenameState = useCallback(
    (agentRef: string, chatId: string, issueSeq: number | undefined): PendingRename => {
      const key = pendingRenameKey(agentRef, chatId)
      const pending = pendingRenamesRef.current.get(key)
      if (pending) return pending.state
      const settledSeq = renameSettledSeqRef.current.get(key)
      if (settledSeq !== undefined && (issueSeq === undefined || issueSeq <= settledSeq)) {
        return 'in-flight'
      }
      return 'none'
    },
    []
  )

  // Persist server freshness and titles into the local index (spec §5.3), so a
  // cold start paints the last server title instead of the hydration
  // placeholder. A chat with a pending local rename, or a page requested before
  // its last rename settled, keeps its local title (§2.2 cases E/F).
  // Best-effort: must never block or fail the visible render.
  const persistServerSessions = useCallback(
    (agentRef: string, sessions: SessionsListResult['items'], issueSeq: number | undefined) => {
      try {
        void chatStore
          .reconcileServerSessions(
            agentRef,
            sessions.map(session => ({
              chatId: session.chatId,
              lastActivityAt: session.lastActivityAt,
              ...(session.title &&
              catalogTitleRenameState(agentRef, session.chatId, issueSeq) === 'none'
                ? { title: session.title }
                : {}),
            }))
          )
          .catch(() => undefined)
      } catch {
        // ignore — reconciliation is best-effort freshness only
      }
    },
    [chatStore.reconcileServerSessions, catalogTitleRenameState]
  )

  // Indirection so the catalog loaders (defined above the queue) can trigger a
  // retry of pending renames after a listSessions poll without depending on the
  // queue's identity. Wired in an effect once the queue is defined.
  const flushPendingRenamesRef = useRef<(serverChatKeys?: Set<string>, agentRef?: string) => void>(
    () => {}
  )

  useEffect(() => {
    requestGenerationRef.current += 1
    authorityScopeGenerationRef.current += 1
    deletedChatIdsByAgentRef.current.clear()
    catalogOfflineByAgentRef.current.clear()
    catalogOfflineToastShownRef.current = false
    // A toast queued for this scope must never flush into the next scope or
    // after unmount: the cleanup runs on both.
    return () => {
      if (catalogOfflineToastTimerRef.current !== null) {
        clearTimeout(catalogOfflineToastTimerRef.current)
        catalogOfflineToastTimerRef.current = null
      }
      catalogOfflineToastQueuedRef.current = false
    }
  }, [isAuthenticated, scopeKey])

  // R1-H1 — the pending-rename queue is per-USER identity. mcp-host keys a chat
  // session by userId (`${userSub}:rpc:${agent}:${chatId}`) and filters by
  // `conversation.user_id === userId`, so a queued rename stays legitimate across
  // a TEAM-switch of the same user and must keep syncing. Only a change of user
  // identity (logout, or login as someone else) makes the queued renames belong to
  // a foreign identity — drop them so a later flush/poll/online never PATCHes them
  // under the new user's token. Keyed on the user portion ONLY, never the combined
  // `scopeKey`: clearing on a team-switch would strip the pending marker and let
  // the server title overwrite the user's own optimistic rename on the next poll
  // (resolveSessionTitle case C). This hook is never unmounted on logout/team-switch
  // (it lives at App's root), so this effect is the queue's only identity teardown.
  // A PATCH still in flight when this runs no-ops on completion without re-inserting
  // (attemptRenameRpc's `pendingRenamesRef.current.get(key) !== entry` guard).
  useEffect(() => {
    pendingRenamesRef.current.clear()
    renameSettledSeqRef.current.clear()
  }, [authUserKey])

  const reportCatalogOffline = (agentRef: string) => {
    if (!catalogOfflineByAgentRef.current.has(agentRef)) {
      catalogOfflineByAgentRef.current.add(agentRef)
    }
    if (catalogOfflineToastShownRef.current || catalogOfflineToastQueuedRef.current) return
    catalogOfflineToastQueuedRef.current = true
    const authorityScopeGeneration = authorityScopeGenerationRef.current
    catalogOfflineToastTimerRef.current = setTimeout(() => {
      catalogOfflineToastTimerRef.current = null
      catalogOfflineToastQueuedRef.current = false
      if (authorityScopeGenerationRef.current !== authorityScopeGeneration) return
      const affectedAgents = [...catalogOfflineByAgentRef.current]
      const currentHost = host.current
      if (!currentHost || !affectedAgents.length) return
      catalogOfflineToastShownRef.current = true
      const names = affectedAgents.map(ref => currentHost.agentDisplayName(ref)).join(', ')
      currentHost.pushToast(`Chat list for ${names} is offline. Showing saved chats.`, 'info')
    }, 0)
  }

  /** A success from an earlier authority scope says nothing about this one. */
  const reportCatalogOnline = (agentRef: string, authorityScopeGeneration: number) => {
    if (authorityScopeGenerationRef.current !== authorityScopeGeneration) return
    catalogOfflineByAgentRef.current.delete(agentRef)
    if (catalogOfflineByAgentRef.current.size === 0) {
      catalogOfflineToastShownRef.current = false
    }
  }

  // Live `selectedAgent` for the stable callbacks below (they gate a chatList
  // write on "is this the selected agent"). A ref keeps the callbacks stable
  // while always reading the committed value at call time.
  const selectedAgentRef = useRef(selectedAgent)
  useEffect(() => {
    selectedAgentRef.current = selectedAgent
    setChatListHasMoreRemoteSessions(
      Boolean(selectedAgent && chatListNextCursorByAgentRef.current[selectedAgent])
    )
    setChatListMoreLoading(
      Boolean(selectedAgent && chatListLoadingMoreByAgentRef.current.has(selectedAgent))
    )
    return () => {
      if (selectedAgentRef.current === selectedAgent) {
        selectedAgentRef.current = null
      }
    }
  }, [selectedAgent])

  // ─── Cross-agent latest-sessions mutators ───

  const upsertLatestChatSession = useCallback(
    (agentRef: string, chat: SidebarChatEntry) => {
      if (
        isHostAccessBlocked(agentRef) ||
        deletedChatIdsByAgentRef.current.get(agentRef)?.has(chat.id)
      )
        return
      setLatestChatSessions(previous => {
        if (deletedChatIdsByAgentRef.current.get(agentRef)?.has(chat.id)) return previous
        const next = [
          { ...chat, agentRef },
          ...previous.filter(item => item.agentRef !== agentRef || item.id !== chat.id),
        ]
        return next.sort(byUpdatedDesc)
      })
    },
    [isHostAccessBlocked]
  )

  const hideAgent = useCallback((agentRef: string) => {
    setLatestChatSessions(previous => previous.filter(chat => chat.agentRef !== agentRef))
  }, [])

  const removeLatestChatSession = useCallback((agentRef: string, chatId: string) => {
    setLatestChatSessions(previous =>
      previous.filter(item => item.agentRef !== agentRef || item.id !== chatId)
    )
  }, [])

  // A catalog request can resolve with a pre-delete snapshot just as its owning
  // component commit lands. Tombstones are imperative truth, so reproject them
  // onto the published list after every confirmed destructive mutation.
  useEffect(() => {
    setLatestChatSessions(previous =>
      previous.filter(item => !deletedChatIdsByAgentRef.current.get(item.agentRef)?.has(item.id))
    )
  }, [latestCatalogMutationRevision])

  // ─── chatList loader (agent-scoped) ───

  const loadChatListOnce = useCallback(
    async (
      agentRef: string,
      requestGeneration: number,
      selectionIntentRevisionAtRequest: number
    ): Promise<{ index: ChatIndex; merged: SidebarChatEntry[] }> => {
      const authorityScopeGeneration = authorityScopeGenerationRef.current
      const authorityScopeAtRequest = currentAuthorityScopeRef.current
      const hostAuthorityEpoch = getHostAuthorityEpoch(agentRef)
      chatListNextCursorByAgentRef.current[agentRef] = null
      if (selectedAgentRef.current === agentRef) {
        setChatListHasMoreRemoteSessions(false)
        setChatListMoreLoading(chatListLoadingMoreByAgentRef.current.has(agentRef))
      }
      const index = await chatStore.getIndex(agentRef)
      if (
        getHostAuthorityEpoch(agentRef) !== hostAuthorityEpoch ||
        currentAuthorityScopeRef.current !== authorityScopeAtRequest ||
        isHostAccessBlocked(agentRef)
      ) {
        return { index, merged: [] }
      }
      if (
        selectedAgentRef.current !== agentRef ||
        requestGenerationRef.current !== requestGeneration
      ) {
        return { index, merged: [...index.chats].sort(byUpdatedDesc) }
      }
      const deleted = deletedChatIdsByAgentRef.current.get(agentRef) ?? new Set<string>()
      for (const chatId of deletedChatIdsForScope(index, authorityScope)) deleted.add(chatId)
      deletedChatIdsByAgentRef.current.set(agentRef, deleted)
      const merged = index.chats.filter(chat => !deleted.has(chat.id)).sort(byUpdatedDesc)
      setChatList(merged)

      const suppressionMarkerAtRequest = suppressAutoSelectionByAgentRef.current.get(agentRef)
      scheduleAfterFirstPaint(async () => {
        let serverResult: IssuedCatalogPage
        try {
          serverResult = await readSessionCatalog(chatStore, agentRef, {
            agent: agentRef,
            limit: SESSION_CATALOG_PAGE_LIMIT,
          })
        } catch (error) {
          if (
            authorityScopeGenerationRef.current === authorityScopeGeneration &&
            getHostAuthorityEpoch(agentRef) === hostAuthorityEpoch &&
            currentAuthorityScopeRef.current === authorityScopeAtRequest &&
            !isHostAccessBlocked(agentRef)
          ) {
            if (isConfirmedHostAccessRevoked(error)) onHostAccessRevoked(agentRef)
            else if (isAuthorizationError(error)) onHostAuthorityUncertain(agentRef)
            if (
              !isConfirmedHostAccessRevoked(error) &&
              !isAuthorizationError(error) &&
              isCatalogOutageError(error)
            )
              reportCatalogOffline(agentRef)
          }
          return
        }
        reportCatalogOnline(agentRef, authorityScopeGeneration)
        if (
          selectedAgentRef.current !== agentRef ||
          requestGenerationRef.current !== requestGeneration ||
          getHostAuthorityEpoch(agentRef) !== hostAuthorityEpoch ||
          currentAuthorityScopeRef.current !== authorityScopeAtRequest ||
          isHostAccessBlocked(agentRef)
        ) {
          if (
            suppressionMarkerAtRequest !== undefined &&
            suppressAutoSelectionByAgentRef.current.get(agentRef) === suppressionMarkerAtRequest
          ) {
            suppressAutoSelectionByAgentRef.current.delete(agentRef)
          }
          return
        }

        // New hosts scope the page server-side. Keep this boundary check for
        // older hosts and malformed proxy responses so another agent's catalog
        // entry can never leak into the selected agent's sidebar.
        const serverSessions = serverResult.items
          .filter(
            s =>
              s.agent === agentRef && !deletedChatIdsByAgentRef.current.get(agentRef)?.has(s.chatId)
          )
          .sort(byLastActivityDesc)
        chatListNextCursorByAgentRef.current[agentRef] = serverResult.nextCursor ?? null
        setChatListHasMoreRemoteSessions(Boolean(serverResult.nextCursor))

        // Seed sidebar session state (state/activeTaskId/pendingApproval/tokens)
        // for badges via SERVER_SNAPSHOT (D4 / §4.1 R2 owns "never degrade a live
        // task").
        seedSessionSnapshots(fsm, agentRef, serverSessions)

        // Chats the server knows but the local cache doesn't (e.g. created on
        // another device). Post-§7.1 wipe these are normal entries — no
        // "Remote ·" label, no isRemote branch; switchToChat's unified path
        // hydrates them.
        setChatList(previous => {
          // The hold is a read-time mask; keep the prior catalog for recovery.
          if (isHostAccessBlocked(agentRef)) return previous
          const visibleSessions = serverSessions.filter(
            session => !deletedChatIdsByAgentRef.current.get(agentRef)?.has(session.chatId)
          )
          const dedupedPrevious = dedupeSidebarChats(previous).filter(
            chat => !deletedChatIdsByAgentRef.current.get(agentRef)?.has(chat.id)
          )
          // §2.2 precedence (cases A-F) lives in `mergeCatalogPage`.
          return mergeSelectedAgentCatalogPage(dedupedPrevious, visibleSessions, chatId =>
            catalogTitleRenameState(agentRef, chatId, serverResult.issueSeq)
          )
        })

        // §2.5: a rename that 404'd (session not yet server-side) retries now that
        // the poll reports which sessions exist.
        flushPendingRenamesRef.current(
          new Set(serverSessions.map(s => `${agentRef}:${s.chatId}`)),
          agentRef
        )

        const latestServerSession = serverSessions[0]
        // A mode:none request suppresses this one deferred catalog result. Consume
        // it here, after the post-paint continuation reaches the auto-select gate,
        // instead of clearing it with the synchronous local-index selection.
        const suppressAutoSelection = suppressAutoSelectionByAgentRef.current.delete(agentRef)
        const currentHost = host.current
        const activeChatId = currentHost?.getActiveChatId() ?? null
        const autoSelectedChatId = currentHost?.getAutoSelectedChatId() ?? null
        const selectedLocalChat = activeChatId
          ? merged.find(chat => chat.id === activeChatId)
          : undefined
        const serverIsNewerThanSelection =
          !selectedLocalChat ||
          Date.parse(latestServerSession?.lastActivityAt ?? '') >
            Date.parse(selectedLocalChat.updatedAt)
        if (
          currentHost &&
          latestServerSession &&
          (activeChatId === null || activeChatId === autoSelectedChatId) &&
          activeChatId !== latestServerSession.chatId &&
          serverIsNewerThanSelection &&
          currentHost.shouldAutoSelectLatest() &&
          currentHost.getSelectionIntentRevision() === selectionIntentRevisionAtRequest &&
          !suppressAutoSelection
        ) {
          currentHost.markAutoSelectedChat(latestServerSession.chatId)
          void currentHost
            .switchToChat(agentRef, latestServerSession.chatId, {
              onCurrentError: error => {
                currentHost.pushToast(
                  `Could not open conversation: ${error instanceof Error ? error.message : String(error)}`,
                  'error'
                )
              },
            })
            .catch(() => undefined)
        }

        persistServerSessions(agentRef, serverSessions, serverResult.issueSeq)
      })

      return { index, merged }
    },
    [
      authorityScope,
      chatStore.getIndex,
      chatStore.listSessions,
      fsm,
      getHostAuthorityEpoch,
      isHostAccessBlocked,
      onHostAccessRevoked,
      host,
      persistServerSessions,
      catalogTitleRenameState,
    ]
  )

  const loadMoreChatSessions = useCallback(async () => {
    const agentRef = selectedAgentRef.current
    if (!agentRef) return

    const cursor = chatListNextCursorByAgentRef.current[agentRef]
    if (!cursor) {
      setChatListHasMoreRemoteSessions(false)
      return
    }
    if (chatListLoadingMoreByAgentRef.current.has(agentRef)) return

    chatListLoadingMoreByAgentRef.current.add(agentRef)
    const requestGeneration = requestGenerationRef.current
    const authorityScopeGeneration = authorityScopeGenerationRef.current
    const authorityScopeAtRequest = currentAuthorityScopeRef.current
    const hostAuthorityEpoch = getHostAuthorityEpoch(agentRef)
    setChatListMoreLoading(true)
    try {
      let serverResult: IssuedCatalogPage
      try {
        serverResult = await readSessionCatalog(
          chatStore,
          agentRef,
          { agent: agentRef, limit: SESSION_CATALOG_PAGE_LIMIT, cursor },
          { force: true }
        )
      } catch (error) {
        // The sidebar's "Load more" state belongs to whichever agent is selected
        // now; a late rejection for another agent may only touch its own cursor.
        const stillShowingRequest = () =>
          selectedAgentRef.current === agentRef &&
          requestGenerationRef.current === requestGeneration
        if (
          authorityScopeGenerationRef.current === authorityScopeGeneration &&
          getHostAuthorityEpoch(agentRef) === hostAuthorityEpoch &&
          currentAuthorityScopeRef.current === authorityScopeAtRequest &&
          !isHostAccessBlocked(agentRef)
        ) {
          if (isConfirmedHostAccessRevoked(error)) onHostAccessRevoked(agentRef)
          else if (isAuthorizationError(error)) onHostAuthorityUncertain(agentRef)
          else if (isTerminalCatalogCursorError(error)) {
            chatListNextCursorByAgentRef.current[agentRef] = null
            if (stillShowingRequest()) setChatListHasMoreRemoteSessions(false)
          } else if (stillShowingRequest() && host.current) {
            // 429, 5xx, a waking Host or a transport failure: the cursor stays
            // valid and the user retries with the same button. No automatic
            // retry is scheduled.
            const currentHost = host.current
            currentHost.pushToast(
              `Couldn't load more chats for ${currentHost.agentDisplayName(agentRef)}. Try again shortly.`,
              'info'
            )
          }
          return
        }
        if (
          requestGenerationRef.current === requestGeneration &&
          getHostAuthorityEpoch(agentRef) === hostAuthorityEpoch &&
          currentAuthorityScopeRef.current === authorityScopeAtRequest &&
          selectedAgentRef.current === agentRef
        ) {
          if (isTerminalCatalogCursorError(error)) {
            chatListNextCursorByAgentRef.current[agentRef] = null
            setChatListHasMoreRemoteSessions(false)
          } else {
            setChatListHasMoreRemoteSessions(true)
          }
        }
        return
      }
      reportCatalogOnline(agentRef, authorityScopeGeneration)
      if (
        requestGenerationRef.current !== requestGeneration ||
        getHostAuthorityEpoch(agentRef) !== hostAuthorityEpoch ||
        currentAuthorityScopeRef.current !== authorityScopeAtRequest
      ) {
        return
      }

      const serverSessions = serverResult.items.filter(
        s => s.agent === agentRef && !deletedChatIdsByAgentRef.current.get(agentRef)?.has(s.chatId)
      )
      if (
        selectedAgentRef.current !== agentRef ||
        isHostAccessBlocked(agentRef) ||
        getHostAuthorityEpoch(agentRef) !== hostAuthorityEpoch ||
        currentAuthorityScopeRef.current !== authorityScopeAtRequest
      ) {
        return
      }

      chatListNextCursorByAgentRef.current[agentRef] = serverResult.nextCursor ?? null
      setChatListHasMoreRemoteSessions(Boolean(serverResult.nextCursor))
      seedSessionSnapshots(fsm, agentRef, serverSessions)
      setChatList(previous => {
        // The hold is a read-time mask; keep the prior catalog for recovery.
        if (isHostAccessBlocked(agentRef)) return previous
        const visibleSessions = serverSessions.filter(
          session => !deletedChatIdsByAgentRef.current.get(agentRef)?.has(session.chatId)
        )
        const dedupedPrevious = dedupeSidebarChats(previous).filter(
          chat => !deletedChatIdsByAgentRef.current.get(agentRef)?.has(chat.id)
        )
        // §2.2 precedence (cases A-F) lives in `mergeCatalogPage`.
        return mergeSelectedAgentCatalogPage(dedupedPrevious, visibleSessions, chatId =>
          catalogTitleRenameState(agentRef, chatId, serverResult.issueSeq)
        )
      })

      persistServerSessions(agentRef, serverSessions, serverResult.issueSeq)
    } finally {
      chatListLoadingMoreByAgentRef.current.delete(agentRef)
      if (selectedAgentRef.current === agentRef) {
        setChatListMoreLoading(false)
      }
    }
  }, [
    chatStore.listSessions,
    fsm,
    getHostAuthorityEpoch,
    isHostAccessBlocked,
    onHostAccessRevoked,
    persistServerSessions,
    catalogTitleRenameState,
  ])

  const loadChatList = useCallback(
    async (
      agentRef: string,
      selectionIntentRevisionAtRequest: number
    ): Promise<{ index: ChatIndex; merged: SidebarChatEntry[] } | null> => {
      const requestGeneration = ++requestGenerationRef.current
      // Reuse the caller's request-start revision on retry; never capture a newer intent here.
      // One retry with a short backoff: during boot a concurrent team-switch /
      // access-catalog refresh can momentarily rebind the main-process chat
      // store, rejecting `getIndex` with "Not authenticated". Swallowing that
      // transient into an empty list blanks "Latest sessions" until the agent
      // is re-selected, so give the store one chance to settle.
      for (let attempt = 0; ; attempt++) {
        try {
          return await loadChatListOnce(
            agentRef,
            requestGeneration,
            selectionIntentRevisionAtRequest
          )
        } catch (err) {
          if (attempt === 0) {
            await new Promise(resolve => setTimeout(resolve, 300))
            if (
              selectedAgentRef.current !== agentRef ||
              requestGenerationRef.current !== requestGeneration
            ) {
              return null
            }
            continue
          }
          console.warn('[loadChatList] failed after retry, clearing list', { agentRef, err })
          if (
            selectedAgentRef.current === agentRef &&
            requestGenerationRef.current === requestGeneration
          ) {
            setChatList([])
          }
          return null
        }
      }
    },
    [loadChatListOnce]
  )

  // ─── Narrow chatList mutation API (called by the parent's remaining flows) ───

  /** Reset the selected agent's list (logout teardown / load failure). */
  const clearList = useCallback(() => {
    pendingChatSelectionByAgentRef.current = {}
    chatListNextCursorByAgentRef.current = {}
    chatListLoadingMoreByAgentRef.current.clear()
    suppressAutoSelectionByAgentRef.current.clear()
    setChatList([])
    setChatListMoreLoading(false)
    setChatListHasMoreRemoteSessions(false)
  }, [])

  /** Sidebar badge mirror: mark/clear the `unreadTerminal` flag by chat id. */
  const markUnreadInList = useCallback((chatId: string) => {
    setChatList(prev => prev.map(c => (c.id === chatId ? { ...c, unreadTerminal: true } : c)))
  }, [])
  const clearUnreadInList = useCallback((chatId: string) => {
    setChatList(prev =>
      prev.map(c => (c.id === chatId && c.unreadTerminal ? { ...c, unreadTerminal: false } : c))
    )
  }, [])

  /**
   * Optimistic provisional entry for a chat opened before its list loads (a
   * notification/deeplink `specific` selection): prepend if absent, else refresh
   * its title. chatList only — `latestChatSessions` is untouched (parity).
   */
  const upsertProvisionalEntry = useCallback((chatId: string, title: string, isRemote: boolean) => {
    const now = new Date().toISOString()
    setChatList(previous => {
      if (previous.some(chat => chat.id === chatId)) {
        return previous.map(chat =>
          chat.id === chatId ? { ...chat, title: title || chat.title } : chat
        )
      }
      return [
        {
          id: chatId,
          title,
          createdAt: now,
          updatedAt: now,
          messageCount: 0,
          remote: isRemote,
        },
        ...previous,
      ]
    })
  }, [])

  /** Re-apply a title to an existing entry after the list load (no insert). */
  const applyEntryTitle = useCallback((chatId: string, title: string) => {
    setChatList(previous =>
      previous.map(chat => (chat.id === chatId ? { ...chat, title: title || chat.title } : chat))
    )
  }, [])

  /** Latest-sessions-only title re-map (hydrate auto-title, S4). */
  const applyLatestTitle = useCallback((agentRef: string, chatId: string, title: string) => {
    setLatestChatSessions(prev =>
      prev.map(c => (c.agentRef === agentRef && c.id === chatId ? { ...c, title } : c))
    )
  }, [])

  /**
   * S4 hydrate upsert: a chat opened via a notification for the already-selected
   * agent may not be in chatList yet — append it with the resolved title, else
   * just refresh the title on the existing entry.
   */
  const upsertHydratedEntry = useCallback((meta: ChatMetadata, title: string) => {
    const agentRef = selectedAgentRef.current
    if (agentRef && deletedChatIdsByAgentRef.current.get(agentRef)?.has(meta.id)) return
    setChatList(prev =>
      agentRef && deletedChatIdsByAgentRef.current.get(agentRef)?.has(meta.id)
        ? prev
        : prev.some(c => c.id === meta.id)
          ? prev.map(c => (c.id === meta.id ? { ...c, ...meta, title, remote: false } : c))
          : [...prev, { ...meta, title }]
    )
  }, [])

  /** Evict a chat the server 404s from the selected agent's list (chatList only). */
  const removeFromList = useCallback((chatId: string) => {
    setChatList(prev => prev.filter(c => c.id !== chatId))
  }, [])

  /**
   * Sidebar freshness on send: bump this chat's updatedAt/messageCount so both
   * lists re-sort it to the top. Touches both lists (the dual-sync this
   * controller exists to own).
   */
  const bumpActivity = useCallback((agentRef: string, chatId: string, updatedAt: string) => {
    setLatestChatSessions(previous =>
      previous
        .map(chat =>
          chat.agentRef === agentRef && chat.id === chatId
            ? { ...chat, updatedAt, messageCount: chat.messageCount + 1 }
            : chat
        )
        .sort(byUpdatedDesc)
    )
    setChatList(previous =>
      previous.map(chat =>
        chat.id === chatId ? { ...chat, updatedAt, messageCount: chat.messageCount + 1 } : chat
      )
    )
  }, [])

  /** Append a freshly-created chat to both lists (create / send auto-create). */
  const appendNewEntry = useCallback(
    (agentRef: string, meta: ChatMetadata) => {
      if (deletedChatIdsByAgentRef.current.get(agentRef)?.has(meta.id)) return
      setChatList(prev => {
        if (deletedChatIdsByAgentRef.current.get(agentRef)?.has(meta.id)) return prev
        const next = prev.some(chat => chat.id === meta.id) ? prev : [...prev, meta]
        return dedupeSidebarChats(next)
      })
      upsertLatestChatSession(agentRef, meta)
    },
    [upsertLatestChatSession]
  )

  // ─── Pending selection API (consumed by the parent's agent-selection effect) ───

  const readPendingSelection = useCallback(
    (agentName: string): PendingChatSelection | undefined =>
      pendingChatSelectionByAgentRef.current[agentName],
    []
  )
  const writePendingSelection = useCallback(
    (agentName: string, selection: PendingChatSelection) => {
      pendingChatSelectionByAgentRef.current[agentName] = selection
      if (selection.mode === 'none') {
        suppressAutoSelectionSequenceRef.current += 1
        suppressAutoSelectionByAgentRef.current.set(
          agentName,
          suppressAutoSelectionSequenceRef.current
        )
      } else {
        suppressAutoSelectionByAgentRef.current.delete(agentName)
      }
    },
    []
  )
  const clearPendingSelection = useCallback(
    (agentName: string, preserveSpecificChatId?: string) => {
      const pendingSelection = pendingChatSelectionByAgentRef.current[agentName]
      // Keep a matching intent for the agent-selection effect when a direct
      // switch and route change are committed in the same turn.
      if (
        pendingSelection?.mode === 'specific' &&
        pendingSelection.chatId === preserveSpecificChatId
      )
        return
      delete pendingChatSelectionByAgentRef.current[agentName]
    },
    []
  )
  const isChatDeleted = useCallback(
    (agentRef: string, chatId: string) =>
      deletedChatIdsByAgentRef.current.get(agentRef)?.has(chatId) ?? false,
    []
  )

  // ─── Chat CRUD ───

  const handleCreateChat = useCallback(async () => {
    const agentRef = selectedAgentRef.current
    if (!agentRef) return
    const pendingSelection = readPendingSelection(agentRef)
    const activeChatIdAtCreate = host.current?.getActiveChatId() ?? null
    const chatSwitchInFlightAtCreate = host.current?.getChatSwitchInFlight() ?? false
    const selectionIntentRevision = host.current?.beginSelectionIntent()
    host.current?.clearPendingSelection(agentRef)
    const requestGeneration = requestGenerationRef.current
    const authorityScopeAtCreate = currentAuthorityScopeRef.current
    const isCurrentCreate = () =>
      selectionIntentRevision !== undefined &&
      requestGenerationRef.current === requestGeneration &&
      currentAuthorityScopeRef.current === authorityScopeAtCreate &&
      host.current?.getSelectionIntentRevision() === selectionIntentRevision
    const chatId = crypto.randomUUID()
    let meta: ChatMetadata
    try {
      meta = await chatStore.createChat(agentRef, chatId)
    } catch (error) {
      // The failed New chat invalidated whichever selection was in flight. Restore
      // its visible conversation only while this create still owns the same scope
      // and selection revision; a newer navigation must remain authoritative.
      if (isCurrentCreate()) {
        host.current?.pushToast(
          `Could not create conversation: ${error instanceof Error ? error.message : String(error)}`,
          'error'
        )
        const restoreChatId =
          pendingSelection?.mode === 'specific'
            ? pendingSelection.chatId
            : chatSwitchInFlightAtCreate
              ? activeChatIdAtCreate
              : null
        if (restoreChatId) {
          void host.current
            ?.switchToChat(agentRef, restoreChatId, {
              onCurrentError: error => {
                host.current?.pushToast(
                  `Could not restore conversation: ${error instanceof Error ? error.message : String(error)}`,
                  'error'
                )
              },
            })
            .catch(() => undefined)
        }
      }
      throw error
    }
    if (
      selectedAgentRef.current !== agentRef ||
      requestGenerationRef.current !== requestGeneration ||
      currentAuthorityScopeRef.current !== authorityScopeAtCreate
    )
      return
    chatStore.clearCachedRemoteData()
    appendNewEntry(agentRef, meta)
    if (!isCurrentCreate()) return
    host.current?.markAutoSelectedChat(null)
    await host.current?.switchToChat(agentRef, chatId, {
      onCurrentError: error => {
        host.current?.pushToast(
          `Could not open conversation: ${error instanceof Error ? error.message : String(error)}`,
          'error'
        )
      },
    })
    host.current?.scrollChatToBottom()
  }, [chatStore, appendNewEntry, host, readPendingSelection])

  /**
   * Optimistic LOCAL-only title update (spec 15 §2.5 / B19). Persists to the
   * local index and both sidebar lists WITHOUT firing the rename RPC. Used by
   * the first-turn auto-title path (which must NOT sync an un-redacted client
   * title that would race the server's COALESCE) and, internally, by the
   * user-rename handler before it syncs.
   */
  const applyLocalTitleOnly = useCallback(
    async (agentRef: string, chatId: string, newTitle: string) => {
      if (!agentRef || !isAuthenticated) return
      const requestGeneration = requestGenerationRef.current
      const authorityScopeGeneration = authorityScopeGenerationRef.current
      const authorityScopeAtDelete = currentAuthorityScopeRef.current
      const stillOwned = () =>
        authorityScopeGenerationRef.current === authorityScopeGeneration &&
        currentAuthorityScopeRef.current === authorityScopeAtDelete
      const bindingGeneration = await chatStore.getBindingGeneration()
      if (!stillOwned()) return
      const updatedAt = new Date().toISOString()
      await chatStore.renameChat(agentRef, chatId, newTitle, bindingGeneration)
      if (requestGenerationRef.current !== requestGeneration) return
      setLatestChatSessions(prev =>
        prev
          .map(chat =>
            chat.agentRef === agentRef && chat.id === chatId
              ? { ...chat, title: newTitle, updatedAt }
              : chat
          )
          .sort(byUpdatedDesc)
      )
      if (selectedAgentRef.current === agentRef) {
        setChatList(prev =>
          prev.map(c => (c.id === chatId ? { ...c, title: newTitle, updatedAt } : c))
        )
      }
    },
    [chatStore]
  )

  /**
   * Sync one pending rename to the server (spec 15 §2.5). 200 confirms and clears
   * the marker; a 404 (session not materialized yet) or a network/5xx failure
   * keeps it pending — 'in-flight' (retried when the session appears in
   * listSessions) or 'offline' (retried on reconnect) — so the local title keeps
   * winning over the server (§2.2 E/F) until it lands. A genuine 4xx rejection
   * rolls the optimistic title back and toasts. Never logs the raw title.
   */
  const attemptRenameRpc = useCallback(
    async (entry: PendingRenameEntry) => {
      const key = pendingRenameKey(entry.agentRef, entry.chatId)
      // FIX 1: never fire a duplicate PATCH for a key whose entry is already
      // sending (a flush poll landing during the initial/awaited attempt), and
      // FIX 2: only act on the entry that is STILL the current pending entry for
      // this key — a newer rename may have replaced it, and that newer attempt
      // owns the key from here on. Both guards use object identity.
      if (entry.sending) return
      if (pendingRenamesRef.current.get(key) !== entry) return
      entry.sending = true
      const authorityScopeGeneration = authorityScopeGenerationRef.current
      const hostAuthorityEpoch = getHostAuthorityEpoch(entry.agentRef)
      const requestStillCurrent = () =>
        authorityScopeGenerationRef.current === authorityScopeGeneration &&
        getHostAuthorityEpoch(entry.agentRef) === hostAuthorityEpoch
      try {
        await chatStore.renameSession(entry.agentRef, entry.chatId, entry.title)
        // Only clear if this attempt still owns the key (a stale 200 must never
        // delete a newer rename's marker — that would drop its case-E protection).
        settlePendingRename(key, entry)
      } catch (error) {
        if (
          isConfirmedHostAccessRevoked(error) &&
          requestStillCurrent() &&
          !isHostAccessBlocked(entry.agentRef)
        ) {
          onHostAccessRevoked(entry.agentRef)
          settlePendingRename(key, entry)
          return
        }
        if (isAuthorizationError(error)) {
          if (
            !requestStillCurrent() ||
            isHostAccessBlocked(entry.agentRef) ||
            pendingRenamesRef.current.get(key) !== entry
          ) {
            return
          }
          let readSucceeded = false
          try {
            await chatStore.listSessions(
              entry.agentRef,
              { agent: entry.agentRef, limit: 1 },
              { force: true }
            )
            readSucceeded = true
          } catch (readError) {
            if (!requestStillCurrent() || isHostAccessBlocked(entry.agentRef)) return
            if (isConfirmedHostAccessRevoked(readError)) {
              onHostAccessRevoked(entry.agentRef)
              settlePendingRename(key, entry)
              return
            }
          }
          if (
            !requestStillCurrent() ||
            isHostAccessBlocked(entry.agentRef) ||
            pendingRenamesRef.current.get(key) !== entry
          ) {
            return
          }
          if (readSucceeded) {
            if (settlePendingRename(key, entry) && entry.previousTitle) {
              await applyLocalTitleOnly(entry.agentRef, entry.chatId, entry.previousTitle)
            }
            host.current?.pushToast('You do not have permission to rename this chat.', 'error')
            return
          }
          // Only the structured host denial proves revocation. A generic 403
          // may be a stale/missing write capability. If the read check also
          // fails, preserve the existing uncertain-authority handling.
          onHostAuthorityUncertain(entry.agentRef)
          if (pendingRenamesRef.current.get(key) === entry) {
            entry.state = 'offline'
            entry.failureCount += 1
            if (entry.failureCount >= MAX_RENAME_SYNC_ATTEMPTS) {
              entry.retriesExhausted = true
            }
          }
          return
        }
        // A newer rename superseded this one: leave the key entirely to it — no
        // rollback, no re-mark (FIX 2).
        if (pendingRenamesRef.current.get(key) !== entry) return
        const kind = classifyRenameError(error)
        if (kind === 'client-error') {
          settlePendingRename(key, entry)
          // FIX 3: never roll back to an empty title (would blank the sidebar for
          // a chat that had no local cache entry). Clear the marker and let the
          // next poll's merge re-resolve from the server title / placeholder.
          if (entry.previousTitle) {
            await applyLocalTitleOnly(entry.agentRef, entry.chatId, entry.previousTitle)
          }
          host.current?.pushToast(
            'Could not rename the chat. Please try a different name.',
            'error'
          )
          return
        }
        // 404 → keep 'in-flight' (retry once the session exists server-side);
        // network / 5xx → 'offline' (retry on reconnect). Never rolled back.
        entry.state = kind === 'network' ? 'offline' : 'in-flight'
        // R1-M1: bound the auto-retry, but count ONLY genuine failures (network /
        // 5xx → 'offline'). A 404 ('in-flight') is not a failure — it is a WAIT
        // for the session to materialize server-side, and it must survive for as
        // long as that takes; counting it would retire a legitimate slow-to-
        // materialize rename before its PATCH could be accepted (a silent rename
        // loss). On the budget's last genuine failure, stop the entry
        // auto-retrying on future polls/online while keeping its optimistic title
        // (case E/F keeps resolving local until a fresh rename replaces it).
        if (kind === 'network') {
          entry.failureCount += 1
          if (entry.failureCount >= MAX_RENAME_SYNC_ATTEMPTS) {
            entry.retriesExhausted = true
          }
        }
      } finally {
        // Clearing on the entry object is safe even if it was deleted from the
        // Map (a superseding rename owns a different object).
        entry.sending = false
      }
    },
    [
      chatStore,
      applyLocalTitleOnly,
      getHostAuthorityEpoch,
      host,
      isHostAccessBlocked,
      onHostAccessRevoked,
      onHostAuthorityUncertain,
      settlePendingRename,
    ]
  )

  /**
   * Retry pending renames (spec 15 §2.5). An 'in-flight' entry (a 404 awaiting the
   * session to materialize server-side) is retried ONLY when a listSessions poll
   * reports its session present (`serverChatKeys` has the key) — a reconnect does
   * not make the session exist, so a bare `window 'online'` event (no keys) never
   * retries it. 'offline' entries (a network / 5xx failure) retry for the arriving
   * Host, or for every Host on reconnect when no agent filter is supplied.
   */
  const flushPendingRenames = useCallback(
    async (serverChatKeys?: Set<string>, agentRef?: string) => {
      for (const entry of [...pendingRenamesRef.current.values()]) {
        if (agentRef !== undefined && entry.agentRef !== agentRef) continue
        // FIX 1: skip a key with a PATCH already in flight (attemptRenameRpc
        // guards this too, but skipping avoids spawning a no-op).
        if (entry.sending) continue
        if (isHostAccessBlocked(entry.agentRef)) continue
        // R1-M1: skip an entry whose retry budget is spent — its optimistic title
        // stays, but it no longer PATCHes on polls/online. Only 'offline' entries
        // can ever reach this state (in-flight never counts toward the budget).
        if (entry.retriesExhausted) continue
        const key = pendingRenameKey(entry.agentRef, entry.chatId)
        // An 'in-flight' (404 waiting for materialization) retries ONLY when this
        // flush is a poll that reports its session present. `online` (no keys) and
        // a poll that does not list the session both skip it — a 404 is not
        // resolved by reconnecting, only by the session existing server-side.
        // Deliberately NOT budgeted: counting the 404 is what silently dropped a
        // legitimate slow-to-materialize rename. The accepted trade is that a
        // session which IS listed yet whose rename keeps 404ing (a backend
        // list-vs-rename inconsistency) re-PATCHes once per poll unbounded — a
        // pathological, self-resolving state, preferred over dropping the rename.
        if (entry.state === 'in-flight' && !serverChatKeys?.has(key)) continue
        await attemptRenameRpc(entry)
      }
    },
    [attemptRenameRpc, isHostAccessBlocked]
  )

  /**
   * Explicit user rename (spec 15 §2.5 / B19): optimistic local first, then sync
   * to the server via the pending-rename queue. This is the ONLY rename path that
   * fires RPC (the auto-title path uses `applyLocalTitleOnly`).
   */
  const handleRenameChatForAgent = useCallback(
    async (agentRef: string, chatId: string, newTitle: string) => {
      if (!agentRef) return
      const authUserKeyAtRequest = authUserKeyRef.current
      const key = pendingRenameKey(agentRef, chatId)
      // FIX 2: the rollback target is the title BEFORE the pending chain began.
      // If a rename is already pending for this key, preserve its `previousTitle`
      // (the last non-pending value) rather than re-reading the index — which now
      // holds the earlier rename's UNCONFIRMED optimistic title.
      const existing = pendingRenamesRef.current.get(key)
      let previousTitle: string
      if (existing) {
        previousTitle = existing.previousTitle
      } else {
        const index = await chatStore.getIndex(agentRef)
        if (authUserKeyRef.current !== authUserKeyAtRequest) return
        previousTitle = index.chats.find(c => c.id === chatId)?.title ?? ''
      }
      // Replace any prior entry: this is now the current rename for the key. A
      // still-in-flight older attempt will no-op on completion (identity guard).
      // It is registered before the local write, so a catalog page handled while
      // the write runs cannot store the old server title over it (#1091 A21);
      // `sending` keeps flushes from sending the PATCH before the write lands.
      const entry: PendingRenameEntry = {
        agentRef,
        chatId,
        title: newTitle,
        previousTitle,
        state: 'in-flight',
        sending: true,
        failureCount: 0,
        retriesExhausted: false,
        settled: false,
      }
      pendingRenamesRef.current.set(key, entry)
      try {
        await applyLocalTitleOnly(agentRef, chatId, newTitle)
      } catch (error) {
        // The local title did not change, so this rename is over. When it is
        // still current, hand the key back to the rename it replaced while that
        // rename is unsettled, so its PATCH keeps protecting its title.
        if (pendingRenamesRef.current.get(key) === entry && existing && !existing.settled) {
          pendingRenamesRef.current.set(key, existing)
        } else {
          settlePendingRename(key, entry)
        }
        throw error
      }
      entry.sending = false
      if (authUserKeyRef.current !== authUserKeyAtRequest) {
        settlePendingRename(key, entry)
        return
      }
      await attemptRenameRpc(entry)
    },
    [authUserKey, chatStore, applyLocalTitleOnly, attemptRenameRpc, settlePendingRename]
  )

  const handleRenameChat = useCallback(
    async (chatId: string, newTitle: string) => {
      const agentRef = selectedAgentRef.current
      if (!agentRef) return
      await handleRenameChatForAgent(agentRef, chatId, newTitle)
    },
    [handleRenameChatForAgent]
  )

  // Retry offline (and best-effort in-flight) pending renames when connectivity
  // returns (spec 15 §2.5 case F).
  useEffect(() => {
    const handleOnline = () => {
      void flushPendingRenames()
    }
    window.addEventListener('online', handleOnline)
    return () => window.removeEventListener('online', handleOnline)
  }, [flushPendingRenames])

  useEffect(() => {
    flushPendingRenamesRef.current = (serverChatKeys?: Set<string>, agentRef?: string) => {
      void flushPendingRenames(serverChatKeys, agentRef)
    }
  }, [flushPendingRenames])

  const captureChatDeleteFence = useCallback(
    async (
      agentRef: string
    ): Promise<{ agentRef: string; fence: ChatDeleteFence; hostAuthorityEpoch: number }> => {
      if (!agentRef || isHostAccessBlocked(agentRef)) {
        throw new Error('Chat deletion is unavailable while host access is blocked')
      }
      const hostAuthorityEpoch = getHostAuthorityEpoch(agentRef)
      const requestScope = currentAuthorityScopeRef.current
      try {
        const fence = await chatStore.captureDeleteFence(authorityScope)
        if (
          !sameAuthorityScope(fence.authorityScope, authorityScope) ||
          hostAuthorityEpoch !== getHostAuthorityEpoch(agentRef) ||
          isHostAccessBlocked(agentRef)
        ) {
          throw new Error('Chat deletion authority changed before confirmation')
        }
        return { agentRef, fence, hostAuthorityEpoch }
      } catch (error) {
        // Confirmation belongs to the destructive operation, not the visible
        // conversation. Same-scope navigation must not hide its failure.
        if (currentAuthorityScopeRef.current === requestScope) {
          host.current?.pushToast('Could not confirm chat access. Please try again.', 'error')
        }
        throw error
      }
    },
    [authorityScope, chatStore.captureDeleteFence, getHostAuthorityEpoch, host, isHostAccessBlocked]
  )

  const handleDeleteChatForAgent = useCallback(
    async (
      agentRef: string,
      chatId: string,
      deletion: { agentRef: string; fence: ChatDeleteFence; hostAuthorityEpoch: number }
    ) => {
      if (!agentRef) return
      if (
        deletion.agentRef !== agentRef ||
        !sameAuthorityScope(deletion.fence.authorityScope, authorityScope) ||
        deletion.hostAuthorityEpoch !== getHostAuthorityEpoch(agentRef) ||
        isHostAccessBlocked(agentRef)
      ) {
        // This is the current UI's synchronous confirmation click, not a late
        // result from the old scope. Explain why no deletion was dispatched.
        host.current?.pushToast(
          'Delete cancelled because chat access changed. Please try again.',
          'error'
        )
        return
      }
      const requestGeneration = requestGenerationRef.current
      const authorityScopeGeneration = authorityScopeGenerationRef.current
      const authorityScopeAtDelete = currentAuthorityScopeRef.current
      const stillOwned = () =>
        authorityScopeGenerationRef.current === authorityScopeGeneration &&
        currentAuthorityScopeRef.current === authorityScopeAtDelete
      // Stop following any in-flight task for this chat first: ack tears down the
      // SSE + connect/watchdog timers, so a later terminal can't fire onTerminal
      // and resurrect the just-deleted chat file via appendAssistantMessage.
      const deletedKey = makeTaskKey(agentRef, chatId)
      // R5 teardown: CHAT_DELETED removes the FSM entry AND emits the
      // `coordinator_release` effect (tracker.ack) — so a later terminal can't
      // fire onTerminal and resurrect the just-deleted chat file. Dispatched
      // FIRST (before the delete), preserving the ack-before-delete ordering.
      host.current?.dispatchSession(deletedKey, { type: 'CHAT_DELETED' })
      let result: Awaited<ReturnType<typeof chatStore.deleteChat>>
      try {
        result = await chatStore.deleteChat(agentRef, chatId, deletion.fence)
      } catch {
        if (stillOwned()) {
          host.current?.pushToast('Could not delete the chat. Please try again.', 'error')
        }
        return
      }
      if (!stillOwned()) return
      const deleted = deletedChatIdsByAgentRef.current.get(agentRef) ?? new Set<string>()
      deleted.add(chatId)
      deletedChatIdsByAgentRef.current.set(agentRef, deleted)
      setLatestCatalogMutationRevision(value => value + 1)
      chatStore.clearCachedRemoteData()
      host.current?.clearComposerDraft(chatId)
      removeLatestChatSession(agentRef, chatId)
      if (result.cleanupPending) {
        host.current?.pushToast(
          'Chat removed. Local transcript cleanup will retry when this team is active.',
          'info'
        )
      }
      if (requestGenerationRef.current !== requestGeneration) return
      // Post-await guards read the LIVE committed values (selectedAgentRef /
      // getActiveChatId), intentionally — if the user switched agent during the
      // delete IPC we must not yank a reselection into the agent they just left.
      if (selectedAgentRef.current !== agentRef) return

      // Functional updater: a concurrent chatList update during the delete IPC
      // await (e.g. a fresh cross-agent sessions load) must not be clobbered by a
      // stale pre-await closure snapshot. `remaining` below is only the local
      // navigation hint (best-effort), not the committed source of truth.
      setChatList(prev => prev.filter(c => c.id !== chatId))
      const remaining = chatList.filter(c => c.id !== chatId)

      if (host.current?.getActiveChatId() === chatId) {
        if (remaining.length > 0) {
          const sorted = [...remaining].sort(byUpdatedDesc)
          await host.current?.switchToChat(agentRef, sorted[0]!.id, {
            onCurrentError: error => {
              host.current?.pushToast(
                `Could not open conversation: ${error instanceof Error ? error.message : String(error)}`,
                'error'
              )
            },
          })
        } else {
          // The removed destination cannot remain the visible transcript when
          // replacement creation fails. Clear only while it is still active.
          host.current?.clearActiveChat()
          await handleCreateChat()
        }
      }
    },
    [
      authorityScope,
      chatList,
      chatStore,
      getHostAuthorityEpoch,
      isHostAccessBlocked,
      removeLatestChatSession,
      handleCreateChat,
      host,
    ]
  )

  const handleDeleteChat = useCallback(
    async (
      chatId: string,
      deletion: { agentRef: string; fence: ChatDeleteFence; hostAuthorityEpoch: number }
    ) => {
      await handleDeleteChatForAgent(deletion.agentRef, chatId, deletion)
    },
    [handleDeleteChatForAgent]
  )

  // A hold is enforced synchronously (the published list below filters held
  // Hosts, and every in-flight read compares its Host's epoch), so holding a
  // Host needs no reload. The stored list may still hold that Host's rows, but
  // its reads were discarded while it was held and those rows can be stale, so
  // the cross-agent list reloads when a held Host comes back.
  const [latestReloadRevision, setLatestReloadRevision] = useState(0)
  const heldAgentsRef = useRef(new Set<string>())
  useEffect(() => {
    const held = new Set(agentNamesRef.current.filter(agentRef => isHostAccessBlocked(agentRef)))
    const released = [...heldAgentsRef.current].some(
      agentRef => !held.has(agentRef) && agentNamesRef.current.includes(agentRef)
    )
    heldAgentsRef.current = held
    if (released) setLatestReloadRevision(revision => revision + 1)
  }, [agentNamesKey, hostAuthorityRevision, isHostAccessBlocked])

  // ─── Cross-agent latest-sessions loader (seeds badges via SERVER_SNAPSHOT) ───

  useEffect(() => {
    const requestedAgentNames = agentNamesRef.current
    if (!isAuthenticated || !loadMenuData || !requestedAgentNames.length) {
      setLatestChatSessions([])
      setLatestChatSessionsLoading(false)
      return
    }

    let cancelled = false
    const authorityScopeGeneration = authorityScopeGenerationRef.current
    const authorityScopeAtRequest = currentAuthorityScopeRef.current
    const hostAuthorityEpochByAgent = new Map(
      requestedAgentNames.map(agentRef => [agentRef, getHostAuthorityEpoch(agentRef)])
    )
    setLatestChatSessionsLoading(true)
    ;(async () => {
      try {
        const localGroups = await Promise.all(
          requestedAgentNames.map(async agentRef => {
            try {
              const index = await chatStore.getIndex(agentRef)
              if (
                currentAuthorityScopeRef.current !== authorityScopeAtRequest ||
                getHostAuthorityEpoch(agentRef) !== hostAuthorityEpochByAgent.get(agentRef) ||
                isHostAccessBlocked(agentRef)
              ) {
                return {
                  agentRef,
                  entries: [] as LatestSidebarChatEntry[],
                  deletedChatIds: [] as string[],
                }
              }
              return {
                agentRef,
                entries: index.chats.map(chat => ({
                  ...chat,
                  agentRef,
                })),
                deletedChatIds: deletedChatIdsForScope(index, authorityScope),
              }
            } catch {
              return {
                agentRef,
                entries: [] as LatestSidebarChatEntry[],
                deletedChatIds: [] as string[],
              }
            }
          })
        )
        if (cancelled || currentAuthorityScopeRef.current !== authorityScopeAtRequest) return
        for (const group of localGroups) {
          if (
            getHostAuthorityEpoch(group.agentRef) !==
              hostAuthorityEpochByAgent.get(group.agentRef) ||
            isHostAccessBlocked(group.agentRef)
          ) {
            continue
          }
          const deleted = deletedChatIdsByAgentRef.current.get(group.agentRef) ?? new Set<string>()
          for (const chatId of group.deletedChatIds) deleted.add(chatId)
          deletedChatIdsByAgentRef.current.set(group.agentRef, deleted)
        }
        setLatestChatSessions(
          localGroups
            .flatMap(group => group.entries)
            .filter(
              chat =>
                !isHostAccessBlocked(chat.agentRef) &&
                !deletedChatIdsByAgentRef.current.get(chat.agentRef)?.has(chat.id)
            )
            .sort(byUpdatedDesc)
        )
        setLatestChatSessionsLoading(false)

        await Promise.all(
          requestedAgentNames.map(async agentRef => {
            const requestStillCurrent = () =>
              !cancelled &&
              authorityScopeGenerationRef.current === authorityScopeGeneration &&
              currentAuthorityScopeRef.current === authorityScopeAtRequest &&
              getHostAuthorityEpoch(agentRef) === hostAuthorityEpochByAgent.get(agentRef) &&
              !isHostAccessBlocked(agentRef)
            // This feeds only the cross-agent sidebar preview. Do not follow
            // cursors here; the selected-agent session list exposes explicit
            // on-demand pagination through `loadMoreChatSessions`.
            let serverSessions: SessionsListResult['items'] = []
            // Undefined when the read failed: no page, so no request time.
            let issueSeq: number | undefined
            try {
              const serverResult = await readSessionCatalog(chatStore, agentRef, {
                agent: agentRef,
                limit: SESSION_CATALOG_PAGE_LIMIT,
              })
              if (!requestStillCurrent()) return
              reportCatalogOnline(agentRef, authorityScopeGeneration)
              serverSessions = serverResult.items
              issueSeq = serverResult.issueSeq
            } catch (error) {
              if (requestStillCurrent()) {
                if (isConfirmedHostAccessRevoked(error)) onHostAccessRevoked(agentRef)
                else if (isAuthorizationError(error)) onHostAuthorityUncertain(agentRef)
                if (
                  !isConfirmedHostAccessRevoked(error) &&
                  !isAuthorizationError(error) &&
                  isCatalogOutageError(error)
                ) {
                  reportCatalogOffline(agentRef)
                }
              }
            }
            if (!requestStillCurrent()) return
            const sessions: LatestCatalogSession[] = serverSessions
              .filter(
                session =>
                  session.agent === agentRef &&
                  !deletedChatIdsByAgentRef.current.get(agentRef)?.has(session.chatId)
              )
              .map(session => ({ ...session, agentRef }))
            seedSessionSnapshots(fsm, agentRef, sessions)
            // Hardening: tombstones are read again inside the updater. The filter
            // above already dropped them from `sessions`, and no test deletes a
            // chat between that filter and this updater.
            setLatestChatSessions(previous => {
              if (!requestStillCurrent()) return previous
              const deleted = deletedChatIdsByAgentRef.current.get(agentRef)
              const cached = previous.filter(
                item => item.agentRef === agentRef && !deleted?.has(item.id)
              )
              // §2.2 precedence (cases A-F) lives in `mergeCatalogPage`; merge
              // only this Host's entries so another Host's arrival preserves them.
              const merged = mergeCatalogPage<LatestSidebarChatEntry, LatestCatalogSession>({
                cached,
                sessions: sessions.filter(session => !deleted?.has(session.chatId)),
                entryKey: item => `${item.agentRef}:${item.id}`,
                sessionKey: session => `${session.agentRef}:${session.chatId}`,
                entryPendingRename: item =>
                  catalogTitleRenameState(item.agentRef, item.id, issueSeq),
                sessionPendingRename: session =>
                  catalogTitleRenameState(session.agentRef, session.chatId, issueSeq),
                placeholderFor: remotePlaceholder,
                serverOnlyEntry: (session, title) => ({
                  id: session.chatId,
                  title,
                  createdAt: session.lastActivityAt,
                  updatedAt: session.lastActivityAt,
                  messageCount: knownServerMessageCount(session),
                  remote: true,
                  agentRef: session.agentRef,
                }),
              })
              // Every writer keeps `previous` sorted, so the other Hosts' rows
              // stay sorted after the filter and one linear merge suffices.
              return mergeByUpdatedDesc(
                merged,
                previous.filter(item => item.agentRef !== agentRef)
              )
            })

            // A Host the user never selects keeps its titles across restarts too.
            if (requestStillCurrent()) persistServerSessions(agentRef, sessions, issueSeq)

            // §2.5: retry only this Host's pending renames as its poll settles.
            if (requestStillCurrent()) {
              flushPendingRenamesRef.current(
                new Set(
                  sessions
                    .filter(
                      session =>
                        !deletedChatIdsByAgentRef.current.get(agentRef)?.has(session.chatId)
                    )
                    .map(session => `${agentRef}:${session.chatId}`)
                ),
                agentRef
              )
            }
          })
        )
      } finally {
        if (!cancelled) {
          setLatestChatSessionsLoading(false)
        }
      }
    })()

    return () => {
      cancelled = true
    }
  }, [
    agentNamesKey,
    chatStore.getIndex,
    chatStore.listSessions,
    isAuthenticated,
    loadMenuData,
    scopeKey,
    fsm,
    getHostAuthorityEpoch,
    isHostAccessBlocked,
    onHostAccessRevoked,
    latestReloadRevision,
    persistServerSessions,
    catalogTitleRenameState,
  ])

  // Stable across renders whose inputs did not change, so consumers keyed on the
  // list identity do not recompute on every parent render (R1-M10).
  const visibleLatestChatSessions = useMemo(
    () => latestChatSessions.filter(session => !isHostAccessBlocked(session.agentRef)),
    // `isHostAccessBlocked` reads mutable authority state; the revision is what
    // changes when its answers do.
    // eslint-disable-next-line react-hooks/exhaustive-deps
    [latestChatSessions, isHostAccessBlocked, hostAuthorityRevision]
  )
  return {
    // State (public contract, re-exported unchanged by the parent).
    chatList: selectedAgent && isHostAccessBlocked(selectedAgent) ? [] : chatList,
    chatListLoading,
    chatListMoreLoading,
    chatListHasMoreRemoteSessions,
    latestChatSessions: visibleLatestChatSessions,
    latestChatSessionsLoading,
    hideAgent,
    // CRUD (public contract).
    handleCreateChat,
    handleRenameChat,
    handleRenameChatForAgent,
    applyLocalTitleOnly,
    captureChatDeleteFence,
    handleDeleteChat,
    handleDeleteChatForAgent,
    // Loader + list-loading control (parent agent-selection effect).
    loadChatList,
    loadMoreChatSessions,
    setChatListLoading,
    clearList,
    // Narrow chatList ops (parent flows).
    markUnreadInList,
    clearUnreadInList,
    upsertProvisionalEntry,
    applyEntryTitle,
    applyLatestTitle,
    upsertHydratedEntry,
    removeFromList,
    bumpActivity,
    appendNewEntry,
    // Pending selection.
    readPendingSelection,
    writePendingSelection,
    clearPendingSelection,
    isChatDeleted,
  }
}