simulator-use 0.10.1 → 0.12.0

package/README.md

@@ -1,15 +1,20 @@
 # simulator-use
 
-Give your agent a phone. simulator-use lets Claude Code, Codex, Cursor and any other MCP client read and drive the iOS Simulator on your Mac, with a small set of tools and a compact view of the screen.
+**The fastest, most token-efficient way for an AI agent to use the iOS Simulator.** simulator-use gives Claude Code, Codex, Cursor and any other MCP client a phone: it builds and runs your Xcode project, reads the screen as a few lines of text, taps and types by label, and runs your tests case by case. Its own native engine talks to the Simulator directly, so reading the whole screen takes about 250 ms and a tap goes out in under a millisecond, where tools that start a helper for every call take 1.5 to 3 seconds. Free and open source (MIT), on any Mac with Xcode, and from Linux, Windows or a Mac without Xcode through a cloud iPhone.
 
-Formerly simtap (until 0.7): the `simtap` command and the `SIMTAP_*` settings still work.
+- **Fast:** a whole-screen read in about 250 ms, a tap sent in under 1 ms, a screenshot in about 60 ms (measured on an M6 Mac mini, October 2026).
+- **Token-efficient:** one line per element the agent can use, nothing else; a dozen tools with short descriptions.
+- **Complete:** build, install, launch, XCTest and XCUITest per case, logs and crashes, video, permission prompts, iPhone and iPad.
+- **Continuously improved:** weekly releases driven by thousands of daily sessions.
+- **Anywhere:** `npx simulator-use cloud start` gives a cloud iPhone with Xcode to any machine.
+
+It builds, runs and tests Xcode projects, reads and uses the screen of any app (SwiftUI, UIKit, React Native), answers iOS's permission prompts, reads the app's logs and crashes, and records video.
 
-It builds, runs and tests Xcode projects, reads and uses the screen of any app (SwiftUI, UIKit, React Native), answers iOS's permission prompts, reads the app's logs and crashes, and records video. Tested on Xcode 26.5 and 27 with iOS 26.5 and 27, on iPhone and iPad.
 
 ## What the agent sees
 
 ```
-Demo · Sign In · iPhone 17 Pro (iOS 26.5)
+Demo · Sign In · iPhone 17 Pro (iOS 27.0)
 textfield "Email" #email @201,194
 securefield "Password" #password @201,246
 switch "Remember me" #remember off @341,298
@@ -22,7 +27,7 @@ tabs: Login (selected) @158,822, Items @244,822
 - Groups, icons inside buttons, scroll bars, the status bar and the keyboard's keys are folded away. The tab bar, scrolling and the keyboard are one line each.
 - Only what can be tapped is listed. An alert, a sheet, a menu or a full-screen view in front hides the screen behind it, and iOS's own permission prompts read as alerts over the app. Rows under the navigation bar, the tab bar or the keyboard are counted as hidden (above, below, to the left or right), not listed.
 - A web view in UIKit (Capacitor, React Native's WebView, a sign-in page inside most apps) is read point by point, and its headings, texts, fields, checkboxes, buttons and links are listed like the rest. Web views hosted by SwiftUI, Safari's own pages, in-app browsers, maps, games and iOS's out-of-process pickers have nothing for accessibility to read. They come back as one `unreadable` line with their place, so the agent knows to take a screenshot and tap by point.
-- A screenshot, when asked for, is sized to points, so a point in the picture is a point to tap.
+- A screenshot, when asked for, is sized to points, so a point in the picture is a point to tap. `screenshot_file` saves the screen at full resolution as a PNG for a person, a report or the App Store; in cloud mode it is saved on your machine too.
 - The sign-in screen above is about 70 tokens. The full accessibility tree it comes from is about 40,000.
 
 ## Using the screen
@@ -67,7 +72,7 @@ Every step is checked, so nothing succeeds silently:
 | `devices` | `simulator-use devices` | Lists the Simulators on this Mac with their runtime, UDID and state, and its Xcodes |
 | `device_use` | `simulator-use use "iPhone 17 Pro"` | Chooses the Simulator the other tools use, booting it (one boot at a time); dark mode, a clean status bar |
 | `app_control` | `simulator-use app launch dev.example.app` | `install`, `launch` (answers with the first screen), `terminate`, `uninstall`, `open_url`; `grant`, `revoke` and `reset_permissions`; `location`; `push`; the phone's `appearance`, `locale`, `timezone`, `text_size` and a clean `status_bar` |
-| `ui_look` | `simulator-use look` | Reads the screen; `find` keeps matching lines, `screenshot` adds a picture, `full` saves the whole tree |
+| `ui_look` | `simulator-use look` | Reads the screen; `find` keeps matching lines, `screenshot` adds a picture, `screenshot_file` saves a full-resolution PNG, `full` saves the whole tree |
 | `ui_act` | `simulator-use act "tap #signIn" ...` | Does steps in order and answers with what changed |
 | `app_logs` | `simulator-use logs` | The app's print output and its own system log lines; `grep`, `wait_for`, `crashes` |
 | `tests_run` | `simulator-use test` | Runs the unit and UI tests; each case as it finishes, counts, each failure as `file:line` and the slowest; "0 tests ran" is an error |
@@ -87,7 +92,7 @@ The app's permissions are granted when it is installed and its first launch's pr
 ```
 Built Demo in 4.2 s, installed dev.simtap.demo.
 Launched Demo in 3.9 s.
