@delacour/warden-e2e 0.6.0 → 0.7.0

package/types/core/src/ios-runner/runner-build.types.d.ts

@@ -0,0 +1,76 @@
+import type { AsyncResult } from "../../../types/src/result";
+import type { BuildLockDeps } from "../builds/lock";
+import type { Exec } from "../exec";
+/** Codes `classify.ts` and `signing.ts` give a failure that has a known fix; every one comes with a `hint`. */
+export declare const CLASSIFIED_RUNNER_ERRORS: readonly ["no_account", "no_team", "ios_team_ambiguous", "bundle_id_taken", "device_locked", "developer_mode_off", "runner_untrusted", "ui_automation_disabled", "device_busy", "ddi_unavailable", "unsupported_os"];
+export type ClassifiedRunnerErrorCode = (typeof CLASSIFIED_RUNNER_ERRORS)[number];
+/** A team the keychain holds an `Apple Development` identity for. */
+export type SigningTeam = {
+    teamId: string;
+    identities: string[];
+};
+type RunnerErrorBase = {
+    message: string;
+    hint: string;
+};
+/**
+ * Why the on-device runner cannot be built / signed / started. `hint` is the one thing to do about it.
+ * `ios_team_ambiguous` carries the teams to pick from; `build_failed` is anything unclassified (with the
+ * tail of the output).
+ */
+export type RunnerBuildError = (RunnerErrorBase & {
+    code: Exclude<ClassifiedRunnerErrorCode, "ios_team_ambiguous">;
+}) | (RunnerErrorBase & {
+    code: "ios_team_ambiguous";
+    teams: SigningTeam[];
+}) | (RunnerErrorBase & {
+    code: "build_failed";
+    output: string;
+});
+export type RunnerBuildErrorCode = RunnerBuildError["code"];
+/** Where the signing team came from. */
+export type TeamSource = "input" | "env" | "config" | "keychain";
+/** The runner sources as a map of path (relative to the staged root, `/`-separated) to text. */
+export type RunnerSourceFiles = Readonly<Record<string, string>>;
+export type EnsureRunnerBuildInput = {
+    /** the phone the runner must be signed for (`-destination id=`; registers it in the provisioning profile) */
+    udid: string;
+    /** signing team; default: `WARDEN_IOS_TEAM_ID`, then `ios.teamId`, then the keychain */
+    team?: string | undefined;
+    /** `ios.teamId` of `warden.config.ts` */
+    configTeamId?: string | undefined;
+    /** `ios.runnerBundleId` of `warden.config.ts` */
+    configBundleId?: string | undefined;
+    env: Record<string, string | undefined>;
+    /** `$WARDEN_HOME` (default: from `env`) */
+    home?: string | undefined;
+    exec: Exec;
+    /** warden's own version (part of the staged-source directory name) */
+    version: string;
+    /** the embedded runner sources (blob in a compiled binary, the checkout when run from source) */
+    loadSources: () => AsyncResult<RunnerSourceFiles>;
+    /** serialises builds of one (team, Xcode, sources): the build lease */
+    lock: BuildLockDeps;
+    now?: () => number;
+    /** progress lines (xcodebuild's own output is not forwarded) */
+    log?: (line: string) => void;
+    /** `xcodebuild` is stopped after this long (default 15 min) */
+    timeoutMs?: number;
+    /** after xcodebuild asks to unlock the phone, wait this long before giving up with `device_locked` (default 45 s) */
+    lockGraceMs?: number;
+};
+/** A runner build ready for `xcodebuild test-without-building -xctestrun <xctestrun>`. */
+export type RunnerBuild = {
+    /** the `.xctestrun` inside `derivedData` */
+    xctestrun: string;
+    derivedData: string;
+    /** the host app's bundle id (the UI-test bundle is `<id>.uitests`, its runner app `<id>.uitests.xctrunner`) */
+    bundleId: string;
+    team: string;
+    teamSource: TeamSource;
+    /** false: built just now */
+    cached: boolean;
+    /** why it was (re)built when `cached` is false */
+    rebuiltBecause?: "none" | "new_udid" | "profile_expiring" | "bundle_id" | "missing";
+};
+export {};

