neoagent 2.3.1-beta.0 → 2.3.1-beta.100

package/server/services/android/controller.js

@@ -1,1919 +1,601 @@
+'use strict';
+
+const { spawn, spawnSync } = require('child_process');
 const fs = require('fs');
+const https = require('https');
+const net = require('net');
 const os = require('os');
 const path = require('path');
-const https = require('https');
-const { spawn, spawnSync } = require('child_process');
-const lockfile = require('proper-lockfile');
-const { CLIExecutor } = require('../cli/executor');
-const { DATA_DIR, RUNTIME_HOME } = require('../../../runtime/paths');
-const { findBestNode, parseUiDump, summarizeNode } = require('./uia');
-
-const ANDROID_ROOT = path.join(RUNTIME_HOME, 'android');
-const SDK_ROOT = path.join(ANDROID_ROOT, 'sdk');
-const CMDLINE_ROOT = path.join(SDK_ROOT, 'cmdline-tools');
-const CMDLINE_LATEST = path.join(CMDLINE_ROOT, 'latest');
-const ARTIFACTS_DIR = path.join(DATA_DIR, 'android');
-const SCREENSHOTS_DIR = path.join(DATA_DIR, 'screenshots');
-const UI_DUMPS_DIR = path.join(ARTIFACTS_DIR, 'ui-dumps');
-const LOGS_DIR = path.join(ARTIFACTS_DIR, 'logs');
-const TMP_DIR = path.join(ARTIFACTS_DIR, 'tmp');
-const AVD_HOME = path.join(ANDROID_ROOT, 'avd');
-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');
-const DEFAULT_AVD_NAME = 'neoagent-default';
-const DEFAULT_DATA_PARTITION = '1024M';
-const DEFAULT_SDCARD_SIZE = '128M';
-const DEFAULT_RAM_SIZE = '1024';
-const DEFAULT_KEYEVENTS = Object.freeze({
-  home: 3,
-  back: 4,
-  up: 19,
-  down: 20,
-  left: 21,
-  right: 22,
-  enter: 66,
-  menu: 82,
-  search: 84,
-  app_switch: 187,
-  delete: 67,
-  escape: 111,
-  space: 62,
-  tab: 61,
-});
-
-for (const dir of [ANDROID_ROOT, SDK_ROOT, ARTIFACTS_DIR, SCREENSHOTS_DIR, UI_DUMPS_DIR, LOGS_DIR, TMP_DIR, AVD_HOME, STATE_DIR]) {
-  fs.mkdirSync(dir, { recursive: true });
-}
-
-function sanitizeScopeKey(value) {
-  const normalized = String(value || '')
-    .trim()
-    .toLowerCase()
-    .replace(/[^a-z0-9_-]+/g, '-');
-  return normalized.replace(/^-+|-+$/g, '').slice(0, 48) || 'default';
-}
-
-function resolveStateFile(scopeKey) {
-  const key = sanitizeScopeKey(scopeKey);
-  if (key === 'default') {
-    return STATE_FILE;
-  }
-  return path.join(STATE_DIR, `${key}.json`);
-}
-
-function readOwnership() {
-  return withOwnershipLock(() => {
-    return readOwnershipUnlocked();
-  });
-}
-
-function writeOwnership(nextOwners) {
-  withOwnershipLock(() => {
-    writeOwnershipUnlocked(nextOwners);
-  });
-}
-
-function readOwnershipUnlocked() {
-  try {
-    const parsed = JSON.parse(fs.readFileSync(OWNERSHIP_FILE, 'utf8'));
-    if (!parsed || typeof parsed !== 'object') {
-      return {};
-    }
-    return parsed;
-  } catch {
-    return {};
-  }
-}
+const { DATA_DIR } = require('../../../runtime/paths');
 
-function writeOwnershipUnlocked(nextOwners) {
-  const tempPath = `${OWNERSHIP_FILE}.tmp`;
-  fs.writeFileSync(tempPath, JSON.stringify(nextOwners, null, 2));
-  fs.renameSync(tempPath, OWNERSHIP_FILE);
-}
+// ─── Constants ───────────────────────────────────────────────────────────────
 
-function withOwnershipLock(work) {
-  fs.mkdirSync(path.dirname(OWNERSHIP_FILE), { recursive: true });
-  if (!fs.existsSync(OWNERSHIP_FILE)) {
-    fs.writeFileSync(OWNERSHIP_FILE, '{}');
-  }
-  let lastError = null;
-  for (let attempt = 0; attempt < 3; attempt += 1) {
-    try {
-      const release = lockfile.lockSync(OWNERSHIP_FILE, {
-        realpath: false,
-      });
-      try {
-        return work();
-      } finally {
-        release();
-      }
-    } catch (err) {
-      lastError = err;
-      if (attempt === 2) {
-        break;
-      }
-    }
-  }
-  throw lastError;
-}
+const DEFAULT_SDK_DIR = path.join(os.homedir(), '.neoagent', 'android-sdk');
+const STATE_DIR = path.join(DATA_DIR, 'android', 'state');
+const LOGO_PATH = path.join(__dirname, '..', '..', '..', 'flutter_app', 'assets', 'branding', 'app_icon_512.png');
 
-function normalizeOwnerKey(userId) {
-  if (userId == null || String(userId).trim() === '') {
-    return 'system';
-  }
-  return `user-${sanitizeScopeKey(userId)}`;
-}
+// Even ports in 5554–5682 (documented ADB range). 65 slots for 65 concurrent users.
+const ADB_PORT_BASE = 5554;
+const ADB_PORT_SLOTS = 65;
 
-function pruneOwnershipByDevices(owners, devices = []) {
-  const presentSerials = new Set(
-    devices
-      .map((device) => String(device?.serial || '').trim())
-      .filter(Boolean)
-  );
-  const next = {};
-  let changed = false;
-
-  for (const [serial, owner] of Object.entries(owners || {})) {
-    if (!presentSerials.has(serial)) {
-      changed = true;
-      continue;
-    }
-    next[serial] = owner;
-  }
+const CMDLINE_TOOLS_VERSION = '14742923';
+const CMDLINE_TOOLS_URLS = {
+  darwin: `https://dl.google.com/android/repository/commandlinetools-mac-${CMDLINE_TOOLS_VERSION}_latest.zip`,
+  linux:  `https://dl.google.com/android/repository/commandlinetools-linux-${CMDLINE_TOOLS_VERSION}_latest.zip`,
+  win32:  `https://dl.google.com/android/repository/commandlinetools-win-${CMDLINE_TOOLS_VERSION}_latest.zip`,
+};
 
-  return { next, changed };
-}
+fs.mkdirSync(STATE_DIR, { recursive: true });
 
-function sleep(ms) {
-  return new Promise((resolve) => setTimeout(resolve, ms));
-}
+// ─── State persistence ───────────────────────────────────────────────────────
 
-function tailFile(filePath, maxLines = 40) {
-  try {
-    const lines = fs.readFileSync(filePath, 'utf8')
-      .split('\n')
-      .map((line) => line.trim())
-      .filter(Boolean);
-    return lines.slice(-maxLines);
-  } catch {
-    return [];
-  }
-}
+function stateFile(userId) { return path.join(STATE_DIR, `${userId}.json`); }
 
