@opengeni/react 3.3.2 → 3.7.0-canary.0

package/src/hooks/use-sandbox-files.ts

@@ -1,4 +1,5 @@
 import type {
+  FileSystemRouteIdentity,
   FsChangedPayload,
   FsReadResponse,
   FsTreeNode,
@@ -84,6 +85,9 @@ export type UseSandboxFilesOptions = ClientOverride & {
   events?: SessionEvent[] | undefined;
   /** Initial path to list (workspace root by default). */
   rootPath?: string | undefined;
+  /** Exact capability identity for the selected filesystem route. A route/root
+   * change resets this hook and makes stale provider requests fail retryably. */
+  route?: FileSystemRouteIdentity | undefined;
   /** Hold off the initial list (e.g. panel collapsed). Default true. */
   enabled?: boolean | undefined;
   /** Pause live reads/invalidation while preserving the last rendered result. */
@@ -169,8 +173,12 @@ function normalizeRoot(root: string): string {
   return normalized === "." ? "" : normalized;
 }
 
+function isAbsoluteTreePath(path: string): boolean {
+  return path.startsWith("/") || /^[A-Za-z]:\//u.test(path);
+}
+
 function joinTreeRoot(root: string, path: string): string {
-  if (!root || path.startsWith("/")) return path;
+  if (!root || isAbsoluteTreePath(path)) return path;
   return root === "/" ? `/${path}` : `${root}/${path}`;
 }
 
@@ -301,6 +309,7 @@ const FS_LIST_BATCH_REQUEST_LIMIT = 16;
 function initialDirectoryFrontier(rootPath: string, repoPaths: readonly string[]): string[] {
   const root = normalizeRoot(rootPath);
   const rootParts = root.split("/").filter(Boolean);
+  const rootPrefix = root.startsWith("//") ? "//" : root.startsWith("/") ? "/" : "";
   const paths = new Set<string>();
   for (const repoPath of repoPaths) {
     const canonicalRepoPath = joinTreeRoot(root, normalizeRoot(repoPath));
@@ -308,7 +317,7 @@ function initialDirectoryFrontier(rootPath: string, repoPaths: readonly string[]
     if (rootParts.some((part, index) => parts[index] !== part)) continue;
     for (let depth = rootParts.length + 1; depth <= parts.length; depth += 1) {
       const path = parts.slice(0, depth).join("/");
-      paths.add(root.startsWith("/") ? `/${path}` : path);
+      paths.add(`${rootPrefix}${path}`);
     }
   }
   // A workspace with hundreds of repositories should remain lazy. This still
@@ -491,6 +500,15 @@ export function useSandboxFiles(
   const enabled = (options.enabled ?? true) && Boolean(sessionId);
   const active = options.active ?? true;
   const rootPath = options.rootPath ?? "";
+  const routeEpoch = options.route?.epoch ?? null;
+  const routeRoot = options.route?.root ?? null;
+  const route = useMemo<FileSystemRouteIdentity | undefined>(
+    () =>
+      routeEpoch !== null && routeRoot !== null
+        ? { epoch: routeEpoch, root: routeRoot }
+        : undefined,
+    [routeEpoch, routeRoot],
+  );
   const repoPathsKey = [
     ...new Set((options.repoPaths?.length ? options.repoPaths : [rootPath]).map(normalizeRoot)),
   ].join("\u0000");
@@ -503,7 +521,7 @@ export function useSandboxFiles(
   const acceptsEventReadsRef = useRef(acceptsEventReads);
   acceptsEventReadsRef.current = acceptsEventReads;
   const hasLiveIoFence = options.liveness !== undefined;
-  const identityKey = `${workspaceId}\u0000${sessionId ?? ""}\u0000${rootPath}\u0000${repoPathsKey}`;
+  const identityKey = `${workspaceId}\u0000${sessionId ?? ""}\u0000${rootPath}\u0000${repoPathsKey}\u0000${routeEpoch ?? ""}\u0000${routeRoot ?? ""}`;
 
   const [tree, setTree] = useState<FileTreeNode[]>([]);
   // A ref mirror of the current tree — lets the optimistic path snapshot the
@@ -597,6 +615,7 @@ export function useSandboxFiles(
       const listRequests = [rootPath, ...frontierPaths].map((path) => ({
         path,
         depth: 1,
+        ...(route ? { route } : {}),
       }));
       // Root plus the bounded repository frontier share one API request, one
       // direct holder, and one provider attach. The old per-directory fan-out
@@ -677,7 +696,7 @@ export function useSandboxFiles(
       if (refreshGenerationRef.current === generation) setGitLoading(false);
       if (refreshAbortRef.current === refreshAbort) refreshAbortRef.current = null;
     }
-  }, [client, workspaceId, sessionId, rootPath, repoPaths, applyStatus]);
+  }, [client, workspaceId, sessionId, rootPath, repoPaths, route, applyStatus]);
 
   // Seed (or re-seed) the tree from a turn-end capture — the COLD/offline paint,
   // zero Channel-A calls. The tree index is workspace-relative (`treeIndex`); the
@@ -737,7 +756,7 @@ export function useSandboxFiles(
         const listed = await client.fsList(
           workspaceId,
           sessionId,
-          { path, depth: 1 },
+          { path, depth: 1, ...(route ? { route } : {}) },
           { signal: identitySignal },
         );
         if (identityGenerationRef.current !== identityGeneration) return;
@@ -757,7 +776,7 @@ export function useSandboxFiles(
         }
       }
     },
-    [client, workspaceId, sessionId, capture, source, applyStatus],
+    [client, workspaceId, sessionId, capture, source, route, applyStatus],
   );
 
   const readFile = useCallback(
@@ -850,9 +869,14 @@ export function useSandboxFiles(
         }
         throw new Error("Captured file download failed after refreshing its URL.");
       }
-      return await client.fsRead(workspaceId, sessionId, { path }, { signal });
+      return await client.fsRead(
+        workspaceId,
+        sessionId,
+        { path, ...(route ? { route } : {}) },
+        { signal },
+      );
     },
