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

package/scripts/dev-ui.mjs

@@ -1,12 +1,12 @@
 #!/usr/bin/env node
-console.error("[dev-ui LOCAL PATCH START] running patched local dev-ui.mjs");
+
 /**
  * Development script that starts:
  * 1. The Eliza dev server (\[(eliza|eliza)(?:-api)?\]|runtime + API on port 31337) with restart support
  * 2. The vite app dev server (port 2138, proxies /api and /ws to 31337)
  *
  * Automatically kills zombie processes on both ports before starting.
- * Waits for the API server to be ready before launching vite so the proxy
+ * Waits for the API port to be open before launching vite so the proxy
  * doesn't flood the terminal with ECONNREFUSED errors.
  *
  * Usage:
@@ -14,18 +14,16 @@ console.error("[dev-ui LOCAL PATCH START] running patched local dev-ui.mjs");
  *   node packages/app-core/scripts/dev-ui.mjs                  # from eliza repo root — same
  *   node …/dev-ui.mjs --ui-only                                # Vite only (API assumed running)
  */
-import { execFileSync, execSync, spawn } from "node:child_process";
-import { existsSync, readFileSync, realpathSync } from "node:fs";
+import { execSync, spawn } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, realpathSync } from "node:fs";
 import { createConnection } from "node:net";
 import os from "node:os";
 import path from "node:path";
 import process from "node:process";
 import { fileURLToPath, pathToFileURL } from "node:url";
-import {
-  resolveDesktopApiPort,
-  resolveDesktopUiPort,
-} from "@elizaos/shared";
+import { resolveDesktopApiPort, resolveDesktopUiPort } from "@elizaos/shared";
 import * as JSON5Module from "json5";
+import { startAgentSourceWatcher } from "./lib/agent-source-watcher.mjs";
 import { createApiSupervisor } from "./lib/api-supervisor.mjs";
 import { relativeAppDir, resolveMainAppDir } from "./lib/app-dir.mjs";
 import { getBunVersionAdvisory } from "./lib/bun-version-guard.mjs";
@@ -35,6 +33,10 @@ import { buildVisionDepsFailureMessage } from "./lib/dev-ui-vision.mjs";
 import { signalSpawnedProcessTree } from "./lib/kill-process-tree.mjs";
 import { extendNodePathEnv } from "./lib/node-path-env.mjs";
 import { syncElizaEnvAliases } from "./lib/sync-eliza-env-aliases.mjs";
+import {
+  chooseElizaRuntime,
+  resolveNodeExecPathFromCandidates,
+} from "./run-node-runtime.mjs";
 
 // Load worktree-specific env overrides (ports, state dir) before port resolution.
 // Generated by: bash scripts/worktree-env.sh <slot>
