@maintainer-pro/ai-bridge 0.1.5 → 0.1.7

package/src/daemon.mjs

@@ -8,27 +8,70 @@
  *   npx @maintainer-pro/ai-bridge --admin-url https://… --pair ABCD-EF01
  */
 import { spawn } from "node:child_process";
-import { randomBytes } from "node:crypto";
+import { createHash, randomBytes } from "node:crypto";
 import fs from "node:fs";
 import http from "node:http";
+import https from "node:https";
 import net from "node:net";
 import os from "node:os";
 import path from "node:path";
 import readline from "node:readline";
 import { fileURLToPath, pathToFileURL } from "node:url";
+import { createLogger } from "@maintainer-pro/ai-cli";
 
 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}`);
+const WS_PING_MS = 10_000;
+const WS_RECONNECT_MIN_MS = 500;
+const WS_RECONNECT_MAX_MS = 8_000;
+
+/** @type {import("@maintainer-pro/ai-cli").Logger} */
+let logger = createLogger("ai-bridge");
+const log = (msg) => logger.info(msg);
+const warn = (msg) => logger.warn(msg);
 const fail = (msg) => {
-  console.error(`[bridge] ${msg}`);
+  logger.fatal(msg);
   process.exit(1);
 };
 
+function shortId(value) {
+  const text = String(value || "");
+  return text.length > 12 ? `${text.slice(0, 8)}…` : text;
+}
+
+function actionLabel(action) {
+  const sandbox = action.sandboxId || action.payload?.sandboxId;
+  const folder = action.payload?.folderPath;
+  const bits = [`action ${action.code}`];
+  if (action.id) bits.push(`id=${shortId(action.id)}`);
+  if (sandbox) bits.push(`sandbox=${shortId(sandbox)}`);
+  if (folder) bits.push(`folder=${folder}`);
+  return bits.join(" ");
+}
+
+function resultSummary(result) {
+  if (!result || typeof result !== "object") return "";
+  /** @type {string[]} */
+  const bits = [];
+  if (result.error) bits.push(`error=${result.error}`);
+  if (result.folderPath) bits.push(`folder=${result.folderPath}`);
+  if (result.port) bits.push(`chat=${result.port}`);
+  if (result.appUrl) bits.push(`app=${result.appUrl}`);
+  if (Array.isArray(result.origins) && result.origins.length) {
+    bits.push(`origins=${result.origins.join(",")}`);
+  }
+  if (typeof result.up === "boolean") bits.push(`chatUp=${result.up}`);
+  if (typeof result.waitingForStart === "boolean") {
+    bits.push(`waitingForStart=${result.waitingForStart}`);
+  }
+  if (Array.isArray(result.startedHosts) && result.startedHosts.length) {
+    bits.push(`started=${result.startedHosts.join(",")}`);
+  }
+  if (result.warning) bits.push(`warning=${result.warning}`);
+  return bits.join(" ");
+}
+
 function readPackageVersion() {
   try {
     const pkg = JSON.parse(
@@ -89,6 +132,10 @@ Flags:
   --offer-folder <path>   Suggest this folder in admin (repeatable via config)
   --no-ai-server          Do not open ai-server terminals for workspaces
   --help
+
+Logging (env):
+  LOG_LEVEL=info|debug|warn|error|silent   (default: info)
+  LOG_PRETTY=0                             disable pretty TTY output
 `);
 }
 
@@ -136,18 +183,43 @@ async function ask(question) {
   });
 }
 