package/types/core/src/netproxy/control.d.ts

@@ -0,0 +1,75 @@
+import { type AsyncResult } from "../../../types/src/result";
+import { z } from "zod";
+import type { HostFault } from "../conditions/conditions.types";
+import type { ProxyConditions, ShapingParams } from "./shaping";
+/** Where a running proxy listens and how to steer it. Persisted as JSON so another process can find it. */
+export type ProxyHandle = {
+    pid: number;
+    /** loopback address the proxy and control channel bind */
+    host: string;
+    /** the forward proxy: what a device's HTTP proxy setting points at */
+    port: number;
+    /** loopback HTTP control channel */
+    controlPort: number;
+    /** required as `x-warden-token` on every control call */
+    token: string;
+};
+export type ProxyStats = {
+    connections: number;
+    resets: number;
+    stalls: number;
+    faulted: number;
+    bytesUp: number;
+    bytesDown: number;
+};
+export type ProxyStatus = ProxyConditions & {
+    pid: number;
+    stats: ProxyStats;
+};
+/** Replace `params` and/or `faults`; an omitted field keeps its current value. */
+export type ConditionsUpdate = {
+    params?: ShapingParams;
+    faults?: readonly HostFault[];
+};
+export declare const conditionsUpdateSchema: z.ZodObject<{
+    params: z.ZodOptional<z.ZodObject<{
+        latencyMs: z.ZodOptional<z.ZodNumber>;
+        jitterMs: z.ZodOptional<z.ZodNumber>;
+        downKbps: z.ZodOptional<z.ZodNumber>;
+        upKbps: z.ZodOptional<z.ZodNumber>;
+        lossPct: z.ZodOptional<z.ZodNumber>;
+        offline: z.ZodOptional<z.ZodEnum<{
+            blackhole: "blackhole";
+            refuse: "refuse";
+        }>>;
+    }, z.core.$strict>>;
+    faults: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        match: z.ZodString;
+        action: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: z.ZodLiteral<"status">;
+            code: z.ZodNumber;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"reset">;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"delay">;
+            ms: z.ZodNumber;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"blackhole">;
+        }, z.core.$strict>], "kind">;
+    }, z.core.$strict>>>;
+}, z.core.$strict>;
+/** What the control server needs from the proxy it steers. */
+export type ControlApi = {
+    status(): ProxyStatus;
+    update(update: ConditionsUpdate): void;
+    shutdown(): void;
+};
+/** Loopback HTTP control channel: `GET /status`, `PUT /conditions`, `POST /shutdown`; token-guarded. */
+export declare function serveControl(api: ControlApi, token: string, host: string): Bun.Server<undefined>;
+/** Live-reconfigure a running proxy without dropping its listener or open connections. */
+export declare function setProxyConditions(handle: ProxyHandle, update: ConditionsUpdate): AsyncResult<ProxyStatus>;
+export declare function getProxyStatus(handle: ProxyHandle): AsyncResult<ProxyStatus>;
+/** Ask the proxy to close its listeners and exit. */
+export declare function stopProxy(handle: ProxyHandle): AsyncResult<{
+    ok: true;
+}>;

package/types/core/src/netproxy/decide.d.ts

@@ -0,0 +1,22 @@
+import type { ProxyEvent } from "./proxy";
+import { type ProxyConditions, type Rng } from "./shaping";
+/** What to do with one request once its target host is known. */
+export type Verdict = {
+    act: {
+        kind: "reset";
+    } | {
+        kind: "hold";
+    } | {
+        kind: "status";
+        code: number;
+    } | {
+        kind: "go";
+    };
+    /** delay before the act: params latency (+ a `delay` fault) */
+    waitMs: number;
+    event?: ProxyEvent;
+    /** which counter to bump */
+    count?: "faulted" | "resets";
+};
+/** Faults first (first glob match wins), then connection loss, then plain latency. */
+export declare function decide(conditions: ProxyConditions, host: string, isConnect: boolean, rng: Rng): Verdict;

