ompchamber 0.3.0

package/src/client/hooks/chat/timeline/send.ts

@@ -0,0 +1,348 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Message-send core for the chamber chat: reads text/image attachments, builds
+ * the optimistic user + AI placeholder bubbles, then routes the send through
+ * the live omp agent bridge (existing/new session) or the mock SSE stream.
+ * Extracted from useChatTimeline so that hook stays under the size ceiling.
+ */
+
+import { useCallback } from 'preact/hooks';
+import type { Dispatch, SetStateAction } from 'preact/compat';
+import type { Attachment, ChatMessageData, OmpAgentHandle, QueuedMessageModel } from '@/shared/types';
+import type { ApprovalMode } from '@/shared/lib/omp/config/access-mode';
+import { streamChatResponse } from '@/client/hooks/chat/stream';
+import { composeMessageWithTextAttachments, isTextAttachmentFile } from '@/shared/lib/chat/attachments';
+import { loadAgentNames } from '@/shared/lib/chat/composer/client';
+import { translateAgentMentions, translateFileMentions } from '@/shared/lib/chat/composer/translate';
+import { normalizeNoticePositions } from '@/shared/lib/chat/order';
+import { createMockStreamCallbacks } from '@/shared/lib/chat/timeline/stream-callbacks';
+import { PHASE_VERBS } from '@/shared/lib/chat/timeline/tool-phrases';
+import { formatClock } from '@/shared/lib/format/time';
+
+type TextFileAttachment = Parameters<typeof composeMessageWithTextAttachments>[1][number];
+
+/**
+ * Build the outgoing prompt. `@agent` mentions are rewritten into an explicit
+ * task-tool delegation directive at send time (oh-my-pi has no `@agent`
+ * syntax); translation failures fall back to the raw prompt.
+ */
+async function buildPromptText(text: string, textFiles: TextFileAttachment[]): Promise<string> {
+  let translated = text;
+  try {
+    const names = await loadAgentNames();
+    if (names.length > 0) translated = translateAgentMentions(text, names).text;
+  } catch {
+    // keep the raw prompt
+  }
+  // File mentions are namespaced (`@file:`) by the picker; strip the namespace
+  // only after the agent pass so `@file:<name>` is never mistaken for `@agent`.
+  return composeMessageWithTextAttachments(translateFileMentions(translated), textFiles);
+}
+
+export interface ChatTimelineSendDeps {
+  folders: any[];
+  selectedFolderId: number | null;
+  sessionId: string | null;
+  isOmpSession: boolean;
+  appSettings: Record<string, any>;
+  ompAgent: OmpAgentHandle;
+  setLocalMessages: Dispatch<SetStateAction<ChatMessageData[]>>;
+  persistMessages: (messages: any[]) => void;
+  setGenerating: (v: boolean) => void;
+  setGeneratingVerb: (v: string) => void;
+  /** Follow-gated scroll for stream chunks. */
+  scrollToBottom: (behavior?: ScrollBehavior) => void;
+  /** Explicit user-action scroll: re-engages follow mode (send/steer). */
+  jumpToBottom: (behavior?: ScrollBehavior) => void;
+  aiPlaceholderIdRef: { current: string | null };
+  adoptedSessionIdRef: { current: string | null };
+  optimisticUserIdRef: { current: string | null };
+  pendingUserDisplaysRef: { current: { sent: string; display: string }[] };
+  setSessionModel: (model: { provider: string; modelId: string } | null) => void;
+  /** Model/thinking picked in the composer before the session existed —
+   *  applied to the spawn command so the first prompt runs with them. */
+  pendingComposerModelRef: { current: { provider: string; modelId: string } | null };
+  pendingThinkingLevelRef: { current: string | null };
+  /** Global access-control mode (persisted user preference), read at send time
+   *  so the spawn-capable requests carry the latest value. */
+  accessModeRef: { current: ApprovalMode };
+  /** Live composer model/thinking mirror (written by ChatInput) so enqueue can
+   *  snapshot the selection onto queued items. */
+  composerModelRef: { current: { provider: string; modelId: string; thinkingLevel: string } | null };
+  abortControllerRef: { current: AbortController | null };
+  setInputValue: (v: string) => void;
+  setSearchParams: (fn: (prev: URLSearchParams) => URLSearchParams, opts?: { replace?: boolean }) => void;
+}
+
+export interface ChatTimelineSendResult {
+  steerOmpAgent: (text: string, attachments: Attachment[]) => Promise<void>;
+  /** `model` re-applies a queued item's snapshot before the prompt runs
+   *  (set_model / set_thinking_level RPC + prompt access mode). */
+  executeSend: (
+    text: string,
+    attachments: Attachment[],
+    options?: { model?: QueuedMessageModel | null },
+  ) => Promise<void>;
+}
+
+export function useChatTimelineSend(deps: ChatTimelineSendDeps): ChatTimelineSendResult {
+  const {
+    folders,
+    selectedFolderId,
+    sessionId,
+    isOmpSession,
+    appSettings,
+    ompAgent,
+    setLocalMessages,
+    persistMessages,
+    setGenerating,
+    setGeneratingVerb,
+    scrollToBottom,
+    jumpToBottom,
+    aiPlaceholderIdRef,
+    adoptedSessionIdRef,
+    optimisticUserIdRef,
+    pendingUserDisplaysRef,
+    setSessionModel,
+    pendingComposerModelRef,
+    pendingThinkingLevelRef,
+    accessModeRef,
+    abortControllerRef,
+    setInputValue,
+    setSearchParams,
+  } = deps;
+
+  // Reads text-file attachments and builds the prompt + image payload for an
+  // omp delivery (mirror of executeSend's assembly block).
+  const prepareDeliverable = useCallback(async (
+    text: string,
+    attachments: Attachment[],
+  ): Promise<{ promptText: string; images?: { data: string; mimeType: string }[] }> => {
+    const textFileContents = new Map<string, string>();
+    try {
+      await Promise.all(
+        attachments
+          .filter(a => isTextAttachmentFile(a.file))
+          .map(async a => {
+            textFileContents.set(a.id, await a.file.text());
+          })
+      );
+    } catch {
+      // Fall back to prompt without inlined contents if a file cannot be read.
+    }
+    const textFiles = attachments
+      .filter(a => textFileContents.has(a.id))
+      .map(a => ({
+        name: a.file.name,
+        mimeType: a.file.type,
+        content: textFileContents.get(a.id) as string,
+        size: a.file.size,
+      }));
+    const promptText = await buildPromptText(text, textFiles);
+    pendingUserDisplaysRef.current = [...pendingUserDisplaysRef.current.slice(-7), { sent: promptText, display: text }];
+    const images = attachments
+      .filter(a => a.file.type.startsWith('image/') && a.dataBase64)
+      .map(a => ({ data: a.dataBase64 as string, mimeType: a.file.type }));
+    return { promptText, images: images.length ? images : undefined };
+  }, []);
+
+  // Steer the running omp agent with a fresh prompt (interrupt-and-reply).
+  const steerOmpAgent = useCallback(async (text: string, attachments: Attachment[]) => {
+    const { promptText, images } = await prepareDeliverable(text, attachments);
+    const ok = await ompAgent.sendInterruptAndReply(promptText, images);
+    if (!ok) setInputValue(text);
+  }, [ompAgent, prepareDeliverable, setInputValue]);
+
+  const executeSend = useCallback(async (
+    text: string,
+    attachments: Attachment[],
+    options?: { model?: QueuedMessageModel | null },
+  ) => {
+    // A queued delivery replays the snapshot the item was queued with; a plain
+    // send keeps the session's live picks. 'auto' thinking leaves omp alone.
+    const modelOverride = options?.model ?? null;
+    const effectiveAccessMode = modelOverride?.accessMode ?? accessModeRef.current;
+    const time = formatClock();
+    const userMsgId = `msg-${Date.now()}-user`;
+    const aiPlaceholderId = `msg-${Date.now() + 1}-ai`;
+
+    // Read text-file contents once: used for the editor (attachment.content)
+    // and for inlining into the prompt (mirror omp-web).
+    const textFileContents = new Map<string, string>();
+    try {
+      await Promise.all(
+        attachments
+          .filter(a => isTextAttachmentFile(a.file))
+          .map(async a => {
+            textFileContents.set(a.id, await a.file.text());
+          })
+      );
+    } catch {
+      // Fall back to prompt without inlined contents if a file cannot be read.
+    }
+
+    const now = Date.now();
+    const newUserMsg: ChatMessageData = {
+      id: userMsgId,
+      role: 'user',
+      date: `Today, ${time}`,
+      // Precise epoch anchor: the footer run-duration measures from here until
+      // the last AI message. The display `date` label is minute-granular, so a
+      // string fallback would inflate the measured span by up to 59s.
+      startedAt: now,
+      content: text,
+      attachments: attachments.map(a => ({
+        name: a.file.name,
+        preview: a.dataBase64 ? `data:${a.file.type};base64,${a.dataBase64}` : a.preview,
+        type: a.file.type,
+        size: a.file.size,
+        content: textFileContents.get(a.id),
+      }))
+    };
+
+    const initialAiMsg: ChatMessageData = {
+      id: aiPlaceholderId,
+      role: 'ai',
+      date: `Today, ${time}`,
+      startedAt: now,
+      content: '',
+    };
+
+    setLocalMessages(prev => {
+      const next = normalizeNoticePositions([...prev, newUserMsg, initialAiMsg]);
+      persistMessages(next.filter(m => m.id !== aiPlaceholderId));
+      return next;
+    });
+
+    setGenerating(true);
+    setGeneratingVerb(PHASE_VERBS.thinking);
+    // An explicit send is user intent to watch the answer: re-engage follow
+    // mode even if the user had scrolled away, then scroll to the tail.
+    setTimeout(() => jumpToBottom('smooth'), 50);
+
+    // Real mode: route through the omp agent RPC bridge + event stream.
+    if (isOmpSession) {
+      aiPlaceholderIdRef.current = aiPlaceholderId;
+      optimisticUserIdRef.current = userMsgId;
+      // Replay the queued snapshot first so the prompt runs on the exact
+      // model/thinking the item was queued with.
+      if (modelOverride) {
+        await ompAgent.setModel(modelOverride.provider, modelOverride.modelId);
+        if (modelOverride.thinkingLevel !== 'auto') {
+          await ompAgent.setThinkingLevel(modelOverride.thinkingLevel);
+        }
+      }
+      const images = attachments
+        .filter(a => a.file.type.startsWith('image/') && a.dataBase64)
+        .map(a => ({ data: a.dataBase64 as string, mimeType: a.file.type }));
+      // Inline text-file contents into the prompt (mirror omp-web): the model
+      // sees the full file content as fenced blocks, not just the filename.
+      const textFiles = attachments
+        .filter(a => textFileContents.has(a.id))
+        .map(a => ({
+          name: a.file.name,
+          mimeType: a.file.type,
+          content: textFileContents.get(a.id) as string,
+          size: a.file.size,
+        }));
+      const promptText = await buildPromptText(text, textFiles);
+      const ok = await ompAgent.sendPrompt(promptText, images.length ? images : undefined, { accessMode: effectiveAccessMode });
+      if (!ok) {
+        // Roll back the optimistic bubbles on a failed send.
+        setLocalMessages(prev => prev.filter(m => m.id !== userMsgId && m.id !== aiPlaceholderId));
+        aiPlaceholderIdRef.current = null;
+        optimisticUserIdRef.current = null;
+        setGenerating(false);
+      }
+      return;
+    }
+
+    // No active session (fresh "New Session"): in real mode spawn a brand-new
+    // omp session and adopt its id; fall back to the mock/simulated path only
+    // when the spawn fails (e.g. MOCK=true or no workspace context).
+    if (!isOmpSession) {
+      const currentFolder = folders.find(f => String(f.id) === String(selectedFolderId));
+      const cwd = currentFolder?.project_path || currentFolder?.name;
+      if (cwd) {
+        const images = attachments
+          .filter(a => a.file.type.startsWith('image/') && a.dataBase64)
+          .map(a => ({ data: a.dataBase64 as string, mimeType: a.file.type }));
+        const textFiles = attachments
+          .filter(a => textFileContents.has(a.id))
+          .map(a => ({
+            name: a.file.name,
+            mimeType: a.file.type,
+            content: textFileContents.get(a.id) as string,
+            size: a.file.size,
+          }));
+        const promptText = await buildPromptText(text, textFiles);
+        optimisticUserIdRef.current = userMsgId;
+        const composerModel = pendingComposerModelRef.current;
+        const composerThinking = pendingThinkingLevelRef.current;
+        const spawned = await ompAgent.sendNewPrompt(
+          promptText,
+          cwd,
+          images.length ? images : undefined,
+          { model: composerModel, thinkingLevel: composerThinking, accessMode: accessModeRef.current },
+        );
+        if (spawned) {
+          adoptedSessionIdRef.current = spawned.sessionId;
+          aiPlaceholderIdRef.current = aiPlaceholderId;
+          if (spawned.model) setSessionModel(spawned.model);
+          pendingComposerModelRef.current = null;
+          pendingThinkingLevelRef.current = null;
+          fetch(`/api/chat/${encodeURIComponent(spawned.sessionId)}`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ messages: [newUserMsg] }),
+          }).catch(err => console.error('Error persisting spawned user turn:', err));
+          setSearchParams(prev => {
+            const next = new URLSearchParams(prev);
+            next.set('sessionId', spawned.sessionId);
+            return next;
+          }, { replace: true });
+          // The agent_start event refreshes the session metadata/sidebar once
+          // the JSONL has the user turn; no immediate refresh is needed here.
+          return;
+        }
+      }
+    }
+
+    // Mock / chamber-created session: existing Gemini/simulated SSE path.
+    // Cancel any previous stream
+    optimisticUserIdRef.current = null;
+    if (abortControllerRef.current) {
+      abortControllerRef.current.abort();
+    }
+    const abortController = new AbortController();
+    abortControllerRef.current = abortController;
+
+    const currentFolder = folders.find(f => String(f.id) === String(selectedFolderId));
+    const workspaceName = currentFolder?.name || 'Workspace';
+
+    await streamChatResponse(
+      {
+        sessionId: sessionId || `session-${Date.now()}`,
+        prompt: text,
+        workspaceName,
+        attachments,
+        signal: abortController.signal,
+      },
+      createMockStreamCallbacks({
+        aiPlaceholderId,
+        setLocalMessages,
+        persistMessages,
+        setGenerating,
+        setGeneratingVerb,
+        abortControllerRef,
+        appSettings,
+        scrollToBottom,
+      })
+    );
+  }, [appSettings, folders, isOmpSession, ompAgent, selectedFolderId, sessionId, scrollToBottom, jumpToBottom, persistMessages, setSessionModel, pendingComposerModelRef, pendingThinkingLevelRef, accessModeRef]);
+  return { steerOmpAgent, executeSend };
+}

