relaybrain 0.2.0 → 0.2.1

package/backend/lib/notices.js

@@ -132,7 +132,14 @@ function dismissByKey(key) {
   return count;
 }
 
+/** The stored row for a key, dismissed or not (raw, with payload). */
+function findNotice(key) {
+  if (!key) return null;
+  return prune(load()).find((n) => n.key === key) || null;
+}
+
 module.exports = {
+  findNotice,
   listNotices,
   unreadCount,
   pushNotice,

package/backend/lib/room.js

@@ -1,10 +1,125 @@
 const fs = require("fs");
+const os = require("os");
 const path = require("path");
 const crypto = require("crypto");
 const { spawn, spawnSync } = require("child_process");
 const { homeRelayDir } = require("./paths");
 const { normalizeWorkspaceRoot } = require("./transcripts/util");
 
+function localLanIp() {
+  try {
+    const nets = os.networkInterfaces() || {};
+    const candidates = [];
+    for (const [name, addrs] of Object.entries(nets)) {
+      if (/vethernet|wsl|docker|vbox|vmware|loopback|tailscale|ZeroTier/i.test(name)) continue;
+      for (const a of addrs || []) {
+        if ((a.family === "IPv4" || a.family === 4) && !a.internal && a.address) {
+          candidates.push(a.address);
+        }
+      }
+    }
+    const prio = candidates.find((ip) => /^(192\.168\.|10\.|172\.(1[6-9]|2\d|3[0-1])\.)/.test(ip));
+    return prio || candidates[0] || null;
+  } catch {
+    return null;
+  }
+}
+
+let cachedProviders = { at: 0, data: null };
+
+function checkCliInstalled(cmd, args = ["--version"]) {
+  try {
+    const r = spawnSync(cmd, args, { encoding: "utf8", windowsHide: true, timeout: 2500 });
+    return !r.error && r.status === 0;
+  } catch {
+    return false;
+  }
+}
+
+function detectProviders(port = 3001) {
+  const now = Date.now();
+  if (cachedProviders.data && now - cachedProviders.at < 15_000) {
+    return { ...cachedProviders.data, lanUrl: localLanIp() ? `http://${localLanIp()}:${port}` : null };
+  }
+  const lanIp = localLanIp();
+  const lanUrl = lanIp ? `http://${lanIp}:${port}` : null;
+  const cfInstalled = checkCliInstalled("cloudflared", ["--version"]);
+  let tsInstalled = false;
+  let tsRunning = false;
+  let tsDns = null;
+  try {
+    const st = spawnSync("tailscale", ["status", "--json"], { encoding: "utf8", windowsHide: true, timeout: 2500 });
+    if (!st.error) {
+      tsInstalled = true;
+      if (st.status === 0) {
+        const info = JSON.parse(st.stdout || "{}");
+        tsRunning = info.BackendState === "Running";
+        tsDns = String(info.Self?.DNSName || "").replace(/\.$/, "") || null;
+      }
+    }
+  } catch {
+    /* ignore */
+  }
+  const ngrokInstalled = checkCliInstalled("ngrok", ["version"]);
+  const providers = [
+    {
+      id: "cloudflared",
+      name: "Cloudflare Quick Tunnel",
+      badge: "Recommended",
+      installed: cfInstalled,
+      ready: cfInstalled,
+      command: `cloudflared tunnel --url http://127.0.0.1:${port}`,
+      installHint: process.platform === "win32" ? "winget install Cloudflare.cloudflared" : "brew install cloudflared",
+      description: "Fast global edge HTTPS tunnel — zero signup, no account, no rate limits.",
+    },
+    {
+      id: "tailscale",
+      name: "Tailscale Funnel",
+      badge: tsRunning ? "Connected" : "Mesh / HTTPS",
+      installed: tsInstalled,
+      ready: tsInstalled && tsRunning && Boolean(tsDns),
+      dns: tsDns ? `https://${tsDns}` : null,
+      command: `tailscale funnel --bg ${port}`,
+      installHint: "tailscale funnel " + port,
+      description: "Private Tailnet mesh or public HTTPS via Tailscale Funnel.",
+    },
+    {
+      id: "lan",
+      name: "Direct LAN / Custom URL",
+      badge: lanUrl ? "Zero-install LAN" : "Custom URL",
+      installed: true,
+      ready: Boolean(lanUrl),
+      lanIp,
+      lanUrl,
+      command: lanUrl || "https://your-relay-host.example.com",
+      description: "Instant zero-install sharing on the same Wi-Fi/LAN, or paste any self-hosted/tunnel URL (Railway, Fly.io, etc.).",
+    },
+    {
+      id: "ngrok",
+      name: "ngrok",
+      badge: "Legacy",
+      installed: ngrokInstalled,
+      ready: ngrokInstalled,
+      command: `ngrok http ${port}`,
+      installHint: process.platform === "win32" ? "winget install Ngrok.Ngrok" : "brew install ngrok",
+      description: "Classic HTTP tunnel (requires ngrok authtoken; subject to free-tier rate limits).",
+    },
+  ];
+  const out = { lanIp, lanUrl, providers };
+  cachedProviders = { at: now, data: out };
+  return out;
+}
+
+function inferProviderFromUrl(url, explicit) {
+  if (explicit && explicit !== "auto") return explicit;
+  const u = String(url || "").toLowerCase();
+  if (u.includes(".trycloudflare.com")) return "cloudflared";
+  if (u.includes(".ts.net")) return "tailscale";
+  if (u.includes("ngrok")) return "ngrok";
+  if (/^https?:\/\/(192\.168\.|10\.|172\.(1[6-9]|2\d|3[0-1])\.|localhost|127\.)/.test(u)) return "lan";
+  return explicit || "custom";
+}
+
 function roomPath(workspacePath) {
   if (workspacePath) {
     const root = normalizeWorkspaceRoot(workspacePath) || workspacePath;
@@ -364,32 +479,36 @@ function activeTunnelUrl() {
  *   3. Tailscale Funnel (`tailscale funnel --bg <port>`) — fast if Tailscale is logged in
  *   4. ngrok (`ngrok http <port>`) — legacy fallback
  */
-async function ensureTunnel(port) {
+async function ensureTunnel(port, requestedProvider) {
   if (ensureInFlight) return ensureInFlight;
-  ensureInFlight = ensureTunnelOnce(port).finally(() => {
+  ensureInFlight = ensureTunnelOnce(port, requestedProvider).finally(() => {
     ensureInFlight = null;
   });
   return ensureInFlight;
 }
 
-async function ensureTunnelOnce(port) {
-  const pref = String(process.env.RELAY_TUNNEL || "").trim().toLowerCase();
-  if (process.env.RELAY_PUBLIC_URL) {
+async function ensureTunnelOnce(port, requestedProvider) {
+  const pref = String(requestedProvider || process.env.RELAY_TUNNEL || "").trim().toLowerCase();
+  if (pref === "lan") {
+    const ip = localLanIp();
+    return ip ? `http://${ip}:${port}` : null;
+  }
+  if (!requestedProvider && process.env.RELAY_PUBLIC_URL) {
     return String(process.env.RELAY_PUBLIC_URL).trim().replace(/\/$/, "");
   }
-  if (cloudflaredAlive() && cloudflaredUrl && (!pref || pref === "cloudflared")) {
+  if (cloudflaredAlive() && cloudflaredUrl && (!pref || pref === "auto" || pref === "cloudflared")) {
     return cloudflaredUrl;
   }
 
   // Try Cloudflare Quick Tunnel first (unless user explicitly requested tailscale/ngrok).
-  if (!pref || pref === "cloudflared") {
+  if (!pref || pref === "auto" || pref === "cloudflared") {
     const cfUrl = await spawnCloudflared(port);
     if (cfUrl) return cfUrl;
     if (pref === "cloudflared") return null;
   }
 
   // Try Tailscale Funnel next.
-  if (!pref || pref === "tailscale") {
+  if (!pref || pref === "auto" || pref === "tailscale") {
     const tsUrl = tryTailscaleFunnel(port);
     if (tsUrl) return tsUrl;
     if (pref === "tailscale") return null;
@@ -442,6 +561,7 @@ function newHostRoom(url, extra, existing) {
     role: "host",
     live: true,
     url,
+    provider: inferProviderFromUrl(url, extra.provider || keep.provider),
     roomId: keep.roomId || mintRoomId(),
     nonce: keep.nonce || mintNonce(),
     hostProjectId: extra.hostProjectId || keep.hostProjectId || null,
@@ -460,19 +580,37 @@ function newHostRoom(url, extra, existing) {
   };
 }
 
+function providerErrorHint(provider, port = 3001) {
+  if (provider === "cloudflared") {
+    return "Cloudflare Quick Tunnel (`cloudflared`) is not installed or could not reach the edge. Install it with `winget install Cloudflare.cloudflared` (Windows) or `brew install cloudflared` (macOS), or choose Direct LAN / Custom URL.";
+  }
+  if (provider === "tailscale") {
+    return `Tailscale Funnel is not active on this machine. Make sure Tailscale is logged in and run \`tailscale funnel ${port}\`, or pick Cloudflare Quick Tunnel / Direct LAN.`;
+  }
+  if (provider === "lan") {
+    return "Could not detect a local LAN IPv4 address. Enter your machine's LAN or custom URL manually.";
+  }
+  if (provider === "ngrok") {
+    return "ngrok could not be started (check `ngrok config add-authtoken` or free-tier limits). Try Cloudflare Quick Tunnel (`cloudflared`) instead.";
+  }
+  return NGROK_HINT;
+}
+
 async function share(port, extra = {}) {
   const explicitUrl = extra.url ? String(extra.url).trim().replace(/\/$/, "") : null;
-  const url = explicitUrl || (await ensureTunnel(port));
+  const requestedProvider = extra.provider ? String(extra.provider).trim().toLowerCase() : null;
+  const url = explicitUrl || (await ensureTunnel(port, requestedProvider));
   if (!url) {
     return {
       ok: false,
-      error: "ngrok_unavailable",
-      hint: NGROK_HINT,
+      error: "tunnel_unavailable",
+      provider: requestedProvider || "auto",
+      hint: providerErrorHint(requestedProvider, port),
     };
   }
   const existing = loadRoom(extra.workspacePath);
   const room = saveRoom(
-    upsertMember(newHostRoom(url, extra, existing), extra.hostUser, "host"),
+    upsertMember(newHostRoom(url, { ...extra, provider: inferProviderFromUrl(url, requestedProvider) }, existing), extra.hostUser, "host"),
     extra.workspacePath
   );
   return { ok: true, room };
@@ -494,5 +632,7 @@ module.exports = {
   dropMember,
   membersView,
   mintRoomId,
+  detectProviders,
+  localLanIp,
   NGROK_HINT,
 };

package/backend/lib/transcripts/discover.js

@@ -121,24 +121,122 @@ function claudeTranscriptCwd(file) {
   return null;
 }
 
-function discoverClaude(workspacePath) {
-  const root = path.join(HOME, ".claude", "projects");
-  const projectDir = path.join(root, claudeSlug(workspacePath));
-  if (!fs.existsSync(projectDir)) return [];
-  const target = normalizeCompare(workspacePath);
-  let files = [];
+function claudeJsonlFiles(dir) {
   try {
-    files = fs
-      .readdirSync(projectDir, { withFileTypes: true })
+    return fs
+      .readdirSync(dir, { withFileTypes: true })
       .filter((entry) => entry.isFile() && entry.name.endsWith(".jsonl"))
-      .map((entry) => path.join(projectDir, entry.name));
+      .map((entry) => path.join(dir, entry.name));
   } catch {
     return [];
   }
-  return files.filter((file) => {
+}
+
+// Claude project dirs for every folder above the workspace. Opening VS Code (or
+// the CLI) one level up — a monorepo root, a hackathon folder holding the repo —
+// files the session under the parent's slug, so the repo's own slug dir never
+// sees it.
+function claudeAncestorDirs(workspacePath) {
+  const root = path.join(HOME, ".claude", "projects");
+  const dirs = [];
+  let dir = path.resolve(workspacePath);
+  for (let parent = path.dirname(dir); parent !== dir; dir = parent, parent = path.dirname(dir)) {
+    const candidate = path.join(root, claudeSlug(parent));
+    if (fs.existsSync(candidate)) dirs.push({ dir: candidate, cwd: normalizeCompare(parent) });
+  }
+  return dirs;
+}
+
+// Transcripts are append-only, so once a session has mentioned a file inside the
+// workspace it always will; only the bytes added since the last look need reading.
+const touchCache = new Map();
+
+// The workspace path as a transcript spells it: plain, JSON-escaped, raw
+// backslashes, or a file:// URL. Matched literally rather than through
+// pathsMentionedIn, whose regex stops at whitespace and so never sees a path
+// under a home folder like "C:\Users\Jane Doe". The trailing separator keeps
+// `.../relay` from matching `.../relay-old`.
+function workspaceSpellings(needle) {
+  const fwd = needle.toLowerCase();
+  const url = fwd.replace(/ /g, "%20");
+  return [
+    `${fwd}/`,
+    `${fwd.replace(/\//g, "\\")}\\`,
+    `${fwd.replace(/\//g, "\\\\")}\\\\`,
+    `${url}/`,
+    `${url.replace(/^([a-z]):/, "$1%3a")}/`,
+  ];
+}
+
+function transcriptTouches(file, needle) {
+  let size;
+  try {
+    size = fs.statSync(file).size;
+  } catch {
+    return false;
+  }
+  const key = `${file}\n${needle}`;
+  const prev = touchCache.get(key);
+  if (prev?.matched) return true;
+  if (prev && prev.size === size) return false;
+  const from = Math.max(0, (prev?.size || 0) - 1024);
+  const spellings = workspaceSpellings(needle);
+  let matched = false;
+  try {
+    const fd = fs.openSync(file, "r");
+    try {
+      const chunk = 4 * 1024 * 1024;
+      const buf = Buffer.alloc(chunk);
+      for (let pos = from; pos < size && !matched; pos += chunk - 1024) {
+        const n = fs.readSync(fd, buf, 0, chunk, pos);
+        if (n <= 0) break;
+        const text = buf.toString("utf8", 0, n).toLowerCase();
+        matched = spellings.some((s) => text.includes(s));
+        if (n < chunk) break;
+      }
+    } finally {
+      fs.closeSync(fd);
+    }
+  } catch {
+    return false;
+  }
+  touchCache.set(key, { size, matched });
+  return matched;
+}
+
+const CLAUDE_ANCESTOR_MAX_FILES = 40;
+
+function discoverClaude(workspacePath) {
+  const root = path.join(HOME, ".claude", "projects");
+  const projectDir = path.join(root, claudeSlug(workspacePath));
+  const target = normalizeCompare(workspacePath);
+  const own = claudeJsonlFiles(projectDir).filter((file) => {
     const cwd = claudeTranscriptCwd(file);
     return !cwd || normalizeCompare(cwd) === target;
   });
+
+  // Sessions started in a parent folder count when they reach into this repo.
+  const needle = pathNeedle(workspacePath);
+  const inherited = [];
+  for (const { dir, cwd: dirCwd } of claudeAncestorDirs(workspacePath)) {
+    const recent = claudeJsonlFiles(dir)
+      .map((file) => {
+        try {
+          return { file, mtimeMs: fs.statSync(file).mtimeMs };
+        } catch {
+          return null;
+        }
+      })
+      .filter(Boolean)
+      .sort((a, b) => b.mtimeMs - a.mtimeMs)
+      .slice(0, CLAUDE_ANCESTOR_MAX_FILES);
+    for (const { file } of recent) {
+      const cwd = claudeTranscriptCwd(file);
+      if (cwd && normalizeCompare(cwd) !== dirCwd) continue;
+      if (transcriptTouches(file, needle)) inherited.push(file);
+    }
+  }
+  return [...own, ...inherited];
 }
 
 function discoverCodex(workspacePath) {
@@ -319,6 +417,7 @@ function transcriptWatchRoots(workspacePath) {
   if (cursorDir) roots.push(cursorDir);
   const claudeDir = path.join(HOME, ".claude", "projects", claudeSlug(workspacePath));
   if (fs.existsSync(claudeDir)) roots.push(claudeDir);
+  for (const { dir } of claudeAncestorDirs(workspacePath)) roots.push(dir);
   const codexDir = path.join(HOME, ".codex", "sessions");
   if (fs.existsSync(codexDir)) roots.push(codexDir);
   roots.push(...antigravityRoots());

package/backend/server.js

@@ -38,7 +38,7 @@ const { listDir, listGithubRepos } = require("./lib/localBrowse");
 const { ingest: ingestSupergraph } = require("./lib/supergraph");
 const { cloneRepo, addLocal, detectRemoteUrl } = require("./lib/cloneRepo");
 const { installProjectHooks, installGlobalHooks } = require("./lib/installHooks");
-const { loadRoom, saveRoom, clearRoom, share: shareRoom, ensureTunnel, activeTunnelUrl, killCloudflared, upsertMember, markLeft, dropMember, membersView } = require("./lib/room");
+const { loadRoom, saveRoom, clearRoom, share: shareRoom, ensureTunnel, activeTunnelUrl, killCloudflared, upsertMember, markLeft, dropMember, membersView, detectProviders } = require("./lib/room");
 const { localSnapshot, savePeerSnapshot, mergeRoomViews, clearPeers } = require("./lib/roomSync");
 const { compileRoomAsk } = require("./lib/roomAsk");
 const { recordCollision, mergeCollisionStats, loadLocalCollisions } = require("./lib/collisionMetrics");
@@ -76,6 +76,7 @@ const { skipPublish, applyClash, aliveLock } = require("./lib/peerClash");
 const { dirtyFiles } = require("./lib/dirtyFiles");
 const { authorizeUrl, exchangeCode } = require("./lib/githubOAuth");
 const {
+  findNotice,
   listNotices,
   unreadCount,
   pushNotice,
@@ -781,6 +782,10 @@ async function main() {
     };
     broadcastPatch(envelope);
     const room = loadRoom(project.path);
+    if (room?.url) {
+      const who = patch.ownerLogin ? `@${patch.ownerLogin}` : "local";
+      console.log(`[relay-patch] sent to room (${room.role}): ${rel} from ${who}`);
+    }
     if (room?.url && room.role !== "host") {
       const body = { ...envelope, workspaceId: room.hostProjectId || envelope.workspaceId, type: "patch" };
       if (!sendToHost(body)) {
@@ -1134,13 +1139,33 @@ async function main() {
     return currentProject();
   }
 
+  function logPeerPatch(patch, result) {
+    if (result?.self) return;
+    const who = patch.ownerLogin ? `@${patch.ownerLogin}` : patch.originId || "teammate";
+    const via = patch.agent && patch.agent !== "fs.watch" ? ` via ${patch.agent}` : "";
+    if (result?.applied) {
+      console.log(`[relay-patch] teammate edit applied: ${patch.file} from ${who}${via} — written to disk`);
+      return;
+    }
+    const why = result?.duplicate
+      ? "already applied"
+      : result?.reason === "identical"
+        ? "already on disk (same content)"
+        : result?.reason || "not written";
+    console.log(`[relay-patch] teammate edit received, not written: ${patch.file} from ${who}${via} — ${why}`);
+  }
+
   function acceptPeerPatch(patch, hint, { skipIfOrigin } = {}) {
     if (!patch?.file) return { applied: false };
     if (skipIfOrigin && patch.originId && patch.originId === originId()) {
       return { applied: false, self: true };
     }
     const project = peerProject(hint);
-    if (!project) return { applied: false, reason: "no_local_repo" };
+    if (!project) {
+      const result = { applied: false, reason: "no_local_repo" };
+      logPeerPatch(patch, result);
+      return result;
+    }
     const clash = applyClash(lockTable, project.path, patch.file, patch);
     if (clash) {
       if (project?.id) {
@@ -1151,12 +1176,15 @@ async function main() {
           reason: clash.reason,
         });
       }
-      return { applied: false, projectId: project.id, ...clash };
+      const result = { applied: false, projectId: project.id, ...clash };
+      logPeerPatch(patch, result);
+      return result;
     }
     applyingRemote.add(`${project.id}:${patch.file}`);
-    const result = applyPeerFile(project.id, patch, project.path);
+    const result = { ...applyPeerFile(project.id, patch, project.path), projectId: project.id };
     applyingRemote.delete(`${project.id}:${patch.file}`);
-    return { ...result, projectId: project.id };
+    logPeerPatch(patch, result);
+    return result;
   }
 
   const currentProject = () => {
@@ -1491,6 +1519,11 @@ async function main() {
       const key = `invite:${room.roomId}`;
       live.add(key);
       if (current?.roomId && current.roomId === room.roomId) continue;
+      // A host keeps one roomId across sessions, so the invite key repeats. A new
+      // tunnel URL means the host started hosting again: bring the invite back
+      // even if the last one was dismissed (otherwise it stays hidden for a week).
+      const prior = findNotice(key);
+      const revive = Boolean(prior && room.url && prior.payload?.url !== room.url);
       emitNotice({
         type: "invite",
         key,
@@ -1506,7 +1539,7 @@ async function main() {
           projectName: room.projectName || project?.name || null,
           projectId: project?.id || null,
         },
-      });
+      }, { revive });
     }
     for (const n of listNotices()) {
       if (n.type === "invite" && n.key && !live.has(n.key) && !(current?.roomId && n.key === `invite:${current.roomId}`)) {
@@ -2080,6 +2113,19 @@ async function main() {
     dashboard.invites = room?.role === "host" && !isRemoteRequest(req) ? inviteView(room) : [];
     dashboard.openRooms =
       !isRemoteRequest(req) && discoverState.key === repoKeyFromRemote(project.remoteUrl) ? discoverState.rooms : [];
+    // Outside a room, presence only knew room members, so everyone — including
+    // the viewer, and a teammate who is visibly hosting — read as offline while
+    // the Team tab simultaneously said "@x is hosting". Mark what we do know.
+    if (!room?.url && !isRemoteRequest(req)) {
+      const me = currentUser();
+      const hosting = new Set(dashboard.openRooms.map((r) => String(r.hostLogin || "").toLowerCase()));
+      dashboard.collaborators = dashboard.collaborators.map((c) => {
+        const key = String(c.login || "").toLowerCase();
+        if (sameLogin(c.login, me.login)) return { ...c, online: true };
+        if (hosting.has(key)) return { ...c, online: true, hosting: true };
+        return c;
+      });
+    }
     if (!isRemoteRequest(req) && room?.role !== "host") {
       refreshOpenRooms(project)
         .then((rooms) => {
@@ -2481,6 +2527,10 @@ async function main() {
   // publicRoom strips invite and member-token hashes: this route answers
   // through the tunnel, and the raw room file is a credential store.
   app.get("/api/room", (_req, res) => res.json({ room: publicRoom(loadRoom()) }));
+  app.get("/api/room/providers", (_req, res) => {
+    const port = parsePort(process.argv);
+    res.json({ ok: true, ...detectProviders(port) });
+  });
   app.post("/api/room/share", async (req, res) => {
     const project = currentProject();
     const existing = loadRoom(project?.path);
@@ -2491,7 +2541,12 @@ async function main() {
       });
     }
     const customUrl = req.body?.url ? String(req.body.url).trim().replace(/\/$/, "") : null;
-    const result = await shareRoom(parsePort(process.argv), { ...shareExtras(project), ...(customUrl ? { url: customUrl } : {}) });
+    const provider = req.body?.provider ? String(req.body.provider).trim().toLowerCase() : null;
+    const result = await shareRoom(parsePort(process.argv), {
+      ...shareExtras(project),
+      ...(customUrl ? { url: customUrl } : {}),
+      ...(provider ? { provider } : {}),
+    });
     if (result.ok) {
       syncRoomLocks();
       result.warning = await publishAndWatch(result.room, project);

package/cli/graph.js

@@ -264,6 +264,14 @@ function seed(target) {
 
 async function graph(args) {
   const [sub, arg] = args;
+  // `relay graph seed --help` must not seed a project called "--help".
+  if (args.some((a) => a === "--help" || a === "-h")) return help();
+  if (arg && arg.startsWith("-")) {
+    console.error(`unknown option ${arg}`);
+    help();
+    process.exitCode = 1;
+    return;
+  }
   if (sub === "up") return up();
   if (sub === "enable") return enable(arg);
   if (sub === "disable") return disable();

package/cli/relay.js

@@ -1,7 +1,7 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 const fs = require("fs");
 const path = require("path");
-const { spawn } = require("child_process");
+const { spawn, spawnSync } = require("child_process");
 
 const root = path.join(__dirname, "..");
 const cmd = process.argv[2] || "help";
@@ -16,9 +16,9 @@ function help() {
   relay clone <url> [dir]  git clone + register workspace + install agent hooks
   relay add <path>         Attach an existing local repo
   relay init [path]        Wire hooks, MCP, and relay-os instructions (default: cwd)
-  relay serve              Start API on 127.0.0.1:3001 and Mission Control on :3002
+  relay serve              Start the API and Mission Control on 127.0.0.1:3001 (prebuilt UI, fast start)
   relay serve --no-ui      Start API + coordinator only
-  relay serve --static     Serve the prebuilt Mission Control from the API port (default for npm installs)
+  relay serve --dev        Run Mission Control with next dev on :3002 (hot reload, slow first load)
   relay push               Send your dirty working-tree files to the shared room
   relay pull               Apply the host's current dirty files onto this clone
   relay status             Health check
@@ -65,18 +65,73 @@ async function waitForApi(url, ms = 30000) {
   return false;
 }
 
+function newestMtime(dir) {
+  let newest = 0;
+  let entries = [];
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return 0;
+  }
+  for (const entry of entries) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) newest = Math.max(newest, newestMtime(full));
+    else newest = Math.max(newest, fs.statSync(full).mtimeMs);
+  }
+  return newest;
+}
+
+/** True when there is no prebuilt UI, or the UI source changed after it was built. */
+function staticUiStale() {
+  const ui = path.join(root, "mission-control");
+  const index = path.join(ui, "out", "index.html");
+  if (!fs.existsSync(index)) return true;
+  const builtAt = fs.statSync(index).mtimeMs;
+  const sources = ["app", "components", "lib", "styles", "public"].map((d) => newestMtime(path.join(ui, d)));
+  for (const f of ["next.config.js", "package.json"]) {
+    try {
+      sources.push(fs.statSync(path.join(ui, f)).mtimeMs);
+    } catch {
+      /* optional */
+    }
+  }
+  return Math.max(...sources) > builtAt;
+}
+
+/** Old bookmarks, docs and invite links point at :3002 — send them to the real UI. */
+function redirectOldUiPort(uiPort, uiOrigin) {
+  const http = require("http");
+  const server = http.createServer((req, res) => {
+    res.writeHead(302, { Location: `${uiOrigin}${req.url || "/"}` });
+    res.end();
+  });
+  server.on("error", () => {
+    /* port busy — nothing to redirect */
+  });
+  server.listen(Number(uiPort), "127.0.0.1");
+  server.unref();
+}
+
 async function serve(args) {
   const noUi = args.includes("--no-ui");
-  const forwarded = args.filter((a) => a !== "--no-ui" && a !== "--static");
+  const dev = args.includes("--dev");
+  const forwarded = args.filter((a) => !["--no-ui", "--static", "--dev"].includes(a));
   const uiPort = process.env.RELAY_UI_PORT || "3002";
   const port = apiPort(forwarded);
   const apiOrigin = `http://127.0.0.1:${port}`;
   const children = [];
-  // An npm install ships Mission Control prebuilt (mission-control/out) and no Next.js,
-  // so the API serves the UI itself; a source checkout runs `next dev` as before.
+  // Mission Control is served prebuilt (mission-control/out) from the API port:
+  // `next dev` compiles the whole UI on first page load, which is a long blank
+  // wait. An npm install ships the build; a source checkout rebuilds it only when
+  // the UI source is newer. `--dev` keeps hot reload for working on the UI.
   const nextBin = path.join(root, "node_modules", "next", "dist", "bin", "next");
+  if (!noUi && !dev && fs.existsSync(nextBin) && staticUiStale()) {
+    console.log("[relay] building Mission Control (once, after UI changes)…");
+    const built = spawnSync(process.execPath, [path.join(root, "scripts", "build-ui.js")], { stdio: "inherit", cwd: root });
+    if (built.status !== 0) console.error("[relay] UI build failed — falling back to `next dev`");
+  }
   const hasStaticUi = fs.existsSync(path.join(root, "mission-control", "out", "index.html"));
-  const staticUi = !noUi && hasStaticUi && (args.includes("--static") || !fs.existsSync(nextBin));
+  const staticUi = !noUi && !dev && hasStaticUi;
   const uiOrigin = staticUi ? `http://localhost:${port}` : `http://localhost:${uiPort}`;
 
   const api = spawn(process.execPath, [path.join(root, "backend", "server.js"), ...forwarded], {
@@ -106,6 +161,7 @@ async function serve(args) {
   });
 
   if (staticUi) {
+    redirectOldUiPort(uiPort, uiOrigin);
     if (await waitForApi(`${apiOrigin}/api/health`)) console.log(`[relay] Mission Control → ${uiOrigin}`);
   } else if (!noUi) {
     if (!fs.existsSync(nextBin)) {