From df7b80d39a6416e32481f41fc74c5a7f5f8187af Mon Sep 17 00:00:00 2001
From: Isaac Rowntree <isaac@rowntree.me>
Date: Mon, 9 Feb 2026 10:52:13 +1100
Subject: [PATCH] feat: add gateway status indicator and controls to admin UI
 (#213)

Add GET /api/admin/gateway/status endpoint that checks process status
and port responsiveness to determine running/starting/stopped state.

Admin UI changes:
- Status badge next to "Gateway Controls" (green/yellow/red dot)
- Always "Restart Gateway" (gateway auto-starts on deploy)
- Post-restart polling until gateway is running or 60s timeout
- Background polling every 15s to keep status badge current
- "Backup Now" disabled when gateway not running

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 src/client/api.ts              |  10 +++
 src/client/pages/AdminPage.css |  57 +++++++++++++
 src/client/pages/AdminPage.tsx |  61 ++++++++++++--
 src/routes/api.test.ts         | 150 +++++++++++++++++++++++++++++++++
 src/routes/api.ts              |  32 ++++++-
 5 files changed, 301 insertions(+), 9 deletions(-)
 create mode 100644 src/routes/api.test.ts

diff --git a/src/client/api.ts b/src/client/api.ts
index 317542891..5c8f10726 100644
--- a/src/client/api.ts
+++ b/src/client/api.ts
@@ -101,6 +101,16 @@ export async function approveAllDevices(): Promise<ApproveAllResponse> {
   });
 }
 
+export interface GatewayStatusResponse {
+  status: 'running' | 'starting' | 'stopped';
+  processId?: string;
+  error?: string;
+}
+
+export async function getGatewayStatus(): Promise<GatewayStatusResponse> {
+  return apiRequest<GatewayStatusResponse>('/gateway/status');
+}
+
 export interface RestartGatewayResponse {
   success: boolean;
   message?: string;
diff --git a/src/client/pages/AdminPage.css b/src/client/pages/AdminPage.css
index b81ff5c4e..a722db374 100644
--- a/src/client/pages/AdminPage.css
+++ b/src/client/pages/AdminPage.css
@@ -161,6 +161,63 @@
   color: var(--text-muted);
 }
 
