stim 1.3.0 → 1.4.0

package/README.md

@@ -44,8 +44,9 @@ stim stop
 
 For `stim logs --errors`, a clean check requires exit code 0 and no matching
 errors in the captured logs. Exit code 0 alone means the query succeeded, even
-when it prints errors; an empty result does not prove launch or log capture
-succeeded.
+when it prints errors. A workspace that has never produced a log timeline
+refuses with `STIM_NO_PROJECT`; in a monorepo, the error names the nearest
+registered descendant app with logs when one exists.
 
 Use `stim start --reset-cache` to recover from stale Metro transforms or file-map
 state. It restarts only this app's verified owned Metro, keeping its port and
@@ -128,7 +129,7 @@ eligible `.env` and local configuration files. Existing entries are preserved;
 existing ignored directories such as `node_modules` are skipped whole.
 
 `stim worktree warm --refresh` brings the source checkout up to date first: it
-fetches, fast-forwards whatever branch is checked out there, and installs what
+checks the upstream, fetches changes when needed, fast-forwards whatever branch is checked out there, and installs what
 the new commits moved before copying. It refuses a source checkout it cannot
 move (uncommitted tracked changes, a rebase or merge in progress, a detached
 HEAD, a diverged branch) and never switches branches. One lock per repository
@@ -197,3 +198,16 @@ stim stop --slot tablet
 `--slot` preserves the shared server and other devices. `stim reload ios` or
 `stim reload android` can reload multiple connected devices. Read
 `stim guide lifecycle options` for launch verification and recycling behavior.
+
+### Named server ports
+
+Use `stim ports get web` to reserve a workspace port for a server Stim does not
+manage, then pass that number to the server, for example
+`pnpm exec vite --port "$(stim ports get web)" --strictPort`.
+`stim ports` lists named allocations and managed Metro. `stim ports stop web`
+stops the TCP listener and releases its port; `--dry-run` previews the action.
+`stim ports release web` releases without stopping. Omitting the label selects
+all named ports. These commands leave Metro alone, and `stim stop` leaves
+named ports alone. Worktree removal and `gc --delete` stop and release named
+ports for removed workspaces. Read `stim guide ports` for the reserved band,
+listener ownership, and allocation limits.

package/dist/{android-CqcW1hrP.mjs → android-BTR1KTMP.mjs}

@@ -1,30 +1,31 @@
 import { t as getExecutor } from "./exec-CyylIdq9.mjs";
-import { C as withConfigLock, I as deviceSlotKey, L as deviceSlotPlatforms, S as upsertProject, V as validateDeviceSlot, b as setDevice, f as getProject, g as loadConfig, l as getConcurrencyLimits, y as saveConfig } from "./config-CcefMY2Q.mjs";
+import { C as withConfigLock, E as ownership_claim_exports, F as deviceSlotPlatforms, P as deviceSlotKey, S as upsertProject, b as setDevice, f as getProject, g as loadConfig, l as getConcurrencyLimits, y as saveConfig, z as validateDeviceSlot } from "./config-6vdGngKa.mjs";
 import { r as createNdjsonWriter } from "./ndjson-BZwI1NBv.mjs";
-import { D as workspaceLogsDir, T as workspaceDir, _ as writeWorkspaceState, g as writeWorkspaceLaunch, n as MODE_EXPO, p as readWorkspaceState, t as MODE_BARE, v as emulatorLogFile } from "./state-B3XA2wp2.mjs";
-import { C as removeTemporaryEntry, S as makeTemporaryDirectory, g as repoRoot, s as gitCommonDir } from "./worktree-Eq6TLH8N.mjs";
-import { a as findProjectRoot, c as projectShortcut, i as detectIsExpo, n as detectAndroidPackage, r as detectBundleId, t as appProjectProblem } from "./project-fKmuIaMI.mjs";
+import { _ as workspaceLogsDir, h as workspaceDir, o as writeWorkspaceState, r as readWorkspaceState, s as emulatorLogFile } from "./workspace-state-Do1e2mOH.mjs";
+import { C as makeTemporaryDirectory, _ as repoRoot, s as gitCommonDir, w as removeTemporaryEntry } from "./worktree-DWNx4tUg.mjs";
+import { a as findProjectRoot, c as projectShortcut, i as detectIsExpo, n as detectAndroidPackage, r as detectBundleId, t as appProjectProblem } from "./project-CBFCwnN5.mjs";
+import { n as MODE_EXPO, p as writeWorkspaceLaunch, t as MODE_BARE } from "./state-CDbvmZdt.mjs";
 import { r as waitForChild, t as createLineReader } from "./process-output-C7IlIzd7.mjs";
