@elizaos/app-core 2.0.0-beta.3 → 2.0.11-beta.6

package/scripts/dev-platform.mjs

@@ -14,7 +14,7 @@
  *    production builds on every restart are slow; watch mode users get HMR from `vite dev`.
  * 2. **Root bundle** — `tsdown` at repo root if `dist/entry.js` missing (Electrobun eliza-dist).
  * 3. **Long-lived children** (see `launch()`):
- *    - **API** — `bun --watch dev-server` unless `--no-api`.
+ *    - **API** — `bun dev-server` unless `--no-api`; `bun --watch` is opt-in.
  *    - **Watch + default** — Vite **dev** server + `ELIZA_RENDERER_URL` for Electrobun (HMR).
  *      Stale dep chunks: `--vite-force` or `ELIZA_VITE_FORCE=1` / `ELIZA_VITE_FORCE=1` (passes `vite --force`).
  *    - **Watch + Rollup** — `--rollup-watch` or `ELIZA_DESKTOP_VITE_BUILD_WATCH=1` with
@@ -52,7 +52,7 @@
  *   `ELIZA_DESKTOP_SCREENSHOT_SERVER=0`.
  */
 
-import { execSync, spawn } from "node:child_process";
+import { execFileSync, spawn } from "node:child_process";
 import { randomBytes } from "node:crypto";
 import {
   appendFileSync,
@@ -75,13 +75,26 @@ import chalk from "chalk";
 import { allocateFirstFreeLoopbackPort } from "./lib/allocate-loopback-port.mjs";
 import { createApiSupervisor } from "./lib/api-supervisor.mjs";
 import { resolveMainAppDir } from "./lib/app-dir.mjs";
+import { resolveDesktopStartupEmbeddingWarmupPolicy } from "./lib/desktop-startup-embedding-warmup-policy.mjs";
 import { signalSpawnedProcessTree } from "./lib/kill-process-tree.mjs";
 import { killUiListenPort } from "./lib/kill-ui-listen-port.mjs";
 import { extendNodePathEnv } from "./lib/node-path-env.mjs";
 import { formatOrchestratorDesktopDevBanner } from "./lib/orchestrator-desktop-dev-banner.mjs";
 import { appIdentityEnv } from "./lib/read-app-identity.mjs";
+import { resolveRendererBuildAction } from "./lib/renderer-build-action.mjs";
 import { viteRendererBuildNeeded } from "./lib/vite-renderer-dist-stale.mjs";
 
+// Linux WebKitGTK: the dmabuf renderer can emit a benign but noisy
+// "X11 Error: GLXBadWindow (code 168)" at webview creation on common
+// XWayland/GLX driver combos. Apply the documented workaround only to the
+// Electrobun child, before it starts, so Vite/API children do not inherit
+// WebKit-specific renderer policy. An explicit user override still wins.
+const linuxWebkitGtkEnv =
+  process.platform === "linux" &&
+  process.env.WEBKIT_DISABLE_DMABUF_RENDERER === undefined
+    ? { WEBKIT_DISABLE_DMABUF_RENDERER: "1" }
+    : {};
+
 const here = path.dirname(fileURLToPath(import.meta.url));
 // `_elizaRoot` is the eliza repo root itself (3 levels up from
 // scripts/). `elizaRoot` is the *wrapper* repo root (4 levels up) used
@@ -135,18 +148,113 @@ const devServerEntry = isElizaMonorepo
 
 const appDir = resolveRendererAppDir();
 const electrobunDir = resolveElectrobunDir();
-const defaultElizaNamespace =
-  isElizaMonorepo &&
-  path
-    .resolve(appDir)
-    .startsWith(`${path.resolve(elizaRoot, "eliza")}${path.sep}`)
-    ? "eliza"
-    : isElizaMonorepo
-      ? "eliza"
-      : "eliza";
+const appIdentity = appIdentityEnv(appDir);
+const defaultElizaNamespace = appIdentity.ELIZA_NAMESPACE || "eliza";
+const API_PROCESS_SPAWNED_AT_ENV = "ELIZA_API_PROCESS_SPAWNED_AT_MS";
+const PROCESS_SPAWNED_AT_ENV = "ELIZA_PROCESS_SPAWNED_AT_MS";
+
+if (isElizaMonorepo && process.env.ELIZA_SKIP_LOCAL_UPSTREAMS !== "1") {
+  process.env.ELIZA_FORCE_LOCAL_UPSTREAMS ??= "1";
+}
+
+function resolveDevStateDir() {
+  const explicit = process.env.ELIZA_STATE_DIR?.trim();
+  if (explicit)
+    return path.resolve(
+      explicit.replace(/^~(?=$|[\\/])/, process.env.HOME || process.cwd()),
+    );
+  const namespace =
+    process.env.ELIZA_NAMESPACE?.trim() || defaultElizaNamespace;
+  const xdgStateHome = process.env.XDG_STATE_HOME?.trim();
+  const base = xdgStateHome
+    ? path.isAbsolute(xdgStateHome)
+      ? xdgStateHome
+      : path.join(process.env.HOME || process.cwd(), xdgStateHome)
+    : path.join(process.env.HOME || process.cwd(), ".local", "state");
+  return path.join(base, namespace);
+}
 
 const BUN_EXECUTABLE = process.versions?.bun ? process.execPath : "bun";
 
+function resolveElizaPackageDir(packageName) {
+  return isElizaMonorepo
+    ? path.join(elizaRoot, "eliza", "packages", packageName)
+    : path.join(elizaRoot, "packages", packageName);
+}
+
+function buildWorkspacePackageAsync(packageName, packageDir) {
+  console.log(`[eliza] Building ${packageName} for desktop startup...`);
+  return new Promise((resolve, reject) => {
+    const child = spawn(BUN_EXECUTABLE, ["run", "build"], {
+      cwd: packageDir,
+      env: { ...process.env },
+      stdio: "inherit",
+    });
+    child.on("error", reject);
+    child.on("exit", (code) =>
+      code === 0
+        ? resolve()
+        : reject(new Error(`${packageName} build exited with code ${code}`)),
+    );
+  });
+}
+
+// These three runtime packages have no build interdependency among themselves,
+// so any that are missing their dist entry are built concurrently rather than
+// in series. Each existing dist is skipped (fast path), so a warm tree returns
+// immediately with no spawned processes.
+async function ensureDesktopRuntimePackagesBuilt() {
+  const targets = [
+    ["@elizaos/security", resolveElizaPackageDir("security")],
+    [
+      "@elizaos/plugin-remote-manifest",
+      resolveElizaPackageDir("plugin-remote-manifest"),
+    ],
+    [
+      "@elizaos/plugin-worker-runtime",
+      resolveElizaPackageDir("plugin-worker-runtime"),
+    ],
+  ];
+  const stale = [];
+  for (const [name, dir] of targets) {
+    if (!existsSync(path.join(dir, "package.json"))) {
+      throw new Error(`Missing ${name} package at ${dir}`);
+    }
+    if (!existsSync(path.join(dir, "dist/index.js"))) stale.push([name, dir]);
+  }
+  await Promise.all(
+    stale.map(([name, dir]) => buildWorkspacePackageAsync(name, dir)),
+  );
+}
+
+function syncRendererPublicAssets() {
+  const syncScript = path.join(
+    bundleRoot,
+    isElizaMonorepo
+      ? "eliza/packages/shared/scripts/sync-to-public.mjs"
+      : "packages/shared/scripts/sync-to-public.mjs",
+  );
+  if (!existsSync(syncScript)) {
+    return;
+  }
+  execFileSync(
+    process.execPath,
+    [
+      syncScript,
+      path.join(appDir, "public"),
+      "--logos",
+      "--favicons",
+      "--concepts",
+      "--banners",
+      "--background",
+      "--background-videos",
+    ],
+    {
+      stdio: "inherit",
+    },
+  );
+}
+
 // Load worktree-specific env overrides (ports, state dir) before anything reads process.env.
 // Generated by: bash scripts/worktree-env.sh <slot>
 const _worktreeEnvPath = path.join(bundleRoot, ".env.worktree");
@@ -178,10 +286,10 @@ Environment (CI / automation; flags override where noted):
   ELIZA_VITE_FORCE=1 / ELIZA_VITE_FORCE=1   Same as --vite-force
   ELIZA_DESKTOP_SCREENSHOT_SERVER=0     Disable screenshot dev server
   ELIZA_DESKTOP_DEV_LOG=0               Disable aggregated log file
-  ELIZA_DESKTOP_API_WATCH=0             Disable bun --watch for the API server
+  ELIZA_DESKTOP_API_WATCH=1             Enable bun --watch for the API server
   ELIZA_DESKTOP_PREWARM=0               Disable desktop startup API prewarming
   ELIZA_DESKTOP_PREWARM_BLOCKING=1      Wait for API prewarming before Electrobun launch
-  ELIZA_API_PORT / ELIZA_API_PORT / ELIZA_PORT   API port (first non-empty wins)
+  ELIZA_API_PORT / ELIZA_PORT                    API port (first non-empty wins)
   ELIZA_PORT                            UI port (Vite dev)
 
 Docs: docs/apps/desktop-local-development.md
@@ -189,15 +297,32 @@ Docs: docs/apps/desktop-local-development.md
   process.exit(0);
 }
 
