@delacour/warden-e2e 0.12.0 → 0.13.0

package/{chunk-qz94hsb6.mjs → chunk-tnr47n9c.mjs}

@@ -723,8 +723,9 @@ var UNCHECKED_WORDS = new Set(["0", "off", "false", "unchecked"]);
 function nonEmpty(value) {
   return value === undefined || value === "" ? undefined : value;
 }
+var MASKED_VALUE = /^[\u2022\u25CF]+$/;
 function isSecure(element, traits) {
-  return element.role === "securefield" || traits.has("password") || traits.has("secure") || element.rawType.toLowerCase().includes("secure");
+  return element.role === "textfield" && element.value !== undefined && MASKED_VALUE.test(element.value) || element.role === "securefield" || traits.has("password") || traits.has("secure") || element.rawType.toLowerCase().includes("secure");
 }
 function deriveChecked(element, role, spelled, traits, value) {
   if (spelled?.checked !== undefined)
@@ -6298,6 +6299,9 @@ function getSession(opts = {}) {
   slot()[SESSION_KEY] = session;
   return session;
 }
+function peekSession() {
+  return slot()[SESSION_KEY];
+}
 
 // ../../packages/e2e/src/a11y/speech.ts
 var ACTIONABLE_ROLES = new Set([
@@ -9323,6 +9327,6 @@ function onlyWasSeen() {
 
 // ../../packages/e2e/src/version.ts
 var WORKSPACE_VERSION = "0.0.0-workspace";
-var WARDEN_E2E_VERSION2 = "0.12.0";
+var WARDEN_E2E_VERSION2 = "0.13.0";
 
-export { E2eError2, registerA11yTarget, a11yTargetOf, canActOnElements, noteSpanDetail, addSpanDetail, canObserve, canDetectAlerts, settleDetailOf, DEFAULT_SETTLE_QUIET_MS, DEFAULT_SETTLE_TIMEOUT_MS, settleByHash, snapshotHash, ok, err, swipeVector, screenRect, fieldValue, PINCH_MS, ROTATE_MS, PATH_MS, centreOf, pinchRadius, rotateRadius, requireGesture, assertScale, assertDegrees, isInteractiveRole, resolveRole, normalizeText, matchesText, indexSnapshot, testIdQuery, textQuery, roleQuery, selectorExpression, renderSnapshot, renderHeader, resolve, locateByTestIdViaReact, isLocator, Locator, pickOne, textOf, scrollUntilVisible, formatNativeTail, realNativeLogDeps, captureNativeLog, bunExec, execError, driverError, driverErr, logEventSchema, fatalEventSchema, responseSchema, mapWireError, createLineSplitter, encodeRequest, bunSpawn, stdioTransport, socketTransport, createSimdClient, spawnSimd, connectSimd, isRecoverableLoss, CAMERA_FACINGS, CONDITION_AREAS, resolveNetwork, resolveTextSize, androidFontScale, ENV_NAMES, DEFAULT_ASSERTION_TIMEOUT_MS, readEnv, runStep, setDefaultHidRecovery, setDefaultNativeLog, setDefaultDriverFactory, hasDefaultDriverFactory, setDefaultFixtureFactory, hasDefaultFixtureFactory, attemptSession, getSession, accessibleName, announce, failing, formatIssues, toE2eError, settled, unwrap, parseUiadA11yEvents, parseInjectEvents, withA11yRead, renderA11yScreen, createDeviceA11y, IOS_DEVICE_CAPABILITIES, sniffCameraMedia, cameraFeedDir, clearCameraFeeds, isLeaseAlive, processAlive, describeOwner, isPhysicalIosId, wardenHome, defaultDbPath, ownerKey, openStore, callerFile, formatCoord, DEFAULT_SPEED_MPS, DEFAULT_INTERVAL_S, realTickerClock, startRouteTicker, startFlap, registerConditions, conditionsOf, conditionSinkFor, createDeviceConditions, parseBudgets, createDevicePerf, perfStartFor, spawnWarden, hash6, attemptDir, screenshotPath, specIdOf, BUN_TIMEOUT_MARGIN_MS2, ownHook, currentScope, createScope, runInScope, hooksFor, resolveUse, registrationDefaults, markOnly, onlyWasSeen, WORKSPACE_VERSION, WARDEN_E2E_VERSION2 };
+export { E2eError2, registerA11yTarget, a11yTargetOf, canActOnElements, noteSpanDetail, addSpanDetail, canObserve, canDetectAlerts, settleDetailOf, DEFAULT_SETTLE_QUIET_MS, DEFAULT_SETTLE_TIMEOUT_MS, settleByHash, snapshotHash, ok, err, swipeVector, screenRect, fieldValue, PINCH_MS, ROTATE_MS, PATH_MS, centreOf, pinchRadius, rotateRadius, requireGesture, assertScale, assertDegrees, isInteractiveRole, resolveRole, normalizeText, matchesText, indexSnapshot, testIdQuery, textQuery, roleQuery, selectorExpression, renderSnapshot, renderHeader, resolve, locateByTestIdViaReact, isLocator, Locator, pickOne, textOf, scrollUntilVisible, formatNativeTail, realNativeLogDeps, captureNativeLog, bunExec, execError, driverError, driverErr, logEventSchema, fatalEventSchema, responseSchema, mapWireError, createLineSplitter, encodeRequest, bunSpawn, stdioTransport, socketTransport, createSimdClient, spawnSimd, connectSimd, isRecoverableLoss, parseDuration, CAMERA_FACINGS, CONDITION_AREAS, resolveNetwork, resolveTextSize, androidFontScale, ENV_NAMES, DEFAULT_ASSERTION_TIMEOUT_MS, readEnv, runStep, setDefaultHidRecovery, setDefaultNativeLog, setDefaultDriverFactory, hasDefaultDriverFactory, setDefaultFixtureFactory, hasDefaultFixtureFactory, attemptSession, getSession, peekSession, accessibleName, announce, failing, formatIssues, toE2eError, settled, unwrap, parseUiadA11yEvents, parseInjectEvents, withA11yRead, renderA11yScreen, createDeviceA11y, IOS_DEVICE_CAPABILITIES, sniffCameraMedia, cameraFeedDir, clearCameraFeeds, isLeaseAlive, processAlive, describeOwner, isPhysicalIosId, wardenHome, defaultDbPath, ownerKey, openStore, callerFile, formatCoord, DEFAULT_SPEED_MPS, DEFAULT_INTERVAL_S, realTickerClock, startRouteTicker, startFlap, registerConditions, conditionsOf, conditionSinkFor, createDeviceConditions, parseBudgets, createDevicePerf, perfStartFor, spawnWarden, hash6, attemptDir, screenshotPath, specIdOf, BUN_TIMEOUT_MARGIN_MS2, ownHook, currentScope, createScope, runInScope, hooksFor, resolveUse, registrationDefaults, markOnly, onlyWasSeen, WORKSPACE_VERSION, WARDEN_E2E_VERSION2 };

package/index.mjs

@@ -15,9 +15,11 @@ import {
   formatNativeTail,
   captureNativeLog,
   isRecoverableLoss,
+  parseDuration,
   runStep,
   attemptSession,
   getSession,
+  peekSession,
   accessibleName,
   announce,
   failing,
@@ -42,7 +44,7 @@ import {
   registrationDefaults,
   markOnly,
   WARDEN_E2E_VERSION2
-} from "./chunk-qz94hsb6.mjs";
+} from "./chunk-tnr47n9c.mjs";
 // ../../packages/e2e/src/expect/expect.ts
 import { expect as bunExpect } from "bun:test";
 
@@ -572,6 +574,116 @@ function createExpect(deps) {
   return call;
 }
 var expect = createExpect({ softSink: currentSoftSink });
+// ../../packages/e2e/src/run.ts
+var DEFAULT_TIMEOUT_MS = 60000;
+var MESSAGE_TAIL = 2000;
+var invalid = (message) => new E2eError2("INVALID_ARGUMENT", `run: ${message}`);
+function timeoutMs(value) {
+  if (value === undefined)
+    return DEFAULT_TIMEOUT_MS;
+  if (typeof value === "number") {
+    if (!Number.isFinite(value) || value <= 0)
+      throw invalid(`timeout must be over 0, got ${String(value)}`);
+    return value;
+  }
+  const parsed = parseDuration(value);
+  if (!parsed.success)
+    throw invalid(`timeout: ${parsed.error}`);
+  return parsed.data;
+}
+function argvOf(command) {
+  if (typeof command === "string") {
+    if (command.trim() === "")
+      throw invalid("command is empty");
+    return ["sh", "-c", command];
+  }
+  if (command.length === 0 || command[0] === "")
+    throw invalid("argv is empty");
+  return [...command];
+}
+var programOf = (command) => typeof command === "string" ? "sh -c" : command[0] ?? "";
+function envOf(extra) {
+  const merged = { ...process.env, ...extra };
+  const env = {};
+  for (const [key, value] of Object.entries(merged))
+    if (value !== undefined)
+      env[key] = value;
+  return env;
+}
+function tail(text) {
+  const trimmed = text.trim();
+  return trimmed.length > MESSAGE_TAIL ? `\u2026${trimmed.slice(-MESSAGE_TAIL)}` : trimmed;
+}
+function resultOf(exitCode, stdout, stderr, ms) {
+  return {
+    ok: exitCode === 0,
+    exitCode,
+    stdout,
+    stderr,
+    ms,
+    json() {
+      try {
+        return JSON.parse(stdout);
+      } catch {
+        throw invalid(`stdout is not JSON: ${tail(stdout).slice(0, 200) || "(empty)"}`);
+      }
+    }
+  };
+}
+async function exec(command, options) {
+  const argv = argvOf(command);
+  const limit = timeoutMs(options.timeout);
+  const started = Date.now();
+  let proc;
+  try {
+    proc = Bun.spawn(argv, {
+      cwd: options.cwd,
+      env: envOf(options.env),
+      stdin: "pipe",
+      stdout: "pipe",
+      stderr: "pipe"
+    });
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    throw new E2eError2("RUN_FAILED", `run: could not start ${programOf(command)}: ${reason}`);
+  }
+  if (options.input !== undefined)
+    proc.stdin.write(options.input);
+  await proc.stdin.end();
+  let timedOut = false;
+  const timer = setTimeout(() => {
+    timedOut = true;
+    proc.kill("SIGKILL");
+  }, limit);
+  try {
+    const [stdout, stderr, exitCode] = await Promise.all([
+      new Response(proc.stdout).text(),
+      new Response(proc.stderr).text(),
+      proc.exited
+    ]);
+    const result = resultOf(exitCode, stdout, stderr, Date.now() - started);
+    if (timedOut) {
+      throw new E2eError2("TIMEOUT", `run: ${programOf(command)} did not finish within ${limit} ms (killed)`);
+    }
+    if (!result.ok && options.check !== false) {
+      const output = tail(stderr) || tail(stdout);
+      throw new E2eError2("RUN_FAILED", `run: ${programOf(command)} failed with exit ${exitCode}${output === "" ? "" : `
+${output}`}`);
+    }
+    return result;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+function createRun(deps) {
+  return (command, options = {}) => deps.span("run", () => exec(command, options), {
+    verdict: (result) => result.ok ? { ok: true } : { ok: false, code: "RUN_FAILED" },
+    detail: (result) => ({ exitCode: result.exitCode })
+  });
+}
+var run = createRun({
+  span: (op, fn, options) => peekSession()?.span(op, fn, options) ?? fn()
+});
 // ../../packages/e2e/src/runner/test.ts
 import { afterAll as bunAfterAll, beforeAll as bunBeforeAll, describe as bunDescribe, test as bunTest } from "bun:test";
 
@@ -1277,5 +1389,6 @@ export {
   beforeEach,
   describe,
   expect,
+  run,
   test
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@delacour/warden-e2e",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "TypeScript e2e testing for React Native and Expo on iOS simulators and Android emulators, run by `warden e2e`: test, expect, screen, device, app",
   "license": "MIT",
   "repository": {
@@ -41,7 +41,7 @@
     "LICENSE"
   ],
   "peerDependencies": {
-    "@delacour/warden": "0.12.0"
+    "@delacour/warden": "0.13.0"
   },
   "dependencies": {
     "zod": "^4.4.3"

package/preload.mjs

@@ -109,7 +109,7 @@ import {
   onlyWasSeen,
   WORKSPACE_VERSION,
   WARDEN_E2E_VERSION2
-} from "./chunk-qz94hsb6.mjs";
+} from "./chunk-tnr47n9c.mjs";
 
 // ../../packages/e2e/src/preload.ts
 import { afterAll, setDefaultTimeout } from "bun:test";
@@ -7728,6 +7728,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 +7736,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 +7817,8 @@ function toSnapshot(data, takenAt) {
   };
   if (data.modal)
     snapshot.modal = data.modal;
+  if (data.fallback?.from === "axbridge")
+    snapshot.fellBackFrom = "axbridge";
   return snapshot;
 }
 
@@ -8401,6 +8404,9 @@ 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 GESTURE_MARGIN_MS = 5000;
 var FRONTMOST_TIMEOUT_MS = 3000;
 var LAUNCH_TIMEOUT_MS = 30000;
@@ -8490,6 +8496,32 @@ function noteHelperHealth(health) {
   if (health.frontmost)
     noteSpanDetail("frontmostUnresolvedAgoMs", health.frontmost.unresolvedAgoMs);
 }
+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");
   noteSpanDetail("rebindMs", data.waitedMs);
@@ -8562,6 +8594,7 @@ function createIosDriver(swap, simctl, opts) {
   let settleUnsupported = !nativeSettle;
   let settleAxFailures = 0;
   let rebindUnsupported = false;
+  let bridgeProven = false;
   let gestureUnsupported = false;
   let appOpsOutdated = false;
   const capabilities = {
@@ -8681,7 +8714,7 @@ function createIosDriver(swap, simctl, opts) {
     }
     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 +8735,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")
@@ -8762,6 +8808,8 @@ function createIosDriver(swap, simctl, opts) {
       return false;
     }
     noteRebind(reply.data);
+    if (reply.data.bound)
+      bridgeProven = true;
     return reply.data.bound;
   }
   function noteSettleAxFailure(message) {
@@ -9082,6 +9130,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),
@@ -10485,11 +10534,13 @@ var EXCERPT_LINES = 40;
 var MAX_ALERT_ANSWERS = 3;
 var REACT_THROTTLE_MS = 450;
 var REACT_TIMEOUT_MS = 2000;
+var FIRST_READER_RETRY_MS = 5000;
 
 class Runtime {
   host;
   reactCache;
   indexed = new WeakMap;
+  firstReaderRetryAt = 0;
   constructor(host) {
     this.host = host;
   }
@@ -10529,19 +10580,30 @@ class Runtime {
       const result = canObserve(driver) ? await driver.observe({ reuse }) : await driver.snapshot();
       if (!result.success)
         return { ok: false, error: result.error };
+      const snapshot = await this.restoreDegraded(driver, 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;
     }
   }
+  async restoreDegraded(driver, snapshot) {
+    const first = snapshot.fellBackFrom;
+    if (first === undefined || this.clock.now() < this.firstReaderRetryAt)
+      return snapshot;
+    const again = await driver.snapshot({ backend: first });
+    if (again.success && again.data.backend === first)
+      return again.data;
+    this.firstReaderRetryAt = this.clock.now() + FIRST_READER_RETRY_MS;
+    return snapshot;
+  }
   earlierThan(driver, before, look) {
     const after = canObserve(driver) ? driver.previous?.() : undefined;
     const same = after !== undefined && after.generation === before.generation && after.snapshot === look;

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/driver.types.d.ts

@@ -134,6 +134,11 @@ 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.
+     */
+    fellBackFrom?: SnapshotBackend;
 };
 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,13 @@ 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;
 /** 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 +102,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/errors.d.ts

@@ -1,5 +1,5 @@
 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";
 /** Plain shape of a spec error: what `e2eErr()` accepts and what a `Result` carries. */
 export type E2eErrorShape = {
     code: E2eErrorCode;

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/screen/context.d.ts

@@ -78,6 +78,8 @@ export declare class Runtime {
     private reactCache;
     /** the index of each snapshot, so a snapshot that several reads share is indexed once */
     private readonly indexed;
+    /** the time before which a degraded look is not retried on its first reader, after that reader failed to answer */
+    private firstReaderRetryAt;
     constructor(host: ScreenHost);
     get clock(): Clock;
     actionTimeout(): number;
@@ -95,6 +97,14 @@ export declare class Runtime {
      * `systemAlerts` on, an alert the screen shows is answered and the screen looked at again.
      */
     tryObserve(options?: ObserveOptions): Promise<Observation>;
+    /**
+     * A snapshot the driver answered from a fallback reader (`Snapshot.fellBackFrom`, iOS `ax` after `axbridge` stalled)
+     * can lack what the first reader has: React Native testIDs on static text. Such a look is read once more on the
+     * first reader, and that read replaces it when it answers. When it does not (the guest is still silent) the
+     * fallback snapshot stands and the first reader is left alone for `FIRST_READER_RETRY_MS`, so a dead guest costs a
+     * poll one deadline, not one per attempt. Every locator and matcher looks through here, so none needs its own rule.
+     */
+    private restoreDegraded;
     /** What came before `look`, given the cache's answer from just before it was taken. */
     private earlierThan;
     /** Whether `snapshot` showed an alert that has now been answered. A screen without one costs no extra read. */

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

@@ -123,5 +123,7 @@ export type AttemptBinding = {
 export declare function attemptSession(session: Session, binding: () => AttemptBinding): Session;
 /** The process-wide session (`globalThis[Symbol.for("./session")]`), created on first call. */
 export declare function getSession(opts?: SessionOptions): Session;
+/** The process-wide session if one exists; never creates one (so a caller outside a test opens no device). */
+export declare function peekSession(): Session | undefined;
 /** Closes and forgets the process-wide session, if any. */
 export declare function resetSession(): Promise<void>;