-    [client, workspaceId, sessionId, capture, source],
+    [client, workspaceId, sessionId, capture, source, route],
   );
 
   // TARGETED reconcile of a single directory — re-list ONE parent at depth 1 and
@@ -874,7 +898,12 @@ export function useSandboxFiles(
       // visible to update; they re-list fresh on the next expand).
       if (!parentIsLoaded(treeRef.current, path, rootPath)) return;
       try {
-        const listed = await client.fsList(workspaceId, sessionId, { path, depth: 1 }, { signal });
+        const listed = await client.fsList(
+          workspaceId,
+          sessionId,
+          { path, depth: 1, ...(route ? { route } : {}) },
+          { signal },
+        );
         if (identityGenerationRef.current !== identityGeneration) return;
         const children = (listed.root.children ?? []).map((node) => fsNodeToTree(node));
         if (path === normalizeRoot(rootPath)) {
@@ -892,7 +921,7 @@ export function useSandboxFiles(
         // root-refresh here (that would collapse the tree the user is working in).
       }
     },
-    [client, workspaceId, sessionId, rootPath, applyStatus],
+    [client, workspaceId, sessionId, rootPath, route, applyStatus],
   );
 
   // Reconcile the visible directory frontier through bounded batch requests.
@@ -915,7 +944,13 @@ export function useSandboxFiles(
           const listed = await client.fsListBatch(
             workspaceId,
             sessionId,
-            { requests: chunk.map((path) => ({ path, depth: 1 })) },
+            {
+              requests: chunk.map((path) => ({
+                path,
+                depth: 1,
+                ...(route ? { route } : {}),
+              })),
+            },
             { signal },
           );
           if (identityGenerationRef.current !== identityGeneration) return;
@@ -943,7 +978,7 @@ export function useSandboxFiles(
         }
       }
     },
-    [client, workspaceId, sessionId, rootPath, applyStatus],
+    [client, workspaceId, sessionId, rootPath, route, applyStatus],
   );
 
   // Run a Channel-A op behind an OPTIMISTIC tree edit. `apply` splices the change
