ompchamber 1.2.1 → 2.0.1

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

@@ -23,6 +23,24 @@ import { useSessionState } from '@/client/hooks/workspace/session-state';
 
 const STEERING_STATE_KEY = 'chat.steeringQueue';
 
+/**
+ * How often a mounted session with a non-empty queue re-offers a delivery slot.
+ *
+ * This is the safety net for a server whose own timers have stopped firing: a
+ * long-lived `bun --hot` process can stop running `setTimeout` callbacks
+ * entirely while still answering HTTP normally (observed live — a 4-hour dev
+ * server whose SSE heartbeat never fired and whose queued follow-ups never
+ * drained, while every request returned in 0.01s). Auto-delivery is timer-driven
+ * server-side, so it dies with those timers; a client poll runs in a different
+ * process and is immune.
+ *
+ * Only armed while something is actually queued, and each tick is one POST that
+ * doubles as the panel's reconcile, so an idle session costs nothing. 3s is a
+ * deliberate compromise: slow enough to be invisible on the wire, fast enough
+ * that a stranded item lands before the user wonders about it.
+ */
+const QUEUE_POLL_INTERVAL_MS = 3_000;
+
 function queueUrl(sessionId: string): string {
   return `/api/sessions/${encodeURIComponent(sessionId)}/queue`;
 }
@@ -74,25 +92,64 @@ export function useChatTimelineQueue(sessionId: string | null): ChatTimelineQueu
       })
       .catch(() => {});
   }, [sessionId]);
+  // Offer the server a delivery slot for this session. The server-side claim
+  // makes this harmless when a run is active or another tab already took the
+  // head — this used to be the client auto-delivery effect, which fired into
+  // whatever session was open at the time.
+  //
+  // The response carries the canonical queue, so this doubles as a reconcile.
+  const nudgeDelivery = useCallback(() => {
+    if (!sessionId) return;
+    const epoch = hydrateEpochRef.current;
+    fetch(`${queueUrl(sessionId)}/deliver`, { method: 'POST' })
+      .then((res) => readQueueResponse(res))
+      .then((queue) => {
+        // Only reconcile when this is still the session on screen: the poll can
+        // outlive a switch, and writing another session's queue here is the
+        // exact cross-session bug the server-owned store was built to stop.
+        if (cancelledRef.current || hydrateEpochRef.current !== epoch) return;
+        if (queue) setMessageQueueState(queue);
+      })
+      .catch(() => {});
+  }, [sessionId]);
+
   useEffect(() => {
     cancelledRef.current = false;
     refresh();
-    const onFocus = () => refresh();
+    // Mount and every focus regain offer a delivery slot. Focus is the trigger
+    // the recovery path depends on, so it must re-nudge even when the queue
+    // length is unchanged: keying this on `messageQueue.length > 0` (a boolean
+    // that stays true while the item is stranded) meant the effect never re-ran
+    // and a stuck queue stayed stuck.
+    nudgeDelivery();
+    const onFocus = () => {
+      refresh();
+      nudgeDelivery();
+    };
     window.addEventListener('focus', onFocus);
     return () => {
       cancelledRef.current = true;
       window.removeEventListener('focus', onFocus);
     };
-  }, [refresh]);
+  }, [refresh, nudgeDelivery]);
+
+  // Items appearing while the session is already mounted (a send while
+  // streaming, or another tab's write): offer a slot without waiting for focus.
+  useEffect(() => {
+    if (messageQueue.length > 0) nudgeDelivery();
+  }, [messageQueue.length, nudgeDelivery]);
 
