@maintainer-pro/ai-bridge 0.1.1 → 0.1.3

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) {
@@ -665,26 +844,391 @@ 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;
   }
-  children.delete(sandboxId);
 }
 
-function startAiServerForWorkspace(ws) {
-  const key = ws.sandboxId;
-  if (children.has(key) && !children.get(key)?.killed) return;
+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}`;
+  }
+  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);
+    });
+  });
+}
+
+async function openInNewTerminal(opts) {
+  const { title, folder, command, env = {}, launchKey } = opts;
+  if (launchKey) {
+    if (!opts.force && 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,
@@ -695,42 +1239,545 @@ 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}`;
+
+  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 };
+}
 
-  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,
-    }
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/** @type {Map<string, { tunnels: Array<{ role: string, localUrl: string, publicUrl: string | null, logFile: string }> }>} */
+const cloudflareTunnels = new Map();
+
+function stopAllCloudflare() {
+  for (const id of [...cloudflareTunnels.keys()]) stopCloudflare(id);
+}
+
+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}`);
+  return match ? match[0].replace(/\/$/, "") : null;
+}
+
+function killProcessesByCommand(fragment) {
+  if (!fragment) return Promise.resolve();
+  return new Promise((resolve) => {
+    const done = () => resolve();
+    if (process.platform === "win32") {
+      const escaped = String(fragment).replace(/'/g, "''");
+      const child = spawn(
+        "powershell.exe",
+        [
+          "-NoProfile",
+          "-Command",
+          `Get-CimInstance Win32_Process | Where-Object { $_.CommandLine -like '*${escaped}*' } | ForEach-Object { Stop-Process -Id $_.ProcessId -Force -ErrorAction SilentlyContinue }`,
+        ],
+        { windowsHide: true, stdio: "ignore" }
+      );
+      child.on("exit", done);
+      child.on("error", done);
+      setTimeout(done, 8000);
+      return;
+    }
+    const child = spawn("pkill", ["-f", String(fragment)], { stdio: "ignore" });
+    child.on("exit", done);
+    child.on("error", done);
+    setTimeout(done, 4000);
   });
-  child.stderr?.on("data", (buf) => {
-    const line = String(buf).trimEnd();
-    if (line) console.error(`[ai-server:${tag}] ${line}`);
+}
+
+function killPort(port) {
+  const n = Number(port);
+  if (!n) return Promise.resolve();
+  return new Promise((resolve) => {
+    const done = () => resolve();
+    if (process.platform === "win32") {
+      const child = spawn(
+        "powershell.exe",
+        [
+          "-NoProfile",
+          "-Command",
+          `$ErrorActionPreference='SilentlyContinue'; $pids=@(); $pids += Get-NetTCPConnection -LocalPort ${n} -State Listen | Select-Object -ExpandProperty OwningProcess; if (-not $pids) { netstat -ano | Select-String ':${n}\\s' | ForEach-Object { if ($_ -match 'LISTENING\\s+(\\d+)') { $pids += [int]$Matches[1] } } }; $pids | Sort-Object -Unique | Where-Object { $_ -gt 0 -and $_ -ne ${process.pid} } | ForEach-Object { Stop-Process -Id $_ -Force }`,
+        ],
+        { windowsHide: true, stdio: "ignore" }
+      );
+      child.on("exit", done);
+      child.on("error", done);
+      setTimeout(done, 8000);
+      return;
+    }
+    const child = spawn(
+      "sh",
+      ["-c", `pids=$(lsof -ti tcp:${n} 2>/dev/null); [ -n "$pids" ] && kill $pids`],
+      { stdio: "ignore" }
+    );
+    child.on("exit", done);
+    child.on("error", done);
+    setTimeout(done, 4000);
   });
-  child.on("exit", (code, signal) => {
-    log(`ai-server ${tag} exited (code=${code}, signal=${signal})`);
-    children.delete(key);
+}
+
+function stopCloudflare(sandboxId) {
+  const row = cloudflareTunnels.get(sandboxId);
+  const files = row?.tunnels?.map((t) => t.logFile).filter(Boolean) ?? [];
+  cloudflareTunnels.delete(sandboxId);
+  return Promise.all(files.map((file) => killProcessesByCommand(file)));
+}
+
+function forgetProcessLaunches(sandboxId) {
+  for (const key of [...launchedAt.keys()]) {
+    if (key === sandboxId || key.startsWith(`${sandboxId}:`)) {
+      launchedAt.delete(key);
+    }
+  }
+}
+
+async function stopWorkspaceApps(ws) {
+  const folder = path.resolve(ws.folderPath || "");
+  const jobs = planHostJobs(folder, null, ws.projectInfo);
+  const ports = new Set();
+  if (ws.port) ports.add(Number(ws.port));
+  for (const job of jobs) {
+    if (job.preferredPort) ports.add(Number(job.preferredPort));
+  }
+  if (ws.appUrl && isLocalAppUrl(ws.appUrl)) {
+    try {
+      const port = Number(new URL(ws.appUrl).port);
+      if (port) ports.add(port);
+    } catch {
+      /* ignore */
+    }
+  }
+  log(`stopping local apps on ports ${[...ports].join(", ") || "(none)"}`);
+  for (const port of ports) {
+    await killPort(port);
+  }
+  forgetProcessLaunches(ws.sandboxId);
+  await sleep(400);
+}
+
+async function waitUntilReachable(url, timeoutMs, label) {
+  const start = Date.now();
+  while (Date.now() - start < timeoutMs) {
+    if (await probeUrl(url)) return true;
+    await sleep(600);
+  }
+  throw new Error(`${label} did not become reachable at ${url}`);
+}
+
+async function waitForUrlInFile(file, timeoutMs = 90_000) {
+  const start = Date.now();
+  while (Date.now() - start < timeoutMs) {
+    if (fs.existsSync(file)) {
+      const url = parseTryCloudflareUrl(fs.readFileSync(file, "utf8"));
+      if (url) return url;
+    }
+    await sleep(500);
+  }
+  throw new Error(
+    `Cloudflare did not publish a URL in time (${path.basename(file)}). Check that terminal.`
+  );
+}
+
+function cloudflaredCommand(localUrl, logFile) {
+  const run = `npx --yes cloudflared tunnel --url ${localUrl} --no-autoupdate`;
+  if (process.platform === "win32") {
+    const dest = String(logFile).replace(/'/g, "''");
+    return `powershell -NoProfile -Command "${run} 2>&1 | Tee-Object -FilePath '${dest}'"`;
+  }
+  return `${run} 2>&1 | tee ${JSON.stringify(logFile)}`;
+}
+
+async function startCloudflareTerminal(ws, role, localUrl) {
+  const folder = path.resolve(ws.folderPath);
+  const logDir = path.join(folder, ".maintainer-pro");
+  fs.mkdirSync(logDir, { recursive: true });
+  const logFile = path.join(
+    logDir,
+    `cf-${String(ws.sandboxId).slice(0, 8)}-${role}.log`
+  );
+  try {
+    fs.unlinkSync(logFile);
+  } catch {
+    /* ignore */
+  }
+  const opened = await openInNewTerminal({
+    title: `MP-cf-${role}`,
+    folder,
+    command: cloudflaredCommand(localUrl, logFile),
+    launchKey: `${ws.sandboxId}:cf:${role}`,
+    force: true,
   });
-  children.set(key, child);
+  if (!opened.ok) {
+    throw new Error(opened.error || `Could not open a Cloudflare terminal for ${role}`);
+  }
+  const publicUrl = await waitForUrlInFile(logFile);
+  return { role, localUrl, publicUrl, logFile };
+}
+
+function uiPublicEnv(tunnels) {
+  /** @type {Record<string, string>} */
+  const env = {};
+  if (tunnels.ai) {
+    env.AI_SERVER_URL = tunnels.ai;
+    env.NEXT_PUBLIC_AI_SERVER_URL = tunnels.ai;
+    env.VITE_AI_SERVER_URL = tunnels.ai;
+  }
+  if (tunnels.backend) {
+    env.API_URL = tunnels.backend;
+    env.API_BASE_URL = tunnels.backend;
+    env.VITE_API_URL = tunnels.backend;
+    env.VITE_API_BASE_URL = tunnels.backend;
+    env.NEXT_PUBLIC_API_URL = tunnels.backend;
+    env.NEXT_PUBLIC_API_BASE_URL = tunnels.backend;
+    env.BACKEND_URL = tunnels.backend;
+  }
+  if (tunnels.ui) {
+    env.APP_URL = tunnels.ui;
+    env.PUBLIC_URL = tunnels.ui;
+    env.CORS_ORIGIN = tunnels.ui;
+  } else if (tunnels.ai) {
+    env.CORS_ORIGIN = tunnels.ai;
+  }
+  return env;
+}
+
+function writeTunnelEnv(ws, tunnels) {
+  const folder = ws.folderPath ? path.resolve(ws.folderPath) : null;
+  if (!folder || !fs.existsSync(folder)) return;
+  const env = uiPublicEnv(tunnels);
+  const lines = Object.entries(tunnels)
+    .filter(([, url]) => url)
+    .map(([role, url]) => `${role}=${url}`);
+  fs.writeFileSync(
+    path.join(folder, ".cloudflare-tunnel-url"),
+    `${lines.join("\n")}\n`,
+    "utf8"
+  );
+  const envPath = path.join(folder, ".env");
+  if (Object.keys(env).length) mergeEnvFile(envPath, env);
+  const localEnv = {};
+  if (env.NEXT_PUBLIC_AI_SERVER_URL) {
+    localEnv.NEXT_PUBLIC_AI_SERVER_URL = env.NEXT_PUBLIC_AI_SERVER_URL;
+  }
+  if (env.NEXT_PUBLIC_API_URL) {
+    localEnv.NEXT_PUBLIC_API_URL = env.NEXT_PUBLIC_API_URL;
+  }
+  if (Object.keys(localEnv).length) {
+    mergeEnvFile(path.join(folder, ".env.local"), localEnv);
+  }
+}
+
+async function configureCloudflareForWorkspace(ws, cfg) {
+  const sandboxId = ws.sandboxId;
+  const label = ws.sandboxName || "this sandbox";
+  const folder = path.resolve(ws.folderPath || "");
+  const reserved = new Set();
+  for (const other of cfg.workspaces || []) {
+    if (other.sandboxId !== sandboxId && other.port) {
+      reserved.add(Number(other.port));
+    }
+  }
+
+  log(`Cloudflare setup for ${label}: stop apps, then tunnel ai-server/backend before UI`);
+  try {
+  await stopCloudflare(sandboxId);
+  await stopWorkspaceApps(ws);
+
+  if (!cfg.noAiServer) {
+    await startAiServerForWorkspace(ws, { reserved, cfg });
+    await waitUntilReachable(
+      `http://127.0.0.1:${ws.port}/embed-config.js`,
+      45_000,
+      "Chat script"
+    );
+  }
+
+  const jobs = planHostJobs(folder, null, ws.projectInfo);
+  const backendJob = jobs.find((job) => job.role === "backend");
+  const uiJob = jobs.find((job) => job.role === "ui" || job.role === "app");
+
+  if (backendJob) {
+    await ensureHostProcesses(ws, {
+      reserved,
+      cfg,
+      onlyRoles: ["backend"],
+      force: true,
+    });
+    const backendPort = Number(backendJob.preferredPort) || 4100;
+    await waitUntilReachable(
+      `http://127.0.0.1:${backendPort}`,
+      45_000,
+      "Backend"
+    );
+  }
+
+  /** @type {Record<string, string>} */
+  const tunnels = {};
+  /** @type {Array<{ role: string, localUrl: string, publicUrl: string | null, logFile: string }>} */
+  const started = [];
+
+  const aiLocal = `http://127.0.0.1:${Number(ws.port) || 3100}`;
+  const aiTunnel = await startCloudflareTerminal(ws, "ai", aiLocal);
+  tunnels.ai = aiTunnel.publicUrl;
+  started.push(aiTunnel);
+  log(`Cloudflare chat script: ${aiTunnel.publicUrl}`);
+
+  if (backendJob) {
+    const backendLocal = `http://127.0.0.1:${Number(backendJob.preferredPort) || 4100}`;
+    const backendTunnel = await startCloudflareTerminal(ws, "backend", backendLocal);
+    tunnels.backend = backendTunnel.publicUrl;
+    started.push(backendTunnel);
+    log(`Cloudflare backend: ${backendTunnel.publicUrl}`);
+  }
+
+  writeTunnelEnv(ws, tunnels);
+  const uiEnv = uiPublicEnv(tunnels);
+
+  if (uiJob) {
+    await ensureHostProcesses(ws, {
+      reserved,
+      cfg,
+      onlyRoles: ["ui", "app"],
+      extraEnv: uiEnv,
+      force: true,
+    });
+    const uiPort = Number(uiJob.preferredPort) || 5173;
+    await waitUntilReachable(`http://127.0.0.1:${uiPort}`, 60_000, "App UI");
+    const uiTunnel = await startCloudflareTerminal(
+      ws,
+      "ui",
+      `http://127.0.0.1:${uiPort}`
+    );
+    tunnels.ui = uiTunnel.publicUrl;
+    started.push(uiTunnel);
+    log(`Cloudflare UI: ${uiTunnel.publicUrl}`);
+    writeTunnelEnv(ws, tunnels);
+    launchedAt.delete(`${sandboxId}:${folder}:ai`);
+    await killPort(ws.port);
+    await sleep(1500);
+    await startAiServerForWorkspace(ws, { reserved, cfg });
+  }
+
+  const appUrl = tunnels.ui || tunnels.ai;
+  ws.cloudflareUrl = appUrl;
+  ws.cloudflare = tunnels;
+  ws.appUrl = appUrl;
+  persistWorkspaceEntry(cfg, ws);
+  cloudflareTunnels.set(sandboxId, { tunnels: started });
+  clearProcessProblem(sandboxId, "cloudflare_launch", "tunnel");
+
+  return {
+    sandboxId,
+    folderPath: ws.folderPath,
+    appUrl,
+    origins: Object.values(tunnels).filter(Boolean),
+    tunnels,
+    cloudflare: true,
+    reused: false,
+  };
+  } 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 or allow npx to download it, then try Share with Cloudflare again.",
+      actionCode: "configure_cloudflare",
+    });
+    throw err;
+  }
+}
+
+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 && isLocalAppUrl(ws.appUrl) ? ws.appUrl : null,
+    ws.projectInfo
+  );
+  const onlyRoles = Array.isArray(opts.onlyRoles) ? new Set(opts.onlyRoles) : null;
+  const extraEnv = opts.extraEnv && typeof opts.extraEnv === "object" ? opts.extraEnv : {};
+  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) {
+    if (onlyRoles && !onlyRoles.has(job.role)) continue;
+    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 (!opts.force && 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), ...extraEnv },
+      launchKey,
+      force: Boolean(opts.force),
+    });
+    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 && isLocalAppUrl(ws.appUrl) ? 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) {
@@ -738,7 +1785,22 @@ 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" &&
@@ -799,6 +1861,8 @@ async function setupWorkspace(cfg, action) {
     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);
@@ -806,27 +1870,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, 1500));
+    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 aiServerUp = await probeUrl(`${aiOrigin.replace("localhost", "127.0.0.1")}/embed-config.js`);
+  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,
-    origins: [corsOrigin, aiOrigin].filter(Boolean),
+    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,
-    openUrl: client.sameOrigin ? aiOrigin : appUrl,
+    startedHosts,
+    openUrl,
+    processIssues,
+    warning,
+    projectInfo,
   };
 }
 
@@ -843,7 +1946,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 =
@@ -859,23 +1970,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
         );
@@ -908,10 +2084,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",
@@ -925,17 +2144,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;
 }
@@ -975,6 +2231,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;
 }
 
@@ -1017,35 +2275,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)) {
@@ -1074,20 +2329,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);