ompchamber 1.1.0 → 1.2.0

package/src/client/hooks/chat/omp/prompt-send.ts

@@ -17,7 +17,7 @@
 
 import { useCallback } from 'preact/hooks';
 import type { Dispatch, SetStateAction } from 'preact/compat';
-import type { OmpAgentState } from '@/shared/types';
+import type { AgentImage, OmpAgentState } from '@/shared/types';
 import type { ApprovalMode } from '@/shared/lib/omp/config/access-mode';
 
 export interface OmpPromptSenderDeps {
@@ -29,11 +29,11 @@ export interface OmpPromptSenderDeps {
 }
 
 export interface OmpPromptSender {
-  sendPrompt: (message: string, images?: { data: string; mimeType: string }[], options?: { accessMode?: ApprovalMode }) => Promise<boolean>;
+  sendPrompt: (message: string, images?: AgentImage[], options?: { accessMode?: ApprovalMode }) => Promise<boolean>;
   sendNewPrompt: (
     message: string,
     cwd: string,
-    images?: { data: string; mimeType: string }[],
+    images?: AgentImage[],
     composerOptions?: { model?: { provider: string; modelId: string } | null; thinkingLevel?: string | null; accessMode?: ApprovalMode },
   ) => Promise<{ sessionId: string; model: { provider: string; modelId: string } | null } | null>;
 }
@@ -44,7 +44,7 @@ export function useOmpPromptSender(deps: OmpPromptSenderDeps): OmpPromptSender {
   /** Send a prompt to the omp session via the RPC bridge. */
   const sendPrompt = useCallback(async (
     message: string,
-    images?: { data: string; mimeType: string }[],
+    images?: AgentImage[],
     options?: { accessMode?: ApprovalMode },
   ) => {
     const sid = sessionIdRef.current;
@@ -105,7 +105,7 @@ export function useOmpPromptSender(deps: OmpPromptSenderDeps): OmpPromptSender {
   const sendNewPrompt = useCallback(async (
     message: string,
     cwd: string,
-    images?: { data: string; mimeType: string }[],
+    images?: AgentImage[],
     composerOptions?: { model?: { provider: string; modelId: string } | null; thinkingLevel?: string | null; accessMode?: ApprovalMode },
   ): Promise<{ sessionId: string; model: { provider: string; modelId: string } | null } | null> => {
     setState((prev) => ({ ...prev, isGenerating: true, error: null }));

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

@@ -17,6 +17,8 @@ import type { Attachment, ChatMessageData, OmpAgentHandle, QueuedMessageModel }
 import type { QueuedMessage } from '@/client/components/workspace/chat-timeline/QueueList';
 import type { ApprovalMode } from '@/shared/lib/omp/config/access-mode';
 import { applyComposerPick, consumeComposerPick, stashComposerPick, type DeferredModelStore } from '@/client/hooks/chat/timeline/deferred-model';
+import { dispatchBtwCommand } from '@/client/hooks/chat/btw/intercept';
+import { prepareQueuedAttachments } from '@/shared/lib/chat/attachments';
 
 export interface ChatTimelineActionsDeps {
   inputValue: string;
@@ -106,6 +108,14 @@ export function useChatTimelineActions(deps: ChatTimelineActionsDeps): ChatTimel
     // resume delivering after this run ends.
     stopHoldRef.current = false;
 
+    // `/btw [question]` is the side-question entry point, not chat text: the
+    // panel owns it (omp's `/btw` is TUI-only, so nothing downstream would
+    // understand the token). A bare `/btw` only opens the panel's history.
+    if (dispatchBtwCommand(textToSend, attachments)) {
+      setInputValue('');
+      return;
+    }
+
     if (isGenerating) {
       if (options?.steering) {
         // Explicit steering while a run is active.
@@ -140,7 +150,12 @@ export function useChatTimelineActions(deps: ChatTimelineActionsDeps): ChatTimel
       // panel is a view of it. Delivery happens when the run ends — the
       // wrapper's terminal `agent_end` claims the head and dispatches it.
       setInputValue('');
-      enqueueMessage({ text: textToSend, attachments, model });
+      // The queue row is JSON: a `File` does not survive it. Capture the text
+      // contents and the display fields now, so delivery can inline the files
+      // and render the chips without a live handle.
+      void prepareQueuedAttachments(attachments).then((prepared) => {
+        enqueueMessage({ text: textToSend, attachments: prepared, model });
+      });
       return;
     }
 

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

@@ -10,8 +10,10 @@ 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';
@@ -119,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,
@@ -141,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.
@@ -303,6 +308,9 @@ export function useChatTimeline({ folders = [], appSettings = {} }: UseChatTimel
     loadOlderError,
     sessionLoading,
     loadOlder,
+    userTurns,
+    jumpingTurn,
+    jumpToUserTurn,
     generatingVerb,
     messageQueue,
     removeMessage,

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,13 +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 { flushDeferredPick, type DeferredModelStore } from '@/client/hooks/chat/timeline/deferred-model';
-import { isTextAttachmentFile } from '@/shared/lib/chat/attachments';
+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';
@@ -104,32 +110,13 @@ 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 };
   }, []);
 
@@ -157,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 = {
@@ -182,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),
       }))
     };
 
@@ -229,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) {
@@ -261,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;

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 };
 }