stim 1.18.0 → 1.20.0

package/dist/device-DVCwAFlX.mjs

@@ -0,0 +1,727 @@
+import { n as ownership_claim_exports } from "./process-identity-Biv3arCO.mjs";
+import { t as getExecutor } from "./exec-B81Qodjn.mjs";
+import { D as withConfigLock, H as projectDeviceSlots, _ as loadConfig, a as clearDevice, b as releaseAndroidConsolePort, i as clearAndroidBootPending, k as acquireAvdClaim, t as allConsolePortsAndSerials, w as setDevice, z as deviceSlotPlatforms } from "./config-D0LhTY3S.mjs";
+import { l as androidDataPartitionSizeGbSetting, o as androidAvdConfigSetting } from "./settings-Bbztm4oV.mjs";
+import { l as phaseLine } from "./command-output-BjPN99ZB.mjs";
+import { o as ownedDeviceLabel } from "./project-B8_duAzW.mjs";
+import { A as listAvds, B as ownedAvdSystemImage, E as getAvdNameForSerial, F as ownedAvdDeviceProfile, J as resolveOwnedAvdSerial, L as ownedAvdMatchesConfiguration, O as listAdbDevices, P as nextConsolePort, R as ownedAvdName, W as pickDefaultSystemImage, b as createOwnedAvd, dt as parkedMaxSetting, f as assertOwnedAvdStopped, ft as readParked, g as avdPoolConfiguration, j as listInstalledSystemImages, lt as isLegacyDeletionClaim, n as OWNED_AVD_CONFIG_DEFAULTS, ot as adoptParked, t as DEFAULT_AVD_DEVICE_PROFILE, tt as waitForBoot, v as bootAndroidEmulator, y as configureNewOwnedAvd } from "./android-BsYNR81W.mjs";
+import { s as pidExists } from "./metro-D_j9sN-B.mjs";
+import { v as teardownOwnedAvd, x as teardownParkedAvd } from "./workspaces-D2xSHBDY.mjs";
+import { F as memoryCulpritAdvice, N as memoryCulpritsUnder, P as readHostMemoryPressure, d as listAllIosSims } from "./ios-CXLIUxXJ.mjs";
+import { t as clearDeviceIdleShutdown } from "./idle-shutdown-DdMqoSUB.mjs";
+import { i as countLiveOwnedDevices, n as DeviceAdmissionRefusal, p as withDeviceBootAdmission } from "./device-capacity-Ca_ke1LE.mjs";
+import { t as reconcileSimSlim } from "./simslim-ChMfe8rg.mjs";
+import { i as ensureOwnedIosDevice, r as ensureIosBooted } from "./device-ios-CRUqPxKw.mjs";
+import { claimRemoveCommand, clearClaimChild, markClaimChildPending, processGroupAlive, releaseClaim, setClaimChild } from "@stim-cli/core/ownership-claim";
+import { captureProcessIdentity } from "@stim-cli/core/process-identity";
+import { randomUUID } from "node:crypto";
+import chalk from "chalk";
+import { isDeepStrictEqual } from "node:util";
+import { request } from "node:http";
+//#region src/engine/metro-warmup.ts
+const WARMUP_TIMEOUT_MS = 6e4;
+async function requestLocal(url, platform, prefetch) {
+	return new Promise((resolve) => {
+		const req = request(url, { headers: {
+			accept: "application/json",
+			"expo-platform": platform,
+			...prefetch ? { "x-stim-metro-warmup": "1" } : {}
+		} });
+		const timer = setTimeout(() => req.destroy(), WARMUP_TIMEOUT_MS);
+		timer.unref();
+		req.on("socket", (socket) => socket.unref());
+		req.on("error", () => resolve(null));
+		req.on("close", () => {
+			clearTimeout(timer);
+			resolve(null);
+		});
+		req.on("response", (res) => {
+			let body = "";
+			res.setEncoding("utf8");
+			res.on("data", (chunk) => {
+				if (!prefetch) body += chunk;
+			});
+			res.on("error", () => resolve(null));
+			res.on("end", () => resolve(res.statusCode === 200 ? body : null));
+		});
+		req.end();
+	});
+}
+async function warmMetro({ port, platform, isExpo, appId, bundleUrl }) {
+	try {
+		const origin = `http://127.0.0.1:${port}`;
+		if (await requestLocal(new URL("/_stim/metro-warmup", origin), platform, false) !== "ready") return;
+		const url = new URL("/index.bundle", origin);
+		url.search = new URLSearchParams({
+			platform,
+			dev: "true",
+			lazy: "true",
+			minify: "false",
+			...platform === "ios" ? { inlineSourceMap: "false" } : {},
+			modulesOnly: "false",
+			runModule: "true",
+			excludeSource: "true",
+			sourcePaths: "url-server",
+			...appId ? { app: appId } : {}
+		}).toString();
+		if (!bundleUrl && isExpo) {
+			const body = await requestLocal(new URL(origin), platform, false);
+			if (body === null) return;
+			const manifest = JSON.parse(body);
+			bundleUrl = manifest.launchAsset?.url ?? manifest.bundleUrl;
+			if (typeof bundleUrl !== "string") return;
+		}
+		if (bundleUrl) {
+			const bundle = new URL(bundleUrl, origin);
+			url.pathname = bundle.pathname;
+			url.search = bundle.search;
+		}
+		await requestLocal(url, platform, true);
+	} catch {}
+}
+//#endregion
+//#region src/engine/android-avd-setup.ts
+var AvdBootError = class extends Error {
+	remedy;
+	constructor(message, remedy, cause) {
+		super(message, { cause });
+		this.remedy = remedy;
+	}
+};
+var AvdRecoveryError = class extends AvdBootError {};
+function findOtherOwner(avdName, projectPath, selectedSlot = "default") {
+	for (const [path, project] of Object.entries(loadConfig()?.projects ?? {})) if (projectDeviceSlots(project).some(({ slot, platforms }) => (path !== projectPath || slot !== selectedSlot) && platforms.android?.avdName?.toLowerCase() === avdName.toLowerCase())) return path;
+	return null;
+}
+async function prepareOwnedAvd({ projectPath, slot, label, previousAvdName, systemImage, deviceProfile, configuration, configure, teardown = teardownOwnedAvd }) {
+	const { claim, reservation, previous, avdName } = withConfigLock(() => {
+		const previous = deviceSlotPlatforms(loadConfig()?.projects?.[projectPath], slot)?.android;
+		if (previous?.avdName && previous.avdName !== previousAvdName) throw new Error(`Another Stim run assigned AVD ${previous.avdName} to this workspace. Retry to use it.`);
+		if (readParked("android").some((entry) => entry.name === ownedAvdName(label)) || findOtherOwner(ownedAvdName(label), projectPath, slot)) label = `${label}-${randomUUID().slice(0, 8)}`;
+		const avdName = ownedAvdName(label);
+		const claim = acquireAvdClaim(avdName);
+		const reservation = {
+			avdName,
+			owned: true,
+			deviceName: avdName,
+			setupIncomplete: true,
+			poolConfiguration: configuration
+		};
+		try {
+			setDevice(projectPath, "android", reservation, slot);
+			return {
+				claim,
+				reservation,
+				previous,
+				avdName
+			};
+		} catch (error) {
+			releaseClaim(claim);
+			throw error;
+		}
+	});
+	const currentRecord = () => deviceSlotPlatforms(loadConfig()?.projects?.[projectPath], slot)?.android;
+	const assertReservation = () => {
+		if (readParked("android").some((entry) => entry.name === avdName)) throw new Error(`AVD ${avdName} was parked by another Stim run. Retry to adopt it safely.`);
+		const owner = findOtherOwner(avdName, projectPath, slot);
+		if (owner) throw new Error(`AVD ${avdName} already exists and is owned by another project (${owner}). Retry to allocate a distinct owned emulator.`);
+		const current = currentRecord();
+		if (!isDeepStrictEqual(current, reservation)) {
+			const state = current?.setupIncomplete ? "has incomplete setup" : "was registered or removed";
+			throw new Error(`AVD ${current?.avdName ?? avdName} ${state} by another concurrent Stim run. Retry after that run finishes so the recorded device is resolved safely.`);
+		}
+	};
+	let prepared;
+	let child;
+	const creationRunning = () => child?.pid !== void 0 && processGroupAlive(child.pid);
+	let configurationFailure;
+	try {
+		try {
+			const creation = await createOwnedAvd(label, {
+				systemImage,
+				deviceProfile,
+				spawn: (...args) => {
+					markClaimChildPending(claim);
+					child = getExecutor().spawn(...args);
+					if (child.pid !== void 0) {
+						const captured = captureProcessIdentity(child.pid);
+						if (captured.ok) try {
+							setClaimChild(claim, {
+								pid: child.pid,
+								processToken: captured.token
+							});
+						} catch {}
+					}
+					return child;
+				}
+			}).then((result) => ({ result }), (error) => ({ error }));
+			if (creationRunning()) throw new AvdRecoveryError(`AVD ${avdName} creation left its process group running (pid ${child.pid}); its reservation remains incomplete.`, `Wait for process group ${child.pid} to finish before retrying stim android. If its identity could not be recorded, inspect the group and remove the claim only after it stops: ${claimRemoveCommand(claim.path)}`);
+			clearClaimChild(claim);
+			if ("error" in creation) throw creation.error;
+			prepared = {
+				...creation.result,
+				created: true
+			};
+		} catch (error) {
+			const message = String(error?.message || error);
+			if (!message.includes("already exists")) throw error;
+			try {
+				if (!listAvds().includes(avdName)) throw new AvdRecoveryError(`AVD ${avdName} already exists on disk but is not listed by the emulator. ${message}`, "Run `npx stim gc` to inspect orphaned owned AVDs, then `npx stim gc --delete` to reclaim those safe to delete. Retry `stim android` after cleanup; keep any AVD that GC cannot verify.", error);
+				withConfigLock(assertReservation);
+				const resolved = resolveOwnedAvdSerial(avdName);
+				if (resolved.missing || resolved.notOwned) throw new Error(`AVD ${avdName} could not be verified for recovery. Retry after checking its registration.`, { cause: error });
+				if (!resolved.serial) assertOwnedAvdStopped(avdName);
+				prepared = {
+					avdName,
+					created: false,
+					systemImage: ownedAvdSystemImage(avdName),
+					deviceProfile: ownedAvdDeviceProfile(avdName),
+					...resolved.serial ? {
+						serial: resolved.serial,
+						consolePort: Number(resolved.serial.replace(/^emulator-/, ""))
+					} : {}
+				};
+			} catch (recoveryError) {
+				withConfigLock(() => {
+					if (!isDeepStrictEqual(currentRecord(), reservation)) return;
+					if (previous) setDevice(projectPath, "android", previous, slot);
+					else clearDevice(projectPath, "android", slot, avdName);
+				});
+				if (recoveryError instanceof AvdRecoveryError) throw recoveryError;
+				throw new AvdRecoveryError(`Could not recover owned AVD ${avdName}: ${String(recoveryError?.message || recoveryError)}`, "Inspect `npx stim status` and `adb devices`. Wait for any other Stim run using this AVD to finish, then retry `stim android`. Keep the AVD and its process locks while its state is unverified.", recoveryError);
+			}
+		}
+		if (prepared.created) try {
+			configure(avdName);
+		} catch (error) {
+			configurationFailure = { error };
+		}
+		if (!configurationFailure) withConfigLock(() => {
+			assertReservation();
+			setDevice(projectPath, "android", {
+				avdName,
+				owned: true,
+				deviceName: avdName,
+				...prepared.created ? {
+					poolConfiguration: configuration,
+					bootPending: true
+				} : {},
+				...prepared.consolePort ? { consolePort: prepared.consolePort } : {}
+			}, slot);
+		});
+	} finally {
+		if (!creationRunning()) releaseClaim(claim);
+		else {
+			child?.stdout?.destroy();
+			child?.stderr?.destroy();
+			child?.unref();
+		}
+	}
+	if (configurationFailure) {
+		const { error } = configurationFailure;
+		const cleanup = teardown(avdName, {
+			del: true,
+			owner: {
+				projectPath,
+				slot,
+				expectedRecord: reservation
+			},
+			onRemoved: () => {
+				clearDevice(projectPath, "android", slot, avdName);
+			}
+		});
+		const orphan = cleanup.status === "failed" || cleanup.status === "skipped" ? ` The owned AVD remains tracked for cleanup (${cleanup.reason || cleanup.status}); fix the cause, then retry or run \`stim gc --delete\`.` : "";
+		throw new Error(`Created owned AVD ${avdName}, but could not configure its AVD settings: ${String(error?.message || error)}${orphan}`, { cause: error });
+	}
+	return prepared;
+}
+//#endregion
+//#region src/engine/device-android.ts
+const ANDROID_FRESH_BOOT_TIMEOUT_MS = process.platform === "win32" ? 12e5 : 12e4;
+const ANDROID_BOOT_TIMEOUT_MS = process.platform === "win32" ? 12e5 : 24e4;
+async function ensureOwnedAndroidDevice({ record, projectPath, slot, settingsRoot, label, settings, flags, note, out, logFile, alive, configureAvd, teardownAvd }) {
+	const projectAvdConfig = androidAvdConfigSetting(settings, settingsRoot);
+	const avdConfig = {
+		...OWNED_AVD_CONFIG_DEFAULTS,
+		...projectAvdConfig
+	};
+	const requestedProfile = flags.deviceProfile || settings.android?.deviceProfile || null;
+	let replacedProfile = null;
+	if (record?.setupIncomplete && record.avdName) {
+		const avdName = record.avdName;
+		const cleanup = teardownAvd(avdName, {
+			del: true,
+			owner: {
+				projectPath,
+				slot,
+				expectedRecord: record
+			},
+			onRemoved: () => {
+				clearDevice(projectPath, "android", slot, avdName);
+			}
+		});
+		if (cleanup.status === "failed" || cleanup.status === "skipped") throw new AvdRecoveryError(`Owned AVD ${record.avdName} has incomplete setup and could not be deleted (${cleanup.reason || cleanup.status}). Fix the cause, then retry; Stim kept the device record for cleanup.`, "Wait for any active AVD operation to finish. If the refusal names an unresolved claim, inspect its creator and native processes before removing only that claim. Retry `stim android` to reconcile the incomplete device.");
+		record = null;
+	}
+	const requestedImage = flags.systemImageFlag || null;
+	const currentImage = requestedImage && record?.owned && record.avdName ? ownedAvdSystemImage(record.avdName) : null;
+	if (record?.avdName && requestedImage && currentImage && currentImage !== requestedImage) {
+		const avdName = record.avdName;
+		if (!record.bootPending) throw new AvdRecoveryError(`this project's emulator ${avdName} uses system image ${currentImage}, but ${requestedImage} was requested. --system-image replaces only an emulator that never finished a boot, and this one has.`, "Run `stim worktree remove` (or `stim gc --delete`) to reap the current emulator, then `stim android` again to create the requested one, or pass `--slot <name>` to create it beside the current one.");
+		replacedProfile = ownedAvdDeviceProfile(avdName);
+		const cleanup = teardownAvd(avdName, {
+			del: true,
+			owner: {
+				projectPath,
+				slot,
+				expectedRecord: record
+			},
+			onRemoved: () => {
+				clearDevice(projectPath, "android", slot, avdName);
+			}
+		});
+		if (cleanup.status === "failed" || cleanup.status === "skipped") throw new AvdRecoveryError(`Owned AVD ${avdName} never finished a boot, but could not be deleted to create one on ${requestedImage} (${cleanup.reason || cleanup.status}). Stim kept the device record.`, "Fix the cause, then retry, or pass `--slot <name>` to create the requested emulator beside it.");
+		out(phaseLine("device", `deleted ${avdName}, which never finished a boot, to create one on ${requestedImage}`));
+		record = null;
+	}
+	const deviceProfile = requestedProfile ?? replacedProfile ?? DEFAULT_AVD_DEVICE_PROFILE;
+	const configuration = avdPoolConfiguration(androidDataPartitionSizeGbSetting(settings), avdConfig, deviceProfile);
+	const configurationBeforeDefaults = avdPoolConfiguration(androidDataPartitionSizeGbSetting(settings), projectAvdConfig, deviceProfile);
+	if (record?.avdName) {
+		if (record.owned) {
+			const resolved = resolveOwnedAvdSerial(record.avdName);
+			const currentProfile = resolved.notOwned || resolved.missing ? null : ownedAvdDeviceProfile(record.avdName);
+			if (requestedProfile && currentProfile && currentProfile !== requestedProfile) throw new AvdRecoveryError(`this project's emulator uses device profile ${currentProfile}, but ${requestedProfile} was requested. Stim will not silently boot a different model.`, "Run `stim worktree remove` (or `stim gc --delete`) to reap the current emulator, then `stim android` again to create the requested one, or pass `--slot <name>` to create it beside the current one.");
+			if (resolved.notOwned) note(chalk.yellow(`Note: recorded AVD ${record.avdName} is not Stim-owned -- creating a fresh owned AVD instead of reusing it.`));
+			else if (resolved.serial) {
+				const consolePort = Number(resolved.serial.replace(/^emulator-/, ""));
+				if (record.consolePort && record.consolePort !== consolePort) out(phaseLine("device", `${record.avdName} changed serial (emulator-${record.consolePort} -> ${resolved.serial}); reconnecting this run, reopen agent-device on ${resolved.serial}`));
+				const updated = {
+					...record,
+					avdName: record.avdName,
+					consolePort,
+					owned: true,
+					deviceName: record.deviceName ?? record.avdName
+				};
+				setDevice(projectPath, "android", updated, slot);
+				return {
+					...updated,
+					systemImage: ownedAvdSystemImage(record.avdName),
+					deviceProfile: currentProfile
+				};
+			} else if (!resolved.missing) {
+				out(chalk.dim(`Recorded port for owned AVD ${record.avdName} is not currently ours; booting it on a freshly allocated port...`));
+				return {
+					...await bootOwnedAvdOnFreshPort({
+						deviceSlotWait: flags.deviceSlotWait,
+						avdName: record.avdName,
+						metadata: record,
+						projectPath,
+						slot,
+						deviceName: record.deviceName,
+						out,
+						logFile,
+						alive
+					}),
+					systemImage: ownedAvdSystemImage(record.avdName),
+					deviceProfile: currentProfile
+				};
+			}
+		} else if (listAvds().includes(record.avdName)) {
+			if (!listAdbDevices().emulators.some((e) => e.consolePort === record.consolePort)) {
+				note(chalk.yellow(`Note: assigned AVD ${record.avdName} (emulator-${record.consolePort}) is shut down and is not owned by Stim, so it will not be booted automatically.`));
+				note(chalk.dim("Boot it yourself, or run `stim gc --delete` to clear the assignment so Stim can create an owned AVD."));
+			}
+			return record;
+		}
+	} else if (record?.serial) {
+		note(chalk.yellow(`Note: this project has a stored assignment to physical device ${record.serial}, which Stim no longer keeps.`));
+		note(chalk.dim("Creating an owned emulator instead. Pass `--device` to build for a connected device."));
+	}
+	if (parkedMaxSetting("android").max > 0) {
+		const systemImage = pickDefaultSystemImage(listInstalledSystemImages(), { systemImage: flags.systemImage || settings.android?.systemImage })?.pkg;
+		const candidates = readParked("android").filter((entry) => entry.systemImage === systemImage && (entry.configuration === configuration || entry.configuration === configurationBeforeDefaults)).toSorted((a, b) => a.parkedAt.localeCompare(b.parkedAt));
+		for (const parked of candidates) {
+			if (isLegacyDeletionClaim(parked.deletionClaim)) continue;
+			const resolved = resolveOwnedAvdSerial(parked.name);
+			if (resolved.missing) {
+				const result = teardownParkedAvd(parked.name);
+				if (result.status === "failed") out(phaseLine("device", `kept ${parked.name}: ${result.reason}`));
+				continue;
+			}
+			if (resolved.notOwned || resolved.serial) continue;
+			try {
+				assertOwnedAvdStopped(parked.name);
+			} catch (error) {
+				out(phaseLine("device", `kept parked ${parked.name}: ${String(error?.message || error)}`));
+				continue;
+			}
+			if (ownedAvdSystemImage(parked.name) !== systemImage || !ownedAvdMatchesConfiguration(parked.name, parked.configuration)) {
+				const result = teardownParkedAvd(parked.name);
+				if (result.status === "failed") out(phaseLine("device", `kept ${parked.name}: ${result.reason}`));
+				continue;
+			}
+			const adopted = {
+				avdName: parked.name,
+				deviceName: parked.name,
+				owned: true,
+				poolConfiguration: parked.configuration,
+				adoptionPending: true
+			};
+			if (!adoptParked({
+				platform: "android",
+				projectPath,
+				slot,
+				udid: parked.udid,
+				device: adopted
+			})) continue;
+			if (parked.configuration !== configuration) try {
+				configureAvd(parked.name, {
+					dataPartitionSizeGb: androidDataPartitionSizeGbSetting(settings),
+					avdConfig
+				});
+				adopted.poolConfiguration = configuration;
+			} catch (error) {
+				out(phaseLine("device", `${parked.name} keeps its old AVD settings: ${String(error?.message || error)}`));
+			}
+			return {
+				...await bootOwnedAvdOnFreshPort({
+					deviceSlotWait: flags.deviceSlotWait,
+					avdName: parked.name,
+					projectPath,
+					slot,
+					metadata: adopted,
+					out,
+					logFile,
+					alive
+				}),
+				adopted: true,
+				systemImage,
+				deviceProfile
+			};
+		}
+	}
+	const created = await prepareOwnedAvd({
+		projectPath,
+		slot,
+		label,
+		previousAvdName: record?.avdName,
+		systemImage: flags.systemImage || settings.android?.systemImage || void 0,
+		deviceProfile,
+		configuration,
+		configure: (avdName) => configureAvd(avdName, {
+			dataPartitionSizeGb: androidDataPartitionSizeGbSetting(settings),
+			avdConfig
+		}),
+		teardown: teardownAvd
+	});
+	if (!created.created) {
+		out(chalk.dim(phaseLine("device", `recovered ${created.avdName} (unrecorded from a prior run)`)));
+		if (created.serial) return {
+			...created,
+			owned: true,
+			deviceName: created.avdName
+		};
+	}
+	return {
+		...await bootOwnedAvdOnFreshPort({
+			deviceSlotWait: flags.deviceSlotWait,
+			avdName: created.avdName,
+			metadata: created.created ? {
+				poolConfiguration: configuration,
+				bootPending: true
+			} : void 0,
+			projectPath,
+			slot,
+			deviceName: created.avdName,
+			out,
+			logFile,
+			alive
+		}),
+		created: created.created,
+		systemImage: created.systemImage,
+		deviceProfile: created.deviceProfile
+	};
+}
+function claimAndroidConsolePort({ projectPath, slot, avdName, deviceName, livePorts = [], metadata }, { lock = withConfigLock, recordedPorts = () => allConsolePortsAndSerials().androidConsolePorts, record = setDevice } = {}) {
+	return lock(() => {
+		const consolePort = nextConsolePort([...recordedPorts(), ...livePorts]);
+		const claim = {
+			...metadata?.poolConfiguration ? { poolConfiguration: metadata.poolConfiguration } : {},
+			...metadata?.adoptionPending ? { adoptionPending: true } : {},
+			...metadata?.bootPending ? { bootPending: true } : {},
+			avdName,
+			consolePort,
+			owned: true,
+			deviceName: deviceName ?? avdName
+		};
+		record(projectPath, "android", claim, slot);
+		return claim;
+	});
+}
+function liveAndroidConsolePorts() {
+	const adbLive = listAdbDevices();
+	return [...adbLive.emulators.map((e) => e.consolePort), ...adbLive.unhealthy.map((u) => u.consolePort).filter((p) => p != null)];
+}
+async function bootOwnedAvdOnFreshPort({ avdName, deviceSlotWait, metadata, projectPath, slot, deviceName, out, logFile = null, alive = pidExists }) {
+	return withDeviceBootAdmission({
+		platform: "android",
+		key: avdName
+	}, async () => {
+		const claim = claimAndroidConsolePort({
+			projectPath,
+			slot,
+			avdName,
+			deviceName,
+			livePorts: liveAndroidConsolePorts(),
+			metadata
+		});
+		const serial = `emulator-${claim.consolePort}`;
+		try {
+			reportAndroidMemoryPressure(out);
+			const pid = bootAndroidEmulator(avdName, claim.consolePort, { logFile });
+			out(chalk.dim(phaseLine("device", `waiting for ${serial} to finish booting`)));
+			const result = await waitForAndroidBoot({
+				serial,
+				timeoutMs: ANDROID_FRESH_BOOT_TIMEOUT_MS,
+				pid,
+				alive,
+				out
+			});
+			if (result.failed) throw new AvdBootError(result.reason, result.remedy);
+			const running = getAvdNameForSerial(serial);
+			if (running && running !== avdName) throw new Error(`${serial} is running AVD ${running}, not this workspace's owned AVD ${avdName}; refusing to use it.`);
+			clearAndroidBootPending(projectPath, avdName, slot);
+			const { bootPending: _booted, ...booted } = claim;
+			return {
+				...booted,
+				serial,
+				setup: true
+			};
+		} catch (error) {
+			releaseAndroidConsolePort(projectPath, claim.consolePort, slot);
+			throw error;
+		}
+	}, {
+		...deviceSlotWait,
+		root: projectPath,
+		out
+	});
+}
+function reportAndroidMemoryPressure(out) {
+	const pressure = readHostMemoryPressure();
+	if (pressure === "warning" || pressure === "critical") {
+		const named = memoryCulpritAdvice(memoryCulpritsUnder(pressure));
+		out(chalk.dim(phaseLine("memory", `macOS reports ${pressure} host memory pressure; emulator boot may be slow.${named ? ` ${named}` : ""} Free memory with \`stim stop\` only in workspaces you own; ask before closing other apps or devices.`)));
+	}
+}
+function androidBootRemedy(pressure) {
+	let count = null;
+	try {
+		const live = countLiveOwnedDevices({
+			sims: () => process.platform === "darwin" ? listAllIosSims({ timeoutMs: 2e3 }) : [],
+			adb: () => ({
+				...listAdbDevices({ timeoutMs: 2e3 }),
+				unhealthy: []
+			}),
+			booting: []
+		});
+		count = typeof live === "number" ? live : null;
+	} catch {}
+	const named = memoryCulpritAdvice(memoryCulpritsUnder(pressure));
+	const observation = pressure === "warning" || pressure === "critical" ? `macOS reports ${pressure} host memory pressure. ${named ? `${named} ` : ""}` : "";
+	const devices = count ? `${count} Stim-owned ${count === 1 ? "device is" : "devices are"} running. ` : "";
+	if (observation || devices) return `${observation}${devices}Stop an unneeded device with \`stim stop\` only in a workspace you own, then run \`stim android\` again; ask before closing other apps or devices. These observations do not establish the cause of the timeout or an OOM crash.`;
+	return "Inspect the emulator log and run `stim doctor` to check JAVA_HOME, ANDROID_HOME, and installed system images, then run `stim android` again.";
+}
+async function waitForAndroidBoot({ serial, timeoutMs, pid = null, alive = pidExists, out }) {
+	const aborted = () => pid !== null && !alive(pid);
+	const wait = (windowMs) => waitForBoot(serial, windowMs, {
+		aborted,
+		commandTimeoutMs: 5e3
+	});
+	let result = await wait(timeoutMs);
+	if (result.ok) return {
+		ok: true,
+		serial
+	};
+	let pressure = readHostMemoryPressure();
+	let elapsedMs = timeoutMs;
+	if (!result.exited && pid !== null && !aborted() && (pressure === "warning" || pressure === "critical")) {
+		const extensionMs = 24e4;
+		out(chalk.dim(phaseLine("memory", `macOS reports ${pressure} host memory pressure; retrying the boot wait once for the same live emulator ${serial} (up to ${extensionMs / 1e3}s more).`)));
+		result = await wait(extensionMs);
+		if (result.ok) return {
+			ok: true,
+			serial
+		};
+		elapsedMs += extensionMs;
+		pressure = readHostMemoryPressure();
+	}
+	const exited = result.exited || aborted();
+	return {
+		failed: true,
+		reason: `${exited ? `The emulator process for ${serial} exited before the device finished booting.` : `Emulator ${serial} did not finish booting within ${Math.round(elapsedMs / 1e3)}s.`} Diagnostic: ${JSON.stringify(result.diagnostic)}`,
+		remedy: exited ? "Inspect the emulator log for the process exit, fix what it reports, then run `stim android` again." : androidBootRemedy(pressure)
+	};
+}
+async function ensureAndroidBooted({ device, deviceSlotWait, projectPath, slot, timeoutMs, out, logFile = null, alive = pidExists }) {
+	if (!device?.avdName || !projectPath) return {
+		failed: true,
+		reason: "No owned Android emulator is recorded for this project."
+	};
+	let resolved;
+	try {
+		resolved = resolveOwnedAvdSerial(device.avdName);
+	} catch (e) {
+		return {
+			failed: true,
+			reason: `Could not list AVDs: ${e?.message || e}`
+		};
+	}
+	if (resolved.missing) return {
+		failed: true,
+		reason: `AVD ${device.avdName} no longer exists. Run \`stim android\` again to create a fresh owned AVD.`
+	};
+	if (resolved.notOwned) return {
+		failed: true,
+		reason: `AVD ${device.avdName} is not Stim-owned; refusing to boot it.`
+	};
+	const avdName = device.avdName;
+	const booted = (result) => {
+		if (!result.failed) clearAndroidBootPending(projectPath, avdName, slot);
+		return result;
+	};
+	if (resolved.serial) return booted(await waitForAndroidBoot({
+		serial: resolved.serial,
+		timeoutMs,
+		out
+	}));
+	const freshSerial = `emulator-${device.consolePort}`;
+	if (device.owned && device.serial === freshSerial) return booted(await waitForAndroidBoot({
+		serial: freshSerial,
+		timeoutMs,
+		out
+	}));
+	const boot = async () => {
+		const claim = claimAndroidConsolePort({
+			projectPath,
+			slot,
+			avdName,
+			deviceName: device.deviceName,
+			livePorts: liveAndroidConsolePorts(),
+			metadata: device
+		});
+		const serial = `emulator-${claim.consolePort}`;
+		reportAndroidMemoryPressure(out);
+		out(chalk.dim(phaseLine("device", `booting ${avdName} as ${serial}`)));
+		let pid = null;
+		try {
+			pid = bootAndroidEmulator(avdName, claim.consolePort, { logFile });
+		} catch (e) {
+			releaseAndroidConsolePort(projectPath, claim.consolePort, slot);
+			return {
+				failed: true,
+				reason: `Could not start emulator for AVD ${avdName}: ${e?.message || e}`
+			};
+		}
+		const result = await waitForAndroidBoot({
+			serial,
+			timeoutMs,
+			pid,
+			alive,
+			out
+		});
+		if (result.failed) releaseAndroidConsolePort(projectPath, claim.consolePort, slot);
+		return booted(result);
+	};
+	try {
+		return await withDeviceBootAdmission({
+			platform: "android",
+			key: avdName
+		}, boot, {
+			...deviceSlotWait,
+			root: projectPath,
+			out
+		});
+	} catch (error) {
+		const refusal = error instanceof DeviceAdmissionRefusal ? error : (0, ownership_claim_exports.claimFailure)(error, "stim android");
+		if (!refusal) throw error;
+		return {
+			failed: true,
+			code: refusal.code,
+			reason: refusal.message,
+			remedy: refusal.remedy
+		};
+	}
+}
+//#endregion
+//#region src/engine/device.ts
+/**
+* Whether `ensureOwnedDevice` created, adopted or started booting the device, rather than finding it booted.
+* Undefined for a remote device, which those functions do not describe.
+*/
+function didSetUpDevice(device, remote) {
+	return remote ? void 0 : Boolean(device.setup || device.booting);
+}
+async function ensureOwnedDevice({ platform, project, projectPath, slot, settingsRoot = projectPath, label = ownedDeviceLabel(projectPath), settings, flags = {}, note = () => {}, out = () => {}, logFile = null, alive = pidExists, configureAvd = configureNewOwnedAvd, teardownAvd = teardownOwnedAvd, reconcileIosSimulator = reconcileSimSlim, simSnapshot }) {
+	clearDeviceIdleShutdown(projectPath, platform, slot);
+	if (slot && slot !== "default") label = `${label}-${slot}`;
+	const record = deviceSlotPlatforms(project, slot)?.[platform] ?? null;
+	if (platform === "ios") return ensureOwnedIosDevice({
+		record,
+		projectPath,
+		slot,
+		settingsRoot,
+		label,
+		settings,
+		flags,
+		note,
+		out,
+		reconcileIosSimulator,
+		simSnapshot
+	});
+	return ensureOwnedAndroidDevice({
+		record,
+		projectPath,
+		slot,
+		settingsRoot,
+		label,
+		settings,
+		flags,
+		note,
+		out,
+		logFile,
+		alive,
+		configureAvd,
+		teardownAvd
+	});
+}
+const BOOT_POLL_MS = 500;
+async function ensureBooted({ platform, device, simulatorApp, timeoutMs, pollMs = BOOT_POLL_MS, out = () => {}, logFile = null, alive = pidExists, projectPath, slot, deviceSlotWait }) {
+	if (platform === "ios") return ensureIosBooted({
+		device,
+		projectPath,
+		deviceSlotWait,
+		simulatorApp,
+		timeoutMs: timeoutMs ?? 6e5,
+		pollMs,
+		out
+	});
+	if (platform === "android") return ensureAndroidBooted({
+		device,
+		deviceSlotWait,
+		projectPath,
+		slot,
+		timeoutMs: timeoutMs ?? ANDROID_BOOT_TIMEOUT_MS,
+		out,
+		logFile,
+		alive
+	});
+	return {
+		failed: true,
+		reason: `Unknown platform "${platform}".`
+	};
+}
+//#endregion
+export { AvdRecoveryError as a, AvdBootError as i, ensureBooted as n, warmMetro as o, ensureOwnedDevice as r, didSetUpDevice as t };