@delacour/warden-e2e 0.6.0 → 0.8.0

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

@@ -0,0 +1,44 @@
+import type { Store } from "./store";
+/**
+ * Ownership marker: warden writes `.warden-owned.json` into the device dir of every iOS simulator it creates,
+ * naming the host instance (a random id kept in the store `meta`) that made it. Destructive paths (shutdown on
+ * release, erase, delete) refuse a sim whose marker names another instance: a second `WARDEN_HOME` or user
+ * account on the same machine owns it. A sim with no marker keeps today's rules. Android emulators are AVDs
+ * launched from a shared definition, not created per claim, so they carry no marker.
+ */
+export declare const MARKER_FILE = ".warden-owned.json";
+export declare const INSTANCE_META_KEY = "instance_id";
+export type OwnershipMarker = {
+    instanceId: string;
+    name: string;
+    createdAt: number;
+};
+/** The filesystem the marker lives on, injectable for tests. */
+export type MarkerFs = {
+    readText: (path: string) => string | undefined;
+    writeText: (path: string, text: string) => void;
+    isDir: (path: string) => boolean;
+};
+export declare const realMarkerFs: MarkerFs;
+type Env = Record<string, string | undefined>;
+/** This host's stable instance id: created on first use inside a transaction, then read from `meta`. */
+export declare function instanceId(store: Store): string;
+/** `~/Library/Developer/CoreSimulator/Devices/<udid>` (the default device set); undefined without `HOME`. */
+export declare function simDeviceDir(env: Env, udid: string): string | undefined;
+export type MarkerRead = {
+    kind: "absent";
+} | {
+    kind: "present";
+    marker: OwnershipMarker;
+} | {
+    kind: "unreadable";
+};
+export declare function readMarker(fs: MarkerFs, env: Env, udid: string): MarkerRead;
+/** Best-effort: only into a device dir that exists, and a failure never fails the create. */
+export declare function writeMarker(fs: MarkerFs, env: Env, store: Store, udid: string, name: string, now: number): boolean;
+/**
+ * Why a destructive step must leave this sim alone, else undefined: its marker names another warden instance.
+ * A missing or unreadable marker blocks nothing (sims made before markers existed).
+ */
+export declare function markerBlock(fs: MarkerFs, env: Env, store: Store, udid: string): string | undefined;
+export {};

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

@@ -1,5 +1,7 @@
 import { type AsyncResult, type Result } from "../../../types/src/result";
+import { type CameraMode } from "../camera-mode";
 import { type PidAlive } from "../liveness";
+import { type Store } from "../store";
 import type { Lease } from "../types";
 import type { DeviceProvider, ProviderDeps } from "./provider.types";
 /** Emulator console ports: even, 5554–5584; the adb port is console + 1. */
@@ -16,7 +18,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 +57,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 +101,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;
 /**
@@ -80,7 +117,12 @@ 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[];
+headless?: boolean, 
+/** a `+cam` device's feeds: each camera plays `mode`'s video, else reads `<facing>.png` from `dir` */
+camera?: {
+    dir: string;
+    mode: CameraMode;
+}): string[];
 export type BootWaitDeps = ExecDeps & {
     now: () => number;
     sleep: (ms: number) => Promise<void>;
@@ -115,6 +157,8 @@ export declare const GOLDEN_PORT_LABEL = "emulator golden ";
  * and unverified on a device; a successful load logs `Successfully loaded snapshot …`, which does not match.
  */
 export declare function snapshotLoadFailed(log: string): boolean;
+/** The bookkeeping of an emulator that is gone: its console-port lease and its `devices` record. */
+export declare function forgetAndroidEmulator(store: Store, serial: string): void;
 /**
  * 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

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

@@ -1,5 +1,6 @@
 import type { AsyncResult } from "../../../types/src/result";
 import type { Exec } from "../exec";
+import type { MarkerFs } from "../ownership";
 import type { Store } from "../store";
 import type { InventoryDevice, Owner, Platform } from "../types";
 import type { Timer } from "./health";
@@ -36,6 +37,12 @@ export interface DeviceProvider {
      * shutdown reuse), never for an already-booted one. A failure is logged by the provider, never fatal.
      */
     prepareBoot?(id: string): Promise<void>;
+    /**
+     * Restart a running warden device in place (same id, same console port, device record and port lease kept) so
+     * launch-time settings apply again; the caller then waits with `waitReady`. Android camera emulators only
+     * (the camera source is fixed at launch). Absent = the platform cannot.
+     */
+    relaunch?(id: string): AsyncResult<void>;
     /** Called once the device is ready, before the health probe. Best effort. */
     afterReady?(id: string): Promise<void>;
 }
