stim 1.3.1 → 1.4.0

package/dist/{doctor-B4EITgQB.mjs → doctor-B_mfURdt.mjs}

@@ -1,21 +1,228 @@
 import { t as getExecutor } from "./exec-CyylIdq9.mjs";
-import { g as loadConfig, l as getConcurrencyLimits, o as configCorruptRepair } from "./config-CcefMY2Q.mjs";
-import { b as sharedBuildCache, w as workspaceDerivedData } from "./state-B3XA2wp2.mjs";
-import { S as makeTemporaryDirectory, a as dirtyFingerprintFiles, f as listWorktrees, g as repoRoot, s as gitCommonDir, w as temporaryRoot, x as filesystemDevice } from "./worktree-Eq6TLH8N.mjs";
-import { i as detectIsExpo, t as appProjectProblem } from "./project-fKmuIaMI.mjs";
-import { d as quotedPath, u as plural } from "./command-output-8wHMEde0.mjs";
-import { B as listBuildLocks, Z as fingerprintProject, q as diffFingerprintSources, y as listAdbDevices } from "./android-hMj83VpN.mjs";
-import { A as resolveSettings, E as remoteAndroidSetting, I as unknownSettingKeys, M as settingOrigin, N as settingShapeErrors, O as remoteIosSetting, P as settingsLayers, U as resolveOptimizations, V as compilerCacheFallbackMessage, a as SETTING_SHAPE_REMEDY, i as SETTINGS_WITH_RESOLVE_TIME_FALLBACK, n as PATH_SETTINGS, v as iosSimSlimProfileSetting, w as projectOptimizations, y as mergeSettingsLayers } from "./settings-DEJf6_kJ.mjs";
-import { a as POOL_SETTING_REMEDY, b as providerFromConfig, c as parkedMaxSetting, m as checkEasAuth$1, x as resolveEasCliBin, y as ownerFromConfig } from "./teardown--gESs9ck.mjs";
+import { g as loadConfig, l as getConcurrencyLimits, o as configCorruptRepair } from "./config-6vdGngKa.mjs";
+import { l as sharedBuildCache, m as workspaceDerivedData } from "./workspace-state-Do1e2mOH.mjs";
+import { C as makeTemporaryDirectory, S as filesystemDevice, T as temporaryRoot, _ as repoRoot, a as dirtyFingerprintFiles, f as listWorktrees, p as locallyKnownUpstream, s as gitCommonDir } from "./worktree-DWNx4tUg.mjs";
+import { a as findProjectRoot, i as detectIsExpo, t as appProjectProblem } from "./project-CBFCwnN5.mjs";
+import { d as quotedPath, l as phaseLine, u as plural } from "./command-output-BuIb_ZOI.mjs";
+import { B as listBuildLocks, Z as fingerprintProject, q as diffFingerprintSources, y as listAdbDevices } from "./android-BkM4qTaN.mjs";
+import { A as resolveSettings, E as remoteAndroidSetting, I as unknownSettingKeys, M as settingOrigin, N as settingShapeErrors, O as remoteIosSetting, P as settingsLayers, U as resolveOptimizations, V as compilerCacheFallbackMessage, a as SETTING_SHAPE_REMEDY, i as SETTINGS_WITH_RESOLVE_TIME_FALLBACK, n as PATH_SETTINGS, v as iosSimSlimProfileSetting, w as projectOptimizations, y as mergeSettingsLayers } from "./settings-DwfltIXQ.mjs";
+import { S as resolveEasCliBin, a as POOL_SETTING_REMEDY, b as ownerFromConfig, h as checkEasAuth$1, l as parkedMaxSetting, x as providerFromConfig } from "./teardown-KsPpvldq.mjs";
 import { E as readHostMemoryPressure, T as hostMemoryPressureAdvice, u as listAllIosSims } from "./ios-Deh5js5V.mjs";
