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

package/src/client/client.ts

@@ -0,0 +1,1656 @@
+// 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 { 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,
+    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,
+    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 { parsePos } from "../logs/log-buffer";
+import { LogSession } from "../logs/log-session";
+import type {
+    ActiveAppInfo,
+    AppUiNode,
+    BuildAndDeployOptions,
+    BuildAndLaunchWithParamsOptions,
+    CaptureStableOptions,
+    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 {
+    buildLaunchUrl,
+    directoryExists,
+    loadToolingDeps,
+    normalizeKeyOrThrow,
+    postNoBody,
+    readAppTypeFromManifest,
+    requestServerBuild,
+    resolveAppPath
+} from "./deploy";
+import { EcpRequestQueue } from "./ecp-queue";
+import { isEcpServerError, isTransientEcpError, retryOnTransient } from "./ecp-retry";
+import { markDeviceFatal, markDeviceUnhealthy } 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 readonly ecp: EcpClient;
+    private readonly queue: EcpRequestQueue;
+    private readonly requestTimeoutMs: number;
+    private readonly serverUrl: string;
+    private readonly logSession: LogSessionLike;
+    private _cachedDeviceInfo: DeviceInfo | null = null;
+
+    constructor(opts: RkClientOptions = {}) {
+        if (!opts.deviceIp) {
+            throw new RkClientError(
+                `RkClient requires a deviceIp. Use createDefaultClient() for env-driven resolution.`,
+                "RK_DEVICE_IP_UNRESOLVED"
+            );
+        }
+        this.deviceIp = opts.deviceIp;
+        this.keyDelay = opts.keyDelay ?? DEFAULT_KEY_DELAY;
+        this.requestTimeoutMs = opts.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
+        this.serverUrl = resolveServerUrl(opts.serverUrl);
+
+        this.ecp = new EcpClient(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 ??
+            new LogSession({
+                serverUrl: this.serverUrl,
+                device: this.deviceIp,
+                port: ROKU_LOG_PORT
+            });
+    }
+
+    /** 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. */
+    async captureScreenshot(): Promise<Buffer> {
+        return this.runEcp("capture", () => this.ecp.captureScreen("png"));
+    }
+
+    /**
+     * 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);
+        });
+    }
+
+    /**
+     * 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`.
+     */
+    private async launchAndAwaitReady(
+        channelId: string,
+        deepLink: Record<string, string> | undefined,
+        timeoutMs: number,
+        readyNode?: NodePredicate
+    ): Promise<void> {
+        const url = buildLaunchUrl(this.deviceIp, channelId, deepLink);
+        try {
+            await this.runEcp("launch", async () => {
+                await postNoBody(url, this.requestTimeoutMs);
+            });
+        } 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({ channelId, timeoutMs, readyNode });
+                return;
+            }
+            throw err;
+        }
+        await this.awaitReadyAndCheckDialog({ channelId, timeoutMs, readyNode });
+    }
+
+    // -----------------------------------------------------------------
+    // 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);
+    }
+
+    /**
+     * 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;
+
+        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.
+     *
+     * 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.
+     */
+    private async awaitReadyAndCheckDialog(opts: {
+        channelId: string;
+        timeoutMs: number;
+        readyNode?: NodePredicate;
+    }): 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;
+
+        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));
+        };
+
+        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) {
+                        hadChannelEvidence = true;
+                        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)) {
+                if (predicateMatches) {
+                    // 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;
+                    hadChannelEvidence = true;
+                    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
+                            });
+                        }
+                        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 reason = `app never left home screen after launch (active.id="${lastActiveApp.id}", title="${lastActiveApp.title}")`;
+            // FATAL, not merely unhealthy: the device answered ECP for the
+            // whole readiness budget but never foregrounded the sideloaded
+            // channel. ECP/installer liveness recovery cannot cure a
+            // foreground-incapable VM, so latch the process-wide fatal flag
+            // — the deploy-guard and recovery hook short-circuit on it
+            // instead of retrying every remaining suite against a dead VM.
+            markDeviceFatal(`deploy: app never left home screen after launch`);
+            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.
+     */
+    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;
+            const recent: LogLine[] = [];
+            const settle = (fn: () => void): void => {
+                if (settled) return;
+                settled = true;
+                unsubscribe();
+                clearTimeout(timer);
+                fn();
+            };
+            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 timer = setTimeout(() => {
+                // 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;
+                }
+                const preview = recentLinesPreview(recent);
+                const msg =
+                    `waitForLog timed out after ${timeoutMs}ms waiting for ${pattern} ` +
+                    `(since=${since}, linesChecked=${linesChecked})${preview ? `\nRecent lines:\n${preview}` : ""}`;
+                settle(() =>
+                    reject(
+                        new WaitForLogTimeoutError(msg, {
+                            pattern: String(pattern),
+                            since,
+                            timeoutMs,
+                            linesChecked,
+                            recentLines: recent.slice()
+                        })
+                    )
+                );
+            }, timeoutMs);
+            // Don't keep the event loop alive purely for this timer.
+            if (typeof (timer as { unref?: () => unknown }).unref === "function") {
+                (timer as { unref: () => unknown }).unref();
+            }
+        });
+    }
+
+    /**
+     * 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
+            );
+        }
+
+        // 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 = "dist-integration-test";
+        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);
+
+        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);
+        } 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
+            });
+        }
+    }
+
+    /**
+     * 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";
+        const launchUrl = buildLaunchUrl(this.deviceIp, channelId, deepLink);
+        try {
+            await this.runEcp("launch", async () => {
+                await postNoBody(launchUrl, this.requestTimeoutMs);
+            });
+        } 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> {
+        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.
+     */
+    private runEcp<T>(category: EcpCategory, op: () => Promise<T>): Promise<T> {
+        return this.queue.enqueue(category, () =>
+            retryOnTransient(op, {
+                backoffMs: ECP_RETRY_BACKOFF_MS,
+                isTransient: isTransientEcpError
+            })
+        );
+    }
+}
+
+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();
+        }
+    });
+}