selftune 0.2.23 → 0.2.24

package/cli/selftune/dashboard-server.ts

@@ -22,7 +22,7 @@ import type { Database } from "bun:sqlite";
 import { existsSync, readFileSync, unwatchFile, watchFile } from "node:fs";
 import { dirname, extname, isAbsolute, join, relative, resolve } from "node:path";
 
-import type { BadgeFormat } from "./badge/badge-svg.js";
+import type { BadgeFormat } from "./badge/badge-data.js";
 import { LOG_DIR, SELFTUNE_CONFIG_DIR } from "./constants.js";
 import type {
   HealthResponse,
@@ -52,12 +52,13 @@ import {
 } from "./routes/index.js";
 import type { StatusResult } from "./status.js";
 import { computeStatus } from "./status.js";
-import type { EvolutionEvidenceEntry } from "./types.js";
+import type { EvolutionAuditEntry, EvolutionEvidenceEntry } from "./types.js";
 
 export interface DashboardServerOptions {
   port?: number;
   host?: string;
   spaDir?: string;
+  spaProxyUrl?: string;
   openBrowser?: boolean;
   runtimeMode?: HealthResponse["process_mode"];
   statusLoader?: () => StatusResult | Promise<StatusResult>;
@@ -67,13 +68,18 @@ export interface DashboardServerOptions {
   actionRunner?: ActionRunner;
 }
 
-/** Read selftune version from package.json once at startup */
-let selftuneVersion = "unknown";
-try {
-  const pkgPath = join(import.meta.dir, "..", "..", "package.json");
-  selftuneVersion = JSON.parse(readFileSync(pkgPath, "utf-8")).version;
-} catch {
-  // fallback already set
+interface DashboardSocketData {
+  upstreamUrl?: string;
+}
+
+/** Read selftune version from package.json (fresh on each call to pick up auto-updates). */
+const VERSION_PKG_PATH = join(import.meta.dir, "..", "..", "package.json");
+function getSelftuneVersion(): string {
+  try {
+    return JSON.parse(readFileSync(VERSION_PKG_PATH, "utf-8")).version;
+  } catch {
+    return "unknown";
+  }
 }
 
 /** Resolve short git SHA once at startup (cached). */
@@ -89,6 +95,10 @@ function getGitSha(): string {
   return cachedGitSha;
 }
 
+function getSpaBuildId(): string {
+  return process.env.SELFTUNE_SPA_BUILD_ID || getSelftuneVersion();
+}
+
 const WORKSPACE_ROOT = resolve(import.meta.dir, "..", "..");
 
 function findSpaDir(): string | null {
@@ -121,6 +131,47 @@ function allowedDashboardOrigins(hostname: string, port: number): Set<string> {
   return origins;
 }
 
+function normalizeSpaProxyUrl(rawValue: string | undefined): URL | null {
+  if (!rawValue) return null;
+  try {
+    const url = new URL(rawValue);
+    if (url.protocol !== "http:" && url.protocol !== "https:") {
+      return null;
+    }
+    return url;
+  } catch {
+    return null;
+  }
+}
+
+function shouldProxySpaRequest(pathname: string): boolean {
+  return (
+    !pathname.startsWith("/api/") &&
+    !pathname.startsWith("/badge/") &&
+    !pathname.startsWith("/report/")
+  );
+}
+
+async function proxySpaRequest(req: Request, proxyBaseUrl: URL, url: URL): Promise<Response> {
+  const targetUrl = new URL(`${url.pathname}${url.search}`, proxyBaseUrl);
+  const headers = new Headers(req.headers);
+  headers.set("host", targetUrl.host);
+  const upstreamResponse = await fetch(targetUrl, {
+    method: req.method,
+    headers,
+    redirect: "manual",
+  });
+  const proxiedHeaders = new Headers(upstreamResponse.headers);
+  for (const [key, value] of Object.entries(corsHeaders())) {
+    proxiedHeaders.set(key, value);
+  }
+  return new Response(upstreamResponse.body, {
+    status: upstreamResponse.status,
+    statusText: upstreamResponse.statusText,
+    headers: proxiedHeaders,
+  });
+}
+
 const MIME_TYPES: Record<string, string> = {
   ".html": "text/html; charset=utf-8",
   ".js": "application/javascript; charset=utf-8",
@@ -139,7 +190,7 @@ async function computeStatusFromDb(): Promise<StatusResult> {
   const telemetry = querySessionTelemetry(db);
   const skillRecords = querySkillUsageRecords(db);
   const queryRecords = queryQueryLog(db);
-  const auditEntries = queryEvolutionAudit(db);
+  const auditEntries = queryEvolutionAudit(db) as EvolutionAuditEntry[];
   const doctorResult = await doctor();
   return computeStatus(telemetry, skillRecords, queryRecords, auditEntries, doctorResult);
 }
@@ -172,6 +223,7 @@ export async function startDashboardServer(
   const hostname = options?.host ?? "localhost";
   const openBrowser = options?.openBrowser ?? true;
   const runtimeMode = options?.runtimeMode ?? (import.meta.main ? "dev-server" : "test");
+  const spaProxyUrl = normalizeSpaProxyUrl(options?.spaProxyUrl ?? process.env.SPA_PROXY_URL);
   const getStatusResult = options?.statusLoader ?? computeStatusFromDb;
   const getEvidenceEntries = options?.evidenceLoader ?? readEvidenceTrail;
   const getOverviewResponse = options?.overviewLoader;
@@ -182,7 +234,14 @@ export async function startDashboardServer(
   const requestedSpaDir = options?.spaDir ?? findSpaDir();
   const spaDir =
     requestedSpaDir && existsSync(join(requestedSpaDir, "index.html")) ? requestedSpaDir : null;
-  if (spaDir) {
+  const spaMode: NonNullable<HealthResponse["spa_mode"]> = spaProxyUrl
+    ? "proxy"
+    : spaDir
+      ? "dist"
+      : "missing";
+  if (spaProxyUrl) {
+    console.log(`SPA proxy enabled at ${spaProxyUrl.toString()}`);
+  } else if (spaDir) {
     console.log(`SPA found at ${spaDir}, serving as default dashboard`);
   } else {
     if (options?.spaDir) {
@@ -247,6 +306,7 @@ export async function startDashboardServer(
 
   let fsDebounceTimer: ReturnType<typeof setTimeout> | null = null;
   const FS_DEBOUNCE_MS = 500;
+  const proxiedSpaSockets = new Map<unknown, WebSocket>();
 
   function onWALChange(): void {
     if (fsDebounceTimer) return;
@@ -298,10 +358,48 @@ export async function startDashboardServer(
   }
 
   // -- HTTP request handler ---------------------------------------------------
-  const server = Bun.serve({
+  const server = Bun.serve<DashboardSocketData>({
     port,
     hostname,
     idleTimeout: 255,
+    websocket: {
+      open(ws) {
+        const upstreamUrl = ws.data?.upstreamUrl;
+        if (!upstreamUrl) {
+          ws.close(1011, "Missing upstream websocket target");
+          return;
+        }
+        const upstreamSocket = new WebSocket(upstreamUrl);
+        proxiedSpaSockets.set(ws, upstreamSocket);
+        upstreamSocket.onmessage = (event) => {
+          ws.send(event.data);
+        };
+        upstreamSocket.onclose = (event) => {
+          proxiedSpaSockets.delete(ws);
+          try {
+            ws.close(event.code || 1000, event.reason);
+          } catch {
+            ws.close();
+          }
+        };
+        upstreamSocket.onerror = () => {
+          proxiedSpaSockets.delete(ws);
+          ws.close(1011, "Upstream websocket error");
+        };
+      },
+      message(ws, message) {
+        const upstreamSocket = proxiedSpaSockets.get(ws);
+        if (!upstreamSocket || upstreamSocket.readyState !== WebSocket.OPEN) {
+          return;
+        }
+        upstreamSocket.send(message);
+      },
+      close(ws) {
+        const upstreamSocket = proxiedSpaSockets.get(ws);
+        proxiedSpaSockets.delete(ws);
+        upstreamSocket?.close();
+      },
+    },
     async fetch(req) {
       const url = new URL(req.url);
 
@@ -315,8 +413,12 @@ export async function startDashboardServer(
         const healthResponse: HealthResponse = {
           ok: true,
           service: "selftune-dashboard",
-          version: selftuneVersion,
-          spa: Boolean(spaDir),
+          version: getSelftuneVersion(),
+          pid: process.pid,
+          spa: Boolean(spaDir || spaProxyUrl),
+          spa_mode: spaMode,
+          spa_build_id: getSpaBuildId(),
+          spa_proxy_url: spaProxyUrl?.toString() ?? null,
           v2_data_available: Boolean(getOverviewResponse || db),
           workspace_root: WORKSPACE_ROOT,
           git_sha: getGitSha(),
@@ -331,6 +433,26 @@ export async function startDashboardServer(
         return Response.json(healthResponse, { headers: corsHeaders() });
       }
 
+      if (
+        spaProxyUrl &&
+        req.headers.get("upgrade")?.toLowerCase() === "websocket" &&
+        shouldProxySpaRequest(url.pathname)
+      ) {
+        const upstreamUrl = new URL(`${url.pathname}${url.search}`, spaProxyUrl);
+        upstreamUrl.protocol = spaProxyUrl.protocol === "https:" ? "wss:" : "ws:";
+        if (
+          server.upgrade(req, {
+            data: { upstreamUrl: upstreamUrl.toString() },
+          })
+        ) {
+          return undefined;
+        }
+        return new Response("WebSocket upgrade failed", {
+          status: 502,
+          headers: corsHeaders(),
+        });
+      }
+
       // ---- GET /api/v2/events ---- SSE stream for live updates
       if (url.pathname === "/api/v2/events" && req.method === "GET") {
         const stream = new ReadableStream({
@@ -357,6 +479,22 @@ export async function startDashboardServer(
         return withCors(await handleDoctor());
       }
 
+      // ---- SPA static assets ----
+      if (spaProxyUrl && req.method === "GET" && shouldProxySpaRequest(url.pathname)) {
+        try {
+          return await proxySpaRequest(req, spaProxyUrl, url);
+        } catch (error) {
+          const message = error instanceof Error ? error.message : String(error);
+          return new Response(
+            `Dashboard SPA proxy unavailable at ${spaProxyUrl.toString()}: ${message}`,
+            {
+              status: 502,
+              headers: { "Content-Type": "text/plain; charset=utf-8", ...corsHeaders() },
+            },
+          );
+        }
+      }
+
       // ---- SPA static assets ----
       if (spaDir && req.method === "GET" && url.pathname.startsWith("/assets/")) {
         const filePath = resolve(spaDir, `.${url.pathname}`);
@@ -470,7 +608,7 @@ export async function startDashboardServer(
           );
         }
         refreshV2Data();
-        return withCors(handleOverview(db, selftuneVersion, url.searchParams));
+        return withCors(handleOverview(db, getSelftuneVersion(), url.searchParams));
       }
 
       // ---- GET /api/v2/orchestrate-runs ----
@@ -544,7 +682,7 @@ export async function startDashboardServer(
     },
   });
 
-  boundPort = server.port;
+  boundPort = server.port ?? port;
 
   if (openBrowser) {
     const url = `http://${hostname}:${boundPort}`;
@@ -575,6 +713,14 @@ export async function startDashboardServer(
       }
     }
     sseClients.clear();
+    for (const upstreamSocket of proxiedSpaSockets.values()) {
+      try {
+        upstreamSocket.close();
+      } catch {
+        /* already closed */
+      }
+    }
+    proxiedSpaSockets.clear();
     if (fsDebounceTimer) clearTimeout(fsDebounceTimer);
     closeSingleton();
     server.stop();
@@ -602,5 +748,10 @@ if (import.meta.main) {
     runtimeModeArg === "standalone" || runtimeModeArg === "dev-server" || runtimeModeArg === "test"
       ? runtimeModeArg
       : "dev-server";
-  startDashboardServer({ port, openBrowser: false, runtimeMode });
+  startDashboardServer({
+    port,
+    openBrowser: false,
+    runtimeMode,
+    spaProxyUrl: process.env.SPA_PROXY_URL,
+  });
 }

package/cli/selftune/dashboard.ts

@@ -4,11 +4,354 @@
  * Usage:
  *   selftune dashboard              — Start server on port 3141 and open browser
  *   selftune dashboard --port 8080  — Start on custom port
+ *   selftune dashboard --restart    — Restart an existing dashboard on the target port
  *   selftune dashboard --serve      — Deprecated alias for the default behavior
  */
 
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import type { HealthResponse } from "./dashboard-contract.js";
 import { CLIError } from "./utils/cli-error.js";
 
+const DEFAULT_PORT = 3141;
+const VERSION_PKG_PATH = join(import.meta.dir, "..", "..", "package.json");
+const HEALTHCHECK_TIMEOUT_MS = 1000;
+const RESTART_WAIT_TIMEOUT_MS = 5000;
+const RESTART_POLL_INTERVAL_MS = 250;
+
+type DashboardServerHandle = Awaited<
+  ReturnType<typeof import("./dashboard-server.js").startDashboardServer>
+>;
+type DashboardStartOptions = Parameters<
+  typeof import("./dashboard-server.js").startDashboardServer
+>[0];
+type DashboardKillFn = (pid: number, signal?: string | number) => boolean;
+
+type DashboardRuntimeHealth = Partial<HealthResponse> & {
+  ok: boolean;
+  service: string;
+  pid?: number;
+};
+
+interface DashboardLaunchOptions {
+  openBrowser: boolean;
+  port: number;
+  restart: boolean;
+}
+
+interface DashboardLaunchResult {
+  action: "reused" | "started";
+  installedVersion: string;
+  serverHandle?: DashboardServerHandle;
+  url: string;
+}
+
+interface DashboardLaunchDeps {
+  fetch?: typeof fetch;
+  findListeningPids?: (port: number) => number[];
+  kill?: DashboardKillFn;
+  log?: Pick<typeof console, "log" | "warn">;
+  openUrl?: (url: string) => void;
+  startDashboardServer?: (options?: DashboardStartOptions) => Promise<DashboardServerHandle>;
+  wait?: (ms: number) => Promise<void>;
+}
+
+function getInstalledSelftuneVersion(): string {
+  try {
+    return JSON.parse(readFileSync(VERSION_PKG_PATH, "utf-8")).version;
+  } catch {
+    return "unknown";
+  }
+}
+
+function buildDashboardUrl(port: number): string {
+  return `http://localhost:${port}`;
+}
+
+function openDashboardUrl(url: string): void {
+  try {
+    const platform = process.platform;
+    if (platform === "darwin") {
+      Bun.spawn(["open", url]);
+    } else if (platform === "linux") {
+      Bun.spawn(["xdg-open", url]);
+    } else if (platform === "win32") {
+      Bun.spawn(["cmd", "/c", "start", "", url]);
+    } else {
+      console.log(`Open manually: ${url}`);
+    }
+  } catch {
+    console.log(`Open manually: ${url}`);
+  }
+}
+
+function isAddressInUseError(error: unknown): boolean {
+  const message = error instanceof Error ? error.message : String(error);
+  return /EADDRINUSE|address already in use|port .* in use|already in use/i.test(message);
+}
+
+function parsePidOutput(output: string): number[] {
+  const pids = new Set<number>();
+  for (const line of output.split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    const pid = Number.parseInt(trimmed, 10);
+    if (Number.isInteger(pid) && pid > 0) {
+      pids.add(pid);
+    }
+  }
+  return [...pids];
+}
+
+export function parseWindowsNetstatListeningPids(output: string, port: number): number[] {
+  const pids = new Set<number>();
+  const portSuffix = `:${port}`;
+
+  for (const line of output.split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (!trimmed || !trimmed.includes("LISTENING")) continue;
+
+    const parts = trimmed.split(/\s+/);
+    const localAddr = parts[1] ?? "";
+    if (!localAddr.endsWith(portSuffix)) continue;
+
+    const pid = Number.parseInt(parts.at(-1) ?? "", 10);
+    if (Number.isInteger(pid) && pid > 0) {
+      pids.add(pid);
+    }
+  }
+
+  return [...pids];
+}
+
+function findListeningPids(port: number): number[] {
+  if (process.platform === "win32") {
+    const result = Bun.spawnSync(["cmd", "/c", "netstat -ano -p tcp"], {
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+    if (result.exitCode !== 0) {
+      return [];
+    }
+    return parseWindowsNetstatListeningPids(result.stdout.toString(), port);
+  }
+
+  const result = Bun.spawnSync(["lsof", "-nP", `-iTCP:${port}`, "-sTCP:LISTEN", "-t"], {
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  if (result.exitCode !== 0) {
+    return [];
+  }
+  return parsePidOutput(result.stdout.toString());
+}
+
+async function probeDashboardHealth(
+  port: number,
+  fetchImpl: typeof fetch = globalThis.fetch,
+): Promise<DashboardRuntimeHealth | null> {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), HEALTHCHECK_TIMEOUT_MS);
+  try {
+    const response = await fetchImpl(`${buildDashboardUrl(port)}/api/health`, {
+      signal: controller.signal,
+    });
+    if (!response.ok) {
+      return null;
+    }
+    const payload = (await response.json()) as Partial<DashboardRuntimeHealth>;
+    if (payload.service !== "selftune-dashboard" || payload.ok !== true) {
+      return null;
+    }
+    return payload as DashboardRuntimeHealth;
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+async function waitForDashboardShutdown(port: number, deps: DashboardLaunchDeps): Promise<void> {
+  const wait =
+    deps.wait ?? ((ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms)));
+  const fetchImpl = deps.fetch ?? globalThis.fetch;
+  const deadline = Date.now() + RESTART_WAIT_TIMEOUT_MS;
+
+  while (Date.now() < deadline) {
+    const health = await probeDashboardHealth(port, fetchImpl);
+    if (!health) {
+      return;
+    }
+    await wait(RESTART_POLL_INTERVAL_MS);
+  }
+
+  throw new CLIError(
+    `Timed out waiting for the existing dashboard on port ${port} to stop.`,
+    "OPERATION_FAILED",
+    "Retry `selftune dashboard --restart` or stop the existing dashboard process manually.",
+  );
+}
+
+async function stopExistingDashboard(
+  port: number,
+  health: DashboardRuntimeHealth,
+  deps: DashboardLaunchDeps,
+): Promise<void> {
+  const listeningPids = deps.findListeningPids?.(port) ?? findListeningPids(port);
+  const pids = new Set<number>();
+
+  if (typeof health.pid === "number" && health.pid > 0) {
+    pids.add(health.pid);
+  }
+
+  for (const pid of listeningPids) {
+    if (pid > 0) {
+      pids.add(pid);
+    }
+  }
+
+  pids.delete(process.pid);
+
+  if (pids.size === 0) {
+    throw new CLIError(
+      `Found a running dashboard on port ${port}, but could not determine its process ID.`,
+      "OPERATION_FAILED",
+      `Stop the dashboard on port ${port} manually, then rerun \`selftune dashboard --port ${port}\`.`,
+    );
+  }
+
+  const kill = deps.kill ?? process.kill.bind(process);
+  for (const pid of pids) {
+    try {
+      kill(pid, "SIGTERM");
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      if (!/ESRCH|no such process/i.test(message)) {
+        throw new CLIError(
+          `Failed to stop dashboard process ${pid}: ${message}`,
+          "OPERATION_FAILED",
+          `Stop the process on port ${port} manually, then rerun \`selftune dashboard --port ${port}\`.`,
+        );
+      }
+    }
+  }
+
+  await waitForDashboardShutdown(port, deps);
+}
+
+export function parseDashboardOptions(
+  args: string[] = process.argv.slice(2),
+): DashboardLaunchOptions {
+  const portIdx = args.indexOf("--port");
+  let port = DEFAULT_PORT;
+
+  if (portIdx !== -1) {
+    const parsed = Number.parseInt(args[portIdx + 1], 10);
+    if (!Number.isInteger(parsed) || parsed < 1 || parsed > 65535) {
+      throw new CLIError(
+        `Invalid port "${args[portIdx + 1]}": must be an integer between 1 and 65535.`,
+        "INVALID_FLAG",
+        "Provide a port number between 1 and 65535 (e.g., --port 3141).",
+      );
+    }
+    port = parsed;
+  }
+
+  return {
+    openBrowser: !args.includes("--no-open"),
+    port,
+    restart: args.includes("--restart"),
+  };
+}
+
+export async function launchDashboard(
+  args: string[] = process.argv.slice(2),
+  deps: DashboardLaunchDeps = {},
+): Promise<DashboardLaunchResult> {
+  const options = parseDashboardOptions(args);
+  const log = deps.log ?? console;
+  const openUrl = deps.openUrl ?? openDashboardUrl;
+  const fetchImpl = deps.fetch ?? globalThis.fetch;
+  const installedVersion = getInstalledSelftuneVersion();
+  const url = buildDashboardUrl(options.port);
+
+  const runningDashboard = await probeDashboardHealth(options.port, fetchImpl);
+  const versionMismatch =
+    runningDashboard?.process_mode === "standalone" &&
+    runningDashboard.version !== undefined &&
+    runningDashboard.version !== "unknown" &&
+    installedVersion !== "unknown" &&
+    runningDashboard.version !== installedVersion;
+
+  if (runningDashboard) {
+    if (options.restart || versionMismatch) {
+      if (versionMismatch) {
+        log.log(
+          `Installed selftune ${installedVersion} differs from running dashboard ${runningDashboard.version}. Restarting ${url} to pick up the update.`,
+        );
+      } else {
+        log.log(`Restarting existing selftune dashboard at ${url}.`);
+      }
+      await stopExistingDashboard(options.port, runningDashboard, deps);
+    } else {
+      if (
+        runningDashboard.process_mode !== "standalone" &&
+        runningDashboard.version !== installedVersion &&
+        installedVersion !== "unknown"
+      ) {
+        log.warn(
+          `Dashboard already running at ${url} from ${runningDashboard.process_mode} mode (version ${runningDashboard.version}). Reusing it without restart.`,
+        );
+      } else {
+        log.log(`Reusing existing selftune dashboard at ${url}.`);
+      }
+      if (options.openBrowser) {
+        openUrl(url);
+      }
+      return { action: "reused", installedVersion, url };
+    }
+  }
+
+  const startDashboardServer =
+    deps.startDashboardServer ?? (await import("./dashboard-server.js")).startDashboardServer;
+
+  try {
+    const serverHandle = await startDashboardServer({
+      port: options.port,
+      openBrowser: options.openBrowser,
+      runtimeMode: "standalone",
+    });
+    return {
+      action: "started",
+      installedVersion,
+      serverHandle,
+      url: buildDashboardUrl(serverHandle.port),
+    };
+  } catch (error) {
+    const liveDashboard = await probeDashboardHealth(options.port, fetchImpl);
+    if (liveDashboard && !options.restart) {
+      log.log(`Reusing existing selftune dashboard at ${url}.`);
+      if (options.openBrowser) {
+        openUrl(url);
+      }
+      return { action: "reused", installedVersion, url };
+    }
+
+    if (isAddressInUseError(error)) {
+      throw new CLIError(
+        `Port ${options.port} is already in use.`,
+        "OPERATION_FAILED",
+        liveDashboard
+          ? `Run \`selftune dashboard --port ${options.port} --restart\` to replace the existing dashboard.`
+          : `Use \`selftune dashboard --port <port>\` or stop the process currently listening on ${options.port}.`,
+      );
+    }
+
+    throw error;
+  }
+}
+
 export async function cliMain(): Promise<void> {
   const args = process.argv.slice(2);
 
@@ -18,6 +361,7 @@ export async function cliMain(): Promise<void> {
 Usage:
   selftune dashboard                      Start dashboard server (port 3141)
   selftune dashboard --port 8080          Start on custom port
+  selftune dashboard --restart            Restart existing dashboard on the target port
   selftune dashboard --serve              Deprecated alias for default behavior
   selftune dashboard --no-open            Start server without opening browser`);
     process.exit(0);
@@ -31,27 +375,16 @@ Usage:
     );
   }
 
-  const portIdx = args.indexOf("--port");
-  let port: number | undefined;
-  if (portIdx !== -1) {
-    const parsed = Number.parseInt(args[portIdx + 1], 10);
-    if (!Number.isInteger(parsed) || parsed < 1 || parsed > 65535) {
-      throw new CLIError(
-        `Invalid port "${args[portIdx + 1]}": must be an integer between 1 and 65535.`,
-        "INVALID_FLAG",
-        "Provide a port number between 1 and 65535 (e.g., --port 3141).",
-      );
-    }
-    port = parsed;
-  }
-
   if (args.includes("--serve")) {
     console.warn("`selftune dashboard --serve` is deprecated; use `selftune dashboard` instead.");
   }
 
-  const openBrowser = !args.includes("--no-open");
-  const { startDashboardServer } = await import("./dashboard-server.js");
-  const { stop } = await startDashboardServer({ port, openBrowser, runtimeMode: "standalone" });
+  const launch = await launchDashboard(args);
+  if (launch.action === "reused" || !launch.serverHandle) {
+    return;
+  }
+
+  const { stop } = launch.serverHandle;
   await new Promise<void>((resolve) => {
     let closed = false;
     const keepAlive = setInterval(() => {}, 1 << 30);