-  // Mounted session with queued items: offer the server a delivery slot. The
-  // server-side claim makes this harmless when a run is active or another tab
-  // already took the head — this used to be the client auto-delivery effect,
-  // which fired into whatever session was open at the time.
+  // Safety net: while anything is queued, keep offering a slot on an interval.
+  // Server-side auto-delivery is timer-driven and a long-lived `--hot` server
+  // can lose that capability silently; this poll lives in the browser and is
+  // unaffected. The effect is torn down the moment the queue empties, so a
+  // session with nothing queued never polls.
+  const hasQueued = messageQueue.length > 0;
   useEffect(() => {
-    if (!sessionId || messageQueue.length === 0) return;
-    fetch(`${queueUrl(sessionId)}/deliver`, { method: 'POST' }).catch(() => {});
-  }, [sessionId, messageQueue.length > 0]);
+    if (!sessionId || !hasQueued) return;
+    const timer = setInterval(nudgeDelivery, QUEUE_POLL_INTERVAL_MS);
+    return () => clearInterval(timer);
+  }, [sessionId, hasQueued, nudgeDelivery]);
 
   const enqueueMessage = useCallback((item: Omit<QueuedMessage, 'id'>) => {
     if (!sessionId) return;

package/src/client/hooks/chat/timeline/scroll.test.ts

@@ -0,0 +1,260 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Chat timeline scroll contract. Both behaviours here were the bug:
+ *
+ * 1. The jump that follows a session's committed history used the follow-gated
+ *    `scrollToBottom`, and follow mode belongs to the mounted view, not to the
+ *    session being opened — a user who scrolled up before switching left it
+ *    disengaged, so the newly opened session painted at `scrollTop = 0` with no
+ *    scroll event to re-engage it and stayed there. Verified live in the
+ *    chamber: scroll up in session A, open session B, viewport pinned at the
+ *    head with the jump button showing until it was clicked.
+ * 2. Nothing re-pinned the tail when content grew while the viewport was
+ *    pinned (a prepended window, a late Shiki/mermaid/image layout), so a jump
+ *    target measured a frame earlier — or at open time — was stranded.
+ *
+ * Runs against a real DOM (happy-dom) because these are Preact hooks; geometry
+ * is faked on the container, since happy-dom does no layout.
+ */
+
+import { afterAll, beforeAll, describe, expect, jest as fakeTimers, test } from 'bun:test';
+import { Window } from 'happy-dom';
+import type { h as PreactH, render as PreactRender } from 'preact';
+import type { act as PreactAct } from 'preact/test-utils';
+import type { useChatTimelineScroll as UseScroll, ChatTimelineScrollResult } from '@/client/hooks/chat/timeline/scroll';
+import type { useTimelineAutoScroll as UseAuto } from '@/client/hooks/chat/timeline/auto-scroll';
+import type { ChatMessageData } from '@/shared/types';
+
+let useChatTimelineScroll: typeof UseScroll;
+let useTimelineAutoScroll: typeof UseAuto;
+let h: typeof PreactH;
+let render: typeof PreactRender;
+let act: typeof PreactAct;
+
+let win: Window;
+const scrolled: Array<{ top: number; behavior?: ScrollBehavior }> = [];
+const geometry = { top: 0, height: 5000, viewport: 500 };
+
+/** Observe what the hook asks for; 'instant' also lands (a smooth scroll would
+ *  animate in a browser, so the fake keeps it as a recorded intent only). */
+function applyTop(el: HTMLDivElement, value: number) {
+  geometry.top = Math.max(0, Math.min(value, geometry.height - geometry.viewport));
+  // The global `Event` the hook's listener expects: happy-dom's, installed
+  // into globalThis in beforeAll.
+  el.dispatchEvent(new Event('scroll'));
+}
+
+function installScroller(el: HTMLDivElement) {
+  Object.defineProperty(el, 'scrollHeight', { get: () => geometry.height, configurable: true });
+  Object.defineProperty(el, 'clientHeight', { get: () => geometry.viewport, configurable: true });
+  Object.defineProperty(el, 'scrollTop', {
+    get: () => geometry.top,
+    set: (value: number) => applyTop(el, value),
+    configurable: true,
+  });
+  Object.defineProperty(el, 'scrollTo', {
+    value: (options: { top: number; behavior?: ScrollBehavior }) => {
+      scrolled.push(options);
+      if (options.behavior !== 'smooth') applyTop(el, options.top);
+    },
+    configurable: true,
+  });
+}
+
+/** ResizeObserver the tests drive by hand — the hook rebuilds one per content
+ *  node, so the last instance of the current mount is the live one. */
+class StubResizeObserver {
+  static instances: StubResizeObserver[] = [];
+  static latest(): StubResizeObserver { return StubResizeObserver.instances[StubResizeObserver.instances.length - 1]; }
+  constructor(private readonly callback: () => void) {
+    StubResizeObserver.instances.push(this);
+  }
+  observe() {}
+  unobserve() {}
+  disconnect() {}
+  fire() { this.callback(); }
+}
+
+interface ProbeProps {
+  sessionId: string;
+  messages: ChatMessageData[];
+  /** Holder owned by ONE test: a stale tree can only write its own hook result. */
+  holder: { current: ChatTimelineScrollResult | null };
+}
+
+function Probe(props: ProbeProps) {
+  const scroll = useChatTimelineScroll({});
+  useTimelineAutoScroll({
+    sessionId: props.sessionId,
+    messages: props.messages,
+    scrollRef: scroll.scrollRef,
+    jumpToBottom: scroll.jumpToBottom,
+    enabled: true,
+  });
+  props.holder.current = scroll;
+  return h('div', { ref: scroll.scrollRef, onScroll: scroll.handleScroll },
+    h('div', { ref: scroll.contentRef }));
+}
+
+interface ProbeHandle {
+  holder: { current: ChatTimelineScrollResult | null };
+  node: HTMLDivElement;
+  el: HTMLDivElement;
+}
+
+const message = (id: string) => ({ id, role: 'user', content: id } as unknown as ChatMessageData);
+
+/** Fresh mount, own container: `follow`, the jump counter and the observers are
+ *  per-hook state, so sharing them across tests would hide the behaviour. */
+async function mountProbe(sessionId: string, messages: ChatMessageData[]): Promise<ProbeHandle> {
+  const holder: ProbeHandle['holder'] = { current: null };
+  const node = document.createElement('div');
+  document.body.appendChild(node);
+  await act(async () => { render(h(Probe, { sessionId, messages, holder }), node); });
+  const el = holder.current!.scrollRef.current!;
+  installScroller(el);
+  return { holder, node, el };
+}
+
+/** Re-render with new props: a session switch, then that session's history. */
+async function updateProbe(probe: ProbeHandle, sessionId: string, messages: ChatMessageData[]) {
+  await act(async () => {
+    render(h(Probe, { sessionId, messages, holder: probe.holder }), probe.node);
+  });
+}
+
+async function unmountProbe(probe: ProbeHandle) {
+  await act(async () => { render(null, probe.node); });
+  probe.node.remove();
+}
+
+beforeAll(async () => {
+  win = new Window({ url: 'http://localhost' });
+  for (const key of ['window', 'document', 'navigator', 'Node', 'Element', 'HTMLElement', 'Event'] as const) {
+    (globalThis as Record<string, unknown>)[key] = (win as unknown as Record<string, unknown>)[key];
+  }
+  (globalThis as Record<string, unknown>).ResizeObserver = StubResizeObserver;
+  // Static imports cannot work here: Preact binds its environment at module
+  // evaluation time, so the modules below must load after those DOM globals.
+  ({ useChatTimelineScroll } = await import('@/client/hooks/chat/timeline/scroll'));
+  ({ useTimelineAutoScroll } = await import('@/client/hooks/chat/timeline/auto-scroll'));
+  ({ h, render } = await import('preact'));
+  ({ act } = await import('preact/test-utils'));
+});
+
+afterAll(() => {
+  for (const key of ['window', 'document', 'navigator', 'Node', 'Element', 'HTMLElement', 'Event', 'ResizeObserver']) {
+    delete (globalThis as Record<string, unknown>)[key];
+  }
+});
+
+describe('timeline scroll', () => {
+  test('opening a session jumps to the tail even after the user scrolled up', async () => {
+    scrolled.length = 0;
+    geometry.top = 0;
+    geometry.height = 5000;
+    const probe = await mountProbe('a', [message('a1')]);
+    const scroll = () => probe.holder.current!;
+
+    await updateProbe(probe, 'a', [message('a1'), message('a2')]);
+    expect(probe.el.scrollTop).toBe(geometry.height - geometry.viewport);
+
+    // The user reads back — follow disengages, and that state outlives the
+    // session it was set in.
+    probe.el.scrollTop = 100;
+    expect(scroll().followRef.current).toBe(false);
+
+    // Session switch: the container paints empty first (the skeleton), the
+    // committed history lands a commit later.
+    await updateProbe(probe, 'b', []);
+    scrolled.length = 0;
+    await updateProbe(probe, 'b', [message('b1')]);
+
+    expect(scroll().followRef.current).toBe(true);
+    expect(scrolled.length).toBe(1);
+    expect(scrolled[0].behavior).toBe('instant');
+    expect(scrolled[0].top).toBe(geometry.height);
+    expect(probe.el.scrollTop).toBe(geometry.height - geometry.viewport);
+    await unmountProbe(probe);
+  });
+
+  test('a stream chunk may not move an unpinned viewport, a jump may', async () => {
+    scrolled.length = 0;
+    geometry.top = 0;
+    geometry.height = 5000;
+    const probe = await mountProbe('a', [message('a1')]);
+    const scroll = () => probe.holder.current!;
+
+    await act(async () => { scroll().jumpToBottom('instant'); });
+    expect(scroll().followRef.current).toBe(true);
+    expect(probe.el.scrollTop).toBe(geometry.height - geometry.viewport);
+    expect(scroll().jumpCountRef.current).toBe(1);
+    expect(scroll().jumpActiveRef.current).toBe(true);
+
+    // The user reads back. A stream chunk must not yank the viewport down...
+    probe.el.scrollTop = 100;
+    expect(scroll().followRef.current).toBe(false);
+    scrolled.length = 0;
+    await act(async () => { scroll().scrollToBottom('smooth'); });
+    expect(scrolled.length).toBe(0);
+
+    // ...while the explicit jump bypasses the gate and re-engages it.
+    await act(async () => { scroll().jumpToBottom('instant'); });
+    expect(scrolled.length).toBe(1);
+    expect(scroll().followRef.current).toBe(true);
+    expect(probe.el.scrollTop).toBe(geometry.height - geometry.viewport);
+    expect(scroll().jumpCountRef.current).toBe(2);
+    await unmountProbe(probe);
+  });
+
+  test('the jump guard releases so history paging is not blocked for good', async () => {
+    scrolled.length = 0;
+    geometry.top = 0;
+    geometry.height = 5000;
+    const probe = await mountProbe('a', [message('a1')]);
+    const scroll = () => probe.holder.current!;
+
+    fakeTimers.useFakeTimers();
+    await act(async () => { scroll().jumpToBottom('instant'); });
+    expect(scroll().jumpActiveRef.current).toBe(true);
+
+    await act(async () => { fakeTimers.advanceTimersByTime(1000); });
+    expect(scroll().jumpActiveRef.current).toBe(false);
+    fakeTimers.useRealTimers();
+    await unmountProbe(probe);
+  });
+
+  test('content growing while pinned re-pins the tail; while reading it does not', async () => {
+    scrolled.length = 0;
+    geometry.top = 0;
+    geometry.height = 5000;
+    const probe = await mountProbe('a', [message('a1')]);
+    const scroll = () => probe.holder.current!;
+
+    await updateProbe(probe, 'a', [message('a1')]);
+    expect(probe.el.scrollTop).toBe(geometry.height - geometry.viewport);
+
+    // A prepended window / a late layout: the tail moved down by 800px.
+    geometry.height += 800;
+    const observer = StubResizeObserver.latest();
+    scrolled.length = 0;
+    await act(async () => { observer.fire(); });
+    expect(scrolled.length).toBe(1);
+    expect(scrolled[0].behavior).toBe('instant');
+    expect(probe.el.scrollTop).toBe(geometry.height - geometry.viewport);
+
+    // Reading back: the same growth must leave the viewport alone.
+    probe.el.scrollTop = 400;
+    scrolled.length = 0;
+    geometry.height += 800;
+    await act(async () => { StubResizeObserver.latest().fire(); });
+    expect(scrolled.length).toBe(0);
+    expect(probe.el.scrollTop).toBe(400);
+    expect(scroll().followRef.current).toBe(false);
+    await unmountProbe(probe);
+  });
+});

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

@@ -19,6 +19,12 @@
  * the tail disengages it (the scroll fight is gone — they can read while the
  * AI generates); scrolling back near the tail, or clicking the scroll-bottom
  * button, re-engages it. Programmatic jumps (`scrollTo`) never flip the mode.
+ *
+ * `jumpToBottom` is the unconditional bypass (`follow` is re-engaged, geometry
+ * is re-baselined, and the paging trigger stands down for a moment) — the
+ * button's jump, the open-session jump, and the send jump all go through it.
+ * `follow` lives across session switches, so an open jump that honoured it was
+ * simply refused for a session opened after the user had scrolled up.
  */
 
 import type { RefObject } from 'preact/compat';
@@ -27,6 +33,13 @@ import { useCallback, useEffect, useRef, useState } from 'preact/hooks';
 /** Distance from the tail, in pixels, that still counts as "at the bottom". */
 const FOLLOW_BOTTOM_THRESHOLD_PX = 100;
 
+/** How long a bottom jump counts as settling. The scroll handler reads "the
+ *  viewport is at the top, fetch older history" from geometry, and a jump that
+ *  STARTS at the top (the button, on a session scrolled back to its head)
+ *  passes through those first pixels — so the paging trigger stands down for
+ *  the jump's duration instead of paging a window the jump must then outrun. */
+const JUMP_SETTLE_MS = 1000;
+
 export interface ChatTimelineScrollOptions {
   /** Called when the viewport reaches the top (history paging trigger).
    *  Ref-indirect; the hook never depends on the callback's identity. */
@@ -41,15 +54,29 @@ export interface ChatTimelineScrollResult {
   isScrolling: boolean;
   /** Streaming auto-scroll gates on this: pinned to the tail = true. */
   followRef: RefObject<boolean>;
+  /** Bottom jumps issued so far. A paging request stamps its viewport anchor
+   *  with this and drops the anchor once it has moved on — otherwise a window
+   *  that lands AFTER the user asked for the tail writes `scrollTop` straight
+   *  over the jump (reproduced: the jump stopped ~26k px short of the tail and
+   *  only the next click reached it, once no window was left to page in). */
+  jumpCountRef: RefObject<number>;
+  /** True while a bottom jump is settling ({@link JUMP_SETTLE_MS}); history
+   *  paging stands down meanwhile. */
+  jumpActiveRef: RefObject<boolean>;
   handleScroll: () => void;
   scrollToBottom: (behavior?: ScrollBehavior) => void;
-  /** Jump to the tail and re-engage follow mode (scroll-bottom button). */
+  /** Jump to the tail and re-engage follow mode (scroll-bottom button, the
+   *  session-open jump, the post-send jump). */
   jumpToBottom: (behavior?: ScrollBehavior) => void;
 }
 
 /** Distance from the top that counts as "reached the history boundary". */
 const SCROLL_TOP_TRIGGER_PX = 40;
 
+/** Pending timeout handle. Named here rather than re-derived per ref because
+ *  the DOM and Bun/Node typings disagree on what `setTimeout` returns. */
+type TimeoutHandle = ReturnType<typeof setTimeout>;
+
 export function useChatTimelineScroll(options: ChatTimelineScrollOptions = {}): ChatTimelineScrollResult {
   const onScrollTopRef = useRef<(() => void) | undefined>(options.onScrollTop);
   onScrollTopRef.current = options.onScrollTop ?? onScrollTopRef.current;
@@ -57,17 +84,33 @@ export function useChatTimelineScroll(options: ChatTimelineScrollOptions = {}):
   const [contentNode, setContentNode] = useState<HTMLDivElement | null>(null);
   const [showScrollBottom, setShowScrollBottom] = useState(false);
   const [isScrolling, setIsScrolling] = useState(false);
-  const scrollTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const scrollTimerRef = useRef<TimeoutHandle>();
   // True while the viewport is (or should stay) pinned to the tail. A ref, not
   // state: scroll chunks read it every frame and a flip must not re-render.
   const followRef = useRef(true);
   // Previous scrollTop, for upward-scroll detection in handleScroll.
   const lastScrollTopRef = useRef(0);
+  // Bottom-jump bookkeeping; see ChatTimelineScrollResult for each ref.
+  const jumpCountRef = useRef(0);
+  const jumpActiveRef = useRef(false);
+  const jumpTimerRef = useRef<TimeoutHandle>();
 
   const contentRef = useCallback((node: HTMLDivElement | null) => {
     setContentNode(node);
   }, []);
 
+  /** Move the viewport to the tail unconditionally, then re-baseline the
+   *  upward-scroll detector. Both matter: `scrollTo` applies the new position
+   *  for 'instant', and the previous session's (larger) scrollTop would
+   *  otherwise read as the user scrolling UP on the very event this jump
+   *  produces — disengaging follow and cancelling a jump in flight. */
+  const pinToBottom = useCallback((behavior: ScrollBehavior) => {
+    const el = scrollRef.current;
+    if (!el) return;
+    el.scrollTo({ top: el.scrollHeight, behavior });
+    lastScrollTopRef.current = el.scrollTop;
+  }, []);
+
   const syncFollowBottom = useCallback(() => {
     const el = scrollRef.current;
     if (!el) return;
@@ -83,7 +126,12 @@ export function useChatTimelineScroll(options: ChatTimelineScrollOptions = {}):
       // increasing scrollTop, so a geometry check alone would flip the flag
       // mid-animation as content outgrows the animation. Re-engage whenever
       // the viewport is back near the tail, whichever way it got there.
-      if (el.scrollTop < lastScrollTopRef.current - 1) followRef.current = false;
+      if (el.scrollTop < lastScrollTopRef.current - 1) {
+        followRef.current = false;
+        // The user took the viewport back: a jump still settling must not keep
+        // re-pinning the tail under them.
+        jumpActiveRef.current = false;
+      }
       if (el.scrollHeight - el.scrollTop - el.clientHeight < FOLLOW_BOTTOM_THRESHOLD_PX) followRef.current = true;
       lastScrollTopRef.current = el.scrollTop;
       // History paging: the viewport hit the top — ask for the older window.
@@ -92,43 +140,68 @@ export function useChatTimelineScroll(options: ChatTimelineScrollOptions = {}):
     }
     syncFollowBottom();
     setIsScrolling(true);
-    if (scrollTimerRef.current) clearTimeout(scrollTimerRef.current);
+    clearTimeout(scrollTimerRef.current);
     scrollTimerRef.current = setTimeout(() => setIsScrolling(false), 600);
   }, [syncFollowBottom]);
 
   const scrollToBottom = useCallback((behavior: ScrollBehavior = 'smooth') => {
-    const el = scrollRef.current;
-    if (!el) return;
     // Follow-gated: a stream chunk in read mode (user scrolled away) must not
     // yank the viewport down. jumpToBottom is the explicit bypass.
     if (!followRef.current) return;
-    el.scrollTo({ top: el.scrollHeight, behavior });
-  }, []);
+    pinToBottom(behavior);
+  }, [pinToBottom]);
 
   const jumpToBottom = useCallback((behavior: ScrollBehavior = 'smooth') => {
-    const el = scrollRef.current;
-    if (!el) return;
+    if (!scrollRef.current) return;
     followRef.current = true;
-    el.scrollTo({ top: el.scrollHeight, behavior });
-  }, []);
+    jumpActiveRef.current = true;
+    jumpCountRef.current += 1;
+    clearTimeout(jumpTimerRef.current);
+    jumpTimerRef.current = setTimeout(() => { jumpActiveRef.current = false; }, JUMP_SETTLE_MS);
+    pinToBottom(behavior);
+  }, [pinToBottom]);
 
