@yoqa/runner 0.3.17 → 0.3.18

package/dist/index.js

@@ -16801,7 +16801,7 @@ function getCatalogDb() {
 // package.json
 var package_default = {
   name: "@yoqa/runner",
-  version: "0.3.17",
+  version: "0.3.18",
   description: "Yoqa local runner \u2014 Appium + catalog HTTP API (Bun). Start with yoqa serve or the yoqa-runner bin.",
   license: "UNLICENSED",
   type: "module",
@@ -16896,207 +16896,666 @@ function abortAllMjpegProxies() {
 import { mkdir as mkdir3 } from "fs/promises";
 import { createServer as createServer2 } from "net";
 import { homedir as homedir6 } from "os";
-import { join as join6 } from "path";
+import { join as join7 } from "path";
 import { remote } from "webdriverio";
-var YOQA_ROOT4 = join6(homedir6(), ".yoqa");
-var DEFAULT_MJPEG_PORT = Number(process.env.YOQA_MJPEG_PORT ?? "9100");
-var SCREENSHOT_DIR = join6(YOQA_ROOT4, "runs", "screenshots");
-var MJPEG_SETTINGS_BASE = {
-  mjpegServerScreenshotQuality: 35,
-  mjpegScalingFactor: 50
-};
-var openByDeviceId = new Map;
-var exclusiveReleaseListener = null;
-function onDeviceSessionExclusiveRelease(listener) {
-  exclusiveReleaseListener = listener;
-}
-var DEAD_SESSION_RE = /session does not exist|invalid session id|no such session|terminated or not started|session is either terminated/i;
 
-class DeadSessionError extends Error {
-  constructor(message = "Device session ended") {
-    super(message);
-    this.name = "DeadSessionError";
-  }
-}
-function isDeadSessionError(error) {
-  if (error instanceof DeadSessionError)
-    return true;
-  const message = error instanceof Error ? error.message : String(error);
-  return DEAD_SESSION_RE.test(message);
-}
-function mjpegSettingsForDevice(options) {
-  const physicalIos = options.platform === "ios" && looksLikePhysicalIosUdid(options.deviceId);
-  if (physicalIos) {
+// src/domains/devices/application.ts
+import { mkdtemp as mkdtemp2, readFile, rm as rm2 } from "fs/promises";
+import { tmpdir as tmpdir2 } from "os";
+import { join as join6 } from "path";
+
+// src/domains/devices/android-identity.ts
+function matchAndroidAppiumIdentity(deviceId, connected, knownAvds = []) {
+  const id = deviceId.trim();
+  if (!id)
+    return {};
+  const bySerial = connected.find((device) => device.serial === id);
+  if (bySerial) {
     return {
-      mjpegServerFramerate: 15,
-      mjpegServerScreenshotQuality: 25,
-      mjpegScalingFactor: 40
+      udid: bySerial.serial,
+      ...bySerial.avdName ? { avd: bySerial.avdName } : {}
     };
   }
-  return {
-    ...MJPEG_SETTINGS_BASE,
-    mjpegServerFramerate: 60
-  };
+  const byAvd = connected.find((device) => device.avdName === id);
+  if (byAvd) {
+    return { udid: byAvd.serial, avd: byAvd.avdName ?? id };
+  }
+  if (knownAvds.includes(id)) {
+    return { avd: id };
+  }
+  return { udid: id };
 }
-function isPortFree2(port) {
-  return new Promise((resolve) => {
-    const server = createServer2();
-    server.unref();
-    server.once("error", () => resolve(false));
-    server.listen(port, APPIUM_HOST, () => {
-      server.close(() => resolve(true));
+function parseAdbEmuAvdName(stdout) {
+  const name = stdout.split(/\r?\n/).map((line) => line.trim()).find((line) => line && line !== "OK");
+  return name || null;
+}
+
+// src/domains/devices/application.ts
+async function runCommand3(command, options) {
+  try {
+    const proc = Bun.spawn(command, {
+      env: options?.env ? { ...process.env, ...options.env } : process.env,
+      stdout: "pipe",
+      stderr: "pipe"
     });
-  });
+    const [stdout, stderr, exitCode] = await Promise.all([
+      new Response(proc.stdout).text(),
+      new Response(proc.stderr).text(),
+      proc.exited
+    ]);
+    return { stdout, stderr, exitCode };
+  } catch {
+    return { stdout: "", stderr: `failed to spawn: ${command[0]}`, exitCode: 127 };
+  }
 }
-async function pickMjpegPort() {
-  if (await isPortFree2(DEFAULT_MJPEG_PORT))
-    return DEFAULT_MJPEG_PORT;
-  for (let offset = 1;offset <= 40; offset++) {
-    const candidate = DEFAULT_MJPEG_PORT + offset;
-    if (await isPortFree2(candidate))
+function androidSdkRoot() {
+  return resolveAndroidSdkRoot();
+}
+async function resolveTool(candidates) {
+  for (const candidate of candidates) {
+    if (!candidate)
+      continue;
+    const { exitCode } = await runCommand3(["test", "-x", candidate]);
+    if (exitCode === 0)
       return candidate;
   }
-  throw new Error(`No free MJPEG port near ${DEFAULT_MJPEG_PORT}. Quit other streams or set YOQA_MJPEG_PORT.`);
+  return null;
 }
-function mjpegUpstreamUrl(mjpegPort) {
-  return `http://127.0.0.1:${mjpegPort}/`;
+async function resolveAdb() {
+  const sdk = androidSdkRoot();
+  return resolveTool([...sdk ? [join6(sdk, "platform-tools/adb")] : [], "adb"]);
 }
-async function probeMjpegStream(mjpegPort, timeoutMs = 4000) {
-  const deadline = Date.now() + timeoutMs;
-  while (Date.now() < deadline) {
-    const controller = new AbortController;
-    const timer = setTimeout(() => controller.abort(), 800);
-    try {
-      const response = await fetch(mjpegUpstreamUrl(mjpegPort), {
-        signal: controller.signal,
-        headers: { Accept: "multipart/x-mixed-replace,image/jpeg,*/*" }
-      });
-      if (response.ok) {
-        controller.abort();
-        return true;
-      }
-    } catch {} finally {
-      clearTimeout(timer);
-    }
-    await Bun.sleep(250);
-  }
-  return false;
+async function resolveEmulator() {
+  const sdk = androidSdkRoot();
+  return resolveTool([...sdk ? [join6(sdk, "emulator/emulator")] : [], "emulator"]);
 }
-async function applyMjpegSettings(browser, options) {
-  try {
-    await browser.updateSettings(mjpegSettingsForDevice(options));
-  } catch (error) {
-    console.warn("[yoqa-runner] MJPEG settings update failed:", error instanceof Error ? error.message : error);
-  }
+function formatIosVersion(version2) {
+  const trimmed = version2.trim();
+  if (!trimmed)
+    return "iOS";
+  if (/^iOS\b/i.test(trimmed))
+    return trimmed;
+  return `iOS ${trimmed}`;
 }
-async function releaseExistingSession(deviceId) {
-  const existing = openByDeviceId.get(deviceId);
-  if (!existing)
-    return;
-  openByDeviceId.delete(deviceId);
-  exclusiveReleaseListener?.(deviceId);
+function formatAndroidVersion(apiOrVersion) {
+  const trimmed = apiOrVersion.trim();
+  if (!trimmed)
+    return "Android";
+  if (/^Android\b/i.test(trimmed))
+    return trimmed;
+  if (/^API\b/i.test(trimmed))
+    return trimmed;
+  if (/^\d+(\.\d+)?$/.test(trimmed))
+    return `API ${trimmed}`;
+  return `Android ${trimmed}`;
+}
+function titleCaseWords(value) {
+  return value.split(/\s+/).filter(Boolean).map((word) => {
+    if (/^[a-z]$/i.test(word))
+      return word.toUpperCase();
+    if (/^\d/.test(word))
+      return word;
+    return word.charAt(0).toUpperCase() + word.slice(1).toLowerCase();
+  }).join(" ");
+}
+function runtimeVersionFromIdentifier(runtimeId) {
+  const match = runtimeId.match(/iOS-([\d-]+)$/i);
+  if (!match?.[1])
+    return "iOS";
+  return formatIosVersion(match[1].replace(/-/g, "."));
+}
+async function listIosSimulators(includeUnavailable) {
+  const { stdout, exitCode } = await runCommand3([
+    "xcrun",
+    "simctl",
+    "list",
+    "devices",
+    "available",
+    "-j"
+  ]);
+  if (exitCode !== 0)
+    return [];
+  let parsed;
   try {
-    await existing.quit();
-  } catch (error) {
-    console.warn("[yoqa-runner] quit prior Device Session for exclusivity:", error instanceof Error ? error.message : error);
+    parsed = JSON.parse(stdout);
+  } catch {
+    return [];
   }
-}
-function capabilitiesToRecord(caps) {
-  const out = {};
-  for (const cap of caps) {
-    const key = cap.key.trim();
-    if (!key)
+  const devices = [];
+  for (const [runtimeId, runtimeDevices] of Object.entries(parsed.devices ?? {})) {
+    if (!/iOS/i.test(runtimeId))
       continue;
-    out[key] = cap.value;
+    const osVersion = runtimeVersionFromIdentifier(runtimeId);
+    for (const device of runtimeDevices) {
+      if (!device.udid || !device.name)
+        continue;
+      if (device.isAvailable === false)
+        continue;
+      const state = device.state ?? "Unknown";
+      if (!includeUnavailable && state !== "Booted")
+        continue;
+      devices.push({
+        id: device.udid,
+        name: device.name,
+        osVersion,
+        platform: "ios",
+        kind: "simulator",
+        state,
+        model: device.deviceTypeIdentifier?.split(".").pop()?.replace(/-/g, " ")
+      });
+    }
   }
-  return out;
-}
-function mergeCapabilities(appCaps, caseCaps) {
-  return {
-    ...capabilitiesToRecord(appCaps),
-    ...capabilitiesToRecord(caseCaps)
-  };
+  return devices.sort((a, b) => {
+    if (a.state === "Booted" && b.state !== "Booted")
+      return -1;
+    if (b.state === "Booted" && a.state !== "Booted")
+      return 1;
+    return a.name.localeCompare(b.name);
+  });
 }
-function looksLikePhysicalIosUdid(udid) {
-  return /^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{16}$/.test(udid.trim());
+function isPhoneOrTablet(deviceType) {
+  if (!deviceType)
+    return false;
+  return /^(iPhone|iPad)$/i.test(deviceType);
 }
-var PHYSICAL_IOS_SESSION_TIMEOUT_MS = 60000;
-var SIMULATOR_WDA_SESSION_TIMEOUT_MS = 600000;
-var SIMULATOR_WDA_DERIVED_DATA = join6(YOQA_ROOT4, "wda-sim");
-function iosSessionCreateTimeoutMs(deviceId) {
-  return looksLikePhysicalIosUdid(deviceId) ? PHYSICAL_IOS_SESSION_TIMEOUT_MS : SIMULATOR_WDA_SESSION_TIMEOUT_MS;
+function physicalIosState(connection) {
+  const tunnel = connection?.tunnelState?.toLowerCase() ?? "";
+  if (tunnel.includes("connected"))
+    return "connected";
+  if (tunnel.includes("unavailable"))
+    return "unavailable";
+  if (tunnel.includes("disconnected"))
+    return "disconnected";
+  if (connection?.pairingState === "paired")
+    return "paired";
+  return tunnel || connection?.pairingState || "unknown";
 }
-async function buildW3cCapabilities(options, mjpegPort) {
-  const merged = mergeCapabilities(options.appCaps, options.caseCaps);
-  const platformName = options.platform === "ios" ? "iOS" : "Android";
-  const automationName = options.platform === "ios" ? "XCUITest" : "UiAutomator2";
-  const caps = {
-    platformName,
-    "appium:automationName": automationName,
-    "appium:udid": options.deviceId,
-    "appium:newCommandTimeout": 3600,
-    "appium:mjpegServerPort": mjpegPort,
-    ...Object.fromEntries(Object.entries(merged).map(([key, value]) => key.includes(":") ? [key, value] : [`appium:${key}`, value]))
-  };
-  if (options.platform === "ios" && options.bundleId && !caps["appium:bundleId"]) {
-    caps["appium:bundleId"] = options.bundleId;
-  }
-  if (options.platform === "android" && options.appPackage && !caps["appium:appPackage"]) {
-    caps["appium:appPackage"] = options.appPackage;
-  }
-  if (options.platform === "ios") {
-    const physical = looksLikePhysicalIosUdid(options.deviceId);
-    if (physical) {
-      const prep = await loadDevicePrep(options.deviceId);
-      if (!prep) {
-        throw new Error(`iOS device ${options.deviceId} is not prepared. Run device setup so WebDriverAgent is installed before starting a run.`);
-      }
-      if (caps["appium:usePreinstalledWDA"] === undefined) {
-        caps["appium:usePreinstalledWDA"] = true;
-      }
-      if (!caps["appium:updatedWDABundleId"]) {
-        caps["appium:updatedWDABundleId"] = prep.bundleId;
-      }
-      if (!caps["appium:xcodeOrgId"]) {
-        caps["appium:xcodeOrgId"] = prep.developmentTeam;
-      }
-      if (!caps["appium:xcodeSigningId"]) {
-        caps["appium:xcodeSigningId"] = "Apple Development";
-      }
-    }
-    const wdaTimeoutMs = iosSessionCreateTimeoutMs(options.deviceId);
-    if (caps["appium:wdaLaunchTimeout"] === undefined) {
-      caps["appium:wdaLaunchTimeout"] = wdaTimeoutMs;
+async function listIosPhysicalDevices(includeUnavailable) {
+  const dir = await mkdtemp2(join6(tmpdir2(), "yoqa-devices-"));
+  const jsonPath = join6(dir, "devices.json");
+  try {
+    const { exitCode } = await runCommand3([
+      "xcrun",
+      "devicectl",
+      "list",
+      "devices",
+      "--json-output",
+      jsonPath
+    ]);
+    if (exitCode !== 0)
+      return [];
+    let parsed;
+    try {
+      parsed = JSON.parse(await readFile(jsonPath, "utf8"));
+    } catch {
+      return [];
     }
-    if (caps["appium:wdaConnectionTimeout"] === undefined) {
-      caps["appium:wdaConnectionTimeout"] = wdaTimeoutMs;
+    const devices = [];
+    for (const item of parsed.result?.devices ?? []) {
+      const hardware = item.hardwareProperties;
+      const props = item.deviceProperties;
+      if (!hardware?.udid)
+        continue;
+      if (hardware.reality && hardware.reality !== "physical")
+        continue;
+      if (!isPhoneOrTablet(hardware.deviceType))
+        continue;
+      if (hardware.platform && !/^iOS$/i.test(hardware.platform))
+        continue;
+      const state = physicalIosState(item.connectionProperties);
+      if (!includeUnavailable && state === "unavailable")
+        continue;
+      const modelName = hardware.marketingName ?? hardware.productType ?? "iPhone";
+      const owner = props?.name?.trim() || undefined;
+      devices.push({
+        id: hardware.udid,
+        name: modelName,
+        owner,
+        osVersion: formatIosVersion(props?.osVersionNumber ?? ""),
+        platform: "ios",
+        kind: "physical",
+        state,
+        model: hardware.productType
+      });
     }
-    if (caps["appium:waitForIdleTimeout"] === undefined) {
-      caps["appium:waitForIdleTimeout"] = 0;
+    return devices.sort((a, b) => a.name.localeCompare(b.name));
+  } finally {
+    await rm2(dir, { recursive: true, force: true });
+  }
+}
+async function listIosDevices(options = {}) {
+  const includeUnavailable = options.includeUnavailable ?? true;
+  const [physical, simulators] = await Promise.all([
+    listIosPhysicalDevices(includeUnavailable),
+    listIosSimulators(includeUnavailable)
+  ]);
+  return [...physical, ...simulators];
+}
+function parseAdbDevices(output) {
+  const lines = output.split(`
+`).map((line) => line.trim()).filter(Boolean);
+  const results = [];
+  for (const line of lines) {
+    if (line.startsWith("List of devices"))
+      continue;
+    const parts = line.split(/\s+/);
+    const serial = parts[0];
+    const state = parts[1];
+    if (!serial || !state)
+      continue;
+    const meta = {};
+    for (const part of parts.slice(2)) {
+      const eq2 = part.indexOf(":");
+      if (eq2 <= 0)
+        continue;
+      meta[part.slice(0, eq2)] = part.slice(eq2 + 1);
     }
-    if (!physical && caps["appium:derivedDataPath"] === undefined) {
-      await mkdir3(SIMULATOR_WDA_DERIVED_DATA, { recursive: true });
-      caps["appium:derivedDataPath"] = SIMULATOR_WDA_DERIVED_DATA;
+    results.push({
+      serial,
+      state,
+      product: meta.product,
+      model: meta.model,
+      device: meta.device,
+      transportId: meta.transport_id
+    });
+  }
+  return results;
+}
+function humanizeAvdName(avdName) {
+  return titleCaseWords(avdName.replace(/_/g, " "));
+}
+function humanizeModel(model) {
+  if (!model)
+    return;
+  return titleCaseWords(model.replace(/_/g, " "));
+}
+async function findAvdConfigPath(avdName) {
+  const home = process.env.HOME ?? "";
+  const roots = [join6(home, ".android/avd"), join6(home, "Library/Android/sdk/.android/avd")];
+  for (const root of roots) {
+    const direct = join6(root, `${avdName}.avd`, "config.ini");
+    try {
+      await readFile(direct, "utf8");
+      return direct;
+    } catch {}
+    try {
+      const glob = new Bun.Glob("*.avd/config.ini");
+      for await (const match of glob.scan({ cwd: root, onlyFiles: true })) {
+        const path = join6(root, match);
+        const text2 = await readFile(path, "utf8");
+        const idLine = text2.split(`
+`).find((line) => line.startsWith("AvdId="));
+        const id = idLine?.slice("AvdId=".length).trim();
+        if (id === avdName)
+          return path;
+      }
+    } catch {}
+  }
+  return null;
+}
+async function readAvdConfig(avdName) {
+  const path = await findAvdConfigPath(avdName);
+  if (!path)
+    return { api: null, deviceName: null };
+  try {
+    const text2 = await readFile(path, "utf8");
+    const imageLine = text2.split(`
+`).find((line) => line.includes("system-images") && line.includes("android-"));
+    const apiMatch = imageLine?.match(/android-([\d.]+)/);
+    const deviceLine = text2.split(`
+`).find((entry) => entry.startsWith("hw.device.name="));
+    const deviceRaw = deviceLine?.slice("hw.device.name=".length).trim();
+    return {
+      api: apiMatch?.[1] ?? null,
+      deviceName: humanizeModel(deviceRaw) ?? null
+    };
+  } catch {
+    return { api: null, deviceName: null };
+  }
+}
+async function adbAvdName(adb, serial) {
+  const fromProp = await adbGetProp(adb, serial, "ro.boot.qemu.avd_name") ?? await adbGetProp(adb, serial, "ro.kernel.qemu.avd_name");
+  if (fromProp)
+    return fromProp;
+  const { stdout, exitCode } = await runCommand3([adb, "-s", serial, "emu", "avd", "name"]);
+  if (exitCode !== 0)
+    return null;
+  return parseAdbEmuAvdName(stdout);
+}
+async function adbGetProp(adb, serial, prop) {
+  const { stdout, exitCode } = await runCommand3([adb, "-s", serial, "shell", "getprop", prop]);
+  if (exitCode !== 0)
+    return null;
+  const value = stdout.trim();
+  return value || null;
+}
+async function listAndroidAdbDevices(adb) {
+  const { stdout, exitCode } = await runCommand3([adb, "devices", "-l"]);
+  if (exitCode !== 0) {
+    return { physical: [], runningEmulators: [], runningAvdNames: new Set };
+  }
+  const entries = parseAdbDevices(stdout);
+  const physical = [];
+  const runningEmulators = [];
+  const runningAvdNames = new Set;
+  for (const entry of entries) {
+    const isEmulator = entry.serial.startsWith("emulator-") || entry.product === "sdk_gphone";
+    if (isEmulator) {
+      const avdName = await adbAvdName(adb, entry.serial);
+      if (avdName)
+        runningAvdNames.add(avdName);
+      const avdConfig = avdName ? await readAvdConfig(avdName) : null;
+      const release2 = await adbGetProp(adb, entry.serial, "ro.build.version.release") ?? avdConfig?.api ?? null;
+      const model2 = humanizeModel(entry.model) ?? avdConfig?.deviceName ?? (avdName ? humanizeAvdName(avdName) : entry.serial);
+      runningEmulators.push({
+        id: avdName ?? entry.serial,
+        name: model2,
+        osVersion: formatAndroidVersion(release2 ?? ""),
+        platform: "android",
+        kind: "emulator",
+        state: entry.state === "device" ? "online" : entry.state,
+        model: avdName ?? entry.model
+      });
+      continue;
     }
+    const release = await adbGetProp(adb, entry.serial, "ro.build.version.release");
+    const model = humanizeModel(entry.model) ?? await adbGetProp(adb, entry.serial, "ro.product.model") ?? entry.serial;
+    physical.push({
+      id: entry.serial,
+      name: model,
+      osVersion: formatAndroidVersion(release ?? ""),
+      platform: "android",
+      kind: "physical",
+      state: entry.state,
+      model: entry.model
+    });
   }
-  return caps;
+  return { physical, runningEmulators, runningAvdNames };
 }
-
-class ActionGate {
-  locked = false;
-  gesture = null;
-  deferredTap = null;
-  isPointerActive() {
-    return this.gesture != null || this.deferredTap != null;
+async function listAndroidAvds(emulatorBin, runningAvdNames, includeUnavailable) {
+  const { stdout, exitCode } = await runCommand3([emulatorBin, "-list-avds"]);
+  if (exitCode !== 0)
+    return [];
+  const names = stdout.split(`
+`).map((line) => line.trim()).filter(Boolean);
+  const devices = [];
+  for (const avdName of names) {
+    const isRunning = runningAvdNames.has(avdName);
+    if (!includeUnavailable && !isRunning)
+      continue;
+    if (isRunning)
+      continue;
+    const { api, deviceName } = await readAvdConfig(avdName);
+    devices.push({
+      id: avdName,
+      name: deviceName ?? humanizeAvdName(avdName),
+      osVersion: formatAndroidVersion(api ?? ""),
+      platform: "android",
+      kind: "emulator",
+      state: "offline",
+      model: avdName
+    });
   }
-  async withLock(fn) {
-    if (this.gesture || this.deferredTap) {
-      throw new Error("Device is busy with live pointer control");
+  return devices;
+}
+async function resolveAndroidAppiumIdentity(deviceId) {
+  const [adb, emulatorBin] = await Promise.all([resolveAdb(), resolveEmulator()]);
+  const connected = [];
+  if (adb) {
+    const { stdout, exitCode } = await runCommand3([adb, "devices", "-l"]);
+    if (exitCode === 0) {
+      for (const entry of parseAdbDevices(stdout)) {
+        const isEmulator = entry.serial.startsWith("emulator-") || entry.product === "sdk_gphone";
+        connected.push({
+          serial: entry.serial,
+          avdName: isEmulator ? await adbAvdName(adb, entry.serial) : null
+        });
+      }
     }
-    if (this.locked) {
-      throw new Error("Device is busy with another action");
+  }
+  const knownAvds = [];
+  if (emulatorBin) {
+    const { stdout, exitCode } = await runCommand3([emulatorBin, "-list-avds"]);
+    if (exitCode === 0) {
+      knownAvds.push(...stdout.split(`
+`).map((line) => line.trim()).filter(Boolean));
     }
-    this.locked = true;
+  }
+  return matchAndroidAppiumIdentity(deviceId, connected, knownAvds);
+}
+async function listAndroidDevices(options = {}) {
+  const includeUnavailable = options.includeUnavailable ?? true;
+  const [adb, emulatorBin] = await Promise.all([resolveAdb(), resolveEmulator()]);
+  const adbResult = adb ? await listAndroidAdbDevices(adb) : { physical: [], runningEmulators: [], runningAvdNames: new Set };
+  const offlineAvds = emulatorBin != null ? await listAndroidAvds(emulatorBin, adbResult.runningAvdNames, includeUnavailable) : [];
+  const physical = includeUnavailable ? adbResult.physical : adbResult.physical.filter((device) => device.state === "device");
+  const emulators = [...adbResult.runningEmulators, ...offlineAvds].sort((a, b) => {
+    const aOnline = a.state === "online" ? 0 : 1;
+    const bOnline = b.state === "online" ? 0 : 1;
+    if (aOnline !== bOnline)
+      return aOnline - bOnline;
+    return a.name.localeCompare(b.name);
+  });
+  return [...physical, ...emulators];
+}
+async function listDevices(platform, options = {}) {
+  if (platform === "ios")
+    return listIosDevices(options);
+  return listAndroidDevices(options);
+}
+
+// src/domains/devices/session.ts
+var YOQA_ROOT4 = join7(homedir6(), ".yoqa");
+var DEFAULT_MJPEG_PORT = Number(process.env.YOQA_MJPEG_PORT ?? "9100");
+var SCREENSHOT_DIR = join7(YOQA_ROOT4, "runs", "screenshots");
+var MJPEG_SETTINGS_BASE = {
+  mjpegServerScreenshotQuality: 35,
+  mjpegScalingFactor: 50
+};
+var openByDeviceId = new Map;
+var exclusiveReleaseListener = null;
+function onDeviceSessionExclusiveRelease(listener) {
+  exclusiveReleaseListener = listener;
+}
+var DEAD_SESSION_RE = /session does not exist|invalid session id|no such session|terminated or not started|session is either terminated/i;
+
+class DeadSessionError extends Error {
+  constructor(message = "Device session ended") {
+    super(message);
+    this.name = "DeadSessionError";
+  }
+}
+function isDeadSessionError(error) {
+  if (error instanceof DeadSessionError)
+    return true;
+  const message = error instanceof Error ? error.message : String(error);
+  return DEAD_SESSION_RE.test(message);
+}
+function mjpegSettingsForDevice(options) {
+  const physicalIos = options.platform === "ios" && looksLikePhysicalIosUdid(options.deviceId);
+  if (physicalIos) {
+    return {
+      mjpegServerFramerate: 15,
+      mjpegServerScreenshotQuality: 25,
+      mjpegScalingFactor: 40
+    };
+  }
+  return {
+    ...MJPEG_SETTINGS_BASE,
+    mjpegServerFramerate: 60
+  };
+}
+function isPortFree2(port) {
+  return new Promise((resolve) => {
+    const server = createServer2();
+    server.unref();
+    server.once("error", () => resolve(false));
+    server.listen(port, APPIUM_HOST, () => {
+      server.close(() => resolve(true));
+    });
+  });
+}
+async function pickMjpegPort() {
+  if (await isPortFree2(DEFAULT_MJPEG_PORT))
+    return DEFAULT_MJPEG_PORT;
+  for (let offset = 1;offset <= 40; offset++) {
+    const candidate = DEFAULT_MJPEG_PORT + offset;
+    if (await isPortFree2(candidate))
+      return candidate;
+  }
+  throw new Error(`No free MJPEG port near ${DEFAULT_MJPEG_PORT}. Quit other streams or set YOQA_MJPEG_PORT.`);
+}
+function mjpegUpstreamUrl(mjpegPort) {
+  return `http://127.0.0.1:${mjpegPort}/`;
+}
+async function probeMjpegStream(mjpegPort, timeoutMs = 4000) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const controller = new AbortController;
+    const timer = setTimeout(() => controller.abort(), 800);
+    try {
+      const response = await fetch(mjpegUpstreamUrl(mjpegPort), {
+        signal: controller.signal,
+        headers: { Accept: "multipart/x-mixed-replace,image/jpeg,*/*" }
+      });
+      if (response.ok) {
+        controller.abort();
+        return true;
+      }
+    } catch {} finally {
+      clearTimeout(timer);
+    }
+    await Bun.sleep(250);
+  }
+  return false;
+}
+async function applyMjpegSettings(browser, options) {
+  try {
+    await browser.updateSettings(mjpegSettingsForDevice(options));
+  } catch (error) {
+    console.warn("[yoqa-runner] MJPEG settings update failed:", error instanceof Error ? error.message : error);
+  }
+}
+async function releaseExistingSession(deviceId) {
+  const existing = openByDeviceId.get(deviceId);
+  if (!existing)
+    return;
+  openByDeviceId.delete(deviceId);
+  exclusiveReleaseListener?.(deviceId);
+  try {
+    await existing.quit();
+  } catch (error) {
+    console.warn("[yoqa-runner] quit prior Device Session for exclusivity:", error instanceof Error ? error.message : error);
+  }
+}
+function capabilitiesToRecord(caps) {
+  const out = {};
+  for (const cap of caps) {
+    const key = cap.key.trim();
+    if (!key)
+      continue;
+    out[key] = cap.value;
+  }
+  return out;
+}
+function mergeCapabilities(appCaps, caseCaps) {
+  return {
+    ...capabilitiesToRecord(appCaps),
+    ...capabilitiesToRecord(caseCaps)
+  };
+}
+function looksLikePhysicalIosUdid(udid) {
+  return /^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{16}$/.test(udid.trim());
+}
+var PHYSICAL_IOS_SESSION_TIMEOUT_MS = 60000;
+var SIMULATOR_WDA_SESSION_TIMEOUT_MS = 600000;
+var SIMULATOR_WDA_DERIVED_DATA = join7(YOQA_ROOT4, "wda-sim");
+function iosSessionCreateTimeoutMs(deviceId) {
+  return looksLikePhysicalIosUdid(deviceId) ? PHYSICAL_IOS_SESSION_TIMEOUT_MS : SIMULATOR_WDA_SESSION_TIMEOUT_MS;
+}
+async function buildW3cCapabilities(options, mjpegPort) {
+  const merged = mergeCapabilities(options.appCaps, options.caseCaps);
+  const platformName = options.platform === "ios" ? "iOS" : "Android";
+  const automationName = options.platform === "ios" ? "XCUITest" : "UiAutomator2";
+  const caps = {
+    platformName,
+    "appium:automationName": automationName,
+    "appium:newCommandTimeout": 3600,
+    "appium:mjpegServerPort": mjpegPort,
+    ...Object.fromEntries(Object.entries(merged).map(([key, value]) => key.includes(":") ? [key, value] : [`appium:${key}`, value]))
+  };
+  if (options.platform === "ios") {
+    if (caps["appium:udid"] === undefined) {
+      caps["appium:udid"] = options.deviceId;
+    }
+    if (options.bundleId && !caps["appium:bundleId"]) {
+      caps["appium:bundleId"] = options.bundleId;
+    }
+    const physical = looksLikePhysicalIosUdid(options.deviceId);
+    if (physical) {
+      const prep = await loadDevicePrep(options.deviceId);
+      if (!prep) {
+        throw new Error(`iOS device ${options.deviceId} is not prepared. Run device setup so WebDriverAgent is installed before starting a run.`);
+      }
+      if (caps["appium:usePreinstalledWDA"] === undefined) {
+        caps["appium:usePreinstalledWDA"] = true;
+      }
+      if (!caps["appium:updatedWDABundleId"]) {
+        caps["appium:updatedWDABundleId"] = prep.bundleId;
+      }
+      if (!caps["appium:xcodeOrgId"]) {
+        caps["appium:xcodeOrgId"] = prep.developmentTeam;
+      }
+      if (!caps["appium:xcodeSigningId"]) {
+        caps["appium:xcodeSigningId"] = "Apple Development";
+      }
+    }
+    const wdaTimeoutMs = iosSessionCreateTimeoutMs(options.deviceId);
+    if (caps["appium:wdaLaunchTimeout"] === undefined) {
+      caps["appium:wdaLaunchTimeout"] = wdaTimeoutMs;
+    }
+    if (caps["appium:wdaConnectionTimeout"] === undefined) {
+      caps["appium:wdaConnectionTimeout"] = wdaTimeoutMs;
+    }
+    if (caps["appium:waitForIdleTimeout"] === undefined) {
+      caps["appium:waitForIdleTimeout"] = 0;
+    }
+    if (!physical && caps["appium:derivedDataPath"] === undefined) {
+      await mkdir3(SIMULATOR_WDA_DERIVED_DATA, { recursive: true });
+      caps["appium:derivedDataPath"] = SIMULATOR_WDA_DERIVED_DATA;
+    }
+  }
+  if (options.platform === "android") {
+    const requested = String(caps["appium:udid"] ?? options.deviceId);
+    const identity = await resolveAndroidAppiumIdentity(requested);
+    if (identity.udid) {
+      caps["appium:udid"] = identity.udid;
+    }
+    if (identity.avd && caps["appium:avd"] === undefined) {
+      caps["appium:avd"] = identity.avd;
+    }
+    if (options.appPackage && !caps["appium:appPackage"]) {
+      caps["appium:appPackage"] = options.appPackage;
+    }
+  }
+  return caps;
+}
+
+class ActionGate {
+  locked = false;
+  gesture = null;
+  deferredTap = null;
+  isPointerActive() {
+    return this.gesture != null || this.deferredTap != null;
+  }
+  async withLock(fn) {
+    if (this.gesture || this.deferredTap) {
+      throw new Error("Device is busy with live pointer control");
+    }
+    if (this.locked) {
+      throw new Error("Device is busy with another action");
+    }
+    this.locked = true;
     try {
       return await fn();
     } finally {
@@ -17369,7 +17828,7 @@ async function createDeviceSession(options) {
   const screenshot = async () => {
     await mkdir3(SCREENSHOT_DIR, { recursive: true });
     const frame = await captureFrame();
-    const path = join6(SCREENSHOT_DIR, `shot_${Date.now()}_${crypto.randomUUID()}.png`);
+    const path = join7(SCREENSHOT_DIR, `shot_${Date.now()}_${crypto.randomUUID()}.png`);
     await Bun.write(path, Uint8Array.from(Buffer.from(frame.base64, "base64")));
     return { path, base64: frame.base64 };
   };
@@ -24193,8 +24652,13 @@ async function installBuildOnDevice(options) {
     }
     throw new Error(`Cannot install iOS build at ${build.path}. Use a .app on simulator or install .ipa via ideviceinstaller.`);
   }
+  const identity = await resolveAndroidAppiumIdentity(deviceId);
+  const serial = identity.udid;
+  if (!serial) {
+    throw new Error(`Android emulator ${deviceId} is not running. Boot it, then retry the install.`);
+  }
   const adb = Bun.which("adb") ?? "adb";
-  const proc = Bun.spawn([adb, "-s", deviceId, "install", "-r", build.path], {
+  const proc = Bun.spawn([adb, "-s", serial, "install", "-r", build.path], {
     stdout: "pipe",
     stderr: "pipe"
   });
@@ -25017,397 +25481,6 @@ function createCatalogRoutes() {
   return app;
 }
 
-// src/domains/devices/application.ts
-import { mkdtemp as mkdtemp2, readFile, rm as rm2 } from "fs/promises";
-import { tmpdir as tmpdir2 } from "os";
-import { join as join7 } from "path";
-async function runCommand3(command, options) {
-  try {
-    const proc = Bun.spawn(command, {
-      env: options?.env ? { ...process.env, ...options.env } : process.env,
-      stdout: "pipe",
-      stderr: "pipe"
-    });
-    const [stdout, stderr, exitCode] = await Promise.all([
-      new Response(proc.stdout).text(),
-      new Response(proc.stderr).text(),
-      proc.exited
-    ]);
-    return { stdout, stderr, exitCode };
-  } catch {
-    return { stdout: "", stderr: `failed to spawn: ${command[0]}`, exitCode: 127 };
-  }
-}
-function androidSdkRoot() {
-  return resolveAndroidSdkRoot();
-}
-async function resolveTool(candidates) {
-  for (const candidate of candidates) {
-    if (!candidate)
-      continue;
-    const { exitCode } = await runCommand3(["test", "-x", candidate]);
-    if (exitCode === 0)
-      return candidate;
-  }
-  return null;
-}
-async function resolveAdb() {
-  const sdk = androidSdkRoot();
-  return resolveTool([...sdk ? [join7(sdk, "platform-tools/adb")] : [], "adb"]);
-}
-async function resolveEmulator() {
-  const sdk = androidSdkRoot();
-  return resolveTool([...sdk ? [join7(sdk, "emulator/emulator")] : [], "emulator"]);
-}
-function formatIosVersion(version2) {
-  const trimmed = version2.trim();
-  if (!trimmed)
-    return "iOS";
-  if (/^iOS\b/i.test(trimmed))
-    return trimmed;
-  return `iOS ${trimmed}`;
-}
-function formatAndroidVersion(apiOrVersion) {
-  const trimmed = apiOrVersion.trim();
-  if (!trimmed)
-    return "Android";
-  if (/^Android\b/i.test(trimmed))
-    return trimmed;
-  if (/^API\b/i.test(trimmed))
-    return trimmed;
-  if (/^\d+(\.\d+)?$/.test(trimmed))
-    return `API ${trimmed}`;
-  return `Android ${trimmed}`;
-}
-function titleCaseWords(value) {
-  return value.split(/\s+/).filter(Boolean).map((word) => {
-    if (/^[a-z]$/i.test(word))
-      return word.toUpperCase();
-    if (/^\d/.test(word))
-      return word;
-    return word.charAt(0).toUpperCase() + word.slice(1).toLowerCase();
-  }).join(" ");
-}
-function runtimeVersionFromIdentifier(runtimeId) {
-  const match2 = runtimeId.match(/iOS-([\d-]+)$/i);
-  if (!match2?.[1])
-    return "iOS";
-  return formatIosVersion(match2[1].replace(/-/g, "."));
-}
-async function listIosSimulators(includeUnavailable) {
-  const { stdout, exitCode } = await runCommand3([
-    "xcrun",
-    "simctl",
-    "list",
-    "devices",
-    "available",
-    "-j"
-  ]);
-  if (exitCode !== 0)
-    return [];
-  let parsed;
-  try {
-    parsed = JSON.parse(stdout);
-  } catch {
-    return [];
-  }
-  const devices = [];
-  for (const [runtimeId, runtimeDevices] of Object.entries(parsed.devices ?? {})) {
-    if (!/iOS/i.test(runtimeId))
-      continue;
-    const osVersion = runtimeVersionFromIdentifier(runtimeId);
-    for (const device of runtimeDevices) {
-      if (!device.udid || !device.name)
-        continue;
-      if (device.isAvailable === false)
-        continue;
-      const state = device.state ?? "Unknown";
-      if (!includeUnavailable && state !== "Booted")
-        continue;
-      devices.push({
-        id: device.udid,
-        name: device.name,
-        osVersion,
-        platform: "ios",
-        kind: "simulator",
-        state,
-        model: device.deviceTypeIdentifier?.split(".").pop()?.replace(/-/g, " ")
-      });
-    }
-  }
-  return devices.sort((a, b) => {
-    if (a.state === "Booted" && b.state !== "Booted")
-      return -1;
-    if (b.state === "Booted" && a.state !== "Booted")
-      return 1;
-    return a.name.localeCompare(b.name);
-  });
-}
-function isPhoneOrTablet(deviceType) {
-  if (!deviceType)
-    return false;
-  return /^(iPhone|iPad)$/i.test(deviceType);
-}
-function physicalIosState(connection) {
-  const tunnel = connection?.tunnelState?.toLowerCase() ?? "";
-  if (tunnel.includes("connected"))
-    return "connected";
-  if (tunnel.includes("unavailable"))
-    return "unavailable";
-  if (tunnel.includes("disconnected"))
-    return "disconnected";
-  if (connection?.pairingState === "paired")
-    return "paired";
-  return tunnel || connection?.pairingState || "unknown";
-}
-async function listIosPhysicalDevices(includeUnavailable) {
-  const dir = await mkdtemp2(join7(tmpdir2(), "yoqa-devices-"));
-  const jsonPath = join7(dir, "devices.json");
-  try {
-    const { exitCode } = await runCommand3([
-      "xcrun",
-      "devicectl",
-      "list",
-      "devices",
-      "--json-output",
-      jsonPath
-    ]);
-    if (exitCode !== 0)
-      return [];
-    let parsed;
-    try {
-      parsed = JSON.parse(await readFile(jsonPath, "utf8"));
-    } catch {
-      return [];
-    }
-    const devices = [];
-    for (const item of parsed.result?.devices ?? []) {
-      const hardware = item.hardwareProperties;
-      const props = item.deviceProperties;
-      if (!hardware?.udid)
-        continue;
-      if (hardware.reality && hardware.reality !== "physical")
-        continue;
-      if (!isPhoneOrTablet(hardware.deviceType))
-        continue;
-      if (hardware.platform && !/^iOS$/i.test(hardware.platform))
-        continue;
-      const state = physicalIosState(item.connectionProperties);
-      if (!includeUnavailable && state === "unavailable")
-        continue;
-      const modelName = hardware.marketingName ?? hardware.productType ?? "iPhone";
-      const owner = props?.name?.trim() || undefined;
-      devices.push({
-        id: hardware.udid,
-        name: modelName,
-        owner,
-        osVersion: formatIosVersion(props?.osVersionNumber ?? ""),
-        platform: "ios",
-        kind: "physical",
-        state,
-        model: hardware.productType
-      });
-    }
-    return devices.sort((a, b) => a.name.localeCompare(b.name));
-  } finally {
-    await rm2(dir, { recursive: true, force: true });
-  }
-}
-async function listIosDevices(options = {}) {
-  const includeUnavailable = options.includeUnavailable ?? true;
-  const [physical, simulators] = await Promise.all([
-    listIosPhysicalDevices(includeUnavailable),
-    listIosSimulators(includeUnavailable)
-  ]);
-  return [...physical, ...simulators];
-}
-function parseAdbDevices(output) {
-  const lines = output.split(`
-`).map((line) => line.trim()).filter(Boolean);
-  const results = [];
-  for (const line of lines) {
-    if (line.startsWith("List of devices"))
-      continue;
-    const parts = line.split(/\s+/);
-    const serial = parts[0];
-    const state = parts[1];
-    if (!serial || !state)
-      continue;
-    const meta = {};
-    for (const part of parts.slice(2)) {
-      const eq2 = part.indexOf(":");
-      if (eq2 <= 0)
-        continue;
-      meta[part.slice(0, eq2)] = part.slice(eq2 + 1);
-    }
-    results.push({
-      serial,
-      state,
-      product: meta.product,
-      model: meta.model,
-      device: meta.device,
-      transportId: meta.transport_id
-    });
-  }
-  return results;
-}
-function humanizeAvdName(avdName) {
-  return titleCaseWords(avdName.replace(/_/g, " "));
-}
-function humanizeModel(model) {
-  if (!model)
-    return;
-  return titleCaseWords(model.replace(/_/g, " "));
-}
-async function findAvdConfigPath(avdName) {
-  const home = process.env.HOME ?? "";
-  const roots = [join7(home, ".android/avd"), join7(home, "Library/Android/sdk/.android/avd")];
-  for (const root of roots) {
-    const direct = join7(root, `${avdName}.avd`, "config.ini");
-    try {
-      await readFile(direct, "utf8");
-      return direct;
-    } catch {}
-    try {
-      const glob = new Bun.Glob("*.avd/config.ini");
-      for await (const match2 of glob.scan({ cwd: root, onlyFiles: true })) {
-        const path = join7(root, match2);
-        const text2 = await readFile(path, "utf8");
-        const idLine = text2.split(`
-`).find((line) => line.startsWith("AvdId="));
-        const id = idLine?.slice("AvdId=".length).trim();
-        if (id === avdName)
-          return path;
-      }
-    } catch {}
-  }
-  return null;
-}
-async function readAvdConfig(avdName) {
-  const path = await findAvdConfigPath(avdName);
-  if (!path)
-    return { api: null, deviceName: null };
-  try {
-    const text2 = await readFile(path, "utf8");
-    const imageLine = text2.split(`
-`).find((line) => line.includes("system-images") && line.includes("android-"));
-    const apiMatch = imageLine?.match(/android-([\d.]+)/);
-    const deviceLine = text2.split(`
-`).find((entry) => entry.startsWith("hw.device.name="));
-    const deviceRaw = deviceLine?.slice("hw.device.name=".length).trim();
-    return {
-      api: apiMatch?.[1] ?? null,
-      deviceName: humanizeModel(deviceRaw) ?? null
-    };
-  } catch {
-    return { api: null, deviceName: null };
-  }
-}
-async function adbAvdName(adb, serial) {
-  const { stdout, exitCode } = await runCommand3([adb, "-s", serial, "emu", "avd", "name"]);
-  if (exitCode !== 0)
-    return null;
-  const name = stdout.trim().split(`
-`)[0]?.trim();
-  return name || null;
-}
-async function adbGetProp(adb, serial, prop) {
-  const { stdout, exitCode } = await runCommand3([adb, "-s", serial, "shell", "getprop", prop]);
-  if (exitCode !== 0)
-    return null;
-  const value = stdout.trim();
-  return value || null;
-}
-async function listAndroidAdbDevices(adb) {
-  const { stdout, exitCode } = await runCommand3([adb, "devices", "-l"]);
-  if (exitCode !== 0) {
-    return { physical: [], runningEmulators: [], runningAvdNames: new Set };
-  }
-  const entries = parseAdbDevices(stdout);
-  const physical = [];
-  const runningEmulators = [];
-  const runningAvdNames = new Set;
-  for (const entry of entries) {
-    const isEmulator = entry.serial.startsWith("emulator-") || entry.product === "sdk_gphone";
-    if (isEmulator) {
-      const avdName = await adbAvdName(adb, entry.serial);
-      if (avdName)
-        runningAvdNames.add(avdName);
-      const avdConfig = avdName ? await readAvdConfig(avdName) : null;
-      const release2 = await adbGetProp(adb, entry.serial, "ro.build.version.release") ?? avdConfig?.api ?? null;
-      const model2 = humanizeModel(entry.model) ?? avdConfig?.deviceName ?? (avdName ? humanizeAvdName(avdName) : entry.serial);
-      runningEmulators.push({
-        id: avdName ?? entry.serial,
-        name: model2,
-        osVersion: formatAndroidVersion(release2 ?? ""),
-        platform: "android",
-        kind: "emulator",
-        state: entry.state === "device" ? "online" : entry.state,
-        model: avdName ?? entry.model
-      });
-      continue;
-    }
-    const release = await adbGetProp(adb, entry.serial, "ro.build.version.release");
-    const model = humanizeModel(entry.model) ?? await adbGetProp(adb, entry.serial, "ro.product.model") ?? entry.serial;
-    physical.push({
-      id: entry.serial,
-      name: model,
-      osVersion: formatAndroidVersion(release ?? ""),
-      platform: "android",
-      kind: "physical",
-      state: entry.state,
-      model: entry.model
-    });
-  }
-  return { physical, runningEmulators, runningAvdNames };
-}
-async function listAndroidAvds(emulatorBin, runningAvdNames, includeUnavailable) {
-  const { stdout, exitCode } = await runCommand3([emulatorBin, "-list-avds"]);
-  if (exitCode !== 0)
-    return [];
-  const names = stdout.split(`
-`).map((line) => line.trim()).filter(Boolean);
-  const devices = [];
-  for (const avdName of names) {
-    const isRunning = runningAvdNames.has(avdName);
-    if (!includeUnavailable && !isRunning)
-      continue;
-    if (isRunning)
-      continue;
-    const { api, deviceName } = await readAvdConfig(avdName);
-    devices.push({
-      id: avdName,
-      name: deviceName ?? humanizeAvdName(avdName),
-      osVersion: formatAndroidVersion(api ?? ""),
-      platform: "android",
-      kind: "emulator",
-      state: "offline",
-      model: avdName
-    });
-  }
-  return devices;
-}
-async function listAndroidDevices(options = {}) {
-  const includeUnavailable = options.includeUnavailable ?? true;
-  const [adb, emulatorBin] = await Promise.all([resolveAdb(), resolveEmulator()]);
-  const adbResult = adb ? await listAndroidAdbDevices(adb) : { physical: [], runningEmulators: [], runningAvdNames: new Set };
-  const offlineAvds = emulatorBin != null ? await listAndroidAvds(emulatorBin, adbResult.runningAvdNames, includeUnavailable) : [];
-  const physical = includeUnavailable ? adbResult.physical : adbResult.physical.filter((device) => device.state === "device");
-  const emulators = [...adbResult.runningEmulators, ...offlineAvds].sort((a, b) => {
-    const aOnline = a.state === "online" ? 0 : 1;
-    const bOnline = b.state === "online" ? 0 : 1;
-    if (aOnline !== bOnline)
-      return aOnline - bOnline;
-    return a.name.localeCompare(b.name);
-  });
-  return [...physical, ...emulators];
-}
-async function listDevices(platform, options = {}) {
-  if (platform === "ios")
-    return listIosDevices(options);
-  return listAndroidDevices(options);
-}
-
 // src/interfaces/http/devices.ts
 function createDevicesRoutes() {
   const app = new Hono2;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@yoqa/runner",
-	"version": "0.3.17",
+	"version": "0.3.18",
 	"description": "Yoqa local runner — Appium + catalog HTTP API (Bun). Start with yoqa serve or the yoqa-runner bin.",
 	"license": "UNLICENSED",
 	"type": "module",