@stim-cli/server 1.10.1 → 1.12.0

package/dist/stim-server.mjs

@@ -1,19 +1,20 @@
 #!/usr/bin/env node
-import { a as MAX_LOG_TAIL, i as LOG_SOURCES, r as LOG_LEVELS, t as CAPABILITIES } from "./protocol-B3k9Ykuu.mjs";
+import { _ as TOUCH_PHASES, c as INPUT_BUTTONS, f as MAX_LOG_TAIL, g as ROTATE_DIRECTIONS, l as LOG_LEVELS, n as CAPABILITIES, o as FRAME_EDGE, s as FRAME_FPS, t as ACTIONS, u as LOG_SOURCES } from "./protocol-BElQc2vm.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 { connect } from "node:http2";
+import { fileURLToPath } from "node:url";
+import { createInterface } from "node:readline";
 //#region src/environment.ts
 function parseEnvironment(output) {
 	const environment = {};
@@ -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")
 				});
 			});
 		}),
@@ -317,92 +447,387 @@ function runStim(stimCli, env, args, cwd, limits) {
 	};
 }
 //#endregion
-//#region src/feed.ts
-var Feed = class {
-	listeners = /* @__PURE__ */ new Set();
-	kept = [];
+//#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().map((name) => join(sourcesDir, name));
+	if (!sources.length) throw new Error(`${sourcesDir} has no Swift sources.`);
+	return compiled("stim-frames", sources, await run("xcrun", ["swiftc", "--version"], env, VERSION_TIMEOUT_MS, signal), async (output) => {
+		await run("xcrun", [
+			"swiftc",
+			"-O",
+			"-swift-version",
+			"5",
+			"-module-name",
+			"StimFrames",
+			"-o",
+			output,
+			...sources
+		], env, BUILD_TIMEOUT_MS, signal);
+	});
+}
+/**
+* Compiles `sim-fold`, which folds or unfolds an iPhone Duo from inside the simulator, from the Stim Desktop
+* sources shipped in `dist/stim-frames/`, the way Stim Desktop's bundle script builds it.
+*/
+async function buildFoldHelper(env, signal, sourcesDir = SOURCES_DIR) {
+	if (process.platform !== "darwin") throw new Error("sim-fold runs only on macOS.");
+	const source = join(sourcesDir, "sim-fold.m");
+	const entitlements = join(sourcesDir, "sim-fold.entitlements");
+	const clang = [
+		"-sdk",
+		"iphonesimulator",
+		"clang"
+	];
+	const version = await run("xcrun", [...clang, "--version"], env, VERSION_TIMEOUT_MS, signal);
+	return compiled("sim-fold", [source, entitlements], version, async (output) => {
+		await run("xcrun", [
+			...clang,
+			"-fobjc-arc",
+			"-arch",
+			"arm64",
+			"-arch",
+			"x86_64",
+			"-mios-simulator-version-min=18.0",
+			"-framework",
+			"Foundation",
+			source,
+			"-o",
+			output,
+			`-Wl,-sectcreate,__TEXT,__entitlements,${entitlements}`
+		], env, BUILD_TIMEOUT_MS, signal);
+		await run("codesign", [
+			"--force",
+			"--sign",
+			"-",
+			output
+		], env, VERSION_TIMEOUT_MS, signal);
+	});
+}
+async function compiled(name, inputs, version, compile) {
+	const hash = createHash("sha256").update(version);
+	for (const input of inputs) hash.update(basename(input)).update(readFileSync(input));
+	const dir = join(serverDir(), "helpers");
+	const helper = join(dir, `${name}-${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 compile(output);
+		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;
+	keyboard = null;
+	stderr = "";
 	ended;
-	constructor(spec, stimCli, env, ended) {
+	bitrate = new Bitrate(DEFAULT_VIDEO_LIMITS, Date.now());
+	keyframeAt = -Infinity;
+	keyframeTimer = null;
+	constructor(helper, device, env, ended) {
 		this.ended = ended;
-		const child = spawn(process.execPath, [stimCli, ...spec.args], {
-			cwd: spec.cwd,
+		const id = device.platform === "ios" ? device.udid : device.serial;
+		this.child = spawn(helper, [device.platform, id], {
 			env,
 			stdio: [
-				"ignore",
+				"pipe",
 				"pipe",
 				"pipe"
 			]
 		});
-		this.child = child;
-		let stderr = "";
-		child.stderr?.setEncoding("utf8");
-		child.stderr?.on("data", (chunk) => {
-			stderr = (stderr + chunk).slice(-2e3);
+		this.child.stdin.on("error", () => {});
+		this.child.stderr.setEncoding("utf8");
+		this.child.stderr.on("data", (chunk) => {
+			this.stderr = (this.stderr + chunk).slice(-1e3);
 		});
-		createInterface({ input: child.stdout }).on("line", (line) => {
-			if (this.child !== child) return;
-			let value;
-			try {
-				value = JSON.parse(line);
-			} catch {
-				return;
-			}
-			if (!isJsonObject(value)) return;
-			this.kept.push(value);
-			if (this.kept.length > spec.keep) this.kept.shift();
-			for (const listener of this.listeners) listener.item(value);
+		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}` : ""}`);
 		});
-		const exited = (reason) => {
-			if (this.child !== child) return;
-			this.child = null;
-			this.ended();
-			const message = `${spec.label} ${reason}${stderr.trim() ? `: ${stderr.trim()}` : ""}`;
-			const listeners = [...this.listeners];
-			this.listeners.clear();
-			for (const listener of listeners) listener.failed(message);
-		};
-		child.on("error", (error) => exited(`could not start (${error.message})`));
-		child.on("close", (code, signal) => exited(`exited (${signal ?? `code ${code}`})`));
 	}
-	add(listener) {
-		this.listeners.add(listener);
-		for (const value of this.kept) listener.item(value);
+	/** A null `hint` keeps the helper running for input without asking for frames. */
+	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) && this.listeners.size === 0) this.stop();
+			if (!this.listeners.delete(listener)) return;
+			if (this.listeners.size === 0) this.stop();
+			else this.configure();
 		};
 	}
 	stop() {
-		const child = this.child;
-		if (!child) return Promise.resolve();
-		this.child = null;
+		if (this.stopped) return Promise.resolve();
+		this.stopped = true;
+		if (this.keyframeTimer) clearTimeout(this.keyframeTimer);
 		this.listeners.clear();
 		this.ended();
-		return terminate(child);
-	}
-};
-var FeedPool = class {
-	feeds = /* @__PURE__ */ new Map();
-	stimCli;
-	env;
-	constructor(stimCli, env) {
-		this.stimCli = stimCli;
-		this.env = env;
+		this.child.stdin.end();
+		return terminate(this.child);
 	}
-	subscribe(spec, listener) {
-		const key = JSON.stringify([spec.cwd, spec.args]);
-		let feed = this.feeds.get(key);
-		if (!feed) {
-			const created = new Feed(spec, this.stimCli, this.env, () => {
-				if (this.feeds.get(key) === created) this.feeds.delete(key);
-			});
-			this.feeds.set(key, created);
-			feed = created;
+	/** 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;
 		}
-		return feed.add(listener);
+		this.keyframeAt = Date.now();
+		this.child.stdin.write("{\"keyframe\":true}\n");
 	}
-	async close() {
-		await Promise.all([...this.feeds.values()].map((feed) => feed.stop()));
+	congested() {
+		if (this.bitrate.congested(Date.now()) !== null) this.configure();
+	}
+	send(command) {
+		if (!this.stopped) this.child.stdin.write(`${JSON.stringify(command)}\n`);
+	}
+	configure() {
+		const watching = [...this.listeners].flatMap(([listener, hint]) => hint ? [{
+			listener,
+			hint
+		}] : []);
+		const hints = watching.map(({ hint }) => hint);
+		const jpegFps = watching.flatMap(({ listener, hint }) => listener.video ? [] : [hint.fps]);
+		const config = JSON.stringify({
+			fps: Math.max(0, ...hints.map((hint) => hint.fps)),
+			maxEdge: Math.max(FRAME_EDGE.min, ...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 notice = JSON.parse(text);
+			const error = notice?.error;
+			if (typeof error === "string") this.notice = error;
+			const keyboard = notice?.keyboard;
+			if (keyboard === "yes" || keyboard === "no") this.keyboard = keyboard === "yes";
+			const inputError = notice?.inputError;
+			if (typeof inputError === "string") console.error(`stim-server: stim-frames: ${inputError}`);
+		} catch {}
 	}
 };
 //#endregion
@@ -437,7 +862,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;
@@ -523,36 +949,90 @@ 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, limits) {
+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, limits.toolTimeoutMs);
+	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)) {
+			litPanels.set(device.udid, lit);
+			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
@@ -564,6 +1044,18 @@ function simulatorCapturer(udid, env, limits) {
 		}
 	};
 }
+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).
@@ -648,36 +1140,58 @@ 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 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.");
+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));
 }
-function emulatorCapturer(serial, env, limits) {
-	let session = null;
-	let tmp = null;
-	const running = /* @__PURE__ */ new Set();
-	const call = (endpoint) => new Promise((resolve, reject) => {
-		if (!session || session.closed || session.destroyed) {
-			session = connect(`http://127.0.0.1:${endpoint.grpcPort}`);
-			session.on("error", () => {});
+/**
+* `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
+	};
+}
+/**
+* `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 grpcSession(endpoint) {
+	const session = connect(`http://127.0.0.1:${endpoint.grpcPort}`);
+	session.on("error", () => {});
+	return session;
+}
+function grpcCall(session, endpoint, serial, method, requestBody, timeoutMs) {
+	return new Promise((resolve, reject) => {
 		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}` } : {}
@@ -690,7 +1204,7 @@ function emulatorCapturer(serial, env, limits) {
 			if (headers["grpc-status"] !== void 0) status = String(headers["grpc-status"]);
 			if (headers["grpc-message"] !== void 0) message = String(headers["grpc-message"]);
 		};
-		request.setTimeout(limits.toolTimeoutMs, () => {
+		request.setTimeout(timeoutMs, () => {
 			timedOut = true;
 			request.close();
 		});
@@ -698,23 +1212,62 @@ function emulatorCapturer(serial, env, limits) {
 		request.on("trailers", record);
 		request.on("data", (chunk) => chunks.push(chunk));
 		request.on("error", (error) => {
-			const text = `getScreenshot failed on ${serial}: ${error.message}`;
+			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));
-			const text = `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);
 	});
+}
+const POSTURE_MODEL = grpcMessage([8, 16]);
+/**
+* The postures `input.posture` accepts for an owned device: the two panels of an iPhone Duo, and the hinge
+* positions of an emulator whose physical model has a posture.
+*/
+async function devicePostures(device, env, timeoutMs) {
+	if (device.platform === "ios") return device.foldable ? ["folded", "unfolded"] : [];
+	const endpoint = emulatorEndpoint(env, device.serial);
+	if (!endpoint) return [];
+	const session = grpcSession(endpoint);
+	try {
+		return hasHinge(await grpcCall(session, endpoint, device.serial, "getPhysicalModel", POSTURE_MODEL, timeoutMs)) ? [
+			"folded",
+			"half-open",
+			"unfolded"
+		] : [];
+	} catch {
+		return [];
+	} finally {
+		session.close();
+	}
+}
+function emulatorCapturer(serial, env, limits) {
+	let session = null;
+	let tmp = null;
+	const running = /* @__PURE__ */ new Set();
+	let hinged = null;
+	const call = (endpoint, method, requestBody) => {
+		if (!session || session.closed || session.destroyed) session = grpcSession(endpoint);
+		return grpcCall(session, endpoint, serial, method, requestBody, limits.toolTimeoutMs);
+	};
 	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", POSTURE_MODEL).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");
@@ -821,7 +1374,8 @@ 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;
@@ -841,40 +1395,766 @@ var FrameSource = class {
 				return;
 			}
 			const listeners = [...this.listeners];
-			this.stop();
-			for (const listener of listeners) listener.failed(error.message);
-		}
+			this.stop();
+			for (const listener of listeners) listener.failed(error.message);
+		}
+	}
+};
+/**
+* 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;
+	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();
+		};
+	}
+	/** The posture of an iPhone Duo as its last frame showed it; null before a frame and for other devices. */
+	litPosture(device) {
+		const lit = device.platform === "ios" && device.foldable ? this.litPanels.get(device.udid) : void 0;
+		return lit ? POSTURES[lit] : null;
+	}
+	/** Records the panel a finished fold lit, so a request before the next frame sees the new posture. */
+	folded(udid, posture) {
+		this.litPanels.set(udid, posture === "folded" ? "primary" : "primary-1");
+	}
+	/** 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();
+	}
+	helperSource(device) {
+		const source = this.sources.get(`helper:${deviceKey(device)}`);
+		return source instanceof HelperSource ? source : null;
+	}
+	/**
+	* Keeps the device's helper running to send it input, or returns null without a helper. `failed` runs when
+	* the helper exits.
+	*/
+	control(device, failed) {
+		const helper = this.helper();
+		if (helper === null) return null;
+		const source = this.stream(helper, device);
+		return {
+			send: (command) => source.send(command),
+			keys: () => source.keyboard === true,
+			detach: source.add({
+				frame: () => {},
+				delayed: () => {},
+				failed
+			}, 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);
+		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()));
+	}
+};
+//#endregion
+//#region src/control.ts
+const SLOT_NAME = /^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/;
+const TEXT = /^[\x20-\x7e\n\t\b]+$/;
+function parseControlBegin(params) {
+	if (!isJsonObject(params)) return {
+		code: "bad-request",
+		message: "params must be an object."
+	};
+	const { workspace, platform, slot, takeOver, ...rest } = params;
+	if (Object.keys(rest).length) return {
+		code: "bad-request",
+		message: `control.begin does not take ${Object.keys(rest).join(", ")}.`
+	};
+	if (typeof workspace !== "string") return {
+		code: "bad-request",
+		message: "params.workspace must be an environment path from a status payload."
+	};
+	if (platform !== "ios" && platform !== "android") return {
+		code: "bad-request",
+		message: "params.platform must be ios or android."
+	};
+	if (slot !== void 0 && (typeof slot !== "string" || !SLOT_NAME.test(slot))) return {
+		code: "bad-request",
+		message: "params.slot must be 1-64 letters, digits, underscores or hyphens."
+	};
+	if (takeOver !== void 0 && typeof takeOver !== "boolean") return {
+		code: "bad-request",
+		message: "params.takeOver must be true or false."
+	};
+	return { value: {
+		workspace,
+		platform,
+		...slot ? { slot } : {},
+		...takeOver ? { takeOver } : {}
+	} };
+}
+const IOS_BUTTONS = ["home", "lock"];
+function fraction(value) {
+	return typeof value === "number" && value >= 0 && value <= 1;
+}
+/** Validates an `input.*` request for one of the connection's sessions; returns its session id and command. */
+function parseInput(method, params, targetOf) {
+	if (!isJsonObject(params) || typeof params.session !== "string") return {
+		code: "bad-request",
+		message: `${method} needs params.session from control.begin.`
+	};
+	const target = targetOf(params.session);
+	if (!target) return {
+		code: "unknown-session",
+		message: `No control session ${params.session} on this connection.`
+	};
+	const { platform, postures } = target;
+	const session = params.session;
+	if (method === "input.rotate") {
+		const { direction } = params;
+		if (!ROTATE_DIRECTIONS.includes(direction)) return {
+			code: "bad-request",
+			message: "input.rotate needs direction left or right."
+		};
+		return { value: {
+			session,
+			command: {
+				input: "rotate",
+				direction
+			}
+		} };
+	}
+	if (method === "input.posture") {
+		const { posture } = params;
+		if (!postures.includes(posture)) return {
+			code: "bad-request",
+			message: `This device ${postures.length ? `takes these postures: ${postures.join(", ")}` : "has no hinge"}.`
+		};
+		return { value: {
+			session,
+			command: {
+				input: "posture",
+				posture
+			}
+		} };
+	}
+	if (method === "input.touch") {
+		const { phase, x, y, display = 0 } = params;
+		if (!TOUCH_PHASES.includes(phase) || !fraction(x) || !fraction(y)) return {
+			code: "bad-request",
+			message: "input.touch needs phase (down, move or up), and x and y from 0 to 1."
+		};
+		if (!Number.isInteger(display) || display < 0 || display > 3) return {
+			code: "bad-request",
+			message: "display must be a display index from 0 to 3."
+		};
+		if (platform === "android" && display !== 0) return {
+			code: "bad-request",
+			message: "An emulator takes input on its main display (0) only."
+		};
+		return { value: {
+			session,
+			command: {
+				input: "touch",
+				phase,
+				x,
+				y,
+				display
+			}
+		} };
+	}
+	if (method === "input.text") {
+		const { text } = params;
+		if (typeof text !== "string" || !text.length || text.length > 256 || !TEXT.test(text)) return {
+			code: "bad-request",
+			message: `input.text takes 1 to 256 printable ASCII characters, with \\n, \\t and \\b.`
+		};
+		return { value: {
+			session,
+			command: {
+				input: "text",
+				text
+			}
+		} };
+	}
+	const { button } = params;
+	const allowed = platform === "ios" ? IOS_BUTTONS : INPUT_BUTTONS;
+	if (!allowed.includes(button)) return {
+		code: "bad-request",
+		message: `An ${platform} device takes these buttons: ${allowed.join(", ")}.`
+	};
+	return { value: {
+		session,
+		command: {
+			input: "button",
+			button
+		}
+	} };
+}
+const ANDROID_KEYS = {
+	home: "KEYCODE_HOME",
+	back: "KEYCODE_BACK",
+	"app-switch": "KEYCODE_APP_SWITCH",
+	lock: "KEYCODE_POWER",
+	"\n": "KEYCODE_ENTER",
+	"	": "KEYCODE_TAB",
+	"\b": "KEYCODE_DEL"
+};
+/**
+* The `adb shell` argument lists that type `text` or press `button` on an emulator without a hardware keyboard
+* (`hw.keyboard=no`), which drops gRPC key events. `adb shell` joins its arguments into one device shell
+* command, so text goes single-quoted; `input text` reads `%s` as a space.
+*/
+function adbInputArgs(command) {
+	if (command.input === "button") return [[
+		"shell",
+		"input",
+		"keyevent",
+		ANDROID_KEYS[command.button]
+	]];
+	const calls = [];
+	for (const part of command.text.split(/([\n\t\b]+)/)) {
+		if (!part) continue;
+		if (/^[\n\t\b]+$/.test(part)) {
+			calls.push([
+				"shell",
+				"input",
+				"keyevent",
+				...Array.from(part, (key) => ANDROID_KEYS[key])
+			]);
+			continue;
+		}
+		calls.push([
+			"shell",
+			"input",
+			"text",
+			`'${part.replaceAll(" ", "%s").replaceAll("'", "'\\''")}'`
+		]);
+	}
+	return calls;
+}
+function adbPath(env) {
+	for (const sdk of [
+		env.ANDROID_HOME,
+		env.ANDROID_SDK_ROOT,
+		join(env.HOME ?? homedir(), "Library/Android/sdk")
+	]) if (sdk && existsSync(join(sdk, "platform-tools/adb"))) return join(sdk, "platform-tools/adb");
+	return "adb";
+}
+const ADB_TIMEOUT_MS = 1e4;
+/** `sim-fold` waits up to 20 seconds for SpringBoard to finish the fold; Stim Desktop stops it after 40. */
+const FOLD_TIMEOUT_MS = 4e4;
+const POSTURE_TIMEOUT_MS = 5e3;
+function runQuietly(env, file, args, label, timeoutMs) {
+	return new Promise((resolve, reject) => {
+		const child = spawn(file, args, {
+			env,
+			stdio: [
+				"ignore",
+				"ignore",
+				"pipe"
+			]
+		});
+		let stderr = "";
+		const timer = setTimeout(() => void terminate(child), timeoutMs);
+		child.stderr.setEncoding("utf8");
+		child.stderr.on("data", (chunk) => stderr = (stderr + chunk).slice(-500));
+		child.on("error", (error) => {
+			clearTimeout(timer);
+			reject(/* @__PURE__ */ new Error(`${label} could not start (${error.message}).`));
+		});
+		child.on("close", (code) => {
+			clearTimeout(timer);
+			if (code === 0) resolve();
+			else reject(/* @__PURE__ */ new Error(`${label} failed (code ${code}): ${stderr.trim()}`));
+		});
+	});
+}
+function runAdb(env, serial, args) {
+	return runQuietly(env, adbPath(env), [
+		"-s",
+		serial,
+		...args
+	], `adb ${args.slice(0, 3).join(" ")}`, ADB_TIMEOUT_MS);
+}
+function activityOf(payload, target) {
+	const environment = payload.environments?.find((candidate) => candidate.path === target.workspace);
+	const slot = target.slot ?? "default";
+	const devices = slot === "default" ? environment : environment?.slots?.find((candidate) => candidate.slot === slot);
+	return target.platform === "ios" ? devices?.ios?.activity : devices?.android?.activity;
+}
+function otherDriver(activity, ownLeases) {
+	if (activity?.state !== "driven" || !activity.driver) return null;
+	const { tool, since } = activity.driver;
+	if (tool === "stim device lock" && since && ownLeases.has(since)) return null;
+	return since ? `${tool} (since ${since})` : tool;
+}
+const STATUS_WAIT_MS = 6e4;
+/**
+* Control sessions across all connections: at most one per device. A session holds the device's `stim-frames`
+* helper for input and a `stim device lock` lease, renewed while it lasts and released when it ends if the
+* session took it.
+*/
+var ControlHub = class {
+	options;
+	sessions = /* @__PURE__ */ new Map();
+	byDevice = /* @__PURE__ */ new Map();
+	ownLeases = /* @__PURE__ */ new Set();
+	starting = /* @__PURE__ */ new Set();
+	folding = /* @__PURE__ */ new Set();
+	closing = false;
+	next = 1;
+	constructor(options) {
+		this.options = options;
+	}
+	targetOf(owner, session) {
+		const found = this.sessions.get(session);
+		return found && found.owner === owner && !found.ended ? {
+			platform: found.target.platform,
+			postures: found.postures
+		} : null;
+	}
+	/**
+	* `stillAllowed` is checked again after the status read and the lock, which can take seconds: the client may
+	* have disconnected or lost `control` meanwhile.
+	*/
+	async begin(owner, target, cwd, stillAllowed) {
+		const beganAt = Date.now();
+		if (this.closing) return {
+			code: "action-failed",
+			message: "stim-server is stopping."
+		};
+		const status = await this.status();
+		if ("code" in status) return status;
+		const device = ownedDevice(status, target, null);
+		if (typeof device === "string") return {
+			code: "action-failed",
+			message: device
+		};
+		const key = deviceKey(device);
+		if (this.starting.has(key)) return {
+			code: "device-busy",
+			message: "Another client is starting to control this device. Try again."
+		};
+		const earlier = this.byDevice.get(key);
+		const driver = earlier ? `${earlier.owner.device.name} through stim-server` : otherDriver(activityOf(status, target), this.ownLeases);
+		if (driver && !target.takeOver) return {
+			code: "device-busy",
+			message: `This device is driven by ${driver}. Take over to control it anyway.`
+		};
+		this.starting.add(key);
+		let lease;
+		let postures;
+		try {
+			[lease, postures] = await Promise.all([this.lock(device, target, cwd, beganAt), devicePostures(device, this.options.env, POSTURE_TIMEOUT_MS)]);
+		} finally {
+			this.starting.delete(key);
+		}
+		const granted = "code" in lease ? null : lease;
+		if (!granted && !target.takeOver) return lease;
+		const current = this.byDevice.get(key);
+		const refuse = (refusal) => {
+			if (granted?.mine && !current?.lease?.mine) this.unlock(target, cwd);
+			return refusal;
+		};
+		if (this.closing || !stillAllowed()) return refuse({
+			code: "forbidden",
+			message: "This device can no longer control devices."
+		});
+		if (current && current !== earlier && !target.takeOver) return refuse({
+			code: "device-busy",
+			message: `${current.owner.device.name} started controlling this device.`
+		});
+		let session;
+		const input = this.options.frames.control(device, (message) => queueMicrotask(() => void this.end(session, "failed", message)));
+		if (!input) return refuse({
+			code: "action-failed",
+			message: "Input needs the stim-frames helper, which this Mac has not built."
+		});
+		const inherited = granted !== null && current?.lease?.mine === true;
+		if (current) this.end(current, "taken-over", `${owner.device.name} took over this device.`, !inherited);
+		const id = `c${this.next++}`;
+		session = {
+			id,
+			owner,
+			device,
+			key,
+			target,
+			cwd,
+			lease: granted ? {
+				...granted,
+				mine: granted.mine || inherited
+			} : null,
+			input,
+			postures,
+			startedAt: Date.now(),
+			idle: setTimeout(() => void this.end(session, "idle", "No input for 5 minutes."), this.options.idleMs),
+			renew: setInterval(() => this.renew(session, beganAt), this.options.renewMs),
+			renewing: Promise.resolve(),
+			unwatch: () => {},
+			adb: Promise.resolve(),
+			ended: false
+		};
+		this.sessions.set(id, session);
+		this.byDevice.set(key, session);
+		session.unwatch = this.options.feeds.subscribe(this.options.statusFeed, {
+			item: (payload) => {
+				const resolved = ownedDevice(payload, target, key);
+				if (typeof resolved === "string" || deviceKey(resolved) !== key) {
+					const message = typeof resolved === "string" ? resolved : "The device changed.";
+					queueMicrotask(() => void this.end(session, "device-gone", message));
+				}
+			},
+			failed: () => {}
+		});
+		this.audit(owner, target, driver || current ? "control.take-over" : "control.begin", {
+			ok: true,
+			...driver || current ? { reason: `took over from ${driver ?? current.owner.device.name}` } : {}
+		});
+		return {
+			session: id,
+			platform: target.platform,
+			lease: session.lease ? {
+				grantedAt: session.lease.grantedAt,
+				expiresAt: session.lease.expiresAt
+			} : null,
+			postures
+		};
+	}
+	renew(session, beganAt) {
+		if (session.ended || !session.lease?.mine) return;
+		session.renewing = (async () => {
+			const renewed = await this.lock(session.device, session.target, session.cwd, beganAt);
+			if ("code" in renewed) console.error(`stim-server: could not renew the device lease: ${renewed.message}`);
+			else if (session.lease) session.lease.expiresAt = renewed.expiresAt;
+		})();
+	}
+	input(owner, id, command) {
+		const session = this.sessions.get(id);
+		if (!session || session.owner !== owner || session.ended) return Promise.resolve({
+			code: "unknown-session",
+			message: `No control session ${id} on this connection.`
+		});
+		session.idle.refresh();
+		if (command.input === "posture" && session.device.platform === "ios") return this.fold(session, session.device.udid, command.posture);
+		if (session.device.platform === "ios" || command.input === "touch" || command.input === "rotate" || command.input === "posture" || session.input.keys()) {
+			session.input.send(command);
+			return Promise.resolve(null);
+		}
+		const serial = session.device.serial;
+		const previous = session.adb;
+		const run = (async () => {
+			await previous;
+			try {
+				for (const args of adbInputArgs(command)) {
+					if (session.ended) return null;
+					await runAdb(this.options.env, serial, args);
+				}
+				return null;
+			} catch (cause) {
+				return {
+					code: "action-failed",
+					message: cause.message
+				};
+			}
+		})();
+		session.adb = run.then(() => void 0);
+		return run;
+	}
+	/**
+	* `sim-fold` sweeps the hinge to the other posture, so it runs only when the Duo's last frame shows the
+	* other one.
+	*/
+	async fold(session, udid, posture) {
+		if (this.folding.has(udid)) return {
+			code: "device-busy",
+			message: "The device is still folding."
+		};
+		const current = this.options.frames.litPosture(session.device);
+		if (!current) return {
+			code: "action-failed",
+			message: "Subscribe to frames of this device to learn its posture first."
+		};
+		if (current === posture) return null;
+		this.folding.add(udid);
+		try {
+			const helper = await this.options.foldHelper();
+			if (session.ended) return null;
+			await runQuietly(this.options.env, "xcrun", [
+				"simctl",
+				"spawn",
+				udid,
+				helper
+			], "sim-fold", FOLD_TIMEOUT_MS);
+			this.options.frames.folded(udid, posture === "folded" ? "folded" : "unfolded");
+			return null;
+		} catch (cause) {
+			return {
+				code: "action-failed",
+				message: cause.message
+			};
+		} finally {
+			this.folding.delete(udid);
+		}
+	}
+	endById(owner, id) {
+		const session = this.sessions.get(id);
+		if (!session || session.owner !== owner) return false;
+		this.end(session, null, "The client ended the session.");
+		return true;
+	}
+	endFor(owner, reason, message) {
+		for (const session of this.sessions.values()) if (session.owner === owner) this.end(session, reason, message);
+	}
+	async close() {
+		this.closing = true;
+		const releases = [...this.sessions.values()].map((session) => this.end(session, null, "stim-server stopped."));
+		await Promise.all(releases);
+	}
+	end(session, reason, message, release = true) {
+		if (session.ended) return Promise.resolve();
+		session.ended = true;
+		clearTimeout(session.idle);
+		clearInterval(session.renew);
+		session.unwatch();
+		session.input.detach();
+		this.sessions.delete(session.id);
+		if (this.byDevice.get(session.key) === session) this.byDevice.delete(session.key);
+		if (reason) session.owner.send({
+			event: "control-ended",
+			session: session.id,
+			reason,
+			message
+		});
+		this.audit(session.owner, session.target, "control.end", {
+			ok: true,
+			durationMs: Date.now() - session.startedAt,
+			reason: `${reason ?? "ended"}: ${message}`
+		});
+		if (!release || !session.lease?.mine) return Promise.resolve();
+		return session.renewing.then(() => this.unlock(session.target, session.cwd));
+	}
+	status() {
+		return new Promise((resolve) => {
+			let settled = false;
+			let unsubscribe = null;
+			const finish = (value) => {
+				if (settled) return;
+				settled = true;
+				clearTimeout(timer);
+				unsubscribe?.();
+				resolve(value);
+			};
+			const timer = setTimeout(() => finish({
+				code: "status-failed",
+				message: "stim status did not report the device in time."
+			}), STATUS_WAIT_MS);
+			unsubscribe = this.options.feeds.subscribe(this.options.statusFeed, {
+				item: (payload) => finish(payload),
+				failed: (message) => finish({
+					code: "status-failed",
+					message
+				})
+			});
+			if (settled) unsubscribe();
+		});
+	}
+	async lock(device, target, cwd, beganAt) {
+		const id = device.platform === "ios" ? device.udid : device.serial;
+		const slot = target.slot && target.slot !== "default" ? ["--slot", target.slot] : [];
+		const args = [
+			"device",
+			"lock",
+			target.platform,
+			id,
+			"--for",
+			this.options.leaseFor,
+			"--wait",
+			"0",
+			"--json",
+			...slot
+		];
+		const printed = actionOutcome(await runStim(this.options.stimCli, this.options.env, args, cwd, this.options.lockLimits).outcome);
+		if (!printed.ok) return {
+			code: printed.error.message.startsWith("STIM_DEVICE_BUSY") ? "device-busy" : "action-failed",
+			message: `stim device lock: ${printed.error.message}`
+		};
+		const grantedAt = typeof printed.output.grantedAt === "string" ? printed.output.grantedAt : null;
+		const expiresAt = typeof printed.output.expiresAt === "string" ? printed.output.expiresAt : "";
+		const mine = grantedAt !== null && Date.parse(grantedAt) >= beganAt - 1e3;
+		if (mine) this.ownLeases.add(grantedAt);
+		return {
+			grantedAt,
+			expiresAt,
+			mine
+		};
+	}
+	async unlock(target, cwd) {
+		const slot = target.slot && target.slot !== "default" ? ["--slot", target.slot] : [];
+		const outcome = await runStim(this.options.stimCli, this.options.env, [
+			"device",
+			"unlock",
+			target.platform,
+			"--json",
+			...slot
+		], cwd, this.options.lockLimits).outcome;
+		if (!outcome.ok) console.error(`stim-server: could not release the device lease: ${outcome.message}`);
+	}
+	audit(owner, target, action, outcome) {
+		this.options.audit({
+			at: (/* @__PURE__ */ new Date()).toISOString(),
+			device: {
+				id: owner.device.id,
+				name: owner.device.name
+			},
+			action,
+			workspace: target.workspace,
+			platform: target.platform,
+			...outcome
+		});
+	}
+};
+//#endregion
+//#region src/feed.ts
+var Feed = class {
+	listeners = /* @__PURE__ */ new Set();
+	kept = [];
+	child;
+	ended;
+	constructor(spec, stimCli, env, ended) {
+		this.ended = ended;
+		const child = spawn(process.execPath, [stimCli, ...spec.args], {
+			cwd: spec.cwd,
+			env,
+			stdio: [
+				"ignore",
+				"pipe",
+				"pipe"
+			]
+		});
+		this.child = child;
+		let stderr = "";
+		child.stderr?.setEncoding("utf8");
+		child.stderr?.on("data", (chunk) => {
+			stderr = (stderr + chunk).slice(-2e3);
+		});
+		createInterface({ input: child.stdout }).on("line", (line) => {
+			if (this.child !== child) return;
+			let value;
+			try {
+				value = JSON.parse(line);
+			} catch {
+				return;
+			}
+			if (!isJsonObject(value)) return;
+			this.kept.push(value);
+			if (this.kept.length > spec.keep) this.kept.shift();
+			for (const listener of this.listeners) listener.item(value);
+		});
+		const exited = (reason) => {
+			if (this.child !== child) return;
+			this.child = null;
+			this.ended();
+			const message = `${spec.label} ${reason}${stderr.trim() ? `: ${stderr.trim()}` : ""}`;
+			const listeners = [...this.listeners];
+			this.listeners.clear();
+			for (const listener of listeners) listener.failed(message);
+		};
+		child.on("error", (error) => exited(`could not start (${error.message})`));
+		child.on("close", (code, signal) => exited(`exited (${signal ?? `code ${code}`})`));
+	}
+	add(listener) {
+		this.listeners.add(listener);
+		for (const value of this.kept) listener.item(value);
+		return () => {
+			if (this.listeners.delete(listener) && this.listeners.size === 0) this.stop();
+		};
+	}
+	stop() {
+		const child = this.child;
+		if (!child) return Promise.resolve();
+		this.child = null;
+		this.listeners.clear();
+		this.ended();
+		return terminate(child);
 	}
 };
