simulator-use 0.10.1 → 0.12.0

package/dist/cloud/sync.js

@@ -3,51 +3,190 @@
  * workspace lacks. The manifest (each file's path, size, mtime and SHA-256) goes in pages; the host answers the
  * paths it lacks; those go as one gzip tar, in 256 KiB chunks up to 8 MiB, else to an upload link; place writes
  * them and every mtime (new mtimes alone make Xcode compile again), and removes what the folder no longer has.
- * Build output and dependencies are left out, and left alone on the host.
+ * Build output and dependencies are left out, and left alone on the host. A file's hash is kept in an index on
+ * this machine, so only files that changed since the last sync are read again.
  */
 import { spawn } from "node:child_process";
 import { createHash, randomBytes } from "node:crypto";
-import { lstatSync, readdirSync, readFileSync, readlinkSync, realpathSync } from "node:fs";
-import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { createReadStream, lstatSync, readdirSync, realpathSync } from "node:fs";
+import { mkdir, mkdtemp, readFile, readlink, rename, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join, relative, sep } from "node:path";
 import { run } from "../engine/exec.js";
+import { stateDir } from "../engine/state.js";
+import { setting } from "../settings.js";
 /** Folders a build makes or a package manager fills: never sent, never removed on the host. */
 export const SKIP_DIRS = new Set([".git", ".hg", ".svn", "DerivedData", "build", ".build", "node_modules", "Pods", "xcuserdata", ".swiftpm", ".expo", ".gradle"]);
-const SKIP_FILES = (name) => name === ".DS_Store" || name.endsWith(".xcuserstate");
+const SKIP_FILES = (name) => name === ".DS_Store" || name.endsWith(".xcuserstate") || secretFile(name);
+/**
+ * Key and credential files, never sent even when git tracks them: environment files (but their examples), signing
+ * keys and certificates, provisioning profiles, keystores, SSH keys and .netrc. A Simulator build needs none of them.
+ */
+export const secretFile = (name) => (/^\.env(\..+)?$/.test(name) && !/\.(example|sample|template)$/.test(name)) ||
+    /\.(p8|p12|pfx|pem|key|mobileprovision|provisionprofile|keystore|jks)$/i.test(name) ||
+    /^id_(rsa|dsa|ecdsa|ed25519)(\.pub)?$/.test(name) ||
+    name === ".netrc";
 // The protocol's limits (NoMac's mac-protocol, simManifestEntrySchema and the sim route's body).
 const PAGE_ENTRIES = 1000;
 const PAGE_BYTES = 192 * 1024;
 const CHUNK = 256 * 1024;
 const INLINE_MAX = 8 * 1024 * 1024;
 const ARCHIVE_MAX = 2 * 1024 ** 3;
-/** The project's files as the host is to have them: build output, dependencies and editor state left out. */
-export function listProject(folder) {
-    const out = [];
-    const walk = (dir) => {
+/**
+ * The project's files as the host is to have them: in a git repository, the files git tracks or would track
+ * (.gitignore's rules kept), else the folder's; build output, dependencies, editor state and key or credential files
+ * left out either way. With only (a .app beside others in its folder), that one alone and all of it: a bundle's own
+ * folders (an app's node_modules or build) are part of the app. Files are hashed a few at a time, never blocking the process (a
+ * cloud tunnel runs in it), and a file whose size, mtime, ctime and inode match the index is not read again.
+ */
+export async function listProject(folder, only) {
+    const found = [];
+    const walk = (dir, whole) => {
         for (const name of readdirSync(dir).sort()) {
             if (SKIP_FILES(name))
                 continue;
             const path = join(dir, name);
             const st = lstatSync(path);
             if (st.isDirectory()) {
-                if (!SKIP_DIRS.has(name))
-                    walk(path);
+                if (whole || !SKIP_DIRS.has(name))
+                    walk(path, whole);
                 continue;
             }
-            const rel = relative(folder, path).split(sep).join("/");
-            if (st.isSymbolicLink()) {
-                const target = readlinkSync(path);
-                out.push({ path: rel, size: Buffer.byteLength(target), mtime_ms: Math.floor(st.mtimeMs), sha256: sha256(target), kind: "symlink" });
-            }
-            else if (st.isFile()) {
-                out.push({ path: rel, size: st.size, mtime_ms: Math.floor(st.mtimeMs), sha256: sha256(readFileSync(path)), kind: st.mode & 0o111 ? "executable" : "file" });
-            }
+            if (st.isSymbolicLink() || st.isFile())
+                found.push({ rel: relative(folder, path).split(sep).join("/"), path, st });
         }
     };
-    walk(folder);
+    if (only) {
+        const top = join(folder, only);
+        if (lstatSync(top, { throwIfNoEntry: false })?.isDirectory())
+            walk(top, true);
+    }
+    else {
+        const tracked = await filesInGit(folder);
+        if (!tracked)
+            walk(folder, false);
+        else {
+            for (const rel of tracked.sort()) {
+                const parts = rel.split("/");
+                if (SKIP_FILES(parts.at(-1)) || parts.slice(0, -1).some((part) => SKIP_DIRS.has(part)))
+                    continue;
+                const path = join(folder, ...parts);
+                const st = lstatSync(path, { throwIfNoEntry: false });
+                if (st && (st.isSymbolicLink() || st.isFile()))
+                    found.push({ rel, path, st });
+            }
+        }
+    }
+    // Windows keeps no executable bit: git's index has it for the files it tracks (a build phase's script).
+    const gitExecutable = process.platform === "win32" ? await executablesInGit(folder) : undefined;
+    const indexed = setting("SYNC_INDEX") !== "0";
+    const file = indexFile(folder, only);
+    const last = indexed ? await readIndex(file) : undefined;
+    const scanned = Date.now();
+    const next = {};
+    const out = new Array(found.length);
+    await eachLimit(found, HASHING, async ({ rel, path, st }, i) => {
+        if (st.isSymbolicLink()) {
+            const target = await readlink(path);
+            out[i] = { path: rel, size: Buffer.byteLength(target), mtime_ms: Math.floor(st.mtimeMs), sha256: sha256(target), kind: "symlink" };
+            return;
+        }
+        const known = last?.files[rel];
+        // Git's rule for a racy entry: a file changed within RACY_MS of the last scan may have changed again since,
+        // with the same mtime, so it is read again.
+        const same = known && known.size === st.size && known.mtime_ms === st.mtimeMs && known.ctime_ms === st.ctimeMs && known.ino === st.ino && st.mtimeMs < last.scanned_ms - RACY_MS;
+        const hash = same ? known.sha256 : await hashFile(path, st.size);
+        next[rel] = { size: st.size, mtime_ms: st.mtimeMs, ctime_ms: st.ctimeMs, ino: st.ino, sha256: hash };
+        const executable = gitExecutable ? gitExecutable.has(rel) : Boolean(st.mode & 0o111);
+        out[i] = { path: rel, size: st.size, mtime_ms: Math.floor(st.mtimeMs), sha256: hash, kind: executable ? "executable" : "file" };
+    });
+    if (indexed)
+        await writeIndex(file, { scanned_ms: scanned, files: next }).catch(() => undefined);
     return out;
 }
+/** The files git tracks as executable (mode 100755) under folder, by their path from it; none outside a repository. */
+/**
+ * The files git tracks in folder, or would (untracked but not ignored), from the folder, a submodule's too; undefined
+ * when folder is not a repository's top (or git is not there).
+ */
+export async function filesInGit(folder) {
+    try {
+        const top = (await run("git", ["-C", folder, "rev-parse", "--show-toplevel"], { timeoutMs: 5_000 })).stdout.trim();
+        if (realpathSync(top) !== realpathSync(folder))
+            return undefined;
+    }
+    catch {
+        return undefined;
+    }
+    const list = async (dir, prefix, depth) => {
+        const listed = (await run("git", ["-C", dir, "ls-files", "-co", "--exclude-standard", "-z"], { timeoutMs: 60_000 })).stdout.split("\0").filter(Boolean);
+        const out = [];
+        for (const rel of listed.map((path) => path.replace(/\/+$/, ""))) {
+            // A submodule (or a repository inside) is listed as its folder: its own files, by its own rules.
+            if (depth < 4 && lstatSync(join(dir, rel), { throwIfNoEntry: false })?.isDirectory())
+                out.push(...(await list(join(dir, rel), `${prefix}${rel}/`, depth + 1).catch(() => [])));
+            else
+                out.push(`${prefix}${rel}`);
+        }
+        return out;
+    };
+    try {
+        return await list(folder, "", 0);
+    }
+    catch {
+        return undefined;
+    }
+}
+export async function executablesInGit(folder) {
+    try {
+        const listed = (await run("git", ["-C", folder, "ls-files", "-s", "-z"], { timeoutMs: 30_000 })).stdout;
+        // Each entry: <mode> <object> <stage>\t<path>, NUL-separated; the paths are from the folder.
+        return new Set(listed.split("\0").filter((e) => e.startsWith("100755 ")).map((e) => e.slice(e.indexOf("\t") + 1)));
+    }
+    catch {
+        return new Set();
+    }
+}
+/** Files hashed at once. */
+const HASHING = 8;
+/** A file changed within this long of a scan is read again at the next one (coarse mtimes on some file systems). */
+const RACY_MS = 2_000;
+const indexFile = (folder, only) => join(stateDir(), "sync-index", `${sha256(`${realpathSync(folder)}\0${only ?? ""}`).slice(0, 32)}.json`);
+async function readIndex(file) {
+    try {
+        const index = JSON.parse(await readFile(file, "utf8"));
+        return typeof index.scanned_ms === "number" && index.files && typeof index.files === "object" ? index : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+async function writeIndex(file, index) {
+    await mkdir(join(stateDir(), "sync-index"), { recursive: true });
+    const tmp = `${file}.${process.pid}.tmp`;
+    await writeFile(tmp, JSON.stringify(index), { mode: 0o600 });
+    await rename(tmp, file);
+}
+/** A file's SHA-256: small files read at once, larger ones streamed. */
+async function hashFile(path, size) {
+    if (size < 1024 * 1024)
+        return sha256(await readFile(path));
+    const hash = createHash("sha256");
+    for await (const chunk of createReadStream(path))
+        hash.update(chunk);
+    return hash.digest("hex");
+}
+/** Runs work on each item, at most limit at a time. */
+async function eachLimit(items, limit, work) {
+    let next = 0;
+    const worker = async () => {
+        while (next < items.length) {
+            const i = next++;
+            await work(items[i], i);
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(limit, items.length) }, worker));
+}
 const sha256 = (data) => createHash("sha256").update(data).digest("hex");
 /** Pages of at most 1000 entries and about 192 KiB each, in the manifest's order. */
 export function pages(entries) {
@@ -110,7 +249,7 @@ async function pack(folder, paths, file) {
 export async function syncFolder(api, session, folder, options = {}) {
     const { only, onStep } = options;
     const started = Date.now();
-    const entries = listProject(folder).filter((e) => !only || e.path === only || e.path.startsWith(`${only}/`));
+    const entries = await listProject(folder, only);
     if (!entries.length)
         throw new Error(`${folder} has no files to send.`);
     const project = options.project ?? (await projectId(folder));
@@ -119,11 +258,15 @@ export async function syncFolder(api, session, folder, options = {}) {
     if (book.length > 256)
         throw new Error(`${folder} has ${entries.length} files: more than NoMac's sync takes (256 pages).`);
     onStep?.(`listing ${entries.length} files`);
-    const missing = [];
-    for (let page = 0; page < book.length; page++) {
-        const answer = await api.json("POST", `/api/v1/simulator/sessions/${session}/sync`, { op: "manifest", sync, project, page, pages: book.length, entries: book[page] });
-        missing.push(...(answer.missing ?? []));
-    }
+    // Pages go 4 at a time: the host keeps each by its number, and places once it has them all.
+    const answered = new Array(book.length);
+    await eachLimit(book, 4, async (entriesOfPage, page) => {
+        const answer = await api.json("POST", `/api/v1/simulator/sessions/${session}/sync`, { op: "manifest", sync, project, page, pages: book.length, entries: entriesOfPage });
+        // Only paths this page listed are packed: an answer naming any other file of the folder sends nothing more.
+        const listed = new Set(entriesOfPage.map((e) => e.path));
+        answered[page] = (answer.missing ?? []).filter((path) => typeof path === "string" && listed.has(path));
+    });
+    const missing = answered.flat();
     let archive;
     let bytes = 0;
     if (missing.length) {

package/dist/cloud/tunnel.js

@@ -13,26 +13,32 @@ 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 {
+    /** How long the phone's relay has to answer once the connection is up; tests shorten it. */
+    static helloWaitMs = 30_000;
     session;
     localPort;
     localHost;
     phonePort;
     state = "connecting";
     error;
+    /** Said once with the next answer: the phone's port changed when the tunnel came back. */
+    notice;
     requests = [];
     connections = 0;
     api;
     onRequest;
+    onNotice;
     ws;
     conns = new Map();
     stopped = false;
     drops = 0;
-    constructor(api, session, localPort, localHost = "127.0.0.1", onRequest) {
+    constructor(api, session, localPort, localHost = "127.0.0.1", onRequest, onNotice) {
         this.api = api;
         this.session = session;
         this.localPort = localPort;
         this.localHost = localHost;
         this.onRequest = onRequest;
+        this.onNotice = onNotice;
     }
     /** Opens the tunnel; answers the port the phone's apps reach once the phone's relay listens. */
     async start() {
@@ -58,6 +64,15 @@ export class Tunnel {
             const reader = new FrameReader();
             let opened = 0;
             let answered = false;
+            // A relay that never says which port it took would leave cloud tunnel waiting for ever.
+            const silent = setTimeout(() => {
+                if (answered)
+                    return;
+                answered = true;
+                this.stop();
+                this.error = "the phone's relay did not answer";
+                reject(new ToolError(`The phone's tunnel did not open within ${Math.max(1, Math.round(Tunnel.helloWaitMs / 1000))} s.`, "The phone must be ready; call cloud status, then cloud tunnel again."));
+            }, Tunnel.helloWaitMs);
             ws.onmessage = (event) => {
                 let frames;
                 try {
@@ -69,9 +84,16 @@ export class Tunnel {
                 }
                 for (const f of frames) {
                     if (f.type === HELLO) {
-                        this.phonePort = Number(JSON.parse(f.payload.toString("utf8")).port);
+                        const port = Number(JSON.parse(f.payload.toString("utf8")).port);
+                        // The host keeps the port when it can; when it could not, an app pointed at the old one fails.
+                        if (this.phonePort !== undefined && port !== this.phonePort) {
+                            this.notice = `The tunnel came back on another port of the phone, ${port} (it was ${this.phonePort}): app_run again with env "API_URL=http://127.0.0.1:${port}" for an app that used the old one.`;
+                            this.onNotice?.(this.notice);
+                        }
+                        this.phonePort = port;
                         this.state = "open";
                         opened = Date.now();
+                        clearTimeout(silent);
                         if (!answered) {
                             answered = true;
                             resolve(this.phonePort);
@@ -86,6 +108,7 @@ export class Tunnel {
                 }
             };
             ws.onclose = () => {
+                clearTimeout(silent);
                 for (const conn of this.conns.values())
                     conn.socket.destroy();
                 this.conns.clear();

package/dist/cloud-hint.js

@@ -12,3 +12,7 @@ export function cloudHint() {
 }
 /** A next step, with the hint after it when it is on. */
 export const withCloudHint = (next) => [next, cloudHint()].filter(Boolean).join(" ");
+/** The next step on a machine that can't run the iOS Simulator: a cloud phone first, when the hint is on. */
+export function cloudFirst(otherwise) {
+    return setting("NO_CLOUD_HINT") ? otherwise : `cloud start runs every tool on a NoMac cloud iPhone Simulator, $0.80 an hour by the minute (${NOMAC_URL}); then call this again. Or: ${otherwise.replace(/^./, (c) => c.toLowerCase())}`;
+}

package/dist/engine/apps.js

@@ -4,6 +4,7 @@ import { join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { ToolError } from "../errors.js";
 import { isOurs, run } from "./exec.js";
+import { laterVersion } from "./xcode.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. */
@@ -36,11 +37,17 @@ export async function bundleIdOf(appPath) {
     const { stdout } = await run("plutil", ["-extract", "CFBundleIdentifier", "raw", plist], { timeoutMs: 10_000 });
     return stdout.trim();
 }
-export async function install(udid, appPath) {
+/** Installs a .app; runtime ("iOS 27.0", the Simulator's) lets a refusal say when the app needs a later iOS. */
+export async function install(udid, appPath, runtime) {
     try {
         await simctl(["install", udid, appPath], 120_000);
     }
     catch (error) {
+        const phone = runtime && /^iOS (\d+(?:\.\d+)*)$/.exec(runtime)?.[1];
+        const needs = phone ? (await run("plutil", ["-extract", "MinimumOSVersion", "raw", join(appPath, "Info.plist")], { timeoutMs: 10_000 }).catch(() => undefined))?.stdout.trim() : undefined;
+        if (phone && needs && laterVersion(needs, phone)) {
+            throw new ToolError(`Could not install ${appPath}: it needs iOS ${needs} (its deployment target) and this Simulator runs ${runtime}.`, `Build it with a deployment target of iOS ${phone} or earlier (IPHONEOS_DEPLOYMENT_TARGET), then install it again.`);
+        }
         throw new ToolError(`Could not install ${appPath}: ${error.message}`, "Check it is built for the Simulator (iphonesimulator), not a device.");
     }
 }
@@ -62,11 +69,6 @@ export function freshFile(path) {
     }
     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
- * output instead, writing to a file until the app ends; NSUnbufferedIO is what Xcode sets so lines arrive at once.
- */
 export async function launch(udid, bundleId) {
     const file = await consoleFile(udid, bundleId);
     const timeZone = await deviceTimeZone(udid);
@@ -79,6 +81,8 @@ export async function launch(udid, bundleId) {
         env: { ...process.env, ...env, SIMCTL_CHILD_NSUnbufferedIO: "YES", ...(timeZone ? { SIMCTL_CHILD_TZ: timeZone } : {}) },
     });
     closeSync(fd);
+    let ended = false;
+    child.once("exit", () => (ended = true));
     // A launch that fails ends the launcher within moments; a running app keeps it alive.
     const code = await new Promise((resolve) => {
         const timer = setTimeout(() => resolve(undefined), 2_000);
@@ -93,6 +97,7 @@ export async function launch(udid, bundleId) {
         }
         throw new ToolError(`Could not launch ${bundleId}: ${output.split("\n").slice(-3).join(" ")}`);
     }
+    return { ended: () => ended };
 }
 /** The app's own system log lines, streamed to a file while simulator-use watches it. */
 export async function streamFile(udid, bundleId) {
@@ -158,26 +163,32 @@ export async function pushPayload(udid, bundleId, payload) {
         child.stdin.end(payload);
     });
 }
+/** Runs xcrun with the text on its input: what is typed never goes in an argument, which every user of a Mac can read. */
+export function withInput(args, input, timeoutMs) {
+    return new Promise((resolve, reject) => {
+        const child = spawn("xcrun", args, { stdio: ["pipe", "ignore", "pipe"] });
+        let stderr = "";
+        const timer = setTimeout(() => child.kill("SIGKILL"), timeoutMs);
+        child.stderr.on("data", (d) => (stderr += d));
+        child.on("error", (error) => (clearTimeout(timer), reject(error)));
+        child.on("close", (code, signal) => (clearTimeout(timer), code === 0 ? resolve() : reject(new ToolError(stderr.trim() || (signal ? `ended by ${signal}` : `exit ${code}`)))));
+        child.stdin.on("error", () => { });
+        child.stdin.end(input);
+    });
+}
 /** Puts text on the Simulator's clipboard, for pasting what the keyboard can't type (é, 日本, emoji). */
 export async function setPasteboard(udid, text) {
     try {
-        await new Promise((resolve, reject) => {
-            const child = spawn("xcrun", ["simctl", "pbcopy", udid], { stdio: ["pipe", "ignore", "pipe"] });
-            let stderr = "";
-            child.stderr.on("data", (d) => (stderr += d));
-            child.on("error", reject);
-            child.on("close", (code, signal) => (code === 0 ? resolve() : reject(new ToolError(`Could not set the Simulator's clipboard: ${stderr.trim() || signal || `exit ${code}`}`))));
-            child.stdin.end(text);
-        });
+        await withInput(["simctl", "pbcopy", udid], text, 15_000);
     }
     catch (error) {
         // A macOS user with no screen session (a shared Simulator host's users) has no pasteboard server, and simctl
-        // pbcopy crashes: the helper sets the phone's own pasteboard from inside the phone instead.
+        // pbcopy crashes: the helper sets the phone's own pasteboard from inside the phone instead, from its input.
         const helper = pasteHelper();
         if (!helper)
-            throw error;
+            throw new ToolError(`Could not set the Simulator's clipboard: ${error.message}`);
         try {
-            await simctl(["spawn", udid, helper, text], 15_000);
+            await withInput(["simctl", "spawn", udid, helper, "-"], text, 15_000);
         }
         catch (fallback) {
             throw new ToolError(`Could not set the Simulator's clipboard: ${error.message}; from inside the phone: ${fallback.message}`);

package/dist/engine/axe.js

@@ -79,6 +79,20 @@ export async function screenshot(udid, points) {
         await rm(dir, { recursive: true, force: true });
     }
 }
+/** The screen at the device's full resolution, as a PNG in file: for a person, a report or a store, not the agent's eyes. */
+export async function screenshotFile(udid, file) {
+    const answer = await engineCall(udid, { op: "screenshot", png_path: file });
+    if (answer?.ok && existsSync(file))
+        return;
+    if (answer?.busy)
+        throw new ToolError("The screenshot took more than 30 s.", "Take it again: the phone is still working on an earlier request.");
+    try {
+        await run(axePath(), ["screenshot", "--output", file, "--udid", udid], { timeoutMs: 30_000 });
+    }
+    catch (error) {
+        throw new ToolError(`Could not take a screenshot: ${error.message}`);
+    }
+}
 /**
  * Any AXe command may open and close an automation session of its own (a slider is found by its id), so each one is
  * followed by the time the next engine waits from (noteSessionClosed).

package/dist/engine/exec.js

@@ -3,11 +3,13 @@ import { setting } from "../settings.js";
 /** Runs a program without a shell. Rejects with its stderr when it fails or runs past the timeout. */
 export function run(file, args, options = {}) {
     const started = Date.now();
+    // A program under the build's clamp (taskpolicy -c <clamp> <program> ...) is named for itself, not for taskpolicy.
+    const [program, shown] = file === "/usr/sbin/taskpolicy" && args[0] === "-c" && args[2] ? [args[2], args.slice(3)] : [file, args];
     return new Promise((resolve, reject) => {
-        execFile(file, args, { timeout: options.timeoutMs ?? 30_000, maxBuffer: options.maxBytes ?? 64 * 1024 * 1024, encoding: "utf8" }, (error, stdout, stderr) => {
+        execFile(file, args, { timeout: options.timeoutMs ?? 30_000, maxBuffer: options.maxBytes ?? 64 * 1024 * 1024, encoding: "utf8", ...(options.env ? { env: options.env } : {}) }, (error, stdout, stderr) => {
             // SIMULATOR_USE_DEBUG=1 prints every program run and how long it took, to find where time goes.
             if (setting("DEBUG"))
-                process.stderr.write(`simulator-use:   ${file.split("/").pop()} ${args.slice(0, 2).join(" ")} ${Date.now() - started} ms${error ? " (failed)" : ""}\n`);
+                process.stderr.write(`simulator-use:   ${program.split("/").pop()} ${shown.slice(0, 2).join(" ")} ${Date.now() - started} ms${error ? " (failed)" : ""}\n`);
             if (!error)
                 return resolve({ stdout, stderr });
             const code = error.code;
@@ -16,7 +18,7 @@ export function run(file, args, options = {}) {
                 : error.killed
                     ? `timed out after ${Math.round((options.timeoutMs ?? 30_000) / 1000)} s`
                     : (stderr || error.message).trim();
-            reject(Object.assign(new Error(`${file.split("/").pop()} ${args[0] ?? ""}: ${reason}`), { stderr, code: error.code }));
+            reject(Object.assign(new Error(`${program.split("/").pop()} ${shown[0] ?? ""}: ${reason}`), { stderr, code: error.code }));
         });
     });
 }

package/dist/engine/jobs.js

@@ -10,12 +10,24 @@ export function cancelAllJobs() {
         if (!job.result)
             job.cancel?.();
 }
-// Node runs no exit handler when a signal ends the process, so the signals stop the jobs themselves.
+/** Work that must end before a signal ends the process (a cloud phone to stop, a tunnel to close). */
+const beforeExit = new Set();
+/** Runs work when a signal ends the process, up to 15 s in all; answers how to take it back. */
+export function onSignalExit(work) {
+    beforeExit.add(work);
+    return () => beforeExit.delete(work);
+}
+// Node runs no exit handler when a signal ends the process, so the signals stop the jobs themselves. A second
+// signal while that work runs ends the process at once (the handler is gone by then).
 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]);
+        const code = 128 + { SIGHUP: 1, SIGINT: 2, SIGTERM: 15 }[signal];
+        if (!beforeExit.size)
+            process.exit(code);
+        const work = [...beforeExit].map((w) => w().catch(() => undefined));
+        void Promise.race([Promise.all(work), delay(15_000, undefined, { ref: false })]).finally(() => process.exit(code));
     });
 }
 export function startJob(title, work) {

package/dist/engine/logs.js

@@ -60,10 +60,12 @@ export function cleanConsole(text) {
 }
 /**
  * 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.
+ * the app's executable. An .ips file is one JSON header line, then the report as JSON. Another app with the same
+ * executable name, or the same app on another Simulator, writes reports there too: a report is this app's when its
+ * header's bundleID is the app's, and this device's when its process path (or coalition) names the device.
  */
-export async function crashReports(executable, since, limit = 3) {
-    const dir = join(homedir(), "Library", "Logs", "DiagnosticReports");
+export async function crashReports(executable, since, of = {}, limit = 3) {
+    const dir = of.dir ?? join(homedir(), "Library", "Logs", "DiagnosticReports");
     let names;
     try {
         names = (await readdir(dir)).filter((n) => n.startsWith(`${executable}-`) && n.endsWith(".ips"));
@@ -72,13 +74,38 @@ export async function crashReports(executable, since, limit = 3) {
         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 recent = files.filter((f) => f.at >= since).sort((a, b) => b.at - a.at);
+    const out = [];
+    for (const f of recent) {
+        if (out.length >= limit)
+            break;
         const text = await readFile(f.file, "utf8");
+        if (!reportOf(text, of.bundleId, of.udid))
+            continue;
         // 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) };
-    }));
+        out.push({ file: f.file, time, summary: summarizeIps(text, executable) });
+    }
+    return out;
+}
+/** Whether a report is this app's on this device; a report without the field to tell is kept. */
+function reportOf(text, bundleId, udid) {
+    const newline = text.indexOf("\n");
+    let header = {};
+    let body = {};
+    try {
+        header = JSON.parse(text.slice(0, newline < 0 ? undefined : newline));
+        body = JSON.parse(text.slice(newline + 1));
+    }
+    catch {
+        // An unreadable part tells nothing.
+    }
+    if (bundleId && typeof header.bundleID === "string" && header.bundleID !== bundleId)
+        return false;
+    const where = [body.procPath, body.coalitionName].filter((v) => typeof v === "string");
+    if (udid && where.length && !where.some((w) => w.includes(`/Devices/${udid}/`) || w.endsWith(`.${udid}`)))
+        return false;
+    return true;
 }
 /**
  * What went wrong and where: the exception, the reason, and the crashing thread from the top down to just past

package/dist/engine/simctl.js

@@ -1,4 +1,6 @@
-import { withCloudHint } from "../cloud-hint.js";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { cloudFirst, withCloudHint } from "../cloud-hint.js";
 import { ToolError } from "../errors.js";
 import { run } from "./exec.js";
 import { withLock } from "./lock.js";
@@ -36,9 +38,30 @@ export function parseDevices(json) {
 /** 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) {
+/** The developer folder Xcode was found in (DEVELOPER_DIR, or none for xcode-select's): it does not go away. */
+let xcodeFound;
+/**
+ * Why this machine can't run the iOS Simulator at all, or nothing: not a Mac, or a Mac without Xcode (none, or only
+ * the Command Line Tools, which have no simctl). Checked before any tool that needs the Simulator, so the agent
+ * reads that and its way on, never a build tool's error. xcode-select -p never asks a person to install anything.
+ */
+export async function simulatorMissing() {
     if (process.platform !== "darwin")
-        throw new ToolError(NO_SIMULATOR, withCloudHint("Run simulator-use on a Mac with Xcode."));
+        return new ToolError("This machine can't run the iOS Simulator: it needs a Mac with Xcode.", cloudFirst("Run simulator-use on a Mac with Xcode."));
+    const asked = process.env.DEVELOPER_DIR ?? "";
+    if (xcodeFound === asked)
+        return undefined;
+    const developer = asked || (await run("xcode-select", ["-p"], { timeoutMs: 10_000 }).then((r) => r.stdout.trim(), () => ""));
+    if (developer && existsSync(join(developer, "usr", "bin", "simctl"))) {
+        xcodeFound = asked;
+        return undefined;
+    }
+    return new ToolError("This Mac has no Xcode, so it can't run the iOS Simulator (the Command Line Tools alone have none).", cloudFirst("Install Xcode from the App Store and open it once."));
+}
+export async function listDevices(fresh = false) {
+    const missing = process.platform !== "darwin" ? await simulatorMissing() : undefined;
+    if (missing)
+        throw missing;
     if (!fresh && cached && Date.now() - cached.at < CACHE_MS)
         return cached.devices;
     try {

package/dist/engine/state.js

@@ -1,4 +1,4 @@
-import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { chmodSync, lstatSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
@@ -12,8 +12,30 @@ import { setting } from "../settings.js";
  */
 let held;
 let persist = false;
-/** Where simulator-use keeps its files: SIMULATOR_USE_STATE_DIR, else simulator-use in the user's temporary folder. */
-export const stateDir = () => setting("STATE_DIR") || join(tmpdir(), "simulator-use");
+/**
+ * Where simulator-use keeps its files: SIMULATOR_USE_STATE_DIR, else a folder of this user's in the temporary folder,
+ * readable by this user alone (ownStateDir).
+ */
+let own;
+export const stateDir = () => setting("STATE_DIR") || (own ??= ownStateDir(tmpdir()));
+/**
+ * simulator-use's folder in base, this user's alone: macOS gives each user a temporary folder of their own, but
+ * Linux's /tmp is shared, so there the folder is named for the user. Made 0700; one that is a link, or another
+ * user's, is refused, and one others can read is closed.
+ */
+export function ownStateDir(base, platform = process.platform) {
+    const uid = process.getuid?.();
+    if (uid === undefined || platform === "win32")
+        return join(base, "simulator-use");
+    const dir = join(base, platform === "darwin" ? "simulator-use" : `simulator-use-${uid}`);
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const st = lstatSync(dir);
+    if (!st.isDirectory() || st.uid !== uid)
+        throw new Error(`${dir} is not this user's own folder (a link, or another user's). Set SIMULATOR_USE_STATE_DIR to a folder of yours.`);
+    if (st.mode & 0o077)
+        chmodSync(dir, 0o700);
+    return dir;
+}
 const heldFile = () => join(stateDir(), "held-device.json");
 /** The CLI keeps the held device between its calls. */
 export function persistHeld() {