iOS physical devices through devicectl

Start with the driver in src/drivers/ios/index.ts and the planned src/drivers/ios/physical.ts, then the passthrough contract in src/core/driver.ts and the routing in src/daemon/dispatcher.ts. Depends on #428, #437, #438 and #439 being merged first, and on ADR 0022. Done when a physical iPhone can be enrolled, presence-checked, leased, exec'd through devicectl, and reclaimed, with simctl unchanged on simulators.

Part of #428.

Scope

After this PR, a real iPhone or iPad works end to end on a Mac worker. An operator enrolls it with simlock device add --platform ios <id>. An agent leases it, installs a build, and runs devicectl on it through device.exec. A release uninstalls the apps the agent added. A locked or unplugged iPhone becomes absent. Until now only the fake driver did this; the real iOS driver refused every physical call. This task fills the iOS driver's physical handler (ADR 0022 §5–§8), routes device.exec by the lease's device, and adds the phone lane for iOS.

In short

The iOS driver gains a physical handler that runs xcrun devicectl. It reads devices over USB only, uninstalls apps only on enrolled devices, and stops every call at a time limit. device.exec now hands the driver the lease's device, so devicectl is aimed at that device and simctl keeps serving simulators.

New terms:

• physical handler: the part of the iOS driver that serves physical: true devices with devicectl. Example: a release of 00008110-001A2B3C4D5E runs xcrun devicectl device info apps --device 00008110-001A2B3C4D5E, then one device uninstall app per added app.

• presence read: one devicectl list devices read plus one device info lockState read per enrolled iPhone listed on USB. Present means all of these:

  • the list has an entry whose udid is the enrolled UDID. When the UDID is listed more than once, the wired entry is the one read; two or more wired entries for it read not present, not-present;
  • its transportType is wired;
  • its reality is not simulated (a missing reality counts as physical);
  • its pairingState is paired;
  • the lock read succeeds and its passcodeRequired is false.

  Otherwise it is not present, with a reason: locked (the lock read says a passcode is needed), untrusted (listed wired but not paired), or not-present (everything else). Example: an iPhone on the desk with its screen locked reads not present, locked.
  devicectl also lists devices it saw before and cannot reach now, with their last transportType. So tunnelState is not read: devicectl opens a tunnel on demand, and an idle phone may list disconnected. The lock read decides instead: it fails for a phone that is not connected. Field names checked with xcrun devicectl list devices --json-output <file> (642.16). That run also showed: simulators list transportType sameMachine; a paired iPad over localNetwork has no reality and no developerModeStatus. Not checked locally, because no phone was on USB: the value wired, and that a lock read of an unplugged phone fails. The phone lane checks both.

• user app (iOS): an app devicectl device info apps lists with its default filter, which lists developer-installed apps only (Xcode or devicectl installs) and no system app. Example: com.example.MyApp installed by xcodebuild; never com.apple.mobilesafari.

• JSON read: every devicectl read Simlock runs for itself passes --json-output <path>. The path is a new file in <simlockHome>/devicectl/ (the driver creates it, mode 0700), one per read. Simlock reads the file back, then deletes it, also when the read fails or times out. devicectl's help says this JSON file is versioned and stable across releases, and its stdout is not. Example: xcrun devicectl list devices --json-output <temp>/devicectl-<id>.json.

• allowed list: the device … commands device.exec may run with devicectl, each with the options it may take. Any other command, and any argument before -- that is not on the command's list, is refused, "not allowed over exec". Example: device info apps runs; device reboot, list devices and device info apps --json-output /tmp/x are refused.

flowchart LR
  A["device add"] --> I["inspect over USB (new: devicectl)"]
  I --> R[ready]
  R --> L["lease --physical"]
  L --> X["device.exec devicectl (new: --device UDID added)"]
  X --> REL[release]
  REL --> C["reclaim: uninstall added apps (new: devicectl)"]
  C --> R
  W["watcher: presence read (new: devicectl)"] -.-> R

