@tapflowio/ios-agent 0.28.1 → 0.30.0

package/dist/IOSAgent.js

@@ -6,7 +6,10 @@ import { randomUUID } from 'crypto';
 import { spawn } from 'child_process';
 import { WebSocket } from 'ws';
 import { createLogger, PlatformError, ValidationError, bootAbandonMessage, BOOT_NO_SESSION_STATE, SHUTDOWN_NO_SESSION_STATE, downloadBuild } from '@tapflowio/agent-core';
+import { appliedKeys, compactLaunchOptions, launchOptionsProblem } from '@tapflowio/protocol/launch';
 const logger = createLogger('ios-agent');
+/** The run reset's pasteboard step, the wait for the clipboard queue included; one step's bound like the others. */
+const RUN_RESET_PASTEBOARD_TIMEOUT_MS = 10_000;
 // Typed so a typo cannot ship silently — the viewer gates the whole clipboard bridge on this.
 // `full-reset` is honoured in `handleDeviceBoot`, which shuts a running device down before
 // `simctl erase` (which refuses anything but a shut-down device) and boots it again.
@@ -14,7 +17,7 @@ const logger = createLogger('ios-agent');
 // actually took is per device and per app, and `network:state.available` carries that — the split the
 // protocol documents. Added last, after the handler and the boot-time arming, because the string on
 // its own is what puts a control on screen.
-const AGENT_CAPABILITIES = ['clipboard', 'full-reset', 'network-control', 'build-download'];
+const AGENT_CAPABILITIES = ['clipboard', 'full-reset', 'network-control', 'build-download', 'launch-options', 'launch-env'];
 // 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
@@ -39,11 +42,11 @@ export const IOS_BUTTON_ALIASES = {
     volume_up: 'volume-up',
     volume_down: 'volume-down',
 };
-import { createResourceSampler, registerStreamWs, disableNagle, createKeyframeAwareSender, pickMaxSize, createRateLimitedDropWarn, createThroughputSampler, createSleepBlocker, acquireLoopStallWatch, describeRelayLoss, getMachineId, isLocalhostWss, DEFAULT_BACKPRESSURE_BYTES, writeEnvelopeHeader, rewriteLowLatencySpsInFrame, CODEC_JPEG, CODEC_H264, CODEC_AUDIO, sendAudioYieldingToVideo, } from '@tapflowio/agent-core/utils';
+import { createResourceSampler, registerStreamWs, disableNagle, createKeyframeAwareSender, pickMaxSize, createRateLimitedDropWarn, createThroughputSampler, createSleepBlocker, acquireLoopStallWatch, describeRelayLoss, getMachineId, sameServiceTier, resetApps, runResetSteps, RUN_RESET_BUDGET_MS, isLocalhostWss, DEFAULT_BACKPRESSURE_BYTES, writeEnvelopeHeader, rewriteLowLatencySpsInFrame, CODEC_JPEG, CODEC_H264, CODEC_AUDIO, sendAudioYieldingToVideo, } from '@tapflowio/agent-core/utils';
 import { SimctlWrapper, isDeviceMissingError, ClipboardTooLargeError, firstLine, launchFailureReason } from './SimctlWrapper.js';
 import { SimulatorNetwork } from './SimulatorNetwork.js';
 import { LeanStore } from './LeanStore.js';
