relaybrain 0.0.0-stage → 0.2.0

package/cli/graph.js

@@ -0,0 +1,278 @@
+// `relay graph …`: run, enable and inspect the FalkorDB memory graph without env vars.
+const fs = require("fs");
+const path = require("path");
+const { spawn, spawnSync } = require("child_process");
+const { readConfig, saveFileConfig, clearFileConfig, loadFileConfig, configPath, validUrl } = require("../backend/lib/falkor/config");
+
+const root = path.join(__dirname, "..");
+const compose = path.join(root, "docker-compose.falkor.yml");
+const DEFAULT_URL = "falkor://127.0.0.1:6379";
+
+function api() {
+  return `http://127.0.0.1:${Number(process.env.RELAY_PORT || 3001)}`;
+}
+
+function mask(url) {
+  return url ? url.replace(/\/\/[^@/]*@/, "//***@") : url;
+}
+
+async function getJson(url, init) {
+  const r = await fetch(url, { ...init, signal: AbortSignal.timeout(6000) });
+  return r.json();
+}
+
+function help() {
+  console.log(`relay graph: the FalkorDB memory graph
+
+  relay graph up                 Start FalkorDB in Docker (docker-compose.falkor.yml)
+  relay graph enable [url]       Save the FalkorDB URL (default ${DEFAULT_URL}) and switch a running relay on
+  relay graph disable            Turn the graph off (takes effect on the next relay serve)
+  relay graph status             Config, connection and per-project ingest state
+  relay graph stats [id|all]     Node/edge counts per label, memory usage, and turn time range
+  relay graph rebuild [id|all]   Rebuild a project's graph from its relay history (default: all)
+  relay graph seed [id]          Seed a realistic 5-agent coordination graph for live demos
+`);
+}
+
+function up() {
+  const docker = spawnSync("docker", ["info", "--format", "{{.ServerVersion}}"], { encoding: "utf8", windowsHide: true });
+  if (docker.error || docker.status !== 0) {
+    console.error("Docker is not running. Start Docker Desktop (or the docker daemon), then run `relay graph up` again.");
+    console.error(`Or run FalkorDB yourself and point relay at it: relay graph enable falkor://host:port`);
+    process.exitCode = 1;
+    return;
+  }
+  const r = spawnSync("docker", ["compose", "-f", compose, "up", "-d"], { stdio: "inherit", windowsHide: true });
+  if (r.status !== 0) {
+    process.exitCode = r.status || 1;
+    return;
+  }
+  console.log(`\nFalkorDB is up on ${DEFAULT_URL} (browser UI: http://localhost:3010).`);
+  console.log("Next: relay graph enable");
+}
+
+async function probe(url) {
+  const { FalkorDB } = require("falkordb");
+  const db = await Promise.race([
+    FalkorDB.connect({ url, socket: { connectTimeout: 3000, reconnectStrategy: false } }),
+    new Promise((_, reject) => setTimeout(() => reject(new Error("timed out")), 4000)),
+  ]);
+  try {
+    db.on?.("error", () => undefined);
+    return await db.list();
+  } finally {
+    await db.close().catch(() => undefined);
+  }
+}
+
+async function enable(url) {
+  const target = (url || "").trim() || DEFAULT_URL;
+  if (!validUrl(target)) {
+    console.error(`Not a FalkorDB URL: ${target}  (expected falkor://[user:pass@]host:port)`);
+    process.exitCode = 1;
+    return;
+  }
+  try {
+    const graphs = await probe(target);
+    console.log(`Connected to ${mask(target)} (${graphs.length} graph(s)).`);
+  } catch (err) {
+    console.error(`Cannot reach ${mask(target)}: ${err.message || err}`);
+    console.error("Start it with `relay graph up`, or pass the right URL. Saving anyway.");
+  }
+  let running = false;
+  try {
+    const body = await getJson(`${api()}/api/graph/enable`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ url: target }),
+    });
+    running = true;
+    if (!body.ok) console.error(`relay serve refused: ${body.reason}`);
+    else console.log(body.note || body.warning || "relay serve: memory graph is on.");
+  } catch {
+    saveFileConfig({ ...(loadFileConfig() || {}), url: target });
+  }
+  console.log(`Saved to ${configPath()}.`);
+  if (!running) console.log("Start relay (`relay serve`) and it will use the graph.");
+  const env = readConfig();
+  if (env.source === "env") console.log(`Note: RELAY_FALKOR_URL is set in this shell and overrides the saved URL.`);
+}
+
+function disable() {
+  const cfg = loadFileConfig();
+  if (!cfg) {
+    console.log("No saved graph config. (If RELAY_FALKOR_URL is set in your shell, unset it.)");
+    return;
+  }
+  clearFileConfig();
+  console.log(`Removed ${configPath()}. Restart relay serve to stop using the graph.`);
+}
+
+async function status() {
+  const cfg = readConfig();
+  console.log(`config: ${cfg.url ? `${mask(cfg.url)} (from ${cfg.source})` : "none — run `relay graph enable`"}`);
+  console.log(`file:   ${configPath()}${fs.existsSync(configPath()) ? "" : " (not present)"}`);
+  let health = null;
+  try {
+    health = await getJson(`${api()}/api/graph/health`);
+  } catch {
+    console.log("relay:  not running on " + api());
+  }
+  if (health) {
+    const b = health.breaker;
+    // Breaker states, in plain words: "closed" is the healthy one.
+    const conn = !b ? "" : b.state === "closed" ? ", connected" : b.state === "open" ? ", FalkorDB unreachable (retrying)" : ", reconnecting";
+    console.log(`relay:  graph ${health.running ? "running" : "off"}${conn}${b?.lastError && b.state !== "closed" ? ` (${b.lastError})` : ""}`);
+    const projects = Object.entries(health.projects || {});
+    if (!projects.length) console.log("        no project ingested yet in this process");
+    for (const [id, p] of projects) {
+      const when = p.lastIngestAt ? new Date(p.lastIngestAt).toLocaleString() : "never";
+      console.log(`        ${id}: last ingest ${when}${p.needsRebuild ? ", NEEDS REBUILD (relay graph rebuild)" : ""}${p.lastError ? `, error: ${p.lastError}` : ""}`);
+    }
+  }
+  if (cfg.url) {
+    try {
+      const graphs = await probe(cfg.url);
+      console.log(`db:     reachable, ${graphs.length} graph(s): ${graphs.slice(0, 8).join(", ")}${graphs.length > 8 ? ", …" : ""}`);
+    } catch (err) {
+      console.log(`db:     unreachable (${err.message || err}). Try \`relay graph up\`.`);
+      process.exitCode = 1;
+    }
+  }
+}
+
+function rebuild(target) {
+  const cfg = readConfig();
+  if (!cfg.url) {
+    console.error("No FalkorDB configured. Run `relay graph enable` first.");
+    process.exitCode = 1;
+    return Promise.resolve();
+  }
+  return new Promise((resolve) => {
+    const child = spawn(process.execPath, [path.join(root, "scripts", "falkor-rebuild.js"), target || "all"], {
+      stdio: "inherit",
+      env: { ...process.env, RELAY_FALKOR_URL: cfg.url },
+      windowsHide: true,
+    });
+    child.on("exit", (code) => {
+      process.exitCode = code || 0;
+      resolve();
+    });
+  });
+}
+
+async function stats(target) {
+  const cfg = readConfig();
+  if (!cfg.url) {
+    console.error("No FalkorDB configured. Run `relay graph enable` first.");
+    process.exitCode = 1;
+    return;
+  }
+  const { FalkorClient } = require("../backend/lib/falkor/client");
+  const { loadRegistry } = require("../backend/lib/store");
+  const client = new FalkorClient(cfg);
+  try {
+    const db = await client.connection();
+    const regProjects = loadRegistry().projects || [];
+    let selected = target && target !== "all"
+      ? regProjects.filter((p) => p.id === target || p.name === target)
+      : [...regProjects];
+    if (!selected.length && target && target !== "all") {
+      selected = [{ id: target, name: target }];
+    }
+    if (!selected.length) {
+      const prefix = cfg.prefix || "relay_";
+      const allGraphs = (await db.list()).filter((g) => g.startsWith(prefix));
+      selected = allGraphs.map((g) => ({ id: g.slice(prefix.length), name: g.slice(prefix.length) }));
+    }
+    if (!selected.length) {
+      console.log("No matching registered projects or FalkorDB graphs.");
+      return;
+    }
+    for (const p of selected) {
+      const gName = client.graphName(p.id);
+      console.log(`\n${p.name} (${p.id}) -> graph ${gName}`);
+      try {
+        const nodes = await client.read(p.id, "MATCH (n) RETURN labels(n)[0] AS label, count(n) AS count ORDER BY count DESC");
+        const edges = await client.read(p.id, "MATCH ()-[r]->() RETURN type(r) AS type, count(r) AS count ORDER BY count DESC");
+        const span = await client.read(
+          p.id,
+          "MATCH (t:Turn) RETURN min(t.ts) AS oldest, max(t.ts) AS newest, count(t.text) AS withText, count(t) AS total"
+        );
+        const meta = await client.read(
+          p.id,
+          "MATCH (m:Meta {key:'meta'}) RETURN m.schemaVersion AS s, m.ingestVersion AS i, coalesce(m.migrations, []) AS migs, m.lastIngestAt AS lastIngestAt"
+        );
+        let memBytes = null;
+        try {
+          const g = db.selectGraph(gName);
+          if (typeof g.memoryUsage === "function") {
+            const mem = await g.memoryUsage();
+            memBytes = Array.isArray(mem) ? mem[1] : mem?.total_graph_sz_mb || mem;
+          }
+        } catch {
+          /* GRAPH.MEMORY USAGE optional on some server builds */
+        }
+        const nodeStr = nodes.map((r) => `${r.label}:${r.count}`).join("  ") || "empty";
+        const edgeStr = edges.map((r) => `${r.type}:${r.count}`).join("  ") || "none";
+        console.log(`  nodes:      ${nodeStr}`);
+        console.log(`  edges:      ${edgeStr}`);
+        if (span[0]?.total) {
+          const oldest = span[0].oldest ? new Date(Number(span[0].oldest)).toISOString() : "n/a";
+          const newest = span[0].newest ? new Date(Number(span[0].newest)).toISOString() : "n/a";
+          console.log(`  turns:      ${span[0].withText}/${span[0].total} with text (${oldest} .. ${newest})`);
+        }
+        if (meta[0]) {
+          console.log(`  schema:     v${meta[0].s} (ingest v${meta[0].i}), migrations: ${(meta[0].migs || []).join(", ") || "none"}`);
+        }
+        if (memBytes != null) {
+          console.log(`  memory:     ${typeof memBytes === "number" ? `${(memBytes / 1024).toFixed(1)} KB` : JSON.stringify(memBytes)}`);
+        }
+      } catch (err) {
+        console.log(`  (no graph or unreachable: ${err.message || err})`);
+      }
+    }
+  } catch (err) {
+    console.error(`Cannot connect to FalkorDB at ${mask(cfg.url)}: ${err.message || err}`);
+    process.exitCode = 1;
+  } finally {
+    await client.close();
+  }
+}
+
+function seed(target) {
+  const cfg = readConfig();
+  if (!cfg.url) {
+    console.error("No FalkorDB configured. Run `relay graph enable` first.");
+    process.exitCode = 1;
+    return Promise.resolve();
+  }
+  return new Promise((resolve) => {
+    const args = [path.join(root, "scripts", "falkor-seed-demo.js")];
+    if (target) args.push(target);
+    const child = spawn(process.execPath, args, {
+      stdio: "inherit",
+      env: { ...process.env, RELAY_FALKOR_URL: cfg.url },
+      windowsHide: true,
+    });
+    child.on("exit", (code) => {
+      process.exitCode = code || 0;
+      resolve();
+    });
+  });
+}
+
+async function graph(args) {
+  const [sub, arg] = args;
+  if (sub === "up") return up();
+  if (sub === "enable") return enable(arg);
+  if (sub === "disable") return disable();
+  if (sub === "status") return status();
+  if (sub === "stats") return stats(arg);
+  if (sub === "rebuild") return rebuild(arg);
+  if (sub === "seed") return seed(arg);
+  help();
+  if (sub && sub !== "help") process.exitCode = 1;
+}
+
+module.exports = { graph };

