@tapflowio/ios-agent 0.29.0 → 0.31.0

package/dist/GuestHelper.js

@@ -0,0 +1,437 @@
+import { execFile, spawn } from 'child_process';
+import { existsSync } from 'fs';
+import { join } from 'path';
+import { promisify } from 'util';
+import { createLogger } from '@tapflowio/agent-core';
+const logger = createLogger('ios-agent:guest-helper');
+const execFileAsync = promisify(execFile);
+// `bin/guest-helper` runs INSIDE the simulator (an iphonesimulator executable), so it is started through
+// `simctl spawn`, never directly. See `src/guest-helper.m` for its protocol and why it exists.
+export const GUEST_HELPER_BINARY = join(import.meta.dirname, '..', 'bin', 'guest-helper');
+// The same rolling window as TouchHelper, for the same reason it gives.
+const RESPAWN_LIMIT = 3;
+const RESPAWN_WINDOW_MS = 30_000;
+// `ready` comes after `simctl spawn` has started the guest process, the helper has registered its
+// services, and a 300 ms settle (a tap within 50 ms of registering is dropped, measured on Xcode 27.1).
+// The spawn alone measured ~0.6–0.9 s. **The bound is for a wedge, not a slow Mac**: on an 8 GB Mac mini
+// swapping 1.8 GB with a Duo up, the agent's own loop stalled 3.2 s, and an 8 s bound replaced three
+// healthy-but-slow helpers in a row.
+const READY_DEADLINE_MS = 15_000;
+// A command the helper answers with `done`: the fold sweep plays inside the helper (0.8 s), a key is held
+// for its own duration. Past this margin on top of that, the helper is treated as wedged and replaced —
+// generous for the reason READY_DEADLINE_MS gives: a 5 s margin replaced a helper mid-stall.
+const COMMAND_MARGIN_MS = 10_000;
+// A fold's margin, longer: the sweep can sit blocked while the device changes panel. Measured on that Mac
+// mini with a session streaming: a sweep went unanswered past 10.8 s although its panel lit at 10.6 s, so
+// the helper was replaced just after it had folded the device — and the next press, landing while the new
+// helper started, was refused. A late answer to a fold is harmless; it is what was asked for.
+const HINGE_MARGIN_MS = 30_000;
+const STOP_SIGKILL_AFTER_MS = 1_000;
+export const defaultGuestHelperNative = {
+    spawn(udid, args) {
+        // Detached so a terminal's Ctrl-C, which signals the whole process group, cannot take `simctl spawn`
+        // down before the agent's own cleanup runs — the guest would then be orphaned with nobody left to
+        // know its pid.
+        return spawn('xcrun', ['simctl', 'spawn', udid, GUEST_HELPER_BINARY, ...args], {
+            stdio: ['pipe', 'pipe', 'pipe'],
+            detached: true,
+        });
+    },
+    async findOrphans(udid) {
+        // **Found by search, not by memory.** An agent killed with -9 restarts knowing no pids, and a
+        // `simctl spawn` that died alone leaves the guest running (measured) — a respawn would then register
+        // a second set of services on the same displays. The udid in argv is what makes the match ours.
+        const marker = `--udid ${udid}`;
+        let out;
+        try {
+            out = (await execFileAsync('/usr/bin/pgrep', ['-f', `guest-helper ${marker}`], { timeout: 5_000 })).stdout;
+        }
+        catch {
+            return []; // pgrep exits 1 when nothing matches
+        }
+        const pids = [];
+        for (const pid of out.split('\n').map(Number).filter((n) => Number.isInteger(n) && n > 0 && n !== process.pid)) {
+            try {
+                const cmd = (await execFileAsync('/bin/ps', ['-o', 'command=', '-p', String(pid)], { timeout: 5_000 })).stdout;
+                if (cmd.includes(GUEST_HELPER_BINARY) && cmd.includes(marker))
+                    pids.push(pid);
+            }
+            catch { /* gone between the two calls */ }
+        }
+        return pids;
+    },
+    killPid(pid, signal) {
+        try {
+            process.kill(pid, signal);
+        }
+        catch { /* already gone, or not ours */ }
+    },
+    async unavailableReason() {
+        if (!existsSync(GUEST_HELPER_BINARY))
+            return `${GUEST_HELPER_BINARY} is missing — reinstall @tapflowio/ios-agent`;
+        try {
+            await execFileAsync('xcrun', ['--find', 'devicectl'], { timeout: 10_000 });
+        }
+        catch {
+            return 'devicectl was not found — install Xcode and select it with xcode-select';
+        }
+        return null;
+    },
+};
+/**
+ * The host side of `guest-helper`: one per multi-panel device, resident for the device's life.
+ *
+ * Its lifecycle follows TouchHelper's rules — readiness gates writes, a gesture belongs to the process
+ * that took its opening frame, deaths are replaced eagerly within a rolling budget — with three
+ * differences the guest process forces:
+ *  - the process the agent spawns is `simctl spawn`, not the helper; the helper's own pid arrives on
+ *    stdout and is killed separately, because the two do not die together;
+ *  - earlier helpers for the same device are found with `pgrep` and killed before every spawn;
+ *  - `fatal` is final: it means the runtime refused the private API, and spawning again would only
+ *    hear the same answer.
+ *
+ * **Running out of the respawn budget is not final**, which is TouchHelper's rule too ("it self-clears,
+ * so a session that briefly could not start a helper is not left without input until the device is
+ * rebooted"). A first version made it final, and a Mac short of memory turned one slow minute into a
+ * device with no input for the rest of its boot. The helper waits for the window to clear and launches
+ * again, answering `starting` meanwhile.
+ */
+export class GuestHelper {
+    udid;
+    touchscreens;
+    native;
+    options;
+    proc = null;
+    guestPid = null;
+    gestureProc = null;
+    ready = false;
+    stopped = false;
+    unavailable = null;
+    fatalReason = null;
+    spawns = [];
+    pending = [];
+    readyTimer = null;
+    readyWaiters = [];
+    generation = 0;
+    // Set while waiting out the respawn window after the budget ran out; cleared by the launch it schedules.
+    cooldown = null;
+    // The reason the helper last went out of service, until a ready says it is back.
+    outage = null;
+    // Between `start()` (or a respawn) and the spawn: sweeping orphans and reading the panels. Input sent
+    // then is told to wait, not that the channel is gone.
+    launching = false;
+    /**
+     * `touchscreens` is asked on every launch, not once: display UUIDs change on every boot, and a respawn
+     * after the device rebooted under the agent must register the new ones.
+     */
+    constructor(udid, touchscreens, native = defaultGuestHelperNative, options = {}) {
+        this.udid = udid;
+        this.touchscreens = touchscreens;
+        this.native = native;
+        this.options = options;
+    }
+    async start() {
+        this.stopped = false;
+        await this.launch();
+    }
+    stop() {
+        this.stopped = true;
+        this.launching = false;
+        if (this.cooldown) {
+            clearTimeout(this.cooldown);
+            this.cooldown = null;
+        }
+        this.generation++;
+        this.clearReadyDeadline();
+        this.failPending();
+        const proc = this.proc;
+        const guestPid = this.guestPid;
+        this.proc = null;
+        this.guestPid = null;
+        this.gestureProc = null;
+        this.ready = false;
+        this.settleReadyWaiters(false);
+        // EOF is the first line of defence (the helper exits on it, measured); the signals cover a helper
+        // that is wedged and a `simctl spawn` that outlives its child.
+        proc?.stdin?.end();
+        if (proc)
+            this.signalProcess(proc, 'SIGTERM');
+        if (guestPid)
+            this.native.killPid(guestPid, 'SIGTERM');
+        const timer = setTimeout(() => {
+            if (proc)
+                this.signalProcess(proc, 'SIGKILL');
+            if (guestPid)
+                this.native.killPid(guestPid, 'SIGKILL');
+        }, STOP_SIGKILL_AFTER_MS);
+        timer.unref?.();
+    }
+    inputState() {
+        if (this.proc && this.ready)
+            return 'ready';
+        if ((this.proc || this.launching || this.cooldown) && !this.unavailable)
+            return 'starting';
+        return 'unavailable';
+    }
+    /** Resolves true once the helper is ready, false if it becomes unavailable or is stopped first. */
+    whenReady() {
+        if (this.inputState() === 'ready')
+            return Promise.resolve(true);
+        if (this.unavailable || this.stopped)
+            return Promise.resolve(false);
+        return new Promise((resolve) => this.readyWaiters.push(resolve));
+    }
+    /** Why the helper cannot serve — for good, or for now — or null. */
+    unavailableReason() {
+        return this.unavailable ?? this.outage;
+    }
+    ownsGesture() {
+        return this.proc !== null && this.proc === this.gestureProc;
+    }
+    /** One finger on the panel whose display UUID is `screen`. Acked on the write, like Indigo: the helper
+     *  answers a touch only when it fails, and a drag is too many lines a second to wait on. */
+    touch(screen, phase, x, y, edge) {
+        return this.gestureFrame(phase, `touch ${screen} ${phase} ${x} ${y} ${edge ? 1 : 0}`);
+    }
+    pinch(screen, phase, x1, y1, x2, y2) {
+        return this.gestureFrame(phase, `pinch ${screen} ${phase} ${x1} ${y1} ${x2} ${y2}`);
+    }
+    hinge(fromDeg, toDeg, durationMs) {
+        return this.command(`hinge ${fromDeg} ${toDeg} ${durationMs}`, durationMs, HINGE_MARGIN_MS);
+    }
+    orient(value) {
+        return this.command(`orient ${value}`, 0);
+    }
+    key(usagePage, usage, holdMs, modifiers = []) {
+        const mods = modifiers.map(([p, u]) => ` ${p} ${u}`).join('');
+        return this.command(`key ${usagePage} ${usage} ${holdMs}${mods}`, holdMs);
+    }
+    /** Half of a held press — a long-press lasts as long as the tester holds it, like TouchHelper's
+     *  `pressButtonDown`/`Up`. */
+    keyDown(usagePage, usage) {
+        return this.command(`keydown ${usagePage} ${usage}`, 0);
+    }
+    keyUp(usagePage, usage) {
+        return this.command(`keyup ${usagePage} ${usage}`, 0);
+    }
+    gestureFrame(phase, line) {
+        if (phase === 'd') {
+            const sent = this.write(line);
+            // Only a delivered down owns the gesture — TouchHelper's `openGesture` explains why recording it
+            // unconditionally lets a fresh process receive an up for a touch it never saw.
+            this.gestureProc = sent ? this.proc : null;
+            return sent;
+        }
+        if (!this.ownsGesture())
+            return false;
+        return this.write(line);
+    }
+    command(line, playMs, marginMs = COMMAND_MARGIN_MS) {
+        const proc = this.proc;
+        if (!proc || !this.write(line))
+            return Promise.resolve(false);
+        return new Promise((resolve) => {
+            const timer = setTimeout(() => {
+                const at = this.pending.findIndex((p) => p.timer === timer);
+                if (at !== -1)
+                    this.pending.splice(at, 1);
+                resolve(false);
+                if (this.proc !== proc)
+                    return;
+                logger.error(`no answer to "${line}" within ${playMs + marginMs}ms — replacing the helper`);
+                // The guest would still act on a queued command after we gave up on it, so it goes, not only
+                // the simctl process that carries its pipe.
+                if (this.guestPid)
+                    this.native.killPid(this.guestPid, 'SIGKILL');
+                this.signalProcess(proc, 'SIGKILL');
+            }, playMs + marginMs);
+            timer.unref?.();
+            this.pending.push({ resolve, timer });
+        });
+    }
+    write(line) {
+        if (this.inputState() !== 'ready')
+            return false;
+        this.proc?.stdin?.write(`${line}\n`);
+        return true;
+    }
+    async launch() {
+        const generation = ++this.generation;
+        this.launching = true;
+        let screens;
+        try {
+            for (const pid of await this.native.findOrphans(this.udid)) {
+                logger.warn(`killing a leftover guest-helper (pid ${pid}) for ${this.udid}`);
+                this.native.killPid(pid, 'SIGKILL');
+            }
+            screens = await this.touchscreens();
+        }
+        catch (e) {
+            if (generation === this.generation)
+                this.launching = false;
+            if (!this.stopped && generation === this.generation) {
+                // Not final: `simctl io enumerate` can fail while a busy Mac is still bringing the device up.
+                this.spawns.push(Date.now());
+                this.retryLater(`could not read the device's panels: ${e instanceof Error ? e.message : String(e)}`);
+            }
+            return;
+        }
+        if (generation !== this.generation)
+            return;
+        this.launching = false;
+        if (this.stopped)
+            return;
+        this.spawns.push(Date.now());
+        this.ready = false;
+        this.guestPid = null;
+        const proc = this.native.spawn(this.udid, [
+            '--udid', this.udid, ...screens.flatMap((uuid) => ['--touchscreen', uuid]),
+        ]);
+        // A pid is the only synchronous sign the exec happened — TouchHelper's `spawnHelper` has the measurement.
+        if (proc.pid === undefined) {
+            proc.on('error', (e) => logger.error(`spawn error: ${e.message}`));
+            this.proc = null;
+            this.becomeUnavailable('could not start guest-helper through simctl spawn');
+            return;
+        }
+        this.proc = proc;
+        this.armReadyDeadline(proc);
+        let partial = '';
+        proc.stdout?.on('data', (d) => {
+            const lines = (partial + d.toString()).split('\n');
+            partial = lines.pop() ?? '';
+            for (const line of lines)
+                this.onLine(proc, line.trim());
+        });
+        proc.stderr?.on('data', (d) => logger.error(d.toString().trim()));
+        proc.on('exit', (code) => {
+            logger.warn(`guest-helper for ${this.udid} exited with code ${code ?? 'null'}`);
+            this.handleDeath(proc);
+        });
+        proc.on('error', (e) => {
+            logger.error(`spawn error: ${e.message}`);
+            this.handleDeath(proc);
+        });
+    }
+    onLine(proc, line) {
+        if (this.proc !== proc || !line)
+            return;
+        const [word, ...rest] = line.split(' ');
+        if (word === 'pid') {
+            const pid = Number(rest[0]);
+            if (Number.isInteger(pid) && pid > 0)
+                this.guestPid = pid;
+        }
+        else if (word === 'ready') {
+            this.ready = true;
+            this.clearReadyDeadline();
+            this.settleReadyWaiters(true);
+            if (this.outage) {
+                logger.info(`guest-helper back in service for ${this.udid}`);
+                this.outage = null;
+                this.options.onAvailable?.();
+            }
+        }
+        else if (word === 'done') {
+            this.pending.shift()?.resolve(rest[0] === '0');
+        }
+        else if (word === 'err') {
+            // A touch frame the guest refused. Touches are acked on the write, so this only gets logged.
+            logger.warn(`guest-helper refused: ${rest.slice(1).join(' ')} (status ${rest[0]})`);
+        }
+        else if (word === 'fatal') {
+            this.fatalReason = rest.join(' ') || 'guest-helper could not start';
+            this.becomeUnavailable(this.fatalReason);
+        }
+    }
+    handleDeath(proc) {
+        if (this.proc !== proc)
+            return;
+        this.clearReadyDeadline();
+        this.failPending();
+        this.proc = null;
+        this.guestPid = null;
+        this.ready = false;
+        if (this.stopped || this.fatalReason)
+            return;
+        const now = Date.now();
+        this.spawns = this.spawns.filter((t) => now - t < RESPAWN_WINDOW_MS);
+        if (this.spawns.length >= RESPAWN_LIMIT) {
+            this.retryLater(`guest-helper died ${RESPAWN_LIMIT} times in ${RESPAWN_WINDOW_MS / 1000}s`);
+            return;
+        }
+        void this.launch();
+    }
+    /** Out of service until the respawn window has room again, then launch. */
+    retryLater(reason) {
+        if (this.cooldown || this.stopped)
+            return;
+        const now = Date.now();
+        this.spawns = this.spawns.filter((t) => now - t < RESPAWN_WINDOW_MS);
+        const wait = this.spawns.length >= RESPAWN_LIMIT ? RESPAWN_WINDOW_MS - (now - this.spawns[0]) + 50 : 0;
+        logger.warn(`guest-helper out of service for ${this.udid}: ${reason} — trying again in ${Math.round(wait / 1000)}s`);
+        this.noteOutage(reason);
+        const timer = setTimeout(() => {
+            if (this.cooldown !== timer)
+                return;
+            this.cooldown = null;
+            if (!this.stopped)
+                void this.launch();
+        }, wait);
+        timer.unref?.();
+        this.cooldown = timer;
+    }
+    noteOutage(reason) {
+        if (this.outage)
+            return;
+        this.outage = reason;
+        this.options.onUnavailable?.(reason);
+    }
+    /** For good: the runtime refused the helper, or it could not be exec'd at all. */
+    becomeUnavailable(reason) {
+        if (this.unavailable)
+            return;
+        this.unavailable = reason;
+        this.ready = false;
+        this.settleReadyWaiters(false);
+        logger.error(`guest-helper unavailable for ${this.udid}: ${reason}`);
+        this.outage = null;
+        this.noteOutage(reason);
+    }
+    armReadyDeadline(proc) {
+        this.clearReadyDeadline();
+        const timer = setTimeout(() => {
+            if (this.proc !== proc || this.ready)
+                return;
+            logger.error(`no ready from guest-helper within ${READY_DEADLINE_MS}ms — replacing it`);
+            if (this.guestPid)
+                this.native.killPid(this.guestPid, 'SIGKILL');
+            this.signalProcess(proc, 'SIGKILL');
+        }, READY_DEADLINE_MS);
+        timer.unref?.();
+        this.readyTimer = timer;
+    }
+    clearReadyDeadline() {
+        if (this.readyTimer) {
+            clearTimeout(this.readyTimer);
+            this.readyTimer = null;
+        }
+    }
+    failPending() {
+        for (const p of this.pending.splice(0)) {
+            clearTimeout(p.timer);
+            p.resolve(false);
+        }
+    }
+    settleReadyWaiters(ok) {
+        for (const resolve of this.readyWaiters.splice(0))
+            resolve(ok);
+    }
+    /** `simctl spawn` was started detached, so it leads its own process group. */
+    signalProcess(proc, signal) {
+        if (proc.pid)
+            this.native.killPid(-proc.pid, signal);
+        proc.kill(signal);
+    }
+}
+//# sourceMappingURL=GuestHelper.js.map

