@opengeni/react 0.57.0 → 1.0.2-canary.37191796234001

package/src/components/sandbox-workspace.tsx

@@ -45,6 +45,7 @@ import { xtermThemeFromTokens } from "../lib/xterm-theme";
 import { sandboxAcceptsLiveIo } from "../lib/sandbox-liveness";
 import type { BrowserFrameWebSocketFactory } from "../hooks/use-browser-frame-stream";
 import type { ComputerFrameWebSocketFactory } from "../hooks/use-computer-frame-stream";
+import type { FileNodeVisibilityPredicate } from "../file-node-visibility";
 import { useSessionCapabilities } from "../hooks/use-session-capabilities";
 import { useSandboxFiles } from "../hooks/use-sandbox-files";
 import {
@@ -55,21 +56,49 @@ import {
 import { useSandboxTerminal } from "../hooks/use-sandbox-terminal";
 import { useWorkspaceCapture } from "../hooks/use-workspace-capture";
 import { useMachineChip, type MachineChip } from "../hooks/use-machine-chip";
-import { useMachines } from "../hooks/use-machines";
+import { MACHINES_SESSION_POLL_MS, useMachines } from "../hooks/use-machines";
 import type { MachineView } from "../types/machines";
-import { SandboxFiles } from "./sandbox-files";
+import type { SandboxFilesProps } from "./sandbox-files";
 import { WorkbenchChanges } from "./workbench-changes";
 import { SandboxTerminal, type XtermTheme } from "./sandbox-terminal";
 import { WorkspaceDock, type WorkspaceDockProps, type WorkspaceTab } from "./workspace-dock";
 
+const LazySandboxFiles = lazy(() =>
+  import("./sandbox-files")
+    .then(({ SandboxFiles }) => ({ default: SandboxFiles }))
+    // A host may already have attempted stale-deployment recovery. Keep an
+    // optional chunk failure inside Files rather than unmounting the chat.
+    .catch(() => ({ default: FilesLoadFailed })),
+);
+
+function FilesLoadFailed() {
+  return (
+    <CenteredState tone="danger" icon={<TriangleAlertIcon className="size-5" aria-hidden />}>
+      <p className="text-og-sm font-medium text-og-fg">Files could not be loaded.</p>
+      <DockActionButton onClick={() => window.location.reload()}>
+        <RefreshCwIcon className="size-3" aria-hidden />
+        Reload
+      </DockActionButton>
+    </CenteredState>
+  );
+}
+
+function FilesTabBody(props: SandboxFilesProps) {
+  return (
+    <Suspense fallback={<WorkbenchSurfaceLoading name="Files" />}>
+      <LazySandboxFiles {...props} />
+    </Suspense>
+  );
+}
+
 const LazyBrowserViewer = lazy(async () => {
-  const viewers = await import("./interactive-workbench-viewers");
-  return { default: viewers.BrowserViewer };
+  const { BrowserViewer } = await import("./browser-viewer");
+  return { default: BrowserViewer };
 });
 
 const LazyComputerViewer = lazy(async () => {
-  const viewers = await import("./interactive-workbench-viewers");
-  return { default: viewers.ComputerViewer };
+  const { ComputerViewer } = await import("./computer-viewer");
+  return { default: ComputerViewer };
 });
 
 /** A host-routed notification (replaces the app-only `sonner` toast coupling). */
@@ -101,6 +130,12 @@ function isWorkbenchSurface(value: string): value is SandboxWorkspaceSurface {
   return (WORKBENCH_SURFACES as readonly string[]).includes(value);
 }
 
+function isCanonicalAbsoluteSandboxPath(value: string | null | undefined): boolean {
+  if (!value) return false;
+  const portable = value.replaceAll("\\", "/");
+  return portable.startsWith("/") || /^[A-Za-z]:\//u.test(portable);
+}
+
 function sourceDrivenDefaultTab(
   hasChanges: boolean,
   changesEnabled: boolean,
@@ -112,31 +147,7 @@ function sourceDrivenDefaultTab(
   return null;
 }
 
-function captureDegradedMessage(reason: string): string {
-  switch (reason) {
-    case "repository_discovery_timed_out":
-      return "Workspace capture is incomplete because repository discovery timed out. Live files remain authoritative.";
-    case "repository_discovery_result_limit_exceeded":
-      return "Workspace capture is incomplete because the repository limit was exceeded. Live files remain authoritative.";
-    case "repository_read_unavailable":
-      return "Workspace capture is incomplete because repository changes could not be read. Live files remain authoritative.";
-    default:
-      return "Workspace capture is incomplete because repository discovery failed. Live files remain authoritative.";
-  }
-}
-
-function WorkbenchTabLabel({ icon, children }: { icon: ReactNode; children: ReactNode }) {
-  return (
-    <span className="inline-flex items-center gap-1.5">
-      <span className="[&>svg]:size-3.5" aria-hidden>
-        {icon}
-      </span>
-      <span>{children}</span>
-    </span>
-  );
-}
-
-function WorkbenchSurfaceLoading({ name }: { name: "Browser" | "Computer" }) {
+function WorkbenchSurfaceLoading({ name }: { name: "Files" | "Browser" | "Desktop" }) {
   return (
     <CenteredState
       icon={
@@ -218,10 +229,51 @@ function sandboxProvisionInFlight(events: SessionEvent[]): boolean {
   return inFlight;
 }
 
+/**
+ * Whether this session currently owns an admitted agent turn. Automatic live
+ * Files/Git reads pause across the whole turn: command boundaries are not a safe
+ * gap because the next tool can dispatch before a remote provider read releases
+ * its sandbox holder. Existing/captured content remains usable, and the terminal
+ * turn event resumes one authoritative refresh.
+ */
+function workspaceTurnInFlight(events: SessionEvent[]): boolean {
+  const activeTurnIds = new Set<string>();
+  let anonymousTurnInFlight = false;
+  let sessionOwnsWorkspace = false;
+  for (const event of events) {
+    if (event.type === "session.status.changed") {
+      const status =
+        event.payload && typeof event.payload === "object" && !Array.isArray(event.payload)
+          ? (event.payload as Record<string, unknown>).status
+          : null;
+      sessionOwnsWorkspace = status === "running" || status === "recovering";
+      continue;
+    }
+    if (event.type === "turn.started") {
+      if (event.turnId) activeTurnIds.add(event.turnId);
+      else anonymousTurnInFlight = true;
+      continue;
+    }
+    if (
+      event.type !== "turn.completed" &&
+      event.type !== "turn.failed" &&
+      event.type !== "turn.cancelled" &&
+      event.type !== "turn.superseded"
+    ) {
+      continue;
+    }
+    if (event.turnId) activeTurnIds.delete(event.turnId);
+    else anonymousTurnInFlight = false;
+  }
+  // The retained event window preserves the latest status even after a very
+  // long turn has evicted its original turn.started event.
+  return sessionOwnsWorkspace || anonymousTurnInFlight || activeTurnIds.size > 0;
+}
+
 export type WorkspaceMachine = {
   /** Whether at least one built-in workbench surface is enabled. */
   enabled: boolean;
-  /** The derived live/waking/offline chip model. */
+  /** The derived live/waking/sleeping-or-offline chip model. */
   chip: MachineChip;
   /** The machine these surfaces are bound to (the Modal group box or a
    *  self-hosted machine), or null while the fleet is still resolving. */
@@ -256,14 +308,27 @@ export type UseSandboxWorkspaceTabsOptions = ClientOverride & {
   browserWebSocketFactory?: BrowserFrameWebSocketFactory | undefined;
   /** Alternate Computer frame transport for non-browser runtimes and deterministic tests. */
   computerWebSocketFactory?: ComputerFrameWebSocketFactory | undefined;
+  /** Host-owned setup page or store listing for attaching an existing Chrome profile. */
+  browserExtensionSetupUrl?: string | undefined;
   /** File requested by a Changes guard. The Files surface defers the read until
    *  the sandbox is live, then reveals this path. */
   requestedFilePath?: string | null | undefined;
   /** Unique identity for `requestedFilePath`, including repeated requests for the
    *  same path. */
   requestedFileRequestId?: string | number | null | undefined;
+  /** 1-based line to reveal after `requestedFilePath` opens. */
+  requestedFileLine?: number | null | undefined;
   /** Route a guarded diff into the host's Files tab. */
   onOpenFile?: ((path: string) => void) | undefined;
+  /** Restore and report navigation inside the built-in workbench surfaces. */
+  initialFilePath?: string | null | undefined;
+  onFilePathChange?: ((path: string | null) => void) | undefined;
+  /** Presentation-only filter for Files tree nodes and selected-file viewing. */
+  isFileNodeVisible?: FileNodeVisibilityPredicate | undefined;
+  initialBrowserSessionId?: string | null | undefined;
+  onBrowserSessionIdChange?: ((browserSessionId: string | null) => void) | undefined;
+  initialComputerSessionId?: string | null | undefined;
+  onComputerSessionIdChange?: ((computerSessionId: string | null) => void) | undefined;
   /** Navigate the host dock to one exact linked ComputerSession. */
   onOpenComputerSession?: ((computerSessionId: string) => void) | undefined;
   requestedComputerSessionId?: string | null | undefined;
@@ -274,7 +339,8 @@ export type UseSandboxWorkspaceTabsResult = {
   /** Changes | Files | Terminal | Browser | Desktop (capability-gated where noted). */
   tabs: WorkspaceTab[];
   /** The source-driven default tab: Changes when the first authoritative capture
-   *  or live Git result has changes, else Files (a host `initialTab` overrides).
+   *  has changes, else Files (a host `initialTab` overrides). Choosing a tab
+   *  never performs hidden live workspace I/O.
    *  null while that source resolves, or permanently when neither Changes nor
    *  Files is enabled; the choice latches once. */
   defaultTab: string | null;
@@ -312,9 +378,18 @@ export function useSandboxWorkspaceTabs(
     onNotify,
     browserWebSocketFactory,
     computerWebSocketFactory,
+    browserExtensionSetupUrl,
     requestedFilePath,
     requestedFileRequestId,
+    requestedFileLine,
     onOpenFile,
+    initialFilePath,
+    onFilePathChange,
+    isFileNodeVisible,
+    initialBrowserSessionId,
+    onBrowserSessionIdChange,
+    initialComputerSessionId,
+    onComputerSessionIdChange,
     onOpenComputerSession,
     requestedComputerSessionId,
     requestedComputerRequestId,
@@ -338,7 +413,7 @@ export function useSandboxWorkspaceTabs(
         ...(placement ? { placement } : {}),
       });
       if (response.operation.state !== "completed" || response.session.lifecycle !== "active") {
-        throw new Error(response.operation.error?.message ?? "The computer could not be opened.");
+        throw new Error(response.operation.error?.message ?? "The desktop could not be opened.");
       }
       return {
         id: response.session.id,
@@ -356,6 +431,7 @@ export function useSandboxWorkspaceTabs(
   const resolvedActiveTab = activeTab ?? initialTab;
   const changesActive = resolvedActiveTab === WORKBENCH_TAB_CHANGES;
   const filesActive = resolvedActiveTab === WORKBENCH_TAB_FILES;
+  const turnInFlight = workspaceTurnInFlight(events);
   const surfaceIdentity = WORKBENCH_SURFACES.filter((surface) => surfaceSet.has(surface)).join(",");
 
   // The two box-warming INTENTS, each off by default and each
@@ -369,6 +445,11 @@ export function useSandboxWorkspaceTabs(
   const warmIntents =
     storedWarmIntents.sessionId === sessionId ? storedWarmIntents : emptyWarmIntents(sessionId);
   const { warmTerminal, warmFiles } = warmIntents;
+  // A host-requested file is itself explicit live-file intent. Derive the wake
+  // directly from the request instead of relying on a follow-up effect to copy
+  // it into local state; otherwise a missing or delayed effect leaves the file
+  // waiting for a sandbox that this hook never asks to start.
+  const filesWarmRequested = warmFiles || Boolean(requestedFilePath);
   const requestWarmIntent = useCallback(
     (intent: Exclude<keyof SessionWarmIntents, "sessionId">) => {
       setStoredWarmIntents((previous) => {
@@ -378,13 +459,12 @@ export function useSandboxWorkspaceTabs(
     },
     [sessionId],
   );
-
   // The session's machine fleet + the active-sandbox pointer. Drives the header
-  // chip (which machine + its connection state). Polls slowly — ambient context.
+  // chip (which machine + its connection state). Shares the session list poll.
   const machines = useMachines({
     workspaceId,
     sessionId,
-    pollIntervalMs: 8000,
+    pollIntervalMs: MACHINES_SESSION_POLL_MS,
     enabled: machineSurfaceEnabled,
   });
   const activeMachine: MachineView | null =
@@ -399,7 +479,7 @@ export function useSandboxWorkspaceTabs(
     attachTerminal: terminalEnabled && warmTerminal,
     // Explicit live-file intent only — NOT "the Files tab is open". A cold edit
     // or guarded-file open wakes the box; a glance at the tree/diff does not.
-    attachFiles: workspaceDataEnabled && warmFiles,
+    attachFiles: workspaceDataEnabled && filesWarmRequested,
   });
   const capabilities = caps.capabilities;
   const liveness = capabilities?.liveness;
@@ -409,6 +489,9 @@ export function useSandboxWorkspaceTabs(
   // is still pending.
   const liveIoLiveness = liveness ?? null;
   const fileSystemOn = capabilities?.FileSystem.available ?? false;
+  const fileSystemRoute = capabilities
+    ? { epoch: capabilities.leaseEpoch, root: capabilities.FileSystem.root }
+    : undefined;
   // The FS is writable only when it's live AND not read-only. A self-hosted box
   // that's offline (or any read-only advertisement) or a capture-served cold tree
   // must not offer create/rename/delete/edit affordances — you cannot mutate a
@@ -487,29 +570,22 @@ export function useSandboxWorkspaceTabs(
     if (advertised.length > 0) return advertised;
     return captureState.capture?.repos.map((repo) => repo.root) ?? [];
   }, [capabilities?.Git.repos, captureState.capture]);
-  const notifiedCaptureDegradedReason = useRef<{
-    sessionId: string;
-    reason: string | null;
-  }>({
-    sessionId,
-    reason: null,
-  });
-  if (notifiedCaptureDegradedReason.current.sessionId !== sessionId) {
-    notifiedCaptureDegradedReason.current = { sessionId, reason: null };
-  }
-  useEffect(() => {
-    const reason = captureState.degradedReason;
-    if (!reason || notifiedCaptureDegradedReason.current.reason === reason) return;
-    notifiedCaptureDegradedReason.current = { sessionId, reason };
-    onNotify?.({ kind: "error", message: captureDegradedMessage(reason) });
-  }, [sessionId, captureState.degradedReason, onNotify]);
-
   const files = useSandboxFiles(sessionId, {
     events,
     // No passive Channel-A reads while cold, even after a conclusive capture
     // miss. A missing capture gets an explicit "Open live workspace" gate.
     enabled: filesEnabled && (captureAvailable || (fileSystemOn && liveWorkspaceExpected)),
-    active: filesActive,
+    // A cold sandbox can become warm while the first agent command still owns
+    // startup. Do not race that command with an automatic Files read. Keeping
+    // this fence at turn scope also avoids unsafe millisecond gaps between
+    // sequential tool calls; rendered state and explicit user actions remain.
+    active: filesActive && !turnInFlight,
+    // A deliberate canonical absolute-path open browses in the selected target's
+    // advertised namespace, so the authoritative tree and link share exact paths.
+    ...(isCanonicalAbsoluteSandboxPath(requestedFilePath) && capabilities?.FileSystem.root
+      ? { rootPath: capabilities.FileSystem.root }
+      : {}),
+    ...(fileSystemRoute ? { route: fileSystemRoute } : {}),
     repoPaths,
     liveness: liveIoLiveness,
     capture: captureState.capture,
@@ -550,10 +626,11 @@ export function useSandboxWorkspaceTabs(
         : changesComparison === "branch"
           ? workspaceDataEnabled && (captureSupportsBranch || (gitOn && liveWorkspaceExpected))
           : workspaceDataEnabled && gitOn && liveWorkspaceExpected,
-    // Before the dock chooses its source-driven default, Git is the sole probe
-    // that may need to resolve that choice on a live workspace. Files remains
-    // dormant, avoiding the old duplicate full-tree read.
-    active: changesActive || resolvedActiveTab === null,
+    // Live Git belongs to the visible Changes surface. In particular, do not
+    // turn an unresolved/default tab into a hidden provider read: that races the
+    // agent's own sandbox commands and used to refresh after every tool output
+    // even while Files was visibly selected.
+    active: changesActive && !turnInFlight,
     repoPaths,
     liveness: liveIoLiveness,
     comparison: changesComparison,
@@ -597,19 +674,17 @@ export function useSandboxWorkspaceTabs(
     capabilitiesState: caps.state,
     activeMachineState: activeMachine?.state ?? null,
     activeIsSelfhosted: activeMachine?.kind === "selfhosted",
-    wantsWarm: (terminalEnabled && warmTerminal) || (workspaceDataEnabled && warmFiles),
+    wantsWarm: (terminalEnabled && warmTerminal) || (workspaceDataEnabled && filesWarmRequested),
     capturedAt: captureState.capturedAt,
   });
   const workspaceWaking = chip.state === "waking";
 
-  // The pre-paint default tab is decided from the first AUTHORITATIVE workspace
-  // source. A capture wins immediately on the cold/offline fast path; a warm box
-  // waits for live Git so a prior snapshot can never outrank the current tree.
-  // When the GET says no capture exists, `fileCount: 0` does NOT itself mean the
-  // working tree is clean. A captured-revision announce can
-  // resolve Changes earlier, but a pure embedder with no event preload still gets
-  // the correct live default. The choice latches once so later edits never steal
-  // the user's current tab.
+  // The pre-paint default comes only from the durable capture. Default selection
+  // must never dispatch live provider work: a live Git probe can overlap the
+  // agent's first command, and an uncontrolled dock used to keep that probe
+  // active forever after it visibly selected Files. A capture with reviewable
+  // changes opens Changes; no capture (or an empty one) opens Files. The choice
+  // latches once so later edits never steal the user's current tab.
   const defaultIdentity = `${sessionId}\u0000${surfaceIdentity}`;
   const defaultTabRef = useRef<{ identity: string; value: string | null }>({
     identity: defaultIdentity,
@@ -618,62 +693,32 @@ export function useSandboxWorkspaceTabs(
   if (defaultTabRef.current.identity !== defaultIdentity) {
     defaultTabRef.current = { identity: defaultIdentity, value: null };
   }
-  const captureIsAuthoritative =
-    !liveWorkspaceExpected && (liveness !== undefined || caps.error !== null);
   const captureHasChanges =
     (captureState.fileCount ?? 0) > 0 ||
     (captureState.capture?.repos.some((repo) => (repo.branchDiff?.length ?? 0) > 0) ?? false);
   const captureUnavailable =
-    (captureState.fileCount === 0 && !captureHasChanges) || captureState.error !== null;
-  const implicitBranchFallbackPending =
-    changesComparison === "branch" &&
-    git.error !== null &&
-    storedChangesComparison?.sessionId !== sessionId;
+    !captureState.loading &&
+    ((captureState.fileCount === 0 && !captureHasChanges) || captureState.error !== null);
   if (defaultTabRef.current.value === null) {
     if (initialTab && (!isWorkbenchSurface(initialTab) || surfaceSet.has(initialTab))) {
       defaultTabRef.current.value = initialTab;
-    } else if (git.source === "live") {
-      defaultTabRef.current.value = sourceDrivenDefaultTab(
-        git.diff.length > 0,
-        changesEnabled,
-        filesEnabled,
-      );
-    } else if (
-      captureIsAuthoritative &&
-      captureState.fileCount !== null &&
-      captureState.available
-    ) {
+    } else if (captureState.fileCount !== null && captureState.available) {
       defaultTabRef.current.value = sourceDrivenDefaultTab(
         captureHasChanges,
         changesEnabled,
         filesEnabled,
       );
+    } else if (captureUnavailable && initialWorkspaceTab(events) === WORKBENCH_TAB_CHANGES) {
+      defaultTabRef.current.value = sourceDrivenDefaultTab(true, changesEnabled, filesEnabled);
     } else if (
-      captureIsAuthoritative &&
-      captureUnavailable &&
-      initialWorkspaceTab(events) === WORKBENCH_TAB_CHANGES
+      !captureState.loading &&
+      (captureState.fileCount !== null || captureState.error !== null)
     ) {
-      defaultTabRef.current.value = sourceDrivenDefaultTab(true, changesEnabled, filesEnabled);
-    } else if (captureUnavailable && caps.error) {
-      // The Changes surface owns the truthful sandbox-unavailable state + retry.
-      // Files would misleadingly describe this as a missing filesystem.
-      defaultTabRef.current.value = sourceDrivenDefaultTab(true, changesEnabled, filesEnabled);
-    } else if (captureIsAuthoritative && captureState.fileCount !== null && captureUnavailable) {
-      // No durable review surface exists and the machine is resting. Files owns
-      // the explicit wake gate; do not issue a live Git probe merely to choose a
-      // tab.
-      defaultTabRef.current.value = sourceDrivenDefaultTab(false, changesEnabled, filesEnabled);
-    } else if (captureState.available && git.error && captureState.fileCount !== null) {
-      // A warm live read failed but the durable capture is intact: retain an
-      // immediate, deterministic review surface instead of hanging unresolved.
-      defaultTabRef.current.value = sourceDrivenDefaultTab(
-        captureHasChanges,
-        changesEnabled,
-        filesEnabled,
-      );
-    } else if (captureUnavailable && git.error && !implicitBranchFallbackPending) {
-      // No capture and live Git failed: Files is the least surprising fallback
-      // after the implicit branch-to-working fallback has also had its chance.
+      // Metadata may arrive before a signed manifest. While that manifest is
+      // loading, neither a positive count nor zero (committed-only changes)
+      // proves an unavailable capture, so leave the default unresolved.
+      // No durable review surface exists. Files owns the explicit live-workspace
+      // gate; a user can open Changes deliberately if they need a fresh Git read.
       defaultTabRef.current.value = sourceDrivenDefaultTab(false, changesEnabled, filesEnabled);
     }
   }
@@ -687,7 +732,8 @@ export function useSandboxWorkspaceTabs(
     if (changesEnabled)
       list.push({
         id: WORKBENCH_TAB_CHANGES,
-        label: <WorkbenchTabLabel icon={<GitCompareArrowsIcon />}>Changes</WorkbenchTabLabel>,
+        label: "Changes",
+        icon: <GitCompareArrowsIcon />,
         badge: dirtyCount > 0 ? <DirtyBadge count={dirtyCount} /> : undefined,
         content: (
           <ChangesTabBody
@@ -695,6 +741,7 @@ export function useSandboxWorkspaceTabs(
             comparison={changesComparison}
             onComparisonChange={setChangesComparison}
             captureAvailable={captureAvailable}
+            captureDegraded={captureState.degradedReason !== null}
             captureRevision={captureState.revision}
             capturePending={capturePending}
             liveWorkspaceExpected={liveWorkspaceExpected}
@@ -719,12 +766,14 @@ export function useSandboxWorkspaceTabs(
     if (filesEnabled)
       list.push({
         id: WORKBENCH_TAB_FILES,
-        label: <WorkbenchTabLabel icon={<FileCode2Icon />}>Files</WorkbenchTabLabel>,
+        label: "Files",
+        icon: <FileCode2Icon />,
         content: (
-          <SandboxFiles
+          <FilesTabBody
             key={sessionId}
             files={files}
             git={git}
+            isNodeVisible={isFileNodeVisible}
             fileSystemAvailable={fileSystemOn || captureAvailable}
             editable={
               filesEditable && files.source === "live" && files.error === null && !files.loading
@@ -738,7 +787,20 @@ export function useSandboxWorkspaceTabs(
             }
             workspaceWaking={!liveWorkspaceExpected && !captureAvailable && workspaceWaking}
             liveWorkspaceReady={liveWorkspaceExpected}
-            onWakeWorkspace={() => requestWarmIntent("warmFiles")}
+            workspaceError={
+              caps.error ??
+              (caps.viewerCapReached
+                ? new Error(
+                    "The live workspace viewer limit has been reached. Close another viewer and retry.",
+                  )
+                : filesWarmRequested && caps.state === "on-demand" && !fileSystemOn
+                  ? new Error("This machine does not currently expose a live file system.")
+                  : null)
+            }
+            onWakeWorkspace={() => {
+              if (filesWarmRequested) caps.renegotiate();
+              else requestWarmIntent("warmFiles");
+            }}
             {...(requestedFilePath
               ? {
                   requestedPath: requestedFilePath,
@@ -746,11 +808,16 @@ export function useSandboxWorkspaceTabs(
                     ? { requestedPathRequestId: requestedFileRequestId }
                     : {}),
                   requestedPathReady: sandboxAcceptsLiveIo(liveness),
+                  ...(requestedFileLine != null && requestedFileLine > 0
+                    ? { requestedLine: requestedFileLine }
+                    : {}),
                 }
               : {})}
             // Ordinary capture browsing does not warm a box. The first edit — or an
             // explicit guarded-file open from Changes — is deliberate live-file intent.
             onEditIntent={() => requestWarmIntent("warmFiles")}
+            initialSelectedPath={initialFilePath}
+            onSelectedPathChange={onFilePathChange}
             className="h-full"
           />
         ),
@@ -760,7 +827,8 @@ export function useSandboxWorkspaceTabs(
     if (terminalOn) {
       list.push({
         id: WORKBENCH_TAB_TERMINAL,
-        label: <WorkbenchTabLabel icon={<SquareTerminalIcon />}>Terminal</WorkbenchTabLabel>,
+        label: "Terminal",
+        icon: <SquareTerminalIcon />,
         content: (
           <div className="h-full bg-og-bg p-1">
             <SandboxTerminal
@@ -785,7 +853,8 @@ export function useSandboxWorkspaceTabs(
     if (browserEnabled) {
       list.push({
         id: WORKBENCH_TAB_BROWSER,
-        label: <WorkbenchTabLabel icon={<Globe2Icon />}>Browser</WorkbenchTabLabel>,
+        label: "Browser",
+        icon: <Globe2Icon />,
         content: (
           <Suspense fallback={<WorkbenchSurfaceLoading name="Browser" />}>
             <LazyBrowserViewer
@@ -802,10 +871,14 @@ export function useSandboxWorkspaceTabs(
               // start BrowserViewer—the lazy panel is still unmounted until the
               // user/agent first visits it.
               enabled={workspaceVisible}
+              active={resolvedActiveTab === WORKBENCH_TAB_BROWSER}
               onNotify={onNotify}
+              initialBrowserSessionId={initialBrowserSessionId}
+              onBrowserSessionIdChange={onBrowserSessionIdChange}
               {...(desktopEnabled ? { createLinkedComputer } : {})}
               {...(onOpenComputerSession ? { onOpenComputer: onOpenComputerSession } : {})}
               {...(browserWebSocketFactory ? { webSocketFactory: browserWebSocketFactory } : {})}
+              {...(browserExtensionSetupUrl ? { browserExtensionSetupUrl } : {})}
               className="h-full"
             />
           </Suspense>
@@ -818,9 +891,10 @@ export function useSandboxWorkspaceTabs(
     if (desktopEnabled) {
       list.push({
         id: WORKBENCH_TAB_DESKTOP,
-        label: <WorkbenchTabLabel icon={<MonitorIcon />}>Computer</WorkbenchTabLabel>,
+        label: "Desktop",
+        icon: <MonitorIcon />,
         content: (
-          <Suspense fallback={<WorkbenchSurfaceLoading name="Computer" />}>
+          <Suspense fallback={<WorkbenchSurfaceLoading name="Desktop" />}>
             <LazyComputerViewer
               key={sessionId}
               client={client}
@@ -832,6 +906,8 @@ export function useSandboxWorkspaceTabs(
               // second and later Computer opens local-machine fast.
               enabled={workspaceVisible}
               onNotify={onNotify}
+              initialComputerSessionId={initialComputerSessionId}
+              onComputerSessionIdChange={onComputerSessionIdChange}
               requestedComputerSessionId={requestedComputerSessionId}
               requestedComputerRequestId={requestedComputerRequestId}
               {...(computerWebSocketFactory ? { webSocketFactory: computerWebSocketFactory } : {})}
@@ -852,11 +928,20 @@ export function useSandboxWorkspaceTabs(
     browserEnabled,
     desktopEnabled,
     captureAvailable,
+    captureState.degradedReason,
     dirtyCount,
     warmTerminal,
     requestedFilePath,
     requestedFileRequestId,
+    requestedFileLine,
     onOpenFile,
+    initialFilePath,
+    onFilePathChange,
+    isFileNodeVisible,
+    initialBrowserSessionId,
+    onBrowserSessionIdChange,
+    initialComputerSessionId,
+    onComputerSessionIdChange,
     onOpenComputerSession,
     requestedComputerSessionId,
     requestedComputerRequestId,
@@ -879,6 +964,8 @@ export function useSandboxWorkspaceTabs(
     caps.state,
     caps.error,
     caps.viewerCapReached,
+    caps.renegotiate,
+    filesWarmRequested,
     requestWarmIntent,
     createLinkedComputer,
   ]);
@@ -913,14 +1000,39 @@ export type SandboxWorkspaceProps = ClientOverride & {
   /** Host tabs injected AFTER the workbench tabs (e.g. a "Debug" tab). */
   trailingTabs?: WorkspaceTab[] | undefined;
   /** Override the pre-paint default tab (e.g. a host landing tab id). When
-   *  omitted the workbench decides from capture, then live Git when no capture exists. */
+   *  omitted the workbench decides from the durable workspace capture. */
   initialTab?: string | undefined;
+  onActiveTabChange?: ((activeTab: string) => void) | undefined;
+  /** Open a built-in or host-injected tab. A new requestId reopens the same tab. */
+  openTabRequest?: { tab: string; requestId: number } | null | undefined;
+  initialFilePath?: string | null | undefined;
+  onFilePathChange?: ((path: string | null) => void) | undefined;
+  /** Presentation-only filter for Files tree nodes and selected-file viewing. */
+  isFileNodeVisible?: FileNodeVisibilityPredicate | undefined;
+  /**
+   * Host request to open a workspace file (and optional line) in Files. A new
+   * `requestId` re-opens even the same path.
+   */
+  openFileRequest?:
+    | {
+        path: string;
+        line?: number | null;
+        requestId: number;
+      }
+    | null
+    | undefined;
+  initialBrowserSessionId?: string | null | undefined;
+  onBrowserSessionIdChange?: ((browserSessionId: string | null) => void) | undefined;
+  initialComputerSessionId?: string | null | undefined;
+  onComputerSessionIdChange?: ((computerSessionId: string | null) => void) | undefined;
   /** Host-routed notifications (no toast dependency in the package). */
   onNotify?: ((notification: WorkspaceNotification) => void) | undefined;
   /** Alternate Browser frame transport for non-browser runtimes and deterministic tests. */
   browserWebSocketFactory?: BrowserFrameWebSocketFactory | undefined;
   /** Alternate Computer frame transport for non-browser runtimes and deterministic tests. */
   computerWebSocketFactory?: ComputerFrameWebSocketFactory | undefined;
+  /** Host-owned setup page or store listing for attaching an existing Chrome profile. */
+  browserExtensionSetupUrl?: string | undefined;
   /** Controlled collapsed state for hosts with their own dock toggle. */
   collapsed?: boolean | undefined;
   onCollapsedChange?: ((collapsed: boolean) => void) | undefined;
@@ -951,9 +1063,20 @@ export function SandboxWorkspace(props: SandboxWorkspaceProps): ReactNode {
     leadingTabs,
     trailingTabs,
     initialTab,
+    onActiveTabChange,
+    openTabRequest,
+    initialFilePath,
+    onFilePathChange,
+    isFileNodeVisible,
+    openFileRequest,
+    initialBrowserSessionId,
+    onBrowserSessionIdChange,
+    initialComputerSessionId,
+    onComputerSessionIdChange,
     onNotify,
     browserWebSocketFactory,
     computerWebSocketFactory,
+    browserExtensionSetupUrl,
     collapsed,
     onCollapsedChange,
     showCollapseControl,
@@ -972,6 +1095,7 @@ export function SandboxWorkspace(props: SandboxWorkspaceProps): ReactNode {
   const [requestedFile, setRequestedFile] = useState<{
     sessionId: string;
     path: string;
+    line: number | null;
     requestId: number;
   } | null>(null);
   const [requestedComputer, setRequestedComputer] = useState<{
@@ -982,15 +1106,55 @@ export function SandboxWorkspace(props: SandboxWorkspaceProps): ReactNode {
   const nextFileRequestId = useRef(0);
   const nextComputerRequestId = useRef(0);
   const selectedTab = storedSelection?.sessionId === sessionId ? storedSelection.tab : null;
+  const handledTabRequest = useRef<{ sessionId: string; requestId: number } | null>(null);
+  useEffect(() => {
+    if (
+      !openTabRequest ||
+      (handledTabRequest.current?.sessionId === sessionId &&
+        handledTabRequest.current.requestId === openTabRequest.requestId)
+    )
+      return;
+    const available =
+      [...(leadingTabs ?? []), ...(trailingTabs ?? [])].some(
+        (tab) => tab.id === openTabRequest.tab,
+      ) || (surfaces ?? WORKBENCH_SURFACES).some((tab) => tab === openTabRequest.tab);
+    if (!available) return;
+    handledTabRequest.current = { sessionId, requestId: openTabRequest.requestId };
+    setStoredSelection({ sessionId, tab: openTabRequest.tab });
+    onActiveTabChange?.(openTabRequest.tab);
+    onCollapsedChange?.(false);
+  }, [
+    openTabRequest,
+    sessionId,
+    leadingTabs,
+    trailingTabs,
+    surfaces,
+    onActiveTabChange,
+    onCollapsedChange,
+  ]);
   const activeTabHint = selectedTab ?? initialTab ?? leadingTabs?.[0]?.id ?? null;
   const openFile = useCallback(
-    (path: string) => {
-      nextFileRequestId.current += 1;
-      setRequestedFile({ sessionId, path, requestId: nextFileRequestId.current });
+    (path: string, line?: number | null) => {
+      setRequestedFile({
+        sessionId,
+        path,
+        line: line != null && line > 0 ? line : null,
+        requestId: ++nextFileRequestId.current,
+      });
       setStoredSelection({ sessionId, tab: WORKBENCH_TAB_FILES });
+      onActiveTabChange?.(WORKBENCH_TAB_FILES);
+      onFilePathChange?.(path);
+      onCollapsedChange?.(false);
     },
-    [sessionId],
+    [onActiveTabChange, onCollapsedChange, onFilePathChange, sessionId],
   );
+  const handledOpenFileRequestId = useRef<number | null>(null);
+  useEffect(() => {
+    if (!openFileRequest) return;
+    if (handledOpenFileRequestId.current === openFileRequest.requestId) return;
+    handledOpenFileRequestId.current = openFileRequest.requestId;
+    openFile(openFileRequest.path, openFileRequest.line);
+  }, [openFile, openFileRequest]);
   const openComputer = useCallback(
     (computerSessionId: string) => {
       nextComputerRequestId.current += 1;
@@ -1000,8 +1164,10 @@ export function SandboxWorkspace(props: SandboxWorkspaceProps): ReactNode {
         requestId: nextComputerRequestId.current,
       });
       setStoredSelection({ sessionId, tab: WORKBENCH_TAB_DESKTOP });
+      onActiveTabChange?.(WORKBENCH_TAB_DESKTOP);
+      onComputerSessionIdChange?.(computerSessionId);
     },
-    [sessionId],
+    [onActiveTabChange, onComputerSessionIdChange, sessionId],
   );
 
   const {
@@ -1020,8 +1186,17 @@ export function SandboxWorkspace(props: SandboxWorkspaceProps): ReactNode {
     ...(onNotify ? { onNotify } : {}),
     ...(browserWebSocketFactory ? { browserWebSocketFactory } : {}),
     ...(computerWebSocketFactory ? { computerWebSocketFactory } : {}),
+    ...(browserExtensionSetupUrl ? { browserExtensionSetupUrl } : {}),
+    initialFilePath,
+    onFilePathChange,
+    isFileNodeVisible,
+    initialBrowserSessionId,
+    onBrowserSessionIdChange,
+    initialComputerSessionId,
+    onComputerSessionIdChange,
     requestedFilePath: requestedFile?.sessionId === sessionId ? requestedFile.path : null,
     requestedFileRequestId: requestedFile?.sessionId === sessionId ? requestedFile.requestId : null,
+    requestedFileLine: requestedFile?.sessionId === sessionId ? requestedFile.line : null,
     onOpenFile: openFile,
     onOpenComputerSession: openComputer,
     requestedComputerSessionId:
@@ -1040,9 +1215,19 @@ export function SandboxWorkspace(props: SandboxWorkspaceProps): ReactNode {
   const activeTab =
     preferredTab && tabs.some((tab) => tab.id === preferredTab) ? preferredTab : tabs[0]?.id;
   const selectTab = useCallback(
-    (tab: string) => setStoredSelection({ sessionId, tab }),
-    [sessionId],
+    (tab: string) => {
+      setStoredSelection({ sessionId, tab });
+      onActiveTabChange?.(tab);
+    },
+    [onActiveTabChange, sessionId],
   );
+  useEffect(() => {
+    if (selectedTab !== null || defaultTab === null) return;
+    // Once the source-driven choice resolves, make it the real controlled
+    // selection. Without this handoff the dock could visibly show Files while
+    // the data hooks continued treating the selection as unresolved.
+    setStoredSelection({ sessionId, tab: defaultTab });
+  }, [defaultTab, selectedTab, sessionId]);
 
   return (
     <WorkspaceDock
@@ -1050,7 +1235,12 @@ export function SandboxWorkspace(props: SandboxWorkspaceProps): ReactNode {
       tabs={tabs}
       {...(activeTab !== undefined ? { activeTab } : {})}
       onActiveTabChange={selectTab}
-      {...(machine.enabled
+      // Browser and Desktop select independent workspace resources, potentially
+      // on another placement. Their own viewers report runtime status; the
+      // agent-session machine chip must not describe those resources.
+      {...(machine.enabled &&
+      activeTab !== WORKBENCH_TAB_BROWSER &&
+      activeTab !== WORKBENCH_TAB_DESKTOP
         ? {
             headerAccessory: <MachineStateChip chip={machine.chip} />,
           }
@@ -1086,7 +1276,7 @@ function chipDotClass(state: MachineChip["state"]): string {
 }
 
 /**
- * The dock-header machine status: one quiet, truthful live/waking/offline
+ * The dock-header machine status: one quiet, truthful live/waking/resting
  * indicator. It is intentionally not interactive; detailed machine controls do
  * not belong in a transient popover above the workspace tabs.
  */
@@ -1170,6 +1360,7 @@ function ChangesTabContent({
   git,
   comparison,
   captureAvailable,
+  captureDegraded,
   captureRevision,
   capturePending,
   liveWorkspaceExpected,
@@ -1183,6 +1374,7 @@ function ChangesTabContent({
   git: UseSandboxGitResult;
   comparison: SandboxGitComparison;
   captureAvailable: boolean;
+  captureDegraded: boolean;
   captureRevision: number | null;
   capturePending: boolean;
   liveWorkspaceExpected: boolean;
@@ -1276,6 +1468,8 @@ function ChangesTabContent({
   }
 
   if (!liveWorkspaceExpected && (comparison !== "working" || !captureAvailable)) {
+    // Staged changes are live-only; a failed saved preview is not their blocker.
+    const previewUnavailable = captureDegraded && !captureAvailable && comparison !== "staged";
     return (
       <CenteredState
         icon={
@@ -1284,22 +1478,30 @@ function ChangesTabContent({
               className="size-5 animate-spin motion-reduce:animate-none"
               aria-hidden
             />
+          ) : previewUnavailable ? (
+            <TriangleAlertIcon className="size-5" aria-hidden />
           ) : (
             <CpuIcon className="size-5" aria-hidden />
           )
         }
       >
         <p className="text-og-sm font-medium text-og-fg">
-          {workspaceWaking ? "Waking workspace" : "Workspace is resting"}
+          {workspaceWaking
+            ? "Waking workspace"
+            : previewUnavailable
+              ? "Saved changes preview is unavailable"
+              : "Workspace is resting"}
         </p>
         <p className="text-og-sm leading-5 text-og-fg-subtle">
           {workspaceWaking
             ? "Connecting to the live working tree…"
-            : comparison === "branch"
-              ? "Wake the sandbox to compare this branch with the remote default branch."
-              : comparison === "staged"
-                ? "Wake the sandbox to inspect staged changes."
-                : "No captured revision is available yet. Wake the sandbox to inspect uncommitted changes."}
+            : previewUnavailable
+              ? "Open the live workspace to view current changes."
+              : comparison === "branch"
+                ? "Wake the sandbox to compare this branch with the remote default branch."
+                : comparison === "staged"
+                  ? "Wake the sandbox to inspect staged changes."
+                  : "No captured revision is available yet. Wake the sandbox to inspect uncommitted changes."}
         </p>
         {!workspaceWaking ? (
           <DockActionButton onClick={onWake}>