@ishlabs/cli 0.27.0 → 0.27.1

package/dist/lib/local-sim/device-pool.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Device pool for parallel native runs. One `ish study run --parallel N` drives
+ * a pool of N devices; each worker claim()s a device and release()s it when its
+ * participant finishes.
+ *
+ * Devices come from a pluggable `DeviceProvider` (simulator | local-avd today;
+ * redroid | remote later), so the pool itself is provider-agnostic — it owns the
+ * claim/release queue, the crash-safe lock, and teardown of only what we started.
+ *
+ * The pure helpers (createDeviceQueue, allocateWdaPorts, maxConcurrentDevices)
+ * are exported and unit-tested without any device.
+ */
+/** Rough per-device RAM for auto-sizing. iOS sims are lighter than emulators. */
+export declare const PER_DEVICE_MB: {
+    readonly ios: 1024;
+    readonly android: 1536;
+};
+export interface PooledDevice {
+    platform: "ios" | "android";
+    /** iOS simulator udid, or Android adb serial (e.g. "emulator-5554"). */
+    id: string;
+    /** iOS only: the WDA port allocated to THIS device. */
+    wdaPort?: number;
+    /** True when the pool booted/cloned/launched this device (=> we tear it down). */
+    startedByUs: boolean;
+    /** Android: name of an AVD WE auto-created for this device (deleted on teardown). */
+    createdAvd?: string;
+}
+/**
+ * `count` distinct ports starting at `base`, skipping any an injected `isFree`
+ * marks taken (a stale runner on 8100). Pure — `isFree` defaults to all-free.
+ */
+export declare function allocateWdaPorts(count: number, base?: number, isFree?: (p: number) => boolean): number[];
+/**
+ * How many devices we can run concurrently given the host's RAM. This is the
+ * "anyone can run it" lever: a weak machine gets fewer (>=1, never errors), the
+ * rest queue.
+ *
+ * Sizes off TOTAL RAM × a utilization fraction, NOT `os.freemem()` —
+ * `freemem()` is unreliable cross-platform (macOS reports nearly everything as
+ * "used" because file cache is reclaimable-but-counted, so a 64 GB Mac shows
+ * ~0 free). Total × utilization is stable and machine-appropriate. Pure so
+ * tests can pin the sizing.
+ */
+export declare function maxConcurrentDevices(opts: {
+    totalMemBytes: number;
+    perDeviceMb: number;
+    requested: number;
+    /** Available device slots (e.g. AVD count). Omit for unbounded (iOS clones). */
+    deviceCount?: number;
+    /** Fraction of total RAM we're willing to dedicate to devices. */
+    utilization?: number;
+    /** Headroom (MB) reserved for the OS + the CLI before counting devices. */
+    reserveMb?: number;
+}): number;
+export interface DeviceQueue {
+    claim(): Promise<PooledDevice>;
+    release(d: PooledDevice): void;
+}
+/**
+ * FIFO semaphore over a fixed device list: claim() takes a free device or waits;
+ * release() hands the device to the next waiter or returns it to the free list.
+ * Double-release of an already-free device is a no-op.
+ */
+export declare function createDeviceQueue(devices: PooledDevice[]): DeviceQueue;
+export interface DeviceProvider {
+    /** Provision up to `want` devices (reuse existing first, start the shortfall). */
+    provision(want: number, log: (m: string) => void): Promise<PooledDevice[]>;
+    /** Tear down ONE device this provider started. No-op for reused devices. */
+    teardownOne(d: PooledDevice, log: (m: string) => void): Promise<void>;
+}
+export interface DevicePool {
+    readonly devices: readonly PooledDevice[];
+    claim(): Promise<PooledDevice>;
+    release(d: PooledDevice): void;
+    /** Tear down ONLY devices we started; idempotent. Called by the loop's finally. */
+    teardown(): Promise<void>;
+}
+export declare function provisionDevicePool(opts: {
+    platform: string;
+    size: number;
+    log: (m: string) => void;
+}): Promise<DevicePool>;
+/** Total host RAM — the basis for auto-sizing the pool (see maxConcurrentDevices). */
+export declare function totalMemBytes(): number;

package/dist/lib/local-sim/device-pool.js