package/types/core/src/netproxy/handle-file.d.ts

@@ -0,0 +1,12 @@
+import type { ProxyHandle } from "./control";
+/** `$WARDEN_HOME/netproxy/<leaseId>.json`: how another warden process finds a lease's proxy. */
+export declare function handlePath(leaseId: string, env?: Record<string, string | undefined>): string;
+/** What `netproxy.main.ts` writes once it is listening. `portLeaseId` is added by `ensureLeaseProxy`. */
+export type HandleFile = ProxyHandle & {
+    leaseId: string;
+    portLeaseId?: string;
+};
+/** Atomic (tmp + rename) and owner-only: the file carries the control token. */
+export declare function writeHandleFile(path: string, data: HandleFile): void;
+export declare function readHandleFile(path: string): HandleFile | undefined;
+export declare function removeHandleFile(path: string): void;

package/types/core/src/netproxy/lease-proxy.d.ts

@@ -0,0 +1,53 @@
+import { type AsyncResult } from "../../../types/src/result";
+import type { NetworkCondition } from "../conditions/conditions.types";
+import { type PidAlive } from "../liveness";
+import type { Store } from "../store";
+import type { Lease } from "../types";
+import { type ProxyHandle } from "./control";
+import type { ProxyConditions } from "./shaping";
+/** Where lease proxies listen unless told otherwise. */
+export declare const DEFAULT_PROXY_PORTS: {
+    readonly from: 19080;
+    readonly span: 200;
+};
+export type LeaseProxyDeps = {
+    store: Store;
+    env: Record<string, string | undefined>;
+    now: () => number;
+    pidAlive?: PidAlive;
+    isPortFree?: (port: number) => Promise<boolean>;
+    /** argv prefix that runs `netproxy.main.ts` (the JSON argument is appended). Default: `bun` + the script next to this file; a compiled `warden` passes its own hidden subcommand. */
+    command?: readonly string[];
+    /** start argv detached and return its pid; default: `child_process.spawn` detached with no stdio */
+    spawn?: (argv: readonly string[], env: Record<string, string | undefined>) => number | undefined;
+    kill?: (pid: number) => void;
+    ports?: {
+        from: number;
+        span: number;
+    };
+    readyTimeoutMs?: number;
+};
+/** The proxy a lease owns, and the port lease holding its port. */
+export type LeaseProxy = {
+    handle: ProxyHandle;
+    portLeaseId: string;
+    reused: boolean;
+};
+export type EnsureProxyInput = {
+    /** what `recordCondition` stores for the `network` area */
+    condition: NetworkCondition;
+    /** shaping to apply now (already translated from `condition`) */
+    conditions: ProxyConditions;
+    /** seeds loss/jitter for a reproducible run */
+    seed?: number;
+};
+/**
+ * Make sure `lease` has a shaping proxy and apply `input.conditions` to it. Reuses a live one
+ * (reconfigured over its control channel, no restart); otherwise claims a port from the allocator,
+ * spawns a detached `netproxy.main.ts`, waits until it answers, and records the `network` condition
+ * with the proxy pid as an `OwnedProcess` so release / gc undo kills it. The port lease's pid is
+ * the proxy's, so a dead proxy frees its port. Binds 127.0.0.1 only.
+ */
+export declare function ensureLeaseProxy(deps: LeaseProxyDeps, lease: Pick<Lease, "id" | "owner" | "ttlMs">, input: EnsureProxyInput): AsyncResult<LeaseProxy>;
+/** Stop a lease's proxy (control channel, then SIGTERM) and free its port; true when one was recorded. */
+export declare function releaseLeaseProxy(deps: Pick<LeaseProxyDeps, "store" | "env" | "kill" | "pidAlive">, leaseId: string): Promise<boolean>;