package/src/client/hooks/chat/timeline/session-load.ts

@@ -0,0 +1,334 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Session loading core for the chamber chat: fetches /api/chat/:sessionId,
+ * applies session metadata (model / thinking level / title) and replaces the
+ * timeline with the committed messages. Extracted from useChatTimeline so that
+ * hook stays under the size ceiling.
+ *
+ * Reload-mid-stream contract: the timeline fetch must NOT depend on the
+ * generating flag alone. On a page reload during a run there is no optimistic
+ * bubble yet (fresh mount, refs are null), so the committed JSONL history —
+ * including the already-finalized turns of the in-flight run — must load
+ * normally; the stream resume continues from there. Clobbering is only possible
+ * while an optimistic AI placeholder actually owns the tail of the timeline.
+ */
+
+import type { Dispatch, RefObject, SetStateAction } from 'preact/compat';
+import { useCallback, useEffect, useLayoutEffect, useRef, useState } from 'preact/hooks';
+
+import type { ChatMessageData } from '@/shared/types';
+import { normalizeNoticePositions } from '@/shared/lib/chat/order';
+import { SESSION_META_RETRY_SCHEDULE_MS } from '@/shared/lib/workspace/refresh-cadence';
+
+export interface SessionDataShape {
+  id?: string;
+  title?: string;
+  model?: string | { provider: string; modelId: string };
+  thinkingLevel?: string;
+  messages?: any[];
+}
+
+export interface UseSessionLoadDeps {
+  sessionId: string | null;
+  setLocalMessages: Dispatch<SetStateAction<ChatMessageData[]>>;
+  setGenerating: (v: boolean) => void;
+  /** Live generating flag written by the caller's `setGenerating` throat. Gates
+   *  the committed-fetch clobber guard and the seeded-model fallback. */
+  isGeneratingRef: { current: boolean };
+  /** Live AI placeholder ref: when non-null it owns the timeline tail and the
+   *  committed fetch must not replace it mid-stream. */
+  aiPlaceholderIdRef: { current: string | null };
+  /** Caller-owned timeline state mirror: lets the committed fetch merge the
+   *  live stream tail (rows the JSONL does not carry yet) into history. */
+  localMessagesRef: { current: ChatMessageData[] };
+  /** Live optimistic user bubble ref: cleared together with the placeholder on
+   *  a session switch so stale ids cannot survive into the next session. */
+  optimisticUserIdRef: { current: string | null };
+  /** Drop queued stream updates belonging to the previous session (coalescer). */
+  cancelStreamingCoalescer: () => void;
+  metaRefreshedRef: { current: string | null };
+  /** Scroll container of the timeline: lets loadOlder preserve the viewport
+   *  position when older rows are prepended above it. */
+  scrollRef?: RefObject<HTMLDivElement>;
+}
+
+export function useSessionLoad(deps: UseSessionLoadDeps) {
+  const { sessionId, setLocalMessages, setGenerating, isGeneratingRef, aiPlaceholderIdRef, localMessagesRef, optimisticUserIdRef, cancelStreamingCoalescer, metaRefreshedRef, scrollRef } = deps;
+
+  const [sessionData, setSessionData] = useState<SessionDataShape | null>(null);
+  // History pagination state: the first fetch receives the newest window only;
+  // scrolling to the top pages further back via ?before=oldestIndex.
+  const [hasMore, setHasMore] = useState(false);
+  const [oldestIndex, setOldestIndex] = useState(0);
+  const [loadingOlder, setLoadingOlder] = useState(false);
+  // Sticky failure flag for the "Load earlier messages" affordance: a failed
+  // page fetch must keep the button visible (retryable) instead of silently
+  // dropping hasMore, which made the button vanish with no feedback.
+  const [loadOlderError, setLoadOlderError] = useState(false);
+  // Bumped on every successful older-window prepend; the scroll-anchor layout
+  // effect keys on it (its other deps have stable identities, so it needs an
+  // explicit change signal per commit).
+  const [prependTick, setPrependTick] = useState(0);
+  const loadingOlderRef = useRef(false);
+  const [sessionLoading, setSessionLoading] = useState(false);
+  // Set while prepending older rows; the layout effect below re-anchors the
+  // viewport to the content the user was reading instead of jumping.
+  const pendingScrollAnchorRef = useRef<{ prevHeight: number; prevTop: number } | null>(null);
+  const prevSessionIdRef = useRef<string | null>(null);
+  // Real session id adopted by a fresh spawn ("new-…" → UUID). onAgentStart
+  // may fire before React re-renders with the new URL, so it reads the id
+  // from here instead of the (still-stale) sessionId prop.
+  const adoptedSessionIdRef = useRef<string | null>(null);
+  // Model seeded from the spawn response; kept until the JSONL writes model_change.
+  const seededModelRef = useRef<{ provider: string; modelId: string } | null>(null);
+
+  const applySessionData = useCallback((incoming: SessionDataShape) => {
+    if (incoming.model && typeof incoming.model === 'object') seededModelRef.current = incoming.model;
+    const model = incoming.model ?? (isGeneratingRef.current ? seededModelRef.current ?? undefined : undefined);
+    setSessionData({ ...incoming, model });
+  }, []);
+
+  const sessionIdRef = useRef(sessionId);
+  sessionIdRef.current = sessionId;
+
+  /** Re-fetch the session's title/metadata after the omp JSONL has been
+   *  written (spawn or agent end) so the navbar and context panel show the
+   *  real session title instead of the default. Retries on a front-loaded
+   *  backoff until the JSONL actually carries messages (omp writes the user
+   *  turn on agent start). */
+  const refreshSessionMeta = useCallback((sid: string) => {
+    // The URL lags the adopted id right after a fresh spawn, so accept either.
+    const isActive = () => sessionIdRef.current === sid || adoptedSessionIdRef.current === sid;
+    if (!isActive()) return;
+    let attempt = 0;
+    const tryFetch = () => {
+      if (!isActive()) return;
+      fetch(`/api/chat/${encodeURIComponent(sid)}`)
+        .then(res => res.json())
+        .then(data => {
+          if (!data?.session || !isActive()) return;
+          applySessionData(data.session);
+          // Signal the sidebar only on a settled read: the early attempts of a
+          // fresh spawn see zero messages, and dispatching on those would reset
+          // the sidebar's throttle window for the whole spawn.
+          if ((data.session.messages?.length ?? 0) > 0) {
+            window.dispatchEvent(new CustomEvent('omp:session-updated', { detail: { sessionId: sid } }));
+            return;
+          }
+          const delay = SESSION_META_RETRY_SCHEDULE_MS[attempt];
+          attempt += 1;
+          if (delay !== undefined) setTimeout(tryFetch, delay);
+        })
+        .catch(() => {});
+    };
+    tryFetch();
+  }, [applySessionData]);
+
+  const setSessionModelWithSeed = useCallback((model: { provider: string; modelId: string } | null) => {
+    seededModelRef.current = model;
+    setSessionData(prev => ({ ...(prev ?? {}), model: model ?? undefined }));
+  }, []);
+
+  /** Whether the optimistic bubble set currently owns the timeline tail (a
+   *  local send is in flight). Only then must a committed fetch be skipped —
+   *  a bare mount (reload mid-run) has isGenerating false AND no placeholder,
+   *  so committed history still loads. */
+  const timelineOwnedByOptimistic = useCallback(
+    () => isGeneratingRef.current && Boolean(aiPlaceholderIdRef.current),
+    [aiPlaceholderIdRef],
+  );
+
+  // Fetch session messages and details from API
+  useEffect(() => {
+    let active = true;
+    setSessionLoading(true);
+    // Track the previous session id so a session switch (including "New
+    // Session" → new-…) clears the timeline, while the optimistic spawn
+    // transition (new-… → real UUID) keeps its bubbles.
+    if (sessionId !== prevSessionIdRef.current) {
+      const isSpawnAdopt = sessionId && !sessionId.startsWith('new-') && prevSessionIdRef.current?.startsWith('new-');
+      // Keep the optimistic bubbles while a local send is in flight and this
+      // session is the one it spawned (a fresh spawn may not have passed
+      // through "new-…"). A reload mid-run has no adopted id, so history loads.
+      const isAdoptingInFlight = isGeneratingRef.current && adoptedSessionIdRef.current === sessionId;
+      if (!isSpawnAdopt && !isAdoptingInFlight) {
+        setLocalMessages([]);
+        setGenerating(false);
+        adoptedSessionIdRef.current = null;
+        seededModelRef.current = null;
+        // The placeholder/optimistic ids belong to the PREVIOUS session's
+        // in-flight send; message_end never arrives after a switch away (the
+        // stream is disconnected), so they must be dropped here. A stale
+        // placeholder made timelineOwnedByOptimistic() report true on return,
+        // which silently DISCARDED the committed history fetch of the
+        // mid-run session — only newly streamed frames ever appeared.
+        aiPlaceholderIdRef.current = null;
+        optimisticUserIdRef.current = null;
+        // Drop coalesced message_update frames queued by the previous
+        // session's stream: otherwise they apply to this (cleared) timeline
+        // as phantom bubbles.
+        cancelStreamingCoalescer();
+      }
+      // Reset pagination cursor on every session switch — the window belongs
+      // to the previous session otherwise.
+      setHasMore(false);
+      setOldestIndex(0);
+      loadingOlderRef.current = false;
+      setLoadingOlder(false);
+      setLoadOlderError(false);
+      // metaRefreshedRef must NOT survive a session switch — including a
+      // spawn adoption. It is the once-per-session guard in onAgentStart
+      // (omp-callbacks.ts); keeping the stale value here ate the retrigger,
+      // so a title refresh that landed before the omp JSONL had messages
+      // (default timestamped title) never ran again and the sidebar stayed
+      // on the placeholder until some later event refreshed it.
+      metaRefreshedRef.current = null;
+      prevSessionIdRef.current = sessionId;
+    }
+    if (sessionId) {
+      fetch(`/api/chat/${sessionId}`)
+        .then(res => res.json())
+        .then(data => {
+          if (!active) return;
+          setSessionLoading(false);
+          if (data?.session) {
+            applySessionData(data.session);
+            // Only replace the timeline when the fetch actually has messages.
+            // A pending "new-…" session or a just-spawned omp session whose
+            // JSONL is not written yet must not wipe the optimistic bubbles.
+            const fetched = data.session.messages || [];
+            const optimisticOwnsTail = timelineOwnedByOptimistic();
+            if (fetched.length > 0 && !optimisticOwnsTail) {
+              // Reattach race: a resumed stream may have appended the
+              // in-flight segment before this committed fetch resolved (the
+              // JSONL does not carry it yet). Keep those live rows instead of
+              // dropping them until the next message_update re-renders them.
+              if (isGeneratingRef.current) {
+                const fetchedIds = fetched.map((m: ChatMessageData) => m.id);
+                const liveTail = localMessagesRef.current.filter(m => !fetchedIds.includes(m.id));
+                setLocalMessages(normalizeNoticePositions([...fetched, ...liveTail]));
+              } else {
+                setLocalMessages(normalizeNoticePositions(fetched));
+              }
+            } else if (!sessionId.startsWith('new-') && !optimisticOwnsTail) {
+              setLocalMessages([]);
+            }
+            if (typeof data.hasMore === 'boolean') setHasMore(data.hasMore);
+            if (typeof data.oldestIndex === 'number') setOldestIndex(data.oldestIndex);
+          } else {
+            setSessionData(null);
+            if (!timelineOwnedByOptimistic()) setLocalMessages([]);
+          }
+        })
+        .catch(err => {
+          console.error('Error loading session from API:', err);
+          if (active) setSessionLoading(false);
+          if (active && !timelineOwnedByOptimistic()) {
+            setSessionData(null);
+            setLocalMessages([]);
+          }
+        });
+    } else {
+      setSessionData(null);
+      setLocalMessages([]);
+    }
+    return () => {
+      active = false;
+    };
+    // sessionModel identity flows through applySessionData; the effect only
+    // re-runs on session switches by design.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [sessionId, applySessionData, timelineOwnedByOptimistic, setLocalMessages, setGenerating]);
+
+  /** Page the next older window into the timeline. Called from the click
+   *  handler and the scroll handler when the viewport reaches the top; a no-op
+   *  while a page is in flight, when the session has no more history, or while
+   *  the session is a pending optimistic spawn. Prepending older rows only
+   *  grows the list ABOVE the tail, so it is safe while the agent is
+   *  generating — unlike a committed refetch, it never clobbers the AI
+   *  placeholder, and blocking it made the button feel dead mid-run. */
+  const loadOlder = useCallback(() => {
+    if (!sessionId || sessionId.startsWith('new-')) return;
+    if (!hasMore || loadingOlderRef.current) return;
+    loadingOlderRef.current = true;
+    setLoadingOlder(true);
+    setLoadOlderError(false);
+    const el = scrollRef?.current;
+    if (el) pendingScrollAnchorRef.current = { prevHeight: el.scrollHeight, prevTop: el.scrollTop };
+    // Session id snapshot: prepending a window fetched for the PREVIOUS
+    // session into the freshly-switched timeline is worse than dropping the
+    // page, so the response is discarded if the user switched mid-flight.
+    const requestedSessionId = sessionId;
+    fetch(`/api/chat/${sessionId}?before=${oldestIndex}`)
+      .then(res => {
+        if (!res.ok) throw new Error(`HTTP ${res.status}`);
+        return res.json();
+      })
+      .then((data: { session?: { messages?: ChatMessageData[] }; hasMore?: boolean; oldestIndex?: number }) => {
+        // The main load effect may have cleared/repurposed localMessages for a
+        // new session while this fetch was in flight.
+        if (sessionIdRef.current !== requestedSessionId) return;
+        const older = data.session?.messages ?? [];
+        setHasMore(Boolean(data.hasMore));
+        if (typeof data.oldestIndex === 'number') setOldestIndex(data.oldestIndex);
+        if (older.length === 0) {
+          // No rows prepended: the recorded anchor is stale — drop it so a
+          // later tick cannot apply it against the wrong geometry.
+          pendingScrollAnchorRef.current = null;
+          return;
+        }
+        setLocalMessages(prev => {
+          // Drop overlap guard: the server window is index-based, so the
+          // fetched slice is strictly older than everything already mounted.
+          return [...normalizeNoticePositions(older), ...prev];
+        });
+        // Bump the prepend tick so the layout effect below re-runs for THIS
+        // commit — it previously depended only on stable identities and ran
+        // exactly once at mount, so the viewport anchor never fired and every
+        // pagination jump snapped the user to the (shifted) top.
+        setPrependTick(t => t + 1);
+      })
+      .catch(() => {
+        // Keep the button mounted and marked for retry; a swallowed failure
+        // previously also cleared hasMore on the next full reload path.
+        if (sessionIdRef.current === requestedSessionId) setLoadOlderError(true);
+      })
+      .finally(() => {
+        loadingOlderRef.current = false;
+        setLoadingOlder(false);
+      });
+  }, [sessionId, hasMore, oldestIndex, scrollRef, setLocalMessages]);
+
+  // Position preservation: after older rows commit above the viewport, shift
+  // scrollTop by the height delta so the rows the user was reading stay put.
+  // prependTick changes on every prepend — without it the effect ran only at
+  // mount (its other deps are stable) and never re-anchored.
+  useLayoutEffect(() => {
+    const anchor = pendingScrollAnchorRef.current;
+    if (!anchor) return;
+    const el = scrollRef?.current;
+    if (!el) return;
+    pendingScrollAnchorRef.current = null;
+    const delta = el.scrollHeight - anchor.prevHeight;
+    if (delta > 0) el.scrollTop = anchor.prevTop + delta;
+  }, [prependTick, scrollRef]);
+
+  return {
+    sessionData,
+    hasMore,
+    loadingOlder,
+    loadOlderError,
+    sessionLoading,
+    loadOlder,
+    adoptedSessionIdRef,
+    seededModelRef,
+    applySessionData,
+    refreshSessionMeta,
+    setSessionModel: setSessionModelWithSeed,
+    timelineOwnedByOptimistic,
+  };
+}