@stim-cli/server 1.10.0 → 1.11.0

package/dist/stim-server.mjs

@@ -1,18 +1,19 @@
 #!/usr/bin/env node
-import { a as MAX_LOG_TAIL, i as LOG_SOURCES, r as LOG_LEVELS, t as CAPABILITIES } from "./protocol-dn2_TUeH.mjs";
+import { a as FRAME_FPS, c as MAX_LOG_TAIL, i as FRAME_EDGE, n as CAPABILITIES, o as LOG_LEVELS, s as LOG_SOURCES, t as ACTIONS } from "./protocol-CmlG7X7_.mjs";
 import { createRequire } from "node:module";
-import { accessSync, constants, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, renameSync, rmSync, watch, writeFileSync } from "node:fs";
-import { homedir, hostname, tmpdir } from "node:os";
+import { accessSync, appendFileSync, constants, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, renameSync, rmSync, statSync, statfsSync, watch, writeFileSync } from "node:fs";
+import { availableParallelism, cpus, homedir, hostname, loadavg, tmpdir, totalmem } from "node:os";
 import { parseArgs } from "node:util";
 import { execFile, execFileSync, spawn, spawnSync } from "node:child_process";
 import { basename, delimiter, dirname, join } from "node:path";
+import { compileGrep, isJsonObject, loadConfig, readJsonObject } from "@stim-cli/core/state";
 import { createHash, randomBytes } from "node:crypto";
 import { configDir, withDirLock } from "@stim-cli/core";
-import { compileGrep, isJsonObject, loadConfig, readJsonObject } from "@stim-cli/core/state";
 import { createServer } from "node:http";
 import { isIP } from "node:net";
 import { WebSocketServer } from "ws";
 import { createInterface } from "node:readline";
+import { fileURLToPath } from "node:url";
 import { connect } from "node:http2";
 //#region src/environment.ts
 function parseEnvironment(output) {
@@ -90,13 +91,18 @@ function parseIdentity(value) {
 	};
 	return null;
 }
