stim 1.20.2 → 1.22.0

package/dist/start-EojN4WFz.mjs

@@ -0,0 +1,1364 @@
+import { a as workspaceProcessLockError, g as process_identity_exports, h as withDrainingCancellation, i as withWorkspaceProcessLock, r as WorkspaceProcessCleanupError, t as getExecutor, x as ownership_claim_exports } from "./exec-DEoAhcze.mjs";
+import { l as workspaceAgentDeviceDir, m as workspaceLogsDir$1, n as ensureWorkspaceStorage, s as supervisorLogFile } from "./paths-DQtTgsBf.mjs";
+import { E as upsertProject, O as withConfigLockAsync$1, p as getProject } from "./config-DlrsduwG.mjs";
+import { _ as stepTimer, l as phaseLine } from "./command-output-gwpm28fu.mjs";
+import { f as throwIfCancelled, u as cancellableSleep } from "./operation-exec-BW0em61G.mjs";
+import { i as recordWorkspaceUse, l as withWorkspaceStateLockAsync, n as clearWorkspaceStateKeys, r as readWorkspaceState$1, s as updateWorkspaceStateAsync } from "./workspace-state-U08dEzhG.mjs";
+import { A as metroIdleStopMinutesSetting, G as resolveCacheProviderConfig, J as resolveProjectSettingsAsync, K as resolveIosProjectDir, M as metroTunnelSettingError, O as metroCommandSetting, P as ngrokUrlSetting, R as publicUrlSetting, U as remoteIosSetting, V as remoteAndroidSetting, W as resolveAndroidLayout, a as SETTING_SHAPE_REMEDY, ct as detectProviders, et as settingShapeErrors, h as deviceIdleShutdownMinutesSetting, it as unknownSettingKeys, j as metroPortSetting, k as metroCommandSettingError, lt as planMetroReach, m as defaultAndroidLayout, p as cacheProviderSettingError, rt as tunnelModeSetting, st as PUBLIC_METRO_ENV } from "./settings-C7O8A6ZI.mjs";
+import { E as MODE_EXPO, M as readMetroTunnel, O as clearManagedMetroTunnel, S as readAppJson, T as MODE_COMMAND, c as projectProblem, i as findProjectRoot$1, t as NO_PROJECT_REFUSAL, v as detectIsExpo, w as MODE_BARE, x as readAppConfigText } from "./project-wM_XFTvE.mjs";
+import { i as levelRank } from "./ndjson-CgE_o3Dl.mjs";
+import { _ as PORT_INSPECTION_REMEDY, a as listeningPidsAsync, c as pidExists, d as resolveProjectMetro, f as signalProcessTree, g as reserveMetroPort, h as isMetroRunning, u as processCwds, v as PortInspectionError } from "./metro-DiXtA3Ty.mjs";
+import { In as runProcessOperation, Kn as readProjectConfig, Pn as exitAfterFlush, Zn as remoteCliInvocation, p as stopOwnedMetroForReset, t as budgetGate } from "./budget-Cvwn54qV.mjs";
+import { _ as stopTunnel, g as startTunnelSequence, h as resolveSupervisorTarget, v as terminateChild, x as withManagedTunnelLock, y as withManagedRemoteWorktreeLock } from "./workspaces-CpANmBlq.mjs";
+import { a as workspaceLinkLine, o as workspaceLinks } from "./stim-desktop-D5OGpYZM.mjs";
+import { t as spawnEntry } from "./spawn-entry-jw19m8Nl.mjs";
+import { n as windowsLauncherArgs } from "./detached-entry-BwNEtIrP.mjs";
+import { appendFileSync, closeSync, mkdirSync, openSync, readFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { ambientContext, ambientEnv } from "@stim-cli/core";
+import { IDLE_STOP_KEY, queryLogs } from "@stim-cli/core/state";
+import { join as join$1 } from "path";
+import chalk from "chalk";
+import { existsSync as existsSync$1, readFileSync as readFileSync$1, readdirSync as readdirSync$1 } from "fs";
+import { CACHE_PROVIDER_ENV, cacheProviderEnv } from "@stim-cli/cache";
+import { EventEmitter } from "node:events";
+//#region src/workspace/app-id.ts
+const ANDROID_PACKAGE_NAME = /^[A-Za-z0-9_]+(?:\.[A-Za-z0-9_]+)+$/;
+function androidPackageFilter(problems) {
+	return (id, source) => {
+		if (id === null || ANDROID_PACKAGE_NAME.test(id)) return id;
+		problems.push(`Invalid Android package ${JSON.stringify(id)} in ${source}. Expected dot-separated letters, digits and underscores, such as com.example.app.`);
+		return null;
+	};
+}
+function configString(config, platform, key) {
+	if (!config || typeof config !== "object") return null;
+	const expoField = config.expo;
+	const section = (expoField && typeof expoField === "object" ? expoField : config)[platform];
+	if (!section || typeof section !== "object") return null;
+	const value = section[key];
+	return typeof value === "string" && value ? value : null;
+}
+function literalString(text, key) {
+	return text?.match(new RegExp(`${key}\\s*:\\s*["']([^"']+)["']`))?.[1] ?? null;
+}
+async function idsFromConfig(projectRoot, options) {
+	const read = await readProjectConfig(projectRoot, options);
+	if (!read.unavailable) return {
+		bundleId: configString(read.config, "ios", "bundleIdentifier"),
+		androidPackage: configString(read.config, "android", "package")
+	};
+	const appJson = readAppJson(projectRoot);
+	const text = readAppConfigText(projectRoot);
+	return {
+		bundleId: configString(appJson, "ios", "bundleIdentifier") ?? literalString(text, "bundleIdentifier"),
+		androidPackage: configString(appJson, "android", "package") ?? literalString(text, "package")
+	};
+}
+async function detectAppIds(projectRoot, iosDir = join$1(projectRoot, "ios"), androidModuleDir = defaultAndroidLayout(projectRoot).moduleDir, config = {}) {
+	const ids = await idsFromConfig(projectRoot, config);
+	const problems = [];
+	const accept = androidPackageFilter(problems);
+	return {
+		bundleId: ids.bundleId ?? detectBundleIdFromPbxproj(iosDir),
+		androidPackage: accept(ids.androidPackage, "the Expo config android.package") ?? detectAndroidPackageFromGradle(androidModuleDir, accept),
+		androidPackageProblem: problems.length > 0 ? problems.join(" ") : null
+	};
+}
+async function detectBundleId(projectRoot, iosDir = join$1(projectRoot, "ios")) {
+	return (await detectAppIds(projectRoot, iosDir)).bundleId;
+}
+async function detectAndroidPackage(projectRoot, androidModuleDir = defaultAndroidLayout(projectRoot).moduleDir) {
+	return (await detectAppIds(projectRoot, void 0, androidModuleDir)).androidPackage;
+}
+function detectBundleIdFromPbxproj(iosDir) {
+	if (!existsSync$1(iosDir)) return null;
+	let entries;
+	try {
+		entries = readdirSync$1(iosDir, { withFileTypes: true });
+	} catch {
+		return null;
+	}
+	for (const entry of entries) {
+		if (!entry.isDirectory() || !entry.name.endsWith(".xcodeproj")) continue;
+		const pbx = join$1(iosDir, entry.name, "project.pbxproj");
+		if (!existsSync$1(pbx)) continue;
+		let text;
+		try {
+			text = readFileSync$1(pbx, "utf-8");
+		} catch {
+			continue;
+		}
+		const concrete = [...text.matchAll(/PRODUCT_BUNDLE_IDENTIFIER\s*=\s*([^;\s"]+)\s*;/g)].map((m) => m[1]).filter((id) => !!id && !id.startsWith("$") && !id.includes("("));
+		if (concrete.length === 0) continue;
+		const counts = {};
+		for (const id of concrete) counts[id] = (counts[id] || 0) + 1;
+		let best = null, bestCount = 0, bestLen = Infinity;
+		for (const [id, count] of Object.entries(counts)) if (count > bestCount || count === bestCount && id.length < bestLen) {
+			best = id;
+			bestCount = count;
+			bestLen = id.length;
+		}
+		return best;
+	}
+	return null;
+}
+function detectAndroidPackageFromGradle(moduleDir, accept) {
+	const gradle = [join$1(moduleDir, "build.gradle"), join$1(moduleDir, "build.gradle.kts")].find((file) => existsSync$1(file));
+	if (!gradle) return null;
+	let text;
+	try {
+		text = readFileSync$1(gradle, "utf-8");
+	} catch {
+		return null;
+	}
+	const nsId = text.match(/namespace\s*=?\s*["']([^"']+)["']/)?.[1];
+	const namespace = nsId ? accept(nsId, gradle) : null;
+	if (namespace) return namespace;
+	const appId = text.match(/applicationId\s*=?\s*["']([^"']+)["']/)?.[1];
+	return appId ? accept(appId, gradle) : null;
+}
+//#endregion
+//#region src/commands/start.ts
+const DEFAULT_WAIT_SECONDS = 60;
+const POLL_MS = 500;
+const LOG_TAIL_LINES = 5;
+async function resolveStartupMetro(port, root) {
+	const signal = ambientContext()?.signal;
+	throwIfCancelled(signal, "Metro startup");
+	const result = await resolveProjectMetro(port, root, {
+		pidsOf: (candidate) => listeningPidsAsync(candidate, process.platform, signal),
+		cwdOf: async (pid) => (await processCwds([pid], signal)).get(pid) ?? null,
+		probe: (candidate) => isMetroRunning(candidate, signal)
+	});
+	throwIfCancelled(signal, "Metro startup");
+	return result;
+}
+function waitForStartup(ms) {
+	return cancellableSleep(ms, {
+		signal: ambientContext()?.signal,
+		what: "Metro startup"
+	});
+}
+function writeNote(line) {
+	console.error(line);
+}
+function supervisorEntry() {
+	return spawnEntry("supervisor-run");
+}
+function wantsExpoOwnTunnel({ isExpo, remote, mode, publicUrl }) {
+	return remote && isExpo && !publicUrl && mode === "expo";
+}
+function parseWait(value) {
+	if (value === void 0 || value === null) return { seconds: DEFAULT_WAIT_SECONDS };
+	const seconds = Number(value);
+	if (!Number.isFinite(seconds) || seconds <= 0) return { error: `Invalid --wait value ${JSON.stringify(value)}. Pass a number of seconds, e.g. --wait 90.` };
+	return { seconds };
+}
+function liveSupervisor({ state, project, port, isAlive = pidExists, inspectIdentity = process_identity_exports.inspectProcessIdentity } = {}) {
+	const target = resolveSupervisorTarget({
+		state: state?.supervisor,
+		record: project?.supervisor,
+		reservedPort: port,
+		isAlive,
+		inspectIdentity
+	});
+	return target.status === "ours" && target.port === port ? {
+		pid: target.pid,
+		port: target.port,
+		mode: target.mode ?? null,
+		startedAt: target.startedAt ?? null
+	} : null;
+}
+function startFacts({ root, port, supervisor, logsDir, alreadyRunning }) {
+	return {
+		port,
+		supervisorPid: supervisor?.pid ?? null,
+		mode: supervisor?.mode ?? null,
+		logsDir,
+		...root ? { agentDevice: { stateDir: workspaceAgentDeviceDir(root) } } : {},
+		alreadyRunning: Boolean(alreadyRunning)
+	};
+}
+function startError({ code, message, remedy = null }) {
+	return {
+		code,
+		message,
+		remedy: remedy ?? null
+	};
+}
+function tailLines(text, n = LOG_TAIL_LINES) {
+	return String(text || "").split("\n").filter((l) => l.trim() !== "").slice(-n);
+}
+function readLogTail(file, n = LOG_TAIL_LINES) {
+	try {
+		return tailLines(readFileSync(file, "utf-8"), n);
+	} catch {
+		return [];
+	}
+}
+function startCommand(program) {
+	registerStart(program);
+}
+function supervisorSignalable(child, inspectIdentity = process_identity_exports.inspectProcessIdentity) {
+	return !child.recordedIdentity || inspectIdentity(child.recordedIdentity) === "same";
+}
+function recordedSupervisorProcess(recorded) {
+	const pid = typeof recorded?.pid === "number" ? recorded.pid : void 0;
+	return Object.assign(new EventEmitter(), {
+		pid,
+		...recorded ? { recordedIdentity: recorded } : {},
+		stdout: null,
+		stderr: null,
+		kill: (signal = "SIGTERM") => pid !== void 0 && signalProcessTree(pid, typeof signal === "number" ? "SIGTERM" : signal),
+		unref() {}
+	});
+}
+const RECORDED_SUPERVISOR_WAIT_MS = 15e3;
+function providersOnPath(mode) {
+	return detectProviders((bin) => {
+		try {
+			return Boolean(getExecutor().findExecutable(bin));
+		} catch {
+			return false;
+		}
+	}, mode);
+}
+const DEFAULT_START_DEPS = {
+	providers: providersOnPath,
+	startTunnelSequence,
+	isTunnelAlive: (pid, processToken) => processToken === void 0 ? pidExists(pid) : (0, process_identity_exports.inspectProcessIdentity)({
+		pid,
+		processToken
+	}) === "same",
+	writeTunnelRecord: (root, patch) => updateWorkspaceStateAsync(root, (state) => ({
+		...state,
+		...patch
+	})),
+	stopTunnel,
+	writeSupervisorRecord: (root, patch) => updateWorkspaceStateAsync(root, (state) => ({
+		...state,
+		...patch
+	})),
+	terminateSupervisorChild: async (child) => {
+		if (child.pid && process.platform !== "win32") try {
+			signalProcessTree(child.pid, "SIGTERM", { group: true });
+		} catch {}
+		return terminateChild(child, {
+			alreadyExited: false,
+			timeoutMs: 1e3,
+			isAlive: pidExists,
+			waitForGroup: process.platform !== "win32"
+		});
+	},
+	withWorktreeLock: withManagedRemoteWorktreeLock,
+	withTunnelLock: withManagedTunnelLock,
+	clearTunnelRecord: (root, record) => withWorkspaceStateLockAsync(root, () => clearManagedMetroTunnel(root, record)),
+	budgetGate,
+	platform: process.platform
+};
+function normalizeManagedTunnelUrl(url) {
+	return url.trim().replace(/\/+$/, "");
+}
+function registerStart(program, overrides = {}) {
+	const d = {
+		...DEFAULT_START_DEPS,
+		...overrides
+	};
+	program.command("start").description("Start this workspace's dev server under a detached supervisor and wait until it verifies as this project's. Idempotent: a healthy dev server on the reserved port is a no-op. Structured logs land in the global workspace logs directory.").option("--json", "Emit the facts as a single JSON line on stdout; every other line goes to stderr").option("--wait <seconds>", `How long to wait for the dev server to answer (default ${DEFAULT_WAIT_SECONDS})`).option("--remote", "Prepare the dev server for a remote device").option("--reset-cache", "Restart owned Metro and clear this app's Metro caches").action(async (opts) => {
+		const json = Boolean(opts.json);
+		const out = (line) => {
+			if (json) console.error(line);
+			else console.log(line);
+		};
+		const note = writeNote;
+		const fail = ({ code, message, remedy = null, lines = [], reclaimed = [], exitCode = 1 }) => {
+			note(chalk.red(message));
+			for (const line of lines) note(chalk.dim(`  ${line}`));
+			if (remedy) note(chalk.dim(remedy));
+			note(chalk.red(`failed: ${code}`));
+			if (json) console.log(JSON.stringify({
+				...startError({
+					code,
+					message,
+					remedy
+				}),
+				...reclaimed.length ? { reclaimed } : {}
+			}));
+			process.exit(exitCode);
+		};
+		const wait = parseWait(opts.wait);
+		if (wait.error) return fail({
+			code: "STIM_BAD_ARG",
+			message: wait.error,
+			remedy: "Pass a whole number of seconds, e.g. --wait 90."
+		});
+		const waitSeconds = wait.seconds;
+		const root = findProjectRoot$1(process.cwd());
+		if (!root) return fail(NO_PROJECT_REFUSAL);
+		const problem = projectProblem(root, "dev-server");
+		if (problem) return fail({
+			code: "STIM_NO_PROJECT",
+			message: problem.message,
+			remedy: problem.remedy
+		});
+		try {
+			ensureWorkspaceStorage(root);
+		} catch (error) {
+			return fail({
+				code: error?.code || "STIM_WORKSPACE_STATE",
+				message: `Could not prepare this workspace's Stim state: ${error?.message || error}`,
+				remedy: "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`)."
+			});
+		}
+		recordWorkspaceUse(root);
+		const { context: settingsContext, settings } = await resolveProjectSettingsAsync(root);
+		const [shapeError, ...moreShapeErrors] = settingShapeErrors(settings);
+		if (shapeError) return fail({
+			code: "STIM_BAD_ARG",
+			message: shapeError,
+			lines: moreShapeErrors,
+			remedy: SETTING_SHAPE_REMEDY
+		});
+		for (const key of unknownSettingKeys(settings)) note(chalk.yellow(`Warning: setting "${key}" is not read by Stim and will be ignored.`));
+		const cacheProviderError = cacheProviderSettingError(settings);
+		if (cacheProviderError) note(chalk.yellow(`Warning: ${cacheProviderError} No cache provider is used.`));
+		const { value: result, interrupted } = await runProcessOperation(root, (context) => withDrainingCancellation(context, context.signal, async () => {
+			try {
+				return await startDevServer({
+					root,
+					settings,
+					settingsContext,
+					waitSeconds,
+					remote: Boolean(opts.remote),
+					resetCache: Boolean(opts.resetCache),
+					out,
+					note
+				}, d);
+			} catch (error) {
+				if (!(error instanceof Error) || !("code" in error) || error.code !== "STIM_CANCELLED") throw error;
+				return {
+					ok: false,
+					error: startError({
+						code: "STIM_CANCELLED",
+						message: error.message
+					}),
+					lines: [],
+					reclaimed: []
+				};
+			}
+		}));
+		if (!result.ok) return fail({
+			...result.error,
+			lines: result.lines,
+			reclaimed: result.reclaimed,
+			exitCode: interrupted ?? 1
+		});
+		report({
+			json,
+			out,
+			facts: result.facts,
+			waited: result.waited,
+			reclaimed: result.reclaimed,
+			links: await workspaceLinks(root)
+		});
+		if (interrupted !== null) exitAfterFlush(interrupted);
+	});
+}
+var StartRefusal = class extends Error {
+	refusal;
+	constructor(refusal) {
+		super(refusal.message);
+		this.refusal = refusal;
+	}
+};
+async function startDevServer({ root, settings, settingsContext, waitSeconds = DEFAULT_WAIT_SECONDS, remote: remoteFlag = false, resetCache = false, out, note }, overrides = {}) {
+	const d = {
+		...DEFAULT_START_DEPS,
+		...overrides
+	};
+	const operationSignal = ambientContext()?.signal;
+	throwIfCancelled(operationSignal, "Metro startup");
+	const waitTimer = stepTimer();
+	let reclaimed = [];
+	const fail = (refusal) => {
+		throw new StartRefusal(refusal);
+	};
+	const isExpo = detectIsExpo(root);
+	const metroCommand = metroCommandSetting(settings);
+	const serverMode = metroCommand ? MODE_COMMAND : isExpo ? MODE_EXPO : MODE_BARE;
+	const expoServer = serverMode === MODE_EXPO;
+	const worktreeRoot = settingsContext.repoRoot ?? root;
+	const cacheProvider = resolveCacheProviderConfig(settingsContext);
+	const run = async () => {
+		const settingError = metroTunnelSettingError(settings);
+		if (settingError) return fail({
+			code: "STIM_BAD_ARG",
+			message: settingError,
+			remedy: "Set metro.tunnel to \"ngrok\" and metro.ngrokUrl to an HTTPS URL, or remove metro.ngrokUrl."
+		});
+		if (metroCommand && d.platform === "win32") return fail({
+			code: "STIM_BAD_ARG",
+			message: "metro.command is not supported on Windows: Stim cannot read a process working directory there, so it cannot prove the Metro a wrapper starts belongs to this app.",
+			remedy: "Remove metro.command on Windows, or run this app from macOS or Linux."
+		});
+		if (metroCommand && resetCache) return fail({
+			code: "STIM_BAD_ARG",
+			message: "--reset-cache cannot reach a dev server started by metro.command; Stim does not know its reset flag.",
+			remedy: "Add the command's own cache-reset flag to metro.command (for React Native, --reset-cache), then run stim stop and stim start."
+		});
+		const commandError = metroCommandSettingError(settings);
+		if (commandError) return fail({
+			code: "STIM_BAD_ARG",
+			message: commandError,
+			remedy: "Set metro.command to the argv that starts the dev server, e.g. [\"npx\", \"react-native\", \"start\", \"--port\", \"{port}\"], or remove it."
+		});
+		const remote = remoteFlag || remoteIosSetting(settings)?.kind === "backend" || remoteAndroidSetting(settings)?.kind === "backend";
+		const tunnelMode = tunnelModeSetting(settings) ?? "auto";
+		const publicUrl = publicUrlSetting(settings);
+		const tunnel = wantsExpoOwnTunnel({
+			isExpo: expoServer,
+			remote,
+			mode: tunnelMode,
+			publicUrl
+		});
+		if (tunnel) note(chalk.dim("note   requesting an Expo tunnel for this workspace's dev server"));
+		const managedRemote = remote && !tunnel && !publicUrl && tunnelMode !== "off";
+		const runStart = async (claim, tunnelClaim) => {
+			const claims = [claim, tunnelClaim];
+			const appIds = await detectAppIds(root, resolveIosProjectDir(settings, root).dir, resolveAndroidLayout(settings, root, settingsContext.repoRoot ?? root).moduleDir, {
+				context: ambientContext(),
+				run: async (file, args, options) => {
+					for (const held of claims) (0, ownership_claim_exports.markClaimChildPending)(held);
+					let child;
+					let identity;
+					let output = "";
+					let failure;
+					try {
+						const invocation = remoteCliInvocation(file, args, "expo");
+						output = await getExecutor().runFileAsync(invocation.file, invocation.args, {
+							...options,
+							cwd: root,
+							containProcessTree: true,
+							signal: operationSignal ?? new AbortController().signal,
+							onSpawn: (spawned) => {
+								child = spawned;
+								if (!spawned.pid) return;
+								const processToken = (0, process_identity_exports.captureProcessToken)(spawned.pid);
+								if (!processToken) throw new Error("Cannot record the Expo config process identity.");
+								identity = {
+									pid: spawned.pid,
+									processToken
+								};
+								for (const held of claims) (0, ownership_claim_exports.setClaimChild)(held, identity);
+							}
+						});
+					} catch (error) {
+						failure = { error };
+					}
+					const pid = child?.pid;
+					if (pid) {
+						const alive = () => d.platform === "win32" ? !identity || (0, process_identity_exports.inspectProcessIdentity)(identity) !== "gone" : (0, ownership_claim_exports.processGroupAlive)(pid);
+						const deadline = Date.now() + 1e3;
+						while (alive() && Date.now() < deadline) await cancellableSleep(25);
+						if (alive()) throw new WorkspaceProcessCleanupError(claims, `Could not confirm cleanup of Expo config process ${pid}.`, "Inspect and stop the Expo config process and its helpers before retrying.");
+					}
+					for (const held of claims) (0, ownership_claim_exports.clearClaimChild)(held);
+					if (failure) throw failure.error;
+					return output;
+				}
+			});
+			await withConfigLockAsync$1(() => {
+				upsertProject(root, {
+					bundleId: appIds.bundleId ?? void 0,
+					androidPackage: appIds.androidPackage ?? void 0,
+					isExpo
+				});
+			}, operationSignal);
+			const gateBudget = async () => {
+				const budget = await d.budgetGate({
+					root,
+					note,
+					env: ambientEnv(),
+					signal: operationSignal
+				});
+				reclaimed = budget.reclaimed;
+				if (budget.refusal) return fail(budget.refusal);
+			};
+			if (resetCache) {
+				await gateBudget();
+				const pin = metroPortSetting(settings, ambientEnv());
+				if (pin.port !== null || pin.error) {
+					const pinCheck = await resolveWorkspaceMetroPort(root, settings, note, "start", false);
+					if (typeof pinCheck !== "number") return fail(pinCheck);
+				}
+				try {
+					await stopOwnedMetroForReset(root, operationSignal);
+				} catch (error) {
+					const failure = error;
+					return fail({
+						code: failure.code ?? "STIM_WORKSPACE_STATE",
+						message: failure.message,
+						remedy: failure.remedy
+					});
+				}
+				note(phaseLine("cache", "clearing this app's Metro transform and file-map caches; devices preserved"));
+			}
+			const logsDir = workspaceLogsDir$1(root);
+			const logFile = supervisorLogFile(root);
+			const port = await resolvePort(root, settings, note, fail);
+			let publicOrigin = remote ? publicUrl : null;
+			let resolution = await resolveStartupMetro(port, root);
+			let supervisor = liveSupervisor({
+				state: readWorkspaceState$1(root),
+				project: getProject(root),
+				port
+			});
+			const recordedTarget = resolveSupervisorTarget({
+				state: readWorkspaceState$1(root)?.supervisor,
+				record: getProject(root)?.supervisor,
+				reservedPort: port
+			});
+			if (recordedTarget.status === "unverified") return fail({
+				code: "STIM_SUPERVISOR_EXITED",
+				message: `Cannot reuse or replace the recorded supervisor: ${recordedTarget.reason}.`,
+				remedy: "Stop it with the tool that started it, then retry `stim start`. Stim leaves unverified processes alone."
+			});
+			if (!resetCache && !resolution.metro && !supervisor) await gateBudget();
+			let managedTunnel = null;
+			const spawned = { child: null };
+			let spawnedTs = null;
+			let childExit = null;
+			let spawnedIdentity = null;
+			let unknownWindowsSpawn = false;
+			let windowsLauncher = null;
+			let tunnelPending = null;
+			const handedOffSupervisor = () => {
+				if (!spawnedIdentity) return null;
+				const target = resolveSupervisorTarget({
+					state: readWorkspaceState$1(root)?.supervisor,
+					record: getProject(root)?.supervisor,
+					reservedPort: port
+				});
+				return target.status === "ours" && typeof target.pid === "number" && target.pid === spawnedIdentity.pid && target.processToken === spawnedIdentity.processToken && target.port === port ? {
+					pid: target.pid,
+					port,
+					mode: target.mode ?? null,
+					startedAt: target.startedAt ?? null
+				} : null;
+			};
+			const spawnDirect = (supervisorArgs, childEnv) => {
+				const fd = openSync(logFile, "a");
+				let child;
+				try {
+					child = getExecutor().spawn(process.execPath, supervisorArgs, {
+						cwd: root,
+						detached: true,
+						stdio: [
+							"ignore",
+							fd,
+							fd
+						],
+						env: childEnv
+					});
+				} finally {
+					closeSync(fd);
+				}
+				child.unref?.();
+				child.on?.("exit", (code, signal) => {
+					childExit = {
+						code,
+						signal
+					};
+				});
+				child.on?.("error", (err) => {
+					childExit = {
+						code: null,
+						signal: null,
+						error: err
+					};
+				});
+				return child;
+			};
+			const recordedSupervisor = async (since, waitMs = RECORDED_SUPERVISOR_WAIT_MS) => {
+				const deadline = Date.now() + waitMs;
+				while (Date.now() < deadline) {
+					const record = readWorkspaceState$1(root)?.supervisor;
+					if (record?.pid && record.port === port && Date.parse(String(record.startedAt)) >= since && pidExists(record.pid)) return {
+						pid: record.pid,
+						processToken: record.processToken
+					};
+					await cancellableSleep(25);
+				}
+				return null;
+			};
+			const spawnThroughWindowsShell = async (supervisorArgs, childEnv) => {
+				const [entry, ...args] = supervisorArgs;
+				const launcher = windowsLauncherArgs({
+					entry,
+					args,
+					cwd: root,
+					logFile
+				});
+				const since = Date.now();
+				const shell = getExecutor().spawn(launcher.file, launcher.args, {
+					cwd: root,
+					stdio: [
+						"ignore",
+						"ignore",
+						"pipe"
+					],
+					env: {
+						...childEnv,
+						...launcher.env
+					},
+					windowsHide: true
+				});
+				const launch = {
+					child: shell,
+					since,
+					closed: false
+				};
+				windowsLauncher = launch;
+				unknownWindowsSpawn = shell.pid !== void 0;
+				const stderr = [];
+				shell.stderr?.on("data", (chunk) => stderr.push(String(chunk)));
+				const closed = new Promise((resolve) => {
+					shell.once("close", (code, signal) => {
+						launch.closed = true;
+						resolve({
+							code,
+							signal
+						});
+					});
+					shell.once("error", (error) => resolve({
+						code: null,
+						signal: null,
+						error
+					}));
+				});
+				const waiting = new AbortController();
+				const signal = operationSignal ? AbortSignal.any([operationSignal, waiting.signal]) : waiting.signal;
+				let exit;
+				try {
+					exit = await Promise.race([closed, cancellableSleep(Math.min(RECORDED_SUPERVISOR_WAIT_MS, waitSeconds * 1e3), {
+						signal,
+						what: "Windows supervisor launcher"
+					}).then(() => fail({
+						code: "STIM_METRO_TIMEOUT",
+						message: "The Windows supervisor launcher did not finish before the startup deadline.",
+						remedy: "Inspect the launcher and supervisor before retrying."
+					}))]);
+				} finally {
+					waiting.abort();
+				}
+				const launcherFailed = exit.code !== 0 || exit.error;
+				unknownWindowsSpawn = !launcherFailed;
+				const recorded = launcherFailed ? null : await recordedSupervisor(since);
+				if (recorded) unknownWindowsSpawn = false;
+				if (recorded === null) {
+					const reason = launcherFailed ? `the supervisor launcher exited (${exit.error ? exit.error.message : `code ${exit.code}`})` : `the supervisor did not record itself within ${RECORDED_SUPERVISOR_WAIT_MS / 1e3}s`;
+					appendFileSync(logFile, `Stim start: ${reason}.\n${stderr.join("")}`);
+					childExit = {
+						code: exit.code,
+						signal: exit.signal,
+						...exit.error ? { error: exit.error } : {}
+					};
+				}
+				windowsLauncher = null;
+				return recordedSupervisorProcess(recorded);
+			};
+			const spawnSupervisor = async (origin) => {
+				mkdirSync(logsDir, { recursive: true });
+				spawnedTs = Date.now();
+				const supervisorArgs = [
+					supervisorEntry(),
+					"--root",
+					root,
+					"--port",
+					String(port),
+					...tunnel ? ["--tunnel"] : [],
+					...resetCache ? ["--reset-cache"] : [],
+					"--idle-stop-minutes",
+					String(metroIdleStopMinutesSetting(settings)),
+					"--device-idle-minutes",
+					String(deviceIdleShutdownMinutesSetting(settings))
+				];
+				const childEnv = {
+					...ambientEnv(),
+					...origin ? {
+						[PUBLIC_METRO_ENV]: origin,
+						EXPO_PACKAGER_PROXY_URL: origin
+					} : {}
+				};
+				childEnv[CACHE_PROVIDER_ENV] = cacheProviderEnv(cacheProvider);
+				for (const held of claims) (0, ownership_claim_exports.markClaimChildPending)(held);
+				const child = d.platform === "win32" ? await spawnThroughWindowsShell(supervisorArgs, childEnv) : spawnDirect(supervisorArgs, childEnv);
+				spawned.child = child;
+				if (child.pid) {
+					const processToken = child.recordedIdentity?.processToken ?? (0, process_identity_exports.captureProcessToken)(child.pid);
+					if (processToken) {
+						spawnedIdentity = {
+							pid: child.pid,
+							processToken
+						};
+						for (const held of claims) (0, ownership_claim_exports.setClaimChild)(held, spawnedIdentity);
+					}
+				}
+				out(chalk.dim(phaseLine("metro", `starting on port ${port} (${serverMode}, supervisor pid ${child.pid})`)));
+				return child;
+			};
+			const waitForSupervisorHandoff = async (child) => {
+				const deadline = Date.now() + 5e3;
+				while (Date.now() < deadline) {
+					const found = handedOffSupervisor();
+					if (found) return found;
+					if (childExit !== null || (child.pid ? !pidExists(child.pid) : true)) return null;
+					await cancellableSleep(25);
+				}
+				return null;
+			};
+			const reconcileSpawnedSupervisor = async () => {
+				try {
+					const launch = windowsLauncher;
+					if (launch) {
+						if (!await terminateChild(launch.child, {
+							alreadyExited: launch.closed || launch.child.exitCode !== null || launch.child.signalCode !== null,
+							timeoutMs: 1e3,
+							isAlive: pidExists
+						})) throw new WorkspaceProcessCleanupError(claims, `Could not confirm cleanup of Windows supervisor launcher pid ${launch.child.pid}.`, "Inspect and stop the launcher and its supervisor with their original tooling before retrying.");
+						if (unknownWindowsSpawn) {
+							const recorded = await recordedSupervisor(launch.since, 1e3);
+							if (recorded) {
+								spawned.child = recordedSupervisorProcess(recorded);
+								spawnedIdentity = recorded;
+								for (const held of claims) (0, ownership_claim_exports.setClaimChild)(held, recorded);
+								unknownWindowsSpawn = false;
+							}
+						}
+						windowsLauncher = null;
+					}
+					const child = spawned.child;
+					if (tunnelPending) throw tunnelPending;
+					if (child?.pid && !handedOffSupervisor()) {
+						const hasPublishedSupervisor = () => {
+							const identity = spawnedIdentity;
+							return identity !== null && [readWorkspaceState$1(root)?.supervisor, getProject(root)?.supervisor].some((record) => record?.pid === identity.pid && record?.processToken === identity.processToken);
+						};
+						if (hasPublishedSupervisor()) {
+							for (const held of claims) (0, ownership_claim_exports.markClaimChildPending)(held);
+							throw new WorkspaceProcessCleanupError(claims, `Supervisor pid ${child.pid} published ownership that cannot be reconciled with the workspace registry.`, "Inspect the supervisor and its dev server, then stop them with their original tooling before retrying.");
+						}
+						const same = spawnedIdentity && (0, process_identity_exports.inspectProcessIdentity)(spawnedIdentity) === "same";
+						const supervisorCleanup = childExit !== null && !(0, ownership_claim_exports.processGroupAlive)(child.pid) || Boolean(same && supervisorSignalable(child) && await d.terminateSupervisorChild(child));
+						const publicationRacedCleanup = hasPublishedSupervisor();
+						if (!supervisorCleanup || d.platform !== "win32" && (0, ownership_claim_exports.processGroupAlive)(child.pid) || publicationRacedCleanup) {
+							if (publicationRacedCleanup) for (const held of claims) (0, ownership_claim_exports.markClaimChildPending)(held);
+							throw new WorkspaceProcessCleanupError(claims, `Could not confirm cleanup of supervisor pid ${child.pid}.`, `Stop supervisor pid ${child.pid} with its original tooling before retrying.`);
+						}
+						for (const held of claims) (0, ownership_claim_exports.clearClaimChild)(held);
+					} else if (unknownWindowsSpawn) throw new WorkspaceProcessCleanupError(claims, "The Windows launcher started a supervisor but its identity was not recorded.", "Inspect and stop it with its original tooling before retrying.");
+				} catch (cause) {
+					if (cause instanceof WorkspaceProcessCleanupError) throw cause;
+					throw new WorkspaceProcessCleanupError(claims, `Could not reconcile supervisor ownership: ${cause.message}`, "Inspect and stop the supervisor with its original tooling before retrying.");
+				}
+			};
+			try {
+				if (remote && !tunnel && !publicUrl && tunnelMode !== "off") {
+					const available = d.providers(tunnelMode);
+					const plan = planMetroReach({
+						mode: tunnelMode,
+						metroPort: port,
+						publicUrl,
+						isExpo: expoServer,
+						available
+					});
+					if ("failed" in plan) return fail({
+						code: "STIM_REMOTE_METRO_UNREACHABLE",
+						message: plan.failed,
+						remedy: plan.remedy
+					});
+					if ("start" in plan) {
+						const candidates = tunnelMode === "auto" ? available.filter((provider) => provider !== "tailscale") : [plan.start];
+						const expectedStableUrl = ngrokUrlSetting(settings);
+						let acquisition;
+						try {
+							acquisition = await (async () => {
+								let tracking;
+								let startedCleanup = null;
+								const recorded = readMetroTunnel(root);
+								if (recorded?.kind === "managed" && d.isTunnelAlive(recorded.pid)) {
+									if (!recorded.processToken) return { failed: {
+										code: "STIM_REMOTE_START_REQUIRED",
+										message: "The recorded managed Metro tunnel has no process identity token.",
+										remedy: "Inspect the process, stop it with the provider tooling, remove the stale metroTunnel state, and retry."
+									} };
+									if (!d.isTunnelAlive(recorded.pid, recorded.processToken)) return { failed: {
+										code: "STIM_REMOTE_START_REQUIRED",
+										message: `The recorded ${recorded.provider} tunnel pid ${recorded.pid} no longer has its recorded process identity.`,
+										remedy: "Run `stim stop`, resolve any ownership refusal, then retry `stim start --remote`."
+									} };
+									if (!(recorded.port === port && candidates.includes(recorded.provider) && (!expectedStableUrl || normalizeManagedTunnelUrl(recorded.url) === expectedStableUrl))) return { failed: {
+										code: "STIM_REMOTE_START_REQUIRED",
+										message: `A different managed Metro tunnel is already running for this workspace.`,
+										remedy: "Run `stim stop`, then `stim start --remote`."
+									} };
+									tracking = {
+										record: {
+											provider: recorded.provider,
+											pid: recorded.pid,
+											url: normalizeManagedTunnelUrl(recorded.url),
+											port: recorded.port,
+											startedAt: recorded.startedAt,
+											processToken: recorded.processToken,
+											logFile: recorded.logFile
+										},
+										startedHere: false
+									};
+								} else {
+									const currentResolution = await resolveStartupMetro(port, root);
+									const currentSupervisor = liveSupervisor({
+										state: readWorkspaceState$1(root),
+										project: getProject(root),
+										port
+									});
+									if (currentResolution.metro || currentSupervisor) return { failed: {
+										code: "STIM_REMOTE_START_REQUIRED",
+										message: `The dev server on port ${port} is local-only and cannot gain a managed tunnel while it is running.`,
+										remedy: "Run `stim stop`, then `stim start --remote`."
+									} };
+									throwIfCancelled(operationSignal, "Metro tunnel startup");
+									for (const held of claims) (0, ownership_claim_exports.markClaimChildPending)(held);
+									tunnelPending = new WorkspaceProcessCleanupError(claims, "A new managed Metro tunnel could not be recorded or confirmed stopped.", "Inspect and stop the tunnel with its provider tooling before retrying.");
+									const started = await d.startTunnelSequence({
+										claims,
+										signal: operationSignal,
+										providers: candidates,
+										port,
+										ngrokUrl: expectedStableUrl,
+										requireReachable: false
+									});
+									if ("failed" in started) {
+										if (started.cleanupFailed) {
+											tunnelPending = new WorkspaceProcessCleanupError(claims, started.reason, "Stop the tunnel with its provider tooling before retrying.");
+											throw tunnelPending;
+										}
+										for (const held of claims) (0, ownership_claim_exports.clearClaimChild)(held);
+										tunnelPending = null;
+										throwIfCancelled(operationSignal, "Metro tunnel startup");
+										return { failed: {
+											code: "STIM_REMOTE_METRO_UNREACHABLE",
+											message: `Could not start a managed Metro tunnel for port ${port}.`,
+											remedy: started.reason
+										} };
+									}
+									for (const held of claims) (0, ownership_claim_exports.setClaimChild)(held, {
+										pid: started.pid,
+										processToken: started.processToken
+									});
+									const record = {
+										provider: started.provider,
+										pid: started.pid,
+										url: normalizeManagedTunnelUrl(started.url),
+										port,
+										startedAt: (/* @__PURE__ */ new Date()).toISOString(),
+										processToken: started.processToken,
+										logFile: started.logFile
+									};
+									startedCleanup = started.cleanup;
+									try {
+										await d.writeTunnelRecord(root, { metroTunnel: {
+											kind: "managed",
+											...record
+										} });
+										const stored = readMetroTunnel(root);
+										if (stored?.kind !== "managed" || stored.pid !== record.pid || stored.processToken !== record.processToken || stored.port !== record.port || stored.provider !== record.provider || stored.url !== record.url) throw new Error("The workspace did not retain this tunnel ownership record.");
+										for (const held of claims) (0, ownership_claim_exports.clearClaimChild)(held);
+										tunnelPending = null;
+									} catch (err) {
+										const recordError = err instanceof Error ? err.message : String(err);
+										const stopped = await started.cleanup();
+										if (stopped.status === "stopped") {
+											for (const held of claims) (0, ownership_claim_exports.clearClaimChild)(held);
+											tunnelPending = null;
+										} else tunnelPending = new WorkspaceProcessCleanupError(claims, `Could not record the managed Metro tunnel: ${recordError}`, `Cleanup failed. Unmanaged pid ${record.pid} may still be running: ${stopped.reason ?? "unknown error"}`);
+										return { failed: {
+											code: "STIM_REMOTE_METRO_UNREACHABLE",
+											message: `Could not record the managed Metro tunnel: ${recordError}`,
+											remedy: stopped.status === "failed" ? `Cleanup failed. Unmanaged pid ${record.pid} may still be running: ${stopped.reason ?? "unknown error"}` : "The tunnel process was stopped. Fix the workspace write error, then retry `stim start --remote`."
+										} };
+									}
+									tracking = {
+										record,
+										startedHere: true
+									};
+								}
+								const currentResolution = await resolveStartupMetro(port, root);
+								const currentSupervisor = liveSupervisor({
+									state: readWorkspaceState$1(root),
+									project: getProject(root),
+									port
+								});
+								if (currentResolution.metro || currentSupervisor) {
+									if (tracking.startedHere && startedCleanup) {
+										const stopped = await startedCleanup();
+										if (stopped.status === "failed") return { failed: {
+											code: "STIM_REMOTE_START_REQUIRED",
+											message: `The dev server on port ${port} started before the managed tunnel was ready.`,
+											remedy: `Tunnel cleanup failed for pid ${tracking.record.pid}: ${stopped.reason ?? "unknown error"}. The tunnel record remains available to \`stim stop\`.`
+										} };
+										await d.clearTunnelRecord(root, tracking.record);
+										return { failed: {
+											code: "STIM_REMOTE_START_REQUIRED",
+											message: `The dev server on port ${port} started before the managed tunnel was ready.`,
+											remedy: "Run `stim stop`, then `stim start --remote`."
+										} };
+									}
+									return {
+										origin: tracking.record.url,
+										tunnel: tracking
+									};
+								}
+								if (!d.isTunnelAlive(tracking.record.pid, tracking.record.processToken)) {
+									if (tracking.startedHere && startedCleanup) {
+										const stopped = await startedCleanup();
+										if (stopped.status === "failed") return { failed: {
+											code: "STIM_REMOTE_METRO_UNREACHABLE",
+											message: `The managed ${tracking.record.provider} tunnel is no longer verified running before supervisor startup.`,
+											remedy: `Cleanup failed. Unmanaged pid ${tracking.record.pid} may still be running: ${stopped.reason ?? "unknown error"}. The tunnel record remains available to \`stim stop\`.`
+										} };
+									}
+									await d.clearTunnelRecord(root, tracking.record);
+									return { failed: {
+										code: "STIM_REMOTE_METRO_UNREACHABLE",
+										message: `The managed ${tracking.record.provider} tunnel is no longer verified running before supervisor startup.`,
+										remedy: "Retry `stim start --remote`."
+									} };
+								}
+								let child;
+								try {
+									child = await spawnSupervisor(tracking.record.url);
+								} catch (err) {
+									return { failed: {
+										code: "STIM_SUPERVISOR_EXITED",
+										message: `Could not spawn the dev server supervisor: ${err?.message || err}`,
+										remedy: "Fix the spawn error, then retry `stim start --remote`."
+									} };
+								}
+								const handoffRecord = {
+									pid: child.pid,
+									processToken: child.recordedIdentity ? child.recordedIdentity.processToken ?? null : child.pid ? (0, process_identity_exports.captureProcessToken)(child.pid) : null,
+									port,
+									mode: serverMode,
+									startedAt: new Date(spawnedTs ?? Date.now()).toISOString()
+								};
+								try {
+									await d.writeSupervisorRecord(root, { supervisor: handoffRecord });
+								} catch {
+									if (!await waitForSupervisorHandoff(child)) return { failed: {
+										code: "STIM_SUPERVISOR_EXITED",
+										message: `Could not record supervisor pid ${child.pid ?? "unknown"} before releasing the managed start lock.`,
+										remedy: "The supervisor process was stopped. Retry `stim start --remote`."
+									} };
+								}
+								return {
+									origin: tracking.record.url,
+									tunnel: tracking
+								};
+							})();
+						} catch (err) {
+							if (err instanceof WorkspaceProcessCleanupError) throw err;
+							throwIfCancelled(operationSignal, "Metro startup");
+							if (err instanceof Error && "code" in err && err.code === "STIM_CANCELLED") throw err;
+							return fail({
+								code: "STIM_REMOTE_METRO_UNREACHABLE",
+								message: `Could not start the managed Metro tunnel: ${err?.message || err}`,
+								remedy: "Retry `stim start --remote` after the other start command finishes."
+							});
+						}
+						if ("failed" in acquisition) return fail(acquisition.failed);
+						publicOrigin = acquisition.origin;
+						managedTunnel = acquisition.tunnel;
+						if (managedTunnel.record.provider === "tailscale") note(phaseLine("lan", `tailnet-only Metro: ${publicOrigin}`));
+						resolution = await resolveStartupMetro(port, root);
+						supervisor = liveSupervisor({
+							state: readWorkspaceState$1(root),
+							project: getProject(root),
+							port
+						});
+					}
+				}
+				const managedTunnelExited = () => managedTunnel !== null && !d.isTunnelAlive(managedTunnel.record.pid, managedTunnel.record.processToken);
+				const failExitedManagedTunnel = async () => {
+					const tracked = managedTunnel;
+					const record = tracked.record;
+					const stopped = tracked.startedHere ? await d.stopTunnel(record) : { status: "missing" };
+					if (stopped.status !== "failed") await d.clearTunnelRecord(root, record);
+					return fail({
+						code: "STIM_REMOTE_METRO_UNREACHABLE",
+						message: `The managed ${record.provider} tunnel is no longer verified running before the dev server became ready.`,
+						remedy: stopped.status === "failed" ? `The tunnel cleanup also failed: ${stopped.reason ?? "unknown error"}. Run \`stim stop\`, then retry.` : "Run `stim stop`, then `stim start --remote`."
+					});
+				};
+				const requireExpoTunnel = () => {
+					if (tunnel && (!supervisor || readMetroTunnel(root)?.kind !== "expo")) fail({
+						code: "STIM_REMOTE_START_REQUIRED",
+						message: `The Expo dev server on port ${port} is local-only and cannot gain a tunnel while it is running.`,
+						remedy: "Run `stim stop`, then `stim start --remote`."
+					});
+				};
+				if (!spawned.child && resolution.metro) {
+					if (managedTunnelExited()) return failExitedManagedTunnel();
+					if (tunnel && supervisor) {
+						if (!await waitForExpoTunnel({
+							root,
+							seconds: waitSeconds,
+							aborted: () => !liveSupervisor({
+								state: readWorkspaceState$1(root),
+								project: getProject(root),
+								port
+							})
+						})) {
+							const stillLive = liveSupervisor({
+								state: readWorkspaceState$1(root),
+								project: getProject(root),
+								port
+							});
+							return fail({
+								code: "STIM_REMOTE_START_REQUIRED",
+								message: stillLive ? `The Expo dev server on port ${port} is local-only and cannot gain a tunnel while it is running.` : `The Expo dev server on port ${port} stopped before its tunnel became ready.`,
+								remedy: stillLive ? "Run `stim stop`, then `stim start --remote`." : "Run `stim start --remote` again."
+							});
+						}
+						supervisor = liveSupervisor({
+							state: readWorkspaceState$1(root),
+							project: getProject(root),
+							port
+						});
+					}
+					requireExpoTunnel();
+					if (!supervisor) {
+						note(chalk.dim(`A dev server for this project already answers on port ${port}, started outside Stim.`));
+						note(chalk.dim("Leaving it alone: Stim will not start a second bundler over a working one."));
+					}
+					if (managedTunnelExited()) return failExitedManagedTunnel();
+					await withWorkspaceStateLockAsync(root, () => clearWorkspaceStateKeys(root, [IDLE_STOP_KEY]), operationSignal);
+					return startFacts({
+						root,
+						port,
+						supervisor,
+						logsDir,
+						alreadyRunning: true
+					});
+				}
+				if (!spawned.child && supervisor) {
+					note(chalk.dim(`Supervisor pid ${supervisor.pid} is already running for this workspace; waiting for it to answer on port ${port}...`));
+					if (!await waitForMetro({
+						root,
+						port,
+						seconds: waitSeconds,
+						aborted: managedTunnel ? managedTunnelExited : void 0
+					})) {
+						if (managedTunnelExited()) return failExitedManagedTunnel();
+						return fail({
+							code: "STIM_METRO_TIMEOUT",
+							message: `Supervisor pid ${supervisor.pid} did not serve port ${port} within ${waitSeconds}s.`,
+							lines: logTailLines(logFile),
+							remedy: "Run `stim stop` to halt it, then `stim start` again."
+						});
+					}
+					if (tunnel) {
+						if (!await waitForExpoTunnel({
+							root,
+							seconds: waitSeconds,
+							aborted: () => !liveSupervisor({
+								state: readWorkspaceState$1(root),
+								project: getProject(root),
+								port
+							})
+						})) {
+							const stillLive = liveSupervisor({
+								state: readWorkspaceState$1(root),
+								project: getProject(root),
+								port
+							});
+							return fail({
+								code: "STIM_REMOTE_START_REQUIRED",
+								message: stillLive ? `The Expo dev server on port ${port} is local-only and cannot gain a tunnel while it is running.` : `The Expo dev server on port ${port} stopped before its tunnel became ready.`,
+								remedy: stillLive ? "Run `stim stop`, then `stim start --remote`." : "Run `stim start --remote` again."
+							});
+						}
+					}
+					supervisor = liveSupervisor({
+						state: readWorkspaceState$1(root),
+						project: getProject(root),
+						port
+					}) || (tunnel ? null : supervisor);
+					requireExpoTunnel();
+					if (managedTunnelExited()) return failExitedManagedTunnel();
+					return startFacts({
+						root,
+						port,
+						supervisor,
+						logsDir,
+						alreadyRunning: true
+					});
+				}
+				if (managedTunnelExited()) return failExitedManagedTunnel();
+				const child = spawned.child ?? await spawnSupervisor(publicOrigin);
+				const attemptStartedTs = spawnedTs ?? Date.now();
+				if (!await waitForMetro({
+					root,
+					port,
+					seconds: waitSeconds,
+					aborted: () => childExit !== null || (child.pid ? !pidExists(child.pid) : false) || managedTunnelExited()
+				})) {
+					if (managedTunnelExited()) return failExitedManagedTunnel();
+					const gone = childExit !== null || (child.pid ? !pidExists(child.pid) : false);
+					const exitInfo = childExit;
+					const how = exitInfo ? exitInfo.signal ? `signal ${exitInfo.signal}` : `code ${exitInfo.code}` : "without being observed";
+					return fail(gone ? {
+						code: "STIM_SUPERVISOR_EXITED",
+						message: `The supervisor exited (${how}) before the dev server came up on port ${port}.`,
+						lines: failureEvidence({
+							logFile,
+							logsDir,
+							sinceTs: attemptStartedTs
+						}),
+						remedy: "Fix the error above and run `stim start` again; `stim logs --errors` has the full records."
+					} : {
+						code: "STIM_METRO_TIMEOUT",
+						message: `The dev server did not answer on port ${port} within ${waitSeconds}s.`,
+						lines: failureEvidence({
+							logFile,
+							logsDir,
+							sinceTs: attemptStartedTs
+						}),
+						remedy: "It may still be starting. Run `stim stop` to halt it, or `stim logs` to follow along."
+					});
+				}
+				if (managedTunnelExited()) return failExitedManagedTunnel();
+				if (tunnel) {
+					if (!await waitForExpoTunnel({
+						root,
+						seconds: waitSeconds,
+						aborted: () => childExit !== null || (child.pid ? !pidExists(child.pid) : false)
+					})) {
+						const gone = childExit !== null || (child.pid ? !pidExists(child.pid) : false);
+						return fail({
+							code: gone ? "STIM_SUPERVISOR_EXITED" : "STIM_METRO_TIMEOUT",
+							message: gone ? `The supervisor exited before the Expo tunnel became ready on port ${port}.` : `Expo did not report a tunnel URL within ${waitSeconds}s.`,
+							remedy: "Run `stim stop`, then `stim start --remote`."
+						});
+					}
+				}
+				supervisor = await waitForSupervisorHandoff(child);
+				if (!supervisor) return fail({
+					code: "STIM_SUPERVISOR_EXITED",
+					message: "The dev server answered before its supervisor ownership could be verified.",
+					remedy: "Retry `stim start` after the supervisor exits or records its ownership."
+				});
+				return startFacts({
+					root,
+					port,
+					supervisor,
+					logsDir,
+					alreadyRunning: false
+				});
+			} finally {
+				await reconcileSpawnedSupervisor();
+			}
+		};
+		const startLocked = async () => {
+			try {
+				return await d.withTunnelLock(root, (tunnelClaim) => withWorkspaceProcessLock(dirname(workspaceLogsDir$1(root)), "metro-start", (claim) => runStart(claim, tunnelClaim), {
+					external: true,
+					signal: operationSignal
+				}), { signal: operationSignal });
+			} catch (error) {
+				if (error instanceof WorkspaceProcessCleanupError || error instanceof StartRefusal) throw error;
+				throwIfCancelled(operationSignal, "Metro startup");
+				if (workspaceProcessLockError(error) === "refused") return fail({
+					code: "STIM_WORKTREE_REMOVAL_IN_PROGRESS",
+					message: `The workspace at ${root} is being removed.`,
+					remedy: "Retry `stim start` after workspace removal finishes."
+				});
+				if (workspaceProcessLockError(error) !== "timeout") throw error;
+				return fail({
+					code: "STIM_METRO_TIMEOUT",
+					message: "Another Metro start or reset is still running for this app.",
+					remedy: "Wait for it to finish, then retry `stim start`."
+				});
+			}
+		};
+		if (!managedRemote) return startLocked();
+		try {
+			return await d.withWorktreeLock(worktreeRoot, startLocked, { signal: operationSignal });
+		} catch (err) {
+			const lockError = workspaceProcessLockError(err);
+			if (lockError === "refused") return fail({
+				code: "STIM_WORKTREE_REMOVAL_IN_PROGRESS",
+				message: `The worktree at ${worktreeRoot} is being removed.`,
+				remedy: "Retry `stim start --remote` after `stim worktree remove` finishes."
+			});
+			if (lockError === "timeout") return fail({
+				code: "STIM_REMOTE_METRO_UNREACHABLE",
+				message: `Could not acquire the managed remote worktree lock: ${err?.message || err}`,
+				remedy: "Retry `stim start --remote` after the other remote start command finishes."
+			});
+			throw err;
+		}
+	};
+	try {
+		return {
+			ok: true,
+			facts: await run(),
+			waited: waitTimer(),
+			reclaimed
+		};
+	} catch (error) {
+		if (error instanceof WorkspaceProcessCleanupError) return {
+			ok: false,
+			error: startError(error),
+			lines: [],
+			reclaimed,
+			retainedClaimRoots: [...new Set(error.claims.map((claim) => claim.root))]
+		};
+		if (!(error instanceof StartRefusal)) throw error;
+		return {
+			ok: false,
+			error: startError(error.refusal),
+			lines: error.refusal.lines ?? [],
+			reclaimed
+		};
+	}
+}
+async function resolvePort(root, settings, note, fail) {
+	const result = await resolveWorkspaceMetroPort(root, settings, note, "start");
+	return typeof result === "number" ? result : fail(result);
+}
+async function resolveWorkspaceMetroPort(root, settings, note, command, reserve = true) {
+	const setting = metroPortSetting(settings, ambientEnv());
+	if (setting.error) return {
+		code: "STIM_BAD_ARG",
+		message: setting.error,
+		remedy: SETTING_SHAPE_REMEDY
+	};
+	const pinned = setting.port;
+	const project = getProject(root);
+	const recorded = project?.metroPort;
+	if (pinned === null && command === "web") return recorded ?? await reservePort(root, null);
+	if (recorded) {
+		const supervisor = resolveSupervisorTarget({
+			state: readWorkspaceState$1(root)?.supervisor,
+			record: project.supervisor,
+			reservedPort: recorded
+		});
+		if (supervisor.status !== "none" && supervisor.status !== "stale") {
+			if (pinned === null || recorded === pinned) return recorded;
+			if (supervisor.status === "unverified") return {
+				code: "STIM_BAD_ARG",
+				message: `Cannot move this workspace's Metro to metro.port ${pinned}: ${supervisor.reason}.`,
+				remedy: `Stop that supervisor with the tool that started it, then retry, or restore metro.port to ${recorded}. Stim leaves unverified processes alone.`
+			};
+			return {
+				code: "STIM_BAD_ARG",
+				message: `This workspace's dev server is running on port ${recorded}, and metro.port pins it to ${pinned}.`,
+				remedy: "Run `stim stop`, then retry, or unset or restore metro.port."
+			};
+		}
+	}
+	if (pinned !== null) {
+		const held = await resolveStartupMetro(pinned, root);
+		if (held.notOurs) return {
+			code: "STIM_BAD_ARG",
+			message: `Port ${pinned} is held by something else (${held.notOurs}), and metro.port pins this workspace's Metro to it.`,
+			remedy: "Stop the process on that port, or set another metro.port."
+		};
+		if (recorded === pinned) return recorded;
+	} else if (recorded) {
+		const held = await resolveStartupMetro(recorded, root);
+		if (!held.notOurs) return recorded;
+		const fresh = await reservePort(root, null);
+		if (typeof fresh === "number" && fresh !== recorded) {
+			note(chalk.yellow(`Port ${recorded} is held by something else (${held.notOurs}).`));
+			note(chalk.dim(`Reserved port ${fresh} for this project instead.`));
+		}
+		return fresh;
+	}
+	if (!reserve && pinned !== null) return pinned;
+	return reservePort(root, pinned);
+}
+async function reservePort(root, pinned) {
+	try {
+		return await reserveMetroPort(root, void 0, void 0, pinned, ambientContext()?.signal);
+	} catch (error) {
+		throwIfCancelled(ambientContext()?.signal, "Metro startup");
+		if (error instanceof PortInspectionError) return {
+			code: error.code,
+			message: error.reason,
+			remedy: PORT_INSPECTION_REMEDY
+		};
+		return {
+			code: "STIM_BAD_ARG",
+			message: error.message,
+			remedy: "Give each workspace its own metro.port, in the workspace layer or the environment."
+		};
+	}
+}
+async function waitForMetro({ root, port, seconds, aborted = () => false, probe = resolveStartupMetro }) {
+	const deadline = Date.now() + seconds * 1e3;
+	while (Date.now() < deadline) {
+		if ((await probe(port, root)).metro) return true;
+		if (aborted()) return false;
+		await waitForStartup(POLL_MS);
+	}
+	const last = await probe(port, root);
+	return Boolean(last.metro);
+}
+async function waitForExpoTunnel({ root, seconds, aborted = () => false }) {
+	const deadline = Date.now() + seconds * 1e3;
+	while (Date.now() < deadline) {
+		if (aborted()) return false;
+		if (readMetroTunnel(root)?.kind === "expo") return true;
+		await waitForStartup(POLL_MS);
+	}
+	return !aborted() && readMetroTunnel(root)?.kind === "expo";
+}
+function logTailLines(logFile) {
+	return [...readLogTail(logFile), `Supervisor log: ${logFile}`];
+}
+function failureEvidence({ logFile, logsDir, sinceTs }) {
+	const supTail = readLogTail(logFile);
+	const lines = supTail.length > 0 ? [...supTail, `Supervisor log: ${logFile}`] : [];
+	let errors = [];
+	let all = [];
+	try {
+		all = queryLogs({ dir: logsDir });
+		errors = all.filter((record) => levelRank(record.level) >= levelRank("error"));
+	} catch {}
+	const since = (rs) => rs.filter((r) => typeof r.ts === "number" && r.ts >= sinceTs).slice(-8);
+	let recent = since(errors);
+	const fellBack = recent.length === 0;
+	if (fellBack) recent = since(all);
+	for (const r of recent) lines.push(`${String(r.src ?? "?")}: ${String(r.msg ?? "").split("\n")[0] ?? ""}`);
+	if (recent.length > 0) lines.push(fellBack ? "Full records: `stim logs`" : "Full records: `stim logs --errors`");
+	return lines;
+}
+function report({ json, out, facts, waited, reclaimed, links }) {
+	if (json) {
+		console.log(JSON.stringify({
+			...facts,
+			...links ? { links } : {},
+			...reclaimed.length ? { reclaimed } : {}
+		}));
+		return;
+	}
+	const who = facts.supervisorPid ? `supervisor pid ${facts.supervisorPid}${facts.mode ? ` (${facts.mode})` : ""}` : "started outside Stim";
+	out(chalk.green(`OK: dev server on port ${facts.port}, ${who}${facts.alreadyRunning ? " (already running)" : ""} ${waited}`));
+	out(chalk.dim(phaseLine("logs", facts.logsDir)));
+	if (facts.agentDevice) out(chalk.dim(phaseLine("agent-device", `AGENT_DEVICE_STATE_DIR=${facts.agentDevice.stateDir}`)));
+	if (links) console.error(chalk.dim(workspaceLinkLine(links)));
+}
+//#endregion
+export { registerStart as a, startDevServer as c, supervisorSignalable as d, tailLines as f, detectBundleId as g, detectAppIds as h, readLogTail as i, startFacts as l, detectAndroidPackage as m, liveSupervisor as n, resolveWorkspaceMetroPort as o, wantsExpoOwnTunnel as p, parseWait as r, startCommand as s, failureEvidence as t, supervisorEntry as u };