@@ -132,9 +134,6 @@ function resolveDevServerEntryRelativePath(devCwd) {
   const packagedAppCoreEntry = path.resolve(
     path.dirname(fileURLToPath(import.meta.url)),
     "..",
-    "packages",
-    "app-core",
-    "src",
     "runtime",
     "dev-server.js",
   );
@@ -203,6 +202,8 @@ function getCliName() {
 
 const cliName = getCliName();
 const logPrefix = `[${cliName}]`;
+const API_PROCESS_SPAWNED_AT_ENV = "ELIZA_API_PROCESS_SPAWNED_AT_MS";
+const PROCESS_SPAWNED_AT_ENV = "ELIZA_PROCESS_SPAWNED_AT_MS";
 
 const bunAdvisory = getBunVersionAdvisory();
 if (bunAdvisory) console.warn(`${logPrefix} ${bunAdvisory}`);
@@ -217,12 +218,18 @@ const devLogLevel =
     .toLowerCase() || "info";
 const quietApiLogs = process.env.ELIZA_DEV_QUIET_LOGS === "1";
 const verboseApiLogs = process.env.ELIZA_DEV_VERBOSE_LOGS !== "0";
-// Keep `bun --watch` opt-in for the API server. Concurrent package builds,
-// native plugin builds, and staged plugin copies rewrite workspace `dist/`
-// files; Bun follows imports into those files and can hot-reload while the
-// runtime is still bootstrapping, leaving PGlite locked by the previous
-// process. The supervisor still restarts the API on explicit restart exits.
-const skipBunWatch = process.env.ELIZA_DEV_NO_WATCH !== "0";
+// Agent hot-reload is ON by default: a source-only watcher (see
+// startAgentSourceWatcher) bounces the API child through the supervisor when
+// backend `*/src` changes. Unlike the old `node --watch`, it never watches
+// `dist/`, so concurrent package builds can't trigger a reload loop — which is
+// why this no longer needs the opt-in / concurrent-build auto-disable dance.
+// Opt out with ELIZA_DEV_NO_WATCH=1.
+const skipSourceWatch = process.env.ELIZA_DEV_NO_WATCH === "1";
+// More distinct source files than this changing in one debounce window is a
+// git reset / checkout / build (churn), not a hand edit — skip the reload.
+// Override with ELIZA_DEV_HOT_RELOAD_BULK_LIMIT.
+const HOT_RELOAD_BULK_CHANGE_LIMIT =
+  Number(process.env.ELIZA_DEV_HOT_RELOAD_BULK_LIMIT) || 4;
 const DEV_TEST_MOCK_ENV_KEYS = [
   "ELIZA_MOCK_GOOGLE_BASE",
   "ELIZA_MOCK_TWILIO_BASE",
@@ -260,6 +267,70 @@ function shellQuoteArg(value) {
   return /^[A-Za-z0-9_./:=+-]+$/.test(value) ? value : JSON.stringify(value);
 }
 
+function appendNodeOption(value, option) {
+  const current = value?.trim();
+  if (!current) return option;
+  if (current.split(/\s+/).includes(option)) return current;
+  return `${current} ${option}`;
+}
+
+function resolveApiRuntimeCommand(env) {
+  const requestedRuntime = env.ELIZA_RUNTIME?.trim().toLowerCase();
+  const { runtime, warning } = chooseElizaRuntime({
+    requestedRuntime,
+    platform: process.platform,
+    bunVersion: process.versions?.bun,
+    hasBun,
+    hasNode,
+  });
+  if (warning) {
+    console.warn(
+      `${logPrefix} ${warning} Set ELIZA_RUNTIME=bun to force Bun runtime.`,
+    );
+  }
+  if (runtime === "bun") {
+    if (!hasBun) {
+      throw new Error(
+        requestedRuntime === "bun"
+          ? "ELIZA_RUNTIME=bun was requested, but bun/bunx was not found in PATH."
+          : "Bun runtime was selected, but bun/bunx was not found in PATH.",
+      );
+    }
+    return { runtime: "bun", command: which("bun") ?? "bun" };
+  }
+
+  if (!hasNode) {
+    throw new Error(
+      requestedRuntime === "node"
+        ? "ELIZA_RUNTIME=node was requested, but Node.js was not found in PATH."
+        : "Node.js was selected for the API runtime, but Node.js was not found in PATH.",
+    );
+  }
+
+  const pathCandidates = (env.PATH ?? "")
+    .split(path.delimiter)
+    .filter(Boolean)
+    .map((dir) =>
+      path.join(dir, process.platform === "win32" ? "node.exe" : "node"),
+    );
+  const candidates = [
+    env.ELIZA_NODE_PATH,
+    env.npm_node_execpath,
+    ...pathCandidates,
+    "/opt/homebrew/bin/node",
+    "/usr/local/bin/node",
+    "/usr/bin/node",
+  ].filter(Boolean);
+  return {
+    runtime: "node",
+    command: resolveNodeExecPathFromCandidates({
+      candidates,
+      explicitNodePath: env.ELIZA_NODE_PATH,
+      platform: process.platform,
+    }),
+  };
+}
+
 const visionDepsRetryCommand = [
   "node",
   path.relative(cwd, visionDepsScriptPath) || visionDepsScriptPath,
@@ -328,6 +399,7 @@ function which(cmd) {
 }
 
 const forceNodeRuntime = process.env.ELIZA_FORCE_NODE === "1";
+const hasNode = !!which("node");
 const hasBun = !forceNodeRuntime && !!which("bun") && !!which("bunx");
 
 if (!hasBun && !which("npx")) {
@@ -345,49 +417,30 @@ if (!hasBun && !which("npx")) {
 // coerceBoolean — imported from ./lib/dev-ui-onchain.mjs
 
 function resolveElizaStateDir() {
-  const brandedStateDir = process.env.ELIZA_STATE_DIR?.trim();
-  if (brandedStateDir) {
-    return path.resolve(brandedStateDir);
-  }
+  const explicitStateDir = process.env.ELIZA_STATE_DIR?.trim();
+  if (explicitStateDir) return path.resolve(explicitStateDir);
 
-  const upstreamStateDir = process.env.ELIZA_STATE_DIR?.trim();
-  if (upstreamStateDir) {
-    return path.resolve(upstreamStateDir);
-  }
+  const xdgStateHome = process.env.XDG_STATE_HOME?.trim();
+  const stateHome = xdgStateHome
+    ? path.isAbsolute(xdgStateHome)
+      ? xdgStateHome
+      : path.join(os.homedir(), xdgStateHome)
+    : path.join(os.homedir(), ".local", "state");
 
-  const brandedDefault = path.join(os.homedir(), ".eliza");
-  if (existsSync(brandedDefault)) {
-    return brandedDefault;
-  }
+  return path.join(stateHome, resolveElizaNamespace());
+}
 
-  return path.join(os.homedir(), ".eliza");
+function resolveElizaNamespace() {
+  return process.env.ELIZA_NAMESPACE?.trim() || cliName || "eliza";
 }
 
 function resolveElizaConfigPath() {
-  const explicitConfigPath =
-    process.env.ELIZA_CONFIG_PATH?.trim() ||
-    process.env.ELIZA_CONFIG_PATH?.trim();
+  const explicitConfigPath = process.env.ELIZA_CONFIG_PATH?.trim();
   if (explicitConfigPath) {
     return path.resolve(explicitConfigPath);
   }
 
-  const brandedStateDir = process.env.ELIZA_STATE_DIR?.trim();
-  if (brandedStateDir) {
-    return path.join(path.resolve(brandedStateDir), "eliza.json");
-  }
-
-  const upstreamStateDir = process.env.ELIZA_STATE_DIR?.trim();
-  if (upstreamStateDir) {
-    return path.join(path.resolve(upstreamStateDir), "eliza.json");
-  }
-
-  const brandedDefault = path.join(os.homedir(), ".eliza", "eliza.json");
-  if (existsSync(brandedDefault)) {
-    return brandedDefault;
-  }
-
-  // Keep the legacy Eliza path as a fallback for older local dev setups.
-  return path.join(os.homedir(), ".eliza", "eliza.json");
+  return path.join(resolveElizaStateDir(), `${resolveElizaNamespace()}.json`);
 }
 
 function loadElizaConfigForDev() {
@@ -426,7 +479,7 @@ function readPluginStealthFlag(entries, ids) {
   return null;
 }
 
-function formatRelativeImportPath(relativePath) {
+function _formatRelativeImportPath(relativePath) {
   const normalized = relativePath.split(path.sep).join("/");
   return normalized.startsWith("./") ? normalized : `./${normalized}`;
 }
@@ -438,7 +491,7 @@ function resolveStealthImportPath(devCwd, candidatePaths) {
       // Return the absolute path so the value stays valid regardless of
       // which cwd the API child gets spawned in. The API child is anchored
       // at the eliza/ submodule (see apiSpawnCwd below), so a path computed
-      // relative to the outer milady cwd would resolve to a non-existent
+      // relative to the outer eliza cwd would resolve to a non-existent
       // `eliza/eliza/...` from the child's perspective.
       return absPath;
     }
@@ -601,43 +654,6 @@ function createStartupFilter(dest) {
   };
 }
 
-// ---------------------------------------------------------------------------
-// Concurrent build detection — bun --watch follows imports into workspace
-// `dist/` files. If a turbo/tsup/tsc build is rewriting those files, --watch
-// hot-reloads on every write and prevents the agent from finishing
-// initialization. We detect that case here and auto-disable --watch.
-// ---------------------------------------------------------------------------
-
-function detectConcurrentBuilds() {
-  if (process.platform === "win32") return null;
-  let psOut;
-  try {
-    psOut = execSync("ps axo pid=,command=", {
-      encoding: "utf8",
-      maxBuffer: 10 * 1024 * 1024,
-      stdio: ["pipe", "pipe", "ignore"],
-    });
-  } catch {
-    return null;
-  }
-  const buildSignatures = [
-    /\bturbo\s+run\s+build\b/i,
-    /\bbun\s+run\s+build\b/i,
-    /\btsup\b.*\bbuild\b/i,
-    /\btsc\b.*\b(--noEmit|tsconfig\.build)\b/i,
-  ];
-  for (const line of psOut.split("\n")) {
-    const trimmed = line.trim();
-    if (!trimmed) continue;
-    if (buildSignatures.some((re) => re.test(trimmed))) {
-      const sp = trimmed.indexOf(" ");
-      const pidStr = sp > 0 ? trimmed.slice(0, sp).trim() : trimmed;
-      return Number.parseInt(pidStr, 10) || null;
-    }
-  }
-  return null;
-}
-
 // ---------------------------------------------------------------------------
 // Port cleanup — force-kill zombie processes on our dev ports
 // ---------------------------------------------------------------------------
@@ -711,15 +727,31 @@ function waitForPort(port, { timeout = 300_000, interval = 500 } = {}) {
   });
 }
 
+function isPortListening(port) {
+  return new Promise((resolve) => {
+    const socket = createConnection({ port, host: "127.0.0.1" });
+    let settled = false;
+    const done = (value) => {
+      if (settled) return;
+      settled = true;
+      socket.destroy();
+      resolve(value);
+    };
+    socket.once("connect", () => done(true));
+    socket.once("error", () => done(false));
+    socket.setTimeout(2000, () => done(false));
+  });
+}
+
 // ---------------------------------------------------------------------------
 // Wait for the agent runtime to be ready (not just the TCP port).
 // Polls GET /api/health and resolves when { ready: true }.
-// Handles bun --watch restarts gracefully (connection resets → retry).
+// Handles supervised hot-reload restarts gracefully (connection resets → retry).
 // ---------------------------------------------------------------------------
 
 async function waitForAgentReady(
   port,
-  { timeout = 300_000, interval = 1000 } = {},
+  { timeout = 300_000, interval = 400 } = {},
 ) {
   const deadline = Date.now() + timeout;
   const url = `http://127.0.0.1:${port}/api/health`;
@@ -742,6 +774,23 @@ async function waitForAgentReady(
   );
 }
 
+// Single quick health probe — true only when the agent reports ready. Used to
+// gate hot-reload restarts so the watcher only ever bounces a HEALTHY agent,
+// never one that is still booting (a booting agent already picks up the latest
+// source, and killing it mid-boot would loop).
+async function isAgentReadyNow(port) {
+  try {
+    const resp = await fetch(`http://127.0.0.1:${port}/api/health`, {
+      signal: AbortSignal.timeout(1500),
+    });
+    if (!resp.ok) return false;
+    const body = await resp.json().catch(() => null);
+    return body?.ready === true;
+  } catch {
+    return false;
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Orphan cleanup (startup only) — never kills arbitrary Bun; PID/name-wide pkill is avoided.
 // Only processes whose command line ties them to this repo or Eliza workspace dirs.
@@ -815,15 +864,29 @@ function killOrphanedWorkspaceProcesses() {
 killOrphanedWorkspaceProcesses();
 killPort(UI_PORT);
 
-// Ensure vision dependencies are installed
-try {
-  execFileSync("node", [visionDepsScriptPath, `--name=${cliName}`], {
-    stdio: "inherit",
-  });
-} catch (error) {
+// Ensure vision dependencies are installed (non-blocking — just probes/installs
+// an optional camera binary; nothing in the boot path depends on its result, so
+// it must not gate API/Vite startup).
+const visionDepsChild = spawn(
+  "node",
+  [visionDepsScriptPath, `--name=${cliName}`],
+  { stdio: "inherit" },
+);
+visionDepsChild.on("error", (error) => {
   process.env.ELIZA_VISION_DEPS_STATUS = "degraded";
   console.warn(buildVisionDepsFailureMessage(error, visionDepsRetryCommand));
-}
+});
+visionDepsChild.on("exit", (code) => {
+  if (code !== 0) {
+    process.env.ELIZA_VISION_DEPS_STATUS = "degraded";
+    console.warn(
+      buildVisionDepsFailureMessage(
+        new Error(`vision deps check exited with code ${code}`),
+        visionDepsRetryCommand,
+      ),
+    );
+  }
+});
 
 if (!uiOnly) {
   killPort(API_PORT);
@@ -831,10 +894,20 @@ if (!uiOnly) {
 
 let apiProcess = null;
 let viteProcess = null;
+/** @type {{ count: number, close: () => void } | null} */
+let sourceWatcher = null;
 let shuttingDown = false;
 let vitePluginBuildAttempted = false;
 let viteRestartCount = 0;
 let viteRestartTimer = null;
+let viteHealthTimer = null;
+let viteStartedAt = 0;
+
+// Vite cold-start of the full raw-source module graph can exceed 60s on slow
+// shared CI runners (2-4 cores). Allow CI to widen the health-check kill window
+// via env; dev machines keep the 60s default.
+const VITE_READY_BUDGET_MS =
+  Number(process.env.ELIZA_DEV_VITE_READY_BUDGET_MS) || 60_000;
 
 function terminateChild(proc, signal = "SIGTERM") {
   if (!proc) return;
@@ -850,12 +923,20 @@ function cleanup(exitCode = 0) {
   }
   shuttingDown = true;
 
+  if (sourceWatcher) {
+    sourceWatcher.close();
+    sourceWatcher = null;
+  }
   terminateChild(viteProcess, "SIGTERM");
   terminateChild(apiProcess, "SIGTERM");
   if (viteRestartTimer) {
     clearTimeout(viteRestartTimer);
     viteRestartTimer = null;
   }
+  if (viteHealthTimer) {
+    clearTimeout(viteHealthTimer);
+    viteHealthTimer = null;
+  }
 
   setTimeout(() => {
     terminateChild(viteProcess, "SIGKILL");
@@ -873,51 +954,58 @@ if (process.platform !== "win32") {
   process.on("SIGHUP", () => cleanup(0));
 }
 
-function startVite() {
-  const childEnv = createDevChildEnv(process.env);
+function buildCapacitorPluginsIfNeeded(childEnv) {
   const pkgPath = path.join(cwd, appDir, "package.json");
-  if (!vitePluginBuildAttempted && existsSync(pkgPath)) {
-    vitePluginBuildAttempted = true;
-    try {
-      const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
-      if (pkg.scripts?.["plugin:build"]) {
-        const appAbs = path.join(cwd, appDir);
-        const pluginsDir = NATIVE_PLUGINS_ROOT;
-        const forcePlugins =
-          process.env.ELIZA_DEV_PLUGIN_BUILD === "1" ||
-          process.env.ELIZA_DEV_PLUGIN_BUILD === "always";
-        const skipPlugins =
-          process.env.ELIZA_DEV_PLUGIN_BUILD === "0" ||
-          process.env.ELIZA_SKIP_PLUGIN_BUILD === "1";
-        if (skipPlugins) {
-          console.log(
-            `  ${green(logPrefix)} ${dim("Skipping Capacitor plugin build (ELIZA_SKIP_PLUGIN_BUILD=1).")}`,
-          );
-        } else if (
-          forcePlugins ||
-          capacitorPluginsBuildNeeded(pluginsDir, CAPACITOR_PLUGIN_NAMES)
-        ) {
-          console.log(
-            `  ${green(logPrefix)} Building plugins for ${appDir}...`,
-          );
-          execSync(hasBun ? "bun run plugin:build" : "npm run plugin:build", {
-            cwd: appAbs,
-            stdio: "inherit",
-            env: childEnv,
-          });
-        } else {
-          console.log(
-            `  ${green(logPrefix)} ${dim("Capacitor plugins dist up to date (skip rimraf/tsc/rollup). Set ELIZA_DEV_PLUGIN_BUILD=1 to force.")}`,
-          );
-        }
+  if (vitePluginBuildAttempted || !existsSync(pkgPath)) {
+    return;
+  }
+  vitePluginBuildAttempted = true;
+  try {
+    const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+    if (pkg.scripts?.["plugin:build"]) {
+      const appAbs = path.join(cwd, appDir);
+      const pluginsDir = NATIVE_PLUGINS_ROOT;
+      const forcePlugins =
+        process.env.ELIZA_DEV_PLUGIN_BUILD === "1" ||
+        process.env.ELIZA_DEV_PLUGIN_BUILD === "always";
+      const skipPlugins =
+        process.env.ELIZA_DEV_PLUGIN_BUILD === "0" ||
+        process.env.ELIZA_SKIP_PLUGIN_BUILD === "1" ||
+        (process.env.ELIZA_DEV_SOURCE === "1" && !forcePlugins);
+      if (skipPlugins) {
+        const skipReason =
+          process.env.ELIZA_DEV_SOURCE === "1" && !forcePlugins
+            ? "ELIZA_DEV_SOURCE=1"
+            : "ELIZA_SKIP_PLUGIN_BUILD=1";
+        console.log(
+          `  ${green(logPrefix)} ${dim(`Skipping Capacitor plugin build (${skipReason}).`)}`,
+        );
+      } else if (
+        forcePlugins ||
+        capacitorPluginsBuildNeeded(pluginsDir, CAPACITOR_PLUGIN_NAMES)
+      ) {
+        console.log(`  ${green(logPrefix)} Building plugins for ${appDir}...`);
+        execSync(hasBun ? "bun run plugin:build" : "npm run plugin:build", {
+          cwd: appAbs,
+          stdio: "inherit",
+          env: childEnv,
+        });
+      } else {
+        console.log(
+          `  ${green(logPrefix)} ${dim("Capacitor plugins dist up to date (skip rimraf/tsc/rollup). Set ELIZA_DEV_PLUGIN_BUILD=1 to force.")}`,
+        );
       }
-    } catch (err) {
-      console.error(
-        `  ${green(logPrefix)} Failed to build plugins for ${appDir}:`,
-        err.message,
-      );
     }
+  } catch (err) {
+    console.error(
+      `  ${green(logPrefix)} Failed to build plugins for ${appDir}:`,
+      err.message,
+    );
   }
+}
+
+function startVite() {
+  const childEnv = createDevChildEnv(process.env);
 
   const viteCmd = hasBun ? "bun" : "npx";
   const viteForce =
@@ -935,6 +1023,7 @@ function startVite() {
       `  ${green(logPrefix)} ${dim("Vite --force (ELIZA_VITE_FORCE=1): re-optimizing deps.")}`,
     );
   }
+  viteStartedAt = Date.now();
   viteProcess = spawn(viteCmd, viteArgs, {
     cwd: path.join(cwd, appDir),
     env: {
@@ -968,11 +1057,25 @@ function startVite() {
     process.stderr.write(data);
   });
 
+  // Capacitor plugin build runs AFTER vite is spawned, not before. The
+  // recursive native-plugin source walk (capacitorPluginsBuildNeeded) is a
+  // synchronous ~1s parent-side cost that previously delayed first paint by
+  // blocking before spawn. Capacitor plugins are not in the web SPA module
+  // graph, so the dist appearing slightly later is safe for the dashboard this
+  // vite instance serves — the vite child now warms up in parallel while the
+  // walk (and any rebuild) runs.
+  buildCapacitorPluginsIfNeeded(childEnv);
+
   viteProcess.on("exit", (code, signal) => {
     if (shuttingDown) return;
     viteProcess = null;
-    const exitLabel =
-      signal ? `signal ${signal}` : `code ${code === null ? "null" : code}`;
+    if (viteHealthTimer) {
+      clearTimeout(viteHealthTimer);
+      viteHealthTimer = null;
+    }
+    const exitLabel = signal
+      ? `signal ${signal}`
+      : `code ${code === null ? "null" : code}`;
     viteRestartCount += 1;
     if (viteRestartCount > 5) {
       console.error(
@@ -989,6 +1092,33 @@ function startVite() {
       if (!shuttingDown) startVite();
     }, 400);
   });
+
+  scheduleViteHealthCheck();
+}
+
+function scheduleViteHealthCheck(delayMs = 15_000) {
+  if (viteHealthTimer) clearTimeout(viteHealthTimer);
+  viteHealthTimer = setTimeout(async () => {
+    viteHealthTimer = null;
+    if (shuttingDown || !viteProcess) return;
+
+    const listening = await isPortListening(UI_PORT);
+    if (!listening) {
+      const ageMs = Date.now() - viteStartedAt;
+      if (ageMs > VITE_READY_BUDGET_MS) {
+        console.log(
+          `  ${green(logPrefix)} ${dim(
+            `Vite process is running but port ${UI_PORT} is not accepting connections — restarting UI.`,
+          )}`,
+        );
+        terminateChild(viteProcess, "SIGTERM");
+        return;
+      }
+    }
+
+    scheduleViteHealthCheck();
+  }, delayMs);
+  viteHealthTimer.unref();
 }
 
 if (uiOnly) {
@@ -1042,38 +1172,30 @@ if (uiOnly) {
     devServerEntry = path.resolve(cwd, devServerEntry);
   }
 
-  let useWatch = !skipBunWatch;
-  if (useWatch) {
-    const buildPid = detectConcurrentBuilds();
-    if (buildPid) {
-      console.log(
-        `  ${green(logPrefix)} ${dim(
-          `Concurrent build detected (PID ${buildPid}) — disabling --watch to avoid hot-reload loop on dist/ writes. Set ELIZA_DEV_NO_WATCH=1 to silence this notice.`,
-        )}`,
-      );
-      useWatch = false;
-    }
-  }
-
-  const apiCmd = hasBun
-    ? [
-        "bun",
-        "--no-install",
-        ...nodeStealthImports.flatMap((filePath) => ["--preload", filePath]),
-        ...(useWatch ? ["--watch"] : []),
-        devServerEntry,
-      ]
-    : [
-        "node",
-        "--import",
-        "tsx",
-        ...nodeStealthImports.flatMap((filePath) => ["--import", filePath]),
-        ...(useWatch ? ["--watch"] : []),
-        devServerEntry,
-      ];
+  // Agent hot-reload is driven by a source-only watcher (started after the
+  // supervisor below), not by `node --watch`. The watcher never sees `dist/`,
+  // so it is immune to concurrent-build churn.
+  const useWatch = !skipSourceWatch;
+
+  const { runtime: apiRuntime, command: apiRuntimeCmd } =
+    resolveApiRuntimeCommand(process.env);
+  const apiRuntimeIsBun = apiRuntime === "bun";
+  const apiCmd = [
+    apiRuntimeCmd,
+    "--conditions=eliza-source",
+    ...(apiRuntimeIsBun ? [] : ["--import", "tsx"]),
+    // Bun preloads modules with `--preload`; Node uses `--import`. Passing
+    // `--import` to Bun breaks startup whenever a stealth shim is enabled
+    // (OpenAI Codex / Claude Code).
+    ...nodeStealthImports.flatMap((filePath) => [
+      apiRuntimeIsBun ? "--preload" : "--import",
+      filePath,
+    ]),
+    devServerEntry,
+  ];
   // The API server resolves @elizaos/* deps via Bun workspace lookup, which
   // walks up from cwd looking for a package.json with a `workspaces` field.
-  // When running from the milady-style outer repo (cwd contains an `eliza/`
+  // When running from the eliza-style outer repo (cwd contains an `eliza/`
   // submodule), the outer package.json's `workspaces: ["apps/*"]` excludes
   // eliza's workspace packages — so plugin-x402, plugin-streaming, etc. fail
   // to resolve. Spawn the API child with cwd anchored at eliza/ so its
@@ -1084,28 +1206,101 @@ if (uiOnly) {
     : cwd;
 
   const childEnv = createDevChildEnv(process.env);
+  // V8 bytecode cache for the Node API runtime. The runtime is deliberately
+  // Node (not Bun) for node: built-ins, so this persists compiled module
+  // bytecode across boots and hot-reload restarts, trimming plugin-import cost.
+  // Node 22.8+ honors it; older node and Bun ignore the var (safe no-op).
+  // Pinned under the state dir (not os.tmpdir()) so an OS temp reap doesn't
+  // wipe the warm ~100MB cache and force a multi-second cold recompile on the
+  // next boot. Content-hash-keyed, so a stale entry self-invalidates.
+  const apiCompileCacheDir =
+    childEnv.NODE_COMPILE_CACHE?.trim() ||
+    path.join(
+      process.env.ELIZA_STATE_DIR?.trim() ||
+        path.join(os.homedir(), ".local", "state", cliName),
+      "cache",
+      "node-compile",
+    );
+  // Opt-in (ELIZA_PIN_TSX_CACHE=1): pin tsx's content-hashed transpile cache
+  // under the state dir. tsx 4.x has no env to relocate its disk cache; the dir
+  // derives from os.tmpdir(), which honors TMPDIR. Same rationale as the
+  // NODE_COMPILE_CACHE pin above — an OS temp reap (>3-day idle, /tmp sweep)
+  // would otherwise wipe the warm transpile cache and force a multi-second cold
+  // recompile. Default (flag unset) leaves TMPDIR untouched, so this only
+  // changes WHERE transpile output caches, never WHAT runs.
+  const pinTsxCache = process.env.ELIZA_PIN_TSX_CACHE?.trim() === "1";
+  let apiTmpDir;
+  if (pinTsxCache) {
+    apiTmpDir = path.join(path.dirname(apiCompileCacheDir), "tmp");
+    mkdirSync(apiTmpDir, { recursive: true });
+  }
   const apiSpawnEnv = extendNodePathEnv(
     {
       ...childEnv,
       NODE_ENV: "development",
+      NODE_COMPILE_CACHE: apiCompileCacheDir,
+      ...(pinTsxCache ? { TMPDIR: apiTmpDir } : {}),
+      NODE_OPTIONS: [
+        "--disable-warning=ExperimentalWarning",
+        // Bound the dev API child's V8 old-space so a runaway JS module/state
+        // graph fails fast (the api-supervisor restarts it) instead of slowly
+        // swap-dying. Healthy boots sit ~230-440MB; only a stuck/looping child
+        // exceeds this. Most of a stuck child's RSS is native/WASM (PGlite,
+        // llama) living OUTSIDE old-space, so this is a backstop, not the
+        // primary bound. Override with ELIZA_DEV_API_MAX_OLD_SPACE_MB.
+        `--max-old-space-size=${process.env.ELIZA_DEV_API_MAX_OLD_SPACE_MB?.trim() || "4096"}`,
+        // Let the dev heap-report timer force a GC for an accurate heapUsed.
+        "--expose-gc",
+      ].reduce(appendNodeOption, childEnv.NODE_OPTIONS),
       ELIZA_NAMESPACE: cliName,
       ELIZA_API_PORT: String(API_PORT),
       ELIZA_UI_PORT: String(UI_PORT),
       ELIZA_PORT: String(UI_PORT),
       ELIZA_HEADLESS: "1",
       ELIZA_DEV_AUTH_BYPASS: "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 dashboard reaches first
+      // paint before they finish. Brief feature-route 404 window after "ready"
+      // is the trade-off; acceptable for dev. Explicit env always wins.
+      ELIZA_DEFER_APP_ROUTES: process.env.ELIZA_DEFER_APP_ROUTES?.trim() || "1",
       LOG_LEVEL: devLogLevel,
+      // Dev boots happen on developer machines that may be busy (concurrent
+      // builds, test suites, other agents). plugin-sql pulls in native pglite
+      // bindings whose dynamic import can exceed the 30s production default
+      // under CPU contention, false-failing the whole boot into a retry loop.
+      // Give dev generous headroom; an explicit env value still wins.
+      ELIZA_PLUGIN_BOOT_TIMEOUT_MS:
+        process.env.ELIZA_PLUGIN_BOOT_TIMEOUT_MS ?? "90000",
     },
     apiSpawnCwd,
   );
 
+  if (apiRuntimeCmd !== "node" && path.isAbsolute(apiRuntimeCmd)) {
+    apiSpawnEnv.PATH = `${path.dirname(apiRuntimeCmd)}${path.delimiter}${apiSpawnEnv.PATH ?? ""}`;
+  }
+
+  // The first launch is a cold boot; every later spawn is a hot-reload respawn
+  // (the source watcher bounced the child). Marking respawns lets the agent skip
+  // boot-tail work that only matters once — e.g. voice warmup, which otherwise
+  // re-fires a cloud TTS call and fully reloads the native whisper model on
+  // every edit, flooding the dev log.
+  let apiLaunchCount = 0;
   const apiSupervisor = createApiSupervisor({
-    spawnChild: () =>
-      spawn(apiCmd[0], apiCmd.slice(1), {
+    spawnChild: () => {
+      const apiProcessSpawnedAtMs = String(Date.now());
+      const isHotReload = apiLaunchCount++ > 0;
+      return spawn(apiCmd[0], apiCmd.slice(1), {
         cwd: apiSpawnCwd,
-        env: apiSpawnEnv,
+        env: {
+          ...apiSpawnEnv,
+          [API_PROCESS_SPAWNED_AT_ENV]: apiProcessSpawnedAtMs,
+          [PROCESS_SPAWNED_AT_ENV]: apiProcessSpawnedAtMs,
+          ...(isHotReload ? { ELIZA_DEV_IS_HOT_RELOAD: "1" } : {}),
+        },
         stdio: ["inherit", "pipe", "pipe"],
-      }),
+      });
+    },
     onSpawn: (child) => {
       apiProcess = child;
       child.on("error", (err) => {
@@ -1134,12 +1329,60 @@ if (uiOnly) {
     },
     onGiveUp: (code) => cleanup(code ?? 1),
     isShuttingDown: () => shuttingDown,
+    // Reuse the dev process-tree killer so a hot-reload restart takes the
+    // API child's descendants (coding sub-agents, native helpers) with it.
+    terminate: (child, signal) => terminateChild(child, signal),
     log: (message) => console.log(`\n  ${green(logPrefix)} ${message}`),
     warn: (message) => console.error(`\n  ${green(logPrefix)} ${message}`),
   });
 
   apiSupervisor.start();
 
+  // Agent hot-reload: bounce the API child when backend source changes. The
+  // watcher only sees `*/src` (never `dist/`), and a restart fires only when the
+  // agent is currently healthy — so a build, or a change during boot, can never
+  // kill an in-progress boot. A booting agent already loads the latest source.
+  if (useWatch) {
+    sourceWatcher = startAgentSourceWatcher({
+      root: apiSpawnCwd,
+      onChange: (relPath, changedCount) => {
+        // A git reset/checkout/branch-switch or a build rewrites many files at
+        // once — that is churn, not a developer edit. Don't bounce the agent
+        // for it (the boots/502s would storm); a single restart can't track a
+        // moving tree anyway. A real edit touches one or a few files.
+        if (changedCount > HOT_RELOAD_BULK_CHANGE_LIMIT) {
+          console.log(
+            `\n  ${green(logPrefix)} ${dim(`Bulk change (${changedCount} files, e.g. ${relPath}) — skipping agent reload (looks like a reset/build).`)}`,
+          );
+          return;
+        }
+        void (async () => {
+          if (!(await isAgentReadyNow(API_PORT))) return;
+          console.log(
+            `\n  ${green(logPrefix)} ${dim(`Source change (${relPath}) — reloading agent…`)}`,
+          );
+          apiSupervisor.restart();
+        })();
+      },
+      onError: (dir, err) => {
+        console.log(
+          `  ${green(logPrefix)} ${dim(`Hot-reload watch skipped for ${path.relative(apiSpawnCwd, dir)}: ${err.message}`)}`,
+        );
+      },
+    });
+    console.log(
+      `  ${green(logPrefix)} ${dim(`Agent hot-reload on: watching ${sourceWatcher.count} source dirs (set ELIZA_DEV_NO_WATCH=1 to disable).`)}`,
+    );
+  }
+
+  // Start Vite immediately, in parallel with the API boot. The dev server only
+  // proxies to the API at request time — it has no startup dependency on the
+  // API being up — so gating it behind waitForPort(API_PORT) just stacked the
+  // full runtime+plugin boot in front of first paint. Booting both at once
+  // gives the browser a UI as soon as Vite is ready, and requests resolve once
+  // the API comes up moments later.
+  startVite();
+
   const startTime = Date.now();
   let phase = "port";
   const dots = setInterval(() => {
@@ -1168,7 +1411,6 @@ if (uiOnly) {
       console.log(
         `\r  ${green(logPrefix)} ${green(`Agent ready`)} ${dim(`(${elapsed}s)`)}          `,
       );
-      startVite();
     })
     .catch((err) => {
       clearInterval(dots);