simulator-use 0.0.0-stage → 0.9.0

package/dist/engine/jobs.js

@@ -0,0 +1,108 @@
+import { randomBytes } from "node:crypto";
+import { setTimeout as delay } from "node:timers/promises";
+import { tryLock } from "./lock.js";
+import { setting } from "../settings.js";
+const jobs = new Map();
+let latest;
+/** Stops every running job: the server is going away, and a build nobody can follow should not keep compiling. */
+export function cancelAllJobs() {
+    for (const job of jobs.values())
+        if (!job.result)
+            job.cancel?.();
+}
+// Node runs no exit handler when a signal ends the process, so the signals stop the jobs themselves.
+process.on("exit", cancelAllJobs);
+for (const signal of ["SIGTERM", "SIGINT", "SIGHUP"]) {
+    process.once(signal, () => {
+        cancelAllJobs();
+        process.exit(128 + { SIGHUP: 1, SIGINT: 2, SIGTERM: 15 }[signal]);
+    });
+}
+export function startJob(title, work) {
+    const id = `job_${randomBytes(4).toString("hex")}`;
+    const job = { id, title, started: Date.now(), step: "starting", tail: [] };
+    const progress = {
+        step: (step) => {
+            job.step = step;
+        },
+        line: (line) => {
+            job.tail.push(line);
+            if (job.tail.length > 20)
+                job.tail.shift();
+        },
+        // Cleared once the part that can be stopped (the build) is over, so a late cancel doesn't claim it stopped.
+        setCancel: (cancel) => {
+            job.cancel = cancel
+                ? () => {
+                    job.cancelled = true;
+                    cancel();
+                }
+                : undefined;
+        },
+        setLog: (file) => {
+            job.log = file;
+        },
+    };
+    job.done = work(progress)
+        .catch((error) => ({ text: error.toText?.() ?? `${title} failed: ${error.message}`, isError: true }))
+        .then((result) => {
+        // Whatever the stopped work reported (a build "fails" when killed), the truth is it was stopped.
+        if (job.cancelled)
+            result = { text: `${title} was stopped by job_cancel after ${elapsed(job)}.`, isError: true };
+        job.result = result;
+        job.cancel = undefined;
+        return result;
+    });
+    jobs.set(id, job);
+    latest = id;
+    return job;
+}
+export const getJob = (id) => jobs.get(id ?? latest ?? "");
+/** Waits for a job up to `ms`, so a caller can answer with the result when it comes soon, or with progress. */
+export async function waitFor(job, ms) {
+    if (job.result)
+        return job.result;
+    return Promise.race([job.done, delay(ms, undefined, { ref: false })]);
+}
+export const elapsed = (job) => {
+    const s = Math.round((Date.now() - job.started) / 1000);
+    return s >= 60 ? `${Math.floor(s / 60)} min ${s % 60} s` : `${s} s`;
+};
+/** A call answers within this (40 s); longer work goes on as a job. */
+export const ANSWER_WITHIN_MS = (Number(setting("JOB_AFTER_S")) || 40) * 1000;
+/** The result if it comes within 40 s, else the job to follow; the CLI just waits. */
+export async function answer(job, waitForJobs) {
+    if (waitForJobs)
+        return job.done;
+    const done = await waitFor(job, ANSWER_WITHIN_MS);
+    if (done)
+        return done;
+    return { text: `${job.title} is still ${job.step} after ${elapsed(job)}: job ${job.id}.\nNext: job_status {job_id: "${job.id}"}; it waits up to 40 s for the result.` };
+}
+/** Which running job holds a project: xcodebuild runs in that project's DerivedData, which only one may use. */
+const projects = new Map();
+/**
+ * Claims a project for a job, or names what already builds it: a job of this process, or the pid of another
+ * simulator-use process (each CLI call is its own). Released when the job ends.
+ */
+export async function claimProject(projectPath, job) {
+    const holder = projects.get(projectPath);
+    if (holder && !holder.result && holder !== job)
+        return holder;
+    // Claimed here first, so a second call of this process waiting on the lock below names this job.
+    projects.set(projectPath, job);
+    const taken = await tryLock(`project-${projectPath}`);
+    if ("holder" in taken) {
+        if (projects.get(projectPath) === job)
+            projects.delete(projectPath);
+        return taken.holder;
+    }
+    void job.done.finally(() => {
+        if (projects.get(projectPath) === job)
+            projects.delete(projectPath);
+        void taken.release();
+    });
+    return undefined;
+}
+/** The job this one is: for work that runs inside it and needs to claim things in its name. */
+export const currentJob = (id) => jobs.get(id);

