@tapflowio/ios-agent 0.26.1 → 0.27.1

package/dist/IOSAgent.d.ts

@@ -4,6 +4,7 @@ import { type SleepBlocker } from '@tapflowio/agent-core/utils';
 import { SimctlWrapper } from './SimctlWrapper.js';
 import { SimulatorNetwork } from './SimulatorNetwork.js';
 import { LeanStore } from './LeanStore.js';
+import { DeviceChromeLoader } from './DeviceChromeLoader.js';
 /** Lean mode needs an iOS runtime of 18.5 or later, where launchd honours the host-side overrides
  *  across reboots. tvOS, watchOS and visionOS devices come through the same list and are left alone. */
 export declare function leanSupported(osVersion: string | undefined): boolean;
@@ -27,6 +28,9 @@ export interface IOSAgentOptions {
     lean?: boolean;
     /** Where the launchd overrides are written. Injectable for the same reason as `network`. */
     leanStore?: LeanStore;
+    /** Device frame loading. Under vitest the default points at directories that do not exist, so a suite never
+     *  reads the developer's Xcode chrome or spends seconds rendering it. */
+    chromeLoader?: DeviceChromeLoader;
 }
 export declare class IOSAgent implements DeviceAgent, NetworkControlCapability {
     private readonly simctl;
@@ -62,6 +66,14 @@ export declare class IOSAgent implements DeviceAgent, NetworkControlCapability {
      *  inside `onopen` on a local socket. */
     private sendOn;
     private deviceStates;
+    /**
+     * One queue of rotations per device (#910). Each is its own helper process, so two sent back to back
+     * can land in either order, and a held ⌘⇧O or the boot reset racing the first press would leave the
+     * simulator on the earlier target. Keyed here rather than on `DeviceState` because a re-register
+     * replaces the states while a rotation already in flight keeps running — the boot reset that follows
+     * has to queue behind it, not start fresh beside it.
+     */
+    private readonly rotations;
     /**
      * Devices **this agent booted**, by device id.
      *
@@ -86,7 +98,15 @@ export declare class IOSAgent implements DeviceAgent, NetworkControlCapability {
     private lastBundleIds;
     private readonly uiTreeReader;
     private readonly sleepBlocker;
+    /** What the next "relay disconnected" line reports: when the relay last pinged, and the socket's last error. */
+    private lastPingAt;
+    private lastSocketError;
+    private releaseStallWatch;
     private relayUrl;
+    /** The last device-type lookup that answered. A udid's type never changes, so on a reconnect whose
+     *  lookup fails this is still right — and the relay overwrites device fields on every register, so
+     *  falling back to nothing would blank a form factor it already had until the next reconnect. */
+    private formFactors;
     private resourcesTimer;
     private readonly resources;
     private _stopping;
@@ -97,12 +117,25 @@ export declare class IOSAgent implements DeviceAgent, NetworkControlCapability {
     constructor(options?: IOSAgentOptions, simctl?: SimctlWrapper);
     get sessionId(): string | null;
     connect(relayUrl: string): Promise<void>;
+    /**
+     * `listTimeoutMs` is set only by the reconnect loop. `simctl list` is left unbounded elsewhere on purpose
+     * (see `SimctlWrapper.listDevices`), but here a hang has a worse outcome than a failure: the attempt never
+     * settles, `_scheduleReconnect` is never reached, and the agent stays offline with nothing in its output
+     * even after CoreSimulator recovers. A bounded attempt fails and the loop tries again.
+     */
+    private connectOnce;
     private initDeviceStates;
     disconnect(): void;
+    /** `loss` is absent when a reconnect attempt failed: there is no close to describe, only a retry. */
     private _scheduleReconnect;
     private reportResources;
     private cleanupDeviceState;
+    /** Resolves `false` when a newer boot or a relay loss retired this one during the chrome load, in which case
+     *  nothing was stored and the caller abandons the boot. A closed socket alone continues as it always did —
+     *  the relay loss that follows bumps the seq. */
     private sendChromeData;
+    /** `failures` counts the frameless runs before this one; only the restart in `pump` passes it, so a new
+     *  boot starts from zero without any state to reset. */
     private startBinaryStream;
     private wsClientOptions;
     private openStreamWs;
@@ -176,6 +209,9 @@ export declare class IOSAgent implements DeviceAgent, NetworkControlCapability {
     private refusalReason;
     private ackInput;
     private isBooted;
+    /** Run `step` after every rotation already queued for this device. A failing step is logged and does
+     *  not stop the ones behind it. */
+    private enqueueRotation;
     private handleRelayMessage;
     private readUITree;
     /**
@@ -318,4 +354,14 @@ export declare class IOSAgent implements DeviceAgent, NetworkControlCapability {
     touchEnd(): Promise<void>;
     openUrl(url: string): Promise<void>;
 }
+/**
+ * When to restart a screen stream that just ended. Only a run that delivered a frame resets the count — not
+ * how long it lasted: the helper retries `device.io` and its ports for up to ~10s before it gives up, so a
+ * duration rule would call every first-boot failure healthy. A simulator shut down from outside makes the
+ * helper exit at once, which without this was a restart loop at full speed.
+ */
+export declare function streamRestartPlan(previousFailures: number, deliveredFrame: boolean): {
+    failures: number;
+    delayMs: number;
+};
 //# sourceMappingURL=IOSAgent.d.ts.map

package/dist/IOSAgent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"IOSAgent.d.ts","sourceRoot":"","sources":["../src/IOSAgent.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"IOSAgent.d.ts","sourceRoot":"","sources":["../src/IOSAgent.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAA4C,MAAM,EAAE,WAAW,EAAE,wBAAwB,EAAE,mBAAmB,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAA;AAsCpK,eAAO,MAAM,kBAAkB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAIrD,CAAA;AACD,OAAO,EAYL,KAAK,YAAY,EAUlB,MAAM,6BAA6B,CAAA;AAEpC,OAAO,EAAE,aAAa,EAAgF,MAAM,oBAAoB,CAAA;AAChI,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAA;AACxD,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAgB1C,OAAO,EAAE,kBAAkB,EAAmB,MAAM,yBAAyB,CAAA;AAW7E;wGACwG;AACxG,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAKpE;AAED,MAAM,WAAW,eAAe;IAC9B,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,eAAe,CAAC,EAAE,MAAM,EAAE,CAAA;IAC1B,2FAA2F;IAC3F,YAAY,CAAC,EAAE,YAAY,CAAA;IAC3B,2FAA2F;IAC3F,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,+FAA+F;IAC/F,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,kEAAkE;IAClE,kBAAkB,CAAC,EAAE,MAAM,CAAA;IAC3B;6FACyF;IACzF,OAAO,CAAC,EAAE,gBAAgB,CAAA;IAC1B;mDAC+C;IAC/C,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,4FAA4F;IAC5F,SAAS,CAAC,EAAE,SAAS,CAAA;IACrB;6EACyE;IACzE,YAAY,CAAC,EAAE,kBAAkB,CAAA;CAClC;AAkDD,qBAAa,QAAS,YAAW,WAAW,EAAE,wBAAwB;IACpE,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAe;IACtC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAkB;IAC1C,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAQ;IAC5B,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAoB;IAC/C,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAU;IAC1C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAoB;IACjD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAQ;IACtC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAQ;IAC/B,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAQ;IAC3C,OAAO,CAAC,EAAE,CAAyB;IAEnC;;;;;;;;;;;;;iDAa6C;IAC7C,OAAO,CAAC,OAAO;IAKf;;;;;6CAKyC;IACzC,OAAO,CAAC,MAAM;IAGd,OAAO,CAAC,YAAY,CAAiC;IACrD;;;;;;OAMG;IACH,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAmC;IAC7D;;;;;;;;;;;;;;;;;;;OAmBG;IACH,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAoB;IAIjD,OAAO,CAAC,aAAa,CAA4B;IACjD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAuB;IAGpD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAc;IAC3C,gHAAgH;IAChH,OAAO,CAAC,UAAU,CAAsB;IACxC,OAAO,CAAC,eAAe,CAAoB;IAC3C,OAAO,CAAC,iBAAiB,CAA4B;IACrD,OAAO,CAAC,QAAQ,CAAsB;IACtC;;qGAEiG;IACjG,OAAO,CAAC,WAAW,CAAgC;IACnD,OAAO,CAAC,cAAc,CAA8C;IACpE,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA0B;IACpD,OAAO,CAAC,SAAS,CAAQ;IACzB,OAAO,CAAC,eAAe,CAA6C;IACpE,OAAO,CAAC,iBAAiB,CAAI;IAC7B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAC9B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAW;gBAEzB,OAAO,GAAE,eAAoB,EAAE,MAAM,CAAC,EAAE,aAAa;IA2CjE,IAAI,SAAS,IAAI,MAAM,GAAG,IAAI,CAG7B;IAEK,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI9C;;;;;OAKG;YACW,WAAW;IAkIzB,OAAO,CAAC,gBAAgB;IA+BxB,UAAU,IAAI,IAAI;IAsBlB,qGAAqG;IACrG,OAAO,CAAC,kBAAkB;IAqC1B,OAAO,CAAC,eAAe;IAkBvB,OAAO,CAAC,kBAAkB;IAuB1B;;qDAEiD;YACnC,cAAc;IAoC5B;4DACwD;IACxD,OAAO,CAAC,iBAAiB;IA+FzB,OAAO,CAAC,eAAe;YAST,YAAY;IAO1B;;;;;+GAK2G;IAC3G,OAAO,CAAC,WAAW;IAKnB;;;;;;wDAMoD;IACpD,OAAO,CAAC,WAAW;YAsBL,gBAAgB;YAsLhB,sBAAsB;IAapC;;;;;;OAMG;IACH,OAAO,CAAC,WAAW;IAcnB,gHAAgH;IAChH,OAAO,CAAC,UAAU;IAQlB;;;;;OAKG;IACH,OAAO,CAAC,kBAAkB;YAQZ,oBAAoB;IAmElC,OAAO,CAAC,iBAAiB;IASzB,OAAO,CAAC,QAAQ,CAAC,cAAc,CAA2B;IAM1D,OAAO,CAAC,QAAQ,CAAC,eAAe,CAA4B;IAE5D,OAAO,CAAC,YAAY;IAMpB,OAAO,CAAC,cAAc;IAWtB;;;;;;;;;;qEAUiE;IACjE,OAAO,CAAC,YAAY;IAMpB,OAAO,CAAC,YAAY;IAWpB;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,aAAa;YAyBP,QAAQ;YAWR,QAAQ;IAOtB;uCACmC;IACnC,OAAO,CAAC,eAAe;IASvB,OAAO,CAAC,kBAAkB;YA4nBZ,UAAU;IAQxB;;;;OAIG;YACW,YAAY;IA0C1B,kFAAkF;YACpE,WAAW;IA+CzB,WAAW,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IAChC,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IACrC,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IACzC;;;;mFAI+E;IACzE,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAShD,4EAA4E;IAC5E;;;;;;;;;;;;;;;;;;;OAmBG;YACW,SAAS;IASvB;;;;;;OAMG;YACW,kBAAkB;IAMhC;;;;;;;;;;;;;;OAcG;IACH,OAAO,CAAC,qBAAqB;YAOf,gBAAgB;IAoB9B;;;;;;;;;;;;;OAaG;IACG,iBAAiB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAIjE,YAAY,IAAI,OAAO,CAAC,mBAAmB,CAAC;IAI5C,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIhD;;mDAE+C;IAC/C,OAAO,CAAC,eAAe;IAKvB;6DACyD;IACzD,OAAO,CAAC,MAAM;IAUd;;;;;;;;;;;;;;;;;;OAkBG;IACH,OAAO,CAAC,eAAe;IAWvB;;;;;;;;;;;;;;;;OAgBG;YACW,mBAAmB;YAmBnB,gBAAgB;IAIxB,WAAW,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC;IAczC,OAAO,CAAC,YAAY;IAOpB,OAAO,CAAC,iBAAiB;IAwBzB,OAAO,CAAC,iBAAiB;IAgBzB,OAAO,CAAC,gBAAgB;YAYV,SAAS;IAiBjB,UAAU,IAAI,OAAO,CAAC,MAAM,CAAC;IACnC,MAAM,IAAI,cAAc,CAAC,MAAM,CAAC;IAShC,UAAU,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI;IAItC,SAAS,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAK9C,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAMnB,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAG1C;AAoBD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,gBAAgB,EAAE,MAAM,EAAE,cAAc,EAAE,OAAO,GAAG;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAI1H"}

package/dist/IOSAgent.js

@@ -3,9 +3,9 @@ import fs from 'fs';
 import path from 'path';
 import { tmpdir } from 'os';
 import { randomUUID } from 'crypto';
-import { spawnSync } from 'child_process';
+import { spawn } from 'child_process';
 import { WebSocket } from 'ws';
-import { createLogger, PlatformError, ValidationError, bootAbandonMessage, BOOT_NO_SESSION_STATE, downloadBuild } from '@tapflowio/agent-core';
+import { createLogger, PlatformError, ValidationError, bootAbandonMessage, BOOT_NO_SESSION_STATE, SHUTDOWN_NO_SESSION_STATE, downloadBuild } 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.
 // `full-reset` is honoured in `handleDeviceBoot`, which shuts a running device down before
@@ -39,8 +39,8 @@ export const IOS_BUTTON_ALIASES = {
     volume_up: 'volume-up',
     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, firstLine } from './SimctlWrapper.js';
+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 { SimctlWrapper, isDeviceMissingError, ClipboardTooLargeError, firstLine, launchFailureReason } from './SimctlWrapper.js';
 import { SimulatorNetwork } from './SimulatorNetwork.js';
 import { LeanStore } from './LeanStore.js';
 import { LEAN_LABELS } from './leanLabels.js';
@@ -58,8 +58,8 @@ import { KEY_CODE_MAP, MODIFIER_BITS } from './KeyCodeMap.js';
 // processes (launched apps, WebKit WebContent). Short enough that a tab's audio starts promptly,
 // long enough to keep `ps` overhead negligible.
 const AUDIO_POLL_MS = 1500;
-// 아카이브 추출(tar/unzip) 시 stdout 상한. 기본 1MB 로는 파일 많은 큰 .app 에서 넘칠 수 있어 넉넉히 잡는다.
-const EXTRACT_MAXBUFFER = 256 * 1024 * 1024; // 256 MB
+/** Bound on `simctl list` during a reconnect attempt only; see `connectOnce`. */
+const RECONNECT_LIST_TIMEOUT_MS = 10_000;
 /** Lean mode needs an iOS runtime of 18.5 or later, where launchd honours the host-side overrides
  *  across reboots. tvOS, watchOS and visionOS devices come through the same list and are left alone. */
 export function leanSupported(osVersion) {
@@ -109,6 +109,14 @@ export class IOSAgent {
         ws.send(JSON.stringify(msg));
     }
     deviceStates = new Map();
+    /**
+     * One queue of rotations per device (#910). Each is its own helper process, so two sent back to back
+     * can land in either order, and a held ⌘⇧O or the boot reset racing the first press would leave the
+     * simulator on the earlier target. Keyed here rather than on `DeviceState` because a re-register
+     * replaces the states while a rotation already in flight keeps running — the boot reset that follows
+     * has to queue behind it, not start fresh beside it.
+     */
+    rotations = new Map();
     /**
      * Devices **this agent booted**, by device id.
      *
@@ -138,7 +146,15 @@ export class IOSAgent {
     // Holds a macOS power assertion while connected so the host doesn't idle-throttle the
     // simulator capture/encode when the Mac is unattended. No-op off macOS.
     sleepBlocker;
+    /** What the next "relay disconnected" line reports: when the relay last pinged, and the socket's last error. */
+    lastPingAt = null;
+    lastSocketError;
+    releaseStallWatch = null;
     relayUrl = null;
+    /** The last device-type lookup that answered. A udid's type never changes, so on a reconnect whose
+     *  lookup fails this is still right — and the relay overwrites device fields on every register, so
+     *  falling back to nothing would blank a form factor it already had until the next reconnect. */
+    formFactors = new Map();
     resourcesTimer = null;
     resources = createResourceSampler();
     _stopping = false;
@@ -176,7 +192,9 @@ export class IOSAgent {
         this.fps = options.fps ?? 30;
         this.intervalMs = options.intervalMs;
         this.reconnectDelays = options.reconnectDelays ?? [1000, 2000, 4000, 8000, 16000, 30000];
-        this.chromeLoader = new DeviceChromeLoader();
+        this.chromeLoader = options.chromeLoader ?? new DeviceChromeLoader(process.env.VITEST
+            ? { run: () => Promise.reject(new Error('no chrome under vitest')) }
+            : {});
         this.deviceFilter = options.deviceFilter;
         this.token = options.token;
         this.handshakeTimeoutMs = options.handshakeTimeoutMs ?? 10_000;
@@ -188,6 +206,15 @@ export class IOSAgent {
         return first?.sessionId ?? null;
     }
     async connect(relayUrl) {
+        return this.connectOnce(relayUrl);
+    }
+    /**
+     * `listTimeoutMs` is set only by the reconnect loop. `simctl list` is left unbounded elsewhere on purpose
+     * (see `SimctlWrapper.listDevices`), but here a hang has a worse outcome than a failure: the attempt never
+     * settles, `_scheduleReconnect` is never reached, and the agent stays offline with nothing in its output
+     * even after CoreSimulator recovers. A bounded attempt fails and the loop tries again.
+     */
+    async connectOnce(relayUrl, listTimeoutMs) {
         this._stopping = false;
         // Paired with the `dispose()` in `disconnect()`. This method is public and reuses the network, so
         // without it a reconnect leaves the liveness watcher off for good — see `SimulatorNetwork.resume`.
@@ -197,11 +224,21 @@ export class IOSAgent {
             this._reconnectTimer = null;
         }
         this.relayUrl = relayUrl;
-        const allDevices = await this.simctl.listDevices();
+        const allDevices = await this.simctl.listDevices(listTimeoutMs);
         this.revertLeftoverLean(allDevices);
         const devices = this.deviceFilter
             ? allDevices.filter((d) => d.name === this.deviceFilter || d.id === this.deviceFilter)
             : allDevices;
+        // A `disconnect()` during this await or the one above does not cancel the connect. Every caller
+        // today exits the process on the next line (the CLI's SIGINT handlers); one that keeps running
+        // needs a generation check here before the socket is built.
+        // An answer the lookup cannot give costs the field, not the register: a viewer draws a device with
+        // no form factor as a phone, which is what it did before there was one. A reconnect falls back to
+        // the last answer rather than to none (see `formFactors`).
+        const formFactors = await this.simctl.formFactorsByType().then((map) => (this.formFactors = map), (e) => {
+            logger.warn(`device types unavailable, registering with the last known form factors: ${e instanceof Error ? e.message : String(e)}`);
+            return this.formFactors;
+        });
         return new Promise((resolve, reject) => {
             const ws = new WebSocket(relayUrl, this.wsClientOptions());
             let registered = false;
@@ -226,6 +263,7 @@ export class IOSAgent {
                         platform: d.platform,
                         status: d.status,
                         osVersion: d.osVersion,
+                        formFactor: d.typeId ? formFactors.get(d.typeId) : undefined,
                     })),
                 });
             });
@@ -262,7 +300,18 @@ export class IOSAgent {
                     });
                     this.reportResources();
                     this.resourcesTimer = setInterval(() => this.reportResources(), 5000);
-                    ws.on('close', () => this._scheduleReconnect());
+                    this.lastPingAt = null;
+                    this.lastSocketError = undefined;
+                    ws.on('ping', () => { this.lastPingAt = Date.now(); });
+                    // After registration the handshake's `once('error', reject)` lands on a settled promise, so the
+                    // code (ETIMEDOUT, ECONNRESET…) was dropped. It is the network half of the disconnect line.
+                    ws.on('error', (e) => { this.lastSocketError = e.code ?? e.message; });
+                    // `now` is taken here, at the close, not when the warning prints: the cleanup in between can run
+                    // work that holds the event loop and would inflate the ping age.
+                    ws.on('close', (code, reason) => this._scheduleReconnect({
+                        code, reason: reason.toString(), errorCode: this.lastSocketError, lastPingAt: this.lastPingAt, now: Date.now(),
+                    }));
+                    this.releaseStallWatch ??= acquireLoopStallWatch();
                     resolve();
                 }
                 else {
@@ -335,12 +384,15 @@ export class IOSAgent {
         // other things that tick. It is `unref`'d, which is why nobody noticed it had no caller.
         this.network.dispose();
         this.sleepBlocker.release();
+        this.releaseStallWatch?.();
+        this.releaseStallWatch = null;
         this.ws?.close();
         this.ws = null;
         this.relayUrl = null;
         this.simctl.stopKeyboardDaemon();
     }
-    _scheduleReconnect() {
+    /** `loss` is absent when a reconnect attempt failed: there is no close to describe, only a retry. */
+    _scheduleReconnect(loss) {
         if (this._stopping)
             return;
         if (this.resourcesTimer) {
@@ -362,12 +414,14 @@ export class IOSAgent {
         const delays = this.reconnectDelays;
         const delay = delays[Math.min(this._reconnectAttempt, delays.length - 1)];
         this._reconnectAttempt++;
-        logger.warn(`relay disconnected — reconnecting in ${delay / 1000}s (attempt ${this._reconnectAttempt})`);
+        logger.warn(loss
+            ? `relay disconnected (${describeRelayLoss(loss)}) — reconnecting in ${delay / 1000}s (attempt ${this._reconnectAttempt})`
+            : `reconnecting in ${delay / 1000}s (attempt ${this._reconnectAttempt})`);
         this._reconnectTimer = setTimeout(() => {
             this._reconnectTimer = null;
             if (this._stopping || !this.relayUrl)
                 return;
-            this.connect(this.relayUrl).then(() => {
+            this.connectOnce(this.relayUrl, RECONNECT_LIST_TIMEOUT_MS).then(() => {
                 this._reconnectAttempt = 0;
                 logger.info('reconnected to relay');
             }).catch((e) => {
@@ -403,7 +457,7 @@ export class IOSAgent {
         void this.network.forget(state.deviceId).catch((e) => {
             logger.warn('could not clear the network rule for a retired device:', e.message);
         });
-        void state.streamReader?.cancel();
+        state.streamReader?.cancel().catch(() => { });
         state.streamReader = null;
         state.captureStreamer = null; // reader.cancel() kills the helper proc; drop the ref so a stale requestKeyframe() no-ops
         if (state.audioPoll) {
@@ -420,12 +474,15 @@ export class IOSAgent {
         state.streamWs?.close();
         state.streamWs = null;
     }
-    sendChromeData(state, device) {
+    /** Resolves `false` when a newer boot or a relay loss retired this one during the chrome load, in which case
+     *  nothing was stored and the caller abandons the boot. A closed socket alone continues as it always did —
+     *  the relay loss that follows bumps the seq. */
+    async sendChromeData(state, device, seq) {
         // `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;
+            return true;
         // 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.
@@ -440,16 +497,28 @@ export class IOSAgent {
                 osVersion: device.osVersion ?? '',
             },
         });
-        state.loadedChrome = this.chromeLoader.load(device.typeId ?? device.name);
-        if (!state.loadedChrome)
-            return;
-        this.sendOn(this.ws, {
+        // Awaited where it used to block: a cold load is seconds of swift renders. A newer boot or a shutdown can
+        // land meanwhile, so the result is stored only after the seq is checked — otherwise a slow stale load
+        // would overwrite the chrome a faster newer boot already set, and the button path reads it.
+        const chrome = await this.chromeLoader.load(device.typeId ?? device.name);
+        if (seq !== state.bootSeq)
+            return false;
+        const ws = this.ws;
+        if (ws?.readyState !== WebSocket.OPEN)
+            return true;
+        state.loadedChrome = chrome;
+        if (!chrome)
+            return true;
+        this.sendOn(ws, {
             type: 'session:chrome',
             sessionId: state.sessionId,
-            payload: state.loadedChrome,
+            payload: chrome,
         });
+        return true;
     }
-    startBinaryStream(state, streamWs) {
+    /** `failures` counts the frameless runs before this one; only the restart in `pump` passes it, so a new
+     *  boot starts from zero without any state to reset. */
+    startBinaryStream(state, streamWs, failures = 0) {
         // 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, and now
@@ -497,11 +566,13 @@ export class IOSAgent {
             state.captureStreamer?.requestKeyframe();
         } };
         const pump = async () => {
+            let delivered = false;
             try {
                 while (true) {
                     const { value, done } = await reader.read();
                     if (done)
                         break;
+                    delivered = true;
                     // Declare reorder=0 on the keyframe SPS so every decoder (WebCodecs, MSE,
                     // WASM) emits frames immediately instead of buffering the level's max DPB
                     // (~8 frames ≈ 250ms). Keyframe-only (SPS lives there); no-op otherwise.
@@ -520,7 +591,26 @@ export class IOSAgent {
             if (metricsTimer)
                 clearInterval(metricsTimer);
             if (state.streamReader === reader && streamWs.readyState === WebSocket.OPEN) {
-                this.startBinaryStream(state, streamWs);
+                const next = streamRestartPlan(failures, delivered);
+                if (next.failures === 2) {
+                    logger.warn(`screen stream for ${state.deviceId} keeps ending before its first frame — backing off restarts`);
+                }
+                // Re-checked after the delay: a new boot, a shutdown, a relay loss or disconnect() all swap or clear
+                // the reader, or close the socket, in the meantime.
+                const restart = () => {
+                    if (this._stopping || state.streamReader !== reader || streamWs.readyState !== WebSocket.OPEN)
+                        return;
+                    try {
+                        this.startBinaryStream(state, streamWs, next.failures);
+                    }
+                    catch (e) {
+                        logger.error(`screen stream for ${state.deviceId} could not restart: ${e instanceof Error ? e.message : String(e)}`);
+                    }
+                };
+                if (next.delayMs === 0)
+                    restart();
+                else
+                    setTimeout(restart, next.delayMs).unref();
             }
         };
         void pump();
@@ -608,7 +698,7 @@ export class IOSAgent {
         // 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?.cancel().catch(() => { });
             state.streamReader = null;
             state.captureStreamer = null; // reader.cancel() kills the helper proc; drop the ref so a stale requestKeyframe() no-ops
             state.touchHelper?.stop();
@@ -710,6 +800,15 @@ export class IOSAgent {
             await this.network.arm(deviceId).catch((e) => {
                 logger.warn('could not arm the network injection:', e.message);
             });
+            // **Stand it up (#910).** A fresh viewer always starts portrait, and a simulator left turned —
+            // by a session whose undo never arrived, or one an agent restart reset the memory of — would
+            // otherwise stream sideways under an upright frame, with every later press inverted. Queued with
+            // the rotations, so one still in flight from before a re-register lands first and is overridden.
+            // Best-effort: a failure leaves the simulator where it was, and the boot goes on.
+            await this.enqueueRotation(deviceId, async () => {
+                await this.simctl.rotate(deviceId, 'portrait');
+                state.orientation = 'portrait';
+            });
             // 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
@@ -718,7 +817,10 @@ export class IOSAgent {
                 this.abandonBoot(state, seq, sessionId, requestId);
                 return;
             }
-            this.sendChromeData(state, bootedDevice);
+            if (!(await this.sendChromeData(state, bootedDevice, seq))) {
+                this.abandonBoot(state, seq, sessionId, requestId);
+                return;
+            }
             const streamWs = await this.openStreamWs(state);
             if (seq !== state.bootSeq) {
                 streamWs.close();
@@ -838,8 +940,15 @@ export class IOSAgent {
     }
     async handleDeviceShutdown(sessionId, deviceId, requestId) {
         const state = this.deviceStates.get(sessionId);
-        if (!state)
+        if (!state) {
+            // Answered only when someone asked: nothing was attempted, and the idle timer's id-less shutdown has no
+            // waiter to tell. A failure below is answered either way — `requestId` is optional on `device:shutdown`,
+            // so an id-less sender that is waiting can only learn of the failure this way (protocol/AGENTS.md,
+            // 「The sender must hold the session」).
+            if (requestId)
+                this.sendMsg({ type: 'device:shutdown-error', sessionId, requestId, message: SHUTDOWN_NO_SESSION_STATE });
             return;
+        }
         this.bumpBootSeq(state, 'shut-down');
         // **Said here as well as in `cleanupDeviceState`, because this path does not go through it.**
         // The teardown below is a copy of that method's, and the copy is older than the network rule —
@@ -851,7 +960,7 @@ export class IOSAgent {
         void this.network.forget(deviceId).catch((e) => {
             logger.warn('could not clear the network rule for a shut-down device:', e.message);
         });
-        void state.streamReader?.cancel();
+        state.streamReader?.cancel().catch(() => { });
         state.streamReader = null;
         state.captureStreamer = null; // reader.cancel() kills the helper proc; drop the ref so a stale requestKeyframe() no-ops
         state.touchHelper?.stop();
@@ -883,6 +992,15 @@ export class IOSAgent {
         catch (e) {
             const message = e instanceof Error ? e.message : String(e);
             logger.error('shutdown failed:', message);
+            // "Already shut down" never reaches here — `SimctlWrapper.shutdown` absorbs it — so this is a device
+            // that is still running, with its stream already torn down above. Said, because silence left the
+            // caller waiting out its deadline (#455).
+            this.sendMsg({
+                type: 'device:shutdown-error',
+                sessionId,
+                requestId,
+                message: `The simulator did not shut down, and its stream has been stopped: ${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).
@@ -1005,6 +1123,17 @@ export class IOSAgent {
             return false;
         }
     }
+    /** Run `step` after every rotation already queued for this device. A failing step is logged and does
+     *  not stop the ones behind it. */
+    enqueueRotation(deviceId, step) {
+        const next = (this.rotations.get(deviceId) ?? Promise.resolve())
+            .then(step)
+            .catch((e) => { logger.error('rotate failed:', e); });
+        this.rotations.set(deviceId, next);
+        void next.then(() => { if (this.rotations.get(deviceId) === next)
+            this.rotations.delete(deviceId); });
+        return next;
+    }
     handleRelayMessage(msg) {
         switch (msg.type) {
             case 'device:boot': {
@@ -1080,8 +1209,9 @@ export class IOSAgent {
                     respond({ type: 'app:launch-done' });
                 })
                     .catch((e) => {
-                    const message = e instanceof Error ? e.message : String(e);
-                    respond({ type: 'app:launch-error', message });
+                    // The toast gets the reason alone; the full simctl output stays in this log.
+                    console.warn('[tapflow] app:launch failed:', e);
+                    respond({ type: 'app:launch-error', message: launchFailureReason(e) });
                 });
                 break;
             }
@@ -1152,9 +1282,19 @@ export class IOSAgent {
                 const state = this.deviceStates.get(msg.sessionId);
                 if (!state)
                     break;
-                state.orientation = state.orientation === 'portrait' ? 'landscapeRight' : 'portrait';
-                this.simctl.rotate(state.deviceId, state.orientation)
-                    .catch((e) => logger.error('rotate failed:', e));
+                // **A target when the viewer sends one, a toggle when it does not** (#910) — an older
+                // dashboard's. The memory is read when the step runs, not when it was queued, and written only
+                // once the simulator took it: a step queued behind another toggles from what that one applied.
+                const sessionId = msg.sessionId;
+                const target = msg.payload?.orientation;
+                void this.enqueueRotation(state.deviceId, async () => {
+                    const live = this.deviceStates.get(sessionId) ?? state;
+                    const next = target
+                        ? (target === 'landscape' ? 'landscapeRight' : 'portrait')
+                        : (live.orientation === 'portrait' ? 'landscapeRight' : 'portrait');
+                    await this.simctl.rotate(live.deviceId, next);
+                    live.orientation = next;
+                });
                 break;
             }
             case 'stream:request-idr': {
@@ -1709,7 +1849,8 @@ export class IOSAgent {
             return await this.installFrom(udid, source, tmpDir);
         }
         finally {
-            fs.rmSync(tmpDir, { recursive: true, force: true });
+            // Async for the same reason as the extraction: a large .app is a lot of files to unlink.
+            await fs.promises.rm(tmpDir, { recursive: true, force: true });
         }
     }
     /** Extraction + `simctl install`, given a file this machine can actually open. */
@@ -1724,11 +1865,12 @@ export class IOSAgent {
         // `tmpDir`, and extracting beside it would put the two in one listing.
         const outDir = path.join(tmpDir, 'x');
         fs.mkdirSync(outDir, { recursive: true });
-        // tar 는 기본 무음, unzip 은 -q 로 무음화해 큰 .app 에서 verbose stdout 이 기본
-        // maxBuffer(1MB)를 넘겨 추출이 죽는 것을 막는다.
+        // **Not `spawnSync`.** It held the event loop for as long as the extraction ran, which on a large build
+        // or a busy Mac was long enough for the relay's heartbeat to end this agent's connection — and every
+        // other session on the Mac froze with it.
         const result = isTar
-            ? spawnSync('tar', ['-xzf', filePath, '-C', outDir], { maxBuffer: EXTRACT_MAXBUFFER })
-            : spawnSync('unzip', ['-q', '-o', filePath, '-d', outDir], { maxBuffer: EXTRACT_MAXBUFFER });
+            ? await runExtractor('tar', ['-xzf', filePath, '-C', outDir])
+            : await runExtractor('unzip', ['-q', '-o', filePath, '-d', outDir]);
         // 실행 자체 실패(tar/unzip 부재=ENOENT 등)는 아카이브 무효와 구분한다.
         if (result.error) {
             const code = result.error.code ?? result.error.message;
@@ -1739,7 +1881,7 @@ export class IOSAgent {
             // evidence away, so a build that was fine read as corrupt — `unzip` had said
             // `cannot find or open`, which names a missing file rather than a bad archive, and nobody
             // could see it. Trimmed because the whole thing reaches a browser toast.
-            const detail = (result.stderr?.toString() ?? '').trim().split('\n')[0]?.slice(0, 300);
+            const detail = result.stderr.trim().split('\n')[0]?.slice(0, 300);
             throw new ValidationError((isTar
                 ? 'tar.gz 압축 해제 실패 — 시뮬레이터용 .tar.gz(경로 탈출/심볼릭 링크 없는)인지 확인하세요.'
                 : 'zip 압축 해제 실패 — 시뮬레이터용 .app.zip 파일인지 확인하세요.')
@@ -2087,4 +2229,34 @@ export class IOSAgent {
         return this.simctl.openUrl(await this.soleLiveDeviceId(), url);
     }
 }
+/**
+ * Runs an archive tool without blocking, in the shape `spawnSync` returned: a spawn failure (the tool is
+ * missing) in `error`, otherwise the exit `status` and what it wrote to stderr. stdout is discarded — the
+ * tools run quiet, and nothing reads it.
+ */
+function runExtractor(cmd, args) {
+    return new Promise((resolve) => {
+        const child = spawn(cmd, args, { stdio: ['ignore', 'ignore', 'pipe'] });
+        let stderr = '';
+        // Decoded by the stream, not per chunk: a chunk boundary inside a multibyte character (a Korean file
+        // name in unzip's message) would otherwise turn into replacement characters.
+        child.stderr?.setEncoding('utf8');
+        child.stderr?.on('data', (chunk) => { if (stderr.length < 64 * 1024)
+            stderr += chunk; });
+        child.once('error', (error) => resolve({ error, status: null, stderr }));
+        child.once('close', (status) => resolve({ status, stderr }));
+    });
+}
+/**
+ * When to restart a screen stream that just ended. Only a run that delivered a frame resets the count — not
+ * how long it lasted: the helper retries `device.io` and its ports for up to ~10s before it gives up, so a
+ * duration rule would call every first-boot failure healthy. A simulator shut down from outside makes the
+ * helper exit at once, which without this was a restart loop at full speed.
+ */
+export function streamRestartPlan(previousFailures, deliveredFrame) {
+    if (deliveredFrame)
+        return { failures: 0, delayMs: 0 };
+    const failures = previousFailures + 1;
+    return { failures, delayMs: failures <= 1 ? 0 : Math.min(250 * 2 ** (failures - 2), 5000) };
+}
 //# sourceMappingURL=IOSAgent.js.map