ompchamber 1.0.0 → 1.2.0

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

@@ -8,9 +8,12 @@ import { useChatTimelineScroll } from '@/client/hooks/chat/timeline/scroll';
 import { useTimelineAutoScroll } from '@/client/hooks/chat/timeline/auto-scroll';
 import { useChatTimelineActions } from '@/client/hooks/chat/timeline/actions';
 import { useChatTimelineSend } from '@/client/hooks/chat/timeline/send';
+import type { ComposerModelPick } from '@/client/hooks/chat/timeline/deferred-model';
 import { useSessionLoad } from '@/client/hooks/chat/timeline/session-load';
+import { useUserTurns } from '@/client/hooks/chat/timeline/user-turns';
 import { useBrowserPageContextInsert } from '@/client/hooks/chat/timeline/browser-context';
-import { cancelStreamingCoalescer, createOmpAgentCallbacks } from '@/shared/lib/chat/timeline/omp-callbacks';
+import { createOmpAgentCallbacks } from '@/shared/lib/chat/timeline/omp-callbacks';
+import { cancelStreamingCoalescer } from '@/shared/lib/chat/timeline/stream-coalescer';
 import { readStreamTransport } from '@/shared/lib/chat/omp/transport';
 import { ACCESS_MODE_SETTING_KEY, normalizeApprovalMode } from '@/shared/lib/omp/config/access-mode';
 import type { ApprovalMode } from '@/shared/lib/omp/config/access-mode';