-  // Re-sync whenever an observed box changes size. `contentNode` is a dep so the
-  // observer is rebuilt when the timeline mounts — a session picked from the
-  // workspace picker swaps the whole subtree in, and the callback ref fires
-  // before this effect, so the node is always available here.
+  // Geometry, not events: content that grows without the user scrolling
+  // (history prepending, an accordion expanding, an image decoding, a late
+  // Shiki/mermaid layout, the panel resizing) never fires `scroll`, so nothing
+  // else notices the tail moving away. While the viewport is pinned that growth
+  // is exactly when to re-pin it — a prepended window shifts the tail down by
+  // its own height, which strands a jump target measured a frame earlier (and
+  // a one-shot open jump by anything that lays out late). Unpinned (the user
+  // reading back) nothing is touched: the prepend anchor owns the position.
+  //
+  // `contentNode` is a dep so the observer is rebuilt when the timeline mounts
+  // — a session picked from the workspace picker swaps the whole subtree in,
+  // and the callback ref fires before this effect, so the node is always
+  // available here.
   useEffect(() => {
     syncFollowBottom();
     if (typeof ResizeObserver === 'undefined') return;
     const container = scrollRef.current;
-    const observer = new ResizeObserver(syncFollowBottom);
+    const observer = new ResizeObserver(() => {
+      if (followRef.current) pinToBottom('instant');
+      syncFollowBottom();
+    });
     if (container) observer.observe(container);
     if (contentNode) observer.observe(contentNode);
     return () => observer.disconnect();
-  }, [contentNode, syncFollowBottom]);
+  }, [contentNode, pinToBottom, syncFollowBottom]);
 
   useEffect(() => () => {
-    if (scrollTimerRef.current) clearTimeout(scrollTimerRef.current);
+    clearTimeout(scrollTimerRef.current);
+    clearTimeout(jumpTimerRef.current);
   }, []);
 
