@delacour/warden-e2e 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,23 @@
+import { type PidAlive } from "./liveness";
+import type { AllocationPlan, DeviceRequest, InventoryDevice, Lease } from "./types";
+export type AllocateInput = {
+    inventory: InventoryDevice[];
+    leases: Lease[];
+    request: DeviceRequest;
+    now: number;
+    pidAlive: PidAlive;
+    /** device ids to leave out this round (failed their health probe in this claim) */
+    skip?: ReadonlySet<string>;
+};
+/** `iPhone 17 Pro` → `iphone-17-pro`. */
+export declare function profileSlug(name: string): string;
+export declare function wardenDeviceName(profile: string, index: number): string;
+/** cores/4, at least 1, capped at 4 (salient's shard heuristic). */
+export declare function defaultMax(cores: number): number;
+export declare function compareRuntimeDesc(a: InventoryDevice, b: InventoryDevice): number;
+/**
+ * Pure allocation: which devices satisfy `request` given current leases. Free warden devices first
+ * (booted before shutdown, newest runtime first), then pool growth up to `max`. Foreign devices are
+ * only considered with `adopt`. Stale leases are ignored and returned for reclaim.
+ */
+export declare function allocate({ inventory, leases, request, now, pidAlive, skip }: AllocateInput): AllocationPlan;

package/types/core/src/builds/app-option.schema.d.ts

