@stim-cli/core 1.13.0 → 1.15.0

package/dist/oversight.mjs

@@ -0,0 +1,666 @@
+//#region oversight.ts
+/** What a notification is about; each can be switched off on its own. */
+const OVERSIGHT_CATEGORIES = [
+	"started",
+	"stuck",
+	"looping",
+	"finished",
+	"machine",
+	"control",
+	"attention"
+];
+const DEFAULT_STUCK_MINUTES = 15;
+/**
+* What counts as someone working on a device: agent actions, reloads and Stim runs. App log records do not, because an
+* idle app keeps logging; a new log error counts through the error count instead. The owned Chrome page records only
+* an agent's input as agent actions, not its navigations or scripts, so its page log counts while an agent drives it.
+*/
+const WORK_EVIDENCE = [
+	"agent-action",
+	"metro-bundle",
+	"workspace-use"
+];
+const DISK_CRITICAL_BYTES = 5e9;
+/** Free space a low-disk episode needs back before it ends, so space hovering at the floor notifies once. */
+const DISK_RECOVERED_BYTES = 6e9;
+const MEMORY_SETTLE_MS = 6e4;
+const OFFLINE_SETTLE_MS = 6e4;
+/** How long an agent must be gone, with nothing happening, before its green work counts as finished. */
+const FINISH_SETTLE_MS = 3e5;
+const LOOP_COUNT = 3;
+/** A workspace absent this long is forgotten; a shorter gap is a status that briefly left it out. */
+const FORGET_MS = 12e4;
+const platformName = (platform) => platform === "ios" ? "iOS" : platform === "android" ? "Android" : platform;
+const basename = (path) => path.split("/").findLast(Boolean) ?? path;
+const time = (text) => text ? Date.parse(text) : NaN;
+function worktreeRoot(path) {
+	const parts = path.split("/");
+	for (let i = parts.length - 2; i > 0; i--) {
+		if (parts[i] === ".worktrees") return parts.slice(0, i).join("/");
+		if (parts[i] === "worktrees" && parts[i - 1] === ".claude") return parts.slice(0, i - 1).join("/");
+	}
+	return null;
+}
+function markedCheckout(path) {
+	const parts = path.split("/");
+	for (let i = parts.length - 2; i > 0; i--) if (parts[i] === ".worktrees" || parts[i] === "worktrees" && parts[i - 1] === ".claude") return parts.slice(0, i + 2).join("/");
+	return null;
+}
+/** The name home shows for a workspace: its branch, else its checkout's folder. */
+function oversightTitle(env, status) {
+	if (env.worktree?.branch) return env.worktree.branch;
+	const checkout = env.worktree?.path ?? markedCheckout(env.path);
+	if (checkout) return basename(checkout);
+	const roots = /* @__PURE__ */ new Set();
+	for (const { path, worktree } of status.environments) roots.add(worktreeRoot(path) ?? worktree?.repository ?? path);
+	for (const { path, repository } of status.unprovisionedWorktrees ?? []) {
+		const root = worktreeRoot(path) ?? repository;
+		if (root) roots.add(root);
+	}
+	const root = worktreeRoot(env.path) ?? env.worktree?.repository ?? [...roots].filter((r) => env.path === r || env.path.startsWith(`${r}/`)).reduce((best, r) => best === null || r.length < best.length ? r : best, null) ?? env.path;
+	return basename(root);
+}
+function devicesOf(env) {
+	const out = [];
+	const add = (slot, ios, android) => {
+		if (ios) {
+			const model = /\(([^()]*(?:\([^()]*\)[^()]*)*)\)\s*$/.exec(ios.name ?? "")?.[1];
+			out.push({
+				platform: "ios",
+				slot,
+				model: model ?? "iOS Simulator",
+				...model === void 0 ? { modelLabel: "ios-simulator" } : {},
+				running: ios.state === "Booted",
+				activity: ios.activity
+			});
+		}
+		if (android) out.push({
+			platform: "android",
+			slot,
+			model: android.physical ? "Android device" : "Android Emulator",
+			modelLabel: android.physical ? "android-device" : "android-emulator",
+			running: android.state === "detected",
+			activity: android.activity
+		});
+	};
+	add("default", env.ios, env.android);
+	for (const slot of env.slots ?? []) add(slot.slot, slot.ios, slot.android);
+	if (env.web) out.push({
+		platform: "web",
+		slot: "default",
+		model: "Chrome",
+		modelLabel: "chrome",
+		running: env.web.running,
+		activity: env.web.activity
+	});
+	return out;
+}
+function agentDriven(device, ownLeases) {
+	const activity = device.activity;
+	if (activity?.state !== "driven") return false;
+	const since = activity.driver?.since;
+	return !(activity.driver?.tool === "stim device lock" && since && ownLeases.includes(since));
+}
+function newestBuild(env) {
+	return [env.lastBuilds?.ios, env.lastBuilds?.android].filter((b) => b !== void 0).reduce((a, b) => a === null || time(b.startedAt) > time(a.startedAt) ? b : a, null);
+}
+function lastActivityAt(env, devices, seen) {
+	const times = seen.map((at) => at ?? NaN);
+	for (const device of devices) {
+		const recent = device.activity?.recent;
+		if (!recent) times.push(time(device.activity?.lastActivityAt));
+		else {
+			times.push(...WORK_EVIDENCE.map((basis) => time(recent[basis])));
+			if (device.platform === "web" && device.activity?.state === "driven") times.push(time(recent["page-log"]));
+		}
+		times.push(time(device.activity?.driver?.since));
+	}
+	for (const build of [env.lastBuilds?.ios, env.lastBuilds?.android]) times.push(time(build?.startedAt), time(build?.finishedAt));
+	times.push(time(env.build?.startedAt));
+	const finite = times.filter(Number.isFinite);
+	return finite.length ? Math.max(...finite) : null;
+}
+const LANGUAGES = {
+	swift: "Swift",
+	m: "Objective-C",
+	mm: "Objective-C++",
+	kt: "Kotlin",
+	java: "Java",
+	c: "C",
+	cc: "C++",
+	cpp: "C++",
+	h: "C",
+	hpp: "C++",
+	js: "JavaScript",
+	ts: "TypeScript",
+	tsx: "TypeScript",
+	gradle: "Gradle",
+	kts: "Gradle"
+};
+const failed = (build) => (build.result ?? build.status) === "failed";
+function causeOf(build) {
+	const at = build.diagnostics?.find((d) => d.file && d.line !== null);
+	if (at) return {
+		key: `${at.file}:${at.line}`,
+		at
+	};
+	return {
+		key: build.errorCode ?? "failed",
+		at: null
+	};
+}
+/** The streak of failures at the head of a platform's history that share the newest one's cause. */
+function failureStreak(platform, history) {
+	const head = history?.[0];
+	if (!head || !failed(head)) return null;
+	const cause = causeOf(head);
+	let count = 0;
+	for (const build of history) {
+		if (!failed(build) || causeOf(build).key !== cause.key) break;
+		count++;
+	}
+	const body = (n, format = attentionBody) => {
+		if (cause.at) {
+			const file = basename(cause.at.file);
+			const language = LANGUAGES[file.split(".").at(-1)?.toLowerCase() ?? ""];
+			return format({
+				kind: "diagnostic-loop",
+				platform,
+				count: n,
+				file,
+				line: cause.at.line,
+				language
+			});
+		}
+		if (head.errorCode === "STIM_LAUNCH_FAILED") return format({
+			kind: "launch-loop",
+			platform,
+			count: n
+		});
+		return format({
+			kind: "build-loop",
+			platform,
+			count: n,
+			errorCode: head.errorCode
+		});
+	};
+	return {
+		signature: cause.key,
+		count,
+		body
+	};
+}
+function heldFor(held, now) {
+	return held ?? {
+		since: now,
+		notified: false
+	};
+}
+function wake(run, at) {
+	if (at > run.now) run.wakeAt = run.wakeAt === null ? at : Math.min(run.wakeAt, at);
+}
+/** Notifies an event now; one missed for quiet hours or a switched-off category is dropped. */
+function event(run, notification) {
+	if (!run.baseline && !run.prefs.quiet && run.prefs.categories.includes(notification.category)) run.notifications.push(notification);
+}
+/** Whether a lasting problem is settled: notified now, or dropped when its category is off. */
+function lasting(run, notification) {
+	if (run.baseline || !run.prefs.categories.includes(notification.category)) return true;
+	if (run.prefs.quiet) return false;
+	run.notifications.push(notification);
+	return true;
+}
+function machineNotification(run, id, body) {
+	return {
+		id: `machine:${id}`,
+		category: "machine",
+		title: run.input.machine,
+		body,
+		quiet: true,
+		thread: null,
+		target: { kind: "machine" }
+	};
+}
+const LINK_BODY = {
+	offline: "Offline",
+	unpaired: "Not paired: pair again",
+	refused: "Refused the connection: pair again or update"
+};
+function overseeMachine(run, previous, state, awakeSince) {
+	const { input, now } = run;
+	const kind = input.link;
+	if (kind !== null && kind !== "open") {
+		const held = {
+			...heldFor(previous?.link?.kind === kind ? previous.link : void 0, now),
+			kind
+		};
+		const due = Math.max(held.since, awakeSince) + (kind === "offline" ? OFFLINE_SETTLE_MS : 0);
+		if (!held.notified && now < due) wake(run, due);
+		else if (!held.notified) held.notified = lasting(run, machineNotification(run, "link", LINK_BODY[kind]));
+		state.link = held;
+	}
+	const lowest = input.volumes?.reduce((min, v) => min === null ? v.freeBytes : Math.min(min, v.freeBytes), null);
+	if (input.volumes === null) {
+		if (previous?.disk) state.disk = previous.disk;
+	} else if (lowest !== null && lowest !== void 0 && lowest < (previous?.disk ? DISK_RECOVERED_BYTES : DISK_CRITICAL_BYTES)) {
+		const held = { ...heldFor(previous?.disk, now) };
+		const body = `${formatBytes(lowest)} free, below Stim's floor`;
+		if (!held.notified) held.notified = lasting(run, machineNotification(run, "disk", body));
+		state.disk = held;
+	}
+	state.memoryKnown = input.memoryPressure !== null || previous?.memoryKnown === true;
+	if (input.memoryPressure === "critical") {
+		const held = { ...heldFor(previous?.memory, now) };
+		if (!previous?.memoryKnown) held.notified = true;
+		const due = held.since + MEMORY_SETTLE_MS;
+		if (!held.notified && now < due && !run.baseline) wake(run, due);
+		else if (!held.notified) held.notified = lasting(run, machineNotification(run, "memory", "Memory pressure is critical"));
+		state.memory = held;
+	} else if (input.memoryPressure === null && previous?.memory) state.memory = previous.memory;
+}
+function deviceTarget(env, device) {
+	return {
+		kind: "device",
+		path: env.path,
+		platform: device.platform,
+		slot: device.slot
+	};
+}
+function overseeStart(run, { env, entry, notify, driven }) {
+	if (env.phase === "warming" && !entry.warmed) {
+		entry.warmed = true;
+		event(run, notify("started", `Warming on ${run.input.machine}`, {
+			kind: "workspace",
+			path: env.path
+		}));
+	}
+	const first = driven[0];
+	if (!first) return;
+	entry.drove = true;
+	entry.drivenAt = run.now;
+	entry.finished = false;
+	if (entry.driveNotified) return;
+	entry.driveNotified = true;
+	event(run, notify("started", `${first.activity?.driver?.tool ?? "An agent"} started driving ${first.model} on ${run.input.machine}`, deviceTarget(env, first)));
+}
+/** Work finishes when the agent stops after a green build; it looks stuck when nothing happens for too long. */
+function overseeProgress(run, { env, entry, notify, devices, driven }) {
+	const { now } = run;
+	const idle = !env.live && (env.phase === void 0 || env.phase === "idle");
+	const building = env.build?.state === "running";
+	const newest = newestBuild(env);
+	const green = newest?.status === "ok";
+	const releasedGreen = driven.length === 0 && green;
+	const quietSince = lastActivityAt(env, devices, [entry.errorsAt, driven.length ? null : entry.drivenAt]);
+	if (entry.stuckAt !== null && quietSince !== null && quietSince > entry.stuckAt) entry.stuckAt = null;
+	if (entry.drove && releasedGreen && newest && !building && quietSince !== null && !entry.finished) {
+		const due = quietSince + FINISH_SETTLE_MS;
+		if (!idle && now < due) wake(run, due);
+		else {
+			entry.finished = true;
+			event(run, notify("finished", `Agent stopped after a green ${platformName(newest.platform)} build`, {
+				kind: "workspace",
+				path: env.path
+			}));
+		}
+	}
+	if (idle || entry.finished) {
+		entry.drove = false;
+		entry.driveNotified = false;
+	}
+	if (idle) {
+		entry.warmed = false;
+		entry.finished = false;
+	}
+	const device = driven[0] ?? devices.find((d) => d.running);
+	if (!entry.drove || !device?.running || building || quietSince === null || releasedGreen) return;
+	if (entry.stuckAt !== null) return;
+	const due = quietSince + run.prefs.stuckMinutes * 6e4;
+	if (now < due) return wake(run, due);
+	if (lasting(run, notify("stuck", `No agent activity for ${Math.floor((now - quietSince) / 6e4)} min${green && newest ? ` after a green ${platformName(newest.platform)} build` : ""}; ${device.model} still up`, deviceTarget(env, device)))) entry.stuckAt = quietSince;
+}
+function overseeLoops(run, { env, entry, notify }, prev) {
+	for (const platform of ["ios", "android"]) {
+		const streak = failureStreak(platform, env.builds?.[platform]);
+		if (!streak) continue;
+		const before = prev?.loops[platform];
+		const loop = before && before.signature === streak.signature && streak.count >= LOOP_COUNT ? { ...before } : {
+			signature: streak.signature,
+			notified: false
+		};
+		if (streak.count >= LOOP_COUNT && !loop.notified) {
+			const target = {
+				kind: "build",
+				path: env.path,
+				platform
+			};
+			loop.notified = lasting(run, notify("looping", streak.body(streak.count), target, `looping-${platform}`));
+		}
+		entry.loops[platform] = loop;
+	}
+}
+/** A pull request that became ready for review or merged, or, without GitHub, a branch git finds merged. */
+function overseeMerge(run, { env, entry, notify }, prev) {
+	const pr = run.input.pullRequests[env.path];
+	if (pr !== void 0) {
+		const known = entry.pr;
+		const current = pr && {
+			number: pr.number,
+			ready: pr.state === "open" && !pr.draft,
+			merged: pr.state === "merged"
+		};
+		if (pr && current && known !== void 0) {
+			const url = {
+				kind: "url",
+				path: env.path,
+				url: pr.url
+			};
+			const same = known?.number === pr.number;
+			if (current.ready && !(same && known.ready)) event(run, notify("finished", `PR #${pr.number} is ready for review`, url));
+			if (current.merged && !(same && known.merged) && !entry.mergeNotified) {
+				entry.mergeNotified = true;
+				event(run, notify("finished", `PR #${pr.number} merged`, url));
+			}
+		} else if (current?.merged) entry.mergeNotified = true;
+		entry.pr = current;
+	}
+	if (!prev) {
+		if (entry.mergedInto !== null) entry.mergeNotified = true;
+	} else if (entry.mergedInto === null) {
+		if (env.worktree?.git && !entry.pr?.merged) entry.mergeNotified = false;
+	} else if (prev.mergedInto === null && !entry.mergeNotified) {
+		entry.mergeNotified = true;
+		event(run, notify("finished", `Merged into ${entry.mergedInto}`, {
+			kind: "workspace",
+			path: env.path
+		}));
+	}
+}
+/** What only a person can fix, notified once per episode; what an agent handles is left out. */
+function overseeAttention(run, { env, entry, notify }, prev) {
+	const items = workspaceItems(env, {
+		now: run.now,
+		stuckMinutes: run.prefs.stuckMinutes,
+		easSessionMinutes: EAS_SESSION_MINUTES,
+		ownLeases: run.input.ownLeases
+	});
+	for (const item of items) {
+		if (item.category !== "attention") continue;
+		let target = {
+			kind: "workspace",
+			path: env.path
+		};
+		if (item.id.startsWith("run-")) {
+			const platform = item.id.startsWith("run-ios") ? "ios" : "android";
+			if ((failureStreak(platform, env.builds?.[platform])?.count ?? 0) >= LOOP_COUNT) continue;
+			target = {
+				kind: "build",
+				path: env.path,
+				platform
+			};
+		}
+		const notification = {
+			...notify("attention", item.body, target),
+			id: item.id
+		};
+		if (prev?.attention?.includes(item.id) || lasting(run, notification)) entry.attention.push(item.id);
+	}
+}
+function overseeWorkspace(run, env, status, prev) {
+	const errors = env.logs?.errorsSinceMarker ?? 0;
+	const git = env.worktree?.git;
+	const entry = {
+		seenAt: run.now,
+		warmed: prev?.warmed ?? false,
+		drove: prev?.drove ?? false,
+		drivenAt: prev?.drivenAt ?? null,
+		driveNotified: prev?.driveNotified ?? false,
+		errors,
+		errorsAt: prev && prev.errors !== errors ? run.now : prev?.errorsAt ?? null,
+		stuckAt: prev?.stuckAt ?? null,
+		finished: prev?.finished ?? false,
+		attention: [],
+		loops: {},
+		pr: prev?.pr,
+		mergedInto: git ? git.mergedInto : prev?.mergedInto ?? null,
+		mergeNotified: prev?.mergeNotified ?? false
+	};
+	const title = oversightTitle(env, status);
+	const notify = (category, body, target, id = category) => ({
+		id: `${id}:${env.path}`,
+		category,
+		title,
+		body,
+		quiet: true,
+		thread: category === "started" ? `started:${run.input.machine}` : null,
+		target
+	});
+	const devices = devicesOf(env);
+	const look = {
+		env,
+		entry,
+		notify,
+		devices,
+		driven: devices.filter((device) => agentDriven(device, run.input.ownLeases))
+	};
+	overseeStart(run, look);
+	overseeProgress(run, look);
+	overseeLoops(run, look, prev);
+	overseeMerge(run, look, prev);
+	overseeAttention(run, look, prev);
+	return entry;
+}
+/**
+* The notifications a machine owes since `previous`, the state the last call returned. Null `previous` records
+* what is already true without notifying, so a restart or a new registration stays quiet. Each workspace and
+* machine problem notifies once per episode, under one id per category, so a later episode replaces it.
+* `awakeSince` restarts the offline settle time, for a checker that was not running.
+*/
+function oversee(previous, input, prefs, now, awakeSince = 0) {
+	const run = {
+		input,
+		prefs,
+		now,
+		baseline: previous === null,
+		notifications: [],
+		wakeAt: null
+	};
+	const state = { workspaces: {} };
+	overseeMachine(run, previous, state, awakeSince);
+	const status = input.status;
+	if (status === null) state.workspaces = { ...previous?.workspaces };
+	else {
+		for (const env of status.environments) state.workspaces[env.path] = overseeWorkspace(run, env, status, previous?.workspaces[env.path]);
+		for (const [path, entry] of Object.entries(previous?.workspaces ?? {})) if (!(path in state.workspaces) && now - entry.seenAt < FORGET_MS) state.workspaces[path] = entry;
+	}
+	return {
+		state,
+		notifications: run.notifications,
+		wakeAt: run.wakeAt
+	};
+}
+function formatBytes(bytes) {
+	if (bytes >= 0xe8d4a51000) return `${(bytes / 0xe8d4a51000).toFixed(1)} TB`;
+	const gb = bytes / 1e9;
+	return gb >= 100 ? `${Math.round(gb)} GB` : `${gb.toFixed(1)} GB`;
+}
+/** Whether `minuteOfDay` falls in quiet hours from `start` to `end`, minutes after midnight; they may span midnight. */
+function inQuietHours(quietHours, minuteOfDay) {
+	if (!quietHours || quietHours.start === quietHours.end) return false;
+	const { start, end } = quietHours;
+	return start < end ? minuteOfDay >= start && minuteOfDay < end : minuteOfDay >= start || minuteOfDay < end;
+}
+/** How long a billable EAS session may run with no agent before it needs a person. */
+const EAS_SESSION_MINUTES = 30;
+function attentionBody(message) {
+	switch (message.kind) {
+		case "issue": return message.slot ? `${message.slot}: ${message.message}` : message.message;
+		case "signing": return `${platformName(message.platform)} signing or provisioning failed (${message.code})`;
+		case "diagnostic-loop": return `Same ${message.language ? `${message.language} ` : `${platformName(message.platform)} build `}error ${message.count}x at ${message.file}:${message.line}`;
+		case "launch-loop": return `App failed to launch on ${platformName(message.platform)} ${message.count}x in a row`;
+		case "build-loop": {
+			const code = message.errorCode ? ` (${message.errorCode})` : "";
+			return `${platformName(message.platform)} build failed ${message.count}x in a row${code}`;
+		}
+		case "lease": return `Lease on ${message.leased} expired`;
+		case "eas": return `EAS session running for ${message.minutes} min with no agent; billed while it runs`;
+		case "stuck": {
+			const after = message.green ? ` after a green ${platformName(message.green)} build` : "";
+			return `No agent activity for ${message.minutes} min${after}; ${message.model} still up`;
+		}
+		case "disk": return `${formatBytes(message.freeBytes)} free, below Stim's floor`;
+	}
+}
+const PERSON_ISSUES = /* @__PURE__ */ new Set([
+	"port-not-ours",
+	"supervisor-unverified",
+	"browser-unverified",
+	"avd-unchecked"
+]);
+const SIGNING_CODES = [
+	"STIM_NO_SIGNING_IDENTITY",
+	"STIM_CODESIGN_FAILED",
+	"STIM_NO_PROFILE",
+	"STIM_PROFILE_MISMATCH"
+];
+/** A failed run older than this on an idle workspace is history, not a problem. */
+const STALE_MS = 864e5;
+const recent = (env, at, now) => env.live || now - time(at) < 864e5;
+function workspaceItems(env, input, format = attentionBody) {
+	const { now } = input;
+	const items = [];
+	for (const issue of env.issues ?? []) {
+		if (issue.severity === "info" || !PERSON_ISSUES.has(issue.code)) continue;
+		items.push({
+			id: `issue-${issue.code}-${issue.slot ?? "default"}:${env.path}`,
+			category: "attention",
+			severity: issue.severity === "error" ? "error" : "warning",
+			workspace: env.path,
+			body: format({
+				kind: "issue",
+				slot: issue.slot,
+				message: issue.message
+			}),
+			remedy: issue.remedy
+		});
+	}
+	for (const platform of ["ios", "android"]) {
+		const last = env.lastBuilds?.[platform];
+		const building = env.build?.state === "running" && env.build.platform === platform;
+		const code = last?.errorCode ?? "";
+		if (last && last.status === "failed" && !building && SIGNING_CODES.includes(code)) {
+			if (recent(env, last.finishedAt ?? last.startedAt, now)) {
+				items.push({
+					id: `run-${platform}:${env.path}`,
+					category: "attention",
+					severity: "error",
+					workspace: env.path,
+					body: format({
+						kind: "signing",
+						platform,
+						code
+					}),
+					remedy: null
+				});
+				continue;
+			}
+		}
+		const history = env.builds?.[platform];
+		const streak = failureStreak(platform, history);
+		const head = history?.[0];
+		if (streak && head && streak.count >= LOOP_COUNT && recent(env, head.finishedAt ?? head.startedAt, now)) items.push({
+			id: `looping-${platform}:${env.path}`,
+			category: "looping",
+			severity: "error",
+			workspace: env.path,
+			body: streak.body(streak.count, format),
+			remedy: null
+		});
+	}
+	for (const device of env.physicalDevices ?? []) {
+		if (!(time(device.lease.expiresAt) <= now)) continue;
+		const slot = device.slot === "default" ? "" : ` --slot ${device.slot}`;
+		items.push({
+			id: `lease-${device.platform}-${device.slot}:${env.path}`,
+			category: "attention",
+			severity: "warning",
+			workspace: env.path,
+			body: format({
+				kind: "lease",
+				leased: device.name ?? device.model ?? device.id
+			}),
+			remedy: `stim device unlock ${device.platform}${slot}`
+		});
+	}
+	const devices = devicesOf(env);
+	const driven = devices.find((d) => d.running && agentDriven(d, input.ownLeases ?? []));
+	for (const session of env.remoteDevices ?? []) {
+		const started = time(session.startedAt);
+		if (driven || !(now - started >= input.easSessionMinutes * 6e4)) continue;
+		items.push({
+			id: `eas-${session.sessionId}:${env.path}`,
+			category: "attention",
+			severity: "warning",
+			workspace: env.path,
+			body: format({
+				kind: "eas",
+				minutes: Math.floor((now - started) / 6e4)
+			}),
+			remedy: "stim stop"
+		});
+	}
+	const since = lastActivityAt(env, devices, []);
+	if (driven && env.build?.state !== "running" && since !== null && now - since >= input.stuckMinutes * 6e4) {
+		const newest = newestBuild(env);
+		items.push({
+			id: `stuck:${env.path}`,
+			category: "stuck",
+			severity: "warning",
+			workspace: env.path,
+			body: format({
+				kind: "stuck",
+				minutes: Math.floor((now - since) / 6e4),
+				green: newest?.status === "ok" && (newest.platform === "ios" || newest.platform === "android") ? newest.platform : null,
+				model: driven.model,
+				modelLabel: driven.modelLabel
+			}),
+			remedy: null
+		});
+	}
+	return items;
+}
+const severityRank = (item) => item.severity === "error" ? 0 : 1;
+/**
+* The items, errors first, then the machine's, then live workspaces' before idle ones', each in status order. Log
+* errors, a single failed run, and issues an agent's next `stim` command repairs are left out: agents handle them.
+*/
+function needsAttention(input, format = attentionBody) {
+	const ranked = [];
+	const lowest = input.volumes?.reduce((min, v) => min === null ? v.freeBytes : Math.min(min, v.freeBytes), null);
+	if (lowest !== null && lowest !== void 0 && lowest < DISK_CRITICAL_BYTES) ranked.push({
+		scope: 0,
+		item: {
+			id: "machine:disk",
+			category: "machine",
+			severity: "error",
+			workspace: null,
+			body: format({
+				kind: "disk",
+				freeBytes: lowest
+			}),
+			remedy: null
+		}
+	});
+	for (const env of input.environments) for (const item of workspaceItems(env, input, format)) ranked.push({
+		item,
+		scope: env.live ? 1 : 2
+	});
+	const order = ranked.map((entry, index) => ({
+		entry,
+		index
+	}));
+	order.sort((a, b) => severityRank(a.entry.item) - severityRank(b.entry.item) || a.entry.scope - b.entry.scope || a.index - b.index);
+	return order.map(({ entry }) => entry.item);
+}
+//#endregion
+export { DEFAULT_STUCK_MINUTES, OVERSIGHT_CATEGORIES, STALE_MS, inQuietHours, needsAttention, oversee, oversightTitle };