+function fetchErrorDetail(err) {
+  const cause = err && typeof err === "object" ? err.cause : null;
+  const code =
+    (cause && typeof cause === "object" && "code" in cause && cause.code) ||
+    (err && typeof err === "object" && "code" in err && err.code) ||
+    "";
+  const port =
+    (cause && typeof cause === "object" && "port" in cause && cause.port) ||
+    "";
+  return [code, port ? `port ${port}` : ""].filter(Boolean).join(" ");
+}
+
 async function api(baseUrl, token, method, pathname, body) {
-  const url = `${baseUrl.replace(/\/$/, "")}${pathname}`;
+  const url = `${String(baseUrl || "").replace(/\/$/, "")}${pathname}`;
+  if (!baseUrl) {
+    throw new Error("Admin URL is missing. Pair this computer again.");
+  }
   const headers = {
     Accept: "application/json",
     "Content-Type": "application/json",
   };
   if (token) headers.Authorization = `Bearer ${token}`;
-  const res = await fetch(url, {
-    method,
-    headers,
-    body: body ? JSON.stringify(body) : undefined,
-  });
+  let res;
+  try {
+    res = await fetch(url, {
+      method,
+      headers,
+      body: body ? JSON.stringify(body) : undefined,
+    });
+  } catch (err) {
+    const detail = fetchErrorDetail(err);
+    throw new Error(
+      `Could not reach Maintainer Pro at ${url}${
+        detail ? ` (${detail})` : ""
+      }. Is the admin server running?`
+    );
+  }
   const text = await res.text();
   let data = null;
   try {
@@ -163,6 +235,28 @@ async function api(baseUrl, token, method, pathname, body) {
   return data;
 }
 
+async function reportActionProgress(cfg, actionId, message) {
+  const text = String(message || "").trim();
+  if (!text) return;
+  log(text);
+  if (!cfg?.adminUrl || !cfg.token || !actionId) return;
+  try {
+    await api(
+      cfg.adminUrl,
+      cfg.token,
+      "POST",
+      `/api/v1/bridge/machine/actions/${actionId}/progress`,
+      { message: text }
+    );
+  } catch (err) {
+    warn(
+      `progress report failed: ${
+        err instanceof Error ? err.message : String(err)
+      }`
+    );
+  }
+}
+
 /** @type {Promise<typeof import("@maintainer-pro/ai-cli")> | null} */
 let aiCliModule = null;
 
@@ -183,18 +277,31 @@ async function loadAiCli() {
   return aiCliModule;
 }
 
+/** @type {{ at: number, ids: string[] } | null} */
+let cliProviderCache = null;
+
 async function detectCliProviders() {
+  if (cliProviderCache && Date.now() - cliProviderCache.at < 60_000) {
+    return cliProviderCache.ids;
+  }
   try {
     const { resolveProvider } = await loadAiCli();
     const provider = await resolveProvider({ preference: "auto" });
-    return [provider.id];
+    cliProviderCache = { at: Date.now(), ids: [provider.id] };
+    return cliProviderCache.ids;
   } catch {
-    return [];
+    cliProviderCache = { at: Date.now(), ids: [] };
+    return cliProviderCache.ids;
   }
 }
 
 function applyProjectInfo(ws, info, cfg) {
   if (!ws || !info) return;
+  const folder = path.resolve(ws.folderPath || "");
+  const fingerprint =
+    typeof info.fingerprint === "string" && info.fingerprint
+      ? info.fingerprint
+      : projectFingerprint(folder);
   ws.projectInfo = {
     kind: info.kind,
     name: info.name,
@@ -205,6 +312,8 @@ function applyProjectInfo(ws, info, cfg) {
     fixes: info.fixes || [],
     ready: Boolean(info.ready),
     provider: info.provider,
+    fingerprint,
+    inspectedAt: info.inspectedAt || new Date().toISOString(),
   };
   if (info.kind) ws.clientKind = info.kind;
   const uiPort = Number(info.ports?.ui || info.ports?.app);
@@ -217,9 +326,144 @@ function applyProjectInfo(ws, info, cfg) {
   persistWorkspaceEntry(cfg, ws);
 }
 
+const PROJECT_INSPECT_CACHE = "project-inspect.json";
+
+function projectInspectCachePath(folder) {
+  return path.join(folder, ".maintainer-pro", PROJECT_INSPECT_CACHE);
+}
+
+/** Invalidate cache when package.json / common config files change. */
+function projectFingerprint(folder) {
+  const resolved = path.resolve(folder || "");
+  /** @type {string[]} */
+  const parts = [];
+  for (const rel of [
+    "package.json",
+    "package-lock.json",
+    "pnpm-lock.yaml",
+    "yarn.lock",
+    "vite.config.ts",
+    "vite.config.js",
+    "vite.config.mjs",
+    "next.config.js",
+    "next.config.mjs",
+    "next.config.ts",
+  ]) {
+    const file = path.join(resolved, rel);
+    if (!fs.existsSync(file)) continue;
+    try {
+      const st = fs.statSync(file);
+      parts.push(`${rel}:${st.size}:${Math.floor(st.mtimeMs)}`);
+    } catch {
+      /* ignore */
+    }
+  }
+  try {
+    const pkg = JSON.parse(
+      fs.readFileSync(path.join(resolved, "package.json"), "utf8")
+    );
+    parts.push(`name:${pkg.name || ""}`);
+    parts.push(`scripts:${JSON.stringify(pkg.scripts || {})}`);
+  } catch {
+    /* ignore */
+  }
+  return createHash("sha256").update(parts.join("|") || resolved).digest("hex").slice(0, 32);
+}
+
+function usableCachedProjectInfo(info) {
+  if (!info || typeof info !== "object") return false;
+  const scripts = info.scripts && typeof info.scripts === "object" ? info.scripts : {};
+  const hasScript = Boolean(scripts.ui || scripts.app || scripts.backend);
+  const hasKind = typeof info.kind === "string" && info.kind.length > 0;
+  return hasKind || hasScript || Boolean(info.summary);
+}
+
+function readProjectInspectCache(folder) {
+  const resolved = path.resolve(folder || "");
+  try {
+    const file = projectInspectCachePath(resolved);
+    if (!fs.existsSync(file)) return null;
+    const data = JSON.parse(fs.readFileSync(file, "utf8"));
+    if (!data || typeof data !== "object") return null;
+    if (!usableCachedProjectInfo(data.projectInfo)) return null;
+    const fingerprint = projectFingerprint(resolved);
+    if (data.fingerprint && data.fingerprint !== fingerprint) return null;
+    return {
+      ...data.projectInfo,
+      fingerprint,
+      inspectedAt: data.inspectedAt || data.projectInfo?.inspectedAt,
+      cached: true,
+    };
+  } catch {
+    return null;
+  }
+}
+
+function writeProjectInspectCache(folder, info) {
+  const resolved = path.resolve(folder || "");
+  if (!info || !usableCachedProjectInfo(info)) return;
+  try {
+    const dir = path.join(resolved, ".maintainer-pro");
+    fs.mkdirSync(dir, { recursive: true });
+    const fingerprint = projectFingerprint(resolved);
+    const payload = {
+      version: 1,
+      fingerprint,
+      inspectedAt: new Date().toISOString(),
+      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,
+      },
+    };
+    fs.writeFileSync(
+      projectInspectCachePath(resolved),
+      `${JSON.stringify(payload, null, 2)}\n`,
+      "utf8"
+    );
+  } catch (err) {
+    warn(
+      `could not write project inspect cache: ${
+        err instanceof Error ? err.message : String(err)
+      }`
+    );
+  }
+}
+
+/**
+ * Resolve project inspect info: prefer on-disk / config cache, else ask ai-cli.
+ * Pass `force: true` to always re-run analysis (recheck / failed start retry).
+ */
 async function inspectProjectWithAiCli(ws, opts = {}) {
   const folder = path.resolve(ws.folderPath || "");
   const label = ws.sandboxName || ws.applicationName || "this sandbox";
+  const force = Boolean(opts.force);
+
+  if (!force) {
+    const fingerprint = projectFingerprint(folder);
+    const fromDisk = readProjectInspectCache(folder);
+    const fromWs =
+      usableCachedProjectInfo(ws.projectInfo) &&
+      (!ws.projectInfo.fingerprint ||
+        ws.projectInfo.fingerprint === fingerprint)
+        ? ws.projectInfo
+        : null;
+    const cached = fromDisk || fromWs;
+    if (cached) {
+      log(`using cached project inspect for ${folder}`);
+      applyProjectInfo(ws, { ...cached, fingerprint }, opts.cfg);
+      if (!fromDisk) writeProjectInspectCache(folder, cached);
+      clearProcessProblem(ws.sandboxId, "project_issue", "inspect");
+      return { ...cached, fingerprint, cached: true };
+    }
+  }
+
   try {
     const { inspectAndRepairWorkspace } = await loadAiCli();
     log(`asking ai-cli to inspect ${folder}`);
@@ -229,7 +473,9 @@ async function inspectProjectWithAiCli(ws, opts = {}) {
       problem: opts.problem,
       extraContext: opts.extraContext,
     });
-    applyProjectInfo(ws, info, opts.cfg);
+    const fingerprint = projectFingerprint(folder);
+    applyProjectInfo(ws, { ...info, fingerprint }, opts.cfg);
+    writeProjectInspectCache(folder, info);
     if (info.issues?.length) {
       recordProcessProblem({
         sandboxId: ws.sandboxId,
@@ -239,17 +485,26 @@ async function inspectProjectWithAiCli(ws, opts = {}) {
         message: info.issues.join(" "),
         resolution: info.fixes?.length
           ? info.fixes.join(" ")
-          : "Fix the project in that folder, then use Start chat server.",
+          : "Fix the project in that folder, then use Start Apps.",
       });
     } else {
       clearProcessProblem(ws.sandboxId, "project_issue", "inspect");
     }
     if (info.summary) log(`ai-cli: ${info.summary}`);
     if (info.fixes?.length) log(`ai-cli fixes: ${info.fixes.join("; ")}`);
-    return info;
+    return { ...info, fingerprint, cached: false };
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
     warn(`ai-cli inspect failed: ${message}`);
+    // Fall back to any stale cache so Start Apps can still try.
+    const fallback =
+      readProjectInspectCache(folder) ||
+      (usableCachedProjectInfo(ws.projectInfo) ? ws.projectInfo : null);
+    if (fallback) {
+      warn(`falling back to cached project inspect after ai-cli error`);
+      applyProjectInfo(ws, fallback, opts.cfg);
+      return { ...fallback, cached: true };
+    }
     recordProcessProblem({
       sandboxId: ws.sandboxId,
       code: "project_issue",
@@ -287,152 +542,1326 @@ async function findFreePort(preferred = 3100, reserved = new Set()) {
       reserved.add(port);
       return port;
     }
-    port += 1;
+    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 `http://localhost:${port}`;
+  }
+}
+
+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) {
+  return new Promise((resolve) => {
+    let settled = false;
+    const done = (ok) => {
+      if (settled) return;
+      settled = true;
+      resolve(ok);
+    };
+    try {
+      const parsed = new URL(String(url));
+      const lib = parsed.protocol === "https:" ? https : http;
+      const req = lib.get(
+        parsed,
+        {
+          timeout: timeoutMs,
+          rejectUnauthorized: true,
+          headers: { Accept: "*/*" },
+        },
+        (res) => {
+          res.resume();
+          done(Boolean(res.statusCode && res.statusCode < 500));
+        }
+      );
+      req.on("error", () => done(false));
+      req.on("timeout", () => {
+        req.destroy();
+        done(false);
+      });
+    } catch {
+      done(false);
+    }
+  });
+}
+
+function fetchText(url, timeoutMs = 8000) {
+  return new Promise((resolve) => {
+    try {
+      const parsed = new URL(String(url));
+      const lib = parsed.protocol === "https:" ? https : http;
+      const req = lib.get(
+        parsed,
+        {
+          timeout: timeoutMs,
+          rejectUnauthorized: true,
+          headers: { Accept: "*/*" },
+        },
+        (res) => {
+          /** @type {Buffer[]} */
+          const chunks = [];
+          res.on("data", (chunk) => chunks.push(chunk));
+          res.on("end", () => {
+            if (!res.statusCode || res.statusCode >= 500) {
+              resolve(null);
+              return;
+            }
+            resolve(Buffer.concat(chunks).toString("utf8"));
+          });
+        }
+      );
+      req.on("error", () => resolve(null));
+      req.on("timeout", () => {
+        req.destroy();
+        resolve(null);
+      });
+    } catch {
+      resolve(null);
+    }
+  });
+}
+
+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 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,
+      parent: path.dirname(resolved),
+      home,
+      entries: [],
+    };
+  }
+  const names = fs.readdirSync(resolved);
+  const entries = [];
+  for (const name of names) {
+    if (name === "node_modules" || name === ".git") continue;
+    const full = path.join(resolved, name);
+    try {
+      const st = fs.statSync(full);
+      entries.push({
+        name,
+        path: full,
+        isDir: st.isDirectory(),
+      });
+    } catch {
+      /* skip */
+    }
+  }
+  entries.sort((a, b) => {
+    if (a.isDir !== b.isDir) return a.isDir ? -1 : 1;
+    return a.name.localeCompare(b.name);
+  });
+  const parent = path.dirname(resolved);
+  return {
+    path: resolved,
+    parent: parent === resolved ? null : parent,
+    home,
+    entries: entries.slice(0, 400),
+  };
+}
+
+function readEnvFile(file) {
+  /** @type {Record<string, string>} */
+  const map = {};
+  if (!fs.existsSync(file)) return map;
+  for (const raw of fs.readFileSync(file, "utf8").split(/\r?\n/)) {
+    const line = raw.trim();
+    if (!line || line.startsWith("#")) continue;
+    const eq = line.indexOf("=");
+    if (eq < 1) continue;
+    map[line.slice(0, eq).trim()] = line.slice(eq + 1).trim();
+  }
+  return map;
+}
+
+function mergeEnvFile(file, values, opts = {}) {
+  const map = readEnvFile(file);
+  for (const key of opts.remove || []) {
+    delete map[key];
+  }
+  for (const [k, v] of Object.entries(values)) {
+    map[k] = String(v);
+  }
+  const body = Object.entries(map)
+    .map(([k, v]) => `${k}=${v}`)
+    .join("\n");
+  fs.writeFileSync(file, body + "\n", "utf8");
+}
+
+function writeProjectEnv(folder, values, opts = {}) {
+  const remove = opts.remove || [];
+  const next = values && typeof values === "object" ? values : {};
+  if (!folder || (!Object.keys(next).length && !remove.length)) return;
+  mergeEnvFile(path.join(folder, ".env"), next, { remove });
+  const localValues = {};
+  for (const [key, value] of Object.entries(next)) {
+    if (
+      key === "PORT" ||
+      key === "APP_URL" ||
+      key === "PUBLIC_URL" ||
+      key === "CORS_ORIGIN" ||
+      key === "AI_SERVER_URL" ||
+      key.startsWith("NEXT_PUBLIC_") ||
+      key.startsWith("VITE_") ||
+      key.startsWith("REACT_APP_")
+    ) {
+      localValues[key] = value;
+    }
+  }
+  const localRemove = remove.filter(
+    (key) =>
+      key === "PORT" ||
+      key === "APP_URL" ||
+      key === "PUBLIC_URL" ||
+      key === "CORS_ORIGIN" ||
+      key === "AI_SERVER_URL" ||
+      key.startsWith("NEXT_PUBLIC_") ||
+      key.startsWith("VITE_") ||
+      key.startsWith("REACT_APP_")
+  );
+  if (Object.keys(localValues).length || localRemove.length) {
+    mergeEnvFile(path.join(folder, ".env.local"), localValues, {
+      remove: localRemove,
+    });
+  }
+  const keys = Object.entries(next)
+    .map(([key, value]) => `${key}=${value}`)
+    .join(" ");
+  log(
+    `env write ${folder} .env${
+      Object.keys(localValues).length || localRemove.length
+        ? " +.env.local"
+        : ""
+    }${remove.length ? ` remove=${remove.join(",")}` : ""}${
+      keys ? ` ${keys}` : ""
+    }`
+  );
+}
+
+function originFromUrl(value) {
+  try {
+    return new URL(String(value || "").trim()).origin;
+  } catch {
+    return null;
+  }
+}
+
+function readProjectEnvValues(folder) {
+  /** @type {Record<string, string>} */
+  const map = {};
+  if (!folder) return map;
+  const resolved = path.resolve(folder);
+  for (const name of [".env", ".env.local"]) {
+    Object.assign(map, readEnvFile(path.join(resolved, name)));
+  }
+  return map;
+}
+
+function isTryCloudflareUrl(value) {
+  try {
+    return new URL(String(value || "").trim()).hostname.endsWith(
+      ".trycloudflare.com"
+    );
+  } catch {
+    return false;
+  }
+}
+
+function normalizePublicOrigin(value) {
+  const origin = originFromUrl(value);
+  return origin || null;
+}
+
+function readCloudflareTunnelFile(folder) {
+  if (!folder) return null;
+  const file = path.join(path.resolve(folder), ".cloudflare-tunnel-url");
+  if (!fs.existsSync(file)) return null;
+  /** @type {Record<string, string>} */
+  const tunnels = {};
+  for (const raw of fs.readFileSync(file, "utf8").split(/\r?\n/)) {
+    const line = raw.trim();
+    if (!line || line.startsWith("#")) continue;
+    const eq = line.indexOf("=");
+    if (eq < 1) continue;
+    const role = line.slice(0, eq).trim();
+    const url = line.slice(eq + 1).trim().replace(/\/$/, "");
+    if (role && isTryCloudflareUrl(url)) tunnels[role] = url;
+  }
+  return Object.keys(tunnels).length ? tunnels : null;
+}
+
+function clearCloudflareTunnelFile(folder) {
+  if (!folder) return;
+  const file = path.join(path.resolve(folder), ".cloudflare-tunnel-url");
+  try {
+    if (fs.existsSync(file)) fs.unlinkSync(file);
+  } catch {
+    /* ignore */
+  }
+}
+
+/** Stop rediscovering dead trycloudflare URLs from old cloudflared logs. */
+function archiveStaleCloudflareLogs(folder) {
+  if (!folder) return;
+  const logDir = path.join(path.resolve(folder), ".maintainer-pro");
+  if (!fs.existsSync(logDir)) return;
+  let names = [];
+  try {
+    names = fs.readdirSync(logDir);
+  } catch {
+    return;
+  }
+  for (const name of names) {
+    if (!/^cf-.*\.log$/i.test(name) || name.endsWith(".stale")) continue;
+    try {
+      fs.renameSync(
+        path.join(logDir, name),
+        path.join(logDir, `${name}.stale`)
+      );
+    } catch {
+      /* ignore */
+    }
+  }
+}
+
+const CLOUDFLARE_ENV_KEYS = [
+  "APP_URL",
+  "PUBLIC_URL",
+  "CORS_ORIGIN",
+  "NEXT_PUBLIC_APP_URL",
+  "VITE_APP_URL",
+  "REACT_APP_APP_URL",
+  "AI_SERVER_URL",
+  "NEXT_PUBLIC_AI_SERVER_URL",
+  "VITE_AI_SERVER_URL",
+  "REACT_APP_AI_SERVER_URL",
+  "API_URL",
+  "API_BASE_URL",
+  "VITE_API_URL",
+  "VITE_API_BASE_URL",
+  "NEXT_PUBLIC_API_URL",
+  "NEXT_PUBLIC_API_BASE_URL",
+  "BACKEND_URL",
+];
+
+/**
+ * Remove dead trycloudflare URLs from workspace state, tunnel file, env, and
+ * archived logs so heartbeats stop re-probing them.
+ */
+function purgeUnreachableCloudflare(ws, cfg, opts = {}) {
+  const folder = ws.folderPath ? path.resolve(ws.folderPath) : null;
+  const label = ws.sandboxName || shortId(ws.sandboxId) || "sandbox";
+  const deadUrls = (opts.deadUrls || [])
+    .map((u) => String(u || "").replace(/\/$/, ""))
+    .filter((u) => isTryCloudflareUrl(u));
+  const keep = opts.keep && typeof opts.keep === "object" ? opts.keep : null;
+
+  if (deadUrls.length) {
+    log(
+      `clearing stale Cloudflare for ${label}: ${deadUrls.join(", ")}`
+    );
+  } else {
+    log(`clearing stale Cloudflare for ${label}`);
+  }
+
+  ws.cloudflareUrl = null;
+  ws.cloudflare = keep && Object.keys(keep).length ? { ...keep } : null;
+  if (keep?.ui || keep?.ai) {
+    ws.cloudflareUrl = keep.ui || keep.ai;
+    ws.appUrl = keep.ui || keep.ai;
+  } else if (ws.appUrl && !isLocalAppUrl(ws.appUrl)) {
+    ws.appUrl = null;
+  }
+
+  if (ws.sandboxId && !(keep && Object.keys(keep).length)) {
+    cloudflareTunnels.delete(ws.sandboxId);
+  }
+
+  if (!folder || !fs.existsSync(folder)) {
+    persistWorkspaceEntry(cfg, ws);
+    return;
+  }
+
+  // Always archive cf-*.log so dead trycloudflare hosts are not rediscovered.
+  archiveStaleCloudflareLogs(folder);
+  if (keep && Object.keys(keep).length) {
+    writeTunnelEnv(ws, keep);
+  } else {
+    clearCloudflareTunnelFile(folder);
+  }
+
+  const current = readProjectEnvValues(folder);
+  /** @type {string[]} */
+  const remove = [];
+  for (const key of CLOUDFLARE_ENV_KEYS) {
+    const value = current[key];
+    if (!isTryCloudflareUrl(value)) continue;
+    const normalized = String(value).replace(/\/$/, "");
+    if (keep && Object.values(keep).some((u) => String(u).replace(/\/$/, "") === normalized)) {
+      continue;
+    }
+    remove.push(key);
+  }
+  if (remove.length) {
+    /** @type {Record<string, string>} */
+    const localFallback = {};
+    if (opts.localEnv && typeof opts.localEnv === "object") {
+      Object.assign(localFallback, opts.localEnv);
+    }
+    writeProjectEnv(folder, localFallback, { remove });
+  }
+
+  persistWorkspaceEntry(cfg, ws);
+}
+
+function parseAllTryCloudflareUrls(text) {
+  const matches = [
+    ...String(text || "").matchAll(
+      /https:\/\/[a-z0-9-]+\.trycloudflare\.com/gi
+    ),
+  ];
+  return matches.map((m) => m[0].replace(/\/$/, ""));
+}
+
+function lastTryCloudflareUrl(text) {
+  const all = parseAllTryCloudflareUrls(text);
+  return all.length ? all[all.length - 1] : null;
+}
+
+/**
+ * Discover Cloudflare tunnel URLs from bridge state, tunnel file, project env,
+ * and cloudflared log files — even if this bridge process did not start them.
+ * @returns {Record<string, string> | null}
+ */
+function discoverCloudflareTunnels(ws) {
+  if (!ws?.folderPath) return null;
+  const folder = path.resolve(ws.folderPath);
+  /** @type {Record<string, string>} */
+  const tunnels = {};
+  const setRole = (role, value) => {
+    if (!role || tunnels[role] || !isTryCloudflareUrl(value)) return;
+    tunnels[role] = String(value).replace(/\/$/, "");
+  };
+
+  if (ws.cloudflare && typeof ws.cloudflare === "object") {
+    for (const [role, value] of Object.entries(ws.cloudflare)) {
+      setRole(role, value);
+    }
+  }
+  if (ws.cloudflareUrl) setRole("ui", ws.cloudflareUrl);
+
+  const fromFile = readCloudflareTunnelFile(folder);
+  if (fromFile) {
+    for (const [role, value] of Object.entries(fromFile)) setRole(role, value);
+  }
+
+  const env = readProjectEnvValues(folder);
+  const envRoles = [
+    ["ai", env.NEXT_PUBLIC_AI_SERVER_URL],
+    ["ai", env.VITE_AI_SERVER_URL],
+    ["ai", env.AI_SERVER_URL],
+    ["ai", env.REACT_APP_AI_SERVER_URL],
+    ["ui", env.NEXT_PUBLIC_APP_URL],
+    ["ui", env.VITE_APP_URL],
+    ["ui", env.APP_URL],
+    ["ui", env.PUBLIC_URL],
+    ["backend", env.NEXT_PUBLIC_API_URL],
+    ["backend", env.VITE_API_URL],
+    ["backend", env.API_URL],
+  ];
+  for (const [role, value] of envRoles) setRole(role, value);
+
+  const logDir = path.join(folder, ".maintainer-pro");
+  if (fs.existsSync(logDir)) {
+    const sandboxPrefix = `cf-${String(ws.sandboxId || "").slice(0, 8)}-`;
+    let names = [];
+    try {
+      names = fs.readdirSync(logDir);
+    } catch {
+      names = [];
+    }
+    // Prefer sandbox-scoped logs, then any cf-*-role.log in the project.
+    const ranked = names
+      .filter((name) => /^cf-.*\.log$/i.test(name) && !name.endsWith(".stale"))
+      .sort((a, b) => {
+        const aScore = a.startsWith(sandboxPrefix) ? 0 : 1;
+        const bScore = b.startsWith(sandboxPrefix) ? 0 : 1;
+        return aScore - bScore || a.localeCompare(b);
+      });
+    for (const name of ranked) {
+      const roleMatch = name.match(
+        /cf-(?:[a-f0-9]{6,}-)?(ai|ui|backend|app)\.log$/i
+      );
+      if (!roleMatch) continue;
+      let role = roleMatch[1].toLowerCase();
+      if (role === "app") role = "ui";
+      if (tunnels[role]) continue;
+      try {
+        const text = fs.readFileSync(path.join(logDir, name), "utf8");
+        const url = lastTryCloudflareUrl(text);
+        if (url) setRole(role, url);
+      } catch {
+        /* ignore unreadable logs */
+      }
+    }
+  }
+
+  return Object.keys(tunnels).length ? tunnels : null;
+}
+
+function rememberCloudflareTunnels(sandboxId, tunnels) {
+  if (!sandboxId || !tunnels) return;
+  cloudflareTunnels.set(sandboxId, {
+    tunnels: Object.entries(tunnels)
+      .filter(([, url]) => Boolean(url))
+      .map(([role, publicUrl]) => ({
+        role,
+        localUrl: "",
+        publicUrl: String(publicUrl),
+        logFile: "",
+      })),
+  });
+}
+
+function cloudflareLive(ws) {
+  if (!ws?.sandboxId) return false;
+  if (ws.cloudflarePending) return false;
+  // Only tunnels managed in this process count as live. Persisted
+  // cloudflareUrl / discovered log URLs go stale when apps stop.
+  const row = cloudflareTunnels.get(ws.sandboxId);
+  return Boolean(
+    row?.tunnels?.some((t) => isTryCloudflareUrl(t.publicUrl))
+  );
+}
+
+function workspaceHostReport(ws) {
+  /** @type {string[]} */
+  const origins = [];
+  const add = (value) => {
+    const origin = originFromUrl(value);
+    if (origin && !origins.includes(origin)) origins.push(origin);
+  };
+  const env = readProjectEnvValues(ws.folderPath);
+  const discovered = discoverCloudflareTunnels(ws);
+  const liveCf = cloudflareLive(ws);
+  const chatPort = Number(env.AI_SERVER_PORT || ws.port);
+  const uiPort = Number(
+    env.PORT || ws.projectInfo?.ports?.ui || ws.projectInfo?.ports?.app
+  );
+  const cf =
+    liveCf || discovered
+      ? {
+          ...(typeof ws.cloudflare === "object" && ws.cloudflare
+            ? ws.cloudflare
+            : {}),
+          ...(discovered || {}),
+        }
+      : null;
+
+  if (cf && Object.keys(cf).length) {
+    add(ws.cloudflareUrl);
+    for (const value of Object.values(cf)) add(value);
+    add(env.NEXT_PUBLIC_AI_SERVER_URL);
+    add(env.AI_SERVER_URL);
+    add(env.APP_URL);
+    add(env.NEXT_PUBLIC_APP_URL);
+  } else {
+    for (const value of [
+      env.CORS_ORIGIN,
+      env.APP_URL,
+      env.NEXT_PUBLIC_APP_URL,
+      env.PUBLIC_URL,
+      ws.appUrl,
+    ]) {
+      if (value && isLocalAppUrl(value)) add(value);
+    }
+    add(env.AI_SERVER_URL);
+    add(env.NEXT_PUBLIC_AI_SERVER_URL);
+  }
+  if (chatPort) {
+    add(`http://localhost:${chatPort}`);
+    add(`http://127.0.0.1:${chatPort}`);
+  }
+  if (uiPort) {
+    add(`http://localhost:${uiPort}`);
+    add(`http://127.0.0.1:${uiPort}`);
+  }
+
+  let appUrl = null;
+  if (cf?.ui && isTryCloudflareUrl(cf.ui)) {
+    appUrl = normalizePublicOrigin(cf.ui);
+  } else if (ws.cloudflareUrl && isTryCloudflareUrl(ws.cloudflareUrl)) {
+    appUrl = normalizePublicOrigin(ws.cloudflareUrl);
+  } else if (cf?.ai && isTryCloudflareUrl(cf.ai)) {
+    appUrl = normalizePublicOrigin(cf.ai);
+  } else if (env.APP_URL && isLocalAppUrl(env.APP_URL)) {
+    appUrl = originFromUrl(env.APP_URL);
+  } else if (ws.appUrl && isLocalAppUrl(ws.appUrl)) {
+    appUrl = originFromUrl(ws.appUrl) || ws.appUrl;
+  } else if (uiPort) {
+    appUrl = `http://localhost:${uiPort}`;
+  } else if (chatPort) {
+    appUrl = `http://localhost:${chatPort}`;
+  }
+  return { appUrl, origins };
+}
+
+/**
+ * Probe discovered public URLs and keep only ones that respond.
+ * @returns {Promise<{ live: Record<string, string> | null, dead: Record<string, string> }>}
+ */
+async function filterReachableCloudflareTunnels(tunnels) {
+  /** @type {Record<string, string>} */
+  const live = {};
+  /** @type {Record<string, string>} */
+  const dead = {};
+  if (!tunnels || !Object.keys(tunnels).length) {
+    return { live: null, dead };
+  }
+  for (const [role, url] of Object.entries(tunnels)) {
+    if (!isTryCloudflareUrl(url)) continue;
+    const normalized = String(url).replace(/\/$/, "");
+    const target =
+      role === "ai"
+        ? `${normalized}/embed-config.js`
+        : normalized;
+    if (await probeUrl(target, 8_000)) {
+      live[role] = normalized;
+    } else {
+      dead[role] = normalized;
+    }
+  }
+  return {
+    live: Object.keys(live).length ? live : null,
+    dead,
+  };
+}
+
+function envNeedsUpdate(folder, desired) {
+  if (!desired || !Object.keys(desired).length) return false;
+  const current = readProjectEnvValues(folder);
+  return Object.entries(desired).some(
+    ([key, value]) => String(current[key] || "") !== String(value)
+  );
+}
+
+/**
+ * Status-only reconcile for a workspace:
+ * 1) probe chat / ui / backend
+ * 2) detect reachable Cloudflare (never starts tunnels)
+ * 3) sync base URLs in env when mode or ports changed
+ * 4) compute host appUrl + CORS origins for Maintainer Pro
+ *
+ * Does not start apps or Cloudflare.
+ */
+async function reconcileWorkspacePresence(ws, cfg, opts = {}) {
+  const label = ws.sandboxName || shortId(ws.sandboxId) || "sandbox";
+  const writeEnv = opts.writeEnv !== false;
+  const timeoutMs = opts.timeoutMs || 800;
+  const folder = path.resolve(ws.folderPath || "");
+
+  // 1. Local process probes
+  const probe = await probeRunningApps(ws, timeoutMs);
+  if (probe.chatUp && Number(ws.port) !== probe.chatPort) {
+    ws.port = probe.chatPort;
+  }
+
+  // 2. Cloudflare detection (never starts tunnels). Purge stale URLs so we
+  // do not keep re-probing dead trycloudflare links from env/logs every tick.
+  const discovered = discoverCloudflareTunnels(ws);
+  const cfCheck = discovered
+    ? await filterReachableCloudflareTunnels(discovered)
+    : { live: null, dead: {} };
+  const reachableCf = cfCheck.live;
+  const deadCf = cfCheck.dead;
+  const managedLive = cloudflareLive(ws);
+
+  if (Object.keys(deadCf).length > 0) {
+    /** @type {Record<string, string>} */
+    let localEnv = {};
+    if (probe.running) {
+      const jobs = probe.hosts
+        .filter((h) => h.up)
+        .map((h) => ({ role: h.role, port: h.port, preferredPort: h.port }));
+      localEnv = envForWorkspacePorts(ws, jobs);
+    }
+    /** @type {Record<string, string> | null} */
+    let keep = reachableCf;
+    if (!keep && managedLive) {
+      const managed = {};
+      for (const t of cloudflareTunnels.get(ws.sandboxId)?.tunnels || []) {
+        if (t?.role && isTryCloudflareUrl(t.publicUrl)) {
+          managed[t.role] = String(t.publicUrl).replace(/\/$/, "");
+        }
+      }
+      keep = Object.keys(managed).length ? managed : null;
+    }
+    purgeUnreachableCloudflare(ws, cfg, {
+      deadUrls: Object.values(deadCf),
+      keep,
+      localEnv,
+    });
+  }
+
+  const usingCloudflare = Boolean(
+    managedLive || (reachableCf && Object.keys(reachableCf).length)
+  );
+
+  if (reachableCf) {
+    ws.cloudflare = { ...(ws.cloudflare || {}), ...reachableCf };
+    ws.cloudflareUrl = reachableCf.ui || reachableCf.ai || ws.cloudflareUrl || null;
+    if (reachableCf.ui || reachableCf.ai) {
+      ws.appUrl = reachableCf.ui || reachableCf.ai;
+    }
+  } else if (!managedLive) {
+    ws.cloudflareUrl = null;
+    ws.cloudflare = null;
+    if (ws.appUrl && !isLocalAppUrl(ws.appUrl)) ws.appUrl = null;
+  }
+
+  const cfTunnels =
+    usingCloudflare
+      ? {
+          ...(typeof ws.cloudflare === "object" && ws.cloudflare
+            ? ws.cloudflare
+            : {}),
+          ...(reachableCf || {}),
+        }
+      : null;
+
+  // 3. Sync env base URLs when apps are up or Cloudflare is live
+  if (writeEnv && folder && fs.existsSync(folder)) {
+    /** @type {Record<string, string>} */
+    let desired = {};
+    if (cfTunnels && Object.keys(cfTunnels).length) {
+      desired = {
+        ...uiPublicEnv(cfTunnels),
+        AI_SERVER_PORT: String(probe.chatPort || ws.port || 3100),
+      };
+      if (probe.hosts.some((h) => h.role === "ui" || h.role === "app")) {
+        const ui = probe.hosts.find(
+          (h) => (h.role === "ui" || h.role === "app") && h.up
+        );
+        if (ui?.port) desired.PORT = String(ui.port);
+      }
+      if (envNeedsUpdate(folder, desired)) {
+        log(
+          `env sync ${label}: cloudflare urls (${Object.keys(cfTunnels).join(",")})`
+        );
+        writeTunnelEnv(ws, cfTunnels);
+        writeProjectEnv(folder, desired);
+      }
+    } else if (probe.running) {
+      const jobs = probe.hosts
+        .filter((h) => h.up)
+        .map((h) => ({ role: h.role, port: h.port, preferredPort: h.port }));
+      desired = envForWorkspacePorts(ws, jobs);
+      // Drop stale trycloudflare values when running local-only.
+      const current = readProjectEnvValues(folder);
+      /** @type {string[]} */
+      const remove = [];
+      for (const key of [
+        "APP_URL",
+        "PUBLIC_URL",
+        "CORS_ORIGIN",
+        "NEXT_PUBLIC_APP_URL",
+        "VITE_APP_URL",
+        "AI_SERVER_URL",
+        "NEXT_PUBLIC_AI_SERVER_URL",
+        "VITE_AI_SERVER_URL",
+        "REACT_APP_AI_SERVER_URL",
+        "API_URL",
+        "VITE_API_URL",
+        "NEXT_PUBLIC_API_URL",
+      ]) {
+        if (isTryCloudflareUrl(current[key]) && desired[key]) {
+          // overwritten by desired
+        } else if (isTryCloudflareUrl(current[key]) && !desired[key]) {
+          remove.push(key);
+        }
+      }
+      if (envNeedsUpdate(folder, desired) || remove.length) {
+        log(`env sync ${label}: local app urls`);
+        writeProjectEnv(folder, desired, { remove });
+      }
+    }
+  }
+
+  // 4. Host + CORS origins for Maintainer Pro
+  const host = workspaceHostReport(ws);
+  if (cfTunnels?.ui && isTryCloudflareUrl(cfTunnels.ui)) {
+    host.appUrl = normalizePublicOrigin(cfTunnels.ui);
+  } else if (cfTunnels?.ai && isTryCloudflareUrl(cfTunnels.ai)) {
+    host.appUrl = normalizePublicOrigin(cfTunnels.ai);
+  } else if (probe.running) {
+    const ui = probe.hosts.find(
+      (h) => (h.role === "ui" || h.role === "app") && h.up
+    );
+    if (ui?.port) {
+      host.appUrl = `http://localhost:${ui.port}`;
+    } else if (probe.chatUp) {
+      host.appUrl = `http://localhost:${probe.chatPort}`;
+    }
+  }
+
+  // Ensure probed local origins are always included when processes are up.
+  for (const h of probe.hosts) {
+    if (!h.up || !h.port) continue;
+    const origin = `http://localhost:${h.port}`;
+    if (!host.origins.includes(origin)) host.origins.push(origin);
+    const loopback = `http://127.0.0.1:${h.port}`;
+    if (!host.origins.includes(loopback)) host.origins.push(loopback);
+  }
+  if (probe.chatUp) {
+    const chatOrigin = `http://localhost:${probe.chatPort}`;
+    if (!host.origins.includes(chatOrigin)) host.origins.push(chatOrigin);
+  }
+  if (cfTunnels) {
+    for (const value of Object.values(cfTunnels)) {
+      const origin = normalizePublicOrigin(value);
+      if (origin && !host.origins.includes(origin)) host.origins.push(origin);
+    }
+  }
+
+  if (host.appUrl) ws.appUrl = host.appUrl;
+
+  if (probe.running) {
+    clearProcessProblem(ws.sandboxId, "ai_server_launch", "ai");
+    clearProcessProblem(ws.sandboxId, "apps_not_started");
+    clearProcessProblem(ws.sandboxId, "ai_server_down", "ai");
+    for (const h of probe.hosts) {
+      if (!h.up) continue;
+      clearProcessProblem(ws.sandboxId, "host_process_launch", h.role);
+      clearProcessProblem(ws.sandboxId, "host_process_down", h.role);
+    }
+  }
+
+  persistWorkspaceEntry(cfg, ws);
+
+  return {
+    probe,
+    usingCloudflare,
+    cloudflare: cfTunnels,
+    host,
+    appsRunning: probe.running,
+    aiServerUp: probe.chatUp,
+  };
+}
+
+async function reconcileCloudflareState(ws, cfg) {
+  const status = await reconcileWorkspacePresence(ws, cfg, {
+    writeEnv: true,
+    timeoutMs: 2500,
+  });
+  return status.usingCloudflare;
+}
+
+/**
+ * If Cloudflare is already running for this folder, attach and share with MP
+ * instead of creating new tunnels.
+ */
+async function tryAttachExistingCloudflare(ws, cfg, opts = {}) {
+  const progress =
+    typeof opts.onProgress === "function" ? opts.onProgress : async () => {};
+  const label = ws.sandboxName || shortId(ws.sandboxId) || "sandbox";
+  await progress(
+    "Looking for Cloudflare tunnels that are already running for this project…"
+  );
+  const discovered = discoverCloudflareTunnels(ws);
+  if (!discovered) {
+    await progress("No existing Cloudflare tunnel URLs found yet.");
+    return null;
+  }
+  await progress(
+    `Found candidate tunnels: ${Object.entries(discovered)
+      .map(([role, url]) => `${role}=${url}`)
+      .join(", ")}`
+  );
+  const { live, dead } = await filterReachableCloudflareTunnels(discovered);
+  if (!live || (!live.ai && !live.ui)) {
+    if (Object.keys(dead).length) {
+      purgeUnreachableCloudflare(ws, cfg, {
+        deadUrls: Object.values(dead),
+      });
+    }
+    await progress(
+      "Those Cloudflare URLs did not respond — will create fresh tunnels."
+    );
+    return null;
+  }
+
+  writeTunnelEnv(ws, live);
+  // Make sure the chat script advertises the public AI URL when we have one.
+  if (live.ai) {
+    const reserved = reservedPortsFor(cfg, ws.sandboxId);
+    const up = await probeUrl(
+      `http://127.0.0.1:${Number(ws.port) || 3100}/embed-config.js`
+    );
+    if (up) {
+      launchedAt.delete(`${ws.sandboxId}:${path.resolve(ws.folderPath)}:ai`);
+      await killPort(ws.port);
+      await sleep(1200);
+    }
+    await startAiServerForWorkspace(ws, {
+      reserved,
+      cfg,
+      port: ws.port,
+      env: uiPublicEnv(live),
+    });
+    await waitUntilReachable(
+      `http://127.0.0.1:${ws.port}/embed-config.js`,
+      45_000,
+      "the chat script",
+      progress
+    );
+  }
+
+  const validation = await validateCloudflareGoLive(ws, live, {
+    onProgress: progress,
+  });
+  if (!validation.ok) {
+    await progress(
+      "Existing tunnels failed go-live checks — will recreate if needed."
+    );
+    return null;
+  }
+
+  const appUrl = live.ui || live.ai;
+  ws.cloudflareUrl = appUrl;
+  ws.cloudflare = live;
+  ws.appUrl = appUrl;
+  ws.cloudflarePending = false;
+  ws.appsRequested = true;
+  persistWorkspaceEntry(cfg, ws);
+  rememberCloudflareTunnels(ws.sandboxId, live);
+  clearProcessProblem(ws.sandboxId, "cloudflare_launch", "tunnel");
+  const host = workspaceHostReport(ws);
+  await progress(`Attached to existing Cloudflare: ${host.appUrl || appUrl}`);
+  log(`cloudflare attached (reuse) ${label}: ${appUrl}`);
+
+  return {
+    sandboxId: ws.sandboxId,
+    folderPath: ws.folderPath,
+    port: ws.port,
+    appUrl: host.appUrl || appUrl,
+    origins: host.origins.length
+      ? host.origins
+      : Object.values(live).filter(Boolean),
+    tunnels: live,
+    validation,
+    cloudflare: true,
+    reused: true,
+    attached: true,
+  };
+}
+
+function clearStaleCloudflare(ws) {
+  if (cloudflareLive(ws)) return;
+  if (!ws.cloudflareUrl && !ws.cloudflare) return;
+  if (discoverCloudflareTunnels(ws)) return;
+  const label = ws.sandboxName || shortId(ws.sandboxId) || "sandbox";
+  log(`clearing stale Cloudflare URL for ${label}`);
+  ws.cloudflareUrl = null;
+  ws.cloudflare = null;
+  if (ws.appUrl && !isLocalAppUrl(ws.appUrl)) {
+    ws.appUrl = null;
+  }
+}
+
+async function probeHttpPaths(port, paths, timeoutMs = 2500) {
+  const n = Number(port);
+  if (!n) return false;
+  for (const host of ["127.0.0.1", "localhost"]) {
+    for (const suffix of paths) {
+      if (await probeUrl(`http://${host}:${n}${suffix}`, timeoutMs)) return true;
+    }
+  }
+  return false;
+}
+
+async function discoverChatPort(ws, timeoutMs = 2500) {
+  const env = readProjectEnvValues(ws.folderPath);
+  const candidates = [
+    Number(ws.port),
+    Number(env.AI_SERVER_PORT),
+    portFromText(env.AI_SERVER_URL, 0),
+    portFromText(env.NEXT_PUBLIC_AI_SERVER_URL, 0),
+    3100,
+  ].filter((port) => port >= 1024);
+  const unique = [...new Set(candidates)];
+  const chatPaths = ["/embed-config.js", "/", "/health"];
+  for (const port of unique) {
+    if (await probeHttpPaths(port, chatPaths, timeoutMs)) {
+      return { port, up: true };
+    }
+  }
+  return { port: unique[0] || Number(ws.port) || 3100, up: false };
+}
+
+async function probeRunningApps(ws, timeoutMs = 2500) {
+  const folder = path.resolve(ws.folderPath || "");
+  const env = readProjectEnvValues(ws.folderPath);
+  const chat = await discoverChatPort(ws, timeoutMs);
+  if (chat.up && Number(ws.port) !== chat.port) {
+    ws.port = chat.port;
+  }
+  const jobs = planHostJobs(
+    folder,
+    ws.appUrl && isLocalAppUrl(ws.appUrl) ? ws.appUrl : null,
+    ws.projectInfo
+  );
+  /** @type {Array<{ role: string, port: number, up: boolean }>} */
+  const hosts = [];
+  for (const job of jobs) {
+    const candidates = [
+      Number(job.port),
+      Number(job.preferredPort),
+      Number(env.PORT),
+      portFromText(env.APP_URL, 0),
+      portFromText(ws.appUrl, 0),
+    ].filter((port) => port >= 1024);
+    const unique = [...new Set(candidates.length ? candidates : [3000])];
+    let up = false;
+    let port = unique[0];
+    for (const candidate of unique) {
+      const probe = (
+        job.probeUrl || `http://127.0.0.1:${candidate}`
+      ).replace("localhost", "127.0.0.1");
+      const ok =
+        (await probeUrl(probe, timeoutMs)) ||
+        (await probeHttpPaths(candidate, ["/"], timeoutMs));
+      if (ok) {
+        up = true;
+        port = candidate;
+        break;
+      }
+    }
+    hosts.push({ role: job.role, port, up });
   }
-  throw new Error("No free TCP port found");
+  return {
+    chatUp: chat.up,
+    chatPort: chat.port,
+    hosts,
+    running: chat.up || hosts.some((host) => host.up),
+  };
 }
 
-function urlWithPort(url, port) {
-  try {
-    const parsed = new URL(url);
-    parsed.port = String(port);
-    return parsed.toString().replace(/\/$/, "");
-  } catch {
-    return `http://localhost:${port}`;
+async function restoreHostsAfterReconnect(cfg) {
+  for (const ws of cfg.workspaces || []) {
+    const label = ws.sandboxName || shortId(ws.sandboxId) || "sandbox";
+    // Status-only: probe apps + Cloudflare, sync env/origins for MP.
+    // Never start apps or tunnels on reconnect.
+    const status = await reconcileWorkspacePresence(ws, cfg, {
+      writeEnv: true,
+      timeoutMs: 2500,
+    });
+    const hostSummary = status.probe.hosts
+      .map((host) => `${host.role}:${host.port}${host.up ? "(up)" : "(down)"}`)
+      .join(" ");
+    if (status.appsRunning) {
+      log(
+        `found running apps for ${label}: chat=${status.probe.chatPort}${
+          status.probe.chatUp ? "(up)" : "(down)"
+        }${hostSummary ? ` ${hostSummary}` : ""} cloudflare=${
+          status.usingCloudflare ? "yes" : "no"
+        } app=${status.host.appUrl || "(none)"} origins=${
+          status.host.origins.join(",") || "none"
+        }`
+      );
+    } else {
+      log(
+        `no apps running for ${label}${
+          status.usingCloudflare ? " (cloudflare urls present)" : ""
+        } — waiting for Start Apps from Maintainer Pro`
+      );
+    }
   }
 }
 
-function isLocalAppUrl(url) {
-  try {
-    const host = new URL(url).hostname;
-    return host === "localhost" || host === "127.0.0.1";
-  } catch {
-    return true;
+function envForWorkspacePorts(ws, jobs) {
+  const aiPort = Number(ws.port) || 3100;
+  const publicAi =
+    (typeof ws.cloudflare?.ai === "string" &&
+      isTryCloudflareUrl(ws.cloudflare.ai) &&
+      String(ws.cloudflare.ai).replace(/\/$/, "")) ||
+    "";
+  const ai = publicAi || `http://localhost:${aiPort}`;
+  /** @type {Record<string, string>} */
+  const env = {
+    AI_SERVER_PORT: String(aiPort),
+    AI_SERVER_URL: ai,
+    NEXT_PUBLIC_AI_SERVER_URL: ai,
+    VITE_AI_SERVER_URL: ai,
+    REACT_APP_AI_SERVER_URL: ai,
+  };
+  const ui = jobs.find((job) => job.role === "ui" || job.role === "app");
+  const publicUi =
+    (typeof ws.cloudflare?.ui === "string" &&
+      isTryCloudflareUrl(ws.cloudflare.ui) &&
+      String(ws.cloudflare.ui).replace(/\/$/, "")) ||
+    "";
+  if (publicUi) {
+    env.PORT = ui?.port ? String(ui.port) : env.PORT;
+    env.APP_URL = publicUi;
+    env.CORS_ORIGIN = publicUi;
+    env.PUBLIC_URL = publicUi;
+    env.NEXT_PUBLIC_APP_URL = publicUi;
+    env.VITE_APP_URL = publicUi;
+  } else if (ui?.port) {
+    const app = `http://localhost:${ui.port}`;
+    env.PORT = String(ui.port);
+    env.APP_URL = app;
+    env.CORS_ORIGIN = app;
+    env.NEXT_PUBLIC_APP_URL = app;
+    env.VITE_APP_URL = app;
   }
+  const backend = jobs.find((job) => job.role === "backend");
+  if (backend?.port) {
+    const publicBackend =
+      (typeof ws.cloudflare?.backend === "string" &&
+        isTryCloudflareUrl(ws.cloudflare.backend) &&
+        String(ws.cloudflare.backend).replace(/\/$/, "")) ||
+      "";
+    const api = publicBackend || `http://localhost:${backend.port}`;
+    env.API_URL = api;
+    env.API_PORT = String(backend.port);
+    env.VITE_API_URL = api;
+    env.NEXT_PUBLIC_API_URL = api;
+  }
+  return env;
 }
 
-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) {
-  return new Promise((resolve) => {
-    let settled = false;
-    const done = (ok) => {
-      if (settled) return;
-      settled = true;
-      resolve(ok);
-    };
-    try {
-      const req = http.get(url, { timeout: timeoutMs }, (res) => {
-        res.resume();
-        done(Boolean(res.statusCode && res.statusCode < 500));
-      });
-      req.on("error", () => done(false));
-      req.on("timeout", () => {
-        req.destroy();
-        done(false);
-      });
-    } catch {
-      done(false);
-    }
-  });
-}
+async function prepareWorkspaceLaunch(ws, cfg, reserved) {
+  const folder = path.resolve(ws.folderPath || "");
+  const label = ws.sandboxName || shortId(ws.sandboxId) || "sandbox";
+  if (!folder || !fs.existsSync(folder)) {
+    const aiPort = Number(ws.port) || 3100;
+    log(`ports skip ${label}: folder missing (${folder || "none"})`);
+    return { aiPort, jobs: [], env: {} };
+  }
+  log(`ports pick ${label} in ${folder}`);
+  const preferredAi = Number(ws.port) || 3100;
+  const aiUp = await probeUrl(
+    `http://127.0.0.1:${preferredAi}/embed-config.js`
+  );
+  const aiPort = aiUp
+    ? (reserved.add(preferredAi), preferredAi)
+    : await findFreePort(preferredAi, reserved);
+  log(
+    aiUp
+      ? `ports chat ${preferredAi} already up`
+      : aiPort === preferredAi
+        ? `ports chat ${aiPort} free`
+        : `ports chat ${preferredAi} busy; using ${aiPort}`
+  );
+  ws.port = aiPort;
 
-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 */
+  const jobs = planHostJobs(
+    folder,
+    ws.appUrl && isLocalAppUrl(ws.appUrl) ? ws.appUrl : null,
+    ws.projectInfo
+  );
+  log(
+    jobs.length
+      ? `ports jobs ${jobs.map((job) => `${job.role}:${job.script}:${job.preferredPort}`).join(" ")}`
+      : `ports jobs none`
+  );
+  const planned = [];
+  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 port = up
+      ? (reserved.add(portFromText(probe, preferred)), portFromText(probe, preferred))
+      : await findFreePort(preferred, reserved);
+    log(
+      up
+        ? `ports ${job.role} ${port} already up (${probe})`
+        : port === preferred
+          ? `ports ${job.role} ${port} free for ${job.script}`
+          : `ports ${job.role} ${preferred} busy; using ${port} for ${job.script}`
+    );
+    planned.push({ ...job, port, up });
+    if (
+      (job.role === "ui" || job.role === "app") &&
+      (!ws.appUrl || isLocalAppUrl(ws.appUrl))
+    ) {
+      ws.appUrl = urlWithPort(ws.appUrl || `http://localhost:${port}`, port);
     }
   }
-  return roots.length ? roots : ["C:\\"];
-}
 
-function listDirEntries(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 env = envForWorkspacePorts(ws, planned);
+  writeProjectEnv(folder, env);
+  if (planned.length) {
+    ws.projectInfo = {
+      ...(ws.projectInfo || {}),
+      ports: {
+        ...(ws.projectInfo?.ports || {}),
+        ...Object.fromEntries(planned.map((job) => [job.role, job.port])),
+      },
     };
   }
+  persistWorkspaceEntry(cfg, ws);
+  log(
+    `ports ready ${label}: chat=${aiPort}${planned
+      .map((job) => ` ${job.role}=${job.port}${job.up ? "(up)" : ""}`)
+      .join("")}`
+  );
+  return { aiPort, jobs: planned, env };
+}
 
-  const resolved = path.resolve(raw);
-  if (!fs.existsSync(resolved) || !fs.statSync(resolved).isDirectory()) {
-    return {
-      error: "Not a directory",
-      path: resolved,
-      parent: path.dirname(resolved),
-      home,
-      entries: [],
-    };
-  }
-  const names = fs.readdirSync(resolved);
-  const entries = [];
-  for (const name of names) {
-    if (name === "node_modules" || name === ".git") continue;
-    const full = path.join(resolved, name);
-    try {
-      const st = fs.statSync(full);
-      entries.push({
-        name,
-        path: full,
-        isDir: st.isDirectory(),
-      });
-    } catch {
-      /* skip */
-    }
+const ACCESS_IGNORE_BEGIN = "# maintainer-pro:access-begin";
+const ACCESS_IGNORE_END = "# maintainer-pro:access-end";
+const DEFAULT_AI_IGNORE_PATHS = [
+  ".env",
+  ".env.*",
+  "**/.env",
+  "**/.env.*",
+  ".maintainer-pro/",
+];
+
+function normalizeIgnorePaths(paths) {
+  /** @type {string[]} */
+  const out = [];
+  const seen = new Set();
+  for (const raw of paths || []) {
+    const p = String(raw || "")
+      .trim()
+      .replace(/\\/g, "/");
+    if (!p || p.startsWith("/") || p.includes("..")) continue;
+    if (seen.has(p)) continue;
+    seen.add(p);
+    out.push(p);
   }
-  entries.sort((a, b) => {
-    if (a.isDir !== b.isDir) return a.isDir ? -1 : 1;
-    return a.name.localeCompare(b.name);
-  });
-  const parent = path.dirname(resolved);
-  return {
-    path: resolved,
-    parent: parent === resolved ? null : parent,
-    home,
-    entries: entries.slice(0, 400),
-  };
+  return out;
 }
 
-function mergeEnvFile(file, values) {
-  /** @type {Record<string, string>} */
-  const map = {};
-  if (fs.existsSync(file)) {
-    for (const raw of fs.readFileSync(file, "utf8").split(/\r?\n/)) {
-      const line = raw.trim();
-      if (!line || line.startsWith("#")) continue;
-      const eq = line.indexOf("=");
-      if (eq < 1) continue;
-      map[line.slice(0, eq).trim()] = line.slice(eq + 1).trim();
-    }
+function resolveIgnorePaths(partnerPaths) {
+  return normalizeIgnorePaths([...DEFAULT_AI_IGNORE_PATHS, ...(partnerPaths || [])]);
+}
+
+function upsertManagedIgnoreFile(existing, ignorePaths) {
+  const block = [
+    ACCESS_IGNORE_BEGIN,
+    "# Managed by Maintainer Pro — do not edit this block by hand.",
+    ...ignorePaths,
+    ACCESS_IGNORE_END,
+    "",
+  ].join("\n");
+  const begin = existing.indexOf(ACCESS_IGNORE_BEGIN);
+  const end = existing.indexOf(ACCESS_IGNORE_END);
+  if (begin >= 0 && end > begin) {
+    const afterEnd = end + ACCESS_IGNORE_END.length;
+    const before = existing.slice(0, begin).replace(/\s+$/, "");
+    const after = existing.slice(afterEnd).replace(/^\r?\n/, "");
+    const parts = [before, block.trimEnd(), after.trimStart()].filter(Boolean);
+    return `${parts.join("\n\n")}\n`;
   }
-  for (const [k, v] of Object.entries(values)) {
-    map[k] = String(v);
+  const trimmed = existing.replace(/\s+$/, "");
+  return trimmed ? `${trimmed}\n\n${block}` : block;
+}
+
+/**
+ * Restrict AI CLI to this project folder and write partner ignore paths.
+ * @param {string} folder
+ * @param {string[]} partnerIgnorePaths
+ */
+function applyAccessPolicy(folder, partnerIgnorePaths) {
+  const resolved = path.resolve(folder);
+  fs.mkdirSync(resolved, { recursive: true });
+  const ignorePaths = resolveIgnorePaths(partnerIgnorePaths);
+  const envPath = path.join(resolved, ".env");
+  mergeEnvFile(envPath, {
+    AI_CLI_WORKSPACE: ".",
+    AI_CLI_IGNORE_PATHS: JSON.stringify(
+      normalizeIgnorePaths(partnerIgnorePaths || [])
+    ),
+  });
+
+  const mpDir = path.join(resolved, ".maintainer-pro");
+  fs.mkdirSync(mpDir, { recursive: true });
+  fs.writeFileSync(
+    path.join(mpDir, "access.json"),
+    JSON.stringify(
+      {
+        workspace: ".",
+        ignorePaths,
+        partnerIgnorePaths: normalizeIgnorePaths(partnerIgnorePaths || []),
+        updatedAt: new Date().toISOString(),
+      },
+      null,
+      2
+    ) + "\n",
+    "utf8"
+  );
+
+  for (const name of [".cursorignore"]) {
+    const file = path.join(resolved, name);
+    const existing = fs.existsSync(file)
+      ? fs.readFileSync(file, "utf8")
+      : "";
+    fs.writeFileSync(file, upsertManagedIgnoreFile(existing, ignorePaths), "utf8");
   }
-  const body = Object.entries(map)
-    .map(([k, v]) => `${k}=${v}`)
-    .join("\n");
-  fs.writeFileSync(file, body + "\n", "utf8");
+
+  return { ignorePaths };
 }
 
 const IGNORE_NAMES = new Set([
@@ -846,6 +2275,8 @@ function collectOfferedFolders(cfg) {
 
 /** Prevents opening a new window on every heartbeat while a process is starting. */
 const launchedAt = new Map();
+/** @type {Map<string, { tunnels: Array<{ role: string, localUrl: string, publicUrl: string | null, logFile: string }> }>} */
+const cloudflareTunnels = new Map();
 
 /** Last process problems to send on heartbeat. Key: sandboxId::code::role */
 const processProblems = new Map();
@@ -1081,12 +2512,67 @@ function planHostJobs(dir, appUrl, hints = null) {
 
 function friendlyLaunchError(raw, title) {
   const text = String(raw || "").trim();
-  if (/ENOENT/i.test(text)) {
+  if (/^spawn\b.*\bENOENT\b/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 writeWinLaunchScript(folder, title, command, env) {
+  const dir = path.join(folder, ".maintainer-pro");
+  fs.mkdirSync(dir, { recursive: true });
+  const safe = String(title || "app").replace(/[^a-zA-Z0-9._-]+/g, "-");
+  const file = path.join(dir, `launch-${safe}.cmd`);
+  const folderArg = String(folder).replace(/"/g, "");
+  const safeTitle = String(title || "Maintainer Pro").replace(/["&<>|^]/g, " ");
+  const lines = [
+    "@echo off",
+    `title ${safeTitle}`,
+    `cd /d "${folderArg}"`,
+    "if errorlevel 1 (",
+    "  echo Could not open the project folder.",
+    "  pause",
+    "  exit /b 1",
+    ")",
+    ...Object.entries(env).map(
+      ([key, value]) => `set "${key}=${String(value).replace(/"/g, "")}"`
+    ),
+    "echo %CD%",
+    `echo ${command}`,
+    command,
+    "if errorlevel 1 pause",
+  ];
+  fs.writeFileSync(file, `${lines.join("\r\n")}\r\n`, "utf8");
+  return file;
+}
+
+function openWindowsConsole(scriptPath, folder) {
+  return new Promise((resolve) => {
+    let child;
+    try {
+      child = spawn(process.env.ComSpec || "cmd.exe", ["/k", scriptPath], {
+        cwd: folder,
+        detached: true,
+        stdio: "ignore",
+        windowsHide: false,
+      });
+    } catch (err) {
+      resolve({
+        ok: false,
+        error: err instanceof Error ? err.message : String(err),
+      });
+      return;
+    }
+    child.once("error", (err) => {
+      resolve({ ok: false, error: err.message });
+    });
+    child.once("spawn", () => {
+      child.unref();
+      resolve({ ok: true });
+    });
+  });
+}
+
 function runLauncher(command, args, extra = {}) {
   return new Promise((resolve) => {
     let settled = false;
@@ -1136,6 +2622,7 @@ async function openInNewTerminal(opts) {
   const { title, folder, command, env = {}, launchKey, sandboxId } = opts;
   if (launchKey) {
     if (!opts.force && recentlyLaunched(launchKey)) {
+      log(`terminal skip [${title}]: launched recently`);
       return { ok: true, skipped: true };
     }
     launchedAt.set(launchKey, Date.now());
@@ -1153,9 +2640,6 @@ async function openInNewTerminal(opts) {
     title
   );
 
-  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(" && ");
@@ -1167,17 +2651,14 @@ async function openInNewTerminal(opts) {
       const safeTitle =
         String(title || "Maintainer Pro").replace(/["&<>|^]/g, " ").trim() ||
         "Maintainer Pro";
-      const body = [envWin, `title ${safeTitle}`, command]
-        .filter(Boolean)
-        .join("&& ");
-      const opened = await runLauncher(
-        process.env.ComSpec || "cmd.exe",
-        ["/d", "/s", "/c", `start "${safeTitle}" /D "${folder}" cmd.exe /k ${body}`],
-        { windowsVerbatimArguments: true }
-      );
+      const script = writeWinLaunchScript(folder, safeTitle, command, env);
+      log(`terminal script [${title}] ${script}`);
+      const opened = await openWindowsConsole(script, folder);
       if (!opened.ok) {
+        warn(`terminal failed [${title}]: ${opened.error || "unknown"}`);
         return { ok: false, error: friendlyLaunchError(opened.error, title) };
       }
+      log(`terminal opened [${title}]`);
       return { ok: true };
     }
 
@@ -1250,23 +2731,22 @@ async function startAiServerForWorkspace(ws, opts = {}) {
   if (await probeUrl(`http://127.0.0.1:${preferred}/embed-config.js`)) {
     reserved.add(preferred);
     clearProcessProblem(ws.sandboxId, "ai_server_launch", "ai");
+    log(`start chat skip ${label}: already up on ${preferred}`);
     return { port: preferred, up: true, launched: false };
   }
 
   if (recentlyLaunched(launchKey)) {
     reserved.add(preferred);
+    log(`start chat skip ${label}: already launching on ${preferred}`);
     return { port: preferred, up: false, launched: false, starting: true };
   }
 
-  let port = preferred;
+  let port = Number(opts.port) || preferred;
   try {
-    if (reserved.has(preferred)) {
-      if (!(await isPortFree(preferred))) {
-        reserved.delete(preferred);
-        port = await findFreePort(preferred, reserved);
-      }
-    } else {
+    if (!opts.port) {
       port = await findFreePort(preferred, reserved);
+    } else {
+      reserved.add(port);
     }
   } catch (err) {
     recordProcessProblem({
@@ -1277,23 +2757,32 @@ async function startAiServerForWorkspace(ws, opts = {}) {
       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.",
+      resolution: "Close other local servers, then use Start Apps.",
     });
     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);
+    log(`port ${preferred} busy; using ${port} for chat script`);
   }
+  ws.port = port;
+  const localAi = `http://localhost:${port}`;
+  const overrideEnv =
+    opts.env && typeof opts.env === "object" ? opts.env : {};
+  const publicAi =
+    (typeof overrideEnv.AI_SERVER_URL === "string" &&
+      overrideEnv.AI_SERVER_URL.trim()) ||
+    (typeof overrideEnv.NEXT_PUBLIC_AI_SERVER_URL === "string" &&
+      overrideEnv.NEXT_PUBLIC_AI_SERVER_URL.trim()) ||
+    (typeof ws.cloudflare?.ai === "string" && ws.cloudflare.ai.trim()) ||
+    "";
+  const aiUrl = publicAi || localAi;
+  writeProjectEnv(folder, {
+    AI_SERVER_URL: aiUrl,
+    NEXT_PUBLIC_AI_SERVER_URL: aiUrl,
+    VITE_AI_SERVER_URL: aiUrl,
+    ...overrideEnv,
+  });
+  persistWorkspaceEntry(cfg, ws);
 
   const localCli = path.resolve(
     __dirname,
@@ -1315,9 +2804,11 @@ async function startAiServerForWorkspace(ws, opts = {}) {
     folder,
     command: run,
     env: {
-      PORT: String(port),
-      AI_SERVER_URL: `http://localhost:${port}`,
-      NEXT_PUBLIC_AI_SERVER_URL: `http://localhost:${port}`,
+      AI_SERVER_PORT: String(port),
+      AI_SERVER_URL: aiUrl,
+      NEXT_PUBLIC_AI_SERVER_URL: aiUrl,
+      VITE_AI_SERVER_URL: aiUrl,
+      ...overrideEnv,
     },
     launchKey,
     sandboxId: ws.sandboxId,
@@ -1344,18 +2835,12 @@ 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
-  );
-  return match ? match[0].replace(/\/$/, "") : null;
+  return lastTryCloudflareUrl(text);
 }
 
 function killProcessesByCommand(fragment) {
@@ -1456,22 +2941,38 @@ async function stopWorkspaceApps(ws) {
   await sleep(400);
 }
 
-async function waitUntilReachable(url, timeoutMs, label) {
+async function waitUntilReachable(url, timeoutMs, label, onWait) {
   const start = Date.now();
+  let last = 0;
   while (Date.now() - start < timeoutMs) {
     if (await probeUrl(url)) return true;
+    const elapsed = Date.now() - start;
+    if (onWait && elapsed - last >= 8_000) {
+      last = elapsed;
+      await onWait(
+        `Still waiting for ${label} (${Math.round(elapsed / 1000)}s)…`
+      );
+    }
     await sleep(600);
   }
   throw new Error(`${label} did not become reachable at ${url}`);
 }
 
-async function waitForUrlInFile(file, timeoutMs = 90_000) {
+async function waitForUrlInFile(file, timeoutMs = 90_000, onWait) {
   const start = Date.now();
+  let last = 0;
   while (Date.now() - start < timeoutMs) {
     if (fs.existsSync(file)) {
       const url = parseTryCloudflareUrl(fs.readFileSync(file, "utf8"));
       if (url) return url;
     }
+    const elapsed = Date.now() - start;
+    if (onWait && elapsed - last >= 8_000) {
+      last = elapsed;
+      await onWait(
+        `Still waiting for a Cloudflare URL (${Math.round(elapsed / 1000)}s)…`
+      );
+    }
     await sleep(500);
   }
   throw new Error(
@@ -1486,7 +2987,7 @@ function cloudflaredCommand(localUrl, logFile) {
   return `${run} 2>&1 | tee ${logArg}`;
 }
 
-async function startCloudflareTerminal(ws, role, localUrl) {
+async function startCloudflareTerminal(ws, role, localUrl, onWait) {
   const folder = path.resolve(ws.folderPath);
   const logDir = path.join(folder, ".maintainer-pro");
   fs.mkdirSync(logDir, { recursive: true });
@@ -1510,7 +3011,7 @@ async function startCloudflareTerminal(ws, role, localUrl) {
   if (!opened.ok) {
     throw new Error(opened.error || `Could not open a Cloudflare terminal for ${role}`);
   }
-  const publicUrl = await waitForUrlInFile(logFile);
+  const publicUrl = await waitForUrlInFile(logFile, 90_000, onWait);
   return { role, localUrl, publicUrl, logFile };
 }
 
@@ -1518,53 +3019,180 @@ 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;
+    const ai = String(tunnels.ai).replace(/\/$/, "");
+    env.AI_SERVER_URL = ai;
+    env.NEXT_PUBLIC_AI_SERVER_URL = ai;
+    env.VITE_AI_SERVER_URL = ai;
+    env.REACT_APP_AI_SERVER_URL = 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;
+    const backend = String(tunnels.backend).replace(/\/$/, "");
+    env.API_URL = backend;
+    env.API_BASE_URL = backend;
+    env.VITE_API_URL = backend;
+    env.VITE_API_BASE_URL = backend;
+    env.NEXT_PUBLIC_API_URL = backend;
+    env.NEXT_PUBLIC_API_BASE_URL = backend;
+    env.BACKEND_URL = backend;
   }
   if (tunnels.ui) {
-    env.APP_URL = tunnels.ui;
-    env.PUBLIC_URL = tunnels.ui;
-    env.CORS_ORIGIN = tunnels.ui;
+    const ui = String(tunnels.ui).replace(/\/$/, "");
+    env.APP_URL = ui;
+    env.PUBLIC_URL = ui;
+    env.CORS_ORIGIN = ui;
+    env.NEXT_PUBLIC_APP_URL = ui;
+    env.VITE_APP_URL = ui;
+    env.REACT_APP_APP_URL = ui;
   } else if (tunnels.ai) {
-    env.CORS_ORIGIN = tunnels.ai;
+    const ai = String(tunnels.ai).replace(/\/$/, "");
+    env.CORS_ORIGIN = ai;
+    env.APP_URL = ai;
+    env.PUBLIC_URL = ai;
+    env.NEXT_PUBLIC_APP_URL = ai;
+    env.VITE_APP_URL = ai;
   }
   return env;
 }
 
 function writeTunnelEnv(ws, tunnels) {
   const folder = ws.folderPath ? path.resolve(ws.folderPath) : null;
-  if (!folder || !fs.existsSync(folder)) return;
+  if (!folder || !fs.existsSync(folder)) return { ok: false, env: {} };
   const env = uiPublicEnv(tunnels);
   const lines = Object.entries(tunnels)
     .filter(([, url]) => url)
-    .map(([role, url]) => `${role}=${url}`);
+    .map(([role, url]) => `${role}=${String(url).replace(/\/$/, "")}`);
   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 (Object.keys(env).length) writeProjectEnv(folder, env);
+  return { ok: true, env };
+}
+
+/**
+ * Validate tunnels + frontend env before sharing URLs with Maintainer Pro.
+ * @returns {Promise<{ ok: boolean, checks: Array<{ id: string, ok: boolean, detail: string }> }>}
+ */
+async function validateCloudflareGoLive(ws, tunnels, opts = {}) {
+  const folder = path.resolve(ws.folderPath || "");
+  const progress =
+    typeof opts.onProgress === "function" ? opts.onProgress : async () => {};
+  /** @type {Array<{ id: string, ok: boolean, detail: string }>} */
+  const checks = [];
+  const add = (id, ok, detail) => {
+    checks.push({ id, ok, detail });
+    log(`go-live ${ok ? "ok" : "FAIL"} ${id}: ${detail}`);
+  };
+
+  await progress(
+    "Validating Cloudflare setup before sharing with Maintainer Pro…"
+  );
+
+  writeTunnelEnv(ws, tunnels);
+  const env = readProjectEnvValues(folder);
+
+  if (!tunnels.ai) {
+    add("ai_tunnel", false, "Missing chat-script Cloudflare URL");
+  } else {
+    const ai = String(tunnels.ai).replace(/\/$/, "");
+    const embed = `${ai}/embed-config.js`;
+    const reachable = await probeUrl(embed, 10_000);
+    add(
+      "ai_tunnel",
+      reachable,
+      reachable ? `Reachable ${embed}` : `Unreachable ${embed}`
+    );
+    if (reachable) {
+      const body = await fetchText(embed, 10_000);
+      const advertises =
+        Boolean(body) &&
+        (body.includes(ai) ||
+          body.includes(ai.replace(/^https:\/\//, "")));
+      add(
+        "embed_config",
+        advertises,
+        advertises
+          ? "embed-config.js advertises the public AI URL"
+          : `embed-config.js does not advertise ${ai}`
+      );
+    }
+  }
+
+  if (tunnels.ui) {
+    const ui = String(tunnels.ui).replace(/\/$/, "");
+    const reachable = await probeUrl(ui, 10_000);
+    add(
+      "ui_tunnel",
+      reachable,
+      reachable ? `Reachable ${ui}` : `Unreachable ${ui}`
+    );
+  } else {
+    add(
+      "ui_tunnel",
+      true,
+      "No separate UI tunnel (AI-only / same-origin share)"
+    );
+  }
+
+  const ai = String(tunnels.ai || "").replace(/\/$/, "");
+  if (ai) {
+    const envAi = [
+      env.NEXT_PUBLIC_AI_SERVER_URL,
+      env.VITE_AI_SERVER_URL,
+      env.AI_SERVER_URL,
+      env.REACT_APP_AI_SERVER_URL,
+    ]
+      .map((value) => String(value || "").replace(/\/$/, ""))
+      .filter(Boolean);
+    const envOk = envAi.some((value) => value === ai);
+    add(
+      "frontend_env",
+      envOk,
+      envOk
+        ? `Frontend env has AI URL ${ai}`
+        : `Frontend env missing AI URL (NEXT_PUBLIC=${
+            env.NEXT_PUBLIC_AI_SERVER_URL || "(empty)"
+          }, VITE=${env.VITE_AI_SERVER_URL || "(empty)"}, AI_SERVER_URL=${
+            env.AI_SERVER_URL || "(empty)"
+          })`
+    );
   }
-  if (env.NEXT_PUBLIC_API_URL) {
-    localEnv.NEXT_PUBLIC_API_URL = env.NEXT_PUBLIC_API_URL;
+
+  if (tunnels.ui) {
+    const ui = String(tunnels.ui).replace(/\/$/, "");
+    const envApp = [
+      env.APP_URL,
+      env.NEXT_PUBLIC_APP_URL,
+      env.PUBLIC_URL,
+      env.VITE_APP_URL,
+      env.CORS_ORIGIN,
+    ]
+      .map((value) => String(value || "").replace(/\/$/, ""))
+      .filter(Boolean);
+    const appOk = envApp.some((value) => value === ui);
+    add(
+      "app_url_env",
+      appOk,
+      appOk
+        ? `App URL env has ${ui}`
+        : `App URL env missing ${ui} (APP_URL=${env.APP_URL || "(empty)"}, NEXT_PUBLIC_APP_URL=${
+            env.NEXT_PUBLIC_APP_URL || "(empty)"
+          })`
+    );
   }
-  if (Object.keys(localEnv).length) {
-    mergeEnvFile(path.join(folder, ".env.local"), localEnv);
+
+  const ok = checks.every((check) => check.ok);
+  if (ok) {
+    await progress("Validation passed — sharing public URLs with Maintainer Pro.");
+  } else {
+    const failed = checks
+      .filter((check) => !check.ok)
+      .map((check) => `${check.id}: ${check.detail}`)
+      .join(" | ");
+    await progress(`Validation failed — not sharing yet. ${failed}`);
   }
+  return { ok, checks };
 }
 
 function reservedPortsFor(cfg, sandboxId) {
@@ -1581,17 +3209,39 @@ function appsWanted(ws) {
   return Boolean(ws?.appsRequested);
 }
 
-async function configureCloudflareForWorkspace(ws, cfg) {
+async function configureCloudflareForWorkspace(ws, cfg, opts = {}) {
   const sandboxId = ws.sandboxId;
   const label = ws.sandboxName || "this sandbox";
+  const progress = (message) =>
+    reportActionProgress(cfg, opts.actionId, message);
+
+  // If tunnels are already up, attach instead of tearing them down.
+  const attached = await tryAttachExistingCloudflare(ws, cfg, {
+    onProgress: progress,
+  });
+  if (attached) {
+    return {
+      ...attached,
+      pending: false,
+      cloudflarePending: false,
+      waitingForStart: false,
+      warning: null,
+    };
+  }
 
-  log(`Cloudflare queued for ${label}: stop apps and wait for Start`);
+  await progress(
+    `Preparing Cloudflare for ${label}. Stopping local apps first — this can take a minute.`
+  );
   await stopCloudflare(sandboxId);
+  await progress("Stopping local app terminals and freeing their ports…");
   await stopWorkspaceApps(ws);
   await forgetLaunch(sandboxId);
   ws.cloudflarePending = true;
   ws.appsRequested = false;
   persistWorkspaceEntry(cfg, ws);
+  await progress(
+    "Cloudflare is queued. Use Start Apps to create the public URLs."
+  );
 
   return {
     sandboxId,
@@ -1601,43 +3251,61 @@ async function configureCloudflareForWorkspace(ws, cfg) {
     cloudflarePending: true,
     waitingForStart: true,
     warning:
-      "Cloudflare is ready in Maintainer Pro. Use Start chat server when you want to launch the apps and create the public URLs.",
+      "Cloudflare is ready in Maintainer Pro. Use Start Apps when you want to launch the apps and create the public URLs.",
   };
 }
 
-async function launchCloudflareTunnels(ws, cfg) {
+async function launchCloudflareTunnels(ws, cfg, opts = {}) {
   const sandboxId = ws.sandboxId;
   const label = ws.sandboxName || "this sandbox";
   const folder = path.resolve(ws.folderPath || "");
   const reserved = reservedPortsFor(cfg, sandboxId);
+  const progress = (message) =>
+    reportActionProgress(cfg, opts.actionId, message);
 
-  log(`Cloudflare start for ${label}: tunnel chat script/backend before UI`);
+  const attached = await tryAttachExistingCloudflare(ws, cfg, {
+    onProgress: progress,
+  });
+  if (attached) return attached;
+
+  await progress(
+    `Creating Cloudflare tunnels for ${label}. This usually takes 1–2 minutes.`
+  );
   try {
+  const plan = await prepareWorkspaceLaunch(ws, cfg, reserved);
   if (!cfg.noAiServer) {
-    await startAiServerForWorkspace(ws, { reserved, cfg });
+    await progress(`Starting the chat script on port ${plan.aiPort}…`);
+    await startAiServerForWorkspace(ws, {
+      reserved,
+      cfg,
+      port: plan.aiPort,
+    });
     await waitUntilReachable(
       `http://127.0.0.1:${ws.port}/embed-config.js`,
       45_000,
-      "Chat script"
+      "the chat script",
+      progress
     );
   }
 
-  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");
+  const backendJob = plan.jobs.find((job) => job.role === "backend");
+  const uiJob = plan.jobs.find((job) => job.role === "ui" || job.role === "app");
 
   if (backendJob) {
+    await progress(`Starting the backend on port ${backendJob.port}…`);
     await ensureHostProcesses(ws, {
       reserved,
       cfg,
       onlyRoles: ["backend"],
       force: true,
+      plannedJobs: plan.jobs,
     });
-    const backendPort = Number(backendJob.preferredPort) || 4100;
+    const backendPort = Number(backendJob.port) || 4100;
     await waitUntilReachable(
       `http://127.0.0.1:${backendPort}`,
       45_000,
-      "Backend"
+      "the backend",
+      progress
     );
   }
 
@@ -1647,45 +3315,125 @@ async function launchCloudflareTunnels(ws, cfg) {
   const started = [];
 
   const aiLocal = `http://127.0.0.1:${Number(ws.port) || 3100}`;
-  const aiTunnel = await startCloudflareTerminal(ws, "ai", aiLocal);
+  await progress(`Opening a Cloudflare tunnel for the chat script (${aiLocal})…`);
+  const aiTunnel = await startCloudflareTerminal(ws, "ai", aiLocal, progress);
   tunnels.ai = aiTunnel.publicUrl;
   started.push(aiTunnel);
-  log(`Cloudflare chat script: ${aiTunnel.publicUrl}`);
+  await progress(`Chat script public URL: ${aiTunnel.publicUrl}`);
 
   if (backendJob) {
-    const backendLocal = `http://127.0.0.1:${Number(backendJob.preferredPort) || 4100}`;
-    const backendTunnel = await startCloudflareTerminal(ws, "backend", backendLocal);
+    const backendLocal = `http://127.0.0.1:${Number(backendJob.port) || 4100}`;
+    await progress(`Opening a Cloudflare tunnel for the backend (${backendLocal})…`);
+    const backendTunnel = await startCloudflareTerminal(
+      ws,
+      "backend",
+      backendLocal,
+      progress
+    );
     tunnels.backend = backendTunnel.publicUrl;
     started.push(backendTunnel);
-    log(`Cloudflare backend: ${backendTunnel.publicUrl}`);
+    await progress(`Backend public URL: ${backendTunnel.publicUrl}`);
   }
 
   writeTunnelEnv(ws, tunnels);
-  const uiEnv = uiPublicEnv(tunnels);
+  let uiEnv = uiPublicEnv(tunnels);
+  const uiPort = uiJob ? Number(uiJob.port) || 5173 : null;
 
   if (uiJob) {
+    await progress(`Starting the app UI on port ${uiPort}…`);
     await ensureHostProcesses(ws, {
       reserved,
       cfg,
       onlyRoles: ["ui", "app"],
       extraEnv: uiEnv,
       force: true,
+      plannedJobs: plan.jobs,
     });
-    const uiPort = Number(uiJob.preferredPort) || 5173;
-    await waitUntilReachable(`http://127.0.0.1:${uiPort}`, 60_000, "App UI");
+    await waitUntilReachable(
+      `http://127.0.0.1:${uiPort}`,
+      60_000,
+      "the app UI",
+      progress
+    );
+    await progress(
+      `Opening a Cloudflare tunnel for the app UI (http://127.0.0.1:${uiPort})…`
+    );
     const uiTunnel = await startCloudflareTerminal(
       ws,
       "ui",
-      `http://127.0.0.1:${uiPort}`
+      `http://127.0.0.1:${uiPort}`,
+      progress
     );
     tunnels.ui = uiTunnel.publicUrl;
     started.push(uiTunnel);
-    log(`Cloudflare UI: ${uiTunnel.publicUrl}`);
+    await progress(`App UI public URL: ${uiTunnel.publicUrl}`);
     writeTunnelEnv(ws, tunnels);
+    uiEnv = uiPublicEnv(tunnels);
+
+    // Restart UI so Vite/Next pick up APP_URL + public AI URL from env files.
+    await progress(
+      "Restarting the app UI so it loads the public base URL from env…"
+    );
+    for (const job of plan.jobs) {
+      if (job.role === "ui" || job.role === "app") {
+        launchedAt.delete(`${sandboxId}:${folder}:${job.script}`);
+      }
+    }
+    await killPort(uiPort);
+    await sleep(1500);
+    await ensureHostProcesses(ws, {
+      reserved,
+      cfg,
+      onlyRoles: ["ui", "app"],
+      extraEnv: uiEnv,
+      force: true,
+      plannedJobs: plan.jobs,
+    });
+    await waitUntilReachable(
+      `http://127.0.0.1:${uiPort}`,
+      60_000,
+      "the app UI",
+      progress
+    );
+  }
+
+  // Restart chat script with the public AI URL (and CORS/app origins).
+  if (tunnels.ai) {
+    await progress("Restarting the chat script with the public AI URL…");
     launchedAt.delete(`${sandboxId}:${folder}:ai`);
     await killPort(ws.port);
     await sleep(1500);
-    await startAiServerForWorkspace(ws, { reserved, cfg });
+    await startAiServerForWorkspace(ws, {
+      reserved,
+      cfg,
+      port: ws.port,
+      env: uiPublicEnv(tunnels),
+    });
+    writeTunnelEnv(ws, tunnels);
+    await waitUntilReachable(
+      `http://127.0.0.1:${ws.port}/embed-config.js`,
+      45_000,
+      "the chat script",
+      progress
+    );
+  }
+
+  const validation = await validateCloudflareGoLive(ws, tunnels, {
+    onProgress: progress,
+  });
+  if (!validation.ok) {
+    const failed = validation.checks
+      .filter((check) => !check.ok)
+      .map((check) => `${check.id}: ${check.detail}`)
+      .join("\n");
+    ws.cloudflarePending = true;
+    ws.cloudflare = tunnels;
+    ws.cloudflareUrl = null;
+    persistWorkspaceEntry(cfg, ws);
+    rememberCloudflareTunnels(sandboxId, tunnels);
+    throw new Error(
+      `Cloudflare validation failed — public URLs were not shared with Maintainer Pro yet.\n${failed}`
+    );
   }
 
   const appUrl = tunnels.ui || tunnels.ai;
@@ -1695,16 +3443,22 @@ async function launchCloudflareTunnels(ws, cfg) {
   ws.cloudflarePending = false;
   ws.appsRequested = true;
   persistWorkspaceEntry(cfg, ws);
+  rememberCloudflareTunnels(sandboxId, tunnels);
   cloudflareTunnels.set(sandboxId, { tunnels: started });
   clearProcessProblem(sandboxId, "cloudflare_launch", "tunnel");
+  const host = workspaceHostReport(ws);
+  await progress(`Cloudflare is ready: ${host.appUrl || appUrl}`);
 
   return {
     sandboxId,
     folderPath: ws.folderPath,
     port: ws.port,
-    appUrl,
-    origins: Object.values(tunnels).filter(Boolean),
+    appUrl: host.appUrl || appUrl,
+    origins: host.origins.length
+      ? host.origins
+      : Object.values(tunnels).filter(Boolean),
     tunnels,
+    validation,
     cloudflare: true,
     reused: false,
   };
@@ -1717,47 +3471,120 @@ async function launchCloudflareTunnels(ws, cfg) {
       title: `Could not start Cloudflare (${label})`,
       message,
       resolution:
-        "Install cloudflared or allow npx to download it, then use Start chat server again.",
+        "Install cloudflared or allow npx to download it, then use Start Apps again.",
       actionCode: "start_ai_server",
     });
     throw err;
   }
 }
 
-async function startAppsForWorkspace(ws, cfg) {
+async function startAppsForWorkspace(ws, cfg, opts = {}) {
+  const label = ws.sandboxName || shortId(ws.sandboxId) || "sandbox";
+  await reportActionProgress(
+    cfg,
+    opts.actionId,
+    `Checking running apps and Cloudflare for ${label}…`
+  );
+
+  // Status + env sync first (never starts Cloudflare here).
+  let status = await reconcileWorkspacePresence(ws, cfg, {
+    writeEnv: true,
+    timeoutMs: 2500,
+  });
+  log(
+    `start apps ${label}: chat=${status.probe.chatUp ? "up" : "down"}@${
+      status.probe.chatPort
+    } hosts=${
+      status.probe.hosts
+        .map((h) => `${h.role}:${h.up ? "up" : "down"}`)
+        .join(",") || "none"
+    } cloudflare=${status.usingCloudflare ? "yes" : "no"}`
+  );
+
+  // Cloudflare tunnels only when Maintainer Pro left a pending Share signal.
   if (ws.cloudflarePending) {
-    return launchCloudflareTunnels(ws, cfg);
+    log(`start apps ${label}: Cloudflare pending, launching tunnels`);
+    return launchCloudflareTunnels(ws, cfg, opts);
   }
+
+  await reportActionProgress(
+    cfg,
+    opts.actionId,
+    `Starting local apps for ${label}…`
+  );
   ws.appsRequested = true;
-  persistWorkspaceEntry(cfg, ws);
   const reserved = reservedPortsFor(cfg, ws.sandboxId);
+  const plan = await prepareWorkspaceLaunch(ws, cfg, reserved);
+
+  // Re-sync env after port assignment (local or cloudflare urls).
+  status = await reconcileWorkspacePresence(ws, cfg, {
+    writeEnv: true,
+    timeoutMs: 800,
+  });
+
+  const cfEnv =
+    status.usingCloudflare && status.cloudflare
+      ? uiPublicEnv(status.cloudflare)
+      : {};
+
   if (!cfg.noAiServer) {
-    await startAiServerForWorkspace(ws, { reserved, cfg });
-    await sleep(1500);
+    if (status.probe.chatUp) {
+      log(`chat already running on ${status.probe.chatPort} — not restarting`);
+      clearProcessProblem(ws.sandboxId, "ai_server_launch", "ai");
+      clearProcessProblem(ws.sandboxId, "apps_not_started");
+      ws.port = status.probe.chatPort;
+    } else {
+      await startAiServerForWorkspace(ws, {
+        reserved,
+        cfg,
+        port: plan.aiPort,
+        env: cfEnv,
+      });
+      await sleep(1500);
+    }
   }
+
+  // ensureHostProcesses skips roles that are already answering HTTP.
   const startedHosts = await ensureHostProcesses(ws, {
     reserved,
     cfg,
     force: true,
+    plannedJobs: plan.jobs.map((job) => {
+      const probed = status.probe.hosts.find((h) => h.role === job.role);
+      return probed?.up ? { ...job, up: true, port: probed.port } : job;
+    }),
+    extraEnv: cfEnv,
   });
   await sleep(800);
+
+  status = await reconcileWorkspacePresence(ws, cfg, {
+    writeEnv: true,
+    timeoutMs: 2500,
+  });
   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");
-    clearProcessProblem(ws.sandboxId, "apps_not_started");
-  }
+
   const processIssues = issuesForSandbox(ws.sandboxId).map(
     ({ role: _role, ...issue }) => issue
   );
   const warning = processIssues[0]?.message || null;
+  log(
+    `start apps done ${label}: chat=${ws.port} chatUp=${
+      status.aiServerUp
+    } hosts=${startedHosts.join(",") || "none"} cloudflare=${
+      status.usingCloudflare ? "yes" : "no"
+    }${status.host.appUrl ? ` app=${status.host.appUrl}` : ""} origins=${
+      status.host.origins.join(",") || "none"
+    }${warning ? ` warning=${warning}` : ""}`
+  );
   return {
-    up,
+    up: status.aiServerUp,
     startedHosts,
     sandboxId: ws.sandboxId,
     folderPath: ws.folderPath,
     port: ws.port,
-    appUrl: ws.appUrl,
+    appUrl: status.host.appUrl || ws.appUrl,
+    origins: status.host.origins,
+    cloudflare: status.usingCloudflare,
     processIssues,
     warning,
   };
@@ -1768,11 +3595,13 @@ async function ensureHostProcesses(ws, opts = {}) {
   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 jobs = Array.isArray(opts.plannedJobs)
+    ? opts.plannedJobs
+    : 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 = [];
@@ -1791,14 +3620,26 @@ async function ensureHostProcesses(ws, opts = {}) {
     return started;
   }
 
+  log(
+    `start hosts ${label}: ${
+      jobs.length
+        ? jobs
+            .filter((job) => !onlyRoles || onlyRoles.has(job.role))
+            .map((job) => `${job.role}:${job.script}:${job.port || job.preferredPort}`)
+            .join(" ")
+        : "none"
+    }`
+  );
+
   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)) {
+    const preferred = Number(job.port || job.preferredPort) || 3000;
+    const probe = (
+      job.port
+        ? `http://127.0.0.1:${job.port}`
+        : job.probeUrl || `http://127.0.0.1:${preferred}`
+    ).replace("localhost", "127.0.0.1");
+    if (job.up || (await probeUrl(probe))) {
       reserved.add(portFromText(probe, preferred));
       clearProcessProblem(ws.sandboxId, "host_process_launch", job.role);
       clearProcessProblem(ws.sandboxId, "host_process_down", job.role);
@@ -1808,12 +3649,17 @@ async function ensureHostProcesses(ws, opts = {}) {
     const launchKey = `${ws.sandboxId}:${folder}:${job.script}`;
     if (!opts.force && recentlyLaunched(launchKey)) {
       reserved.add(preferred);
+      log(`start ${job.role} skip ${label}: launched recently`);
       continue;
     }
 
-    let port = preferred;
+    let port = Number(job.port) || preferred;
     try {
-      port = await findFreePort(preferred, reserved);
+      if (!job.port) {
+        port = await findFreePort(preferred, reserved);
+      } else {
+        reserved.add(port);
+      }
     } catch (err) {
       recordProcessProblem({
         sandboxId: ws.sandboxId,
@@ -1823,7 +3669,7 @@ async function ensureHostProcesses(ws, opts = {}) {
         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.",
+        resolution: "Close other local servers, then use Start Apps.",
       });
       continue;
     }
@@ -1845,7 +3691,10 @@ async function ensureHostProcesses(ws, opts = {}) {
       sandboxId: ws.sandboxId,
       force: Boolean(opts.force),
     });
-    if (opened.skipped) continue;
+    if (opened.skipped) {
+      log(`start ${job.role} skip ${label}: terminal already opening`);
+      continue;
+    }
     if (!opened.ok) {
       recordProcessProblem({
         sandboxId: ws.sandboxId,
@@ -1859,6 +3708,7 @@ async function ensureHostProcesses(ws, opts = {}) {
       continue;
     }
     started.push(job.role);
+    log(`start ${job.role} launched ${label} on ${port}: ${command}`);
     if (
       (job.role === "ui" || job.role === "app") &&
       (!ws.appUrl || isLocalAppUrl(ws.appUrl))
@@ -1918,7 +3768,7 @@ async function inspectHostJobs(ws) {
         ? `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.",
+        "Fix the error in that terminal, then use Start Apps to try again.",
     });
   }
   return hosts;
@@ -1929,6 +3779,7 @@ async function setupWorkspace(cfg, action) {
   const sandboxId = String(
     action.sandboxId || action.payload?.sandboxId || ""
   );
+  log(`setup begin sandbox=${shortId(sandboxId)} folder=${folderPath || "(none)"}`);
   const requestedPort = Number(action.payload?.port) || 3100;
   const reserved = new Set();
   for (const other of cfg.workspaces || []) {
@@ -1939,10 +3790,13 @@ async function setupWorkspace(cfg, action) {
   let port = requestedPort;
   if (await probeUrl(`http://127.0.0.1:${requestedPort}/embed-config.js`)) {
     reserved.add(requestedPort);
+    log(`setup chat port ${requestedPort} already up`);
   } else {
     port = await findFreePort(requestedPort, reserved);
     if (port !== requestedPort) {
-      log(`port ${requestedPort} busy; using ${port} for ai-server`);
+      log(`setup chat port ${requestedPort} busy; using ${port}`);
+    } else {
+      log(`setup chat port ${port} free`);
     }
   }
   const clientMode = String(action.payload?.clientMode || "auto"); // auto|empty|existing|skip
@@ -1983,18 +3837,29 @@ async function setupWorkspace(cfg, action) {
   const appUrl = client.appUrl || corsOrigin;
 
   const envPath = path.join(resolved, ".env");
+  const partnerIgnorePaths = Array.isArray(config.aiIgnorePaths)
+    ? config.aiIgnorePaths
+    : [];
   const envValues = {
     ...config.env,
     AI_CLI_WORKSPACE: ".",
+    AI_CLI_IGNORE_PATHS: JSON.stringify(
+      normalizeIgnorePaths(partnerIgnorePaths)
+    ),
     AI_SERVER_UI: client.sameOrigin || client.kind === "empty" ? "." : ".",
-    PORT: String(port),
+    AI_SERVER_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);
+  mergeEnvFile(envPath, envValues, { remove: ["PORT"] });
+  const envLocal = path.join(resolved, ".env.local");
+  if (fs.existsSync(envLocal)) {
+    mergeEnvFile(envLocal, {}, { remove: ["PORT"] });
+  }
+  const access = applyAccessPolicy(resolved, partnerIgnorePaths);
 
   cfg.workspaces = cfg.workspaces || [];
   const existing = cfg.workspaces.findIndex((w) => w.sandboxId === sandboxId);
@@ -2028,6 +3893,12 @@ async function setupWorkspace(cfg, action) {
   });
 
   await inspectHostJobs(entry);
+  const planned = planHostJobs(
+    resolved,
+    entry.appUrl && isLocalAppUrl(entry.appUrl) ? entry.appUrl : null,
+    entry.projectInfo
+  ).map((job) => ({ ...job, port: job.preferredPort }));
+  writeProjectEnv(resolved, envForWorkspacePorts(entry, planned));
 
   const openUrl = client.sameOrigin
     ? `http://localhost:${entry.port}`
@@ -2043,22 +3914,25 @@ async function setupWorkspace(cfg, action) {
   );
   const waitingForStart = !aiServerUp;
   const warning = waitingForStart
-    ? "Folder is attached in Maintainer Pro. Use Start chat server when you want to launch the apps."
+    ? "Folder is attached in Maintainer Pro. Use Start Apps when you want to launch the apps."
     : processIssues[0]?.message || null;
 
-  for (const note of client.notes) log(note);
-  if (waitingForStart) {
-    log(`folder attached — waiting for Start (${openUrl})`);
-  } else {
-    log(`ai-server already up — open ${openUrl}`);
-  }
+  for (const note of client.notes) log(`setup note ${note}`);
+  log(
+    waitingForStart
+      ? `setup done — waiting for Start (${openUrl}) kind=${client.kind}`
+      : `setup done — chat already up (${openUrl}) kind=${client.kind}`
+  );
 
+  const host = workspaceHostReport(entry);
   return {
     sandboxId,
     folderPath: resolved,
     port: entry.port,
-    appUrl: entry.appUrl || appUrl,
-    origins: [...new Set([corsOrigin, aiOrigin, entry.appUrl].filter(Boolean))],
+    appUrl: host.appUrl || entry.appUrl || appUrl,
+    origins: host.origins.length
+      ? host.origins
+      : [...new Set([corsOrigin, aiOrigin, entry.appUrl].filter(Boolean))],
     wroteEnv: true,
     clientKind: client.kind,
     clientFiles: client.filesWritten,
@@ -2070,26 +3944,64 @@ async function setupWorkspace(cfg, action) {
     warning,
     waitingForStart,
     projectInfo,
+    ignorePaths: access.ignorePaths,
   };
 }
 
 async function runActions(cfg, actions) {
+  if (!actions.length) return;
+  log(`actions received ${actions.length}: ${actions.map((a) => a.code).join(", ")}`);
   for (const action of actions) {
-    log(`action ${action.code} (${action.id})`);
+    const startedAt = Date.now();
+    const label = actionLabel(action);
+    log(`${label} start`);
     let ok = true;
     /** @type {Record<string, unknown>} */
     let result = {};
     try {
       if (action.code === "browse") {
         const p = String(action.payload?.path || process.cwd());
+        log(`${label} browse ${p}`);
         result = listDirEntries(p);
+        log(`${label} browse ${result.entries?.length ?? 0} entries`);
       } else if (action.code === "setup_workspace") {
         result = await setupWorkspace(cfg, action);
+      } else if (action.code === "sync_access_policy") {
+        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),
+              }
+            : null);
+        if (!ws?.folderPath) {
+          ok = false;
+          result = { error: "No workspace folder for access policy sync" };
+          warn(`${label} skipped: ${result.error}`);
+        } else {
+          const partnerIgnorePaths = Array.isArray(action.payload?.aiIgnorePaths)
+            ? action.payload.aiIgnorePaths
+            : [];
+          const access = applyAccessPolicy(ws.folderPath, partnerIgnorePaths);
+          log(
+            `access policy synced for ${ws.folderPath} (${access.ignorePaths.length} ignore rules)`
+          );
+          result = {
+            folderPath: path.resolve(ws.folderPath),
+            ignorePaths: access.ignorePaths,
+            syncedAt: new Date().toISOString(),
+          };
+        }
       } else if (action.code === "recheck") {
         const sandboxId = action.sandboxId || action.payload?.sandboxId;
         const ws = (cfg.workspaces || []).find((w) => w.sandboxId === sandboxId);
+        if (!ws) {
+          log(`${label} recheck: no local workspace`);
+        }
         const projectInfo = ws
-          ? await inspectProjectWithAiCli(ws, { cfg })
+          ? await inspectProjectWithAiCli(ws, { cfg, force: true })
           : null;
         result = {
           recheckedAt: new Date().toISOString(),
@@ -2109,18 +4021,57 @@ async function runActions(cfg, actions) {
         if (!ws || cfg.noAiServer) {
           ok = false;
           result = { error: "No workspace or --no-ai-server" };
+          warn(`${label} skipped: ${result.error}`);
         } else {
-          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.",
+          // Prefer cached project inspect; only call ai-cli when missing or
+          // after a failed start that used the cache.
+          log(`${label} start ${ws.folderPath}`);
+          let projectInfo = await inspectProjectWithAiCli(ws, { cfg });
+          let started = await startAppsForWorkspace(ws, cfg, {
+            actionId: action.id,
           });
+          const launchFailed =
+            Array.isArray(started.processIssues) &&
+            started.processIssues.some(
+              (issue) =>
+                issue.code === "ai_server_launch" ||
+                issue.code === "host_process_launch" ||
+                issue.code === "host_process_down" ||
+                issue.code === "project_issue"
+            );
+          const nothingUp =
+            !started.up &&
+            !(
+              Array.isArray(started.startedHosts) &&
+              started.startedHosts.length
+            );
+          if ((launchFailed || nothingUp) && projectInfo?.cached) {
+            const problem = [
+              ...issuesForSandbox(ws.sandboxId).map((issue) => issue.message),
+              started.warning,
+              "Local processes did not come up using the cached project setup.",
+            ]
+              .filter(Boolean)
+              .join("\n");
+            log(
+              `${label} start incomplete — re-inspecting project with ai-cli`
+            );
+            await reportActionProgress(
+              cfg,
+              action.id,
+              "Start did not fully succeed — re-analyzing the project…"
+            );
+            projectInfo = await inspectProjectWithAiCli(ws, {
+              cfg,
+              force: true,
+              problem,
+            });
+            started = await startAppsForWorkspace(ws, cfg, {
+              actionId: action.id,
+            });
+          }
           result = {
-            ...(await startAppsForWorkspace(ws, cfg)),
+            ...started,
             projectInfo,
           };
           if (
@@ -2134,14 +4085,23 @@ async function runActions(cfg, actions) {
       } else if (action.code === "refresh_public_url") {
         const sandboxId = action.sandboxId || action.payload?.sandboxId;
         const ws = (cfg.workspaces || []).find((w) => w.sandboxId === sandboxId);
+        const host = ws ? workspaceHostReport(ws) : { appUrl: null, origins: [] };
         result = {
+          sandboxId: sandboxId || ws?.sandboxId || null,
           appUrl:
+            host.appUrl ||
             ws?.cloudflareUrl ||
             ws?.appUrl ||
             process.env.APP_URL ||
             process.env.PUBLIC_URL ||
             null,
+          origins: host.origins,
         };
+        log(
+          `${label} public url ${result.appUrl || "(none)"} origins=${
+            host.origins.join(",") || "none"
+          }`
+        );
       } else if (action.code === "configure_cloudflare") {
         const sandboxId = action.sandboxId || action.payload?.sandboxId;
         const ws =
@@ -2161,8 +4121,11 @@ async function runActions(cfg, actions) {
         if (!ws) {
           ok = false;
           result = { error: "No folder is attached for this sandbox" };
+          warn(`${label} skipped: ${result.error}`);
         } else {
-          result = await configureCloudflareForWorkspace(ws, cfg);
+          result = await configureCloudflareForWorkspace(ws, cfg, {
+            actionId: action.id,
+          });
         }
       } else if (action.code === "remove_workspace") {
         const sandboxId = String(
@@ -2174,15 +4137,26 @@ async function runActions(cfg, actions) {
         );
         saveConfig(cfg);
         result = { removedSandboxId: sandboxId };
+        log(`${label} removed workspace`);
       } else {
         ok = false;
         result = { error: `Unknown action ${action.code}` };
+        warn(`${label} skipped: ${result.error}`);
       }
     } catch (err) {
       ok = false;
       result = { error: err instanceof Error ? err.message : String(err) };
+      warn(`${label} threw: ${result.error}`);
     }
 
+    const elapsed = Date.now() - startedAt;
+    const summary = resultSummary(result);
+    log(
+      `${label} ${ok ? "ok" : "failed"} ${elapsed}ms${
+        summary ? ` ${summary}` : ""
+      }`
+    );
+
     try {
       await api(
         cfg.adminUrl,
@@ -2191,9 +4165,10 @@ async function runActions(cfg, actions) {
         `/api/v1/bridge/machine/actions/${action.id}/complete`,
         { ok, result }
       );
+      log(`${label} reported to admin`);
     } catch (err) {
       warn(
-        `failed to complete action: ${
+        `${label} report failed: ${
           err instanceof Error ? err.message : String(err)
         }`
       );
@@ -2202,50 +4177,155 @@ async function runActions(cfg, actions) {
 }
 
 async function collectWorkspaceStates(cfg) {
-  /** @type {Array<{sandboxId:string,sandboxName?:string,port:number,aiServerUp:boolean,startingAi:boolean,folderPath:string,appUrl?:string|null}>} */
+  /** @type {Array<{sandboxId:string,sandboxName?:string,port:number,aiServerUp:boolean,startingAi:boolean,folderPath:string,appUrl?:string|null,origins?:string[]}>} */
   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);
+    const status = await reconcileWorkspacePresence(ws, cfg, {
+      writeEnv: true,
+      timeoutMs: 800,
+    });
     localStates.push({
       sandboxId: ws.sandboxId,
       sandboxName: ws.sandboxName,
-      port: ws.port,
+      port: status.probe.chatPort || ws.port,
       folderPath: ws.folderPath,
-      aiServerUp: up,
+      aiServerUp: status.aiServerUp,
+      appsRunning: status.appsRunning,
       startingAi: recentlyLaunched(`${ws.sandboxId}:${folder}:ai`),
-      appUrl: ws.appUrl || null,
-      appsRequested: appsWanted(ws),
+      appUrl:
+        status.appsRunning || status.usingCloudflare
+          ? status.host.appUrl || ws.appUrl || null
+          : null,
+      origins:
+        status.appsRunning || status.usingCloudflare
+          ? status.host.origins
+          : [],
+      appsRequested: appsWanted(ws) || status.appsRunning,
     });
   }
   return localStates;
 }
 
+/** @type {Map<string, string>} */
+const lastHostReports = new Map();
+
+function syncAssignedWorkspaces(cfg, remotes) {
+  if (!Array.isArray(remotes)) return;
+  for (const remote of remotes) {
+    const local = (cfg.workspaces || []).find(
+      (w) => w.sandboxId === remote.sandboxId
+    );
+    if (!local) {
+      cfg.workspaces = cfg.workspaces || [];
+      cfg.workspaces.push({
+        sandboxId: remote.sandboxId,
+        folderPath: remote.folderPath,
+        port: remote.port,
+        sandboxName: remote.sandboxName,
+        applicationName: remote.applicationName,
+      });
+      saveConfig(cfg);
+    } else if (local.folderPath !== remote.folderPath) {
+      local.folderPath = remote.folderPath;
+      local.port = remote.port;
+      saveConfig(cfg);
+    }
+  }
+}
+
 async function sendHeartbeat(cfg, folders, localStates) {
+  for (const st of localStates) {
+    if (!st.appsRunning) continue;
+    const key = `${st.appUrl || ""}|${(st.origins || []).join(",")}`;
+    if (lastHostReports.get(st.sandboxId) === key) continue;
+    lastHostReports.set(st.sandboxId, key);
+    log(
+      `host report sandbox=${shortId(st.sandboxId)} app=${
+        st.appUrl || "(none)"
+      } origins=${(st.origins || []).join(",") || "none"}`
+    );
+  }
+  const body = {
+    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,
+      appsRunning: Boolean(st.appsRunning),
+      port: st.port,
+      appUrl: st.appsRunning && st.appUrl ? st.appUrl : undefined,
+      origins:
+        st.appsRunning && Array.isArray(st.origins) && st.origins.length
+          ? st.origins
+          : undefined,
+      appsRequested: Boolean(st.appsRequested),
+    })),
+  };
   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,
-        appsRequested: Boolean(st.appsRequested),
-      })),
-    }
+    body
   );
 }
 
+function buildLightHeartbeatPayload(cfg, folders) {
+  return {
+    type: "heartbeat",
+    hostname: os.hostname(),
+    platform: `${os.platform()}-${os.arch()}`,
+    bridgeVersion: PACKAGE_VERSION,
+    folders,
+  };
+}
+
+async function buildHeartbeatPayload(cfg, folders, localStates) {
+  for (const st of localStates) {
+    if (!st.appsRunning) continue;
+    const key = `${st.appUrl || ""}|${(st.origins || []).join(",")}`;
+    if (lastHostReports.get(st.sandboxId) === key) continue;
+    lastHostReports.set(st.sandboxId, key);
+    log(
+      `host report sandbox=${shortId(st.sandboxId)} app=${
+        st.appUrl || "(none)"
+      } origins=${(st.origins || []).join(",") || "none"}`
+    );
+  }
+  return {
+    type: "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,
+      appsRunning: Boolean(st.appsRunning),
+      port: st.port,
+      appUrl: st.appsRunning && st.appUrl ? st.appUrl : undefined,
+      origins:
+        st.appsRunning && Array.isArray(st.origins) && st.origins.length
+          ? st.origins
+          : undefined,
+      appsRequested: Boolean(st.appsRequested),
+    })),
+  };
+}
+
+function adminWsUrl(adminUrl, token) {
+  const base = String(adminUrl || "").replace(/\/$/, "");
+  const u = new URL(`${base}/api/v1/ws`);
+  u.protocol = u.protocol === "https:" ? "wss:" : "ws:";
+  u.searchParams.set("token", token);
+  return u.toString();
+}
+
 async function buildIssues(cfg, workspaceStates) {
   /** @type {Array<Record<string, unknown>>} */
   const issues = [];
@@ -2263,15 +4343,15 @@ async function buildIssues(cfg, workspaceStates) {
     });
   }
   for (const st of workspaceStates) {
-    if (st.aiServerUp || st.startingAi) continue;
+    if (st.aiServerUp || st.appsRunning || st.startingAi) continue;
     if (!st.appsRequested) {
       issues.push({
         code: "apps_not_started",
         severity: "info",
         title: `Apps are not running (${st.sandboxName || "sandbox"})`,
         message:
-          "This folder is attached in Maintainer Pro. Use Start chat server when you want to launch the local apps.",
-        resolution: "Use Start chat server.",
+          "This folder is attached in Maintainer Pro. Use Start Apps when you want to launch the local apps.",
+        resolution: "Use Start Apps.",
         actionCode: "start_ai_server",
         sandboxId: st.sandboxId,
       });
@@ -2292,7 +4372,7 @@ async function buildIssues(cfg, workspaceStates) {
         `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.",
+        "Read the error in that terminal, then use Start Apps.",
       actionCode: "start_ai_server",
       sandboxId: st.sandboxId,
     });
@@ -2369,12 +4449,22 @@ async function pairFlow(args) {
 }
 
 async function main() {
+  if (!process.env.NODE_ENV?.trim()) {
+    process.env.NODE_ENV = "development";
+  }
+  logger = createLogger("ai-bridge");
+
   const args = parseArgs(process.argv.slice(2));
   if (args.help) {
     printHelp();
     process.exit(0);
   }
 
+  logger.debug(
+    { logLevel: logger.level, nodeEnv: process.env.NODE_ENV },
+    "bridge starting"
+  );
+
   let cfg = loadConfig() || {};
   ensureMachineId(cfg);
 
@@ -2398,113 +4488,307 @@ async function main() {
   log(`machine ${cfg.machineId}`);
   log(`admin ${cfg.adminUrl}`);
   log(`config ${configPath()}`);
+  log(
+    `online via websocket (presence every ${HEARTBEAT_MS / 1000}s, ping every ${WS_PING_MS / 1000}s)`
+  );
+  await restoreHostsAfterReconnect(cfg);
 
-  const tick = async () => {
-    const remoteWorkspaces = [];
+  /** @type {unknown[]} */
+  const claimedActions = [];
+  let workBusy = false;
+
+  const runWork = async () => {
+    if (workBusy) return;
+    workBusy = true;
     try {
-      // Heartbeat first — server returns assigned workspaces
-      const folders = collectOfferedFolders(cfg);
-      /** @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 (appsWanted(ws) && !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");
-            clearProcessProblem(ws.sandboxId, "apps_not_started");
-          }
-        }
-        if (appsWanted(ws)) {
-          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,
-          appsRequested: appsWanted(ws),
-        });
+      while (claimedActions.length) {
+        const batch = claimedActions.splice(0, claimedActions.length);
+        await runActions(cfg, batch);
       }
+    } catch (err) {
+      warn(err instanceof Error ? err.message : String(err));
+    } finally {
+      workBusy = false;
+      if (claimedActions.length) void runWork();
+    }
+  };
 
-      const hb = await sendHeartbeat(cfg, folders, localStates);
+  const queueActions = (actions) => {
+    if (!Array.isArray(actions) || actions.length === 0) return;
+    claimedActions.push(...actions);
+    void runWork();
+  };
 
-      // Sync local workspace list from server assignments
-      if (Array.isArray(hb.workspaces)) {
-        for (const remote of hb.workspaces) {
-          remoteWorkspaces.push(remote);
-          const local = (cfg.workspaces || []).find(
-            (w) => w.sandboxId === remote.sandboxId
-          );
-          if (!local) {
-            cfg.workspaces = cfg.workspaces || [];
-            cfg.workspaces.push({
-              sandboxId: remote.sandboxId,
-              folderPath: remote.folderPath,
-              port: remote.port,
-              sandboxName: remote.sandboxName,
-              applicationName: remote.applicationName,
-            });
-            saveConfig(cfg);
-          } else if (local.folderPath !== remote.folderPath) {
-            local.folderPath = remote.folderPath;
-            local.port = remote.port;
-            saveConfig(cfg);
-          }
-        }
-      }
+  /** @type {import('ws').WebSocket | null} */
+  let socket = null;
+  let heartbeatTimer = null;
+  let pingTimer = null;
+  let reconnectTimer = null;
+  let wsGeneration = 0;
+  let reconnectAttempt = 0;
+  let stopped = false;
+  let presenceBusy = false;
+
+  const sendJson = (payload) => {
+    if (!socket || socket.readyState !== 1) return false;
+    try {
+      socket.send(JSON.stringify(payload));
+      return true;
+    } catch {
+      return false;
+    }
+  };
 
-      if (Array.isArray(hb.actions) && hb.actions.length > 0) {
-        await runActions(cfg, hb.actions);
-        await sendHeartbeat(cfg, folders, await collectWorkspaceStates(cfg));
-      }
+  const clearHeartbeatTimer = () => {
+    if (heartbeatTimer) {
+      clearInterval(heartbeatTimer);
+      heartbeatTimer = null;
+    }
+  };
+
+  const clearPingTimer = () => {
+    if (pingTimer) {
+      clearInterval(pingTimer);
+      pingTimer = null;
+    }
+  };
+
+  const clearReconnectTimer = () => {
+    if (reconnectTimer) {
+      clearTimeout(reconnectTimer);
+      reconnectTimer = null;
+    }
+  };
+
+  const sendPing = () => {
+    sendJson({ type: "ping" });
+    sendLightPresence();
+  };
+
+  const sendLightPresence = () => {
+    const folders = collectOfferedFolders(cfg);
+    sendJson(buildLightHeartbeatPayload(cfg, folders));
+  };
+
+  const sendPresenceOverWs = async () => {
+    if (!socket || socket.readyState !== 1 || presenceBusy) return;
+    presenceBusy = true;
+    try {
+      const folders = collectOfferedFolders(cfg);
+      const localStates = await collectWorkspaceStates(cfg);
+      const payload = await buildHeartbeatPayload(cfg, folders, localStates);
+      sendJson(payload);
     } catch (err) {
       warn(err instanceof Error ? err.message : String(err));
+    } finally {
+      presenceBusy = false;
     }
   };
 
-  let cycleBusy = false;
-  const runLocked = async (fn) => {
-    if (cycleBusy) return;
-    cycleBusy = true;
+  const handleChatRun = async (msg) => {
+    const sandboxId = typeof msg.sandboxId === "string" ? msg.sandboxId : "";
+    const conversationId =
+      typeof msg.conversationId === "string" ? msg.conversationId : "";
+    const userMessageId =
+      typeof msg.userMessageId === "string" ? msg.userMessageId : "";
+    const content = typeof msg.content === "string" ? msg.content : "";
+    const messages = Array.isArray(msg.messages)
+      ? msg.messages.filter(
+          (row) =>
+            row &&
+            (row.role === "user" || row.role === "assistant") &&
+            typeof row.content === "string"
+        )
+      : [];
+    const payloadMessages = messages.length
+      ? messages
+      : content
+        ? [{ role: "user", content }]
+        : [];
+    const fail = (error) => {
+      warn(`chat.run: ${error}`);
+      sendJson({
+        type: "chat.run.result",
+        ok: false,
+        sandboxId,
+        conversationId,
+        userMessageId,
+        error,
+      });
+    };
+    if (!conversationId || payloadMessages.length === 0) {
+      fail("missing conversation or messages");
+      return;
+    }
+    const ws = (cfg.workspaces || []).find(
+      (row) => row.sandboxId === sandboxId
+    );
+    if (!ws) {
+      fail(`no local workspace for sandbox ${sandboxId || "?"}`);
+      return;
+    }
+    const chat = await discoverChatPort(ws, 2500);
+    if (chat.up) ws.port = chat.port;
+    const port = Number(chat.port || ws.port) || 3100;
+    const url = `http://127.0.0.1:${port}/api/chat`;
+    log(`chat.run → ${url} (${conversationId})`);
     try {
-      await fn();
-    } finally {
-      cycleBusy = false;
+      const res = await fetch(url, {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          accept: "application/json",
+        },
+        body: JSON.stringify({
+          conversationId,
+          messages: payloadMessages,
+          userMessage: content || undefined,
+          skipPersistUser: true,
+          userMessageId: userMessageId || undefined,
+          senderType: msg.senderType === "client" ? "client" : undefined,
+          senderName:
+            typeof msg.senderName === "string" ? msg.senderName : undefined,
+        }),
+      });
+      const text = await res.text();
+      let data = null;
+      try {
+        data = text ? JSON.parse(text) : null;
+      } catch {
+        data = { raw: text };
+      }
+      if (!res.ok) {
+        fail(data?.error || `AI server ${res.status}`);
+        return;
+      }
+      log(`chat.run ok (${conversationId})`);
+      sendJson({
+        type: "chat.run.result",
+        ok: true,
+        sandboxId,
+        conversationId,
+        userMessageId,
+      });
+    } catch (err) {
+      fail(err instanceof Error ? err.message : String(err));
     }
   };
 
-  await runLocked(tick);
-  setInterval(() => {
-    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);
+  const handleWsMessage = (raw) => {
+    let msg;
+    try {
+      msg = JSON.parse(String(raw));
+    } catch {
+      return;
+    }
+    if (!msg || typeof msg !== "object") return;
+    if (msg.type === "pong" || msg.type === "hello") return;
+    if (msg.type === "actions") {
+      queueActions(msg.actions);
+      return;
+    }
+    if (msg.type === "heartbeat.ok") {
+      syncAssignedWorkspaces(cfg, msg.workspaces);
+      queueActions(msg.actions);
+      return;
+    }
+    if (msg.type === "chat.run") {
+      void handleChatRun(msg);
+      return;
+    }
+    if (msg.type === "error") {
+      warn(`ws: ${msg.error || "error"}`);
+    }
+  };
+
+  const scheduleReconnect = (code, reason) => {
+    if (stopped || reconnectTimer) return;
+    const delay = Math.min(
+      WS_RECONNECT_MAX_MS,
+      WS_RECONNECT_MIN_MS * 2 ** Math.min(reconnectAttempt, 4)
+    );
+    reconnectAttempt += 1;
+    const detail = reason ? ` ${reason}` : "";
+    const wait =
+      delay < 1000 ? `${delay}ms` : `${Math.round(delay / 1000)}s`;
+    warn(
+      `websocket closed (${code || "?"}${detail}); reconnecting in ${wait}`
+    );
+    reconnectTimer = setTimeout(() => {
+      reconnectTimer = null;
+      connectWs();
+    }, delay);
+  };
+
+  const connectWs = () => {
+    if (stopped) return;
+    clearReconnectTimer();
+    const generation = ++wsGeneration;
+    if (socket) {
+      try {
+        socket.close();
+      } catch {
+        /* ignore */
       }
+      socket = null;
+    }
+    const url = adminWsUrl(cfg.adminUrl, cfg.token);
+    log(
+      reconnectAttempt
+        ? `websocket connecting (attempt ${reconnectAttempt + 1})…`
+        : "websocket connecting…"
+    );
+    /** @type {WebSocket} */
+    const ws = new WebSocket(url);
+    socket = ws;
+
+    ws.addEventListener("open", () => {
+      if (generation !== wsGeneration) return;
+      reconnectAttempt = 0;
+      log("websocket connected");
+      clearHeartbeatTimer();
+      clearPingTimer();
+      sendPing();
+      sendLightPresence();
+      void sendPresenceOverWs();
+      pingTimer = setInterval(sendPing, WS_PING_MS);
+      heartbeatTimer = setInterval(() => {
+        void sendPresenceOverWs();
+      }, HEARTBEAT_MS);
+    });
+
+    ws.addEventListener("message", (event) => {
+      if (generation !== wsGeneration) return;
+      handleWsMessage(event.data);
+    });
+
+    ws.addEventListener("close", (event) => {
+      if (generation !== wsGeneration) return;
+      clearHeartbeatTimer();
+      clearPingTimer();
+      if (socket === ws) socket = null;
+      scheduleReconnect(event.code, event.reason);
     });
-  }, ACTION_POLL_MS);
+
+    ws.addEventListener("error", () => {
+      // close handler drives reconnect
+    });
+  };
+
+  connectWs();
 
   const shutdown = () => {
+    stopped = true;
+    wsGeneration += 1;
+    clearHeartbeatTimer();
+    clearPingTimer();
+    clearReconnectTimer();
     stopAllCloudflare();
+    try {
+      socket?.close();
+    } catch {
+      /* ignore */
+    }
     log("shutting down (other terminals stay open)");
     process.exit(0);
   };