@@ -60,4 +67,6 @@ export type ProviderDeps = {
     timer?: (ms: number) => Timer;
     /** progress notes (e.g. "cloning from golden…") — stderr in the CLI */
     log?: (line: string) => void;
+    /** where the iOS ownership marker is written (default: the real filesystem) */
+    markerFs?: MarkerFs;
 };

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

@@ -0,0 +1,43 @@
+import { type Result } from "../../types/src/result";
+import type { CapacityReason } from "./claim-errors";
+import type { QueueEntry } from "./types";
+export declare const PRIORITY: {
+    readonly interactive: 30;
+    readonly high: 20;
+    readonly normal: 10;
+    readonly low: 0;
+};
+export type PriorityName = keyof typeof PRIORITY;
+/** `high` for 20, the number itself for a custom priority. */
+export declare const priorityName: (priority: number) => string;
+/** Gap between adjacent named priorities (`low` → `normal` → `high` → `interactive`). */
+export declare const PRIORITY_STEP = 10;
+/**
+ * One priority level (`PRIORITY_STEP` points) is earned per this much waiting, so a `low` row overtakes
+ * a fresh `high` one after 20 min, inside the default 30 min `--wait`.
+ */
+export declare const AGING_MS: number;
+export declare function parsePriority(input: string): Result<number>;
+/** `priority + PRIORITY_STEP × floor(age / 10 min)`; clock skew (now < enqueuedAt) earns nothing. */
+export declare function effectivePriority(entry: QueueEntry, now: number): number;
+/** Head first: effective priority desc, then enqueued_at asc, then id. */
+export declare function queueOrder(entries: readonly QueueEntry[], now: number): QueueEntry[];
+/** 1-based position, or undefined when `id` is not queued. */
+export declare function queuePosition(entries: readonly QueueEntry[], id: string, now: number): number | undefined;
+export declare function isHead(entries: readonly QueueEntry[], id: string, now: number): boolean;
+/** Why a polling claim has no device yet although the host has room: nothing to reserve. */
+export declare const DEVICE_WAIT_REASONS: readonly ["device-limit", "requester-limit", "waiting-for-device"];
+export type DeviceWaitReason = (typeof DEVICE_WAIT_REASONS)[number];
+/**
+ * Why a claim is not running yet. Queued for host capacity: behind an earlier claim, or the resource the
+ * host is out of. Polling for a device: the pool is at `--max`, the owner is at its limit, or a physical
+ * device is not free / ready.
+ */
+export type WaitReason = "behind-earlier" | CapacityReason | DeviceWaitReason;
+export declare const isWaitReason: (s: string) => s is WaitReason;
+export declare const isDeviceWaitReason: (reason: WaitReason | undefined) => reason is DeviceWaitReason;
+/**
+ * Rows that take part in admission order. A claim polling for a device holds a row so `warden queue` can
+ * show why it waits, but it needs no boot slot: it is never ahead of, or counted against, a claim that does.
+ */
+export declare const admissionQueue: (entries: readonly QueueEntry[]) => QueueEntry[];

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

@@ -1,9 +1,21 @@
 import { Database } from "bun:sqlite";
+import { type EventFilter, type LeaseEvent, type NewLeaseEvent } from "./lease-events";
 import { type PidAlive } from "./liveness";
+import { type WaitReason } from "./queue";
 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;
