@ishlabs/cli 0.27.0 → 0.27.1

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

@@ -5,9 +5,6 @@
  */
 import { existsSync } from "node:fs";
 import { chromium } from "playwright-core";
-// Deep-import the bundled registry so this works in both the npm-install path
-// and the standalone bun binary (which has no `npx` to spawn).
-import { registry } from "playwright-core/lib/server/registry/index";
 // playwright-core's userAgent module does `require("../../../package.json")`
 // at runtime to read its version. bun's --compile bundler is unreliable about
 // embedding that JSON, which causes install to crash in the standalone binary
@@ -17,6 +14,13 @@ import { registry } from "playwright-core/lib/server/registry/index";
 // Keep this string in sync with the playwright-core dep in package.json. It
 // only feeds the User-Agent string sent to download CDN, so a slight mismatch
 // is harmless.
+//
+// package.json pins playwright-core EXACTLY (no ^) because this module's
+// registry deep import and scripts/patch-playwright-core.mjs both depend on
+// playwright-core internals that change between minor versions — 1.60.0
+// removed `./lib/server/registry/index` from the exports map, which broke
+// every fresh `npm install @ishlabs/cli` while CI (lockfile-pinned to 1.59.1)
+// stayed green. Bump the pin and this constant together, deliberately.
 const PLAYWRIGHT_CORE_VERSION = "1.59.1";
 if (!process.env.PW_VERSION_OVERRIDE) {
     process.env.PW_VERSION_OVERRIDE = PLAYWRIGHT_CORE_VERSION;
@@ -34,6 +38,22 @@ export async function installBrowser(quiet = false) {
     const log = (msg) => { if (!quiet)
         console.error(msg); };
     log("Installing Chromium for local simulations (~120 MB)...");
+    // Deep-import the bundled registry so this works in both the npm-install
+    // path and the standalone bun binary (which has no `npx` to spawn). The
+    // import is lazy — `playwright-core/lib/server/registry/index` is not a
+    // semver-stable subpath (1.60.0 dropped it from the exports map), so a
+    // top-level import would make this whole module unloadable and take
+    // `isBrowserInstalled()` / doctor down with it.
+    let registry;
+    try {
+        ({ registry } = await import("playwright-core/lib/server/registry/index"));
+    }
+    catch (err) {
+        const detail = err instanceof Error ? err.message : String(err);
+        throw new Error(`Failed to load the Playwright browser installer (${detail}). ` +
+            `The installed playwright-core version is incompatible with this CLI — ` +
+            `expected ${PLAYWRIGHT_CORE_VERSION}. Reinstall the CLI to fix.`);
+    }
     try {
         const executables = registry.resolveBrowsers(["chromium"], {});
         await registry.install(executables, { force: false });

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

@@ -37,16 +37,41 @@ export interface IosDeviceOptions {
     bundleId?: string;
     /** Local .app path to install before the run, or a bundle id to launch. */
     appPath?: string;
+    /** Simulator udid to drive. When set (pooled/parallel run), skip booted-sim discovery. */
+    udid?: string;
+    /** WDA port for THIS device. When set, the runner binds it instead of DEFAULT_PORT (concurrent pool). */
+    wdaPort?: number;
     contextValues: ContextValue[];
     log?: (msg: string) => void;
 }
+/**
+ * The run-up-front caveat for native state reset, or null when none is needed.
+ *
+ * A terminate+relaunch does NOT clear app data, so state one participant creates
+ * (a reminder, a saved record) can leak into the next. When we hold an
+ * installable `.app` the runner uninstall+reinstalls per participant (clean), so
+ * no warning is needed. A bare bundle-id / system app (e.g.
+ * `com.apple.reminders`) can't be reinstalled — so for a multi-participant run
+ * against one, warn that state may persist. A single-participant run has nothing
+ * to leak into, so it stays quiet.
+ *
+ * Lives here (not on the per-participant IOSDevice, which is recreated each
+ * participant) because the decision needs the run-scoped cohort size — the loop
+ * owns that. Pure + exported so it can be unit-tested without a simulator.
+ *
+ * @param reinstallable    true when the target is a local `.app`/`.apk` we reinstall
+ * @param participantCount number of participants in this run
+ */
+export declare function nativeStateResetWarning(reinstallable: boolean, participantCount: number): string | null;
 export declare class IOSDevice implements SimulationDevice {
     private readonly contextValues;
     private readonly log;
     private bundleId;
     private readonly appPath;
-    /** udid of the single booted simulator we drive. */
+    /** udid of the simulator we drive. Set from opts (pooled) or discovered (single-device). */
     private udid;
+    /** WDA port for this device when pooled; undefined → DEFAULT_PORT (single-device). */
+    private readonly wdaPort;
     /** Set once the WebDriverAgent runner is up, so the startup note logs once. */
     private wdaStarted;
     /** POINT size — what idb ui tap/swipe consume (de-normalization basis for TAPS). */

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

@@ -31,7 +31,7 @@
  *   backend never converts coords with screen_width/height.
  */
 import { resolveTextValue } from "./actions.js";
-import { requireOneBootedSimulator, screenshotPng, terminateApp, launchApp, installApp, isAppInstalled, bundleIdFromApp, appBuildFromSimulator, } from "./simctl.js";
+import { requireOneBootedSimulator, screenshotPng, terminateApp, launchApp, installApp, uninstallApp, isAppInstalled, bundleIdFromApp, appBuildFromSimulator, } from "./simctl.js";
 // iOS UI interaction + a11y run through WebDriverAgent (XCUITest), not idb.
 import { ensureWda, closeWda, describeScreen, describeAll, activeBundleId, uiTap, uiLongPress, uiSwipe, uiText, uiKey, HID_KEY_RETURN, } from "./xcuitest.js";
 import { isLocalPath } from "../upload.js";
@@ -58,13 +58,42 @@ const NON_BACK_LEADING_LABELS = new Set([
 async function settle(ms = POST_GESTURE_SETTLE_MS) {
     await new Promise((r) => setTimeout(r, ms));
 }
+/**
+ * The run-up-front caveat for native state reset, or null when none is needed.
+ *
+ * A terminate+relaunch does NOT clear app data, so state one participant creates
+ * (a reminder, a saved record) can leak into the next. When we hold an
+ * installable `.app` the runner uninstall+reinstalls per participant (clean), so
+ * no warning is needed. A bare bundle-id / system app (e.g.
+ * `com.apple.reminders`) can't be reinstalled — so for a multi-participant run
+ * against one, warn that state may persist. A single-participant run has nothing
+ * to leak into, so it stays quiet.
+ *
+ * Lives here (not on the per-participant IOSDevice, which is recreated each
+ * participant) because the decision needs the run-scoped cohort size — the loop
+ * owns that. Pure + exported so it can be unit-tested without a simulator.
+ *
+ * @param reinstallable    true when the target is a local `.app`/`.apk` we reinstall
+ * @param participantCount number of participants in this run
+ */
+export function nativeStateResetWarning(reinstallable, participantCount) {
+    if (reinstallable || participantCount <= 1)
+        return null;
+    return ("Note: app data is NOT reset between participants — the target is an installed " +
+        "bundle id (e.g. a system app), which can't be reinstalled, so state an earlier " +
+        "participant creates may persist into the next and skew results. Pass " +
+        "--app <path-to.app> to enable a clean reinstall per participant, or run one " +
+        "participant per study for a guaranteed clean start.");
+}
 export class IOSDevice {
     contextValues;
     log;
     bundleId;
     appPath;
-    /** udid of the single booted simulator we drive. */
+    /** udid of the simulator we drive. Set from opts (pooled) or discovered (single-device). */
     udid = "";
+    /** WDA port for this device when pooled; undefined → DEFAULT_PORT (single-device). */
+    wdaPort;
     /** Set once the WebDriverAgent runner is up, so the startup note logs once. */
     wdaStarted = false;
     /** POINT size — what idb ui tap/swipe consume (de-normalization basis for TAPS). */
@@ -91,9 +120,13 @@ export class IOSDevice {
         this.log = opts.log ?? (() => { });
         this.bundleId = opts.bundleId ?? null;
         this.appPath = opts.appPath;
+        this.udid = opts.udid ?? "";
+        this.wdaPort = opts.wdaPort;
     }
     async launchOrReset(target) {
-        this.udid = await requireOneBootedSimulator();
+        // Pooled/parallel runs pin a udid via opts; the single-device path discovers
+        // the one booted simulator (and still rejects >1, preserving today's UX).
+        this.udid = this.udid || (await requireOneBootedSimulator());
         // First call: install the .app (if --app is a local path) and resolve the
         // bundle id to terminate/relaunch on. `target` is the iteration's platform
         // target (a bundle id) when no --app is supplied. Throws (rather than
@@ -108,11 +141,15 @@ export class IOSDevice {
         if (!this.wdaStarted) {
             this.log("Starting the iOS automation runner (WebDriverAgent); first launch can take ~30-60s...");
         }
-        await ensureWda(this.udid);
+        await ensureWda(this.udid, { port: this.wdaPort });
         this.wdaStarted = true;
         // Prime screen geometry (points) before the first de-normalization.
         await this.refreshScreen();
-        // Per-participant reset: terminate then relaunch from a clean state.
+        // Per-participant reset: terminate then relaunch. For a local .app target,
+        // resolveBundleId (above) already uninstall+reinstalled this fresh device's
+        // app, so each participant starts from clean data. A bundle-id / system-app
+        // target can't be reinstalled — runLocalSimulations warns once up front that
+        // its state may persist between participants (see nativeStateResetWarning).
         await terminateApp(this.udid, bundleId);
         await launchApp(this.udid, bundleId);
         await settle(1500); // cold start needs longer than a gesture settle
@@ -156,7 +193,10 @@ export class IOSDevice {
                 throw new Error(`Could not read CFBundleIdentifier from "${appSpec}/Info.plist". ` +
                     `Pass --app <bundle.id> explicitly if the .app layout is unusual.`);
             }
-            this.log(`Installing ${appSpec} (${id})...`);
+            // Uninstall first so a build left over from a prior run doesn't carry its
+            // data into participant 0 — installApp alone preserves the data container.
+            this.log(`Installing a clean build of ${appSpec} (${id})...`);
+            await uninstallApp(this.udid, id);
             await installApp(this.udid, appSpec);
             return id;
         }
@@ -183,7 +223,7 @@ export class IOSDevice {
         // failure → the navTitle-only coarse token).
         await this.refreshScreen();
         const [png, tree, bundleId] = await Promise.all([
-            screenshotPng(),
+            screenshotPng(this.udid),
             this.dumpTree(),
             activeBundleId(this.udid),
         ]);
@@ -238,14 +278,14 @@ export class IOSDevice {
         }
     }
     async captureScreenshot() {
-        const png = await screenshotPng();
+        const png = await screenshotPng(this.udid);
         return png.toString("base64");
     }
     async captureScreenshotJpeg() {
         // simctl screenshot only emits PNG. We return the PNG bytes; the upload/
         // record path treats them as opaque image bytes (PDQ frame-matching works
         // on PNG). The loop labels native uploads image/png.
-        return screenshotPng();
+        return screenshotPng(this.udid);
     }
     dimensions() {
         // PIXELS — the space the loop re-normalizes the recorded coord against.
@@ -549,7 +589,7 @@ export class IOSDevice {
      * success:true (the gesture was attempted); the loud log is the signal.
      */
     async openSystemPanel(panel) {
-        const before = await screenshotPng();
+        const before = await screenshotPng(this.udid);
         const w = this.pointWidth;
         const h = this.pointHeight;
         // Start ON the top edge and travel a third of the screen down. Control
@@ -562,7 +602,7 @@ export class IOSDevice {
         await settle();
         // Loudly surface a no-op: the simulator's synthetic touch often can't drive
         // the system edge gesture. An identical screenshot means the panel didn't open.
-        const after = await screenshotPng();
+        const after = await screenshotPng(this.udid);
         if (before.equals(after)) {
             this.log(`open_system_panel (${panel}): top-edge swipe produced no visible change — ` +
                 `the simulator's synthetic touch likely didn't trigger the system gesture (flaky on the simulator).`);

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

@@ -10,6 +10,10 @@ import { launchSharedBrowser, FULL_PAGE_HEIGHT_CAP_PX_MOBILE, FULL_PAGE_HEIGHT_C
 import { uploadScreenshot } from "./upload.js";
 import { detectNoVisibleChange, describeAction, classifyStepKind } from "./actions.js";
 import { createDevice } from "./device.js";
+import { nativeStateResetWarning } from "./ios.js";
+import { provisionDevicePool, maxConcurrentDevices, totalMemBytes, PER_DEVICE_MB, } from "./device-pool.js";
+import { listOnlineSerials } from "./adb.js";
+import { listAvds } from "./emulator.js";
 import pkg from "../../../package.json" with { type: "json" };
 import { enableDebug, isDebugEnabled, debugRawResponse, debugNormalizedActions, debugActionExecution, debugForwards, debugStepSummary, debugRecord, } from "./debug.js";
 /**
@@ -214,13 +218,59 @@ export async function runLocalSimulations(client, opts) {
         log("\nCancelling after current step...");
     };
     process.on("SIGINT", onSigint);
-    // Native runs share ONE physical device (emulator / simulator), so they
-    // can't run in parallel — force sequential regardless of --parallel.
     const isNativeRun = isNativePlatform(opts.platform);
-    if (isNativeRun && (opts.parallel ?? 1) > 1) {
-        log("Native (android/ios) runs drive a single device — running sequentially.");
+    const requested = opts.parallel ?? opts.participantIds.length;
+    // Native (iOS + Android) can drive a POOL of devices concurrently, auto-sized
+    // to the host's RAM (and, for Android, the number of AVDs) so a small machine
+    // just runs fewer in parallel + queues the rest — never errors. Browser uses
+    // the requested parallelism directly.
+    const NATIVE_PARALLEL_MAX = 5;
+    const nativeParallel = isNativeRun && requested > 1 && opts.participantIds.length > 1;
+    let concurrency;
+    if (nativeParallel) {
+        const cap = Math.min(requested, opts.participantIds.length, NATIVE_PARALLEL_MAX);
+        if (opts.platform === "android") {
+            // Bound by AVDs we can launch + emulators already online.
+            let slots = cap;
+            try {
+                const [avds, online] = await Promise.all([listAvds(), listOnlineSerials()]);
+                slots = avds.length + online.length;
+            }
+            catch {
+                /* fall back to cap if the toolchain query fails */
+            }
+            concurrency = maxConcurrentDevices({
+                totalMemBytes: totalMemBytes(),
+                perDeviceMb: PER_DEVICE_MB.android,
+                requested: cap,
+                deviceCount: Math.max(1, slots),
+            });
+        }
+        else {
+            concurrency = maxConcurrentDevices({
+                totalMemBytes: totalMemBytes(),
+                perDeviceMb: PER_DEVICE_MB.ios,
+                requested: cap,
+            });
+        }
+    }
+    else {
+        if (isNativeRun && requested > 1) {
+            log("Native parallel needs --parallel >1 and >1 participant; running sequentially.");
+        }
+        concurrency = isNativeRun ? 1 : requested;
+    }
+    // iOS: a bundle-id / system-app target can't be reinstalled, so its data
+    // isn't cleared between participants (a local .app IS reinstalled per
+    // participant — see ios.ts resolveBundleId). Warn once up front when that
+    // could skew a multi-participant run. (--app .app ⇒ reinstallable; a bundle id
+    // from --app or the iteration's app_artifact ⇒ not.)
+    if (opts.platform === "ios") {
+        const reinstallable = !!opts.appPath?.toLowerCase().endsWith(".app");
+        const warning = nativeStateResetWarning(reinstallable, opts.participantIds.length);
+        if (warning)
+            log(warning);
     }
-    const concurrency = isNativeRun ? 1 : (opts.parallel ?? opts.participantIds.length);
     // Native runs stamp the app build onto the iteration once — every
     // participant in a run drives the same installed build, so dedupe to a
     // single best-effort POST after the first device resolves its app.
@@ -231,6 +281,15 @@ export async function runLocalSimulations(client, opts) {
         appBuildReported = true;
         void reportObservedApp(client, opts.iterationId, platform, build, log);
     };
+    // With a device pool, N workers would each read the app build (a redundant
+    // simctl listapps / dumpsys per device). Let only the first worker do it.
+    let appBuildClaimed = false;
+    const claimAppBuild = () => {
+        if (appBuildClaimed)
+            return false;
+        appBuildClaimed = true;
+        return true;
+    };
     try {
         if (concurrency <= 1 || opts.participantIds.length <= 1) {
             // Sequential execution — each participant owns its own browser
@@ -250,6 +309,47 @@ export async function runLocalSimulations(client, opts) {
                 }
             }
         }
+        else if (nativeParallel) {
+            // Native device pool — N simulators/emulators, one participant per device.
+            const deviceWord = opts.platform === "ios" ? "simulator" : "emulator";
+            // nativeParallel ⇒ opts.platform is "ios" | "android" (isNativePlatform true).
+            const pool = await provisionDevicePool({ platform: opts.platform, size: concurrency, log });
+            try {
+                const poolN = pool.devices.length;
+                log(`\nRunning ${opts.participantIds.length} ${opts.platform} simulations across a pool of ` +
+                    `${poolN} ${deviceWord}${poolN === 1 ? "" : "s"}` +
+                    (poolN < Math.min(requested, opts.participantIds.length, NATIVE_PARALLEL_MAX)
+                        ? " (auto-sized to fit this machine)"
+                        : "") +
+                    "...");
+                // Launch all participants; each awaits a free device, so actual
+                // concurrency is bounded by the pool size. A finished worker releases
+                // its device to the next in line.
+                const runOne = async (participantId) => {
+                    if (cancelled)
+                        return;
+                    const participantName = opts.participantNames.get(participantId) ?? participantId;
+                    const participantLog = (msg) => log(`[${participantName}] ${msg}`);
+                    const device = await pool.claim();
+                    try {
+                        participantLog(`Starting on ${deviceWord} ${device.id}`);
+                        await runSingleSimulation(client, participantId, participantName, opts, participantLog, () => cancelled, reportAppBuild, undefined, device, claimAppBuild);
+                        log(`Completed: ${participantName}`);
+                    }
+                    catch (err) {
+                        const msg = err instanceof Error ? err.message : String(err);
+                        log(`Failed: ${participantName} — ${msg}`);
+                    }
+                    finally {
+                        pool.release(device);
+                    }
+                };
+                await Promise.allSettled(opts.participantIds.map(runOne));
+            }
+            finally {
+                await pool.teardown();
+            }
+        }
         else {
             // Parallel execution — shared browser, one tab per participant
             log(`\nRunning ${opts.participantIds.length} simulations in parallel (concurrency: ${concurrency})...`);
@@ -295,7 +395,7 @@ export async function runLocalSimulations(client, opts) {
         process.off("SIGINT", onSigint);
     }
 }
-async function runSingleSimulation(client, participantId, participantName, opts, log, isCancelled, onAppBuild, sharedBrowser) {
+async function runSingleSimulation(client, participantId, participantName, opts, log, isCancelled, onAppBuild, sharedBrowser, pooledDevice, claimAppBuild) {
     // Step 1: Initialize session
     const initResponse = await client.localSimInit({
         participant_id: participantId,
@@ -353,6 +453,8 @@ async function runSingleSimulation(client, participantId, participantName, opts,
         contextValues: session.context_values,
         sharedBrowser,
         appPath: opts.appPath,
+        deviceId: pooledDevice?.id,
+        wdaPort: pooledDevice?.wdaPort,
         log,
     });
     const history = [];
@@ -367,9 +469,10 @@ async function runSingleSimulation(client, participantId, participantName, opts,
         // Step 3: Launch / navigate the target to its starting point.
         await device.launchOrReset(launchTarget);
         // Step 3b: Capture the installed app's build (native only). Best-effort —
-        // the dedupe in runLocalSimulations keeps this to one POST per run, and a
-        // failed read or report never disturbs the simulation.
-        if (onAppBuild) {
+        // the dedupe in runLocalSimulations keeps this to one POST per run. With a
+        // device pool, only the worker that wins claimAppBuild() reads it (one
+        // simctl/dumpsys read total, not one per device).
+        if (onAppBuild && (!claimAppBuild || claimAppBuild())) {
             try {
                 const observed = await device.appBuild?.();
                 if (observed)

package/dist/lib/local-sim/screen-signature.js

@@ -150,6 +150,10 @@ function stableTokenSet(nodes) {
     }
     return [...out].sort();
 }
+// EXPERIMENT: native-consensus-rescue (REVERTED) — a stateful consensus-rescue layer on top of
+// this single-compute signature nets only -2 frag/220 but adds 8 real over-merges. Canonical
+// record: ish-backend docs/experiments/native-consensus-rescue/README.md (stub in docs/experiments/
+// here). Don't re-litigate stateful identity without reading it.
 /**
  * Compute the screen signature from this step's parsed tree + coarse inputs.
  * `value` is `platform|coarse|sha1(tokens)`; `usable` gates whether it's safe to

package/dist/lib/local-sim/simctl-provision.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Simulator provisioning primitives (boot / clone / shutdown / delete) used by
+ * the device pool to stand up N iOS simulators for a parallel run and tear down
+ * the ones it created. Kept separate from simctl.ts (the per-device drive layer)
+ * so the lifecycle module stays lean.
+ *
+ * All of these are thin wrappers over `xcrun simctl`. The pool, not this module,
+ * decides WHICH devices to clone/boot and tracks ownership for teardown.
+ */
+export interface SimDevice {
+    udid: string;
+    name: string;
+    /** "Booted" | "Shutdown" | "Creating" | … */
+    state: string;
+    /** e.g. com.apple.CoreSimulator.SimDeviceType.iPhone-16 */
+    deviceTypeId?: string;
+    /** runtime identifier the device lives under, e.g. com.apple.CoreSimulator.SimRuntime.iOS-18-2 */
+    runtime: string;
+}
+/**
+ * Every device across all runtimes (not just booted), with its runtime folded
+ * in from the grouping key. Unavailable devices (missing runtime) are dropped.
+ */
+export declare function listAllDevices(): Promise<SimDevice[]>;
+/** Booted devices only (convenience over listAllDevices). */
+export declare function listBootedDevices(): Promise<SimDevice[]>;
+/**
+ * Create a fresh simulator of the given device type + runtime and return its
+ * udid. Unlike `clone`, `create` works regardless of the source's state (clone
+ * refuses while the source is Booted, which it always is when we're reusing it
+ * as device 0). A created device is clean — the per-participant app install
+ * (IOSDevice.resolveBundleId) and WDA install (ensureWda) populate it.
+ */
+export declare function createSimulator(name: string, deviceTypeId: string, runtime: string): Promise<string>;
+/**
+ * Clone a SHUTDOWN simulator (carries installed apps; faster than create). Not
+ * used by the pool today because the reuse source is booted — kept for callers
+ * that hold a shut-down source.
+ */
+export declare function cloneDevice(sourceUdid: string, name: string): Promise<string>;
+/**
+ * Boot a simulator and wait until it's fully booted. `bootstatus -b` boots the
+ * device if needed and blocks until ready, so it's a one-shot "boot and wait".
+ */
+export declare function bootDevice(udid: string): Promise<void>;
+/** Power down a simulator. Tolerant of an already-shutdown device. */
+export declare function shutdownDevice(udid: string): Promise<void>;
+/** Delete a (cloned, disposable) simulator. Shut it down first if needed. */
+export declare function deleteDevice(udid: string): Promise<void>;

package/dist/lib/local-sim/simctl-provision.js

@@ -0,0 +1,89 @@
+/**
+ * Simulator provisioning primitives (boot / clone / shutdown / delete) used by
+ * the device pool to stand up N iOS simulators for a parallel run and tear down
+ * the ones it created. Kept separate from simctl.ts (the per-device drive layer)
+ * so the lifecycle module stays lean.
+ *
+ * All of these are thin wrappers over `xcrun simctl`. The pool, not this module,
+ * decides WHICH devices to clone/boot and tracks ownership for teardown.
+ */
+import { simctl, IosError } from "./simctl.js";
+/**
+ * Every device across all runtimes (not just booted), with its runtime folded
+ * in from the grouping key. Unavailable devices (missing runtime) are dropped.
+ */
+export async function listAllDevices() {
+    const out = await simctl(["list", "devices", "-j"], 30_000);
+    let parsed;
+    try {
+        parsed = JSON.parse(out);
+    }
+    catch {
+        throw new IosError("Could not parse `simctl list devices -j` output.");
+    }
+    const rows = [];
+    for (const [runtime, devices] of Object.entries(parsed.devices ?? {})) {
+        for (const d of devices) {
+            if (d.isAvailable === false)
+                continue;
+            rows.push({
+                udid: d.udid,
+                name: d.name,
+                state: d.state,
+                deviceTypeId: d.deviceTypeIdentifier,
+                runtime,
+            });
+        }
+    }
+    return rows;
+}
+/** Booted devices only (convenience over listAllDevices). */
+export async function listBootedDevices() {
+    return (await listAllDevices()).filter((d) => d.state === "Booted");
+}
+/**
+ * Create a fresh simulator of the given device type + runtime and return its
+ * udid. Unlike `clone`, `create` works regardless of the source's state (clone
+ * refuses while the source is Booted, which it always is when we're reusing it
+ * as device 0). A created device is clean — the per-participant app install
+ * (IOSDevice.resolveBundleId) and WDA install (ensureWda) populate it.
+ */
+export async function createSimulator(name, deviceTypeId, runtime) {
+    const out = await simctl(["create", name, deviceTypeId, runtime], 120_000);
+    const udid = out.trim();
+    if (!/^[0-9A-Fa-f-]{36}$/.test(udid)) {
+        throw new IosError(`simctl create did not return a udid (got: ${udid.slice(0, 80)})`);
+    }
+    return udid;
+}
+/**
+ * Clone a SHUTDOWN simulator (carries installed apps; faster than create). Not
+ * used by the pool today because the reuse source is booted — kept for callers
+ * that hold a shut-down source.
+ */
+export async function cloneDevice(sourceUdid, name) {
+    const out = await simctl(["clone", sourceUdid, name], 120_000);
+    const udid = out.trim();
+    if (!/^[0-9A-Fa-f-]{36}$/.test(udid)) {
+        throw new IosError(`simctl clone did not return a udid (got: ${udid.slice(0, 80)})`);
+    }
+    return udid;
+}
+/**
+ * Boot a simulator and wait until it's fully booted. `bootstatus -b` boots the
+ * device if needed and blocks until ready, so it's a one-shot "boot and wait".
+ */
+export async function bootDevice(udid) {
+    // `boot` errors if already booted; swallow that, then bootstatus waits.
+    await simctl(["boot", udid], 60_000).catch(() => { });
+    await simctl(["bootstatus", udid, "-b"], 180_000);
+}
+/** Power down a simulator. Tolerant of an already-shutdown device. */
+export async function shutdownDevice(udid) {
+    await simctl(["shutdown", udid], 60_000).catch(() => { });
+}
+/** Delete a (cloned, disposable) simulator. Shut it down first if needed. */
+export async function deleteDevice(udid) {
+    await shutdownDevice(udid);
+    await simctl(["delete", udid], 60_000);
+}

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

@@ -39,14 +39,16 @@ export interface IosScreen {
     density: number;
 }
 /**
- * Capture the booted simulator's screen as PNG bytes via
- * `simctl io booted screenshot`. simctl writes to a file path (no reliable
- * stdout in current Xcode), so we round-trip through a temp file.
+ * Capture a simulator's screen as PNG bytes via `simctl io <udid> screenshot`.
+ * simctl writes to a file path (no reliable stdout in current Xcode), so we
+ * round-trip through a temp file. Targets an explicit udid (not the "booted"
+ * literal) so concurrent pooled devices each screenshot the right simulator.
  */
-export declare function screenshotPng(): Promise<Buffer>;
+export declare function screenshotPng(udid: string): Promise<Buffer>;
 export declare function terminateApp(udid: string, bundleId: string): Promise<void>;
 export declare function launchApp(udid: string, bundleId: string): Promise<void>;
 export declare function installApp(udid: string, appPath: string): Promise<void>;
+export declare function uninstallApp(udid: string, bundleId: string): Promise<void>;
 export declare function isAppInstalled(udid: string, bundleId: string): Promise<boolean>;
 /**
  * Read CFBundleIdentifier from a local `.app`'s Info.plist via `plutil`. Lets us

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

@@ -82,15 +82,16 @@ export async function requireOneBootedSimulator() {
 }
 // --- Screenshot (PIXELS) ---
 /**
- * Capture the booted simulator's screen as PNG bytes via
- * `simctl io booted screenshot`. simctl writes to a file path (no reliable
- * stdout in current Xcode), so we round-trip through a temp file.
+ * Capture a simulator's screen as PNG bytes via `simctl io <udid> screenshot`.
+ * simctl writes to a file path (no reliable stdout in current Xcode), so we
+ * round-trip through a temp file. Targets an explicit udid (not the "booted"
+ * literal) so concurrent pooled devices each screenshot the right simulator.
  */
-export async function screenshotPng() {
+export async function screenshotPng(udid) {
     const dir = await mkdtemp(join(tmpdir(), "ish-ios-shot-"));
     const path = join(dir, "shot.png");
     try {
-        await simctl(["io", "booted", "screenshot", path], SCREENSHOT_TIMEOUT_MS);
+        await simctl(["io", udid, "screenshot", path], SCREENSHOT_TIMEOUT_MS);
         return await readFile(path);
     }
     finally {
@@ -117,6 +118,18 @@ export async function installApp(udid, appPath) {
     // Simulator builds aren't code-signed; `simctl install` just stages the .app.
     await simctl(["install", udid, appPath], 180_000);
 }
+export async function uninstallApp(udid, bundleId) {
+    // Removes the app AND its data container — this is what actually wipes state
+    // between participants (a terminate+relaunch leaves the data store intact).
+    // Uninstalling an app that isn't installed exits non-zero; swallow it so a
+    // first-participant "reset" is a no-op rather than a failure.
+    try {
+        await simctl(["uninstall", udid, bundleId], 60_000);
+    }
+    catch {
+        // not installed — nothing to remove
+    }
+}
 export async function isAppInstalled(udid, bundleId) {
     // `simctl listapps` emits a plist of installed bundles; a substring check on
     // the quoted bundle id is enough to confirm presence.

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

@@ -18,6 +18,19 @@
  * and reuses an already-running runner.
  */
 import { type IosScreen } from "./simctl.js";
+/**
+ * The Return keystroke we feed to WDA's `/wda/keys` for a submit.
+ *
+ * NOT the W3C ENTER code (U+E007): WDA's `/wda/keys` does NOT interpret the
+ * WebDriver special-key PUA codepoints \u2014 it types them LITERALLY. On the
+ * simulator U+E007 renders as a running-shoe emoji, so a submit appended a
+ * stray `\uD83D\uDC5F` to the field (e.g. a search for `Photos` became `Photos\uD83D\uDC5F`,
+ * returning no results and derailing the run) AND never actually submitted.
+ * A plain newline is what WDA's keyboard treats as Return \u2014 it submits
+ * single-line fields and inserts a line break in multiline ones, with no glyph.
+ * Verified on a booted iOS 18 simulator (Settings search).
+ */
+export declare const WDA_RETURN = "\n";
 interface Session {
     port: number;
     baseUrl: string;
@@ -38,6 +51,7 @@ export declare function resolveWdaBundle(): Promise<string>;
  */
 export declare function ensureWda(udid: string, opts?: {
     bundleId?: string;
+    port?: number;
 }): Promise<Session>;
 /** Tear down the WDA session for `udid` (the runner is left for the next run). */
 export declare function closeWda(udid: string): Promise<void>;
@@ -59,7 +73,7 @@ export declare function uiSwipe(udid: string, x1: number, y1: number, x2: number
 export declare function uiText(udid: string, text: string): Promise<void>;
 /**
  * Press a key. Only the idb HID Return keycode (40) is used by ios.ts today;
- * map it to W3C ENTER. Unknown codes are a no-op-safe error.
+ * map it to a newline (see WDA_RETURN). Unknown codes are a no-op-safe error.
  */
 export declare function uiKey(udid: string, keycode: number): Promise<void>;
 /** Re-export so a future ios.ts can drop the simctl HID constant. */