-Demo · Sign In · iPhone 17 Pro (iOS 26.5)
+Demo · Sign In · iPhone 17 Pro (iOS 27.0)
 textfield "Email" #email @201,194
 ...
 ```
@@ -126,7 +131,7 @@ DemoTests/rejectsAnEmailWithoutAt(): Tests/SignInTests.swift:18: Expectation fai
 
 ## Several agents, one Mac
 
-- Each agent runs its own MCP server and holds its own Simulator through `device_use`.
+- Each agent runs its own MCP server and holds its own Simulator through `device_use`, and its own cloud phone: one agent's `cloud start` never moves another's tools, its `cloud stop` never ends another's phone, and the phone stops when the agent's server ends. A `cloud start` typed in a terminal is the command line's own.
 - Boots never overlap, across every simulator-use process on the Mac: two Simulators booting at once on an 8 GB Mac pushed it into swap for minutes.
 - `SIMULATOR_USE_MAX_BOOTED` caps how many run at once; asking for another shuts down the others first.
 - Steps on one Simulator run one at a time, across every simulator-use process on the Mac, so two agents' or two commands' taps never interleave.
@@ -140,7 +145,7 @@ Agents that run simulator-use through a shell, a command per call, get the same
 
 ```
 $ simulator-use call ui_look '{"find":"Sign In"}'
-{"content":[{"type":"text","text":"Demo · Sign In · iPhone 17 Pro (iOS 26.5)\nbutton \"Sign In\" #signIn @201,350"}]}
+{"content":[{"type":"text","text":"Demo · Sign In · iPhone 17 Pro (iOS 27.0)\nbutton \"Sign In\" #signIn @201,350"}]}
 ```
 
 ## What it can't do yet
@@ -184,13 +189,14 @@ From a shell: `npx simulator-use look`.
 Where this machine can't run the Simulator (Linux, Windows, a cloud agent), or for CI, the same tools run on a cloud iPhone Simulator on [NoMac](https://nomac.app/?utm_source=simulator-use), a Mac with Xcode, $0.80 an hour by the minute:
 
 ```
-simulator-use cloud start      # signs in through a link the first time (or NOMAC_API_KEY), starts a phone
+simulator-use cloud start      # signs in through a link the first time (or NOMAC_API_KEY), starts a phone (--device ipad for an iPad)
 simulator-use run              # every tool now runs there; run and test send the project first
