feat(cabinet): recoverable "service unavailable" screen when the backend is unreachable

When the backend was down the cabinet got stuck on a blank loader: the bootstrap
token refresh used bare axios with no timeout (hung forever), and every
interceptor guard required an HTTP response — so a transport-level failure had
zero handling and no error UI ever appeared.

Add a full-screen ServiceUnavailableScreen (extends the existing blocking-store
pattern) shown whenever the backend is unreachable, that auto-recovers when it
returns:
- New 'backend_unavailable' blocking type + BlockingOverlay branch; mirrors
  MaintenanceScreen, CloudWarningIcon, i18n in ru/en/zh/fa.
- api/health.ts: pingBackend() probes the root /health/unified (bypasses the
  /api baseURL + interceptor); URL derived from the origin for remote/sub-path
  deploys; 502/503/504 count as down. reportPossibleBackendDown() confirms an
  outage with a liveness probe before flipping, so a one-off blip never blanks a
  loaded app.
- Detected from the response interceptor (no-response) and the bootstrap refresh
  path; doRefresh gets a timeout so it can no longer hang.
- A transport failure during refresh now PRESERVES the session (distinguished
  from a rejected token via lastFailureWasTransport) instead of logging the user
  out, so recovery actually resumes.
- Recovery lifts the overlay + refetches for an already-loaded session, and only
  hard-reloads when the initial bootstrap never reached the backend — no lost
  form state. Manual retry + 5s auto-poll. Dev proxy for /health.

src/api/client.ts

@@ -7,6 +7,7 @@ import {
   safeRedirectToLogin,
 } from '../utils/token';
 import { useBlockingStore } from '../store/blocking';
+import { reportPossibleBackendDown, markBackendReached } from './health';
 import { API } from '../config/constants';
 
 const API_BASE_URL = import.meta.env.VITE_API_URL || '/api';
