@ishlabs/cli 0.26.1 → 0.27.1

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

@@ -14,8 +14,32 @@ import { execFile, execFileSync } from "node:child_process";
 import { existsSync, mkdirSync, writeFileSync, rmSync } from "node:fs";
 import { join } from "node:path";
 import { promisify } from "node:util";
+import { AsyncLocalStorage } from "node:async_hooks";
 import { binDir, adbBin } from "../paths.js";
 const execFileAsync = promisify(execFile);
+/**
+ * The adb serial to target for the current async call chain. A parallel run
+ * drives N emulators in ONE process; every adb call must hit the right device,
+ * but the CLI targets devices via the `adb -s <serial>` prefix, not a per-call
+ * argument threaded through ~25 functions. AsyncLocalStorage carries the serial
+ * implicitly through the call stack so `adb()` / `screencapPng()` pick it up,
+ * and two concurrent `withAdbSerial(A, …)` / `withAdbSerial(B, …)` chains stay
+ * isolated. Single-device runs leave the store empty and fall back to
+ * ANDROID_SERIAL / the one online device (unchanged behavior).
+ */
+const serialStore = new AsyncLocalStorage();
+/** Run `fn` with all its adb calls pinned to `serial` (parallel pool path). */
+export function withAdbSerial(serial, fn) {
+    return serialStore.run(serial?.trim() || undefined, fn);
+}
+/** The serial in effect for this call chain: store → ANDROID_SERIAL → none. */
+function activeSerial() {
+    return serialStore.getStore() ?? (process.env.ANDROID_SERIAL?.trim() || undefined);
+}
+/** `["-s", serial]` or `[]` — the device-targeting prefix. Pure (tested). */
+export function serialArgs(serial) {
+    return serial ? ["-s", serial] : [];
+}
 // Resolve adb without depending on the caller's PATH: ISH_ADB/ADB override → the
 // Android SDK → Homebrew → our own download cache → PATH. If none is found,
 // ensureAdb() fetches Google's standalone platform-tools (a small zip) into
@@ -105,11 +129,12 @@ export class AdbError extends Error {
         this.name = "AdbError";
     }
 }