package/dist/GuestHelper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"GuestHelper.js","sourceRoot":"","sources":["../src/GuestHelper.ts"],"names":[],"mappings":"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"}

package/dist/IOSAgent.d.ts

@@ -1,9 +1,13 @@
-import type { Device, DeviceAgent, NetworkControlCapability, NetworkStatePayload, UIElement } from '@tapflowio/agent-core';
+import type { Device, DeviceAgent, DevicePosture, NetworkControlCapability, NetworkStatePayload, PosturableAgent, UIElement } from '@tapflowio/agent-core';
+import type { LaunchOptions } from '@tapflowio/protocol';
 export declare const IOS_BUTTON_ALIASES: Record<string, string>;
 import { type SleepBlocker } from '@tapflowio/agent-core/utils';
 import { SimctlWrapper } from './SimctlWrapper.js';
 import { SimulatorNetwork } from './SimulatorNetwork.js';
 import { LeanStore } from './LeanStore.js';
+import { type GuestHelperNative } from './GuestHelper.js';
+import { PanelState } from './PanelState.js';
+import { PhysicalOrientation } from './PhysicalOrientation.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. */
@@ -31,8 +35,25 @@ export interface IOSAgentOptions {
     /** 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;
+    /** Which panel a multi-panel device shows (devicectl). Injectable so a suite never runs devicectl. */
+    panelState?: PanelState;
+    /** Which way a multi-panel device is held (devicectl). Injectable for the same reason. */
+    physicalOrientation?: PhysicalOrientation;
+    /** How a multi-panel device's in-simulator helper is spawned and found. Injectable for the same reason. */
+    guestHelperNative?: GuestHelperNative;
+    /** How long a fold may take to light its panel before it counts as failed. Injectable so a suite does not
+     *  wait the real 10 s on the path where it never does. */
+    foldSettleMs?: number;
+    /** How often a multi-panel device's lit panel is read while a session is on it, to follow a fold made
+     *  outside tapflow (DeviceHub). Injectable for the same reason. */
+    panelPollMs?: number;
+    /** The same, once nothing has moved for `panelQuietMs`. Injectable for the same reason. */
+    panelIdlePollMs?: number;
+    panelQuietMs?: number;
+    /** How long a boot waits for a multi-panel device's helper to be ready. Injectable for the same reason. */
+    helperBootReadyMs?: number;
 }
