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

package/platforms/electrobun/src/native/agent.ts

@@ -17,11 +17,10 @@
  * remote -- it simply connects to `http://localhost:{port}`.
  *
  * **Port policy (WHY):** we resolve a **free** loopback desktop API port from
- * `ELIZA_API_PORT`, `ELIZA_API_PORT`, or `ELIZA_PORT` (see
- * `findFirstAvailableLoopbackPort`) instead of SIGKILL-ing listeners by
- * default, so two desktop apps can run side by side. Optional
- * `ELIZA_AGENT_RECLAIM_STALE_PORT=1` (legacy: `ELIZA_AGENT_RECLAIM_STALE_PORT`)
- * restores lsof-based reclaim for single-instance dev.
+ * `ELIZA_API_PORT` or `ELIZA_PORT` (see `findFirstAvailableLoopbackPort`)
+ * instead of SIGKILL-ing listeners by default, so two desktop apps can run
+ * side by side. Optional `ELIZA_AGENT_RECLAIM_STALE_PORT=1` restores
+ * lsof-based reclaim for single-instance dev.
  */
 
 import crypto from "node:crypto";
@@ -29,65 +28,82 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import {
-	resolveApiToken,
-	resolveDesktopApiPort,
-	resolveDisableAutoApiToken,
-	setApiToken,
+  resolveApiToken,
+  resolveDesktopApiPort,
+  resolveDisableAutoApiToken,
+  setApiToken,
 } from "@elizaos/shared";
 import { Utils } from "electrobun/bun";
 import { resolveDesktopRuntimeMode } from "../api-base";
 import { getBrandConfig } from "../brand-config";
 import { DEFAULT_API_PORT } from "../constants";
+import {
+  acquireDatabaseStartupLock,
+  applyDatabaseResolutionToEnv,
+  backupPgliteDirectory,
+  classifyDatabaseError,
+  createDatabaseSnapshot,
+  createUnknownDatabaseSnapshot,
+  type DatabaseSnapshot,
+  type DatabaseStartupLock,
+  ensurePgliteDataDir,
+  redactDatabaseTarget,
+  resetPgliteDirectory,
+  resolveDatabaseMode,
+  updateDatabaseSnapshotStatus,
+} from "../database";
 import { logger } from "../logger";
 import { recordStartupPhase, resolveStartupBundlePath } from "../startup-trace";
 import type { SendToWebview } from "../types.js";
 import { findFirstAvailableLoopbackPort } from "./loopback-port";
+import { applyBundledWhisperEnv } from "./whisper-env";
 
 // ---------------------------------------------------------------------------
 // Types
 // ---------------------------------------------------------------------------
 
 interface AgentStatus {
-	state: "not_started" | "starting" | "running" | "stopped" | "error";
-	agentName: string | null;
-	port: number | null;
-	startedAt: number | null;
-	error: string | null;
+  state: "not_started" | "starting" | "running" | "stopped" | "error";
+  agentName: string | null;
+  port: number | null;
+  startedAt: number | null;
+  error: string | null;
 }
 
 export interface StartupDiagnosticsSnapshot {
-	state: AgentStatus["state"];
-	phase: string;
-	updatedAt: string;
-	lastError: string | null;
-	agentName: string | null;
-	port: number | null;
-	startedAt: number | null;
-	platform: string;
-	arch: string;
-	configDir: string;
-	logPath: string;
-	statusPath: string;
+  state: AgentStatus["state"];
+  phase: string;
+  updatedAt: string;
+  lastError: string | null;
+  agentName: string | null;
+  port: number | null;
+  startedAt: number | null;
+  platform: string;
+  arch: string;
+  configDir: string;
+  logPath: string;
+  statusPath: string;
+  database: DatabaseSnapshot;
 }
 
 export interface BugReportBundleResult {
-	directory: string;
-	reportMarkdownPath: string;
-	reportJsonPath: string;
-	startupLogPath: string | null;
-	startupStatusPath: string | null;
+  directory: string;
+  reportMarkdownPath: string;
+  reportJsonPath: string;
+  startupLogPath: string | null;
+  startupStatusPath: string | null;
 }
 
 import type {
-	ExistingElizaInstallInfo,
-	ExistingElizaInstallSource,
-	StateDirMigrationResult,
+  ExistingElizaInstallInfo,
+  ExistingElizaInstallSource,
+  StateDirMigrationResult,
 } from "../rpc-schema";
 
 export type {
-	ExistingElizaInstallInfo,
-	ExistingElizaInstallSource,
-	StateDirMigrationResult,
+  ExistingElizaInstallInfo,
+  ExistingElizaInstallSource,
+  StateDirMigrationResult,
 };
 
 // Subprocess type from Bun.spawn
@@ -104,283 +120,408 @@ const WINDOWS_ABS_PATH_RE = /^[A-Za-z]:[\\/]/;
 const ELIZA_CONFIG_FILENAME = "eliza.json";
 
 export function getHealthPollTimeoutMs(
-	env: NodeJS.ProcessEnv = process.env,
-	platform: string = process.platform,
+  env: NodeJS.ProcessEnv = process.env,
+  platform: string = process.platform,
 ): number {
-	const raw = env.ELIZA_AGENT_HEALTH_TIMEOUT_MS?.trim();
-	if (raw) {
-		const parsed = Number.parseInt(raw, 10);
-		if (Number.isFinite(parsed) && parsed > 0) {
-			return parsed;
-		}
-	}
-
-	// Windows packaged first-run startup can include PGLite initialization plus
-	// a GGUF embedding model download before /api/health comes online.
-	return platform === "win32" ? 240_000 : 120_000;
+  const raw = env.ELIZA_AGENT_HEALTH_TIMEOUT_MS?.trim();
+  if (raw) {
+    const parsed = Number.parseInt(raw, 10);
+    if (Number.isFinite(parsed) && parsed > 0) {
+      return parsed;
+    }
+  }
+
+  // Windows packaged first-run startup can include PGLite initialization plus
+  // a GGUF embedding model download before /api/health comes online.
+  return platform === "win32" ? 240_000 : 120_000;
 }
 
 function isPosixAbsolutePath(value: string): boolean {
-	return value.startsWith("/") && !WINDOWS_ABS_PATH_RE.test(value);
+  return value.startsWith("/") && !WINDOWS_ABS_PATH_RE.test(value);
 }
 
 function resolvePortablePath(value: string): string {
-	if (isPosixAbsolutePath(value) || WINDOWS_ABS_PATH_RE.test(value)) {
-		return value;
-	}
-	return path.resolve(value);
+  if (isPosixAbsolutePath(value) || WINDOWS_ABS_PATH_RE.test(value)) {
+    return value;
+  }
+  return path.resolve(value);
 }
 
 function dirnamePortable(value: string): string {
-	return isPosixAbsolutePath(value)
-		? path.posix.dirname(value)
-		: path.dirname(value);
+  return isPosixAbsolutePath(value)
+    ? path.posix.dirname(value)
+    : path.dirname(value);
 }
 
 function joinPortable(base: string, ...parts: string[]): string {
-	return isPosixAbsolutePath(base)
-		? path.posix.join(base, ...parts)
-		: path.join(base, ...parts);
+  return isPosixAbsolutePath(base)
+    ? path.posix.join(base, ...parts)
+    : path.join(base, ...parts);
 }
 
 function resolveRelativePortable(base: string, relativePath: string): string {
-	return isPosixAbsolutePath(base)
-		? path.posix.resolve(base, relativePath)
-		: path.resolve(base, relativePath);
+  return isPosixAbsolutePath(base)
+    ? path.posix.resolve(base, relativePath)
+    : path.resolve(base, relativePath);
 }
 
 function getDefaultModuleDir(): string {
-	return import.meta.dir ?? path.join(process.cwd(), "src");
+  return import.meta.dir;
 }
 
 function normalizeEnvPath(value: string | undefined): string | null {
-	const trimmed = value?.trim();
-	return trimmed ? resolvePortablePath(trimmed) : null;
+  const trimmed = value?.trim();
+  return trimmed ? resolvePortablePath(trimmed) : null;
 }
 
 function isStoreBuildVariant(env: NodeJS.ProcessEnv = process.env): boolean {
-	const raw =
-		env.MILADY_BUILD_VARIANT?.trim() || env.ELIZA_BUILD_VARIANT?.trim();
-	return raw?.toLowerCase() === "store";
+  const raw = env.ELIZA_BUILD_VARIANT?.trim();
+  return raw?.toLowerCase() === "store";
+}
+
+function resolveBrandAwareNamespace(
+  envNamespace: string | undefined,
+  brandNamespace = getBrandConfig().namespace || "eliza",
+): string {
+  const trimmed = envNamespace?.trim();
+  if (!trimmed) return brandNamespace;
+  if (trimmed === "eliza" && brandNamespace !== "eliza") return brandNamespace;
+  return trimmed;
 }
 
 function resolveStateNamespace(env: NodeJS.ProcessEnv = process.env): string {
-	return env.ELIZA_NAMESPACE?.trim() || getBrandConfig().namespace || "eliza";
+  return resolveBrandAwareNamespace(env.ELIZA_NAMESPACE);
+}
+
+export function resolveDesktopChildNamespace(
+  env: Record<string, string | undefined>,
+  brandNamespace?: string,
+): string {
+  return resolveBrandAwareNamespace(env.ELIZA_NAMESPACE, brandNamespace);
 }
 
 function resolveExplicitStateDir(env: NodeJS.ProcessEnv): string | null {
-	return (
-		normalizeEnvPath(env.MILADY_STATE_DIR) ??
-		normalizeEnvPath(env.ELIZA_STATE_DIR)
-	);
+  return normalizeEnvPath(env.ELIZA_STATE_DIR);
+}
+
+function isTruthyDesktopEnv(value: string | undefined): boolean {
+  const normalized = value?.trim().toLowerCase();
+  return normalized === "1" || normalized === "true" || normalized === "yes";
+}
+
+export function applyPackagedStartupEmbeddingWarmupPolicy(
+  childEnv: Record<string, string>,
+  packagedRuntime: boolean,
+): void {
+  if (!packagedRuntime) {
+    return;
+  }
+
+  const explicitSkip = childEnv.ELIZA_SKIP_LOCAL_EMBEDDING_WARMUP?.trim();
+  if (explicitSkip) {
+    childEnv.ELIZA_SKIP_LOCAL_EMBEDDING_WARMUP = explicitSkip;
+    return;
+  }
+
+  if (
+    isTruthyDesktopEnv(childEnv.ELIZA_ENABLE_STARTUP_LOCAL_EMBEDDING_WARMUP)
+  ) {
+    return;
+  }
+
+  childEnv.ELIZA_SKIP_LOCAL_EMBEDDING_WARMUP = "1";
+}
+
+/**
+ * Default the desktop-spawned agent to deferring the post-ready boot tail so
+ * `/api/health` flips `ready:true` (and the renderer reaches first paint /
+ * usable chat) before app-route plugins, training hooks, sensitive-request
+ * adapters, the trigger bridge, the connector catalog, and voice warmup finish.
+ *
+ * The trade-off is a brief window after "ready" where feature routes registered
+ * by app-route plugins (e.g. lifeops/steward/training) can 404 until the
+ * background tail completes — acceptable on desktop where first paint latency is
+ * far more visible than a sub-second feature-route gap.
+ *
+ * Only sets the default when `ELIZA_DEFER_APP_ROUTES` is unset, so an explicit
+ * `0`/`1` from the user or a test harness always wins. The production CLI
+ * `serve` path (not spawned here) is untouched and keeps the awaited-inline tail.
+ */
+export function applyDesktopDeferAppRoutesPolicy(
+  childEnv: Record<string, string>,
+): void {
+  if (childEnv.ELIZA_DEFER_APP_ROUTES?.trim()) {
+    return;
+  }
+  childEnv.ELIZA_DEFER_APP_ROUTES = "1";
+}
+
+export function prependDesktopChildPathDirectory(
+  childEnv: Record<string, string | undefined>,
+  directory: string,
+): boolean {
+  const existingPathKey =
+    childEnv.PATH !== undefined
+      ? "PATH"
+      : childEnv.Path !== undefined
+        ? "Path"
+        : "PATH";
+  const existingPath = childEnv[existingPathKey]?.trim();
+  if (!existingPath) {
+    childEnv[existingPathKey] = directory;
+    return true;
+  }
+  if (existingPath.split(path.delimiter).includes(directory)) {
+    return false;
+  }
+  childEnv[existingPathKey] = `${directory}${path.delimiter}${existingPath}`;
+  return true;
 }
 
 function resolveStoreUserDataStateDir(): string {
-	const userData = Utils.paths.userData || resolveConfigDir();
-	return path.join(userData, "state");
+  const userData = Utils.paths.userData || resolveConfigDir();
+  return path.join(userData, "state");
+}
+
+function resolveXdgStateHome(opts?: {
+  env?: NodeJS.ProcessEnv;
+  homedir?: string;
+}): string {
+  const env = opts?.env ?? process.env;
+  const explicit = normalizeEnvPath(env.XDG_STATE_HOME);
+  if (explicit) return explicit;
+  return joinPortable(opts?.homedir ?? os.homedir(), ".local", "state");
+}
+
+function resolveDefaultDesktopStateDir(opts?: {
+  env?: NodeJS.ProcessEnv;
+  homedir?: string;
+}): string {
+  const env = opts?.env ?? process.env;
+  return joinPortable(resolveXdgStateHome(opts), resolveStateNamespace(env));
+}
+
+function resolveLegacyDotStateDir(opts?: {
+  env?: NodeJS.ProcessEnv;
+  homedir?: string;
+}): string {
+  return joinPortable(
+    opts?.homedir ?? os.homedir(),
+    `.${resolveStateNamespace(opts?.env ?? process.env)}`,
+  );
 }
 
 export function resolveDesktopChildStateDir(opts?: {
-	env?: NodeJS.ProcessEnv;
-	homedir?: string;
+  env?: NodeJS.ProcessEnv;
+  homedir?: string;
 }): string {
-	const env = opts?.env ?? process.env;
-	const explicit = resolveExplicitStateDir(env);
-	if (explicit) return explicit;
-	if (isStoreBuildVariant(env)) return resolveStoreUserDataStateDir();
-	return joinPortable(
-		opts?.homedir ?? os.homedir(),
-		`.${resolveStateNamespace(env)}`,
-	);
+  const env = opts?.env ?? process.env;
+  const explicit = resolveExplicitStateDir(env);
+  if (explicit) return explicit;
+  if (isStoreBuildVariant(env)) return resolveStoreUserDataStateDir();
+  return resolveDefaultDesktopStateDir(opts);
 }
 
 function applyDesktopChildStateEnv(childEnv: Record<string, string>): void {
-	if (!isStoreBuildVariant(childEnv as NodeJS.ProcessEnv)) return;
-	const stateDir = resolveDesktopChildStateDir({
-		env: childEnv as NodeJS.ProcessEnv,
-	});
-	fs.mkdirSync(stateDir, { recursive: true });
-	childEnv.MILADY_STATE_DIR = stateDir;
-	childEnv.ELIZA_STATE_DIR = stateDir;
+  const stateDir = resolveDesktopChildStateDir({
+    env: childEnv as NodeJS.ProcessEnv,
+  });
+  fs.mkdirSync(stateDir, { recursive: true });
+  childEnv.ELIZA_STATE_DIR = stateDir;
+}
+
+export function applyWindowsNativeInferenceDefaults(
+  childEnv: Record<string, string>,
+  platform: NodeJS.Platform = process.platform,
+): void {
+  if (platform !== "win32") return;
+
+  // node-llama-cpp crashes Bun on Windows during packaged startup.
+  // Disable local embeddings until upstream fix lands.
+  childEnv.ELIZA_DISABLE_LOCAL_EMBEDDINGS = "1";
+
+  // The fused elizaOS llama.cpp / OmniVoice runtime can trip GGML's
+  // uncaught-exception backtrace guard inside packaged Bun unless this is set
+  // before any native GGML library is loaded.
+  if (!childEnv.GGML_NO_BACKTRACE?.trim()) {
+    childEnv.GGML_NO_BACKTRACE = "1";
+  }
 }
 
 function listStateEntries(stateDir: string): string[] {
-	try {
-		return fs
-			.readdirSync(stateDir)
-			.filter(
-				(entry) => entry !== "." && entry !== ".." && entry !== ".DS_Store",
-			);
-	} catch {
-		return [];
-	}
+  try {
+    return fs
+      .readdirSync(stateDir)
+      .filter(
+        (entry) => entry !== "." && entry !== ".." && entry !== ".DS_Store",
+      );
+  } catch {
+    return [];
+  }
 }
 
 function buildExistingElizaInstallCandidates(opts?: {
-	env?: NodeJS.ProcessEnv;
-	homedir?: string;
+  env?: NodeJS.ProcessEnv;
+  homedir?: string;
 }): Array<{
-	source: ExistingElizaInstallSource;
-	stateDir: string;
-	configPath: string;
+  source: ExistingElizaInstallSource;
+  stateDir: string;
+  configPath: string;
 }> {
-	const env = opts?.env ?? process.env;
-	const homedir = opts?.homedir ?? os.homedir();
-	const configPathFromEnv =
-		normalizeEnvPath(env.MILADY_CONFIG_PATH) ??
-		normalizeEnvPath(env.ELIZA_CONFIG_PATH);
-	const stateDirFromEnv = resolveExplicitStateDir(env);
-	const defaultStateDir = joinPortable(
-		homedir,
-		`.${resolveStateNamespace(env)}`,
-	);
-
-	const candidates = [
-		configPathFromEnv
-			? {
-					source: "config-path-env" as const,
-					stateDir: dirnamePortable(configPathFromEnv),
-					configPath: configPathFromEnv,
-				}
-			: null,
-		stateDirFromEnv
-			? {
-					source: "state-dir-env" as const,
-					stateDir: stateDirFromEnv,
-					configPath: joinPortable(stateDirFromEnv, ELIZA_CONFIG_FILENAME),
-				}
-			: null,
-		{
-			source: "default-state-dir" as const,
-			stateDir: defaultStateDir,
-			configPath: joinPortable(defaultStateDir, ELIZA_CONFIG_FILENAME),
-		},
-	].filter((candidate): candidate is NonNullable<typeof candidate> =>
-		Boolean(candidate),
-	);
-
-	return candidates.filter(
-		(candidate, index, all) =>
-			all.findIndex(
-				(other) =>
-					other.stateDir === candidate.stateDir &&
-					other.configPath === candidate.configPath,
-			) === index,
-	);
+  const env = opts?.env ?? process.env;
+  const homedir = opts?.homedir ?? os.homedir();
+  const configPathFromEnv = normalizeEnvPath(env.ELIZA_CONFIG_PATH);
+  const stateDirFromEnv = resolveExplicitStateDir(env);
+  const defaultStateDir = resolveDefaultDesktopStateDir({ env, homedir });
+  const legacyStateDir = resolveLegacyDotStateDir({ env, homedir });
+
+  const candidates = [
+    configPathFromEnv
+      ? {
+          source: "config-path-env" as const,
+          stateDir: dirnamePortable(configPathFromEnv),
+          configPath: configPathFromEnv,
+        }
+      : null,
+    stateDirFromEnv
+      ? {
+          source: "state-dir-env" as const,
+          stateDir: stateDirFromEnv,
+          configPath: joinPortable(stateDirFromEnv, ELIZA_CONFIG_FILENAME),
+        }
+      : null,
+    {
+      source: "default-state-dir" as const,
+      stateDir: defaultStateDir,
+      configPath: joinPortable(defaultStateDir, ELIZA_CONFIG_FILENAME),
+    },
+    legacyStateDir !== defaultStateDir
+      ? {
+          source: "legacy-dot-state-dir" as const,
+          stateDir: legacyStateDir,
+          configPath: joinPortable(legacyStateDir, ELIZA_CONFIG_FILENAME),
+        }
+      : null,
+  ].filter((candidate): candidate is NonNullable<typeof candidate> =>
+    Boolean(candidate),
+  );
+
+  return candidates.filter(
+    (candidate, index, all) =>
+      all.findIndex(
+        (other) =>
+          other.stateDir === candidate.stateDir &&
+          other.configPath === candidate.configPath,
+      ) === index,
+  );
 }
 
 export function inspectExistingElizaInstall(opts?: {
-	env?: NodeJS.ProcessEnv;
-	homedir?: string;
+  env?: NodeJS.ProcessEnv;
+  homedir?: string;
 }): ExistingElizaInstallInfo {
-	const candidates = buildExistingElizaInstallCandidates(opts);
-
-	for (const candidate of candidates) {
-		const configExists = fs.existsSync(candidate.configPath);
-		const stateDirExists = fs.existsSync(candidate.stateDir);
-		const hasStateEntries =
-			stateDirExists && listStateEntries(candidate.stateDir).length > 0;
-
-		if (configExists || hasStateEntries) {
-			return {
-				detected: true,
-				stateDir: candidate.stateDir,
-				configPath: candidate.configPath,
-				configExists,
-				stateDirExists,
-				hasStateEntries,
-				source: candidate.source,
-			};
-		}
-	}
-
-	const fallback = candidates[0] ?? {
-		source: "default-state-dir" as const,
-		stateDir: joinPortable(
-			opts?.homedir ?? os.homedir(),
-			`.${resolveStateNamespace(opts?.env ?? process.env)}`,
-		),
-		configPath: joinPortable(
-			joinPortable(
-				opts?.homedir ?? os.homedir(),
-				`.${resolveStateNamespace(opts?.env ?? process.env)}`,
-			),
-			ELIZA_CONFIG_FILENAME,
-		),
-	};
-
-	return {
-		detected: false,
-		stateDir: fallback.stateDir,
-		configPath: fallback.configPath,
-		configExists: false,
-		stateDirExists: fs.existsSync(fallback.stateDir),
-		hasStateEntries: false,
-		source: fallback.source,
-	};
+  const candidates = buildExistingElizaInstallCandidates(opts);
+
+  for (const candidate of candidates) {
+    const configExists = fs.existsSync(candidate.configPath);
+    const stateDirExists = fs.existsSync(candidate.stateDir);
+    const hasStateEntries =
+      stateDirExists && listStateEntries(candidate.stateDir).length > 0;
+
+    if (configExists || hasStateEntries) {
+      return {
+        detected: true,
+        stateDir: candidate.stateDir,
+        configPath: candidate.configPath,
+        configExists,
+        stateDirExists,
+        hasStateEntries,
+        source: candidate.source,
+      };
+    }
+  }
+
+  const fallback = candidates[0] ?? {
+    source: "default-state-dir" as const,
+    stateDir: resolveDefaultDesktopStateDir(opts),
+    configPath: joinPortable(
+      resolveDefaultDesktopStateDir(opts),
+      ELIZA_CONFIG_FILENAME,
+    ),
+  };
+
+  return {
+    detected: false,
+    stateDir: fallback.stateDir,
+    configPath: fallback.configPath,
+    configExists: false,
+    stateDirExists: fs.existsSync(fallback.stateDir),
+    hasStateEntries: false,
+    source: fallback.source,
+  };
 }
 
 export function migrateDesktopStateDirFromPath(
-	fromPath: string,
-	opts?: { env?: NodeJS.ProcessEnv },
+  fromPath: string,
+  opts?: { env?: NodeJS.ProcessEnv },
 ): StateDirMigrationResult {
-	const source = resolvePortablePath(fromPath);
-	const target = resolveDesktopChildStateDir({ env: opts?.env ?? process.env });
-
-	if (source === target) {
-		return {
-			ok: true,
-			migrated: false,
-			fromPath: source,
-			toPath: target,
-			skippedReason: "same-path",
-		};
-	}
-
-	try {
-		const stat = fs.statSync(source);
-		if (!stat.isDirectory()) {
-			return {
-				ok: true,
-				migrated: false,
-				fromPath: source,
-				toPath: target,
-				skippedReason: "source-not-directory",
-			};
-		}
-	} catch {
-		return {
-			ok: true,
-			migrated: false,
-			fromPath: source,
-			toPath: target,
-			skippedReason: "source-missing",
-		};
-	}
-
-	try {
-		fs.mkdirSync(target, { recursive: true });
-		fs.cpSync(source, target, {
-			recursive: true,
-			force: false,
-			errorOnExist: false,
-			dereference: false,
-		});
-		return {
-			ok: true,
-			migrated: true,
-			fromPath: source,
-			toPath: target,
-		};
-	} catch (err) {
-		return {
-			ok: false,
-			migrated: false,
-			fromPath: source,
-			toPath: target,
-			error: err instanceof Error ? err.message : String(err),
-		};
-	}
+  const source = resolvePortablePath(fromPath);
+  const target = resolveDesktopChildStateDir({ env: opts?.env ?? process.env });
+
+  if (source === target) {
+    return {
+      ok: true,
+      migrated: false,
+      fromPath: source,
+      toPath: target,
+      skippedReason: "same-path",
+    };
+  }
+
+  try {
+    const stat = fs.statSync(source);
+    if (!stat.isDirectory()) {
+      return {
+        ok: true,
+        migrated: false,
+        fromPath: source,
+        toPath: target,
+        skippedReason: "source-not-directory",
+      };
+    }
+  } catch {
+    return {
+      ok: true,
+      migrated: false,
+      fromPath: source,
+      toPath: target,
+      skippedReason: "source-missing",
+    };
+  }
+
+  try {
+    fs.mkdirSync(target, { recursive: true });
+    fs.cpSync(source, target, {
+      recursive: true,
+      force: false,
+      errorOnExist: false,
+      dereference: false,
+    });
+    return {
+      ok: true,
+      migrated: true,
+      fromPath: source,
+      toPath: target,
+    };
+  } catch (err) {
+    return {
+      ok: false,
+      migrated: false,
+      fromPath: source,
+      toPath: target,
+      error: err instanceof Error ? err.message : String(err),
+    };
+  }
 }
 
 // ---------------------------------------------------------------------------
