@tapflowio/ios-agent 0.16.0 → 0.18.0

package/dist/IOSAgent.js

@@ -7,6 +7,8 @@ import { spawnSync } from 'child_process';
 import { WebSocket } from 'ws';
 import { createLogger, PlatformError, ValidationError } 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'];
 // 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.
@@ -16,7 +18,8 @@ export const IOS_BUTTON_ALIASES = {
     volume_down: 'volume-down',
 };
 import { createResourceSampler, registerStreamWs, disableNagle, createKeyframeAwareSender, pickMaxSize, createRateLimitedDropWarn, createThroughputSampler, createSleepBlocker, getMachineId, isLocalhostWss, DEFAULT_BACKPRESSURE_BYTES, writeEnvelopeHeader, rewriteLowLatencySpsInFrame, CODEC_JPEG, CODEC_H264, CODEC_AUDIO, sendAudioYieldingToVideo, } from '@tapflowio/agent-core/utils';
-import { SimctlWrapper, isDeviceMissingError } from './SimctlWrapper.js';
+import { SimctlWrapper, isDeviceMissingError, ClipboardTooLargeError } 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';
 import { ensureHelperApp, launchAudioHelper, isAudioSupported } from '@tapflowio/audiotap-helper';
@@ -103,6 +106,9 @@ export class IOSAgent {
                 ws.send(JSON.stringify({
                     type: 'agent:register',
                     platform: 'ios',
+                    // Lets a viewer tell a clipboard-capable agent from one that predates the
+                    // feature, instead of inferring it from silence. See agent-core AgentCapability.
+                    capabilities: AGENT_CAPABILITIES,
                     agentId: getMachineId(),
                     agentName: os.hostname(),
                     devices: devices.map((d) => ({
@@ -172,6 +178,7 @@ export class IOSAgent {
                 sessionId,
                 deviceId,
                 touchHelper: null,
+                booted: false,
                 streamWs: null,
                 streamReader: null,
                 captureStreamer: null,
@@ -273,6 +280,7 @@ export class IOSAgent {
         state.audioPids = null;
         state.touchHelper?.stop();
         state.touchHelper = null;
+        state.booted = false;
         state.streamWs?.close();
         state.streamWs = null;
     }
@@ -308,7 +316,7 @@ export class IOSAgent {
         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({
@@ -316,7 +324,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();
         }
@@ -405,6 +413,7 @@ export class IOSAgent {
         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 }));
@@ -416,7 +425,48 @@ export class IOSAgent {
             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)
+                    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') {
@@ -440,6 +490,7 @@ export class IOSAgent {
             // — never blocks/affects the video path.
             if (this.audioEnabled())
                 this.startAudioCapture(state, streamWs, deviceId);
+            state.booted = true;
             this.ws?.send(JSON.stringify({ type: 'device:ready', sessionId, 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.
@@ -480,6 +531,7 @@ export class IOSAgent {
         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.lastBundleIds.delete(deviceId);
@@ -499,6 +551,51 @@ export class IOSAgent {
             logger.error('shutdown failed:', message);
         }
     }
+    // Lazily set up the touch channel: a reconnect re-issues the session with touchHelper=null while the sim stays booted, so input self-heals without a fresh device:boot. Sync so a tap's start+end stay paired (async would drop touchEnd → stuck finger).
+    ensureTouchHelper(state) {
+        if (state.touchHelper)
+            return;
+        state.touchHelper = new TouchHelper(state.deviceId);
+        state.touchHelper.start();
+    }
+    // Clipboard work parks a sentinel on the device while it waits, so two operations on the same
+    // device must not interleave — each would read the other's marker instead of the real
+    // clipboard. Keyed by device, not session: several sessions (and MCP) can address one device.
+    clipboardQueue = createKeyedSerialQueue();
+    // Device-scoped, not operation-scoped. Several sessions (and MCP) can address one simulator,
+    // so an operation that fails before parking anything may still be answering while ANOTHER
+    // holds a marker down. The viewer decides from this whether pressing the plain chord is safe,
+    // and that chord travels as `input:key` — outside this queue — so the answer has to describe
+    // the device rather than the caller.
+    parkedSentinels = new Map();
+    markSentinel(deviceId, delta) {
+        const n = (this.parkedSentinels.get(deviceId) ?? 0) + delta;
+        if (n > 0)
+            this.parkedSentinels.set(deviceId, n);
+        else
+            this.parkedSentinels.delete(deviceId);
+    }
+    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)
+            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' }));
+    }
+    async isBooted(deviceId) {
+        try {
+            const devices = await this.simctl.listDevices();
+            return devices.find((d) => d.id === deviceId)?.status === 'booted';
+        }
+        catch {
+            return false;
+        }
+    }
     handleRelayMessage(msg) {
         switch (msg.type) {
             case 'device:boot': {
@@ -518,7 +615,12 @@ export class IOSAgent {
             case 'app:install': {
                 const { filePath, bundleId } = msg.payload;
                 const sessionId = msg.sessionId;
-                this.installBuild(filePath, bundleId)
+                const installState = this.deviceStates.get(sessionId);
+                if (!installState) {
+                    this.ws?.send(JSON.stringify({ type: 'app:install-error', sessionId, message: 'No booted device' }));
+                    break;
+                }
+                this.installBuild(installState.deviceId, filePath, bundleId)
                     .then(() => this.ws?.send(JSON.stringify({ type: 'app:install-done', sessionId })))
                     .catch((e) => {
                     const message = e instanceof Error ? e.message : String(e);
@@ -530,11 +632,14 @@ export class IOSAgent {
                 const { bundleId } = msg.payload;
                 const sessionId = msg.sessionId;
                 const launchState = this.deviceStates.get(sessionId);
-                this.simctl.launchApp(bundleId)
+                if (!launchState) {
+                    this.ws?.send(JSON.stringify({ type: 'app:launch-error', sessionId, 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 }));
@@ -547,12 +652,11 @@ export class IOSAgent {
             }
             case 'input:touch:start': {
                 const state = this.deviceStates.get(msg.sessionId);
-                if (!state?.touchHelper) {
-                    logger.error('touch:start — touchHelper not ready');
+                if (!state)
                     break;
-                }
+                this.ensureTouchHelper(state);
                 const { x, y } = msg.payload;
-                state.touchHelper.touchStart(x, y);
+                state.touchHelper?.touchStart(x, y);
                 break;
             }
             case 'input:touch:move': {
@@ -565,15 +669,19 @@ export class IOSAgent {
             }
             case 'input:touch:end': {
                 const state = this.deviceStates.get(msg.sessionId);
-                state?.touchHelper?.touchEnd();
+                if (!state)
+                    break;
+                state.touchHelper?.touchEnd();
+                void this.ackInput(state, state.touchHelper !== null); // terminal of a tap/swipe → ack the gesture
                 break;
             }
             case 'input:pinch:start': {
                 const state = this.deviceStates.get(msg.sessionId);
-                if (!state?.touchHelper)
+                if (!state)
                     break;
+                this.ensureTouchHelper(state);
                 const { f0, f1 } = msg.payload;
-                state.touchHelper.pinchStart(f0.x, f0.y, f1.x, f1.y);
+                state.touchHelper?.pinchStart(f0.x, f0.y, f1.x, f1.y);
                 break;
             }
             case 'input:pinch:move': {
@@ -586,9 +694,10 @@ export class IOSAgent {
             }
             case 'input:pinch:end': {
                 const state = this.deviceStates.get(msg.sessionId);
-                if (!state?.touchHelper)
+                if (!state)
                     break;
-                state.touchHelper.pinchEnd();
+                state.touchHelper?.pinchEnd();
+                void this.ackInput(state, state.touchHelper !== null);
                 break;
             }
             case 'input:rotate': {
@@ -628,6 +737,8 @@ export class IOSAgent {
             case 'input:type': {
                 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' }));
@@ -651,7 +762,9 @@ export class IOSAgent {
                 };
                 // Ack on completion so a following input step (e.g. pressKey Enter) is
                 // only sent after the paste has actually landed.
-                doType()
+                // 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 })))
                     .catch((e) => {
                     const message = e instanceof Error ? e.message : String(e);
@@ -662,12 +775,15 @@ export class IOSAgent {
             }
             case 'input:key': {
                 const state = this.deviceStates.get(msg.sessionId);
-                if (!state?.touchHelper)
+                if (!state)
                     break;
+                this.ensureTouchHelper(state);
                 const { code, modifiers } = msg.payload;
                 const usage = KEY_CODE_MAP[code];
-                if (usage === undefined)
+                if (usage === undefined) {
+                    this.ws?.send(JSON.stringify({ type: 'input:error', sessionId: msg.sessionId, message: `unknown key code: ${code}` }));
                     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).
@@ -680,14 +796,16 @@ export class IOSAgent {
                     });
                 }
                 else {
-                    state.touchHelper.sendKey(usage, modifiers ?? 0);
+                    state.touchHelper?.sendKey(usage, modifiers ?? 0);
                 }
+                void this.ackInput(state, state.touchHelper !== null);
                 break;
             }
             case 'input:button': {
                 const state = this.deviceStates.get(msg.sessionId);
-                if (!state?.touchHelper)
+                if (!state)
                     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
@@ -697,19 +815,20 @@ export class IOSAgent {
                     // 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);
+                        state.touchHelper?.pressLegacyButton(0);
                 }
                 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);
+                            state.touchHelper?.pressButtonDown(btn.usagePage, btn.usage);
                         else if (phase === 'up')
-                            state.touchHelper.pressButtonUp(btn.usagePage, btn.usage);
+                            state.touchHelper?.pressButtonUp(btn.usagePage, btn.usage);
                         else
-                            state.touchHelper.pressButton(btn.usagePage, btn.usage);
+                            state.touchHelper?.pressButton(btn.usagePage, btn.usage);
                     }
                 }
+                void this.ackInput(state, state.touchHelper !== null);
                 break;
             }
             case 'open-url': {
@@ -732,7 +851,16 @@ export class IOSAgent {
                 const raw = msg;
                 const { requestId, format } = raw;
                 const sessionId = msg.sessionId;
-                this.simctl.screenshot(format ?? 'png')
+                const shotState = this.deviceStates.get(sessionId);
+                if (!shotState) {
+                    this.ws?.send(JSON.stringify({ 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.ws?.send(JSON.stringify({
                     type: 'screenshot:done',
                     sessionId,
@@ -754,7 +882,7 @@ export class IOSAgent {
                     this.ws?.send(JSON.stringify({ type: 'app:clear-state-error', sessionId, message: !state ? 'No booted device' : 'bundleId missing' }));
                     break;
                 }
-                this.simctl.clearAppData(bundleId)
+                this.simctl.clearAppData(state.deviceId, bundleId)
                     .then(() => this.ws?.send(JSON.stringify({ type: 'app:clear-state-done', sessionId })))
                     .catch((e) => {
                     const message = e instanceof Error ? e.message : String(e);
@@ -762,6 +890,194 @@ export class IOSAgent {
                 });
                 break;
             }
+            // Clipboard bridge. The chord is pressed HERE rather than by the viewer: the browser
+            // cannot know when the key actually lands (a visible software keyboard makes this path
+            // await hideSoftwareKeyboard first), and reading too early returns the PREVIOUS
+            // pasteboard — a stale value the user would never notice.
+            case 'clipboard:read': {
+                const { requestId } = msg;
+                const sessionId = msg.sessionId;
+                const state = this.deviceStates.get(sessionId);
+                if (!state) {
+                    this.ws?.send(JSON.stringify({
+                        type: 'clipboard:error', sessionId, requestId, message: 'No booted device',
+                        payload: { sentinelParked: false },
+                    }));
+                    break;
+                }
+                const { press } = (msg.payload ?? {});
+                // Answering is separate from cleaning up. The restore below runs in a `finally`, which
+                // 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 read = async () => {
+                    if (!press) {
+                        respond({ type: 'clipboard:data', payload: { text: await this.simctl.getPasteboard(state.deviceId) } });
+                        return;
+                    }
+                    this.ensureTouchHelper(state);
+                    if (!state.touchHelper)
+                        throw new PlatformError('Cannot press copy — no input channel to the device');
+                    if (state.softKeyboardVisible) {
+                        state.softKeyboardVisible = false;
+                        await this.simctl.hideSoftwareKeyboard(state.deviceId).catch(() => { });
+                    }
+                    // Overwrite the pasteboard with a value only we could have written, then press the
+                    // chord and wait for it to change. Without this there is no way to tell "the app
+                    // copied" from "the app has not copied yet" — a fixed delay guesses, and guessing
+                    // wrong hands the PREVIOUS clipboard to the user with no error. The sentinel also
+                    // covers re-copying the identical text, where a plain value-change watch never fires.
+                    // Read the original first. If we cannot (a hung simctl, or a pasteboard past
+                    // maxBuffer), do NOT continue: parking a sentinel we are unable to undo would
+                    // destroy whatever the user had on the device clipboard.
+                    const raw = await this.simctl.getPasteboard(state.deviceId);
+                    // Never restore someone else's marker as if it were the user's text.
+                    const before = isSentinel(raw) ? '' : raw;
+                    const sentinel = `${SENTINEL_PREFIX}${randomUUID()}`;
+                    let copied = null;
+                    // Counted before the call: setPasteboard can reject after the device took the value,
+                    // so anything from here until the restore has to be treated as parked.
+                    this.markSentinel(state.deviceId, 1);
+                    try {
+                        // Inside the try: if this rejects *after* the device applied it, the restore below
+                        // still runs. Outside, a leaked sentinel would sit on the device permanently.
+                        await this.simctl.setPasteboard(state.deviceId, sentinel);
+                        // `pbcopy` exiting means the write was accepted, not that the pasteboard shows it
+                        // yet. Pressing before it does lets the first poll read the PRE-sentinel value,
+                        // decide it is not a sentinel, and return it as "what the app copied" — the exact
+                        // staleness this whole mechanism exists to prevent. Mirrors the Android read path.
+                        const applied = Date.now() + CLIPBOARD_WRITE_DEADLINE_MS;
+                        while ((await this.simctl.getPasteboard(state.deviceId)) !== sentinel) {
+                            if (Date.now() >= applied)
+                                throw new PlatformError('The device clipboard did not respond');
+                            await new Promise((r) => setTimeout(r, CLIPBOARD_POLL_MS));
+                        }
+                        state.touchHelper.sendKey(KEY_CODE_MAP[press === 'cut' ? 'KeyX' : 'KeyC'], MODIFIER_BITS['MetaLeft']);
+                        const deadline = Date.now() + CLIPBOARD_COPY_DEADLINE_MS;
+                        do {
+                            let now;
+                            try {
+                                now = await this.simctl.getPasteboard(state.deviceId);
+                            }
+                            catch (e) {
+                                // ONLY the size ceiling means the app copied — we just cannot carry it — so the
+                                // restore below must be skipped or it would overwrite the very text the user
+                                // copied. Every other failure here (a hung or timed-out pbpaste) says nothing
+                                // about the device, and skipping the restore for those left the sentinel parked
+                                // for good: the user's clipboard destroyed, and a zero-width marker pasted into
+                                // the app under test. Android reaches the same two states, by assigning `copied`
+                                // before it throws for the over-sized case and not otherwise.
+                                if (e instanceof ClipboardTooLargeError)
+                                    copied = '';
+                                throw e;
+                            }
+                            // A sentinel is never a copy result — ours means "not yet", any other means a
+                            // concurrent operation slipped in and its marker must not be handed to the user.
+                            if (!isSentinel(now)) {
+                                copied = now;
+                                respond({ type: 'clipboard:data', payload: { text: now } });
+                                return;
+                            }
+                            await new Promise((r) => setTimeout(r, CLIPBOARD_POLL_MS));
+                        } while (Date.now() < deadline);
+                        throw new PlatformError('The device did not copy anything — is something selected?');
+                    }
+                    catch (e) {
+                        // Reply here rather than letting this propagate: a rejection would surface only
+                        // after `finally` had finished restoring, putting that window inside the round trip.
+                        respond({
+                            type: 'clipboard:error', message: e instanceof Error ? e.message : String(e),
+                            // A sentinel may be on the device: setPasteboard can reject after the device took
+                            // it. The viewer must not press the chord — the restore would overwrite the copy.
+                            payload: { sentinelParked: this.sentinelParked(state.deviceId) },
+                        });
+                    }
+                    finally {
+                        // Only restore when the copy never happened; otherwise this would overwrite the
+                        // value we just captured. A leaked sentinel would be worse than the original bug.
+                        // Wait for the restore to be visible, not merely accepted: releasing the queue early
+                        // lets the next operation read the sentinel as "the original", which then becomes ''
+                        // and wipes the user's device clipboard. Mirrors the Android read path.
+                        if (copied === null) {
+                            await this.simctl.setPasteboard(state.deviceId, before).catch(() => { });
+                            const restored = Date.now() + CLIPBOARD_RESTORE_DEADLINE_MS;
+                            while ((await this.simctl.getPasteboard(state.deviceId).catch(() => before)) !== before) {
+                                if (Date.now() >= restored)
+                                    break; // best effort; the error is already going out
+                                await new Promise((r) => setTimeout(r, CLIPBOARD_POLL_MS));
+                            }
+                        }
+                        this.markSentinel(state.deviceId, -1);
+                    }
+                };
+                // `read` answers for itself once the sentinel is in play. This catches only what can
+                // throw BEFORE that — the press-less branch, a missing input channel, and the failed
+                // read of the original — so nothing is parked and the viewer's chord fallback is safe.
+                this.clipboardQueue(state.deviceId, read).catch((e) => {
+                    respond({
+                        type: 'clipboard:error', message: e instanceof Error ? e.message : String(e),
+                        payload: { sentinelParked: this.sentinelParked(state.deviceId) },
+                    });
+                });
+                break;
+            }
+            case 'clipboard:write': {
+                const { requestId } = msg;
+                const sessionId = msg.sessionId;
+                const state = this.deviceStates.get(sessionId);
+                if (!state) {
+                    this.ws?.send(JSON.stringify({
+                        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({
+                        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 () => {
+                    const wanted = text ?? '';
+                    await this.simctl.setPasteboard(state.deviceId, wanted);
+                    if (!pasteAfter)
+                        return;
+                    this.ensureTouchHelper(state);
+                    if (!state.touchHelper)
+                        throw new PlatformError('Cannot press paste — no input channel to the device');
+                    // Confirm the pasteboard really holds it before pressing paste; otherwise the device
+                    // could paste whatever was there before. (On Android the same call is documented as
+                    // asynchronous, so this is not iOS paranoia — it is the same failure on both sides.)
+                    const deadline = Date.now() + CLIPBOARD_WRITE_DEADLINE_MS;
+                    while ((await this.simctl.getPasteboard(state.deviceId).catch(() => null)) !== wanted) {
+                        if (Date.now() >= deadline)
+                            throw new PlatformError('The device clipboard did not accept the text');
+                        await new Promise((r) => setTimeout(r, CLIPBOARD_POLL_MS));
+                    }
+                    // Same guard as input:key — skipping it desyncs the hardware keyboard context.
+                    if (state.softKeyboardVisible) {
+                        state.softKeyboardVisible = false;
+                        await this.simctl.hideSoftwareKeyboard(state.deviceId).catch(() => { });
+                    }
+                    state.touchHelper.sendKey(KEY_CODE_MAP['KeyV'], MODIFIER_BITS['MetaLeft']);
+                };
+                // 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 })))
+                    .catch((e) => {
+                    const message = e instanceof Error ? e.message : String(e);
+                    this.ws?.send(JSON.stringify({
+                        type: 'clipboard:error', sessionId, requestId, message,
+                        payload: { sentinelParked: this.sentinelParked(state.deviceId) },
+                    }));
+                });
+                break;
+            }
             case 'ui:tree:request': {
                 const raw = msg;
                 const { requestId } = raw;
@@ -796,15 +1112,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 });
@@ -829,7 +1145,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 });
@@ -839,12 +1155,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) ───────────────────────────────
@@ -938,35 +1287,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);
     }
 }