package/types/core/src/netproxy/netproxy.main.d.ts

@@ -0,0 +1,40 @@
+import { z } from "zod";
+declare const argvSchema: z.ZodObject<{
+    leaseId: z.ZodString;
+    handleFile: z.ZodString;
+    port: z.ZodNumber;
+    conditions: z.ZodOptional<z.ZodObject<{
+        params: z.ZodOptional<z.ZodObject<{
+            latencyMs: z.ZodOptional<z.ZodNumber>;
+            jitterMs: z.ZodOptional<z.ZodNumber>;
+            downKbps: z.ZodOptional<z.ZodNumber>;
+            upKbps: z.ZodOptional<z.ZodNumber>;
+            lossPct: z.ZodOptional<z.ZodNumber>;
+            offline: z.ZodOptional<z.ZodEnum<{
+                blackhole: "blackhole";
+                refuse: "refuse";
+            }>>;
+        }, z.core.$strict>>;
+        faults: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            match: z.ZodString;
+            action: z.ZodDiscriminatedUnion<[z.ZodObject<{
+                kind: z.ZodLiteral<"status">;
+                code: z.ZodNumber;
+            }, z.core.$strict>, z.ZodObject<{
+                kind: z.ZodLiteral<"reset">;
+            }, z.core.$strict>, z.ZodObject<{
+                kind: z.ZodLiteral<"delay">;
+                ms: z.ZodNumber;
+            }, z.core.$strict>, z.ZodObject<{
+                kind: z.ZodLiteral<"blackhole">;
+            }, z.core.$strict>], "kind">;
+        }, z.core.$strict>>>;
+    }, z.core.$strict>>;
+    seed: z.ZodOptional<z.ZodNumber>;
+    portLeaseId: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+/** Argv for this entry: one JSON argument (`NetproxyMainArgs`). */
+export type NetproxyMainArgs = z.input<typeof argvSchema>;
+/** Run a detached proxy: parse the JSON argument, listen, publish the handle file, exit on SIGTERM / `POST /shutdown`. */
+export declare function runNetproxy(raw: string): Promise<void>;
+export {};

package/types/core/src/netproxy/pipe.d.ts

@@ -0,0 +1,37 @@
+import type { Socket } from "node:net";
+export type PipeOptions = {
+    /** bandwidth cap read per slice, so a live change applies to the next one */
+    kbps: () => number | undefined;
+    /** delay for the next chunk, read per chunk */
+    delay: () => number;
+    now: () => number;
+    /** bytes written to `dest` */
+    onBytes: (n: number) => void;
+};
+/**
+ * One direction of a shaped connection. Chunks keep order; each waits out its own latency (pipelined,
+ * not serial), then goes out in slices at the bandwidth cap. Driven by one timer at a time, never polled.
+ */
+export declare class Pipe {
+    private readonly src;
+    private readonly dest;
+    private readonly opts;
+    private queue;
+    private queued;
+    private lastNotBefore;
+    private timer;
+    private bucket;
+    private finished;
+    private stopped;
+    private draining;
+    constructor(src: Socket, dest: Socket, opts: PipeOptions);
+    push(data: Buffer): void;
+    /** The source ended: close `dest` once everything queued is out. */
+    finish(): void;
+    stop(): void;
+    private wake;
+    /** What the head of the queue needs next: nothing, a wait (latency or bandwidth), or a send. */
+    private next;
+    private send;
+    private pump;
+}

package/types/core/src/netproxy/proxy.d.ts

