@stim-cli/server 1.11.0 → 1.13.0

package/dist/stim-server.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { a as FRAME_FPS, c as MAX_LOG_TAIL, i as FRAME_EDGE, n as CAPABILITIES, o as LOG_LEVELS, s as LOG_SOURCES, t as ACTIONS } from "./protocol-CmlG7X7_.mjs";
+import { _ as ROTATE_DIRECTIONS, c as INPUT_BUTTONS, f as MAX_LOG_TAIL, g as RELOAD_PLATFORMS, l as LOG_LEVELS, n as CAPABILITIES, o as FRAME_EDGE, s as FRAME_FPS, t as ACTIONS, u as LOG_SOURCES, v as TOUCH_PHASES } from "./protocol-rC-5KT1O.mjs";
 import { createRequire } from "node:module";
 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";
@@ -12,9 +12,9 @@ import { configDir, withDirLock } from "@stim-cli/core";
 import { createServer } from "node:http";
 import { isIP } from "node:net";
 import { WebSocketServer } from "ws";
-import { createInterface } from "node:readline";
-import { fileURLToPath } from "node:url";
 import { connect } from "node:http2";
+import { fileURLToPath } from "node:url";
+import { createInterface } from "node:readline";
 //#region src/environment.ts
 function parseEnvironment(output) {
 	const environment = {};
@@ -284,9 +284,9 @@ function parseAction(params) {
 		action,
 		workspace
 	} };
-	if (platform !== void 0 && platform !== "ios" && platform !== "android") return {
+	if (platform !== void 0 && !RELOAD_PLATFORMS.includes(platform)) return {
 		code: "bad-request",
-		message: "platform must be ios or android."
+		message: `platform must be one of ${RELOAD_PLATFORMS.join(", ")}.`
 	};
 	return { action: {
 		action: "reload",
@@ -397,12 +397,20 @@ function runStim(stimCli, env, args, cwd, limits) {
 	const chunks = [];
 	let size = 0;
 	let stderr = "";
+	const release = () => {
+		child.stdout.destroy();
+		child.stderr.destroy();
+	};
 	const fail = (message) => {
 		if (failure) return;
 		failure = message;
+		release();
 		terminate(child);
 	};
-	const timer = setTimeout(() => fail(`${label} did not finish within ${limits.timeoutMs / 1e3} s.`), limits.timeoutMs);
+	const timer = setTimeout(() => {
+		if (child.exitCode !== null || child.signalCode !== null) return release();
+		fail(`${label} did not finish within ${limits.timeoutMs / 1e3} s.`);
+	}, limits.timeoutMs);
 	child.stdout.on("data", (chunk) => {
 		size += chunk.length;
 		if (size > limits.maxOutputBytes) return fail(`${label} printed more than ${limits.maxOutputBytes} bytes.`);
@@ -447,95 +455,6 @@ function runStim(stimCli, env, args, cwd, limits) {
 	};
 }
 //#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);
-	}
-};
-var FeedPool = class {
-	feeds = /* @__PURE__ */ new Map();
-	stimCli;
-	env;
-	constructor(stimCli, env) {
-		this.stimCli = stimCli;
-		this.env = env;
-	}
-	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;
-		}
-		return feed.add(listener);
-	}
-	async close() {
-		await Promise.all([...this.feeds.values()].map((feed) => feed.stop()));
-	}
-};
-//#endregion
 //#region src/video.ts
 const FIXED_HEADER_BYTES = 21;
 /** The binary WebSocket message for `unit` on `subscription`; see `VideoPacket` in protocol.ts for the layout. */
@@ -543,7 +462,8 @@ 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);
+	const posture = unit.posture === "folded" ? 2 : unit.posture === "unfolded" ? 4 : 0;
+	header.writeUInt8((unit.keyframe ? 1 : 0) | posture, 1);
 	header.writeUInt16BE(header.length, 2);
 	header.writeUInt32BE(sequence >>> 0, 4);
 	header.writeDoubleBE(unit.capturedAt, 8);