+simulator-use cloud extend 30  # 30 minutes more (an hour by default), up to 8 hours in all
 simulator-use cloud stop       # ends it; the tools run on this machine again
 simulator-use cloud run . --tests   # CI in one line: start, build, run, test, a screenshot and a recording, stop
 ```
 
-Only the files the phone lacks are sent (a one-file change sends one file), into the account's own encrypted workspace, kept between sessions so builds stay incremental; build output and dependencies stay behind. The `cloud` tool does the same over MCP.
+Only the files the phone lacks are sent (a one-file change sends one file), into the account's own encrypted workspace, kept between sessions so builds stay incremental; build output and dependencies stay behind. Only files changed since the last send are read again (an index in simulator-use's state folder; `SIMULATOR_USE_SYNC_INDEX=0` reads every file). A CocoaPods project builds there too: `pod install` runs on the phone's host before the build when the pods are not the ones `Podfile` and `Podfile.lock` name, keeping the lock's versions, and the next build skips it. The `cloud` tool does the same over MCP.
 
 `cloud start` answers a link for a person to watch the phone in a browser and one to use it. `cloud stop` answers the session's replay: the screen as a video beside every call (typed text left out), kept for 7 days.
 
@@ -200,7 +206,7 @@ An app that talks to a backend on your machine reaches it through a tunnel (Node
 simulator-use cloud tunnel 8080    # until Ctrl-C: the phone reaches localhost:8080 here, each request printed
 ```
 
-The answer says the address the phone's apps use, such as `http://127.0.0.1:20199`; point the app there, for example with `run --env "API_URL=http://127.0.0.1:20199"`. Each request that passes is listed with its status and time (`cloud tunnel` without a port shows them over MCP). It lasts while the phone runs and comes back by itself after a dropped connection; `cloud tunnel` with port 0 closes it.
+The answer says the address the phone's apps use, such as `http://127.0.0.1:20199`; point the app there, for example with `run --env "API_URL=http://127.0.0.1:20199"`. Each request that passes is listed with its status and time (`cloud tunnel` without a port shows them over MCP). It lasts while the phone runs and comes back by itself after a dropped connection; `cloud tunnel` with port 0 closes it. While it is open, anything on the phone reaches that port: its apps, pages in its Safari and your project's build; nothing outside the phone does.
 
 On GitHub, from any runner, with the result posted on each pull request and the screenshot and recording kept as artifacts:
 
@@ -209,14 +215,16 @@ permissions:
   pull-requests: write
 steps:
   - uses: actions/checkout@v5
-  - uses: NoMac-app/simulator-use@v0.10
+  - uses: NoMac-app/simulator-use@v0.12
     with:
       api-key: ${{ secrets.NOMAC_API_KEY }}
 ```
 
+It runs the simulator-use of its own tag (`@v0.12` runs what that tag holds; `version` picks another). `path` is the project's folder, `scheme` the scheme when the project has several, and `tests: false` skips the tests (a project without a test target fails otherwise: zero tests is not a pass). A cancelled run stops its phone, and a pull request from a fork, which gets no secrets, fails with that reason. A job's log and its pull request comment can be public, so in CI (`CI` or `GITHUB_ACTIONS` set) `cloud run` prints no link that opens without signing in: files it links are kept in the run's artifacts, and the replay's link is read with the account's key (`GET https://nomac.app/api/v1/simulator/sessions/{id}`, `links.replay`).
+
 ## Privacy
 
-simulator-use sends nothing unless cloud mode is on. There is no telemetry and no network access at runtime: it runs `xcrun simctl`, the bundled AXe binary and `sips`, all on your Mac. With cloud on, it sends the project being run or tested, and the tools' calls, to NoMac, which keeps the session's replay for 7 days.
+simulator-use sends nothing unless cloud mode is on. There is no telemetry and no network access at runtime: it runs `xcrun simctl`, the bundled AXe binary and `sips`, all on your Mac. With cloud on, it sends the project being run or tested, and the tools' calls, to NoMac, which keeps the session's replay for 7 days. The project is the git repository it is in, as the files git tracks or would track (what `.gitignore` leaves out stays on your machine), or its folder when it is in none; either way never build output, dependencies, editor state or key and credential files (`.env` files but their examples, `.p8`, `.p12`, `.pfx`, `.pem`, `.key`, provisioning profiles, keystores, SSH keys, `.netrc`), even when git tracks them.
 
 ## How it works
 

