@tapflowio/ios-agent 0.18.0 → 0.20.0

package/dist/IOSAgent.js

@@ -5,10 +5,32 @@ import { tmpdir } from 'os';
 import { randomUUID } from 'crypto';
 import { spawnSync } from 'child_process';
 import { WebSocket } from 'ws';
-import { createLogger, PlatformError, ValidationError } from '@tapflowio/agent-core';
+import { createLogger, PlatformError, ValidationError, bootAbandonMessage, BOOT_NO_SESSION_STATE } from '@tapflowio/agent-core';
 const logger = createLogger('ios-agent');
 // Typed so a typo cannot ship silently — the viewer gates the whole clipboard bridge on this.
-const AGENT_CAPABILITIES = ['clipboard'];
+// `full-reset` is honoured in `handleDeviceBoot`, which shuts a running device down before
+// `simctl erase` (which refuses anything but a shut-down device) and boots it again.
+// `network-control` claims what the other two claim: this agent has the code. Whether the injection
+// actually took is per device and per app, and `network:state.available` carries that — the split the
+// protocol documents. Added last, after the handler and the boot-time arming, because the string on
+// its own is what puts a control on screen.
+const AGENT_CAPABILITIES = ['clipboard', 'full-reset', 'network-control'];
+// Human prose for each reason. Not in `@tapflowio/protocol`: that package's main entry must stay
+// runtime-free so it erases under `import type` and never reaches the dashboard bundle — a lookup
+// table is a runtime value. The `reason` on the wire is the machine-readable half; this is only what
+// a human reads, and each agent owns its own wording.
+const INPUT_ERROR_MESSAGES = {
+    'not-booted': 'device not booted',
+    'channel-unavailable': 'input channel not ready',
+    'channel-starting': 'the input channel is still starting — retry in a moment',
+    'dispatch-failed': 'the device rejected the input',
+    unsupported: 'this input is not supported on the active connection to the device',
+    malformed: 'this input does not fit what the device is doing',
+    'no-gesture': 'no gesture is in progress to complete — start a new one',
+    // The relay is the only producer of this one — an agent has no way to know which socket asked. Present
+    // because the map is exhaustive, which is what makes a new reason a decision rather than an omission.
+    'not-session-owner': 'this input was addressed to a session the sender does not hold',
+};
 // Cross-platform button name → iOS device-chrome button name. Chrome uses
 // hyphens and "power" (not "lock"); MCP's vocabulary uses underscores. Names
 // not listed here (incl. the raw chrome names the dashboard sends) pass through.
@@ -18,7 +40,8 @@ export const IOS_BUTTON_ALIASES = {
     volume_down: 'volume-down',
 };
 import { createResourceSampler, registerStreamWs, disableNagle, createKeyframeAwareSender, pickMaxSize, createRateLimitedDropWarn, createThroughputSampler, createSleepBlocker, getMachineId, isLocalhostWss, DEFAULT_BACKPRESSURE_BYTES, writeEnvelopeHeader, rewriteLowLatencySpsInFrame, CODEC_JPEG, CODEC_H264, CODEC_AUDIO, sendAudioYieldingToVideo, } from '@tapflowio/agent-core/utils';
-import { SimctlWrapper, isDeviceMissingError, ClipboardTooLargeError } from './SimctlWrapper.js';
+import { SimctlWrapper, isDeviceMissingError, ClipboardTooLargeError, firstLine } from './SimctlWrapper.js';
+import { SimulatorNetwork } from './SimulatorNetwork.js';
 import { MAX_CLIPBOARD_BYTES, clipboardByteLength, CLIPBOARD_SENTINEL_PREFIX as SENTINEL_PREFIX, isClipboardSentinel as isSentinel, CLIPBOARD_COPY_DEADLINE_MS, CLIPBOARD_WRITE_DEADLINE_MS, CLIPBOARD_RESTORE_DEADLINE_MS, CLIPBOARD_POLL_MS, createKeyedSerialQueue, } from '@tapflowio/agent-core';
 import { ScreenCaptureStreamer } from './ScreenCaptureStreamer.js';
 import { AudioCaptureStreamer, readSimVolume, applyGain } from './AudioCaptureStreamer.js';
