simulator-use 0.9.0 → 0.10.0

package/dist/cloud/tunnel.js

@@ -0,0 +1,222 @@
+/**
+ * A NoMac phone's tunnel to a backend on this machine (NoMac Simulator plan 10.7 E6): the phone's apps reach
+ * http://127.0.0.1:<port> on the phone, and each connection they make is carried here and dialed to the local port.
+ * The requests that pass are kept (method, path, status, time, size), as a capture of what the app asked the backend.
+ * The tunnel comes back by itself after a dropped connection while the phone runs.
+ */
+import { connect } from "node:net";
+import { ToolError } from "../errors.js";
+import { CLOSE, DATA, dataFrames, frame, FrameReader, HELLO, MAX_CONNECTIONS, OPEN } from "../tunnel-frames.js";
+const KEEP = 200;
+const REQUEST = /^(GET|POST|PUT|PATCH|DELETE|HEAD|OPTIONS) (\S{1,2048}) HTTP\/1\.[01]\r\n/;
+const RESPONSE = /^HTTP\/1\.[01] (\d{3})/;
+// The WebSocket may hold this much unsent before a local connection waits for it.
+const SEND_BUFFER = 4 * 1024 * 1024;
+export class Tunnel {
+    session;
+    localPort;
+    localHost;
+    phonePort;
+    state = "connecting";
+    error;
+    requests = [];
+    connections = 0;
+    api;
+    onRequest;
+    ws;
+    conns = new Map();
+    stopped = false;
+    drops = 0;
+    constructor(api, session, localPort, localHost = "127.0.0.1", onRequest) {
+        this.api = api;
+        this.session = session;
+        this.localPort = localPort;
+        this.localHost = localHost;
+        this.onRequest = onRequest;
+    }
+    /** Opens the tunnel; answers the port the phone's apps reach once the phone's relay listens. */
+    async start() {
+        if (typeof globalThis.WebSocket !== "function")
+            throw new ToolError("cloud tunnel needs Node 22 or later (for its WebSocket).", "Update Node, then call cloud tunnel again.");
+        return this.open();
+    }
+    stop() {
+        this.stopped = true;
+        this.state = "closed";
+        this.ws?.close();
+        for (const conn of this.conns.values())
+            conn.socket.destroy();
+        this.conns.clear();
+    }
+    async open() {
+        const access = await this.api.json("POST", `/api/v1/simulator/sessions/${this.session}/tunnel`, {});
+        const url = String(access.url), token = String(access.token);
+        return new Promise((resolve, reject) => {
+            const ws = new WebSocket(url, [String(access.protocol ?? "nomac.tunnel"), `nomac.token.${token}`]);
+            ws.binaryType = "arraybuffer";
+            this.ws = ws;
+            const reader = new FrameReader();
+            let opened = 0;
+            let answered = false;
+            ws.onmessage = (event) => {
+                let frames;
+                try {
+                    frames = reader.push(Buffer.from(event.data));
+                }
+                catch {
+                    ws.close();
+                    return;
+                }
+                for (const f of frames) {
+                    if (f.type === HELLO) {
+                        this.phonePort = Number(JSON.parse(f.payload.toString("utf8")).port);
+                        this.state = "open";
+                        opened = Date.now();
+                        if (!answered) {
+                            answered = true;
+                            resolve(this.phonePort);
+                        }
+                    }
+                    else if (f.type === OPEN)
+                        this.dial(f.conn);
+                    else if (f.type === DATA)
+                        this.toLocal(f.conn, f.payload);
+                    else if (f.type === CLOSE)
+                        this.drop(f.conn);
+                }
+            };
+            ws.onclose = () => {
+                for (const conn of this.conns.values())
+                    conn.socket.destroy();
+                this.conns.clear();
+                if (this.ws !== ws || this.stopped)
+                    return;
+                if (!answered) {
+                    answered = true;
+                    this.state = "closed";
+                    reject(new ToolError("The phone's tunnel did not open.", "The phone must be ready; call cloud status, then cloud tunnel again."));
+                    return;
+                }
+                // Back after a dropped connection (a NoMac deploy, the network), while the phone runs: a connection that
+                // lasted a minute starts the count again.
+                this.drops = Date.now() - opened > 60_000 ? 1 : this.drops + 1;
+                this.state = "connecting";
+                if (this.drops > 8) {
+                    this.state = "closed";
+                    this.error = "the tunnel kept dropping";
+                    return;
+                }
+                setTimeout(() => {
+                    if (!this.stopped)
+                        this.open().catch((error) => {
+                            this.state = "closed";
+                            this.error = error.message;
+                        });
+                }, Math.min(30_000, 1000 * 2 ** (this.drops - 1)));
+            };
+        });
+    }
+    send(bytes, socket) {
+        const ws = this.ws;
+        if (!ws || ws.readyState !== WebSocket.OPEN)
+            return;
+        ws.send(bytes);
+        if (socket && ws.bufferedAmount > SEND_BUFFER) {
+            socket.pause();
+            const wait = setInterval(() => {
+                if (ws.readyState !== WebSocket.OPEN || ws.bufferedAmount < SEND_BUFFER / 2) {
+                    clearInterval(wait);
+                    socket.resume();
+                }
+            }, 20);
+        }
+    }
+    dial(id) {
+        if (this.conns.size >= MAX_CONNECTIONS) {
+            this.send(frame(CLOSE, id));
+            return;
+        }
+        const socket = connect({ port: this.localPort, host: this.localHost });
+        const conn = { socket };
+        this.conns.set(id, conn);
+        this.connections++;
+        socket.on("data", (chunk) => {
+            this.noteResponse(conn, chunk);
+            for (const f of dataFrames(id, chunk))
+                this.send(f, socket);
+        });
+        socket.on("close", () => {
+            if (this.conns.get(id) !== conn)
+                return;
+            this.conns.delete(id);
+            this.finish(conn);
+            this.send(frame(CLOSE, id));
+        });
+        socket.on("error", (error) => {
+            if (error.code === "ECONNREFUSED")
+                this.error = `nothing listens on ${this.localHost}:${this.localPort} on this machine`;
+            socket.destroy();
+        });
+    }
+    toLocal(id, bytes) {
+        const conn = this.conns.get(id);
+        if (!conn)
+            return;
+        this.noteRequest(conn, bytes);
+        conn.socket.write(bytes);
+    }
+    drop(id) {
+        const conn = this.conns.get(id);
+        if (!conn)
+            return;
+        this.conns.delete(id);
+        this.finish(conn);
+        conn.socket.destroy();
+    }
+    // The capture: a request line at the start of what the app sends, the status line of what comes back.
+    noteRequest(conn, bytes) {
+        if (conn.pending) {
+            conn.pending.entry.bytes += bytes.length;
+            return;
+        }
+        const m = REQUEST.exec(bytes.subarray(0, 2100).toString("latin1"));
+        if (!m)
+            return;
+        conn.answered = undefined;
+        conn.pending = { entry: { method: m[1], path: m[2], bytes: bytes.length, at: new Date().toISOString() }, started: Date.now() };
+    }
+    noteResponse(conn, bytes) {
+        const pending = conn.pending;
+        if (!pending) {
+            if (conn.answered)
+                conn.answered.bytes += bytes.length;
+            return;
+        }
+        pending.entry.bytes += bytes.length;
+        const m = RESPONSE.exec(bytes.subarray(0, 32).toString("latin1"));
+        if (!m)
+            return;
+        pending.entry.status = Number(m[1]);
+        pending.entry.ms = Date.now() - pending.started;
+        this.keep(pending.entry);
+        // The rest of the answer counts here; the next request on this connection (keep-alive) starts a new entry.
+        conn.answered = pending.entry;
+        conn.pending = undefined;
+    }
+    finish(conn) {
+        if (conn.pending && conn.pending.entry.status === undefined)
+            this.keep({ ...conn.pending.entry, ms: Date.now() - conn.pending.started });
+        conn.pending = undefined;
+    }
+    keep(entry) {
+        this.requests.push(entry);
+        if (this.requests.length > KEEP)
+            this.requests.splice(0, this.requests.length - KEEP);
+        this.onRequest?.(entry);
+    }
+}
+/** A request as a line: "GET /api/items → 200 in 34 ms (1.2 KB)"; as it is answered, without its size (still coming). */
+export function describeRequest(r, withSize = true) {
+    const size = r.bytes >= 1024 ? `${(r.bytes / 1024).toFixed(1)} KB` : `${r.bytes} B`;
+    return `${r.method} ${r.path} → ${r.status ?? "no answer"}${r.ms !== undefined ? ` in ${r.ms} ms` : ""}${withSize ? ` (${size})` : ""}`;
+}

