@opengeni/react 0.48.0 → 0.52.1

package/src/hooks/use-machine-chip.ts

@@ -1,6 +1,7 @@
 import { useMemo } from "react";
 import type { MachineState } from "@opengeni/sdk";
 import type { SessionCapabilitiesState } from "./use-session-capabilities";
+import { sandboxAcceptsLiveIo } from "../lib/sandbox-liveness";
 
 /** The one truthful machine indicator. Honest staleness beats
  *  fake liveness: a cold/asleep box reads "offline — as of <time>", never "live". */
@@ -53,7 +54,7 @@ export function formatAsOf(capturedAt: string, now: number): string {
  * it; the whole point is a deterministic, testable projection).
  *
  * Precedence:
- *   1. warm/draining lease → **live** (a warm box always wins).
+ *   1. warm lease → **live** (a holder-confirmed box always wins).
  *   2. actively warming (negotiating, wake-on-edit, or a reconnecting/enrolling
  *      machine) → **waking**.
  *   3. everything else (a cold/asleep box, a self-hosted machine that's offline,
@@ -64,8 +65,9 @@ export function deriveMachineChip(input: DeriveMachineChipInput): MachineChip {
   const asOf = input.capturedAt ?? null;
   const offlineLabel = asOf ? `Offline — as of ${formatAsOf(asOf, now)}` : "Offline";
 
-  // 1. A warm (or draining) lease is live regardless of anything else.
-  if (input.liveness === "warm" || input.liveness === "draining") {
+  // 1. Only holder-confirmed warm is live. Draining is teardown-owned and may
+  // already have lost its provider instance, so it uses the capture-backed label.
+  if (sandboxAcceptsLiveIo(input.liveness)) {
     return { state: "live", label: "Live", asOf: null };
   }
 

package/src/hooks/use-machines.ts

@@ -1,5 +1,9 @@
 import { useCallback, useRef, useState } from "react";
-import type { RemoveEnrollmentRequest, RemoveEnrollmentResponse } from "@opengeni/sdk";
+import type {
+  RemoveEnrollmentRequest,
+  RemoveEnrollmentResponse,
+  SwapActiveSandboxResponse,
+} from "@opengeni/sdk";
 import { useOpenGeni, type ClientOverride } from "../provider";
 import { useMutationRunner, usePolledValue } from "./internal";
 import type { MachinesResponse, MachineView, MetricSample } from "../types/machines";
@@ -46,7 +50,7 @@ export type MachinesClientLike = {
     workspaceId: string,
     sessionId: string,
     request: { target: string },
-  ) => Promise<unknown>;
+  ) => Promise<SwapActiveSandboxResponse>;
   /**
    * Host-supplied swap adapter (an escape hatch). When present it wins over the
    * default `swapActiveSandbox` path. Session-scoped, like the swap it backs.
@@ -99,6 +103,24 @@ export type UseMachinesResult = {
 
 const EMPTY: MachinesResponse = { activeSandboxId: null, activeEpoch: 0, machines: [] };
 
+function swapFailureMessage(result: SwapActiveSandboxResponse): string {
+  if (result.reason?.trim()) return result.reason;
+  switch (result.code) {
+    case "recovery_in_progress":
+      return "The managed sandbox is still recovering. Try again shortly.";
+    case "recovery_degraded":
+      return "The managed sandbox recovery is degraded and needs attention.";
+    case "recovery_unrecoverable":
+      return "The managed sandbox could not be recovered.";
+    case "offline_enrollment":
+      return "The selected machine is offline.";
+    case "concurrent_swap":
+      return "The session route changed concurrently. Refresh and try again.";
+    default:
+      return "The session stayed on its current sandbox.";
+  }
+}
+
 /**
  * The workspace Machines fleet: the selfhosted enrollments + the session's Modal
  * box, each with latest metrics + state, plus the active-sandbox pointer. Polls
@@ -171,7 +193,15 @@ export function useMachines(options: UseMachinesOptions = {}): UseMachinesResult
       const ownedIdentity = identityKey;
       setAttachState({ identity: ownedIdentity, sandboxId });
       const result = await run(async () => {
-        await runSwap();
+        const response = await runSwap();
+        if (
+          response &&
+          typeof response === "object" &&
+          "swapped" in response &&
+          response.swapped === false
+        ) {
+          throw new Error(swapFailureMessage(response as SwapActiveSandboxResponse));
+        }
         return true;
       });
       if (identityRef.current === ownedIdentity) {

package/src/hooks/use-packs.ts

@@ -1,8 +1,14 @@
 import type {
   CapabilityPack,
   EnablePackRequest,
+  InstallPackRequest,
+  PackInstallationPreview,
   PackInstallation,
+  PackUninstallPreview,
+  PreviewPackInstallationRequest,
   RegisterCapabilityPackRequest,
+  UninstallPackRequest,
+  UninstallPackResult,
   WorkspaceRegisteredPack,
 } from "@opengeni/sdk";
 import { useCallback } from "react";
@@ -28,7 +34,15 @@ export type UsePacksResult = {
   refresh: () => Promise<void>;
   /** Register (or replace) a workspace-scoped pack manifest. */
   register: (manifest: RegisterCapabilityPackRequest) => Promise<WorkspaceRegisteredPack | null>;
+  /** @deprecated Use previewInstallation + install for component/Rig-aware Packs. */
   enable: (packId: string, request?: EnablePackRequest) => Promise<PackInstallation | null>;
+  previewInstallation: (
+    packId: string,
+    request?: PreviewPackInstallationRequest,
+  ) => Promise<PackInstallationPreview | null>;
+  install: (packId: string, request: InstallPackRequest) => Promise<PackInstallation | null>;
+  previewUninstall: (packId: string) => Promise<PackUninstallPreview | null>;
+  uninstall: (packId: string, request: UninstallPackRequest) => Promise<UninstallPackResult | null>;
   /** Unregister a workspace-scoped pack (built-ins cannot be removed). */
   remove: (packId: string) => Promise<boolean>;
   mutating: boolean;
@@ -68,6 +82,39 @@ export function usePacks(options: UsePacksOptions = {}): UsePacksResult {
     [client, workspaceId, run, refresh],
   );
 
+  const previewInstallation = useCallback(
+    async (
+      packId: string,
+      request: PreviewPackInstallationRequest = {},
+    ): Promise<PackInstallationPreview | null> =>
+      await run(() => client.previewPackInstallation(workspaceId, packId, request)),
+    [client, workspaceId, run],
+  );
+
+  const install = useCallback(
+    async (packId: string, request: InstallPackRequest): Promise<PackInstallation | null> => {
+      const result = await run(() => client.installPack(workspaceId, packId, request));
+      if (result) await refresh();
+      return result;
+    },
+    [client, workspaceId, run, refresh],
+  );
+
+  const previewUninstall = useCallback(
+    async (packId: string): Promise<PackUninstallPreview | null> =>
+      await run(() => client.previewPackUninstall(workspaceId, packId)),
+    [client, workspaceId, run],
+  );
+
+  const uninstall = useCallback(
+    async (packId: string, request: UninstallPackRequest): Promise<UninstallPackResult | null> => {
+      const result = await run(() => client.uninstallPack(workspaceId, packId, request));
+      if (result) await refresh();
+      return result;
+    },
+    [client, workspaceId, run, refresh],
+  );
+
   const remove = useCallback(
     async (packId: string): Promise<boolean> => {
       const result = await run(async () => {
@@ -98,6 +145,10 @@ export function usePacks(options: UsePacksOptions = {}): UsePacksResult {
     refresh,
     register,
     enable,
+    previewInstallation,
+    install,
+    previewUninstall,
+    uninstall,
     remove,
     mutating,
     mutationError,

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

@@ -7,11 +7,13 @@ import type {
   GitFileStatusCode,
   GitStatusResponse,
   OpenGeniRequestOptions,
+  SessionCapabilities,
   SessionEvent,
   WorkspaceCaptureManifest,
 } from "@opengeni/sdk";
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { type ClientOverride, useOpenGeni } from "../provider";
+import { sandboxAcceptsLiveIo } from "../lib/sandbox-liveness";
 
 /** The git-status overlay a file row may carry (tints modified files in the tree). */
 export type FileTreeStatus = "added" | "modified" | "deleted" | "renamed" | "untracked";
@@ -87,12 +89,14 @@ export type UseSandboxFilesOptions = ClientOverride & {
   active?: boolean | undefined;
   /** Repository roots advertised by capabilities, relative to the workspace. */
   repoPaths?: readonly string[] | undefined;
-  /** The lease liveness ("cold" | "warm" | "draining"). The structured FileSystem
+  /** The lease liveness. `null` means capability negotiation has not produced
+   *  an authoritative lifecycle value yet and therefore blocks live I/O. Omitting
+   *  the option preserves the legacy direct-hook behavior. The structured FileSystem
    *  capability is advertised even on a COLD box, so the mount-time list can race
    *  the box: it lists before the box is warm, gets an empty/errored result, and
    *  (with no `fs.changed` event) never re-lists. Passing liveness re-lists when
    *  the box first becomes warm, so the tree populates as soon as the box is up. */
-  liveness?: string | undefined;
+  liveness?: SessionCapabilities["liveness"] | null | undefined;
   /** The latest turn-end workspace capture (from `useWorkspaceCapture`). The tree
    *  paints immediately from this durable index, then a warm box reconciles live
    *  in place. If that live read fails, the capture remains a truthful read-only
@@ -487,7 +491,13 @@ export function useSandboxFiles(
   ].join("\u0000");
   const repoPaths = useMemo(() => repoPathsKey.split("\u0000"), [repoPathsKey]);
   const capture = options.capture ?? null;
-  const isLive = options.liveness === "warm" || options.liveness === "draining";
+  const isLive = sandboxAcceptsLiveIo(options.liveness);
+  // `liveness` predates this hook option. Preserve legacy embedders that omit it;
+  // explicit `null` (negotiating) and lifecycle values require authoritative warm.
+  const acceptsEventReads = options.liveness === undefined || isLive;
+  const acceptsEventReadsRef = useRef(acceptsEventReads);
+  acceptsEventReadsRef.current = acceptsEventReads;
+  const hasLiveIoFence = options.liveness !== undefined;
   const identityKey = `${workspaceId}\u0000${sessionId ?? ""}\u0000${rootPath}\u0000${repoPathsKey}`;
 
   const [tree, setTree] = useState<FileTreeNode[]>([]);
@@ -512,6 +522,7 @@ export function useSandboxFiles(
   const refreshGenerationRef = useRef(0);
   const refreshAbortRef = useRef<AbortController | null>(null);
   const identityAbortRef = useRef(new AbortController());
+  const eventReadAbortRef = useRef(new AbortController());
   const identityGenerationRef = useRef(0);
   const lastSeqRef = useRef(0);
   const pendingParentsRef = useRef<Set<string>>(new Set());
@@ -846,20 +857,18 @@ export function useSandboxFiles(
   // of a parent that isn't loaded (collapsed/unmounted) is a no-op — there's
   // nothing visible to update, and it re-lists fresh when the user expands it.
   const reconcilePath = useCallback(
-    async (path: string) => {
+    async (path: string, requestSignal?: AbortSignal) => {
       if (!sessionId) return;
       const identityGeneration = identityGenerationRef.current;
       const identitySignal = identityAbortRef.current.signal;
+      const signal = requestSignal
+        ? AbortSignal.any([identitySignal, requestSignal])
+        : 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;
       try {
-        const listed = await client.fsList(
-          workspaceId,
-          sessionId,
-          { path, depth: 1 },
-          { signal: identitySignal },
-        );
+        const listed = await client.fsList(workspaceId, sessionId, { path, depth: 1 }, { signal });
         if (identityGenerationRef.current !== identityGeneration) return;
         const children = (listed.root.children ?? []).map((node) => fsNodeToTree(node));
         if (path === "") setTree((prev) => applyStatus(mergeRootChildren(prev, children)));
@@ -1075,9 +1084,10 @@ export function useSandboxFiles(
 
   // Initial paint + reset on identity change. Source selection:
   //   • any box WITH a capture → paint instantly from the durable capture index;
-  //     a warm/draining box then reconciles live in place.
+  //     a holder-confirmed warm box then reconciles live in place.
   //   • if that live reconciliation fails, keep the capture visible and read-only.
-  //   • cold box with NO capture → best-effort live list (status quo — never worse).
+  //   • legacy callers that omit liveness and have no capture retain their live
+  //     fallback; an explicitly cold/draining lease never wakes from a passive mount.
   // Key the seed on the capture's REVISION (a primitive), not the manifest object
   // — a consumer passing a fresh object each render (or a new revision) must not
   // spin the effect. The latest manifest is read from a ref at run time.
@@ -1092,6 +1102,8 @@ export function useSandboxFiles(
     refreshAbortRef.current?.abort();
     refreshAbortRef.current = null;
     refreshGenerationRef.current += 1;
+    eventReadAbortRef.current.abort();
+    eventReadAbortRef.current = new AbortController();
     const identityChanged = previousIdentityRef.current !== identityKey;
     previousIdentityRef.current = identityKey;
     if (identityChanged || !enabled) {
@@ -1135,53 +1147,69 @@ export function useSandboxFiles(
       }
       return;
     }
-    if (isLive || !currentCapture) {
+    if (isLive || (!hasLiveIoFence && !currentCapture)) {
       void refresh();
     }
     return () => {
       refreshAbortRef.current?.abort();
       refreshAbortRef.current = null;
       refreshGenerationRef.current += 1;
+      eventReadAbortRef.current.abort();
     };
-  }, [enabled, active, isLive, captureRevision, identityKey, refresh, seedFromCapture]);
+  }, [
+    enabled,
+    active,
+    isLive,
+    hasLiveIoFence,
+    captureRevision,
+    identityKey,
+    refresh,
+    seedFromCapture,
+  ]);
 
   // Re-pull JUST the git-status overlay and re-tint the existing tree in place —
   // no fs re-list, no collapse. This is all a `git.changed` (commit/stage/checkout)
   // needs: the tree SHAPE is unchanged, only the tints move.
-  const refreshGitOverlay = useCallback(async () => {
-    if (!sessionId) return;
-    const identityGeneration = identityGenerationRef.current;
-    const identitySignal = identityAbortRef.current.signal;
-    setGitLoading(true);
-    try {
-      const batch = await client.gitReadBatch(
-        workspaceId,
-        sessionId,
-        { requests: repoPaths.map((root) => ({ status: { path: root } })) },
-        { signal: identitySignal },
-      );
-      const statuses = batch.results.map((result, index) => ({
-        root: repoPaths[index] ?? "",
-        status: result.status,
-      }));
-      if (identityGenerationRef.current !== identityGeneration) return;
-      const overlay = new Map<string, FileTreeStatus>();
-      for (const { root, status } of statuses) {
-        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);
+  const refreshGitOverlay = useCallback(
+    async (requestSignal?: AbortSignal) => {
+      if (!sessionId) return;
+      const identityGeneration = identityGenerationRef.current;
+      const identitySignal = identityAbortRef.current.signal;
+      const signal = requestSignal
+        ? AbortSignal.any([identitySignal, requestSignal])
+        : identitySignal;
+      setGitLoading(true);
+      try {
+        const batch = await client.gitReadBatch(
+          workspaceId,
+          sessionId,
+          { requests: repoPaths.map((root) => ({ status: { path: root } })) },
+          { signal },
+        );
+        const statuses = batch.results.map((result, index) => ({
+          root: repoPaths[index] ?? "",
+          status: result.status,
+        }));
+        if (identityGenerationRef.current !== identityGeneration) return;
+        const overlay = new Map<string, FileTreeStatus>();
+        for (const { root, status } of statuses) {
+          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);
+          }
         }
+        statusRef.current = overlay;
+        setGitSummary(summarizeStatuses(statuses));
+        setTree((prev) => applyStatus(prev));
+      } catch {
+        /* a non-repo box has no overlay — leave the tree untinted */
+      } finally {
+        if (identityGenerationRef.current === identityGeneration) setGitLoading(false);
       }
-      statusRef.current = overlay;
-      setGitSummary(summarizeStatuses(statuses));
-      setTree((prev) => applyStatus(prev));
-    } catch {
-      /* a non-repo box has no overlay — leave the tree untinted */
-    } finally {
-      if (identityGenerationRef.current === identityGeneration) setGitLoading(false);
-    }
-  }, [client, workspaceId, sessionId, repoPaths, applyStatus]);
+    },
+    [client, workspaceId, sessionId, repoPaths, applyStatus],
+  );
 
   // Auto-reconcile on fs/git change notifications — TARGETED, never a root
   // collapse-reload, and de-duped against our OWN mutations.
@@ -1197,13 +1225,20 @@ export function useSandboxFiles(
 
   useEffect(() => {
     if (!enabled || !events) return;
-    // An inactive tab must not replay the entire historical event log when it is
-    // opened. Keep its cursor current without performing any reconciliation;
-    // only events that arrive while Files is visible should trigger live reads.
-    if (!active) {
+    // An inactive tab or holderless draining/cold lease must not replay the
+    // historical log into live provider reads. The capture already includes
+    // those events; a later warm transition performs one authoritative refresh.
+    if (!active || !acceptsEventReads) {
       for (const event of events) {
         if (event.sequence > lastSeqRef.current) lastSeqRef.current = event.sequence;
       }
+      if (debounceRef.current) {
+        clearTimeout(debounceRef.current);
+        debounceRef.current = null;
+      }
+      pendingParentsRef.current = new Set();
+      pendingGitRef.current = false;
+      pendingAgentToolRef.current = false;
       return;
     }
     let sawNew = false;
@@ -1277,6 +1312,12 @@ export function useSandboxFiles(
     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);
@@ -1289,18 +1330,19 @@ export function useSandboxFiles(
       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() : Promise.resolve(),
-          Promise.all(paths.map((path) => reconcilePath(path))),
+          wantGit ? refreshGitOverlay(eventReadSignal) : Promise.resolve(),
+          Promise.all(paths.map((path) => reconcilePath(path, eventReadSignal))),
         ]);
       })();
     }, delay);
-  }, [enabled, active, events, reconcilePath, refreshGitOverlay]);
+  }, [enabled, active, acceptsEventReads, events, reconcilePath, refreshGitOverlay]);
 
   useEffect(() => {
-    if (active) return;
+    if (active && acceptsEventReads) return;
     if (debounceRef.current) {
       clearTimeout(debounceRef.current);
       debounceRef.current = null;
@@ -1308,12 +1350,13 @@ export function useSandboxFiles(
     pendingParentsRef.current = new Set();
     pendingGitRef.current = false;
     pendingAgentToolRef.current = false;
-  }, [active]);
+  }, [active, acceptsEventReads]);
 
   useEffect(
     () => () => {
       refreshAbortRef.current?.abort();
       identityAbortRef.current.abort();
+      eventReadAbortRef.current.abort();
       identityGenerationRef.current += 1;
       if (debounceRef.current) clearTimeout(debounceRef.current);
     },

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

@@ -1,11 +1,13 @@
 import type {
   GitFileDiff,
+  SessionCapabilities,
   SessionEvent,
   WorkspaceCaptureManifest,
   WorkspaceCaptureRepo,
 } from "@opengeni/sdk";
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { type ClientOverride, useOpenGeni } from "../provider";
+import { sandboxAcceptsLiveIo } from "../lib/sandbox-liveness";
 
 export type UseSandboxGitOptions = ClientOverride & {
   /** Live event log (usually `useSessionEvents().events`) — drives auto-refresh
@@ -26,9 +28,10 @@ export type UseSandboxGitOptions = ClientOverride & {
   enabled?: boolean | undefined;
   /** Pause live reads/invalidation while preserving the last rendered result. */
   active?: boolean | undefined;
-  /** Lease liveness ("warm" | "draining" | "cold"). When NOT warm, the diff is
-   *  served from the capture (cold/offline) instead of a live `gitDiff` RPC. */
-  liveness?: string | undefined;
+  /** Lease liveness. `null` means capability negotiation is still pending and
+   *  blocks live I/O. When not warm, the diff is served from the capture instead
+   *  of a live `gitDiff` RPC. Omission preserves legacy direct-hook behavior. */
+  liveness?: SessionCapabilities["liveness"] | null | undefined;
   /** The latest turn-end capture (from `useWorkspaceCapture`). Seeds the diff
    *  immediately; a warm box reconciles live and leaves this durable review
    *  surface in place if the live request is temporarily unavailable. */
@@ -93,6 +96,11 @@ function uniqueRoots(roots: readonly string[]): string[] {
   return [...new Set(roots.map(normalizeRoot))].sort((a, b) => a.localeCompare(b));
 }
 
+// GitReadBatchRequest is contract-bounded to 32 items. Keep workspace-wide
+// reads bounded without changing the wire limit; sequential chunks preserve
+// deterministic root/result mapping and cap Channel-A lease concurrency at one.
+const GIT_READ_BATCH_REQUEST_LIMIT = 32;
+
 /** Find the capture repo matching `repoPath` (default workspace root). */
 function repoForPath(
   manifest: WorkspaceCaptureManifest,
@@ -201,7 +209,13 @@ export function useSandboxGit(
   // remains live-only; legacy captures simply lack branchDiff and fall back via
   // the workspace controller without inventing an empty branch comparison.
   const capture = comparison === "staged" ? null : (options.capture ?? null);
-  const isLive = options.liveness === "warm" || options.liveness === "draining";
+  const isLive = sandboxAcceptsLiveIo(options.liveness);
+  // `liveness` is optional for compatibility with direct hook consumers. Explicit
+  // `null` (negotiating) and lifecycle values require authoritative warm.
+  const acceptsEventReads = options.liveness === undefined || isLive;
+  const acceptsEventReadsRef = useRef(acceptsEventReads);
+  acceptsEventReadsRef.current = acceptsEventReads;
+  const hasLiveIoFence = options.liveness !== undefined;
   const identityKey = `${workspaceId}\u0000${sessionId ?? ""}\u0000${repoPathsKey}\u0000${workspaceWide}\u0000${comparison}`;
 
   const [diff, setDiff] = useState<SandboxGitFileDiff[]>([]);
@@ -251,35 +265,54 @@ export function useSandboxGit(
       // take several seconds on a remote sandbox. The legacy root probe remains
       // serial so a non-repository workspace never receives a failing git diff.
       const prefetched = hasAdvertisedRepoPaths
-        ? await client
-            .gitReadBatch(
-              workspaceId,
-              sessionId,
-              {
-                requests: repoPaths.map((root) => ({
-                  status: { path: root },
-                  diff: {
-                    path: root,
-                    ...(comparison === "branch"
-                      ? { fromRef: "origin/HEAD", includeUntracked: true }
-                      : comparison === "working"
-                        ? { fromRef: "HEAD", includeUntracked: true }
-                        : { staged: true, includeUntracked: false }),
-                  },
-                })),
-              },
-              { signal: refreshAbort.signal },
-            )
-            .then((batch) =>
-              batch.results.map((item, index) => ({
-                root: repoPaths[index] ?? "",
-                status: item.status,
-                result: item.diff ?? {
-                  files: [],
-                  revision: item.status.revision,
+        ? await (async () => {
+            const prefetchedRepos: Array<{
+              root: string;
+              status: Awaited<ReturnType<typeof client.gitStatus>>;
+              result: Awaited<ReturnType<typeof client.gitDiff>>;
+            }> = [];
+            for (
+              let offset = 0;
+              offset < repoPaths.length;
+              offset += GIT_READ_BATCH_REQUEST_LIMIT
+            ) {
+              const roots = repoPaths.slice(offset, offset + GIT_READ_BATCH_REQUEST_LIMIT);
+              const batch = await client.gitReadBatch(
+                workspaceId,
+                sessionId,
+                {
+                  requests: roots.map((root) => ({
+                    status: { path: root },
+                    diff: {
+                      path: root,
+                      ...(comparison === "branch"
+                        ? { fromRef: "origin/HEAD", includeUntracked: true }
+                        : comparison === "working"
+                          ? { fromRef: "HEAD", includeUntracked: true }
+                          : { staged: true, includeUntracked: false }),
+                    },
+                  })),
                 },
-              })),
-            )
+                { signal: refreshAbort.signal },
+              );
+              if (batch.results.length !== roots.length) {
+                throw new Error(
+                  `Workspace Git batch returned ${batch.results.length} results for ${roots.length} repositories.`,
+                );
+              }
+              batch.results.forEach((item, index) => {
+                prefetchedRepos.push({
+                  root: roots[index]!,
+                  status: item.status,
+                  result: item.diff ?? {
+                    files: [],
+                    revision: item.status.revision,
+                  },
+                });
+              });
+            }
+            return prefetchedRepos;
+          })()
         : null;
       const statuses =
         prefetched ??
@@ -427,7 +460,7 @@ export function useSandboxGit(
       if (!active) setLoading(false);
       return;
     }
-    if (isLive || !currentCapture) {
+    if (isLive || (!hasLiveIoFence && !currentCapture)) {
       void refresh();
     }
     return () => {
@@ -435,14 +468,36 @@ export function useSandboxGit(
       refreshAbortRef.current = null;
       refreshGenerationRef.current += 1;
     };
-  }, [enabled, active, isLive, captureRevision, identityKey, refresh, seedFromCapture]);
+  }, [
+    enabled,
+    active,
+    isLive,
+    hasLiveIoFence,
+    captureRevision,
+    identityKey,
+    refresh,
+    seedFromCapture,
+  ]);
 
   // git.changed → re-fetch the LIVE diff. Agent tool completion is also an
   // invalidation point because shell/apply-patch writes can bypass Channel-A and
   // therefore emit no git.changed event. This is event-driven, never polling.
   const events = options.events;
   useEffect(() => {
-    if (!enabled || !active || !events) {
+    if (!enabled || !events) {
+      if (commandRefreshTimerRef.current) {
+        clearTimeout(commandRefreshTimerRef.current);
+        commandRefreshTimerRef.current = null;
+      }
+      return;
+    }
+    // Historical events describe the capture we already loaded. Inactive tabs
+    // and holderless draining/cold leases advance the cursor without issuing
+    // provider I/O; becoming warm performs one authoritative reconcile above.
+    if (!active || !acceptsEventReads) {
+      for (const event of events) {
+        if (event.sequence > lastChangeRef.current) lastChangeRef.current = event.sequence;
+      }
       if (commandRefreshTimerRef.current) {
         clearTimeout(commandRefreshTimerRef.current);
         commandRefreshTimerRef.current = null;
@@ -467,15 +522,15 @@ export function useSandboxGit(
       if (immediate) {
         if (commandRefreshTimerRef.current) clearTimeout(commandRefreshTimerRef.current);
         commandRefreshTimerRef.current = null;
-        void refresh();
+        if (acceptsEventReadsRef.current) void refresh();
       } else if (commandDelta && !commandRefreshTimerRef.current) {
         commandRefreshTimerRef.current = setTimeout(() => {
           commandRefreshTimerRef.current = null;
-          void refresh();
+          if (acceptsEventReadsRef.current) void refresh();
         }, 1_000);
       }
     }
-  }, [enabled, active, events, refresh]);
+  }, [enabled, active, acceptsEventReads, events, refresh]);
 
   useEffect(
     () => () => {