package/cli/relay.js

@@ -0,0 +1,419 @@
+#!/usr/bin/env node
+const fs = require("fs");
+const path = require("path");
+const { spawn } = require("child_process");
+
+const root = path.join(__dirname, "..");
+const cmd = process.argv[2] || "help";
+const rest = process.argv.slice(3);
+
+function help() {
+  console.log(`Relay — GitHub Desktop for AI agents
+
+  relay login              Sign in with GitHub (uses gh CLI, or device flow if GITHUB_CLIENT_ID is set)
+  relay logout             Clear the local session
+  relay whoami             Show the signed-in GitHub user
+  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 --no-ui      Start API + coordinator only
+  relay serve --static     Serve the prebuilt Mission Control from the API port (default for npm installs)
+  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
+  relay mcp-url            Print the MCP config for this room's shared context endpoint
+  relay doctor             Why the Coordinator board is empty (run it on the machine that sees nothing)
+  relay graph <cmd>        Memory graph (FalkorDB): up | enable [url] | disable | status | stats | rebuild [id|all]
+`);
+}
+
+function killTree(child) {
+  if (!child?.pid) return;
+  try {
+    if (process.platform === "win32") {
+      spawn("taskkill", ["/pid", String(child.pid), "/t", "/f"], {
+        stdio: "ignore",
+        windowsHide: true,
+        shell: false,
+      });
+    } else {
+      child.kill("SIGTERM");
+    }
+  } catch {
+    /* already gone */
+  }
+}
+
+function apiPort(args) {
+  const idx = args.indexOf("--port");
+  if (idx >= 0) return Number(args[idx + 1]);
+  return Number(process.env.RELAY_PORT || 3001);
+}
+
+async function waitForApi(url, ms = 30000) {
+  const start = Date.now();
+  while (Date.now() - start < ms) {
+    try {
+      const r = await fetch(url);
+      if (r.ok) return true;
+    } catch {
+      /* still booting */
+    }
+    await new Promise((resolve) => setTimeout(resolve, 200));
+  }
+  return false;
+}
+
+async function serve(args) {
+  const noUi = args.includes("--no-ui");
+  const forwarded = args.filter((a) => a !== "--no-ui" && a !== "--static");
+  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.
+  const nextBin = path.join(root, "node_modules", "next", "dist", "bin", "next");
+  const hasStaticUi = fs.existsSync(path.join(root, "mission-control", "out", "index.html"));
+  const staticUi = !noUi && hasStaticUi && (args.includes("--static") || !fs.existsSync(nextBin));
+  const uiOrigin = staticUi ? `http://localhost:${port}` : `http://localhost:${uiPort}`;
+
+  const api = spawn(process.execPath, [path.join(root, "backend", "server.js"), ...forwarded], {
+    stdio: "inherit",
+    cwd: root,
+    windowsHide: false,
+    shell: false,
+    env: {
+      ...process.env,
+      RELAY_PORT: String(port),
+      RELAY_UI_ORIGIN: process.env.RELAY_UI_ORIGIN || uiOrigin,
+    },
+  });
+  children.push(api);
+
+  let shuttingDown = false;
+  function shutdown(code = 0) {
+    if (shuttingDown) return;
+    shuttingDown = true;
+    for (const child of children) killTree(child);
+    process.exit(code);
+  }
+  process.on("SIGINT", () => shutdown(0));
+  process.on("SIGTERM", () => shutdown(0));
+  api.on("exit", (code) => {
+    if (!shuttingDown) shutdown(code || 0);
+  });
+
+  if (staticUi) {
+    if (await waitForApi(`${apiOrigin}/api/health`)) console.log(`[relay] Mission Control → ${uiOrigin}`);
+  } else if (!noUi) {
+    if (!fs.existsSync(nextBin)) {
+      console.error("Mission Control is not installed — run npm install");
+      shutdown(1);
+      return;
+    }
+    const ready = await waitForApi(`${apiOrigin}/api/health`);
+    if (!ready) {
+      console.error("[relay] API did not become ready on", apiOrigin);
+      shutdown(1);
+      return;
+    }
+    const ui = spawn(process.execPath, [nextBin, "dev", "--port", String(uiPort)], {
+      stdio: "inherit",
+      cwd: path.join(root, "mission-control"),
+      windowsHide: false,
+      shell: false,
+      env: {
+        ...process.env,
+        NEXT_PUBLIC_RELAY_API: apiOrigin,
+      },
+    });
+    children.push(ui);
+    ui.on("exit", (code) => {
+      if (!shuttingDown) shutdown(code || 0);
+    });
+  }
+}
+
+/**
+ * Walks the exact chain the Coordinator board depends on and says which link is
+ * broken. Locks and the board are different subsystems — a hook claims straight
+ * against the host over HTTP, while the board is fed by the lock mirror and SSE
+ * — so "locking works but I see nothing" is a normal, and otherwise invisible,
+ * way for this to fail.
+ */
+async function doctor() {
+  const api = `http://127.0.0.1:${apiPort(rest)}`;
+  const ok = (m) => console.log(`  ok    ${m}`);
+  const bad = (m) => console.log(`  BROKE ${m}`);
+  const info = (m) => console.log(`        ${m}`);
+
+  console.log("relay doctor — room + Coordinator board\n");
+  let hostLockCount = 0;
+
+  let health;
+  try {
+    health = await fetch(`${api}/api/health`).then((r) => r.json());
+    ok(`local API on ${api}`);
+  } catch {
+    bad(`no local API on ${api} — run \`relay serve\` here`);
+    process.exitCode = 1;
+    return;
+  }
+
+  try {
+    const g = await fetch(`${api}/api/graph/health`).then((r) => r.json());
+    if (!g.running) info("memory graph off — `relay graph up && relay graph enable` to turn it on");
+    else if (g.breaker?.state === "closed") ok(`memory graph connected (${g.url})`);
+    else bad(`memory graph cannot reach FalkorDB at ${g.url}${g.breaker?.lastError ? ` (${g.breaker.lastError})` : ""} — \`relay graph status\``);
+  } catch {
+    info("memory graph status unavailable (older relay serve?)");
+  }
+
+  const room = health.room;
+  if (!room?.url) {
+    info("no room joined on this machine — the board shows only local agents.");
+    info("Host: Team tab -> Invite next to a teammate. Guest: Join on the Team tab.");
+    return;
+  }
+  ok(`room joined as ${room.role} -> ${room.url}`);
+  if (room.role === "host") {
+    info(`sharing ${room.hostProjectName || "?"} (${room.hostWorkspacePath || "?"})`);
+    info("A host reads its own lock table, so the board is local by definition.");
+  }
+
+  if (room.role === "guest") {
+    if (!room.hostProjectId) {
+      bad("room.json has no hostProjectId — the lock mirror never starts, so the");
+      info("board stays empty even while your locks work. Re-join with the invite link.");
+    } else {
+      ok(`mirroring host project ${room.hostProjectId}`);
+    }
+    const token = require("../backend/lib/room").loadRoom()?.memberToken;
+    const hit = async (p) => {
+      const r = await fetch(`${String(room.url).replace(/\/$/, "")}${p}`, {
+        headers: {
+          "ngrok-skip-browser-warning": "relay",
+          ...(token ? { "x-relay-room-token": token } : {}),
+        },
+        signal: AbortSignal.timeout(6000),
+      });
+      if (!r.ok) throw new Error(`${r.status}`);
+      return r.json();
+    };
+    try {
+      await hit("/api/health");
+      ok("host answers through the tunnel");
+    } catch (err) {
+      bad(`cannot reach the host (${err.message}) — board falls back to local locks`);
+      info("Host is unreachable — Relay will look up their current tunnel and reconnect.");
+    }
+    try {
+      const remote = await hit(`/api/locks?projectId=${encodeURIComponent(room.hostProjectId || "")}`);
+      hostLockCount = (remote.locks || []).length;
+      ok(`host reports ${hostLockCount} lock(s) for the shared project`);
+    } catch (err) {
+      bad(`host refused /api/locks (${err.message})` + (token ? "" : " — no member token stored"));
+    }
+  }
+
+  // The mirror polls on its own clock, so a lock claimed a moment ago has not
+  // necessarily landed yet. Give it a few beats before calling anything broken.
+  let mine = await fetch(`${api}/api/locks`).then((r) => r.json());
+  for (let i = 0; i < 8 && hostLockCount > 0 && !(mine.locks || []).length; i += 1) {
+    await new Promise((r) => setTimeout(r, 500));
+    mine = await fetch(`${api}/api/locks`).then((r) => r.json());
+  }
+  if (hostLockCount > 0 && !(mine.locks || []).length) {
+    bad("the host holds locks but this machine mirrors none of them.");
+    info("Locks still arbitrate correctly (hooks call the host directly); it is only");
+    info("the board that is fed by the mirror. Restart `relay serve` here — and if it");
+    info("comes back, report it: the mirror is not committing its polls.");
+  }
+
+  const localKeys = new Set(Object.values(mine.raw?.locks || {}).map((l) => `${l.filePath}::${l.agentId}`));
+  const fromHost = (mine.locks || []).filter((l) => !localKeys.has(`${l.filePath}::${l.agentId}`));
+  console.log("");
+  console.log(`  board would render ${(mine.locks || []).length} lock(s):`);
+  info(`${fromHost.length} mirrored from the room, ${localKeys.size} claimed on this machine`);
+  for (const l of mine.locks || []) {
+    info(`${l.filePath}  ${l.holder?.login ? "@" + l.holder.login : l.agentId}  ${l.mode || "write"}`);
+  }
+  if (!(mine.locks || []).length) {
+    console.log("");
+    info("Nothing is locked anywhere right now — an empty board here is correct.");
+    info("Have someone start an agent edit, then run this again.");
+  }
+}
+
+async function main() {
+  if (cmd === "help" || cmd === "-h" || cmd === "--help") {
+    help();
+    return;
+  }
+  if (cmd === "doctor") {
+    await doctor();
+    return;
+  }
+  if (cmd === "graph") {
+    await require("./graph").graph(rest);
+    return;
+  }
+  if (cmd === "serve") {
+    await serve(rest);
+    return;
+  }
+  if (cmd === "push" || cmd === "pull") {
+    try {
+      const r = await fetch(`http://127.0.0.1:3001/api/${cmd}`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: "{}",
+      });
+      const body = await r.json();
+      if (!r.ok) {
+        console.error(body.hint || body.error || `${cmd} failed`);
+        process.exitCode = 1;
+        return;
+      }
+      const files = body.files || [];
+      console.log(files.length ? `${cmd} ${files.length} file(s)` : `${cmd}: nothing to ${cmd}`);
+      for (const file of files) console.log(`  ${file}`);
+    } catch {
+      console.error("offline — run relay serve");
+      process.exitCode = 1;
+    }
+    return;
+  }
+
+  if (cmd === "status") {
+    try {
+      const r = await fetch("http://127.0.0.1:3001/api/health");
+      console.log(JSON.stringify(await r.json(), null, 2));
+    } catch {
+      console.error("offline — run relay serve");
+      process.exitCode = 1;
+    }
+    return;
+  }
+
+  const gh = require("../backend/lib/githubLogin");
+  const clone = require("../backend/lib/cloneRepo");
+
+  if (cmd === "whoami") {
+    const { user, session } = gh.whoami();
+    if (!user) {
+      console.log("not signed in — run relay login");
+      process.exitCode = 1;
+      return;
+    }
+    console.log(`${user.name} (@${user.login})`);
+    if (session.projectId) console.log(`project ${session.projectId}`);
+    return;
+  }
+
+  if (cmd === "logout") {
+    gh.logout();
+    console.log("signed out");
+    return;
+  }
+
+  if (cmd === "login") {
+    try {
+      const user = await gh.loginFromGh();
+      console.log(`signed in as ${user.name} (@${user.login}) via GitHub CLI`);
+      return;
+    } catch (err) {
+      if (process.env.GITHUB_CLIENT_ID) {
+        const device = await gh.loginDeviceFlow();
+        console.log(`Open ${device.verification_uri} and enter code: ${device.user_code}`);
+        const user = await gh.pollDevice(device);
+        console.log(`signed in as ${user.name} (@${user.login})`);
+        return;
+      }
+      console.error(err.message || err);
+      console.error("Install GitHub CLI and run: gh auth login");
+      console.error("Or set GITHUB_CLIENT_ID / GITHUB_CLIENT_SECRET and use Mission Control → Continue with GitHub.");
+      process.exitCode = 1;
+    }
+    return;
+  }
+
+  if (cmd === "clone") {
+    const url = rest[0];
+    const dir = rest[1];
+    const { project, path: dest } = await clone.cloneRepo(url, dir);
+    console.log(`cloned ${url}`);
+    console.log(`workspace ${dest}`);
+    console.log(`registered ${project.name} (${project.id})`);
+    return;
+  }
+
+  if (cmd === "add") {
+    const project = clone.addLocal(rest[0], rest[1]);
+    console.log(`added ${project.path} as ${project.name}`);
+    return;
+  }
+
+  if (cmd === "init") {
+    const target = path.resolve(rest[0] || process.cwd());
+    if (!fs.existsSync(target)) {
+      console.error(`path not found: ${target}`);
+      process.exitCode = 1;
+      return;
+    }
+    const { installProjectHooks, installGlobalHooks } = require("../backend/lib/installHooks");
+    try {
+      installProjectHooks(target);
+      installGlobalHooks();
+      const existing = clone.addLocal(target, path.basename(target));
+      console.log(`Relay initialized in ${existing.path}`);
+      console.log("Hooks + MCP wired for Cursor, Claude Code, Codex, Copilot CLI, Antigravity.");
+      console.log("Run `relay serve`, then say `/relay ask` in any agent — it calls MCP relay_room_brief.");
+    } catch (err) {
+      console.error(err.message || err);
+      process.exitCode = 1;
+    }
+    return;
+  }
+
+  if (cmd === "mcp-url") {
+    const room = require("../backend/lib/room").loadRoom();
+    if (!room?.url) {
+      console.log("Not in a room. `relay serve`, then Share in Mission Control, or join with an invite link.");
+      console.log("Locally your agents already reach relay over stdio — nothing to configure.");
+      process.exitCode = 1;
+      return;
+    }
+    const config = {
+      mcpServers: {
+        "relay-room": {
+          type: "http",
+          url: `${String(room.url).replace(/\/$/, "")}/mcp`,
+          headers: {
+            "ngrok-skip-browser-warning": "relay",
+            ...(room.memberToken ? { "x-relay-room-token": room.memberToken } : {}),
+          },
+        },
+      },
+    };
+    console.log(`Room MCP endpoint (${room.role}) — read-only for anyone off this machine.\n`);
+    console.log(JSON.stringify(config, null, 2));
+    console.log(`\nPaste into the agent's MCP config. It exposes the room's context (chat history,
+recent edits, locks, conflicts) to any MCP client — including one on a machine
+with no relay installed. Locks and other writes stay on each member's own relay.`);
+    if (!room.memberToken && room.role === "guest") {
+      console.log("\nNo member token on file — if the host made the room invite-only, re-join with the invite link.");
+    }
+    return;
+  }
+
+  help();
+  process.exitCode = 1;
+}
+
+main().catch((err) => {
+  console.error(err.message || err);
+  process.exit(1);
+});