package/dist/act/steps.js

@@ -186,3 +186,12 @@ export function describeTarget(t) {
         return `@${t.x},${t.y}`;
     return `${t.kind ? `${t.kind} ` : ""}${JSON.stringify(t.label)}`;
 }
+/** A step as an answer repeats it: a fill's or type's text left out, since the answer can reach logs and a replay. */
+export function maskedStep(line) {
+    const trimmed = line.trim();
+    const verb = (/^\S+/.exec(trimmed)?.[0] ?? "").toLowerCase();
+    if (verb !== "fill" && verb !== "type")
+        return trimmed;
+    const step = parseStep(trimmed);
+    return typeof step !== "string" && step.op === "fill" ? `fill ${describeTarget(step.target)} …` : `${verb} …`;
+}

package/dist/cli.js

@@ -5,9 +5,13 @@
 import { writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
+import { setTimeout as delay } from "node:timers/promises";
+import { persistCloud } from "./cloud/account.js";
+import { onSignalExit } from "./engine/jobs.js";
 import { persistHeld } from "./engine/state.js";
 import { serve } from "./mcp.js";
 import { callTool, toContent, TOOLS, VERSION } from "./registry.js";
+import { stopServerPhone } from "./tools/cloud.js";
 import { relay, relayPorts } from "./tunnel-relay.js";
 const flag = (name) => `--${name.replace(/_/g, "-")}`;
 /** Parses `--name value` and `--switch` into arguments the tool's schema accepts. */
@@ -151,12 +155,17 @@ export async function main(argv) {
         process.exit(0);
     }
     if (command === "mcp") {
+        // The server's cloud phone is its agent's own: stopped when the server ends, by a signal or below.
+        onSignalExit(stopServerPhone);
         await serve();
-        // The client closed stdin: answer what was in flight, then go, even if a child process still holds a pipe.
+        // The client closed stdin: answer what was in flight, stop the server's phone, then go, even if a child process
+        // still holds a pipe.
+        await Promise.race([stopServerPhone().catch(() => undefined), delay(15_000, undefined, { ref: false })]);
         process.exit(0);
     }
-    // From here on each command is its own process: the Simulator chosen with `use` is kept in a file.
+    // From here on each command is its own process: the Simulator chosen with `use` and cloud mode are kept in files.
     persistHeld();
+    persistCloud();
     if (command === "call")
         return call(rest);
     const tool = TOOLS.find((t) => t.command === command || t.name === command);

package/dist/cloud/account.js

@@ -1,7 +1,8 @@
 /**
  * Cloud mode's account and phone: the NoMac account it signs in to (NOMAC_API_KEY, else the NoMac CLI's
  * ~/.nomac/credentials.json, else NoMac's device sign-in, whose key is saved there for both tools), and the phone
- * it uses, kept in simulator-use's state folder so every CLI call reaches the same one.
+ * it uses: an MCP server's own, in its memory; the CLI's in simulator-use's state folder, so every CLI call reaches
+ * the same one.
  */
 import { chmod, mkdir, readFile, writeFile } from "node:fs/promises";
 import { homedir, hostname } from "node:os";
@@ -34,7 +35,21 @@ async function saveKey(key, base) {
     await chmod(credentialsFile(), 0o600);
 }
 const stateFile = () => join(stateDir(), "cloud.json");
+/**
+ * An MCP server keeps cloud mode in its memory, as it keeps its held Simulator: each agent runs its own server, so
+ * one agent's cloud start never sends another agent's tools to its phone, and one's cloud stop never ends another's.
+ * A CLI call is its own process, so the CLI keeps it in a file (persistCloud), and cloud start carries over to the
+ * next command.
+ */
+let memory = { on: false };
+let persistent = false;
+/** The CLI keeps cloud mode between its calls. */
+export function persistCloud() {
+    persistent = true;
+}
 export async function cloudState() {
+    if (!persistent)
+        return { ...memory };
     try {
         return JSON.parse(await readFile(stateFile(), "utf8"));
     }
@@ -43,6 +58,10 @@ export async function cloudState() {
     }
 }
 export async function setCloudState(state) {
+    if (!persistent) {
+        memory = { ...state };
+        return;
+    }
     await mkdir(stateDir(), { recursive: true });
     await writeFile(stateFile(), JSON.stringify(state), { mode: 0o600 });
 }
@@ -57,6 +76,9 @@ export async function signIn() {
     const ready = await account();
     if (ready)
         return { api: ready };
+    // In CI nobody can open a sign-in link: no key is a missing secret (a fork's pull request gets none).
+    if (process.env.CI)
+        throw new Error("No NOMAC_API_KEY: in CI, set it from a secret (a pull request from a fork gets no secrets).");
     const state = await cloudState();
     const base = (process.env.NOMAC_API_URL || DEFAULT_API).replace(/\/+$/, "");
     let pending = state.signIn && state.signIn.expires_at > Date.now() && state.signIn.base === base ? state.signIn : undefined;

package/dist/cloud/api.js

@@ -6,10 +6,13 @@ import { VERSION } from "../registry.js";
 export class CloudError extends Error {
     code;
     status;
-    constructor(code, message, status) {
+    /** The rest of NoMac's error: starting (a phone not ready yet), retry_after_seconds, next_action ... */
+    details;
+    constructor(code, message, status, details = {}) {
         super(message);
         this.code = code;
         this.status = status;
+        this.details = details;
     }
 }
 const PASSING = new Set([429, 502, 503, 504]);
@@ -55,7 +58,8 @@ export class CloudApi {
                 await pause(attempt, Number(response.headers.get("retry-after")));
                 continue;
             }
-            throw new CloudError(error.code ?? `http_${response.status}`, error.message ?? `NoMac answered ${response.status}.`, response.status);
+            const { code: _code, message: _message, ...details } = error;
+            throw new CloudError(error.code ?? `http_${response.status}`, error.message ?? `NoMac answered ${response.status}.`, response.status, details);
         }
     }
 }

