iOS simulators can live in Xcode's device set (drivers.ios.deviceSet) #968

Part of #962.

Scope

An operator sets drivers.ios.deviceSet: "default" and restarts the daemon. Simlock then keeps its iOS simulators in Xcode's own device set, so xcodebuild, the React Native CLI, Detox and agent-device's XCTest runner target a leased simulator by its UDID. Simlock still claims only simulators whose mark names its own instance. A bad value, or a switch with simulators left from the other setting, turns iOS off with a reason doctor shows. Unset, everything is as today. The website gets a "Build and run your app" page, and simlock instructions names the build route for each setting. simlock doctor shows a refused driver's reason (today a refused driver makes doctor fail, F29). A stopped slow-lane run leaves no simulator in the maintainer's Xcode set.

One task, kept whole: every behaviour reads the one setting through the iOS driver, and the docs and instructions must change with it (documentation rule 9). About 12 Tests lines.

The "Build and run your app" page (using-devices/build-and-run.mdx) holds: under simlock, -DVTSimulatorSetLocation="$SIMLOCK_IOS_DEVICE_SET" on Xcode 27 or later, and on older Xcode or a tool that takes no extra xcodebuild arguments the generic build (-destination 'generic/platform=iOS Simulator') then simlock simctl install or agent-device install; under default, -destination "platform=iOS Simulator,id=<udid>" directly; on Android, ANDROID_ADB_SERVER_PORT from the grant and -s <serial> (or ANDROID_SERIAL); and a warning for default: xcrun simctl shutdown all stops leased simulators, Simlock reboots each under its lease and the holder loses running apps, and one erased while stopped ends its lease. How to switch: the key, a restart, and the device-set-changed steps. An operator who set drivers.ios.deviceRoot runs those steps with it still set, and removes it only when switching to "default"; the leftover check reads only the default own root, so a custom root's simulators are named by these steps, not by the check (decided in delivery, pending the maintainer).

In short

drivers.ios.deviceSet is "simlock" (default, today's behaviour) or "default" (Xcode's set, ~/Library/Developer/CoreSimulator/Devices). Under "default" no simctl call carries --set, the grant carries no SIMLOCK_IOS_DEVICE_SET, and a simulator is this Simlock's only when its durable mark names this instance's id. The check for simulators left from the other setting reads files only, at driver start: no simctl call is added to start-up.