+/** An owner's idempotency key and the claim it created (one row per key, however many leases the claim holds). */
+export type ClaimKey = {
+    ownerKey: string;
+    key: string;
+    claimId: string;
+    platform: string;
+    profile: string;
+    count: number;
+    ready: boolean;
+};
 /**
  * Ordered schema migrations; index + 1 = `PRAGMA user_version` after applying. Append only — never
  * edit an entry that has shipped.
@@ -12,6 +24,11 @@ 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;
+/** Why leases are being deleted when it is history worth logging (see `Store.deleteLeases`). */
+export type LeaseEnd = {
+    type: "released" | "expired";
+    now: number;
+};
 export type NewLease = {
     resource: Resource;
     owner: Owner;
@@ -20,6 +37,7 @@ export type NewLease = {
     pid?: number;
     bootedByOwner?: boolean;
     shared?: boolean;
+    claimId?: string;
 };
 /** A device warden created (sim) or launched (emulator). */
 export type DeviceRecord = {
@@ -35,6 +53,8 @@ export type DeviceRecord = {
     quarantineReason?: string;
     /** set while the simulator's daemons are switched off (`sim slim`); cleared by `--restore` */
     slimmedAt?: number;
+    /** set when `warden dev` took the sim: kept on shutdown (not ephemeral) so installs and logins survive */
+    persistentAt?: number;
 };
 export declare function newLeaseId(): string;
 /**
@@ -61,7 +81,29 @@ export declare class Store {
     listLeases(): Lease[];
     listLeasesByOwner(owner: Owner): Lease[];
     findLeaseByResource(resource: Resource): Lease | undefined;
-    deleteLeases(ids: readonly string[]): number;
+    /**
+     * Delete leases. With `end`, a device lease that was granted (has a `granted` event) also logs `end.type`
+     * in the same transaction. Without it nothing is logged: rollbacks, create placeholders, eviction holds,
+     * ports and build locks are not lease history.
+     */
+    deleteLeases(ids: readonly string[], end?: LeaseEnd): number;
+    private recordLeaseEnd;
+    /** Append one lease event (join the caller's transaction when there is one). */
+    recordEvent(event: NewLeaseEvent): void;
+    /** `queued` is logged once per claim call (its queue row is refreshed every round): false when already there. */
+    recordQueuedOnce(event: Extract<NewLeaseEvent, {
+        type: "queued";
+    }>): boolean;
+    /**
+     * A holder's heartbeat found these leases gone: log `heartbeat_lost` for those no longer held, copying
+     * who/what from their `granted` event. Returns how many were logged.
+     */
+    recordHeartbeatLost(ids: readonly string[], now: number): number;
+    /** The `heartbeat_lost` event of a granted lease (who/what copied from its grant); undefined for one never granted (ports, builds). */
+    private heartbeatLostEvent;
+    listEvents(filter?: EventFilter): LeaseEvent[];
+    /** Delete events older than `before` (ms). */
+    pruneEvents(before: number): 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,
@@ -72,8 +114,17 @@ export declare class Store {
     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;
+    /** Stamp `heartbeat_at` and the live wait `reason`; false when the row is gone (reclaimed or dequeued). */
+    refreshQueue(id: string, now: number, reason?: WaitReason): boolean;
+    /** The claim an owner's idempotency key points at (caller holds the transaction), if any. */
+    getClaimKey(ownerKey: string, key: string): ClaimKey | undefined;
+    /** Point (owner, key) at a claim, replacing a stale mapping; `ready` stays false until the claim is granted. */
+    setClaimKey(entry: Omit<ClaimKey, "ready">, now: number): void;
+    /** The claim's leases are all granted: a repeat of its key now returns them. */
+    markClaimKeyReady(claimId: string): void;
+    deleteClaimKey(ownerKey: string, key: string): void;
+    /** Forget the keys of a claim that failed (its leases are gone). */
+    deleteClaimKeysOf(claimId: string): void;
     dequeue(id: string): boolean;
     /** Raw insertion order (`enqueued_at`, id); use `queueOrder` for admission order. */
     listQueue(): QueueEntry[];
@@ -83,11 +134,16 @@ export declare class Store {
     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;
+    quarantineDevice(device: Omit<DeviceRecord, "createdAt" | "lastUsedAt" | "quarantinedAt" | "quarantineReason" | "slimmedAt" | "persistentAt">, 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;
+    unquarantineDevice(id: string, now: number): 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;
+    /**
+     * Mark a recorded device persistent (never deleted as ephemeral). Update-only: a record is what makes a device
+     * warden-created (`shouldShutdown`), so a sim that was already running when leased must not gain one here.
+     */
+    markPersistent(platform: Platform, id: string, now: number): void;
     forgetDevice(platform: Platform, id: string): void;
     /**
      * What a `warden gc` pass could find to do, from the store alone (no simulator is asked):

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

@@ -1,9 +1,39 @@
+import type { WaitReason } from "./queue";
 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";
@@ -55,6 +85,11 @@ export type Lease = {
      * attaches to it instead of refusing with `device_busy`, and never releases it. Other owners still see it as foreign.
      */
     shared?: boolean;
+    /**
+     * The `claimDevices` call(s) that took this lease: a wrapper's legs share one id, so the per-owner limit counts
+     * claims, not devices. Absent on leases an older binary wrote (each counts as its own claim).
+     */
+    claimId?: string;
 };
 export type DeviceState = "booted" | "shutdown" | "booting";
 /** A device as seen by a provider, enriched with warden's own bookkeeping. */
@@ -73,6 +108,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 +120,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";
@@ -123,4 +166,18 @@ export type QueueEntry = {
     owner: Owner;
     label?: string;
     pid?: number;
+    /** why the claim waits, rewritten every round (absent on rows an older binary wrote) */
+    reason?: WaitReason;
+    /** the claim this row belongs to (absent on rows an older binary wrote) */
+    claimId?: string;
 };
+/** 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;