@maintainer-pro/ai-bridge 0.1.2 → 0.1.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maintainer-pro/ai-bridge",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Local bridge daemon that pairs a machine to Maintainer Pro and configures multiple client sandboxes.",
   "keywords": [
     "maintainer-pro",

package/src/daemon.mjs

@@ -850,7 +850,65 @@ const launchedAt = new Map();
 /** Last process problems to send on heartbeat. Key: sandboxId::code::role */
 const processProblems = new Map();
 
-function forgetLaunch(sandboxId) {
+/** @type {Map<string, Set<string>>} sandboxId -> CMD/terminal titles we opened */
+const openedTerminalTitles = new Map();
+
+function rememberTerminalTitle(sandboxId, title) {
+  const id = String(sandboxId || "").trim();
+  const name = String(title || "").trim();
+  if (!id || !name) return;
+  let titles = openedTerminalTitles.get(id);
+  if (!titles) {
+    titles = new Set();
+    openedTerminalTitles.set(id, titles);
+  }
+  titles.add(name);
+}
+
+function closeWindowsByTitle(title) {
+  const name = String(title || "").trim();
+  if (!name) return Promise.resolve();
+  return new Promise((resolve) => {
+    const done = () => resolve();
+    if (process.platform === "win32") {
+      const child = spawn(
+        "taskkill",
+        ["/F", "/T", "/FI", `WINDOWTITLE eq ${name}*`],
+        { windowsHide: true, stdio: "ignore" }
+      );
+      child.on("exit", done);
+      child.on("error", done);
+      setTimeout(done, 4000);
+      return;
+    }
+    if (process.platform === "darwin") {
+      const child = spawn(
+        "osascript",
+        [
+          "-e",
+          `tell application "Terminal" to close (every window whose name contains ${JSON.stringify(name)})`,
+        ],
+        { stdio: "ignore" }
+      );
+      child.on("exit", done);
+      child.on("error", done);
+      setTimeout(done, 4000);
+      return;
+    }
+    done();
+  });
+}
+
+async function closeRememberedTerminals(sandboxId) {
+  const titles = openedTerminalTitles.get(sandboxId);
+  if (!titles) return;
+  for (const title of titles) {
+    await closeWindowsByTitle(title);
+  }
+  openedTerminalTitles.delete(sandboxId);
+}
+
+async function forgetLaunch(sandboxId) {
   for (const key of [...launchedAt.keys()]) {
     if (key === sandboxId || key.startsWith(`${sandboxId}:`)) {
       launchedAt.delete(key);
@@ -859,7 +917,8 @@ function forgetLaunch(sandboxId) {
   for (const key of [...processProblems.keys()]) {
     if (key.startsWith(`${sandboxId}::`)) processProblems.delete(key);
   }
-  stopCloudflare(sandboxId);
+  await closeRememberedTerminals(sandboxId);
+  await stopCloudflare(sandboxId);
 }
 
 function problemKey(sandboxId, code, role = "") {
@@ -1073,9 +1132,11 @@ function runLauncher(command, args, extra = {}) {
 }
 
 async function openInNewTerminal(opts) {
-  const { title, folder, command, env = {}, launchKey } = opts;
+  const { title, folder, command, env = {}, launchKey, sandboxId } = opts;
   if (launchKey) {
-    if (recentlyLaunched(launchKey)) return { ok: true, skipped: true };
+    if (!opts.force && recentlyLaunched(launchKey)) {
+      return { ok: true, skipped: true };
+    }
     launchedAt.set(launchKey, Date.now());
   }
   if (!fs.existsSync(folder)) {
@@ -1084,6 +1145,13 @@ async function openInNewTerminal(opts) {
     return { ok: false, error };
   }
 
+  await closeWindowsByTitle(title);
+  await sleep(250);
+  rememberTerminalTitle(
+    sandboxId || String(launchKey || "").split(":")[0],
+    title
+  );
+
   const envWin = Object.entries(env)
     .map(([key, value]) => `set ${key}=${value}`)
     .join("&& ");
@@ -1096,18 +1164,14 @@ async function openInNewTerminal(opts) {
   try {
     if (process.platform === "win32") {
       const inner = `cd /d "${folder}" && ${envWin ? `${envWin}&& ` : ""}title ${title}&& ${command}`;
-      const escaped = inner.replace(/'/g, "''");
-      const opened = await runLauncher(
-        "powershell.exe",
-        [
-          "-NoProfile",
-          "-WindowStyle",
-          "Hidden",
-          "-Command",
-          `Start-Process -FilePath $env:ComSpec -WorkingDirectory ${JSON.stringify(folder)} -ArgumentList @('/k', '${escaped}')`,
-        ],
-        { windowsHide: true }
-      );
+      const opened = await runLauncher(process.env.ComSpec || "cmd.exe", [
+        "/c",
+        "start",
+        title,
+        "cmd.exe",
+        "/k",
+        inner,
+      ]);
       if (!opened.ok) {
         return { ok: false, error: friendlyLaunchError(opened.error, title) };
       }
@@ -1253,6 +1317,7 @@ async function startAiServerForWorkspace(ws, opts = {}) {
       NEXT_PUBLIC_AI_SERVER_URL: `http://localhost:${port}`,
     },
     launchKey,
+    sandboxId: ws.sandboxId,
   });
   if (opened.skipped) {
     return { port, up: false, launched: false, starting: true };
@@ -1276,189 +1341,423 @@ function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
-/** @type {Map<string, { child: import("node:child_process").ChildProcess, url: string | null, localUrl: string }>} */
+/** @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;
+}
+
+function killProcessesByCommand(fragment) {
+  if (!fragment) return Promise.resolve();
+  return new Promise((resolve) => {
+    const done = () => resolve();
+    if (process.platform === "win32") {
+      const escaped = String(fragment).replace(/'/g, "''");
+      const child = spawn(
+        "powershell.exe",
+        [
+          "-NoProfile",
+          "-Command",
+          `Get-CimInstance Win32_Process | Where-Object { $_.CommandLine -like '*${escaped}*' } | ForEach-Object { Stop-Process -Id $_.ProcessId -Force -ErrorAction SilentlyContinue }`,
+        ],
+        { windowsHide: true, stdio: "ignore" }
+      );
+      child.on("exit", done);
+      child.on("error", done);
+      setTimeout(done, 8000);
+      return;
+    }
+    const child = spawn("pkill", ["-f", String(fragment)], { stdio: "ignore" });
+    child.on("exit", done);
+    child.on("error", done);
+    setTimeout(done, 4000);
+  });
+}
+
+function killPort(port) {
+  const n = Number(port);
+  if (!n) return Promise.resolve();
+  return new Promise((resolve) => {
+    const done = () => resolve();
+    if (process.platform === "win32") {
+      const child = spawn(
+        "powershell.exe",
+        [
+          "-NoProfile",
+          "-Command",
+          `$ErrorActionPreference='SilentlyContinue'; $pids=@(); $pids += Get-NetTCPConnection -LocalPort ${n} -State Listen | Select-Object -ExpandProperty OwningProcess; if (-not $pids) { netstat -ano | Select-String ':${n}\\s' | ForEach-Object { if ($_ -match 'LISTENING\\s+(\\d+)') { $pids += [int]$Matches[1] } } }; $pids | Sort-Object -Unique | Where-Object { $_ -gt 0 -and $_ -ne ${process.pid} } | ForEach-Object { Stop-Process -Id $_ -Force }`,
+        ],
+        { windowsHide: true, stdio: "ignore" }
+      );
+      child.on("exit", done);
+      child.on("error", done);
+      setTimeout(done, 8000);
+      return;
+    }
+    const child = spawn(
+      "sh",
+      ["-c", `pids=$(lsof -ti tcp:${n} 2>/dev/null); [ -n "$pids" ] && kill $pids`],
+      { stdio: "ignore" }
+    );
+    child.on("exit", done);
+    child.on("error", done);
+    setTimeout(done, 4000);
+  });
+}
+
 function stopCloudflare(sandboxId) {
   const row = cloudflareTunnels.get(sandboxId);
-  if (row?.child && !row.child.killed) {
+  const files = row?.tunnels?.map((t) => t.logFile).filter(Boolean) ?? [];
+  cloudflareTunnels.delete(sandboxId);
+  return Promise.all(files.map((file) => killProcessesByCommand(file)));
+}
+
+function forgetProcessLaunches(sandboxId) {
+  for (const key of [...launchedAt.keys()]) {
+    if (key === sandboxId || key.startsWith(`${sandboxId}:`)) {
+      launchedAt.delete(key);
+    }
+  }
+}
+
+async function stopWorkspaceApps(ws) {
+  const folder = path.resolve(ws.folderPath || "");
+  const jobs = planHostJobs(folder, null, ws.projectInfo);
+  const ports = new Set();
+  if (ws.port) ports.add(Number(ws.port));
+  for (const job of jobs) {
+    if (job.preferredPort) ports.add(Number(job.preferredPort));
+  }
+  if (ws.appUrl && isLocalAppUrl(ws.appUrl)) {
     try {
-      row.child.kill();
+      const port = Number(new URL(ws.appUrl).port);
+      if (port) ports.add(port);
     } catch {
       /* ignore */
     }
   }
-  cloudflareTunnels.delete(sandboxId);
+  log(`stopping local apps on ports ${[...ports].join(", ") || "(none)"}`);
+  await closeRememberedTerminals(ws.sandboxId);
+  for (const port of ports) {
+    await killPort(port);
+  }
+  forgetProcessLaunches(ws.sandboxId);
+  await sleep(400);
 }
 
-function stopAllCloudflare() {
-  for (const id of [...cloudflareTunnels.keys()]) stopCloudflare(id);
+async function waitUntilReachable(url, timeoutMs, label) {
+  const start = Date.now();
+  while (Date.now() - start < timeoutMs) {
+    if (await probeUrl(url)) return true;
+    await sleep(600);
+  }
+  throw new Error(`${label} did not become reachable at ${url}`);
 }
 
-function localUrlForWorkspace(ws) {
-  if (ws.appUrl && isLocalAppUrl(ws.appUrl)) return ws.appUrl;
-  return `http://127.0.0.1:${Number(ws.port) || 3100}`;
+async function waitForUrlInFile(file, timeoutMs = 90_000) {
+  const start = Date.now();
+  while (Date.now() - start < timeoutMs) {
+    if (fs.existsSync(file)) {
+      const url = parseTryCloudflareUrl(fs.readFileSync(file, "utf8"));
+      if (url) return url;
+    }
+    await sleep(500);
+  }
+  throw new Error(
+    `Cloudflare did not publish a URL in time (${path.basename(file)}). Check that terminal.`
+  );
 }
 
-function parseTryCloudflareUrl(text) {
-  const match = String(text || "").match(
-    /https:\/\/[a-z0-9-]+\.trycloudflare\.com/i
-  );
-  return match ? match[0].replace(/\/$/, "") : null;
+function cloudflaredCommand(localUrl, logFile) {
+  const logArg = JSON.stringify(logFile);
+  const run = `npx --yes cloudflared tunnel --url ${localUrl} --no-autoupdate --logfile ${logArg}`;
+  if (process.platform === "win32") return run;
+  return `${run} 2>&1 | tee ${logArg}`;
 }
 
-function spawnCloudflared(localUrl) {
-  const args = ["tunnel", "--url", localUrl, "--no-autoupdate"];
-  const trySpawn = (file, argv, extra = {}) =>
-    new Promise((resolve, reject) => {
-      const child = spawn(file, argv, {
-        stdio: ["ignore", "pipe", "pipe"],
-        windowsHide: true,
-        ...extra,
-      });
-      const onError = (err) => reject(err);
-      child.once("error", onError);
-      child.once("spawn", () => {
-        child.off("error", onError);
-        resolve(child);
-      });
-    });
+async function startCloudflareTerminal(ws, role, localUrl) {
+  const folder = path.resolve(ws.folderPath);
+  const logDir = path.join(folder, ".maintainer-pro");
+  fs.mkdirSync(logDir, { recursive: true });
+  const logFile = path.join(
+    logDir,
+    `cf-${String(ws.sandboxId).slice(0, 8)}-${role}.log`
+  );
+  try {
+    fs.unlinkSync(logFile);
+  } catch {
+    /* ignore */
+  }
+  const opened = await openInNewTerminal({
+    title: `MP-cf-${role}`,
+    folder,
+    command: cloudflaredCommand(localUrl, logFile),
+    launchKey: `${ws.sandboxId}:cf:${role}`,
+    sandboxId: ws.sandboxId,
+    force: true,
+  });
+  if (!opened.ok) {
+    throw new Error(opened.error || `Could not open a Cloudflare terminal for ${role}`);
+  }
+  const publicUrl = await waitForUrlInFile(logFile);
+  return { role, localUrl, publicUrl, logFile };
+}
 
-  return trySpawn("cloudflared", args).catch(() =>
-    trySpawn(
-      process.platform === "win32" ? "npx.cmd" : "npx",
-      ["--yes", "cloudflared", ...args],
-      { shell: process.platform === "win32" }
-    )
+function uiPublicEnv(tunnels) {
+  /** @type {Record<string, string>} */
+  const env = {};
+  if (tunnels.ai) {
+    env.AI_SERVER_URL = tunnels.ai;
+    env.NEXT_PUBLIC_AI_SERVER_URL = tunnels.ai;
+    env.VITE_AI_SERVER_URL = tunnels.ai;
+  }
+  if (tunnels.backend) {
+    env.API_URL = tunnels.backend;
+    env.API_BASE_URL = tunnels.backend;
+    env.VITE_API_URL = tunnels.backend;
+    env.VITE_API_BASE_URL = tunnels.backend;
+    env.NEXT_PUBLIC_API_URL = tunnels.backend;
+    env.NEXT_PUBLIC_API_BASE_URL = tunnels.backend;
+    env.BACKEND_URL = tunnels.backend;
+  }
+  if (tunnels.ui) {
+    env.APP_URL = tunnels.ui;
+    env.PUBLIC_URL = tunnels.ui;
+    env.CORS_ORIGIN = tunnels.ui;
+  } else if (tunnels.ai) {
+    env.CORS_ORIGIN = tunnels.ai;
+  }
+  return env;
+}
+
+function writeTunnelEnv(ws, tunnels) {
+  const folder = ws.folderPath ? path.resolve(ws.folderPath) : null;
+  if (!folder || !fs.existsSync(folder)) return;
+  const env = uiPublicEnv(tunnels);
+  const lines = Object.entries(tunnels)
+    .filter(([, url]) => url)
+    .map(([role, url]) => `${role}=${url}`);
+  fs.writeFileSync(
+    path.join(folder, ".cloudflare-tunnel-url"),
+    `${lines.join("\n")}\n`,
+    "utf8"
   );
+  const envPath = path.join(folder, ".env");
+  if (Object.keys(env).length) mergeEnvFile(envPath, env);
+  const localEnv = {};
+  if (env.NEXT_PUBLIC_AI_SERVER_URL) {
+    localEnv.NEXT_PUBLIC_AI_SERVER_URL = env.NEXT_PUBLIC_AI_SERVER_URL;
+  }
+  if (env.NEXT_PUBLIC_API_URL) {
+    localEnv.NEXT_PUBLIC_API_URL = env.NEXT_PUBLIC_API_URL;
+  }
+  if (Object.keys(localEnv).length) {
+    mergeEnvFile(path.join(folder, ".env.local"), localEnv);
+  }
 }
 
-function waitForTunnelUrl(child, timeoutMs = 90_000) {
-  return new Promise((resolve, reject) => {
-    let buffer = "";
-    let settled = false;
-    const done = (err, url) => {
-      if (settled) return;
-      settled = true;
-      clearTimeout(timer);
-      if (err) reject(err);
-      else resolve(url);
-    };
-    const onData = (chunk) => {
-      buffer += String(chunk);
-      const url = parseTryCloudflareUrl(buffer);
-      if (url) done(null, url);
-    };
-    child.stdout?.on("data", onData);
-    child.stderr?.on("data", onData);
-    child.once("exit", (code) => {
-      done(
-        new Error(
-          `cloudflared exited ${code ?? "early"} before it published a URL`
-        )
-      );
-    });
-    const timer = setTimeout(() => {
-      done(
-        new Error(
-          "Cloudflare did not publish a URL in time. Is cloudflared installed and online?"
-        )
-      );
-    }, timeoutMs);
-  });
+function reservedPortsFor(cfg, sandboxId) {
+  const reserved = new Set();
+  for (const other of cfg.workspaces || []) {
+    if (other.sandboxId !== sandboxId && other.port) {
+      reserved.add(Number(other.port));
+    }
+  }
+  return reserved;
+}
+
+function appsWanted(ws) {
+  return Boolean(ws?.appsRequested);
 }
 
 async function configureCloudflareForWorkspace(ws, cfg) {
   const sandboxId = ws.sandboxId;
   const label = ws.sandboxName || "this sandbox";
-  const localUrl = localUrlForWorkspace(ws);
-  const existing = cloudflareTunnels.get(sandboxId);
-  if (existing?.url && existing.localUrl === localUrl && existing.child && !existing.child.killed) {
-    return {
-      sandboxId,
-      folderPath: ws.folderPath,
-      appUrl: existing.url,
-      origins: [existing.url],
-      localUrl,
-      cloudflare: true,
-      reused: true,
-    };
-  }
-  if (existing) stopCloudflare(sandboxId);
 
-  log(`starting Cloudflare tunnel for ${label} → ${localUrl}`);
-  let child;
+  log(`Cloudflare queued for ${label}: stop apps and wait for Start`);
+  await stopCloudflare(sandboxId);
+  await stopWorkspaceApps(ws);
+  await forgetLaunch(sandboxId);
+  ws.cloudflarePending = true;
+  ws.appsRequested = false;
+  persistWorkspaceEntry(cfg, ws);
+
+  return {
+    sandboxId,
+    folderPath: ws.folderPath,
+    port: ws.port,
+    pending: true,
+    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.",
+  };
+}
+
+async function launchCloudflareTunnels(ws, cfg) {
+  const sandboxId = ws.sandboxId;
+  const label = ws.sandboxName || "this sandbox";
+  const folder = path.resolve(ws.folderPath || "");
+  const reserved = reservedPortsFor(cfg, sandboxId);
+
+  log(`Cloudflare start for ${label}: tunnel chat script/backend before UI`);
   try {
-    child = await spawnCloudflared(localUrl);
-  } catch (err) {
-    const message = err instanceof Error ? err.message : String(err);
-    recordProcessProblem({
-      sandboxId,
-      code: "cloudflare_launch",
-      role: "tunnel",
-      title: `Could not start Cloudflare (${label})`,
-      message,
-      resolution:
-        "Install cloudflared (https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/) or allow npx to download it, then try again.",
-      actionCode: "configure_cloudflare",
-    });
-    throw new Error(
-      `Could not start cloudflared. Install it or allow npx to download it. ${message}`
+  if (!cfg.noAiServer) {
+    await startAiServerForWorkspace(ws, { reserved, cfg });
+    await waitUntilReachable(
+      `http://127.0.0.1:${ws.port}/embed-config.js`,
+      45_000,
+      "Chat script"
     );
   }
 
-  cloudflareTunnels.set(sandboxId, { child, url: null, localUrl });
-  child.once("exit", () => {
-    const row = cloudflareTunnels.get(sandboxId);
-    if (row?.child === child) cloudflareTunnels.delete(sandboxId);
-  });
+  const jobs = planHostJobs(folder, null, ws.projectInfo);
+  const backendJob = jobs.find((job) => job.role === "backend");
+  const uiJob = jobs.find((job) => job.role === "ui" || job.role === "app");
+
+  if (backendJob) {
+    await ensureHostProcesses(ws, {
+      reserved,
+      cfg,
+      onlyRoles: ["backend"],
+      force: true,
+    });
+    const backendPort = Number(backendJob.preferredPort) || 4100;
+    await waitUntilReachable(
+      `http://127.0.0.1:${backendPort}`,
+      45_000,
+      "Backend"
+    );
+  }
 
-  const publicUrl = await waitForTunnelUrl(child);
-  cloudflareTunnels.set(sandboxId, { child, url: publicUrl, localUrl });
-  child.unref();
+  /** @type {Record<string, string>} */
+  const tunnels = {};
+  /** @type {Array<{ role: string, localUrl: string, publicUrl: string | null, logFile: string }>} */
+  const started = [];
 
-  ws.cloudflareUrl = publicUrl;
-  ws.appUrl = publicUrl;
-  const folder = ws.folderPath ? path.resolve(ws.folderPath) : null;
-  if (folder && fs.existsSync(folder)) {
-    fs.writeFileSync(
-      path.join(folder, ".cloudflare-tunnel-url"),
-      `${publicUrl}\n`,
-      "utf8"
+  const aiLocal = `http://127.0.0.1:${Number(ws.port) || 3100}`;
+  const aiTunnel = await startCloudflareTerminal(ws, "ai", aiLocal);
+  tunnels.ai = aiTunnel.publicUrl;
+  started.push(aiTunnel);
+  log(`Cloudflare chat script: ${aiTunnel.publicUrl}`);
+
+  if (backendJob) {
+    const backendLocal = `http://127.0.0.1:${Number(backendJob.preferredPort) || 4100}`;
+    const backendTunnel = await startCloudflareTerminal(ws, "backend", backendLocal);
+    tunnels.backend = backendTunnel.publicUrl;
+    started.push(backendTunnel);
+    log(`Cloudflare backend: ${backendTunnel.publicUrl}`);
+  }
+
+  writeTunnelEnv(ws, tunnels);
+  const uiEnv = uiPublicEnv(tunnels);
+
+  if (uiJob) {
+    await ensureHostProcesses(ws, {
+      reserved,
+      cfg,
+      onlyRoles: ["ui", "app"],
+      extraEnv: uiEnv,
+      force: true,
+    });
+    const uiPort = Number(uiJob.preferredPort) || 5173;
+    await waitUntilReachable(`http://127.0.0.1:${uiPort}`, 60_000, "App UI");
+    const uiTunnel = await startCloudflareTerminal(
+      ws,
+      "ui",
+      `http://127.0.0.1:${uiPort}`
     );
-    const envPath = path.join(folder, ".env");
-    const envValues = {
-      APP_URL: publicUrl,
-      PUBLIC_URL: publicUrl,
-      CORS_ORIGIN: publicUrl,
-    };
-    if (isAiServerTarget(ws, localUrl)) {
-      envValues.AI_SERVER_URL = publicUrl;
-      envValues.NEXT_PUBLIC_AI_SERVER_URL = publicUrl;
-    }
-    if (fs.existsSync(envPath)) mergeEnvFile(envPath, envValues);
+    tunnels.ui = uiTunnel.publicUrl;
+    started.push(uiTunnel);
+    log(`Cloudflare UI: ${uiTunnel.publicUrl}`);
+    writeTunnelEnv(ws, tunnels);
+    launchedAt.delete(`${sandboxId}:${folder}:ai`);
+    await killPort(ws.port);
+    await sleep(1500);
+    await startAiServerForWorkspace(ws, { reserved, cfg });
   }
+
+  const appUrl = tunnels.ui || tunnels.ai;
+  ws.cloudflareUrl = appUrl;
+  ws.cloudflare = tunnels;
+  ws.appUrl = appUrl;
+  ws.cloudflarePending = false;
+  ws.appsRequested = true;
   persistWorkspaceEntry(cfg, ws);
+  cloudflareTunnels.set(sandboxId, { tunnels: started });
   clearProcessProblem(sandboxId, "cloudflare_launch", "tunnel");
-  log(`Cloudflare URL for ${label}: ${publicUrl}`);
+
   return {
     sandboxId,
     folderPath: ws.folderPath,
-    appUrl: publicUrl,
-    origins: [publicUrl],
-    localUrl,
+    port: ws.port,
+    appUrl,
+    origins: Object.values(tunnels).filter(Boolean),
+    tunnels,
     cloudflare: true,
     reused: false,
   };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    recordProcessProblem({
+      sandboxId,
+      code: "cloudflare_launch",
+      role: "tunnel",
+      title: `Could not start Cloudflare (${label})`,
+      message,
+      resolution:
+        "Install cloudflared or allow npx to download it, then use Start chat server again.",
+      actionCode: "start_ai_server",
+    });
+    throw err;
+  }
 }
 
-function isAiServerTarget(ws, localUrl) {
-  try {
-    const port = Number(new URL(localUrl).port);
-    return port === Number(ws.port);
-  } catch {
-    return true;
+async function startAppsForWorkspace(ws, cfg) {
+  if (ws.cloudflarePending) {
+    return launchCloudflareTunnels(ws, cfg);
+  }
+  ws.appsRequested = true;
+  persistWorkspaceEntry(cfg, ws);
+  const reserved = reservedPortsFor(cfg, ws.sandboxId);
+  if (!cfg.noAiServer) {
+    await startAiServerForWorkspace(ws, { reserved, cfg });
+    await sleep(1500);
+  }
+  const startedHosts = await ensureHostProcesses(ws, {
+    reserved,
+    cfg,
+    force: true,
+  });
+  await sleep(800);
+  await inspectHostJobs(ws);
+  const up = await probeUrl(`http://127.0.0.1:${ws.port}/embed-config.js`);
+  if (up) {
+    clearProcessProblem(ws.sandboxId, "ai_server_launch", "ai");
+    clearProcessProblem(ws.sandboxId, "apps_not_started");
   }
+  const processIssues = issuesForSandbox(ws.sandboxId).map(
+    ({ role: _role, ...issue }) => issue
+  );
+  const warning = processIssues[0]?.message || null;
+  return {
+    up,
+    startedHosts,
+    sandboxId: ws.sandboxId,
+    folderPath: ws.folderPath,
+    port: ws.port,
+    appUrl: ws.appUrl,
+    processIssues,
+    warning,
+  };
 }
 
 async function ensureHostProcesses(ws, opts = {}) {
@@ -1466,7 +1765,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 || null, ws.projectInfo);
+  const jobs = planHostJobs(
+    folder,
+    ws.appUrl && isLocalAppUrl(ws.appUrl) ? ws.appUrl : null,
+    ws.projectInfo
+  );
+  const onlyRoles = Array.isArray(opts.onlyRoles) ? new Set(opts.onlyRoles) : null;
+  const extraEnv = opts.extraEnv && typeof opts.extraEnv === "object" ? opts.extraEnv : {};
   const started = [];
   let persisted = false;
   const label = ws.sandboxName || "this sandbox";
@@ -1484,6 +1789,7 @@ async function ensureHostProcesses(ws, opts = {}) {
   }
 
   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",
@@ -1497,7 +1803,7 @@ async function ensureHostProcesses(ws, opts = {}) {
       continue;
     }
     const launchKey = `${ws.sandboxId}:${folder}:${job.script}`;
-    if (recentlyLaunched(launchKey)) {
+    if (!opts.force && recentlyLaunched(launchKey)) {
       reserved.add(preferred);
       continue;
     }
@@ -1531,8 +1837,10 @@ async function ensureHostProcesses(ws, opts = {}) {
       title: `MP-${job.role}-${port}`,
       folder,
       command,
-      env: { PORT: String(port) },
+      env: { PORT: String(port), ...extraEnv },
       launchKey,
+      sandboxId: ws.sandboxId,
+      force: Boolean(opts.force),
     });
     if (opened.skipped) continue;
     if (!opened.ok) {
@@ -1563,7 +1871,11 @@ async function ensureHostProcesses(ws, opts = {}) {
 
 async function inspectHostJobs(ws) {
   const folder = path.resolve(ws.folderPath || "");
-  const jobs = planHostJobs(folder, ws.appUrl || null, ws.projectInfo);
+  const jobs = planHostJobs(
+    folder,
+    ws.appUrl && isLocalAppUrl(ws.appUrl) ? ws.appUrl : null,
+    ws.projectInfo
+  );
   const label = ws.sandboxName || "this sandbox";
   const hosts = [];
   for (const job of jobs) {
@@ -1587,6 +1899,11 @@ async function inspectHostJobs(ws) {
       clearProcessProblem(ws.sandboxId, "host_process_down", job.role);
       continue;
     }
+    if (!appsWanted(ws)) {
+      clearProcessProblem(ws.sandboxId, "host_process_launch", job.role);
+      clearProcessProblem(ws.sandboxId, "host_process_down", job.role);
+      continue;
+    }
     if (starting) continue;
     const tried = launchedAt.has(launchKey);
     recordProcessProblem({
@@ -1687,6 +2004,8 @@ async function setupWorkspace(cfg, action) {
     clientKind: client.kind,
     appUrl,
     sameOrigin: Boolean(client.sameOrigin),
+    appsRequested: false,
+    cloudflarePending: false,
   };
   if (existing >= 0) cfg.workspaces[existing] = entry;
   else cfg.workspaces.push(entry);
@@ -1705,12 +2024,6 @@ async function setupWorkspace(cfg, action) {
       .join("\n"),
   });
 
-  if (!cfg.noAiServer) {
-    await startAiServerForWorkspace(entry, { reserved, cfg });
-    await sleep(1500);
-  }
-  const startedHosts = await ensureHostProcesses(entry, { reserved, cfg });
-  await sleep(800);
   await inspectHostJobs(entry);
 
   const openUrl = client.sameOrigin
@@ -1719,23 +2032,22 @@ async function setupWorkspace(cfg, action) {
   const aiServerUp = await probeUrl(`http://127.0.0.1:${entry.port}/embed-config.js`);
   if (aiServerUp) {
     clearProcessProblem(sandboxId, "ai_server_launch", "ai");
+    clearProcessProblem(sandboxId, "apps_not_started");
   }
 
   const processIssues = issuesForSandbox(sandboxId).map(
     ({ role: _role, ...issue }) => issue
   );
-  const warning = processIssues[0]?.message || null;
+  const waitingForStart = !aiServerUp;
+  const warning = waitingForStart
+    ? "Folder is attached in Maintainer Pro. Use Start chat server when you want to launch the apps."
+    : processIssues[0]?.message || null;
 
   for (const note of client.notes) log(note);
-  if (startedHosts.length) {
-    log(`started ${startedHosts.join(" + ")} in separate terminals`);
-  }
-  if (aiServerUp) {
-    log(`ai-server up — open ${openUrl}`);
-  } else if (warning) {
-    log(`process issue: ${warning}`);
+  if (waitingForStart) {
+    log(`folder attached — waiting for Start (${openUrl})`);
   } else {
-    log("ai-server not reachable yet; it may still be starting");
+    log(`ai-server already up — open ${openUrl}`);
   }
 
   return {
@@ -1749,10 +2061,11 @@ async function setupWorkspace(cfg, action) {
     clientFiles: client.filesWritten,
     clientNotes: client.notes,
     aiServerUp,
-    startedHosts,
+    startedHosts: [],
     openUrl,
     processIssues,
     warning,
+    waitingForStart,
     projectInfo,
   };
 }
@@ -1794,12 +2107,6 @@ async function runActions(cfg, actions) {
           ok = false;
           result = { error: "No workspace or --no-ai-server" };
         } else {
-          const reserved = new Set();
-          for (const other of cfg.workspaces || []) {
-            if (other.sandboxId !== ws.sandboxId && other.port) {
-              reserved.add(Number(other.port));
-            }
-          }
           const problem = issuesForSandbox(ws.sandboxId)
             .map((issue) => issue.message)
             .join("\n");
@@ -1809,32 +2116,15 @@ async function runActions(cfg, actions) {
               problem ||
               "Local processes are not running or the project setup looks incomplete.",
           });
-          await startAiServerForWorkspace(ws, { reserved, cfg });
-          await sleep(1500);
-          const startedHosts = await ensureHostProcesses(ws, { reserved, cfg });
-          await sleep(800);
-          await inspectHostJobs(ws);
-          const up = await probeUrl(
-            `http://127.0.0.1:${ws.port}/embed-config.js`
-          );
-          if (up) clearProcessProblem(ws.sandboxId, "ai_server_launch", "ai");
-          const processIssues = issuesForSandbox(ws.sandboxId).map(
-            ({ role: _role, ...issue }) => issue
-          );
-          const warning = processIssues[0]?.message || null;
           result = {
-            up,
-            startedHosts,
-            sandboxId: ws.sandboxId,
-            folderPath: ws.folderPath,
-            port: ws.port,
-            appUrl: ws.appUrl,
-            processIssues,
-            warning,
+            ...(await startAppsForWorkspace(ws, cfg)),
             projectInfo,
           };
-          if (processIssues.some((issue) => issue.code === "ai_server_launch")) {
-            result.error = warning;
+          if (
+            Array.isArray(result.processIssues) &&
+            result.processIssues.some((issue) => issue.code === "ai_server_launch")
+          ) {
+            result.error = result.warning;
             ok = false;
           }
         }
@@ -1875,7 +2165,7 @@ async function runActions(cfg, actions) {
         const sandboxId = String(
           action.sandboxId || action.payload?.sandboxId || ""
         );
-        forgetLaunch(sandboxId);
+        await forgetLaunch(sandboxId);
         cfg.workspaces = (cfg.workspaces || []).filter(
           (w) => w.sandboxId !== sandboxId
         );
@@ -1924,6 +2214,7 @@ async function collectWorkspaceStates(cfg) {
       aiServerUp: up,
       startingAi: recentlyLaunched(`${ws.sandboxId}:${folder}:ai`),
       appUrl: ws.appUrl || null,
+      appsRequested: appsWanted(ws),
     });
   }
   return localStates;
@@ -1946,6 +2237,7 @@ async function sendHeartbeat(cfg, folders, localStates) {
         aiServerUp: st.aiServerUp,
         port: st.port,
         appUrl: st.appUrl || undefined,
+        appsRequested: Boolean(st.appsRequested),
       })),
     }
   );
@@ -1969,6 +2261,19 @@ async function buildIssues(cfg, workspaceStates) {
   }
   for (const st of workspaceStates) {
     if (st.aiServerUp || 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.",
+        actionCode: "start_ai_server",
+        sandboxId: st.sandboxId,
+      });
+      continue;
+    }
     const launch = [...processProblems.values()].find(
       (issue) =>
         issue.sandboxId === st.sandboxId && issue.code === "ai_server_launch"
@@ -2105,13 +2410,18 @@ async function main() {
         const up = await probeUrl(
           `http://127.0.0.1:${ws.port}/embed-config.js`
         );
-        if (!cfg.noAiServer && !up) {
+        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");
+          if (up) {
+            clearProcessProblem(ws.sandboxId, "ai_server_launch", "ai");
+            clearProcessProblem(ws.sandboxId, "apps_not_started");
+          }
+        }
+        if (appsWanted(ws)) {
+          await ensureHostProcesses(ws, { reserved, cfg });
         }
-        await ensureHostProcesses(ws, { reserved, cfg });
         await inspectHostJobs(ws);
         localStates.push({
           sandboxId: ws.sandboxId,
@@ -2121,6 +2431,7 @@ async function main() {
           aiServerUp: up,
           startingAi: recentlyLaunched(`${ws.sandboxId}:${folder}:ai`),
           appUrl: ws.appUrl || null,
+          appsRequested: appsWanted(ws),
         });
       }