@ishlabs/cli 0.26.1 → 0.27.1

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

@@ -14,6 +14,8 @@
 import type { Browser } from "playwright-core";
 import type { LocalStepAction, LocalSimBrowserOptions, LocalTabInfo, ContextValue } from "./types.js";
 import type { BrowserSession } from "./browser.js";
+import type { ScreenSignature, CoarseInputs } from "./screen-signature.js";
+import type { NativeNode } from "./native-a11y.js";
 /**
  * One observation of the target's current state.
  *
@@ -39,6 +41,29 @@ export interface DeviceObservation {
     documentHeight: number;
     /** Open-tab snapshot (browser-only; empty for native). */
     tabs: LocalTabInfo[];
+    /**
+     * Native only: the scroll-invariant structural "screen signature" computed
+     * from this observation's a11y tree (see screen-signature.ts). The loop sends
+     * `value` as the match-frame anchor ONLY when `usable` is true; browser
+     * targets omit it. Undefined when the platform doesn't compute one.
+     */
+    screenSignature?: ScreenSignature;
+    /**
+     * Native only, corpus-dump only: the PARSED a11y nodes that
+     * `computeScreenSignature` consumed for this observation (the exact array, so
+     * any signature algorithm can be replayed offline against it). Populated by the
+     * android/ios `observe()`; the browser leaves it undefined. Only surfaced for
+     * the `ISH_DUMP_CORPUS` instrumentation in loop.ts — nothing in the live path
+     * reads it.
+     */
+    nativeNodes?: NativeNode[];
+    /**
+     * Native only, corpus-dump only: the `CoarseInputs` (platform / package /
+     * activity / bundleId) fed into `computeScreenSignature` for this observation.
+     * Populated by the android/ios `observe()`; the browser leaves it undefined.
+     * Same instrumentation-only purpose as `nativeNodes`.
+     */
+    coarseInputs?: CoarseInputs;
 }
 /**
  * Result of executing one action against the target.
@@ -158,5 +183,9 @@ export declare function createDevice(platform: string, opts: {
     sharedBrowser?: Browser;
     /** Native: local .apk/.app path to install or a package/bundle id to launch. */
     appPath?: string;
+    /** Native pool: the device to drive — iOS simulator udid or Android adb serial. */
+    deviceId?: string;
+    /** iOS pool: the per-device WDA port. */
+    wdaPort?: number;
     log?: (msg: string) => void;
 }): Promise<SimulationDevice>;

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

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

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

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

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

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

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). */
@@ -86,10 +111,11 @@ export declare class IOSDevice implements SimulationDevice {
     private refreshScreen;
     observe(): Promise<DeviceObservation>;
     /**
-     * Read + serialize WDA's /source a11y tree (bounds in POINTS). Any
-     * failure (retries exhausted on a trivial tree, parse error) degrades to an
-     * empty tree so the backend falls back to vision — a missing tree must never
-     * abort the observation.
+     * Read + serialize WDA's /source a11y tree (bounds in POINTS). Returns the
+     * serialized tree, the node map and the FLAT parsed nodes (for the screen
+     * signature). Any failure (retries exhausted on a trivial tree, parse error)
+     * degrades to an empty tree so the backend falls back to vision — a missing
+     * tree must never abort the observation.
      */
     private dumpTree;
     captureScreenshot(): Promise<string>;

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

@@ -31,12 +31,13 @@
  *   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, uiTap, uiLongPress, uiSwipe, uiText, uiKey, HID_KEY_RETURN, } from "./xcuitest.js";
+import { ensureWda, closeWda, describeScreen, describeAll, activeBundleId, uiTap, uiLongPress, uiSwipe, uiText, uiKey, HID_KEY_RETURN, } from "./xcuitest.js";
 import { isLocalPath } from "../upload.js";
 import { deNormalizePoint, deNormalizeDrag, pointToPixel } from "./coordinates.js";
 import { parseXcuiHierarchy, serializeNativeTree, boundsCenter } from "./native-a11y.js";
+import { computeScreenSignature } from "./screen-signature.js";
 // Let animations/transitions settle before the next observation so the
 // screenshot the LLM reasons over reflects the action's result.
 const POST_GESTURE_SETTLE_MS = 500;
@@ -57,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). */
@@ -90,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
@@ -107,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
@@ -155,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;
         }
@@ -176,14 +217,26 @@ export class IOSDevice {
     }
     async observe() {
         // Refresh geometry each step (orientation can change), then capture the
-        // pixel screenshot and the a11y tree in parallel (independent reads). The
-        // dump is wrapped so a failure degrades to the vision path (empty tree).
+        // pixel screenshot, the a11y tree, and the active bundle id in parallel
+        // (independent reads). The dump is wrapped so a failure degrades to the
+        // vision path (empty tree); the bundle-id read is best-effort ("" on
+        // failure → the navTitle-only coarse token).
         await this.refreshScreen();
-        const [png, tree] = await Promise.all([
-            screenshotPng(),
+        const [png, tree, bundleId] = await Promise.all([
+            screenshotPng(this.udid),
             this.dumpTree(),
+            activeBundleId(this.udid),
         ]);
         this.lastNodeMap = tree.nodeMap;
+        // Scroll-invariant screen signature from this dump's parsed nodes + coarse
+        // inputs (active bundle id; navTitle is derived from the nodes). iOS is
+        // best-effort — sparse SwiftUI trees are usually unusable and fall back to
+        // Phase-1 continuity (sent only when usable; see loop.ts).
+        const coarseInputs = {
+            platform: "ios",
+            bundleId,
+        };
+        const screenSignature = computeScreenSignature(tree.nodes, coarseInputs);
         return {
             screenshot: png.toString("base64"),
             // Element path when describe-all produced a tree; "" → backend vision.
@@ -196,13 +249,19 @@ export class IOSDevice {
             // Native has no scrollable document; the screen IS the page.
             documentHeight: this.pixelHeight,
             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,
         };
     }
     /**
-     * Read + serialize WDA's /source a11y tree (bounds in POINTS). Any
-     * failure (retries exhausted on a trivial tree, parse error) degrades to an
-     * empty tree so the backend falls back to vision — a missing tree must never
-     * abort the observation.
+     * Read + serialize WDA's /source a11y tree (bounds in POINTS). Returns the
+     * serialized tree, the node map and the FLAT parsed nodes (for the screen
+     * signature). Any failure (retries exhausted on a trivial tree, parse error)
+     * degrades to an empty tree so the backend falls back to vision — a missing
+     * tree must never abort the observation.
      */
     async dumpTree() {
         try {
@@ -210,23 +269,23 @@ export class IOSDevice {
             const nodes = parseXcuiHierarchy(json);
             const tree = serializeNativeTree(nodes);
             this.log(`a11y tree: ${tree.nodeMap.size} node(s)`);
-            return tree;
+            return { ...tree, nodes };
         }
         catch (err) {
             const msg = err instanceof Error ? err.message : String(err);
             this.log(`a11y describe-all failed, falling back to vision: ${msg}`);
-            return { simplified: "", nodeMap: new Map() };
+            return { simplified: "", nodeMap: new Map(), nodes: [] };
         }
     }
     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.
@@ -530,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
@@ -543,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).`);