-import { i as resolveProjectMetro, r as pidExists } from "./metro-CORqXyTL.mjs";
-import { n as verifyCollectorOwnership, r as readCollectors } from "./ownership-8O073GIC.mjs";
-import { _ as launchErrorPreview, c as launchErrorReport, g as stepTimer, h as stepClock, i as formatDuration, l as phaseLine, n as appReadinessMessage, p as shortHash } from "./command-output-8wHMEde0.mjs";
-import { r as claimFailure } from "./ownership-claim-Bf2CAfw3.mjs";
-import { $ as providerDownloadPath, C as memoizeEmulatorProbe, G as buildCacheKey, J as filesystemBuildCapability, K as describeFingerprintMiss, L as waitForBoot, M as resetAdoptedAvd, N as resolveOwnedAvdSerial, P as resolvePhysicalDevice, Q as prepareProviderDownloadDir, R as WAIT_CEILING_MS, U as takeoverLine, V as releaseBuildLock, W as waitForBuild, X as fingerprintDiffSuffix, Y as fingerprintDiffRecord, Z as fingerprintProject, _ as findBuildTool, a as androidSystemImageAbi, at as untrackedMissLine, ct as captureAssetManifest, et as providerUploadOutcome, g as extractEmulatorFailure, h as emulatorFailureRemedy, i as androidPoolNoCandidatesRefusal, it as storedAssetManifest, j as probeEmulatorSerial, k as physicalDeviceModel, lt as compareAssetManifests, m as emulatorDiskSpaceRemedy, n as androidHome, nt as resolveBuild, ot as untrackedNativeFiles, r as androidPoolCandidates, rt as storeBuild, st as assetDiffReason, t as androidDeviceAbi, tt as refingerprintAfterMutation, ut as readAssetManifest, x as listInstalledSystemImages, y as listAdbDevices, z as acquireBuildLock } from "./android-BqVIJoG7.mjs";
-import { A as resolveSettings, B as artifactCachePolicy, D as remoteDeviceSettingError, E as remoteAndroidSetting, F as tunnelModeSetting, H as optimizationBuildProfile, I as unknownSettingKeys, N as settingShapeErrors, R as detectProviders, T as publicUrlSetting, U as resolveOptimizations, V as compilerCacheFallbackMessage, a as SETTING_SHAPE_REMEDY, d as cacheProviderSettingError, j as settingFile, k as resolveCacheProviderConfig, r as REMOTE_DEVICE_BACKENDS, s as androidAvdConfigSettingError, u as androidDataPartitionSizeGbSettingError, x as metroWarmupUrlSetting } from "./settings-DEJf6_kJ.mjs";
-import { t as cleanLine } from "./server-expo-DizT4OMk.mjs";
-import { C as uploadRemote, S as resolveRemote, _ as isEasAuthFailureText, c as parkedMaxSetting, d as RESOLVE_TIMEOUT_MS, f as UPLOAD_TIMEOUT_MS, g as exitAfterFlush, h as easAuthNote, m as checkEasAuth, p as cacheLevel, v as loadProjectProvider, x as resolveEasCliBin } from "./teardown-ClFp1Aax.mjs";
-import { c as ensureWorkspaceStorageSafely, d as launchOutcomeRecord, f as noMetroMessage, g as warmMetro, i as detectEntryFile, m as resolveMetroWithRetry, n as pickDevClientScheme, o as needsPrebuild, p as noMetroRemedy, s as runPrebuild, t as devClientScheme, u as isPhysicalDeviceRequest, v as isEasBuildFailure, y as resolveEasDevelopmentBuild } from "./dev-client-BjisHDB5.mjs";
-import { t as withWorkspaceProcessLock } from "./workspace-process-lock-3NcQnZ0X.mjs";
-import { D as verifyAndroidReleaseLaunch, E as unverifiedLaunchLines, O as verifyLaunch, S as launchAndroidReleaseApp, _ as installConflictKind, c as RELEASE_VERIFY_WAIT_MS, d as androidDevClientUrl, g as installAndroidApp, h as deviceShellArg, i as LAUNCH_BUNDLING, l as VERIFY_TIMEOUT_MS, n as DEFAULT_METRO_PORT, o as LAUNCH_FATAL, s as LAUNCH_UNVERIFIED, t as ADB_INSTALL_TIMEOUT_MS, u as androidAppProcess, x as launchAndroidApp } from "./app-install-DIp9riNx.mjs";
-import { a as lostLine, c as releaseLeaseOnSignal, i as leaseExpiryText, l as runLease, n as DEBUG_VERIFY_STEP_MS, o as lostRefusal, r as acquireRunLease, s as parseDeviceWait, t as selectFromPool, u as waitFlagConflict } from "./device-pool-CPbLGfrB.mjs";
-import { r as releaseBuildSlot, t as acquireBuildSlot } from "./build-slots-C3-R4XQr.mjs";
-import { a as statsProjectKey, i as recordRunStats, n as readRunEstimates, t as createRunRecorder } from "./stats-BR-kwj0B.mjs";
-import { C as unknownAndroidSystemImageRefusal, _ as AvdRecoveryError, b as ensureBooted, f as startBuildHeartbeat, p as tailLines, r as HEARTBEAT_INTERVAL_MS, v as checkDeviceCapacity, x as ensureOwnedDevice } from "./xcode-D7sAp-Zy.mjs";
-import { a as ensureMetroReachable, b as ownedSessionName, l as resolveRemoteContext, n as binOnPath, o as ensureRemoteBootOwned, s as remoteAndroidDeps } from "./device-remote-AkYCKS8U.mjs";
-import { a as buildAndroid, c as CCACHE_NOT_RUN, f as resolveCcache, l as CCACHE_UNAVAILABLE, n as resolveAndroidCas, o as productFlavorRefusal, p as formatDiagnostic, r as resolveAndroidCompilerCache, s as readProductFlavors, u as ccacheActivityLine } from "./android-cas-BR5YJBYv.mjs";
-import { n as nativeRunCommand, t as launchSlotScope } from "./slot-launch-cci0xvmC.mjs";
+import { i as resolveProjectMetro, r as pidExists } from "./metro-DFLmaVz8.mjs";
+import { n as verifyCollectorOwnership, r as readCollectors } from "./ownership-BvSpZVBk.mjs";
+import { _ as launchErrorPreview, c as launchErrorReport, g as stepTimer, h as stepClock, i as formatDuration, l as phaseLine, n as appReadinessMessage, p as shortHash } from "./command-output-BuIb_ZOI.mjs";
+import { $ as providerDownloadPath, C as memoizeEmulatorProbe, G as buildCacheKey, J as filesystemBuildCapability, K as describeFingerprintMiss, L as waitForBoot, M as resetAdoptedAvd, N as resolveOwnedAvdSerial, P as resolvePhysicalDevice, Q as prepareProviderDownloadDir, R as WAIT_CEILING_MS, U as takeoverLine, V as releaseBuildLock, W as waitForBuild, X as fingerprintDiffSuffix, Y as fingerprintDiffRecord, Z as fingerprintProject, _ as findBuildTool, a as androidSystemImageAbi, at as untrackedMissLine, ct as captureAssetManifest, et as providerUploadOutcome, g as extractEmulatorFailure, h as emulatorFailureRemedy, i as androidPoolNoCandidatesRefusal, it as storedAssetManifest, j as probeEmulatorSerial, k as physicalDeviceModel, lt as compareAssetManifests, m as emulatorDiskSpaceRemedy, n as androidHome, nt as resolveBuild, ot as untrackedNativeFiles, r as androidPoolCandidates, rt as storeBuild, st as assetDiffReason, t as androidDeviceAbi, tt as refingerprintAfterMutation, ut as readAssetManifest, x as listInstalledSystemImages, y as listAdbDevices, z as acquireBuildLock } from "./android-BkM4qTaN.mjs";
+import { A as resolveSettings, B as artifactCachePolicy, D as remoteDeviceSettingError, E as remoteAndroidSetting, F as tunnelModeSetting, H as optimizationBuildProfile, I as unknownSettingKeys, N as settingShapeErrors, R as detectProviders, T as publicUrlSetting, U as resolveOptimizations, V as compilerCacheFallbackMessage, a as SETTING_SHAPE_REMEDY, d as cacheProviderSettingError, j as settingFile, k as resolveCacheProviderConfig, r as REMOTE_DEVICE_BACKENDS, s as androidAvdConfigSettingError, u as androidDataPartitionSizeGbSettingError, x as metroWarmupUrlSetting } from "./settings-DwfltIXQ.mjs";
+import { t as cleanLine } from "./server-expo-D4P7iTvf.mjs";
+import { C as resolveRemote, S as resolveEasCliBin, _ as exitAfterFlush, f as RESOLVE_TIMEOUT_MS, g as easAuthNote, h as checkEasAuth, l as parkedMaxSetting, m as cacheLevel, p as UPLOAD_TIMEOUT_MS, v as isEasAuthFailureText, w as uploadRemote, y as loadProjectProvider } from "./teardown-KsPpvldq.mjs";
+import { c as ensureWorkspaceStorageSafely, d as launchOutcomeRecord, f as noMetroMessage, g as warmMetro, i as detectEntryFile, m as resolveMetroWithRetry, n as pickDevClientScheme, o as needsPrebuild, p as noMetroRemedy, s as runPrebuild, t as devClientScheme, u as isPhysicalDeviceRequest, v as isEasBuildFailure, y as resolveEasDevelopmentBuild } from "./dev-client-Cd0v7iZk.mjs";
+import { t as withWorkspaceProcessLock } from "./workspace-process-lock-UEIrvZMJ.mjs";
+import { D as verifyAndroidReleaseLaunch, E as unverifiedLaunchLines, O as verifyLaunch, S as launchAndroidReleaseApp, _ as installConflictKind, c as RELEASE_VERIFY_WAIT_MS, d as androidDevClientUrl, g as installAndroidApp, h as deviceShellArg, i as LAUNCH_BUNDLING, l as VERIFY_TIMEOUT_MS, n as DEFAULT_METRO_PORT, o as LAUNCH_FATAL, s as LAUNCH_UNVERIFIED, t as ADB_INSTALL_TIMEOUT_MS, u as androidAppProcess, x as launchAndroidApp } from "./app-install--PAocWvq.mjs";
+import { a as lostLine, c as releaseLeaseOnSignal, i as leaseExpiryText, l as runLease, n as DEBUG_VERIFY_STEP_MS, o as lostRefusal, r as acquireRunLease, s as parseDeviceWait, t as selectFromPool, u as waitFlagConflict } from "./device-pool-DJvbIBGW.mjs";
+import { r as releaseBuildSlot, t as acquireBuildSlot } from "./build-slots-D6sDzOe-.mjs";
+import { a as statsProjectKey, i as recordRunStats, n as readRunEstimates, t as createRunRecorder } from "./stats-C59QLKm2.mjs";
+import { i as ensureOwnedDevice, l as AvdBootError, o as unknownAndroidSystemImageRefusal, r as ensureBooted, t as checkDeviceCapacity, u as AvdRecoveryError } from "./device-CMDFzx7C.mjs";
+import { a as ensureMetroReachable, b as ownedSessionName, l as resolveRemoteContext, n as binOnPath, o as ensureRemoteBootOwned, s as remoteAndroidDeps } from "./device-remote-CMfHhoc8.mjs";
+import { a as buildAndroid, c as CCACHE_NOT_RUN, f as resolveCcache, l as CCACHE_UNAVAILABLE, n as resolveAndroidCas, o as productFlavorRefusal, p as formatDiagnostic, r as resolveAndroidCompilerCache, s as readProductFlavors, u as ccacheActivityLine } from "./android-cas-BjLRZyks.mjs";
+import { d as startBuildHeartbeat, f as tailLines, n as HEARTBEAT_INTERVAL_MS } from "./xcode-D9tVItl-.mjs";
+import { n as nativeRunCommand, t as launchSlotScope } from "./slot-launch-DeKen9e5.mjs";
 import { t as spawnEntry } from "./spawn-entry-nCE6m770.mjs";
