serve-sim 0.1.49-beta.141.1 → 0.1.49

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "serve-sim",
-  "version": "0.1.49-beta.141.1",
+  "version": "0.1.49",
   "type": "module",
   "author": {
     "name": "Evan Bacon",

package/src/device-hub-input.ts

@@ -1,5 +1,6 @@
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
+import { simctlArguments } from "./simctl";
 
 const exec = promisify(execFile);
 type Run = (args: string[]) => Promise<string>;
@@ -13,7 +14,7 @@ export function isDeviceHubInputShadowed(output: string): boolean {
 /** Warns when shadowed. Resolves the guest flag, or undefined when the runtime does not publish it. */
 export async function warnDeviceHubInput(udid: string, invoke: Run = run): Promise<boolean | undefined> {
   try {
-    const shadowed = isDeviceHubInputShadowed(await invoke(["simctl", "spawn", udid, "notifyutil", "-g", key]));
+    const shadowed = isDeviceHubInputShadowed(await invoke(simctlArguments(["spawn", udid, "notifyutil", "-g", key])));
     if (shadowed) {
       console.warn(`[hid] Device Hub has disconnected legacy input. Run serve-sim repair-input -d ${udid} before using touch or keyboard. Repair restarts SpringBoard and closes running apps.`);
     }
@@ -24,7 +25,7 @@ export async function warnDeviceHubInput(udid: string, invoke: Run = run): Promi
 /** Raw guest flag for diagnostics: true/false, or null when unreadable. */
 export async function readDeviceHubInputShadowed(udid: string, invoke: Run = run): Promise<boolean | null> {
   try {
-    return isDeviceHubInputShadowed(await invoke(["simctl", "spawn", udid, "notifyutil", "-g", key]));
+    return isDeviceHubInputShadowed(await invoke(simctlArguments(["spawn", udid, "notifyutil", "-g", key])));
   } catch {
     return null;
   }
@@ -32,7 +33,7 @@ export async function readDeviceHubInputShadowed(udid: string, invoke: Run = run
 
 /** Explicit recovery only: restarting backboardd also terminates running apps. */
 export async function repairDeviceHubInput(udid: string, invoke: Run = run): Promise<boolean> {
-  const args = ["simctl", "spawn", udid];
+  const args = simctlArguments(["spawn", udid]);
   if (!isDeviceHubInputShadowed(await invoke([...args, "notifyutil", "-g", key]))) return false;
   // Order is essential: the replacement backboardd must start with state zero.
   await invoke([...args, "notifyutil", "-s", key, "0"]);

package/src/device.ts

@@ -1,4 +1,5 @@
-import { execSync } from "child_process";
+import { execFileSync } from "child_process";
+import { simctlArguments } from "./simctl";
 
 /**
  * UDID of a booted simulator, or null if none is booted. Prefers an iOS device
@@ -7,7 +8,7 @@ import { execSync } from "child_process";
  */
 export function findBootedDevice(): string | null {
   try {
-    const output = execSync("xcrun simctl list devices booted -j", { encoding: "utf-8" });
+    const output = execFileSync("xcrun", simctlArguments(["list", "devices", "booted", "-j"]), { encoding: "utf-8" });
     const data = JSON.parse(output) as {
       devices: Record<string, Array<{ udid: string; name: string; state: string }>>;
     };
@@ -24,6 +25,17 @@ export function findBootedDevice(): string | null {
   return null;
 }
 
+/** Whether the selected device set lists `udid`, in any case, as simctl reads it. */
+export function isInDeviceSet(udid: string): boolean {
+  try {
+    const output = execFileSync("xcrun", simctlArguments(["list", "devices", "-j"]), { encoding: "utf-8" });
+    const data = JSON.parse(output) as { devices: Record<string, Array<{ udid: string }>> };
+    return Object.values(data.devices).some((devices) => devices.some((device) => device.udid.toUpperCase() === udid.toUpperCase()));
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Resolve a device name or UDID to a UDID. A UDID is returned as-is; a name is
  * matched case-insensitively against `simctl list devices`. Exits the process
@@ -34,7 +46,7 @@ export function resolveDevice(nameOrUDID: string): string {
     return nameOrUDID;
   }
   try {
-    const output = execSync("xcrun simctl list devices -j", { encoding: "utf-8" });
+    const output = execFileSync("xcrun", simctlArguments(["list", "devices", "-j"]), { encoding: "utf-8" });
     const data = JSON.parse(output) as {
       devices: Record<string, Array<{ udid: string; name: string; state: string }>>;
     };

package/src/doctor.ts

@@ -10,6 +10,7 @@ import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { duoModelPath, resolveDuoModel, resolveDuoRendererExecutable } from "./duo-renderer";
+import { simctlArguments } from "./simctl";
 import { readDeviceHubInputShadowed } from "./device-hub-input";
 import { redactHome } from "./diagnostics-redact";
 
@@ -144,7 +145,7 @@ export async function collectHostDiagnostics(options: HostDiagnosticsOptions = {
 
 /** Simulator facts for one UDID from `simctl list -j`, plus the guest Device Hub input flag. */
 export async function collectDeviceDiagnostics(udid: string, probe: Probe = defaultProbe): Promise<Record<string, unknown>> {
-  const listing = await probe("/usr/bin/xcrun", ["simctl", "list", "devices", "-j"]);
+  const listing = await probe("/usr/bin/xcrun", simctlArguments(["list", "devices", "-j"]));
   let device: Record<string, unknown> | null = null;
   try {
     const parsed = JSON.parse(listing ?? "{}") as { devices?: Record<string, Array<Record<string, unknown>>> };

package/src/duo-state.ts

@@ -1,5 +1,6 @@
 import { execFile, spawn, type ChildProcess } from "node:child_process";
 import type { SimulatorOrientation } from "./client/types";
+import { simctlArguments } from "./simctl";
 
 export function parseHingeSample(line: string): number | null {
   if (!/AngleValid:Y\b/.test(line)) return null;
@@ -60,7 +61,7 @@ export class DuoStateMonitor {
   refreshOrientation(): void {
     if (this.stopped || this.enumeration) return;
     if (this.poll) clearTimeout(this.poll);
-    this.enumeration = execFile("/usr/bin/xcrun", ["simctl", "io", this.udid, "enumerate"],
+    this.enumeration = execFile("/usr/bin/xcrun", simctlArguments(["io", this.udid, "enumerate"]),
       { timeout: 3000, maxBuffer: 1024 * 1024 }, (error, stdout) => {
         this.enumeration = undefined;
         if (this.stopped) return;
@@ -88,7 +89,7 @@ export class DuoStateMonitor {
       this.onState(this.state);
       this.refreshOrientation();
     };
-    const child = spawn("/usr/bin/xcrun", ["simctl", "spawn", this.udid, "log", "stream", "--style", "compact", "--predicate", predicate], { stdio: ["ignore", "pipe", "ignore"] });
+    const child = spawn("/usr/bin/xcrun", simctlArguments(["spawn", this.udid, "log", "stream", "--style", "compact", "--predicate", predicate]), { stdio: ["ignore", "pipe", "ignore"] });
     this.panelMonitor = child;
     let pending = "";
     child.stdout.setEncoding("utf8");
@@ -102,7 +103,7 @@ export class DuoStateMonitor {
       }
     });
     // Seed from this boot's most recent transition, then let live events win.
-    this.panelSeed = execFile("/usr/bin/xcrun", ["simctl", "spawn", this.udid, "log", "show", "--last", "boot", "--style", "compact", "--predicate", predicate],
+    this.panelSeed = execFile("/usr/bin/xcrun", simctlArguments(["spawn", this.udid, "log", "show", "--last", "boot", "--style", "compact", "--predicate", predicate]),
       { timeout: 10000, maxBuffer: 4 * 1024 * 1024 }, (error, stdout) => {
         this.panelSeed = undefined;
         if (!error && !liveSample) {

package/src/event-log.ts

@@ -627,9 +627,11 @@ function isUploadPlumbing(tokens: string[]): boolean {
 function simctlCommand(tokens: string[]): { verb: string; args: string[] } | null {
   const i = tokens.findIndex((token) => token === "simctl");
   if (i < 0 || tokens[i - 1] !== "xcrun") return null;
-  const verb = tokens[i + 1];
+  // `simctl --set <path> <verb>` (a `--device-set`) names its verb after the set.
+  const v = tokens[i + 1] === "--set" ? i + 3 : i + 1;
+  const verb = tokens[v];
   if (!verb) return null;
-  return { verb, args: tokens.slice(i + 2) };
+  return { verb, args: tokens.slice(v + 1) };
 }
 
 function serveSimCommand(tokens: string[]): { verb: string; args: string[] } | null {

package/src/helper-lifecycle.ts

@@ -16,6 +16,7 @@ import { readFileSync, unlinkSync } from "fs";
 import { sleepSync } from "./runtime";
 import { getPortHolders } from "./ports";
 import { debugHelper, debugState } from "./debug";
+import { sameDeviceSet } from "./simctl";
 import type { ServeSimDeviceState } from "./state";
 import { writeServeSimState } from "./state";
 
@@ -205,10 +206,14 @@ export type StaleStateAction = "keep" | "recycle-self" | "recycle-helper";
  * `recycle-*` as a reason to drop the pidfile — the process is still alive.
  */
 export function classifyStaleState(
-  state: { pid: number; device: string },
+  state: { pid: number; device: string; deviceSet?: string },
   booted: Set<string> | null,
   selfPid: number,
+  deviceSet: string | undefined,
 ): StaleStateAction {
+  // `booted` lists only this process's device set; another set's simulator
+  // is not in it whether or not it is booted.
+  if (!sameDeviceSet(state.deviceSet, deviceSet)) return "keep";
   if (booted && isSimulatorUdid(state.device) && !booted.has(state.device)) {
     return state.pid === selfPid ? "recycle-self" : "recycle-helper";
   }

package/src/host-rpc.ts

@@ -14,6 +14,7 @@ import { homedir } from "os";
 import { basename, dirname, join } from "path";
 import { PERMISSION_SERVICES } from "./client/utils/permissions";
 import { shellJoin } from "./shell-quote";
+import { simctlArguments } from "./simctl";
 import { getUiOption, setUiOption } from "./ui-settings";
 
 // Narrow host actions for the preview page, carried as `{id, rpc}` frames on
@@ -193,7 +194,7 @@ export function createHostRpcHandler(opts: HostRpcOptions): HostRpcHandler {
   };
 
   const appContainer = async (udid: string, bundleId: string): Promise<string> => {
-    const r = await run("xcrun", ["simctl", "get_app_container", udid, bundleId, "app"]);
+    const r = await run("xcrun", simctlArguments(["get_app_container", udid, bundleId, "app"]));
     if (r.exitCode !== 0) fail(r.stderr.trim() || "App not found on simulator");
     const appPath = r.stdout.trim();
     if (!appPath) fail("Empty app path");
@@ -216,7 +217,7 @@ export function createHostRpcHandler(opts: HostRpcOptions): HostRpcHandler {
       const watch = p.watch === true;
       await requireDevice(udid);
       if (watch) return { ...(await run("osascript", WATCH_HOME_SCRIPT.flatMap((line) => ["-e", line]))) };
-      return { ...(await run("xcrun", ["simctl", "launch", udid, "com.apple.springboard"])) };
+      return { ...(await run("xcrun", simctlArguments(["launch", udid, "com.apple.springboard"]))) };
     },
 
     async screenshot(p) {
@@ -224,11 +225,11 @@ export function createHostRpcHandler(opts: HostRpcOptions): HostRpcHandler {
       const display = p.display === undefined ? undefined : enumParam(p, "display", DISPLAYS);
       await requireDevice(udid);
       const path = join(desktop(), `serve-sim-screenshot-${timestampSlug()}.png`);
-      const r = await run("xcrun", [
-        "simctl", "io", udid, "screenshot",
+      const r = await run("xcrun", simctlArguments([
+        "io", udid, "screenshot",
         ...(display ? [`--display=${display}`] : []),
         path,
-      ]);
+      ]));
       return { ...r, path: r.exitCode === 0 ? path : "" };
     },
 
@@ -421,7 +422,7 @@ export function createHostRpcHandler(opts: HostRpcOptions): HostRpcHandler {
         path = screenshotPathParam(p);
       }
       await requireDevice(udid);
-      return { ...(await run("xcrun", ["simctl", "addmedia", udid, path])) };
+      return { ...(await run("xcrun", simctlArguments(["addmedia", udid, path]))) };
     },
 
     async installApp(p) {
@@ -430,7 +431,7 @@ export function createHostRpcHandler(opts: HostRpcOptions): HostRpcHandler {
       const path = uploadPathParam(p, "path", ["install"]);
       if (!path.endsWith(".ipa")) fail("invalid path");
       await requireDevice(udid);
-      return { ...(await run("xcrun", ["simctl", "install", udid, path])) };
+      return { ...(await run("xcrun", simctlArguments(["install", udid, path]))) };
     },
 
     // Set (lat/lng) or clear the simulated location.
@@ -439,7 +440,7 @@ export function createHostRpcHandler(opts: HostRpcOptions): HostRpcHandler {
       const clear = p.lat === undefined && p.lng === undefined;
       const point = clear ? null : `${coordinate(p, "lat", 90).toFixed(7)},${coordinate(p, "lng", 180).toFixed(7)}`;
       await requireDevice(udid);
-      return { ...(await run("xcrun", ["simctl", "location", udid, ...(point ? ["set", point] : ["clear"])])) };
+      return { ...(await run("xcrun", simctlArguments(["location", udid, ...(point ? ["set", point] : ["clear"])]))) };
     },
   };
 

package/src/middleware.ts

@@ -51,7 +51,7 @@ import { createExecUpgradeHandler, EXEC_DISABLED_MESSAGE, type UiRequestHandler
 import { createHostRpcHandler } from "./host-rpc";
 import { UI_OPTIONS, getUiStatus, normalizeUiValue, setUiOption } from "./ui-settings";
 import type { PreviewInitialState } from "./preview-initial-state";
-import { simctlBootStatusArguments } from "./simctl";
+import { resolveDeviceSet, sameDeviceSet, simctlArguments, simctlBootStatusArguments } from "./simctl";
 import { authBootstrapPage } from "./auth-bootstrap";
 import {
   AUTH_COOKIE,
@@ -222,7 +222,7 @@ export function parseForegroundAppLogMessage(message: string): { bundleId: strin
 function detectReactNative(udid: string, bundleId: string): Promise<boolean> {
   if (RN_BUNDLE_IDS.has(bundleId)) return Promise.resolve(true);
   return new Promise((resolve) => {
-    execFile("xcrun", ["simctl", "get_app_container", udid, bundleId, "app"],
+    execFile("xcrun", simctlArguments(["get_app_container", udid, bundleId, "app"]),
       { timeout: 2000 },
       (err, stdout) => {
         if (err) return resolve(false);
@@ -280,7 +280,7 @@ async function getBootedUdids(): Promise<Set<string> | null> {
     const stdout = await new Promise<string>((resolve, reject) => {
       execFile(
         "xcrun",
-        ["simctl", "list", "devices", "booted", "-j"],
+        simctlArguments(["list", "devices", "booted", "-j"]),
         { encoding: "utf-8", timeout: 3_000 },
         (err, stdout) => {
           if (err) {
@@ -338,6 +338,7 @@ export async function readServeSimStates(): Promise<ServeSimState[]> {
     return [];
   }
   const booted = await getBootedUdids();
+  const deviceSet = resolveDeviceSet();
   const states: ServeSimState[] = [];
   for (const f of files) {
     const path = join(STATE_DIR, f);
@@ -350,11 +351,14 @@ export async function readServeSimStates(): Promise<ServeSimState[]> {
         continue;
       }
       if (state.pid !== recorded.pid) persistRecoveredState(state);
+      // Previews in every device set share this folder; another set's
+      // simulator is not one this preview can stream.
+      if (!sameDeviceSet(state.deviceSet, deviceSet)) continue;
       // Helper alive but its simulator was shut down — the MJPEG stream
       // would accept connections yet never produce frames, leaving the
       // preview stuck on "Connecting...". Recycle the stale state so the
       // caller can spawn a fresh helper bound to whatever is booted.
-      const action = classifyStaleState(state, booted, process.pid);
+      const action = classifyStaleState(state, booted, process.pid, deviceSet);
       if (action !== "keep") {
         if (action === "recycle-self") {
           // This device is streamed in-process by *us* (the close button just
@@ -439,11 +443,12 @@ function endpoint(base: string, path: string, device: string): string {
 /**
  * A state record as it may be served over HTTP: drops the server-private
  * fields (the auth-token fingerprint and the exec opt-in recorded for
- * `--detach` reuse checks), which no client needs.
+ * `--detach` reuse checks, and the host path of the device set), which no
+ * client needs.
  */
 export function publicState(state: ServeSimState): ServeSimState {
-  if (!("authTokenSha256" in state) && !("allowExec" in state)) return state;
-  const { authTokenSha256: _fingerprint, allowExec: _allowExec, ...rest } = state;
+  if (!("authTokenSha256" in state) && !("allowExec" in state) && !("deviceSet" in state)) return state;
+  const { authTokenSha256: _fingerprint, allowExec: _allowExec, deviceSet: _deviceSet, ...rest } = state;
   return rest;
 }
 
@@ -887,7 +892,7 @@ export async function startDeviceInProcess(
   record: Pick<ServeSimDeviceState, "authTokenSha256" | "allowExec"> = {},
 ): Promise<string | null> {
   // `simctl boot` errors when already booted — ignore and let bootstatus confirm.
-  await new Promise<void>((resolve) => execFile("xcrun", ["simctl", "boot", udid], () => resolve()));
+  await new Promise<void>((resolve) => execFile("xcrun", simctlArguments(["boot", udid]), () => resolve()));
   const ready = await new Promise<boolean>((resolve) => {
     // Boot was already requested above. Passing `-b` redundantly can remain
     // blocked on Xcode 27 even after `simctl list` reports Booted, so only
@@ -898,7 +903,7 @@ export async function startDeviceInProcess(
     // bootstatus can exit non-zero even when the device is actually ready;
     // confirm against the real state before reporting failure.
     const booted = await new Promise<boolean>((resolve) => {
-      execFile("xcrun", ["simctl", "list", "devices", "-j"], (err, stdout) => {
+      execFile("xcrun", simctlArguments(["list", "devices", "-j"]), (err, stdout) => {
         if (err) return resolve(false);
         try {
           const data = JSON.parse(stdout) as { devices: Record<string, Array<{ udid: string; state: string }>> };
@@ -1244,7 +1249,7 @@ function listAllSimulators(): Promise<SimctlDevice[]> {
   return new Promise((resolve) => {
     execFile(
       "xcrun",
-      ["simctl", "list", "devices", "-j"],
+      simctlArguments(["list", "devices", "-j"]),
       { encoding: "utf-8", timeout: 3_000 },
       (err, stdout) => {
         if (err) return resolve([]);
@@ -1502,6 +1507,9 @@ export function simMiddleware(options?: SimMiddlewareOptions): SimMiddleware {
   const authToken = resolveAuthToken(options?.authToken);
   const serveDiagnostics = createDiagnosticsHandler(options?.diagnostics);
   const serveSimBin = options?.serveSimBin ?? resolveServeSimBin();
+  // A dev server that embeds this middleware never runs the CLI: settle the
+  // device set (and refuse a bad SERVE_SIM_DEVICE_SET) here, not mid-request.
+  resolveDeviceSet();
   // Every path this middleware may answer. Standalone serve-sim mounts at "/"
   // (base ""), so it owns the whole origin; embedded mounts own only `base/…`.
   const ownsPath = (pathname: string) =>
@@ -1904,7 +1912,7 @@ export function simMiddleware(options?: SimMiddlewareOptions): SimMiddleware {
         // Drop the snapshot so the next /grid/api call re-queries simctl
         // and prunes any helper bound to this now-shutdown device.
         bootedSnapshot = { at: 0, booted: null };
-        execFile("xcrun", ["simctl", "shutdown", udid], { timeout: 30_000 }, (err, _stdout, stderr) => {
+        execFile("xcrun", simctlArguments(["shutdown", udid]), { timeout: 30_000 }, (err, _stdout, stderr) => {
           if (err) {
             res.writeHead(500, { "Content-Type": "application/json" });
             res.end(JSON.stringify({
@@ -2450,13 +2458,13 @@ export function simMiddleware(options?: SimMiddlewareOptions): SimMiddleware {
         // AX bridge may be warming up — the log tail fills in once anything moves.
       }
 
-      const child: ChildProcess = spawn("xcrun", [
-        "simctl", "spawn", udid, "log", "stream",
+      const child: ChildProcess = spawn("xcrun", simctlArguments([
+        "spawn", udid, "log", "stream",
         "--style", "ndjson",
         "--level", "info",
         "--predicate",
         'process == "SpringBoard" AND eventMessage CONTAINS "Setting process visibility to: Foreground"',
-      ], { stdio: ["ignore", "pipe", "ignore"] });
+      ]), { stdio: ["ignore", "pipe", "ignore"] });
 
       let closed = false;
       const emitApp = async (bundleId: string, pid?: number) => {

package/src/native.ts

@@ -13,6 +13,7 @@ import { existsSync } from "fs";
 import { fileURLToPath } from "url";
 import { KeySequencer, type KeyType } from "./key-sequencer";
 import { maxBitrateFromEnv } from "./max-bitrate";
+import { resolveDeviceSet } from "./simctl";
 
 export type { KeyType } from "./key-sequencer";
 
@@ -59,6 +60,7 @@ interface NativeAddon {
   SimCapture: new (udid: string, maxBitrate: number | null) => SimCaptureHandle;
   axDescribe(udid: string): Promise<string>;
   axFrontmost(udid: string): Promise<string>;
+  setDeviceSet(path: string | null): void;
 }
 
 // (data, width, height, flags) — codec 0=MJPEG 1=AVCC 2=size-only; flags bit0=desc bit1=keyframe.
@@ -164,7 +166,12 @@ function resolveAddon(): string {
 
 let addon: NativeAddon | undefined;
 function load(): NativeAddon {
-  if (!addon) addon = require(resolveAddon()) as NativeAddon;
+  if (!addon) {
+    addon = require(resolveAddon()) as NativeAddon;
+    // The addon cannot read the set from the environment: under Bun a
+    // `process.env` write never reaches it.
+    addon.setDeviceSet(resolveDeviceSet() ?? null);
+  }
   return addon;
 }
 

package/src/simctl.ts

@@ -1,3 +1,84 @@
+import { realpathSync, statSync } from "fs";
+import { homedir } from "os";
+import { join, resolve } from "path";
+
+// The CoreSimulator device set to use instead of Xcode's default, as
+// `simctl --set` takes it. Tools that keep simulators in a set of their own
+// (device pools, CI runners, Xcode Previews) put them where `simctl list` and
+// Simulator.app never look. The variable is how the set reaches what the CLI
+// starts (a --detach child, host-action subprocesses) and a dev server that
+// embeds the middleware without the CLI.
+const DEVICE_SET_ENV = "SERVE_SIM_DEVICE_SET";
+const DEFAULT_DEVICE_SET = join(homedir(), "Library/Developer/CoreSimulator/Devices");
+
+let resolved: { path: string | undefined } | undefined;
+
+/**
+ * The device set this process targets: an absolute directory, or undefined
+ * for Xcode's default set. The first call settles it from `flag` (the CLI's
+ * `--device-set`), or else from SERVE_SIM_DEVICE_SET, and writes the result
+ * back to that variable for the processes serve-sim starts. Every later call
+ * returns the same value, so simctl, the native addon and the state file
+ * never disagree. Throws when the value is not an existing directory, or
+ * when a flag arrives after the set was settled.
+ */
+export function resolveDeviceSet(flag?: string): string | undefined {
+  if (resolved !== undefined) {
+    if (flag !== undefined) throw new Error("--device-set arrived after the device set was settled");
+    return resolved.path;
+  }
+  const fromEnv = process.env[DEVICE_SET_ENV]?.trim();
+  let path: string | undefined;
+  if (flag !== undefined) path = existingDirectory(flag, "--device-set");
+  else if (fromEnv) path = existingDirectory(fromEnv, DEVICE_SET_ENV);
+  resolved = { path };
+  if (path === undefined) delete process.env[DEVICE_SET_ENV];
+  else process.env[DEVICE_SET_ENV] = path;
+  return path;
+}
+
+function existingDirectory(value: string, source: string): string {
+  const trimmed = value.trim();
+  const expanded = trimmed === "~" || trimmed.startsWith("~/") ? join(homedir(), trimmed.slice(1)) : trimmed;
+  const path = resolve(expanded);
+  let isDirectory = false;
+  try {
+    isDirectory = statSync(path).isDirectory();
+  } catch {}
+  if (trimmed === "" || !isDirectory) {
+    throw new Error(`${source}: invalid device set '${value}': expected an existing directory (a simctl --set path).`);
+  }
+  return path;
+}
+
+/**
+ * Whether two device-set paths (undefined: Xcode's default set) name one
+ * set, symlinks resolved, so `/tmp/set` and `/private/tmp/set` match, and
+ * so does Xcode's default folder named explicitly.
+ */
+export function sameDeviceSet(a: string | undefined, b: string | undefined): boolean {
+  if (a === b) return true;
+  const real = (path: string) => {
+    try {
+      return realpathSync(path);
+    } catch {
+      return resolve(path);
+    }
+  };
+  return real(a ?? DEFAULT_DEVICE_SET) === real(b ?? DEFAULT_DEVICE_SET);
+}
+
+/** `xcrun` arguments that run `simctl <args>` against the device set. */
+export function simctlArguments(args: readonly string[]): string[] {
+  const set = resolveDeviceSet();
+  return set === undefined ? ["simctl", ...args] : ["simctl", "--set", set, ...args];
+}
+
+/** The directory holding one folder per simulator UDID in the device set. */
+export function simulatorDevicesDir(): string {
+  return resolveDeviceSet() ?? DEFAULT_DEVICE_SET;
+}
+
 /**
  * Arguments for monitoring a boot that serve-sim has already requested.
  *
@@ -6,6 +87,6 @@
  * even though the device is already Booted. This form only monitors the boot
  * transition that serve-sim requested.
  */
-export function simctlBootStatusArguments(udid: string): [string, string, string] {
-  return ["simctl", "bootstatus", udid];
+export function simctlBootStatusArguments(udid: string): string[] {
+  return simctlArguments(["bootstatus", udid]);
 }

package/src/state.ts

@@ -1,5 +1,6 @@
 import { tmpdir } from "os";
 import { join } from "path";
+import { resolveDeviceSet } from "./simctl";
 import {
   chmodSync,
   closeSync,
@@ -46,6 +47,12 @@ export interface ServeSimDeviceState {
    * opt-in differs from the one requested. Absent means off.
    */
   allowExec?: boolean;
+  /**
+   * The `--device-set` the server's simulator lives in. Absent means Xcode's
+   * default set. Previews in different sets share this state folder, and
+   * each can tell only whether its own set's simulators are booted.
+   */
+  deviceSet?: string;
 }
 
 /**
@@ -65,7 +72,9 @@ export function inProcessServeSimState(
   // leading slash (e.g. "foo") still yields well-formed `…:port/foo/helper/…`.
   const trimmed = base.replace(/^\/+/, "").replace(/\/+$/, "");
   const prefix = trimmed === "" ? "" : `/${trimmed}`;
+  const deviceSet = resolveDeviceSet();
   return {
+    ...(deviceSet !== undefined ? { deviceSet } : {}),
     pid: process.pid,
     port,
     device: udid,

package/src/ui-settings.ts

@@ -3,6 +3,7 @@ import { existsSync } from "fs";
 import { join, resolve } from "path";
 import { findBootedDevice, resolveDevice } from "./device";
 import { dirnameOf } from "./runtime";
+import { simctlArguments } from "./simctl";
 
 // Bun's bundler inlines a bare `__dirname` as the build machine's source
 // directory; shadow it with the runtime location so the published bundle
@@ -199,14 +200,14 @@ function run(file: string, args: string[]): Promise<string> {
 }
 
 function simctlUi(udid: string, subcommand: string, value?: string): Promise<string> {
-  const args = ["simctl", "ui", udid, subcommand];
+  const args = simctlArguments(["ui", udid, subcommand]);
   if (value !== undefined) args.push(value);
   return run("xcrun", args);
 }
 
 async function axRun(udid: string, ...args: string[]): Promise<string> {
   const tool = await axSettingsTool();
-  return run("xcrun", ["simctl", "spawn", udid, tool, ...args]);
+  return run("xcrun", simctlArguments(["spawn", udid, tool, ...args]));
 }
 
 function toToggle(simctlValue: string): string {