flowchart LR
  C[config: drivers.ios.deviceSet] --> D["IosSimctlDriver.create (CHANGED)"]
  D -->|bad value / leftovers| R[iOS off: invalid-device-set / device-set-changed]
  D --> S["simctl argv: --set root, or none (CHANGED)"]
  D --> L["listManaged: all in set, or only this instance's marks (CHANGED)"]
  D --> E["grant env: SIMLOCK_IOS_DEVICE_SET, or none (CHANGED)"]
  E --> A[agent-device daemon: set, or Xcode's set]

Messages, word for word (<…> are the variable parts):

• Bad value: Refusing the ios device set: drivers.ios.deviceSet must be "simlock" or "default", but it is <JSON of the value>
• deviceRoot with "default": Refusing the ios device set: drivers.ios.deviceRoot names Simlock's own set, but drivers.ios.deviceSet is "default". Remove one of them.
• Leftovers under "default": Refusing the ios device set: Simlock's own set at <root> still holds <n> simulator(s) (<udid>, <udid>, …). 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 <root> delete <udid>`.
• Leftovers under "simlock": Refusing the ios device set: Xcode's device set still holds <n> of this Simlock's simulator(s) (<udid>, …). Set drivers.ios.deviceSet back to default, run `simlock nuke --delete-devices` and `simlock doctor --purge-orphans`, then switch again. Delete any that remain with `xcrun simctl delete <udid>`.

The operator's and agent's sessions are in #962, How it works for the user.

If this goes wrong, a user would notice Simlock wiping or deleting a simulator of their own or of another Simlock, or iOS staying off after they followed the printed steps.

Technical spec

Facts

At 3de46d1ff unless noted.

Values sent elsewhere:

• driver.root-rejected reason: invalid-device-set, device-set-changed. The bus types it as string (F13), so it passes; RootRejectionReason gains both.
• root in that payload: for invalid-device-set, the configured deviceSet value as a string (JSON.stringify for a non-string); for device-set-changed, the path of the set that holds the leftovers.
• The durable and erasable marks gain instanceId (F7, F11). A mark without it reads as no instance.

Modules touched

Searches: rg -n "deviceRoot|--set|SIMLOCK_IOS_DEVICE_SET|RootRejectionReason|#writeMark|#readMark|foreignDevices" src e2e website/src/content/docs docs/internal/EVENTS.md, and rg -n "device set" website/src/content/docs.

• src/drivers/ios/index.ts: read deviceSet; create validates it and runs the leftover check (files only); under "default": no --set in F1/F2/F3, deviceRoot and the device folders are <coreSimulatorRoot>/Devices (the sweep then looks only for entries named after Devices, which Simlock never makes there, F33), no ensureOwnedRoot, revalidateRoot resolves, listManaged filters by this instance's durable mark, #listedImages counts the rest as foreign and unused, findLegacy answers undefined (so a lost mark stays report-only, F32), a failed mark write in provision deletes the new simulator before rethrowing, no SIMLOCK_IOS_DEVICE_SET in the lease environment. Under both: the marks carry instanceId.
• src/drivers/ios/screen-capture.ts: when the driver passes no set, remove SIMLOCK_IOS_DEVICE_SET from the spread environment (F36).
• src/contract/schemas.ts: a driver-unavailable arm (platform, reason, detail) in doctorFindingSchema; src/contract/protocol.ts: this PR bumps the protocol by one (min and max).
• src/cli/commands/doctor.ts: writes Unavailable [<platform>] <reason>: <detail> to stderr for each driver-unavailable finding, beside the other finding lines; stdout unchanged.
• scripts/slow-e2e.sh: clean (and stop, which calls it) also deletes, with xcrun simctl delete <udid>, each simulator in ~/Library/Developer/CoreSimulator/Devices whose durable mark names the instanceId of a home under the lane folder, before removing the folder (F34, F35).
• src/core/device-root.ts: two new RootRejectionReasons.
• src/drivers/ios/AGENTS.md, src/drivers/AGENTS.md: the --set rule and ownership rule per setting; the new key.
• docs/internal/EVENTS.md: driver.root-rejected reasons.
• src/instructions/index.ts, src/instructions/index.test.ts (from Add simlock instructions: the rules an agent must follow, printable and served over MCP #147): the "iOS builds" section for both settings.
• src/agent-device/host/agent-device-supervisor.test.ts: the absent-key case (no code change, F16).
• e2e/slow-agent-device.test.ts (and its helper as A standalone worker serves agent-device on localhost by default #957 leaves it): a "default" daemon case.
• Website: reference/configuration.mdx (the key), worker/cleanup.mdx (roots, the two reasons, "never touches Xcode's set" per setting), using-devices/working-with-a-device.mdx (env table, simctl --set text, refusals, rules), introduction/how-it-works.mdx (Device), worker/runtimes-and-images.mdx (foreignDevices, F38), reference/cli.mdx (SIMLOCK_IOS_DEVICE_SET "iOS simulator under simlock"), new using-devices/build-and-run.mdx and its line in website/astro.config.mjs under "Using devices".

flowchart LR
  main[daemon/main.ts] --> ios["drivers/ios/index.ts (CHANGED)"]
  ios --> root["core/device-root.ts (CHANGED)"]
  ios --> cap["drivers/ios/screen-capture.ts (CHANGED)"]
  main --> sup[agent-device supervisor]
  ios -. lease env .-> sup
  instr["instructions/index.ts (CHANGED)"]
  disp[daemon/dispatcher.ts] --> doc[core doctor]
  disp --> schema["contract/schemas.ts (CHANGED)"]

Contract and event changes

doctorFindingSchema gains the driver-unavailable arm core already produces (F29): platform (a platform), reason (a string, at most 64 characters), detail (a string). This PR bumps the protocol by one. driver.root-rejected itself is not a contract shape (rg "root-rejected" src/contract finds nothing; the bus payload reason is a string, F13). driver.root-rejected gains reasons invalid-device-set and device-set-changed: docs/internal/EVENTS.md:153 lists them.

New config field drivers.ios.deviceSet: a string, exactly "simlock" or "default" (case-sensitive); absent means "simlock". Anything else gets invalid-device-set. New mark field instanceId: the instance's id string as written; read as absent when missing or not a non-empty string.

Other code on the same state

Searches: the set path (rg -n "deviceRoot|--set" src, 41 hits), the marks (rg -n "simlock-mark|readMark|provenanceDrift" src, 14 hits), the default set (rg -n "legacySimctl|CoreSimulator" src, 9 hits).

• Lease health monitor (src/leasing/lease-health-monitor.ts:176, :386-404): reads listManaged and the marks. Under "default" it sees only this instance's devices; drift reads as today, since durable/erasable tokens are unchanged.
• Doctor (src/core/doctor.ts:264, :1115-1124): orphans and provenance from listManaged; under "default" only this instance's devices, so another instance's or the user's never become orphans.
• Startup read (src/core/startup-read.ts:64): one listManaged per driver; same filter.
• findLegacy / destroyLegacy (F4): unscoped already; under "default" the same set. Only registry records reach them.
• Another Simlock instance under "default" in the same Xcode set: each lists only its own marks, so neither sees the other's devices. Its simctl writes touch only UDIDs its own registry names.
• device.exec fills in the lease's device and refuses another #958 (device.exec fill-in): changes the same passthrough method. T1 builds on it: the argv rule here applies to the argv device.exec fills in the lease's device and refuses another #958 builds.

Failure modes

State: the marks gain a field, written atomically as today. A restart between simctl create and the durable mark under "default" leaves one unlisted simlock-<id> simulator in Xcode's set; it is rare, no test, and ios/AGENTS.md Known gaps names it with its fix (xcrun simctl delete <udid>). No new shared state.

Rules in play

• ADR 0048 §1–5: the key, ownership by instance mark, refusal on a change, no set in any env, refusals kept.
• ADR 0001 §6, "Orphans are reported, never automatically destroyed": kept; only the orphan rule's input is filtered.
• Safety: "Simlock destroys only what its registry owns" (docs/internal/ARCHITECTURE.md:112-113): listManaged never offers a device this instance did not mark.
• Drivers rule 1, "A refusal (OwnedRootError) skips that platform only": both new refusals are OwnedRootErrors.
• Drivers rule 3, "drivers.<platform>.* are carried unread": core does not validate the key (F23).
• Documentation rule 9: every page above changes in this PR.
• Contract manual, "Every change to a contract shape bumps it by one in the same PR": the driver-unavailable arm bumps the protocol by one.

Tests

Seam: IosSimctlDriver (src/drivers/ios/index.test.ts, with ScriptedProcessRunner and MemoryFilesystem), plus agent-device-supervisor.test.ts, src/instructions/index.test.ts and the slow lane. Model on "refuses the platform, not the daemon, when the configured device root is not a path" (index.test.ts:1537) and "reports every device in its set, whatever the device is named" (:1335). Unset key = today: the leftover check reads only files, which the existing tests' MemoryFilesystem does not hold, so no existing test gets a new process call (F30), and the existing suite proves it unchanged.

• The driver given deviceSet runs every simctl call with or without --set: cases key unset and "simlock" (--set <root> on create, boot, erase, delete, list, runtime delete); "default" (none of them carries --set).
• An operator with a bad value or a conflicting deviceRoot gets OwnedRootError reason invalid-device-set with the message above: cases "Default", "", true, "default" with deviceRoot set.
• An operator who switches with leftovers gets device-set-changed: cases "default" with two devices in Simlock's set (refused, message names both UDIDs and xcrun simctl --set <root> delete <udid>); "default" with the set empty, and with no root folder (starts); "simlock" with a device in Xcode's set marked by this instance (refused, xcrun simctl delete <udid>); "simlock" with only unmarked and other-instance devices there (starts); an unreadable folder (unreadable); no case runs a process.
• A new or reclaimed simulator's marks name this instance: cases "simlock", "default"; both mark files carry instanceId. Under "default", a mark write that fails in provision runs simctl delete <udid> and rethrows.
• Under "default", listManaged reports only devices whose durable mark names this instance: cases this instance's mark (listed); erasable mark gone (listed, erasable undefined); no mark; a mark with no instanceId; another instance's mark; unmarked named simlock-1 (none of these four listed); findLegacy of a registered UDID answers undefined under "default".
• Under "default", listComponents foreignDevices and the removal's unused count take only devices this instance's mark does not name: three used devices on one runtime (this instance's, unmarked, another instance's) → foreignDevices 2; three never-used ones → unused count 2.
• A lease holder and the screen capture get the set only under "simlock": cases "simlock" ({ SIMLOCK_IOS_DEVICE_SET: <root> }, capture env has it); "default" ({}, capture env lacks it, also when the daemon's own environment had it); a physical device under both (SIMLOCK_DEVICE_UDID only).
• simlock simctl under "default" runs plain xcrun simctl and keeps its refusals: cases install <udid> app.app (argv ["simctl","install",…], no --set); erase <udid>, shutdown all, --set /tmp list (refused as today).
• The agent-device simulator daemon gets no AGENT_DEVICE_IOS_SIMULATOR_DEVICE_SET when the lease env lacks SIMLOCK_IOS_DEVICE_SET and iOS is on (extends "passes every key and value of the drivers' environment unchanged", agent-device-supervisor.test.ts:627).
• simlock instructions' "iOS builds" section names the route per grant: required phrases SIMLOCK_IOS_DEVICE_SET, -DVTSimulatorSetLocation, Xcode 27, generic/platform=iOS Simulator, xcodebuild -destination id=<udid>.
• An operator running simlock doctor while iOS is refused gets a driver-unavailable finding with its reason and detail, not INTERNAL (src/daemon/dispatcher.test.ts, extends "doctor.run forwards purgeOrphans…" at :915): cases invalid-device-set, device-set-changed; and simlock doctor writes Unavailable [ios] <reason>: <detail> on stderr with stdout unchanged (src/cli/index.test.ts, modelled on :2364).
• Slow lane, e2e/slow-agent-device.test.ts: under a daemon with drivers.ios.deviceSet: "default", an agent opens an iOS device, plain xcrun simctl list devices (no --set) lists its UDID, and snapshot answers; teardown runs simlock nuke --delete-devices --yes so no simulator is left in Xcode's set.
• The "Build and run your app" page's switch steps tell an operator with a custom drivers.ios.deviceRoot to keep it set while running simlock nuke --delete-devices and simlock doctor --purge-orphans, and to remove it only when switching to "default" (checked by the Done when docs review; decided in delivery, pending the maintainer).

Done when

• pnpm test:changed passes, with the Tests lines above.
• pnpm --dir website install && pnpm --dir website build && node website/scripts/check-openapi.mjs passes.
• In each page listed under Modules touched, every iOS hit of rg -n "simctl --set|device set|deviceRoot|SIMLOCK_IOS_DEVICE_SET|foreignDevices" website/src/content/docs says which setting it holds for; website/src/content/docs/docs/using-devices/build-and-run.mdx exists and is in the sidebar under "Using devices".
• docs/internal/EVENTS.md lists invalid-device-set and device-set-changed.
• Slow lane (real simulator): scripts/slow-e2e.sh e2e/slow-agent-device.test.ts passes the "default" case.
• Slow lane: start that case, run scripts/slow-e2e.sh stop while it runs, then xcrun simctl list devices shows no simulator whose durable mark names a lane instance.

Out of scope

• Flipping the default (ADR 0048 §6).
• Scoping simlock simctl to the lease's device (simlock simctl and simlock adb on a worker run only against the caller's lease, and fill the device in #948).
• Moving devices between sets.
• Android and physical devices.

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
• A standalone worker serves agent-device on localhost by default #957
• Per-platform lease limit per requester, on a worker and a gateway #966 (both bump the protocol)

Written by an agent.