package/dist/engine/lock.js

@@ -0,0 +1,68 @@
+import { createHash } from "node:crypto";
+import { mkdir, readFile, rm, stat, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { stateDir } from "./state.js";
+const alive = (pid) => {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === "EPERM";
+    }
+};
+/** A lock's directory: names that are not plain words (a project's path) are hashed. */
+const lockDir = (name) => join(stateDir(), `${/^[\w.-]{1,80}$/.test(name) ? name : createHash("sha1").update(name).digest("hex").slice(0, 16)}.lock.d`);
+/**
+ * Takes a lock shared by every simulator-use process on this Mac (each agent, and each CLI call, is its own process).
+ * The lock is a directory, made atomically, holding the owner's pid; a lock whose owner died, or that was left
+ * without a pid for 60 s, is taken over. Returns its release, or the pid that holds it.
+ */
+export async function tryLock(name) {
+    await mkdir(stateDir(), { recursive: true });
+    const lock = lockDir(name);
+    const owner = join(lock, "pid");
+    for (;;) {
+        try {
+            await mkdir(lock);
+            await writeFile(owner, String(process.pid));
+            return {
+                // Only its owner removes it: one taken over from a dead owner belongs to someone else now.
+                release: async () => {
+                    if (Number(await readFile(owner, "utf8").catch(() => "0")) === process.pid)
+                        await rm(lock, { recursive: true, force: true });
+                },
+            };
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+            const holder = Number(await readFile(owner, "utf8").catch(() => "0"));
+            const age = Date.now() - ((await stat(lock).catch(() => undefined))?.mtimeMs ?? Date.now());
+            // An empty pid is a lock being made right now, unless it has been empty for a minute.
+            if ((holder && !alive(holder)) || (!holder && age > 60_000)) {
+                await rm(lock, { recursive: true, force: true });
+                continue;
+            }
+            return { holder };
+        }
+    }
+}
+/** Runs work holding the lock, waiting for it up to waitMs; past that, busy() says why it can't. */
+export async function withLock(name, waitMs, busy, work) {
+    const deadline = Date.now() + waitMs;
+    for (;;) {
+        const taken = await tryLock(name);
+        if ("release" in taken) {
+            try {
+                return await work();
+            }
+            finally {
+                await taken.release();
+            }
+        }
+        if (Date.now() > deadline)
+            throw busy(taken.holder);
+        await new Promise((r) => setTimeout(r, 250));
+    }
+}

package/dist/engine/logs.js