@@ -0,0 +1,48 @@
+import { type ConditionsUpdate, type ProxyHandle, type ProxyStats } from "./control";
+import { type ProxyConditions, type Rng } from "./shaping";
+/** Something notable the proxy did; `https-status-as-reset` is the CONNECT fallback for a `status` fault. */
+export type ProxyEvent = {
+    kind: "fault";
+    host: string;
+    action: "status" | "reset" | "delay" | "blackhole";
+    note?: "https-status-as-reset";
+} | {
+    kind: "loss";
+    outcome: "reset" | "stall";
+    host: string;
+} | {
+    kind: "offline";
+    mode: "refuse" | "blackhole";
+};
+export type StartProxyOptions = {
+    /** listen port; 0 (default) = random */
+    port?: number;
+    conditions?: Partial<ProxyConditions>;
+    /** drives loss and jitter; default `Math.random` */
+    rng?: Rng;
+    now?: () => number;
+    /** map the requested origin to where to actually connect (tests point fake hosts at local servers) */
+    resolve?: (host: string, port: number) => {
+        host: string;
+        port: number;
+    };
+    onEvent?: (event: ProxyEvent) => void;
+    /** fixed control token (default random) */
+    token?: string;
+    /** called after `POST /shutdown` has closed the proxy (a detached entry exits here) */
+    onShutdown?: () => void;
+};
+export type RunningProxy = {
+    handle: ProxyHandle;
+    conditions(): ProxyConditions;
+    setConditions(update: ConditionsUpdate): void;
+    stats(): ProxyStats;
+    /** resolves once listeners and every open connection are closed */
+    close(): Promise<void>;
+};
+/**
+ * Start a shaping forward proxy on loopback: plain-HTTP absolute-URI requests and HTTPS `CONNECT`
+ * tunnels (bytes only, no TLS interception). Conditions can change at any time via `setConditions`
+ * or the control channel in `handle`; new connections and the next slice of open ones follow.
+ */
+export declare function startProxy(options?: StartProxyOptions): Promise<RunningProxy>;

package/types/core/src/netproxy/shaping.d.ts

@@ -0,0 +1,43 @@
+import type { HostFault, NetworkCondition } from "../conditions/conditions.types";
+import { type NetworkShaping } from "../conditions/network.presets";
+/** How an `offline` proxy treats connections: close at accept, or accept and never answer. */
+export type OfflineMode = "refuse" | "blackhole";
+/**
+ * What the proxy does to traffic: the shared `NetworkShaping` fields (all optional here; unset / 0 = no
+ * limit, delay or loss) plus `offline`. `latencyMs` is the added round trip: the full amount at connection
+ * open, half on each direction's chunks. `jitterMs` spreads each delay by +/- that much (halved per chunk).
+ * `lossPct` (0-100) resets or stalls (half each) a connection at open.
+ */
+export type ShapingParams = Partial<NetworkShaping> & {
+    offline?: OfflineMode;
+};
+/** Proxy params for a condition (presets table); `offline` refuses connections. Faults are separate. */
+export declare function shapingFromCondition(condition: NetworkCondition): ShapingParams;
+/** The live state of a proxy: what `setProxyConditions` replaces. */
+export type ProxyConditions = {
+    params: ShapingParams;
+    faults: readonly HostFault[];
+};
+export declare const NO_CONDITIONS: ProxyConditions;
+/** Uniform [0, 1); injectable so loss and jitter are reproducible in tests. */
+export type Rng = () => number;
+/** mulberry32: tiny seeded PRNG. */
+export declare function seededRng(seed: number): Rng;
+/** `(latencyMs ± jitterMs) * scale`, floored at 0. */
+export declare function delayMs(params: ShapingParams, rng: Rng, scale?: number): number;
+/** `*` matches any run of characters; case-insensitive; the whole host must match. */
+export declare function hostMatches(glob: string, host: string): boolean;
+/** First fault whose glob matches `host`. */
+export declare function faultFor(faults: readonly HostFault[], host: string): HostFault | undefined;
+/**
+ * Serialises sends at a fixed rate: `waitMs` says how long until the next `bytes` may go out, and
+ * `take` books them. The rate is read per call, so a live change applies to the next slice.
+ */
+export declare class TokenBucket {
+    private nextFree;
+    /** ms until `bytes` may be sent at `kbps` (0 = now); unlimited when `kbps` is unset or ≤ 0 */
+    waitMs(now: number): number;
+    take(bytes: number, kbps: number | undefined, now: number): void;
+}
+/** Slice size giving ~50 ms granularity at `kbps`, within 256 B – 64 KB. */
+export declare function sliceSize(kbps: number | undefined): number;