@@ -685,20 +605,9 @@ function run(file, args, env, timeoutMs, signal) {
 */
 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();
+	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.`);
-	const version = await run("xcrun", ["swiftc", "--version"], env, VERSION_TIMEOUT_MS, signal);
-	const hash = createHash("sha256").update(version);
-	for (const name of sources) hash.update(name).update(readFileSync(join(sourcesDir, name)));
-	const dir = join(serverDir(), "helpers");
-	const helper = join(dir, `stim-frames-${hash.digest("hex").slice(0, 16)}`);
-	if (existsSync(helper)) return helper;
-	mkdirSync(dir, {
-		recursive: true,
-		mode: 448
-	});
-	const output = `${helper}.tmp-${process.pid}-${randomBytes(4).toString("hex")}`;
-	try {
+	return compiled("stim-frames", sources, await run("xcrun", ["swiftc", "--version"], env, VERSION_TIMEOUT_MS, signal), async (output) => {
 		await run("xcrun", [
 			"swiftc",
 			"-O",
@@ -708,8 +617,61 @@ async function buildFrameHelper(env, signal, sourcesDir = SOURCES_DIR) {
 			"StimFrames",
 			"-o",
 			output,
-			...sources.map((source) => join(sourcesDir, source))
+			...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 });
@@ -717,9 +679,11 @@ async function buildFrameHelper(env, signal, sourcesDir = SOURCES_DIR) {
 	return helper;
 }
 /**
-* One `stim-frames` process per device, shared by its subscribers and stopped with the last of them. It runs
+* One `stim-frames` process per device, shared by its subscribers and stopped `lingerMs` after the last of them
+* leaves, unchanged meanwhile, so a subscriber that comes back within that time gets the latest frame at once. 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.
+* helper exits when its stdin closes, so it cannot outlive the server. `lit` turns the display the helper
+* reports it streams into a posture, which the frames and access units after it carry.
 */
 var HelperSource = class {
 	listeners = /* @__PURE__ */ new Map();
@@ -728,13 +692,20 @@ var HelperSource = class {
 	config = "";
 	stopped = false;
 	notice = null;
+	keyboard = null;
 	stderr = "";
 	ended;
 	bitrate = new Bitrate(DEFAULT_VIDEO_LIMITS, Date.now());
 	keyframeAt = -Infinity;
 	keyframeTimer = null;
-	constructor(helper, device, env, ended) {
+	lit;
+	posture;
+	lingerMs;
+	lingerTimer = null;
+	constructor(helper, device, env, ended, lingerMs, lit) {
 		this.ended = ended;
+		this.lingerMs = lingerMs;
+		this.lit = lit;
 		const id = device.platform === "ios" ? device.udid : device.serial;
 		this.child = spawn(helper, [device.platform, id], {
 			env,
@@ -756,21 +727,25 @@ var HelperSource = class {
 			this.fail(`stim-frames exited (${signal ?? `code ${code}`})${detail ? `: ${detail}` : ""}`);
 		});
 	}
+	/** A null `hint` keeps the helper running for input without asking for frames. */
 	add(listener, hint) {
+		if (this.lingerTimer) clearTimeout(this.lingerTimer);
+		this.lingerTimer = null;
 		this.listeners.set(listener, hint);
 		this.configure();
 		if (listener.video) this.keyframe();
 		else if (this.last) listener.frame(this.last);
 		return () => {
 			if (!this.listeners.delete(listener)) return;
-			if (this.listeners.size === 0) this.stop();
-			else this.configure();
+			if (this.listeners.size > 0) this.configure();
+			else this.lingerTimer = setTimeout(() => void this.stop(), this.lingerMs);
 		};
 	}
 	stop() {
 		if (this.stopped) return Promise.resolve();
 		this.stopped = true;
 		if (this.keyframeTimer) clearTimeout(this.keyframeTimer);
+		if (this.lingerTimer) clearTimeout(this.lingerTimer);
 		this.listeners.clear();
 		this.ended();
 		this.child.stdin.end();
@@ -793,12 +768,20 @@ var HelperSource = class {
 	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 hints = [...this.listeners.values()];
-		const jpegFps = [...this.listeners].flatMap(([listener, hint]) => listener.video ? [] : [hint.fps]);
+		if (this.listeners.size === 0) return;
+		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(...hints.map((hint) => hint.fps)),
-			maxEdge: Math.max(...hints.map((hint) => hint.maxEdge)),
+			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,
@@ -840,7 +823,8 @@ var HelperSource = class {
 			width: body.readUInt16BE(1),
 			height: body.readUInt16BE(3),
 			capturedAt: (/* @__PURE__ */ new Date()).toISOString(),
-			data: body.subarray(5).toString("base64")
+			data: body.subarray(5).toString("base64"),
+			...this.posture ? { posture: this.posture } : {}
 		};
 		for (const listener of this.listeners.keys()) if (!listener.video) listener.frame(this.last);
 	}
@@ -851,15 +835,23 @@ var HelperSource = class {
 			capturedAt: body.readDoubleBE(2),
 			width: body.readUInt16BE(10),
 			height: body.readUInt16BE(12),
-			data: body.subarray(VIDEO_HEADER_BYTES)
+			data: body.subarray(VIDEO_HEADER_BYTES),
+			...this.posture ? { posture: this.posture } : {}
 		};
 		if (this.bitrate.tick(Date.now()) !== null) this.configure();
 		for (const listener of this.listeners.keys()) listener.video?.(unit);
 	}
 	readNotice(text) {
 		try {
-			const error = JSON.parse(text)?.error;
+			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}`);
+			const display = notice?.display;
+			if (this.lit && typeof display === "number") this.posture = this.lit(display);
 		} catch {}
 	}
 };
