@elizaos/app-core 2.0.3-beta.2 → 2.0.3-beta.4

package/scripts/run-mobile-build.mjs

@@ -64,16 +64,38 @@ import {
   resolveAppConfigPath,
 } from "./aosp/lib/load-variant-config.mjs";
 import { resolveMainAppDir } from "./lib/app-dir.mjs";
+import { artifactStaleness } from "./lib/artifact-staleness.mjs";
 import {
   isCapacitorPlatformReady as isCapacitorPlatformReadyImpl,
   resolvePlatformTemplateRoot as resolvePlatformTemplateRootImpl,
   syncPlatformTemplateFiles as syncPlatformTemplateFilesImpl,
 } from "./lib/capacitor-platform-templates.mjs";
+import { ensurePlistUrlScheme } from "./lib/ios-plist-url-scheme.mjs";
+import {
+  androidUsesAppDirFor,
+  MTP_FORK_SRC_CANDIDATES,
+  mtpForceRebuildRequested,
+  mtpSliceReuse,
+} from "./lib/mobile-build-decisions.mjs";
+import {
+  assertStagedRendererMatchesBuild,
+  overlayFreshRendererIntoPublic,
+  readRendererBuildManifest,
+} from "./lib/renderer-build-manifest.mjs";
 import { resolveRepoRootFromImportMeta } from "./lib/repo-root.mjs";
 import {
   RUNTIME_PROVENANCE_FILENAME,
   stageAndroidAgentRuntime,
 } from "./lib/stage-android-agent.mjs";
+import { viteRendererBuildNeeded } from "./lib/vite-renderer-dist-stale.mjs";
+
+export {
+  androidUsesAppDirFor,
+  MTP_FORK_SRC_CANDIDATES,
+  mtpBuilderRepoRoot,
+  mtpForceRebuildRequested,
+  mtpSliceReuse,
+} from "./lib/mobile-build-decisions.mjs";
 
 // ── Paths ───────────────────────────────────────────────────────────────
 
@@ -103,10 +125,11 @@ const iosDir = path.join(appDir, "ios", "App");
 // treating app-core/platforms/android as a read-only template copied in by
 // overlayAndroid/patchAndroidGradle/syncAndroidAppActionsResources. That keeps
 // the two brands' Android builds fully separate.
