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

package/runtime/eliza.js

@@ -16,17 +16,27 @@ import { pathToFileURL } from "node:url";
 import { CUSTOM_PLUGINS_DIRNAME, getLastFailedPluginNames, loadElizaConfig, resolveDefaultAgentWorkspaceDir, resolvePackageEntry, resolveUserPath, scanDropInPlugins, applyCloudConfigToEnv as upstreamApplyCloudConfigToEnv, bootElizaRuntime as upstreamBootElizaRuntime, collectPluginNames as upstreamCollectPluginNames, configureLocalEmbeddingPlugin as upstreamConfigureLocalEmbeddingPlugin, shutdownRuntime as upstreamShutdownRuntime, startEliza as upstreamStartEliza, } from "@elizaos/agent";
 export { CHANNEL_PLUGIN_MAP } from "./channel-plugin-map.js";
 export { CUSTOM_PLUGINS_DIRNAME, resolvePackageEntry, scanDropInPlugins };
-import { AutonomyService, ChannelType, logger, stringToUuid, } from "@elizaos/core";
-import { ensureRuntimeSqlCompatibility, isMobilePlatform, resolveServerOnlyPort, syncAppEnvToEliza, syncElizaEnvAliases, syncResolvedApiPort, } from "@elizaos/shared";
-import { getApps, loadRegistry } from "../registry";
+import { AutonomyService, ChannelType, logger, ModelType, stringToUuid, } from "@elizaos/core";
+import { ensureRuntimeSqlCompatibility, formatError, formatErrorWithStack, isMobilePlatform, resolveDesktopApiPort, resolveServerOnlyPort, syncAppEnvToEliza, syncElizaEnvAliases, syncResolvedApiPort, } from "@elizaos/shared";
+import { getApps, loadRegistry } from "../registry/index.js";
+import { registerCoreSensitiveRequestAdapters } from "../services/sensitive-requests/index.js";
 import { listAppRoutePluginLoaders, } from "./app-route-plugin-registry.js";
-import { DEFAULT_MODELS_DIR, embeddingGgufFilePresent, ensureModel, findExistingEmbeddingModelForWarmupReuse, isEmbeddingWarmupReuseDisabled, } from "./embedding-manager-support.js";
-import { detectEmbeddingPreset } from "./embedding-presets.js";
-import { shouldWarmupLocalEmbeddingModel } from "./embedding-warmup-policy.js";
-import { ensureLocalInferenceHandler } from "./ensure-local-inference-handler.js";
+import { shouldWarmupVoice, warmVoiceModels } from "./voice-warmup.js";
+// plugin-local-inference loaded lazily to avoid static plugin boundary violations.
+let _localInferenceRuntime;
+async function _localInference() {
+    if (!_localInferenceRuntime) {
+        _localInferenceRuntime = await import("@elizaos/plugin-local-inference/runtime");
+    }
+    return _localInferenceRuntime;
+}
+import { getSharedCompatRuntimeState, patchHttpCreateServerForCompat, startApiServer, } from "../api/server.js";
+const _require = createRequire(import.meta.url);
+import { invalidateCorsAllowedPorts } from "../api/server-cors.js";
+import { bootLap } from "../boot-profile.js";
+import { isRuntimeAutonomyEnabled } from "./autonomy-policy.js";
 import { ensureTextToSpeechHandler, isEdgeTtsDisabled as isTextToSpeechEdgeTtsDisabled, } from "./ensure-text-to-speech-handler.js";
-import { shouldEnableMobileLocalInference } from "./mobile-local-inference-gate.js";
-import { updateStartupEmbeddingProgress } from "./startup-overlay.js";
+import { updateStartupEmbeddingProgress, } from "./startup-overlay.js";
 import { handleTelegramStandaloneMessage } from "./telegram-standalone-handler.js";
 import { shouldStartTelegramStandaloneBot } from "./telegram-standalone-policy.js";
 const AUTONOMY_WORLD_ID = stringToUuid("00000000-0000-0000-0000-000000000001");