@@ -118,14 +121,9 @@ export function useChatTimeline({ folders = [], appSettings = {} }: UseChatTimel
 
   const {
     sessionData,
-    adoptedSessionIdRef,
-    refreshSessionMeta,
-    seedSession,
+    adoptedSessionIdRef, refreshSessionMeta, seedSession,
     hasMore,
-    loadingOlder,
-    loadOlderError,
-    sessionLoading,
-    loadOlder,
+    loadingOlder, loadOlderError, sessionLoading, loadOlder, jumpToTurn,
   } = useSessionLoad({
     sessionId,
     setLocalMessages,
@@ -140,6 +138,14 @@ export function useChatTimeline({ folders = [], appSettings = {} }: UseChatTimel
   });
   loadOlderRef.current = loadOlder;
 
+  // Jump rail: the full-history turn index (the mounted window is only a page
+  // of a long session) plus the paging walk that reaches a turn outside it.
+  const { turns: userTurns, jumping: jumpingTurn, jumpToTurn: jumpToUserTurn } = useUserTurns({
+    sessionId,
+    messages: localMessages,
+    jumpToTurn,
+  });
+
   // Composer picks made BEFORE the omp session exists (pending "new-…" view):
   // there is no live session to receive the RPC yet, so the selection is held
   // here and applied to the spawn command on first send.
@@ -148,6 +154,15 @@ export function useChatTimeline({ folders = [], appSettings = {} }: UseChatTimel
   // Live mirror of the composer's model/thinking pick: the enqueue path
   // snapshots it onto queued items so auto-delivery replays those settings.
   const composerModelRef = useRef<{ provider: string; modelId: string; thinkingLevel: string } | null>(null);
+  // Picks made WHILE a turn streams: held here so they cannot re-target the
+  // answer in flight (omp applies set_model to the running turn), and pushed
+  // onto the session right before the next prompt.
+  const deferredComposerPickRef = useRef<ComposerModelPick | null>(null);
+  // A stashed pick belongs to ONE session's next prompt: carrying it across a
+  // switch would silently re-target the session the user just opened.
+  useEffect(() => {
+    deferredComposerPickRef.current = null;
+  }, [sessionId]);
 
   // Access-control mode is a global, persisted user preference (unlike the
   // per-session model/thinking picks): it hydrates from appSettings at first
@@ -229,7 +244,7 @@ export function useChatTimeline({ folders = [], appSettings = {} }: UseChatTimel
     seedSession,
     pendingComposerModelRef,
     pendingThinkingLevelRef,
-    composerModelRef,
+    deferredComposerPickRef,
     accessModeRef,
     abortControllerRef,
     setInputValue,
@@ -274,6 +289,7 @@ export function useChatTimeline({ folders = [], appSettings = {} }: UseChatTimel
     pendingComposerModelRef,
     pendingThinkingLevelRef,
     composerModelRef,
+    deferredComposerPickRef,
     accessModeRef,
     setSearchParams,
   });
@@ -292,6 +308,9 @@ export function useChatTimeline({ folders = [], appSettings = {} }: UseChatTimel
     loadOlderError,
     sessionLoading,
     loadOlder,
+    userTurns,
+    jumpingTurn,
+    jumpToUserTurn,
     generatingVerb,
     messageQueue,
     removeMessage,
@@ -321,6 +340,7 @@ export function useChatTimeline({ folders = [], appSettings = {} }: UseChatTimel
     accessMode,
     handleAccessModeChange,
     composerModelRef,
+    deferredComposerPickRef,
     extensionDialogs,
     resolveExtensionDialog,
     respondToExtensionUi: ompAgent.respondToExtensionUi,

package/src/client/hooks/chat/timeline/prompt-text.ts

@@ -20,8 +20,13 @@ type TextFileAttachment = Parameters<typeof composeMessageWithTextAttachments>[1
  * 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.
+ *
+ * A file whose bytes could not be read is left OUT rather than inlined empty:
+ * an empty fenced block tells the model the file exists and says nothing, which
+ * is worse than not mentioning it. The composer reports the omission.
  */
 export async function buildPromptText(text: string, textFiles: TextFileAttachment[]): Promise<string> {
+  const readable = textFiles.filter((file) => !('missing' in file && file.missing));
   let translated = text;
   try {
     const names = await loadAgentNames();
@@ -31,5 +36,5 @@ export async function buildPromptText(text: string, textFiles: TextFileAttachmen
   }
   // 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);
+  return composeMessageWithTextAttachments(translateFileMentions(translated), readable);
 }

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

@@ -12,12 +12,19 @@
 
 import { useCallback } from 'preact/hooks';
 import type { Dispatch, SetStateAction } from 'preact/compat';
-import type { Attachment, ChatMessageData, OmpAgentHandle, QueuedMessageModel } from '@/shared/types';
+import type { AgentImage, 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 type { SessionSeed } from '@/client/hooks/chat/timeline/session-load';
 import { buildPromptText } from '@/client/hooks/chat/timeline/prompt-text';
-import { isTextAttachmentFile } from '@/shared/lib/chat/attachments';
+import { flushDeferredPick, type DeferredModelStore } from '@/client/hooks/chat/timeline/deferred-model';
+import {
+  attachmentImage,
+  attachmentName,
+  attachmentSize,
+  attachmentType,
+  readTextAttachments,
+} from '@/shared/lib/chat/attachments';
 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';
@@ -51,9 +58,9 @@ export interface ChatTimelineSendDeps {
   /** 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 };
+  /** Picks the composer made while a turn was streaming. Pushed onto the
+   *  session here, immediately before the prompt they were meant for. */
+  deferredComposerPickRef: DeferredModelStore;
   abortControllerRef: { current: AbortController | null };
   setInputValue: (v: string) => void;
   setSearchParams: (fn: (prev: URLSearchParams) => URLSearchParams, opts?: { replace?: boolean }) => void;
@@ -91,6 +98,7 @@ export function useChatTimelineSend(deps: ChatTimelineSendDeps): ChatTimelineSen
     seedSession,
     pendingComposerModelRef,
     pendingThinkingLevelRef,
+    deferredComposerPickRef,
     accessModeRef,
     abortControllerRef,
     setInputValue,
@@ -102,41 +110,25 @@ export function useChatTimelineSend(deps: ChatTimelineSendDeps): ChatTimelineSen
   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,
-      }));
+  ): Promise<{ promptText: string; images?: AgentImage[] }> => {
+    const textFiles = await readTextAttachments(attachments);
     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 }));
+      .map(attachmentImage)
+      .filter((image): image is AgentImage => image !== null);
     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[]) => {
+    // A steer IS a new prompt: a pick made during the interrupted turn belongs
+    // to it, so it is pushed before the interrupt-and-reply starts the turn.
+    await flushDeferredPick(ompAgent, deferredComposerPickRef);
     const { promptText, images } = await prepareDeliverable(text, attachments);
     const ok = await ompAgent.sendInterruptAndReply(promptText, images);
     if (!ok) setInputValue(text);
-  }, [ompAgent, prepareDeliverable, setInputValue]);
+  }, [ompAgent, prepareDeliverable, setInputValue, deferredComposerPickRef]);
 
   const executeSend = useCallback(async (
     text: string,
@@ -152,19 +144,10 @@ export function useChatTimelineSend(deps: ChatTimelineSendDeps): ChatTimelineSen
     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.
-    }
+    // and for inlining into the prompt. Reads a persisted `content` when the
+    // attachment is a replay (queue delivery, retry) and has no live File.
+    const textFiles = await readTextAttachments(attachments);
+    const textContentById = new Map(textFiles.map((file) => [file.id, file.content]));
 
     const now = Date.now();
     const newUserMsg: ChatMessageData = {
@@ -177,11 +160,13 @@ export function useChatTimelineSend(deps: ChatTimelineSendDeps): ChatTimelineSen
       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),
+        name: attachmentName(a),
+        // The blob URL only lives as long as this page, so the data URL wins
+        // where it exists — a persisted turn re-renders its images from it.
+        preview: a.dataBase64 ? `data:${attachmentType(a)};base64,${a.dataBase64}` : a.preview,
+        type: attachmentType(a),
+        size: attachmentSize(a),
+        content: textContentById.get(a.id),
       }))
     };
 