-import { a as printNativeCrashReport, r as captureNativeCrashes, t as errorDiagnostics } from "./error-diagnostics-DHC31rXA.mjs";
+import { a as printNativeCrashReport, r as captureNativeCrashes, t as errorDiagnostics } from "./error-diagnostics-_VmkqRZo.mjs";
 import { existsSync, mkdirSync, openSync, readFileSync, readdirSync, rmSync } from "node:fs";
 import { InvalidArgumentError } from "commander";
 import { basename, dirname, join, relative } from "node:path";
@@ -1012,12 +1013,7 @@ async function finishAndroidRun({ lease, releaseLease, root, slot, json, metroCh
 		deviceId: booted.serial
 	});
 	if (booted.failed) {
-		const diag = noDeviceDiagnostic({
-			reason: booted.reason ?? "The emulator did not boot.",
-			logFile: emuLog,
-			remedy: `Run \`stim status\` to see what Stim thinks it owns; re-running \`${runCommand}\` creates a fresh owned AVD.`,
-			localEmulator: !physical
-		});
+		const diag = diagnoseBootFailure(booted, emuLog, runCommand, physical);
 		return fail(NO_DEVICE, diag.message, diag.remedy, {
 			lines: diag.lines,
 			logPath: diag.logPath ? displayPath(root, diag.logPath) : null
@@ -1275,9 +1271,25 @@ async function finishAndroidRun({ lease, releaseLease, root, slot, json, metroCh
 		facts
 	};
 }
+function diagnoseBootFailure(booted, logFile, runCommand, physical) {
+	return 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
+	});
+}
 //#endregion
-//#region src/commands/android.ts
-const FALLBACK_LINES = 5;
+//#region src/commands/android/plan.ts
+function fail(code, message, remedy, { lines = [] } = {}) {
+	return {
+		ok: false,
+		code,
+		message,
+		remedy,
+		lines
+	};
+}
 function androidCompilerCache({ root, optimizations, settingsContext }) {
 	const { cas, optimizations: resolved } = resolveAndroidCompilerCache({
 		optimizations,
@@ -1302,6 +1314,104 @@ function androidCompilerCache({ root, optimizations, settingsContext }) {
 		})}`
 	};
 }
+function resolveAndroidRunPlan({ settings, settingsContext, slot, easProfile, variant: variantFlag, systemImage: systemImageFlag, device: deviceFlag, wait: waitFlag, waitConflict, remote: commandRemoteBackend, buildCache: requestedBuildCache }, { warn, resolveCompilerCache = androidCompilerCache, resolveCacheProvider = resolveCacheProviderConfig, validateAvdConfig = androidAvdConfigSettingError, readFlavors = readProductFlavors, detectExpo = detectIsExpo, listSystemImages = listInstalledSystemImages, parkedLimit = parkedMaxSetting }) {
+	const root = settingsContext.projectPath;
+	const [shapeError, ...moreShapeErrors] = [parkedLimit("android").error, ...settingShapeErrors(settings)].filter((error) => Boolean(error));
+	if (shapeError) return fail("STIM_BAD_ARG", shapeError, SETTING_SHAPE_REMEDY, { lines: moreShapeErrors });
+	for (const key of unknownSettingKeys(settings)) warn("setting", `Warning: setting "${key}" is not read by Stim and will be ignored.`);
+	let optimizations;
+	try {
+		optimizations = resolveOptimizations(settings);
+	} catch (error) {
+		return fail("STIM_BAD_ARG", `Could not configure Android build: ${error.message}`, SETTING_SHAPE_REMEDY);
+	}
+	const compilerCache = resolveCompilerCache({
+		root,
+		optimizations,
+		settingsContext
+	});
+	const cas = compilerCache.cas;
+	optimizations = compilerCache.optimizations;
+	if (compilerCache.warning) warn("cache", compilerCache.warning);
+	const buildProfile = optimizationBuildProfile("android", optimizations);
+	const cacheProviderConfig = resolveCacheProvider(settingsContext);
+	const cacheProviderError = cacheProviderSettingError(settings);
+	if (cacheProviderError) warn("cache", `${cacheProviderError} Using the local cache.`);
+	const dataPartitionSizeError = androidDataPartitionSizeGbSettingError(settings);
+	if (dataPartitionSizeError) return fail("STIM_BAD_ARG", dataPartitionSizeError, "Set android.dataPartitionSizeGb to a whole number of GiB from 6 through 16384.");
+	const avdConfigError = validateAvdConfig(settings, root);
+	if (avdConfigError) return fail("STIM_BAD_ARG", avdConfigError, "Use only documented android.avdConfig keys, or an android.avdConfigFile fragment contained by the app directory.");
+	const remoteSettingError = remoteDeviceSettingError(settings);
+	if (remoteSettingError) return fail("STIM_BAD_ARG", remoteSettingError, `Set ios.remote and android.remote to one of: ${REMOTE_DEVICE_BACKENDS.join(", ")}.`);
+	const systemImage = resolveSystemImage(systemImageFlag, settings);
+	const variant = easProfile !== void 0 ? "debug" : resolveVariant(variantFlag, settings);
+	const flavorRefusal = productFlavorRefusal({
+		flavors: readFlavors(root),
+		variant
+	});
+	if (flavorRefusal) return fail(flavorRefusal.code, flavorRefusal.reason, flavorRefusal.remedy);
+	const release = isReleaseVariant(variant);
+	const cachePolicy = artifactCachePolicy(optimizations, requestedBuildCache, release);
+	const isExpo = detectExpo(root);
+	const physical = isPhysicalDeviceRequest(deviceFlag);
+	if (physical && deviceFlag === "") return fail("STIM_BAD_ARG", "--device was given an empty serial.", "Pass `--device` on its own to take the first connected device this workspace can lease, or `--device <serial>` to name one.");
+	if (physical && commandRemoteBackend) return fail("STIM_BAD_ARG", "--device installs on a device connected to this machine, and --remote installs on a remote one.", "Pass only one of --device and --remote.");
+	const noWait = waitFlag === false;
+	const waitFlagged = waitFlag !== void 0;
+	if (waitConflict) return fail("STIM_BAD_ARG", "--wait and --no-wait ask for opposite things.", "Pass `--wait <seconds>` to wait for the lease, or `--no-wait` to install without one.");
+	if (waitFlagged && !physical) return fail("STIM_BAD_ARG", "--wait and --no-wait only apply to a `--device` run.", "This workspace owns its emulator, so nothing contends for it. Drop the flag, or pass `--device`.");
+	const waitParsed = parseDeviceWait(noWait ? void 0 : waitFlag);
+	if ("error" in waitParsed) return fail("STIM_BAD_ARG", waitParsed.error, "Pass a whole number of seconds, e.g. --wait 90. `--wait 0` refuses a leased device at once.");
+	const waitSeconds = waitParsed.seconds;
+	const remoteBackend = physical ? null : commandRemoteBackend ?? remoteAndroidSetting(settings);
+	const imageRefusal = systemImageRefusal({
+		slot,
+		flag: systemImageFlag,
+		resolved: systemImage,
+		physical,
+		remoteBackend,
+		listImages: listSystemImages
+	});
+	if (imageRefusal) return fail(imageRefusal.code, imageRefusal.message, imageRefusal.remedy);
+	const target = physical ? {
+		kind: "physical",
+		serial: typeof deviceFlag === "string" ? deviceFlag : null,
+		lease: {
+			waitSeconds,
+			noWait
+		}
+	} : remoteBackend ? {
+		kind: "remote",
+		backend: remoteBackend,
+		systemImage
+	} : {
+		kind: "emulator",
+		systemImage
+	};
+	return {
+		ok: true,
+		plan: {
+			build: {
+				variant,
+				release,
+				profile: buildProfile,
+				cas,
+				cache: cachePolicy,
+				compilerCache: optimizations.android.compilerCache,
+				gradleBuildCache: optimizations.android.gradleBuildCache,
+				pch: optimizations.android.pch,
+				targetAbiOnly: optimizations.android.targetAbiOnly
+			},
+			target,
+			isExpo,
+			metroWarmup: optimizations.metroWarmup,
+			cacheProviderConfig
+		}
+	};
+}
+//#endregion
+//#region src/commands/android.ts
+const FALLBACK_LINES = 5;
 function androidCommand(program) {
 	registerAndroid(program);
 }
@@ -1448,6 +1558,25 @@ function androidSlotOptions(options) {
 		writeLaunch: ((projectRoot, platform, record) => base.writeLaunch(projectRoot, platform, record, slot))
 	};
 }
+function avdSetupFailure(error, root, logFile) {
+	const refusal = (0, ownership_claim_exports.claimFailure)(error, "stim android");
+	if (refusal) return refusal;
+	const diag = noDeviceDiagnostic({
+		reason: `Could not ensure an owned Android emulator: ${error?.message || error}`,
+		logFile,
+		localEmulator: !(error instanceof AvdRecoveryError),
+		remedy: error instanceof AvdBootError ? error.remedy : "Check that JAVA_HOME and ANDROID_HOME are set correctly, and that an arm64 system image is installed (`sdkmanager \"system-images;android-36;google_apis;arm64-v8a\"`)."
+	});
+	return {
+		code: NO_DEVICE,
+		message: diag.message,
+		remedy: diag.remedy,
+		extra: {
+			lines: diag.lines,
+			logPath: diag.logPath ? displayPath(root, diag.logPath) : null
+		}
+	};
+}
 async function runAndroid(options = {}) {
 	let { root, json, commandRemoteBackend, resolveSettingsFor, resolveRemoteDeviceContext, makeRemoteDeviceDeps, resolveEasBin, ensureRemoteMetro, ensureRemoteOwned, detectRemoteProviders, metroCheck, useBuildCache: requestedBuildCache, easProfile, resolveEasBuild, variantFlag, systemImageFlag, deviceFlag, waitFlag, waitConflict, acquireLease, makeRunLease, selectPool, onLeaseSignal, listDevices, deviceModel, deviceAbi, isEmulatorDevice, readApkPackage, getLimits, checkCapacity, acquireSlot, releaseSlot, ensureDevice, listSystemImages, ensureDeviceBooted, resolveAvdSerial, waitForDeviceBoot, resolveMetro, prewarmMetro, resolveMetroRetrying, readState, pidAlive, verifyCollector, verifyLaunched, ensureStorage, fingerprint, untracked, resolveCached, storeCached, storedAssets, captureAssets, acquireLock, releaseLock, waitForBuild, loadProvider, easAuth, resolveRemoteBuild, uploadRemoteBuild, resolveCacheProvider, loadCacheProviderModule, needsPrebuildFor, prebuild, build, ccacheFor, install, launch, launchRelease, verifyReleaseLaunched, swapApk, resolveDevClientScheme, spawn, kill, createWriter, writeLaunch, writeState, recordStats, readEstimates, now, out, emit } = androidSlotOptions(options);
 	const slot = validateDeviceSlot(options.slot);
@@ -1596,64 +1725,30 @@ async function runAndroid(options = {}) {
 		platform: PLATFORM
 	});
 	const settings = resolveSettingsFor(settingsContext);
