Skip to content

Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.

74.8 KB
Raw Blame
import { TEXT_NOT_SUBMITTED, isChatPromptBlocked } from '@shared/text-delivery'
import { claudeScreenBlocksInput, type ChatScreenRead } from '@shared/agents/claude-screen'
import { Fragment, memo, useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState, type KeyboardEvent, type SetStateAction } from 'react'
import { renderMarkdown } from '../lib/markdown'
import { inferInterruptAfterSettle, useAgentStatus } from '../state/agentStatus'
import { useChatDraft } from '../state/chatDraft'
import { useSession } from '../session/session'
import { chipFor } from '../lib/keybindingOverrides'
import {
  canQueue,
  chatComposerPlaceholder,
  chatSendMode,
  chatSendRefusal,
  composerStandsDown,
  screenBlockedSentence,
  type ScreenBlock
} from '../lib/chatSendGate'
import type { ChatMessage, ChatPart } from '@shared/types'
import { forgetQueuedSend, queuedSendsFor, rememberQueuedSend } from '../state/chatQueued'
import { uuid } from '../lib/uuid'
import { chatPaneRefusal, chatPaneRefusalToast } from '../lib/chatPaneGate'
import { chatAgentLabel, isNearBottom, shouldFollowOnLoad, toolCardTitle, unseenAfter } from '../lib/chatPanel'
import { useSettings } from '../state/settings'
import {
  CHAT_OLDER_PAGE_BYTES,
  CHAT_TAIL_PAGE_BYTES,
  anchoredScrollTop,
  applyOlder,
  applyTail,
  tailConfirmsSends,
  unconfirmedQueuedSends,
  emptyThread,
  shouldFetchOlder,
  type ChatThread
} from '../lib/chatPaging'
import { E_UNSUPPORTED } from '@shared/rpc'
import { GROK_AMBIGUOUS_SESSION_MESSAGE, isGrokAmbiguousSessionError } from '@shared/chat-page'
import { Spinner } from '../components/Spinner'
import { newMessagesLabel } from '../lib/chatLabels'
import {
  CHAT_LIVE_RELOAD_MIN_MS,
  CHAT_OPTIMISTIC_WORKING_MS,
  CHAT_SCREEN_POLL_MS,
  REMOTE_SUGGESTION_READ_DELAYS_MS,
  SUGGESTION_BURST_MS,
  SUGGESTION_BURST_WINDOW_MS,
  endsTurn,
  TURN_END_RELOAD_DELAYS_MS,
  chatActivity,
  planLiveReload,
  screenPollTickAllowed,
  shouldPollScreen,
  turnEndReloadCarries,
  windowFocusHint
} from '../lib/chatLive'
import { BASH_COMMAND_TOOL, sentCommand } from '@shared/chat-command'
import { ChatShellCommand } from './ChatShellCommand'
import { isInteractiveBuiltin } from '@shared/chat-catalog'
import { capabilityAgentId, chatReadsLocalOnly, readsScreenDialogs } from '@shared/agents/config'
import { ChatLoadingStatus } from './ChatPanelFallback'
import { answerCardState, answerRebindPending, rebindRetryDelay, type BoundAnswerCard } from '../lib/chatAnswer'
import { AnswerControlsUpdating, PlanAnswerControls, QuestionAnswerControls } from './ChatAnswerControls'
import type { PermissionAnswer } from '@shared/agents/permission-answer'
import { ChatComposer } from './ChatComposer'
import { ChatTurnActions } from './ChatTurnActions'
import { useCodeBlockCopy } from './CodeBlockCopy'
import { useCodeHighlight } from './CodeHighlight'
import { assistantTurnEnds, chatAbsoluteTime, chatClockTime, dayDividers } from '../lib/chatThread'
import { groupToolCalls, partPosition } from '../lib/chatToolGroups'
import { thinkingLabel } from '../lib/chatThinking'
import { TODO_WRITE_TOOL, latestTodoIndex, staleTodo } from '../lib/chatTodo'
import { ChatToolGroup } from './ChatToolGroup'
import { ChatImage } from './ChatImage'
import { ChatToolDiff } from './ChatToolDiff'
import { ChatTeammateMessage } from './ChatTeammate'
import { isTeammateMessage } from '../lib/chatTeammate'
import { FALLBACK_SESSION_NOTE, transcriptReadCwd } from '../lib/transcriptSession'
import { chatPageDirection, pageChatThread } from '../lib/chatPageKeys'
import { CLAUDE_INTERRUPT_LINE, chatEscInterrupts, chatInterruptRefusalText } from '../lib/chatEscInterrupt'

// Memoized bubble: marked+DOMPurify re-ran for EVERY message on each ChatPanel render (each
// turn-finish reload, each keystroke re-render). Text is stable per message, so cache per text.
// `breaks`: a single newline is a line break, as Claude Code's own TUI renders it — without it a
// multi-line prompt, or a reply quoting one line by line (`> a` / `> b`), collapsed onto one line.
// Every code block gets a Copy button in its top-right corner (useCodeBlockCopy), and a fenced block
// whose language lib/codeHighlight.ts names is syntax-colored by Monaco (useCodeHighlight).
export const MarkdownText = memo(function MarkdownText({ text }: { text: string }) {
  const html = useMemo(() => renderMarkdown(text, { breaks: true }), [text])
  const ref = useRef<HTMLDivElement>(null)
  const copyButtons = useCodeBlockCopy(ref, html)
  useCodeHighlight(ref, html)
  return (
    <>
      <div ref={ref} className="term-chat__text" dangerouslySetInnerHTML={{ __html: html }} />
      {copyButtons}
    </>
  )
})

interface ChatPanelProps {
  nodeId: string
  sessionId?: string
  cwd?: string
  /** Managed Claude account this node runs under; resolves the transcript in the right root. */
  accountId?: string
  /** Which agent's reader to use. REQUIRED, and not cosmetic: claude's resolver falls back to the
   *  newest transcript for the cwd, so a non-claude node that arrives unlabelled is answered with
   *  another session's conversation. It was optional until 2026-09-02, defaulting to claude -- and
   *  deleting the single `agentId={agentId}` at the one mount site left the typecheck and 3767
   *  tests green while restoring that leak in full. Required makes the compiler the proof: the
   *  wiring cannot be dropped silently, with no render test needed to notice. */
  agentId: string
  /**
   * Read a transcript with no live session behind it (issue #531: a CLOSED node's conversation,
   * opened from "Recently closed"). Hides the composer — `pty.sendText` would be aimed at a node
   * id that no longer exists — and names the bar for what it is. Absent = the ⌘M panel on a live
   * node, byte-identical to before.
   */
  readOnly?: boolean
  /** Bar caption. Defaults to the ⌘M panel's own 'Chat'. */
  title?: string
  /** Rendered at the right of the bar in place of the ⌘M exit hint. */
  hint?: string
  /**
   * Resolve attached files (the composer's "+", a drop, a pasted file or screenshot) to the paths
   * the agent should read — the SAME resolution a drop onto the node's terminal uses
   * (`droppedPaths`), supplied by the mount site because only it knows the node's scope (an SSH
   * node uploads to its host over the master it runs on; a local one uses the local path, or the
   * uploads dir for clipboard bytes). Absent = no attach affordance.
   */
  pathsForFiles?: (files: File[]) => Promise<string[]>
  /**
   * Leave the ⌘M view for the node's terminal. The toolbar's model / effort labels type the
   * agent's own picker command (`/model`, `/effort`) into the pane and then call this, so the user
   * sees the picker they just opened. Absent = no labels (a label that opens a picker nobody can
   * see is worse than none).
   */
  onShowTerminal?: () => void
  /**
   * An SSH node's project scope (the same one `pathsForFiles` uploads through): the composer's `@`
   * list is the HOST's files, read over that project's master. Absent = the session's own file
   * index (this machine, or a relay peer's core).
   */
  sshProjectId?: string
  /**
   * `sessionId` is the node's PERSISTED launch id, not one a hook confirmed (lib/transcriptSession.ts).
   * It can be stale after a `/clear` or `/resume` inside the CLI, so the panel says so in one quiet
   * line, reads strictly by id (no cwd — claude's cwd-newest fallback would show another session),
   * and never offers plan/question answer controls. Absent = a hook-confirmed id, as before.
   */
  sessionFallback?: boolean
}

/**
 * Why the transcript isn't on screen. Every one of these used to render as "No conversation
 * yet.": a rejected read (this surface has no transcript reader at all) left `messages` at its
 * initial `[]` because nothing caught the rejection, and a failed resolution was indistinguishable
 * from a session nobody has spoken to. They need different words — and two of them are retryable.
 */
type LoadState = 'loading' | 'ok' | 'missing' | 'unsupported' | 'remoteUnsupported' | 'ambiguous' | 'exportError' | 'error'

