@tapflowio/ios-agent 0.18.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,31 +346,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 +467,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 +569,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 +597,44 @@ 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 });
+            // 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 +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.
@@ -500,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
@@ -521,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
@@ -540,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);
@@ -578,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 {
@@ -601,39 +841,55 @@ 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)
@@ -642,11 +898,11 @@ export class IOSAgent {
                     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 +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': {
@@ -693,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': {
@@ -724,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
@@ -758,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;
             }
@@ -853,7 +1188,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 +1196,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;
             }
@@ -895,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 ?? {});
@@ -910,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) } });
@@ -1023,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 () => {
@@ -1064,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;
             }
@@ -1084,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;
             }