package/types/core/src/providers/android.d.ts

@@ -16,7 +16,24 @@ export type AdbEmulator = {
     port: number;
     state: string;
 };
-/** Parse `adb devices -l`, keeping only `emulator-<port>` serials (physical devices ignored). */
+/** One `adb devices -l` row: a console emulator, or anything else (a phone, or a network emulator until `classifyOther`). */
+export type AdbListEntry = ({
+    kind: "emulator";
+} & AdbEmulator) | {
+    kind: "other";
+    serial: string;
+    state: string;
+    transport: "usb" | "wifi";
+    model?: string;
+    product?: string;
+};
+/**
+ * Parse `adb devices -l`. A state may be several words (`no permissions (…); see [url]`), so the state is
+ * the first token unless the row says `no permissions`. Transport: a `usb:` attribute is usb; `ip:port` and
+ * `_adb-tls-connect._tcp` serials (and anything else without `usb:`) are wifi.
+ */
+export declare function parseAdbDeviceList(stdout: string): AdbListEntry[];
+/** Parse `adb devices -l`, keeping only `emulator-<port>` serials (phones and network emulators ignored). */
 export declare function parseAdbDevices(stdout: string): AdbEmulator[];
 /** Parse `emulator -list-avds`, dropping the emulator's own `INFO | …` / `WARNING | …` log lines. */
 export declare function parseAvdList(stdout: string): string[];
@@ -38,8 +55,24 @@ export declare const LIST_AVDS_TIMEOUT_MS = 15000;
 export declare function listAvds(deps: ExecDeps, opts?: {
     fresh?: boolean;
 }): AsyncResult<string[]>;
+/** Every row of `adb devices -l`: emulators, phones and network emulators. */
+export declare function listAdbDevices(deps: ExecDeps): AsyncResult<AdbListEntry[]>;
 /** Running emulators from `adb devices -l`. */
 export declare function listEmulators(deps: ExecDeps): AsyncResult<AdbEmulator[]>;
