@roku-sdk/device-test-client 0.0.0-stage → 2.19.0

package/src/client/client.ts

@@ -0,0 +1,1964 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+
+import {
+    EcpClient,
+    ROKU_INSTALLER_PORT,
+    tcpProbe,
+    xmlToJson,
+    xmlToKeyValue
+} from "@roku-sdk/tooling/src/device-test-helpers";
+import type { DeviceTarget } from "@roku-sdk/tooling/src/tooling-utils/device-target";
+import { PNG } from "pngjs";
+
+import { summarizeTree, tryFindNode } from "../assertions/assertions";
+import { pngsEqualOutsideMask, validateMasks } from "../assertions/screenshot-diff";
+import {
+    DEFAULT_KEY_DELAY,
+    DEFAULT_REQUEST_TIMEOUT_MS,
+    DEVICE_ONLINE_DEFAULT_TIMEOUT_MS,
+    DEVICE_ONLINE_POLL_INTERVAL_MS,
+    ECP_INTERVAL_MS,
+    ECP_RETRY_BACKOFF_MS,
+    ENV_VAR,
+    FOREGROUND_FAILURE_STREAK_FATAL,
+    HOME_SCREEN_GRACE_FRACTION,
+    HOME_SCREEN_GRACE_MIN_MS,
+    INSTALLER_PORT_PROBE_DEFAULT_TIMEOUT_MS,
+    INSTALLER_PORT_PROBE_INTERVAL_MS,
+    INSTALLER_PORT_TCP_TIMEOUT_MS,
+    INTEGRATION_BUILD_OUT_DIR,
+    LAUNCH_CRASH_RELAUNCH_GAP_MS,
+    LAUNCH_CRASH_RELAUNCH_MAX,
+    LOG_STREAM_RESYNC_GRACE_MS,
+    READINESS_CONFIRM_POLLS,
+    READINESS_POLL_INTERVAL_MS,
+    READINESS_TIMEOUT_MS,
+    ROKU_LOG_PORT,
+    SCREENSHOT_STABLE_DEFAULT_INTERVAL_MS,
+    SYSTEM_DIALOG_TAGS,
+    WAIT_FOR_LOG_DEFAULT_TIMEOUT_MS,
+    WAIT_FOR_LOG_RECENT_CHARS_MAX,
+    WAIT_FOR_LOG_RECENT_LINES_MAX,
+    WAIT_FOR_NODE_DEFAULT_INTERVAL_MS
+} from "../constants";
+import {
+    AppCrashedError,
+    BuildFailedError,
+    DeployFailedError,
+    DeviceOfflineError,
+    LogBufferOverflowError,
+    LogStreamGapError,
+    RkClientError,
+    ScreenshotNotStableError,
+    UnexpectedLogError,
+    WaitForLogTimeoutError,
+    WaitForNodeTimeoutError
+} from "../errors";
+import { LogBuffer, parsePos } from "../logs/log-buffer";
+import { LogSession } from "../logs/log-session";
+import type {
+    ActiveAppInfo,
+    AppUiNode,
+    BuildAndDeployOptions,
+    BuildAndLaunchWithParamsOptions,
+    CaptureStableOptions,
+    DeploymentDriver,
+    DeviceInfo,
+    EcpCategory,
+    KeySequenceOptions,
+    LaunchOptions,
+    LogBufferLike,
+    LogLine,
+    LogPosition,
+    LogQueryOptions,
+    LogSessionLike,
+    LogStreamHealth,
+    MaskRegion,
+    NodePredicate,
+    RkClientOptions,
+    SystemDialogNode,
+    WaitForDeviceFullyReadyOptions,
+    WaitForDeviceOnlineOptions,
+    WaitOptions
+} from "../types";
+import { getOrCreateBuildPromise, invalidateBuildCacheForApp } from "./build-cache";
+import type { ToolingDeps, ToolingDevice } from "./deploy";
+import {
+    buildLaunchPath,
+    buildLaunchUrl,
+    directoryExists,
+    loadToolingDeps,
+    normalizeKeyOrThrow,
+    postNoBody,
+    readAppTypeFromManifest,
+    requestServerBuild,
+    resolveAppPath
+} from "./deploy";
+import { EcpRequestQueue } from "./ecp-queue";
+import { isEcpServerError, isTransientEcpError, retryOnTransient } from "./ecp-retry";
+import {
+    hasForegroundedChannel,
+    markChannelForegrounded,
+    markDeviceFatal,
+    markDeviceUnhealthy,
+    noteForegroundFailure
+} from "./health";
+import { asNodeTuple, isHomeScreenActiveApp, parseActiveApp, parseDeviceInfo, tupleToAppUiNode } from "./parsers";
+import { resolveServerUrl as resolveServerUrlShared } from "./server-url";
+
+function resolveServerUrl(optsServerUrl?: string): string {
+    return resolveServerUrlShared({ serverUrl: optsServerUrl });
+}
+
+export class RkClient {
+    public readonly keyDelay: number;
+    public readonly deviceIp: string;
+
+    private ecp: EcpClient;
+    private readonly driver: DeploymentDriver | undefined;
+    private driverTarget: DeviceTarget | undefined;
+    private readonly queue: EcpRequestQueue;
+    private readonly requestTimeoutMs: number;
+    private readonly serverUrl: string;
+    private readonly logSession: LogSessionLike;
+    private _cachedDeviceInfo: DeviceInfo | null = null;
+
+    constructor(opts: RkClientOptions = {}) {
+        this.driver = opts.driver;
+        if (!opts.deviceIp && !opts.driver) {
+            throw new RkClientError(
+                `RkClient requires a deviceIp. Use createDefaultClient() for env-driven resolution.`,
+                "RK_DEVICE_IP_UNRESOLVED"
+            );
+        }
+        this.deviceIp = opts.deviceIp ?? opts.driver!.label;
+        this.keyDelay = opts.keyDelay ?? DEFAULT_KEY_DELAY;
+        this.requestTimeoutMs = opts.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
+        this.serverUrl = resolveServerUrl(opts.serverUrl);
+
+        this.driverTarget = opts.driver?.initialTarget;
+        this.ecp = new EcpClient(this.driverTarget ?? this.deviceIp, this.requestTimeoutMs);
+        this.queue = new EcpRequestQueue({ ...ECP_INTERVAL_MS, ...opts.intervals });
+        // Construction is free (no I/O); first `ensureStarted()` POSTs
+        // `/logs/start` and opens the SSE tail.
+        this.logSession =
+            opts.logSession ??
+            (opts.driver ? driverLogSession(opts.driver) : undefined) ??
+            new LogSession({
+                serverUrl: this.serverUrl,
+                device: this.deviceIp,
+                port: ROKU_LOG_PORT
+            });
+    }
+
+    /** Stop whatever the deployment driver started; no-op without one. Idempotent. */
+    async releaseDriver(): Promise<void> {
+        await this.driver?.release?.();
+    }
+
+    /** Accessor for the active `rk server` URL (for setup helpers). */
+    getServerUrl(): string {
+        return this.serverUrl;
+    }
+
+    /** Lazy-open the log session against `rk server`. Idempotent. */
+    async ensureLogSession(): Promise<void> {
+        await this.logSession.ensureStarted();
+    }
+
+    /**
+     * Close the local SSE subscription. Does NOT stop the server-side
+     * session — another worker may share it; global teardown owns that.
+     */
+    disposeLogSession(): void {
+        this.logSession.dispose();
+    }
+
+    /** Read-only accessor for the per-client `LogBuffer`. */
+    logBuffer(): LogBufferLike {
+        return this.logSession.buffer;
+    }
+
+    /**
+     * Return the last `n` buffered log entries, oldest first. Non-invasive:
+     * no ECP slot, no buffer mutation. On overflow, re-queries from the
+     * surviving `minAvailableSeq` in O(1) instead of scanning per-seq.
+     */
+    recentLogLines(n = 100): Array<{ seq: number; line: LogLine }> {
+        const requested = Math.max(0, Math.floor(n));
+        if (requested === 0) return [];
+        const buffer = this.logSession.buffer;
+        const currPos = Number.parseInt(buffer.currentPosition(), 10);
+        if (!Number.isFinite(currPos) || currPos <= 0) return [];
+        const desiredStart = Math.max(0, currPos - requested);
+        const tailFromStart = (start: number): Array<{ seq: number; line: LogLine }> => {
+            const entries = buffer.entriesSince(String(start));
+            const tail = entries.slice(Math.max(0, entries.length - requested));
+            return tail.map(e => ({ seq: e.seq, line: e.line }));
+        };
+        try {
+            return tailFromStart(desiredStart);
+        } catch (err) {
+            // Overflow — retry from the surviving `minAvailableSeq`.
+            if (!(err instanceof LogBufferOverflowError)) throw err;
+            const minAvailable = Number.parseInt(err.minAvailable, 10);
+            if (!Number.isFinite(minAvailable) || minAvailable >= currPos) return [];
+            // Defensive: if eviction races again, return [] rather than
+            // throw out of a non-invasive accessor.
+            try {
+                return tailFromStart(minAvailable);
+            } catch {
+                return [];
+            }
+        }
+    }
+
+    /**
+     * Snapshot of client-side gap accounting plus server-side reconnect
+     * metrics (`GET /api/logs/list`). Network failures yield
+     * `serverMetrics: null` — a reporter must never throw out of a
+     * diagnostic surface. Non-invasive: no ECP slot, no buffer mutation.
+     */
+    async getLogStreamHealth(): Promise<LogStreamHealth> {
+        const buffer = this.logSession.buffer;
+        const stats = buffer.getStats();
+        const base: LogStreamHealth = {
+            gapCount: stats.gapCount,
+            totalGapSeqSpan: stats.totalGapSeqSpan,
+            lastGapAt: stats.lastGapAt,
+            openGap: stats.openGap
+        };
+
+        // `serverUrl` is normalized to end with `/api`; append `/logs/list`
+        // only. Server keys sessions by (device, port); filter on deviceIp.
+        const url = `${trimTrailingSlash(this.serverUrl)}/logs/list`;
+        let res: Response;
+        try {
+            res = await fetch(url, { method: "GET", headers: { Accept: "application/json" } });
+        } catch {
+            return { ...base, serverMetrics: null };
+        }
+        if (!res.ok) {
+            return { ...base, serverMetrics: null };
+        }
+        let body: unknown;
+        try {
+            body = await res.json();
+        } catch {
+            return { ...base, serverMetrics: null };
+        }
+        const sessions = isObject(body) && Array.isArray(body.sessions) ? body.sessions : [];
+        const matched = sessions.find(
+            (s): s is Record<string, unknown> => isObject(s) && (s.ip === this.deviceIp || s.device === this.deviceIp)
+        );
+        if (!matched) {
+            // Reachable server, no matching session — `undefined` is
+            // distinct from `null` (network failure) for reporters.
+            return { ...base, serverMetrics: undefined };
+        }
+        const metrics = isObject(matched.metrics) ? matched.metrics : {};
+        return {
+            ...base,
+            serverMetrics: {
+                reconnectCount: numberOr(metrics.reconnectCount, 0),
+                totalDowntime: numberOr(metrics.totalDowntime, 0),
+                uptime: numberOr(metrics.uptime, 1),
+                connectedAt: stringOrNull(metrics.connectedAt),
+                lastActivity: stringOrNull(metrics.lastActivity)
+            }
+        };
+    }
+
+    // -----------------------------------------------------------------
+    // ECP methods
+    // -----------------------------------------------------------------
+
+    /**
+     * Fetch the SceneGraph node tree. Rate-limited at 200ms between calls.
+     * `bounds` is parsed to `{x,y,width,height}`; unparseable/missing
+     * values degrade to a zero-sized rect so callers get a shape, not a throw.
+     */
+    async queryAppUi(): Promise<AppUiNode> {
+        const xml = await this.runEcp("query-appui", () => this.ecp.query("/query/app-ui"));
+        const root = asNodeTuple(xmlToJson(xml));
+        if (!root) {
+            throw new RkClientError(
+                `Failed to parse /query/app-ui response from ${this.deviceIp}.`,
+                "ECP_APPUI_PARSE_FAILED"
+            );
+        }
+        return tupleToAppUiNode(root);
+    }
+
+    /**
+     * Fetch device metadata. Always re-queries ECP; result is cached on
+     * the instance. Use `cachedDeviceInfo()` to read without a network hit.
+     */
+    async queryDeviceInfo(): Promise<DeviceInfo> {
+        const xml = await this.runEcp("query-device-info", () => this.ecp.query("/query/device-info"));
+        const info = parseDeviceInfo(xmlToKeyValue(xml));
+        this._cachedDeviceInfo = info;
+        return info;
+    }
+
+    /** In-memory cached `DeviceInfo` snapshot, or null if never fetched. */
+    cachedDeviceInfo(): DeviceInfo | null {
+        return this._cachedDeviceInfo;
+    }
+
+    /** Prime the cache from an external source (avoids a second ECP hit per-worker). */
+    seedDeviceInfo(info: DeviceInfo): void {
+        this._cachedDeviceInfo = info;
+    }
+
+    /** Clear the cached `DeviceInfo`. Test-only. */
+    resetCache(): void {
+        this._cachedDeviceInfo = null;
+    }
+
+    /**
+     * Return the currently-active app, faithful to the ECP XML. The home
+     * screen has more than one shape across firmware, so test it with
+     * `isHomeScreenActiveApp` instead of comparing fields.
+     */
+    async queryActiveApp(): Promise<ActiveAppInfo> {
+        const xml = await this.runEcp("query-active-app", () => this.ecp.query("/query/active-app"));
+        const root = asNodeTuple(xmlToJson(xml));
+        if (!root) {
+            throw new RkClientError(
+                `Failed to parse /query/active-app response from ${this.deviceIp}.`,
+                "ECP_ACTIVEAPP_PARSE_FAILED"
+            );
+        }
+        return parseActiveApp(root);
+    }
+
+    /**
+     * PNG screenshot bytes; rate-limited at 500ms between captures. Throws on a driver-hosted run:
+     * pixel baselines are recorded from a physical device, so a capture from another host must fail
+     * loudly rather than compare against the wrong rendering and pass.
+     */
+    async captureScreenshot(): Promise<Buffer> {
+        this.assertScreenshotSupported();
+        return this.runEcp("capture", () => this.ecp.captureScreen("png"));
+    }
+
+    private assertScreenshotSupported(): void {
+        if (this.driver) {
+            throw new RkClientError(
+                `Screenshot capture is not supported on this target (deployment driver "${this.driver.label}"). ` +
+                    "Use app-ui queries, or run the test on a device.",
+                "SCREENSHOT_UNSUPPORTED_TARGET"
+            );
+        }
+    }
+
+    /**
+     * Validate and send one keypress. Invalid keys throw before hitting
+     * the queue so a typo in a test doesn't consume a slot.
+     */
+    async keypress(key: string): Promise<void> {
+        const normalized = normalizeKeyOrThrow(key);
+        await this.runEcp("keypress", async () => {
+            await this.ecp.keypress(normalized);
+        });
+    }
+
+    /**
+     * Hold a key down for `holdMs` (ECP keydown, wait, keyup). The release is
+     * sent even if the wait is interrupted, so a failed test never leaves a
+     * key stuck down on the target.
+     */
+    async holdKey(key: string, holdMs: number): Promise<void> {
+        const normalized = normalizeKeyOrThrow(key);
+        await this.runEcp("keypress", () => this.ecp.keypress(normalized, "keydown"));
+        try {
+            await sleepUnref(holdMs);
+        } finally {
+            await this.runEcp("keypress", () => this.ecp.keypress(normalized, "keyup"));
+        }
+    }
+
+    /**
+     * Send a sequence of keypresses with an inter-key delay (between end
+     * of one and start of next). All keys validated up-front so a typo
+     * deep in the sequence fails before any input is sent.
+     */
+    async keysequence(keys: string[], opts?: KeySequenceOptions): Promise<void> {
+        const normalized = keys.map(normalizeKeyOrThrow);
+        const delay = opts?.keyDelay ?? this.keyDelay;
+        for (let i = 0; i < normalized.length; i++) {
+            await this.runEcp("keypress", async () => {
+                await this.ecp.keypress(normalized[i]!);
+            });
+            if (i < normalized.length - 1 && delay > 0) {
+                await sleepUnref(delay);
+            }
+        }
+    }
+
+    /**
+     * Launch a channel via ECP `/launch/{channelId}` (defaults to `"dev"`),
+     * then block on the shared readiness + system-dialog gate. All failures
+     * surface as `DeployFailedError` with the device marked unhealthy.
+     */
+    async launch(opts?: LaunchOptions): Promise<void> {
+        const channelId = opts?.channelId ?? "dev";
+        const timeout = opts?.readinessTimeout ?? READINESS_TIMEOUT_MS;
+        try {
+            await this.launchAndAwaitReady(channelId, opts?.deepLink, timeout, opts?.readyNode);
+        } catch (err) {
+            // Readiness/dialog failures are already wrapped (health flag set);
+            // re-throw to avoid double-marking or losing structured context.
+            if (err instanceof DeployFailedError) throw err;
+            const reason = `ECP launch failed: ${errorMessage(err)}`;
+            markDeviceUnhealthy(`launch: ${reason}`);
+            throw new DeployFailedError(`Deploy failed: ${reason}`, {
+                deviceIp: this.deviceIp,
+                expectedChannelId: channelId,
+                phase: "launch",
+                cause: err
+            });
+        }
+    }
+
+    /**
+     * Shared launch path: POST `/launch/{channelId}` via the queue, then
+     * block on the readiness + dialog gate. HTTP errors propagate verbatim
+     * unless the auto-launch fallback below absorbs them; readiness/dialog
+     * failures already arrive as `DeployFailedError`.
+     *
+     * `logSince` marks where this launch's device log starts. A sideload
+     * passes the position from before `replace()`, which already launches
+     * the build; it defaults to the position before the POST.
+     */
+    private async launchAndAwaitReady(
+        channelId: string,
+        deepLink: Record<string, string> | undefined,
+        timeoutMs: number,
+        readyNode?: NodePredicate,
+        logSince: LogPosition = this.logPosition()
+    ): Promise<void> {
+        // The relaunch goes through `postLaunch`, so a driver-hosted run uses the driver's transport
+        // and never builds a URL from the driver's display label.
+        const gate = {
+            channelId,
+            timeoutMs,
+            readyNode,
+            relaunch: () => this.postLaunch(channelId, deepLink),
+            logSince
+        };
+        try {
+            await this.runEcp("launch", () => this.postLaunch(channelId, deepLink));
+        } catch (err) {
+            // Newer firmware auto-launches sideloaded `dev` builds after
+            // `replace()`, so the POST races a launch that is already
+            // under way. For plain sideload (no deep-link), fall back to
+            // waiting on the auto-launched app instead of treating the
+            // POST verdict as fatal.
+            if (channelId === "dev" && deepLink === undefined && isAutoLaunchTolerableError(err)) {
+                await this.awaitReadyAndCheckDialog(gate);
+                return;
+            }
+            throw err;
+        }
+        await this.awaitReadyAndCheckDialog(gate);
+    }
+
+    // -----------------------------------------------------------------
+    // Readiness & health helpers (shared by launch + buildAndDeploy)
+    // -----------------------------------------------------------------
+
+    /**
+     * Return the first root-level system-dialog child of `tree`, or null.
+     * Matches by tag against `SYSTEM_DIALOG_TAGS`.
+     */
+    static detectSystemDialog(tree: AppUiNode): SystemDialogNode | null {
+        for (const child of tree.children) {
+            if (SYSTEM_DIALOG_TAGS.has(child.tag)) {
+                return {
+                    tag: child.tag,
+                    title: child.attrs.title ?? "",
+                    node: child
+                };
+            }
+        }
+        return null;
+    }
+
+    /** Instance-level alias for `RkClient.detectSystemDialog`. */
+    detectSystemDialog(tree: AppUiNode): SystemDialogNode | null {
+        return RkClient.detectSystemDialog(tree);
+    }
+
+    /**
+     * What the device log since `since` says about `channelId`'s launch:
+     * whether it entered, and how many times it then exited with
+     * `EXIT_APP_ERROR`, the code for a channel that failed while starting.
+     * The log cannot tell a firmware launch failure from a build that
+     * crashes during mount; the relaunch cap and the failure streak bound
+     * what the second costs. Code that ran and then threw exits with
+     * another code and is not counted.
+     * An exit with no Entering line before it belongs to the build
+     * `replace()` ended. Reads only the client's buffer, so with no log
+     * session, or with `since` already evicted, it reports nothing.
+     */
+    private channelLaunchLog(since: LogPosition, channelId: string): { entered: boolean; failedLaunches: number } {
+        let lines: LogLine[];
+        try {
+            lines = this.logSession.buffer.linesSince(since);
+        } catch {
+            return { entered: false, failedLaunches: 0 };
+        }
+        const id = channelId.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+        const enter = new RegExp(`\\[scrpt\\.ctx\\.run\\.enter\\].*, id '${id}'`);
+        const failedExit = new RegExp(`\\[scrpt\\.ctx\\.run\\.exit\\].*, id '${id}', EXIT_APP_ERROR\\b`);
+        let entered = false;
+        let failedLaunches = 0;
+        for (const line of lines) {
+            if (enter.test(line)) {
+                entered = true;
+            } else if (entered && failedExit.test(line)) {
+                failedLaunches += 1;
+            }
+        }
+        return { entered, failedLaunches };
+    }
+
+    /**
+     * Re-request a launch the device log shows ending before the channel
+     * reached the screen. Best-effort: the readiness poll that follows
+     * judges the outcome, and a launcher busy with the previous attempt
+     * may reject the request.
+     */
+    private async relaunchAfterLaunchExit(
+        relaunch: () => Promise<void>,
+        channelId: string,
+        attempt: number
+    ): Promise<void> {
+        console.warn(
+            `[device-test-client] channel "${channelId}" exited before reaching the screen; ` +
+                `relaunching (${attempt}/${LAUNCH_CRASH_RELAUNCH_MAX}).`
+        );
+        try {
+            await this.runEcp("launch", relaunch);
+        } catch {
+            // See doc-block.
+        }
+    }
+
+    /**
+     * Single-shot crash probe used by polling loops between ticks.
+     * Throws `AppCrashedError` if active-app is a home surface — see
+     * `isHomeScreenActiveApp` for which variants that covers.
+     */
+    async assertAppAlive(context?: unknown): Promise<void> {
+        const active = await this.queryActiveApp();
+        if (isHomeScreenActiveApp(active)) {
+            throw new AppCrashedError(
+                `App crashed — active app is the home screen (id="${active.id}", title="${active.title}").`,
+                active,
+                context
+            );
+        }
+    }
+
+    /**
+     * Block until `/query/device-info` succeeds or the budget elapses.
+     * At least one probe always runs (do/while). Probe errors are
+     * absorbed and retried; the last is included on `DeviceOfflineError`
+     * so reporters can distinguish ECP 5xx storms from DNS unreachable.
+     */
+    async waitForDeviceOnline(opts: WaitForDeviceOnlineOptions = {}): Promise<DeviceInfo> {
+        const timeoutMs = opts.timeoutMs ?? DEVICE_ONLINE_DEFAULT_TIMEOUT_MS;
+        const intervalMs = opts.intervalMs ?? DEVICE_ONLINE_POLL_INTERVAL_MS;
+        const startedAt = Date.now();
+        const deadline = startedAt + Math.max(0, timeoutMs);
+        let attempts = 0;
+        let lastError: unknown;
+
+        // do/while so `timeoutMs: 0` still gets exactly one attempt —
+        // matches the "always try once" contract of our other poll helpers.
+        do {
+            attempts += 1;
+            try {
+                return await this.queryDeviceInfo();
+            } catch (err) {
+                lastError = err;
+            }
+            const remaining = deadline - Date.now();
+            if (remaining <= 0) break;
+            await sleepUnref(Math.min(intervalMs, remaining));
+        } while (Date.now() < deadline);
+
+        throw new DeviceOfflineError(
+            `Device ${this.deviceIp} did not respond to /query/device-info within ${timeoutMs}ms (attempts=${attempts}).${
+                lastError ? ` Last error: ${errorMessage(lastError)}` : ""
+            }`,
+            { deviceIp: this.deviceIp, timeoutMs, attempts, lastError, reason: "ecp" }
+        );
+    }
+
+    /**
+     * Block until the device is ready to accept ANOTHER deploy: ECP
+     * (`/query/device-info` on port 8060) AND the sideload installer
+     * (TCP/80) are both reachable. Phases run in order — ECP first,
+     * installer second — so a flapping ECP doesn't waste the installer
+     * budget on TCP probes that will be invalidated by the next reboot.
+     *
+     * Why this exists: `waitForDeviceOnline` only proves ECP liveness.
+     * After a crash/reboot the installer lags ECP recovery by several
+     * seconds on reference hardware; a deploy issued in that window
+     * surfaces the misleading "Device is not reachable on the network"
+     * diagnostic from `sideload-diagnostics`. This method is the broader
+     * gate `installDeployGuard` wants between failed deploy attempts.
+     *
+     * Failure modes:
+     *   - ECP arm exhausts → `DeviceOfflineError` with `reason: "ecp"`.
+     *   - ECP arm passes, installer arm exhausts → `DeviceOfflineError`
+     *     with `reason: "installer"` and `tcpStatus` set to the last
+     *     `tcpProbe` status (`"closed" | "timeout" | "unreachable"`).
+     *
+     * On success the cached `DeviceInfo` is primed (matches
+     * `waitForDeviceOnline`'s contract) so callers can read it without
+     * an extra ECP round-trip.
+     */
+    async waitForDeviceFullyReady(opts: WaitForDeviceFullyReadyOptions = {}): Promise<DeviceInfo> {
+        const ecpTimeoutMs = opts.ecpTimeoutMs ?? DEVICE_ONLINE_DEFAULT_TIMEOUT_MS;
+        const ecpIntervalMs = opts.ecpIntervalMs ?? DEVICE_ONLINE_POLL_INTERVAL_MS;
+        const installerTimeoutMs = opts.installerTimeoutMs ?? INSTALLER_PORT_PROBE_DEFAULT_TIMEOUT_MS;
+        const installerIntervalMs = opts.installerIntervalMs ?? INSTALLER_PORT_PROBE_INTERVAL_MS;
+
+        // Phase A: ECP responder. Re-throws verbatim so the existing
+        // `reason: "ecp"` taxonomy on `DeviceOfflineError` is preserved.
+        const info = await this.waitForDeviceOnline({
+            timeoutMs: ecpTimeoutMs,
+            intervalMs: ecpIntervalMs
+        });
+
+        // Phase B: installer accepts a TCP connection. `do/while` so a
+        // `installerTimeoutMs: 0` budget still gets one probe — matches
+        // `waitForDeviceOnline`'s "always try once" contract.
+        const phaseBStart = Date.now();
+        const phaseBDeadline = phaseBStart + Math.max(0, installerTimeoutMs);
+        let attempts = 0;
+        let lastStatus = "unknown";
+        let lastErrorMessage: string | undefined;
+
+        // With a driver the installer arm is not probed from here: a driver's label is not an address, and
+        // the driver's own deploy retries until its host accepts the sideload, which is the readiness
+        // signal for `replace()` (the RCE driver included).
+        if (this.driver) return info;
+
+        do {
+            attempts += 1;
+            const result = await tcpProbe(this.deviceIp, ROKU_INSTALLER_PORT, INSTALLER_PORT_TCP_TIMEOUT_MS);
+            lastStatus = result.status;
+            lastErrorMessage = result.errorMessage;
+            if (result.status === "open") {
+                return info;
+            }
+            const remaining = phaseBDeadline - Date.now();
+            if (remaining <= 0) break;
+            await sleepUnref(Math.min(installerIntervalMs, remaining));
+        } while (Date.now() < phaseBDeadline);
+
+        throw new DeviceOfflineError(
+            `Device ${this.deviceIp} ECP recovered but installer port ${ROKU_INSTALLER_PORT} did not accept TCP within ${installerTimeoutMs}ms (attempts=${attempts}, lastStatus=${lastStatus}).${
+                lastErrorMessage ? ` Last error: ${lastErrorMessage}` : ""
+            }`,
+            {
+                deviceIp: this.deviceIp,
+                timeoutMs: installerTimeoutMs,
+                attempts,
+                reason: "installer",
+                tcpStatus: lastStatus
+            }
+        );
+    }
+
+    /**
+     * Wait until the app is interactive, then check for system dialogs.
+     *
+     * Each poll requires (a) `/query/active-app` matches `channelId` AND
+     * (b) the predicate (caller-supplied `readyNode`, or `children.length > 0`
+     * fallback) passes on the same iteration — avoids one-tick races where
+     * the app is launching but the scene has not rendered.
+     *
+     * A poll also requires (c) no firmware overlay (`osd`) left in the
+     * tree, so "ready" means the app owns the screen rather than
+     * merely having rendered behind the launch facade.
+     *
+     * Stability: requires `READINESS_CONFIRM_POLLS` consecutive matches
+     * before declaring ready, catching the "crash shortly after splash"
+     * pattern. Home-screen responses are tolerated while we have not
+     * seen any evidence that the app launched; slow sideload→launch
+     * handoffs are indistinguishable from a never-started app until
+     * the full readiness budget expires. Once we HAVE seen app-owned
+     * evidence, a persistent post-grace Home response is classified as
+     * crashed-after-ready.
+     *
+     * The device log since `logSince` is the one signal that separates a
+     * launch that started and failed from one that never started: when it
+     * shows the channel exiting with `EXIT_APP_ERROR` after it entered,
+     * and the screen is Home past the grace window, `relaunch` is
+     * called again, up to `LAUNCH_CRASH_RELAUNCH_MAX` times.
+     */
+    private async awaitReadyAndCheckDialog(opts: {
+        channelId: string;
+        timeoutMs: number;
+        readyNode?: NodePredicate;
+        relaunch: () => Promise<void>;
+        logSince: LogPosition;
+    }): Promise<void> {
+        const startedAt = Date.now();
+        const deadline = startedAt + opts.timeoutMs;
+        // Race-guard: tolerate home-screen for the leading grace fraction
+        // of the budget (with an absolute floor) so a tiny readiness budget
+        // cannot collapse the grace below the observed transition window.
+        const homeScreenGraceMs = Math.max(
+            HOME_SCREEN_GRACE_MIN_MS,
+            Math.floor(opts.timeoutMs * HOME_SCREEN_GRACE_FRACTION)
+        );
+        let lastTree: AppUiNode | undefined;
+        let lastActiveApp: ActiveAppInfo | undefined;
+        // Consecutive predicate matches required to declare ready;
+        // the follow-ups catch crashes right after first render.
+        let consecutiveMatches = 0;
+        // Sticky: did we ever observe a predicate match in this run?
+        // Stays true across home-screen-induced counter resets so the
+        // post-grace branch can distinguish "slow or never launched"
+        // (no prior match, keep polling until timeout) from
+        // "crashed-after-ready" (had a prior match). Required because
+        // Roku's InstantOn pre-warm transiently surfaces the app+tree
+        // before the real launch starts; the intervening home-screen
+        // window must not be misclassified as a crash.
+        let hadAnyMatch = false;
+        // Sticky: did we ever observe this channel at all, even if the
+        // caller's readyNode never matched. Negative readyNode tests and
+        // slow app boots can render a real app tree, then transiently hop
+        // through Home before the deadline. That is not "never left home";
+        // keep polling so the final error preserves the readiness-timeout
+        // contract with the last app tree attached.
+        let hadChannelEvidence = false;
+        // Stronger than `hadChannelEvidence`: active-app or plugin-tree
+        // explicitly identified the target channel. Once this is true,
+        // a later Home report is a crash signal rather than active-app lag.
+        let hadActiveChannelEvidence = false;
+        // Each logged launch failure earns at most one relaunch.
+        let relaunches = 0;
+        let lastLaunchAt = startedAt;
+        let failuresAnswered = 0;
+
+        // App-owned evidence of any kind — the channel in the tree, or its
+        // own ready node rendering — proves this VM foregrounds a sideloaded
+        // channel, which disqualifies the fatal verdict at the end of this
+        // method for the rest of the run. Reaching readiness is sufficient
+        // but not necessary: an app that renders and then never satisfies
+        // the caller's predicate still got foregrounded.
+        const noteChannelEvidence = (): void => {
+            hadChannelEvidence = true;
+            markChannelForegrounded(this.deviceIp);
+        };
+
+        const treeContainsChannel = (node: AppUiNode, channelId: string): boolean => {
+            if (node.tag === "plugin" && node.attrs?.id === channelId) {
+                return true;
+            }
+            return node.children.some(child => treeContainsChannel(child, channelId));
+        };
+
+        // A firmware overlay still in the tree — the launch facade a
+        // channel start puts up, reported as `<osd type="FacadeScreen"
+        // focused="true">`. The app's own nodes can already be behind
+        // it, so a predicate match on its own proves neither that the
+        // app is on screen nor that it can receive a key; a caller that
+        // captures a tree or presses a key the moment we return gets a
+        // node the baseline never had, and presses the facade swallows.
+        // Any `osd` counts, not just a focused one: it is firmware
+        // chrome either way, and a launched app's steady state has none.
+        const treeContainsOverlay = (node: AppUiNode): boolean =>
+            node.children.some(child => child.tag === "osd" || treeContainsOverlay(child));
+
+        while (Date.now() < deadline) {
+            const active = await this.queryActiveApp();
+            lastActiveApp = active;
+
+            // channelId "dev" matches when active.id === "dev" (sideloaded).
+            // For published channels we accept exact id match.
+            const idMatches = active.id === opts.channelId;
+            let tree: AppUiNode | undefined;
+            let channelVisibleInTree = false;
+            if (idMatches || isHomeScreenActiveApp(active)) {
+                try {
+                    tree = await this.queryAppUi();
+                    lastTree = tree;
+                    // Some firmware lags `/query/active-app` behind the
+                    // SceneGraph tree during sideload launch — trust the
+                    // tree as a stronger signal than active-app.
+                    channelVisibleInTree = treeContainsChannel(tree, opts.channelId);
+                    if (idMatches || channelVisibleInTree) {
+                        noteChannelEvidence();
+                        hadActiveChannelEvidence = true;
+                    }
+                } catch (err) {
+                    // Sparse XML during the launch→first-commit window is
+                    // expected; any other error must propagate.
+                    if (err instanceof RkClientError && err.code === "ECP_APPUI_PARSE_FAILED") {
+                        consecutiveMatches = 0;
+                        await sleepUnref(READINESS_POLL_INTERVAL_MS);
+                        continue;
+                    }
+                    throw err;
+                }
+            }
+
+            const predicateMatches = tree
+                ? opts.readyNode
+                    ? tryFindNode(tree, opts.readyNode) !== null
+                    : tree.children.length > 0
+                : false;
+            // On some firmware `/query/active-app` can briefly report Home
+            // while `/query/app-ui` has already switched to the sideloaded
+            // SceneGraph tree. A caller-provided readyNode is app-specific
+            // evidence, so trust it as a stronger signal than active-app.
+            const readyNodeVisibleWhileHome = Boolean(
+                opts.readyNode && isHomeScreenActiveApp(active) && predicateMatches && !hadActiveChannelEvidence
+            );
+            if (tree && (idMatches || channelVisibleInTree || readyNodeVisibleWhileHome)) {
+                // The overlay check shares the stability counter rather
+                // than draining separately: the layer can blink out and
+                // back while it tears down, and `READINESS_CONFIRM_POLLS`
+                // consecutive clean polls already require it to be gone
+                // and stay gone.
+                if (predicateMatches && !treeContainsOverlay(tree)) {
+                    // Dialog check on every match: a dialog appearing AFTER
+                    // first-render must still fail the deploy.
+                    const dialog = RkClient.detectSystemDialog(tree);
+                    if (dialog) {
+                        const reason = `system dialog detected: ${dialog.tag}${dialog.title ? ` ("${dialog.title}")` : ""}`;
+                        markDeviceUnhealthy(reason);
+                        throw new DeployFailedError(`Deploy failed: ${reason}`, {
+                            deviceIp: this.deviceIp,
+                            expectedChannelId: opts.channelId,
+                            phase: "readiness",
+                            reason: "system-dialog",
+                            dialog,
+                            lastTree: tree,
+                            lastActiveApp: active
+                        });
+                    }
+                    consecutiveMatches += 1;
+                    hadAnyMatch = true;
+                    noteChannelEvidence();
+                    if (consecutiveMatches >= READINESS_CONFIRM_POLLS) {
+                        return;
+                    }
+                } else {
+                    // Reset the stability counter on any miss.
+                    consecutiveMatches = 0;
+                }
+            } else {
+                // Home screen here = either a slow/never launch (no prior
+                // app-owned evidence) or crashed-after-ready (had a prior
+                // match). Crash decisions are deferred until we are past
+                // the grace window: Roku's InstantOn pre-warm transiently
+                // exits the app back to the launcher before the real
+                // launch starts, and we MUST tolerate that flip-flop
+                // for the leading slice of the readiness budget. With no
+                // prior evidence, keep polling until the full timeout; in
+                // CI, cold sideloads can stay on Home beyond the
+                // grace window and still launch successfully.
+                if (isHomeScreenActiveApp(active)) {
+                    const pastGrace = Date.now() - startedAt >= homeScreenGraceMs;
+                    if (pastGrace) {
+                        if (hadAnyMatch) {
+                            const reason = `app crashed between first render and stability confirmation (active.id="${active.id}", title="${active.title}")`;
+                            markDeviceUnhealthy(`deploy: ${reason}`);
+                            throw new DeployFailedError(`Deploy failed: ${reason}`, {
+                                deviceIp: this.deviceIp,
+                                expectedChannelId: opts.channelId,
+                                phase: "readiness",
+                                reason: "crashed-after-ready",
+                                lastTree,
+                                lastActiveApp: active
+                            });
+                        }
+                        // Active-app can report the channel for the
+                        // fraction of a second a failed launch lasts, so
+                        // channel evidence does not rule a relaunch out.
+                        if (
+                            relaunches < LAUNCH_CRASH_RELAUNCH_MAX &&
+                            Date.now() - lastLaunchAt >= LAUNCH_CRASH_RELAUNCH_GAP_MS
+                        ) {
+                            const { failedLaunches } = this.channelLaunchLog(opts.logSince, opts.channelId);
+                            if (failedLaunches > failuresAnswered) {
+                                failuresAnswered = failedLaunches;
+                                relaunches += 1;
+                                lastLaunchAt = Date.now();
+                                await this.relaunchAfterLaunchExit(opts.relaunch, opts.channelId, relaunches);
+                            }
+                        }
+                        if (hadChannelEvidence && opts.readyNode) {
+                            // The app launched but never satisfied the
+                            // caller's readiness predicate. Do not relabel
+                            // that as "never-left-home" just because the
+                            // firmware reports Home on a later poll.
+                            consecutiveMatches = 0;
+                            await sleepUnref(READINESS_POLL_INTERVAL_MS);
+                            continue;
+                        }
+                    }
+                    // Within grace: home screen is a transient handoff
+                    // (InstantOn pre-warm exit, or sideload→launch
+                    // window). Reset stability and keep polling — a
+                    // subsequent real launch can still pass the gate.
+                }
+                // Active is some other app (launcher, different channel)
+                // or home-within-grace — reset stability counter; any
+                // prior tentative match is invalid for stability.
+                consecutiveMatches = 0;
+            }
+
+            await sleepUnref(READINESS_POLL_INTERVAL_MS);
+        }
+
+        if (lastActiveApp && isHomeScreenActiveApp(lastActiveApp) && !hadChannelEvidence) {
+            const launchLog = this.channelLaunchLog(opts.logSince, opts.channelId);
+            const exitDetail =
+                launchLog.failedLaunches > 0
+                    ? `; channel exited during launch ${launchLog.failedLaunches} time(s), relaunched ${relaunches} time(s)`
+                    : "";
+            const reason = `app never left home screen after launch (active.id="${lastActiveApp.id}", title="${lastActiveApp.title}"${exitDetail})`;
+            // Home for the whole budget with no channel evidence is either a
+            // foreground-incapable VM or a launch slower than the budget,
+            // and within a single deploy the two are identical. An earlier
+            // deploy that reached readiness on this VM breaks the tie: a
+            // device that has foregrounded a channel is not incapable of it,
+            // so the fault belongs to this launch and stays soft, letting
+            // the deploy-guard retry this deploy alone. The device log
+            // showing this deploy's channel entering breaks it the same
+            // way: the launch ran and died, so the VM can run one.
+            //
+            // Without that history, latch FATAL: ECP/installer liveness
+            // recovery cannot cure a foreground-incapable VM, so the
+            // deploy-guard and recovery hook short-circuit on the latch
+            // instead of retrying every remaining suite against a dead VM.
+            // History earns a bounded number of soft verdicts, not an
+            // unlimited supply: a VM that worked and then died looks
+            // exactly like a bad launch from inside any single deploy,
+            // and staying soft forever means every remaining suite pays
+            // a full deploy budget against a dead VM until the job's own
+            // wall-clock kills it, which recycles nothing and retries
+            // nothing. Past the streak the verdict reverts to fatal so
+            // the cell recycles the slot and the job is retried on a
+            // live one.
+            if (
+                (hasForegroundedChannel(this.deviceIp) || launchLog.entered) &&
+                noteForegroundFailure(this.deviceIp) < FOREGROUND_FAILURE_STREAK_FATAL
+            ) {
+                markDeviceUnhealthy(`deploy: ${reason}`);
+            } else {
+                markDeviceFatal(`deploy: ${reason}`);
+            }
+            throw new DeployFailedError(`Deploy failed: ${reason}`, {
+                deviceIp: this.deviceIp,
+                expectedChannelId: opts.channelId,
+                phase: "readiness",
+                reason: "never-left-home",
+                lastTree,
+                lastActiveApp
+            });
+        }
+
+        const detail = opts.readyNode
+            ? `predicate ${JSON.stringify(opts.readyNode)} never matched`
+            : `no children in tree`;
+        const reason = `readiness timeout after ${opts.timeoutMs}ms waiting for active-app="${opts.channelId}" (${detail})`;
+        markDeviceUnhealthy(reason);
+        throw new DeployFailedError(`Deploy failed: ${reason}`, {
+            deviceIp: this.deviceIp,
+            expectedChannelId: opts.channelId,
+            phase: "readiness",
+            reason: "readiness-timeout",
+            lastTree,
+            lastActiveApp
+        });
+    }
+
+    // -----------------------------------------------------------------
+    // Polling helpers (waitForNode + log/screenshot convergence)
+    // -----------------------------------------------------------------
+
+    /**
+     * Poll `queryAppUi()` until `predicate` matches or `opts.timeout`
+     * elapses. Each iteration: crash probe → fresh tree → match attempt.
+     *
+     * `opts.interval` is a gap-based minimum (iteration-start to next
+     * iteration-start), not a fixed sleep, so we don't double-sleep on
+     * top of the ECP queue's 200ms cadence. On timeout, throws
+     * `WaitForNodeTimeoutError` carrying the last tree for diagnostics.
+     */
+    async waitForNode(predicate: NodePredicate, opts: WaitOptions): Promise<AppUiNode> {
+        const interval = opts.interval ?? WAIT_FOR_NODE_DEFAULT_INTERVAL_MS;
+        const timeoutMs = opts.timeout;
+        const deadline = Date.now() + timeoutMs;
+        let lastTree: AppUiNode | null = null;
+
+        // do/while so a single iteration runs even at `timeoutMs <= 0`,
+        // populating `lastTree` for the timeout diagnostic.
+        do {
+            const iterStart = Date.now();
+            await this.assertAppAlive({ operation: "waitForNode", predicate });
+            // Errors from queryAppUi propagate verbatim — callers need the
+            // structured RkClientError/ToolingError code to react.
+            lastTree = await this.queryAppUi();
+            const match = tryFindNode(lastTree, predicate);
+            if (match) return match;
+
+            const now = Date.now();
+            const remaining = deadline - now;
+            if (remaining <= 0) break;
+
+            // Gap-based: only sleep for the slack between iteration
+            // duration and the caller's desired minimum.
+            const slack = interval - (now - iterStart);
+            if (slack > 0) {
+                await sleepUnref(Math.min(slack, remaining));
+            } else if (interval === 0) {
+                // 1ms yield avoids tight-spin when both `interval` and the
+                // queue gap are 0; smallest value guaranteed to post-pone
+                // the next iteration across Node/jsdom/browser envs.
+                await sleepUnref(1);
+            }
+        } while (Date.now() < deadline);
+
+        const preview = lastTree ? `\nLast tree (summary):\n${summarizeTree(lastTree, 2, 600)}` : "";
+        throw new WaitForNodeTimeoutError(
+            `waitForNode timed out after ${timeoutMs}ms waiting for ${JSON.stringify(predicate)}.${preview}`,
+            { predicate, timeoutMs, lastTree }
+        );
+    }
+
+    /**
+     * Opaque snapshot of the current log-stream position. Synchronous so
+     * callers can grab a baseline before an action and prove causality
+     * with a follow-up `waitForLog`. A fresh client reports `"0"` even
+     * before the session has attached.
+     */
+    logPosition(): LogPosition {
+        return this.logSession.buffer.currentPosition();
+    }
+
+    /**
+     * Wait for a line matching `pattern` at or after `opts.since`.
+     * Buffered matches outside any gap resolve immediately; otherwise
+     * we subscribe for the first live clean match. On timeout, a gap
+     * within the wait window surfaces as `LogStreamGapError` (we can't
+     * disambiguate "marker fell into the gap"); otherwise
+     * `WaitForLogTimeoutError` with the recent-lines preview.
+     *
+     * Matches whose seq is itself inside a gap are skipped (the line
+     * could be partial/concatenated at the reconnect boundary).
+     * `expectNoLog` is the asymmetric strict counterpart: absence is
+     * unprovable across a gap.
+     *
+     * A window in which no line arrived at all gets one re-attach
+     * before the verdict: a subscription can stop delivering while
+     * both ends still believe it is attached, and from inside the
+     * wait that is indistinguishable from a device with nothing to
+     * say. See `LogSession.resync`.
+     */
+    async waitForLog(pattern: RegExp, opts: LogQueryOptions): Promise<LogLine> {
+        await this.ensureLogSession();
+        const buffer = this.logSession.buffer;
+        const since = opts.since;
+        const timeoutMs = opts.timeout ?? WAIT_FOR_LOG_DEFAULT_TIMEOUT_MS;
+
+        // Existing-match scan: accept the first match whose seq is
+        // outside every recorded gap; fall through to the live wait
+        // if none clean exists.
+        const existing = buffer.entriesSince(since);
+        let linesChecked = 0;
+        for (const e of existing) {
+            linesChecked += 1;
+            if (pattern.test(e.line)) {
+                const gap = buffer.findGapContaining(e.seq);
+                if (gap) {
+                    // Suspect line at a reconnect boundary — keep scanning.
+                    continue;
+                }
+                return e.line;
+            }
+        }
+
+        return new Promise<LogLine>((resolve, reject) => {
+            let settled = false;
+            let timer: ReturnType<typeof setTimeout> | undefined;
+            let resyncTried = false;
+            const recent: LogLine[] = [];
+            const settle = (fn: () => void): void => {
+                if (settled) return;
+                settled = true;
+                unsubscribe();
+                if (timer !== undefined) clearTimeout(timer);
+                fn();
+            };
+            const arm = (ms: number, onFire: () => void): void => {
+                timer = setTimeout(onFire, ms);
+                // Don't keep the event loop alive purely for this timer.
+                if (typeof (timer as { unref?: () => unknown }).unref === "function") {
+                    (timer as { unref: () => unknown }).unref();
+                }
+            };
+            const unsubscribe = buffer.subscribe(entry => {
+                if (settled) return;
+                linesChecked += 1;
+                recent.push(entry.line);
+                if (recent.length > WAIT_FOR_LOG_RECENT_LINES_MAX) {
+                    recent.shift();
+                }
+                if (pattern.test(entry.line)) {
+                    // Skip matches inside a gap (line may be partial); a
+                    // later clean line may still satisfy the assertion.
+                    const gap = buffer.findGapContaining(entry.seq);
+                    if (gap) return;
+                    settle(() => resolve(entry.line));
+                }
+            });
+            const onDeadline = (): void => {
+                if (settled) return;
+                // A gap inside the window makes a non-result ambiguous;
+                // surface the gap rather than a bare timeout.
+                const gap = buffer.hasGapWithin(since);
+                if (gap) {
+                    settle(() =>
+                        reject(
+                            new LogStreamGapError(gapMessage("waitForLog", pattern, gap), {
+                                gapStart: String(gap.start),
+                                gapEnd: String(gap.end)
+                            })
+                        )
+                    );
+                    return;
+                }
+                // Not one line in the whole window, which an app with
+                // nothing to say and a stream that stopped delivering
+                // both produce, so re-attach and let the replay land
+                // before calling the marker absent. The subscription
+                // above stays live, so a replayed match resolves
+                // through it, and a replay that adds nothing is what
+                // narrows the verdict below to the app's own silence.
+                if (!resyncTried && linesChecked === 0 && typeof this.logSession.resync === "function") {
+                    resyncTried = true;
+                    arm(LOG_STREAM_RESYNC_GRACE_MS, onDeadline);
+                    void this.logSession.resync().catch(() => {
+                        // A failed re-attach adds no evidence; the
+                        // grace expires and the verdict below stands.
+                    });
+                    return;
+                }
+                const preview = recentLinesPreview(recent);
+                // Report what an empty window actually establishes. A
+                // re-attach that turned up nothing rules out lines lost
+                // on the way here, which leaves an app that logged
+                // nothing and a stream stalled at its far end — and
+                // those two are indistinguishable from this side.
+                // Naming only the stream would send the reader after a
+                // transport fault on every quiet window.
+                const silent =
+                    linesChecked === 0
+                        ? " — no output at all reached this window, re-attach included: the app logged nothing, or the stream stalled upstream"
+                        : "";
+                const msg =
+                    `waitForLog timed out after ${timeoutMs}ms waiting for ${pattern} ` +
+                    `(since=${since}, linesChecked=${linesChecked}${silent})${preview ? `\nRecent lines:\n${preview}` : ""}`;
+                settle(() =>
+                    reject(
+                        new WaitForLogTimeoutError(msg, {
+                            pattern: String(pattern),
+                            since,
+                            timeoutMs,
+                            linesChecked,
+                            recentLines: recent.slice()
+                        })
+                    )
+                );
+            };
+            arm(timeoutMs, onDeadline);
+        });
+    }
+
+    /**
+     * Bulk read of every line with seq >= parseInt(opts.since). Does not
+     * subscribe. Throws `LogBufferOverflowError` if `since` predates
+     * the retention window.
+     */
+    async logs(opts: { since: LogPosition }): Promise<LogLine[]> {
+        await this.ensureLogSession();
+        return this.logSession.buffer.linesSince(opts.since);
+    }
+
+    /**
+     * Fail if `pattern` matches any line within `opts.window` ms of "now"
+     * starting from `opts.since`. Pre-existing or live match throws
+     * `UnexpectedLogError`; any gap overlapping the window throws
+     * `LogStreamGapError` (absence is unprovable across a gap).
+     * `opts.timeout` is accepted as an alias for `opts.window`.
+     */
+    async expectNoLog(pattern: RegExp, opts: LogQueryOptions): Promise<void> {
+        await this.ensureLogSession();
+        const buffer = this.logSession.buffer;
+        const since = opts.since;
+        const windowMs = opts.window ?? opts.timeout;
+        if (typeof windowMs !== "number" || windowMs < 0) {
+            throw new RkClientError(
+                `expectNoLog requires opts.window (ms) — received: ${JSON.stringify(opts)}`,
+                "EXPECT_NO_LOG_INVALID_WINDOW"
+            );
+        }
+
+        for (const e of buffer.entriesSince(since)) {
+            if (pattern.test(e.line)) {
+                throw new UnexpectedLogError(
+                    `expectNoLog: pattern ${pattern} matched existing line "${truncate(e.line, 200)}" at seq ${e.seq}.`,
+                    { pattern: String(pattern), matchedLine: e.line, since }
+                );
+            }
+        }
+        // A pre-existing gap already makes the window inconclusive.
+        const initialGap = buffer.hasGapWithin(since);
+        if (initialGap) {
+            throw new LogStreamGapError(gapMessage("expectNoLog", pattern, initialGap), {
+                gapStart: String(initialGap.start),
+                gapEnd: String(initialGap.end)
+            });
+        }
+
+        return new Promise<void>((resolve, reject) => {
+            let settled = false;
+            const settle = (fn: () => void): void => {
+                if (settled) return;
+                settled = true;
+                unsubscribe();
+                clearTimeout(timer);
+                fn();
+            };
+            const unsubscribe = buffer.subscribe(entry => {
+                if (settled) return;
+                // A mid-window gap fails immediately: cannot prove the
+                // negative across dropped lines.
+                const gap = buffer.hasGapWithin(since);
+                if (gap) {
+                    settle(() =>
+                        reject(
+                            new LogStreamGapError(gapMessage("expectNoLog", pattern, gap), {
+                                gapStart: String(gap.start),
+                                gapEnd: String(gap.end)
+                            })
+                        )
+                    );
+                    return;
+                }
+                if (pattern.test(entry.line)) {
+                    settle(() =>
+                        reject(
+                            new UnexpectedLogError(
+                                `expectNoLog: pattern ${pattern} matched live line "${truncate(entry.line, 200)}" at seq ${entry.seq}.`,
+                                {
+                                    pattern: String(pattern),
+                                    matchedLine: entry.line,
+                                    since
+                                }
+                            )
+                        )
+                    );
+                }
+            });
+            const timer = setTimeout(() => {
+                // Catch a gap that closed silently during the wait with
+                // no intervening line.
+                const gap = buffer.hasGapWithin(since);
+                if (gap) {
+                    settle(() =>
+                        reject(
+                            new LogStreamGapError(gapMessage("expectNoLog", pattern, gap), {
+                                gapStart: String(gap.start),
+                                gapEnd: String(gap.end)
+                            })
+                        )
+                    );
+                    return;
+                }
+                settle(resolve);
+            }, windowMs);
+            if (typeof (timer as { unref?: () => unknown }).unref === "function") {
+                (timer as { unref: () => unknown }).unref();
+            }
+        });
+    }
+
+    /**
+     * Build the app at `appPath`, sideload the resulting `pkg-dir`,
+     * launch, and block until interactive. Failures split into
+     * `BuildFailedError` (host-side; device not flagged) vs
+     * `DeployFailedError` (device-side; device flagged unhealthy so
+     * later `beforeEach` hooks can fail fast).
+     *
+     * Deep-link caveat: passing `opts.deepLink` on a cold sideload is
+     * best-effort — the `Install` ECP auto-launches without params and
+     * the follow-up `/launch/?…` races the runtime's handler
+     * registration. If correctness depends on params landing, use
+     * `buildAndLaunchWithParams` which gates on a runtime-ready log line.
+     */
+    async buildAndDeploy(appPath: string, opts?: BuildAndDeployOptions): Promise<void> {
+        const absPath = resolveAppPath(appPath);
+        if (!directoryExists(absPath)) {
+            throw new BuildFailedError(
+                `buildAndDeploy: app path does not exist or is not a directory: ${absPath}`,
+                absPath
+            );
+        }
+        const configFile = join(absPath, "roku-config.ts");
+        if (!existsSync(configFile)) {
+            throw new BuildFailedError(
+                `buildAndDeploy: no roku-config.ts at ${configFile}. Mode A expects the app's own config; Mode B expects the fixture's roku-config.ts to export makeConfig(...).`,
+                absPath
+            );
+        }
+
+        if (this.driver) {
+            await this.deployThroughDriver(absPath, opts);
+            return;
+        }
+
+        // The build runs server-side via `requestServerBuild`, so we do
+        // not need esbuild loaded in this process — keeps ~200 MiB of
+        // orphan `esbuild --service` procs out of the build container.
+        // `loadToolingDeps()` uses `require()` (not dynamic `import()`)
+        // because TS5.9 parse fails on esbuild's `.d.cts` types
+        // (transitive `@jridgewell/remapping` ESM-in-CJS syntax) — and
+        // `skipLibCheck` cannot help since parse precedes check.
+        const tooling = loadToolingDeps();
+
+        // Per-integration-test out-dir keeps artifacts out of the app's
+        // own `dist-build` so local `rk build` runs don't collide.
+        const outDir = INTEGRATION_BUILD_OUT_DIR;
+        let pkgDir: string;
+        // The build is memoised per-process via `getOrCreateBuildPromise`:
+        // when the same `(absPath, outDir, buildType, dropConsole)` tuple
+        // appears across multiple `beforeAll` deploys in one Jest run —
+        // typical for shards that share a fixture, e.g. `runtime` reusing
+
+        // `apps/internal-runtime` across eight test files — rk-server is only
+
+        // asked to bundle once. Source files do not change between those
+        // `beforeAll`s, so the second through N-th call would be pure
+        // wasted wall-clock. See `build-cache.ts` for the failure /
+        // invalidation contract (rejected builds drop the entry; the
+        // deploy-guard wipes both `dist-integration-test/` and the
+        // matching cache entry on retry).
+        const buildType = process.env.ROKU_BUILD_TYPE || "build";
+        const serverUrl = this.serverUrl;
+        try {
+            await getOrCreateBuildPromise(
+                {
+                    absRoot: absPath,
+                    outDir,
+                    buildType,
+                    dropConsole: opts?.dropConsole,
+                    dev: opts?.dev,
+                    solidDevMode: opts?.solidDevMode,
+                    buildVariables: opts?.buildVariables
+                },
+                () =>
+                    requestServerBuild(serverUrl, {
+                        root: absPath,
+                        outDir,
+                        // Forward ROKU_BUILD_TYPE so the server-side build sees
+                        // the same fixture mode the test set; otherwise the
+                        // fixture's roku-config always sees the default "build".
+                        buildType,
+                        // Integration-test fixture builds only need to bundle
+                        // and deploy so device tests can exercise runtime APIs;
+                        // they must not be gated on the workspace-wide semantic
+                        // type check (a pre-existing type error in an unrelated
+                        // package would otherwise block every on-device run).
+                        // Temporary "for now" measure — drop once the workspace
+                        // build is type-clean again.
+                        disableTypeChecking: true,
+                        // Only forward `dropConsole` when explicitly set so the
+                        // server's arg-derivation falls back to the fixture's
+                        // roku-config value (parity with mergeConfig pre-server-build).
+                        ...(opts?.dropConsole !== undefined ? { dropConsole: opts.dropConsole } : {}),
+                        // Forward `dev` when set — disables minification and enables
+                        // source maps for profiling sessions with readable identifiers.
+                        ...(opts?.dev ? { dev: true } : {}),
+                        // Forward `solidDevMode` to enable SolidJS dev build (readable
+                        // signal/effect names in Perfetto tracepoints).
+                        ...(opts?.solidDevMode ? { solidDevMode: true } : {}),
+                        // Forward `buildVariables` overrides so the server can merge
+                        // them with the app's roku-config buildVariables (e.g.
+                        // { __SIGNAL__: true } enables SolidJS dev mode).
+                        ...(opts?.buildVariables ? { buildVariables: opts.buildVariables } : {})
+                    })
+            );
+            pkgDir = join(absPath, outDir, "pkg-dir");
+        } catch (err) {
+            throw new BuildFailedError(
+                `Build failed for ${absPath}: ${errorMessage(err)}. Fix the host-side TypeScript/bundler/manifest errors and try again.`,
+                absPath,
+                err
+            );
+        }
+
+        const { ip, password } = await this.resolveTargetDevice(opts?.deviceSelector, absPath, tooling);
+
+        const { appType, libraryName } = await readAppTypeFromManifest(pkgDir, tooling.readManifestEntries);
+        const launchLogSince = this.logPosition();
+
+        try {
+            const device = new tooling.RokuDevice(ip, password, await tooling.getTempDir());
+            // Don't pass launchParams here — we run the launch ourselves
+            // below so it goes through the queue and shared readiness gate.
+            // Retry once on transient installer/network errors: `/plugin_install`
+            // occasionally rejects or times out under rapid back-to-back sideloads.
+            // If the upload was interrupted after firmware touched the dev channel,
+            // best-effort delete clears the half-installed state before retrying.
+            let lastErr: unknown;
+            for (let attempt = 0; attempt < 2; attempt += 1) {
+                try {
+                    await device.replace(pkgDir, appType, libraryName);
+                    lastErr = undefined;
+                    break;
+                } catch (sideloadErr) {
+                    lastErr = sideloadErr;
+                    const transient = isTransientSideloadError(sideloadErr);
+                    if (!transient || attempt === 1) {
+                        throw sideloadErr;
+                    }
+                    try {
+                        await device.delete();
+                    } catch {
+                        // Best effort only: a busy installer can reject cleanup,
+                        // but the retry still has a chance after a short pause.
+                    }
+                    await sleepUnref(2000);
+                }
+            }
+            if (lastErr) throw lastErr;
+        } catch (err) {
+            let formatted: string | undefined;
+            try {
+                const diagnostics = await tooling.runSideloadDiagnostics(ip);
+                formatted = tooling.formatSideloadDiagnostics({
+                    ip,
+                    diagnostics,
+                    verbose: false
+                });
+            } catch {
+                // best-effort; diagnostics are advisory
+            }
+            const reason = `sideload failed: ${errorMessage(err)}`;
+            invalidateBuildCacheForApp(absPath);
+            markDeviceUnhealthy(reason);
+            throw new DeployFailedError(`Deploy failed for ${absPath}: ${reason}${formatted ? `\n${formatted}` : ""}`, {
+                appPath: absPath,
+                deviceIp: ip,
+                phase: "sideload",
+                reason: "sideload-failed",
+                diagnostics: formatted,
+                cause: err
+            });
+        }
+
+        // Readiness/dialog failures are already wrapped as
+        // DeployFailedError in `awaitReadyAndCheckDialog`; HTTP errors
+        // from the launch POST are wrapped here for a uniform contract.
+        const channelId = opts?.channelId ?? "dev";
+        const readinessTimeout = opts?.readinessTimeout ?? READINESS_TIMEOUT_MS;
+        try {
+            await this.launchAndAwaitReady(
+                channelId,
+                opts?.deepLink,
+                readinessTimeout,
+                opts?.readyNode,
+                launchLogSince
+            );
+        } catch (err) {
+            if (err instanceof DeployFailedError) {
+                invalidateBuildCacheForApp(absPath);
+                throw err;
+            }
+            // The auto-launch race is absorbed inside
+            // `launchAndAwaitReady`; anything surfacing here is a launch
+            // failure the readiness gate could not vouch for.
+            const reason = `ECP launch failed: ${errorMessage(err)}`;
+            invalidateBuildCacheForApp(absPath);
+            markDeviceUnhealthy(`launch: ${reason}`);
+            throw new DeployFailedError(`Deploy failed for ${absPath}: ${reason}`, {
+                appPath: absPath,
+                deviceIp: ip,
+                expectedChannelId: channelId,
+                phase: "launch",
+                reason: "launch-failed",
+                cause: err
+            });
+        }
+    }
+
+    /** `buildAndDeploy` for a driver-hosted run: the driver builds and starts, ECP does readiness. */
+    private async deployThroughDriver(absPath: string, opts?: BuildAndDeployOptions): Promise<void> {
+        const channelId = opts?.channelId ?? "dev";
+        const logSince = this.logPosition();
+        try {
+            this.driverTarget = await this.driver!.deploy({ absPath, launchParams: opts?.deepLink });
+            this.ecp = new EcpClient(this.driverTarget, this.requestTimeoutMs);
+        } catch (err) {
+            invalidateBuildCacheForApp(absPath);
+            throw new BuildFailedError(`Build failed for ${absPath}: ${errorMessage(err)}.`, absPath, err);
+        }
+        await this.awaitReadyAndCheckDialog({
+            channelId,
+            timeoutMs: opts?.readinessTimeout ?? READINESS_TIMEOUT_MS,
+            readyNode: opts?.readyNode,
+            relaunch: () => this.postLaunch(channelId, opts?.deepLink),
+            logSince
+        });
+    }
+
+    /**
+     * Cold sideload + reliable deep-link delivery.
+     *
+     * `buildAndDeploy({ deepLink })` races the runtime's launch-params
+     * handler on cold sideload (firmware drops the params-carrying POST
+     * if it arrives before `setLaunchParamsUpdateHandler` runs). This
+     * method splits the flow:
+     *
+     *   1. `buildAndDeploy` without params → firmware auto-launches.
+     *   2. `waitForLog(runtimeReadyLogPattern)` → fixture must emit this
+     *      only after the runtime has subscribed to launch params.
+     *   3. `launch({ deepLink })` → params-carrying launch hits a ready handler.
+     *   4. `waitForLog(paramsAckLogPattern)` → proves the reactive graph
+     *      observed the params; subsequent DOM timeouts are then
+     *      attributable to the renderer, not to lost signal.
+     *
+     * Both log regexes are required: making either optional would
+     * re-introduce the race this method exists to eliminate. Errors
+     * flow through with their original types (no extra wrapping).
+     */
+    async buildAndLaunchWithParams(
+        appPath: string,
+        deepLink: Record<string, string>,
+        opts: BuildAndLaunchWithParamsOptions
+    ): Promise<void> {
+        const runtimeReadyTimeout = opts.runtimeReadyTimeout ?? 5000;
+        const paramsAckTimeout = opts.paramsAckTimeout ?? 5000;
+        await this.ensureLogSession();
+        // Tail-fallback scan: only accept matches at/after `since` (else a
+        // stale match from a previous deploy would pass).
+        // Flag-stripping `g`/`y` because `RegExp.prototype.test` is
+        // stateful with either, which causes false negatives across
+        // multiple `Array.some` probes.
+        const recentTailMatches = (pattern: RegExp, since: LogPosition): boolean => {
+            const safePattern = new RegExp(pattern.source, pattern.flags.replace(/[gy]/g, ""));
+            let minSeq: number;
+            try {
+                minSeq = parsePos(since);
+            } catch (err) {
+                // Malformed `since` means a caller hand-rolled the token;
+                // warn loudly so the impending `LogBufferOverflowError`
+                // isn't misattributed to a silent tail-fallback.
+                console.warn(
+                    `[device-test-client] tail-fallback skipped: malformed ` +
+                        `since position "${since}" — ${(err as Error).message}`
+                );
+                return false;
+            }
+            return this.recentLogLines(500).some(entry => entry.seq >= minSeq && safePattern.test(entry.line));
+        };
+        const waitForLogWithTailFallback = async (
+            pattern: RegExp,
+            since: LogPosition,
+            timeout: number
+        ): Promise<void> => {
+            try {
+                await this.waitForLog(pattern, { since, timeout });
+            } catch (err) {
+                // Only mask `LogBufferOverflowError`, and only when a
+                // post-`since` tail line confirms the marker.
+                if (!(err instanceof LogBufferOverflowError) || !recentTailMatches(pattern, since)) {
+                    throw err;
+                }
+            }
+        };
+
+        // Phase 1: capture position BEFORE the deploy so a fast-emitting
+        // ready log cannot race ahead of our wait window.
+        const readyPos = this.logPosition();
+        await this.buildAndDeploy(appPath, {
+            deviceSelector: opts.deviceSelector,
+            channelId: opts.channelId,
+            readinessTimeout: opts.readinessTimeout,
+            readyNode: opts.readyNode,
+            dropConsole: opts.dropConsole
+        });
+        await waitForLogWithTailFallback(opts.runtimeReadyLogPattern, readyPos, runtimeReadyTimeout);
+
+        // Phase 2: skip the readiness gate — during a params relaunch
+        // the app can hop through home/splash before rebinding, which
+        // the stability check would treat as a crash. The ack log is
+        // the authoritative success signal.
+        const ackPos = this.logPosition();
+        const channelId = opts.channelId ?? "dev";
+        try {
+            await this.runEcp("launch", () => this.postLaunch(channelId, deepLink));
+        } catch (err) {
+            // The params-ack log — not the POST status — is the
+            // authoritative signal here, so a POST that raced the
+            // relaunch is tolerated and the ack wait below decides.
+            if (!isLaunchPostRaceError(err)) throw err;
+        }
+        await waitForLogWithTailFallback(opts.paramsAckLogPattern, ackPos, paramsAckTimeout);
+    }
+
+    /**
+     * Resolve `{ip, password}` for the target device. Order:
+     * `RK_DEVICE_IP` + `RK_DEVICE_PASSWORD` env pair (skipped when
+     * `selector` is set), then `.roku/roku-dev-config.json`. When only
+     * `RK_DEVICE_IP` is set, the store is searched for that IP rather
+     * than the active device: `globalSetup` exports the IP it resolved
+     * from the store, so a run against a stored device always arrives
+     * here with the IP set and the password unset.
+     * `RK_DEVICE_PASSWORD` alone, a missing device, or an IP mismatch
+     * with `this.deviceIp` throws `DeployFailedError({ phase: "config" })`.
+     */
+    private async resolveTargetDevice(
+        selector: string | undefined,
+        appPath: string,
+        deps: Pick<ToolingDeps, "listMergedDevices" | "findDeviceBySelector">
+    ): Promise<{ ip: string; password: string }> {
+        if (selector === undefined) {
+            const fromEnv = this.tryResolveTargetDeviceFromEnv(appPath);
+            if (fromEnv) return fromEnv;
+        }
+        const envIpOnly = selector === undefined ? process.env[ENV_VAR.RK_DEVICE_IP] || undefined : undefined;
+        const { devices, activeId, activeRceId } = await deps.listMergedDevices(process.cwd());
+        const target = selector
+            ? deps.findDeviceBySelector(devices, selector)
+            : envIpOnly
+              ? devices.find((d: ToolingDevice) => d.ip === envIpOnly)
+              : devices.find((d: ToolingDevice) => d.id === activeId);
+        if (!target) {
+            const reason = selector
+                ? `no device matched selector "${selector}"`
+                : envIpOnly
+                  ? `RK_DEVICE_IP (${envIpOnly}) is not a registered rk device; run \`rk device add ${envIpOnly}\` and \`rk device update ${envIpOnly} --password <pw>\`, or set RK_DEVICE_PASSWORD`
+                  : activeRceId
+                    ? `the active device ${activeRceId} is a Roku Cloud Emulator device, and device tests run on LAN devices only; set RK_DEVICE_IP + RK_DEVICE_PASSWORD or make a LAN device active`
+                    : "no active device configured; run `rk device add <ip>` or set RK_DEVICE_IP + RK_DEVICE_PASSWORD";
+            markDeviceUnhealthy(reason);
+            throw new DeployFailedError(`Deploy failed for ${appPath}: ${reason}`, {
+                appPath,
+                deviceIp: this.deviceIp,
+                phase: "config"
+            });
+        }
+        if (!target.password) {
+            const reason = `device '${target.name || target.ip}' has no password; run \`rk device update\` to set one or set RK_DEVICE_PASSWORD`;
+            markDeviceUnhealthy(reason);
+            throw new DeployFailedError(`Deploy failed for ${appPath}: ${reason}`, {
+                appPath,
+                deviceIp: target.ip,
+                phase: "config"
+            });
+        }
+        if (target.ip !== this.deviceIp) {
+            const reason = envIpOnly
+                ? `RK_DEVICE_IP env var (${envIpOnly}) does not match RkClient deviceIp (${this.deviceIp}); fix one of them`
+                : `.roku/ active device IP (${target.ip}) does not match RkClient deviceIp (${this.deviceIp}); fix one of them`;
+            markDeviceUnhealthy(reason);
+            throw new DeployFailedError(`Deploy failed for ${appPath}: ${reason}`, {
+                appPath,
+                deviceIp: this.deviceIp,
+                phase: "config"
+            });
+        }
+        return { ip: target.ip, password: target.password };
+    }
+
+    /**
+     * Env-var fast path: returns `{ip, password}` when both are set,
+     * `null` when neither is or when only `RK_DEVICE_IP` is (the caller
+     * then looks the password up in the store by that IP). Throws
+     * `DeployFailedError({ phase: "config" })` when only
+     * `RK_DEVICE_PASSWORD` is set (a password with no device to send it
+     * to) or on an env-var IP mismatch.
+     */
+    private tryResolveTargetDeviceFromEnv(appPath: string): { ip: string; password: string } | null {
+        const envIp = process.env[ENV_VAR.RK_DEVICE_IP] ?? "";
+        const envPassword = process.env[ENV_VAR.RK_DEVICE_PASSWORD] ?? "";
+        const ipSet = envIp.length > 0;
+        const passwordSet = envPassword.length > 0;
+        if (!passwordSet) return null;
+        if (!ipSet) {
+            const reason =
+                "RK_DEVICE_PASSWORD is set but RK_DEVICE_IP is empty; set both env vars or neither (env-var device config requires both)";
+            markDeviceUnhealthy(reason);
+            throw new DeployFailedError(`Deploy failed for ${appPath}: ${reason}`, {
+                appPath,
+                deviceIp: this.deviceIp,
+                phase: "config"
+            });
+        }
+        if (envIp !== this.deviceIp) {
+            const reason = `RK_DEVICE_IP env var (${envIp}) does not match RkClient deviceIp (${this.deviceIp}); fix one of them`;
+            markDeviceUnhealthy(reason);
+            throw new DeployFailedError(`Deploy failed for ${appPath}: ${reason}`, {
+                appPath,
+                deviceIp: this.deviceIp,
+                phase: "config"
+            });
+        }
+        return { ip: envIp, password: envPassword };
+    }
+
+    /**
+     * Poll `captureScreenshot()` until two successive captures agree
+     * outside the (optional) `mask` regions (strict pixel-equality by
+     * default; `opts.tolerance` relaxes the gate by up to N differing
+     * pixels — see `CaptureStableOptions.tolerance`), then resolve
+     * with the second (newest) PNG. Required precondition for
+     * meaningful `expectScreenshot(...)` assertions.
+     *
+     * `interval` is gap-based (mirrors `waitForNode`); `assertAppAlive`
+     * runs before every capture so a crash surfaces immediately.
+     * On timeout: `ScreenshotNotStableError` with last diff stats and
+     * `lastPng` for artifacts (excluded from `toJSON`).
+     */
+    async captureStableScreenshot(opts: CaptureStableOptions): Promise<Buffer> {
+        this.assertScreenshotSupported();
+        const interval = opts.interval ?? SCREENSHOT_STABLE_DEFAULT_INTERVAL_MS;
+        const timeoutMs = opts.timeout;
+        const deadline = Date.now() + timeoutMs;
+        const rawMasks: MaskRegion[] = opts.mask ?? [];
+        const tolerance = Math.max(0, Math.floor(opts.tolerance ?? 0));
+
+        let prevBuf: Buffer | null = null;
+        let prevPng: PNG | null = null;
+        // Cached across iterations: canvas dims are fixed per-device.
+        // Validated on iteration 1 so an invalid-mask bug surfaces as
+        // `ScreenshotMaskError` even on `timeout: 0`.
+        let normalizedMasks: MaskRegion[] | null = null;
+        let iterations = 0;
+        let lastDiffCount = 0;
+        let lastFirstDiffPoint: { x: number; y: number } | undefined;
+
+        do {
+            const iterStart = Date.now();
+            await this.assertAppAlive({ operation: "captureStableScreenshot" });
+            const nextBuf = await this.captureScreenshot();
+            iterations += 1;
+            // Parse once; reused as `prevPng` next iteration.
+            const nextPng = PNG.sync.read(nextBuf);
+
+            if (normalizedMasks === null) {
+                normalizedMasks = validateMasks(rawMasks, {
+                    w: nextPng.width,
+                    h: nextPng.height
+                });
+            }
+
+            if (prevPng) {
+                const cmp = pngsEqualOutsideMask(prevPng, nextPng, normalizedMasks);
+                // `tolerance` lets sub-pixel anti-alias jitter on
+                // static text settle without us declaring the screen
+                // unstable; strict equality is still the default.
+                if (cmp.equal || cmp.diffCount <= tolerance) return nextBuf;
+                lastDiffCount = cmp.diffCount;
+                lastFirstDiffPoint = cmp.firstDiffPoint;
+            }
+
+            prevBuf = nextBuf;
+            prevPng = nextPng;
+
+            const now = Date.now();
+            const remaining = deadline - now;
+            if (remaining <= 0) break;
+
+            // Gap-based; queue's 500ms `capture` gap already paces us.
+            const slack = interval - (now - iterStart);
+            if (slack > 0) {
+                await sleepUnref(Math.min(slack, remaining));
+            } else if (interval === 0) {
+                await sleepUnref(1);
+            }
+        } while (Date.now() < deadline);
+
+        const maskedForError = normalizedMasks ?? rawMasks;
+        throw new ScreenshotNotStableError(
+            `captureStableScreenshot timed out after ${timeoutMs}ms ` +
+                `(${iterations} iterations, lastDiffCount=${lastDiffCount}${
+                    lastFirstDiffPoint ? `, firstDiffPoint=(${lastFirstDiffPoint.x},${lastFirstDiffPoint.y})` : ""
+                }). Mask regions: ${JSON.stringify(maskedForError)}.`,
+            {
+                timeoutMs,
+                iterations,
+                lastDiffCount,
+                maskedRegions: maskedForError,
+                firstDiffPoint: lastFirstDiffPoint,
+                lastPng: prevBuf ?? undefined
+            }
+        );
+    }
+
+    /**
+     * Run an ECP operation through the queue with the retry wrapper.
+     * Retry happens inside the queue slot so the backoff does not let
+     * another request slip between the two attempts.
+     */
+    /** POST the ECP launch request, through the driver's transport when one is in use. */
+    private async postLaunch(channelId: string, deepLink?: Record<string, string>): Promise<void> {
+        if (!this.driverTarget) {
+            await postNoBody(buildLaunchUrl(this.deviceIp, channelId, deepLink), this.requestTimeoutMs);
+            return;
+        }
+        // A driver's label is a display name (for example `rce:my-device`), not a host, so no URL is
+        // built from it: the transport only needs the path and query.
+        const path = buildLaunchPath(channelId, deepLink);
+        const res = await this.driverTarget.http(8060, path, { method: "POST" });
+        if (!res.ok) {
+            throw new Error(`POST ${path.split("?")[0]} failed: HTTP ${res.status}`);
+        }
+    }
+
+    private runEcp<T>(category: EcpCategory, op: () => Promise<T>): Promise<T> {
+        return this.queue.enqueue(category, () =>
+            retryOnTransient(op, {
+                backoffMs: ECP_RETRY_BACKOFF_MS,
+                isTransient: isTransientEcpError
+            })
+        );
+    }
+}
+
+/** A log session whose lines come from the driver's console feed instead of the rk server. */
+function driverLogSession(driver: DeploymentDriver): LogSessionLike {
+    const buffer = new LogBuffer();
+    driver.onLog(line => {
+        buffer.append(line);
+    });
+    return { ensureStarted: async () => {}, dispose: () => {}, buffer };
+}
+
+function errorMessage(err: unknown): string {
+    if (err instanceof Error) return err.message;
+    try {
+        return String(err);
+    } catch {
+        return "<unserializable error>";
+    }
+}
+
+/**
+ * Matches the `postNoBody` timeout message for any `/launch/...` URL —
+ * with or without a deep-link query string, which the previous literal
+ * `"/launch/dev timed out"` check missed.
+ */
+const LAUNCH_POST_TIMEOUT_RE = /\/launch\/\S*\s+timed out/;
+
+/**
+ * True when the `/launch` POST raced a launch that was already under
+ * way, so its verdict says nothing about whether the app came up:
+ *
+ *   - the POST timed out while the firmware was mid-boot;
+ *   - the transport blipped (`fetch failed`);
+ *   - the launcher answered 5xx (observed as `503 Service Unavailable`
+ *     on virtualized hosts) because it was busy foregrounding that very
+ *     channel.
+ *
+ * Callers that tolerate these must still prove the launch another way —
+ * the readiness gate or the params-ack log.
+ */
+function isLaunchPostRaceError(err: unknown): boolean {
+    const message = errorMessage(err);
+    return LAUNCH_POST_TIMEOUT_RE.test(message) || message.includes("fetch failed") || isEcpServerError(err);
+}
+
+/**
+ * Phase-1 (plain sideload) superset of `isLaunchPostRaceError`: newer
+ * firmware auto-launches the sideloaded `dev` build and need not serve
+ * `/launch/dev` at all, so a 404 there is also no evidence of failure.
+ * Deep-link launches must NOT tolerate it — a missing endpoint means
+ * the params were never delivered.
+ */
+function isAutoLaunchTolerableError(err: unknown): boolean {
+    return isLaunchPostRaceError(err) || errorMessage(err).includes("ECP endpoint not found");
+}
+
+function isTransientSideloadError(err: unknown): boolean {
+    const name = err instanceof Error ? err.name : "";
+    const msg = errorMessage(err);
+    return (
+        name === "AbortError" ||
+        /AbortError/i.test(msg) ||
+        /operation was aborted/i.test(msg) ||
+        /Request to Roku device .* timed out/i.test(msg) ||
+        /DEVICE_REQUEST_TIMEOUT/i.test(msg) ||
+        /fetch failed/i.test(msg) ||
+        /ECONNRESET/i.test(msg) ||
+        /ETIMEDOUT/i.test(msg) ||
+        /socket hang up/i.test(msg)
+    );
+}
+
+function recentLinesPreview(lines: LogLine[]): string {
+    if (lines.length === 0) return "";
+    const joined = lines.join("\n");
+    if (joined.length <= WAIT_FOR_LOG_RECENT_CHARS_MAX) return joined;
+    const half = Math.floor(WAIT_FOR_LOG_RECENT_CHARS_MAX / 2);
+    return `${joined.slice(0, half)}\n… (${joined.length - WAIT_FOR_LOG_RECENT_CHARS_MAX} more chars) …\n${joined.slice(-half)}`;
+}
+
+function gapMessage(op: "waitForLog" | "expectNoLog", pattern: RegExp, gap: { start: number; end: number }): string {
+    return (
+        `${op}: log stream had a gap covering seqs [${gap.start}, ${gap.end}) ` +
+        `during the wait window — unable to prove the presence/absence of ${pattern}. ` +
+        `This happens when \`rk server\`'s connection to the device dropped and reconnected; ` +
+        `re-run the test against a stable device or widen the window.`
+    );
+}
+
+function truncate(s: string, max: number): string {
+    if (s.length <= max) return s;
+    return `${s.slice(0, max - 1)}…`;
+}
+
+function trimTrailingSlash(s: string): string {
+    return s.endsWith("/") ? s.slice(0, -1) : s;
+}
+
+function isObject(v: unknown): v is Record<string, unknown> {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+function numberOr(v: unknown, fallback: number): number {
+    return typeof v === "number" && Number.isFinite(v) ? v : fallback;
+}
+
+function stringOrNull(v: unknown): string | null {
+    return typeof v === "string" ? v : null;
+}
+
+function sleepUnref(ms: number): Promise<void> {
+    return new Promise<void>(resolve => {
+        const t = setTimeout(resolve, ms);
+        if (typeof (t as { unref?: () => unknown }).unref === "function") {
+            (t as { unref: () => unknown }).unref();
+        }
+    });
+}