iOS: make the device set configurable so Xcode tools can target a leased simulator #962

Request: #946

Problem

Simlock's iOS simulators live in their own CoreSimulator device set. On Xcode 26 and older, no Xcode tool can target a simulator there by its UDID: xcodebuild -destination "platform=iOS Simulator,id=<udid>", react-native run-ios --udid, Expo run:ios, Detox and Maestro all read Xcode's own set. The only switch is a per-user Xcode default, which leaks into every xcodebuild run of that user and hides their own simulators while set. Xcode 27 takes the set as a per-command argument (-DVTSimulatorSetLocation=<set>), but only tools that pass extra xcodebuild arguments can use it; Expo run:ios cannot. The docs mention none of this. The only workaround they hint at is to build for generic/platform=iOS Simulator and install with simlock simctl install.

Android does not have this problem: adb, Gradle and the React Native CLI honour ANDROID_ADB_SERVER_PORT, which the lease exports.

Who it is for

Coding agents (agent-device first, then the React Native CLI, Expo, Detox and plain xcodebuild) that hold an iOS lease and need to build and run an app on that simulator. Also the operator who sets up the worker and chooses how much isolation to keep.

Outcome

• An operator can set drivers.ios.deviceSet to "default". A worker set that way keeps its simulators in Xcode's own set. Any Xcode tool then targets a leased simulator by its UDID, with no extra argument and no detour.
• With either setting, Simlock's own work (cleanup, the warm pool, nuke, doctor --purge-orphans, reclaim) acts only on simulators this Simlock created. A user's own simulators in Xcode's set, and another Simlock's, are never listed as Simlock's, wiped or deleted by it.
• An agent's simlock simctl still refuses the commands that change a device's lifecycle (create, erase, delete, shutdown all, runtime delete) under both settings. Under "default" it can list or install on any simulator in Xcode's set by UDID, as it can reach another agent's device today; scoping it to the lease is simlock simctl and simlock adb on a worker run only against the caller's lease, and fill the device in #948.
• simlock instructions tells an agent which build route its lease needs.
• The default stays "simlock", so nothing changes for a worker that does not opt in.
• A new docs page, "Build and run your app", says how to build onto a leased device for each setting and each platform, and what a careless xcrun simctl … all does to leased devices under "default".

How it works for the user