@@ -0,0 +1,115 @@
+import { readdir, readFile, stat } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { ownLines } from "./apps.js";
+import { run } from "./exec.js";
+const LEVELS = { Df: "", I: "info", Db: "debug", E: "error", F: "fault" };
+/** `2026-10-19 01:56:22.114 E  Demo[94957:88904] (Sender) [subsystem:category] message`; sender and subsystem are optional. */
+const COMPACT = /^\d{4}-\d\d-\d\d (\d\d:\d\d:\d\d\.\d+) (\w+)\s+\S+?\[\d+:\w+\] (?:\(([^)]+)\) )?(?:\[([^\]]+)\] )?(.*)$/;
+/** Parses `log show --style compact`. Activity lines (type A) are bookkeeping, never kept. */
+export function parseSystemLog(output, appSubsystem) {
+    const lines = [];
+    for (const raw of output.split("\n")) {
+        const m = COMPACT.exec(raw);
+        if (!m || m[2] === "A")
+            continue;
+        const [, time, type, sender, source = "", text = ""] = m;
+        const [subsystem = "", category = ""] = source.split(":");
+        const tag = subsystem && appSubsystem && subsystem.startsWith(appSubsystem) ? category : source || (sender ? `(${sender})` : "");
+        lines.push({ time: time, level: LEVELS[type] ?? type, text: `${tag ? `${tag}: ` : ""}${text}` });
+    }
+    return lines;
+}
+/**
+ * The app's lines from the Simulator's system log. Apple's frameworks log a great deal from inside the app's
+ * process (UIKit's event dispatch, several lines a tap; on the Simulator, a haptics error every key press), so
+ * by default only what the app itself logged is read, and faults from anywhere; `everything` reads it all.
+ */
+export async function systemLog(udid, executable, seconds, bundleId, everything = false) {
+    const predicate = everything ? `process == "${executable.replace(/"/g, "")}"` : ownLines(executable, bundleId);
+    const { stdout } = await run("xcrun", ["simctl", "spawn", udid, "log", "show", "--style", "compact", "--info", "--last", `${Math.max(1, Math.ceil(seconds))}s`, "--predicate", predicate], {
+        timeoutMs: 12_000,
+    });
+    return parseSystemLog(stdout, bundleId);
+}
+/** Lines from the app's own log stream (startLogStream) that are newer than `since` (ms since 1970). */
+export async function streamedLines(file, since, bundleId) {
+    let text;
+    try {
+        text = await readFile(file, "utf8");
+    }
+    catch {
+        return undefined;
+    }
+    const lines = [];
+    for (const raw of text.split("\n")) {
+        // The stamp is the Mac's local time, as `2026-10-19 02:04:48.818`.
+        const stamp = /^(\d{4}-\d\d-\d\d) (\d\d:\d\d:\d\d\.\d+)/.exec(raw);
+        if (!stamp || new Date(`${stamp[1]}T${stamp[2]}`).getTime() < since)
+            continue;
+        lines.push(...parseSystemLog(raw, bundleId));
+    }
+    return lines;
+}
+/** The app's print() output, without the Simulator's own start-up noise. */
+export function cleanConsole(text) {
+    return text
+        .replace(/\r/g, "")
+        .split("\n")
+        .filter((line) => line.trim() && !/^objc\[\d+\]: Class .* is implemented in both/.test(line));
+}
+/**
+ * Crash reports of a Simulator app land on the Mac itself, in ~/Library/Logs/DiagnosticReports, named after
+ * the app's executable. An .ips file is one JSON header line, then the report as JSON.
+ */
+export async function crashReports(executable, since, limit = 3) {
+    const dir = join(homedir(), "Library", "Logs", "DiagnosticReports");
+    let names;
+    try {
+        names = (await readdir(dir)).filter((n) => n.startsWith(`${executable}-`) && n.endsWith(".ips"));
+    }
+    catch {
+        return [];
+    }
+    const files = await Promise.all(names.map(async (n) => ({ file: join(dir, n), at: (await stat(join(dir, n))).mtimeMs })));
+    const recent = files.filter((f) => f.at >= since).sort((a, b) => b.at - a.at).slice(0, limit);
+    return Promise.all(recent.map(async (f) => {
+        const text = await readFile(f.file, "utf8");
+        // When it crashed, not when macOS finished writing the report (up to a minute later).
+        const time = /"captureTime"\s*:\s*"([^"]+)"/.exec(text)?.[1] ?? new Date(f.at).toISOString();
+        return { file: f.file, time, summary: summarizeIps(text, executable) };
+    }));
+}
+/**
+ * What went wrong and where: the exception, the reason, and the crashing thread from the top down to just past
+ * the app's own last frame (the rest is the framework that called it).
+ */
+export function summarizeIps(text, executable) {
+    const body = text.slice(text.indexOf("\n") + 1);
+    let ips;
+    try {
+        ips = JSON.parse(body);
+    }
+    catch {
+        return ["(unreadable crash report)"];
+    }
+    const out = [];
+    if (ips.exception)
+        out.push(`exception: ${[ips.exception.type, ips.exception.signal].filter(Boolean).join(" ")}`);
+    const reasons = [...(ips.termination?.reasons ?? []), ...Object.values(ips.asi ?? {}).flat(), ips.termination?.indicator ?? ""].filter(Boolean);
+    for (const reason of reasons.slice(0, 3))
+        out.push(`reason: ${reason.replace(/\s+/g, " ").trim()}`);
+    const thread = ips.threads?.find((t) => t.triggered) ?? ips.threads?.[ips.faultingThread ?? 0];
+    const all = thread?.frames ?? [];
+    const imageOf = (f) => ips.usedImages?.[f.imageIndex ?? -1]?.name ?? "?";
+    const own = (f) => Boolean(executable) && (imageOf(f) === executable || imageOf(f).startsWith(`${executable}.`));
+    const lastOwn = all.reduce((last, f, i) => (own(f) ? i : last), -1);
+    const frames = all.slice(0, lastOwn >= 0 ? Math.min(lastOwn + 3, 12) : 8).map((f) => {
+        const image = imageOf(f);
+        const where = f.sourceFile ? ` (${f.sourceFile}:${f.sourceLine ?? "?"})` : "";
+        return `  ${image} ${f.symbol ?? `+${f.imageOffset ?? 0}`}${where}`;
+    });
+    if (frames.length)
+        out.push("crashed thread:", ...frames);
+    return out;
+}

