@loadmill/droid-cua 2.43.0 → 2.45.0

package/build/src/device/ios/real-device/readiness.js

@@ -0,0 +1,439 @@
+import { execFile } from "node:child_process";
+import { readdir } from "node:fs/promises";
+import { promisify } from "node:util";
+import { DevicectlError, getDdiServices, getLockState, listApps, listDevices } from "./devicectl.js";
+import { didIosVersionChange, readDeviceState, updateDeviceState } from "./device-state.js";
+import { chooseSigning, fetchXcodeTeams, listPaidTeams, listXcodeAccounts, wdaRunnerBundleId } from "./signing.js";
+import { APPIUM_WDA_DIR, ensureSigning, getPinnedWdaVersion, provisionWda, wdaBundleIdBase } from "./wda-provisioning.js";
+const execFileAsync = promisify(execFile);
+const TEAM_FETCH_INTERVAL_MS = 60 * 1000;
+let lastTeamFetchAt = null;
+let teamFetchInFlight = null;
+export function __resetTeamFetchThrottle() {
+    lastTeamFetchAt = null;
+    teamFetchInFlight = null;
+}
+export const MESSAGES = {
+    installXcode: "Install Xcode from the App Store and open it once.",
+    signIntoXcode: "Sign into Xcode with your work Apple ID (Xcode > Settings > Apple Accounts).",
+    askTeamAdmin: "Ask your admin to add you with the Developer role and Access to Certificates, Identifiers & Profiles.",
+    connectUsb: "Connect your iPhone with a USB cable.",
+    trust: "Unlock the iPhone and tap Trust.",
+    developerMode: "Turn on Developer Mode: on the iPhone open Settings > Privacy & Security > Developer Mode, turn it on, let the iPhone restart, then tap Turn On and enter your passcode.",
+    unlock: "Unlock your iPhone.",
+    allowAutomation: "Enter your passcode on the iPhone to allow automation",
+    lockedMidRun: "iPhone locked — unlock to continue",
+};
+const DEVICECTL_MESSAGES = {
+    "developer-mode-disabled": `Developer Mode is off. ${MESSAGES.developerMode}`,
+    "untrusted-developer": "The iPhone doesn't trust the helper app's developer yet. On the iPhone open Settings > General > VPN & Device Management and trust it.",
+    "app-not-installed": "The helper app (WebDriverAgent) isn't installed on the iPhone.",
+    "device-locked": `The iPhone is locked. ${MESSAGES.unlock}`,
+    "device-not-found": `The iPhone isn't connected. ${MESSAGES.connectUsb}`,
+    "not-paired": `The iPhone doesn't trust this Mac yet. ${MESSAGES.trust}`,
+};
+export function messageForError(error) {
+    if (error instanceof DevicectlError && DEVICECTL_MESSAGES[error.kind])
+        return DEVICECTL_MESSAGES[error.kind];
+    if (error instanceof DevicectlError && error.kind === "timeout") {
+        return `${error.message}. Check the USB cable and unlock the iPhone.`;
+    }
+    return error?.message || String(error);
+}
+export function xcodeAdviceForIos(iosVersion) {
+    const major = Number.parseInt(String(iosVersion ?? ""), 10);
+    if (major >= 26)
+        return `Install Xcode ${major} and open it once.`;
+    return `Install an Xcode that supports iOS ${iosVersion} and open it once.`;
+}
+function pass(summary, details) {
+    return { status: "pass", summary, details };
+}
+function fail(summary, details, cause) {
+    return { status: "fail", summary, details, ...(cause ? { cause } : {}) };
+}
+function warn(summary, details) {
+    return { status: "warn", summary, details };
+}
+function teamLabel(team) {
+    return team.teamName ? `${team.teamName} (${team.teamId})` : team.teamId;
+}
+async function xcodeMissing(ctx) {
+    const apps = await ctx.deps.listXcodeApps();
+    if (!apps.length) {
+        return fail("Xcode isn't in your Applications folder.", "Install Xcode from the App Store, or move Xcode into /Applications, then open it once.", "xcode-not-in-applications");
+    }
+    const developerPath = await ctx.deps.xcodeSelectPath();
+    if (developerPath?.includes("/CommandLineTools")) {
+        const app = apps.includes("Xcode.app") ? "Xcode.app" : apps[0];
+        return fail("The Command Line Tools are selected instead of Xcode.", `Run: sudo xcode-select -s /Applications/${app}`, "command-line-tools-selected");
+    }
+    return fail("Xcode isn't installed or isn't the selected developer tool (Command Line Tools alone aren't enough).", `${MESSAGES.installXcode} If Xcode is already installed, run: sudo xcode-select -s /Applications/Xcode.app`);
+}
+function versionParts(version) {
+    return String(version ?? "").split(".").map((part) => Number.parseInt(part, 10) || 0);
+}
+export function matchingIosRuntime(sdkVersion, runtimes) {
+    const [sdkMajor, sdkMinor] = versionParts(sdkVersion);
+    return runtimes.find((runtime) => {
+        const [major, minor] = versionParts(runtime.version);
+        return major === sdkMajor && minor >= sdkMinor;
+    }) ?? null;
+}
+async function listIosRuntimes() {
+    const { stdout } = await execFileAsync("xcrun", ["simctl", "list", "runtimes", "-j"], { timeout: 30_000 });
+    return (JSON.parse(stdout).runtimes ?? []).filter((runtime) => runtime.platform === "iOS" && runtime.isAvailable);
+}
+async function fetchTeamsThrottled(ctx) {
+    if (teamFetchInFlight) {
+        await teamFetchInFlight;
+        return true;
+    }
+    const now = ctx.deps.now();
+    if (lastTeamFetchAt !== null && now - lastTeamFetchAt < TEAM_FETCH_INTERVAL_MS)
+        return false;
+    lastTeamFetchAt = now;
+    teamFetchInFlight = Promise.resolve(ctx.deps.fetchXcodeTeams()).finally(() => {
+        teamFetchInFlight = null;
+    });
+    await teamFetchInFlight;
+    return true;
+}
+export const READINESS_CHECKS = [
+    {
+        id: "xcode_devicectl",
+        title: "Xcode installed",
+        kind: "human-detectable",
+        blocking: true,
+        dependsOn: [],
+        async detect(ctx) {
+            try {
+                await ctx.deps.findDevicectl();
+            }
+            catch {
+                return await xcodeMissing(ctx);
+            }
+            try {
+                await ctx.deps.checkXcodeLicense();
+            }
+            catch {
+                return fail("The Xcode license hasn't been accepted.", "Run: sudo xcodebuild -license accept", "xcode-license");
+            }
+            return pass("Xcode is installed.");
+        },
+    },
+    {
+        id: "ios_platform",
+        title: "iOS platform installed",
+        kind: "human-detectable",
+        blocking: true,
+        dependsOn: ["xcode_devicectl"],
+        async detect(ctx) {
+            const sdkVersion = await ctx.deps.iosSdkVersion();
+            const runtime = matchingIosRuntime(sdkVersion, await ctx.deps.listIosRuntimes());
+            if (runtime)
+                return pass(`The iOS ${runtime.version} platform is installed.`);
+            return fail("The iOS platform isn't installed in Xcode.", `Xcode needs the iOS ${sdkVersion} platform to build the helper app. Install it from Xcode > Settings > Components, or run: xcodebuild -downloadPlatform iOS. It's a large download (about 10 GB).`, "ios-platform-missing");
+        },
+    },
+    {
+        id: "apple_team",
+        title: "Apple team access",
+        kind: "human-detectable",
+        blocking: true,
+        dependsOn: ["ios_platform"],
+        async detect(ctx) {
+            let teams = await ctx.deps.listPaidTeams();
+            if (!teams.length) {
+                if (!(await ctx.deps.listXcodeAccounts()).length) {
+                    return fail("No Apple account is signed into Xcode.", MESSAGES.signIntoXcode);
+                }
+                if (await fetchTeamsThrottled(ctx))
+                    teams = await ctx.deps.listPaidTeams();
+            }
+            if (!teams.length) {
+                return fail("Signed into Xcode, but none of your accounts is in a paid Apple Developer team.", MESSAGES.askTeamAdmin);
+            }
+            const list = teams.map(teamLabel).join(", ");
+            if (ctx.teamId) {
+                const team = teams.find((t) => t.teamId === ctx.teamId);
+                if (!team) {
+                    return fail(`Team ${ctx.teamId} isn't one of your paid Apple teams (${list}).`, `Choose one of those teams, or sign into Xcode with an Apple ID that belongs to team ${ctx.teamId}.`);
+                }
+                return pass(`Using team ${teamLabel(team)}.`);
+            }
+            if (teams.length > 1) {
+                return fail(`You belong to several paid Apple teams: ${list}.`, "Choose the team droid should sign the helper app with.");
+            }
+            ctx.teamId = teams[0].teamId;
+            return pass(`Using team ${teamLabel(teams[0])}.`);
+        },
+    },
+    {
+        id: "iphone_connected",
+        title: "iPhone connected",
+        kind: "human-detectable",
+        blocking: true,
+        dependsOn: ["xcode_devicectl"],
+        async detect(ctx) {
+            const devices = await ctx.deps.listDevices();
+            const device = ctx.udid
+                ? devices.find((d) => d.udid === ctx.udid)
+                : devices.find((d) => d.transport === "wired");
+            if (!device || device.transport !== "wired") {
+                const summary = ctx.udid ? `iPhone ${device?.name ?? ctx.udid} isn't connected by USB.` : "No iPhone is connected by USB.";
+                return fail(summary, MESSAGES.connectUsb);
+            }
+            ctx.udid = device.udid;
+            ctx.device = device;
+            ctx.previousIosVersion = (await ctx.deps.readDeviceState(device.udid, { dir: ctx.stateDir }))?.lastIosVersion ?? null;
+            ctx.iosVersionChanged = await ctx.deps.didIosVersionChange(device.udid, device.iosVersion, { dir: ctx.stateDir });
+            const changed = ctx.iosVersionChanged ? ` It moved from iOS ${ctx.previousIosVersion}; re-checking everything.` : "";
+            return pass(`${device.name} (${device.model}, iOS ${device.iosVersion}) is connected.${changed}`);
+        },
+    },
+    {
+        id: "iphone_trusted",
+        title: "iPhone trusts this Mac",
+        kind: "human-detectable",
+        blocking: true,
+        dependsOn: ["iphone_connected"],
+        async detect(ctx) {
+            if (ctx.device.pairingState === "paired")
+                return pass("The iPhone trusts this Mac.");
+            return fail("The iPhone doesn't trust this Mac yet.", MESSAGES.trust);
+        },
+    },
+    {
+        id: "iphone_developer_mode",
+        title: "Developer Mode",
+        kind: "human-detectable",
+        blocking: true,
+        dependsOn: ["iphone_trusted"],
+        async detect(ctx) {
+            ctx.lockState = await ctx.deps.getLockState(ctx.udid);
+            const fresh = (await ctx.deps.listDevices()).find((d) => d.udid === ctx.udid);
+            if (fresh)
+                ctx.device = fresh;
+            if (ctx.device.developerModeStatus === "enabled")
+                return pass("Developer Mode is on.");
+            return fail("Developer Mode is off.", MESSAGES.developerMode);
+        },
+    },
+    {
+        id: "iphone_unlocked",
+        title: "iPhone unlocked",
+        kind: "human-detectable",
+        blocking: true,
+        dependsOn: ["iphone_developer_mode"],
+        async detect(ctx) {
+            const lock = ctx.lockState;
+            if (!lock.unlockedSinceBoot)
+                return fail("The iPhone hasn't been unlocked since it restarted.", MESSAGES.unlock);
+            if (lock.passcodeRequired)
+                return fail("The iPhone is locked.", MESSAGES.unlock);
+            return pass("The iPhone is unlocked.");
+        },
+    },
+    {
+        id: "iphone_device_components",
+        title: "Device components",
+        kind: "human-detectable",
+        blocking: true,
+        dependsOn: ["iphone_unlocked"],
+        async detect(ctx) {
+            const ddi = await ctx.deps.getDdiServices(ctx.udid);
+            const build = ddi?.buildUpdate ? ` (from Xcode build ${ddi.buildUpdate})` : "";
+            if (ddi?.isUsable === true && ddi.contentIsCompatible !== false) {
+                return pass(`This Mac's device components${build} support the iPhone.`);
+            }
+            const ios = ctx.device.iosVersion;
+            return fail(`Your iPhone is on iOS ${ios}. ${xcodeAdviceForIos(ios)}`, `The device components on this Mac${build} can't drive this iPhone.`);
+        },
+    },
+    {
+        id: "wda_signing",
+        title: "Signing ready",
+        kind: "auto",
+        blocking: true,
+        dependsOn: ["apple_team", "iphone_unlocked"],
+        fixLabel: "Set up signing",
+        async detect(ctx) {
+            ctx.bundleIdBase = wdaBundleIdBase(ctx.teamId);
+            const found = await ctx.deps.chooseSigning({ teamId: ctx.teamId, bundleIdBase: ctx.bundleIdBase, udid: ctx.udid });
+            if (found.profile) {
+                ctx.signing = found;
+                return pass(found.reason);
+            }
+            return fail("Signing for the helper app isn't set up yet.", `${found.reason} droid runs a one-time Xcode build (about a minute) to set it up.`);
+        },
+        async fix(ctx) {
+            await ctx.deps.ensureSigning({ udid: ctx.udid, teamId: ctx.teamId, bundleIdBase: ctx.bundleIdBase, onProgress: ctx.onProgress });
+        },
+    },
+    {
+        id: "wda_installed",
+        title: "Helper app (WebDriverAgent)",
+        kind: "auto",
+        blocking: true,
+        dependsOn: ["wda_signing", "iphone_device_components"],
+        fixLabel: "Install helper app",
+        async detect(ctx) {
+            ctx.wdaVersion = await ctx.deps.getPinnedWdaVersion();
+            const runnerBundleId = wdaRunnerBundleId(ctx.bundleIdBase);
+            const apps = await ctx.deps.listApps(ctx.udid, { includeAll: true });
+            if (!apps.some((app) => app.bundleIdentifier === runnerBundleId)) {
+                return fail("The helper app (WebDriverAgent) isn't on the iPhone.", "droid installs it automatically in a few seconds.");
+            }
+            const recorded = (await ctx.deps.readDeviceState(ctx.udid, { dir: ctx.stateDir }))?.wda;
+            const current = recorded?.version === ctx.wdaVersion
+                && recorded?.identitySha1 === ctx.signing.identity.sha1
+                && recorded?.bundleIdBase === ctx.bundleIdBase
+                && recorded?.iosVersion === ctx.device.iosVersion;
+            if (!current) {
+                return fail("The helper app on the iPhone is out of date.", "Its version, signing or the iPhone's iOS changed since droid installed it. droid reinstalls it automatically in a few seconds.");
+            }
+            return pass(`WebDriverAgent ${ctx.wdaVersion} is installed.`);
+        },
+        async fix(ctx) {
+            const result = await ctx.deps.provisionWda({
+                udid: ctx.udid,
+                teamId: ctx.teamId,
+                bundleIdBase: ctx.bundleIdBase,
+                version: ctx.wdaVersion,
+                onProgress: ctx.onProgress,
+            });
+            await ctx.deps.updateDeviceState(ctx.udid, {
+                wda: {
+                    version: result.version,
+                    identitySha1: result.identity.sha1,
+                    bundleIdBase: result.bundleIdBase,
+                    sha256: result.sha256,
+                    profileUuid: result.profile?.uuid ?? null,
+                    iosVersion: ctx.device.iosVersion,
+                    installedAt: new Date().toISOString(),
+                },
+            }, { dir: ctx.stateDir });
+        },
+    },
+    {
+        id: "iphone_auto_lock",
+        title: "Auto-Lock",
+        kind: "human-undetectable",
+        blocking: false,
+        dependsOn: [],
+        async detect() {
+            return warn("Set Auto-Lock to Never on the iPhone while testing.", "Settings > Display & Brightness > Auto-Lock > Never. droid can't read this setting; if the iPhone locks mid-run, droid pauses until you unlock it.");
+        },
+    },
+    {
+        id: "iphone_dedicated",
+        title: "Dedicated test iPhone",
+        kind: "human-undetectable",
+        blocking: false,
+        dependsOn: [],
+        async detect() {
+            return warn("Use a test-only iPhone if you can.", "droid tests the apps and data already on the phone and never resets it.");
+        },
+    },
+];
+const defaultDeps = {
+    findDevicectl: () => execFileAsync("xcrun", ["--find", "devicectl"], { timeout: 15_000 }),
+    checkXcodeLicense: () => execFileAsync("xcodebuild", ["-license", "check"], { timeout: 15_000 }),
+    iosSdkVersion: () => execFileAsync("xcrun", ["--sdk", "iphoneos", "--show-sdk-version"], { timeout: 15_000 }).then(({ stdout }) => stdout.trim()),
+    listIosRuntimes,
+    listXcodeApps: async () => (await readdir("/Applications").catch(() => [])).filter((name) => /^Xcode.*\.app$/i.test(name)).sort(),
+    xcodeSelectPath: () => execFileAsync("xcode-select", ["-p"], { timeout: 15_000 }).then(({ stdout }) => stdout.trim(), () => null),
+    listPaidTeams,
+    listXcodeAccounts,
+    fetchXcodeTeams: () => fetchXcodeTeams({ wdaProjectDir: APPIUM_WDA_DIR }),
+    now: () => Date.now(),
+    listDevices,
+    getLockState,
+    getDdiServices,
+    listApps,
+    chooseSigning,
+    ensureSigning,
+    provisionWda,
+    getPinnedWdaVersion,
+    readDeviceState,
+    updateDeviceState,
+    didIosVersionChange,
+};
+async function detect(check, ctx) {
+    try {
+        return await check.detect(ctx);
+    }
+    catch (error) {
+        return fail(messageForError(error));
+    }
+}
+async function fixAndDetect(check, ctx) {
+    try {
+        ctx.onProgress({ step: check.id, message: `${check.fixLabel}...` });
+        await check.fix(ctx);
+    }
+    catch (error) {
+        return fail(messageForError(error), error?.details);
+    }
+    return detect(check, ctx);
+}
+function toResult(check, outcome, extra = {}) {
+    return {
+        id: check.id,
+        status: outcome.status,
+        title: check.title,
+        summary: outcome.summary,
+        ...(outcome.details ? { details: outcome.details } : {}),
+        ...(outcome.cause ? { cause: outcome.cause } : {}),
+        blocking: check.blocking,
+        checkedAt: new Date().toISOString(),
+        ...(outcome.status === "fail" && check.fix && !extra.blockedBy
+            ? { remediation: [{ kind: "run_fix", label: check.fixLabel, fixId: check.id }] }
+            : {}),
+        kind: check.kind,
+        ...extra,
+    };
+}
+export function firstBlockingFailure(results) {
+    return results.find((r) => r.blocking && r.status === "fail" && !r.blockedBy) ?? null;
+}
+export function describeFailure(result) {
+    return [`${result.title}: ${result.summary}`, result.details].filter(Boolean).join(" ");
+}
+export async function runChecks({ udid = null, teamId = null, autoFix = false, onProgress = () => { }, stateDir, deps = {} } = {}) {
+    const ctx = { udid, teamId, stateDir, onProgress, deps: { ...defaultDeps, ...deps } };
+    const results = [];
+    for (const check of READINESS_CHECKS) {
+        const blocker = check.dependsOn
+            .map((id) => results.find((r) => r.id === id))
+            .find((r) => r.status !== "pass");
+        if (blocker) {
+            const root = blocker.blockedBy ?? blocker.id;
+            const rootTitle = results.find((r) => r.id === root).title;
+            results.push(toResult(check, { status: "fail", summary: `Not checked yet: waiting for "${rootTitle}".` }, { blockedBy: root }));
+            continue;
+        }
+        let outcome = await detect(check, ctx);
+        if (outcome.status === "fail" && autoFix && check.kind === "auto" && check.fix) {
+            outcome = await fixAndDetect(check, ctx);
+        }
+        results.push(toResult(check, outcome));
+    }
+    const ready = results.every((r) => !r.blocking || r.status === "pass");
+    if (ready) {
+        await ctx.deps.updateDeviceState(ctx.udid, { lastIosVersion: ctx.device.iosVersion }, { dir: stateDir });
+    }
+    return {
+        ready,
+        results,
+        context: {
+            udid: ctx.udid,
+            teamId: ctx.teamId,
+            bundleIdBase: ctx.bundleIdBase ?? null,
+            device: ctx.device ?? null,
+            iosVersionChanged: ctx.iosVersionChanged === true,
+            previousIosVersion: ctx.previousIosVersion ?? null,
+        },
+    };
+}