/**
 * An `unreadable` read of a LOCAL-ONLY reader's node (`CHAT_LOCAL_ONLY` — agents with no remote
 * leg) can only be the remote case: core's leg for those agents answers a remote node (`remoteOnly`)
 * with `unreadable` before touching anything, while their local readers never set the flag. So the
 * agent alone names it — no renderer-side remoteness guess, and no new field on the wire (the phone
 * contract keeps `unreadable`). Retry cannot heal it, so it must not read as a transient failure.
 * Grok is NOT in that list: its remote node is read on the host (`core/remote-grok-chat.ts`), so a
 * grok `unreadable` is a real, retryable failure.
 */
const remoteReaderUnsupported = (agentId: string | undefined): boolean => !!agentId && chatReadsLocalOnly(agentId)

/**
 * An `unreadable` read of an OPENCODE node has two causes and nothing on the wire tells them apart:
 * a local `opencode export` that failed (Retry heals it) and a remote node core refuses before
 * running anything (it never heals). So its copy names both instead of guessing — and never blames
 * an unreachable host for a local failure. Through the base harness, mirroring core's routing
 * (`readChatTranscript` routes `capabilityAgentId(...) === 'opencode'` to `opencode-chat.ts`).
 * That ambiguity is why opencode is NOT in `CHAT_LOCAL_ONLY` even though it has no remote leg.
 */
const opencodeUnreadable = (agentId: string | undefined): boolean =>
  !!agentId && capabilityAgentId(agentId) === 'opencode'

const isUnsupported = (e: unknown): boolean =>
  !!e && typeof e === 'object' && (e as { code?: string }).code === E_UNSUPPORTED

/** One line each, in the user's terms: what is on screen and whether waiting will fix it.
 *  `missing` is a CLEAN miss — the (local or remote) host looked and there is no file: a transcript
 *  Claude has cleaned up (30 days by default), or a session that has not written one yet (the
 *  second heals the moment it speaks). A host that could not be ASKED is `error`, which Retry can
 *  fix — a remote grok node included, whose host is read by `core/remote-grok-chat.ts`;
 *  `remoteUnsupported` is a remote node whose agent has no remote reader, which it never can. */
const EMPTY_TEXT: Record<LoadState, { title: string; detail?: string }> = {
  loading: { title: 'Loading conversation…' },
  ok: { title: 'No conversation yet.' },
  missing: {
    title: 'No transcript found for this session.',
    detail: "It may have been cleaned up, or the session hasn't written one yet."
  },
  unsupported: {
    title: "Transcripts can't be read on this surface.",
    detail: 'Open this session on the desktop app to read its conversation.'
  },
  // `{agent}` is the node's own agent label (`agentLabel` below) — the case spans several agents.
  remoteUnsupported: { title: "Reading a remote {agent} session's transcript isn't supported yet." },
  // A remote grok id that names two sessions on the host: a fixed fact, like `unsupported` — so,
  // like it, no Retry (waiting cannot change which file is this node's).
  ambiguous: {
    title: GROK_AMBIGUOUS_SESSION_MESSAGE,
    detail: 'nodeterm will not guess which one belongs to this node.'
  },
  exportError: {
    title: "Couldn't read this opencode session.",
    detail: "opencode export failed on this machine — Retry once it works. A session on a remote host can't be read here yet."
  },
  error: {
    title: "Couldn't read the transcript.",
    detail: "The agent's host may not be reachable — Retry once it is."
  }
}

/**
 * Chat view for a chat-capable agent node (Cmd+M). Renders the session transcript as
 * markdown bubbles with collapsible tool calls, and sends new prompts into the running tmux
 * session via pty.sendText. While a turn runs, a status row closes the thread and the tail is
 * re-read (throttled) on every hook event, so the answer grows as it is written; the turn's end
 * (working -> idle) takes one final reload. Replaces the markdown-of-output overlay.
 */