package/dist/engine/native.js

@@ -0,0 +1,210 @@
+import { execFileSync, spawn } from "node:child_process";
+import { existsSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createInterface } from "node:readline";
+import { fileURLToPath } from "node:url";
+import { setting } from "../settings.js";
+/**
+ * The native engine (native/engine): one long-lived process per booted Simulator that keeps CoreSimulator's
+ * HID connection, accessibility and screen buffer open, so a tap is about a millisecond and a full read a few
+ * hundred, where AXe pays one to three seconds per call to set up. When it is missing or fails, every caller
+ * falls back to AXe. It sits beside AXe's frameworks (vendor/axe), which it loads; SIMULATOR_USE_ENGINE points
+ * at another build, or "off" turns it off.
+ */
+export function enginePath() {
+    const override = setting("ENGINE");
+    if (override === "off" || override === "0")
+        return undefined;
+    if (override)
+        return override;
+    const bundled = fileURLToPath(new URL("../../vendor/axe/simulator-use-engine", import.meta.url));
+    return existsSync(bundled) ? bundled : undefined;
+}
+const START_MS = 15_000;
+/**
+ * An engine that answers nothing for this long is hung, and is ended. A request merely slower than its caller's
+ * wait never ends it: a new engine's first read costs 1 to 5 s and its cached web page is lost, and on a phone
+ * copied from another user's golden a new engine could not open an automation session at all (a web field's first
+ * read took 4.2 s against a 3 s wait, and ending the engine then left that phone unreadable).
+ */
+const HUNG_MS = 120_000;
+class Engine {
+    child;
+    lines;
+    queue = Promise.resolve();
+    dead = false;
+    ready;
+    constructor(path, udid) {
+        this.child = spawn(path, ["--udid", udid], { stdio: ["pipe", "pipe", "ignore"] });
+        // The engine closes its automation session when its input ends, so a CLI process may exit at any time:
+        // nothing here keeps Node alive, and the engine finishes on its own.
+        this.child.unref();
+        this.child.stdin?.unref?.();
+        this.child.stdout?.unref?.();
+        this.child.on("exit", () => (this.dead = true));
+        this.child.on("error", () => (this.dead = true));
+        this.lines = createInterface({ input: this.child.stdout })[Symbol.asyncIterator]();
+        this.ready = this.next(START_MS).then((line) => {
+            const ready = parse(line);
+            if (!ready?.ready)
+                this.kill();
+            return Boolean(ready?.ready);
+        }, () => (this.kill(), false));
+    }
+    async next(timeoutMs) {
+        let timer;
+        try {
+            const line = await Promise.race([
+                this.lines.next(),
+                new Promise((_, reject) => (timer = setTimeout(() => reject(new Error("the engine did not answer in time")), timeoutMs))),
+            ]);
+            if (line.done)
+                throw new Error("the engine stopped");
+            return line.value;
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    /**
+     * One request at a time, in order. A caller waits timeoutMs and then gets a busy answer, while the engine
+     * finishes: the next request still waits for this one's answer, which is read and dropped, so answers stay paired
+     * with their requests and the engine stays.
+     */
+    call(request, timeoutMs) {
+        const answer = this.queue.then(async () => {
+            if (this.dead)
+                throw new Error("the engine stopped");
+            this.child.stdin.write(`${JSON.stringify(request)}\n`);
+            try {
+                return parse(await this.next(HUNG_MS)) ?? { ok: false, error: "unreadable answer" };
+            }
+            catch (error) {
+                this.kill();
+                throw error;
+            }
+        });
+        this.queue = answer.catch(() => undefined);
+        let timer;
+        const late = new Promise((resolve) => {
+            timer = setTimeout(() => resolve({ ok: false, busy: true, error: `no answer within ${timeoutMs} ms` }), timeoutMs);
+            timer.unref();
+        });
+        return Promise.race([answer, late]).finally(() => clearTimeout(timer));
+    }
+    kill() {
+        this.dead = true;
+        this.child.stdin?.end();
+        setTimeout(() => this.child.kill(), 2_000).unref();
+    }
+}
+function parse(line) {
+    try {
+        return JSON.parse(line);
+    }
+    catch {
+        return undefined;
+    }
+}
+const engines = new Map();
+/** Phones whose engine would not start: AXe for the rest of this process. */
+const unavailable = new Set();
+async function engineFor(udid) {
+    const path = enginePath();
+    if (!path || unavailable.has(udid))
+        return undefined;
+    let engine = engines.get(udid);
+    if (!engine || engine.dead) {
+        engine = new Engine(path, udid);
+        engines.set(udid, engine);
+    }
+    if (await engine.ready)
+        return engine;
+    engines.delete(udid);
+    unavailable.add(udid);
+    return undefined;
+}
+/**
+ * A request to the phone's engine, or undefined when there is none (the caller uses AXe). An answer with busy set
+ * means the engine is still working on it: the caller goes on without it, never with AXe, whose own automation
+ * session would compete with the engine's.
+ */
+export async function engineCall(udid, request, timeoutMs = 30_000) {
+    const engine = await engineFor(udid);
+    if (!engine)
+        return undefined;
+    try {
+        return await engine.call(request, timeoutMs);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Each AXe read opens and closes an automation session of its own. A phone refuses a session opened too soon after
+ * the last one closed, and then every session after it (measured on iOS 27), so the time goes where the next engine
+ * looks before opening one (native/engine: takeSessionTurn).
+ */
+export function noteSessionClosed(udid) {
+    try {
+        writeFileSync(join(sessionFolder(), `simulator-use-engine-${udid}.lock`), String(Date.now() / 1000), { mode: 0o600 });
+    }
+    catch {
+        // Best effort: the engine still waits for its own turn.
+    }
+}
+let folder;
+/** Where the engine keeps its lock: $TMPDIR, else the user's own temporary folder (as NSTemporaryDirectory()). */
+function sessionFolder() {
+    folder ??= process.env.TMPDIR || execFileSync("getconf", ["DARWIN_USER_TEMP_DIR"], { encoding: "utf8" }).trim() || tmpdir();
+    return folder;
+}
+/** Ends this process's engines (tests, and a phone that was shut down). */
+export function closeEngines(udid) {
+    for (const [id, engine] of engines)
+        if (!udid || id === udid)
+            (engine.kill(), engines.delete(id));
+}
+/**
+ * AXe's batch steps, as the engine's steps. Undefined for any step it does not know, so the whole batch goes to
+ * AXe as before.
+ */
+export function engineSteps(steps) {
+    const out = [];
+    for (const step of steps) {
+        let m;
+        if ((m = step.match(/^tap -x (-?[\d.]+) -y (-?[\d.]+)( --tap-style physical)?$/))) {
+            // Switches and checkboxes need a real touch down and up (see tapStep in ui-act).
+            out.push(m[3] ? { touch: [Number(m[1]), Number(m[2])], hold: 0.1 } : { tap: [Number(m[1]), Number(m[2])] });
+        }
+        else if ((m = step.match(/^sleep ([\d.]+)$/)))
+            out.push({ sleep: Number(m[1]) });
+        else if ((m = step.match(/^key-combo --modifiers ([\d,]+) --key (\d+)$/)))
+            out.push({ combo: { mods: m[1].split(",").map(Number), key: Number(m[2]) } });
+        else if ((m = step.match(/^key (\d+)$/)))
+            out.push({ key: Number(m[1]) });
+        else if ((m = step.match(/^type '([\s\S]*)'$/)))
+            out.push({ type: m[1].replace(/'\\''/g, "'") });
+        else if ((m = step.match(/^touch -x (-?[\d.]+) -y (-?[\d.]+) --down --up --delay ([\d.]+)$/)))
+            out.push({ touch: [Number(m[1]), Number(m[2])], hold: Number(m[3]) });
+        else
+            return undefined;
+    }
+    return out;
+}
+/** AXe's swipe and drag arguments, as an engine request; undefined for anything else. */
+export function engineGesture(args) {
+    const [kind, ...rest] = args;
+    if (kind !== "swipe" && kind !== "drag")
+        return undefined;
+    const value = (flag) => {
+        const i = rest.indexOf(flag);
+        return i >= 0 ? Number(rest[i + 1]) : NaN;
+    };
+    const [x1, y1, x2, y2] = ["--start-x", "--start-y", "--end-x", "--end-y"].map(value);
+    const duration = value("--duration");
+    if ([x1, y1, x2, y2].some((n) => !Number.isFinite(n)))
+        return undefined;
+    return { op: kind, x1, y1, x2, y2, duration: Number.isFinite(duration) ? duration : kind === "drag" ? 0.6 : 0.3 };
+}

package/dist/engine/simctl.js

@@ -0,0 +1,156 @@
+import { withCloudHint } from "../cloud-hint.js";
+import { ToolError } from "../errors.js";
+import { run } from "./exec.js";
+import { withLock } from "./lock.js";
+const NO_SIMULATOR = "This computer can't run the iOS Simulator: it needs macOS with Xcode and a Simulator runtime.";
+/** "com.apple.CoreSimulator.SimRuntime.iOS-26-5" becomes "iOS 26.5". */
+export function runtimeName(identifier) {
+    const match = /SimRuntime\.([A-Za-z]+)-(\d+)-(\d+)(?:-(\d+))?$/.exec(identifier);
+    if (!match)
+        return identifier;
+    const [, os, major, minor, patch] = match;
+    return `${os === "xrOS" ? "visionOS" : os} ${major}.${minor}${patch ? `.${patch}` : ""}`;
+}
+/** Parses `simctl list devices --json`: available devices only, booted first, then by runtime and name. */
+export function parseDevices(json) {
+    const parsed = JSON.parse(json);
+    const devices = [];
+    for (const [runtime, list] of Object.entries(parsed.devices ?? {})) {
+        for (const d of list) {
+            if (d.isAvailable === false)
+                continue;
+            devices.push({ udid: d.udid, name: d.name, state: d.state, runtime: runtimeName(runtime), booted: d.state === "Booted" });
+        }
+    }
+    // iOS before watchOS, tvOS and visionOS (by name, "watchOS 26" would sort first); the newest iOS first;
+    // iPhones before iPads: most agents want a phone.
+    const platform = (d) => (d.runtime.startsWith("iOS ") ? 0 : 1);
+    const version = (d) => d.runtime.replace(/^\S+\s/, "");
+    const family = (d) => ["iPhone", "iPad"].findIndex((p) => d.name.startsWith(p)) >>> 0;
+    return devices.sort((a, b) => Number(b.booted) - Number(a.booted) ||
+        platform(a) - platform(b) ||
+        version(b).localeCompare(version(a), undefined, { numeric: true }) ||
+        family(a) - family(b) ||
+        a.name.localeCompare(b.name, undefined, { numeric: true }));
+}
+/** The MCP server lives for a whole session: one list serves the calls of the next few seconds (0.35 s saved each). */
+const CACHE_MS = 5_000;
+let cached;
+export async function listDevices(fresh = false) {
+    if (process.platform !== "darwin")
+        throw new ToolError(NO_SIMULATOR, withCloudHint("Run simulator-use on a Mac with Xcode."));
+    if (!fresh && cached && Date.now() - cached.at < CACHE_MS)
+        return cached.devices;
+    try {
+        const { stdout } = await run("xcrun", ["simctl", "list", "devices", "--json"], { timeoutMs: 30_000 });
+        cached = { at: Date.now(), devices: parseDevices(stdout) };
+        return cached.devices;
+    }
+    catch (error) {
+        throw listError(error);
+    }
+}
+/**
+ * Why simctl gave no device list. A timeout means the Simulator service is still starting (it can take a minute
+ * the first time after a reboot or an Xcode update), not that this computer can't run it.
+ */
+export function listError(error) {
+    if (/timed out after/.test(error.message)) {
+        return new ToolError("The Simulator service did not answer within 30 s: it can take a minute to start the first time after a reboot or an Xcode update.", "Call again in 30 s.");
+    }
+    return new ToolError(`${NO_SIMULATOR} (${error.message})`, withCloudHint("Install Xcode from the App Store, open it once, then add an iOS Simulator runtime in Settings > Components."));
+}
+export async function xcodeVersion() {
+    try {
+        const { stdout } = await run("xcodebuild", ["-version"], { timeoutMs: 15_000 });
+        return stdout.split("\n")[0]?.trim();
+    }
+    catch {
+        return undefined;
+    }
+}
+/** A device by name or UDID; a name on several runtimes means the booted one, else the newest. */
+export function findDevice(devices, wanted) {
+    const want = wanted.trim().toLowerCase();
+    const matches = devices.filter((d) => d.udid.toLowerCase() === want || d.name.toLowerCase() === want);
+    return matches.find((d) => d.booted) ?? matches[0];
+}
+/**
+ * The device a call works on: the one named (by name or UDID), else the one this agent holds (device_use),
+ * else the only booted one.
+ */
+export function pickDevice(devices, wanted, held) {
+    const booted = devices.filter((d) => d.booted);
+    if (wanted) {
+        const device = findDevice(devices, wanted);
+        if (!device)
+            throw new ToolError(`No Simulator named "${wanted}".`, "Call devices to see the names and UDIDs on this Mac.");
+        if (!device.booted)
+            throw new ToolError(`${device.name} (${device.runtime}) is not booted.`, `Call device_use {device: "${device.udid}"} to boot it.`);
+        return device;
+    }
+    const mine = held && booted.find((d) => d.udid === held);
+    if (mine)
+        return mine;
+    // The device this agent chose was shut down (by another agent's boot, say): never slide onto someone else's.
+    const gone = held && devices.find((d) => d.udid === held);
+    if (gone)
+        throw new ToolError(`${gone.name} (${gone.runtime}), the Simulator this agent was using, is no longer booted.`, `Call device_use {device: "${gone.udid}"} to boot it again, or device_use another.`);
+    if (booted.length === 1)
+        return booted[0];
+    if (!booted.length) {
+        const suggestion = devices.find((d) => d.name.startsWith("iPhone")) ?? devices[0];
+        throw new ToolError("No Simulator is booted.", suggestion ? `Call device_use {device: "${suggestion.name}"} to boot ${suggestion.name} (${suggestion.runtime}).` : "Call devices to see what this Mac has.");
+    }
+    throw new ToolError(`${booted.length} Simulators are booted: ${booted.map((d) => `${d.name} (${d.udid})`).join(", ")}.`, "Call device_use with the one to use, or pass device.");
+}
+/** A call may take 45 s: waiting for another boot and this boot share 40 of them. */
+const BOOT_BUDGET_MS = 40_000;
+const LOCK_WAIT_MS = 20_000;
+/**
+ * One boot at a time on this Mac, across every simulator-use process (each agent runs its own), held in a lock
+ * (lock.ts) that a dead owner's successor takes over.
+ */
+const withBootLock = (work) => withLock("boot", LOCK_WAIT_MS, () => new ToolError("Another Simulator is still booting, and boots never overlap.", "Call device_use again in 30 s."), work);
+/**
+ * Boots a device and waits until it is ready, within the time a call may take. Two Simulators booting at once
+ * on an 8 GB Mac pushed it into swap for minutes (measured October 18), so boots never overlap. With a limit on
+ * booted devices (SIMULATOR_USE_MAX_BOOTED), others are shut down first, inside the lock so two calls can't both
+ * see room.
+ */
+export async function bootDevice(device, maxBooted = Infinity) {
+    const asked = Date.now();
+    return withBootLock(async () => {
+        const started = Date.now();
+        // A boot started outside simulator-use (Xcode, simctl) is waited out too.
+        while (Date.now() - asked < LOCK_WAIT_MS && (await listDevices(true)).some((d) => d.state === "Booting" && d.udid !== device.udid)) {
+            await new Promise((r) => setTimeout(r, 1_000));
+        }
+        const others = (await listDevices(true)).filter((d) => d.booted && d.udid !== device.udid);
+        const shutDown = [];
+        for (const d of others.slice(0, Math.max(0, others.length - (maxBooted - 1)))) {
+            await shutdownDevice(d);
+            shutDown.push(d.name);
+        }
+        try {
+            await run("xcrun", ["simctl", "boot", device.udid], { timeoutMs: 20_000 });
+        }
+        catch (error) {
+            if (!/current state: Booted/i.test(error.message))
+                throw new ToolError(`Could not boot ${device.name}: ${error.message}`);
+        }
+        let ready = true;
+        try {
+            await run("xcrun", ["simctl", "bootstatus", device.udid, "-b"], { timeoutMs: Math.max(5_000, BOOT_BUDGET_MS - (Date.now() - asked)) });
+        }
+        catch {
+            ready = false;
+        }
+        cached = undefined;
+        return { ms: Date.now() - started, ready, waitedMs: started - asked, shutDown };
+    });
+}
+export async function shutdownDevice(device) {
+    await run("xcrun", ["simctl", "shutdown", device.udid], { timeoutMs: 15_000 }).catch(() => undefined);
+    cached = undefined;
+}