@@ -1027,7 +1062,7 @@ export function useSandboxFiles(
             const live = await client.fsRead(
               workspaceId,
               sessionId,
-              { path },
+              { path, ...(route ? { route } : {}) },
               { signal: identitySignal },
             );
             if (identityGenerationRef.current !== identityGeneration) {
@@ -1046,12 +1081,13 @@ export function useSandboxFiles(
             path,
             content,
             overwrite: true,
+            ...(route ? { route } : {}),
           });
         },
         exists ? [] : [parent],
       );
     },
-    [client, workspaceId, sessionId, tree, rootPath, runOptimistic],
+    [client, workspaceId, sessionId, tree, rootPath, route, runOptimistic],
   );
 
   const createFile = useCallback(
@@ -1072,11 +1108,12 @@ export function useSandboxFiles(
             path,
             content: "",
             overwrite: false,
+            ...(route ? { route } : {}),
           }),
         [parent],
       );
     },
-    [client, workspaceId, sessionId, rootPath, runOptimistic],
+    [client, workspaceId, sessionId, rootPath, route, runOptimistic],
   );
 
   const createDir = useCallback(
@@ -1094,11 +1131,16 @@ export function useSandboxFiles(
       await runOptimistic(
         "create folder",
         (nodes) => insertNode(nodes, parent, node, rootPath),
-        () => client.fsMkdir(workspaceId, sessionId, { path, recursive: true }),
+        () =>
+          client.fsMkdir(workspaceId, sessionId, {
+            path,
+            recursive: true,
+            ...(route ? { route } : {}),
+          }),
         [parent],
       );
     },
-    [client, workspaceId, sessionId, rootPath, runOptimistic],
+    [client, workspaceId, sessionId, rootPath, route, runOptimistic],
   );
 
   const deleteEntry = useCallback(
@@ -1107,11 +1149,16 @@ export function useSandboxFiles(
       await runOptimistic(
         "delete",
         (nodes) => removeNode(nodes, path, rootPath),
-        () => client.fsDelete(workspaceId, sessionId, { path, recursive }),
+        () =>
+          client.fsDelete(workspaceId, sessionId, {
+            path,
+            recursive,
+            ...(route ? { route } : {}),
+          }),
         [parentWithinTree(path, rootPath)],
       );
     },
-    [client, workspaceId, sessionId, rootPath, runOptimistic],
+    [client, workspaceId, sessionId, rootPath, route, runOptimistic],
   );
 
   const moveEntry = useCallback(
@@ -1133,11 +1180,12 @@ export function useSandboxFiles(
             path,
             newPath,
             overwrite: opts?.overwrite ?? false,
+            ...(route ? { route } : {}),
           }),
         to === from ? [from] : [from, to],
       );
     },
-    [client, workspaceId, sessionId, rootPath, runOptimistic],
+    [client, workspaceId, sessionId, rootPath, route, runOptimistic],
   );
 
   // Initial paint + reset on identity change. Source selection:

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