-function commandExists(command) {
-  const probe = spawnSync('bash', ['-lc', `command -v "${command}"`], { encoding: 'utf8' });
-  return probe.status === 0;
+function readState(userId) {
+  try { return JSON.parse(fs.readFileSync(stateFile(userId), 'utf8')); }
+  catch { return { userId, bootstrapped: false, starting: false, startupPhase: null, lastStartError: null, pid: null, adbSerial: null }; }
 }
 
-function parseResolvedLaunchComponent(output, packageName) {
-  const lines = String(output || '')
-    .split('\n')
-    .map((line) => line.trim())
-    .filter(Boolean);
-  const normalizedPackage = String(packageName || '').trim();
-  const componentPattern = /^[A-Za-z0-9._$]+\/[A-Za-z0-9._$]+$/;
-  const relativePattern = /^[A-Za-z0-9._$]+\/\.[A-Za-z0-9._$]+$/;
-
-  const exact = lines.find((line) =>
-    normalizedPackage
-      ? line.startsWith(`${normalizedPackage}/`)
-      : componentPattern.test(line) || relativePattern.test(line)
-  );
-  if (exact) return exact;
-
-  return lines.find((line) => componentPattern.test(line) || relativePattern.test(line)) || null;
+function writeState(userId, patch) {
+  const current = readState(userId);
+  fs.writeFileSync(stateFile(userId), JSON.stringify({ ...current, ...patch }, null, 2));
 }
 
-function appendState(patch, stateFile = STATE_FILE) {
-  const current = readState(stateFile);
-  const next = {
-    ...current,
-    ...patch,
-    updatedAt: new Date().toISOString(),
-  };
-  fs.writeFileSync(stateFile, JSON.stringify(next, null, 2));
-  return next;
-}
+// ─── SDK resolution ──────────────────────────────────────────────────────────
 
-function readState(stateFile = STATE_FILE) {
-  try {
-    return JSON.parse(fs.readFileSync(stateFile, 'utf8'));
-  } catch {
-    return {
-      avdName: DEFAULT_AVD_NAME,
-      serial: null,
-      emulatorPid: null,
-      bootstrapped: false,
-      updatedAt: null,
-    };
+function findExistingSdk() {
+  const candidates = [
+    process.env.ANDROID_HOME,
+    process.env.ANDROID_SDK_ROOT,
+    path.join(os.homedir(), 'Library', 'Android', 'sdk'),
+    path.join(os.homedir(), 'Android', 'Sdk'),
+    path.join(os.homedir(), '.android', 'sdk'),
+    DEFAULT_SDK_DIR,
+  ].filter(Boolean);
+  for (const dir of candidates) {
+    if (fs.existsSync(path.join(dir, 'emulator', process.platform === 'win32' ? 'emulator.exe' : 'emulator'))) return dir;
   }
+  return null;
 }
 
-function platformTag() {
-  if (process.platform === 'darwin') return 'mac';
-  if (process.platform === 'linux') return 'linux';
-  throw new Error(`Android runtime bootstrap is only supported on macOS and Linux, not ${process.platform}`);
+function sdkManagerBin(sdkDir) {
+  return path.join(sdkDir, 'cmdline-tools', 'latest', 'bin', process.platform === 'win32' ? 'sdkmanager.bat' : 'sdkmanager');
 }
-
-function systemImageArch() {
-  if (process.arch === 'arm64') return 'arm64-v8a';
-  return 'x86_64';
+function avdManagerBin(sdkDir) {
+  return path.join(sdkDir, 'cmdline-tools', 'latest', 'bin', process.platform === 'win32' ? 'avdmanager.bat' : 'avdmanager');
 }
-
-function parseCsvEnv(value) {
-  return String(value || '')
-    .split(',')
-    .map((entry) => entry.trim())
-    .filter(Boolean);
+function emulatorBin(sdkDir) {
+  return path.join(sdkDir, 'emulator', process.platform === 'win32' ? 'emulator.exe' : 'emulator');
 }
-
-function configuredSystemImagePackage() {
-  return String(process.env.ANDROID_SYSTEM_IMAGE_PACKAGE || '').trim() || null;
+function adbBin(sdkDir) {
+  return path.join(sdkDir, 'platform-tools', process.platform === 'win32' ? 'adb.exe' : 'adb');
 }
 
-function configuredSystemImagePlatform() {
-  return String(process.env.ANDROID_SYSTEM_IMAGE_PLATFORM || '').trim() || null;
-}
+// ─── System image selection ──────────────────────────────────────────────────
 
-function shouldForceSdkRefresh() {
-  return String(process.env.ANDROID_FORCE_SDK_REFRESH || '').trim().toLowerCase() === 'true';
-}
+function pickSystemImage(sdkDir) {
+  const siRoot = path.join(sdkDir, 'system-images');
+  if (!fs.existsSync(siRoot)) return null;
 
-function systemImageArchCandidates() {
-  const configured = parseCsvEnv(process.env.ANDROID_SYSTEM_IMAGE_ARCH);
-  if (configured.length > 0) {
-    return configured.filter((arch, index, list) => list.indexOf(arch) === index);
-  }
-  const preferred = systemImageArch();
-  const fallbacks = ['x86_64', 'arm64-v8a'];
-  return [preferred, ...fallbacks].filter((arch, index, list) => list.indexOf(arch) === index);
-}
+  const hostArm = os.arch() === 'arm64' || os.arch() === 'arm';
+  const preferred = hostArm ? 'arm64-v8a' : 'x86_64';
+  const fallback  = hostArm ? 'x86_64' : 'arm64-v8a';
 
-function parseSystemImagePlatform(platformId) {
-  const stable = String(platformId || '').match(/^android-(\d+)$/);
-  if (stable) {
-    return {
-      platformId,
-      apiLevel: Number(stable[1] || 0),
-      stable: true,
-    };
+  const images = [];
+  for (const api of fs.readdirSync(siRoot)) {
+    const apiPath = path.join(siRoot, api);
+    if (!fs.statSync(apiPath).isDirectory()) continue;
+    for (const tag of fs.readdirSync(apiPath)) {
+      const tagPath = path.join(apiPath, tag);
+      if (!fs.statSync(tagPath).isDirectory()) continue;
+      for (const abi of fs.readdirSync(tagPath)) {
+        images.push({ api, tag, abi, key: `system-images;${api};${tag};${abi}` });
+      }
+    }
   }
 
-  const preview = String(platformId || '').match(/^android-([A-Za-z][A-Za-z0-9_-]*)$/);
-  if (preview) {
-    return {
-      platformId,
-      apiLevel: 0,
-      stable: false,
+  images.sort((a, b) => {
+    const score = img => {
+      let s = 0;
+      if (img.abi === preferred) s += 100;
+      else if (img.abi === fallback) s += 10;
+      if (img.tag === 'google_apis') s += 5;
+      else if (img.tag === 'google_apis_playstore') s += 3;
+      s += parseInt(img.api.replace('android-', '') || '0', 10);
+      return s;
     };
-  }
-
-  return {
-    platformId,
-    apiLevel: 0,
-    stable: false,
-  };
-}
-
-function sdkEnv() {
-  const base = {
-    ...process.env,
-    ANDROID_HOME: SDK_ROOT,
-    ANDROID_SDK_ROOT: SDK_ROOT,
-    ANDROID_AVD_HOME: AVD_HOME,
-    AVD_HOME,
-  };
-  const pathParts = [
-    path.join(SDK_ROOT, 'platform-tools'),
-    path.join(SDK_ROOT, 'emulator'),
-    path.join(CMDLINE_LATEST, 'bin'),
-    process.env.PATH || '',
-  ].filter(Boolean);
-  base.PATH = pathParts.join(path.delimiter);
-  return base;
-}
-
-function adbBinary() {
-  return process.env.ANDROID_ADB_PATH || path.join(SDK_ROOT, 'platform-tools', process.platform === 'win32' ? 'adb.exe' : 'adb');
-}
-
-function sdkManagerBinary() {
-  return path.join(CMDLINE_LATEST, 'bin', process.platform === 'win32' ? 'sdkmanager.bat' : 'sdkmanager');
-}
-
-function avdManagerBinary() {
-  return path.join(CMDLINE_LATEST, 'bin', process.platform === 'win32' ? 'avdmanager.bat' : 'avdmanager');
-}
-
-function emulatorBinary() {
-  return path.join(SDK_ROOT, 'emulator', process.platform === 'win32' ? 'emulator.exe' : 'emulator');
+    return score(b) - score(a);
+  });
+  return images[0]?.key || null;
 }
 
-function isExecutable(filePath) {
-  try {
-    fs.accessSync(filePath, fs.constants.X_OK);
-    return true;
-  } catch {
-    return false;
-  }
+function defaultSystemImage() {
+  const abi = (os.arch() === 'arm64' || os.arch() === 'arm') ? 'arm64-v8a' : 'x86_64';
+  return `system-images;android-33;google_apis;${abi}`;
 }
 
-function fetchText(url) {
-  return new Promise((resolve, reject) => {
-    https.get(url, (res) => {
-      if (res.statusCode && res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
-        return resolve(fetchText(res.headers.location));
-      }
-      if (res.statusCode !== 200) {
-        reject(new Error(`GET ${url} failed with status ${res.statusCode}`));
-        return;
-      }
-      let body = '';
-      res.setEncoding('utf8');
-      res.on('data', (chunk) => { body += chunk; });
-      res.on('end', () => resolve(body));
-    }).on('error', reject);
-  });
-}
+// ─── SDK setup ───────────────────────────────────────────────────────────────
 
 function downloadFile(url, dest) {
   return new Promise((resolve, reject) => {
-    const out = fs.createWriteStream(dest);
-    https.get(url, (res) => {
-      if (res.statusCode && res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
-        out.close();
-        fs.rmSync(dest, { force: true });
-        return resolve(downloadFile(res.headers.location, dest));
-      }
-      if (res.statusCode !== 200) {
-        out.close();
-        fs.rmSync(dest, { force: true });
-        reject(new Error(`Download failed with status ${res.statusCode}`));
-        return;
+    const file = fs.createWriteStream(dest);
+    const follow = u => https.get(u, res => {
+      if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+        file.close(); return follow(res.headers.location);
       }
-      res.pipe(out);
-      out.on('finish', () => out.close(resolve));
-    }).on('error', (err) => {
-      out.close();
-      fs.rmSync(dest, { force: true });
-      reject(err);
-    });
+      if (res.statusCode !== 200) { file.close(); return reject(new Error(`HTTP ${res.statusCode}`)); }
+      res.pipe(file);
+      file.on('finish', () => file.close(resolve));
+    }).on('error', err => { file.close(); fs.unlink(dest, () => {}); reject(err); });
+    follow(url);
   });
 }
 
-function extractZip(zipPath, destDir) {
-  if (commandExists('unzip')) {
-    const res = spawnSync('unzip', ['-qo', zipPath, '-d', destDir], { encoding: 'utf8' });
-    if (res.status === 0) return;
-    throw new Error(res.stderr || `unzip failed for ${zipPath}`);
-  }
-
-  if (process.platform === 'darwin' && commandExists('ditto')) {
-    const res = spawnSync('ditto', ['-x', '-k', zipPath, destDir], { encoding: 'utf8' });
-    if (res.status === 0) return;
-    throw new Error(res.stderr || `ditto failed for ${zipPath}`);
-  }
-
-  throw new Error('Neither unzip nor ditto is available to extract Android SDK archives');
-}
-
-function listFilesRecursive(rootDir, predicate, bucket = []) {
-  for (const entry of fs.readdirSync(rootDir, { withFileTypes: true })) {
-    const fullPath = path.join(rootDir, entry.name);
-    if (entry.isDirectory()) {
-      listFilesRecursive(fullPath, predicate, bucket);
-      continue;
-    }
-    if (!predicate || predicate(fullPath, entry)) {
-      bucket.push(fullPath);
-    }
-  }
-  return bucket;
-}
-
-function resolveBundleInstallTargets(bundleDir) {
-  const apkFiles = listFilesRecursive(bundleDir, (filePath) => path.extname(filePath).toLowerCase() === '.apk')
-    .sort((a, b) => a.localeCompare(b));
-  if (apkFiles.length === 0) {
-    throw new Error('APK bundle did not contain any installable .apk files.');
-  }
+async function ensureSdk(sdkDir, onProgress) {
+  if (fs.existsSync(sdkManagerBin(sdkDir))) return;
+  const url = CMDLINE_TOOLS_URLS[process.platform];
+  if (!url) throw new Error(`No cmdline-tools download for platform: ${process.platform}`);
 
-  const universalApk = apkFiles.find((filePath) => path.basename(filePath).toLowerCase() === 'universal.apk');
-  if (universalApk) {
-    return {
-      mode: 'single',
-      installPaths: [universalApk],
-      layout: 'universal',
-    };
-  }
+  fs.mkdirSync(sdkDir, { recursive: true });
+  onProgress('Downloading Android SDK command-line tools (~150 MB)…');
+  const zip = path.join(os.tmpdir(), 'cmdline-tools.zip');
+  await downloadFile(url, zip);
 
-  if (apkFiles.length === 1) {
-    return {
-      mode: 'single',
-      installPaths: apkFiles,
-      layout: 'single-apk',
-    };
-  }
+  onProgress('Extracting…');
+  const toolsDir = path.join(sdkDir, 'cmdline-tools');
+  fs.mkdirSync(toolsDir, { recursive: true });
+  const unzip = spawnSync('unzip', ['-qo', zip, '-d', toolsDir]);
+  fs.unlinkSync(zip);
+  if (unzip.status !== 0) throw new Error('unzip failed');
 
-  throw new Error(
-    'APK bundles must include a universal APK. Export a universal .apks bundle or upload a single .apk instead.'
-  );
+  const extracted = path.join(toolsDir, 'cmdline-tools');
+  const latest = path.join(toolsDir, 'latest');
+  if (fs.existsSync(extracted) && !fs.existsSync(latest)) fs.renameSync(extracted, latest);
+  if (!fs.existsSync(sdkManagerBin(sdkDir))) throw new Error('sdkmanager not found after extraction');
 }
 
-function parseLatestCmdlineToolsUrl(xml) {
-  const tag = platformTag() === 'mac' ? 'macosx' : 'linux';
-  const packageMatch = xml.match(new RegExp(`<remotePackage\\s+path="cmdline-tools;latest">([\\s\\S]*?)<\\/remotePackage>`));
-  if (!packageMatch) throw new Error('Could not locate cmdline-tools;latest in Android repository metadata');
+async function ensurePackages(sdkDir, onProgress) {
+  const env = { ...process.env, ANDROID_SDK_ROOT: sdkDir, ANDROID_HOME: sdkDir };
+  const sdkman = sdkManagerBin(sdkDir);
 
-  const archiveBlocks = packageMatch[1].match(/<archive>[\s\S]*?<\/archive>/g) || [];
-  for (const block of archiveBlocks) {
-    if (!new RegExp(`<host-os>${tag}<\\/host-os>`).test(block)) continue;
-    const urlMatch = block.match(/<url>\s*([^<]*commandlinetools-[^<]+_latest\.zip)\s*<\/url>/);
-    if (urlMatch) return `https://dl.google.com/android/repository/${urlMatch[1]}`;
-  }
+  onProgress('Accepting Android SDK licenses…');
+  spawnSync(sdkman, ['--licenses', `--sdk_root=${sdkDir}`], { input: 'y\n'.repeat(20), encoding: 'utf8', env, stdio: ['pipe', 'pipe', 'pipe'] });
 
-  throw new Error(`Could not find a command line tools archive for ${tag}`);
-}
-
-function systemImageTagScore(tag) {
-  const value = String(tag || '').toLowerCase();
-  if (value.startsWith('google_apis_playstore')) return 50;
-  if (value.startsWith('google_apis')) return 40;
-  if (value === 'google_atd') return 30;
-  if (value === 'aosp_atd') return 20;
-  if (value === 'default') return 10;
-  return 0;
-}
-
-function parseSystemImageCandidates(entries = []) {
-  return entries.map((entry) => {
-    const platform = parseSystemImagePlatform(entry.platformId);
-    return {
-      packageName: entry.packageName,
-      platformId: entry.platformId,
-      tag: entry.tag,
-      arch: entry.arch,
-      apiLevel: platform.apiLevel,
-      stable: platform.stable,
-      tagScore: systemImageTagScore(entry.tag),
-    };
+  const img = defaultSystemImage();
+  onProgress(`Installing platform-tools, emulator, ${img} (~1–2 GB, first run only)…`);
+  const r = spawnSync(sdkman, ['platform-tools', 'emulator', img, `--sdk_root=${sdkDir}`], {
+    encoding: 'utf8', env, stdio: ['pipe', 'pipe', 'pipe'], timeout: 20 * 60 * 1000,
   });
+  if (r.status !== 0) throw new Error(`sdkmanager failed: ${(r.stderr || r.stdout || '').slice(0, 500)}`);
 }
 
-function parseSystemImages(listOutput) {
-  const matches = [];
-  const regex = /system-images;(android-[^;\s]+);([^;\s]+);([^;\s]+)/g;
-  let match = regex.exec(listOutput);
-  while (match) {
-    matches.push({
-      packageName: match[0],
-      platformId: match[1],
-      tag: match[2],
-      arch: match[3],
-    });
-    match = regex.exec(listOutput);
-  }
-
-  return parseSystemImageCandidates(matches);
-}
-
-function parseInstalledSystemImages() {
-  const root = path.join(SDK_ROOT, 'system-images');
-  if (!fs.existsSync(root)) {
-    return [];
-  }
-
-  const matches = [];
-  const platforms = fs.readdirSync(root, { withFileTypes: true })
-    .filter((entry) => entry.isDirectory())
-    .map((entry) => entry.name);
-
-  for (const platformId of platforms) {
-    const platformDir = path.join(root, platformId);
-    const tags = fs.readdirSync(platformDir, { withFileTypes: true })
-      .filter((entry) => entry.isDirectory())
-      .map((entry) => entry.name);
-    for (const tag of tags) {
-      const tagDir = path.join(platformDir, tag);
-      const archs = fs.readdirSync(tagDir, { withFileTypes: true })
-        .filter((entry) => entry.isDirectory())
-        .map((entry) => entry.name);
-      for (const arch of archs) {
-        const packageXml = path.join(tagDir, arch, 'package.xml');
-        if (!fs.existsSync(packageXml)) {
-          continue;
-        }
-        matches.push({
-          packageName: `system-images;${platformId};${tag};${arch}`,
-          platformId,
-          tag,
-          arch,
-        });
-      }
-    }
-  }
-
-  return parseSystemImageCandidates(matches);
-}
-
-function rankSystemImagePool(pool) {
-  const preferredMatches = pool.filter((candidate) => candidate.tagScore > 0);
-  const rankedPool = preferredMatches.length > 0 ? preferredMatches : pool;
-
-  rankedPool.sort((a, b) =>
-    Number(b.stable) - Number(a.stable) ||
-    b.tagScore - a.tagScore ||
-    b.apiLevel - a.apiLevel ||
-    a.packageName.localeCompare(b.packageName)
-  );
-
-  return rankedPool;
-}
-
-function chooseConfiguredSystemImage(listOutput) {
-  const matches = Array.isArray(listOutput)
-    ? parseSystemImageCandidates(listOutput)
-    : parseSystemImages(listOutput);
-  const packageName = configuredSystemImagePackage();
-  if (packageName) {
-    return matches.find((candidate) => candidate.packageName === packageName) || null;
-  }
-
-  const platformId = configuredSystemImagePlatform();
-  if (!platformId) return null;
-
-  const pool = matches.filter((candidate) => candidate.platformId === platformId);
-  if (pool.length === 0) return null;
-
-  let archPool = [];
-  for (const arch of systemImageArchCandidates()) {
-    archPool = pool.filter((candidate) => candidate.arch === arch);
-    if (archPool.length > 0) break;
-  }
-
-  return rankSystemImagePool(archPool.length > 0 ? archPool : pool)[0] || null;
-}
-
-function chooseLatestSystemImage(listOutput, preferredArchs = systemImageArchCandidates()) {
-  const matches = Array.isArray(listOutput)
-    ? parseSystemImageCandidates(listOutput)
-    : parseSystemImages(listOutput);
-  const archPool = Array.isArray(preferredArchs) && preferredArchs.length > 0
-    ? preferredArchs
-    : systemImageArchCandidates();
-
-  let pool = [];
-  for (const arch of archPool) {
-    pool = matches.filter((candidate) => candidate.arch === arch);
-    if (pool.length > 0) break;
-  }
-
-  if (pool.length === 0) {
-    pool = matches;
-  }
-
-  return rankSystemImagePool(pool)[0] || null;
-}
-
-function formatSystemImageError(listOutput) {
-  const candidates = Array.isArray(listOutput)
-    ? parseSystemImageCandidates(listOutput)
-    : parseSystemImages(listOutput);
-  const availableArchs = [...new Set(candidates.map((candidate) => candidate.arch))].sort();
-  const wantedArchs = systemImageArchCandidates().join(', ');
-  const packageName = configuredSystemImagePackage();
-  const platformId = configuredSystemImagePlatform();
-  const available = availableArchs.length > 0 ? availableArchs.join(', ') : 'none';
-  const overrideDetails = [
-    packageName ? `package=${packageName}` : null,
-    platformId ? `platform=${platformId}` : null,
-  ].filter(Boolean);
-  const overrideText = overrideDetails.length > 0 ? ` Configured override: ${overrideDetails.join(', ')}.` : '';
-  return `No compatible Android system image found. Preferred architectures: ${wantedArchs}. Available architectures: ${available}.${overrideText}`;
+function ensureEmulatorRegistered(sdkDir) {
+  const packageXml = path.join(sdkDir, 'emulator', 'package.xml');
+  if (fs.existsSync(packageXml) || !fs.existsSync(emulatorBin(sdkDir))) return;
+  const env = { ...process.env, ANDROID_SDK_ROOT: sdkDir, ANDROID_HOME: sdkDir };
+  spawnSync(sdkManagerBin(sdkDir), ['emulator', `--sdk_root=${sdkDir}`], {
+    encoding: 'utf8', env, input: 'y\n'.repeat(5), stdio: ['pipe', 'pipe', 'pipe'], timeout: 5 * 60 * 1000,
+  });
 }
 
-function parseApiLevelFromSystemImage(packageName) {
-  const match = String(packageName || '').match(/system-images;android-(\d+);/);
-  return match ? Number(match[1] || 0) : 0;
-}
+function ensureAvd(sdkDir, avdName, onProgress) {
+  const avdDir = path.join(os.homedir(), '.android', 'avd', `${avdName}.avd`);
+  if (fs.existsSync(avdDir)) return;
 
-function androidTextEscape(text) {
-  return String(text || '')
-    .replace(/\\/g, '\\\\')
-    .replace(/ /g, '%s')
-    .replace(/"/g, '\\"')
-    .replace(/'/g, "\\'")
-    .replace(/[&()<>|;$`]/g, '');
-}
+  ensureEmulatorRegistered(sdkDir);
+  const img = pickSystemImage(sdkDir) || defaultSystemImage();
+  onProgress(`Creating AVD "${avdName}" using ${img}…`);
 
-function quoteShell(value) {
-  return `'${String(value || '').replace(/'/g, `'\\''`)}'`;
-}
+  const env = { ...process.env, ANDROID_SDK_ROOT: sdkDir, ANDROID_HOME: sdkDir };
+  const r = spawnSync(avdManagerBin(sdkDir), ['create', 'avd', '-n', avdName, '-k', img, '--device', 'pixel', '--force'], {
+    encoding: 'utf8', env, stdio: ['pipe', 'pipe', 'pipe'], input: '\n',
+  });
+  if (r.status !== 0) throw new Error(`avdmanager failed: ${(r.stderr || r.stdout || '').slice(0, 500)}`);
 
-function updateIniValue(content, key, value) {
-  const escapedKey = key.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-  const line = `${key}=${value}`;
-  if (new RegExp(`^${escapedKey}=.*$`, 'm').test(content)) {
-    return content.replace(new RegExp(`^${escapedKey}=.*$`, 'm'), line);
+  // Patch config: sparse QCOW2 (no pre-allocation), smaller cache partition.
+  const cfgPath = path.join(avdDir, 'config.ini');
+  if (fs.existsSync(cfgPath)) {
+    let cfg = fs.readFileSync(cfgPath, 'utf8');
+    cfg = cfg.replace(/disk\.dataPartition\.size\s*=\s*\S+/, `disk.dataPartition.size = ${2 * 1024 * 1024 * 1024}`);
+    cfg = cfg.replace(/disk\.cachePartition\.size\s*=\s*\S+/, `disk.cachePartition.size = ${32 * 1024 * 1024}`);
+    cfg = cfg.replace(/userdata\.useQcow2\s*=\s*\S+/, 'userdata.useQcow2 = yes');
+    if (!/userdata\.useQcow2/.test(cfg)) cfg += '\nuserdata.useQcow2 = yes\n';
+    fs.writeFileSync(cfgPath, cfg);
   }
-  return `${content.replace(/\s*$/, '')}\n${line}\n`;
 }
 
-function readIniValue(content, key) {
-  const escapedKey = key.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-  const match = content.match(new RegExp(`^${escapedKey}=(.*)$`, 'm'));
-  return match ? String(match[1] || '').trim() : null;
-}
+// ─── Helpers ─────────────────────────────────────────────────────────────────
 
-function systemImagePackageToRelativeDir(packageName) {
-  const parts = String(packageName || '').split(';').filter(Boolean);
-  if (parts.length !== 4 || parts[0] !== 'system-images') {
-    return null;
-  }
-  return `${parts.join('/')}/`;
+function hashCode(str) {
+  let h = 0;
+  for (let i = 0; i < str.length; i++) h = (Math.imul(31, h) + str.charCodeAt(i)) | 0;
+  return h;
 }
 
-function systemImagePackageToAbi(packageName) {
-  const parts = String(packageName || '').split(';').filter(Boolean);
-  if (parts.length !== 4 || parts[0] !== 'system-images') {
-    return null;
-  }
-  return parts[3] || null;
+// Escape a string for safe use inside single-quoted Android shell (`mksh`) commands.
+function shellEscape(str) {
+  return String(str).replace(/'/g, "'\\''");
 }
 
-function abiToCpuArch(abi) {
-  const value = String(abi || '').trim().toLowerCase();
-  if (value === 'arm64-v8a') return 'arm64';
-  if (value === 'armeabi-v7a' || value === 'armeabi') return 'arm';
-  if (value === 'x86_64') return 'x86_64';
-  if (value === 'x86') return 'x86';
-  return null;
+// Validate an Android package name or intent action (alphanumeric + dots + underscores).
+function isSafeIdentifier(str) {
+  return /^[\w.]+$/.test(String(str || ''));
 }
 
-function systemImagePackageToCpuArch(packageName) {
-  return abiToCpuArch(systemImagePackageToAbi(packageName));
-}
-
-function describeAutoFixChanges(current, next, fields = []) {
-  return fields
-    .map((field) => {
-      const before = current?.[field] ?? null;
-      const after = next?.[field] ?? null;
-      if (before === after) return null;
-      return `${field}: ${before ?? 'null'} -> ${after ?? 'null'}`;
-    })
-    .filter(Boolean)
-    .join(', ');
-}
-
-function sanitizeUiXml(raw) {
-  const text = String(raw || '');
-  const start = text.indexOf('<?xml');
-  const end = text.lastIndexOf('</hierarchy>');
-  if (start >= 0 && end >= start) {
-    return text.slice(start, end + '</hierarchy>'.length);
-  }
-  return text.trim();
-}
+// ─── AndroidController ───────────────────────────────────────────────────────
 
 class AndroidController {
   constructor(options = {}) {
-    this.io = options?.io;
-    this.userId = options?.userId != null ? String(options.userId) : null;
-    this.artifactStore = options?.artifactStore || null;
-    this.runtimeBackend = options?.runtimeBackend || 'host';
-    this.scopeKey = sanitizeScopeKey(this.userId ? `user-${this.userId}` : 'default');
-    this.ownerKey = normalizeOwnerKey(this.userId);
-    this.stateFile = resolveStateFile(this.scopeKey);
-    this.cli = new CLIExecutor();
-    this.avdName = this.#readState().avdName || (this.userId ? `neoagent-${this.scopeKey}` : DEFAULT_AVD_NAME);
-    this.bootstrapPromise = null;
-    this.startPromise = null;
-    this.#registerProcessCleanup();
-  }
-
-  static cleanupRegistered = false;
-  static cleanupControllers = new Set();
-
-  #readState() {
-    return readState(this.stateFile);
-  }
-
-  #appendState(patch) {
-    return appendState(patch, this.stateFile);
-  }
-
-  #readOwnership() {
-    return readOwnership();
-  }
-
-  #writeOwnership(nextOwners) {
-    writeOwnership(nextOwners);
+    this.userId   = String(options.userId || 'default').trim();
+    this.avdName  = `neoagent_${this.userId}`;
+    // Deterministic ADB console port per user, within documented range 5554–5682 (even only).
+    this.adbPort  = ADB_PORT_BASE + ((hashCode(this.userId) >>> 0) % ADB_PORT_SLOTS) * 2;
+    this.adbSerial = `emulator-${this.adbPort}`;
+    this.sdkDir   = options.sdkDir || findExistingSdk() || DEFAULT_SDK_DIR;
+    this.artifactStore = options.artifactStore || null;
+    this.startPromise  = null;
   }
 
-  #releaseSerialOwnership(serial) {
-    const normalizedSerial = String(serial || '').trim();
-    if (!normalizedSerial) return;
-    withOwnershipLock(() => {
-      const owners = readOwnershipUnlocked();
-      const current = owners[normalizedSerial];
-      if (!current || current.ownerKey !== this.ownerKey) {
-        return;
-      }
+  // ── Status ────────────────────────────────────────────────────────────────
 
-      delete owners[normalizedSerial];
-      writeOwnershipUnlocked(owners);
-    });
-  }
+  getStatusSync() { return readState(this.userId); }
 
-  #claimSerial(serial) {
-    const normalizedSerial = String(serial || '').trim();
-    if (!normalizedSerial) {
-      throw new Error('Cannot claim an empty Android serial.');
-    }
+  async getStatus() {
+    const state = readState(this.userId);
+    const base = {
+      bootstrapped:  state.bootstrapped  || false,
+      starting:      state.starting      || false,
+      startupPhase:  state.startupPhase  || null,
+      lastStartError: state.lastStartError || null,
+      adbSerial:     state.adbSerial     || null,
+      devices:       [],
+    };
 
-    withOwnershipLock(() => {
-      const owners = readOwnershipUnlocked();
-      const existing = owners[normalizedSerial];
-      if (existing && existing.ownerKey && existing.ownerKey !== this.ownerKey) {
-        throw new Error(`Android device ${normalizedSerial} is currently reserved by another user.`);
-      }
+    if (!state.adbSerial) return base;
+    if (!this.#isPidAlive(state.pid)) return { ...base, bootstrapped: false };
 
-      owners[normalizedSerial] = {
-        ownerKey: this.ownerKey,
-        ownerUserId: this.userId,
-        updatedAt: new Date().toISOString(),
+    try {
+      const r = spawnSync(adbBin(this.sdkDir), ['-s', state.adbSerial, 'shell', 'getprop', 'sys.boot_completed'],
+        { encoding: 'utf8', timeout: 5000 });
+      const booted = r.stdout?.trim() === '1';
+      return {
+        ...base,
+        bootstrapped: booted,
+        devices: booted ? [{ serial: state.adbSerial, status: 'device', emulator: true }] : [],
       };
-      writeOwnershipUnlocked(owners);
-    });
-  }
-
-  #isSerialOwnedByAnother(serial, owners = null) {
-    const normalizedSerial = String(serial || '').trim();
-    if (!normalizedSerial) return false;
-    const effectiveOwners = owners || this.#readOwnership();
-    const existing = effectiveOwners[normalizedSerial];
-    return Boolean(existing?.ownerKey && existing.ownerKey !== this.ownerKey);
-  }
-
-  #assertSerialAccess(serial, options = {}) {
-    const normalizedSerial = String(serial || '').trim();
-    if (!normalizedSerial) {
-      throw new Error('Android serial is required.');
+    } catch {
+      return base;
     }
-
-    const claimIfUnowned = options.claimIfUnowned !== false;
-    withOwnershipLock(() => {
-      const owners = readOwnershipUnlocked();
-      const existing = owners[normalizedSerial];
-
-      if (existing?.ownerKey && existing.ownerKey !== this.ownerKey) {
-        throw new Error(`Android device ${normalizedSerial} is currently reserved by another user.`);
-      }
-
-      if (claimIfUnowned) {
-        owners[normalizedSerial] = {
-          ownerKey: this.ownerKey,
-          ownerUserId: this.userId,
-          updatedAt: new Date().toISOString(),
-        };
-        writeOwnershipUnlocked(owners);
-      }
-    });
-  }
-
-  #pruneOwnership(devices = []) {
-    withOwnershipLock(() => {
-      const owners = readOwnershipUnlocked();
-      const { next, changed } = pruneOwnershipByDevices(owners, devices);
-      if (changed) {
-        writeOwnershipUnlocked(next);
-      }
-    });
-  }
-
-  #registerProcessCleanup() {
-    AndroidController.cleanupControllers.add(this);
-    if (AndroidController.cleanupRegistered) {
-      return;
-    }
-    AndroidController.cleanupRegistered = true;
-
-    const cleanup = () => {
-      for (const controller of AndroidController.cleanupControllers) {
-        try {
-          controller.#stopTrackedEmulatorSync();
-        } catch {}
-      }
-    };
-
-    process.once('exit', cleanup);
-    process.once('uncaughtException', cleanup);
-    process.once('unhandledRejection', cleanup);
   }
 
-  #stopTrackedEmulatorSync() {
-    const state = this.#readState();
-    const serial = state.serial;
+  // ── Lifecycle ─────────────────────────────────────────────────────────────
 
-    if (serial && isExecutable(adbBinary())) {
-      try {
-        spawnSync(adbBinary(), ['-s', serial, 'emu', 'kill'], {
-          stdio: 'ignore',
-          env: sdkEnv(),
-        });
-      } catch {}
-    }
-
-    if (state.emulatorPid) {
-      try {
-        process.kill(state.emulatorPid, 0);
-        process.kill(state.emulatorPid, 'SIGTERM');
-      } catch {}
+  async requestStartEmulator() {
+    console.log(`[Android] requestStartEmulator for user ${this.userId}`);
+    const state = readState(this.userId);
+    if (state.adbSerial && this.#isPidAlive(state.pid)) {
+      console.log(`[Android] Emulator already running (pid=${state.pid})`);
+      return { success: true, pending: false, adbSerial: state.adbSerial };
     }
-
-    this.#releaseSerialOwnership(serial);
-    this.#appendState({ serial: null, emulatorPid: null });
-  }
-
-  async #run(command, options = {}) {
-    const result = await this.cli.execute(command, {
-      timeout: options.timeout || 120000,
-      env: sdkEnv(),
-      cwd: options.cwd || ANDROID_ROOT,
-    });
-    if (result.exitCode !== 0) {
-      throw new Error(result.stderr || result.stdout || `Command failed: ${command}`);
+    if (!this.startPromise) {
+      writeState(this.userId, { starting: true, startupPhase: 'Initializing', lastStartError: null });
+      this.startPromise = this.#setup().finally(() => { this.startPromise = null; });
+      this.startPromise.catch(() => {});
     }
-    return result.stdout || '';
+    const s = readState(this.userId);
+    return { success: true, pending: true, bootstrapped: false, starting: true, startupPhase: s.startupPhase };
   }
 
-  async #runAllowFailure(command, options = {}) {
-    return this.cli.execute(command, {
-      timeout: options.timeout || 120000,
-      env: sdkEnv(),
-      cwd: options.cwd || ANDROID_ROOT,
-    });
+  async stopEmulator() {
+    const state = readState(this.userId);
+    if (state.pid) { try { process.kill(Number(state.pid), 'SIGTERM'); } catch {} }
+    writeState(this.userId, { bootstrapped: false, starting: false, pid: null, adbSerial: null, startupPhase: null });
+    console.log('[Android] Emulator stopped');
   }
 
-  async ensureBootstrapped() {
-    const binariesReady =
-      isExecutable(adbBinary()) &&
-      isExecutable(sdkManagerBinary()) &&
-      isExecutable(emulatorBinary());
-
-    if (!binariesReady) {
-      if (this.bootstrapPromise) {
-        await this.bootstrapPromise;
-      } else {
-        this.bootstrapPromise = this.#bootstrapRuntime();
-        try {
-          await this.bootstrapPromise;
-        } finally {
-          this.bootstrapPromise = null;
-        }
-      }
-    }
-
-    const state = this.#readState();
-    if (!shouldForceSdkRefresh()) {
-      const installedImages = parseInstalledSystemImages();
-      if (installedImages.length > 0) {
-        const preferredInstalled =
-          chooseConfiguredSystemImage(installedImages) ||
-          chooseLatestSystemImage(installedImages);
-        if (!preferredInstalled) {
-          throw new Error(formatSystemImageError(installedImages));
-        }
-        const stateApiLevel = Number(state.apiLevel || 0) || 0;
-        const stateNeedsRefresh =
-          preferredInstalled.packageName !== state.systemImage ||
-          preferredInstalled.apiLevel !== stateApiLevel ||
-          preferredInstalled.arch !== state.systemImageArch;
-        if (stateNeedsRefresh) {
-          const changeSummary = describeAutoFixChanges(
-            {
-              systemImage: state.systemImage || null,
-              apiLevel: stateApiLevel || null,
-              systemImageArch: state.systemImageArch || null,
-            },
-            {
-              systemImage: preferredInstalled.packageName,
-              apiLevel: preferredInstalled.apiLevel,
-              systemImageArch: preferredInstalled.arch,
-            },
-            ['systemImage', 'apiLevel', 'systemImageArch']
-          );
-          if (changeSummary) {
-            console.log(`[Android] Auto-fixed preferred system image (${changeSummary})`);
-          }
-          this.#appendState({
-            bootstrapped: true,
-            systemImage: preferredInstalled.packageName,
-            apiLevel: preferredInstalled.apiLevel,
-            systemImageArch: preferredInstalled.arch,
-          });
-        }
-        return;
-      } else if (state.bootstrapped === true && state.systemImage) {
-        return;
-      }
-    }
+  async close() { await this.stopEmulator().catch(() => {}); }
 
-    this.#appendState({ bootstrapped: true });
-    const sdkmanager = sdkManagerBinary();
-    const available = await this.#run(`${quoteShell(sdkmanager)} --sdk_root=${quoteShell(SDK_ROOT)} --list`, { timeout: 300000 });
-    const latestSystemImage = chooseConfiguredSystemImage(available) || chooseLatestSystemImage(available);
-    if (!latestSystemImage) throw new Error(formatSystemImageError(available));
-
-    const refreshedState = this.#readState();
-    const currentApiLevel = parseApiLevelFromSystemImage(refreshedState.systemImage);
-    const shouldUpgrade =
-      refreshedState.systemImage !== latestSystemImage.packageName ||
-      currentApiLevel < latestSystemImage.apiLevel;
-
-    if (shouldUpgrade) {
-      await this.#run(`${quoteShell(sdkmanager)} --sdk_root=${quoteShell(SDK_ROOT)} "${latestSystemImage.packageName}"`, {
-        timeout: 300000,
-      });
-      this.#appendState({
-        bootstrapped: true,
-        systemImage: latestSystemImage.packageName,
-        apiLevel: latestSystemImage.apiLevel,
-        systemImageArch: latestSystemImage.arch,
-      });
+  async waitForDevice(options = {}) {
+    const deadline = Date.now() + (options.timeoutMs || 600000);
+    while (Date.now() < deadline) {
+      const s = await this.getStatus();
+      if (s.bootstrapped) return this.adbSerial;
+      await new Promise(r => setTimeout(r, 2000));
     }
+    throw new Error('Android emulator did not become ready in time');
   }
 
-  async #bootstrapRuntime() {
-    const metadata = await fetchText('https://dl.google.com/android/repository/repository2-1.xml');
-    const url = parseLatestCmdlineToolsUrl(metadata);
-    const zipPath = path.join(TMP_DIR, path.basename(url));
-    const extractDir = path.join(TMP_DIR, `cmdline-tools-${Date.now()}`);
-
-    fs.mkdirSync(extractDir, { recursive: true });
-    await downloadFile(url, zipPath);
-    extractZip(zipPath, extractDir);
-
-    const candidates = [
-      path.join(extractDir, 'cmdline-tools'),
-      path.join(extractDir, 'tools'),
-      extractDir,
-    ];
-    const extractedRoot = candidates.find((candidate) => fs.existsSync(path.join(candidate, 'bin')));
-    if (!extractedRoot) throw new Error('Downloaded Android command line tools archive did not contain a bin directory');
-
-    fs.rmSync(CMDLINE_LATEST, { recursive: true, force: true });
-    fs.mkdirSync(CMDLINE_ROOT, { recursive: true });
-    fs.cpSync(extractedRoot, CMDLINE_LATEST, { recursive: true });
-    fs.rmSync(zipPath, { force: true });
-    fs.rmSync(extractDir, { recursive: true, force: true });
-
-    const sdkmanager = sdkManagerBinary();
-    await this.#run(`yes | ${quoteShell(sdkmanager)} --sdk_root=${quoteShell(SDK_ROOT)} --licenses`, { timeout: 300000 });
-    await this.#run(`${quoteShell(sdkmanager)} --sdk_root=${quoteShell(SDK_ROOT)} "platform-tools" "emulator"`, { timeout: 300000 });
-
-    const available = await this.#run(`${quoteShell(sdkmanager)} --sdk_root=${quoteShell(SDK_ROOT)} --list`, { timeout: 300000 });
-    const systemImage = chooseConfiguredSystemImage(available) || chooseLatestSystemImage(available);
-    if (!systemImage) throw new Error(formatSystemImageError(available));
-
-    await this.#run(`${quoteShell(sdkmanager)} --sdk_root=${quoteShell(SDK_ROOT)} "${systemImage.packageName}"`, { timeout: 300000 });
-    this.#appendState({
-      bootstrapped: true,
-      systemImage: systemImage.packageName,
-      apiLevel: systemImage.apiLevel,
-      systemImageArch: systemImage.arch,
-    });
+  async listDevices() {
+    const s = await this.getStatus();
+    return s.bootstrapped ? [{ serial: this.adbSerial, status: 'device', emulator: true }] : [];
   }
 
-  async ensureAvd() {
-    await this.ensureBootstrapped();
-
-    const state = this.#readState();
-    const list = await this.#run(`${quoteShell(avdManagerBinary())} list avd`, { timeout: 120000 }).catch(() => '');
-    const pkg = state.systemImage;
-    if (!pkg) throw new Error('Android system image not installed');
-    const avdExists = list.includes(`Name: ${this.avdName}`);
-    let avdNeedsRecreate = avdExists && (!state.avdSystemImage || state.avdSystemImage !== pkg);
-    const avdRecreateReasons = [];
-    if (avdNeedsRecreate && state.avdSystemImage !== pkg) {
-      avdRecreateReasons.push(`systemImage: ${state.avdSystemImage || 'null'} -> ${pkg}`);
-    }
-    const configPath = path.join(AVD_HOME, `${this.avdName}.avd`, 'config.ini');
-    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);
-        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}`);
-        }
-      } catch {}
-    }
-
-    if (avdNeedsRecreate) {
-      if (avdRecreateReasons.length > 0) {
-        console.log(`[Android] Recreating AVD to repair config mismatch (${avdRecreateReasons.join(', ')})`);
-      }
-      await this.stopEmulator().catch(() => {});
-      await this.#run(`${quoteShell(avdManagerBinary())} delete avd -n ${quoteShell(this.avdName)}`, {
-        timeout: 120000,
-      }).catch(() => {});
-      fs.rmSync(path.join(AVD_HOME, `${this.avdName}.avd`), { recursive: true, force: true });
-      fs.rmSync(path.join(AVD_HOME, `${this.avdName}.ini`), { force: true });
-    } else if (avdExists) {
-      return;
-    }
-
-    await this.#run(`printf 'no\\n' | ${quoteShell(avdManagerBinary())} create avd -n ${quoteShell(this.avdName)} -k "${pkg}" --force`, {
-      timeout: 120000,
+  async ensureBootstrapped() {
+    const s = readState(this.userId);
+    if (!s.bootstrapped) await this.requestStartEmulator();
+  }
+
+  // ── Shell / ADB ───────────────────────────────────────────────────────────
+
+  async shell(commandOrObj) {
+    const command = typeof commandOrObj === 'string' ? commandOrObj : String(commandOrObj?.command || '');
+    const serial = this.#requireSerial();
+    const adb = adbBin(this.sdkDir);
+    return new Promise((resolve, reject) => {
+      const proc = spawn(adb, ['-s', serial, 'shell', command], { encoding: 'utf8' });
+      let out = '', err = '';
+      proc.stdout?.on('data', d => { out += d; });
+      proc.stderr?.on('data', d => { err += d; });
+      proc.on('close', code => code === 0 ? resolve(out) : reject(new Error(err || out || `exit ${code}`)));
+      proc.on('error', reject);
     });
-    this.#normalizeAvdConfig();
-    this.#appendState({ avdSystemImage: pkg });
-  }
-
-  #normalizeAvdConfig() {
-    const configPath = path.join(AVD_HOME, `${this.avdName}.avd`, 'config.ini');
-    if (!fs.existsSync(configPath)) return;
-
-    let content = fs.readFileSync(configPath, 'utf8');
-    content = updateIniValue(content, 'disk.dataPartition.size', DEFAULT_DATA_PARTITION);
-    content = updateIniValue(content, 'sdcard.size', DEFAULT_SDCARD_SIZE);
-    content = updateIniValue(content, 'hw.ramSize', DEFAULT_RAM_SIZE);
-    fs.writeFileSync(configPath, content);
-  }
-
-  async listDevices(options = {}) {
-    if (options.ensureBootstrapped !== false) {
-      await this.ensureBootstrapped();
-    }
-    if (!isExecutable(adbBinary())) {
-      return [];
-    }
-    const out = await this.#run(`${quoteShell(adbBinary())} devices -l`);
-    const lines = out.split('\n').map((line) => line.trim()).filter(Boolean);
-    const devices = lines
-      .filter((line) => !line.toLowerCase().startsWith('list of devices'))
-      .map((line) => {
-        const parts = line.split(/\s+/);
-        return {
-          serial: parts[0] || '',
-          status: parts[1] || 'unknown',
-          details: parts.slice(2).join(' '),
-          emulator: (parts[0] || '').startsWith('emulator-'),
-        };
-      });
-    this.#pruneOwnership(devices);
-    return devices;
-  }
-
-  async getPrimarySerial(options = {}) {
-    const state = this.#readState();
-    const devices = await this.listDevices(options);
-    const owners = this.#readOwnership();
-    const canUse = (device) => device.status === 'device' && !this.#isSerialOwnedByAnother(device.serial, owners);
-
-    const preferred = state.serial ? devices.find((device) => device.serial === state.serial && canUse(device)) : null;
-    if (preferred) {
-      this.#claimSerial(preferred.serial);
-      return preferred.serial;
-    }
-
-    const emulator = devices.find((device) => device.emulator && canUse(device));
-    if (emulator) {
-      this.#claimSerial(emulator.serial);
-      this.#appendState({ serial: emulator.serial });
-      return emulator.serial;
-    }
-
-    const online = devices.find((device) => canUse(device));
-    if (online) {
-      this.#claimSerial(online.serial);
-      this.#appendState({ serial: online.serial });
-      return online.serial;
-    }
-
-    return null;
   }
 
-  async #startEmulatorBlocking(options = {}) {
-    this.#appendState({
-      starting: true,
-      startupPhase: 'Preparing Android runtime',
-      lastStartError: null,
-      startRequestedAt: this.#readState().startRequestedAt || new Date().toISOString(),
-    });
-    console.log('[Android] Preparing emulator start');
-    await this.ensureAvd();
-    this.#appendState({
-      starting: true,
-      startupPhase: 'Checking for an existing Android device',
-      lastStartError: null,
-    });
-    this.#normalizeAvdConfig();
-    const serial = await this.getPrimarySerial();
-    if (serial) {
-      this.#appendState({
-        starting: false,
-        startupPhase: null,
-        serial,
-        lastStartError: null,
-        lastLogLine: 'Android device already running.',
-      });
-      return {
-        success: true,
-        serial,
-        reused: true,
-        bootstrapped: this.#readState().bootstrapped === true,
-      };
-    }
-
-    const logPath = path.join(LOGS_DIR, `emulator-${Date.now()}.log`);
-    const out = fs.openSync(logPath, 'a');
-    const args = [
-      `@${this.avdName}`,
-      '-no-boot-anim',
-      '-gpu',
-      process.platform === 'darwin' ? 'host' : 'swiftshader_indirect',
-      '-netdelay',
-      'none',
-      '-netspeed',
-      'full',
-    ];
-
-    if (options.headless !== false) {
-      args.push('-no-window', '-no-audio');
-    }
-
-    const child = spawn(emulatorBinary(), args, {
-      detached: true,
-      stdio: ['ignore', out, out],
-      env: sdkEnv(),
-    });
-
-    console.log(`[Android] Emulator process started (pid ${child.pid})`);
-    this.#appendState({
-      emulatorPid: child.pid,
-      avdName: this.avdName,
-      logPath,
-      starting: true,
-      startupPhase: 'Waiting for Android emulator to boot',
-      lastStartError: null,
-      lastLogLine: 'Android emulator process started. Waiting for boot completion...',
-    });
-
-    const processExit = new Promise((resolve) => {
-      child.once('exit', (code, signal) => {
-        resolve({ code, signal });
-      });
-      child.once('error', (error) => {
-        resolve({ code: null, signal: null, error });
-      });
-    });
-
-    child.unref();
-
-    const bootResult = await Promise.race([
-      this.waitForDevice({ timeoutMs: options.timeoutMs || 240000 }).then((serial) => ({
-        serial,
-        exited: false,
-      })),
-      processExit.then((result) => ({
-        exited: true,
-        ...result,
-      })),
-    ]);
-
-    if (bootResult.exited) {
-      const recentLogLines = tailFile(logPath, 12);
-      const lastLine =
-        bootResult.error?.message ||
-        recentLogLines[recentLogLines.length - 1] ||
-        `Emulator process exited before boot completed (code ${bootResult.code ?? 'unknown'}, signal ${bootResult.signal ?? 'none'}).`;
-      throw new Error(lastLine);
-    }
-
-    const onlineSerial = bootResult.serial;
-    this.#appendState({
-      serial: onlineSerial,
-      emulatorPid: child.pid,
-      starting: false,
-      startupPhase: null,
-      lastStartError: null,
-      lastLogLine: 'Android emulator boot completed.',
+  async adb(...args) {
+    const state = readState(this.userId);
+    const adb = adbBin(this.sdkDir);
+    return new Promise((resolve, reject) => {
+      const proc = spawn(adb, ['-s', state.adbSerial || this.adbSerial, ...args], { encoding: 'utf8' });
+      let out = '', err = '';
+      proc.stdout?.on('data', d => { out += d; });
+      proc.stderr?.on('data', d => { err += d; });
+      proc.on('close', code => code === 0 ? resolve(out) : reject(new Error(err || `adb ${args[0]} exit ${code}`)));
+      proc.on('error', reject);
     });
-    console.log(`[Android] Emulator ready on ${onlineSerial}`);
-
-    return {
-      success: true,
-      serial: onlineSerial,
-      emulatorPid: child.pid,
-      logPath,
-    };
   }
 
-  async startEmulator(options = {}) {
-    if (this.startPromise) {
-      await this.startPromise;
-      const serial = await this.getPrimarySerial();
-      if (!serial) {
-        throw new Error(this.#readState().lastStartError || 'Android emulator did not finish starting.');
-      }
-      return {
-        success: true,
-        serial,
-        reused: false,
-        bootstrapped: this.#readState().bootstrapped === true,
-      };
-    }
+  // ── Actions ───────────────────────────────────────────────────────────────
 
-    return this.#startEmulatorBlocking(options);
+  async screenshot(_opts = {}) {
+    const serial = this.#requireSerial();
+    const r = this.#adbCapture(serial, ['exec-out', 'screencap', '-p']);
+    if (!r?.length) throw new Error('screencap returned no data');
+    return { screenshotPath: this.#saveArtifact(r) };
   }
 
-  async requestStartEmulator(options = {}) {
-    const serial = await this.getPrimarySerial({ ensureBootstrapped: false }).catch(() => null);
-    if (serial) {
-      this.#appendState({
-        starting: false,
-        startupPhase: null,
-        serial,
-        lastStartError: null,
-        lastLogLine: 'Android device already running.',
-      });
-      return {
-        success: true,
-        pending: false,
-        serial,
-        reused: true,
-        bootstrapped: this.#readState().bootstrapped === true,
-      };
-    }
-
-    if (!this.startPromise) {
-      const requestedAt = new Date().toISOString();
-      this.#appendState({
-        starting: true,
-        startupPhase: 'Preparing Android runtime',
-        lastStartError: null,
-        startRequestedAt: requestedAt,
-        lastLogLine: 'Android start requested.',
-      });
-      const startPromise = this.#startEmulatorBlocking(options).catch((err) => {
-        const state = this.#readState();
-        const recentLogLines = state.logPath ? tailFile(state.logPath, 12) : [];
-        const detailedMessage = recentLogLines[recentLogLines.length - 1] || err.message;
-        this.#appendState({
-          starting: false,
-          startupPhase: 'Start failed',
-          lastStartError: detailedMessage,
-          lastLogLine: detailedMessage,
-        });
-        console.error('[Android] Emulator start failed:', detailedMessage);
-        throw new Error(detailedMessage);
-      }).finally(() => {
-        if (this.startPromise === startPromise) {
-          this.startPromise = null;
-        }
-      });
-      this.startPromise = startPromise;
-      startPromise.catch(() => {});
-    }
+  async observe(_opts = {}) { return this.screenshot(); }
 
-    const state = this.#readState();
-    return {
-      success: true,
-      pending: true,
-      bootstrapped: state.bootstrapped === true,
-      starting: true,
-      startupPhase: state.startupPhase || 'Preparing Android runtime',
-      startRequestedAt: state.startRequestedAt || null,
-      logPath: state.logPath || null,
-    };
+  async tap({ x, y } = {}) {
+    await this.shell(`input tap ${Math.round(x)} ${Math.round(y)}`);
+    return { success: true, screenshotPath: this.#saveArtifact(this.#adbCapture(this.#requireSerial(), ['exec-out', 'screencap', '-p'])) };
   }
 
-  async waitForDevice(options = {}) {
-    const timeoutMs = Math.max(10000, Number(options.timeoutMs) || 180000);
-    const deadline = Date.now() + timeoutMs;
-
-    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') {
-          return serial;
-        }
-      }
-      await sleep(3000);
-    }
-
-    throw new Error(`Android emulator did not finish booting within ${timeoutMs} ms`);
-  }
-
-  async ensureDevice() {
-    const serial = await this.getPrimarySerial();
-    if (serial) {
-      this.#assertSerialAccess(serial, { claimIfUnowned: true });
-      return serial;
-    }
-    const started = await this.startEmulator();
-    this.#assertSerialAccess(started.serial, { claimIfUnowned: true });
-    return started.serial;
-  }
-
-  async stopEmulator() {
-    const state = this.#readState();
-    const serial = await this.getPrimarySerial();
-    if (serial) {
-      this.#assertSerialAccess(serial, { claimIfUnowned: true });
-      await this.#runAllowFailure(`${quoteShell(adbBinary())} -s ${quoteShell(serial)} emu kill`, { timeout: 15000 });
-    }
-    if (state.emulatorPid) {
-      try { process.kill(state.emulatorPid, 'SIGTERM'); } catch {}
-    }
-    this.#releaseSerialOwnership(serial);
-    this.#releaseSerialOwnership(state.serial);
-    this.#appendState({
-      serial: null,
-      emulatorPid: null,
-      starting: false,
-      startupPhase: null,
-      lastStartError: null,
-      lastLogLine: 'Android emulator stopped.',
-    });
-
-    const deadline = Date.now() + 30000;
-    while (Date.now() < deadline) {
-      const devices = await this.listDevices().catch(() => []);
-      const stillPresent = devices.some((device) => device.emulator && device.status === 'device');
-      let pidAlive = false;
-      if (state.emulatorPid) {
-        try {
-          process.kill(state.emulatorPid, 0);
-          pidAlive = true;
-        } catch {
-          pidAlive = false;
-        }
-      }
-      if (!stillPresent && !pidAlive) break;
-      await sleep(1000);
-    }
-
+  async longPress({ x, y, durationMs = 1000 } = {}) {
+    await this.shell(`input swipe ${Math.round(x)} ${Math.round(y)} ${Math.round(x)} ${Math.round(y)} ${durationMs}`);
     return { success: true };
   }
 
-  async #adb(serial, command, options = {}) {
-    this.#assertSerialAccess(serial, { claimIfUnowned: true });
-    return this.#run(`${quoteShell(adbBinary())} -s ${quoteShell(serial)} ${command}`, options);
+  async swipe({ x1, y1, x2, y2, durationMs = 300 } = {}) {
+    await this.shell(`input swipe ${Math.round(x1)} ${Math.round(y1)} ${Math.round(x2)} ${Math.round(y2)} ${durationMs}`);
+    return { success: true, screenshotPath: this.#saveArtifact(this.#adbCapture(this.#requireSerial(), ['exec-out', 'screencap', '-p'])) };
   }
 
-  async screenshot(options = {}) {
-    const serial = options.serial || await this.ensureDevice();
-    let artifactRecord = null;
-    let filename = `android_${Date.now()}.png`;
-    let fullPath = path.join(SCREENSHOTS_DIR, filename);
-    if (this.artifactStore && this.userId != null) {
-      artifactRecord = this.artifactStore.allocateFile(this.userId, {
-        kind: 'android-screenshot',
-        backend: this.runtimeBackend,
-        extension: 'png',
-        contentType: 'image/png',
-        filenameBase: 'android-screenshot',
-        metadata: {
-          serial,
-        },
-      });
-      fullPath = artifactRecord.storagePath;
-      filename = path.basename(fullPath);
-    }
-    await this.#adb(serial, `exec-out screencap -p > ${quoteShell(fullPath)}`, { timeout: 30000 });
-    if (artifactRecord) {
-      this.artifactStore.finalizeFile(artifactRecord.artifactId, fullPath);
-    }
-    return {
-      success: true,
-      serial,
-      screenshotPath: artifactRecord ? artifactRecord.url : `/screenshots/${filename}`,
-      artifactId: artifactRecord?.artifactId || null,
-      fullPath,
-    };
+  async type({ text, pressEnter } = {}) {
+    if (!text) return { success: true };
+    // ADB input text encoding: %% = literal %, %s = space.
+    const encoded = String(text).replace(/%/g, '%%').replace(/ /g, '%s');
+    await this.shell(`input text '${shellEscape(encoded)}'`);
+    if (pressEnter) await this.shell('input keyevent KEYCODE_ENTER');
+    return { success: true };
   }
 
-  async dumpUi(options = {}) {
-    const serial = options.serial || await this.ensureDevice();
-    let xml = await this.#adb(serial, 'shell uiautomator dump --compressed /dev/tty', { timeout: 30000 });
-    if (!String(xml || '').includes('<hierarchy')) {
-      const remote = '/sdcard/neoagent-ui.xml';
-      await this.#adb(serial, `shell uiautomator dump --compressed ${quoteShell(remote)}`, { timeout: 30000 });
-      xml = await this.#adb(serial, `shell cat ${quoteShell(remote)}`, { timeout: 30000 });
-    }
-    xml = sanitizeUiXml(xml);
-    let artifactRecord = null;
-    let filename = `android_ui_${Date.now()}.xml`;
-    let fullPath = path.join(UI_DUMPS_DIR, filename);
-    if (this.artifactStore && this.userId != null) {
-      artifactRecord = this.artifactStore.allocateFile(this.userId, {
-        kind: 'android-ui-dump',
-        backend: this.runtimeBackend,
-        extension: 'xml',
-        contentType: 'application/xml',
-        filenameBase: 'android-ui',
-        metadata: {
-          serial,
-        },
-      });
-      fullPath = artifactRecord.storagePath;
-      filename = path.basename(fullPath);
-    }
-    fs.writeFileSync(fullPath, xml);
-    if (artifactRecord) {
-      this.artifactStore.finalizeFile(artifactRecord.artifactId, fullPath);
-    }
-
-    const nodes = parseUiDump(xml);
-    return {
-      success: true,
-      serial,
-      nodeCount: nodes.length,
-      uiDumpPath: artifactRecord ? artifactRecord.url : fullPath,
-      uiDumpArtifactId: artifactRecord?.artifactId || null,
-      preview: options.includeNodes === false ? undefined : nodes.slice(0, 25).map((node) => summarizeNode(node)),
-      xml,
+  async pressKey(keyOrObj) {
+    const raw = typeof keyOrObj === 'string' ? keyOrObj : (keyOrObj?.key || '');
+    const KEY_MAP = {
+      back: 'KEYCODE_BACK', home: 'KEYCODE_HOME', app_switch: 'KEYCODE_APP_SWITCH',
+      enter: 'KEYCODE_ENTER', del: 'KEYCODE_DEL', escape: 'KEYCODE_ESCAPE',
+      menu: 'KEYCODE_MENU', power: 'KEYCODE_POWER',
+      volume_up: 'KEYCODE_VOLUME_UP', volume_down: 'KEYCODE_VOLUME_DOWN',
     };
+    const keycode = KEY_MAP[raw.toLowerCase()] || raw.toUpperCase();
+    await this.shell(`input keyevent ${keycode}`);
+    return { success: true };
   }
 
-  async #captureObservation(serial, options = {}) {
-    const resolvedSerial = serial || await this.ensureDevice();
-    const observation = {
-      serial: resolvedSerial,
-      screenshotPath: null,
-      fullPath: null,
-      uiDumpPath: null,
-      nodeCount: null,
-      preview: undefined,
-      observationWarnings: [],
-    };
-
-    if (options.screenshot !== false) {
-      try {
-        const shot = await this.screenshot({ serial: resolvedSerial });
-        observation.screenshotPath = shot?.screenshotPath || null;
-        observation.fullPath = shot?.fullPath || null;
-      } catch (err) {
-        observation.observationWarnings.push(`screenshot: ${err.message}`);
-      }
-    }
-
-    if (options.uiDump !== false) {
-      try {
-        const dump = await this.dumpUi({
-          serial: resolvedSerial,
-          includeNodes: options.includeNodes !== false,
-        });
-        observation.uiDumpPath = dump.uiDumpPath;
-        observation.nodeCount = dump.nodeCount;
-        observation.preview = dump.preview;
-      } catch (err) {
-        observation.observationWarnings.push(`ui_dump: ${err.message}`);
-      }
-    }
-
-    if (observation.observationWarnings.length === 0) {
-      delete observation.observationWarnings;
-    }
-
-    return observation;
+  async dumpUi(_opts = {}) {
+    const serial = this.#requireSerial();
+    await this.shell('uiautomator dump /sdcard/window_dump.xml');
+    const r = spawnSync(adbBin(this.sdkDir), ['-s', serial, 'shell', 'cat', '/sdcard/window_dump.xml'], { encoding: 'utf8', timeout: 10000 });
+    return { xml: r.stdout || '' };
   }
 
-  async observe(options = {}) {
-    const serial = options.serial || await this.ensureDevice();
-    const observation = await this.#captureObservation(serial, options);
-    if (!observation.screenshotPath && !observation.uiDumpPath) {
-      throw new Error(
-        Array.isArray(observation.observationWarnings) && observation.observationWarnings.length > 0
-          ? observation.observationWarnings.join(' | ')
-          : 'Unable to capture Android observation',
-      );
-    }
-    return {
-      success: true,
-      ...observation,
-    };
+  async listApps({ includeSystem = false } = {}) {
+    const out = await this.shell(includeSystem ? 'pm list packages' : 'pm list packages -3');
+    const packages = out.trim().split('\n').filter(Boolean).map(l => l.replace('package:', '').trim());
+    return { packages };
   }
 
-  async #resolveSelector(args = {}) {
-    const dump = await this.dumpUi({ includeNodes: false });
-    const selector = {
-      text: args.text,
-      resourceId: args.resourceId,
-      description: args.description,
-      className: args.className,
-      packageName: args.packageName,
-      clickable: args.clickable,
-    };
-    const node = findBestNode(dump.xml, selector);
-    if (!node) throw new Error('No Android UI element matched the selector');
-    return {
-      serial: dump.serial,
-      uiDumpPath: dump.uiDumpPath,
-      node,
-    };
+  async openApp({ packageName } = {}) {
+    if (!isSafeIdentifier(packageName)) throw new Error('Invalid package name');
+    await this.shell(`monkey -p '${shellEscape(packageName)}' -c android.intent.category.LAUNCHER 1`);
+    await new Promise(r => setTimeout(r, 1500));
+    return this.screenshot();
   }
 
-  async tap(args = {}) {
-    let x = Number(args.x);
-    let y = Number(args.y);
-    let node = null;
-    let serial = await this.ensureDevice();
-    let resolvedFromUiDumpPath = null;
-
-    if (!Number.isFinite(x) || !Number.isFinite(y)) {
-      const resolved = await this.#resolveSelector(args);
-      serial = resolved.serial;
-      node = resolved.node;
-      resolvedFromUiDumpPath = resolved.uiDumpPath;
-      x = node.bounds.centerX;
-      y = node.bounds.centerY;
+  async openIntent({ action, dataUri, extras = {} } = {}) {
+    const safeAction = isSafeIdentifier(action) ? action : 'android.intent.action.VIEW';
+    let cmd = `am start -a '${shellEscape(safeAction)}'`;
+    if (dataUri) cmd += ` -d '${shellEscape(dataUri)}'`;
+    for (const [k, v] of Object.entries(extras || {})) {
+      if (isSafeIdentifier(k)) cmd += ` --es '${shellEscape(k)}' '${shellEscape(v)}'`;
     }
-
-    await this.#adb(serial, `shell input tap ${Math.round(x)} ${Math.round(y)}`, { timeout: 15000 });
-    const observation = await this.#captureObservation(serial, args);
-    return {
-      success: true,
-      serial,
-      x: Math.round(x),
-      y: Math.round(y),
-      target: summarizeNode(node),
-      resolvedFromUiDumpPath,
-      ...observation,
-    };
+    await this.shell(cmd);
+    await new Promise(r => setTimeout(r, 2000));
+    return this.screenshot();
   }
 
-  async longPress(args = {}) {
-    let x = Number(args.x);
-    let y = Number(args.y);
-    let node = null;
-    let serial = await this.ensureDevice();
-    let resolvedFromUiDumpPath = null;
-
-    if (!Number.isFinite(x) || !Number.isFinite(y)) {
-      const resolved = await this.#resolveSelector(args);
-      serial = resolved.serial;
-      node = resolved.node;
-      resolvedFromUiDumpPath = resolved.uiDumpPath;
-      x = node.bounds.centerX;
-      y = node.bounds.centerY;
-    }
-
-    const durationMs = Math.max(250, Number(args.durationMs) || 650);
-    await this.#adb(
-      serial,
-      `shell input swipe ${Math.round(x)} ${Math.round(y)} ${Math.round(x)} ${Math.round(y)} ${Math.round(durationMs)}`,
-      { timeout: Math.max(15000, durationMs + 5000) },
-    );
-    const observation = await this.#captureObservation(serial, args);
-    return {
-      success: true,
-      serial,
-      x: Math.round(x),
-      y: Math.round(y),
-      durationMs,
-      target: summarizeNode(node),
-      resolvedFromUiDumpPath,
-      ...observation,
-    };
+  async waitFor({ timeout = 10000 } = {}) {
+    const deadline = Date.now() + timeout;
+    while (Date.now() < deadline) {
+      const s = await this.getStatus();
+      if (s.bootstrapped) return { ready: true };
+      await new Promise(r => setTimeout(r, 1000));
+    }
+    return { ready: false };
+  }
+
+  async installApk({ apkPath } = {}) {
+    if (!apkPath) throw new Error('apkPath required');
+    const serial = this.#requireSerial();
+    const adb = adbBin(this.sdkDir);
+    return new Promise((resolve, reject) => {
+      const proc = spawn(adb, ['-s', serial, 'install', '-r', apkPath]);
+      let out = '', err = '';
+      proc.stdout?.on('data', d => { out += d; });
+      proc.stderr?.on('data', d => { err += d; });
+      proc.on('close', code => {
+        if (code === 0 && out.includes('Success')) resolve({ success: true, output: out });
+        else reject(new Error(err || out || `adb install exit ${code}`));
+      });
+      proc.on('error', reject);
+    });
   }
 
-  async type(args = {}) {
-    const serial = await this.ensureDevice();
-    if (args.clear === true) {
-      await this.#adb(serial, 'shell input keyevent 123', { timeout: 10000 }).catch(() => {});
-      await this.#adb(serial, 'shell input keyevent 67', { timeout: 10000 }).catch(() => {});
-    }
+  // ── Private helpers ───────────────────────────────────────────────────────
 
-    if (args.selector || args.textSelector || args.resourceId || args.description) {
-      await this.tap({
-        text: args.textSelector,
-        resourceId: args.resourceId,
-        description: args.description,
-        className: args.className,
-        clickable: true,
-        screenshot: false,
-        uiDump: false,
-      }).catch(() => {});
-    }
+  #requireSerial() {
+    const state = readState(this.userId);
+    if (!state.adbSerial) throw new Error('No emulator running');
+    return state.adbSerial;
+  }
 
-    await this.#adb(serial, `shell input text ${quoteShell(androidTextEscape(args.text || ''))}`, { timeout: 20000 });
-    if (args.pressEnter) {
-      await this.#adb(serial, 'shell input keyevent 66', { timeout: 10000 });
-    }
-    const observation = await this.#captureObservation(serial, args);
-    return {
-      success: true,
-      serial,
-      typed: args.text || '',
-      ...observation,
-    };
+  #isPidAlive(pid) {
+    if (!pid || !Number.isInteger(Number(pid))) return false;
+    try { process.kill(Number(pid), 0); return true; } catch { return false; }
   }
 
-  async swipe(args = {}) {
-    const serial = await this.ensureDevice();
-    const x1 = Number(args.x1);
-    const y1 = Number(args.y1);
-    const x2 = Number(args.x2);
-    const y2 = Number(args.y2);
-    const duration = Math.max(50, Number(args.durationMs) || 300);
-    if (![x1, y1, x2, y2].every(Number.isFinite)) {
-      throw new Error('x1, y1, x2, and y2 are required for android_swipe');
-    }
-    await this.#adb(serial, `shell input swipe ${Math.round(x1)} ${Math.round(y1)} ${Math.round(x2)} ${Math.round(y2)} ${Math.round(duration)}`, { timeout: 15000 });
-    const observation = await this.#captureObservation(serial, args);
-    return {
-      success: true,
-      serial,
-      ...observation,
-    };
+  #adbCapture(serial, args) {
+    const r = spawnSync(adbBin(this.sdkDir), ['-s', serial, ...args], { maxBuffer: 20 * 1024 * 1024, timeout: 15000 });
+    return (r.status === 0 && r.stdout?.length) ? r.stdout : null;
   }
 
-  async pressKey(args = {}) {
-    const serial = await this.ensureDevice();
-    const raw = String(args.key || '').trim().toLowerCase();
-    const keyCode = Number.isFinite(Number(raw)) ? Number(raw) : (DEFAULT_KEYEVENTS[raw] || null);
-    if (!keyCode) throw new Error(`Unsupported Android key: ${args.key}`);
-    await this.#adb(serial, `shell input keyevent ${keyCode}`, { timeout: 10000 });
-    const observation = await this.#captureObservation(serial, args);
-    return {
-      success: true,
-      serial,
-      key: args.key,
-      keyCode,
-      ...observation,
-    };
+  #saveArtifact(data) {
+    if (!data || !this.artifactStore) return null;
+    const alloc = this.artifactStore.allocateFile(this.userId, { kind: 'screenshot', extension: 'png', contentType: 'image/png' });
+    fs.writeFileSync(alloc.storagePath, data);
+    const fin = this.artifactStore.finalizeFile(alloc.artifactId, alloc.storagePath);
+    return fin.url;
   }
 
-  async waitFor(args = {}) {
-    const timeoutMs = Math.max(1000, Number(args.timeoutMs) || 20000);
-    const intervalMs = Math.max(250, Number(args.intervalMs) || 1500);
-    const deadline = Date.now() + timeoutMs;
+  // ── Setup pipeline ────────────────────────────────────────────────────────
 
-    while (Date.now() < deadline) {
-      const dump = await this.dumpUi({ includeNodes: false });
-      const node = findBestNode(dump.xml, {
-        text: args.text,
-        resourceId: args.resourceId,
-        description: args.description,
-        className: args.className,
-        packageName: args.packageName,
-        clickable: args.clickable,
+  async #resolveAdbPort() {
+    const base = (hashCode(this.userId) >>> 0) % ADB_PORT_SLOTS;
+    for (let i = 0; i < ADB_PORT_SLOTS; i++) {
+      const slot = (base + i) % ADB_PORT_SLOTS;
+      const port = ADB_PORT_BASE + slot * 2;
+      const free = await new Promise(resolve => {
+        const srv = net.createServer();
+        srv.listen(port, '127.0.0.1', () => srv.close(() => resolve(true)));
+        srv.on('error', () => resolve(false));
       });
-      if (node) {
-        const observation = await this.#captureObservation(dump.serial, {
-          screenshot: args.screenshot !== false,
-          uiDump: args.uiDump !== false,
-          includeNodes: args.includeNodes,
-        });
-        return {
-          success: true,
-          serial: dump.serial,
-          matched: summarizeNode(node),
-          matchedFromUiDumpPath: dump.uiDumpPath,
-          ...observation,
-        };
+      if (free) {
+        this.adbPort   = port;
+        this.adbSerial = `emulator-${port}`;
+        return;
       }
-      await sleep(intervalMs);
     }
-
-    throw new Error(`Timed out after ${timeoutMs} ms waiting for Android UI element`);
+    throw new Error(`No free ADB port in range ${ADB_PORT_BASE}–${ADB_PORT_BASE + ADB_PORT_SLOTS * 2}`);
   }
 
-  async openApp(args = {}) {
-    const serial = await this.ensureDevice();
-    if (args.activity) {
-      await this.#adb(serial, `shell am start -n ${quoteShell(`${args.packageName}/${args.activity}`)}`, { timeout: 20000 });
-    } else if (args.packageName) {
-      this.#assertSerialAccess(serial, { claimIfUnowned: true });
-      const resolved = await this.#runAllowFailure(
-        `${quoteShell(adbBinary())} -s ${quoteShell(serial)} shell cmd package resolve-activity --brief -c android.intent.category.LAUNCHER ${quoteShell(args.packageName)}`,
-        { timeout: 15000 },
-      );
-      const component = parseResolvedLaunchComponent(
-        `${resolved.stdout || ''}\n${resolved.stderr || ''}`,
-        args.packageName,
-      );
-
-      if (component) {
-        await this.#adb(serial, `shell am start -n ${quoteShell(component)}`, { timeout: 20000 });
+  async #setup() {
+    const progress = msg => {
+      console.log(`[Android] ${msg}`);
+      writeState(this.userId, { startupPhase: msg });
+    };
+    try {
+      await this.#resolveAdbPort();
+      const existing = findExistingSdk();
+      if (existing) {
+        this.sdkDir = existing;
+        progress(`Found existing Android SDK at ${existing}`);
       } else {
-        await this.#adb(serial, `shell monkey -p ${quoteShell(args.packageName)} -c android.intent.category.LAUNCHER 1`, { timeout: 30000 });
+        progress('Downloading Android SDK…');
+        await ensureSdk(this.sdkDir, progress);
+        await ensurePackages(this.sdkDir, progress);
       }
-    } else {
-      throw new Error('packageName is required for android_open_app');
+      ensureAvd(this.sdkDir, this.avdName, progress);
+      await this.#startEmulatorProcess(progress);
+    } catch (err) {
+      console.error(`[Android] Setup failed: ${err.message}`);
+      writeState(this.userId, { starting: false, startupPhase: 'Failed', lastStartError: err.message });
     }
-    const observation = await this.#captureObservation(serial, args);
-    return {
-      success: true,
-      serial,
-      packageName: args.packageName,
-      activity: args.activity || null,
-      ...observation,
-    };
   }
 
-  async openIntent(args = {}) {
-    const serial = await this.ensureDevice();
-    const parts = ['shell am start'];
-    if (args.action) parts.push('-a', quoteShell(args.action));
-    if (args.dataUri) parts.push('-d', quoteShell(args.dataUri));
-    if (args.packageName) parts.push('-p', quoteShell(args.packageName));
-    if (args.component) parts.push('-n', quoteShell(args.component));
-    if (args.mimeType) parts.push('-t', quoteShell(args.mimeType));
-
-    if (args.extras && typeof args.extras === 'object') {
-      for (const [key, value] of Object.entries(args.extras)) {
-        parts.push('--es', quoteShell(key), quoteShell(String(value)));
-      }
-    }
+  async #startEmulatorProcess(progress) {
+    progress('Starting Android emulator…');
+    const env = { ...process.env, ANDROID_SDK_ROOT: this.sdkDir, ANDROID_HOME: this.sdkDir };
+    const proc = spawn(emulatorBin(this.sdkDir), [
+      '-avd', this.avdName,
+      '-no-window', '-no-audio', '-no-boot-anim',
+      '-port', String(this.adbPort),
+      '-gpu', 'swiftshader_indirect',
+      '-partition-size', '800',
+    ], { env, detached: false, stdio: ['ignore', 'pipe', 'pipe'] });
 
-    await this.#adb(serial, parts.join(' '), { timeout: 20000 });
-    const observation = await this.#captureObservation(serial, args);
-    return {
-      success: true,
-      serial,
-      ...observation,
-    };
-  }
+    proc.stdout.on('data', d => console.log(`[Android/emu] ${d.toString().trimEnd()}`));
+    proc.stderr.on('data', d => console.log(`[Android/emu] ${d.toString().trimEnd()}`));
+    writeState(this.userId, { pid: proc.pid, adbSerial: this.adbSerial });
 
-  async listApps(args = {}) {
-    const serial = await this.ensureDevice();
-    const cmd = args.includeSystem === true ? 'shell pm list packages' : 'shell pm list packages -3';
-    const out = await this.#adb(serial, cmd, { timeout: 30000 });
-    const packages = out
-      .split('\n')
-      .map((line) => line.trim())
-      .filter(Boolean)
-      .map((line) => line.replace(/^package:/, ''))
-      .sort();
-    return {
-      success: true,
-      serial,
-      count: packages.length,
-      packages,
-    };
-  }
+    proc.on('exit', code => {
+      console.log(`[Android] Emulator exited with code ${code}`);
+      writeState(this.userId, { bootstrapped: false, starting: false, pid: null });
+    });
 
-  async installApk(args = {}) {
-    const apkPath = path.resolve(String(args.apkPath || ''));
-    if (!apkPath || !fs.existsSync(apkPath)) throw new Error(`APK not found: ${apkPath}`);
-    const serial = await this.ensureDevice();
-    const extension = path.extname(apkPath).toLowerCase();
+    progress('Waiting for Android to boot (can take 2–5 min on first run)…');
+    await this.#waitForBoot();
 
-    if (extension === '.aab') {
-      throw new Error('.aab app bundles are not directly installable. Export a .apks bundle or .apk first.');
-    }
+    writeState(this.userId, { bootstrapped: true, starting: false, startupPhase: null, lastStartError: null });
+    console.log(`[Android] Emulator ready on ${this.adbSerial}`);
+
+    // Set wallpaper — best-effort, never fails the boot sequence.
+    this.#setWallpaper(this.adbSerial).catch(err => {
+      console.warn(`[Android] Wallpaper not set: ${err.message}`);
+    });
+  }
 
-    if (extension === '.apks') {
-      const extractDir = fs.mkdtempSync(path.join(TMP_DIR, 'apk-bundle-'));
+  async #waitForBoot(timeoutMs = 10 * 60 * 1000) {
+    const adb = adbBin(this.sdkDir);
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
       try {
-        extractZip(apkPath, extractDir);
-        const bundle = resolveBundleInstallTargets(extractDir);
-        await this.#adb(serial, `install -r ${quoteShell(bundle.installPaths[0])}`, { timeout: 300000 });
-        return {
-          success: true,
-          serial,
-          apkPath,
-          artifactType: 'apks',
-          installedPaths: bundle.installPaths,
-          bundleLayout: bundle.layout,
-        };
-      } finally {
-        fs.rmSync(extractDir, { recursive: true, force: true });
-      }
+        const r = spawnSync(adb, ['-s', this.adbSerial, 'shell', 'getprop', 'sys.boot_completed'], { encoding: 'utf8', timeout: 5000 });
+        if (r.stdout?.trim() === '1') return;
+      } catch {}
+      await new Promise(r => setTimeout(r, 3000));
     }
-
-    await this.#adb(serial, `install -r ${quoteShell(apkPath)}`, { timeout: 300000 });
-    return {
-      success: true,
-      serial,
-      apkPath,
-      artifactType: 'apk',
-      installedPaths: [apkPath],
-    };
+    throw new Error('Emulator did not boot within timeout');
   }
 
-  async shell(args = {}) {
-    const serial = await this.ensureDevice();
-    const command = String(args.command || '').trim();
-    if (!command) throw new Error('command is required for android_shell');
-
-    const timeout = Math.max(1000, Number(args.timeoutMs) || 20000);
-    const stdout = await this.#adb(serial, `shell ${quoteShell(command)}`, { timeout });
-    const observation = args.screenshot === true
-      ? await this.#captureObservation(serial)
-      : null;
-    return {
-      success: true,
-      serial,
-      command,
-      stdout,
-      screenshotPath: observation?.screenshotPath || null,
-      fullPath: observation?.fullPath || null,
-      uiDumpPath: observation?.uiDumpPath || null,
-      nodeCount: observation?.nodeCount,
-      preview: observation?.preview,
-    };
-  }
+  async #setWallpaper(serial) {
+    if (!fs.existsSync(LOGO_PATH)) return;
+    const adb = adbBin(this.sdkDir);
 
-  async getStatus() {
-    const devices = isExecutable(adbBinary())
-      ? await this.listDevices({ ensureBootstrapped: false }).catch(() => [])
-      : [];
-    const state = this.#readState();
-    const serialInState = String(state.serial || '').trim();
-    const serialOwnedByCurrentUser = serialInState
-      ? !this.#isSerialOwnedByAnother(serialInState)
-      : null;
-    let lastLogLine =
-      state.lastStartError ||
-      state.lastLogLine ||
-      state.startupPhase ||
-      null;
-    if (state.logPath && fs.existsSync(state.logPath)) {
-      try {
-        const lines = fs.readFileSync(state.logPath, 'utf8')
-          .split('\n')
-          .map((line) => line.trim())
-          .filter(Boolean);
-        const emulatorLogLine = [...lines].reverse().find((line) =>
-          /fatal|error|warning|boot completed|disk space|running avd/i.test(line)
-        ) || lines[lines.length - 1] || null;
-        lastLogLine = emulatorLogLine || lastLogLine;
-      } catch {
-        lastLogLine =
-          state.lastStartError ||
-          state.lastLogLine ||
-          state.startupPhase ||
-          null;
-      }
+    // Try to gain root access (works on AOSP default images).
+    spawnSync(adb, ['-s', serial, 'root'], { timeout: 5000 });
+    await new Promise(r => setTimeout(r, 1500));
+
+    // Push PNG to device sdcard.
+    const push = spawnSync(adb, ['-s', serial, 'push', LOGO_PATH, '/sdcard/neoagent-wallpaper.png'], { timeout: 15000 });
+    if (push.status !== 0) throw new Error('adb push logo failed');
+
+    // cmd wallpaper set-stream reads PNG from stdin (Android 7.1+).
+    const logoData = fs.readFileSync(LOGO_PATH);
+    const r = spawnSync(adb, ['-s', serial, 'shell', 'cmd', 'wallpaper', 'set-stream'], {
+      input: logoData, timeout: 15000,
+    });
+    if (r.status === 0) {
+      console.log('[Android] Wallpaper set');
+      return;
     }
-    return {
-      bootstrapped: state.bootstrapped === true,
-      starting: state.starting === true || this.startPromise != null,
-      startupPhase: state.startupPhase || null,
-      startRequestedAt: state.startRequestedAt || null,
-      lastStartError: state.lastStartError || null,
-      sdkRoot: SDK_ROOT,
-      avdHome: AVD_HOME,
-      avdName: this.avdName,
-      adbPath: adbBinary(),
-      emulatorPath: emulatorBinary(),
-      serial: state.serial,
-      serialOwnedByCurrentUser,
-      emulatorPid: state.emulatorPid,
-      systemImage: state.systemImage || null,
-      systemImageArch: state.systemImageArch || null,
-      preferredSystemImageArchs: systemImageArchCandidates(),
-      configuredSystemImagePackage: configuredSystemImagePackage(),
-      configuredSystemImagePlatform: configuredSystemImagePlatform(),
-      apiLevel: Number(state.apiLevel || 0) || null,
-      avdSystemImage: state.avdSystemImage || null,
-      logPath: state.logPath || null,
-      lastLogLine,
-      devices,
-      canBootstrap: process.platform === 'darwin' || process.platform === 'linux',
-    };
-  }
 
-  async close() {
-    AndroidController.cleanupControllers.delete(this);
-    return this.stopEmulator().catch(() => {});
+    // Fallback: direct file copy for rooted images (Android 11 AOSP).
+    spawnSync(adb, ['-s', serial, 'shell', 'cp /sdcard/neoagent-wallpaper.png /data/system/users/0/wallpaper'], { timeout: 5000 });
+    spawnSync(adb, ['-s', serial, 'shell', 'chmod 600 /data/system/users/0/wallpaper'], { timeout: 5000 });
+    spawnSync(adb, ['-s', serial, 'shell', 'chown system:system /data/system/users/0/wallpaper'], { timeout: 5000 });
+    spawnSync(adb, ['-s', serial, 'shell', 'am broadcast -a android.intent.action.WALLPAPER_CHANGED'], { timeout: 5000 });
+    console.log('[Android] Wallpaper set via direct copy');
   }
 }
 
-module.exports = {
-  AndroidController,
-  androidTextEscape,
-  chooseConfiguredSystemImage,
-  chooseLatestSystemImage,
-  configuredSystemImagePackage,
-  configuredSystemImagePlatform,
-  formatSystemImageError,
-  parseResolvedLaunchComponent,
-  parseLatestCmdlineToolsUrl,
-  parseSystemImages,
-  sanitizeUiXml,
-  systemImageArchCandidates,
-};
+module.exports = { AndroidController };