-import { n as listBuildSlots } from "./build-slots-C4AouyNz.mjs";
-import { C as liveOwnedDeviceCount, D as simslimIsOnPath, a as ccacheEnabled, g as podInstallCommand } from "./xcode-xnxyvJkD.mjs";
-import { d as projectCmakeLauncher, i as apkOutputsDir, r as resolveAndroidCompilerCache, t as readAndroidCasToolchain } from "./android-cas-DXorPCi_.mjs";
-import { existsSync, lstatSync, readFileSync, readdirSync, realpathSync, rmSync } from "node:fs";
-import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
-import { existsSync as existsSync$1, lstatSync as lstatSync$1, readFileSync as readFileSync$1, readdirSync as readdirSync$1, realpathSync as realpathSync$1, rmSync as rmSync$1 } from "fs";
+import { n as listBuildSlots } from "./build-slots-D6sDzOe-.mjs";
+import { a as liveOwnedDeviceCount, d as simslimIsOnPath } from "./device-CMDFzx7C.mjs";
+import { d as projectCmakeLauncher, i as apkOutputsDir, r as resolveAndroidCompilerCache, t as readAndroidCasToolchain } from "./android-cas-BjLRZyks.mjs";
+import { h as podInstallCommand, i as ccacheEnabled, o as detectXcodeMajor } from "./xcode-D9tVItl-.mjs";
+import { n as hasInstalledDependencies, r as installedNpmTreeIsValid, t as dependencyState } from "./dependency-state-BMirHEPD.mjs";
+import { accessSync, constants, existsSync, lstatSync, readFileSync, readdirSync, realpathSync, rmSync, statSync } from "node:fs";
+import { InvalidArgumentError } from "commander";
+import { basename, delimiter, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { existsSync as existsSync$1, lstatSync as lstatSync$1, mkdirSync as mkdirSync$1, readFileSync as readFileSync$1, readdirSync as readdirSync$1, realpathSync as realpathSync$1, renameSync as renameSync$1, rmSync as rmSync$1, writeFileSync as writeFileSync$1 } from "fs";
+import { homedir } from "os";
 import { dirname as dirname$1, isAbsolute as isAbsolute$1, join as join$1, relative as relative$1, resolve as resolve$1 } from "path";
 import * as expoFingerprint from "@expo/fingerprint";
+import chalk from "chalk";
+//#region src/sandbox.ts
+/**
+* What a sandboxed harness has to permit for Stim to work: its state
+* directory, the XPC service simctl talks to, and the port adb's server binds.
+*/
+function sandboxAllowance(stimHome = "~/.stim") {
+	return {
+		allowWrite: [stimHome],
+		allowMachLookup: ["com.apple.coresimulator.*"],
+		allowLocalBinding: true
+	};
+}
+function detectHarness(env = process.env) {
+	if (env.CLAUDECODE || env.CLAUDE_CODE_ENTRYPOINT) return "claude-code";
+	if (Object.keys(env).some((k) => k.startsWith("CODEX_"))) return "codex";
+	return null;
+}
+function expandHome(value, home) {
+	const v = value.trim();
+	if (v === "~" || v === "$HOME") return home;
+	if (v.startsWith("~/")) return join$1(home, v.slice(2));
+	if (v.startsWith("$HOME/")) return join$1(home, v.slice(6));
+	return v;
+}
+/**
+* Whether the sandbox actually stops Stim, rather than whether a harness that
+* can sandbox is present: a session with its sandbox off exports the same
+* variables as one with it on, so only a write says which this is.
+*/
+function sandboxBlocksStimHome(stimHome, home = homedir()) {
+	const dir = expandHome(stimHome, home);
+	const probe = join$1(dir, `.probe-${process.pid}-${Math.random().toString(36).slice(2)}`);
+	try {
+		mkdirSync$1(dir, { recursive: true });
+		writeFileSync$1(probe, "");
+		rmSync$1(probe, { force: true });
+		return false;
+	} catch (err) {
+		const code = err.code;
+		return code === "EPERM" || code === "EACCES";
+	}
+}
+/** Where a per-user, gitignored Claude Code settings file belongs for this project. */
+function claudeLocalSettingsPath(root) {
+	return join$1(root, ".claude", "settings.local.json");
+}
+/** Every settings file that may already carry the allowance, most local first. */
+function allowanceSearchPaths(settingsRoot, home = homedir()) {
+	return [
+		claudeLocalSettingsPath(settingsRoot),
+		join$1(settingsRoot, ".claude", "settings.json"),
+		join$1(home, ".claude", "settings.json")
+	];
+}
+function isPlainObject(value) {
+	return !!value && typeof value === "object" && !Array.isArray(value);
+}
+/**
+* Absent, unreadable and present-but-not-an-object are three different states.
+* Collapsing them loses the one distinction that matters before a write: a
+* file whose contents did not parse still holds settings we must not destroy.
+*/
+function readSettings(path) {
+	let raw;
+	try {
+		raw = readFileSync$1(path, "utf-8");
+	} catch (err) {
+		return err.code === "ENOENT" ? { kind: "absent" } : { kind: "invalid" };
+	}
+	try {
+		const parsed = JSON.parse(raw);
+		return isPlainObject(parsed) ? {
+			kind: "object",
+			value: parsed
+		} : { kind: "invalid" };
+	} catch {
+		return { kind: "invalid" };
+	}
+}
+function nested(source, ...keys) {
+	let cursor = source;
+	for (const key of keys) {
+		if (!isPlainObject(cursor)) return void 0;
+		cursor = cursor[key];
+	}
+	return cursor;
+}
+/** Whether an allowWrite entry covers the Stim home, including as a parent. */
+function covers(entry, target, home) {
+	const e = expandHome(entry.replace(/\/+\*+$/, "").replace(/\/+$/, ""), home);
+	const t = expandHome(target.replace(/\/+$/, ""), home);
+	return e === t || t.startsWith(`${e}/`);
+}
+/**
+* Which parts of the allowance the settings files already carry. Any file may
+* supply any part, so a project that solved this in one place is not asked to
+* repeat it in another.
+*/
+function missingAllowance(paths, stimHome = "~/.stim", home = homedir()) {
+	const files = paths.map((p) => {
+		const read = readSettings(p);
+		return read.kind === "object" ? read.value : null;
+	});
+	const list = (...keys) => files.flatMap((f) => {
+		const value = nested(f, ...keys);
+		return Array.isArray(value) ? value.map(String) : [];
+	});
+	const missing = [];
+	if (!list("sandbox", "filesystem", "allowWrite").some((w) => covers(w, stimHome, home))) missing.push("sandbox.filesystem.allowWrite");
+	if (!list("sandbox", "network", "allowMachLookup").some((l) => l.toLowerCase().startsWith("com.apple.coresimulator"))) missing.push("sandbox.network.allowMachLookup");
+	if (!files.some((f) => nested(f, "sandbox", "network", "allowLocalBinding") === true)) missing.push("sandbox.network.allowLocalBinding");
+	return missing;
+}
+/**
+* The key that stops a merge, or null when the settings can take the
+* allowance. A value of an unexpected shape is someone else's, and rewriting
+* it would lose whatever it means.
+*/
+function unmergeableKey(settings) {
+	if (!("sandbox" in settings)) return null;
+	if (!isPlainObject(settings.sandbox)) return "sandbox";
+	const sandbox = settings.sandbox;
+	if ("filesystem" in sandbox && !isPlainObject(sandbox.filesystem)) return "sandbox.filesystem";
+	if ("network" in sandbox && !isPlainObject(sandbox.network)) return "sandbox.network";
+	return null;
+}
+/** Merge the allowance into a settings object, leaving everything else as it is. */
+function withAllowance(settings, allowance) {
+	const next = { ...settings };
+	const sandbox = isPlainObject(next.sandbox) ? { ...next.sandbox } : {};
+	const filesystem = isPlainObject(sandbox.filesystem) ? { ...sandbox.filesystem } : {};
+	const network = isPlainObject(sandbox.network) ? { ...sandbox.network } : {};
+	const writes = Array.isArray(filesystem.allowWrite) ? filesystem.allowWrite.map(String) : [];
+	const lookups = Array.isArray(network.allowMachLookup) ? network.allowMachLookup.map(String) : [];
+	filesystem.allowWrite = [.../* @__PURE__ */ new Set([...writes, ...allowance.allowWrite])];
+	network.allowMachLookup = [.../* @__PURE__ */ new Set([...lookups, ...allowance.allowMachLookup])];
+	network.allowLocalBinding = true;
+	sandbox.filesystem = filesystem;
+	sandbox.network = network;
+	next.sandbox = sandbox;
+	return next;
+}
+/**
+* Write the allowance into a Claude Code local settings file, creating it if
+* needed. Refuses whenever the current contents cannot be read back, because
+* the merge would replace settings rather than extend them.
+*/
+function applyClaudeAllowance(path, allowance) {
+	const read = readSettings(path);
+	if (read.kind === "invalid") return {
+		status: "refused",
+		reason: `${path} is not a plain JSON object, so Stim cannot merge into it without losing what is there. Comments make a settings file unparseable here even though Claude Code accepts them.`
+	};
+	const existing = read.kind === "object" ? read.value : {};
+	const blocker = unmergeableKey(existing);
+	if (blocker) return {
+		status: "refused",
+		reason: `${path} holds a "${blocker}" that is not an object, so Stim cannot merge into it without discarding that value.`
+	};
+	mkdirSync$1(dirname$1(path), { recursive: true });
+	const tmp = `${path}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`;
+	writeFileSync$1(tmp, `${JSON.stringify(withAllowance(existing, allowance), null, 2)}\n`);
+	try {
+		renameSync$1(tmp, path);
+	} catch (err) {
+		rmSync$1(tmp, { force: true });
+		throw err;
+	}
+	return { status: read.kind === "absent" ? "created" : "updated" };
+}
+/**
+* The finding a sandboxed session should see: what fails, and the one command
+* that fixes it where the harness has a per-path allowance.
+*/
+function sandboxFinding(settingsRoot, { env = process.env, home = homedir(), stimHome = process.env.STIM_HOME || "~/.stim", blocked } = {}) {
+	const harness = detectHarness(env);
+	if (!harness) return null;
+	if (!(blocked ?? sandboxBlocksStimHome(stimHome, home))) return null;
+	const symptoms = `Writes to ${stimHome} raise EPERM on a directory you can write, the simulator service looks dead, and the adb server looks unreachable.`;
+	const title = "This session sandboxes shell commands, and Stim is not allowed through";
+	if (harness === "codex") return {
+		level: "cost",
+		title,
+		detail: `${symptoms} Codex has one sandbox setting and no per-path allowance, so there is nothing to add.`,
+		fix: "Run Stim with the sandbox off, or start Codex with `codex -s danger-full-access`, which turns the whole sandbox off rather than allowing these three. See `stim guide errors sandbox`."
+	};
+	const paths = allowanceSearchPaths(settingsRoot, home);
+	const missing = missingAllowance(paths, stimHome, home);
+	if (missing.length === 0) return {
+		level: "cost",
+		title: "Stim is allowed through this sandbox, but the session has not picked it up",
+		detail: `${symptoms} ${paths[0]} already grants all three, so the settings were read before they were written.`,
+		fix: "Restart the session for the allowance to take effect."
+	};
+	return {
+		level: "cost",
+		title,
+		detail: `${symptoms} Missing: ${missing.join(", ")}.`,
+		fix: `Run \`stim doctor --fix\` to write sandbox.filesystem.allowWrite, sandbox.network.allowMachLookup, and sandbox.network.allowLocalBinding into ${paths[0]}, merged with what is there, or add the missing keys by hand. See \`stim guide errors sandbox\`.`
+	};
+}
+//#endregion
 //#region src/doctor-storage.ts
 function checkStorageLayout(projectRoot, { platform, device = filesystemDevice, stagingRoot = temporaryRoot } = {}) {
 	const findings = [];
@@ -459,105 +666,6 @@ function mainCheckoutProjectRoot(projectRoot) {
 		return projectRoot;
 	}
 }
-function installedNpmTreeIsValid(projectRoot) {
-	try {
-		getExecutor().runFile("npm", [
-			"ls",
-			"--all",
-			"--json",
-			"--silent"
-		], {
-			cwd: projectRoot,
-			timeoutMs: 3e4
-		});
-		return true;
-	} catch {
-		return false;
-	}
-}
-const DEPENDENCY_STATES = [
-	{
-		lock: "pnpm-lock.yaml",
-		installed: ["node_modules"],
-		command: "pnpm install"
-	},
-	{
-		lock: "yarn.lock",
-		installed: [
-			"node_modules",
-			".pnp.cjs",
-			".pnp.js"
-		],
-		command: "yarn install"
-	},
-	{
-		lock: "bun.lock",
-		installed: ["node_modules"],
-		command: "bun install"
-	},
-	{
-		lock: "bun.lockb",
-		installed: ["node_modules"],
-		command: "bun install"
-	},
-	{
-		lock: "package-lock.json",
-		installed: ["node_modules"],
-		command: "npm ci"
-	}
-];
-function dependencyState(projectRoot) {
-	const root = repoRoot(projectRoot) ?? projectRoot;
-	let dir = projectRoot;
-	while (true) {
-		const state = DEPENDENCY_STATES.find((candidate) => existsSync$1(join$1(dir, candidate.lock)));
-		if (state) return {
-			...state,
-			root: dir
-		};
-		if (dir === root) return null;
-		const parent = dirname$1(dir);
-		if (parent === dir || relative$1(root, parent).startsWith("..")) return null;
-		dir = parent;
-	}
-}
-function hasInstalledDependencies(projectRoot, markers = [
-	"node_modules",
-	".pnp.cjs",
-	".pnp.js"
-]) {
-	return markers.some((entry) => existsSync$1(join$1(projectRoot, entry)));
-}
-function locallyKnownUpstream(projectRoot) {
-	try {
-		const name = getExecutor().runFile("git", [
-			"-C",
-			projectRoot,
-			"rev-parse",
-			"--abbrev-ref",
-			"--symbolic-full-name",
-			"@{upstream}"
-		], { timeoutMs: 5e3 });
-		const counts = getExecutor().runFile("git", [
-			"-C",
-			projectRoot,
-			"rev-list",
-			"--left-right",
-			"--count",
-			"HEAD...@{upstream}"
-		], { timeoutMs: 5e3 }).trim().split(/\s+/).map(Number);
-		const ahead = counts[0] ?? NaN;
-		const behind = counts[1] ?? NaN;
-		if (!name || !Number.isInteger(ahead) || !Number.isInteger(behind)) return null;
-		return {
-			name,
-			ahead,
-			behind
-		};
-	} catch {
-		return null;
-	}
-}
 function brokenPodLinks(podsRoot) {
 	try {
 		return getExecutor().runFile("find", [
@@ -1126,4 +1234,318 @@ async function detectFingerprintParity(projectRoot, { createFingerprint = expoFi
 	}
 }
 //#endregion
-export { installedNpmTreeIsValid as a, repairCxxLauncherState as c, hasInstalledDependencies as i, detectFingerprintParity as n, locallyKnownUpstream as o, detectLinkedLibraryGitMetadata as r, runDoctor as s, dependencyState as t };
+//#region src/stim-installations.ts
+const VERSION_OUTPUT_LIMIT = 4096;
+function parsedVersion(version) {
+	const match = /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/.exec(version);
+	if (!match) return null;
+	const core = [
+		match[1],
+		match[2],
+		match[3]
+	];
+	if (core.some((part) => part.length > 1 && part.startsWith("0"))) return null;
+	const prereleaseParts = match[4]?.split(".");
+	if (prereleaseParts?.some((part) => !part || /^\d+$/.test(part) && part.length > 1 && part.startsWith("0"))) return null;
+	const prerelease = prereleaseParts?.map((part) => /^\d+$/.test(part) ? Number(part) : part);
+	return {
+		core: core.map(Number),
+		prerelease: prerelease ?? null
+	};
+}
+function compareStimVersions(left, right) {
+	const a = parsedVersion(left);
+	const b = parsedVersion(right);
+	if (!a || !b) return null;
+	for (let index = 0; index < a.core.length; index += 1) {
+		const difference = (a.core[index] ?? 0) - (b.core[index] ?? 0);
+		if (difference !== 0) return difference;
+	}
+	if (!a.prerelease && !b.prerelease) return 0;
+	if (!a.prerelease) return 1;
+	if (!b.prerelease) return -1;
+	for (let index = 0; index < Math.max(a.prerelease.length, b.prerelease.length); index += 1) {
+		const x = a.prerelease[index];
+		const y = b.prerelease[index];
+		if (x === void 0) return -1;
+		if (y === void 0) return 1;
+		if (x === y) continue;
+		if (typeof x === "number" && typeof y === "number") return x - y;
+		if (typeof x === "number") return -1;
+		if (typeof y === "number") return 1;
+		return x < y ? -1 : 1;
+	}
+	return 0;
+}
+function parseStimVersionOutput(output) {
+	const version = output?.split("\n")[0]?.trim() ?? "";
+	return parsedVersion(version) ? version.replace(/^v/, "") : null;
+}
+function executableNames(platform) {
+	return platform === "win32" ? [
+		"stim.cmd",
+		"stim.exe",
+		"stim"
+	] : ["stim"];
+}
+function stimExecutablePaths(pathValue, { platform = process.platform, cwd = process.cwd() } = {}) {
+	const found = [];
+	const seen = /* @__PURE__ */ new Set();
+	for (const entry of pathValue.split(delimiter)) {
+		const directory = resolve(cwd, entry || ".");
+		for (const name of executableNames(platform)) {
+			const path = join(directory, name);
+			try {
+				accessSync(path, platform === "win32" ? constants.F_OK : constants.X_OK);
+				if (!statSync(path).isFile()) continue;
+				const realPath = realpathSync(path);
+				if (seen.has(realPath)) continue;
+				seen.add(realPath);
+				found.push({
+					path,
+					realPath
+				});
+			} catch {}
+		}
+	}
+	return found;
+}
+function canonicalPath(path) {
+	if (!path) return null;
+	try {
+		return realpathSync(resolve(path));
+	} catch {
+		return resolve(path);
+	}
+}
+function analyzeStimVersions(runningVersion, runningPath, installations) {
+	const candidates = [runningVersion, ...installations.map((entry) => entry.version)];
+	const versions = [...new Set(candidates)].filter((version) => version !== null && compareStimVersions(version, version) !== null).toSorted((left, right) => -(compareStimVersions(left, right) ?? 0));
+	const highestVersion = versions[0] ?? null;
+	const resolved = installations[0] ?? null;
+	return {
+		runningVersion,
+		runningPath,
+		resolved,
+		installations,
+		versions,
+		highestVersion,
+		resolvedIsOlder: Boolean(resolved?.version && highestVersion && (compareStimVersions(resolved.version, highestVersion) ?? 0) < 0)
+	};
+}
+function probeStimVersion(path, timeoutMs) {
+	return new Promise((resolveProbe) => {
+		let settled = false;
+		let output = "";
+		const finish = (version) => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(timer);
+			resolveProbe(version);
+		};
+		let child;
+		try {
+			child = getExecutor().spawn(path, ["--version"], {
+				stdio: [
+					"ignore",
+					"pipe",
+					"ignore"
+				],
+				detached: process.platform !== "win32"
+			});
+		} catch {
+			resolveProbe(null);
+			return;
+		}
+		const timer = setTimeout(() => {
+			try {
+				if (process.platform !== "win32" && child.pid) process.kill(-child.pid, "SIGKILL");
+				else child.kill("SIGKILL");
+			} catch {}
+			finish(null);
+		}, timeoutMs);
+		child.stdout?.on("data", (chunk) => {
+			if (output.length < VERSION_OUTPUT_LIMIT) output += String(chunk).slice(0, VERSION_OUTPUT_LIMIT - output.length);
+		});
+		child.on("error", () => finish(null));
+		child.on("close", (code) => finish(code === 0 ? parseStimVersionOutput(output) : null));
+	});
+}
+async function inspectStimVersions(runningVersion, { pathValue = process.env.PATH ?? "", runningPath = process.argv[1], probeTimeoutMs = 5e3 } = {}) {
+	const paths = stimExecutablePaths(pathValue);
+	const versions = await Promise.all(paths.map((entry) => probeStimVersion(entry.path, probeTimeoutMs)));
+	const installations = paths.map((entry, index) => ({
+		path: entry.path,
+		realPath: entry.realPath,
+		version: versions[index] ?? null
+	}));
+	return analyzeStimVersions(runningVersion, canonicalPath(runningPath), installations);
+}
+//#endregion
+//#region src/commands/doctor.ts
+function parseDoctorPlatform(value) {
+	if (value === "ios" || value === "android") return value;
+	throw new InvalidArgumentError("expected one of: ios, android");
+}
+function doctorTarget(platform) {
+	if (platform === "ios") return "iOS";
+	if (platform === "android") return "Android";
+	return "all platforms";
+}
+function stimVersionLines(report) {
+	const resolved = report.resolved ? `${report.resolved.version ?? "unknown version"} at ${report.resolved.path}` : "not found on PATH";
+	const paths = `${report.installations.length} distinct PATH install${report.installations.length === 1 ? "" : "s"}`;
+	const pathVersions = [...new Set(report.installations.map((entry) => entry.version).filter(Boolean))];
+	const versions = pathVersions.length > 1 ? ` (${pathVersions.join(", ")})` : "";
+	return [
+		phaseLine("version", report.runningVersion),
+		phaseLine("resolved", resolved),
+		phaseLine("installs", paths + versions)
+	];
+}
+function doctorSuccessLines(platform, stim) {
+	const lines = [
+		`Doctor (${doctorTarget(platform)})`,
+		phaseLine("result", "PASS"),
+		phaseLine("findings", "0"),
+		...stimVersionLines(stim),
+		"",
+		"Project",
+		phaseLine("project", "source checkout, dependencies, local upstream"),
+		phaseLine("settings", "every Stim setting type, machine config paths, companions and inert keys")
+	];
+	if (platform !== "android") {
+		lines.push("", "iOS");
+		lines.push(phaseLine("setup", "CocoaPods, warm state, effective Debug simulator architectures"));
+		lines.push(phaseLine("caches", "Metro, Xcode compilation, ccache, build provider"));
+		lines.push(phaseLine("devices", "remote device, SimSlim profile"));
+	}
+	if (platform !== "ios") {
+		lines.push("", "Android");
+		lines.push(phaseLine("setup", "warm state"));
+		lines.push(phaseLine("caches", "Metro, Gradle, ccache, build provider"));
+		lines.push(phaseLine("devices", "remote device"));
+	}
+	lines.push("", "Shared");
+	lines.push(phaseLine("services", "EAS session"));
+	lines.push(phaseLine("storage", "temporary staging and build-cache volume placement"));
+	lines.push(phaseLine("fingerprint", "parity when dependencies are absent"));
+	lines.push("", "Handled automatically");
+	const suppliedCaches = platform === "ios" ? "Metro transform store, Xcode compilation cache" : platform === "android" ? "Metro transform store, Gradle build cache, ccache" : "Metro transform store, Xcode compilation cache, Gradle build cache, ccache";
+	lines.push(phaseLine("caches", suppliedCaches));
+	lines.push(phaseLine("meaning", "missing project cache settings are healthy"));
+	return lines;
+}
+function shadowedStimFinding(report) {
+	if (!report.resolvedIsOlder || !report.resolved?.version || !report.highestVersion) return null;
+	const newer = [...(compareStimVersions(report.runningVersion, report.resolved.version) ?? 0) > 0 ? [{
+		path: report.runningPath,
+		version: report.runningVersion
+	}] : [], ...report.installations.filter((entry) => entry.version && (compareStimVersions(entry.version, report.resolved?.version ?? "") ?? 0) > 0)].find((entry) => entry.version === report.highestVersion);
+	const newerLocation = newer?.path ? ` at ${newer.path}` : "";
+	return {
+		level: "cost",
+		title: "The Stim resolved from PATH is older than another installation",
+		detail: `${report.resolved.path} reports ${report.resolved.version}, while ${report.highestVersion} is also installed${newerLocation}. A shell command named stim uses the first executable on PATH, so newer commands and fixes can appear to be missing.`,
+		fix: `Update or remove ${report.resolved.path}, or put the ${report.highestVersion} installation earlier on PATH. Then run \`stim doctor\` again.`
+	};
+}
+/**
+* Status goes to stderr so `--json --fix` still prints one parseable payload
+* on stdout, and the report that follows shows what the write left.
+*/
+function applySandboxFix(root, env = process.env) {
+	const harness = detectHarness(env);
+	if (harness === "codex") {
+		console.error(chalk.yellow("Nothing to apply under Codex."));
+		console.error(chalk.dim("Its sandbox is one setting, `sandbox_mode`, with no per-path allowance: the only value that clears Stim is `danger-full-access`, which turns the sandbox off rather than allowing these three. Run Stim with the sandbox off instead, or set it yourself."));
+		process.exitCode = 1;
+		return;
+	}
+	if (harness !== "claude-code") {
+		console.error(chalk.dim("No sandboxing harness detected, so there is nothing to apply."));
+		return;
+	}
+	const settingsRoot = repoRoot(root) ?? root;
+	const stimHome = env.STIM_HOME || "~/.stim";
+	const target = claudeLocalSettingsPath(settingsRoot);
+	const missing = missingAllowance(allowanceSearchPaths(settingsRoot), stimHome);
+	if (missing.length === 0) {
+		console.error(chalk.green("Stim is already allowed through this sandbox. Nothing to apply."));
+		return;
+	}
+	const result = applyClaudeAllowance(target, sandboxAllowance(stimHome));
+	if (result.status === "refused") {
+		console.error(chalk.red(result.reason));
+		console.error(chalk.dim(`Nothing was written. Add ${missing.join(", ")} by hand.`));
+		process.exitCode = 1;
+		return;
+	}
+	console.error(chalk.green(`${result.status === "created" ? "Wrote" : "Updated"} ${target}`));
+	console.error(chalk.dim("Added writes to Stim's state directory, the simulator XPC service, and local port binding. Claude Code reads project settings from the directory a session starts in, so this file only counts for sessions rooted there. Restart the session for it to take effect."));
+}
+function doctorCommand(program, version, inspectVersions = inspectStimVersions) {
+	program.command("doctor").description("Inspect the source checkout and report project state that can make native worktrees slow or invalid. Read-only unless --fix is passed; --platform filters native findings.").option("--json", "print the findings as JSON").option("--platform <platform>", "report shared findings plus only this native platform: ios or android", parseDoctorPlatform).option("--fix", "repair the sandbox allowance when the report names it, and stale Android .cxx configurations in this checkout. Stop native builds first. Generated CMake output must be ignored and untracked; custom launcher settings and source files are preserved.").action(async (opts) => {
+		const root = findProjectRoot(process.cwd());
+		if (!root) {
+			console.error(chalk.red("Not in a React Native project (no package.json found)."));
+			process.exitCode = 1;
+			return;
+		}
+		if (opts.fix) {
+			if (sandboxFinding(repoRoot(root) ?? root)) applySandboxFix(root);
+			if (opts.platform !== "ios") try {
+				const repair = repairCxxLauncherState(root);
+				for (const path of repair.removed) console.error(phaseLine("cache", `removed ${path}; next build reconfigures`));
+				for (const { path, reason } of repair.refused) console.error(phaseLine("cache", `kept ${path}: ${reason}`));
+				if (repair.refused.length > 0) process.exitCode = 1;
+			} catch (error) {
+				console.error(phaseLine("cache", `CMake cleanup failed: ${error.message}`));
+				process.exitCode = 1;
+			}
+		}
+		const stim = await inspectVersions(version);
+		const findings = runDoctor(root, {
+			xcodeMajor: opts.platform === "android" ? null : detectXcodeMajor(),
+			platform: opts.platform
+		});
+		const parity = await detectFingerprintParity(root, { platform: opts.platform });
+		if (parity) findings.push(parity);
+		const linkedGit = await detectLinkedLibraryGitMetadata(root, { platform: opts.platform });
+		if (linkedGit) findings.push(linkedGit);
+		if (detectHarness()) {
+			const sandbox = sandboxFinding(repoRoot(root) ?? root);
+			if (sandbox) findings.push(sandbox);
+		}
+		const shadowed = shadowedStimFinding(stim);
+		if (shadowed) findings.push(shadowed);
+		if (opts.json) {
+			console.log(JSON.stringify({
+				project: root,
+				platform: opts.platform ?? null,
+				stim,
+				findings
+			}));
+			return;
+		}
+		if (findings.length === 0) {
+			const lines = doctorSuccessLines(opts.platform, stim);
+			for (const [index, line] of lines.entries()) if (index === 1) console.log(chalk.green(line));
+			else if (line && !line.startsWith("  ")) console.log(chalk.bold(line));
+			else console.log(chalk.dim(line));
+			return;
+		}
+		const ordered = findings.toSorted((a, b) => a.level === b.level ? 0 : a.level === "cost" ? -1 : 1);
+		console.log(chalk.bold(`Doctor (${doctorTarget(opts.platform)})`));
+		for (const line of stimVersionLines(stim)) console.log(chalk.dim(line));
+		for (const f of ordered) {
+			const tag = f.level === "cost" ? chalk.yellow("costs time") : chalk.dim("note");
+			console.log(`\n${tag}  ${chalk.bold(f.title)}`);
+			console.log(`  ${f.detail}`);
+			if (f.fix) console.log(chalk.dim(`  -> ${f.fix}`));
+		}
+		console.log(chalk.dim(`\n${findings.length} finding(s). Fix relevant "costs time" findings before copying the source checkout into a native worktree.`));
+	});
+}
+//#endregion
+export { applySandboxFix, doctorCommand as default, doctorSuccessLines, parseDoctorPlatform, shadowedStimFinding };