export function ChatPanel({
  nodeId,
  sessionId,
  cwd,
  accountId,
  agentId,
  readOnly,
  title,
  hint,
  pathsForFiles,
  onShowTerminal,
  sshProjectId,
  sessionFallback
}: ChatPanelProps) {
  // This node's core api (stable for the session — the chat transcript and the tmux session
  // both live on the core this panel's project belongs to).
  const { api, source } = useSession()
  // Which transcript this panel reads. Keys are byte offsets into ONE file, so a thread is only
  // ever merged with a read of the same identity (see lib/chatPaging.ts).
  // The cwd a transcript read carries: none while reading the fallback id (the composer keeps `cwd`).
  const readCwd = transcriptReadCwd(cwd, sessionFallback === true)
  const identity = JSON.stringify([nodeId, sessionId ?? null, readCwd ?? null, accountId ?? null, agentId])
  const [thread, setThread] = useState<ChatThread>(() => emptyThread(identity))
  const messages = thread.messages
  // For the "scroll to latest" pill's count, read from a stable callback (markFollowing, below).
  const messagesRef = useRef<readonly ChatMessage[]>(messages)
  messagesRef.current = messages
  // Read by the async handlers, which must decide against the thread as it is NOW, not as it was
  // when the read was issued.
  const threadRef = useRef(thread)
  threadRef.current = thread
  // The optimistic bubbles sent into the CLI's queue mid-turn, drawn as "Queued" until the transcript
  // has them, each with its id in `state/chatQueued.ts`. Object identity is enough: `applyTail`
  // carries an unconfirmed send as the same object.
  const queuedRef = useRef(new WeakMap<ChatMessage, string>())
  // The identity whose remembered queued sends this mount has already drawn again (see `load`).
  const queuedRestoredForRef = useRef<string | null>(null)
  // The queued ids the thread showed at its last change: one that leaves the thread was confirmed
  // by the transcript (or its session ended) and is forgotten.
  const shownQueuedRef = useRef(new Set<string>())
  useEffect(() => {
    const now = new Set<string>()
    for (const m of thread.messages) {
      const id = queuedRef.current.get(m)
      if (id !== undefined) now.add(id)
    }
    for (const id of shownQueuedRef.current) if (!now.has(id)) forgetQueuedSend(nodeId, id)
    shownQueuedRef.current = now
  }, [thread, nodeId])
  const [loadState, setLoadState] = useState<LoadState>('loading')
  // Mirror for `attemptLive`, which runs from timers and settles, outside any render.
  const loadStateRef = useRef(loadState)
  loadStateRef.current = loadState
  // The older-page fetch (scroll-up paging): its own in-flight flag and token, and a failed page
  // gets a retry row instead of retrying on every scroll event.
  const [olderState, setOlderState] = useState<'idle' | 'loading' | 'error'>('idle')
  // A tail read in flight. Older paging waits for it: the tail can RESET the thread (see
  // applyTail), and an older page fetched against the pre-reload cursor would be thrown away. State,
  // not a ref, so the paging check re-runs when the tail lands.
  const [tailLoading, setTailLoading] = useState(false)
  // Mirror for `load`, which must not depend on it (its identity drives the initial-load effect).
  const olderStateRef = useRef(olderState)
  olderStateRef.current = olderState
  // The draft lives in a store keyed by node (state/chatDraft.ts): this panel unmounts on every
  // project switch, and a draft in component state was lost with it.
  const input = useChatDraft((s) => s.drafts[nodeId] ?? '')
  const setInput = useCallback(
    (next: SetStateAction<string>) => useChatDraft.getState().setDraft(nodeId, next),
    [nodeId]
  )
  const [readonly, setReadonly] = useState(false)
  // The last prompt this panel sent, for taking it back out of the agent's input box after an Esc.
  const lastSentRef = useRef<string | null>(null)
  const [optimistic, setOptimistic] = useState(false)
  const state = useAgentStatus((s) => s.byId[nodeId]?.state)
  // The shell-owned-pane flags, each as its own primitive selector (an object selector would
  // re-render on every hook event for every node). See lib/chatSendGate.ts for why they gate.
  const hibernated = useAgentStatus((s) => s.byId[nodeId]?.hibernated)
  const paused = useAgentStatus((s) => s.byId[nodeId]?.paused)
  const dropped = useAgentStatus((s) => s.byId[nodeId]?.dropped)
  const sessionEnded = useAgentStatus((s) => s.byId[nodeId]?.sessionEnded)
  // The request the node's managed hook is holding (plan / question / permission). The store keeps
  // the same object across same-ticket events, so this selector re-renders only on a new hold.
  const held = useAgentStatus((s) => s.byId[nodeId]?.held)
  const customAgents = useSettings((s) => s.settings.customAgents)
  // Not just `working`: a TUI dialog (`waiting`/`blocked`) would be ANSWERED by sendText's Enter,
  // and a pane whose CLI is gone (hibernated/paused/dropped/exited) is a SHELL that would execute it.
  const refusal = chatSendRefusal(agentId, { state, hibernated, paused, dropped, sessionEnded })
  // What Enter does now — `queue` lifts the `working` refusal for a CLI that queues mid-turn input.
  const sendMode = chatSendMode(agentId, { state, hibernated, paused, dropped, sessionEnded })
  // The agent's OWN dialog on the pane's screen (folder trust, /model, setup questions): no hook
  // reports those, so the state gate above cannot see them. Found by the poll (local panes, `live`
  // — the poll also clears it) or by a send core refused before writing (`live: false` — it then
  // stays until a send gets through or the view closes). `text`: the dialog's own lines.
  const [screenBlock, setScreenBlock] = useState<{ kind: ScreenBlock; text: string | null; live: boolean } | null>(
    null
  )
  const pollScreen = shouldPollScreen({
    readable: readsScreenDialogs(agentId),
    readOnly: readOnly === true,
    // An SSH node's tmux is on its host (`sshProjectId` is set exactly for those); a relay tab's
    // is on the peer. Either way each read is a network round trip.
    remote: sshProjectId !== undefined || source !== 'local',
    refusal
  })
  // The prompt Claude suggests next (`readClaudeSuggestion`), from the latest screen read. Shown as
  // the composer's placeholder only while a message could be sent and nothing else is on screen.
  const [suggestion, setSuggestion] = useState<string | null>(null)
  const shownSuggestion = !readonly && refusal === null && screenBlock === null ? suggestion : null
  // An SSH node, read after each turn instead of polled (`REMOTE_SUGGESTION_READ_DELAYS_MS`). Not a
  // relay tab: that pane is on the peer, and it has its own composer there.
  const readsRemoteSuggestion =
    readsScreenDialogs(agentId) && readOnly !== true && sshProjectId !== undefined && source === 'local'
  const agentLabel = chatAgentLabel(agentId, customAgents)
  // What the row closing the thread says (lib/chatLive.ts). `optimistic` covers the gap between a
  // send and the first hook event: set by `send`, retired by the next state change (the real state
  // takes over) or, for an agent whose hooks never report, after a bounded timeout.
  const activity = chatActivity({ refusal, optimistic, readOnly: !!readOnly })
  // The one Plan / Question card that gets answer controls (lib/chatAnswer.ts): only while the pane
  // holds a TUI dialog (`dialog` — the CLI is in the pane and waiting) and only on the card the held
  // ticket belongs to. A host whose hook script predates structured answers never sends `held`, so
  // its cards stay read-only — the terminal path is then the only one, exactly as before.
  //
  // …and only when the thread on screen was READ for that ticket (`threadHeldFor`, lib/chatAnswer.ts
  // `answerCardState`): while the hook moves held A → held B the thread can still show plan A's card
  // with no result, and matching by tool name alone would approve B from A's card. Until a tail read
  // that started under B lands, the latest card says "Updating…" instead. Keyed by the transcript
  // identity, so a session change never carries the previous thread's binding over.
  const [heldRead, setHeldRead] = useState<{ identity: string; pendingId: string | null } | null>(null)
  const threadHeldFor = heldRead && heldRead.identity === identity ? heldRead.pendingId : undefined
  const threadHeldForRef = useRef(threadHeldFor)
  threadHeldForRef.current = threadHeldFor
  // The card the last request was bound to (per transcript identity): a NEW request must surface on
  // a card the thread shows as new, never on that one — see `answerCardState`'s `previous`.
  const [boundCard, setBoundCard] = useState<(BoundAnswerCard & { identity: string }) | null>(null)
  const previousBound = boundCard && boundCard.identity === identity ? boundCard : null
  const cardState = useMemo(
    // Never on a fallback id: an answer is a WRITE bound to the live `held` ticket, and a thread read
    // from the node's launch id may not be the conversation that ticket belongs to.
    () =>
      !readOnly && !sessionFallback && refusal === 'dialog'
        ? answerCardState(messages, held, threadHeldFor, previousBound)
        : null,
    [readOnly, sessionFallback, refusal, messages, held, threadHeldFor, previousBound]
  )
  const answerCard = cardState?.kind === 'active' ? cardState : null
  const updatingCard = cardState?.kind === 'updating' ? cardState.card : null
  // The request a rebind reload is owed for (null = none): drives the forced reload and its retry.
  const rebindFor = cardState?.kind === 'updating' ? (held?.pendingId ?? null) : null
  const rebindForRef = useRef(rebindFor)
  rebindForRef.current = rebindFor
  const activePendingId = cardState?.kind === 'active' ? cardState.pendingId : null
  const activeCardKey = cardState?.kind === 'active' ? cardState.cardKey : null
  useEffect(() => {
    if (activePendingId === null || activeCardKey === null) return
    setBoundCard((b) =>
      b && b.identity === identity && b.pendingId === activePendingId && b.cardKey === activeCardKey
        ? b
        : { identity, pendingId: activePendingId, cardKey: activeCardKey }
    )
  }, [identity, activePendingId, activeCardKey])
  const msgsRef = useRef<HTMLDivElement>(null)
  const prevState = useRef(state)
  // Request token: only the NEWEST readTranscript may land. An older read resolving late (the
  // sessionId changed underneath it, or a ↻ raced the turn-finish reload) would otherwise paint
  // another session's thread over the current one. Bumped on unmount too, so a read that resolves
  // after the panel closed is dropped rather than applied to a dead component.
  const reqRef = useRef(0)
  // Scroll-follow inputs, captured BEFORE a load changes the content: was the user following the
  // bottom (updated on every scroll), and did they just send (they expect to see it land).
  const nearBottomRef = useRef(true)
  const justSentRef = useRef(false)
  // The same fact as state, for the "scroll to latest" pill: it shows exactly while the view has
  // stopped following, i.e. while a new message would land out of sight. `lastSeenRef` is the newest
  // message on screen when following stopped; the pill counts what came in after it.
  const [following, setFollowing] = useState(true)
  const lastSeenRef = useRef<ChatMessage | null>(null)
  const markFollowing = useCallback((v: boolean) => {
    nearBottomRef.current = v
    if (v) lastSeenRef.current = null
    else if (lastSeenRef.current === null) lastSeenRef.current = messagesRef.current.at(-1) ?? null
    setFollowing(v)
  }, [])
  // Token for the older-page fetch. A TAIL load bumps it too: a tail read can reset the thread
  // (see applyTail), and an older page computed against the previous cursor must not land on it.
  const olderReqRef = useRef(0)
  const olderInFlightRef = useRef(false)
  // Geometry captured just BEFORE content is inserted above the viewport (an older page, or the
  // "Loading earlier messages…" row appearing); the layout effect shifts scrollTop by the height
  // that was added, so what the user is reading stays put.
  const anchorRef = useRef<{ scrollTop: number; scrollHeight: number } | null>(null)
  // Never on a panel with no layout box (collapsed node, `display:none`): every metric is 0 there,
  // and an "anchor" at 0 would pin the view to the top of whatever loads while hidden.
  const captureAnchor = () => {
    const el = msgsRef.current
    if (el && el.clientHeight > 0) anchorRef.current = { scrollTop: el.scrollTop, scrollHeight: el.scrollHeight }
  }
  // Live refresh bookkeeping (lib/chatLive.ts `planLiveReload`). Refs, not state: none of it is
  // rendered, and a hook event must not re-render the panel just to note that it arrived.
  // - a TAIL read is in flight (any: initial, ↻, turn-end or live) — live reads never overlap one
  //   (nor an older-page fetch, `olderInFlightRef`);
  // - when the last tail read started — the throttle's clock;
  // - a hook event not yet served by a read — the trailing call, retried on settle / timer /
  //   reveal / visibilitychange;
  // - the trailing timer.
  const tailInFlightRef = useRef(false)
  const lastTailStartRef = useRef<number | null>(null)
  const livePendingRef = useRef(false)
  const liveTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null)
  const attemptLiveRef = useRef<() => void>(() => {})
  // A held-request reload asked for while a tail read was in flight: run when that read settles
  // (single-flight, like the live reads) — never dropped, since the read in flight started under the
  // PREVIOUS request and cannot bind the new one. Any read that STARTS later satisfies it.
  const heldReloadQueuedRef = useRef(false)
  // The ONE tail read a sent local command schedules (see `send`): `/model` or `!ls` fires no hook,
  // so neither a state change nor a live read would ever confirm it.
  const commandReadTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null)
  const loadRef = useRef<(live?: boolean, rebind?: boolean, carry?: boolean) => void>(() => {})
  // The turn-end settle reloads (TURN_END_RELOAD_DELAYS_MS) still to fire; cleared on unmount.
  const settleTimersRef = useRef<ReturnType<typeof setTimeout>[]>([])
  const requestHeldReloadRef = useRef<() => void>(() => {})

  // `live` = a read driven by a hook event while the agent works (see `attemptLive`), as opposed to
  // the first open, the turn-end reload and ↻. A live read is background refresh: it keeps
  // unconfirmed sends on screen (`carryUnconfirmed`), leaves a failed older page's retry row alone
  // (clearing it would re-arm a failing fetch every interval) and never flips the empty state to
  // "Loading…" (which would strobe on every hook event).
  //
  // `rebind` = the held-request reload (see `requestHeldReload`): QUIET like a live read (no
  // "Loading…", the older-page row left alone, unconfirmed sends kept), and it never cancels an
  // older-page fetch — it is only ever started with none in flight.
  //
  // `carry` = keep unconfirmed sends (`carryUnconfirmed`). Every live and rebind read does; so do the
  // turn-end settle reloads but the last (`turnEndReloadCarries`).
  const load = useCallback((live = false, rebind = false, carry = live || rebind) => {
    const token = ++reqRef.current
    if (!rebind) olderReqRef.current++
    // The held request this read starts under: once it is applied, the thread is known to show the
    // transcript as of (at least) that request. Read from the store, not the render: a hold that
    // landed since the last render is exactly what this must see.
    const heldAtStart = useAgentStatus.getState().byId[nodeId]?.held?.pendingId ?? null
    heldReloadQueuedRef.current = false
    // After this read settles: a queued held-request reload runs if the thread is still not read
    // for the request held NOW (`bound` = what the thread is read for after this read).
    const settleHeldReload = (bound: string | null | undefined) => {
      if (!heldReloadQueuedRef.current) return
      heldReloadQueuedRef.current = false
      if (answerRebindPending(useAgentStatus.getState().byId[nodeId]?.held, bound)) loadRef.current(false, true)
    }
    if (!rebind) olderInFlightRef.current = false
    if (!live && !rebind) {
      // Cancelling an older fetch (or clearing its error) removes a row ABOVE the viewport: anchor
      // it like any other change up there, or the view jumps by the row's height.
      if (olderStateRef.current !== 'idle') captureAnchor()
      setOlderState('idle')
    }
    setTailLoading(true)
    tailInFlightRef.current = true
    lastTailStartRef.current = Date.now()
    if (!live && !rebind) setLoadState((s) => (s === 'ok' ? s : 'loading')) // a reload never blanks a rendered thread
    // `nodeId` is what lets an SSH-project node resolve on its host; the rejection branch is what
    // keeps a surface that cannot read transcripts (Server Edition, relay tab) from silently
    // presenting itself as an empty conversation. Only the newest TAIL window is read — older
    // history pages in on scroll-up, and a reload merges by key instead of discarding it.
    void api.chat.readTranscript(sessionId, readCwd, accountId, nodeId, agentId, {
      maxBytes: CHAT_TAIL_PAGE_BYTES,
      thinking: true,
      rich: true,
      // A hook-driven refresh the user did not ask for: an expensive reader (opencode's export) may
      // space these out. An open, ↻, Retry or a held-request rebind is never marked.
      ...(live && !rebind ? { background: true } : {})
    }).then(
      (res) => {
        if (token !== reqRef.current) return
        setTailLoading(false)
        tailInFlightRef.current = false
        // A hook event held while this read was in flight gets its (trailing) read now.
        queueMicrotask(() => attemptLiveRef.current())
        if (!res.found) {
          // `missing` only when there is nothing of THIS transcript on screen. A reload that
          // failed to resolve (an SSH master blip) must not blank a thread the user is reading.
          const t = threadRef.current
          if (t.identity === identity && t.messages.length > 0) {
            // The thread on screen is still this transcript's: back to `ok`, or the `loading` this
            // reload set would stick and silently disable older paging (it waits for `ok`).
            setLoadState('ok')
            // Nothing was applied: the thread is still read for what it was read for before.
            settleHeldReload(threadHeldForRef.current)
            return
          }
          setThread(emptyThread(identity))
          // A read that FAILED (the host did not answer, a remote node with no reachable master)
          // is not "no transcript": it gets the error copy, and ↻ is the way out.
          setLoadState(
            !res.unreadable
              ? 'missing'
              : remoteReaderUnsupported(agentId)
                ? 'remoteUnsupported'
                : opencodeUnreadable(agentId)
                  ? 'exportError'
                  : 'error'
          )
          setHeldRead({ identity, pendingId: heldAtStart })
          settleHeldReload(heldAtStart)
          return
        }
        // A read that confirms every optimistic send retires the working row: for a local
        // command it is the ONLY signal (no hook fires). A command that starts a real turn is
        // still covered — its `working` state keeps the row (and the send refusal) on its own.
        if (tailConfirmsSends(threadRef.current, identity, res)) setOptimistic(false)
        // A remounted panel (a project switch, the card modal) draws its queued sends again: the
        // transcript does not hold a prompt the CLI has not delivered yet. Once per identity, and
        // only mid-turn: a CLI queue exists only while a turn runs, so once the agent is not working
        // the queue was delivered, or pulled back into the input box (Esc), and is forgotten.
        const restored: ChatMessage[] = []
        if (queuedRestoredForRef.current !== identity) {
          queuedRestoredForRef.current = identity
          const remembered = queuedSendsFor(nodeId, identity)
          const working = useAgentStatus.getState().byId[nodeId]?.state === 'working'
          const waiting = working ? unconfirmedQueuedSends(res, remembered) : []
          for (const r of remembered) if (!waiting.includes(r)) forgetQueuedSend(nodeId, r.id)
          for (const r of waiting) {
            const m: ChatMessage = { role: 'user', parts: [{ kind: 'text', text: r.text }] }
            queuedRef.current.set(m, r.id)
            restored.push(m)
          }
        }
        setThread((t) => {
          const next = applyTail(t, identity, res, { carryUnconfirmed: carry })
          if (restored.length === 0) return next
          const shown = new Set(next.messages.map((m) => queuedRef.current.get(m)))
          const missing = restored.filter((m) => !shown.has(queuedRef.current.get(m)))
          return missing.length === 0 ? next : { ...next, messages: [...next.messages, ...missing] }
        })
        setLoadState('ok')
        setHeldRead({ identity, pendingId: heldAtStart })
        settleHeldReload(heldAtStart)
      },
      (e: unknown) => {
        if (token !== reqRef.current) return
        setTailLoading(false)
        tailInFlightRef.current = false
        queueMicrotask(() => attemptLiveRef.current())
        // Same rule as a failed resolution: a rendered thread of this transcript stays usable.
        const t = threadRef.current
        if (t.identity === identity && t.messages.length > 0) {
          setLoadState('ok')
          settleHeldReload(threadHeldForRef.current)
          return
        }
        // …and, as there, a thread of ANOTHER transcript (the session changed under the panel) is
        // cleared: the error message must not sit under the previous session's conversation.
        if (t.identity !== identity) setThread(emptyThread(identity))
        setLoadState(isUnsupported(e) ? 'unsupported' : isGrokAmbiguousSessionError(e) ? 'ambiguous' : 'error')
        settleHeldReload(threadHeldForRef.current)
      }
    )
  }, [api, sessionId, readCwd, accountId, nodeId, agentId, identity])
  loadRef.current = load

  // Fetch the next OLDER page and prepend it. One in flight at a time; a result that arrives
  // after a newer tail load (or unmount) is dropped by its token. A `found:false` here is a failed
  // older-page load, NOT a missing transcript: the rendered thread stays, and a retry row appears.
  const loadOlder = useCallback(() => {
    const before = thread.olderCursor
    if (before === null || olderInFlightRef.current || thread.identity !== identity) return
    const token = ++olderReqRef.current
    olderInFlightRef.current = true
    captureAnchor()
    setOlderState('loading')
    const settle = () => {
      olderInFlightRef.current = false
      // A hook event held behind this page gets its (trailing) tail read now.
      queueMicrotask(() => attemptLiveRef.current())
      // …and so does a held-request reload queued behind it (`requestHeldReload`), once the page
      // has landed (microtask: after its setThread below).
      if (heldReloadQueuedRef.current) {
        heldReloadQueuedRef.current = false
        // Through the one entry point: a tail read that started meanwhile (and so already captured
        // the new request) is queued behind, never superseded.
        queueMicrotask(() => {
          if (rebindForRef.current !== null) requestHeldReloadRef.current()
        })
      }
    }
    void api.chat.readTranscript(sessionId, readCwd, accountId, nodeId, agentId, {
      before,
      maxBytes: CHAT_OLDER_PAGE_BYTES,
      thinking: true,
      rich: true
    }).then(
      (res) => {
        if (token !== olderReqRef.current) return
        settle()
        captureAnchor()
        if (!res.found) {
          setOlderState('error')
          return
        }
        setThread((t) => (t.identity === identity && t.olderCursor === before ? applyOlder(t, res) : t))
        setOlderState('idle')
      },
      () => {
        if (token !== olderReqRef.current) return
        settle()
        captureAnchor()
        setOlderState('error')
      }
    )
  }, [api, sessionId, readCwd, accountId, nodeId, agentId, identity, thread.olderCursor, thread.identity])

  // Initial load.
  useEffect(() => {
    load()
  }, [load])

  // A newly held plan / question the thread was not read for: re-read the tail now (declared after
  // the initial load, so on mount this QUEUES behind that read rather than superseding it) — or, with a
  // read in flight (it started under the previous request), queue it for that read's settle. Not
  // for a surface that cannot read transcripts at all (every read would be refused).
  // An older-page fetch in flight is waited for too, never cancelled: the user's scroll-up paging
  // must not restart because a plan was revised.
  const requestHeldReload = useCallback(() => {
    if (loadStateRef.current === 'unsupported') return
    if (tailInFlightRef.current || olderInFlightRef.current) heldReloadQueuedRef.current = true
    else loadRef.current(false, true)
  }, [])
  requestHeldReloadRef.current = requestHeldReload
  // Retries back off (`rebindRetryDelay`), counted per held request: a new one starts over.
  const rebindAttemptRef = useRef(0)
  useEffect(() => {
    rebindAttemptRef.current = 0
    // working → blocked with a new held id in the same render: the turn-end reload below (a full
    // read that starts NOW, under the new request) owns it — one read, not two.
    if (rebindFor !== null && !(prevState.current === 'working' && state !== 'working')) requestHeldReload()
  }, [rebindFor, requestHeldReload]) // eslint-disable-line react-hooks/exhaustive-deps -- `state` is read, not a trigger
  // …and while a card stays on "Updating…" with no read in flight (the reload failed, or the
  // transcript has not caught up), try again: nothing else reads the tail while the agent is
  // blocked. Also with no card on screen (A answered, B's card not read yet): the reload is quiet,
  // backs off, and stops by itself once a read under the new request lands.
  useEffect(() => {
    if (rebindFor === null || tailLoading) return
    const t = setTimeout(() => {
      rebindAttemptRef.current++
      requestHeldReload()
    }, rebindRetryDelay(rebindAttemptRef.current))
    return () => clearTimeout(t)
  }, [rebindFor, tailLoading, requestHeldReload])

  // Invalidate any in-flight read when the panel goes away.
  useEffect(
    () => () => {
      reqRef.current++
      olderReqRef.current++
      livePendingRef.current = false
      attemptLiveRef.current = () => {}
      if (liveTimerRef.current !== null) clearTimeout(liveTimerRef.current)
      liveTimerRef.current = null
      for (const t of settleTimersRef.current) clearTimeout(t)
      settleTimersRef.current = []
    },
    []
  )

  // Serve a pending hook event if the plan allows it now; otherwise leave it pending for whichever
  // retry the plan waits on. Everything is read at call time (store, geometry, visibility): it
  // runs from timers and settles, long after the render that defined it.
  attemptLiveRef.current = () => {
    if (!livePendingRef.current) return
    // This surface cannot read transcripts at all (relay tab): every live read would be refused.
    if (loadStateRef.current === 'unsupported' || loadStateRef.current === 'remoteUnsupported') {
      livePendingRef.current = false
      return
    }
    const el = msgsRef.current
    const plan = planLiveReload({
      working: useAgentStatus.getState().byId[nodeId]?.state === 'working',
      // No layout box (collapsed node, display:none) = the paging gate; a hidden document too.
      visible: !!el && el.clientHeight > 0 && !document.hidden,
      // An older page in flight counts too: `load` cancels it, and a live read every interval
      // would keep restarting the user's scroll-up paging for the whole turn.
      inFlight: tailInFlightRef.current || olderInFlightRef.current,
      now: Date.now(),
      lastStartAt: lastTailStartRef.current
    })
    switch (plan.kind) {
      case 'skip':
        livePendingRef.current = false
        return
      case 'hold':
        return
      case 'wait':
        if (liveTimerRef.current === null) {
          liveTimerRef.current = setTimeout(() => {
            liveTimerRef.current = null
            attemptLiveRef.current()
          }, plan.ms)
        }
        return
      case 'run':
        livePendingRef.current = false
        load(true)
    }
  }

  // Every hook event for this node — same-state ones included, which no zustand selector sees (the
  // store refreshes `stateAt` in place without notifying; see `onHookEvent`). While the agent is
  // working each one may have written to the transcript, so each asks for a tail refresh.
  useEffect(
    () =>
      useAgentStatus.getState().onHookEvent(nodeId, () => {
        livePendingRef.current = true
        attemptLiveRef.current()
      }),
    [nodeId]
  )

  // A tab that comes back into view serves what was held while it was hidden.
  useEffect(() => {
    const onVisibility = () => attemptLiveRef.current()
    document.addEventListener('visibilitychange', onVisibility)
    return () => document.removeEventListener('visibilitychange', onVisibility)
  }, [])

  // Reload when a turn completes (working -> not working), then again on the settle schedule
  // (TURN_END_RELOAD_DELAYS_MS): the Stop hook lands before the final reply is written, so the read
  // at the edge usually misses it. A new turn does NOT cancel the schedule: a prompt sent the moment
  // the turn ended starts one at once, and cancelling there would hide the finished turn's reply
  // until the next one ended. Sessions whose hooks never report `working` never take this path —
  // the bar's ↻ is their reload.
  useEffect(() => {
    if (prevState.current === 'working' && state !== 'working') {
      load(false, false, true)
      for (const t of settleTimersRef.current) clearTimeout(t)
      const last = TURN_END_RELOAD_DELAYS_MS.length - 1
      settleTimersRef.current = TURN_END_RELOAD_DELAYS_MS.map((ms, i) =>
        setTimeout(() => {
          const working = useAgentStatus.getState().byId[nodeId]?.state === 'working'
          loadRef.current(false, false, turnEndReloadCarries({ final: i === last, working }))
        }, ms)
      )
    }
    prevState.current = state
  }, [state, load, nodeId])

  // Any state change retires the optimistic working row: from here the real state speaks. And a
  // suggestion belongs to the turn that ended: the next read brings the new one.
  useEffect(() => {
    setOptimistic(false)
    setSuggestion(null)
  }, [state])

  // Right after a turn ends, read faster until Claude's suggestion is on screen (`SUGGESTION_BURST_MS`).
  // Same gates as the regular poll, which keeps running beside it for dialogs.
  const lastTurnStateRef = useRef(state)
  useEffect(() => {
    const prev = lastTurnStateRef.current
    lastTurnStateRef.current = state
    if (!pollScreen || !endsTurn(prev, state)) return
    let cancelled = false
    let inFlight = false
    const until = Date.now() + SUGGESTION_BURST_WINDOW_MS
    const t = setInterval(() => {
      if (Date.now() > until) {
        clearInterval(t)
        return
      }
      const el = msgsRef.current
      if (inFlight || el === null || el.clientHeight === 0) return
      if (!screenPollTickAllowed({ hidden: document.hidden, focused: windowFocusHint(document) })) return
      inFlight = true
      void api.pty
        .readChatScreen(nodeId, agentId)
        .then((r) => {
          if (cancelled || r.screen.kind === 'unknown' || r.suggestion === null) return
          setSuggestion(r.suggestion)
          clearInterval(t)
        })
        .catch(() => undefined)
        .finally(() => {
          inFlight = false
        })
    }, SUGGESTION_BURST_MS)
    return () => {
      cancelled = true
      clearInterval(t)
    }
  }, [pollScreen, state, api, nodeId, agentId])

  useEffect(() => {
    if (!readsRemoteSuggestion || state !== 'done') return
    let cancelled = false
    const read = async (): Promise<void> => {
      const el = msgsRef.current
      if (el === null || el.clientHeight === 0 || document.hidden) return
      try {
        const r = await api.pty.readChatScreen(nodeId, agentId)
        if (!cancelled && r.screen.kind !== 'unknown') setSuggestion(r.suggestion)
      } catch {
        // A failed read offers nothing; the next turn reads again.
      }
    }
    const timers = REMOTE_SUGGESTION_READ_DELAYS_MS.map((ms) => setTimeout(() => void read(), ms))
    return () => {
      cancelled = true
      for (const t of timers) clearTimeout(t)
    }
  }, [readsRemoteSuggestion, state, api, nodeId, agentId])
  useEffect(() => {
    if (!optimistic) return
    const t = setTimeout(() => setOptimistic(false), CHAT_OPTIMISTIC_WORKING_MS)
    return () => clearTimeout(t)
  }, [optimistic])

  // Re-read the pane's screen while the view is visible (see `screenBlock`). A read that fails or
  // finds a blank screen changes nothing: unknown is not evidence either way.
  // Ticks are skipped while the window is unfocused (`screenPollTickAllowed`: ~30 tmux spawns a
  // minute per chat view otherwise), and coming back — `focus`, or the page turning
  // visible — re-reads at once, so a dialog that opened meanwhile is on screen before anyone types.
  useEffect(() => {
    if (!pollScreen) {
      setScreenBlock((b) => (b?.live === true ? null : b))
      return
    }
    let cancelled = false
    // A focus re-tick can land while the interval's read is still out; one read at a time.
    let inFlight = false
    const tick = async (): Promise<void> => {
      const el = msgsRef.current
      if (el === null || el.clientHeight === 0 || inFlight) return
      if (!screenPollTickAllowed({ hidden: document.hidden, focused: windowFocusHint(document) })) return
      let result: ChatScreenRead
      inFlight = true
      try {
        // One styled read answers both: who owns the keyboard, and the prompt Claude suggests next.
        result = await api.pty.readChatScreen(nodeId, agentId)
      } catch {
        return
      } finally {
        inFlight = false
      }
      if (cancelled) return
      const read = result.screen
      if (read.kind === 'unknown') return
      setSuggestion(result.suggestion)
      if (!claudeScreenBlocksInput(read)) setScreenBlock(null)
      else if (read.kind === 'dialog') setScreenBlock({ kind: 'dialog', text: read.text, live: true })
      else setScreenBlock({ kind: 'no-prompt', text: null, live: true })
    }
    void tick()
    const t = setInterval(() => void tick(), CHAT_SCREEN_POLL_MS)
    const onReturn = (): void => void tick()
    window.addEventListener('focus', onReturn)
    document.addEventListener('visibilitychange', onReturn)
    return () => {
      cancelled = true
      clearInterval(t)
      window.removeEventListener('focus', onReturn)
      document.removeEventListener('visibilitychange', onReturn)
    }
  }, [pollScreen, api, nodeId, agentId])

  // Follow the newest message only when the user was already at the bottom or just sent; a user
  // scrolled up reading an earlier answer keeps their place. Layout effect: the jump lands before
  // paint, so a followed thread never flashes one frame short.
  //
  // Content inserted ABOVE the viewport (an older page, the loading row) is the other case: there
  // the anchor captured before the change wins, and the view is shifted by exactly the added
  // height — no jump, and no follow (the user is at the top, reading history).
  useLayoutEffect(() => {
    const el = msgsRef.current
    if (!el) return
    const anchor = anchorRef.current
    if (anchor) {
      anchorRef.current = null
      el.scrollTop = anchoredScrollTop(anchor, el.scrollHeight)
      return
    }
    if (shouldFollowOnLoad({ wasNearBottom: nearBottomRef.current, justSent: justSentRef.current })) {
      el.scrollTop = el.scrollHeight
      markFollowing(true)
    }
    justSentRef.current = false
    // `activity` / `screenBlock`: a row appearing at the end grows the thread like a message does.
  }, [messages, olderState, activity, screenBlock, markFollowing])

  const maybeLoadOlder = useCallback(() => {
    const el = msgsRef.current
    if (!el) return
    if (
      shouldFetchOlder({
        scrollTop: el.scrollTop,
        scrollHeight: el.scrollHeight,
        clientHeight: el.clientHeight,
        olderCursor: thread.identity === identity ? thread.olderCursor : null,
        inFlight: olderInFlightRef.current || tailLoading,
        failed: olderState === 'error',
        loaded: loadState === 'ok'
      })
    ) {
      loadOlder()
    }
  }, [thread.identity, thread.olderCursor, identity, olderState, loadState, tailLoading, loadOlder])

  // After every thread change too, not only on scroll: a thread shorter than the viewport cannot
  // scroll, so without this its older history would be unreachable.
  useEffect(() => {
    maybeLoadOlder()
  }, [maybeLoadOlder])

  // The panel's box changing size — above all a collapsed node being EXPANDED (display:none → a
  // real box), and the composer growing or being resized under it. Nothing else re-runs the checks
  // then: while hidden, follow and anchor had zero geometry to work with and paging was refused. So:
  // a user who was following stays at the bottom, and paging resumes (a short thread fetches older
  // right away). Guarded: jsdom and old engines have no ResizeObserver, and the panel works without
  // it.
  const maybeLoadOlderRef = useRef(maybeLoadOlder)
  maybeLoadOlderRef.current = maybeLoadOlder
  useEffect(() => {
    const el = msgsRef.current
    if (!el || typeof ResizeObserver === 'undefined') return
    let lastHeight = el.clientHeight
    const ro = new ResizeObserver(() => {
      const height = el.clientHeight
      if (height > 0 && height !== lastHeight && nearBottomRef.current) el.scrollTop = el.scrollHeight
      lastHeight = height
      maybeLoadOlderRef.current()
      attemptLiveRef.current() // a hook event held while the panel was hidden
    })
    ro.observe(el)
    return () => ro.disconnect()
  }, [])

  const onScroll = () => {
    const el = msgsRef.current
    if (el) markFollowing(isNearBottom(el))
    maybeLoadOlder()
  }

  // Page Up / Page Down page the thread from anywhere in the panel, the composer included
  // (lib/chatPageKeys.ts). `contains`: a React portal's keydown bubbles here too.
  const onPanelKey = (e: KeyboardEvent<HTMLDivElement>) => {
    const el = msgsRef.current
    if (!el || e.defaultPrevented || !(e.target instanceof Element) || !e.currentTarget.contains(e.target)) return
    if (
      chatEscInterrupts({ ...e, isComposing: e.nativeEvent.isComposing }, e.target, {
        agentId,
        state: useAgentStatus.getState().byId[nodeId]?.state,
        draft: input,
        readOnly: readOnly === true || readonly
      })
    ) {
      e.preventDefault()
      void interrupt()
      return
    }
    const direction = chatPageDirection(e, e.target)
    if (direction === null) return
    e.preventDefault()
    pageChatThread(el, direction)
  }

  // Esc while the agent works (lib/chatEscInterrupt.ts). Core checks the screen for a dialog first
  // and, when the Esc beat the reply's first token, takes the prompt Claude put back into its own
  // input box out again: it goes into this composer instead, where the user can see and edit it.
  const interrupt = async () => {
    const r = await api.pty.interruptChat(nodeId, agentId, lastSentRef.current ?? undefined)
    if (!r.sent) {
      if (r.reason === 'dialog') {
        const dialog = r.dialog ?? null
        setScreenBlock({ kind: dialog === null ? 'no-prompt' : 'dialog', text: dialog, live: pollScreen })
      }
      const message = chatInterruptRefusalText(r.reason, chatAgentLabel(agentId, useSettings.getState().settings.customAgents))
      window.dispatchEvent(new CustomEvent('nodeterm:toast', { detail: { kind: 'error', message } }))
      return
    }
    // An Esc before the first token writes no transcript marker and fires no hook, so the state would
    // read working until the stale sweep. The same guess an Esc typed in the terminal makes: an
    // interrupted `done` after a short settle, healed by the turn's next hook if the guess was wrong.
    inferInterruptAfterSettle(nodeId)
    const restored = r.restored
    if (restored === null) return
    lastSentRef.current = null
    // The bubble for that send stays: Claude still writes the prompt to the transcript (as a branch it
    // then drops from its context), so the next read would draw it again anyway.
    setInput((cur) => (cur.trim() === '' ? restored : `${restored}\n${cur}`))
  }

  const scrollToLatest = () => {
    const el = msgsRef.current
    if (!el) return
    el.scrollTop = el.scrollHeight
    markFollowing(true)
  }

  const sendOnce = useCallback(async () => {
    const text = input.trim()
    if (!text) return
    // Read the store at SEND time, not the render-time values: a PermissionRequest (or an Eco
    // hibernation) that landed between the last render and this keypress must still block.
    const mode = chatSendMode(agentId, useAgentStatus.getState().byId[nodeId] ?? {})
    if (mode === null) return
    if (mode === 'queue' && !canQueue(text)) {
      const message = `${chatAgentLabel(agentId, useSettings.getState().settings.customAgents)} is working — send commands once the reply finishes.`
      window.dispatchEvent(new CustomEvent('nodeterm:toast', { detail: { kind: 'error', message } }))
      return
    }
    // The kernel's say (chatPaneGate.ts): an agent that announces no quit (codex) may have left a
    // SHELL in the pane while the store still reads `done` — typed there, the message would run.
    const pane = await chatPaneRefusal(agentId, nodeId, {
      paneOwner: (n) => api.pty.paneOwner(n),
      customAgents: useSettings.getState().settings.customAgents
    })
    if (pane) {
      const message = chatPaneRefusalToast(pane, chatAgentLabel(agentId, useSettings.getState().settings.customAgents))
      window.dispatchEvent(new CustomEvent('nodeterm:toast', { detail: { kind: 'error', message } }))
      return
    }
    // Through core's chat-prompt path: where it can read the agent's screen, it refuses before
    // writing anything when the agent's own dialog owns the keyboard (such dialogs fire no hook).
    const ok = await api.pty.sendChatPrompt(nodeId, text, agentId)
    if (isChatPromptBlocked(ok)) {
      // Nothing reached the pane: the draft stays for a resend once the dialog is answered.
      setScreenBlock({ kind: ok.dialog === null ? 'no-prompt' : 'dialog', text: ok.dialog, live: pollScreen })
      return
    }
    if (ok === 'pasted-not-submitted') {
      window.dispatchEvent(new CustomEvent('nodeterm:toast', { detail: { kind: 'error', message: TEXT_NOT_SUBMITTED } }))
      setInput('')
      return
    }
    if (!ok) {
      setReadonly(true)
      return
    }
    // Optimistic: show the prompt immediately. A live read keeps it until the transcript carries it
    // (`carryUnconfirmed`); the turn-end reload / ↻ reconcile from the transcript outright.
    setScreenBlock(null)
    setSuggestion(null)
    justSentRef.current = true
    lastSentRef.current = text
    const sent: ChatMessage = { role: 'user', parts: [{ kind: 'text', text }] }
    if (mode === 'queue') {
      let afterKey: number | null = null
      for (const m of threadRef.current.messages) {
        if (m.key !== undefined && (afterKey === null || m.key > afterKey)) afterKey = m.key
      }
      const id = uuid()
      queuedRef.current.set(sent, id)
      rememberQueuedSend(nodeId, { id, identity, text, afterKey })
    }
    setThread((t) => ({ ...t, messages: [...t.messages, sent] }))
    setOptimistic(true)
    setInput('')
    // A built-in that opens a dialog in the TUI (`/rewind`, `/resume`, `/model`, …) is now on screen
    // THERE, invisible from here, and the state still reads `done`: the next message's Enter would
    // answer it. Go to the terminal — the same hand-off the toolbar's model/effort labels make.
    // Only after the send was confirmed (`ok === true` above): nothing opened otherwise.
    if (onShowTerminal && isInteractiveBuiltin(agentId, text)) {
      onShowTerminal()
      return
    }
    // A local command (`/model`, `!ls`) fires no hook: schedule ONE live tail read, one throttle
    // interval out (claude writes the command record once the command ran), so its confirmation
    // retires the working row instead of the 15 s timeout. A read already in flight defers it.
    if (sentCommand(text)) {
      if (commandReadTimerRef.current !== null) clearTimeout(commandReadTimerRef.current)
      const fire = () => {
        if (tailInFlightRef.current || olderInFlightRef.current) {
          commandReadTimerRef.current = setTimeout(fire, CHAT_LIVE_RELOAD_MIN_MS)
          return
        }
        commandReadTimerRef.current = null
        loadRef.current(true)
      }
      commandReadTimerRef.current = setTimeout(fire, CHAT_LIVE_RELOAD_MIN_MS)
    }
  }, [api, input, nodeId, agentId, identity, onShowTerminal, pollScreen])
  // A send in flight. A typed send (core/typed-input.ts, claude) takes a moment — core waits for the
  // pane to show the text before it presses Enter — and the draft is only cleared once it lands, so
  // a second Enter in that window would send the same prompt twice. Ignore it instead.
  const sendingRef = useRef(false)
  const send = useCallback(async () => {
    if (sendingRef.current) return
    sendingRef.current = true
    try {
      await sendOnce()
    } finally {
      sendingRef.current = false
    }
  }, [sendOnce])

  // The scheduled command read belongs to THIS transcript and this mount.
  useEffect(
    () => () => {
      if (commandReadTimerRef.current !== null) clearTimeout(commandReadTimerRef.current)
      commandReadTimerRef.current = null
    },
    [identity]
  )

  const onWriteRefused = useCallback(() => setReadonly(true), [])

  // Answer the held request through core, which validates the answer against the pending request
  // file and builds what the hook prints. `pendingId` is the request the CARD was bound to
  // (`answerCardState`), re-checked at SEND time against both the store and the thread's binding:
  // a hold that ended (answered in the TUI, timed out, replaced) while the user was choosing must
  // not receive an answer meant for it — that reads as a refusal, and the card says to use the
  // terminal. `false` from core is the same (see ChatAnswerControls).
  const answerHeld = useCallback(
    async (pendingId: string, answer: PermissionAnswer): Promise<boolean> => {
      if (useAgentStatus.getState().byId[nodeId]?.held?.pendingId !== pendingId) return false
      if (threadHeldForRef.current !== pendingId) return false
      return api.answerPermission({ nodeId, pendingId, answer })
    },
    [api, nodeId]
  )

  // Whatever the markdown/chat toggle is bound to; '' when unbound, in which case the bar names
  // the action instead of promising a chord that never fires.
  const mdChip = chipFor('node.toggleMarkdown')

  // The thread's claude.ai look (lib/chatThread.ts): one action row per assistant TURN, keyed by
  // the turn's last message. `now` is ONE clock for every row's relative time, ticked once a minute
  // (a per-row timer would be a timer per turn for a label that changes once a minute).
  const turnEnds = useMemo(() => assistantTurnEnds(messages), [messages])
  // Runs of consecutive tool calls, folded into one closed block each (lib/chatToolGroups.ts) —
  // except, while the turn is live, the run at the end of the thread: its calls stay open chips until
  // something else ends the run. Live = working, or waiting on a prompt (`dialog`: a permission
  // request or question lands MID-turn, and folding on it would close the run on every prompt).
  // A prompt queued meanwhile is drawn at the very end, but is not the turn's output: the tail is
  // measured before it (`isQueued`; the set gains a send before the thread does, so it is current).
  const liveTurn = refusal === 'working' || refusal === 'dialog'
  const toolGroups = useMemo(
    () => groupToolCalls(messages, { foldTail: !liveTurn, isQueued: (m) => queuedRef.current.has(m) }),
    [messages, liveTurn]
  )
  // The last key IS the latest turn end: `assistantTurnEnds` inserts in thread order.
  const latestTurnEnd = useMemo(() => {
    let last = -1
    for (const k of turnEnds.keys()) last = k
    return last
  }, [turnEnds])
  const [now, setNow] = useState(() => Date.now())
  useEffect(() => {
    const t = setInterval(() => setNow(Date.now()), 60_000)
    return () => clearInterval(t)
  }, [])
  // A divider at the first message of each local day; the same `now`, so Today rolls to Yesterday.
  const days = useMemo(() => dayDividers(messages, now), [messages, now])
  // Only the latest todo list is a card (lib/chatTodo.ts).
  const latestTodo = useMemo(() => latestTodoIndex(messages), [messages])
  // Whether the part at (i, j) draws anything at its own place: not when an earlier tool block holds it.
  const drawsAt = (i: number, j: number): boolean => !toolGroups.absorbed.has(partPosition(i, j))

  // One part of a message, as the thread draws it. Also used for the members of a folded tool block,
  // which are drawn inside the block instead of at their own place (lib/chatToolGroups.ts).
  const renderPart = (p: ChatPart, i: number, j: number, key: string | number = j): JSX.Element =>
    p.kind === 'text' ? (
      <MarkdownText key={key} text={p.text} />
    ) : p.kind === 'thinking' ? (
      // Claude's thinking summary — the "thinking out loud" line its TUI prints between tool calls.
      // A fold, closed by default and dimmed, so it never reads as the answer; its line says how long
      // the thinking took when the parser could stamp it (`p.ms`). Native and uncontrolled, like the
      // tool block: it keeps whatever the user opened while the thread re-renders.
      <details key={key} className="term-chat__thinking">
        <summary>{thinkingLabel(p.ms)}</summary>
        <MarkdownText text={p.text} />
      </details>
    ) : p.kind === 'image' ? (
      // An image the user attached to the prompt (the opt-in `rich` read): a thumbnail, click to enlarge.
      <ChatImage key={key} mediaType={p.mediaType} data={p.data} />
    ) : p.kind === 'teammate' ? (
      // A teammate's message (the opt-in `rich` read). A message of them is drawn whole below, so a
      // run from one teammate folds into one row; this is the part on its own.
      <ChatTeammateMessage key={key} parts={[p]} Markdown={MarkdownText} />
    ) : p.kind === 'interrupt' ? (
      // The user interrupted the turn (the opt-in `rich` read). Claude saves that as a user record,
      // but the user did not type it: drawn as Claude's own TUI line, hanging off what came before.
      <div key={key} className="term-chat__interrupt">
        <span className="term-chat__interrupt-hook" aria-hidden="true">⎿</span>
        {CLAUDE_INTERRUPT_LINE}
      </div>
    ) : p.kind === 'tool' && p.name === BASH_COMMAND_TOOL ? (
      // A `!` command the user ran: the TUI's `! cmd` with its output's first line under a `⎿`.
      <ChatShellCommand key={key} arg={p.arg} result={p.result} />
    ) : p.body && !staleTodo(p, i, latestTodo) ? (
      // A plan / question / the latest todo list is the content itself, not plumbing: shown
      // expanded, in full, flowing with the thread (no inner scroll box). The answer stays under it.
      // A superseded todo list falls through to the plain chip.
      <div key={key} className={`term-chat__tool-card${p.name === TODO_WRITE_TOOL ? ' term-chat__todo' : ''}`}>
        <div className="term-chat__tool-card-title">{toolCardTitle(p.name)}</div>
        <MarkdownText text={p.body} />
        {/* A TodoWrite's result is the CLI's canned "Todos have been modified…": plumbing, not content. */}
        {p.result && p.name !== TODO_WRITE_TOOL && <pre className="term-chat__tool-result">{p.result}</pre>}
        {answerCard && answerCard.card.message === i && answerCard.card.part === j && (
          // Keyed by the BOUND ticket: a new hold on the same card starts from a clean
          // state, and every answer names the request this card was drawn for.
          p.name === 'AskUserQuestion' && p.questions ? (
            <QuestionAnswerControls
              key={answerCard.pendingId}
              questions={p.questions}
              agentLabel={agentLabel}
              chip={mdChip}
              onSubmit={(a) => answerHeld(answerCard.pendingId, a)}
            />
          ) : (
            <PlanAnswerControls
              key={answerCard.pendingId}
              agentLabel={agentLabel}
              chip={mdChip}
              onSubmit={(a) => answerHeld(answerCard.pendingId, a)}
            />
          )
        )}
        {updatingCard && updatingCard.message === i && updatingCard.part === j && (
          <AnswerControlsUpdating chip={mdChip} />
        )}
      </div>
    ) : p.diff ? (
      // An Edit / Write (the opt-in `rich` read): the plain chip plus `+N −M`, opening to the diff.
      <ChatToolDiff key={key} name={p.name} diff={p.diff} result={p.result} />
    ) : (
      <details key={key} className="term-chat__tool">
        <summary>
          <span className="term-chat__tool-name">{p.name}</span>
          {p.arg && <span className="term-chat__tool-arg">{p.arg}</span>}
        </summary>
        {p.result && <pre className="term-chat__tool-result">{p.result}</pre>}
      </details>
    )

  // A tail that yielded no message but has history behind it (all-metadata records, or a window a
  // single huge record filled) is STILL LOADING — the panel pages back by itself from here. Saying
  // "No conversation yet." there, until the older page landed, told the user a session with a
  // whole conversation had none. A failed older page gets the retry row instead (below).
  const historyPending = thread.identity === identity && thread.olderCursor !== null
  const initialLoading =
    messages.length === 0 &&
    (loadState === 'loading' || (loadState === 'ok' && historyPending && olderState !== 'error'))
  const unseen = following ? 0 : unseenAfter(messages, lastSeenRef.current)
  const showEmpty = messages.length === 0 && loadState !== 'loading' && !(loadState === 'ok' && historyPending)

  return (
    // `data-chat-node-id`: which node's chat view this is — the mics that name only a node ask it
    // (lib/chatComposerDictation.ts `dictationTargetForNode`) so a take never reaches the hidden pane.
    <div className="term-chat nodrag nowheel" data-chat-node-id={nodeId} onKeyDown={onPanelKey}>
      <div className="term-chat__bar">
        <span>{title ?? 'Chat'}</span>
        <span className="term-chat__bar-end">
          <button
            className="term-chat__refresh"
            onClick={() => load()}
            title="Reload conversation"
            aria-label="Reload conversation"
          >
            ↻
          </button>
          <span className="term-chat__hint">{hint ?? (mdChip ? `${mdChip} to exit` : 'Exit')}</span>
        </span>
      </div>
      {sessionFallback && (
        <div className="term-chat__fallback-note" role="note">
          {FALLBACK_SESSION_NOTE}
        </div>
      )}
      <div className="term-chat__thread">
        <div className="term-chat__msgs" ref={msgsRef} onScroll={onScroll}>
          {initialLoading && (
            <ChatLoadingStatus text={EMPTY_TEXT.loading.title} />
          )}
          {messages.length > 0 && olderState === 'loading' && (
            <div className="term-chat__older" role="status">
              <Spinner />
              <span>Loading earlier messages…</span>
            </div>
          )}
          {olderState === 'error' && (
            <div className="term-chat__older term-chat__older--error">
              <span>Couldn't load earlier messages.</span>
              <button className="term-chat__retry" onClick={loadOlder}>
                Retry
              </button>
            </div>
          )}
          {/* Only a PAGED thread (keyed messages) can know it reached the start; grok's capped
              whole-file read says nothing about what lies before it. */}
          {olderState === 'idle' && thread.olderCursor === null && messages.some((m) => m.key !== undefined) && (
            <div className="term-chat__older term-chat__older--start">Beginning of conversation</div>
          )}
          {showEmpty && (
            <div className="term-chat__empty">
              <div>{EMPTY_TEXT[loadState].title.replace('{agent}', agentLabel)}</div>
              {EMPTY_TEXT[loadState].detail && (
                <div className="term-chat__empty-detail">{EMPTY_TEXT[loadState].detail}</div>
              )}
              {loadState !== 'unsupported' && loadState !== 'remoteUnsupported' && loadState !== 'ambiguous' && loadState !== 'ok' && (
                <button className="term-chat__retry" onClick={() => load()}>
                  Retry
                </button>
              )}
            </div>
          )}
          {messages.map((m, i) => {
            // A message whose every part is drawn inside an earlier message's tool block has nothing
            // of its own to draw, unless it ends a turn: then it draws that turn's action row and
            // nothing else — bar a day divider (below). (Only assistant parts fold, so a queued
            // message — the user's — never does.)
            const folded = m.parts.length > 0 && m.parts.every((_, j) => !drawsAt(i, j))
            const turnEnd = turnEnds.get(i)
            // Keyed by the source line's byte offset: a prepended page does not re-key (and so does
            // not re-render) a single existing bubble. Unkeyed ones (grok, the optimistic sent
            // bubble) fall back to their position.
            const key = m.key !== undefined ? `k${m.key}` : `i${i}`
            // The day divider is a sibling BEFORE the wrapper, a folded one's too. A message drawn
            // whole inside an earlier tool block still draws its divider alone: its day would
            // otherwise lose its label, since the divider goes only on a day's FIRST stamped message.
            const day = days.get(i)
            const divider = day !== undefined && (
              <div className="term-chat__day" role="separator" aria-label={day}>
                {day}
              </div>
            )
            if (folded && !turnEnd) return divider ? <Fragment key={key}>{divider}</Fragment> : null
            const actions = turnEnd && (
              <ChatTurnActions copyText={turnEnd.copyText} at={turnEnd.at} now={now} latest={i === latestTurnEnd} />
            )
            if (folded) {
              return (
                <Fragment key={key}>
                  {divider}
                  <div className={`term-chat__msg term-chat__msg--${m.role} term-chat__msg--folded`}>{actions}</div>
                </Fragment>
              )
            }
            const queued = queuedRef.current.has(m)
            return (
              <Fragment key={key}>
                {divider}
                <div
                  className={`term-chat__msg term-chat__msg--${m.role}${m.role === 'user' ? ' term-chat__bubble' : ''}${
                    queued ? ' term-chat__msg--queued' : ''
                  }`}
                >
                  {isTeammateMessage(m) ? (
                    // A teammate's messages (the opt-in `rich` read), drawn whole so a run from one
                    // teammate folds into one row, as Claude Code's TUI does.
                    <ChatTeammateMessage parts={m.parts} Markdown={MarkdownText} />
                  ) : (
                    m.parts.map((p, j) => {
                      if (!drawsAt(i, j)) return null
                      const group = toolGroups.groupAt.get(partPosition(i, j))
                      if (group) return <ChatToolGroup key={group.key} messages={messages} group={group} renderPart={renderPart} />
                      return renderPart(p, i, j)
                    })
                  )}
                  {m.role === 'user' && m.at !== undefined && (
                    <time
                      className="term-chat__time term-chat__time--user"
                      dateTime={new Date(m.at).toISOString()}
                      title={chatAbsoluteTime(m.at)}
                    >
                      {chatClockTime(m.at)}
                    </time>
                  )}
                  {queued && <div className="term-chat__queued-label">Queued</div>}
                  {actions}
                </div>
              </Fragment>
            )
          })}
          {screenBlock && (
            <div className="term-chat__screen-block" role="status" aria-live="polite">
              <div className="term-chat__screen-block-title">
                {screenBlockedSentence(screenBlock.kind, agentLabel, mdChip)}
              </div>
              {screenBlock.text !== null && <pre className="term-chat__screen-block-text">{screenBlock.text}</pre>}
            </div>
          )}
          {activity && (
            // One live region for both sentences, so working → waiting changes its text instead of
            // remounting it (a remounted role=status is announced again). The words are the
            // composer placeholder's own (`chatComposerPlaceholder`), so the two never disagree.
            <div className="term-chat__activity" role="status" aria-live="polite">
              {activity === 'working' && <Spinner />}
              {chatComposerPlaceholder({
                readonly: false,
                refusal: activity,
                agentLabel,
                chip: mdChip,
                answerOnCard: answerCard !== null
              })}
            </div>
          )}
        </div>
        {!following && messages.length > 0 && (
          // An "N new messages ↓" pill, plus a bare "↓" while nothing new has come in: the thread is
          // also read back from deep in its history.
          <button
            type="button"
            className="confirm__btn primary term-chat__to-latest"
            title="Scroll to the latest message"
            aria-label={unseen > 0 ? undefined : 'Scroll to the latest message'}
            // Keep the keyboard where it was (the composer): a click here is not a reason to leave it.
            onMouseDown={(e) => e.preventDefault()}
            onClick={scrollToLatest}
          >
            {unseen > 0 ? `${newMessagesLabel(unseen)} ↓` : '↓'}
          </button>
        )}
      </div>
      {!readOnly && (
        <ChatComposer
          nodeId={nodeId}
          sessionId={sessionId}
          agentId={agentId}
          agentLabel={agentLabel}
          value={input}
          onChange={setInput}
          onSend={() => void send()}
          placeholder={
            shownSuggestion ??
            chatComposerPlaceholder({
              readonly,
              refusal,
              agentLabel,
              chip: mdChip,
              answerOnCard: answerCard !== null,
              sendMode,
              screen: screenBlock?.live === true ? screenBlock.kind : null
            })
          }
          suggestion={shownSuggestion}
          // A dialog the POLL found is also cleared by it; one a refused send found is not (a remote
          // pane is never polled), so that one leaves the draft editable for the resend.
          disabled={readonly || composerStandsDown(refusal) || screenBlock?.live === true}
          agentBusy={refusal === 'working'}
          onWriteRefused={onWriteRefused}
          sendUnconfirmed={optimistic}
          pathsForFiles={pathsForFiles}
          onShowTerminal={onShowTerminal}
          cwd={cwd}
          accountId={accountId}
          sshProjectId={sshProjectId}
        />
      )}
    </div>
  )
}