@maintainer-pro/ai-bridge 0.1.0 → 0.1.2

package/src/daemon.mjs

@@ -7,18 +7,20 @@
  *   npx @maintainer-pro/ai-bridge
  *   npx @maintainer-pro/ai-bridge --admin-url https://… --pair ABCD-EF01
  */
-import { spawn, execFileSync } from "node:child_process";
+import { spawn } from "node:child_process";
 import { randomBytes } from "node:crypto";
 import fs from "node:fs";
 import http from "node:http";
+import net from "node:net";
 import os from "node:os";
 import path from "node:path";
 import readline from "node:readline";
-import { fileURLToPath } from "node:url";
+import { fileURLToPath, pathToFileURL } from "node:url";
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const PACKAGE_VERSION = readPackageVersion();
 const HEARTBEAT_MS = 15_000;
+const ACTION_POLL_MS = 2_000;
 
 const log = (msg) => console.log(`[bridge] ${msg}`);
 const warn = (msg) => console.warn(`[bridge] ${msg}`);
@@ -85,7 +87,7 @@ Flags:
   --pair <code>           Claim a pair code from admin → Bridges page
   --admin-url <url>       Maintainer Pro base URL (required for first pair)
   --offer-folder <path>   Suggest this folder in admin (repeatable via config)
-  --no-ai-server          Do not start sidecars for workspaces
+  --no-ai-server          Do not open ai-server terminals for workspaces
   --help
 `);
 }
@@ -161,26 +163,161 @@ async function api(baseUrl, token, method, pathname, body) {
   return data;
 }
 
-function commandExists(cmd) {
+/** @type {Promise<typeof import("@maintainer-pro/ai-cli")> | null} */
+let aiCliModule = null;
+
+async function loadAiCli() {
+  if (!aiCliModule) {
+    aiCliModule = (async () => {
+      try {
+        return await import("@maintainer-pro/ai-cli");
+      } catch {
+        const local = path.resolve(__dirname, "..", "..", "ai-cli", "dist", "index.js");
+        if (fs.existsSync(local)) {
+          return await import(pathToFileURL(local).href);
+        }
+        throw new Error("@maintainer-pro/ai-cli is not installed");
+      }
+    })();
+  }
+  return aiCliModule;
+}
+
+async function detectCliProviders() {
   try {
-    if (process.platform === "win32") {
-      execFileSync("where", [cmd], { stdio: "ignore" });
+    const { resolveProvider } = await loadAiCli();
+    const provider = await resolveProvider({ preference: "auto" });
+    return [provider.id];
+  } catch {
+    return [];
+  }
+}
+
+function applyProjectInfo(ws, info, cfg) {
+  if (!ws || !info) return;
+  ws.projectInfo = {
+    kind: info.kind,
+    name: info.name,
+    summary: info.summary,
+    scripts: info.scripts || {},
+    ports: info.ports || {},
+    issues: info.issues || [],
+    fixes: info.fixes || [],
+    ready: Boolean(info.ready),
+    provider: info.provider,
+  };
+  if (info.kind) ws.clientKind = info.kind;
+  const uiPort = Number(info.ports?.ui || info.ports?.app);
+  if (
+    uiPort &&
+    (!ws.appUrl || isLocalAppUrl(ws.appUrl))
+  ) {
+    ws.appUrl = urlWithPort(ws.appUrl || `http://localhost:${uiPort}`, uiPort);
+  }
+  persistWorkspaceEntry(cfg, ws);
+}
+
+async function inspectProjectWithAiCli(ws, opts = {}) {
+  const folder = path.resolve(ws.folderPath || "");
+  const label = ws.sandboxName || ws.applicationName || "this sandbox";
+  try {
+    const { inspectAndRepairWorkspace } = await loadAiCli();
+    log(`asking ai-cli to inspect ${folder}`);
+    const info = await inspectAndRepairWorkspace({
+      workspaceDir: folder,
+      appName: ws.applicationName || ws.sandboxName || undefined,
+      problem: opts.problem,
+      extraContext: opts.extraContext,
+    });
+    applyProjectInfo(ws, info, opts.cfg);
+    if (info.issues?.length) {
+      recordProcessProblem({
+        sandboxId: ws.sandboxId,
+        code: "project_issue",
+        role: "inspect",
+        title: `Project needs attention (${label})`,
+        message: info.issues.join(" "),
+        resolution: info.fixes?.length
+          ? info.fixes.join(" ")
+          : "Fix the project in that folder, then use Start chat server.",
+      });
     } else {
-      execFileSync("which", [cmd], { stdio: "ignore" });
+      clearProcessProblem(ws.sandboxId, "project_issue", "inspect");
     }
-    return true;
+    if (info.summary) log(`ai-cli: ${info.summary}`);
+    if (info.fixes?.length) log(`ai-cli fixes: ${info.fixes.join("; ")}`);
+    return info;
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    warn(`ai-cli inspect failed: ${message}`);
+    recordProcessProblem({
+      sandboxId: ws.sandboxId,
+      code: "project_issue",
+      role: "inspect",
+      title: `Could not inspect the project (${label})`,
+      message,
+      resolution:
+        "Install and authenticate a coding-agent CLI (agent, claude, or agy), then Check connection.",
+      actionCode: "recheck",
+    });
+    return null;
+  }
+}
+
+function isPortFree(port) {
+  return new Promise((resolve) => {
+    const server = net.createServer();
+    server.unref();
+    server.once("error", () => resolve(false));
+    server.once("listening", () => {
+      server.close(() => resolve(true));
+    });
+    server.listen(port);
+  });
+}
+
+/**
+ * Prefer `preferred` if it is free and not already reserved this launch.
+ * Walks upward so bind failures are avoided without a central port service.
+ */
+async function findFreePort(preferred = 3100, reserved = new Set()) {
+  let port = Math.max(1024, Number(preferred) || 3100);
+  while (port <= 49151) {
+    if (!reserved.has(port) && (await isPortFree(port))) {
+      reserved.add(port);
+      return port;
+    }
+    port += 1;
+  }
+  throw new Error("No free TCP port found");
+}
+
+function urlWithPort(url, port) {
+  try {
+    const parsed = new URL(url);
+    parsed.port = String(port);
+    return parsed.toString().replace(/\/$/, "");
   } catch {
-    return false;
+    return `http://localhost:${port}`;
   }
 }
 
-function detectCliProviders() {
-  /** @type {string[]} */
-  const found = [];
-  if (commandExists("agent")) found.push("agent");
-  if (commandExists("claude")) found.push("claude");
-  if (commandExists("agy")) found.push("agy");
-  return found;
+function isLocalAppUrl(url) {
+  try {
+    const host = new URL(url).hostname;
+    return host === "localhost" || host === "127.0.0.1";
+  } catch {
+    return true;
+  }
+}
+
+function persistWorkspaceEntry(cfg, ws) {
+  if (!cfg || !ws?.sandboxId) return;
+  cfg.workspaces = cfg.workspaces || [];
+  const index = cfg.workspaces.findIndex((row) => row.sandboxId === ws.sandboxId);
+  if (index >= 0) cfg.workspaces[index] = { ...cfg.workspaces[index], ...ws };
+  else cfg.workspaces.push(ws);
+  saveConfig(cfg);
 }
 
 function probeUrl(url, timeoutMs = 2500) {
@@ -207,10 +344,46 @@ function probeUrl(url, timeoutMs = 2500) {
   });
 }
 
+function listDriveRoots() {
+  if (process.platform !== "win32") return ["/"];
+  const roots = [];
+  for (const letter of "CDEFGHIJKLMNOPQRSTUVWXYZAB") {
+    const root = `${letter}:\\`;
+    try {
+      if (fs.existsSync(root)) roots.push(root);
+    } catch {
+      /* skip */
+    }
+  }
+  return roots.length ? roots : ["C:\\"];
+}
+
 function listDirEntries(dirPath) {
-  const resolved = path.resolve(dirPath);
+  const raw = String(dirPath || "").trim();
+  const home = os.homedir();
+  if (!raw || raw === "roots") {
+    const roots = listDriveRoots();
+    return {
+      path: "",
+      parent: null,
+      home,
+      entries: roots.map((root) => ({
+        name: root,
+        path: root,
+        isDir: true,
+      })),
+    };
+  }
+
+  const resolved = path.resolve(raw);
   if (!fs.existsSync(resolved) || !fs.statSync(resolved).isDirectory()) {
-    return { error: "Not a directory", path: resolved, entries: [] };
+    return {
+      error: "Not a directory",
+      path: resolved,
+      parent: path.dirname(resolved),
+      home,
+      entries: [],
+    };
   }
   const names = fs.readdirSync(resolved);
   const entries = [];
@@ -232,7 +405,13 @@ function listDirEntries(dirPath) {
     if (a.isDir !== b.isDir) return a.isDir ? -1 : 1;
     return a.name.localeCompare(b.name);
   });
