@delacour/warden-e2e 0.12.1 → 0.14.0

package/preload.mjs

@@ -11,6 +11,7 @@ import {
   settleDetailOf,
   DEFAULT_SETTLE_QUIET_MS,
   DEFAULT_SETTLE_TIMEOUT_MS,
+  hashFallbackQuietMs,
   settleByHash,
   snapshotHash,
   ok,
@@ -35,7 +36,7 @@ import {
   selectorExpression,
   renderSnapshot,
   renderHeader,
-  locateByTestIdViaReact,
+  lookUpTestIdViaReact,
   isLocator,
   Locator,
   scrollUntilVisible,
@@ -44,6 +45,10 @@ import {
   execError,
   driverError,
   driverErr,
+  bridgeStallSchema,
+  toBridgeStall,
+  noteBridgeStall,
+  formatBridgeStall,
   logEventSchema,
   fatalEventSchema,
   responseSchema,
@@ -109,7 +114,7 @@ import {
   onlyWasSeen,
   WORKSPACE_VERSION,
   WARDEN_E2E_VERSION2
-} from "./chunk-rbbn127e.mjs";
+} from "./chunk-zk3wxa70.mjs";
 
 // ../../packages/e2e/src/preload.ts
 import { afterAll, setDefaultTimeout } from "bun:test";
@@ -7728,6 +7733,7 @@ function locateHelper(input) {
 function resolveHelper(o) {
   if (o.helperPath !== undefined)
     return { success: true, data: o.helperPath };
+  const version = o.version ?? o.env?.wardenVersion;
   const located = locateHelper({
     env: { [ENV_NAMES.simd]: o.env?.simd, [ENV_NAMES.helperDir]: o.env?.helperDir },
     execPath: o.execPath ?? process.execPath,
@@ -7735,7 +7741,7 @@ function resolveHelper(o) {
     wardenHome: o.wardenHome ?? wardenHome(),
     exists: o.exists ?? existsSync7,
     realpath: o.realpath ?? realpathSync,
-    ...o.version ? { version: o.version } : {}
+    ...version ? { version } : {}
   });
   return located.success ? { success: true, data: located.data.path } : located;
 }
@@ -7816,6 +7822,10 @@ function toSnapshot(data, takenAt) {
   };
   if (data.modal)
     snapshot.modal = data.modal;
+  if (data.fallback?.from === "axbridge")
+    snapshot.fellBackFrom = "axbridge";
+  if (data.fallback?.stall)
+    snapshot.bridgeStall = toBridgeStall(data.fallback.stall);
   return snapshot;
 }
 
@@ -8401,6 +8411,17 @@ var DEFAULT_QUIET_MS = 250;
 var DEFAULT_SETTLE_TIMEOUT_MS2 = 5000;
 var SETTLE_MARGIN_MS = 2000;
 var REBIND_TIMEOUT_MS = 1e4;
+var COLD_BRIDGE_BUDGET_MS = 60000;
+var COLD_BRIDGE_FIRST_WAIT_MS = 2000;
+var COLD_BRIDGE_WAIT_MS = 5000;
+var BRIDGE_COLD_DEADLINE_MS = 12000;
+var AX_FALLBACK_MARGIN_MS = 8000;
+var COLD_READ_TIMEOUT_MS = BRIDGE_COLD_DEADLINE_MS + AX_FALLBACK_MARGIN_MS;
+function coldReadTimeoutMs(env = process.env) {
+  const raw = Number(env.WARDEN_SIMD_BRIDGE_COLD_DEADLINE_MS);
+  const deadline = Number.isFinite(raw) && raw > BRIDGE_COLD_DEADLINE_MS ? raw : BRIDGE_COLD_DEADLINE_MS;
+  return deadline + AX_FALLBACK_MARGIN_MS;
+}
 var GESTURE_MARGIN_MS = 5000;
 var FRONTMOST_TIMEOUT_MS = 3000;
 var LAUNCH_TIMEOUT_MS = 30000;
@@ -8474,6 +8495,23 @@ function noteSnapshotError(detail) {
     if (typeof value === "string")
       noteSpanDetail(to, value);
   }
+  const stall = bridgeStallSchema.safeParse(detail.stall);
+  if (stall.success)
+    noteBridgeStall(toBridgeStall(stall.data));
+}
+function noteFallback(fallback, log) {
+  const stall = fallback.stall && toBridgeStall(fallback.stall);
+  const why = stall ? ` (${formatBridgeStall(stall)})` : "";
+  log?.(`[ios] snapshot fell back ${fallback.from} -> ${fallback.to}: ${fallback.reason}${why}`);
+  noteSpanDetail("fallback", fallback.reason);
+  if (stall)
+    noteBridgeStall(stall);
+}
+function noteSnapshotTarget(target) {
+  if (!target)
+    return;
+  noteSpanDetail("targetPid", target.pid);
+  noteSpanDetail("targetSource", target.source);
 }
 function noteHelperHealth(health) {
   noteSpanDetail("bridge", health.ax.bridge);
@@ -8489,6 +8527,36 @@ function noteHelperHealth(health) {
     noteSpanDetail("coreSimulator", health.coreSimulatorVersion);
   if (health.frontmost)
     noteSpanDetail("frontmostUnresolvedAgoMs", health.frontmost.unresolvedAgoMs);
+  if (health.bridgeRecycles) {
+    noteSpanDetail("bridgeRecycles", health.bridgeRecycles.count);
+    noteSpanDetail("bridgeRecyclesExhausted", health.bridgeRecycles.exhausted);
+  }
+}
+function coldBridgeWait(error, attempt, spentMs, budgetMs) {
+  if (!bridgeNotReady(error))
+    return;
+  const wait = attempt === 1 ? COLD_BRIDGE_FIRST_WAIT_MS : COLD_BRIDGE_WAIT_MS;
+  return spentMs + wait >= budgetMs ? undefined : wait;
+}
+async function retryColdSnapshot(read, ctx) {
+  const started = ctx.now();
+  let waited = 0;
+  for (let attempt = 1;; attempt++) {
+    const result = await read();
+    const spent = Math.max(ctx.now() - started, waited);
+    const wait = result.success ? undefined : coldBridgeWait(result.error, attempt, spent, ctx.budgetMs);
+    if (wait === undefined) {
+      if (attempt > 1)
+        noteSpanDetail("coldBridgeMs", spent);
+      return result;
+    }
+    ctx.log?.(`[ios] snapshot try ${attempt} failed, the bridge is not up yet: retrying`);
+    await ctx.sleep(wait);
+    waited += wait;
+  }
+}
+function bridgeNotReady(error) {
+  return error.code === "E_TIMEOUT" || error.code === "E_AX_UNAVAILABLE";
 }
 function noteRebind(data) {
   noteSpanDetail("rebind", data.bound ? "bound" : data.reason ?? "unbound");
@@ -8562,6 +8630,10 @@ function createIosDriver(swap, simctl, opts) {
   let settleUnsupported = !nativeSettle;
   let settleAxFailures = 0;
   let rebindUnsupported = false;
+  let bridgeProven = false;
+  let warmGeneration;
+  const coldTimeoutMs = coldReadTimeoutMs();
+  const readOpts = () => warmGeneration === swap.generation() ? {} : { minTimeoutMs: coldTimeoutMs };
   let gestureUnsupported = false;
   let appOpsOutdated = false;
   const capabilities = {
@@ -8657,7 +8729,8 @@ function createIosDriver(swap, simctl, opts) {
   }
   let failureDiagnosed = false;
   const fetchSnapshot = async (o) => {
-    const result = await request("snapshot", params({ interactiveOnly: o?.interactiveOnly, backend: o?.backend }));
+    const generation = swap.generation();
+    const result = await request("snapshot", params({ interactiveOnly: o?.interactiveOnly, backend: o?.backend }), readOpts());
     if (!result.success) {
       noteSnapshotError(result.error.detail);
       if (!failureDiagnosed) {
@@ -8670,18 +8743,15 @@ function createIosDriver(swap, simctl, opts) {
     }
     failureDiagnosed = false;
     const { fallback, target } = result.data;
+    if (result.data.backend === "axbridge" && !fallback)
+      warmGeneration = generation;
     noteSpanDetail("backend", result.data.backend);
-    if (fallback) {
-      opts.log?.(`[ios] snapshot fell back ${fallback.from} -> ${fallback.to}: ${fallback.reason}`);
-      noteSpanDetail("fallback", fallback.reason);
-    }
-    if (target) {
-      noteSpanDetail("targetPid", target.pid);
-      noteSpanDetail("targetSource", target.source);
-    }
+    if (fallback)
+      noteFallback(fallback, opts.log);
+    noteSnapshotTarget(target);
     return { success: true, data: toSnapshot(result.data, now()) };
   };
-  async function snapshot(o) {
+  async function snapshotOnce(o) {
     const generation = swap.generation();
     const first = await fetchSnapshot(o);
     if (first.success) {
@@ -8702,6 +8772,19 @@ function createIosDriver(swap, simctl, opts) {
     axFailures = 0;
     return fetchSnapshot(o);
   }
+  async function snapshot(o) {
+    if (bridgeProven)
+      return snapshotOnce(o);
+    const result = await retryColdSnapshot(() => snapshotOnce(o), {
+      now,
+      sleep,
+      budgetMs: opts.coldBridgeBudgetMs ?? COLD_BRIDGE_BUDGET_MS,
+      ...opts.log ? { log: opts.log } : {}
+    });
+    if (result.success)
+      bridgeProven = true;
+    return result;
+  }
   async function typeText(text) {
     const typed = await sendVoid("typeText", { text }, typeTextBudgetMs(text));
     if (typed.success || typed.error.code !== "E_UNSUPPORTED_TEXT")
@@ -8728,7 +8811,7 @@ function createIosDriver(swap, simctl, opts) {
         if (!snap.success)
           throw new DriverFailure(snap.error);
         return snapshotHash(snap.data);
-      }, { quietMs: o.quietMs, timeoutMs: o.timeoutMs, now, sleep });
+      }, { quietMs: hashFallbackQuietMs(o.quietMs), timeoutMs: o.timeoutMs, now, sleep });
       noteSpanDetail("via", "hash");
       return { success: true, data: { ...outcome, via: "hash" } };
     } catch (error) {
@@ -8739,6 +8822,7 @@ function createIosDriver(swap, simctl, opts) {
   }
   async function settleAfterLaunch(bundleId) {
     lastLaunched = bundleId;
+    warmGeneration = undefined;
     launchedBundle = bundleId;
     if (await rebind(bundleId))
       launchedBundle = undefined;
@@ -8762,6 +8846,8 @@ function createIosDriver(swap, simctl, opts) {
       return false;
     }
     noteRebind(reply.data);
+    if (reply.data.bound)
+      bridgeProven = true;
     return reply.data.bound;
   }
   function noteSettleAxFailure(message) {
@@ -8834,7 +8920,7 @@ function createIosDriver(swap, simctl, opts) {
     return info;
   }
   async function readAlert(backend) {
-    const result = await request("alertButtons", params({ backend }));
+    const result = await request("alertButtons", params({ backend }), readOpts());
     if (!result.success)
       return result;
     return { success: true, data: result.data === null ? null : toAlertInfo(result.data) };
@@ -8890,7 +8976,7 @@ function createIosDriver(swap, simctl, opts) {
     health,
     snapshot,
     async elementAtPoint(point, o) {
-      const result = await request("elementAtPoint", params({ x: point.x, y: point.y, reachability: o?.reachability }));
+      const result = await request("elementAtPoint", params({ x: point.x, y: point.y, reachability: o?.reachability }), readOpts());
       if (!result.success)
         return result;
       return {
@@ -9082,6 +9168,7 @@ async function openIosDriver(o) {
       now,
       sleep,
       log,
+      ...o.coldBridgeBudgetMs !== undefined ? { coldBridgeBudgetMs: o.coldBridgeBudgetMs } : {},
       ...network ? { network } : {},
       a11y: () => iosA11yFor(o, now, sleep),
       nativeAudit: (ctx) => nativeAuditFor(o, exec, log, ctx),
@@ -9417,7 +9504,12 @@ function createIosDeviceDriver(client, devicectl, opts) {
         if (!snap.success)
           throw new DriverFailure2(snap.error);
         return snapshotHash(snap.data);
-      }, { quietMs: o.quietMs ?? DEFAULT_QUIET_MS2, timeoutMs: o.timeoutMs ?? DEFAULT_SETTLE_TIMEOUT_MS3, now, sleep });
+      }, {
+        quietMs: hashFallbackQuietMs(o.quietMs ?? DEFAULT_QUIET_MS2),
+        timeoutMs: o.timeoutMs ?? DEFAULT_SETTLE_TIMEOUT_MS3,
+        now,
+        sleep
+      });
       noteSpanDetail("via", "hash");
       return { success: true, data: { ...outcome, via: "hash" } };
     } catch (error) {
@@ -10406,7 +10498,7 @@ function createDevice({
       if (native.error.code !== "E_UNSUPPORTED")
         throw toE2eError(native.error, "settle");
       const polled = await settleByHash(async () => snapshotHash(await readSnapshot()), {
-        quietMs,
+        quietMs: hashFallbackQuietMs(quietMs),
         timeoutMs,
         now: clock.now,
         sleep: clock.sleep
@@ -10529,15 +10621,16 @@ class Runtime {
       const result = canObserve(driver) ? await driver.observe({ reuse }) : await driver.snapshot();
       if (!result.success)
         return { ok: false, error: result.error };
+      const snapshot = result.data;
       const observation = {
         ok: true,
-        observed: { driver, snapshot: result.data, index: this.indexOf(result.data) }
+        observed: { driver, snapshot, index: this.indexOf(snapshot) }
       };
       if (before !== undefined)
         observation.earlier = this.earlierThan(driver, before, result.data);
       if (options.alerts === false || answered >= MAX_ALERT_ANSWERS)
         return observation;
-      if (!await this.answeredAlert(driver, result.data))
+      if (!await this.answeredAlert(driver, snapshot))
         return observation;
       reuse = false;
     }
@@ -10578,18 +10671,25 @@ class Runtime {
     throw driverFailure("snapshot", result.last ?? { code: "E_TIMEOUT", message: "no snapshot", retryable: true });
   }
   async reactMatches(testId, observed) {
+    const lookup = await this.reactLookup(testId, observed);
+    return lookup.answered ? lookup.matches : [];
+  }
+  hasReactTree() {
+    return this.host.devtools?.() !== undefined;
+  }
+  async reactLookup(testId, observed) {
     const facet = this.host.devtools?.();
     if (facet === undefined)
-      return [];
+      return { answered: false };
     const key = typeof testId === "string" ? `s:${testId}` : `r:${testId.toString()}`;
     const cached = this.reactCache;
     if (cached !== undefined && cached.key === key && this.clock.now() - cached.at < REACT_THROTTLE_MS) {
-      return cached.matches;
+      return cached.lookup;
     }
     const view = { platform: observed.snapshot.platform, screen: observed.snapshot.screen };
-    const matches = await locateByTestIdViaReact(facet, testId, view, { timeoutMs: REACT_TIMEOUT_MS });
-    this.reactCache = { key, at: this.clock.now(), matches };
-    return matches;
+    const lookup = await lookUpTestIdViaReact(facet, testId, view, { timeoutMs: REACT_TIMEOUT_MS });
+    this.reactCache = { key, at: this.clock.now(), lookup };
+    return lookup;
   }
   excerpt(snapshot) {
     const rendered = renderSnapshot(snapshot, { interactiveOnly: true, refs: new Map, maxLines: EXCERPT_LINES });

package/types/core/src/affected/affected.schema.d.ts

@@ -18,6 +18,7 @@ type RunSettings = {
     passes: number;
     count?: number | undefined;
     profile?: string | undefined;
+    runtime?: string | undefined;
     devices?: Array<{
         profile: string;
         default: boolean;
@@ -141,6 +142,7 @@ export declare const e2eSuiteSchema: z.ZodObject<{
     retry: z.ZodDefault<z.ZodNumber>;
     count: z.ZodOptional<z.ZodNumber>;
     profile: z.ZodOptional<z.ZodString>;
+    runtime: z.ZodOptional<z.ZodString>;
     app: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodObject<{
         installMode: z.ZodOptional<z.ZodEnum<{
             clean: "clean";

package/types/core/src/builds/config.schema.d.ts

@@ -333,6 +333,7 @@ export declare const wardenConfigSchema: z.ZodObject<{
         retry: z.ZodDefault<z.ZodNumber>;
         count: z.ZodOptional<z.ZodNumber>;
         profile: z.ZodOptional<z.ZodString>;
+        runtime: z.ZodOptional<z.ZodString>;
         app: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodObject<{
             installMode: z.ZodOptional<z.ZodEnum<{
                 clean: "clean";

package/types/core/src/builds/define-config.d.ts

@@ -687,6 +687,16 @@ export interface WardenE2eSuite {
     count?: number | undefined;
     /** Device profile (not with `devices`). */
     profile?: string | undefined;
+    /**
+     * iOS simulator runtime the run's devices boot on, and whose golden they clone: `latest`, `iOS-26-5` or `26.5`.
+     * Pin it so the run (locally and on CI) sees one accessibility tree: values change between iOS releases.
+     * A runtime that is not installed fails the run before any device is claimed, listing the installed ones; it never
+     * falls back to another. Applies to every `devices` leg. Skipped on Android. `--runtime` overrides it.
+     * `warden golden key --profile <profile> --runtime <runtime>` names the golden archive the run uses.
+     *
+     * @example "27.0"
+     */
+    runtime?: string | undefined;
     /** Ensure the app on every device first. */
     app?: WardenAppOption | undefined;
     /** Ports leased for the run (`<from>[:<span>]`), exported as `WARDEN_PORT_<i>` / `WARDEN_PORTS` to serve, setup and every spec process. */

package/types/e2e/src/driver/bridge-stall.d.ts

@@ -0,0 +1,37 @@
+import { z } from "zod";
+import { type SpanDetail } from "./span-detail";
+/**
+ * What one iOS `axbridge` fallback or stall looked like, as `warden-simd` reports it (`fallback.stall` on a snapshot,
+ * `detail.stall` on a failed read). Recorded in `trace.jsonl` (the `stall*` span fields), `results.jsonl` (`bridge`)
+ * and under the header of `screen-at-failure.txt`.
+ */
+export declare const bridgeStallSchema: z.ZodObject<{
+    stage: z.ZodString;
+    readMs: z.ZodOptional<z.ZodNumber>;
+    deadlineMs: z.ZodOptional<z.ZodNumber>;
+    guestAgeMs: z.ZodOptional<z.ZodNumber>;
+    cold: z.ZodBoolean;
+    cooldownRemainingMs: z.ZodOptional<z.ZodNumber>;
+    probes: z.ZodNumber;
+    recycles: z.ZodOptional<z.ZodNumber>;
+    recyclesExhausted: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$loose>;
+export type BridgeStall = {
+    stage: string;
+    readMs?: number;
+    deadlineMs?: number;
+    guestAgeMs?: number;
+    cold: boolean;
+    cooldownRemainingMs?: number;
+    probes: number;
+    recycles?: number;
+    recyclesExhausted?: boolean;
+};
+/** Only the fields of the schema, so a newer helper's extra keys stay off the span and out of the results. */
+export declare function toBridgeStall(wire: z.infer<typeof bridgeStallSchema>): BridgeStall;
+/** Leaves the stall on the span timing the read (`stallStage`, `stallReadMs`, …). */
+export declare function noteBridgeStall(stall: BridgeStall): void;
+/** The stall a span recorded, or undefined when it has none. */
+export declare function bridgeStallFromSpan(detail: SpanDetail | undefined): BridgeStall | undefined;
+/** One line for a log or a report: `stage read · read 4012 ms of a 4000 ms deadline · warm · …`. */
+export declare function formatBridgeStall(stall: BridgeStall): string;

package/types/e2e/src/driver/driver.types.d.ts

@@ -1,6 +1,7 @@
 import type { CameraCondition, ClockCondition, HostFault, LocationCondition, NetworkCondition, PermissionName, PermissionState, TextSize } from "../../../core/src/conditions/conditions.types";
 import type { AsyncResult } from "../../../types/src/result";
 import type { ScreenReaderState } from "../a11y/a11y.types";
+import type { BridgeStall } from "./bridge-stall";
 /**
  * The device driver contract every layer of warden-e2e builds on: the spec API (`screen`, `device`,
  * `app`), `warden ui`, specs and the devtools facet all talk to a `Driver`. Implementations:
@@ -134,6 +135,14 @@ export type Snapshot = {
     flat: Element[];
     truncated: boolean;
     modal?: ModalInfo;
+    /**
+     * Set when `backend` answered because this reader failed or was skipped first (iOS: `axbridge` stalled, `ax` read in
+     * its place). The fallback reader can lack what the first one has, so a missing node on such a snapshot is not final:
+     * the iOS helper probes the first reader in the background, and a later read is back on it once it answers.
+     */
+    fellBackFrom?: SnapshotBackend;
+    /** iOS: what the bridge failure behind `fellBackFrom` looked like, when the helper reported it */
+    bridgeStall?: BridgeStall;
 };
 export type Orientation = "portrait" | "portraitUpsideDown" | "landscapeLeft" | "landscapeRight";
 export type HardwareButton = "home" | "back" | "lock" | "volumeUp" | "volumeDown" | "shake";

package/types/e2e/src/driver/ios/ios-driver.d.ts

@@ -25,7 +25,7 @@ import type { SimdSpawn } from "./simd-transport";
  * cannot type, `settle` polls snapshot hashes when the helper has no native quiescence, `screenshot` uses
  * `simctl io` when the helper cannot, and a helper built before the app ops leaves app lifecycle to `simctl`.
  */
-export type IosDriverEnv = Pick<E2eEnv, "simd" | "simdSocket" | "helperDir">;
+export type IosDriverEnv = Pick<E2eEnv, "simd" | "simdSocket" | "helperDir"> & Partial<Pick<E2eEnv, "wardenVersion">>;
 /** The iOS driver is a `Driver` plus the optional capabilities of `driver/alerts.ts`. */
 export type IosDriver = Driver & SelectsAll & PastesText & ReadsAlertOn & ProbesFrontmost & ReadsA11y & ReadsA11yEvents & AuditsNatively;
 export type OpenIosDriverOptions = {
@@ -46,6 +46,8 @@ export type OpenIosDriverOptions = {
     client?: SimdClient;
     now?: () => number;
     sleep?: (ms: number) => Promise<void>;
+    /** how long the session's first snapshot waits for an in-sim bridge that is up but silent (default 60 s); 0 tries once */
+    coldBridgeBudgetMs?: number;
     /** for `locateHelper` / `$WARDEN_HOME/simd/<version>`; defaults read the process */
     version?: string;
     wardenHome?: string;
@@ -82,6 +84,23 @@ export type OpenIosDriverOptions = {
     /** test seams for the XCUITest audit's runner */
     nativeAudit?: Pick<IosNativeAuditOptions, "ensureBuild" | "spawn" | "connect">;
 };
+/**
+ * How long the first snapshot of a session waits for an in-sim bridge that is up but silent. A freshly cloned
+ * simulator on a loaded host can take longer than one read's budget (axbridge 4 s + AX fallback 5 s) to answer the
+ * first time, and every read after it is fast, so the first one retries while the failure says "not ready yet".
+ * Once a read or a rebind has succeeded the normal per-call budgets apply.
+ */
+export declare const COLD_BRIDGE_BUDGET_MS = 60000;
+/**
+ * warden-simd's deadline for the first `axbridge` read of a cold guest (helper start, a recycled guest, an app just
+ * launched): `BridgeDeadline.defaultColdReadMs`, or `WARDEN_SIMD_BRIDGE_COLD_DEADLINE_MS`. On a 3-vCPU runner that
+ * first read takes 4-11 s; warm reads keep the 4 s deadline.
+ */
+export declare const BRIDGE_COLD_DEADLINE_MS = 12000;
+/** The request timeout of a read while the bridge is cold, so the client never gives up before the helper's deadline. */
+export declare const COLD_READ_TIMEOUT_MS: number;
+/** {@link COLD_READ_TIMEOUT_MS}, following a `WARDEN_SIMD_BRIDGE_COLD_DEADLINE_MS` the helper also reads. */
+export declare function coldReadTimeoutMs(env?: Readonly<Record<string, string | undefined>>): number;
 /** USB HID keyboard-page usage ids for the keys `Driver.key` offers. */
 export declare const KEY_USAGE: Readonly<Record<KeyName, number>>;
 /** The fields of a failed snapshot's `detail` the helper sets (which reader, why, both readers' errors), on its span. */
@@ -93,6 +112,8 @@ export declare function createIosDriver(swap: SwappableClient, simctl: Simctl, o
     now: () => number;
     sleep: (ms: number) => Promise<void>;
     log?: Logger;
+    /** how long the first snapshot waits for a bridge that is not up yet (default {@link COLD_BRIDGE_BUDGET_MS}) */
+    coldBridgeBudgetMs?: number;
     /** told about every successful `clock` op */
     clockRecorder?: ClockRecorder;
     /** device settings (`ios-settings.ts`); absent: those ops answer `E_UNSUPPORTED` */

package/types/e2e/src/driver/ios/simd-client.d.ts

@@ -21,6 +21,8 @@ export type SimdEventMap = {
 };
 export type RequestOptions = {
     timeoutMs?: number;
+    /** a floor for this request's timeout (a cold bridge read): raises the default or `timeoutMs`, never lowers it */
+    minTimeoutMs?: number;
 };
 export type SimdClient = {
     /** the handshake of the current helper process (refreshed after a respawn) */

package/types/e2e/src/driver/ios/simd-protocol.d.ts

@@ -192,6 +192,10 @@ export declare const healthDataSchema: z.ZodObject<{
         unresolvedAgoMs: z.ZodNumber;
         method: z.ZodString;
     }, z.core.$strip>>;
+    bridgeRecycles: z.ZodOptional<z.ZodObject<{
+        count: z.ZodNumber;
+        exhausted: z.ZodBoolean;
+    }, z.core.$strip>>;
     state: z.ZodOptional<z.ZodString>;
     uptimeMs: z.ZodOptional<z.ZodNumber>;
 }, z.core.$loose>;
@@ -214,6 +218,17 @@ export declare const snapshotDataSchema: z.ZodObject<{
         from: z.ZodString;
         to: z.ZodString;
         reason: z.ZodString;
+        stall: z.ZodOptional<z.ZodObject<{
+            stage: z.ZodString;
+            readMs: z.ZodOptional<z.ZodNumber>;
+            deadlineMs: z.ZodOptional<z.ZodNumber>;
+            guestAgeMs: z.ZodOptional<z.ZodNumber>;
+            cold: z.ZodBoolean;
+            cooldownRemainingMs: z.ZodOptional<z.ZodNumber>;
+            probes: z.ZodNumber;
+            recycles: z.ZodOptional<z.ZodNumber>;
+            recyclesExhausted: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$loose>>;
     }, z.core.$strip>>;
     target: z.ZodOptional<z.ZodObject<{
         pid: z.ZodNumber;
@@ -362,6 +377,10 @@ export declare const opSchemas: {
             unresolvedAgoMs: z.ZodNumber;
             method: z.ZodString;
         }, z.core.$strip>>;
+        bridgeRecycles: z.ZodOptional<z.ZodObject<{
+            count: z.ZodNumber;
+            exhausted: z.ZodBoolean;
+        }, z.core.$strip>>;
         state: z.ZodOptional<z.ZodString>;
         uptimeMs: z.ZodOptional<z.ZodNumber>;
     }, z.core.$loose>;
@@ -383,6 +402,17 @@ export declare const opSchemas: {
             from: z.ZodString;
             to: z.ZodString;
             reason: z.ZodString;
+            stall: z.ZodOptional<z.ZodObject<{
+                stage: z.ZodString;
+                readMs: z.ZodOptional<z.ZodNumber>;
+                deadlineMs: z.ZodOptional<z.ZodNumber>;
+                guestAgeMs: z.ZodOptional<z.ZodNumber>;
+                cold: z.ZodBoolean;
+                cooldownRemainingMs: z.ZodOptional<z.ZodNumber>;
+                probes: z.ZodNumber;
+                recycles: z.ZodOptional<z.ZodNumber>;
+                recyclesExhausted: z.ZodOptional<z.ZodBoolean>;
+            }, z.core.$loose>>;
         }, z.core.$strip>>;
         target: z.ZodOptional<z.ZodObject<{
             pid: z.ZodNumber;

package/types/e2e/src/driver/settle.d.ts

@@ -33,6 +33,14 @@ export declare function settleDetailOf(outcome: SettleOutcome): SettleDetail;
 export declare const DEFAULT_SETTLE_QUIET_MS = 250;
 /** How long a settle waits for quiet before it gives up. */
 export declare const DEFAULT_SETTLE_TIMEOUT_MS = 3000;
+/**
+ * The shortest window a snapshot-hash settle fallback waits (iOS, and `device.settle` on a driver without one). A navigation push exposes both screens at their final
+ * frames for 300-460 ms before the old one leaves the tree, so two equal reads 250 ms apart can settle on that mixed
+ * tree. The helper's own snapshot fallback (`FrameStability.minQuietMs`) uses the same floor.
+ */
+export declare const HASH_FALLBACK_MIN_QUIET_MS = 500;
+/** The quiet window a hash fallback uses for a caller's `quietMs`. */
+export declare function hashFallbackQuietMs(quietMs: number): number;
 /**
  * Snapshot-hash settle: poll a UI fingerprint until it stays unchanged for `quietMs`
  * (two consecutive equal hashes and ≥ quietMs since the last change), or give up at `timeoutMs`.

package/types/e2e/src/errors.d.ts

@@ -1,5 +1,7 @@
 import type { ErrorResult } from "../../types/src/result";
-export type E2eErrorCode = "LOCATOR_NOT_FOUND" | "LOCATOR_AMBIGUOUS" | "INVALID_LOCATOR" | "ACTION_FAILED" | "TIMEOUT" | "NOT_ACTIONABLE" | "INVALID_ARGUMENT" | "SESSION" | "DRIVER" | "ASSERTION" | "PERF_BUDGET";
+export type E2eErrorCode = "LOCATOR_NOT_FOUND" | "LOCATOR_AMBIGUOUS" | "INVALID_LOCATOR" | "ACTION_FAILED" | "TIMEOUT" | "NOT_ACTIONABLE" | "INVALID_ARGUMENT" | "SESSION" | "DRIVER" | "ASSERTION" | "PERF_BUDGET" | "RUN_FAILED"
+/** a read that fell back from its first reader (or came back an empty root) could not confirm the locator either way */
+ | "READ_DEGRADED";
 /** Plain shape of a spec error: what `e2eErr()` accepts and what a `Result` carries. */
 export type E2eErrorShape = {
     code: E2eErrorCode;

package/types/e2e/src/expect/matchers.d.ts

@@ -81,6 +81,11 @@ export declare class LocatorAssertions {
     toHaveCount(expected: number, options?: AssertionOptions): Promise<void>;
     private assert;
     private poll;
+    /**
+     * What one look says about `spec`: a judgement (from the accessibility tree, or from the React tree for a degraded
+     * read it answered), or `unsettled` when the read was degraded and nothing could say whether the locator is there.
+     */
+    private judgeLook;
     /** The screen is rendered here, from the last snapshot read, because only a failure needs the text. */
     private failure;
 }

package/types/e2e/src/index.d.ts

@@ -10,6 +10,8 @@ export { expect } from "./expect/expect";
 export type { PerfBreach, PerfBudgets } from "./perf/budgets";
 export type { DevicePerf } from "./perf/device-perf";
 export type { PerfMetrics, PerfReport, PerfStartOptions } from "./perf/perf.types";
+export type { Run, RunCommand, RunDuration, RunOptions, RunResult } from "./run";
+export { run } from "./run";
 export type { App, Device, Screen, SystemAlerts, TestFixtures } from "./runner/fixtures.types";
 export { afterAll, afterEach, beforeAll, beforeEach, describe, test } from "./runner/test";
 export type { Locator, LocatorReading, PinchOptions, RotateOptions, TapOptions, TapUntil } from "./screen/locator";

package/types/e2e/src/run.d.ts

@@ -0,0 +1,48 @@
+import type { SpanRunner } from "./runner/span";
+/** Milliseconds, or a duration string (`500ms`, `30s`, `2m`). */
+export type RunDuration = string | number;
+export type RunOptions = {
+    /** working directory; default the spec process's (the project root under `warden e2e`) */
+    cwd?: string;
+    /** merged over the spec's environment; `undefined` removes a variable */
+    env?: Record<string, string | undefined>;
+    /** kill the command after this long and throw `TIMEOUT`; default `60s` */
+    timeout?: RunDuration;
+    /** written to the command's stdin */
+    input?: string;
+    /** throw `RUN_FAILED` on a non-zero exit; default true. `false` returns the result with `ok: false` */
+    check?: boolean;
+};
+export type RunResult = {
+    /** exit code was 0 */
+    ok: boolean;
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+    /** wall time of the command */
+    ms: number;
+    /** `stdout` parsed as JSON; throws `INVALID_ARGUMENT` when it is not JSON */
+    json(): unknown;
+};
+/**
+ * A shell command (`string`, run with `sh -c`) or an argv (`string[]`, no shell: nothing is expanded or split).
+ */
+export type RunCommand = string | readonly string[];
+export type Run = (command: RunCommand, options?: RunOptions) => Promise<RunResult>;
+export type RunDeps = {
+    /** times the call as a span in the running attempt's trace */
+    span: SpanRunner;
+};
+/** `run` with its span runner injected (tests); specs use {@link run}. */
+export declare function createRun(deps: RunDeps): Run;
+/**
+ * Runs a command on the host (the machine running the spec, not the device) and returns its exit code and output.
+ * Use it to seed a backend, call a script, or reset state before a test. A non-zero exit throws `RUN_FAILED`
+ * (`check: false` returns it instead), a command over `timeout` (default 60 s) is killed and throws `TIMEOUT`.
+ * Inside a test it is one `run` span in `trace.jsonl` (exit code only, never the command).
+ *
+ * @example
+ * await run("bun scripts/seed.ts");
+ * const { id } = (await run(["bun", "scripts/create-user.ts", "--json"])).json() as { id: string };
+ */
+export declare const run: Run;

package/types/e2e/src/runner/bridge-evidence.d.ts

@@ -0,0 +1,12 @@
+import type { TestResult } from "./results";
+import type { TraceEvent } from "./trace";
+export type BridgeEvidence = NonNullable<TestResult["bridge"]>;
+/**
+ * Collects an attempt's iOS bridge fallbacks from its spans for `results.jsonl` (`bridge`): reads answered by `ax`
+ * in place of `axbridge`, and failed reads that carried a stall report. A read the bridge answered by pid (frontmost
+ * unresolved) is not one.
+ */
+export declare function bridgeEvidence(): {
+    observe(event: TraceEvent): void;
+    summary(): BridgeEvidence | undefined;
+};