@opengeni/react 0.15.0 → 0.23.0

package/src/components/sandbox-workspace.tsx

@@ -12,7 +12,7 @@
 // (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";
@@ -28,6 +28,7 @@ import {
 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";
@@ -51,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) {
@@ -122,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. */
@@ -136,6 +170,12 @@ export type UseSandboxWorkspaceTabsOptions = ClientOverride & {
   sessionId: string;
   /** Live event log (usually `useSessionEvents().events`). */
   events: SessionEvent[];
+  /**
+   * 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;
@@ -157,7 +197,8 @@ export type UseSandboxWorkspaceTabsResult = {
   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).
-   *  null while that source resolves; the choice latches once. */
+   *  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;
@@ -191,6 +232,15 @@ export function useSandboxWorkspaceTabs(
   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 box-warming INTENTS, each off by default and each
   // flipped true by a genuine user action (never on mount, never on a passive
@@ -219,6 +269,7 @@ export function useSandboxWorkspaceTabs(
     workspaceId,
     sessionId,
     pollIntervalMs: 8000,
+    enabled: anySurfaceEnabled,
   });
   const activeMachine: MachineView | null =
     machines.machines.find((m) => m.sandboxId === machines.activeSandboxId) ??
@@ -227,11 +278,12 @@ export function useSandboxWorkspaceTabs(
 
   const caps = useSessionCapabilities(sessionId, {
     events,
-    attachDesktop: watchDesktop,
-    attachTerminal: warmTerminal,
+    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: warmFiles,
+    attachFiles: workspaceDataEnabled && warmFiles,
   });
   const capabilities = caps.capabilities;
   const liveness = capabilities?.liveness;
@@ -239,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).
@@ -253,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.
@@ -280,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;
@@ -302,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
@@ -315,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,
   });
@@ -331,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);
@@ -340,7 +421,7 @@ export function useSandboxWorkspaceTabs(
       attributeFilter: ["data-og-theme", "class"],
     });
     return () => observer.disconnect();
-  }, []);
+  }, [terminalEnabled]);
 
   async function acknowledgeAndWatch() {
     try {
@@ -375,9 +456,13 @@ export function useSandboxWorkspaceTabs(
     capabilitiesState: caps.state,
     activeMachineState: activeMachine?.state ?? null,
     activeIsSelfhosted: activeMachine?.kind === "selfhosted",
-    wantsWarm: warmTerminal || watchDesktop || warmFiles,
+    wantsWarm:
+      (terminalEnabled && warmTerminal) ||
+      (desktopEnabled && watchDesktop) ||
+      (workspaceDataEnabled && warmFiles),
     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
@@ -387,49 +472,63 @@ export function useSandboxWorkspaceTabs(
   // 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 defaultTabRef = useRef<{ sessionId: string; value: string | null }>({
-    sessionId,
+  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 liveWorkspaceExpected = liveness === "warm" || liveness === "draining";
   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 (git.source === "live") {
-      defaultTabRef.current.value =
-        git.diff.length > 0 ? WORKBENCH_TAB_CHANGES : WORKBENCH_TAB_FILES;
+      defaultTabRef.current.value = sourceDrivenDefaultTab(
+        git.diff.length > 0,
+        changesEnabled,
+        filesEnabled,
+      );
     } else if (
       captureIsAuthoritative &&
       captureState.fileCount !== null &&
       captureState.available
     ) {
-      defaultTabRef.current.value =
-        captureState.fileCount > 0 ? WORKBENCH_TAB_CHANGES : WORKBENCH_TAB_FILES;
+      defaultTabRef.current.value = sourceDrivenDefaultTab(
+        captureState.fileCount > 0,
+        changesEnabled,
+        filesEnabled,
+      );
     } else if (
       captureIsAuthoritative &&
       captureUnavailable &&
       initialWorkspaceTab(events) === WORKBENCH_TAB_CHANGES
     ) {
-      defaultTabRef.current.value = WORKBENCH_TAB_CHANGES;
-    } 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 =
-        captureState.fileCount > 0 ? WORKBENCH_TAB_CHANGES : WORKBENCH_TAB_FILES;
+      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 = WORKBENCH_TAB_CHANGES;
+      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 = WORKBENCH_TAB_FILES;
+      defaultTabRef.current.value = sourceDrivenDefaultTab(false, changesEnabled, filesEnabled);
     }
   }
   // null only during the brief pre-first-resolve window (no host override yet).
@@ -438,66 +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}
-          {...(onOpenFile
-            ? {
-                onOpenFile: (path: string) => {
-                  requestWarmIntent("warmFiles");
-                  onOpenFile(path);
-                },
-              }
-            : {})}
-        />
-      ),
-    });
+    // 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
-          key={sessionId}
-          files={files}
-          git={git}
-          stagedGit={stagedGit}
-          fileSystemAvailable={fileSystemOn || captureAvailable}
-          editable={filesEditable}
-          {...(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"
-        />
-      ),
-    });
+    // 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">
@@ -518,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,
@@ -542,6 +657,8 @@ export function useSandboxWorkspaceTabs(
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [
     fileSystemOn,
+    changesEnabled,
+    filesEnabled,
     terminalOn,
     desktopAdvertised,
     captureAvailable,
@@ -559,6 +676,7 @@ export function useSandboxWorkspaceTabs(
     terminal,
     xtermTheme,
     capabilities,
+    workspaceWaking,
     caps.state,
     caps.error,
     caps.viewerCapReached,
@@ -569,6 +687,7 @@ export function useSandboxWorkspaceTabs(
     tabs,
     defaultTab,
     machine: {
+      enabled: anySurfaceEnabled,
       chip,
       activeMachine,
       loading: machines.loading,
@@ -584,6 +703,11 @@ 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). */
@@ -617,6 +741,7 @@ export function SandboxWorkspace(props: SandboxWorkspaceProps): ReactNode {
     sessionId,
     events,
     primary,
+    surfaces,
     leadingTabs,
     trailingTabs,
     initialTab,
@@ -659,6 +784,7 @@ 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,
@@ -673,7 +799,9 @@ export function SandboxWorkspace(props: SandboxWorkspaceProps): ReactNode {
   // so committing the real default at first-resolve produces no CONTENT switch.
   const tabs: WorkspaceTab[] = [...(leadingTabs ?? []), ...workbenchTabs, ...(trailingTabs ?? [])];
   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],
@@ -685,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 } : {})}
@@ -710,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>
   );
 }
 
@@ -737,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,
@@ -750,10 +884,13 @@ 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 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-og-accent max-[1023px]:min-h-11 pointer-coarse:min-h-11"
@@ -768,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} />
@@ -802,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}>
@@ -840,30 +980,69 @@ 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}
-        {...(onOpenFile ? { onOpenFile } : {})}
-      />
+      <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>
     );
   }
 
@@ -871,7 +1050,7 @@ function ChangesTabBody({
     return (
       <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}>
@@ -882,7 +1061,11 @@ function ChangesTabBody({
     );
   }
 
-  if ((capabilitiesState === "negotiating" || capabilitiesState === "cold") && !captureAvailable) {
+  if (
+    (capturePending || capabilitiesState === "negotiating") &&
+    !captureAvailable &&
+    !workspaceWaking
+  ) {
     return (
       <CenteredState
         icon={
@@ -900,6 +1083,38 @@ function ChangesTabBody({
     );
   }
 
+  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
@@ -936,7 +1151,12 @@ function CenteredState({
   tone?: "neutral" | "success" | "danger";
 }) {
   return (
-    <div className="grid h-full place-items-center p-6 text-center">
+    <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