@tapflowio/ios-agent 0.17.0 → 0.19.0

package/dist/IOSAgent.js

@@ -5,10 +5,26 @@ 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'];
+// 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 +34,7 @@ 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 { 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';
@@ -45,6 +61,34 @@ 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();
     // Last app launched per device (deviceId → bundleId). The XCUITest tree backend
     // queries by bundleId; kept outside DeviceState so it survives a relay reconnect
@@ -103,7 +147,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 +162,7 @@ export class IOSAgent {
                         status: d.status,
                         osVersion: d.osVersion,
                     })),
-                }));
+                });
             });
             ws.once('message', (data) => {
                 let msg;
@@ -140,7 +184,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 +234,8 @@ export class IOSAgent {
                 streamReader: null,
                 captureStreamer: null,
                 bootSeq: 0,
+                bootAbandon: new Map(),
+                bootsInFlight: new Set(),
                 orientation: 'portrait',
                 loadedChrome: null,
                 softKeyboardVisible: false,
@@ -208,6 +261,7 @@ export class IOSAgent {
             this.resourcesTimer = null;
         }
         for (const state of this.deviceStates.values()) {
+            this.bumpBootSeq(state, 'relay-lost');
             this.cleanupDeviceState(state);
         }
         this.deviceStates.clear();
@@ -226,6 +280,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 +315,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,7 +325,7 @@ export class IOSAgent {
                 slotsTotal,
                 reportedAt: Date.now(),
             },
-        }));
+        });
     }
     cleanupDeviceState(state) {
         void state.streamReader?.cancel();
@@ -285,38 +346,46 @@ 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;
         let stream;
         if (this.intervalMs !== undefined) {
             state.captureStreamer = null;
-            stream = new MjpegStreamer(this.simctl, this.intervalMs).start();
+            stream = new MjpegStreamer(this.simctl, state.deviceId, this.intervalMs).start();
         }
         else {
             const maxSize = pickMaxSize({
@@ -324,7 +393,7 @@ export class IOSAgent {
                 external: state.external,
                 override: process.env.TAPFLOW_IOS_MAX_SIZE ?? process.env.TAPFLOW_MAX_SIZE,
             });
-            const capture = new ScreenCaptureStreamer(this.fps, state.deviceId, useH264 ? 'h264' : 'jpeg', maxSize);
+            const capture = new ScreenCaptureStreamer(state.deviceId, this.fps, useH264 ? 'h264' : 'jpeg', maxSize);
             state.captureStreamer = capture;
             stream = capture.start();
         }
@@ -398,50 +467,174 @@ 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}`);
             if (fullErase) {
-                await this.simctl.erase(deviceId);
+                // `simctl erase` only accepts a shut-down device, and a device is often already running —
+                // it survives agent restarts and sessions that ended without a clean shutdown. Without this
+                // the boot fails outright (#439).
+                //
+                // Anything that is not `shutdown` gets the shutdown, not just `booted`: `toDeviceStatus`
+                // collapses `Booting` / `Shutting Down` / `Creating` into `unknown`, and `erase` refuses
+                // every one of them. Re-picking a device while its `device:shutdown` is still draining
+                // lands exactly there. `SimctlWrapper.shutdown` already tolerates an off device, so
+                // widening the condition costs nothing.
+                //
+                // This makes an unwanted reset *succeed* rather than fail, so it is only safe alongside the
+                // dashboard change that consumes the toggle after one use. The erase failing is what used
+                // to stand between a stale toggle and a wiped device.
+                if (target.status !== 'shutdown')
+                    await this.simctl.shutdown(deviceId);
+                // 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) {
+                    this.abandonBoot(state, seq, sessionId, requestId);
+                    return;
+                }
+                try {
+                    await this.simctl.erase(deviceId);
+                }
+                catch (err) {
+                    // We powered the device off to make the erase possible. If the erase then fails, leaving
+                    // it off strands the tester with a dead device on top of the error message, so put it
+                    // back the way we found it and report the original failure.
+                    //
+                    // `=== 'booted'`, deliberately narrower than the `!== 'shutdown'` above: that one asks
+                    // "does this need shutting down", this one asks "did we take it down". `unknown` covers
+                    // `Shutting Down` (someone else was already stopping it) and `Creating` (never ran) —
+                    // booting either would not be putting it back.
+                    //
+                    // The seq check matters as much: erase takes seconds, and a shutdown arriving mid-flight
+                    // bumps bootSeq. Recovering then would power a device back up right after the tester
+                    // asked for it to stop — and the throw below is swallowed by the outer catch on the same
+                    // seq mismatch, so nothing would say why.
+                    if (seq === state.bootSeq && target.status === 'booted') {
+                        await this.simctl.boot(deviceId).catch(() => { });
+                    }
+                    throw err;
+                }
                 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 });
+            // 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);
@@ -450,7 +643,7 @@ 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 } }));
+            this.sendMsg({ type: 'device:ready', sessionId, requestId, payload: { deviceId } });
             // 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.
@@ -459,10 +652,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
@@ -480,11 +685,11 @@ 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');
         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
@@ -499,11 +704,12 @@ export class IOSAgent {
         this.uiTreeReader.stopIfDevice(deviceId);
         try {
             await this.simctl.shutdown(deviceId);
-            this.ws?.send(JSON.stringify({
+            this.sendMsg({
                 type: 'device:shutdown-done',
                 sessionId,
+                requestId,
                 payload: { deviceId },
-            }));
+            });
         }
         catch (e) {
             const message = e instanceof Error ? e.message : String(e);
@@ -537,14 +743,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 {
@@ -560,44 +841,68 @@ 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;
-                this.installBuild(filePath, bundleId)
-                    .then(() => this.ws?.send(JSON.stringify({ type: 'app:install-done', 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) {
+                    respond({ type: 'app:install-error', message: 'No booted device' });
+                    break;
+                }
+                this.installBuild(installState.deviceId, filePath, bundleId)
+                    .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);
-                this.simctl.launchApp(bundleId)
+                if (!launchState) {
+                    respond({ type: 'app:launch-error', message: 'No booted device' });
+                    break;
+                }
+                this.simctl.launchApp(launchState.deviceId, bundleId)
                     .then(() => {
                     // Track the foreground app so ui:tree:request can query it via XCUITest.
-                    if (launchState)
-                        this.lastBundleIds.set(launchState.deviceId, bundleId);
+                    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;
             }
@@ -619,11 +924,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': {
@@ -644,11 +957,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': {
@@ -675,24 +993,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
@@ -709,92 +1030,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;
             }
@@ -802,33 +1186,48 @@ export class IOSAgent {
                 const raw = msg;
                 const { requestId, format } = raw;
                 const sessionId = msg.sessionId;
-                this.simctl.screenshot(format ?? 'png')
-                    .then((buf) => this.ws?.send(JSON.stringify({
+                const shotState = this.deviceStates.get(sessionId);
+                if (!shotState) {
+                    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
+                // read `screenshot(format ?? 'png')`, and adding a leading `udid: string` did NOT make it a
+                // 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.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(bundleId)
-                    .then(() => this.ws?.send(JSON.stringify({ type: 'app:clear-state-done', sessionId })))
+                this.simctl.clearAppData(state.deviceId, bundleId)
+                    .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;
             }
@@ -837,14 +1236,22 @@ export class IOSAgent {
             // await hideSoftwareKeyboard first), and reading too early returns the PREVIOUS
             // pasteboard — a stale value the user would never notice.
             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 ?? {});
@@ -852,7 +1259,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) } });
@@ -965,23 +1372,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 () => {
@@ -1006,17 +1421,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;
             }
@@ -1026,14 +1446,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;
             }
@@ -1054,15 +1474,15 @@ export class IOSAgent {
      * 직접 설치. tar 추출은 실행 비트·심볼릭 링크를 보존하고(재압축이 아니라 네이티브 보관),
      * macOS tar(libarchive)가 path traversal·symlink 탈출을 기본 차단한다. 완료 후 임시 정리.
      */
-    async installBuild(filePath, bundleId) {
+    async installBuild(udid, filePath, bundleId) {
         if (bundleId) {
-            await this.simctl.uninstallApp(bundleId).catch(() => { });
+            await this.simctl.uninstallApp(udid, bundleId).catch(() => { });
         }
         const lower = filePath.toLowerCase();
         const isTar = lower.endsWith('.tar.gz') || lower.endsWith('.tgz');
         const isZip = lower.endsWith('.zip');
         if (!isTar && !isZip) {
-            return this.simctl.installApp(filePath);
+            return this.simctl.installApp(udid, filePath);
         }
         const tmpDir = path.join(tmpdir(), `tapflow-install-${randomUUID()}`);
         fs.mkdirSync(tmpDir, { recursive: true });
@@ -1087,7 +1507,7 @@ export class IOSAgent {
             if (!appDir) {
                 throw new ValidationError('.app 디렉토리를 찾을 수 없습니다. iphonesimulator 로 빌드한 .app 을 .app.zip 또는 .tar.gz 로 업로드하세요.');
             }
-            await this.simctl.installApp(path.join(tmpDir, appDir));
+            await this.simctl.installApp(udid, path.join(tmpDir, appDir));
         }
         finally {
             fs.rmSync(tmpDir, { recursive: true, force: true });
@@ -1097,12 +1517,45 @@ export class IOSAgent {
     listDevices() { return this.simctl.listDevices(); }
     boot(deviceId) { return this.simctl.boot(deviceId); }
     shutdown(deviceId) { return this.simctl.shutdown(deviceId); }
-    installApp(appPath) { return this.simctl.installApp(appPath); }
-    async launchApp(bundleId) { await this.simctl.launchApp(bundleId); }
-    async queryUITree() {
-        const state = this.deviceStates.values().next().value;
-        if (!state)
+    /** The `DeviceAgent` interface has no device parameter — it predates multi-session agents and is
+     *  shared with Android, so widening it would be a breaking change for every implementation and
+     *  caller. `AndroidAgent` resolves the single live session internally instead
+     *  (`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);
+    }
+    async launchApp(bundleId) {
+        await this.simctl.launchApp(this.soleDeviceId(), 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
+     *  `soleDeviceState`, which throws instead. */
+    liveDeviceState() {
+        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);
+        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
+        // one silently is the whole defect being fixed here.
+        if (live.length > 1) {
+            throw new ValidationError(`${live.length} booted devices — this entry point cannot choose between them`);
+        }
+        return live[0];
+    }
+    soleDeviceId() { return this.soleDeviceState().deviceId; }
+    async queryUITree() {
+        const state = this.soleDeviceState();
         return this.readUITree(state);
     }
     // ── Audio output (opt-in, macOS 14.2+ Core Audio process taps) ───────────────────────────────
@@ -1196,35 +1649,33 @@ export class IOSAgent {
             // stream cancelled or ws closed — expected on teardown/restart
         }
     }