-  return { scrollRef, contentRef, showScrollBottom, isScrolling, followRef, handleScroll, scrollToBottom, jumpToBottom };
+  return {
+    scrollRef,
+    contentRef,
+    showScrollBottom,
+    isScrolling,
+    followRef,
+    jumpCountRef,
+    jumpActiveRef,
+    handleScroll,
+    scrollToBottom,
+    jumpToBottom,
+  };
 }

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

@@ -60,10 +60,14 @@ export interface UseSessionLoadDeps {
   /** Scroll container of the timeline: lets loadOlder preserve the viewport
    *  position when older rows are prepended above it. */
   scrollRef?: RefObject<HTMLDivElement>;
+  /** Scroll hook's bottom-jump guard and counter, forwarded to the pagination
+   *  hook: a jump to the tail outranks an in-flight older window. */
+  jumpActiveRef?: RefObject<boolean>;
+  jumpCountRef?: RefObject<number>;
 }
 
 export function useSessionLoad(deps: UseSessionLoadDeps) {
-  const { sessionId, setLocalMessages, setGenerating, isGeneratingRef, aiPlaceholderIdRef, localMessagesRef, optimisticUserIdRef, cancelStreamingCoalescer, metaRefreshedRef, scrollRef } = deps;
+  const { sessionId, setLocalMessages, setGenerating, isGeneratingRef, aiPlaceholderIdRef, localMessagesRef, optimisticUserIdRef, cancelStreamingCoalescer, metaRefreshedRef, scrollRef, jumpActiveRef, jumpCountRef } = deps;
 
   const [sessionData, setSessionData] = useState<SessionDataShape | null>(null);
   const [sessionLoading, setSessionLoading] = useState(false);
@@ -99,6 +103,8 @@ export function useSessionLoad(deps: UseSessionLoadDeps) {
     sessionIdRef,
     setLocalMessages,
     scrollRef,
+    jumpActiveRef,
+    jumpCountRef,
   });
 
   /** Re-fetch the session's title/metadata after the omp JSONL has been