feat(desktop): surface a host unreachable screen for v2 workspaces

apps/desktop/src/renderer/routes/_authenticated/_dashboard/v2-workspace/components/WorkspaceHostOfflineState/WorkspaceHostOfflineState.tsx → apps/desktop/src/renderer/routes/_authenticated/_dashboard/v2-workspace/components/WorkspaceHostUnreachableState/WorkspaceHostUnreachableState.tsx

@@ -1,16 +1,29 @@
 import { Button } from "@superset/ui/button";
+import { cn } from "@superset/ui/utils";
 import { Link } from "@tanstack/react-router";
-import { ArrowRight, Monitor, Settings, WifiOff } from "lucide-react";
+import { Monitor, RefreshCw, Settings, WifiOff } from "lucide-react";
 
-interface WorkspaceHostOfflineStateProps {
+interface WorkspaceHostUnreachableStateProps {
 	hostId: string;
 	hostName: string;
+	/** Why this connection in particular is down. */
+	detail: string;
+	/** The socket is still dialling on its own backoff. */
+	isReconnecting: boolean;
+	onRetry: () => void;
+	retryLabel?: string;
+	retryBusyLabel?: string;
 }
 
-export function WorkspaceHostOfflineState({
+export function WorkspaceHostUnreachableState({
 	hostId,
 	hostName,
-}: WorkspaceHostOfflineStateProps) {
+	detail,
+	isReconnecting,
+	onRetry,
+	retryLabel = "Retry",
+	retryBusyLabel = "Retrying…",
+}: WorkspaceHostUnreachableStateProps) {
 	return (
 		<div className="flex h-full w-full items-center justify-center p-6">
 			<div className="flex w-full max-w-sm flex-col items-start gap-6">
@@ -32,27 +45,38 @@ export function WorkspaceHostOfflineState({
 
 				<div className="flex flex-col gap-1.5">
 					<h1 className="text-[15px] font-medium tracking-tight text-foreground">
-						Host offline
+						Host unreachable
 					</h1>
 					<p className="select-text cursor-text text-[13px] leading-relaxed text-muted-foreground">
-						This workspace lives on a paired device that is not reachable right
-						now. Terminals and file actions are unavailable until that device
-						reconnects.
+						This workspace lives on a device Superset can't reach right now.
+						Terminals, files, and agents stay put — they come back as soon as
+						the connection does.
+					</p>
+					<p className="select-text cursor-text text-[13px] leading-relaxed text-muted-foreground/80">
+						{detail}
 					</p>
 				</div>
 
 				<div className="flex w-full flex-col gap-0 overflow-hidden rounded-md border border-border/60 bg-muted/30">
 					<div className="flex items-center gap-2.5 px-3 py-2">
 						<span
 							aria-hidden="true"
-							className="size-1.5 shrink-0 rounded-full bg-muted-foreground/40"
+							className={cn(
+								"size-1.5 shrink-0 rounded-full",
+								isReconnecting
+									? "animate-pulse bg-yellow-500"
+									: "bg-muted-foreground/40",
+							)}
 						/>
 						<span
 							className="select-text cursor-text min-w-0 truncate text-[13px] font-medium text-foreground"
 							title={hostName}
 						>
 							{hostName}
 						</span>
+						<span className="ml-auto shrink-0 text-[11px] uppercase tracking-wider text-muted-foreground/70">
+							{isReconnecting ? "Reconnecting" : "Disconnected"}
+						</span>
 					</div>
 					<div className="border-t border-border/60 px-3 py-2">
 						<div className="grid gap-1.5 sm:grid-cols-[auto_minmax(0,1fr)] sm:items-center sm:gap-3">
@@ -73,33 +97,31 @@ export function WorkspaceHostOfflineState({
 
 				<div className="flex flex-wrap items-center gap-2">
 					<Button
-						asChild
 						size="sm"
-						variant="ghost"
-						className="-ml-2 h-7 gap-1.5 px-2 text-[13px] font-medium text-foreground hover:bg-muted/60"
+						variant="secondary"
+						className="h-7 gap-1.5 px-2.5 text-[13px] font-medium"
+						onClick={onRetry}
 					>
-						<Link to="/settings/hosts/$hostId" params={{ hostId }}>
-							<Settings
-								className="size-3.5"
-								strokeWidth={2}
-								aria-hidden="true"
-							/>
-							Host settings
-						</Link>
+						<RefreshCw
+							className={cn("size-3.5", isReconnecting && "animate-spin")}
+							strokeWidth={2}
+							aria-hidden="true"
+						/>
+						{isReconnecting ? retryBusyLabel : retryLabel}
 					</Button>
 					<Button
 						asChild
 						size="sm"
 						variant="ghost"
 						className="h-7 gap-1.5 px-2 text-[13px] font-medium text-foreground hover:bg-muted/60"
 					>
-						<Link to="/v2-workspaces">
-							Browse workspaces
-							<ArrowRight
+						<Link to="/settings/hosts/$hostId" params={{ hostId }}>
+							<Settings
 								className="size-3.5"
 								strokeWidth={2}
 								aria-hidden="true"
 							/>
+							Host settings
 						</Link>
 					</Button>
 				</div>

apps/desktop/src/renderer/routes/_authenticated/_dashboard/v2-workspace/components/WorkspaceHostUnreachableState/index.ts

@@ -0,0 +1 @@
+export { WorkspaceHostUnreachableState } from "./WorkspaceHostUnreachableState";

apps/desktop/src/renderer/routes/_authenticated/_dashboard/v2-workspace/hooks/useHostReachability/index.ts

@@ -0,0 +1,4 @@
+export {
+	type HostReachability,
+	useHostReachability,
+} from "./useHostReachability";

apps/desktop/src/renderer/routes/_authenticated/_dashboard/v2-workspace/hooks/useHostReachability/useHostReachability.ts

@@ -0,0 +1,103 @@
+import {
+	getEventBus,
+	type HostConnectionStatus,
+} from "@superset/workspace-client";
+import { useCallback, useEffect, useMemo, useSyncExternalStore } from "react";
+import { useDelayElapsed } from "renderer/hooks/useDelayElapsed";
+import { getHostServiceWsToken } from "renderer/lib/host-service-auth";
+
+/**
+ * How long the host has to stay unreachable before the workspace hands over to
+ * the unreachable screen. The socket reconnects on its own backoff, so a relay
+ * redeploy, a laptop lid, or a half-open TCP flap resolves well inside this
+ * window — taking the screen over for those would be the false-positive that
+ * got the earlier cloud-presence gate reverted twice (#4430, #4727).
+ */
+const UNREACHABLE_GRACE_MS = 10_000;
+
+/**
+ * While the screen is up, dial on this cadence instead of riding the socket's
+ * own backoff. That backoff grows to 30s, so a host that came back could sit
+ * behind "Reconnecting…" for half a minute — measured at 20.7s — which reads
+ * as broken next to copy promising the workspace returns with the connection.
+ * Only runs while the takeover is visible, so it can't hammer a healthy host.
+ */
+const REDIAL_INTERVAL_MS = 5_000;
+
+export interface HostReachability {
+	/** Sustained loss of the host connection — safe to take the screen over. */
+	isUnreachable: boolean;
+	/** A dial is in flight right now (auto-backoff or a manual retry). */
+	isReconnecting: boolean;
+	/** What the relay preflight says is wrong. Only read while unreachable. */
+	detail: string;
+	/** Dial now instead of waiting out the backoff. */
+	retry: () => void;
+}
+
+function describeFailure(
+	status: HostConnectionStatus,
+	isRelayHost: boolean,
+): string {
+	if (!isRelayHost) {
+		return "The local host service stopped answering. Retry first; if that doesn't take, restart it from the Superset tray menu > Host Service > Restart.";
+	}
+	const probe = status.probe;
+	// No probe result at all: the relay itself never answered.
+	if (!probe) {
+		return "Couldn't reach the relay service. Check this machine's network connection — the other device is probably fine.";
+	}
+	if (probe.status === 503) {
+		return "That device isn't connected to the relay. Check it's awake, online, and running Superset — it reconnects on its own once it is.";
+	}
+	if (probe.status === 401 || probe.status === 403) {
+		return "You don't have access to this host. If it's your own device, turn on relay access there under Settings > Security.";
+	}
+	if (probe.status === 502 || probe.status === 504) {
+		return "The relay couldn't reach that device right now. This is usually temporary — retrying in a moment normally works.";
+	}
+	if (probe.status === 200) {
+		const where = probe.region ? ` (region ${probe.region})` : "";
+		return `That device is online${where} but the connection couldn't be established — usually relay routing rather than the device itself. Retry, and if it persists restart Superset on that device.`;
+	}
+	return `The connection failed (relay status ${probe.status}). Retry, and if it persists restart Superset on that device.`;
+}
+
+/**
+ * Live reachability of the host serving this workspace, read off the shared
+ * event-bus socket — the same connection the workspace's own data flows over,
+ * so it reflects what the UI can actually do rather than the cloud's `isOnline`
+ * flag (which drifts through relay redeploys and API blips).
+ */
+export function useHostReachability(hostUrl: string): HostReachability {
+	const bus = useMemo(
+		() => getEventBus(hostUrl, () => getHostServiceWsToken(hostUrl)),
+		[hostUrl],
+	);
+	// Hold the connection open for as long as this screen is mounted: the
+	// panes that normally keep the bus alive are gone once we take over, and a
+	// closed socket would never observe the host coming back.
+	useEffect(() => bus.retain(), [bus]);
+
+	const status = useSyncExternalStore(
+		useCallback((onChange) => bus.subscribeConnectionStatus(onChange), [bus]),
+		() => bus.getConnectionStatus(),
+	);
+
+	const isDown = status.state !== "open";
+	const isUnreachable = useDelayElapsed(isDown, UNREACHABLE_GRACE_MS);
+	const isRelayHost = /\/hosts\/[^/]+/.test(hostUrl);
+
+	useEffect(() => {
+		if (!isUnreachable) return;
+		const timer = window.setInterval(() => bus.reconnect(), REDIAL_INTERVAL_MS);
+		return () => window.clearInterval(timer);
+	}, [isUnreachable, bus]);
+
+	return {
+		isUnreachable,
+		isReconnecting: isDown && status.state !== "closed",
+		detail: describeFailure(status, isRelayHost),
+		retry: () => bus.reconnect(),
+	};
+}

apps/desktop/src/renderer/routes/_authenticated/_dashboard/v2-workspace/providers/WorkspaceProvider/WorkspaceProvider.tsx

@@ -1,5 +1,11 @@
 import { buildHostRoutingKey } from "@superset/shared/host-routing";
-import { createContext, type ReactNode, useContext } from "react";
+import {
+	createContext,
+	type ReactNode,
+	useContext,
+	useEffect,
+	useRef,
+} from "react";
 import type { HostShapedWorkspace } from "renderer/hooks/host-workspaces/useHostWorkspaces";
 import { useRelayUrl } from "renderer/hooks/useRelayUrl";
 import {
@@ -8,6 +14,8 @@ import {
 } from "renderer/lib/host-service-auth";
 import { useLocalHostService } from "renderer/routes/_authenticated/providers/LocalHostServiceProvider";
 import { WorkspaceTrpcProvider } from "../WorkspaceTrpcProvider";
+import { WorkspaceHostGate } from "./components/WorkspaceHostGate";
+import { WorkspaceLocalHostPendingState } from "./components/WorkspaceLocalHostPendingState";
 
 interface WorkspaceContextValue {
 	workspace: HostShapedWorkspace;
@@ -25,28 +33,46 @@ export function WorkspaceProvider({
 }) {
 	const { machineId, activeHostUrl } = useLocalHostService();
 	const relayUrl = useRelayUrl();
+
+	// A host-service restart takes the coordinator's port away for ~5s and
+	// usually brings it back on the same one. Dropping to null there would
+	// unmount the whole workspace — panes, scrollback, unsaved files — and
+	// leave a blank frame until it returned. Keep serving the last URL we had
+	// and let WorkspaceHostGate handle the dead socket in place.
+	const lastLocalHostUrlRef = useRef<string | null>(null);
+	useEffect(() => {
+		if (activeHostUrl) lastLocalHostUrlRef.current = activeHostUrl;
+	}, [activeHostUrl]);
+	const localHostUrl = activeHostUrl ?? lastLocalHostUrlRef.current;
+
 	const hostUrl =
 		workspace.hostId === machineId
-			? activeHostUrl
+			? localHostUrl
 			: `${relayUrl}/hosts/${buildHostRoutingKey(
 					workspace.organizationId,
 					workspace.hostId,
 				)}`;
 
+	// Only before the local host service has ever reported a port — there is
+	// nothing to point a client at, so this can't go through WorkspaceHostGate.
 	if (!hostUrl) {
-		return <div className="flex h-full w-full" />;
+		return <WorkspaceLocalHostPendingState hostId={workspace.hostId} />;
 	}
 
 	return (
 		<WorkspaceContext.Provider value={{ workspace, hostUrl }}>
+			{/* Keyed on the workspace alone: the host service can come back on a
+			    different port, and keying on the URL too would remount every pane
+			    for what is only a transport swap. WorkspaceClientProvider already
+			    rebuilds its clients when hostUrl changes. */}
 			<WorkspaceTrpcProvider
 				cacheKey={workspace.id}
-				key={`${workspace.id}:${hostUrl}`}
+				key={workspace.id}
 				hostUrl={hostUrl}
 				headers={() => getHostServiceHeaders(hostUrl)}
 				wsToken={() => getHostServiceWsToken(hostUrl)}
 			>
-				{children}
+				<WorkspaceHostGate workspace={workspace}>{children}</WorkspaceHostGate>
 			</WorkspaceTrpcProvider>
 		</WorkspaceContext.Provider>
 	);

apps/desktop/src/renderer/routes/_authenticated/_dashboard/v2-workspace/providers/WorkspaceProvider/components/WorkspaceHostGate/WorkspaceHostGate.tsx

@@ -0,0 +1,68 @@
+import { useWorkspaceHostUrl } from "@superset/workspace-client";
+import type { ReactNode } from "react";
+import type { HostShapedWorkspace } from "renderer/hooks/host-workspaces/useHostWorkspaces";
+import { cloudTrpc } from "renderer/lib/cloud-trpc";
+import { useLocalHostService } from "renderer/routes/_authenticated/providers/LocalHostServiceProvider";
+import { StateScreenShell } from "../../../../components/StateScreenShell";
+import { WorkspaceHostUnreachableState } from "../../../../components/WorkspaceHostUnreachableState";
+import { useHostReachability } from "../../../../hooks/useHostReachability";
+
+const HOST_LIST_STALE_MS = 30_000;
+
+/**
+ * Covers the workspace with the unreachable screen while its host is down.
+ * Overlays rather than replaces: panes keep their live state (terminal
+ * scrollback, unsaved editor documents, in-flight agent sessions) so a dropped
+ * connection costs nothing once the host is back.
+ */
+export function WorkspaceHostGate({
+	workspace,
+	children,
+}: {
+	workspace: HostShapedWorkspace;
+	children: ReactNode;
+}) {
+	const hostUrl = useWorkspaceHostUrl();
+	const { isUnreachable, isReconnecting, detail, retry } =
+		useHostReachability(hostUrl);
+	const { machineId } = useLocalHostService();
+	const { data: hostRows = [] } = cloudTrpc.v2Host.list.useQuery(undefined, {
+		staleTime: HOST_LIST_STALE_MS,
+	});
+
+	const hostRow =
+		hostRows.find(
+			(host) =>
+				host.organizationId === workspace.organizationId &&
+				host.machineId === workspace.hostId,
+		) ?? null;
+	const hostName =
+		hostRow?.name ??
+		(workspace.hostId === machineId ? "This device" : "Unknown host");
+
+	// The wrapper renders unconditionally — dropping it when the host is
+	// reachable would move `children` in the tree and remount the whole
+	// workspace on every reconnect.
+	return (
+		<div className="relative flex min-h-0 min-w-0 flex-1">
+			{/* Covered panes stay mounted, so without `inert` they keep taking Tab
+			    stops and screen-reader focus behind the takeover. */}
+			<div className="flex min-h-0 min-w-0 flex-1" inert={isUnreachable}>
+				{children}
+			</div>
+			{isUnreachable ? (
+				<div className="absolute inset-0 z-50 bg-background">
+					<StateScreenShell>
+						<WorkspaceHostUnreachableState
+							hostId={workspace.hostId}
+							hostName={hostName}
+							detail={detail}
+							isReconnecting={isReconnecting}
+							onRetry={retry}
+						/>
+					</StateScreenShell>
+				</div>
+			) : null}
+		</div>
+	);
+}

apps/desktop/src/renderer/routes/_authenticated/_dashboard/v2-workspace/providers/WorkspaceProvider/components/WorkspaceHostGate/index.ts

@@ -0,0 +1 @@
+export { WorkspaceHostGate } from "./WorkspaceHostGate";