@@ -1,4 +1,9 @@
-import type { SessionEvent, SessionStatus, StreamConnectionState } from "@opengeni/sdk";
+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";
@@ -69,10 +74,10 @@ export type UseSessionEventsResult = {
   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 = 255;
 const INITIAL_FETCH_CAP = 1;
 const OLDER_GROUP_TARGET = 32;
 const OLDER_FETCH_CAP = 2;
@@ -80,7 +85,19 @@ 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();
@@ -172,6 +189,7 @@ 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);
@@ -218,6 +236,7 @@ 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
@@ -229,16 +248,35 @@ export function useSessionEvents(
       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;
     streamAbortRef.current = controller;
@@ -309,6 +347,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 = boundBrowserSessionEventWindow([...current.events, ...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
@@ -316,9 +404,10 @@ 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()) {
@@ -425,6 +514,8 @@ export function useSessionEvents(
     workspaceId,
     sessionId,
     after,
+    enabled,
+    pageLive,
     streamEnabled,
     fullReplay,
     streamKey,
@@ -459,7 +550,7 @@ export function useSessionEvents(
         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,
           });
@@ -564,7 +655,7 @@ export function useSessionEvents(
     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,
       });
@@ -633,7 +724,7 @@ export function useSessionEvents(
     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,
       });
@@ -1083,6 +1174,70 @@ function observeSessionStatus(
   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)
+    .map(boundBrowserLegacyEvent);
+  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 = {
   events: SessionEvent[];
   oldestSequence: number | null;
@@ -1106,6 +1261,7 @@ async function loadEventWindow(
     pageSize: number;
     targetGroups: number;
     maxFetches: number;
+    boundaryPageCap?: number;
     signal?: AbortSignal;
   },
 ): Promise<LoadedEventWindow> {
@@ -1140,14 +1296,13 @@ 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,
@@ -1378,13 +1533,13 @@ function maxResumeSequenceOrNull(events: readonly SessionEvent[]): number | null
 }
 
 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 asRecord(value: unknown): Record<string, unknown> {
-  return value && typeof value === "object" ? (value as Record<string, unknown>) : {};
+  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 {

package/src/hooks/use-workspace-edit.ts

@@ -1,4 +1,5 @@
-import { useCallback, useEffect, useRef, useState } from "react";
+import type { FileSystemRouteIdentity } from "@opengeni/sdk";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { useOpenGeni, type ClientOverride } from "../provider";
 import { sandboxAcceptsLiveIo } from "../lib/sandbox-liveness";
 
@@ -39,6 +40,9 @@ export type UseWorkspaceEditOptions = ClientOverride & {
   path?: string | null | undefined;
   /** The capture-served content loaded into the editor — the flush base (C2). */
   baseContent?: string | null | undefined;
+  /** Exact capability identity for the selected filesystem route. A route/root
+   * change discards the buffered edit and makes stale flushes fail retryably. */
+  route?: FileSystemRouteIdentity | undefined;
   /** `capabilities.liveness` — "warm" | "draining" | "cold". Drives the flush. */
   liveness?: string | undefined;
   /** True while the host is actively warming the box (attach in flight, not warm
@@ -95,9 +99,18 @@ export function useWorkspaceEdit(
   const { client, workspaceId } = useOpenGeni(options);
   const path = options.path ?? null;
   const baseContent = options.baseContent ?? null;
+  const routeEpoch = options.route?.epoch;
+  const routeRoot = options.route?.root;
+  const route = useMemo<FileSystemRouteIdentity | undefined>(
+    () =>
+      routeEpoch !== undefined && routeRoot !== undefined
+        ? { epoch: routeEpoch, root: routeRoot }
+        : undefined,
+    [routeEpoch, routeRoot],
+  );
   const live = isLive(options.liveness);
   const offline = options.offline === true;
-  const identityKey = `${workspaceId}\u0000${sessionId ?? ""}\u0000${path ?? ""}`;
+  const identityKey = `${workspaceId}\u0000${sessionId ?? ""}\u0000${path ?? ""}\u0000${routeEpoch ?? ""}\u0000${routeRoot ?? ""}`;
 
   const [buffer, setBuffer] = useState<string | null>(null);
   const [wantsWarm, setWantsWarm] = useState(false);
@@ -178,7 +191,7 @@ export function useWorkspaceEdit(
           const liveRead = await client.fsRead(
             workspaceId,
             sessionId,
-            { path },
+            { path, ...(route ? { route } : {}) },
             { signal: readAbort.signal },
           );
           if (readAbortRef.current === readAbort) readAbortRef.current = null;
@@ -190,7 +203,12 @@ export function useWorkspaceEdit(
             return;
           }
         }
-        await client.fsWrite(workspaceId, sessionId, { path, content, overwrite: true });
+        await client.fsWrite(workspaceId, sessionId, {
+          path,
+          content,
+          overwrite: true,
+          ...(route ? { route } : {}),
+        });
         if (identityGenerationRef.current !== identityGeneration) return;
         setConflict(null);
         setFlush("flushed");
@@ -207,7 +225,7 @@ export function useWorkspaceEdit(
         }
       }
     },
-    [client, workspaceId, sessionId, path, baseContent, stateIdentity, identityKey],
+    [client, workspaceId, sessionId, path, baseContent, route, stateIdentity, identityKey],
   );
 
   // Auto-flush once the box is warm and a buffer is pending (the wake completed).