rnxsim 0.1.513 → 0.1.514

package/cli/outbound-endpoints.ts

@@ -164,16 +164,10 @@ export const DECLARED_OUTBOUND_CALLS: Record<string, OutboundCallDeclaration> =
     category: 'contrast_user_action',
     count: 1,
   },
-  'packages/sootsim/src/cloud.ts :: fetch :: `${origin}/v1/boxes`': {
+  'packages/sootsim/src/cloud.ts :: fetch :: url': {
     category: 'rnx_cloud_sim',
     count: 1,
   },
-  'packages/sootsim/src/cloud.ts :: fetch :: `${this.session.origin}/v1/sims/${encodeURIComponent(this.session.simId)}/commands`':
-    { category: 'rnx_cloud_sim', count: 1 },
-  'packages/sootsim/src/cloud.ts :: fetch :: `${this.session.origin}/v1/sims/${encodeURIComponent(this.session.simId)}/claim`':
-    { category: 'rnx_cloud_sim', count: 1 },
-  'packages/sootsim/src/cloud.ts :: fetch :: `${this.session.origin}/v1/boxes/${encodeURIComponent(this.session.boxId)}`':
-    { category: 'rnx_cloud_sim', count: 1 },
   // maestro's flow `http` API. the url is whatever the flow author wrote, and
   // it is fetched from a child process because that API is synchronous.
   'packages/sootsim/cli/internal-child.ts :: fetch :: request.url': {

package/dist-lib/agent-daemon-client.cjs

@@ -1,4 +1,4 @@
-/*! rnx v0.1.513 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
+/*! rnx v0.1.514 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
 let __sootsim_import_meta_url = ''; try { __sootsim_import_meta_url = require('url').pathToFileURL(__filename).href; } catch {}
 "use strict";
 var __create = Object.create;

package/dist-lib/agent-events.cjs

@@ -1,4 +1,4 @@
-/*! rnx v0.1.513 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
+/*! rnx v0.1.514 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
 let __sootsim_import_meta_url = ''; try { __sootsim_import_meta_url = require('url').pathToFileURL(__filename).href; } catch {}
 "use strict";
 var __defProp = Object.defineProperty;

package/dist-lib/agent-identity.cjs

@@ -1,4 +1,4 @@
-/*! rnx v0.1.513 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
+/*! rnx v0.1.514 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
 let __sootsim_import_meta_url = ''; try { __sootsim_import_meta_url = require('url').pathToFileURL(__filename).href; } catch {}
 "use strict";
 var __defProp = Object.defineProperty;

package/dist-lib/agent-sessions.cjs

@@ -1,4 +1,4 @@
-/*! rnx v0.1.513 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
+/*! rnx v0.1.514 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
 let __sootsim_import_meta_url = ''; try { __sootsim_import_meta_url = require('url').pathToFileURL(__filename).href; } catch {}
 "use strict";
 var __create = Object.create;

package/dist-lib/attached-projects.cjs

@@ -1,4 +1,4 @@
-/*! rnx v0.1.513 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
+/*! rnx v0.1.514 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
 let __sootsim_import_meta_url = ''; try { __sootsim_import_meta_url = require('url').pathToFileURL(__filename).href; } catch {}
 "use strict";
 var __create = Object.create;

package/dist-lib/auth/shared-session.cjs

@@ -1,4 +1,4 @@
-/*! rnx v0.1.513 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
+/*! rnx v0.1.514 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
 let __sootsim_import_meta_url = ''; try { __sootsim_import_meta_url = require('url').pathToFileURL(__filename).href; } catch {}
 "use strict";
 var __create = Object.create;

package/dist-lib/backend-origin.cjs

@@ -1,4 +1,4 @@
-/*! rnx v0.1.513 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
+/*! rnx v0.1.514 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
 let __sootsim_import_meta_url = ''; try { __sootsim_import_meta_url = require('url').pathToFileURL(__filename).href; } catch {}
 "use strict";
 var __defProp = Object.defineProperty;

package/dist-lib/beta.cjs

@@ -1,4 +1,4 @@
-/*! rnx v0.1.513 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
+/*! rnx v0.1.514 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
 let __sootsim_import_meta_url = ''; try { __sootsim_import_meta_url = require('url').pathToFileURL(__filename).href; } catch {}
 "use strict";
 var __defProp = Object.defineProperty;

package/dist-lib/beta.mjs

@@ -1,4 +1,4 @@
-/*! rnx v0.1.513 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
+/*! rnx v0.1.514 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
 
 // src/beta.ts
 var IS_BETA = true;

package/dist-lib/bridge-constants.cjs

@@ -1,4 +1,4 @@
-/*! rnx v0.1.513 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
+/*! rnx v0.1.514 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
 let __sootsim_import_meta_url = ''; try { __sootsim_import_meta_url = require('url').pathToFileURL(__filename).href; } catch {}
 "use strict";
 var __defProp = Object.defineProperty;

package/dist-lib/bridge-contract-input.cjs

@@ -1,4 +1,4 @@
-/*! rnx v0.1.513 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
+/*! rnx v0.1.514 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
 let __sootsim_import_meta_url = ''; try { __sootsim_import_meta_url = require('url').pathToFileURL(__filename).href; } catch {}
 "use strict";
 var __defProp = Object.defineProperty;

package/dist-lib/bridge-contract-input.mjs

@@ -1,4 +1,4 @@
-/*! rnx v0.1.513 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
+/*! rnx v0.1.514 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
 
 // src/bridge-contract.ts
 var SIM_LONG_PRESS_MAX_MS = 5e3;

package/dist-lib/bridge-contract.cjs

@@ -1,4 +1,4 @@
-/*! rnx v0.1.513 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
+/*! rnx v0.1.514 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
 let __sootsim_import_meta_url = ''; try { __sootsim_import_meta_url = require('url').pathToFileURL(__filename).href; } catch {}
 "use strict";
 var __defProp = Object.defineProperty;

package/dist-lib/bridge-contract.mjs

@@ -1,4 +1,4 @@
-/*! rnx v0.1.513 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
+/*! rnx v0.1.514 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
 
 // src/bridge-contract.ts
 var SIM_LONG_PRESS_DEFAULT_MS = 500;

package/dist-lib/capture-contract.cjs

@@ -1,4 +1,4 @@
-/*! rnx v0.1.513 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
+/*! rnx v0.1.514 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
 let __sootsim_import_meta_url = ''; try { __sootsim_import_meta_url = require('url').pathToFileURL(__filename).href; } catch {}
 "use strict";
 var __defProp = Object.defineProperty;

package/dist-lib/capture-contract.mjs

@@ -1,4 +1,4 @@
-/*! rnx v0.1.513 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
+/*! rnx v0.1.514 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
 
 // src/capture-contract.ts
 var RNX_SCREEN_CAPTURE_VERSION = 1;

package/dist-lib/cli-constants.cjs

@@ -1,4 +1,4 @@
-/*! rnx v0.1.513 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
+/*! rnx v0.1.514 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
 let __sootsim_import_meta_url = ''; try { __sootsim_import_meta_url = require('url').pathToFileURL(__filename).href; } catch {}
 "use strict";
 var __defProp = Object.defineProperty;

package/dist-lib/cloud-contract.cjs

@@ -1,4 +1,4 @@
-/*! rnx v0.1.513 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
+/*! rnx v0.1.514 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
 let __sootsim_import_meta_url = ''; try { __sootsim_import_meta_url = require('url').pathToFileURL(__filename).href; } catch {}
 "use strict";
 var __defProp = Object.defineProperty;
@@ -25,10 +25,17 @@ __export(cloud_contract_exports, {
   RNX_CLOUD_COMMAND_TYPES: () => RNX_CLOUD_COMMAND_TYPES,
   RNX_CLOUD_DESIGN_MAX_STORAGE_BYTES: () => RNX_CLOUD_DESIGN_MAX_STORAGE_BYTES,
   RNX_CLOUD_DESIGN_MAX_STORAGE_ENTRIES: () => RNX_CLOUD_DESIGN_MAX_STORAGE_ENTRIES,
+  RNX_CLOUD_LABELS_MAX_COUNT: () => RNX_CLOUD_LABELS_MAX_COUNT,
+  RNX_CLOUD_LABEL_MAX_LENGTH: () => RNX_CLOUD_LABEL_MAX_LENGTH,
   RNX_CLOUD_MAX_ARTIFACT_BYTES: () => RNX_CLOUD_MAX_ARTIFACT_BYTES,
   RNX_CLOUD_TEST_FILES_MAX_BYTES: () => RNX_CLOUD_TEST_FILES_MAX_BYTES,
   RNX_CLOUD_TEST_FILES_MAX_COUNT: () => RNX_CLOUD_TEST_FILES_MAX_COUNT,
-  isRnxCloudCommandType: () => isRnxCloudCommandType
+  isRnxCloudCommandType: () => isRnxCloudCommandType,
+  isRnxCloudSimStatus: () => isRnxCloudSimStatus,
+  isValidRnxCloudLabel: () => isValidRnxCloudLabel,
+  matchesRnxCloudLabels: () => matchesRnxCloudLabels,
+  parseRnxCloudLabels: () => parseRnxCloudLabels,
+  readRnxCloudLabels: () => readRnxCloudLabels
 });
 module.exports = __toCommonJS(cloud_contract_exports);
 var RNX_CLOUD_MAX_ARTIFACT_BYTES = 20 * 1024 * 1024;
@@ -59,13 +66,60 @@ var RNX_CLOUD_COMMAND_TYPE_SET = new Set(RNX_CLOUD_COMMAND_TYPES);
 function isRnxCloudCommandType(value) {
   return RNX_CLOUD_COMMAND_TYPE_SET.has(value);
 }
+var RNX_CLOUD_LABELS_MAX_COUNT = 16;
+var RNX_CLOUD_LABEL_MAX_LENGTH = 63;
+var RNX_CLOUD_LABEL_CONTROL = /[\u0000-\u001f\u007f]/;
+function isValidRnxCloudLabel(key, value) {
+  return key.length > 0 && key.length <= RNX_CLOUD_LABEL_MAX_LENGTH && value.length <= RNX_CLOUD_LABEL_MAX_LENGTH && !key.includes(",") && !key.includes("=") && !value.includes(",") && !RNX_CLOUD_LABEL_CONTROL.test(key) && !RNX_CLOUD_LABEL_CONTROL.test(value);
+}
+function parseRnxCloudLabels(value) {
+  if (value === "") return {};
+  const entries = value.split(",");
+  if (entries.length > RNX_CLOUD_LABELS_MAX_COUNT) return null;
+  const labels = {};
+  for (const entry of entries) {
+    const separator = entry.indexOf("=");
+    if (separator < 1) return null;
+    const key = entry.slice(0, separator).trim();
+    const label = entry.slice(separator + 1).trim();
+    if (!isValidRnxCloudLabel(key, label)) return null;
+    if (Object.hasOwn(labels, key)) return null;
+    labels[key] = label;
+  }
+  return labels;
+}
+function readRnxCloudLabels(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return null;
+  const entries = Object.entries(value);
+  if (entries.length > RNX_CLOUD_LABELS_MAX_COUNT) return null;
+  const labels = {};
+  for (const [key, label] of entries) {
+    if (typeof label !== "string") return null;
+    if (!isValidRnxCloudLabel(key, label)) return null;
+    labels[key] = label;
+  }
+  return labels;
+}
+function matchesRnxCloudLabels(labels, selector) {
+  return Object.entries(selector).every(([key, value]) => labels[key] === value);
+}
+function isRnxCloudSimStatus(value) {
+  return value === "creating" || value === "open" || value === "hibernated" || value === "deleting" || value === "deleted";
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   RNX_CLOUD_COMMAND_TYPES,
   RNX_CLOUD_DESIGN_MAX_STORAGE_BYTES,
   RNX_CLOUD_DESIGN_MAX_STORAGE_ENTRIES,
+  RNX_CLOUD_LABELS_MAX_COUNT,
+  RNX_CLOUD_LABEL_MAX_LENGTH,
   RNX_CLOUD_MAX_ARTIFACT_BYTES,
   RNX_CLOUD_TEST_FILES_MAX_BYTES,
   RNX_CLOUD_TEST_FILES_MAX_COUNT,
-  isRnxCloudCommandType
+  isRnxCloudCommandType,
+  isRnxCloudSimStatus,
+  isValidRnxCloudLabel,
+  matchesRnxCloudLabels,
+  parseRnxCloudLabels,
+  readRnxCloudLabels
 });

package/dist-lib/cloud-contract.mjs

@@ -1,4 +1,4 @@
-/*! rnx v0.1.513 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
+/*! rnx v0.1.514 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
 
 // src/cloud-contract.ts
 var RNX_CLOUD_MAX_ARTIFACT_BYTES = 20 * 1024 * 1024;
@@ -29,12 +29,59 @@ var RNX_CLOUD_COMMAND_TYPE_SET = new Set(RNX_CLOUD_COMMAND_TYPES);
 function isRnxCloudCommandType(value) {
   return RNX_CLOUD_COMMAND_TYPE_SET.has(value);
 }
+var RNX_CLOUD_LABELS_MAX_COUNT = 16;
+var RNX_CLOUD_LABEL_MAX_LENGTH = 63;
+var RNX_CLOUD_LABEL_CONTROL = /[\u0000-\u001f\u007f]/;
+function isValidRnxCloudLabel(key, value) {
+  return key.length > 0 && key.length <= RNX_CLOUD_LABEL_MAX_LENGTH && value.length <= RNX_CLOUD_LABEL_MAX_LENGTH && !key.includes(",") && !key.includes("=") && !value.includes(",") && !RNX_CLOUD_LABEL_CONTROL.test(key) && !RNX_CLOUD_LABEL_CONTROL.test(value);
+}
+function parseRnxCloudLabels(value) {
+  if (value === "") return {};
+  const entries = value.split(",");
+  if (entries.length > RNX_CLOUD_LABELS_MAX_COUNT) return null;
+  const labels = {};
+  for (const entry of entries) {
+    const separator = entry.indexOf("=");
+    if (separator < 1) return null;
+    const key = entry.slice(0, separator).trim();
+    const label = entry.slice(separator + 1).trim();
+    if (!isValidRnxCloudLabel(key, label)) return null;
+    if (Object.hasOwn(labels, key)) return null;
+    labels[key] = label;
+  }
+  return labels;
+}
+function readRnxCloudLabels(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return null;
+  const entries = Object.entries(value);
+  if (entries.length > RNX_CLOUD_LABELS_MAX_COUNT) return null;
+  const labels = {};
+  for (const [key, label] of entries) {
+    if (typeof label !== "string") return null;
+    if (!isValidRnxCloudLabel(key, label)) return null;
+    labels[key] = label;
+  }
+  return labels;
+}
+function matchesRnxCloudLabels(labels, selector) {
+  return Object.entries(selector).every(([key, value]) => labels[key] === value);
+}
+function isRnxCloudSimStatus(value) {
+  return value === "creating" || value === "open" || value === "hibernated" || value === "deleting" || value === "deleted";
+}
 export {
   RNX_CLOUD_COMMAND_TYPES,
   RNX_CLOUD_DESIGN_MAX_STORAGE_BYTES,
   RNX_CLOUD_DESIGN_MAX_STORAGE_ENTRIES,
+  RNX_CLOUD_LABELS_MAX_COUNT,
+  RNX_CLOUD_LABEL_MAX_LENGTH,
   RNX_CLOUD_MAX_ARTIFACT_BYTES,
   RNX_CLOUD_TEST_FILES_MAX_BYTES,
   RNX_CLOUD_TEST_FILES_MAX_COUNT,
-  isRnxCloudCommandType
+  isRnxCloudCommandType,
+  isRnxCloudSimStatus,
+  isValidRnxCloudLabel,
+  matchesRnxCloudLabels,
+  parseRnxCloudLabels,
+  readRnxCloudLabels
 };

package/dist-lib/cloud.cjs

@@ -1,4 +1,4 @@
-/*! rnx v0.1.513 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
+/*! rnx v0.1.514 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
 let __sootsim_import_meta_url = ''; try { __sootsim_import_meta_url = require('url').pathToFileURL(__filename).href; } catch {}
 "use strict";
 var __defProp = Object.defineProperty;
@@ -136,6 +136,8 @@ var rnxPublicBrand = Object.freeze({
 // src/cloud.ts
 var DEFAULT_DEVICE = "iphone-16";
 var DEFAULT_WAIT_READY_MS = 2e4;
+var CLOUD_MAX_RETRIES = 2;
+var CLOUD_NEVER_RETRY_CODES = /* @__PURE__ */ new Set(["concurrency_limit", "early_access"]);
 function isRecord(value) {
   return value !== null && typeof value === "object" && !Array.isArray(value);
 }
@@ -173,6 +175,62 @@ function responseError(status, text) {
     `RNX Cloud request failed (${status})${text.trim() ? `: ${text.trim()}` : ""}`
   );
 }
+function readCloudErrorCode(text) {
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    return null;
+  }
+  if (!isRecord(parsed)) return null;
+  if (typeof parsed.error === "string") return parsed.error;
+  if (isRecord(parsed.error) && typeof parsed.error.code === "string") {
+    return parsed.error.code;
+  }
+  return null;
+}
+function readRetryAfterMs(response, text) {
+  const header = response.headers.get("retry-after");
+  if (header !== null) {
+    const seconds = Number(header.trim());
+    if (Number.isFinite(seconds) && seconds >= 0) return seconds * 1e3;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    return null;
+  }
+  if (isRecord(parsed) && typeof parsed.retryAfterMs === "number" && Number.isFinite(parsed.retryAfterMs) && parsed.retryAfterMs >= 0) {
+    return parsed.retryAfterMs;
+  }
+  return null;
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function fetchWithCloudRetry(url, init, options) {
+  let attempt = 0;
+  for (; ; ) {
+    const response = await fetch(
+      url,
+      options?.timeoutMs === void 0 ? init : { ...init, signal: AbortSignal.timeout(options.timeoutMs) }
+    );
+    if (response.ok) return response;
+    const retryableStatus = response.status === 429 || response.status >= 500;
+    if (!retryableStatus || attempt >= CLOUD_MAX_RETRIES) return response;
+    const text = await response.text();
+    const code = readCloudErrorCode(text);
+    const retryable = response.status >= 500 ? !(code !== null && CLOUD_NEVER_RETRY_CODES.has(code)) : code === "rate_limited";
+    if (!retryable) {
+      return new Response(text, { status: response.status, headers: response.headers });
+    }
+    if (response.status === 429) {
+      await sleep(readRetryAfterMs(response, text) ?? 1e3);
+    }
+    attempt += 1;
+  }
+}
 function copyArrayBuffer(bytes) {
   const copy = new ArrayBuffer(bytes.byteLength);
   new Uint8Array(copy).set(bytes);
@@ -321,7 +379,7 @@ var RemoteSimulator = class {
     };
     let response;
     try {
-      response = await fetch(
+      response = await fetchWithCloudRetry(
         `${this.session.origin}/v1/sims/${encodeURIComponent(this.session.simId)}/commands`,
         {
           method: "POST",
@@ -329,9 +387,9 @@ var RemoteSimulator = class {
             authorization: `Bearer ${this.session.simulatorToken}`,
             "content-type": "application/json"
           },
-          body: JSON.stringify(body),
-          ...options?.timeoutMs ? { signal: AbortSignal.timeout(options.timeoutMs) } : {}
-        }
+          body: JSON.stringify(body)
+        },
+        options?.timeoutMs === void 0 ? void 0 : { timeoutMs: options.timeoutMs }
       );
     } catch (error) {
       throw new Error(
@@ -356,7 +414,7 @@ var RemoteSimulator = class {
     return parsed.result;
   }
   async confirm() {
-    const response = await fetch(
+    const response = await fetchWithCloudRetry(
       `${this.session.origin}/v1/sims/${encodeURIComponent(this.session.simId)}/claim`,
       {
         method: "POST",
@@ -383,7 +441,7 @@ var RemoteSimulator = class {
     return claim;
   }
   async close() {
-    const response = await fetch(
+    const response = await fetchWithCloudRetry(
       `${this.session.origin}/v1/boxes/${encodeURIComponent(this.session.boxId)}`,
       {
         method: "DELETE",
@@ -414,7 +472,7 @@ async function createRemoteSimulator(input) {
   const device = input.device?.trim() || DEFAULT_DEVICE;
   let response;
   try {
-    response = await fetch(`${origin}/v1/boxes`, {
+    response = await fetchWithCloudRetry(`${origin}/v1/boxes`, {
       method: "POST",
       headers: {
         authorization: input.authorization,

package/dist-lib/cloud.mjs

@@ -1,4 +1,4 @@
-/*! rnx v0.1.513 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
+/*! rnx v0.1.514 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
 var __defProp = Object.defineProperty;
 var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
 var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
@@ -109,6 +109,8 @@ var rnxPublicBrand = Object.freeze({
 // src/cloud.ts
 var DEFAULT_DEVICE = "iphone-16";
 var DEFAULT_WAIT_READY_MS = 2e4;
+var CLOUD_MAX_RETRIES = 2;
+var CLOUD_NEVER_RETRY_CODES = /* @__PURE__ */ new Set(["concurrency_limit", "early_access"]);
 function isRecord(value) {
   return value !== null && typeof value === "object" && !Array.isArray(value);
 }
@@ -146,6 +148,62 @@ function responseError(status, text) {
     `RNX Cloud request failed (${status})${text.trim() ? `: ${text.trim()}` : ""}`
   );
 }
+function readCloudErrorCode(text) {
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    return null;
+  }
+  if (!isRecord(parsed)) return null;
+  if (typeof parsed.error === "string") return parsed.error;
+  if (isRecord(parsed.error) && typeof parsed.error.code === "string") {
+    return parsed.error.code;
+  }
+  return null;
+}
+function readRetryAfterMs(response, text) {
+  const header = response.headers.get("retry-after");
+  if (header !== null) {
+    const seconds = Number(header.trim());
+    if (Number.isFinite(seconds) && seconds >= 0) return seconds * 1e3;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    return null;
+  }
+  if (isRecord(parsed) && typeof parsed.retryAfterMs === "number" && Number.isFinite(parsed.retryAfterMs) && parsed.retryAfterMs >= 0) {
+    return parsed.retryAfterMs;
+  }
+  return null;
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function fetchWithCloudRetry(url, init, options) {
+  let attempt = 0;
+  for (; ; ) {
+    const response = await fetch(
+      url,
+      options?.timeoutMs === void 0 ? init : { ...init, signal: AbortSignal.timeout(options.timeoutMs) }
+    );
+    if (response.ok) return response;
+    const retryableStatus = response.status === 429 || response.status >= 500;
+    if (!retryableStatus || attempt >= CLOUD_MAX_RETRIES) return response;
+    const text = await response.text();
+    const code = readCloudErrorCode(text);
+    const retryable = response.status >= 500 ? !(code !== null && CLOUD_NEVER_RETRY_CODES.has(code)) : code === "rate_limited";
+    if (!retryable) {
+      return new Response(text, { status: response.status, headers: response.headers });
+    }
+    if (response.status === 429) {
+      await sleep(readRetryAfterMs(response, text) ?? 1e3);
+    }
+    attempt += 1;
+  }
+}
 function copyArrayBuffer(bytes) {
   const copy = new ArrayBuffer(bytes.byteLength);
   new Uint8Array(copy).set(bytes);
@@ -294,7 +352,7 @@ var RemoteSimulator = class {
     };
     let response;
     try {
-      response = await fetch(
+      response = await fetchWithCloudRetry(
         `${this.session.origin}/v1/sims/${encodeURIComponent(this.session.simId)}/commands`,
         {
           method: "POST",
@@ -302,9 +360,9 @@ var RemoteSimulator = class {
             authorization: `Bearer ${this.session.simulatorToken}`,
             "content-type": "application/json"
           },
-          body: JSON.stringify(body),
-          ...options?.timeoutMs ? { signal: AbortSignal.timeout(options.timeoutMs) } : {}
-        }
+          body: JSON.stringify(body)
+        },
+        options?.timeoutMs === void 0 ? void 0 : { timeoutMs: options.timeoutMs }
       );
     } catch (error) {
       throw new Error(
@@ -329,7 +387,7 @@ var RemoteSimulator = class {
     return parsed.result;
   }
   async confirm() {
-    const response = await fetch(
+    const response = await fetchWithCloudRetry(
       `${this.session.origin}/v1/sims/${encodeURIComponent(this.session.simId)}/claim`,
       {
         method: "POST",
@@ -356,7 +414,7 @@ var RemoteSimulator = class {
     return claim;
   }
   async close() {
-    const response = await fetch(
+    const response = await fetchWithCloudRetry(
       `${this.session.origin}/v1/boxes/${encodeURIComponent(this.session.boxId)}`,
       {
         method: "DELETE",
@@ -387,7 +445,7 @@ async function createRemoteSimulator(input) {
   const device = input.device?.trim() || DEFAULT_DEVICE;
   let response;
   try {
-    response = await fetch(`${origin}/v1/boxes`, {
+    response = await fetchWithCloudRetry(`${origin}/v1/boxes`, {
       method: "POST",
       headers: {
         authorization: input.authorization,

package/dist-lib/config.cjs

@@ -1,4 +1,4 @@
-/*! rnx v0.1.513 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
+/*! rnx v0.1.514 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
 let __sootsim_import_meta_url = ''; try { __sootsim_import_meta_url = require('url').pathToFileURL(__filename).href; } catch {}
 "use strict";
 var __defProp = Object.defineProperty;

package/dist-lib/detox/index.cjs

@@ -1,4 +1,4 @@
-/*! rnx v0.1.513 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
+/*! rnx v0.1.514 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
 let __sootsim_import_meta_url = ''; try { __sootsim_import_meta_url = require('url').pathToFileURL(__filename).href; } catch {}
 "use strict";
 var __create = Object.create;

package/dist-lib/dev-bundle-resolution.cjs

@@ -1,4 +1,4 @@
-/*! rnx v0.1.513 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
+/*! rnx v0.1.514 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
 let __sootsim_import_meta_url = ''; try { __sootsim_import_meta_url = require('url').pathToFileURL(__filename).href; } catch {}
 "use strict";
 var __defProp = Object.defineProperty;

package/dist-lib/home-paths.cjs

@@ -1,4 +1,4 @@
-/*! rnx v0.1.513 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
+/*! rnx v0.1.514 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
 let __sootsim_import_meta_url = ''; try { __sootsim_import_meta_url = require('url').pathToFileURL(__filename).href; } catch {}
 "use strict";
 var __create = Object.create;

package/dist-lib/host/bridge-host.cjs

@@ -1,4 +1,4 @@
-/*! rnx v0.1.513 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
+/*! rnx v0.1.514 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
 let __sootsim_import_meta_url = ''; try { __sootsim_import_meta_url = require('url').pathToFileURL(__filename).href; } catch {}
 "use strict";
 var __create = Object.create;

package/dist-lib/host/fetch-proxy-handler.cjs

@@ -1,4 +1,4 @@
-/*! rnx v0.1.513 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
+/*! rnx v0.1.514 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
 let __sootsim_import_meta_url = ''; try { __sootsim_import_meta_url = require('url').pathToFileURL(__filename).href; } catch {}
 "use strict";
 var __create = Object.create;

package/dist-lib/host/fetch-proxy-overrides.cjs

@@ -1,4 +1,4 @@
-/*! rnx v0.1.513 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
+/*! rnx v0.1.514 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
 let __sootsim_import_meta_url = ''; try { __sootsim_import_meta_url = require('url').pathToFileURL(__filename).href; } catch {}
 "use strict";
 var __defProp = Object.defineProperty;

package/dist-lib/host/fetch-proxy-overrides.mjs

@@ -1,4 +1,4 @@
-/*! rnx v0.1.513 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
+/*! rnx v0.1.514 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
 
 // src/host/fetch-proxy-overrides.ts
 var FETCH_PROXY_BROWSER_USER_AGENT = "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/146.0.0.0 Safari/537.36";

package/dist-lib/host/replacement-module-handler.cjs

@@ -1,4 +1,4 @@
-/*! rnx v0.1.513 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
+/*! rnx v0.1.514 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
 let __sootsim_import_meta_url = ''; try { __sootsim_import_meta_url = require('url').pathToFileURL(__filename).href; } catch {}
 "use strict";
 var __create = Object.create;

package/dist-lib/host/websocket-proxy.cjs

@@ -1,4 +1,4 @@
-/*! rnx v0.1.513 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
+/*! rnx v0.1.514 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
 let __sootsim_import_meta_url = ''; try { __sootsim_import_meta_url = require('url').pathToFileURL(__filename).href; } catch {}
 "use strict";
 var __defProp = Object.defineProperty;

package/dist-lib/index.cjs

@@ -1,4 +1,4 @@
-/*! rnx v0.1.513 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
+/*! rnx v0.1.514 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
 let __sootsim_import_meta_url = ''; try { __sootsim_import_meta_url = require('url').pathToFileURL(__filename).href; } catch {}
 "use strict";
 var __create = Object.create;

package/dist-lib/jump-to-source-babel.cjs

@@ -1,4 +1,4 @@
-/*! rnx v0.1.513 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
+/*! rnx v0.1.514 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
 let __sootsim_import_meta_url = ''; try { __sootsim_import_meta_url = require('url').pathToFileURL(__filename).href; } catch {}
 "use strict";
 var __defProp = Object.defineProperty;

package/dist-lib/jump-to-source-native.cjs

@@ -1,4 +1,4 @@
-/*! rnx v0.1.513 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
+/*! rnx v0.1.514 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
 let __sootsim_import_meta_url = ''; try { __sootsim_import_meta_url = require('url').pathToFileURL(__filename).href; } catch {}
 "use strict";
 var __create = Object.create;

package/dist-lib/menu.cjs

@@ -1,4 +1,4 @@
-/*! rnx v0.1.513 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
+/*! rnx v0.1.514 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
 let __sootsim_import_meta_url = ''; try { __sootsim_import_meta_url = require('url').pathToFileURL(__filename).href; } catch {}
 "use strict";
 var __defProp = Object.defineProperty;

package/dist-lib/menu.mjs

@@ -1,4 +1,4 @@
-/*! rnx v0.1.513 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
+/*! rnx v0.1.514 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
 
 // src/public-brand.ts
 var name = "rnx";

package/dist-lib/metro-fingerprint-registry.cjs

@@ -1,4 +1,4 @@
-/*! rnx v0.1.513 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
+/*! rnx v0.1.514 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
 let __sootsim_import_meta_url = ''; try { __sootsim_import_meta_url = require('url').pathToFileURL(__filename).href; } catch {}
 "use strict";
 var __defProp = Object.defineProperty;

package/dist-lib/metro-fingerprint-registry.mjs

@@ -1,4 +1,4 @@
-/*! rnx v0.1.513 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
+/*! rnx v0.1.514 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
 
 // src/metro-fingerprint-registry.ts
 var RNX_METRO_FINGERPRINT_SCHEMA_VERSION = 2;

package/dist-lib/metro-production-bundle.cjs

@@ -1,4 +1,4 @@
-/*! rnx v0.1.513 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
+/*! rnx v0.1.514 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
 let __sootsim_import_meta_url = ''; try { __sootsim_import_meta_url = require('url').pathToFileURL(__filename).href; } catch {}
 "use strict";
 var __defProp = Object.defineProperty;

package/dist-lib/metro-production-bundle.mjs

@@ -1,4 +1,4 @@
-/*! rnx v0.1.513 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
+/*! rnx v0.1.514 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
 
 // src/metro-production-bundle.ts
 var RNXSIM_METRO_MODULE_PATHS_PREFIX = "globalThis.__sootsimModulePaths=";

package/dist-lib/metro.cjs

@@ -1,4 +1,4 @@
-/*! rnx v0.1.513 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
+/*! rnx v0.1.514 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
 let __sootsim_import_meta_url = ''; try { __sootsim_import_meta_url = require('url').pathToFileURL(__filename).href; } catch {}
 "use strict";
 var __create = Object.create;

package/dist-lib/profiles.cjs

@@ -1,4 +1,4 @@
-/*! rnx v0.1.513 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
+/*! rnx v0.1.514 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
 let __sootsim_import_meta_url = ''; try { __sootsim_import_meta_url = require('url').pathToFileURL(__filename).href; } catch {}
 "use strict";
 var __create = Object.create;

package/dist-lib/public-brand.cjs

@@ -1,4 +1,4 @@
-/*! rnx v0.1.513 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
+/*! rnx v0.1.514 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
 let __sootsim_import_meta_url = ''; try { __sootsim_import_meta_url = require('url').pathToFileURL(__filename).href; } catch {}
 "use strict";
 var __defProp = Object.defineProperty;

package/dist-lib/react-native-host-modules.cjs

@@ -1,4 +1,4 @@
-/*! rnx v0.1.513 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
+/*! rnx v0.1.514 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
 let __sootsim_import_meta_url = ''; try { __sootsim_import_meta_url = require('url').pathToFileURL(__filename).href; } catch {}
 "use strict";
 var __defProp = Object.defineProperty;

package/dist-lib/react-native-host-modules.mjs

@@ -1,4 +1,4 @@
-/*! rnx v0.1.513 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
+/*! rnx v0.1.514 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
 
 // src/react-native-host-modules.ts
 var REACT_NATIVE_PASSTHROUGH_SPECIFIERS = [

package/dist-lib/render-mode.cjs

@@ -1,4 +1,4 @@
-/*! rnx v0.1.513 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
+/*! rnx v0.1.514 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
 let __sootsim_import_meta_url = ''; try { __sootsim_import_meta_url = require('url').pathToFileURL(__filename).href; } catch {}
 "use strict";
 var __defProp = Object.defineProperty;

package/dist-lib/scripts/dev-server-scanner.cjs

@@ -1,4 +1,4 @@
-/*! rnx v0.1.513 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
+/*! rnx v0.1.514 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
 let __sootsim_import_meta_url = ''; try { __sootsim_import_meta_url = require('url').pathToFileURL(__filename).href; } catch {}
 "use strict";
 var __create = Object.create;

package/dist-lib/sdk.cjs

@@ -1,4 +1,4 @@
-/*! rnx v0.1.513 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
+/*! rnx v0.1.514 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
 let __sootsim_import_meta_url = ''; try { __sootsim_import_meta_url = require('url').pathToFileURL(__filename).href; } catch {}
 "use strict";
 var __defProp = Object.defineProperty;

package/dist-lib/sdk.mjs

@@ -1,4 +1,4 @@
-/*! rnx v0.1.513 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
+/*! rnx v0.1.514 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
 var __defProp = Object.defineProperty;
 var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
 var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);

package/dist-lib/skills.cjs

@@ -1,4 +1,4 @@
-/*! rnx v0.1.513 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
+/*! rnx v0.1.514 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
 let __sootsim_import_meta_url = ''; try { __sootsim_import_meta_url = require('url').pathToFileURL(__filename).href; } catch {}
 "use strict";
 var __create = Object.create;

package/dist-lib/swift.cjs

@@ -1,4 +1,4 @@
-/*! rnx v0.1.513 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
+/*! rnx v0.1.514 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
 let __sootsim_import_meta_url = ''; try { __sootsim_import_meta_url = require('url').pathToFileURL(__filename).href; } catch {}
 "use strict";
 var __defProp = Object.defineProperty;

package/dist-lib/vite.cjs

@@ -1,4 +1,4 @@
-/*! rnx v0.1.513 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
+/*! rnx v0.1.514 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
 let __sootsim_import_meta_url = ''; try { __sootsim_import_meta_url = require('url').pathToFileURL(__filename).href; } catch {}
 "use strict";
 var __create = Object.create;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rnxsim",
-  "version": "0.1.513",
+  "version": "0.1.514",
   "description": "Vite and Metro plugins, testing drivers, and SDK exports for rnx.",
   "author": "Tamagui LLC",
   "license": "SEE LICENSE IN LICENSE",

package/src/cloud-contract.ts

@@ -58,3 +58,123 @@ export interface RnxCloudBoxCreateReceipt {
   }
   simulator: RnxCloudCreateReceipt
 }
+
+// what a cloud simulator reports. the stored lifecycle values are
+// `creating`/`open`/`hibernated`/`deleting`; `deleted` is only ever a response,
+// answered by a delete, because a deleted simulator has no row left to read.
+export type RnxCloudSimStatus =
+  | 'creating'
+  | 'open'
+  | 'hibernated'
+  | 'deleting'
+  | 'deleted'
+
+// one simulator as the instance list reports it: the lifecycle view plus the
+// labels it was created with.
+export interface RnxCloudSimView {
+  simId: string
+  status: RnxCloudSimStatus
+  labels: Record<string, string>
+  artifact: { sha256: string; bytes: number }
+  claim: RnxCloudClaim | null
+  createdAt: number
+  lastActiveAt: number
+  lastHibernatedAt?: number
+  storageFrom?: string
+  /** the idle window the creator set, or null for the service default. */
+  inactivityTimeoutMs: number | null
+  /** the instant the creator's hard timeout stops this simulator, or null. */
+  hardTimeoutAt: number | null
+}
+
+// one simulator as create and get report it, with the watch URL a browser
+// opens to see it.
+export interface RnxCloudSimInstance extends RnxCloudSimView {
+  /** a watch URL with its grant in the fragment, or null when none can be
+   * minted yet: an unconfirmed simulator is not watchable. */
+  streamUrl: string | null
+}
+
+// the create/reuse answer: the receipt the box path also returns, plus what
+// only the instance API knows.
+export interface RnxCloudSimCreateResponse extends RnxCloudCreateReceipt {
+  token: string
+  status: RnxCloudSimStatus
+  labels: Record<string, string>
+  streamUrl: string | null
+}
+
+// one grammar for the create map and the list selector: `key=value,key2=value2`.
+// a value may be empty; a key may not; a repeated key is the caller's mistake
+// rather than a silent last-one-wins. commas and control characters never
+// belong in a key or value, and 63 characters is the ceiling for either.
+export const RNX_CLOUD_LABELS_MAX_COUNT = 16
+export const RNX_CLOUD_LABEL_MAX_LENGTH = 63
+
+const RNX_CLOUD_LABEL_CONTROL = /[\u0000-\u001f\u007f]/
+
+export function isValidRnxCloudLabel(key: string, value: string): boolean {
+  return (
+    key.length > 0 &&
+    key.length <= RNX_CLOUD_LABEL_MAX_LENGTH &&
+    value.length <= RNX_CLOUD_LABEL_MAX_LENGTH &&
+    !key.includes(',') &&
+    !key.includes('=') &&
+    !value.includes(',') &&
+    !RNX_CLOUD_LABEL_CONTROL.test(key) &&
+    !RNX_CLOUD_LABEL_CONTROL.test(value)
+  )
+}
+
+/** the wire form, or null when it is not one. `''` is the empty map. */
+export function parseRnxCloudLabels(value: string): Record<string, string> | null {
+  if (value === '') return {}
+  const entries = value.split(',')
+  if (entries.length > RNX_CLOUD_LABELS_MAX_COUNT) return null
+  const labels: Record<string, string> = {}
+  for (const entry of entries) {
+    const separator = entry.indexOf('=')
+    if (separator < 1) return null
+    const key = entry.slice(0, separator).trim()
+    const label = entry.slice(separator + 1).trim()
+    if (!isValidRnxCloudLabel(key, label)) return null
+    if (Object.hasOwn(labels, key)) return null
+    labels[key] = label
+  }
+  return labels
+}
+
+/** the same grammar with the map already split apart, as a json body carries
+ * it. anything the wire form would refuse is refused here too. */
+export function readRnxCloudLabels(value: unknown): Record<string, string> | null {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return null
+  const entries = Object.entries(value)
+  if (entries.length > RNX_CLOUD_LABELS_MAX_COUNT) return null
+  const labels: Record<string, string> = {}
+  for (const [key, label] of entries) {
+    if (typeof label !== 'string') return null
+    if (!isValidRnxCloudLabel(key, label)) return null
+    labels[key] = label
+  }
+  return labels
+}
+
+/** every selector entry must be present with the same value. an empty
+ * selector selects everything. */
+export function matchesRnxCloudLabels(
+  labels: Record<string, string>,
+  selector: Record<string, string>,
+): boolean {
+  return Object.entries(selector).every(([key, value]) => labels[key] === value)
+}
+
+/** the selector an instance list filters by, given the statuses it accepts. */
+export function isRnxCloudSimStatus(value: string): value is RnxCloudSimStatus {
+  return (
+    value === 'creating' ||
+    value === 'open' ||
+    value === 'hibernated' ||
+    value === 'deleting' ||
+    value === 'deleted'
+  )
+}

package/src/cloud.ts

@@ -26,6 +26,15 @@ export type { RnxCloudClaim, RnxCloudCreateReceipt, RnxScreenCapture }
 const DEFAULT_DEVICE = 'iphone-16'
 const DEFAULT_WAIT_READY_MS = 20_000
 
+// how many times a request goes back after a retryable refusal or a server
+// error. the sim service passes the account's own 429 bodies through, so the
+// code on the body is what decides: `rate_limited` carries a `retry-after`
+// and is worth waiting for, while `concurrency_limit` refuses until the
+// customer stops something and retrying only hammers a closed door.
+// `early_access` and 402 never change on retry either.
+const CLOUD_MAX_RETRIES = 2
+const CLOUD_NEVER_RETRY_CODES = new Set(['concurrency_limit', 'early_access'])
+
 export type RemoteCommand = {
   type: (typeof RNX_CLOUD_COMMAND_TYPES)[number]
   [key: string]: unknown
@@ -117,6 +126,86 @@ function responseError(status: number, text: string): Error {
   )
 }
 
+function readCloudErrorCode(text: string): string | null {
+  // the account api answers `{ error: 'code', message }` and the sim service
+  // `{ error: { code, message } }`; both reach this client, so both read.
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(text)
+  } catch {
+    return null
+  }
+  if (!isRecord(parsed)) return null
+  if (typeof parsed.error === 'string') return parsed.error
+  if (isRecord(parsed.error) && typeof parsed.error.code === 'string') {
+    return parsed.error.code
+  }
+  return null
+}
+
+function readRetryAfterMs(response: Response, text: string): number | null {
+  const header = response.headers.get('retry-after')
+  if (header !== null) {
+    const seconds = Number(header.trim())
+    if (Number.isFinite(seconds) && seconds >= 0) return seconds * 1000
+  }
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(text)
+  } catch {
+    return null
+  }
+  if (
+    isRecord(parsed) &&
+    typeof parsed.retryAfterMs === 'number' &&
+    Number.isFinite(parsed.retryAfterMs) &&
+    parsed.retryAfterMs >= 0
+  ) {
+    return parsed.retryAfterMs
+  }
+  return null
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms))
+}
+
+// one fetch with the cloud retry policy: `rate_limited` waits out its
+// `retry-after` and 5xx goes again at once, each at most twice, and nothing
+// else is retried. the body is buffered only on a retryable status, so every
+// other refusal reaches the caller on its original response.
+async function fetchWithCloudRetry(
+  url: string,
+  init: RequestInit,
+  options?: { timeoutMs?: number },
+): Promise<Response> {
+  let attempt = 0
+  for (;;) {
+    const response = await fetch(
+      url,
+      options?.timeoutMs === undefined
+        ? init
+        : { ...init, signal: AbortSignal.timeout(options.timeoutMs) },
+    )
+    if (response.ok) return response
+    const retryableStatus = response.status === 429 || response.status >= 500
+    if (!retryableStatus || attempt >= CLOUD_MAX_RETRIES) return response
+    const text = await response.text()
+    const code = readCloudErrorCode(text)
+    const retryable =
+      response.status >= 500
+        ? !(code !== null && CLOUD_NEVER_RETRY_CODES.has(code))
+        : code === 'rate_limited'
+    if (!retryable) {
+      return new Response(text, { status: response.status, headers: response.headers })
+    }
+    if (response.status === 429) {
+      await sleep(readRetryAfterMs(response, text) ?? 1000)
+    }
+    attempt += 1
+  }
+}
+
 function copyArrayBuffer(bytes: Uint8Array): ArrayBuffer {
   const copy = new ArrayBuffer(bytes.byteLength)
   new Uint8Array(copy).set(bytes)
@@ -325,7 +414,7 @@ export class RemoteSimulator {
     }
     let response: Response
     try {
-      response = await fetch(
+      response = await fetchWithCloudRetry(
         `${this.session.origin}/v1/sims/${encodeURIComponent(this.session.simId)}/commands`,
         {
           method: 'POST',
@@ -334,10 +423,8 @@ export class RemoteSimulator {
             'content-type': 'application/json',
           },
           body: JSON.stringify(body),
-          ...(options?.timeoutMs
-            ? { signal: AbortSignal.timeout(options.timeoutMs) }
-            : {}),
         },
+        options?.timeoutMs === undefined ? undefined : { timeoutMs: options.timeoutMs },
       )
     } catch (error) {
       throw new Error(
@@ -365,7 +452,7 @@ export class RemoteSimulator {
   }
 
   async confirm(): Promise<RnxCloudClaim> {
-    const response = await fetch(
+    const response = await fetchWithCloudRetry(
       `${this.session.origin}/v1/sims/${encodeURIComponent(this.session.simId)}/claim`,
       {
         method: 'POST',
@@ -393,7 +480,7 @@ export class RemoteSimulator {
   }
 
   async close(): Promise<void> {
-    const response = await fetch(
+    const response = await fetchWithCloudRetry(
       `${this.session.origin}/v1/boxes/${encodeURIComponent(this.session.boxId)}`,
       {
         method: 'DELETE',
@@ -427,7 +514,7 @@ export async function createRemoteSimulator(
   const device = input.device?.trim() || DEFAULT_DEVICE
   let response: Response
   try {
-    response = await fetch(`${origin}/v1/boxes`, {
+    response = await fetchWithCloudRetry(`${origin}/v1/boxes`, {
       method: 'POST',
       headers: {
         authorization: input.authorization,