+.section-title-row {
+  display: flex;
+  align-items: center;
+  gap: 0.75rem;
+}
+
+.gateway-status-badge {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.375rem;
+  font-size: 0.75rem;
+  font-weight: 500;
+  padding: 0.25rem 0.625rem;
+  border-radius: 9999px;
+  text-transform: uppercase;
+  letter-spacing: 0.025em;
+}
+
+.gateway-status-badge .status-dot {
+  width: 8px;
+  height: 8px;
+  border-radius: 50%;
+}
+
+.gateway-status-badge.running {
+  background-color: rgba(74, 222, 128, 0.15);
+  color: var(--success-color);
+}
+
+.gateway-status-badge.running .status-dot {
+  background-color: var(--success-color);
+}
+
+.gateway-status-badge.starting {
+  background-color: rgba(251, 191, 36, 0.15);
+  color: var(--warning-color);
+}
+
+.gateway-status-badge.starting .status-dot {
+  background-color: var(--warning-color);
+  animation: pulse-dot 1.5s ease-in-out infinite;
+}
+
+.gateway-status-badge.stopped {
+  background-color: rgba(239, 68, 68, 0.15);
+  color: var(--error-color);
+}
+
+.gateway-status-badge.stopped .status-dot {
+  background-color: var(--error-color);
+}
+
+@keyframes pulse-dot {
+  0%, 100% { opacity: 1; }
+  50% { opacity: 0.3; }
+}
+
 /* Empty state */
 .empty-state {
   text-align: center;
diff --git a/src/client/pages/AdminPage.tsx b/src/client/pages/AdminPage.tsx
index cfe725fce..695f10a84 100644
--- a/src/client/pages/AdminPage.tsx
+++ b/src/client/pages/AdminPage.tsx
@@ -4,6 +4,7 @@ import {
   approveDevice,
   approveAllDevices,
   restartGateway,
+  getGatewayStatus,
   getStorageStatus,
   triggerSync,
   AuthError,
@@ -11,6 +12,7 @@ import {
   type PairedDevice,
   type DeviceListResponse,
   type StorageStatusResponse,
+  type GatewayStatusResponse,
 } from '../api';
 import './AdminPage.css';
 
@@ -49,6 +51,7 @@ export default function AdminPage() {
   const [pending, setPending] = useState<PendingDevice[]>([]);
   const [paired, setPaired] = useState<PairedDevice[]>([]);
   const [storageStatus, setStorageStatus] = useState<StorageStatusResponse | null>(null);
+  const [gatewayStatus, setGatewayStatus] = useState<GatewayStatusResponse | null>(null);
   const [loading, setLoading] = useState(true);
   const [error, setError] = useState<string | null>(null);
   const [actionInProgress, setActionInProgress] = useState<string | null>(null);
@@ -88,10 +91,28 @@ export default function AdminPage() {
     }
   }, []);
 
+  const fetchGatewayStatus = useCallback(async () => {
+    try {
+      const status = await getGatewayStatus();
+      setGatewayStatus(status);
+      return status;
+    } catch (err) {
+      console.error('Failed to fetch gateway status:', err);
+      return null;
+    }
+  }, []);
+
   useEffect(() => {
     fetchDevices();
     fetchStorageStatus();
-  }, [fetchDevices, fetchStorageStatus]);
+    fetchGatewayStatus();
+  }, [fetchDevices, fetchStorageStatus, fetchGatewayStatus]);
+
+  // Poll gateway status every 15s so the badge stays current
+  useEffect(() => {
+    const id = setInterval(fetchGatewayStatus, 15000);
+    return () => clearInterval(id);
+  }, [fetchGatewayStatus]);
 
   const handleApprove = async (requestId: string) => {
     setActionInProgress(requestId);
@@ -138,19 +159,31 @@ export default function AdminPage() {
     }
 
     setRestartInProgress(true);
+    setGatewayStatus((prev) => prev ? { ...prev, status: 'starting' } : { status: 'starting' });
     try {
       const result = await restartGateway();
       if (result.success) {
         setError(null);
-        // Show success message briefly
-        alert('Gateway restart initiated. Clients will reconnect automatically.');
+        // Poll for gateway status until running or timeout (60s)
+        const startTime = Date.now();
+        const poll = async () => {
+          const status = await fetchGatewayStatus();
+          if (status?.status === 'running' || Date.now() - startTime > 60000) {
+            setRestartInProgress(false);
+            return;
+          }
+          setTimeout(poll, 2000);
+        };
+        setTimeout(poll, 2000);
       } else {
         setError(result.error || 'Failed to restart gateway');
+        setRestartInProgress(false);
+        fetchGatewayStatus();
       }
     } catch (err) {
       setError(err instanceof Error ? err.message : 'Failed to restart gateway');
-    } finally {
       setRestartInProgress(false);
+      fetchGatewayStatus();
     }
   };
 
