stim 1.18.0 → 1.19.0

package/dist/ios-ITYno9rO.mjs

@@ -0,0 +1,2241 @@
+import { n as ownership_claim_exports } from "./process-identity-Biv3arCO.mjs";
+import { _ as stepTimer, g as stepClock, i as formatDuration, l as phaseLine, m as shortHash } from "./command-output-Bt8ygHE7.mjs";
+import { L as deviceSlotFileKey, V as parseDeviceSlotOption, W as validateDeviceSlot, z as deviceSlotPlatforms } from "./config-DC5jEtd1.mjs";
+import { i as recordWorkspaceUse, v as workspaceDir, x as workspaceLogsDir$1 } from "./workspace-state-CR9X86xJ.mjs";
+import { b as MODE_EXPO, s as projectProblem, t as NO_PROJECT_REFUSAL, y as MODE_BARE } from "./project-B5eQ1USs.mjs";
+import { A as publicUrlSetting, B as settingShapeErrors, C as metroWarmupUrlSetting, Dt as optimizationBuildProfile, N as remoteEasFallbackSetting, Ot as resolveOptimizations, P as remoteIosSetting, T as parseIosRemote, Tt as artifactCachePolicy, U as tunnelModeSetting, W as unknownSettingKeys, _ as iosSigningIdentitySha1SettingError, f as iosLanHostSetting, g as iosSigningIdentitySha1Setting, h as iosSigningIdentitySettingError, i as SETTING_SHAPE_REMEDY, m as iosSigningIdentitySetting, p as iosLanHostSettingError, u as cacheProviderSettingError, x as metroPortSetting } from "./settings-CxgngUZk.mjs";
+import { I as startBuildProgress, L as tapBuildLog, O as NO_BUILD_PROGRESS, R as createRunRecorder, W as statsProjectKey$1 } from "./budget-Dz-kyXLv.mjs";
+import { A as providerDownloadPath, b as buildCacheKey, j as providerUploadOutcome, k as prepareProviderDownloadDir, v as waitForSharedBuild } from "./device-lease-Cu7PtQpZ.mjs";
+import { ft as parkedMaxSetting, ot as POOL_SETTING_REMEDY } from "./android-BdQC6zs1.mjs";
+import { i as createIosSimSnapshot } from "./ios-BWbHFZVz.mjs";
+import { A as resolveBuildPlacement, C as setRemoteLogSink, D as parseBuildMachineOption, E as namedBuildMachine, O as requireLocalBuild, S as withNativeBuildRun, a as offloadBuild, b as runCancellation, c as placementLoad, i as closeOffload, l as remotePhaseText, n as buildPlacementCandidates, p as cancelledFailure, r as chooseBuildMachine, s as offloadPlacement, u as simulatorRuntime, w as OffloadRefusal, x as runCancellationSignal } from "./client-CuUo8Nvg.mjs";
+import { p as COMPILATION_CACHE_NOT_RUN, v as compilationCacheActivityLine } from "./toolchain-C3xSoyUl.mjs";
+import { r as hostedMetroSettings } from "./metro-gateway-BxpJLIwh.mjs";
+import { i as writeDevicePlacement } from "./ios-state-By0XuLTQ.mjs";
+import { _ as devicePlacementLine, i as skippedMissReason, l as didSetUpDevice } from "./miss-reason-CjQCOKqq.mjs";
+import { n as devicePlacementRecord, t as buildPlacementRecord } from "./placement-log-Dxe34rJm.mjs";
+import { r as DEFAULT_METRO_PORT } from "./app-install-CFI4ptUL.mjs";
+import { r as siblingPlatformSlots, t as launchSlotScope } from "./slot-launch-HV_KtPIw.mjs";
+import { a as easAuthNote, o as exitAfterFlush, s as isEasAuthFailureText, t as RESOLVE_TIMEOUT_MS } from "./remote-cache-N3hAEaAL.mjs";
+import "./dev-client-CDY_zAmD.mjs";
+import { T as ownedSessionName, n as binOnPath } from "./device-remote-B5GiUifk.mjs";
+import { a as isEasBuildFailure, o as planEasDevelopmentBuild } from "./simslim-D9LkJxIO.mjs";
+import { f as waitFlagConflict, o as leaseExpiryText } from "./device-lease-run-D38SnZtt.mjs";
+import { r as isPhysicalDeviceRequest, t as ensureDevServer } from "./native-runtime-BGxsbfny.mjs";
+import { a as printPlan, i as planPayload, n as planCachedBuild, o as refusePlan, r as planFlagRefusal, s as runArtifactLifecycle, t as planHostedDevice } from "./plan-placement-BVY59qa8.mjs";
+import { a as iosPoolCandidates, c as isWirelessIosDevice, f as resolveIosPhysicalDevice, o as iosPoolNoCandidatesRefusal, r as iosDeviceBounds } from "./ios-device-CJ_ZOGky.mjs";
+import { c as lastBuildRecord, d as DEFAULT_DEPS, h as lanOriginUrlFor, i as finishIosRun, l as reportIosResult, m as chooseLanAddress, n as reactNativeIosSchemeProblem, o as finishIosUpload, r as IosRecipeRefusal, u as writeLastBuild } from "./react-native-ios-CSpIxexZ.mjs";
+import { _ as resolveSimulatorAppFlag, a as deviceModelRefusal, c as iosProviderRunOptions, f as printDiagnostics, g as resolveRuntime, h as resolveIosWait, i as deviceLabel, l as isReleaseConfiguration, m as resolveDeviceType, n as buildLogFile, p as resolveConfiguration, r as createIosDeviceWaitRun, u as ownedSimFailure, v as simulatorBuildArch, y as xcodeFailureReport } from "./support-CNqYkV0y.mjs";
+import { rmSync } from "node:fs";
+import { basename, join } from "node:path";
+import { hostedIosStatus, machineCapacity, parseMachine } from "@stim-cli/core/state";
+import chalk from "chalk";
+import { InvalidArgumentError } from "commander";
+import { workspaceId } from "@stim-cli/core";
+import { createWarnOnce, resolveTieredBuild, storeTieredBuild } from "@stim-cli/cache";
+//#region src/commands/ios/artifact.ts
+const PROVIDER_SKIPPED_ON_DEVICE = "a device build is local-tier only: its cache key names the iphoneos slice, and a remote or provider entry is keyed for the simulator";
+function fail(failure) {
+	throw new IosRecipeRefusal(failure);
+}
+async function acquireIosArtifact({ root, logFile, recipe, physical, configuration, buildMachine = "auto", cache, easBuild, maxBuilds, progress }, d) {
+	const { phase, note, logWriter, stats, step, miss, hit: lateHit, place, waitingOn, waitingFor } = progress;
+	const cachePolicy = cache.policy;
+	const signal = runCancellationSignal() ?? new AbortController().signal;
+	const cacheTarget = (key) => ({
+		projectRoot: root,
+		platform: "ios",
+		key,
+		signal
+	});
+	const useBuildCache = cachePolicy.read;
+	const cacheProviderConfig = cache.providerConfig;
+	let compilationCache = COMPILATION_CACHE_NOT_RUN;
+	const temporaryDirs = /* @__PURE__ */ new Set();
+	const releaseArtifact = () => {
+		for (const directory of temporaryDirs) {
+			try {
+				rmSync(directory, {
+					recursive: true,
+					force: true
+				});
+			} catch {}
+			temporaryDirs.delete(directory);
+		}
+	};
+	let buildLock = null;
+	const releaseLock = () => {
+		if (!buildLock) return;
+		const held = buildLock;
+		buildLock = null;
+		try {
+			d.releaseBuildLock(held);
+		} catch (e) {
+			note(chalk.dim(`Could not release the build lock at ${held.path}: ${e?.message || e}`));
+		}
+	};
+	let buildSlot = null;
+	const releaseSlot = () => {
+		if (!buildSlot) return;
+		const held = buildSlot;
+		buildSlot = null;
+		try {
+			d.releaseBuildSlot(held);
+		} catch (e) {
+			note(chalk.dim(`Could not release the build slot: ${e?.message || e}`));
+		}
+	};
+	let fingerprint = "";
+	let cacheKey = "";
+	let storeHash = null;
+	let storeKey = null;
+	let appPath = null;
+	let bundleId = null;
+	let cacheHit = false;
+	let offloadedTo = null;
+	let handoff = null;
+	let offloadFallback = null;
+	let fallbackMachine = null;
+	let hereReason = "no remote Mac is paired";
+	let slotWaitMs;
+	let builtOn;
+	const fallBack = (reason, line = reason, info = {}) => {
+		logWriter().write(buildPlacementRecord({
+			platform: "ios",
+			buildMachine,
+			candidates: info.candidates,
+			event: "placement_fallback",
+			fallback: {
+				code: info.code ?? "fallback",
+				reason,
+				machine: info.machine
+			}
+		}));
+		if (namedBuildMachine(buildMachine)) throw new OffloadRefusal(buildMachine, reason);
+		requireLocalBuild(buildMachine);
+		offloadFallback = reason;
+		buildFailure = {
+			...buildFailure,
+			offloadFallback: reason
+		};
+		phase("build", `${line} -> building here`);
+	};
+	const openOffload = { choice: null };
+	let remote = null;
+	let abandonedRemote = false;
+	let uploadPending = null;
+	let providerUpload = null;
+	let providerName = null;
+	let providerLoad = null;
+	const cacheWarn = createWarnOnce((line) => note(chalk.yellow(phaseLine("cache", line))));
+	const loadProvider = cachePolicy.remote && cacheProviderConfig && !physical ? () => providerLoad ??= d.loadCacheProvider({
+		projectRoot: root,
+		config: cacheProviderConfig
+	}) : null;
+	if (cacheProviderConfig && physical) note(chalk.dim(phaseLine("cache", PROVIDER_SKIPPED_ON_DEVICE)));
+	let waitedForBuild = null;
+	let releasedWait = null;
+	let swapFellBack = false;
+	let buildFailure = {};
+	let missReason = null;
+	async function resolveInitialFingerprint() {
+		if (easBuild?.ok) {
+			fingerprint = storeHash = easBuild.fingerprint;
+			cacheKey = storeKey = easBuild.cacheKey;
+			appPath = easBuild.path;
+			cacheHit = easBuild.cacheHit;
+			providerName = "eas";
+			stats.setCacheKey(cacheKey);
+			recipe.validateExternal(appPath);
+			return;
+		}
+		if (useBuildCache) step("cache-lookup");
+		const fingerprintTimer = stepTimer(d.now);
+		const identity = await recipe.identity();
+		fingerprint = identity.hash;
+		cacheKey = identity.key;
+		stats.setCacheKey(cacheKey);
+		storeHash = fingerprint;
+		storeKey = cacheKey;
+		const found = await resolveTieredBuild({
+			local: recipe.cache(),
+			loadProvider,
+			target: {
+				projectRoot: root,
+				platform: "ios",
+				key: cacheKey
+			},
+			destinationDir: providerDownloadPath(workspaceDir(root)),
+			ensureDestination: prepareProviderDownloadDir,
+			skipRead: !useBuildCache,
+			warn: cacheWarn
+		});
+		const cached = found?.tier === "local" ? found.path : null;
+		cacheHit = cached ? "local" : false;
+		phase("fingerprint", `${shortHash(fingerprint)} ${cached ? "hit" : "miss"}${useBuildCache ? "" : cache.disabledByFlag ? " (--no-build-cache)" : " (cache reuse off in config)"} ${fingerprintTimer()}`);
+		if (found?.tier === "provider") {
+			cacheHit = "remote";
+			providerName = found.providerName ?? null;
+			phase("cache", `provider hit (${providerName})${found.storedLocally ? " -> stored locally" : ""}`);
+		}
+		appPath = found?.path ?? null;
+	}
+	async function resolveRemoteArtifact() {
+		if (!recipe.legacyCache) return null;
+		if (!appPath) {
+			const loaded = await recipe.legacyCache.load();
+			if (loaded?.unavailable) note(chalk.yellow(phaseLine("cache", `provider not usable: ${loaded.unavailable}`)));
+			else if (loaded?.provider) remote = loaded;
+			if (remote?.name === "eas") {
+				const auth = d.checkEasAuth({
+					projectRoot: root,
+					owner: loaded?.owner || null
+				});
+				const authNote = easAuthNote(auth);
+				if (authNote) note(chalk.yellow(phaseLine("cache", authNote)));
+				if (auth?.code === "logged-out") remote = null;
+			}
+		}
+		if (remote && useBuildCache) {
+			const remoteTimer = stepTimer(d.now);
+			const hit = await d.resolveRemote({
+				logWriter: logWriter(),
+				provider: remote.provider,
+				platform: "ios",
+				projectRoot: root,
+				fingerprintHash: fingerprint,
+				runOptions: recipe.legacyCache?.runOptions ?? null
+			});
+			if (hit?.appPath) {
+				let stored = null;
+				try {
+					stored = await recipe.cache().store({
+						...cacheTarget(cacheKey),
+						sourcePath: hit.appPath,
+						overwrite: false
+					}) ?? null;
+				} catch (e) {
+					note(chalk.yellow(phaseLine("cache", `remote hit could not be stored locally: ${e?.message || e}`)));
+				}
+				appPath = stored || hit.appPath;
+				cacheHit = "remote";
+				phase("cache", `remote hit (${remote.name})${stored ? " -> stored locally" : ""} ${remoteTimer()}`);
+			} else if (hit?.timedOut) {
+				abandonedRemote = true;
+				note(chalk.yellow(phaseLine("cache", `${remote.name} did not answer within ${formatDuration(RESOLVE_TIMEOUT_MS)}; building instead`)));
+			} else if (hit?.failed) {
+				const authNote = remote.name === "eas" && isEasAuthFailureText(hit.failed) ? easAuthNote({
+					code: "logged-out",
+					reason: hit.failed
+				}) : null;
+				note(chalk.yellow(phaseLine("cache", authNote || `${remote.name} could not be used: ${hit.failed}; building instead`)));
+			} else phase("cache", `remote miss (${remote.name}) ${remoteTimer()}`);
+		}
+		return remote;
+	}
+	async function awaitSharedBuild() {
+		if (!useBuildCache || appPath) return;
+		const shared = await waitForSharedBuild({
+			platform: "ios",
+			key: cacheKey,
+			fingerprint,
+			root,
+			logFile,
+			command: "stim ios",
+			acquire: d.acquireBuildLock,
+			wait: d.waitForBuild,
+			now: d.now,
+			phase: (text) => {
+				step("wait");
+				phase("build", text);
+			},
+			waitingOn,
+			warn: (text) => note(chalk.yellow(phaseLine("build", text))),
+			out: note
+		});
+		if (shared.refusal) fail({
+			...shared.refusal,
+			build: {
+				fingerprint,
+				cacheKey,
+				cacheHit,
+				cacheSkipped: !useBuildCache
+			}
+		});
+		buildLock = shared.lock;
+		releasedWait = shared.released;
+		if (shared.hit) {
+			appPath = shared.hit.path;
+			cacheHit = "local";
+			waitedForBuild = shared.hit.waited;
+		}
+	}
+	const installableCachedApp = async (path) => {
+		const prepared = await recipe.materialize(path, {
+			fresh: false,
+			ownTemporary: (directory) => temporaryDirs.add(directory)
+		});
+		if (!prepared) swapFellBack = true;
+		return prepared;
+	};
+	async function prepareCachedArtifact(cachedPath) {
+		const prepared = await installableCachedApp(cachedPath);
+		if (!prepared) {
+			cacheHit = false;
+			waitedForBuild = null;
+		}
+		return prepared;
+	}
+	function reasonForMiss(rekeyedBy) {
+		if (swapFellBack) return {
+			reason: skippedMissReason("the cached app could not be reused, so this run built it fresh"),
+			diff: null
+		};
+		if (!useBuildCache) return {
+			reason: skippedMissReason(cache.disabledByFlag ? "cache reuse turned off by --no-build-cache" : "cache reuse off in config"),
+			diff: null
+		};
+		return recipe.explain(rekeyedBy);
+	}
+	function explainMiss(rekeyedBy) {
+		const explained = reasonForMiss(rekeyedBy);
+		missReason = explained.reason;
+		if (explained.diff) logWriter().write(explained.diff);
+		buildFailure = {
+			...buildFailure,
+			missReason
+		};
+		miss(missReason);
+		phase("cache", `miss: ${missReason.summary}`);
+		if (missReason.kind === "no-baseline") {
+			const untracked = recipe.untrackedLine();
+			if (untracked) note(chalk.dim(phaseLine("fingerprint", untracked)));
+		}
+	}
+	async function settleStoreKeyAfterCompile() {
+		if (!storeHash || !storeKey) return;
+		const identity = await recipe.validate();
+		storeHash = identity?.hash ?? null;
+		storeKey = identity?.key ?? null;
+		buildFailure = {
+			...buildFailure,
+			fingerprint: storeHash,
+			cacheKey: storeKey
+		};
+	}
+	async function takeBuildSlot() {
+		requireLocalBuild(buildMachine);
+		if (!maxBuilds) return;
+		try {
+			buildSlot = await d.acquireBuildSlot({
+				automatic: buildMachine === "auto",
+				max: maxBuilds,
+				root,
+				logFile,
+				out: note,
+				waitingFor: (info) => waitingFor?.(info, "build-slot")
+			});
+			slotWaitMs = buildSlot.slotWaitMs;
+		} catch (e) {
+			requireLocalBuild(buildMachine);
+			const refusal = (0, ownership_claim_exports.claimFailure)(e, "stim ios");
+			if (refusal) fail({
+				code: refusal.code,
+				message: refusal.message,
+				remedy: refusal.remedy,
+				build: buildFailure
+			});
+			note(chalk.yellow(phaseLine("build", `could not take a build slot: ${e?.message || e}; building anyway`)));
+		}
+	}
+	/** Whether this build should leave this Mac, before any machine is asked; null builds here. */
+	function placeBuild() {
+		const { mode, machines, localEnabled } = buildPlacementCandidates(buildMachine);
+		if (localEnabled && machines.length === 0 && !namedBuildMachine(buildMachine) && buildMachine !== "local") return null;
+		const { runtime, unsupported } = recipe.offload?.context() ?? {
+			runtime: null,
+			unsupported: "this project integration does not support offloaded builds"
+		};
+		const here = machineCapacity();
+		const placement = offloadPlacement({
+			mode,
+			localEnabled,
+			machines: machines.length,
+			here,
+			unsupported,
+			selected: buildMachine
+		});
+		if (!placement.offload) {
+			hereReason = placement.reason;
+			logWriter().write(buildPlacementRecord({
+				platform: "ios",
+				buildMachine,
+				stays: {
+					code: placement.code,
+					reason: placement.reason
+				}
+			}));
+			if (mode !== "off") phase("build", `placement: here (${placement.reason})`);
+			return null;
+		}
+		return {
+			mode,
+			here,
+			code: placement.code,
+			reason: placement.reason,
+			runtime,
+			machines
+		};
+	}
+	/** Asks the paired machines once the post-mutation key is known; null builds here. */
+	async function chooseMachine(candidate) {
+		let asked = [];
+		const choice = await chooseBuildMachine({
+			projectRoot: root,
+			target: recipe.offload.target(candidate.runtime),
+			mode: candidate.mode,
+			here: candidate.here,
+			note: (line) => note(chalk.dim(phaseLine("build", `offload: ${line}`))),
+			machines: candidate.machines,
+			selected: buildMachine,
+			onCandidates: (each) => asked = each
+		});
+		if (typeof choice === "string") {
+			const only = candidate.machines.length === 1 ? candidate.machines[0].machine : null;
+			if (only && choice.startsWith(`${only}: `)) fallbackMachine = only;
+			fallBack(choice, choice, {
+				code: "no-remote-mac-took-it",
+				candidates: asked
+			});
+			return null;
+		}
+		openOffload.choice = choice;
+		logWriter().write(buildPlacementRecord({
+			platform: "ios",
+			buildMachine,
+			candidates: asked,
+			chose: {
+				machine: choice.machine,
+				reason: `${candidate.reason}${placementLoad(choice)}`
+			}
+		}));
+		phase("build", `placement: ${choice.machine} (${candidate.reason}${placementLoad(choice)})`);
+		return choice;
+	}
+	/** Builds on the chosen machine and stores the app under the post-mutation key; false builds here instead unless a machine was named. */
+	async function compileElsewhere({ choice, candidate }) {
+		const runtime = candidate.runtime;
+		if (!storeKey || !storeHash) {
+			if (namedBuildMachine(buildMachine)) fallBack("the build fingerprint or cache key is unavailable");
+			return false;
+		}
+		const stagingDir = join(workspaceDir(root), "offload", "ios");
+		const outcome = await offloadBuild({
+			choice,
+			expectedFingerprint: storeHash,
+			request: recipe.offload.request(runtime),
+			stagingDir,
+			onPhase: (name, msg) => phase(name, remotePhaseText(name, msg, choice.machine)),
+			onEnter: (name) => {
+				if (name === "compile" || name === "build" || name === "prebuild" || name === "pods") {
+					builtOn = choice.machine;
+					buildFailure = {
+						...buildFailure,
+						builtOn
+					};
+				}
+				place({
+					host: choice.machine,
+					phase: name
+				});
+				step(name === "prebuild" || name === "pods" ? name : "compile");
+			},
+			onRecord: (record) => logWriter().write({
+				...record,
+				offloadedTo: choice.machine
+			}),
+			note: (line) => phase("build", line)
+		});
+		place(null);
+		let stored = null;
+		let reason = outcome.ok ? null : outcome.reason;
+		if (outcome.ok) {
+			if (!await recipe.offload.unchanged()) reason = "the checkout here changed while it built";
+			else try {
+				stored = await recipe.cache().store({
+					...cacheTarget(storeKey),
+					sourcePath: outcome.artifactPath,
+					overwrite: !useBuildCache
+				}) ?? null;
+			} catch (e) {
+				reason = `could not store the app: ${e?.message || e}`;
+			}
+		}
+		try {
+			rmSync(stagingDir, {
+				recursive: true,
+				force: true
+			});
+		} catch {}
+		step("compile");
+		const prepared = stored ? await installableCachedApp(stored) : null;
+		if (!outcome.ok || !prepared) {
+			const why = reason ?? "the stored app is not installable";
+			fallbackMachine = choice.machine;
+			fallBack(`${choice.machine}: ${why}`, `offload failed: ${why}`, {
+				code: "offload-failed",
+				machine: choice.machine
+			});
+			logWriter().write({
+				src: "build",
+				level: "warn",
+				event: "offload_failed",
+				msg: reason,
+				machine: choice.machine
+			});
+			return false;
+		}
+		const { timings } = outcome;
+		appPath = prepared;
+		builtOn = outcome.machine;
+		offloadedTo = outcome.machine;
+		handoff = outcome.handoff ?? null;
+		stats.setPlacement({
+			decision: "offloaded",
+			machine: outcome.machine,
+			reason: `${candidate.reason}${placementLoad(choice)}`,
+			buildMs: timings.totalMs
+		});
+		phase("build", `built on ${outcome.machine} in ${formatDuration(timings.totalMs)}: offer ${formatDuration(timings.offerMs)}, sync ${formatDuration(timings.syncMs)}, build ${formatDuration(timings.workerMs)}, fetch ${formatDuration(timings.fetchMs)}`);
+		compilationCache = outcome.compilationCache;
+		phase("cache", `compilation cache on ${outcome.machine} ${compilationCacheActivityLine(compilationCache)}`);
+		logWriter().write({
+			src: "build",
+			level: "info",
+			event: "offload_done",
+			msg: `built on ${outcome.machine}`,
+			timings
+		});
+		return true;
+	}
+	async function prepareSource() {
+		await recipe.prepare(() => miss(reasonForMiss([]).reason, true));
+		return recipe.reconcile();
+	}
+	async function revalidateSource({ identity, mutationLabel }) {
+		if (!identity) {
+			storeHash = null;
+			storeKey = null;
+			buildFailure = {
+				...buildFailure,
+				fingerprint: null,
+				cacheKey: null
+			};
+		} else if (identity.key !== storeKey) {
+			storeHash = identity.hash;
+			storeKey = identity.key;
+			buildFailure = {
+				...buildFailure,
+				fingerprint: storeHash,
+				cacheKey: storeKey
+			};
+			const late = useBuildCache ? await recipe.cache().resolve({
+				...cacheTarget(storeKey),
+				destinationDir: providerDownloadPath(workspaceDir(root))
+			}) : null;
+			if (late) {
+				const prepared = await installableCachedApp(late);
+				if (prepared) {
+					appPath = prepared;
+					cacheHit = "local";
+					lateHit();
+					phase("cache", `hit ${shortHash(storeHash)} (post-${mutationLabel} key)`);
+					if (releasedWait) {
+						waitedForBuild = releasedWait.facts;
+						phase("build", `waited ${formatDuration(waitedForBuild.ms)} for ${releasedWait.who}'s build -> installed from cache -- stim guide lifecycle concurrency`);
+					}
+				}
+			}
+		}
+		return appPath ? { ready: appPath } : null;
+	}
+	async function acquireRemoteArtifact(offload, { rekeyedBy }) {
+		explainMiss(rekeyedBy);
+		step("compile");
+		if (!storeKey) fallBack("no cache key to store the app under", "offload failed: no cache key to store the app under");
+		const choice = storeKey ? await chooseMachine(offload) : null;
+		if (choice) await compileElsewhere({
+			choice,
+			candidate: offload
+		});
+		return appPath ? { ready: appPath } : null;
+	}
+	async function compileHere(offload, { rekeyedBy }) {
+		if (!offload) explainMiss(rekeyedBy);
+		step("compile");
+		if (offload) stats.setPlacement({
+			decision: "fell-back",
+			slotWaitMs,
+			deviceSlotWaitMs: stats.deviceSlotWaitMs(),
+			reason: offloadFallback ?? "offload failed",
+			...fallbackMachine ? { machine: fallbackMachine } : {}
+		});
+		else stats.setPlacement({
+			decision: "here",
+			reason: hereReason,
+			slotWaitMs,
+			deviceSlotWaitMs: stats.deviceSlotWaitMs()
+		});
+		requireLocalBuild(buildMachine);
+		builtOn = "here";
+		buildFailure = {
+			...buildFailure,
+			builtOn
+		};
+		phase("build", `compiling ${configuration || "Debug"} with xcodebuild`);
+		const result = await recipe.compile();
+		compilationCache = result.compilationCache;
+		phase("cache", `compilation cache ${compilationCacheActivityLine(compilationCache)}`);
+		if (!result.ok) {
+			phase("build", `FAILED after ${formatDuration(result.durationMs)}`);
+			printDiagnostics(note, result);
+			const report = xcodeFailureReport(result, logFile);
+			fail({
+				code: result.code,
+				message: report.message,
+				remedy: report.remedy,
+				logPath: logFile,
+				build: {
+					...buildFailure,
+					diagnostics: result.diagnostics
+				}
+			});
+		}
+		stats.setBuildMs(result.durationMs);
+		phase("build", `ok (${formatDuration(result.durationMs)})`);
+		appPath = result.appPath;
+		bundleId = result.bundleId;
+		return appPath;
+	}
+	async function storeArtifact(artifactPath) {
+		if (storeKey && cachePolicy.write) try {
+			const stored = await storeTieredBuild({
+				local: recipe.cache(),
+				loadProvider,
+				target: {
+					projectRoot: root,
+					platform: "ios",
+					key: storeKey
+				},
+				sourcePath: artifactPath,
+				overwrite: !useBuildCache || swapFellBack,
+				warn: cacheWarn
+			});
+			providerUpload = stored.providerUpload;
+			providerName = stored.providerName ?? providerName;
+		} catch (e) {
+			note(chalk.yellow(`Could not store the build in the shared cache: ${e?.message || e}`));
+		}
+	}
+	async function finishArtifact(artifactPath) {
+		let installPath = artifactPath;
+		const prepared = await recipe.materialize(installPath, {
+			fresh: true,
+			ownTemporary: (directory) => temporaryDirs.add(directory)
+		});
+		if (!prepared) fail({
+			code: "STIM_INSTALL_FAILED",
+			message: "The project integration could not prepare the built app for installation.",
+			remedy: "Check the artifact preparation details above, then retry.",
+			build: {
+				...buildFailure,
+				appPath: installPath
+			}
+		});
+		installPath = prepared;
+		if (remote && !physical && storeHash) uploadPending = d.uploadRemote({
+			logWriter: logWriter(),
+			provider: remote.provider,
+			platform: "ios",
+			projectRoot: root,
+			fingerprintHash: storeHash,
+			buildPath: installPath,
+			runOptions: recipe.legacyCache?.runOptions ?? null
+		});
+		return installPath;
+	}
+	let transferred = false;
+	try {
+		appPath = await runArtifactLifecycle({
+			resolve: async () => {
+				await resolveInitialFingerprint();
+				if (easBuild) return {
+					kind: "ready",
+					artifact: appPath
+				};
+				remote = await resolveRemoteArtifact();
+				if (appPath) return {
+					kind: "cached",
+					artifact: appPath
+				};
+				miss(reasonForMiss([]).reason);
+				return { kind: "miss" };
+			},
+			claim: useBuildCache ? async () => {
+				await awaitSharedBuild();
+				return appPath;
+			} : void 0,
+			reuse: async (cached) => {
+				appPath = await prepareCachedArtifact(cached);
+				if (appPath) lateHit();
+				else if (swapFellBack) miss(reasonForMiss([]).reason);
+				return appPath;
+			},
+			build: {
+				placement: {
+					select: () => {
+						buildFailure = {
+							fingerprint,
+							cacheKey,
+							cacheHit,
+							cacheSkipped: !useBuildCache,
+							buildMachine
+						};
+						return placeBuild();
+					},
+					acquire: acquireRemoteArtifact
+				},
+				admit: takeBuildSlot,
+				prepare: prepareSource,
+				revalidate: revalidateSource,
+				compile: compileHere,
+				validate: async () => {
+					await settleStoreKeyAfterCompile();
+					return storeKey ? "cacheable" : "uncacheable";
+				},
+				store: storeArtifact,
+				finish: finishArtifact
+			},
+			release: () => {
+				if (openOffload.choice) closeOffload(openOffload.choice);
+				releaseLock();
+				releaseSlot();
+			}
+		});
+		const artifact = {
+			handoff,
+			path: appPath,
+			bundleId,
+			cache: {
+				identity: storeHash && storeKey ? {
+					fingerprint: storeHash,
+					key: storeKey
+				} : null,
+				hit: cacheHit,
+				providerName: remote?.name ?? providerName,
+				buildMachine,
+				...builtOn ? { builtOn } : {},
+				offloadedTo,
+				offloadFallback: offloadedTo ? null : offloadFallback,
+				readEnabled: useBuildCache,
+				missReason: cacheHit ? null : missReason,
+				waitedForBuild,
+				compilation: compilationCache
+			},
+			failureFields: {
+				...buildFailure,
+				buildMachine,
+				...builtOn ? { builtOn } : {},
+				fingerprint: storeHash,
+				cacheKey: storeKey,
+				cacheHit,
+				cacheSkipped: !useBuildCache
+			},
+			completeUploads: async () => {
+				const uploadWasAbandoned = await finishIosUpload(uploadPending, remote, phase, note);
+				const outcome = providerUploadOutcome(providerUpload ? await providerUpload : null, providerName);
+				if (outcome) {
+					if (outcome.warn) note(chalk.yellow(phaseLine("cache", outcome.line)));
+					else phase("cache", outcome.line);
+				}
+				return abandonedRemote || uploadWasAbandoned;
+			},
+			release: releaseArtifact
+		};
+		transferred = true;
+		return {
+			ok: true,
+			artifact
+		};
+	} catch (error) {
+		if (error instanceof OffloadRefusal) {
+			const refusal = error;
+			return {
+				ok: false,
+				failure: {
+					code: refusal.code,
+					message: refusal.message,
+					remedy: refusal.remedy,
+					build: {
+						...buildFailure,
+						buildMachine,
+						...builtOn ? { builtOn } : {}
+					}
+				},
+				compilationCache
+			};
+		}
+		if (error instanceof IosRecipeRefusal) return {
+			ok: false,
+			failure: {
+				...error.failure,
+				build: {
+					...buildFailure,
+					...error.failure.build
+				}
+			},
+			compilationCache
+		};
+		throw error;
+	} finally {
+		if (!transferred) releaseArtifact();
+	}
+}
+//#endregion
+//#region src/commands/ios/remote.ts
+function resolveIosRemote({ opts, settings, physical, recorded }) {
+	const target = opts.remote !== void 0 ? parseIosRemote(opts.remote) : remoteIosSetting(settings);
+	if (physical && target?.kind === "machine") return { failure: {
+		code: "STIM_BAD_ARG",
+		message: "--device builds for a phone connected to this machine, and --remote installs on a remote one.",
+		remedy: "Pass only one of --device and --remote; unset ios.remote for a local phone."
+	} };
+	const machine = target?.kind === "machine" ? target.machine : null;
+	if (recorded && recorded.machine !== machine && machine !== "auto") return { failure: {
+		code: "STIM_BAD_ARG",
+		message: `This workspace's iOS simulator runs on ${recorded.machine}; run stim stop first.`
+	} };
+	return {
+		machine,
+		backend: !physical && target?.kind === "backend" ? target.backend : null,
+		recorded
+	};
+}
+function selectIosTarget({ root, slot, opts, settings, physical, release, metroCheck, d }) {
+	let recorded;
+	try {
+		recorded = d.readHostedIos(root, slot)[slot];
+	} catch (error) {
+		return { failure: {
+			code: "STIM_HOSTING_REFUSED",
+			message: error.message,
+			...error instanceof Error && "remedy" in error && typeof error.remedy === "string" ? { remedy: error.remedy } : {}
+		} };
+	}
+	const selection = resolveIosRemote({
+		opts,
+		settings,
+		physical,
+		recorded
+	});
+	if ("failure" in selection) return selection;
+	const localIos = selection.machine ? deviceSlotPlatforms(d.getProject(root), slot)?.ios : void 0;
+	if (selection.machine !== "auto" && selection.machine && localIos?.owned && localIos.deviceUdid) {
+		let localRunning = true;
+		try {
+			localRunning = d.listAllIosSims({ timeoutMs: 5e3 }).some((sim) => sim.udid === localIos.deviceUdid && sim.state !== "Shutdown");
+		} catch {}
+		if (localRunning) return { failure: {
+			code: "STIM_BAD_ARG",
+			message: `This workspace's iOS simulator for slot ${slot} runs on this Mac; run stim stop first.`
+		} };
+	}
+	if (selection.machine !== "auto" && selection.machine && !release && !metroCheck) return { failure: {
+		code: "STIM_BAD_ARG",
+		message: "Hosted Debug runs require the local Metro supervisor; --no-metro-check cannot be used.",
+		remedy: "Run stim stop; stim start, then retry without --no-metro-check."
+	} };
+	return selection;
+}
+async function selectIosPlacement(args) {
+	const selection = selectIosTarget(args);
+	if ("failure" in selection || selection.machine !== "auto") return selection;
+	const { root, slot, d, opts, deviceType, runtime, noWait, phase, log, release, metroCheck } = args;
+	const viewer = resolveSimulatorAppFlag(opts.simulatorApp, args.physical, null);
+	if ("refusal" in viewer) return { failure: viewer.refusal };
+	const refusal = args.validateSelectors();
+	if (refusal) return { failure: refusal };
+	const easFallback = remoteEasFallbackSetting(args.settings);
+	try {
+		const placed = await d.automaticDevicePlacement({
+			root,
+			slot,
+			platform: "ios",
+			selectors: hostedIosSelectors(deviceType, runtime),
+			buildMachine: opts.remoteBuild,
+			noWait,
+			...easFallback ? { eas: () => d.checkEasFallback({
+				root,
+				platform: "ios",
+				slot,
+				release,
+				isExpo: d.detectIsExpo(root),
+				tunnelMode: tunnelModeSetting(args.settings),
+				publicUrl: publicUrlSetting(args.settings),
+				deviceTypeFlag: opts.deviceType,
+				localOnlyFlags: typeof opts.runtime === "string" ? ["--runtime"] : []
+			}) } : {}
+		});
+		phase("placement:", devicePlacementLine(placed.placement, placed.skipped));
+		log?.(devicePlacementRecord({
+			platform: "ios",
+			fromFlag: opts.remote !== void 0,
+			easFallback,
+			placed
+		}));
+		if (placed.placement.decision === "eas") return {
+			...selection,
+			machine: null,
+			backend: "eas",
+			recorded: void 0,
+			auto: { target: null },
+			devicePlacement: placed.placement
+		};
+		if (placed.target && !release && !metroCheck) return { failure: {
+			code: "STIM_BAD_ARG",
+			message: "Hosted Debug runs require the local Metro supervisor; --no-metro-check cannot be used.",
+			remedy: "Run stim stop; stim start, then retry without --no-metro-check."
+		} };
+		return {
+			...selection,
+			machine: placed.target?.host.machine ?? null,
+			recorded: void 0,
+			auto: { target: placed.target },
+			budget: placed.target ? {
+				reclaimed: [],
+				refusal: null
+			} : void 0,
+			devicePlacement: placed.placement
+		};
+	} catch (error) {
+		return { failure: {
+			code: error.code ?? "STIM_HOSTING_REFUSED",
+			message: error.message,
+			...error instanceof Error && "remedy" in error && typeof error.remedy === "string" ? { remedy: error.remedy } : {}
+		} };
+	}
+}
+function hostedIosSelectors(deviceType, runtime) {
+	return {
+		...deviceType ? { deviceType } : {},
+		...runtime ? { runtime } : {}
+	};
+}
+async function connectIosTarget(selection, selectors, d) {
+	if (selection.auto) return { target: selection.auto.target };
+	if (!selection.machine) return { target: null };
+	try {
+		return { target: await d.prepareHostedIos(selection.machine, selectors, selection.recorded) };
+	} catch (error) {
+		return { failure: {
+			code: error instanceof Error && "code" in error && typeof error.code === "string" ? error.code : "STIM_HOSTING_REFUSED",
+			message: error instanceof Error ? error.message : String(error),
+			...error instanceof Error && "remedy" in error && typeof error.remedy === "string" ? { remedy: error.remedy } : {}
+		} };
+	}
+}
+async function iosPlacementBudget(d, root, note, hosted, automatic, simSnapshot) {
+	if (automatic) return {
+		...automatic,
+		refusal: hosted ? null : automatic.refusal
+	};
+	return hosted ? {
+		reclaimed: [],
+		refusal: null
+	} : d.budgetGate({
+		root,
+		note,
+		simSnapshot
+	});
+}
+function hostedIosMetroNote(hosted, settings, note, simulatorApp) {
+	if (hosted && (settings.iosSimulatorApp !== void 0 || simulatorApp !== void 0)) note(chalk.dim(phaseLine("device", "iosSimulatorApp is ignored on a hosting Mac; the simulator boots headless.")));
+	if (hosted && (publicUrlSetting(settings) || tunnelModeSetting(settings))) note(chalk.dim(phaseLine("metro", "metro.publicUrl and metro.tunnel are ignored on a hosting Mac; Metro uses the private tailnet bridge.")));
+}
+async function connectIosBackend(root, backend, deviceType, d) {
+	if (!backend) return {
+		remote: null,
+		arch: null
+	};
+	const resolved = await d.resolveRemoteContext({
+		root,
+		backend,
+		easBin: d.resolveEasCliBin(root)?.file ?? null,
+		deviceType: deviceType?.trim() || null
+	});
+	if ("failed" in resolved) return { failure: {
+		code: resolved.code ?? "STIM_NO_REMOTE_SESSION",
+		message: resolved.failed,
+		remedy: resolved.remedy
+	} };
+	return {
+		remote: d.remoteIosDeps(resolved.ctx),
+		arch: await d.readRemoteSimulatorArch(resolved.ctx.existingDaemon)
+	};
+}
+//#endregion
+//#region src/commands/ios/hosted.ts
+async function finishHostedIosRun({ target, d, artifact, root, slot, release, isExpo, metroCheck, metroPort, logsDir, fail, note, enterPhase, selectors, ...report }) {
+	const bundleId = artifact.bundleId ?? (d.readBundleId(artifact.path) || d.detectBundleId(root));
+	if (!bundleId) return fail({
+		code: "STIM_INSTALL_FAILED",
+		message: "The built app has no bundle identifier."
+	});
+	const launchedAt = d.now();
+	let run;
+	try {
+		run = await d.placeHostedIos(target, {
+			root,
+			slot,
+			bundle: artifact.path,
+			handoff: artifact.handoff,
+			bundleId,
+			selectors,
+			release,
+			...!release && isExpo ? { devClientScheme: d.devClientScheme(root, artifact.path) ?? void 0 } : {},
+			reserved: (placement) => d.writeHostedIos(root, slot, placement),
+			note,
+			enterPhase
+		});
+	} catch (error) {
+		return fail({
+			code: error.code ?? "STIM_HOSTING_REFUSED",
+			message: error.message,
+			remedy: error instanceof Error && "remedy" in error && typeof error.remedy === "string" ? error.remedy : `Retry stim ios --remote ${target.host.machine}, or run stim stop to reconcile any recorded placement.`
+		});
+	}
+	d.writeHostedIos(root, slot, run.placement);
+	d.writeWorkspaceLaunch(root, "ios", {
+		appId: bundleId,
+		deviceId: run.placement.session,
+		metroPort,
+		release,
+		launchedAt: new Date(launchedAt).toISOString()
+	}, slot);
+	let launched = run.launched;
+	if (!release && metroCheck) {
+		const evidence = await d.verifyLaunch({
+			requireBundleResponse: true,
+			platform: "ios",
+			logsDir,
+			since: launchedAt,
+			metroPort,
+			mode: isExpo ? MODE_EXPO : MODE_BARE,
+			slot: launchSlotScope(root, slot),
+			platformShared: siblingPlatformSlots(root, "ios", slot).length > 0
+		});
+		if (evidence.fatal) return fail({
+			code: "STIM_LAUNCH_FAILED",
+			message: "Metro could not deliver the hosted app bundle.",
+			remedy: "Run stim logs --errors and fix the bundle error."
+		});
+		launched = evidence.verified ? true : evidence.requested ? "bundling" : "unverified";
+	}
+	if (launched === "unverified") note(`Launch on ${target.host.machine} is unverified; check the hosted app, then retry stim ios --remote ${target.host.machine}.`);
+	const cache = artifact.cache;
+	const device = run.placement.device;
+	const uploadsAbandoned = await artifact.completeUploads();
+	return {
+		facts: reportIosResult({
+			...report,
+			root,
+			slot,
+			release,
+			metroCheck,
+			metroPort,
+			logsDir,
+			device: {
+				deviceName: device.deviceType,
+				deviceType: device.deviceType,
+				runtime: device.runtime
+			},
+			udid: "",
+			host: hostedIosStatus(run.placement),
+			appPath: artifact.path,
+			bundleId,
+			installSkipped: false,
+			storeHash: cache.identity?.fingerprint ?? null,
+			storeKey: cache.identity?.key ?? null,
+			cacheHit: cache.hit,
+			missReason: cache.missReason,
+			compilationCache: cache.compilation,
+			useBuildCache: cache.readEnabled,
+			waitedForBuild: cache.waitedForBuild,
+			launchState: launched,
+			providerName: cache.providerName,
+			buildMachine: cache.buildMachine,
+			builtOn: cache.builtOn,
+			offloadedTo: cache.offloadedTo,
+			offloadFallback: cache.offloadFallback,
+			webPreviewUrl: null
+		}),
+		uploadsAbandoned
+	};
+}
+//#endregion
+//#region src/commands/ios/next-build.ts
+function note(line) {
+	console.error(line);
+}
+function runOnlyFlag(opts) {
+	if (isPhysicalDeviceRequest(opts.device)) return "--device";
+	if (opts.remote) return "--remote";
+	if (opts.wait !== void 0) return opts.wait === false ? "--no-wait" : "--wait";
+	if (opts.simulatorApp !== void 0) return "--simulator-app";
+	if (opts.metroCheck === false) return "--no-metro-check";
+	return null;
+}
+async function planIos(opts, d, schemeRefusal) {
+	const json = Boolean(opts.json);
+	const refuse = (refusal, lines = []) => refusePlan(refusal, json, lines);
+	const flag = runOnlyFlag(opts);
+	if (flag) return refuse(planFlagRefusal(flag));
+	const root = d.findProjectRoot(process.cwd());
+	if (!root) return refuse(NO_PROJECT_REFUSAL);
+	const problem = projectProblem(root, "ios");
+	if (problem) return refuse({
+		code: "STIM_NO_PROJECT",
+		...problem
+	});
+	const settingsContext = {
+		projectPath: root,
+		gitCommonDir: d.gitCommonDir(root),
+		repoRoot: d.repoRoot(root)
+	};
+	const settings = d.resolveSettings(settingsContext);
+	const [shapeError, ...moreShapeErrors] = settingShapeErrors(settings);
+	if (shapeError) return refuse({
+		code: "STIM_BAD_ARG",
+		message: shapeError,
+		remedy: SETTING_SHAPE_REMEDY
+	}, moreShapeErrors);
+	let optimizations;
+	try {
+		optimizations = resolveOptimizations(settings);
+	} catch (error) {
+		return refuse({
+			code: "STIM_BAD_ARG",
+			message: error.message,
+			remedy: SETTING_SHAPE_REMEDY
+		});
+	}
+	const cacheProviderError = cacheProviderSettingError(settings);
+	if (cacheProviderError) note(chalk.yellow(phaseLine("cache", `${cacheProviderError} Using the local cache.`)));
+	const slot = opts.slot ?? "default";
+	const target = {
+		platform: "ios",
+		slot,
+		root,
+		projectKey: statsProjectKey$1({
+			root,
+			commonDir: settingsContext.gitCommonDir,
+			repoRoot: settingsContext.repoRoot
+		})
+	};
+	const isExpo = d.detectIsExpo(root);
+	const settingsLayersForOrigin = d.settingsLayers(settingsContext);
+	const iosRemote = remoteIosSetting(settings);
+	const modelRefusal = deviceModelRefusal({
+		slot,
+		deviceTypeFlag: opts.deviceType,
+		runtimeFlag: opts.runtime,
+		deviceType: resolveDeviceType(opts.deviceType, settings),
+		runtime: resolveRuntime(opts.runtime, settings),
+		deviceTypeOrigin: d.settingOriginScope(settingsLayersForOrigin, "ios.deviceType"),
+		runtimeOrigin: d.settingOriginScope(settingsLayersForOrigin, "ios.runtime"),
+		physical: false,
+		remoteBackend: iosRemote?.kind === "backend" ? iosRemote.backend : null,
+		hosted: iosRemote?.kind === "machine",
+		listRuntimes: d.listIosRuntimes
+	});
+	if (modelRefusal) return refuse(modelRefusal);
+	if (opts.easProfile !== void 0) {
+		const eas = await planEasDevelopmentBuild({
+			root,
+			platform: "ios",
+			profile: opts.easProfile,
+			note,
+			isExpo,
+			selectors: [opts.scheme, opts.configuration],
+			buildCache: opts.buildCache
+		});
+		if (!eas.ok) return refuse(eas);
+		return printPlan(planPayload(target, {
+			fingerprint: eas.fingerprint,
+			cacheKey: eas.cacheKey,
+			cacheHit: eas.buildId ? "remote" : false,
+			provider: "eas",
+			cacheSkipped: false,
+			prebuild: null,
+			refusal: eas.missing
+		}), json);
+	}
+	if (iosRemote?.kind === "backend") return refuse({
+		code: "STIM_BAD_ARG",
+		message: `ios.remote is ${iosRemote.backend}, whose simulator architecture --plan cannot read without a session.`,
+		remedy: "Run `stim ios` to build for the remote device, or unset ios.remote to plan the owned simulator."
+	});
+	const refusal = schemeRefusal(root, opts.scheme, isExpo);
+	if (refusal) return refuse({
+		code: refusal.code,
+		message: refusal.message ?? "",
+		remedy: refusal.remedy ?? ""
+	});
+	const configuration = resolveConfiguration(opts.configuration, settings);
+	const buildProfile = optimizationBuildProfile("ios", optimizations);
+	const cachePolicy = artifactCachePolicy(optimizations, opts.buildCache !== false, isReleaseConfiguration(configuration));
+	let fingerprint;
+	try {
+		fingerprint = await d.fingerprintProject(root, { platform: "ios" });
+	} catch (error) {
+		note(chalk.dim(`Fingerprinting failed: ${error?.message || error}`));
+	}
+	if (!fingerprint?.hash) return refuse({
+		code: "STIM_NO_FINGERPRINT",
+		message: `Could not fingerprint ${root}: @expo/fingerprint produced no hash for it.`,
+		remedy: "Check the project native inputs and the @expo/fingerprint error above, then retry."
+	});
+	const keyArch = (remoteArch) => simulatorBuildArch({
+		physical: false,
+		remoteArch,
+		hostArch: d.hostSimulatorArch(),
+		configuration
+	});
+	let arch = keyArch(null);
+	let placement;
+	if (iosRemote?.kind === "machine") {
+		const planned = await planHostedDevice({
+			root,
+			slot,
+			platform: "ios",
+			machine: iosRemote.machine,
+			selectors: hostedIosSelectors(resolveDeviceType(opts.deviceType, settings), resolveRuntime(opts.runtime, settings)),
+			sameKey: (choice) => keyArch("runtime" in choice ? choice.architecture : null) === arch,
+			...remoteEasFallbackSetting(settings) ? { eas: () => d.checkEasFallback({
+				root,
+				platform: "ios",
+				slot,
+				release: isReleaseConfiguration(configuration),
+				isExpo,
+				tunnelMode: tunnelModeSetting(settings),
+				publicUrl: publicUrlSetting(settings),
+				deviceTypeFlag: opts.deviceType,
+				localOnlyFlags: typeof opts.runtime === "string" ? ["--runtime"] : []
+			}) } : {}
+		});
+		if (planned.kind === "unknown") return refuse({
+			code: "STIM_BAD_ARG",
+			message: `ios.remote is ${iosRemote.machine}, and its simulator architecture is unknown here: ${planned.reason}.`,
+			remedy: "Run `stim ios` to build for the remote device, or unset ios.remote to plan the owned simulator."
+		});
+		placement = planned.placement;
+		if (planned.kind === "hosted" && "runtime" in planned.choice) arch = keyArch(planned.choice.architecture);
+	}
+	const cacheKey = buildCacheKey("ios", fingerprint.hash, {
+		scheme: opts.scheme,
+		...configuration ? { configuration } : {},
+		isSimulator: true,
+		...arch ? { arch } : {},
+		...buildProfile ? { buildProfile } : {}
+	});
+	const plan = await planCachedBuild({
+		...target,
+		isExpo,
+		fingerprint: fingerprint.hash,
+		sources: fingerprint.sources ?? [],
+		cacheKey,
+		cachePolicy,
+		providerConfig: d.resolveCacheProviderConfig(settingsContext),
+		expoRemote: cachePolicy.remote && !buildProfile && !opts.scheme ? { runOptions: iosProviderRunOptions(configuration, arch) } : null
+	}, {
+		loadCacheProvider: d.loadCacheProvider,
+		loadProjectProvider: d.loadProjectProvider,
+		checkEasAuth: d.checkEasAuth,
+		resolveRemote: d.resolveRemote,
+		planPrebuild: d.planPrebuild,
+		note
+	});
+	printPlan(placement ? {
+		...plan,
+		placement
+	} : plan, json);
+}
+//#endregion
+//#region src/commands/ios.ts
+function writeNote(line) {
+	console.error(line);
+}
+function writePhase(name, text) {
+	console.error(phaseLine(name, text));
+}
+function iosCommand(program) {
+	registerIos(program);
+}
+function registerIos(program, deps = {}) {
+	program.command("ios").description("Build (or restore from the fingerprint cache), install and launch this workspace's app on its owned simulator, wired to the reserved Metro port. A Debug run starts the dev server when it is not running.").option("--eas-profile <name>", "Download a matching EAS development build; on a miss, print the build command without running it").option("--slot <name>", "Reusable device slot within this workspace (default: default)", parseDeviceSlotOption).option("--remote-build <value>", "Build on auto, local, or one named machine; a name refuses without fallback", parseBuildMachineOption).option("--json", "Emit the facts as a single JSON line on stdout; every other line goes to stderr").option("--plan", "Predict the next build without building, booting or installing: resolve the fingerprint, check the local then remote cache, and print the expected cache result and duration. Writes no Stim state.").option("--scheme <name>", "Shared Xcode app scheme to build; overrides automatic scheme selection, not the app URL scheme").option("--no-metro-check", "Skip the \"is this workspace's dev server running?\" check: do not start it, and build anyway").option("--no-build-cache", "Build fresh, ignoring cached artifacts (local and the project's build-cache provider); the fresh build still replaces the cache entry").option("--configuration <name>", "Xcode configuration to build (e.g. Release). A non-Debug configuration embeds the JS bundle and skips Metro entirely. Overrides the ios.configuration setting. Default: Debug").option("--device-type <name>", "Simulator model to create this workspace's owned sim as, exactly as `xcrun simctl list devicetypes` names it (e.g. \"iPad Pro 13-inch (M5)\"). Overrides the ios.deviceType setting for this invocation. A model no installed runtime can create refuses with STIM_BAD_ARG and prints the models they do offer.").option("--runtime <version>", "Simulator runtime to create this workspace's owned sim on, as a version (\"18.5\") or a runtime's full name (\"iOS 18.5\"); nothing else matches. Overrides the ios.runtime setting for this invocation. An unknown version refuses with STIM_BAD_ARG and prints the installed runtimes.").option("--simulator-app <app>", "Open the owned simulator in xcode, siniulator, or stim-desktop for this run, overriding the machine iosSimulatorApp setting. Also opens an already running simulator; local simulators only.").option("--device [udid]", "Build the iphoneos slice for a connected iPhone, install it, and launch it, instead of using this workspace's owned simulator. The phone can be cabled or paired over Wi-Fi. With no UDID, the first cabled device this workspace can lease is used, waiting for one that is busy; a Wi-Fi device is used only when no cabled one is connected and ready. In Debug the app is wired to this workspace's Metro over the LAN. Stim never creates, boots, or deletes a physical device.").option("--remote <target>", "Run on eas, proxy, or an approved Mac in remote.machines; named Macs never fall back locally. auto places on an approved Mac when this Mac is full or busy. local runs here, whatever ios.remote says.", (value) => {
+		if (parseMachine(value)) return value.trim();
+		throw new InvalidArgumentError("expected eas, proxy, auto, local, or a remote Mac name");
+	}).option("--wait <seconds>", "How long to wait for another workspace to release the phone it leases, before refusing with STIM_DEVICE_BUSY (default 60, 0 refuses at once). Without --device, wait for an owned-device slot (default 600 seconds; --no-wait refuses immediately).").option("--no-wait", "Install on a phone another workspace leases instead of waiting: this run takes no lease and, when both workspaces build the same app id, the install terminates the holder's running app. Without --device, refuse a full device cap or existing slot queue immediately.").action(async (opts) => {
+		if (opts.plan) {
+			const d = {
+				...DEFAULT_DEPS,
+				...deps
+			};
+			await planIos(opts, d, (root, scheme, isExpo) => reactNativeIosSchemeProblem(root, scheme, isExpo, d));
+			return;
+		}
+		const completion = await runIosOperation((deps.findProjectRoot ?? DEFAULT_DEPS.findProjectRoot)(process.cwd()), {
+			...opts,
+			waitConflict: waitFlagConflict(process.argv)
+		}, deps);
+		if (!completion) process.exit(runCancellation() ? 130 : 1);
+		else if (completion.uploadsAbandoned) exitAfterFlush(0);
+	});
+}
+function runIosOperation(root, opts = {}, deps = {}, onFailure = () => {}) {
+	const run = (progress) => runIos(root, opts, deps, progress, onFailure);
+	return root ? withNativeBuildRun(root, {
+		command: "ios",
+		platform: "ios",
+		slot: opts.slot ?? "default"
+	}, async (claim) => {
+		recordWorkspaceUse(root);
+		const progress = startBuildProgress({
+			root,
+			platform: "ios",
+			slot: opts.slot ?? "default",
+			claim,
+			note: (line) => writeNote(chalk.dim(line))
+		});
+		try {
+			return await run(progress);
+		} finally {
+			progress.clear();
+		}
+	}, { write: (line) => writeNote(chalk.dim(phaseLine("lock", line))) }) : run();
+}
+function unlessCancelled(result) {
+	if (!result.ok || !runCancellation()) return result;
+	return {
+		ok: false,
+		failure: {
+			code: "STIM_CANCELLED",
+			message: "before install"
+		},
+		compilationCache: result.artifact.cache.compilation
+	};
+}
+function resolveIosBuildSetup(flag, settings) {
+	const placement = resolveBuildPlacement(flag);
+	if (placement.failure) return {
+		ok: false,
+		failure: {
+			...placement.failure,
+			setup: true
+		}
+	};
+	try {
+		return {
+			ok: true,
+			buildMachine: placement.selected,
+			optimizations: resolveOptimizations(settings)
+		};
+	} catch (error) {
+		return {
+			ok: false,
+			failure: {
+				code: "STIM_BAD_ARG",
+				message: error.message,
+				remedy: SETTING_SHAPE_REMEDY
+			}
+		};
+	}
+}
+function iosProjectTargetRefusal(project, { physical, easProfile, placement }) {
+	const target = physical ? "physical" : placement ? placement.machine ? "hosted" : placement.backend ? "remote" : "simulator" : null;
+	if (target && !project.targets.includes(target)) return {
+		code: "STIM_BAD_ARG",
+		message: `This project integration does not support the ${target} iOS target.`,
+		remedy: "Use a local iOS simulator for this integration."
+	};
+	if (easProfile !== void 0 && !project.eas) return {
+		code: "STIM_BAD_ARG",
+		message: "This project integration does not support EAS builds.",
+		remedy: "Use its local iOS build recipe."
+	};
+	return null;
+}
+function iosArtifactTargetInputs({ udid, physical, remote, hosted, simulatorArch, lanAddress, metroPort, settings }) {
+	return {
+		target: {
+			udid,
+			destination: remote || hosted ? "generic/platform=iOS Simulator" : null,
+			sdk: physical ? "iphoneos" : "iphonesimulator",
+			arch: remote || hosted ? simulatorArch : null,
+			keyArch: simulatorArch,
+			offloadRuntime: () => hosted?.choice.runtimeId ?? (remote ? null : simulatorRuntime(udid)),
+			hostedArchitecture: hosted?.choice.architecture,
+			offloadRefusal: physical ? "device builds build here" : remote ? "--remote builds build here" : null
+		},
+		device: physical ? {
+			lanAddress,
+			metroPort,
+			signingName: iosSigningIdentitySetting(settings),
+			signingSha1: iosSigningIdentitySha1Setting(settings)
+		} : null
+	};
+}
+function iosSlotLogFile(root, slot) {
+	return slot === "default" ? buildLogFile(root) : join(workspaceLogsDir$1(root), `build-${deviceSlotFileKey("ios", slot)}.ndjson`);
+}
+function iosSlotDeps(d, slot) {
+	if (slot !== "default") {
+		const base = d;
+		d = {
+			...base,
+			ensureOwnedDevice: (args) => base.ensureOwnedDevice({
+				...args,
+				slot
+			}),
+			checkDeviceCapacity: (args) => base.checkDeviceCapacity({
+				...args,
+				slot
+			}),
+			selectFromPool: (args) => base.selectFromPool({
+				...args,
+				slot
+			}),
+			acquireRunLease: (args) => base.acquireRunLease({
+				...args,
+				slot
+			}),
+			runLease: (args) => base.runLease({
+				...args,
+				slot
+			}),
+			replaceCollector: (args) => base.replaceCollector({
+				...args,
+				slot
+			}),
+			stopPreviousCollector: (args) => base.stopPreviousCollector({
+				...args,
+				slot
+			}),
+			clearIosAdoptionPending: (root) => base.clearIosAdoptionPending(root, slot),
+			writeWorkspaceLaunch: (root, platform, record) => base.writeWorkspaceLaunch(root, platform, record, slot),
+			createWriter: (file, options) => base.createWriter(file, {
+				...options,
+				fields: { slot }
+			})
+		};
+	}
+	return d;
+}
+async function runIos(projectRoot, opts = {}, overrides = {}, progress = NO_BUILD_PROGRESS, onFailure) {
+	const slot = validateDeviceSlot(opts.slot);
+	let d = iosSlotDeps({
+		...DEFAULT_DEPS,
+		...overrides
+	}, slot);
+	const json = Boolean(opts.json);
+	const metroCheck = opts.metroCheck !== false;
+	let useBuildCache = opts.buildCache !== false;
+	const phase = writePhase;
+	const note = writeNote;
+	const started = d.now();
+	const startedAt = new Date(started).toISOString();
+	const elapsed = () => d.now() - started;
+	const refuseProject = ({ message, remedy }) => {
+		note(chalk.red(phaseLine("error", message)));
+		note(chalk.dim(phaseLine("remedy", remedy)));
+		note(chalk.red(phaseLine("failed", "STIM_NO_PROJECT")));
+		if (json) console.log(JSON.stringify({
+			code: "STIM_NO_PROJECT",
+			message,
+			remedy
+		}));
+		onFailure({
+			code: "STIM_NO_PROJECT",
+			message,
+			remedy
+		});
+		return null;
+	};
+	if (!projectRoot) return refuseProject(NO_PROJECT_REFUSAL);
+	const root = projectRoot;
+	const selectedProject = d.projectRegistry.selectIos(root);
+	if ("problem" in selectedProject) return refuseProject(selectedProject.problem);
+	const integration = await selectedProject.load();
+	try {
+		await d.ensureWorkspaceStorage(root, { note });
+	} catch (error) {
+		const code = error?.code || "STIM_WORKSPACE_STATE";
+		const message = `Could not prepare this workspace's Stim state: ${error?.message || error}`;
+		note(chalk.red(`${code}: ${message}`));
+		note(chalk.dim("Check that STIM_HOME is writable and has free space. An EPERM on a directory you can write is a sandbox: allow writes to STIM_HOME, or run Stim with the sandbox disabled (`stim guide errors sandbox`)."));
+		if (json) console.log(JSON.stringify({
+			code,
+			message,
+			remedy: "Check that STIM_HOME is writable and has free space."
+		}));
+		onFailure({
+			code,
+			message,
+			remedy: "Check that STIM_HOME is writable and has free space."
+		});
+		return null;
+	}
+	const logsDir = workspaceLogsDir$1(root);
+	const logFile = iosSlotLogFile(root, slot);
+	let writer = null;
+	const logWriter = () => writer ||= tapBuildLog(d.createWriter(logFile, {
+		truncate: true,
+		fields: {
+			platform: "ios",
+			slot
+		}
+	}), progress);
+	setRemoteLogSink((record) => logWriter().write(record));
+	let leaseHandle = null;
+	let stopLeaseSignals = null;
+	const releaseLease = () => {
+		const held = leaseHandle;
+		const stopSignals = stopLeaseSignals;
+		leaseHandle = null;
+		stopLeaseSignals = null;
+		stopSignals?.();
+		try {
+			held?.release();
+		} catch (e) {
+			note(chalk.dim(`Could not release this run's device lease: ${e?.message || e}`));
+		}
+	};
+	const stats = createRunRecorder({
+		platform: "ios",
+		write: (statsRun, at) => d.recordStats(statsRun, at),
+		now: () => d.now(),
+		note: (line) => note(chalk.dim(line)),
+		phases: () => progress.durations(),
+		deviceSetup: () => progress.deviceSetupKnown()
+	});
+	const deviceWaitRun = createIosDeviceWaitRun(stats, progress, runCancellationSignal());
+	const recordRun = deviceWaitRun.record;
+	let compilationCache = COMPILATION_CACHE_NOT_RUN;
+	let reclaimed = [];
+	let buildMachine = "auto";
+	let devicePlacement;
+	let builtConfiguration = null;
+	const fail = ({ code, message, remedy = null, lines = [], logPath = null, build = null, lease, setup = false }) => {
+		({code, message, remedy, lines} = cancelledFailure("ios", {
+			code,
+			message
+		}) ?? {
+			code,
+			message,
+			remedy,
+			lines
+		});
+		releaseLease();
+		if (message) note(chalk.red(phaseLine("error", message)));
+		for (const line of lines) note(chalk.dim(phaseLine("", line)));
+		if (remedy) note(chalk.dim(phaseLine("remedy", remedy)));
+		if (logPath) note(chalk.dim(phaseLine("log", logPath)));
+		if (build) writeLastBuild(root, lastBuildRecord({
+			devicePlacement,
+			buildMachine,
+			...build,
+			configuration: builtConfiguration,
+			startedAt,
+			status: "failed",
+			errorCode: code,
+			durationMs: elapsed()
+		}));
+		note(chalk.red(phaseLine("failed", code)));
+		if (!setup) recordRun({
+			failed: true,
+			durationMs: elapsed()
+		});
+		if (json) console.log(JSON.stringify({
+			code,
+			message: message ?? null,
+			remedy: remedy ?? null,
+			...devicePlacement ? { devicePlacement } : {},
+			...compilationCache.status === "not-run" ? {} : { compilationCache },
+			...lease === void 0 ? {} : { lease },
+			...reclaimed.length ? { reclaimed } : {}
+		}));
+		writer?.close?.();
+		onFailure({
+			code,
+			message,
+			remedy,
+			lines,
+			logPath,
+			build,
+			lease,
+			setup
+		});
+		return null;
+	};
+	const settingsRepoRoot = d.repoRoot(root);
+	const settingsContext = {
+		projectPath: root,
+		gitCommonDir: d.gitCommonDir(root),
+		repoRoot: settingsRepoRoot
+	};
+	const projectKey = statsProjectKey$1({
+		root,
+		commonDir: settingsContext.gitCommonDir,
+		repoRoot: settingsRepoRoot
+	});
+	stats.setProject(projectKey);
+	progress.estimate(projectKey);
+	let estimatesRead = null;
+	const estimates = () => estimatesRead ??= d.readEstimates({
+		projectKey,
+		platform: "ios"
+	});
+	const settings = d.resolveSettings(settingsContext);
+	const [shapeError, ...moreShapeErrors] = settingShapeErrors(settings);
+	if (shapeError) return fail({
+		code: "STIM_BAD_ARG",
+		message: shapeError,
+		lines: moreShapeErrors,
+		remedy: SETTING_SHAPE_REMEDY
+	});
+	const setup = resolveIosBuildSetup(opts.remoteBuild, settings);
+	if (!setup.ok) return fail(setup.failure);
+	buildMachine = setup.buildMachine;
+	const { optimizations } = setup;
+	const buildProfile = optimizationBuildProfile("ios", optimizations);
+	const cacheProviderConfig = d.resolveCacheProviderConfig(settingsContext);
+	for (const key of unknownSettingKeys(settings)) note(phaseLine("setting", chalk.yellow(`Warning: setting "${key}" is not read by Stim and will be ignored.`)));
+	const cacheProviderError = cacheProviderSettingError(settings);
+	if (cacheProviderError) note(chalk.yellow(phaseLine("cache", `${cacheProviderError} Using the local cache.`)));
+	const poolError = parkedMaxSetting("ios").error;
+	if (poolError) return fail({
+		code: "STIM_BAD_ARG",
+		message: poolError,
+		remedy: POOL_SETTING_REMEDY
+	});
+	for (const settingError of [
+		iosSigningIdentitySettingError(settings),
+		iosSigningIdentitySha1SettingError(settings),
+		iosLanHostSettingError(settings)
+	]) if (settingError) return fail({
+		code: "STIM_BAD_ARG",
+		message: settingError,
+		remedy: SETTING_SHAPE_REMEDY
+	});
+	const configuration = opts.easProfile !== void 0 ? null : resolveConfiguration(opts.configuration, settings);
+	builtConfiguration = configuration ?? "Debug";
+	const buildScheme = opts.scheme;
+	const release = isReleaseConfiguration(configuration);
+	const cachePolicy = artifactCachePolicy(optimizations, useBuildCache, release);
+	useBuildCache = cachePolicy.read;
+	const deviceType = resolveDeviceType(opts.deviceType, settings);
+	const runtime = resolveRuntime(opts.runtime, settings);
+	const deviceFlag = opts.device;
+	const physical = isPhysicalDeviceRequest(deviceFlag);
+	if (physical && deviceFlag === "") return fail({
+		code: "STIM_BAD_ARG",
+		message: "--device was given an empty UDID.",
+		remedy: "Pass `--device` on its own to take the first connected device this workspace can lease, or `--device <udid>` to name one."
+	});
+	if (physical && opts.remote) return fail({
+		code: "STIM_BAD_ARG",
+		message: "--device builds for a phone connected to this machine, and --remote installs on a remote one.",
+		remedy: "Pass only one of --device and --remote."
+	});
+	const wait = resolveIosWait(opts, physical);
+	if ("failure" in wait) return fail(wait.failure);
+	const { waitSeconds, noWait, deviceSlotWaitMs, checkCapacity } = wait;
+	const deviceSlotWait = {
+		automatic: false,
+		waitMs: deviceSlotWaitMs,
+		displayName: basename(root),
+		...deviceWaitRun.policy,
+		onWait: (ms) => {
+			deviceWaitRun.policy.onWait?.(ms);
+			if (devicePlacement?.decision === "local" && ms > 0) devicePlacement.decision = "waited-locally";
+		}
+	};
+	const isExpo = integration.isExpo;
+	const schemeRefusal = integration.schemeProblem(buildScheme);
+	if (schemeRefusal) return fail(schemeRefusal);
+	const capabilityRefusal = iosProjectTargetRefusal(integration, {
+		physical,
+		easProfile: opts.easProfile
+	});
+	if (capabilityRefusal) return fail(capabilityRefusal);
+	const remoteSelection = await selectIosPlacement({
+		root,
+		slot,
+		opts,
+		settings,
+		physical,
+		release,
+		metroCheck,
+		d,
+		deviceType,
+		runtime,
+		validateSelectors: () => deviceModelRefusal({
+			slot,
+			deviceTypeFlag: opts.deviceType,
+			runtimeFlag: opts.runtime,
+			deviceType,
+			runtime,
+			physical,
+			remoteBackend: null,
+			deviceTypeOrigin: d.settingOriginScope(d.settingsLayers(settingsContext), "ios.deviceType"),
+			runtimeOrigin: d.settingOriginScope(d.settingsLayers(settingsContext), "ios.runtime"),
+			listRuntimes: d.listIosRuntimes
+		}),
+		noWait: deviceSlotWaitMs === 0,
+		note,
+		phase,
+		log: (entry) => logWriter().write(entry)
+	});
+	if ("failure" in remoteSelection) return fail(remoteSelection.failure);
+	deviceSlotWait.automatic = Boolean(remoteSelection.auto);
+	const targetRefusal = iosProjectTargetRefusal(integration, {
+		physical,
+		placement: remoteSelection
+	});
+	if (targetRefusal) return fail(targetRefusal);
+	devicePlacement = remoteSelection.devicePlacement;
+	writeDevicePlacement(root, slot, "ios", devicePlacement);
+	const { machine: hostedMachine, backend: remoteBackend } = remoteSelection;
+	const viewer = resolveSimulatorAppFlag(opts.simulatorApp, physical, hostedMachine ?? remoteBackend, Boolean(remoteSelection.auto));
+	if ("refusal" in viewer) return fail(viewer.refusal);
+	const { simulatorApp } = viewer;
+	const settingsLayersForOrigin = d.settingsLayers(settingsContext);
+	const modelRefusal = deviceModelRefusal({
+		slot,
+		deviceTypeFlag: opts.deviceType,
+		runtimeFlag: opts.runtime,
+		deviceType,
+		runtime,
+		deviceTypeOrigin: d.settingOriginScope(settingsLayersForOrigin, "ios.deviceType"),
+		runtimeOrigin: d.settingOriginScope(settingsLayersForOrigin, "ios.runtime"),
+		physical,
+		remoteBackend,
+		hosted: Boolean(hostedMachine),
+		listRuntimes: d.listIosRuntimes
+	});
+	if (modelRefusal) return fail(modelRefusal);
+	const selectors = hostedIosSelectors(deviceType, runtime);
+	const connected = await connectIosTarget(remoteSelection, selectors, d);
+	if ("failure" in connected) return fail(connected.failure);
+	const hostedTarget = connected.target;
+	try {
+		const simSnapshot = createIosSimSnapshot();
+		const budget = await iosPlacementBudget(d, root, note, Boolean(hostedTarget), remoteSelection.budget, simSnapshot);
+		reclaimed = budget.reclaimed;
+		if (budget.refusal) return fail(budget.refusal);
+		const backendConnection = await connectIosBackend(root, remoteBackend, opts.deviceType, d);
+		if ("failure" in backendConnection) return fail(backendConnection.failure);
+		const remoteDevice = backendConnection.remote;
+		const remoteArch = hostedTarget ? hostedTarget.choice.architecture : backendConnection.arch;
+		if (remoteDevice) d = {
+			...d,
+			checkDeviceCapacity: remoteDevice.checkDeviceCapacity,
+			ensureOwnedDevice: remoteDevice.ensureOwnedDevice,
+			ensureBooted: remoteDevice.ensureBooted,
+			installIosApp: remoteDevice.installIosApp,
+			launchIosApp: remoteDevice.launchIosApp
+		};
+		const easBuild = await d.resolveEasDevelopmentBuild({
+			root,
+			platform: "ios",
+			profile: opts.easProfile,
+			note,
+			isExpo,
+			physical,
+			selectors: [opts.scheme, opts.configuration],
+			buildCache: opts.buildCache
+		});
+		if (isEasBuildFailure(easBuild)) return fail(easBuild);
+		const registerProject = () => d.upsertProject(root, {
+			bundleId: integration.bundleId() ?? void 0,
+			isExpo
+		});
+		if (remoteBackend !== "eas") registerProject();
+		const proj = d.getProject(root);
+		const limits = d.getConcurrencyLimits();
+		let physicalDevice = null;
+		let wireless = false;
+		if (physical && typeof deviceFlag !== "string") {
+			const pooled = await d.selectFromPool({
+				root,
+				platform: "ios",
+				idLabel: "udid",
+				list: () => iosPoolCandidates(d.listIosDevices()).map((entry) => ({
+					id: entry.udid,
+					name: entry.name,
+					fallback: isWirelessIosDevice(entry)
+				})),
+				noCandidates: () => {
+					const resolved = iosPoolNoCandidatesRefusal(d.listIosDevices());
+					return {
+						message: resolved.error,
+						remedy: resolved.remedy
+					};
+				},
+				waitSeconds,
+				noWait,
+				now: d.now,
+				warn: (line) => note(chalk.yellow(phaseLine("lease", line)))
+			});
+			if (pooled.status === "refused") return fail({
+				code: pooled.refusal.code,
+				message: pooled.refusal.message,
+				remedy: pooled.refusal.remedy,
+				...pooled.refusal.lease === null ? {} : { lease: pooled.refusal.lease }
+			});
+			physicalDevice = {
+				udid: pooled.candidate.id,
+				name: pooled.candidate.name ?? pooled.candidate.id
+			};
+			wireless = pooled.candidate.fallback === true;
+		} else if (physical) {
+			const resolved = resolveIosPhysicalDevice(typeof deviceFlag === "string" ? deviceFlag : null, d.listIosDevices());
+			if (!resolved.udid) return fail({
+				code: "STIM_NO_DEVICE",
+				message: resolved.error,
+				remedy: resolved.remedy
+			});
+			physicalDevice = {
+				udid: resolved.udid,
+				name: resolved.name ?? resolved.udid
+			};
+			wireless = resolved.wireless === true;
+		}
+		if (checkCapacity && !hostedTarget) {
+			const capacity = d.checkDeviceCapacity({
+				platform: "ios",
+				project: proj,
+				max: limits.maxDevices,
+				sims: () => simSnapshot.read().filter((sim) => sim.available)
+			});
+			if (capacity) {
+				if (capacity.code === "STIM_AT_CAPACITY") d.recordCapacityRefusal({
+					platform: "ios",
+					max: limits.maxDevices,
+					workspace: workspaceId(root)
+				}, d.now());
+				return fail(capacity);
+			}
+		}
+		let metroPort = proj?.metroPort ?? null;
+		let lanAddress = null;
+		let lanOriginUrl = null;
+		let devServer = null;
+		const appRuntime = composeRuntime();
+		const preparation = await appRuntime.prepare();
+		if (!preparation.ok) return fail(preparation.error);
+		const runtimePreparation = preparation.prepared;
+		metroPort = runtimePreparation.metroPort;
+		let device;
+		if (physicalDevice) device = {
+			deviceUdid: physicalDevice.udid,
+			deviceName: physicalDevice.name,
+			owned: false
+		};
+		else if (hostedTarget) device = {
+			owned: false,
+			deviceName: hostedTarget.choice.deviceType,
+			runtime: hostedTarget.choice.runtime
+		};
+		else {
+			const prepare = stepClock(d.now);
+			try {
+				device = await d.ensureOwnedDevice({
+					platform: "ios",
+					project: proj,
+					projectPath: root,
+					settingsRoot: root,
+					settings,
+					flags: {
+						deviceSlotWait,
+						deviceType,
+						runtime,
+						runtimeFlag: resolveRuntime(opts.runtime, null),
+						simulatorApp
+					},
+					note,
+					out: note,
+					simSnapshot
+				});
+			} catch (e) {
+				return fail(ownedSimFailure(e));
+			}
+			deviceWaitRun.booting(device.booting);
+			progress.deviceSetup(didSetUpDevice(device, Boolean(remoteDevice)));
+			const prepareMs = prepare();
+			if (device.created || prepareMs >= 2e3) phase("device", `${deviceLabel(device, device.deviceUdid)} ${device.created ? "created" : "prepared"} (${formatDuration(prepareMs)})`);
+		}
+		let bootDuration = "";
+		let bootPromise;
+		let udid = "";
+		function composeRuntime() {
+			return d.runtimePlan ?? integration.runtime({
+				configuration,
+				prepareMetro,
+				prepareEmbedded: async () => {
+					phase("metro", `skipped (${configuration}: the JS bundle is embedded, no dev server is used)`);
+					hostedIosMetroNote(Boolean(hostedTarget), settings, note, opts.simulatorApp);
+					return {
+						ok: true,
+						prepared: { metroPort: null }
+					};
+				}
+			});
+		}
+		async function prepareMetro() {
+			if (metroCheck) {
+				const gate = await ensureDevServer({
+					root,
+					port: metroPort,
+					settings: hostedMetroSettings(settings, Boolean(hostedTarget)),
+					remote: Boolean(remoteDevice),
+					note,
+					resolve: d.resolveProjectMetro,
+					start: d.startDevServer,
+					readState: d.readWorkspaceState
+				});
+				reclaimed = [...reclaimed, ...gate.reclaimed];
+				if (!gate.ok) return {
+					ok: false,
+					error: {
+						code: gate.code,
+						message: gate.message,
+						remedy: gate.remedy,
+						lines: gate.lines
+					}
+				};
+				metroPort = gate.port;
+				devServer = gate.devServer;
+			} else {
+				const pin = metroPortSetting(root);
+				if (pin.error) return {
+					ok: false,
+					error: {
+						code: "STIM_BAD_ARG",
+						message: pin.error,
+						remedy: SETTING_SHAPE_REMEDY
+					}
+				};
+				if (pin.port === null && !metroPort) note(chalk.yellow(`No Metro port is reserved for this workspace; wiring the app to ${DEFAULT_METRO_PORT}.`));
+				metroPort = pin.port ?? metroPort ?? 8081;
+			}
+			hostedIosMetroNote(Boolean(hostedTarget), settings, note, opts.simulatorApp);
+			if (physical && metroPort !== null) {
+				const error = await resolveLanOrigin();
+				if (error) return {
+					ok: false,
+					error
+				};
+			}
+			if (remoteDevice && metroPort !== null) {
+				const reachable = await d.ensureMetroReachable({
+					ctx: remoteDevice.ctx,
+					metroPort,
+					isExpo,
+					tunnelMode: tunnelModeSetting(settings) ?? void 0,
+					publicUrl: publicUrlSetting(settings),
+					available: d.detectProviders(binOnPath, tunnelModeSetting(settings) ?? "auto")
+				});
+				if ("failed" in reachable) return {
+					ok: false,
+					error: {
+						code: reachable.code ?? "STIM_NO_REMOTE_SESSION",
+						message: reachable.failed,
+						remedy: reachable.remedy
+					}
+				};
+			}
+			if (metroCheck && optimizations.metroWarmup) d.warmMetro({
+				port: metroPort,
+				platform: "ios",
+				isExpo,
+				appId: proj?.bundleId,
+				bundleUrl: metroWarmupUrlSetting(settings, "ios")
+			});
+			return {
+				ok: true,
+				prepared: { metroPort }
+			};
+		}
+		async function resolveLanOrigin() {
+			const port = metroPort;
+			const pinned = iosLanHostSetting(settings);
+			const candidates = d.hostLanCandidates();
+			const chosen = chooseLanAddress({
+				pinned,
+				candidates
+			});
+			if (!chosen) return {
+				code: "STIM_NO_LAN_ADDRESS",
+				message: "A Debug run on a phone needs an address the phone can reach, and this Mac has no non-internal IPv4 interface.",
+				remedy: "The phone reaches Metro over the network you share, because USB carries no reverse forward. Join a Wi-Fi or Ethernet network, or connect this Mac by cable, then run the command again."
+			};
+			lanAddress = chosen.address;
+			lanOriginUrl = lanOriginUrlFor(chosen.address, port);
+			const source = chosen.pinned ? "ios.lanHost" : `${chosen.interfaceName ?? "interface"}${chosen.candidates > 1 ? ` of ${chosen.candidates} candidates` : ""}`;
+			phase("lan", `${lanOriginUrl} (${source})`);
+			if (publicUrlSetting(settings) || tunnelModeSetting(settings)) note(chalk.dim(phaseLine("lan", "metro.publicUrl and metro.tunnel are ignored on --device: neither channel to a phone carries a URL, only a host and a port. They still apply to --remote.")));
+			if (!metroCheck) return null;
+			const reachable = await d.ensureLanReachable({
+				origin: lanOriginUrl,
+				metroPort: port,
+				root,
+				isExpo,
+				logsDir
+			});
+			if ("failed" in reachable) return {
+				code: "STIM_LAN_METRO_UNREACHABLE",
+				message: reachable.failed,
+				remedy: reachable.remedy
+			};
+			phase("lan", `gated: ${lanOriginUrl} answered as this workspace's Metro`);
+			return null;
+		}
+		let artifact = null;
+		try {
+			const boot = () => physicalDevice ? Promise.resolve({
+				ok: true,
+				udid: physicalDevice.udid
+			}) : Promise.resolve(d.ensureBooted({
+				platform: "ios",
+				device,
+				projectPath: root,
+				deviceSlotWait,
+				simulatorApp,
+				out: note
+			})).catch((e) => ({
+				ok: false,
+				reason: String(e?.message || e)
+			}));
+			const startBoot = () => {
+				const bootTimer = stepTimer(d.now);
+				bootPromise = (remoteDevice?.ctx.backend === "eas" ? d.ensureRemoteBootOwned({
+					root,
+					platform: "ios",
+					sessionName: ownedSessionName(remoteDevice.ctx.label),
+					startedAt: new Date(d.now()).toISOString(),
+					deviceType: remoteDevice.ctx.deviceType ?? null,
+					boot,
+					createdSessionId: remoteDevice.createdSessionId,
+					abandonCreatedSession: remoteDevice.abandonCreatedSession,
+					webPreviewUrl: remoteDevice.webPreviewUrl,
+					writeState: d.writeWorkspaceState,
+					register: registerProject,
+					notice: (line) => note(chalk.dim(phaseLine("lock", line)))
+				}) : boot()).then((result) => {
+					bootDuration = bootTimer();
+					return result;
+				});
+				deviceWaitRun.booting({ done: bootPromise });
+				return bootPromise.then((result) => result?.udid ?? "");
+			};
+			const localBoot = remoteDevice || hostedTarget ? null : startBoot();
+			udid = device.deviceUdid ?? await localBoot ?? "";
+			const simulatorArch = simulatorBuildArch({
+				physical,
+				remoteArch,
+				hostArch: d.hostSimulatorArch(),
+				configuration
+			});
+			const acquiredArtifact = unlessCancelled(await acquireIosArtifact({
+				root,
+				logFile,
+				configuration,
+				buildMachine,
+				physical,
+				recipe: integration.artifact({
+					root,
+					logFile,
+					configuration,
+					buildScheme,
+					buildProfile,
+					...iosArtifactTargetInputs({
+						udid,
+						physical,
+						remote: Boolean(remoteDevice),
+						hosted: hostedTarget,
+						simulatorArch,
+						lanAddress,
+						metroPort,
+						settings
+					}),
+					optimizations: optimizations.ios,
+					easProfile: opts.easProfile,
+					cache: cachePolicy,
+					phase,
+					note,
+					logWriter,
+					estimates,
+					step: progress.step,
+					setPodsMs: (ms) => stats.setPodsMs(ms)
+				}),
+				cache: {
+					policy: cachePolicy,
+					providerConfig: cacheProviderConfig,
+					disabledByFlag: opts.buildCache === false
+				},
+				easBuild,
+				maxBuilds: limits.maxBuilds,
+				progress: {
+					phase,
+					note,
+					logWriter,
+					stats,
+					step: progress.step,
+					miss: progress.miss,
+					hit: progress.hit,
+					place: progress.place,
+					waitingOn: progress.waitingOn,
+					waitingFor: progress.waitingFor
+				}
+			}, d));
+			if (!acquiredArtifact.ok) {
+				compilationCache = acquiredArtifact.compilationCache;
+				return fail(acquiredArtifact.failure);
+			}
+			artifact = acquiredArtifact.artifact;
+			compilationCache = artifact.cache.compilation;
+			if (hostedTarget) return await finishHostedIosRun({
+				target: hostedTarget,
+				root,
+				slot,
+				d,
+				artifact,
+				configuration,
+				buildScheme,
+				release,
+				isExpo,
+				metroCheck,
+				metroPort,
+				logsDir,
+				json,
+				elapsed,
+				startedAt,
+				closeWriter: () => writer?.close(),
+				devicePlacement,
+				recordRun,
+				reclaimed,
+				devServer,
+				fail,
+				note,
+				enterPhase: progress.step,
+				selectors
+			});
+			if (!localBoot) {
+				progress.step("device");
+				udid = await startBoot();
+			}
+			if (physicalDevice) {
+				progress.step("device");
+				const acquired = await d.acquireRunLease({
+					root,
+					platform: "ios",
+					id: physicalDevice.udid,
+					deviceName: physicalDevice.name,
+					idLabel: "udid",
+					waitSeconds,
+					noWait,
+					installBoundMs: iosDeviceBounds(wireless).installMs,
+					appId: artifact.bundleId ?? proj?.bundleId ?? null,
+					holderAppId: (holder) => d.getProject(holder)?.bundleId ?? null,
+					now: d.now,
+					warn: (line) => note(chalk.yellow(phaseLine("lease", line)))
+				});
+				if (acquired.status === "refused") return fail({
+					code: acquired.refusal.code,
+					message: acquired.refusal.message,
+					remedy: acquired.refusal.remedy,
+					lease: acquired.refusal.lease
+				});
+				leaseHandle = d.runLease({
+					root,
+					platform: "ios",
+					kind: acquired.status === "leased" ? acquired.kind : null,
+					expiresAt: acquired.status === "leased" ? acquired.expiresAt : null
+				});
+				if (acquired.status === "leased") {
+					stopLeaseSignals = d.releaseLeaseOnSignal(releaseLease);
+					phase("lease", `${acquired.kind} lease on ${physicalDevice.udid} until ${leaseExpiryText(acquired.expiresAt, d.now())}`);
+				}
+			}
+			try {
+				return await finishIosRun({
+					projectBundleId: integration.bundleId,
+					runtime: appRuntime,
+					runtimePreparation,
+					slot,
+					d,
+					root,
+					json,
+					release,
+					configuration,
+					buildScheme,
+					isExpo,
+					metroCheck,
+					metroPort,
+					logsDir,
+					logFile,
+					device,
+					udid,
+					physical,
+					wireless,
+					lanAddress,
+					lanOriginUrl,
+					remoteDevice,
+					bootPromise,
+					bootDuration: () => bootDuration,
+					artifact,
+					fail,
+					phase,
+					note,
+					logWriter,
+					elapsed,
+					startedAt,
+					closeWriter: () => writer?.close?.(),
+					lease: leaseHandle,
+					releaseLease,
+					devicePlacement,
+					recordRun,
+					reclaimed,
+					devServer,
+					enterPhase: progress.step
+				});
+			} finally {
+				releaseLease();
+			}
+		} catch (error) {
+			recordRun({
+				failed: true,
+				durationMs: elapsed()
+			});
+			throw error;
+		} finally {
+			artifact?.release();
+		}
+	} finally {
+		await deviceWaitRun.finish();
+		hostedTarget?.host.connection.close();
+	}
+}
+//#endregion
+export { registerIos as n, runIosOperation as r, iosCommand as t };