Summary

Introduce a Dashboard Delivery Contract — a single source of truth for dashboard reachability configuration, a chain-level health verifier, and layered recovery. This replaces the current scattered approach where CORS origins, port forwarding, health probes, and access URLs are derived independently in 4+ files with no shared model.

Motivation

15 closed bugs, same files, same root cause

Over the past 5 weeks, 15 dashboard-related bugs have been filed, fixed as point patches, and closed — almost all touching onboard.ts, Dockerfile, nemoclaw-start.sh, and dashboard.ts:

12 of these 15 would have been prevented by a contract that derives all dashboard config from a single source and verifies the full delivery chain.

6 more open bugs in the same area

The Problem

The dashboard delivery chain has 4 links:

Link 1: Gateway Process      → running inside sandbox on :18789
Link 2: Port Forward          → SSH tunnel: host:18789 → sandbox:18789
Link 3: CORS / Auth Config    → allowedOrigins includes the browser's origin
Link 4: External Routing      → [Brev] nginx + cloudflared → host:18789

Today, each link is configured in a different file, checked in a different way (or not at all), and has no recovery mechanism:

• CHAT_UI_URL is derived independently in onboard.ts, Dockerfile, nemoclaw-start.sh, and dashboard.ts
• CORS origins are baked at Dockerfile build time with no runtime detection of the actual access URL
• Health probes check / (returns 401 with auth enabled) instead of /health
• Port forwarding is fire-and-forget with no health monitoring
• No function exists that answers "is the dashboard reachable end-to-end and if not, which link is broken?"
• Recovery only happens as a hidden side-effect of nemoclaw connect

Proposed Architecture

1. dashboard-contract.ts — Single Source of Truth (~80 lines)

interface DashboardDeliveryChain {
  accessUrl: string;        // auto-detected: Brev public URL, WSL host IP, or loopback
  corsOrigins: string[];    // always includes accessUrl origin + loopback
  forwardTarget: string;    // loopback → port-only; non-loopback → 0.0.0.0:port
  healthEndpoint: string;   // /health — accepts 200 or 401 as "alive"
  port: number;             // from NEMOCLAW_DASHBOARD_PORT or default
}

function buildChain(options?: { chatUiUrl?: string; platform?: string }): DashboardDeliveryChain;

All consumers (Dockerfile, onboard.ts, nemoclaw-start.sh, status, connect) read from this instead of deriving independently.

2. dashboard-health.ts — Chain Verification (~120 lines)

interface ChainStatus {
  healthy: boolean;
  links: {
    gateway: { ok: boolean; detail: string };
    forward: { ok: boolean; detail: string };
    cors: { ok: boolean; detail: string };
    external: { ok: boolean; detail: string };
  };
  diagnosis: string; // human-readable: "CORS allowedOrigins missing https://..."
}

function verifyDashboardChain(sandboxName: string): ChainStatus;

Used by nemoclaw status, onboard.ts (verify before printing success), and the dashboard UI.

3. dashboard-recover.ts — Layered Recovery (~100 lines)

function recoverDashboardChain(sandboxName: string): RecoverResult;

Idempotent, link-aware. Only fixes broken links:

• Link 1 down → restart gateway inside sandbox
• Link 2 down → re-establish openshell forward
• Link 3 wrong → patch CORS with detected accessUrl
• Link 4 down → diagnose and report (outside our control)

Used by nemoclaw recover (PR #2050), nemoclaw connect, and nemoclaw-start.sh on boot.

Files Changed

3 new files (~300 lines), 3 modified files (net code reduction in onboard.ts).

Open Issues This Would Address

Once landed, the following open issues can be resolved or significantly simplified:

• [NemoClaw][Brev Launchable] OpenClaw Gateway Dashboard shows "Version n/a" and "Health Offline" after Brev Launchable deployment succeeds #2342 — Brev Launchable dashboard dead → contract auto-detects Brev URL for CORS + forward
• [Sandbox][Recovery] Pod restart leaves OpenClaw gateway and dashboard port-forward dead; recovery is a side-effect of nemoclaw connect #2042 — Gateway/forward not recovered after pod restart → recoverDashboardChain on boot
• [Brev Launchable] Openclaw UI link is unhealthy #1178 — Intermittent unhealthy UI → chain verification diagnoses which link failed
• Brev onboard UI: OpenClaw preflight false red, openshell exec argv, SSE/nginx + cloudflared EOF #2258 — Brev CORS/probe/forward failures → contract handles all three
• [All Platform][Onboard][Regression] Second onboard crashes with unhandled exception and leaks ghost sandbox when dashboard port 18789 is already forwarded #2174 — Port contention on second onboard → contract centralizes port allocation
• [Feature] add coverage for OpenClaw dashboard reachability #2100 — No E2E dashboard test → verifyDashboardChain() becomes the test primitive

Non-Goals

• TLS certificate lifecycle (Gateway Restart Regenerates TLS Certificates Breaking Sandbox Connections - IssueFinder - SN 04 #1425) — separate concern
• Gateway internals (inference routing, provider setup) — outside the delivery chain
• Brev-specific nginx/cloudflared configuration — Link 4 is diagnose-only, not managed

Sequencing

This refactor touches onboard.ts and nemoclaw-start.sh, which currently have 9 open PRs against them. However, none of those PRs touch the dashboard delivery chain code (CORS, ensureDashboardForward, health probes, CHAT_UI_URL derivation). The contract can land independently or after the current wave of PRs clears.

Recommended approach: land #2342 (Brev Launchable point fix) first as a quick win, then follow with this refactor so the pattern doesn't repeat.