-import { LEAN_LABELS } from './leanLabels.js';
+import { MANAGED_LABELS, labelsFor } from './serviceTiers.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';
@@ -156,6 +159,7 @@ export class IOSAgent {
      *  falling back to nothing would blank a form factor it already had until the next reconnect. */
     formFactors = new Map();
     resourcesTimer = null;
+    resourcesInFlight = null;
     resources = createResourceSampler();
     _stopping = false;
     _reconnectTimer = null;
@@ -182,7 +186,7 @@ export class IOSAgent {
         // reason, as `sleepBlocker` below.
         this.lean = options.lean ?? false;
         // Never the host's real store under vitest, for the reason given for `network` just below.
-        this.leanStore = options.leanStore ?? new LeanStore(process.env.VITEST ? path.join(tmpdir(), 'tapflow-no-lean-store') : undefined);
+        this.leanStore = options.leanStore ?? new LeanStore(process.env.VITEST ? path.join(tmpdir(), 'tapflow-no-lean-store') : undefined, MANAGED_LABELS);
         this.network = options.network ?? new SimulatorNetwork(this.simctl, process.env.VITEST ? { filterHostBinary: path.join(tmpdir(), 'tapflow-no-filter-host') } : {});
         // **Wired here rather than in the constructor call above, and the difference is coverage.** An
         // injected `SimulatorNetwork` — which is what every test uses — would otherwise never carry the
@@ -264,6 +268,7 @@ export class IOSAgent {
                         status: d.status,
                         osVersion: d.osVersion,
                         formFactor: d.typeId ? formFactors.get(d.typeId) : undefined,
+                        serviceTier: this.reportedTier(d),
                     })),
                 });
             });
@@ -298,8 +303,8 @@ export class IOSAgent {
                         }
                         catch { /* ignore malformed */ }
                     });
-                    this.reportResources();
-                    this.resourcesTimer = setInterval(() => this.reportResources(), 5000);
+                    void this.reportResources();
+                    this.resourcesTimer = setInterval(() => { void this.reportResources(); }, 5000);
                     this.lastPingAt = null;
                     this.lastSocketError = undefined;
                     ws.on('ping', () => { this.lastPingAt = Date.now(); });
@@ -431,23 +436,41 @@ export class IOSAgent {
             });
         }, delay);
     }
