@opengeni/react 0.57.0 → 1.0.2-canary.37191796234001

package/src/hooks/use-desktop-stream.ts

@@ -6,7 +6,15 @@ import {
   type DesktopRfbLike,
   type DesktopStreamCapability,
 } from "@opengeni/sdk";
-import { type RefObject, useCallback, useEffect, useRef, useState } from "react";
+import {
+  type RefObject,
+  useCallback,
+  useEffect,
+  useRef,
+  useState,
+  useSyncExternalStore,
+} from "react";
+import { desktopViewerPeers } from "../lib/workbench-peers";
 import { type DesktopWebSocketFactory, useRelayFrameStream } from "./use-relay-frame-stream";
 
 export type UseDesktopStreamOptions = {
@@ -17,7 +25,7 @@ export type UseDesktopStreamOptions = {
   /** Read-only by default (v1 ruling H). interactive only when cap.mode allows. */
   interactive?: boolean | undefined;
   scaleViewport?: boolean | undefined;
-  /** Custom RFB factory (tests / a WebRTC swap). Defaults to a lazy @novnc/novnc. */
+  /** Custom RFB factory. Otherwise call enableDesktopViewer() on the desktop subpath. */
   rfbFactory?: DesktopRfbFactory | undefined;
   /** Additional WebSocket protocols for an authenticated placement proxy. */
   webSocketProtocols?: string[] | undefined;
@@ -35,29 +43,6 @@ export type UseDesktopStreamResult = {
   sendKey?: ((keysym: number, code: string, down?: boolean) => boolean) | undefined;
 };
 
-/** Lazy-load @novnc/novnc's RFB as the default factory. Imported inside the
- *  connect effect so SSR / non-desktop bundles never pull the DOM-only lib.
- *  @novnc/novnc ships no types and a single `export default class RFB`. The
- *  specifier is STATIC (`import("@novnc/novnc")`) so Vite can pre-bundle and
- *  resolve it — a runtime-string indirection with `@vite-ignore` (the previous
- *  approach) hands the browser a bare specifier and throws
- *  "Failed to resolve module specifier '@novnc/novnc'". The dynamic form keeps
- *  it out of the SSR / non-desktop critical path while staying resolvable. */
-async function defaultRfbFactory(): Promise<DesktopRfbFactory> {
-  const mod = (await import("@novnc/novnc")) as unknown as {
-    default: new (
-      t: HTMLElement,
-      u: string,
-      o: {
-        credentials?: { password?: string | undefined } | undefined;
-        wsProtocols?: string[] | undefined;
-      },
-    ) => DesktopRfbLike;
-  };
-  const RFB = mod.default;
-  return (target, url, opts) => new RFB(target, url, opts);
-}
-
 /**
  * Drive the noVNC RFB lifecycle from a `DesktopStreamCapability`, using the
  * SDK's `desktop.ts` reducer + `desktopSocketUrl`. SSR-safe: the RFB import and
@@ -87,6 +72,12 @@ export function useDesktopStream(options: UseDesktopStreamOptions): UseDesktopSt
     webSocketProtocols,
     webSocketFactory,
   } = options;
+  const peerRevision = useSyncExternalStore(
+    desktopViewerPeers.subscribe,
+    desktopViewerPeers.revision,
+    desktopViewerPeers.revision,
+  );
+  const factoryRevision = rfbFactory ? 0 : peerRevision;
 
   // The self-hosted PNG-frame path. Always invoked (rules of hooks); dormant
   // unless `transport === "relay-frames"`, in which case it owns the surface.
@@ -188,7 +179,7 @@ export function useDesktopStream(options: UseDesktopStreamOptions): UseDesktopSt
 
     void (async () => {
       try {
-        const factory = rfbFactoryRef.current ?? (await defaultRfbFactory());
+        const factory = rfbFactoryRef.current ?? (await desktopViewerPeers.load());
         if (disposed) return;
         const socketUrl = desktopSocketUrl({ url });
         setBoth(nextDesktopState(stateRef.current, { type: "negotiated" }));
@@ -232,11 +223,11 @@ export function useDesktopStream(options: UseDesktopStreamOptions): UseDesktopSt
     };
     // ONLY a real transport change reconnects: a fresh url (rotation), a new
     // credential (RFB password OR bearer subprotocol), the transport flipping,
-    // or an explicit manual reconnect
+    // a newly registered default peer loader, or an explicit manual reconnect
     // (`nonce`). `interactive`/`scaleViewport`/`mode`/`rfbFactory` are read via
     // refs and applied live below — they must never re-open the socket.
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [url, token, transport, webSocketProtocolsKey, nonce]);
+  }, [url, token, transport, webSocketProtocolsKey, nonce, factoryRevision]);
 
   // Apply take-control / return-control to the OPEN connection in place. noVNC
   // honours `viewOnly` live, so flipping it neither blinks the surface nor drops

package/src/hooks/use-file-attachments.ts

@@ -4,6 +4,7 @@ import {
   useEmbeddedFileAttachments,
   type EmbeddedFileAttachmentClientOverride,
 } from "../session-context";
+import { useErrorMessage } from "../lib/error-message";
 
 export type UseFileAttachmentsOptions = EmbeddedFileAttachmentClientOverride & {
   /**
@@ -13,6 +14,8 @@ export type UseFileAttachmentsOptions = EmbeddedFileAttachmentClientOverride & {
    * UseFileAttachmentsResult.addFiles} (the explicit picker / drop path)
    * bypasses it.
    */
+  /** Retain original uploads in the chat owner’s personal scope when private. */
+  scope?: "workspace" | "personal";
   pasteFilter?: ((file: File) => boolean) | undefined;
 };
 
@@ -26,7 +29,11 @@ export type FileAttachment = {
   file?: FileAsset | undefined;
   /** Object-URL for an inline preview; minted for `image/*` files only. */
   previewUrl?: string | undefined;
+  /** Stable SDK failure code for UI behavior that must not parse error copy. */
+  errorCode?: "secure_context_required" | undefined;
   error?: string | undefined;
+  /** Original diagnostic failure; presentation copy is kept separately in `error`. */
+  errorCause?: unknown;
 };
 
 export type UseFileAttachmentsResult = {
@@ -50,12 +57,25 @@ export type UseFileAttachmentsResult = {
   addFromPaste: (event: { clipboardData: DataTransfer | null }) => void;
   /** Restore already-ready server assets without recreating browser-local bytes. */
   restoreReadyFiles: (files: Iterable<FileAsset>) => void;
+  /**
+   * Resolve a ready image's short-lived server preview URL on demand. Optional
+   * for upload-only embedded clients; local object-URL previews remain usable
+   * without it.
+   */
+  loadPreview?: ((id: string, signal?: AbortSignal) => Promise<string | undefined>) | undefined;
   /**
    * Re-run the upload for a `failed` attachment, in place (same id, same
    * source file). No-op for an id that isn't a known failed upload.
    */
   retry: (id: string) => void;
-  /** Remove one attachment; revokes its object-URL. */
+  /**
+   * Keep an attachment's object-URL alive for a consumer that outlives its
+   * queue entry (for example, an open route-level lightbox). The returned
+   * release is idempotent; pending revocation finishes after the last holder
+   * releases. Returns `undefined` when the attachment has no local preview.
+   */
+  retainPreview: (id: string) => (() => void) | undefined;
+  /** Remove one attachment; revokes its object-URL after retained users finish. */
   remove: (id: string) => void;
   /**
    * Remove only finalized files whose durable ids were accepted by a send.
@@ -63,12 +83,33 @@ export type UseFileAttachmentsResult = {
    * next message.
    */
   removeReadyFiles: (fileIds: Iterable<string>) => void;
-  /** Remove all attachments and revoke every object-URL. */
+  /** Remove all attachments and revoke every unretained object-URL. */
   clear: () => void;
 };
 
 const isImage = (file: File): boolean => file.type.startsWith("image/");
 
+let fallbackAttachmentId = 0;
+
+function createAttachmentId(): string {
+  const cryptoSource = globalThis.crypto;
+  if (typeof cryptoSource?.randomUUID === "function") return cryptoSource.randomUUID();
+  fallbackAttachmentId += 1;
+  // This id is only a browser-local React key and retry lookup, never durable
+  // authority. Keep attachment tracking usable when HTTP withholds randomUUID
+  // or Web Crypto is unavailable so the SDK's typed failure reaches the card.
+  return `attachment:${Date.now().toString(36)}:${fallbackAttachmentId.toString(36)}`;
+}
+
+function secureContextRequiredErrorCode(error: unknown): "secure_context_required" | undefined {
+  return typeof error === "object" &&
+    error !== null &&
+    "code" in error &&
+    error.code === "secure_context_required"
+    ? error.code
+    : undefined;
+}
+
 /**
  * Upload-and-track state for files attached to the next message. Owns the
  * full client-side upload layer: a per-file `uploading | ready | failed`
@@ -82,8 +123,11 @@ export function useFileAttachments(
   options: UseFileAttachmentsOptions = {},
 ): UseFileAttachmentsResult {
   const { client, workspaceId } = useEmbeddedFileAttachments(options);
+  const formatError = useErrorMessage();
   const pasteFilter = options.pasteFilter ?? isImage;
   const [attachments, setAttachments] = useState<FileAttachment[]>([]);
+  const attachmentsRef = useRef(attachments);
+  attachmentsRef.current = attachments;
   // Keep the source File per attachment id so a failed upload can be retried
   // in place. Cleared on remove/clear so it never outlives its attachment.
   const sources = useRef<Map<string, File>>(new Map());
@@ -91,17 +135,41 @@ export function useFileAttachments(
   // state update when its component unmounts in the same batch that minted the
   // preview. The registry remains available to cleanup even before a render.
   const previewUrls = useRef<Map<string, string>>(new Map());
+  const previewRetainers = useRef<Map<string, number>>(new Map());
+  const pendingPreviewRevocations = useRef<Set<string>>(new Set());
   const revokePreview = useCallback((id: string) => {
     const previewUrl = previewUrls.current.get(id);
     if (!previewUrl) return;
+    if ((previewRetainers.current.get(id) ?? 0) > 0) {
+      pendingPreviewRevocations.current.add(id);
+      return;
+    }
     previewUrls.current.delete(id);
+    pendingPreviewRevocations.current.delete(id);
     URL.revokeObjectURL(previewUrl);
   }, []);
   const revokeAllPreviews = useCallback(() => {
-    const urls = [...previewUrls.current.values()];
-    previewUrls.current.clear();
-    for (const previewUrl of urls) URL.revokeObjectURL(previewUrl);
-  }, []);
+    for (const id of previewUrls.current.keys()) revokePreview(id);
+  }, [revokePreview]);
+  const retainPreview = useCallback(
+    (id: string): (() => void) | undefined => {
+      if (!previewUrls.current.has(id)) return undefined;
+      previewRetainers.current.set(id, (previewRetainers.current.get(id) ?? 0) + 1);
+      let released = false;
+      return () => {
+        if (released) return;
+        released = true;
+        const remaining = (previewRetainers.current.get(id) ?? 1) - 1;
+        if (remaining > 0) {
+          previewRetainers.current.set(id, remaining);
+          return;
+        }
+        previewRetainers.current.delete(id);
+        if (pendingPreviewRevocations.current.has(id)) revokePreview(id);
+      };
+    },
+    [revokePreview],
+  );
   // Ready-file reconciliation uses functional state updaters, which React may
   // evaluate during a concurrent render that later suspends or is abandoned.
   // Diff only committed attachment sets here so URL revocation cannot run from
@@ -150,6 +218,7 @@ export function useFileAttachments(
           filename: file.name || "file",
           contentType: file.type || "application/octet-stream",
           data: file,
+          ...(options.scope ? { scope: options.scope } : {}),
         })
         .then((asset) => {
           if (scopeGeneration.current !== generation) return;
@@ -167,7 +236,9 @@ export function useFileAttachments(
                     name: asset.filename,
                     contentType: asset.contentType,
                     sizeBytes: asset.sizeBytes,
+                    errorCode: undefined,
                     error: undefined,
+                    errorCause: undefined,
                   }
                 : attachment,
             ),
@@ -181,20 +252,22 @@ export function useFileAttachments(
                 ? {
                     ...attachment,
                     status: "failed",
-                    error: error instanceof Error ? error.message : String(error),
+                    errorCode: secureContextRequiredErrorCode(error),
+                    error: formatError(error),
+                    errorCause: error,
                   }
                 : attachment,
             ),
           );
         });
     },
-    [client, workspaceId],
+    [client, workspaceId, options.scope, formatError],
   );
 
   const addFiles = useCallback(
     (files: Iterable<File>) => {
       for (const file of files) {
-        const id = crypto.randomUUID();
+        const id = createAttachmentId();
         sources.current.set(id, file);
         const previewUrl = isImage(file) ? URL.createObjectURL(file) : undefined;
         if (previewUrl) previewUrls.current.set(id, previewUrl);
@@ -224,7 +297,13 @@ export function useFileAttachments(
       setAttachments((current) =>
         current.map((attachment) =>
           attachment.id === id
-            ? { ...attachment, status: "uploading", error: undefined }
+            ? {
+                ...attachment,
+                status: "uploading",
+                errorCode: undefined,
+                error: undefined,
+                errorCause: undefined,
+              }
             : attachment,
         ),
       );
@@ -274,7 +353,9 @@ export function useFileAttachments(
                 sizeBytes: file.sizeBytes,
                 status: "ready",
                 file,
+                errorCode: undefined,
                 error: undefined,
+                errorCause: undefined,
               }
             : {
                 id: `restored:${file.id}`,
@@ -296,6 +377,31 @@ export function useFileAttachments(
     [workspaceId],
   );
 
+  const loadPreview = useCallback(
+    async (id: string, signal?: AbortSignal): Promise<string | undefined> => {
+      const generation = scopeGeneration.current;
+      const attachment = attachmentsRef.current.find((candidate) => candidate.id === id);
+      const createDownloadUrl = client.createFileDownloadUrl;
+      if (
+        !attachment ||
+        attachment.status !== "ready" ||
+        !attachment.file ||
+        !attachment.contentType.startsWith("image/") ||
+        typeof createDownloadUrl !== "function" ||
+        signal?.aborted
+      ) {
+        return undefined;
+      }
+      const fileId = attachment.file.id;
+      const signed = await createDownloadUrl.call(client, workspaceId, fileId, { signal });
+      if (scopeGeneration.current !== generation || signal?.aborted) return undefined;
+      const current = attachmentsRef.current.find((candidate) => candidate.id === id);
+      if (current?.status !== "ready" || current.file?.id !== fileId) return undefined;
+      return signed.url;
+    },
+    [client, workspaceId],
+  );
+
   const remove = useCallback(
     (id: string) => {
       sources.current.delete(id);
@@ -337,7 +443,9 @@ export function useFileAttachments(
     addFiles,
     addFromPaste,
     restoreReadyFiles,
+    ...(typeof client.createFileDownloadUrl === "function" ? { loadPreview } : {}),
     retry,
+    retainPreview,
     remove,
     removeReadyFiles,
     clear,

package/src/hooks/use-goal.ts

@@ -1,6 +1,7 @@
 import { OpenGeniApiError, type SessionEvent, type SessionGoal } from "@opengeni/sdk";
 import { useCallback, useEffect, useRef, useState } from "react";
 import { useEmbeddedGoal, type EmbeddedGoalClientOverride } from "../session-context";
+import { normalizeError } from "../lib/error-message";
 import {
   useDebouncedCallback,
   useMutationRunner,
@@ -83,14 +84,26 @@ export function useGoal(
   const { run, mutating, mutationError, clearMutationError } = useMutationRunner();
   const generation = useRef(0);
   const targetKeyRef = useRef<string | null>(null);
+  const loadAbort = useRef<AbortController | null>(null);
+
+  const retireLoads = useCallback(() => {
+    generation.current += 1;
+    loadAbort.current?.abort();
+    loadAbort.current = null;
+  }, []);
 
   const load = useCallback(async (): Promise<void> => {
     if (!sessionId) {
       return;
     }
     const ticket = ++generation.current;
+    loadAbort.current?.abort();
+    const controller = new AbortController();
+    loadAbort.current = controller;
     try {
-      const fetched = await client.getGoal(workspaceId, sessionId);
+      const fetched = await client.getGoal(workspaceId, sessionId, {
+        signal: controller.signal,
+      });
       if (ticket === generation.current) {
         setGoal(fetched);
         setError(null);
@@ -105,9 +118,11 @@ export function useGoal(
         setGoal(null);
         setError(null);
       } else {
-        setError(cause instanceof Error ? cause : new Error(String(cause)));
+        setError(normalizeError(cause));
       }
       setLoading(false);
+    } finally {
+      if (loadAbort.current === controller) loadAbort.current = null;
     }
   }, [client, workspaceId, sessionId]);
 
@@ -119,13 +134,16 @@ export function useGoal(
       setError(null);
     }
     if (!enabled || !pageLive) {
+      retireLoads();
       setLoading(false);
       return;
     }
     if (sharedFeed) {
-      setLoading(false);
+      // A shared log supplies invalidations, not the authoritative goal snapshot.
+      setLoading(true);
+      void load();
       return () => {
-        generation.current += 1;
+        retireLoads();
       };
     }
     setLoading(true);
@@ -133,7 +151,7 @@ export function useGoal(
     if (pollIntervalMs === undefined || pollIntervalMs <= 0) {
       void load();
       return () => {
-        generation.current += 1;
+        retireLoads();
       };
     }
     let cancelled = false;
@@ -149,9 +167,18 @@ export function useGoal(
     return () => {
       cancelled = true;
       if (timer !== null) clearTimeout(timer);
-      generation.current += 1;
+      retireLoads();
     };
-  }, [load, enabled, pageLive, workspaceId, sessionId, options.pollIntervalMs, sharedFeed]);
+  }, [
+    load,
+    enabled,
+    pageLive,
+    workspaceId,
+    sessionId,
+    options.pollIntervalMs,
+    retireLoads,
+    sharedFeed,
+  ]);
 
   const scheduleRefresh = useDebouncedCallback(() => void load());
   useSessionEventTrigger(client, workspaceId, sessionId, isGoalRefreshEvent, scheduleRefresh, {
@@ -203,11 +230,11 @@ export function useGoal(
       return true as const;
     });
     if (ok) {
-      generation.current += 1;
+      retireLoads();
       setGoal(null);
       setError(null);
     }
-  }, [client, workspaceId, sessionId, run]);
+  }, [client, workspaceId, sessionId, run, retireLoads]);
 
   return {
     goal,

package/src/hooks/use-human-input.ts

@@ -8,6 +8,7 @@ import {
   useEmbeddedHumanInputSession,
   type EmbeddedHumanInputClientOverride,
 } from "../session-context";
+import { isActionableHumanInputRequest } from "../human-input";
 import {
   useDebouncedCallback,
   useMutationRunner,
@@ -70,8 +71,11 @@ export function useHumanInputRequests(
     enabled,
     pollIntervalMs: options.pollIntervalMs,
   });
+  const loadedRequests = state.data;
+  const refreshRequests = state.refresh;
   const mutation = useMutationRunner(`${workspaceId}\u0000${sessionId ?? ""}`);
   const [respondingRequestId, setRespondingRequestId] = useState<string | null>(null);
+  const [deadlineVersion, setDeadlineVersion] = useState(0);
   const respondingRequestRef = useRef<string | null>(null);
 
   useEffect(() => {
@@ -89,6 +93,25 @@ export function useHumanInputRequests(
     ...(options.events !== undefined ? { events: options.events } : {}),
   });
 
+  useEffect(() => {
+    const now = Date.now();
+    const nextDeadline = (loadedRequests ?? []).reduce<number | null>((next, request) => {
+      if (request.status !== "pending" || !request.expiresAt) return next;
+      const deadline = Date.parse(request.expiresAt);
+      if (!Number.isFinite(deadline) || deadline <= now) return next;
+      return next === null ? deadline : Math.min(next, deadline);
+    }, null);
+    if (nextDeadline === null) return;
+    const timer = globalThis.setTimeout(
+      () => {
+        setDeadlineVersion((current) => current + 1);
+        void refreshRequests();
+      },
+      Math.min(2_147_483_647, Math.max(0, nextDeadline - now + 1)),
+    );
+    return () => globalThis.clearTimeout(timer);
+  }, [loadedRequests, refreshRequests]);
+
   const respond = useCallback(
     async (
       requestId: string,
@@ -115,11 +138,15 @@ export function useHumanInputRequests(
     [client, mutation, sessionId, state, workspaceId],
   );
 
+  const now = Date.now();
+  void deadlineVersion;
   return {
-    requests: [...(state.data ?? [])].sort(
-      (left, right) =>
-        left.createdAt.localeCompare(right.createdAt) || left.id.localeCompare(right.id),
-    ),
+    requests: [...(state.data ?? [])]
+      .filter((request) => isActionableHumanInputRequest(request, now))
+      .sort(
+        (left, right) =>
+          left.createdAt.localeCompare(right.createdAt) || left.id.localeCompare(right.id),
+      ),
     loading: state.loading,
     error: state.error,
     refresh: state.refresh,

package/src/hooks/use-last-started-turn-policy.ts

@@ -33,7 +33,7 @@ function policyFromTurn(turn: SessionTurn | null | undefined): LastStartedTurnPo
   return {
     model: turn.model,
     reasoningEffort: turn.reasoningEffort,
-    latencyMode: turn.latencyMode ?? "standard",
+    latencyMode: turn.latencyMode,
     turnId: turn.id,
   };
 }
@@ -47,25 +47,26 @@ export function useLastStartedTurnPolicy(
   sessionId: string | null | undefined,
   options: UseLastStartedTurnPolicyOptions = {},
 ): UseLastStartedTurnPolicyResult {
-  const { client, workspaceId, workspaceControlEvent, registerSessionReconciler } =
-    useOpenGeni(options);
+  const { client, workspaceId, registerSessionReconciler } = useOpenGeni(options);
   const enabled = (options.enabled ?? true) && Boolean(sessionId);
 
-  const load = useCallback(async (): Promise<LastStartedTurnPolicy | null> => {
-    if (!sessionId) return null;
-    const turns = await client.listTurns(workspaceId, sessionId, { latestStarted: true });
-    return policyFromTurn(turns[0]);
-  }, [client, workspaceId, sessionId]);
+  const load = useCallback(
+    async (signal?: AbortSignal): Promise<LastStartedTurnPolicy | null> => {
+      if (!sessionId) return null;
+      const turns = await client.listTurns(workspaceId, sessionId, {
+        latestStarted: true,
+        signal,
+      });
+      return policyFromTurn(turns[0]);
+    },
+    [client, workspaceId, sessionId],
+  );
 
   const { data, loading, error, refresh } = usePolledValue(load, {
     pollIntervalMs: options.pollIntervalMs,
     enabled,
   });
 
-  useEffect(() => {
-    if (enabled && workspaceControlEvent) void refresh();
-  }, [enabled, refresh, workspaceControlEvent]);
-
   useEffect(() => {
     if (!sessionId || !enabled) return;
     return registerSessionReconciler(sessionId, "last-started-turn-policy", refresh);
@@ -73,7 +74,8 @@ export function useLastStartedTurnPolicy(
 
   // Shared-feed only: the session header lives outside the route event log and
   // must not open a second SSE. Without `events`, rely on the initial fetch +
-  // optional poll / workspace-control / reconciler.
+  // optional poll / reconciler. Pause/resume controls do not change the last
+  // admitted turn; its own turn.started event supplies that invalidation.
   useSessionEventTrigger(
     client,
     workspaceId,

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

@@ -4,13 +4,13 @@ import type { SessionCapabilitiesState } from "./use-session-capabilities";
 import { sandboxAcceptsLiveIo } from "../lib/sandbox-liveness";
 import { connectionStatusForState } from "../types/machines";
 
-/** The one truthful machine indicator. Honest staleness beats
- *  fake liveness: a cold/asleep box reads "offline — as of <time>", never "live". */
+/** The one truthful machine indicator. Managed cold compute is sleeping; a
+ *  Connected Machine that is genuinely unreachable remains offline. */
 export type MachineChipState = "live" | "waking" | "offline";
 
 export type MachineChip = {
   state: MachineChipState;
-  /** A ready-to-render label ("Live" / "Waking…" / "Offline — as of 3m ago"). */
+  /** A ready-to-render label ("Live" / "Waking…" / "Sleeping · saved 3m ago"). */
   label: string;
   /** The capture time backing an offline/stale label (ISO), or null. M4 may
    *  reformat this; `label` already embeds a relative form. */
@@ -64,7 +64,8 @@ export function formatAsOf(capturedAt: string, now: number): string {
 export function deriveMachineChip(input: DeriveMachineChipInput): MachineChip {
   const now = input.now ?? Date.now();
   const asOf = input.capturedAt ?? null;
-  const offlineLabel = asOf ? `Offline — as of ${formatAsOf(asOf, now)}` : "Offline";
+  const managedRestingLabel = asOf ? `Sleeping · saved ${formatAsOf(asOf, now)}` : "Sleeping";
+  const offlineLabel = "Offline";
 
   // A connected machine has no Modal group lease, so capability negotiation
   // legitimately reports `cold` until a stream holder is minted. Its fleet
@@ -86,6 +87,16 @@ export function deriveMachineChip(input: DeriveMachineChipInput): MachineChip {
   const selfhostedOffline =
     input.activeIsSelfhosted === true && input.activeMachineState === "offline";
 
+  // Capability negotiation has definitively failed. A retained warm intent
+  // must not turn that error into the optimistic Waking state.
+  if (input.capabilitiesState === "error") {
+    return {
+      state: "offline",
+      label: input.activeIsSelfhosted === true ? offlineLabel : managedRestingLabel,
+      asOf,
+    };
+  }
+
   // 2. Actively coming up: negotiation in flight, an edit/terminal is warming, or
   //    the active machine is (re)connecting. Never when self-hosted is hard-offline.
   const machineWarming =
@@ -97,8 +108,14 @@ export function deriveMachineChip(input: DeriveMachineChipInput): MachineChip {
     return { state: "waking", label: "Waking…", asOf };
   }
 
-  // 3. Cold / asleep / offline / error → honest stale label.
-  return { state: "offline", label: offlineLabel, asOf };
+  // 3. Managed cold compute is sleeping with saved-workspace freshness. A
+  // Connected Machine is only described as Offline when its reachability is
+  // genuinely unavailable; capture time is not a heartbeat.
+  return {
+    state: "offline",
+    label: input.activeIsSelfhosted === true ? offlineLabel : managedRestingLabel,
+    asOf,
+  };
 }
 
 export type UseMachineChipOptions = DeriveMachineChipInput;