@@ -209,6 +194,12 @@ export function useChatTimelineSend(deps: ChatTimelineSendDeps): ChatTimelineSen
     if (isOmpSession) {
       aiPlaceholderIdRef.current = aiPlaceholderId;
       optimisticUserIdRef.current = userMsgId;
+      // A model/thinking pick made while the previous turn streamed was held
+      // back so it could not re-target that answer. A queued delivery does NOT
+      // own it: that item carries its own snapshot, so the pick stays pending
+      // for the composer's own next prompt instead of being spent — and then
+      // overwritten — by a delivery it was never meant for.
+      if (!modelOverride) await flushDeferredPick(ompAgent, deferredComposerPickRef);
       // Replay the queued snapshot first so the prompt runs on the exact
       // model/thinking the item was queued with.
       if (modelOverride) {
@@ -218,18 +209,10 @@ export function useChatTimelineSend(deps: ChatTimelineSendDeps): ChatTimelineSen
         }
       }
       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,
-        }));
+        .map(attachmentImage)
+        .filter((image): image is AgentImage => image !== null);
+      // Inline text-file contents into the prompt: the model sees the full file
+      // content as fenced blocks, not just the filename.
       const promptText = await buildPromptText(text, textFiles);
       const ok = await ompAgent.sendPrompt(promptText, images.length ? images : undefined, { accessMode: effectiveAccessMode });
       if (!ok) {
@@ -250,16 +233,8 @@ export function useChatTimelineSend(deps: ChatTimelineSendDeps): ChatTimelineSen
       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,
-          }));
+          .map(attachmentImage)
+          .filter((image): image is AgentImage => image !== null);
         const promptText = await buildPromptText(text, textFiles);
         optimisticUserIdRef.current = userMsgId;
         const composerModel = pendingComposerModelRef.current;
@@ -329,6 +304,6 @@ export function useChatTimelineSend(deps: ChatTimelineSendDeps): ChatTimelineSen
         scrollToBottom,
       })
     );
-  }, [appSettings, folders, isOmpSession, ompAgent, selectedFolderId, sessionId, scrollToBottom, jumpToBottom, persistMessages, seedSession, pendingComposerModelRef, pendingThinkingLevelRef, accessModeRef]);
+  }, [appSettings, folders, isOmpSession, ompAgent, selectedFolderId, sessionId, scrollToBottom, jumpToBottom, persistMessages, seedSession, pendingComposerModelRef, pendingThinkingLevelRef, deferredComposerPickRef, accessModeRef]);
   return { steerOmpAgent, executeSend };
 }

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

