@opengeni/react 3.1.0 → 3.1.2

package/src/hooks/use-session-events.ts

@@ -1,11 +1,18 @@
-import type { SessionEvent, SessionStatus, StreamConnectionState } from "@opengeni/sdk";
-import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import {
+  sessionEventStreamCoveredThrough,
+  type SessionEvent,
+  type SessionStatus,
+  type StreamConnectionState,
+} from "@opengeni/sdk";
+import { startTransition, useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { useEmbeddedSession, type EmbeddedSessionClientOverride } from "../session-context";
 import { createOlderHistoryLoadReceipt, type OlderHistoryLoadReceipt } from "../older-history";
 import { buildTimeline, groupTimeline, sessionStatusFromEvents } from "../timeline/projection";
 import type { TimelineItem } from "../timeline/types";
 import type { EmbeddedSessionClientLike } from "../client";
+import { normalizeError } from "../lib/error-message";
 import { usePageLiveActivity } from "./internal";
+import type { LatestQuestionOptions } from "./latest-question";
 
 export type SessionEventsConnectionState = StreamConnectionState | "idle" | "ended" | "error";
 
@@ -21,10 +28,12 @@ export type UseSessionEventsOptions = EmbeddedSessionClientOverride & {
 export type UseSessionEventsResult = {
   /** Replayed + live events, ordered by sequence, no gaps, no duplicates. */
   events: SessionEvent[];
-  /** Projected, renderable timeline (memoized over `events`). */
+  /** Renderable timeline, including the bounded navigation witness for a distant queued prompt. */
   timeline: TimelineItem[];
   /** Latest session status observed in the event log, if any. */
   sessionStatus: SessionStatus | null;
+  /** Sequence of the retained status projection, including events evicted from the window. */
+  sessionStatusSequence?: number;
   connectionState: SessionEventsConnectionState;
   /** Highest sequence seen so far (0 before the first event). */
   lastSequence: number;
@@ -34,6 +43,10 @@ export type UseSessionEventsResult = {
   windowTruncated: boolean;
   /** True until the initial tail window has been applied (windowed mode). */
   initialLoading: boolean;
+  /** A history window (including an empty tail) succeeded for this session/replay
+   * identity. Stays true through later stream errors and navigation/reloads.
+   * Full replay has no snapshot-completion watermark and does not set this by itself. */
+  initialHistoryReady: boolean;
   /** Whether older durable events are available before the current window. */
   hasOlder: boolean;
   /** True while an older window is being fetched. */
@@ -66,13 +79,20 @@ export type UseSessionEventsResult = {
    * "Jump to latest" when the tip is not in memory (history view).
    */
   jumpToLatest: () => Promise<void>;
+  /** Resolve the newest eligible durable human question. Pending prompts use the
+   * optional queue destination and return null; started prompts load their actual
+   * turn context (pass `timeline` to MessageTimeline as `items`). */
+  jumpToLatestQuestion: (options?: LatestQuestionOptions) => Promise<number | null>;
+  /** Replace history with a bounded window containing this exact durable event. */
+  jumpToSequence: (sequence: number, options?: { signal?: AbortSignal }) => Promise<boolean>;
+  loadingTarget: boolean;
   error: Error | null;
 };
 
-const INITIAL_TAIL_PAGE_SIZE = 1000;
-const OLDER_PAGE_SIZE = 5000;
-const NEWER_PAGE_SIZE = 5000;
-const OLDEST_PAGE_SIZE = 1000;
+// Keep every browser history read inside one database batch, including the
+// server's one-row continuation lookahead. A large total session must never
+// turn one lazy page into dozens of sequential database round trips.
+const SESSION_HISTORY_PAGE_SIZE = 1000;
 const INITIAL_FETCH_CAP = 1;
 const OLDER_GROUP_TARGET = 32;
 const OLDER_FETCH_CAP = 2;
@@ -80,37 +100,26 @@ const NEWER_GROUP_TARGET = 32;
 const NEWER_FETCH_CAP = 2;
 const OLDEST_GROUP_TARGET = 32;
 const OLDEST_FETCH_CAP = 2;
-const BOUNDARY_PAGE_CAP = 4;
+// A tail page may land inside one unusually dense turn. Permit exactly one
+// additional bounded page to find its user/session boundary without turning a
+// fresh open into an unbounded history walk.
+const BOUNDARY_PAGE_CAP = 1;
+// Foreground reconciliation is intentionally semantic, not merely time-based:
+// tiny raw gaps can stay on SSE; medium raw gaps get one compact probe so a
+// token-heavy single answer is not mistaken for hundreds of visible messages;
+// only a large/complex missed window reloads the latest tail.
+const FOREGROUND_DIRECT_REPLAY_MAX_SEQUENCES = 16;
+const FOREGROUND_COMPACT_PROBE_MAX_SEQUENCES = SESSION_HISTORY_PAGE_SIZE;
+const FOREGROUND_COMPACT_CATCHUP_MAX_EVENTS = 128;
+const FOREGROUND_COMPACT_CATCHUP_MAX_GROUPS = 16;
+const FOREGROUND_COMPACT_CATCHUP_MAX_BYTES = 512 * 1024;
 const EMPTY_EVENTS: SessionEvent[] = [];
 const encoder = new TextEncoder();
-const decoder = new TextDecoder();
-
-const BROWSER_EVENT_TYPE_MAX_BYTES = 256;
-const BROWSER_EVENT_ID_MAX_BYTES = 256;
-const BROWSER_EVENT_CLIENT_ID_MAX_BYTES = 4 * 1024;
-const BROWSER_EVENT_DUPLICATE_REASON_MAX_BYTES = 4 * 1024;
-const BROWSER_EVENT_PAYLOAD_PREVIEW_MAX_BYTES = 48 * 1024;
-const BROWSER_EVENT_PAYLOAD_IDENTITY_FIELDS = [
-  "id",
-  "callId",
-  "call_id",
-  "name",
-  "toolName",
-  "status",
-  "code",
-  "isError",
-  "stream",
-  "commandId",
-  "sequence",
-  "coalescedUntil",
-  "coalescedCount",
-  "firstSequence",
-  "lastSequence",
-] as const;
-
-export const SESSION_EVENT_BROWSER_MAX_BYTES = 8 * 1024 * 1024;
-export const SESSION_EVENT_BROWSER_MAX_COUNT = 10_000;
-export const SESSION_EVENT_BROWSER_SINGLE_EVENT_MAX_BYTES = 96 * 1024;
+// Durable history remains on the server and is available through bounded
+// navigation. Keep the live browser working set small across multiple tabs;
+// serialized payloads also expand into objects and timeline projections.
+export const SESSION_EVENT_BROWSER_MAX_BYTES = 16 * 1024 * 1024;
+export const SESSION_EVENT_BROWSER_MAX_COUNT = 20_000;
 export const SESSION_EVENT_BROWSER_PENDING_MAX_BYTES = 1024 * 1024;
 export const SESSION_EVENT_BROWSER_PENDING_MAX_COUNT = 256;
 
@@ -143,20 +152,47 @@ export function useSessionEvents(
   const replay = options.replay ?? "windowed";
   const fullReplay = replay === "full" || after !== 0;
   const streamKey = `${workspaceId}\u0000${sessionId ?? ""}\u0000${after}\u0000${fullReplay ? "full" : "windowed"}`;
+  // Bind callbacks to this read lifetime, including a return to a previous
+  // identity. Publish during render so old callbacks are fenced before passive
+  // cleanup can advance the navigation generation.
+  const navigationIdentityRef = useRef({ client, streamKey, enabled });
+  if (
+    navigationIdentityRef.current.client !== client ||
+    navigationIdentityRef.current.streamKey !== streamKey ||
+    navigationIdentityRef.current.enabled !== enabled
+  ) {
+    navigationIdentityRef.current = { client, streamKey, enabled };
+  }
+  const navigationIdentity = navigationIdentityRef.current;
+  const ownsNavigation = useCallback(
+    () => navigationIdentityRef.current === navigationIdentity,
+    [navigationIdentity],
+  );
 
   const [eventWindow, setEventWindow] = useState<BrowserSessionEventWindow>(EMPTY_EVENT_WINDOW);
+  // One navigation witness, not a second history cache. Raw events stay contiguous.
+  const [questionEvidence, setQuestionEvidence] = useState<{
+    client: EmbeddedSessionClientLike;
+    streamKey: string;
+    anchor: number;
+    events: SessionEvent[];
+  } | null>(null);
   const [connectionState, setConnectionState] = useState<SessionEventsConnectionState>("idle");
   const [error, setError] = useState<Error | null>(null);
+  const [newerError, setNewerError] = useState<Error | null>(null);
   const [hasOlder, setHasOlder] = useState(false);
   const [hasNewer, setHasNewer] = useState(false);
   const [sessionStatusProjection, setSessionStatusProjection] = useState<SessionStatus | null>(
     null,
   );
   const [initialLoading, setInitialLoading] = useState(true);
+  const [initialHistoryReady, setInitialHistoryReady] = useState(false);
   const [loadingOlder, setLoadingOlder] = useState(false);
   const [loadingNewer, setLoadingNewer] = useState(false);
   const [loadingOldest, setLoadingOldest] = useState(false);
   const [loadingLatest, setLoadingLatest] = useState(false);
+  const [loadingTarget, setLoadingTarget] = useState(false);
+  const loadingTargetRef = useRef(false);
   const [streamEpoch, setStreamEpoch] = useState(0);
   // "history" = reading a non-tip window; live SSE must not fill the gap.
   const [viewMode, setViewMode] = useState<"live" | "history">("live");
@@ -172,9 +208,11 @@ export function useSessionEvents(
   const loadingLatestRef = useRef(false);
   const viewModeRef = useRef<"live" | "history">("live");
   const initialWindowLoadedRef = useRef(false);
+  const reconcileAfterPageResumeRef = useRef(false);
   const streamAbortRef = useRef<AbortController | null>(null);
   const streamKeyRef = useRef<string | null>(null);
   const generationRef = useRef(0);
+  const navigationGenerationRef = useRef(0);
   const eventWindowRef = useRef<BrowserSessionEventWindow>(EMPTY_EVENT_WINDOW);
   const sessionStatusRef = useRef<{
     sequence: number;
@@ -187,6 +225,25 @@ export function useSessionEvents(
   // new stream identity cannot expose the previous session's event log.
   const [stateStreamKey, setStateStreamKey] = useState(streamKey);
 
+  // Navigation belongs to the session/client lifetime, not the transport: an
+  // SSE reconnect must never cancel an in-flight history page.
+  useEffect(() => {
+    navigationGenerationRef.current += 1;
+    setNewerError(null);
+    loadingOlderRef.current = false;
+    loadingNewerRef.current = false;
+    loadingOldestRef.current = false;
+    loadingTargetRef.current = false;
+    setQuestionEvidence(null);
+    setLoadingTarget(false);
+    setLoadingOlder(false);
+    setLoadingNewer(false);
+    setLoadingOldest(false);
+    return () => {
+      navigationGenerationRef.current += 1;
+    };
+  }, [client, workspaceId, sessionId, after, enabled, fullReplay]);
+
   useEffect(() => {
     // Reset the accumulated log only when the stream identity changes —
     // pausing via `enabled: false` keeps the timeline visible.
@@ -205,6 +262,7 @@ export function useSessionEvents(
       setLoadingOldest(false);
       setLoadingLatest(false);
       setInitialLoading(true);
+      setInitialHistoryReady(false);
       lastSequenceRef.current = after;
       streamResumeSequenceRef.current = after;
       oldestSequenceRef.current = null;
@@ -218,29 +276,50 @@ export function useSessionEvents(
       viewModeRef.current = "live";
       setViewMode("live");
       initialWindowLoadedRef.current = false;
+      reconcileAfterPageResumeRef.current = false;
     }
     // AbortController is advisory: custom SDK clients and async iterators may
     // ignore it and resolve/yield after cleanup. Fence every effect instance so
     // only the newest dependency generation can mutate refs or React state.
     const generation = generationRef.current + 1;
     generationRef.current = generation;
-    if (loadingOlderRef.current) {
-      loadingOlderRef.current = false;
-      setLoadingOlder(false);
-    }
     if (!sessionId || !streamEnabled) {
+      // A page that stayed hidden beyond the live-activity grace deliberately
+      // closed its SSE connection. Replaying from the old cursor on return can
+      // drip a large background backlog through React in many fast batches and
+      // leave the pinned camera catching up long after the user is foregrounded.
+      // Remember that suspension so the next live effect replaces the browser
+      // window with one compact durable tail instead.
+      if (
+        sessionId &&
+        enabled &&
+        !pageLive &&
+        !fullReplay &&
+        viewModeRef.current === "live" &&
+        initialWindowLoadedRef.current
+      ) {
+        reconcileAfterPageResumeRef.current = true;
+      }
       setConnectionState("idle");
       return;
     }
     // History view owns a non-tip window; do not open SSE (it would replay the
     // entire gap into the browser). jumpToLatest / catching loadNewer resume live.
     if (viewMode === "history") {
+      reconcileAfterPageResumeRef.current = false;
       setConnectionState("idle");
       setInitialLoading(false);
       return;
     }
+    const reconcileForegroundResume = reconcileAfterPageResumeRef.current && !fullReplay;
+    reconcileAfterPageResumeRef.current = false;
     const controller = new AbortController();
-    const isCurrent = () => generationRef.current === generation && !controller.signal.aborted;
+    const isCurrent = () =>
+      generationRef.current === generation &&
+      !controller.signal.aborted &&
+      navigationIdentityRef.current.client === client &&
+      navigationIdentityRef.current.streamKey === streamKey &&
+      navigationIdentityRef.current.enabled === enabled;
     streamAbortRef.current = controller;
     // Batch yielded events into one React update per flush window so a long
     // replay (thousands of events) does not render per event. Project every
@@ -283,9 +362,12 @@ export function useSessionEvents(
           batchResumeSequence,
         );
       }
-      observeSessionStatus(batch, sessionStatusRef, setSessionStatusProjection);
+      const status = observeSessionStatus(batch, sessionStatusRef);
+      if (status !== undefined) {
+        setSessionStatusProjection(status);
+      }
       const current = eventWindowRef.current;
-      const next = boundBrowserSessionEventWindow([...current.events, ...batch]);
+      const next = appendBrowserSessionEventWindow(current, batch);
       const retained = {
         ...next,
         truncated: current.truncated || next.truncated,
@@ -293,7 +375,7 @@ export function useSessionEvents(
       eventWindowRef.current = retained;
       setEventWindow(retained);
       oldestSequenceRef.current = retained.events[0]?.sequence ?? null;
-      newestSequenceRef.current = retained.events.at(-1)?.sequence ?? null;
+      newestSequenceRef.current = maxResumeSequenceOrNull(retained.events);
       if (retained.truncated) {
         hasOlderRef.current = true;
         setHasOlder(true);
@@ -306,6 +388,56 @@ export function useSessionEvents(
 
     void (async () => {
       try {
+        if (reconcileForegroundResume) {
+          setConnectionState("connecting");
+          const cursor = streamResumeSequenceRef.current;
+          let plan: ForegroundCatchupPlan = { kind: "resume" };
+          try {
+            plan = await planForegroundCatchup(client, workspaceId, sessionId, cursor, {
+              signal: controller.signal,
+            });
+          } catch {
+            if (controller.signal.aborted) return;
+            // This read is an optimization gate, not a new availability
+            // dependency. If it fails, preserve the SDK's exact cursor replay
+            // rather than blanking a usable timeline or failing the stream.
+            plan = { kind: "resume" };
+          }
+          if (!isCurrent()) return;
+          if (plan.kind === "append") {
+            const current = eventWindowRef.current;
+            assertAppendOrder(current.events, plan.events);
+            const status = observeSessionStatus(plan.events, sessionStatusRef);
+            const next = appendBrowserSessionEventWindow(current, plan.events);
+            const retained = {
+              ...next,
+              truncated: current.truncated || next.truncated,
+            };
+            eventWindowRef.current = retained;
+            oldestSequenceRef.current = retained.events[0]?.sequence ?? null;
+            newestSequenceRef.current = maxResumeSequenceOrNull(retained.events);
+            lastSequenceRef.current = Math.max(lastSequenceRef.current, plan.resumeSequence);
+            streamResumeSequenceRef.current = Math.max(
+              streamResumeSequenceRef.current,
+              plan.resumeSequence,
+            );
+            if (status !== undefined) {
+              setSessionStatusProjection(status);
+            }
+            setEventWindow(retained);
+            if (retained.truncated) {
+              hasOlderRef.current = true;
+              setHasOlder(true);
+            }
+          } else if (plan.kind === "reload") {
+            // A large/complex missed window would make the foreground timeline
+            // and pinned camera chase many rapid commits. Keep the last known
+            // complete window visible until the bounded latest replacement is
+            // ready, then install that replacement atomically below.
+            initialWindowLoadedRef.current = false;
+            setError(null);
+          }
+        }
         if (!fullReplay && !initialWindowLoadedRef.current) {
           setConnectionState("connecting");
           // First paint is ONE compact fetch — the newest window, revealed at
@@ -313,25 +445,42 @@ export function useSessionEvents(
           // reader actually scrolls up (the sentinel drives loadOlder).
           const window = await loadEventWindow(client, workspaceId, sessionId, {
             before: Number.MAX_SAFE_INTEGER,
-            pageSize: INITIAL_TAIL_PAGE_SIZE,
+            pageSize: SESSION_HISTORY_PAGE_SIZE,
             targetGroups: Number.POSITIVE_INFINITY,
             maxFetches: INITIAL_FETCH_CAP,
+            boundaryPageCap: BOUNDARY_PAGE_CAP,
             signal: controller.signal,
           });
           if (!isCurrent()) {
             return;
           }
-          observeSessionStatus(window.events, sessionStatusRef, setSessionStatusProjection);
+          const status = observeSessionStatus(window.events, sessionStatusRef);
           const retained = boundBrowserSessionEventWindow(window.events);
+          // A replacement tail retires requests against the discarded window.
+          // Ordinary SSE reconnects preserve navigation, but splicing an old
+          // page into this new tail could leave an inaccessible history gap.
+          navigationGenerationRef.current += 1;
+          loadingOlderRef.current = false;
+          loadingNewerRef.current = false;
+          loadingOldestRef.current = false;
+          setLoadingOlder(false);
+          setLoadingNewer(false);
+          setLoadingOldest(false);
           eventWindowRef.current = retained;
-          setEventWindow(retained);
           oldestSequenceRef.current = retained.events[0]?.sequence ?? window.oldestSequence;
-          newestSequenceRef.current = retained.events.at(-1)?.sequence ?? window.newestSequence;
+          newestSequenceRef.current =
+            maxResumeSequenceOrNull(retained.events) ?? window.newestSequence;
           hasOlderRef.current = window.hasOlder || retained.truncated;
           hasNewerRef.current = false;
           lastSequenceRef.current = window.newestSequence;
           streamResumeSequenceRef.current = window.newestSequence;
           initialWindowLoadedRef.current = true;
+          setInitialHistoryReady(true);
+          setError(null);
+          if (status !== undefined) {
+            setSessionStatusProjection(status);
+          }
+          setEventWindow(retained);
           setHasOlder(window.hasOlder || retained.truncated);
           setHasNewer(false);
           setInitialLoading(false);
@@ -350,7 +499,7 @@ export function useSessionEvents(
               .then(() => reconcileSession(sessionId))
               .catch((cause) => {
                 if (isCurrent()) {
-                  setError(cause instanceof Error ? cause : new Error(String(cause)));
+                  setError(normalizeError(cause));
                 }
               });
           },
@@ -362,7 +511,7 @@ export function useSessionEvents(
         });
         for await (const event of stream) {
           if (!isCurrent()) break;
-          const boundedEvent = boundBrowserLegacyEvent(event);
+          const boundedEvent = event;
           const boundedEventBytes = browserJsonBytes(boundedEvent);
           const separatorBytes = pending.length === 0 ? 0 : 1;
           if (
@@ -391,8 +540,12 @@ export function useSessionEvents(
       } catch (cause) {
         if (isCurrent()) {
           flush();
-          setError(cause instanceof Error ? cause : new Error(String(cause)));
+          setError(normalizeError(cause));
           setConnectionState("error");
+          // A failed first compact-tail request has no later success path in
+          // this effect instance. End the loading gate so hosts can render the
+          // retryable error instead of an infinite initial spinner.
+          setInitialLoading(false);
         }
       }
     })();
@@ -414,6 +567,8 @@ export function useSessionEvents(
     workspaceId,
     sessionId,
     after,
+    enabled,
+    pageLive,
     streamEnabled,
     fullReplay,
     streamKey,
@@ -423,6 +578,7 @@ export function useSessionEvents(
   ]);
 
   const navigationBusy = (): boolean =>
+    loadingTargetRef.current ||
     loadingOlderRef.current ||
     loadingNewerRef.current ||
     loadingOldestRef.current ||
@@ -430,8 +586,8 @@ export function useSessionEvents(
 
   const loadOlder = useCallback(
     (): OlderHistoryLoadReceipt =>
-      createOlderHistoryLoadReceipt(async (markCommitted) => {
-        if (!sessionId || navigationBusy() || !hasOlderRef.current) {
+      createOlderHistoryLoadReceipt(async (markCommitted, preserveTail, markTailPreserved) => {
+        if (!ownsNavigation() || !sessionId || navigationBusy() || !hasOlderRef.current) {
           return false;
         }
         const before = oldestSequenceRef.current;
@@ -441,17 +597,20 @@ export function useSessionEvents(
           setHasOlder(false);
           return false;
         }
-        const generation = generationRef.current;
+        const generation = navigationGenerationRef.current;
+        const isCurrent = () => ownsNavigation() && navigationGenerationRef.current === generation;
         loadingOlderRef.current = true;
         setLoadingOlder(true);
+        let published = false;
         try {
           const window = await loadEventWindow(client, workspaceId, sessionId, {
             before,
-            pageSize: OLDER_PAGE_SIZE,
+            pageSize: SESSION_HISTORY_PAGE_SIZE,
             targetGroups: OLDER_GROUP_TARGET,
             maxFetches: OLDER_FETCH_CAP,
+            isCurrent,
           });
-          if (generationRef.current !== generation) {
+          if (!isCurrent()) {
             return false;
           }
           if (window.events.length === 0) {
@@ -462,14 +621,16 @@ export function useSessionEvents(
           }
           const current = eventWindowRef.current;
           assertPrependOrder(current.events, window.events);
-          // Freeze the live iterator before replacing its in-memory window. Rows
-          // pending in the aborted iterator were never cursor-committed and will
-          // be replayed from the retained high-water mark below.
-          streamAbortRef.current?.abort();
-          observeSessionStatus(window.events, sessionStatusRef, setSessionStatusProjection);
           const next = boundBrowserSessionEventWindow([...window.events, ...current.events], {
             direction: "oldest",
           });
+          if (preserveTail && maxResumeSequence(next.events) < maxResumeSequence(current.events)) {
+            // Automatic viewport filling must not navigate away from the
+            // reader's retained tail. Explicit history navigation may do so.
+            markTailPreserved();
+            return false;
+          }
+          const status = observeSessionStatus(window.events, sessionStatusRef);
           const retained = {
             ...next,
             truncated: current.truncated || next.truncated,
@@ -478,54 +639,99 @@ export function useSessionEvents(
           if (retainedOldest === null || retainedOldest >= before) {
             throw new Error("@opengeni/react: loadOlder made no durable sequence progress");
           }
-          const retainedNewest = retained.events.at(-1)?.sequence ?? null;
+          const retainedNewest = maxResumeSequenceOrNull(retained.events);
+          const previousNewest = maxResumeSequenceOrNull(current.events);
+          const evictedLiveTail =
+            previousNewest !== null && retainedNewest !== null && retainedNewest < previousNewest;
+          if (evictedLiveTail && viewModeRef.current === "live") {
+            // The prepend leaves the live tip. Freeze the iterator before the
+            // window is replaced so a late flush cannot append live rows onto
+            // (and newest-bound away) the history the reader just requested.
+            streamAbortRef.current?.abort();
+          }
           eventWindowRef.current = retained;
           markCommitted();
-          setEventWindow(retained);
           oldestSequenceRef.current = retainedOldest;
           newestSequenceRef.current = retainedNewest;
-          streamResumeSequenceRef.current = maxResumeSequence(retained.events);
+          if (evictedLiveTail) {
+            streamResumeSequenceRef.current = maxResumeSequence(retained.events);
+          }
           // Oldest-directed eviction can discard newer in-memory rows. That fact
           // keeps windowTruncated true, but it does not imply older durable rows
           // exist; only the backward DB page can answer hasOlder truthfully.
           const olderStillAvailable = window.hasOlder;
           hasOlderRef.current = olderStillAvailable;
-          setHasOlder(olderStillAvailable);
-          if (viewModeRef.current === "history") {
+          let newer: boolean | null = null;
+          let enterHistory = false;
+          if (viewModeRef.current === "history" || evictedLiveTail) {
             const highWater = lastSequenceRef.current;
-            const newer =
-              retainedNewest !== null && (retainedNewest < highWater || retained.truncated);
+            newer = retainedNewest !== null && (retainedNewest < highWater || retained.truncated);
             hasNewerRef.current = newer;
-            setHasNewer(newer);
-          } else {
-            // Live mode keeps the historical contract: reconnect and replay the
-            // evicted tip through SSE so the window stays one contiguous suffix.
-            setStreamEpoch((epoch) => epoch + 1);
+            if (evictedLiveTail) {
+              // A full oldest-directed browser window cannot also retain the
+              // live suffix. Keep the newly loaded history and page forward;
+              // reconnecting SSE here immediately newest-bounds the window and
+              // evicts every row the reader just requested.
+              viewModeRef.current = "history";
+              enterHistory = true;
+            }
           }
+          // Otherwise the merge is still one contiguous live suffix and the open
+          // SSE iterator keeps appending to it: every flush reads
+          // eventWindowRef, so rows delivered during or after this fetch land
+          // once, in order, on the prepended window. Reopening the stream here
+          // would flash a connecting state and re-run session reconciliation on
+          // every scroll-up for no data benefit.
+          loadingOlderRef.current = false;
+          startTransition(() => {
+            if (status !== undefined) {
+              setSessionStatusProjection(status);
+            }
+            setEventWindow(retained);
+            setHasOlder(olderStillAvailable);
+            if (newer !== null) {
+              setHasNewer(newer);
+            }
+            if (enterHistory) {
+              setViewMode("history");
+            }
+            setLoadingOlder(false);
+          });
+          published = true;
           return olderStillAvailable;
+        } catch (reason) {
+          if (!isCurrent()) return false;
+          throw reason;
         } finally {
-          loadingOlderRef.current = false;
-          setLoadingOlder(false);
+          if (!published && isCurrent()) {
+            loadingOlderRef.current = false;
+            setLoadingOlder(false);
+          }
         }
       }),
-    [client, workspaceId, sessionId],
+    [client, workspaceId, sessionId, ownsNavigation],
   );
 
   const loadOldest = useCallback(async (): Promise<boolean> => {
-    if (!sessionId || navigationBusy() || !hasOlderRef.current) {
+    if (!ownsNavigation() || !sessionId || navigationBusy() || !hasOlderRef.current) {
       return false;
     }
-    const generation = generationRef.current;
+    // Explicit window replacement supersedes unresolved question destinations.
+    const generation = ++navigationGenerationRef.current;
+    const isCurrent = () => ownsNavigation() && navigationGenerationRef.current === generation;
+    setQuestionEvidence(null);
     loadingOldestRef.current = true;
     setLoadingOldest(true);
+    let published = false;
     try {
       const window = await loadForwardEventWindow(client, workspaceId, sessionId, {
         after: 0,
-        pageSize: OLDEST_PAGE_SIZE,
+        pageSize: SESSION_HISTORY_PAGE_SIZE,
         targetGroups: OLDEST_GROUP_TARGET,
         maxFetches: OLDEST_FETCH_CAP,
+        isCurrent,
       });
-      if (generationRef.current !== generation) {
+      if (!isCurrent()) {
         return false;
       }
       if (window.events.length === 0) {
@@ -534,17 +740,15 @@ export function useSessionEvents(
         return false;
       }
       streamAbortRef.current?.abort();
-      observeSessionStatus(window.events, sessionStatusRef, setSessionStatusProjection);
+      const status = observeSessionStatus(window.events, sessionStatusRef);
       // Keep the oldest prefix — never the middle or tip.
       const retained = boundBrowserSessionEventWindow(window.events, { direction: "oldest" });
       const retainedOldest = retained.events[0]?.sequence ?? null;
-      const retainedNewest = retained.events.at(-1)?.sequence ?? null;
+      const retainedNewest = maxResumeSequenceOrNull(retained.events);
       eventWindowRef.current = retained;
-      setEventWindow(retained);
       oldestSequenceRef.current = retainedOldest;
       newestSequenceRef.current = retainedNewest;
       hasOlderRef.current = false;
-      setHasOlder(false);
       const highWater = Math.max(lastSequenceRef.current, retainedNewest ?? 0);
       lastSequenceRef.current = highWater;
       const newer =
@@ -552,19 +756,37 @@ export function useSessionEvents(
         retained.truncated ||
         (retainedNewest !== null && retainedNewest < highWater);
       hasNewerRef.current = newer;
-      setHasNewer(newer);
       initialWindowLoadedRef.current = true;
+      setInitialHistoryReady(true);
+      setError(null);
       viewModeRef.current = "history";
-      setViewMode("history");
+      loadingOldestRef.current = false;
+      setNewerError(null);
+      startTransition(() => {
+        if (status !== undefined) {
+          setSessionStatusProjection(status);
+        }
+        setEventWindow(retained);
+        setHasOlder(false);
+        setHasNewer(newer);
+        setViewMode("history");
+        setLoadingOldest(false);
+      });
+      published = true;
       return newer;
+    } catch (reason) {
+      if (!isCurrent()) return false;
+      throw reason;
     } finally {
-      loadingOldestRef.current = false;
-      setLoadingOldest(false);
+      if (!published && isCurrent()) {
+        loadingOldestRef.current = false;
+        setLoadingOldest(false);
+      }
     }
-  }, [client, workspaceId, sessionId]);
+  }, [client, workspaceId, sessionId, ownsNavigation]);
 
   const loadNewer = useCallback(async (): Promise<boolean> => {
-    if (!sessionId || navigationBusy() || !hasNewerRef.current) {
+    if (!ownsNavigation() || !sessionId || navigationBusy() || !hasNewerRef.current) {
       return false;
     }
     const afterSequence = newestSequenceRef.current;
@@ -573,20 +795,24 @@ export function useSessionEvents(
       setHasNewer(false);
       return false;
     }
-    const generation = generationRef.current;
+    const generation = navigationGenerationRef.current;
+    const isCurrent = () => ownsNavigation() && navigationGenerationRef.current === generation;
     loadingNewerRef.current = true;
     setLoadingNewer(true);
+    let published = false;
     try {
       const window = await loadForwardEventWindow(client, workspaceId, sessionId, {
         after: afterSequence,
-        pageSize: NEWER_PAGE_SIZE,
+        pageSize: SESSION_HISTORY_PAGE_SIZE,
         targetGroups: NEWER_GROUP_TARGET,
         maxFetches: NEWER_FETCH_CAP,
+        isCurrent,
       });
-      if (generationRef.current !== generation) {
+      if (!isCurrent()) {
         return false;
       }
       if (window.events.length === 0) {
+        setNewerError(null);
         hasNewerRef.current = false;
         setHasNewer(false);
         // Caught up with durable history — resume the live tip stream.
@@ -598,23 +824,20 @@ export function useSessionEvents(
       }
       const current = eventWindowRef.current;
       assertAppendOrder(current.events, window.events);
-      observeSessionStatus(window.events, sessionStatusRef, setSessionStatusProjection);
+      const status = observeSessionStatus(window.events, sessionStatusRef);
       const previousOldest = current.events[0]?.sequence ?? null;
       // Moving forward through history: keep the newest suffix of the merge.
-      const next = boundBrowserSessionEventWindow([...current.events, ...window.events], {
-        direction: "newest",
-      });
+      const next = appendBrowserSessionEventWindow(current, window.events);
       const retained = {
         ...next,
         truncated: current.truncated || next.truncated || window.hasNewer,
       };
       const retainedOldest = retained.events[0]?.sequence ?? null;
-      const retainedNewest = retained.events.at(-1)?.sequence ?? null;
+      const retainedNewest = maxResumeSequenceOrNull(retained.events);
       if (retainedNewest === null || retainedNewest <= afterSequence) {
         throw new Error("@opengeni/react: loadNewer made no durable sequence progress");
       }
       eventWindowRef.current = retained;
-      setEventWindow(retained);
       oldestSequenceRef.current = retainedOldest;
       newestSequenceRef.current = retainedNewest;
       // Evicting the start while paging forward re-arms hasOlder.
@@ -627,69 +850,261 @@ export function useSessionEvents(
             retainedOldest > 1))
       ) {
         hasOlderRef.current = true;
-        setHasOlder(true);
       }
+      const rearmedOlder = hasOlderRef.current;
       const highWater = Math.max(lastSequenceRef.current, retainedNewest);
       lastSequenceRef.current = highWater;
       const newer = window.hasNewer || retainedNewest < highWater;
       hasNewerRef.current = newer;
-      setHasNewer(newer);
+      let resumeLive = false;
       if (!newer) {
         streamResumeSequenceRef.current = retainedNewest;
         viewModeRef.current = "live";
-        setViewMode("live");
-        setStreamEpoch((epoch) => epoch + 1);
+        resumeLive = true;
       }
+      loadingNewerRef.current = false;
+      setNewerError(null);
+      startTransition(() => {
+        if (status !== undefined) {
+          setSessionStatusProjection(status);
+        }
+        setEventWindow(retained);
+        setHasOlder(rearmedOlder);
+        setHasNewer(newer);
+        if (resumeLive) {
+          setViewMode("live");
+          setStreamEpoch((epoch) => epoch + 1);
+        }
+        setLoadingNewer(false);
+      });
+      published = true;
       return newer;
+    } catch (reason) {
+      // A settled request from an old navigation lifetime is not a failure of
+      // the current session. Preserve current loading/error state as well.
+      if (!isCurrent()) {
+        return false;
+      }
+      setNewerError(normalizeError(reason));
+      // Keep authorization and integrity failures actionable for callers;
+      // timeline-owned invocations attach their own explicit recovery UI.
+      throw reason;
     } finally {
-      loadingNewerRef.current = false;
-      setLoadingNewer(false);
+      if (!published && isCurrent()) {
+        loadingNewerRef.current = false;
+        setLoadingNewer(false);
+      }
     }
-  }, [client, workspaceId, sessionId]);
+  }, [client, workspaceId, sessionId, ownsNavigation]);
+
+  const jumpToSequence = useCallback(
+    async (sequence: number, navigationOptions?: { signal?: AbortSignal }): Promise<boolean> => {
+      const signal = navigationOptions?.signal;
+      if (!ownsNavigation() || !sessionId || !Number.isSafeInteger(sequence) || sequence < 1)
+        return false;
+      // A navigation that was already cancelled (for example Find closed before
+      // the caller could react) must not disturb any current view state.
+      if (signal?.aborted) return false;
+      // Explicit targets supersede both other targets and adjacent-page requests.
+      const generation = ++navigationGenerationRef.current;
+      setQuestionEvidence(null);
+      const current = () => generation === navigationGenerationRef.current && ownsNavigation();
+      const previousMode = viewModeRef.current;
+      streamAbortRef.current?.abort();
+      generationRef.current += 1;
+      viewModeRef.current = "history";
+      setViewMode("history");
+      loadingOlderRef.current = loadingNewerRef.current = loadingOldestRef.current = false;
+      setLoadingOlder(false);
+      setLoadingNewer(false);
+      setLoadingOldest(false);
+      loadingTargetRef.current = true;
+      setLoadingTarget(true);
+      let published = false;
+      try {
+        const [before, following] = await Promise.all([
+          loadPreviousPage(client, workspaceId, sessionId, sequence + 1, { pageSize: 128 }),
+          loadNextPage(client, workspaceId, sessionId, sequence, { pageSize: 128 }),
+        ]);
+        // Close-during-fetch fence: a pending jump must not replace the window
+        // after its owner (for example ConversationFind) has gone away. The
+        // finally block still settles loadingTarget for this generation.
+        if (signal?.aborted) return false;
+        if (!current()) return false;
+        if (!before.some((event) => event.sequence === sequence)) return false;
+        // Bound each side, keeping the target even if its message alone exceeds
+        // the ordinary byte budget. Never evict the very event being navigated to.
+        const prefix = boundBrowserSessionEventWindow(before, {
+          direction: "newest",
+          maxBytes: SESSION_EVENT_BROWSER_MAX_BYTES / 2,
+        });
+        const retained = boundBrowserSessionEventWindow([...prefix.events, ...following], {
+          direction: "oldest",
+        });
+        if (!retained.events.some((event) => event.sequence === sequence)) return false;
+        streamAbortRef.current?.abort();
+        generationRef.current += 1;
+        const status = observeSessionStatus(retained.events, sessionStatusRef);
+        eventWindowRef.current = retained;
+        oldestSequenceRef.current = retained.events[0]!.sequence;
+        newestSequenceRef.current = maxResumeSequenceOrNull(retained.events);
+        lastSequenceRef.current = Math.max(lastSequenceRef.current, newestSequenceRef.current ?? 0);
+        hasOlderRef.current = !isLogStart(retained.events[0]!);
+        // Compact/byte-bounded pages may be short despite more durable history.
+        // Only an empty forward page proves the end (same rule as loadNewer).
+        hasNewerRef.current =
+          following.length > 0 ||
+          retained.truncated ||
+          (newestSequenceRef.current ?? 0) < lastSequenceRef.current;
+        initialWindowLoadedRef.current = true;
+        setInitialHistoryReady(true);
+        setError(null);
+        viewModeRef.current = "history";
+        setEventWindow(retained);
+        setHasOlder(hasOlderRef.current);
+        setHasNewer(hasNewerRef.current);
+        setInitialLoading(false);
+        setViewMode("history");
+        setNewerError(null);
+        if (status !== undefined) setSessionStatusProjection(status);
+        published = true;
+        return true;
+      } catch (reason) {
+        if (!current() || signal?.aborted) return false;
+        throw reason;
+      } finally {
+        if (current()) {
+          loadingTargetRef.current = false;
+          setLoadingTarget(false);
+          if (!published && previousMode === "live") {
+            viewModeRef.current = "live";
+            setViewMode("live");
+            setStreamEpoch((epoch) => epoch + 1);
+          }
+        }
+      }
+    },
+    [client, workspaceId, sessionId, ownsNavigation],
+  );
+
+  const jumpToLatestQuestion = useCallback(
+    async (questionOptions?: LatestQuestionOptions): Promise<number | null> => {
+      if (!sessionId || !ownsNavigation()) return null;
+      let generation = navigationGenerationRef.current;
+      const current = () => ownsNavigation() && generation === navigationGenerationRef.current;
+      try {
+        // Optional action code stays off the session-open path. Capture identity
+        // before the import and fence its completion just like network reads.
+        const { resolveLatestQuestion } = await import("./latest-question");
+        if (!current()) return null;
+        const destination = await resolveLatestQuestion({
+          client,
+          workspaceId,
+          sessionId,
+          isCurrent: current,
+          resumeSequence: maxResumeSequence,
+          options: questionOptions,
+        });
+        if (!destination || !current()) return null;
+        if (!eventWindowRef.current.events.some((event) => event.sequence === destination.anchor)) {
+          const navigation = jumpToSequence(destination.anchor);
+          generation = navigationGenerationRef.current;
+          if (!(await navigation) || !current()) return null;
+        }
+        setQuestionEvidence({
+          client,
+          streamKey,
+          anchor: destination.anchor,
+          events: destination.events,
+        });
+        return destination.questionSequence;
+      } catch (reason) {
+        if (!current()) return null;
+        throw reason;
+      }
+    },
+    [client, workspaceId, sessionId, streamKey, ownsNavigation, jumpToSequence],
+  );
 
   const jumpToLatest = useCallback(async (): Promise<void> => {
+    // An old host retry closure must not clear a replacement session's error
+    // or abort its live feed before the passive effect cleanup has run.
+    if (!ownsNavigation()) return;
+    if (loadingTargetRef.current) {
+      navigationGenerationRef.current += 1;
+      loadingTargetRef.current = false;
+      setLoadingTarget(false);
+    }
     if (!sessionId || navigationBusy()) {
       return;
     }
+    navigationGenerationRef.current += 1;
+    setQuestionEvidence(null);
     loadingLatestRef.current = true;
     setLoadingLatest(true);
+    setNewerError(null);
+    setError(null);
+    let published = false;
     try {
       streamAbortRef.current?.abort();
       hasNewerRef.current = false;
-      setHasNewer(false);
       hasOlderRef.current = false;
-      setHasOlder(false);
       newestSequenceRef.current = null;
       oldestSequenceRef.current = null;
       eventWindowRef.current = EMPTY_EVENT_WINDOW;
-      setEventWindow(EMPTY_EVENT_WINDOW);
       initialWindowLoadedRef.current = false;
       streamResumeSequenceRef.current = after;
-      setInitialLoading(true);
       viewModeRef.current = "live";
-      setViewMode("live");
-      setStreamEpoch((epoch) => epoch + 1);
+      loadingLatestRef.current = false;
+      startTransition(() => {
+        setHasNewer(false);
+        setHasOlder(false);
+        setEventWindow(EMPTY_EVENT_WINDOW);
+        setInitialLoading(true);
+        setViewMode("live");
+        setStreamEpoch((epoch) => epoch + 1);
+        setLoadingLatest(false);
+      });
+      published = true;
       // Effect reloads the tip. The tip fetch itself is owned by the effect.
       await Promise.resolve();
     } finally {
-      loadingLatestRef.current = false;
-      setLoadingLatest(false);
+      if (!published) {
+        loadingLatestRef.current = false;
+        setLoadingLatest(false);
+      }
     }
-  }, [after, sessionId]);
+  }, [after, sessionId, ownsNavigation]);
 
   const identityMatches = stateStreamKey === streamKey;
   const visibleEvents = identityMatches ? eventWindow.events : EMPTY_EVENTS;
-  const timeline = useMemo(() => buildTimeline(visibleEvents), [visibleEvents]);
+  const timeline = useMemo(() => {
+    const witness =
+      questionEvidence?.client === client &&
+      questionEvidence.streamKey === streamKey &&
+      visibleEvents.some((event) => event.sequence === questionEvidence.anchor)
+        ? questionEvidence.events
+        : EMPTY_EVENTS;
+    const timelineOptions = { partialStart: hasOlder || eventWindow.truncated || after > 0 };
+    if (witness.length === 0) return buildTimeline(visibleEvents, timelineOptions);
+    const ids = new Set(visibleEvents.map((event) => event.id));
+    return buildTimeline(
+      [...visibleEvents, ...witness.filter((event) => !ids.has(event.id))],
+      timelineOptions,
+    );
+  }, [visibleEvents, hasOlder, eventWindow.truncated, after, questionEvidence, client, streamKey]);
 
   return {
     events: visibleEvents,
     timeline,
     sessionStatus: identityMatches ? sessionStatusProjection : null,
+    sessionStatusSequence: identityMatches ? sessionStatusRef.current.sequence : 0,
     connectionState: identityMatches ? connectionState : "idle",
     lastSequence: identityMatches ? lastSequenceRef.current : after,
     windowBytes: identityMatches ? eventWindow.bytes : 2,
     windowTruncated: identityMatches ? eventWindow.truncated : false,
     initialLoading: fullReplay ? false : identityMatches ? initialLoading : true,
+    initialHistoryReady: identityMatches && initialHistoryReady,
     hasOlder: !identityMatches ? false : hasOlder,
     loadingOlder: !identityMatches ? false : loadingOlder,
     loadOlder,
@@ -700,7 +1115,10 @@ export function useSessionEvents(
     loadOldest,
     loadingLatest: !identityMatches ? false : loadingLatest,
     jumpToLatest,
-    error: identityMatches ? error : null,
+    jumpToLatestQuestion,
+    jumpToSequence,
+    loadingTarget: identityMatches && loadingTarget,
+    error: identityMatches ? (newerError ?? error) : null,
   };
 }
 
@@ -709,9 +1127,10 @@ export function useSessionEvents(
  * accumulation retains the newest suffix; backward paging retains the oldest
  * prefix so newly fetched history cannot be immediately evicted. This is
  * deliberately separate from durable history and transport paging: when a
- * backward page evicts the live tail, the hook reconnects from the retained
- * high-water mark while preserving the highest-ever-observed sequence
- * separately. The source event remains durable in PostgreSQL throughout.
+ * backward page evicts the live tail, the hook enters bounded history mode and
+ * preserves the highest-ever-observed sequence separately for forward paging.
+ * The source event remains durable in PostgreSQL throughout. An event larger
+ * than the byte target is retained alone, never replaced by a lossy preview.
  */
 export function boundBrowserSessionEventWindow(
   events: readonly SessionEvent[],
@@ -723,7 +1142,7 @@ export function boundBrowserSessionEventWindow(
 ): BrowserSessionEventWindow {
   const maxBytes = Math.max(1024, options.maxBytes ?? SESSION_EVENT_BROWSER_MAX_BYTES);
   const maxCount = Math.max(1, Math.floor(options.maxCount ?? SESSION_EVENT_BROWSER_MAX_COUNT));
-  const safe = events.map(boundBrowserLegacyEvent);
+  const safe = events;
   const selected: SessionEvent[] = [];
   let bytes = 2; // []
   const direction = options.direction ?? "newest";
@@ -734,7 +1153,7 @@ export function boundBrowserSessionEventWindow(
     const event = safe[index]!;
     const eventBytes = browserJsonBytes(event);
     const separator = selected.length === 0 ? 0 : 1;
-    if (bytes + separator + eventBytes > maxBytes) break;
+    if (selected.length > 0 && bytes + separator + eventBytes > maxBytes) break;
     selected.push(event);
     bytes += separator + eventBytes;
   }
@@ -746,255 +1165,41 @@ export function boundBrowserSessionEventWindow(
   };
 }
 
-function boundBrowserLegacyEvent(event: SessionEvent): SessionEvent {
-  // The server-side canonical projection lives in @opengeni/contracts. The
-  // publishable React package may depend only on the zero-runtime-dependency
-  // SDK, so this is intentionally a last-resort client guard rather than a
-  // second durable representation. Reconstructing the SDK wire shape prevents
-  // legacy/malformed extra properties from bypassing the browser byte cap.
-  const serialized = browserSerialize(event);
-  const originalBytes = serialized.serializable
-    ? encoder.encode(serialized.value).byteLength
-    : null;
-  const typeIsSafe =
-    browserUtf8Bytes(event.type) <= BROWSER_EVENT_TYPE_MAX_BYTES &&
-    !event.type.includes("\n") &&
-    !event.type.includes("\r");
-  const clientEventId = boundBrowserOptionalText(
-    event.clientEventId,
-    BROWSER_EVENT_CLIENT_ID_MAX_BYTES,
-  );
-  const duplicateReason = boundBrowserOptionalText(
-    event.duplicateReason,
-    BROWSER_EVENT_DUPLICATE_REASON_MAX_BYTES,
-  );
-
-  if (
-    serialized.serializable &&
-    originalBytes !== null &&
-    originalBytes <= SESSION_EVENT_BROWSER_SINGLE_EVENT_MAX_BYTES &&
-    typeIsSafe &&
-    clientEventId === event.clientEventId &&
-    duplicateReason === event.duplicateReason
-  ) {
-    return event;
-  }
-
-  const envelopeProjection = [
-    !typeIsSafe
-      ? browserEnvelopeFieldProjection("type", event.type, "session.event.envelope_omitted")
-      : null,
-    clientEventId !== event.clientEventId
-      ? browserEnvelopeFieldProjection("clientEventId", event.clientEventId, clientEventId)
-      : null,
-    duplicateReason !== event.duplicateReason
-      ? browserEnvelopeFieldProjection("duplicateReason", event.duplicateReason, duplicateReason)
-      : null,
-  ].filter((field) => field !== null);
-  const payloadSerialization = browserSerialize(event.payload);
-  const payloadBytes = payloadSerialization.serializable
-    ? encoder.encode(payloadSerialization.value).byteLength
-    : null;
-  const preview = truncateBrowserUtf8Middle(
-    payloadSerialization.value,
-    BROWSER_EVENT_PAYLOAD_PREVIEW_MAX_BYTES,
-  );
-  const truncation = {
-    truncated: true as const,
-    surface: "browser_legacy_guard" as const,
-    reason: serialized.serializable ? "event_envelope_bytes_exceeded" : "event_not_serializable",
-    originalBytes,
-    deliveredBytes: 0,
-    omittedBytes: originalBytes,
-    estimatedOriginalTokens: originalBytes === null ? null : Math.ceil(originalBytes / 4),
-    estimatedDeliveredTokens: 0,
-    fullEvidence: { available: false as const, reason: "not_retained" as const },
-    details: [
-      {
-        path: "$.payload",
-        kind: "payload_preview",
-        originalBytes: payloadBytes,
-        deliveredBytes: browserUtf8Bytes(preview),
-      },
-    ],
-  };
-  const payload: Record<string, unknown> = {
-    ...browserPayloadIdentity(event.payload),
-    preview,
-    ...(envelopeProjection.length > 0
-      ? {
-          originalType: boundBrowserText(event.type, BROWSER_EVENT_TYPE_MAX_BYTES),
-          envelopeProjection: {
-            truncated: true,
-            surface: "browser_legacy_guard",
-            fields: envelopeProjection,
-          },
-        }
-      : {}),
-    truncation,
-  };
-  const bounded: SessionEvent = {
-    id: boundBrowserText(event.id, BROWSER_EVENT_ID_MAX_BYTES),
-    workspaceId: boundBrowserText(event.workspaceId, BROWSER_EVENT_ID_MAX_BYTES),
-    sessionId: boundBrowserText(event.sessionId, BROWSER_EVENT_ID_MAX_BYTES),
-    sequence: event.sequence,
-    type: typeIsSafe ? event.type : "session.event.envelope_omitted",
-    payload,
-    occurredAt: boundBrowserText(event.occurredAt, BROWSER_EVENT_ID_MAX_BYTES),
-    clientEventId,
-    turnId: boundBrowserOptionalText(event.turnId, BROWSER_EVENT_ID_MAX_BYTES),
-    turnGeneration: event.turnGeneration,
-    turnAttemptId: boundBrowserOptionalText(event.turnAttemptId, BROWSER_EVENT_ID_MAX_BYTES),
-    turnAssociation: event.turnAssociation,
-    duplicateOfEventId: boundBrowserOptionalText(
-      event.duplicateOfEventId,
-      BROWSER_EVENT_ID_MAX_BYTES,
-    ),
-    duplicateReason,
-  };
-
-  settleBrowserEventTruncation(bounded, truncation);
-  if (browserJsonBytes(bounded) > SESSION_EVENT_BROWSER_SINGLE_EVENT_MAX_BYTES) {
-    payload.preview = truncateBrowserUtf8Middle(String(payload.preview), 4 * 1024);
-    truncation.details = truncation.details.slice(0, 1);
-    settleBrowserEventTruncation(bounded, truncation);
-  }
-  if (browserJsonBytes(bounded) > SESSION_EVENT_BROWSER_SINGLE_EVENT_MAX_BYTES) {
-    bounded.clientEventId = null;
-    bounded.duplicateReason = null;
-    payload.preview = "[legacy event omitted at the browser byte boundary]";
-    settleBrowserEventTruncation(bounded, truncation);
-  }
-  return bounded;
-}
-
-function browserJsonBytes(value: unknown): number {
-  return encoder.encode(browserSerialize(value).value).byteLength;
-}
-
-function browserSerialize(value: unknown): { value: string; serializable: boolean } {
-  try {
-    const serialized = JSON.stringify(value);
-    return { value: serialized === undefined ? "null" : serialized, serializable: true };
-  } catch {
-    return {
-      value: '"[unserializable event payload omitted at browser boundary]"',
-      serializable: false,
-    };
+/** @internal Append immutable events without serializing the retained history again. */
+export function appendBrowserSessionEventWindow(
+  current: BrowserSessionEventWindow,
+  batch: readonly SessionEvent[],
+  options: { maxBytes?: number; maxCount?: number } = {},
+): BrowserSessionEventWindow {
+  const maxBytes = Math.max(1024, options.maxBytes ?? SESSION_EVENT_BROWSER_MAX_BYTES);
+  const maxCount = Math.max(1, Math.floor(options.maxCount ?? SESSION_EVENT_BROWSER_MAX_COUNT));
+  const events = [...current.events, ...batch];
+  let bytes = current.bytes;
+  for (let index = 0; index < batch.length; index += 1) {
+    bytes += browserJsonBytes(batch[index]) + (current.events.length + index > 0 ? 1 : 0);
   }
-}
-
-function browserPayloadIdentity(payload: unknown): Record<string, unknown> {
-  if (!payload || typeof payload !== "object" || Array.isArray(payload)) return {};
-  const record = payload as Record<string, unknown>;
-  const identity: Record<string, unknown> = {};
-  for (const field of BROWSER_EVENT_PAYLOAD_IDENTITY_FIELDS) {
-    const value = record[field];
-    if (typeof value === "string") {
-      identity[field] = boundBrowserText(value, BROWSER_EVENT_ID_MAX_BYTES);
-    } else if (typeof value === "number" || typeof value === "boolean" || value === null) {
-      identity[field] = value;
-    }
+  let start = 0;
+  // Preserve the newest event even when it alone exceeds the byte target,
+  // matching the full-window reducer and retaining exact cursor progress.
+  while (events.length - start > 1 && (bytes > maxBytes || events.length - start > maxCount)) {
+    bytes -= browserJsonBytes(events[start]) + 1;
+    start += 1;
   }
-  return identity;
-}
-
-function browserEnvelopeFieldProjection(
-  field: string,
-  original: string | null | undefined,
-  delivered: string | null | undefined,
-): { field: string; originalBytes: number; deliveredBytes: number } {
   return {
-    field,
-    originalBytes: typeof original === "string" ? browserUtf8Bytes(original) : 0,
-    deliveredBytes: typeof delivered === "string" ? browserUtf8Bytes(delivered) : 0,
+    events: start === 0 ? events : events.slice(start),
+    bytes,
+    truncated: current.truncated || start > 0,
   };
 }
 
-function boundBrowserOptionalText<T extends string | null | undefined>(
-  value: T,
-  maxBytes: number,
-): T {
-  return (typeof value === "string" ? boundBrowserText(value, maxBytes) : value) as T;
-}
-
-function boundBrowserText(value: string, maxBytes: number): string {
-  const bytes = encoder.encode(value);
-  if (bytes.byteLength <= maxBytes) return value;
-  const marker = "…[truncated]";
-  const prefixBudget = Math.max(0, maxBytes - browserUtf8Bytes(marker));
-  let prefixEnd = Math.min(prefixBudget, bytes.byteLength);
-  while (
-    prefixEnd > 0 &&
-    prefixEnd < bytes.byteLength &&
-    isBrowserUtf8Continuation(bytes[prefixEnd]!)
-  ) {
-    prefixEnd -= 1;
-  }
-  return `${decoder.decode(bytes.subarray(0, prefixEnd))}${marker}`;
-}
-
-function truncateBrowserUtf8Middle(value: string, maxBytes: number): string {
-  const bytes = encoder.encode(value);
-  if (bytes.byteLength <= maxBytes) return value;
-  const marker = `…[${bytes.byteLength - maxBytes} bytes omitted]…`;
-  const contentBudget = Math.max(0, maxBytes - browserUtf8Bytes(marker));
-  const leftBudget = Math.floor(contentBudget / 2);
-  const rightBudget = contentBudget - leftBudget;
-  let leftEnd = Math.min(leftBudget, bytes.byteLength);
-  while (leftEnd > 0 && leftEnd < bytes.byteLength && isBrowserUtf8Continuation(bytes[leftEnd]!)) {
-    leftEnd -= 1;
-  }
-  let rightStart = Math.max(0, bytes.byteLength - rightBudget);
-  while (rightStart < bytes.byteLength && isBrowserUtf8Continuation(bytes[rightStart]!)) {
-    rightStart += 1;
-  }
-  return `${decoder.decode(bytes.subarray(0, leftEnd))}${marker}${decoder.decode(bytes.subarray(rightStart))}`;
-}
-
-function settleBrowserEventTruncation(
-  event: SessionEvent,
-  truncation: {
-    originalBytes: number | null;
-    deliveredBytes: number;
-    omittedBytes: number | null;
-    estimatedDeliveredTokens: number;
-  },
-): void {
-  for (let attempt = 0; attempt < 16; attempt += 1) {
-    const deliveredBytes = browserJsonBytes(event);
-    const omittedBytes =
-      truncation.originalBytes === null
-        ? null
-        : Math.max(0, truncation.originalBytes - deliveredBytes);
-    const estimatedDeliveredTokens = Math.ceil(deliveredBytes / 4);
-    if (
-      truncation.deliveredBytes === deliveredBytes &&
-      truncation.omittedBytes === omittedBytes &&
-      truncation.estimatedDeliveredTokens === estimatedDeliveredTokens
-    ) {
-      return;
-    }
-    truncation.deliveredBytes = deliveredBytes;
-    truncation.omittedBytes = omittedBytes;
-    truncation.estimatedDeliveredTokens = estimatedDeliveredTokens;
-  }
-  throw new RangeError("Browser event byte accounting did not converge");
-}
-
-function browserUtf8Bytes(value: string): number {
-  return encoder.encode(value).byteLength;
-}
-
-function isBrowserUtf8Continuation(value: number): boolean {
-  return (value & 0xc0) === 0x80;
+function browserJsonBytes(value: unknown): number {
+  return encoder.encode(JSON.stringify(value)).byteLength;
 }
 
 function observeSessionStatus(
   events: readonly SessionEvent[],
   ref: { current: { sequence: number; status: SessionStatus | null } },
-  setStatus: (status: SessionStatus | null) => void,
-): void {
+): SessionStatus | undefined {
   let latest: { sequence: number; status: SessionStatus } | null = null;
   for (const event of events) {
     const status = sessionStatusFromEvents([event]);
@@ -1002,9 +1207,71 @@ function observeSessionStatus(
       latest = { sequence: event.sequence, status };
     }
   }
-  if (!latest || latest.sequence < ref.current.sequence) return;
+  if (!latest || latest.sequence < ref.current.sequence) return undefined;
   ref.current = latest;
-  setStatus(latest.status);
+  return latest.status;
+}
+
+type ForegroundCatchupPlan =
+  | { kind: "resume" }
+  | { kind: "append"; events: SessionEvent[]; resumeSequence: number }
+  | { kind: "reload" };
+
+/**
+ * Decide how a sustained hidden-tab suspension rejoins the durable event log.
+ *
+ * `lastSequence - cursor` is the exact raw durable work missed, but it is not
+ * the number of visible messages: one streaming answer can own thousands of
+ * adjacent delta rows. Small raw gaps therefore resume directly; medium gaps
+ * get one forward compact page and are judged by the browser-visible result;
+ * a page that cannot prove complete bounded coverage, or that would add too
+ * many rows/groups/bytes, reloads the latest tail instead.
+ */
+async function planForegroundCatchup(
+  client: EmbeddedSessionClientLike,
+  workspaceId: string,
+  sessionId: string,
+  cursor: number,
+  options: { signal?: AbortSignal } = {},
+): Promise<ForegroundCatchupPlan> {
+  if (options.signal?.aborted) throw abortError();
+  const session = await client.getSession(workspaceId, sessionId, {
+    fresh: true,
+    ...(options.signal ? { signal: options.signal } : {}),
+  });
+  if (options.signal?.aborted) throw abortError();
+  const durableHead = Math.max(cursor, session.lastSequence);
+  const rawGap = durableHead - cursor;
+  if (rawGap <= FOREGROUND_DIRECT_REPLAY_MAX_SEQUENCES) {
+    return { kind: "resume" };
+  }
+  if (rawGap > FOREGROUND_COMPACT_PROBE_MAX_SEQUENCES) {
+    return { kind: "reload" };
+  }
+
+  const page = await loadNextPage(client, workspaceId, sessionId, cursor, {
+    pageSize: rawGap,
+    ...(options.signal ? { signal: options.signal } : {}),
+  });
+  const events = page.filter((event) => eventResumeSequence(event) > cursor);
+  if (events.length === 0) {
+    return { kind: "reload" };
+  }
+  assertAscending(events);
+  const resumeSequence = maxResumeSequence(events);
+  if (resumeSequence < durableHead) {
+    // Byte/count truncation or an incomplete projection means this page cannot
+    // prove that one append reaches the head observed above.
+    return { kind: "reload" };
+  }
+  if (
+    events.length > FOREGROUND_COMPACT_CATCHUP_MAX_EVENTS ||
+    groupCount(events) > FOREGROUND_COMPACT_CATCHUP_MAX_GROUPS ||
+    browserJsonBytes(events) > FOREGROUND_COMPACT_CATCHUP_MAX_BYTES
+  ) {
+    return { kind: "reload" };
+  }
+  return { kind: "append", events, resumeSequence };
 }
 
 type LoadedEventWindow = {
@@ -1030,7 +1297,9 @@ async function loadEventWindow(
     pageSize: number;
     targetGroups: number;
     maxFetches: number;
+    boundaryPageCap?: number;
     signal?: AbortSignal;
+    isCurrent?: () => boolean;
   },
 ): Promise<LoadedEventWindow> {
   let cursor = options.before;
@@ -1046,6 +1315,7 @@ async function loadEventWindow(
       pageSize: options.pageSize,
       ...(options.signal ? { signal: options.signal } : {}),
     });
+    if (options.isCurrent?.() === false) throw abortError();
     fetches += 1;
     if (page.length === 0) {
       reachedStart = true;
@@ -1064,19 +1334,19 @@ async function loadEventWindow(
   // turn boundary already in the buffer — the dropped fragment is refetched by
   // the next loadOlder (everything below the new oldest sequence), whose own
   // window snaps the same way, so every seam lands on a turn start. Extra
-  // pages are fetched only when the buffer holds no boundary at all (one
-  // monster turn); past the cap a mid-turn top is accepted.
+  // page is fetched only when the buffer holds no boundary at all (one dense
+  // turn); past the cap the existing truncation/hasOlder signal remains true.
   let snapPages = 0;
   while (
     !reachedStart &&
     findBoundaryIndex(buffer) === -1 &&
-    snapPages < BOUNDARY_PAGE_CAP &&
-    fetches < options.maxFetches
+    snapPages < (options.boundaryPageCap ?? 0)
   ) {
     const page = await loadPreviousPage(client, workspaceId, sessionId, cursor, {
       pageSize: options.pageSize,
       ...(options.signal ? { signal: options.signal } : {}),
     });
+    if (options.isCurrent?.() === false) throw abortError();
     fetches += 1;
     snapPages += 1;
     if (page.length === 0) {
@@ -1097,6 +1367,8 @@ async function loadEventWindow(
       buffer = buffer.slice(boundary);
     }
   }
+  const densityWindow = trimBackwardToGroupTarget(buffer, options.targetGroups);
+  buffer = densityWindow.events;
 
   const oldest = buffer[0] ?? null;
   const newest = buffer[buffer.length - 1] ?? null;
@@ -1104,21 +1376,26 @@ async function loadEventWindow(
     events: buffer,
     oldestSequence: oldest?.sequence ?? null,
     newestSequence: newest ? maxResumeSequence(buffer) : 0,
-    hasOlder: buffer.length > 0 && !reachedStart && oldest?.type !== "session.created",
+    hasOlder:
+      buffer.length > 0 &&
+      (densityWindow.trimmed || (!reachedStart && oldest?.type !== "session.created")),
   };
 }
 
 /** Index of the oldest clean turn start in the buffer, or -1. */
 function findBoundaryIndex(events: SessionEvent[]): number {
   for (let index = 0; index < events.length; index += 1) {
-    const type = events[index]!.type;
-    if (type === "session.created" || type === "user.message") {
+    if (isTurnBoundary(events[index]!)) {
       return index;
     }
   }
   return -1;
 }
 
+function isTurnBoundary(event: SessionEvent): boolean {
+  return event.type === "session.created" || event.type === "user.message";
+}
+
 /**
  * Forward (oldest→newer) density-bounded window. Used for jump-to-start and
  * loadNewer so the browser never walks the whole middle gap.
@@ -1133,6 +1410,7 @@ async function loadForwardEventWindow(
     targetGroups: number;
     maxFetches: number;
     signal?: AbortSignal;
+    isCurrent?: () => boolean;
   },
 ): Promise<LoadedForwardEventWindow> {
   let cursor = options.after;
@@ -1148,6 +1426,7 @@ async function loadForwardEventWindow(
       pageSize: options.pageSize,
       ...(options.signal ? { signal: options.signal } : {}),
     });
+    if (options.isCurrent?.() === false) throw abortError();
     fetches += 1;
     if (page.length === 0) {
       reachedEnd = true;
@@ -1155,12 +1434,15 @@ async function loadForwardEventWindow(
     }
     assertAscending(page);
     buffer = [...buffer, ...page];
-    cursor = page[page.length - 1]!.sequence;
-    if (page.length < options.pageSize) {
-      reachedEnd = true;
-      break;
-    }
+    // Compact events retain their first raw sequence in `sequence` and expose
+    // the covered high-water mark through `coalescedUntil`. Advancing by the
+    // first sequence duplicates compacted text on the next page. A compact
+    // response length is not an end-of-history signal either: thousands of raw
+    // events may legitimately collapse into one returned event.
+    cursor = maxResumeSequence(page);
   }
+  const densityWindow = trimForwardToGroupTarget(buffer, options.targetGroups);
+  buffer = densityWindow.events;
 
   const oldest = buffer[0] ?? null;
   const newest = buffer[buffer.length - 1] ?? null;
@@ -1168,10 +1450,45 @@ async function loadForwardEventWindow(
     events: buffer,
     oldestSequence: oldest?.sequence ?? null,
     newestSequence: newest ? maxResumeSequence(buffer) : 0,
-    hasNewer: buffer.length > 0 && !reachedEnd,
+    hasNewer: buffer.length > 0 && (densityWindow.trimmed || !reachedEnd),
   };
 }
 
+type DensityWindow = {
+  events: SessionEvent[];
+  trimmed: boolean;
+};
+
+/** Keep the newest complete turn groups near an older-history seam. */
+function trimBackwardToGroupTarget(events: SessionEvent[], targetGroups: number): DensityWindow {
+  if (!Number.isFinite(targetGroups) || targetGroups <= 0 || events.length === 0) {
+    return { events, trimmed: false };
+  }
+  for (let index = events.length - 1; index > 0; index -= 1) {
+    if (!isTurnBoundary(events[index]!)) continue;
+    const candidate = events.slice(index);
+    if (groupCount(candidate) >= targetGroups) {
+      return { events: candidate, trimmed: true };
+    }
+  }
+  return { events, trimmed: false };
+}
+
+/** Keep the oldest complete turn groups near a forward-history seam. */
+function trimForwardToGroupTarget(events: SessionEvent[], targetGroups: number): DensityWindow {
+  if (!Number.isFinite(targetGroups) || targetGroups <= 0 || events.length === 0) {
+    return { events, trimmed: false };
+  }
+  for (let index = 1; index < events.length; index += 1) {
+    if (!isTurnBoundary(events[index]!)) continue;
+    const candidate = events.slice(0, index);
+    if (groupCount(candidate) >= targetGroups) {
+      return { events: candidate, trimmed: true };
+    }
+  }
+  return { events, trimmed: false };
+}
+
 type PreviousPage = SessionEvent[] & { requested: number };
 
 async function loadPreviousPage(
@@ -1248,18 +1565,22 @@ function isLogStart(event: SessionEvent): boolean {
   return event.type === "session.created" || event.sequence <= 1;
 }
 
-function maxResumeSequence(events: SessionEvent[]): number {
+function maxResumeSequence(events: readonly SessionEvent[]): number {
   return events.reduce((max, event) => Math.max(max, eventResumeSequence(event)), 0);
 }
 
-function eventResumeSequence(event: SessionEvent): number {
-  const payload = asRecord(event.payload);
-  const coalescedUntil = Number(payload.coalescedUntil);
-  return Math.max(event.sequence, Number.isFinite(coalescedUntil) ? Math.floor(coalescedUntil) : 0);
+function maxResumeSequenceOrNull(events: readonly SessionEvent[]): number | null {
+  return events.length > 0 ? maxResumeSequence(events) : null;
 }
 
-function asRecord(value: unknown): Record<string, unknown> {
-  return value && typeof value === "object" ? (value as Record<string, unknown>) : {};
+function eventResumeSequence(event: SessionEvent): number {
+  const streamedCoverage = sessionEventStreamCoveredThrough(event);
+  if (streamedCoverage !== null) return streamedCoverage;
+  return typeof event.coveredThrough === "number" &&
+    Number.isSafeInteger(event.coveredThrough) &&
+    event.coveredThrough >= event.sequence
+    ? event.coveredThrough
+    : event.sequence;
 }
 
 function assertAscending(events: SessionEvent[]): void {