@opengeni/react 1.0.1 → 1.0.2-canary.37191796234001

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

@@ -1,4 +1,5 @@
 import type {
+  FileSystemRouteIdentity,
   FsChangedPayload,
   FsReadResponse,
   FsTreeNode,
@@ -65,7 +66,8 @@ export type SandboxWriteFileOptions = {
 /** A node in the Pierre file tree. `children === undefined` ⇒ an unexpanded dir
  *  (lazy treeMode); `children: []` ⇒ an expanded-but-empty dir. */
 export type FileTreeNode = {
-  path: string; // workspace-relative POSIX
+  /** Opaque path returned by the selected target's FileSystem boundary. */
+  path: string;
   name: string;
   kind: "file" | "dir";
   children?: FileTreeNode[] | undefined;
@@ -83,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. */
@@ -162,16 +167,25 @@ export type SandboxFilesGitSummary = {
 };
 
 function normalizeRoot(root: string): string {
-  const normalized = root
-    .replaceAll("\\", "/")
-    .replace(/^\.\/+/, "")
-    .replace(/\/+$/, "");
+  const slashNormalized = root.replaceAll("\\", "/").replace(/^\.\/+/, "");
+  if (slashNormalized === "/") return "/";
+  const normalized = slashNormalized.replace(/\/+$/, "");
   return normalized === "." ? "" : normalized;
 }
 
-function qualifyStatusPath(root: string, path: string): string {
+function isAbsoluteTreePath(path: string): boolean {
+  return path.startsWith("/") || /^[A-Za-z]:\//u.test(path);
+}
+
+function joinTreeRoot(root: string, path: string): string {
+  if (!root || isAbsoluteTreePath(path)) return path;
+  return root === "/" ? `/${path}` : `${root}/${path}`;
+}
+
+function qualifyStatusPath(root: string, path: string, treeRoot: string): string {
   const normalized = normalizeRoot(root);
-  return normalized ? `${normalized}/${path}` : path;
+  const workspaceRelative = joinTreeRoot(normalized, path);
+  return joinTreeRoot(normalizeRoot(treeRoot), workspaceRelative);
 }
 
 function summarizeStatuses(
@@ -194,6 +208,11 @@ function parentOf(path: string): string {
   return i <= 0 ? "" : path.slice(0, i);
 }
 
+function parentWithinTree(path: string, rootPath: string): string {
+  const parent = parentOf(path);
+  return parent === "" && normalizeRoot(rootPath) === "/" && path.startsWith("/") ? "/" : parent;
+}
+
 /** The leaf name of a POSIX path. */
 function leafOf(path: string): string {
   const i = path.lastIndexOf("/");
@@ -282,33 +301,23 @@ function findNodeByPath(nodes: FileTreeNode[], path: string): FileTreeNode | und
   return undefined;
 }
 
-/** Root plus every directory whose children are currently loaded. Re-listing
- * this small visible frontier refreshes agent shell edits without expanding or
- * traversing hidden directories. */
-function loadedDirectoryPaths(nodes: FileTreeNode[]): string[] {
-  const paths = [""];
-  const walk = (list: FileTreeNode[]) => {
-    for (const node of list) {
-      if (node.kind !== "dir" || node.children === undefined) continue;
-      paths.push(node.path);
-      walk(node.children);
-    }
-  };
-  walk(nodes);
-  return paths;
-}
+const FS_LIST_BATCH_REQUEST_LIMIT = 16;
 
 /** Repository paths are capability-advertised and therefore safe to use as a
  * bounded initial lazy-tree frontier. Listing their ancestors concurrently with
  * the root avoids a root → repositories → repo remote waterfall. */
 function initialDirectoryFrontier(rootPath: string, repoPaths: readonly string[]): string[] {
-  const rootParts = normalizeRoot(rootPath).split("/").filter(Boolean);
+  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 parts = normalizeRoot(repoPath).split("/").filter(Boolean);
+    const canonicalRepoPath = joinTreeRoot(root, normalizeRoot(repoPath));
+    const parts = canonicalRepoPath.split("/").filter(Boolean);
     if (rootParts.some((part, index) => parts[index] !== part)) continue;
     for (let depth = rootParts.length + 1; depth <= parts.length; depth += 1) {
-      paths.add(parts.slice(0, depth).join("/"));
+      const path = parts.slice(0, depth).join("/");
+      paths.add(`${rootPrefix}${path}`);
     }
   }
   // A workspace with hundreds of repositories should remain lazy. This still
@@ -333,8 +342,8 @@ function initialDirectoryFrontier(rootPath: string, repoPaths: readonly string[]
 
 /** True when `parent` is the root ("") or a dir node that is actually present in
  *  the loaded tree (so an insert/remove there would be visible). */
-function parentIsLoaded(nodes: FileTreeNode[], parent: string): boolean {
-  if (parent === "") return true;
+function parentIsLoaded(nodes: FileTreeNode[], parent: string, rootPath = ""): boolean {
+  if (parent === normalizeRoot(rootPath)) return true;
   const node = findNodeByPath(nodes, parent);
   return Boolean(node && node.kind === "dir" && node.children !== undefined);
 }
@@ -342,8 +351,13 @@ function parentIsLoaded(nodes: FileTreeNode[], parent: string): boolean {
 /** Insert `child` under `parent` (immutably), keeping siblings sorted. A no-op
  *  (returns the same array) when the parent isn't a loaded dir or the child
  *  already exists. */
-function insertNode(nodes: FileTreeNode[], parent: string, child: FileTreeNode): FileTreeNode[] {
-  if (parent === "") {
+function insertNode(
+  nodes: FileTreeNode[],
+  parent: string,
+  child: FileTreeNode,
+  rootPath = "",
+): FileTreeNode[] {
+  if (parent === normalizeRoot(rootPath)) {
     if (nodes.some((n) => n.path === child.path)) return nodes;
     return sortNodes([...nodes, child]);
   }
@@ -354,16 +368,16 @@ function insertNode(nodes: FileTreeNode[], parent: string, child: FileTreeNode):
       return { ...node, children: sortNodes([...node.children, child]) };
     }
     if (node.kind === "dir" && node.children && parent.startsWith(`${node.path}/`)) {
-      return { ...node, children: insertNode(node.children, parent, child) };
+      return { ...node, children: insertNode(node.children, parent, child, rootPath) };
     }
     return node;
   });
 }
 
 /** Remove the node at `path` (immutably). No-op when it isn't in the tree. */
-function removeNode(nodes: FileTreeNode[], path: string): FileTreeNode[] {
-  const parent = parentOf(path);
-  if (parent === "") {
+function removeNode(nodes: FileTreeNode[], path: string, rootPath = ""): FileTreeNode[] {
+  const parent = parentWithinTree(path, rootPath);
+  if (parent === normalizeRoot(rootPath)) {
     if (!nodes.some((n) => n.path === path)) return nodes;
     return nodes.filter((n) => n.path !== path);
   }
@@ -376,7 +390,7 @@ function removeNode(nodes: FileTreeNode[], path: string): FileTreeNode[] {
       };
     }
     if (node.kind === "dir" && node.children && parent.startsWith(`${node.path}/`)) {
-      return { ...node, children: removeNode(node.children, path) };
+      return { ...node, children: removeNode(node.children, path, rootPath) };
     }
     return node;
   });
@@ -486,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");
@@ -498,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
@@ -527,9 +550,9 @@ export function useSandboxFiles(
   const lastSeqRef = useRef(0);
   const pendingParentsRef = useRef<Set<string>>(new Set());
   const pendingGitRef = useRef(false);
-  const pendingAgentToolRef = useRef(false);
+  const eventReconcileInFlightRef = useRef<Promise<void> | null>(null);
+  const eventReconcilePendingRef = useRef(false);
   const debounceRef = useRef<ReturnType<typeof setTimeout> | null>(null);
-  const lastCommandRefreshAtRef = useRef(0);
 
   // ── Self-emitted fs.changed de-dupe ───────────────────────────────────────
   // Every one of OUR mutations emits an `fs.changed` event back on the live log
@@ -584,34 +607,16 @@ export function useSandboxFiles(
     setGitLoading(true);
     setError(null);
     try {
-      // Start the optional Git tint and the actual directory listing together.
-      // A remote status read must never block the first useful file-tree paint.
+      // Paint the useful file tree before the optional Git tint. Separate remote
+      // requests for one Modal box are deliberately serialized by the API; firing
+      // both here only made the Git request contend with the file request during
+      // cold starts.
       const frontierPaths = initialDirectoryFrontier(rootPath, repoPaths);
       const listRequests = [rootPath, ...frontierPaths].map((path) => ({
         path,
         depth: 1,
+        ...(route ? { route } : {}),
       }));
-      const statusPromise =
-        repoPaths.length > 0
-          ? client
-              .gitReadBatch(
-                workspaceId,
-                sessionId,
-                {
-                  requests: repoPaths.map((root) => ({
-                    status: { path: root },
-                  })),
-                },
-                { signal: refreshAbort.signal },
-              )
-              .then((batch) =>
-                batch.results.map((result, index) => ({
-                  root: repoPaths[index] ?? "",
-                  status: result.status,
-                })),
-              )
-              .catch(() => null)
-          : Promise.resolve([]);
       // Root plus the bounded repository frontier share one API request, one
       // direct holder, and one provider attach. The old per-directory fan-out
       // paid that fixed control-plane cost up to nine times on every Files open.
@@ -644,7 +649,27 @@ export function useSandboxFiles(
       setSource("live");
       setLoading(false);
 
-      const statuses = await statusPromise;
+      const statuses =
+        repoPaths.length > 0
+          ? await client
+              .gitReadBatch(
+                workspaceId,
+                sessionId,
+                {
+                  requests: repoPaths.map((root) => ({
+                    status: { path: root },
+                  })),
+                },
+                { signal: refreshAbort.signal },
+              )
+              .then((batch) =>
+                batch.results.map((result, index) => ({
+                  root: repoPaths[index] ?? "",
+                  status: result.status,
+                })),
+              )
+              .catch(() => null)
+          : [];
       if (refreshGenerationRef.current !== generation) return;
       if (statuses) {
         const overlay = new Map<string, FileTreeStatus>();
@@ -652,7 +677,7 @@ export function useSandboxFiles(
           for (const file of status.files) {
             const code = file.worktree ?? file.index;
             const mapped = code ? GIT_STATUS_TO_TREE[code] : undefined;
-            if (mapped) overlay.set(qualifyStatusPath(root, file.path), mapped);
+            if (mapped) overlay.set(qualifyStatusPath(root, file.path, rootPath), mapped);
           }
         }
         statusRef.current = overlay;
@@ -671,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
@@ -731,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;
@@ -751,7 +776,7 @@ export function useSandboxFiles(
         }
       }
     },
-    [client, workspaceId, sessionId, capture, source, applyStatus],
+    [client, workspaceId, sessionId, capture, source, route, applyStatus],
   );
 
   const readFile = useCallback(
@@ -844,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
@@ -866,13 +896,19 @@ export function useSandboxFiles(
         : identitySignal;
       // Skip parents that aren't currently loaded/expanded in the tree (nothing
       // visible to update; they re-list fresh on the next expand).
-      if (!parentIsLoaded(treeRef.current, path)) return;
+      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 === "") setTree((prev) => applyStatus(mergeRootChildren(prev, children)));
-        else
+        if (path === normalizeRoot(rootPath)) {
+          setTree((prev) => applyStatus(mergeRootChildren(prev, children)));
+        } else
           setTree((prev) => {
             const existing = findNodeByPath(prev, path);
             const merged = existing?.children
@@ -885,7 +921,64 @@ export function useSandboxFiles(
         // root-refresh here (that would collapse the tree the user is working in).
       }
     },
-    [client, workspaceId, sessionId, applyStatus],
+    [client, workspaceId, sessionId, rootPath, route, applyStatus],
+  );
+
+  // Reconcile the visible directory frontier through bounded batch requests.
+  // One tool completion can affect several expanded directories; issuing one
+  // provider request per directory created a self-inflicted lock convoy.
+  const reconcilePaths = useCallback(
+    async (requestedPaths: readonly string[], requestSignal?: AbortSignal) => {
+      if (!sessionId) return;
+      const identityGeneration = identityGenerationRef.current;
+      const identitySignal = identityAbortRef.current.signal;
+      const signal = requestSignal
+        ? AbortSignal.any([identitySignal, requestSignal])
+        : identitySignal;
+      const paths = [...new Set(requestedPaths)].filter((path) =>
+        parentIsLoaded(treeRef.current, path, rootPath),
+      );
+      for (let offset = 0; offset < paths.length; offset += FS_LIST_BATCH_REQUEST_LIMIT) {
+        const chunk = paths.slice(offset, offset + FS_LIST_BATCH_REQUEST_LIMIT);
+        try {
+          const listed = await client.fsListBatch(
+            workspaceId,
+            sessionId,
+            {
+              requests: chunk.map((path) => ({
+                path,
+                depth: 1,
+                ...(route ? { route } : {}),
+              })),
+            },
+            { signal },
+          );
+          if (identityGenerationRef.current !== identityGeneration) return;
+          setTree((previous) => {
+            let next = previous;
+            for (const [index, path] of chunk.entries()) {
+              const result = listed.results[index];
+              if (!result) continue;
+              const children = (result.root.children ?? []).map((node) => fsNodeToTree(node));
+              if (path === normalizeRoot(rootPath)) {
+                next = mergeRootChildren(next, children);
+              } else {
+                const existing = findNodeByPath(next, path);
+                const merged = existing?.children
+                  ? mergeChildren(existing.children, children)
+                  : children;
+                next = replaceChildren(next, path, merged);
+              }
+            }
+            return applyStatus(next);
+          });
+        } catch {
+          // Reconciliation is best-effort. Preserve the current visible tree and
+          // let the next real event or explicit refresh reconcile it.
+        }
+      }
+    },
+    [client, workspaceId, sessionId, rootPath, route, applyStatus],
   );
 
   // Run a Channel-A op behind an OPTIMISTIC tree edit. `apply` splices the change
@@ -950,7 +1043,7 @@ export function useSandboxFiles(
       if (!sessionId) throw new Error("no session");
       const identityGeneration = identityGenerationRef.current;
       const identitySignal = identityAbortRef.current.signal;
-      const parent = parentOf(path);
+      const parent = parentWithinTree(path, rootPath);
       // Splice a new file node in immediately ONLY when the path doesn't already
       // exist in a loaded parent (an editor SAVE to an existing file mutates no
       // tree shape — just content — so it needs no optimistic node, no reconcile).
@@ -963,13 +1056,13 @@ export function useSandboxFiles(
       };
       return await runOptimistic(
         "write",
-        (nodes) => (exists ? nodes : insertNode(nodes, parent, node)),
+        (nodes) => (exists ? nodes : insertNode(nodes, parent, node, rootPath)),
         async () => {
           if (!writeOptions.force && writeOptions.expectedContent !== undefined) {
             const live = await client.fsRead(
               workspaceId,
               sessionId,
-              { path },
+              { path, ...(route ? { route } : {}) },
               { signal: identitySignal },
             );
             if (identityGenerationRef.current !== identityGeneration) {
@@ -988,18 +1081,19 @@ export function useSandboxFiles(
             path,
             content,
             overwrite: true,
+            ...(route ? { route } : {}),
           });
         },
         exists ? [] : [parent],
       );
     },
-    [client, workspaceId, sessionId, tree, runOptimistic],
+    [client, workspaceId, sessionId, tree, rootPath, route, runOptimistic],
   );
 
   const createFile = useCallback(
     async (path: string): Promise<void> => {
       if (!sessionId) throw new Error("no session");
-      const parent = parentOf(path);
+      const parent = parentWithinTree(path, rootPath);
       const node: FileTreeNode = {
         path,
         name: leafOf(path),
@@ -1008,23 +1102,24 @@ export function useSandboxFiles(
       };
       await runOptimistic(
         "create file",
-        (nodes) => insertNode(nodes, parent, node),
+        (nodes) => insertNode(nodes, parent, node, rootPath),
         () =>
           client.fsWrite(workspaceId, sessionId, {
             path,
             content: "",
             overwrite: false,
+            ...(route ? { route } : {}),
           }),
         [parent],
       );
     },
-    [client, workspaceId, sessionId, runOptimistic],
+    [client, workspaceId, sessionId, rootPath, route, runOptimistic],
   );
 
   const createDir = useCallback(
     async (path: string): Promise<void> => {
       if (!sessionId) throw new Error("no session");
-      const parent = parentOf(path);
+      const parent = parentWithinTree(path, rootPath);
       // A freshly-created dir is empty + expanded: children:[] (not undefined, so
       // it doesn't show the lazy-expand marker over a dir we KNOW is empty).
       const node: FileTreeNode = {
@@ -1035,12 +1130,17 @@ export function useSandboxFiles(
       };
       await runOptimistic(
         "create folder",
-        (nodes) => insertNode(nodes, parent, node),
-        () => client.fsMkdir(workspaceId, sessionId, { path, recursive: true }),
+        (nodes) => insertNode(nodes, parent, node, rootPath),
+        () =>
+          client.fsMkdir(workspaceId, sessionId, {
+            path,
+            recursive: true,
+            ...(route ? { route } : {}),
+          }),
         [parent],
       );
     },
-    [client, workspaceId, sessionId, runOptimistic],
+    [client, workspaceId, sessionId, rootPath, route, runOptimistic],
   );
 
   const deleteEntry = useCallback(
@@ -1048,19 +1148,24 @@ export function useSandboxFiles(
       if (!sessionId) throw new Error("no session");
       await runOptimistic(
         "delete",
-        (nodes) => removeNode(nodes, path),
-        () => client.fsDelete(workspaceId, sessionId, { path, recursive }),
-        [parentOf(path)],
+        (nodes) => removeNode(nodes, path, rootPath),
+        () =>
+          client.fsDelete(workspaceId, sessionId, {
+            path,
+            recursive,
+            ...(route ? { route } : {}),
+          }),
+        [parentWithinTree(path, rootPath)],
       );
     },
-    [client, workspaceId, sessionId, runOptimistic],
+    [client, workspaceId, sessionId, rootPath, route, runOptimistic],
   );
 
   const moveEntry = useCallback(
     async (path: string, newPath: string, opts?: { overwrite?: boolean }): Promise<void> => {
       if (!sessionId) throw new Error("no session");
-      const from = parentOf(path);
-      const to = parentOf(newPath);
+      const from = parentWithinTree(path, rootPath);
+      const to = parentWithinTree(newPath, rootPath);
       await runOptimistic(
         "move",
         (nodes) => {
@@ -1068,18 +1173,19 @@ export function useSandboxFiles(
           if (!moving) return nodes; // not loaded — let the reconcile pick it up
           // Re-path the moved subtree, drop it from its old parent, splice into new.
           const moved = repathNode(moving, path, newPath);
-          return insertNode(removeNode(nodes, path), to, moved);
+          return insertNode(removeNode(nodes, path, rootPath), to, moved, rootPath);
         },
         () =>
           client.fsMove(workspaceId, sessionId, {
             path,
             newPath,
             overwrite: opts?.overwrite ?? false,
+            ...(route ? { route } : {}),
           }),
         to === from ? [from] : [from, to],
       );
     },
-    [client, workspaceId, sessionId, runOptimistic],
+    [client, workspaceId, sessionId, rootPath, route, runOptimistic],
   );
 
   // Initial paint + reset on identity change. Source selection:
@@ -1107,14 +1213,14 @@ export function useSandboxFiles(
     const identityChanged = previousIdentityRef.current !== identityKey;
     previousIdentityRef.current = identityKey;
     if (identityChanged || !enabled) {
+      if (identityChanged) eventReconcileInFlightRef.current = null;
       identityAbortRef.current.abort();
       identityAbortRef.current = new AbortController();
       identityGenerationRef.current += 1;
       lastSeqRef.current = 0;
       pendingParentsRef.current = new Set();
       pendingGitRef.current = false;
-      pendingAgentToolRef.current = false;
-      lastCommandRefreshAtRef.current = 0;
+      eventReconcilePendingRef.current = false;
       if (debounceRef.current) {
         clearTimeout(debounceRef.current);
         debounceRef.current = null;
@@ -1155,6 +1261,7 @@ export function useSandboxFiles(
       refreshAbortRef.current = null;
       refreshGenerationRef.current += 1;
       eventReadAbortRef.current.abort();
+      eventReconcilePendingRef.current = false;
     };
   }, [
     enabled,
@@ -1196,7 +1303,7 @@ export function useSandboxFiles(
           for (const file of status.files) {
             const code = file.worktree ?? file.index;
             const mapped = code ? GIT_STATUS_TO_TREE[code] : undefined;
-            if (mapped) overlay.set(qualifyStatusPath(root, file.path), mapped);
+            if (mapped) overlay.set(qualifyStatusPath(root, file.path, rootPath), mapped);
           }
         }
         statusRef.current = overlay;
@@ -1208,9 +1315,47 @@ export function useSandboxFiles(
         if (identityGenerationRef.current === identityGeneration) setGitLoading(false);
       }
     },
-    [client, workspaceId, sessionId, repoPaths, applyStatus],
+    [client, workspaceId, sessionId, repoPaths, rootPath, applyStatus],
   );
 
+  const performEventReconcile = useCallback(async () => {
+    const parents = pendingParentsRef.current;
+    pendingParentsRef.current = new Set();
+    const wantGit = pendingGitRef.current;
+    pendingGitRef.current = false;
+    const signal = eventReadAbortRef.current.signal;
+    const paths = [...parents];
+
+    // File content is the primary Files-tab result. Reconcile it first, then add
+    // the optional Git tint through a second serial request. This matches the
+    // API's exact-provider serialization instead of making the two reads contend.
+    await reconcilePaths(paths, signal);
+    if (wantGit) await refreshGitOverlay(signal);
+  }, [reconcilePaths, refreshGitOverlay]);
+  const performEventReconcileRef = useRef(performEventReconcile);
+  performEventReconcileRef.current = performEventReconcile;
+  const reconcilePendingEvents = useCallback(async () => {
+    eventReconcilePendingRef.current = true;
+    const existing = eventReconcileInFlightRef.current;
+    if (existing) return await existing;
+    const identityGeneration = identityGenerationRef.current;
+    const run = (async () => {
+      while (
+        eventReconcilePendingRef.current &&
+        identityGenerationRef.current === identityGeneration
+      ) {
+        eventReconcilePendingRef.current = false;
+        await performEventReconcileRef.current();
+      }
+    })();
+    eventReconcileInFlightRef.current = run;
+    try {
+      await run;
+    } finally {
+      if (eventReconcileInFlightRef.current === run) eventReconcileInFlightRef.current = null;
+    }
+  }, []);
+
   // Auto-reconcile on fs/git change notifications — TARGETED, never a root
   // collapse-reload, and de-duped against our OWN mutations.
   //
@@ -1221,6 +1366,8 @@ export function useSandboxFiles(
   //     reconciles ONLY the affected parent directories (in place, expansion
   //     preserved). Bursts are debounced into a single reconcile pass.
   //   • A git.changed just re-tints (refreshes the status overlay) — no fs re-list.
+  //   • Generic command/tool output performs no provider reads. The canonical
+  //     turn-end capture refreshes the root once after the command burst settles.
   const events = options.events;
 
   useEffect(() => {
@@ -1238,12 +1385,11 @@ export function useSandboxFiles(
       }
       pendingParentsRef.current = new Set();
       pendingGitRef.current = false;
-      pendingAgentToolRef.current = false;
+      eventReconcilePendingRef.current = false;
       return;
     }
     let sawNew = false;
     let contentChanged = false;
-    let sawCommandDelta = false;
     for (const event of events) {
       if (event.sequence <= lastSeqRef.current) continue;
       if (event.type === "fs.changed") {
@@ -1256,8 +1402,10 @@ export function useSandboxFiles(
           continue;
         contentChanged = true;
         for (const change of payload.changes ?? []) {
-          pendingParentsRef.current.add(parentOf(change.path));
-          if (change.oldPath) pendingParentsRef.current.add(parentOf(change.oldPath));
+          pendingParentsRef.current.add(parentWithinTree(change.path, rootPath));
+          if (change.oldPath) {
+            pendingParentsRef.current.add(parentWithinTree(change.oldPath, rootPath));
+          }
         }
       } else if (event.type === "git.changed") {
         sawNew = true;
@@ -1273,73 +1421,27 @@ export function useSandboxFiles(
         )
           continue;
         pendingGitRef.current = true;
-      } else if (event.type === "agent.toolCall.output") {
-        // Agent shell/apply-patch writes do not necessarily pass through the
-        // structured FS service, so they may have no fs.changed notification.
-        // A completed tool is a bounded invalidation point: refresh only the
-        // currently-loaded directory frontier, never poll and never traverse a
-        // collapsed subtree.
-        sawNew = true;
-        contentChanged = true;
-        pendingAgentToolRef.current = true;
-        // Shell/apply-patch writes bypass the structured Git service too, so no
-        // git.changed event is guaranteed. Refresh the summary/tints alongside
-        // the visible tree frontier; both remote reads can run concurrently.
-        pendingGitRef.current = true;
-      } else if (event.type === "sandbox.command.output.delta") {
-        // Ordinary shell writes can bypass Channel-A and therefore emit no
-        // fs.changed/git.changed event until the command completes. Reconcile
-        // the visible frontier at most once per second while output streams so
-        // Files and Changes stay useful without turning the dock into polling.
-        sawNew = true;
-        contentChanged = true;
-        sawCommandDelta = true;
-        pendingAgentToolRef.current = true;
-        pendingGitRef.current = true;
       }
     }
     // Advance the high-water mark past everything we've folded.
     for (const event of events)
       if (event.sequence > lastSeqRef.current) lastSeqRef.current = event.sequence;
     if (!sawNew) return;
-    if (contentChanged && !sawCommandDelta) setContentRevision((revision) => revision + 1);
+    if (contentChanged) setContentRevision((revision) => revision + 1);
 
     if (debounceRef.current) clearTimeout(debounceRef.current);
     const identityGeneration = identityGenerationRef.current;
-    const delay = sawCommandDelta
-      ? Math.max(0, 1_000 - (Date.now() - lastCommandRefreshAtRef.current))
-      : 150;
     debounceRef.current = setTimeout(() => {
       debounceRef.current = null;
       if (identityGenerationRef.current !== identityGeneration) return;
       if (!acceptsEventReadsRef.current) {
         pendingParentsRef.current = new Set();
         pendingGitRef.current = false;
-        pendingAgentToolRef.current = false;
         return;
       }
-      if (sawCommandDelta) {
-        lastCommandRefreshAtRef.current = Date.now();
-        setContentRevision((revision) => revision + 1);
-      }
-      const parents = pendingParentsRef.current;
-      pendingParentsRef.current = new Set();
-      const wantGit = pendingGitRef.current;
-      pendingGitRef.current = false;
-      const wantAgentTool = pendingAgentToolRef.current;
-      pendingAgentToolRef.current = false;
-      // Reconcile the changed directories and Git overlay concurrently. Both are
-      // independent remote reads; applyStatus makes their completion order safe.
-      const eventReadSignal = eventReadAbortRef.current.signal;
-      void (async () => {
-        const paths = wantAgentTool ? loadedDirectoryPaths(treeRef.current) : [...parents];
-        await Promise.all([
-          wantGit ? refreshGitOverlay(eventReadSignal) : Promise.resolve(),
-          Promise.all(paths.map((path) => reconcilePath(path, eventReadSignal))),
-        ]);
-      })();
-    }, delay);
-  }, [enabled, active, acceptsEventReads, events, reconcilePath, refreshGitOverlay]);
+      void reconcilePendingEvents();
+    }, 150);
+  }, [enabled, active, acceptsEventReads, events, rootPath, reconcilePendingEvents]);
 
   useEffect(() => {
     if (active && acceptsEventReads) return;
@@ -1349,7 +1451,7 @@ export function useSandboxFiles(
     }
     pendingParentsRef.current = new Set();
     pendingGitRef.current = false;
-    pendingAgentToolRef.current = false;
+    eventReconcilePendingRef.current = false;
   }, [active, acceptsEventReads]);
 
   useEffect(
@@ -1357,6 +1459,7 @@ export function useSandboxFiles(
       refreshAbortRef.current?.abort();
       identityAbortRef.current.abort();
       eventReadAbortRef.current.abort();
+      eventReconcilePendingRef.current = false;
       identityGenerationRef.current += 1;
       if (debounceRef.current) clearTimeout(debounceRef.current);
     },