package/dist/cloud-hint.js

@@ -1,14 +1,14 @@
 import { setting } from "./settings.js";
 /**
- * Where simulator-use can't run (no Mac, no Xcode, no Simulator runtime), the agent is told where to get a Mac: NoMac,
- * which makes simulator-use, rents agents cloud Macs with Xcode by the minute. Never shown when simulator-use works;
+ * Where simulator-use can't run (no Mac, no Xcode, no Simulator runtime), the agent is told it can run the same
+ * tools on a cloud phone: cloud mode, on NoMac, which makes simulator-use. Never shown when simulator-use works;
  * SIMULATOR_USE_NO_CLOUD_HINT=1 hides it.
  */
 export const NOMAC_URL = "https://nomac.app/?utm_source=simulator-use";
 export function cloudHint() {
     if (setting("NO_CLOUD_HINT"))
         return "";
-    return `No Mac to run it on? NoMac gives your agent a cloud Mac with Xcode and the iOS Simulator ready, billed by the minute: ${NOMAC_URL}`;
+    return `No Mac to run it on? The cloud tool (simulator-use cloud start) runs the same tools on a NoMac cloud iPhone Simulator, $0.80 an hour by the minute: ${NOMAC_URL}`;
 }
 /** A next step, with the hint after it when it is on. */
 export const withCloudHint = (next) => [next, cloudHint()].filter(Boolean).join(" ");