@@ -869,7 +861,8 @@ const DEFAULT_FRAME_LIMITS = {
 	toolTimeoutMs: 3e4,
 	slowCaptureMs: 3e3,
 	failureBackoffMs: 3e3,
-	maxConsecutiveFailures: 3
+	maxConsecutiveFailures: 3,
+	lingerMs: 1e4
 };
 const MIN_INTERVAL_MS = 200;
 const MAX_INTERVAL_MS = 1e3;
@@ -1032,11 +1025,14 @@ function simulatorCapturer(device, env, limits, litPanels) {
 		const lit = litPanels.get(device.udid) ?? "primary";
 		const jpeg = await screenshot([`--display=${lit}`]);
 		open();
-		if (!await isBlack(jpeg)) return {
-			raw: jpeg,
-			jpeg: async () => jpeg,
-			posture: POSTURES[lit]
-		};
+		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}`]);
@@ -1074,6 +1070,8 @@ function simulatorCapturer(device, env, limits, litPanels) {
 		}
 	};
 }
+/** The Duo's panels in the order the helper indexes CoreSimulator's displays, by screen ID. */
+const DUO_PANELS = ["primary", "primary-1"];
 const POSTURES = {
 	primary: "folded",
 	"primary-1": "unfolded"
@@ -1212,16 +1210,13 @@ function hasHinge(body) {
 	}
 	return false;
 }
-function emulatorCapturer(serial, env, limits) {
-	let session = null;
-	let tmp = null;
-	const running = /* @__PURE__ */ new Set();
-	let hinged = null;
-	const call = (endpoint, method, requestBody) => new Promise((resolve, reject) => {
-		if (!session || session.closed || session.destroyed) {
-			session = connect(`http://127.0.0.1:${endpoint.grpcPort}`);
-			session.on("error", () => {});
-		}
+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/${method}`,
@@ -1237,7 +1232,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();
 		});
@@ -1255,11 +1250,43 @@ function emulatorCapturer(serial, env, limits) {
 		});
 		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.`);