@@ -94,7 +94,7 @@ export function useSessionLoad(deps: UseSessionLoadDeps) {
 
   // Older-window pagination (cursor, retry flag, scroll anchoring) lives in its
   // own hook so this one stays under the repo's per-file size ceiling.
-  const { hasMore, loadingOlder, loadOlderError, loadOlder, resetPages, applyWindow } = useSessionPagination({
+  const { hasMore, loadingOlder, loadOlderError, loadOlder, jumpToTurn, resetPages, applyWindow } = useSessionPagination({
     sessionId,
     sessionIdRef,
     setLocalMessages,
@@ -268,6 +268,7 @@ export function useSessionLoad(deps: UseSessionLoadDeps) {
     loadOlderError,
     sessionLoading,
     loadOlder,
+    jumpToTurn,
     adoptedSessionIdRef,
     refreshSessionMeta,
     seedSession,

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

@@ -8,6 +8,14 @@
  * `/api/chat/:id?before=` into the head of the message list and keeps the
  * viewport anchored on the rows the user was reading. Extracted from
  * useSessionLoad so that hook stays under the repo's per-file size ceiling.
+ *
+ * The same cursor serves the jump rail: a turn the user picks from the FULL
+ * history is usually not mounted yet (the timeline only holds the newest
+ * window plus whatever was paged in), so {@link SessionPagination.jumpToTurn}
+ * pages contiguous windows from the head until that turn's row exists. Windows
+ * must stay contiguous — a middle window fetched straight to the target would
+ * leave a hole in the timeline — so the jump walks the cursor down, one bounded
+ * chunk per request instead of the default page size.
  */
 
 import type { Dispatch, RefObject, SetStateAction } from 'preact/compat';
@@ -33,12 +41,31 @@ export interface SessionPagination {
    *  dropping hasMore, which made the button vanish with no feedback. */
   loadOlderError: boolean;
   loadOlder: () => void;
+  /** Reach a user turn by paging history until its row is mounted. Returns
+   *  whether the row was reached; a turn inside the mounted window (or a live
+   *  row, `index < 0`) needs no paging and is not this hook's concern. */
+  jumpToTurn: (id: string, index: number) => Promise<boolean>;
   /** Forget the cursor and the retry flag — a window belongs to one session. */
   resetPages: () => void;
   /** Adopt the window metadata a session load returned. */
   applyWindow: (hasMore: unknown, oldestIndex: unknown) => void;
 }
 
+/** Messages one jump request may pull. Larger than the default page so a jump
+ *  is a few round trips instead of dozens, small enough that no single payload
+ *  mounts an unbounded slice of the session. */
+const JUMP_CHUNK_MESSAGES = 300;
+
+/** Ceiling on jump requests: a cursor that refuses to advance (a server window
+ *  that keeps re-serving the same slice) must end the walk, not spin. */
+const JUMP_MAX_REQUESTS = 40;
+
+interface WindowPayload {
+  messages: ChatMessageData[];
+  hasMore?: boolean;
+  oldestIndex?: number;
+}
+
 export function useSessionPagination(deps: UseSessionPaginationDeps): SessionPagination {
   const { sessionId, sessionIdRef, setLocalMessages, scrollRef } = deps;
 
@@ -51,6 +78,16 @@ export function useSessionPagination(deps: UseSessionPaginationDeps): SessionPag
   // explicit change signal per commit).
   const [prependTick, setPrependTick] = useState(0);
   const loadingOlderRef = useRef(false);
+  // True from a jump's first request until its target scroll has settled. A
+  // jump prepends rows above a viewport that is still parked near the top, so
+  // the scroll handler would read "the user reached the top" and page an extra
+  // window nobody asked for — and that window's own scroll anchor would fight
+  // the jump's.
+  const jumpActiveRef = useRef(false);
+  // Live cursor: a jump walks it across several requests, and state does not
+  // update between iterations of that loop.
+  const oldestIndexRef = useRef(0);
+  oldestIndexRef.current = oldestIndex;
   // 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);
@@ -58,6 +95,9 @@ export function useSessionPagination(deps: UseSessionPaginationDeps): SessionPag
   const resetPages = useCallback(() => {
     setHasMore(false);
     setOldestIndex(0);
+    // The live cursor too: a jump could otherwise read the previous session's
+    // window start before the state change has re-rendered.
+    oldestIndexRef.current = 0;
     loadingOlderRef.current = false;
     setLoadingOlder(false);
     setLoadOlderError(false);
@@ -68,6 +108,51 @@ export function useSessionPagination(deps: UseSessionPaginationDeps): SessionPag
     if (typeof oldestIndexFromLoad === 'number') setOldestIndex(oldestIndexFromLoad);
   }, []);
 
+  /** One older window ending just before `before`. `limit` of null leaves the
+   *  server's default window size in place. */
+  const fetchWindow = useCallback(async (before: number, limit: number | null): Promise<WindowPayload | null> => {
+    if (!sessionId) return null;
+    const suffix = limit === null ? '' : `&limit=${limit}`;
+    const res = await fetch(`/api/chat/${sessionId}?before=${before}${suffix}`);
+    if (!res.ok) throw new Error(`HTTP ${res.status}`);
+    const data = (await res.json()) as { session?: { messages?: ChatMessageData[] }; hasMore?: boolean; oldestIndex?: number };
+    return { messages: data.session?.messages ?? [], hasMore: data.hasMore, oldestIndex: data.oldestIndex };
+  }, [sessionId]);
+
+  /** Record the viewport geometry an older-window prepend is about to shift. */
+  const anchorViewport = useCallback(() => {
+    const el = scrollRef?.current;
+    if (el) pendingScrollAnchorRef.current = { prevHeight: el.scrollHeight, prevTop: el.scrollTop };
+  }, [scrollRef]);
+
+  /** Drop the jump's scroll-handler guard once its target scroll has settled.
+   *  Until then the viewport is still near the top of history (where the paging
+   *  trigger lives) and the smooth scroll is animating, so a stray "reached the
+   *  top" read would page a window nobody asked for. */
+  const releaseJumpGuard = useCallback(() => {
+    const el = scrollRef?.current;
+    if (!el) {
+      jumpActiveRef.current = false;
+      return;
+    }
+    let lastTop = el.scrollTop;
+    let settledFrames = 0;
+    const watch = () => {
+      if (el.scrollTop === lastTop) settledFrames += 1;
+      else {
+        settledFrames = 0;
+        lastTop = el.scrollTop;
+      }
+      // A few still frames = the smooth scroll is done (or never started).
+      if (settledFrames >= 5) {
+        jumpActiveRef.current = false;
+        return;
+      }
+      requestAnimationFrame(watch);
+    };
+    requestAnimationFrame(watch);
+  }, [scrollRef]);
+
   /** 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
@@ -77,27 +162,22 @@ export function useSessionPagination(deps: UseSessionPaginationDeps): SessionPag
    *  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;
+    if (!hasMore || loadingOlderRef.current || jumpActiveRef.current) return;
     loadingOlderRef.current = true;
     setLoadingOlder(true);
     setLoadOlderError(false);
-    const el = scrollRef?.current;
-    if (el) pendingScrollAnchorRef.current = { prevHeight: el.scrollHeight, prevTop: el.scrollTop };
+    anchorViewport();
     // 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 }) => {
+    fetchWindow(oldestIndex, null)
+      .then((page) => {
         // 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 ?? [];
-        applyWindow(data.hasMore, data.oldestIndex);
+        if (!page || sessionIdRef.current !== requestedSessionId) return;
+        const older = page.messages;
+        applyWindow(page.hasMore, page.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.
@@ -124,7 +204,74 @@ export function useSessionPagination(deps: UseSessionPaginationDeps): SessionPag
         loadingOlderRef.current = false;
         setLoadingOlder(false);
       });
-  }, [sessionId, sessionIdRef, hasMore, oldestIndex, scrollRef, setLocalMessages, applyWindow]);
+  }, [sessionId, sessionIdRef, hasMore, oldestIndex, fetchWindow, anchorViewport, setLocalMessages, applyWindow]);
+
+  /**
+   * Walk the cursor down until the row with `id` is mounted, prepending every
+   * window on the way so the timeline stays contiguous, then adopt the final
+   * window metadata. Shares the in-flight flag with `loadOlder`, so the
+   * scroll-triggered loader cannot interleave a second cursor walk.
+   *
+   * Resolves true when the row is mounted once the call returns — it already
+   * was (a live row, or one inside the mounted window) or the walk brought it
+   * in. The DOM commit for the last prepend may still be pending; the caller
+   * owns waiting for the node.
+   */
+  const jumpToTurn = useCallback(async (id: string, index: number): Promise<boolean> => {
+    if (!sessionId || sessionId.startsWith('new-')) return false;
+    // `index < 0` is a live row (an optimistic send the committed history does
+    // not carry yet); `index >= oldestIndex` is inside the mounted window.
+    // Both are already on screen, so the jump needs no paging.
+    if (index < 0 || index >= oldestIndexRef.current) return true;
+    if (loadingOlderRef.current) return false;
+    const requestedSessionId = sessionId;
+    loadingOlderRef.current = true;
+    jumpActiveRef.current = true;
+    setLoadingOlder(true);
+    setLoadOlderError(false);
+    // No viewport anchor here, deliberately: the anchor exists to hold the
+    // user's reading position when history is paged in while they read, but a
+    // jump is an explicit request for a DIFFERENT position. Anchoring would
+    // write `scrollTop` on the prepend commit and abort the caller's smooth
+    // scroll to the target mid-flight.
+
+    let cursor = oldestIndexRef.current;
+    let lastHasMore: unknown = hasMore;
+    let reached = false;
+    let requests = 0;
+    try {
+      while (!reached && cursor > index && requests < JUMP_MAX_REQUESTS) {
+        requests += 1;
+        // Stop exactly at the target: a window ending before `index` with
+        // `cursor - index` rows has that turn as its oldest row.
+        const page = await fetchWindow(cursor, Math.min(JUMP_CHUNK_MESSAGES, cursor - index));
+        // The user switched sessions mid-walk: prepending this window would
+        // inject another session's rows into the fresh timeline.
+        if (!page || sessionIdRef.current !== requestedSessionId) return false;
+        const older = page.messages;
+        if (older.length === 0) break;
+        const next = typeof page.oldestIndex === 'number' ? page.oldestIndex : Math.max(0, cursor - older.length);
+        setLocalMessages(prev => [...older, ...prev]);
+        reached = older.some((message) => message.id === id);
+        // A cursor that did not advance would re-serve the same slice forever.
+        if (next >= cursor) break;
+        cursor = next;
+        lastHasMore = page.hasMore;
+      }
+    } catch {
+      if (sessionIdRef.current === requestedSessionId) setLoadOlderError(true);
+      return false;
+    } finally {
+      loadingOlderRef.current = false;
+      setLoadingOlder(false);
+    }
+    applyWindow(lastHasMore, cursor);
+    // Bump the prepend tick so the viewport-anchor effect re-runs for the rows
+    // this walk prepended (same contract as loadOlder).
+    if (requests > 0) setPrependTick(t => t + 1);
+    releaseJumpGuard();
+    return reached;
+  }, [sessionId, sessionIdRef, hasMore, fetchWindow, setLocalMessages, applyWindow, releaseJumpGuard]);
 
   // Position preservation: after older rows commit above the viewport, shift
   // scrollTop by the height delta so the rows the user was reading stay put.
@@ -140,5 +287,5 @@ export function useSessionPagination(deps: UseSessionPaginationDeps): SessionPag
     if (delta > 0) el.scrollTop = anchor.prevTop + delta;
   }, [prependTick, scrollRef]);
 
-  return { hasMore, loadingOlder, loadOlderError, loadOlder, resetPages, applyWindow };
+  return { hasMore, loadingOlder, loadOlderError, loadOlder, jumpToTurn, resetPages, applyWindow };
 }