stim 1.9.0 → 1.10.0

package/dist/budget-BP4jZZL4.mjs

@@ -0,0 +1,620 @@
+import { D as process_identity_exports, F as volumeRootFor, H as projectDeviceSlots, P as measuredDirectorySize, a as clearSupervisor, f as getProject, g as loadConfig$1, j as formatBytes, u as getConfigDir } from "./config-BEq0Qw_a.mjs";
+import { O as workspaceDir, S as sharedBuildCache, m as readWorkspaceState$1, s as resolveProjectMetro, t as killMetroTree } from "./metro-BWLOJ_Wr.mjs";
+import { n as supervisorError } from "./errors-B6W7FkxQ.mjs";
+import { o as clearWorkspaceSupervisor } from "./state-WGdIbi_d.mjs";
+import { n as workspaceProcessLockError, t as withWorkspaceProcessLock } from "./workspace-process-lock-BXA96myD.mjs";
+import { l as phaseLine } from "./command-output-D5z2_bcF.mjs";
+import { u as workspaceActivity } from "./build-progress-BXx-ZBe4.mjs";
+import { N as ownedAvdSerialResolver } from "./android-787HhP5w.mjs";
+import { t as resolveSupervisorTarget } from "./ownership-DZjdx8Gq.mjs";
+import { l as listAllIosSims } from "./ios-B2Fpqvlb.mjs";
+import { i as idleShutdownCandidates, n as collectOwnedDeviceActivity, o as shutDownIdleDevices, s as workspaceBuildInProgress, t as collectIdleDevices } from "./idle-DpRLp5lj.mjs";
+import { i as canonicalPath, n as withIdleWorkspace } from "./in-use-CjUluqIX.mjs";
+import { n as capacity, o as environmentState, s as formatSpace } from "./status-Dr4fRkym.mjs";
+import { A as discoverCaches, D as planCacheEmptying, a as collectWorkspaceOutputs, k as trimCaches, r as clearWorkspaceOutputs, y as deviceSweepIsScoped } from "./workspaces-BTUyFfkv.mjs";
+import { existsSync, statSync, statfsSync } from "node:fs";
+import { settingDefinition, settingValueError } from "@stim-cli/core/state";
+import { dirname, join, sep } from "node:path";
+import { homedir, platform, totalmem } from "node:os";
+import chalk from "chalk";
+//#region src/supervisor/cache-reset.ts
+async function stopOwnedMetro(root) {
+	const project = getProject(root);
+	const port = project?.metroPort;
+	const target = resolveSupervisorTarget({
+		state: readWorkspaceState$1(root)?.supervisor,
+		record: project?.supervisor,
+		reservedPort: port
+	});
+	if (target.status === "unverified") return {
+		status: "unverified",
+		reason: target.reason ?? "unknown identity"
+	};
+	if (port && target.status !== "ours" && !(await resolveProjectMetro(port, root)).missing) return {
+		status: "external",
+		reason: `a dev server Stim did not start answers on port ${port}`
+	};
+	if (target.status !== "ours") return { status: "not-running" };
+	const expected = {
+		pid: target.pid,
+		processToken: target.processToken
+	};
+	if (!killMetroTree(target.pid, target.processToken) || !await (0, process_identity_exports.waitForProcessExit)(expected, 1e4)) return {
+		status: "stuck",
+		reason: `supervisor pid ${target.pid} did not exit`
+	};
+	if (port && !(await resolveProjectMetro(port, root)).missing) return {
+		status: "port-occupied",
+		reason: `port ${port} is still occupied after stopping Metro`
+	};
+	clearWorkspaceSupervisor(root, expected);
+	clearSupervisor(root, expected);
+	return { status: "stopped" };
+}
+async function stopOwnedMetroForReset(root) {
+	const stopped = await stopOwnedMetro(root);
+	switch (stopped.status) {
+		case "unverified": throw supervisorError("STIM_SUPERVISOR_EXITED", `Cannot reset Metro: ${stopped.reason}.`, "Stop it with the tool that started it, then retry. Stim leaves unverified processes alone.");
+		case "external": 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`.");
+		case "stuck": 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.");
+		case "port-occupied": throw supervisorError("STIM_SUPERVISOR_EXITED", `Port ${getProject(root)?.metroPort} is still occupied after stopping Metro.`, "Inspect the listener before retrying. Stim does not terminate unrecorded processes.");
+	}
+}
+//#endregion
+//#region src/budget.ts
+const MB = 1048576;
+const GB_IN_MB = 1024;
+const COMMITTED_MEMORY_SHARE = .6;
+const STALE_CACHE_DAYS = 14;
+const DEVICE_LIST_TIMEOUT_MS = 1e4;
+const USAGE_TIMEOUT_MS = 1e4;
+const BUDGET_SETTING_REMEDY = "Fix the value with `stim settings set <key> <value>`, or unset the environment variable. Run `stim guide settings` for the budget keys.";
+function valueAt(source, key) {
+	let node = source;
+	for (const part of key.split(".")) {
+		if (node === null || typeof node !== "object" || Array.isArray(node)) return void 0;
+		node = node[part];
+	}
+	return node;
+}
+function machineNumber(key, config, env) {
+	const setting = settingDefinition(key);
+	const fromEnv = setting.env ? env[setting.env] : void 0;
+	if (fromEnv !== void 0 && fromEnv !== "") {
+		const value = fromEnv.trim() === "" ? NaN : Number(fromEnv);
+		const problem = settingValueError(setting, value);
+		return problem ? {
+			value: void 0,
+			error: `Invalid ${setting.env} value ${JSON.stringify(fromEnv)}. Expected ${problem}.`
+		} : {
+			value,
+			error: null
+		};
+	}
+	if (env.STIM_HOME && setting.scopedHomeValue !== void 0) return {
+		value: setting.scopedHomeValue,
+		error: null
+	};
+	const raw = valueAt(config, key);
+	if (raw === void 0) return {
+		value: typeof setting.default === "number" ? setting.default : void 0,
+		error: null
+	};
+	const problem = settingValueError(setting, raw);
+	return problem ? {
+		value: void 0,
+		error: `Invalid ${key} value ${JSON.stringify(raw)}. Expected ${problem}.`
+	} : {
+		value: raw,
+		error: null
+	};
+}
+function resolveBudget({ config = loadConfig$1(), env = process.env, totalMemoryMb = totalmem() / MB } = {}) {
+	const minFree = machineNumber("budget.minFreeDiskGb", config, env);
+	const hardFloor = machineNumber("budget.hardFloorDiskGb", config, env);
+	const memory = machineNumber("budget.maxCommittedMemoryGb", config, env);
+	const live = machineNumber("budget.maxLiveWorkspaces", config, env);
+	return {
+		budget: {
+			minFreeDiskMb: (minFree.value ?? 0) * GB_IN_MB,
+			hardFloorDiskMb: (hardFloor.value ?? 0) * GB_IN_MB,
+			maxCommittedMemoryMb: memory.value === void 0 ? Math.round(totalMemoryMb * COMMITTED_MEMORY_SHARE) : memory.value * GB_IN_MB,
+			maxLiveWorkspaces: live.value ?? 0
+		},
+		error: minFree.error ?? hardFloor.error ?? memory.error ?? live.error
+	};
+}
+function existingAncestor(path) {
+	let current = path;
+	while (!existsSync(current) && dirname(current) !== current) current = dirname(current);
+	return current;
+}
+function readVolumeSpace(paths) {
+	const seen = /* @__PURE__ */ new Set();
+	const volumes = [];
+	for (const path of paths) try {
+		const existing = existingAncestor(path);
+		const device = statSync(existing).dev;
+		if (seen.has(device)) continue;
+		seen.add(device);
+		const fs = statfsSync(existing);
+		volumes.push({
+			volume: volumeRootFor(path),
+			freeMb: fs.bavail * fs.bsize / MB
+		});
+	} catch {}
+	return volumes;
+}
+function estimateMemoryUse({ config, sims, androidSerial, supervisorRunning }) {
+	const simsByUdid = Object.fromEntries((sims ?? []).map((sim) => [sim.udid, sim]));
+	const runtime = (avdName) => {
+		if (!avdName) return null;
+		const serial = androidSerial(avdName);
+		return {
+			serial,
+			state: serial ? "detected" : "not-detected"
+		};
+	};
+	const states = Object.entries(config?.projects ?? {}).map(([path, project]) => {
+		const pid = supervisorRunning(path, project);
+		const slots = projectDeviceSlots(project);
+		return environmentState({
+			...project,
+			__path: path
+		}, {
+			simsByUdid,
+			simsAvailable: sims !== null,
+			metro: pid === null ? { missing: true } : { metro: { pid } },
+			androidRuntime: project.platforms?.android?.owned ? runtime(project.platforms.android.avdName) : null,
+			androidRuntimes: Object.fromEntries(slots.slice(1).map(({ slot, platforms }) => [slot, platforms.android?.owned ? runtime(platforms.android.avdName) : null]))
+		});
+	});
+	const { committedMb, liveCount } = capacity(states, 0);
+	return {
+		committedMb,
+		liveWorkspaces: liveCount
+	};
+}
+function listSims() {
+	try {
+		return listAllIosSims({ timeoutMs: DEVICE_LIST_TIMEOUT_MS });
+	} catch {
+		return null;
+	}
+}
+function runningSupervisorPid(path, project) {
+	const target = resolveSupervisorTarget({
+		state: readWorkspaceState$1(path)?.supervisor,
+		record: project.supervisor,
+		reservedPort: project.metroPort
+	});
+	return target.status === "ours" ? target.pid ?? null : null;
+}
+function readMemoryUse() {
+	const resolve = ownedAvdSerialResolver({ timeoutMs: 5e3 });
+	return estimateMemoryUse({
+		config: loadConfig$1(),
+		sims: listSims(),
+		androidSerial: (avdName) => {
+			try {
+				return resolve(avdName).serial ?? null;
+			} catch {
+				return null;
+			}
+		},
+		supervisorRunning: runningSupervisorPid
+	});
+}
+function budgetShortfalls(budget, measure) {
+	const floor = Math.max(budget.minFreeDiskMb, budget.hardFloorDiskMb);
+	return {
+		disk: floor > 0 ? measure.volumes.filter((v) => v.freeMb < floor) : [],
+		hardFloor: budget.hardFloorDiskMb > 0 ? measure.volumes.filter((v) => v.freeMb < budget.hardFloorDiskMb) : [],
+		memory: Boolean(budget.maxCommittedMemoryMb > 0 && measure.memory && measure.memory.committedMb > budget.maxCommittedMemoryMb),
+		workspaces: Boolean(budget.maxLiveWorkspaces > 0 && measure.memory && measure.memory.liveWorkspaces > budget.maxLiveWorkspaces)
+	};
+}
+const DISK_ONLY = ["workspace-outputs", "stale-cache-entries"];
+function reclaimPlan(short) {
+	const disk = short.disk.length > 0;
+	return [...disk || short.memory || short.workspaces ? ["idle-devices", "idle-dev-servers"] : [], ...disk ? DISK_ONLY : []];
+}
+function overBudget(short) {
+	return short.disk.length > 0 || short.memory || short.workspaces;
+}
+function isOtherWorkspace(root) {
+	const self = canonicalPath(root);
+	return (path) => canonicalPath(path) !== self;
+}
+function deviceLabel(device) {
+	return `${device.kind} ${device.name} in ${device.project}`;
+}
+function reclaimIdleDevices({ root, dryRun, note, now }) {
+	if (deviceSweepIsScoped()) {
+		note(chalk.dim(phaseLine("budget", "idle devices left alone: STIM_HOME scopes this config, devices are global")));
+		return {
+			targets: [],
+			failures: 0
+		};
+	}
+	const other = isOtherWorkspace(root);
+	const collect = (at) => idleShutdownCandidates(collectIdleDevices(loadConfig$1(), listSims() ?? [], [], at).filter((device) => other(device.project)), 0);
+	const idle = collect(now);
+	if (dryRun || idle.length === 0) return {
+		targets: idle.map(deviceLabel),
+		failures: 0
+	};
+	const { failures, shutDown } = shutDownIdleDevices(idle, 0, () => collect(Date.now()));
+	return {
+		targets: shutDown.map(deviceLabel),
+		failures
+	};
+}
+function idleSince(path, now) {
+	const activity = workspaceActivity(path, now);
+	const at = Date.parse(activity.lastActivityAt ?? "");
+	return activity.state === "idle" && Number.isFinite(at) ? at : null;
+}
+async function reclaimIdleDevServers({ root, dryRun, note, now }) {
+	const config = loadConfig$1();
+	const other = isOtherWorkspace(root);
+	const serving = Object.entries(config?.projects ?? {}).flatMap(([path, project]) => {
+		const pid = other(path) ? runningSupervisorPid(path, project) : null;
+		return pid !== null && !workspaceBuildInProgress(path) && idleSince(path, now) !== null ? [{
+			path,
+			pid
+		}] : [];
+	});
+	if (serving.length === 0) return {
+		targets: [],
+		failures: 0
+	};
+	const sims = listSims();
+	if (sims === null) {
+		note(chalk.dim(phaseLine("budget", "dev servers left alone: simulators could not be listed to prove them idle")));
+		return {
+			targets: [],
+			failures: 0
+		};
+	}
+	const busy = new Set(collectOwnedDeviceActivity(config, sims, now).filter((device) => device.activity.state !== "idle").map((device) => device.project));
+	const idle = serving.filter(({ path }) => !busy.has(path));
+	if (dryRun) return {
+		targets: idle.map(({ path }) => path),
+		failures: 0
+	};
+	const targets = [];
+	let failures = 0;
+	const stillIdle = (path, pid) => {
+		const project = loadConfig$1()?.projects?.[path];
+		return Boolean(project && runningSupervisorPid(path, project) === pid && !workspaceBuildInProgress(path) && idleSince(path, Date.now()) !== null);
+	};
+	for (const { path, pid } of idle) {
+		let run;
+		try {
+			run = await withIdleWorkspace(path, async () => {
+				try {
+					return await withWorkspaceProcessLock(workspaceDir(path), "metro-start", async () => stillIdle(path, pid) ? stopOwnedMetro(path) : "busy", {
+						external: true,
+						waitMs: 0,
+						ownerPurpose: "budget reclaim"
+					});
+				} catch (error) {
+					if (workspaceProcessLockError(error)) return "starting";
+					throw error;
+				}
+			}, {
+				purpose: "budget reclaim",
+				supervisor: false
+			});
+		} catch (error) {
+			failures++;
+			note(chalk.red(`Could not stop the dev server of ${path}: ${error?.message || error}`));
+			continue;
+		}
+		if (!run.ran) {
+			note(chalk.yellow(`Kept the dev server of ${path}: ${run.reasons.join("; ")}`));
+			continue;
+		}
+		const stopped = run.value;
+		if (stopped === "busy" || stopped === "starting") {
+			const why = stopped === "busy" ? "it is no longer idle" : "a stim start holds its metro-start lock";
+			note(chalk.dim(`Kept the dev server of ${path}: ${why}`));
+		} else if (stopped.status === "stopped") {
+			targets.push(path);
+			note(chalk.green(`Stopped the idle dev server of ${path}`));
+		} else if ("reason" in stopped) {
+			if (stopped.status === "stuck") failures++;
+			note(chalk.yellow(`Kept the dev server of ${path}: ${stopped.reason}`));
+		}
+	}
+	return {
+		targets,
+		failures
+	};
+}
+async function reclaimWorkspaceOutputs({ root, dryRun, now, diskRecovered }) {
+	const other = isOtherWorkspace(root);
+	const report = collectWorkspaceOutputs({
+		olderThan: null,
+		now,
+		measure: false
+	});
+	const clearable = report.workspaces.flatMap((entry) => {
+		const project = entry.projectRoot;
+		const since = project !== null && entry.willClear && other(project) ? idleSince(project, now) : null;
+		return since === null ? [] : [{
+			entry,
+			since
+		}];
+	}).toSorted((a, b) => a.since - b.since).map(({ entry }) => entry);
+	if (dryRun) return {
+		targets: clearable.map((entry) => entry.projectRoot),
+		failures: 0
+	};
+	const targets = [];
+	let failures = 0;
+	for (const entry of clearable) {
+		const result = await clearWorkspaceOutputs({
+			...report,
+			workspaces: [entry]
+		}, {
+			olderThan: null,
+			now
+		});
+		failures += result.failures;
+		targets.push(...result.cleared);
+		if (diskRecovered()) break;
+	}
+	return {
+		targets,
+		failures
+	};
+}
+function cacheLabel(cache) {
+	return `${cache.name} ${cache.dir}`;
+}
+function reclaimStaleCacheEntries({ dryRun }) {
+	const caches = planCacheEmptying(discoverCaches(), false).filter((cache) => cache.prune !== "report-only" && cache.prune !== "atomic" && !cache.machineGlobal);
+	if (dryRun) return {
+		targets: caches.map(cacheLabel),
+		failures: 0
+	};
+	return {
+		targets: trimCaches(caches, STALE_CACHE_DAYS).map(cacheLabel),
+		failures: 0
+	};
+}
+const STEPS = {
+	"idle-devices": reclaimIdleDevices,
+	"idle-dev-servers": reclaimIdleDevServers,
+	"workspace-outputs": reclaimWorkspaceOutputs,
+	"stale-cache-entries": reclaimStaleCacheEntries
+};
+const STEP_ACTIONS = {
+	"idle-devices": "shut down idle owned devices",
+	"idle-dev-servers": "stop idle dev servers",
+	"workspace-outputs": "clear build outputs of idle workspaces",
+	"stale-cache-entries": `trim cache entries unused for ${STALE_CACHE_DAYS} days`
+};
+async function runStep(step, context) {
+	const log = console.log;
+	const exitCode = process.exitCode;
+	console.log = console.error;
+	try {
+		const result = await STEPS[step](context);
+		return process.exitCode === exitCode ? result : {
+			...result,
+			failures: result.failures + 1
+		};
+	} catch (error) {
+		context.note(chalk.red(phaseLine("budget", `${STEP_ACTIONS[step]} failed: ${error?.message || error}`)));
+		return {
+			targets: [],
+			failures: 1
+		};
+	} finally {
+		console.log = log;
+		process.exitCode = exitCode;
+	}
+}
+function spaceUsers() {
+	const home = homedir();
+	const candidates = [
+		["Stim state", getConfigDir()],
+		["shared build cache", sharedBuildCache()],
+		...platform() === "darwin" ? [["simulators", join(home, "Library", "Developer", "CoreSimulator", "Devices")], ["Xcode DerivedData", join(home, "Library", "Developer", "Xcode", "DerivedData")]] : [],
+		["Android emulators", join(home, ".android", "avd")]
+	];
+	const measured = /* @__PURE__ */ new Set();
+	const users = [];
+	for (const [label, path] of candidates) {
+		const canonical = canonicalPath(path);
+		if (measured.has(canonical) || [...measured].some((dir) => canonical.startsWith(`${dir}${sep}`))) continue;
+		measured.add(canonical);
+		if (!existsSync(path)) continue;
+		const bytes = measuredDirectorySize(path, { timeoutMs: USAGE_TIMEOUT_MS });
+		if (bytes) users.push({
+			label: `${label} ${path}`,
+			bytes
+		});
+	}
+	return users.toSorted((a, b) => b.bytes - a.bytes).map(({ label, bytes }) => `${label}: ${formatBytes(bytes)}`);
+}
+const DEFAULT_DEPS = {
+	volumes: readVolumeSpace,
+	memory: readMemoryUse,
+	step: runStep,
+	usage: spaceUsers,
+	now: Date.now
+};
+const LOW_DISK_REMEDY = "Run `stim gc` to see what else Stim can reclaim, then `stim gc --delete` (add `--cache all` to empty the shared caches, or `--worktrees` to remove finished worktrees). Free space outside Stim from the largest uses listed, or lower budget.hardFloorDiskGb.";
+function describeShortfall(budget, measure, short) {
+	const floor = Math.max(budget.minFreeDiskMb, budget.hardFloorDiskMb);
+	return [
+		...short.disk.map((v) => `${formatSpace(v.freeMb)} free on ${v.volume}, below the ${formatSpace(floor)} floor`),
+		...short.memory && measure.memory ? [`roughly ${formatSpace(measure.memory.committedMb)} of memory committed, over the ${formatSpace(budget.maxCommittedMemoryMb)} budget`] : [],
+		...short.workspaces && measure.memory ? [`${measure.memory.liveWorkspaces} live workspaces, over the limit of ${budget.maxLiveWorkspaces}`] : []
+	];
+}
+async function enforceBudget({ root, note, dryRun = false, budget: resolved }, overrides = {}) {
+	const deps = {
+		...DEFAULT_DEPS,
+		...overrides
+	};
+	let budget = resolved;
+	if (!budget) {
+		const read = resolveBudget();
+		if (read.error) return {
+			status: "invalid",
+			refusal: {
+				code: "STIM_BAD_ARG",
+				message: read.error,
+				remedy: BUDGET_SETTING_REMEDY
+			}
+		};
+		budget = read.budget;
+	}
+	const paths = [root, getConfigDir()];
+	const measureNow = () => ({
+		volumes: budget.minFreeDiskMb > 0 || budget.hardFloorDiskMb > 0 ? deps.volumes(paths) : [],
+		memory: budget.maxCommittedMemoryMb > 0 || budget.maxLiveWorkspaces > 0 ? deps.memory() : null
+	});
+	let measure = measureNow();
+	let short = budgetShortfalls(budget, measure);
+	const reclaimed = [];
+	const plan = reclaimPlan(short);
+	if (plan.length) note(chalk.yellow(phaseLine("budget", `${describeShortfall(budget, measure, short).join("; ")}; ${dryRun ? "would reclaim" : "reclaiming"}`)));
+	for (const step of plan) {
+		if (!dryRun && (!overBudget(short) || DISK_ONLY.includes(step) && short.disk.length === 0)) break;
+		const freeBefore = measure.volumes.reduce((sum, v) => sum + v.freeMb, 0);
+		const result = await deps.step(step, {
+			root,
+			dryRun,
+			note,
+			now: deps.now(),
+			diskRecovered: () => budgetShortfalls(budget, {
+				volumes: deps.volumes(paths),
+				memory: null
+			}).disk.length === 0
+		});
+		if (!dryRun) {
+			measure = measureNow();
+			short = budgetShortfalls(budget, measure);
+		}
+		if (result.targets.length === 0 && result.failures === 0) continue;
+		const freedMb = Math.max(0, Math.round(measure.volumes.reduce((sum, v) => sum + v.freeMb, 0) - freeBefore));
+		reclaimed.push({
+			step,
+			...result,
+			...dryRun ? {} : { freedMb }
+		});
+		const outcome = dryRun ? result.targets.join(", ") : `${result.targets.length}${result.failures ? `, ${result.failures} failed` : ""} (${formatSpace(freedMb)} freed)`;
+		note(chalk.dim(phaseLine("budget", `${STEP_ACTIONS[step]}: ${outcome}`)));
+	}
+	if (!dryRun && short.hardFloor.length) {
+		const tight = short.hardFloor.map((v) => `${formatSpace(v.freeMb)} on ${v.volume}`).join(" and ");
+		const users = deps.usage();
+		return {
+			status: "refused",
+			reclaimed,
+			refusal: {
+				code: "STIM_LOW_DISK",
+				message: `Only ${tight} is free, below the ${formatSpace(budget.hardFloorDiskMb)} hard floor (budget.hardFloorDiskGb)${reclaimed.length ? " after reclaiming what Stim safely could" : ""}, so this run could fill the disk.` + (users.length ? ` Largest uses: ${users.join("; ")}.` : ""),
+				remedy: LOW_DISK_REMEDY
+			}
+		};
+	}
+	if (!dryRun && overBudget(short)) note(chalk.yellow(phaseLine("budget", `still over budget: ${describeShortfall(budget, measure, short).join("; ")}`)));
+	return {
+		status: "ok",
+		reclaimed,
+		budget,
+		measure,
+		short
+	};
+}
+async function budgetGate(args, overrides = {}) {
+	const outcome = await enforceBudget(args, overrides);
+	return {
+		reclaimed: "reclaimed" in outcome ? outcome.reclaimed : [],
+		refusal: outcome.status === "ok" ? null : outcome.refusal
+	};
+}
+const gb = (mb) => Math.round(mb / GB_IN_MB * 10) / 10;
+function budgetFindings(budget, measure, short, plan) {
+	const findings = [];
+	const steps = plan.length ? plan.map((entry) => `${STEP_ACTIONS[entry.step]} (${entry.targets.join(", ")})`).join("; then ") : "nothing Stim can reclaim on its own right now";
+	if (short.disk.length) {
+		const refuses = short.hardFloor.length ? ` Below ${formatSpace(budget.hardFloorDiskMb)} it refuses with STIM_LOW_DISK when reclaiming does not free enough.` : "";
+		findings.push({
+			level: "cost",
+			title: "Free disk is below the Stim budget",
+			detail: `${describeShortfall(budget, measure, {
+				...short,
+				memory: false,
+				workspaces: false
+			}).join("; ")}. The next ios, android or start will first ${steps}.${refuses}`,
+			fix: "Run `stim gc` to see what Stim can reclaim, then `stim gc --delete`. Free space outside Stim, or lower budget.minFreeDiskGb."
+		});
+	}
+	if (short.memory || short.workspaces) findings.push({
+		level: "note",
+		title: "Live environments are over the memory budget",
+		detail: `${describeShortfall(budget, measure, {
+			...short,
+			disk: []
+		}).join("; ")}. The next ios, android or start shuts down idle owned devices and stops idle dev servers in other workspaces first.`,
+		fix: "Run `stim status` to see what is live, and `stim stop` in workspaces you own that you no longer need."
+	});
+	return findings;
+}
+async function inspectBudget(root, deps = {}) {
+	const read = resolveBudget();
+	if (read.error) return {
+		report: null,
+		findings: [{
+			level: "cost",
+			title: "A budget setting is invalid",
+			detail: read.error,
+			fix: BUDGET_SETTING_REMEDY
+		}]
+	};
+	const outcome = await enforceBudget({
+		root,
+		note: () => {},
+		dryRun: true,
+		budget: read.budget
+	}, deps);
+	if (outcome.status !== "ok") return {
+		report: null,
+		findings: []
+	};
+	const { budget, measure, short, reclaimed } = outcome;
+	return {
+		report: {
+			budget: {
+				minFreeDiskGb: gb(budget.minFreeDiskMb),
+				hardFloorDiskGb: gb(budget.hardFloorDiskMb),
+				maxCommittedMemoryGb: gb(budget.maxCommittedMemoryMb),
+				maxLiveWorkspaces: budget.maxLiveWorkspaces
+			},
+			volumes: measure.volumes.map((v) => ({
+				volume: v.volume,
+				freeGb: gb(v.freeMb)
+			})),
+			memory: measure.memory ? {
+				committedGb: gb(measure.memory.committedMb),
+				liveWorkspaces: measure.memory.liveWorkspaces
+			} : null,
+			plan: reclaimed
+		},
+		findings: budgetFindings(budget, measure, short, reclaimed)
+	};
+}
+function budgetLine(report) {
+	const { budget } = report;
+	return `${report.volumes.length ? `${report.volumes.map((v) => `${v.freeGb} GB free on ${v.volume}`).join(", ")} (reclaims below ${Math.max(budget.minFreeDiskGb, budget.hardFloorDiskGb)} GB, ${budget.hardFloorDiskGb ? `refuses below ${budget.hardFloorDiskGb} GB` : "never refuses"})` : "disk budget off"}; ${report.memory ? `roughly ${report.memory.committedGb} GB of a ${budget.maxCommittedMemoryGb} GB memory budget committed` : "memory budget off"}`;
+}
+//#endregion
+export { stopOwnedMetroForReset as i, budgetLine as n, inspectBudget as r, budgetGate as t };