-			hinged ??= await call(endpoint, "getPhysicalModel", grpcMessage([8, 16])).then(hasHinge).catch(() => false);
+			hinged ??= await call(endpoint, "getPhysicalModel", POSTURE_MODEL).then(hasHinge).catch(() => false);
 			const { png, folded } = screenshotReply(await call(endpoint, "getScreenshot", grpcMessage([
 				24,
 				...varint(MAX_EDGE),
@@ -1402,12 +1429,15 @@ var FrameSource = class {
 	}
 };
 /**
-* 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.
+* One capture per device, shared by its subscribers. A `stim-frames` helper stops `lingerMs` after the last of
+* them leaves, so a client that takes one frame at a time reuses it; a screenshot loop stops 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; an iPhone Duo
+* streams its lit panel, which is its posture. Without the helper, and while it 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();
@@ -1423,7 +1453,7 @@ var FramePool = class {
 	}
 	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);
+		if (helper === null) return this.screenshots(device).add(listener);
 		let streamed = false;
 		let cancelled = false;
 		const { video } = listener;
@@ -1448,6 +1478,15 @@ var FramePool = class {
 			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();
@@ -1460,13 +1499,37 @@ var FramePool = class {
 		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 lit = device.platform === "ios" && device.foldable ? (display) => {
+			const panel = DUO_PANELS[display];
+			if (!panel) return void 0;
+			this.litPanels.set(device.udid, panel);
+			return POSTURES[panel];
+		} : void 0;
 		const created = new HelperSource(helper, device, this.env, () => {
 			if (this.sources.get(key) === created) this.sources.delete(key);
-		});
+		}, this.limits.lingerMs, lit);
 		this.sources.set(key, created);
 		return created;
 	}
@@ -1485,14 +1548,668 @@ var FramePool = class {
 	}
 };
 //#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;
+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 finish = (code) => {
+			clearTimeout(timer);
+			if (code === 0) resolve();
+			else reject(/* @__PURE__ */ new Error(`${label} failed (code ${code}): ${stderr.trim()}`));
+		};
+		const timer = setTimeout(() => {
+			child.stderr.destroy();
+			if (child.exitCode !== null || child.signalCode !== null) return finish(child.exitCode);
+			terminate(child);
+			reject(/* @__PURE__ */ new Error(`${label} did not finish within ${timeoutMs / 1e3} s.`));
+		}, 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", finish);
+	});
+}
+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", this.options.foldTimeoutMs);
+			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,
+				text: line
+			});
+			if (this.kept.length > spec.keep) this.kept.shift();
+			for (const listener of this.listeners) listener.item(value, line);
+		});
+		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, text } of this.kept) listener.item(value, text);
+		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);
+	}
+};
+var FeedPool = class {
+	feeds = /* @__PURE__ */ new Map();
+	stimCli;
+	env;
+	constructor(stimCli, env) {
+		this.stimCli = stimCli;
+		this.env = env;
+	}
+	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;
+		}
+		return feed.add(listener);
+	}
+	async close() {
+		await Promise.all([...this.feeds.values()].map((feed) => feed.stop()));
+	}
+};
+//#endregion
 //#region src/logs.ts
 function parseLogFilter(params) {
 	if (!isJsonObject(params) || typeof params.workspace !== "string") return { error: "params.workspace is required." };
 	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: {
@@ -1994,6 +2711,19 @@ const LOG_LIMITS = {
 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,
+	foldTimeoutMs: 4e4
+};
+const LOCK_LIMITS = {
+	timeoutMs: 3e4,
+	maxOutputBytes: 65536
+};
 const STATUS_FEED = {
 	args: [
 		"status",
@@ -2010,7 +2740,6 @@ const COMMAND_LIMITS = {
 	maxOutputBytes: 33554432
 };
 const PLAN_TIMEOUT_MS = 15e4;
-const SLOT_NAME = /^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/;
 const AUDIT_FIELD_CHARS = 256;
 const ACTION_LIMITS = {
 	timeoutMs: 12e4,
@@ -2068,8 +2797,23 @@ 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));
+	if (socket.readyState === socket.OPEN) socket.send(typeof message === "string" ? message : JSON.stringify(message));
 }
 function requestId(value) {
 	return typeof value === "number" || typeof value === "string" ? value : null;
@@ -2130,6 +2874,15 @@ async function startServer(options) {
 	};
 	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,
@@ -2144,8 +2897,28 @@ async function startServer(options) {
 		...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,
+		foldTimeoutMs: controlLimits.foldTimeoutMs
+	});
 	const wss = new WebSocketServer({
 		noServer: true,
 		maxPayload: MAX_PAYLOAD
@@ -2158,8 +2931,12 @@ 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) {
@@ -2244,6 +3021,82 @@ 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();
 			const resolved = registeredWorkspace(workspace);
@@ -2271,12 +3124,9 @@ async function startServer(options) {
 		function subscribeStatus(id) {
 			const subscription = openSubscription(id);
 			if (!subscription) return;
+			const envelope = `{"event":"status","subscription":${JSON.stringify(subscription)},"payload":`;
 			const unsubscribe = feeds.subscribe(STATUS_FEED, {
-				item: (payload) => send(socket, {
-					event: "status",
-					subscription,
-					payload
-				}),
+				item: (_payload, text) => send(socket, `${envelope}${text}}`),
 				failed: (message) => {
 					subscriptions.delete(subscription);
 					send(socket, {
@@ -2473,30 +3323,53 @@ async function startServer(options) {
 			});
 			subscriptions.set(subscription, cleanup);
 		}
-		function command(id, args, cwd, result, limits = commandLimits) {
-			if (commands.size >= MAX_COMMANDS) return error(id, "limit-exceeded", `A connection can run ${MAX_COMMANDS} requests at a time.`);
-			const run = runStim(options.stimCli, options.env, args, cwd, limits);
-			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) {
-					const printed = actionOutcome(outcome);
-					return error(id, "stim-failed", printed.ok ? outcome.message : printed.error.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);
@@ -2613,7 +3486,7 @@ async function startServer(options) {
 			if (slot !== void 0 && (typeof slot !== "string" || !SLOT_NAME.test(slot))) return error(id, "bad-request", "params.slot must be 1-64 letters, digits, underscores or hyphens.");
 			const cwd = workspaceDir(id, params.workspace, true);
 			if (!cwd) return;
-			command(id, [
+			const finished = command(id, [
 				platform,
 				"--plan",
 				"--json",
@@ -2625,6 +3498,11 @@ async function startServer(options) {
 			}, {
 				...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) {
@@ -2684,6 +3562,23 @@ async function startServer(options) {
 			}
 			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;
@@ -2717,6 +3612,9 @@ async function startServer(options) {
 			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) {
@@ -2759,6 +3657,7 @@ async function startServer(options) {
 		sampler.stop();
 		if (revocationCheck) clearTimeout(revocationCheck);
 		for (const client of wss.clients) client.terminate();
+		await control.close();
 		await Promise.all([
 			frames.close(),
 			feeds.close(),
@@ -2948,7 +3847,7 @@ async function main() {
 		if (values.json) return void console.log(JSON.stringify({ actions: records }));
 		if (!records.length) console.log("No actions.");
 		for (const record of records) {
-			const outcome = record.ok ? "ok" : `${record.error?.code ?? "failed"}: ${record.error?.message ?? ""}`;
+			const 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(""));
 		}