device.exec fills in the lease's device and refuses another #958

Part of #951.

Scope

After this PR, every device.exec caller (HTTP POST /v1/leases/{id}/exec, a gateway relay, the programmatic client's exec, and simlock --gateway simctl / simlock --gateway adb, F14) may leave the device out of a simctl command on a simulator lease, an adb command on an emulator lease, or a devicectl command on an iPhone lease: the worker's driver fills in the lease's device (ADR 0047 §1). A command that names a different device is refused before it runs (ADR 0047 §2). simlock simctl / simlock adb on a worker are unchanged (ADR 0047 §5).

In short

A remote agent sends {"tool":"simctl","args":["install","/builds/App.app"]} and the app lands on its own simulator; booted or another UDID is refused with the message in the feature's Shared values ("Other-device refusal").

flowchart LR
  C[device.exec caller] --> W[worker dispatcher]
  W --> D["driver passthrough (CHANGED: fills in / refuses)"]
  D --> P[process runner]

Before and after, HTTP on a simulator lease 6F1D2A8C-3B4E-4F7A-9C2D-8E5B1A7F3C90:

POST /v1/leases/$LEASE/exec {"tool":"simctl","args":["install","/builds/App.app"]}
before: event: exit {"exitCode":…}   (simctl usage error: no device)
after:  runs `xcrun simctl --set <root> install 6F1D2A8C-… /builds/App.app`

POST /v1/leases/$LEASE/exec {"tool":"simctl","args":["install","booted","/builds/App.app"]}
before: runs on whichever simulator simctl picks
after:  422 {"error":{"code":"PASSTHROUGH_REFUSED","tool":"simctl","message":"Refusing `simctl install booted /builds/App.app`: it names device booted, and this lease holds 6F1D2A8C-3B4E-4F7A-9C2D-8E5B1A7F3C90. Leave the device out; Simlock fills it in."}}

The full inputs table is the feature's Examples table. A user would notice a wrong build as a simctl or adb usage error, or a command landing on the wrong device.

Technical spec

Facts

Commit cac23e033.

Modules touched

Searches: rg "passthrough\(" src, rg "devicectlExecCommand" src, rg -i "name your device|booted|emulator's serial|passed to the tool unchanged|-s., .-t." website docs/internal src/contract, rg -i "PASSTHROUGH_REFUSED" website.

flowchart LR
  disp[daemon/dispatcher.ts] --> cat[core/driver-catalog.ts]
  cat --> ios["drivers/ios/index.ts (CHANGED)"]
  ios --> dctl["drivers/ios/devicectl-exec.ts (CHANGED)"]
  cat --> and["drivers/android/index.ts (CHANGED)"]

• src/drivers/ios/index.ts: simctl fill-in and check when a simulator device is passed; the device-verb list (ADR 0047 §1) as a constant. A UUID-shaped operand is 8-4-4-4-12 hex digits, any letter case. simctl on a lease whose context.platform is not ios is refused, as devicectl does (F16): Refusing `simctl`: it only serves an iOS simulator, and this lease is on the <platform> platform.
• src/drivers/ios/devicectl-exec.ts: refuse --device <v>, -d <v> or --device=<v> when <v> is not the lease's UDID (any letter case). The tests at devicectl-passthrough.test.ts:272-281 and the option cases at :200-221, :305-309 change: they use OTHER / x as the device (F15).
• src/drivers/android/index.ts: emulator -s fill-in and check when a virtual device with a non-empty address is passed; the no-device list (ADR 0047 §1) as a constant; a lone --version / --help gets nothing filled in. adb on a lease whose context.platform is not android is refused: Refusing `adb`: it only serves an Android device, and this lease is on the <platform> platform.
• Comments made false: src/contract/operations.ts:429-431, src/daemon/dispatcher.ts:706-711.
• Docs: docs/internal/flows/device-exec.md (Resolution per platform), src/drivers/ios/AGENTS.md, src/drivers/android/AGENTS.md (Passthrough), src/cli/AGENTS.md (gateway passthrough), and the website: using-devices/remote-agents.mdx ("Running commands with exec": the "Name your device" and "find the emulator's serial" bullets, the example at line 122), using-devices/programmatic-client.mdx:115, gateway/index.mdx:32 (install booted example), reference/cli.mdx:166 and :181 (refusals and allowed adb globals through a gateway), reference/errors.mdx:79 (PASSTHROUGH_REFUSED causes).

A request through a gateway is unchanged in shape: ADR 0047's sequence diagram.

Contract and event changes

None. device.exec input and output are unchanged; no protocol bump (ADR 0047 §4). No event.

Other code on the same state

The state is the argument list a driver returns. Searches: rg "passthrough\(" src (5 non-test hits, F1). driver.passthrough (dispatcher.ts:662) passes no device, so nothing is filled in or refused there; the existing tests in src/drivers/ios/index.test.ts:1664 and the Android passthrough tests that pass undefined keep proving it. leasing/testing.ts:164 forwards whatever a test passes.

Failure modes

The task adds no process or network call; it changes arguments before the existing spawn.

Writes no state.

Rules in play

• ADR 0047 §1–5: the table, the refusal, every caller, no contract change, local path unchanged.
• Drivers rule 6: "the driver owns the scoping flags and the refused verbs" — the fill-in lives in the drivers.
• Architecture rule 10, "A rule is enforced in exactly one place" — no copy in the dispatcher or a frontend.
• Testing rule 7, "Prove each claim once, at the cheapest level" — the driver passthrough is the seam; no e2e.

Tests

Seam: each driver's passthrough(tool, device, args, {hasTerminal:false, platform}), modelled on src/drivers/ios/index.test.ts:1664 and src/drivers/android/index.test.ts:3273 and src/drivers/ios/devicectl-passthrough.test.ts:223. src/drivers/android/index.test.ts:3285 stays as is (its device has an empty address, F12); the devicectl tests in F15 change.

• A device.exec caller sends a simctl device verb without a device and the command runs with the lease's UDID in place: install /b/App.app; launch --console com.x; launch -a arm64 com.x; spawn -s launchctl list → spawn -s <udid> launchctl list; io screenshot /tmp/s.png; own UDID upper or lower case → unchanged; list devices → unchanged; runtime list → unchanged.
• A device.exec caller's simctl command names another device and is refused with the shared message: another UUID; booted; launch --console booted com.x; and simctl on an Android lease is refused with the platform message.
• A device.exec caller sends an emulator adb command without a device and it runs with -s <serial> first: shell getprop; install app.apk; reverse --list; -s <own> → unchanged; devices, version, --version, forward --list, reconnect offline → unchanged; empty address → unchanged. (forward --list and reconnect offline added in delivery from ADR 0047 §1, pending the maintainer.)
• A device.exec caller's emulator adb command names another device and is refused with the shared message: -s emulator-5556; -e; -d; -t 3; -t3; -t <own serial> (added in delivery from ADR 0047 §2: -t is always refused, pending the maintainer); and adb on an iOS lease is refused with the platform message.
• A device.exec caller's devicectl command names another device and is refused with the shared message; its own is left alone: --device <other>; -d <other>; --device=<other>; --device <own> and --device <OWN in upper case> → unchanged.

Done when

• pnpm check is green (toolchain.md).
• The five Tests lines pass in pnpm test.
• The website pages in Modules touched no longer tell a caller to name the device, look up the emulator serial, or use booted, and say a command naming another device is refused.
• docs/internal/flows/device-exec.md, both driver manuals and the two comments in Modules touched describe the fill-in.

Out of scope

• simlock simctl / simlock adb on a worker (simlock simctl and simlock adb on a worker run only against the caller's lease, and fill the device in #948).
• Filling in for simctl verbs with two devices (pair, pbsync, clone) or an optional one (logverbose).
• Physical Android adb changes (F8 already fills in).

Depends on

• docs(adr): 0047 device.exec fills in the lease's device, and refuses another (#951) #955 (ADR 0047, bottom of the stack)
• fix(http): an Android lease over HTTP names its adb serial as address #953 (rewrites the remote-agents.mdx serial-lookup bullet this task removes)
• Add simlock instructions: the rules an agent must follow, printable and served over MCP #147 (exports the refusal constants in src/drivers/ios/index.ts:134-138 and src/drivers/android/index.ts:289, and changes #assertProxyable, which this task also changes)

Written by an agent.