@@ -87,7 +97,7 @@ async function ensureAutonomyBootstrapContext(runtime) {
     const runtimeWithCompat = runtime;
     const adapter = runtime.adapter;
     const autonomousRoomId = stringToUuid(`autonomy-room-${runtime.agentId}`);
-    await runtimeWithCompat.ensureWorldExists?.({
+    await runtimeWithCompat.ensureWorldExists({
         id: AUTONOMY_WORLD_ID,
         name: "Autonomy World",
         agentId: runtime.agentId,
@@ -97,7 +107,7 @@ async function ensureAutonomyBootstrapContext(runtime) {
             description: "World for autonomous agent thinking",
         },
     });
-    await runtimeWithCompat.ensureRoomExists?.({
+    await runtimeWithCompat.ensureRoomExists({
         id: autonomousRoomId,
         name: "Autonomous Thoughts",
         worldId: AUTONOMY_WORLD_ID,
@@ -117,9 +127,9 @@ async function ensureAutonomyBootstrapContext(runtime) {
             description: "Dedicated entity for autonomy service prompts",
         },
     };
-    const existingEntity = (await runtimeWithCompat.getEntityById?.(AUTONOMY_ENTITY_ID)) ?? null;
+    const existingEntity = (await runtimeWithCompat.getEntityById(AUTONOMY_ENTITY_ID)) ?? null;
     if (!existingEntity) {
-        const created = await runtimeWithCompat.createEntity?.(autonomyEntity);
+        const created = await runtimeWithCompat.createEntity(autonomyEntity);
         if (!created && adapter?.upsertEntities) {
             await adapter.upsertEntities([autonomyEntity]);
         }
@@ -156,6 +166,48 @@ async function ensureAutonomyBootstrapContext(runtime) {
         await runtimeWithCompat.addParticipant(AUTONOMY_ENTITY_ID, autonomousRoomId);
     }
 }
+class OptionalAppRoutePluginUnavailableError extends Error {
+    specifier;
+    constructor(specifier, cause) {
+        super(`Optional app route plugin ${specifier} is unavailable`, { cause });
+        this.specifier = specifier;
+        this.name = "OptionalAppRoutePluginUnavailableError";
+    }
+}
+function isOptionalAppRoutePluginUnavailableError(err) {
+    return err instanceof OptionalAppRoutePluginUnavailableError;
+}
+function splitPackageSpecifier(specifier) {
+    const parts = specifier.split("/");
+    if (specifier.startsWith("@")) {
+        if (parts.length < 2)
+            return null;
+        return {
+            packageName: `${parts[0]}/${parts[1]}`,
+            exportSubpath: parts.length > 2 ? `./${parts.slice(2).join("/")}` : ".",
+        };
+    }
+    if (!parts[0])
+        return null;
+    return {
+        packageName: parts[0],
+        exportSubpath: parts.length > 1 ? `./${parts.slice(1).join("/")}` : ".",
+    };
+}
+async function resolveLocalAppRoutePluginEntry(specifier) {
+    const parsed = splitPackageSpecifier(specifier);
+    if (!parsed)
+        return null;
+    let packageJsonPath;
+    try {
+        packageJsonPath = _require.resolve(`${parsed.packageName}/package.json`);
+    }
+    catch {
+        return null;
+    }
+    const entry = await resolvePackageEntry(path.dirname(packageJsonPath), parsed.exportSubpath);
+    return existsSync(entry) ? entry : null;
+}
 function isPlugin(value) {
     return (typeof value === "object" &&
         value !== null &&
@@ -179,10 +231,27 @@ function resolvePluginExport(module, exportName) {
     throw new Error("No plugin export found");
 }
 async function loadAppRoutePluginFromSpecifier(specifier, exportName) {
-    const module = (await import(__rewriteRelativeImportExtension(
-    /* webpackIgnore: true */ specifier)));
+    let module;
+    try {
+        module = (await import(__rewriteRelativeImportExtension(
+        /* webpackIgnore: true */ specifier)));
+    }
+    catch (err) {
+        if (!isModuleNotFoundError(err))
+            throw err;
+        const sourceEntry = await resolveLocalAppRoutePluginEntry(specifier);
+        if (!sourceEntry) {
+            throw new OptionalAppRoutePluginUnavailableError(specifier, err);
+        }
+        logger.debug(`[eliza] Loading app route plugin ${specifier} from workspace source at ${sourceEntry}`);
+        module = (await import(__rewriteRelativeImportExtension(pathToFileURL(sourceEntry).href)));
+    }
     return resolvePluginExport(module, exportName);
 }
+/** @internal Exported for focused loader regression tests. */
+export const __loadAppRoutePluginFromSpecifierForTest = loadAppRoutePluginFromSpecifier;
+const WORKFLOW_ROUTE_PLUGIN_ID = "@elizaos/plugin-workflow:routes";
+const WALLET_ROUTE_PLUGIN_ID = "@elizaos/plugin-wallet:routes";
 function getRegistryAppRoutePluginLoaders() {
     return getApps(loadRegistry()).flatMap((app) => {
         const routePlugin = app.launch.routePlugin;
@@ -196,6 +265,55 @@ function getRegistryAppRoutePluginLoaders() {
         ];
     });
 }
+/**
+ * Opt-in dev knob: comma-separated app-route-plugin ids to skip on boot.
+ * Empty / unset => no filtering (default behavior unchanged: every app-route
+ * plugin loads). This trims time-to-ready for core/runtime work by not
+ * transpiling + registering hundreds of feature routes a core dev does not
+ * exercise.
+ *
+ * A loader's id is its full package name (e.g. `@elizaos/plugin-personal-assistant`,
+ * `@elizaos/plugin-steward-app`, `@elizaos/plugin-elizacloud:routes`). Tokens
+ * are matched against BOTH the full id and a normalized short alias
+ * (see {@link normalizeAppRoutePluginId}), so the ergonomic short forms work
+ * too: `ELIZA_SKIP_APP_ROUTE_PLUGINS=lifeops,steward,training,shopify`.
+ */
+export function getSkippedAppRoutePluginIds() {
+    return new Set((process.env.ELIZA_SKIP_APP_ROUTE_PLUGINS ?? "")
+        .split(",")
+        .map((value) => value.trim())
+        .filter(Boolean));
+}
+/**
+ * Opt-in dev knob: when set to the literal token `"1"`, the post-ready boot
+ * tail (app-route plugins, training hooks, sensitive-request adapters, telegram
+ * polling, trigger bridge, connector catalog, voice warmup) runs in the
+ * background instead of blocking the readiness gate, so `/api/health` flips
+ * `ready:true` and "Agent ready" prints sooner. Composes with
+ * {@link getSkippedAppRoutePluginIds}: `ELIZA_SKIP_APP_ROUTE_PLUGINS` filters
+ * WHICH route plugins load; this controls WHETHER that tail blocks ready.
+ *
+ * Returns true ONLY for `"1"` (undefined / `""` / `"0"` / `"false"` / `"true"`
+ * all return false) so the default boot is byte-identical: the tail is awaited
+ * inline exactly as before.
+ */
+export function getDeferAppRoutesEnabled(env = process.env) {
+    return env.ELIZA_DEFER_APP_ROUTES?.trim() === "1";
+}
+/**
+ * Normalize an app-route-plugin id (or a user-supplied skip token) to a short
+ * alias for forgiving matching: lowercase, drop the `@elizaos/plugin-` prefix
+ * and the `:routes` / `-app` / `-ui` / `-routes` suffixes. So
+ * `@elizaos/plugin-steward-app` and `steward` both normalize to `steward`.
+ */
+export function normalizeAppRoutePluginId(id) {
+    return id
+        .trim()
+        .toLowerCase()
+        .replace(/^@elizaos\/plugin-/, "")
+        .replace(/:routes$/, "")
+        .replace(/-(app|ui|routes)$/, "");
+}
 function getAppRoutePluginLoaders() {
     const byId = new Map();
     for (const entry of getRegistryAppRoutePluginLoaders()) {
@@ -204,46 +322,139 @@ function getAppRoutePluginLoaders() {
     for (const entry of listAppRoutePluginLoaders()) {
         byId.set(entry.id, entry);
     }
-    return [...byId.values()];
+    // plugin-workflow is default-enabled and registers its rawPath route plugin
+    // (`/api/automations`, `/api/workflow/*`) only as a side effect of its
+    // `register-routes` import. That side effect runs inside the plugin's own
+    // module init, which is not guaranteed to have executed before this snapshot
+    // is taken on the post-ready boot tail — so the loader can be missing and the
+    // routes 404. Register it explicitly here (load-order independent), mirroring
+    // how every other rawPath route plugin is wired via the registry.
+    if (!byId.has(WORKFLOW_ROUTE_PLUGIN_ID)) {
+        byId.set(WORKFLOW_ROUTE_PLUGIN_ID, {
+            id: WORKFLOW_ROUTE_PLUGIN_ID,
+            load: () => loadAppRoutePluginFromSpecifier("@elizaos/plugin-workflow/plugin-routes", "workflowRoutePlugin"),
+        });
+    }
+    // plugin-wallet has the same load-order hazard: its rawPath route plugin
+    // (`/api/wallet/market-overview`) registers only as a side effect of the
+    // `register-routes` import, which is not guaranteed to have run before this
+    // snapshot. Register it explicitly so the route is always mounted.
+    if (!byId.has(WALLET_ROUTE_PLUGIN_ID)) {
+        byId.set(WALLET_ROUTE_PLUGIN_ID, {
+            id: WALLET_ROUTE_PLUGIN_ID,
+            load: () => loadAppRoutePluginFromSpecifier("@elizaos/plugin-wallet/routes/plugin", "walletRoutePlugin"),
+        });
+    }
+    const skip = getSkippedAppRoutePluginIds();
+    if (skip.size === 0) {
+        return [...byId.values()];
+    }
+    // Match a loader against the skip tokens by full id OR normalized short alias
+    // (so both `@elizaos/plugin-steward-app` and `steward` skip the same loader).
+    const skipNormalized = new Set([...skip].map((token) => normalizeAppRoutePluginId(token)));
+    const kept = [];
+    const skipped = [];
+    for (const entry of byId.values()) {
+        if (skip.has(entry.id) ||
+            skipNormalized.has(normalizeAppRoutePluginId(entry.id))) {
+            skipped.push(entry.id);
+        }
+        else {
+            kept.push(entry);
+        }
+    }
+    if (skipped.length > 0) {
+        logger.info(`[eliza] Skipping ${skipped.length} app route plugin(s) via ELIZA_SKIP_APP_ROUTE_PLUGINS: ${skipped.join(", ")}`);
+    }
+    return kept;
 }
 async function registerAppRoutePlugins(runtime) {
-    for (const { id, load } of getAppRoutePluginLoaders()) {
+    // Load all app-route plugin modules concurrently. This runs on the gated
+    // ready-path (repairRuntimeAfterBoot is awaited before the runtime is handed
+    // back and /api/health flips ready), so the previous sequential await-loop
+    // serialized ~11 independent dynamic imports (lifeops alone registers 188
+    // routes) and dominated time-to-ready. Imports are independent; loading them
+    // together overlaps their I/O and module resolution. Route registration is
+    // still applied in loader order after all settle, so dispatch order is
+    // unchanged, and per-plugin failures stay isolated (a rejected load logs and
+    // contributes no routes rather than aborting the rest).
+    const loaded = await Promise.all(getAppRoutePluginLoaders().map(async ({ id, load }) => {
         try {
-            const plugin = await load();
-            // Push rawPath routes directly onto runtime.routes to avoid the core's
-            // registerPlugin() path mangling (which prepends /<pluginName>/ to every
-            // route path). The rawPath flag means these routes already have their
-            // final absolute paths (e.g. /api/lifeops/app-state).
-            if (plugin.routes?.length) {
-                for (const route of plugin.routes) {
-                    const routePath = route.path.startsWith("/")
-                        ? route.path
-                        : `/${route.path}`;
-                    runtime.routes.push({ ...route, path: routePath });
-                }
-            }
-            logger.info(`[eliza] Registered app route plugin: ${plugin.name} (${plugin.routes?.length ?? 0} routes)`);
+            return await load();
         }
         catch (err) {
-            logger.warn(`[eliza] Failed to register app route plugin ${id}: ${err instanceof Error ? err.message : String(err)}`);
+            if (isOptionalAppRoutePluginUnavailableError(err)) {
+                logger.debug(`[eliza] App route plugin ${id} unavailable, skipping route registration`);
+                return null;
+            }
+            logger.warn(`[eliza] Failed to register app route plugin ${id}: ${formatError(err)}`);
+            return null;
+        }
+    }));
+    for (const plugin of loaded) {
+        if (!plugin)
+            continue;
+        // Push rawPath routes directly onto runtime.routes to avoid the core's
+        // registerPlugin() path mangling (which prepends /<pluginName>/ to every
+        // route path). The rawPath flag means these routes already have their
+        // final absolute paths (e.g. /api/lifeops/app-state).
+        if (plugin.routes?.length) {
+            for (const route of plugin.routes) {
+                const routePath = route.path.startsWith("/")
+                    ? route.path
+                    : `/${route.path}`;
+                runtime.routes.push({ ...route, path: routePath });
+            }
         }
+        logger.info(`[eliza] Registered app route plugin: ${plugin.name} (${plugin.routes?.length ?? 0} routes)`);
     }
 }
-const TRAINING_RUNTIME_HOOKS_SPECIFIER = "@elizaos/app-training";
+const TRAINING_RUNTIME_HOOKS_SPECIFIER = "@elizaos/plugin-training";
+/**
+ * Returns true only for genuine "module is not installed" import failures.
+ * Bun raises `ResolveMessage` with `code === "ERR_MODULE_NOT_FOUND"` when a
+ * specifier cannot be resolved; Node uses the same `code`. Anything else
+ * (syntax error, runtime error during module init, tsconfig path hijack,
+ * missing transitive dependency) is a real load failure and must NOT be
+ * misreported as "not installed".
+ */
+function isModuleNotFoundError(err) {
+    if (!err || typeof err !== "object")
+        return false;
+    const errObj = err;
+    if (errObj.code === "ERR_MODULE_NOT_FOUND")
+        return true;
+    if (errObj.constructor?.name === "ResolveMessage")
+        return true;
+    return false;
+}
 async function registerTrainingRuntimeHooks(runtime) {
     let hookMod;
     try {
         hookMod = (await import(__rewriteRelativeImportExtension(TRAINING_RUNTIME_HOOKS_SPECIFIER)));
     }
     catch (err) {
-        logger.warn(`[eliza] @elizaos/app-training not installed, skipping runtime hooks: ${err instanceof Error ? err.message : String(err)}`);
-        return;
+        if (isModuleNotFoundError(err)) {
+            logger.warn(`[eliza] @elizaos/plugin-training not installed, skipping runtime hooks`);
+            return;
+        }
+        // Real load failure (syntax error, broken transitive, init throw, etc.) —
+        // surface it loudly so it is not mistaken for "not installed".
+        logger.error(`[eliza] @elizaos/plugin-training failed to load (not 'not installed'): ${formatErrorWithStack(err)}`);
+        throw err;
     }
     if (!hookMod.registerTrainingRuntimeHooks) {
         throw new Error(`[eliza] ${TRAINING_RUNTIME_HOOKS_SPECIFIER} did not export registerTrainingRuntimeHooks`);
     }
     await hookMod.registerTrainingRuntimeHooks(runtime);
 }
+// The most recent runtime handed to the post-ready boot tail. A backgrounded
+// (deferred) tail compares against this so a hot-restart that boots a newer
+// runtime supersedes the old one's still-running tail, preventing route/service
+// registration onto a torn-down runtime. In the default inline-await path the
+// tail completes before the next repair call reassigns this, so the guard never
+// trips and default behavior stays byte-identical.
+let latestBootTailRuntime = null;
 async function repairRuntimeAfterBoot(runtime) {
     await ensureRuntimeSqlCompatibility(runtime);
     // Mobile (Android / iOS) shortcut: the runtime is already serving from
@@ -255,31 +466,31 @@ async function repairRuntimeAfterBoot(runtime) {
     // them here is what the mobile bundle has to do to avoid crashing on first
     // turn — feature parity comes from cloud-side services, not on-device state.
     if (isMobilePlatform()) {
-        if (shouldEnableMobileLocalInference()) {
-            await ensureLocalInferenceHandler(runtime);
+        if ((await _localInference()).shouldEnableMobileLocalInference()) {
+            await (await _localInference()).ensureLocalInferenceHandler(runtime);
         }
         logger.info("[eliza] Mobile platform detected — skipping desktop-only boot helpers");
         return runtime;
     }
-    await ensureTextToSpeechHandler(runtime);
-    await ensureLocalInferenceHandler(runtime);
-    await ensureAutonomyBootstrapContext(runtime);
-    // ── Register app-specific route plugins ─────────────────────────────
-    // The registry and explicit registration API own the package bindings; the
-    // runtime only consumes app route plugin loaders.
-    await registerAppRoutePlugins(runtime);
-    await registerTrainingRuntimeHooks(runtime);
+    await (await _localInference()).ensureLocalInferenceHandler(runtime);
+    const autonomyLoopEnabled = isRuntimeAutonomyEnabled(process.env);
+    if (autonomyLoopEnabled) {
+        await ensureAutonomyBootstrapContext(runtime);
+    }
+    else {
+        logger.info("[eliza] Autonomy bootstrap deferred — autonomous loop disabled");
+    }
     if (!runtime.getService("AUTONOMY")) {
         try {
             await startAndRegisterAutonomyService(runtime);
-            logger.info("[eliza] AutonomyService started after SQL compatibility repair");
+            logger.info("[eliza] AutonomyService started and waiting");
         }
         catch (error) {
-            throw new Error(`[eliza] AutonomyService restart after SQL compatibility repair failed: ${error instanceof Error ? error.message : String(error)}`);
+            throw new Error(`[eliza] AutonomyService start failed: ${formatError(error)}`);
         }
     }
-    // Enable the autonomy loop so trigger/heartbeat instructions are processed.
-    {
+    // Enable the continuous autonomy loop only when explicitly requested.
+    if (autonomyLoopEnabled) {
         const autonomySvc = getAutonomyService(runtime);
         if (autonomySvc) {
             try {
@@ -287,24 +498,98 @@ async function repairRuntimeAfterBoot(runtime) {
                 logger.info("[eliza] AutonomyService enabled — trigger instructions will be processed");
             }
             catch (err) {
-                throw new Error(`[eliza] Failed to enable autonomy loop: ${err instanceof Error ? err.message : String(err)}`);
+                throw new Error(`[eliza] Failed to enable autonomy loop: ${formatError(err)}`);
             }
         }
     }
-    if (shouldStartTelegramStandaloneBot()) {
-        await ensureTelegramBotPolling(runtime);
+    else {
+        logger.info("[eliza] AutonomyService waiting — set ENABLE_AUTONOMY=true to start autonomous loop");
+    }
+    // Post-ready tail: feature-route plugins, training hooks, sensitive-request
+    // adapters, telegram polling, the trigger bridge, the connector catalog, and
+    // voice warmup. None of these gate correctness of the first turn, so when
+    // ELIZA_DEFER_APP_ROUTES=1 they run in the background and ready flips before
+    // the tail completes (feature routes may 404 for a brief window — same
+    // audience as ELIZA_SKIP_APP_ROUTE_PLUGINS). When the knob is unset the tail
+    // is awaited inline, identical in steps and order to the pre-split path.
+    latestBootTailRuntime = runtime;
+    if (getDeferAppRoutesEnabled()) {
+        void runPostReadyBootTail(runtime);
+        return runtime;
+    }
+    await runPostReadyBootTail(runtime);
+    return runtime;
+}
+const DEFAULT_POST_READY_BOOT_STEPS = {
+    ensureTextToSpeechHandler,
+    registerAppRoutePlugins,
+    registerTrainingRuntimeHooks,
+    registerCoreSensitiveRequestAdapters,
+    shouldStartTelegramStandaloneBot,
+    ensureTelegramBotPolling,
+    stopTelegramBotPolling,
+    ensureTriggerEventBridge,
+    ensureConnectorTargetCatalog,
+    startDeferredVoiceWarmup,
+};
+/**
+ * Post-ready boot steps split out of {@link repairRuntimeAfterBoot}. Each step
+ * keeps its original error behavior verbatim — there is no wrapping try/catch:
+ * registerAppRoutePlugins isolates per-loader failures internally,
+ * ensureTriggerEventBridge / ensureConnectorTargetCatalog swallow into
+ * logger.warn internally, and ensureTextToSpeechHandler /
+ * registerTrainingRuntimeHooks throw (preserved in the default inline-await
+ * dispatch above).
+ *
+ * `steps` defaults to the real bound functions, so production behavior is
+ * unchanged; the seam exists only so the phase split is unit-testable.
+ */
+export async function runPostReadyBootTail(runtime, steps = DEFAULT_POST_READY_BOOT_STEPS) {
+    // Liveness guard: a hot-restart can swap runtimes mid-tail. If a newer boot
+    // has already claimed the tail slot, this runtime is superseded — bail before
+    // the first mutation so we never register routes/services onto a torn-down
+    // runtime. (In the default inline-await path the tail completes before the
+    // next repair call reassigns the slot, so this never trips.)
+    if (latestBootTailRuntime !== runtime) {
+        logger.info("[eliza] post-ready boot tail skipped — runtime superseded");
+        return;
+    }
+    await steps.ensureTextToSpeechHandler(runtime);
+    // ── Register app-specific route plugins ─────────────────────────────
+    // The registry and explicit registration API own the package bindings; the
+    // runtime only consumes app route plugin loaders.
+    await steps.registerAppRoutePlugins(runtime);
+    await steps.registerTrainingRuntimeHooks(runtime);
+    // Register first-party sensitive-request delivery adapters with the
+    // dispatch registry (no-op when the registry service isn't present).
+    steps.registerCoreSensitiveRequestAdapters(runtime);
+    if (steps.shouldStartTelegramStandaloneBot()) {
+        await steps.ensureTelegramBotPolling(runtime);
     }
     else {
-        stopTelegramBotPolling("passive-lifeops-connectors");
+        steps.stopTelegramBotPolling("passive-lifeops-connectors");
     }
     // Subscribe the trigger event bridge to the runtime event bus so
     // event-kind triggers fire on real MESSAGE_RECEIVED / REACTION_RECEIVED /
     // etc. emissions. plugin-workflow registers WORKFLOW_DISPATCH in its `init`
     // so by the time the bridge starts, workflow-kind event triggers already
     // have a dispatcher to call.
-    await ensureTriggerEventBridge(runtime);
-    await ensureConnectorTargetCatalog(runtime);
-    return runtime;
+    await steps.ensureTriggerEventBridge(runtime);
+    await steps.ensureConnectorTargetCatalog(runtime);
+    // Warm local voice models (Whisper STT + Kokoro TTS) in the background now
+    // that the runtime is ready. repairRuntimeAfterBoot is the single chokepoint
+    // every boot path funnels through (bootElizaRuntime AND startEliza's
+    // server-only + restart paths), so the warmup fires regardless of entry
+    // point. Fire-and-forget; gated + non-fatal inside startDeferredVoiceWarmup.
+    void steps.startDeferredVoiceWarmup(runtime);
+}
+/**
+ * Test seam: set the runtime that owns the post-ready tail slot. Mirrors what
+ * {@link repairRuntimeAfterBoot} does just before dispatching the tail, so a
+ * unit test can drive the liveness guard without a full boot.
+ */
+export function __setLatestBootTailRuntimeForTest(runtime) {
+    latestBootTailRuntime = runtime;
 }
 // Module-level handle for the trigger event bridge. Reset across
 // hot-reloads so we never leave two handler sets racing the runtime's
@@ -334,7 +619,7 @@ async function ensureTriggerEventBridge(runtime) {
         logger.info("[eliza] trigger event bridge armed");
     }
     catch (err) {
-        logger.warn(`[eliza] Failed to start trigger event bridge: ${err instanceof Error ? err.message : String(err)}`);
+        logger.warn(`[eliza] Failed to start trigger event bridge: ${formatError(err)}`);
     }
 }
 async function ensureConnectorTargetCatalog(runtime) {
@@ -353,8 +638,8 @@ async function ensureConnectorTargetCatalog(runtime) {
         const { createElizaConnectorTargetCatalog } = await import("../services/connector-target-catalog.js");
         const catalog = createElizaConnectorTargetCatalog({
             getConfig: () => loadElizaConfig(),
-            discordCache: _discordEnumerationCache ?? undefined,
-            logger: { warn: runtime.logger.warn?.bind(runtime.logger) },
+            discordCache: _discordEnumerationCache,
+            logger: { warn: runtime.logger.warn.bind(runtime.logger) },
         });
         runtime.services.set(CONNECTOR_TARGET_CATALOG_SERVICE_TYPE, [
             catalog,
@@ -372,7 +657,7 @@ async function ensureConnectorTargetCatalog(runtime) {
         logger.info("[eliza] connector-target-catalog registered");
     }
     catch (err) {
-        logger.warn(`[eliza] Failed to register connector-target-catalog: ${err instanceof Error ? err.message : String(err)}`);
+        logger.warn(`[eliza] Failed to register connector-target-catalog: ${formatError(err)}`);
     }
 }
 // Module-level Telegraf bot reference for lifecycle management across restarts.
@@ -405,14 +690,14 @@ async function ensureTelegramBotPolling(runtime) {
         bot.on("message", async (ctx) => {
             await handleTelegramStandaloneMessage(runtime, ctx);
         });
-        bot.catch((err) => logger.warn(`[eliza] Telegram bot error: ${err instanceof Error ? err.message : String(err)}`));
+        bot.catch((err) => logger.warn(`[eliza] Telegram bot error: ${formatError(err)}`));
         // Fire-and-forget — bot.launch() only resolves on stop()
         bot
             .launch({
             dropPendingUpdates: true,
             allowedUpdates: ["message", "message_reaction"],
         })
-            .catch((err) => logger.warn(`[eliza] Telegram bot launch error: ${err instanceof Error ? err.message : String(err)}`));
+            .catch((err) => logger.warn(`[eliza] Telegram bot launch error: ${formatError(err)}`));
         _telegramBot = bot;
         // Telegram bot cleanup is handled by the central signal handler in
         // startEliza() via _telegramBot — no separate registration needed.
@@ -420,7 +705,7 @@ async function ensureTelegramBotPolling(runtime) {
         logger.info("[eliza] Telegram bot polling started");
     }
     catch (err) {
-        logger.warn(`[eliza] Telegram bot setup failed: ${err instanceof Error ? err.message : String(err)}`);
+        logger.warn(`[eliza] Telegram bot setup failed: ${formatError(err)}`);
     }
 }
 /**
@@ -439,7 +724,43 @@ async function ensureTelegramBotPolling(runtime) {
  * so we do not re-download multi‑GB models. Opt out:
  * `ELIZA_EMBEDDING_WARMUP_NO_REUSE=1`.
  */
+// In-flight promise cache so concurrent callers (bootElizaRuntime +
+// startEliza both run on agent boot) share a single download. Without this,
+// two `fs.createWriteStream(dest)` open the same GGUF target concurrently,
+// and the first to fail calls `safeUnlink(dest)` — which deletes the file
+// out from under the second's pending write. Downstream `llama.loadModel`
+// then opens the now-missing file and throws ENOENT, which surfaces as an
+// uncaughtException and kills the agent.
+let warmupInFlight = null;
+function isTruthyEnvValue(value) {
+    const normalized = value?.trim().toLowerCase();
+    return (normalized === "1" ||
+        normalized === "true" ||
+        normalized === "yes" ||
+        normalized === "on");
+}
+function isLocalEmbeddingWarmupDeferredByEnv() {
+    return isTruthyEnvValue(process.env.ELIZA_DEFER_LOCAL_EMBEDDING_WARMUP);
+}
+function startLocalEmbeddingWarmup(onProgress) {
+    void warmupEmbeddingModel(onProgress);
+}
+export function startDeferredLocalEmbeddingWarmup(onProgress) {
+    if (!isLocalEmbeddingWarmupDeferredByEnv())
+        return false;
+    logger.info("[eliza] Starting deferred local embedding warmup");
+    startLocalEmbeddingWarmup(onProgress);
+    return true;
+}
 async function warmupEmbeddingModel(onProgress) {
+    if (warmupInFlight)
+        return warmupInFlight;
+    warmupInFlight = warmupEmbeddingModelImpl(onProgress).finally(() => {
+        warmupInFlight = null;
+    });
+    return warmupInFlight;
+}
+async function warmupEmbeddingModelImpl(onProgress) {
     // Mobile bundle does not ship `node-llama-cpp` (no Android prebuild) and
     // pulling a multi-GB GGUF over a phone's data plan is not acceptable. The
     // mobile path uses `@elizaos/plugin-elizacloud` or a remote provider for
@@ -448,19 +769,20 @@ async function warmupEmbeddingModel(onProgress) {
         logger.info("[eliza] Skipping local embedding warmup — running on mobile (ELIZA_PLATFORM=android|ios)");
         return;
     }
-    if (!shouldWarmupLocalEmbeddingModel()) {
+    const li = await _localInference();
+    if (!li.shouldWarmupLocalEmbeddingModel()) {
         logger.info("[eliza] Skipping local embedding (GGUF) warmup — not needed for this configuration (e.g. Eliza Cloud embeddings, or local embeddings disabled).");
         return;
     }
     const config = loadElizaConfig();
     upstreamConfigureLocalEmbeddingPlugin({}, config);
-    const preset = detectEmbeddingPreset();
-    const modelsDir = process.env.MODELS_DIR ?? DEFAULT_MODELS_DIR;
+    const preset = li.detectEmbeddingPreset();
+    const modelsDir = process.env.MODELS_DIR ?? li.DEFAULT_MODELS_DIR;
     let model = process.env.LOCAL_EMBEDDING_MODEL?.trim() || preset.model;
     let modelRepo = process.env.LOCAL_EMBEDDING_MODEL_REPO?.trim() || preset.modelRepo;
-    if (!isEmbeddingWarmupReuseDisabled() &&
-        !embeddingGgufFilePresent(modelsDir, model)) {
-        const reuse = findExistingEmbeddingModelForWarmupReuse(modelsDir);
+    if (!li.isEmbeddingWarmupReuseDisabled() &&
+        !li.embeddingGgufFilePresent(modelsDir, model)) {
+        const reuse = li.findExistingEmbeddingModelForWarmupReuse(modelsDir);
         if (reuse) {
             logger.info(`[eliza] Embedding warmup: configured file "${model}" not found in MODELS_DIR — reusing existing ${reuse.model} to avoid a large re-download. ` +
                 "Set LOCAL_EMBEDDING_MODEL or ELIZA_EMBEDDING_WARMUP_NO_REUSE=1 to force the configured model.");
@@ -478,7 +800,7 @@ async function warmupEmbeddingModel(onProgress) {
     logger.info(`[eliza] Local embedding warmup: ${model} (hardware tier preset: ${preset.label}). ` +
         "This file is for TEXT_EMBEDDING / memory only (not your conversation model).");
     const progressCb = (phase, detail) => {
-        updateStartupEmbeddingProgress(phase, detail);
+        updateStartupEmbeddingProgress(phase, typeof detail === "string" ? detail : undefined);
         // Always log to stdout for server/container monitoring
         if (phase === "downloading") {
             logger.info(`[eliza] Embedding model: ${detail ?? "downloading..."}`);
@@ -493,27 +815,69 @@ async function warmupEmbeddingModel(onProgress) {
         onProgress?.(phase, detail);
     };
     try {
-        await ensureModel(modelsDir, modelRepo, model, false, progressCb);
+        await li.ensureModel(modelsDir, modelRepo, model, false, progressCb);
     }
     catch (err) {
         // Non-fatal: the plugin will attempt its own download on first use
-        logger.warn(`[eliza] Embedding model warmup failed (will retry on first use): ${err instanceof Error ? err.message : String(err)}`);
+        logger.warn(`[eliza] Embedding model warmup failed (will retry on first use): ${formatError(err)}`);
     }
 }
+/**
+ * Warm local voice models (Whisper STT + Kokoro TTS) in the background AFTER
+ * the runtime is ready, by firing one tiny useModel request at each. Voice
+ * models only load through the live runtime (the Kokoro bridge auto-starts on
+ * the first TEXT_TO_SPEECH call), so unlike embedding — which warms pre-boot
+ * via a runtime-free facade — this runs post-ready. Fire-and-forget; gated to
+ * the local-inference path so cloud-only setups never make a paid TTS/STT call.
+ */
+async function startDeferredVoiceWarmup(runtime) {
+    if (!shouldWarmupVoice({
+        mobile: isMobilePlatform(),
+        skipEnv: isTruthyEnvValue(process.env.ELIZA_SKIP_LOCAL_VOICE_WARMUP),
+        hotReload: isTruthyEnvValue(process.env.ELIZA_DEV_IS_HOT_RELOAD),
+    })) {
+        return;
+    }
+    logger.info("[eliza] Starting deferred voice warmup");
+    await warmVoiceModels(runtime, {
+        ttsType: ModelType.TEXT_TO_SPEECH,
+        transcriptionType: ModelType.TRANSCRIPTION,
+    }, {
+        info: (m) => logger.info(m),
+        warn: (m) => logger.warn(m),
+    });
+}
 export async function bootElizaRuntime(opts = {}) {
     syncAppEnvToEliza();
     try {
         // Eagerly download the embedding model before the full runtime boot.
         // This way the TUI loading screen (or server logs) can show download
         // progress instead of the app silently stalling on first embedding call.
-        await warmupEmbeddingModel(opts.onEmbeddingProgress);
-        // Cap embedding dimension to 384 — plugin-sql's DIMENSION_MAP only
-        // supports up to 3072, and the performance-tier E5-Mistral-7B model
-        // outputs 4096-dim vectors which would silently fall back to 384 anyway.
+        // Fire-and-forget: warmupEmbeddingModelImpl declares "non-fatal: will
+        // retry on first use" semantics, and self-serializes via the module-level
+        // warmupInFlight singleton. Awaiting it here parked bootstrap on sticky
+        // HF 401 → multi-URL fallback chains with no overall deadline; the API
+        // port never bound and dev-ui.mjs's 300s watchdog tore the stack down
+        // (W-016). Voiding lets bootstrap proceed; the renderer's startup overlay
+        // still surfaces progress via updateStartupEmbeddingProgress.
+        if (isLocalEmbeddingWarmupDeferredByEnv()) {
+            logger.info("[eliza] Deferring local embedding warmup until runtime ready");
+        }
+        else {
+            startLocalEmbeddingWarmup(opts.onEmbeddingProgress);
+        }
+        // Default the embedding-vector dimension plugin-sql provisions to 384 when
+        // unset: that is the compact SQL-safe column and the native width of the
+        // standalone gte-small embedding model. Setting it here lets plugin-sql
+        // provision the column without a boot-time model probe (see core
+        // provisioning). An explicit EMBEDDING_DIMENSION — a different local model,
+        // the desktop Eliza-1 sidecar's Matryoshka width, or cloud embeddings —
+        // still wins.
         if (!process.env.EMBEDDING_DIMENSION) {
             process.env.EMBEDDING_DIMENSION = "384";
         }
         const runtime = await upstreamBootElizaRuntime(opts);
+        // Voice warmup fires inside repairRuntimeAfterBoot (the shared ready-point).
         return runtime ? await repairRuntimeAfterBoot(runtime) : runtime;
     }
     finally {
@@ -571,6 +935,19 @@ function isManualResetPgliteError(err) {
             normalized.includes("migrations._migrations")) {
             return true;
         }
+        // PGlite is an Emscripten/WASM build of Postgres. When the embedded
+        // postmaster hits an unrecoverable internal state — most commonly a
+        // corrupt on-disk pgdata directory from a previous crash, an
+        // unsupported syscall, or pg_logical/WAL replay failure — Emscripten
+        // calls `abort()` and surfaces it as an Error whose message starts
+        // with `Aborted(). Build with -sASSERTIONS for more info.` That bare
+        // string carries no PGlite-specific marker, so the older heuristics
+        // above never matched and the dev-server retried forever against the
+        // same poisoned data dir. Treat it as a recoverable corruption signal:
+        // the auto-reset path quarantines the .elizadb dir and retries once.
+        if (normalized.includes("aborted()")) {
+            return true;
+        }
         return false;
     });
 }
@@ -607,7 +984,7 @@ function resolveManagedPgliteDataDir() {
         return resolveUserPath(configuredDataDir);
     }
     const workspaceDir = config.agents?.defaults?.workspace ?? resolveDefaultAgentWorkspaceDir();
-    return path.join(resolveUserPath(workspaceDir), ".eliza", ".elizadb");
+    return path.join(resolveUserPath(workspaceDir), ".elizadb");
 }
 function isAutoResettablePgliteDir(dataDir) {
     return typeof dataDir === "string" && path.basename(dataDir) === ".elizadb";
@@ -631,7 +1008,7 @@ async function resetPluginSqlPgliteSingleton(context) {
             ]);
         }
         catch (err) {
-            logger.warn(`[eliza] ${context}: failed to close plugin-sql PGlite singleton: ${err instanceof Error ? err.message : String(err)}`);
+            logger.warn(`[eliza] ${context}: failed to close plugin-sql PGlite singleton: ${formatError(err)}`);
         }
         finally {
             if (timeoutHandle) {
@@ -674,8 +1051,7 @@ function normalizePgliteStartupError(err) {
         return err;
     }
     const dataDir = getPgliteDataDirFromError(err) ?? resolveManagedPgliteDataDir();
-    const detail = collectErrorMessages(err)[0] ??
-        (err instanceof Error ? err.message : String(err));
+    const detail = collectErrorMessages(err)[0] ?? formatError(err);
     const wrapped = new Error(dataDir
         ? `PGlite initialization failed for ${dataDir}: ${detail}. Stop the app, then rename or delete only this directory before retrying: ${dataDir}`
         : `PGlite initialization failed: ${detail}. Stop the app, then rename or delete only the managed PGlite data directory before retrying.`, { cause: err });
@@ -720,46 +1096,100 @@ export async function startEliza(options) {
     if (orchRaw !== "0" && orchRaw !== "false" && orchRaw !== "no") {
         process.env.ELIZA_AGENT_ORCHESTRATOR = "1";
     }
+    // Install the compat-route http.createServer wrapper BEFORE the upstream
+    // agent's bootElizaRuntime path (which calls upstream startApiServer →
+    // http.createServer at packages/agent/src/runtime/eliza.ts ~3984). The
+    // upstream call binds the port and creates the listener that will receive
+    // every request from the renderer; if our patch isn't already in place,
+    // /api/tts/local-inference, /api/database, /api/runtime/mode, and every
+    // other compat-dispatcher path 404 because the wrapper never runs on the
+    // active listener. The app-core `startApiServer` wrapper (line ~1188 of
+    // ../api/server.ts) ALSO installs the patch, but that's too late — the
+    // upstream listener is already bound by then.
+    //
+    // The patch falls back to a module-scoped singleton state when called
+    // without an explicit one; `startApiServer` later seeds that same
+    // singleton with the live runtime via its `server.updateRuntime` wrapper,
+    // so the early listener picks up the runtime as soon as it's available.
     try {
-        // Eagerly download the embedding model with progress reporting
-        await warmupEmbeddingModel(options?.onEmbeddingProgress);
+        patchHttpCreateServerForCompat();
+        const earlyCompatState = getSharedCompatRuntimeState();
+        // Eagerly download the embedding model with progress reporting.
+        // Fire-and-forget — see comment at the matching call in bootElizaRuntime
+        // (W-016): awaiting parks bootstrap; voiding lets the API port bind on
+        // time while the warmup runs alongside.
+        if (isLocalEmbeddingWarmupDeferredByEnv()) {
+            logger.info("[eliza] Deferring local embedding warmup until runtime ready");
+        }
+        else {
+            startLocalEmbeddingWarmup(options?.onEmbeddingProgress);
+        }
         // Cap embedding dimension to 384 — see comment in bootElizaRuntime.
         if (!process.env.EMBEDDING_DIMENSION) {
             process.env.EMBEDDING_DIMENSION = "384";
         }
         if (options?.serverOnly) {
-            let currentRuntime = (await upstreamStartElizaWithPgliteCompat({
-                ...options,
-                headless: true,
-                serverOnly: false,
-            })) ?? undefined;
-            currentRuntime = currentRuntime
-                ? await repairRuntimeAfterBoot(currentRuntime)
-                : currentRuntime;
-            if (!currentRuntime) {
-                return currentRuntime;
+            bootLap("startEliza:serverOnly entry");
+            let currentRuntime;
+            // Boot (or re-boot) the runtime headless + repair, and hand the live
+            // runtime to the early-installed compat wrapper so `/api/tts/*`,
+            // `/api/database`, `/api/runtime/mode`, and every other compat-dispatcher
+            // path can resolve. Without the latter, `state.current` stays null and
+            // `handleCompatRoute` short-circuits. Used for the initial async boot AND
+            // the `/api/agent/restart` handler.
+            const bootServerOnlyRuntime = async () => {
+                const booted = (await upstreamStartElizaWithPgliteCompat({
+                    ...options,
+                    headless: true,
+                    serverOnly: false,
+                })) ?? undefined;
+                const repaired = booted ? await repairRuntimeAfterBoot(booted) : booted;
+                earlyCompatState.current = repaired ?? null;
+                return repaired;
+            };
+            // Desktop launcher sets ELIZA_API_PORT (default 31337) to match the
+            // renderer's hardcoded API base; honor it when present. CLI/server-only
+            // mode (no ELIZA_API_PORT) keeps the legacy `resolveServerOnlyPort`
+            // default (2138) so this change is transparent for non-desktop users.
+            const apiPort = process.env.ELIZA_API_PORT
+                ? resolveDesktopApiPort(process.env)
+                : resolveServerOnlyPort(process.env);
+            let actualApiPort;
+            let updateRuntime;
+            let updateStartup;
+            bootLap("startEliza:before startApiServer (config/registry/embedding setup done)");
+            try {
+                // Bind the API server FIRST with no runtime yet (state "starting"), so
+                // the desktop webview connects + hydrates in PARALLEL with the heavier
+                // agent boot instead of waiting the full boot. The runtime is wired in
+                // via updateRuntime once it finishes booting below. Mirrors the
+                // dev-server's bind-first orchestration.
+                const startedApiServer = await startApiServer({
+                    port: apiPort,
+                    initialAgentState: "starting",
+                    onRestart: async () => {
+                        if (currentRuntime) {
+                            await upstreamShutdownRuntime(currentRuntime, "server-only restart");
+                        }
+                        currentRuntime = await bootServerOnlyRuntime();
+                        return currentRuntime ?? null;
+                    },
+                });
+                actualApiPort = startedApiServer.port;
+                updateRuntime = startedApiServer.updateRuntime;
+                updateStartup = startedApiServer.updateStartup;
+            }
+            catch (apiErr) {
+                const apiErrMsg = apiErr instanceof Error
+                    ? (apiErr.stack ?? apiErr.message)
+                    : String(apiErr);
+                logger.error(`[eliza] API server failed to start: ${apiErrMsg}`);
+                console.error(apiErrMsg);
+                if (options?.serverOnly) {
+                    process.exit(1);
+                }
+                throw apiErr;
             }
-            const { startApiServer } = await import("../api/server");
-            const apiPort = resolveServerOnlyPort(process.env);
-            const { port: actualApiPort } = await startApiServer({
-                port: apiPort,
-                runtime: currentRuntime,
-                onRestart: async () => {
-                    if (!currentRuntime) {
-                        return null;
-                    }
-                    await upstreamShutdownRuntime(currentRuntime, "server-only restart");
-                    const restarted = (await upstreamStartElizaWithPgliteCompat({
-                        ...options,
-                        headless: true,
-                        serverOnly: false,
-                    })) ?? undefined;
-                    currentRuntime = restarted
-                        ? await repairRuntimeAfterBoot(restarted)
-                        : undefined;
-                    return currentRuntime ?? null;
-                },
-            });
             // WHY: `startApiServer` may bind a different port than requested (busy
             // socket, upstream policy). Shells, scripts, and follow-up code reading
             // env must match the real listener or health checks and user-facing URLs
@@ -768,14 +1198,35 @@ export async function startEliza(options) {
                 overwriteUiPort: true,
             });
             // Invalidate cached CORS port set so the new port is allowed.
-            try {
-                const { invalidateCorsAllowedPorts } = await import("../api/server-cors.js");
-                invalidateCorsAllowedPorts();
-            }
-            catch { }
-            logger.info(`[eliza] API server listening on http://localhost:${actualApiPort}`);
+            // server-cors is statically imported at the top of this module — the
+            // previous dynamic import was INEFFECTIVE_DYNAMIC_IMPORT.
+            invalidateCorsAllowedPorts();
+            logger.info(`[eliza] API server listening on http://localhost:${actualApiPort} (agent booting…)`);
             console.log(`[eliza] Control UI: http://localhost:${actualApiPort}`);
+            bootLap("startEliza:API bound (webview can connect, ready:false)");
+            // Now boot the runtime; the API is already reachable (state "starting"),
+            // so the UI is connecting + hydrating while this runs, then flips to
+            // "running" once the agent is ready.
+            currentRuntime = await bootServerOnlyRuntime();
+            if (!currentRuntime) {
+                updateStartup?.({ phase: "error", state: "error" });
+                return currentRuntime;
+            }
+            updateRuntime?.(currentRuntime);
+            updateStartup?.({ phase: "running", attempt: 0, state: "running" });
+            bootLap("startEliza:runtime booted + ready:true");
             console.log("[eliza] Server running. Press Ctrl+C to stop.");
+            const { buildSandboxRegistryFromEnv } = await import("../services/sandbox-registry.js");
+            const sandboxRegistry = buildSandboxRegistryFromEnv();
+            if (sandboxRegistry) {
+                try {
+                    await sandboxRegistry.register();
+                }
+                catch (err) {
+                    logger.error(`[eliza] Failed to register sandbox in Redis (gateways will not route inbound platform messages here until the next heartbeat succeeds): ${formatError(err)}`);
+                }
+                sandboxRegistry.startHeartbeat(30_000);
+            }
             const keepAlive = setInterval(() => { }, 1 << 30);
             let isCleaningUp = false;
             const cleanup = async () => {
@@ -789,8 +1240,17 @@ export async function startEliza(options) {
                     logger.warn("[eliza] Shutdown timed out after 10s — forcing exit");
                     process.exit(1);
                 }, 10_000);
-                forceExitTimer.unref?.();
+                forceExitTimer.unref();
                 stopTelegramBotPolling("SIGINT");
+                if (sandboxRegistry) {
+                    sandboxRegistry.stopHeartbeat();
+                    try {
+                        await sandboxRegistry.unregister();
+                    }
+                    catch (err) {
+                        logger.warn(`[eliza] Sandbox unregister failed (keys will expire via TTL): ${formatError(err)}`);
+                    }
+                }
                 if (currentRuntime) {
                     await upstreamShutdownRuntime(currentRuntime, "server-only shutdown");
                 }
@@ -815,13 +1275,27 @@ export async function startEliza(options) {
             return currentRuntime;
         }
         const runtime = await upstreamStartElizaWithPgliteCompat(options);
-        return runtime ? await repairRuntimeAfterBoot(runtime) : runtime;
+        const repaired = runtime ? await repairRuntimeAfterBoot(runtime) : runtime;
+        // Same wiring as the serverOnly branch above — hand the live runtime to
+        // the early-installed compat wrapper so its dispatcher engages.
+        if (repaired) {
+            earlyCompatState.current = repaired;
+        }
+        return repaired;
     }
     finally {
         syncElizaEnvAliases();
     }
 }
 function isDirectRuntimeRun() {
+    if (globalThis
+        .__ELIZA_MOBILE_BUNDLE__ === true ||
+        globalThis
+            .__ELIZA_DISABLE_DIRECT_RUN === true ||
+        process.argv.includes("ios-bridge") ||
+        process.env.ELIZA_DISABLE_DIRECT_RUN === "1") {
+        return false;
+    }
     const scriptArg = process.argv[1];
     if (!scriptArg) {
         return false;
@@ -856,7 +1330,7 @@ if (isDirectRuntimeRun()) {
     }
     else {
         startEliza().catch((err) => {
-            console.error("[eliza] Fatal error:", err instanceof Error ? (err.stack ?? err.message) : err);
+            console.error("[eliza] Fatal error:", formatErrorWithStack(err));
             process.exit(1);
         });
     }