-/**
-* 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.
-*/
-var FramePool = class {
-	sources = /* @__PURE__ */ new Map();
-	limiter = new Limiter(MAX_CAPTURES);
+var FeedPool = class {
+	feeds = /* @__PURE__ */ new Map();
+	stimCli;
 	env;
-	limits;
-	constructor(env, limits = DEFAULT_FRAME_LIMITS) {
+	constructor(stimCli, env) {
+		this.stimCli = stimCli;
 		this.env = env;
-		this.limits = limits;
 	}
-	subscribe(device, listener) {
-		const key = deviceKey(device);
-		let source = this.sources.get(key);
-		if (!source) {
-			const created = new FrameSource(device.platform === "ios" ? simulatorCapturer(device.udid, this.env, this.limits) : emulatorCapturer(device.serial, this.env, this.limits), this.limiter, this.limits, () => {
-				if (this.sources.get(key) === created) this.sources.delete(key);
+	subscribe(spec, listener) {
+		const key = JSON.stringify([spec.cwd, spec.args]);
+		let feed = this.feeds.get(key);
+		if (!feed) {
+			const created = new Feed(spec, this.stimCli, this.env, () => {
+				if (this.feeds.get(key) === created) this.feeds.delete(key);
 			});
-			this.sources.set(key, created);
-			source = created;
+			this.feeds.set(key, created);
+			feed = created;
 		}
-		return source.add(listener);
+		return feed.add(listener);
 	}
 	async close() {
-		await Promise.all([...this.sources.values()].map((source) => source.stop()));
+		await Promise.all([...this.feeds.values()].map((feed) => feed.stop()));
 	}
 };
 //#endregion
@@ -884,8 +2164,8 @@ function parseLogFilter(params) {
 	const { sources, level, slot, grep, errors, tail } = params;
 	if (sources !== void 0 && (!Array.isArray(sources) || sources.length === 0 || !sources.every((source) => LOG_SOURCES.includes(source)))) return { error: `sources must be a non-empty list of ${LOG_SOURCES.join(", ")}.` };
 	if (level !== void 0 && !LOG_LEVELS.includes(level)) return { error: `level must be one of ${LOG_LEVELS.join(", ")}.` };
-	if (slot !== void 0 && (typeof slot !== "string" || slot === "")) return { error: "slot must be a slot name." };
-	if (grep !== void 0 && (typeof grep !== "string" || compileGrep(grep).error)) return { error: "grep must be a valid regular expression." };
+	if (slot !== void 0 && (typeof slot !== "string" || !SLOT_NAME.test(slot))) return { error: "slot must be 1-64 letters, digits, underscores or hyphens." };
+	if (grep !== void 0 && (typeof grep !== "string" || grep.includes("\0") || compileGrep(grep).error)) return { error: "grep must be a valid regular expression without NUL characters." };
 	if (errors !== void 0 && typeof errors !== "boolean") return { error: "errors must be true or false." };
 	if (tail !== void 0 && (!Number.isInteger(tail) || tail < 1 || tail > 5e3)) return { error: `tail must be an integer from 1 to ${MAX_LOG_TAIL}.` };
 	return { filter: {
@@ -951,6 +2231,198 @@ 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;
@@ -1192,8 +2664,21 @@ 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 CONTROL_LIMITS = {
+	idleMs: 3e5,
+	renewMs: 6e4,
+	leaseFor: "2m",
+	inputPerSecond: 120,
+	textCharsPerSecond: 40,
+	shapeChangesPerSecond: 2
+};
+const LOCK_LIMITS = {
+	timeoutMs: 3e4,
+	maxOutputBytes: 65536
+};
 const STATUS_FEED = {
 	args: [
 		"status",
@@ -1209,6 +2694,12 @@ const COMMAND_LIMITS = {
 	timeoutMs: 6e4,
 	maxOutputBytes: 33554432
 };
+const PLAN_TIMEOUT_MS = 15e4;
+const AUDIT_FIELD_CHARS = 256;
+const ACTION_LIMITS = {
+	timeoutMs: 12e4,
+	maxOutputBytes: 1048576
+};
 const AUTH_REFUSALS = {
 	"pairing-unknown": {
 		code: "pairing-expired",
@@ -1261,12 +2752,52 @@ var FailureLimiter = class {
 		this.failures.set(key, [...this.recent(key, now), now]);
 	}
 };
+function auditSafely(record) {
+	try {
+		appendAudit(record);
+	} catch (cause) {
+		console.error(`stim-server: could not append to the action log: ${cause.message}`);
+	}
+}
+function take(bucket, cost, perSecond, capacity) {
+	const now = Date.now();
+	bucket.tokens = Math.min(capacity, bucket.tokens + (now - bucket.at) / 1e3 * perSecond);
+	bucket.at = now;
+	if (bucket.tokens < cost) return false;
+	bucket.tokens -= cost;
+	return true;
+}
 function send(socket, message) {
 	if (socket.readyState === socket.OPEN) socket.send(JSON.stringify(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;
@@ -1275,7 +2806,38 @@ async function startServer(options) {
 		...DEFAULT_FRAME_LIMITS,
 		...options.frameLimits
 	};
-	const frames = new FramePool(options.env, 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);
+	let foldBuild = null;
+	const foldHelper = () => {
+		if (options.foldHelper !== void 0) return Promise.resolve(options.foldHelper);
+		foldBuild ??= buildFoldHelper(options.env, helperAbort.signal).catch((cause) => {
+			foldBuild = null;
+			throw new Error(`sim-fold could not be built: ${cause.message}`);
+		});
+		return foldBuild;
+	};
 	const running = /* @__PURE__ */ new Set();
 	const logLimits = {
 		...LOG_LIMITS,
@@ -1285,7 +2847,32 @@ async function startServer(options) {
 		...COMMAND_LIMITS,
 		...options.commandLimits
 	};
+	const actionLimits = {
+		...ACTION_LIMITS,
+		...options.actionLimits
+	};
+	const busyWorkspaces = /* @__PURE__ */ new Set();
+	const planQueues = /* @__PURE__ */ new Map();
 	const sessions = /* @__PURE__ */ new Map();
+	const sampler = new UsageSampler();
+	const controllers = /* @__PURE__ */ new Map();
+	const controlLimits = {
+		...CONTROL_LIMITS,
+		...options.controlLimits
+	};
+	const control = new ControlHub({
+		env: options.env,
+		stimCli: options.stimCli,
+		feeds,
+		frames,
+		statusFeed: STATUS_FEED,
+		audit: auditSafely,
+		lockLimits: LOCK_LIMITS,
+		idleMs: controlLimits.idleMs,
+		renewMs: controlLimits.renewMs,
+		leaseFor: controlLimits.leaseFor,
+		foldHelper
+	});
 	const wss = new WebSocketServer({
 		noServer: true,
 		maxPayload: MAX_PAYLOAD
@@ -1298,13 +2885,18 @@ async function startServer(options) {
 	const watcher = watch(serverDir(), () => {
 		revocationCheck ??= setTimeout(() => {
 			revocationCheck = null;
-			const paired = new Set(readDevices().map((device) => device.id));
+			const paired = new Map(readDevices().map((device) => [device.id, device]));
 			for (const [socket, device] of sessions) if (!paired.has(device.id)) socket.close(CLOSE_UNAUTHORIZED, "device revoked");
+			for (const [socket, controller] of controllers) if (!paired.get(controller.device.id)?.capabilities.includes("control")) {
+				control.endFor(controller, "forbidden", "This device can no longer control devices.");
+				controllers.delete(socket);
+			}
 		}, 50);
 	});
 	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;
@@ -1353,6 +2945,7 @@ async function startServer(options) {
 			}
 			device = outcome.device;
 			sessions.set(socket, device);
+			sampler.start();
 			send(socket, {
 				id,
 				result: {
@@ -1360,9 +2953,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
@@ -1380,30 +2975,92 @@ async function startServer(options) {
 				}
 			});
 		}
+		const inputs = {
+			tokens: controlLimits.inputPerSecond,
+			at: Date.now()
+		};
+		const characters = {
+			tokens: 256,
+			at: Date.now()
+		};
+		const shapeChanges = {
+			tokens: controlLimits.shapeChangesPerSecond,
+			at: Date.now()
+		};
+		function controller(session) {
+			let found = controllers.get(socket);
+			if (!found) {
+				found = {
+					device: session,
+					send: (message) => send(socket, message)
+				};
+				controllers.set(socket, found);
+			}
+			return found;
+		}
+		async function beginControl(id, params, session) {
+			const raw = isJsonObject(params) ? params : {};
+			const clip = (value) => typeof value === "string" ? value.slice(0, AUDIT_FIELD_CHARS) : null;
+			const refuseControl = (code, message) => {
+				auditSafely({
+					at: (/* @__PURE__ */ new Date()).toISOString(),
+					device: {
+						id: session.id,
+						name: session.name
+					},
+					action: raw.takeOver === true ? "control.take-over" : "control.begin",
+					workspace: clip(raw.workspace),
+					...typeof raw.platform === "string" ? { platform: clip(raw.platform) } : {},
+					ok: false,
+					error: {
+						code,
+						message: clip(message)
+					}
+				});
+				error(id, code, message);
+			};
+			if (!readDevices().find((entry) => entry.id === session.id)?.capabilities.includes("control")) return refuseControl("forbidden", `This device can only read. On the Mac, run \`stim-server devices grant ${session.id} --control\` to let it control devices.`);
+			const parsed = parseControlBegin(params);
+			if ("code" in parsed) return refuseControl(parsed.code, parsed.message);
+			const resolved = registeredWorkspace(parsed.value.workspace);
+			if ("code" in resolved) return refuseControl(resolved.code, resolved.message);
+			const owner = controller(session);
+			const outcome = await control.begin(owner, {
+				...parsed.value,
+				workspace: resolved.dir
+			}, resolved.dir, () => socket.readyState === socket.OPEN && controllers.get(socket) === owner && readDevices().some((entry) => entry.id === session.id && entry.capabilities.includes("control")));
+			if ("code" in outcome) return refuseControl(outcome.code, outcome.message);
+			send(socket, {
+				id,
+				result: outcome
+			});
+		}
+		async function input(id, method, params, session) {
+			const owner = controller(session);
+			const parsed = parseInput(method, params, (name) => control.targetOf(owner, name));
+			if ("code" in parsed) return error(id, parsed.code, parsed.message);
+			if (!take(inputs, 1, controlLimits.inputPerSecond, controlLimits.inputPerSecond)) return error(id, "limit-exceeded", `A connection can send ${controlLimits.inputPerSecond} inputs a second.`);
+			const { command: sent } = parsed.value;
+			if (sent.input === "text" && !take(characters, sent.text.length, controlLimits.textCharsPerSecond, 256)) return error(id, "limit-exceeded", `A connection can type ${controlLimits.textCharsPerSecond} characters a second. Send the rest shortly.`);
+			const { shapeChangesPerSecond } = controlLimits;
+			if ((sent.input === "rotate" || sent.input === "posture") && !take(shapeChanges, 1, shapeChangesPerSecond, shapeChangesPerSecond)) return error(id, "limit-exceeded", `A connection can rotate or fold ${shapeChangesPerSecond} times a second.`);
+			const refused = await control.input(owner, parsed.value.session, parsed.value.command);
+			if (refused) return error(id, refused.code, refused.message);
+			send(socket, {
+				id,
+				result: {}
+			});
+		}
 		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.");
-				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.`);
+			const resolved = registeredWorkspace(workspace);
+			if ("code" in resolved) {
+				error(id, resolved.code, resolved.message);
 				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;
@@ -1411,7 +3068,10 @@ async function startServer(options) {
 			const subscription = `s${nextSubscription++}`;
 			send(socket, {
 				id,
-				result: { subscription }
+				result: {
+					subscription,
+					...result
+				}
 			});
 			return subscription;
 		}
@@ -1495,31 +3155,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,
@@ -1531,7 +3219,9 @@ async function startServer(options) {
 			};
 			const cleanup = () => {
 				ended = true;
+				keyframes.delete(subscription);
 				if (retry) clearTimeout(retry);
+				if (draining) clearTimeout(draining);
 				detach?.();
 				detach = null;
 				unsubscribeStatus?.();
@@ -1561,8 +3251,18 @@ async function startServer(options) {
 						delayed
 					});
 				},
-				failed: end
+				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) => {
@@ -1571,34 +3271,62 @@ 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) {
-			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);
-			commands.add(run.cancel);
-			running.add(run.cancel);
-			(async () => {
+		function command(id, args, cwd, result, limits = commandLimits, turn = null) {
+			if (commands.size >= MAX_COMMANDS) {
+				error(id, "limit-exceeded", `A connection can run ${MAX_COMMANDS} requests at a time.`);
+				return null;
+			}
+			let run = null;
+			let dropped = false;
+			let release;
+			const released = new Promise((resolve) => {
+				release = resolve;
+			});
+			const cancel = async () => {
+				dropped = true;
+				if (!run) return void (turn ?? Promise.resolve()).then(release);
+				await run.cancel();
+				release();
+			};
+			const start = async () => {
+				if (dropped) return;
+				run = runStim(options.stimCli, options.env, args, cwd, limits);
 				const outcome = await run.outcome;
-				commands.delete(run.cancel);
-				running.delete(run.cancel);
-				if (!outcome.ok) return error(id, "stim-failed", outcome.message);
-				let value;
+				commands.delete(cancel);
+				running.delete(cancel);
 				try {
-					value = result(outcome.stdout);
-				} catch {
-					return error(id, "stim-failed", `stim ${args[0]} printed output that is not JSON.`);
+					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);
+					} catch {
+						return error(id, "stim-failed", `stim ${args[0]} printed output that is not JSON.`);
+					}
+					send(socket, {
+						id,
+						result: value
+					});
+				} finally {
+					release();
 				}
-				send(socket, {
-					id,
-					result: value
-				});
-			})();
+			};
+			commands.add(cancel);
+			running.add(cancel);
+			if (turn) turn.then(start);
+			else start();
+			return released;
 		}
 		function queryLogs(id, params) {
 			const parsed = parseLogFilter(params);
@@ -1617,6 +3345,123 @@ 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;
+			const finished = 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
+			}, planQueues.get(cwd) ?? null);
+			if (!finished) return;
+			planQueues.set(cwd, finished);
+			finished.finally(() => {
+				if (planQueues.get(cwd) === finished) planQueues.delete(cwd);
+			});
+		}
 		async function handle(raw) {
 			if (socket.readyState !== socket.OPEN) return;
 			let message;
@@ -1642,7 +3487,55 @@ 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 === "control.begin") {
+				beginControl(id, message.params, device);
+				return;
+			}
+			if (message.method === "control.end") {
+				const name = isJsonObject(message.params) ? message.params.session : void 0;
+				if (typeof name !== "string" || !control.endById(controller(device), name)) return error(id, "unknown-session", `No control session ${String(name)} on this connection.`);
+				return send(socket, {
+					id,
+					result: {}
+				});
+			}
+			if (message.method === "input.touch" || message.method === "input.text" || message.method === "input.button" || message.method === "input.rotate" || message.method === "input.posture") {
+				const method = message.method;
+				input(id, method, message.params, device);
+				return;
+			}
 			if (message.method === "unsubscribe") {
 				const name = isJsonObject(message.params) ? message.params.subscription : void 0;
 				const unsubscribe = typeof name === "string" ? subscriptions.get(name) : void 0;
@@ -1675,6 +3568,10 @@ async function startServer(options) {
 		socket.on("close", () => {
 			clearTimeout(timer);
 			sessions.delete(socket);
+			if (sessions.size === 0) sampler.stop();
+			const owner = controllers.get(socket);
+			if (owner) control.endFor(owner, null, "The client disconnected.");
+			controllers.delete(socket);
 			for (const unsubscribe of subscriptions.values()) unsubscribe();
 			subscriptions.clear();
 			for (const cancel of commands) {
@@ -1713,8 +3610,11 @@ async function startServer(options) {
 	const addresses = [];
 	const close = async () => {
 		watcher.close();
+		helperAbort.abort();
+		sampler.stop();
 		if (revocationCheck) clearTimeout(revocationCheck);
 		for (const client of wss.clients) client.terminate();
+		await control.close();
 		await Promise.all([
 			frames.close(),
 			feeds.close(),
@@ -1760,11 +3660,15 @@ 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}`);
@@ -1829,7 +3733,7 @@ async function serve(port) {
 	process.on("SIGTERM", shutdown);
 	process.on("SIGHUP", shutdown);
 }
-async function pair(port, json) {
+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}`;
@@ -1841,7 +3745,7 @@ async function pair(port, json) {
 		endpoint = tailnetEndpoint(tailscale.dnsName, route.port);
 		note = routeNote(route, port);
 	}
-	const { token, expiresAt } = createPairingToken();
+	const { token, expiresAt } = createPairingToken(Date.now(), capabilitiesFor(control));
 	const payload = {
 		v: 1,
 		name: macName(tailscale),
@@ -1853,12 +3757,13 @@ async function pair(port, json) {
 		expiresAt
 	}));
 	console.log(JSON.stringify(payload));
-	console.error(`The pairing token is single use and expires at ${expiresAt}.`);
+	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({
@@ -1866,6 +3771,8 @@ async function main() {
 		options: {
 			port: { type: "string" },
 			json: { type: "boolean" },
+			control: { type: "boolean" },
+			read: { type: "boolean" },
 			help: {
 				type: "boolean",
 				short: "h"
@@ -1882,7 +3789,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.reason ? ` (${record.reason})` : ""}` : `${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) {