@@ -396,268 +537,269 @@ export function migrateDesktopStateDirFromPath(
  * to mock process globals.
  */
 export function resolveConfigDir(opts?: {
-	platform?: string;
-	appdata?: string;
-	homedir?: string;
+  platform?: string;
+  appdata?: string;
+  homedir?: string;
 }): string {
-	const platform = opts?.platform ?? process.platform;
-	const homedir = opts?.homedir ?? os.homedir();
-	const dirName = getBrandConfig().configDirName;
-	if (platform === "win32") {
-		const roaming =
-			opts?.appdata ??
-			process.env.APPDATA ??
-			joinPortable(homedir, "AppData", "Roaming");
-		return joinPortable(roaming, dirName);
-	}
-	return joinPortable(homedir, ".config", dirName);
+  const platform = opts?.platform ?? process.platform;
+  const homedir = opts?.homedir ?? os.homedir();
+  const dirName = getBrandConfig().configDirName;
+  if (platform === "win32") {
+    const roaming =
+      opts?.appdata ??
+      process.env.APPDATA ??
+      joinPortable(homedir, "AppData", "Roaming");
+    return joinPortable(roaming, dirName);
+  }
+  return joinPortable(homedir, ".config", dirName);
 }
 
 export function ensureDesktopApiToken(
-	env: NodeJS.ProcessEnv = process.env,
+  env: NodeJS.ProcessEnv = process.env,
 ): string {
-	const existingToken = resolveApiToken(env);
-	if (existingToken) {
-		setApiToken(env, existingToken);
-		return existingToken;
-	}
-
-	if (resolveDisableAutoApiToken(env)) {
-		return "";
-	}
-
-	const generated = crypto.randomBytes(16).toString("hex");
-	setApiToken(env, generated);
-	return generated;
+  const existingToken = resolveApiToken(env);
+  if (existingToken) {
+    setApiToken(env, existingToken);
+    return existingToken;
+  }
+
+  if (resolveDisableAutoApiToken(env)) {
+    return "";
+  }
+
+  const generated = crypto.randomBytes(16).toString("hex");
+  setApiToken(env, generated);
+  return generated;
 }
 
 export function configureDesktopLocalApiAuth(
-	env: NodeJS.ProcessEnv = process.env,
+  env: NodeJS.ProcessEnv = process.env,
 ): string {
-	const token = ensureDesktopApiToken(env);
-	env.ELIZA_PAIRING_DISABLED = "1";
-	return token;
+  const token = ensureDesktopApiToken(env);
+  env.ELIZA_PAIRING_DISABLED = "1";
+  return token;
 }
 
 function getDesktopApiToken(
-	env: NodeJS.ProcessEnv = process.env,
+  env: NodeJS.ProcessEnv = process.env,
 ): string | null {
-	return resolveApiToken(env);
+  return resolveApiToken(env);
 }
 
 function getDesktopApiHeaders(
-	env: NodeJS.ProcessEnv = process.env,
+  env: NodeJS.ProcessEnv = process.env,
 ): Record<string, string> | undefined {
-	const token = getDesktopApiToken(env);
-	if (!token) return undefined;
-	return {
-		Authorization: `Bearer ${token}`,
-		"X-Api-Key": token,
-		"X-Api-Token": token,
-	};
+  const token = getDesktopApiToken(env);
+  if (!token) return undefined;
+  return {
+    Authorization: `Bearer ${token}`,
+    "X-Api-Key": token,
+    "X-Api-Token": token,
+  };
 }
 
 let diagnosticLogPath: string | null = null;
 let startupStatusPath: string | null = null;
 
 export function getDiagnosticLogPath(): string {
-	if (diagnosticLogPath !== null) return diagnosticLogPath;
-	try {
-		const configDir = resolveConfigDir();
-		if (!fs.existsSync(configDir)) {
-			fs.mkdirSync(configDir, { recursive: true });
-		}
-		diagnosticLogPath = path.join(
-			configDir,
-			getBrandConfig().startupLogFileName,
-		);
-	} catch {
-		// Fallback to temp dir
-		diagnosticLogPath = path.join(
-			os.tmpdir(),
-			getBrandConfig().startupLogFileName,
-		);
-	}
-	return diagnosticLogPath;
+  if (diagnosticLogPath !== null) return diagnosticLogPath;
+  try {
+    const configDir = resolveConfigDir();
+    if (!fs.existsSync(configDir)) {
+      fs.mkdirSync(configDir, { recursive: true });
+    }
+    diagnosticLogPath = path.join(
+      configDir,
+      getBrandConfig().startupLogFileName,
+    );
+  } catch {
+    // Fallback to temp dir
+    diagnosticLogPath = path.join(
+      os.tmpdir(),
+      getBrandConfig().startupLogFileName,
+    );
+  }
+  return diagnosticLogPath;
 }
 
 export function getStartupStatusPath(): string {
-	if (startupStatusPath !== null) return startupStatusPath;
-	try {
-		const configDir = resolveConfigDir();
-		if (!fs.existsSync(configDir)) {
-			fs.mkdirSync(configDir, { recursive: true });
-		}
-		startupStatusPath = path.join(configDir, "startup-status.json");
-	} catch {
-		startupStatusPath = path.join(os.tmpdir(), "startup-status.json");
-	}
-	return startupStatusPath;
+  if (startupStatusPath !== null) return startupStatusPath;
+  try {
+    const configDir = resolveConfigDir();
+    if (!fs.existsSync(configDir)) {
+      fs.mkdirSync(configDir, { recursive: true });
+    }
+    startupStatusPath = path.join(configDir, "startup-status.json");
+  } catch {
+    startupStatusPath = path.join(os.tmpdir(), "startup-status.json");
+  }
+  return startupStatusPath;
 }
 
 export function diagnosticLog(message: string): void {
-	const timestamp = new Date().toISOString();
-	const line = `[${timestamp}] ${message}\n`;
-	console.log(message);
-	try {
-		const logPath = getDiagnosticLogPath();
-		fs.appendFileSync(logPath, line);
-	} catch {
-		// Ignore write errors
-	}
+  const timestamp = new Date().toISOString();
+  const line = `[${timestamp}] ${message}\n`;
+  console.log(message);
+  try {
+    const logPath = getDiagnosticLogPath();
+    fs.appendFileSync(logPath, line);
+  } catch {
+    // Ignore write errors
+  }
 }
 
 /** One-line, truncated error string safe for UI (status.error). */
 function shortError(err: unknown, maxLen = 280): string {
-	const raw =
-		err instanceof Error
-			? err.message || (err.stack ?? String(err))
-			: String(err);
-	const oneLine = raw.replace(/\s+/g, " ").trim();
-	if (oneLine.length <= maxLen) return oneLine;
-	return `${oneLine.slice(0, maxLen)}... (see logs for full details)`;
+  const raw =
+    err instanceof Error
+      ? err.message || (err.stack ?? String(err))
+      : String(err);
+  const oneLine = raw.replace(/\s+/g, " ").trim();
+  if (oneLine.length <= maxLen) return oneLine;
+  return `${oneLine.slice(0, maxLen)}... (see logs for full details)`;
 }
 
 export function redactSensitiveDiagnostics(input: string): string {
-	return input
-		.replace(
-			/(authorization\s*[:=]\s*bearer\s+)([a-z0-9._-]+)/gi,
-			"$1[REDACTED]",
-		)
-		.replace(
-			/((?:x-api-key|x-api-token|api[_-]?key|bearer[_-]?token|access[_-]?token|secret|password)\s*[:=]\s*)([^\s]+)/gi,
-			"$1[REDACTED]",
-		);
+  return input
+    .replace(
+      /(authorization\s*[:=]\s*bearer\s+)([a-z0-9._-]+)/gi,
+      "$1[REDACTED]",
+    )
+    .replace(
+      /((?:x-api-key|x-api-token|api[_-]?key|bearer[_-]?token|access[_-]?token|secret|password)\s*[:=]\s*)([^\s]+)/gi,
+      "$1[REDACTED]",
+    );
 }
 
 function readFileTail(filePath: string, maxChars = 16_000): string {
-	try {
-		const content = fs.readFileSync(filePath, "utf8");
-		return redactSensitiveDiagnostics(content.slice(-maxChars));
-	} catch {
-		return "";
-	}
+  try {
+    const content = fs.readFileSync(filePath, "utf8");
+    return redactSensitiveDiagnostics(content.slice(-maxChars));
+  } catch {
+    return "";
+  }
 }
 
 function writeStartupDiagnosticsSnapshot(
-	snapshot: StartupDiagnosticsSnapshot,
+  snapshot: StartupDiagnosticsSnapshot,
 ): void {
-	try {
-		fs.writeFileSync(
-			getStartupStatusPath(),
-			`${JSON.stringify(snapshot, null, 2)}\n`,
-			"utf8",
-		);
-	} catch {
-		// Ignore write errors
-	}
+  try {
+    fs.writeFileSync(
+      getStartupStatusPath(),
+      `${JSON.stringify(snapshot, null, 2)}\n`,
+      "utf8",
+    );
+  } catch {
+    // Ignore write errors
+  }
 }
 
 export function getStartupDiagnosticsSnapshot(): StartupDiagnosticsSnapshot {
-	let parsed: Partial<StartupDiagnosticsSnapshot> | null = null;
-	try {
-		parsed = JSON.parse(
-			fs.readFileSync(getStartupStatusPath(), "utf8"),
-		) as Partial<StartupDiagnosticsSnapshot> | null;
-	} catch {
-		parsed = null;
-	}
-
-	return {
-		state: parsed?.state ?? "not_started",
-		phase: parsed?.phase ?? "unknown",
-		updatedAt: parsed?.updatedAt ?? new Date().toISOString(),
-		lastError: parsed?.lastError ?? null,
-		agentName: parsed?.agentName ?? null,
-		port: parsed?.port ?? null,
-		startedAt: parsed?.startedAt ?? null,
-		platform: parsed?.platform ?? process.platform,
-		arch: parsed?.arch ?? process.arch,
-		configDir: parsed?.configDir ?? resolveConfigDir(),
-		logPath: parsed?.logPath ?? getDiagnosticLogPath(),
-		statusPath: parsed?.statusPath ?? getStartupStatusPath(),
-	};
+  let parsed: Partial<StartupDiagnosticsSnapshot> | null = null;
+  try {
+    parsed = JSON.parse(
+      fs.readFileSync(getStartupStatusPath(), "utf8"),
+    ) as Partial<StartupDiagnosticsSnapshot> | null;
+  } catch {
+    parsed = null;
+  }
+
+  return {
+    state: parsed?.state ?? "not_started",
+    phase: parsed?.phase ?? "unknown",
+    updatedAt: parsed?.updatedAt ?? new Date().toISOString(),
+    lastError: parsed?.lastError ?? null,
+    agentName: parsed?.agentName ?? null,
+    port: parsed?.port ?? null,
+    startedAt: parsed?.startedAt ?? null,
+    platform: parsed?.platform ?? process.platform,
+    arch: parsed?.arch ?? process.arch,
+    configDir: parsed?.configDir ?? resolveConfigDir(),
+    logPath: parsed?.logPath ?? getDiagnosticLogPath(),
+    statusPath: parsed?.statusPath ?? getStartupStatusPath(),
+    database: parsed?.database ?? createUnknownDatabaseSnapshot(),
+  };
 }
 
 export function getStartupDiagnosticLogTail(maxChars = 16_000): string {
-	return readFileTail(getDiagnosticLogPath(), maxChars);
+  return readFileTail(getDiagnosticLogPath(), maxChars);
 }
 
 function sanitizeBugReportPrefix(prefix: string | undefined): string {
-	const trimmed = prefix?.trim();
-	if (!trimmed) return "bug-report";
-
-	const sanitized = trimmed
-		.replace(/[\\/]+/g, "-")
-		.replace(/\.\.+/g, "-")
-		.replace(/[^a-zA-Z0-9._-]+/g, "-")
-		.replace(/-+/g, "-")
-		.replace(/^[._-]+|[._-]+$/g, "")
-		.slice(0, 64);
-
-	return sanitized || "bug-report";
+  const trimmed = prefix?.trim();
+  if (!trimmed) return "bug-report";
+
+  const sanitized = trimmed
+    .replace(/[\\/]+/g, "-")
+    .replace(/\.\.+/g, "-")
+    .replace(/[^a-zA-Z0-9._-]+/g, "-")
+    .replace(/-+/g, "-")
+    .replace(/^[._-]+|[._-]+$/g, "")
+    .slice(0, 64);
+
+  return sanitized || "bug-report";
 }
 export function createBugReportBundle(options: {
-	reportMarkdown: string;
-	reportJson: Record<string, unknown>;
-	prefix?: string;
+  reportMarkdown: string;
+  reportJson: Record<string, unknown>;
+  prefix?: string;
 }): BugReportBundleResult {
-	const configDir = resolveConfigDir();
-	const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
-	const prefix = sanitizeBugReportPrefix(options.prefix);
-	const directory = path.join(
-		configDir,
-		"bug-reports",
-		`${prefix}-${timestamp}`,
-	);
-	const reportMarkdownPath = path.join(directory, "report.md");
-	const reportJsonPath = path.join(directory, "report.json");
-	const logPath = getDiagnosticLogPath();
-	const statusPath = getStartupStatusPath();
-	const startupLogTarget = path.join(
-		directory,
-		getBrandConfig().startupLogFileName,
-	);
-	const startupStatusTarget = path.join(directory, "startup-status.json");
-	const startupDiagnostics = getStartupDiagnosticsSnapshot();
-	const includeLogTail =
-		typeof options.reportJson.attachLogs === "boolean"
-			? options.reportJson.attachLogs
-			: true;
-	const startupLogTail = includeLogTail ? getStartupDiagnosticLogTail() : "";
-	const normalizedReportJson = {
-		...options.reportJson,
-		startupDiagnostics,
-		startupLogTail,
-	};
-
-	fs.mkdirSync(directory, { recursive: true });
-	fs.writeFileSync(reportMarkdownPath, options.reportMarkdown, "utf8");
-	fs.writeFileSync(
-		reportJsonPath,
-		`${JSON.stringify(normalizedReportJson, null, 2)}\n`,
-		"utf8",
-	);
-
-	let copiedLogPath: string | null = null;
-	let copiedStatusPath: string | null = null;
-
-	if (fs.existsSync(logPath)) {
-		fs.copyFileSync(logPath, startupLogTarget);
-		copiedLogPath = startupLogTarget;
-	}
-	if (fs.existsSync(statusPath)) {
-		fs.copyFileSync(statusPath, startupStatusTarget);
-		copiedStatusPath = startupStatusTarget;
-	}
-
-	return {
-		directory,
-		reportMarkdownPath,
-		reportJsonPath,
-		startupLogPath: copiedLogPath,
-		startupStatusPath: copiedStatusPath,
-	};
+  const configDir = resolveConfigDir();
+  const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
+  const prefix = sanitizeBugReportPrefix(options.prefix);
+  const directory = path.join(
+    configDir,
+    "bug-reports",
+    `${prefix}-${timestamp}`,
+  );
+  const reportMarkdownPath = path.join(directory, "report.md");
+  const reportJsonPath = path.join(directory, "report.json");
+  const logPath = getDiagnosticLogPath();
+  const statusPath = getStartupStatusPath();
+  const startupLogTarget = path.join(
+    directory,
+    getBrandConfig().startupLogFileName,
+  );
+  const startupStatusTarget = path.join(directory, "startup-status.json");
+  const startupDiagnostics = getStartupDiagnosticsSnapshot();
+  const includeLogTail =
+    typeof options.reportJson.attachLogs === "boolean"
+      ? options.reportJson.attachLogs
+      : true;
+  const startupLogTail = includeLogTail ? getStartupDiagnosticLogTail() : "";
+  const normalizedReportJson = {
+    ...options.reportJson,
+    startupDiagnostics,
+    startupLogTail,
+  };
+
+  fs.mkdirSync(directory, { recursive: true });
+  fs.writeFileSync(reportMarkdownPath, options.reportMarkdown, "utf8");
+  fs.writeFileSync(
+    reportJsonPath,
+    `${JSON.stringify(normalizedReportJson, null, 2)}\n`,
+    "utf8",
+  );
+
+  let copiedLogPath: string | null = null;
+  let copiedStatusPath: string | null = null;
+
+  if (fs.existsSync(logPath)) {
+    fs.copyFileSync(logPath, startupLogTarget);
+    copiedLogPath = startupLogTarget;
+  }
+  if (fs.existsSync(statusPath)) {
+    fs.copyFileSync(statusPath, startupStatusTarget);
+    copiedStatusPath = startupStatusTarget;
+  }
+
+  return {
+    directory,
+    reportMarkdownPath,
+    reportJsonPath,
+    startupLogPath: copiedLogPath,
+    startupStatusPath: copiedStatusPath,
+  };
 }
 
 // ---------------------------------------------------------------------------
@@ -672,255 +814,260 @@ export function createBugReportBundle(options: {
  *   2. Walk up from import.meta.dir to find the runtime dist dir as a sibling
  */
 export function getRuntimeDistFallbackCandidates(
-	moduleDir: string = getDefaultModuleDir(),
-	execPath: string = process.execPath,
+  moduleDir: string = getDefaultModuleDir(),
+  execPath: string = process.execPath,
 ): string[] {
-	const execDir = execPath ? dirnamePortable(execPath) : moduleDir;
-	const distDir = getBrandConfig().runtimeDistDirName;
-
-	return [
-		// macOS: inside .app bundle (Contents/Resources/app/<dist>)
-		resolveRelativePortable(execDir, `../Resources/app/${distDir}`),
-		// Windows NSIS/portable: resources/app/<dist> next to exe
-		resolveRelativePortable(execDir, `resources/app/${distDir}`),
-		resolveRelativePortable(execDir, `../resources/app/${distDir}`),
-		resolveRelativePortable(moduleDir, `app/${distDir}`),
-		resolveRelativePortable(moduleDir, `../${distDir}`),
-		resolveRelativePortable(moduleDir, `../app/${distDir}`),
-		resolveRelativePortable(moduleDir, `../../../${distDir}`),
-		// Legacy eliza-dist fallback for existing packaged builds
-		resolveRelativePortable(execDir, "../Resources/app/eliza-dist"),
-		resolveRelativePortable(execDir, "resources/app/eliza-dist"),
-		resolveRelativePortable(moduleDir, "../eliza-dist"),
-		resolveRelativePortable(moduleDir, "../../../eliza-dist"),
-	].filter((candidate, index, all) => all.indexOf(candidate) === index);
+  const execDir = execPath ? dirnamePortable(execPath) : moduleDir;
+  const distDir = getBrandConfig().runtimeDistDirName;
+
+  return [
+    // macOS: inside .app bundle (Contents/Resources/app/<dist>)
+    resolveRelativePortable(execDir, `../Resources/app/${distDir}`),
+    // Windows NSIS/portable: resources/app/<dist> next to exe
+    resolveRelativePortable(execDir, `resources/app/${distDir}`),
+    resolveRelativePortable(execDir, `../resources/app/${distDir}`),
+    resolveRelativePortable(moduleDir, `app/${distDir}`),
+    resolveRelativePortable(moduleDir, `../${distDir}`),
+    resolveRelativePortable(moduleDir, `../app/${distDir}`),
+    resolveRelativePortable(moduleDir, `../../../${distDir}`),
+    // Legacy eliza-dist fallback for existing packaged builds
+    resolveRelativePortable(execDir, "../Resources/app/eliza-dist"),
+    resolveRelativePortable(execDir, "resources/app/eliza-dist"),
+    resolveRelativePortable(moduleDir, "../eliza-dist"),
+    resolveRelativePortable(moduleDir, "../../../eliza-dist"),
+  ].filter((candidate, index, all) => all.indexOf(candidate) === index);
 }
 
 export function isPackagedDesktopRuntime(
-	moduleDir: string = getDefaultModuleDir(),
-	execPath: string = process.execPath,
+  moduleDir: string = getDefaultModuleDir(),
+  execPath: string = process.execPath,
 ): boolean {
-	const normalizedModuleDir = moduleDir.replaceAll("\\", "/");
-	const normalizedExecPath = execPath.replaceAll("\\", "/").toLowerCase();
-	const looksLikePackagedExec =
-		normalizedExecPath.includes(".app/contents/") ||
-		normalizedExecPath.includes("/self-extraction/") ||
-		normalizedExecPath.endsWith("/launcher") ||
-		normalizedExecPath.endsWith("/launcher.exe");
-	if (process.env.ELIZA_DIST_PATH?.trim() && !looksLikePackagedExec) {
-		return false;
-	}
-	if (!normalizedModuleDir.includes("/src/")) {
-		return true;
-	}
-
-	return looksLikePackagedExec;
+  const normalizedModuleDir = moduleDir.replaceAll("\\", "/");
+  const normalizedExecPath = execPath.replaceAll("\\", "/").toLowerCase();
+  const looksLikePackagedExec =
+    normalizedExecPath.includes(".app/contents/") ||
+    normalizedExecPath.includes("/self-extraction/") ||
+    normalizedExecPath.endsWith("/launcher") ||
+    normalizedExecPath.endsWith("/launcher.exe");
+  if (process.env.ELIZA_DIST_PATH?.trim() && !looksLikePackagedExec) {
+    return false;
+  }
+  if (!normalizedModuleDir.includes("/src/")) {
+    return true;
+  }
+
+  return looksLikePackagedExec;
 }
 
 export function resolveBunExecutablePath(opts?: {
-	execPath?: string;
-	moduleDir?: string;
-	platform?: string;
+  execPath?: string;
+  moduleDir?: string;
+  platform?: string;
 }): string {
-	const execPath = opts?.execPath ?? process.execPath;
-	const moduleDir = opts?.moduleDir ?? getDefaultModuleDir();
-	const platform = opts?.platform ?? process.platform;
-	const packagedRuntime = isPackagedDesktopRuntime(moduleDir, execPath);
-	const looksLikeMacBundleExec = execPath.includes(".app/Contents/MacOS/");
-	const executableName =
-		platform === "win32" && !looksLikeMacBundleExec ? "bun.exe" : "bun";
-	const execDir = execPath ? dirnamePortable(execPath) : "";
-	const packagedCandidates = [
-		execPath,
-		execDir ? joinPortable(execDir, executableName) : "",
-		execDir
-			? resolveRelativePortable(
-					execDir,
-					`../Resources/app/bun/${executableName}`,
-				)
-			: "",
-		execDir
-			? resolveRelativePortable(
-					execDir,
-					`../Resources/app/bun/bin/${executableName}`,
-				)
-			: "",
-		moduleDir ? joinPortable(moduleDir, executableName) : "",
-		moduleDir ? joinPortable(moduleDir, "bin", executableName) : "",
-		moduleDir
-			? resolveRelativePortable(moduleDir, `../bun/${executableName}`)
-			: "",
-		moduleDir
-			? resolveRelativePortable(moduleDir, `../bun/bin/${executableName}`)
-			: "",
-	].filter(Boolean);
-
-	for (const candidate of packagedCandidates) {
-		if (!fs.existsSync(candidate)) continue;
-		if (
-			path.basename(candidate).toLowerCase() === executableName.toLowerCase()
-		) {
-			return candidate;
-		}
-	}
-
-	if (packagedRuntime) {
-		return (
-			packagedCandidates.find(
-				(candidate) =>
-					path.basename(candidate).toLowerCase() ===
-					executableName.toLowerCase(),
-			) ?? executableName
-		);
-	}
-
-	const _candidates = [
-		execPath,
-		execDir ? joinPortable(execDir, executableName) : "",
-	].filter(Boolean);
-
-	const bunGlobal = Bun as { which?: (binary: string) => string | null };
-	const whichCandidate =
-		typeof bunGlobal.which === "function" ? bunGlobal.which("bun") : null;
-	if (whichCandidate) return whichCandidate;
-
-	// Windows: bun is not always on PATH; check well-known install locations.
-	if (process.platform === "win32") {
-		const localAppData =
-			process.env.LOCALAPPDATA ??
-			joinPortable(os.homedir(), "AppData", "Local");
-		const programFiles = process.env.ProgramFiles ?? "C:\\Program Files";
-		const winCandidates = [
-			joinPortable(localAppData, "bun", "bun.exe"),
-			joinPortable(programFiles, "bun", "bun.exe"),
-			joinPortable(os.homedir(), ".bun", "bin", "bun.exe"),
-		];
-		for (const candidate of winCandidates) {
-			if (fs.existsSync(candidate)) return candidate;
-		}
-	}
-
-	return "bun";
+  const execPath = opts?.execPath ?? process.execPath;
+  const moduleDir = opts?.moduleDir ?? getDefaultModuleDir();
+  const platform = opts?.platform ?? process.platform;
+  const packagedRuntime = isPackagedDesktopRuntime(moduleDir, execPath);
+  const looksLikeMacBundleExec = execPath.includes(".app/Contents/MacOS/");
+  const executableName =
+    platform === "win32" && !looksLikeMacBundleExec ? "bun.exe" : "bun";
+  const execDir = execPath ? dirnamePortable(execPath) : "";
+  const packagedCandidates = [
+    execPath,
+    execDir ? joinPortable(execDir, executableName) : "",
+    execDir
+      ? resolveRelativePortable(
+          execDir,
+          `../Resources/app/bun/${executableName}`,
+        )
+      : "",
+    execDir
+      ? resolveRelativePortable(
+          execDir,
+          `../Resources/app/bun/bin/${executableName}`,
+        )
+      : "",
+    moduleDir ? joinPortable(moduleDir, executableName) : "",
+    moduleDir ? joinPortable(moduleDir, "bin", executableName) : "",
+    moduleDir
+      ? resolveRelativePortable(moduleDir, `../bun/${executableName}`)
+      : "",
+    moduleDir
+      ? resolveRelativePortable(moduleDir, `../bun/bin/${executableName}`)
+      : "",
+  ].filter(Boolean);
+
+  for (const candidate of packagedCandidates) {
+    if (!fs.existsSync(candidate)) continue;
+    if (
+      path.basename(candidate).toLowerCase() === executableName.toLowerCase()
+    ) {
+      return candidate;
+    }
+  }
+
+  if (packagedRuntime) {
+    return (
+      packagedCandidates.find(
+        (candidate) =>
+          path.basename(candidate).toLowerCase() ===
+          executableName.toLowerCase(),
+      ) ?? executableName
+    );
+  }
+
+  const _candidates = [
+    execPath,
+    execDir ? joinPortable(execDir, executableName) : "",
+  ].filter(Boolean);
+
+  const bunGlobal = Bun as { which?: (binary: string) => string | null };
+  const whichCandidate =
+    typeof bunGlobal.which === "function" ? bunGlobal.which("bun") : null;
+  if (whichCandidate) return whichCandidate;
+
+  // Windows: bun is not always on PATH; check well-known install locations.
+  if (process.platform === "win32") {
+    const localAppData =
+      process.env.LOCALAPPDATA ??
+      joinPortable(os.homedir(), "AppData", "Local");
+    const programFiles = process.env.ProgramFiles ?? "C:\\Program Files";
+    const winCandidates = [
+      joinPortable(localAppData, "bun", "bun.exe"),
+      joinPortable(programFiles, "bun", "bun.exe"),
+      joinPortable(os.homedir(), ".bun", "bin", "bun.exe"),
+    ];
+    for (const candidate of winCandidates) {
+      if (fs.existsSync(candidate)) return candidate;
+    }
+  }
+
+  return "bun";
 }
 
 export function resolveRuntimeDistPath(opts?: {
-	env?: NodeJS.ProcessEnv;
-	moduleDir?: string;
-	execPath?: string;
+  env?: NodeJS.ProcessEnv;
+  moduleDir?: string;
+  execPath?: string;
 }): string {
-	const env = opts?.env ?? process.env;
-	const moduleDir = opts?.moduleDir ?? getDefaultModuleDir();
-	const execPath = opts?.execPath ?? process.execPath;
-	const packagedRuntime = isPackagedDesktopRuntime(moduleDir, execPath);
-	const distDir = getBrandConfig().runtimeDistDirName;
-	const fallbackCandidates = getRuntimeDistFallbackCandidates(
-		moduleDir,
-		execPath,
-	);
-
-	if (packagedRuntime) {
-		for (const candidate of fallbackCandidates) {
-			if (fs.existsSync(candidate)) {
-				return candidate;
-			}
-		}
-		const fallback = fallbackCandidates[0];
-		diagnosticLog(
-			`[Agent] Could not find packaged runtime dist; using fallback: ${fallback}`,
-		);
-		return fallback;
-	}
-
-	// 1. Env override
-	const envPath = env.ELIZA_DIST_PATH;
-	if (envPath) {
-		const resolved = resolvePortablePath(envPath);
-		if (fs.existsSync(resolved)) {
-			return resolved;
-		}
-		diagnosticLog(
-			`[Agent] ELIZA_DIST_PATH set but does not exist: ${resolved}`,
-		);
-	}
-
-	// 2. Walk up from import.meta.dir looking for runtime dist or dev dist
-	let dir = moduleDir;
-	const maxDepth = 15;
-	for (let i = 0; i < maxDepth; i++) {
-		// Packaged: runtime dist sibling
-		const runtimeDist = joinPortable(dir, distDir);
-		if (fs.existsSync(runtimeDist)) {
-			return runtimeDist;
-		}
-		// Legacy eliza-dist sibling (existing packaged builds)
-		const legacyDist = joinPortable(dir, "eliza-dist");
-		if (fs.existsSync(legacyDist)) {
-			return legacyDist;
-		}
-		// Dev monorepo: dist/ sibling containing the canonical CLI entrypoint
-		const devDist = joinPortable(dir, "dist");
-		if (fs.existsSync(joinPortable(devDist, "entry.js"))) {
-			return devDist;
-		}
-		const parent = dirnamePortable(dir);
-		if (parent === dir) break; // reached filesystem root
-		dir = parent;
-	}
-
-	// 3. Packaged/dev fallbacks derived from the launcher path and module dir.
-	for (const candidate of fallbackCandidates) {
-		if (fs.existsSync(candidate)) {
-			diagnosticLog(
-				`[Agent] Could not find runtime dist by walking up; using fallback: ${candidate}`,
-			);
-			return candidate;
-		}
-	}
-
-	const fallback = fallbackCandidates[0];
-	diagnosticLog(
-		`[Agent] Could not find runtime dist by walking up; using fallback: ${fallback}`,
-	);
-	return fallback;
+  const env = opts?.env ?? process.env;
+  const moduleDir = opts?.moduleDir ?? getDefaultModuleDir();
+  const execPath = opts?.execPath ?? process.execPath;
+  const packagedRuntime = isPackagedDesktopRuntime(moduleDir, execPath);
+  const distDir = getBrandConfig().runtimeDistDirName;
+  const fallbackCandidates = getRuntimeDistFallbackCandidates(
+    moduleDir,
+    execPath,
+  );
+
+  if (packagedRuntime) {
+    for (const candidate of fallbackCandidates) {
+      if (fs.existsSync(candidate)) {
+        return candidate;
+      }
+    }
+    const fallback = fallbackCandidates[0];
+    diagnosticLog(
+      `[Agent] Could not find packaged runtime dist; using fallback: ${fallback}`,
+    );
+    return fallback;
+  }
+
+  // 1. Env override
+  const envPath = env.ELIZA_DIST_PATH;
+  if (envPath) {
+    const resolved = resolvePortablePath(envPath);
+    if (fs.existsSync(resolved)) {
+      return resolved;
+    }
+    diagnosticLog(
+      `[Agent] ELIZA_DIST_PATH set but does not exist: ${resolved}`,
+    );
+  }
+
+  // 2. Walk up from import.meta.dir looking for runtime dist or dev dist
+  let dir = moduleDir;
+  const maxDepth = 15;
+  for (let i = 0; i < maxDepth; i++) {
+    // Packaged: runtime dist sibling
+    const runtimeDist = joinPortable(dir, distDir);
+    if (fs.existsSync(runtimeDist)) {
+      return runtimeDist;
+    }
+    // Legacy eliza-dist sibling (existing packaged builds)
+    const legacyDist = joinPortable(dir, "eliza-dist");
+    if (fs.existsSync(legacyDist)) {
+      return legacyDist;
+    }
+    // Dev monorepo: dist/ sibling containing the canonical CLI entrypoint
+    const devDist = joinPortable(dir, "dist");
+    if (fs.existsSync(joinPortable(devDist, "entry.js"))) {
+      return devDist;
+    }
+    const parent = dirnamePortable(dir);
+    if (parent === dir) break; // reached filesystem root
+    dir = parent;
+  }
+
+  // 3. Packaged/dev fallbacks derived from the launcher path and module dir.
+  for (const candidate of fallbackCandidates) {
+    if (fs.existsSync(candidate)) {
+      diagnosticLog(
+        `[Agent] Could not find runtime dist by walking up; using fallback: ${candidate}`,
+      );
+      return candidate;
+    }
+  }
+
+  const fallback = fallbackCandidates[0];
+  diagnosticLog(
+    `[Agent] Could not find runtime dist by walking up; using fallback: ${fallback}`,
+  );
+  return fallback;
 }
 
 export function buildChildNodePaths(
-	runtimeDistPath: string,
-	opts?: { packagedRuntime?: boolean },
+  runtimeDistPath: string,
+  opts?: { packagedRuntime?: boolean },
 ): string[] {
-	const nodePaths = new Set<string>();
-	const distModules = joinPortable(runtimeDistPath, "node_modules");
-	if (fs.existsSync(distModules)) {
-		nodePaths.add(distModules);
-	}
-
-	if (opts?.packagedRuntime) {
-		return [...nodePaths];
-	}
-
-	let searchDir = runtimeDistPath;
-	while (searchDir !== dirnamePortable(searchDir)) {
-		const candidate = joinPortable(searchDir, "node_modules");
-		if (fs.existsSync(candidate) && candidate !== distModules) {
-			nodePaths.add(candidate);
-			break;
-		}
-		searchDir = dirnamePortable(searchDir);
-	}
-
-	return [...nodePaths];
+  const nodePaths = new Set<string>();
+  const distModules = joinPortable(runtimeDistPath, "node_modules");
+  if (fs.existsSync(distModules)) {
+    nodePaths.add(distModules);
+  }
+
+  if (opts?.packagedRuntime) {
+    return [...nodePaths];
+  }
+
+  let searchDir = runtimeDistPath;
+  while (searchDir !== dirnamePortable(searchDir)) {
+    const candidate = joinPortable(searchDir, "node_modules");
+    if (fs.existsSync(candidate) && candidate !== distModules) {
+      nodePaths.add(candidate);
+      break;
+    }
+    searchDir = dirnamePortable(searchDir);
+  }
+
+  return [...nodePaths];
 }
 
-function resolveRuntimeEntryPath(runtimeDistPath: string): string | null {
-	const candidates = [joinPortable(runtimeDistPath, "entry.js")];
-
-	for (const candidate of candidates) {
-		if (fs.existsSync(candidate)) {
-			return candidate;
-		}
-	}
-
-	return null;
+export function resolveRuntimeEntryPath(
+  runtimeDistPath: string,
+): string | null {
+  const candidates = [
+    joinPortable(runtimeDistPath, "entry.js"),
+    joinPortable(runtimeDistPath, "runtime", "entry.js"),
+  ];
+
+  for (const candidate of candidates) {
+    if (fs.existsSync(candidate)) {
+      return candidate;
+    }
+  }
+
+  return null;
 }
 
 // ---------------------------------------------------------------------------
@@ -928,52 +1075,97 @@ function resolveRuntimeEntryPath(runtimeDistPath: string): string | null {
 // ---------------------------------------------------------------------------
 
 async function waitForHealthy(
-	getPort: () => number,
-	timeoutMs: number = getHealthPollTimeoutMs(),
-	childProcess?: BunSubprocess | null,
+  getPort: () => number,
+  timeoutMs: number = getHealthPollTimeoutMs(),
+  childProcess?: BunSubprocess | null,
+): Promise<boolean> {
+  const deadline = Date.now() + timeoutMs;
+  const headers = getDesktopApiHeaders();
+
+  while (Date.now() < deadline) {
+    // Bail early if the child process has already exited
+    if (childProcess && childProcess.exitCode !== null) {
+      return false;
+    }
+
+    const port = getPort();
+    const url = `http://127.0.0.1:${port}/api/health`;
+    try {
+      const response = await fetch(url, {
+        headers,
+        signal: AbortSignal.timeout(2_000),
+      });
+      if (response.ok) {
+        const health = (await response.json().catch(() => null)) as {
+          ready?: boolean;
+          agentState?: string;
+          startup?: { phase?: string };
+        } | null;
+        if (!health) {
+          return true;
+        }
+        if (typeof health.ready === "boolean") {
+          if (health.ready) {
+            return true;
+          }
+        } else if (
+          health.agentState !== "starting" &&
+          health.agentState !== "restarting"
+        ) {
+          return true;
+        }
+      }
+      if (await isStartupStatusReachable(port, headers)) {
+        return true;
+      }
+    } catch {
+      if (await isStartupStatusReachable(port, headers)) {
+        return true;
+      }
+    }
+    await Bun.sleep(HEALTH_POLL_INTERVAL_MS);
+  }
+  return false;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function isNonFatalStartupStatus(value: unknown): boolean {
+  if (!isRecord(value)) return false;
+  const startup = value.startup;
+  if (!isRecord(startup)) return false;
+  const phase = startup.phase;
+  if (
+    phase === "fatal" ||
+    phase === "startup_failed" ||
+    phase === "runtime_entry_missing"
+  ) {
+    return false;
+  }
+  return (
+    typeof phase === "string" ||
+    typeof startup.embeddingPhase === "string" ||
+    typeof startup.embeddingDetail === "string"
+  );
+}
+
+async function isStartupStatusReachable(
+  port: number,
+  headers: Record<string, string> | undefined,
 ): Promise<boolean> {
-	const deadline = Date.now() + timeoutMs;
-	const headers = getDesktopApiHeaders();
-
-	while (Date.now() < deadline) {
-		// Bail early if the child process has already exited
-		if (childProcess && childProcess.exitCode !== null) {
-			return false;
-		}
-
-		const port = getPort();
-		const url = `http://127.0.0.1:${port}/api/health`;
-		try {
-			const response = await fetch(url, {
-				headers,
-				signal: AbortSignal.timeout(2_000),
-			});
-			if (response.ok) {
-				const health = (await response.json().catch(() => null)) as {
-					ready?: boolean;
-					agentState?: string;
-					startup?: { phase?: string };
-				} | null;
-				if (!health) {
-					return true;
-				}
-				if (typeof health.ready === "boolean") {
-					if (health.ready) {
-						return true;
-					}
-				} else if (
-					health.agentState !== "starting" &&
-					health.agentState !== "restarting"
-				) {
-					return true;
-				}
-			}
-		} catch {
-			// Server not ready yet
-		}
-		await Bun.sleep(HEALTH_POLL_INTERVAL_MS);
-	}
-	return false;
+  try {
+    const response = await fetch(`http://127.0.0.1:${port}/api/status`, {
+      headers,
+      signal: AbortSignal.timeout(2_000),
+    });
+    const body = await response.json().catch(() => null);
+    if (response.ok) return true;
+    return isNonFatalStartupStatus(body);
+  } catch {
+    return false;
+  }
 }
 
 // ---------------------------------------------------------------------------
@@ -981,171 +1173,154 @@ async function waitForHealthy(
 // ---------------------------------------------------------------------------
 
 async function watchStdoutForReady(
-	stream: ReadableStream<Uint8Array>,
-	onLine: (line: string) => void,
-	signal: AbortSignal,
+  stream: ReadableStream<Uint8Array>,
+  onLine: (line: string) => void,
+  signal: AbortSignal,
 ): Promise<void> {
-	const decoder = new TextDecoder();
-	let buffer = "";
-
-	try {
-		const reader = stream.getReader();
-		while (!signal.aborted) {
-			const { done, value } = await reader.read();
-			if (done) break;
-
-			buffer += decoder.decode(value, { stream: true });
-			const lines = buffer.split("\n");
-			buffer = lines.pop() ?? "";
-
-			for (const line of lines) {
-				if (line.trim()) {
-					onLine(line);
-				}
-			}
-		}
-		// Flush remaining buffer
-		if (buffer.trim()) {
-			onLine(buffer);
-		}
-		reader.releaseLock();
-	} catch (err) {
-		if (!signal.aborted) {
-			diagnosticLog(
-				`[Agent] stdout watcher error: ${err instanceof Error ? err.message : String(err)}`,
-			);
-		}
-	}
+  const decoder = new TextDecoder();
+  let buffer = "";
+
+  try {
+    const reader = stream.getReader();
+    while (!signal.aborted) {
+      const { done, value } = await reader.read();
+      if (done) break;
+
+      buffer += decoder.decode(value, { stream: true });
+      const lines = buffer.split("\n");
+      buffer = lines.pop() ?? "";
+
+      for (const line of lines) {
+        if (line.trim()) {
+          onLine(line);
+        }
+      }
+    }
+    // Flush remaining buffer
+    if (buffer.trim()) {
+      onLine(buffer);
+    }
+    reader.releaseLock();
+  } catch (err) {
+    if (!signal.aborted) {
+      diagnosticLog(
+        `[Agent] stdout watcher error: ${err instanceof Error ? err.message : String(err)}`,
+      );
+    }
+  }
 }
 
 async function drainStderrToLog(
-	stream: ReadableStream<Uint8Array>,
-	signal: AbortSignal,
-	onLine?: (line: string) => void,
+  stream: ReadableStream<Uint8Array>,
+  signal: AbortSignal,
+  onLine?: (line: string) => void,
 ): Promise<void> {
-	const decoder = new TextDecoder();
-	let buffer = "";
-
-	try {
-		const reader = stream.getReader();
-		while (!signal.aborted) {
-			const { done, value } = await reader.read();
-			if (done) break;
-
-			buffer += decoder.decode(value, { stream: true });
-			const lines = buffer.split("\n");
-			buffer = lines.pop() ?? "";
-
-			for (const line of lines) {
-				if (line.trim()) {
-					diagnosticLog(`[Agent][stderr] ${line}`);
-					onLine?.(line);
-				}
-			}
-		}
-		if (buffer.trim()) {
-			diagnosticLog(`[Agent][stderr] ${buffer}`);
-			onLine?.(buffer);
-		}
-		reader.releaseLock();
-	} catch (err) {
-		if (!signal.aborted) {
-			diagnosticLog(
-				`[Agent] stderr drain error: ${err instanceof Error ? err.message : String(err)}`,
-			);
-		}
-	}
+  const decoder = new TextDecoder();
+  let buffer = "";
+
+  try {
+    const reader = stream.getReader();
+    while (!signal.aborted) {
+      const { done, value } = await reader.read();
+      if (done) break;
+
+      buffer += decoder.decode(value, { stream: true });
+      const lines = buffer.split("\n");
+      buffer = lines.pop() ?? "";
+
+      for (const line of lines) {
+        if (line.trim()) {
+          diagnosticLog(`[Agent][stderr] ${line}`);
+          onLine?.(line);
+        }
+      }
+    }
+    if (buffer.trim()) {
+      diagnosticLog(`[Agent][stderr] ${buffer}`);
+      onLine?.(buffer);
+    }
+    reader.releaseLock();
+  } catch (err) {
+    if (!signal.aborted) {
+      diagnosticLog(
+        `[Agent] stderr drain error: ${err instanceof Error ? err.message : String(err)}`,
+      );
+    }
+  }
 }
 
 const PGLITE_LOCK_RE =
-	/pglite data dir is already in use|database is locked|lock file already exists/i;
+  /pglite data dir is already in use|database is locked|lock file already exists/i;
 const PGLITE_RECOVERY_RE =
-	/failed query:\s*(?:create schema if not exists|create table if not exists life_)|aborted\(\)\. build with -sassertions|database disk image is malformed|file is not a database|malformed database schema|checksum mismatch|checkpoint failed|wal file/i;
+  /failed query:\s*(?:create schema if not exists|create table if not exists life_)|aborted\(\)\. build with -sassertions|database disk image is malformed|file is not a database|malformed database schema|checksum mismatch|checkpoint failed|wal file/i;
 
 function shouldAutoRecoverPgliteFailure(line: string): boolean {
-	if (PGLITE_LOCK_RE.test(line)) {
-		return false;
-	}
-
-	return (
-		PGLITE_RECOVERY_RE.test(line) ||
-		(/corrupt/i.test(line) && /pglite|sqlite/i.test(line))
-	);
+  if (PGLITE_LOCK_RE.test(line)) {
+    return false;
+  }
+
+  return (
+    PGLITE_RECOVERY_RE.test(line) ||
+    (/corrupt/i.test(line) && /pglite|sqlite/i.test(line))
+  );
 }
 
 /**
  * Opt-in: kill processes listening on `port` (lsof + SIGKILL). Default off so a
  * second desktop instance can coexist on the same machine when ports differ.
- * Set ELIZA_AGENT_RECLAIM_STALE_PORT=1 (legacy: ELIZA_AGENT_RECLAIM_STALE_PORT)
- * to restore the old “take over default port” behavior.
+ * Set ELIZA_AGENT_RECLAIM_STALE_PORT=1 to restore the old "take over default
+ * port" behavior.
  */
 async function maybeReclaimPortWithSigkill(port: number): Promise<void> {
-	const raw = process.env.ELIZA_AGENT_RECLAIM_STALE_PORT?.trim().toLowerCase();
-	if (raw !== "1" && raw !== "true" && raw !== "yes") {
-		return;
-	}
-	try {
-		const lsofResult = Bun.spawnSync(["lsof", "-ti", `tcp:${port}`]);
-		const pids = new TextDecoder()
-			.decode(lsofResult.stdout)
-			.trim()
-			.split("\n")
-			.filter(Boolean);
-		for (const pid of pids) {
-			const numPid = parseInt(pid, 10);
-			if (!Number.isNaN(numPid) && numPid !== process.pid) {
-				diagnosticLog(
-					`[Agent] Reclaim: killing process ${numPid} on port ${port} (ELIZA_AGENT_RECLAIM_STALE_PORT)`,
-				);
-				try {
-					process.kill(numPid, "SIGKILL");
-				} catch {
-					// Process may have already exited
-				}
-			}
-		}
-		if (pids.length > 0) {
-			await new Promise((r) => setTimeout(r, 500));
-		}
-	} catch {
-		// lsof missing — ignore
-	}
-}
-
-function resolvePgliteDataDir(): string {
-	return joinPortable(
-		os.homedir(),
-		`.${getBrandConfig().namespace}`,
-		"workspace",
-		".eliza",
-		".elizadb",
-	);
+  const raw = process.env.ELIZA_AGENT_RECLAIM_STALE_PORT?.trim().toLowerCase();
+  if (raw !== "1" && raw !== "true" && raw !== "yes") {
+    return;
+  }
+  try {
+    const lsofResult = Bun.spawnSync(["lsof", "-ti", `tcp:${port}`]);
+    const pids = new TextDecoder()
+      .decode(lsofResult.stdout)
+      .trim()
+      .split("\n")
+      .filter(Boolean);
+    for (const pid of pids) {
+      const numPid = parseInt(pid, 10);
+      if (!Number.isNaN(numPid) && numPid !== process.pid) {
+        diagnosticLog(
+          `[Agent] Reclaim: killing process ${numPid} on port ${port} (ELIZA_AGENT_RECLAIM_STALE_PORT)`,
+        );
+        try {
+          process.kill(numPid, "SIGKILL");
+        } catch {
+          // Process may have already exited
+        }
+      }
+    }
+    if (pids.length > 0) {
+      await new Promise((r) => setTimeout(r, 500));
+    }
+  } catch {
+    // lsof missing — ignore
+  }
 }
 
-/**
- * Removes only the PGLite database folder (agent memory / conversations).
- * GGUF embedding weights live under `MODELS_DIR` / `~/.eliza/models` by default — never deleted here.
- */
-function deletePgliteDataDir(): void {
-	const dir = resolvePgliteDataDir();
-	if (path.basename(dir) !== ".elizadb") {
-		diagnosticLog(
-			`[Agent] deletePgliteDataDir: refused — basename must be .elizadb, got: ${dir}`,
-		);
-		return;
-	}
-	try {
-		if (fs.existsSync(dir)) {
-			fs.rmSync(dir, { recursive: true, force: true });
-			diagnosticLog(
-				`[Agent] Deleted PGLite data dir (GGUF model cache elsewhere): ${dir}`,
-			);
-		}
-	} catch (err) {
-		diagnosticLog(
-			`[Agent] Failed to delete PGLite data dir: ${err instanceof Error ? err.message : String(err)}`,
-		);
-	}
+function resolveDatabaseAppStateDir(
+  env: NodeJS.ProcessEnv = process.env,
+): string {
+  const stateDir = resolveDesktopChildStateDir({ env });
+  fs.mkdirSync(stateDir, { recursive: true });
+  return stateDir;
+}
+
+function resolveManagedPgliteDataDir(): string | null {
+  const resolution = resolveDatabaseMode({
+    env: process.env as Record<string, string | undefined>,
+    packagedDesktop: isPackagedDesktopRuntime(),
+    appStateDir: resolveDatabaseAppStateDir(process.env),
+  });
+  return resolution.mode === "pglite-persistent"
+    ? (resolution.pgliteDataDir ?? null)
+    : null;
 }
 
 // ---------------------------------------------------------------------------
@@ -1153,800 +1328,1065 @@ function deletePgliteDataDir(): void {
 // ---------------------------------------------------------------------------
 
 export class AgentManager {
-	private sendToWebview: SendToWebview | null = null;
-	private readonly statusListeners = new Set<
-		(status: Readonly<AgentStatus>) => void
-	>();
-	private status: AgentStatus = {
-		state: "not_started",
-		agentName: null,
-		port: null,
-		startedAt: null,
-		error: null,
-	};
-	private childProcess: BunSubprocess | null = null;
-	private stdioAbortController: AbortController | null = null;
-	private hasPgliteError = false;
-	private pgliteRecoveryDone = false;
-	private startupPhase = "not_started";
-
-	constructor() {
-		this.persistStartupDiagnostics();
-	}
-
-	setSendToWebview(fn: SendToWebview): void {
-		this.sendToWebview = fn;
-	}
-
-	onStatusChange(
-		listener: (status: Readonly<AgentStatus>) => void,
-	): () => void {
-		this.statusListeners.add(listener);
-		return () => {
-			this.statusListeners.delete(listener);
-		};
-	}
-
-	/** Start the agent runtime as a child process. Idempotent. */
-	async start(): Promise<AgentStatus> {
-		recordStartupPhase("agent_start_entered", {
-			pid: process.pid,
-			exec_path: process.execPath,
-			bundle_path: resolveStartupBundlePath(process.execPath),
-		});
-		this.setStartupPhase("start_requested");
-		recordStartupPhase("agent_start_entered", {
-			pid: process.pid,
-			exec_path: process.execPath,
-			bundle_path: resolveStartupBundlePath(process.execPath),
-		});
-		diagnosticLog(
-			`[Agent] start() called, current state: ${this.status.state}`,
-		);
-		diagnosticLog(`[Agent] Diagnostic log file: ${getDiagnosticLogPath()}`);
-
-		if (this.status.state === "running" || this.status.state === "starting") {
-			return this.status;
-		}
-
-		const runtimeMode = resolveDesktopRuntimeMode(
-			process.env as Record<string, string | undefined>,
-		);
-		if (runtimeMode.mode !== "local") {
-			const reason =
-				runtimeMode.mode === "external"
-					? `Embedded desktop runtime is disabled because ${runtimeMode.externalApi.source} points at ${runtimeMode.externalApi.base}.`
-					: "Embedded desktop runtime is disabled by ELIZA_DESKTOP_SKIP_EMBEDDED_AGENT=1.";
-			diagnosticLog(`[Agent] ${reason}`);
-			this.setStartupPhase("startup_disabled", reason);
-			throw new Error(reason);
-		}
-
-		let packagedRuntime: boolean;
-		let apiPort: number;
-		let preferredPort: number;
-		try {
-			configureDesktopLocalApiAuth();
-			packagedRuntime = isPackagedDesktopRuntime();
-
-			// Reset per-startup flags
-			this.pgliteRecoveryDone = false;
-
-			// Clean up any stale process before starting
-			if (this.childProcess) {
-				await this.killChildProcess();
-			}
-
-			preferredPort = resolveDesktopApiPort(process.env) || DEFAULT_API_PORT;
-			diagnosticLog(
-				`[Agent] Preferred port: ${preferredPort} (packaged: ${packagedRuntime})`,
-			);
-			if (!packagedRuntime) {
-				await maybeReclaimPortWithSigkill(preferredPort);
-			}
-			apiPort = await findFirstAvailableLoopbackPort(preferredPort);
-		} catch (err) {
-			const msg =
-				err instanceof Error ? err.message : "Failed during pre-startup";
-			diagnosticLog(`[Agent] ${msg}`);
-			this.status = {
-				state: "error",
-				agentName: null,
-				port: null,
-				startedAt: null,
-				error: msg,
-			};
-			recordStartupPhase("fatal", {
-				port: null,
-				error: msg,
-			});
-			this.setStartupPhase("port_allocation_failed", msg);
-			this.emitStatus();
-			return this.status;
-		}
-		if (apiPort !== preferredPort) {
-			diagnosticLog(
-				`[Agent] Port ${preferredPort} busy — using ${apiPort} for embedded API (set ELIZA_AGENT_RECLAIM_STALE_PORT=1 to try reclaiming the preferred port first)`,
-			);
-		}
-		recordStartupPhase("port_selected", {
-			port: apiPort,
-		});
-
-		this.status = {
-			state: "starting",
-			agentName: null,
-			port: null,
-			startedAt: null,
-			error: null,
-		};
-		this.setStartupPhase("starting_runtime");
-		this.emitStatus();
-
-		try {
-			// Resolve the bundled runtime dist path.
-			this.setStartupPhase("resolving_runtime");
-			const runtimeDistPath = resolveRuntimeDistPath();
-			diagnosticLog(`[Agent] Resolved runtime dist: ${runtimeDistPath}`);
-
-			// Packaged builds can expose the runnable entry either at the dist root
-			// or under runtime/. Prefer the root file but accept both layouts.
-			const runtimeEntryPath = resolveRuntimeEntryPath(runtimeDistPath);
-			if (!runtimeEntryPath) {
-				const distExists = fs.existsSync(runtimeDistPath);
-				let contents = "<directory missing>";
-				if (distExists) {
-					try {
-						contents = fs.readdirSync(runtimeDistPath).join(", ");
-					} catch {
-						contents = "<unreadable>";
-					}
-				}
-				const errMsg = `No runnable runtime entry found in ${runtimeDistPath} (checked entry.js; dist exists: ${distExists}, contents: ${contents})`;
-				diagnosticLog(`[Agent] ${errMsg}`);
-				this.status = {
-					state: "error",
-					agentName: null,
-					port: null,
-					startedAt: null,
-					error: errMsg,
-				};
-				recordStartupPhase("fatal", {
-					port: apiPort,
-					error: errMsg,
-				});
-				this.setStartupPhase("runtime_entry_missing", errMsg);
-				recordStartupPhase("fatal", {
-					port: apiPort,
-					error: errMsg,
-				});
-				this.emitStatus();
-				return this.status;
-			}
-
-			diagnosticLog(`[Agent] runtime entry: exists (${runtimeEntryPath})`);
-			recordStartupPhase("runtime_path_resolved", {
-				port: apiPort,
-			});
-
-			diagnosticLog(`[Agent] Starting child process on port ${apiPort}...`);
-			this.setStartupPhase("spawning_runtime");
-
-			// Build NODE_PATH so the child can find node_modules
-			const nodePaths = buildChildNodePaths(runtimeDistPath, {
-				packagedRuntime,
-			});
-			if (packagedRuntime && nodePaths.length === 0) {
-				const errMsg =
-					`Packaged runtime is missing bundle-local node_modules under ${runtimeDistPath}; ` +
-					"refusing to inherit the parent NODE_PATH";
-				diagnosticLog(`[Agent] ${errMsg}`);
-				this.status = {
-					state: "error",
-					agentName: null,
-					port: apiPort,
-					startedAt: null,
-					error: errMsg,
-				};
-				recordStartupPhase("fatal", {
-					port: apiPort,
-					error: errMsg,
-				});
-				this.emitStatus();
-				return this.status;
-			}
-
-			const childEnv: Record<string, string> = {
-				...(process.env as Record<string, string>),
-				ELIZA_API_PORT: String(apiPort),
-				ELIZA_PORT: String(apiPort),
-			};
-			childEnv.ELIZA_NAMESPACE =
-				childEnv.ELIZA_NAMESPACE?.trim() || getBrandConfig().namespace;
-			childEnv.ELIZA_NAMESPACE =
-				childEnv.ELIZA_NAMESPACE?.trim() || childEnv.ELIZA_NAMESPACE;
-			applyDesktopChildStateEnv(childEnv);
-			delete childEnv.ELIZA_PORT;
-			delete childEnv.NODE_PATH;
-
-			// node-llama-cpp crashes Bun on Windows during packaged startup.
-			// Disable local embeddings until upstream fix lands.
-			if (process.platform === "win32") {
-				childEnv.ELIZA_DISABLE_LOCAL_EMBEDDINGS = "1";
-			}
-
-			// Propagate PGlite data dir from parent env so CI/smoke test overrides
-			// (e.g. a short Windows path avoiding MAX_PATH issues) reach the runtime.
-			if (process.env.PGLITE_DATA_DIR) {
-				childEnv.PGLITE_DATA_DIR = process.env.PGLITE_DATA_DIR;
-			}
-
-			if (nodePaths.length > 0) {
-				childEnv.NODE_PATH = nodePaths.join(path.delimiter);
-				diagnosticLog(`[Agent] Child NODE_PATH: ${childEnv.NODE_PATH}`);
-			}
-
-			const bunExecutable = resolveBunExecutablePath();
-			diagnosticLog(`[Agent] Using Bun executable: ${bunExecutable}`);
-			diagnosticLog(
-				`[Agent] Bun exists on disk: ${fs.existsSync(bunExecutable)}`,
-			);
-
-			// Ensure bun's directory is on PATH so child_process.exec calls
-			// (e.g. plugin-manager running `bun add ...`) can find it.
-			const bunDir = path.dirname(bunExecutable);
-			const existingPath = childEnv.PATH ?? "";
-			if (!existingPath.split(path.delimiter).includes(bunDir)) {
-				childEnv.PATH = bunDir + path.delimiter + existingPath;
-				diagnosticLog(`[Agent] Prepended bun dir to child PATH: ${bunDir}`);
-			}
-
-			// Spawn the child process
-			const spawnTime = Date.now();
-			const proc = Bun.spawn(
-				[bunExecutable, "run", runtimeEntryPath, "start"],
-				{
-					cwd: runtimeDistPath,
-					env: childEnv,
-					stdout: "pipe",
-					stderr: "pipe",
-				},
-			);
-
-			this.childProcess = proc;
-			diagnosticLog(
-				`[Agent] Child spawned pid=${proc.pid} elapsed=${Date.now() - spawnTime}ms`,
-			);
-			recordStartupPhase("child_spawned", {
-				port: apiPort,
-				child_pid: proc.pid,
-			});
-
-			// Set up abort controller for stdio watchers
-			this.stdioAbortController = new AbortController();
-			const { signal } = this.stdioAbortController;
-
-			// Surface the port immediately while waiting for ready
-			this.status = {
-				...this.status,
-				port: apiPort,
-			};
-			this.emitStatus();
-
-			// Track whether we detected the "listening" message from stdout
-			let detectedListening = false;
-
-			// Watch stdout for "listening on port" or similar ready messages
-			if (proc.stdout) {
-				watchStdoutForReady(
-					proc.stdout,
-					(line: string) => {
-						diagnosticLog(`[Agent][stdout] ${line}`);
-						const lower = line.toLowerCase();
-						// Parse dynamic port from "[eliza-api] Listening on http://host:PORT"
-						const portMatch = line.match(
-							/Listening on https?:\/\/[^:]+:(\d+)/i,
-						);
-						if (portMatch) {
-							const parsedPort = parseInt(portMatch[1], 10);
-							if (!Number.isNaN(parsedPort) && parsedPort > 0) {
-								if (parsedPort !== apiPort) {
-									diagnosticLog(
-										`[Agent] Server bound to dynamic port ${parsedPort} (requested ${apiPort})`,
-									);
-									apiPort = parsedPort;
-								}
-								detectedListening = true;
-							}
-						} else if (
-							lower.includes("listening on port") ||
-							lower.includes("server started") ||
-							lower.includes("ready on")
-						) {
-							detectedListening = true;
-						}
-						// Update status port so callers see the actual bound port
-						this.status = { ...this.status, port: apiPort };
-						this.emitStatus();
-					},
-					signal,
-				).catch(() => {
-					// Stream ended or aborted -- expected on shutdown
-				});
-			}
-
-			// Drain stderr to diagnostic log; detect PGLite migration failures
-			this.hasPgliteError = false;
-			if (proc.stderr) {
-				drainStderrToLog(proc.stderr, signal, (line) => {
-					if (shouldAutoRecoverPgliteFailure(line)) {
-						this.hasPgliteError = true;
-					}
-				}).catch(() => {
-					// Stream ended or aborted -- expected on shutdown
-				});
-			}
-
-			// Monitor child process exit
-			this.monitorChildExit(proc);
-
-			// Wait for the health endpoint to respond
-			// Use a getter so the health check follows dynamic port reassignment from stdout
-			diagnosticLog(
-				`[Agent] Waiting for health endpoint at http://127.0.0.1:${apiPort}/api/health ...`,
-			);
-			this.setStartupPhase("waiting_for_health");
-			const healthPollTimeoutMs = getHealthPollTimeoutMs();
-			const healthy = await waitForHealthy(
-				() => apiPort,
-				healthPollTimeoutMs,
-				proc,
-			);
-
-			if (!healthy) {
-				// Check if process already exited
-				if (proc.exitCode !== null) {
-					const errMsg = `Child process exited with code ${proc.exitCode} before becoming healthy`;
-					diagnosticLog(`[Agent] ${errMsg}`);
-					this.childProcess = null;
-					this.status = {
-						state: "error",
-						agentName: null,
-						port: apiPort,
-						startedAt: null,
-						error: errMsg,
-					};
-					recordStartupPhase("fatal", {
-						port: apiPort,
-						child_pid: proc.pid,
-						error: errMsg,
-						exit_code: proc.exitCode,
-					});
-					this.setStartupPhase("startup_failed", errMsg);
-					recordStartupPhase("fatal", {
-						port: apiPort,
-						child_pid: proc.pid,
-						error: errMsg,
-						exit_code: proc.exitCode,
-					});
-					this.emitStatus();
-					return this.status;
-				}
-
-				const errMsg = detectedListening
-					? "Server reported listening but health check timed out"
-					: `Health check timed out after ${healthPollTimeoutMs}ms`;
-				diagnosticLog(`[Agent] ${errMsg}`);
-				this.status = {
-					state: "error",
-					agentName: null,
-					port: apiPort,
-					startedAt: null,
-					error: errMsg,
-				};
-				recordStartupPhase("fatal", {
-					port: apiPort,
-					child_pid: proc.pid,
-					error: errMsg,
-				});
-				this.setStartupPhase("startup_failed", errMsg);
-				recordStartupPhase("fatal", {
-					port: apiPort,
-					child_pid: proc.pid,
-					error: errMsg,
-				});
-				this.emitStatus();
-				return this.status;
-			}
-			recordStartupPhase("health_ready", {
-				port: apiPort,
-				child_pid: proc.pid,
-			});
-
-			this.setStartupPhase("fetching_agent_metadata");
-			const startedAt = Date.now();
-			const startupMs = startedAt - spawnTime;
-
-			this.status = {
-				state: "running",
-				agentName: getBrandConfig().appName,
-				port: apiPort,
-				startedAt,
-				error: null,
-			};
-			this.setStartupPhase("ready", null);
-			this.emitStatus();
-			diagnosticLog(
-				`[Agent] Runtime ready -- port: ${apiPort}, pid: ${proc.pid}, startup_ms: ${startupMs}`,
-			);
-			recordStartupPhase("runtime_ready", {
-				port: apiPort,
-				child_pid: proc.pid,
-			});
-			void this.refreshAgentMetadata(proc, apiPort, startupMs);
-			return this.status;
-		} catch (err) {
-			const errMsg =
-				err instanceof Error ? err.stack || err.message : String(err);
-			diagnosticLog(`[Agent] Failed to start: ${errMsg}`);
-			recordStartupPhase("fatal", {
-				port: this.status.port,
-				error: errMsg,
-			});
-
-			// Clean up child if it was spawned
-			if (this.childProcess) {
-				await this.killChildProcess();
-			}
-
-			this.status = {
-				state: "error",
-				agentName: null,
-				port: this.status.port, // preserve port if set
-				startedAt: null,
-				error: shortError(err),
-			};
-			this.setStartupPhase("startup_failed", shortError(err));
-			this.emitStatus();
-			return this.status;
-		}
-	}
-
-	/** Stop the agent runtime. */
-	async stop(): Promise<void> {
-		if (this.status.state !== "running" && this.status.state !== "starting") {
-			return;
-		}
-
-		diagnosticLog("[Agent] Stopping...");
-		this.setStartupPhase("stopping");
-
-		// Abort stdio watchers
-		if (this.stdioAbortController) {
-			this.stdioAbortController.abort();
-			this.stdioAbortController = null;
-		}
-
-		await this.killChildProcess();
-
-		this.status = {
-			state: "stopped",
-			agentName: this.status.agentName,
-			port: null,
-			startedAt: null,
-			error: null,
-		};
-		this.setStartupPhase("stopped", null);
-		this.emitStatus();
-		diagnosticLog("[Agent] Runtime stopped");
-	}
-
-	/**
-	 * Restart the agent runtime -- stops the current instance and starts a
-	 * fresh one, picking up config/plugin changes.
-	 */
-	async restart(): Promise<AgentStatus> {
-		diagnosticLog("[Agent] Restart requested -- stopping current runtime...");
-		this.setStartupPhase("restart_requested");
-		await this.stop();
-		diagnosticLog("[Agent] Restarting...");
-		return this.start();
-	}
-
-	/**
-	 * Used after `POST /api/agent/reset`: stop the child, delete local PGLite
-	 * (conversations / agent memory under `~/.${getBrandConfig().namespace}/workspace/.eliza/.elizadb`),
-	 * then start fresh. Does not remove downloaded **GGUF** models (`MODELS_DIR`,
-	 * default ~/.eliza/models), env-backed wallet keys, or eliza.json (the API
-	 * reset already rewrote config on disk).
-	 *
-	 * When `ELIZA_DESKTOP_API_BASE` points at an external dev API (e.g. :31337),
-	 * the embedded child is never used — this is a no-op so the renderer can
-	 * bounce the real API via `POST /api/agent/restart` instead.
-	 */
-	async restartClearingLocalDb(): Promise<AgentStatus> {
-		const runtimeMode = resolveDesktopRuntimeMode(
-			process.env as Record<string, string | undefined>,
-		);
-		if (runtimeMode.mode !== "local") {
-			diagnosticLog(
-				`[Agent] restartClearingLocalDb skipped — mode=${runtimeMode.mode} externalBase=${runtimeMode.externalApi.base ?? "n/a"} source=${runtimeMode.externalApi.source ?? "n/a"} (renderer uses POST /api/agent/restart)`,
-			);
-			return this.getStatus();
-		}
-
-		diagnosticLog(
-			`[Agent] restartClearingLocalDb: local mode — stop → rm PGLite (${resolvePgliteDataDir()}) → start`,
-		);
-		await this.stop();
-		this.hasPgliteError = false;
-		this.pgliteRecoveryDone = false;
-		deletePgliteDataDir();
-		const next = await this.start();
-		diagnosticLog(
-			`[Agent] restartClearingLocalDb: start() finished state=${next.state} port=${next.port ?? "null"}`,
-		);
-		return next;
-	}
-
-	getStatus(): AgentStatus {
-		return { ...this.status };
-	}
-
-	inspectExistingInstall(): ExistingElizaInstallInfo {
-		return inspectExistingElizaInstall();
-	}
-
-	migrateStateDir(params: { fromPath: string }): StateDirMigrationResult {
-		return migrateDesktopStateDirFromPath(params.fromPath);
-	}
-
-	getPort(): number | null {
-		return this.status.port;
-	}
-
-	/** Clean up on app quit. */
-	async dispose(): Promise<void> {
-		if (this.stdioAbortController) {
-			this.stdioAbortController.abort();
-			this.stdioAbortController = null;
-		}
-		try {
-			await this.killChildProcess();
-		} catch (err) {
-			logger.warn(
-				`[Agent] dispose error: ${err instanceof Error ? err.message : String(err)}`,
-			);
-		}
-	}
-
-	// -----------------------------------------------------------------------
-	// Private helpers
-	// -----------------------------------------------------------------------
-
-	private emitStatus(): void {
-		this.persistStartupDiagnostics();
-		if (this.sendToWebview) {
-			this.sendToWebview("agentStatusUpdate", this.status);
-		}
-		const statusSnapshot = { ...this.status };
-		for (const listener of this.statusListeners) {
-			try {
-				listener(statusSnapshot);
-			} catch (err) {
-				logger.warn(
-					`[Agent] status listener failed: ${err instanceof Error ? err.message : String(err)}`,
-				);
-			}
-		}
-	}
-
-	private async refreshAgentMetadata(
-		proc: BunSubprocess,
-		port: number,
-		startupMs: number,
-	): Promise<void> {
-		const agentName = await this.fetchAgentName(port);
-		if (
-			this.childProcess !== proc ||
-			this.status.state !== "running" ||
-			this.status.port !== port
-		) {
-			return;
-		}
-
-		if (this.status.agentName !== agentName) {
-			this.status = {
-				...this.status,
-				agentName,
-			};
-			this.emitStatus();
-		}
-
-		diagnosticLog(
-			`[Agent] Runtime started -- agent: ${agentName}, port: ${port}, pid: ${proc.pid}, startup_ms: ${startupMs}`,
-		);
-		recordStartupPhase("metadata_ready", {
-			port,
-			child_pid: proc.pid,
-		});
-	}
-	private setStartupPhase(phase: string, lastError?: string | null): void {
-		this.startupPhase = phase;
-		this.persistStartupDiagnostics(lastError);
-	}
-
-	private persistStartupDiagnostics(lastError?: string | null): void {
-		writeStartupDiagnosticsSnapshot({
-			state: this.status.state,
-			phase: this.startupPhase,
-			updatedAt: new Date().toISOString(),
-			lastError: lastError ?? this.status.error,
-			agentName: this.status.agentName,
-			port: this.status.port,
-			startedAt: this.status.startedAt,
-			platform: process.platform,
-			arch: process.arch,
-			configDir: resolveConfigDir(),
-			logPath: getDiagnosticLogPath(),
-			statusPath: getStartupStatusPath(),
-		});
-	}
-
-	/**
-	 * Monitor the child process for unexpected exits and update status.
-	 */
-	private monitorChildExit(proc: BunSubprocess): void {
-		// Bun.spawn provides an `exited` promise that resolves when the process exits
-		proc.exited
-			.then((exitCode: number) => {
-				// Only update status if this is still our active child process
-				if (this.childProcess !== proc) return;
-
-				const wasRunning = this.status.state === "running";
-				const wasStarting = this.status.state === "starting";
-
-				if (wasRunning || wasStarting) {
-					diagnosticLog(
-						`[Agent] Child process exited unexpectedly with code ${exitCode} (pid: ${proc.pid})`,
-					);
-					recordStartupPhase("fatal", {
-						port: this.status.port,
-						child_pid: proc.pid,
-						error: `Process exited unexpectedly with code ${exitCode}`,
-						exit_code: exitCode,
-					});
-					this.childProcess = null;
-
-					// Auto-recover from PGLite migration failures by deleting the DB
-					// and spawning a fresh process (new process = fresh WASM state).
-					if (this.hasPgliteError && !this.pgliteRecoveryDone) {
-						this.pgliteRecoveryDone = true;
-						diagnosticLog(
-							"[Agent] PGLite migration error detected — deleting DB and retrying with fresh process",
-						);
-						deletePgliteDataDir();
-						this.status = {
-							state: "not_started",
-							agentName: null,
-							port: null,
-							startedAt: null,
-							error: null,
-						};
-						this.setStartupPhase("recovering_pglite");
-						// Delay slightly so OS releases file handles before respawn
-						setTimeout(() => void this.start(), 500);
-						return;
-					}
-
-					this.status = {
-						state: "error",
-						agentName: this.status.agentName,
-						port: this.status.port,
-						startedAt: null,
-						error: `Process exited unexpectedly with code ${exitCode}`,
-					};
-					this.setStartupPhase(
-						"process_exited_unexpectedly",
-						`Process exited unexpectedly with code ${exitCode}`,
-					);
-					this.emitStatus();
-				} else {
-					// Expected exit (we called stop)
-					this.childProcess = null;
-				}
-			})
-			.catch((err: unknown) => {
-				if (this.childProcess !== proc) return;
-				diagnosticLog(
-					`[Agent] Child process exited with error: ${err instanceof Error ? err.message : String(err)}`,
-				);
-				recordStartupPhase("fatal", {
-					port: this.status.port,
-					child_pid: proc.pid,
-					error: err instanceof Error ? err.message : String(err),
-				});
-				this.childProcess = null;
-				if (
-					this.status.state === "running" ||
-					this.status.state === "starting"
-				) {
-					this.status = {
-						state: "error",
-						agentName: this.status.agentName,
-						port: this.status.port,
-						startedAt: null,
-						error: shortError(err),
-					};
-					this.setStartupPhase("process_exit_error", shortError(err));
-					this.emitStatus();
-				}
-			});
-	}
-
-	/**
-	 * Kill the child process gracefully with SIGTERM, escalating to SIGKILL
-	 * after a timeout.
-	 */
-	private async killChildProcess(): Promise<void> {
-		const proc = this.childProcess;
-		if (!proc) return;
-
-		this.childProcess = null;
-
-		// Already exited
-		if (proc.exitCode !== null) return;
-
-		diagnosticLog(`[Agent] Sending SIGTERM to pid ${proc.pid}`);
-		proc.kill("SIGTERM");
-
-		// Wait for graceful shutdown or timeout
-		const exited = await Promise.race([
-			proc.exited.then(() => true as const),
-			Bun.sleep(SIGTERM_GRACE_MS).then(() => false as const),
-		]);
-
-		if (!exited) {
-			diagnosticLog(
-				`[Agent] Process did not exit within ${SIGTERM_GRACE_MS}ms, sending SIGKILL`,
-			);
-			try {
-				proc.kill("SIGKILL");
-			} catch {
-				// Process may have already exited between check and kill
-			}
-			// Wait briefly for SIGKILL to take effect
-			await Promise.race([proc.exited.catch(() => {}), Bun.sleep(1_000)]);
-		}
-
-		diagnosticLog("[Agent] Child process terminated");
-	}
-
-	/**
-	 * Attempt to fetch the agent name from the running API server.
-	 * Falls back to the configured desktop app name if the endpoint is unavailable.
-	 */
-	private async fetchAgentName(port: number): Promise<string> {
-		try {
-			const headers = getDesktopApiHeaders();
-			const response = await fetch(`http://127.0.0.1:${port}/api/agents`, {
-				headers,
-				signal: AbortSignal.timeout(AGENT_NAME_FETCH_TIMEOUT_MS),
-			});
-			if (response.ok) {
-				const data = (await response.json()) as
-					| { agents?: Array<{ name?: string }> }
-					| Array<{ name?: string }>;
-				const agents = Array.isArray(data) ? data : data.agents;
-				if (agents && agents.length > 0 && agents[0].name) {
-					return agents[0].name;
-				}
-			}
-		} catch {
-			diagnosticLog("[Agent] Could not fetch agent name, using default");
-		}
-		return getBrandConfig().appName;
-	}
+  private sendToWebview: SendToWebview | null = null;
+  private readonly statusListeners = new Set<
+    (status: Readonly<AgentStatus>) => void
+  >();
+  private status: AgentStatus = {
+    state: "not_started",
+    agentName: null,
+    port: null,
+    startedAt: null,
+    error: null,
+  };
+  private childProcess: BunSubprocess | null = null;
+  private stdioAbortController: AbortController | null = null;
+  private hasPgliteError = false;
+  private pgliteRecoveryDone = false;
+  private startupPhase = "not_started";
+  private databaseSnapshot: DatabaseSnapshot = createUnknownDatabaseSnapshot();
+  private databaseStartupLock: DatabaseStartupLock | null = null;
+
+  constructor() {
+    this.persistStartupDiagnostics();
+  }
+
+  setSendToWebview(fn: SendToWebview): void {
+    this.sendToWebview = fn;
+  }
+
+  onStatusChange(
+    listener: (status: Readonly<AgentStatus>) => void,
+  ): () => void {
+    this.statusListeners.add(listener);
+    return () => {
+      this.statusListeners.delete(listener);
+    };
+  }
+
+  /** Start the agent runtime as a child process. Idempotent. */
+  async start(): Promise<AgentStatus> {
+    recordStartupPhase("agent_start_entered", {
+      pid: process.pid,
+      exec_path: process.execPath,
+      bundle_path: resolveStartupBundlePath(process.execPath),
+    });
+    this.setStartupPhase("start_requested");
+    recordStartupPhase("agent_start_entered", {
+      pid: process.pid,
+      exec_path: process.execPath,
+      bundle_path: resolveStartupBundlePath(process.execPath),
+    });
+    diagnosticLog(
+      `[Agent] start() called, current state: ${this.status.state}`,
+    );
+    diagnosticLog(`[Agent] Diagnostic log file: ${getDiagnosticLogPath()}`);
+
+    if (this.status.state === "running" || this.status.state === "starting") {
+      return this.status;
+    }
+
+    const runtimeMode = resolveDesktopRuntimeMode(
+      process.env as Record<string, string | undefined>,
+    );
+    if (runtimeMode.mode !== "local") {
+      const reason =
+        runtimeMode.mode === "external"
+          ? `Embedded desktop runtime is disabled because ${runtimeMode.externalApi.source} points at ${runtimeMode.externalApi.base}.`
+          : "Embedded desktop runtime is disabled by ELIZA_DESKTOP_SKIP_EMBEDDED_AGENT=1.";
+      diagnosticLog(`[Agent] ${reason}`);
+      this.setStartupPhase("startup_disabled", reason);
+      throw new Error(reason);
+    }
+
+    let packagedRuntime: boolean;
+    let apiPort: number;
+    let preferredPort: number;
+    try {
+      configureDesktopLocalApiAuth();
+      packagedRuntime = isPackagedDesktopRuntime();
+
+      // Reset per-startup flags
+      this.pgliteRecoveryDone = false;
+
+      // Clean up any stale process before starting
+      if (this.childProcess) {
+        await this.killChildProcess();
+      }
+
+      preferredPort = resolveDesktopApiPort(process.env) || DEFAULT_API_PORT;
+      diagnosticLog(
+        `[Agent] Preferred port: ${preferredPort} (packaged: ${packagedRuntime})`,
+      );
+      if (!packagedRuntime) {
+        await maybeReclaimPortWithSigkill(preferredPort);
+      }
+      apiPort = await findFirstAvailableLoopbackPort(preferredPort);
+    } catch (err) {
+      const msg =
+        err instanceof Error ? err.message : "Failed during pre-startup";
+      diagnosticLog(`[Agent] ${msg}`);
+      this.status = {
+        state: "error",
+        agentName: null,
+        port: null,
+        startedAt: null,
+        error: msg,
+      };
+      recordStartupPhase("fatal", {
+        port: null,
+        error: msg,
+      });
+      this.setStartupPhase("port_allocation_failed", msg);
+      this.emitStatus();
+      return this.status;
+    }
+    if (apiPort !== preferredPort) {
+      diagnosticLog(
+        `[Agent] Port ${preferredPort} busy — using ${apiPort} for embedded API (set ELIZA_AGENT_RECLAIM_STALE_PORT=1 to try reclaiming the preferred port first)`,
+      );
+    }
+    recordStartupPhase("port_selected", {
+      port: apiPort,
+    });
+
+    this.status = {
+      state: "starting",
+      agentName: null,
+      port: null,
+      startedAt: null,
+      error: null,
+    };
+    this.setStartupPhase("starting_runtime");
+    this.emitStatus();
+
+    try {
+      // Resolve the bundled runtime dist path.
+      this.setStartupPhase("resolving_runtime");
+      const runtimeDistPath = resolveRuntimeDistPath();
+      diagnosticLog(`[Agent] Resolved runtime dist: ${runtimeDistPath}`);
+
+      // Packaged builds can expose the runnable entry either at the dist root
+      // or under runtime/. Prefer the root file but accept both layouts.
+      const runtimeEntryPath = resolveRuntimeEntryPath(runtimeDistPath);
+      if (!runtimeEntryPath) {
+        const distExists = fs.existsSync(runtimeDistPath);
+        let contents = "<directory missing>";
+        if (distExists) {
+          try {
+            contents = fs.readdirSync(runtimeDistPath).join(", ");
+          } catch {
+            contents = "<unreadable>";
+          }
+        }
+        const errMsg = `No runnable runtime entry found in ${runtimeDistPath} (checked entry.js; dist exists: ${distExists}, contents: ${contents})`;
+        diagnosticLog(`[Agent] ${errMsg}`);
+        this.status = {
+          state: "error",
+          agentName: null,
+          port: null,
+          startedAt: null,
+          error: errMsg,
+        };
+        recordStartupPhase("fatal", {
+          port: apiPort,
+          error: errMsg,
+        });
+        this.setStartupPhase("runtime_entry_missing", errMsg);
+        recordStartupPhase("fatal", {
+          port: apiPort,
+          error: errMsg,
+        });
+        this.emitStatus();
+        return this.status;
+      }
+
+      diagnosticLog(`[Agent] runtime entry: exists (${runtimeEntryPath})`);
+      recordStartupPhase("runtime_path_resolved", {
+        port: apiPort,
+      });
+
+      diagnosticLog(`[Agent] Starting child process on port ${apiPort}...`);
+      this.setStartupPhase("spawning_runtime");
+
+      // Build NODE_PATH so the child can find node_modules
+      const nodePaths = buildChildNodePaths(runtimeDistPath, {
+        packagedRuntime,
+      });
+      if (packagedRuntime && nodePaths.length === 0) {
+        const errMsg =
+          `Packaged runtime is missing bundle-local node_modules under ${runtimeDistPath}; ` +
+          "refusing to inherit the parent NODE_PATH";
+        diagnosticLog(`[Agent] ${errMsg}`);
+        this.status = {
+          state: "error",
+          agentName: null,
+          port: apiPort,
+          startedAt: null,
+          error: errMsg,
+        };
+        recordStartupPhase("fatal", {
+          port: apiPort,
+          error: errMsg,
+        });
+        this.emitStatus();
+        return this.status;
+      }
+
+      const childEnv: Record<string, string> = {
+        ...(process.env as Record<string, string>),
+        ELIZA_API_PORT: String(apiPort),
+        ELIZA_PORT: String(apiPort),
+      };
+      childEnv.ELIZA_NAMESPACE = resolveDesktopChildNamespace(childEnv);
+      applyDesktopChildStateEnv(childEnv);
+      delete childEnv.ELIZA_PORT;
+      delete childEnv.NODE_PATH;
+
+      const databaseResolution = resolveDatabaseMode({
+        env: childEnv,
+        packagedDesktop: packagedRuntime,
+        appStateDir: childEnv.ELIZA_STATE_DIR,
+        cwd: runtimeDistPath,
+      });
+      applyDatabaseResolutionToEnv(childEnv, databaseResolution);
+      const bundledWhisper = applyBundledWhisperEnv(childEnv, runtimeDistPath);
+      if (bundledWhisper) {
+        diagnosticLog(
+          `[Agent] Bundled Whisper ASR: ${bundledWhisper.libraryPath}`,
+        );
+      }
+      const effectiveTarget =
+        databaseResolution.mode === "postgres"
+          ? redactDatabaseTarget(databaseResolution.postgresUrl)
+          : (databaseResolution.pgliteDataDir ?? null);
+      this.databaseSnapshot = createDatabaseSnapshot({
+        mode: databaseResolution.mode,
+        status: "resolving",
+        postgresUrlSet: databaseResolution.mode === "postgres",
+        databaseUrlMapped: databaseResolution.databaseUrlMapped,
+        pgliteDataDir: databaseResolution.pgliteDataDir ?? null,
+        effectiveTarget,
+        warnings: databaseResolution.warnings,
+      });
+      this.persistStartupDiagnostics();
+      diagnosticLog(
+        `[Agent] Database mode: ${databaseResolution.mode} source=${databaseResolution.source} target=${effectiveTarget ?? "runtime-default"}`,
+      );
+      recordStartupPhase("database_mode_resolved", {
+        port: apiPort,
+      });
+      if (
+        databaseResolution.mode === "pglite-persistent" &&
+        databaseResolution.pgliteDataDir
+      ) {
+        try {
+          ensurePgliteDataDir(databaseResolution.pgliteDataDir);
+          const lockResult = acquireDatabaseStartupLock(
+            databaseResolution.pgliteDataDir,
+          );
+          if (!lockResult.ok) {
+            const errMsg = lockResult.error;
+            this.databaseSnapshot = updateDatabaseSnapshotStatus(
+              this.databaseSnapshot,
+              "locked",
+              {
+                error: errMsg,
+                lock: lockResult.snapshot,
+              },
+            );
+            this.persistStartupDiagnostics(errMsg);
+            this.status = {
+              state: "error",
+              agentName: null,
+              port: apiPort,
+              startedAt: null,
+              error: errMsg,
+            };
+            this.emitStatus();
+            return this.status;
+          }
+          this.databaseStartupLock = lockResult.lock;
+          this.databaseSnapshot = updateDatabaseSnapshotStatus(
+            this.databaseSnapshot,
+            "starting",
+            {
+              lock: lockResult.lock.snapshot,
+            },
+          );
+          this.persistStartupDiagnostics();
+        } catch (error) {
+          const message =
+            error instanceof Error ? error.message : String(error);
+          const status = classifyDatabaseError(message);
+          this.databaseSnapshot = updateDatabaseSnapshotStatus(
+            this.databaseSnapshot,
+            status,
+            {
+              error: message,
+            },
+          );
+          this.persistStartupDiagnostics(message);
+          this.status = {
+            state: "error",
+            agentName: null,
+            port: apiPort,
+            startedAt: null,
+            error: message,
+          };
+          this.emitStatus();
+          return this.status;
+        }
+      } else if (
+        databaseResolution.mode === "postgres" ||
+        databaseResolution.mode === "pglite-memory"
+      ) {
+        this.databaseSnapshot = updateDatabaseSnapshotStatus(
+          this.databaseSnapshot,
+          "starting",
+        );
+        this.persistStartupDiagnostics();
+      }
+
+      applyWindowsNativeInferenceDefaults(childEnv);
+      applyPackagedStartupEmbeddingWarmupPolicy(childEnv, packagedRuntime);
+      applyDesktopDeferAppRoutesPolicy(childEnv);
+
+      if (nodePaths.length > 0) {
+        childEnv.NODE_PATH = nodePaths.join(path.delimiter);
+        diagnosticLog(`[Agent] Child NODE_PATH: ${childEnv.NODE_PATH}`);
+      }
+
+      const bunExecutable = resolveBunExecutablePath();
+      diagnosticLog(`[Agent] Using Bun executable: ${bunExecutable}`);
+      diagnosticLog(
+        `[Agent] Bun exists on disk: ${fs.existsSync(bunExecutable)}`,
+      );
+
+      // Ensure bun's directory is on PATH so child_process.exec calls
+      // (e.g. plugin-manager running `bun add ...`) can find it.
+      const bunDir = path.dirname(bunExecutable);
+      if (prependDesktopChildPathDirectory(childEnv, bunDir)) {
+        diagnosticLog(`[Agent] Prepended bun dir to child PATH: ${bunDir}`);
+      }
+
+      // Spawn the child process
+      const spawnTime = Date.now();
+      const proc = Bun.spawn(
+        [bunExecutable, "run", runtimeEntryPath, "start"],
+        {
+          cwd: runtimeDistPath,
+          env: childEnv,
+          stdout: "pipe",
+          stderr: "pipe",
+        },
+      );
+
+      this.childProcess = proc;
+      diagnosticLog(
+        `[Agent] Child spawned pid=${proc.pid} elapsed=${Date.now() - spawnTime}ms`,
+      );
+      recordStartupPhase("child_spawned", {
+        port: apiPort,
+        child_pid: proc.pid,
+      });
+
+      // Set up abort controller for stdio watchers
+      this.stdioAbortController = new AbortController();
+      const { signal } = this.stdioAbortController;
+
+      // Surface the port immediately while waiting for ready
+      this.status = {
+        ...this.status,
+        port: apiPort,
+      };
+      this.emitStatus();
+
+      // Track whether we detected the "listening" message from stdout
+      let detectedListening = false;
+
+      // Watch stdout for "listening on port" or similar ready messages
+      if (proc.stdout) {
+        watchStdoutForReady(
+          proc.stdout,
+          (line: string) => {
+            diagnosticLog(`[Agent][stdout] ${line}`);
+            const lower = line.toLowerCase();
+            // Parse dynamic port from "[eliza-api] Listening on http://host:PORT"
+            const portMatch = line.match(
+              /Listening on https?:\/\/[^:]+:(\d+)/i,
+            );
+            if (portMatch) {
+              const parsedPort = parseInt(portMatch[1], 10);
+              if (!Number.isNaN(parsedPort) && parsedPort > 0) {
+                if (parsedPort !== apiPort) {
+                  diagnosticLog(
+                    `[Agent] Server bound to dynamic port ${parsedPort} (requested ${apiPort})`,
+                  );
+                  apiPort = parsedPort;
+                }
+                detectedListening = true;
+              }
+            } else if (
+              lower.includes("listening on port") ||
+              lower.includes("server started") ||
+              lower.includes("ready on")
+            ) {
+              detectedListening = true;
+            }
+            // Update status port so callers see the actual bound port
+            this.status = { ...this.status, port: apiPort };
+            this.emitStatus();
+          },
+          signal,
+        ).catch(() => {
+          // Stream ended or aborted -- expected on shutdown
+        });
+      }
+
+      // Drain stderr to diagnostic log; detect PGLite migration failures
+      this.hasPgliteError = false;
+      if (proc.stderr) {
+        drainStderrToLog(proc.stderr, signal, (line) => {
+          this.updateDatabaseSnapshotFromRuntimeLog(line);
+          if (shouldAutoRecoverPgliteFailure(line)) {
+            this.hasPgliteError = true;
+          }
+        }).catch(() => {
+          // Stream ended or aborted -- expected on shutdown
+        });
+      }
+
+      // Monitor child process exit
+      this.monitorChildExit(proc);
+
+      // Wait for the health endpoint to respond
+      // Use a getter so the health check follows dynamic port reassignment from stdout
+      diagnosticLog(
+        `[Agent] Waiting for health endpoint at http://127.0.0.1:${apiPort}/api/health ...`,
+      );
+      this.setStartupPhase("waiting_for_health");
+      const healthPollTimeoutMs = getHealthPollTimeoutMs();
+      const healthy = await waitForHealthy(
+        () => apiPort,
+        healthPollTimeoutMs,
+        proc,
+      );
+
+      if (!healthy) {
+        // Check if process already exited
+        if (proc.exitCode !== null) {
+          const errMsg = `Child process exited with code ${proc.exitCode} before becoming healthy`;
+          diagnosticLog(`[Agent] ${errMsg}`);
+          this.childProcess = null;
+          this.status = {
+            state: "error",
+            agentName: null,
+            port: apiPort,
+            startedAt: null,
+            error: errMsg,
+          };
+          recordStartupPhase("fatal", {
+            port: apiPort,
+            child_pid: proc.pid,
+            error: errMsg,
+            exit_code: proc.exitCode,
+          });
+          this.setStartupPhase("startup_failed", errMsg);
+          recordStartupPhase("fatal", {
+            port: apiPort,
+            child_pid: proc.pid,
+            error: errMsg,
+            exit_code: proc.exitCode,
+          });
+          this.releaseDatabaseStartupLock();
+          this.emitStatus();
+          return this.status;
+        }
+
+        const errMsg = detectedListening
+          ? "Server reported listening but health check timed out"
+          : `Health check timed out after ${healthPollTimeoutMs}ms`;
+        diagnosticLog(`[Agent] ${errMsg}`);
+        this.status = {
+          state: "error",
+          agentName: null,
+          port: apiPort,
+          startedAt: null,
+          error: errMsg,
+        };
+        recordStartupPhase("fatal", {
+          port: apiPort,
+          child_pid: proc.pid,
+          error: errMsg,
+        });
+        this.setStartupPhase("startup_failed", errMsg);
+        recordStartupPhase("fatal", {
+          port: apiPort,
+          child_pid: proc.pid,
+          error: errMsg,
+        });
+        this.releaseDatabaseStartupLock();
+        this.emitStatus();
+        return this.status;
+      }
+      recordStartupPhase("health_ready", {
+        port: apiPort,
+        child_pid: proc.pid,
+      });
+      this.databaseSnapshot = updateDatabaseSnapshotStatus(
+        this.databaseSnapshot,
+        "ready",
+        {
+          migrationStatus:
+            this.databaseSnapshot.migrationStatus?.failed === true
+              ? this.databaseSnapshot.migrationStatus
+              : {
+                  running: false,
+                  completed: true,
+                  failed: false,
+                },
+          lock: {
+            held: false,
+          },
+        },
+      );
+      this.releaseDatabaseStartupLock();
+
+      this.setStartupPhase("fetching_agent_metadata");
+      const startedAt = Date.now();
+      const startupMs = startedAt - spawnTime;
+
+      this.status = {
+        state: "running",
+        agentName: getBrandConfig().appName,
+        port: apiPort,
+        startedAt,
+        error: null,
+      };
+      this.setStartupPhase("ready", null);
+      this.emitStatus();
+      diagnosticLog(
+        `[Agent] Runtime ready -- port: ${apiPort}, pid: ${proc.pid}, startup_ms: ${startupMs}`,
+      );
+      recordStartupPhase("runtime_ready", {
+        port: apiPort,
+        child_pid: proc.pid,
+      });
+      void this.refreshAgentMetadata(proc, apiPort, startupMs);
+      return this.status;
+    } catch (err) {
+      const errMsg =
+        err instanceof Error ? err.stack || err.message : String(err);
+      diagnosticLog(`[Agent] Failed to start: ${errMsg}`);
+      recordStartupPhase("fatal", {
+        port: this.status.port,
+        error: errMsg,
+      });
+
+      // Clean up child if it was spawned
+      if (this.childProcess) {
+        await this.killChildProcess();
+      }
+      this.releaseDatabaseStartupLock();
+
+      this.status = {
+        state: "error",
+        agentName: null,
+        port: this.status.port, // preserve port if set
+        startedAt: null,
+        error: shortError(err),
+      };
+      this.setStartupPhase("startup_failed", shortError(err));
+      this.emitStatus();
+      return this.status;
+    }
+  }
+
+  /** Stop the agent runtime. */
+  async stop(): Promise<void> {
+    if (this.status.state !== "running" && this.status.state !== "starting") {
+      return;
+    }
+
+    diagnosticLog("[Agent] Stopping...");
+    this.setStartupPhase("stopping");
+
+    // Abort stdio watchers
+    if (this.stdioAbortController) {
+      this.stdioAbortController.abort();
+      this.stdioAbortController = null;
+    }
+
+    await this.killChildProcess();
+    this.releaseDatabaseStartupLock();
+
+    this.status = {
+      state: "stopped",
+      agentName: this.status.agentName,
+      port: null,
+      startedAt: null,
+      error: null,
+    };
+    this.setStartupPhase("stopped", null);
+    this.emitStatus();
+    diagnosticLog("[Agent] Runtime stopped");
+  }
+
+  /**
+   * Restart the agent runtime -- stops the current instance and starts a
+   * fresh one, picking up config/plugin changes.
+   */
+  async restart(): Promise<AgentStatus> {
+    diagnosticLog("[Agent] Restart requested -- stopping current runtime...");
+    this.setStartupPhase("restart_requested");
+    await this.stop();
+    diagnosticLog("[Agent] Restarting...");
+    return this.start();
+  }
+
+  /**
+   * Used after `POST /api/agent/reset`: stop the child, delete local PGLite
+   * (conversations / agent memory under the active state-dir workspace),
+   * then start fresh. Does not remove downloaded **GGUF** models (`MODELS_DIR`,
+   * env-backed wallet keys, or eliza.json (the API reset already rewrote
+   * config on disk).
+   *
+   * When `ELIZA_DESKTOP_API_BASE` points at an external dev API (e.g. :31337),
+   * the embedded child is never used — this is a no-op so the renderer can
+   * bounce the real API via `POST /api/agent/restart` instead.
+   */
+  async restartClearingLocalDb(): Promise<AgentStatus> {
+    const runtimeMode = resolveDesktopRuntimeMode(
+      process.env as Record<string, string | undefined>,
+    );
+    if (runtimeMode.mode !== "local") {
+      diagnosticLog(
+        `[Agent] restartClearingLocalDb skipped — mode=${runtimeMode.mode} externalBase=${runtimeMode.externalApi.base ?? "n/a"} source=${runtimeMode.externalApi.source ?? "n/a"} (renderer uses POST /api/agent/restart)`,
+      );
+      return this.getStatus();
+    }
+
+    const dataDir = resolveManagedPgliteDataDir();
+    if (!dataDir) {
+      const message =
+        "Local PGlite reset is unavailable for the active database mode.";
+      diagnosticLog(`[Agent] restartClearingLocalDb skipped — ${message}`);
+      this.databaseSnapshot = updateDatabaseSnapshotStatus(
+        this.databaseSnapshot,
+        "error",
+        { error: message },
+      );
+      return this.getStatus();
+    }
+
+    diagnosticLog(
+      `[Agent] restartClearingLocalDb: local mode — stop → backup/reset PGLite (${dataDir}) → start`,
+    );
+    await this.stop();
+    this.hasPgliteError = false;
+    this.pgliteRecoveryDone = false;
+    const reset = resetPgliteDirectory(dataDir);
+    diagnosticLog(
+      `[Agent] PGLite backup/reset completed backup=${reset.backup.backupDir ?? "none"} removed=${reset.removed}`,
+    );
+    this.databaseSnapshot = updateDatabaseSnapshotStatus(
+      this.databaseSnapshot,
+      "starting",
+      { error: null },
+    );
+    const next = await this.start();
+    diagnosticLog(
+      `[Agent] restartClearingLocalDb: start() finished state=${next.state} port=${next.port ?? "null"}`,
+    );
+    return next;
+  }
+
+  getStatus(): AgentStatus {
+    return { ...this.status };
+  }
+
+  getDatabaseSnapshot(): DatabaseSnapshot {
+    return this.databaseSnapshot;
+  }
+
+  previewDatabaseRecovery(): {
+    snapshot: DatabaseSnapshot;
+    actions: DatabaseSnapshot["recoveryActions"];
+  } {
+    return {
+      snapshot: this.databaseSnapshot,
+      actions: this.databaseSnapshot.recoveryActions,
+    };
+  }
+
+  backupPgliteDatabase(): ReturnType<typeof backupPgliteDirectory> {
+    const dataDir =
+      this.databaseSnapshot.pgliteDataDir ?? resolveManagedPgliteDataDir();
+    if (!dataDir) {
+      throw new Error("No persistent PGlite data directory is active.");
+    }
+    const result = backupPgliteDirectory(dataDir);
+    diagnosticLog(
+      `[Agent] PGLite backup created: ${result.backupDir ?? "none"} reason=${result.reason ?? "created"}`,
+    );
+    return result;
+  }
+
+  async resetPgliteDatabase(params?: {
+    restart?: boolean;
+  }): Promise<
+    ReturnType<typeof resetPgliteDirectory> & { restarted: boolean }
+  > {
+    const dataDir =
+      this.databaseSnapshot.pgliteDataDir ?? resolveManagedPgliteDataDir();
+    if (!dataDir) {
+      throw new Error("No persistent PGlite data directory is active.");
+    }
+    await this.stop();
+    const result = resetPgliteDirectory(dataDir);
+    diagnosticLog(
+      `[Agent] PGLite reset completed backup=${result.backup.backupDir ?? "none"} removed=${result.removed}`,
+    );
+    if (params?.restart === true) {
+      await this.start();
+      return { ...result, restarted: true };
+    }
+    return { ...result, restarted: false };
+  }
+
+  inspectExistingInstall(): ExistingElizaInstallInfo {
+    return inspectExistingElizaInstall();
+  }
+
+  migrateStateDir(params: { fromPath: string }): StateDirMigrationResult {
+    return migrateDesktopStateDirFromPath(params.fromPath);
+  }
+
+  getPort(): number | null {
+    return this.status.port;
+  }
+
+  /** Clean up on app quit. */
+  async dispose(): Promise<void> {
+    if (this.stdioAbortController) {
+      this.stdioAbortController.abort();
+      this.stdioAbortController = null;
+    }
+    try {
+      await this.killChildProcess();
+      this.releaseDatabaseStartupLock();
+    } catch (err) {
+      logger.warn(
+        `[Agent] dispose error: ${err instanceof Error ? err.message : String(err)}`,
+      );
+    }
+  }
+
+  // -----------------------------------------------------------------------
+  // Private helpers
+  // -----------------------------------------------------------------------
+
+  private emitStatus(): void {
+    this.persistStartupDiagnostics();
+    if (this.sendToWebview) {
+      this.sendToWebview("agentStatusUpdate", this.status);
+    }
+    const statusSnapshot = { ...this.status };
+    for (const listener of this.statusListeners) {
+      try {
+        listener(statusSnapshot);
+      } catch (err) {
+        logger.warn(
+          `[Agent] status listener failed: ${err instanceof Error ? err.message : String(err)}`,
+        );
+      }
+    }
+  }
+
+  private async refreshAgentMetadata(
+    proc: BunSubprocess,
+    port: number,
+    startupMs: number,
+  ): Promise<void> {
+    const agentName = await this.fetchAgentName(port);
+    if (
+      this.childProcess !== proc ||
+      this.status.state !== "running" ||
+      this.status.port !== port
+    ) {
+      return;
+    }
+
+    if (this.status.agentName !== agentName) {
+      this.status = {
+        ...this.status,
+        agentName,
+      };
+      this.emitStatus();
+    }
+
+    diagnosticLog(
+      `[Agent] Runtime started -- agent: ${agentName}, port: ${port}, pid: ${proc.pid}, startup_ms: ${startupMs}`,
+    );
+    recordStartupPhase("metadata_ready", {
+      port,
+      child_pid: proc.pid,
+    });
+  }
+  private setStartupPhase(phase: string, lastError?: string | null): void {
+    this.startupPhase = phase;
+    this.persistStartupDiagnostics(lastError);
+  }
+
+  private persistStartupDiagnostics(lastError?: string | null): void {
+    writeStartupDiagnosticsSnapshot({
+      state: this.status.state,
+      phase: this.startupPhase,
+      updatedAt: new Date().toISOString(),
+      lastError: lastError ?? this.status.error,
+      agentName: this.status.agentName,
+      port: this.status.port,
+      startedAt: this.status.startedAt,
+      platform: process.platform,
+      arch: process.arch,
+      configDir: resolveConfigDir(),
+      logPath: getDiagnosticLogPath(),
+      statusPath: getStartupStatusPath(),
+      database: this.databaseSnapshot,
+    });
+  }
+
+  private releaseDatabaseStartupLock(): void {
+    if (!this.databaseStartupLock) return;
+    this.databaseStartupLock.release();
+    this.databaseStartupLock = null;
+  }
+
+  private updateDatabaseSnapshotFromRuntimeLog(line: string): void {
+    const lower = line.toLowerCase();
+    if (lower.includes("starting migrations")) {
+      this.databaseSnapshot = updateDatabaseSnapshotStatus(
+        this.databaseSnapshot,
+        "migrating",
+        {
+          migrationStatus: {
+            running: true,
+            completed: false,
+            failed: false,
+          },
+        },
+      );
+      this.persistStartupDiagnostics();
+      recordStartupPhase("database_migration_started", {
+        port: this.status.port,
+      });
+      return;
+    }
+    if (lower.includes("all migrations completed successfully")) {
+      this.databaseSnapshot = updateDatabaseSnapshotStatus(
+        this.databaseSnapshot,
+        "starting",
+        {
+          migrationStatus: {
+            running: false,
+            completed: true,
+            failed: false,
+          },
+        },
+      );
+      this.persistStartupDiagnostics();
+      recordStartupPhase("database_migration_completed", {
+        port: this.status.port,
+      });
+      return;
+    }
+    if (
+      lower.includes("migration failed") ||
+      lower.includes("migration(s) failed")
+    ) {
+      const pluginMatch = line.match(/pluginName[":=\s]+["']?([^"',\s}]+)/);
+      const error = redactSensitiveDiagnostics(line);
+      this.databaseSnapshot = updateDatabaseSnapshotStatus(
+        this.databaseSnapshot,
+        "migration-failed",
+        {
+          error,
+          migrationStatus: {
+            running: false,
+            completed: false,
+            failed: true,
+            failedPlugin: pluginMatch?.[1],
+            error,
+          },
+        },
+      );
+      this.persistStartupDiagnostics(error);
+      recordStartupPhase("database_migration_failed", {
+        port: this.status.port,
+        error,
+      });
+      return;
+    }
+    const status = classifyDatabaseError(line);
+    if (status === "error") return;
+    const error = redactSensitiveDiagnostics(line);
+    this.databaseSnapshot = updateDatabaseSnapshotStatus(
+      this.databaseSnapshot,
+      status,
+      { error },
+    );
+    this.persistStartupDiagnostics(error);
+  }
+
+  /**
+   * Monitor the child process for unexpected exits and update status.
+   */
+  private monitorChildExit(proc: BunSubprocess): void {
+    // Bun.spawn provides an `exited` promise that resolves when the process exits
+    proc.exited
+      .then((exitCode: number) => {
+        // Only update status if this is still our active child process
+        if (this.childProcess !== proc) return;
+
+        const wasRunning = this.status.state === "running";
+        const wasStarting = this.status.state === "starting";
+
+        if (wasRunning || wasStarting) {
+          diagnosticLog(
+            `[Agent] Child process exited unexpectedly with code ${exitCode} (pid: ${proc.pid})`,
+          );
+          recordStartupPhase("fatal", {
+            port: this.status.port,
+            child_pid: proc.pid,
+            error: `Process exited unexpectedly with code ${exitCode}`,
+            exit_code: exitCode,
+          });
+          this.childProcess = null;
+
+          if (this.hasPgliteError && !this.pgliteRecoveryDone) {
+            this.pgliteRecoveryDone = true;
+            const error =
+              "PGLite startup or migration failed. Use database recovery to backup/reset local data or switch to Postgres.";
+            diagnosticLog(`[Agent] ${error}`);
+            this.databaseSnapshot = updateDatabaseSnapshotStatus(
+              this.databaseSnapshot,
+              classifyDatabaseError(error),
+              { error },
+            );
+          }
+
+          this.status = {
+            state: "error",
+            agentName: this.status.agentName,
+            port: this.status.port,
+            startedAt: null,
+            error: `Process exited unexpectedly with code ${exitCode}`,
+          };
+          this.setStartupPhase(
+            "process_exited_unexpectedly",
+            `Process exited unexpectedly with code ${exitCode}`,
+          );
+          this.releaseDatabaseStartupLock();
+          this.emitStatus();
+        } else {
+          // Expected exit (we called stop)
+          this.childProcess = null;
+          this.releaseDatabaseStartupLock();
+        }
+      })
+      .catch((err: unknown) => {
+        if (this.childProcess !== proc) return;
+        diagnosticLog(
+          `[Agent] Child process exited with error: ${err instanceof Error ? err.message : String(err)}`,
+        );
+        recordStartupPhase("fatal", {
+          port: this.status.port,
+          child_pid: proc.pid,
+          error: err instanceof Error ? err.message : String(err),
+        });
+        this.childProcess = null;
+        this.releaseDatabaseStartupLock();
+        if (
+          this.status.state === "running" ||
+          this.status.state === "starting"
+        ) {
+          this.status = {
+            state: "error",
+            agentName: this.status.agentName,
+            port: this.status.port,
+            startedAt: null,
+            error: shortError(err),
+          };
+          this.setStartupPhase("process_exit_error", shortError(err));
+          this.emitStatus();
+        }
+      });
+  }
+
+  /**
+   * Kill the child process gracefully with SIGTERM, escalating to SIGKILL
+   * after a timeout.
+   */
+  private async killChildProcess(): Promise<void> {
+    const proc = this.childProcess;
+    if (!proc) return;
+
+    this.childProcess = null;
+
+    // Already exited
+    if (proc.exitCode !== null) return;
+
+    diagnosticLog(`[Agent] Sending SIGTERM to pid ${proc.pid}`);
+    proc.kill("SIGTERM");
+
+    // Wait for graceful shutdown or timeout
+    const exited = await Promise.race([
+      proc.exited.then(() => true as const),
+      Bun.sleep(SIGTERM_GRACE_MS).then(() => false as const),
+    ]);
+
+    if (!exited) {
+      diagnosticLog(
+        `[Agent] Process did not exit within ${SIGTERM_GRACE_MS}ms, sending SIGKILL`,
+      );
+      try {
+        proc.kill("SIGKILL");
+      } catch {
+        // Process may have already exited between check and kill
+      }
+      // Wait briefly for SIGKILL to take effect
+      await Promise.race([proc.exited.catch(() => {}), Bun.sleep(1_000)]);
+    }
+
+    diagnosticLog("[Agent] Child process terminated");
+  }
+
+  /**
+   * Attempt to fetch the agent name from the running API server.
+   * Falls back to the configured desktop app name if the endpoint is unavailable.
+   */
+  private async fetchAgentName(port: number): Promise<string> {
+    try {
+      const headers = getDesktopApiHeaders();
+      const response = await fetch(`http://127.0.0.1:${port}/api/agents`, {
+        headers,
+        signal: AbortSignal.timeout(AGENT_NAME_FETCH_TIMEOUT_MS),
+      });
+      if (response.ok) {
+        const data = (await response.json()) as
+          | { agents?: Array<{ name?: string }> }
+          | Array<{ name?: string }>;
+        const agents = Array.isArray(data) ? data : data.agents;
+        if (agents && agents.length > 0 && agents[0].name) {
+          return agents[0].name;
+        }
+      }
+    } catch {
+      diagnosticLog("[Agent] Could not fetch agent name, using default");
+    }
+    return getBrandConfig().appName;
+  }
 }
 
 // ---------------------------------------------------------------------------
@@ -1956,8 +2396,8 @@ export class AgentManager {
 let agentManager: AgentManager | null = null;
 
 export function getAgentManager(): AgentManager {
-	if (!agentManager) {
-		agentManager = new AgentManager();
-	}
-	return agentManager;
+  if (!agentManager) {
+    agentManager = new AgentManager();
+  }
+  return agentManager;
 }