stim 1.0.0 → 1.1.0

package/dist/start-ByCylYtB.mjs

@@ -0,0 +1,822 @@
+import { t as getExecutor } from "./exec-bsN9MJXb.mjs";
+import { E as inspectProcessIdentity, O as waitForProcessExit, S as upsertProject, T as captureProcessToken, a as clearSupervisor, f as getProject } from "./config-D7uu8Gbq.mjs";
+import { C as supervisorLogFile, D as workspaceLogsDir, _ as writeWorkspaceState, c as readMetroTunnel, i as clearManagedMetroTunnel, p as readWorkspaceState, s as clearWorkspaceSupervisor, y as ensureWorkspaceStorage } from "./state-IYEY-zi8.mjs";
+import { g as repoRoot, s as gitCommonDir } from "./worktree-Dx3ZC5lS.mjs";
+import { a as findProjectRoot, i as detectIsExpo, n as detectAndroidPackage, r as detectBundleId, t as appProjectProblem } from "./project-COj6nzzh.mjs";
+import { n as supervisorError } from "./errors-B6W7FkxQ.mjs";
+import { i as resolveProjectMetro, n as killMetroTree, o as reserveMetroPort, r as pidExists } from "./metro-B01H3EuD.mjs";
+import { D as remoteIosSetting, E as remoteDeviceSettingError, F as unknownSettingKeys, I as PUBLIC_METRO_ENV, L as detectProviders, M as settingShapeErrors, O as resolveCacheProviderConfig, P as tunnelModeSetting, R as planMetroReach, T as remoteAndroidSetting, a as SETTING_SHAPE_REMEDY, b as metroTunnelSettingError, d as cacheProviderSettingError, k as resolveSettings, w as publicUrlSetting, x as ngrokUrlSetting } from "./settings-BSwrY4FZ.mjs";
+import { g as stepTimer, l as phaseLine } from "./command-output-8wHMEde0.mjs";
+import { n as workspaceProcessLockError, t as withWorkspaceProcessLock } from "./workspace-process-lock-CxOO9-pf.mjs";
+import { n as expoMetroConfigPath } from "./metro-store-CDDZHtPl.mjs";
+import { o as expoSdkMajor } from "./server-expo-BEMr_m6p.mjs";
+import { t as spawnEntry } from "./spawn-entry-nCE6m770.mjs";
+import { s as queryLogs } from "./logs-query-oqn47Ffx.mjs";
+import { a as withManagedRemoteWorktreeLock, i as terminateChild, n as startTunnelSequence, r as stopTunnel, s as withManagedTunnelLock, t as resolveSupervisorTarget } from "./ownership-B9QIdQOw.mjs";
+import { mkdirSync, openSync, readFileSync } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { dirname } from "node:path";
+import chalk from "chalk";
+import { CACHE_PROVIDER_ENV, cacheProviderEnv } from "@stim-cli/cache";
+//#region src/supervisor/cache-reset.ts
+async function resetMetroCache(root) {
+	if (detectIsExpo(root) && ((expoSdkMajor(root) ?? 0) < 54 || !expoMetroConfigPath())) throw supervisorError("STIM_BAD_ARG", "An isolated Metro cache reset requires Expo SDK 54 or newer and the Stim Metro config adapter.", "Upgrade Expo or repair the Stim installation before retrying. The running server was not changed.");
+	const project = getProject(root);
+	const port = project?.metroPort;
+	const target = resolveSupervisorTarget({
+		state: readWorkspaceState(root)?.supervisor,
+		record: project?.supervisor,
+		reservedPort: port
+	});
+	if (target.status === "unverified") throw supervisorError("STIM_SUPERVISOR_EXITED", `Cannot reset Metro: ${target.reason}.`, "Stop it with the tool that started it, then retry. Stim leaves unverified processes alone.");
+	if (port && target.status !== "ours" && !(await resolveProjectMetro(port, root)).missing) throw supervisorError("STIM_SUPERVISOR_EXITED", "Cannot reset an externally started dev server.", "Stop it with the tool that started it, then retry `stim start --reset-cache`.");
+	if (target.status === "ours") {
+		const expected = {
+			pid: target.pid,
+			processToken: target.processToken
+		};
+		if (!killMetroTree(target.pid, target.processToken) || !await waitForProcessExit(expected, 1e4)) throw supervisorError("STIM_SUPERVISOR_EXITED", "The owned Metro supervisor could not be stopped for a cache reset.", "Inspect `stim status` and `stim logs`, then retry. No cache reset was recorded.");
+		if (port && !(await resolveProjectMetro(port, root)).missing) throw supervisorError("STIM_SUPERVISOR_EXITED", `Port ${port} is still occupied after stopping Metro.`, "Inspect the listener before retrying. Stim does not terminate unrecorded processes.");
+		clearWorkspaceSupervisor(root, expected);
+		clearSupervisor(root, expected);
+	}
+	writeWorkspaceState(root, { metroCacheGeneration: randomUUID() });
+}
+//#endregion
+//#region src/commands/start.ts
+const DEFAULT_WAIT_SECONDS = 60;
+const POLL_MS = 500;
+const LOG_TAIL_LINES = 5;
+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 = 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({ port, supervisor, logsDir, alreadyRunning }) {
+	return {
+		port,
+		supervisorPid: supervisor?.pid ?? null,
+		mode: supervisor?.mode ?? null,
+		logsDir,
+		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 [];
+	}
+}
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+function startCommand(program) {
+	registerStart(program);
+}
+function providersOnPath() {
+	return detectProviders((bin) => {
+		try {
+			return Boolean(getExecutor().runQuiet(`command -v ${bin}`, { timeoutMs: 5e3 }));
+		} catch {
+			return false;
+		}
+	});
+}
+const DEFAULT_START_DEPS = {
+	providers: providersOnPath,
+	startTunnelSequence,
+	isTunnelAlive: pidExists,
+	writeTunnelRecord: writeWorkspaceState,
+	stopTunnel,
+	writeSupervisorRecord: writeWorkspaceState,
+	terminateSupervisorChild: (child) => terminateChild(child, {
+		alreadyExited: false,
+		timeoutMs: 1e3,
+		now: Date.now,
+		sleep,
+		isAlive: pidExists
+	}),
+	withWorktreeLock: withManagedRemoteWorktreeLock,
+	withTunnelLock: withManagedTunnelLock,
+	clearTunnelRecord: clearManagedMetroTunnel
+};
+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 with fresh per-app transform and file-map cache state").action(async (opts) => {
+		const json = Boolean(opts.json);
+		const waitTimer = stepTimer();
+		const out = (line) => {
+			if (json) console.error(line);
+			else console.log(line);
+		};
+		const note = writeNote;
+		const fail = ({ code, message, remedy = null, lines = [] }) => {
+			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
+			})));
+			process.exit(1);
+		};
+		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(process.cwd());
+		if (!root) return fail({
+			code: "STIM_NO_PROJECT",
+			message: "Not in a React Native project (no package.json found).",
+			remedy: "Run this from the app directory -- the one holding package.json."
+		});
+		const projectProblem = appProjectProblem(root);
+		if (projectProblem) return fail({
+			code: "STIM_NO_PROJECT",
+			message: projectProblem.message,
+			remedy: projectProblem.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`)."
+			});
+		}
+		const isExpo = detectIsExpo(root);
+		const worktreeRoot = repoRoot(root) ?? root;
+		const settingsContext = {
+			projectPath: root,
+			gitCommonDir: gitCommonDir(root),
+			repoRoot: worktreeRoot
+		};
+		const settings = resolveSettings(settingsContext);
+		const [shapeError, ...moreShapeErrors] = settingShapeErrors(settings);
+		if (shapeError) return fail({
+			code: "STIM_BAD_ARG",
+			message: shapeError,
+			lines: moreShapeErrors,
+			remedy: SETTING_SHAPE_REMEDY
+		});
+		const cacheProvider = resolveCacheProviderConfig(settingsContext);
+		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 settingError = metroTunnelSettingError(settings);
+		if (settingError) return fail({
+			code: "STIM_BAD_ARG",
+			message: settingError,
+			remedy: `Set metro.tunnel to one of: auto, expo, ngrok, cloudflared, off.`
+		});
+		const remoteSettingError = remoteDeviceSettingError(settings);
+		if (remoteSettingError) return fail({
+			code: "STIM_BAD_ARG",
+			message: remoteSettingError,
+			remedy: "Set ios.remote and android.remote to either proxy or eas."
+		});
+		const remote = Boolean(opts.remote) || remoteIosSetting(settings) !== null || remoteAndroidSetting(settings) !== null;
+		const tunnelMode = tunnelModeSetting(settings) ?? "auto";
+		const publicUrl = publicUrlSetting(settings);
+		const tunnel = wantsExpoOwnTunnel({
+			isExpo,
+			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 () => {
+			upsertProject(root, {
+				bundleId: detectBundleId(root) ?? void 0,
+				androidPackage: detectAndroidPackage(root) ?? void 0,
+				isExpo
+			});
+			if (opts.resetCache) {
+				try {
+					await resetMetroCache(root);
+				} catch (error) {
+					const failure = error;
+					return fail({
+						code: failure.code ?? "STIM_WORKSPACE_STATE",
+						message: failure.message,
+						remedy: failure.remedy
+					});
+				}
+				note(phaseLine("cache", "fresh Metro cache state for this app; shared cache entries and devices preserved"));
+			}
+			const logsDir = workspaceLogsDir(root);
+			const logFile = supervisorLogFile(root);
+			const port = await resolvePort(root, note);
+			let publicOrigin = remote ? publicUrl : null;
+			let resolution = await resolveProjectMetro(port, root);
+			let supervisor = liveSupervisor({
+				state: readWorkspaceState(root),
+				project: getProject(root),
+				port
+			});
+			const recordedTarget = resolveSupervisorTarget({
+				state: readWorkspaceState(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."
+			});
+			let managedTunnel = null;
+			let spawnedChild = null;
+			let spawnedTs = null;
+			let childExit = null;
+			const spawnSupervisor = (origin) => {
+				mkdirSync(logsDir, { recursive: true });
+				const fd = openSync(logFile, "a");
+				spawnedTs = Date.now();
+				const supervisorArgs = [
+					supervisorEntry(),
+					"--root",
+					root,
+					"--port",
+					String(port),
+					...tunnel ? ["--tunnel"] : []
+				];
+				const childEnv = {
+					...process.env,
+					...origin ? {
+						[PUBLIC_METRO_ENV]: origin,
+						EXPO_PACKAGER_PROXY_URL: origin
+					} : {}
+				};
+				childEnv[CACHE_PROVIDER_ENV] = cacheProviderEnv(cacheProvider);
+				const child = getExecutor().spawn(process.execPath, supervisorArgs, {
+					cwd: root,
+					detached: true,
+					stdio: [
+						"ignore",
+						fd,
+						fd
+					],
+					env: childEnv
+				});
+				child.unref?.();
+				child.on?.("exit", (code, signal) => {
+					childExit = {
+						code,
+						signal
+					};
+				});
+				child.on?.("error", (err) => {
+					childExit = {
+						code: null,
+						signal: null,
+						error: err
+					};
+				});
+				out(chalk.dim(phaseLine("metro", `starting on port ${port} (${isExpo ? "expo-child" : "bare-inproc"}, supervisor pid ${child.pid})`)));
+				spawnedChild = child;
+				return child;
+			};
+			const waitForSupervisorHandoff = async (child) => {
+				const deadline = Date.now() + 5e3;
+				while (Date.now() < deadline) {
+					const found = liveSupervisor({
+						state: readWorkspaceState(root),
+						project: getProject(root),
+						port
+					});
+					if (found?.pid === child.pid) return found;
+					if (childExit !== null || (child.pid ? !pidExists(child.pid) : true)) return null;
+					await sleep(25);
+				}
+				return null;
+			};
+			if (remote && !tunnel && !publicUrl && tunnelMode !== "off") {
+				const available = d.providers();
+				const plan = planMetroReach({
+					mode: tunnelMode,
+					metroPort: port,
+					publicUrl,
+					isExpo,
+					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 : [plan.start];
+					const expectedStableUrl = ngrokUrlSetting(settings);
+					let acquisition;
+					try {
+						acquisition = await d.withTunnelLock(root, 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 (!(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 resolveProjectMetro(port, root);
+								const currentSupervisor = liveSupervisor({
+									state: readWorkspaceState(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`."
+								} };
+								const started = await d.startTunnelSequence({
+									providers: candidates,
+									port,
+									ngrokUrl: expectedStableUrl,
+									requireReachable: false
+								});
+								if ("failed" in started) return { failed: {
+									code: "STIM_REMOTE_METRO_UNREACHABLE",
+									message: `Could not start a managed Metro tunnel for port ${port}.`,
+									remedy: started.reason
+								} };
+								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 {
+									d.writeTunnelRecord(root, { metroTunnel: {
+										kind: "managed",
+										...record
+									} });
+								} catch (err) {
+									const stopped = await started.cleanup();
+									return { failed: {
+										code: "STIM_REMOTE_METRO_UNREACHABLE",
+										message: `Could not record the managed Metro tunnel: ${err?.message || err}`,
+										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 resolveProjectMetro(port, root);
+							const currentSupervisor = liveSupervisor({
+								state: readWorkspaceState(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\`.`
+									} };
+									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)) {
+								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 exited before the supervisor started.`,
+										remedy: `Cleanup failed. Unmanaged pid ${tracking.record.pid} may still be running: ${stopped.reason ?? "unknown error"}. The tunnel record remains available to \`stim stop\`.`
+									} };
+								}
+								d.clearTunnelRecord(root, tracking.record);
+								return { failed: {
+									code: "STIM_REMOTE_METRO_UNREACHABLE",
+									message: `The managed ${tracking.record.provider} tunnel exited before the supervisor started.`,
+									remedy: "Retry `stim start --remote`."
+								} };
+							}
+							let child;
+							try {
+								child = 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.pid ? captureProcessToken(child.pid) : null,
+								port,
+								mode: isExpo ? "expo-child" : "bare-inproc",
+								startedAt: new Date(spawnedTs ?? Date.now()).toISOString()
+							};
+							try {
+								d.writeSupervisorRecord(root, { supervisor: handoffRecord });
+							} catch {
+								if (!await waitForSupervisorHandoff(child)) {
+									const stopped = await d.terminateSupervisorChild(child);
+									return { failed: {
+										code: "STIM_SUPERVISOR_EXITED",
+										message: `Could not record supervisor pid ${child.pid ?? "unknown"} before releasing the managed start lock.`,
+										remedy: stopped ? "The supervisor process was stopped. Retry `stim start --remote`." : `Cleanup failed. Unmanaged supervisor pid ${child.pid ?? "unknown"} may still be running. Stop it before retrying.`
+									} };
+								}
+							}
+							return {
+								origin: tracking.record.url,
+								tunnel: tracking
+							};
+						});
+					} catch (err) {
+						return fail({
+							code: "STIM_REMOTE_METRO_UNREACHABLE",
+							message: `Could not acquire the managed Metro tunnel lock: ${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;
+					resolution = await resolveProjectMetro(port, root);
+					supervisor = liveSupervisor({
+						state: readWorkspaceState(root),
+						project: getProject(root),
+						port
+					});
+				}
+			}
+			const managedTunnelExited = () => managedTunnel !== null && !d.isTunnelAlive(managedTunnel.record.pid);
+			const failExitedManagedTunnel = async () => {
+				const tracked = managedTunnel;
+				const record = tracked.record;
+				const stopped = tracked.startedHere ? await d.stopTunnel(record) : { status: "missing" };
+				if (stopped.status !== "failed") d.clearTunnelRecord(root, record);
+				return fail({
+					code: "STIM_REMOTE_METRO_UNREACHABLE",
+					message: `The managed ${record.provider} tunnel exited 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 (!spawnedChild && resolution.metro) {
+				if (managedTunnelExited()) return failExitedManagedTunnel();
+				if (tunnel && supervisor) {
+					if (!await waitForExpoTunnel({
+						root,
+						seconds: waitSeconds,
+						aborted: () => !liveSupervisor({
+							state: readWorkspaceState(root),
+							project: getProject(root),
+							port
+						})
+					})) {
+						const stillLive = liveSupervisor({
+							state: readWorkspaceState(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(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();
+				report({
+					json,
+					out,
+					port,
+					supervisor,
+					logsDir,
+					alreadyRunning: true,
+					waited: waitTimer()
+				});
+				return;
+			}
+			if (!spawnedChild && 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(root),
+							project: getProject(root),
+							port
+						})
+					})) {
+						const stillLive = liveSupervisor({
+							state: readWorkspaceState(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(root),
+					project: getProject(root),
+					port
+				}) || (tunnel ? null : supervisor);
+				requireExpoTunnel();
+				if (managedTunnelExited()) return failExitedManagedTunnel();
+				report({
+					json,
+					out,
+					port,
+					supervisor,
+					logsDir,
+					alreadyRunning: true,
+					waited: waitTimer()
+				});
+				return;
+			}
+			if (managedTunnelExited()) return failExitedManagedTunnel();
+			const child = spawnedChild ?? 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 = liveSupervisor({
+				state: readWorkspaceState(root),
+				project: getProject(root),
+				port
+			}) || {
+				pid: child.pid,
+				port,
+				mode: null,
+				startedAt: null
+			};
+			report({
+				json,
+				out,
+				port,
+				supervisor,
+				logsDir,
+				alreadyRunning: false,
+				waited: waitTimer()
+			});
+		};
+		const startLocked = async () => {
+			try {
+				return await withWorkspaceProcessLock(dirname(workspaceLogsDir(root)), "metro-start", runStart, { external: true });
+			} catch (error) {
+				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);
+		} 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;
+		}
+	});
+}
+async function resolvePort(root, note) {
+	const recorded = getProject(root)?.metroPort;
+	if (!recorded) return await reserveMetroPort(root);
+	const held = await resolveProjectMetro(recorded, root);
+	if (!held.notOurs) return recorded;
+	const fresh = await reserveMetroPort(root);
+	if (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;
+}
+async function waitForMetro({ root, port, seconds, aborted = () => false, probe = resolveProjectMetro }) {
+	const deadline = Date.now() + seconds * 1e3;
+	while (Date.now() < deadline) {
+		if ((await probe(port, root)).metro) return true;
+		if (aborted()) return false;
+		await sleep(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 sleep(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 {
+		errors = queryLogs({
+			dir: logsDir,
+			minLevel: "error"
+		});
+		all = queryLogs({ dir: logsDir });
+	} 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, port, supervisor, logsDir, alreadyRunning, waited }) {
+	const facts = startFacts({
+		port,
+		supervisor,
+		logsDir,
+		alreadyRunning
+	});
+	if (json) {
+		console.log(JSON.stringify(facts));
+		return facts;
+	}
+	const who = facts.supervisorPid ? `supervisor pid ${facts.supervisorPid}${facts.mode ? ` (${facts.mode})` : ""}` : "started outside Stim";
+	out(chalk.green(`OK: dev server on port ${port}, ${who}${alreadyRunning ? " (already running)" : ""} ${waited}`));
+	out(chalk.dim(phaseLine("logs", logsDir)));
+	return facts;
+}
+//#endregion
+export { startCommand as default, failureEvidence, liveSupervisor, parseWait, readLogTail, registerStart, startFacts, supervisorEntry, tailLines, wantsExpoOwnTunnel };