@opengeni/react 0.13.0 → 0.20.0

package/src/components/sandbox-workspace.tsx

@@ -12,15 +12,23 @@
 // (never an app context), notifications flow through an optional `onNotify` prop
 // (no `sonner` import), and every surface renders with package primitives + og
 // tokens only. `apps/web` consumes this through the exact public surface an
-// external embedder (cloudgeni #1577) uses — that is criterion F1.
+// external embedder uses — that is criterion F1.
 import { type ReactNode, useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { Popover } from "radix-ui";
 import type { SessionEvent } from "@opengeni/sdk";
-import { CpuIcon, LaptopIcon, RefreshCwIcon } from "lucide-react";
+import {
+  CircleCheckIcon,
+  CpuIcon,
+  LaptopIcon,
+  LoaderCircleIcon,
+  RefreshCwIcon,
+  TriangleAlertIcon,
+} from "lucide-react";
 
 import { type ClientOverride, useOpenGeni } from "../provider";
 import { cn } from "../lib/cn";
 import { xtermThemeFromTokens } from "../lib/xterm-theme";
+import { usePortalTokenStyle } from "../lib/use-portal-token-style";
 import { useSessionCapabilities } from "../hooks/use-session-capabilities";
 import { useSandboxFiles } from "../hooks/use-sandbox-files";
 import { useSandboxGit, type UseSandboxGitResult } from "../hooks/use-sandbox-git";
@@ -44,6 +52,37 @@ export type WorkspaceNotification = { kind: "error" | "info"; message: string };
 /** The workbench's canonical tab ids (a host injects extras around these). */
 export const WORKBENCH_TAB_CHANGES = "changes";
 export const WORKBENCH_TAB_FILES = "files";
+export const WORKBENCH_TAB_TERMINAL = "terminal";
+export const WORKBENCH_TAB_DESKTOP = "desktop";
+
+/**
+ * The built-in workbench surfaces in their canonical display order. Hosts can
+ * pass a subset through `surfaces`; omission preserves the complete standalone
+ * workbench.
+ */
+export const WORKBENCH_SURFACES = [
+  WORKBENCH_TAB_CHANGES,
+  WORKBENCH_TAB_FILES,
+  WORKBENCH_TAB_TERMINAL,
+  WORKBENCH_TAB_DESKTOP,
+] as const;
+
+export type SandboxWorkspaceSurface = (typeof WORKBENCH_SURFACES)[number];
+
+function isWorkbenchSurface(value: string): value is SandboxWorkspaceSurface {
+  return (WORKBENCH_SURFACES as readonly string[]).includes(value);
+}
+
+function sourceDrivenDefaultTab(
+  hasChanges: boolean,
+  changesEnabled: boolean,
+  filesEnabled: boolean,
+): string | null {
+  if (hasChanges && changesEnabled) return WORKBENCH_TAB_CHANGES;
+  if (filesEnabled) return WORKBENCH_TAB_FILES;
+  if (changesEnabled) return WORKBENCH_TAB_CHANGES;
+  return null;
+}
 
 function captureDegradedMessage(reason: string): string {
   switch (reason) {
@@ -62,11 +101,9 @@ function captureDegradedMessage(reason: string): string {
  * "changes exist → Changes, else Files" needs zero machine round-trips. A host
  * `override` (e.g. a landing "run" tab) wins when supplied.
  *
- * NOTE: the dock no longer uses this for its default tab — `<SandboxWorkspace>`
- * now derives the default from its OWN capture fetch (`useWorkspaceCapture`'s
- * `fileCount`), so a pure embedder needs no events-at-mount contract (Refinement
- * 2). This remains exported as a standalone helper for hosts that already hold
- * the event log and want the same decision without the capture fetch.
+ * `<SandboxWorkspace>` uses this only as an optional early hint after its own
+ * capture GET reports no durable capture. A pure embedder needs no events-at-mount
+ * contract: it falls through to authoritative live Git instead.
  */
 export function initialWorkspaceTab(
   events: SessionEvent[] | undefined,
@@ -117,7 +154,9 @@ function sandboxProvisionInFlight(events: SessionEvent[]): boolean {
 }
 
 export type WorkspaceMachine = {
-  /** The derived live/waking/offline chip model (dossier §3 #10). */
+  /** Whether at least one built-in workbench surface is enabled. */
+  enabled: boolean;
+  /** The derived live/waking/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. */
@@ -131,22 +170,35 @@ export type UseSandboxWorkspaceTabsOptions = ClientOverride & {
   sessionId: string;
   /** Live event log (usually `useSessionEvents().events`). */
   events: SessionEvent[];
-  /** Override the capture-driven default tab (e.g. a host landing tab id). When
-   *  omitted the workbench picks Changes-vs-Files from its own capture fetch. */
+  /**
+   * Built-in surfaces this host wants to expose. Omit for all four. A disabled
+   * surface is behaviorally dormant: its data hooks, warm intents, stream
+   * attachment, and navigation callbacks are not activated.
+   */
+  surfaces?: readonly SandboxWorkspaceSurface[] | undefined;
+  /** Override the source-driven default tab (e.g. a host landing tab id). When
+   *  omitted the workbench picks Changes-vs-Files from capture or live Git. */
   initialTab?: string | null | undefined;
   /** Host-routed notifications (mutation errors, desktop-consent failures). The
    *  package never imports a toast library — the host decides how to surface. */
   onNotify?: ((notification: WorkspaceNotification) => void) | 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;
+  /** Route a guarded diff into the host's Files tab. */
+  onOpenFile?: ((path: string) => void) | undefined;
 };
 
 export type UseSandboxWorkspaceTabsResult = {
   /** Changes | Files | Terminal | Desktop (capability-gated where noted). */
   tabs: WorkspaceTab[];
-  /** The capture-driven default tab: Changes when the session has changes, else
-   *  Files (a host `initialTab` overrides). null during the brief window before the
-   *  capture GET first resolves (and no host override was given) — consumers render
-   *  their dock's own first-tab fallback until it latches, which it does ONCE, so it
-   *  never causes a post-render switch. */
+  /** The source-driven default tab: Changes when the first authoritative capture
+   *  or live Git result has changes, else Files (a host `initialTab` overrides).
+   *  null while that source resolves, or permanently when neither Changes nor
+   *  Files is enabled; the choice latches once. */
   defaultTab: string | null;
   /** The machine-state model for the dock-header chip. */
   machine: WorkspaceMachine;
@@ -156,7 +208,7 @@ type SessionWarmIntents = {
   sessionId: string;
   watchDesktop: boolean;
   warmTerminal: boolean;
-  warmEdit: boolean;
+  warmFiles: boolean;
 };
 
 function emptyWarmIntents(sessionId: string): SessionWarmIntents {
@@ -164,7 +216,7 @@ function emptyWarmIntents(sessionId: string): SessionWarmIntents {
     sessionId,
     watchDesktop: false,
     warmTerminal: false,
-    warmEdit: false,
+    warmFiles: false,
   };
 }
 
@@ -177,20 +229,30 @@ export function useSandboxWorkspaceTabs(
   options: UseSandboxWorkspaceTabsOptions,
 ): UseSandboxWorkspaceTabsResult {
   const { client, workspaceId } = useOpenGeni(options);
-  const { sessionId, events, onNotify } = options;
+  const { sessionId, events, onNotify, requestedFilePath, requestedFileRequestId, onOpenFile } =
+    options;
   const initialTab = options.initialTab ?? null;
+  const requestedSurfaces = options.surfaces ?? WORKBENCH_SURFACES;
+  const surfaceSet = new Set<SandboxWorkspaceSurface>(requestedSurfaces);
+  const changesEnabled = surfaceSet.has(WORKBENCH_TAB_CHANGES);
+  const filesEnabled = surfaceSet.has(WORKBENCH_TAB_FILES);
+  const terminalEnabled = surfaceSet.has(WORKBENCH_TAB_TERMINAL);
+  const desktopEnabled = surfaceSet.has(WORKBENCH_TAB_DESKTOP);
+  const workspaceDataEnabled = changesEnabled || filesEnabled;
+  const anySurfaceEnabled = workspaceDataEnabled || terminalEnabled || desktopEnabled;
+  const surfaceIdentity = WORKBENCH_SURFACES.filter((surface) => surfaceSet.has(surface)).join(",");
 
-  // The three — and only three — box-warming INTENTS, each off by default and each
+  // The three box-warming INTENTS, each off by default and each
   // flipped true by a genuine user action (never on mount, never on a passive
   // capture glance): desktop watch consent, terminal engagement (`onActivate`), and
-  // the first wake-on-edit keystroke in the Files editor. Browsing capture-served
+  // a deliberate live-file open/edit in Files. Browsing capture-served
   // Changes/Files warms nothing — that is the whole point of Refinement 1.
   const [storedWarmIntents, setStoredWarmIntents] = useState<SessionWarmIntents>(() =>
     emptyWarmIntents(sessionId),
   );
   const warmIntents =
     storedWarmIntents.sessionId === sessionId ? storedWarmIntents : emptyWarmIntents(sessionId);
-  const { watchDesktop, warmTerminal, warmEdit } = warmIntents;
+  const { watchDesktop, warmTerminal, warmFiles } = warmIntents;
   const requestWarmIntent = useCallback(
     (intent: Exclude<keyof SessionWarmIntents, "sessionId">) => {
       setStoredWarmIntents((previous) => {
@@ -207,6 +269,7 @@ export function useSandboxWorkspaceTabs(
     workspaceId,
     sessionId,
     pollIntervalMs: 8000,
+    enabled: anySurfaceEnabled,
   });
   const activeMachine: MachineView | null =
     machines.machines.find((m) => m.sandboxId === machines.activeSandboxId) ??
@@ -215,11 +278,12 @@ export function useSandboxWorkspaceTabs(
 
   const caps = useSessionCapabilities(sessionId, {
     events,
-    attachDesktop: watchDesktop,
-    attachTerminal: warmTerminal,
-    // Edit intent only — NOT "the Files tab is open". A cold edit warms the box
-    // (that is the wake); a cold glance at the tree/diff does not.
-    attachFiles: warmEdit,
+    enabled: anySurfaceEnabled,
+    attachDesktop: desktopEnabled && watchDesktop,
+    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,
   });
   const capabilities = caps.capabilities;
   const liveness = capabilities?.liveness;
@@ -227,13 +291,17 @@ export function useSandboxWorkspaceTabs(
   // 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
-  // machine you can't reach (dossier §12-A2/C3). Tree-structure ops need a warm
+  // machine you can't reach (C3). Tree-structure ops need a warm
   // writable box; content editing on a cold CLOUD box is the wake-on-edit path in
   // the editor, not tree mutation.
   const fsReadOnly = capabilities?.FileSystem.readOnly ?? false;
-  const filesEditable = fileSystemOn && !fsReadOnly;
+  // Mutations are live-only. A capture is a review artifact, never a writable
+  // surrogate for a sleeping machine; the user must deliberately open the live
+  // workspace before create/rename/delete/edit controls appear.
+  const filesEditable =
+    fileSystemOn && !fsReadOnly && (liveness === "warm" || liveness === "draining");
   const gitOn = capabilities?.Git.available ?? false;
-  const terminalOn = (capabilities?.Terminal.transport ?? null) !== null;
+  const terminalOn = terminalEnabled && (capabilities?.Terminal.transport ?? null) !== null;
   // The REAL interactive terminal is the ttyd pty-ws stream. When it's live the
   // legacy HTTP PTY must NOT run; `useSandboxTerminal` opens its HTTP PTY only as
   // the firehose-mode fallback (a backend without ttyd).
@@ -241,13 +309,14 @@ export function useSandboxWorkspaceTabs(
     capabilities?.Terminal.transport === "pty-ws" && Boolean(capabilities?.Terminal.url);
   const ptyCapable = (capabilities?.Terminal.ptyCapable ?? false) && !ptyWsLive;
   const terminal = useSandboxTerminal(sessionId, {
-    events,
-    interactive: ptyCapable,
+    events: terminalEnabled ? events : [],
+    interactive: terminalEnabled && ptyCapable,
     liveness,
   });
   const desktopAdvertised =
-    (capabilities?.DesktopStream.transport ?? null) !== null ||
-    capabilities?.DesktopStream.reason === "lease_cold";
+    desktopEnabled &&
+    ((capabilities?.DesktopStream.transport ?? null) !== null ||
+      capabilities?.DesktopStream.reason === "lease_cold");
 
   // Lazy provisioning (#315) creates the box mid-turn on the first sandbox tool
   // call, emitting sandbox.provision started→completed/failed on the live stream.
@@ -268,9 +337,27 @@ export function useSandboxWorkspaceTabs(
 
   // The cold-paint data source: the latest turn-end capture, fetched with a single
   // api round-trip on mount (no machine). Feeds the Files tree + the Changes/Git
-  // diff when the box is not warm; a warm box always wins (live path unchanged).
-  const captureState = useWorkspaceCapture(sessionId, { events });
+  // diff immediately; a warm box reconciles live without discarding the capture
+  // when that provider read is temporarily unavailable.
+  const captureState = useWorkspaceCapture(sessionId, {
+    events,
+    enabled: workspaceDataEnabled,
+  });
   const captureAvailable = captureState.available;
+  const liveWorkspaceExpected = liveness === "warm" || liveness === "draining";
+  // Capability negotiation and capture resolution are independent requests. A
+  // cold capability document can win that race by a few milliseconds; enabling
+  // the leaf hooks in that window would make them interpret `capture: null` as a
+  // real miss and issue Channel-A reads, waking the very box the capture exists
+  // to avoid. Wait until the capture request has conclusively resolved. A warm
+  // workspace never waits on this server-side snapshot.
+  const capturePending =
+    !liveWorkspaceExpected && (captureState.fileCount === null || captureState.loading);
+  const repoPaths = useMemo(() => {
+    const advertised = capabilities?.Git.repos ?? [];
+    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;
@@ -290,7 +377,9 @@ export function useSandboxWorkspaceTabs(
 
   const files = useSandboxFiles(sessionId, {
     events,
-    enabled: fileSystemOn || captureAvailable,
+    // 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)),
     liveness,
     capture: captureState.capture,
     // A reverted optimistic mutation (e.g. a 409 rename collision) surfaces as a
@@ -303,14 +392,18 @@ export function useSandboxWorkspaceTabs(
   });
   const git = useSandboxGit(sessionId, {
     events,
-    enabled: gitOn || captureAvailable,
+    enabled: workspaceDataEnabled && (captureAvailable || (gitOn && liveWorkspaceExpected)),
+    repoPaths,
     liveness,
     capture: captureState.capture,
   });
   const stagedGit = useSandboxGit(sessionId, {
     events,
-    enabled: gitOn,
+    // Captures intentionally expose one combined review diff, not a staged
+    // index. Never probe the live index while the lease is cold.
+    enabled: filesEnabled && gitOn && liveWorkspaceExpected,
     staged: true,
+    repoPaths,
     liveness,
     capture: captureState.capture,
   });
@@ -319,7 +412,7 @@ export function useSandboxWorkspaceTabs(
   // belongs in the package (an embedder's theme toggle drives it too).
   const [xtermTheme, setXtermTheme] = useState<XtermTheme | undefined>(undefined);
   useEffect(() => {
-    if (typeof document === "undefined") return;
+    if (!terminalEnabled || typeof document === "undefined") return;
     const derive = () => setXtermTheme(xtermThemeFromTokens());
     derive();
     const observer = new MutationObserver(derive);
@@ -328,7 +421,7 @@ export function useSandboxWorkspaceTabs(
       attributeFilter: ["data-og-theme", "class"],
     });
     return () => observer.disconnect();
-  }, []);
+  }, [terminalEnabled]);
 
   async function acknowledgeAndWatch() {
     try {
@@ -363,31 +456,79 @@ export function useSandboxWorkspaceTabs(
     capabilitiesState: caps.state,
     activeMachineState: activeMachine?.state ?? null,
     activeIsSelfhosted: activeMachine?.kind === "selfhosted",
-    wantsWarm: warmTerminal || watchDesktop || warmEdit,
+    wantsWarm:
+      (terminalEnabled && warmTerminal) ||
+      (desktopEnabled && watchDesktop) ||
+      (workspaceDataEnabled && warmFiles),
     capturedAt: captureState.capturedAt,
   });
+  const workspaceWaking = chip.state === "waking";
 
-  // The pre-paint default tab, decided from the workbench's OWN capture fetch — no
-  // embedder events-at-mount contract (Refinement 2). A host `initialTab` wins
-  // immediately; otherwise the default stays null until the capture GET first
-  // resolves, then latches Changes (changes exist) or Files, ONCE — live data can
-  // never switch it afterward. Committing at first-resolve — before the tab body's
-  // first CONTENT paint (both bodies show a connecting/loading state until the
-  // capture lands) — means the first real content is the correct tab, no switch. A
-  // pure embedder that never preloads events now gets the right default for free.
-  const defaultTabRef = useRef<{ sessionId: string; value: string | null }>({
-    sessionId,
+  // 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.
+  const defaultIdentity = `${sessionId}\u0000${surfaceIdentity}`;
+  const defaultTabRef = useRef<{ identity: string; value: string | null }>({
+    identity: defaultIdentity,
     value: null,
   });
-  if (defaultTabRef.current.sessionId !== sessionId) {
-    defaultTabRef.current = { sessionId, value: null };
+  if (defaultTabRef.current.identity !== defaultIdentity) {
+    defaultTabRef.current = { identity: defaultIdentity, value: null };
   }
+  const captureIsAuthoritative =
+    !liveWorkspaceExpected && (liveness !== undefined || caps.error !== null);
+  const captureUnavailable = captureState.fileCount === 0 || captureState.error !== null;
   if (defaultTabRef.current.value === null) {
-    if (initialTab) {
+    if (initialTab && (!isWorkbenchSurface(initialTab) || surfaceSet.has(initialTab))) {
       defaultTabRef.current.value = initialTab;
-    } else if (captureState.fileCount !== null) {
-      defaultTabRef.current.value =
-        captureState.fileCount > 0 ? WORKBENCH_TAB_CHANGES : WORKBENCH_TAB_FILES;
+    } else if (git.source === "live") {
+      defaultTabRef.current.value = sourceDrivenDefaultTab(
+        git.diff.length > 0,
+        changesEnabled,
+        filesEnabled,
+      );
+    } else if (
+      captureIsAuthoritative &&
+      captureState.fileCount !== null &&
+      captureState.available
+    ) {
+      defaultTabRef.current.value = sourceDrivenDefaultTab(
+        captureState.fileCount > 0,
+        changesEnabled,
+        filesEnabled,
+      );
+    } else if (
+      captureIsAuthoritative &&
+      captureUnavailable &&
+      initialWorkspaceTab(events) === WORKBENCH_TAB_CHANGES
+    ) {
+      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(
+        captureState.fileCount > 0,
+        changesEnabled,
+        filesEnabled,
+      );
+    } else if (captureUnavailable && git.error) {
+      // No capture and live Git failed: Files is the least surprising fallback
+      // and preserves the established no-capture degraded behavior.
+      defaultTabRef.current.value = sourceDrivenDefaultTab(false, changesEnabled, filesEnabled);
     }
   }
   // null only during the brief pre-first-resolve window (no host override yet).
@@ -396,48 +537,82 @@ export function useSandboxWorkspaceTabs(
   const tabs = useMemo(() => {
     const list: WorkspaceTab[] = [];
 
-    // Changes — always present (capture-backed, works cold/offline). The default
-    // primary surface. M5 replaces this body with the windowed diff renderer; the
-    // seam is the `<ChangesTabBody>` element (this is the minimal placeholder).
-    list.push({
-      id: WORKBENCH_TAB_CHANGES,
-      label: "Changes",
-      badge: dirtyCount > 0 ? <DirtyBadge count={dirtyCount} /> : undefined,
-      content: (
-        <ChangesTabBody
-          git={git}
-          captureAvailable={captureAvailable}
-          captureRevision={captureState.revision}
-          capabilitiesState={caps.state}
-          capabilitiesError={caps.error}
-          onRetry={caps.renegotiate}
-        />
-      ),
-    });
+    // Changes — capture-backed and usable cold/offline when the host enables it.
+    if (changesEnabled)
+      list.push({
+        id: WORKBENCH_TAB_CHANGES,
+        label: "Changes",
+        badge: dirtyCount > 0 ? <DirtyBadge count={dirtyCount} /> : undefined,
+        content: (
+          <ChangesTabBody
+            git={git}
+            captureAvailable={captureAvailable}
+            captureRevision={captureState.revision}
+            capturePending={capturePending}
+            liveWorkspaceExpected={liveWorkspaceExpected}
+            workspaceWaking={workspaceWaking}
+            capabilitiesState={caps.state}
+            capabilitiesError={caps.error}
+            onRetry={caps.renegotiate}
+            onWake={() => requestWarmIntent("warmFiles")}
+            {...(filesEnabled && onOpenFile
+              ? {
+                  onOpenFile: (path: string) => {
+                    requestWarmIntent("warmFiles");
+                    onOpenFile(path);
+                  },
+                }
+              : {})}
+          />
+        ),
+      });
 
-    // Files — always present (capture-backed cold tree; live warm). M5 virtualizes.
-    list.push({
-      id: WORKBENCH_TAB_FILES,
-      label: "Files",
-      content: (
-        <SandboxFiles
-          files={files}
-          git={git}
-          stagedGit={stagedGit}
-          fileSystemAvailable={fileSystemOn || captureAvailable}
-          editable={filesEditable}
-          // The first keystroke in the editor is the wake-on-edit INTENT: warm the
-          // box (even cold) so the write lands fast. Opening/reading files does not.
-          onEditIntent={() => requestWarmIntent("warmEdit")}
-          className="h-full"
-        />
-      ),
-    });
+    // Files — capture-backed cold tree; live warm when the host enables it.
+    if (filesEnabled)
+      list.push({
+        id: WORKBENCH_TAB_FILES,
+        label: "Files",
+        content: (
+          <SandboxFiles
+            key={sessionId}
+            files={files}
+            git={git}
+            stagedGit={stagedGit}
+            fileSystemAvailable={fileSystemOn || captureAvailable}
+            editable={
+              filesEditable && files.source === "live" && files.error === null && !files.loading
+            }
+            workspaceResting={
+              !liveWorkspaceExpected &&
+              liveness !== undefined &&
+              !capturePending &&
+              !captureAvailable &&
+              !workspaceWaking
+            }
+            workspaceWaking={!liveWorkspaceExpected && !captureAvailable && workspaceWaking}
+            liveWorkspaceReady={liveWorkspaceExpected}
+            onWakeWorkspace={() => requestWarmIntent("warmFiles")}
+            {...(requestedFilePath
+              ? {
+                  requestedPath: requestedFilePath,
+                  ...(requestedFileRequestId !== null && requestedFileRequestId !== undefined
+                    ? { requestedPathRequestId: requestedFileRequestId }
+                    : {}),
+                  requestedPathReady: liveness === "warm" || liveness === "draining",
+                }
+              : {})}
+            // 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")}
+            className="h-full"
+          />
+        ),
+      });
 
     // Terminal — capability-gated (appears after negotiation; never the default).
     if (terminalOn) {
       list.push({
-        id: "terminal",
+        id: WORKBENCH_TAB_TERMINAL,
         label: "Terminal",
         content: (
           <div className="h-full bg-og-bg p-1">
@@ -458,10 +633,10 @@ export function useSandboxWorkspaceTabs(
     // Desktop — capability-gated + consent-gated.
     if (desktopAdvertised) {
       list.push({
-        id: "desktop",
+        id: WORKBENCH_TAB_DESKTOP,
         label: "Desktop",
         badge: watchDesktop ? (
-          <span className="rounded-og-xs bg-og-status-running/20 px-1 text-2xs text-og-status-running">
+          <span className="rounded-og-xs bg-og-status-running/20 px-1 text-og-xs text-og-status-running">
             Live
           </span>
         ) : undefined,
@@ -482,18 +657,26 @@ export function useSandboxWorkspaceTabs(
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [
     fileSystemOn,
+    changesEnabled,
+    filesEnabled,
     terminalOn,
     desktopAdvertised,
     captureAvailable,
     dirtyCount,
     watchDesktop,
     warmTerminal,
+    requestedFilePath,
+    requestedFileRequestId,
+    onOpenFile,
+    liveness,
+    sessionId,
     files,
     git,
     stagedGit,
     terminal,
     xtermTheme,
     capabilities,
+    workspaceWaking,
     caps.state,
     caps.error,
     caps.viewerCapReached,
@@ -504,6 +687,7 @@ export function useSandboxWorkspaceTabs(
     tabs,
     defaultTab,
     machine: {
+      enabled: anySurfaceEnabled,
       chip,
       activeMachine,
       loading: machines.loading,
@@ -519,12 +703,17 @@ export type SandboxWorkspaceProps = ClientOverride & {
   events: SessionEvent[];
   /** The chat / primary pane shown beside the dock. */
   primary: ReactNode;
+  /**
+   * Built-in surfaces this host wants to expose. Omit for Changes, Files,
+   * Terminal, and Desktop. Disabled surfaces remain behaviorally dormant.
+   */
+  surfaces?: readonly SandboxWorkspaceSurface[] | undefined;
   /** Host tabs injected BEFORE the workbench tabs (e.g. a "Run" landing tab). */
   leadingTabs?: WorkspaceTab[] | undefined;
   /** 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 Changes-vs-Files from local capture stats. */
+   *  omitted the workbench decides from capture, then live Git when no capture exists. */
   initialTab?: string | undefined;
   /** Host-routed notifications (no toast dependency in the package). */
   onNotify?: ((notification: WorkspaceNotification) => void) | undefined;
@@ -552,6 +741,7 @@ export function SandboxWorkspace(props: SandboxWorkspaceProps): ReactNode {
     sessionId,
     events,
     primary,
+    surfaces,
     leadingTabs,
     trailingTabs,
     initialTab,
@@ -566,6 +756,25 @@ export function SandboxWorkspace(props: SandboxWorkspaceProps): ReactNode {
     className,
   } = props;
 
+  const [storedSelection, setStoredSelection] = useState<{
+    sessionId: string;
+    tab: string;
+  } | null>(null);
+  const [requestedFile, setRequestedFile] = useState<{
+    sessionId: string;
+    path: string;
+    requestId: number;
+  } | null>(null);
+  const nextFileRequestId = useRef(0);
+  const openFile = useCallback(
+    (path: string) => {
+      nextFileRequestId.current += 1;
+      setRequestedFile({ sessionId, path, requestId: nextFileRequestId.current });
+      setStoredSelection({ sessionId, tab: WORKBENCH_TAB_FILES });
+    },
+    [sessionId],
+  );
+
   const {
     tabs: workbenchTabs,
     machine,
@@ -575,22 +784,24 @@ export function SandboxWorkspace(props: SandboxWorkspaceProps): ReactNode {
     ...(props.workspaceId ? { workspaceId: props.workspaceId } : {}),
     sessionId,
     events,
+    ...(surfaces ? { surfaces } : {}),
     ...(initialTab ? { initialTab } : {}),
     ...(onNotify ? { onNotify } : {}),
+    requestedFilePath: requestedFile?.sessionId === sessionId ? requestedFile.path : null,
+    requestedFileRequestId: requestedFile?.sessionId === sessionId ? requestedFile.requestId : null,
+    onOpenFile: openFile,
   });
 
-  // A user's tab click wins forever; before that we follow the capture-driven
+  // A user's tab click wins forever; before that we follow the source-driven
   // default. While it is still resolving (null, pure-embedder pre-first-resolve)
   // we pass no controlled tab, so the dock renders its own first-tab fallback
   // (Changes) — whose body is a connecting/loading state until the capture lands,
   // so committing the real default at first-resolve produces no CONTENT switch.
   const tabs: WorkspaceTab[] = [...(leadingTabs ?? []), ...workbenchTabs, ...(trailingTabs ?? [])];
-  const [storedSelection, setStoredSelection] = useState<{
-    sessionId: string;
-    tab: string;
-  } | null>(null);
   const selectedTab = storedSelection?.sessionId === sessionId ? storedSelection.tab : null;
-  const activeTab = selectedTab ?? defaultTab ?? tabs[0]?.id;
+  const preferredTab = selectedTab ?? defaultTab;
+  const activeTab =
+    preferredTab && tabs.some((tab) => tab.id === preferredTab) ? preferredTab : tabs[0]?.id;
   const selectTab = useCallback(
     (tab: string) => setStoredSelection({ sessionId, tab }),
     [sessionId],
@@ -602,14 +813,18 @@ export function SandboxWorkspace(props: SandboxWorkspaceProps): ReactNode {
       tabs={tabs}
       {...(activeTab !== undefined ? { activeTab } : {})}
       onActiveTabChange={selectTab}
-      headerAccessory={
-        <MachineStateChip
-          chip={machine.chip}
-          activeMachine={machine.activeMachine}
-          error={machine.error}
-          onRetry={() => void machine.refresh()}
-        />
-      }
+      {...(machine.enabled
+        ? {
+            headerAccessory: (
+              <MachineStateChip
+                chip={machine.chip}
+                activeMachine={machine.activeMachine}
+                error={machine.error}
+                onRetry={() => void machine.refresh()}
+              />
+            ),
+          }
+        : {})}
       {...(mobileLeadingControl !== undefined ? { mobileLeadingControl } : {})}
       {...(collapsed !== undefined ? { collapsed } : {})}
       {...(onCollapsedChange ? { onCollapsedChange } : {})}
@@ -627,7 +842,9 @@ export type { WorkspaceDockProps };
 
 function DirtyBadge({ count }: { count: number }) {
   return (
-    <span className="rounded-og-xs bg-og-accent-soft px-1 text-2xs text-og-fg-muted">{count}</span>
+    <span className="rounded-og-xs bg-og-accent-soft px-1 text-og-xs text-og-fg-muted">
+      {count}
+    </span>
   );
 }
 
@@ -645,7 +862,7 @@ function MachineKindIcon({
 
 function chipDotClass(state: MachineChip["state"]): string {
   if (state === "live") return "bg-og-status-running";
-  if (state === "waking") return "bg-og-status-idle animate-pulse";
+  if (state === "waking") return "bg-og-status-idle animate-pulse motion-reduce:animate-none";
   return "bg-og-fg-subtle";
 }
 
@@ -654,7 +871,7 @@ function chipDotClass(state: MachineChip["state"]): string {
  * with a popover carrying the machine identity, connection state, the "shown as
  * of <time>" staleness note, the shared-session disclosure, and a retry when the
  * fleet failed to resolve (the old per-surface machine bar + Sandbox info tab,
- * folded into one header affordance — dossier §10.6 recommendation).
+ * folded into one header affordance — recommendation).
  */
 function MachineStateChip({
   chip,
@@ -667,13 +884,16 @@ function MachineStateChip({
   error: Error | null;
   onRetry: () => void;
 }) {
+  const triggerRef = useRef<HTMLButtonElement | null>(null);
+  const portalStyle = usePortalTokenStyle(triggerRef);
   return (
     <Popover.Root>
       <Popover.Trigger asChild>
         <button
+          ref={triggerRef}
           type="button"
           aria-label={`Machine: ${chip.label}`}
-          className="inline-flex min-h-7 items-center gap-1.5 rounded-og-sm px-2 py-1 text-og-xs font-medium text-og-fg-muted transition-colors hover:bg-og-surface-2 hover:text-og-fg max-[1023px]:min-h-11 pointer-coarse:min-h-11"
+          className="inline-flex min-h-7 items-center gap-1.5 rounded-og-sm px-2 py-1 text-og-xs font-medium text-og-fg-muted transition-colors hover:bg-og-surface-2 hover:text-og-fg focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-og-accent max-[1023px]:min-h-11 pointer-coarse:min-h-11"
         >
           <span
             className={cn("size-1.5 shrink-0 rounded-full", chipDotClass(chip.state))}
@@ -685,9 +905,12 @@ function MachineStateChip({
       <Popover.Portal forceMount>
         <Popover.Content
           forceMount
+          data-machine-state-popover
           align="end"
           sideOffset={6}
-          className="z-50 w-64 rounded-og-md border border-og-border bg-og-surface-1 p-3 text-og-sm text-og-fg shadow-lg outline-none data-[state=closed]:hidden"
+          collisionPadding={8}
+          className="og-root z-50 w-64 max-w-[calc(100vw-1rem)] rounded-og-md border border-og-border bg-og-surface-1 p-3 text-og-sm text-og-fg shadow-lg outline-none"
+          style={portalStyle}
         >
           <div className="flex min-w-0 items-center gap-1.5">
             <MachineKindIcon kind={activeMachine?.kind} />
@@ -719,7 +942,7 @@ function MachineStateChip({
           ) : null}
           {error ? (
             <div className="mt-2.5 space-y-1.5 border-t border-og-border pt-2.5">
-              <p className="text-og-xs leading-4 text-og-status-danger">
+              <p className="text-og-xs leading-4 text-og-danger">
                 Couldn't reach the sandbox for this session.
               </p>
               <DockActionButton onClick={onRetry}>
@@ -740,7 +963,7 @@ function DockActionButton({ onClick, children }: { onClick: () => void; children
     <button
       type="button"
       onClick={onClick}
-      className="inline-flex items-center gap-1.5 rounded-og-sm border border-og-border px-2 py-1 text-og-xs font-medium text-og-fg-muted transition-colors hover:border-og-border-strong hover:text-og-fg pointer-coarse:min-h-9"
+      className="inline-flex items-center gap-1.5 rounded-og-sm border border-og-border px-2 py-1 text-og-xs font-medium text-og-fg-muted transition-colors hover:border-og-border-strong hover:text-og-fg focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-og-accent max-[1023px]:min-h-11 pointer-coarse:min-h-11"
     >
       {children}
     </button>
@@ -757,35 +980,77 @@ function ChangesTabBody({
   git,
   captureAvailable,
   captureRevision,
+  capturePending,
+  liveWorkspaceExpected,
+  workspaceWaking,
   capabilitiesState,
   capabilitiesError,
   onRetry,
+  onWake,
+  onOpenFile,
 }: {
   git: UseSandboxGitResult;
   captureAvailable: boolean;
   captureRevision: number | null;
+  capturePending: boolean;
+  liveWorkspaceExpected: boolean;
+  workspaceWaking: boolean;
   capabilitiesState: string;
   capabilitiesError: Error | null;
   onRetry: () => void;
+  onWake: () => void;
+  onOpenFile?: ((path: string) => void) | undefined;
 }) {
   const diff = git.diff;
 
   if (diff.length > 0) {
     return (
-      <WorkbenchChanges
-        diff={diff}
-        source={git.source}
-        capturedAt={git.capturedAt}
-        captureRevision={captureRevision}
-      />
+      <div className="flex h-full min-h-0 flex-col">
+        {git.error ? (
+          <div
+            role="status"
+            aria-live="polite"
+            data-opengeni-changes-degraded
+            className="flex shrink-0 items-center gap-2 border-b border-og-status-running/30 bg-og-status-running/10 px-2 py-1.5 text-og-xs text-og-fg-muted"
+          >
+            <TriangleAlertIcon className="size-3.5 shrink-0 text-og-status-running" aria-hidden />
+            <span className="min-w-0 flex-1">
+              {git.source === "capture"
+                ? "Live changes are temporarily unavailable. Showing the latest captured revision."
+                : "Live refresh failed. Showing the last loaded changes."}
+            </span>
+            <button
+              type="button"
+              onClick={() => void git.refresh()}
+              disabled={git.loading}
+              className="inline-flex min-h-7 shrink-0 items-center gap-1 rounded-og-sm border border-og-border bg-og-surface-1 px-2 font-medium text-og-fg transition-colors hover:border-og-border-strong focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-og-accent disabled:cursor-not-allowed disabled:opacity-50 pointer-coarse:min-h-11"
+            >
+              <RefreshCwIcon
+                className={cn("size-3", git.loading && "animate-spin motion-reduce:animate-none")}
+                aria-hidden
+              />
+              Retry
+            </button>
+          </div>
+        ) : null}
+        <div className="min-h-0 flex-1">
+          <WorkbenchChanges
+            diff={diff}
+            source={git.source}
+            capturedAt={git.capturedAt}
+            captureRevision={captureRevision}
+            {...(onOpenFile ? { onOpenFile } : {})}
+          />
+        </div>
+      </div>
     );
   }
 
   if (capabilitiesError && !captureAvailable) {
     return (
-      <CenteredState>
+      <CenteredState icon={<TriangleAlertIcon className="size-5" aria-hidden />} tone="danger">
         <p className="text-og-sm font-medium text-og-fg">Sandbox unavailable</p>
-        <p className="text-og-sm leading-5 text-og-fg-muted">
+        <p data-contrast-audited className="text-og-sm leading-5 text-og-fg-muted">
           {capabilitiesError.message || "Couldn't reach the sandbox for this session."}
         </p>
         <DockActionButton onClick={onRetry}>
@@ -796,28 +1061,117 @@ function ChangesTabBody({
     );
   }
 
-  if ((capabilitiesState === "negotiating" || capabilitiesState === "cold") && !captureAvailable) {
+  if (
+    (capturePending || capabilitiesState === "negotiating") &&
+    !captureAvailable &&
+    !workspaceWaking
+  ) {
     return (
-      <CenteredState>
-        <p className="text-og-sm text-og-fg-muted">Connecting sandbox…</p>
+      <CenteredState
+        icon={
+          <LoaderCircleIcon
+            className="size-5 animate-spin motion-reduce:animate-none"
+            aria-hidden
+          />
+        }
+      >
+        <p className="text-og-sm font-medium text-og-fg">Connecting workspace</p>
+        <p className="text-og-sm leading-5 text-og-fg-subtle">
+          Looking for the latest files and changes…
+        </p>
+      </CenteredState>
+    );
+  }
+
+  if (!liveWorkspaceExpected && !captureAvailable) {
+    return (
+      <CenteredState
+        icon={
+          workspaceWaking ? (
+            <LoaderCircleIcon
+              className="size-5 animate-spin motion-reduce:animate-none"
+              aria-hidden
+            />
+          ) : (
+            <CpuIcon className="size-5" aria-hidden />
+          )
+        }
+      >
+        <p className="text-og-sm font-medium text-og-fg">
+          {workspaceWaking ? "Waking workspace" : "Workspace is resting"}
+        </p>
+        <p className="text-og-sm leading-5 text-og-fg-subtle">
+          {workspaceWaking
+            ? "Connecting to the live working tree…"
+            : "No captured revision is available yet. Wake the sandbox to inspect current changes."}
+        </p>
+        {!workspaceWaking ? (
+          <DockActionButton onClick={onWake}>
+            <CpuIcon className="size-3" />
+            Open live workspace
+          </DockActionButton>
+        ) : null}
+      </CenteredState>
+    );
+  }
+
+  if (git.loading && git.source === null) {
+    return (
+      <CenteredState
+        icon={
+          <LoaderCircleIcon
+            className="size-5 animate-spin motion-reduce:animate-none"
+            aria-hidden
+          />
+        }
+      >
+        <p className="text-og-sm font-medium text-og-fg">Loading workspace</p>
+        <p className="text-og-sm leading-5 text-og-fg-subtle">Reading the current working tree…</p>
       </CenteredState>
     );
   }
 
   return (
-    <CenteredState>
-      <p className="text-og-sm font-medium text-og-fg">No changes yet</p>
+    <CenteredState icon={<CircleCheckIcon className="size-5" aria-hidden />} tone="success">
+      <p className="text-og-sm font-medium text-og-fg">Working tree is clean</p>
       <p className="text-og-sm leading-5 text-og-fg-subtle">
-        File edits from this session's turns show up here.
+        File edits from future turns will appear here.
       </p>
     </CenteredState>
   );
 }
 
-function CenteredState({ children }: { children: ReactNode }) {
+function CenteredState({
+  children,
+  icon,
+  tone = "neutral",
+}: {
+  children: ReactNode;
+  icon?: ReactNode | undefined;
+  tone?: "neutral" | "success" | "danger";
+}) {
   return (
-    <div className="grid h-full place-items-center p-6 text-center">
-      <div className="flex max-w-sm flex-col items-center gap-2.5">{children}</div>
+    <div
+      role={tone === "danger" ? "alert" : "status"}
+      aria-atomic="true"
+      aria-live={tone === "danger" ? "assertive" : "polite"}
+      className="grid h-full place-items-center p-6 text-center"
+    >
+      <div className="flex max-w-sm flex-col items-center gap-2.5">
+        {icon ? (
+          <span
+            className={cn(
+              "grid size-10 place-items-center rounded-og-lg border bg-og-surface-1 shadow-sm",
+              tone === "success" && "border-og-status-idle/30 text-og-status-idle",
+              tone === "danger" && "border-og-status-failed/30 text-og-status-failed",
+              tone === "neutral" && "border-og-border text-og-fg-muted",
+            )}
+          >
+            {icon}
+          </span>
+        ) : null}
+        {children}
+      </div>
     </div>
   );
 }