Before (the real iOS driver after #439; wording illustrative):

$ simlock device add --platform ios 00008110-001A2B3C4D5E
{"error":{"code":"DEVICE_NOT_ENROLLABLE","message":"this driver cannot read physical devices yet"}}

After:

$ simlock device add --platform ios D39C0F5B-3E40-5848-8E7E-85A32473C183
Enrolled iPhone 15 Pro (iOS 18.4) as 00008110-001A2B3C4D5E, 3 user apps recorded.

$ simlock device add --platform ios 00008030-0011223344556677
Refused: physical iOS devices need iOS 17 or later.

$ simlock status        # after the leased iPhone was locked for the grace period
Device dev_7: absent (locked), physical phone

$ curl -X POST .../v1/leases/lse_9/exec -d '{"tool":"devicectl","args":["device","install","app","/builds/MyApp.app"]}'
event: exit  data: {"exitCode":0}          # ran: xcrun devicectl device install app --device 00008110-… /builds/MyApp.app

$ curl -X POST .../v1/leases/lse_9/exec -d '{"tool":"devicectl","args":["--json-output","/tmp/x","list","devices"]}'
422 {"error":{"code":"PASSTHROUGH_REFUSED", ...}}

Input (real iOS driver)	After #439	After
device add of an iPhone on USB, trusted, Developer Mode on, unlocked	refused: no physical support	enrolled under its UDID, user apps recorded
device add with its CoreDevice ID, ECID or serial number	refused	enrolled under its UDID
device add of an ID listed twice, once on USB and once over Wi-Fi	refused	read from the USB entry
device add of an iPhone on iOS 16	refused	refused: needs iOS 17 or later
device add of an Apple TV, Watch, Vision device or Mac	refused	refused: not supported
device add of a simulator's UDID	refused	refused: not a physical device
device add of an iPhone seen only over Wi-Fi	refused	refused: connect it by USB
device add of an iPhone not paired	refused	refused: not trusted
device add with Developer Mode off	refused	refused: Developer Mode is off
device add of a locked iPhone	refused	refused: locked, unlock it and try again
enrolled iPhone locked, untrusted, or unplugged for the grace period	stays ready (no real presence read)	absent (locked), absent (untrusted), absent (not-present)
device add of an ID devicectl does not list	refused	refused: not connected
device add while a devicectl read fails, times out, or lacks a field, or of an ID that matches two devices on USB	refused	refused: could not read the device, naming the read (unreadable)
release of a physical iOS lease	fake driver only	apps not on the enrollment list uninstalled; missing listed apps reported
device.exec devicectl device install app <path> on a physical lease	UNKNOWN_PASSTHROUGH_TOOL	runs xcrun devicectl device install app --device <UDID> <path>
device.exec devicectl device process launch <bundle> -- -AppleLanguages (en) on a physical lease	UNKNOWN_PASSTHROUGH_TOOL	runs; the arguments after -- reach the app unchecked
device.exec devicectl device reboot, list devices, or any command not on the allowed list	UNKNOWN_PASSTHROUGH_TOOL	PASSTHROUGH_REFUSED: not allowed over exec
device.exec devicectl device install app <path> --json-output <file>, or any option not on the command's list before --	UNKNOWN_PASSTHROUGH_TOOL	PASSTHROUGH_REFUSED: not allowed over exec
device.exec devicectl on a simulator lease	UNKNOWN_PASSTHROUGH_TOOL	PASSTHROUGH_REFUSED
device.exec simctl on a physical lease	runs simctl on the device set	PASSTHROUGH_REFUSED
device.exec simctl on a simulator lease	runs	unchanged
driver.passthrough (local simlock simctl)	runs	unchanged
driver.passthrough with tool devicectl (no lease)	UNKNOWN_PASSTHROUGH_TOOL	PASSTHROUGH_REFUSED: run xcrun devicectl directly

If this goes wrong, an operator would see a release that leaves an agent's app on the phone, a system or pre-enrolled app gone, a phone that never leaves absent, or a devicectl command run on the wrong device.

Technical spec

Modules touched

flowchart LR
  DSP["daemon/dispatcher *"] --> CAT["core/driver-catalog *"]
  SRV["daemon/server *"] --> CAT
  MAIN["daemon/main *"] --> IOS
  CAT --> IOS["drivers/ios *<br/>simulator + physical handler"]
  CAT --> AND["drivers/android * (signature only)"]
  LEAS["leasing: enroll, reclaim, watcher (unchanged)"] --> IOS
  IOS --> PR["ports: ProcessRunner, Clock, Filesystem"]
  PR --> DC["xcrun devicectl"]

* marks a changed module.

• src/drivers/ios/index.ts (or a new src/drivers/ios/physical.ts the driver delegates to; index.ts stays the module's surface):

  • Routing. Every shared method branches on device.physical. The virtual branch is today's code, unchanged.

  • inspectPhysical(id). One list devices read. It matches id against each entry's identifier (CoreDevice ID), udid, ecid and serialNumber:

    • identifier, udid and serialNumber match as strings, ignoring letter case;
    • ecid is a JSON number. It matches id written as decimal digits, or as 0x and hex digits (any case). It is compared as an exact integer, read from the raw JSON text, so no digit is lost above 2^53;
    • a name or DNS name is not an ID and does not match (safety rule 8).

    When id matches more than one entry, the wired entry is the one checked. Two or more wired matches are refused unreadable, "matches more than one device", and no lock read runs. When none of the matches is wired, the first match in devicectl's list order is the one checked.

    It then refuses, in this order, and stops at the first that applies:

    • no match: not connected (not-connected);
    • transportType is sameMachine, or reality is simulated: not a physical device (virtual-device);
    • transportType is not wired: connect it by USB (network-only);
    • platform is not iOS, or deviceType is not iPhone or iPad: not supported (unsupported-kind);
    • OS major below 17, or isMobileDeviceOnly true: needs iOS 17 or later (os-too-old). A missing isMobileDeviceOnly counts as false;
    • pairingState is not paired: not trusted (untrusted);
    • developerModeStatus is not enabled: Developer Mode is off (developer-mode-off);
    • the lock read says a passcode is needed: "locked: unlock it and try again" (locked). The lock read runs only when every check above passed.

    A field is required only from the wired step on. Before that step, a missing field refuses nothing: a missing reality is not simulated, and a missing transportType is not sameMachine. From that step on, the matched entry needs transportType, udid, platform, deviceType, osVersionNumber and pairingState, and developerModeStatus once the earlier checks pass. A missing one, or one whose JSON type is not the one read (a string, or a number for ecid), is refused unreadable. So the Wi-Fi iPad from the 642.16 run, with no reality and no developerModeStatus, is refused network-only. The lock read needs a boolean passcodeRequired.

    A read that fails, times out, exits non-zero, or leaves a JSON file that is missing or does not parse is refused unreadable (#437's reason, ADR 0022 §6), with a message naming the read (list devices, lockState or apps). The reason codes are #437's DEVICE_NOT_ENROLLABLE reasons. inspectPhysical never rejects for a failed read.

    Otherwise it reads user apps with device info apps --device <UDID>, default filter, no --include-* flag. It returns UDID, model (marketingName, else productType), OS version (osVersionNumber), class (iPad is tablet, else phone) and the bundle IDs. A failed apps read is refused unreadable. It never returns an empty app list in place of a failed read. It runs only read verbs: list devices, device info lockState, device info apps.

  • listPresentPhysical(enrolledIds). One list devices read. It matches entries by udid only; an entry with no udid is ignored. For a given UDID listed more than once, the wired entry is the one read; two or more wired entries answer that UDID not present, not-present, with no lock read. Then one lock read for each given UDID whose entry is wired, paired and not simulated. The lock reads run in parallel, so they take one read limit in all, not one each. It answers one entry per given UDID and none for any other device: present with its OS version (osVersionNumber), as the presence read above defines it; or not present with locked, untrusted or not-present. A list entry with no osVersionNumber answers its UDID not-present. A failed or timed-out list read answers every given UDID not present, not-present. A lock read that fails, times out, leaves no JSON, or has no boolean passcodeRequired answers that UDID not present, not-present. It never rejects for a failed read.

  • reclaim (physical). One apps read. Then, by #438's uninstallPlan, one device uninstall app --device <UDID> <bundleId> for each listed bundle ID not on enrolledApps, one at a time, stopping at the first failure. It returns strategy uninstall and missingApps: the enrolled bundle IDs the read no longer lists. A failed read or uninstall rejects, and the core's failed-reclaim path (#438, #439) decides absent or quarantined. It never uninstalls a bundle ID the read did not list.

  • estimate. For a physical reclaim it returns 90 000 ms at both clean levels: one 30 s read limit plus one 60 s uninstall limit. Two callers read it: a grant's estimatedReclaimMs (src/leasing/lease-acquisition-coordinator.ts:1128), and doctor's stall threshold (src/core/doctor.ts:908-909), which only applies to a reclaim no live claim holds.

  • passthroughTools. It becomes ["simctl", "devicectl"].

  • passthrough(tool, device, args, context) (async, below):

    • simctl with no device or a virtual device: today's command and refusals, unchanged.
    • simctl with a physical device: refused.
    • devicectl with a virtual device: refused.
    • devicectl with no device (driver.passthrough): refused; the message says to run xcrun devicectl directly.
    • devicectl with a physical device: xcrun devicectl <args>, with no env entries of its own. The checks below run before anything is spawned. When no -d, --device or --device=… appears before the first --, it inserts --device <UDID> right after the command's three words. A -d after -- belongs to the app and does not count. A caller's own --device is left as it is: naming another device is not stopped (ADR 0022 §5).

  • devicectl allowed list (device.exec, ADR 0022 §5, safety rule 10). The check is structural. It reads every argument before the first --. The arguments after the first -- pass unchecked: devicectl reads them as positional arguments, never as its own options (checked with 642.16 and a dummy device: device info details --device <id> -- --json-output <path> exits 64 and writes no file). devicectl reads its own options anywhere before --, also after a positional argument, so the check does too.

    1. Refused anywhere before the first --, also as another option's value: -j, --json-output, -l, --log-output, --destination, --file and --filter, each alone or as --flag=…, and any single-dash cluster that holds j or l (-vj). The first six name a path on the host. devicectl evaluates a --filter predicate on the host.
    2. args[0..2] must be one of these nine commands, exactly. So any global option before the command is refused, and so are list …, manage … and diagnose.
    3. After the command, each argument before the first -- must be one of: an option on the command's list below; the value of the option just before it, when that option takes one (--option value, or --option=value for a long option); or one of the command's positional arguments, up to its count. Anything else is refused. That covers an unknown option, a short-option cluster (-vq, -qd <id>), a short option with its value attached (-d<id>; devicectl 642.16 does not accept that form either), and a positional argument past the count.

    The nine commands, their positional arguments, and their options, from xcrun devicectl <command> --help (642.16). Every command also takes the common options: with a value, -d/--device and -t/--timeout; without, -v/--verbose, -q/--quiet, --omit-deprecated-fields-in-json, -h/--help and --version.

    Command	Positional	Options with a value	Options without a value
    device install app	<path>, a path on the worker by design: "install only a build already on the worker"	--columns	--hide-default-columns, --hide-headers
    device uninstall app	<bundle-identifier>
    device process launch	<bundle-identifier-or-path>; the app's own arguments go after --	-u/--user, -e/--environment-variables, --working-directory, --arch, --payload-url, --display, --launch-persistent-identifier	--start-stopped, --activate, --no-activate, --terminate-existing, --console
    device process terminate	none	-p/--pid	--kill
    device process signal	none	-p/--pid, -s/--signal
    device info apps	none	--bundle-id, -s/--search, --sort-by, --columns	--include-app-clips, --no-include-app-clips, --include-removable-apps, --no-include-removable-apps, --include-default-apps, --no-include-default-apps, --include-all-apps, --require-container-access, --include-app-group-identifiers, --include-container-paths, --hide-default-columns, --hide-headers
    device info lockState	none
    device info details	none
    device info processes	none	-s/--search, --sort-by, --columns	--hide-default-columns, --hide-headers

    Anything else is refused with PASSTHROUGH_REFUSED and the message "not allowed over exec: is not on the reviewed list" (or names the argument that is not). Each listed command takes --device. The list was built by walking xcrun devicectl <path> --help for devicectl 642.16 (Xcode 27.0): 80 leaves, 70 of them under device. Not on the list, among others: the four device … leaves that take no --device (device pairings pair, device pairings set-active, device pairings unpair, device profile validate), every leaf with a host-path flag (device capture screenshot and screen-record --destination, device sysdiagnose --destination, device pasteboard copy --file, device copy to|from), the host-pasteboard leaves (device pasteboard transfer to|from, device pasteboard sync-with-host), and the leaves that change the device beyond its apps (device reboot, device rename, device settings …, device profile install|remove).

  • Time limits. Every devicectl call goes through #invokeXcrun with its own limit: 30 s for a read, 60 s for an uninstall. A read past its limit counts as not present. An uninstall past its limit is a reclaim failure. No lock or queue is shared with the simctl calls.

  • JSON. Every devicectl read passes --json-output <path>, a new file in <simlockHome>/devicectl/ (the driver creates it, mode 0700), one per read, so two lock reads in parallel never share a file. After the call ends, the driver reads the file through its Filesystem port and deletes it. It deletes it also after a non-zero exit or a timeout. A missing file, a file that does not parse as JSON, a non-zero exit, or a field shape that does not parse is a failed read. The parser reads result.devices[]. It reads each field from its deprecated key, and from its properties key only when the deprecated key is absent. devicectl 642.16 still writes both:

    Field	Deprecated key	Else
    udid, reality, platform, deviceType, marketingName, productType, ecid, serialNumber	hardwareProperties.<field>	properties.hardware.<field>
    osVersionNumber	deviceProperties.osVersionNumber	properties.software.osVersionNumber
    developerModeStatus	deviceProperties.developerModeStatus	properties.state.developerModeStatus
    transportType, pairingState	connectionProperties.<field>	properties.connection.<field>
    isMobileDeviceOnly	connectionProperties.isMobileDeviceOnly	none: absent counts as false

    identifier is read from the entry itself.

• src/core/driver.ts:376, 389: passthroughTool becomes passthroughTools: readonly string[]. passthrough takes the tool and the lease's device (VirtualDriverDevice | PhysicalDriverDevice | undefined), as in ADR 0022 §5. It also becomes async: it returns Promise<PassthroughCommand>, and a refusal rejects with PassthroughRefusedError. This task changes the signature, so it makes the change; #441 needs it, because its adb protocol check awaits a read before every physical adb command. DriverRejection.passthroughTool (:516) becomes passthroughTools.

• src/core/core-ports.ts:40 PassthroughResolver and src/core/driver-catalog.ts:74-84: they take the device, return a promise, and route to the driver whose passthroughTools holds the tool. The catalog awaits the driver's passthrough (:81). An unknown tool rejects with UnknownPassthroughToolError.

• src/daemon/dispatcher.ts:

  • #driverPassthrough (:514-519, the call at :518) passes no device and returns the promise. Its Handler type already allows one (:198), and runDispatch awaits it (src/daemon/dispatch.ts:316).
  • #deviceExec (:539-566, the call at :555) finds the lease's device record and passes it, converted with #438's exported toDriverDevice (architecture rule 10). It awaits the command before it spawns anything.

• Every other site of the rename and the new signature. The list is complete for grep -rn "passthroughTool\|passthrough(" src e2e on main at ac4cf1e:

  • src/leasing/testing.ts:149 (the test harness's resolver);
  • src/daemon/main.ts:1013 (iOS root rejection: simctl and devicectl), :1060 and :1078 (Android rejections: adb), :1091-1094 (rootRejection takes the list);
  • src/daemon/server.ts:869-871: matches a tool against passthroughTools;
  • src/drivers/ios/index.ts:1522, 1532, 1567, 1595, 1604;
  • src/drivers/android/index.ts:642, 650, 667, 673, 682, 690: passthroughTools: ["adb"] and the new async signature. The device argument is ignored until #441. No real Android physical device can be enrolled before #441;
  • src/core/fake-driver.ts:112, 177, 209, 549, 552 and e2e/fake-driver/fake-driver.ts:199, 215, 521, 528, 535-536: the same rename and the async signature; the fake keeps its behaviour;
  • tests that name either: src/drivers/ios/index.test.ts, src/drivers/android/index.test.ts, src/core/driver-catalog.test.ts, src/daemon/dispatcher.test.ts, src/daemon/server.test.ts, src/daemon/main.test.ts, src/daemon/gateway-fleet.e2e.test.ts. A refusal test moves from toThrow to rejects.toThrow.

• src/ports/process-runner.ts:605 ScriptedProcessExpectation: an optional callback that runs when the scripted call is spawned, given its args. The driver tests use it to write a devicectl read's JSON into the test's MemoryFilesystem at the path the --json-output argument names.

• src/drivers/ios/fixtures/:

  • devicectl-list-devices.json: hand-made in the shape of a real devicectl 642.16 run on a Mac with no phone on USB. That run listed simulators (sameMachine), a paired iPhone over localNetwork, and a paired iPad over localNetwork with no reality and no developerModeStatus; those entries are kept. A wired iPhone, a wired unpaired iPhone and a wired iPad are edited in. The phone lane confirms the wired shape.
  • devicectl-info-apps.json and devicectl-lock-state.json: hand-written. No real run made them, because no phone was on USB. They hold the keys this spec reads (result.apps[].bundleIdentifier, a boolean passcodeRequired), and the phone lane confirms them.

• Phone lane wiring (M5, ADR 0022 §11). Two tags:

  • physical: tests that need no person (enroll, lease, install, release, presence of a plugged-in unlocked phone). They run unattended when the env vars name a device;
  • physical-manual: tests that need a person (lock, unplug, replug). They run only when SIMLOCK_PHYSICAL_PERSON is 1, which only a person running them by hand sets. The hardware verifier never sets it, so it never runs them.

  Changes:

  • vitest.config.ts declares both tags;
  • package.json: test:e2e:slow adds --tags-filter='!physical && !physical-manual'. New test:e2e:physical runs only physical, and new test:e2e:physical-manual runs only physical-manual, both with --no-file-parallelism;
  • scripts/slow-e2e.sh --physical <files> runs test:e2e:physical, and --physical-manual <files> runs test:e2e:physical-manual, under the same machine lock. A person follows the manual run's prompts in its log.

• docs/internal/agent-rules/toolchain.md, slow lane: two rows in the machine-check table.

  • "Physical iOS": uname -s = Darwin, SIMLOCK_PHYSICAL_IOS set to the UDID of an iPhone on USB (trusted, Developer Mode on, unlocked, Auto-Lock Never), and SIMLOCK_PHYSICAL_IOS_APP set to a .app signed for it. It names scripts/slow-e2e.sh --physical e2e/slow-ios-physical.test.ts.
  • "Physical iOS, a person at the phone": the checks above, a passcode set on the phone (locking it then needs the passcode), and SIMLOCK_PHYSICAL_PERSON = 1. It names scripts/slow-e2e.sh --physical-manual e2e/slow-ios-physical-manual.test.ts.

  A paragraph says what the two tags mean, as above: physical runs unattended; physical-manual prompts a person in its log and waits up to 150 s for each step. Only a person running it by hand sets SIMLOCK_PHYSICAL_PERSON. The hardware verifier never does, so this machine check fails and it reports unavailable (needs a person), its existing outcome for a failed check (.claude/agents/hardware-verifier.md:20-21). No agent file changes.

• docs/CLI.md Prerequisites gets a "Physical iOS devices" list:

  • Xcode 15 or later (it ships devicectl); checked with Xcode 27 (devicectl 642.16);
  • iOS or iPadOS 17 or later;
  • the device trusts this Mac ("Trust This Computer");
  • Developer Mode on;
  • connected by USB;
  • unlocked: a device whose passcode is needed counts as not present, and status shows it absent (locked), so set Auto-Lock to Never or use no passcode.

  "Reaching a leased device" (#438 added the SIMLOCK_DEVICE_UDID row) gets the example xcrun devicectl device info apps --device "$SIMLOCK_DEVICE_UDID", and says a remote agent runs devicectl through device.exec over HTTP or the client: there is no simlock devicectl command.

One device.exec through a worker:

sequenceDiagram
  participant A as Agent (HTTP)
  participant D as Worker dispatcher
  participant C as DriverCatalog
  participant I as iOS driver
  participant X as xcrun devicectl
  A->>D: device.exec {leaseId, tool: devicectl, args}
  D->>D: lease -> device record (UNKNOWN_LEASE if none)
  D->>C: await passthrough(devicectl, device, args)
  C->>I: await passthrough(devicectl, device, args)
  alt refused (not on the allowed list, host-path option before --, virtual lease ...)
    I-->>A: PASSTHROUGH_REFUSED {tool: devicectl}, nothing spawned
  else allowed
    I-->>D: xcrun devicectl ... --device UDID
    D->>X: spawn (exec.timeoutMs)
    X-->>A: output chunks, then exit code
  end

One enrollment:

sequenceDiagram
  participant O as Operator CLI
  participant L as Daemon (enrollment, #437)
  participant I as iOS driver
  participant X as xcrun devicectl
  O->>L: device.add {platform: ios, id}
  L->>I: inspectPhysical(id)
  I->>X: list devices --json-output <temp file> (30 s)
  I->>X: device info lockState --device UDID --json-output <temp file> (30 s, only when every earlier check passed)
  alt not listed, simulated, Wi-Fi, unsupported, iOS < 17, untrusted, Developer Mode off, locked
    I-->>O: refused, with the reason
  else a read failed, timed out, or lacks a field; or two wired entries match
    I-->>O: refused unreadable, naming the read
  else ok
    I->>X: device info apps --device UDID --json-output <temp file> (30 s)
    I-->>L: UDID, model, OS, class, bundle IDs (apps read failed: refused unreadable)
    L-->>O: enrolled
  end

Contract and event changes

None. device.exec and driver.passthrough keep tool as an open string. PASSTHROUGH_REFUSED already carries tool. passthroughTools and the async passthrough signature are internal driver types, not contract shapes. Events (device.enrolled, device.reclaimed with uninstall and missingApps, device.absence-detected) were added by #437, #438 and #439. This task only fills their payloads from real reads.

Other code on the same state

• Apps on an enrolled iPhone. The writers are: reclaim (#438, src/core/reclaim-coordinator.ts); the quarantine retry (src/core/quarantine-coordinator.ts, which calls reclaim); enrollment's read (#437); the watcher's reads (#439); and a lease holder's device.exec. The first four hold the device's operation claim (src/core/device-operation-claims.ts), so they never overlap on one device. The watcher only reads, and never transitions a claimed device. A device.exec started before release is not claimed and can outlive its lease (KNOWN-PITFALLS "A device.exec command is authorized once"). An install it finishes after the reclaim's apps read survives until the next release. The straggler wins; this is accepted as it is for simulators.
• Tool routing. DriverCatalog.passthrough (driver-catalog.ts:74-84) is the one place a tool name picks a driver. DaemonServer#rejectionFor (server.ts:869-871) explains a missing tool from DriverRejection. Both move to passthroughTools in this PR, so no copy keeps the old single name.
• CLI wrappers. src/cli/index.ts:631-647 publishes simctl and adb only. It is unchanged: there is no simlock devicectl command. A local agent runs plain xcrun devicectl; a remote one uses device.exec over HTTP or the client. The gateway path is #442.
• Gateway. src/gateway/dispatcher.ts:505 forwards device.exec with the tool name unread. The worker resolves it, so nothing changes there in this PR (#442).
• Presence timing. One presence read takes at most 60 s: 30 s for the list, then 30 s for the parallel lock reads. The default health.probeIntervalMs is 30 s. #439's watcher arms its next tick only after the previous one settles; a grant's read (#438) can run beside it, and this driver allows concurrent reads.
• Simulator calls. #invokeSimctl and #invokeXcrun (src/drivers/ios/index.ts:1787-1834) share only the process runner and clock. A hung devicectl call holds no simctl call.
• JSON files. Each devicectl read writes its own new file and the driver deletes it. No other component reads or writes these files. A caller's device.exec can never name one: --json-output is refused there.

Rules in play

• safety.md rules 1, 7 and 8 as amended by ADR 0022 §12. The only destructive call is device uninstall app. It targets only a UDID from a PhysicalDriverDevice, and only for a bundle ID the fresh read listed and the enrollment list lacks. Lock reads run only for enrolled UDIDs.
• safety.md rule 10: device.exec arguments are claims. Only commands and options on the allowed list run, and the check runs before anything is spawned.
• architecture.md rules 2 and 3: every devicectl fact (verbs, JSON keys, the allowed list) stays in src/drivers/ios/. Rule 10: one tool-routing place and one record-to-DriverDevice function. Rule 11: every devicectl call is bounded. Rule 9: devicectl goes through the existing ProcessRunner port, and its JSON files through the Filesystem port.
• testing.md rules 1–4. A refusal test asserts that nothing was spawned, not only the error.
• toolchain.md: the slow lane and its two new rows.

Tests

Seam: IosSimctlDriver built with ScriptedProcessRunner, FakeClock and MemoryFilesystem, modelled on src/drivers/ios/index.test.ts. Each scripted devicectl read writes its JSON into the MemoryFilesystem at its --json-output path, through the new spawn callback. Core routing uses src/core/driver-catalog.test.ts, src/daemon/dispatcher.test.ts and src/daemon/main.test.ts (discoverIos). The phone lane is e2e/slow-ios-physical.test.ts and e2e/slow-ios-physical-manual.test.ts, modelled on e2e/slow-ios-smoke.test.ts and e2e/device-exec.test.ts. Lane wiring is a new unit test, src/test-lanes.test.ts, which reads package.json.

Driver, enrollment:

• inspectPhysical with a CoreDevice ID, an ECID or a serial number returns the device's UDID, and every later call names the UDID
• inspectPhysical matches a UDID, CoreDevice ID and serial number written in the other letter case, and an ECID written in decimal and as 0x hex
• inspectPhysical matches an ECID above 2^53 by its exact digits, and not an ECID one apart
• inspectPhysical with a device's name matches nothing and is refused as not connected
• inspectPhysical of an ID listed once over localNetwork and once wired reads the wired entry and enrolls it
• inspectPhysical of an ID that matches two wired entries is refused unreadable with "matches more than one device", and runs no lock read
• inspectPhysical of an ID that matches two entries, neither wired, answers the refusal of the first one in the list (a Wi-Fi entry before a sameMachine one gives network-only)
• inspectPhysical returns marketingName as model, osVersionNumber as OS version, tablet for an iPad and phone for an iPhone
• inspectPhysical falls back to productType when marketingName is absent
• inspectPhysical returns the bundle IDs device info apps lists, and the apps read passes no --include-* flag
• inspectPhysical refuses each case in the enrollment table above with its reason code: not connected not-connected, simulated virtual-device, sameMachine virtual-device, Wi-Fi only network-only, not supported (tvOS, watchOS, visionOS, macOS) unsupported-kind, below iOS 17 and isMobileDeviceOnly os-too-old, not paired untrusted, Developer Mode off developer-mode-off, locked locked with "locked: unlock it and try again"
• the first check in the order wins, for each pair of neighbours: a simulated entry over localNetwork is virtual-device; an Apple TV over Wi-Fi is network-only; a wired Apple TV on tvOS 16 is unsupported-kind; a wired, unpaired iPhone on iOS 16 is os-too-old; a wired, unpaired iPhone with Developer Mode off is untrusted; a wired iPhone with Developer Mode off that is locked is developer-mode-off
• inspectPhysical runs no lock read when an earlier check refuses
• inspectPhysical of the fixture's Wi-Fi iPad, which has no reality and no developerModeStatus, is refused network-only, not unreadable; an iPad over Wi-Fi on iOS 16 is network-only too
• inspectPhysical of an entry over Wi-Fi with no platform or no pairingState is refused network-only: no field is required before the wired step
• inspectPhysical of a physical entry with no transportType is refused unreadable
• inspectPhysical of a wired entry that lacks udid, platform, deviceType, osVersionNumber or pairingState, or that lacks developerModeStatus once the earlier checks pass, or whose lock read lacks a boolean passcodeRequired, is refused unreadable
• inspectPhysical of an entry with no isMobileDeviceOnly reads it as false
• inspectPhysical whose list read, lock read or apps read exits non-zero, leaves no file, leaves a file that is not JSON, or passes 30 s is refused unreadable with a message naming that read, returns no app list, and does not reject
• inspectPhysical runs only list devices, device info lockState and device info apps
• the parser reads the same device from the deprecated keys and from properties alone, field by field as the table above maps them

Driver, presence:

• listPresentPhysical answers a paired, wired, unlocked given iPhone present, with its OS version
• listPresentPhysical answers a paired, wired, unlocked given iPhone with no reality present
• listPresentPhysical answers a locked iPhone not present locked, an unpaired one untrusted, and a Wi-Fi-only one and one not listed not-present
• listPresentPhysical gives no entry for, and never runs a lock read for, a physical device not among the UDIDs it was given
• listPresentPhysical ignores a list entry with no udid: it runs no lock read for it, and every given UDID reads as it would without that entry
• listPresentPhysical of a given UDID listed once over Wi-Fi and once wired reads the wired entry; one listed wired twice reads not-present with no lock read
• listPresentPhysical whose list read exits non-zero, leaves no file or a file that is not JSON, or passes 30 s answers every given UDID not present not-present, and does not reject
• one lock read past 30 s answers that device not present not-present and the others as read
• a lock read that exits non-zero, leaves no file or a file that is not JSON, or lacks a boolean passcodeRequired answers that device not present not-present
• two lock reads that each take 25 s (fake clock) both finish, and listPresentPhysical resolves before 30 s have passed after the list read: they run in parallel
• a list entry for a given UDID with no osVersionNumber answers that UDID not present not-present
• a wired, paired, physical entry with tunnelState disconnected and a lock read that answers passcodeRequired: false reads present; the same entry whose lock read fails reads not present not-present

Driver, reclaim:

• reclaim of a physical device uninstalls each listed bundle ID missing from enrolledApps, with --device <UDID>, and returns strategy uninstall
• reclaim uninstalls nothing on the enrollment list, and nothing the apps read did not list
• reclaim reports enrolled bundle IDs the read no longer lists as missingApps, and installs nothing
• reclaim whose apps read fails rejects and uninstalls nothing
• reclaim whose uninstall exits non-zero, or passes 60 s, rejects and runs no further uninstall
• estimate of a physical reclaim is 90 000 ms at both clean levels; a virtual reclaim's estimate is unchanged

Driver, files and limits:

• every devicectl read passes --json-output <path> naming a new file in <simlockHome>/devicectl/ (the driver creates it, mode 0700), and the driver reads that file and then deletes it
• the file is deleted also after a read that exits non-zero or passes its limit
• two lock reads in parallel name two different files
• a read whose file holds a field of the wrong JSON type (passcodeRequired as a string, udid as a number) is a failed read
• a devicectl read that hangs does not delay a simctl call made at the same time

Driver, passthrough and environment:

• passthroughTools is simctl and devicectl
• passthrough is async: it resolves the command, and every refusal rejects with PassthroughRefusedError
• devicectl device install app <path> on a physical device inserts --device <UDID> right after app, and returns no env entries
• devicectl device process launch <bundle> --console inserts --device <UDID> before the bundle ID
• devicectl args that carry --device, -d or --device= before -- are passed as given
• devicectl device process launch <bundle> -- -d x inserts --device <UDID>: a -d after -- does not count
• each of the nine allowed commands runs, with --device <UDID> inserted
• each option in the table runs on its command: an option with a value as -o value or --option value, a long one also as --option=value (device process signal --pid 12 --signal SIGTERM, device process launch -e '{"A":"1"}' <bundle>), and each option without a value
• device process launch <bundle> -- -AppleLanguages (en) runs with the arguments after -- unchanged; device process launch <bundle> -AppleLanguages (en) is refused
• devicectl with a global option before the command (-v, -q, -t 5, --timeout 5, -j -, --json-output -, -l x, --omit-deprecated-fields-in-json) is refused
• list devices, manage pair, diagnose, device reboot, device copy from, device capture screenshot, device pasteboard copy, device pasteboard sync-with-host, device pairings pair and device profile validate are refused "not allowed over exec", with and without --device
• --json-output, --json-output=x, -j, -vj, --log-output, -l, --destination, --file and --filter are refused right after the command, after the positional argument (device install app <path> --json-output x), and as another option's value (device info apps --search --json-output x)
• --json-output x after the first -- (device process launch <bundle> -- --json-output x) runs: it is the app's argument
• device info apps --filter <predicate> and device info processes --filter <predicate> are refused
• an unknown option (--foo), a short-option cluster (-vq, -qd <id>), an attached short value (-d<id>), and a second positional argument before -- (device uninstall app a b, device process launch <bundle> extra) are refused
• an option that is on another command's list but not on this one's (device info details --kill) is refused
• every refusal rejects with PassthroughRefusedError naming devicectl, and the process runner starts nothing
• devicectl on a virtual device is refused, and with no device it is refused with a message naming xcrun devicectl
• simctl on a physical device is refused
• simctl with no device and with a virtual device gives today's command and today's refusals
• adb passthrough on the Android driver gives today's command with and without a device, now awaited
• src/core/fake-driver.ts and e2e/fake-driver resolve today's passthrough command and reject today's refusals

Core routing:

• (catalog) passthrough("devicectl", …) resolves the command of the driver whose passthroughTools holds it; an unknown tool rejects with UnknownPassthroughToolError
• (server) a devicectl call when the iOS driver was rejected at startup names the iOS rejection's summary
• (main) discoverIos with a rejected root returns a rejection whose passthroughTools are simctl and devicectl; an Android rejection's are adb
• (dispatcher) device.exec passes the lease's device to passthrough; driver.passthrough passes none
• (dispatcher) a passthrough that rejects with PassthroughRefusedError answers PASSTHROUGH_REFUSED on driver.passthrough and on device.exec, and device.exec spawns nothing
• (dispatcher) device.exec with an unknown lease is UNKNOWN_LEASE and resolves no command, as today

Phone lane. Both files are skipped when SIMLOCK_PHYSICAL_IOS or SIMLOCK_PHYSICAL_IOS_APP is unset, and the manual file also when SIMLOCK_PHYSICAL_PERSON is not 1. The skipped title names the missing variable. Health is set to probeIntervalMs 2000 and stableObservations 2. The lane confirms the devicectl facts the driver tests assume, which were read from devicectl 642.16 help and one list devices run with no phone on USB: a wired phone reads transportType: wired; device info lockState writes a passcodeRequired boolean to its JSON file; device info apps writes result.apps[].bundleIdentifier; --device inserted after the command works for process launch with app arguments after --.

e2e/slow-ios-physical.test.ts (tags slow, ios, physical; no person needed):

• enrolling by the phone's CoreDevice ID shows the device in simlock list --devices under its UDID, marked physical
• the plugged-in, unlocked phone reads present: it stays ready across three probe intervals, and the test logs the tunnelState its list entry showed
• an app installed before enrollment is still installed after a lease and release
• after re-enrolling without that app, an install through device.exec devicectl device install app <APP> (no --device) exits 0, and after release the app is gone and the device is ready
• device.exec devicectl --json-output <path> list devices is refused and no file appears at <path>
• device.exec devicectl device process launch <bundle> -- -AppleLanguages (en) of the test app exits 0
• the grant's environment carries SIMLOCK_DEVICE_UDID equal to the phone's UDID
• the file ends with device remove and removes the test app

e2e/slow-ios-physical-manual.test.ts (tags slow, ios, physical-manual; a person follows prompts in the log, and the test waits up to 150 s for each):

• after the prompt "lock the phone", the device becomes absent with absentReason locked within 150 s, and once unlocked it is reclaimed back to ready
• after the prompt "unplug the phone" during a lease, the lease ends device-lost and the device becomes absent with absentReason not-present within 150 s (so a lock read of an unplugged phone fails), and once it is plugged in and unlocked it is ready again
• the file ends with device remove

Lane wiring (src/test-lanes.test.ts, reads package.json):

• test:e2e:slow's --tags-filter excludes physical and physical-manual, and test:e2e's excludes slow, which both phone files carry
• test:e2e:physical's --tags-filter selects physical and not physical-manual; test:e2e:physical-manual's selects physical-manual only; both pass --no-file-parallelism

Done when

• On a Mac with an iPhone on USB (trusted, Developer Mode on, Auto-Lock Never) and a .app signed for it, scripts/slow-e2e.sh --physical e2e/slow-ios-physical.test.ts passes, unattended. It proves: enroll by CoreDevice ID under the UDID; the plugged-in phone reads present; install through device.exec; release removes the app and keeps the pre-enrolled one. This needs real hardware.
• On the same Mac, with a passcode set on the phone and a person at it, SIMLOCK_PHYSICAL_PERSON=1 scripts/slow-e2e.sh --physical-manual e2e/slow-ios-physical-manual.test.ts passes: lock gives absent (locked); unplug gives device-lost then absent (not-present); return gives ready. This needs real hardware and a person. The hardware verifier reports it unavailable (needs a person), and the maintainer runs it.
• Both commands with SIMLOCK_PHYSICAL_IOS unset skip, and the skipped title names the variable.
• device.exec devicectl with a command not on the allowed list, a global option before the command, an option not on the command's list, or a host-path option anywhere before -- answers PASSTHROUGH_REFUSED and spawns nothing (driver tests).
• A devicectl read that fails, times out or lacks a field, or an ID that matches two wired devices, refuses device add as unreadable (driver tests).
• simctl on a physical lease and devicectl on a simulator lease answer PASSTHROUGH_REFUSED (driver tests). simlock simctl on a simulator works as before.
• passthrough is async on every driver, and driver.passthrough and device.exec still answer PASSTHROUGH_REFUSED for a refusal (driver and dispatcher tests).
• Each enrollment refusal in the table above has its reason code, and the first check in the order wins (driver tests).
• listPresentPhysical answers locked, untrusted and not-present as the presence read defines them, and every devicectl read's JSON file is deleted after the read, also after a failure or a timeout (driver tests).
• A devicectl read past 30 s counts as not present, and an uninstall past 60 s fails the reclaim (driver tests with the fake clock).
• test:e2e:slow and test:e2e in package.json select no physical and no physical-manual test (lane wiring unit test).
• toolchain.md has the "Physical iOS" and "Physical iOS, a person at the phone" rows, and docs/CLI.md Prerequisites lists the physical iOS requirements above.

Out of scope

• Android physical devices (#441).
• device.exec of devicectl through a gateway (#442). A simlock devicectl command: there is none.
• Recording or reclaiming App Store and TestFlight apps: never (feature decision; #438's docs say so).
• The physical lease environment (SIMLOCK_DEVICE_UDID): #438 set it.
• Unlocking a device, fixing trust or pairing, and enabling Developer Mode.
• A doctor finding for a missing devicectl.
• File upload to a worker.
• Adding commands to the allowed list beyond the nine above (a later change, when an agent needs one).

Depends on

• #435
• #439

Approval

• Approved for delivery

Written by an agent.