neoagent 2.3.1-beta.87 → 2.3.1-beta.89

package/server/services/android/controller.js

@@ -20,7 +20,6 @@ const TMP_DIR = path.join(ARTIFACTS_DIR, 'tmp');
 const EMULATOR_HOME = path.join(ANDROID_ROOT, 'home');
 const EMULATOR_ADVANCED_FEATURES_FILE = path.join(EMULATOR_HOME, 'advancedFeatures.ini');
 const AVD_HOME = path.join(ANDROID_ROOT, 'avd');
-const EMULATOR_READY_SNAPSHOT = 'neoagent-ready';
 const STATE_DIR = path.join(ARTIFACTS_DIR, 'state');
 const STATE_FILE = path.join(ARTIFACTS_DIR, 'state.json');
 const OWNERSHIP_FILE = path.join(ARTIFACTS_DIR, 'device-ownership.json');
@@ -53,19 +52,17 @@ for (const dir of [ANDROID_ROOT, SDK_ROOT, EMULATOR_HOME, ARTIFACTS_DIR, SCREENS
 }
 
 function ensureEmulatorAdvancedFeaturesFile() {
-  const content = [
-    'Vulkan = off',
-    'GLDirectMem = off',
-    '',
-  ].join('\n');
   try {
-    if (fs.existsSync(EMULATOR_ADVANCED_FEATURES_FILE)) {
-      const current = fs.readFileSync(EMULATOR_ADVANCED_FEATURES_FILE, 'utf8');
-      if (current.trim() === content.trim()) {
-        return;
-      }
-    }
-    fs.writeFileSync(EMULATOR_ADVANCED_FEATURES_FILE, content);
+    fs.mkdirSync(path.dirname(EMULATOR_ADVANCED_FEATURES_FILE), { recursive: true });
+    fs.writeFileSync(
+      EMULATOR_ADVANCED_FEATURES_FILE,
+      [
+        'QuickbootFileBacked=off',
+        'QuickbootSupport=off',
+        '',
+      ].join('\n'),
+      'utf8',
+    );
   } catch {}
 }
 
@@ -103,7 +100,7 @@ function readOwnershipUnlocked() {
     if (!parsed || typeof parsed !== 'object') {
       return {};
     }
-  return parsed;
+    return parsed;
   } catch {
     return {};
   }
@@ -185,6 +182,19 @@ function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
+function isProcessAlive(pid) {
+  const numericPid = Number(pid);
+  if (!Number.isInteger(numericPid) || numericPid <= 0) {
+    return false;
+  }
+  try {
+    process.kill(numericPid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 function tailFile(filePath, maxLines = 40) {
   try {
     const lines = fs.readFileSync(filePath, 'utf8')
@@ -197,6 +207,15 @@ function tailFile(filePath, maxLines = 40) {
   }
 }
 
+function isLikelyPng(buffer) {
+  return Buffer.isBuffer(buffer)
+    && buffer.length > 24
+    && buffer[0] === 0x89
+    && buffer[1] === 0x50
+    && buffer[2] === 0x4e
+    && buffer[3] === 0x47;
+}
+
 function commandExists(command) {
   const probe = spawnSync('bash', ['-lc', `command -v "${command}"`], { encoding: 'utf8' });
   return probe.status === 0;
@@ -265,25 +284,40 @@ function emulatorHostArch() {
 }
 
 function emulatorGpuMode() {
-  return 'swiftshader_indirect';
-}
-
-function emulatorSnapshotStoragePath(avdName) {
-  return path.join(AVD_HOME, `${avdName}.avd`, 'snapshots.img');
-}
-
-function emulatorLaunchArgs(avdName) {
   if (process.platform === 'darwin' && process.arch === 'arm64') {
-    return ['-no-snapshot'];
+    return 'swiftshader_indirect';
   }
+  if (process.platform === 'linux' && process.arch === 'arm64') {
+    return 'swiftshader_indirect';
+  }
+  return 'auto';
+}
+
+function emulatorLaunchArgs() {
   return [
-    '-snapshot',
-    EMULATOR_READY_SNAPSHOT,
-    '-snapstorage',
-    emulatorSnapshotStoragePath(avdName),
+    '-no-snapshot',
+    '-no-snapshot-save',
+    '-no-window',
+    '-no-audio',
+    '-no-metrics',
+    '-skip-adb-auth',
+    '-crash-report-mode',
+    'disabled',
   ];
 }
 
+function isRecoverableEmulatorStartError(message) {
+  const value = String(message || '').toLowerCase();
+  return (
+    value.includes('failed to restore previous context') ||
+    value.includes('emulator exited before boot completed') ||
+    value.includes('android framework did not become ready') ||
+    value.includes('package manager service did not become ready') ||
+    value.includes('failed to process .ini file') ||
+    value.includes('error while loading state for instance')
+  );
+}
+
 function parseCsvEnv(value) {
   return String(value || '')
     .split(',')
@@ -345,6 +379,15 @@ function parseSystemImagePlatform(platformId) {
     };
   }
 
+  const released = String(platformId || '').match(/^android-(\d+(?:\.\d+)?)$/);
+  if (released) {
+    return {
+      platformId,
+      apiLevel: Math.floor(Number(released[1]) || 0),
+      stable: false,
+    };
+  }
+
   const preview = String(platformId || '').match(/^android-([A-Za-z][A-Za-z0-9_-]*)$/);
   if (preview) {
     return {
@@ -415,10 +458,10 @@ function hostAndroidSdkRoot() {
   return null;
 }
 
-const SHARED_ANDROID_SDK_ROOT = hostAndroidSdkRoot();
+const SHARED_ANDROID_SDK_ROOT = null;
 
 function activeAndroidSdkRoot() {
-  return SHARED_ANDROID_SDK_ROOT || SDK_ROOT;
+  return SDK_ROOT;
 }
 
 function sharedAndroidSdkReady() {
@@ -436,20 +479,6 @@ function adbBinary() {
   if (process.env.ANDROID_ADB_PATH) {
     return process.env.ANDROID_ADB_PATH;
   }
-  if (SHARED_ANDROID_SDK_ROOT) {
-    const sharedAdb = path.join(SHARED_ANDROID_SDK_ROOT, 'platform-tools', process.platform === 'win32' ? 'adb.exe' : 'adb');
-    if (isExecutable(sharedAdb)) {
-      return sharedAdb;
-    }
-  }
-  const hostAdb = hostAdbBinary();
-  if (hostAdb) {
-    return hostAdb;
-  }
-  const distroAdb = systemAdbBinary();
-  if (process.platform === 'linux' && process.arch === 'arm64' && distroAdb && isExecutable(distroAdb)) {
-    return distroAdb;
-  }
   return path.join(SDK_ROOT, 'platform-tools', process.platform === 'win32' ? 'adb.exe' : 'adb');
 }
 
@@ -797,17 +826,8 @@ async function installPlatformToolsArchive(metadata) {
 }
 
 function shouldInstallPlatformToolsArchive() {
-  if (SHARED_ANDROID_SDK_ROOT) {
-    return false;
-  }
-  if (hostAdbBinary()) {
-    return false;
-  }
-  const distroAdb = systemAdbBinary();
-  if (process.platform === 'linux' && process.arch === 'arm64' && distroAdb && isExecutable(distroAdb)) {
-    return false;
-  }
-  return true;
+  const localAdb = path.join(SDK_ROOT, 'platform-tools', process.platform === 'win32' ? 'adb.exe' : 'adb');
+  return !isExecutable(localAdb);
 }
 
 async function installSystemImageArchive(metadata, packageName) {
@@ -817,6 +837,8 @@ async function installSystemImageArchive(metadata, packageName) {
   const extractDir = fs.mkdtempSync(path.join(TMP_DIR, 'system-image-'));
 
   try {
+    fs.rmSync(targetRoot, { recursive: true, force: true });
+    fs.mkdirSync(path.dirname(targetRoot), { recursive: true });
     await downloadFile(url, zipPath);
     extractZip(zipPath, extractDir);
 
@@ -827,9 +849,15 @@ async function installSystemImageArchive(metadata, packageName) {
       throw new Error(`Downloaded Android system image archive for ${packageName} did not contain the expected files`);
     }
 
-    fs.rmSync(targetRoot, { recursive: true, force: true });
-    fs.mkdirSync(path.dirname(targetRoot), { recursive: true });
-    fs.cpSync(extractedRoot, targetRoot, { recursive: true, force: true });
+    fs.rmSync(zipPath, { force: true });
+    try {
+      fs.renameSync(extractedRoot, targetRoot);
+    } catch (renameErr) {
+      fs.cpSync(extractedRoot, targetRoot, { recursive: true, force: true });
+      if (renameErr) {
+        console.warn(`[Android] Falling back to copy for ${packageName}: ${renameErr.message}`);
+      }
+    }
   } finally {
     fs.rmSync(zipPath, { force: true });
     fs.rmSync(extractDir, { recursive: true, force: true });
@@ -838,8 +866,8 @@ async function installSystemImageArchive(metadata, packageName) {
 
 function systemImageTagScore(tag) {
   const value = String(tag || '').toLowerCase();
-  if (value.startsWith('google_apis_playstore')) return 60;
-  if (value.startsWith('google_apis')) return 50;
+  if (value.startsWith('google_apis_playstore')) return 80;
+  if (value.startsWith('google_apis')) return 60;
   if (value === 'default') return 40;
   if (value === 'google_atd') return 20;
   if (value === 'aosp_atd') return 10;
@@ -917,6 +945,25 @@ function parseInstalledSystemImages() {
   return parseSystemImageCandidates(matches);
 }
 
+function chooseStableRuntimeSystemImage(candidates, currentPackage) {
+  const normalizedCurrent = String(currentPackage || '').trim();
+  const pool = Array.isArray(candidates)
+    ? candidates.filter((item) => item && item.packageName && isValidInstalledSystemImage(item.packageName))
+    : [];
+  if (pool.length === 0) return null;
+  const ranked = rankSystemImagePool(pool);
+  const recommended = ranked.find((item) =>
+    item.arch === 'arm64-v8a'
+    && item.stable
+    && item.apiLevel >= 33
+  ) || ranked[0];
+  if (!recommended) return null;
+  if (normalizedCurrent && recommended.packageName === normalizedCurrent) {
+    return null;
+  }
+  return recommended;
+}
+
 function rankSystemImagePool(pool) {
   const preferredMatches = pool.filter((candidate) => candidate.tagScore > 0);
   const rankedPool = preferredMatches.length > 0 ? preferredMatches : pool;
@@ -1034,6 +1081,18 @@ function systemImagePackageToRelativeDir(packageName) {
   return `${parts.join('/')}/`;
 }
 
+function isValidInstalledSystemImage(packageName) {
+  const relativeDir = systemImagePackageToRelativeDir(packageName);
+  if (!relativeDir) return false;
+  const root = path.join(activeAndroidSdkRoot(), relativeDir);
+  const required = [
+    path.join(root, 'package.xml'),
+    path.join(root, 'system.img'),
+    path.join(root, 'userdata.img'),
+  ];
+  return required.every((filePath) => fs.existsSync(filePath));
+}
+
 function systemImagePackageToAbi(packageName) {
   const parts = String(packageName || '').split(';').filter(Boolean);
   if (parts.length !== 4 || parts[0] !== 'system-images') {
@@ -1083,6 +1142,7 @@ class AndroidController {
     this.userId = options?.userId != null ? String(options.userId) : null;
     this.artifactStore = options?.artifactStore || null;
     this.runtimeBackend = options?.runtimeBackend || 'host';
+    this.manageProcessCleanup = options?.manageProcessCleanup !== false;
     this.scopeKey = sanitizeScopeKey(this.userId ? `user-${this.userId}` : 'default');
     this.ownerKey = normalizeOwnerKey(this.userId);
     this.stateFile = resolveStateFile(this.scopeKey);
@@ -1122,7 +1182,9 @@ class AndroidController {
     }
     this.bootstrapPromise = null;
     this.startPromise = null;
-    this.#registerProcessCleanup();
+    if (this.manageProcessCleanup) {
+      this.#registerProcessCleanup();
+    }
   }
 
   static cleanupRegistered = false;
@@ -1336,20 +1398,37 @@ class AndroidController {
       chooseConfiguredSystemImage(available) ||
       chooseLatestSystemImage(available, [desiredArch]) ||
       chooseLatestSystemImage(available);
+    const selectedImage = rankSystemImagePool([preferredInstalled, preferredAvailable].filter(Boolean))[0] || preferredInstalled || preferredAvailable;
     const stateApiLevel = Number(state.apiLevel || 0) || 0;
-
-    if (!shouldForceSdkRefresh() && sharedAndroidSdkReady() && preferredInstalled && preferredAvailable) {
+    const legacyLinuxArm64Image =
+      process.platform === 'linux'
+      && process.arch === 'arm64'
+      && /system-images;android-30;default;arm64-v8a/i.test(String(state.systemImage || ''));
+    const migrationTargetImage =
+      process.platform === 'linux' && process.arch === 'arm64'
+        ? (
+            rankSystemImagePool(
+              [preferredAvailable, preferredInstalled]
+                .filter(Boolean)
+                .filter((image) => image.arch === 'arm64-v8a' && image.stable && image.apiLevel >= 33)
+            )[0] || null
+          )
+        : null;
+    const effectiveSelectedImage = migrationTargetImage || selectedImage;
+    const selectedImageInvalid = effectiveSelectedImage?.packageName && !isValidInstalledSystemImage(effectiveSelectedImage.packageName);
+
+    if (!shouldForceSdkRefresh() && !legacyLinuxArm64Image && !selectedImageInvalid && sharedAndroidSdkReady() && effectiveSelectedImage) {
       const stateAligned =
-        preferredInstalled.packageName === state.systemImage &&
-        preferredInstalled.apiLevel === stateApiLevel &&
-        preferredInstalled.arch === state.systemImageArch &&
+        effectiveSelectedImage.packageName === state.systemImage &&
+        effectiveSelectedImage.apiLevel === stateApiLevel &&
+        effectiveSelectedImage.arch === state.systemImageArch &&
         state.avdName === this.avdName;
 
-      if (stateAligned && preferredInstalled.packageName === preferredAvailable.packageName) {
+      if (stateAligned) {
         return;
       }
 
-      if (preferredInstalled.packageName !== preferredAvailable.packageName) {
+      if (effectiveSelectedImage === preferredInstalled && effectiveSelectedImage.packageName) {
         const changeSummary = describeAutoFixChanges(
           {
             avdName: state.avdName || null,
@@ -1359,38 +1438,26 @@ class AndroidController {
           },
           {
             avdName: this.avdName,
-            systemImage: preferredAvailable.packageName,
-            apiLevel: preferredAvailable.apiLevel,
-            systemImageArch: preferredAvailable.arch,
+            systemImage: effectiveSelectedImage.packageName,
+            apiLevel: effectiveSelectedImage.apiLevel,
+            systemImageArch: effectiveSelectedImage.arch,
           },
           ['avdName', 'systemImage', 'apiLevel', 'systemImageArch']
         );
         if (changeSummary) {
           console.log(`[Android] Auto-fixed host SDK state (${changeSummary})`);
         }
-        await installSystemImageArchive(systemImageMetadata, preferredAvailable.packageName);
         this.#appendState({
           bootstrapped: true,
           avdName: this.avdName,
           serial: null,
           emulatorPid: null,
-          systemImage: preferredAvailable.packageName,
-          apiLevel: preferredAvailable.apiLevel,
-          systemImageArch: preferredAvailable.arch,
+          systemImage: effectiveSelectedImage.packageName,
+          apiLevel: effectiveSelectedImage.apiLevel,
+          systemImageArch: effectiveSelectedImage.arch,
         });
         return;
       }
-
-      this.#appendState({
-        bootstrapped: true,
-        avdName: this.avdName,
-        serial: null,
-        emulatorPid: null,
-        systemImage: preferredInstalled.packageName,
-        apiLevel: preferredInstalled.apiLevel,
-        systemImageArch: preferredInstalled.arch,
-      });
-      return;
     }
 
     const binariesReady =
@@ -1413,12 +1480,12 @@ class AndroidController {
     const runtimeNeedsRefresh =
       state.systemImageArch !== desiredArch ||
       !installedEmulatorMatchesHost();
-    if (!shouldForceSdkRefresh()) {
-      if (!runtimeNeedsRefresh && preferredInstalled) {
+    if (!shouldForceSdkRefresh() && !legacyLinuxArm64Image && !selectedImageInvalid) {
+      if (!runtimeNeedsRefresh && effectiveSelectedImage && effectiveSelectedImage === preferredInstalled) {
         const stateNeedsRefresh =
-          preferredInstalled.packageName !== state.systemImage ||
-          preferredInstalled.apiLevel !== stateApiLevel ||
-          preferredInstalled.arch !== state.systemImageArch ||
+          effectiveSelectedImage.packageName !== state.systemImage ||
+          effectiveSelectedImage.apiLevel !== stateApiLevel ||
+          effectiveSelectedImage.arch !== state.systemImageArch ||
           state.avdName !== this.avdName;
         if (stateNeedsRefresh) {
           const changeSummary = describeAutoFixChanges(
@@ -1430,9 +1497,9 @@ class AndroidController {
             },
             {
               avdName: this.avdName,
-              systemImage: preferredInstalled.packageName,
-              apiLevel: preferredInstalled.apiLevel,
-              systemImageArch: preferredInstalled.arch,
+              systemImage: effectiveSelectedImage.packageName,
+              apiLevel: effectiveSelectedImage.apiLevel,
+              systemImageArch: effectiveSelectedImage.arch,
             },
             ['avdName', 'systemImage', 'apiLevel', 'systemImageArch']
           );
@@ -1444,14 +1511,20 @@ class AndroidController {
             avdName: this.avdName,
             serial: null,
             emulatorPid: null,
-            systemImage: preferredInstalled.packageName,
-            apiLevel: preferredInstalled.apiLevel,
-            systemImageArch: preferredInstalled.arch,
+            systemImage: effectiveSelectedImage.packageName,
+            apiLevel: effectiveSelectedImage.apiLevel,
+            systemImageArch: effectiveSelectedImage.arch,
           });
         }
         return;
       }
-      if (!runtimeNeedsRefresh && state.bootstrapped === true && state.systemImage) {
+      if (
+        !runtimeNeedsRefresh &&
+        state.bootstrapped === true &&
+        state.systemImage &&
+        effectiveSelectedImage &&
+        effectiveSelectedImage.packageName === state.systemImage
+      ) {
         return;
       }
     }
@@ -1462,17 +1535,19 @@ class AndroidController {
       await installPlatformToolsArchive(metadata);
     }
     await installEmulatorArchive(metadata);
-    await installSystemImageArchive(systemImageMetadata, preferredAvailable?.packageName || preferredInstalled?.packageName);
-    const selectedImage = preferredAvailable || preferredInstalled;
-    if (!selectedImage) {
+    if (!effectiveSelectedImage) {
       throw new Error(formatSystemImageError(available));
     }
+    if (effectiveSelectedImage?.packageName) {
+      await installSystemImageArchive(systemImageMetadata, effectiveSelectedImage.packageName);
+    }
     this.#appendState({
       bootstrapped: true,
       avdName: this.avdName,
-      systemImage: selectedImage.packageName,
-      apiLevel: selectedImage.apiLevel,
-      systemImageArch: selectedImage.arch,
+      systemImage: effectiveSelectedImage.packageName,
+      apiLevel: effectiveSelectedImage.apiLevel,
+      systemImageArch: effectiveSelectedImage.arch,
+      avdSystemImage: null,
     });
   }
 
@@ -1531,6 +1606,7 @@ class AndroidController {
       startupPhase: 'Start failed',
       lastStartError: detailedMessage,
       lastLogLine: detailedMessage,
+      bootstrapWorkerPid: null,
     });
     return detailedMessage;
   }
@@ -1539,8 +1615,22 @@ class AndroidController {
     await this.ensureBootstrapped();
 
     const state = this.#readState();
-    const pkg = state.systemImage;
+    let pkg = state.systemImage;
     if (!pkg) throw new Error('Android system image not installed');
+    if (process.platform === 'linux' && process.arch === 'arm64') {
+      const installedCandidates = parseInstalledSystemImages();
+      const migratedImage = chooseStableRuntimeSystemImage(installedCandidates, pkg);
+      if (migratedImage) {
+        pkg = migratedImage.packageName;
+        this.#appendState({
+          systemImage: pkg,
+          apiLevel: migratedImage.apiLevel,
+          systemImageArch: migratedImage.arch,
+          avdSystemImage: null,
+          lastLogLine: `Migrated Android runtime image to ${pkg} for stability.`,
+        });
+      }
+    }
     const avdDir = path.join(AVD_HOME, `${this.avdName}.avd`);
     const configPath = path.join(avdDir, 'config.ini');
     const avdExists = fs.existsSync(configPath);
@@ -1566,6 +1656,8 @@ class AndroidController {
         const expectedRamSize = String(DEFAULT_RAM_SIZE_MB);
         const currentGpuMode = readIniValue(config, 'hw.gpu.mode');
         const expectedGpuMode = emulatorGpuMode();
+        const currentPlayStoreEnabled = readIniValue(config, 'PlayStore.enabled');
+        const expectedPlayStoreEnabled = String(String(pkg || '').includes('playstore'));
         if (expectedImageDir && currentImageDir && currentImageDir !== expectedImageDir) {
           avdNeedsRecreate = true;
           avdRecreateReasons.push(`image.sysdir.1: ${currentImageDir} -> ${expectedImageDir}`);
@@ -1594,6 +1686,10 @@ class AndroidController {
           avdNeedsRecreate = true;
           avdRecreateReasons.push(`hw.gpu.mode: ${currentGpuMode} -> ${expectedGpuMode}`);
         }
+        if (currentPlayStoreEnabled && currentPlayStoreEnabled !== expectedPlayStoreEnabled) {
+          avdNeedsRecreate = true;
+          avdRecreateReasons.push(`PlayStore.enabled: ${currentPlayStoreEnabled} -> ${expectedPlayStoreEnabled}`);
+        }
       } catch {}
     }
 
@@ -1605,7 +1701,6 @@ class AndroidController {
       fs.rmSync(avdDir, { recursive: true, force: true });
       fs.rmSync(path.join(AVD_HOME, `${this.avdName}.ini`), { force: true });
       fs.rmSync(path.join(avdDir, 'userdata-qemu.img'), { force: true });
-      fs.rmSync(emulatorSnapshotStoragePath(this.avdName), { force: true });
     } else if (avdExists) {
       ensureSparseFile(path.join(avdDir, 'userdata-qemu.img'), DEFAULT_DATA_PARTITION_BYTES);
       return;
@@ -1625,6 +1720,7 @@ class AndroidController {
     const tagId = parts[2];
     const tagDisplay = tagId === 'google_apis' ? 'Google APIs' : tagId.replace(/_/g, ' ');
     const abi = parts[3];
+    const playStoreEnabled = tagId.includes('playstore');
     const avdDir = path.join(AVD_HOME, `${this.avdName}.avd`);
     const imageSysDir = systemImagePackageToRelativeDir(packageName);
     if (!imageSysDir) {
@@ -1648,7 +1744,7 @@ class AndroidController {
       'avd.ini.encoding=UTF-8',
       `AvdId=${this.avdName}`,
       `avd.ini.displayname=${this.avdName}`,
-      'PlayStore.enabled=false',
+      `PlayStore.enabled=${playStoreEnabled}`,
       `image.sysdir.1=${imageSysDir}`,
       `abi.type=${abi}`,
       `hw.cpu.arch=${systemImagePackageToCpuArch(packageName) || abi}`,
@@ -1671,6 +1767,8 @@ class AndroidController {
       `sdcard.size=${DEFAULT_SDCARD_SIZE_BYTES}`,
       'runtime.network.latency=none',
       'runtime.network.speed=full',
+      'fastboot.forceColdBoot=yes',
+      'fastboot.forceFastBoot=no',
       'vm.heapSize=256',
       `tag.display=${tagDisplay}`,
       `tag.id=${tagId}`,
@@ -1683,7 +1781,6 @@ class AndroidController {
     if (fs.existsSync(userdataImage)) {
       fs.copyFileSync(userdataImage, path.join(avdDir, 'userdata.img'));
     }
-    fs.rmSync(emulatorSnapshotStoragePath(this.avdName), { force: true });
   }
 
   #normalizeAvdConfig() {
@@ -1695,9 +1792,60 @@ class AndroidController {
     content = updateIniValue(content, 'sdcard.size', DEFAULT_SDCARD_SIZE_BYTES);
     content = updateIniValue(content, 'hw.ramSize', DEFAULT_RAM_SIZE_MB);
     content = updateIniValue(content, 'hw.gpu.mode', emulatorGpuMode());
+    content = updateIniValue(content, 'fastboot.forceColdBoot', 'yes');
+    content = updateIniValue(content, 'fastboot.forceFastBoot', 'no');
+    content = updateIniValue(content, 'PlayStore.enabled', String(this.#readState()?.systemImage || '').includes('playstore'));
     fs.writeFileSync(configPath, content);
   }
 
+  #cleanupAvdTransientState() {
+    const avdDir = path.join(AVD_HOME, `${this.avdName}.avd`);
+    const transientTargets = [
+      'cache.img',
+      'cache.img.qcow2',
+      'hardware-qemu.ini.lock',
+      'multiinstance.lock',
+      'snapshot.lock',
+      'quickbootChoice.ini',
+      'launchParams.txt',
+      'emu-launch-params.txt',
+      'bootcompleted.ini',
+      'userdata-qemu.img.lock',
+      'encryptionkey.img',
+    ];
+
+    for (const target of transientTargets) {
+      fs.rmSync(path.join(avdDir, target), { force: true, recursive: true });
+    }
+
+    for (const entry of ['snapshots', '.lock']) {
+      fs.rmSync(path.join(avdDir, entry), { force: true, recursive: true });
+    }
+
+    try {
+      for (const entry of fs.readdirSync(avdDir)) {
+        if (/\.lock$/i.test(entry) || /\.tmp$/i.test(entry)) {
+          fs.rmSync(path.join(avdDir, entry), { force: true, recursive: true });
+        }
+      }
+    } catch {}
+  }
+
+  async #forceRecreateAvdForRecovery() {
+    const avdDir = path.join(AVD_HOME, `${this.avdName}.avd`);
+    await this.stopEmulator().catch(() => {});
+    fs.rmSync(avdDir, { recursive: true, force: true });
+    fs.rmSync(path.join(AVD_HOME, `${this.avdName}.ini`), { force: true });
+    this.#appendState({
+      avdSystemImage: null,
+      serial: null,
+      emulatorPid: null,
+      lastLogLine: 'Recreating AVD after failed framework boot.',
+    });
+    await this.ensureAvd();
+    this.#cleanupAvdTransientState();
+  }
+
   async listDevices(options = {}) {
     if (options.ensureBootstrapped !== false) {
       await this.ensureBootstrapped();
@@ -1789,7 +1937,7 @@ class AndroidController {
     const args = [
       `@${this.avdName}`,
       '-no-boot-anim',
-      ...emulatorLaunchArgs(this.avdName),
+      ...emulatorLaunchArgs(),
       '-data',
       path.join(AVD_HOME, `${this.avdName}.avd`, 'userdata-qemu.img'),
       '-gpu',
@@ -1831,6 +1979,16 @@ class AndroidController {
         error?.message ||
         String(error || 'Android emulator did not finish booting.');
       await this.stopEmulator().catch(() => {});
+      if (!options._recoveredOnce && isRecoverableEmulatorStartError(lastLine)) {
+        console.warn(`[Android] Recoverable emulator start failure detected. Cleaning transient AVD state and retrying once: ${lastLine}`);
+        this.#cleanupAvdTransientState();
+        return this.#startEmulatorBlocking({ ...options, _recoveredOnce: true });
+      }
+      if (!options._recreatedAvdOnce && isRecoverableEmulatorStartError(lastLine)) {
+        console.warn(`[Android] Emulator recovery escalation: recreating AVD and retrying once: ${lastLine}`);
+        await this.#forceRecreateAvdForRecovery();
+        return this.#startEmulatorBlocking({ ...options, _recoveredOnce: true, _recreatedAvdOnce: true });
+      }
       this.markBootstrapFailure(lastLine);
       throw new Error(lastLine);
     }
@@ -1889,6 +2047,24 @@ class AndroidController {
       };
     }
 
+    const currentState = this.#readState();
+    const existingWorkerPid = Number(currentState.bootstrapWorkerPid || 0);
+    if (isProcessAlive(existingWorkerPid)) {
+      return {
+        success: true,
+        pending: true,
+        bootstrapped: currentState.bootstrapped === true,
+        starting: true,
+        startupPhase: currentState.startupPhase || 'Preparing Android runtime',
+        startRequestedAt: currentState.startRequestedAt || null,
+        logPath: currentState.logPath || null,
+      };
+    }
+
+    if (existingWorkerPid) {
+      this.#appendState({ bootstrapWorkerPid: null });
+    }
+
     if (!this.startPromise) {
       const requestedAt = new Date().toISOString();
       this.#appendState({
@@ -1912,9 +2088,13 @@ class AndroidController {
         env: workerEnv,
       });
       child.unref();
+      this.#appendState({
+        bootstrapWorkerPid: child.pid,
+      });
       this.startPromise = new Promise((resolve) => {
         child.once('exit', (code, signal) => {
           this.startPromise = null;
+          this.#appendState({ bootstrapWorkerPid: null });
           if (code !== 0) {
             console.error('[Android] Emulator bootstrap worker exited', { code, signal });
           }
@@ -1922,6 +2102,7 @@ class AndroidController {
         });
         child.once('error', (error) => {
           this.startPromise = null;
+          this.#appendState({ bootstrapWorkerPid: null });
           console.error('[Android] Emulator bootstrap worker failed to spawn', error);
           resolve({ code: null, signal: null, error });
         });
@@ -1943,15 +2124,110 @@ class AndroidController {
   async waitForDevice(options = {}) {
     const timeoutMs = Math.max(10000, Number(options.timeoutMs) || 180000);
     const deadline = Date.now() + timeoutMs;
+    let reconnectCounter = 0;
+    let missingPidSince = null;
+    let firstOnlineAt = null;
+    let offlineSince = null;
 
     while (Date.now() < deadline) {
       const serial = await this.getPrimarySerial();
       if (serial) {
         this.#assertSerialAccess(serial, { claimIfUnowned: true });
-        const boot = await this.#runAllowFailure(`${quoteShell(adbBinary())} -s ${quoteShell(serial)} shell getprop sys.boot_completed`, { timeout: 10000 });
-        if ((boot.stdout || '').trim() === '1') {
+        if (!firstOnlineAt) {
+          firstOnlineAt = Date.now();
+        }
+        const bootCompleted = await this.#runAllowFailure(
+          `${quoteShell(adbBinary())} -s ${quoteShell(serial)} shell getprop sys.boot_completed`,
+          { timeout: 10000 },
+        );
+        const devBootComplete = await this.#runAllowFailure(
+          `${quoteShell(adbBinary())} -s ${quoteShell(serial)} shell getprop dev.bootcomplete`,
+          { timeout: 10000 },
+        );
+        const bootAnim = await this.#runAllowFailure(
+          `${quoteShell(adbBinary())} -s ${quoteShell(serial)} shell getprop init.svc.bootanim`,
+          { timeout: 10000 },
+        );
+        const shellProbe = await this.#runAllowFailure(
+          `${quoteShell(adbBinary())} -s ${quoteShell(serial)} shell echo ready`,
+          { timeout: 10000 },
+        );
+        const packageServiceProbe = await this.#runAllowFailure(
+          `${quoteShell(adbBinary())} -s ${quoteShell(serial)} shell service check package`,
+          { timeout: 10000 },
+        );
+        const pmProbe = await this.#runAllowFailure(
+          `${quoteShell(adbBinary())} -s ${quoteShell(serial)} shell pm path android`,
+          { timeout: 10000 },
+        );
+
+        const bootValue = String(bootCompleted.stdout || '').trim();
+        const devBootValue = String(devBootComplete.stdout || '').trim();
+        const bootAnimValue = String(bootAnim.stdout || '').trim().toLowerCase();
+        const shellReady = String(shellProbe.stdout || '').trim() === 'ready';
+        const packageServiceReady = /found/i.test(String(packageServiceProbe.stdout || ''));
+        const packageManagerReady = /^package:/m.test(String(pmProbe.stdout || '').trim());
+        if (
+          packageServiceReady
+          && packageManagerReady
+          && (
+            bootValue === '1'
+            || devBootValue === '1'
+            || (shellReady && (bootAnimValue === 'stopped' || bootAnimValue === ''))
+          )
+        ) {
           return serial;
         }
+        if (
+          firstOnlineAt
+          && Date.now() - firstOnlineAt > 120000
+          && (
+            !packageServiceReady
+            || !packageManagerReady
+          )
+        ) {
+          throw new Error('Android framework did not become ready (package manager service did not become ready).');
+        }
+        missingPidSince = null;
+        offlineSince = null;
+      } else {
+        firstOnlineAt = null;
+        const state = this.#readState();
+        const emulatorPid = Number(state.emulatorPid || 0);
+        if (emulatorPid > 0 && !isProcessAlive(emulatorPid)) {
+          throw new Error('Android emulator exited before boot completed.');
+        }
+        if (!emulatorPid) {
+          if (!missingPidSince) {
+            missingPidSince = Date.now();
+          }
+          if (Date.now() - missingPidSince > 20000) {
+            throw new Error('Android emulator is not running.');
+          }
+        } else {
+          missingPidSince = null;
+          const devices = await this.listDevices({ ensureBootstrapped: false }).catch(() => []);
+          const hasOfflineEmulator = devices.some((device) => device.emulator && device.status === 'offline');
+          if (hasOfflineEmulator) {
+            if (!offlineSince) {
+              offlineSince = Date.now();
+            }
+            if (Date.now() - offlineSince > 30000) {
+              await this.#runAllowFailure(`${quoteShell(adbBinary())} kill-server`, { timeout: 10000 });
+              await sleep(600);
+              await this.#runAllowFailure(`${quoteShell(adbBinary())} start-server`, { timeout: 15000 });
+              await this.#runAllowFailure(`${quoteShell(adbBinary())} reconnect`, { timeout: 15000 });
+              await this.#runAllowFailure(`${quoteShell(adbBinary())} wait-for-device`, { timeout: 30000 });
+              offlineSince = Date.now();
+            }
+          } else {
+            offlineSince = null;
+          }
+        }
+      }
+      reconnectCounter += 1;
+      if (reconnectCounter % 5 === 0) {
+        await this.#runAllowFailure(`${quoteShell(adbBinary())} reconnect offline`, { timeout: 10000 });
       }
       await sleep(3000);
     }
@@ -2016,8 +2292,17 @@ class AndroidController {
     return this.#run(`${quoteShell(adbBinary())} -s ${quoteShell(serial)} ${command}`, options);
   }
 
+  async #prepareScreenForCapture(serial) {
+    await this.#adb(serial, 'shell input keyevent 224', { timeout: 10000 }).catch(() => {});
+    await this.#adb(serial, 'shell wm dismiss-keyguard', { timeout: 10000 }).catch(() => {});
+    await this.#adb(serial, 'shell input keyevent 82', { timeout: 10000 }).catch(() => {});
+    await this.#adb(serial, 'shell input keyevent 3', { timeout: 10000 }).catch(() => {});
+    await sleep(350);
+  }
+
   async screenshot(options = {}) {
     const serial = options.serial || await this.ensureDevice();
+    await this.#prepareScreenForCapture(serial).catch(() => {});
     let artifactRecord = null;
     let filename = `android_${Date.now()}.png`;
     let fullPath = path.join(SCREENSHOTS_DIR, filename);
@@ -2035,7 +2320,32 @@ class AndroidController {
       fullPath = artifactRecord.storagePath;
       filename = path.basename(fullPath);
     }
-    await this.#adb(serial, `exec-out screencap -p > ${quoteShell(fullPath)}`, { timeout: 30000 });
+    let captured = false;
+    const localTmp = path.join(TMP_DIR, `shot-${Date.now()}-${Math.random().toString(16).slice(2)}.png`);
+    const remoteTmp = `/sdcard/neoagent-shot-${Date.now()}.png`;
+    for (let attempt = 0; attempt < 3 && !captured; attempt += 1) {
+      try {
+        if (attempt === 0) {
+          await this.#adb(serial, `exec-out screencap -p > ${quoteShell(fullPath)}`, { timeout: 30000 });
+        } else {
+          await this.#adb(serial, `shell screencap -p ${quoteShell(remoteTmp)}`, { timeout: 30000 });
+          await this.#adb(serial, `pull ${quoteShell(remoteTmp)} ${quoteShell(localTmp)}`, { timeout: 30000 });
+          if (fs.existsSync(localTmp)) {
+            fs.copyFileSync(localTmp, fullPath);
+          }
+        }
+        const data = fs.readFileSync(fullPath);
+        captured = isLikelyPng(data);
+      } catch {}
+      if (!captured) {
+        await sleep(500);
+      }
+    }
+    fs.rmSync(localTmp, { force: true });
+    await this.#adb(serial, `shell rm -f ${quoteShell(remoteTmp)}`, { timeout: 10000 }).catch(() => {});
+    if (!captured) {
+      throw new Error('Failed to capture a valid Android screenshot.');
+    }
     if (artifactRecord) {
       this.artifactStore.finalizeFile(artifactRecord.artifactId, fullPath);
     }
@@ -2393,9 +2703,36 @@ class AndroidController {
   }
 
   async listApps(args = {}) {
-    const serial = await this.ensureDevice();
+    let serial = null;
+    try {
+      serial = await this.ensureDevice();
+    } catch (error) {
+      return {
+        success: false,
+        serial: null,
+        count: 0,
+        packages: [],
+        error: String(error?.message || 'Android device is not ready.'),
+      };
+    }
     const cmd = args.includeSystem === true ? 'shell pm list packages' : 'shell pm list packages -3';
-    const out = await this.#adb(serial, cmd, { timeout: 30000 });
+    let out = '';
+    try {
+      out = await this.#adb(serial, cmd, { timeout: 30000 });
+    } catch (error) {
+      await sleep(1000);
+      try {
+        out = await this.#adb(serial, cmd, { timeout: 30000 });
+      } catch (retryError) {
+        return {
+          success: false,
+          serial,
+          count: 0,
+          packages: [],
+          error: String(retryError?.message || error?.message || 'Failed to list Android apps.'),
+        };
+      }
+    }
     const packages = out
       .split('\n')
       .map((line) => line.trim())
@@ -2474,8 +2811,9 @@ class AndroidController {
 
   async getStatus() {
     const state = this.#readState();
-    const shouldSkipDeviceProbe = state.starting === true || this.startPromise != null;
-    const devices = !shouldSkipDeviceProbe && isExecutable(adbBinary())
+    const bootstrapWorkerPid = Number(state.bootstrapWorkerPid || 0) || null;
+    const bootstrapWorkerAlive = isProcessAlive(bootstrapWorkerPid);
+    const devices = isExecutable(adbBinary())
       ? await this.listDevices({ ensureBootstrapped: false }).catch(() => [])
       : [];
     const serialInState = String(state.serial || '').trim();
@@ -2507,8 +2845,8 @@ class AndroidController {
     }
     return {
       bootstrapped: state.bootstrapped === true,
-      starting: state.starting === true || this.startPromise != null,
-      startupPhase: state.startupPhase || null,
+      starting: state.starting === true || this.startPromise != null || bootstrapWorkerAlive,
+      startupPhase: state.startupPhase || (bootstrapWorkerAlive ? 'Preparing Android runtime' : null),
       startRequestedAt: state.startRequestedAt || null,
       lastStartError: state.lastStartError || null,
       sdkRoot: activeAndroidSdkRoot(),
@@ -2519,6 +2857,7 @@ class AndroidController {
       serial: state.serial,
       serialOwnedByCurrentUser,
       emulatorPid: state.emulatorPid,
+      bootstrapWorkerPid,
       systemImage: state.systemImage || null,
       systemImageArch: state.systemImageArch || null,
       preferredSystemImageArchs: systemImageArchCandidates(),