+export type OtherClass = {
+    emulator: boolean;
+    hwSerial?: string;
+    model?: string;
+    sdk?: string;
+};
+/**
+ * Is a non-`emulator-N` adb serial a real phone? `localhost:5555` / Genymotion / a network emulator set
+ * `ro.boot.qemu` or `ro.kernel.qemu` to 1: a foreign emulator, never physical. One bounded read; a failure
+ * is an error, not a guess.
+ */
+export declare function classifyOther(deps: ExecDeps, serial: string): AsyncResult<OtherClass>;
+/** Is `id` a console emulator serial; anything else is a phone (or a network emulator), which warden never boots, kills or writes settings to. */
+export declare function isEmulatorSerial(id: string): boolean;
 /** Launch `cmd` so it outlives warden, stdout/stderr appended to `logPath`. */
 export type SpawnDetached = (cmd: readonly string[], logPath: string) => AsyncResult<{
     pid: number;
@@ -66,6 +99,8 @@ export type AndroidProviderOptions = {
 };
 /** One `adb shell` that returns once the guest has booted; POSIX `sh` (toybox `[`). */
 export declare const BOOT_WAIT_SCRIPT = "while [ \"$(getprop sys.boot_completed)\" != 1 ]; do sleep 0.2; done";
+/** One shell: qemu props (emulator tell-tales), hardware serial, model, SDK level — one value per line. */
+export declare const PHONE_PROBE_SCRIPT = "getprop ro.boot.qemu; getprop ro.kernel.qemu; getprop ro.serialno; getprop ro.product.model; getprop ro.build.version.sdk";
 /** The last 3 lines of an emulator log, one line. */
 export declare function logTail(logPath: string): string;
 /**

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

@@ -1,9 +1,38 @@
 export type Platform = "ios" | "android";
+/** Facts about a real phone/tablet, from its provider. Only physical devices carry one. */
+export type PhysicalInfo = {
+    platform: "android";
+    transport: "usb" | "wifi";
+    adbState: string;
+    hwSerial?: string;
+    model?: string;
+} | {
+    platform: "ios";
+    transport: "wired" | "localNetwork";
+    deviceType: string;
+    osVersion: string;
+    developerMode: boolean;
+    ddi: boolean;
+    tunnelIp?: string;
+    /** devicectl's pairing state when it is not `paired` (the reason the device is not ready) */
+    pairingState?: string;
+    /** devicectl's `tunnelState` (`connected` = reachable now); a `localNetwork` phone is often `disconnected` until something talks to it */
+    tunnelState?: string;
+    /** why a paired phone cannot be reached right now (its `lockState` probe failed); set means never auto-picked */
+    unreachable?: string;
+    /** `lockState.passcodeRequired` from the reachability probe (true = locked); only set when that probe ran and answered */
+    locked?: boolean;
+};
 export type DeviceResource = {
     kind: "device";
     platform: Platform;
     id: string;
     name: string;
+    /** set on leases of real devices; id stays the transport id (adb serial / CoreDevice UDID) */
+    physical?: {
+        transport: string;
+        hwSerial?: string;
+    };
 };
 export type PortResource = {
     kind: "port";
@@ -73,6 +102,8 @@ export type InventoryDevice = {
     golden?: boolean;
     /** reported bad: never allocated until `warden sim unquarantine` */
     quarantined?: boolean;
+    /** a real phone/tablet: never booted, shut down, created, adopted, counted in capacity or recorded as a warden device */
+    physical?: PhysicalInfo;
 };
 export type DeviceRequest = {
     platform: Platform;
@@ -83,6 +114,12 @@ export type DeviceRequest = {
     max: number;
     /** allow allocating foreign (non-warden) devices that match the profile */
     adopt?: boolean;
+    /** opt-in: only physical devices (optionally just these ids), never create or boot */
+    physical?: {
+        ids?: string[];
+        /** allowlist: with no `ids`, only these devices are picked (`physical.allow` / `WARDEN_PHYSICAL_IDS`); `ids` beat it */
+        allow?: string[];
+    };
 };
 export type AllocationStep = {
     action: "reuse";
@@ -124,3 +161,13 @@ export type QueueEntry = {
     label?: string;
     pid?: number;
 };
+/** The one constructor of a device lease resource: carries `physical` for real devices. */
+export declare function deviceResourceOf(d: InventoryDevice): DeviceResource;
+/** An iPhone/iPad hardware UDID: `XXXXXXXX-XXXXXXXXXXXXXXXX` or 40 hex (older devices); a simulator UUID is neither. */
+export declare function isPhysicalIosId(id: string): boolean;
+/** A device warden may not boot, shut down, create, erase or count in host capacity. */
+export declare function isPhysicalDevice(d: Pick<InventoryDevice, "physical">): boolean;
+/** Is a physical device usable now: an Android phone in adb state `device`, an iOS device its provider reports `booted` (paired and available). */
+export declare function isPhysicalReady(d: InventoryDevice): boolean;
+/** Why a physical device cannot be used now (undefined = ready, or not a phone), as `<label>: <hint>`; `devices` and a failed claim print it. */
+export declare function physicalNotReadyReason(d: InventoryDevice): string | undefined;

package/types/e2e/src/alert-buttons.d.ts

@@ -39,3 +39,12 @@ export declare const ANDROID_ALLOW_IDS: readonly string[];
  * `AlertDialog`'s negative `button2` (after the names).
  */
 export declare const ANDROID_DENY_IDS: readonly string[];
+/**
+ * The ids of the Android autofill "Save password?" sheet's buttons (`autofill_save_no` "Never", `autofill_save_yes`
+ * "Continue"). Either one marks the sheet, in any locale. Its two answers write to the user's account ("Never" a
+ * permanent opt-out, "Continue" a stored password), so `device.alert` never presses them: both `accept` and `dismiss`
+ * close the sheet with the Back key.
+ */
+export declare const ANDROID_AUTOFILL_SAVE_IDS: readonly string[];
+/** Whether `buttons` belong to the Android autofill save sheet. */
+export declare function isAutofillSaveSheet(buttons: readonly Element[]): boolean;

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

@@ -58,5 +58,7 @@ export type AppDeps = {
     log?: (line: string) => void;
     /** time for the `wait: "quiet"` content poll; default the system clock */
     clock?: Clock;
+    /** whether an iOS launch loads the warden network dylib (the suite declares a network or clock condition, or one is active) */
+    injectWanted?: () => boolean;
 };
-export declare function createApp({ session, driver, env, log, clock }: AppDeps): App;
+export declare function createApp({ session, driver, env, log, clock, injectWanted }: AppDeps): App;

package/types/e2e/src/conditions/condition-events.d.ts

@@ -0,0 +1,63 @@
+import type { A11yCondition, BatteryCondition, ClockCondition, HostFault, LocaleCondition, LocationCondition, NetworkCondition, PermissionCondition } from "../../../core/src/conditions/conditions.types";
+/**
+ * One applied condition transition, the evidence line that lets a failure show which network/location was
+ * active. Written to `results.jsonl` beside the test results (`readResults` skips lines that are not a
+ * `TestResult`, so the two kinds share the file).
+ */
+export type ConditionEvent = {
+    type: "condition";
+    area: "network";
+    value: NetworkCondition;
+    at: number;
+} | {
+    type: "condition";
+    area: "location";
+    value: LocationCondition;
+    at: number;
+} | {
+    type: "condition";
+    area: "clock";
+    value: ClockCondition;
+    at: number;
+} | {
+    type: "condition";
+    area: "permission";
+    value: PermissionCondition;
+    at: number;
+} | {
+    type: "condition";
+    area: "locale";
+    value: LocaleCondition;
+    at: number;
+} | {
+    type: "condition";
+    area: "a11y";
+    value: A11yCondition;
+    at: number;
+} | {
+    type: "condition";
+    area: "battery";
+    value: BatteryCondition;
+    at: number;
+} | {
+    type: "condition";
+    area: "faults";
+    value: {
+        kind: "faults";
+        rules: readonly HostFault[];
+    };
+    at: number;
+};
+export type ConditionSink = (event: ConditionEvent) => void;
+/** A sink that appends each event as one JSON line (`appendFileSync`: a crash never loses an earlier line). */
+export declare function openConditionSink(path: string): ConditionSink;
+/** Condition events in file order; every other line (test results, blank, truncated) is skipped. */
+export declare function readConditionEvents(text: string): ConditionEvent[];
+/** What was active per area at epoch ms `at`: the latest event at or before it. */
+export declare function activeConditionsAt(events: readonly ConditionEvent[], at: number): {
+    network?: NetworkCondition;
+    location?: LocationCondition;
+    clock?: ClockCondition;
+};
+/** The `kind` of an event's value (`offline`, `point`, ...); the area name for a setting that has none (`permission`, `a11y`). */
+export declare function eventKind(event: ConditionEvent): string;