@mycadet/cli 0.0.1 → 0.12.6-dev.202610072225.d7acd73

package/src/commands/client.ts

@@ -0,0 +1,1674 @@
+import { isManagedCloud } from "../lib/managed-cloud.js";
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import path from "node:path";
+
+import {
+  findAssistantByName,
+  formatAssistantLookupError,
+  getActiveAssistant,
+  lookupAssistantByIdentifier,
+  resolveAssistant,
+  saveAssistantEntry,
+  type AssistantEntry,
+} from "../lib/assistant-config";
+import { DAEMON_INTERNAL_ASSISTANT_ID, GATEWAY_PORT } from "../lib/constants";
+import {
+  loadGuardianToken,
+  refreshGuardianToken,
+  guardianTokenDueForRenewal,
+} from "../lib/guardian-token";
+import { normalizeRuntimeUrl, trustedRefreshUrl } from "../lib/runtime-url";
+import {
+  CLI_INTERFACE_ID,
+  WEB_INTERFACE_ID,
+  getClientRegistrationHeaders,
+} from "../lib/client-identity";
+import {
+  getLockfileData,
+  renameLockfileAssistantIfPresent,
+  upsertRendererLockfileAssistant,
+  replacePlatformAssistants,
+  isActiveAssistant,
+  isPairedLockfileEntry,
+  PAIRED_GUARDIAN_TOKEN_HOST_ONLY_ERROR,
+  runDevicesList,
+  runDevicesRevoke,
+  runHatch,
+  runRetire,
+  pairingCancel,
+  pairingPoll,
+  pairingStart,
+  unpairAssistant,
+  getGuardianAccessToken,
+  getPairedGuardianAccessToken,
+  parseGatewayUrl,
+  parsePairedGatewayUrl,
+  resolveGatewayProxyTarget,
+  resolvePairedGatewayProxyTarget,
+  readAllowedGatewayPorts,
+  readPairedGatewayTargets,
+  authorizePairedForwardHeaders,
+  isLoopbackAddr,
+  headerHostIsLoopback,
+  originIsAllowed,
+  hasSameOriginCredentialProof,
+  resolveDevCliInvocation,
+  resolveLockfilePaths,
+  resolveConfigDir,
+  type CliInvocation,
+} from "@mycadet/local-mode";
+import { parseAssistantTargetArg } from "../lib/assistant-target-args.js";
+import { parseFeatureFlagArgs, readAmbientFlagEnvVars } from "../lib/flag-args";
+import {
+  fetchOrganizationId,
+  fetchPlatformAssistants,
+  getPlatformUrl,
+  getWebUrl,
+  readPlatformToken,
+  savePlatformToken,
+  clearPlatformToken,
+} from "../lib/platform-client";
+import { tuiLog } from "../lib/tui-log";
+import { loopbackSafeFetch } from "../lib/loopback-fetch.js";
+import { relaunchDetached } from "../lib/detached-process.js";
+import { probePort } from "../lib/port-probe.js";
+import { openBrowser } from "../lib/open-browser";
+import { findWebDistDir } from "../lib/web-dist.js";
+
+const SUPPORTED_INTERFACES = ["cli", "web"] as const;
+type SupportedInterface = (typeof SUPPORTED_INTERFACES)[number];
+
+const ANSI = {
+  reset: "\x1b[0m",
+  bold: "\x1b[1m",
+  dim: "\x1b[2m",
+};
+
+const FALLBACK_RUNTIME_URL = `http://127.0.0.1:${GATEWAY_PORT}`;
+
+interface ParsedArgs {
+  runtimeUrl: string;
+  assistantId: string;
+  assistantName?: string;
+  /** "cadet" for platform-hosted assistants, undefined for local. */
+  cloud?: string;
+  /** Platform session token (X-Session-Token), set when isManagedCloud(cloud). */
+  platformToken?: string;
+  /** Guardian JWT (Authorization: Bearer), set for local assistants. */
+  bearerToken?: string;
+  /** Interface identifier sent as X-Cadet-Interface-Id on all requests. */
+  interfaceId: SupportedInterface;
+  /** CADET_FLAG_* env vars for the gateway (process.env propagation). */
+  flagEnvVars: Record<string, string>;
+  /** Parsed --flag overrides: kebab-case key -> typed value (for web injection). */
+  parsedFlagOverrides: Record<string, boolean | string>;
+  disablePlatform: boolean;
+  /** Auto-open the web interface in the default browser (--interface web only). */
+  openBrowser: boolean;
+  /** Explicit web server port (--interface web only). Binds strictly — no scan. */
+  webPort?: number;
+  /** Run the web server as a detached background process (--interface web only). */
+  background: boolean;
+}
+
+function readAssistantName(entry: AssistantEntry | null): string | undefined {
+  const rawName = entry?.name ?? entry?.assistantName;
+  return typeof rawName === "string" && rawName.trim()
+    ? rawName.trim()
+    : undefined;
+}
+
+// Exported for unit testing the arg/auth resolution without launching the TUI.
+export function parseArgs(): ParsedArgs {
+  const { envVars: cliFlagVars, remaining: argsWithoutFlags } =
+    parseFeatureFlagArgs(process.argv.slice(3));
+  const flagEnvVars = { ...readAmbientFlagEnvVars(), ...cliFlagVars };
+  const disablePlatformAmbient =
+    process.env.CADET_DISABLE_PLATFORM?.trim().toLowerCase();
+  let disablePlatform =
+    disablePlatformAmbient === "true" || disablePlatformAmbient === "1";
+  const args = argsWithoutFlags;
+
+  // Build parsedFlagOverrides from the extracted env vars:
+  // CADET_FLAG_UPPER_SNAKE -> kebab-case key with typed value.
+  const parsedFlagOverrides: Record<string, boolean | string> = {};
+  for (const [envName, rawValue] of Object.entries(flagEnvVars)) {
+    const snake = envName.replace(/^CADET_FLAG_/, "");
+    const kebab = snake.toLowerCase().replace(/_/g, "-");
+    const lower = rawValue.toLowerCase();
+    if (["true", "1", "yes", "on"].includes(lower)) {
+      parsedFlagOverrides[kebab] = true;
+    } else if (["false", "0", "no", "off"].includes(lower)) {
+      parsedFlagOverrides[kebab] = false;
+    } else {
+      parsedFlagOverrides[kebab] = rawValue;
+    }
+  }
+
+  const positionalName = parseAssistantTargetArg(args, [
+    "--url",
+    "-u",
+    "--assistant-id",
+    "-a",
+    "--interface",
+    "-i",
+    "--token",
+    "-t",
+    "--port",
+  ]);
+  // Auto-open the web interface in the browser by default; --no-open opts out.
+  let openBrowserPref = true;
+  let webPort: number | undefined;
+  let background = false;
+  const flagArgs: string[] = [];
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--help" || arg === "-h") {
+      printUsage();
+      process.exit(0);
+    } else if (arg === "--disable-platform") {
+      disablePlatform = true;
+    } else if (arg === "--no-open") {
+      openBrowserPref = false;
+    } else if (arg === "--background") {
+      background = true;
+    } else if (arg === "--port") {
+      const value = args[++i];
+      const parsed =
+        value === undefined ? Number.NaN : Number.parseInt(value, 10);
+      if (String(parsed) !== value || parsed < 1 || parsed > 65535) {
+        console.error(
+          `Invalid --port '${value ?? ""}'. Expected an integer between 1 and 65535.`,
+        );
+        process.exit(1);
+      }
+      webPort = parsed;
+    } else if (
+      (arg === "--url" ||
+        arg === "-u" ||
+        arg === "--assistant-id" ||
+        arg === "-a" ||
+        arg === "--interface" ||
+        arg === "-i" ||
+        arg === "--token" ||
+        arg === "-t") &&
+      args[i + 1]
+    ) {
+      flagArgs.push(arg, args[++i]);
+    }
+  }
+
+  let entry: AssistantEntry | null = null;
+  if (positionalName) {
+    const result = lookupAssistantByIdentifier(positionalName);
+    if (result.status !== "found") {
+      console.error(formatAssistantLookupError(positionalName, result));
+      process.exit(1);
+    }
+    entry = result.entry;
+  } else {
+    const hasExplicitUrl =
+      flagArgs.includes("--url") || flagArgs.includes("-u");
+    const active = getActiveAssistant();
+    if (active) {
+      const result = lookupAssistantByIdentifier(active);
+      if (result.status === "found") {
+        entry = result.entry;
+      }
+      if (!entry && !hasExplicitUrl) {
+        console.error(
+          `Active assistant '${active}' not found in lockfile. Set an active assistant with 'cadet use <name-or-id>'.`,
+        );
+        process.exit(1);
+      }
+    }
+    if (!entry && hasExplicitUrl) {
+      // URL provided but active assistant missing or unset — resolve for remaining defaults
+      entry = resolveAssistant();
+    } else if (!entry) {
+      console.error(
+        "No active assistant set. Set one with 'cadet use <name-or-id>' or specify one: 'cadet client <name-or-id>'.",
+      );
+      process.exit(1);
+    }
+  }
+
+  let runtimeUrl = entry?.localUrl || entry?.runtimeUrl || FALLBACK_RUNTIME_URL;
+  let assistantId = entry?.assistantId || DAEMON_INTERNAL_ASSISTANT_ID;
+  let assistantName = readAssistantName(entry);
+  const cloud = entry?.cloud;
+
+  // Ephemeral auth: a handed-over token (e.g. from `cadet pair`) used for this
+  // session only. Resolve it BEFORE the credential lookup below so an ephemeral
+  // session never reads (or writes) the local token store.
+  let bearerTokenOverride: string | undefined;
+  for (let i = 0; i < flagArgs.length; i++) {
+    if (
+      (flagArgs[i] === "--token" || flagArgs[i] === "-t") &&
+      flagArgs[i + 1]
+    ) {
+      bearerTokenOverride = flagArgs[i + 1];
+    }
+  }
+
+  // Platform-hosted assistants (cloud "cadet") use a session token; every
+  // other topology — local, docker, and "paired" (a remote assistant paired
+  // from another machine) — uses a bearer guardian JWT. Both are skipped
+  // entirely when --token supplies the credential, so no saved creds are read.
+  const platformToken = bearerTokenOverride
+    ? undefined
+    : isManagedCloud(cloud)
+      ? (readPlatformToken() ?? undefined)
+      : undefined;
+  const bearerToken = bearerTokenOverride
+    ? bearerTokenOverride
+    : isManagedCloud(cloud)
+      ? undefined
+      : (loadGuardianToken(entry?.assistantId ?? "")?.accessToken ?? undefined);
+
+  let interfaceId: SupportedInterface = CLI_INTERFACE_ID;
+
+  for (let i = 0; i < flagArgs.length; i++) {
+    const flag = flagArgs[i];
+    if ((flag === "--url" || flag === "-u") && flagArgs[i + 1]) {
+      runtimeUrl = flagArgs[++i];
+    } else if (
+      (flag === "--assistant-id" || flag === "-a") &&
+      flagArgs[i + 1]
+    ) {
+      assistantId = flagArgs[++i];
+      assistantName = undefined;
+    } else if ((flag === "--interface" || flag === "-i") && flagArgs[i + 1]) {
+      const value = flagArgs[++i];
+      if (!(SUPPORTED_INTERFACES as readonly string[]).includes(value)) {
+        console.error(
+          `Unknown interface '${value}'. Supported: ${SUPPORTED_INTERFACES.join(", ")}.`,
+        );
+        process.exit(1);
+      }
+      interfaceId = value as SupportedInterface;
+    }
+  }
+
+  if (interfaceId !== WEB_INTERFACE_ID) {
+    if (webPort !== undefined) {
+      console.error("--port requires --interface web.");
+      process.exit(1);
+    }
+    if (background) {
+      console.error("--background requires --interface web.");
+      process.exit(1);
+    }
+  }
+
+  return {
+    runtimeUrl: normalizeRuntimeUrl(runtimeUrl),
+    assistantId,
+    assistantName,
+    cloud,
+    platformToken,
+    bearerToken,
+    interfaceId,
+    flagEnvVars,
+    parsedFlagOverrides,
+    disablePlatform,
+    openBrowser: openBrowserPref,
+    webPort,
+    background,
+  };
+}
+
+function printUsage(): void {
+  console.log(`${ANSI.bold}cadet client${ANSI.reset} - Connect to a hatched assistant
+
+${ANSI.bold}USAGE:${ANSI.reset}
+    cadet client [name-or-id] [options]
+
+${ANSI.bold}ARGUMENTS:${ANSI.reset}
+    [name-or-id]               Assistant display name or ID (default: active)
+
+${ANSI.bold}OPTIONS:${ANSI.reset}
+    -u, --url <url>            Runtime URL
+    -t, --token <jwt>          Bearer token to use for this session (e.g. from
+                              'cadet pair'). Overrides the stored token and is
+                              not persisted.
+    -a, --assistant-id <id>    Assistant ID
+    -i, --interface <id>       Interface identifier: cli (default) or web
+    --no-open                  Don't auto-open the browser (--interface web)
+    --port <port>              Web server port, 1-65535 (--interface web).
+                              Errors if the port is taken. Default: 3000,
+                              scanning upward when busy.
+    --background               Run the web server as a background process
+                              (--interface web). Prints the URL, PID, and log
+                              path, then returns to the shell.
+    --flag <key=value>         Feature flag override (repeatable, kebab-case key)
+    --disable-platform         Suppress all outbound platform API calls
+    -h, --help                 Show this help message
+
+${ANSI.bold}DEFAULTS:${ANSI.reset}
+    Reads from ~/.cadet.lock.json (created by cadet hatch).
+    Override with flags above.
+
+${ANSI.bold}EXAMPLES:${ANSI.reset}
+    cadet client
+    cadet client mycadet-foo
+    # Remote assistants must be reached over https (e.g. a tunnel) — the
+    # guardian refresh token is only sent over https or a loopback address:
+    cadet client --url https://your-tunnel.example
+    cadet client mycadet-foo --url http://localhost:${GATEWAY_PORT}
+
+    # Ephemeral: connect to another machine's assistant with a paired token
+    # (no lockfile entry, nothing persisted):
+    cadet client --url https://your-tunnel.example --token <jwt>
+
+    # Web interface on a fixed port, detached from the shell:
+    cadet client --interface web --port 4000 --background
+`);
+}
+
+async function maybeHydratePlatformAssistantName(
+  assistantId: string,
+  assistantName: string | undefined,
+  cloud: string | undefined,
+  platformToken: string | undefined,
+): Promise<string | undefined> {
+  if (!isManagedCloud(cloud) || assistantName || !platformToken) {
+    return assistantName;
+  }
+
+  try {
+    const matchedAssistant = (
+      await fetchPlatformAssistants(platformToken)
+    ).find((assistant) => assistant.id === assistantId);
+    const hydratedName = matchedAssistant?.name.trim();
+    if (!hydratedName) {
+      return assistantName;
+    }
+
+    const entry = findAssistantByName(assistantId);
+    if (entry && entry.name !== hydratedName) {
+      saveAssistantEntry({
+        ...entry,
+        name: hydratedName,
+      });
+    }
+
+    return hydratedName;
+  } catch {
+    return assistantName;
+  }
+}
+
+const SPA_BASE = "/assistant/";
+
+/**
+ * Cache policy for hashed build output under `dist/assets/`: the content hash
+ * is part of the filename, so a new build emits new names and a stored copy can
+ * never be stale.
+ */
+const IMMUTABLE_CACHE_CONTROL = "public, max-age=31536000, immutable";
+
+/**
+ * Cache policy for everything whose name is stable across builds: the HTML
+ * shell and unhashed `public/` files. Storing is allowed, serving without
+ * revalidating is not, so an assistant update is never masked by a cached copy.
+ */
+const REVALIDATE_CACHE_CONTROL = "no-cache";
+
+/**
+ * Locate the clients/web source directory for running the Vite dev server.
+ * Only works from a source checkout (not npm-installed).
+ */
+function findWebSourceDir(): string | null {
+  let dir = import.meta.dir;
+  for (let depth = 0; depth < 8; depth++) {
+    const candidate = path.join(dir, "clients", "web", "vite.config.ts");
+    if (existsSync(candidate)) {
+      return path.dirname(candidate);
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+
+const LOCKFILE_PATTERN = /^(?:\/assistant)?\/__local\/lockfile$/;
+const HATCH_PATTERN = /^(?:\/assistant)?\/__local\/hatch$/;
+const RETIRE_PATTERN = /^(?:\/assistant)?\/__local\/retire$/;
+const UNPAIR_PATTERN = /^(?:\/assistant)?\/__local\/unpair$/;
+const DEVICES_PATTERN = /^(?:\/assistant)?\/__local\/devices$/;
+const DEVICES_REVOKE_PATTERN = /^(?:\/assistant)?\/__local\/devices-revoke$/;
+const PAIRING_START_PATTERN = /^(?:\/assistant)?\/__local\/pairing-start$/;
+const PAIRING_POLL_PATTERN = /^(?:\/assistant)?\/__local\/pairing-poll$/;
+const PAIRING_CANCEL_PATTERN = /^(?:\/assistant)?\/__local\/pairing-cancel$/;
+const GUARDIAN_TOKEN_PATTERN =
+  /^(?:\/assistant)?\/__local\/guardian-token\/([^/]+)$/;
+const PLATFORM_SESSION_PATTERN =
+  /^(?:\/assistant)?\/__local\/platform-session$/;
+
+// The loopback platform session token. Persisted via the same store the CLI
+// uses (so `cadet client` restarts and CLI logins stay in sync), cached here
+// to keep it off the per-request proxy path. Set only after the SPA validates
+// the loopback `state`, so an unsolicited /callback can't fixate a session.
+let platformSessionToken: string | null | undefined;
+function currentPlatformToken(): string | null {
+  if (platformSessionToken === undefined) {
+    platformSessionToken = readPlatformToken();
+  }
+  return platformSessionToken;
+}
+
+// Whether to attach a host-owned credential to a proxied request. The browser
+// must positively identify the request as coming from this server's origin.
+export function isSameOriginRequest(req: Request): boolean {
+  return hasSameOriginCredentialProof(
+    req.headers.get("host") ?? undefined,
+    req.headers.get("origin") ?? undefined,
+    req.headers.get("sec-fetch-site") ?? undefined,
+  );
+}
+
+function getEnvRecord(): Record<string, string> {
+  const result: Record<string, string> = {};
+  for (const [k, v] of Object.entries(process.env)) {
+    if (v !== undefined) result[k] = v;
+  }
+  return result;
+}
+
+const _localEnv = getEnvRecord();
+const _lockfilePaths = resolveLockfilePaths(_localEnv);
+const _configDir = resolveConfigDir(_localEnv);
+const _baseDir = getBaseDir();
+
+async function handleLocalEndpoints(
+  req: Request,
+  url: URL,
+  server: { requestIP(req: Request): { address: string } | null },
+): Promise<Response | null> {
+  const { pathname } = url;
+  const lockfilePaths = _lockfilePaths;
+  const configDir = _configDir;
+
+  // Check if this is a __local or __gateway route before enforcing loopback.
+  const isLocalRoute =
+    LOCKFILE_PATTERN.test(pathname) ||
+    HATCH_PATTERN.test(pathname) ||
+    RETIRE_PATTERN.test(pathname) ||
+    UNPAIR_PATTERN.test(pathname) ||
+    DEVICES_PATTERN.test(pathname) ||
+    DEVICES_REVOKE_PATTERN.test(pathname) ||
+    PAIRING_START_PATTERN.test(pathname) ||
+    PAIRING_POLL_PATTERN.test(pathname) ||
+    PAIRING_CANCEL_PATTERN.test(pathname) ||
+    GUARDIAN_TOKEN_PATTERN.test(pathname) ||
+    PLATFORM_SESSION_PATTERN.test(pathname) ||
+    parseGatewayUrl(pathname).match ||
+    parsePairedGatewayUrl(pathname).match;
+
+  if (!isLocalRoute) return null;
+
+  // All __local and __gateway endpoints are restricted to loopback clients.
+  const peer = server.requestIP(req)?.address ?? "";
+  if (!isLoopbackAddr(peer)) {
+    return Response.json({ error: "Forbidden" }, { status: 403 });
+  }
+
+  if (
+    !headerHostIsLoopback(req.headers.get("host") ?? undefined) ||
+    !originIsAllowed(req.headers.get("origin") ?? undefined)
+  ) {
+    return Response.json({ error: "Forbidden" }, { status: 403 });
+  }
+
+  // Platform session: the SPA hands over the loopback token here (after it has
+  // validated the `state` nonce) so the proxy below can authenticate to the
+  // platform. The browser never holds a session cookie.
+  if (PLATFORM_SESSION_PATTERN.test(pathname)) {
+    if (req.method === "DELETE") {
+      clearPlatformToken();
+      platformSessionToken = null;
+      return Response.json({ ok: true });
+    }
+    if (req.method === "POST") {
+      const body = (await req.json().catch(() => null)) as {
+        token?: unknown;
+      } | null;
+      const token = body?.token;
+      if (typeof token !== "string" || !/^[A-Za-z0-9]+$/.test(token)) {
+        return Response.json(
+          { ok: false, error: "Invalid token" },
+          { status: 400 },
+        );
+      }
+      savePlatformToken(token);
+      platformSessionToken = token;
+      return Response.json({ ok: true });
+    }
+    return new Response(null, { status: 405 });
+  }
+
+  // Lockfile
+  if (LOCKFILE_PATTERN.test(pathname)) {
+    if (req.method === "GET") {
+      const result = getLockfileData(lockfilePaths);
+      if (result.ok) {
+        return Response.json(result.data);
+      }
+      return new Response(null, { status: result.status });
+    }
+    if (req.method === "POST") {
+      let body: Record<string, unknown>;
+      try {
+        body = (await req.json()) as Record<string, unknown>;
+      } catch {
+        return Response.json(
+          { ok: false, error: "Invalid JSON body" },
+          { status: 400 },
+        );
+      }
+      let result;
+      if (body.syncPlatform && Array.isArray(body.platformAssistants)) {
+        result = replacePlatformAssistants(
+          lockfilePaths,
+          body.platformAssistants as Array<Record<string, unknown>>,
+          body.organizationId as string | undefined,
+        );
+      } else if (body.rename && typeof body.rename === "object") {
+        const rename = body.rename as Record<string, unknown>;
+        result = renameLockfileAssistantIfPresent(
+          lockfilePaths,
+          rename.assistantId as string,
+          rename.name as string,
+        );
+      } else {
+        result = upsertRendererLockfileAssistant(
+          lockfilePaths,
+          body.assistant as Record<string, unknown>,
+          body.activeAssistant as string | undefined,
+        );
+      }
+      return Response.json(result, { status: result.ok ? 200 : result.status });
+    }
+    return new Response(null, { status: 405 });
+  }
+
+  // Hatch
+  if (HATCH_PATTERN.test(pathname)) {
+    if (req.method !== "POST") return new Response(null, { status: 405 });
+
+    let remote: string | undefined;
+    const contentType = req.headers.get("content-type") ?? "";
+    if (contentType.includes("json")) {
+      try {
+        const body = (await req.json()) as {
+          remote?: string;
+        };
+        if (body.remote) remote = body.remote;
+      } catch {
+        return Response.json(
+          { ok: false, error: "Invalid JSON body" },
+          { status: 400 },
+        );
+      }
+    }
+
+    let invocation: CliInvocation;
+    try {
+      invocation = resolveDevCliInvocation(_baseDir);
+    } catch (err) {
+      return Response.json(
+        { ok: false, error: err instanceof Error ? err.message : String(err) },
+        { status: 500 },
+      );
+    }
+
+    const result = await runHatch(invocation, remote ? { remote } : undefined);
+    if (result.ok) {
+      return Response.json({ ok: true, assistantId: result.assistantId });
+    }
+    return Response.json(
+      { ok: false, error: result.error },
+      { status: result.status },
+    );
+  }
+
+  // Retire
+  if (RETIRE_PATTERN.test(pathname)) {
+    if (req.method !== "POST") return new Response(null, { status: 405 });
+
+    let assistantId: string | undefined;
+    try {
+      const body = (await req.json()) as { assistantId?: string };
+      assistantId = body.assistantId;
+    } catch {
+      return Response.json(
+        { ok: false, error: "Invalid JSON body" },
+        { status: 400 },
+      );
+    }
+
+    if (!assistantId) {
+      return Response.json(
+        { ok: false, error: "Missing assistantId" },
+        { status: 400 },
+      );
+    }
+
+    if (!isActiveAssistant(lockfilePaths, assistantId)) {
+      return Response.json(
+        { ok: false, error: "Can only retire the active local assistant" },
+        { status: 403 },
+      );
+    }
+
+    let invocation: CliInvocation;
+    try {
+      invocation = resolveDevCliInvocation(_baseDir);
+    } catch (err) {
+      return Response.json(
+        { ok: false, error: err instanceof Error ? err.message : String(err) },
+        { status: 500 },
+      );
+    }
+
+    const result = await runRetire(invocation, assistantId);
+    if (result.ok) {
+      return Response.json({ ok: true });
+    }
+    return Response.json(
+      { ok: false, error: result.error },
+      { status: result.status },
+    );
+  }
+
+  // Unpair: forget a paired assistant (lockfile entry + guardian token).
+  if (UNPAIR_PATTERN.test(pathname)) {
+    if (req.method !== "POST") {
+      return new Response(null, { status: 405 });
+    }
+
+    let assistantId: string | undefined;
+    try {
+      const body = (await req.json()) as { assistantId?: string };
+      assistantId = body.assistantId;
+    } catch {
+      return Response.json(
+        { ok: false, error: "Invalid JSON body" },
+        { status: 400 },
+      );
+    }
+
+    if (!assistantId) {
+      return Response.json(
+        { ok: false, error: "Missing assistantId" },
+        { status: 400 },
+      );
+    }
+
+    const result = unpairAssistant(lockfilePaths, configDir, assistantId);
+    if (result.ok) {
+      return Response.json({ ok: true, lockfile: result.lockfile });
+    }
+    return Response.json(
+      { ok: false, error: result.error },
+      { status: result.status },
+    );
+  }
+
+  // Paired devices: list and revoke via the CLI (`cadet devices … --json`).
+  // Always 200 with `ok` discriminating success, matching the other hosts.
+  const isDevicesRevoke = DEVICES_REVOKE_PATTERN.test(pathname);
+  if (DEVICES_PATTERN.test(pathname) || isDevicesRevoke) {
+    if (req.method !== "POST") {
+      return new Response(null, { status: 405 });
+    }
+
+    let body: { assistantId?: unknown; hashedDeviceId?: unknown };
+    try {
+      body = (await req.json()) as typeof body;
+    } catch {
+      return Response.json(
+        { ok: false, error: "Invalid JSON body" },
+        { status: 400 },
+      );
+    }
+
+    const { assistantId, hashedDeviceId } = body;
+    if (typeof assistantId !== "string" || !assistantId) {
+      return Response.json(
+        { ok: false, error: "Missing assistantId" },
+        { status: 400 },
+      );
+    }
+    let revokeHash: string | null = null;
+    if (isDevicesRevoke) {
+      if (typeof hashedDeviceId !== "string" || !hashedDeviceId) {
+        return Response.json(
+          { ok: false, error: "Missing hashedDeviceId" },
+          { status: 400 },
+        );
+      }
+      revokeHash = hashedDeviceId;
+    }
+
+    let invocation: CliInvocation;
+    try {
+      invocation = resolveDevCliInvocation(_baseDir);
+    } catch (err) {
+      return Response.json(
+        { ok: false, error: err instanceof Error ? err.message : String(err) },
+        { status: 500 },
+      );
+    }
+
+    if (revokeHash !== null) {
+      return Response.json(
+        await runDevicesRevoke(invocation, assistantId, revokeHash),
+      );
+    }
+    return Response.json(await runDevicesList(invocation, assistantId));
+  }
+
+  // Pairing: the three-step device-code exchange that registers an assistant
+  // paired on another machine (guardian token + paired lockfile entry), the
+  // write counterpart of unpair. The exchange runs here rather than in the
+  // browser, so the device code and the credentials it buys never reach it.
+  if (
+    PAIRING_START_PATTERN.test(pathname) ||
+    PAIRING_POLL_PATTERN.test(pathname) ||
+    PAIRING_CANCEL_PATTERN.test(pathname)
+  ) {
+    if (req.method !== "POST") {
+      return new Response(null, { status: 405 });
+    }
+
+    let body: { address?: unknown; handle?: unknown; name?: unknown };
+    try {
+      body = (await req.json()) as {
+        address?: unknown;
+        handle?: unknown;
+        name?: unknown;
+      };
+    } catch {
+      return Response.json(
+        { ok: false, error: "Invalid JSON body" },
+        { status: 400 },
+      );
+    }
+
+    if (PAIRING_CANCEL_PATTERN.test(pathname)) {
+      return Response.json({ ok: pairingCancel(body.handle) });
+    }
+
+    if (PAIRING_START_PATTERN.test(pathname)) {
+      const result = await pairingStart(body.address);
+      if (result.ok) {
+        return Response.json({
+          ok: true,
+          handle: result.handle,
+          userCode: result.userCode,
+          expiresAt: result.expiresAt,
+          intervalSeconds: result.intervalSeconds,
+        });
+      }
+      // `rejection` rides along so the renderer can show its own localized
+      // copy for a refused address instead of this host's English.
+      return Response.json(
+        {
+          ok: false,
+          reason: result.reason,
+          error: result.error,
+          rejection: result.rejection,
+        },
+        { status: result.status },
+      );
+    }
+
+    const result = await pairingPoll(lockfilePaths, configDir, {
+      handle: body.handle,
+      name: body.name,
+    });
+    if (!result.ok) {
+      return Response.json(
+        { ok: false, reason: result.reason, error: result.error },
+        { status: result.status },
+      );
+    }
+    if (result.status === "pending") {
+      return Response.json({
+        ok: true,
+        status: "pending",
+        expiresAt: result.expiresAt,
+        intervalSeconds: result.intervalSeconds,
+      });
+    }
+    return Response.json({
+      ok: true,
+      status: "imported",
+      assistantId: result.assistantId,
+      accessOnly: result.accessOnly,
+    });
+  }
+
+  // Guardian token
+  const guardianMatch = pathname.match(GUARDIAN_TOKEN_PATTERN);
+  if (guardianMatch) {
+    if (req.method !== "GET") return new Response(null, { status: 405 });
+
+    const assistantId = decodeURIComponent(guardianMatch[1]!);
+
+    if (isPairedLockfileEntry(lockfilePaths, assistantId)) {
+      return Response.json(
+        { error: PAIRED_GUARDIAN_TOKEN_HOST_ONLY_ERROR },
+        { status: 403 },
+      );
+    }
+
+    let invocation: CliInvocation;
+    try {
+      invocation = resolveDevCliInvocation(_baseDir);
+    } catch (err) {
+      return Response.json(
+        { error: err instanceof Error ? err.message : String(err) },
+        { status: 500 },
+      );
+    }
+
+    const result = await getGuardianAccessToken(
+      assistantId,
+      configDir,
+      invocation,
+      true,
+      _localEnv,
+      { paired: false },
+    );
+    if (result.ok) {
+      return Response.json({ accessToken: result.accessToken });
+    }
+    return Response.json({ error: result.error }, { status: result.status });
+  }
+
+  // Gateway proxy — same allowlist decision the web (Vite middleware) and
+  // Electron (`app://` handler) hosts use, so all three can't drift.
+  const gatewayDecision = resolveGatewayProxyTarget(pathname, () =>
+    readAllowedGatewayPorts(lockfilePaths),
+  );
+  if (gatewayDecision.kind === "invalid-port") {
+    return new Response("Port must be between 1024 and 65535", { status: 400 });
+  }
+  if (gatewayDecision.kind === "forbidden-port") {
+    return new Response("Gateway port is not active in lockfile", {
+      status: 403,
+    });
+  }
+  if (gatewayDecision.kind === "forward") {
+    const { target: gatewayTarget } = gatewayDecision;
+    const targetUrl = `http://127.0.0.1:${gatewayTarget.port}${gatewayTarget.path}${url.search}`;
+    const headers = new Headers(req.headers);
+    headers.set("host", `127.0.0.1:${gatewayTarget.port}`);
+    return proxyGatewayFetch(req, targetUrl, headers, "Gateway proxy error");
+  }
+
+  // Paired-gateway proxy: same shared decision as the web (Vite middleware)
+  // and Electron (`app://` handler) hosts, forwarding to the remote gateway an
+  // imported pairing recorded as its `runtimeUrl`. The lockfile's paired
+  // entries are the allowlist. Renderer authorization and browser-ambient
+  // headers are stripped on the server-to-server hop. This CLI host reads the
+  // paired guardian bearer from disk and installs it after sanitization.
+  const pairedDecision = resolvePairedGatewayProxyTarget(
+    pathname + url.search,
+    () => readPairedGatewayTargets(lockfilePaths),
+  );
+  if (pairedDecision.kind === "reject") {
+    return new Response(pairedDecision.message, {
+      status: pairedDecision.status,
+    });
+  }
+  if (pairedDecision.kind === "forward") {
+    if (!isSameOriginRequest(req)) {
+      return Response.json({ error: "Forbidden" }, { status: 403 });
+    }
+    let invocation: CliInvocation;
+    try {
+      invocation = resolveDevCliInvocation(_baseDir);
+    } catch (err) {
+      return new Response(err instanceof Error ? err.message : String(err), {
+        status: 500,
+      });
+    }
+    const headers = new Headers(req.headers);
+    const tokenResult = await authorizePairedForwardHeaders(
+      pairedDecision.assistantId,
+      pairedDecision.runtimeUrl,
+      headers,
+      (assistantId, runtimeUrl) =>
+        getPairedGuardianAccessToken(
+          assistantId,
+          runtimeUrl,
+          configDir,
+          invocation,
+          true,
+          _localEnv,
+        ),
+    );
+    if (!tokenResult.ok) {
+      return new Response(tokenResult.error, { status: tokenResult.status });
+    }
+    headers.set("host", new URL(pairedDecision.url).host);
+    return proxyGatewayFetch(
+      req,
+      pairedDecision.url,
+      headers,
+      "Paired gateway proxy error",
+    );
+  }
+
+  return null;
+}
+
+// One streamed hop for both gateway data-plane proxies. The upstream
+// `transfer-encoding` is dropped so re-serving the streamed body doesn't emit
+// a duplicate chunked header.
+async function proxyGatewayFetch(
+  req: Request,
+  targetUrl: string,
+  headers: Headers,
+  errorMessage: string,
+): Promise<Response> {
+  try {
+    const hasBody = req.method !== "GET" && req.method !== "HEAD";
+    const proxyRes = await loopbackSafeFetch(targetUrl, {
+      method: req.method,
+      headers,
+      body: hasBody ? req.body : undefined,
+      redirect: "manual",
+    });
+    const resHeaders = new Headers(proxyRes.headers);
+    resHeaders.delete("transfer-encoding");
+    return new Response(proxyRes.body, {
+      status: proxyRes.status,
+      statusText: proxyRes.statusText,
+      headers: resHeaders,
+    });
+  } catch {
+    return new Response(errorMessage, { status: 502 });
+  }
+}
+
+function getBaseDir(): string {
+  let dir = import.meta.dir;
+  for (let depth = 0; depth < 8; depth++) {
+    if (existsSync(path.join(dir, "cli", "src", "index.ts"))) {
+      return dir;
+    }
+    const pkgPath = path.join(dir, "package.json");
+    if (existsSync(pkgPath)) {
+      return dir;
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return path.resolve(import.meta.dir, "..", "..", "..");
+}
+
+// Just the slice of a Bun server `fetchHandler` needs — matches the structural
+// arg `handleLocalEndpoints` accepts, so Bun's `Server` is assignable to it.
+type RequestPeerServer = {
+  requestIP(req: Request): { address: string } | null;
+};
+
+const WEB_PORT_SCAN_LIMIT = 50;
+
+type WebFetchHandler = (
+  req: Request,
+  server: RequestPeerServer,
+) => Promise<Response>;
+
+function isAddrInUse(err: unknown): boolean {
+  const e = err as { code?: string; message?: string } | undefined;
+  return (
+    e?.code === "EADDRINUSE" ||
+    /EADDRINUSE|address already in use/i.test(e?.message ?? "")
+  );
+}
+
+// Bind one loopback family; returns the server, or null when the port is in
+// use. Server type is inferred from `Bun.serve` (avoids a generic mismatch).
+function tryBindLoopback(
+  port: number,
+  hostname: string,
+  fetchHandler: WebFetchHandler,
+) {
+  try {
+    return Bun.serve({ port, hostname, fetch: fetchHandler });
+  } catch (err) {
+    if (isAddrInUse(err)) return null;
+    throw err;
+  }
+}
+
+/**
+ * Bind the local web server on BOTH loopback families (`127.0.0.1` and `::1`)
+ * so the app can be reached at `http://localhost:<port>` regardless of whether
+ * the browser resolves `localhost` to IPv4 or IPv6 — matching the host the
+ * platform hardcodes in its loopback login callback.
+ *
+ * IPv4 is mandatory. IPv6 is best-effort: if `::1` is already taken (e.g. the
+ * local platform's `vel up` edge-proxy owns `[::]:<port>`), the port is
+ * contested and we advance — otherwise `localhost` would resolve to that other
+ * server. If IPv6 is simply unavailable on the host, we proceed IPv4-only.
+ *
+ * Never binds wildcard interfaces (`0.0.0.0`/`::`): the server exposes
+ * `/__local/*` control endpoints, so it must stay loopback-only.
+ */
+function serveLoopback(
+  preferredPort: number,
+  fetchHandler: WebFetchHandler,
+  scanLimit = WEB_PORT_SCAN_LIMIT,
+) {
+  for (let port = preferredPort; port < preferredPort + scanLimit; port++) {
+    const primary = tryBindLoopback(port, "127.0.0.1", fetchHandler);
+    if (!primary) continue;
+
+    try {
+      const secondary = Bun.serve({
+        port,
+        hostname: "::1",
+        fetch: fetchHandler,
+      });
+      return { port, servers: [primary, secondary] };
+    } catch (err) {
+      if (isAddrInUse(err)) {
+        // `::1` is contested (e.g. `vel up`) — move ports so `localhost`
+        // doesn't resolve to that other server.
+        primary.stop(true);
+        continue;
+      }
+      // IPv6 unavailable (e.g. EADDRNOTAVAIL) — IPv4-only is acceptable since
+      // `localhost` then resolves to 127.0.0.1 anyway.
+      return { port, servers: [primary] };
+    }
+  }
+  throw new Error(
+    scanLimit === 1
+      ? `Port ${preferredPort} is already in use`
+      : `Could not bind a free loopback port in [${preferredPort}, ${preferredPort + scanLimit - 1}]`,
+  );
+}
+
+/** True when neither loopback family has a listener on `port`. */
+async function isDualLoopbackPortFree(port: number): Promise<boolean> {
+  const [busyV4, busyV6] = await Promise.all([
+    probePort(port, "127.0.0.1"),
+    probePort(port, "::1"),
+  ]);
+  return !busyV4 && !busyV6;
+}
+
+/**
+ * Find the first port at/above `preferred` with nothing listening on either
+ * loopback family. Used for the Vite dev server, which binds the port itself
+ * (via the `PORT` env). Connect-probe based, so there's a small TOCTOU window
+ * before Vite binds — acceptable for dev.
+ */
+async function findFreeDualLoopbackPort(preferred: number): Promise<number> {
+  for (let port = preferred; port < preferred + WEB_PORT_SCAN_LIMIT; port++) {
+    if (await isDualLoopbackPortFree(port)) {
+      return port;
+    }
+  }
+  return preferred;
+}
+
+/**
+ * Resolve the port for a probe-based web server launch: an explicit --port
+ * must be free (exit 1 otherwise — strict, no silent move), the default picks
+ * the first free port at/above 3000.
+ */
+async function resolveWebPort(webPort: number | undefined): Promise<number> {
+  if (webPort === undefined) {
+    return findFreeDualLoopbackPort(3000);
+  }
+  if (!(await isDualLoopbackPortFree(webPort))) {
+    console.error(`Port ${webPort} is already in use`);
+    process.exit(1);
+  }
+  return webPort;
+}
+
+/**
+ * Open `url` in the browser once `port` is accepting connections, polling for
+ * up to ~10s. Used for the Vite dev server, which binds the port asynchronously
+ * after spawn — opening immediately would load the tab before Vite is ready.
+ */
+async function openBrowserWhenReady(url: string, port: number): Promise<void> {
+  for (let attempt = 0; attempt < 50; attempt++) {
+    if (await probePort(port, "127.0.0.1")) {
+      openBrowser(url);
+      return;
+    }
+    await new Promise((resolve) => setTimeout(resolve, 200));
+  }
+}
+
+const WEB_BACKGROUND_LOG_FILE = "client-web.log";
+// Generous cap so a cold Vite dev-server boot (dependency optimization) still
+// counts as a successful start.
+const WEB_BACKGROUND_START_TIMEOUT_MS = 30_000;
+
+/**
+ * Launch `cadet client --interface web` as a detached background process.
+ *
+ * The port is resolved up front (explicit --port must be free; otherwise the
+ * first free port at/above 3000) and pinned via `--port` on the child so the
+ * URL printed here is the one the child binds. The child's stdout/stderr go to
+ * `<xdg-log-dir>/client-web.log` — same detach idiom as the nginx/ngrok
+ * spawns. Success is only reported once the child is accepting connections on
+ * the port; an early child exit (e.g. missing @mycadet/web assets) or a
+ * startup timeout fails with a pointer at the log file.
+ */
+async function spawnBackgroundWebInterface(
+  webPort: number | undefined,
+): Promise<void> {
+  const port = await resolveWebPort(webPort);
+
+  // Rebuild the argv without --background, pinning the resolved port.
+  const childArgs: string[] = ["client"];
+  const rawArgs = process.argv.slice(3);
+  for (let i = 0; i < rawArgs.length; i++) {
+    const arg = rawArgs[i];
+    if (arg === "--background") {
+      continue;
+    }
+    // A dangling --port can't reach here — parseArgs already rejected it.
+    if (arg === "--port") {
+      i++;
+      continue;
+    }
+    childArgs.push(arg);
+  }
+  childArgs.push("--port", String(port));
+
+  // Don't report success until the child is actually serving: watch for an
+  // early exit (e.g. missing @mycadet/web assets, port lost to the TOCTOU
+  // window) and poll the port until it accepts connections.
+  const { child, logPath, ready, exitCode } = await relaunchDetached({
+    args: childArgs,
+    logFile: WEB_BACKGROUND_LOG_FILE,
+    timeoutMs: WEB_BACKGROUND_START_TIMEOUT_MS,
+    isReady: () => probePort(port, "127.0.0.1"),
+    pollIntervalMs: 200,
+  });
+
+  if (exitCode !== undefined) {
+    console.error(
+      `Web interface exited during startup${exitCode !== null ? ` (exit code ${exitCode})` : ""}. Logs: ${logPath}`,
+    );
+    process.exit(1);
+  }
+  if (!ready) {
+    // Kill the detached child (its whole process group — the Vite path spawns
+    // grandchildren) so a slow startup can't bind the port and linger after
+    // we've reported failure.
+    if (child.pid !== undefined) {
+      try {
+        process.kill(-child.pid, "SIGTERM");
+      } catch {
+        child.kill("SIGTERM");
+      }
+    }
+    console.error(
+      `Web interface did not start listening on port ${port} within ${WEB_BACKGROUND_START_TIMEOUT_MS / 1000}s; terminated it. Logs: ${logPath}`,
+    );
+    process.exit(1);
+  }
+
+  console.log(`Cadet web interface: http://localhost:${port}${SPA_BASE}`);
+  console.log(`Running in background (pid ${child.pid}). Logs: ${logPath}`);
+  console.log(`Stop with: kill ${child.pid}`);
+}
+
+/**
+ * Config the local web host injects as `window.__CADET_CONFIG__` and serves at
+ * `/assistant/__config`, the document a caller probes to learn which assistant
+ * an origin fronts.
+ *
+ * It carries no `assistantId`: this host also serves `handleLocalEndpoints`, so
+ * the SPA on it switches between every assistant in the lockfile, exactly like
+ * the Vite dev server (`clients/web/vite-plugin-local-mode.ts`, which omits the
+ * id for the same reason). An id here would be the launch-time one, and a probe
+ * for any other assistant this origin serves would read it as a mismatch and
+ * report a false `foreign`. An absent id is deliberately benign to the probe.
+ */
+export function buildWebInterfaceConfig(opts: {
+  webUrl: string;
+  platformUrl: string;
+  disablePlatform: boolean;
+}): Record<string, unknown> {
+  const { webUrl, platformUrl, disablePlatform } = opts;
+  return { webUrl, platformUrl, disablePlatform };
+}
+
+async function runWebInterface(
+  flagEnvVars: Record<string, string>,
+  parsedFlagOverrides: Record<string, boolean | string>,
+  disablePlatform: boolean,
+  openInBrowser: boolean,
+  webPort: number | undefined,
+): Promise<void> {
+  // Propagate flag env vars so child processes (e.g. hatch from the web UI) inherit them.
+  Object.assign(process.env, flagEnvVars);
+
+  // Prefer Vite dev server in source checkouts for full local-mode support
+  // (HMR, __local endpoints, gateway proxy).
+  const webSourceDir = findWebSourceDir();
+  if (webSourceDir) {
+    return runViteDevServer(
+      webSourceDir,
+      flagEnvVars,
+      disablePlatform,
+      openInBrowser,
+      webPort,
+    );
+  }
+
+  const distDir = findWebDistDir();
+  if (!distDir) {
+    console.error(
+      `${ANSI.bold}--interface web${ANSI.reset}: unable to locate ` +
+        `@mycadet/web assets.\n\n` +
+        `  npm/bunx install:   npm install @mycadet/web\n` +
+        `  source checkout:    cd clients/web && VITE_PLATFORM_MODE=false bun run build`,
+    );
+    process.exit(1);
+  }
+
+  const rawIndexHtml = await Bun.file(path.join(distDir, "index.html")).text();
+  const platformUrl = getPlatformUrl();
+  const webUrl = getWebUrl();
+  const safeJson = (v: unknown) =>
+    JSON.stringify(v).replace(/</g, "\\u003c").replace(/>/g, "\\u003e");
+  const configJson = safeJson(
+    buildWebInterfaceConfig({ webUrl, platformUrl, disablePlatform }),
+  );
+  const hasOverrides = Object.keys(parsedFlagOverrides).length > 0;
+  const flagOverridesSnippet = hasOverrides
+    ? `;window.__CADET_FLAG_OVERRIDES__=${safeJson(parsedFlagOverrides)}`
+    : "";
+  const indexHtml = rawIndexHtml.replace(
+    "</head>",
+    `<script>window.__CADET_CONFIG__=${configJson}${flagOverridesSnippet}</script></head>`,
+  );
+
+  // The shell names this build's hashed chunks and carries the host's injected
+  // config snippet, so every route that falls back to it serves the same body
+  // under the same revalidating policy.
+  const spaShellResponse = () =>
+    new Response(indexHtml, {
+      headers: {
+        "Content-Type": "text/html; charset=utf-8",
+        "Cache-Control": REVALIDATE_CACHE_CONTROL,
+      },
+    });
+
+  const fetchHandler: WebFetchHandler = async (req, server) => {
+    const url = new URL(req.url);
+    const { pathname } = url;
+
+    if (pathname === "/" || pathname === "/assistant") {
+      return Response.redirect(SPA_BASE, 302);
+    }
+
+    // Loopback auth: the platform redirects here after login with
+    // ?state=...&session_token=... — forward into the SPA, which validates the
+    // `state` nonce before registering the token via /__local/platform-session.
+    if (pathname === "/callback") {
+      return Response.redirect(`/account/platform-callback${url.search}`, 302);
+    }
+
+    // Expose environment config to the SPA.
+    if (pathname === "/assistant/__config" || pathname === "/__config") {
+      return new Response(configJson, {
+        headers: { "Content-Type": "application/json" },
+      });
+    }
+
+    // __local endpoints for local-mode (lockfile, hatch, retire, guardian-token, gateway-proxy).
+    const localResponse = await handleLocalEndpoints(req, url, server);
+    if (localResponse) return localResponse;
+
+    // Reverse-proxy platform API requests.
+    if (
+      pathname.startsWith("/v1/") ||
+      pathname.startsWith("/_allauth/") ||
+      pathname.startsWith("/accounts/")
+    ) {
+      const target = new URL(pathname + url.search, platformUrl);
+      const headers = new Headers(req.headers);
+      headers.set("Host", new URL(platformUrl).host);
+      headers.delete("Origin");
+      headers.delete("Referer");
+
+      // The DRF API authenticates by header (X-Session-Token); the allauth /
+      // accounts session endpoints need the Django session cookie.
+      const isApiRequest = pathname.startsWith("/v1/");
+
+      // Authenticate with the loopback session token the SPA registered. Only
+      // same-origin SPA traffic gets the credential — never a cross-site caller.
+      const sessionToken = isSameOriginRequest(req)
+        ? currentPlatformToken()
+        : null;
+      if (isApiRequest) {
+        // Header-only auth for the DRF API. Sending a `sessionid` cookie would
+        // engage Django's SessionAuthentication, which enforces CSRF — and the
+        // proxy strips Origin/Referer above, so the CSRF Referer check would
+        // reject every unsafe (POST/PUT/PATCH) request. Drop any browser cookie
+        // (localhost jar) so it can't re-engage that path.
+        headers.delete("Cookie");
+        if (sessionToken) {
+          headers.set("X-Session-Token", sessionToken);
+        }
+      } else if (sessionToken) {
+        // allauth / accounts: the platform expects the Django session cookie.
+        headers.set(
+          "Cookie",
+          `sessionid=${sessionToken}; __Secure-sessionid=${sessionToken}`,
+        );
+        headers.set("X-Session-Token", sessionToken);
+      }
+
+      try {
+        const hasBody = req.method !== "GET" && req.method !== "HEAD";
+        const body = hasBody ? await req.arrayBuffer() : undefined;
+        const proxyRes = await loopbackSafeFetch(target.toString(), {
+          method: req.method,
+          headers,
+          body,
+          redirect: "manual",
+        });
+        const resHeaders = new Headers(proxyRes.headers);
+        resHeaders.delete("transfer-encoding");
+        return new Response(proxyRes.body, {
+          status: proxyRes.status,
+          statusText: proxyRes.statusText,
+          headers: resHeaders,
+        });
+      } catch (err) {
+        return new Response(
+          JSON.stringify({ error: `Platform proxy error: ${err}` }),
+          { status: 502, headers: { "Content-Type": "application/json" } },
+        );
+      }
+    }
+
+    if (pathname.startsWith(SPA_BASE)) {
+      const relPath = pathname.slice(SPA_BASE.length);
+      if (relPath) {
+        const filePath = path.join(distDir, relPath);
+        const file = Bun.file(filePath);
+        if (await file.exists()) {
+          return new Response(file, {
+            headers: {
+              "Cache-Control": relPath.startsWith("assets/")
+                ? IMMUTABLE_CACHE_CONTROL
+                : REVALIDATE_CACHE_CONTROL,
+            },
+          });
+        }
+      }
+      return spaShellResponse();
+    }
+
+    // SPA fallback for /account/* routes (login, callback, etc.)
+    if (pathname.startsWith("/account/")) {
+      return spaShellResponse();
+    }
+
+    return new Response("Not Found", { status: 404 });
+  };
+
+  // An explicit --port binds strictly (no scan) so the user gets the port they
+  // asked for or a clear error.
+  const preferredPort = webPort ?? 3000;
+  let bound: ReturnType<typeof serveLoopback>;
+  try {
+    bound = serveLoopback(
+      preferredPort,
+      fetchHandler,
+      webPort !== undefined ? 1 : WEB_PORT_SCAN_LIMIT,
+    );
+  } catch (err) {
+    console.error(err instanceof Error ? err.message : String(err));
+    process.exit(1);
+  }
+  const { port, servers } = bound;
+  if (port !== preferredPort) {
+    console.log(`Port ${preferredPort} in use; using ${port}.`);
+  }
+  // Advertise `localhost` (not `127.0.0.1`) so the app origin matches the host
+  // the platform hardcodes in its loopback callback. We bind both loopback
+  // families above so `localhost` reaches us whichever one it resolves to.
+  const webInterfaceUrl = `http://localhost:${port}${SPA_BASE}`;
+  console.log(`Cadet web interface: ${webInterfaceUrl}`);
+  if (openInBrowser) openBrowser(webInterfaceUrl);
+
+  const shutdown = (): void => {
+    for (const server of servers) server.stop();
+    process.exit(0);
+  };
+  process.on("SIGINT", shutdown);
+  process.on("SIGTERM", shutdown);
+
+  await new Promise(() => {});
+}
+
+async function runViteDevServer(
+  webSourceDir: string,
+  flagEnvVars: Record<string, string>,
+  disablePlatform: boolean,
+  openInBrowser: boolean,
+  webPort: number | undefined,
+): Promise<void> {
+  const platformUrl = getPlatformUrl();
+
+  // Build VITE_CADET_FLAG_* vars so Vite exposes them to the browser bundle.
+  const viteFlagVars: Record<string, string> = {};
+  for (const [envName, value] of Object.entries(flagEnvVars)) {
+    viteFlagVars[`VITE_${envName}`] = value;
+  }
+
+  // Auto-pick a free port (Vite uses strictPort) so a running `vel up` stack
+  // on :3000 doesn't wedge dev. The loopback callback port follows
+  // window.location.port, so a non-3000 port propagates automatically.
+  // An explicit --port is strict: error rather than silently moving.
+  const port = await resolveWebPort(webPort);
+  if (webPort === undefined && port !== 3000) {
+    console.log(`Port 3000 in use; using ${port}.`);
+  }
+
+  const child = spawn("bun", ["run", "dev"], {
+    cwd: webSourceDir,
+    stdio: "inherit",
+    windowsHide: true,
+    env: {
+      ...process.env,
+      ...flagEnvVars,
+      ...viteFlagVars,
+      ...(disablePlatform ? { VITE_CADET_DISABLE_PLATFORM: "true" } : {}),
+      VITE_PLATFORM_MODE: "false",
+      API_PROXY_TARGET: platformUrl,
+      CADET_WEB_URL: getWebUrl(),
+      CADET_PLATFORM_URL: platformUrl,
+      PORT: String(port),
+    },
+  });
+
+  // Vite binds the port itself, so wait until it's listening before opening the
+  // browser — otherwise the tab loads before the dev server is ready.
+  if (openInBrowser) {
+    void openBrowserWhenReady(`http://localhost:${port}${SPA_BASE}`, port);
+  }
+
+  const shutdown = (): void => {
+    child.kill();
+    process.exit(0);
+  };
+  process.on("SIGINT", shutdown);
+  process.on("SIGTERM", shutdown);
+
+  await new Promise<void>((_, reject) => {
+    child.on("exit", (code) => {
+      if (code !== 0) {
+        reject(new Error(`Vite dev server exited with code ${code}`));
+      }
+    });
+  });
+}
+
+/**
+ * Return a possibly-refreshed bearer token for the TUI's startup auth.
+ *
+ * Only a STORED guardian token is refreshable: platform session auth
+ * (`isManagedCloud(cloud)`) and ephemeral `--token` overrides (whose token won't
+ * match the store) are left untouched, as is a token that's still fresh. When
+ * the stored token has passed its `refreshAfter` (or expiry) and a refresh
+ * token is available, refresh once via the concurrency-safe refreshGuardianToken
+ * and use the rotated access token. Falls back to the existing token if refresh
+ * isn't possible/fails — the session still starts (same as before).
+ */
+export async function resolveFreshBearerToken(
+  runtimeUrl: string,
+  assistantId: string,
+  bearerToken: string | undefined,
+  cloud: string | undefined,
+): Promise<string | undefined> {
+  if (isManagedCloud(cloud) || !bearerToken || !assistantId) return bearerToken;
+
+  const stored = loadGuardianToken(assistantId);
+  // Refresh only the stored token (an ephemeral --token won't match), and only
+  // when a refresh credential is present.
+  if (!stored || stored.accessToken !== bearerToken || !stored.refreshToken) {
+    return bearerToken;
+  }
+
+  // Only refresh once the stored token is actually due for renewal.
+  if (!guardianTokenDueForRenewal(stored)) return bearerToken;
+
+  // SECURITY: bind the refresh to the entry's persisted URL. `--url`/`-u` can
+  // override `runtimeUrl` while still reusing this stored guardian token, so a
+  // poisoned/attacker URL must not receive the long-lived refreshToken +
+  // deviceId. Refresh only when the URL is one of the entry's persisted URLs,
+  // and send to the trusted persisted URL — not the caller-supplied one.
+  const lookup = lookupAssistantByIdentifier(assistantId);
+  if (lookup.status !== "found") return bearerToken;
+  const refreshUrl = trustedRefreshUrl(lookup.entry, runtimeUrl);
+  if (!refreshUrl) return bearerToken;
+
+  const refreshed = await refreshGuardianToken(refreshUrl, assistantId);
+  return refreshed?.accessToken ?? bearerToken;
+}
+
+export async function client(): Promise<void> {
+  const {
+    runtimeUrl,
+    assistantId,
+    assistantName: parsedAssistantName,
+    cloud,
+    platformToken,
+    bearerToken,
+    interfaceId,
+    flagEnvVars,
+    parsedFlagOverrides,
+    disablePlatform,
+    openBrowser: openInBrowser,
+    webPort,
+    background,
+  } = parseArgs();
+
+  if (disablePlatform) {
+    process.env.CADET_DISABLE_PLATFORM = "true";
+  }
+
+  if (interfaceId === WEB_INTERFACE_ID) {
+    if (background) {
+      await spawnBackgroundWebInterface(webPort);
+      return;
+    }
+    await runWebInterface(
+      flagEnvVars,
+      parsedFlagOverrides,
+      disablePlatform,
+      openInBrowser,
+      webPort,
+    );
+    return;
+  }
+
+  tuiLog.init();
+  tuiLog.info("session start", {
+    runtimeUrl,
+    assistantId,
+    cloud,
+    interfaceId,
+  });
+
+  const assistantName = await maybeHydratePlatformAssistantName(
+    assistantId,
+    parsedAssistantName,
+    cloud,
+    platformToken,
+  );
+
+  // Build pre-constructed request headers merged from auth + client registration.
+  // Spreading into every fetch site ensures consistency across REST and SSE endpoints.
+  let auth: Record<string, string> | undefined;
+  if (isManagedCloud(cloud) && platformToken) {
+    const orgId = await fetchOrganizationId(platformToken).catch((err) => {
+      tuiLog.warn("failed to fetch organization id", { err: String(err) });
+      return undefined;
+    });
+    auth = {
+      "X-Session-Token": platformToken,
+      ...(orgId ? { "Cadet-Organization-Id": orgId } : {}),
+      ...getClientRegistrationHeaders(interfaceId),
+    };
+  } else {
+    // Proactively refresh a stale STORED guardian token before opening the TUI,
+    // so launching after the access token expired renews transparently rather
+    // than erroring. (Mid-session expiry — the token dying while the TUI is
+    // already open — is a separate follow-up, since the TUI threads a static
+    // auth object through React.)
+    const token = await resolveFreshBearerToken(
+      runtimeUrl,
+      assistantId,
+      bearerToken,
+      cloud,
+    );
+    auth = {
+      ...(token ? { Authorization: `Bearer ${token}` } : {}),
+      ...getClientRegistrationHeaders(interfaceId),
+    };
+  }
+
+  const { renderChatApp } = await import("../components/DefaultMainScreen");
+
+  process.stdout.write("\x1b[2J\x1b[H");
+
+  const app = renderChatApp(
+    runtimeUrl,
+    assistantId,
+    () => {
+      tuiLog.info("session end (user disconnect)");
+      tuiLog.close();
+      app.unmount();
+      process.stdout.write("\x1b[2J\x1b[H");
+      console.log(`${ANSI.dim}Disconnected.${ANSI.reset}`);
+      process.exit(0);
+    },
+    { auth, assistantName },
+  );
+}