@@ -0,0 +1,316 @@
+/**
+ * Device pool for parallel native runs. One `ish study run --parallel N` drives
+ * a pool of N devices; each worker claim()s a device and release()s it when its
+ * participant finishes.
+ *
+ * Devices come from a pluggable `DeviceProvider` (simulator | local-avd today;
+ * redroid | remote later), so the pool itself is provider-agnostic — it owns the
+ * claim/release queue, the crash-safe lock, and teardown of only what we started.
+ *
+ * The pure helpers (createDeviceQueue, allocateWdaPorts, maxConcurrentDevices)
+ * are exported and unit-tested without any device.
+ */
+import { totalmem } from "node:os";
+import { existsSync, readFileSync, writeFileSync, rmSync } from "node:fs";
+import { devicePoolLockPath } from "../paths.js";
+import { IosError } from "./simctl.js";
+import { listAllDevices, listBootedDevices, createSimulator, bootDevice, deleteDevice, } from "./simctl-provision.js";
+import { listOnlineSerials } from "./adb.js";
+import { listAvds, spawnEmulator, emulatorPorts, waitForBoot, emuKill, cloneAvd, deleteAvd, EmulatorError, } from "./emulator.js";
+/** WDA port range start for pooled iOS devices. */
+const WDA_BASE_PORT = 8100;
+/** Rough per-device RAM for auto-sizing. iOS sims are lighter than emulators. */
+export const PER_DEVICE_MB = { ios: 1024, android: 1536 };
+// --- Pure helpers (unit-tested) ---------------------------------------------
+/**
+ * `count` distinct ports starting at `base`, skipping any an injected `isFree`
+ * marks taken (a stale runner on 8100). Pure — `isFree` defaults to all-free.
+ */
+export function allocateWdaPorts(count, base = WDA_BASE_PORT, isFree = () => true) {
+    const ports = [];
+    for (let p = base; ports.length < count && p < base + 1000; p++) {
+        if (isFree(p))
+            ports.push(p);
+    }
+    if (ports.length < count) {
+        throw new Error(`could not allocate ${count} free WDA ports from ${base}`);
+    }
+    return ports;
+}
+/**
+ * How many devices we can run concurrently given the host's RAM. This is the
+ * "anyone can run it" lever: a weak machine gets fewer (>=1, never errors), the
+ * rest queue.
+ *
+ * Sizes off TOTAL RAM × a utilization fraction, NOT `os.freemem()` —
+ * `freemem()` is unreliable cross-platform (macOS reports nearly everything as
+ * "used" because file cache is reclaimable-but-counted, so a 64 GB Mac shows
+ * ~0 free). Total × utilization is stable and machine-appropriate. Pure so
+ * tests can pin the sizing.
+ */
+export function maxConcurrentDevices(opts) {
+    const utilization = opts.utilization ?? 0.5;
+    const reserveMb = opts.reserveMb ?? 1536;
+    const budgetMb = Math.max(0, (opts.totalMemBytes / (1024 * 1024)) * utilization - reserveMb);
+    const byRam = Math.max(1, Math.floor(budgetMb / Math.max(1, opts.perDeviceMb)));
+    let n = Math.min(opts.requested, byRam);
+    if (opts.deviceCount !== undefined)
+        n = Math.min(n, opts.deviceCount);
+    return Math.max(1, n); // always at least sequential
+}
+/**
+ * FIFO semaphore over a fixed device list: claim() takes a free device or waits;
+ * release() hands the device to the next waiter or returns it to the free list.
+ * Double-release of an already-free device is a no-op.
+ */
+export function createDeviceQueue(devices) {
+    const free = [...devices];
+    const freeIds = new Set(free.map((d) => d.id));
+    const waiters = [];
+    return {
+        claim() {
+            const d = free.shift();
+            if (d) {
+                freeIds.delete(d.id);
+                return Promise.resolve(d);
+            }
+            return new Promise((resolve) => waiters.push(resolve));
+        },
+        release(d) {
+            if (freeIds.has(d.id))
+                return; // already free — double release is a no-op
+            const waiter = waiters.shift();
+            if (waiter) {
+                waiter(d); // handed straight to the next worker; stays claimed
+            }
+            else {
+                free.push(d);
+                freeIds.add(d.id);
+            }
+        },
+    };
+}
+/** Prefer an iPhone to clone from; a booted one first, else any available. */
+function pickCloneSource(all, booted) {
+    return (booted[0] ??
+        all.find((d) => /iPhone/i.test(d.name) && d.state !== "Creating") ??
+        all[0]);
+}
+function simulatorProvider() {
+    return {
+        async provision(want, log) {
+            const all = await listAllDevices();
+            const booted = await listBootedDevices();
+            const ports = allocateWdaPorts(want);
+            const devices = [];
+            // Reuse already-booted simulators first (don't tear these down).
+            for (const d of booted.slice(0, want)) {
+                devices.push({ platform: "ios", id: d.udid, wdaPort: ports[devices.length], startedByUs: false });
+            }
+            const shortfall = want - devices.length;
+            if (shortfall > 0) {
+                const source = pickCloneSource(all, booted);
+                if (!source?.deviceTypeId) {
+                    throw new IosError("No simulator to model the pool on — boot one (Simulator.app) or run `ish check ios`.");
+                }
+                log(`Creating ${shortfall} simulator(s) (${source.name}) for the pool — first boot can take ~30s each...`);
+                for (let i = 0; i < shortfall; i++) {
+                    const name = `ish-pool-${process.pid}-${i}`;
+                    const udid = await createSimulator(name, source.deviceTypeId, source.runtime);
+                    await bootDevice(udid);
+                    devices.push({ platform: "ios", id: udid, wdaPort: ports[devices.length], startedByUs: true });
+                }
+            }
+            return devices;
+        },
+        async teardownOne(d, log) {
+            if (!d.startedByUs)
+                return;
+            log(`Removing pooled simulator ${d.id.slice(0, 8)}…`);
+            await deleteDevice(d.id);
+        },
+    };
+}
+function localAvdProvider() {
+    // Track emulators WE spawned so teardown can SIGKILL them if `emu kill` hangs.
+    const spawned = new Map();
+    return {
+        async provision(want, log) {
+            const online = await listOnlineSerials();
+            const devices = [];
+            for (const serial of online.slice(0, want)) {
+                devices.push({ platform: "android", id: serial, startedByUs: false });
+            }
+            const shortfall = want - devices.length;
+            if (shortfall > 0) {
+                const avds = await listAvds();
+                if (avds.length === 0) {
+                    throw new EmulatorError("No Android AVDs found — create one in Android Studio › Device Manager. (The pool clones it to as many as you need.)");
+                }
+                // AVDs we'll launch from. Auto-clone the shortfall from an existing AVD
+                // (file-copy, no avdmanager/JDK needed) so you only need ONE AVD.
+                const usable = [...avds];
+                const createdAvds = [];
+                const need = shortfall - usable.length;
+                if (need > 0) {
+                    const source = avds[0];
+                    log(`Cloning ${need} AVD(s) from "${source}" so --parallel has enough devices...`);
+                    for (let i = 0; i < need; i++) {
+                        const name = `ish-pool-avd-${process.pid}-${i}`;
+                        cloneAvd(source, name);
+                        createdAvds.push(name);
+                        usable.push(name);
+                    }
+                }
+                const toLaunch = Math.min(shortfall, usable.length);
+                if (toLaunch < shortfall) {
+                    log(`Only ${usable.length} AVD(s) available; launching ${toLaunch} (create more AVDs or lower --parallel).`);
+                }
+                // Avoid console ports already taken by reused emulators.
+                const usedPorts = new Set(online
+                    .filter((s) => s.startsWith("emulator-"))
+                    .map((s) => Number(s.slice("emulator-".length))));
+                const ports = emulatorPorts(toLaunch + usedPorts.size)
+                    .filter((p) => !usedPorts.has(p))
+                    .slice(0, toLaunch);
+                const createdSet = new Set(createdAvds);
+                log(`Launching ${toLaunch} headless emulator(s) for the pool — first boot can take ~60s each...`);
+                const launched = [];
+                for (let i = 0; i < toLaunch; i++) {
+                    const avd = usable[i];
+                    const { child, serial } = spawnEmulator(avd, ports[i], { headless: true });
+                    spawned.set(serial, child);
+                    launched.push({ serial, avd });
+                }
+                await Promise.all(launched.map((l) => waitForBoot(l.serial)));
+                for (const { serial, avd } of launched) {
+                    devices.push({
+                        platform: "android",
+                        id: serial,
+                        startedByUs: true,
+                        ...(createdSet.has(avd) ? { createdAvd: avd } : {}),
+                    });
+                }
+            }
+            return devices;
+        },
+        async teardownOne(d, log) {
+            if (!d.startedByUs)
+                return;
+            log(`Stopping pooled emulator ${d.id}…`);
+            await emuKill(d.id);
+            const child = spawned.get(d.id);
+            if (child && !child.killed) {
+                try {
+                    child.kill("SIGKILL");
+                }
+                catch {
+                    /* already gone */
+                }
+            }
+            spawned.delete(d.id);
+            if (d.createdAvd)
+                deleteAvd(d.createdAvd);
+        },
+    };
+}
+function providerFor(platform) {
+    if (platform === "ios")
+        return simulatorProvider();
+    if (platform === "android")
+        return localAvdProvider();
+    throw new IosError(`device pool not yet implemented for platform "${platform}"`);
+}
+function pidIsAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function readLock() {
+    const p = devicePoolLockPath();
+    if (!existsSync(p))
+        return null;
+    try {
+        return JSON.parse(readFileSync(p, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+function writeLock(lock) {
+    writeFileSync(devicePoolLockPath(), JSON.stringify(lock), { mode: 0o600 });
+}
+function clearLock() {
+    try {
+        rmSync(devicePoolLockPath(), { force: true });
+    }
+    catch {
+        /* best effort */
+    }
+}
+/** Reap a lock left by a crashed prior run: tear down its started devices. */
+async function reapStaleLock(log) {
+    const lock = readLock();
+    if (!lock)
+        return;
+    if (pidIsAlive(lock.pid)) {
+        throw new IosError(`Another parallel native run (pid ${lock.pid}) holds the device pool. ` +
+            "Wait for it to finish, or kill it and retry.");
+    }
+    log("Reaping devices from a previous interrupted parallel run...");
+    for (const d of lock.devices) {
+        if (!d.startedByUs)
+            continue;
+        try {
+            if (d.platform === "ios")
+                await deleteDevice(d.id);
+            else if (d.platform === "android") {
+                await emuKill(d.id);
+                if (d.createdAvd)
+                    deleteAvd(d.createdAvd);
+            }
+        }
+        catch {
+            /* best effort */
+        }
+    }
+    clearLock();
+}
+export async function provisionDevicePool(opts) {
+    await reapStaleLock(opts.log);
+    const provider = providerFor(opts.platform);
+    const devices = await provider.provision(opts.size, opts.log);
+    writeLock({ pid: process.pid, platform: opts.platform, startedAt: Date.now(), devices });
+    const queue = createDeviceQueue([...devices]);
+    let tornDown = false;
+    const pool = {
+        devices,
+        claim: () => queue.claim(),
+        release: (d) => queue.release(d),
+        async teardown() {
+            if (tornDown)
+                return;
+            tornDown = true;
+            for (const d of devices) {
+                await provider.teardownOne(d, opts.log).catch(() => { });
+            }
+            clearLock();
+            process.off("SIGTERM", onTerm);
+        },
+    };
+    // The run loop owns SIGINT (sets `cancelled`, then runs teardown in its
+    // finally). Add SIGTERM here so a `kill` also cleans up the devices we booted.
+    const onTerm = () => {
+        void pool.teardown().finally(() => process.exit(1));
+    };
+    process.once("SIGTERM", onTerm);
+    return pool;
+}
+/** Total host RAM — the basis for auto-sizing the pool (see maxConcurrentDevices). */
+export function totalMemBytes() {
+    return totalmem();
+}

package/dist/lib/local-sim/device.d.ts

@@ -183,5 +183,9 @@ export declare function createDevice(platform: string, opts: {
     sharedBrowser?: Browser;
     /** Native: local .apk/.app path to install or a package/bundle id to launch. */
     appPath?: string;
+    /** Native pool: the device to drive — iOS simulator udid or Android adb serial. */
+    deviceId?: string;
+    /** iOS pool: the per-device WDA port. */
+    wdaPort?: number;
     log?: (msg: string) => void;
 }): Promise<SimulationDevice>;

package/dist/lib/local-sim/device.js

@@ -132,17 +132,35 @@ export async function createDevice(platform, opts) {
         }
         case "android": {
             const { AndroidDevice } = await import("./android.js");
-            return new AndroidDevice({
+            const dev = new AndroidDevice({
                 appPath: opts.appPath,
                 contextValues: opts.contextValues,
                 log: opts.log,
             });
+            if (!opts.deviceId)
+                return dev; // single-device path — unchanged
+            // Parallel pool: pin every adb call this device makes to its serial.
+            // A Proxy runs each method inside withAdbSerial so AsyncLocalStorage
+            // carries the serial through all the device's internal adb calls — no
+            // per-method threading, and concurrent devices stay isolated.
+            const { withAdbSerial } = await import("./adb.js");
+            const serial = opts.deviceId;
+            return new Proxy(dev, {
+                get(target, prop, receiver) {
+                    const val = Reflect.get(target, prop, receiver);
+                    return typeof val === "function"
+                        ? (...args) => withAdbSerial(serial, () => val.apply(target, args))
+                        : val;
+                },
+            });
         }
         case "ios": {
             const { IOSDevice } = await import("./ios.js");
             return new IOSDevice({
                 appPath: opts.appPath,
                 contextValues: opts.contextValues,
+                udid: opts.deviceId,
+                wdaPort: opts.wdaPort,
                 log: opts.log,
             });
         }

package/dist/lib/local-sim/emulator.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Android emulator (AVD) provisioning for parallel runs: list AVDs, launch
+ * tuned/headless emulators on distinct ports, wait for boot, kill them.
+ *
+ * The pool launches these and tears them down; the per-device adb routing is
+ * handled by `withAdbSerial` (see adb.ts), so this module only deals with the
+ * emulator PROCESS lifecycle (mirrors how connect.ts spawns/kills cloudflared).
+ */
+import { type ChildProcess } from "node:child_process";
+export declare class EmulatorError extends Error {
+    constructor(message: string);
+}
+/**
+ * Rewrite the `path=` / `path.rel=` lines of an AVD's pointer `.ini` to point at
+ * the clone's dir. Pure (tested).
+ */
+export declare function rewriteAvdPointerIni(text: string, newAvdDirAbs: string): string;
+/**
+ * Clone an existing AVD by file-copy — NO avdmanager (and therefore no JDK
+ * dependency, which `avdmanager` needs and many machines lack). Copies the
+ * `.avd` dir minus its running-state, rewrites the pointer `.ini` paths and the
+ * `AvdId` / displayname. Turns "you need N AVDs" into "you need ONE".
+ */
+export declare function cloneAvd(source: string, newName: string): void;
+/** Delete a (cloned) AVD's files. Best-effort, no avdmanager needed. */
+export declare function deleteAvd(name: string): void;
+/** AVD names available on this machine (`emulator -list-avds`). */
+export declare function listAvds(): Promise<string[]>;
+export interface SpawnedEmulator {
+    child: ChildProcess;
+    /** adb serial for this instance, e.g. "emulator-5554". */
+    serial: string;
+    port: number;
+}
+/**
+ * Launch an AVD as a tuned, lightweight, (by default) headless emulator on a
+ * specific console port. The serial is deterministically `emulator-<port>`.
+ * The flags keep it small so many fit on a normal machine: no window, software
+ * GPU, capped RAM, no boot animation / audio / snapshot writeback.
+ */
+export declare function spawnEmulator(avd: string, port: number, opts?: {
+    headless?: boolean;
+    memMb?: number;
+}): SpawnedEmulator;
+/** Console ports for N emulators: 5554, 5556, 5558, … (adb wants even ports). */
+export declare function emulatorPorts(count: number, base?: number): number[];
+/** Wait until `serial` is online AND `sys.boot_completed` is 1. */
+export declare function waitForBoot(serial: string, timeoutMs?: number): Promise<void>;
+/** Gracefully stop an emulator (`adb -s <serial> emu kill`). Best-effort. */
+export declare function emuKill(serial: string): Promise<void>;

package/dist/lib/local-sim/emulator.js

@@ -0,0 +1,189 @@
+/**
+ * Android emulator (AVD) provisioning for parallel runs: list AVDs, launch
+ * tuned/headless emulators on distinct ports, wait for boot, kill them.
+ *
+ * The pool launches these and tears them down; the per-device adb routing is
+ * handled by `withAdbSerial` (see adb.ts), so this module only deals with the
+ * emulator PROCESS lifecycle (mirrors how connect.ts spawns/kills cloudflared).
+ */
+import { spawn, execFile, execFileSync } from "node:child_process";
+import { existsSync, readFileSync, writeFileSync, cpSync, rmSync } from "node:fs";
+import { join, basename } from "node:path";
+import { homedir } from "node:os";
+import { promisify } from "node:util";
+import { withAdbSerial, adb, adbShell } from "./adb.js";
+const execFileAsync = promisify(execFile);
+/** Candidate Android SDK roots (env first, then the OS defaults). */
+function sdkRoots() {
+    return [
+        process.env.ANDROID_HOME,
+        process.env.ANDROID_SDK_ROOT,
+        join(homedir(), "Library", "Android", "sdk"),
+        join(homedir(), "Android", "Sdk"),
+    ].filter(Boolean);
+}
+export class EmulatorError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "EmulatorError";
+    }
+}
+/** Resolve the `emulator` binary: ISH_EMULATOR → SDK → PATH. */
+function findEmulator() {
+    const fromEnv = process.env.ISH_EMULATOR;
+    if (fromEnv && existsSync(fromEnv))
+        return fromEnv;
+    for (const home of sdkRoots()) {
+        const p = join(home, "emulator", "emulator");
+        if (existsSync(p))
+            return p;
+    }
+    try {
+        execFileSync(process.platform === "win32" ? "where" : "which", ["emulator"], { stdio: "ignore" });
+        return "emulator";
+    }
+    catch {
+        return null;
+    }
+}
+/** The AVD home dir (where `<name>.avd/` + `<name>.ini` live). */
+function avdHome() {
+    return process.env.ANDROID_AVD_HOME || join(homedir(), ".android", "avd");
+}
+/**
+ * Running-state / lock files we must NOT copy into a clone — the emulator
+ * regenerates them on boot, and copying them would carry over locks, snapshots,
+ * and the running userdata overlay (also a needless multi-GB copy).
+ */
+const TRANSIENT_AVD_ENTRIES = new Set([
+    "snapshots",
+    "snapshot.lock.lock",
+    "snapshot.trace",
+    "read-snapshot.txt",
+    "multiinstance.lock",
+    "hardware-qemu.ini",
+    "hardware-qemu.ini.lock",
+    "userdata-qemu.img",
+    "userdata-qemu.img.qcow2",
+    "cache.img.qcow2",
+    "encryptionkey.img.qcow2",
+    "tmpAdbCmds",
+    "version_num.cache",
+]);
+/**
+ * Rewrite the `path=` / `path.rel=` lines of an AVD's pointer `.ini` to point at
+ * the clone's dir. Pure (tested).
+ */
+export function rewriteAvdPointerIni(text, newAvdDirAbs) {
+    const rel = `avd/${basename(newAvdDirAbs)}`;
+    return text
+        .replace(/^path=.*$/m, `path=${newAvdDirAbs}`)
+        .replace(/^path\.rel=.*$/m, `path.rel=${rel}`);
+}
+/**
+ * Clone an existing AVD by file-copy — NO avdmanager (and therefore no JDK
+ * dependency, which `avdmanager` needs and many machines lack). Copies the
+ * `.avd` dir minus its running-state, rewrites the pointer `.ini` paths and the
+ * `AvdId` / displayname. Turns "you need N AVDs" into "you need ONE".
+ */
+export function cloneAvd(source, newName) {
+    const home = avdHome();
+    const srcDir = join(home, `${source}.avd`);
+    const srcIni = join(home, `${source}.ini`);
+    const dstDir = join(home, `${newName}.avd`);
+    const dstIni = join(home, `${newName}.ini`);
+    if (!existsSync(srcDir)) {
+        throw new EmulatorError(`Cannot clone AVD "${source}" — ${srcDir} not found.`);
+    }
+    // Copy the data dir, skipping running-state/lock files (also avoids a needless
+    // multi-GB copy of the live userdata overlay).
+    cpSync(srcDir, dstDir, {
+        recursive: true,
+        filter: (src) => !TRANSIENT_AVD_ENTRIES.has(basename(src)),
+    });
+    // Pointer .ini (paths) and config.ini (AvdId / displayname) → the new name.
+    if (existsSync(srcIni)) {
+        writeFileSync(dstIni, rewriteAvdPointerIni(readFileSync(srcIni, "utf8"), dstDir));
+    }
+    const cfgPath = join(dstDir, "config.ini");
+    if (existsSync(cfgPath)) {
+        const cfg = readFileSync(cfgPath, "utf8")
+            .replace(/^AvdId=.*$/m, `AvdId=${newName}`)
+            .replace(/^avd\.ini\.displayname=.*$/m, `avd.ini.displayname=${newName}`);
+        writeFileSync(cfgPath, cfg);
+    }
+}
+/** Delete a (cloned) AVD's files. Best-effort, no avdmanager needed. */
+export function deleteAvd(name) {
+    const home = avdHome();
+    rmSync(join(home, `${name}.avd`), { recursive: true, force: true });
+    rmSync(join(home, `${name}.ini`), { force: true });
+}
+/** AVD names available on this machine (`emulator -list-avds`). */
+export async function listAvds() {
+    const bin = findEmulator();
+    if (!bin)
+        return [];
+    try {
+        const { stdout } = await execFileAsync(bin, ["-list-avds"], { timeout: 15_000 });
+        return stdout.split("\n").map((s) => s.trim()).filter(Boolean);
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Launch an AVD as a tuned, lightweight, (by default) headless emulator on a
+ * specific console port. The serial is deterministically `emulator-<port>`.
+ * The flags keep it small so many fit on a normal machine: no window, software
+ * GPU, capped RAM, no boot animation / audio / snapshot writeback.
+ */
+export function spawnEmulator(avd, port, opts = {}) {
+    const bin = findEmulator();
+    if (!bin) {
+        throw new EmulatorError("emulator binary not found — set ISH_EMULATOR or install the Android SDK 'emulator' package.");
+    }
+    const args = [
+        "-avd", avd,
+        "-port", String(port),
+        "-no-snapshot-save",
+        "-no-boot-anim",
+        "-no-audio",
+        "-gpu", "swiftshader_indirect",
+        "-memory", String(opts.memMb ?? 1536),
+    ];
+    if (opts.headless !== false)
+        args.push("-no-window");
+    // Detach so the emulator outlives this call; we track the child to kill it.
+    const child = spawn(bin, args, { detached: true, stdio: "ignore" });
+    child.unref();
+    return { child, serial: `emulator-${port}`, port };
+}
+/** Console ports for N emulators: 5554, 5556, 5558, … (adb wants even ports). */
+export function emulatorPorts(count, base = 5554) {
+    return Array.from({ length: count }, (_, i) => base + i * 2);
+}
+const delay = (ms) => new Promise((r) => setTimeout(r, ms));
+/** Wait until `serial` is online AND `sys.boot_completed` is 1. */
+export async function waitForBoot(serial, timeoutMs = 180_000) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        try {
+            const booted = await withAdbSerial(serial, async () => {
+                await adb(["wait-for-device"], 10_000);
+                return (await adbShell(["getprop", "sys.boot_completed"], 10_000)).trim();
+            });
+            if (booted === "1")
+                return;
+        }
+        catch {
+            /* not online yet */
+        }
+        await delay(2000);
+    }
+    throw new EmulatorError(`emulator ${serial} did not finish booting within ${timeoutMs / 1000}s`);
+}
+/** Gracefully stop an emulator (`adb -s <serial> emu kill`). Best-effort. */
+export async function emuKill(serial) {
+    await withAdbSerial(serial, () => adb(["emu", "kill"], 15_000)).catch(() => { });
+}