stim 1.0.0 → 1.2.0

package/dist/device-remote-E81KAdXf.mjs

@@ -0,0 +1,1209 @@
+import { t as getExecutor } from "./exec-CyylIdq9.mjs";
+import { k as withDirLock, u as getConfigDir } from "./config-CMtIaTk9.mjs";
+import { D as workspaceLogsDir, O as workspaceName, T as workspaceDir, a as clearRemoteSession, c as readMetroTunnel, k as workspaceStateFile, u as readRemoteSession } from "./state-CZ-ER-8d.mjs";
+import { r as pidExists } from "./metro-COslRK_F.mjs";
+import { z as planMetroReach } from "./settings-DwU1_U_q.mjs";
+import { T as readMetroRecords, a as LAUNCH_ERROR, b as isBundleProof, p as devClientDeepLink, r as INSTALL_ERROR } from "./app-install-NFxUahnH.mjs";
+import { S as sanitizeDeviceLabel } from "./ios-D1h1Di39.mjs";
+import { t as withWorkspaceProcessLock } from "./workspace-process-lock-BKfdys1q.mjs";
+import { existsSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { homedir } from "node:os";
+//#region src/engine/metro-gate.ts
+const REMOTE_METRO_WRONG = "STIM_REMOTE_METRO_WRONG";
+const GATE_TIMEOUT_MS = 25e3;
+const POLL_MS = 250;
+function probeBundleUrl(origin, platform, entryPoint = "index") {
+	const entry = entryPoint.replace(/^\/+/, "").replace(/\.(?:[cm]?[jt]sx?)$/, "");
+	return `${origin.replace(/\/+$/, "")}/${entry}.bundle?platform=${platform}&dev=true`;
+}
+const defaultProbe = async (url, signal) => {
+	try {
+		return (await fetch(url, {
+			signal,
+			redirect: "follow"
+		})).status;
+	} catch {
+		return null;
+	}
+};
+async function gateMetroOrigin({ origin, metroPort, platform, entryPoint = "index", readRecords, isProof, probe = defaultProbe, now = Date.now, sleep = (ms) => new Promise((r) => setTimeout(r, ms)), timeoutMs = GATE_TIMEOUT_MS }) {
+	const since = now();
+	const controller = new AbortController();
+	const request = probe(probeBundleUrl(origin, platform, entryPoint), controller.signal);
+	request.catch(() => {});
+	try {
+		const deadline = now() + timeoutMs;
+		while (now() < deadline) {
+			for (const record of readRecords()) if (isProof(record, since)) return { ok: true };
+			await sleep(POLL_MS);
+		}
+	} finally {
+		controller.abort();
+	}
+	const status = await request.catch(() => null);
+	return {
+		failed: true,
+		code: REMOTE_METRO_WRONG,
+		reason: describeMiss(origin, metroPort, status),
+		remedy: `Check that ${origin} forwards to port ${metroPort} on THIS machine. A tunnel built for a port this workspace no longer holds will answer normally and serve a different project. \`stim start\` prints the port it reserved.`
+	};
+}
+function describeMiss(origin, metroPort, status) {
+	if (status === null) return `${origin} did not answer, so it cannot be this workspace's Metro (port ${metroPort}).`;
+	if (status >= 500) return `${origin} answered ${status}, so it reached a tunnel but not a dev server (port ${metroPort} may no longer be forwarded).`;
+	return `${origin} answered ${status}, but the request never reached THIS workspace's Metro on port ${metroPort} -- it is serving a different dev server.`;
+}
+//#endregion
+//#region src/engine/agent-device.ts
+const DAEMON_TOKEN_ENV = "AGENT_DEVICE_DAEMON_AUTH_TOKEN";
+const PROFILE_FILE = "agent-device.remote.json";
+function sessionNameFor(label) {
+	return `stim-${sanitizeDeviceLabel(label)}`;
+}
+function remoteProfilePath(root) {
+	return join(workspaceDir(root), PROFILE_FILE);
+}
+function remoteProfile({ daemon, platform, label }) {
+	const scope = sessionNameFor(label);
+	return {
+		daemonBaseUrl: daemon.baseUrl,
+		daemonTransport: "http",
+		platform,
+		session: scope,
+		tenant: scope,
+		runId: scope,
+		sessionIsolation: "tenant"
+	};
+}
+function daemonEnv(daemon) {
+	return { [DAEMON_TOKEN_ENV]: daemon.token };
+}
+function withProfile(profilePath, args) {
+	return [
+		...args,
+		"--remote-config",
+		profilePath
+	];
+}
+function connectArgs(profilePath) {
+	return withProfile(profilePath, ["connect", "--force"]);
+}
+function installArgs(profilePath, artifactPath) {
+	return withProfile(profilePath, ["install", artifactPath]);
+}
+function openArgs(profilePath, bundleId, url, metro = null) {
+	const positional = url ? [bundleId, url] : [bundleId];
+	const hint = metro ? [
+		"--metro-host",
+		metro.host,
+		"--metro-port",
+		metro.port
+	] : [];
+	return withProfile(profilePath, [
+		"open",
+		...positional,
+		"--relaunch",
+		...hint
+	]);
+}
+function metroHintFrom(origin) {
+	let url;
+	try {
+		url = new URL(origin);
+	} catch {
+		return null;
+	}
+	const port = url.port || (url.protocol === "https:" ? "443" : url.protocol === "http:" ? "80" : "");
+	return port ? {
+		host: url.hostname,
+		port
+	} : null;
+}
+function acceptAlertArgs(profilePath) {
+	return withProfile(profilePath, ["alert", "accept"]);
+}
+function disconnectArgs(profilePath) {
+	return withProfile(profilePath, ["disconnect"]);
+}
+function closeArgs(profilePath) {
+	return withProfile(profilePath, ["close"]);
+}
+//#endregion
+//#region src/engine/eas-simulator.ts
+const OWNED_PREFIX = "stim-";
+const LIVE_STATUSES$1 = ["new", "in-progress"];
+const LIVE_SESSION_STATUSES = /* @__PURE__ */ new Set(["NEW", "IN_PROGRESS"]);
+const TERMINAL_SESSION_STATUSES = /* @__PURE__ */ new Set(["STOPPED", "ERRORED"]);
+const SESSION_PLATFORMS = /* @__PURE__ */ new Set(["ios", "android"]);
+function ownedSessionName(label) {
+	const clean = sanitizeDeviceLabel(label);
+	return `${OWNED_PREFIX}${clean.startsWith(OWNED_PREFIX) ? clean.slice(5) : clean}`;
+}
+function isOwnedSessionName(name) {
+	return typeof name === "string" && name.startsWith(OWNED_PREFIX);
+}
+function createSessionArgs({ label, platform, maxDurationMinutes = null }) {
+	const args = [
+		"sim",
+		"--platform",
+		platform,
+		"--json",
+		"--non-interactive",
+		"--out-config-type",
+		"env",
+		"--name",
+		ownedSessionName(label)
+	];
+	if (maxDurationMinutes) args.push("--max-duration-minutes", String(maxDurationMinutes));
+	return args;
+}
+function getSessionArgs(sessionId) {
+	return [
+		"simulator:get",
+		"--id",
+		sessionId,
+		"--json",
+		"--non-interactive"
+	];
+}
+function stopSessionArgs(sessionId) {
+	return [
+		"simulator:stop",
+		"--id",
+		sessionId,
+		"--json",
+		"--non-interactive"
+	];
+}
+function listOwnedSessionsArgs(after = null) {
+	const args = [
+		"simulator:list",
+		"--name",
+		OWNED_PREFIX,
+		...LIVE_STATUSES$1.flatMap((s) => ["--status", s]),
+		"--limit",
+		"100",
+		"--json",
+		"--non-interactive"
+	];
+	if (after) args.push("--after", after);
+	return args;
+}
+function remoteDaemonFrom(config) {
+	if (!isRecord(config)) return null;
+	const typename = str(config["__typename"]);
+	if (typename && typename !== "AgentDeviceRunSessionRemoteConfig") return null;
+	const baseUrl = str(config.agentDeviceRemoteSessionUrl);
+	const token = str(config.agentDeviceRemoteSessionToken);
+	if (!baseUrl || !token) return null;
+	const daemon = {
+		baseUrl,
+		token
+	};
+	const preview = str(config.webPreviewUrl);
+	if (preview) daemon.webPreviewUrl = preview;
+	return daemon;
+}
+function parseJson(stdout) {
+	try {
+		return JSON.parse(stdout);
+	} catch {
+		return null;
+	}
+}
+function isRecord(value) {
+	return typeof value === "object" && value !== null;
+}
+function str(value) {
+	return typeof value === "string" && value.length > 0 ? value : null;
+}
+function inspectSessionForTeardown(stdout, sessionId) {
+	const data = parseJson(stdout);
+	if (!isRecord(data)) return {
+		action: "refused",
+		reason: `Session ${sessionId} lookup did not return valid JSON.`
+	};
+	const id = str(data.id);
+	if (!id) return {
+		action: "refused",
+		reason: `Session ${sessionId} lookup returned no session id.`
+	};
+	if (id !== sessionId) return {
+		action: "refused",
+		reason: `Session ${sessionId} lookup returned different session ${id}.`
+	};
+	const status = str(data.status);
+	if (!status) return {
+		action: "refused",
+		reason: `Session ${sessionId} lookup returned no status.`
+	};
+	const name = str(data.name);
+	if (!isOwnedSessionName(name)) return {
+		action: "refused",
+		reason: `Session ${sessionId} is not owned by Stim (name: ${name ?? "missing"}).`
+	};
+	if (TERMINAL_SESSION_STATUSES.has(status)) return {
+		action: "already-stopped",
+		name,
+		status
+	};
+	if (!LIVE_SESSION_STATUSES.has(status)) return {
+		action: "refused",
+		reason: `Session ${sessionId} has unknown status ${status}.`
+	};
+	return {
+		action: "stop",
+		name,
+		status
+	};
+}
+function isDefinitiveMissingSessionError(error, sessionId) {
+	const candidate = error;
+	const stderr = typeof candidate?.stderr === "string" ? candidate.stderr : "";
+	const message = typeof candidate?.message === "string" ? candidate.message : "";
+	const escapedSessionId = sessionId.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+	const missingSession = new RegExp(`(?:device[\\s-]*run[\\s-]*session|simulator[\\s-]*session)[\\s:#]*\\b${escapedSessionId}\\b[\\s,:]*(?:(?:was\\s+)?not\\s+found|does\\s+not\\s+exist)\\b`, "i");
+	return `${stderr}\n${message}`.split(/\r?\n/).map((line) => line.replace(/\s+/g, " ").trim()).some((line) => missingSession.test(line));
+}
+function verifyStoppedSession(stdout, sessionId) {
+	const stopped = parseStoppedSession(stdout);
+	if (!stopped) return {
+		ok: false,
+		reason: `Stop for session ${sessionId} did not return valid JSON with an id.`
+	};
+	if (stopped.id !== sessionId) return {
+		ok: false,
+		reason: `Stop for session ${sessionId} returned different session ${stopped.id}.`
+	};
+	if (!stopped.status || !TERMINAL_SESSION_STATUSES.has(stopped.status)) return {
+		ok: false,
+		reason: `Stop for session ${sessionId} returned unknown status ${stopped.status ?? "missing"}.`
+	};
+	return { ok: true };
+}
+function parseCreatedSession(stdout) {
+	const data = parseJson(stdout);
+	if (!isRecord(data)) return null;
+	const id = str(data.id);
+	if (!id) return null;
+	return {
+		id,
+		name: str(data.name),
+		url: str(data.deviceRunSessionUrl),
+		daemon: remoteDaemonFrom(data.remoteConfig)
+	};
+}
+function parseSessionListPage(stdout) {
+	const data = parseJson(stdout);
+	if (!isRecord(data) || !Array.isArray(data.sessions)) return {
+		ok: false,
+		reason: "EAS session list did not return valid JSON with a sessions array."
+	};
+	if (!isRecord(data.pageInfo) || typeof data.pageInfo.hasNextPage !== "boolean") return {
+		ok: false,
+		reason: "EAS session list page did not return valid pagination information."
+	};
+	const endCursor = data.pageInfo.endCursor;
+	if (endCursor !== null && typeof endCursor !== "string") return {
+		ok: false,
+		reason: "EAS session list returned a malformed pagination cursor."
+	};
+	return {
+		ok: true,
+		page: {
+			sessions: data.sessions,
+			hasNextPage: data.pageInfo.hasNextPage,
+			endCursor
+		}
+	};
+}
+function findOrphanedOwnedSessions({ sessions, recordedSessionIds, projectScope }) {
+	const scope = typeof projectScope === "string" ? projectScope.trim() : "";
+	if (!scope) return {
+		orphaned: [],
+		notices: ["EAS session list has no current-project scope."]
+	};
+	const recorded = new Set(recordedSessionIds.filter((id) => typeof id === "string" && id.length > 0));
+	const candidates = /* @__PURE__ */ new Map();
+	const conflicts = /* @__PURE__ */ new Set();
+	const blocked = /* @__PURE__ */ new Set();
+	const notices = [];
+	for (const raw of sessions) {
+		if (!isRecord(raw)) {
+			notices.push("EAS session list contains a malformed entry.");
+			continue;
+		}
+		const id = str(raw.id);
+		const name = str(raw.name);
+		if (!id) {
+			if (isOwnedSessionName(name)) notices.push("EAS session list contains an owned entry with no session id.");
+			continue;
+		}
+		if (!name) {
+			blocked.add(id);
+			candidates.delete(id);
+			notices.push(`EAS session ${id} has no name and cannot be classified as Stim-owned.`);
+			continue;
+		}
+		if (!isOwnedSessionName(name)) continue;
+		const status = str(raw.status)?.toUpperCase().replace(/-/g, "_") ?? null;
+		if (!status) {
+			blocked.add(id);
+			candidates.delete(id);
+			notices.push(`Owned EAS session ${id} has no status.`);
+			continue;
+		}
+		if (TERMINAL_SESSION_STATUSES.has(status)) continue;
+		if (!LIVE_SESSION_STATUSES.has(status)) {
+			blocked.add(id);
+			candidates.delete(id);
+			notices.push(`Owned EAS session ${id} has unknown status ${status}.`);
+			continue;
+		}
+		const platformValue = str(raw.platform);
+		const normalizedPlatform = platformValue?.toLowerCase() ?? null;
+		if (!normalizedPlatform || !SESSION_PLATFORMS.has(normalizedPlatform)) {
+			blocked.add(id);
+			candidates.delete(id);
+			notices.push(platformValue ? `Owned EAS session ${id} has unknown platform ${platformValue}.` : `Owned EAS session ${id} has no platform.`);
+			continue;
+		}
+		if (recorded.has(id) || blocked.has(id)) continue;
+		const candidate = {
+			id,
+			name,
+			status,
+			platform: normalizedPlatform,
+			projectScope: scope
+		};
+		const previous = candidates.get(id);
+		if (!previous) {
+			candidates.set(id, candidate);
+			continue;
+		}
+		if (previous.name !== candidate.name || previous.status !== candidate.status || previous.platform !== candidate.platform) {
+			conflicts.add(id);
+			candidates.delete(id);
+			notices.push(`EAS session list contains conflicting entries for session ${id}.`);
+		}
+	}
+	for (const id of [...conflicts, ...blocked]) candidates.delete(id);
+	return {
+		orphaned: [...candidates.values()],
+		notices
+	};
+}
+function parseStoppedSession(stdout) {
+	const data = parseJson(stdout);
+	if (!isRecord(data)) return null;
+	const id = str(data.id);
+	if (!id) return null;
+	return {
+		id,
+		status: str(data.status)
+	};
+}
+//#endregion
+//#region src/engine/eas-session-ledger.ts
+function easMachineStateRoot() {
+	return join(homedir(), ".stim", "machine", "eas");
+}
+function easSessionLedgerFile(root = easMachineStateRoot()) {
+	return join(root, "sessions.json");
+}
+function validClaim(id, value) {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+	const claim = value;
+	if (claim.sessionId !== id) return null;
+	if (typeof claim.name !== "string" || !claim.name.startsWith("stim-")) return null;
+	if (claim.platform !== "ios" && claim.platform !== "android") return null;
+	if (typeof claim.workspaceRoot !== "string" || !isAbsolute(claim.workspaceRoot)) return null;
+	if (typeof claim.workspaceHome !== "string" || !isAbsolute(claim.workspaceHome)) return null;
+	if (typeof claim.stateFile !== "string" || !isAbsolute(claim.stateFile)) return null;
+	const workspaceRoot = resolve(claim.workspaceRoot);
+	const workspaceHome = resolve(claim.workspaceHome);
+	const stateFile = resolve(claim.stateFile);
+	const stateRelative = relative(workspaceHome, stateFile);
+	if (!stateRelative || stateRelative.startsWith("..") || isAbsolute(stateRelative)) return null;
+	if (stateFile !== join(workspaceHome, "workspaces", workspaceName(workspaceRoot), "state.json")) return null;
+	return {
+		sessionId: id,
+		name: claim.name,
+		platform: claim.platform,
+		workspaceRoot,
+		workspaceHome,
+		stateFile
+	};
+}
+function readEasSessionLedger(root = easMachineStateRoot()) {
+	const file = easSessionLedgerFile(root);
+	if (!existsSync(file)) return {
+		claims: /* @__PURE__ */ new Map(),
+		notice: null,
+		safe: true
+	};
+	let parsed;
+	try {
+		parsed = JSON.parse(readFileSync(file, "utf-8"));
+	} catch (error) {
+		return {
+			claims: /* @__PURE__ */ new Map(),
+			notice: `EAS ownership ledger ${file} is unreadable: ${error.message}`,
+			safe: false
+		};
+	}
+	if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return {
+		claims: /* @__PURE__ */ new Map(),
+		notice: `EAS ownership ledger ${file} is malformed.`,
+		safe: false
+	};
+	const ledger = parsed;
+	if (ledger.version !== 1 || !ledger.claims || typeof ledger.claims !== "object" || Array.isArray(ledger.claims)) return {
+		claims: /* @__PURE__ */ new Map(),
+		notice: `EAS ownership ledger ${file} is malformed.`,
+		safe: false
+	};
+	const claims = /* @__PURE__ */ new Map();
+	for (const [id, value] of Object.entries(ledger.claims)) {
+		const claim = validClaim(id, value);
+		if (!claim) return {
+			claims: /* @__PURE__ */ new Map(),
+			notice: `EAS ownership ledger ${file} is malformed.`,
+			safe: false
+		};
+		claims.set(id, claim);
+	}
+	return {
+		claims,
+		notice: null,
+		safe: true
+	};
+}
+function writeLedger(root, ledger) {
+	mkdirSync(root, { recursive: true });
+	const file = easSessionLedgerFile(root);
+	const tmp = `${file}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`;
+	writeFileSync(tmp, `${JSON.stringify(ledger, null, 2)}\n`);
+	try {
+		renameSync(tmp, file);
+	} catch (error) {
+		rmSync(tmp, { force: true });
+		throw error;
+	}
+}
+function recordEasSessionClaim(claim, root = easMachineStateRoot()) {
+	const normalized = validClaim(claim.sessionId, claim);
+	if (!normalized) throw new Error(`Invalid EAS session claim for ${claim.sessionId}.`);
+	withDirLock(join(root, "ledger.lock"), () => {
+		const current = readEasSessionLedger(root);
+		if (!current.safe) throw new Error(current.notice ?? "EAS ownership ledger is unreadable.");
+		current.claims.set(normalized.sessionId, normalized);
+		writeLedger(root, {
+			version: 1,
+			claims: Object.fromEntries(current.claims)
+		});
+	}, { ensureParent: () => mkdirSync(dirname(join(root, "ledger.lock")), { recursive: true }) });
+}
+function removeEasSessionClaim(sessionId, root = easMachineStateRoot()) {
+	const file = easSessionLedgerFile(root);
+	if (!existsSync(file)) return false;
+	return withDirLock(join(root, "ledger.lock"), () => {
+		const current = readEasSessionLedger(root);
+		if (!current.safe) return false;
+		if (!current.claims.delete(sessionId)) return false;
+		writeLedger(root, {
+			version: 1,
+			claims: Object.fromEntries(current.claims)
+		});
+		return true;
+	});
+}
+//#endregion
+//#region src/engine/eas-project-lock.ts
+const EAS_PROJECT_LOCK_WAIT_MS = 24e4;
+function withEasProjectLock(_root, fn, options = {}) {
+	const { machineRoot = easMachineStateRoot(), ...lockOptions } = options;
+	return withWorkspaceProcessLock(machineRoot, "eas-project", fn, {
+		waitMs: EAS_PROJECT_LOCK_WAIT_MS,
+		...lockOptions,
+		external: true
+	});
+}
+//#endregion
+//#region src/engine/device-remote.ts
+const REMOTE_SESSION_ERROR = "STIM_NO_REMOTE_SESSION";
+const REMOTE_METRO_ERROR = "STIM_REMOTE_METRO_UNREACHABLE";
+function resolveMetroOrigin({ metroPort, publicUrl = null, mode = "auto", isExpo = false, available = [] }) {
+	const plan = planMetroReach({
+		mode,
+		metroPort,
+		publicUrl,
+		isExpo,
+		available
+	});
+	if ("origin" in plan) return plan;
+	if ("failed" in plan) return plan;
+	return {
+		failed: "Metro has no address the device can reach yet.",
+		remedy: "This is a Stim bug: the tunnel step did not run before the launch."
+	};
+}
+function describe(err) {
+	const e = err;
+	return (typeof e?.stderr === "string" ? e.stderr.trim() : "") || String(e?.message ?? err);
+}
+const PROXY_CREDENTIAL_ENV = ["AGENT_DEVICE_DAEMON_BASE_URL", "AGENT_DEVICE_DAEMON_AUTH_TOKEN"];
+function easExecOptions(root) {
+	return {
+		cwd: root,
+		omitEnv: PROXY_CREDENTIAL_ENV
+	};
+}
+const EAS_OPERATION_TIMEOUT_MS = 3e4;
+function easBoundedExecOptions(root) {
+	return {
+		...easExecOptions(root),
+		timeoutMs: EAS_OPERATION_TIMEOUT_MS
+	};
+}
+function writeProfile(ctx, daemon) {
+	const path = remoteProfilePath(ctx.root);
+	mkdirSync(dirname(path), { recursive: true });
+	const profile = remoteProfile({
+		daemon,
+		platform: ctx.platform ?? "ios",
+		label: ctx.label
+	});
+	writeFileSync(path, `${JSON.stringify(profile, null, 2)}\n`);
+	return path;
+}
+function remoteDeviceDeps(ctx) {
+	let session = null;
+	let createdSession = null;
+	const easEnv = easExecOptions(ctx.root);
+	return {
+		checkCapacity: () => null,
+		ensureDevice: async () => ({
+			deviceName: ctx.backend === "proxy" ? "remote device (your daemon)" : "EAS Simulator",
+			owned: true,
+			remote: true
+		}),
+		ensureBooted: async ({ out = () => {} } = {}) => {
+			session = null;
+			createdSession = null;
+			const note = (message) => {
+				try {
+					out(message);
+				} catch {}
+			};
+			let daemon = ctx.existingDaemon ?? null;
+			let id = null;
+			let createdHere = null;
+			if (!daemon) {
+				const recorded = readRemoteSession(ctx.root);
+				if (recorded && recorded.platform !== (ctx.platform ?? "ios")) return {
+					failed: true,
+					code: "STIM_REMOTE_PLATFORM_MISMATCH",
+					reason: `Session ${recorded.sessionId} belongs to ${recorded.platform ?? "an unknown platform"}, not ${ctx.platform ?? "ios"}.`,
+					remedy: "Run `stim stop` for this workspace before selecting a different remote platform."
+				};
+				if (recorded) {
+					const existing = readLiveDaemon(ctx, recorded.sessionId);
+					if (existing) {
+						note(`Reusing EAS Simulator session ${recorded.sessionId}.`);
+						daemon = existing;
+						id = recorded.sessionId;
+					} else {
+						note(`Recorded session ${recorded.sessionId} is not usable; verifying it before replacement.`);
+						const cleanup = teardownRemote(ctx, { sessionId: recorded.sessionId });
+						if (cleanup.status === "failed" || cleanup.reason) return {
+							failed: true,
+							code: "STIM_REMOTE_SESSION_CLEANUP",
+							reason: cleanup.reason ?? `Could not verify recorded EAS session ${recorded.sessionId}.`,
+							remedy: "Inspect the recorded session, then run `stim stop` again."
+						};
+						clearRemoteSession(ctx.root, recorded.sessionId);
+					}
+				}
+			}
+			if (!daemon) {
+				note("Creating an EAS Simulator session (this takes a moment).");
+				let stdout;
+				try {
+					stdout = getExecutor().runFile(ctx.easBin, createSessionArgs({
+						label: ctx.label,
+						platform: ctx.platform ?? "ios",
+						maxDurationMinutes: ctx.maxDurationMinutes ?? null
+					}), easEnv);
+				} catch (err) {
+					return {
+						failed: true,
+						reason: `eas sim failed: ${describe(err)}`
+					};
+				}
+				const created = parseCreatedSession(stdout);
+				if (!created) return {
+					failed: true,
+					reason: "eas sim returned no session; run it by hand to see what it reported."
+				};
+				id = created.id;
+				createdHere = created.id;
+				daemon = created.daemon ?? await waitForDaemon(ctx, created.id, note, { sleep: ctx.sleep ?? defaultSleep });
+				if (!daemon) return abandonSession(ctx, created.id, `Session ${created.id} never published an agent-device endpoint. It may be an appium or argent session rather than an agent-device one.`);
+			}
+			let profilePath;
+			try {
+				profilePath = writeProfile(ctx, daemon);
+			} catch (err) {
+				const reason = `Could not write the remote connection profile: ${describe(err)}`;
+				if (createdHere) return abandonSession(ctx, createdHere, reason);
+				return {
+					failed: true,
+					reason
+				};
+			}
+			try {
+				getExecutor().runFile(ctx.agentDeviceBin, closeArgs(profilePath), {
+					cwd: ctx.root,
+					env: daemonEnv(daemon)
+				});
+			} catch {}
+			try {
+				getExecutor().runFile(ctx.agentDeviceBin, connectArgs(profilePath), {
+					cwd: ctx.root,
+					env: daemonEnv(daemon)
+				});
+			} catch (err) {
+				if (createdHere) return abandonSession(ctx, createdHere, `agent-device connect failed: ${describe(err)}`);
+				return {
+					failed: true,
+					reason: `agent-device connect failed: ${describe(err)}`
+				};
+			}
+			session = {
+				id,
+				daemon,
+				profilePath
+			};
+			createdSession = createdHere;
+			if (daemon.webPreviewUrl) note(`Watch this device: ${daemon.webPreviewUrl}`);
+			return {
+				ok: true,
+				udid: id ?? daemonHostLabel(daemon.baseUrl)
+			};
+		},
+		installArtifact: (artifactPath) => {
+			if (!session) return notConnected(INSTALL_ERROR);
+			try {
+				getExecutor().runFile(ctx.agentDeviceBin, installArgs(session.profilePath, artifactPath), {
+					cwd: ctx.root,
+					env: daemonEnv(session.daemon)
+				});
+				return {
+					ok: true,
+					appPath: artifactPath
+				};
+			} catch (err) {
+				return {
+					failed: true,
+					code: INSTALL_ERROR,
+					reason: `agent-device install failed for ${artifactPath}: ${describe(err)}`
+				};
+			}
+		},
+		launchApp: ({ appId, metroPort, devClientScheme = null }) => {
+			if (!session) return notConnected(LAUNCH_ERROR);
+			if (metroPort === null) try {
+				getExecutor().runFile(ctx.agentDeviceBin, openArgs(session.profilePath, appId, null, null), {
+					cwd: ctx.root,
+					env: daemonEnv(session.daemon)
+				});
+				return {
+					ok: true,
+					mode: "launch"
+				};
+			} catch (err) {
+				return {
+					failed: true,
+					code: LAUNCH_ERROR,
+					reason: `agent-device open ${appId} failed: ${describe(err)}`
+				};
+			}
+			const origin = resolveMetroOrigin({
+				metroPort,
+				publicUrl: ctx.publicMetroUrl ?? null,
+				mode: ctx.tunnelMode ?? "auto",
+				isExpo: ctx.isExpo ?? false
+			});
+			if ("failed" in origin) return {
+				failed: true,
+				code: REMOTE_METRO_ERROR,
+				reason: `${origin.failed} ${origin.remedy}`
+			};
+			const url = devClientScheme ? devClientDeepLink(devClientScheme, origin.origin) : null;
+			try {
+				getExecutor().runFile(ctx.agentDeviceBin, openArgs(session.profilePath, appId, url, metroHintFrom(origin.origin)), {
+					cwd: ctx.root,
+					env: daemonEnv(session.daemon)
+				});
+				if (url) try {
+					getExecutor().runFile(ctx.agentDeviceBin, acceptAlertArgs(session.profilePath), {
+						cwd: ctx.root,
+						env: daemonEnv(session.daemon)
+					});
+				} catch {}
+				return {
+					ok: true,
+					mode: url ? "openurl" : "launch",
+					url: url ?? void 0,
+					jsLocation: origin.origin
+				};
+			} catch (err) {
+				return {
+					failed: true,
+					code: LAUNCH_ERROR,
+					reason: `agent-device open ${appId} failed: ${describe(err)}`
+				};
+			}
+		},
+		createdSessionId: () => createdSession,
+		abandonCreatedSession: () => {
+			if (!createdSession) return {
+				ok: true,
+				sessionId: null
+			};
+			const stopped = stopCreatedSession(ctx, createdSession);
+			if (stopped.ok) {
+				session = null;
+				createdSession = null;
+			}
+			return stopped;
+		},
+		webPreviewUrl: () => session?.daemon.webPreviewUrl ?? null
+	};
+}
+async function resolveRemoteContext({ root, label, backend, platform = "ios", easBin, env = process.env, lookupAgentDevice = defaultLookupAgentDevice, maxDurationMinutes = null }) {
+	const agentDeviceBin = lookupAgentDevice();
+	if (!agentDeviceBin) return {
+		failed: "agent-device is not on PATH, and it is what drives a remote device.",
+		remedy: `Install it (\`npm i -g agent-device\`), then run \`stim ${platform} --remote ${backend}\` again.`
+	};
+	const baseUrl = env.AGENT_DEVICE_DAEMON_BASE_URL?.trim();
+	const token = env.AGENT_DEVICE_DAEMON_AUTH_TOKEN?.trim();
+	let existingDaemon = null;
+	if (backend === "proxy") {
+		if (!baseUrl && !token) return {
+			failed: "The proxy backend requires AGENT_DEVICE_DAEMON_BASE_URL and AGENT_DEVICE_DAEMON_AUTH_TOKEN.",
+			remedy: "Export AGENT_DEVICE_DAEMON_BASE_URL and AGENT_DEVICE_DAEMON_AUTH_TOKEN, then run the device command with `--remote proxy` again.",
+			code: "STIM_REMOTE_PROXY_CONFIG"
+		};
+		if (!baseUrl) return {
+			failed: "The proxy backend requires AGENT_DEVICE_DAEMON_BASE_URL.",
+			remedy: "Export AGENT_DEVICE_DAEMON_BASE_URL, then run the device command with `--remote proxy` again.",
+			code: "STIM_REMOTE_PROXY_CONFIG"
+		};
+		if (!token) return {
+			failed: "The proxy backend requires AGENT_DEVICE_DAEMON_AUTH_TOKEN.",
+			remedy: "Export AGENT_DEVICE_DAEMON_AUTH_TOKEN, then run the device command with `--remote proxy` again.",
+			code: "STIM_REMOTE_PROXY_CONFIG"
+		};
+		existingDaemon = {
+			baseUrl,
+			token
+		};
+	} else if (!easBin) return {
+		failed: "The eas backend requires eas-cli.",
+		remedy: "Install eas-cli, then run the device command with `--remote eas` again.",
+		code: "STIM_REMOTE_EAS_UNAVAILABLE"
+	};
+	return { ctx: {
+		root,
+		label,
+		backend,
+		platform,
+		easBin: easBin ?? "",
+		agentDeviceBin,
+		maxDurationMinutes,
+		publicMetroUrl: null,
+		existingDaemon
+	} };
+}
+function binOnPath(bin) {
+	try {
+		return Boolean(getExecutor().runQuiet(`command -v ${bin}`, { timeoutMs: 5e3 }));
+	} catch {
+		return false;
+	}
+}
+function defaultLookupAgentDevice() {
+	const found = getExecutor().runQuiet("command -v agent-device", { timeoutMs: 5e3 });
+	return (String(found ?? "").split("\n")[0] ?? "").trim() || null;
+}
+const DAEMON_WAIT_MS = 18e4;
+const DAEMON_POLL_MS = 5e3;
+async function waitForDaemon(ctx, sessionId, out, { sleep = defaultSleep } = {}) {
+	const attempts = Math.ceil(DAEMON_WAIT_MS / DAEMON_POLL_MS);
+	for (let attempt = 0; attempt < attempts; attempt++) {
+		const daemon = readDaemon(ctx, sessionId);
+		if (daemon) return daemon;
+		if (attempt === 0) out(`Waiting for session ${sessionId} to become reachable.`);
+		await sleep(DAEMON_POLL_MS);
+	}
+	return null;
+}
+function defaultSleep(ms) {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function stopCreatedSession(ctx, sessionId) {
+	let stopOutput;
+	try {
+		stopOutput = getExecutor().runFile(ctx.easBin, stopSessionArgs(sessionId), easBoundedExecOptions(ctx.root));
+	} catch (err) {
+		return {
+			failed: true,
+			code: "STIM_REMOTE_SESSION_CLEANUP",
+			reason: `Stim could not stop session ${sessionId} (${describe(err)}). The session bills until its cap.`,
+			remedy: `Run \`eas simulator:stop --id ${sessionId}\`.`,
+			sessionId
+		};
+	}
+	const verified = verifyStoppedSession(stopOutput, sessionId);
+	if (!verified.ok) return {
+		failed: true,
+		code: "STIM_REMOTE_SESSION_CLEANUP",
+		reason: `Stim could not verify that session ${sessionId} stopped (${verified.reason}). The session bills until its cap.`,
+		remedy: `Run \`eas simulator:stop --id ${sessionId}\`.`,
+		sessionId
+	};
+	return {
+		ok: true,
+		sessionId
+	};
+}
+function abandonSession(ctx, sessionId, reason) {
+	const stopped = stopCreatedSession(ctx, sessionId);
+	if (stopped.ok) return {
+		failed: true,
+		reason: `${reason} The session was stopped.`
+	};
+	return {
+		failed: true,
+		code: stopped.code,
+		reason: `${reason} ${stopped.reason} ${stopped.remedy}`,
+		remedy: stopped.remedy
+	};
+}
+function withRemoteSessionLock(root, fn, options = {}) {
+	let canonicalRoot;
+	try {
+		canonicalRoot = realpathSync(root);
+	} catch {
+		canonicalRoot = resolve(root);
+	}
+	return withWorkspaceProcessLock(workspaceDir(canonicalRoot), "remote-session", fn, {
+		external: true,
+		waitMs: 24e4,
+		...options
+	});
+}
+async function ensureRemoteBootOwned({ root, platform, sessionName, startedAt, boot, createdSessionId, abandonCreatedSession, writeState, register = () => {}, withProjectLock = withEasProjectLock, withLock = withRemoteSessionLock, removeEasSessionClaim: removeClaim = removeEasSessionClaim, ledgerRoot = easMachineStateRoot() }) {
+	try {
+		return await withProjectLock(root, () => withLock(root, async () => {
+			register();
+			const booted = await boot();
+			if (booted.failed) return booted;
+			const sessionId = createdSessionId();
+			if (!sessionId) return booted;
+			try {
+				recordEasSessionClaim({
+					sessionId,
+					name: sessionName,
+					platform,
+					workspaceRoot: root,
+					workspaceHome: getConfigDir(),
+					stateFile: workspaceStateFile(root)
+				}, ledgerRoot);
+				writeState(root, { remoteDevice: {
+					platform,
+					sessionId,
+					startedAt
+				} });
+				return booted;
+			} catch (err) {
+				const cleanup = abandonCreatedSession();
+				if (cleanup.ok) {
+					let removalFailure = "the claim store did not remove it";
+					try {
+						if (removeClaim(sessionId, ledgerRoot)) return {
+							failed: true,
+							code: "STIM_REMOTE_SESSION_STATE",
+							reason: `Could not record EAS session ${sessionId}: ${describe(err)}. The session was stopped.`,
+							remedy: "Fix workspace state storage, then retry the remote command."
+						};
+					} catch (error) {
+						removalFailure = describe(error);
+					}
+					return {
+						failed: true,
+						code: "STIM_REMOTE_SESSION_CLEANUP",
+						reason: `Could not record EAS session ${sessionId}: ${describe(err)}. The session was stopped, but its ownership claim could not be removed: ${removalFailure}.`,
+						remedy: `The stopped session claim remains under ${ledgerRoot}. Repair that ownership ledger before retrying the remote command.`
+					};
+				}
+				return {
+					failed: true,
+					code: cleanup.code ?? "STIM_REMOTE_SESSION_CLEANUP",
+					reason: `Could not record EAS session ${sessionId}: ${describe(err)}. ${cleanup.reason ?? ""}`.trim(),
+					remedy: cleanup.remedy ?? `Run \`eas simulator:stop --id ${sessionId}\`.`
+				};
+			}
+		}), {
+			ownerPurpose: "EAS remote start",
+			machineRoot: ledgerRoot
+		});
+	} catch (err) {
+		return {
+			failed: true,
+			code: err.code ?? "STIM_NO_REMOTE_SESSION",
+			reason: describe(err),
+			remedy: "Retry the remote command after the other workspace operation finishes."
+		};
+	}
+}
+function daemonHostLabel(baseUrl) {
+	try {
+		return new URL(baseUrl).host;
+	} catch {
+		return baseUrl;
+	}
+}
+function notConnected(code) {
+	return {
+		failed: true,
+		code,
+		reason: "No remote session is connected; the device step did not complete."
+	};
+}
+const LIVE_STATUSES = /* @__PURE__ */ new Set(["NEW", "IN_PROGRESS"]);
+function readLiveDaemon(ctx, sessionId) {
+	let stdout;
+	try {
+		stdout = getExecutor().runFile(ctx.easBin, getSessionArgs(sessionId), easBoundedExecOptions(ctx.root));
+	} catch {
+		return null;
+	}
+	try {
+		const inspection = inspectSessionForTeardown(stdout, sessionId);
+		if (inspection.action !== "stop" || !LIVE_STATUSES.has(inspection.status)) return null;
+		return remoteDaemonFrom(JSON.parse(stdout).remoteConfig);
+	} catch {
+		return null;
+	}
+}
+function readDaemon(ctx, sessionId) {
+	let stdout;
+	try {
+		stdout = getExecutor().runFile(ctx.easBin, getSessionArgs(sessionId), easBoundedExecOptions(ctx.root));
+	} catch {
+		return null;
+	}
+	try {
+		return remoteDaemonFrom(JSON.parse(stdout).remoteConfig);
+	} catch {
+		return null;
+	}
+}
+function remoteIosDeps(ctx) {
+	const shared = {
+		...ctx,
+		platform: "ios"
+	};
+	const core = remoteDeviceDeps(shared);
+	return {
+		ctx: shared,
+		checkDeviceCapacity: core.checkCapacity,
+		ensureOwnedDevice: core.ensureDevice,
+		ensureBooted: core.ensureBooted,
+		installIosApp: ({ appPath }) => core.installArtifact(appPath),
+		launchIosApp: ({ bundleId, metroPort, devClientScheme }) => core.launchApp({
+			appId: bundleId,
+			metroPort,
+			devClientScheme
+		}),
+		createdSessionId: core.createdSessionId,
+		abandonCreatedSession: core.abandonCreatedSession,
+		webPreviewUrl: core.webPreviewUrl
+	};
+}
+function remoteAndroidDeps(ctx) {
+	const shared = {
+		...ctx,
+		platform: "android"
+	};
+	const core = remoteDeviceDeps(shared);
+	return {
+		ctx: shared,
+		checkCapacity: core.checkCapacity,
+		ensureDevice: core.ensureDevice,
+		ensureDeviceBooted: async (opts) => {
+			const booted = await core.ensureBooted(opts);
+			return booted.ok ? {
+				ok: true,
+				serial: booted.udid
+			} : booted;
+		},
+		install: ({ apkPath }) => core.installArtifact(apkPath),
+		launch: ({ packageName, metroPort, devClientScheme }) => core.launchApp({
+			appId: packageName,
+			metroPort,
+			devClientScheme
+		}),
+		createdSessionId: core.createdSessionId,
+		abandonCreatedSession: core.abandonCreatedSession,
+		webPreviewUrl: core.webPreviewUrl
+	};
+}
+function endRecordedSession({ root, sessionId, easBin, lookupAgentDevice, ledgerRoot }) {
+	const agentDeviceBin = (lookupAgentDevice ?? defaultLookupAgentDevice)();
+	if (!easBin) return {
+		status: "failed",
+		reason: `No eas-cli to stop session ${sessionId} with; it keeps billing until its max duration. Run \`eas simulator:stop --id ${sessionId}\`.`
+	};
+	return teardownRemote({
+		root,
+		label: "",
+		backend: "eas",
+		easBin,
+		agentDeviceBin: agentDeviceBin ?? "",
+		existingDaemon: null,
+		easLedgerRoot: ledgerRoot
+	}, { sessionId });
+}
+function teardownRemote(ctx, { sessionId }) {
+	const profilePath = remoteProfilePath(ctx.root);
+	try {
+		getExecutor().runFile(ctx.agentDeviceBin, disconnectArgs(profilePath), { cwd: ctx.root });
+	} catch {}
+	if (!sessionId) return { status: "torn-down" };
+	const ledger = readEasSessionLedger(ctx.easLedgerRoot);
+	const claimNeedsRemoval = !ledger.safe || ledger.claims.has(sessionId);
+	const removeClaim = () => {
+		try {
+			if ((ctx.removeEasSessionClaim ?? removeEasSessionClaim)(sessionId, ctx.easLedgerRoot) || !claimNeedsRemoval) return void 0;
+			return `EAS session ${sessionId} is stopped, but its ownership claim could not be removed. The claim and workspace record were kept for reconciliation. Re-run stop.`;
+		} catch (error) {
+			return `EAS session ${sessionId} is stopped, but its ownership claim could not be removed: ${describe(error)}. The claim and workspace record were kept for reconciliation. Re-run stop.`;
+		}
+	};
+	let sessionOutput;
+	try {
+		sessionOutput = getExecutor().runFile(ctx.easBin, getSessionArgs(sessionId), easBoundedExecOptions(ctx.root));
+	} catch (err) {
+		if (isDefinitiveMissingSessionError(err, sessionId)) return {
+			status: "torn-down",
+			reason: removeClaim()
+		};
+		return {
+			status: "failed",
+			reason: `Could not verify EAS session ${sessionId}: ${describe(err)}. The session record was kept for retry.`
+		};
+	}
+	const inspection = inspectSessionForTeardown(sessionOutput, sessionId);
+	if (inspection.action === "refused") return {
+		status: "failed",
+		reason: `${inspection.reason} The session record was kept for retry.`
+	};
+	if (inspection.action === "already-stopped") return {
+		status: "torn-down",
+		reason: removeClaim()
+	};
+	let stopOutput;
+	try {
+		stopOutput = getExecutor().runFile(ctx.easBin, stopSessionArgs(sessionId), easBoundedExecOptions(ctx.root));
+	} catch (err) {
+		return {
+			status: "failed",
+			reason: `eas simulator:stop ${sessionId} failed: ${describe(err)}. The session record was kept for retry.`
+		};
+	}
+	const verified = verifyStoppedSession(stopOutput, sessionId);
+	if (!verified.ok) return {
+		status: "failed",
+		reason: `${verified.reason} The session record was kept for retry.`
+	};
+	return {
+		status: "torn-down",
+		reason: removeClaim()
+	};
+}
+async function ensureMetroReachable({ ctx, metroPort, isExpo, tunnelMode = "auto", publicUrl = null, available = [], env = process.env, readTunnelRecord = readMetroTunnel, isTunnelAlive = pidExists, gateOrigin = gateMetroOrigin }) {
+	const { root } = ctx;
+	const platform = ctx.platform ?? "ios";
+	const publicMetroUrl = env["STIM_METRO_PUBLIC_URL"]?.trim() || publicUrl || null;
+	const recorded = readTunnelRecord(root);
+	const effectiveAvailable = recorded?.kind === "managed" && isTunnelAlive(recorded.pid) ? [recorded.provider, ...available.filter((provider) => provider !== recorded.provider)] : available;
+	const plan = planMetroReach({
+		mode: tunnelMode,
+		metroPort,
+		publicUrl: publicMetroUrl,
+		isExpo,
+		available: effectiveAvailable
+	});
+	if ("failed" in plan) return plan;
+	let resolvedUrl = null;
+	let gate = false;
+	if ("origin" in plan) {
+		resolvedUrl = plan.origin;
+		gate = plan.gate;
+	} else if ("expoTunnel" in plan) {
+		if (!recorded || recorded.kind !== "expo") return {
+			failed: "This workspace's Metro tunnels itself (metro.tunnel is expo, or auto on an Expo project), but no Expo tunnel URL is recorded.",
+			remedy: "Run `stim start --remote` so Expo can establish its own tunnel before a remote device connects."
+		};
+		resolvedUrl = recorded.url;
+		gate = true;
+	} else {
+		const port = Number(metroPort);
+		const providerMatches = tunnelMode === "auto" || recorded?.kind === "managed" && recorded.provider === plan.start;
+		if (recorded && recorded.kind === "managed" && recorded.port === port && providerMatches && isTunnelAlive(recorded.pid)) resolvedUrl = recorded.url;
+		else return {
+			failed: `No live managed Metro tunnel is recorded for port ${port}.`,
+			remedy: "Run `stim start --remote`, then retry the device command."
+		};
+		gate = true;
+	}
+	if (gate && resolvedUrl) {
+		const logsDir = workspaceLogsDir(root);
+		const result = await gateOrigin({
+			origin: resolvedUrl,
+			metroPort,
+			platform,
+			entryPoint: bundleEntryPoint(root, isExpo),
+			readRecords: () => readMetroRecords(logsDir),
+			isProof: isBundleProof
+		});
+		if (result.failed) return {
+			failed: result.reason ?? "Metro gate failed.",
+			remedy: result.remedy ?? "",
+			code: REMOTE_METRO_WRONG
+		};
+	}
+	ctx.publicMetroUrl = resolvedUrl;
+	return { ok: true };
+}
+function bundleEntryPoint(root, isExpo) {
+	if (!isExpo) return "index";
+	try {
+		const pkg = JSON.parse(readFileSync(resolve(root, "package.json"), "utf-8"));
+		if (typeof pkg.main !== "string" || !pkg.main.trim()) return "index";
+		const main = pkg.main.trim();
+		const local = main.startsWith(".") || /\.[cm]?[jt]sx?$/.test(main) || existsSync(resolve(root, main));
+		const normalized = main.replace(/^\.\//, "").replace(/\.(?:[cm]?[jt]sx?)$/, "");
+		return local ? normalized : `node_modules/${normalized}`;
+	} catch {
+		return "index";
+	}
+}
+//#endregion
+export { verifyStoppedSession as C, stopSessionArgs as S, inspectSessionForTeardown as _, ensureMetroReachable as a, ownedSessionName as b, remoteIosDeps as c, withEasProjectLock as d, easMachineStateRoot as f, getSessionArgs as g, findOrphanedOwnedSessions as h, endRecordedSession as i, resolveRemoteContext as l, removeEasSessionClaim as m, binOnPath as n, ensureRemoteBootOwned as o, readEasSessionLedger as p, bundleEntryPoint as r, remoteAndroidDeps as s, REMOTE_SESSION_ERROR as t, withRemoteSessionLock as u, isDefinitiveMissingSessionError as v, gateMetroOrigin as w, parseSessionListPage as x, listOwnedSessionsArgs as y };