neoagent 2.3.1-beta.88 → 2.3.1-beta.90

package/server/services/android/controller.js

@@ -27,9 +27,11 @@ const ANDROID_BOOTSTRAP_WORKER = path.join(__dirname, 'android_bootstrap_worker.
 const ANDROID_JAVA_TOOL_TIMEOUT_MS = 20 * 60 * 1000;
 const DEFAULT_AVD_NAME = 'neoagent-default';
 const DEFAULT_DATA_PARTITION_BYTES = 1024 * 1024 * 1024;
-const DEFAULT_PARTITION_SIZE_MB = 1024;
 const DEFAULT_SDCARD_SIZE_BYTES = 32 * 1024 * 1024;
-const DEFAULT_RAM_SIZE_MB = 768;
+const DEFAULT_RAM_SIZE_MB = 1536;
+const MIN_SYSTEM_IMAGE_INSTALL_FREE_BYTES = 5 * 1024 * 1024 * 1024;
+const EMULATOR_CONSOLE_PORT_MIN = 5554;
+const EMULATOR_CONSOLE_PORT_MAX = 5584;
 const DEFAULT_KEYEVENTS = Object.freeze({
   home: 3,
   back: 4,
@@ -53,9 +55,19 @@ for (const dir of [ANDROID_ROOT, SDK_ROOT, EMULATOR_HOME, ARTIFACTS_DIR, SCREENS
 
 function ensureEmulatorAdvancedFeaturesFile() {
   try {
-    if (fs.existsSync(EMULATOR_ADVANCED_FEATURES_FILE)) {
-      fs.rmSync(EMULATOR_ADVANCED_FEATURES_FILE, { force: true });
-    }
+    fs.mkdirSync(path.dirname(EMULATOR_ADVANCED_FEATURES_FILE), { recursive: true });
+    fs.writeFileSync(
+      EMULATOR_ADVANCED_FEATURES_FILE,
+      [
+        'QuickbootFileBacked=off',
+        'QuickbootSupport=off',
+        // Disable FBE so Android doesn't boot into Before-First-Unlock state,
+        // which blocks ADB from transitioning offline → device.
+        'EncryptUserData=off',
+        '',
+      ].join('\n'),
+      'utf8',
+    );
   } catch {}
 }
 
@@ -200,6 +212,101 @@ function tailFile(filePath, maxLines = 40) {
   }
 }
 
+function buildAndroidBootstrapError(message, details = {}) {
+  const error = new Error(message);
+  error.code = details.code || 'ANDROID_BOOTSTRAP_FAILED';
+  error.details = details;
+  return error;
+}
+
+function selectAndroidFailureMessage(logPath, error) {
+  const structuredTail = Array.isArray(error?.details?.logTail) ? error.details.logTail : null;
+  if (structuredTail && structuredTail.length > 0) {
+    return structuredTail.slice(-100).join(' | ');
+  }
+
+  const errorMessage = error?.message || (error ? String(error) : '');
+  const sanitizedErrorMessage = errorMessage
+    .split('\n')
+    .map((line) => line.trim())
+    .filter((line) => line && line !== 'null' && !/^Picked up JAVA_TOOL_OPTIONS:/i.test(line))
+    .join('\n');
+  if (sanitizedErrorMessage && !/^INFO\s+\|/i.test(sanitizedErrorMessage) && !/^WARNING\s+\|/i.test(sanitizedErrorMessage)) {
+    return sanitizedErrorMessage;
+  }
+
+  const seriousLine = tailFile(logPath, 100)
+    .reverse()
+    .find((line) => /FATAL|PANIC|ERROR|disk full|broken avd|failed|exited/i.test(line));
+  if (seriousLine) {
+    return seriousLine;
+  }
+
+  return sanitizedErrorMessage || tailFile(logPath, 100).at(-1) || 'Android bootstrap failed.';
+}
+
+
+function isLikelyPng(buffer) {
+  return Buffer.isBuffer(buffer)
+    && buffer.length > 24
+    && buffer[0] === 0x89
+    && buffer[1] === 0x50
+    && buffer[2] === 0x4e
+    && buffer[3] === 0x47;
+}
+
+function freeBytesForPath(targetPath) {
+  try {
+    const stats = fs.statfsSync(targetPath);
+    return Number(stats.bavail || 0) * Number(stats.bsize || 0);
+  } catch {
+    return 0;
+  }
+}
+
+function pruneAndroidRuntimeCache(keepPackageName = null) {
+  fs.rmSync(TMP_DIR, { recursive: true, force: true });
+  fs.mkdirSync(TMP_DIR, { recursive: true });
+
+  for (const orphan of ['arm64-v8a', 'x86_64', 'x86']) {
+    fs.rmSync(path.join(activeAndroidSdkRoot(), orphan), { recursive: true, force: true });
+  }
+
+  const keep = String(keepPackageName || '').trim();
+  const root = path.join(activeAndroidSdkRoot(), 'system-images');
+  if (!fs.existsSync(root)) return;
+
+  for (const candidate of parseInstalledSystemImages()) {
+    if (keep && candidate.packageName === keep) continue;
+    const candidateRoot = path.join(activeAndroidSdkRoot(), ...String(candidate.packageName).split(';').filter(Boolean));
+    const notSelectedImage = Boolean(keep && candidate.packageName !== keep);
+    const wrongArch = candidate.arch !== systemImageArch();
+    const oldProblemImage = /system-images;android-30;default;arm64-v8a/i.test(candidate.packageName);
+    if (notSelectedImage || wrongArch || oldProblemImage || !isValidInstalledSystemImage(candidate.packageName)) {
+      console.warn('[Android][runtime_cache_prune]', {
+        packageName: candidate.packageName,
+        reason: notSelectedImage ? 'not_selected_image' : wrongArch ? 'wrong_arch' : oldProblemImage ? 'known_unstable_image' : 'invalid_image',
+      });
+      fs.rmSync(candidateRoot, { recursive: true, force: true });
+    }
+  }
+}
+
+function isBlankSparseFile(filePath) {
+  try {
+    const stats = fs.statSync(filePath);
+    if (!stats.isFile()) return false;
+    if (stats.size === 0) return true;
+    if (stats.blocks !== 0) return false;
+    // Sparse backing file is normal when a qcow2 overlay exists alongside it.
+    const qcow2Path = `${filePath}.qcow2`;
+    const qcow2Stats = fs.statSync(qcow2Path);
+    return !qcow2Stats.isFile() || qcow2Stats.size < 8192;
+  } catch {
+    return false;
+  }
+}
+
 function commandExists(command) {
   const probe = spawnSync('bash', ['-lc', `command -v "${command}"`], { encoding: 'utf8' });
   return probe.status === 0;
@@ -268,33 +375,14 @@ function emulatorHostArch() {
 }
 
 function emulatorGpuMode() {
-  if (process.platform === 'darwin' && process.arch === 'arm64') {
-    return 'swiftshader_indirect';
+  if (process.platform === 'darwin') {
+    return 'host';
   }
   return 'auto';
 }
 
-function emulatorLaunchArgs() {
-  return [
-    '-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('failed to process .ini file') ||
-    value.includes('error while loading state for instance')
-  );
+function logAndroidIssue(event, details = {}) {
+  console.warn(`[Android][${event}]`, details);
 }
 
 function parseCsvEnv(value) {
@@ -394,6 +482,7 @@ function sdkEnv() {
     ANDROID_USER_HOME: EMULATOR_HOME,
     ANDROID_AVD_HOME: AVD_HOME,
     AVD_HOME,
+    ADB_VENDOR_KEYS: EMULATOR_HOME,
     JAVA_TOOL_OPTIONS: process.env.JAVA_TOOL_OPTIONS || '-Xint',
   };
   const pathParts = [
@@ -437,10 +526,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() {
@@ -458,20 +547,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');
 }
 
@@ -745,7 +820,11 @@ function parseRepositorySystemImages(xml) {
   return parseSystemImageCandidates(matches);
 }
 
-function parseLatestSystemImageUrl(xml, packageName) {
+function parseLatestSystemImageUrl(source, packageName) {
+  const xml = typeof source === 'string' ? source : source?.xml;
+  const baseUrl = typeof source === 'string'
+    ? 'https://dl.google.com/android/repository/sys-img/android/'
+    : source?.baseUrl || 'https://dl.google.com/android/repository/sys-img/android/';
   const packageMatch = xml.match(new RegExp(`<remotePackage\\s+path="${packageName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}">([\\s\\S]*?)<\\/remotePackage>`));
   if (!packageMatch) throw new Error(`Could not locate ${packageName} in Android repository metadata`);
 
@@ -755,13 +834,52 @@ function parseLatestSystemImageUrl(xml, packageName) {
     if (urlMatch) {
       const urlPart = urlMatch[1];
       if (urlPart.startsWith('http')) return urlPart;
-      return `https://dl.google.com/android/repository/sys-img/android/${urlPart}`;
+      return `${baseUrl}${urlPart}`;
     }
   }
 
   throw new Error(`Could not find a system image archive for ${packageName}`);
 }
 
+async function fetchSystemImageRepositories() {
+  const sources = [
+    {
+      url: 'https://dl.google.com/android/repository/sys-img/android/sys-img2-1.xml',
+      baseUrl: 'https://dl.google.com/android/repository/sys-img/android/',
+    },
+    {
+      url: 'https://dl.google.com/android/repository/sys-img/google_apis/sys-img2-1.xml',
+      baseUrl: 'https://dl.google.com/android/repository/sys-img/google_apis/',
+    },
+    {
+      url: 'https://dl.google.com/android/repository/sys-img/google_apis_playstore/sys-img2-1.xml',
+      baseUrl: 'https://dl.google.com/android/repository/sys-img/google_apis_playstore/',
+    },
+  ];
+  const results = [];
+  for (const source of sources) {
+    try {
+      results.push({
+        ...source,
+        xml: await fetchText(source.url),
+      });
+    } catch (error) {
+      logAndroidIssue('system_image_repository_fetch_failed', {
+        url: source.url,
+        message: String(error?.message || error),
+      });
+    }
+  }
+  if (results.length === 0) {
+    throw new Error('Could not fetch Android system image repository metadata.');
+  }
+  return results;
+}
+
+function parseRepositorySystemImagesFromSources(sources) {
+  return sources.flatMap((source) => parseRepositorySystemImages(source.xml));
+}
+
 async function fetchEmulatorMetadata() {
   const urls = [
     'https://dl.google.com/android/repository/repository2-3.xml',
@@ -819,29 +937,48 @@ 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) {
-  const url = parseLatestSystemImageUrl(metadata, packageName);
+  const sources = Array.isArray(metadata) ? metadata : [{ xml: metadata }];
+  const source = sources.find((entry) => {
+    try {
+      parseLatestSystemImageUrl(entry, packageName);
+      return true;
+    } catch {
+      return false;
+    }
+  });
+  if (!source) {
+    throw new Error(`Could not locate ${packageName} in Android repository metadata`);
+  }
+  const url = parseLatestSystemImageUrl(source, packageName);
   const zipPath = path.join(TMP_DIR, path.basename(url));
   const targetRoot = path.join(activeAndroidSdkRoot(), ...String(packageName).split(';').filter(Boolean));
   const extractDir = fs.mkdtempSync(path.join(TMP_DIR, 'system-image-'));
 
   try {
+    pruneAndroidRuntimeCache(packageName);
+    fs.mkdirSync(extractDir, { recursive: true });
+    let freeBytes = freeBytesForPath(ANDROID_ROOT);
+    if (freeBytes < MIN_SYSTEM_IMAGE_INSTALL_FREE_BYTES) {
+      throw new Error(
+        `Not enough disk space to install Android system image ${packageName}. ` +
+        `Free ${Math.round(freeBytes / 1024 / 1024)} MB, need at least ${Math.round(MIN_SYSTEM_IMAGE_INSTALL_FREE_BYTES / 1024 / 1024)} MB.`
+      );
+    }
     fs.rmSync(targetRoot, { recursive: true, force: true });
     fs.mkdirSync(path.dirname(targetRoot), { recursive: true });
     await downloadFile(url, zipPath);
+    freeBytes = freeBytesForPath(ANDROID_ROOT);
+    if (freeBytes < MIN_SYSTEM_IMAGE_INSTALL_FREE_BYTES / 2) {
+      throw new Error(
+        `Not enough disk space to extract Android system image ${packageName}. ` +
+        `Free ${Math.round(freeBytes / 1024 / 1024)} MB after download.`
+      );
+    }
     extractZip(zipPath, extractDir);
 
     const extractedRoot = findDirectoryContainingFiles(extractDir, ['userdata.img']) ||
@@ -855,6 +992,13 @@ async function installSystemImageArchive(metadata, packageName) {
     try {
       fs.renameSync(extractedRoot, targetRoot);
     } catch (renameErr) {
+      freeBytes = freeBytesForPath(ANDROID_ROOT);
+      if (freeBytes < MIN_SYSTEM_IMAGE_INSTALL_FREE_BYTES / 2) {
+        throw new Error(
+          `Not enough disk space to move Android system image ${packageName}. ` +
+          `Free ${Math.round(freeBytes / 1024 / 1024)} MB.`
+        );
+      }
       fs.cpSync(extractedRoot, targetRoot, { recursive: true, force: true });
       if (renameErr) {
         console.warn(`[Android] Falling back to copy for ${packageName}: ${renameErr.message}`);
@@ -947,27 +1091,78 @@ 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 runtimeSystemImagePreferenceRank(candidate) {
+  if (!candidate) return Number.MAX_SAFE_INTEGER;
+  if (process.platform === 'darwin' && process.arch === 'arm64') {
+    const preferredApis = [31, 34, 35, 33, 32];
+    const index = preferredApis.indexOf(Number(candidate.apiLevel || 0));
+    return index === -1 ? 1000 + Math.abs(Number(candidate.apiLevel || 0) - 31) : index;
+  }
+  if (process.platform === 'linux' && process.arch === 'arm64') {
+    const preferredApis = [34, 35, 33, 31, 36];
+    const index = preferredApis.indexOf(Number(candidate.apiLevel || 0));
+    return index === -1 ? 1000 + Math.abs(Number(candidate.apiLevel || 0) - 34) : index;
+  }
+  return 0;
+}
+
+function preferredRuntimeSystemImageCandidate(candidates = []) {
+  if (!(process.platform === 'darwin' && process.arch === 'arm64')) {
+    return null;
+  }
+
+  const desired = [
+    ['android-31', 'google_apis', 'arm64-v8a'],
+    ['android-34', 'google_apis', 'arm64-v8a'],
+    ['android-33', 'google_apis', 'arm64-v8a'],
+    ['android-31', 'google_apis_playstore', 'arm64-v8a'],
+    ['android-34', 'google_apis_playstore', 'arm64-v8a'],
+    ['android-33', 'google_apis_playstore', 'arm64-v8a'],
+  ];
+  const parsed = Array.isArray(candidates) ? candidates : [];
+  for (const [platformId, tag, arch] of desired) {
+    const found = parsed.find((candidate) =>
+      candidate.platformId === platformId &&
+      candidate.tag === tag &&
+      candidate.arch === arch
+    );
+    if (found) return found;
+  }
+  const [platformId, tag, arch] = desired[0];
+  return parseSystemImageCandidates([{
+    packageName: `system-images;${platformId};${tag};${arch}`,
+    platformId,
+    tag,
+    arch,
+  }])[0];
+}
+
+
 function rankSystemImagePool(pool) {
   const preferredMatches = pool.filter((candidate) => candidate.tagScore > 0);
   const rankedPool = preferredMatches.length > 0 ? preferredMatches : pool;
-  const appleSiliconPreferredApis = process.platform === 'darwin' && process.arch === 'arm64'
-    ? [30, 31, 35, 36]
-    : [];
-  const preferredApiRank = (apiLevel) => appleSiliconPreferredApis.indexOf(Number(apiLevel || 0));
 
   rankedPool.sort((a, b) =>
-    (
-      (() => {
-        const aRank = preferredApiRank(a.apiLevel);
-        const bRank = preferredApiRank(b.apiLevel);
-        if (aRank !== -1 || bRank !== -1) {
-          if (aRank === -1) return 1;
-          if (bRank === -1) return -1;
-          return aRank - bRank;
-        }
-        return 0;
-      })()
-    ) ||
+    runtimeSystemImagePreferenceRank(a) - runtimeSystemImagePreferenceRank(b) ||
     Number(b.stable) - Number(a.stable) ||
     b.tagScore - a.tagScore ||
     b.apiLevel - a.apiLevel ||
@@ -1080,6 +1275,30 @@ function systemImagePackageToRelativeDir(packageName) {
   return `${parts.join('/')}/`;
 }
 
+function isValidInstalledSystemImage(packageName) {
+  const relativeDir = systemImagePackageToRelativeDir(packageName);
+  if (!relativeDir) return false;
+  const root = path.join(activeAndroidSdkRoot(), relativeDir);
+  const hasMetadata = fs.existsSync(path.join(root, 'package.xml')) || fs.existsSync(path.join(root, 'source.properties'));
+  return hasMetadata
+    && fs.existsSync(path.join(root, 'system.img'))
+    && fs.existsSync(path.join(root, 'userdata.img'));
+}
+
+function systemImagePackageRoot(packageName) {
+  const relativeDir = systemImagePackageToRelativeDir(packageName);
+  if (!relativeDir) return null;
+  return path.join(activeAndroidSdkRoot(), relativeDir);
+}
+
+function ensureSystemImageUserdataImage(packageName) {
+  const root = systemImagePackageRoot(packageName);
+  if (!root) return;
+  const userdataImage = path.join(root, 'userdata.img');
+  if (fs.existsSync(userdataImage)) return;
+  ensureSparseFile(userdataImage, DEFAULT_DATA_PARTITION_BYTES);
+}
+
 function systemImagePackageToAbi(packageName) {
   const parts = String(packageName || '').split(';').filter(Boolean);
   if (parts.length !== 4 || parts[0] !== 'system-images') {
@@ -1358,7 +1577,30 @@ class AndroidController {
       cwd: options.cwd || ANDROID_ROOT,
     });
     if (result.exitCode !== 0) {
-      throw new Error(result.stderr || result.stdout || `Command failed: ${command}`);
+      const stderr = String(result.stderr || '').trim();
+      const stdout = String(result.stdout || '').trim();
+      const fragments = [];
+      if (result.timedOut) {
+        fragments.push(`Command timed out after ${result.durationMs || options.timeout || 120000}ms: ${command}`);
+      } else {
+        fragments.push(`Command failed (exit ${result.exitCode ?? 'unknown'}): ${command}`);
+      }
+      if (stderr) {
+        fragments.push(`stderr: ${stderr}`);
+      }
+      if (stdout) {
+        fragments.push(`stdout: ${stdout}`);
+      }
+      const error = new Error(fragments.join('\n'));
+      error.details = {
+        command,
+        exitCode: result.exitCode,
+        timedOut: result.timedOut === true,
+        durationMs: result.durationMs,
+        stderr,
+        stdout,
+      };
+      throw error;
     }
     return result.stdout || '';
   }
@@ -1372,6 +1614,11 @@ class AndroidController {
   }
 
   async ensureBootstrapped() {
+    this.#appendState({
+      starting: this.#readState().starting === true,
+      startupPhase: 'Checking Android runtime',
+      lastLogLine: 'Checking Android SDK, emulator, and system image.',
+    });
     const desiredArch = systemImageArch();
     const state = this.#readState();
     const installedImages = parseInstalledSystemImages();
@@ -1379,27 +1626,52 @@ class AndroidController {
       chooseConfiguredSystemImage(installedImages) ||
       chooseLatestSystemImage(installedImages, [desiredArch]) ||
       chooseLatestSystemImage(installedImages);
-    const systemImageMetadata = await fetchText('https://dl.google.com/android/repository/sys-img/android/sys-img2-1.xml');
-    const available = parseRepositorySystemImages(systemImageMetadata);
+    const systemImageMetadata = await fetchSystemImageRepositories();
+    const available = parseRepositorySystemImagesFromSources(systemImageMetadata);
     const preferredAvailable =
       chooseConfiguredSystemImage(available) ||
+      preferredRuntimeSystemImageCandidate(available) ||
       chooseLatestSystemImage(available, [desiredArch]) ||
       chooseLatestSystemImage(available);
-    const selectedImage = rankSystemImagePool([preferredInstalled, preferredAvailable].filter(Boolean))[0] || preferredInstalled || preferredAvailable;
+    const shouldPreferLighterAvailableImage =
+      process.platform === 'darwin' &&
+      process.arch === 'arm64' &&
+      preferredAvailable?.packageName &&
+      /;google_apis;/.test(preferredAvailable.packageName) &&
+      /;google_apis_playstore;/.test(String(preferredInstalled?.packageName || ''));
+    const selectedImage = shouldPreferLighterAvailableImage
+      ? preferredAvailable
+      : (rankSystemImagePool([preferredInstalled, preferredAvailable].filter(Boolean))[0] || preferredInstalled || preferredAvailable);
     const stateApiLevel = Number(state.apiLevel || 0) || 0;
-
-    if (!shouldForceSdkRefresh() && sharedAndroidSdkReady() && selectedImage) {
+    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 =
-        selectedImage.packageName === state.systemImage &&
-        selectedImage.apiLevel === stateApiLevel &&
-        selectedImage.arch === state.systemImageArch &&
+        effectiveSelectedImage.packageName === state.systemImage &&
+        effectiveSelectedImage.apiLevel === stateApiLevel &&
+        effectiveSelectedImage.arch === state.systemImageArch &&
         state.avdName === this.avdName;
 
       if (stateAligned) {
         return;
       }
 
-      if (selectedImage === preferredInstalled && selectedImage.packageName) {
+      if (effectiveSelectedImage === preferredInstalled && effectiveSelectedImage.packageName) {
         const changeSummary = describeAutoFixChanges(
           {
             avdName: state.avdName || null,
@@ -1409,9 +1681,9 @@ class AndroidController {
           },
           {
             avdName: this.avdName,
-            systemImage: selectedImage.packageName,
-            apiLevel: selectedImage.apiLevel,
-            systemImageArch: selectedImage.arch,
+            systemImage: effectiveSelectedImage.packageName,
+            apiLevel: effectiveSelectedImage.apiLevel,
+            systemImageArch: effectiveSelectedImage.arch,
           },
           ['avdName', 'systemImage', 'apiLevel', 'systemImageArch']
         );
@@ -1423,9 +1695,9 @@ class AndroidController {
           avdName: this.avdName,
           serial: null,
           emulatorPid: null,
-          systemImage: selectedImage.packageName,
-          apiLevel: selectedImage.apiLevel,
-          systemImageArch: selectedImage.arch,
+          systemImage: effectiveSelectedImage.packageName,
+          apiLevel: effectiveSelectedImage.apiLevel,
+          systemImageArch: effectiveSelectedImage.arch,
         });
         return;
       }
@@ -1436,6 +1708,10 @@ class AndroidController {
       isExecutable(emulatorBinary()) &&
       installedEmulatorMatchesHost();
     if (!binariesReady) {
+      this.#appendState({
+        startupPhase: 'Installing Android tools',
+        lastLogLine: 'Installing Android platform tools and emulator.',
+      });
       if (this.bootstrapPromise) {
         await this.bootstrapPromise;
       } else {
@@ -1451,12 +1727,12 @@ class AndroidController {
     const runtimeNeedsRefresh =
       state.systemImageArch !== desiredArch ||
       !installedEmulatorMatchesHost();
-    if (!shouldForceSdkRefresh()) {
-      if (!runtimeNeedsRefresh && selectedImage && selectedImage === preferredInstalled) {
+    if (!shouldForceSdkRefresh() && !legacyLinuxArm64Image && !selectedImageInvalid) {
+      if (!runtimeNeedsRefresh && effectiveSelectedImage && effectiveSelectedImage === preferredInstalled) {
         const stateNeedsRefresh =
-          selectedImage.packageName !== state.systemImage ||
-          selectedImage.apiLevel !== stateApiLevel ||
-          selectedImage.arch !== state.systemImageArch ||
+          effectiveSelectedImage.packageName !== state.systemImage ||
+          effectiveSelectedImage.apiLevel !== stateApiLevel ||
+          effectiveSelectedImage.arch !== state.systemImageArch ||
           state.avdName !== this.avdName;
         if (stateNeedsRefresh) {
           const changeSummary = describeAutoFixChanges(
@@ -1468,9 +1744,9 @@ class AndroidController {
             },
             {
               avdName: this.avdName,
-              systemImage: selectedImage.packageName,
-              apiLevel: selectedImage.apiLevel,
-              systemImageArch: selectedImage.arch,
+              systemImage: effectiveSelectedImage.packageName,
+              apiLevel: effectiveSelectedImage.apiLevel,
+              systemImageArch: effectiveSelectedImage.arch,
             },
             ['avdName', 'systemImage', 'apiLevel', 'systemImageArch']
           );
@@ -1482,9 +1758,9 @@ class AndroidController {
             avdName: this.avdName,
             serial: null,
             emulatorPid: null,
-            systemImage: selectedImage.packageName,
-            apiLevel: selectedImage.apiLevel,
-            systemImageArch: selectedImage.arch,
+            systemImage: effectiveSelectedImage.packageName,
+            apiLevel: effectiveSelectedImage.apiLevel,
+            systemImageArch: effectiveSelectedImage.arch,
           });
         }
         return;
@@ -1493,8 +1769,8 @@ class AndroidController {
         !runtimeNeedsRefresh &&
         state.bootstrapped === true &&
         state.systemImage &&
-        selectedImage &&
-        selectedImage.packageName === state.systemImage
+        effectiveSelectedImage &&
+        effectiveSelectedImage.packageName === state.systemImage
       ) {
         return;
       }
@@ -1503,21 +1779,34 @@ class AndroidController {
     this.#appendState({ bootstrapped: true });
     const metadata = await fetchEmulatorMetadata();
     if (shouldInstallPlatformToolsArchive()) {
+      this.#appendState({
+        startupPhase: 'Installing Android platform tools',
+        lastLogLine: 'Installing Android platform tools.',
+      });
       await installPlatformToolsArchive(metadata);
     }
+    this.#appendState({
+      startupPhase: 'Installing Android emulator',
+      lastLogLine: 'Installing or updating the Android emulator.',
+    });
     await installEmulatorArchive(metadata);
-    if (!selectedImage) {
+    if (!effectiveSelectedImage) {
       throw new Error(formatSystemImageError(available));
     }
-    if (selectedImage?.packageName) {
-      await installSystemImageArchive(systemImageMetadata, selectedImage.packageName);
+    if (effectiveSelectedImage?.packageName) {
+      this.#appendState({
+        startupPhase: 'Installing Android system image',
+        lastLogLine: `Installing ${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,
     });
   }
 
@@ -1549,8 +1838,8 @@ class AndroidController {
     }
     await installEmulatorArchive(metadata);
 
-    const systemImageMetadata = await fetchText('https://dl.google.com/android/repository/sys-img/android/sys-img2-1.xml');
-    const available = parseRepositorySystemImages(systemImageMetadata);
+    const systemImageMetadata = await fetchSystemImageRepositories();
+    const available = parseRepositorySystemImagesFromSources(systemImageMetadata);
     const systemImage = chooseConfiguredSystemImage(available) || chooseLatestSystemImage(available);
     if (!systemImage) throw new Error(formatSystemImageError(available));
 
@@ -1569,8 +1858,7 @@ class AndroidController {
 
   markBootstrapFailure(error) {
     const state = this.#readState();
-    const recentLogLines = state.logPath ? tailFile(state.logPath, 12) : [];
-    const detailedMessage = recentLogLines[recentLogLines.length - 1] || error?.message || String(error || 'Android bootstrap failed.');
+    const detailedMessage = selectAndroidFailureMessage(state.logPath, error);
     this.#appendState({
       starting: false,
       startupPhase: 'Start failed',
@@ -1578,6 +1866,12 @@ class AndroidController {
       lastLogLine: detailedMessage,
       bootstrapWorkerPid: null,
     });
+    logAndroidIssue('bootstrap_failure', {
+      scopeKey: this.scopeKey,
+      avdName: this.avdName,
+      message: detailedMessage,
+      logPath: state.logPath || null,
+    });
     return detailedMessage;
   }
 
@@ -1585,158 +1879,42 @@ 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');
     const avdDir = path.join(AVD_HOME, `${this.avdName}.avd`);
     const configPath = path.join(avdDir, 'config.ini');
     const avdExists = fs.existsSync(configPath);
-    let avdNeedsRecreate = avdExists && (!state.avdSystemImage || state.avdSystemImage !== pkg);
-    const avdRecreateReasons = [];
-    if (avdNeedsRecreate && state.avdSystemImage !== pkg) {
-      avdRecreateReasons.push(`systemImage: ${state.avdSystemImage || 'null'} -> ${pkg}`);
-    }
-    if (avdExists && fs.existsSync(configPath)) {
-      try {
-        const config = fs.readFileSync(configPath, 'utf8');
-        const currentImageDir = readIniValue(config, 'image.sysdir.1');
-        const expectedImageDir = systemImagePackageToRelativeDir(pkg);
-        const currentAbi = readIniValue(config, 'abi.type');
-        const expectedAbi = systemImagePackageToAbi(pkg);
-        const currentCpuArch = readIniValue(config, 'hw.cpu.arch');
-        const expectedCpuArch = systemImagePackageToCpuArch(pkg);
-        const currentDataPartitionSize = readIniValue(config, 'disk.dataPartition.size');
-        const expectedDataPartitionSize = String(DEFAULT_DATA_PARTITION_BYTES);
-        const currentSdcardSize = readIniValue(config, 'sdcard.size');
-        const expectedSdcardSize = String(DEFAULT_SDCARD_SIZE_BYTES);
-        const currentRamSize = readIniValue(config, 'hw.ramSize');
-        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}`);
-        }
-        if (expectedAbi && currentAbi && currentAbi !== expectedAbi) {
-          avdNeedsRecreate = true;
-          avdRecreateReasons.push(`abi.type: ${currentAbi} -> ${expectedAbi}`);
-        }
-        if (expectedCpuArch && currentCpuArch && currentCpuArch !== expectedCpuArch) {
-          avdNeedsRecreate = true;
-          avdRecreateReasons.push(`hw.cpu.arch: ${currentCpuArch} -> ${expectedCpuArch}`);
-        }
-        if (currentDataPartitionSize && currentDataPartitionSize !== expectedDataPartitionSize) {
-          avdNeedsRecreate = true;
-          avdRecreateReasons.push(`disk.dataPartition.size: ${currentDataPartitionSize} -> ${expectedDataPartitionSize}`);
-        }
-        if (currentSdcardSize && currentSdcardSize !== expectedSdcardSize) {
-          avdNeedsRecreate = true;
-          avdRecreateReasons.push(`sdcard.size: ${currentSdcardSize} -> ${expectedSdcardSize}`);
-        }
-        if (currentRamSize && currentRamSize !== expectedRamSize) {
-          avdNeedsRecreate = true;
-          avdRecreateReasons.push(`hw.ramSize: ${currentRamSize} -> ${expectedRamSize}`);
-        }
-        if (currentGpuMode && currentGpuMode !== expectedGpuMode) {
-          avdNeedsRecreate = true;
-          avdRecreateReasons.push(`hw.gpu.mode: ${currentGpuMode} -> ${expectedGpuMode}`);
-        }
-        if (currentPlayStoreEnabled && currentPlayStoreEnabled !== expectedPlayStoreEnabled) {
-          avdNeedsRecreate = true;
-          avdRecreateReasons.push(`PlayStore.enabled: ${currentPlayStoreEnabled} -> ${expectedPlayStoreEnabled}`);
-        }
-      } catch {}
+    if (avdExists && state.avdSystemImage === pkg) {
+      return;
     }
 
-    if (avdNeedsRecreate) {
-      if (avdRecreateReasons.length > 0) {
-        console.log(`[Android] Recreating AVD to repair config mismatch (${avdRecreateReasons.join(', ')})`);
+    ensureSystemImageUserdataImage(pkg);
+
+    const createAvdCommand =
+      `printf 'no\\n' | ${quoteShell(avdManagerBinary())} create avd -n ${quoteShell(this.avdName)} -k "${pkg}" --force`;
+    try {
+      await this.#run(createAvdCommand, { timeout: 300000 });
+    } catch (error) {
+      const message = String(error?.message || error || '');
+      if (/Unable to find a 'userdata\.img' file/i.test(message)) {
+        ensureSystemImageUserdataImage(pkg);
+        await this.#run(createAvdCommand, { timeout: 300000 });
+      } else if (/"emulator" package must be installed/i.test(message)) {
+        this.#appendState({
+          startupPhase: 'Repairing Android emulator package',
+          lastLogLine: 'Reinstalling Android emulator package.',
+        });
+        const metadata = await fetchEmulatorMetadata();
+        await installEmulatorArchive(metadata);
+        await this.#run(createAvdCommand, { timeout: 300000 });
+      } else {
+        throw error;
       }
-      await this.stopEmulator().catch(() => {});
-      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 });
-    } else if (avdExists) {
-      ensureSparseFile(path.join(avdDir, 'userdata-qemu.img'), DEFAULT_DATA_PARTITION_BYTES);
-      return;
     }
-
-    this.#writeAvdFiles(pkg);
     this.#normalizeAvdConfig();
     this.#appendState({ avdSystemImage: pkg });
   }
 
-  #writeAvdFiles(packageName) {
-    const parts = String(packageName || '').split(';').filter(Boolean);
-    if (parts.length !== 4 || parts[0] !== 'system-images') {
-      throw new Error(`Invalid Android system image package: ${packageName}`);
-    }
-    const apiLevel = parts[1].replace(/^android-/, '');
-    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) {
-      throw new Error(`Invalid Android system image directory for package: ${packageName}`);
-    }
-
-    fs.mkdirSync(avdDir, { recursive: true });
-    ensureSparseFile(path.join(avdDir, 'userdata-qemu.img'), DEFAULT_DATA_PARTITION_BYTES);
-    fs.writeFileSync(
-      path.join(AVD_HOME, `${this.avdName}.ini`),
-      [
-        'avd.ini.encoding=UTF-8',
-        `path=${avdDir}`,
-        `path.rel=avd/${this.avdName}.avd`,
-        `target=android-${apiLevel}`,
-        '',
-      ].join('\n')
-    );
-
-    const configLines = [
-      'avd.ini.encoding=UTF-8',
-      `AvdId=${this.avdName}`,
-      `avd.ini.displayname=${this.avdName}`,
-      `PlayStore.enabled=${playStoreEnabled}`,
-      `image.sysdir.1=${imageSysDir}`,
-      `abi.type=${abi}`,
-      `hw.cpu.arch=${systemImagePackageToCpuArch(packageName) || abi}`,
-      'hw.cpu.ncore=2',
-      'hw.dPad=no',
-      'hw.gps=yes',
-      'hw.gpu.enabled=yes',
-      `hw.gpu.mode=${emulatorGpuMode()}`,
-      'hw.initialOrientation=Portrait',
-      'hw.keyboard=yes',
-      'hw.lcd.density=440',
-      'hw.lcd.height=1920',
-      'hw.lcd.width=1080',
-      'hw.mainKeys=no',
-      `hw.ramSize=${DEFAULT_RAM_SIZE_MB}`,
-      'hw.sensors.orientation=yes',
-      'hw.sensors.proximity=yes',
-      'hw.trackBall=no',
-      `disk.dataPartition.size=${DEFAULT_DATA_PARTITION_BYTES}`,
-      `sdcard.size=${DEFAULT_SDCARD_SIZE_BYTES}`,
-      'runtime.network.latency=none',
-      'runtime.network.speed=full',
-      'vm.heapSize=256',
-      `tag.display=${tagDisplay}`,
-      `tag.id=${tagId}`,
-      '',
-    ];
-    fs.writeFileSync(path.join(avdDir, 'config.ini'), configLines.join('\n'));
-
-    const systemImageRoot = path.join(activeAndroidSdkRoot(), ...String(packageName).split(';').filter(Boolean));
-    const userdataImage = path.join(systemImageRoot, 'userdata.img');
-    if (fs.existsSync(userdataImage)) {
-      fs.copyFileSync(userdataImage, path.join(avdDir, 'userdata.img'));
-    }
-  }
-
   #normalizeAvdConfig() {
     const configPath = path.join(AVD_HOME, `${this.avdName}.avd`, 'config.ini');
     if (!fs.existsSync(configPath)) return;
@@ -1746,43 +1924,9 @@ 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, '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 listDevices(options = {}) {
     if (options.ensureBootstrapped !== false) {
       await this.ensureBootstrapped();
@@ -1812,6 +1956,14 @@ class AndroidController {
     const devices = await this.listDevices(options);
     const owners = this.#readOwnership();
     const canUse = (device) => device.status === 'device' && !this.#isSerialOwnedByAnother(device.serial, owners);
+    const expected = state.expectedSerial
+      ? devices.find((device) => device.serial === state.expectedSerial && canUse(device))
+      : null;
+    if (expected) {
+      this.#claimSerial(expected.serial);
+      this.#appendState({ serial: expected.serial });
+      return expected.serial;
+    }
 
     const preferred = state.serial ? devices.find((device) => device.serial === state.serial && canUse(device)) : null;
     if (preferred) {
@@ -1844,15 +1996,22 @@ class AndroidController {
       startRequestedAt: this.#readState().startRequestedAt || new Date().toISOString(),
     });
     console.log('[Android] Preparing emulator start');
-    await this.#terminateStaleEmulatorProcesses([this.avdName, this.previousAvdName]).catch(() => {});
-    await this.ensureAvd();
-    this.#appendState({
-      starting: true,
-      startupPhase: 'Checking for an existing Android device',
-      lastStartError: null,
-    });
-    this.#normalizeAvdConfig();
-    const serial = await this.getPrimarySerial();
+    let serial = null;
+    try {
+      await this.ensureBootstrapped();
+      await this.#terminateStaleEmulatorProcesses([this.avdName, this.previousAvdName]).catch(() => {});
+      await this.ensureAvd();
+      this.#appendState({
+        starting: true,
+        startupPhase: 'Checking for an existing Android device',
+        lastStartError: null,
+      });
+      this.#normalizeAvdConfig();
+      serial = await this.getPrimarySerial();
+    } catch (error) {
+      this.markBootstrapFailure(error);
+      throw error;
+    }
     if (serial) {
       this.#appendState({
         starting: false,
@@ -1874,21 +2033,14 @@ class AndroidController {
     const args = [
       `@${this.avdName}`,
       '-no-boot-anim',
-      ...emulatorLaunchArgs(),
-      '-data',
-      path.join(AVD_HOME, `${this.avdName}.avd`, 'userdata-qemu.img'),
       '-gpu',
       emulatorGpuMode(),
-      '-accel',
-      'auto',
-      '-partition-size',
-      String(DEFAULT_PARTITION_SIZE_MB),
-      '-netdelay',
-      'none',
-      '-netspeed',
-      'full',
+      '-no-window',
+      '-no-audio',
     ];
 
+    await this.#runAllowFailure(`${quoteShell(adbBinary())} kill-server`, { timeout: 15000 });
+    await this.#runAllowFailure(`${quoteShell(adbBinary())} start-server`, { timeout: 15000 });
     const child = spawn(emulatorBinary(), args, {
       detached: true,
       stdio: ['ignore', out, out],
@@ -1910,18 +2062,12 @@ class AndroidController {
     try {
       onlineSerial = await this.waitForDevice({ timeoutMs: options.timeoutMs || 600000 });
     } catch (error) {
-      const recentLogLines = tailFile(logPath, 12);
-      const lastLine =
-        recentLogLines[recentLogLines.length - 1] ||
-        error?.message ||
-        String(error || 'Android emulator did not finish booting.');
+      const lastLine = selectAndroidFailureMessage(logPath, error);
       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 });
-      }
       this.markBootstrapFailure(lastLine);
+      if (error?.details?.logTail) {
+        throw error;
+      }
       throw new Error(lastLine);
     }
     this.#appendState({
@@ -1997,6 +2143,8 @@ class AndroidController {
       this.#appendState({ bootstrapWorkerPid: null });
     }
 
+    await this.ensureBootstrapped();
+
     if (!this.startPromise) {
       const requestedAt = new Date().toISOString();
       this.#appendState({
@@ -2054,14 +2202,14 @@ class AndroidController {
   }
 
   async waitForDevice(options = {}) {
-    const timeoutMs = Math.max(10000, Number(options.timeoutMs) || 180000);
+    const timeoutMs = Math.max(10000, Number(options.timeoutMs) || 600000);
     const deadline = Date.now() + timeoutMs;
-    let reconnectCounter = 0;
     let missingPidSince = null;
     let firstOnlineAt = null;
+    let lastDiagnosticAt = 0;
 
     while (Date.now() < deadline) {
-      const serial = await this.getPrimarySerial();
+      const serial = await this.getPrimarySerial({ ensureBootstrapped: false });
       if (serial) {
         this.#assertSerialAccess(serial, { claimIfUnowned: true });
         if (!firstOnlineAt) {
@@ -2083,21 +2231,39 @@ class AndroidController {
           `${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 (Date.now() - lastDiagnosticAt > 15000) {
+          lastDiagnosticAt = Date.now();
+          this.#appendState({
+            startupPhase: 'Waiting for Android emulator to boot',
+            lastLogLine: `ADB connected to ${serial}; boot=${bootValue || 'unknown'}, devBoot=${devBootValue || 'unknown'}, packageService=${packageServiceReady}, packageManager=${packageManagerReady}.`,
+          });
+        }
         if (
-          bootValue === '1' ||
-          devBootValue === '1' ||
-          (shellReady && (bootAnimValue === 'stopped' || bootAnimValue === ''))
+          packageServiceReady
+          && packageManagerReady
+          && (
+            bootValue === '1'
+            || devBootValue === '1'
+            || (shellReady && (bootAnimValue === 'stopped' || bootAnimValue === ''))
+          )
         ) {
           return serial;
         }
-        if (shellReady && firstOnlineAt && Date.now() - firstOnlineAt >= 45000) {
-          return serial;
-        }
         missingPidSince = null;
       } else {
         firstOnlineAt = null;
@@ -2115,16 +2281,38 @@ class AndroidController {
           }
         } else {
           missingPidSince = null;
+          const devices = await this.listDevices({ ensureBootstrapped: false }).catch(() => []);
+          if (Date.now() - lastDiagnosticAt > 15000) {
+            lastDiagnosticAt = Date.now();
+            this.#appendState({
+              startupPhase: 'Waiting for Android emulator to connect',
+              lastLogLine: devices.length > 0
+                ? `Emulator process running; ADB: ${devices.map((d) => `${d.serial}:${d.status}`).join(', ')}.`
+                : 'Emulator running, no ADB transport yet.',
+            });
+          }
         }
       }
-      reconnectCounter += 1;
-      if (reconnectCounter % 5 === 0) {
-        await this.#runAllowFailure(`${quoteShell(adbBinary())} reconnect offline`, { timeout: 10000 });
-      }
       await sleep(3000);
     }
 
-    throw new Error(`Android emulator did not finish booting within ${timeoutMs} ms`);
+    const state = this.#readState();
+    const logTail = tailFile(state.logPath || null, 100);
+    throw buildAndroidBootstrapError(
+      `Android emulator did not finish booting within ${timeoutMs} ms`,
+      {
+        code: 'ANDROID_BOOTSTRAP_TIMEOUT',
+        timeoutMs,
+        logPath: state.logPath || null,
+        logTail,
+        state: {
+          emulatorPid: state.emulatorPid || null,
+          serial: state.serial || null,
+          startupPhase: state.startupPhase || null,
+          lastStartError: state.lastStartError || null,
+        },
+      }
+    );
   }
 
   async ensureDevice() {
@@ -2184,8 +2372,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);
@@ -2203,7 +2400,42 @@ 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) {
+        logAndroidIssue('screenshot_attempt_failed', {
+          scopeKey: this.scopeKey,
+          serial,
+          attempt: attempt + 1,
+        });
+        await sleep(500);
+      }
+    }
+    fs.rmSync(localTmp, { force: true });
+    await this.#adb(serial, `shell rm -f ${quoteShell(remoteTmp)}`, { timeout: 10000 }).catch(() => {});
+    if (!captured) {
+      logAndroidIssue('screenshot_capture_failed', {
+        scopeKey: this.scopeKey,
+        serial,
+        fullPath,
+      });
+      throw new Error('Failed to capture a valid Android screenshot.');
+    }
     if (artifactRecord) {
       this.artifactStore.finalizeFile(artifactRecord.artifactId, fullPath);
     }
@@ -2561,9 +2793,46 @@ class AndroidController {
   }
 
   async listApps(args = {}) {
-    const serial = await this.ensureDevice();
+    let serial = null;
+    try {
+      serial = await this.ensureDevice();
+    } catch (error) {
+      logAndroidIssue('list_apps_device_not_ready', {
+        scopeKey: this.scopeKey,
+        message: String(error?.message || error || 'Android device is not ready.'),
+      });
+      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) {
+        logAndroidIssue('list_apps_command_failed', {
+          scopeKey: this.scopeKey,
+          serial,
+          command: cmd,
+          message: String(retryError?.message || error?.message || 'Failed to list Android apps.'),
+        });
+        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())
@@ -2642,6 +2911,8 @@ class AndroidController {
 
   async getStatus() {
     const state = this.#readState();
+    const bootstrapWorkerPid = Number(state.bootstrapWorkerPid || 0) || null;
+    const bootstrapWorkerAlive = isProcessAlive(bootstrapWorkerPid);
     const devices = isExecutable(adbBinary())
       ? await this.listDevices({ ensureBootstrapped: false }).catch(() => [])
       : [];
@@ -2674,8 +2945,10 @@ 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.starting === true || this.startPromise != null || bootstrapWorkerAlive)
+        ? (state.startupPhase || (bootstrapWorkerAlive ? 'Preparing Android runtime' : null))
+        : null,
       startRequestedAt: state.startRequestedAt || null,
       lastStartError: state.lastStartError || null,
       sdkRoot: activeAndroidSdkRoot(),
@@ -2686,7 +2959,7 @@ class AndroidController {
       serial: state.serial,
       serialOwnedByCurrentUser,
       emulatorPid: state.emulatorPid,
-      bootstrapWorkerPid: Number(state.bootstrapWorkerPid || 0) || null,
+      bootstrapWorkerPid,
       systemImage: state.systemImage || null,
       systemImageArch: state.systemImageArch || null,
       preferredSystemImageArchs: systemImageArchCandidates(),