-  return { path: resolved, entries: entries.slice(0, 200) };
+  const parent = path.dirname(resolved);
+  return {
+    path: resolved,
+    parent: parent === resolved ? null : parent,
+    home,
+    entries: entries.slice(0, 400),
+  };
 }
 
 function mergeEnvFile(file, values) {
@@ -256,6 +435,401 @@ function mergeEnvFile(file, values) {
   fs.writeFileSync(file, body + "\n", "utf8");
 }
 
+const IGNORE_NAMES = new Set([
+  ".git",
+  ".DS_Store",
+  "Thumbs.db",
+  "node_modules",
+  ".maintainer-pro",
+  ".maintainer-pro-bridge.json",
+  ".cloudflare-tunnel-url",
+]);
+
+function isIgnorableEntry(name) {
+  if (IGNORE_NAMES.has(name)) return true;
+  if (name.startsWith(".env")) return true;
+  return false;
+}
+
+/**
+ * Detect project shape in a folder.
+ * @returns {"empty"|"next"|"html"|"other"}
+ */
+function detectProjectKind(dir) {
+  if (!fs.existsSync(dir)) return "empty";
+  const names = fs.readdirSync(dir).filter((n) => !isIgnorableEntry(n));
+  if (names.length === 0) return "empty";
+
+  const has = (n) => names.includes(n) || fs.existsSync(path.join(dir, n));
+  if (
+    has("next.config.js") ||
+    has("next.config.mjs") ||
+    has("next.config.ts") ||
+    has("app") ||
+    has("pages")
+  ) {
+    // package.json with next is a stronger signal
+    try {
+      const pkg = JSON.parse(
+        fs.readFileSync(path.join(dir, "package.json"), "utf8")
+      );
+      if (pkg.dependencies?.next || pkg.devDependencies?.next) return "next";
+    } catch {
+      /* fall through */
+    }
+    if (has("next.config.js") || has("next.config.mjs") || has("next.config.ts")) {
+      return "next";
+    }
+  }
+
+  if (has("index.html") || has(path.join("public", "index.html"))) {
+    return "html";
+  }
+
+  // Only README / license → treat as empty scaffold target
+  const meaningful = names.filter(
+    (n) =>
+      !/^readme/i.test(n) &&
+      !/^license/i.test(n) &&
+      n !== "package.json"
+  );
+  if (meaningful.length === 0 && !has("package.json")) return "empty";
+
+  return "other";
+}
+
+function escapeHtml(value) {
+  return String(value)
+    .replaceAll("&", "&amp;")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;");
+}
+
+function emptyProjectIndexHtml(appName) {
+  return `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>${escapeHtml(appName)}</title>
+    <style>
+      body { font-family: system-ui, sans-serif; margin: 2rem; color: #1a2330; }
+      p { color: #5c6b7a; }
+    </style>
+  </head>
+  <body>
+    <h1>${escapeHtml(appName)}</h1>
+    <p>Ask the assistant to change this page.</p>
+    <script src="/embed-config.js"></script>
+    <script src="/ai-ui.iife.js"></script>
+    <script>
+      (function () {
+        var cfg = window.__MAINTAINER_PRO__ || {};
+        AiUi.init({
+          apiUrl: cfg.apiUrl || "/api/chat",
+          title: "AI Assistant",
+          maintainerProUrl: cfg.maintainerProUrl || undefined,
+          maintainerProApiKey: cfg.maintainerProApiKey || undefined,
+        });
+      })();
+    </script>
+  </body>
+</html>
+`;
+}
+
+const WIDGET_MARKER = "AiUi.init";
+
+function injectHtmlWidget(html, aiServerUrl) {
+  if (html.includes(WIDGET_MARKER) || html.includes("ai-ui.iife.js")) {
+    return { html, injected: false };
+  }
+  const snippet = `
+<script src="${aiServerUrl}/embed-config.js"></script>
+<script src="${aiServerUrl}/ai-ui.iife.js"></script>
+<script>
+  (function () {
+    var cfg = window.__MAINTAINER_PRO__ || {};
+    if (!cfg.apiUrl) {
+      console.error("Maintainer Pro: embed-config.js missing apiUrl (is ai-server running?)");
+      return;
+    }
+    AiUi.init({
+      apiUrl: cfg.apiUrl,
+      title: "AI Assistant",
+      maintainerProUrl: cfg.maintainerProUrl || undefined,
+      maintainerProApiKey: cfg.maintainerProApiKey || undefined,
+    });
+  })();
+</script>
+`;
+  if (/<\/body>/i.test(html)) {
+    return {
+      html: html.replace(/<\/body>/i, `${snippet}</body>`),
+      injected: true,
+    };
+  }
+  return { html: html + snippet, injected: true };
+}
+
+function nextWidgetComponentSource() {
+  return `"use client";
+
+import { useEffect } from "react";
+
+declare global {
+  interface Window {
+    AiUi?: { init: (opts: Record<string, unknown>) => void; destroy?: () => void };
+    __MAINTAINER_PRO__?: {
+      aiServerUrl?: string;
+      apiUrl?: string;
+      maintainerProUrl?: string;
+      maintainerProApiKey?: string;
+    };
+  }
+}
+
+const AI_SERVER_URL = (process.env.NEXT_PUBLIC_AI_SERVER_URL || "").replace(/\\/$/, "");
+
+export function MaintainerProWidget() {
+  useEffect(() => {
+    if (!AI_SERVER_URL) {
+      console.error("Set NEXT_PUBLIC_AI_SERVER_URL to the ai-server origin");
+      return;
+    }
+    let cancelled = false;
+
+    const start = (cfg: {
+      apiUrl?: string;
+      maintainerProUrl?: string;
+      maintainerProApiKey?: string;
+    }) => {
+      if (cancelled) return;
+      const AiUi = window.AiUi;
+      if (!AiUi?.init) {
+        setTimeout(() => start(cfg), 40);
+        return;
+      }
+      AiUi.init({
+        apiUrl: cfg.apiUrl || \`\${AI_SERVER_URL}/api/chat\`,
+        title: "AI Assistant",
+        maintainerProUrl: cfg.maintainerProUrl,
+        maintainerProApiKey: cfg.maintainerProApiKey,
+      });
+    };
+
+    const ensureScript = (src: string) =>
+      new Promise<void>((resolve, reject) => {
+        const existing = document.querySelector<HTMLScriptElement>(\`script[src="\${src}"]\`);
+        if (existing) {
+          if (existing.dataset.loaded === "1") resolve();
+          else existing.addEventListener("load", () => resolve(), { once: true });
+          return;
+        }
+        const script = document.createElement("script");
+        script.src = src;
+        script.async = true;
+        script.onload = () => {
+          script.dataset.loaded = "1";
+          resolve();
+        };
+        script.onerror = () => reject(new Error(\`Failed to load \${src}\`));
+        document.body.appendChild(script);
+      });
+
+    void (async () => {
+      try {
+        await ensureScript(\`\${AI_SERVER_URL}/embed-config.js\`);
+        await ensureScript(\`\${AI_SERVER_URL}/ai-ui.iife.js\`);
+        start(window.__MAINTAINER_PRO__ || {});
+      } catch (err) {
+        console.error(err);
+      }
+    })();
+
+    return () => {
+      cancelled = true;
+      window.AiUi?.destroy?.();
+    };
+  }, []);
+
+  return null;
+}
+`;
+}
+
+function tryMountNextWidget(dir) {
+  const candidates = [
+    path.join(dir, "app", "layout.tsx"),
+    path.join(dir, "app", "layout.jsx"),
+    path.join(dir, "src", "app", "layout.tsx"),
+    path.join(dir, "src", "app", "layout.jsx"),
+  ];
+  for (const layout of candidates) {
+    if (!fs.existsSync(layout)) continue;
+    let text = fs.readFileSync(layout, "utf8");
+    if (text.includes("MaintainerProWidget")) {
+      return { mounted: false, reason: "already mounted" };
+    }
+    const fromAppRoot =
+      /[/\\]app[/\\]layout\.(t|j)sx$/.test(layout) &&
+      !/[/\\]src[/\\]app[/\\]/.test(layout);
+    const imp = fromAppRoot
+      ? "../components/MaintainerProWidget"
+      : "@/components/MaintainerProWidget";
+
+    text = `import { MaintainerProWidget } from "${imp}";\n` + text;
+    if (/\{children\}/.test(text)) {
+      text = text.replace(
+        /\{children\}/,
+        "{children}\n        <MaintainerProWidget />"
+      );
+      fs.writeFileSync(layout, text, "utf8");
+      return { mounted: true, layout };
+    }
+  }
+  return { mounted: false, reason: "no layout found" };
+}
+
+/**
+ * Configure client files for a workspace.
+ */
+function configureClient(opts) {
+  const {
+    dir,
+    port,
+    appName,
+    mode, // auto | empty | existing | skip
+    hostAppUrl,
+  } = opts;
+  const aiOrigin = `http://localhost:${port}`;
+  /** @type {string[]} */
+  const notes = [];
+  /** @type {string[]} */
+  const filesWritten = [];
+
+  let kind = detectProjectKind(dir);
+  if (mode === "empty") kind = "empty";
+  if (mode === "existing") {
+    if (kind === "empty") kind = "other";
+  }
+  if (mode === "skip") {
+    return {
+      kind: "skipped",
+      notes: ["Client scaffolding skipped (manual)."],
+      filesWritten,
+      corsOrigin: hostAppUrl || null,
+      appUrl: hostAppUrl || null,
+      sameOrigin: false,
+    };
+  }
+
+  if (kind === "empty" || mode === "empty") {
+    const indexPath = path.join(dir, "index.html");
+    if (!fs.existsSync(indexPath)) {
+      fs.writeFileSync(indexPath, emptyProjectIndexHtml(appName), "utf8");
+      filesWritten.push("index.html");
+      notes.push("Created index.html (served by ai-server).");
+    } else {
+      notes.push("index.html already present.");
+    }
+    return {
+      kind: "empty",
+      notes,
+      filesWritten,
+      corsOrigin: aiOrigin,
+      appUrl: hostAppUrl || aiOrigin,
+      sameOrigin: true,
+    };
+  }
+
+  if (kind === "html") {
+    const candidates = [
+      path.join(dir, "index.html"),
+      path.join(dir, "public", "index.html"),
+    ];
+    for (const htmlPath of candidates) {
+      if (!fs.existsSync(htmlPath)) continue;
+      const raw = fs.readFileSync(htmlPath, "utf8");
+      const { html, injected } = injectHtmlWidget(raw, aiOrigin);
+      if (injected) {
+        fs.writeFileSync(htmlPath, html, "utf8");
+        filesWritten.push(path.relative(dir, htmlPath));
+        notes.push(`Injected widget into ${path.relative(dir, htmlPath)}.`);
+      } else {
+        notes.push(`Widget already present in ${path.relative(dir, htmlPath)}.`);
+      }
+      break;
+    }
+    const origin = hostAppUrl || "http://localhost:3000";
+    return {
+      kind: "html",
+      notes,
+      filesWritten,
+      corsOrigin: origin,
+      appUrl: origin,
+      sameOrigin: false,
+    };
+  }
+
+  if (kind === "next") {
+    const envLocal = path.join(dir, ".env.local");
+    mergeEnvFile(envLocal, {
+      NEXT_PUBLIC_AI_SERVER_URL: aiOrigin,
+    });
+    filesWritten.push(".env.local");
+    notes.push("Set NEXT_PUBLIC_AI_SERVER_URL in .env.local.");
+
+    const useSrc = fs.existsSync(path.join(dir, "src", "app"));
+    const compDir = useSrc
+      ? path.join(dir, "src", "components")
+      : path.join(dir, "components");
+    fs.mkdirSync(compDir, { recursive: true });
+    const widgetPath = path.join(compDir, "MaintainerProWidget.tsx");
+    if (!fs.existsSync(widgetPath)) {
+      fs.writeFileSync(widgetPath, nextWidgetComponentSource(), "utf8");
+      filesWritten.push(path.relative(dir, widgetPath));
+      notes.push("Added MaintainerProWidget.tsx.");
+    }
+    const mount = tryMountNextWidget(dir);
+    if (mount.mounted) {
+      notes.push(`Mounted widget in ${path.relative(dir, mount.layout)}.`);
+    } else {
+      notes.push(
+        "Add <MaintainerProWidget /> to your root layout if it is not mounted yet."
+      );
+    }
+    const origin = hostAppUrl || "http://localhost:3000";
+    return {
+      kind: "next",
+      notes,
+      filesWritten,
+      corsOrigin: origin,
+      appUrl: origin,
+      sameOrigin: false,
+    };
+  }
+
+  // other — write host env hints only
+  const origin = hostAppUrl || "http://localhost:3000";
+  mergeEnvFile(path.join(dir, ".env"), {
+    AI_SERVER_URL: aiOrigin,
+    NEXT_PUBLIC_AI_SERVER_URL: aiOrigin,
+  });
+  notes.push(
+    "Existing project detected. Set AI_SERVER_URL / mount the widget manually if needed."
+  );
+  return {
+    kind: "other",
+    notes,
+    filesWritten,
+    corsOrigin: origin,
+    appUrl: origin,
+    sameOrigin: false,
+  };
+}
+
 function collectOfferedFolders(cfg) {
   /** @type {string[]} */
   const folders = [];
@@ -270,26 +844,389 @@ function collectOfferedFolders(cfg) {
   return folders;
 }
 
-/** @type {Map<string, import('node:child_process').ChildProcess>} */
-const children = new Map();
+/** Prevents opening a new window on every heartbeat while a process is starting. */
+const launchedAt = new Map();
+
+/** Last process problems to send on heartbeat. Key: sandboxId::code::role */
+const processProblems = new Map();
 
-function stopChild(sandboxId) {
-  const child = children.get(sandboxId);
-  if (!child || child.killed) {
-    children.delete(sandboxId);
-    return;
+function forgetLaunch(sandboxId) {
+  for (const key of [...launchedAt.keys()]) {
+    if (key === sandboxId || key.startsWith(`${sandboxId}:`)) {
+      launchedAt.delete(key);
+    }
+  }
+  for (const key of [...processProblems.keys()]) {
+    if (key.startsWith(`${sandboxId}::`)) processProblems.delete(key);
   }
+  stopCloudflare(sandboxId);
+}
+
+function problemKey(sandboxId, code, role = "") {
+  return `${sandboxId || ""}::${code}::${role}`;
+}
+
+function clipIssueText(text, max) {
+  const value = String(text || "").trim();
+  if (value.length <= max) return value;
+  return `${value.slice(0, max - 1)}…`;
+}
+
+function processRoleLabel(role) {
+  if (role === "ui") return "app UI";
+  if (role === "backend") return "backend";
+  if (role === "ai") return "chat script";
+  return "app";
+}
+
+function recordProcessProblem(issue) {
+  const sandboxId = issue.sandboxId || "";
+  const role = issue.role || "";
+  processProblems.set(problemKey(sandboxId, issue.code, role), {
+    code: issue.code,
+    role,
+    severity: issue.severity || "error",
+    title: clipIssueText(issue.title, 200),
+    message: clipIssueText(issue.message, 2000),
+    resolution: clipIssueText(issue.resolution || "", 2000),
+    actionCode: issue.actionCode ?? "start_ai_server",
+    sandboxId: sandboxId || null,
+  });
+  warn(`${issue.title}: ${issue.message}`);
+}
+
+function clearProcessProblem(sandboxId, code, role = "") {
+  processProblems.delete(problemKey(sandboxId, code, role));
+}
+
+function issuesForSandbox(sandboxId) {
+  return [...processProblems.values()].filter(
+    (issue) => issue.sandboxId === sandboxId
+  );
+}
+
+function recentlyLaunched(launchKey) {
+  const last = launchedAt.get(launchKey) ?? 0;
+  return last > 0 && Date.now() - last < 60_000;
+}
+
+function readPackageJson(dir) {
   try {
-    child.kill("SIGTERM");
+    return JSON.parse(fs.readFileSync(path.join(dir, "package.json"), "utf8"));
   } catch {
-    /* ignore */
+    return null;
+  }
+}
+
+function isChatScript(name, command) {
+  const text = `${name} ${command}`;
+  return /\b(ai-server|ai-cli|dev:chat|start:chat)\b/i.test(text);
+}
+
+function isUiCommand(command) {
+  return /\b(vite|next|nuxt|astro|remix|react-scripts|webpack-dev-server|parcel)\b/i.test(
+    command
+  );
+}
+
+function portFromText(text, fallback) {
+  const match =
+    String(text || "").match(/--port(?:\s+|=)(\d{2,5})/i) ||
+    String(text || "").match(/\bPORT[=:]\s*(\d{2,5})/i) ||
+    String(text || "").match(/:(\d{2,5})\b/);
+  return match ? Number(match[1]) : fallback;
+}
+
+/**
+ * @returns {Array<{ role: string, script: string, command: string, preferredPort: number, probeUrl: string | null }>}
+ */
+function planHostJobs(dir, appUrl, hints = null) {
+  const pkg = readPackageJson(dir);
+  const scripts = pkg?.scripts && typeof pkg.scripts === "object" ? pkg.scripts : {};
+  const hinted = hints?.scripts && typeof hints.scripts === "object" ? hints.scripts : {};
+  const hintedPorts = hints?.ports && typeof hints.ports === "object" ? hints.ports : {};
+  const pickHint = (name) =>
+    name && scripts[name] && !isChatScript(name, scripts[name]) ? name : null;
+  const pick = (names) =>
+    names.find((name) => scripts[name] && !isChatScript(name, scripts[name]));
+
+  const uiScript =
+    pickHint(hinted.ui) ||
+    pick([
+      "dev:client",
+      "dev:ui",
+      "dev:web",
+      "dev:frontend",
+      "client",
+      "start:client",
+    ]);
+  const apiScript =
+    pickHint(hinted.backend) ||
+    pick([
+      "dev:server",
+      "dev:backend",
+      "dev:api",
+      "server",
+      "start:server",
+    ]);
+
+  /** @type {Array<{ role: string, script: string, command: string, preferredPort: number, probeUrl: string | null }>} */
+  const jobs = [];
+  const addJob = (role, script, fallbackPort, probe) => {
+    if (!script || jobs.some((job) => job.script === script)) return;
+    const port = portFromText(scripts[script] || probe, fallbackPort);
+    jobs.push({
+      role,
+      script,
+      command: `npm run ${script}`,
+      preferredPort: port,
+      probeUrl: probe || `http://127.0.0.1:${port}`,
+    });
+  };
+
+  addJob("ui", uiScript, Number(hintedPorts.ui) || 5173, appUrl || null);
+  addJob("backend", apiScript, Number(hintedPorts.backend) || 4100, null);
+  if (jobs.length === 0 && pickHint(hinted.app)) {
+    addJob(
+      isUiCommand(scripts[hinted.app]) ? "ui" : "app",
+      hinted.app,
+      Number(hintedPorts.app) || 3000,
+      appUrl || null
+    );
+  }
+
+  if (scripts.dev && !isChatScript("dev", scripts.dev)) {
+    const nested = [
+      ...String(scripts.dev).matchAll(/npm run ([a-zA-Z0-9:_-]+)/g),
+    ]
+      .map((match) => match[1])
+      .filter(
+        (name) =>
+          name !== "dev" && scripts[name] && !isChatScript(name, scripts[name])
+      );
+    if (nested.length >= 2) {
+      for (const name of nested) {
+        const role = /client|ui|web|frontend/i.test(name)
+          ? "ui"
+          : /server|backend|api/i.test(name)
+            ? "backend"
+            : name;
+        addJob(role, name, 3000, role === "ui" ? appUrl || null : null);
+      }
+    } else if (jobs.length === 0) {
+      addJob(isUiCommand(scripts.dev) ? "ui" : "app", "dev", 3000, appUrl || null);
+    }
+  }
+  return jobs;
+}
+
+function friendlyLaunchError(raw, title) {
+  const text = String(raw || "").trim();
+  if (/ENOENT/i.test(text)) {
+    return `Could not find a program to open a terminal for "${title}". ${text}`;
   }
-  children.delete(sandboxId);
+  return text || `Could not open a terminal for "${title}".`;
+}
+
+function runLauncher(command, args, extra = {}) {
+  return new Promise((resolve) => {
+    let settled = false;
+    const done = (result) => {
+      if (settled) return;
+      settled = true;
+      resolve(result);
+    };
+    let child;
+    try {
+      child = spawn(command, args, {
+        stdio: ["ignore", "pipe", "pipe"],
+        windowsHide: extra.windowsHide,
+      });
+    } catch (err) {
+      done({
+        ok: false,
+        error: err instanceof Error ? err.message : String(err),
+      });
+      return;
+    }
+    let stderr = "";
+    child.stderr.on("data", (chunk) => {
+      stderr += String(chunk);
+    });
+    child.once("error", (err) => {
+      done({ ok: false, error: err.message });
+    });
+    child.once("exit", (code) => {
+      if (code === 0 || code === null) done({ ok: true });
+      else {
+        const detail = stderr.trim().replace(/\s+/g, " ");
+        done({
+          ok: false,
+          error: detail || `${command} exited with code ${code}`,
+        });
+      }
+    });
+    child.once("spawn", () => {
+      setTimeout(() => done({ ok: true }), 400);
+    });
+  });
 }
 
-function startAiServerForWorkspace(ws) {
-  const key = ws.sandboxId;
-  if (children.has(key) && !children.get(key)?.killed) return;
+async function openInNewTerminal(opts) {
+  const { title, folder, command, env = {}, launchKey } = opts;
+  if (launchKey) {
+    if (recentlyLaunched(launchKey)) return { ok: true, skipped: true };
+    launchedAt.set(launchKey, Date.now());
+  }
+  if (!fs.existsSync(folder)) {
+    const error = `Folder is missing: ${folder}`;
+    warn(`cannot open terminal: ${error}`);
+    return { ok: false, error };
+  }
+
+  const envWin = Object.entries(env)
+    .map(([key, value]) => `set ${key}=${value}`)
+    .join("&& ");
+  const envUnix = Object.entries(env)
+    .map(([key, value]) => `export ${key}=${JSON.stringify(String(value))}`)
+    .join(" && ");
+
+  log(`opening separate terminal [${title}] in ${folder}: ${command}`);
+
+  try {
+    if (process.platform === "win32") {
+      const inner = `cd /d "${folder}" && ${envWin ? `${envWin}&& ` : ""}title ${title}&& ${command}`;
+      const escaped = inner.replace(/'/g, "''");
+      const opened = await runLauncher(
+        "powershell.exe",
+        [
+          "-NoProfile",
+          "-WindowStyle",
+          "Hidden",
+          "-Command",
+          `Start-Process -FilePath $env:ComSpec -WorkingDirectory ${JSON.stringify(folder)} -ArgumentList @('/k', '${escaped}')`,
+        ],
+        { windowsHide: true }
+      );
+      if (!opened.ok) {
+        return { ok: false, error: friendlyLaunchError(opened.error, title) };
+      }
+      return { ok: true };
+    }
+
+    const script = `cd ${JSON.stringify(folder)} && ${envUnix ? `${envUnix} && ` : ""}${command}`;
+    if (process.platform === "darwin") {
+      const opened = await runLauncher("osascript", [
+        "-e",
+        `tell application "Terminal" to do script ${JSON.stringify(script)}`,
+      ]);
+      if (!opened.ok) {
+        return { ok: false, error: friendlyLaunchError(opened.error, title) };
+      }
+      return { ok: true };
+    }
+
+    const opened = await runLauncher(process.env.TERMINAL || "x-terminal-emulator", [
+      "-e",
+      "bash",
+      "-lc",
+      `${script}; exec bash`,
+    ]);
+    if (!opened.ok) {
+      return { ok: false, error: friendlyLaunchError(opened.error, title) };
+    }
+    return { ok: true };
+  } catch (err) {
+    return {
+      ok: false,
+      error: friendlyLaunchError(
+        err instanceof Error ? err.message : String(err),
+        title
+      ),
+    };
+  }
+}
+
+function commandWithPort(job, scripts, port) {
+  const raw = String(scripts?.[job.script] || "");
+  if (
+    job.role === "ui" ||
+    job.role === "app" ||
+    isUiCommand(raw) ||
+    /--port\b/i.test(raw)
+  ) {
+    return `${job.command} -- --port ${port}`;
+  }
+  return job.command;
+}
+
+async function startAiServerForWorkspace(ws, opts = {}) {
+  const reserved = opts.reserved instanceof Set ? opts.reserved : new Set();
+  const cfg = opts.cfg || null;
+  const folder = path.resolve(ws.folderPath);
+  const preferred = Number(ws.port) || 3100;
+  const launchKey = `${ws.sandboxId}:${folder}:ai`;
+  const label = ws.sandboxName || "this sandbox";
+
+  if (!fs.existsSync(folder)) {
+    recordProcessProblem({
+      sandboxId: ws.sandboxId,
+      code: "ai_server_launch",
+      role: "ai",
+      title: `Could not start the chat script (${label})`,
+      message: `The project folder is missing: ${folder}`,
+      resolution: "Attach the folder again from Local setup.",
+    });
+    return { port: preferred, up: false, launched: false };
+  }
+
+  if (await probeUrl(`http://127.0.0.1:${preferred}/embed-config.js`)) {
+    reserved.add(preferred);
+    clearProcessProblem(ws.sandboxId, "ai_server_launch", "ai");
+    return { port: preferred, up: true, launched: false };
+  }
+
+  if (recentlyLaunched(launchKey)) {
+    reserved.add(preferred);
+    return { port: preferred, up: false, launched: false, starting: true };
+  }
+
+  let port = preferred;
+  try {
+    if (reserved.has(preferred)) {
+      if (!(await isPortFree(preferred))) {
+        reserved.delete(preferred);
+        port = await findFreePort(preferred, reserved);
+      }
+    } else {
+      port = await findFreePort(preferred, reserved);
+    }
+  } catch (err) {
+    recordProcessProblem({
+      sandboxId: ws.sandboxId,
+      code: "ai_server_launch",
+      role: "ai",
+      title: `Could not start the chat script (${label})`,
+      message: `No free port found (tried from ${preferred}). ${
+        err instanceof Error ? err.message : String(err)
+      }`,
+      resolution: "Close other local servers, then use Start chat server.",
+    });
+    return { port: preferred, up: false, launched: false };
+  }
+  if (port !== preferred) {
+    log(`port ${preferred} busy; using ${port} for ai-server`);
+    ws.port = port;
+    const envPath = path.join(folder, ".env");
+    if (fs.existsSync(envPath)) {
+      mergeEnvFile(envPath, {
+        PORT: String(port),
+        AI_SERVER_URL: `http://localhost:${port}`,
+        NEXT_PUBLIC_AI_SERVER_URL: `http://localhost:${port}`,
+      });
+    }
+    persistWorkspaceEntry(cfg, ws);
+  }
 
   const localCli = path.resolve(
     __dirname,
@@ -300,42 +1237,371 @@ function startAiServerForWorkspace(ws) {
     "cli.js"
   );
   const useLocal = fs.existsSync(localCli);
-  const env = {
-    ...process.env,
-    PORT: String(ws.port),
-    AI_SERVER_URL: `http://localhost:${ws.port}`,
-    NEXT_PUBLIC_AI_SERVER_URL: `http://localhost:${ws.port}`,
-  };
+  const run = useLocal
+    ? process.platform === "win32"
+      ? `"${process.execPath}" "${localCli}" --port ${port}`
+      : `${JSON.stringify(process.execPath)} ${JSON.stringify(localCli)} --port ${port}`
+    : `npx --yes @maintainer-pro/ai-server --port ${port}`;
 
-  log(`starting ai-server for ${ws.sandboxName || ws.sandboxId} on :${ws.port}`);
-  const child = spawn(
-    useLocal
-      ? process.execPath
-      : process.platform === "win32"
-        ? "npx.cmd"
-        : "npx",
-    useLocal ? [localCli] : ["--yes", "@maintainer-pro/ai-server"],
-    {
-      cwd: ws.folderPath,
-      env,
-      stdio: ["ignore", "pipe", "pipe"],
-      shell: process.platform === "win32" && !useLocal,
+  const opened = await openInNewTerminal({
+    title: `MP-ai-${port}`,
+    folder,
+    command: run,
+    env: {
+      PORT: String(port),
+      AI_SERVER_URL: `http://localhost:${port}`,
+      NEXT_PUBLIC_AI_SERVER_URL: `http://localhost:${port}`,
+    },
+    launchKey,
+  });
+  if (opened.skipped) {
+    return { port, up: false, launched: false, starting: true };
+  }
+  if (!opened.ok) {
+    recordProcessProblem({
+      sandboxId: ws.sandboxId,
+      code: "ai_server_launch",
+      role: "ai",
+      title: `Could not start the chat script (${label})`,
+      message: opened.error,
+      resolution:
+        "Allow the bridge to open terminal windows, or start the script manually in that folder.",
+    });
+    return { port, up: false, launched: false };
+  }
+  return { port, up: false, launched: true, starting: true };
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/** @type {Map<string, { child: import("node:child_process").ChildProcess, url: string | null, localUrl: string }>} */
+const cloudflareTunnels = new Map();
+
+function stopCloudflare(sandboxId) {
+  const row = cloudflareTunnels.get(sandboxId);
+  if (row?.child && !row.child.killed) {
+    try {
+      row.child.kill();
+    } catch {
+      /* ignore */
     }
+  }
+  cloudflareTunnels.delete(sandboxId);
+}
+
+function stopAllCloudflare() {
+  for (const id of [...cloudflareTunnels.keys()]) stopCloudflare(id);
+}
+
+function localUrlForWorkspace(ws) {
+  if (ws.appUrl && isLocalAppUrl(ws.appUrl)) return ws.appUrl;
+  return `http://127.0.0.1:${Number(ws.port) || 3100}`;
+}
+
+function parseTryCloudflareUrl(text) {
+  const match = String(text || "").match(
+    /https:\/\/[a-z0-9-]+\.trycloudflare\.com/i
   );
-  const tag = ws.sandboxName || ws.sandboxId.slice(0, 8);
-  child.stdout?.on("data", (buf) => {
-    const line = String(buf).trimEnd();
-    if (line) console.log(`[ai-server:${tag}] ${line}`);
-  });
-  child.stderr?.on("data", (buf) => {
-    const line = String(buf).trimEnd();
-    if (line) console.error(`[ai-server:${tag}] ${line}`);
+  return match ? match[0].replace(/\/$/, "") : null;
+}
+
+function spawnCloudflared(localUrl) {
+  const args = ["tunnel", "--url", localUrl, "--no-autoupdate"];
+  const trySpawn = (file, argv, extra = {}) =>
+    new Promise((resolve, reject) => {
+      const child = spawn(file, argv, {
+        stdio: ["ignore", "pipe", "pipe"],
+        windowsHide: true,
+        ...extra,
+      });
+      const onError = (err) => reject(err);
+      child.once("error", onError);
+      child.once("spawn", () => {
+        child.off("error", onError);
+        resolve(child);
+      });
+    });
+
+  return trySpawn("cloudflared", args).catch(() =>
+    trySpawn(
+      process.platform === "win32" ? "npx.cmd" : "npx",
+      ["--yes", "cloudflared", ...args],
+      { shell: process.platform === "win32" }
+    )
+  );
+}
+
+function waitForTunnelUrl(child, timeoutMs = 90_000) {
+  return new Promise((resolve, reject) => {
+    let buffer = "";
+    let settled = false;
+    const done = (err, url) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      if (err) reject(err);
+      else resolve(url);
+    };
+    const onData = (chunk) => {
+      buffer += String(chunk);
+      const url = parseTryCloudflareUrl(buffer);
+      if (url) done(null, url);
+    };
+    child.stdout?.on("data", onData);
+    child.stderr?.on("data", onData);
+    child.once("exit", (code) => {
+      done(
+        new Error(
+          `cloudflared exited ${code ?? "early"} before it published a URL`
+        )
+      );
+    });
+    const timer = setTimeout(() => {
+      done(
+        new Error(
+          "Cloudflare did not publish a URL in time. Is cloudflared installed and online?"
+        )
+      );
+    }, timeoutMs);
   });
-  child.on("exit", (code, signal) => {
-    log(`ai-server ${tag} exited (code=${code}, signal=${signal})`);
-    children.delete(key);
+}
+
+async function configureCloudflareForWorkspace(ws, cfg) {
+  const sandboxId = ws.sandboxId;
+  const label = ws.sandboxName || "this sandbox";
+  const localUrl = localUrlForWorkspace(ws);
+  const existing = cloudflareTunnels.get(sandboxId);
+  if (existing?.url && existing.localUrl === localUrl && existing.child && !existing.child.killed) {
+    return {
+      sandboxId,
+      folderPath: ws.folderPath,
+      appUrl: existing.url,
+      origins: [existing.url],
+      localUrl,
+      cloudflare: true,
+      reused: true,
+    };
+  }
+  if (existing) stopCloudflare(sandboxId);
+
+  log(`starting Cloudflare tunnel for ${label} → ${localUrl}`);
+  let child;
+  try {
+    child = await spawnCloudflared(localUrl);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    recordProcessProblem({
+      sandboxId,
+      code: "cloudflare_launch",
+      role: "tunnel",
+      title: `Could not start Cloudflare (${label})`,
+      message,
+      resolution:
+        "Install cloudflared (https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/) or allow npx to download it, then try again.",
+      actionCode: "configure_cloudflare",
+    });
+    throw new Error(
+      `Could not start cloudflared. Install it or allow npx to download it. ${message}`
+    );
+  }
+
+  cloudflareTunnels.set(sandboxId, { child, url: null, localUrl });
+  child.once("exit", () => {
+    const row = cloudflareTunnels.get(sandboxId);
+    if (row?.child === child) cloudflareTunnels.delete(sandboxId);
   });
-  children.set(key, child);
+
+  const publicUrl = await waitForTunnelUrl(child);
+  cloudflareTunnels.set(sandboxId, { child, url: publicUrl, localUrl });
+  child.unref();
+
+  ws.cloudflareUrl = publicUrl;
+  ws.appUrl = publicUrl;
+  const folder = ws.folderPath ? path.resolve(ws.folderPath) : null;
+  if (folder && fs.existsSync(folder)) {
+    fs.writeFileSync(
+      path.join(folder, ".cloudflare-tunnel-url"),
+      `${publicUrl}\n`,
+      "utf8"
+    );
+    const envPath = path.join(folder, ".env");
+    const envValues = {
+      APP_URL: publicUrl,
+      PUBLIC_URL: publicUrl,
+      CORS_ORIGIN: publicUrl,
+    };
+    if (isAiServerTarget(ws, localUrl)) {
+      envValues.AI_SERVER_URL = publicUrl;
+      envValues.NEXT_PUBLIC_AI_SERVER_URL = publicUrl;
+    }
+    if (fs.existsSync(envPath)) mergeEnvFile(envPath, envValues);
+  }
+  persistWorkspaceEntry(cfg, ws);
+  clearProcessProblem(sandboxId, "cloudflare_launch", "tunnel");
+  log(`Cloudflare URL for ${label}: ${publicUrl}`);
+  return {
+    sandboxId,
+    folderPath: ws.folderPath,
+    appUrl: publicUrl,
+    origins: [publicUrl],
+    localUrl,
+    cloudflare: true,
+    reused: false,
+  };
+}
+
+function isAiServerTarget(ws, localUrl) {
+  try {
+    const port = Number(new URL(localUrl).port);
+    return port === Number(ws.port);
+  } catch {
+    return true;
+  }
+}
+
+async function ensureHostProcesses(ws, opts = {}) {
+  const reserved = opts.reserved instanceof Set ? opts.reserved : new Set();
+  const cfg = opts.cfg || null;
+  const folder = path.resolve(ws.folderPath);
+  const scripts = readPackageJson(folder)?.scripts || {};
+  const jobs = planHostJobs(folder, ws.appUrl || null, ws.projectInfo);
+  const started = [];
+  let persisted = false;
+  const label = ws.sandboxName || "this sandbox";
+
+  if (jobs.length > 0 && !fs.existsSync(folder)) {
+    recordProcessProblem({
+      sandboxId: ws.sandboxId,
+      code: "host_process_launch",
+      role: "app",
+      title: `Could not start the app (${label})`,
+      message: `The project folder is missing: ${folder}`,
+      resolution: "Attach the folder again from Local setup.",
+    });
+    return started;
+  }
+
+  for (const job of jobs) {
+    const preferred = Number(job.preferredPort) || 3000;
+    const probe = (job.probeUrl || `http://127.0.0.1:${preferred}`).replace(
+      "localhost",
+      "127.0.0.1"
+    );
+    if (await probeUrl(probe)) {
+      reserved.add(portFromText(probe, preferred));
+      clearProcessProblem(ws.sandboxId, "host_process_launch", job.role);
+      clearProcessProblem(ws.sandboxId, "host_process_down", job.role);
+      log(`${job.role} already running at ${job.probeUrl || probe}`);
+      continue;
+    }
+    const launchKey = `${ws.sandboxId}:${folder}:${job.script}`;
+    if (recentlyLaunched(launchKey)) {
+      reserved.add(preferred);
+      continue;
+    }
+
+    let port = preferred;
+    try {
+      port = await findFreePort(preferred, reserved);
+    } catch (err) {
+      recordProcessProblem({
+        sandboxId: ws.sandboxId,
+        code: "host_process_launch",
+        role: job.role,
+        title: `Could not start the ${processRoleLabel(job.role)} (${label})`,
+        message: `No free port found for "${job.script}" (tried from ${preferred}). ${
+          err instanceof Error ? err.message : String(err)
+        }`,
+        resolution: "Close other local servers, then use Start chat server.",
+      });
+      continue;
+    }
+    if (port !== preferred) {
+      log(`port ${preferred} busy; using ${port} for ${job.role}`);
+    }
+
+    const needsInstall =
+      fs.existsSync(path.join(folder, "package.json")) &&
+      !fs.existsSync(path.join(folder, "node_modules"));
+    const run = commandWithPort(job, scripts, port);
+    const command = needsInstall ? `npm install && ${run}` : run;
+    const opened = await openInNewTerminal({
+      title: `MP-${job.role}-${port}`,
+      folder,
+      command,
+      env: { PORT: String(port) },
+      launchKey,
+    });
+    if (opened.skipped) continue;
+    if (!opened.ok) {
+      recordProcessProblem({
+        sandboxId: ws.sandboxId,
+        code: "host_process_launch",
+        role: job.role,
+        title: `Could not start the ${processRoleLabel(job.role)} (${label})`,
+        message: `${opened.error} Command: ${command}`,
+        resolution:
+          "Allow the bridge to open terminal windows, or run that command manually in the folder.",
+      });
+      continue;
+    }
+    started.push(job.role);
+    if (
+      (job.role === "ui" || job.role === "app") &&
+      (!ws.appUrl || isLocalAppUrl(ws.appUrl))
+    ) {
+      ws.appUrl = urlWithPort(ws.appUrl || `http://localhost:${port}`, port);
+      persisted = true;
+    }
+    await sleep(400);
+  }
+  if (persisted) persistWorkspaceEntry(cfg, ws);
+  return started;
+}
+
+async function inspectHostJobs(ws) {
+  const folder = path.resolve(ws.folderPath || "");
+  const jobs = planHostJobs(folder, ws.appUrl || null, ws.projectInfo);
+  const label = ws.sandboxName || "this sandbox";
+  const hosts = [];
+  for (const job of jobs) {
+    const preferred = Number(job.preferredPort) || 3000;
+    const probe = (job.probeUrl || `http://127.0.0.1:${preferred}`).replace(
+      "localhost",
+      "127.0.0.1"
+    );
+    const up = await probeUrl(probe);
+    const launchKey = `${ws.sandboxId}:${folder}:${job.script}`;
+    const starting = recentlyLaunched(launchKey);
+    hosts.push({
+      role: job.role,
+      script: job.script,
+      probeUrl: job.probeUrl || probe,
+      up,
+      starting,
+    });
+    if (up) {
+      clearProcessProblem(ws.sandboxId, "host_process_launch", job.role);
+      clearProcessProblem(ws.sandboxId, "host_process_down", job.role);
+      continue;
+    }
+    if (starting) continue;
+    const tried = launchedAt.has(launchKey);
+    recordProcessProblem({
+      sandboxId: ws.sandboxId,
+      code: "host_process_down",
+      role: job.role,
+      title: `The ${processRoleLabel(job.role)} is not running (${label})`,
+      message: tried
+        ? `Started "${job.script}" in a separate terminal, but nothing answered at ${probe}. Open that window and read the error.`
+        : `Nothing is running at ${probe} for "${job.script}".`,
+      resolution:
+        "Fix the error in that terminal, then use Start chat server to try again.",
+    });
+  }
+  return hosts;
 }
 
 async function setupWorkspace(cfg, action) {
@@ -343,7 +1609,29 @@ async function setupWorkspace(cfg, action) {
   const sandboxId = String(
     action.sandboxId || action.payload?.sandboxId || ""
   );
-  const port = Number(action.payload?.port) || 3100;
+  const requestedPort = Number(action.payload?.port) || 3100;
+  const reserved = new Set();
+  for (const other of cfg.workspaces || []) {
+    if (other.sandboxId !== sandboxId && other.port) {
+      reserved.add(Number(other.port));
+    }
+  }
+  let port = requestedPort;
+  if (await probeUrl(`http://127.0.0.1:${requestedPort}/embed-config.js`)) {
+    reserved.add(requestedPort);
+  } else {
+    port = await findFreePort(requestedPort, reserved);
+    if (port !== requestedPort) {
+      log(`port ${requestedPort} busy; using ${port} for ai-server`);
+    }
+  }
+  const clientMode = String(action.payload?.clientMode || "auto"); // auto|empty|existing|skip
+  const hostAppUrl =
+    typeof action.payload?.hostAppUrl === "string" &&
+    action.payload.hostAppUrl.trim()
+      ? action.payload.hostAppUrl.trim().replace(/\/$/, "")
+      : null;
+
   if (!folderPath || !sandboxId) {
     throw new Error("setup_workspace requires folderPath and sandboxId");
   }
@@ -357,13 +1645,34 @@ async function setupWorkspace(cfg, action) {
     `/api/v1/bridge/machine/sandboxes/${sandboxId}/setup-config?port=${port}`
   );
 
+  const appName =
+    config.sandbox?.applicationName ||
+    config.sandbox?.name ||
+    "Maintainer Pro App";
+
+  const client = configureClient({
+    dir: resolved,
+    port,
+    appName,
+    mode: clientMode,
+    hostAppUrl,
+  });
+
+  const aiOrigin = `http://localhost:${port}`;
+  const corsOrigin = client.corsOrigin || aiOrigin;
+  const appUrl = client.appUrl || corsOrigin;
+
   const envPath = path.join(resolved, ".env");
   const envValues = {
     ...config.env,
     AI_CLI_WORKSPACE: ".",
-    AI_SERVER_UI: ".",
-    CORS_ORIGIN: process.env.CORS_ORIGIN || `http://localhost:${port}`,
-    APP_URL: process.env.APP_URL || `http://localhost:3000`,
+    AI_SERVER_UI: client.sameOrigin || client.kind === "empty" ? "." : ".",
+    PORT: String(port),
+    AI_SERVER_URL: aiOrigin,
+    NEXT_PUBLIC_AI_SERVER_URL: aiOrigin,
+    CORS_ORIGIN: corsOrigin,
+    APP_URL: appUrl,
+    AI_SERVER_PRODUCT_DESCRIPTION: appName,
   };
   mergeEnvFile(envPath, envValues);
 
@@ -375,6 +1684,9 @@ async function setupWorkspace(cfg, action) {
     port,
     sandboxName: config.sandbox?.name,
     applicationName: config.sandbox?.applicationName,
+    clientKind: client.kind,
+    appUrl,
+    sameOrigin: Boolean(client.sameOrigin),
   };
   if (existing >= 0) cfg.workspaces[existing] = entry;
   else cfg.workspaces.push(entry);
@@ -382,18 +1694,66 @@ async function setupWorkspace(cfg, action) {
   if (!cfg.offeredFolders.includes(resolved)) cfg.offeredFolders.push(resolved);
   saveConfig(cfg);
 
+  const projectInfo = await inspectProjectWithAiCli(entry, {
+    cfg,
+    extraContext: [
+      `Scaffold kind: ${client.kind}`,
+      `Chat script port: ${port}`,
+      client.notes.join(" "),
+    ]
+      .filter(Boolean)
+      .join("\n"),
+  });
+
   if (!cfg.noAiServer) {
-    startAiServerForWorkspace(entry);
-    await new Promise((r) => setTimeout(r, 1200));
+    await startAiServerForWorkspace(entry, { reserved, cfg });
+    await sleep(1500);
+  }
+  const startedHosts = await ensureHostProcesses(entry, { reserved, cfg });
+  await sleep(800);
+  await inspectHostJobs(entry);
+
+  const openUrl = client.sameOrigin
+    ? `http://localhost:${entry.port}`
+    : entry.appUrl || appUrl;
+  const aiServerUp = await probeUrl(`http://127.0.0.1:${entry.port}/embed-config.js`);
+  if (aiServerUp) {
+    clearProcessProblem(sandboxId, "ai_server_launch", "ai");
+  }
+
+  const processIssues = issuesForSandbox(sandboxId).map(
+    ({ role: _role, ...issue }) => issue
+  );
+  const warning = processIssues[0]?.message || null;
+
+  for (const note of client.notes) log(note);
+  if (startedHosts.length) {
+    log(`started ${startedHosts.join(" + ")} in separate terminals`);
+  }
+  if (aiServerUp) {
+    log(`ai-server up — open ${openUrl}`);
+  } else if (warning) {
+    log(`process issue: ${warning}`);
+  } else {
+    log("ai-server not reachable yet; it may still be starting");
   }
 
   return {
     sandboxId,
     folderPath: resolved,
-    port,
-    appUrl: envValues.APP_URL || null,
-    origins: envValues.CORS_ORIGIN ? [envValues.CORS_ORIGIN] : [],
+    port: entry.port,
+    appUrl: entry.appUrl || appUrl,
+    origins: [...new Set([corsOrigin, aiOrigin, entry.appUrl].filter(Boolean))],
     wroteEnv: true,
+    clientKind: client.kind,
+    clientFiles: client.filesWritten,
+    clientNotes: client.notes,
+    aiServerUp,
+    startedHosts,
+    openUrl,
+    processIssues,
+    warning,
+    projectInfo,
   };
 }
 
@@ -410,7 +1770,15 @@ async function runActions(cfg, actions) {
       } else if (action.code === "setup_workspace") {
         result = await setupWorkspace(cfg, action);
       } else if (action.code === "recheck") {
-        result = { recheckedAt: new Date().toISOString() };
+        const sandboxId = action.sandboxId || action.payload?.sandboxId;
+        const ws = (cfg.workspaces || []).find((w) => w.sandboxId === sandboxId);
+        const projectInfo = ws
+          ? await inspectProjectWithAiCli(ws, { cfg })
+          : null;
+        result = {
+          recheckedAt: new Date().toISOString(),
+          projectInfo,
+        };
       } else if (action.code === "start_ai_server") {
         const sandboxId = action.sandboxId || action.payload?.sandboxId;
         const ws =
@@ -426,23 +1794,88 @@ async function runActions(cfg, actions) {
           ok = false;
           result = { error: "No workspace or --no-ai-server" };
         } else {
-          startAiServerForWorkspace(ws);
-          await new Promise((r) => setTimeout(r, 1200));
+          const reserved = new Set();
+          for (const other of cfg.workspaces || []) {
+            if (other.sandboxId !== ws.sandboxId && other.port) {
+              reserved.add(Number(other.port));
+            }
+          }
+          const problem = issuesForSandbox(ws.sandboxId)
+            .map((issue) => issue.message)
+            .join("\n");
+          const projectInfo = await inspectProjectWithAiCli(ws, {
+            cfg,
+            problem:
+              problem ||
+              "Local processes are not running or the project setup looks incomplete.",
+          });
+          await startAiServerForWorkspace(ws, { reserved, cfg });
+          await sleep(1500);
+          const startedHosts = await ensureHostProcesses(ws, { reserved, cfg });
+          await sleep(800);
+          await inspectHostJobs(ws);
+          const up = await probeUrl(
+            `http://127.0.0.1:${ws.port}/embed-config.js`
+          );
+          if (up) clearProcessProblem(ws.sandboxId, "ai_server_launch", "ai");
+          const processIssues = issuesForSandbox(ws.sandboxId).map(
+            ({ role: _role, ...issue }) => issue
+          );
+          const warning = processIssues[0]?.message || null;
           result = {
-            up: await probeUrl(
-              `http://127.0.0.1:${ws.port}/embed-config.js`
-            ),
+            up,
+            startedHosts,
+            sandboxId: ws.sandboxId,
+            folderPath: ws.folderPath,
+            port: ws.port,
+            appUrl: ws.appUrl,
+            processIssues,
+            warning,
+            projectInfo,
           };
+          if (processIssues.some((issue) => issue.code === "ai_server_launch")) {
+            result.error = warning;
+            ok = false;
+          }
         }
       } else if (action.code === "refresh_public_url") {
+        const sandboxId = action.sandboxId || action.payload?.sandboxId;
+        const ws = (cfg.workspaces || []).find((w) => w.sandboxId === sandboxId);
         result = {
-          appUrl: process.env.APP_URL || process.env.PUBLIC_URL || null,
+          appUrl:
+            ws?.cloudflareUrl ||
+            ws?.appUrl ||
+            process.env.APP_URL ||
+            process.env.PUBLIC_URL ||
+            null,
         };
+      } else if (action.code === "configure_cloudflare") {
+        const sandboxId = action.sandboxId || action.payload?.sandboxId;
+        const ws =
+          (cfg.workspaces || []).find((w) => w.sandboxId === sandboxId) ||
+          (action.payload?.folderPath
+            ? {
+                sandboxId,
+                folderPath: String(action.payload.folderPath),
+                port: Number(action.payload.port) || 3100,
+                appUrl:
+                  typeof action.payload.appUrl === "string"
+                    ? action.payload.appUrl
+                    : null,
+                sandboxName: action.payload.sandboxName,
+              }
+            : null);
+        if (!ws) {
+          ok = false;
+          result = { error: "No folder is attached for this sandbox" };
+        } else {
+          result = await configureCloudflareForWorkspace(ws, cfg);
+        }
       } else if (action.code === "remove_workspace") {
         const sandboxId = String(
           action.sandboxId || action.payload?.sandboxId || ""
         );
-        stopChild(sandboxId);
+        forgetLaunch(sandboxId);
         cfg.workspaces = (cfg.workspaces || []).filter(
           (w) => w.sandboxId !== sandboxId
         );
@@ -475,10 +1908,53 @@ async function runActions(cfg, actions) {
   }
 }
 
-function buildIssues(cfg, workspaceStates) {
+async function collectWorkspaceStates(cfg) {
+  /** @type {Array<{sandboxId:string,sandboxName?:string,port:number,aiServerUp:boolean,startingAi:boolean,folderPath:string,appUrl?:string|null}>} */
+  const localStates = [];
+  for (const ws of cfg.workspaces || []) {
+    const folder = path.resolve(ws.folderPath || "");
+    const up = await probeUrl(`http://127.0.0.1:${ws.port}/embed-config.js`);
+    if (up) clearProcessProblem(ws.sandboxId, "ai_server_launch", "ai");
+    await inspectHostJobs(ws);
+    localStates.push({
+      sandboxId: ws.sandboxId,
+      sandboxName: ws.sandboxName,
+      port: ws.port,
+      folderPath: ws.folderPath,
+      aiServerUp: up,
+      startingAi: recentlyLaunched(`${ws.sandboxId}:${folder}:ai`),
+      appUrl: ws.appUrl || null,
+    });
+  }
+  return localStates;
+}
+
+async function sendHeartbeat(cfg, folders, localStates) {
+  return api(
+    cfg.adminUrl,
+    cfg.token,
+    "POST",
+    "/api/v1/bridge/machine/heartbeat",
+    {
+      hostname: os.hostname(),
+      platform: `${os.platform()}-${os.arch()}`,
+      bridgeVersion: PACKAGE_VERSION,
+      folders,
+      issues: await buildIssues(cfg, localStates),
+      workspaces: localStates.map((st) => ({
+        sandboxId: st.sandboxId,
+        aiServerUp: st.aiServerUp,
+        port: st.port,
+        appUrl: st.appUrl || undefined,
+      })),
+    }
+  );
+}
+
+async function buildIssues(cfg, workspaceStates) {
   /** @type {Array<Record<string, unknown>>} */
   const issues = [];
-  const cli = detectCliProviders();
+  const cli = await detectCliProviders();
   if (!cli.length) {
     issues.push({
       code: "missing_cli",
@@ -492,17 +1968,54 @@ function buildIssues(cfg, workspaceStates) {
     });
   }
   for (const st of workspaceStates) {
-    if (!st.aiServerUp) {
-      issues.push({
-        code: "ai_server_down",
-        severity: "error",
-        title: `AI server down (${st.sandboxName || st.sandboxId})`,
-        message: `Cannot reach http://localhost:${st.port}`,
-        resolution: "Start ai-server from the Bridges page or restart the bridge.",
-        actionCode: "start_ai_server",
-        sandboxId: st.sandboxId,
-      });
+    if (st.aiServerUp || st.startingAi) continue;
+    const launch = [...processProblems.values()].find(
+      (issue) =>
+        issue.sandboxId === st.sandboxId && issue.code === "ai_server_launch"
+    );
+    issues.push({
+      code: "ai_server_down",
+      severity: "error",
+      title:
+        launch?.title ||
+        `Local script is not running (${st.sandboxName || "sandbox"})`,
+      message:
+        launch?.message ||
+        `Cannot reach http://localhost:${st.port}. Check the MP-ai terminal on that computer for the error.`,
+      resolution:
+        launch?.resolution ||
+        "Read the error in that terminal, then use Start chat server.",
+      actionCode: "start_ai_server",
+      sandboxId: st.sandboxId,
+    });
+  }
+  for (const problem of processProblems.values()) {
+    if (
+      problem.code === "ai_server_launch" ||
+      problem.code === "ai_server_down"
+    ) {
+      continue;
+    }
+    if (
+      problem.code === "host_process_down" &&
+      [...processProblems.values()].some(
+        (other) =>
+          other.sandboxId === problem.sandboxId &&
+          other.role === problem.role &&
+          other.code === "host_process_launch"
+      )
+    ) {
+      continue;
     }
+    issues.push({
+      code: problem.code,
+      severity: problem.severity,
+      title: problem.title,
+      message: problem.message,
+      resolution: problem.resolution,
+      actionCode: problem.actionCode,
+      sandboxId: problem.sandboxId,
+    });
   }
   return issues;
 }
@@ -542,6 +2055,8 @@ async function pairFlow(args) {
   saveConfig(cfg);
   log(`paired as ${result.machine?.name || cfg.machineId}`);
   log(`config ${configPath()}`);
+  log("Keep this process running.");
+  log("Next: Admin → Bridges → pick a folder → Setup sandbox.");
   return cfg;
 }
 
@@ -584,35 +2099,32 @@ async function main() {
       /** @type {Array<{sandboxId:string,sandboxName?:string,port:number,aiServerUp:boolean,folderPath:string}>} */
       const localStates = [];
 
+      const reserved = new Set();
       for (const ws of cfg.workspaces || []) {
+        const folder = path.resolve(ws.folderPath || "");
         const up = await probeUrl(
           `http://127.0.0.1:${ws.port}/embed-config.js`
         );
+        if (!cfg.noAiServer && !up) {
+          await startAiServerForWorkspace(ws, { reserved, cfg });
+        } else if (ws.port) {
+          reserved.add(Number(ws.port));
+          if (up) clearProcessProblem(ws.sandboxId, "ai_server_launch", "ai");
+        }
+        await ensureHostProcesses(ws, { reserved, cfg });
+        await inspectHostJobs(ws);
         localStates.push({
           sandboxId: ws.sandboxId,
           sandboxName: ws.sandboxName,
           port: ws.port,
           folderPath: ws.folderPath,
           aiServerUp: up,
+          startingAi: recentlyLaunched(`${ws.sandboxId}:${folder}:ai`),
+          appUrl: ws.appUrl || null,
         });
-        if (!cfg.noAiServer && !up) {
-          startAiServerForWorkspace(ws);
-        }
       }
 
-      const hb = await api(
-        cfg.adminUrl,
-        cfg.token,
-        "POST",
-        "/api/v1/bridge/machine/heartbeat",
-        {
-          hostname: os.hostname(),
-          platform: `${os.platform()}-${os.arch()}`,
-          bridgeVersion: PACKAGE_VERSION,
-          folders,
-          issues: buildIssues(cfg, localStates),
-        }
-      );
+      const hb = await sendHeartbeat(cfg, folders, localStates);
 
       // Sync local workspace list from server assignments
       if (Array.isArray(hb.workspaces)) {
@@ -641,20 +2153,45 @@ async function main() {
 
       if (Array.isArray(hb.actions) && hb.actions.length > 0) {
         await runActions(cfg, hb.actions);
+        await sendHeartbeat(cfg, folders, await collectWorkspaceStates(cfg));
       }
     } catch (err) {
       warn(err instanceof Error ? err.message : String(err));
     }
   };
 
-  await tick();
+  let cycleBusy = false;
+  const runLocked = async (fn) => {
+    if (cycleBusy) return;
+    cycleBusy = true;
+    try {
+      await fn();
+    } finally {
+      cycleBusy = false;
+    }
+  };
+
+  await runLocked(tick);
   setInterval(() => {
-    void tick();
+    void runLocked(tick);
   }, HEARTBEAT_MS);
+  setInterval(() => {
+    void runLocked(async () => {
+      const pending = await api(
+        cfg.adminUrl,
+        cfg.token,
+        "GET",
+        "/api/v1/bridge/machine/actions"
+      );
+      if (Array.isArray(pending?.actions) && pending.actions.length > 0) {
+        await runActions(cfg, pending.actions);
+      }
+    });
+  }, ACTION_POLL_MS);
 
   const shutdown = () => {
-    log("shutting down");
-    for (const id of [...children.keys()]) stopChild(id);
+    stopAllCloudflare();
+    log("shutting down (other terminals stay open)");
     process.exit(0);
   };
   process.on("SIGINT", shutdown);