package/build/src/device/ios/real-device/session.js

@@ -0,0 +1,176 @@
+import net from "node:net";
+import * as appium from "../appium-client.js";
+import { getLockState } from "./devicectl.js";
+import { updateDeviceState } from "./device-state.js";
+import { MESSAGES, describeFailure, firstBlockingFailure, runChecks } from "./readiness.js";
+export const IOS_DEVICE_PREFIX = "ios-device:";
+export const WDA_LAUNCH_TIMEOUT_MS = 15_000;
+export const WDA_RELAUNCH_TIMEOUT_MS = 60_000;
+export const UNLOCK_WAIT_MS = 5 * 60_000;
+export const LOCK_CHECK_INTERVAL_MS = 20_000;
+const UNLOCK_POLL_MS = 2_000;
+let statusListener = null;
+export function setRealDeviceStatusListener(fn) {
+    statusListener = fn || null;
+}
+function announce(log, status, message) {
+    if (statusListener) {
+        statusListener({ status, message });
+    }
+    else {
+        log(message);
+    }
+}
+export function findFreePort() {
+    return new Promise((resolve, reject) => {
+        const server = net.createServer();
+        server.unref();
+        server.on("error", reject);
+        server.listen(0, "127.0.0.1", () => {
+            const { port } = server.address();
+            server.close(() => resolve(port));
+        });
+    });
+}
+const defaultDeps = {
+    runChecks,
+    createSession: appium.createSession,
+    deleteSession: appium.deleteSession,
+    getLockState,
+    findFreePort,
+    updateDeviceState,
+    sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+    now: () => Date.now(),
+};
+export function parseIosDeviceToken(name) {
+    if (typeof name !== "string")
+        return null;
+    const trimmed = name.trim();
+    if (!trimmed.toLowerCase().startsWith(IOS_DEVICE_PREFIX))
+        return null;
+    const udid = trimmed.slice(IOS_DEVICE_PREFIX.length).trim();
+    return { udid: udid && udid.toLowerCase() !== "auto" ? udid : null };
+}
+export function realDeviceCapabilities({ udid, bundleIdBase, deviceName, wdaLocalPort, wdaLaunchTimeout = WDA_LAUNCH_TIMEOUT_MS }) {
+    return {
+        platformName: "iOS",
+        "appium:automationName": "XCUITest",
+        "appium:deviceName": deviceName || "iPhone",
+        "appium:udid": udid,
+        "appium:usePreinstalledWDA": true,
+        "appium:updatedWDABundleId": bundleIdBase,
+        "appium:wdaLaunchTimeout": wdaLaunchTimeout,
+        "appium:wdaLocalPort": wdaLocalPort,
+        "appium:noReset": true,
+        "appium:shouldTerminateApp": false,
+    };
+}
+export function isBrokenHelperError(error) {
+    const text = String(error?.message ?? error ?? "");
+    return /Code=41|Not authorized for performing UI testing|local\.pid\.0|attempt to insert nil object/i.test(text);
+}
+function messageForSessionError(error) {
+    const text = String(error?.message ?? error ?? "");
+    if (/Developer Mode is disabled|CoreDeviceError error 10005/i.test(text))
+        return `Developer Mode is off. ${MESSAGES.developerMode}`;
+    if (/is not installed/i.test(text))
+        return "The helper app (WebDriverAgent) isn't on the iPhone. Run droid again to reinstall it.";
+    return `The helper app didn't start on the iPhone: ${text}`;
+}
+export async function createRealDeviceSession({ udid, bundleIdBase, deviceName, log = console.log, deps = {} }) {
+    const { createSession, findFreePort: pickPort } = { ...defaultDeps, ...deps };
+    const wdaLocalPort = await pickPort();
+    try {
+        return await createSession(realDeviceCapabilities({ udid, bundleIdBase, deviceName, wdaLocalPort }));
+    }
+    catch (firstError) {
+        log(`The helper app didn't answer (${String(firstError?.message ?? firstError).slice(0, 160)}).`);
+        announce(log, "allow-automation", `${MESSAGES.allowAutomation}. Relaunching once...`);
+        try {
+            return await createSession(realDeviceCapabilities({ udid, bundleIdBase, deviceName, wdaLocalPort, wdaLaunchTimeout: WDA_RELAUNCH_TIMEOUT_MS }));
+        }
+        catch (error) {
+            throw new Error(messageForSessionError(error));
+        }
+    }
+}
+export async function waitForUnlock({ udid, log = console.log, timeoutMs = UNLOCK_WAIT_MS, intervalMs = UNLOCK_POLL_MS, deps = {} }) {
+    const { getLockState: readLock, sleep, now } = { ...defaultDeps, ...deps };
+    announce(log, "locked", MESSAGES.lockedMidRun);
+    const deadline = now() + timeoutMs;
+    while (now() < deadline) {
+        await sleep(intervalMs);
+        const lock = await readLock(udid).catch(() => null);
+        if (lock && !lock.passcodeRequired) {
+            announce(log, "unlocked", "iPhone unlocked, continuing.");
+            return;
+        }
+    }
+    throw new Error(`The iPhone stayed locked for ${Math.round(timeoutMs / 60_000)} minutes. Unlock it and run again.`);
+}
+export async function startRealDeviceSession({ udid, teamId, log = console.log, deps = {} }) {
+    const d = { ...defaultDeps, ...deps };
+    log(udid ? `Checking iPhone ${udid}...` : "Looking for an iPhone connected by USB...");
+    const readiness = await d.runChecks({ udid, teamId, autoFix: true, onProgress: (p) => log(p.message) });
+    if (!readiness.ready) {
+        const failure = firstBlockingFailure(readiness.results);
+        if (failure.id === "iphone_device_components") {
+            statusListener?.({ status: "device-components", message: failure.summary });
+        }
+        throw new Error(describeFailure(failure));
+    }
+    const { device, bundleIdBase } = readiness.context;
+    log(`Creating Appium session on ${device.name}...`);
+    const session = await createRealDeviceSession({ udid: device.udid, bundleIdBase, deviceName: device.name, log, deps: d });
+    await d.updateDeviceState(device.udid, { lastSuccessAt: new Date().toISOString(), teamId: readiness.context.teamId });
+    return {
+        sessionId: session.sessionId,
+        udid: device.udid,
+        realDevice: true,
+        bundleIdBase,
+        deviceName: device.name,
+        model: device.model,
+        teamId: readiness.context.teamId,
+        lockCheckedAt: d.now(),
+    };
+}
+async function restartSession(session, log, d) {
+    await d.deleteSession(session.sessionId).catch(() => { });
+    const fresh = await createRealDeviceSession({
+        udid: session.udid,
+        bundleIdBase: session.bundleIdBase,
+        deviceName: session.deviceName,
+        log,
+        deps: d,
+    });
+    return fresh.sessionId;
+}
+export async function recoverRealDeviceSession(session, error, { log = console.log, deps = {} } = {}) {
+    const d = { ...defaultDeps, ...deps };
+    const lock = await d.getLockState(session.udid).catch(() => null);
+    if (lock?.passcodeRequired) {
+        await waitForUnlock({ udid: session.udid, log, deps: d });
+    }
+    else if (isBrokenHelperError(error)) {
+        log("The helper app on the iPhone stopped responding. Starting a new session...");
+    }
+    else {
+        return null;
+    }
+    return restartSession(session, log, d);
+}
+export async function recoverIfLocked(session, { log = console.log, deps = {} } = {}) {
+    const d = { ...defaultDeps, ...deps };
+    if (Number.isFinite(session.lockCheckedAt) && d.now() - session.lockCheckedAt < LOCK_CHECK_INTERVAL_MS) {
+        return null;
+    }
+    session.lockCheckedAt = d.now();
+    const lock = await d.getLockState(session.udid).catch(() => null);
+    if (!lock?.passcodeRequired) {
+        return null;
+    }
+    await waitForUnlock({ udid: session.udid, log, deps: d });
+    const sessionId = await restartSession(session, log, d);
+    session.lockCheckedAt = d.now();
+    return sessionId;
+}