@opengeni/react 3.5.1-canary.0 → 3.7.0-canary.1

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-background-commands.ts

@@ -1,5 +1,5 @@
 import type { SessionBackgroundCommand } from "@opengeni/sdk";
-import { useCallback } from "react";
+import { useCallback, useEffect, useRef } from "react";
 
 import { useOpenGeni, type ClientOverride } from "../provider";
 import { usePolledValue } from "./internal";
@@ -23,28 +23,39 @@ export function useSessionBackgroundCommands(
 ): UseSessionBackgroundCommandsResult {
   const { client, workspaceId } = useOpenGeni(options);
   const enabled = (options.enabled ?? true) && Boolean(sessionId);
-  const load = useCallback(async () => {
-    if (!sessionId) return { commands: [] };
-    if (!client.listSessionBackgroundCommands) {
-      throw new Error("The configured OpenGeni client does not support background commands");
-    }
-    return await client.listSessionBackgroundCommands(workspaceId, sessionId);
-  }, [client, workspaceId, sessionId]);
+  const load = useCallback(
+    async (signal?: AbortSignal) => {
+      if (!sessionId) return { commands: [] };
+      if (!client.listSessionBackgroundCommands) {
+        throw new Error("The configured OpenGeni client does not support background commands");
+      }
+      return await client.listSessionBackgroundCommands(workspaceId, sessionId, { signal });
+    },
+    [client, workspaceId, sessionId],
+  );
   const state = usePolledValue(load, {
     enabled,
     pollIntervalMs: options.pollIntervalMs,
   });
   const refresh = state.refresh;
+  const generation = useRef(0);
+  useEffect(() => {
+    generation.current += 1;
+    return () => {
+      generation.current += 1;
+    };
+  }, [client, workspaceId, sessionId, enabled]);
   const cancel = useCallback(
     async (commandId: string): Promise<void> => {
       if (!sessionId) return;
       if (!client.cancelSessionBackgroundCommand) {
         throw new Error("The configured OpenGeni client does not support background commands");
       }
+      const ticket = generation.current;
       await client.cancelSessionBackgroundCommand(workspaceId, sessionId, commandId);
-      await refresh();
+      if (enabled && ticket === generation.current) await refresh();
     },
-    [client, workspaceId, sessionId, refresh],
+    [client, workspaceId, sessionId, refresh, enabled],
   );
   return {
     commands: state.data?.commands ?? [],

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

@@ -74,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 = 1000;
 const INITIAL_FETCH_CAP = 1;
 const OLDER_GROUP_TARGET = 32;
 const OLDER_FETCH_CAP = 2;
@@ -85,13 +85,16 @@ 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 = 5_000;
+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;
@@ -190,6 +193,7 @@ export function useSessionEvents(
   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;
@@ -202,6 +206,21 @@ export function useSessionEvents(
   // new stream identity cannot expose the previous session's event log.
   const [stateStreamKey, setStateStreamKey] = useState(streamKey);
 
+  // Reopening SSE after a prepend must not cancel the next history page.
+  // Navigation belongs to the session/client lifetime, not the transport.
+  useEffect(() => {
+    navigationGenerationRef.current += 1;
+    loadingOlderRef.current = false;
+    loadingNewerRef.current = false;
+    loadingOldestRef.current = 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.
@@ -240,10 +259,6 @@ export function useSessionEvents(
     // 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
@@ -387,19 +402,10 @@ export function useSessionEvents(
             }
           } else if (plan.kind === "reload") {
             // A large/complex missed window would make the foreground timeline
-            // and pinned camera chase many rapid commits. Clear once so the
-            // normal bottom-anchored bulk-load path can paint one latest tail.
-            eventWindowRef.current = EMPTY_EVENT_WINDOW;
-            oldestSequenceRef.current = null;
-            newestSequenceRef.current = null;
-            hasOlderRef.current = false;
-            hasNewerRef.current = false;
+            // 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;
-            streamResumeSequenceRef.current = after;
-            setEventWindow(EMPTY_EVENT_WINDOW);
-            setHasOlder(false);
-            setHasNewer(false);
-            setInitialLoading(true);
             setError(null);
           }
         }
@@ -410,9 +416,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()) {
@@ -420,6 +427,16 @@ export function useSessionEvents(
           }
           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;
           oldestSequenceRef.current = retained.events[0]?.sequence ?? window.oldestSequence;
           newestSequenceRef.current =
@@ -548,18 +565,18 @@ export function useSessionEvents(
           setHasOlder(false);
           return false;
         }
-        const generation = generationRef.current;
+        const generation = navigationGenerationRef.current;
         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,
           });
-          if (generationRef.current !== generation) {
+          if (navigationGenerationRef.current !== generation) {
             return false;
           }
           if (window.events.length === 0) {
@@ -640,7 +657,7 @@ export function useSessionEvents(
           published = true;
           return olderStillAvailable;
         } finally {
-          if (!published) {
+          if (!published && navigationGenerationRef.current === generation) {
             loadingOlderRef.current = false;
             setLoadingOlder(false);
           }
@@ -653,18 +670,18 @@ export function useSessionEvents(
     if (!sessionId || navigationBusy() || !hasOlderRef.current) {
       return false;
     }
-    const generation = generationRef.current;
+    const generation = navigationGenerationRef.current;
     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,
       });
-      if (generationRef.current !== generation) {
+      if (navigationGenerationRef.current !== generation) {
         return false;
       }
       if (window.events.length === 0) {
@@ -705,7 +722,7 @@ export function useSessionEvents(
       published = true;
       return newer;
     } finally {
-      if (!published) {
+      if (!published && navigationGenerationRef.current === generation) {
         loadingOldestRef.current = false;
         setLoadingOldest(false);
       }
@@ -722,18 +739,18 @@ export function useSessionEvents(
       setHasNewer(false);
       return false;
     }
-    const generation = generationRef.current;
+    const generation = navigationGenerationRef.current;
     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,
       });
-      if (generationRef.current !== generation) {
+      if (navigationGenerationRef.current !== generation) {
         return false;
       }
       if (window.events.length === 0) {
@@ -805,7 +822,7 @@ export function useSessionEvents(
       published = true;
       return newer;
     } finally {
-      if (!published) {
+      if (!published && navigationGenerationRef.current === generation) {
         loadingNewerRef.current = false;
         setLoadingNewer(false);
       }
@@ -1266,6 +1283,7 @@ async function loadEventWindow(
     pageSize: number;
     targetGroups: number;
     maxFetches: number;
+    boundaryPageCap?: number;
     signal?: AbortSignal;
   },
 ): Promise<LoadedEventWindow> {
@@ -1300,14 +1318,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,

package/src/hooks/use-session.ts

@@ -38,6 +38,10 @@ export function isTitleEvent(event: Pick<SessionEvent, "type">): boolean {
   return event.type === "session.title_set";
 }
 
+function isSessionDetailEvent(event: Pick<SessionEvent, "type">): boolean {
+  return isTitleEvent(event) || event.type.startsWith("session.command.");
+}
+
 /** Fetch one session (with optional polling), live-patching its title on `session.title_set`. */
 export function useSession(
   sessionId: string | null | undefined,
@@ -99,10 +103,27 @@ export function useSession(
     [base, override],
   );
 
+  const sharedEvents = options.events;
+
   // Live-patch the title on auto (agent) + cross-client (user/agent) renames so
   // the UI reflects the new title without polling or a full re-fetch.
   const onTitleEvent = useCallback(
     (event: SessionEvent) => {
+      // Reconciliation emits only the last matching member of a shared batch.
+      // A later title must not hide an earlier command activity change.
+      if (
+        sharedEvents?.some(
+          (item) =>
+            item.sessionId === sessionId &&
+            item.type.startsWith("session.command.") &&
+            item.sequence > (base?.lastSequence ?? -1),
+        )
+      ) {
+        void refresh();
+      } else if (event.type.startsWith("session.command.")) {
+        if (!base || event.sequence > base.lastSequence) void refresh();
+        return;
+      }
       // The fetched session row is the authoritative title projection through
       // lastSequence. Shared feeds may replay that historical tail after the
       // fetch; applying it would undo a row-only migration quarantine. Only an
@@ -122,9 +143,9 @@ export function useSession(
         return { ...next, title, titleSource: source };
       });
     },
-    [base],
+    [base, refresh, sharedEvents, sessionId],
   );
-  useSessionEventTrigger(client, workspaceId, sessionId, isTitleEvent, onTitleEvent, {
+  useSessionEventTrigger(client, workspaceId, sessionId, isSessionDetailEvent, onTitleEvent, {
     enabled,
     ...(options.events !== undefined ? { events: options.events } : {}),
   });

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).