+// The Electrobun platform package is compiled from the workspace checkout. Its
+// directory can exist (e.g. an empty placeholder) without a package.json when
+// the @elizaos/* workspace packages aren't linked, in which case `bun run dev`
+// there would fail opaquely. Fail fast with an actionable message instead, and
+// before the expensive renderer build below.
+if (!existsSync(path.join(electrobunDir, "package.json"))) {
+  console.error(
+    `[eliza] Desktop dev requires the Electrobun platform package on disk, but ` +
+      `none was found at ${path.join(electrobunDir, "package.json")}.\n` +
+      `  Run dev:desktop from a workspace checkout where the @elizaos/* packages ` +
+      `are present and linked.`,
+  );
+  process.exit(1);
+}
+
 const skipApi = process.argv.includes("--no-api");
 const forceRendererCli = process.argv.includes("--force-renderer");
 const forceRenderer =
   forceRendererCli ||
   process.env.ELIZA_DESKTOP_RENDERER_BUILD === "always" ||
   process.env.ELIZA_DESKTOP_RENDERER_BUILD === "1";
-const viteWatch =
-  process.env.ELIZA_DESKTOP_VITE_WATCH === "1" ||
-  process.env.ELIZA_DESKTOP_VITE_WATCH === "1";
+// Opt-in fast inner loop: start against the EXISTING dist even when stale
+// (renderer may be stale until the next build). Prefer dev:desktop:watch (HMR).
+const rendererBuildSkipRequested =
+  process.env.ELIZA_DESKTOP_RENDERER_BUILD === "skip";
+const viteWatch = process.env.ELIZA_DESKTOP_VITE_WATCH === "1";
 const viteDepForceCli = process.argv.includes("--vite-force");
 const viteDepForce =
   viteDepForceCli ||