-const androidDir =
-  process.env.ELIZA_ANDROID_USE_APP_DIR === "1"
-    ? path.join(appDir, "android")
-    : path.join(appCoreRoot, "platforms", "android");
+const androidBuildAppId = readAppIdentity().appId;
+const androidUsesAppDir = androidUsesAppDirFor(androidBuildAppId, process.env);
+const androidDir = androidUsesAppDir
+  ? path.join(appDir, "android")
+  : path.join(appCoreRoot, "platforms", "android");
 const localArtifactsDir = path.join(elizaRepoRoot, ".eliza-local", "artifacts");
 const androidSmsGatewayDebugApkArtifact = path.join(
   localArtifactsDir,
@@ -291,8 +314,23 @@ function withMobileBuildNodeOptions(env = process.env) {
 }
 
 function run(command, args, { cwd, env = process.env } = {}) {
+  // Windows: gradlew is gradlew.bat, and Node cannot spawn `./gradlew` (ENOENT)
+  // nor a .bat/.cmd directly (EINVAL since CVE-2024-27980). Translate
+  // ./gradlew -> the sibling gradlew.bat (resolved against cwd) and run any
+  // .bat/.cmd through cmd.exe with args as separate argv (no shell:true).
+  let spawnCmd = command;
+  let spawnArgs = args;
+  if (process.platform === "win32") {
+    if (command === "./gradlew" || command === "gradlew") {
+      spawnCmd = path.join(cwd || process.cwd(), "gradlew.bat");
+    }
+    if (/.(?:bat|cmd)$/i.test(spawnCmd)) {
+      spawnArgs = ["/d", "/s", "/c", spawnCmd, ...args];
+      spawnCmd = process.env.ComSpec || "cmd.exe";
+    }
+  }
   return new Promise((resolve, reject) => {
-    const child = spawn(command, args, { cwd, env, stdio: "inherit" });
+    const child = spawn(spawnCmd, spawnArgs, { cwd, env, stdio: "inherit" });
     child.on("exit", (code, signal) => {
       if (signal) return reject(new Error(`${command} killed by ${signal}`));
       if ((code ?? 1) !== 0)
@@ -386,6 +424,11 @@ function resolveAndroidSdkRoot() {
     process.env.ANDROID_HOME,
     path.join(os.homedir(), "Library", "Android", "sdk"),
     path.join(os.homedir(), "Android", "Sdk"),
+    path.join(
+      process.env.LOCALAPPDATA || path.join(os.homedir(), "AppData", "Local"),
+      "Android",
+      "Sdk",
+    ),
   ]);
 }
 
@@ -402,15 +445,66 @@ function resolveViteCli() {
   return viteCli;
 }
 
+function javaMajorVersion(javaHome) {
+  if (!javaHome || !fs.existsSync(javaHome)) return null;
+  // `release` is the cheapest, most reliable source (no JVM spawn).
+  const releaseFile = path.join(javaHome, "release");
+  if (fs.existsSync(releaseFile)) {
+    const m = fs
+      .readFileSync(releaseFile, "utf8")
+      .match(/JAVA_VERSION="?(\d+)/);
+    if (m) return Number.parseInt(m[1], 10);
+  }
+  const javaBin = path.join(
+    javaHome,
+    "bin",
+    process.platform === "win32" ? "java.exe" : "java",
+  );
+  if (fs.existsSync(javaBin)) {
+    const r = spawnSync(javaBin, ["-version"], { encoding: "utf8" });
+    const m = `${r.stderr ?? ""}${r.stdout ?? ""}`.match(/version "?(\d+)/);
+    if (m) return Number.parseInt(m[1], 10);
+  }
+  return null;
+}
+
+// Auto-select a JDK >= 21 so a plain `build:android` "just works" with no
+// JAVA_HOME juggling. JAVA_HOME is honored ONLY when it actually is >= 21;
+// otherwise we fall through to the well-known JDK 21 install paths and finally
+// scan /usr/lib/jvm. (AGP 9 + the Android toolchain require 21.)
 function resolveJavaHome() {
-  return firstExisting([
+  const candidates = [
     process.env.JAVA_HOME,
     "/opt/homebrew/opt/openjdk@21",
     "/usr/local/opt/openjdk@21",
     "/usr/lib/jvm/temurin-21-jdk-amd64",
     "/usr/lib/jvm/java-21-openjdk-amd64",
     "/usr/lib/jvm/java-21-openjdk",
-  ]);
+  ];
+  for (const candidate of candidates) {
+    if (candidate && (javaMajorVersion(candidate) ?? 0) >= 21) return candidate;
+  }
+  const jvmRoot = "/usr/lib/jvm";
+  if (fs.existsSync(jvmRoot)) {
+    for (const name of fs.readdirSync(jvmRoot)) {
+      const full = path.join(jvmRoot, name);
+      if ((javaMajorVersion(full) ?? 0) >= 21) return full;
+    }
+  }
+  if (process.platform === "win32") {
+    const programFiles = process.env.ProgramFiles || "C:\\Program Files";
+    for (const vendor of ["Eclipse Adoptium", "Microsoft", "Java", "Zulu"]) {
+      const vendorRoot = path.join(programFiles, vendor);
+      if (!fs.existsSync(vendorRoot)) continue;
+      for (const name of fs.readdirSync(vendorRoot)) {
+        const full = path.join(vendorRoot, name);
+        if ((javaMajorVersion(full) ?? 0) >= 21) return full;
+      }
+    }
+  }
+  // Nothing >= 21 found — return the first path that exists so the caller's
+  // "JDK 21 not found" error fires with a concrete (if wrong-version) hint.
+  return firstExisting(candidates);
 }
 
 function prependPath(env, entries) {
@@ -487,32 +581,6 @@ function insertBeforeRootPlistDictClose(content, insertion) {
   return `${content.slice(0, fallbackIndex)}${insertion}${content.slice(fallbackIndex + "</dict>".length)}`;
 }
 
-function ensurePlistUrlScheme(content, urlScheme) {
-  const escapedScheme = escapeXmlText(urlScheme);
-  const urlTypesRe =
-    /(<key>CFBundleURLTypes<\/key>\s*<array>)([\s\S]*?)(\s*<\/array>)/;
-  const entry = `
-		<dict>
-			<key>CFBundleURLName</key>
-			<string>$(PRODUCT_BUNDLE_IDENTIFIER)</string>
-			<key>CFBundleURLSchemes</key>
-			<array>
-				<string>${escapedScheme}</string>
-			</array>
-		</dict>`;
-  const match = content.match(urlTypesRe);
-  if (!match) {
-    return insertBeforeRootPlistDictClose(
-      content,
-      `\t<key>CFBundleURLTypes</key>\n\t<array>${entry}\n\t</array>\n</dict>`,
-    );
-  }
-  if (match[2].includes(`<string>${escapedScheme}</string>`)) {
-    return content;
-  }
-  return content.replace(urlTypesRe, `$1${match[2]}${entry}$3`);
-}
-
 /**
  * Resolve the real filesystem path to a node_modules package (follows bun
  * symlinks). Returns a path relative to `relativeTo`.
@@ -912,14 +980,69 @@ export function resolveMobileBuildPolicy(platform) {
 
 async function buildWeb(platform) {
   if (process.env.ELIZA_MOBILE_SKIP_WEB_BUILD === "1") {
-    const indexPath = path.join(appDir, "dist", "index.html");
+    const distDir = path.join(appDir, "dist");
+    const indexPath = path.join(distDir, "index.html");
     if (!fs.existsSync(indexPath)) {
       throw new Error(
         `[mobile-build] ELIZA_MOBILE_SKIP_WEB_BUILD=1 but ${indexPath} is missing.`,
       );
     }
+    // Never SILENTLY reuse a stale renderer (issue #9309). The skip flag is an
+    // explicit "reuse the existing dist" request, but it must still fail loudly
+    // when that dist is stale relative to sources or was built for a different
+    // variant/target than this build needs. A deliberate stale reuse can be
+    // forced with ELIZA_MOBILE_SKIP_WEB_BUILD_ALLOW_STALE=1.
+    const allowStale =
+      process.env.ELIZA_MOBILE_SKIP_WEB_BUILD_ALLOW_STALE === "1";
+    const policy = resolveMobileBuildPolicy(platform);
+    const expectedVariant =
+      process.env.ELIZA_BUILD_VARIANT || policy.buildVariant;
+    const expectedTarget = policy.capacitorTarget;
+    const manifest = readRendererBuildManifest(distDir);
+    const problems = [];
+    if (!manifest) {
+      problems.push(
+        `no ${path.join("dist", "eliza-renderer-build.json")} (renderer not built with the build-manifest plugin)`,
+      );
+    } else {
+      if (
+        expectedVariant &&
+        manifest.variant != null &&
+        manifest.variant !== expectedVariant
+      ) {
+        problems.push(
+          `dist built for variant '${manifest.variant}' but this build targets '${expectedVariant}'`,
+        );
+      }
+      if (
+        expectedTarget &&
+        manifest.capacitorTarget != null &&
+        manifest.capacitorTarget !== expectedTarget
+      ) {
+        problems.push(
+          `dist built for capacitor target '${manifest.capacitorTarget}' but this build targets '${expectedTarget}'`,
+        );
+      }
+    }
+    if (viteRendererBuildNeeded(appDir, repoRoot)) {
+      problems.push("dist is older than renderer sources (stale)");
+    }
+    if (problems.length > 0) {
+      const detail = problems.map((p) => `  - ${p}`).join("\n");
+      if (!allowStale) {
+        throw new Error(
+          `[mobile-build] ELIZA_MOBILE_SKIP_WEB_BUILD=1 refused — the existing web build is stale or mismatched:\n${detail}\n` +
+            `Drop ELIZA_MOBILE_SKIP_WEB_BUILD to rebuild, or set ` +
+            `ELIZA_MOBILE_SKIP_WEB_BUILD_ALLOW_STALE=1 to ship this dist anyway (NOT recommended).`,
+        );
+      }
+      console.warn(
+        `[mobile-build] ELIZA_MOBILE_SKIP_WEB_BUILD_ALLOW_STALE=1 — shipping a renderer flagged as stale/mismatched:\n${detail}`,
+      );
+    }
     console.log(
-      `[mobile-build] Reusing existing web build: ${path.relative(repoRoot, path.dirname(indexPath))}`,
+      `[mobile-build] Reusing existing web build: ${path.relative(repoRoot, distDir)}` +
+        (manifest ? ` (buildId=${manifest.buildId.slice(0, 12)})` : ""),
     );
     return;
   }
@@ -1098,6 +1221,23 @@ function stageIosAgentRuntime({
     }
   }
 
+  // The agent bundle must be the freshly built one — never a stale leftover that
+  // forces a manual hot-swap to get latest (issue #9309). buildIos rebuilds it
+  // before staging, so this is a hard guarantee; fail loudly if it regressed.
+  if (process.env.ELIZA_MOBILE_ALLOW_STALE_AGENT_BUNDLE !== "1") {
+    const bundleStale = artifactStaleness(
+      path.join(sourceDir, "agent-bundle.js"),
+      { sourceDirs: [path.join(packagesRoot, "agent", "src")] },
+    );
+    if (bundleStale.stale) {
+      throw new Error(
+        `[mobile-build] iOS agent bundle is stale (${bundleStale.reason}). ` +
+          `Run \`bun run --cwd packages/agent build:ios-bun\` to rebuild, or set ` +
+          `ELIZA_MOBILE_ALLOW_STALE_AGENT_BUNDLE=1 to stage it anyway (NOT recommended).`,
+      );
+    }
+  }
+
   const targetDir = path.join(iosDir, "App", "public", "agent");
   fs.rmSync(targetDir, { recursive: true, force: true });
   fs.mkdirSync(targetDir, { recursive: true });
@@ -1117,6 +1257,19 @@ function stageIosAgentRuntime({
   for (const file of assetPlan.rootAssets) {
     fs.copyFileSync(path.join(sourceDir, file), path.join(publicDir, file));
   }
+  // Verify the staged bundle is a faithful copy (catch a torn/partial copy that
+  // would ship a corrupt agent runtime).
+  if (assetPlan.agentAssets?.includes("agent-bundle.js")) {
+    const sha = (p) =>
+      crypto.createHash("sha256").update(fs.readFileSync(p)).digest("hex");
+    const srcSha = sha(path.join(sourceDir, "agent-bundle.js"));
+    const dstSha = sha(path.join(targetDir, "agent-bundle.js"));
+    if (srcSha !== dstSha) {
+      throw new Error(
+        `[mobile-build] staged iOS agent-bundle.js hash ${dstSha} != source ${srcSha} — partial/corrupt copy.`,
+      );
+    }
+  }
   const stagedModelCount = stageIosBundledLocalModels(targetDir);
   console.log(
     `[mobile-build] Staged iOS Bun agent payload${appStoreBuild ? " (App Store allowlist)" : ""}: ${path.relative(repoRoot, targetDir)}${stagedModelCount > 0 ? ` with ${stagedModelCount} local model file(s)` : ""}`,
@@ -1303,7 +1456,85 @@ function mirrorCapacitorWebPayloadIntoAndroidDir() {
       `[mobile-build] Stale-web guard: overlaid fresh ${path.relative(repoRoot, freshWeb)} → ${path.relative(repoRoot, targetPublic)}`,
     );
   }
+  dropRetiredLlamaCppFromAndroidGradle();
   reconcilePluginManifestWithGradle(targetAssets);
+  // Verify the staged Android renderer is exactly the freshly built one. The
+  // overlay above makes it so; this turns "should be fresh" into a hard,
+  // build-failing guarantee (issue #9309).
+  if (fs.existsSync(path.join(freshWeb, "index.html"))) {
+    assertStagedRendererMatchesBuild(freshWeb, targetPublic, {
+      label: "android",
+    });
+  }
+}
+
+/**
+ * iOS stale-web guard — the iOS counterpart to
+ * mirrorCapacitorWebPayloadIntoAndroidDir. `cap sync ios` (and a skipped sync)
+ * have both been observed to leave a STALE `ios/App/App/public` — an old entry
+ * hash shipping an ancient UI despite a fresh `dist`. The freshly vite-built
+ * bundle is the source of truth, so overlay it unconditionally: clear the hashed
+ * assets/ then copy dist over public. The on-device agent payload
+ * (`public/agent`) and PGlite root extension assets staged by
+ * stageIosAgentRuntime live OUTSIDE dist and survive — we only clear
+ * `public/assets` and cpSync never deletes existing non-dist files. After the
+ * overlay we assert the staged renderer matches the build so a stale/missing UI
+ * FAILS THE BUILD instead of shipping (issue #9309).
+ */
+function mirrorCapacitorWebPayloadIntoIosDir() {
+  const freshWeb = path.join(appDir, "dist");
+  const targetPublic = path.join(iosDir, "App", "public");
+  overlayFreshRendererIntoPublic(freshWeb, targetPublic, { label: "ios" });
+  console.log(
+    `[mobile-build] Stale-web guard: overlaid fresh ${path.relative(repoRoot, freshWeb)} → ${path.relative(repoRoot, targetPublic)}`,
+  );
+}
+
+/**
+ * Remove the RETIRED llama-cpp-capacitor Android module from the gradle build
+ * entirely — the `include ':llama-cpp-capacitor'` + project line in
+ * capacitor.settings.gradle and the `implementation project(':llama-cpp-capacitor')`
+ * in app/capacitor.build.gradle. `cap sync` re-adds these on every sync because
+ * the package ships an android/ dir, but agent inference runs solely through the
+ * fused libelizainference.so and nothing on Android loads this plugin's separate
+ * libllama-cpp-arm64.so. Leaving the gradle project in only made gradle configure
+ * its CMake — which built a no-op stub and used to require the
+ * ELIZA_ANDROID_SKIP_FORK_LLAMA_LIB opt-out. Dropping the project removes the
+ * stub build outright (no flag needed). iOS is untouched: ios-local-agent-kernel
+ * loads the package via a dynamic import, so the npm dependency stays.
+ *
+ * Opt back into the full second library (not the stub) with
+ * ELIZA_ANDROID_INCLUDE_LLAMA_CPP_CAPACITOR=1. Idempotent.
+ */
+function dropRetiredLlamaCppFromAndroidGradle() {
+  if (
+    process.env.ELIZA_ANDROID_INCLUDE_LLAMA_CPP_CAPACITOR === "1" ||
+    process.env.elizaIncludeLlamaCppCapacitor === "true"
+  ) {
+    return;
+  }
+  const targets = [
+    path.join(androidDir, "capacitor.settings.gradle"),
+    path.join(androidDir, "app", "capacitor.build.gradle"),
+  ];
+  let dropped = false;
+  for (const target of targets) {
+    if (!fs.existsSync(target)) continue;
+    const before = fs.readFileSync(target, "utf8");
+    const after = before
+      .split("\n")
+      .filter((line) => !line.includes("llama-cpp-capacitor"))
+      .join("\n");
+    if (after !== before) {
+      fs.writeFileSync(target, after, "utf8");
+      dropped = true;
+    }
+  }
+  if (dropped) {
+    console.log(
+      "[mobile-build] Dropped retired llama-cpp-capacitor from the Android gradle build (no stub CMake; libelizainference is the sole in-process inference lib).",
+    );
+  }
 }
 
 /**
@@ -1342,22 +1573,19 @@ function reconcilePluginManifestWithGradle(targetAssets) {
     String(pkg ?? "")
       .replace(/@/g, "")
       .replace(/\//g, "-");
-  // When ELIZA_ANDROID_SKIP_FORK_LLAMA_LIB=1 the llama-cpp-capacitor CMake builds
-  // a no-op stub (`ELIZA_SKIP_MTP_ANDROID_LIB`). The stub registers and
-  // System.loadLibrary()s fine, but its JNI methods have no implementation, so a
-  // native call (LlamaCpp.toggleNativeLog during WebView device-bridge init)
-  // raises java.lang.UnsatisfiedLinkError. The call site is now defended — the
-  // patches/llama-cpp-capacitor@0.1.5.patch hardening makes LlamaCpp.toggleNativeLog
-  // catch Throwable and reject the Capacitor call instead of letting the Error
-  // escape to crash MainActivity — so registering the stub no longer kills the
-  // app. We still drop it from the manifest here because a stub Capacitor plugin
-  // is pure dead weight: agent-side local inference (ELIZA_LOCAL_LLAMA, libllama
-  // via bun:ffi) does NOT use this Capacitor plugin, so the device-bridge import
-  // failing as a catchable "LlamaCpp plugin not implemented" JS error costs
-  // nothing and keeps the JS↔native surface honest.
+  // The llama-cpp-capacitor plugin is RETIRED on Android: agent inference runs
+  // entirely through the single fused libelizainference.so, and nothing loads
+  // this plugin's separate libllama-cpp-arm64.so (its JS adapter is retired).
+  // dropRetiredLlamaCppFromAndroidGradle() (called above) removes its gradle
+  // project outright, so its CMake never runs — there is no stub to register
+  // and no ELIZA_ANDROID_SKIP_FORK_LLAMA_LIB opt-out to set. We also drop it from
+  // the plugins manifest here so the LlamaCpp class never auto-registers. The
+  // device-bridge's optional LlamaCpp import resolves to a catchable "plugin not
+  // implemented" JS error, which costs nothing. Opt the full second library back
+  // in (gradle project + manifest) only with ELIZA_ANDROID_INCLUDE_LLAMA_CPP_CAPACITOR=1.
   const stubLlamaCpp =
-    process.env.ELIZA_ANDROID_SKIP_FORK_LLAMA_LIB === "1" ||
-    process.env.elizaSkipForkLlamaLib === "true";
+    process.env.ELIZA_ANDROID_INCLUDE_LLAMA_CPP_CAPACITOR !== "1" &&
+    process.env.elizaIncludeLlamaCppCapacitor !== "true";
   // Third-party Capacitor plugins that `cap sync` includes (they ship an
   // android/ dir, so they ARE in capacitor.settings.gradle) but whose Kotlin
   // plugin class never lands in the app dex on AGP 8.x: both rely on AGP's
@@ -1670,34 +1898,20 @@ export function injectNativeLibLegacyPackaging(content) {
  *
  * Fails local builds when no path is configured or the dir doesn't exist. The
  * Android Capacitor JNI wrapper links against these MTP libraries and cannot
- * honestly support Eliza-1/Qwen3.5 without them. Cloud builds skip the task.
- * CI smoke builds that intentionally install no native deps can opt out with
- * -PelizaSkipForkLlamaLib=true or ELIZA_ANDROID_SKIP_FORK_LLAMA_LIB=1.
+ * honestly support Eliza-1/Gemma 4 without them. Cloud builds skip the task.
+ * A build with no fresh source dir falls back to the already-staged fused lib
+ * set (the common dev case); only a genuinely missing arm64 lib is a hard error.
  *
  * Idempotent: re-runs are no-ops once the block is present.
  */
 function ensureCopyForkLlamaLibGuards(content) {
   if (!/\[copyForkLlamaLib\]/.test(content)) return content;
-  const hasCloudGuard = /skipped for cloud build/.test(content);
-  const hasExplicitSkipGuard =
-    /elizaSkipForkLlamaLib/.test(content) ||
-    /ELIZA_ANDROID_SKIP_FORK_LLAMA_LIB/.test(content);
-  if (hasCloudGuard && hasExplicitSkipGuard) return content;
-  let guards = "";
-  if (!hasCloudGuard) {
-    guards +=
-      `        if (project.findProperty('elizaCloudBuild') == 'true') {\n` +
-      `            println "[copyForkLlamaLib] skipped for cloud build"\n` +
-      `            return\n` +
-      `        }\n`;
-  }
-  if (!hasExplicitSkipGuard) {
-    guards +=
-      `        if (project.findProperty('elizaSkipForkLlamaLib') == 'true' || System.getenv('ELIZA_ANDROID_SKIP_FORK_LLAMA_LIB') == '1') {\n` +
-      `            println "[copyForkLlamaLib] skipped by explicit native-lib opt-out"\n` +
-      `            return\n` +
-      `        }\n`;
-  }
+  if (/skipped for cloud build/.test(content)) return content;
+  const guards =
+    `        if (project.findProperty('elizaCloudBuild') == 'true') {\n` +
+    `            println "[copyForkLlamaLib] skipped for cloud build"\n` +
+    `            return\n` +
+    `        }\n`;
   return content.replace(
     /(task copyForkLlamaLib\s*\{\s*\n\s*doLast\s*\{\s*\n)/,
     `$1${guards}`,
@@ -1710,7 +1924,7 @@ export function injectCopyForkLlamaLibTask(content) {
   }
   const block =
     `\n// Bundle the MTP Android llama.cpp stack into the APK so mobile\n` +
-    `// gets Eliza-1/Qwen3.5 support across every supported Android ABI\n` +
+    `// gets Eliza-1/Gemma 4 support across every supported Android ABI\n` +
     `// (arm64-v8a, x86_64, riscv64). The arm64-v8a slice is mandatory for\n` +
     `// local-agent capable builds; x86_64 and riscv64 ship when their\n` +
     `// per-ABI artifacts exist (Wave 2 cross-compiles land them\n` +
@@ -1783,25 +1997,35 @@ export function injectCopyForkLlamaLibTask(content) {
     `    return null\n` +
     `}\n` +
     `\n` +
+    `// NOTE: despite the legacy "ForkLlama" name, this stages the SINGLE canonical\n` +
+    `// fused inference lib — libelizainference.so — with its own DT_NEEDED runtime\n` +
+    `// siblings (libggml*, libllama.so, libllama-common.so, libmtmd.so, libomp.so),\n` +
+    `// which ARE libelizainference's GPU/CPU backends, NOT a separate llama.cpp fork.\n` +
+    `// There is no second inference library; do NOT delete this task or its siblings.\n` +
     `task copyForkLlamaLib {\n` +
     `    doLast {\n` +
     `        if (project.findProperty('elizaCloudBuild') == 'true') {\n` +
     `            println "[copyForkLlamaLib] skipped for cloud build"\n` +
     `            return\n` +
     `        }\n` +
-    `        if (project.findProperty('elizaSkipForkLlamaLib') == 'true' || System.getenv('ELIZA_ANDROID_SKIP_FORK_LLAMA_LIB') == '1') {\n` +
-    `            println "[copyForkLlamaLib] skipped by explicit native-lib opt-out"\n` +
-    `            return\n` +
-    `        }\n` +
     `        boolean stagedArm64 = false\n` +
     `        int totalCopied = 0\n` +
     `        boolean stagedKernels = false\n` +
     `        project.ext.elizaForkLlamaAbis.each { abi ->\n` +
     `            def libDir = resolveForkLlamaLibDir(abi)\n` +
     `            if (!libDir) {\n` +
+    `                // No fresh source configured. If the fused lib set is already\n` +
+    `                // staged in jniLibs (a prior build, the common dev case), use it\n` +
+    `                // as-is so a plain build:android "just works" without any flag.\n` +
+    `                def alreadyStaged = new File(file("src/main/jniLibs/\${abi}"), 'libelizainference.so')\n` +
+    `                if (alreadyStaged.isFile()) {\n` +
+    `                    logger.lifecycle("[copyForkLlamaLib] no source dir for \${abi}; libelizainference.so already staged in jniLibs — using the pre-staged fused lib set")\n` +
+    `                    if (abi == 'arm64-v8a') stagedArm64 = true\n` +
+    `                    return\n` +
+    `                }\n` +
     `                if (abi == 'arm64-v8a') {\n` +
-    `                    // arm64-v8a is the mandatory baseline ABI; missing it is a hard error.\n` +
-    `                    throw new GradleException("[copyForkLlamaLib] no MTP Android lib dir configured for arm64-v8a. Run packages/app-core/scripts/aosp/compile-libllama.mjs --target android-arm64-vulkan-fused (the Android cross-compiler; build-llama-cpp-mtp.mjs has no Android targets) or set -Peliza.mtp.android.libdir / ELIZA_MTP_ANDROID_LIBDIR.")\n` +
+    `                    // arm64-v8a is the mandatory baseline ABI; missing it (and no pre-staged lib) is a hard error.\n` +
+    `                    throw new GradleException("[copyForkLlamaLib] no fused inference lib for arm64-v8a (not configured, not pre-staged). Run packages/app-core/scripts/aosp/compile-libllama.mjs --target android-arm64-vulkan-fused (the Android cross-compiler; build-llama-cpp-mtp.mjs has no Android targets) or set -Peliza.mtp.android.libdir / ELIZA_MTP_ANDROID_LIBDIR.")\n` +
     `                }\n` +
     `                logger.lifecycle("[copyForkLlamaLib] no fork lib dir for ABI \${abi}; skipping")\n` +
     `                return\n` +
@@ -2540,7 +2764,20 @@ export function validateAndroidAppActionsXmlResource(
   return failures;
 }
 
+function assertSharedTreeOnlyForEliza(what) {
+  if (
+    APP.appId !== "ai.elizaos.app" &&
+    path.resolve(androidDir) === path.resolve(platformsDir, "android")
+  ) {
+    throw new Error(
+      `[mobile-build] Refusing to ${what} for brand '${APP.appId}' in the shared elizaOS android tree (${androidDir}). ` +
+        "Whitelabel builds must use apps/app/android (set ELIZA_ANDROID_USE_APP_DIR=1); the elizaOS build owns the shared tree.",
+    );
+  }
+}
+
 function syncAndroidAppActionsResources() {
+  assertSharedTreeOnlyForEliza("patch app-actions resources");
   const templateResDir = path.join(
     platformsDir,
     "android",
@@ -2690,6 +2927,7 @@ function restoreAndroidManifestFromPlatformTemplateIfMissing() {
 }
 
 function overlayAndroid({ includeAospRoleLaunchers = false } = {}) {
+  assertSharedTreeOnlyForEliza("overlay Java sources");
   const templateJavaRoot = path.join(
     platformsDir,
     "android",
@@ -2806,7 +3044,23 @@ function overlayAndroid({ includeAospRoleLaunchers = false } = {}) {
         code = injectBrandUserAgentMarkers(code, APP.userAgentMarkers ?? []);
       }
       fs.writeFileSync(path.join(dstJava, file), code, "utf8");
-      if (path.resolve(src) !== path.resolve(path.join(dstJava, file))) {
+      // Rewrite the legacy-package copy's R/BuildConfig imports so any file left
+      // behind in the old package still resolves — but ONLY when that copy lives
+      // in THIS build's own android dir. NEVER write into the shared elizaOS
+      // template tree (platforms/android): a whitelabel build
+      // (ELIZA_ANDROID_USE_APP_DIR) reads that template READ-ONLY, and writing
+      // the brand package back into it corrupts the elizaOS checkout's
+      // ai/elizaos/app sources (the recurring "package ai.milady.app does not
+      // exist" pollution that breaks the next elizaOS build). srcJava resolves
+      // to templateJava for a whitelabel build, so this guard is what keeps the
+      // two brands' source trees separate.
+      const srcInOwnAndroidDir = path
+        .resolve(src)
+        .startsWith(`${path.resolve(androidDir)}${path.sep}`);
+      if (
+        srcInOwnAndroidDir &&
+        path.resolve(src) !== path.resolve(path.join(dstJava, file))
+      ) {
         const legacyCode = fs
           .readFileSync(src, "utf8")
           .replaceAll(
@@ -3699,7 +3953,14 @@ function shouldSkipIosPodInstall(env = process.env) {
   return isTruthyEnv(env.ELIZA_IOS_SKIP_POD_INSTALL);
 }
 
-function shouldIncludeIosFullBunEngine(env = process.env) {
+// An iOS build ships the on-device no-JIT Bun engine (and thus a real local
+// agent) when it is explicitly requested, OR when it is a store/App Store build
+// with the local runtime left enabled (the default). App Store builds are
+// cloud-hybrid: they keep the App Store-safe local runtime unless an operator
+// opts into a cloud-only thin client via ELIZA_IOS_APP_STORE_LOCAL_RUNTIME=0.
+// Exported so the release preflight + tests share one definition of "will the
+// shipped IPA actually contain a local agent runtime".
+export function shouldIncludeIosFullBunEngine(env = process.env) {
   return (
     isFullIosBunEngineRequested(env) ||
     (isIosAppStoreBuild(env) && isIosAppStoreLocalRuntimeEnabled(env))
@@ -4061,6 +4322,7 @@ function patchInstalledLlamaCapacitorBuildGradle() {
 }
 
 function patchAndroidGradle() {
+  assertSharedTreeOnlyForEliza("patch gradle identity");
   patchAndroidGradleWrapperForReleaseCompat();
   patchAndroidGradleProperties();
   patchInstalledLlamaCapacitorBuildGradle();
@@ -4529,6 +4791,7 @@ async function generateIosBrandAssets() {
 }
 
 async function generateAndroidBrandAssets() {
+  assertSharedTreeOnlyForEliza("write brand icons");
   const resDir = path.join(androidDir, "app", "src", "main", "res");
   if (!fs.existsSync(resDir)) return;
 
@@ -4729,17 +4992,55 @@ function mtpTargetOutDir(target) {
   );
 }
 
+function resolveMtpForkSrc() {
+  for (const candidate of MTP_FORK_SRC_CANDIDATES) {
+    if (fs.existsSync(path.join(candidate, "CMakeLists.txt"))) return candidate;
+  }
+  return null;
+}
+
+/** `git describe --always --dirty` of the fork, or null when git/desc fails. */
+function currentMtpForkRevision(forkSrc) {
+  if (!forkSrc) return null;
+  const result = spawnSync(
+    "git",
+    ["-C", forkSrc, "describe", "--always", "--dirty"],
+    { encoding: "utf8" },
+  );
+  if (result.status !== 0) return null;
+  return result.stdout?.trim() || null;
+}
+
 async function ensureMtpIosTarget(target) {
   const outDir = mtpTargetOutDir(target);
   const capabilities = path.join(outDir, "CAPABILITIES.json");
-  if (fs.existsSync(capabilities)) {
+  const forkSrc = resolveMtpForkSrc();
+  const reuse = mtpSliceReuse(
+    capabilities,
+    forkSrc,
+    currentMtpForkRevision(forkSrc),
+  );
+  const forceRebuild = mtpForceRebuildRequested(reuse, process.env);
+  if (!forceRebuild) {
     console.log(
-      `[mobile-build] Reusing existing mtp artifact for ${target} at ${outDir}`,
+      `[mobile-build] Reusing fresh mtp artifact for ${target} at ${outDir}`,
     );
     return outDir;
   }
-  console.log(`[mobile-build] Building mtp artifact for ${target}`);
-  await run("node", [MTP_BUILD_SCRIPT, "--target", target]);
+  if (fs.existsSync(capabilities)) {
+    console.log(
+      `[mobile-build] Rebuilding mtp artifact for ${target} — ${process.env.ELIZA_IOS_REBUILD_MTP === "1" ? "ELIZA_IOS_REBUILD_MTP=1" : reuse.reason}`,
+    );
+  } else {
+    console.log(`[mobile-build] Building mtp artifact for ${target}`);
+  }
+  // The child builder (build-llama-cpp-mtp.mjs) has its OWN presence-only reuse
+  // gate keyed on ELIZA_MTP_FORCE_REBUILD. Without propagating it, the child
+  // would see the stale CAPABILITIES.json and reuse it — turning this staleness
+  // gate into a no-op. Force the child to actually rebuild (#9309).
+  await run("node", [MTP_BUILD_SCRIPT, "--target", target], {
+    env: { ...process.env, ELIZA_MTP_FORCE_REBUILD: "1" },
+  });
   if (!fs.existsSync(capabilities)) {
     throw new Error(
       `[mobile-build] mtp build for ${target} did not produce CAPABILITIES.json at ${capabilities}. ` +
@@ -7162,6 +7463,8 @@ async function buildAndroidSystem() {
     androidDir,
     spikeDir: androidAgentSpikeDir,
     bunChannel: "canary",
+    // Objective AOSP/chip image: riscv64 bun stays fail-closed (it ships it).
+    objective: true,
   });
   auditAndroidSystemSource("pre-gradle");
 
@@ -7329,6 +7632,11 @@ async function buildIos({ local = false } = {}) {
   } else {
     await runCapacitor(["sync", "ios"]);
   }
+  // Overlay the freshly built renderer onto ios/App/App/public and assert it
+  // matches the build — never ship a stale UI whether sync ran, was skipped, or
+  // left old hashed assets behind (issue #9309). Runs before the post-sync agent
+  // re-stage so the agent payload remains the final authority on public/agent.
+  mirrorCapacitorWebPayloadIntoIosDir();
   if (includesLocalAgentPayload) {
     stageIosAgentRuntime({
       appStoreBuild: isIosAppStoreBuild() && !local,
@@ -7445,6 +7753,20 @@ export async function main(argv = process.argv.slice(2)) {
   } else {
     prepareIosOverlay();
     await generateIosBrandAssets();
+    // The App Store release pipeline splits the build into `bun run build`
+    // (web) + `cap:sync:ios` + this overlay + fastlane, so it never runs
+    // buildIos()'s local-agent staging. When the build embeds the full Bun
+    // engine, stage the agent runtime payload here (after cap sync, before
+    // pod install / fastlane archive) so the shipped IPA actually contains the
+    // agent the engine runs — without it the engine boots with nothing to
+    // execute. The agent bundle must already be built (packages/agent
+    // build:ios-bun); stageIosAgentRuntime throws with that hint if missing.
+    if (shouldIncludeIosFullBunEngine()) {
+      stageIosAgentRuntime({
+        appStoreBuild: isIosAppStoreBuild(),
+        includeFullBunEngine: true,
+      });
+    }
   }
 }