-/** Run `adb <args>` and return trimmed stdout. Throws AdbError on failure. */
+/** Run `adb [-s serial] <args>` and return trimmed stdout. Throws AdbError on failure. */
 export async function adb(args, timeoutMs = DEFAULT_TIMEOUT_MS) {
     const bin = await ensureAdb();
+    const full = [...serialArgs(activeSerial()), ...args];
     try {
-        const { stdout } = await execFileAsync(bin, args, {
+        const { stdout } = await execFileAsync(bin, full, {
             timeout: timeoutMs,
             maxBuffer: 4 * 1024 * 1024,
         });
@@ -117,7 +142,7 @@ export async function adb(args, timeoutMs = DEFAULT_TIMEOUT_MS) {
     }
     catch (err) {
         const msg = err instanceof Error ? err.message : String(err);
-        throw new AdbError(`adb ${args.join(" ")} failed: ${msg}`);
+        throw new AdbError(`adb ${full.join(" ")} failed: ${msg}`);
     }
 }
 /** Run `adb shell <args>` and return trimmed stdout. */
@@ -152,6 +177,38 @@ export async function appBuildFromDevice(pkg) {
         return null;
     }
 }
+/**
+ * Pull `"pkg/activity"` out of `dumpsys activity activities`. The foreground
+ * activity surfaces as `topResumedActivity=ActivityRecord{... u0 pkg/activity
+ * t123}` (older builds: `mResumedActivity=...`); we take the `pkg/activity`
+ * token from whichever line is present. The activity may be a short `.Name`
+ * (relative to the package) — kept as-is, exactly what dumpsys reports. Returns
+ * "" when neither line is present.
+ */
+export function parseTopActivity(out) {
+    const m = /topResumedActivity=ActivityRecord\{[^}]*\s(\S+\/\S+)/.exec(out) ??
+        /mResumedActivity:\s*ActivityRecord\{[^}]*\s(\S+\/\S+)/.exec(out) ??
+        /mResumedActivity=ActivityRecord\{[^}]*\s(\S+\/\S+)/.exec(out);
+    if (!m)
+        return "";
+    // The token can carry a trailing task id glued by the regex boundary? No —
+    // `\S+/\S+` stops at the first whitespace, so it is exactly `pkg/activity`.
+    return m[1];
+}
+/**
+ * The foreground `"pkg/activity"` from `dumpsys activity activities`, a coarse
+ * input for the screen signature. Best-effort: returns "" on any failure (the
+ * signature degrades to its package-only coarse token, and the run never
+ * depends on this read).
+ */
+export async function currentActivity() {
+    try {
+        return parseTopActivity(await adbShell(["dumpsys", "activity", "activities"], 15_000));
+    }
+    catch {
+        return "";
+    }
+}
 /**
  * Capture the current screen as raw PNG bytes via `adb exec-out screencap -p`.
  * `exec-out` (not `shell`) avoids the CRLF translation that corrupts binary
@@ -159,8 +216,9 @@ export async function appBuildFromDevice(pkg) {
  */
 export async function screencapPng() {
     const bin = await ensureAdb();
+    const full = [...serialArgs(activeSerial()), "exec-out", "screencap", "-p"];
     try {
-        const { stdout } = await execFileAsync(bin, ["exec-out", "screencap", "-p"], {
+        const { stdout } = await execFileAsync(bin, full, {
             timeout: SCREENCAP_TIMEOUT_MS,
             maxBuffer: SCREENCAP_MAX_BUFFER,
             encoding: "buffer",
@@ -172,27 +230,62 @@ export async function screencapPng() {
         throw new AdbError(`adb exec-out screencap failed: ${msg}`);
     }
 }
-/** Assert exactly one device/emulator is in the `device` state. */
+/**
+ * Parse `adb devices` output into {serial, state} rows. Pure (tested). Skips the
+ * "List of devices attached" header and blank lines.
+ */
+export function parseAdbDevices(out) {
+    return out
+        .split("\n")
+        .slice(1)
+        .map((l) => l.trim())
+        .filter(Boolean)
+        .map((l) => {
+        const [serial, state] = l.split("\t");
+        return { serial: serial ?? "", state: state ?? "" };
+    })
+        .filter((d) => d.serial);
+}
+/** `adb devices` WITHOUT a serial prefix (the list is global, not per-device). */
+async function devicesRaw() {
+    const bin = await ensureAdb();
+    const { stdout } = await execFileAsync(bin, ["devices"], {
+        timeout: DEFAULT_TIMEOUT_MS,
+        maxBuffer: 1024 * 1024,
+    });
+    return stdout.trim();
+}
+/** List online (state==="device") serials. */
+export async function listOnlineSerials() {
+    return parseAdbDevices(await devicesRaw())
+        .filter((d) => d.state === "device")
+        .map((d) => d.serial);
+}
+/**
+ * Assert the target device is online. With a serial in effect (pool path or
+ * ANDROID_SERIAL), confirm THAT serial is online. Otherwise require exactly one.
+ */
 export async function requireOneDevice() {
-    let out;
+    let online;
     try {
-        out = await adb(["devices"]);
+        online = await listOnlineSerials();
     }
     catch (err) {
         const msg = err instanceof Error ? err.message : String(err);
         throw new AdbError(`Could not run adb (looked for "${findAdb() ?? "adb"}"). Run \`ish check android\` to check your setup. ${msg}`);
     }
-    // Output: "List of devices attached\n<serial>\tdevice\n..."
-    const online = out
-        .split("\n")
-        .slice(1)
-        .map((l) => l.trim())
-        .filter((l) => l && l.endsWith("\tdevice"));
     if (online.length === 0) {
         throw new AdbError("No Android device/emulator online. Run `ish check android` to check your setup and how to boot one.");
     }
+    const pinned = activeSerial();
+    if (pinned) {
+        if (online.includes(pinned))
+            return;
+        throw new AdbError(`Android device ${pinned} is not online. Online: ${online.join(", ") || "none"}.`);
+    }
     if (online.length > 1) {
-        throw new AdbError(`Expected exactly one Android device, found ${online.length}. Stop the extras (the sim drives a single device).`);
+        throw new AdbError(`Expected exactly one Android device, found ${online.length}. ` +
+            `Stop the extras, or run with --parallel to pool them.`);
     }
 }
 // --- Input gestures (all in screencap pixel space) ---

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

@@ -66,9 +66,11 @@ export declare class AndroidDevice implements SimulationDevice {
     private refreshDimensions;
     observe(): Promise<DeviceObservation>;
     /**
-     * Dump + serialize the uiautomator a11y tree. Any failure (dump retries
-     * exhausted, parse error) degrades to an empty tree so the backend falls back
-     * to the vision path — a missing tree must never abort the observation.
+     * Dump + serialize the uiautomator a11y tree. Returns the serialized tree, the
+     * node map, the FLAT parsed nodes (for the screen signature) and the
+     * foreground package read off the dump. Any failure (dump retries exhausted,
+     * parse error) degrades to an empty tree so the backend falls back to the
+     * vision path — a missing tree must never abort the observation.
      */
     private dumpTree;
     captureScreenshot(): Promise<string>;

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

@@ -19,10 +19,11 @@
  *   - Vision path: px = round(x / 1000 * screencapWidth); same for y.
  */
 import { resolveTextValue } from "./actions.js";
-import { requireOneDevice, screencapPng, pngDimensions, dumpUiautomatorXml, inputTap, inputSwipe, inputDrag, inputLongPress, setUserRotation, forceStop, launchApp, installApk, isPackageInstalled, listPackages, isAdbKeyboardInstalled, enableAdbKeyboard, setIme, resetIme, currentIme, adbKeyboardType, adbKeyboardClear, pressKeyEvent, statusbarExpand, appBuildFromDevice, ADB_KEYBOARD_PKG, } from "./adb.js";
+import { requireOneDevice, screencapPng, pngDimensions, dumpUiautomatorXml, inputTap, inputSwipe, inputDrag, inputLongPress, setUserRotation, forceStop, launchApp, installApk, isPackageInstalled, listPackages, isAdbKeyboardInstalled, enableAdbKeyboard, setIme, resetIme, currentIme, adbKeyboardType, adbKeyboardClear, pressKeyEvent, statusbarExpand, appBuildFromDevice, currentActivity, ADB_KEYBOARD_PKG, } from "./adb.js";
 import { isLocalPath } from "../upload.js";
 import { deNormalizePoint, deNormalizeDrag } from "./coordinates.js";
-import { parseUiautomatorXml, serializeNativeTree, boundsCenter } from "./native-a11y.js";
+import { parseUiautomatorXml, serializeNativeTree, boundsCenter, androidPackage, } from "./native-a11y.js";
+import { computeScreenSignature } from "./screen-signature.js";
 import { packageNameFromApk } from "./apk-manifest.js";
 // Let animations/IME transitions settle before the next observation so the
 // screenshot the LLM reasons over reflects the action's result.
@@ -175,14 +176,24 @@ export class AndroidDevice {
         return png;
     }
     async observe() {
-        // Screencap and the a11y dump are independent reads — run them in parallel.
-        // The dump is wrapped so a failure degrades to the vision path (empty tree)
-        // rather than aborting the observation.
-        const [png, tree] = await Promise.all([
+        // Screencap, the a11y dump, and the foreground-activity read are independent
+        // — run them in parallel. The dump is wrapped so a failure degrades to the
+        // vision path (empty tree) rather than aborting the observation; the
+        // activity read is best-effort ("" on failure → package-only coarse token).
+        const [png, tree, activity] = await Promise.all([
             this.refreshDimensions(),
             this.dumpTree(),
+            currentActivity(),
         ]);
         this.lastNodeMap = tree.nodeMap;
+        // Scroll-invariant screen signature from this dump's parsed nodes + coarse
+        // inputs (foreground package/activity). Sent only when usable (see loop.ts).
+        const coarseInputs = {
+            platform: "android",
+            package: tree.package,
+            activity,
+        };
+        const screenSignature = computeScreenSignature(tree.nodes, coarseInputs);
         return {
             screenshot: png.toString("base64"),
             // Element path when the dump produced a tree; "" → backend vision branch.
@@ -193,12 +204,19 @@ export class AndroidDevice {
             // Native has no scrollable document; the screen IS the page.
             documentHeight: this.screenHeight,
             tabs: [],
+            screenSignature,
+            // Corpus-dump only (ISH_DUMP_CORPUS): the exact parsed nodes + coarse
+            // inputs the signature consumed, so any algorithm can be replayed offline.
+            nativeNodes: tree.nodes,
+            coarseInputs,
         };
     }
     /**
-     * Dump + serialize the uiautomator a11y tree. Any failure (dump retries
-     * exhausted, parse error) degrades to an empty tree so the backend falls back
-     * to the vision path — a missing tree must never abort the observation.
+     * Dump + serialize the uiautomator a11y tree. Returns the serialized tree, the
+     * node map, the FLAT parsed nodes (for the screen signature) and the
+     * foreground package read off the dump. Any failure (dump retries exhausted,
+     * parse error) degrades to an empty tree so the backend falls back to the
+     * vision path — a missing tree must never abort the observation.
      */
     async dumpTree() {
         try {
@@ -206,12 +224,12 @@ export class AndroidDevice {
             const nodes = parseUiautomatorXml(xml);
             const tree = serializeNativeTree(nodes);
             this.log(`a11y tree: ${tree.nodeMap.size} node(s)`);
-            return tree;
+            return { ...tree, nodes, package: androidPackage(xml) };
         }
         catch (err) {
             const msg = err instanceof Error ? err.message : String(err);
             this.log(`a11y dump failed, falling back to vision: ${msg}`);
-            return { simplified: "", nodeMap: new Map() };
+            return { simplified: "", nodeMap: new Map(), nodes: [], package: "" };
         }
     }
     async captureScreenshot() {

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();
+}