stim 1.19.0 → 1.20.0

package/dist/launch-DxH0THLP.mjs

@@ -0,0 +1,745 @@
+import { t as spawnEntry } from "./spawn-entry-Dcb7sDUz.mjs";
+import { C as saveConfig, D as withConfigLock, E as upsertProject, L as deviceSlotFileKey, R as deviceSlotKey, _ as loadConfig, j as formatBytes, w as setDevice, z as deviceSlotPlatforms } from "./config-D0LhTY3S.mjs";
+import { j as providerUploadOutcome } from "./device-lease-DHOBXGgS.mjs";
+import { w as workspaceLogsDir } from "./workspace-state-CSIFuuDa.mjs";
+import { _ as stepTimer, c as launchErrorReport, i as formatDuration, l as phaseLine, n as appReadinessMessage, v as launchErrorPreview } from "./command-output-BjPN99ZB.mjs";
+import { I as workspaceDevServerMode } from "./project-B8_duAzW.mjs";
+import { a as workspaceLinks } from "./stim-desktop-8GQX2OV8.mjs";
+import { $ as trimAndroidCaches, i as androidDataFreeBytes, q as resetAdoptedAvd, u as androidToolCwd } from "./android-BsYNR81W.mjs";
+import { d as signalProcessTree, s as pidExists } from "./metro-D_j9sN-B.mjs";
+import { v as teardownOwnedAvd } from "./workspaces-D2xSHBDY.mjs";
+import { o as exitAfterFlush } from "./remote-cache-Bsts6f6Y.mjs";
+import { a as VERIFY_TIMEOUT_MS, i as RELEASE_VERIFY_WAIT_MS, l as unattributedLaunchLines, n as LAUNCH_FATAL, r as LAUNCH_UNVERIFIED, t as LAUNCH_BUNDLING, u as unverifiedLaunchLines } from "./launch-verify-BzRdbuO1.mjs";
+import { S as restartedAppNote, c as androidDevClientUrl, g as installConflictKind, s as androidAppProcess, t as ADB_INSTALL_TIMEOUT_MS } from "./app-install-0LgaQRT7.mjs";
+import { i as launchOutcomeRecord } from "./native-runtime-BRmWL7ru.mjs";
+import { a as PLATFORM, b as noDeviceDiagnostic, h as displayPath, n as LAUNCH_FAILED, r as NO_DEVICE, t as INSTALL_FAILED } from "./support-CnE_SIjt.mjs";
+import { c as lostRefusal, s as lostLine, t as DEBUG_VERIFY_STEP_MS } from "./device-lease-run-CvDeHTkG.mjs";
+import { a as reportAndroidResult, i as persistLastBuild, n as finishAndroidUpload } from "./result-BDoRk1k3.mjs";
+import { n as nativeRunCommand, r as siblingPlatformSlots, t as launchSlotScope } from "./slot-launch-B9hn96wd.mjs";
+import { n as verifyCollectorOwnership, r as readCollectors } from "./ownership-DXzMMSx6.mjs";
+import { a as printNativeCrashReport, r as captureNativeCrashes, t as errorDiagnostics } from "./error-diagnostics-Du7I_GuY.mjs";
+import { mkdirSync, openSync, statSync } from "node:fs";
+import { basename, join } from "node:path";
+import chalk from "chalk";
+//#region src/commands/android/collector.ts
+function collectorEntry() {
+	return spawnEntry("collector-run");
+}
+function collectorLogFile(root, slot = "default") {
+	return join(workspaceLogsDir(root), `collector-${deviceSlotFileKey(PLATFORM, slot)}.log`);
+}
+const COLLECTOR_EXIT_WAIT_MS = 2e3;
+const COLLECTOR_POLL_MS = 25;
+function killPreviousCollector(root, { platform = PLATFORM, slot = "default", kill = (pid, signal) => signalProcessTree(pid, signal), collectors = null, verify = verifyCollectorOwnership, isAlive = pidExists, note = (_line) => {} } = {}) {
+	const record = (collectors ?? readCollectors(root))?.[deviceSlotKey(platform, slot)];
+	const pid = Number(record?.pid);
+	if (!Number.isFinite(pid) || pid <= 0 || pid === process.pid) return null;
+	const ownership = verify({
+		pid,
+		platform: deviceSlotKey(platform, slot),
+		root,
+		isAlive,
+		expected: record
+	});
+	if (ownership.status === "gone") return null;
+	if (ownership.status === "unverified") {
+		note(chalk.dim(`Previous ${platform} log collector (pid ${pid}): ${ownership.reason}, so it was not signalled -- starting a replacement anyway`));
+		return null;
+	}
+	try {
+		kill(pid, "SIGTERM");
+		return pid;
+	} catch {
+		return null;
+	}
+}
+async function startCollector({ root, slot = "default", serial, packageName, spawn, kill, alive = pidExists, verify = verifyCollectorOwnership, waitMs = COLLECTOR_EXIT_WAIT_MS, sleep = (ms) => new Promise((r) => setTimeout(r, ms)), out }) {
+	const previousPid = killPreviousCollector(root, {
+		slot,
+		kill,
+		isAlive: alive,
+		verify,
+		note: (line) => out(phaseLine("logs", line))
+	});
+	if (previousPid) {
+		const deadline = Date.now() + waitMs;
+		while (Date.now() < deadline && alive(previousPid)) await sleep(COLLECTOR_POLL_MS);
+	}
+	let stdio = "ignore";
+	try {
+		mkdirSync(workspaceLogsDir(root), { recursive: true });
+		const fd = openSync(collectorLogFile(root, slot), "a");
+		stdio = [
+			"ignore",
+			fd,
+			fd
+		];
+	} catch {}
+	try {
+		const child = spawn(process.execPath, [
+			collectorEntry(),
+			"--platform",
+			PLATFORM,
+			"--root",
+			root,
+			...slot === "default" ? [] : ["--slot", slot],
+			"--serial",
+			serial,
+			"--package",
+			packageName
+		], {
+			cwd: androidToolCwd() ?? root,
+			detached: true,
+			stdio,
+			env: process.env
+		});
+		child?.unref?.();
+		return child?.pid ?? null;
+	} catch (err) {
+		out(phaseLine("logs", chalk.yellow(`could not start the device log collector: ${err?.message || err}`)));
+		return null;
+	}
+}
+//#endregion
+//#region src/commands/android/launch.ts
+function androidLaunchOutcomeRecord(kind, args) {
+	if (kind !== "process") return launchOutcomeRecord({
+		...args,
+		release: kind === "embedded-js"
+	});
+	const unverified = args.launchState === LAUNCH_UNVERIFIED;
+	return {
+		src: "build",
+		level: unverified ? "warn" : "info",
+		event: unverified ? "launch_unverified" : "launch_verified",
+		msg: unverified ? `${args.bundleId} could not be verified as running` : `${args.bundleId} is running its native process`
+	};
+}
+function androidProcessRuntime(prepare, kind = "process") {
+	return {
+		kind,
+		prepare,
+		scheme: () => void 0,
+		verificationWaitMs: RELEASE_VERIFY_WAIT_MS,
+		launch: async (_prepared, { serial, androidPackage, remoteDevice, launchRelease }) => remoteDevice ? remoteDevice.launch({
+			serial,
+			packageName: androidPackage,
+			metroPort: null
+		}) : launchRelease({
+			serial,
+			packageName: androidPackage
+		}),
+		verify: async (_prepared, context) => verifyAndroidProcessRun({
+			...context,
+			embeddedJavaScript: kind === "embedded-js"
+		})
+	};
+}
+function androidMetroRuntime(prepare) {
+	return {
+		kind: "metro",
+		prepare,
+		scheme: (root, apkPath, resolve) => resolve(root, apkPath),
+		verificationWaitMs: DEBUG_VERIFY_STEP_MS,
+		launch: async ({ metroPort }, { serial, androidPackage, scheme, physical, launch }) => launch({
+			serial,
+			packageName: androidPackage,
+			metroPort: metroPort ?? 8081,
+			devClientScheme: scheme,
+			physical
+		}),
+		verify: async ({ metroPort }, context) => verifyAndroidMetroRun({
+			...context,
+			metroPort
+		})
+	};
+}
+async function verifyAndroidProcessRun({ root, slot, remoteDevice, verifyReleaseLaunched, serial, androidPackage, variant, logsDir, launchedAt, phase, embeddedJavaScript }) {
+	const readNativeCrashes = () => remoteDevice ? [] : captureNativeCrashes({
+		root,
+		slot,
+		platform: "android",
+		deviceId: serial,
+		appId: androidPackage,
+		since: launchedAt
+	}, logsDir);
+	if (remoteDevice) {
+		phase("verify", chalk.yellow("UNVERIFIED: remote adapter launch accepted; process verification is unavailable"));
+		return { state: LAUNCH_UNVERIFIED };
+	}
+	const processCheck = await verifyReleaseLaunched({
+		serial,
+		packageName: androidPackage
+	});
+	const crashes = readNativeCrashes();
+	if (processCheck?.verified && !crashes.length) {
+		phase("verify", `process alive ${formatDuration(processCheck.waitedMs ?? 0)} after launch (${variant}: no bundle fetch to observe)`);
+		return { state: true };
+	}
+	if (processCheck?.reason === "probe-failed" && !crashes.length) {
+		phase("verify", chalk.yellow("UNVERIFIED: the app process check failed"));
+		return { state: LAUNCH_UNVERIFIED };
+	}
+	for (const line of launchErrorPreview(crashes, root)) phase("launch", chalk.red(line));
+	if (!crashes.length) phase("logs", "Process missing; no attributable native crash report captured. Read `stim logs --source device` for available output.");
+	phase("verify", chalk.yellow(crashes.length ? "FATAL: the app reported a native crash" : `FATAL: no ${androidPackage} process on ${serial} ${formatDuration(processCheck?.waitedMs ?? 0)} after launch`));
+	phase("", chalk.yellow(`${embeddedJavaScript ? "A release process" : "The app process"} exited before readiness. Run \`stim logs --errors\` for captured crash reports, or \`stim logs --source device\` for the full device output.`));
+	return { state: LAUNCH_FATAL };
+}
+async function verifyAndroidMetroRun({ root, slot, remoteDevice, verifyLaunched, serial, androidPackage, metroCheck, logsDir, launchedAt, metroPort, isExpo, physical, device, scheme, component = null, phase, enterActivity }) {
+	const runCommand = nativeRunCommand("android", slot, {
+		physical,
+		deviceId: serial
+	});
+	const readNativeCrashes = () => remoteDevice ? [] : captureNativeCrashes({
+		root,
+		slot,
+		platform: "android",
+		deviceId: serial,
+		appId: androidPackage,
+		since: launchedAt
+	}, logsDir);
+	const freshEmulator = Boolean((device.created || device.adoptionPending) && device.owned && !remoteDevice);
+	const timeoutMs = freshEmulator ? 6e4 : VERIFY_TIMEOUT_MS;
+	if (metroCheck && freshEmulator) phase("verify", `waiting up to 60s for bundle load (${device.created ? "new" : "adopted"} emulator)`);
+	const siblings = metroCheck ? siblingPlatformSlots(root, "android", slot) : [];
+	const verification = metroCheck ? await verifyLaunched({
+		timeoutMs,
+		requireBundleResponse: true,
+		slot: launchSlotScope(root, slot),
+		platformShared: siblings.length > 0,
+		onReadinessPending: () => phase("readiness", "waiting for app readiness (up to 30s after bundle load)"),
+		onActivity: enterActivity,
+		logsDir,
+		since: launchedAt,
+		metroPort,
+		platform: "android",
+		mode: workspaceDevServerMode(root, isExpo),
+		readNativeCrashes,
+		processAlive: () => {
+			const pid = androidAppProcess(serial, androidPackage);
+			return pid === void 0 ? null : pid !== null;
+		}
+	}) : {
+		verified: false,
+		skipped: true
+	};
+	const nativeCrashes = verification.errors?.some((record) => record.event === "native_crash") ? [] : readNativeCrashes();
+	if (nativeCrashes.length) verification.fatal = true;
+	verification.errors = await errorDiagnostics([...verification.errors ?? [], ...nativeCrashes], {
+		root,
+		logsDir,
+		port: metroPort,
+		allowRequest: true
+	});
+	if (verification.readiness) phase("readiness", appReadinessMessage(verification.readiness, verification.waitedMs ?? 0));
+	if (verification?.fatal) {
+		const nativeFatal = verification.errors?.some((record) => record.event === "native_crash");
+		const deliveryFailed = verification.record?.event === "bundle_response_failed";
+		const reason = nativeFatal ? "the app reported a native crash" : verification.processAlive === false ? "the app process exited" : deliveryFailed ? "Metro bundle delivery failed" : "Metro could not build the bundle";
+		phase("verify", chalk.red(`FATAL after ${formatDuration(verification.waitedMs ?? 0)}: ${reason}`));
+		for (const line of launchErrorPreview(verification.errors ?? [], root)) phase("", chalk.red(line));
+		if (verification.processAlive === false && !verification.errors?.some((record) => record.event === "native_crash")) phase("logs", "No attributable native crash report captured yet. Run `stim logs --errors` again for delayed reports, or `stim logs --source device` for available output.");
+		if (nativeFatal || verification.processAlive === false) phase("remedy", chalk.yellow(`Fix the crash, then run \`${runCommand}\` again; it force-stops a crashed process that remains alive behind the system crash dialog. Metro reload cannot recover it.`));
+		else if (verification.processAlive === true && metroPort !== null) {
+			const reloadRemedy = physical ? `run \`agent-device metro reload --metro-port ${metroPort}\`.` : "run `stim reload android`.";
+			phase("remedy", chalk.yellow(`The native app is still running. ${deliveryFailed ? "Check the Metro logs and device connection, then" : "Fix the JavaScript or TypeScript error, then"} ${reloadRemedy} Do not run \`${runCommand}\` unless native inputs changed or the app process exits.`));
+		}
+		return { state: LAUNCH_FATAL };
+	}
+	if (verification?.verified) {
+		phase("verify", `bundle loaded` + (verification.processAlive === true ? ", process alive" : "") + (verification.readiness ? "" : ", stable for 3s -- the first screen may still be rendering") + ` (${formatDuration(verification.waitedMs ?? 0)} total)`);
+		const report = launchErrorReport(verification.errors ?? [], root);
+		if (report.summary) phase("launch", chalk.dim(report.summary));
+		for (const line of report.lines) phase("launch", chalk.yellow(line));
+		if (report.lines.length > 0 && verification.processAlive === true && metroPort !== null) {
+			const reloadRemedy = physical ? `run \`agent-device metro reload --metro-port ${metroPort}\`.` : "run `stim reload android`.";
+			phase("remedy", chalk.yellow(`The native app is still running. Fix the JavaScript or TypeScript error; Fast Refresh should apply the edit. If the error screen remains, ${reloadRemedy} Do not run \`${runCommand}\` unless native inputs changed or the app process exits.`));
+		}
+		return {
+			state: true,
+			warning: report.lines.length > 0 ? "app errors detected; inspect the error above" : verification.readiness === "timed-out" || verification.readiness === "error" ? "app readiness not confirmed; inspect the UI and logs" : void 0
+		};
+	}
+	if (verification?.skipped) {
+		phase("verify", "skipped (--no-metro-check): the launch is reported as unverified");
+		return { state: LAUNCH_UNVERIFIED };
+	}
+	if (verification?.requested) {
+		phase("verify", `BUNDLING: the app asked port ${metroPort} for its bundle; build, delivery, or JavaScript loading was still pending after ${formatDuration(verification.waitedMs ?? 0)} (a cold bundle on a large graph outlasts this window)`);
+		phase("", chalk.dim("Nothing to do: `stim logs --source metro` shows the build finishing, usually within a minute."));
+		return { state: LAUNCH_BUNDLING };
+	}
+	if (verification?.unattributed) {
+		const [headline, ...lines] = unattributedLaunchLines({
+			platform: "android",
+			metroPort,
+			slot,
+			siblings
+		});
+		phase("verify", chalk.yellow(headline));
+		for (const line of lines) phase("", chalk.yellow(line));
+		return {
+			state: LAUNCH_UNVERIFIED,
+			unattributed: true
+		};
+	}
+	phase("verify", chalk.yellow("UNVERIFIED: no bundle request reached this workspace's Metro"));
+	for (const line of unverifiedLaunchLines({
+		platform: PLATFORM,
+		metroPort: metroPort ?? 8081,
+		waitedMs: verification?.waitedMs,
+		bundleId: androidPackage,
+		serial,
+		component,
+		devClientUrl: scheme ? androidDevClientUrl(scheme, metroPort ?? 8081, physical) : null,
+		devClient: Boolean(scheme),
+		mode: workspaceDevServerMode(root, isExpo)
+	})) phase("", chalk.yellow(line));
+	return { state: LAUNCH_UNVERIFIED };
+}
+const ADOPTED_INSTALL_HEADROOM_BYTES = 536870912;
+const INSUFFICIENT_STORAGE = /INSTALL_FAILED_INSUFFICIENT_STORAGE/;
+async function wipeAdoptedAvd(room, free) {
+	room.phase("device", chalk.yellow(`${room.avdName} has ${free === null ? "too little space" : `${formatBytes(free)} free`} on /data after removing other apps and trimming caches; wiping its user data`));
+	const expectedRecord = deviceSlotPlatforms(loadConfig()?.projects?.[room.root], room.slot)?.android;
+	if (!expectedRecord?.adoptionPending || expectedRecord.avdName !== room.avdName) throw new Error("the emulator assignment changed before the wipe; its data was kept");
+	const wiped = room.wipeDevice(room.avdName, {
+		wipe: true,
+		owner: {
+			projectPath: room.root,
+			slot: room.slot,
+			expectedRecord
+		},
+		workspace: room.root
+	});
+	if (wiped.status !== "torn-down") throw new Error(`could not wipe it: ${wiped.reason ?? wiped.status}`);
+	const rebooted = await room.rebootDevice();
+	if (!rebooted.ok || !rebooted.serial) throw new Error(`it did not boot after its user data was wiped: ${rebooted.reason ?? "no serial"}`);
+	if (room.resolveAvdSerial(room.avdName).serial !== rebooted.serial) throw new Error(`${rebooted.serial} is not running ${room.avdName} after the wipe`);
+	room.phase("device", `${room.avdName} (${rebooted.serial}) booted with wiped user data`);
+	return rebooted.serial;
+}
+async function installOnAdoptedAvd(room, serial, installApk) {
+	const neededBytes = 2 * statSync(room.apkPath).size + ADOPTED_INSTALL_HEADROOM_BYTES;
+	const roomy = (free) => free === null || free >= neededBytes;
+	const outOfSpace = (result) => Boolean(result.failed) && INSUFFICIENT_STORAGE.test(result.reason ?? "");
+	let target = serial;
+	let wiped = false;
+	if (!roomy(room.dataFreeBytes(target))) {
+		room.trimCaches(target, neededBytes);
+		const free = room.dataFreeBytes(target);
+		if (roomy(free)) room.phase("install", `trimmed app caches on ${room.avdName} to make room for the APK`);
+		else {
+			target = await wipeAdoptedAvd(room, free);
+			wiped = true;
+		}
+	}
+	let installed = installApk(target);
+	if (wiped || !outOfSpace(installed)) return {
+		serial: target,
+		installed
+	};
+	room.trimCaches(target, neededBytes);
+	installed = installApk(target);
+	if (!outOfSpace(installed)) return {
+		serial: target,
+		installed
+	};
+	target = await wipeAdoptedAvd(room, room.dataFreeBytes(target));
+	return {
+		serial: target,
+		installed: installApk(target)
+	};
+}
+async function resolveInstallSerial({ root, slot, device, physical, remoteDevice, serial, resolveAvdSerial, waitForDeviceBoot, phase }) {
+	if (physical || remoteDevice || !device.owned || !device.avdName) return serial;
+	const resolved = resolveAvdSerial(device.avdName, { timeoutMs: 5e3 });
+	if (!resolved.serial) throw new Error(`Could not verify a running owned AVD ${device.avdName} before installation.`);
+	if (resolved.serial !== serial) {
+		phase("device", `${device.avdName} changed serial (${serial} -> ${resolved.serial}); checking readiness before installation`);
+		const ready = await waitForDeviceBoot(resolved.serial, 6e4, { commandTimeoutMs: 5e3 });
+		if (!ready.ok) throw new Error(`Emulator ${resolved.serial} never reported boot completion. Diagnostic: ${JSON.stringify(ready.diagnostic)}`);
+		if (resolveAvdSerial(device.avdName, { timeoutMs: 5e3 }).serial !== resolved.serial) throw new Error(`Could not verify AVD ${device.avdName} still runs on ${resolved.serial} after checking readiness.`);
+		phase("device", `reopen agent-device on ${resolved.serial}`);
+	}
+	const consolePort = Number(resolved.serial.replace(/^emulator-/, ""));
+	withConfigLock(() => {
+		const current = deviceSlotPlatforms(loadConfig()?.projects?.[root], slot)?.android;
+		if (!current?.owned || current.avdName !== device.avdName) throw new Error("The owned emulator assignment changed before installation.");
+		if (current.consolePort !== consolePort) setDevice(root, PLATFORM, {
+			...current,
+			consolePort
+		}, slot);
+	});
+	return resolved.serial;
+}
+async function finishAndroidRun({ runtime, runtimePreparation, lease, releaseLease, root, slot, json, metroCheck, useBuildCache, variant, release, isExpo, metroPort, logsDir, emuLog, device, physical, remoteDevice, bootPromise, resolveAvdSerial, waitForDeviceBoot, bootDuration, bootPending, apkPath, androidPackage: initialPackage, androidPackageProblem, record, waitedForBuild, ccache, uploadPending, providerUpload, providerName, remote, abandonedRemote: remoteWasAbandoned, started, startedAt, writer, phase, fail, readApkPackage, readProjectPackage, packageRemedy, install, launch, launchRelease, resolveDevClientScheme, verifyLaunched, verifyReleaseLaunched, spawn, kill, pidAlive, verifyCollector, writeLaunch, recordBuild, now, out, emit, recordRun, reclaimed, devServer, enterPhase, enterActivity, rebootDevice, dataFreeBytes = androidDataFreeBytes, trimCaches = trimAndroidCaches, wipeDevice = teardownOwnedAvd }) {
+	let androidPackage = initialPackage;
+	let leaseWarned = false;
+	const raiseLeaseFor = (boundMs, beforeInstall) => {
+		const step = lease?.raise(boundMs);
+		if (!step || step.ok) return null;
+		if (beforeInstall) {
+			const refusal = lostRefusal(step.holder, step.expiresAt, now());
+			return fail(refusal.code, refusal.message, refusal.remedy, { lease: refusal.lease });
+		}
+		if (!leaseWarned) {
+			leaseWarned = true;
+			phase("lease", chalk.yellow(lostLine(step.holder, step.expiresAt, now())));
+		}
+		return null;
+	};
+	enterPhase("device");
+	if (bootPending()) enterActivity("booting");
+	const booted = await bootPromise;
+	enterActivity(null);
+	const runCommand = nativeRunCommand("android", slot, {
+		physical,
+		deviceId: booted.serial
+	});
+	if (booted.failed) {
+		const diag = diagnoseBootFailure(booted, emuLog, runCommand, physical);
+		return fail(diag.code, diag.message, diag.remedy, {
+			lines: diag.lines,
+			logPath: diag.logPath ? displayPath(root, diag.logPath) : null
+		});
+	}
+	let serial;
+	try {
+		serial = await resolveInstallSerial({
+			root,
+			slot,
+			device,
+			physical,
+			remoteDevice,
+			serial: booted.serial,
+			resolveAvdSerial,
+			waitForDeviceBoot,
+			phase
+		});
+	} catch (error) {
+		return fail(NO_DEVICE, error instanceof Error ? error.message : String(error), `Run \`stim status\` to inspect the owned AVD, then retry \`${runCommand}\`; the APK was not installed.`);
+	}
+	phase("device", physical ? `${device.deviceName || serial} (${serial}) connected, not owned by Stim` : `${device.avdName || serial} (${serial}) ${device.adopted || device.adoptionPending ? "adopted" : "booted"} ${bootDuration()}`);
+	const packageFromApk = readApkPackage(apkPath);
+	if (packageFromApk && androidPackage && packageFromApk !== androidPackage) phase("install", chalk.dim(`applicationId ${packageFromApk} (from the APK; project files say ${androidPackage})`));
+	androidPackage = packageFromApk || androidPackage || readProjectPackage();
+	if (!androidPackage && androidPackageProblem) return fail(LAUNCH_FAILED, androidPackageProblem, packageRemedy, { lastBuildStatus: true });
+	const adopting = !physical && !remoteDevice && Boolean(device.adoptionPending);
+	if (adopting) {
+		if (!androidPackage || !device.avdName) return fail(LAUNCH_FAILED, "Cannot clean an adopted emulator without its app package and AVD name.", "Retry once the APK applicationId can be read.");
+		try {
+			await resetAdoptedAvd(device.avdName, serial, androidPackage);
+		} catch (error) {
+			return fail(LAUNCH_FAILED, `Could not clean adopted emulator ${device.avdName}: ${String(error?.message || error)}`, "Fix the device cleanup error and retry; adoption remains pending and the app was not launched.");
+		}
+	}
+	const lostBeforeInstall = physical ? raiseLeaseFor(ADB_INSTALL_TIMEOUT_MS, true) : null;
+	if (lostBeforeInstall) return lostBeforeInstall;
+	enterPhase("install");
+	let installTimer = stepTimer(now);
+	const installApk = (target) => {
+		installTimer = stepTimer(now);
+		return install({
+			serial: target,
+			apkPath,
+			packageName: androidPackage,
+			allowUninstall: release || adopting
+		});
+	};
+	let installed;
+	if (adopting && device.avdName && apkPath) {
+		const room = {
+			root,
+			slot,
+			avdName: device.avdName,
+			apkPath,
+			phase,
+			rebootDevice,
+			dataFreeBytes,
+			trimCaches,
+			wipeDevice,
+			resolveAvdSerial
+		};
+		try {
+			({serial, installed} = await installOnAdoptedAvd(room, serial, installApk));
+		} catch (error) {
+			return fail(INSTALL_FAILED, `Could not make room on adopted emulator ${device.avdName}: ${String(error?.message || error)}`, `Run \`${runCommand}\` again; adoption remains pending, so it retries the cleanup.`);
+		}
+	} else installed = installApk(serial);
+	if (installed.failed) {
+		const installRemedy = remoteDevice?.failureRemedy() ?? localInstallRemedy({
+			reason: installed.reason,
+			packageName: androidPackage,
+			serial,
+			useBuildCache
+		});
+		return fail(installed.code || "STIM_INSTALL_FAILED", installed.reason, installRemedy, { lastBuildStatus: true });
+	}
+	if (adopting) try {
+		withConfigLock(() => {
+			const config = loadConfig();
+			const current = deviceSlotPlatforms(config?.projects?.[root], slot)?.android;
+			if (!config || !current || current.avdName !== device.avdName) throw new Error("The adopted emulator assignment changed during installation.");
+			delete current.adoptionPending;
+			saveConfig(config);
+		});
+	} catch (error) {
+		return fail(LAUNCH_FAILED, `Could not finish adopting emulator ${device.avdName}: ${String(error?.message || error)}`, "Retry to reconcile the emulator assignment; the app was not launched.");
+	}
+	const installSkipped = Boolean(installed.skipped);
+	phase("install", installSkipped ? `unchanged (${serial} already has this build) ${installTimer()}` : `${basename(apkPath)} -> ${serial} ${installTimer()}`);
+	if (installed.note) {
+		phase("install", chalk.yellow(installed.note));
+		writer.write({
+			src: "build",
+			level: "warn",
+			event: "install_uninstalled_first",
+			msg: installed.note
+		});
+	}
+	if (androidPackage) upsertProject(root, { androidPackage });
+	record.bundleId = androidPackage;
+	if (!androidPackage) return fail(LAUNCH_FAILED, "Could not determine this app's Android package name, so there is nothing to launch.", packageRemedy, { lastBuildStatus: true });
+	if (physical) raiseLeaseFor(0, false);
+	const scheme = runtime.scheme(root, apkPath, resolveDevClientScheme);
+	enterPhase("launch");
+	const launchTimer = stepTimer(now);
+	const launchedAt = now();
+	writer.write({
+		src: "build",
+		level: "info",
+		marker: true,
+		event: "launch_attempt",
+		ts: launchedAt,
+		platform: "android",
+		appId: androidPackage,
+		deviceId: serial,
+		remote: Boolean(remoteDevice),
+		physical,
+		msg: `launching ${androidPackage} on ${serial}`
+	});
+	const launched = await runtime.launch(runtimePreparation, {
+		serial,
+		androidPackage,
+		scheme,
+		physical,
+		remoteDevice,
+		launch,
+		launchRelease
+	});
+	if (launched.failed) {
+		printNativeCrashReport({
+			root,
+			slot,
+			platform: "android",
+			deviceId: serial,
+			appId: androidPackage,
+			since: launchedAt
+		}, logsDir, (line) => phase("launch", chalk.red(line)), Boolean(remoteDevice));
+		return fail(launched.code || "STIM_LAUNCH_FAILED", launched.reason, launchRemedy(remoteDevice, serial, androidPackage), { lastBuildStatus: true });
+	}
+	writer.write({
+		src: "build",
+		level: "info",
+		event: "app_launched",
+		msg: (runtime.kind === "process" ? `launched ${androidPackage} on ${serial} (${variant ?? "debug"}, native process, no Metro)` : runtime.kind === "embedded-js" ? `launched ${androidPackage} on ${serial} (${variant}, embedded JS bundle, no Metro)` : `launched ${androidPackage} on ${serial} against Metro port ${metroPort}`) + restartedAppNote(launched.restartedPid, "; ")
+	});
+	phase("launch", `${androidPackage}${restartedAppNote(launched.restartedPid)} ${launchTimer()}`);
+	if (!physical && !remoteDevice) try {
+		writeLaunch(root, "android", {
+			appId: androidPackage,
+			deviceId: serial,
+			metroPort,
+			release,
+			...runtime.kind === "process" ? { runtime: "process" } : {},
+			launchedAt: new Date(launchedAt).toISOString()
+		});
+	} catch (error) {
+		out(phaseLine("state", chalk.yellow(`could not record Android launch: ${error?.message || error}`)));
+	}
+	if (runtime.kind === "metro") reportMetroRoute({
+		launched,
+		remote: Boolean(remoteDevice),
+		metroPort,
+		androidPackage,
+		serial,
+		phase,
+		writer
+	});
+	if (launched.devClientNote) {
+		phase("metro", chalk.yellow(launched.devClientNote));
+		writer.write({
+			src: "build",
+			level: "warn",
+			event: "dev_client_link_failed",
+			msg: launched.devClientNote
+		});
+	}
+	const uploadWasAbandoned = await finishAndroidUpload(uploadPending, remote, phase);
+	const providerOutcome = providerUploadOutcome(providerUpload ? await providerUpload : null, providerName);
+	if (providerOutcome) phase("cache", providerOutcome.warn ? chalk.yellow(providerOutcome.line) : providerOutcome.line);
+	persistLastBuild({
+		recordBuild,
+		root,
+		record,
+		startedAt,
+		durationMs: now() - started,
+		status: "ok",
+		out
+	});
+	const remoteRelease = Boolean(remoteDevice && release);
+	if (remoteDevice) {
+		killPreviousCollector(root, {
+			slot,
+			kill,
+			isAlive: pidAlive,
+			verify: verifyCollector,
+			note: (line) => out(phaseLine("logs", line))
+		});
+		writer.write({
+			src: "build",
+			level: "info",
+			event: "collector_skipped",
+			msg: `remote session ${serial}: device logs come from agent-device/EAS, so no adb logcat collector is attached`
+		});
+	} else {
+		if (physical) raiseLeaseFor(0, false);
+		const collectorPid = await startCollector({
+			root,
+			slot,
+			serial,
+			packageName: androidPackage,
+			spawn,
+			kill,
+			alive: pidAlive,
+			verify: verifyCollector,
+			out
+		});
+		phase("logs", `${displayPath(root, logsDir)}${collectorPid ? ` (collector pid ${collectorPid})` : ""}`);
+	}
+	if (physical) raiseLeaseFor(runtime.verificationWaitMs, false);
+	const { state: launchState, warning: launchWarning, unattributed } = await runtime.verify(runtimePreparation, {
+		root,
+		slot,
+		remoteDevice: Boolean(remoteDevice),
+		verifyReleaseLaunched,
+		verifyLaunched,
+		serial,
+		androidPackage,
+		variant,
+		metroCheck,
+		logsDir,
+		launchedAt,
+		metroPort,
+		isExpo,
+		physical,
+		device,
+		scheme,
+		component: launched.component ?? null,
+		phase,
+		enterActivity
+	});
+	if (launchState === "fatal") return fail(LAUNCH_FAILED, "The app failed its launch readiness check.", `Read the launch error above or run \`stim logs --errors\`. The full timeline is in ${logsDir}.`, {
+		lastBuildStatus: true,
+		logPath: displayPath(root, logsDir)
+	});
+	writer.write(androidLaunchOutcomeRecord(runtime.kind, {
+		launchState,
+		bundleId: androidPackage,
+		configuration: variant,
+		metroPort,
+		unattributed
+	}));
+	const leaseFacts = lease?.facts() ?? null;
+	releaseLease();
+	const facts = reportAndroidResult({
+		root,
+		slot,
+		json,
+		useBuildCache,
+		variant,
+		release,
+		runtimeKind: runtime.kind,
+		metroCheck,
+		metroPort,
+		logsDir: remoteRelease ? null : logsDir,
+		serial,
+		apkPath,
+		androidPackage,
+		installSkipped,
+		record,
+		waitedForBuild,
+		remote,
+		providerName,
+		launchState,
+		launchWarning,
+		launched,
+		ccache,
+		durationMs: now() - started,
+		writer,
+		emit,
+		lease: physical ? leaseFacts : void 0,
+		recordRun,
+		reclaimed,
+		devServer,
+		links: workspaceLinks(root, {
+			platform: "android",
+			slot
+		})
+	});
+	if (remoteWasAbandoned || uploadWasAbandoned) exitAfterFlush(0);
+	return {
+		ok: true,
+		facts
+	};
+}
+function localInstallRemedy({ reason, packageName, serial, useBuildCache }) {
+	const conflict = installConflictKind(reason);
+	if (!conflict) return `Check that ${serial} is still connected (\`adb devices\`) and has room for the APK.`;
+	const rerun = useBuildCache ? " Then run this command again; it installs the APK from cache without building it again." : " Then run this command again.";
+	return `${packageName} is already installed on ${serial} ` + (conflict === "signature" ? "with a different signer" : "at a higher versionCode") + `. Uninstall it first (\`adb -s ${serial} uninstall ${packageName}\`); its data goes with it.` + rerun;
+}
+function launchRemedy(remoteDevice, serial, packageName) {
+	return remoteDevice?.failureRemedy() ?? `Check the app installed correctly (\`adb -s ${serial} shell pm list packages ${packageName}\`).`;
+}
+function reportMetroRoute({ launched, remote, metroPort, androidPackage, serial, phase, writer }) {
+	if (remote) {
+		phase("metro", `public origin ${launched.jsLocation}`);
+		return;
+	}
+	const reversedSummary = (launched.reversed ?? []).join(", ") || `tcp:${metroPort}->tcp:${metroPort}`;
+	if (launched.debugHttpHost) {
+		phase("metro", `debug_http_host ${launched.debugHttpHost} + adb reverse ${reversedSummary}`);
+		return;
+	}
+	phase("metro", chalk.yellow(`adb reverse ${reversedSummary}; ${launched.debugHttpHostNote || "debug_http_host not written"}`));
+	writer.write({
+		src: "build",
+		level: "warn",
+		event: "debug_http_host_failed",
+		msg: `debug_http_host was not written for ${androidPackage} on ${serial}: ${launched.debugHttpHostNote || "unknown reason"}`
+	});
+}
+function diagnoseBootFailure(booted, logFile, runCommand, physical) {
+	if (booted.code) return {
+		code: booted.code,
+		message: booted.reason ?? "The emulator did not boot.",
+		remedy: booted.remedy ?? null,
+		lines: [],
+		logPath: null
+	};
+	const diag = noDeviceDiagnostic({
+		reason: booted.reason ?? "The emulator did not boot.",
+		logFile,
+		remedy: booted.remedy ?? `Run \`stim status\` to see what Stim thinks it owns; re-running \`${runCommand}\` creates a fresh owned AVD.`,
+		localEmulator: !physical
+	});
+	return {
+		code: NO_DEVICE,
+		...diag
+	};
+}
+//#endregion
+export { killPreviousCollector as a, collectorLogFile as i, androidProcessRuntime as n, startCollector as o, finishAndroidRun as r, androidMetroRuntime as t };