@ishlabs/cli 0.26.1 → 0.27.1

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

@@ -0,0 +1,170 @@
+/**
+ * Native "screen signature" v2 — a SCROLL-INVARIANT structural identity for a
+ * logical native screen, derived from the accessibility tree, sent to the
+ * backend as an entry/cross-run frame anchor (Phase 2 of native frame
+ * continuity; Phase 1 reuses the prior frame on pure scroll/keyboard steps).
+ *
+ * FCIS: this module is PURE (NativeNode[] + coarse inputs in, signature out) —
+ * no device access. The device gathers the coarse inputs (foreground activity /
+ * bundle id) and the parsed tree; this turns them into `{value, usable}`.
+ *
+ * The signature has two parts:
+ *   coarse  — a cheap, almost-always-available anchor (android `package|activity`,
+ *             ios `bundleId|navTitle`).
+ *   tokens  — the persistent CHROME tokens that are NOT scroll content. Each
+ *             chrome node contributes its resource-id (`id:…`) AND its label
+ *             (`tx:…`) when present. This is what makes the signature
+ *             scroll-invariant AND lets two same-activity screens be told apart.
+ *
+ * WHY v2 (two verified gaps in the id-only v1):
+ *  1. LABELS close the shared-chrome OVER-MERGE. A single-Activity app — Jetpack
+ *     Compose (exposes NO resource-ids beyond the framework `android:id/content`)
+ *     or a View app with a fixed toolbar+container shared across fragments —
+ *     gives two DISTINCT screens the SAME id-set → identical signature → SILENT
+ *     over-merge (the cardinal failure). But those screens DO differ in chrome
+ *     LABELS (a home screen vs a settings sub-screen show different toolbar /
+ *     button text). Including labels makes distinct screens produce distinct
+ *     signatures, and makes Compose usable at all (label-only tokens).
+ *  2. STRUCTURAL scroll-exclusion replaces v1's geometric `contains()`. v1
+ *     excluded scroll content by bounds-containment, which (a) mis-flagged an
+ *     overlay/FAB sitting inside a list's rect as content (→ could over-merge),
+ *     and (b) on iOS the scroll CONTAINER is isAccessible=0 and pruned from the
+ *     NativeNode[], so geometric exclusion never fired (scroll changed the
+ *     signature → over-split, feature inert). v2 excludes by TREE STRUCTURE: a
+ *     node is content iff `insideScrollable` (it has a scrollable ANCESTOR),
+ *     computed during parsing — see native-a11y.ts. The scroll container's OWN
+ *     tokens are kept (it's durable chrome; `insideScrollable` is about
+ *     descendants).
+ *
+ * The remaining failure mode after v2 is SAFE: dynamic chrome labels (a live
+ * clock, an unread badge) cause OVER-SPLIT (a new frame), never over-merge — the
+ * backend just mints a fresh frame, which is the conservative direction.
+ *
+ * USABLE GUARD (load-bearing, unchanged in spirit): `usable` is true only with
+ * >= MIN_STABLE_TOKENS tokens. A signature derived from an empty/sparse token
+ * set must NEVER be sent — sha1("") (and any near-empty set) collides across
+ * distinct screens and would silently over-merge them. When unusable the caller
+ * omits the field entirely and the backend falls back to Phase-1 continuity.
+ * This is the SAFE default: Flutter (no a11y tree) and the sparsest screens
+ * degrade here; id-rich Android and label-rich Compose are the validated wins.
+ */
+import { createHash } from "node:crypto";
+/** Minimum stable-chrome tokens for a signature to be usable (sent to the backend). */
+export const MIN_STABLE_TOKENS = 2;
+/**
+ * App-bar / title chrome resource-ids. A node whose resource-id matches carries
+ * the SCREEN TITLE (e.g. a CollapsingToolbar's title, an ActionBar/Toolbar title).
+ * On modern Android the title sits INSIDE the scrollable app-bar (CoordinatorLayout
+ * / NestedScrollView), so structural scroll-exclusion drops it — collapsing every
+ * sub-screen of a single host activity (e.g. Android Settings' `.SubSettings`) to
+ * the SAME generic outer-container ids and silently OVER-MERGING distinct screens
+ * (proven live: Display/Apps/Network all → one frame). We rescue the title LABEL
+ * even when `insideScrollable`: the title text is the screen's most reliable
+ * discriminator and is scroll-INVARIANT (it stays constant as the bar collapses).
+ *
+ * WHY no `_title$` here (removed): a trailing-`_title$` rescue was originally added
+ * to also catch Android `homepage_title`, but (a) `homepage_title` is the VOLATILE
+ * home big-title we deliberately do NOT want to rescue, and (b) `_title$`
+ * OVER-MATCHES iOS list-row section ids that are pure SCROLL CONTENT —
+ * `MOTION_TITLE`, `SPEECH_TITLE`, `LIVE_SPEECH_TITLE`, `VOCAL_SHORTCUTS_TITLE`
+ * (role=text, insideScrollable=true). Rescuing those re-includes scroll-content row
+ * labels in the signature, so scrolling reveals different rows and CHURNS the
+ * signature → over-fragment (iOS Settings/Accessibility split into two frames). The
+ * SubSettings over-merge discriminator rides on the explicitly-matched
+ * `collapsing_toolbar` / `action_bar` / `toolbar`, NOT on an arbitrary `_title$`.
+ */
+const TITLE_CHROME_ID = /(collapsing_toolbar|action_bar|toolbar)$/;
+function isTitleChrome(resourceId) {
+    return resourceId !== "" && TITLE_CHROME_ID.test(resourceId.toLowerCase());
+}
+/** Max length of a label token's value — bounds the hashed string on chatty labels. */
+const LABEL_TOKEN_MAX_LENGTH = 64;
+/**
+ * Normalized role of the iOS navigation bar after `normalizeRole` in
+ * native-a11y.ts (`AXNavigationBar`/`NavigationBar` → "navigationbar"). The
+ * spike matched the raw "NavigationBar" role; the CLI's NativeNode carries the
+ * normalized role, so we match the normalized form here.
+ */
+const IOS_NAV_BAR_ROLE = "navigationbar";
+function sha1(s) {
+    return createHash("sha1").update(s).digest("hex");
+}
+/** First nav-bar node's label (iOS), else "" — best-effort coarse signal. */
+function iosNavTitle(nodes) {
+    const nav = nodes.find((n) => n.role === IOS_NAV_BAR_ROLE);
+    return nav ? nav.label.trim() : "";
+}
+/** The coarse, almost-always-available anchor token. */
+function coarseToken(nodes, coarse) {
+    if (coarse.platform === "android") {
+        return `${coarse.package ?? ""}|${coarse.activity ?? ""}`;
+    }
+    return `${coarse.bundleId ?? ""}|${iosNavTitle(nodes)}`;
+}
+/** Collapse whitespace, lowercase, and cap length so a label token is stable. */
+function normalizeLabelToken(label) {
+    const collapsed = label.replace(/\s+/g, " ").trim().toLowerCase();
+    return collapsed.length <= LABEL_TOKEN_MAX_LENGTH
+        ? collapsed
+        : collapsed.slice(0, LABEL_TOKEN_MAX_LENGTH);
+}
+/**
+ * Sorted, de-duped token set of the persistent CHROME — every node that is NOT
+ * scroll content (`!insideScrollable`). Each such node contributes:
+ *   - `id:<resourceId>`  when its resource-id is non-empty, and
+ *   - `tx:<label>`       when its label is non-empty (normalized).
+ * A scroll CONTAINER's own tokens ARE kept (the container is durable chrome;
+ * `insideScrollable` flags its descendants, not the container). Labels are the
+ * v2 win: they discriminate single-Activity screens that share a chrome id-set
+ * (and give Compose, which exposes no ids, a usable signature at all).
+ */
+function stableTokenSet(nodes) {
+    const out = new Set();
+    for (const n of nodes) {
+        const id = (n.resourceId ?? "").trim();
+        const label = n.label.trim();
+        // App-bar / title chrome carries the screen's name but sits inside the
+        // scrollable app-bar on modern Android — rescue its scroll-invariant LABEL
+        // even when insideScrollable (its generic container id is NOT added; the
+        // label is the discriminator). See TITLE_CHROME_ID.
+        if (label && isTitleChrome(id))
+            out.add(`tx:${normalizeLabelToken(label)}`);
+        if (n.insideScrollable)
+            continue; // scroll content — shifts under a scroll
+        // Suppress the `id:` token for a self-named / generic nav control. On iOS,
+        // parseXcuiHierarchy promotes the WDA `name` to resourceId, but WDA reports a
+        // NON-DETERMINISTIC name for the nav back button — "BackButton" when fresh,
+        // the parent screen's title (e.g. "Settings") once scrolled — while its
+        // visible label stays constant. That churn flips the `id:` token between
+        // scroll states and fragments the same screen. Drop the id when it's the
+        // literal "BackButton" OR is redundant with the node's own label (id ===
+        // normalized label): in both cases the `id:` carries no identity beyond the
+        // already-emitted `tx:` label. We KEEP the `tx:` token below.
+        const redundantNavId = id !== "" &&
+            (id === "BackButton" ||
+                (label !== "" && normalizeLabelToken(id) === normalizeLabelToken(label)));
+        if (id && !redundantNavId)
+            out.add(`id:${id}`);
+        if (label)
+            out.add(`tx:${normalizeLabelToken(label)}`);
+    }
+    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
+ * send (>= MIN_STABLE_TOKENS distinct stable chrome tokens).
+ */
+export function computeScreenSignature(nodes, coarse) {
+    const tokens = stableTokenSet(nodes);
+    const value = `${coarse.platform}|${coarseToken(nodes, coarse)}|${sha1(tokens.join(","))}`;
+    return {
+        value,
+        usable: tokens.length >= MIN_STABLE_TOKENS,
+        tokenCount: tokens.length,
+    };
+}

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>;
@@ -45,6 +59,13 @@ export declare function closeWda(udid: string): Promise<void>;
 export declare function describeScreen(udid: string): Promise<IosScreen>;
 /** Raw WDA `/source?format=json` string — feed to `parseXcuiHierarchy`. */
 export declare function describeAll(udid: string): Promise<string>;
+/**
+ * The foreground app's bundle id via WDA `GET /wda/activeAppInfo`, a coarse
+ * input for the screen signature. Best-effort: returns "" on any failure (the
+ * signature degrades to a bundleId-less coarse token, and the run never depends
+ * on this read).
+ */
+export declare function activeBundleId(udid: string): Promise<string>;
 export declare function uiTap(udid: string, x: number, y: number): Promise<void>;
 export declare function uiLongPress(udid: string, x: number, y: number, durationMs?: number): Promise<void>;
 export declare function uiSwipe(udid: string, x1: number, y1: number, x2: number, y2: number, durationMs?: number): Promise<void>;
@@ -52,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. */

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

@@ -31,8 +31,19 @@ const WDA_BUNDLE_ID = "com.facebook.WebDriverAgentRunner.xctrunner";
 const DEFAULT_PORT = Number(process.env.ISH_WDA_PORT) || 8100;
 /** WDA's XCTest runtime cold-starts slowly; poll /status up to this long. */
 const STARTUP_TIMEOUT_MS = 75_000;
-/** W3C ENTER key (maps the idb HID Return keycode 40 used by ios.ts). */
-const W3C_ENTER = "\uE007"; // idb HID Return (40) -> W3C ENTER
+/**
+ * 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 const WDA_RETURN = "\n";
 const sessions = new Map();
 // ── WDA bundle resolution (fetch is wired in the distribution phase) ──────────
 /** Appium's prebuilt WebDriverAgent simulator release we fetch + pin. */
@@ -178,7 +189,10 @@ export async function ensureWda(udid, opts = {}) {
     const existing = sessions.get(udid);
     if (existing && (await statusOk(existing.port)))
         return existing;
-    const port = DEFAULT_PORT;
+    // Each device gets its own WDA runner on its own port so N pooled simulators
+    // don't collide on 8100. The pool allocates the port and passes it in; the
+    // single-device path falls back to DEFAULT_PORT (8100 / $ISH_WDA_PORT).
+    const port = opts.port ?? DEFAULT_PORT;
     if (!(await statusOk(port))) {
         const app = await resolveWdaBundle();
         await simctlRun(["install", udid, app]);
@@ -211,7 +225,9 @@ async function getSession(udid) {
     const s = sessions.get(udid);
     if (s && (await statusOk(s.port)))
         return s;
-    return ensureWda(udid);
+    // Re-ensure on the SAME port if this device had one (a WDA restart mid-run
+    // must not migrate a pooled device back to DEFAULT_PORT).
+    return ensureWda(udid, s ? { port: s.port } : {});
 }
 /** Tear down the WDA session for `udid` (the runner is left for the next run). */
 export async function closeWda(udid) {
@@ -250,6 +266,22 @@ export async function describeAll(udid) {
     const json = await wdaCall(s.port, "GET", `/session/${s.sessionId}/source?format=json`);
     return JSON.stringify(json);
 }
+/**
+ * The foreground app's bundle id via WDA `GET /wda/activeAppInfo`, a coarse
+ * input for the screen signature. Best-effort: returns "" on any failure (the
+ * signature degrades to a bundleId-less coarse token, and the run never depends
+ * on this read).
+ */
+export async function activeBundleId(udid) {
+    try {
+        const s = await getSession(udid);
+        const v = unwrap(await wdaCall(s.port, "GET", "/wda/activeAppInfo"));
+        return typeof v.bundleId === "string" ? v.bundleId : "";
+    }
+    catch {
+        return "";
+    }
+}
 // ── Gestures (W3C pointer actions; coordinates in POINTS) ────────────────────
 function pointerAction(steps) {
     return {
@@ -291,13 +323,13 @@ export async function uiText(udid, text) {
 }
 /**
  * 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 async function uiKey(udid, keycode) {
     if (keycode !== 40)
         throw new IosError(`unsupported WDA keycode: ${keycode}`);
     const s = await getSession(udid);
-    await wdaCall(s.port, "POST", `/session/${s.sessionId}/wda/keys`, { value: [W3C_ENTER] });
+    await wdaCall(s.port, "POST", `/session/${s.sessionId}/wda/keys`, { value: [WDA_RETURN] });
 }
 /** Re-export so a future ios.ts can drop the simctl HID constant. */
 export const HID_KEY_RETURN = 40;

package/dist/lib/modality.js

@@ -97,8 +97,13 @@ export function iterationHasContent(details, modality) {
         const ep = readExternalChatbotEndpoint(details);
         return !!ep.endpoint || !!ep.chatbot_endpoint_id;
     }
-    // interactive (default)
-    return typeof d.url === "string" && d.url.length > 0;
+    // interactive (default): browser/figma iterations carry a `url`; native
+    // (ios/android) iterations carry an `app_artifact` instead and need no URL
+    // (the backend made url optional for native — ish-backend 9708e06e). Either
+    // satisfies "has content".
+    const hasUrl = typeof d.url === "string" && d.url.length > 0;
+    const hasApp = typeof d.app_artifact === "string" && d.app_artifact.length > 0;
+    return hasUrl || hasApp;
 }
 /** The flag fragment a user should pass to populate content for a given modality. */
 export function describeRequiredContentFlag(modality, chatMode) {

package/dist/lib/paths.d.ts

@@ -27,3 +27,4 @@ export declare function wdaVersionFile(): string;
  */
 export declare function adbBin(): string;
 export declare function connectLockPath(): string;
+export declare function devicePoolLockPath(): string;

package/dist/lib/paths.js

@@ -58,3 +58,6 @@ export function adbBin() {
 export function connectLockPath() {
     return path.join(rootDir(), "connect.lock");
 }
+export function devicePoolLockPath() {
+    return path.join(rootDir(), "device-pool.lock");
+}

package/dist/lib/skill-content.js

@@ -230,8 +230,11 @@ To hand a study to someone **without an ish account** — a prospect, a stakehol
 - **\`ish person create\` accepts inline flags** (mirrors \`person update\`): the file-only API (\`--file <path>\`) is preserved as an escape hatch but the common path is \`ish person create --name "X" --type ai --country US ...\` — \`--type\` defaults to \`ai\` when \`--file\` is omitted. See \`ish person create --help\` for the full inline-flag set including \`--household\` (MECE rule applies) and \`--accessibility-profile\`.
 - **\`ish status\` now surfaces \`chat_endpoint\`** alongside \`workspace\`/\`study\`/\`ask\`. Stale or orphan active refs get a \`warning\` + \`hint\` field on the affected ref (instead of silently dropping the \`name\`). On \`workspace use <other>\`, the CLI cascade-clears \`study\`/\`ask\`/\`chat_endpoint\` (they belong to the previous workspace).
 - **Share link URL host ≠ API host**: \`ish study share\` prints the backend-built \`share_url\` (the web frontend host). Use it verbatim — never reconstruct the URL from the API host or app URL; they differ. \`ish study unshare\` takes the **raw token** (from \`study share\` / \`study share --list\`), not a study id or alias.
-- **Native app iterations (ios/android) name the app, not a URL**: \`ish iteration create --platform ios --app <bundle-id>\` stores the target as \`app_artifact\` (no URL). The iteration remembers it, so \`ish study run --local\` needs **no \`--app\` on reruns** (it defaults from the iteration). Pass \`--app <path-to.app|.apk>\` only to override with a fresh local build. \`--app\` is optional at create time (omit it for "chosen at run time"). Only \`browser\`/\`figma\` iterations require \`--url\`.
-- **Local runs have no server-side screenshots**: \`ish study run --local\` (including ios/android) writes a per-step HTML debug report to \`~/.ish/debug/sim-*.html\` (path printed at the end of the run) instead of pushing screenshots to the server. \`ish study screenshots list\` on a local-only study finds none — open the debug report instead.
+- **Native app iterations (ios/android) name the app, not a URL**: \`ish iteration create --platform ios --app <bundle-id>\` stores the target as \`app_artifact\` (no URL). \`screen_format\` defaults to **mobile_portrait** for native (vs desktop for browser). The iteration remembers it, so \`ish study run --local\` needs **no \`--app\` on reruns** (it defaults from the iteration). Pass \`--app <path-to.app|.apk>\` only to override with a fresh local build. \`--app\` is optional at create time (omit it for "chosen at run time"). Only \`browser\`/\`figma\` iterations require \`--url\`. Full walkthrough: \`ish docs get-page guides/native-app\`.
+- **Native runs reset state per participant only with a local .app**: with a local \`.app\`/\`.apk\` the runner uninstall+reinstalls before each participant (no state leak). A bare bundle-id / system app (e.g. \`com.apple.reminders\`) can't be reinstalled — it relaunches and warns once that earlier-participant state may persist; pass \`--app <.app>\` or run one participant per study for a clean start.
+- **Parallel native runs**: \`ish study run --local --platform ios|android --parallel N\` drives a **pool of N devices** (iOS: reuses booted simulators + auto-creates the shortfall; Android: reuses online emulators + auto-launches headless emulators from your AVDs), one participant per device, and tears down only what it started. N auto-sizes to host RAM; default 1, max 5 — small machines run fewer + queue, never error. Android needs just **one AVD** (the pool clones it via file-copy — no JDK — and deletes the clones). Browser \`--parallel\` is unchanged.
+- **Local runs still capture per-interaction screenshots**: \`ish study run --local\` (including ios/android) does NOT populate the remote frame-grouped index (\`ish study screenshots list\` reads that and won't show local frames), but per-interaction screenshots ARE captured — read them via \`ish study get <id>\` (each interaction carries \`screenshot_url\`) or the per-step HTML debug report at \`~/.ish/debug/sim-*.html\` (path printed at the end of the run).
+- **\`<entity> use --json\` is capturable**: \`study use\`/\`workspace use\`/\`ask use\` print the human confirmation to stderr and an \`{id, alias, name, active}\` object to stdout under \`--json\`, so \`ish study use s-… --json --get alias\` works.
 
 ## When in doubt
 

package/dist/lib/upload.d.ts

@@ -16,6 +16,14 @@ export declare function validateFile(filePath: string): Promise<{
     size: number;
     mime: string;
 }>;
+/**
+ * Upload raw bytes to Supabase Storage via the backend's signed URL flow.
+ * Returns the public content_url. The bytes-level core shared by file uploads
+ * and HTML image archiving (no temp file needed).
+ */
+export declare function uploadStudyContentBytes(client: ApiClient, studyId: string, data: Buffer, mime: string, name: string, opts?: {
+    quiet?: boolean;
+}): Promise<string>;
 /**
  * Upload a local file to Supabase Storage via the backend's signed URL flow.
  * Returns the public content_url for use in iteration details.
@@ -40,6 +48,25 @@ export declare function resolveContentUrls(client: ApiClient, studyId: string, c
     mimeTypeOverride?: string;
     quiet?: boolean;
 }): Promise<string[]>;
+/**
+ * Archive every external `<img>` in a text iteration's `content_html` onto the
+ * workspace storage origin, rewriting each `src` to the uploaded URL.
+ *
+ * Why: the render-to-image worker that lets a participant SEE the page
+ * default-denies egress to every origin except workspace storage (SSRF guard).
+ * An `<img>` pointing at the open web is therefore aborted and renders broken.
+ * The frontend's paste pipeline (`cacheHtmlAssets`) already archives images;
+ * this is the CLI-side equivalent so `ish iteration create --content-html`
+ * produces content whose images actually render. It is a focused subset (just
+ * `<img src>` via regex — the CLI has no HTML-parser dependency); inline
+ * `data:` images, relative paths, and non-image responses are left untouched.
+ *
+ * Best-effort: a single image that cannot be fetched/uploaded is left as-is
+ * with a warning rather than failing the whole create.
+ */
+export declare function archiveHtmlImages(client: ApiClient, studyId: string, html: string, opts?: {
+    quiet?: boolean;
+}): Promise<string>;
 /**
  * Resolve text content. If the value starts with '@', read the file at
  * the path that follows (curl-style convention). Otherwise return as-is.