flowchart TD
  A[Operator sets drivers.ios.deviceSet] --> B{Value}
  B -->|simlock, or not set| C[Simulators in Simlock's own set, as today]
  B -->|default| D[Simulators in Xcode's set]
  B -->|anything else| E[iOS off; doctor says invalid-device-set]
  D --> F{Simulators left from the other setting?}
  C --> F
  F -->|yes| G[iOS off; doctor says device-set-changed and the steps]
  F -->|no| H[iOS starts]
  H --> I[Agent leases a simulator]
  I --> J[default: xcodebuild / run-ios --udid works directly]
  I --> K[simlock: Xcode 27 argument, or generic build + simctl install]

The operator's session, switching to default:

$ simlock config set drivers.ios.deviceSet default
Updated drivers.ios.deviceSet in /Users/alex/.simlock/config.json; takes effect on daemon restart.
$ simlock daemon stop && simlock daemon start
$ simlock doctor
...
Unavailable [ios] device-set-changed: Refusing the ios device set: Simlock's own set at /Users/alex/.simlock/devices/ios still holds 2 simulators (6F1D2A8C-…, 0B7E…). Set drivers.ios.deviceSet back to simlock, run `simlock nuke --delete-devices` and `simlock doctor --purge-orphans`, then switch again. Delete any that remain with `xcrun simctl --set /Users/alex/.simlock/devices/ios delete <udid>`.

After the steps, an agent's session:

$ simlock lease --platform ios --detach
...
$ UDID=6F1D2A8C-3B4E-4F7A-9C2D-8E5B1A7F3C90   # the device id the lease printed
$ xcodebuild -scheme MyApp -destination "platform=iOS Simulator,id=$UDID" build
** BUILD SUCCEEDED **

Today (and under simlock on Xcode 26) the same xcodebuild prints Unable to find a device matching the provided destination specifier.

Examples

What could go wrong

• A user's own simulator, or another Simlock's, is treated as this Simlock's and wiped or deleted. Unlikely: Simlock claims only devices carrying the mark it writes, with its own instance id, when it creates one. It would be the worst failure.
• Under "default", a user runs xcrun simctl shutdown all. Leased simulators stop; Simlock reboots them under their leases and agents lose running apps. One erased while stopped ends its lease. The docs say so.
• An operator flips the key with simulators still around and iOS stays off until they follow the steps doctor prints.

Words used

• device set: a folder of simulators that simctl and Xcode read, e.g. ~/Library/Developer/CoreSimulator/Devices (Xcode's set) or ~/.simlock/devices/ios (Simlock's own set).
• Xcode's set: the default device set every Xcode tool reads when given no other.
• durable mark: the small file Simlock writes into a simulator's folder when it creates the simulator. It will name the Simlock instance; under "default" it is what makes a simulator this Simlock's.
• instance: one Simlock data folder (SIMLOCK_HOME, ~/.simlock by default) with its own id. One OS user can run more than one, e.g. the slow-lane tests.
• generic build: xcodebuild -destination "generic/platform=iOS Simulator", a build for no particular simulator, installed afterwards.

Non-goals

• Flipping the default to "default". ADR 0048 §6 names the condition; a later issue does it.
• Moving or recreating simulators when the setting changes.
• Writing the per-user DVTSimulatorSetLocation default.
• Any change on Android or for physical devices.
• Lease-scoped simlock simctl (simlock simctl and simlock adb on a worker run only against the caller's lease, and fill the device in #948) and simlock run (simlock run holds a lease around one command, and a detached lease follows the agent process #944).

Completion conditions

• With drivers.ios.deviceSet: "default", a leased simulator is listed by a plain xcrun simctl list devices and agent-device drives it (snapshot), on a real Mac.
• With the key unset, every iOS behaviour is as today.
• Under "default", a simulator this Simlock did not create is never in its device list, so cleanup, the warm pool, nuke and doctor --purge-orphans never touch it.
• A bad value, or a switch with simulators left from the other setting, turns iOS off with a reason simlock doctor shows; Android keeps running. (Today a refused driver makes simlock doctor fail with an internal error; iOS simulators can live in Xcode's device set (drivers.ios.deviceSet) #968 fixes that.)
• The website has a "Build and run your app" page, the configuration, cleanup, device and how-it-works pages describe both settings, and simlock instructions gives the build route for each.

Open questions

Decisions

• ADR 0048 — An iOS worker may keep its simulators in Xcode's device set (PR docs(adr): 0048 an iOS worker may keep its simulators in Xcode's device set #964): the drivers.ios.deviceSet key, ownership by a durable mark naming the instance under "default", the refusal on a changed setting, no set in any environment under "default", the wrapper's refusals kept, and when to flip the default.

Shared values

none (one task)

Behaviours

Tasks

One task.

• iOS simulators can live in Xcode's device set (drivers.ios.deviceSet) #968 iOS simulators can live in Xcode's device set — an operator sets drivers.ios.deviceSet: "default" and Xcode tools target leased simulators directly. Risk: a user's own simulator, or another Simlock's, is wiped by Simlock, or iOS will not start after a switch.

Completion conditions: all delivered by #968.

Open work in the same area:

• simlock simctl and simlock adb on a worker run only against the caller's lease, and fill the device in #948 (lease-scoped simlock simctl/adb, request:new): changes the same passthrough and working-with-a-device.mdx. Not specced; no Depends on. Whichever lands second takes the other's refusal list.
• simlock run holds a lease around one command, and a detached lease follows the agent process #944 (simlock run, request:new): would read the lease environment; under "default" it carries no set. Not specced; no Depends on.
• device.exec fills in the lease's device and refuses another #958 (device.exec fills in the lease's device, task:ready, feature MCP: a run_on_device tool runs simctl, adb or devicectl against the session's lease #951, ADR 0047 PR docs(adr): 0047 device.exec fills in the lease's device, and refuses another (#951) #955): changes the iOS simctl passthrough in src/drivers/ios/index.ts, the same function iOS simulators can live in Xcode's device set (drivers.ios.deviceSet) #968 changes. iOS simulators can live in Xcode's device set (drivers.ios.deviceSet) #968 depends on device.exec fills in the lease's device and refuses another #958.
• Add simlock instructions: the rules an agent must follow, printable and served over MCP #147 / PR feat(cli): simlock instructions prints the rules an agent must follow #960 (simlock instructions, feature One command installs the agent rules where agent tools read them #157): adds the "iOS builds" section in src/instructions/index.ts, which says Simlock's simulators are never in Xcode's set, and pins its phrases in src/instructions/index.test.ts. iOS simulators can live in Xcode's device set (drivers.ios.deviceSet) #968 rewrites that section for both settings. iOS simulators can live in Xcode's device set (drivers.ios.deviceSet) #968 depends on Add simlock instructions: the rules an agent must follow, printable and served over MCP #147.
• A standalone worker serves agent-device on localhost by default #957 (standalone worker serves agent-device, feature agent-device on the same Mac works with no operator step #952): changes the shared daemon setup of e2e/slow-agent-device.test.ts and e2e/helpers/agent-device.ts, which iOS simulators can live in Xcode's device set (drivers.ios.deviceSet) #968's slow-lane case extends. iOS simulators can live in Xcode's device set (drivers.ios.deviceSet) #968 depends on A standalone worker serves agent-device on localhost by default #957.
• Per-platform lease limit per requester, on a worker and a gateway #966 (per-platform lease limit, another feature): also changes contract shapes and bumps the protocol. iOS simulators can live in Xcode's device set (drivers.ios.deviceSet) #968 depends on Per-platform lease limit per requester, on a worker and a gateway #966.
• PR fix(daemon): exec children get a minimal environment; docs say what an agent token can do #891 (minimal env for exec children): reads the lease environment. Under "default" there is less of it; no Depends on.

Written by an agent.