stim 1.0.0 → 1.2.0

package/dist/ios-B7KLgIp5.mjs

@@ -0,0 +1,2733 @@
+import { t as getExecutor } from "./exec-CyylIdq9.mjs";
+import { S as upsertProject, f as getProject, l as getConcurrencyLimits } from "./config-CMtIaTk9.mjs";
+import { r as createNdjsonWriter } from "./ndjson-DcAtEx_K.mjs";
+import { D as workspaceLogsDir, T as workspaceDir, _ as writeWorkspaceState, g as writeWorkspaceLaunch, n as MODE_EXPO, p as readWorkspaceState, t as MODE_BARE } from "./state-CZ-ER-8d.mjs";
+import { C as removeTemporaryEntry, S as makeTemporaryDirectory, g as repoRoot, s as gitCommonDir } from "./worktree-C79xx_kM.mjs";
+import { a as findProjectRoot, c as projectShortcut, i as detectIsExpo, r as detectBundleId, t as appProjectProblem } from "./project-BBTVABUz.mjs";
+import { i as resolveProjectMetro, r as pidExists } from "./metro-COslRK_F.mjs";
+import { n as verifyCollectorOwnership } from "./ownership-CGPart6T.mjs";
+import { a as easAuthNote, c as loadProjectProvider, d as resolveEasCliBin, f as resolveRemote, i as checkEasAuth, n as UPLOAD_TIMEOUT_MS, o as exitAfterFlush, p as uploadRemote, r as cacheLevel, s as isEasAuthFailureText, t as RESOLVE_TIMEOUT_MS, v as POOL_SETTING_REMEDY, x as parkedMaxSetting } from "./remote-cache-DDmJ1Roq.mjs";
+import { A as resolveSettings, B as artifactCachePolicy, D as remoteDeviceSettingError, F as tunnelModeSetting, H as optimizationBuildProfile, I as unknownSettingKeys, N as settingShapeErrors, O as remoteIosSetting, R as detectProviders, T as publicUrlSetting, U as resolveOptimizations, _ as iosSigningIdentitySha1SettingError, a as SETTING_SHAPE_REMEDY, d as cacheProviderSettingError, f as iosLanHostSetting, g as iosSigningIdentitySha1Setting, h as iosSigningIdentitySettingError, k as resolveCacheProviderConfig, m as iosSigningIdentitySetting, p as iosLanHostSettingError, r as REMOTE_DEVICE_BACKENDS, x as metroWarmupUrlSetting } from "./settings-DwU1_U_q.mjs";
+import { _ as launchErrorPreview, c as launchErrorReport, g as stepTimer, h as stepClock, i as formatDuration, l as phaseLine, m as shortUdid, n as appReadinessMessage, p as shortHash } from "./command-output-8wHMEde0.mjs";
+import { C as launchIosApp, E as unverifiedLaunchLines, O as verifyLaunch, T as readMetroRecords, b as isBundleProof, c as RELEASE_VERIFY_WAIT_MS, f as clearOtherUserApps, i as LAUNCH_BUNDLING, k as verifyReleaseLaunch, m as devClientUrl, n as DEFAULT_METRO_PORT, o as LAUNCH_FATAL, s as LAUNCH_UNVERIFIED, v as installIosApp, w as readCollectorRecords, y as iosAppProcess } from "./app-install-NFxUahnH.mjs";
+import { f as listIosRuntimes } from "./ios-D1h1Di39.mjs";
+import { C as untrackedNativeFiles, S as untrackedMissLine, _ as providerUploadOutcome, b as storeBuild, c as buildCacheKey, d as filesystemBuildCapability, f as fingerprintDiffRecord, g as providerDownloadPath, h as prepareProviderDownloadDir, i as releaseBuildLock, l as describeFingerprintMiss, m as fingerprintProject, n as acquireBuildLock, o as takeoverLine, p as fingerprintDiffSuffix, s as waitForBuild, t as WAIT_CEILING_MS, v as refingerprintAfterMutation, y as resolveBuild } from "./build-lock-BsVoLDaq.mjs";
+import { r as claimFailure } from "./ownership-claim-7zRxxTfZ.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-B5pEVa3t.mjs";
+import { r as releaseBuildSlot, t as acquireBuildSlot } from "./build-slots-D0b6sJyo.mjs";
+import { a as swapJsBundle, c as ensureWorkspaceStorageSafely, d as noMetroMessage, f as noMetroRemedy, h as warmMetro, l as gateShouldRetry, m as sleep, n as pickDevClientScheme, o as needsPrebuild, p as resolveMetroWithRetry, r as schemesFromInfoPlist, s as runPrebuild, t as devClientScheme, u as launchOutcomeRecord } from "./dev-client-RpvXxCXV.mjs";
+import { a as statsProjectKey, i as recordRunStats, n as readRunEstimates, t as createRunRecorder } from "./stats-BCWEVLrM.mjs";
+import { T as unknownIosRuntimeRefusal, b as ensureBooted, c as discoverXcodeProject, d as resolveScheme, i as buildIos, l as readBundleExecutable, m as describeDiagnostic, n as COMPILATION_CACHE_UNAVAILABLE, o as compilationCacheActivityLine, t as COMPILATION_CACHE_NOT_RUN, u as readBundleId, v as checkDeviceCapacity, w as unknownIosDeviceTypeRefusal, x as ensureOwnedDevice, y as clearIosAdoptionPending } from "./xcode-DeKCribl.mjs";
+import { a as ensureMetroReachable, b as ownedSessionName, c as remoteIosDeps, l as resolveRemoteContext, n as binOnPath, o as ensureRemoteBootOwned, r as bundleEntryPoint, w as gateMetroOrigin } from "./device-remote-E81KAdXf.mjs";
+import { t as spawnEntry } from "./spawn-entry-nCE6m770.mjs";
+import { a as printNativeCrashReport, n as IOS_CRASH_REPORT_RETRY, o as simulatorConsolePaths, r as captureNativeCrashes, t as errorDiagnostics } from "./error-diagnostics-Dw8Gn3yw.mjs";
+import { a as iosDeviceProcess, c as listIosDevices, d as verifyIosDeviceReleaseLaunch, i as installIosDeviceApp, l as localNetworkPending, n as LAUNCH_PROBE_TIMEOUT_MS, o as iosPoolCandidates, r as awaitIosDeviceLaunch, s as iosPoolNoCandidatesRefusal, t as DEVICECTL_INSTALL_TIMEOUT_MS, u as resolveIosPhysicalDevice } from "./ios-device-xNt0Lg6v.mjs";
+import { a as runPodInstall, n as podsAreStale, r as readPodState } from "./deps-BLBsTNDS.mjs";
+import { existsSync, mkdirSync, mkdtempSync, openSync, rmSync, writeFileSync } from "node:fs";
+import { InvalidArgumentError } from "commander";
+import { X509Certificate } from "node:crypto";
+import { basename, join } from "node:path";
+import { networkInterfaces, tmpdir } from "node:os";
+import chalk from "chalk";
+import { createWarnOnce, loadCacheProvider, resolveTieredBuild, storeTieredBuild } from "@stim-cli/cache";
+//#region src/engine/ios-profile.ts
+const TAG = /<(\/?)\s*([A-Za-z0-9_]+)(?:\s[^>]*?)?(\/?)>/g;
+const ENTITIES = {
+	amp: "&",
+	lt: "<",
+	gt: ">",
+	quot: "\"",
+	apos: "'"
+};
+var PlistError = class extends Error {};
+function codePoint(value) {
+	if (!Number.isInteger(value) || value < 0 || value > 1114111 || value >= 55296 && value <= 57343) throw new PlistError(`character reference out of range: ${value}`);
+	return String.fromCodePoint(value);
+}
+function decodeEntities(raw) {
+	return raw.replace(/&(#x?[0-9A-Fa-f]+|[a-z]+);/g, (match, body) => {
+		if (body.startsWith("#x") || body.startsWith("#X")) return codePoint(Number.parseInt(body.slice(2), 16));
+		if (body.startsWith("#")) return codePoint(Number.parseInt(body.slice(1), 10));
+		return ENTITIES[body] ?? match;
+	});
+}
+function peekTag(cursor) {
+	TAG.lastIndex = cursor.pos;
+	const match = TAG.exec(cursor.xml);
+	if (!match) return null;
+	return {
+		name: (match[2] ?? "").toLowerCase(),
+		closing: match[1] === "/",
+		selfClosing: match[3] === "/",
+		end: TAG.lastIndex
+	};
+}
+function takeTag(cursor) {
+	const tag = peekTag(cursor);
+	if (tag) cursor.pos = tag.end;
+	return tag;
+}
+function takeText(cursor, name) {
+	const close = cursor.xml.indexOf(`</${name}>`, cursor.pos);
+	if (close < 0) {
+		cursor.pos = cursor.xml.length;
+		return "";
+	}
+	const raw = cursor.xml.slice(cursor.pos, close);
+	cursor.pos = close + name.length + 3;
+	return raw;
+}
+function parseValue(cursor) {
+	const peeked = peekTag(cursor);
+	if (!peeked || peeked.closing) return void 0;
+	const tag = takeTag(cursor);
+	if (tag.selfClosing) {
+		if (tag.name === "true") return true;
+		if (tag.name === "false") return false;
+		if (tag.name === "array") return [];
+		if (tag.name === "dict") return {};
+		return "";
+	}
+	switch (tag.name) {
+		case "plist": return parseValue(cursor);
+		case "dict": {
+			const out = {};
+			for (;;) {
+				const next = peekTag(cursor);
+				if (!next) break;
+				if (next.closing) {
+					cursor.pos = next.end;
+					break;
+				}
+				cursor.pos = next.end;
+				if (next.name !== "key") continue;
+				const key = decodeEntities(next.selfClosing ? "" : takeText(cursor, "key"));
+				const value = parseValue(cursor);
+				if (value !== void 0) out[key] = value;
+			}
+			return out;
+		}
+		case "array": {
+			const out = [];
+			for (;;) {
+				const next = peekTag(cursor);
+				if (!next) break;
+				if (next.closing) {
+					cursor.pos = next.end;
+					break;
+				}
+				const value = parseValue(cursor);
+				if (value === void 0) break;
+				out.push(value);
+			}
+			return out;
+		}
+		case "string":
+		case "key": return decodeEntities(takeText(cursor, tag.name));
+		case "integer": return Number.parseInt(takeText(cursor, "integer").trim(), 10);
+		case "real": return Number.parseFloat(takeText(cursor, "real").trim());
+		case "date": return new Date(takeText(cursor, "date").trim());
+		case "data": return Buffer.from(takeText(cursor, "data").replace(/\s+/g, ""), "base64");
+		case "true":
+			takeText(cursor, "true");
+			return true;
+		case "false":
+			takeText(cursor, "false");
+			return false;
+		default:
+			takeText(cursor, tag.name);
+			return "";
+	}
+}
+function parsePlist(xml) {
+	if (typeof xml !== "string" || xml.trim() === "") return null;
+	const stripped = xml.replace(/<!--[\s\S]*?-->/g, "");
+	const start = stripped.indexOf("<plist");
+	const cursor = {
+		xml: stripped,
+		pos: start < 0 ? 0 : start
+	};
+	try {
+		const value = parseValue(cursor);
+		return value === void 0 ? null : value;
+	} catch {
+		return null;
+	}
+}
+function isDict(value) {
+	return value !== null && typeof value === "object" && !Array.isArray(value) && !Buffer.isBuffer(value) && !(value instanceof Date);
+}
+function stringsOf(value) {
+	if (!Array.isArray(value)) return null;
+	return value.filter((v) => typeof v === "string");
+}
+function parseProvisioningProfilePlist(xml) {
+	const root = parsePlist(xml);
+	if (!isDict(root)) return null;
+	const entitlements = isDict(root.Entitlements ?? null) ? root.Entitlements : {};
+	const teamIdentifier = stringsOf(root.TeamIdentifier);
+	const expiration = root.ExpirationDate;
+	const certificates = Array.isArray(root.DeveloperCertificates) ? root.DeveloperCertificates.filter((v) => Buffer.isBuffer(v)) : [];
+	return {
+		name: typeof root.Name === "string" ? root.Name : null,
+		uuid: typeof root.UUID === "string" ? root.UUID : null,
+		teamIdentifier: teamIdentifier?.[0] ?? null,
+		expirationDate: expiration instanceof Date && !Number.isNaN(expiration.getTime()) ? expiration : null,
+		provisionedDevices: stringsOf(root.ProvisionedDevices),
+		provisionsAllDevices: root.ProvisionsAllDevices === true,
+		getTaskAllow: entitlements["get-task-allow"] === true,
+		certificates
+	};
+}
+function provisioningProfileKind(profile) {
+	if (profile.provisionedDevices) return profile.getTaskAllow ? "development" : "ad hoc";
+	return profile.provisionsAllDevices ? "enterprise" : "App Store";
+}
+function certificateCommonName(der) {
+	if (!Buffer.isBuffer(der) || der.length === 0) return null;
+	let subject;
+	try {
+		subject = new X509Certificate(der).subject;
+	} catch {
+		return null;
+	}
+	for (const part of String(subject).split(/\r?\n/)) {
+		const trimmed = part.trim();
+		if (trimmed.startsWith("CN=")) return trimmed.slice(3).trim() || null;
+	}
+	return /(?:^|,)\s*CN=([^,]+)/.exec(String(subject))?.[1]?.trim() || null;
+}
+const IDENTITY_LINE = /^\s*\d+\)\s+([0-9A-Fa-f]{40})\s+"(.+)"\s*$/;
+function parseSigningIdentities(text) {
+	if (typeof text !== "string") return [];
+	const out = [];
+	for (const line of text.split(/\r?\n/)) {
+		const match = IDENTITY_LINE.exec(line);
+		if (!match) continue;
+		out.push({
+			sha1: match[1].toUpperCase(),
+			name: match[2]
+		});
+	}
+	return out;
+}
+const SIGNING_CODES = {
+	noProfile: "STIM_NO_PROFILE",
+	profileMismatch: "STIM_PROFILE_MISMATCH",
+	noIdentity: "STIM_NO_SIGNING_IDENTITY",
+	codesignFailed: "STIM_CODESIGN_FAILED"
+};
+const XCODE_STEP = "build once from Xcode to install it -- Stim will not, because registering a device or minting a profile changes your Apple Developer account.";
+const KEYCHAIN_REMEDY = "Open Xcode > Settings > Accounts and download your certificates, or unlock the login keychain with `security unlock-keychain`. `security find-identity -v -p codesigning` should list `Apple Development: ...`.";
+function signingConfiguration(input) {
+	return input.configuration ?? "Debug";
+}
+function profileGate(input) {
+	const now = input.now ?? Date.now();
+	if (!input.profilePresent) return {
+		ok: false,
+		code: SIGNING_CODES.noProfile,
+		reason: "The app bundle has no embedded.mobileprovision, so it was built unsigned or for the simulator.",
+		remedy: `Set a team and profile for the target's ${signingConfiguration(input)} configuration in Xcode > Signing & Capabilities, then ${XCODE_STEP}`
+	};
+	if (!input.profile) return {
+		ok: false,
+		code: SIGNING_CODES.noProfile,
+		reason: "`security cms -D` could not decode the app bundle's embedded.mobileprovision.",
+		remedy: `The profile inside the app is corrupt. Delete the build cache entry with \`stim gc --delete\`, then ${XCODE_STEP}`
+	};
+	const profile = input.profile;
+	const named = profile.name ? `"${profile.name}"` : "the embedded profile";
+	if (!profile.expirationDate || profile.expirationDate.getTime() <= now) return {
+		ok: false,
+		code: SIGNING_CODES.profileMismatch,
+		reason: profile.expirationDate ? `The ${provisioningProfileKind(profile)} profile ${named} expired on ${profile.expirationDate.toISOString()}.` : `The ${provisioningProfileKind(profile)} profile ${named} carries no ExpirationDate, so Stim cannot prove it is still valid.`,
+		remedy: `Renew the profile under Signing & Capabilities, then ${XCODE_STEP}`
+	};
+	if (!profile.provisionedDevices) {
+		const kind = provisioningProfileKind(profile);
+		return {
+			ok: false,
+			code: SIGNING_CODES.profileMismatch,
+			reason: `${named} is an ${kind} profile, which carries no ProvisionedDevices list, so Stim cannot prove ${input.udid ?? "the target device"} is admitted.`,
+			remedy: `Local device runs need a development profile. Select one under Signing & Capabilities, then ${XCODE_STEP}`
+		};
+	}
+	const udid = input.udid;
+	if (!udid || !profile.provisionedDevices.some((d) => d.toLowerCase() === udid.toLowerCase())) return {
+		ok: false,
+		code: SIGNING_CODES.profileMismatch,
+		reason: `The ${provisioningProfileKind(profile)} profile ${named} lists ${profile.provisionedDevices.length} device(s) and ${udid ?? "the target device"} is not one of them.`,
+		remedy: `Register ${udid ?? "the device"} at developer.apple.com, regenerate the profile, then ${XCODE_STEP}`
+	};
+	return {
+		ok: true,
+		profile
+	};
+}
+function signingGate(input) {
+	const gated = profileGate(input);
+	if (!gated.ok) return gated;
+	const profile = gated.profile;
+	const named = profile.name ? `"${profile.name}"` : "the embedded profile";
+	const identities = Array.isArray(input.identities) ? input.identities : [];
+	if (identities.length === 0) return {
+		ok: false,
+		code: SIGNING_CODES.noIdentity,
+		reason: "`security find-identity -v -p codesigning` lists no codesigning identity on this machine.",
+		remedy: KEYCHAIN_REMEDY
+	};
+	if (input.pinnedSha1) {
+		const wanted = input.pinnedSha1.trim().toUpperCase();
+		const match = identities.find((i) => i.sha1 === wanted);
+		if (match) return {
+			ok: true,
+			identity: match
+		};
+		return {
+			ok: false,
+			code: SIGNING_CODES.noIdentity,
+			reason: `ios.signingIdentitySha1 is ${wanted}, which is not in the keychain. Available: ${identities.map((i) => `${i.sha1} "${i.name}"`).join(", ")}.`,
+			remedy: KEYCHAIN_REMEDY
+		};
+	}
+	const wantedName = input.pinnedName?.trim() || certificateCommonName(profile.certificates[0] ?? null);
+	if (!wantedName) return {
+		ok: false,
+		code: SIGNING_CODES.noIdentity,
+		reason: `Stim could not read a signing-identity name out of ${named}: its DeveloperCertificates entry has no readable subject CN.`,
+		remedy: "Set ios.signingIdentity in .stim.json to the identity name to re-sign with, or ios.signingIdentitySha1 to its SHA-1 hash."
+	};
+	const matches = identities.filter((i) => i.name === wantedName);
+	if (matches.length === 1) return {
+		ok: true,
+		identity: matches[0]
+	};
+	if (matches.length === 0) return {
+		ok: false,
+		code: SIGNING_CODES.noIdentity,
+		reason: `The app was signed by "${wantedName}", which is not in this machine's keychain. Available: ${identities.map((i) => `"${i.name}"`).join(", ")}.`,
+		remedy: `${KEYCHAIN_REMEDY} Or set ios.signingIdentity in .stim.json to one of the identities listed above.`
+	};
+	return {
+		ok: false,
+		code: SIGNING_CODES.noIdentity,
+		reason: `${matches.length} keychain identities share the name "${wantedName}", so Stim cannot pick one: ${matches.map((i) => i.sha1).join(", ")}.`,
+		remedy: "Set ios.signingIdentitySha1 in .stim.json to the SHA-1 hash of the certificate to sign with."
+	};
+}
+//#endregion
+//#region src/engine/ios-signing.ts
+const EMBEDDED_PROFILE = "embedded.mobileprovision";
+const SIGNING_TIMEOUT_MS = 12e4;
+function lastLines(text, count = 5) {
+	return String(text ?? "").split(/\r?\n/).map((line) => line.trimEnd()).filter((line) => line.trim() !== "").slice(-count);
+}
+function errorText(error) {
+	const withOutput = error;
+	const stderr = String(withOutput?.stderr ?? "").trim();
+	const stdout = String(withOutput?.stdout ?? "").trim();
+	return stderr || stdout || String(withOutput?.message ?? error);
+}
+function readEmbeddedProfile(appPath, { exec = null } = {}) {
+	const executor = exec || getExecutor();
+	const path = join(appPath, EMBEDDED_PROFILE);
+	if (!existsSync(path)) return {
+		present: false,
+		profile: null
+	};
+	try {
+		return {
+			present: true,
+			profile: parseProvisioningProfilePlist(executor.runFile("security", [
+				"cms",
+				"-D",
+				"-i",
+				path
+			], { timeoutMs: SIGNING_TIMEOUT_MS }))
+		};
+	} catch {
+		return {
+			present: true,
+			profile: null
+		};
+	}
+}
+function findSigningIdentities({ exec = null } = {}) {
+	const executor = exec || getExecutor();
+	try {
+		return parseSigningIdentities(executor.runFile("security", [
+			"find-identity",
+			"-v",
+			"-p",
+			"codesigning"
+		], { timeoutMs: SIGNING_TIMEOUT_MS }));
+	} catch {
+		return [];
+	}
+}
+function gateProfileForDevice(options) {
+	const read = readEmbeddedProfile(options.appPath, { exec: options.exec ?? null });
+	return profileGate({
+		profilePresent: read.present,
+		profile: read.profile,
+		identities: [],
+		udid: options.udid,
+		configuration: options.configuration ?? null,
+		...options.now === void 0 ? {} : { now: options.now }
+	});
+}
+function gateAppForDevice(options) {
+	const read = readEmbeddedProfile(options.appPath, { exec: options.exec ?? null });
+	return signingGate({
+		profilePresent: read.present,
+		profile: read.profile,
+		identities: read.present ? findSigningIdentities({ exec: options.exec ?? null }) : [],
+		udid: options.udid,
+		configuration: options.configuration ?? null,
+		pinnedName: options.pinnedName ?? null,
+		pinnedSha1: options.pinnedSha1 ?? null,
+		...options.now === void 0 ? {} : { now: options.now }
+	});
+}
+function extractEntitlements(appPath, executor) {
+	try {
+		return String(executor.runFile("codesign", [
+			"-d",
+			"--entitlements",
+			"-",
+			"--xml",
+			appPath
+		], { timeoutMs: SIGNING_TIMEOUT_MS })).trim();
+	} catch {
+		return "";
+	}
+}
+function resealBundle({ appPath, identity, exec = null }) {
+	const executor = exec || getExecutor();
+	const signAs = identity.sha1 || identity.name;
+	let mode = "preserve-metadata";
+	let preserveError = null;
+	try {
+		executor.runFile("codesign", [
+			"--force",
+			"--sign",
+			signAs,
+			"--preserve-metadata=identifier,entitlements,flags,runtime",
+			appPath
+		], { timeoutMs: SIGNING_TIMEOUT_MS });
+	} catch (error) {
+		preserveError = error;
+	}
+	let tempDir = null;
+	if (preserveError) {
+		const entitlements = extractEntitlements(appPath, executor);
+		const args = [
+			"--force",
+			"--sign",
+			signAs
+		];
+		if (entitlements !== "") {
+			tempDir = mkdtempSync(join(tmpdir(), "stim-entitlements-"));
+			const plist = join(tempDir, "entitlements.plist");
+			writeFileSync(plist, `${entitlements}\n`, "utf-8");
+			args.push("--entitlements", plist);
+			mode = "entitlements";
+		} else mode = "no-entitlements";
+		args.push(appPath);
+		try {
+			executor.runFile("codesign", args, { timeoutMs: SIGNING_TIMEOUT_MS });
+		} catch (error) {
+			return {
+				ok: false,
+				code: SIGNING_CODES.codesignFailed,
+				reason: `codesign could not re-seal ${appPath} with "${identity.name}": ${errorText(error)}`,
+				remedy: `Unlock the login keychain (\`security unlock-keychain\`) and confirm exactly one identity matches "${identity.name}".`,
+				lastLines: [...lastLines(errorText(preserveError)), ...lastLines(errorText(error))]
+			};
+		} finally {
+			if (tempDir) rmSync(tempDir, {
+				recursive: true,
+				force: true
+			});
+		}
+	}
+	try {
+		executor.runFile("codesign", [
+			"--verify",
+			"--strict",
+			appPath
+		], { timeoutMs: SIGNING_TIMEOUT_MS });
+	} catch (error) {
+		return {
+			ok: false,
+			code: SIGNING_CODES.codesignFailed,
+			reason: `codesign --verify --strict rejected ${appPath} after re-sealing it with "${identity.name}": ${errorText(error)}`,
+			remedy: "The bundle signed but did not seal. Delete the cached artifact with `stim gc --delete` and build fresh, then retry.",
+			lastLines: lastLines(errorText(error))
+		};
+	}
+	return {
+		ok: true,
+		identity,
+		mode
+	};
+}
+function sealAppForDevice(options) {
+	const gate = gateAppForDevice(options);
+	if (!gate.ok) return {
+		...gate,
+		lastLines: []
+	};
+	return resealBundle({
+		appPath: options.appPath,
+		identity: gate.identity,
+		exec: options.exec ?? null
+	});
+}
+//#endregion
+//#region src/engine/ios-lan.ts
+const IP_TXT = "ip.txt";
+function chooseLanAddress({ pinned = null, candidates }) {
+	const list = Array.isArray(candidates) ? candidates : [];
+	if (pinned) return {
+		address: pinned,
+		interfaceName: list.find((candidate) => candidate.address === pinned)?.interfaceName ?? null,
+		pinned: true,
+		candidates: list.length
+	};
+	const first = list[0];
+	if (!first) return null;
+	return {
+		address: first.address,
+		interfaceName: first.interfaceName,
+		pinned: false,
+		candidates: list.length
+	};
+}
+function lanOriginUrlFor(address, port) {
+	return `http://${address}:${port}`;
+}
+function ipTxtContents(address, port) {
+	return `${String(address).trim()}:${String(port).trim()}\n`;
+}
+function writeIpTxt(appPath, address, port, { write = writeFileSync } = {}) {
+	const path = join(appPath, IP_TXT);
+	write(path, ipTxtContents(address, port), "utf-8");
+	return path;
+}
+async function ensureLanReachable({ origin, metroPort, root, isExpo, logsDir, gateOrigin = gateMetroOrigin, readRecords = null }) {
+	const result = await gateOrigin({
+		origin,
+		metroPort,
+		platform: "ios",
+		entryPoint: bundleEntryPoint(root, isExpo),
+		readRecords: readRecords ?? (() => readMetroRecords(logsDir)),
+		isProof: isBundleProof
+	});
+	if (result.failed) return {
+		failed: result.reason ?? `${origin} is not this workspace's Metro.`,
+		remedy: `The phone reaches Metro at ${origin}, so that address has to serve THIS workspace's dev server. \`stim start\` prints the port it reserved. Set ios.lanHost in .stim.json when this Mac has several network interfaces and the phone shares one that is not the first.`
+	};
+	return { ok: true };
+}
+function copyAppAside(appPath, { exec = null, mkdtemp = () => makeTemporaryDirectory(appPath, "stim-ios-device-") } = {}) {
+	const e = exec || getExecutor();
+	const tmpDir = mkdtemp();
+	const copy = join(tmpDir, basename(appPath));
+	try {
+		e.runFile("cp", [
+			"-c",
+			"-R",
+			appPath,
+			copy
+		]);
+	} catch {
+		try {
+			e.runFile("cp", [
+				"-R",
+				appPath,
+				copy
+			]);
+		} catch (error) {
+			removeTemporaryEntry(tmpDir);
+			throw error;
+		}
+	}
+	return {
+		tmpDir,
+		appPath: copy
+	};
+}
+//#endregion
+//#region src/engine/lan-address.ts
+const EN_INTERFACE = /^en(\d+)$/;
+const EXCLUDED_INTERFACE = /^(?:utun|bridge|awdl)/;
+const LINK_LOCAL = /^169\.254\./;
+function isIpv4(entry) {
+	return entry.family === "IPv4" || entry.family === 4;
+}
+function lanCandidates(interfaces) {
+	const ranked = [];
+	const seen = /* @__PURE__ */ new Set();
+	for (const [interfaceName, entries] of Object.entries(interfaces ?? {})) {
+		if (EXCLUDED_INTERFACE.test(interfaceName)) continue;
+		const en = EN_INTERFACE.exec(interfaceName);
+		for (const entry of entries ?? []) {
+			if (!entry || typeof entry !== "object" || !isIpv4(entry) || entry.internal === true) continue;
+			const address = typeof entry.address === "string" ? entry.address.trim() : "";
+			if (address === "" || LINK_LOCAL.test(address)) continue;
+			if (seen.has(address)) continue;
+			seen.add(address);
+			ranked.push({
+				interfaceName,
+				address,
+				rank: en ? 0 : 1,
+				index: en ? Number(en[1]) : 0
+			});
+		}
+	}
+	ranked.sort((a, b) => a.rank - b.rank || a.index - b.index || a.interfaceName.localeCompare(b.interfaceName) || a.address.localeCompare(b.address));
+	return ranked.map(({ interfaceName, address }) => ({
+		interfaceName,
+		address
+	}));
+}
+function hostLanCandidates(interfaces = networkInterfaces) {
+	return lanCandidates(interfaces());
+}
+function buildLogFile(root) {
+	return join(workspaceLogsDir(root), `build-ios.ndjson`);
+}
+const MAX_PRINTED_DIAGNOSTICS = 6;
+function deviceLabel(device, udid) {
+	const name = device?.deviceName || device?.name || null;
+	return name ? `${name} (${shortUdid(udid)})` : shortUdid(udid);
+}
+function deviceShortName(device, udid) {
+	return device?.deviceName || device?.name || shortUdid(udid);
+}
+function appNameFromPath(appPath) {
+	if (typeof appPath !== "string" || appPath.trim() === "") return null;
+	const name = basename(appPath).replace(/\.app$/i, "");
+	return name === "" ? null : name;
+}
+function iosConfigurationSetting(settings) {
+	const ios = settings?.["ios"];
+	if (!ios || typeof ios !== "object" || Array.isArray(ios)) return null;
+	const raw = ios["configuration"];
+	return typeof raw === "string" && raw.trim() !== "" ? raw.trim() : null;
+}
+function resolveConfiguration(flag, settings) {
+	return (typeof flag === "string" && flag.trim() !== "" ? flag.trim() : null) || iosConfigurationSetting(settings);
+}
+function iosStringSetting(settings, key) {
+	const ios = settings?.["ios"];
+	if (!ios || typeof ios !== "object" || Array.isArray(ios)) return null;
+	const raw = ios[key];
+	return typeof raw === "string" && raw.trim() !== "" ? raw.trim() : null;
+}
+function resolveDeviceType(flag, settings) {
+	return (typeof flag === "string" && flag.trim() !== "" ? flag.trim() : null) || iosStringSetting(settings, "deviceType");
+}
+function resolveRuntime(flag, settings) {
+	return (typeof flag === "string" && flag.trim() !== "" ? flag.trim() : null) || iosStringSetting(settings, "runtime");
+}
+function deviceModelRefusal({ deviceTypeFlag, runtimeFlag, deviceType, runtime, physical, remoteBackend, listRuntimes }) {
+	if (typeof deviceTypeFlag === "string" && deviceTypeFlag.trim() === "") return {
+		code: "STIM_BAD_ARG",
+		message: "--device-type was given an empty name.",
+		remedy: "Pass `--device-type <name>` with a model `xcrun simctl list devicetypes` names, e.g. \"iPad Pro 13-inch (M4)\"."
+	};
+	if (typeof runtimeFlag === "string" && runtimeFlag.trim() === "") return {
+		code: "STIM_BAD_ARG",
+		message: "--runtime was given an empty version.",
+		remedy: "Pass `--runtime <version>` with a runtime `xcrun simctl list runtimes` reports, e.g. \"18.5\"."
+	};
+	if (physical || remoteBackend) return null;
+	if (!deviceType && !runtime) return null;
+	let runtimes;
+	try {
+		runtimes = listRuntimes();
+	} catch (error) {
+		return {
+			code: "STIM_NO_DEVICE",
+			message: `Could not read the installed simulator runtimes: ${error?.message || error}`,
+			remedy: "Run `stim doctor` to check the simulator toolchain, then try again."
+		};
+	}
+	const refusal = unknownIosRuntimeRefusal(runtime, runtimes) ?? unknownIosDeviceTypeRefusal(deviceType, runtimes, runtime);
+	return refusal ? {
+		code: "STIM_BAD_ARG",
+		message: refusal.message,
+		remedy: refusal.remedy
+	} : null;
+}
+function isReleaseConfiguration(configuration) {
+	return typeof configuration === "string" && configuration.trim() !== "" && configuration.trim().toLowerCase() !== "debug";
+}
+function podAction(podState, verdict) {
+	if (verdict?.stale) return {
+		install: true,
+		reason: verdict.reason
+	};
+	if (verdict?.noPods && podState?.hasPodfile) return {
+		install: true,
+		reason: "ios/Podfile exists but no pods are installed"
+	};
+	return { install: false };
+}
+function xcodeFailureReport(result, logPath) {
+	const diagnostics = Array.isArray(result?.diagnostics) ? result.diagnostics : [];
+	const code = result?.exitCode;
+	const how = code === null || code === void 0 ? "" : ` (exit code ${code})`;
+	return {
+		message: diagnostics.length ? `\`xcodebuild\` failed${how} with ${diagnostics.length} diagnostic${diagnostics.length === 1 ? "" : "s"}.` : `\`xcodebuild\` failed${how} with no recognizable diagnostic.`,
+		remedy: diagnostics.find((d) => d?.remedy)?.remedy || `See ${logPath} for the transcript.`
+	};
+}
+function printDiagnostics(note, result) {
+	const diagnostics = Array.isArray(result?.diagnostics) ? result.diagnostics : [];
+	const shown = diagnostics.slice(0, MAX_PRINTED_DIAGNOSTICS);
+	for (const diagnostic of shown) note(chalk.red(phaseLine("error", describeDiagnostic(diagnostic))));
+	const hidden = diagnostics.length - shown.length + (result?.truncated || 0);
+	if (hidden > 0) note(chalk.dim(phaseLine("error", `... and ${hidden} more diagnostic${hidden === 1 ? "" : "s"} in the log`)));
+	if (diagnostics.length === 0) {
+		note(chalk.red(phaseLine("error", "xcodebuild failed with no recognizable diagnostic; last lines:")));
+		for (const line of (result?.tail || []).slice(-5)) note(chalk.dim(phaseLine("", line)));
+	}
+}
+//#endregion
+//#region src/commands/ios/collector.ts
+function collectorLogFile(root) {
+	return join(workspaceLogsDir(root), `collector-ios.log`);
+}
+function collectorEntry() {
+	return spawnEntry("collector-run");
+}
+const COLLECTOR_EXIT_WAIT_MS = 2e3;
+const COLLECTOR_POLL_MS = 25;
+async function stopPreviousCollector({ root, kill = (pid, signal) => process.kill(pid, signal), alive = pidExists, readState = readWorkspaceState, verify = verifyCollectorOwnership, waitMs = COLLECTOR_EXIT_WAIT_MS, note = (_line) => {} }) {
+	const previous = (readState(root)?.collectors)?.["ios"] || null;
+	const previousPid = Number(previous?.pid) || null;
+	let killed = null;
+	if (previousPid) {
+		const ownership = verify({
+			pid: previousPid,
+			platform: "ios",
+			root,
+			isAlive: alive,
+			expected: previous
+		});
+		if (ownership.status === "ours") {
+			try {
+				kill(previousPid, "SIGTERM");
+				killed = previousPid;
+			} catch (err) {
+				if (err?.code !== "ESRCH") note(chalk.yellow(`Could not stop the previous ios log collector (pid ${previousPid}): ${err?.message || err}`));
+			}
+			const deadline = Date.now() + waitMs;
+			while (Date.now() < deadline && alive(previousPid)) await sleep(COLLECTOR_POLL_MS);
+		} else if (ownership.status === "unverified") note(chalk.dim(`Previous ios log collector (pid ${previousPid}): ${ownership.reason}, so it was not signalled -- starting a replacement anyway`));
+	}
+	return { killed };
+}
+async function replaceCollector({ root, udid, bundleId, appName, appExecutable, physical = false, payloadUrl = null, spawn = (cmd, args, opts) => getExecutor().spawn(cmd, args, opts), kill = (pid, signal) => process.kill(pid, signal), alive = pidExists, readState = readWorkspaceState, verify = verifyCollectorOwnership, waitMs = COLLECTOR_EXIT_WAIT_MS, note = (_line) => {} }) {
+	const { killed } = await stopPreviousCollector({
+		root,
+		kill,
+		alive,
+		readState,
+		verify,
+		waitMs,
+		note
+	});
+	const args = [
+		collectorEntry(),
+		"--platform",
+		"ios",
+		"--root",
+		root,
+		"--udid",
+		udid,
+		"--bundle",
+		bundleId
+	];
+	if (appName) args.push("--app-name", appName);
+	if (appExecutable) args.push("--app-executable", appExecutable);
+	if (physical) args.push("--physical");
+	if (payloadUrl) args.push("--payload-url", payloadUrl);
+	let stdio = "ignore";
+	try {
+		mkdirSync(workspaceLogsDir(root), { recursive: true });
+		const fd = openSync(collectorLogFile(root), "a");
+		stdio = [
+			"ignore",
+			fd,
+			fd
+		];
+	} catch {}
+	let child;
+	try {
+		child = spawn(process.execPath, args, {
+			cwd: root,
+			detached: true,
+			stdio,
+			env: process.env
+		});
+		child?.unref?.();
+	} catch (err) {
+		note(chalk.yellow(`Could not start the ios log collector: ${err?.message || err}`));
+		return {
+			killed,
+			pid: null
+		};
+	}
+	return {
+		killed,
+		pid: child?.pid ?? null
+	};
+}
+//#endregion
+//#region src/commands/ios/dependencies.ts
+const DEFAULT_DEPS = {
+	findProjectRoot,
+	resolveSettings,
+	gitCommonDir,
+	repoRoot,
+	detectBundleId,
+	detectIsExpo,
+	devClientScheme,
+	getProject,
+	upsertProject,
+	projectShortcut,
+	checkDeviceCapacity,
+	ensureOwnedDevice,
+	listIosRuntimes,
+	ensureBooted,
+	resolveRemoteContext,
+	remoteIosDeps,
+	ensureMetroReachable,
+	ensureRemoteBootOwned,
+	detectProviders,
+	resolveProjectMetro,
+	resolveMetroWithRetry,
+	warmMetro,
+	readWorkspaceState,
+	pidExists,
+	getConcurrencyLimits,
+	fingerprintProject,
+	untrackedNativeFiles,
+	resolveBuild,
+	storeBuild,
+	resolveCacheProviderConfig,
+	loadCacheProvider,
+	acquireBuildLock,
+	releaseBuildLock,
+	waitForBuild,
+	acquireBuildSlot,
+	releaseBuildSlot,
+	loadProjectProvider,
+	checkEasAuth,
+	resolveEasCliBin,
+	resolveRemote,
+	uploadRemote,
+	needsPrebuild,
+	runPrebuild,
+	readPodState,
+	podsAreStale,
+	runPodInstall,
+	buildIos,
+	discoverXcodeProject,
+	resolveScheme,
+	listIosDevices,
+	hostLanCandidates,
+	ensureLanReachable,
+	gateProfileForDevice,
+	sealAppForDevice,
+	installIosDeviceApp,
+	awaitIosDeviceLaunch,
+	acquireRunLease,
+	runLease,
+	selectFromPool,
+	releaseLeaseOnSignal,
+	iosDeviceProcess,
+	verifyIosDeviceReleaseLaunch,
+	readBundleId,
+	readBundleExecutable,
+	swapJsBundle,
+	installIosApp,
+	clearOtherUserApps,
+	clearIosAdoptionPending,
+	launchIosApp,
+	verifyLaunch,
+	verifyReleaseLaunch,
+	ensureWorkspaceStorage: ensureWorkspaceStorageSafely,
+	replaceCollector,
+	stopPreviousCollector,
+	writeWorkspaceLaunch,
+	writeWorkspaceState,
+	createWriter: createNdjsonWriter,
+	recordStats: recordRunStats,
+	readEstimates: readRunEstimates,
+	now: () => Date.now()
+};
+//#endregion
+//#region src/commands/ios/result.ts
+function lastBuildRecord({ fingerprint = null, cacheKey = null, cacheHit = false, cacheSkipped = false, durationMs = 0, appPath = null, bundleId = null, startedAt, status, errorCode = null }) {
+	const record = {
+		platform: "ios",
+		fingerprint,
+		cacheKey,
+		cacheHit: cacheLevel(cacheHit),
+		cacheSkipped: Boolean(cacheSkipped),
+		durationMs,
+		appPath,
+		bundleId,
+		startedAt,
+		status
+	};
+	if (errorCode) record.errorCode = errorCode;
+	return record;
+}
+function iosFacts({ udid, deviceName, deviceType = null, runtime = null, fingerprint, configuration = null, scheme = null, cacheKey, cacheHit, cacheSkipped = false, compilationCache = COMPILATION_CACHE_NOT_RUN, waitedForBuild = null, appPath, bundleId, installSkipped = false, metroPort, logsDir, durationMs, launched = true, webPreviewUrl = null, lease }) {
+	return {
+		platform: "ios",
+		udid,
+		deviceName: deviceName ?? null,
+		deviceType: deviceType ?? null,
+		runtime: runtime ?? null,
+		fingerprint,
+		configuration: configuration ?? null,
+		...scheme ? { scheme } : {},
+		cacheKey,
+		cacheHit: cacheLevel(cacheHit),
+		cacheSkipped: Boolean(cacheSkipped),
+		compilationCache,
+		waitedForBuild: waitedForBuild ? {
+			pid: waitedForBuild.pid ?? null,
+			ms: waitedForBuild.ms ?? 0
+		} : null,
+		appPath,
+		bundleId,
+		installSkipped: Boolean(installSkipped),
+		launched: launched === "unverified" || launched === "bundling" ? launched : Boolean(launched),
+		metroPort,
+		logs: { dir: logsDir },
+		durationMs,
+		...webPreviewUrl ? { webPreviewUrl } : {},
+		...lease === void 0 ? {} : { lease }
+	};
+}
+function writeLastBuild(root, record, { write = writeWorkspaceState } = {}) {
+	try {
+		write(root, { lastBuild: record });
+	} catch {}
+	return record;
+}
+async function finishIosUpload(uploadPending, remote, phase, note) {
+	if (!uploadPending) return false;
+	const upload = await uploadPending;
+	if (upload?.uploaded) phase("cache", `uploaded (${remote?.name})`);
+	else if (upload?.timedOut) {
+		note(chalk.yellow(phaseLine("cache", `${remote?.name} upload still running after ${formatDuration(UPLOAD_TIMEOUT_MS)}; not waiting`)));
+		return true;
+	} else if (upload?.failed) {
+		const authNote = remote?.name === "eas" && isEasAuthFailureText(upload.failed) ? easAuthNote({
+			code: "logged-out",
+			reason: upload.failed,
+			phase: "upload"
+		}) : null;
+		note(chalk.yellow(phaseLine("cache", authNote || `${remote?.name} upload failed: ${upload.failed}`)));
+	}
+	return false;
+}
+function reportIosResult({ d, root, json, release, configuration, buildScheme = null, metroCheck, metroPort, logsDir, device, udid, appPath, bundleId, installSkipped, elapsed, startedAt, storeHash, storeKey, cacheHit, compilationCache, useBuildCache, waitedForBuild, launchState, launchWarning, remote, providerName, closeWriter, webPreviewUrl, lease, recordRun }) {
+	const durationMs = elapsed();
+	recordRun({
+		failed: false,
+		cacheHit,
+		waited: waitedForBuild,
+		durationMs
+	});
+	writeLastBuild(root, lastBuildRecord({
+		fingerprint: storeHash,
+		cacheKey: storeKey,
+		cacheHit,
+		cacheSkipped: !useBuildCache,
+		durationMs,
+		appPath,
+		bundleId,
+		startedAt,
+		status: "ok"
+	}), { write: d.writeWorkspaceState });
+	closeWriter();
+	const facts = iosFacts({
+		udid,
+		deviceName: device?.deviceName ?? null,
+		deviceType: device?.deviceType,
+		runtime: device?.runtime,
+		fingerprint: storeHash,
+		configuration,
+		scheme: buildScheme,
+		cacheKey: storeKey,
+		cacheHit,
+		compilationCache,
+		cacheSkipped: !useBuildCache,
+		waitedForBuild,
+		appPath,
+		bundleId,
+		installSkipped,
+		metroPort,
+		logsDir,
+		durationMs,
+		launched: launchState,
+		webPreviewUrl,
+		lease
+	});
+	if (json) console.log(JSON.stringify(facts));
+	else {
+		const summary = `${launchWarning ? "WARNING" : "OK"}: ${bundleId} on ${deviceLabel(device, udid)}, ` + (release ? `${configuration} (embedded JS, no Metro)` : `Metro port ${metroPort}`) + ` (${cacheDescription(cacheHit, remote?.name ?? providerName)}, ${formatDuration(durationMs)})`;
+		const outcome = launchWarning ? chalk.yellow(`${summary} -- ${launchWarning}`) : launchState === "unverified" ? chalk.yellow(`${summary} -- launch UNVERIFIED`) : launchState === "bundling" ? chalk.green(`${summary} -- bundle requested, still building`) : chalk.green(summary);
+		const deviceName = device?.deviceName ?? device?.name ?? udid;
+		const cacheResult = useBuildCache ? cacheDescription(cacheHit, remote?.name ?? providerName) : "bypassed; built";
+		const metroResult = release ? `embedded (${configuration})` : !metroCheck ? `check skipped on port ${metroPort}` : launchState === "unverified" ? `state unverified on port ${metroPort}` : `running on port ${metroPort}`;
+		console.log([
+			outcome,
+			phaseLine("device", `${deviceName} (${udid})`),
+			phaseLine("app", bundleId),
+			phaseLine("metro", metroResult),
+			phaseLine("cache", cacheResult),
+			...compilationCache.status === "not-run" ? [phaseLine("compilation cache", compilationCacheActivityLine(compilationCache))] : [],
+			phaseLine("logs", logsDir)
+		].join("\n"));
+		if (facts.webPreviewUrl) console.error(chalk.dim(`Watch this device: ${facts.webPreviewUrl}`));
+	}
+	return facts;
+}
+function cacheDescription(cacheHit, providerName = null) {
+	if (cacheHit === "remote") return `from ${providerName || "the remote cache"}`;
+	if (cacheHit === "local") return "from cache";
+	return "built";
+}
+//#endregion
+//#region src/commands/ios/launch.ts
+function missingCrashReportHint({ physical, remote, crashed }) {
+	return crashed && !physical && !remote ? `No attributable native crash report captured yet. ${IOS_CRASH_REPORT_RETRY}` : "No attributable native crash report captured. Read `stim logs --source device` for available output.";
+}
+async function verifyIosRun({ root, appPath, d, release, launched, configuration, phase, note, metroCheck, logsDir, launchedAt, metroPort, isExpo, bundleId, udid, scheme, physical, appName, lanAddress, lanOrigin, remoteDevice, metroOrigin }) {
+	const readNativeCrashes = () => remoteDevice ? [] : captureNativeCrashes({
+		root,
+		platform: "ios",
+		deviceId: udid,
+		appId: bundleId,
+		since: launchedAt,
+		appPath,
+		physical
+	}, logsDir);
+	const deviceProcess = () => {
+		const pid = d.iosDeviceProcess({
+			udid,
+			appName: appName ?? bundleId
+		});
+		return pid === void 0 ? null : pid !== null;
+	};
+	if (release) {
+		const processCheck = physical ? await d.verifyIosDeviceReleaseLaunch({
+			udid,
+			appName: appName ?? bundleId
+		}) : await d.verifyReleaseLaunch({ pid: launched?.pid ?? null });
+		const crashes = readNativeCrashes();
+		if (processCheck?.verified && !crashes.length) {
+			phase("verify", `process alive ${formatDuration(processCheck.waitedMs ?? 0)} after launch (${configuration}: no bundle fetch to observe)`);
+			return { state: true };
+		}
+		for (const line of launchErrorPreview(crashes, root)) note(chalk.red(phaseLine("launch", line)));
+		if (!crashes.length) note(phaseLine("logs", missingCrashReportHint({
+			physical,
+			remote: Boolean(remoteDevice),
+			crashed: processCheck?.reason === "exited"
+		})));
+		phase("verify", chalk.yellow(crashes.length ? "FATAL: the app reported a native crash" : processCheck?.reason === "exited" ? `FATAL: the app process exited within ${formatDuration(processCheck.waitedMs ?? 0)} of launch` : physical ? `UNVERIFIED: devicectl could not read ${udid}'s process list` : "UNVERIFIED: simctl launch reported no process id to check"));
+		note(chalk.yellow(phaseLine("", "Release readiness was not established. Run `stim logs --errors` for captured crash reports, or `stim logs --source device` for the full device output.")));
+		return { state: crashes.length || processCheck?.reason === "exited" ? LAUNCH_FATAL : LAUNCH_UNVERIFIED };
+	}
+	const verification = metroCheck ? await d.verifyLaunch({
+		requireBundleResponse: true,
+		onReadinessPending: () => phase("readiness", "waiting for app readiness (up to 30s after bundle load)"),
+		logsDir,
+		since: launchedAt,
+		metroPort,
+		platform: "ios",
+		mode: isExpo ? MODE_EXPO : MODE_BARE,
+		readNativeCrashes,
+		processAlive: remoteDevice ? null : physical ? deviceProcess : () => {
+			if (launched?.pid) return d.pidExists(launched.pid);
+			const pid = iosAppProcess(udid, bundleId);
+			return pid === void 0 ? null : pid !== null;
+		}
+	}) : {
+		verified: false,
+		skipped: true
+	};
+	const nativeCrashes = verification.errors?.some((record) => record.event === "native_crash") ? [] : readNativeCrashes();
+	if (nativeCrashes.length) verification.fatal = true;
+	verification.errors = await errorDiagnostics([...verification.errors ?? [], ...nativeCrashes], {
+		root,
+		logsDir,
+		port: metroPort,
+		allowRequest: true
+	});
+	if (verification.readiness) phase("readiness", appReadinessMessage(verification.readiness, verification.waitedMs ?? 0));
+	if (verification?.fatal) {
+		const nativeFatal = verification.errors?.some((record) => record.event === "native_crash");
+		const deliveryFailed = verification.record?.event === "bundle_response_failed";
+		const reason = nativeFatal ? "the app reported a native crash" : verification.processAlive === false ? "the app process exited" : deliveryFailed ? "Metro bundle delivery failed" : "Metro could not build the bundle";
+		phase("verify", chalk.red(`FATAL after ${formatDuration(verification.waitedMs ?? 0)}: ${reason}`));
+		for (const line of launchErrorPreview(verification.errors ?? [], root)) note(chalk.red(phaseLine("", line)));
+		if (verification.processAlive === false && !verification.errors?.some((record) => record.event === "native_crash")) note(phaseLine("logs", missingCrashReportHint({
+			physical,
+			remote: Boolean(remoteDevice),
+			crashed: true
+		})));
+		if (nativeFatal || verification.processAlive === false) note(chalk.yellow(phaseLine("remedy", "Fix the crash, then run `stim ios` again. A Metro reload cannot restart an exited app.")));
+		else if (verification.processAlive === true && metroPort !== null) {
+			const reloadRemedy = `press Reload on the app's own error screen -- run \`agent-device snapshot -i --platform ios --udid ${udid}\` in your existing automation session to reach it. Neither \`stim reload ios\` nor \`agent-device metro reload\` can: this app never connected to Metro.`;
+			note(chalk.yellow(phaseLine("remedy", `The native app is still running. ${deliveryFailed ? "Check the Metro logs and device connection, then" : "Fix the JavaScript or TypeScript error, then"} ${reloadRemedy} Do not run \`stim ios\` unless native inputs changed or the app process exits.`)));
+		}
+		return { state: LAUNCH_FATAL };
+	}
+	if (verification?.verified) {
+		phase("verify", `bundle loaded` + (verification.processAlive === true ? ", process alive" : "") + (verification.readiness ? "" : ", stable for 3s -- the first screen may still be rendering") + ` (${formatDuration(verification.waitedMs ?? 0)} total)`);
+		const hasAppErrors = reportLaunchErrors(verification.errors ?? [], note, root);
+		if (hasAppErrors && verification.processAlive === true && metroPort !== null) {
+			const reloadRemedy = physical || remoteDevice ? `run \`agent-device metro reload --metro-port ${metroPort}\`.` : "run `stim reload ios`.";
+			note(chalk.yellow(phaseLine("remedy", `The native app is still running. Fix the JavaScript or TypeScript error; Fast Refresh should apply the edit. If the error screen remains, ${reloadRemedy} Do not run \`stim ios\` unless native inputs changed or the app process exits.`)));
+		}
+		return {
+			state: true,
+			warning: hasAppErrors ? "app errors detected; inspect the error above" : verification.readiness === "timed-out" || verification.readiness === "error" ? "app readiness not confirmed; inspect the UI and logs" : void 0
+		};
+	}
+	if (verification?.skipped) {
+		phase("verify", "skipped (--no-metro-check): the launch is reported as unverified");
+		return { state: LAUNCH_UNVERIFIED };
+	}
+	if (verification?.requested) {
+		phase("verify", `BUNDLING: the app asked port ${metroPort} for its bundle; build or delivery was still pending after ${formatDuration(verification.waitedMs ?? 0)} (a cold bundle on a large graph outlasts this window)`);
+		note(chalk.dim(phaseLine("", "Nothing to do: `stim logs --source metro` shows the build finishing, usually within a minute.")));
+		return { state: LAUNCH_BUNDLING };
+	}
+	phase("verify", chalk.yellow("UNVERIFIED: no bundle request reached this workspace's Metro"));
+	for (const line of unverifiedLaunchLines({
+		platform: "ios",
+		metroPort: metroPort ?? 8081,
+		waitedMs: verification?.waitedMs,
+		bundleId,
+		udid,
+		devClientUrl: scheme ? devClientUrl(scheme, metroPort ?? 8081, lanAddress ?? void 0) : null,
+		mode: isExpo ? MODE_EXPO : MODE_BARE,
+		remote: remoteDevice,
+		physical,
+		devClient: Boolean(scheme),
+		lanOrigin,
+		metroOrigin,
+		localNetworkPending: physical && localNetworkPending(readCollectorRecords(logsDir), {
+			since: launchedAt,
+			pid: launched?.pid ?? null,
+			lanOrigin
+		})
+	})) note(chalk.yellow(phaseLine("", line)));
+	return { state: LAUNCH_UNVERIFIED };
+}
+function reportLaunchErrors(errors, note, root) {
+	const report = launchErrorReport(errors, root);
+	if (report.summary) note(chalk.dim(phaseLine("launch", report.summary)));
+	for (const line of report.lines) note(chalk.yellow(phaseLine("launch", line)));
+	return report.lines.length > 0;
+}
+function cleanAdoptedIosApps({ d, root, udid, bundleId, phase, note }) {
+	const swept = d.clearOtherUserApps({
+		udid,
+		keep: bundleId
+	});
+	if (swept.removed.length) phase("install", `removed ${swept.removed.join(", ")}, left by the previous workspace`);
+	if (swept.listed && swept.failed.length === 0) {
+		d.clearIosAdoptionPending(root);
+		return null;
+	}
+	if (!swept.listed) return "Could not list apps left by the previous workspace.";
+	for (const failure of swept.failed) note(chalk.yellow(phaseLine("install", `could not remove ${failure}, left by the previous workspace`)));
+	return `Could not remove ${swept.failed.join(", ")}, left by the previous workspace.`;
+}
+function resolveRunBundleId(d, root, appPath, bundleId) {
+	if (!appPath || bundleId) return bundleId;
+	return d.readBundleId(appPath) || d.detectBundleId(root);
+}
+function removeSwapDirectory(swapDir) {
+	if (!swapDir) return;
+	try {
+		rmSync(swapDir, {
+			recursive: true,
+			force: true
+		});
+	} catch {}
+}
+function readRunExecutable(d, appPath, note) {
+	const executable = appPath ? d.readBundleExecutable(appPath) : null;
+	if (appPath && !executable) note(chalk.dim(`Could not read CFBundleExecutable from ${appPath}; the device log predicate falls back to the .app basename.`));
+	return executable;
+}
+function recordIosReloadTarget({ d, root, physical, remoteDevice, bundleId, udid, metroPort, release, launchedAt, note }) {
+	if (physical || remoteDevice) return;
+	try {
+		d.writeWorkspaceLaunch(root, "ios", {
+			appId: bundleId,
+			deviceId: udid,
+			metroPort,
+			release,
+			launchedAt: new Date(launchedAt).toISOString()
+		});
+	} catch (error) {
+		note(chalk.yellow(phaseLine("state", `could not record iOS launch: ${error?.message || error}`)));
+	}
+}
+function simulatorLaunchFailureRemedy(remote, udid, bundleId, logFile) {
+	return `${remote ? "Run" : "If the simulator timed out, run `stim doctor --platform ios` and resolve any reported host memory pressure before retrying. Otherwise run"} \`xcrun simctl launch --console ${udid} ${bundleId}\` to see what the app reports, and check ${logFile}.`;
+}
+async function finishIosRun({ d, root, json, release, configuration, buildScheme, isExpo, metroCheck, metroPort, logsDir, logFile, device, udid, physical, lanAddress, lanOriginUrl, remoteDevice, bootPromise, bootDuration, appPath, bundleId: initialBundleId, swapDir, buildFailure, fail, phase, note, logWriter, uploadPending, providerUpload, providerName, remote, abandonedRemote: remoteWasAbandoned, elapsed, startedAt, storeHash, storeKey, cacheHit, compilationCache, useBuildCache, waitedForBuild, closeWriter, lease, releaseLease, recordRun }) {
+	let bundleId = initialBundleId;
+	let leaseWarned = false;
+	const raiseLeaseFor = (boundMs, beforeInstall) => {
+		const step = lease?.raise(boundMs);
+		if (!step || step.ok) return null;
+		if (beforeInstall) {
+			const refusal = lostRefusal(step.holder, step.expiresAt, d.now());
+			return {
+				code: refusal.code,
+				message: refusal.message,
+				remedy: refusal.remedy,
+				lease: refusal.lease
+			};
+		}
+		if (!leaseWarned) {
+			leaseWarned = true;
+			note(chalk.yellow(phaseLine("lease", lostLine(step.holder, step.expiresAt, d.now()))));
+		}
+		return null;
+	};
+	bundleId = resolveRunBundleId(d, root, appPath, bundleId);
+	if (appPath && !bundleId) return fail({
+		code: "STIM_INSTALL_FAILED",
+		message: `Could not read a bundle identifier from the cached app at ${appPath}.`,
+		remedy: "Remove the cache entry (`stim gc`) and run again to rebuild it.",
+		build: {
+			...buildFailure,
+			appPath
+		}
+	});
+	if (bundleId) d.upsertProject(root, { bundleId });
+	const booted = await bootPromise;
+	if (!booted?.ok) return fail({
+		code: booted?.code || "STIM_NO_DEVICE",
+		message: booted?.reason || "The owned simulator could not be booted.",
+		remedy: booted?.remedy || "Run `stim ios` again to re-establish an owned simulator for this workspace."
+	});
+	const deviceOutcome = physical ? "connected" : `${device?.adopted ? "adopted" : "booted"} ${bootDuration()}`;
+	phase("device", `${deviceLabel(device, udid)} ${deviceOutcome}`);
+	const scheme = release ? void 0 : d.devClientScheme(root, appPath);
+	const appName = appNameFromPath(appPath);
+	const appExecutable = readRunExecutable(d, appPath, note);
+	const dropSwapDir = () => removeSwapDirectory(swapDir);
+	let installSkipped = false;
+	let launched = null;
+	let launchedAt = d.now();
+	if (physical) {
+		const lostBeforeInstall = raiseLeaseFor(DEVICECTL_INSTALL_TIMEOUT_MS, true);
+		if (lostBeforeInstall) return fail(lostBeforeInstall);
+		await d.stopPreviousCollector({
+			root,
+			note
+		});
+		const installTimer = stepTimer(d.now);
+		const installed = d.installIosDeviceApp({
+			udid,
+			appPath,
+			bundleId
+		});
+		if (installed?.failed) {
+			dropSwapDir();
+			return fail({
+				code: installed.code || "STIM_INSTALL_FAILED",
+				message: installed.reason ?? `devicectl could not install ${appPath} on ${udid}.`,
+				remedy: installed.remedy ?? null,
+				build: {
+					...buildFailure,
+					appPath,
+					bundleId
+				}
+			});
+		}
+		phase("install", `${basename(appPath)} -> ${deviceLabel(device, udid)} ${installTimer()}`);
+		if (installed?.note) {
+			note(chalk.yellow(phaseLine("install", installed.note)));
+			logWriter().write({
+				src: "build",
+				level: "warn",
+				event: "install_uninstalled_first",
+				msg: installed.note
+			});
+		}
+		dropSwapDir();
+		raiseLeaseFor(COLLECTOR_EXIT_WAIT_MS + LAUNCH_PROBE_TIMEOUT_MS, false);
+		const payloadUrl = scheme && metroPort !== null && lanAddress ? devClientUrl(scheme, metroPort, lanAddress) : null;
+		const launchTimer = stepTimer(d.now);
+		launchedAt = d.now();
+		logWriter().write({
+			src: "build",
+			level: "info",
+			marker: true,
+			event: "launch_attempt",
+			ts: launchedAt,
+			platform: "ios",
+			appId: bundleId,
+			deviceId: udid,
+			appPath,
+			physical: true,
+			msg: `launching ${bundleId} on ${udid}`
+		});
+		const collector = await d.replaceCollector({
+			root,
+			udid,
+			bundleId,
+			appName,
+			physical: true,
+			payloadUrl,
+			note
+		});
+		if (!collector?.pid) return fail({
+			code: "STIM_LAUNCH_FAILED",
+			message: `The device log collector, which is what launches ${bundleId} on a phone, could not be started.`,
+			remedy: `Check ${logFile} and the workspace collector log, then run the command again.`,
+			build: {
+				...buildFailure,
+				appPath,
+				bundleId
+			}
+		});
+		const started = await d.awaitIosDeviceLaunch({
+			udid,
+			bundleId,
+			appName: appName ?? bundleId,
+			collectorPid: collector.pid,
+			readRecords: () => readCollectorRecords(logsDir).filter((entry) => Number(entry.ts) >= launchedAt)
+		});
+		if (started.failed || !started.pid) return fail({
+			code: "STIM_LAUNCH_FAILED",
+			message: started.reason ?? `${bundleId} did not start on ${udid}.`,
+			remedy: started.remedy ?? null,
+			lines: started.lines ?? [],
+			logPath: logsDir,
+			build: {
+				...buildFailure,
+				appPath,
+				bundleId
+			}
+		});
+		launched = {
+			ok: true,
+			mode: payloadUrl ? "payload-url" : "launch",
+			pid: started.pid,
+			...payloadUrl ? { url: payloadUrl } : {},
+			...lanOriginUrl ? { jsLocation: lanOriginUrl } : {}
+		};
+		phase("launch", `${bundleId} pid ${started.pid} ${launchTimer()}`);
+	} else {
+		const adopting = Boolean(device?.adoptionPending);
+		if (adopting) {
+			const cleanupFailure = cleanAdoptedIosApps({
+				d,
+				root,
+				udid,
+				bundleId,
+				phase,
+				note
+			});
+			if (cleanupFailure) return fail({
+				code: "STIM_INSTALL_FAILED",
+				message: `${cleanupFailure} Stim kept the adoption cleanup pending and did not install or launch the app.`,
+				remedy: "Run `stim ios` again after simulator tooling is responsive.",
+				build: {
+					...buildFailure,
+					appPath,
+					bundleId
+				}
+			});
+		}
+		const installTimer = stepTimer(d.now);
+		const installed = d.installIosApp({
+			udid,
+			appPath,
+			bundleId,
+			devClientScheme: scheme,
+			proveInstalled: !adopting || device?.parkedCacheKey === storeKey
+		}, { now: d.now });
+		if (installed?.failed) return fail({
+			code: installed.code || "STIM_INSTALL_FAILED",
+			message: installed.reason,
+			remedy: "Check that the simulator is booted and that the app was built for the simulator SDK.",
+			build: {
+				...buildFailure,
+				appPath,
+				bundleId
+			}
+		});
+		installSkipped = Boolean(installed?.skipped);
+		const artifactDuration = installed?.artifactDurationMs === void 0 ? installTimer() : `(${formatDuration(installed.artifactDurationMs)})`;
+		phase("install", installSkipped ? `unchanged (${deviceShortName(device, udid)} already has this build) ${artifactDuration}` : `${basename(appPath)} -> ${deviceLabel(device, udid)} ${artifactDuration}`);
+		if (!remoteDevice && installed?.devClientPreparationDurationMs !== void 0) phase("install", `dev client prepared (${formatDuration(installed.devClientPreparationDurationMs)})`);
+		dropSwapDir();
+		if (!remoteDevice) await d.replaceCollector({
+			root,
+			udid,
+			bundleId,
+			appName,
+			appExecutable,
+			note
+		});
+		const launchTimer = stepTimer(d.now);
+		launchedAt = d.now();
+		logWriter().write({
+			src: "build",
+			level: "info",
+			marker: true,
+			event: "launch_attempt",
+			ts: launchedAt,
+			platform: "ios",
+			appId: bundleId,
+			deviceId: udid,
+			appPath,
+			remote: Boolean(remoteDevice),
+			msg: `launching ${bundleId} on ${udid}`
+		});
+		launched = d.launchIosApp({
+			udid,
+			bundleId,
+			metroPort,
+			devClientScheme: scheme,
+			consolePaths: simulatorConsolePaths({
+				deviceId: udid,
+				appId: bundleId,
+				since: launchedAt
+			}, true, Boolean(remoteDevice))
+		});
+		if (launched?.failed) {
+			printNativeCrashReport({
+				root,
+				platform: "ios",
+				deviceId: udid,
+				appId: bundleId,
+				since: launchedAt,
+				appPath
+			}, logsDir, (line) => note(chalk.red(phaseLine("launch", line))), Boolean(remoteDevice));
+			return fail({
+				code: launched.code || "STIM_LAUNCH_FAILED",
+				message: launched.reason,
+				remedy: simulatorLaunchFailureRemedy(Boolean(remoteDevice), udid, bundleId, logFile),
+				build: {
+					...buildFailure,
+					appPath,
+					bundleId
+				}
+			});
+		}
+		phase("launch", `${bundleId} ${launchTimer()}`);
+	}
+	recordIosReloadTarget({
+		d,
+		root,
+		physical,
+		remoteDevice: Boolean(remoteDevice),
+		bundleId,
+		udid,
+		metroPort,
+		release,
+		launchedAt,
+		note
+	});
+	logWriter().write({
+		src: "build",
+		level: "info",
+		event: "launch",
+		msg: release ? `launched ${bundleId} on ${udid} (${configuration}, embedded JS bundle, no Metro)` : `launched ${bundleId} on ${udid} against Metro ${lanOriginUrl ?? `port ${metroPort}`}` + (launched?.mode === "openurl" || launched?.mode === "payload-url" ? " (expo-dev-client)" : "")
+	});
+	if (remoteDevice) await d.replaceCollector({
+		root,
+		udid,
+		bundleId,
+		appName,
+		appExecutable,
+		note
+	});
+	if (physical) raiseLeaseFor(release ? RELEASE_VERIFY_WAIT_MS : DEBUG_VERIFY_STEP_MS, false);
+	const { state: launchState, warning: launchWarning } = await verifyIosRun({
+		root,
+		appPath,
+		d,
+		release,
+		launched,
+		configuration,
+		phase,
+		note,
+		metroCheck,
+		logsDir,
+		launchedAt,
+		metroPort,
+		isExpo,
+		bundleId,
+		udid,
+		scheme,
+		physical,
+		appName,
+		lanAddress,
+		lanOrigin: lanOriginUrl,
+		remoteDevice: Boolean(remoteDevice),
+		metroOrigin: typeof launched?.jsLocation === "string" ? launched.jsLocation : null
+	});
+	if (launchState === "fatal") return fail({
+		code: "STIM_LAUNCH_FAILED",
+		message: "The app failed its launch readiness check.",
+		remedy: `Read the launch error above or run \`stim logs --errors\`. The full timeline is in ${logsDir}.`,
+		logPath: logsDir,
+		build: {
+			...buildFailure,
+			appPath,
+			bundleId
+		}
+	});
+	logWriter().write(launchOutcomeRecord({
+		launchState,
+		release,
+		bundleId,
+		configuration,
+		metroPort
+	}));
+	const leaseFacts = lease?.facts() ?? null;
+	releaseLease();
+	const uploadWasAbandoned = await finishIosUpload(uploadPending, remote, phase, note);
+	const providerOutcome = providerUploadOutcome(providerUpload ? await providerUpload : null, providerName);
+	if (providerOutcome) {
+		if (providerOutcome.warn) note(chalk.yellow(phaseLine("cache", providerOutcome.line)));
+		else phase("cache", providerOutcome.line);
+	}
+	const facts = reportIosResult({
+		d,
+		root,
+		json,
+		release,
+		configuration,
+		buildScheme,
+		metroCheck,
+		metroPort,
+		logsDir,
+		device,
+		udid,
+		appPath,
+		bundleId,
+		installSkipped,
+		elapsed,
+		startedAt,
+		storeHash,
+		storeKey,
+		cacheHit,
+		compilationCache,
+		useBuildCache,
+		waitedForBuild,
+		launchState,
+		launchWarning,
+		remote,
+		providerName,
+		closeWriter,
+		webPreviewUrl: remoteDevice?.webPreviewUrl() ?? null,
+		lease: physical ? leaseFacts : void 0,
+		recordRun
+	});
+	if (remoteWasAbandoned || uploadWasAbandoned) exitAfterFlush(0);
+	return facts;
+}
+//#endregion
+//#region src/commands/ios.ts
+function writeNote(line) {
+	console.error(line);
+}
+function writePhase(name, text) {
+	console.error(phaseLine(name, text));
+}
+const GENERIC_SIM_DESTINATION = "generic/platform=iOS Simulator";
+const IPHONEOS_SDK = "iphoneos";
+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 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. Requires a running dev server (`stim start`).").option("--json", "Emit the facts as a single JSON line on stdout; every other line goes to stderr").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?\" gate 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 (M4)\"). 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("--device [udid]", "Build the iphoneos slice for a connected iPhone, install it, and launch it, instead of using this workspace's owned simulator. With no UDID, the first connected device this workspace can lease is used. 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 <backend>", "Install and launch on a remote device with proxy or EAS. The build still happens here.", (value) => {
+		if (REMOTE_DEVICE_BACKENDS.includes(value)) return value;
+		throw new InvalidArgumentError(`expected one of: ${REMOTE_DEVICE_BACKENDS.join(", ")}`);
+	}).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). Only with --device.").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. Only with --device.").action(async (opts) => {
+		await runIos({
+			...opts,
+			waitConflict: waitFlagConflict(process.argv)
+		}, deps);
+	});
+}
+function explicitSchemeRefusal(root, scheme, isExpo, d) {
+	if (scheme === void 0) return null;
+	if (!scheme.trim()) return {
+		code: "STIM_BAD_ARG",
+		message: "--scheme must name a non-empty shared Xcode app scheme.",
+		remedy: "Pass the exact scheme name shown by xcodebuild -list."
+	};
+	if (d.needsPrebuild(root, "ios", isExpo)) return null;
+	const project = d.discoverXcodeProject(root);
+	if (project.error) return project.error;
+	return d.resolveScheme(project, { scheme }).error ?? null;
+}
+async function runIos(opts = {}, overrides = {}) {
+	let d = {
+		...DEFAULT_DEPS,
+		...overrides
+	};
+	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 foundRoot = d.findProjectRoot(process.cwd());
+	if (!foundRoot) {
+		note(chalk.red("Not in a React Native project (no package.json found)."));
+		process.exit(1);
+		return null;
+	}
+	const root = foundRoot;
+	const projectProblem = appProjectProblem(root);
+	if (projectProblem) {
+		const { message, remedy } = projectProblem;
+		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
+		}));
+		process.exit(1);
+		return null;
+	}
+	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."
+		}));
+		process.exitCode = 1;
+		return null;
+	}
+	const logsDir = workspaceLogsDir(root);
+	const logFile = buildLogFile(root);
+	let writer = null;
+	const logWriter = () => writer ||= d.createWriter(logFile, { truncate: true });
+	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 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}`));
+		}
+	};
+	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}`));
+		}
+	};
+	const stats = createRunRecorder({
+		platform: "ios",
+		write: (statsRun, at) => d.recordStats(statsRun, at),
+		now: () => d.now(),
+		note: (line) => note(chalk.dim(line))
+	});
+	const recordRun = stats.record;
+	let compilationCache = COMPILATION_CACHE_NOT_RUN;
+	const fail = ({ code, message, remedy = null, lines = [], logPath = null, build = null, lease }) => {
+		releaseLock();
+		releaseSlot();
+		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({
+			...build,
+			startedAt,
+			status: "failed",
+			errorCode: code,
+			durationMs: elapsed()
+		}), { write: d.writeWorkspaceState });
+		note(chalk.red(phaseLine("failed", code)));
+		recordRun({
+			failed: true,
+			durationMs: elapsed()
+		});
+		if (json) console.log(JSON.stringify({
+			code,
+			message: message ?? null,
+			remedy: remedy ?? null,
+			...compilationCache.status === "not-run" ? {} : { compilationCache },
+			...lease === void 0 ? {} : { lease }
+		}));
+		writer?.close?.();
+		process.exit(1);
+		return null;
+	};
+	const settingsRepoRoot = d.repoRoot(root);
+	const settingsContext = {
+		projectPath: root,
+		gitCommonDir: d.gitCommonDir(root),
+		repoRoot: settingsRepoRoot
+	};
+	const projectKey = statsProjectKey({
+		root,
+		commonDir: settingsContext.gitCommonDir,
+		repoRoot: settingsRepoRoot
+	});
+	stats.setProject(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
+	});
+	let optimizations;
+	try {
+		optimizations = resolveOptimizations(settings);
+	} catch (error) {
+		return fail({
+			code: "STIM_BAD_ARG",
+			message: error.message,
+			remedy: SETTING_SHAPE_REMEDY
+		});
+	}
+	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 remoteSettingError = remoteDeviceSettingError(settings);
+	if (remoteSettingError) return fail({
+		code: "STIM_BAD_ARG",
+		message: remoteSettingError,
+		remedy: `Set ios.remote and android.remote to one of: ${REMOTE_DEVICE_BACKENDS.join(", ")}.`
+	});
+	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 = resolveConfiguration(opts.configuration, settings);
+	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 = deviceFlag !== null && deviceFlag !== void 0 && deviceFlag !== false;
+	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 cabled to this machine, and --remote installs on a remote one.",
+		remedy: "Pass only one of --device and --remote."
+	});
+	const noWait = opts.wait === false;
+	const waitFlagged = opts.wait !== void 0;
+	if (opts.waitConflict) return fail({
+		code: "STIM_BAD_ARG",
+		message: "--wait and --no-wait ask for opposite things.",
+		remedy: "Pass `--wait <seconds>` to wait for the lease, or `--no-wait` to install without one."
+	});
+	if (waitFlagged && !physical) return fail({
+		code: "STIM_BAD_ARG",
+		message: "--wait and --no-wait only apply to a `--device` run.",
+		remedy: "This workspace owns its simulator, so nothing contends for it. Drop the flag, or pass `--device`."
+	});
+	const waitParsed = parseDeviceWait(noWait ? void 0 : opts.wait);
+	if ("error" in waitParsed) return fail({
+		code: "STIM_BAD_ARG",
+		message: waitParsed.error,
+		remedy: "Pass a whole number of seconds, e.g. --wait 90. `--wait 0` refuses a leased device at once."
+	});
+	const waitSeconds = waitParsed.seconds;
+	const isExpo = d.detectIsExpo(root);
+	const schemeRefusal = explicitSchemeRefusal(root, buildScheme, isExpo, d);
+	if (schemeRefusal) return fail(schemeRefusal);
+	const remoteBackend = physical ? null : opts.remote ?? remoteIosSetting(settings);
+	const modelRefusal = deviceModelRefusal({
+		deviceTypeFlag: opts.deviceType,
+		runtimeFlag: opts.runtime,
+		deviceType,
+		runtime,
+		physical,
+		remoteBackend,
+		listRuntimes: d.listIosRuntimes
+	});
+	if (modelRefusal) return fail(modelRefusal);
+	const registerProject = () => d.upsertProject(root, {
+		bundleId: d.detectBundleId(root) ?? void 0,
+		isExpo
+	});
+	if (remoteBackend !== "eas") registerProject();
+	const proj = d.getProject(root);
+	const label = d.projectShortcut(root, proj);
+	let remoteDevice = null;
+	if (remoteBackend) {
+		const resolved = await d.resolveRemoteContext({
+			root,
+			label,
+			backend: remoteBackend,
+			easBin: d.resolveEasCliBin(root)?.file ?? null
+		});
+		if ("failed" in resolved) return fail({
+			code: resolved.code ?? "STIM_NO_REMOTE_SESSION",
+			message: resolved.failed,
+			remedy: resolved.remedy
+		});
+		remoteDevice = d.remoteIosDeps(resolved.ctx);
+		d = {
+			...d,
+			checkDeviceCapacity: remoteDevice.checkDeviceCapacity,
+			ensureOwnedDevice: remoteDevice.ensureOwnedDevice,
+			ensureBooted: remoteDevice.ensureBooted,
+			installIosApp: remoteDevice.installIosApp,
+			launchIosApp: remoteDevice.launchIosApp
+		};
+	}
+	const limits = d.getConcurrencyLimits();
+	let physicalDevice = null;
+	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
+			})),
+			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
+		};
+	} 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
+		};
+	}
+	if (!physical) {
+		const capacity = d.checkDeviceCapacity({
+			platform: "ios",
+			project: proj,
+			max: limits.maxDevices
+		});
+		if (capacity) return fail(capacity);
+	}
+	let metroPort = proj?.metroPort ?? null;
+	let lanAddress = null;
+	let lanOriginUrl = null;
+	if (!await resolveMetroPort()) return null;
+	let device;
+	if (physicalDevice) device = {
+		deviceUdid: physicalDevice.udid,
+		deviceName: physicalDevice.name,
+		owned: false
+	};
+	else {
+		const prepare = stepClock(d.now);
+		try {
+			device = await d.ensureOwnedDevice({
+				platform: "ios",
+				project: proj,
+				projectPath: root,
+				settingsRoot: root,
+				settings,
+				flags: {
+					deviceType,
+					runtime
+				},
+				note,
+				out: note
+			});
+		} catch (e) {
+			return fail({
+				code: "STIM_NO_DEVICE",
+				message: `Could not ensure an owned iOS simulator: ${e?.message || e}`,
+				remedy: "Run `stim doctor` to check the simulator toolchain, then try again."
+			});
+		}
+		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 = "";
+	let fingerprint = "";
+	let fingerprintSources = [];
+	let cacheKey = "";
+	let storeHash = null;
+	let storeKey = null;
+	let storeSources = [];
+	let appPath = null;
+	let bundleId = null;
+	let cacheHit = false;
+	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 swapDir = null;
+	let swapFellBack = false;
+	let buildFailure = {};
+	async function resolveMetroPort() {
+		if (release) {
+			metroPort = null;
+			phase("metro", `skipped (${configuration}: the JS bundle is embedded, no dev server is used)`);
+		} else if (metroCheck) {
+			if (!metroPort) {
+				fail({
+					code: "STIM_NO_METRO",
+					message: "No Metro port is reserved for this workspace, so there is no dev server to build against.",
+					remedy: "Run `stim start` first, or pass --no-metro-check."
+				});
+				return false;
+			}
+			const resolution = await d.resolveMetroWithRetry(d.resolveProjectMetro, metroPort, root, { onRetry: ({ delayMs }) => note(chalk.dim(phaseLine("metro", `port ${metroPort} did not verify yet; retrying in ${Math.round(delayMs / 1e3)}s (Metro may still be indexing)`))) });
+			if (!resolution?.metro) {
+				const supervisor = d.readWorkspaceState(root)?.supervisor ?? null;
+				const supervisorAlive = Boolean(supervisor?.pid && d.pidExists(supervisor.pid));
+				fail({
+					code: "STIM_NO_METRO",
+					message: noMetroMessage({
+						port: metroPort,
+						resolution,
+						supervisor,
+						supervisorAlive
+					}),
+					remedy: noMetroRemedy({
+						port: metroPort,
+						supervisor,
+						supervisorAlive
+					})
+				});
+				return false;
+			}
+		} else if (!metroPort) {
+			metroPort = DEFAULT_METRO_PORT;
+			note(chalk.yellow(`No Metro port is reserved for this workspace; wiring the app to ${metroPort}.`));
+		}
+		if (physical && metroPort !== null && !await resolveLanOrigin()) return false;
+		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)
+			});
+			if ("failed" in reachable) {
+				fail({
+					code: reachable.code ?? "STIM_NO_REMOTE_SESSION",
+					message: reachable.failed,
+					remedy: reachable.remedy
+				});
+				return false;
+			}
+		}
+		if (!release && metroCheck && optimizations.metroWarmup) d.warmMetro({
+			port: metroPort,
+			platform: "ios",
+			isExpo,
+			appId: proj?.bundleId,
+			bundleUrl: metroWarmupUrlSetting(settings, "ios")
+		});
+		return true;
+	}
+	async function resolveLanOrigin() {
+		const port = metroPort;
+		const chosen = chooseLanAddress({
+			pinned: iosLanHostSetting(settings),
+			candidates: d.hostLanCandidates()
+		});
+		if (!chosen) {
+			fail({
+				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."
+			});
+			return false;
+		}
+		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 true;
+		const reachable = await d.ensureLanReachable({
+			origin: lanOriginUrl,
+			metroPort: port,
+			root,
+			isExpo,
+			logsDir
+		});
+		if ("failed" in reachable) {
+			fail({
+				code: "STIM_LAN_METRO_UNREACHABLE",
+				message: reachable.failed,
+				remedy: reachable.remedy
+			});
+			return false;
+		}
+		phase("lan", `gated: ${lanOriginUrl} answered as this workspace's Metro`);
+		return true;
+	}
+	async function resolveInitialFingerprint() {
+		const bootTimer = stepTimer(d.now);
+		const boot = () => physicalDevice ? Promise.resolve({
+			ok: true,
+			udid: physicalDevice.udid
+		}) : Promise.resolve(d.ensureBooted({
+			platform: "ios",
+			device,
+			out: note
+		})).catch((e) => ({
+			ok: false,
+			reason: String(e?.message || e)
+		}));
+		bootPromise = (remoteDevice?.ctx.backend === "eas" ? d.ensureRemoteBootOwned({
+			root,
+			platform: "ios",
+			sessionName: ownedSessionName(remoteDevice.ctx.label),
+			startedAt,
+			boot,
+			createdSessionId: remoteDevice.createdSessionId,
+			abandonCreatedSession: remoteDevice.abandonCreatedSession,
+			writeState: d.writeWorkspaceState,
+			register: registerProject
+		}) : boot()).then((result) => {
+			bootDuration = bootTimer();
+			return result;
+		});
+		udid = device.deviceUdid ?? (await bootPromise)?.udid ?? "";
+		const fingerprintTimer = stepTimer(d.now);
+		let computedFingerprint;
+		try {
+			const computed = await d.fingerprintProject(root, { platform: "ios" });
+			computedFingerprint = computed?.hash ?? null;
+			fingerprintSources = computed?.sources ?? [];
+		} catch (e) {
+			computedFingerprint = null;
+			note(chalk.dim(`Fingerprinting failed: ${e?.message || e}`));
+		}
+		if (!computedFingerprint) {
+			fail({
+				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."
+			});
+			return false;
+		}
+		fingerprint = computedFingerprint;
+		cacheKey = buildCacheKey("ios", fingerprint, {
+			scheme: buildScheme,
+			...configuration ? { configuration } : {},
+			isSimulator: !physical,
+			...buildProfile ? { buildProfile } : {}
+		});
+		stats.setCacheKey(cacheKey);
+		storeHash = fingerprint;
+		storeKey = cacheKey;
+		storeSources = fingerprintSources;
+		const found = await resolveTieredBuild({
+			local: filesystemBuildCapability({
+				resolve: d.resolveBuild,
+				store: d.storeBuild,
+				sources: fingerprintSources
+			}),
+			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;
+		let missDiff = "";
+		let missUntracked = null;
+		if (!cached) {
+			const lastBuild = d.readWorkspaceState(root)?.lastBuild ?? null;
+			const miss = describeFingerprintMiss({
+				platform: "ios",
+				current: {
+					hash: fingerprint,
+					sources: fingerprintSources
+				},
+				lastBuild
+			});
+			if (miss) {
+				missDiff = fingerprintDiffSuffix(miss.changed);
+				logWriter().write(fingerprintDiffRecord({
+					changed: miss.changed,
+					previousHash: miss.previousHash,
+					hash: fingerprint
+				}));
+			} else if (useBuildCache) missUntracked = untrackedMissLine(d.untrackedNativeFiles({ projectRoot: root }));
+		}
+		phase("fingerprint", `${shortHash(fingerprint)} ${cached ? "hit" : "miss"}${useBuildCache ? "" : opts.buildCache === false ? " (--no-build-cache)" : " (cache reuse off in config)"} ${fingerprintTimer()}${missDiff}`);
+		if (missUntracked) note(chalk.dim(phaseLine("fingerprint", missUntracked)));
+		if (found?.tier === "provider") {
+			cacheHit = "remote";
+			providerName = found.providerName ?? null;
+			phase("cache", `provider hit (${providerName})${found.storedLocally ? " -> stored locally" : ""}`);
+		}
+		appPath = found?.path ?? null;
+		return true;
+	}
+	async function resolveRemoteArtifact() {
+		if (physical || !cachePolicy.remote || buildProfile || buildScheme) return;
+		if (!appPath) {
+			const loaded = await d.loadProjectProvider(root, { isExpo });
+			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: configuration ? { configuration } : null
+			});
+			if (hit?.appPath) {
+				let stored = null;
+				try {
+					stored = d.storeBuild("ios", cacheKey, hit.appPath, { sources: fingerprintSources });
+				} 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()}`);
+		}
+	}
+	async function waitForSharedBuild() {
+		if (!useBuildCache) return true;
+		const waitStarted = d.now();
+		let failedHolder;
+		while (!appPath) {
+			let attempt = null;
+			try {
+				attempt = d.acquireBuildLock({
+					platform: "ios",
+					key: cacheKey,
+					root,
+					logFile
+				});
+			} catch (e) {
+				const refusal = claimFailure(e, "stim ios");
+				if (refusal) {
+					fail({
+						code: refusal.code,
+						message: refusal.message,
+						remedy: refusal.remedy,
+						build: {
+							fingerprint,
+							cacheKey,
+							cacheHit,
+							cacheSkipped: !useBuildCache
+						}
+					});
+					return false;
+				}
+				note(chalk.yellow(phaseLine("build", `could not take the build lock: ${e?.message || e}; building anyway`)));
+			}
+			if (attempt?.acquired) {
+				buildLock = attempt;
+				const previous = attempt.tookOver ?? failedHolder;
+				if (previous) note(chalk.yellow(phaseLine("build", takeoverLine(previous))));
+				break;
+			} else if (attempt?.held) {
+				releasedWait = null;
+				const held = attempt.held;
+				const who = held.projectRoot || "another workspace";
+				phase("build", `${who} is already building ${shortHash(fingerprint)} (pid ${held.pid})${held.logFile ? ` -- tail ${held.logFile}` : ""} -- stim guide lifecycle concurrency`);
+				let waited = null;
+				try {
+					const ceilingMs = WAIT_CEILING_MS - (d.now() - waitStarted);
+					if (ceilingMs <= 0) throw Object.assign(/* @__PURE__ */ new Error(`Waited ${formatDuration(d.now() - waitStarted)} for shared builds without an artifact; ${who} (pid ${held.pid}) holds ${attempt.path}.`), {
+						code: "STIM_BUILD_WAIT_TIMEOUT",
+						lockPath: attempt.path
+					});
+					waited = await d.waitForBuild({
+						platform: "ios",
+						key: cacheKey,
+						out: note,
+						ceilingMs
+					});
+				} catch (e) {
+					const refusal = claimFailure(e, "stim ios");
+					if (refusal) {
+						fail({
+							code: refusal.code,
+							message: refusal.message,
+							remedy: refusal.remedy,
+							build: {
+								fingerprint,
+								cacheKey,
+								cacheHit,
+								cacheSkipped: !useBuildCache
+							}
+						});
+						return false;
+					}
+					const err = e;
+					if (err?.code !== "STIM_BUILD_WAIT_TIMEOUT") throw e;
+					fail({
+						code: "STIM_BUILD_WAIT_TIMEOUT",
+						message: err.message,
+						remedy: `Check pid ${held.pid}; if it is not really building, remove ${err.lockPath} and run \`stim ios\` again.`,
+						build: {
+							fingerprint,
+							cacheKey,
+							cacheHit,
+							cacheSkipped: !useBuildCache
+						}
+					});
+					return false;
+				}
+				if (waited?.hit) {
+					appPath = waited.hit ?? null;
+					cacheHit = "local";
+					waitedForBuild = {
+						pid: held.pid,
+						ms: waited.waitedMs
+					};
+					phase("build", `waited ${formatDuration(waited.waitedMs)} for ${who}'s build -> installed from cache -- stim guide lifecycle concurrency`);
+				} else if (waited?.lockReleased) {
+					failedHolder = void 0;
+					releasedWait = {
+						facts: {
+							pid: held.pid,
+							ms: waited.waitedMs
+						},
+						who
+					};
+					phase("build", `${who}'s build lock was released; rechecking this workspace before building`);
+				} else {
+					note(chalk.yellow(phaseLine("build", `${who}'s build ended without an artifact (${waited?.builderFailed}); retrying the build lock`)));
+					failedHolder = held;
+				}
+			} else break;
+		}
+		return true;
+	}
+	const prepareDeviceApp = async (path, { fresh }) => {
+		const refuse = (code, reason, remedy) => {
+			if (fresh) {
+				fail({
+					code,
+					message: reason,
+					remedy,
+					build: {
+						...buildFailure,
+						appPath: path
+					}
+				});
+				return null;
+			}
+			note(chalk.yellow(phaseLine("cache", `${reason} -- building fresh instead`)));
+			note(chalk.dim(phaseLine("", remedy)));
+			swapFellBack = true;
+			return null;
+		};
+		const gateProfile = () => {
+			const gate = d.gateProfileForDevice({
+				appPath: path,
+				udid,
+				configuration
+			});
+			return gate.ok ? path : refuse(gate.code, gate.reason, gate.remedy);
+		};
+		if (release) {
+			if (!fresh) {
+				note(chalk.yellow(phaseLine("cache", `a cached ${configuration} device app carries its builder's JS, and the device JS swap lands with phase 6 of appandflow/stim#178 -- building fresh instead, which bakes in this workspace's JS`)));
+				swapFellBack = true;
+				return null;
+			}
+			return gateProfile();
+		}
+		if (d.devClientScheme(root, path)) return gateProfile();
+		let copy;
+		try {
+			copy = copyAppAside(path);
+		} catch (e) {
+			return refuse("STIM_INSTALL_FAILED", `Could not copy ${path} aside to write its ip.txt: ${e?.message || e}`, "Free space in the temporary directory and run the command again.");
+		}
+		writeIpTxt(copy.appPath, lanAddress, metroPort);
+		const sealed = d.sealAppForDevice({
+			appPath: copy.appPath,
+			udid,
+			configuration,
+			pinnedName: iosSigningIdentitySetting(settings),
+			pinnedSha1: iosSigningIdentitySha1Setting(settings)
+		});
+		if (!sealed.ok) {
+			try {
+				rmSync(copy.tmpDir, {
+					recursive: true,
+					force: true
+				});
+			} catch {}
+			for (const line of sealed.lastLines ?? []) note(chalk.dim(phaseLine("", line)));
+			return refuse(sealed.code, sealed.reason, sealed.remedy);
+		}
+		if (swapDir) try {
+			rmSync(swapDir, {
+				recursive: true,
+				force: true
+			});
+		} catch {}
+		swapDir = copy.tmpDir;
+		phase("ip.txt", `${lanAddress}:${metroPort} written into the install copy and re-sealed with "${sealed.identity.name}"${sealed.mode === "preserve-metadata" ? "" : ` (${sealed.mode})`}`);
+		return copy.appPath;
+	};
+	const installableCachedApp = async (cachedPath) => {
+		if (physical) return prepareDeviceApp(cachedPath, { fresh: false });
+		if (!release) return cachedPath;
+		phase("swap", `regenerating this workspace's JS for the cached ${configuration} app`);
+		const swap = await d.swapJsBundle({
+			root,
+			isExpo,
+			cachedAppPath: cachedPath,
+			logWriter: logWriter()
+		});
+		if (swap?.ok && swap.appPath) {
+			if (swap.note) note(chalk.yellow(phaseLine("swap", swap.note)));
+			swapDir = swap.tmpDir ?? null;
+			phase("swap", `${swap.hermes ? "hermes bytecode" : "plain JS"} + assets replaced, re-signed (${formatDuration(swap.durationMs ?? 0)})`);
+			return swap.appPath;
+		}
+		note(chalk.yellow(phaseLine("swap", `failed at ${swap?.step || "unknown step"}: ${swap?.reason || "unknown reason"} -- building fresh instead (a cached ${configuration} app carries its builder's JS; it is never installed after a failed swap)`)));
+		for (const line of swap?.lastLines ?? []) note(chalk.dim(phaseLine("", line)));
+		swapFellBack = true;
+		return null;
+	};
+	async function prepareCachedArtifact() {
+		if (appPath && cacheHit) {
+			const prepared = await installableCachedApp(appPath);
+			appPath = prepared;
+			if (!prepared) {
+				cacheHit = false;
+				waitedForBuild = null;
+			}
+		}
+	}
+	async function buildArtifact() {
+		buildFailure = {
+			fingerprint,
+			cacheKey,
+			cacheHit,
+			cacheSkipped: !useBuildCache
+		};
+		if (!appPath) try {
+			if (limits.maxBuilds) try {
+				buildSlot = await d.acquireBuildSlot({
+					max: limits.maxBuilds,
+					root,
+					logFile,
+					out: note
+				});
+			} catch (e) {
+				const refusal = claimFailure(e, "stim ios");
+				if (refusal) {
+					fail({
+						code: refusal.code,
+						message: refusal.message,
+						remedy: refusal.remedy,
+						build: buildFailure
+					});
+					return false;
+				}
+				note(chalk.yellow(phaseLine("build", `could not take a build slot: ${e?.message || e}; building anyway`)));
+			}
+			const mutatingSteps = [];
+			if (d.needsPrebuild(root, "ios", isExpo)) {
+				const result = await d.runPrebuild(root, "ios", logWriter());
+				if (result?.failed) {
+					phase("prebuild", "FAILED");
+					fail({
+						code: result.code || "STIM_PREBUILD_FAILED",
+						message: result.reason || "expo prebuild failed.",
+						remedy: result.remedy || `See ${logFile} for the transcript.`,
+						lines: (result.lastLines || []).slice(-5),
+						build: buildFailure
+					});
+					return false;
+				}
+				phase("prebuild", `ios/ absent -> generated (${formatDuration(result?.durationMs ?? 0)})`);
+				mutatingSteps.push("prebuild");
+			}
+			const podState = d.readPodState(root);
+			const action = podAction(podState, d.podsAreStale(podState.lockText, podState.manifestText));
+			if (action.install) {
+				const result = await d.runPodInstall(root, logWriter(), { estimateMs: estimates().podsMs });
+				const podCommand = result?.command || "pod install";
+				for (const line of result?.notes || []) note(chalk.dim(phaseLine("pods", line)));
+				if (result?.failed) {
+					phase("pods", "FAILED");
+					fail({
+						code: result.code || "STIM_DEPS_FAILED",
+						message: result.reason || "`pod install` failed.",
+						remedy: result.remedy || `See ${logFile} for the transcript.`,
+						lines: result.diagnosticLines?.length ? result.diagnosticLines : (result.lastLines || []).slice(-5),
+						build: buildFailure
+					});
+					return false;
+				}
+				stats.setPodsMs(result?.durationMs ?? 0);
+				phase("pods", `${action.reason} -> installed with \`${podCommand}\` (${formatDuration(result?.durationMs ?? 0)})`);
+				mutatingSteps.push(podCommand);
+			}
+			if (mutatingSteps.length) {
+				const after = await refingerprintAfterMutation({
+					projectRoot: root,
+					platform: "ios",
+					previousHash: fingerprint,
+					fingerprint: d.fingerprintProject
+				});
+				if (!after) {
+					storeHash = null;
+					storeKey = null;
+					buildFailure = {
+						...buildFailure,
+						fingerprint: null,
+						cacheKey: null
+					};
+					note(chalk.yellow(phaseLine("fingerprint", `unavailable after ${mutatingSteps.join(", ")}; the build will be installed but not cached`)));
+				} else if (after.moved) {
+					storeHash = after.hash;
+					storeSources = after.sources;
+					storeKey = buildCacheKey("ios", after.hash, {
+						scheme: buildScheme,
+						...configuration ? { configuration } : {},
+						isSimulator: !physical,
+						...buildProfile ? { buildProfile } : {}
+					});
+					note(chalk.dim(phaseLine("fingerprint", `${shortHash(fingerprint)} -> ${shortHash(storeHash)} (after ${mutatingSteps.join(", ")})`)));
+					const late = useBuildCache ? d.resolveBuild("ios", storeKey) : null;
+					if (late) {
+						const prepared = await installableCachedApp(late);
+						if (prepared) {
+							appPath = prepared;
+							cacheHit = "local";
+							phase("cache", `hit ${shortHash(storeHash)} (post-${mutatingSteps.join("/")} key)`);
+							if (releasedWait) {
+								waitedForBuild = releasedWait.facts;
+								phase("build", `waited ${formatDuration(waitedForBuild.ms)} for ${releasedWait.who}'s build -> installed from cache -- stim guide lifecycle concurrency`);
+							}
+						}
+					}
+				}
+			}
+			if (!appPath) {
+				phase("build", `compiling ${configuration || "Debug"} with xcodebuild`);
+				const result = await d.buildIos({
+					root,
+					scheme: buildScheme,
+					udid,
+					destination: remoteDevice ? GENERIC_SIM_DESTINATION : null,
+					...physical ? { sdk: IPHONEOS_SDK } : {},
+					logWriter: logWriter(),
+					...configuration ? { configuration } : {},
+					estimateMs: estimates().coldBuildMs,
+					optimizations: optimizations.ios
+				});
+				compilationCache = result.compilationCache ?? COMPILATION_CACHE_UNAVAILABLE;
+				phase("cache", `compilation cache ${compilationCacheActivityLine(compilationCache)}`);
+				if (result?.failed) {
+					phase("build", `FAILED after ${formatDuration(result.durationMs)}`);
+					printDiagnostics(note, result);
+					const report = xcodeFailureReport(result, logFile);
+					fail({
+						code: result.code || "STIM_BUILD_FAILED",
+						message: report.message,
+						remedy: report.remedy,
+						logPath: logFile,
+						build: buildFailure
+					});
+					return false;
+				}
+				stats.setBuildMs(result.durationMs ?? 0);
+				phase("build", `ok (${formatDuration(result.durationMs)})`);
+				appPath = result.appPath ?? null;
+				bundleId = result.bundleId ?? null;
+				if (storeKey && cachePolicy.write) try {
+					const stored = await storeTieredBuild({
+						local: filesystemBuildCapability({
+							resolve: d.resolveBuild,
+							store: d.storeBuild,
+							sources: storeSources
+						}),
+						loadProvider,
+						target: {
+							projectRoot: root,
+							platform: "ios",
+							key: storeKey
+						},
+						sourcePath: appPath,
+						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}`));
+				}
+				if (physical) {
+					const prepared = await prepareDeviceApp(appPath, { fresh: true });
+					if (!prepared) return false;
+					appPath = prepared;
+				}
+				if (remote && !physical && storeHash) uploadPending = d.uploadRemote({
+					logWriter: logWriter(),
+					provider: remote.provider,
+					platform: "ios",
+					projectRoot: root,
+					fingerprintHash: storeHash,
+					buildPath: appPath,
+					runOptions: configuration ? { configuration } : null
+				});
+			}
+		} finally {
+			releaseLock();
+			releaseSlot();
+		}
+		return true;
+	}
+	try {
+		if (!await resolveInitialFingerprint()) return null;
+		await resolveRemoteArtifact();
+		if (!await waitForSharedBuild()) return null;
+		await prepareCachedArtifact();
+		if (!await buildArtifact()) return null;
+		if (physicalDevice) {
+			const acquired = await d.acquireRunLease({
+				root,
+				platform: "ios",
+				id: physicalDevice.udid,
+				deviceName: physicalDevice.name,
+				idLabel: "udid",
+				waitSeconds,
+				noWait,
+				installBoundMs: DEVICECTL_INSTALL_TIMEOUT_MS,
+				appId: 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({
+				d,
+				root,
+				json,
+				release,
+				configuration,
+				buildScheme,
+				isExpo,
+				metroCheck,
+				metroPort,
+				logsDir,
+				logFile,
+				device,
+				udid,
+				physical,
+				lanAddress,
+				lanOriginUrl,
+				remoteDevice,
+				bootPromise,
+				bootDuration: () => bootDuration,
+				appPath,
+				bundleId,
+				swapDir,
+				buildFailure,
+				fail,
+				phase,
+				note,
+				logWriter,
+				uploadPending,
+				providerUpload,
+				providerName,
+				remote,
+				abandonedRemote,
+				elapsed,
+				startedAt,
+				storeHash,
+				storeKey,
+				cacheHit,
+				compilationCache,
+				useBuildCache,
+				waitedForBuild,
+				closeWriter: () => writer?.close?.(),
+				lease: leaseHandle,
+				releaseLease,
+				recordRun
+			});
+		} finally {
+			releaseLease();
+		}
+	} catch (error) {
+		recordRun({
+			failed: true,
+			durationMs: elapsed()
+		});
+		throw error;
+	}
+}
+//#endregion
+export { appNameFromPath, buildLogFile, cacheDescription, collectorEntry, iosCommand as default, devClientScheme, deviceLabel, ensureWorkspaceStorageSafely, formatDuration, gateShouldRetry, iosConfigurationSetting, iosFacts, isReleaseConfiguration, lastBuildRecord, noMetroMessage, phaseLine, pickDevClientScheme, podAction, registerIos, replaceCollector, resolveConfiguration, resolveDeviceType, resolveMetroWithRetry, resolveRuntime, schemesFromInfoPlist, shortHash, shortUdid, writeLastBuild };