package/dist/cloud/files.js

@@ -0,0 +1,57 @@
+/**
+ * The files a phone's answers link to, saved on this machine: a link ends with its phone, and a local tool's answer
+ * names a path.
+ */
+import { createWriteStream, existsSync } from "node:fs";
+import { unlink } from "node:fs/promises";
+import { basename, join } from "node:path";
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+/** A file link in a phone's answer: <base>/api/v1/simulator/files/<payload>.<signature>, never the sentence's period. */
+const FILE_LINK = /https?:\/\/[^\s"'<>]+?\/api\/v1\/simulator\/files\/[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+/g;
+const KEEP_FILES = 10;
+const KEEP_BYTES = 200 * 1024 * 1024;
+/** The file's name as the link carries it (its payload's n), made safe for a folder. */
+function linkName(link) {
+    try {
+        const payload = /\/files\/([A-Za-z0-9_-]+)\./.exec(link)?.[1];
+        const name = payload ? JSON.parse(Buffer.from(payload, "base64url").toString("utf8")).n : undefined;
+        const safe = typeof name === "string" ? basename(name).replace(/[^A-Za-z0-9._-]/g, "_").replace(/^\.+/, "") : "";
+        return safe || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The files a run's answers link to (a failed build's full log), kept in out before the phone stops: a link that
+ * was never opened ends with its phone. At most 10 files and 200 MB; each link in lines becomes its file's path.
+ */
+export async function keepFiles(lines, out) {
+    const links = [...new Set(lines.join("\n").match(FILE_LINK) ?? [])].slice(0, KEEP_FILES);
+    let total = 0;
+    for (const [i, link] of links.entries()) {
+        const name = linkName(link) ?? `simulator-use-file-${i + 1}`;
+        const file = join(out, existsSync(join(out, name)) ? `${i + 1}-${name}` : name);
+        try {
+            const response = await fetch(link, { signal: AbortSignal.timeout(120_000) });
+            if (!response.ok || !response.body || total + Number(response.headers.get("content-length") ?? 0) > KEEP_BYTES)
+                continue;
+            let size = 0;
+            const capped = Readable.fromWeb(response.body).map((chunk) => {
+                size += chunk.length;
+                if (total + size > KEEP_BYTES)
+                    throw new Error("over the run's file budget");
+                return chunk;
+            });
+            await pipeline(capped, createWriteStream(file));
+            total += size;
+            for (let j = 0; j < lines.length; j++)
+                lines[j] = lines[j].split(link).join(file);
+        }
+        catch {
+            // The link stays in the text; a file cut short is not kept.
+            await unlink(file).catch(() => undefined);
+        }
+    }
+}

package/dist/cloud/forward.js

@@ -1,17 +1,25 @@
 /**
  * With cloud on, every tool runs on the NoMac phone instead of this machine: called by name through NoMac's API
  * and polled until it ends. app_run and tests_run send their project first, and app_control install its .app, so
- * the paths the phone takes are its own. Answers read as a local tool's do; files they name are links.
+ * the paths the phone takes are its own. Answers read as a local tool's do; files they name are links, but for the
+ * files ui_look saves, which are saved here.
  */
 import { existsSync, realpathSync, statSync } from "node:fs";
+import { mkdir } from "node:fs/promises";
 import { basename, dirname, extname, relative, resolve, sep } from "node:path";
 import { createHash } from "node:crypto";
 import { run } from "../engine/exec.js";
+import { stateDir } from "../engine/state.js";
 import { ToolError } from "../errors.js";
 import { account, cloudState, setCloudState } from "./account.js";
 import { CloudError } from "./api.js";
+import { keepFiles } from "./files.js";
 import { randomKey, syncFolder } from "./sync.js";
 const JOB = /Next: job_status \{job_id: "([^"]+)"\}/;
+// job_status's answer while the job still runs (tools/jobs.ts): the same job is read again.
+const STILL_RUNNING = /\nNext: job_status again, or job_cancel\./;
+/** How long a call waits for a phone that is still starting (queued for a free one, or being prepared). */
+const STARTING_WAIT_MS = { cli: 5 * 60_000, mcp: 30_000 };
 /** The phone cloud mode uses, or why there is none. */
 export async function cloudPhone() {
     const state = await cloudState();
@@ -48,8 +56,20 @@ async function projectRoot(path) {
     }
     return { folder, inside: relative(folder, realpathSync(local)).split(sep).join("/") };
 }
+/** Waits for a phone that is still starting, up to waitMs: its state as last read (ready, or not yet). */
+async function whenReady(api, session, waitMs) {
+    const deadline = Date.now() + waitMs;
+    for (;;) {
+        const phone = (await api.json("GET", `/api/v1/simulator/sessions/${session}`)).session;
+        if (phone.state !== "queued" && phone.state !== "provisioning")
+            return phone;
+        if (Date.now() >= deadline)
+            return phone;
+        await new Promise((r) => setTimeout(r, 2_000));
+    }
+}
 /** Runs one tool on the phone and answers as the local tool would. */
-export async function forward(name, args, context) {
+export async function forward(name, args, context, waited = false) {
     const { api, session } = await cloudPhone();
     let sent = args;
     let note = "";
@@ -70,16 +90,33 @@ export async function forward(name, args, context) {
             sent = { ...args, app: `${synced.root}/${basename(app)}` };
         }
         let result = await call(api, session, name, sent);
-        // The command line waits for a long build, as it does on this Mac: job_status until the job ends.
-        for (let rounds = 0; context.waitForJobs && rounds < 60; rounds++) {
-            const job = JOB.exec(result.text)?.[1];
-            if (!job)
-                break;
+        // The command line waits for a long build, as it does on this Mac: job_status until the job ends. A job named
+        // in an error (another build of the project running) is not this call's.
+        const job = context.waitForJobs && !result.isError ? JOB.exec(result.text)?.[1] : undefined;
+        for (let rounds = 0; job && rounds < 120; rounds++) {
             result = await call(api, session, "job_status", { job_id: job });
+            if (result.isError || !STILL_RUNNING.test(result.text))
+                break;
+        }
+        // A file ui_look saved (the screenshot, the whole tree) is saved here too, as the tool on this machine does.
+        if (name === "ui_look" && (args.screenshot_file || args.full) && !result.isError) {
+            const lines = [result.text];
+            await mkdir(stateDir(), { recursive: true });
+            await keepFiles(lines, stateDir());
+            result = { ...result, text: lines[0] };
         }
         return note ? { ...result, text: `${note}${result.text}` } : result;
     }
     catch (error) {
+        // A phone still starting (waiting for a free one, or being prepared) is waited for, then the call goes again.
+        if (error instanceof CloudError && error.code === "session_not_ready" && error.details.starting === true) {
+            const phone = waited ? undefined : await whenReady(api, session, context.waitForJobs ? STARTING_WAIT_MS.cli : STARTING_WAIT_MS.mcp).catch(() => undefined);
+            if (phone?.state === "ready")
+                return forward(name, args, context, true);
+            if (phone && !["queued", "provisioning"].includes(phone.state))
+                return ended(session);
+            return { text: `The cloud phone ${session} is still starting${phone?.message ? `: ${phone.message}` : "."}\nNext: ${name} again in a moment (nothing ran); cloud status shows its place.`, isError: true };
+        }
         if (error instanceof CloudError && (error.code === "session_not_found" || error.code === "session_not_ready" || error.code === "session_expired"))
             return ended(session);
         if (error instanceof CloudError)
@@ -87,6 +124,19 @@ export async function forward(name, args, context) {
         throw error;
     }
 }
+/**
+ * NoMac's stop notice, in the phone's last 15 minutes before a limit or the account's credit's end, as cloud mode can
+ * act on it: it keeps no saved states, so a new phone after this one is the way on (its build stays in the workspace).
+ */
+export function stopNotice(answer) {
+    const notice = answer.stop_notice;
+    if (!notice?.message)
+        return "";
+    if (notice.reason === "credit")
+        return `\n${notice.message}`;
+    const when = (notice.minutes_left ?? 0) <= 1 ? "within a minute" : `in about ${notice.minutes_left} minutes`;
+    return `\nThe cloud phone stops ${when}, at its ${notice.reason === "spend_cap" ? "spend cap" : "time limit"}: cloud extend keeps it running an hour longer. Once it stops, its apps and data go with it; the project's build stays, so the next cloud start builds incrementally.`;
+}
 async function call(api, session, name, args) {
     let answer = await api.json("POST", `/api/v1/simulator/sessions/${session}/tools/${name}`, args, `cli-${name}-${randomKey()}`);
     while (answer.state === "running" && typeof answer.id === "string") {
@@ -102,7 +152,7 @@ async function call(api, session, name, args) {
     const picture = (result.content ?? []).find((c) => c.type === "image" && c.data);
     const notices = answer.notices?.includes("phone_restarted") ? "\nThe phone restarted; its apps and data are kept." : "";
     return {
-        text: `${text}${notices}`,
+        text: `${text}${notices}${stopNotice(answer)}`,
         ...(picture ? { image: { data: Buffer.from(picture.data, "base64"), mimeType: picture.mimeType === "image/png" ? "image/png" : "image/jpeg" } } : {}),
         ...(result.isError ? { isError: true } : {}),
     };