@@ -220,7 +253,8 @@ export default function AdminPage() {
             <button
               className="btn btn-secondary btn-sm"
               onClick={handleSync}
-              disabled={syncInProgress}
+              disabled={syncInProgress || gatewayStatus?.status !== 'running'}
+              title={gatewayStatus?.status !== 'running' ? 'Gateway must be running to backup' : undefined}
             >
               {syncInProgress && <ButtonSpinner />}
               {syncInProgress ? 'Syncing...' : 'Backup Now'}
@@ -231,7 +265,17 @@ export default function AdminPage() {
 
       <section className="devices-section gateway-section">
         <div className="section-header">
-          <h2>Gateway Controls</h2>
+          <div className="section-title-row">
+            <h2>Gateway Controls</h2>
+            {gatewayStatus && (
+              <span className={`gateway-status-badge ${gatewayStatus.status}`}>
+                <span className="status-dot" />
+                {gatewayStatus.status === 'running' && 'Running'}
+                {gatewayStatus.status === 'starting' && 'Starting'}
+                {gatewayStatus.status === 'stopped' && 'Stopped'}
+              </span>
+            )}
+          </div>
           <button
             className="btn btn-danger"
             onClick={handleRestartGateway}
@@ -242,8 +286,9 @@ export default function AdminPage() {
           </button>
         </div>
         <p className="hint">
-          Restart the gateway to apply configuration changes or recover from errors. All connected
-          clients will be temporarily disconnected.
+          {gatewayStatus?.status === 'stopped'
+            ? 'The gateway is not running. It starts automatically on deploy — use restart to recover from errors.'
+            : 'Restart the gateway to apply configuration changes or recover from errors. All connected clients will be temporarily disconnected.'}
         </p>
       </section>
 
diff --git a/src/routes/api.test.ts b/src/routes/api.test.ts
new file mode 100644
index 000000000..5d1322f75
--- /dev/null
+++ b/src/routes/api.test.ts
@@ -0,0 +1,150 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { Hono } from 'hono';
+import type { AppEnv } from '../types';
+import { createMockEnv, createMockSandbox, suppressConsole } from '../test-utils';
+import type { Process } from '@cloudflare/sandbox';
+
+import { api } from './api';
+
+function createFullMockProcess(overrides: Partial<Process> = {}): Process {
+  return {
+    id: 'test-id',
+    command: 'openclaw gateway',
+    status: 'running',
+    startTime: new Date(),
+    endTime: undefined,
+    exitCode: undefined,
+    waitForPort: vi.fn(),
+    kill: vi.fn(),
+    getLogs: vi.fn().mockResolvedValue({ stdout: '', stderr: '' }),
+    ...overrides,
+  } as Process;
+}
+
+/**
+ * Build a test app that sets up sandbox on context and mounts the api routes.
+ */
+function createTestApp(mockSandbox: ReturnType<typeof createMockSandbox>) {
+  const app = new Hono<AppEnv>();
+
+  // Middleware: inject sandbox into context (mirrors src/index.ts)
+  app.use('*', async (c, next) => {
+    c.set('sandbox', mockSandbox.sandbox);
+    await next();
+  });
+
+  // Mount the api routes
+  app.route('/api', api);
+
+  return app;
+}
+
+function makeRequest(app: Hono<AppEnv>, path: string, env: Record<string, unknown> = {}) {
+  const mockEnv = createMockEnv({ DEV_MODE: 'true', ...env });
+  return app.request(path, {}, mockEnv);
+}
+
+describe('GET /api/admin/gateway/status', () => {
+  beforeEach(() => {
+    suppressConsole();
+  });
+
+  it('returns stopped when no gateway process found', async () => {
+    const mockSandbox = createMockSandbox({ processes: [] });
+    const app = createTestApp(mockSandbox);
+
+    const res = await makeRequest(app, '/api/admin/gateway/status');
+    expect(res.status).toBe(200);
+
+    const body = await res.json();
+    expect(body.status).toBe('stopped');
+    expect(body.processId).toBeUndefined();
+  });
+
+  it('returns running when process exists and port responds', async () => {
+    const gatewayProcess = createFullMockProcess({
+      id: 'gw-123',
+      command: 'openclaw gateway --port 18789',
+      status: 'running',
+    });
+    const mockSandbox = createMockSandbox();
+    mockSandbox.listProcessesMock.mockResolvedValue([gatewayProcess]);
+    mockSandbox.containerFetchMock.mockResolvedValue(new Response('OK', { status: 200 }));
+
+    const app = createTestApp(mockSandbox);
+    const res = await makeRequest(app, '/api/admin/gateway/status');
+    expect(res.status).toBe(200);
+
+    const body = await res.json();
+    expect(body.status).toBe('running');
+    expect(body.processId).toBe('gw-123');
+  });
+
+  it('returns starting when process exists but port does not respond', async () => {
+    const gatewayProcess = createFullMockProcess({
+      id: 'gw-456',
+      command: '/usr/local/bin/start-openclaw.sh',
+      status: 'starting',
+    });
+    const mockSandbox = createMockSandbox();
+    mockSandbox.listProcessesMock.mockResolvedValue([gatewayProcess]);
+    mockSandbox.containerFetchMock.mockRejectedValue(new Error('Connection refused'));
+
+    const app = createTestApp(mockSandbox);
+    const res = await makeRequest(app, '/api/admin/gateway/status');
+    expect(res.status).toBe(200);
+
+    const body = await res.json();
+    expect(body.status).toBe('starting');
+    expect(body.processId).toBe('gw-456');
+  });
+
+  it('returns stopped when listProcesses fails gracefully', async () => {
+    const mockSandbox = createMockSandbox();
+    mockSandbox.listProcessesMock.mockRejectedValue(new Error('Sandbox unavailable'));
+    // findExistingMoltbotProcess catches listProcesses errors and returns null
+    const app = createTestApp(mockSandbox);
+    const res = await makeRequest(app, '/api/admin/gateway/status');
+    expect(res.status).toBe(200);
+
+    const body = await res.json();
+    expect(body.status).toBe('stopped');
+  });
+
+  it('returns running even when containerFetch returns a non-200 status', async () => {
+    const gatewayProcess = createFullMockProcess({
+      id: 'gw-789',
+      command: 'openclaw gateway',
+      status: 'running',
+    });
+    const mockSandbox = createMockSandbox();
+    mockSandbox.listProcessesMock.mockResolvedValue([gatewayProcess]);
+    // Gateway responds with 404 — still means port is up
+    mockSandbox.containerFetchMock.mockResolvedValue(new Response('Not Found', { status: 404 }));
+
+    const app = createTestApp(mockSandbox);
+    const res = await makeRequest(app, '/api/admin/gateway/status');
+    expect(res.status).toBe(200);
+
+    const body = await res.json();
+    expect(body.status).toBe('running');
+    expect(body.processId).toBe('gw-789');
+  });
+
+  it('ignores CLI command processes and returns stopped', async () => {
+    const cliProcess = createFullMockProcess({
+      id: 'cli-1',
+      command: 'openclaw devices list --json',
+      status: 'running',
+    });
+    const mockSandbox = createMockSandbox();
+    mockSandbox.listProcessesMock.mockResolvedValue([cliProcess]);
+
+    const app = createTestApp(mockSandbox);
+    const res = await makeRequest(app, '/api/admin/gateway/status');
+    expect(res.status).toBe(200);
+
+    const body = await res.json();
+    expect(body.status).toBe('stopped');
+  });
+});
diff --git a/src/routes/api.ts b/src/routes/api.ts
index bbc04feb7..32ec70cea 100644
--- a/src/routes/api.ts
+++ b/src/routes/api.ts
@@ -8,7 +8,7 @@ import {
   syncToR2,
   waitForProcess,
 } from '../gateway';
-import { R2_MOUNT_PATH } from '../config';
+import { R2_MOUNT_PATH, MOLTBOT_PORT } from '../config';
 
 // CLI commands can take 10-15 seconds to complete due to WebSocket connection overhead
 const CLI_TIMEOUT_MS = 20000;
@@ -269,6 +269,36 @@ adminApi.post('/storage/sync', async (c) => {
   }
 });
 
+// GET /api/admin/gateway/status - Check gateway process status
+adminApi.get('/gateway/status', async (c) => {
+  const sandbox = c.get('sandbox');
+
+  try {
+    const process = await findExistingMoltbotProcess(sandbox);
+
+    if (!process) {
+      return c.json({ status: 'stopped' as const });
+    }
+
+    // Process exists — check if port is responding
+    try {
+      const url = `http://localhost:${MOLTBOT_PORT}/`;
+      const response = await sandbox.containerFetch(new Request(url), MOLTBOT_PORT);
+      // Any response (even 404) means the port is up
+      if (response) {
+        return c.json({ status: 'running' as const, processId: process.id });
+      }
+    } catch {
+      // Port not responding — process is still starting
+    }
+
+    return c.json({ status: 'starting' as const, processId: process.id });
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+    return c.json({ error: errorMessage }, 500);
+  }
+});
+
 // POST /api/admin/gateway/restart - Kill the current gateway and start a new one
 adminApi.post('/gateway/restart', async (c) => {
   const sandbox = c.get('sandbox');