@@ -37,6 +60,7 @@ const AUDIO_POLL_MS = 1500;
 const EXTRACT_MAXBUFFER = 256 * 1024 * 1024; // 256 MB
 export class IOSAgent {
     simctl;
+    network;
     fps;
     intervalMs;
     reconnectDelays;
@@ -45,7 +69,55 @@ export class IOSAgent {
     token;
     handshakeTimeoutMs;
     ws = null;
+    /** Send on the control socket, if there is one. The `?.` is the point: 66 call sites relied on a send
+     *  being a no-op between reconnects, and this preserves that exactly.
+     *
+     *  Typed with `AgentControlOutbound`, which is why this exists — an agent's literal used to reach `ws.send`
+     *  with nothing checking it, and #489/#490 are what that cost. *
+   *  **The guard is not defensive tidying.** `ws.send` on anything other than OPEN takes the `sendAfterClose`
+   *  path, which adds the payload to a buffer nobody will flush and neither throws nor emits — so a reply
+   *  sent to a closing socket is indistinguishable from a delivered one at the call site. `reportResources`
+   *  has always checked; this did not, and the boot answers this file now owes a caller are exactly the
+   *  messages whose purpose is to end someone's wait.
+   *
+   *  The body is held character for character by `scripts/__tests__/agentSendTyped.test.mjs`, so the comment
+   *  lives out here: that check strips comments and matches the body exactly, having watched three earlier
+   *  drafts get bypassed by a renamed socket. */
+    sendMsg(msg) {
+        if (this.ws?.readyState !== WebSocket.OPEN)
+            return;
+        this.ws.send(JSON.stringify(msg));
+    }
+    /** Send on a socket the caller has already established. Takes the socket **as an argument** rather than
+     *  reading `this.ws`, and that is deliberate: the call sites that use it sit behind an entry guard
+     *  (`if (!this.ws) return`), and today deleting one of those guards is a compile error. Reading
+     *  `this.ws` here — or asserting it with `!` — would make the guard optional to the compiler and turn
+     *  its removal into a runtime `TypeError` instead. It also serves the `agent:register` send, which runs
+     *  inside `onopen` on a local socket. */
+    sendOn(ws, msg) {
+        ws.send(JSON.stringify(msg));
+    }
     deviceStates = new Map();
+    /**
+     * Devices **this agent booted**, by device id.
+     *
+     * Separate from `DeviceState.booted` because the two answer different questions and have different
+     * lifetimes. `booted` is liveness and is a cache: `initDeviceStates` rebuilds the whole map on
+     * every `agent:registered`, so it does not survive a reconnect. This does — the agent process is
+     * the same one across a reconnect — and it is what says *which* device is tapflow's when a
+     * developer has a second simulator of their own open.
+     *
+     * Without it, a reconnect on a two-simulator desk left the capability entry points asking simctl,
+     * getting two live devices, and refusing both. Written only where a boot succeeds; never by
+     * `ackInput`, which verifies liveness and proves nothing about ownership.
+     *
+     * **The `DeviceAgent.boot`/`shutdown` delegates do not touch this**, and that is deliberate: they
+     * hand a device id straight to simctl without opening a session, so a device they start is not one
+     * this agent is driving. Nothing in the repo calls either — the same position `stream()` is in — so
+     * wiring ownership through them would be a mechanism built for a caller that does not exist. A
+     * future caller that wants both should go through the boot handler rather than around it.
+     */
+    ownedDevices = new Set();
     // Last app launched per device (deviceId → bundleId). The XCUITest tree backend
     // queries by bundleId; kept outside DeviceState so it survives a relay reconnect
     // (which clears deviceStates) while the app keeps running in the simulator.
@@ -68,6 +140,22 @@ export class IOSAgent {
             throw new PlatformError('IOSAgent requires macOS (xcrun simctl is macOS-only)');
         }
         this.simctl = simctl ?? new SimctlWrapper();
+        // **Never the real filter under vitest.** Layer 1 is a system extension installed on the
+        // developer's Mac, and `arm()` runs on every boot — so a suite that booted a mock device was
+        // launching the notarized container app and rewriting the host's live filter configuration, once
+        // per boot test, on any machine where tapflow's own filter is installed. Nothing in the suite
+        // said so, because the class reports a missing container app rather than failing.
+        //
+        // Pointed at a path that does not exist rather than stubbed out: that is the same state a machine
+        // without the app is in, so the tests exercise the real class along its real reporting path
+        // (`filter-unavailable`) instead of a double that could drift from it. Same shape, and the same
+        // reason, as `sleepBlocker` below.
+        this.network = options.network ?? new SimulatorNetwork(this.simctl, process.env.VITEST ? { filterHostBinary: path.join(tmpdir(), 'tapflow-no-filter-host') } : {});
+        // **Wired here rather than in the constructor call above, and the difference is coverage.** An
+        // injected `SimulatorNetwork` — which is what every test uses — would otherwise never carry the
+        // handler, so the only path that tells a tester enforcement was lost was reachable in production
+        // and in nothing else.
+        this.network.setEnforcementLostHandler((deviceId) => { this.reportEnforcementLost(deviceId); });
         this.fps = options.fps ?? 30;
         this.intervalMs = options.intervalMs;
         this.reconnectDelays = options.reconnectDelays ?? [1000, 2000, 4000, 8000, 16000, 30000];
@@ -84,6 +172,9 @@ export class IOSAgent {
     }
     async connect(relayUrl) {
         this._stopping = false;
+        // Paired with the `dispose()` in `disconnect()`. This method is public and reuses the network, so
+        // without it a reconnect leaves the liveness watcher off for good — see `SimulatorNetwork.resume`.
+        this.network.resume();
         if (this._reconnectTimer) {
             clearTimeout(this._reconnectTimer);
             this._reconnectTimer = null;
@@ -103,7 +194,7 @@ export class IOSAgent {
             }, this.handshakeTimeoutMs);
             ws.once('open', () => {
                 disableNagle(ws);
-                ws.send(JSON.stringify({
+                this.sendOn(ws, {
                     type: 'agent:register',
                     platform: 'ios',
                     // Lets a viewer tell a clipboard-capable agent from one that predates the
@@ -118,7 +209,7 @@ export class IOSAgent {
                         status: d.status,
                         osVersion: d.osVersion,
                     })),
-                }));
+                });
             });
             ws.once('message', (data) => {
                 let msg;
@@ -140,7 +231,14 @@ export class IOSAgent {
                     this.initDeviceStates(msg.registeredSessions);
                     ws.on('message', (d) => {
                         try {
-                            this.handleRelayMessage(JSON.parse(d.toString()));
+                            const m = JSON.parse(d.toString());
+                            // Every type `handleRelayMessage` dispatches is session-scoped, and the relay resolves the
+                            // session before forwarding — so a message without one did not come from that path. Rejecting
+                            // it here is what lets the dispatcher declare `sessionId: string` instead of threading an
+                            // optional through 30 sends and asserting it with `!` at each one.
+                            if (typeof m.type !== 'string' || typeof m.sessionId !== 'string')
+                                return;
+                            this.handleRelayMessage(m);
                         }
                         catch { /* ignore malformed */ }
                     });
@@ -183,6 +281,8 @@ export class IOSAgent {
                 streamReader: null,
                 captureStreamer: null,
                 bootSeq: 0,
+                bootAbandon: new Map(),
+                bootsInFlight: new Set(),
                 orientation: 'portrait',
                 loadedChrome: null,
                 softKeyboardVisible: false,
@@ -208,10 +308,14 @@ export class IOSAgent {
             this.resourcesTimer = null;
         }
         for (const state of this.deviceStates.values()) {
+            this.bumpBootSeq(state, 'relay-lost');
             this.cleanupDeviceState(state);
         }
         this.deviceStates.clear();
         this.uiTreeReader.stop();
+        // The liveness watcher outlives every device it was started for, so it is stopped here with the
+        // other things that tick. It is `unref`'d, which is why nobody noticed it had no caller.
+        this.network.dispose();
         this.sleepBlocker.release();
         this.ws?.close();
         this.ws = null;
@@ -226,6 +330,13 @@ export class IOSAgent {
             this.resourcesTimer = null;
         }
         for (const state of this.deviceStates.values()) {
+            // Invalidate any boot still in flight against this state. The map is dropped just below, but a
+            // `handleDeviceBoot` awaiting simctl holds its own reference and its seq would still match, so it
+            // would go on to build a TouchHelper on a state nobody owns. That used to leak one child process;
+            // a self-reviving helper would respawn for the life of the agent with no reference left to stop it.
+            // Bumped here rather than inside `cleanupDeviceState` so that all three retirements name a reason —
+            // and so Android, whose boot path calls its own cleanup mid-boot, can hold the same shape.
+            this.bumpBootSeq(state, 'relay-lost');
             this.cleanupDeviceState(state);
         }
         this.deviceStates.clear();
@@ -254,7 +365,7 @@ export class IOSAgent {
         const bootedCount = Array.from(this.deviceStates.values()).filter((s) => s.streamReader !== null).length;
         const slotsTotal = this.deviceStates.size;
         const { memUsedMB, memTotalMB } = this.resources.getMemoryUsage();
-        this.ws.send(JSON.stringify({
+        this.sendOn(this.ws, {
             type: 'agent:resources',
             resources: {
                 cpuPercent: this.resources.getCpuPercent(),
@@ -264,9 +375,16 @@ export class IOSAgent {
                 slotsTotal,
                 reportedAt: Date.now(),
             },
-        }));
+        });
     }
     cleanupDeviceState(state) {
+        // Drop this device out of the filter rule. The rule lives on the host and is keyed only by udid,
+        // so a simulator that goes away while offline would otherwise keep its udid named there for the
+        // rest of the Mac's uptime — and the next boot of that same device would come up offline with
+        // nothing on screen saying why.
+        void this.network.forget(state.deviceId).catch((e) => {
+            logger.warn('could not clear the network rule for a retired device:', e.message);
+        });
         void state.streamReader?.cancel();
         state.streamReader = null;
         state.captureStreamer = null; // reader.cancel() kills the helper proc; drop the ref so a stale requestKeyframe() no-ops
@@ -285,31 +403,39 @@ export class IOSAgent {
         state.streamWs = null;
     }
     sendChromeData(state, device) {
-        if (!this.ws)
+        // `readyState`, not presence: this runs mid-boot, and a socket that closed since the entry guard
+        // takes the payload into a buffer nobody flushes while `device:ready` is dropped by `sendMsg`'s own
+        // check — leaving the caller with neither the data nor an answer.
+        if (this.ws?.readyState !== WebSocket.OPEN)
             return;
+        // Stop the outgoing helper before dropping the reference. This used to leak a child process;
+        // now that a helper revives itself on death, an orphan would also keep respawning with
+        // nobody left holding a reference to stop it.
+        state.touchHelper?.stop();
         state.touchHelper = new TouchHelper(device.id);
         state.touchHelper.start();
-        this.ws.send(JSON.stringify({
+        this.sendOn(this.ws, {
             type: 'session:deviceInfo',
             sessionId: state.sessionId,
             payload: {
                 deviceName: device.name,
                 osVersion: device.osVersion ?? '',
             },
-        }));
+        });
         state.loadedChrome = this.chromeLoader.load(device.typeId ?? device.name);
         if (!state.loadedChrome)
             return;
-        this.ws.send(JSON.stringify({
+        this.sendOn(this.ws, {
             type: 'session:chrome',
             sessionId: state.sessionId,
             payload: state.loadedChrome,
-        }));
+        });
     }
     startBinaryStream(state, streamWs) {
         // H.264 is the default; opt out per-agent with TAPFLOW_IOS_CODEC=jpeg. It also needs
         // a browser that reported it can decode it (device:boot acceptH264) — otherwise JPEG.
-        // Only on the ScreenCaptureStreamer path — the MjpegStreamer fallback is always JPEG.
+        // Only on the ScreenCaptureStreamer path — the MjpegStreamer fallback is always JPEG, and now
+        // genuinely produces it rather than only being stamped that way.
         const envAllowsH264 = process.env.TAPFLOW_IOS_CODEC !== 'jpeg';
         const useH264 = this.intervalMs === undefined && envAllowsH264 && state.acceptH264;
         const codec = useH264 ? CODEC_H264 : CODEC_JPEG;
@@ -398,29 +524,86 @@ export class IOSAgent {
         await registerStreamWs(streamWs, state.sessionId);
         return streamWs;
     }
-    async handleDeviceBoot(sessionId, deviceId, fullErase = false, acceptH264 = false, tier) {
+    /** Retire the boot that holds the current seq, recording what retired it, and return the new seq.
+     *
+     *  **Three callers, and the third is why this is a method.** A new boot supersedes the one in flight, a
+     *  shutdown abandons it, and losing the relay invalidates it — that last one lives in the reconnect path
+     *  (`cleanupDeviceState`'s callers) and is easy to miss when reading `handleDeviceBoot` alone. Spreading
+     *  the reason across three `state.bootSeq++` lines makes forgetting one silent; here it is a parameter. */
+    bumpBootSeq(state, reason) {
+        if (state.bootsInFlight.has(state.bootSeq))
+            state.bootAbandon.set(state.bootSeq, reason);
+        return ++state.bootSeq;
+    }
+    /** Answer a boot this agent has stopped running. Called at every point that abandons one.
+     *
+     *  **Only when a correlator exists**, which is the same rule the input path settled on (#489): a reply
+     *  nobody is waiting for is not an answer, and the dashboard reports every *uncorrelated*
+     *  `device:boot-error` as a failure — deliberately, since Android's dead-stream report has no id it could
+     *  carry (#426). So sending one for a boot with no correlator would put an error toast on a tester's
+     *  screen for a device that is booting normally. */
+    abandonBoot(state, seq, sessionId, requestId) {
+        const reason = state.bootAbandon.get(seq) ?? 'superseded';
+        state.bootAbandon.delete(seq);
+        // **A state the agent has stopped holding cannot be answered, and trying is worse than silence.**
+        // `relay-lost` retires a boot by dropping the whole map, so by the time the parked `await` resumes this
+        // `state` is an object nobody is registered against — and whether the socket is back yet decides
+        // between dropping the reply and sending it to a *new* relay naming a session id it has never heard
+        // of. Neither is an answer, and which one happens is a race between a poll interval and a backoff.
+        if (this.deviceStates.get(sessionId) !== state) {
+            logger.warn(`boot for ${sessionId} abandoned (${reason}) after the session was dropped — nothing to answer`);
+            return;
+        }
+        if (!requestId) {
+            logger.warn(`boot for ${sessionId} abandoned (${reason}) with no requestId — nothing to answer`);
+            return;
+        }
+        this.sendMsg({ type: 'device:boot-error', sessionId, requestId, message: bootAbandonMessage(reason) });
+    }
+    // `requestId` is a parameter, never a field on `state`: `bootSeq` exists because two boots overlap,
+    // and a correlator hoisted onto shared state would answer the first request with the second's id.
+    // Optional because the relay's idle timer boots nothing — but every *browser* boot carries one.
+    async handleDeviceBoot(sessionId, deviceId, fullErase = false, acceptH264 = false, tier, requestId) {
         const state = this.deviceStates.get(sessionId);
-        if (!state || !this.ws)
+        // Split, because the two halves are not the same kind of nothing. No open control channel means the
+        // answer itself has nowhere to go, so this is the one abandonment that stays silent — and the caller
+        // learns from the relay instead, which declares the agent away and terminates the session. A missing
+        // `state` is answerable and now answered (#489's reasoning, on the boot path).
+        const ws = this.ws;
+        if (!ws || ws.readyState !== WebSocket.OPEN)
+            return;
+        if (!state) {
+            if (requestId)
+                this.sendMsg({ type: 'device:boot-error', sessionId, requestId, message: BOOT_NO_SESSION_STATE });
             return;
+        }
         state.acceptH264 = acceptH264;
         if (tier) {
             state.secureContext = tier.secureContext;
             state.external = tier.external;
         }
-        const seq = ++state.bootSeq;
-        void state.streamReader?.cancel();
-        state.streamReader = null;
-        state.captureStreamer = null; // reader.cancel() kills the helper proc; drop the ref so a stale requestKeyframe() no-ops
-        state.touchHelper?.stop();
-        state.touchHelper = null;
-        state.booted = false;
-        state.streamWs?.close();
-        state.streamWs = null;
-        this.ws.send(JSON.stringify({ type: 'device:booting', sessionId }));
+        const seq = this.bumpBootSeq(state, 'superseded');
+        state.bootsInFlight.add(seq);
+        // **The teardown runs inside the try, and that is a fix rather than tidying.** It ran before it, so a
+        // throw there rejected this handler into the bare `.catch(logger.error)` at its dispatch site: no
+        // `device:booting`, no ready, no error — and the seq was already bumped, so the boot this one
+        // superseded was gone as well. The caller then waited out the very deadline this change exists to
+        // end. `finally` is what stops `bootAbandon` outliving the boot that would have read it.
         try {
+            void state.streamReader?.cancel();
+            state.streamReader = null;
+            state.captureStreamer = null; // reader.cancel() kills the helper proc; drop the ref so a stale requestKeyframe() no-ops
+            state.touchHelper?.stop();
+            state.touchHelper = null;
+            state.booted = false;
+            state.streamWs?.close();
+            state.streamWs = null;
+            this.sendOn(ws, { type: 'device:booting', sessionId });
             const devices = await this.simctl.listDevices();
-            if (seq !== state.bootSeq)
+            if (seq !== state.bootSeq) {
+                this.abandonBoot(state, seq, sessionId, requestId);
                 return;
+            }
             const target = devices.find((d) => d.id === deviceId);
             if (!target)
                 throw new PlatformError(`Device not found: ${deviceId}`);
@@ -443,8 +626,10 @@ export class IOSAgent {
                 // The shutdown is an await, so a newer boot for this device may have overtaken us while it
                 // ran. Without this check the superseded boot goes on to erase a device the tester has
                 // since re-picked with the toggle off — the exact wipe-with-no-click this issue is about.
-                if (seq !== state.bootSeq)
+                if (seq !== state.bootSeq) {
+                    this.abandonBoot(state, seq, sessionId, requestId);
                     return;
+                }
                 try {
                     await this.simctl.erase(deviceId);
                 }
@@ -469,20 +654,51 @@ export class IOSAgent {
                 }
                 await this.simctl.boot(deviceId);
             }
-            else if (target.status !== 'booted') {
+            else {
+                // Unconditionally, including when the list above said `booted`. That reading is already
+                // stale by the time we act on it — a tester can ⌘Q the simulator, or run `simctl shutdown`,
+                // in the width of one `xcrun` round trip — and skipping the boot on it is the only way to
+                // reach the wait below with *nothing bringing the device up*, which then costs the full
+                // deadline to discover. `SimctlWrapper.boot` swallows `Unable to boot device in current
+                // state: Booted`, so re-issuing it for a device that really is up costs one no-op
+                // subprocess and makes "the wait only ever runs after a boot was accepted" true.
                 await this.bootWithZombieRecovery(deviceId);
             }
-            if (seq !== state.bootSeq)
+            if (seq !== state.bootSeq) {
+                this.abandonBoot(state, seq, sessionId, requestId);
                 return;
-            const refreshed = await this.simctl.listDevices();
-            const refreshedDevice = refreshed.find((d) => d.id === deviceId) ?? target;
-            this.sendChromeData(state, {
-                ...refreshedDevice,
-                status: 'booted',
+            }
+            // `simctl boot` returns on initiation, so everything below used to run while the device was
+            // still coming up — measured 7.6s early (#486). The status sent with the chrome data was
+            // hardcoded `'booted'` over a value that had just been fetched and discarded, and
+            // `device:ready` went out a few lines later. A human is slower than the gap and rarely
+            // notices; `mcp-server` installs and taps the moment it sees ready, which is what #440's
+            // "No devices are booted" was.
+            // `isStale` rather than a check on the far side alone: this handler is fire-and-forget, so a
+            // shutdown arriving mid-wait bumps `bootSeq` and leaves the poll spawning `xcrun simctl list`
+            // twice a second against a device that is now deliberately off — for the rest of the deadline,
+            // with nothing left that wants the answer.
+            const bootedDevice = await this.simctl.waitUntilBooted(deviceId, { isStale: () => seq !== state.bootSeq });
+            // Arm the network injection while nothing is running on the device yet — dyld reads the
+            // environment at process start, so anything launched before this is unhooked for its whole life.
+            // Best-effort: the network toggle is opt-in and a device that cannot be armed says so through
+            // `network:state.available`, which is a better answer than a boot that fails for it.
+            await this.network.arm(deviceId).catch((e) => {
+                logger.warn('could not arm the network injection:', e.message);
             });
+            // Another await — a multi-second one — and `sendChromeData` below starts a helper process. A
+            // shutdown or a newer boot arriving in this gap would otherwise get a helper installed for the
+            // device it is taking down — and one that revives itself, so the stale reference outlives the
+            // boot that returns just below.
+            if (seq !== state.bootSeq) {
+                this.abandonBoot(state, seq, sessionId, requestId);
+                return;
+            }
+            this.sendChromeData(state, bootedDevice);
             const streamWs = await this.openStreamWs(state);
             if (seq !== state.bootSeq) {
                 streamWs.close();
+                this.abandonBoot(state, seq, sessionId, requestId);
                 return;
             }
             this.startBinaryStream(state, streamWs);
@@ -491,7 +707,16 @@ export class IOSAgent {
             if (this.audioEnabled())
                 this.startAudioCapture(state, streamWs, deviceId);
             state.booted = true;
-            this.ws?.send(JSON.stringify({ type: 'device:ready', sessionId, payload: { deviceId } }));
+            // **"Driving", not "transitioned from off to on".** A tester who picks a simulator that was
+            // already running is choosing the device tapflow should act on, and `simctl boot` is issued on
+            // every path precisely so that case reaches here. Requiring an off→on transition would leave
+            // that device unowned and put the resolvers back to refusing between two live simulators.
+            this.ownedDevices.add(deviceId);
+            this.sendMsg({ type: 'device:ready', sessionId, requestId, payload: { deviceId } });
+            // The unsolicited report the protocol names on `device:ready`. It follows the ready rather than
+            // riding inside it: a tester whose device just came up can arm the toggle in the same breath, and
+            // a boot that armed nothing still has to say so rather than leaving the control blank.
+            void this.reportNetworkState(sessionId);
             // Sync AppleKeyboards after ready — fire-and-forget so streaming isn't delayed.
             // hw=Automatic lets the hardware layout follow the active input source on LANG1/CapsLock.
             // By the time the user navigates to a text field the sync has already completed.
@@ -500,10 +725,22 @@ export class IOSAgent {
             });
         }
         catch (e) {
-            if (seq !== state.bootSeq)
+            if (seq !== state.bootSeq) {
+                this.abandonBoot(state, seq, sessionId, requestId);
                 return;
-            const message = e instanceof Error ? e.message : String(e);
-            this.ws?.send(JSON.stringify({ type: 'device:boot-error', sessionId, message }));
+            }
+            // `firstLine`, not `e.message`: this reaches a toast, and node's first line is
+            // `Command failed: xcrun simctl boot <UDID>`, which says nothing and echoes the udid. That
+            // matters more now that the boot is issued unconditionally — a device caught mid `Shutting
+            // Down` refuses the boot, and refusing is correct (swallowing it would put us back to waiting
+            // on a device nobody is bringing up), so the refusal is what the tester reads.
+            this.sendMsg({ type: 'device:boot-error', sessionId, requestId, message: firstLine(e) });
+        }
+        finally {
+            state.bootsInFlight.delete(seq);
+            // Its own key, in the one case nothing reads it: a newer boot arriving after this boot's last
+            // checkpoint but before it returns.
+            state.bootAbandon.delete(seq);
         }
     }
     // Boot a device, auto-recovering from a vanished data dir. simctl lists the device
@@ -521,11 +758,21 @@ export class IOSAgent {
             await this.simctl.boot(deviceId);
         }
     }
-    async handleDeviceShutdown(sessionId, deviceId) {
+    async handleDeviceShutdown(sessionId, deviceId, requestId) {
         const state = this.deviceStates.get(sessionId);
         if (!state)
             return;
-        state.bootSeq++;
+        this.bumpBootSeq(state, 'shut-down');
+        // **Said here as well as in `cleanupDeviceState`, because this path does not go through it.**
+        // The teardown below is a copy of that method's, and the copy is older than the network rule —
+        // so a device shut down from the dashboard while offline kept its udid in the host filter for
+        // the rest of the Mac's uptime, and its next boot came up with traffic dead and nothing on
+        // screen saying why. The two bodies have already diverged in another respect (this one does not
+        // stop the audio tap), which is why this is a call rather than a merge: unifying them changes
+        // audio teardown on a path nobody asked about.
+        void this.network.forget(deviceId).catch((e) => {
+            logger.warn('could not clear the network rule for a shut-down device:', e.message);
+        });
         void state.streamReader?.cancel();
         state.streamReader = null;
         state.captureStreamer = null; // reader.cancel() kills the helper proc; drop the ref so a stale requestKeyframe() no-ops
@@ -540,11 +787,19 @@ export class IOSAgent {
         this.uiTreeReader.stopIfDevice(deviceId);
         try {
             await this.simctl.shutdown(deviceId);
-            this.ws?.send(JSON.stringify({
+            // **After the shutdown lands, not with the teardown above.** Everything before this point is
+            // the session's state, which is correct to drop the moment a shutdown is asked for. Ownership
+            // is about the *device*, and a shutdown that throws leaves it running — forgetting it was ours
+            // there would hand an ambiguous choice back to the resolvers for a simulator tapflow is still
+            // driving. `cleanupDeviceState` deliberately does not clear it at all: that path is a relay
+            // disconnect, where the device outlives the session and ownership is the thing worth keeping.
+            this.ownedDevices.delete(deviceId);
+            this.sendMsg({
                 type: 'device:shutdown-done',
                 sessionId,
+                requestId,
                 payload: { deviceId },
-            }));
+            });
         }
         catch (e) {
             const message = e instanceof Error ? e.message : String(e);
@@ -578,14 +833,89 @@ export class IOSAgent {
     sentinelParked(deviceId) {
         return (this.parkedSentinels.get(deviceId) ?? 0) > 0;
     }
-    // Ack a terminal input: input:done = dispatched to a booted device (not a landing guarantee — HID is fire-and-forget); input:error = no live channel / not booted. Off the sync inject path, so start/end pairing is unaffected.
-    async ackInput(state, dispatched) {
-        const booted = dispatched && (state.booted || (await this.isBooted(state.deviceId)));
-        if (booted)
+    // A terminal input naming a session this agent holds no state for. Reachable in a way that is
+    // genuinely disputed: `sessionRebind.test.ts` records that a restarted agent is re-seeded from
+    // `agent:registered`, so `!state` should never fire — but `registeredSessions` carries one entry
+    // per *device* (`RelayServer.ts`, `byDeviceId`), and the relay's own comment there notes that one
+    // device can now sit behind two sessions, which leaves the second unseeded. Answering costs four
+    // lines; staying silent costs a terminal input swallowed and the caller's own fallback reporting
+    // success. Android already answers, and `channel-unavailable` is what it maps this to.
+    /** The correlator on an input an ack answers, or `null` if the frame cannot be attributed.
+     *
+     *  A local capture rather than a guard at the top of the dispatcher, and that is the point: a guard there
+     *  would not narrow `msg.requestId` inside the case, so the shortest way to satisfy the reply's required
+     *  field would be `msg.requestId!` — the assertion removed from `open-url` and then from clipboard. This
+     *  hands back a `string` the case can close over.
+     *
+     *  It is unvalidated JSON, so the check is real work rather than ceremony: the declaration is required and
+     *  every in-repo sender is typed against it, and #444 made the relay refuse an empty one — but this agent may
+     *  be talking to a relay older than that, and `mcp-server`'s tool
+     *  schemas are bare `z.string()` so a model can produce `''`. */
+    correlatorOf(msg) {
+        if (typeof msg.requestId === 'string' && msg.requestId !== '')
+            return msg.requestId;
+        logger.warn(`${msg.type} without a usable requestId — dropped, its ack could not be attributed`);
+        return null;
+    }
+    ackNoSession(sessionId, requestId) {
+        // The `if (!sessionId) return` this used to open with is gone: the dispatcher now declares
+        // `sessionId: string`, so there is no undefined to guard against and the guard would have been a
+        // silent drop with nothing left that could reach it.
+        this.sendMsg({
+            type: 'input:error', sessionId, requestId,
+            message: INPUT_ERROR_MESSAGES['channel-unavailable'],
+            reason: 'channel-unavailable',
+        });
+    }
+    /**
+     * Why a write was refused. The helper's boolean says only "no".
+     *
+     * `kind` matters because the two questions were decided at different times. Readiness is about now;
+     * a continuation frame's fate was decided when the gesture opened. A gesture whose opening frame
+     * was refused inside the start-up window owns nothing, so its terminal frame can never land no
+     * matter how ready the helper has since become — and reading readiness first answered `malformed`
+     * ("never retry") for precisely the case `channel-starting` exists to serve. Ownership is therefore
+     * checked first for continuations, which is also the right answer when the helper died mid-gesture
+     * and its replacement is still starting: waiting would not help either.
+     *
+     * Safe to read at the ack site rather than inside the write, because iOS writes are synchronous —
+     * but only for the question readiness answers. That is why ownership is asked separately.
+     */
+    refusalReason(helper, kind) {
+        const state = helper?.inputState() ?? 'unavailable';
+        // No channel at all dominates: the caller must reconnect, and telling it to re-open a gesture
+        // would send it round a loop that cannot succeed.
+        if (state === 'unavailable')
+            return 'channel-unavailable';
+        // Then ownership, and only for a continuation. A gesture whose opening frame never landed owns
+        // nothing, so its terminal frame can never be delivered however ready the helper has become —
+        // which is why readiness must not be consulted first here.
+        //
+        // A consequence worth stating: `channel-starting` is unreachable for a continuation. Owning a
+        // gesture requires an opening frame to have landed, which requires the helper to have been ready,
+        // so a continuation is never refused *merely* because the channel is still coming up. Standalone
+        // inputs — a key, a button — are the ones that get that answer.
+        if (kind === 'continuation' && !helper?.ownsGesture())
+            return 'no-gesture';
+        return state === 'starting' ? 'channel-starting' : 'no-gesture';
+    }
+    // Ack a terminal input. `input:done` = dispatched to a booted device (not a landing guarantee —
+    // HID is fire-and-forget). Otherwise `input:error` carries a machine-readable `reason` so a caller
+    // can tell "retry in a moment" from "reconnect" from "never retry"; `message` stays human prose.
+    // Off the sync inject path, so start/end pairing is unaffected.
+    //
+    // `requestId` is a parameter, never read from shared state: a gesture is dozens of frames and two can
+    // overlap, so a correlator hoisted out of per-request scope would answer one input with another's id —
+    // which is #499 rebuilt inside the agent. Same reason `seq` is passed in on the Android side.
+    async ackInput(state, outcome, requestId) {
+        const reason = outcome !== 'delivered'
+            ? outcome
+            : (state.booted || (await this.isBooted(state.deviceId))) ? null : 'not-booted';
+        if (reason === null)
             state.booted = true; // cache the post-reconnect verify so later inputs skip simctl
-        this.ws?.send(JSON.stringify(booted
-            ? { type: 'input:done', sessionId: state.sessionId }
-            : { type: 'input:error', sessionId: state.sessionId, message: dispatched ? 'device not booted' : 'input channel not ready' }));
+        this.sendMsg(reason === null
+            ? { type: 'input:done', sessionId: state.sessionId, requestId }
+            : { type: 'input:error', sessionId: state.sessionId, requestId, message: INPUT_ERROR_MESSAGES[reason], reason });
     }
     async isBooted(deviceId) {
         try {
@@ -601,52 +931,78 @@ export class IOSAgent {
             case 'device:boot': {
                 const { deviceId, resetMode, acceptH264, secureContext, external } = msg.payload;
                 const sessionId = msg.sessionId;
-                this.handleDeviceBoot(sessionId, deviceId, resetMode === 'full-erase', acceptH264 === true, { secureContext: !!secureContext, external: !!external })
+                this.handleDeviceBoot(sessionId, deviceId, resetMode === 'full-erase', acceptH264 === true, { secureContext: !!secureContext, external: !!external }, msg.requestId)
                     .catch((e) => logger.error('handleDeviceBoot failed:', e));
                 break;
             }
             case 'device:shutdown': {
                 const { deviceId } = msg.payload;
                 const sessionId = msg.sessionId;
-                this.handleDeviceShutdown(sessionId, deviceId)
+                this.handleDeviceShutdown(sessionId, deviceId, msg.requestId)
                     .catch((e) => logger.error('handleDeviceShutdown failed:', e));
                 break;
             }
             case 'app:install': {
                 const { filePath, bundleId } = msg.payload;
                 const sessionId = msg.sessionId;
+                const { requestId } = msg;
+                if (typeof requestId !== 'string' || requestId === '') {
+                    console.warn('[tapflow] app:install without a requestId — dropped, cannot correlate a reply');
+                    break;
+                }
+                // `...body` first: with the ids last, a body *variable* carrying one would override the real
+                // correlator, because excess-property checking does not fire on variables. See `open-url`.
+                const respond = (body) => this.sendMsg({ ...body, sessionId, requestId });
                 const installState = this.deviceStates.get(sessionId);
                 if (!installState) {
-                    this.ws?.send(JSON.stringify({ type: 'app:install-error', sessionId, message: 'No booted device' }));
+                    respond({ type: 'app:install-error', message: 'No booted device' });
                     break;
                 }
                 this.installBuild(installState.deviceId, filePath, bundleId)
-                    .then(() => this.ws?.send(JSON.stringify({ type: 'app:install-done', sessionId })))
+                    .then(() => respond({ type: 'app:install-done' }))
                     .catch((e) => {
                     const message = e instanceof Error ? e.message : String(e);
-                    this.ws?.send(JSON.stringify({ type: 'app:install-error', sessionId, message }));
+                    respond({ type: 'app:install-error', message });
                 });
                 break;
             }
             case 'app:launch': {
                 const { bundleId } = msg.payload;
                 const sessionId = msg.sessionId;
+                const { requestId } = msg;
+                if (typeof requestId !== 'string' || requestId === '') {
+                    console.warn('[tapflow] app:launch without a requestId — dropped, cannot correlate a reply');
+                    break;
+                }
+                // `...body` first: with the ids last, a body *variable* carrying one would override the real
+                // correlator, because excess-property checking does not fire on variables. See `open-url`.
+                const respond = (body) => this.sendMsg({ ...body, sessionId, requestId });
                 const launchState = this.deviceStates.get(sessionId);
                 if (!launchState) {
-                    this.ws?.send(JSON.stringify({ type: 'app:launch-error', sessionId, message: 'No booted device' }));
+                    respond({ type: 'app:launch-error', message: 'No booted device' });
                     break;
                 }
-                this.simctl.launchApp(launchState.deviceId, bundleId)
-                    .then(() => {
+                // The target is named BEFORE the launch, and the order is the whole point: dyld reads the
+                // environment when the process starts, so naming it afterwards arms the next launch and leaves
+                // this one unhooked while `available` would still say true.
+                this.network.target(launchState.deviceId, bundleId)
+                    .catch((e) => logger.warn('could not name the network target:', e.message))
+                    .then(() => this.simctl.launchApp(launchState.deviceId, bundleId))
+                    .then((pid) => {
+                    // **After the launch, with the pid it returned.** The network control measures how long a
+                    // started process has gone without reporting its hooks; opening that window before
+                    // `simctl launch` had run put the launch itself inside the budget, and left it open when
+                    // the launch failed. A null or unchanged pid means no new process, so nothing is owed.
+                    this.network.markLaunched(launchState.deviceId, pid);
                     // Track the foreground app so ui:tree:request can query it via XCUITest.
                     this.lastBundleIds.set(launchState.deviceId, bundleId);
                     // Audio: the whole-sim tap's poll picks up the launched app process within one interval;
                     // no per-launch helper needed.
-                    this.ws?.send(JSON.stringify({ type: 'app:launch-done', sessionId }));
+                    respond({ type: 'app:launch-done' });
                 })
                     .catch((e) => {
                     const message = e instanceof Error ? e.message : String(e);
-                    this.ws?.send(JSON.stringify({ type: 'app:launch-error', sessionId, message }));
+                    respond({ type: 'app:launch-error', message });
                 });
                 break;
             }
@@ -668,11 +1024,19 @@ export class IOSAgent {
                 break;
             }
             case 'input:touch:end': {
+                const requestId = this.correlatorOf(msg);
+                if (requestId === null)
+                    break;
                 const state = this.deviceStates.get(msg.sessionId);
-                if (!state)
+                if (!state) {
+                    this.ackNoSession(msg.sessionId, requestId);
                     break;
-                state.touchHelper?.touchEnd();
-                void this.ackInput(state, state.touchHelper !== null); // terminal of a tap/swipe → ack the gesture
+                }
+                // The helper's answer, not its existence: a helper whose process has died reports every
+                // write as dropped, and that is what the caller needs to hear (#482).
+                const helper = state.touchHelper;
+                // terminal of a tap/swipe → ack the gesture
+                void this.ackInput(state, helper?.touchEnd() ? 'delivered' : this.refusalReason(helper, 'continuation'), requestId);
                 break;
             }
             case 'input:pinch:start': {
@@ -693,11 +1057,16 @@ export class IOSAgent {
                 break;
             }
             case 'input:pinch:end': {
+                const requestId = this.correlatorOf(msg);
+                if (requestId === null)
+                    break;
                 const state = this.deviceStates.get(msg.sessionId);
-                if (!state)
+                if (!state) {
+                    this.ackNoSession(msg.sessionId, requestId);
                     break;
-                state.touchHelper?.pinchEnd();
-                void this.ackInput(state, state.touchHelper !== null);
+                }
+                const pinchHelper = state.touchHelper;
+                void this.ackInput(state, pinchHelper?.pinchEnd() ? 'delivered' : this.refusalReason(pinchHelper, 'continuation'), requestId);
                 break;
             }
             case 'input:rotate': {
@@ -724,24 +1093,27 @@ export class IOSAgent {
                     : this.simctl.hideSoftwareKeyboard(state.deviceId);
                 op.then(() => {
                     state.softKeyboardVisible = showing;
-                    this.ws?.send(JSON.stringify({
+                    this.sendMsg({
                         type: 'keyboard:toggled',
                         sessionId: state.sessionId,
                         payload: { visible: showing },
-                    }));
+                    });
                 }).catch((e) => {
                     logger.error('keyboard toggle failed:', e);
                 });
                 break;
             }
             case 'input:type': {
+                const requestId = this.correlatorOf(msg);
+                if (requestId === null)
+                    break;
                 const sessionId = msg.sessionId;
                 const state = this.deviceStates.get(sessionId);
                 if (state)
                     this.ensureTouchHelper(state);
                 const { text } = (msg.payload ?? {});
                 if (!state?.touchHelper) {
-                    this.ws?.send(JSON.stringify({ type: 'input:type-error', sessionId, message: 'No booted device' }));
+                    this.sendMsg({ type: 'input:type-error', sessionId, requestId, message: 'No booted device' });
                     break;
                 }
                 // simctl pbcopy → Cmd+V paste. Works for arbitrary Unicode (unlike a
@@ -758,92 +1130,155 @@ export class IOSAgent {
                         state.softKeyboardVisible = false;
                         await this.simctl.hideSoftwareKeyboard(state.deviceId).catch(() => { });
                     }
-                    state.touchHelper?.sendKey(KEY_CODE_MAP['KeyV'], MODIFIER_BITS['MetaLeft']);
+                    // Throwing routes into the input:type-error below. Without it a dropped chord still
+                    // answers input:type-done: the text sits on the device pasteboard, nothing was pasted
+                    // into the app, and the caller moves on. Unlike the copy path in clipboard:read there
+                    // is no pasteboard deadline here to fail loudly in its place.
+                    if (!state.touchHelper?.sendKey(KEY_CODE_MAP['KeyV'], MODIFIER_BITS['MetaLeft'])) {
+                        throw new PlatformError('Cannot paste the text — no input channel to the device');
+                    }
                 };
                 // Ack on completion so a following input step (e.g. pressKey Enter) is
                 // only sent after the paste has actually landed.
                 // Shares the clipboard queue: this writes the pasteboard, so running it alongside a
                 // clipboard:read would overwrite that read's sentinel and be returned as "copied".
                 this.clipboardQueue(state.deviceId, doType)
-                    .then(() => this.ws?.send(JSON.stringify({ type: 'input:type-done', sessionId })))
+                    .then(() => this.sendMsg({ type: 'input:type-done', sessionId, requestId }))
                     .catch((e) => {
                     const message = e instanceof Error ? e.message : String(e);
                     logger.error('input:type (pbcopy+paste) failed:', e);
-                    this.ws?.send(JSON.stringify({ type: 'input:type-error', sessionId, message }));
+                    this.sendMsg({ type: 'input:type-error', sessionId, requestId, message });
                 });
                 break;
             }
             case 'input:key': {
+                const requestId = this.correlatorOf(msg);
+                if (requestId === null)
+                    break;
                 const state = this.deviceStates.get(msg.sessionId);
-                if (!state)
+                if (!state) {
+                    this.ackNoSession(msg.sessionId, requestId);
                     break;
+                }
                 this.ensureTouchHelper(state);
                 const { code, modifiers } = msg.payload;
                 const usage = KEY_CODE_MAP[code];
                 if (usage === undefined) {
-                    this.ws?.send(JSON.stringify({ type: 'input:error', sessionId: msg.sessionId, message: `unknown key code: ${code}` }));
+                    // Prose preserved (it names the code), reason added: `unsupported` tells a caller never to
+                    // retry, which the message alone could not.
+                    this.sendMsg({
+                        type: 'input:error', sessionId: msg.sessionId, requestId,
+                        message: `unknown key code: ${code}`, reason: 'unsupported',
+                    });
                     break;
                 }
                 if (state.softKeyboardVisible) {
                     // Hide the SW keyboard first so iOS re-initialises the HW keyboard
                     // context. Skipping this causes input-source desync (qks / ㅂㅏㄴ symptoms).
                     state.softKeyboardVisible = false;
-                    this.simctl.hideSoftwareKeyboard(state.deviceId)
-                        .then(() => state.touchHelper?.sendKey(usage, modifiers ?? 0))
-                        .catch((e) => {
-                        logger.error('hideSoftwareKeyboard (on key) failed:', e);
-                        state.touchHelper?.sendKey(usage, modifiers ?? 0);
+                    // The ack belongs after the deferred chord, not beside it. Acking out here ran before
+                    // the key was ever written, so the answer could only be a guess — and the guess was
+                    // "delivered". The hide failing is not fatal (the key still goes out), so the catch
+                    // resolves and the send happens exactly once either way.
+                    void this.simctl.hideSoftwareKeyboard(state.deviceId)
+                        .catch((e) => { logger.error('hideSoftwareKeyboard (on key) failed:', e); })
+                        .then(() => {
+                        const h = state.touchHelper;
+                        return this.ackInput(state, h?.sendKey(usage, modifiers ?? 0) ? 'delivered' : this.refusalReason(h, 'standalone'), requestId);
                     });
                 }
                 else {
-                    state.touchHelper?.sendKey(usage, modifiers ?? 0);
+                    const h = state.touchHelper;
+                    void this.ackInput(state, h?.sendKey(usage, modifiers ?? 0) ? 'delivered' : this.refusalReason(h, 'standalone'), requestId);
                 }
-                void this.ackInput(state, state.touchHelper !== null);
                 break;
             }
             case 'input:button': {
+                const requestId = this.correlatorOf(msg);
+                if (requestId === null)
+                    break;
                 const state = this.deviceStates.get(msg.sessionId);
-                if (!state)
+                if (!state) {
+                    this.ackNoSession(msg.sessionId, requestId);
                     break;
+                }
                 this.ensureTouchHelper(state);
                 const { name, phase } = msg.payload;
                 // Map the cross-platform button vocabulary (used by MCP) onto this
                 // device's actual chrome button names. Dashboard already sends the raw
                 // chrome names (e.g. "volume-up"), which pass through unchanged.
                 const chromeName = IOS_BUTTON_ALIASES[name] ?? name;
+                // Two branches below deliberately write nothing — a home press-down, and a button this
+                // device's chrome has no HID mapping for. Neither is a dropped input, so they answer
+                // with the channel's health instead of a write result; reporting an error there would
+                // trade this issue's false success for a false failure.
+                const btnHelper = state.touchHelper;
+                const wrote = (ok) => ok ? 'delivered' : this.refusalReason(btnHelper, 'standalone');
+                // The two branches that write nothing answer from the channel's state, which is `delivered`
+                // when it is ready. A button this device's chrome lacks stays a *success* — the device
+                // genuinely has no such button, so an error would be a false failure (#484). That is a
+                // decision, and it is why iOS never sends `unsupported` for a button while Android does.
+                let outcome = btnHelper?.inputState() === 'ready'
+                    ? 'delivered'
+                    : this.refusalReason(btnHelper, 'standalone');
                 if (chromeName === 'home') {
                     // Home has no HID down/up split — always a single legacy press. Send once on release
                     // (or on a phase-less legacy message) so a down+up pair doesn't fire it twice.
                     if (phase !== 'down')
-                        state.touchHelper?.pressLegacyButton(0);
+                        outcome = wrote(btnHelper?.pressLegacyButton(0) ?? false);
                 }
                 else {
                     const btn = state.loadedChrome?.buttons.find((b) => b.name === chromeName);
                     if (btn && btn.usagePage > 0 && btn.usage > 0) {
                         if (phase === 'down')
-                            state.touchHelper?.pressButtonDown(btn.usagePage, btn.usage);
+                            outcome = wrote(btnHelper?.pressButtonDown(btn.usagePage, btn.usage) ?? false);
                         else if (phase === 'up')
-                            state.touchHelper?.pressButtonUp(btn.usagePage, btn.usage);
+                            outcome = wrote(btnHelper?.pressButtonUp(btn.usagePage, btn.usage) ?? false);
                         else
-                            state.touchHelper?.pressButton(btn.usagePage, btn.usage);
+                            outcome = wrote(btnHelper?.pressButton(btn.usagePage, btn.usage) ?? false);
                     }
                 }
-                void this.ackInput(state, state.touchHelper !== null);
+                void this.ackInput(state, outcome, requestId);
                 break;
             }
             case 'open-url': {
                 const { url } = msg.payload;
                 const sessionId = msg.sessionId;
+                const { requestId } = msg;
+                // No fallback by design (see the note above `OpenUrl`), so an uncorrelatable request cannot be
+                // answered correlatably either — and inventing an id would make this agent's reply look like a
+                // response to a request nobody made. Every in-repo sender supplies one, and the `fixed` version
+                // group means there is no in-repo skew window; validating third-party frames at the relay's door
+                // is #444, which will take this over. Until then a drop with a log beats a reply that lies.
+                if (typeof requestId !== 'string' || requestId === '') {
+                    console.warn('[tapflow] open-url without a requestId — dropped, cannot correlate a reply');
+                    break;
+                }
+                // Every exit merges the correlation ids here. What that buys, precisely — review measured 13
+                // attacks and the type caught 3:
+                //
+                //  - **Omitting the correlator is a compile error.** That comes from `requestId: string` being
+                //    required on `OpenUrlDone`/`OpenUrlError`, reached through `sendMsg`'s `AgentControlOutbound`
+                //    — not from `OpenUrlReplyBody`, whose one contribution is rejecting a fresh id written as a
+                //    literal at the `respond(...)` call.
+                //  - **`...body` goes first on purpose.** With the ids last, a body *variable* carrying a
+                //    `requestId` cannot override them — excess-property checking does not fire on variables, so
+                //    the earlier `{ sessionId, requestId, ...body }` let a wrong id win.
+                //
+                // What it does **not** buy: `sendMsg` accepts any `string` here, so a site that bypasses
+                // `respond` type-checks. The echo tests in both agents' suites are what catch that, and each
+                // remaining correlation pair needs its own — this helper does not remove that work.
+                const respond = (body) => this.sendMsg({ ...body, sessionId, requestId });
                 const state = this.deviceStates.get(sessionId);
                 if (!state) {
-                    this.ws?.send(JSON.stringify({ type: 'open-url:error', sessionId, message: 'no booted device' }));
+                    respond({ type: 'open-url:error', message: 'no booted device' });
                     break;
                 }
                 this.simctl.openUrl(state.deviceId, url)
-                    .then(() => this.ws?.send(JSON.stringify({ type: 'open-url:done', sessionId })))
+                    .then(() => respond({ type: 'open-url:done' }))
                     .catch((e) => {
                     const message = e instanceof Error ? e.message : String(e);
-                    this.ws?.send(JSON.stringify({ type: 'open-url:error', sessionId, message }));
+                    respond({ type: 'open-url:error', message });
                 });
                 break;
             }
@@ -853,7 +1288,7 @@ export class IOSAgent {
                 const sessionId = msg.sessionId;
                 const shotState = this.deviceStates.get(sessionId);
                 if (!shotState) {
-                    this.ws?.send(JSON.stringify({ type: 'screenshot:error', sessionId, requestId, message: 'No booted device' }));
+                    this.sendMsg({ type: 'screenshot:error', sessionId, requestId, message: 'No booted device' });
                     break;
                 }
                 // Note for anyone widening this signature again: before the udid parameter existed this
@@ -861,32 +1296,38 @@ export class IOSAgent {
                 // type error — the format string simply became the device id. The compiler cannot help
                 // here; the test that scans exec arguments is what does.
                 this.simctl.screenshot(shotState.deviceId, format ?? 'png')
-                    .then((buf) => this.ws?.send(JSON.stringify({
+                    .then((buf) => this.sendMsg({
                     type: 'screenshot:done',
                     sessionId,
                     requestId,
                     format: format ?? 'png',
                     data: buf.toString('base64'),
-                })))
+                }))
                     .catch((e) => {
                     const message = e instanceof Error ? e.message : String(e);
-                    this.ws?.send(JSON.stringify({ type: 'screenshot:error', sessionId, requestId, message }));
+                    this.sendMsg({ type: 'screenshot:error', sessionId, requestId, message });
                 });
                 break;
             }
             case 'app:clear-state': {
                 const { bundleId } = (msg.payload ?? {});
                 const sessionId = msg.sessionId;
+                const { requestId } = msg;
+                if (typeof requestId !== 'string' || requestId === '') {
+                    console.warn('[tapflow] app:clear-state without a requestId — dropped, cannot correlate a reply');
+                    break;
+                }
+                const respond = (body) => this.sendMsg({ ...body, sessionId, requestId });
                 const state = this.deviceStates.get(sessionId);
                 if (!state || !bundleId) {
-                    this.ws?.send(JSON.stringify({ type: 'app:clear-state-error', sessionId, message: !state ? 'No booted device' : 'bundleId missing' }));
+                    respond({ type: 'app:clear-state-error', message: !state ? 'No booted device' : 'bundleId missing' });
                     break;
                 }
                 this.simctl.clearAppData(state.deviceId, bundleId)
-                    .then(() => this.ws?.send(JSON.stringify({ type: 'app:clear-state-done', sessionId })))
+                    .then(() => respond({ type: 'app:clear-state-done' }))
                     .catch((e) => {
                     const message = e instanceof Error ? e.message : String(e);
-                    this.ws?.send(JSON.stringify({ type: 'app:clear-state-error', sessionId, message }));
+                    respond({ type: 'app:clear-state-error', message });
                 });
                 break;
             }
@@ -894,15 +1335,46 @@ export class IOSAgent {
             // cannot know when the key actually lands (a visible software keyboard makes this path
             // await hideSoftwareKeyboard first), and reading too early returns the PREVIOUS
             // pasteboard — a stale value the user would never notice.
+            case 'network:set': {
+                const requestId = this.correlatorOf(msg);
+                if (requestId === null)
+                    break;
+                // `?? {}` and a re-check of a field the relay's schema already requires: this case owes a
+                // reply, and a cast that dereferences a missing payload throws into a dispatch that swallows
+                // it — answering nothing at all, the one failure a requester cannot tell from a hung device.
+                const { offline } = (msg.payload ?? {});
+                if (typeof offline !== 'boolean') {
+                    this.sendMsg({
+                        type: 'network:error', sessionId: msg.sessionId, requestId,
+                        message: 'network:set payload must carry a boolean `offline`.',
+                    });
+                    break;
+                }
+                void this.handleNetworkSet(msg.sessionId, offline, requestId);
+                break;
+            }
+            // The relay asks on a viewer's re-join (#614). Uncorrelated both ways: the reply is a report and
+            // nothing is waiting on it, so a session with no booted device answers nothing at all.
+            case 'network:request-state':
+                void this.reportNetworkState(msg.sessionId);
+                break;
             case 'clipboard:read': {
+                // `requestId: string`, matching the screenshot and ui:tree casts a few cases below — clipboard was
+                // the only one reading it as optional, for the same wire guarantee. `ClipboardRequest.requestId` is
+                // required and the only requester goes through a typed `send()`, so nothing in-repo omits it.
+                //
+                // It is still an assertion about unvalidated JSON, as those other two are: a third-party client
+                // could omit it, and then the reply would carry `undefined` and be uncorrelatable. That is inbound
+                // validation (#444), not producer typing, and making it optional here instead would just move the
+                // same hole into every reply this case sends.
                 const { requestId } = msg;
                 const sessionId = msg.sessionId;
                 const state = this.deviceStates.get(sessionId);
                 if (!state) {
-                    this.ws?.send(JSON.stringify({
+                    this.sendMsg({
                         type: 'clipboard:error', sessionId, requestId, message: 'No booted device',
                         payload: { sentinelParked: false },
-                    }));
+                    });
                     break;
                 }
                 const { press } = (msg.payload ?? {});
@@ -910,7 +1382,7 @@ export class IOSAgent {
                 // executes AFTER this — so the viewer hears back as soon as the outcome is known and
                 // does not wait out the restore window. The queue is still held until the restore
                 // finishes, which is what actually matters: the next operation must not see a sentinel.
-                const respond = (body) => this.ws?.send(JSON.stringify({ sessionId, requestId, ...body }));
+                const respond = (body) => this.sendMsg({ sessionId, requestId, ...body });
                 const read = async () => {
                     if (!press) {
                         respond({ type: 'clipboard:data', payload: { text: await this.simctl.getPasteboard(state.deviceId) } });
@@ -1023,23 +1495,31 @@ export class IOSAgent {
                 break;
             }
             case 'clipboard:write': {
+                // `requestId: string`, matching the screenshot and ui:tree casts a few cases below — clipboard was
+                // the only one reading it as optional, for the same wire guarantee. `ClipboardRequest.requestId` is
+                // required and the only requester goes through a typed `send()`, so nothing in-repo omits it.
+                //
+                // It is still an assertion about unvalidated JSON, as those other two are: a third-party client
+                // could omit it, and then the reply would carry `undefined` and be uncorrelatable. That is inbound
+                // validation (#444), not producer typing, and making it optional here instead would just move the
+                // same hole into every reply this case sends.
                 const { requestId } = msg;
                 const sessionId = msg.sessionId;
                 const state = this.deviceStates.get(sessionId);
                 if (!state) {
-                    this.ws?.send(JSON.stringify({
+                    this.sendMsg({
                         type: 'clipboard:error', sessionId, requestId, message: 'No booted device',
                         payload: { sentinelParked: false },
-                    }));
+                    });
                     break;
                 }
                 const { text, pasteAfter } = (msg.payload ?? {});
                 if (clipboardByteLength(text ?? '') > MAX_CLIPBOARD_BYTES) {
-                    this.ws?.send(JSON.stringify({
+                    this.sendMsg({
                         type: 'clipboard:error', sessionId, requestId,
                         message: `Clipboard is too large (max ${Math.floor(MAX_CLIPBOARD_BYTES / 1024)} KB)`,
                         payload: { sentinelParked: this.sentinelParked(state.deviceId) },
-                    }));
+                    });
                     break;
                 }
                 const write = async () => {
@@ -1064,17 +1544,22 @@ export class IOSAgent {
                         state.softKeyboardVisible = false;
                         await this.simctl.hideSoftwareKeyboard(state.deviceId).catch(() => { });
                     }
-                    state.touchHelper.sendKey(KEY_CODE_MAP['KeyV'], MODIFIER_BITS['MetaLeft']);
+                    // Same reason as input:type: the deadline above proves the pasteboard took the text,
+                    // not that the chord reached the device, so a dead channel here would answer
+                    // clipboard:write-done having pasted nothing.
+                    if (!state.touchHelper?.sendKey(KEY_CODE_MAP['KeyV'], MODIFIER_BITS['MetaLeft'])) {
+                        throw new PlatformError('Cannot press paste — no input channel to the device');
+                    }
                 };
                 // Ack only once the write (and the paste, when asked for) actually landed.
                 this.clipboardQueue(state.deviceId, write)
-                    .then(() => this.ws?.send(JSON.stringify({ type: 'clipboard:write-done', sessionId, requestId })))
+                    .then(() => this.sendMsg({ type: 'clipboard:write-done', sessionId, requestId }))
                     .catch((e) => {
                     const message = e instanceof Error ? e.message : String(e);
-                    this.ws?.send(JSON.stringify({
+                    this.sendMsg({
                         type: 'clipboard:error', sessionId, requestId, message,
                         payload: { sentinelParked: this.sentinelParked(state.deviceId) },
-                    }));
+                    });
                 });
                 break;
             }
@@ -1084,14 +1569,14 @@ export class IOSAgent {
                 const sessionId = msg.sessionId;
                 const state = this.deviceStates.get(sessionId);
                 if (!state) {
-                    this.ws?.send(JSON.stringify({ type: 'ui:tree:error', sessionId, requestId, message: 'No booted device' }));
+                    this.sendMsg({ type: 'ui:tree:error', sessionId, requestId, message: 'No booted device' });
                     break;
                 }
                 this.readUITree(state)
-                    .then((elements) => this.ws?.send(JSON.stringify({ type: 'ui:tree:response', sessionId, requestId, elements })))
+                    .then((elements) => this.sendMsg({ type: 'ui:tree:response', sessionId, requestId, elements }))
                     .catch((e) => {
                     const message = e instanceof Error ? e.message : String(e);
-                    this.ws?.send(JSON.stringify({ type: 'ui:tree:error', sessionId, requestId, message }));
+                    this.sendMsg({ type: 'ui:tree:error', sessionId, requestId, message });
                 });
                 break;
             }
@@ -1161,10 +1646,122 @@ export class IOSAgent {
      *  (`AndroidAgent.ts:1429`); these do the same. Throwing beats falling back to simctl's `booted`
      *  alias, which would quietly act on whichever simulator happened to be up. */
     async installApp(appPath) {
-        await this.simctl.installApp(this.soleDeviceId(), appPath);
+        await this.simctl.installApp(await this.soleLiveDeviceId(), appPath);
+    }
+    // ── network control (#607) ─────────────────────────────────────────────────
+    //
+    // iOS has no airplane mode to ask for, so "offline" is three mechanisms applied together — see
+    // `SimulatorNetwork`, which owns the ordering. What lives here is the wire: which device a request
+    // means, and what the session is told afterwards.
+    /** The device a session is driving, or undefined when nothing is booted. */
+    /**
+     * The session's device, **only while it is up**.
+     *
+     * `deviceStates` holds one entry per *registered* simulator, not per running one, so this used to
+     * answer for a device that was shut down — or never booted. The network path is where that costs
+     * something: a toggle after a shutdown writes the kernel rule for a dead udid, and `arm()` is the
+     * only thing that clears it, which now happens on the *next* boot of that device. Until then the
+     * host is dropping flows for nothing, and a simulator that reuses the udid comes up offline.
+     *
+     * **`booted` alone is not the check, and reading it as one is a regression this shipped once.**
+     * The flag is a cache, not the truth: `initDeviceStates` runs on `agent:registered`, which is every
+     * *reconnect* and not only the first connection, so it is `false` for a simulator that has been up
+     * the whole time. Gated on the flag alone, a relay restart left the toggle answering
+     * `No booted device` for a running device and left `network:request-state` — the message a viewer's
+     * re-join sends, which exists precisely for this moment — silently unanswered, so the control never
+     * left `waiting`.
+     *
+     * So it falls back to asking simctl and caches the answer, which is what `ackInput` already does
+     * with the same flag and for the same reason. That is also why this is async.
+     */
+    async deviceFor(sessionId) {
+        const state = this.deviceStates.get(sessionId);
+        if (!state)
+            return undefined;
+        if (state.booted)
+            return state.deviceId;
+        if (!(await this.isBooted(state.deviceId)))
+            return undefined;
+        state.booted = true;
+        return state.deviceId;
+    }
+    /**
+     * Send the current state to a session.
+     *
+     * Uncorrelated on purpose: this answers `device:ready` and a viewer's re-join, neither of which is a
+     * request anyone is waiting on. Silent with no device, for the same reason `network:error` would be
+     * addressed to nobody.
+     */
+    async reportNetworkState(sessionId) {
+        const deviceId = await this.deviceFor(sessionId);
+        if (!deviceId)
+            return;
+        this.sendMsg({ type: 'network:state', sessionId, payload: this.network.state(deviceId) });
+    }
+    /**
+     * A device that was offline stopped being enforced — tell whoever is watching it.
+     *
+     * **Uncorrelated, and it has to be**: nobody asked. `network:error` is the wrong carrier for the
+     * same reason — that type is *"a `network:set` that could not be dispatched"*, and this is not a
+     * request failing. `network:state` already supports an unsolicited frame; the viewer re-join path
+     * has been sending one since #614.
+     *
+     * **Every session holding the device, not one.** A device can sit behind two sessions, and the one
+     * that happened to make the last request is not necessarily the one whose tester is looking at it.
+     *
+     * Synchronous on purpose: `deviceFor` asks simctl before believing a device is up, and this runs
+     * from a timer while something has just gone wrong with that device. The state being reported is
+     * about the filter, not about whether the simulator is still booted.
+     */
+    reportEnforcementLost(deviceId) {
+        for (const [sessionId, state] of this.deviceStates) {
+            if (state.deviceId !== deviceId)
+                continue;
+            this.sendMsg({ type: 'network:state', sessionId, payload: this.network.state(deviceId) });
+        }
+    }
+    async handleNetworkSet(sessionId, offline, requestId) {
+        const deviceId = await this.deviceFor(sessionId);
+        if (!deviceId) {
+            this.sendMsg({
+                type: 'network:error', sessionId, requestId,
+                message: 'No booted device — boot one before changing its network.',
+            });
+            return;
+        }
+        try {
+            const payload = await this.network.setOffline(deviceId, offline);
+            this.sendMsg({ type: 'network:state', sessionId, requestId, payload });
+        }
+        catch (e) {
+            this.sendMsg({
+                type: 'network:error', sessionId, requestId,
+                message: e instanceof Error ? e.message : String(e),
+            });
+        }
+    }
+    /**
+     * The two capability entry points, which resolve their device the way every other one on this class
+     * does — **`soleDeviceState`, not the first key in the map.**
+     *
+     * `deviceStates` holds one entry per *registered* simulator and this Mac reports dozens, so
+     * `keys().next()` is whichever simctl listed first, almost always a shut-down one. That was wrong
+     * before the liveness check and became a hard failure after it: `deviceFor` answers `undefined` for
+     * a shut-down device, so both of these threw `No booted device` while a booted device sat right
+     * there. `soleDeviceState` filters on `booted` and refuses to guess between two, which is the
+     * policy this class already settled and wrote down — these were simply not using it.
+     *
+     * `deviceFor` stays for the wire path, where the caller names a session and the only open question
+     * is whether that device is up.
+     */
+    async setNetworkOffline(offline) {
+        return this.network.setOffline(await this.soleLiveDeviceId(), offline);
+    }
+    async networkState() {
+        return this.network.state(await this.soleLiveDeviceId());
     }
     async launchApp(bundleId) {
-        await this.simctl.launchApp(this.soleDeviceId(), bundleId);
+        await this.simctl.launchApp(await this.soleLiveDeviceId(), bundleId);
     }
     /** The one booted session, or undefined when there is no unambiguous answer. Callers that can
      *  reasonably do nothing (input) use this; callers that owe the user a result use
@@ -1173,15 +1770,9 @@ export class IOSAgent {
         const live = [...this.deviceStates.values()].filter((s) => s.booted);
         return live.length === 1 ? live[0] : undefined;
     }
-    soleDeviceState() {
-        // `deviceStates` holds one entry per *registered* simulator, not per running one — the relay
-        // opens a session for every device in `agent:register` and this Mac reports dozens. Taking the
-        // first entry would pick whichever simulator simctl listed first, almost always a shut-down
-        // one, which is worse than the `booted` alias it replaced: the alias at least found the device
-        // that was actually up. `booted` is set by handleDeviceBoot, so filtering on it is the liveness
-        // check `AndroidAgent` gets for free from `getSerial` (its serial map is only populated on
-        // launch).
-        const live = [...this.deviceStates.values()].filter((s) => s.booted);
+    /** The one device out of `live`, or the refusal. Factored so the async resolver below answers
+     *  ambiguity with the same words rather than its own. */
+    soleOf(live) {
         if (live.length === 0)
             throw new ValidationError('no booted device — call connect() first');
         // Refusing beats guessing: this interface has no way to say which device is meant, and picking
@@ -1191,9 +1782,73 @@ export class IOSAgent {
         }
         return live[0];
     }
-    soleDeviceId() { return this.soleDeviceState().deviceId; }
+    /**
+     * **The synchronous resolver, and `stream()` is the only caller left.**
+     *
+     * Everything else that resolves a device for a capability call awaits `soleLiveDeviceState`,
+     * which asks simctl rather than trusting `booted` — a flag `initDeviceStates` clears on every
+     * reconnect. `stream()` returns a `ReadableStream` and is part of `DeviceAgent`, so it cannot
+     * await without changing that interface across both agents.
+     *
+     * **It is deliberately left with the stale flag, and nothing was added to paper over that.** A
+     * refresh that marked every simulator simctl reports as booted was written and removed: it also
+     * marked the ones a developer had open in Simulator.app, which destroys the very thing `booted`
+     * disambiguates by — *the device this agent booted* — and made all the callers above refuse with
+     * "2 booted devices" on the common two-simulator desk. Fire-and-forget, it could also resurrect a
+     * flag a `device:shutdown` had just cleared, with no path back.
+     *
+     * That was a mechanism for a method **nothing in this repo calls**. A future caller needs the
+     * interface decision, not a guess: make `stream()` async across `DeviceAgent`, or give it an
+     * explicit device argument.
+     */
+    soleDeviceState() {
+        // `deviceStates` holds one entry per *registered* simulator, not per running one — the relay
+        // opens a session for every device in `agent:register` and this Mac reports dozens. Taking the
+        // first entry would pick whichever simulator simctl listed first, almost always a shut-down
+        // one, which is worse than the `booted` alias it replaced: the alias at least found the device
+        // that was actually up. `booted` is set by handleDeviceBoot, so filtering on it is the liveness
+        // check `AndroidAgent` gets for free from `getSerial` (its serial map is only populated on
+        // launch).
+        return this.soleOf([...this.deviceStates.values()].filter((s) => s.booted));
+    }
+    /**
+     * `soleDeviceState`, but **it asks simctl before believing that nothing is booted**.
+     *
+     * `booted` is a cache and `initDeviceStates` clears it on `agent:registered` — every reconnect,
+     * not only the first connection. So after a relay restart every flag reads false while the
+     * simulators are still running, and a resolver that trusts the cache refuses a live device until
+     * something else happens to refresh it. On the wire path that is `deviceFor`; these two entry
+     * points have no session id to work from, so without this they stay broken.
+     *
+     * Only the empty case pays for the `listDevices` call: a cache that already names a booted device
+     * is not wrong, just possibly incomplete, and the ambiguity refusal is stricter for having fewer
+     * candidates rather than looser.
+     *
+     * **Every entry point that can await now comes through here** — the network pair, `installApp`,
+     * `launchApp`, `queryUITree`, `screenshot`, `openUrl`. `stream()` cannot, and `soleDeviceState`
+     * above says what that costs and why nothing was bolted on to hide it.
+     */
+    async soleLiveDeviceState() {
+        const cached = [...this.deviceStates.values()].filter((s) => s.booted);
+        if (cached.length > 0)
+            return this.soleOf(cached);
+        const booted = new Set((await this.simctl.listDevices()).filter((d) => d.status === 'booted').map((d) => d.id));
+        const up = [...this.deviceStates.values()].filter((s) => booted.has(s.deviceId));
+        // **Ownership narrows liveness, and only when it can.** A developer with their own simulator open
+        // makes two devices live, and asking simctl alone would find both and refuse both — the reconnect
+        // case this whole path exists for. `ownedDevices` survives the reconnect and says which one is
+        // tapflow's. When it says nothing — a fresh agent process, or devices booted entirely outside
+        // tapflow — there is no ownership to apply and the refusal is the honest answer.
+        const mine = up.filter((s) => this.ownedDevices.has(s.deviceId));
+        const live = this.soleOf(mine.length > 0 ? mine : up);
+        live.booted = true; // same cache write `ackInput` makes, so the next call skips simctl
+        return live;
+    }
+    async soleLiveDeviceId() {
+        return (await this.soleLiveDeviceState()).deviceId;
+    }
     async queryUITree() {
-        const state = this.soleDeviceState();
+        const state = await this.soleLiveDeviceState();
         return this.readUITree(state);
     }
     // ── Audio output (opt-in, macOS 14.2+ Core Audio process taps) ───────────────────────────────
@@ -1289,7 +1944,7 @@ export class IOSAgent {
     }
     // async, not a bare `return`: `soleDeviceId` throws, and a synchronous throw out of a method
     // typed `Promise<T>` skips every caller's `.catch`.
-    async screenshot() { return this.simctl.screenshot(this.soleDeviceId()); }
+    async screenshot() { return this.simctl.screenshot(await this.soleLiveDeviceId()); }
     stream() {
         const first = this.soleDeviceState();
         // DeviceAgent.stream() is the platform-neutral Buffer contract; unwrap StreamFrame payloads.
@@ -1312,9 +1967,8 @@ export class IOSAgent {
         first?.touchHelper?.touchEnd();
         return Promise.resolve();
     }
-    openUrl(url) {
-        const first = this.soleDeviceState();
-        return this.simctl.openUrl(first.deviceId, url);
+    async openUrl(url) {
+        return this.simctl.openUrl(await this.soleLiveDeviceId(), url);
     }
 }
 //# sourceMappingURL=IOSAgent.js.map