simulator-use 0.10.1 → 0.11.0

package/dist/hosted.js

@@ -6,7 +6,7 @@
 import { execFile, spawn } from "node:child_process";
 import { createHash } from "node:crypto";
 import { createReadStream, createWriteStream, existsSync, statSync } from "node:fs";
-import { chmod, lstat, lutimes, mkdir, mkdtemp, readdir, readFile, readlink, rename, rm, unlink, writeFile } from "node:fs/promises";
+import { chmod, lstat, lutimes, mkdir, mkdtemp, open, readdir, readFile, readlink, realpath, rename, rm, unlink, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { basename, dirname, join, sep } from "node:path";
 import { Readable } from "node:stream";
@@ -16,8 +16,10 @@ import { closeEngines, engineCall } from "./engine/native.js";
 import { cancelAllJobs } from "./engine/jobs.js";
 import { listDevices, pickDevice } from "./engine/simctl.js";
 import { heldDevice, stateDir } from "./engine/state.js";
+import { describeTarget, parseStep } from "./act/steps.js";
 import { normalizeRemote, SKIP_DIRS } from "./cloud/sync.js";
 import { callTool } from "./registry.js";
+import { fetchState, uploadState } from "./state-archive.js";
 const PROJECT = /^prj_[a-f0-9]{32}$/;
 const SYNC = /^sync_[a-f0-9]{40}$/;
 const SHA = /^[a-f0-9]{64}$/;
@@ -31,6 +33,22 @@ const syncs = new Map();
 const invalid = (message) => Object.assign(new Error(message), { code: -32602 });
 const absolute = (value) => typeof value === "string" && value.startsWith("/") && !value.includes("\0") && !value.split("/").includes("..") && value.length <= 1024;
 const safePath = (path) => typeof path === "string" && path.length > 0 && !path.includes("\0") && !path.includes("\\") && path.split("/").every((part) => part !== "" && part !== "." && part !== "..");
+/**
+ * Whether every folder on the way to rel inside root is a real folder (or not there yet): a sync or an upload never
+ * reads or writes through a link that code in the workspace left where a folder goes.
+ */
+export async function realFolders(root, rel) {
+    let at = root;
+    for (const part of rel.split("/").slice(0, -1)) {
+        at = join(at, part);
+        const st = await lstat(at).catch(() => undefined);
+        if (!st)
+            return true;
+        if (!st.isDirectory())
+            return false;
+    }
+    return true;
+}
 /** The host tells a warm server, at hand-over, the account's build cache and workspace. */
 export function configure(params) {
     for (const key of ["cache_dir", "workspace"])
@@ -85,7 +103,7 @@ async function manifest(params) {
     for (const e of entries) {
         const known = index[e.path];
         let present = false;
-        if (known && known.sha256 === e.sha256 && known.kind === (e.kind ?? "file")) {
+        if (known && known.sha256 === e.sha256 && known.kind === (e.kind ?? "file") && (await realFolders(root, e.path))) {
             present = await lstat(join(root, e.path)).then((st) => (known.kind === "symlink" ? st.isSymbolicLink() : st.isFile() && st.size === e.size), () => false);
         }
         if (!present) {
@@ -142,9 +160,12 @@ async function asAnnounced(root, entries, missing) {
         if (!e)
             continue;
         const at = join(root, path);
-        const st = await lstat(at).catch(() => undefined);
+        const inside = await realFolders(root, path);
+        const st = inside ? await lstat(at).catch(() => undefined) : undefined;
         let why;
-        if (!st)
+        if (!inside)
+            why = "a folder on its way is a link";
+        else if (!st)
             why = "not in the archive";
         else if ((e.kind ?? "file") === "symlink") {
             if (!st.isSymbolicLink())
@@ -181,10 +202,7 @@ async function write(sync, archive) {
                 await writeFile(file, Buffer.from(archive.base64, "base64"));
             }
             else if (typeof archive.url === "string" && archive.url.startsWith("https://")) {
-                const response = await fetch(archive.url);
-                if (!response.ok || !response.body)
-                    throw new Error(`archive_download_failed: ${response.status}`);
-                await pipeline(Readable.fromWeb(response.body), createWriteStream(file));
+                await download(archive.url, file, "archive");
             }
             else {
                 throw new Error("archive_invalid");
@@ -196,6 +214,9 @@ async function write(sync, archive) {
                     throw new Error("archive_checksum_mismatch");
             }
             await onlyAskedFor(file, sync.missing);
+            // The folders the manifest's files go in are real folders, as on the client: a link left in one's place goes.
+            for (const path of sync.missing)
+                await realFoldersIn(root, path);
             // bsdtar keeps every entry inside root: it strips a leading / and refuses .. without -P.
             await run("/usr/bin/tar", ["-xzf", file, "-C", root], { timeoutMs: 10 * 60_000 });
         }
@@ -210,11 +231,14 @@ async function write(sync, archive) {
     for (const e of entries) {
         const path = join(root, e.path);
         const kind = e.kind ?? "file";
+        if (!(await realFolders(root, e.path)))
+            continue;
         const st = await lstat(path).catch(() => undefined);
         if (!st)
             continue;
         const mode = kind === "executable" ? 0o755 : 0o644;
-        if (kind !== "symlink" && (st.mode & 0o777) !== mode)
+        // chmod follows a link: only a file itself gets its mode.
+        if (kind !== "symlink" && st.isFile() && (st.mode & 0o777) !== mode)
             await chmod(path, mode).catch(() => { });
         if (Math.floor(st.mtimeMs) !== e.mtime_ms) {
             const when = new Date(e.mtime_ms);
@@ -225,7 +249,7 @@ async function write(sync, archive) {
     const now = new Set(entries.map((e) => e.path));
     let removed = 0;
     for (const path of Object.keys(before)) {
-        if (now.has(path) || !safePath(path))
+        if (now.has(path) || !safePath(path) || !(await realFolders(root, path)))
             continue;
         await rm(join(root, path), { force: true });
         removed++;
@@ -306,7 +330,7 @@ async function get(params) {
     let got = gets.get(id);
     if (!got) {
         const path = files.get(file);
-        if (!path || !existsSync(path))
+        if (!path || !(await insideRoots(path)))
             throw Object.assign(new Error("file_not_found"), { code: -32000 });
         const started = { state: "running" };
         gets.set(id, started);
@@ -320,6 +344,17 @@ async function get(params) {
         await new Promise((r) => setTimeout(r, 50));
     return { ...got };
 }
+/** A file itself (never a link), whose real path is inside the folders an answer may name. */
+async function insideRoots(path) {
+    const st = await lstat(path).catch(() => undefined);
+    if (!st?.isFile())
+        return false;
+    const real = await realpath(path).catch(() => undefined);
+    if (!real)
+        return false;
+    const roots = await Promise.all(fileRoots().map((root) => realpath(root).catch(() => undefined)));
+    return roots.some((root) => root !== undefined && real.startsWith(`${root}${sep}`));
+}
 /** Streams the file to the link, never whole in memory: as many bytes as it had when the upload began. */
 async function upload(path, url) {
     const { size } = statSync(path);
@@ -382,14 +417,16 @@ export function gitUrl(url) {
 async function fetchRepository(url, ref, token) {
     const root = join(srcRoot(), `git_${createHash("sha256").update(normalizeRemote(url)).digest("hex").slice(0, 32)}`);
     const git = (args, timeoutMs = 60_000) => gitRun(args, gitEnv(url, token), timeoutMs, token);
-    if (!existsSync(join(root, ".git"))) {
+    // A folder's git metadata is a folder of its own; anything else there (a file or a link pointing elsewhere) is not
+    // trusted, and the repository is fetched again from nothing.
+    const meta = await lstat(join(root, ".git")).catch(() => undefined);
+    if (meta && !meta.isDirectory())
+        await rm(root, { recursive: true, force: true });
+    if (!meta || !meta.isDirectory()) {
         await mkdir(root, { recursive: true });
         await git(["init", "-q", root]);
-        await git(["-C", root, "remote", "add", "origin", url]);
-    }
-    else {
-        await git(["-C", root, "remote", "set-url", "origin", url]);
     }
+    await trustNothingIn(root, url);
     await git(["-C", root, "fetch", "--depth", "1", "--no-tags", "origin", ref ?? "HEAD"], 10 * 60_000);
     await git(["-C", root, "checkout", "--quiet", "--force", "--detach", "FETCH_HEAD"]);
     if (existsSync(join(root, ".gitmodules")))
@@ -397,14 +434,63 @@ async function fetchRepository(url, ref, token) {
     const commit = (await git(["-C", root, "rev-parse", "--short=12", "HEAD"])).trim();
     return { root, commit };
 }
-/** git never asks, and a token goes as an HTTP header set from the environment (GIT_CONFIG_*), for this host only. */
+/**
+ * The clone folder is reused, so code that ran in this workspace may have changed its git configuration: before each
+ * fetch the repository's config, and each submodule's, is written again from nothing but the values git needs (the
+ * remote's link, a submodule's worktree), so no setting there runs a program or sends the token anywhere. The link
+ * goes in the file, never in an argument. Hooks and the file monitor are off from the environment (gitEnv).
+ */
+export async function trustNothingIn(root, url) {
+    const gitDir = join(root, ".git");
+    await writeConfig(gitDir, { url });
+    // Submodules' own repositories, at any depth: .git/modules/<name>[/modules/<name>...].
+    const walk = async (dir) => {
+        for (const entry of await readdir(dir, { withFileTypes: true }).catch(() => [])) {
+            if (!entry.isDirectory())
+                continue;
+            const sub = join(dir, entry.name);
+            if (existsSync(join(sub, "HEAD"))) {
+                const read = async (key) => (await gitRun(["config", "--file", join(sub, "config"), "--get", key], gitEnv(url, undefined), 10_000, undefined).catch(() => "")).trim();
+                const worktree = await read("core.worktree");
+                const remote = await read("remote.origin.url");
+                await writeConfig(sub, { worktree: worktree && !/[\n\r"\\]/.test(worktree) ? worktree : undefined, url: remote && gitUrl(remote) ? remote : undefined });
+                await walk(join(sub, "modules"));
+            }
+            else {
+                await walk(sub);
+            }
+        }
+    };
+    await walk(join(gitDir, "modules"));
+}
+async function writeConfig(gitDir, values) {
+    const lines = ["[core]", "\trepositoryformatversion = 0", "\tfilemode = true", "\tbare = false"];
+    if (values.worktree)
+        lines.push(`\tworktree = "${values.worktree}"`);
+    if (values.url)
+        lines.push('[remote "origin"]', `\turl = ${values.url}`, "\tfetch = +refs/heads/*:refs/remotes/origin/*");
+    const tmp = join(gitDir, `config.nomac-${process.pid}`);
+    await writeFile(tmp, `${lines.join("\n")}\n`, { mode: 0o600 });
+    await rename(tmp, join(gitDir, "config"));
+}
+/**
+ * git never asks, reads no configuration of the user or the system, runs no hook or file monitor, and fetches only
+ * over https; a token goes as an HTTP header set from the environment (GIT_CONFIG_*), for this host only.
+ */
 export function gitEnv(url, token) {
-    const env = { ...process.env, GIT_TERMINAL_PROMPT: "0", GIT_ASKPASS: "/usr/bin/false" };
+    const config = [
+        ["core.hooksPath", "/dev/null"],
+        ["core.fsmonitor", "false"],
+        ["protocol.allow", "never"],
+        ["protocol.https.allow", "always"],
+    ];
     if (token) {
         const { hostname } = new URL(url);
         const user = hostname === "gitlab.com" ? "oauth2" : hostname === "bitbucket.org" ? "x-token-auth" : "x-access-token";
-        Object.assign(env, { GIT_CONFIG_COUNT: "1", GIT_CONFIG_KEY_0: `http.https://${hostname}/.extraHeader`, GIT_CONFIG_VALUE_0: `Authorization: Basic ${Buffer.from(`${user}:${token}`).toString("base64")}` });
+        config.push([`http.https://${hostname}/.extraHeader`, `Authorization: Basic ${Buffer.from(`${user}:${token}`).toString("base64")}`]);
     }
+    const env = { ...process.env, GIT_TERMINAL_PROMPT: "0", GIT_ASKPASS: "/usr/bin/false", GIT_CONFIG_NOSYSTEM: "1", GIT_CONFIG_GLOBAL: "/dev/null", GIT_CONFIG_COUNT: String(config.length) };
+    config.forEach(([key, value], i) => Object.assign(env, { [`GIT_CONFIG_KEY_${i}`]: key, [`GIT_CONFIG_VALUE_${i}`]: value }));
     return env;
 }
 function gitRun(args, env, timeoutMs, token) {
@@ -462,17 +548,11 @@ async function unpackUpload(url, sha256, name) {
     const work = await mkdtemp(join(srcRoot(), ".nomac-upload-"));
     try {
         const file = join(work, "archive");
-        const response = await fetch(url);
-        if (!response.ok || !response.body)
-            throw new Error(`upload_download_failed: ${response.status}`);
-        await pipeline(Readable.fromWeb(response.body), createWriteStream(file));
-        const hash = createHash("sha256");
-        await pipeline(createReadStream(file), hash);
-        if (hash.digest("hex") !== sha256)
+        if ((await download(url, file, "upload")) !== sha256)
             throw new Error("upload_checksum_mismatch: the file is not the one its sha256 names");
         const out = join(work, "out");
         await mkdir(out);
-        const head = (await readFile(file)).subarray(0, 4);
+        const head = await firstBytes(file, 4);
         if (head[0] === 0x50 && head[1] === 0x4b)
             await run("/usr/bin/ditto", ["-x", "-k", file, out], { timeoutMs: 10 * 60_000 });
         // bsdtar keeps every entry inside out: it strips a leading / and refuses .. without -P.
@@ -489,6 +569,62 @@ async function unpackUpload(url, sha256, name) {
         await rm(work, { recursive: true, force: true });
     }
 }
+/** An upload or a sync's archive is at most this large, and its download takes at most this long. */
+let DOWNLOAD_MAX_BYTES = 2 * 1024 ** 3;
+const DOWNLOAD_MS = 30 * 60_000;
+export const setDownloadLimit = (bytes) => (DOWNLOAD_MAX_BYTES = bytes);
+/**
+ * Downloads a link NoMac signed to file, streamed (never whole in memory), within DOWNLOAD_MS and DOWNLOAD_MAX_BYTES;
+ * answers its sha256.
+ */
+async function download(url, file, what) {
+    const response = await fetch(url, { signal: AbortSignal.timeout(DOWNLOAD_MS) }).catch((error) => {
+        throw new Error(`${what}_download_failed: ${error.name === "TimeoutError" ? "timed out" : error.message}`);
+    });
+    if (!response.ok || !response.body)
+        throw new Error(`${what}_download_failed: ${response.status}`);
+    if (Number(response.headers.get("content-length") ?? 0) > DOWNLOAD_MAX_BYTES)
+        throw new Error(`${what}_too_large: at most ${Math.round(DOWNLOAD_MAX_BYTES / 1024 ** 2)} MiB`);
+    const hash = createHash("sha256");
+    let bytes = 0;
+    await pipeline(Readable.fromWeb(response.body), async function* (chunks) {
+        for await (const chunk of chunks) {
+            bytes += chunk.length;
+            if (bytes > DOWNLOAD_MAX_BYTES)
+                throw new Error(`${what}_too_large: at most ${Math.round(DOWNLOAD_MAX_BYTES / 1024 ** 2)} MiB`);
+            hash.update(chunk);
+            yield chunk;
+        }
+    }, createWriteStream(file)).catch((error) => {
+        throw error.message.startsWith(what) ? error : new Error(`${what}_download_failed: ${error.name === "TimeoutError" ? "timed out" : error.message}`);
+    });
+    return hash.digest("hex");
+}
+/** A file's first bytes, read alone. */
+async function firstBytes(file, n) {
+    const handle = await open(file, "r");
+    try {
+        const buffer = Buffer.alloc(n);
+        const { bytesRead } = await handle.read(buffer, 0, n, 0);
+        return buffer.subarray(0, bytesRead);
+    }
+    finally {
+        await handle.close();
+    }
+}
+/** Each folder on the way to rel inside root becomes a real folder: a link or a file where one goes is removed first. */
+async function realFoldersIn(root, rel) {
+    let at = root;
+    for (const part of rel.split("/").slice(0, -1)) {
+        at = join(at, part);
+        const st = await lstat(at).catch(() => undefined);
+        if (st?.isDirectory())
+            continue;
+        if (st)
+            await unlink(at);
+        await mkdir(at);
+    }
+}
 /**
  * Makes to hold what from holds: a file whose content differs is moved in, the rest keep theirs and their mtimes;
  * what to has beyond from goes, but build output and dependencies stay (they were made here).
@@ -506,6 +642,7 @@ async function mirror(from, to) {
             }
             files.add(rel);
             const target = join(to, rel);
+            await realFoldersIn(to, rel);
             if (await sameContent(path, target, entry.isSymbolicLink()))
                 continue;
             await mkdir(dirname(target), { recursive: true });
@@ -540,7 +677,11 @@ async function sameContent(a, b, link) {
             return sa.isSymbolicLink() && sb.isSymbolicLink() && (await readlink(a)) === (await readlink(b));
         if (sa.size !== sb.size || (sa.mode & 0o111) !== (sb.mode & 0o111))
             return false;
-        const [ha, hb] = await Promise.all([a, b].map(async (p) => createHash("sha256").update(await readFile(p)).digest("hex")));
+        const [ha, hb] = await Promise.all([a, b].map(async (p) => {
+            const hash = createHash("sha256");
+            await pipeline(createReadStream(p), hash);
+            return hash.digest("hex");
+        }));
         return ha === hb;
     }
     catch {
@@ -562,26 +703,69 @@ async function appIn(root) {
 // The replay's own recorder, the file it records and the calls so far.
 let replay;
 const REPLAY_CALLS = 2000;
+/** A ui_act step as the replay lists it, from the parsed step: what it acted on, never what it typed or a line it could not read. */
+function stepSummary(line) {
+    const step = parseStep(String(line));
+    if (typeof step === "string")
+        return "(a step that did not parse)";
+    switch (step.op) {
+        case "fill":
+            return `fill ${describeTarget(step.target)} …`;
+        case "type":
+            return "type …";
+        case "scroll":
+        case "swipe":
+            return [step.op, step.direction, ...(step.target ? [describeTarget(step.target)] : [])].join(" ");
+        case "key":
+            return `key ${step.key}`;
+        case "back":
+        case "home":
+            return step.op;
+        default:
+            return `${step.op} ${describeTarget(step.target)}`;
+    }
+}
 /**
- * What a call did, for the replay: the tool and its main argument, with typed text masked (fill #password …).
+ * What a call did, for the replay: the tool and its main argument, built from what was asked (a ui_act step's action and
+ * target), so typed text and links never reach the list.
  */
 export function callSummary(tool, args) {
     if (tool === "ui_act" && Array.isArray(args.steps))
-        return args.steps.map((step) => String(step).replace(/^((?:fill|type)\b(?:\s+(?:#\S+|"[^"]*"|\S+))?)\s.*$/i, (_m, head) => (/^type/i.test(head) ? "type …" : `${head} …`))).join(" · ").slice(0, 200);
+        return args.steps.map(stepSummary).join(" · ").slice(0, 200);
     if (tool === "app_control")
         return [args.action, args.action === "open_url" ? "(a link)" : args.app].filter(Boolean).join(" ").slice(0, 120);
     if (tool === "app_run" || tool === "tests_run")
         return tool;
     return Object.keys(args).length ? `${tool} ${Object.keys(args).join(", ")}` : tool;
 }
+/**
+ * What a call answered, for the replay: for ui_act, how many steps were done or which one failed, never its answer's
+ * words (they can repeat what a field shows); for a link, that it opened; for logs, that they were read (an app's logs
+ * can hold anything). Other tools' first line.
+ */
+export function callAnswer(tool, args, text, failed) {
+    const first = hostedText(text.split(/\r?\n|\r|\u2028|\u2029/)[0] ?? "");
+    if (tool === "ui_act") {
+        const done = /^(\d+) steps? done in ([\d.]+) s$/.exec(first);
+        if (done && !failed)
+            return `${done[1]} step${done[1] === "1" ? "" : "s"} done in ${done[2]} s`;
+        const step = /^Step (\d+)\b/.exec(first) ?? /^Stopped before step (\d+)\b/.exec(first);
+        if (step)
+            return first.startsWith("Stopped") ? `Stopped before step ${step[1]}: out of time` : `Step ${step[1]} failed`;
+        return failed ? "failed" : "done";
+    }
+    if (tool === "app_control" && args.action === "open_url")
+        return failed ? "Could not open the link." : "Opened the link.";
+    if (tool === "app_logs")
+        return failed ? "Could not read the app's logs." : "Read the app's logs.";
+    return first;
+}
 /** Notes a call for the replay, while one records. */
 export function noteCall(tool, args, started, result) {
     if (!replay || replay.log.length >= REPLAY_CALLS)
         return;
     const text = result.content.map((c) => (c && typeof c === "object" && c.type === "text" ? String(c.text ?? "") : "")).join("\n");
-    // ui_act's answer can repeat what was typed ("fill #password \"…\" failed"): its quoted parts never reach the list.
-    const first = hostedText(text.split("\n")[0] ?? "");
-    const said = tool === "ui_act" ? first.replace(/"[^"]*"|“[^”]*”/g, "…") : first;
+    const said = callAnswer(tool, args, text, Boolean(result.isError));
     replay.log.push({ at_ms: started - replay.started, tool, what: callSummary(tool, args), ms: Date.now() - started, ok: !result.isError, said: said.slice(0, 200) });
 }
 // simctl's recorder, as screen_record's but its own process: the agent's recordings go on beside it, and the video
@@ -754,11 +938,12 @@ const listStates = async () => {
     }
     return states.sort((a, b) => b.saved_at.localeCompare(a.saved_at));
 };
-async function saveState(name) {
+async function saveState(name, upload) {
     const device = pickDevice(await listDevices(true), undefined, await heldDevice());
     const data = await dataPathOf(device.udid);
     const dir = join(statesDir(), name), saving = `${dir}.saving`;
     await shutDown(device.udid);
+    let uploading, result;
     try {
         await rm(saving, { recursive: true, force: true });
         await mkdir(saving, { recursive: true });
@@ -768,22 +953,36 @@ async function saveState(name) {
         await writeFile(join(saving, "state.json"), JSON.stringify(meta));
         await rm(dir, { recursive: true, force: true });
         await rename(saving, dir);
-        return { state: "done", bytes, device: `${device.name} (${device.runtime})` };
+        // Kept in NoMac's storage too, so it restores on any phone: it uploads while the phone boots again.
+        uploading = upload ? uploadState(statesDir(), name, upload.url, upload.key, tmpdir()) : undefined;
+        uploading?.catch(() => { });
+        result = { state: "done", bytes, device: `${device.name} (${device.runtime})`, saved_at: meta.saved_at };
     }
     finally {
         await rm(saving, { recursive: true, force: true });
         await bootAgain(device.udid);
     }
+    if (uploading) {
+        await uploading.catch((error) => { throw new Error(`saved on this phone, but not kept for other phones: ${error.message}`); });
+        result.uploaded = true;
+    }
+    return result;
 }
-async function restoreState(name) {
+async function restoreState(name, fetch) {
     const dir = join(statesDir(), name);
-    let meta;
-    try {
-        meta = JSON.parse(await readFile(join(dir, "state.json"), "utf8"));
+    const local = async () => JSON.parse(await readFile(join(dir, "state.json"), "utf8"));
+    let meta = await local().catch(() => undefined);
+    // A copy here is the state only if it is the same save; otherwise the account's copy in NoMac's storage comes down.
+    let fetched = false;
+    if (fetch && meta?.saved_at !== fetch.savedAt) {
+        await fetchState(statesDir(), name, fetch.url, fetch.key);
+        meta = await local();
+        if (meta.saved_at !== fetch.savedAt)
+            throw new Error(`the stored ${name} is not the save asked for`);
+        fetched = true;
     }
-    catch {
+    if (!meta)
         throw new Error(`no saved state named ${name}`);
-    }
     const device = pickDevice(await listDevices(true), undefined, await heldDevice());
     // A state goes back onto the phone it came from: the same model and iOS.
     if (meta.device !== device.name || meta.runtime !== device.runtime)
@@ -794,7 +993,7 @@ async function restoreState(name) {
         await removeExcept(data, SYSTEM_ASSETS);
         await run("/usr/bin/ditto", [join(dir, "data"), data], { timeoutMs: 10 * 60_000 });
         await forgetAppPaths(data);
-        return { state: "done", bytes: meta.bytes, device: `${device.name} (${device.runtime})` };
+        return { state: "done", bytes: meta.bytes, device: `${device.name} (${device.runtime})`, ...(fetch ? { fetched } : {}) };
     }
     finally {
         await bootAgain(device.udid);
@@ -807,7 +1006,14 @@ async function restoreState(name) {
  * id reads their state.
  */
 async function phoneState(params) {
-    const { id, action, name } = params;
+    const { id, action, name, url, data_key: key, saved_at: savedAt } = params;
+    // A save given a link and a key keeps the state in NoMac's storage too; a restore given them fetches it when this
+    // workspace has no copy of that save (saved_at).
+    const transfer = url === undefined && key === undefined ? undefined : typeof url === "string" && url.startsWith("https://") && typeof key === "string" && /^[A-Za-z0-9_-]{43}$/.test(key) ? { url, key } : null;
+    if (transfer === null)
+        throw invalid("a state's url (https) and data_key");
+    if (transfer && action === "restore" && (typeof savedAt !== "string" || savedAt.length > 64))
+        throw invalid("a restore's saved_at");
     if (typeof id !== "string" || !STATE_ID.test(id))
         throw invalid("state id");
     if (action === "list")
@@ -828,7 +1034,7 @@ async function phoneState(params) {
         while (stateJobs.size > KEEP_STATE_JOBS)
             stateJobs.delete(stateJobs.keys().next().value);
         const began = Date.now();
-        (action === "save" ? saveState(name) : restoreState(name)).then(
+        (action === "save" ? saveState(name, transfer) : restoreState(name, transfer ? { ...transfer, savedAt: savedAt } : undefined)).then(
         // The whole of it: the copy and the phone booted and readable again.
         (result) => Object.assign(started, result, { ms: Date.now() - began }), (error) => Object.assign(started, { state: "failed", error: error.message.slice(0, 300) }));
         job = started;

package/dist/registry.js

@@ -2,11 +2,12 @@ import { createRequire } from "node:module";
 import { cloudState } from "./cloud/account.js";
 import { forward } from "./cloud/forward.js";
 import { ToolError } from "./errors.js";
+import { simulatorMissing } from "./engine/simctl.js";
 import { setting } from "./settings.js";
 import { appControl } from "./tools/app-control.js";
 import { appLogs } from "./tools/app-logs.js";
 import { appRun } from "./tools/app-run.js";
-import { cloud } from "./tools/cloud.js";
+import { cloud, tunnelNotice } from "./tools/cloud.js";
 import { deviceUse } from "./tools/device-use.js";
 import { devices } from "./tools/devices.js";
 import { jobCancel, jobStatus } from "./tools/jobs.js";
@@ -15,6 +16,8 @@ import { testsRun } from "./tools/tests-run.js";
 import { uiAct } from "./tools/ui-act.js";
 import { uiLook } from "./tools/ui-look.js";
 export const VERSION = createRequire(import.meta.url)("../package.json").version;
+/** Tools that run without a Simulator on this machine: cloud mode itself, and following a job. */
+const NO_SIMULATOR_NEEDED = new Set(["cloud", "job_status", "job_cancel"]);
 /** Every tool, in the order clients list them. The MCP server and the CLI are both built from this. */
 export const TOOLS = [devices, deviceUse, appRun, uiLook, uiAct, appControl, appLogs, testsRun, jobStatus, jobCancel, screenRecord, cloud];
 /** How the tools fit together, sent once to MCP clients. */
@@ -68,8 +71,17 @@ export async function callTool(name, args = {}, context = { waitForJobs: false }
         return { text: problem, isError: true };
     try {
         // With cloud on, every other tool runs on the NoMac phone (src/cloud/forward.ts).
-        if (tool !== cloud && !setting("HOSTED") && (await cloudState()).on)
-            return await forward(tool.name, args, context);
+        if (tool !== cloud && !setting("HOSTED") && (await cloudState()).on) {
+            const out = await forward(tool.name, args, context);
+            const notice = tunnelNotice();
+            return notice ? { ...out, text: `${out.text}\n${notice}` } : out;
+        }
+        // Where the Simulator can't run, every tool that needs it says so, and how to get a cloud phone.
+        if (!NO_SIMULATOR_NEEDED.has(tool.name) && !setting("HOSTED")) {
+            const missing = await simulatorMissing();
+            if (missing)
+                throw missing;
+        }
         return await tool.run(args, context);
     }
     catch (error) {