@@ -0,0 +1,37 @@
+import { z } from "zod";
+/**
+ * What to do with the app's installed state before a run:
+ * - unset: install only when the device lacks this build; a different build is installed over the old one.
+ * - `"clean"`: fresh app data every run without reinstalling an unchanged build.
+ * - `"reinstall"`: uninstall, then install, every run.
+ */
+export declare const installModeSchema: z.ZodEnum<{
+    clean: "clean";
+    reinstall: "reinstall";
+}>;
+export type InstallMode = z.infer<typeof installModeSchema>;
+/**
+ * `app` on a batch preset / e2e suite: `true` installs the project's app on every device first;
+ * `{ installMode }` also resets the installed app (see {@link InstallMode}); `{ resetKeychain: true }`
+ * (needs `installMode`) also resets the iOS simulator's keychain;
+ * `{ variant }` installs that `projects[].variants` build instead of the project's default one.
+ * `{ clean: true }` is the deprecated spelling of `{ installMode: "reinstall" }`.
+ */
+export declare const appOptionSchema: z.ZodUnion<readonly [z.ZodBoolean, z.ZodObject<{
+    installMode: z.ZodOptional<z.ZodEnum<{
+        clean: "clean";
+        reinstall: "reinstall";
+    }>>;
+    resetKeychain: z.ZodOptional<z.ZodBoolean>;
+    clean: z.ZodOptional<z.ZodBoolean>;
+    variant: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>]>;
+export type AppOption = z.infer<typeof appOptionSchema>;
+export type AppSwitches = {
+    app: boolean;
+    installMode?: InstallMode;
+    resetKeychain?: true;
+    variant?: string;
+};
+/** The switches `app` stands for. An object means install (`app: {}` = `app: true`). */
+export declare function appSwitches(app: AppOption | undefined): AppSwitches;

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

@@ -0,0 +1,95 @@
+import { type AsyncResult } from "../../../types/src/result";
+import { type Exec } from "../exec";
+import type { Platform } from "../types";
+import type { InstalledApp } from "./resolve";
+/** Byte size of a file; undefined when it cannot be read. Injected so identity checks need no `stat` spawns. */
+export type FileSize = (path: string) => Promise<number | undefined>;
+export declare const nodeFileSize: FileSize;
+/** `ino:mtime` of a file; undefined when it cannot be read. Injected so tests need no real container. */
+export type FileStamp = (path: string) => Promise<string | undefined>;
+export declare const nodeFileStamp: FileStamp;
+/**
+ * `ino:mtime` of an installed `.app`'s executable, guessed as the bundle's own name (`App.app/App`, what
+ * Xcode's `EXECUTABLE_NAME` defaults to) so no `plutil` is needed; undefined when that file is not there.
+ */
+export declare function executableStamp(container: string, fileStamp?: FileStamp): Promise<string | undefined>;
+export type InstallerDeps = {
+    exec: Exec;
+    env: Record<string, string | undefined>;
+    /** default: `node:fs` */
+    fileSize?: FileSize;
+};
+/** A device to install onto: iOS simulator udid / Android emulator serial. */
+export type InstallTarget = {
+    platform: Platform;
+    deviceId: string;
+};
+/** `xcrun simctl install <udid> <app>` / `adb -s <serial> install -r <apk>`. */
+export declare function installArgv(target: InstallTarget, appPath: string, env: InstallerDeps["env"]): string[];
+/** `xcrun simctl get_app_container <udid> <bundleId>` / `adb -s <serial> shell pm path <bundleId>`. */
+export declare function probeArgv(target: InstallTarget, bundleId: string, env: InstallerDeps["env"]): string[];
+/**
+ * Is `bundleId` on the device, and (iOS) where is its container? One `simctl get_app_container` /
+ * `pm path` — hand the container to `appMatchesArtifact` instead of asking again. simctl exits
+ * non-zero / `pm path` prints nothing when the app is not there.
+ */
+export declare function probeApp(deps: InstallerDeps, target: InstallTarget, bundleId: string): AsyncResult<InstalledApp>;
+/** Is `bundleId` installed on the device? */
+export declare function isAppInstalled(deps: InstallerDeps, target: InstallTarget, bundleId: string): AsyncResult<boolean>;
+/**
+ * What distinguishes one build of an `.app` from another, cheaply: `CFBundleVersion` plus the byte
+ * size of the main executable and of the embedded `main.jsbundle` (Release). Size is used instead
+ * of mtime because `simctl install` re-copies the bundle, so the installed mtime need not match the
+ * cached one. One `plutil` spawn; the sizes are read in-process. undefined when the bundle can't be read.
+ */
+export declare function appIdentity(deps: InstallerDeps, appDir: string): Promise<string | undefined>;
+/**
+ * Is the app on the device the cached `artifactPath` build? iOS: compare `appIdentity` of the
+ * installed container with the cached `.app`; pass `installedDir` (the container `probeApp` already
+ * found) to skip a second `simctl get_app_container`. Anything unreadable counts as a mismatch
+ * (reinstall is the safe side). Android: not checked (always true) — warden's install record is
+ * trusted there.
+ */
+export declare function appMatchesArtifact(deps: InstallerDeps, target: InstallTarget, bundleId: string, artifactPath: string, installedDir?: string): AsyncResult<boolean>;
+/** `xcrun simctl uninstall <udid> <bundleId>` / `adb -s <serial> uninstall <bundleId>`. */
+export declare function uninstallArgv(target: InstallTarget, bundleId: string, env: InstallerDeps["env"]): string[];
+/**
+ * Remove `bundleId` (and with it the app container: data, keychain-less state) so the next install
+ * starts fresh. Absent already is fine; present after the uninstall is an error.
+ */
+export declare function uninstallApp(deps: InstallerDeps, target: InstallTarget, bundleId: string): AsyncResult<void>;
+/** Install `appPath`, then confirm `bundleId` is present. */
+export declare function installApp(deps: InstallerDeps, target: InstallTarget, appPath: string, bundleId: string): AsyncResult<void>;
+/** `installApp`, keeping what the confirming probe found (iOS: the new bundle container, 17-7). */
+export declare function installAndProbe(deps: InstallerDeps, target: InstallTarget, appPath: string, bundleId: string): AsyncResult<InstalledApp>;
+/** Filesystem ops the iOS data wipe needs (injected; tests pass fakes). */
+export type ResetFs = {
+    readdir: (dir: string) => Promise<string[]>;
+    /** Recursive, force. */
+    rm: (path: string) => Promise<void>;
+    /** Recursive. */
+    mkdir: (path: string) => Promise<void>;
+};
+export type ResetDeps = InstallerDeps & {
+    fs: ResetFs;
+};
+export type ResetOptions = {
+    keychain?: boolean;
+};
+/** `node:fs/promises`-backed `ResetFs`. */
+export declare const nodeResetFs: ResetFs;
+/**
+ * Android: `adb -s <serial> shell pm clear <bundleId>`. iOS: `simctl privacy <udid> reset all <bundleId>`
+ * (the last argv-only step of the multi-step iOS reset; see `resetAppData`).
+ */
+export declare function resetArgv(target: InstallTarget, bundleId: string, env: InstallerDeps["env"]): string[];
+/** iOS: `simctl keychain <udid> reset` (the whole simulator's keychain; an uninstall leaves it). Android: nothing. */
+export declare function resetSimKeychain(deps: InstallerDeps, target: InstallTarget): AsyncResult<void>;
+/**
+ * Reset an installed app to first-launch state without reinstalling. Not installed → error (the
+ * caller installs instead). Android: `pm clear` (data, permissions; keychain n/a). iOS: terminate,
+ * `defaults delete` (via cfprefsd; deleting the plist alone is undone by its cache), wipe the data
+ * and app-group containers in place (the metadata plist stays), recreate the standard subdirs,
+ * reset privacy grants, and with `keychain` the simulator-wide keychain.
+ */
+export declare function resetAppData(deps: ResetDeps, target: InstallTarget, bundleId: string, opts?: ResetOptions): AsyncResult<void>;

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

@@ -0,0 +1,74 @@
+import { type AsyncResult } from "../../../types/src/result";
+import type { InstallMode } from "./app-option.schema";
+/** Where `ensure` found the app. */
+export type ResolveSource = "installed" | "cache" | "eas" | "build";
+export type EnsureResult = {
+    /** cached `.app`/`.apk` ("" only when already installed and the cache no longer has it) */
+    appPath: string;
+    hash: string;
+    source: ResolveSource;
+    /** the app is on the device at `hash` (false when no device was given) */
+    installed: boolean;
+};
+export type EasStepOutcome = {
+    kind: "hit";
+    path: string;
+} | {
+    kind: "miss";
+    reason: string;
+};
+/** What the device probe found: is the app there, and (iOS) its container so `matches` need not ask again. */
+export type InstalledApp = {
+    present: boolean;
+    container?: string;
+};
+/** Device half of the resolver — absent when only the artifact is wanted. */
+export type DeviceSteps = {
+    /** hash recorded in the `installs` table for this device + bundle id */
+    installedHash: () => string | undefined;
+    /** does the device really have the bundle id (simctl get_app_container / pm path)? */
+    confirm: () => AsyncResult<InstalledApp>;
+    /** does the installed app (as `confirm` found it) match the cached build at `cachedPath` (CFBundleVersion + binary)? Absent = trust the record. */
+    matches?: (cachedPath: string, installed: InstalledApp) => AsyncResult<boolean>;
+    /** remove the app (and its data) so the install starts fresh; absent is fine */
+    uninstall: () => AsyncResult<void>;
+    /** `installMode: "clean"`: wipe the installed app's data (and the keychain when asked), keeping the binary */
+    reset: () => AsyncResult<void>;
+    /** install + record in `installs` */
+    install: (appPath: string) => AsyncResult<void>;
+};
+/**
+ * The resolver's effects, each a thin closure — tests pass fakes. `eas` / `build` absent means
+ * skipped (`--no-eas` / `--no-build`, or EAS not configured).
+ */
+export type ResolveSteps = {
+    hash: string;
+    device?: DeviceSteps;
+    /** `clean`: fresh app data without reinstalling an unchanged build; `reinstall`: uninstall + install even at `hash`; unset: install only when `hash` differs */
+    installMode?: InstallMode;
+    /** cached artifact path for `hash` (touches lastUsedAt) */
+    cached: () => string | undefined;
+    /** import `hash` from a legacy cache dir into the cache; path when found */
+    legacy: () => AsyncResult<string | undefined>;
+    /** serialise the fetch/build of `hash` across processes */
+    lock: <T>(fn: () => AsyncResult<T>) => AsyncResult<T>;
+    /**
+     * Same-process single flight: concurrent `resolveApp`s with this key (one per device of a session)
+     * share the first one's locked fetch/build and its result, success or error; only other processes
+     * wait on the build lock. Absent: every call takes the lock itself.
+     */
+    flightKey?: string;
+    /** EAS: download into the cache, or miss */
+    eas?: () => AsyncResult<EasStepOutcome>;
+    /** local build into the cache; path */
+    build?: () => AsyncResult<string>;
+    log: (line: string) => void;
+};
+/**
+ * The 5-step resolver, first hit wins: (1) already installed at this hash → nothing to do;
+ * (2) warden cache; (3) legacy cache import; then under the build lock (4) EAS, (5) local build.
+ * Whatever was found is installed over the old app (a hash mismatch reinstalls). `installMode: "clean"` keeps
+ * step 1 but resets the app's data either way; `reinstall` skips step 1 and uninstalls first. A new fingerprint
+ * misses 1–3 by construction, so it never gets a stale binary.
+ */
+export declare function resolveApp(steps: ResolveSteps): AsyncResult<EnsureResult>;

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

@@ -0,0 +1,25 @@
+/** Default lease TTL for agents/users: 30 min (plan default 2a). */
+export declare const DEFAULT_TTL_MS: number;
+/** Bare `warden claim` by an agent: 5 min. Only wrappers (`dev`/`run`/`batch`/`e2e`) or `heartbeat` hold longer. */
+export declare const BARE_CLAIM_AGENT_TTL_MS: number;
+/** `warden gc` shuts down idle warden devices after 20 min. */
+export declare const DEFAULT_IDLE_MS: number;
+/** `warden run` heartbeat interval. */
+export declare const HEARTBEAT_INTERVAL_MS = 30000;
+/** Device boot/ready timeout. */
+export declare const DEFAULT_READY_TIMEOUT_MS: number;
+/** Default device profile per platform. Android `auto` = first AVD from `emulator -list-avds`. */
+export declare const DEFAULT_PROFILE: {
+    readonly ios: "iphone-17";
+    readonly android: "auto";
+};
+/** Where a warden-owned Metro leases its port from (`warden dev`, `e2e.<suite>.metro`). */
+export declare const DEFAULT_METRO_PORT_SPEC = "8081:100";
+/** How long to wait for an owned Metro to serve its project. */
+export declare const DEFAULT_METRO_READY_TIMEOUT = "2m";
+/** `e2e.<suite>.jobTimeoutMs`: a spec process still going after this is killed. */
+export declare const DEFAULT_JOB_TIMEOUT_MS: number;
+/** `e2e.<suite>.spec` defaults: per-test, per-action and per-assertion timeouts. */
+export declare const DEFAULT_SPEC_TIMEOUT = "2m";
+export declare const DEFAULT_SPEC_ACTION_TIMEOUT = "30s";
+export declare const DEFAULT_SPEC_ASSERTION_TIMEOUT = "5s";

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

@@ -0,0 +1,18 @@
+export type ExecResult = {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+};
+export type ExecOptions = {
+    cwd?: string;
+    env?: Record<string, string | undefined>;
+    timeoutMs?: number;
+    /** aborting kills the command (SIGTERM), like a timeout */
+    signal?: AbortSignal;
+};
+/** Injectable process runner — providers take this so tests can fake `simctl`/`adb`. */
+export type Exec = (cmd: readonly string[], opts?: ExecOptions) => Promise<ExecResult>;
+/** Never throws: a command that cannot start (missing binary, missing cwd) is exit 127 with the reason on stderr. */
+export declare const bunExec: Exec;
+/** `cmd` failed → one-line error string for a `Result`. */
+export declare function execError(cmd: readonly string[], result: ExecResult): string;

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

@@ -0,0 +1,12 @@
+import type { Lease } from "./types";
+export type PidAlive = (pid: number) => boolean;
+/** Heartbeats a supervised lease may miss while its pid is dead before it is stale (suspend/resume grace). */
+export declare const LOST_HEARTBEATS = 3;
+/**
+ * Lease alive = pid alive || heartbeat within ttl. A supervised lease (pid + `heartbeatMs`, held by a
+ * heartbeating `run` / `dev` / `batch` / `e2e`) whose pid is dead is alive only within
+ * `LOST_HEARTBEATS` periods of its last heartbeat (and the ttl). Pure: pid check injected.
+ */
+export declare function isLeaseAlive(lease: Lease, now: number, pidAlive: PidAlive): boolean;
+/** `kill(pid, 0)` probe: EPERM means the process exists but belongs to someone else. */
+export declare function processAlive(pid: number): boolean;

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

@@ -0,0 +1,132 @@
+import { type AsyncResult, type Result } from "../../../types/src/result";
+import { type PidAlive } from "../liveness";
+import type { Lease } from "../types";
+import type { DeviceProvider, ProviderDeps } from "./provider.types";
+/** Emulator console ports: even, 5554–5584; the adb port is console + 1. */
+export declare const CONSOLE_PORT_MIN = 5554;
+export declare const CONSOLE_PORT_MAX = 5584;
+export type AndroidTools = {
+    adb: string;
+    emulator: string;
+};
+/** `adb`/`emulator` from `$ANDROID_HOME` / `$ANDROID_SDK_ROOT`, else bare PATH names. */
+export declare function androidTools(env: Record<string, string | undefined>): AndroidTools;
+export type AdbEmulator = {
+    serial: string;
+    port: number;
+    state: string;
+};
+/** Parse `adb devices -l`, keeping only `emulator-<port>` serials (physical devices 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[];
+/**
+ * First even console port in 5554–5584 where neither the console port nor its adb port (+1) is in
+ * `taken` (leased ports ∪ running emulator console/adb ports).
+ */
+export declare function pickConsolePort(taken: ReadonlySet<number>): number | undefined;
+type ExecDeps = Pick<ProviderDeps, "exec" | "env">;
+/** `adb emu …` talks to the emulator console, which a wedged emulator never answers. */
+export declare const EMU_CONSOLE_TIMEOUT_MS = 10000;
+/** `emulator -list-avds` starts the emulator binary. */
+export declare const LIST_AVDS_TIMEOUT_MS = 15000;
+/**
+ * AVD names from `emulator -list-avds`, run once per process (per `exec`): a claim resolves `auto` and
+ * then the AVD of each create from the same list. `fresh` re-reads it (an AVD made since); failures are
+ * never kept.
+ */
+export declare function listAvds(deps: ExecDeps, opts?: {
+    fresh?: boolean;
+}): AsyncResult<string[]>;
+/** Running emulators from `adb devices -l`. */
+export declare function listEmulators(deps: ExecDeps): AsyncResult<AdbEmulator[]>;
+/** Launch `cmd` so it outlives warden, stdout/stderr appended to `logPath`. */
+export type SpawnDetached = (cmd: readonly string[], logPath: string) => AsyncResult<{
+    pid: number;
+}>;
+export type AndroidProviderOptions = {
+    spawnDetached?: SpawnDetached;
+    sleep?: (ms: number) => Promise<void>;
+    /** `sys.boot_completed` poll interval of the fallback loop, default 250 ms */
+    pollIntervalMs?: number;
+    /** how long the default `spawnDetached` watches for an immediate exit, default 1.5 s */
+    earlyExitMs?: number;
+    /** is the launched emulator process still alive (default: `kill -0`) */
+    pidAlive?: PidAlive;
+    /**
+     * Name of a warden quick-boot snapshot of `avd` to launch from (see `golden/android-golden.ts`), when
+     * one exists: a claim never builds one. `ok(undefined)` = none (off, not built yet, no SDK). A failure
+     * only logs: the emulator then cold-boots as before.
+     */
+    snapshot?: (avd: string) => AsyncResult<string | undefined>;
+    /** The emulator logged that `snapshot` of `avd` did not load (it cold-booted instead): drop it so it is rebuilt. */
+    snapshotFailed?: (avd: string, snapshot: string) => AsyncResult<unknown>;
+    /** The emulator launched from `snapshot` of `avd` and reached ready with no load failure logged. */
+    snapshotLoaded?: (avd: string, snapshot: string) => void;
+};
+/** 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";
+/** The last 3 lines of an emulator log, one line. */
+export declare function logTail(logPath: string): string;
+/**
+ * Default detached launcher: node `spawn` with `detached` + `unref` (own process group, so warden
+ * exiting / Ctrl-C does not kill the emulator). Fails if the process exits within `earlyExitMs`.
+ */
+export declare function createSpawnDetached(earlyExitMs?: number): SpawnDetached;
+/** Cheap headless flags every warden emulator gets: no audio backend (unless `WARDEN_EMULATOR_AUDIO=1`), no usage metrics. */
+export declare function headlessEmulatorFlags(env: Record<string, string | undefined>): string[];
+/** An early exit whose message says the emulator does not know one of its options (an older emulator). */
+export declare function rejectedOption(error: string): boolean;
+/** A claim's emulator: headless, `-read-only` (one AVD backs many), from `snapshot` when given, never saving on exit. */
+export declare function claimEmulatorArgv(tools: AndroidTools, env: Record<string, string | undefined>, avd: string, port: number, snapshot?: string, 
+/** `false` leaves out `headlessEmulatorFlags` (an emulator that rejected them) */
+headless?: boolean): string[];
+export type BootWaitDeps = ExecDeps & {
+    now: () => number;
+    sleep: (ms: number) => Promise<void>;
+    pidAlive: PidAlive;
+    /** fallback `getprop` poll interval */
+    pollIntervalMs: number;
+};
+/** The launched emulator process, when known: a boot wait fails as soon as it is gone. */
+export type BootWatch = {
+    pid?: number;
+    logPath?: string;
+};
+/**
+ * Wait for `sys.boot_completed=1` within `timeoutMs`: one `adb wait-for-device shell <loop>` bounded by
+ * the budget (falling back to a bounded poll when it fails early), raced against the deadline and the
+ * emulator process staying alive, so a dead emulator fails in ≤ 0.5 s with its log tail instead of
+ * waiting out the budget. Whatever is still running when it settles is aborted.
+ */
+export declare function waitBootCompleted(deps: BootWaitDeps, serial: string, timeoutMs: number, watch?: BootWatch): AsyncResult<void>;
+/**
+ * Take a console-port lease (`emulator <name>`) under the store's cross-process lock: the first even
+ * port whose console and adb ports are neither leased nor used by a running emulator.
+ */
+export declare function leaseConsolePort(deps: Pick<ProviderDeps, "store" | "owner" | "now">, name: string, running: AdbEmulator[]): Result<{
+    lease: Lease;
+    port: number;
+}>;
+/** Label prefix of the console-port lease a snapshot build's writable emulator runs on. */
+export declare const GOLDEN_PORT_LABEL = "emulator golden ";
+/**
+ * A snapshot load the emulator gave up on (it then cold-boots by itself). The wording is the emulator's
+ * and unverified on a device; a successful load logs `Successfully loaded snapshot …`, which does not match.
+ */
+export declare function snapshotLoadFailed(log: string): boolean;
+/**
+ * Global settings applied after every boot. On a fresh playstore image the first `adb install` can pop a Play
+ * Protect consent dialog (a GMS activity the e2e alert detector cannot classify), and every adb install otherwise
+ * waits on the GMS verifier (up to the 10 s verifier_timeout). Warden's emulators run `-read-only -no-snapshot-save`,
+ * so /data changes are a per-boot overlay and must be re-applied on each boot.
+ */
+export declare const BOOT_SETTINGS: ReadonlyArray<readonly [key: string, value: string]>;
+export declare function bootSettingsCommand(): string;
+/**
+ * Android emulators on `adb` + `emulator`. Warden never boots an existing emulator — it launches a
+ * new headless `-read-only` instance of an AVD (so one AVD backs many emulators) on a leased even
+ * console port, and only kills emulators it launched (store `devices` table).
+ */
+export declare function createAndroidProvider(deps: ProviderDeps, options?: AndroidProviderOptions): DeviceProvider;
+export {};

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

@@ -0,0 +1,45 @@
+import { type AsyncResult } from "../../../types/src/result";
+import type { Exec, ExecResult } from "../exec";
+export declare const PROBE_TIMEOUT_MS = 5000;
+/** A probe that timed out is asked once more, with this much longer: a busy host is not a hung sim. */
+export declare const PROBE_RETRY_FACTOR = 3;
+/** A cancellable timer: `promise` resolves after `ms` unless `cancel` runs first. */
+export type Timer = {
+    promise: Promise<void>;
+    cancel: () => void;
+};
+export declare function realTimer(ms: number): Timer;
+/** An exec plus the timer that bounds it. */
+export type TimedExec = {
+    exec: Exec;
+    /** the timeout timer — tests resolve it immediately instead of waiting */
+    timer: (ms: number) => Timer;
+};
+export type HealthDeps = TimedExec & {
+    timeoutMs?: number;
+};
+/** What a probe error says when the sim gave no answer in time (as opposed to a wrong answer). */
+export declare const PROBE_NO_ANSWER = "did not answer within";
+/** The probe failed because the sim did not answer in time, not because SpringBoard is down or launchctl failed. */
+export declare function isProbeTimeout(error: string): boolean;
+/**
+ * Run `cmd`, giving up (undefined) after `timeoutMs`. The exec gets the same timeout so a real process
+ * is killed; the timer race bounds an exec that never returns at all.
+ */
+export declare function execWithin(deps: TimedExec, cmd: readonly string[], timeoutMs: number): Promise<ExecResult | undefined>;
+/** `launchctl list` rows are `PID\tStatus\tLabel`; SpringBoard is a job with a numeric pid. */
+export declare function springboardRunning(launchctlList: string): boolean;
+/**
+ * iOS claim health probe: the booted simulator's launchd answers `launchctl print system` within
+ * the timeout (retried once, longer, so a loaded host does not get a healthy sim quarantined) and
+ * SpringBoard is running. A hung or half-booted sim fails one of the two. The two are independent,
+ * so they are asked at the same time.
+ */
+export declare function probeIosHealth(deps: HealthDeps, udid: string): AsyncResult<void>;
+/**
+ * Probe for a simulator that was already Booted when claimed: one `launchctl list`. It answering at
+ * all proves launchd is up (so `launchctl print system` and `bootstatus` would add nothing), and
+ * SpringBoard running proves the boot finished. A failure is not a verdict — the caller falls back to
+ * `bootstatus` + the full probe, since a sim another process was still booting looks like this.
+ */
+export declare function probeIosWarm(deps: HealthDeps, udid: string): AsyncResult<void>;

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

@@ -0,0 +1,56 @@
+import type { AsyncResult } from "../../../types/src/result";
+import type { Exec } from "../exec";
+import type { Store } from "../store";
+import type { InventoryDevice, Owner, Platform } from "../types";
+import type { Timer } from "./health";
+/**
+ * A device backend (iOS simulators, Android emulators). Providers report raw devices with
+ * `wardenCreated: false`; callers mark warden's own via `markWardenDevices` (store `devices` table).
+ * Providers never decide ownership — they only list, create, boot, wait and shut down.
+ */
+export interface DeviceProvider {
+    readonly platform: Platform;
+    inventory(): AsyncResult<InventoryDevice[]>;
+    /** Create (iOS) or launch (Android) a new warden device called `name`. Returned device is not necessarily ready. */
+    create(name: string, profile: string, runtime?: string): AsyncResult<InventoryDevice>;
+    boot(id: string): AsyncResult<void>;
+    waitReady(id: string, timeoutMs: number): AsyncResult<void>;
+    shutdown(id: string): AsyncResult<void>;
+    /** Is a booted device responsive? Absent = no probe (Android), treated as healthy. */
+    probe?(id: string): AsyncResult<void>;
+    /**
+     * Cheap proof that a device already Booted when claimed is usable: when it succeeds the claim skips
+     * `waitReady` and `probe`. A failure is not a verdict — the claim falls back to `waitReady` + `probe`.
+     * Absent = always take the full path.
+     */
+    verifyWarm?(id: string): AsyncResult<void>;
+    /**
+     * Boot a shut-down device and wait until it is ready in one step, where the platform can do both at
+     * once (iOS: `bootstatus -b` boots it). Absent = `boot`, then `waitReady`.
+     */
+    bootReady?(id: string, timeoutMs: number): Promise<BootReady>;
+    /** Probe for a device `bootReady` just booted and saw ready. Absent = `probe`. */
+    probeBooted?(id: string): AsyncResult<void>;
+}
+/** `bootReady`: a boot failure is an error; a device that booted but never got ready is unhealthy. */
+export type BootReady = {
+    kind: "ready";
+} | {
+    kind: "boot-failed";
+    error: string;
+} | {
+    kind: "not-ready";
+    error: string;
+};
+export type ProviderDeps = {
+    exec: Exec;
+    store: Store;
+    env: Record<string, string | undefined>;
+    now: () => number;
+    /** the claimer — owner for any side leases a provider takes (e.g. Android console ports) */
+    owner: Owner;
+    /** timer for probe timeouts (default: real timers) */
+    timer?: (ms: number) => Timer;
+    /** progress notes (e.g. "cloning from golden…") — stderr in the CLI */
+    log?: (line: string) => void;
+};

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

@@ -0,0 +1,105 @@
+import { Database } from "bun:sqlite";
+import { type PidAlive } from "./liveness";
+import type { Lease, Owner, Platform, QueueEntry, Resource } from "./types";
+/** `$WARDEN_HOME`, else `~/.warden`. */
+export declare function wardenHome(env?: Record<string, string | undefined>): string;
+export declare function defaultDbPath(env?: Record<string, string | undefined>): string;
+/**
+ * Ordered schema migrations; index + 1 = `PRAGMA user_version` after applying. Append only — never
+ * edit an entry that has shipped.
+ */
+export declare const MIGRATIONS: readonly string[];
+/** A queued claim that has not refreshed within this long is dead (its waiter polls every few seconds). */
+export declare const QUEUE_TTL_MS = 60000;
+export declare function ownerKey(owner: Owner): string;
+export type NewLease = {
+    resource: Resource;
+    owner: Owner;
+    ttlMs: number;
+    label?: string;
+    pid?: number;
+    bootedByOwner?: boolean;
+    shared?: boolean;
+};
+/** A device warden created (sim) or launched (emulator). */
+export type DeviceRecord = {
+    platform: Platform;
+    id: string;
+    name: string;
+    profile?: string;
+    runtime?: string;
+    createdAt: number;
+    lastUsedAt: number;
+    /** set when the device was reported bad (`release --bad`, failed health probe): never allocated until cleared */
+    quarantinedAt?: number;
+    quarantineReason?: string;
+    /** set while the simulator's daemons are switched off (`sim slim`); cleared by `--restore` */
+    slimmedAt?: number;
+};
+export declare function newLeaseId(): string;
+/**
+ * The lease registry. One sqlite file (WAL) shared by every warden process on the machine;
+ * `transaction` runs under `BEGIN IMMEDIATE`, which is the cross-process mutex for claims.
+ */
+export declare class Store {
+    readonly db: Database;
+    constructor(db: Database);
+    close(): void;
+    /** Run `fn` under `BEGIN IMMEDIATE` (write lock taken up front). Nested calls join the outer txn. */
+    transaction<T>(fn: () => T): T;
+    insertLease(input: NewLease, now: number): Lease;
+    /** Mark leases shared (`Lease.shared`): `warden dev` on the device leases it just claimed. */
+    markShared(ids: readonly string[]): void;
+    /** Record that this lease's owner booted its device (claim boot/create, hook saw it shut down). */
+    markBootedByOwner(id: string): void;
+    /** Record the process a lease now lives with (an emulator launched after its port was leased). */
+    setLeasePid(id: string, pid: number): void;
+    getMeta(key: string): string | undefined;
+    setMeta(key: string, value: string): void;
+    deleteMeta(key: string): void;
+    getLease(id: string): Lease | undefined;
+    listLeases(): Lease[];
+    listLeasesByOwner(owner: Owner): Lease[];
+    findLeaseByResource(resource: Resource): Lease | undefined;
+    deleteLeases(ids: readonly string[]): number;
+    /**
+     * Stamp `heartbeat_at = now` on `ids`; returns how many leases were updated (fewer than `ids` = some
+     * were released). `periodMs` (the holder's heartbeat interval) marks them supervised: with a pid,
+     * a dead pid makes them stale after `LOST_HEARTBEATS` periods instead of the TTL.
+     */
+    heartbeat(ids: readonly string[], now: number, periodMs?: number): number;
+    /** Delete leases that are not alive (`isLeaseAlive`: pid dead AND heartbeat expired). Returns reclaimed ids. */
+    reclaimStale(now: number, pidAlive: PidAlive): string[];
+    /** Insert a queue row; an existing id keeps its `enqueuedAt` (queue age) and updates the rest. */
+    enqueue(entry: QueueEntry): QueueEntry;
+    /** Stamp `heartbeat_at`; false when the row is gone (reclaimed or dequeued). */
+    refreshQueue(id: string, now: number): boolean;
+    dequeue(id: string): boolean;
+    /** Raw insertion order (`enqueued_at`, id); use `queueOrder` for admission order. */
+    listQueue(): QueueEntry[];
+    /** Delete queue rows whose waiter is gone: pid dead, or heartbeat older than `QUEUE_TTL_MS`. */
+    reclaimStaleQueue(now: number, pidAlive: PidAlive): string[];
+    recordDevice(device: Omit<DeviceRecord, "createdAt" | "lastUsedAt">, now: number): void;
+    listDevices(platform?: Platform): DeviceRecord[];
+    touchDevice(platform: Platform, id: string, now: number): void;
+    /** Quarantine a warden device (recording it first when only its name marked it ours). */
+    quarantineDevice(device: Omit<DeviceRecord, "createdAt" | "lastUsedAt" | "quarantinedAt" | "quarantineReason" | "slimmedAt">, reason: string | undefined, now: number): void;
+    /** Clear quarantine on every recorded device with this id (any platform); returns how many were cleared. */
+    unquarantineDevice(id: string): number;
+    /** Record (`at` set) or clear (`at` undefined) that a recorded device's daemons are slimmed. */
+    setSlimmed(platform: Platform, id: string, at: number | undefined): void;
+    forgetDevice(platform: Platform, id: string): void;
+    /**
+     * What a `warden gc` pass could find to do, from the store alone (no simulator is asked):
+     * - `staleLeases`: leases whose heartbeat expired and whose process is gone;
+     * - `idleDevices`: recorded devices nobody holds that went idle (unused for `idleMs`) after the
+     *   last pass (`last_gc_at`). Whether one is still booted only the provider knows; a pass that
+     *   ran after the device went idle has dealt with it, so it is not work again until it is used.
+     */
+    gcWork(now: number, idleMs: number, pidAlive: PidAlive): {
+        staleLeases: number;
+        idleDevices: number;
+    };
+}
+/** Open (creating + migrating) the store at `path`, default `$WARDEN_HOME/warden.db`. */
+export declare function openStore(path?: string): Store;