-	const [shapeError, ...moreShapeErrors] = [parkedMaxSetting("android").error, ...settingShapeErrors(settings)].filter((error) => Boolean(error));
-	if (shapeError) return fail("STIM_BAD_ARG", shapeError, SETTING_SHAPE_REMEDY, { lines: moreShapeErrors });
-	for (const key of unknownSettingKeys(settings)) out(phaseLine("setting", chalk.yellow(`Warning: setting "${key}" is not read by Stim and will be ignored.`)));
-	let optimizations;
-	try {
-		optimizations = resolveOptimizations(settings);
-	} catch (error) {
-		return fail("STIM_BAD_ARG", `Could not configure Android build: ${error.message}`, SETTING_SHAPE_REMEDY);
-	}
-	const compilerCache = androidCompilerCache({
-		root,
-		optimizations,
-		settingsContext
-	});
-	const cas = compilerCache.cas;
-	optimizations = compilerCache.optimizations;
-	if (compilerCache.warning) out(phaseLine("cache", chalk.yellow(compilerCache.warning)));
-	const buildProfile = optimizationBuildProfile("android", optimizations);
-	const cacheProviderConfig = resolveCacheProvider(settingsContext);
-	const cacheProviderError = cacheProviderSettingError(settings);
-	if (cacheProviderError) out(phaseLine("cache", chalk.yellow(`${cacheProviderError} Using the local cache.`)));
-	const dataPartitionSizeError = androidDataPartitionSizeGbSettingError(settings);
-	if (dataPartitionSizeError) return fail("STIM_BAD_ARG", dataPartitionSizeError, "Set android.dataPartitionSizeGb to a whole number of GiB from 6 through 16384.");
-	const avdConfigError = androidAvdConfigSettingError(settings, settingsRoot);
-	if (avdConfigError) return fail("STIM_BAD_ARG", avdConfigError, "Use only documented android.avdConfig keys, or an android.avdConfigFile fragment contained by the app directory.");
-	const remoteSettingError = remoteDeviceSettingError(settings);
-	if (remoteSettingError) return fail("STIM_BAD_ARG", remoteSettingError, `Set ios.remote and android.remote to one of: ${REMOTE_DEVICE_BACKENDS.join(", ")}.`);
-	const systemImage = resolveSystemImage(systemImageFlag, settings);
-	const variant = easProfile !== void 0 ? "debug" : resolveVariant(variantFlag, settings);
-	const flavorRefusal = productFlavorRefusal({
-		flavors: readProductFlavors(root),
-		variant
-	});
-	if (flavorRefusal) return fail(flavorRefusal.code, flavorRefusal.reason, flavorRefusal.remedy);
-	const release = isReleaseVariant(variant);
-	const cachePolicy = artifactCachePolicy(optimizations, requestedBuildCache, release);
-	const useBuildCache = cachePolicy.read;
-	const isExpo = detectIsExpo(root);
-	const physical = isPhysicalDeviceRequest(deviceFlag);
-	if (physical && deviceFlag === "") return fail("STIM_BAD_ARG", "--device was given an empty serial.", "Pass `--device` on its own to take the first connected device this workspace can lease, or `--device <serial>` to name one.");
-	if (physical && commandRemoteBackend) return fail("STIM_BAD_ARG", "--device installs on a device connected to this machine, and --remote installs on a remote one.", "Pass only one of --device and --remote.");
-	const noWait = waitFlag === false;
-	const waitFlagged = waitFlag !== void 0;
-	if (waitConflict) return fail("STIM_BAD_ARG", "--wait and --no-wait ask for opposite things.", "Pass `--wait <seconds>` to wait for the lease, or `--no-wait` to install without one.");
-	if (waitFlagged && !physical) return fail("STIM_BAD_ARG", "--wait and --no-wait only apply to a `--device` run.", "This workspace owns its emulator, so nothing contends for it. Drop the flag, or pass `--device`.");
-	const waitParsed = parseDeviceWait(noWait ? void 0 : waitFlag);
-	if ("error" in waitParsed) return fail("STIM_BAD_ARG", waitParsed.error, "Pass a whole number of seconds, e.g. --wait 90. `--wait 0` refuses a leased device at once.");
-	const waitSeconds = waitParsed.seconds;
-	const remoteBackend = physical ? null : commandRemoteBackend ?? remoteAndroidSetting(settings);
-	const imageRefusal = systemImageRefusal({
+	const planned = resolveAndroidRunPlan({
+		settings,
+		settingsContext,
 		slot,
-		flag: systemImageFlag,
-		resolved: systemImage,
-		physical,
-		remoteBackend,
-		listImages: listSystemImages
+		easProfile,
+		variant: variantFlag,
+		systemImage: systemImageFlag,
+		device: deviceFlag,
+		wait: waitFlag,
+		waitConflict,
+		remote: commandRemoteBackend,
+		buildCache: requestedBuildCache
+	}, {
+		resolveCacheProvider,
+		listSystemImages,
+		warn: (label, message) => out(phaseLine(label, chalk.yellow(message)))
 	});
-	if (imageRefusal) return fail(imageRefusal.code, imageRefusal.message, imageRefusal.remedy);
+	if (!planned.ok) return fail(planned.code, planned.message, planned.remedy, { lines: planned.lines });
+	const { plan } = planned;
+	const { build: buildPlan, target, isExpo, cacheProviderConfig } = plan;
+	const { variant, release, profile: buildProfile, cas, cache: cachePolicy } = buildPlan;
+	const useBuildCache = cachePolicy.read;
+	const physical = target.kind === "physical";
+	const remoteBackend = target.kind === "remote" ? target.backend : null;
 	const easBuild = await resolveEasBuild({
 		root,
 		platform: PLATFORM,
@@ -1665,7 +1760,6 @@ async function runAndroid(options = {}) {
 		buildCache: requestedBuildCache
 	});
 	if (isEasBuildFailure(easBuild)) return fail(easBuild.code, easBuild.message, easBuild.remedy);
-	const requestedSerial = typeof deviceFlag === "string" ? deviceFlag : null;
 	let androidPackage = detectAndroidPackage(root);
 	record.bundleId = androidPackage;
 	const registerProject = () => upsertProject(root, {
@@ -1741,15 +1835,15 @@ async function runAndroid(options = {}) {
 	let device;
 	let bootDuration = "";
 	let bootPromise;
-	if (physical && !requestedSerial) {
+	if (target.kind === "physical" && !target.serial) {
 		const pooled = await pooledAndroidDevice({
 			root,
 			selectPool,
 			listDevices,
 			isEmulatorDevice,
 			deviceModel,
-			waitSeconds,
-			noWait,
+			waitSeconds: target.lease.waitSeconds,
+			noWait: target.lease.noWait,
 			now,
 			warn: (line) => out(phaseLine("lease", chalk.yellow(line)))
 		});
@@ -1759,8 +1853,8 @@ async function runAndroid(options = {}) {
 			ok: true,
 			serial: pooled.device.serial
 		});
-	} else if (physical) {
-		const resolved = resolvePhysicalDevice(requestedSerial, listDevices(), isEmulatorDevice);
+	} else if (target.kind === "physical") {
+		const resolved = resolvePhysicalDevice(target.serial, listDevices(), isEmulatorDevice);
 		if (!resolved.serial) return fail(NO_DEVICE, resolved.error, resolved.remedy);
 		device = {
 			serial: resolved.serial,
@@ -1786,22 +1880,14 @@ async function runAndroid(options = {}) {
 				projectPath: root,
 				settingsRoot,
 				settings,
-				flags: { systemImage },
+				flags: { systemImage: target.systemImage },
 				note: out,
 				out,
 				logFile: emuLog
 			});
 		} catch (err) {
-			const diag = noDeviceDiagnostic({
-				reason: `Could not ensure an owned Android emulator: ${err?.message || err}`,
-				logFile: emuLog,
-				localEmulator: !(err instanceof AvdRecoveryError),
-				remedy: err instanceof AvdRecoveryError ? err.remedy : "Check that JAVA_HOME and ANDROID_HOME are set correctly, and that an arm64 system image is installed (`sdkmanager \"system-images;android-36;google_apis;arm64-v8a\"`)."
-			});
-			return fail(NO_DEVICE, diag.message, diag.remedy, {
-				lines: diag.lines,
-				logPath: diag.logPath ? displayPath(root, diag.logPath) : null
-			});
+			const failure = avdSetupFailure(err, root, emuLog);
+			return fail(failure.code, failure.message, failure.remedy, failure.extra);
 		}
 		const prepareMs = prepare();
 		if (device.created || prepareMs >= 2e3) phase("device", `${device.avdName || device.deviceName || label} ${device.created ? "created" : "prepared"} (${formatDuration(prepareMs)})`);
@@ -1858,7 +1944,7 @@ async function runAndroid(options = {}) {
 		deviceAbi,
 		compiler: cas?.id,
 		buildProfile,
-		targetAbiOnly: optimizations.android.targetAbiOnly
+		targetAbiOnly: buildPlan.targetAbiOnly
 	});
 	let hash = "";
 	let providerUpload = null;
@@ -1960,7 +2046,7 @@ async function runAndroid(options = {}) {
 		return true;
 	}
 	const runFromFingerprint = async () => {
-		if (metroCheck && metroPort !== null && optimizations.metroWarmup) prewarmMetro({
+		if (metroCheck && metroPort !== null && plan.metroWarmup) prewarmMetro({
 			port: metroPort,
 			platform: "android",
 			isExpo,
@@ -2036,7 +2122,7 @@ async function runAndroid(options = {}) {
 						logFile: buildLog
 					});
 				} catch (err) {
-					const refusal = claimFailure(err, "stim android");
+					const refusal = (0, ownership_claim_exports.claimFailure)(err, "stim android");
 					if (refusal) {
 						phaseFailure = fail(refusal.code, refusal.message, refusal.remedy, { lastBuildStatus: true });
 						return false;
@@ -2067,7 +2153,7 @@ async function runAndroid(options = {}) {
 							ceilingMs
 						});
 					} catch (err) {
-						const refusal = claimFailure(err, "stim android");
+						const refusal = (0, ownership_claim_exports.claimFailure)(err, "stim android");
 						if (refusal) {
 							phaseFailure = fail(refusal.code, refusal.message, refusal.remedy, { lastBuildStatus: true });
 							return false;
@@ -2149,7 +2235,7 @@ async function runAndroid(options = {}) {
 						out
 					});
 				} catch (err) {
-					const refusal = claimFailure(err, "stim android");
+					const refusal = (0, ownership_claim_exports.claimFailure)(err, "stim android");
 					if (refusal) {
 						phaseFailure = fail(refusal.code, refusal.message, refusal.remedy, { lastBuildStatus: true });
 						return false;
@@ -2206,19 +2292,19 @@ async function runAndroid(options = {}) {
 						abi: buildAbi
 					}, {
 						estimateMs: estimates().coldBuildMs,
-						ccache: optimizations.android.compilerCache === "ccache" ? ccacheFor({
+						ccache: buildPlan.compilerCache === "ccache" ? ccacheFor({
 							root,
 							onNote: out
 						}) : null,
 						cas,
-						buildCache: optimizations.android.gradleBuildCache,
-						pch: optimizations.android.pch,
-						compilerCacheDisabled: optimizations.android.compilerCache === "none"
+						buildCache: buildPlan.gradleBuildCache,
+						pch: buildPlan.pch,
+						compilerCacheDisabled: buildPlan.compilerCache === "none"
 					});
 					ccacheActivity = built.ccache ?? CCACHE_UNAVAILABLE;
 					phase("cache", `compilation cache ${ccacheActivityLine(ccacheActivity)}`);
-					if (built.failed) {
-						const diagnostics = built.diagnostics || [];
+					if (!built.ok) {
+						const diagnostics = built.diagnostics;
 						for (const diag of diagnostics) writer.write({
 							src: "build",
 							level: "error",
@@ -2227,7 +2313,7 @@ async function runAndroid(options = {}) {
 						});
 						phase("build", chalk.red(`FAILED after ${formatDuration(built.durationMs)}`));
 						const extracted = diagnostics.map(formatDiagnostic);
-						if ((built.truncated ?? 0) > 0) extracted.push(`... and ${built.truncated} more diagnostic(s) in the log`);
+						if (built.truncated > 0) extracted.push(`... and ${built.truncated} more diagnostic(s) in the log`);
 						phaseFailure = fail(built.code, built.reason, diagnostics.find((d) => d.remedy)?.remedy || built.remedy || null, {
 							lastBuildStatus: true,
 							diagnostics: extracted,
@@ -2236,8 +2322,8 @@ async function runAndroid(options = {}) {
 						});
 						return false;
 					}
-					apkPath = built.apkPath ?? null;
-					stats.setBuildMs(built.durationMs ?? 0);
+					apkPath = built.apkPath;
+					stats.setBuildMs(built.durationMs);
 					phase("build", `ok (${formatDuration(built.durationMs)})`);
 					if (built.apkNote) phase("build", chalk.yellow(built.apkNote));
 					const beforeBuildHash = storeHash;
@@ -2329,8 +2415,8 @@ async function runAndroid(options = {}) {
 				id: device.serial,
 				deviceName: device.deviceName ?? null,
 				idLabel: "serial",
-				waitSeconds,
-				noWait,
+				waitSeconds: target.lease.waitSeconds,
+				noWait: target.lease.noWait,
 				installBoundMs: ADB_INSTALL_TIMEOUT_MS,
 				appId: androidPackage,
 				holderAppId: (holder) => getProject(holder)?.androidPackage ?? null,