@@ -94,6 +95,12 @@ apiClient.interceptors.request.use(async (config: InternalAxiosRequestConfig) =>
       const newToken = await tokenRefreshManager.refreshAccessToken();
       if (newToken) {
         token = newToken;
+      } else if (tokenRefreshManager.lastFailureWasTransport) {
+        // Backend unreachable (not a rejected token): keep the session intact so
+        // the ServiceUnavailableScreen can auto-recover once the backend returns,
+        // instead of wiping tokens and stranding the user on /login. Let the
+        // request go out with the stale token; it will fail and be handled.
+        return config;
       } else {
         tokenStorage.clearTokens();
         safeRedirectToLogin();
@@ -195,10 +202,28 @@ export function isAccountDeletedError(
 }
 
 apiClient.interceptors.response.use(
-  (response) => response,
+  (response) => {
+    // First successful response means the app reached the backend at least once
+    // (it bootstrapped). Recovery from a later outage can then just lift the
+    // overlay instead of hard-reloading and losing unsaved UI state.
+    markBackendReached();
+    return response;
+  },
   async (error: AxiosError) => {
     const originalRequest = error.config as InternalAxiosRequestConfig & { _retry?: boolean };
 
+    // Transport-level failure: no HTTP response at all (backend unreachable, DNS
+    // failure, connection refused, timeout). All the coded guards below need
+    // `error.response`, so this case had zero handling and produced a blank
+    // screen during bootstrap. Confirm the outage with a liveness probe (so a
+    // one-off blip doesn't blank an already-loaded app) and, if confirmed, flip
+    // the full-screen ServiceUnavailableScreen. Fire-and-forget — the original
+    // request still rejects now. Axios cancellations are not outages.
+    if (!error.response && error.code !== 'ERR_CANCELED') {
+      void reportPossibleBackendDown();
+      return Promise.reject(error);
+    }
+
     if (isMaintenanceError(error)) {
       const detail = (error.response?.data as { detail: MaintenanceError }).detail;
       useBlockingStore.getState().setMaintenance({
@@ -256,6 +281,9 @@ apiClient.interceptors.response.use(
           originalRequest.headers.Authorization = `Bearer ${newToken}`;
         }
         return apiClient(originalRequest);
+      } else if (tokenRefreshManager.lastFailureWasTransport) {
+        // Backend died between the 401 and the refresh: keep the session so the
+        // ServiceUnavailableScreen can recover, rather than logging the user out.
       } else {
         tokenStorage.clearTokens();
         safeRedirectToLogin();

src/api/health.ts

@@ -0,0 +1,99 @@
+import axios from 'axios';
+import { useBlockingStore } from '../store/blocking';
+
+/**
+ * Backend liveness probe + "service unavailable" detection.
+ *
+ * The bot backend serves an unauthenticated liveness endpoint at the host ROOT
+ * (`/health/unified` when the Web API is enabled, `/health` otherwise) — NOT
+ * under the apiClient baseURL (`/api`). So we probe it with a BARE axios call at
+ * a root-relative URL, deliberately bypassing both the baseURL and the apiClient
+ * response interceptor (a probe must never itself touch blocking state).
+ */
+function resolveHealthUrl(): string {
+  const override = import.meta.env.VITE_HEALTH_URL;
+  if (override) return override;
+  const apiUrl = String(import.meta.env.VITE_API_URL || '/api').trim();
+  // For an absolute API base (remote / sub-path deployments like
+  // `https://api.bot.com/cabinet`) the health route still lives at the host
+  // ROOT, so derive the origin — NOT just strip `/api`. Mirrors the URL parsing
+  // in WebSocketProvider. For a relative base (`/api`, `/cabinet`) health is
+  // same-origin at the site root.
+  if (apiUrl.startsWith('http://') || apiUrl.startsWith('https://')) {
+    try {
+      return `${new URL(apiUrl).origin}/health/unified`;
+    } catch {
+      // malformed URL — fall through to the root-relative path
+    }
+  }
+  return '/health/unified';
+}
+
+export const HEALTH_URL = resolveHealthUrl();
+
+// Statuses a reverse proxy returns when it is up but its API upstream is down.
+// These must count as NOT reachable, otherwise the recovery poll would reload
+// the app straight back into a still-broken backend.
+const GATEWAY_DOWN_STATUSES = new Set([502, 503, 504]);
+
+/**
+ * Resolves true when the backend is actually serving — i.e. it returns an HTTP
+ * response that is NOT a gateway-down status. A 404 still counts as up (a
+ * Web-API-disabled deployment serves `/health`, not `/health/unified`, so
+ * probing the latter 404s while the server is fine). A 502/503/504 means a front
+ * proxy is up but the API upstream is dead, so it counts as NOT reachable.
+ * Resolves false on a transport-level failure with no response.
+ */
+export async function pingBackend(): Promise<boolean> {
+  try {
+    await axios.get(HEALTH_URL, { timeout: 5000 });
+    return true;
+  } catch (err) {
+    if (axios.isAxiosError(err) && err.response) {
+      return !GATEWAY_DOWN_STATUSES.has(err.response.status);
+    }
+    return false;
+  }
+}
+
+let everReachedBackend = false;
+
+/** Called on the first successful API response: the app reached the backend at
+ *  least once, so a later outage struck an already-loaded session. */
+export function markBackendReached(): void {
+  everReachedBackend = true;
+}
+
+/** True once the app has had at least one successful backend response. Lets the
+ *  ServiceUnavailableScreen recover by lifting the overlay (state preserved)
+ *  rather than hard-reloading, which is only needed when the INITIAL bootstrap
+ *  never reached the backend. */
+export function hasEverReachedBackend(): boolean {
+  return everReachedBackend;
+}
+
+let confirmInFlight = false;
+
+/**
+ * Called from the places that see a transport-level (no-response) failure — the
+ * apiClient interceptor and the bootstrap token refresh. Rather than blanking
+ * the whole app on a single one-off network blip, it CONFIRMS the outage with a
+ * liveness probe first and only then flips the global `backend_unavailable`
+ * state that renders the full-screen ServiceUnavailableScreen. Fire-and-forget:
+ * callers still reject/handle their own request immediately. Guarded so a burst
+ * of failing requests triggers at most one probe, and skipped once the screen is
+ * already shown.
+ */
+export async function reportPossibleBackendDown(): Promise<void> {
+  if (confirmInFlight) return;
+  if (useBlockingStore.getState().blockingType === 'backend_unavailable') return;
+  confirmInFlight = true;
+  try {
+    const reachable = await pingBackend();
+    if (!reachable) {
+      useBlockingStore.getState().setBackendUnavailable();
+    }
+  } finally {
+    confirmInFlight = false;
+  }
+}