-    reportResources() {
-        if (!this.ws || this.ws.readyState !== WebSocket.OPEN)
+    /** Samples off the event loop, then reports. One sample at a time per socket, so a slow one (bounded by its
+     *  1 s timeout) is not stacked by the next tick; keyed by socket, so a reconnect is not skipped behind the
+     *  old socket's sample. Slots and the clock are read after the sample, when the report leaves. */
+    async reportResources() {
+        const ws = this.ws;
+        if (!ws || ws.readyState !== WebSocket.OPEN || this.resourcesInFlight === ws)
             return;
-        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.sendOn(this.ws, {
-            type: 'agent:resources',
-            resources: {
-                cpuPercent: this.resources.getCpuPercent(),
-                memUsedMB,
-                memTotalMB,
-                slotsAvailable: Math.max(0, slotsTotal - bootedCount),
-                slotsTotal,
-                reportedAt: Date.now(),
-            },
-        });
+        this.resourcesInFlight = ws;
+        try {
+            const [{ memUsedMB, memTotalMB }, memoryPressure] = await Promise.all([
+                this.resources.getMemoryUsage(),
+                this.resources.getMemoryPressure(),
+            ]);
+            // A reconnect while sampling replaced the socket: this report has nowhere to go.
+            if (this.ws !== ws || ws.readyState !== WebSocket.OPEN)
+                return;
+            const bootedCount = Array.from(this.deviceStates.values()).filter((s) => s.streamReader !== null).length;
+            const slotsTotal = this.deviceStates.size;
+            this.sendOn(ws, {
+                type: 'agent:resources',
+                resources: {
+                    cpuPercent: this.resources.getCpuPercent(),
+                    memUsedMB,
+                    memTotalMB,
+                    slotsAvailable: Math.max(0, slotsTotal - bootedCount),
+                    slotsTotal,
+                    reportedAt: Date.now(),
+                    memoryPressure,
+                },
+            });
+        }
+        finally {
+            if (this.resourcesInFlight === ws)
+                this.resourcesInFlight = null;
+        }
     }
     cleanupDeviceState(state) {
         // Drop this device out of the filter rule. The rule lives on the host and is keyed only by udid,
@@ -674,7 +697,7 @@ export class IOSAgent {
     // `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, automation = false) {
+    async handleDeviceBoot(sessionId, deviceId, fullErase = false, acceptH264 = false, tier, requestId, automation = false, serviceTier, runReset) {
         const state = this.deviceStates.get(sessionId);
         // 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
@@ -721,6 +744,13 @@ export class IOSAgent {
             const target = devices.find((d) => d.id === deviceId);
             if (!target)
                 throw new PlatformError(`Device not found: ${deviceId}`);
+            // A running device on another tier than the run asked for is restarted onto it: the services have to be off
+            // from launch, and replaying on whatever the last boot left is what the tier exists to stop.
+            const retier = !fullErase && target.status === 'booted' && serviceTier !== undefined && leanSupported(target.osVersion)
+                && !sameServiceTier(this.leanStore.currentTier(deviceId), serviceTier);
+            // Read before anything below changes it: a Full reset shuts the device down itself, and `unknown`
+            // (booting, shutting down) is a device paying a boot's cost now.
+            const cold = fullErase || retier || target.status !== 'booted';
             if (fullErase) {
                 // `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
@@ -747,7 +777,6 @@ export class IOSAgent {
                     this.abandonBoot(state, seq, sessionId, requestId);
                     return;
                 }
-                this.prepareLean(target);
                 try {
                     await this.simctl.erase(deviceId);
                 }
@@ -770,6 +799,9 @@ export class IOSAgent {
                     }
                     throw err;
                 }
+                // After the erase, not before: a failed erase boots the device back as it was found, and the tier is part of
+                // that. The overrides live on the host, so the erase does not touch them either way.
+                this.prepareTier(target, serviceTier);
                 await this.simctl.boot(deviceId);
             }
             else {
@@ -780,10 +812,22 @@ export class IOSAgent {
                 // 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.
-                if (target.status === 'shutdown')
-                    this.prepareLean(target);
-                else if (this.lean && !this.leanStore.isApplied(deviceId)) {
-                    logger.info(`Lean mode: ${target.name} is already running, so it applies from its next boot`);
+                if (retier) {
+                    logger.info(`Service tier: restarting ${target.name} onto ${serviceTier.name}`);
+                    // As for a Full reset: a runner starting for this device would boot it back up mid-change.
+                    this.uiTreeReader.stopIfDevice(deviceId);
+                    await this.simctl.shutdown(deviceId);
+                    if (seq !== state.bootSeq) {
+                        this.abandonBoot(state, seq, sessionId, requestId);
+                        return;
+                    }
+                    this.prepareTier(target, serviceTier);
+                }
+                else if (target.status === 'shutdown') {
+                    this.prepareTier(target, serviceTier);
+                }
+                else if (leanSupported(target.osVersion) && !sameServiceTier(this.leanStore.currentTier(deviceId), this.defaultTier())) {
+                    logger.info(`Service tier: ${target.name} is already running, so ${this.defaultTier().name} applies from its next boot`);
                 }
                 await this.bootWithZombieRecovery(deviceId);
             }
@@ -802,6 +846,13 @@ export class IOSAgent {
             // 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 });
+            // Before anything runs on the device: the network arm below starts nothing, and the run installs its app after the
+            // ready. Clearing an app now and installing it after leaves a clean container.
+            const runResetReport = runReset ? await this.resetForRun(deviceId, runReset, () => seq !== state.bootSeq) : undefined;
+            if (seq !== state.bootSeq) {
+                this.abandonBoot(state, seq, sessionId, requestId);
+                return;
+            }
             // Arm the network injection while nothing is running on the device yet — dyld reads the
             // environment at process start, so anything launched before this is unhooked for its whole life.
             // Best-effort: the network toggle is opt-in and a device that cannot be armed says so through
@@ -847,7 +898,7 @@ export class IOSAgent {
             // every path precisely so that case reaches here. Requiring an off→on transition would leave
             // that device unowned and put the resolvers back to refusing between two live simulators.
             this.ownedDevices.add(deviceId);
-            this.sendMsg({ type: 'device:ready', sessionId, requestId, payload: { deviceId } });
+            this.sendMsg({ type: 'device:ready', sessionId, requestId, payload: { deviceId, cold, serviceTier: this.reportedTier(target), ...(runResetReport ? { runReset: runResetReport } : {}) } });
             // The unsolicited report the protocol names on `device:ready`. It follows the ready rather than
             // riding inside it: a tester whose device just came up can arm the toggle in the same breath, and
             // a boot that armed nothing still has to say so rather than leaving the control blank.
@@ -897,27 +948,37 @@ export class IOSAgent {
         }
     }
     // ── Lean mode ──────────────────────────────────────────────────────────────
+    /** The tier a boot gets when it does not ask for one: Lean mode's setting. A person's boot is always this. */
+    defaultTier() {
+        return { name: this.lean ? 'lean' : 'stock', keep: [] };
+    }
+    /** What the device boots with now, for the relay: the marker's tier, or `unsupported` on a runtime that cannot take one. */
+    reportedTier(device) {
+        return leanSupported(device.osVersion) ? this.leanStore.currentTier(device.id) : 'unsupported';
+    }
     /**
      * Called only when the device is known to be shut down: `launchd_sim` reads the store when it
      * starts, and a write while it runs is not known to survive. So a device that was already up when
-     * asked for is booted as it is, and becomes lean from its next boot through tapflow.
+     * asked for is booted as it is, and takes the default tier from its next boot through tapflow —
+     * unless a run asked for a tier, which restarts it (`retier` in `handleDeviceBoot`).
+     *
+     * **Every boot sets an exact tier**, the asked-for one or the default. Adding to whatever the last boot left
+     * is how a device a run left slim reached a person still slim (L2 review R4-S1).
      *
-     * **A failure here never stops the boot.** Lean mode is an optimisation and booting is the job.
+     * **A failure here never stops the boot.** A tier is an optimisation and booting is the job.
      */
-    prepareLean(device) {
+    prepareTier(device, requested) {
+        const tier = requested ?? this.defaultTier();
         try {
-            if (!this.lean) {
-                this.revertLean(device.id);
-            }
-            else if (!leanSupported(device.osVersion)) {
-                logger.info(`Lean mode: not applied to ${device.name} (${device.osVersion ?? 'unknown runtime'}) — iOS 18.5 or later only`);
-            }
-            else {
-                this.leanStore.apply(device.id, LEAN_LABELS);
+            if (!leanSupported(device.osVersion)) {
+                if (tier.name !== 'stock')
+                    logger.info(`Service tier: ${tier.name} not applied to ${device.name} (${device.osVersion ?? 'unknown runtime'}) — iOS 18.5 or later only`);
+                return;
             }
+            this.leanStore.setTier(device.id, tier, labelsFor(tier));
         }
         catch (e) {
-            logger.warn(`Lean mode: could not update ${device.name}, booting it as it is:`, e.message);
+            logger.warn(`Service tier: could not set ${device.name} to ${tier.name}, booting it as it is:`, e.message);
         }
     }
     /** Put back what Lean mode disabled on a device that is now shut down. A no-op for devices it never touched. */
@@ -1014,6 +1075,49 @@ export class IOSAgent {
             });
         }
     }
+    /**
+     * What `flow run` asks reset before a run, carried out on a booted device. Only the agent's report says it happened.
+     * It waits for the system services first: `Booted` shows before tccd and securityd serve, and not only on a boot this
+     * agent started — a device someone else just booted reads `booted` too. On a settled device the wait returns at once.
+     * The wait does not watch `isStale`; a shutdown meanwhile holds this boot's abandonment until its deadline.
+     */
+    async resetForRun(deviceId, request, isStale) {
+        // One budget for the wait and the steps: a device whose services never come up spends it waiting, and the steps
+        // that would have failed against it are reported failed instead of each running out its own timeout.
+        const deadline = Date.now() + RUN_RESET_BUDGET_MS;
+        const stop = () => isStale() || Date.now() >= deadline;
+        await this.simctl.waitForBootStatus(deviceId).catch((e) => logger.warn(`run reset: boot status unknown: ${firstLine(e)}`));
+        const steps = [];
+        if (request.uninstall.length > 0) {
+            steps.push({ item: 'app-uninstall', run: () => resetApps(request.uninstall, (id) => this.simctl.uninstallAppForReset(deviceId, id), stop) });
+        }
+        if (request.clear.length > 0) {
+            steps.push({ item: 'app-files', run: () => resetApps(request.clear, (id) => this.simctl.clearAppDataIfInstalled(deviceId, id), stop) });
+        }
+        steps.push({ item: 'keychain', run: () => this.simctl.resetKeychain(deviceId) }, { item: 'privacy-services', run: () => this.simctl.resetPrivacy(deviceId) }, 
+        // Through the clipboard queue: a clipboard read in flight parks a sentinel on this pasteboard.
+        { item: 'pasteboard', run: () => this.clearPasteboardQueued(deviceId, stop) }, { item: 'location', run: () => this.simctl.clearLocation(deviceId) });
+        return runResetSteps(steps, isStale, (item, e) => logger.warn(`run reset: ${item} failed: ${firstLine(e)}`), deadline);
+    }
+    /**
+     * The pasteboard step of a run reset. The queue can be held by a clipboard operation already running, so the wait for
+     * it is bounded too; a clear that reaches the front after the step gave up does nothing, because by then the run may
+     * have put something of its own there.
+     */
+    clearPasteboardQueued(deviceId, stop) {
+        let abandoned = false;
+        let timer;
+        const queued = this.clipboardQueue(deviceId, async () => {
+            if (abandoned || stop())
+                throw new PlatformError('the clipboard was busy for the whole reset');
+            await this.simctl.setPasteboard(deviceId, '');
+        });
+        const late = new Promise((_, reject) => {
+            timer = setTimeout(() => { abandoned = true; reject(new PlatformError('pasteboard clear timed out')); }, RUN_RESET_PASTEBOARD_TIMEOUT_MS);
+        });
+        queued.catch(() => { });
+        return Promise.race([queued, late]).finally(() => clearTimeout(timer));
+    }
     // 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)
@@ -1149,9 +1253,9 @@ export class IOSAgent {
         switch (msg.type) {
             case 'device:boot': {
                 // `external` and `automation` are added by the relay, never by the browser (see `DeviceBoot`).
-                const { deviceId, resetMode, acceptH264, secureContext, external, automation } = msg.payload;
+                const { deviceId, resetMode, acceptH264, secureContext, external, automation, serviceTier, runReset } = msg.payload;
                 const sessionId = msg.sessionId;
-                this.handleDeviceBoot(sessionId, deviceId, resetMode === 'full-erase', acceptH264 === true, { secureContext: !!secureContext, external: !!external }, msg.requestId, automation === true)
+                this.handleDeviceBoot(sessionId, deviceId, resetMode === 'full-erase', acceptH264 === true, { secureContext: !!secureContext, external: !!external }, msg.requestId, automation === true, serviceTier, runReset)
                     .catch((e) => logger.error('handleDeviceBoot failed:', e));
                 break;
             }
@@ -1187,7 +1291,7 @@ export class IOSAgent {
                 break;
             }
             case 'app:launch': {
-                const { bundleId } = msg.payload;
+                const { bundleId, arguments: args, env } = msg.payload;
                 const sessionId = msg.sessionId;
                 const { requestId } = msg;
                 if (typeof requestId !== 'string' || requestId === '') {
@@ -1202,12 +1306,20 @@ export class IOSAgent {
                     respond({ type: 'app:launch-error', message: 'No booted device' });
                     break;
                 }
+                // Checked again here rather than trusted: the relay checks with the same function, but an agent is the last
+                // door before a command line, and a relay of another version may check less.
+                const problem = launchOptionsProblem({ arguments: args, env });
+                if (problem) {
+                    respond({ type: 'app:launch-error', message: problem });
+                    break;
+                }
+                const options = compactLaunchOptions({ arguments: args, env });
                 // The target is named BEFORE the launch, and the order is the whole point: dyld reads the
                 // environment when the process starts, so naming it afterwards arms the next launch and leaves
                 // this one unhooked while `available` would still say true.
                 this.network.target(launchState.deviceId, bundleId)
                     .catch((e) => logger.warn('could not name the network target:', e.message))
-                    .then(() => this.simctl.launchApp(launchState.deviceId, bundleId))
+                    .then(() => this.simctl.launchApp(launchState.deviceId, bundleId, options))
                     .then((pid) => {
                     // **After the launch, with the pid it returned.** The network control measures how long a
                     // started process has gone without reporting its hooks; opening that window before
@@ -1218,7 +1330,7 @@ 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.
-                    respond({ type: 'app:launch-done' });
+                    respond(options ? { type: 'app:launch-done', applied: appliedKeys(options) } : { type: 'app:launch-done' });
                 })
                     .catch((e) => {
                     // The toast gets the reason alone; the full simctl output stays in this log.
@@ -1256,8 +1368,12 @@ export class IOSAgent {
                 // 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);
+                // terminal of a tap/swipe → ack the gesture, once the up is written (it may wait for the
+                // touch's minimum contact). The refusal is read then too, from the helper the state holds *then*:
+                // one replaced during the wait (a chrome reload, a reboot) is up and owns nothing, which is
+                // `no-gesture`, where the stopped one it replaced would say the channel is gone.
+                void (helper ? helper.touchEndAfterMinContact() : Promise.resolve(false))
+                    .then((sent) => this.ackInput(state, sent ? 'delivered' : this.refusalReason(state.touchHelper, 'continuation'), requestId));
                 break;
             }
             case 'input:pinch:start': {
@@ -2030,8 +2146,11 @@ export class IOSAgent {
     async networkState() {
         return this.network.state(await this.soleLiveDeviceId());
     }
-    async launchApp(bundleId) {
-        await this.simctl.launchApp(await this.soleLiveDeviceId(), bundleId);
+    async launchApp(bundleId, options) {
+        const problem = launchOptionsProblem(options ?? {});
+        if (problem)
+            throw new ValidationError(problem);
+        await this.simctl.launchApp(await this.soleLiveDeviceId(), bundleId, compactLaunchOptions(options));
     }
     /** 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
@@ -2139,7 +2258,7 @@ export class IOSAgent {
         const seq = state.bootSeq;
         const streamer = new AudioCaptureStreamer();
         streamer.listen()
-            .then((port) => {
+            .then(async (port) => {
             // A reboot/shutdown/disconnect may have superseded this boot while listen() was binding —
             // discard so we don't leave an orphan helper/poll/server behind the current lifecycle.
             if (seq !== state.bootSeq || streamWs.readyState !== WebSocket.OPEN) {
@@ -2148,21 +2267,37 @@ export class IOSAgent {
             }
             state.audioStreamer = streamer;
             state.audioPort = port;
-            state.audioVolume = readSimVolume(udid);
+            // Read before launching, so the first frames carry the sim's volume rather than full.
+            const [pids, volume] = await Promise.all([enumerateSimPids(udid), readSimVolume(udid)]);
+            // A stop or reboot while reading retired this capture: `stopAudioCapture` already stopped `streamer`,
+            // and launching the helper now would tap a device nobody is streaming.
+            if (state.audioStreamer !== streamer)
+                return;
+            // Only the control socket's close tears audio down; a stream socket that closed while reading would
+            // leave a helper and a poll running for nothing until the next reboot.
+            if (streamWs.readyState !== WebSocket.OPEN) {
+                this.stopAudioCapture(state);
+                return;
+            }
+            state.audioVolume = volume;
             void this.pumpAudio(streamWs, streamer.frames(), state);
-            this.launchWholeSimTap(state, udid);
+            this.launchWholeSimTap(state, pids);
+            // Started after the launch, so the first poll never races the launch's own pid set. One poll at a
+            // time: `ps` is bounded by its timeout, and a slow one is not stacked by the next tick.
+            let polling = false;
             state.audioPoll = setInterval(() => {
-                this.refreshAudioPids(state, udid);
-                state.audioVolume = readSimVolume(udid); // track live sim-volume changes
+                if (polling)
+                    return;
+                polling = true;
+                void this.refreshAudio(state, udid, streamer).finally(() => { polling = false; });
             }, AUDIO_POLL_MS);
         })
             .catch((e) => logger.warn(`audio capture server failed to start: ${e instanceof Error ? e.message : String(e)}`));
     }
     // Launch the tap helper for the simulator's whole process tree. Swallows errors — audio must never
     // break the launch/video path (e.g. helper build fails, or the user hasn't granted the audio
-    // permission). The helper holds the socket open; refreshAudioPids() pushes later updates to it.
-    launchWholeSimTap(state, udid) {
-        const pids = enumerateSimPids(udid);
+    // permission). The helper holds the socket open; refreshAudio() pushes later updates to it.
+    launchWholeSimTap(state, pids) {
         if (!pids.length) {
             logger.warn('no simulator processes to tap (audio idle until first poll)');
             return;
@@ -2179,18 +2314,21 @@ export class IOSAgent {
     // freshly spawned WebKit WebContent), push the updated set so the helper rebuilds its tap. Dead pids
     // need no rebuild — they resolve to no audio object, so the helper just stops mixing them; we still
     // refresh the baseline so a later reappearance is detected. Rebuilding only on additions keeps
-    // short-lived daemon churn from causing constant tap teardown (audio glitches).
-    refreshAudioPids(state, udid) {
-        if (!state.audioStreamer)
+    // short-lived daemon churn from causing constant tap teardown (audio glitches). Also tracks live sim-volume
+    // changes. Both reads are asynchronous, so the capture may have been retired by the time they land; `streamer`
+    // is the capture this poll belongs to.
+    async refreshAudio(state, udid, streamer) {
+        const [pids, volume] = await Promise.all([enumerateSimPids(udid), readSimVolume(udid)]);
+        if (state.audioStreamer !== streamer)
             return;
-        const pids = enumerateSimPids(udid);
+        state.audioVolume = volume;
         if (!pids.length)
             return;
         const prev = state.audioPids;
         const hasNew = !prev || pids.some((p) => !prev.has(p));
         state.audioPids = new Set(pids);
         if (hasNew)
-            state.audioStreamer.updatePids(pids);
+            streamer.updatePids(pids);
     }
     // Forward captured PCM to the relay on the shared stream socket via the yielding sender (audio must
     // never inflate the socket buffer enough to trip video's backpressure). Mirrors android-agent.
@@ -2232,10 +2370,9 @@ export class IOSAgent {
         first?.touchHelper?.touchMove(x, y);
         return Promise.resolve();
     }
-    touchEnd() {
+    async touchEnd() {
         const first = this.liveDeviceState();
-        first?.touchHelper?.touchEnd();
-        return Promise.resolve();
+        await first?.touchHelper?.touchEndAfterMinContact();
     }
     async openUrl(url) {
         return this.simctl.openUrl(await this.soleLiveDeviceId(), url);