@ishlabs/cli 0.26.0 → 0.27.0

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

@@ -10,30 +10,90 @@
  * backend's 0-1000 coordinates against the screencap pixel size and taps
  * directly. (Verified by the Layer-1 driver smoke; see scripts/mobile-e2e.)
  */
-import { execFile } from "node:child_process";
-import { existsSync } from "node:fs";
+import { execFile, execFileSync } from "node:child_process";
+import { existsSync, mkdirSync, writeFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
 import { promisify } from "node:util";
+import { binDir, adbBin } from "../paths.js";
 const execFileAsync = promisify(execFile);
-// adb ships with Homebrew's android-platform-tools and inside the SDK. Prefer
-// an explicit absolute path so we never depend on the caller's PATH (mirrors
-// scripts/mobile-e2e/lib.sh). Override with ISH_ADB / ADB.
-function resolveAdb() {
+// Resolve adb without depending on the caller's PATH: ISH_ADB/ADB override → the
+// Android SDK → Homebrew → our own download cache → PATH. If none is found,
+// ensureAdb() fetches Google's standalone platform-tools (a small zip) into
+// ~/.ish/bin, mirroring how cloudflared / the iOS WebDriverAgent runner are
+// fetched. Override the binary with ISH_ADB / ADB.
+function findAdb() {
     const fromEnv = process.env.ISH_ADB || process.env.ADB;
     if (fromEnv && existsSync(fromEnv))
         return fromEnv;
-    const homebrew = "/opt/homebrew/bin/adb";
-    if (existsSync(homebrew))
-        return homebrew;
     const sdkHome = process.env.ANDROID_HOME || process.env.ANDROID_SDK_ROOT;
     if (sdkHome) {
-        const sdkAdb = `${sdkHome}/platform-tools/adb`;
+        const sdkAdb = join(sdkHome, "platform-tools", "adb");
         if (existsSync(sdkAdb))
             return sdkAdb;
     }
-    // Last resort: rely on PATH and surface a clear error if it's missing.
-    return "adb";
+    const homebrew = "/opt/homebrew/bin/adb";
+    if (existsSync(homebrew))
+        return homebrew;
+    if (existsSync(adbBin()))
+        return adbBin(); // our downloaded cache
+    // PATH fallback — only if `adb` actually resolves there.
+    try {
+        execFileSync(process.platform === "win32" ? "where" : "which", ["adb"], { stdio: "ignore" });
+        return "adb";
+    }
+    catch {
+        return null;
+    }
+}
+let cachedAdb = null;
+/** Resolve adb, downloading Google's platform-tools on first use if not found. */
+export async function ensureAdb() {
+    if (cachedAdb)
+        return cachedAdb;
+    cachedAdb = findAdb() ?? (await downloadAdb());
+    return cachedAdb;
+}
+const PLATFORM_TOOLS_OS = {
+    darwin: "darwin",
+    linux: "linux",
+    win32: "windows",
+};
+/** Fetch + unpack Google's standalone platform-tools into ~/.ish/bin. */
+async function downloadAdb() {
+    const os = PLATFORM_TOOLS_OS[process.platform];
+    if (!os) {
+        throw new AdbError(`no prebuilt adb for ${process.platform}; install Android platform-tools and set ISH_ADB`);
+    }
+    const url = `https://dl.google.com/android/repository/platform-tools-latest-${os}.zip`;
+    const dir = binDir();
+    console.error("Fetching adb (Android platform-tools) from Google...");
+    mkdirSync(dir, { recursive: true });
+    const zipPath = join(dir, "platform-tools.zip");
+    let resp;
+    try {
+        resp = await fetch(url, { signal: AbortSignal.timeout(120_000) });
+    }
+    catch (e) {
+        throw new AdbError(`failed to download platform-tools from ${url}: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    if (!resp.ok)
+        throw new AdbError(`failed to download platform-tools: HTTP ${resp.status} from ${url}`);
+    writeFileSync(zipPath, Buffer.from(await resp.arrayBuffer()));
+    try {
+        // The zip carries a top-level `platform-tools/` dir; extract into binDir().
+        const [cmd, args] = process.platform === "win32"
+            ? ["tar", ["-xf", zipPath, "-C", dir]]
+            : ["unzip", ["-o", "-q", zipPath, "-d", dir]];
+        await execFileAsync(cmd, args, { timeout: 120_000 });
+    }
+    catch (e) {
+        throw new AdbError(`failed to unpack platform-tools: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    rmSync(zipPath, { force: true });
+    if (!existsSync(adbBin()))
+        throw new AdbError(`platform-tools unpacked but adb is missing at ${adbBin()}`);
+    return adbBin();
 }
-const ADB = resolveAdb();
 const DEFAULT_TIMEOUT_MS = 30_000;
 // screencap on a cold emulator frame can be slow; give it generous headroom.
 const SCREENCAP_TIMEOUT_MS = 30_000;
@@ -47,8 +107,9 @@ export class AdbError extends Error {
 }
 /** Run `adb <args>` and return trimmed stdout. Throws AdbError on failure. */
 export async function adb(args, timeoutMs = DEFAULT_TIMEOUT_MS) {
+    const bin = await ensureAdb();
     try {
-        const { stdout } = await execFileAsync(ADB, args, {
+        const { stdout } = await execFileAsync(bin, args, {
             timeout: timeoutMs,
             maxBuffer: 4 * 1024 * 1024,
         });
@@ -63,14 +124,75 @@ export async function adb(args, timeoutMs = DEFAULT_TIMEOUT_MS) {
 export async function adbShell(args, timeoutMs = DEFAULT_TIMEOUT_MS) {
     return adb(["shell", ...args], timeoutMs);
 }
+/**
+ * Pull versionName / versionCode out of `dumpsys package <pkg>` text. The
+ * relevant lines read `versionCode=42 minSdk=24 targetSdk=34` and
+ * `versionName=1.2.3`; `\d+` stops the build before the trailing tokens and
+ * `\S+` takes the version up to the next space. Returns null when neither is
+ * present (wrong/empty package).
+ */
+export function parseDumpsysAppBuild(out) {
+    const version = out.match(/versionName=(\S+)/)?.[1] ?? null;
+    const build = out.match(/versionCode=(\d+)/)?.[1] ?? null;
+    if (!version && !build)
+        return null;
+    return { version, build };
+}
+/**
+ * Read an installed package's versionName / versionCode from
+ * `dumpsys package <pkg>`. Best-effort: returns null on any failure (the run
+ * never depends on it). Covers both freshly-installed apks and pre-installed
+ * packages — by call time the package name is already resolved.
+ */
+export async function appBuildFromDevice(pkg) {
+    try {
+        return parseDumpsysAppBuild(await adbShell(["dumpsys", "package", pkg], 30_000));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Pull `"pkg/activity"` out of `dumpsys activity activities`. The foreground
+ * activity surfaces as `topResumedActivity=ActivityRecord{... u0 pkg/activity
+ * t123}` (older builds: `mResumedActivity=...`); we take the `pkg/activity`
+ * token from whichever line is present. The activity may be a short `.Name`
+ * (relative to the package) — kept as-is, exactly what dumpsys reports. Returns
+ * "" when neither line is present.
+ */
+export function parseTopActivity(out) {
+    const m = /topResumedActivity=ActivityRecord\{[^}]*\s(\S+\/\S+)/.exec(out) ??
+        /mResumedActivity:\s*ActivityRecord\{[^}]*\s(\S+\/\S+)/.exec(out) ??
+        /mResumedActivity=ActivityRecord\{[^}]*\s(\S+\/\S+)/.exec(out);
+    if (!m)
+        return "";
+    // The token can carry a trailing task id glued by the regex boundary? No —
+    // `\S+/\S+` stops at the first whitespace, so it is exactly `pkg/activity`.
+    return m[1];
+}
+/**
+ * The foreground `"pkg/activity"` from `dumpsys activity activities`, a coarse
+ * input for the screen signature. Best-effort: returns "" on any failure (the
+ * signature degrades to its package-only coarse token, and the run never
+ * depends on this read).
+ */
+export async function currentActivity() {
+    try {
+        return parseTopActivity(await adbShell(["dumpsys", "activity", "activities"], 15_000));
+    }
+    catch {
+        return "";
+    }
+}
 /**
  * Capture the current screen as raw PNG bytes via `adb exec-out screencap -p`.
  * `exec-out` (not `shell`) avoids the CRLF translation that corrupts binary
  * output. Returns the PNG buffer at full device resolution.
  */
 export async function screencapPng() {
+    const bin = await ensureAdb();
     try {
-        const { stdout } = await execFileAsync(ADB, ["exec-out", "screencap", "-p"], {
+        const { stdout } = await execFileAsync(bin, ["exec-out", "screencap", "-p"], {
             timeout: SCREENCAP_TIMEOUT_MS,
             maxBuffer: SCREENCAP_MAX_BUFFER,
             encoding: "buffer",
@@ -90,7 +212,7 @@ export async function requireOneDevice() {
     }
     catch (err) {
         const msg = err instanceof Error ? err.message : String(err);
-        throw new AdbError(`Could not run adb (looked for "${ADB}"). Run \`ish check android\` to check your setup. ${msg}`);
+        throw new AdbError(`Could not run adb (looked for "${findAdb() ?? "adb"}"). Run \`ish check android\` to check your setup. ${msg}`);
     }
     // Output: "List of devices attached\n<serial>\tdevice\n..."
     const online = out
@@ -101,8 +223,21 @@ export async function requireOneDevice() {
     if (online.length === 0) {
         throw new AdbError("No Android device/emulator online. Run `ish check android` to check your setup and how to boot one.");
     }
+    // Honor ANDROID_SERIAL (the standard adb convention): when it names an online
+    // device, pin to it instead of failing on "more than one device". The adb
+    // wrapper inherits process.env, so every subsequent `adb` call already targets
+    // that serial — this lets multiple emulators run in parallel, each driven by a
+    // CLI invocation with its own ANDROID_SERIAL.
+    const pinned = process.env.ANDROID_SERIAL?.trim();
+    if (pinned) {
+        if (online.some((l) => l.startsWith(`${pinned}\t`)))
+            return;
+        throw new AdbError(`ANDROID_SERIAL=${pinned} is set but that device is not online. ` +
+            `Online: ${online.map((l) => l.split("\t")[0]).join(", ") || "none"}.`);
+    }
     if (online.length > 1) {
-        throw new AdbError(`Expected exactly one Android device, found ${online.length}. Stop the extras (the sim drives a single device).`);
+        throw new AdbError(`Expected exactly one Android device, found ${online.length}. ` +
+            `Stop the extras, or set ANDROID_SERIAL=<serial> to pin one (parallel runs).`);
     }
 }
 // --- Input gestures (all in screencap pixel space) ---

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

@@ -19,7 +19,7 @@
  *   - Vision path: px = round(x / 1000 * screencapWidth); same for y.
  */
 import type { LocalStepAction, ContextValue } from "./types.js";
-import type { SimulationDevice, DeviceObservation, DeviceActionResult } from "./device.js";
+import type { SimulationDevice, DeviceObservation, DeviceActionResult, AppBuild } from "./device.js";
 export interface AndroidDeviceOptions {
     /** App package name to force-stop/relaunch between participants. May be derived from --app. */
     appPackage?: string;
@@ -47,6 +47,12 @@ export declare class AndroidDevice implements SimulationDevice {
     private adbKeyboardActive;
     constructor(opts: AndroidDeviceOptions);
     launchOrReset(target: string): Promise<void>;
+    /**
+     * The installed app's version/build, read off the device after
+     * launchOrReset has resolved the package. Best-effort — null until the
+     * package is known, or if dumpsys can't report it.
+     */
+    appBuild(): Promise<AppBuild | null>;
     /**
      * Resolve which package to drive, returning a non-null package name or
      * throwing. For a local .apk we read the package straight from its binary
@@ -60,9 +66,11 @@ export declare class AndroidDevice implements SimulationDevice {
     private refreshDimensions;
     observe(): Promise<DeviceObservation>;
     /**
-     * Dump + serialize the uiautomator a11y tree. Any failure (dump retries
-     * exhausted, parse error) degrades to an empty tree so the backend falls back
-     * to the vision path — a missing tree must never abort the observation.
+     * Dump + serialize the uiautomator a11y tree. Returns the serialized tree, the
+     * node map, the FLAT parsed nodes (for the screen signature) and the
+     * foreground package read off the dump. Any failure (dump retries exhausted,
+     * parse error) degrades to an empty tree so the backend falls back to the
+     * vision path — a missing tree must never abort the observation.
      */
     private dumpTree;
     captureScreenshot(): Promise<string>;

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

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

package/dist/lib/local-sim/device.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.
@@ -56,6 +81,19 @@ export interface DeviceActionResult {
     } | null;
     openedNewTab: boolean;
 }
+/**
+ * The version/build of the installed native app being driven, read off the
+ * device after `launchOrReset`. Lets the web app show which build an iteration
+ * last ran against. `package` is the resolved bundle id (iOS) / package name
+ * (Android); `version` is the marketing version (CFBundleShortVersionString /
+ * versionName) and `build` the build number (CFBundleVersion / versionCode),
+ * either of which may be null when the device doesn't report it.
+ */
+export interface AppBuild {
+    package: string;
+    version: string | null;
+    build: string | null;
+}
 /**
  * A drivable simulation target. Implementations own their own lifecycle and
  * (for the browser) tab bookkeeping.
@@ -90,6 +128,12 @@ export interface SimulationDevice {
     executeAction(action: LocalStepAction): Promise<DeviceActionResult>;
     /** Current location string for recording (URL for browser; "" for native). */
     currentUrl(): string;
+    /**
+     * Native only: the version/build of the installed app being driven, read
+     * off the device after `launchOrReset`. Browser omits it. Best-effort — a
+     * failed read resolves to null and never disturbs the run.
+     */
+    appBuild?(): Promise<AppBuild | null>;
     /** Tear down. For shared-browser tabs this closes just the tab. */
     close(): Promise<void>;
 }

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

@@ -31,7 +31,7 @@
  *   backend never converts coords with screen_width/height.
  */
 import type { LocalStepAction, ContextValue } from "./types.js";
-import type { SimulationDevice, DeviceObservation, DeviceActionResult } from "./device.js";
+import type { SimulationDevice, DeviceObservation, DeviceActionResult, AppBuild } from "./device.js";
 export interface IosDeviceOptions {
     /** Bundle id to terminate/relaunch between participants. Derived from --app when a .app is given. */
     bundleId?: string;
@@ -70,6 +70,12 @@ export declare class IOSDevice implements SimulationDevice {
     private lastNodeMap;
     constructor(opts: IosDeviceOptions);
     launchOrReset(target: string): Promise<void>;
+    /**
+     * The installed app's version/build, read off the simulator after
+     * launchOrReset has resolved the bundle id. Best-effort — null until the
+     * bundle id is known, or if simctl/plutil can't report it.
+     */
+    appBuild(): Promise<AppBuild | null>;
     /**
      * Resolve the bundle id to drive, returning a non-null id or throwing.
      * Installs a local `.app` first and reads its CFBundleIdentifier from
@@ -80,10 +86,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, } from "./simctl.js";
+import { requireOneBootedSimulator, screenshotPng, terminateApp, launchApp, installApp, 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;
@@ -116,6 +117,21 @@ export class IOSDevice {
         await launchApp(this.udid, bundleId);
         await settle(1500); // cold start needs longer than a gesture settle
     }
+    /**
+     * The installed app's version/build, read off the simulator after
+     * launchOrReset has resolved the bundle id. Best-effort — null until the
+     * bundle id is known, or if simctl/plutil can't report it.
+     */
+    async appBuild() {
+        if (!this.bundleId || !this.udid)
+            return null;
+        const meta = await appBuildFromSimulator(this.udid, this.bundleId);
+        return {
+            package: this.bundleId,
+            version: meta?.version ?? null,
+            build: meta?.build ?? null,
+        };
+    }
     /**
      * Resolve the bundle id to drive, returning a non-null id or throwing.
      * Installs a local `.app` first and reads its CFBundleIdentifier from
@@ -161,14 +177,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([
+        const [png, tree, bundleId] = await Promise.all([
             screenshotPng(),
             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.
@@ -181,13 +209,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 {
@@ -195,12 +229,12 @@ 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() {