-    screenshot() { return this.simctl.screenshot(); }
+    // 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()); }
     stream() {
-        const first = this.deviceStates.values().next().value;
-        if (!first)
-            throw new ValidationError('no booted device — call connect() first');
+        const first = this.soleDeviceState();
         // DeviceAgent.stream() is the platform-neutral Buffer contract; unwrap StreamFrame payloads.
-        return new ScreenCaptureStreamer(this.fps, first.deviceId).start()
+        return new ScreenCaptureStreamer(first.deviceId, this.fps).start()
             .pipeThrough(new TransformStream({
             transform(frame, controller) { controller.enqueue(frame.payload); },
         }));
     }
     touchStart(x, y) {
-        const first = this.deviceStates.values().next().value;
+        const first = this.liveDeviceState();
         first?.touchHelper?.touchStart(x, y);
     }
     touchMove(x, y) {
-        const first = this.deviceStates.values().next().value;
+        const first = this.liveDeviceState();
         first?.touchHelper?.touchMove(x, y);
         return Promise.resolve();
     }
     touchEnd() {
-        const first = this.deviceStates.values().next().value;
+        const first = this.liveDeviceState();
         first?.touchHelper?.touchEnd();
         return Promise.resolve();
     }
     openUrl(url) {
-        const first = this.deviceStates.values().next().value;
-        if (!first)
-            throw new ValidationError('no booted device — call connect() first');
+        const first = this.soleDeviceState();
         return this.simctl.openUrl(first.deviceId, url);
     }
 }