+function parseCapabilities(value) {
+	return Array.isArray(value) ? CAPABILITIES.filter((capability) => value.includes(capability)) : [];
+}
+function capabilitiesFor(control) {
+	return control ? ["read", "control"] : ["read"];
+}
 function parseDevice(value) {
 	if (!isJsonObject(value)) return null;
 	const { id, name, tokenHash, pairedAt, lastSeenAt } = value;
 	const identity = parseIdentity(value.identity);
 	if (typeof id !== "string" || typeof name !== "string" || typeof tokenHash !== "string" || !identity) return null;
 	if (typeof pairedAt !== "string") return null;
-	const capabilities = Array.isArray(value.capabilities) ? CAPABILITIES.filter((capability) => value.capabilities.includes(capability)) : [];
 	return {
 		id,
 		name,
@@ -104,7 +110,7 @@ function parseDevice(value) {
 		identity,
 		pairedAt,
 		lastSeenAt: typeof lastSeenAt === "string" ? lastSeenAt : null,
-		capabilities
+		capabilities: parseCapabilities(value.capabilities)
 	};
 }
 function readDevices() {
@@ -116,7 +122,8 @@ function readPairings() {
 	if (!Array.isArray(tokens)) return [];
 	return tokens.flatMap((entry) => isJsonObject(entry) && typeof entry.tokenHash === "string" && typeof entry.expiresAt === "string" ? [{
 		tokenHash: entry.tokenHash,
-		expiresAt: entry.expiresAt
+		expiresAt: entry.expiresAt,
+		capabilities: "capabilities" in entry ? parseCapabilities(entry.capabilities) : capabilitiesFor(false)
 	}] : []);
 }
 function writeJson(file, value) {
@@ -138,7 +145,8 @@ function transaction(fn) {
 function unexpired(record, now) {
 	return Date.parse(record.expiresAt) > now;
 }
-function createPairingToken(now = Date.now()) {
+/** The device that spends the token gets `capabilities`. */
+function createPairingToken(now = Date.now(), capabilities = capabilitiesFor(false)) {
 	const token = newToken();
 	const expiresAt = new Date(now + PAIRING_TTL_MS).toISOString();
 	transaction(() => {
@@ -147,7 +155,8 @@ function createPairingToken(now = Date.now()) {
 			version: 1,
 			tokens: [...pending, {
 				tokenHash: hashToken(token),
-				expiresAt
+				expiresAt,
+				capabilities
 			}]
 		});
 	});
@@ -187,7 +196,7 @@ function spendPairingToken(token, name, identity, now = Date.now()) {
 			identity,
 			pairedAt: at,
 			lastSeenAt: at,
-			capabilities: ["read"]
+			capabilities: match.capabilities
 		};
 		writeJson(devicesFile(), {
 			version: 1,
@@ -224,6 +233,19 @@ function authenticateDevice(token, identity, now = Date.now()) {
 		};
 	});
 }
+function grantDevice(id, capabilities) {
+	return transaction(() => {
+		const devices = readDevices();
+		const device = devices.find((entry) => entry.id === id);
+		if (!device) return false;
+		device.capabilities = capabilities;
+		writeJson(devicesFile(), {
+			version: 1,
+			devices
+		});
+		return true;
+	});
+}
 function revokeDevice(id) {
 	return transaction(() => {
 		const devices = readDevices();
@@ -237,6 +259,113 @@ function revokeDevice(id) {
 	});
 }
 //#endregion
+//#region src/actions.ts
+function parseAction(params) {
+	if (!isJsonObject(params)) return {
+		code: "bad-request",
+		message: "params must be an object."
+	};
+	const { action, workspace, platform, ...rest } = params;
+	if (typeof action !== "string" || !ACTIONS.includes(action)) return {
+		code: "unknown-action",
+		message: `Unknown action ${JSON.stringify(action)}. Actions: ${ACTIONS.join(", ")}.`
+	};
+	if (typeof workspace !== "string") return {
+		code: "bad-request",
+		message: "params.workspace must be an environment path from a status payload."
+	};
+	const extra = Object.keys(rest);
+	if (action === "stop" && platform !== void 0) extra.push("platform");
+	if (extra.length) return {
+		code: "bad-request",
+		message: `${action} does not take ${extra.join(", ")}.`
+	};
+	if (action === "stop") return { action: {
+		action,
+		workspace
+	} };
+	if (platform !== void 0 && platform !== "ios" && platform !== "android") return {
+		code: "bad-request",
+		message: "platform must be ios or android."
+	};
+	return { action: {
+		action: "reload",
+		workspace,
+		...platform ? { platform } : {}
+	} };
+}
+function actionArgs(action) {
+	if (action.action === "stop") return ["stop", "--json"];
+	return [
+		"reload",
+		...action.platform ? [action.platform] : [],
+		"--json"
+	];
+}
+/** The JSON object the command printed, and on failure the message and remedy it printed, if any. */
+function actionOutcome(outcome) {
+	let printed = null;
+	try {
+		printed = JSON.parse(outcome.stdout?.trim() ?? "");
+	} catch {
+		printed = null;
+	}
+	if (outcome.ok) return isJsonObject(printed) ? {
+		ok: true,
+		output: printed
+	} : {
+		ok: false,
+		error: {
+			code: "action-failed",
+			message: "The command printed output that is not a JSON object."
+		}
+	};
+	if (isJsonObject(printed) && typeof printed.message === "string") {
+		const code = typeof printed.code === "string" ? `${printed.code}: ` : "";
+		const remedy = typeof printed.remedy === "string" ? ` ${printed.remedy}` : "";
+		return {
+			ok: false,
+			error: {
+				code: "action-failed",
+				message: `${code}${printed.message}${remedy}`
+			}
+		};
+	}
+	return {
+		ok: false,
+		error: {
+			code: "action-failed",
+			message: outcome.message
+		}
+	};
+}
+function auditFile() {
+	return join(serverDir(), "actions.ndjson");
+}
+function appendAudit(record) {
+	mkdirSync(serverDir(), {
+		recursive: true,
+		mode: 448
+	});
+	appendFileSync(auditFile(), `${JSON.stringify(record)}\n`, { mode: 384 });
+}
+function readAudit() {
+	let text;
+	try {
+		text = readFileSync(auditFile(), "utf8");
+	} catch {
+		return [];
+	}
+	return text.split("\n").flatMap((line) => {
+		try {
+			const value = JSON.parse(line);
+			return isJsonObject(value) ? [value] : [];
+		} catch {
+			return [];
+		}
+	});
+}
+//#endregion
 //#region src/stim-command.ts
 const KILL_GRACE_MS = 1e3;
 function terminate(child) {
@@ -305,7 +434,8 @@ function runStim(stimCli, env, args, cwd, limits) {
 				const detail = stderr.trim();
 				settle({
 					ok: false,
-					message: `${label} exited (${signal ?? `code ${code}`})${detail ? `: ${detail}` : ""}`
+					message: `${label} exited (${signal ?? `code ${code}`})${detail ? `: ${detail}` : ""}`,
+					stdout: Buffer.concat(chunks).toString("utf8")
 				});
 			});
 		}),
@@ -406,11 +536,344 @@ var FeedPool = class {
 	}
 };
 //#endregion
+//#region src/video.ts
+const FIXED_HEADER_BYTES = 21;
+/** The binary WebSocket message for `unit` on `subscription`; see `VideoPacket` in protocol.ts for the layout. */
+function videoPacket(subscription, sequence, unit) {
+	const id = Buffer.from(subscription, "ascii");
+	const header = Buffer.alloc(FIXED_HEADER_BYTES + id.length);
+	header.writeUInt8(1, 0);
+	header.writeUInt8(unit.keyframe ? 1 : 0, 1);
+	header.writeUInt16BE(header.length, 2);
+	header.writeUInt32BE(sequence >>> 0, 4);
+	header.writeDoubleBE(unit.capturedAt, 8);
+	header.writeUInt16BE(unit.width, 16);
+	header.writeUInt16BE(unit.height, 18);
+	header.writeUInt8(id.length, 20);
+	id.copy(header, FIXED_HEADER_BYTES);
+	return Buffer.concat([header, unit.data]);
+}
+const DEFAULT_VIDEO_LIMITS = {
+	congestedBytes: 262144,
+	startBitrate: 3e6,
+	minBitrate: 25e4,
+	maxBitrate: 8e6,
+	recoverMs: 2e3
+};
+/**
+* Decides, for one subscriber, whether each access unit goes out. A subscriber starts waiting for a keyframe.
+* When its socket backs up it drops everything until the next keyframe, because a P-frame is useless without
+* the frames before it; `congested` is reported once per episode.
+*/
+var VideoGate = class {
+	waiting = true;
+	congestedBytes;
+	constructor(congestedBytes) {
+		this.congestedBytes = congestedBytes;
+	}
+	admit(unit, bufferedBytes) {
+		if (bufferedBytes > this.congestedBytes) {
+			if (this.waiting) return "drop";
+			this.waiting = true;
+			return "congested";
+		}
+		if (this.waiting && !unit.keyframe) return "drop";
+		this.waiting = false;
+		return "send";
+	}
+	/** The client lost its decoder state; drop until the keyframe it asked for. */
+	reset() {
+		this.waiting = true;
+	}
+};
+/**
+* One encoder's bitrate, shared by all subscribers of a device: halved on congestion at most once per `recoverMs`,
+* and raised by a quarter after `recoverMs` without congestion.
+*/
+var Bitrate = class {
+	value;
+	calmSince;
+	cutAt = -Infinity;
+	limits;
+	constructor(limits, now) {
+		this.limits = limits;
+		this.value = limits.startBitrate;
+		this.calmSince = now;
+	}
+	get current() {
+		return this.value;
+	}
+	/** Called while any subscriber is congested. Returns the new bitrate when it changed. */
+	congested(now) {
+		this.calmSince = now;
+		if (now - this.cutAt < this.limits.recoverMs) return null;
+		this.cutAt = now;
+		return this.set(Math.max(this.limits.minBitrate, Math.round(this.value / 2)));
+	}
+	/** Returns the new bitrate when it changed. */
+	tick(now) {
+		if (now - this.calmSince < this.limits.recoverMs) return null;
+		this.calmSince = now;
+		return this.set(Math.min(this.limits.maxBitrate, Math.round(this.value * 1.25)));
+	}
+	set(next) {
+		if (next === this.value) return null;
+		this.value = next;
+		return next;
+	}
+};
+//#endregion
+//#region src/frame-helper.ts
+const DEFAULT_FRAME_HINT = {
+	fps: FRAME_FPS.default,
+	maxEdge: FRAME_EDGE.default
+};
+const SOURCES_DIR = fileURLToPath(new URL("./stim-frames/", import.meta.url));
+const BUILD_TIMEOUT_MS = 18e4;
+const VERSION_TIMEOUT_MS = 3e4;
+const MAX_MESSAGE_BYTES = 16777216;
+const FRAME_MESSAGE = 1;
+const NOTICE_MESSAGE = 2;
+const VIDEO_MESSAGE = 3;
+const VIDEO_HEADER_BYTES = 14;
+const KEYFRAME_INTERVAL_MS = 250;
+/** Runs the compiler in its own process group, so a timeout or `signal` also stops `swift-frontend` and `ld`. */
+function run(file, args, env, timeoutMs, signal) {
+	return new Promise((resolve, reject) => {
+		const child = spawn(file, args, {
+			env,
+			stdio: [
+				"ignore",
+				"pipe",
+				"pipe"
+			],
+			detached: true
+		});
+		let output = "";
+		let stopped = null;
+		const stop = (reason) => {
+			stopped ??= reason;
+			try {
+				process.kill(-child.pid, "SIGKILL");
+			} catch {}
+		};
+		const timer = setTimeout(() => stop(`${file} ${args[0]} did not finish within ${timeoutMs / 1e3} s.`), timeoutMs);
+		const abort = () => stop(`${file} ${args[0]} was stopped with the server.`);
+		signal?.addEventListener("abort", abort);
+		child.stdout.setEncoding("utf8");
+		child.stderr.setEncoding("utf8");
+		child.stdout.on("data", (chunk) => output = (output + chunk).slice(-4e3));
+		child.stderr.on("data", (chunk) => output = (output + chunk).slice(-4e3));
+		child.on("error", (error) => {
+			clearTimeout(timer);
+			signal?.removeEventListener("abort", abort);
+			reject(/* @__PURE__ */ new Error(`${file} could not start (${error.message}).`));
+		});
+		child.on("close", (code) => {
+			clearTimeout(timer);
+			signal?.removeEventListener("abort", abort);
+			if (stopped) reject(new Error(stopped));
+			else if (code === 0) resolve(output);
+			else reject(/* @__PURE__ */ new Error(`${file} ${args[0]} exited (code ${code}): ${output.trim()}`));
+		});
+	});
+}
+/**
+* Compiles the `stim-frames` helper from the Swift sources shipped in `dist/stim-frames/` into
+* `$STIM_HOME/server/helpers/`, named by a hash of the sources and the compiler version. Resolves to the
+* helper's path, or rejects with the reason it cannot be built.
+*/
+async function buildFrameHelper(env, signal, sourcesDir = SOURCES_DIR) {
+	if (process.platform !== "darwin") throw new Error("stim-frames runs only on macOS.");
+	const sources = readdirSync(sourcesDir).filter((name) => name.endsWith(".swift")).toSorted();
+	if (!sources.length) throw new Error(`${sourcesDir} has no Swift sources.`);
+	const version = await run("xcrun", ["swiftc", "--version"], env, VERSION_TIMEOUT_MS, signal);
+	const hash = createHash("sha256").update(version);
+	for (const name of sources) hash.update(name).update(readFileSync(join(sourcesDir, name)));
+	const dir = join(serverDir(), "helpers");
+	const helper = join(dir, `stim-frames-${hash.digest("hex").slice(0, 16)}`);
+	if (existsSync(helper)) return helper;
+	mkdirSync(dir, {
+		recursive: true,
+		mode: 448
+	});
+	const output = `${helper}.tmp-${process.pid}-${randomBytes(4).toString("hex")}`;
+	try {
+		await run("xcrun", [
+			"swiftc",
+			"-O",
+			"-swift-version",
+			"5",
+			"-module-name",
+			"StimFrames",
+			"-o",
+			output,
+			...sources.map((source) => join(sourcesDir, source))
+		], env, BUILD_TIMEOUT_MS, signal);
+		renameSync(output, helper);
+	} finally {
+		rmSync(output, { force: true });
+	}
+	return helper;
+}
+/**
+* One `stim-frames` process per device, shared by its subscribers and stopped with the last of them. It runs
+* at the highest fps and the largest edge any subscriber asked for; each subscriber paces its own frames. The
+* helper exits when its stdin closes, so it cannot outlive the server.
+*/
+var HelperSource = class {
+	listeners = /* @__PURE__ */ new Map();
+	child;
+	last = null;
+	config = "";
+	stopped = false;
+	notice = null;
+	stderr = "";
+	ended;
+	bitrate = new Bitrate(DEFAULT_VIDEO_LIMITS, Date.now());
+	keyframeAt = -Infinity;
+	keyframeTimer = null;
+	constructor(helper, device, env, ended) {
+		this.ended = ended;
+		const id = device.platform === "ios" ? device.udid : device.serial;
+		this.child = spawn(helper, [device.platform, id], {
+			env,
+			stdio: [
+				"pipe",
+				"pipe",
+				"pipe"
+			]
+		});
+		this.child.stdin.on("error", () => {});
+		this.child.stderr.setEncoding("utf8");
+		this.child.stderr.on("data", (chunk) => {
+			this.stderr = (this.stderr + chunk).slice(-1e3);
+		});
+		this.readMessages();
+		this.child.on("error", (error) => this.fail(`stim-frames could not start (${error.message}).`));
+		this.child.on("close", (code, signal) => {
+			const detail = this.notice ?? this.stderr.trim();
+			this.fail(`stim-frames exited (${signal ?? `code ${code}`})${detail ? `: ${detail}` : ""}`);
+		});
+	}
+	add(listener, hint) {
+		this.listeners.set(listener, hint);
+		this.configure();
+		if (listener.video) this.keyframe();
+		else if (this.last) listener.frame(this.last);
+		return () => {
+			if (!this.listeners.delete(listener)) return;
+			if (this.listeners.size === 0) this.stop();
+			else this.configure();
+		};
+	}
+	stop() {
+		if (this.stopped) return Promise.resolve();
+		this.stopped = true;
+		if (this.keyframeTimer) clearTimeout(this.keyframeTimer);
+		this.listeners.clear();
+		this.ended();
+		this.child.stdin.end();
+		return terminate(this.child);
+	}
+	/** Asks for at most one keyframe per {@link KEYFRAME_INTERVAL_MS}; a request inside the interval is sent at its end. */
+	keyframe() {
+		if (this.stopped || this.keyframeTimer) return;
+		const wait = this.keyframeAt + KEYFRAME_INTERVAL_MS - Date.now();
+		if (wait > 0) {
+			this.keyframeTimer = setTimeout(() => {
+				this.keyframeTimer = null;
+				this.keyframe();
+			}, wait);
+			return;
+		}
+		this.keyframeAt = Date.now();
+		this.child.stdin.write("{\"keyframe\":true}\n");
+	}
+	congested() {
+		if (this.bitrate.congested(Date.now()) !== null) this.configure();
+	}
+	configure() {
+		const hints = [...this.listeners.values()];
+		const jpegFps = [...this.listeners].flatMap(([listener, hint]) => listener.video ? [] : [hint.fps]);
+		const config = JSON.stringify({
+			fps: Math.max(...hints.map((hint) => hint.fps)),
+			maxEdge: Math.max(...hints.map((hint) => hint.maxEdge)),
+			jpeg: jpegFps.length > 0,
+			...jpegFps.length ? { jpegFps: Math.max(...jpegFps) } : {},
+			video: jpegFps.length < hints.length,
+			bitrate: this.bitrate.current
+		});
+		if (!jpegFps.length) this.last = null;
+		if (config === this.config || this.stopped) return;
+		this.config = config;
+		this.child.stdin.write(`${config}\n`);
+	}
+	fail(message) {
+		if (this.stopped) return;
+		const listeners = [...this.listeners.keys()];
+		this.stop();
+		for (const listener of listeners) listener.failed(message);
+	}
+	readMessages() {
+		let buffer = Buffer.alloc(0);
+		this.child.stdout.on("data", (chunk) => {
+			buffer = buffer.length ? Buffer.concat([buffer, chunk]) : chunk;
+			while (buffer.length >= 4) {
+				const length = buffer.readUInt32BE(0);
+				if (length < 1 || length > MAX_MESSAGE_BYTES) {
+					this.child.stdout.removeAllListeners("data");
+					return this.fail("stim-frames wrote a malformed message.");
+				}
+				if (buffer.length < 4 + length) break;
+				const body = buffer.subarray(4, 4 + length);
+				buffer = buffer.subarray(4 + length);
+				if (body[0] === FRAME_MESSAGE && body.length > 5) this.frame(body);
+				else if (body[0] === VIDEO_MESSAGE && body.length > VIDEO_HEADER_BYTES) this.video(body);
+				else if (body[0] === NOTICE_MESSAGE) this.readNotice(body.subarray(1).toString("utf8"));
+			}
+		});
+	}
+	frame(body) {
+		if (this.stopped) return;
+		this.last = {
+			width: body.readUInt16BE(1),
+			height: body.readUInt16BE(3),
+			capturedAt: (/* @__PURE__ */ new Date()).toISOString(),
+			data: body.subarray(5).toString("base64")
+		};
+		for (const listener of this.listeners.keys()) if (!listener.video) listener.frame(this.last);
+	}
+	video(body) {
+		if (this.stopped) return;
+		const unit = {
+			keyframe: (body[1] & 1) !== 0,
+			capturedAt: body.readDoubleBE(2),
+			width: body.readUInt16BE(10),
+			height: body.readUInt16BE(12),
+			data: body.subarray(VIDEO_HEADER_BYTES)
+		};
+		if (this.bitrate.tick(Date.now()) !== null) this.configure();
+		for (const listener of this.listeners.keys()) listener.video?.(unit);
+	}
+	readNotice(text) {
+		try {
+			const error = JSON.parse(text)?.error;
+			if (typeof error === "string") this.notice = error;
+		} catch {}
+	}
+};
+//#endregion
 //#region src/frames.ts
+const DEFAULT_FRAME_LIMITS = {
+	toolTimeoutMs: 3e4,
+	slowCaptureMs: 3e3,
+	failureBackoffMs: 3e3,
+	maxConsecutiveFailures: 3
+};
 const MIN_INTERVAL_MS = 200;
 const MAX_INTERVAL_MS = 1e3;
 const MAX_CAPTURES = 2;
-const TOOL_TIMEOUT_MS = 1e4;
 const MAX_EDGE = 1280;
 const JPEG_QUALITY = 70;
 function deviceKey(device) {
@@ -432,7 +895,8 @@ function ownedDevice(payload, target, attached) {
 		if (sim.state !== "Booted") return `The simulator for ${where} is ${sim.state}, not booted.`;
 		return {
 			platform: "ios",
-			udid: sim.udid
+			udid: sim.udid,
+			foldable: /\bDuo\b/.test(sim.name ?? "")
 		};
 	}
 	const emulator = devices?.android;
@@ -469,7 +933,14 @@ function jpegSize(bytes) {
 	}
 	return null;
 }
-function runTool(file, args, env, running) {
+/** A rejection with `transient: true` is a timeout on a machine that is merely busy, not a broken capturer. */
+function timeoutError(message) {
+	return Object.assign(new Error(message), { transient: true });
+}
+function isTransient(error) {
+	return error instanceof Error && error.transient === true;
+}
+function runTool(file, args, env, running, timeoutMs) {
 	return new Promise((resolve, reject) => {
 		const child = spawn(file, args, {
 			env,
@@ -485,8 +956,8 @@ function runTool(file, args, env, running) {
 		let stderr = "";
 		const timer = setTimeout(() => {
 			terminate(child);
-			reject(/* @__PURE__ */ new Error(`${file} ${args[0]} did not finish within ${TOOL_TIMEOUT_MS / 1e3} s.`));
-		}, TOOL_TIMEOUT_MS);
+			reject(timeoutError(`${file} ${args[0]} did not finish within ${timeoutMs / 1e3} s.`));
+		}, timeoutMs);
 		child.stdout.on("data", (chunk) => chunks.push(chunk));
 		child.stderr.setEncoding("utf8");
 		child.stderr.on("data", (chunk) => {
@@ -511,36 +982,87 @@ async function stopTools(running, tmp) {
 	});
 }
 /**
-* Without `--display`, simctl captures the first panel it finds, which on a foldable simulator (iPhone Duo)
-* can be the unlit one and comes back black; `primary` is the panel CoreDevice reports as primary. A simctl
-* that rejects `primary` gets the default display instead.
+* Without `--display`, simctl captures the first panel it finds; `primary` is the panel CoreDevice reports as
+* primary. A simctl that rejects `primary` gets the default display instead.
+*
+* An iPhone Duo lights one of two panels: `primary` is the cover, lit when folded, and `primary-1` the inner
+* panel, lit when unfolded; the other one's framebuffer is all black. `litPanels` remembers the lit panel per
+* simulator across subscriptions, and a black capture tries the other panel.
 */
-function simulatorCapturer(udid, env) {
+function simulatorCapturer(device, env, limits, litPanels) {
 	let tmp = null;
 	let display = ["--display=primary"];
 	let closed = false;
 	const running = /* @__PURE__ */ new Set();
-	const screenshot = (output) => runTool("xcrun", [
-		"simctl",
-		"io",
-		udid,
-		"screenshot",
-		"--type=jpeg",
-		...display,
-		output
-	], env, running);
+	const screenshot = async (panel) => {
+		tmp ??= mkdtempSync(join(serverDir(), "frames-"));
+		const output = join(tmp, "frame.jpg");
+		await runTool("xcrun", [
+			"simctl",
+			"io",
+			device.udid,
+			"screenshot",
+			"--type=jpeg",
+			...panel,
+			output
+		], env, running, limits.toolTimeoutMs);
+		return readFileSync(output);
+	};
+	const isBlack = async (jpeg) => {
+		const input = join(tmp, "check.jpg");
+		const output = join(tmp, "check.bmp");
+		writeFileSync(input, jpeg);
+		await runTool("sips", [
+			"-s",
+			"format",
+			"bmp",
+			"-z",
+			"24",
+			"24",
+			input,
+			"--out",
+			output
+		], env, running, limits.toolTimeoutMs);
+		return bmpIsBlack(readFileSync(output));
+	};
+	const open = () => {
+		if (closed) throw new Error("The capture was stopped.");
+	};
+	const captureDuo = async () => {
+		const lit = litPanels.get(device.udid) ?? "primary";
+		const jpeg = await screenshot([`--display=${lit}`]);
+		open();
+		if (!await isBlack(jpeg)) return {
+			raw: jpeg,
+			jpeg: async () => jpeg,
+			posture: POSTURES[lit]
+		};
+		const other = lit === "primary" ? "primary-1" : "primary";
+		open();
+		const otherJpeg = await screenshot([`--display=${other}`]);
+		open();
+		if (await isBlack(otherJpeg)) return {
+			raw: jpeg,
+			jpeg: async () => jpeg
+		};
+		litPanels.set(device.udid, other);
+		return {
+			raw: otherJpeg,
+			jpeg: async () => otherJpeg,
+			posture: POSTURES[other]
+		};
+	};
 	return {
 		capture: async () => {
-			tmp ??= mkdtempSync(join(serverDir(), "frames-"));
-			const output = join(tmp, "frame.jpg");
+			if (device.foldable) return captureDuo();
+			let jpeg;
 			try {
-				await screenshot(output);
+				jpeg = await screenshot(display);
 			} catch (error) {
 				if (closed || !display.length || !/display/i.test(error.stderr ?? "")) throw error;
 				display = [];
-				await screenshot(output);
+				jpeg = await screenshot(display);
 			}
-			const jpeg = readFileSync(output);
 			return {
 				raw: jpeg,
 				jpeg: async () => jpeg
@@ -552,6 +1074,18 @@ function simulatorCapturer(udid, env) {
 		}
 	};
 }
+const POSTURES = {
+	primary: "folded",
+	"primary-1": "unfolded"
+};
+/** Whether every pixel of an uncompressed 24- or 32-bit BMP, as `sips -s format bmp` writes it, is black. */
+function bmpIsBlack(bmp) {
+	if (bmp.length < 54 || bmp.toString("latin1", 0, 2) !== "BM") throw new Error("sips did not write a BMP image.");
+	const offset = bmp.readUInt32LE(10);
+	const bytesPerPixel = bmp.readUInt16LE(28) / 8;
+	for (let at = offset; at + 3 <= bmp.length; at += bytesPerPixel) if (bmp[at] > 8 || bmp[at + 1] > 8 || bmp[at + 2] > 8) return false;
+	return true;
+}
 /**
 * The emulator writes `pid_<pid>.ini` to this directory on macOS when it was started with `-grpc`, which
 * Stim passes when it boots an owned AVD (#1064).
@@ -636,36 +1170,61 @@ function* protoFields(bytes) {
 		else throw new Error(`unsupported protobuf wire type ${type}`);
 	}
 }
-/** `ImageFormat` and `Image` in the emulator's emulator_controller.proto; format 0 is PNG. */
-function screenshotRequest() {
-	const message = Buffer.from([
-		24,
-		...varint(MAX_EDGE),
-		32,
-		...varint(MAX_EDGE)
-	]);
+function grpcMessage(message) {
 	const header = Buffer.alloc(5);
 	header.writeUInt32BE(message.length, 1);
-	return Buffer.concat([header, message]);
+	return Buffer.concat([header, Buffer.from(message)]);
+}
+function grpcReply(body, method) {
+	if (body.length < 5 || body[0] !== 0) throw new Error(`${method} returned no message.`);
+	return body.subarray(5, 5 + body.readUInt32BE(1));
+}
+/**
+* `ImageFormat` and `Image` in the emulator's emulator_controller.proto; format 0 is PNG. The reply's
+* format carries `foldedDisplay` (field 7) while a foldable is folded.
+*/
+function screenshotReply(body) {
+	let png = null;
+	let folded = false;
+	for (const entry of protoFields(grpcReply(body, "getScreenshot"))) {
+		if (entry.field === 4 && "bytes" in entry) png = Buffer.from(entry.bytes);
+		if (entry.field === 1 && "bytes" in entry) folded = [...protoFields(entry.bytes)].some((format) => format.field === 7);
+	}
+	if (!png) throw new Error("getScreenshot returned no image.");
+	return {
+		png,
+		folded
+	};
 }
-function screenshotImage(body) {
-	if (body.length < 5 || body[0] !== 0) throw new Error("getScreenshot returned no message.");
-	const message = body.subarray(5, 5 + body.readUInt32BE(1));
-	for (const entry of protoFields(message)) if (entry.field === 4 && "bytes" in entry) return Buffer.from(entry.bytes);
-	throw new Error("getScreenshot returned no image.");
+/**
+* `PhysicalModelValue` for POSTURE (PhysicalType 16), whose one float is a `Posture.PostureValue`; 1 to 5
+* are real postures, so any of them means the emulator has a hinge.
+*/
+function hasHinge(body) {
+	for (const entry of protoFields(grpcReply(body, "getPhysicalModel"))) {
+		if (entry.field === 2 && "varint" in entry && entry.varint !== 0) return false;
+		if (entry.field !== 3 || !("bytes" in entry)) continue;
+		for (const value of protoFields(entry.bytes)) {
+			if (value.field !== 1 || !("bytes" in value) || value.bytes.length < 4) continue;
+			const posture = Math.round(value.bytes.readFloatLE(0));
+			return posture >= 1 && posture <= 5;
+		}
+	}
+	return false;
 }
-function emulatorCapturer(serial, env) {
+function emulatorCapturer(serial, env, limits) {
 	let session = null;
 	let tmp = null;
 	const running = /* @__PURE__ */ new Set();
-	const call = (endpoint) => new Promise((resolve, reject) => {
+	let hinged = null;
+	const call = (endpoint, method, requestBody) => new Promise((resolve, reject) => {
 		if (!session || session.closed || session.destroyed) {
 			session = connect(`http://127.0.0.1:${endpoint.grpcPort}`);
 			session.on("error", () => {});
 		}
 		const request = session.request({
 			":method": "POST",
-			":path": "/android.emulation.control.EmulatorController/getScreenshot",
+			":path": `/android.emulation.control.EmulatorController/${method}`,
 			"content-type": "application/grpc",
 			te: "trailers",
 			...endpoint.token ? { authorization: `Bearer ${endpoint.token}` } : {}
@@ -673,28 +1232,43 @@ function emulatorCapturer(serial, env) {
 		const chunks = [];
 		let status;
 		let message;
+		let timedOut = false;
 		const record = (headers) => {
 			if (headers["grpc-status"] !== void 0) status = String(headers["grpc-status"]);
 			if (headers["grpc-message"] !== void 0) message = String(headers["grpc-message"]);
 		};
-		request.setTimeout(TOOL_TIMEOUT_MS, () => request.close());
+		request.setTimeout(limits.toolTimeoutMs, () => {
+			timedOut = true;
+			request.close();
+		});
 		request.on("response", record);
 		request.on("trailers", record);
 		request.on("data", (chunk) => chunks.push(chunk));
-		request.on("error", (error) => reject(/* @__PURE__ */ new Error(`getScreenshot failed on ${serial}: ${error.message}`)));
+		request.on("error", (error) => {
+			const text = `${method} failed on ${serial}: ${error.message}`;
+			reject(timedOut ? timeoutError(text) : new Error(text));
+		});
 		request.on("close", () => {
 			if (status === "0") return resolve(Buffer.concat(chunks));
-			reject(/* @__PURE__ */ new Error(`getScreenshot failed on ${serial}: ${message ?? `status ${status ?? "missing"}`}`));
+			const text = `${method} failed on ${serial}: ${message ?? `status ${status ?? "missing"}`}`;
+			reject(timedOut ? timeoutError(text) : new Error(text));
 		});
-		request.end(screenshotRequest());
+		request.end(requestBody);
 	});
 	return {
 		capture: async () => {
 			const endpoint = emulatorEndpoint(env, serial);
 			if (!endpoint) throw new Error(`${serial} has no gRPC endpoint. Frames appear after Stim next boots this emulator.`);
-			const png = screenshotImage(await call(endpoint));
+			hinged ??= await call(endpoint, "getPhysicalModel", grpcMessage([8, 16])).then(hasHinge).catch(() => false);
+			const { png, folded } = screenshotReply(await call(endpoint, "getScreenshot", grpcMessage([
+				24,
+				...varint(MAX_EDGE),
+				32,
+				...varint(MAX_EDGE)
+			])));
 			return {
 				raw: png,
+				...hinged ? { posture: folded ? "folded" : "unfolded" } : {},
 				jpeg: async () => {
 					tmp ??= mkdtempSync(join(serverDir(), "frames-"));
 					const input = join(tmp, "frame.png");
@@ -712,7 +1286,7 @@ function emulatorCapturer(serial, env) {
 						input,
 						"--out",
 						output
-					], env, running);
+					], env, running, limits.toolTimeoutMs);
 					return readFileSync(output);
 				}
 			};
@@ -749,18 +1323,23 @@ var FrameSource = class {
 	interval = MIN_INTERVAL_MS;
 	timer = null;
 	stopped = false;
+	delayed = false;
+	consecutiveFailures = 0;
 	capturer;
 	limiter;
+	limits;
 	ended;
-	constructor(capturer, limiter, ended) {
+	constructor(capturer, limiter, limits, ended) {
 		this.capturer = capturer;
 		this.limiter = limiter;
+		this.limits = limits;
 		this.ended = ended;
 		this.tick();
 	}
 	add(listener) {
 		this.listeners.add(listener);
 		if (this.last) listener.frame(this.last);
+		if (this.delayed) listener.delayed(true);
 		return () => {
 			if (this.listeners.delete(listener) && this.listeners.size === 0) this.stop();
 		};
@@ -773,6 +1352,11 @@ var FrameSource = class {
 		this.ended();
 		return this.capturer.close();
 	}
+	setDelayed(delayed) {
+		if (this.delayed === delayed) return;
+		this.delayed = delayed;
+		for (const listener of this.listeners) listener.delayed(delayed);
+	}
 	async tick() {
 		this.timer = null;
 		let took = 0;
@@ -791,17 +1375,26 @@ var FrameSource = class {
 				this.last = {
 					...size,
 					capturedAt: new Date(started).toISOString(),
-					data: jpeg.toString("base64")
+					data: jpeg.toString("base64"),
+					...capture.posture ? { posture: capture.posture } : {}
 				};
 				took = Date.now() - started;
 				return true;
 			});
 			if (this.stopped) return;
+			this.consecutiveFailures = 0;
+			this.setDelayed(took > this.limits.slowCaptureMs);
 			if (changed) for (const listener of this.listeners) listener.frame(this.last);
 			this.interval = changed ? MIN_INTERVAL_MS : Math.min(this.interval * 2, MAX_INTERVAL_MS);
 			this.timer = setTimeout(() => void this.tick(), Math.max(this.interval - took, took));
 		} catch (error) {
 			if (this.stopped) return;
+			if (isTransient(error) && this.consecutiveFailures + 1 < this.limits.maxConsecutiveFailures) {
+				this.consecutiveFailures++;
+				this.setDelayed(true);
+				this.timer = setTimeout(() => void this.tick(), this.limits.failureBackoffMs);
+				return;
+			}
 			const listeners = [...this.listeners];
 			this.stop();
 			for (const listener of listeners) listener.failed(error.message);
@@ -809,29 +1402,83 @@ var FrameSource = class {
 	}
 };
 /**
-* One capture loop per device, shared by its subscribers and stopped with the last of them. A loop sends a
-* frame only when the screen changed; it captures up to 5 times a second while the screen changes and backs
-* off to once a second while it does not, and spends at most half of its time capturing. At most two
-* captures run at once across all devices.
+* One capture per device, shared by its subscribers and stopped with the last of them. With the `stim-frames`
+* helper, a device streams frames as its screen changes, at the rate its subscribers ask for. Without it, for
+* an iPhone Duo, and while the helper is still being built, a screenshot loop sends a frame only when the
+* screen changed: up to 5 times a second while it changes, backing off to once a second while it does not,
+* spending at most half of its time capturing, with at most two captures at once across all devices. A helper
+* that fails before its first frame gives way to the screenshot loop.
 */
 var FramePool = class {
 	sources = /* @__PURE__ */ new Map();
 	limiter = new Limiter(MAX_CAPTURES);
+	litPanels = /* @__PURE__ */ new Map();
 	env;
-	constructor(env) {
+	limits;
+	helper;
+	constructor(env, limits = DEFAULT_FRAME_LIMITS, helper = () => null) {
 		this.env = env;
+		this.limits = limits;
+		this.helper = helper;
+	}
+	subscribe(device, listener, hint = DEFAULT_FRAME_HINT) {
+		const helper = this.helper();
+		if (helper === null || device.platform === "ios" && device.foldable) return this.screenshots(device).add(listener);
+		let streamed = false;
+		let cancelled = false;
+		const { video } = listener;
+		let detach = this.stream(helper, device).add({
+			frame: (frame) => {
+				streamed = true;
+				listener.frame(frame);
+			},
+			...video ? { video: (unit) => {
+				streamed = true;
+				video(unit);
+			} } : {},
+			delayed: listener.delayed,
+			failed: (message) => {
+				if (streamed || cancelled) return listener.failed(message);
+				console.error(`stim-server: ${message} Falling back to screenshots.`);
+				detach = this.screenshots(device).add(listener);
+			}
+		}, hint);
+		return () => {
+			cancelled = true;
+			detach();
+		};
+	}
+	/** Makes the next video frame of `device` a keyframe, for a subscriber whose decoder lost its state. */
+	keyframe(device) {
+		this.helperSource(device)?.keyframe();
+	}
+	/** A subscriber of `device` is behind; called until its socket drains, it lowers the shared bitrate. */
+	congested(device) {
+		this.helperSource(device)?.congested();
 	}
-	subscribe(device, listener) {
+	helperSource(device) {
+		const source = this.sources.get(`helper:${deviceKey(device)}`);
+		return source instanceof HelperSource ? source : null;
+	}
+	stream(helper, device) {
+		const key = `helper:${deviceKey(device)}`;
+		const existing = this.sources.get(key);
+		if (existing instanceof HelperSource) return existing;
+		const created = new HelperSource(helper, device, this.env, () => {
+			if (this.sources.get(key) === created) this.sources.delete(key);
+		});
+		this.sources.set(key, created);
+		return created;
+	}
+	screenshots(device) {
 		const key = deviceKey(device);
-		let source = this.sources.get(key);
-		if (!source) {
-			const created = new FrameSource(device.platform === "ios" ? simulatorCapturer(device.udid, this.env) : emulatorCapturer(device.serial, this.env), this.limiter, () => {
-				if (this.sources.get(key) === created) this.sources.delete(key);
-			});
-			this.sources.set(key, created);
-			source = created;
-		}
-		return source.add(listener);
+		const existing = this.sources.get(key);
+		if (existing instanceof FrameSource) return existing;
+		const created = new FrameSource(device.platform === "ios" ? simulatorCapturer(device, this.env, this.limits, this.litPanels) : emulatorCapturer(device.serial, this.env, this.limits), this.limiter, this.limits, () => {
+			if (this.sources.get(key) === created) this.sources.delete(key);
+		});
+		this.sources.set(key, created);
+		return created;
 	}
 	async close() {
 		await Promise.all([...this.sources.values()].map((source) => source.stop()));
@@ -911,9 +1558,203 @@ var LogBatcher = class {
 	}
 };
 //#endregion
+//#region src/machine.ts
+function stimDiskLocations() {
+	let workspaces = [];
+	try {
+		workspaces = Object.keys(loadConfig()?.projects ?? {});
+	} catch {}
+	return [
+		...workspaces.map((path) => ({
+			label: "Workspaces",
+			path
+		})),
+		{
+			label: "Stim home",
+			path: configDir()
+		},
+		...process.platform === "darwin" ? [{
+			label: "Simulators",
+			path: join(homedir(), "Library", "Developer", "CoreSimulator")
+		}] : []
+	];
+}
+function existingAncestor(path) {
+	let current = path;
+	while (!existsSync(current) && dirname(current) !== current) current = dirname(current);
+	return current;
+}
+function mountOf(path) {
+	return /^\/Volumes\/[^/]+/.exec(path)?.[0] ?? "/";
+}
+function readVolumes(locations) {
+	const byDevice = /* @__PURE__ */ new Map();
+	for (const { label, path } of locations) try {
+		const existing = existingAncestor(path);
+		const device = statSync(existing).dev;
+		const known = byDevice.get(device);
+		if (known) {
+			if (!known.holds.includes(label)) known.holds.push(label);
+			continue;
+		}
+		const fs = statfsSync(existing);
+		byDevice.set(device, {
+			mount: mountOf(existing),
+			holds: [label],
+			freeBytes: fs.bavail * fs.bsize,
+			totalBytes: fs.blocks * fs.bsize
+		});
+	} catch {}
+	return [...byDevice.values()];
+}
+function readMemoryPressure() {
+	if (process.platform !== "darwin") return Promise.resolve(null);
+	return new Promise((resolve) => {
+		execFile("/usr/sbin/sysctl", ["-n", "kern.memorystatus_vm_pressure_level"], { timeout: 2e3 }, (error, stdout) => {
+			const level = error ? "" : stdout.trim();
+			resolve(level === "1" ? "normal" : level === "2" ? "warning" : level === "4" ? "critical" : null);
+		});
+	});
+}
+/**
+* Activity Monitor's "Memory Used" from `vm_stat` output: app memory (anonymous minus purgeable pages),
+* wired, and compressed pages, times the page size its header names. Null when a count is missing.
+*/
+function parseVmStatUsedBytes(output) {
+	const pageSize = /page size of (\d+) bytes/.exec(output)?.[1];
+	const count = (label) => {
+		const value = new RegExp(`^${label}:\\s+(\\d+)\\.`, "m").exec(output)?.[1];
+		return value === void 0 ? null : Number(value);
+	};
+	const anonymous = count("Anonymous pages");
+	const purgeable = count("Pages purgeable");
+	const wired = count("Pages wired down");
+	const compressed = count("Pages occupied by compressor");
+	if (!pageSize || anonymous === null || purgeable === null || wired === null || compressed === null) return null;
+	return (Math.max(0, anonymous - purgeable) + wired + compressed) * Number(pageSize);
+}
+function readMemoryUsed() {
+	if (process.platform !== "darwin") return Promise.resolve(null);
+	return new Promise((resolve) => {
+		execFile("/usr/bin/vm_stat", { timeout: 2e3 }, (error, stdout) => {
+			resolve(error ? null : parseVmStatUsedBytes(stdout));
+		});
+	});
+}
+function cpuTicks(list) {
+	let idle = 0;
+	let total = 0;
+	for (const cpu of list) {
+		idle += cpu.times.idle;
+		total += cpu.times.user + cpu.times.nice + cpu.times.sys + cpu.times.irq + cpu.times.idle;
+	}
+	return {
+		idle,
+		total
+	};
+}
+/** The busy fraction (0..1) between two `os.cpus()` tick totals. Null when the totals did not advance. */
+function cpuUsageFraction(previous, current) {
+	const totalDelta = current.total - previous.total;
+	if (totalDelta <= 0) return null;
+	const idleDelta = current.idle - previous.idle;
+	return Math.min(1, Math.max(0, 1 - idleDelta / totalDelta));
+}
+let previousCpuTicks = null;
+function readCpuUsage() {
+	const current = cpuTicks(cpus());
+	const usage = previousCpuTicks ? cpuUsageFraction(previousCpuTicks, current) : null;
+	previousCpuTicks = current;
+	return {
+		usage,
+		cores: availableParallelism()
+	};
+}
+async function readMachineUsage() {
+	const [avg1 = 0, avg5 = 0, avg15 = 0] = loadavg();
+	const [pressure, usedBytes] = await Promise.all([readMemoryPressure(), readMemoryUsed()]);
+	return {
+		volumes: readVolumes(stimDiskLocations()),
+		memory: {
+			totalBytes: totalmem(),
+			usedBytes,
+			pressure
+		},
+		load: {
+			avg1,
+			avg5,
+			avg15,
+			cpus: availableParallelism()
+		},
+		cpu: readCpuUsage(),
+		sampledAt: (/* @__PURE__ */ new Date()).toISOString()
+	};
+}
+const PRESSURE_LEVEL = {
+	normal: 0,
+	warning: 1,
+	critical: 2
+};
+const HISTORY_INTERVAL_MS = 5e3;
+const HISTORY_CAPACITY = 720;
+var UsageSampler = class {
+	samples = [];
+	previousTicks = null;
+	timer = null;
+	intervalMs;
+	capacity;
+	constructor(intervalMs = HISTORY_INTERVAL_MS, capacity = HISTORY_CAPACITY) {
+		this.intervalMs = intervalMs;
+		this.capacity = capacity;
+	}
+	start() {
+		if (this.timer) return;
+		this.previousTicks = cpuTicks(cpus());
+		this.timer = setInterval(() => void this.sample(), this.intervalMs);
+	}
+	stop() {
+		if (this.timer) clearInterval(this.timer);
+		this.timer = null;
+		this.previousTicks = null;
+	}
+	record(sample) {
+		this.samples.push(sample);
+		if (this.samples.length > this.capacity) this.samples.splice(0, this.samples.length - this.capacity);
+	}
+	history(sinceMs) {
+		const samples = sinceMs === void 0 ? [...this.samples] : this.samples.filter((s) => s.at > sinceMs);
+		return {
+			intervalMs: this.intervalMs,
+			samples
+		};
+	}
+	async sample() {
+		const at = Date.now();
+		const ticks = cpuTicks(cpus());
+		const cpu = this.previousTicks ? cpuUsageFraction(this.previousTicks, ticks) : null;
+		this.previousTicks = ticks;
+		const [pressure, memoryUsedBytes] = await Promise.all([readMemoryPressure(), readMemoryUsed()]);
+		let diskFreeBytes = null;
+		try {
+			const fs = statfsSync("/");
+			diskFreeBytes = fs.bavail * fs.bsize;
+		} catch {}
+		if (!this.timer) return;
+		this.record({
+			at,
+			cpu,
+			memoryUsedBytes,
+			memoryPressure: pressure === null ? null : PRESSURE_LEVEL[pressure],
+			diskFreeBytes
+		});
+	}
+};
+//#endregion
 //#region src/tailscale.ts
 const MAC_APP_BINARY = "/Applications/Tailscale.app/Contents/MacOS/Tailscale";
 const TIMEOUT_MS = 3e3;
+/** The tailnet-only HTTPS port the setup command serves stim-server on. */
+const SERVE_PORT = 7443;
 function executable(path) {
 	try {
 		accessSync(path, constants.X_OK);
@@ -967,6 +1808,124 @@ function tailscaleStatus(binary, env) {
 		};
 	}
 }
+function reaches(address, target, hosts) {
+	if (typeof address !== "string") return null;
+	let url;
+	try {
+		url = new URL(address.includes("://") ? address : `tcp://${address}`);
+	} catch {
+		return null;
+	}
+	return hosts.has(url.hostname) && url.port === String(target) ? url : null;
+}
+function portOf(hostPort) {
+	return Number(hostPort.slice(hostPort.lastIndexOf(":") + 1));
+}
+/**
+* Reads `tailscale serve status --json`, an ipn.ServeConfig: `TCP` maps a port to `{ HTTPS }` or
+* `{ TCPForward }`, `Web` maps `<host>:<port>` to `{ Handlers: { <mount>: { Proxy } } }`,
+* `AllowFunnel` maps `<host>:<port>` to true, and `Foreground` holds the same shape per
+* foreground session. Any handler or TCP forward that reaches the server on a Funnel port exposes
+* it; only a `/` HTTP proxy on an HTTPS port is a route a client can use.
+*/
+function parseServeStatus(value, target, ips) {
+	if (!isJsonObject(value)) return {
+		state: "unknown",
+		reason: "it printed no serve config",
+		port: SERVE_PORT
+	};
+	const hosts = /* @__PURE__ */ new Set([
+		"127.0.0.1",
+		"localhost",
+		"[::1]",
+		"0.0.0.0",
+		"[::]",
+		...ips.map((ip) => ip.includes(":") ? `[${ip}]` : ip)
+	]);
+	const configs = [value, ...isJsonObject(value.Foreground) ? Object.values(value.Foreground) : []].filter(isJsonObject);
+	const used = /* @__PURE__ */ new Set();
+	const funneled = /* @__PURE__ */ new Set();
+	const reaching = /* @__PURE__ */ new Set();
+	const routes = /* @__PURE__ */ new Set();
+	for (const config of configs) {
+		const tcp = isJsonObject(config.TCP) ? config.TCP : {};
+		for (const [port, listener] of Object.entries(tcp)) {
+			used.add(Number(port));
+			if (isJsonObject(listener) && reaches(listener.TCPForward, target, hosts)) reaching.add(Number(port));
+		}
+		for (const [hostPort, allowed] of Object.entries(isJsonObject(config.AllowFunnel) ? config.AllowFunnel : {})) if (allowed === true) funneled.add(portOf(hostPort));
+		for (const [hostPort, web] of Object.entries(isJsonObject(config.Web) ? config.Web : {})) {
+			const port = portOf(hostPort);
+			const listener = tcp[String(port)];
+			const https = isJsonObject(listener) && listener.HTTPS === true;
+			const handlers = isJsonObject(web) && isJsonObject(web.Handlers) ? web.Handlers : {};
+			for (const [mount, handler] of Object.entries(handlers)) {
+				const url = isJsonObject(handler) ? reaches(handler.Proxy, target, hosts) : null;
+				if (!url) continue;
+				reaching.add(port);
+				if (https && mount === "/" && url.protocol === "http:" && url.pathname === "/") routes.add(port);
+			}
+		}
+	}
+	let free = SERVE_PORT;
+	while (used.has(free) || funneled.has(free)) free++;
+	const exposed = [...reaching].filter((port) => funneled.has(port)).toSorted((a, b) => a - b);
+	if (exposed.length) return {
+		state: "funneled",
+		ports: exposed,
+		port: free
+	};
+	const tailnet = [...routes].toSorted((a, b) => a - b);
+	if (tailnet.length) return {
+		state: "routed",
+		port: tailnet.includes(SERVE_PORT) ? SERVE_PORT : tailnet[0]
+	};
+	return {
+		state: "missing",
+		port: free
+	};
+}
+function serveRoute(binary, env, target, ips, timeoutMs = TIMEOUT_MS) {
+	if (!binary) return Promise.resolve({
+		state: "unknown",
+		reason: "the tailscale command was not found",
+		port: SERVE_PORT
+	});
+	return new Promise((resolve) => {
+		execFile(binary, [
+			"serve",
+			"status",
+			"--json"
+		], {
+			env,
+			timeout: timeoutMs,
+			killSignal: "SIGKILL",
+			encoding: "utf8"
+		}, (error, stdout) => {
+			let route;
+			try {
+				route = error ? {
+					state: "unknown",
+					reason: error.killed ? "it timed out" : error.message.split("\n")[0],
+					port: SERVE_PORT
+				} : parseServeStatus(stdout.trim() ? JSON.parse(stdout) : {}, target, ips);
+			} catch {
+				route = {
+					state: "unknown",
+					reason: "it printed output that is not JSON",
+					port: SERVE_PORT
+				};
+			}
+			resolve(route);
+		});
+	});
+}
+function tailnetEndpoint(dnsName, port) {
+	return port === 443 ? `wss://${dnsName}` : `wss://${dnsName}:${port}`;
+}
+function serveCommand(port, target) {
+	return `tailscale serve --bg --https=${port} http://127.0.0.1:${target}`;
+}
 /** Reads `tailscale whois --json`: the peer's node (`Node.StableID`, `Node.Name`) and user (`UserProfile.LoginName`). */
 function parseWhois(value) {
 	if (!isJsonObject(value) || !isJsonObject(value.Node)) return null;
@@ -1032,8 +1991,9 @@ const LOG_LIMITS = {
 	maxBufferedBytes: 4194304,
 	maxPendingRecords: 2e4
 };
-const FRAME_BUFFER_BYTES = 1048576;
-const FRAME_RETRY_MS = 100;
+const FRAME_BUFFER_FRAMES = 2;
+const FRAME_RETRY_MS = 50;
+const HELPER_RETRY_MS = 3e5;
 const STATUS_FEED = {
 	args: [
 		"status",
@@ -1044,10 +2004,18 @@ const STATUS_FEED = {
 	keep: 1,
 	label: "stim status --watch"
 };
+const HEALTH_ROUTE_TIMEOUT_MS = 1e3;
 const COMMAND_LIMITS = {
 	timeoutMs: 6e4,
 	maxOutputBytes: 33554432
 };
+const PLAN_TIMEOUT_MS = 15e4;
+const SLOT_NAME = /^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/;
+const AUDIT_FIELD_CHARS = 256;
+const ACTION_LIMITS = {
+	timeoutMs: 12e4,
+	maxOutputBytes: 1048576
+};
 const AUTH_REFUSALS = {
 	"pairing-unknown": {
 		code: "pairing-expired",
@@ -1106,11 +2074,62 @@ function send(socket, message) {
 function requestId(value) {
 	return typeof value === "number" || typeof value === "string" ? value : null;
 }
+function registeredWorkspace(workspace) {
+	if (typeof workspace !== "string") return {
+		code: "bad-request",
+		message: "params.workspace must be an environment path from a status payload."
+	};
+	let projects;
+	try {
+		projects = loadConfig()?.projects ?? {};
+	} catch (cause) {
+		return {
+			code: "stim-failed",
+			message: cause.message
+		};
+	}
+	const dir = Object.keys(projects).find((path) => path === workspace);
+	if (dir === void 0) return {
+		code: "unknown-workspace",
+		message: `${workspace} is not a Stim workspace on this Mac.`
+	};
+	if (!existsSync(dir)) return {
+		code: "unknown-workspace",
+		message: `${dir} is registered but no longer exists on this Mac.`
+	};
+	return { dir };
+}
 async function startServer(options) {
 	const limiter = new FailureLimiter(options.maxAuthFailures ?? 5, options.failureWindowMs ?? 6e4);
 	const authTimeoutMs = options.authTimeoutMs ?? 5e3;
 	const feeds = new FeedPool(options.stimCli, options.env);
-	const frames = new FramePool(options.env);
+	const frameLimits = {
+		...DEFAULT_FRAME_LIMITS,
+		...options.frameLimits
+	};
+	let helperPath = options.frameHelper ?? null;
+	let helperBuilding = false;
+	let helperRetryAt = 0;
+	const helperAbort = new AbortController();
+	const buildHelper = () => {
+		helperBuilding = true;
+		(async () => {
+			try {
+				helperPath = await buildFrameHelper(options.env, helperAbort.signal);
+			} catch (cause) {
+				helperRetryAt = Date.now() + HELPER_RETRY_MS;
+				if (!helperAbort.signal.aborted) console.error(`stim-server: frames come from screenshots: ${cause.message}`);
+			} finally {
+				helperBuilding = false;
+			}
+		})();
+	};
+	const frameHelper = () => {
+		if (options.frameHelper === void 0 && !helperPath && !helperBuilding && Date.now() >= helperRetryAt) buildHelper();
+		return helperPath;
+	};
+	if (options.frameHelper === void 0) buildHelper();
+	const frames = new FramePool(options.env, frameLimits, frameHelper);
 	const running = /* @__PURE__ */ new Set();
 	const logLimits = {
 		...LOG_LIMITS,
@@ -1120,7 +2139,13 @@ async function startServer(options) {
 		...COMMAND_LIMITS,
 		...options.commandLimits
 	};
+	const actionLimits = {
+		...ACTION_LIMITS,
+		...options.actionLimits
+	};
+	const busyWorkspaces = /* @__PURE__ */ new Set();
 	const sessions = /* @__PURE__ */ new Map();
+	const sampler = new UsageSampler();
 	const wss = new WebSocketServer({
 		noServer: true,
 		maxPayload: MAX_PAYLOAD
@@ -1140,6 +2165,7 @@ async function startServer(options) {
 	function connection(socket, peer) {
 		const limitKey = peer ?? "local";
 		const subscriptions = /* @__PURE__ */ new Map();
+		const keyframes = /* @__PURE__ */ new Map();
 		const commands = /* @__PURE__ */ new Set();
 		let nextSubscription = 1;
 		let device = null;
@@ -1188,6 +2214,7 @@ async function startServer(options) {
 			}
 			device = outcome.device;
 			sessions.set(socket, device);
+			sampler.start();
 			send(socket, {
 				id,
 				result: {
@@ -1195,9 +2222,11 @@ async function startServer(options) {
 					server: {
 						name: options.name,
 						version: options.serverVersion,
-						stim: options.stimVersion
+						stim: options.stimVersion,
+						home: homedir()
 					},
 					capabilities: device.capabilities,
+					actions: device.capabilities.includes("control") ? [...ACTIONS] : [],
 					device: {
 						id: device.id,
 						name: device.name
@@ -1217,28 +2246,14 @@ async function startServer(options) {
 		}
 		function workspaceDir(id, workspace, required) {
 			if (workspace === void 0 && !required) return homedir();
-			if (typeof workspace !== "string") {
-				error(id, "bad-request", "params.workspace must be an environment path from a status payload.");
+			const resolved = registeredWorkspace(workspace);
+			if ("code" in resolved) {
+				error(id, resolved.code, resolved.message);
 				return null;
 			}
-			let registered;
-			try {
-				registered = Object.hasOwn(loadConfig()?.projects ?? {}, workspace);
-			} catch (cause) {
-				error(id, "stim-failed", cause.message);
-				return null;
-			}
-			if (!registered) {
-				error(id, "unknown-workspace", `${workspace} is not a Stim workspace on this Mac.`);
-				return null;
-			}
-			if (!existsSync(workspace)) {
-				error(id, "unknown-workspace", `${workspace} is registered but no longer exists on this Mac.`);
-				return null;
-			}
-			return workspace;
+			return resolved.dir;
 		}
-		function openSubscription(id) {
+		function openSubscription(id, result = {}) {
 			if (subscriptions.size >= MAX_SUBSCRIPTIONS) {
 				error(id, "limit-exceeded", `A connection can hold ${MAX_SUBSCRIPTIONS} subscriptions.`);
 				return null;
@@ -1246,7 +2261,10 @@ async function startServer(options) {
 			const subscription = `s${nextSubscription++}`;
 			send(socket, {
 				id,
-				result: { subscription }
+				result: {
+					subscription,
+					...result
+				}
 			});
 			return subscription;
 		}
@@ -1330,31 +2348,59 @@ async function startServer(options) {
 			});
 		}
 		function subscribeFrames(id, params) {
-			const { workspace, platform, slot } = isJsonObject(params) ? params : {};
+			const { workspace, platform, slot, fps, maxEdge, video } = isJsonObject(params) ? params : {};
 			if (typeof workspace !== "string" || platform !== "ios" && platform !== "android") return error(id, "bad-request", "frames.subscribe needs params.workspace and params.platform (ios or android).");
 			if (slot !== void 0 && (typeof slot !== "string" || slot === "")) return error(id, "bad-request", "slot must be a slot name.");
+			if (video !== void 0 && (!Array.isArray(video) || !video.every((codec) => typeof codec === "string"))) return error(id, "bad-request", "video must be a list of codec names.");
+			const wantsVideo = video?.includes("h264") === true;
+			const offersVideo = wantsVideo && frameHelper() !== null;
+			const maxFps = wantsVideo ? FRAME_FPS.video : FRAME_FPS.max;
+			if (fps !== void 0 && (!Number.isInteger(fps) || fps < 1 || fps > maxFps)) return error(id, "bad-request", `fps must be a whole number from 1 to ${maxFps}.`);
+			if (maxEdge !== void 0 && (!Number.isInteger(maxEdge) || maxEdge < FRAME_EDGE.min || maxEdge > FRAME_EDGE.max)) return error(id, "bad-request", `maxEdge must be a whole number of pixels from ${FRAME_EDGE.min} to ${FRAME_EDGE.max}.`);
+			const hint = {
+				fps: Math.min(fps ?? FRAME_FPS.default, offersVideo ? FRAME_FPS.video : FRAME_FPS.max),
+				maxEdge: maxEdge ?? FRAME_EDGE.default
+			};
 			if (!workspaceDir(id, workspace, true)) return;
-			const subscription = openSubscription(id);
+			const subscription = openSubscription(id, offersVideo ? { video: "h264" } : {});
 			if (!subscription) return;
 			const frameTarget = {
 				workspace,
 				platform,
 				...slot ? { slot } : {}
 			};
+			const gate = new VideoGate(DEFAULT_VIDEO_LIMITS.congestedBytes);
+			let sequence = 0;
+			let streamed = null;
+			let draining = null;
+			const drain = () => {
+				draining = null;
+				if (ended || !streamed) return;
+				if (socket.bufferedAmount <= DEFAULT_VIDEO_LIMITS.congestedBytes) return frames.keyframe(streamed);
+				frames.congested(streamed);
+				draining = setTimeout(drain, FRAME_RETRY_MS);
+			};
 			let attached = null;
 			let detach = null;
 			let pending = null;
 			let retry = null;
 			let ended = false;
+			let sentAt = 0;
 			const flush = () => {
 				retry = null;
 				if (!pending || ended) return;
-				if (socket.bufferedAmount > FRAME_BUFFER_BYTES) {
+				const wait = sentAt + 1e3 / hint.fps - Date.now();
+				if (wait > 0) {
+					retry = setTimeout(flush, wait);
+					return;
+				}
+				if (socket.bufferedAmount > FRAME_BUFFER_FRAMES * pending.data.length) {
 					retry = setTimeout(flush, FRAME_RETRY_MS);
 					return;
 				}
 				const frame = pending;
 				pending = null;
+				sentAt = Date.now();
 				send(socket, {
 					event: "frame",
 					subscription,
@@ -1366,7 +2412,9 @@ async function startServer(options) {
 			};
 			const cleanup = () => {
 				ended = true;
+				keyframes.delete(subscription);
 				if (retry) clearTimeout(retry);
+				if (draining) clearTimeout(draining);
 				detach?.();
 				detach = null;
 				unsubscribeStatus?.();
@@ -1389,8 +2437,25 @@ async function startServer(options) {
 					pending = frame;
 					if (!retry) flush();
 				},
-				failed: end
+				delayed: (delayed) => {
+					if (!ended) send(socket, {
+						event: "frame-delayed",
+						subscription,
+						delayed
+					});
+				},
+				failed: end,
+				...offersVideo ? { video: (unit) => {
+					if (ended || socket.readyState !== socket.OPEN) return;
+					const verdict = gate.admit(unit, socket.bufferedAmount);
+					if (verdict === "send") socket.send(videoPacket(subscription, sequence++, unit));
+					else if (verdict === "congested" && !draining) drain();
+				} } : {}
 			};
+			if (offersVideo) keyframes.set(subscription, () => {
+				gate.reset();
+				if (streamed) frames.keyframe(streamed);
+			});
 			let unsubscribeStatus = null;
 			unsubscribeStatus = feeds.subscribe(STATUS_FEED, {
 				item: (payload) => {
@@ -1399,23 +2464,28 @@ async function startServer(options) {
 					if (typeof resolved === "string") return queueMicrotask(() => end(resolved));
 					if (deviceKey(resolved) === attached) return;
 					detach?.();
+					gate.reset();
+					streamed = resolved;
 					attached = deviceKey(resolved);
-					detach = frames.subscribe(resolved, listener);
+					detach = frames.subscribe(resolved, listener, hint);
 				},
 				failed: (message) => queueMicrotask(() => end(message))
 			});
 			subscriptions.set(subscription, cleanup);
 		}
-		function command(id, args, cwd, result) {
+		function command(id, args, cwd, result, limits = commandLimits) {
 			if (commands.size >= MAX_COMMANDS) return error(id, "limit-exceeded", `A connection can run ${MAX_COMMANDS} requests at a time.`);
-			const run = runStim(options.stimCli, options.env, args, cwd, commandLimits);
+			const run = runStim(options.stimCli, options.env, args, cwd, limits);
 			commands.add(run.cancel);
 			running.add(run.cancel);
 			(async () => {
 				const outcome = await run.outcome;
 				commands.delete(run.cancel);
 				running.delete(run.cancel);
-				if (!outcome.ok) return error(id, "stim-failed", outcome.message);
+				if (!outcome.ok) {
+					const printed = actionOutcome(outcome);
+					return error(id, "stim-failed", printed.ok ? outcome.message : printed.error.message);
+				}
 				let value;
 				try {
 					value = result(outcome.stdout);
@@ -1445,6 +2515,118 @@ async function startServer(options) {
 				return value;
 			});
 		}
+		function runAction(id, params, session) {
+			const startedAt = Date.now();
+			const raw = isJsonObject(params) ? params : {};
+			const clip = (value) => typeof value === "string" ? value.slice(0, AUDIT_FIELD_CHARS) : null;
+			const record = {
+				at: new Date(startedAt).toISOString(),
+				device: {
+					id: session.id,
+					name: session.name
+				},
+				action: clip(raw.action),
+				workspace: clip(raw.workspace),
+				...typeof raw.platform === "string" ? { platform: clip(raw.platform) } : {},
+				ok: false
+			};
+			const audit = (outcome) => {
+				const logged = outcome.error ? {
+					...outcome.error,
+					message: clip(outcome.error.message)
+				} : void 0;
+				try {
+					appendAudit({
+						...record,
+						...outcome,
+						...logged ? { error: logged } : {}
+					});
+				} catch (cause) {
+					console.error(`stim-server: could not append to the action log: ${cause.message}`);
+				}
+			};
+			const refuseAction = (code, message) => {
+				audit({
+					ok: false,
+					error: {
+						code,
+						message
+					}
+				});
+				error(id, code, message);
+			};
+			if (!readDevices().find((entry) => entry.id === session.id)?.capabilities.includes("control")) return refuseAction("forbidden", `This device can only read. On the Mac, run \`stim-server devices grant ${session.id} --control\` to let it run actions.`);
+			const parsed = parseAction(params);
+			if ("code" in parsed) return refuseAction(parsed.code, parsed.message);
+			const { action } = parsed;
+			const resolved = registeredWorkspace(action.workspace);
+			if ("code" in resolved) return refuseAction(resolved.code, resolved.message);
+			if (busyWorkspaces.has(resolved.dir)) return refuseAction("action-busy", `An action is already running in ${resolved.dir}. Try again when it finishes.`);
+			let run;
+			try {
+				run = runStim(options.stimCli, options.env, actionArgs(action), resolved.dir, actionLimits);
+			} catch (cause) {
+				return refuseAction("action-failed", `stim ${action.action} could not start (${cause.message}).`);
+			}
+			busyWorkspaces.add(resolved.dir);
+			let finished = false;
+			const finish = (outcome) => {
+				if (finished) return;
+				finished = true;
+				running.delete(cancel);
+				busyWorkspaces.delete(resolved.dir);
+				audit({
+					ok: outcome.ok,
+					...outcome.ok ? {} : { error: outcome.error },
+					durationMs: Date.now() - startedAt
+				});
+				if (outcome.ok) send(socket, {
+					id,
+					result: {
+						action: action.action,
+						workspace: resolved.dir,
+						output: outcome.output
+					}
+				});
+				else send(socket, {
+					id,
+					error: outcome.error
+				});
+			};
+			const cancel = async () => {
+				finish({
+					ok: false,
+					error: {
+						code: "action-failed",
+						message: "stim-server stopped before the action finished."
+					}
+				});
+				await run.cancel();
+			};
+			running.add(cancel);
+			run.outcome.then((outcome) => finish(actionOutcome(outcome)));
+		}
+		function planBuild(id, params) {
+			if (!isJsonObject(params)) return error(id, "bad-request", "params must be an object.");
+			const { platform, slot } = params;
+			if (platform !== "ios" && platform !== "android") return error(id, "bad-request", "params.platform must be ios or android.");
+			if (slot !== void 0 && (typeof slot !== "string" || !SLOT_NAME.test(slot))) return error(id, "bad-request", "params.slot must be 1-64 letters, digits, underscores or hyphens.");
+			const cwd = workspaceDir(id, params.workspace, true);
+			if (!cwd) return;
+			command(id, [
+				platform,
+				"--plan",
+				"--json",
+				...slot === void 0 ? [] : [`--slot=${slot}`]
+			], cwd, (stdout) => {
+				const value = JSON.parse(stdout);
+				if (!isJsonObject(value) || value.platform !== platform) throw new Error("not a plan");
+				return value;
+			}, {
+				...commandLimits,
+				timeoutMs: options.commandLimits?.timeoutMs ?? PLAN_TIMEOUT_MS
+			});
+		}
 		async function handle(raw) {
 			if (socket.readyState !== socket.OPEN) return;
 			let message;
@@ -1470,7 +2652,38 @@ async function startServer(options) {
 			if (message.method === "logs.subscribe") return subscribeLogs(id, message.params);
 			if (message.method === "logs.query") return queryLogs(id, message.params);
 			if (message.method === "frames.subscribe") return subscribeFrames(id, message.params);
+			if (message.method === "frames.keyframe") {
+				const name = isJsonObject(message.params) ? message.params.subscription : void 0;
+				const keyframe = typeof name === "string" ? keyframes.get(name) : void 0;
+				if (!keyframe) return send(socket, {
+					id,
+					error: {
+						code: "unknown-subscription",
+						message: `No video subscription ${String(name)}.`
+					}
+				});
+				keyframe();
+				return send(socket, {
+					id,
+					result: {}
+				});
+			}
+			if (message.method === "build.plan") return planBuild(id, message.params);
+			if (message.method === "machine.get") return send(socket, {
+				id,
+				result: await readMachineUsage()
+			});
+			if (message.method === "machine.history") {
+				const params = message.params ?? {};
+				const sinceMs = isJsonObject(params) ? params.sinceMs : void 0;
+				if (!isJsonObject(params) || sinceMs !== void 0 && typeof sinceMs !== "number") return error(id, "bad-request", "machine.history takes an optional numeric sinceMs.");
+				return send(socket, {
+					id,
+					result: sampler.history(sinceMs)
+				});
+			}
 			if (message.method === "stats.get" || message.method === "settings.get") return workspaceCommand(id, message.method, message.params);
+			if (message.method === "action") return runAction(id, message.params, device);
 			if (message.method === "unsubscribe") {
 				const name = isJsonObject(message.params) ? message.params.subscription : void 0;
 				const unsubscribe = typeof name === "string" ? subscriptions.get(name) : void 0;
@@ -1503,6 +2716,7 @@ async function startServer(options) {
 		socket.on("close", () => {
 			clearTimeout(timer);
 			sessions.delete(socket);
+			if (sessions.size === 0) sampler.stop();
 			for (const unsubscribe of subscriptions.values()) unsubscribe();
 			subscriptions.clear();
 			for (const cancel of commands) {
@@ -1529,10 +2743,20 @@ async function startServer(options) {
 		stimHome: configDir(),
 		tailscale: healthTailscale(options.tailscaleState)
 	};
+	const answerHealth = async (response) => {
+		const tailscale = options.tailscaleState;
+		const route = tailscale.state === "running" && tailscale.dnsName ? await serveRoute(options.tailscale, options.env, addresses[0].port, tailscale.ips, HEALTH_ROUTE_TIMEOUT_MS) : void 0;
+		response.writeHead(200, { "content-type": "application/json" }).end(JSON.stringify({
+			...health,
+			route
+		}));
+	};
 	const servers = [];
 	const addresses = [];
 	const close = async () => {
 		watcher.close();
+		helperAbort.abort();
+		sampler.stop();
 		if (revocationCheck) clearTimeout(revocationCheck);
 		for (const client of wss.clients) client.terminate();
 		await Promise.all([
@@ -1547,7 +2771,7 @@ async function startServer(options) {
 		for (const host of options.hosts) {
 			const server = createServer((request, response) => {
 				if (localHealthRequest(request)) {
-					response.writeHead(200, { "content-type": "application/json" }).end(JSON.stringify(health));
+					answerHealth(response);
 					return;
 				}
 				response.writeHead(426, { "content-type": "text/plain" }).end("stim-server speaks WebSocket only.\n");
@@ -1580,22 +2804,32 @@ async function startServer(options) {
 const DEFAULT_PORT = 7787;
 const USAGE = `Usage:
   stim-server [--port <n>]          serve paired clients (default port ${DEFAULT_PORT})
-  stim-server pair [--port <n>] [--json]
-                                    print a single-use pairing payload for the QR code
+  stim-server pair [--port <n>] [--control] [--json]
+                                    print a single-use pairing payload for the QR code;
+                                    --control lets the paired device run actions
   stim-server devices [list] [--json]
                                     list paired devices
-  stim-server devices revoke <id>   revoke a paired device`;
+  stim-server devices grant <id> --control|--read
+                                    let a paired device run actions, or only read
+  stim-server devices revoke <id>   revoke a paired device
+  stim-server log [--json]          list the actions paired devices ran`;
 const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
 function fail(message) {
 	console.error(`stim-server: ${message}`);
 	process.exit(1);
 }
-function tailscaleNote(tailscale, port) {
-	const remedy = `Remote clients cannot connect until Tailscale runs; then restart stim-server and run \`tailscale serve --bg http://127.0.0.1:${port}\` once.`;
+function tailscaleNote(tailscale) {
+	const remedy = `Remote clients cannot connect until Tailscale runs; then restart stim-server, which prints the \`tailscale serve\` command to run once.`;
 	if (tailscale.state === "not-running") return `Tailscale is not running (${tailscale.backendState}). ${remedy}`;
 	if (tailscale.state === "unavailable") return `Tailscale is unavailable: ${tailscale.reason}. ${remedy}`;
 	return null;
 }
+function routeNote(route, port) {
+	if (route.state === "missing") return `No \`tailscale serve\` route reaches port ${port}, so phones cannot connect yet. Run this once to serve it on a tailnet-only port: \`${serveCommand(route.port, port)}\``;
+	if (route.state === "unknown") return `Could not read \`tailscale serve status --json\` (${route.reason}); assuming stim-server is served on port ${route.port}.`;
+	if (route.state === "funneled") return `Tailscale Funnel is on for port ${route.ports.join(", ")}, which proxies to stim-server, so the server is reachable from the public internet. Remove that handler (see \`tailscale serve status\`), then serve stim-server on a tailnet-only port: \`${serveCommand(route.port, port)}\``;
+	return null;
+}
 function macName(tailscale) {
 	return tailscale.state === "running" && tailscale.hostName || hostname();
 }
@@ -1628,8 +2862,13 @@ async function serve(port) {
 	}
 	console.log(`stim-server ${pkg.version} (stim ${stim.version}, protocol 1)`);
 	for (const { host, port: bound } of server.addresses) console.log(`listening on ws://${host.includes(":") ? `[${host}]` : host}:${bound}`);
-	if (tailscale.state === "running" && tailscale.dnsName) console.log(`tailnet endpoint: wss://${tailscale.dnsName}`);
-	const note = tailscaleNote(tailscale, port);
+	let note = tailscaleNote(tailscale);
+	if (tailscale.state === "running" && tailscale.dnsName) {
+		const route = await serveRoute(tailscaleBinary, env, port, tailscale.ips);
+		if (route.state !== "funneled") console.log(`tailnet endpoint: ${tailnetEndpoint(tailscale.dnsName, route.port)}`);
+		note = routeNote(route, port);
+		if (route.state === "funneled") note = `${note} Pairing is refused until then.`;
+	}
 	if (note) console.error(note);
 	const shutdown = () => {
 		server.close().then(() => process.exit(0));
@@ -1638,14 +2877,23 @@ async function serve(port) {
 	process.on("SIGTERM", shutdown);
 	process.on("SIGHUP", shutdown);
 }
-function pair(port, json) {
-	const tailscale = tailscaleStatus(findTailscale(process.env), process.env);
-	const { token, expiresAt } = createPairingToken();
-	const running = tailscale.state === "running";
+async function pair(port, json, control) {
+	const binary = findTailscale(process.env);
+	const tailscale = tailscaleStatus(binary, process.env);
+	let endpoint = `ws://127.0.0.1:${port}`;
+	let note = tailscaleNote(tailscale);
+	if (note) note = `${note} The endpoint above only works on this Mac.`;
+	if (tailscale.state === "running" && tailscale.dnsName) {
+		const route = await serveRoute(binary, process.env, port, tailscale.ips);
+		if (route.state === "funneled") fail(`refusing to pair. ${routeNote(route, port)}`);
+		endpoint = tailnetEndpoint(tailscale.dnsName, route.port);
+		note = routeNote(route, port);
+	}
+	const { token, expiresAt } = createPairingToken(Date.now(), capabilitiesFor(control));
 	const payload = {
 		v: 1,
 		name: macName(tailscale),
-		endpoint: running && tailscale.dnsName ? `wss://${tailscale.dnsName}` : `ws://127.0.0.1:${port}`,
+		endpoint,
 		pairingToken: token
 	};
 	if (json) return void console.log(JSON.stringify({
@@ -1653,13 +2901,13 @@ function pair(port, json) {
 		expiresAt
 	}));
 	console.log(JSON.stringify(payload));
-	console.error(`The pairing token is single use and expires at ${expiresAt}.`);
-	const note = tailscaleNote(tailscale, port);
-	if (note) console.error(`${note} The endpoint above only works on this Mac.`);
+	console.error(`The pairing token is single use and expires at ${expiresAt}. The device it pairs can ${control ? "run actions" : "only read"}.`);
+	if (note) console.error(note);
 }
 function describe(device) {
 	const from = device.identity.kind === "local" ? "this Mac" : `${device.identity.nodeName || device.identity.nodeId}${device.identity.user ? ` (${device.identity.user})` : ""}`;
-	return `${device.id}  ${device.name}  from ${from}  paired ${device.pairedAt}  last seen ${device.lastSeenAt ?? "never"}`;
+	const scope = device.capabilities.includes("control") ? "control" : "read";
+	return `${device.id}  ${device.name}  ${scope}  from ${from}  paired ${device.pairedAt}  last seen ${device.lastSeenAt ?? "never"}`;
 }
 async function main() {
 	const { values, positionals } = parseArgs({
@@ -1667,6 +2915,8 @@ async function main() {
 		options: {
 			port: { type: "string" },
 			json: { type: "boolean" },
+			control: { type: "boolean" },
+			read: { type: "boolean" },
 			help: {
 				type: "boolean",
 				short: "h"
@@ -1683,7 +2933,27 @@ async function main() {
 	if (!Number.isInteger(port) || port < 0 || port > 65535) fail(`--port must be a port number, got ${values.port}.`);
 	const [command, sub, arg, ...rest] = positionals;
 	if (command === void 0) return serve(port);
-	if (command === "pair" && sub === void 0) return pair(port, values.json === true);
+	const grant = command === "devices" && sub === "grant";
+	if (values.read && !grant) fail(`--read applies only to \`devices grant\`.\n${USAGE}`);
+	if (values.control && !grant && command !== "pair") fail(`--control applies only to \`pair\` and \`devices grant\`.\n${USAGE}`);
+	if (command === "pair" && sub === void 0) return pair(port, values.json === true, values.control === true);
+	if (grant && arg !== void 0 && rest.length === 0) {
+		if (values.control === values.read) fail("devices grant takes exactly one of --control or --read.");
+		if (!grantDevice(arg, capabilitiesFor(values.control === true))) fail(`no paired device ${arg}. Run \`stim-server devices\` to list them.`);
+		console.log(`${arg} can now ${values.control ? "run actions" : "only read"}.`);
+		return;
+	}
+	if (command === "log" && sub === void 0) {
+		const records = readAudit();
+		if (values.json) return void console.log(JSON.stringify({ actions: records }));
+		if (!records.length) console.log("No actions.");
+		for (const record of records) {
+			const outcome = record.ok ? "ok" : `${record.error?.code ?? "failed"}: ${record.error?.message ?? ""}`;
+			const line = `${record.at}  ${record.device.id} (${record.device.name})  ${record.action}  ${record.workspace}  ${outcome}`;
+			console.log(Array.from(line, (char) => /\p{Cc}/u.test(char) ? "?" : char).join(""));
+		}
+		return;
+	}
 	if (command === "devices" && (sub === void 0 || sub === "list") && arg === void 0) {
 		const devices = readDevices();
 		if (values.json) {