@moondeck/station 0.0.0-stage → 1.0.0

package/src/ui/server.ts

@@ -0,0 +1,852 @@
+/**
+ * Local host UI HTTP server (ADR-028, docs/host-ui.md).
+ *
+ * Bound to 127.0.0.1 ONLY — never 0.0.0.0, never the tailnet. No auth (the
+ * localhost binding is the perimeter — see ADR-028 security stance), no CORS,
+ * read-only. Serves the static UI from `host-agent/ui/` and a small JSON API
+ * under `/api/*`. Every JSON body is parsed through its zod schema before send
+ * so the API can never emit an off-contract shape.
+ */
+
+import { existsSync } from "node:fs";
+import { readFile, writeFile } from "node:fs/promises";
+import {
+  createServer,
+  type IncomingMessage,
+  type Server,
+  type ServerResponse,
+} from "node:http";
+import type { AddressInfo } from "node:net";
+import { hostname } from "node:os";
+import { join } from "node:path";
+
+import { desc, isNull } from "drizzle-orm";
+import type { ZodType } from "zod";
+
+import { agentMode } from "../../lib/agents/mode";
+import { schema, type Db } from "../../lib/db";
+import { whileOnOwnCredentials } from "../../lib/cloud-credential-host";
+import { getOrchestrator } from "../../lib/orchestrator";
+import { parsePreviewPortRuntimes } from "../../lib/preview-ports";
+import { getCloudState } from "../../lib/cloud-state";
+import { dockerCli } from "../../lib/docker-exec";
+import { STATION } from "../station-identity";
+import type { ContainerRuntimeState } from "../../lib/container-runtime";
+import {
+  connectEngine,
+  disconnectEngine,
+  engineCliStatuses,
+  installEngineCli,
+  engineCatalog,
+  engineStatuses,
+  isEngineKind,
+  type EngineSeams,
+} from "../../lib/engines";
+import {
+  addEngineAccount,
+  listEngineAccounts,
+  removeEngineAccount,
+} from "../../lib/engine-accounts";
+import { ensureStandardImage } from "../../lib/standard-image";
+import {
+  CloudResponse,
+  ContainerRuntimeResponse,
+  EngineOpResponse,
+  EnginesResponse,
+  EventsResponse,
+  StatusResponse,
+  TasksResponse,
+  UsersResponse,
+  type TaskRow,
+} from "./types";
+
+const HOST = "127.0.0.1";
+const MAX_PORT_ATTEMPTS = 10;
+export const RUNTIME_RECHECK_CONTROL_HEADER = "runtime-recheck-v1";
+
+export interface UiServerOptions {
+  /** Host runtime DB (read-only here). */
+  db: Db;
+  /** Static asset directory (`host-agent/ui`). */
+  uiDir: string;
+  /** File to persist the chosen port to (`$UAI_DATA_DIR/host.port`). */
+  portFilePath: string;
+  /**
+   * ADR-136 sign-in box: answer only the read-only status trio
+   * (`/api/status`, `/api/cloud`, `/api/tasks`) so `uai-host status` — and
+   * the managed installer's post-start check, which parses it — can see the
+   * box come up and connect. Every write and every other read (engines,
+   * users, events, the static UI) is 404: the box holds no credential at
+   * rest and runs no tasks, and nobody sits at it.
+   */
+  monitorOnly?: boolean;
+  /** First port to try (5876 or UAI_HOST_UI_PORT). 0 lets the OS pick (tests). */
+  startPort: number;
+  // Facts for /api/status:
+  version: string;
+  cloudUrl: string;
+  hostId: string;
+  logPath: string;
+  /** Best-effort container memory by compose project; null on failure. */
+  taskMemory?: (composeProject: string) => Promise<number | null>;
+  /**
+   * Re-advertise host capabilities to the cloud (ADR-021). Wired from main.ts
+   * (`sendCapabilities`) so an engine connect/disconnect updates the cloud's
+   * task picker promptly. Optional (tests omit it).
+   */
+  readvertise?: () => void;
+  /**
+   * Stop a task's containers (resumable) — wired from main.ts to the
+   * orchestrator. The host operator's "reclaim my machine" control (ADR-028).
+   * Optional (tests omit it).
+   */
+  stopTask?: (taskId: string) => Promise<{ ok: boolean; error?: string }>;
+  /**
+   * Engine probe seams for /api/engines. Production omits this and gets the
+   * real filesystem + login-shell probes; tests pin `loginShellPath` so the
+   * endpoint never spawns a login shell (which is bounded, but real, I/O).
+   */
+  engineSeams?: Partial<EngineSeams>;
+  /** ADR-101 local control/read surface. Optional for embedding/tests. */
+  runtimeState?: () => ContainerRuntimeState;
+  recheckRuntime?: () => Promise<ContainerRuntimeState>;
+  /** False while the selected backend is unavailable or still recovering.
+   * Credential edits remain usable, but must not kick Docker maintenance. */
+  containersOperational?: () => boolean;
+}
+
+export interface UiServerHandle {
+  server: Server;
+  port: number;
+  close: () => Promise<void>;
+}
+
+/** The GET routes a `monitorOnly` server still answers (see UiServerOptions). */
+const MONITOR_ONLY_ROUTES: ReadonlySet<string> = new Set([
+  "/api/status",
+  "/api/cloud",
+  "/api/tasks",
+]);
+
+/** Start the local UI server, binding to 127.0.0.1 with port fallback. */
+export async function startUiServer(
+  opts: UiServerOptions,
+): Promise<UiServerHandle> {
+  const memory = opts.taskMemory ? taskMemorySampler(opts.taskMemory) : null;
+  const server = createServer((req, res) => {
+    void handle(req, res, opts, memory);
+  });
+  const port = await listenWithFallback(server, opts.startPort);
+  await writeFile(opts.portFilePath, `${port}\n`, "utf8");
+  return {
+    server,
+    port,
+    close: () =>
+      new Promise<void>((resolve) => server.close(() => resolve())),
+  };
+}
+
+async function listenWithFallback(
+  server: Server,
+  startPort: number,
+): Promise<number> {
+  let lastErr: NodeJS.ErrnoException | null = null;
+  for (let i = 0; i < MAX_PORT_ATTEMPTS; i += 1) {
+    const port = startPort === 0 ? 0 : startPort + i;
+    try {
+      await new Promise<void>((resolve, reject) => {
+        const onError = (err: NodeJS.ErrnoException): void => {
+          server.removeListener("listening", onListening);
+          reject(err);
+        };
+        const onListening = (): void => {
+          server.removeListener("error", onError);
+          resolve();
+        };
+        server.once("error", onError);
+        server.once("listening", onListening);
+        // 127.0.0.1 ONLY. Binding to 0.0.0.0 here would expose the UI off-box.
+        server.listen(port, HOST);
+      });
+      return (server.address() as AddressInfo).port;
+    } catch (err) {
+      lastErr = err as NodeJS.ErrnoException;
+      if (lastErr.code === "EADDRINUSE" && startPort !== 0) continue;
+      throw lastErr;
+    }
+  }
+  throw new Error(
+    `no free UI port in [${startPort}, ${startPort + MAX_PORT_ATTEMPTS - 1}]` +
+      (lastErr ? `: ${lastErr.message}` : ""),
+  );
+}
+
+/** The local UI's writes of an engine credential (a sign-in, a key, an
+ *  account): refused once the runner is off its own credentials. */
+const ENGINE_CREDENTIAL_ROUTES: ReadonlySet<string> = new Set([
+  "/api/engines/connect",
+  "/api/engines/disconnect",
+  "/api/engines/accounts/connect",
+  "/api/engines/accounts/add",
+  "/api/engines/accounts/remove",
+]);
+
+async function handleEngineCredentialWrite(
+  path: string,
+  req: IncomingMessage,
+  res: ServerResponse,
+  opts: UiServerOptions,
+): Promise<void> {
+  switch (path) {
+    case "/api/engines/connect":
+      return handleEngineConnect(req, res, opts);
+    case "/api/engines/disconnect":
+      return handleEngineDisconnect(req, res, opts);
+    case "/api/engines/accounts/connect":
+      return handleEngineAccountConnect(req, res, opts);
+    case "/api/engines/accounts/add":
+      return handleEngineAccountAdd(req, res, opts);
+    case "/api/engines/accounts/remove":
+      return handleEngineAccountRemove(req, res, opts);
+    default:
+      return sendError(res, 404, `no such endpoint: ${path}`);
+  }
+}
+
+async function handle(
+  req: IncomingMessage,
+  res: ServerResponse,
+  opts: UiServerOptions,
+  memory: TaskMemorySampler | null,
+): Promise<void> {
+  const path = (req.url ?? "/").split("?")[0] ?? "/";
+  const method = req.method ?? "GET";
+  try {
+    if (opts.monitorOnly && !MONITOR_ONLY_ROUTES.has(path)) {
+      return sendError(res, 404, `no such endpoint: ${path}`);
+    }
+    // POST — engine connect/disconnect (the only writes; localhost-bound, so
+    // the loopback binding is the perimeter, ADR-028).
+    if (method === "POST") {
+      // ADR-154 §13: an engine credential is written here only while the
+      // runner is on its own credentials, as work on them that leaving them
+      // waits for; off them it keeps none, and Connections in Uai Cloud
+      // holds them.
+      if (ENGINE_CREDENTIAL_ROUTES.has(path)) {
+        const write = whileOnOwnCredentials(() => handleEngineCredentialWrite(path, req, res, opts));
+        if (write === null) {
+          return sendError(
+            res,
+            409,
+            "this station reads its credentials from Moondeck Cloud; manage them in Connections",
+          );
+        }
+        return await write;
+      }
+      switch (path) {
+        case "/api/engines/install":
+          return await handleEngineInstall(req, res);
+        case "/api/tasks/stop":
+          return await handleTaskStop(req, res, opts);
+        case "/api/runtime/recheck": {
+          // Loopback is not a browser CSRF boundary. Requiring a non-simple
+          // header is deliberate even though its value is not a secret:
+          // hostile pages cannot attach it without a CORS preflight, and this
+          // server grants no CORS permission. The local CLI is the caller.
+          if (
+            req.headers["x-uai-local-control"] !==
+            RUNTIME_RECHECK_CONTROL_HEADER
+          ) {
+            return sendError(res, 403, "local control header required");
+          }
+          if (!opts.recheckRuntime) {
+            return sendError(res, 501, "runtime recheck is unavailable");
+          }
+          return sendJson(
+            res,
+            ContainerRuntimeResponse,
+            await opts.recheckRuntime(),
+          );
+        }
+      }
+      return sendError(res, 404, `no such endpoint: ${path}`);
+    }
+    if (method !== "GET") {
+      return sendError(res, 405, "method not allowed");
+    }
+    switch (path) {
+      case "/api/status":
+        return sendJson(res, StatusResponse, {
+          pid: process.pid,
+          uptime: process.uptime(),
+          version: opts.version,
+          logPath: opts.logPath,
+          cloudUrl: opts.cloudUrl,
+          hostName: hostname(),
+          hostId: opts.hostId,
+          agentMode: agentMode(),
+          containerRuntime: opts.runtimeState?.(),
+          product: STATION.packageName,
+        });
+      case "/api/cloud":
+        return sendJson(res, CloudResponse, getCloudState());
+      case "/api/tasks":
+        return sendJson(res, TasksResponse, await tasksBody(opts, memory));
+      case "/api/events":
+        return sendJson(res, EventsResponse, eventsBody(opts));
+      case "/api/users":
+        return sendJson(res, UsersResponse, usersBody(opts));
+      case "/api/engines":
+        return sendJson(res, EnginesResponse, await enginesBody(opts.engineSeams));
+    }
+    if (path.startsWith("/api/")) {
+      return sendError(res, 404, `no such endpoint: ${path}`);
+    }
+    return await serveStatic(res, opts.uiDir, path);
+  } catch (err) {
+    return sendError(res, 500, err instanceof Error ? err.message : "internal error");
+  }
+}
+
+// --- engines ----------------------------------------------------------------
+
+/** Engine kinds that participate in the multi-account model (ADR-076). */
+const ACCOUNT_KINDS = ["claude", "codex", "opencode"] as const;
+
+async function enginesBody(
+  seams: Partial<EngineSeams> = {},
+): Promise<EnginesResponse> {
+  const accounts: Record<string, ReturnType<typeof listEngineAccounts>> = {};
+  for (const kind of ACCOUNT_KINDS) {
+    accounts[kind] = listEngineAccounts(kind);
+  }
+  return {
+    catalog: engineCatalog(),
+    statuses: engineStatuses(seams),
+    cli: await engineCliStatuses(seams),
+    accounts,
+  };
+}
+
+/**
+ * POST /api/engines/install `{kind}` — run the engine's pinned installer,
+ * streaming NDJSON like connect: `{"line":…}` frames, then `{done,ok,message}`.
+ * No re-advertise or image rebuild here: installing a CLI connects nothing;
+ * that happens on the connect that follows.
+ */
+async function handleEngineInstall(
+  req: IncomingMessage,
+  res: ServerResponse,
+): Promise<void> {
+  const body = await readJsonBody(req);
+  const kind = body?.kind;
+  if (!isEngineKind(kind)) {
+    return sendError(res, 400, "unknown or missing engine kind");
+  }
+  res.writeHead(200, {
+    "content-type": "application/x-ndjson; charset=utf-8",
+    "cache-control": "no-store",
+  });
+  const emit = (obj: unknown): void => {
+    res.write(`${JSON.stringify(obj)}\n`);
+  };
+  let result: { ok: boolean; message: string };
+  try {
+    result = await installEngineCli(kind, (line) => emit({ line }));
+  } catch (err) {
+    result = {
+      ok: false,
+      message: err instanceof Error ? err.message : "install failed",
+    };
+  }
+  emit({ done: true, ok: result.ok, message: result.message });
+  res.end();
+}
+
+/**
+ * POST /api/engines/connect `{kind, apiKey?, pastedToken?}`.
+ *
+ * Streams the connect as newline-delimited JSON (`application/x-ndjson`): each
+ * live CLI log line is `{"line":"…"}`, and a final `{"done":true,"ok":…,
+ * "message":"…"}` carries the result. api-key/paste connects emit no log lines
+ * and just the final frame. On success we re-advertise and kick a (best-effort)
+ * standard-image rebuild so a newly-configured engine's CLI gets installed.
+ */
+async function handleEngineConnect(
+  req: IncomingMessage,
+  res: ServerResponse,
+  opts: UiServerOptions,
+): Promise<void> {
+  const body = await readJsonBody(req);
+  const kind = body?.kind;
+  if (!isEngineKind(kind)) {
+    return sendError(res, 400, "unknown or missing engine kind");
+  }
+  const apiKey = typeof body?.apiKey === "string" ? body.apiKey : undefined;
+  const pastedToken =
+    typeof body?.pastedToken === "string" ? body.pastedToken : undefined;
+
+  res.writeHead(200, {
+    "content-type": "application/x-ndjson; charset=utf-8",
+    "cache-control": "no-store",
+  });
+  const emit = (obj: unknown): void => {
+    res.write(`${JSON.stringify(obj)}\n`);
+  };
+
+  let result: { ok: boolean; message: string };
+  try {
+    result = await connectEngine(
+      kind,
+      { apiKey, pastedToken },
+      (line) => emit({ line }),
+    );
+  } catch (err) {
+    result = {
+      ok: false,
+      message: err instanceof Error ? err.message : "connect failed",
+    };
+  }
+  if (result.ok) {
+    // Re-advertise so the cloud picker offers the engine; rebuild the image so
+    // an optional engine's CLI (kimi/grok/cursor) is installed. Best-effort.
+    opts.readvertise?.();
+    if (opts.containersOperational?.() !== false) {
+      void ensureStandardImage();
+      // A re-login only reaches a RUNNING task once its agents re-spawn — the
+      // credential is injected at spawn (Claude's token via `docker exec -e`).
+      // Refresh running agents of this kind so a reconnect self-heals tasks
+      // stuck on a revoked/expired token, instead of needing Stop/Resume.
+      void getOrchestrator()
+        .refreshEngineAccountAgents(kind)
+        .catch(() => {});
+    }
+  }
+  emit({ done: true, ok: result.ok, message: result.message });
+  res.end();
+}
+
+/** POST /api/engines/disconnect `{kind}` → forget the credential + re-advertise. */
+async function handleEngineDisconnect(
+  req: IncomingMessage,
+  res: ServerResponse,
+  opts: UiServerOptions,
+): Promise<void> {
+  const body = await readJsonBody(req);
+  const kind = body?.kind;
+  if (!isEngineKind(kind)) {
+    return sendError(res, 400, "unknown or missing engine kind");
+  }
+  disconnectEngine(kind);
+  opts.readvertise?.();
+  return sendJson(res, EngineOpResponse, { ok: true });
+}
+
+/**
+ * POST /api/engines/accounts/add `{kind, label, apiKey?|token?}` → register an
+ * EXTRA account (ADR-076) by pasting a token / API key, then re-advertise (the
+ * kind may not have been available before) + rebuild the image if needed.
+ */
+async function handleEngineAccountAdd(
+  req: IncomingMessage,
+  res: ServerResponse,
+  opts: UiServerOptions,
+): Promise<void> {
+  const body = await readJsonBody(req);
+  const kind = body?.kind;
+  if (!isEngineKind(kind)) {
+    return sendError(res, 400, "unknown or missing engine kind");
+  }
+  const label = typeof body?.label === "string" ? body.label : "";
+  const apiKey = typeof body?.apiKey === "string" ? body.apiKey : undefined;
+  const token = typeof body?.token === "string" ? body.token : undefined;
+  const result = addEngineAccount(kind, label, { apiKey, token });
+  if (result.ok) {
+    opts.readvertise?.();
+    if (opts.containersOperational?.() !== false) {
+      void ensureStandardImage();
+    }
+  }
+  return sendJson(res, EngineOpResponse, {
+    ok: result.ok,
+    message: result.message,
+  });
+}
+
+/**
+ * POST /api/engines/accounts/connect `{kind, label}` → run the engine's
+ * token-command sign-in (streamed NDJSON exactly like /api/engines/connect) and
+ * store the captured token as an EXTRA account (ADR-076) rather than the default
+ * credential. Only meaningful for token-command kinds (Claude); the browser
+ * OAuth authorizes whichever account you sign in with, so run it signed-out /
+ * incognito for the browser to prompt for the second account.
+ */
+async function handleEngineAccountConnect(
+  req: IncomingMessage,
+  res: ServerResponse,
+  opts: UiServerOptions,
+): Promise<void> {
+  const body = await readJsonBody(req);
+  const kind = body?.kind;
+  if (!isEngineKind(kind)) {
+    return sendError(res, 400, "unknown or missing engine kind");
+  }
+  const label = typeof body?.label === "string" ? body.label.trim() : "";
+  if (!label) {
+    return sendError(res, 400, "give the account a label");
+  }
+
+  res.writeHead(200, {
+    "content-type": "application/x-ndjson; charset=utf-8",
+    "cache-control": "no-store",
+  });
+  const emit = (obj: unknown): void => {
+    res.write(`${JSON.stringify(obj)}\n`);
+  };
+
+  let result: { ok: boolean; message: string };
+  try {
+    result = await connectEngine(
+      kind,
+      { onToken: (token) => addEngineAccount(kind, label, { token }) },
+      (line) => emit({ line }),
+    );
+  } catch (err) {
+    result = {
+      ok: false,
+      message: err instanceof Error ? err.message : "sign-in failed",
+    };
+  }
+  if (result.ok) {
+    opts.readvertise?.();
+    if (opts.containersOperational?.() !== false) {
+      void ensureStandardImage();
+    }
+  }
+  emit({ done: true, ok: result.ok, message: result.message });
+  res.end();
+}
+
+/** POST /api/engines/accounts/remove `{id}` → forget an EXTRA account. */
+async function handleEngineAccountRemove(
+  req: IncomingMessage,
+  res: ServerResponse,
+  opts: UiServerOptions,
+): Promise<void> {
+  const body = await readJsonBody(req);
+  const id = body?.id;
+  if (typeof id !== "string" || id.length === 0) {
+    return sendError(res, 400, "missing account id");
+  }
+  const result = removeEngineAccount(id);
+  if (result.ok) opts.readvertise?.();
+  return sendJson(res, EngineOpResponse, {
+    ok: result.ok,
+    message: result.message,
+  });
+}
+
+/** POST /api/tasks/stop `{taskId}` → compose-stop the task (resumable). */
+async function handleTaskStop(
+  req: IncomingMessage,
+  res: ServerResponse,
+  opts: UiServerOptions,
+): Promise<void> {
+  const body = await readJsonBody(req);
+  const taskId = body?.taskId;
+  if (typeof taskId !== "string" || taskId.length === 0) {
+    return sendError(res, 400, "missing taskId");
+  }
+  if (!opts.stopTask) {
+    return sendError(res, 501, "stop not available on this host");
+  }
+  const result = await opts.stopTask(taskId);
+  return sendJson(res, EngineOpResponse, {
+    ok: result.ok,
+    message: result.error,
+  });
+}
+
+/** Read a request body and parse it as a JSON object; null on empty/invalid. */
+async function readJsonBody(
+  req: IncomingMessage,
+): Promise<Record<string, unknown> | null> {
+  const chunks: Buffer[] = [];
+  let size = 0;
+  for await (const chunk of req) {
+    const buf = chunk as Buffer;
+    size += buf.length;
+    if (size > 64 * 1024) throw new Error("request body too large");
+    chunks.push(buf);
+  }
+  if (chunks.length === 0) return null;
+  try {
+    const parsed: unknown = JSON.parse(Buffer.concat(chunks).toString("utf8"));
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed)
+      ? (parsed as Record<string, unknown>)
+      : null;
+  } catch {
+    return null;
+  }
+}
+
+// --- handlers ---------------------------------------------------------------
+
+async function tasksBody(
+  opts: UiServerOptions,
+  memory: TaskMemorySampler | null,
+): Promise<TasksResponse> {
+  const rows = opts.db
+    .select()
+    .from(schema.hostTasks)
+    .where(isNull(schema.hostTasks.endedAt))
+    .all();
+  const now = Date.now();
+  const memoryByProject = memory
+    ? await memory.read(rows.flatMap((r) => (r.composeProject ? [r.composeProject] : [])))
+    : new Map<string, number | null>();
+  const tasks: TaskRow[] = rows.map((r) => ({
+    taskId: r.taskId,
+    status: r.statusMirror,
+    ownerEmail: r.ownerEmail,
+    projectSlugs: parseSlugs(r.projectSlugs),
+    startedAt: r.startedAt,
+    ageMs: r.startedAt != null ? now - r.startedAt : null,
+    composeProject: r.composeProject,
+    codeServerPort: r.codeServerPort,
+    previewPorts: parsePreviewPortRuntimes(r.previewPorts).map((p) => ({
+      name: p.name,
+      hostPort: p.hostPort ?? null,
+    })),
+    memoryBytes: r.composeProject ? (memoryByProject.get(r.composeProject) ?? null) : null,
+  }));
+  return { tasks };
+}
+
+/** How long `/api/tasks` waits for fresh memory samples before it answers
+ *  with the last ones it has (null for a task never sampled yet). */
+export const TASK_MEMORY_WAIT_MS = 250;
+/** A sample this recent is served without asking Docker again. */
+export const TASK_MEMORY_FRESH_MS = 15_000;
+
+export interface TaskMemorySampler {
+  /** The latest memory sample of each compose project asked for. */
+  read(projects: readonly string[]): Promise<Map<string, number | null>>;
+}
+
+/**
+ * Memory for `/api/tasks` without making the response wait on Docker.
+ * `docker stats --no-stream` takes about two seconds per task once tasks
+ * run, so `/api/tasks` took ~2 s and `uai-host status`, which allowed it one,
+ * said "service unreachable" on a healthy runner (2026-10-30). Each project
+ * is sampled in the background, one sample at a time, at most once per
+ * `freshMs`; a read waits at most `waitMs` for samples under way, then
+ * answers with what it has. A project no longer asked for is forgotten.
+ */
+export function taskMemorySampler(
+  sample: (composeProject: string) => Promise<number | null>,
+  options: { now?: () => number; waitMs?: number; freshMs?: number } = {},
+): TaskMemorySampler {
+  const now = options.now ?? Date.now;
+  const waitMs = options.waitMs ?? TASK_MEMORY_WAIT_MS;
+  const freshMs = options.freshMs ?? TASK_MEMORY_FRESH_MS;
+  const entries = new Map<
+    string,
+    { value: number | null; sampledAt: number | null; sampling: Promise<void> | null }
+  >();
+  return {
+    async read(projects) {
+      const wanted = new Set(projects);
+      for (const project of entries.keys()) {
+        if (!wanted.has(project)) entries.delete(project);
+      }
+      const sampling: Promise<void>[] = [];
+      for (const project of wanted) {
+        let entry = entries.get(project);
+        if (!entry) {
+          entry = { value: null, sampledAt: null, sampling: null };
+          entries.set(project, entry);
+        }
+        if (entry.sampling === null && (entry.sampledAt === null || now() - entry.sampledAt >= freshMs)) {
+          const current = entry;
+          current.sampling = sample(project)
+            .catch(() => null)
+            .then((value) => {
+              current.value = value;
+              current.sampledAt = now();
+              current.sampling = null;
+            });
+        }
+        if (entry.sampling !== null) sampling.push(entry.sampling);
+      }
+      if (sampling.length > 0) {
+        let timer: NodeJS.Timeout | undefined;
+        await Promise.race([
+          Promise.all(sampling),
+          new Promise<void>((resolve) => {
+            timer = setTimeout(resolve, waitMs);
+            timer.unref?.();
+          }),
+        ]);
+        clearTimeout(timer);
+      }
+      return new Map([...wanted].map((project) => [project, entries.get(project)?.value ?? null]));
+    },
+  };
+}
+
+function eventsBody(opts: UiServerOptions): EventsResponse {
+  const rows = opts.db
+    .select()
+    .from(schema.hostEvents)
+    .orderBy(desc(schema.hostEvents.ts))
+    .limit(50)
+    .all();
+  return {
+    events: rows
+      .filter((r) => isKnownEventKind(r.kind))
+      .map((r) => ({
+        id: r.id,
+        taskId: r.taskId,
+        kind: r.kind as EventsResponse["events"][number]["kind"],
+        ts: r.ts,
+        detail: r.detail,
+      })),
+  };
+}
+
+function usersBody(opts: UiServerOptions): UsersResponse {
+  const rows = opts.db
+    .select()
+    .from(schema.hostTasks)
+    .where(isNull(schema.hostTasks.endedAt))
+    .all();
+  const byUser = new Map<string, { email: string | null; count: number }>();
+  for (const r of rows) {
+    if (!r.ownerUserId) continue;
+    const cur = byUser.get(r.ownerUserId) ?? { email: r.ownerEmail, count: 0 };
+    cur.count += 1;
+    if (!cur.email && r.ownerEmail) cur.email = r.ownerEmail;
+    byUser.set(r.ownerUserId, cur);
+  }
+  return {
+    users: [...byUser].map(([userId, v]) => ({
+      userId,
+      email: v.email,
+      activeTasks: v.count,
+    })),
+  };
+}
+
+// --- static -----------------------------------------------------------------
+
+const STATIC_FILES: Record<string, string> = {
+  "/": "index.html",
+  "/index.html": "index.html",
+  "/style.css": "style.css",
+  "/app.js": "app.js",
+  "/uai-wheel.svg": "uai-wheel.svg",
+  "/uai-favicon.svg": "uai-favicon.svg",
+  "/uai-logo-black.svg": "uai-logo-black.svg",
+};
+
+async function serveStatic(
+  res: ServerResponse,
+  uiDir: string,
+  path: string,
+): Promise<void> {
+  const file = STATIC_FILES[path];
+  if (!file) return sendError(res, 404, `not found: ${path}`);
+  const full = join(uiDir, file);
+  if (!existsSync(full)) return sendError(res, 404, `not found: ${path}`);
+  const body = await readFile(full);
+  res.writeHead(200, { "content-type": contentType(file) });
+  res.end(body);
+}
+
+function contentType(file: string): string {
+  if (file.endsWith(".html")) return "text/html; charset=utf-8";
+  if (file.endsWith(".css")) return "text/css; charset=utf-8";
+  if (file.endsWith(".js")) return "text/javascript; charset=utf-8";
+  if (file.endsWith(".svg")) return "image/svg+xml";
+  return "application/octet-stream";
+}
+
+// --- response helpers -------------------------------------------------------
+
+function sendJson<T>(res: ServerResponse, shape: ZodType<T>, body: T): void {
+  // Parse before send: the API can never emit an off-contract body.
+  const validated = shape.parse(body);
+  res.writeHead(200, { "content-type": "application/json; charset=utf-8" });
+  res.end(JSON.stringify(validated));
+}
+
+function sendError(res: ServerResponse, status: number, message: string): void {
+  res.writeHead(status, { "content-type": "application/json; charset=utf-8" });
+  res.end(JSON.stringify({ error: message }));
+}
+
+// --- misc -------------------------------------------------------------------
+
+function parseSlugs(raw: string): string[] {
+  try {
+    const parsed: unknown = JSON.parse(raw);
+    return Array.isArray(parsed)
+      ? parsed.filter((s): s is string => typeof s === "string")
+      : [];
+  } catch {
+    return [];
+  }
+}
+
+function isKnownEventKind(kind: string): boolean {
+  return (
+    kind === "task.created" ||
+    kind === "task.started" ||
+    kind === "task.ended" ||
+    kind === "task.ship"
+  );
+}
+
+/**
+ * Best-effort container memory for a task's compose project via `docker stats`.
+ * Returns null on any failure (docker down, container gone, parse miss).
+ */
+export async function dockerMemoryBytes(
+  composeProject: string,
+): Promise<number | null> {
+  try {
+    // Async (not spawnSync): this runs per task on every status request, on the
+    // SAME event loop as the cloud-bridge heartbeat. `docker stats --no-stream`
+    // samples for ~1-2s; doing it synchronously for N tasks blocked the loop
+    // long enough that the bridge heartbeat timed out and the cloud dropped the
+    // host into a reconnect loop.
+    const res = await dockerCli(
+      ["stats", "--no-stream", "--format", "{{.MemUsage}}", `${composeProject}-app-1`],
+      { timeoutMs: 3_000 },
+    );
+    if (res.status !== 0 || !res.stdout) return null;
+    const used = res.stdout.trim().split("/")[0]?.trim();
+    return used ? parseMemUsage(used) : null;
+  } catch {
+    return null;
+  }
+}
+
+function parseMemUsage(text: string): number | null {
+  const m = /^([\d.]+)\s*([a-zA-Z]+)$/.exec(text);
+  if (!m || !m[1] || !m[2]) return null;
+  const value = Number(m[1]);
+  const unit = m[2].toLowerCase();
+  const scale: Record<string, number> = {
+    b: 1,
+    kb: 1e3,
+    mb: 1e6,
+    gb: 1e9,
+    kib: 1024,
+    mib: 1024 ** 2,
+    gib: 1024 ** 3,
+  };
+  const factor = scale[unit];
+  return factor ? Math.round(value * factor) : null;
+}