-export declare class IOSAgent implements DeviceAgent, NetworkControlCapability {
+export declare class IOSAgent implements DeviceAgent, NetworkControlCapability, PosturableAgent {
     private readonly simctl;
     private readonly network;
     private readonly fps;
@@ -96,6 +117,24 @@ export declare class IOSAgent implements DeviceAgent, NetworkControlCapability {
      */
     private readonly ownedDevices;
     private lastBundleIds;
+    private multiPanelDevices;
+    private deviceTypeIds;
+    private readonly guests;
+    private readonly guestScreens;
+    private readonly panelState;
+    private readonly physical;
+    private readonly typePanels;
+    private readonly guestHelperNative;
+    private readonly foldSettleMs;
+    private readonly panelPollMs;
+    private readonly panelIdlePollMs;
+    private readonly panelQuietMs;
+    private readonly helperBootReadyMs;
+    private readonly panelPolls;
+    private readonly panelActivity;
+    private readonly panelRechecks;
+    private readonly posturing;
+    private readonly reportedPosture;
     private readonly uiTreeReader;
     private readonly sleepBlocker;
     /** What the next "relay disconnected" line reports: when the relay last pinged, and the socket's last error. */
@@ -108,6 +147,7 @@ export declare class IOSAgent implements DeviceAgent, NetworkControlCapability {
      *  falling back to nothing would blank a form factor it already had until the next reconnect. */
     private formFactors;
     private resourcesTimer;
+    private resourcesInFlight;
     private readonly resources;
     private _stopping;
     private _reconnectTimer;
@@ -128,6 +168,9 @@ export declare class IOSAgent implements DeviceAgent, NetworkControlCapability {
     disconnect(): void;
     /** `loss` is absent when a reconnect attempt failed: there is no close to describe, only a retry. */
     private _scheduleReconnect;
+    /** 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. */
     private reportResources;
     private cleanupDeviceState;
     private stopAudioCapture;
@@ -197,6 +240,85 @@ export declare class IOSAgent implements DeviceAgent, NetworkControlCapability {
      */
     private clearPasteboardQueued;
     private ensureTouchHelper;
+    /**
+     * **The one place a device's input path is chosen** (see `InputChannel`). A device with more than one
+     * integrated panel gets `FoldableInput` over its in-simulator helper; every other device gets the Indigo
+     * `TouchHelper` it always had. A multi-panel device is never given a `TouchHelper`: its writes would
+     * answer success and land on a dark panel or nowhere.
+     */
+    private createInputChannel;
+    private ensureGuest;
+    /** The lit panel of a multi-panel device, from the last devicectl reading and this boot's panels. */
+    private litPanel;
+    /**
+     * How far the viewer turns a multi-panel device (`ChromeData.streamRotation`): the way it is held, plus the
+     * lit panel's own native turn — the Duo's unfolded panel is drawn turned 270, so a device held upright
+     * shows it turned 90 (measured: portrait → rot90 … landscapeLeft → rot0). Undefined for a single-panel
+     * device, and until both the orientation and the lit panel have been read.
+     */
+    private chromeRotation;
+    /** The cached frame with this send's turn and scale — never written into the loader's shared object. */
+    private forViewer;
+    /** The lit panel's frame for `DeviceChromeLoader`, or undefined for a single-panel device or an unknown panel. */
+    private chromePanel;
+    /** Point every stream of this device at its lit panel, and give its viewers that panel's frame. */
+    private applyLitPanel;
+    /**
+     * Load the lit panel's frame and send it as `session:chrome` to every session on this device whose frame
+     * it is not already. `session:chrome` is re-sendable by contract (protocol `InputPosture`), and the relay
+     * caches the last one for a re-joining viewer.
+     */
+    private resendChrome;
+    /** The display UUID of the panel a multi-panel device is showing, or null if not known yet. */
+    private litScreen;
+    /**
+     * Follow a fold made outside tapflow (DeviceHub's picker) while a session is on the device: read the lit
+     * panel, re-point the capture and the frame, and report the posture if it moved. Skipped while tapflow's own
+     * fold is in flight, which reports for itself.
+     */
+    private startPanelPoll;
+    private schedulePanelPoll;
+    /** The device's panel or orientation is moving, or about to: the poll goes back to its fast rate now, not
+     *  after the slow wait already scheduled. */
+    private panelMoved;
+    private followPanel;
+    /** The device's teardown: shut down, erased, or the agent leaving. Not a relay reconnect — see `guests`. */
+    private stopGuest;
+    listPostures(deviceId: string): Promise<DevicePosture[]>;
+    getPosture(deviceId: string): Promise<DevicePosture | null>;
+    setPosture(deviceId: string, postureId: string): Promise<void>;
+    /**
+     * Turn a multi-panel device the way it is held, through the helper (Purple and `devicectl orientation set`
+     * do nothing on the Duo — measured). From the orientation read back now, never one remembered: a quarter
+     * turn `direction`, or an older viewer's `target` — where either landscape meets landscape, so asking for
+     * it never flips one into the other, and portrait means upright. Then waits for devicectl to say so, which
+     * is what the re-sent chrome reports; a turn that does not land is logged and the chrome says where the
+     * device really is.
+     */
+    private turnHeld;
+    /**
+     * Where a single-panel device is held: read (devicectl on Xcode 27, the guest helper before — see
+     * `defaultPhysicalOrientationNative`), else the last known — the last reading, or what tapflow last set on a
+     * host where neither source answers. Read every time, never marked unreadable: one failure right after a
+     * boot would otherwise have left the device on memory for the life of the agent (review finding).
+     */
+    private heldSingle;
+    /** Turn a device nobody can say the orientation of upright, so there is one to turn from. */
+    private standUp;
+    /**
+     * Turn a single-panel device, through Purple: a quarter turn `direction` from where it is held, or an older
+     * viewer's `target`. **That viewer draws landscape as 270**, so `landscape` means exactly `landscapeLeft` —
+     * the other landscape would show it upside down — and is met only there; `portrait` means upright. A device
+     * whose orientation cannot be read or remembered (an agent restarted under it) is stood up first.
+     */
+    private turnSingle;
+    /** Re-send the frame each session on this device already has, with the turn it is held at now. */
+    private resendTurn;
+    /** `closed` while the cover is lit, `open` while the unfolded panel is. */
+    private postureOf;
+    /** Tell the viewer which postures exist and which one the device is in — read from the device, so a fold
+     *  made outside tapflow shows too. Sent at boot, after a change (failed or not), and on the helper dying. */
+    private sendPostures;
     private readonly clipboardQueue;
     private readonly parkedSentinels;
     private markSentinel;
@@ -316,7 +438,7 @@ export declare class IOSAgent implements DeviceAgent, NetworkControlCapability {
      */
     setNetworkOffline(offline: boolean): Promise<NetworkStatePayload>;
     networkState(): Promise<NetworkStatePayload>;
-    launchApp(bundleId: string): Promise<void>;
+    launchApp(bundleId: string, options?: LaunchOptions): Promise<void>;
     /** 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. */
@@ -367,7 +489,7 @@ export declare class IOSAgent implements DeviceAgent, NetworkControlCapability {
     private audioEnabled;
     private startAudioCapture;
     private launchWholeSimTap;
-    private refreshAudioPids;
+    private refreshAudio;
     private pumpAudio;
     screenshot(): Promise<Buffer>;
     stream(): ReadableStream<Buffer>;