@@ -237,7 +362,7 @@ const desktopDevLogOptOut = (() => {
 })();
 const desktopDevLogPath = desktopDevLogOptOut
   ? null
-  : path.resolve(bundleRoot, ".eliza", "desktop-dev-console.log");
+  : path.join(resolveDevStateDir(), "desktop-dev-console.log");
 const desktopCefWorkaroundEnv = (() => {
   if (process.platform !== "darwin") {
     return null;
@@ -262,11 +387,6 @@ const desktopUnsafeDevtoolsEnv = (() => {
 
   return "1";
 })();
-const desktopWhisperOptOut = (() => {
-  const v = process.env.ELIZA_DESKTOP_ENSURE_WHISPER?.trim().toLowerCase();
-  return v === "0" || v === "false" || v === "no" || v === "off";
-})();
-
 function ensureBunRootPackageLink(packageName) {
   const rootNodeModules = path.join(bundleRoot, "node_modules");
   const packageLink = path.join(rootNodeModules, packageName);
@@ -307,58 +427,37 @@ function ensureBunRootPackageLink(packageName) {
   }
 }
 
-function desktopWhisperAssetsMissing() {
-  if (process.platform === "win32") {
-    return false;
-  }
-  const whisperCppDir = path.join(
-    bundleRoot,
-    "node_modules",
-    "whisper-node",
-    "lib",
-    "whisper.cpp",
-  );
-  const whisperBin = path.join(whisperCppDir, "main");
-  const whisperModel = path.join(whisperCppDir, "models", "ggml-base.en.bin");
-  return !existsSync(whisperBin) || !existsSync(whisperModel);
-}
-
-function ensureDesktopWhisperAssets() {
-  if (desktopWhisperOptOut || process.platform === "win32") {
-    return;
-  }
-  if (!desktopWhisperAssetsMissing()) {
-    return;
-  }
-
-  console.log(
-    "\n[eliza] Desktop voice input needs whisper.cpp assets — building them once for Electrobun dev…\n",
-  );
-  try {
-    execSync("bun run build:whisper", {
-      cwd: electrobunDir,
-      stdio: "inherit",
-    });
-  } catch (_error) {
-    console.warn(
-      "[eliza] Warning: failed to build whisper.cpp for desktop voice input. " +
-        "Electrobun mic/STT may stay unavailable until this succeeds.",
-    );
-    console.warn(
-      "[eliza] Retry manually with: (cd <renderer-app>/electrobun && bun run build:whisper)",
-    );
-  }
-}
-
+syncRendererPublicAssets();
 const rendererDistStale = viteRendererBuildNeeded(appDir, bundleRoot);
-const needRendererBuild = forceRenderer || rendererDistStale;
+const rendererDistExists = existsSync(path.join(appDir, "dist", "index.html"));
+const rendererBuildAction = resolveRendererBuildAction({
+  forceRenderer,
+  distStale: rendererDistStale,
+  distExists: rendererDistExists,
+  skipRequested: rendererBuildSkipRequested,
+});
 let ranInitialViteBuild = false;
 
-if (needRendererBuild) {
+if (rendererBuildAction === "build") {
   ranInitialViteBuild = true;
   console.log("\n[eliza] Building renderer (vite build)…");
-  execSync("bun run vite build", { cwd: appDir, stdio: "inherit" });
+  console.log(
+    chalk.dim(
+      "  Tip: `bun dev:desktop:watch` uses Vite HMR and skips this build.",
+    ),
+  );
+  execFileSync(BUN_EXECUTABLE, ["--bun", "run", "vite", "build"], {
+    cwd: appDir,
+    env: { ...process.env },
+    stdio: "inherit",
+  });
   console.log("[eliza] Renderer ready.\n");
+} else if (rendererBuildAction === "skip-stale") {
+  console.warn(
+    "\n[eliza] Skipping STALE vite build (ELIZA_DESKTOP_RENDERER_BUILD=skip) —\n" +
+      "  the renderer may be out of date. Use `bun dev:desktop:watch` for HMR,\n" +
+      "  or `--force-renderer` to rebuild now.\n",
+  );
 } else {
   console.log(
     "\n[eliza] Skipping vite build — renderer dist/ is up to date.\n" +
@@ -393,7 +492,7 @@ export * from ${JSON.stringify(entryTs)};
 }
 
 ensureBunRootPackageLink("jsdom");
-ensureDesktopWhisperAssets();
+await ensureDesktopRuntimePackagesBuilt();
 
 async function allocateDistinctLoopbackPort(preferredPort, reservedPorts) {
   let candidate = preferredPort;
@@ -695,6 +794,9 @@ async function launch() {
   }
 
   const serviceLine = namesForLog.join(", ");
+  const apiEmbeddingWarmupPolicy = resolveDesktopStartupEmbeddingWarmupPolicy(
+    process.env,
+  );
   const orchestratorBanner = formatOrchestratorDesktopDevBanner({
     worktreePath: _worktreeEnvPath,
     worktreeLoaded: existsSync(_worktreeEnvPath),
@@ -722,6 +824,7 @@ async function launch() {
     desktopDevLogPath,
     desktopDevLogOptOut,
     childrenList: serviceLine,
+    apiEmbeddingWarmupPolicy,
     elizaNamespace:
       process.env.ELIZA_NAMESPACE?.trim() || defaultElizaNamespace,
     elizaNamespaceUnset: !process.env.ELIZA_NAMESPACE?.trim(),
@@ -756,6 +859,12 @@ async function launch() {
     NODE_ENV: "development",
     ELIZA_API_PORT: apiPort,
     ELIZA_HEADLESS: "1",
+    // Defer the post-ready boot tail (app-route plugins, training hooks,
+    // sensitive-request adapters, trigger bridge, connector catalog, voice
+    // warmup) so /api/health flips ready:true and the UI reaches first paint
+    // before they finish. Brief feature-route 404 window after "ready" is the
+    // trade-off; acceptable for dev/desktop. Explicit env always wins.
+    ELIZA_DEFER_APP_ROUTES: process.env.ELIZA_DEFER_APP_ROUTES?.trim() || "1",
     ELIZA_PORT: String(uiDevPort),
     ELIZA_UI_PORT: String(uiDevPort),
     ELIZA_NAMESPACE: process.env.ELIZA_NAMESPACE ?? defaultElizaNamespace,
@@ -765,28 +874,37 @@ async function launch() {
     ...(desktopDevLogPath
       ? { ELIZA_DESKTOP_DEV_LOG_PATH: desktopDevLogPath }
       : {}),
+    ...apiEmbeddingWarmupPolicy.env,
   };
-  const apiWatchEnabled = !envFlagDisabled("ELIZA_DESKTOP_API_WATCH");
+  const apiWatchEnabled = envFlagEnabled("ELIZA_DESKTOP_API_WATCH");
   const apiArgs = apiWatchEnabled
     ? ["--watch", devServerEntry]
     : [devServerEntry];
   if (!apiWatchEnabled) {
     console.log(
-      "[eliza] API file watcher disabled (ELIZA_DESKTOP_API_WATCH=0).",
+      "[eliza] API file watcher disabled (set ELIZA_DESKTOP_API_WATCH=1 to enable).",
     );
   }
 
   const apiSupervisor = createApiSupervisor({
-    spawnChild: () =>
-      spawn(BUN_EXECUTABLE, apiArgs, {
+    spawnChild: () => {
+      const apiProcessSpawnedAtMs = String(Date.now());
+      return spawn(BUN_EXECUTABLE, apiArgs, {
         cwd: bundleRoot,
         env: extendNodePathEnv(
-          { ...process.env, ...apiEnv, FORCE_COLOR: "1" },
+          {
+            ...process.env,
+            ...apiEnv,
+            [API_PROCESS_SPAWNED_AT_ENV]: apiProcessSpawnedAtMs,
+            [PROCESS_SPAWNED_AT_ENV]: apiProcessSpawnedAtMs,
+            FORCE_COLOR: "1",
+          },
           bundleRoot,
         ),
         stdio: ["ignore", "pipe", "pipe"],
         ...(process.platform !== "win32" ? { detached: true } : {}),
-      }),
+      });
+    },
     onSpawn: (child) => {
       if (child.stdout) prefixStream("api", child.stdout);
       if (child.stderr) prefixStream("api", child.stderr);
@@ -850,7 +968,9 @@ async function launch() {
     pushChild(
       "vite",
       "bun",
-      viteDepForce ? ["run", "vite", "--", "--force"] : ["run", "vite"],
+      viteDepForce
+        ? ["--bun", "run", "vite", "--", "--force"]
+        : ["--bun", "run", "vite"],
       appDir,
       {
         NODE_ENV: "development",
@@ -866,35 +986,159 @@ async function launch() {
   }
 
   if (viteRollupWatch) {
-    pushChild("vite", "bun", ["run", "vite", "build", "--watch"], appDir, {
-      ELIZA_DESKTOP_VITE_FAST_DIST: "1",
-    });
+    pushChild(
+      "vite",
+      "bun",
+      ["--bun", "run", "vite", "build", "--watch"],
+      appDir,
+      {
+        ELIZA_DESKTOP_VITE_FAST_DIST: "1",
+      },
+    );
   }
 
-  pushChild("electrobun", "bun", ["run", "dev"], electrobunDir, {
-    NODE_ENV: "development",
-    ELECTROBUN_SKIP_CODESIGN: "1",
-    ...appIdentityEnv(appDir),
-    ...(desktopCefWorkaroundEnv
-      ? { ELIZA_DESKTOP_FORCE_CEF: desktopCefWorkaroundEnv }
-      : {}),
-    ...(desktopUnsafeDevtoolsEnv
-      ? {
-          ELIZA_ALLOW_UNSAFE_NATIVE_DEVTOOLS: desktopUnsafeDevtoolsEnv,
+  const electrobunChild = pushChild(
+    "electrobun",
+    "bun",
+    ["run", "dev"],
+    electrobunDir,
+    {
+      NODE_ENV: "development",
+      ELECTROBUN_SKIP_CODESIGN: "1",
+      ELIZA_ELECTROBUN_REPO_ROOT: bundleRoot,
+      ...appIdentity,
+      ...(desktopCefWorkaroundEnv
+        ? { ELIZA_DESKTOP_FORCE_CEF: desktopCefWorkaroundEnv }
+        : {}),
+      ...(desktopUnsafeDevtoolsEnv
+        ? {
+            ELIZA_ALLOW_UNSAFE_NATIVE_DEVTOOLS: desktopUnsafeDevtoolsEnv,
+          }
+        : {}),
+      ...linuxWebkitGtkEnv,
+      ...(rendererUrlForShell
+        ? { ELIZA_RENDERER_URL: rendererUrlForShell }
+        : {}),
+      ...(skipApi
+        ? { ELIZA_DESKTOP_SKIP_EMBEDDED_AGENT: "1" }
+        : {
+            ELIZA_API_PORT: apiPort,
+            ELIZA_UI_PORT: String(uiDevPort),
+            ELIZA_NAMESPACE:
+              process.env.ELIZA_NAMESPACE ?? defaultElizaNamespace,
+            ELIZA_DESKTOP_API_BASE: `http://127.0.0.1:${apiPort}`,
+          }),
+      ELIZA_BROWSER_WORKSPACE_PORT: String(browserWorkspacePort),
+      ...screenshotEnvElectrobun,
+    },
+  );
+
+  // macOS-only safety net: on some setups, `bunx electrobun dev` finishes
+  // building (copying the WGPU library, packaging app/bun/index.js into the
+  // bundle, etc.) but the native launcher it forks never registers a window
+  // because it was started via POSIX fork-exec instead of LaunchServices.
+  // Symptom: electrobun child stays alive, no `.app` window appears, the
+  // screenshot server port never starts listening.
+  //
+  // The fix is to also `open` the .app explicitly — LaunchServices then
+  // registers it as a GUI app with window-creation rights. If electrobun
+  // already launched it, `open` is a no-op (LaunchServices won't
+  // double-launch a registered bundle).
+  //
+  // **Crucially**, we wait until electrobun's build phase is _done_ before
+  // opening — otherwise the running app would hold files in the bundle and
+  // electrobun's bun-bundler would fail with PermissionDenied trying to write
+  // app/bun/index.js. We watch for the screenshot server port (preferred
+  // signal, only set after electrobun launches the launcher) and use a
+  // bundle-mtime stability check as a fallback. Honors
+  // `ELIZA_DESKTOP_AUTO_OPEN=0` to opt out.
+  if (
+    process.platform === "darwin" &&
+    process.env.ELIZA_DESKTOP_AUTO_OPEN !== "0"
+  ) {
+    let scheduledOpen = false;
+    const resolveDevMacAppPath = () => {
+      const arch = process.arch === "arm64" ? "arm64" : "x86_64";
+      const buildDir = path.join(electrobunDir, "build", `dev-macos-${arch}`);
+      if (!existsSync(buildDir)) return null;
+      try {
+        const entries = readdirSync(buildDir);
+        const appBundle = entries.find((e) => e.endsWith(".app"));
+        return appBundle ? path.join(buildDir, appBundle) : null;
+      } catch {
+        return null;
+      }
+    };
+    const triggerOpen = (reason) => {
+      if (scheduledOpen) return;
+      scheduledOpen = true;
+      const macAppPath = resolveDevMacAppPath();
+      if (!macAppPath) {
+        console.log(
+          "[eliza] LaunchServices auto-open skipped — no .app bundle found in dev build dir",
+        );
+        return;
+      }
+      try {
+        const opener = spawn("open", [macAppPath], {
+          stdio: "ignore",
+          detached: true,
+        });
+        opener.unref();
+        opener.on("error", (err) => {
+          console.log(
+            `[eliza] LaunchServices auto-open failed: ${err.message}`,
+          );
+        });
+        console.log(
+          `[eliza] LaunchServices auto-open (${reason}): open ${path.basename(macAppPath)}`,
+        );
+      } catch (err) {
+        console.log(
+          `[eliza] LaunchServices auto-open threw: ${err instanceof Error ? err.message : String(err)}`,
+        );
+      }
+    };
+
+    // Watch for the screenshot server port — if it comes up on its own, the
+    // electrobun launcher launched the app properly and we don't need to.
+    // If it doesn't come up within the deadline, fall back to `open`.
+    const screenshotPortStr =
+      screenshotEnvElectrobun.ELIZA_SCREENSHOT_SERVER_PORT;
+    const fallbackDeadlineMs = 45000;
+    const startedAt = Date.now();
+    const checkAndFallback = async () => {
+      if (scheduledOpen) return;
+      if (!electrobunChild || electrobunChild.exitCode != null) return;
+      const port = screenshotPortStr ? Number(screenshotPortStr) : 0;
+      if (port > 0) {
+        try {
+          // Try to connect — if it succeeds, the launcher's screenshot
+          // server is listening and the app is up. Done.
+          await new Promise((resolve, reject) => {
+            const sock = createConnection({ host: "127.0.0.1", port }, () => {
+              sock.end();
+              resolve();
+            });
+            sock.on("error", reject);
+            sock.setTimeout(500, () => {
+              sock.destroy();
+              reject(new Error("timeout"));
+            });
+          });
+          return; // screenshot server is up, nothing to do
+        } catch {
+          // not listening yet — keep waiting unless past deadline
         }
-      : {}),
-    ...(rendererUrlForShell ? { ELIZA_RENDERER_URL: rendererUrlForShell } : {}),
-    ...(skipApi
-      ? {}
-      : {
-          ELIZA_API_PORT: apiPort,
-          ELIZA_UI_PORT: String(uiDevPort),
-          ELIZA_NAMESPACE: process.env.ELIZA_NAMESPACE ?? defaultElizaNamespace,
-          ELIZA_DESKTOP_API_BASE: `http://127.0.0.1:${apiPort}`,
-        }),
-    ELIZA_BROWSER_WORKSPACE_PORT: String(browserWorkspacePort),
-    ...screenshotEnvElectrobun,
-  });
+      }
+      if (Date.now() - startedAt >= fallbackDeadlineMs) {
+        triggerOpen("fallback after 45s with no screenshot server");
+        return;
+      }
+      setTimeout(checkAndFallback, 3000);
+    };
+    setTimeout(checkAndFallback, 8000);
+  }
 }
 
 /**