package/dist/engine/apps.js

@@ -1,10 +1,10 @@
 import { spawn } from "node:child_process";
-import { closeSync, existsSync, openSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { closeSync, existsSync, openSync, readFileSync, rmSync, unlinkSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { ToolError } from "../errors.js";
 import { isOurs, run } from "./exec.js";
-import { deviceDir } from "./state.js";
+import { deviceDir, deviceEnv, deviceTimeZone } from "./state.js";
 const simctl = (args, timeoutMs = 60_000) => run("xcrun", ["simctl", ...args], { timeoutMs });
 /** The value of a key in `simctl appinfo`'s old-style plist output. */
 export function plistValue(text, key) {
@@ -48,6 +48,20 @@ export async function install(udid, appPath) {
 export async function consoleFile(udid, bundleId) {
     return join(await deviceDir(udid), `${bundleId}.console.log`);
 }
+/**
+ * A new, empty file at path, open for writing. The previous launch's launcher can still write to the old file at
+ * its own offset: truncating that file left NUL bytes before the next line (October 23). So the old file goes and a
+ * new one is made; the old writer keeps writing into a file no one reads.
+ */
+export function freshFile(path) {
+    try {
+        unlinkSync(path);
+    }
+    catch {
+        // None yet.
+    }
+    return openSync(path, "w");
+}
 /**
  * Launches fresh (any running copy is stopped) and keeps the app's print() output for app_logs.
  * simctl's --stdout wrote nothing on iOS 26.5, so a detached `simctl launch --console-pty` holds the app's
@@ -55,11 +69,14 @@ export async function consoleFile(udid, bundleId) {
  */
 export async function launch(udid, bundleId) {
     const file = await consoleFile(udid, bundleId);
-    const fd = openSync(file, "w");
+    const timeZone = await deviceTimeZone(udid);
+    const env = Object.fromEntries(Object.entries(await deviceEnv(udid)).map(([key, value]) => [`SIMCTL_CHILD_${key}`, value]));
+    const fd = freshFile(file);
     const child = spawn("xcrun", ["simctl", "launch", "--console-pty", "--terminate-running-process", udid, bundleId], {
         detached: true,
         stdio: ["ignore", fd, fd],
-        env: { ...process.env, SIMCTL_CHILD_NSUnbufferedIO: "YES" },
+        // The time zone app_control set (iOS takes a process's TZ) and app_run's env: simctl hands SIMCTL_CHILD_ variables to the app.
+        env: { ...process.env, ...env, SIMCTL_CHILD_NSUnbufferedIO: "YES", ...(timeZone ? { SIMCTL_CHILD_TZ: timeZone } : {}) },
     });
     closeSync(fd);
     // A launch that fails ends the launcher within moments; a running app keeps it alive.

package/dist/engine/native.js

@@ -108,21 +108,31 @@ function parse(line) {
     }
 }
 const engines = new Map();
-/** Phones whose engine would not start: AXe for the rest of this process. */
-const unavailable = new Set();
+/**
+ * Phones whose engine would not start, and when: AXe for a while, then a new engine is tried. A phone that was shut
+ * down (its engine exits, and one started meanwhile fails) gets its engine back once it is booted again, instead of
+ * staying on AXe for the rest of a long-lived MCP server.
+ */
+const unavailable = new Map();
+const RETRY_MS = 30_000;
 async function engineFor(udid) {
     const path = enginePath();
-    if (!path || unavailable.has(udid))
+    if (!path)
+        return undefined;
+    const failedAt = unavailable.get(udid);
+    if (failedAt !== undefined && Date.now() - failedAt < RETRY_MS)
         return undefined;
     let engine = engines.get(udid);
     if (!engine || engine.dead) {
         engine = new Engine(path, udid);
         engines.set(udid, engine);
     }
-    if (await engine.ready)
+    if (await engine.ready) {
+        unavailable.delete(udid);
         return engine;
+    }
     engines.delete(udid);
-    unavailable.add(udid);
+    unavailable.set(udid, Date.now());
     return undefined;
 }
 /**

package/dist/engine/prompts.js

@@ -0,0 +1,71 @@
+/**
+ * iOS's prompts that stop an agent before it reaches the app it asked for: "Open in “Expo Go”?" when a link opens
+ * another app, and the permission prompts an app shows on its first launch (notifications have no simctl grant).
+ * Answered only where the agent asked for the outcome: a link it opened itself, or an app it ran with permissions
+ * granted (app_run's default). With permissions: "ask" the prompts stay, for testing them.
+ */
+import { readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { simctlAction } from "./apps.js";
+import { deviceDir } from "./state.js";
+const OPEN_IN = /^Open in “.+”\?$/;
+// "Would Like to Access the Camera", "would like full access to your Photo Library" (iOS 26), "to use your location".
+const PERMISSION = /would like (to )?(send you notifications|access|full access|use|find and connect)|to use your location|to track your activity/i;
+/** The button that gives the app what it asks, in the order iOS words it. */
+const ALLOWING = ["Allow", "Allow While Using App", "Allow Full Access", "OK"];
+const alertOf = (snap) => (snap.modal === "alert" ? snap.elements.find((e) => e.kind === "alert" && e.label) : undefined);
+const button = (snap, label) => snap.elements.some((e) => e.kind === "button" && e.label === label);
+/** The title of the alert in front, or nothing. */
+export const alertTitle = (snap) => alertOf(snap)?.label;
+/** iOS's "Open in “App”?" in front, with its Open button: the title, or nothing. */
+export function openInPrompt(snap) {
+    const alert = alertOf(snap);
+    return alert && OPEN_IN.test(alert.label) && button(snap, "Open") ? alert.label : undefined;
+}
+/** A permission prompt over the app (named as ui_look names it): its title and the button that allows, or nothing. */
+export function permissionPrompt(snap, app) {
+    if (snap.app !== `${app} · system alert`)
+        return undefined;
+    const alert = alertOf(snap);
+    if (!alert || !PERMISSION.test(alert.label))
+        return undefined;
+    const allow = ALLOWING.find((label) => button(snap, label));
+    return allow ? { title: alert.label, allow } : undefined;
+}
+const modesFile = async (udid) => join(await deviceDir(udid), "permissions.json");
+/** How an app was run on this Simulator: its permissions granted (prompts answered), or iOS asking. */
+export async function permissionMode(udid, bundleId) {
+    try {
+        const modes = JSON.parse(await readFile(await modesFile(udid), "utf8"));
+        return modes[bundleId];
+    }
+    catch {
+        return undefined;
+    }
+}
+export async function setPermissionMode(udid, bundleId, mode) {
+    let modes = {};
+    try {
+        modes = JSON.parse(await readFile(await modesFile(udid), "utf8"));
+    }
+    catch {
+        // The first one.
+    }
+    modes[bundleId] = mode;
+    await writeFile(await modesFile(udid), JSON.stringify(modes));
+}
+/**
+ * Every permission the Simulator can grant the app (simctl privacy grant all: photos, location, contacts, camera,
+ * microphone and the rest), recorded so its first launch's other prompts are answered too. Answers why it could
+ * not, or nothing.
+ */
+export async function grantAll(udid, bundleId) {
+    await setPermissionMode(udid, bundleId, "grant");
+    try {
+        await simctlAction(["privacy", udid, "grant", "all", bundleId], "grant its permissions");
+        return undefined;
+    }
+    catch (error) {
+        return error.message;
+    }
+}

package/dist/engine/simctl.js

@@ -72,7 +72,12 @@ export async function xcodeVersion() {
 /** 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);
+    // "iPhone 17 Pro (iOS 26.5)", the way simulator-use prints a device, picks that runtime's phone; a bare name
+    // means the newest runtime's.
+    const withRuntime = /^(.+?)\s*\((.+)\)$/.exec(want);
+    const matches = devices.filter((d) => d.udid.toLowerCase() === want ||
+        d.name.toLowerCase() === want ||
+        (withRuntime !== null && d.name.toLowerCase() === withRuntime[1] && d.runtime.toLowerCase() === withRuntime[2]));
     return matches.find((d) => d.booted) ?? matches[0];
 }
 /**

package/dist/engine/state.js

@@ -61,3 +61,35 @@ export async function currentApp(udid) {
 export async function setCurrentApp(udid, app) {
     await writeFile(join(await deviceDir(udid), "app.json"), JSON.stringify(app));
 }
+/**
+ * A device's time zone as simulator-use sets it (app_control timezone): iOS has no setting a tool can change, so
+ * every app simulator-use launches gets it as TZ.
+ */
+export async function deviceTimeZone(udid) {
+    return (await deviceSettings(udid)).timeZone;
+}
+export async function setDeviceTimeZone(udid, timeZone) {
+    await setDeviceSettings(udid, { timeZone });
+}
+/** The environment app_run gave the device's apps (env): every later launch passes it, as Xcode's scheme would. */
+export async function deviceEnv(udid) {
+    return (await deviceSettings(udid)).env ?? {};
+}
+export async function setDeviceEnv(udid, env) {
+    await setDeviceSettings(udid, { env: Object.keys(env).length ? env : undefined });
+}
+async function deviceSettings(udid) {
+    try {
+        return JSON.parse(await readFile(join(await deviceDir(udid), "settings.json"), "utf8"));
+    }
+    catch {
+        return {};
+    }
+}
+async function setDeviceSettings(udid, change) {
+    const next = { ...(await deviceSettings(udid)), ...change };
+    for (const key of Object.keys(next))
+        if (next[key] === undefined)
+            delete next[key];
+    await writeFile(join(await deviceDir(udid), "settings.json"), JSON.stringify(next));
+}

package/dist/engine/testcases.js

@@ -0,0 +1,45 @@
+// XCTest: "Test Case '-[DemoTests.SignInTests testSignIn]' passed (0.123 seconds)."
+const XCTEST = /^Test Case '-\[(?:[\w]+\.)?([\w]+) ([\w]+)\]' (passed|failed|skipped) \((\d+(?:\.\d+)?) seconds\)/;
+// XCTest with parallel clones (Xcode 15 on): "Test case 'SignInTests.testSignIn()' passed on 'Clone 1 of iPhone 17 Pro' (0.123 seconds)"
+const XCTEST_CLONES = /^Test case '([\w]+)\.([\w]+)\(\)' (passed|failed|skipped) on '[^']*' \((\d+(?:\.\d+)?) seconds\)/;
+// Swift Testing: "✔ Test signIn() passed after 0.012 seconds." and "✘ Test signIn() failed after 0.010 seconds with 1 issue.",
+// but not its summary, "✔ Test run with 3 tests in 1 suite passed after 0.055 seconds."
+const SWIFT_TESTING = /^[✔✘] Test (?!run with \d+ tests? in )(.+?) (passed|failed) after (\d+(?:\.\d+)?) seconds/;
+const SWIFT_SKIPPED = /^[➜↷] Test (.+?) skipped/;
+export function finishedCase(line) {
+    const text = line.trim();
+    let m = XCTEST.exec(text) ?? XCTEST_CLONES.exec(text);
+    if (m)
+        return { name: `${m[1]}/${m[2]}`, result: m[3], seconds: Number(m[4]) };
+    if ((m = SWIFT_TESTING.exec(text)))
+        return { name: m[1], result: m[2], seconds: Number(m[3]) };
+    if ((m = SWIFT_SKIPPED.exec(text)))
+        return { name: m[1], result: "skipped" };
+    return undefined;
+}
+/** The cases of a run so far: counts, the last one, and the slowest, for job_status while tests run and their answer. */
+export class CaseTally {
+    passed = 0;
+    failed = 0;
+    skipped = 0;
+    last;
+    all = [];
+    add(c) {
+        this[c.result]++;
+        this.last = c;
+        this.all.push(c);
+    }
+    get count() {
+        return this.all.length;
+    }
+    /** "12 passed, 1 failed so far; last: SignInTests/testSignIn failed (0.4 s)". */
+    progress() {
+        const counts = `${this.passed} passed${this.failed ? `, ${this.failed} failed` : ""}${this.skipped ? `, ${this.skipped} skipped` : ""} so far`;
+        return this.last ? `${counts}; last: ${this.last.name} ${this.last.result}${this.last.seconds !== undefined ? ` (${this.last.seconds.toFixed(1)} s)` : ""}` : counts;
+    }
+    /** The slowest cases, when any took a second or more: where a run's time goes. */
+    slowest(n = 3) {
+        const slow = this.all.filter((c) => (c.seconds ?? 0) >= 1).sort((a, b) => (b.seconds ?? 0) - (a.seconds ?? 0)).slice(0, n);
+        return slow.map((c) => `${c.name} ${c.seconds.toFixed(1)} s`).join(", ");
+    }
+}

package/dist/engine/xcode.js

@@ -1,6 +1,6 @@
 import { spawn } from "node:child_process";
 import { createHash } from "node:crypto";
-import { createWriteStream, existsSync, readdirSync, realpathSync } from "node:fs";
+import { createWriteStream, existsSync, readdirSync, readFileSync, realpathSync } from "node:fs";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { basename, dirname, extname, join, relative, resolve } from "node:path";
 import { ToolError } from "../errors.js";
@@ -37,13 +37,39 @@ export async function findProject(where) {
     }
     if (project)
         return { kind: "project", path: join(path, project), name: basename(project, ".xcodeproj"), dir: path };
-    if (entries.includes("app.json") || entries.includes("pubspec.yaml") || entries.some((e) => e.startsWith("capacitor.config"))) {
-        throw new ToolError("Expo, React Native, Flutter and Capacitor projects are not built by app_run yet; Xcode projects are.", "Build it with its own tool for the iOS Simulator, then app_control {action: \"install\", app: \"path/to/App.app\"}.");
+    const ios = join(path, "ios");
+    const hasIos = entries.includes("ios") && existsSync(ios);
+    if (entries.includes("pubspec.yaml")) {
+        throw new ToolError("A Flutter project: Flutter builds it, not app_run.", "Run flutter build ios --simulator, then app_control {action: \"install\", app: \"build/ios/iphonesimulator/Runner.app\"}.");
     }
-    if (entries.includes("ios") && existsSync(join(path, "ios")))
-        return findProject(join(path, "ios"));
+    if (entries.some((e) => e.startsWith("capacitor.config"))) {
+        throw new ToolError("A Capacitor project: its web build is copied into the iOS project first.", `Run npx cap sync ios, then app_run {path: "${join(path, "ios", "App")}"}.`);
+    }
+    if (entries.includes("app.json")) {
+        const expo = isExpo(join(path, "app.json"));
+        if (!hasIos) {
+            throw new ToolError(expo ? "An Expo project with no ios/ folder yet." : "A React Native project with no ios/ folder.", expo ? "Run npx expo prebuild --platform ios to make one, then app_run again; or open the project in Expo Go." : "app_run builds the Xcode project in ios/.");
+        }
+        if (!readdirSync(ios).some((e) => e.endsWith(".xcworkspace")) && existsSync(join(ios, "Podfile"))) {
+            throw new ToolError("ios/ has a Podfile but no workspace yet.", `Run pod install in ${ios}, then app_run again.`);
+        }
+        const found = await findProject(ios);
+        // A Debug build loads its JavaScript from Metro; Release puts it in the app.
+        return { ...found, note: [found.note, "A React Native app: a Debug build loads its JavaScript from Metro (start it first: npx react-native start, or npx expo start), and configuration Release puts it in the app."].filter(Boolean).join(" ") };
+    }
+    if (hasIos)
+        return findProject(ios);
     throw new ToolError(`No Xcode project in ${path}.`, "Pass path: the folder with the .xcodeproj or .xcworkspace.");
 }
+/** An app.json with an "expo" key is Expo's; a React Native CLI project's has only its name. */
+function isExpo(file) {
+    try {
+        return "expo" in JSON.parse(readFileSync(file, "utf8"));
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * XcodeGen makes the project from project.yml, and a spec edit or a new, moved or deleted source file needs a new
  * project, or the build misses it. So the project is regenerated before every build; --use-cache skips the work when
@@ -81,6 +107,27 @@ export async function pickScheme(project, wanted) {
         throw new ToolError(`${basename(project.path)} has no shared schemes.`, "Open it in Xcode once, or share a scheme (Product > Scheme > Manage Schemes).");
     throw new ToolError(`${basename(project.path)} has several schemes: ${own.join(", ")}.`, "Pass scheme.");
 }
+/**
+ * A failed build whose cause has a known fix, said with the fix: the errors alone read like a code problem. A
+ * project that keeps its xcconfig out of git as a template (IceCubesApp does) fails at once from a fresh clone; a
+ * full disk fails deep in the linker (errno 28); packages Xcode could not fetch fail before any compile.
+ */
+export function knownFix(errors, tail) {
+    const text = [...errors.map((e) => e.message), ...tail].join("\n");
+    const xcconfig = /Unable to open base configuration reference file '([^']+\.xcconfig)'/.exec(text)?.[1];
+    if (xcconfig) {
+        const name = basename(xcconfig);
+        return existsSync(`${xcconfig}.template`)
+            ? `the project keeps ${name} as a template: copy ${name}.template to ${name} (fill in its values if it has any), then build again.`
+            : `the project expects ${name}, which is not in its folder (often kept out of git): create it, then build again.`;
+    }
+    if (/No space left on device|errno=28/.test(text))
+        return "the disk is full: free space, or build with clean: true to clear this project's build cache.";
+    if (/Could not resolve package dependencies|Failed to clone repository|package resolution failed/i.test(text)) {
+        return "Xcode could not fetch the project's Swift packages: check the network, and that a private package's repository can be reached from this Mac.";
+    }
+    return undefined;
+}
 const LOCATED = /^(\/[^:]+):(\d+):(?:(\d+):)? (error|warning|fatal error): (.+)$/;
 const BARE = /^(?:xcodebuild: |clang: |ld: |\s*)?(error|fatal error): (.+)$/;
 /** One line of xcodebuild output as an error or warning, or nothing. */
@@ -120,13 +167,31 @@ export function formatIssue(issue, base) {
  * NoMac's ~/drive, makes the next machine's build incremental), else simulator-use's own folder.
  */
 export const cacheDir = () => setting("CACHE_DIR") || stateDir();
-/** Each worktree builds into its own DerivedData, so builds stay incremental and never share products. */
-export function derivedDataFor(project) {
+/**
+ * Each worktree builds into its own DerivedData, so builds stay incremental and never share products; an Xcode other
+ * than the default has its own beside it, since two Xcodes' products and module caches do not mix.
+ */
+export function derivedDataFor(project, xcode) {
     const key = createHash("sha1").update(project.path).digest("hex").slice(0, 12);
-    return join(cacheDir(), "DerivedData", `${project.name}-${key}`);
+    return join(cacheDir(), "DerivedData", `${project.name}-${key}${xcode && !xcode.default ? `-xcode${xcode.version}${xcode.beta ? "b" : ""}` : ""}`);
+}
+/** The environment a build with this Xcode runs in: its DEVELOPER_DIR, unless it is the default. */
+export const xcodeEnv = (xcode) => (xcode && !xcode.default ? { ...process.env, DEVELOPER_DIR: xcode.developer } : process.env);
+/** An Xcode older than the phone's iOS cannot name the phone as a destination: it builds for any Simulator instead. */
+export const noDestination = (result) => result.tail.some((line) => /Unable to find a destination matching/i.test(line));
+/**
+ * xcodebuild, or xcodebuild under taskpolicy's clamp when SIMULATOR_USE_BUILD_CLAMP is utility or background:
+ * on a shared host the phones stay quick while builds run (NoMac Simulator), and what a build starts inherits
+ * the clamp and cannot lift it.
+ */
+export function buildCommand(args) {
+    const clamp = setting("BUILD_CLAMP");
+    if (clamp === "utility" || clamp === "background")
+        return ["/usr/sbin/taskpolicy", ["-c", clamp, "xcodebuild", ...args]];
+    return ["xcodebuild", args];
 }
 export async function build(project, scheme, udid, options) {
-    const derived = derivedDataFor(project);
+    const derived = derivedDataFor(project, options.xcode);
     await mkdir(derived, { recursive: true });
     const log = join(derived, `${options.action ?? "build"}-${Date.now()}.log`);
     const args = [
@@ -137,7 +202,7 @@ export async function build(project, scheme, udid, options) {
         "-configuration",
         options.configuration ?? "Debug",
         "-destination",
-        `id=${udid}`,
+        options.destination ?? `id=${udid}`,
         "-derivedDataPath",
         derived,
         ...(options.extra ?? []),
@@ -147,7 +212,8 @@ export async function build(project, scheme, udid, options) {
     const started = Date.now();
     const out = createWriteStream(log);
     // Its own process group, so a cancel stops the compilers it started too.
-    const child = spawn("xcodebuild", args, { cwd: project.dir, detached: true, stdio: ["ignore", "pipe", "pipe"] });
+    const [command, commandArgs] = buildCommand(args);
+    const child = spawn(command, commandArgs, { cwd: project.dir, detached: true, stdio: ["ignore", "pipe", "pipe"], env: xcodeEnv(options.xcode) });
     options.onCancel?.(() => {
         try {
             process.kill(-child.pid, "SIGTERM");
@@ -194,8 +260,8 @@ export async function build(project, scheme, udid, options) {
     return { ok: code === 0, errors, warnings, log, ms: Date.now() - started, tail };
 }
 /** The .app a Simulator build made: the scheme's own, never a test runner. */
-export function builtApp(project, scheme, configuration = "Debug") {
-    const products = join(derivedDataFor(project), "Build", "Products", `${configuration}-iphonesimulator`);
+export function builtApp(project, scheme, configuration = "Debug", xcode) {
+    const products = join(derivedDataFor(project, xcode), "Build", "Products", `${configuration}-iphonesimulator`);
     if (!existsSync(products))
         return undefined;
     const apps = readdirSync(products).filter((e) => e.endsWith(".app") && !e.endsWith("-Runner.app"));
@@ -252,8 +318,8 @@ export async function projectFor(path, scheme) {
     }
     if (project.note)
         note += `${project.note}\n`;
-    const rememberedScheme = memory?.project === project.path ? memory.scheme : (await remembered(project.dir))?.scheme;
-    const chosen = await pickScheme(project, scheme ?? rememberedScheme);
+    const known = memory?.project === project.path ? memory : await remembered(project.dir);
+    const chosen = await pickScheme(project, scheme ?? known?.scheme);
     await setLastProject(project.path);
-    return { project, scheme: chosen, dir: path ? dir : project.dir, note };
+    return { project, scheme: chosen, dir: path ? dir : project.dir, note, ...(known?.xcode ? { xcode: known.xcode } : {}) };
 }