agent-scenario-loop 0.1.0

package/dist/runner/android-adb.js

@@ -0,0 +1,1618 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ANDROID_DEVICE_EPOCH_MS_PLACEHOLDER = void 0;
+exports.buildAndroidHealth = buildAndroidHealth;
+exports.buildAndroidVerdict = buildAndroidVerdict;
+exports.buildReactNativeDebugHostPreferenceCommand = buildReactNativeDebugHostPreferenceCommand;
+exports.escapeAndroidPreferenceXml = escapeAndroidPreferenceXml;
+exports.execFileCommand = execFileCommand;
+exports.main = main;
+exports.parseAdbDevices = parseAdbDevices;
+exports.parseArgs = parseArgs;
+exports.parsePositiveInteger = parsePositiveInteger;
+exports.parseReactNativeDebugHostPort = parseReactNativeDebugHostPort;
+exports.resolveAndroidAdbDriverSteps = resolveAndroidAdbDriverSteps;
+exports.applyAndroidSelectorResolution = applyAndroidSelectorResolution;
+exports.buildAndroidSelectorHealthMetadata = buildAndroidSelectorHealthMetadata;
+exports.needsAndroidSelectorResolution = needsAndroidSelectorResolution;
+exports.runAndroidAdbDriverStep = runAndroidAdbDriverStep;
+exports.runAndroidAdbPreflight = runAndroidAdbPreflight;
+exports.selectDevice = selectDevice;
+exports.usage = usage;
+const { execFile } = require('node:child_process');
+const crypto = require('node:crypto');
+const fsp = require('node:fs/promises');
+const path = require('node:path');
+const { buildAgentSummaryMarkdown } = require('../core/agent-summary');
+const { createArtifactLayout } = require('../core/artifact-layout');
+const { writeJsonArtifact, writeTextArtifact } = require('../core/artifact-writer');
+const { SCHEMAS, assertValidJson } = require('../core/schema-validator');
+const { hasHelpFlag, writeUsage } = require('./cli');
+const { buildAndroidScrollCoordinatesFromBounds, createAndroidAdbDriver, formatAndroidAdbRawOutput, quoteAndroidShellArg, resolveAndroidSelectorFromUiTree, } = require('./android-adb-driver');
+const ANDROID_DEVICE_EPOCH_MS_PLACEHOLDER = '__ASL_ANDROID_DEVICE_EPOCH_MS__';
+exports.ANDROID_DEVICE_EPOCH_MS_PLACEHOLDER = ANDROID_DEVICE_EPOCH_MS_PLACEHOLDER;
+const ANDROID_READY_LOG_POLL_MS = 1000;
+/**
+ * Prints CLI usage to stderr.
+ *
+ * @returns {void}
+ */
+function usage(output = process.stderr) {
+    writeUsage([
+        'Usage: asl-android-adb [--adb <path>] [--serial <device>] [--package <name>] [--run-id <id>] [--out <dir>]',
+        '',
+        'Checks adb/device readiness and writes health.json, verdict.json, agent-summary.md, and raw adb evidence.',
+        'Use --capture-logcat [--logcat-lines <count>] to attach a bounded adb logcat snapshot under raw/adb-logcat.txt.',
+        'Use --clear-logcat --launch [--launch-wait-ms <ms>] --wait-ms <ms> with --package <name> to capture a bounded app launch window.',
+        'Use --react-native-debug-host <host:port> with --package <name> to set the app debug server and adb reverse for React Native dev builds.',
+        'Use --android-dev-client-url <url> [--android-dev-client-wait-ms <ms>] [--android-dev-client-ready-pattern <pattern>] to open an Expo dev-client session before scenario deep links.',
+    ], output);
+}
+/**
+ * Parses `--key value` arguments for the Android adb preflight CLI.
+ *
+ * @param {string[]} argv
+ * @returns {CliArgs}
+ */
+function parseArgs(argv) {
+    const args = {};
+    for (let index = 0; index < argv.length; index += 1) {
+        const token = argv[index];
+        if (token === '--') {
+            continue;
+        }
+        if (!token || !token.startsWith('--')) {
+            continue;
+        }
+        const key = token.slice(2);
+        const value = argv[index + 1];
+        if (value && !value.startsWith('--')) {
+            args[key] = value;
+            index += 1;
+        }
+        else {
+            args[key] = true;
+        }
+    }
+    return args;
+}
+/**
+ * Creates a short random run id for Android preflight runs.
+ *
+ * @returns {string}
+ */
+function createRunId() {
+    return crypto.randomBytes(6).toString('hex');
+}
+/**
+ * Parses a positive integer CLI value, falling back when absent or invalid.
+ *
+ * @param {string | boolean | undefined} value
+ * @param {number} fallback
+ * @returns {number}
+ */
+function parsePositiveInteger(value, fallback) {
+    if (typeof value !== 'string') {
+        return fallback;
+    }
+    const parsed = Number(value);
+    return Number.isInteger(parsed) && parsed > 0 ? parsed : fallback;
+}
+/**
+ * Runs a command and captures stdout, stderr, and exit code without throwing.
+ *
+ * @param {string} command
+ * @param {string[]} args
+ * @returns {Promise<CommandResult>}
+ */
+function execFileCommand(command, args) {
+    return new Promise((resolve) => {
+        execFile(command, args, (error, stdout, stderr) => {
+            resolve({
+                command,
+                args,
+                exitCode: error && typeof error.code === 'number' ? error.code : error ? 1 : 0,
+                stderr,
+                stdout,
+            });
+        });
+    });
+}
+/**
+ * Waits for the requested capture window.
+ *
+ * @param {number} ms
+ * @returns {Promise<void>}
+ */
+function delay(ms) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+}
+/**
+ * Parses `adb devices -l` output into device rows.
+ *
+ * @param {string} output
+ * @returns {AndroidDevice[]}
+ */
+function parseAdbDevices(output) {
+    return String(output)
+        .split(/\r?\n/u)
+        .slice(1)
+        .map((line) => line.trim())
+        .filter(Boolean)
+        .map((line) => {
+        const [serial = '', state = '', ...rest] = line.split(/\s+/u);
+        return {
+            serial,
+            state,
+            description: rest.join(' '),
+        };
+    })
+        .filter((device) => device.serial.length > 0);
+}
+/**
+ * Selects an Android device by explicit serial or first online device.
+ *
+ * @param {AndroidDevice[]} devices
+ * @param {string | null | undefined} serial
+ * @returns {AndroidDevice | null}
+ */
+function selectDevice(devices, serial) {
+    if (serial) {
+        return devices.find((device) => device.serial === serial) ?? null;
+    }
+    return devices.find((device) => device.state === 'device') ?? null;
+}
+/**
+ * Creates scalar health-check metadata for an agent-readable next action.
+ *
+ * @param {string} nextActionCode
+ * @param {string} nextAction
+ * @returns {NextActionHint}
+ */
+function nextActionHint(nextActionCode, nextAction) {
+    return {
+        nextAction,
+        nextActionCode,
+    };
+}
+/**
+ * Detects adb daemon/socket failures that are distinct from a genuinely missing device.
+ *
+ * @param {CommandResult} result
+ * @returns {boolean}
+ */
+function isAdbDaemonUnavailable(result) {
+    if (result.exitCode === 0) {
+        return false;
+    }
+    const output = `${result.stdout}\n${result.stderr}`.toLowerCase();
+    return (output.includes('cannot connect to daemon') ||
+        output.includes('failed to check server version') ||
+        output.includes('could not install *smartsocket* listener') ||
+        output.includes('adb server didn'));
+}
+/**
+ * Builds the health check details for device selection failures.
+ *
+ * @param {{devicesOutput: CommandResult, serial?: string | null}} options
+ * @returns {{code: string, message: string, metadata: NextActionHint}}
+ */
+function buildAndroidDeviceFailure({ devicesOutput, serial, }) {
+    if (isAdbDaemonUnavailable(devicesOutput)) {
+        return {
+            code: 'adb_daemon_unreachable',
+            message: 'adb devices could not reach or start the adb daemon.',
+            metadata: nextActionHint('rerun_with_adb_daemon_access', 'Start the adb daemon from a host shell or rerun the live proof with host adb daemon access, then confirm `adb devices -l` lists the target device as `device`.'),
+        };
+    }
+    return {
+        code: 'android_device_missing',
+        message: serial
+            ? `No online Android device matched serial ${serial}.`
+            : 'No online Android device was found.',
+        metadata: nextActionHint('select_android_device', 'Start or unlock an Android emulator/device, confirm it appears as `device` in adb devices -l, or pass --serial for the intended device.'),
+    };
+}
+/**
+ * Reads the TCP port from a React Native debug server host string.
+ *
+ * @param {string} debugHost
+ * @returns {number | null}
+ */
+function parseReactNativeDebugHostPort(debugHost) {
+    if (debugHost.includes('://')) {
+        return null;
+    }
+    const match = /:(?<port>\d+)$/u.exec(debugHost);
+    const port = match?.groups?.port ? Number(match.groups.port) : NaN;
+    return Number.isInteger(port) && port > 0 && port <= 65535 ? port : null;
+}
+/**
+ * Escapes text for the Android shared preference XML file.
+ *
+ * @param {string} value
+ * @returns {string}
+ */
+function escapeAndroidPreferenceXml(value) {
+    return value
+        .replace(/&/gu, '&amp;')
+        .replace(/</gu, '&lt;')
+        .replace(/>/gu, '&gt;')
+        .replace(/"/gu, '&quot;')
+        .replace(/'/gu, '&apos;');
+}
+/**
+ * Builds a device-side shell command that writes React Native debug host preferences.
+ *
+ * @param {{debugHost: string, packageName: string}} options
+ * @returns {string}
+ */
+function buildReactNativeDebugHostPreferenceCommand({ debugHost, packageName, }) {
+    const preferenceFile = `shared_prefs/${packageName}_preferences.xml`;
+    const lines = [
+        '<?xml version="1.0" encoding="utf-8" standalone="yes" ?>',
+        '<map>',
+        `    <string name="debug_http_host">${escapeAndroidPreferenceXml(debugHost)}</string>`,
+        '</map>',
+    ];
+    return [
+        `cd ${quoteAndroidShellArg(`/data/data/${packageName}`)}`,
+        'mkdir -p shared_prefs',
+        [
+            `printf ${quoteAndroidShellArg('%s\\n')}`,
+            ...lines.map((line) => quoteAndroidShellArg(line)),
+            `> ${quoteAndroidShellArg(preferenceFile)}`,
+        ].join(' '),
+    ].join(' && ');
+}
+/**
+ * Escapes a string for insertion as a SQLite string literal.
+ *
+ * @param {string} value
+ * @returns {string}
+ */
+function escapeSqliteString(value) {
+    return value.replace(/'/gu, "''");
+}
+/**
+ * Builds SQL that updates React Native AsyncStorage's Android RKStorage table.
+ *
+ * @param {{clearKeys?: string[], key: string, value: string}} options
+ * @returns {string}
+ */
+function buildAndroidAsyncStorageWriteSql({ clearKeys = [], key, value, }) {
+    return [
+        'PRAGMA busy_timeout=5000;',
+        ...clearKeys.map((clearKey) => (`DELETE FROM catalystLocalStorage WHERE key='${escapeSqliteString(clearKey)}';`)),
+        `INSERT OR REPLACE INTO catalystLocalStorage (key,value) VALUES ('${escapeSqliteString(key)}','${escapeSqliteString(value)}');`,
+    ].join('\n');
+}
+/**
+ * Builds a package-scoped command for writing one Android AsyncStorage value.
+ *
+ * @param {{packageName: string, write: AndroidAsyncStorageWrite}} options
+ * @returns {string}
+ */
+function buildAndroidAsyncStorageWriteCommand({ packageName, write, }) {
+    const sql = buildAndroidAsyncStorageWriteSql({
+        ...(write.clearKeys ? { clearKeys: write.clearKeys } : {}),
+        key: write.key,
+        value: write.value,
+    });
+    return [
+        'run-as',
+        quoteAndroidShellArg(packageName),
+        'sqlite3',
+        quoteAndroidShellArg('databases/RKStorage'),
+        quoteAndroidShellArg(sql),
+    ].join(' ');
+}
+/**
+ * Reads the selected device clock as epoch milliseconds for app-side timing.
+ *
+ * @param {{adbPath: string, deviceSerial: string, executor: CommandExecutor}} options
+ * @returns {Promise<CommandResult & {epochMs: number | null}>}
+ */
+async function readAndroidDeviceEpochMs({ adbPath, deviceSerial, executor, }) {
+    const result = await executor(adbPath, ['-s', deviceSerial, 'shell', 'date', '+%s']);
+    const seconds = Number(result.stdout.trim());
+    const epochMs = result.exitCode === 0 && Number.isFinite(seconds) && seconds > 0
+        ? Math.round(seconds * 1000)
+        : null;
+    return {
+        ...result,
+        epochMs,
+    };
+}
+/**
+ * Combines one adb command result into raw evidence text.
+ *
+ * @param {CommandResult} result
+ * @returns {string}
+ */
+function formatAndroidCommandRawOutput(result) {
+    return [
+        `$ adb ${result.args.join(' ')}`,
+        `exitCode=${result.exitCode}`,
+        result.stdout,
+        result.stderr,
+    ].filter(Boolean).join('\n');
+}
+/**
+ * Parses Android `pidof` output into stable process ids.
+ *
+ * @param {string} output
+ * @returns {string[]}
+ */
+function parseAndroidPidofOutput(output) {
+    return String(output)
+        .trim()
+        .split(/\s+/u)
+        .filter((pid) => /^\d+$/u.test(pid));
+}
+/**
+ * Escapes text so it can be embedded in a regular expression.
+ *
+ * @param {string} value
+ * @returns {string}
+ */
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/gu, '\\$&');
+}
+/**
+ * Finds crash-like Android logcat windows for one app process.
+ *
+ * Android crash logs often split the signal line from the `Process:` line, so
+ * this scans a small neighborhood around each crash marker before deciding it
+ * belongs to the launched app.
+ *
+ * @param {{logText: string, packageName: string, pids?: string[]}} options
+ * @returns {AndroidAppLifecycleScan}
+ */
+function scanAndroidAppLifecycleLog({ logText, packageName, pids = [], }) {
+    const lines = String(logText).split(/\r?\n/u);
+    const packagePattern = new RegExp(escapeRegExp(packageName), 'u');
+    const pidPatterns = pids.map((pid) => new RegExp(`\\b${escapeRegExp(pid)}\\b`, 'u'));
+    const crashPattern = /\b(FATAL EXCEPTION|Fatal signal|SIGSEGV|SIGABRT|ANR in|Force finishing activity|has died|Process .* died)\b/iu;
+    const evidence = new Set();
+    for (let index = 0; index < lines.length; index += 1) {
+        const line = lines[index] ?? '';
+        if (!crashPattern.test(line)) {
+            continue;
+        }
+        const windowStart = Math.max(0, index - 3);
+        const windowEnd = Math.min(lines.length, index + 4);
+        const windowLines = lines.slice(windowStart, windowEnd);
+        const windowText = windowLines.join('\n');
+        const belongsToApp = packagePattern.test(windowText)
+            || pidPatterns.some((pattern) => pattern.test(windowText));
+        if (belongsToApp) {
+            for (const evidenceLine of windowLines) {
+                if (evidenceLine.trim()) {
+                    evidence.add(evidenceLine);
+                }
+            }
+        }
+    }
+    return {
+        crashed: evidence.size > 0,
+        evidence: Array.from(evidence),
+    };
+}
+/**
+ * Counts readiness markers in a bounded Android logcat snapshot.
+ *
+ * @param {{logText: string, pattern: string}} options
+ * @returns {number}
+ */
+function countAndroidReadyLogMatches({ logText, pattern, }) {
+    try {
+        return Array.from(String(logText).matchAll(new RegExp(pattern, 'gu'))).length;
+    }
+    catch {
+        return String(logText).split(pattern).length - 1;
+    }
+}
+/**
+ * Waits until a startup deep link has produced an expected Android log marker.
+ *
+ * @param {{driver: import('./android-adb-driver').AndroidAdbDriver, logcatLines: number, pattern: string, quietMs: number, rawFileName: string, timeoutMs: number, wait: (ms: number) => Promise<void>}} options
+ * @returns {Promise<{ready: boolean, result: import('./android-adb-driver').AndroidAdbCommandResult}>}
+ */
+async function waitForAndroidReadyLog({ driver, logcatLines, pattern, quietMs, rawFileName, timeoutMs, wait, }) {
+    const deadline = Date.now() + timeoutMs;
+    let lastMatchCount = -1;
+    let lastChangeAt = Date.now();
+    let result = await driver.readLogs({ lines: logcatLines, rawFileName });
+    for (;;) {
+        const matchCount = countAndroidReadyLogMatches({
+            logText: `${result.stdout}\n${result.stderr}`,
+            pattern,
+        });
+        if (matchCount !== lastMatchCount) {
+            lastMatchCount = matchCount;
+            lastChangeAt = Date.now();
+        }
+        const ready = matchCount > 0 && Date.now() - lastChangeAt >= quietMs;
+        if (ready || Date.now() >= deadline) {
+            return { ready, result };
+        }
+        await wait(ANDROID_READY_LOG_POLL_MS);
+        result = await driver.readLogs({ lines: logcatLines, rawFileName });
+    }
+}
+/**
+ * Builds a runner health artifact from adb preflight checks.
+ *
+ * @param {{runId: string, checks: Record<string, unknown>[]}} options
+ * @returns {Record<string, unknown>}
+ */
+function buildAndroidHealth({ runId, checks }) {
+    const failed = checks.some((check) => check.status === 'failed');
+    return assertValidJson({
+        schemaVersion: '1.0.0',
+        scenarioId: 'android-adb-preflight',
+        flowId: 'android-adb-preflight',
+        runId,
+        healthStatus: failed ? 'failed' : 'passed',
+        checks,
+    }, SCHEMAS.health, 'Health artifact');
+}
+/**
+ * Builds a verdict artifact for adb preflight readiness.
+ *
+ * @param {{runId: string, health: Record<string, unknown>}} options
+ * @returns {Record<string, unknown>}
+ */
+function buildAndroidVerdict({ runId, health }) {
+    const passed = health.healthStatus === 'passed';
+    return assertValidJson({
+        schemaVersion: '1.0.0',
+        scenarioId: 'android-adb-preflight',
+        flowId: 'android-adb-preflight',
+        runId,
+        healthStatus: health.healthStatus,
+        verdictStatus: passed ? 'not_evaluated' : 'inconclusive',
+        budgetChecks: [],
+        summary: passed
+            ? 'Android adb preflight passed; no product budget has been evaluated.'
+            : 'Android adb preflight failed; runtime scenario execution is not ready.',
+    }, SCHEMAS.verdict, 'Verdict artifact');
+}
+/**
+ * Builds the driver steps for this adb capture window.
+ *
+ * @param {{captureLogcat: boolean, driverSteps: AndroidAdbDriverStep[], logcatLines: number, waitMs: number}} options
+ * @returns {AndroidAdbDriverStep[]}
+ */
+function resolveAndroidAdbDriverSteps({ captureLogcat, driverSteps, logcatLines, waitMs, }) {
+    if (driverSteps.length > 0) {
+        let readLogsIndex = 0;
+        const resolved = driverSteps.map((step, index) => {
+            const actionIndex = index + 1;
+            if (step.driverAction === 'readLogs') {
+                readLogsIndex += 1;
+            }
+            return {
+                ...step,
+                ...(step.driverAction === 'readLogs' ? { lines: step.lines ?? logcatLines } : {}),
+                rawFileName: step.rawFileName ?? defaultAndroidAdbRawFileName({
+                    driverAction: step.driverAction,
+                    index: actionIndex,
+                    readLogsIndex,
+                }),
+                ...(step.driverAction === 'record'
+                    ? {
+                        captureFileName: step.captureFileName ?? defaultAndroidAdbCaptureFileName({
+                            driverAction: step.driverAction,
+                            index: actionIndex,
+                        }),
+                    }
+                    : {}),
+                required: step.required !== false,
+            };
+        });
+        if (captureLogcat && readLogsIndex === 0) {
+            resolved.push({
+                driverAction: 'readLogs',
+                lines: logcatLines,
+                rawFileName: 'adb-logcat.txt',
+                required: true,
+                ...(waitMs > 0 ? { waitMs } : {}),
+            });
+        }
+        return resolved;
+    }
+    return captureLogcat
+        ? [{
+                driverAction: 'readLogs',
+                lines: logcatLines,
+                rawFileName: 'adb-logcat.txt',
+                required: true,
+                ...(waitMs > 0 ? { waitMs } : {}),
+            }]
+        : [];
+}
+/**
+ * Returns the default raw evidence filename for one adb driver action.
+ *
+ * @param {{driverAction: AndroidAdbDriverStep['driverAction'], index: number, readLogsIndex: number}} options
+ * @returns {string}
+ */
+function defaultAndroidAdbRawFileName({ driverAction, index, readLogsIndex, }) {
+    if (driverAction === 'readLogs') {
+        return readLogsIndex === 1 ? 'adb-logcat.txt' : `adb-logcat-${readLogsIndex}.txt`;
+    }
+    const suffix = index === 1 ? '' : `-${index}`;
+    if (driverAction === 'inspectTree') {
+        return `adb-ui-tree${suffix}.xml`;
+    }
+    if (driverAction === 'assertVisible') {
+        return `adb-assert-visible${suffix}.xml`;
+    }
+    if (driverAction === 'screenshot') {
+        return `adb-screenshot${suffix}.png`;
+    }
+    return `adb-${driverAction}${suffix}.txt`;
+}
+/**
+ * Returns the default capture filename for one adb driver action.
+ *
+ * @param {{driverAction: AndroidAdbDriverStep['driverAction'], index: number}} options
+ * @returns {string}
+ */
+function defaultAndroidAdbCaptureFileName({ driverAction, index, }) {
+    const suffix = index === 1 ? '' : `-${index}`;
+    if (driverAction === 'record') {
+        return `adb-record${suffix}.mp4`;
+    }
+    return `adb-${driverAction}${suffix}`;
+}
+/**
+ * Builds a stable health code suffix for an adb driver action.
+ *
+ * @param {AndroidAdbDriverStep['driverAction']} driverAction
+ * @returns {string}
+ */
+function androidDriverActionCode(driverAction) {
+    return driverAction.replace(/[A-Z]/gu, (letter) => `_${letter.toLowerCase()}`);
+}
+/**
+ * Returns whether a driver step can derive missing coordinates from a selector.
+ *
+ * @param {AndroidAdbDriverStep} driverStep
+ * @returns {boolean}
+ */
+function needsAndroidSelectorResolution(driverStep) {
+    if (!driverStep.selector) {
+        return false;
+    }
+    if (driverStep.driverAction === 'tap') {
+        return typeof driverStep.x !== 'number' || typeof driverStep.y !== 'number';
+    }
+    return driverStep.driverAction === 'scroll' && (typeof driverStep.startX !== 'number' ||
+        typeof driverStep.startY !== 'number' ||
+        typeof driverStep.endX !== 'number' ||
+        typeof driverStep.endY !== 'number');
+}
+/**
+ * Applies a resolved selector to one tap or scroll driver step.
+ *
+ * @param {{driverStep: AndroidAdbDriverStep, resolution: import('./android-adb-driver').AndroidSelectorResolution}} options
+ * @returns {AndroidAdbDriverStep}
+ */
+function applyAndroidSelectorResolution({ driverStep, resolution, }) {
+    if (driverStep.driverAction === 'tap') {
+        return {
+            ...driverStep,
+            x: driverStep.x ?? resolution.centerX,
+            y: driverStep.y ?? resolution.centerY,
+        };
+    }
+    if (driverStep.driverAction === 'scroll') {
+        const coordinates = buildAndroidScrollCoordinatesFromBounds(resolution.bounds);
+        return {
+            ...driverStep,
+            endX: driverStep.endX ?? coordinates.endX,
+            endY: driverStep.endY ?? coordinates.endY,
+            startX: driverStep.startX ?? coordinates.startX,
+            startY: driverStep.startY ?? coordinates.startY,
+        };
+    }
+    return driverStep;
+}
+/**
+ * Converts a selector into scalar health-check metadata fields.
+ *
+ * @param {import('./android-adb-driver').AndroidSelector | undefined} selector
+ * @returns {Record<string, string>}
+ */
+function buildAndroidSelectorHealthMetadata(selector) {
+    if (!selector) {
+        return {};
+    }
+    return {
+        selectorKind: selector.kind,
+        selectorValue: selector.value,
+        ...(selector.match ? { selectorMatch: selector.match } : {}),
+    };
+}
+/**
+ * Returns a compact single-line adb driver failure preview.
+ *
+ * @param {import('./android-adb-driver').AndroidAdbCommandResult} driverResult
+ * @returns {string | null}
+ */
+function previewAndroidDriverFailure(driverResult) {
+    const preview = [driverResult.stderr, driverResult.stdout]
+        .filter(Boolean)
+        .join('\n')
+        .replace(/\s+/gu, ' ')
+        .trim();
+    return preview ? preview.slice(0, 500) : null;
+}
+/**
+ * Builds next-action metadata for failed adb driver steps.
+ *
+ * @param {{driverResult: import('./android-adb-driver').AndroidAdbCommandResult, isReadLogs: boolean}} options
+ * @returns {Record<string, string>}
+ */
+function buildAndroidDriverFailureMetadata({ driverResult, isReadLogs, }) {
+    const failurePreview = previewAndroidDriverFailure(driverResult);
+    const diagnostic = `${driverResult.stderr}\n${driverResult.stdout}`;
+    const uiAutomationBusy = /uiautomationservice|uiautomator|already registered|\/sdcard\/agent-scenario-loop-ui\.xml|killed/iu
+        .test(diagnostic);
+    const metadata = uiAutomationBusy
+        ? nextActionHint('reset_android_uiautomator', 'Android UIAutomator could not provide a UI tree, likely because another automation session owns the service. Close or reset competing UI automation sessions, then rerun the capture before treating this as an app or selector failure.')
+        : nextActionHint(isReadLogs ? 'inspect_android_logcat_capture' : 'inspect_android_driver_action', isReadLogs
+            ? `Inspect raw/${driverResult.rawFileName}, confirm adb logcat access for the selected device, and rerun the capture.`
+            : `Inspect raw/${driverResult.rawFileName}, confirm the device is interactive and the action metadata is valid, then rerun the capture.`);
+    return {
+        ...metadata,
+        ...(failurePreview ? { failurePreview } : {}),
+    };
+}
+/**
+ * Runs one normalized adb driver step through the Android driver adapter.
+ *
+ * @param {{driver: import('./android-adb-driver').AndroidAdbDriver, driverStep: AndroidAdbDriverStep, logcatLines: number}} options
+ * @returns {Promise<import('./android-adb-driver').AndroidAdbCommandResult>}
+ */
+async function runAndroidAdbDriverStep({ capturesDir, driver, driverStep, logcatLines, }) {
+    if (driverStep.driverAction === 'readLogs') {
+        return driver.readLogs({
+            lines: driverStep.lines ?? logcatLines,
+            ...(typeof driverStep.rawFileName === 'string' ? { rawFileName: driverStep.rawFileName } : {}),
+        });
+    }
+    if (driverStep.driverAction === 'inspectTree') {
+        return driver.inspectTree({
+            ...(typeof driverStep.rawFileName === 'string' ? { rawFileName: driverStep.rawFileName } : {}),
+        });
+    }
+    if (driverStep.driverAction === 'assertVisible') {
+        if (!driverStep.selector) {
+            return {
+                action: 'assertVisible',
+                args: [],
+                command: 'adb',
+                exitCode: 1,
+                rawFileName: driverStep.rawFileName ?? 'adb-assert-visible.xml',
+                stderr: 'assertVisible driver action requires a selector.',
+                stdout: '',
+            };
+        }
+        return driver.assertVisible({
+            ...(typeof driverStep.rawFileName === 'string' ? { rawFileName: driverStep.rawFileName } : {}),
+            selector: driverStep.selector,
+        });
+    }
+    if (driverStep.driverAction === 'record') {
+        const captureFileName = driverStep.captureFileName ?? 'adb-record.mp4';
+        return driver.record({
+            ...(typeof driverStep.durationSeconds === 'number' ? { durationSeconds: driverStep.durationSeconds } : {}),
+            outputPath: path.join(capturesDir, captureFileName),
+            ...(typeof driverStep.rawFileName === 'string' ? { rawFileName: driverStep.rawFileName } : {}),
+            ...(typeof driverStep.remotePath === 'string' ? { remotePath: driverStep.remotePath } : {}),
+        });
+    }
+    if (driverStep.driverAction === 'screenshot') {
+        return driver.screenshot({
+            ...(typeof driverStep.rawFileName === 'string' ? { rawFileName: driverStep.rawFileName } : {}),
+        });
+    }
+    if (driverStep.driverAction === 'scroll') {
+        if (typeof driverStep.startX !== 'number' ||
+            typeof driverStep.startY !== 'number' ||
+            typeof driverStep.endX !== 'number' ||
+            typeof driverStep.endY !== 'number') {
+            return {
+                action: 'scroll',
+                args: [],
+                command: 'adb',
+                exitCode: 1,
+                rawFileName: driverStep.rawFileName ?? 'adb-scroll.txt',
+                stderr: 'scroll driver action requires startX, startY, endX, and endY.',
+                stdout: '',
+            };
+        }
+        return driver.scroll({
+            ...(typeof driverStep.durationMs === 'number' ? { durationMs: driverStep.durationMs } : {}),
+            endX: driverStep.endX,
+            endY: driverStep.endY,
+            ...(typeof driverStep.rawFileName === 'string' ? { rawFileName: driverStep.rawFileName } : {}),
+            startX: driverStep.startX,
+            startY: driverStep.startY,
+        });
+    }
+    if (typeof driverStep.x !== 'number' || typeof driverStep.y !== 'number') {
+        return {
+            action: 'tap',
+            args: [],
+            command: 'adb',
+            exitCode: 1,
+            rawFileName: driverStep.rawFileName ?? 'adb-tap.txt',
+            stderr: 'tap driver action requires x and y.',
+            stdout: '',
+        };
+    }
+    return driver.tap({
+        ...(typeof driverStep.rawFileName === 'string' ? { rawFileName: driverStep.rawFileName } : {}),
+        x: driverStep.x,
+        y: driverStep.y,
+    });
+}
+/**
+ * Runs Android adb readiness checks and writes the preflight artifact set.
+ *
+ * @param {AndroidPreflightOptions} options
+ * @returns {Promise<AndroidPreflightResult>}
+ */
+async function runAndroidAdbPreflight({ adbPath = 'adb', captureLogcat = false, clearLogcat = false, deepLinks = [], delay: wait = delay, driverSteps = [], executor = execFileCommand, launch = false, launchWaitMs = 0, logcatLines = 1000, outputDir = path.resolve('artifacts/android-adb-preflight'), packageName = null, reactNativeDebugHost = null, runId = createRunId(), serial = null, startupDeepLinks = [], storageWrites = [], waitMs = 0, } = {}) {
+    const runDir = path.resolve(outputDir);
+    const layout = createArtifactLayout({ outputDir: runDir });
+    const rawDir = layout.raw;
+    await fsp.mkdir(rawDir, { recursive: true });
+    const raw = {};
+    const checks = [];
+    const version = await executor(adbPath, ['version']);
+    const adbAvailable = version.exitCode === 0;
+    raw['adb-version.txt'] = [version.stdout, version.stderr].filter(Boolean).join('\n');
+    checks.push({
+        name: 'adb_available',
+        status: adbAvailable ? 'passed' : 'failed',
+        source: 'runner',
+        code: adbAvailable ? 'adb_available' : 'adb_unavailable',
+        message: adbAvailable ? 'adb command is available.' : 'adb command could not be executed.',
+        ...(!adbAvailable
+            ? {
+                metadata: nextActionHint('fix_adb_command', 'Install Android platform-tools or pass --adb with a working adb binary, then rerun the capture.'),
+            }
+            : {}),
+    });
+    const devicesOutput = adbAvailable
+        ? await executor(adbPath, ['devices', '-l'])
+        : {
+            command: adbPath,
+            args: ['devices', '-l'],
+            exitCode: 1,
+            stderr: 'adb unavailable',
+            stdout: '',
+        };
+    raw['adb-devices.txt'] = [devicesOutput.stdout, devicesOutput.stderr].filter(Boolean).join('\n');
+    const devices = parseAdbDevices(devicesOutput.stdout);
+    const device = selectDevice(devices, serial);
+    const deviceOnline = Boolean(device && device.state === 'device');
+    const deviceFailure = !deviceOnline
+        ? buildAndroidDeviceFailure({ devicesOutput, serial })
+        : null;
+    checks.push({
+        name: 'android_device_connected',
+        status: deviceOnline ? 'passed' : 'failed',
+        source: 'runner',
+        code: deviceOnline ? 'android_device_connected' : deviceFailure?.code,
+        message: deviceOnline && device
+            ? `Selected Android device ${device.serial}.`
+            : deviceFailure?.message,
+        ...(!deviceOnline
+            ? {
+                metadata: deviceFailure?.metadata,
+            }
+            : {}),
+    });
+    const metadata = {
+        adbPath,
+        captureLogcat,
+        clearLogcat,
+        deepLinks,
+        devices,
+        driverSteps,
+        launch,
+        logcatLines,
+        selectedDevice: device,
+        packageName,
+        reactNativeDebugHost,
+        startupDeepLinks,
+        storageWrites: storageWrites.map((write) => ({
+            clearKeys: write.clearKeys,
+            key: write.key,
+            label: write.label,
+            waitMs: write.waitMs,
+        })),
+        waitMs,
+    };
+    const resolvedDriverSteps = resolveAndroidAdbDriverSteps({
+        captureLogcat,
+        driverSteps,
+        logcatLines,
+        waitMs,
+    });
+    if (device && device.state === 'device') {
+        const shellPrefix = ['-s', device.serial, 'shell'];
+        const driver = createAndroidAdbDriver({
+            adbPath,
+            deviceSerial: device.serial,
+            executor,
+        });
+        const [model, release, sdk] = await Promise.all([
+            executor(adbPath, [...shellPrefix, 'getprop', 'ro.product.model']),
+            executor(adbPath, [...shellPrefix, 'getprop', 'ro.build.version.release']),
+            executor(adbPath, [...shellPrefix, 'getprop', 'ro.build.version.sdk']),
+        ]);
+        metadata.deviceProperties = {
+            model: model.stdout.trim(),
+            release: release.stdout.trim(),
+            sdk: sdk.stdout.trim(),
+        };
+        raw['adb-device-properties.txt'] = [
+            `model=${model.stdout.trim()}`,
+            `release=${release.stdout.trim()}`,
+            `sdk=${sdk.stdout.trim()}`,
+        ].join('\n');
+        let selectedPackageInstalled = false;
+        if (packageName) {
+            const packageCheck = await executor(adbPath, [...shellPrefix, 'pm', 'path', packageName]);
+            raw['adb-package.txt'] = [packageCheck.stdout, packageCheck.stderr].filter(Boolean).join('\n');
+            const packageInstalled = packageCheck.exitCode === 0 && packageCheck.stdout.includes('package:');
+            selectedPackageInstalled = packageInstalled;
+            checks.push({
+                name: 'android_package_installed',
+                status: packageInstalled ? 'passed' : 'failed',
+                source: 'runner',
+                code: packageInstalled
+                    ? 'android_package_installed'
+                    : 'android_package_missing',
+                message: packageInstalled
+                    ? `Package ${packageName} is installed.`
+                    : `Package ${packageName} is not installed on ${device.serial}.`,
+                ...(!packageInstalled
+                    ? {
+                        metadata: nextActionHint('install_android_package', 'Build and install the app on the selected device, or rerun with --package set to the installed application id.'),
+                    }
+                    : {}),
+            });
+        }
+        if (reactNativeDebugHost) {
+            const reactNativeDebugPort = parseReactNativeDebugHostPort(reactNativeDebugHost);
+            if (!packageName) {
+                checks.push({
+                    name: 'android_react_native_debug_host_configured',
+                    status: 'failed',
+                    source: 'runner',
+                    code: 'android_react_native_debug_host_missing_package',
+                    message: 'React Native debug host setup was requested, but --package was not provided.',
+                    metadata: nextActionHint('provide_android_package', 'Rerun with --package set to the installed Android application id when --react-native-debug-host is enabled.'),
+                });
+            }
+            else if (!selectedPackageInstalled) {
+                checks.push({
+                    name: 'android_react_native_debug_host_configured',
+                    status: 'failed',
+                    source: 'runner',
+                    code: 'android_react_native_debug_host_package_missing',
+                    message: `React Native debug host setup requires installed package ${packageName}.`,
+                    metadata: nextActionHint('install_android_package', 'Build and install the app on the selected device before configuring the React Native debug host.'),
+                });
+            }
+            else if (!reactNativeDebugPort) {
+                checks.push({
+                    name: 'android_react_native_debug_host_configured',
+                    status: 'failed',
+                    source: 'runner',
+                    code: 'android_react_native_debug_host_invalid',
+                    message: `React Native debug host ${reactNativeDebugHost} must be a host:port value without a URL scheme.`,
+                    metadata: nextActionHint('fix_react_native_debug_host', 'Pass a React Native debug host such as localhost:8097, not a full http:// URL.'),
+                });
+            }
+            else {
+                const reverseResult = await executor(adbPath, [
+                    '-s',
+                    device.serial,
+                    'reverse',
+                    `tcp:${reactNativeDebugPort}`,
+                    `tcp:${reactNativeDebugPort}`,
+                ]);
+                const preferenceCommand = buildReactNativeDebugHostPreferenceCommand({
+                    debugHost: reactNativeDebugHost,
+                    packageName,
+                });
+                const preferenceResult = await executor(adbPath, [
+                    '-s',
+                    device.serial,
+                    'shell',
+                    'run-as',
+                    packageName,
+                    'sh',
+                    '-c',
+                    quoteAndroidShellArg(preferenceCommand),
+                ]);
+                const reversePassed = reverseResult.exitCode === 0;
+                const preferencePassed = preferenceResult.exitCode === 0;
+                raw['adb-react-native-reverse.txt'] = formatAndroidCommandRawOutput(reverseResult);
+                raw['adb-react-native-debug-host.txt'] = formatAndroidCommandRawOutput(preferenceResult);
+                checks.push({
+                    name: 'android_react_native_reverse_configured',
+                    status: reversePassed ? 'passed' : 'failed',
+                    source: 'runner',
+                    code: reversePassed
+                        ? 'android_react_native_reverse_configured'
+                        : 'android_react_native_reverse_failed',
+                    message: reversePassed
+                        ? `Configured adb reverse for React Native debug port ${reactNativeDebugPort}.`
+                        : `Failed to configure adb reverse for React Native debug port ${reactNativeDebugPort}.`,
+                    ...(!reversePassed
+                        ? {
+                            metadata: nextActionHint('inspect_android_react_native_reverse', 'Inspect raw/adb-react-native-reverse.txt, confirm the selected device supports adb reverse, then rerun the capture.'),
+                        }
+                        : {}),
+                });
+                checks.push({
+                    name: 'android_react_native_debug_host_configured',
+                    status: preferencePassed ? 'passed' : 'failed',
+                    source: 'runner',
+                    code: preferencePassed
+                        ? 'android_react_native_debug_host_configured'
+                        : 'android_react_native_debug_host_failed',
+                    message: preferencePassed
+                        ? `Configured React Native debug host ${reactNativeDebugHost} for ${packageName}.`
+                        : `Failed to configure React Native debug host ${reactNativeDebugHost} for ${packageName}.`,
+                    ...(!preferencePassed
+                        ? {
+                            metadata: nextActionHint('inspect_android_react_native_debug_host', 'Inspect raw/adb-react-native-debug-host.txt, confirm the app is debuggable and run-as works for the package, then rerun the capture.'),
+                        }
+                        : {}),
+                });
+                metadata.reactNativeDebugHostSetup = {
+                    debugHost: reactNativeDebugHost,
+                    port: reactNativeDebugPort,
+                    preferenceRawPath: 'raw/adb-react-native-debug-host.txt',
+                    reverseRawPath: 'raw/adb-react-native-reverse.txt',
+                };
+            }
+        }
+        if (clearLogcat) {
+            const clear = await driver.clearLogs();
+            const logcatCleared = clear.exitCode === 0;
+            raw[clear.rawFileName] = formatAndroidAdbRawOutput(clear);
+            checks.push({
+                name: 'android_logcat_cleared',
+                status: logcatCleared ? 'passed' : 'failed',
+                source: 'runner',
+                code: logcatCleared ? 'android_logcat_cleared' : 'android_logcat_clear_failed',
+                message: logcatCleared ? 'Cleared adb logcat before capture.' : 'adb logcat clear failed.',
+                ...(!logcatCleared
+                    ? {
+                        metadata: nextActionHint('inspect_adb_logcat_clear', `Inspect raw/${clear.rawFileName}, confirm the selected device allows logcat access, then rerun the capture.`),
+                    }
+                    : {}),
+            });
+            metadata.logcatClear = {
+                args: clear.args,
+                exitCode: clear.exitCode,
+                rawPath: `raw/${clear.rawFileName}`,
+            };
+        }
+        const appLifecycleMetadata = {};
+        let lifecyclePackageName = null;
+        let knownLifecyclePids = [];
+        if (launch) {
+            if (!packageName) {
+                checks.push({
+                    name: 'android_package_launched',
+                    status: 'failed',
+                    source: 'runner',
+                    code: 'android_launch_missing_package',
+                    message: 'Package launch was requested, but --package was not provided.',
+                    metadata: nextActionHint('provide_android_package', 'Rerun with --package set to the installed Android application id when --launch is enabled.'),
+                });
+            }
+            else {
+                const launchResult = await driver.launchPackage(packageName);
+                const launchPassed = launchResult.exitCode === 0;
+                raw[launchResult.rawFileName] = formatAndroidAdbRawOutput(launchResult);
+                checks.push({
+                    name: 'android_package_launched',
+                    status: launchPassed ? 'passed' : 'failed',
+                    source: 'runner',
+                    code: launchPassed ? 'android_package_launched' : 'android_package_launch_failed',
+                    message: launchPassed
+                        ? `Launched package ${packageName}.`
+                        : `Failed to launch package ${packageName}.`,
+                    ...(!launchPassed
+                        ? {
+                            metadata: nextActionHint('inspect_android_launch', `Inspect raw/${launchResult.rawFileName}, verify the package has a launcher activity, and confirm the app can open manually on the device.`),
+                        }
+                        : {}),
+                });
+                metadata.launchResult = {
+                    args: launchResult.args,
+                    exitCode: launchResult.exitCode,
+                    rawPath: `raw/${launchResult.rawFileName}`,
+                };
+                if (launchPassed && launchWaitMs > 0) {
+                    await wait(launchWaitMs);
+                    checks.push({
+                        name: 'android_launch_waited',
+                        status: 'passed',
+                        source: 'runner',
+                        code: 'android_launch_waited',
+                        message: `Waited ${launchWaitMs}ms after Android package launch.`,
+                    });
+                    metadata.launchWaitMs = launchWaitMs;
+                }
+                if (launchPassed) {
+                    lifecyclePackageName = packageName;
+                    const pidofAfterLaunch = await executor(adbPath, [
+                        '-s',
+                        device.serial,
+                        'shell',
+                        'pidof',
+                        packageName,
+                    ]);
+                    const rawPath = 'raw/adb-app-pidof-after-launch.txt';
+                    raw['adb-app-pidof-after-launch.txt'] = formatAndroidCommandRawOutput(pidofAfterLaunch);
+                    const afterLaunchPids = parseAndroidPidofOutput(pidofAfterLaunch.stdout);
+                    knownLifecyclePids = afterLaunchPids;
+                    const runningAfterLaunch = pidofAfterLaunch.exitCode === 0 && afterLaunchPids.length > 0;
+                    checks.push({
+                        name: 'android_app_process_running_after_launch',
+                        status: runningAfterLaunch ? 'passed' : 'failed',
+                        source: 'runner',
+                        code: runningAfterLaunch
+                            ? 'android_app_process_running_after_launch'
+                            : 'android_app_not_running_after_launch',
+                        message: runningAfterLaunch
+                            ? `Package ${packageName} is running after launch with PID ${afterLaunchPids.join(', ')}.`
+                            : `Package ${packageName} is not running after launch.`,
+                        ...(!runningAfterLaunch
+                            ? {
+                                metadata: nextActionHint('inspect_android_app_launch', `Inspect ${rawPath} and the app's device logs to find why the launched process exited before evidence capture.`),
+                            }
+                            : {}),
+                    });
+                    Object.assign(appLifecycleMetadata, {
+                        afterLaunchPids,
+                        afterLaunchRawPath: rawPath,
+                    });
+                }
+            }
+        }
+        for (const [index, deepLink] of startupDeepLinks.entries()) {
+            const rawFileName = `adb-startup-deep-link-${index + 1}.txt`;
+            const deepLinkResult = await driver.openDeepLink({
+                packageName,
+                rawFileName,
+                url: deepLink.url,
+            });
+            const deepLinkOpened = deepLinkResult.exitCode === 0;
+            raw[deepLinkResult.rawFileName] = formatAndroidAdbRawOutput(deepLinkResult);
+            checks.push({
+                name: 'android_startup_deep_link_opened',
+                status: deepLinkOpened ? 'passed' : 'failed',
+                source: 'runner',
+                code: deepLinkOpened ? 'android_startup_deep_link_opened' : 'android_startup_deep_link_failed',
+                message: deepLinkOpened
+                    ? `Opened Android startup deep link ${deepLink.label ?? index + 1}.`
+                    : `Failed to open Android startup deep link ${deepLink.label ?? index + 1}.`,
+                ...(!deepLinkOpened
+                    ? {
+                        metadata: nextActionHint('inspect_android_startup_deep_link', `Inspect raw/${deepLinkResult.rawFileName}, verify the dev-client URL and package intent filter, then rerun the capture.`),
+                    }
+                    : {}),
+            });
+            if (deepLink.waitMs && deepLink.waitMs > 0) {
+                await wait(deepLink.waitMs);
+                checks.push({
+                    name: 'android_startup_deep_link_waited',
+                    status: 'passed',
+                    source: 'runner',
+                    code: 'android_startup_deep_link_waited',
+                    message: `Waited ${deepLink.waitMs}ms after Android startup deep link ${deepLink.label ?? index + 1}.`,
+                });
+            }
+            if (deepLink.readyLogPattern) {
+                const rawFileName = `adb-startup-deep-link-${index + 1}-ready-log.txt`;
+                const readyLog = await waitForAndroidReadyLog({
+                    driver,
+                    logcatLines,
+                    pattern: deepLink.readyLogPattern,
+                    quietMs: deepLink.readyLogQuietMs ?? 0,
+                    rawFileName,
+                    timeoutMs: deepLink.readyLogTimeoutMs ?? 60000,
+                    wait,
+                });
+                raw[rawFileName] = formatAndroidAdbRawOutput(readyLog.result);
+                checks.push({
+                    name: 'android_startup_deep_link_ready',
+                    status: readyLog.ready ? 'passed' : 'failed',
+                    source: 'runner',
+                    code: readyLog.ready
+                        ? 'android_startup_deep_link_ready'
+                        : 'android_startup_deep_link_not_ready',
+                    message: readyLog.ready
+                        ? `Android startup deep link ${deepLink.label ?? index + 1} emitted readiness log evidence.`
+                        : `Android startup deep link ${deepLink.label ?? index + 1} did not emit readiness log evidence before timeout.`,
+                    ...(!readyLog.ready
+                        ? {
+                            metadata: nextActionHint('inspect_android_startup_deep_link_ready_log', `Inspect raw/${rawFileName}, confirm the dev-client loaded the app bundle, and increase the ready timeout only if the app is still making progress.`),
+                        }
+                        : {}),
+                });
+            }
+        }
+        for (const [index, write] of storageWrites.entries()) {
+            const rawFileName = `adb-async-storage-write-${index + 1}.txt`;
+            if (!packageName) {
+                checks.push({
+                    name: 'android_async_storage_written',
+                    status: 'failed',
+                    source: 'runner',
+                    code: 'android_async_storage_missing_package',
+                    message: 'Android AsyncStorage write was requested, but --package was not provided.',
+                    metadata: nextActionHint('provide_android_package', 'Rerun with --package set to the installed Android application id when Android AsyncStorage profile-session storage is enabled.'),
+                });
+                continue;
+            }
+            let resolvedWrite = write;
+            if (write.value.includes(ANDROID_DEVICE_EPOCH_MS_PLACEHOLDER)) {
+                const deviceEpoch = await readAndroidDeviceEpochMs({
+                    adbPath,
+                    deviceSerial: device.serial,
+                    executor,
+                });
+                raw['adb-device-epoch-ms.txt'] = formatAndroidCommandRawOutput(deviceEpoch);
+                const deviceClockRead = typeof deviceEpoch.epochMs === 'number';
+                checks.push({
+                    name: 'android_device_clock_read',
+                    status: deviceClockRead ? 'passed' : 'failed',
+                    source: 'runner',
+                    code: deviceClockRead ? 'android_device_clock_read' : 'android_device_clock_unavailable',
+                    message: deviceClockRead
+                        ? `Read Android device clock as ${deviceEpoch.epochMs}ms since epoch.`
+                        : 'Failed to read Android device clock for AsyncStorage timing evidence.',
+                    ...(!deviceClockRead
+                        ? {
+                            metadata: nextActionHint('inspect_android_device_clock', 'Inspect raw/adb-device-epoch-ms.txt and confirm the selected Android device supports `adb shell date +%s` before using storage-backed timing evidence.'),
+                        }
+                        : {}),
+                });
+                if (!deviceClockRead || deviceEpoch.epochMs === null) {
+                    continue;
+                }
+                resolvedWrite = {
+                    ...write,
+                    value: write.value.replaceAll(ANDROID_DEVICE_EPOCH_MS_PLACEHOLDER, String(deviceEpoch.epochMs)),
+                };
+            }
+            const writeResult = await executor(adbPath, [
+                '-s',
+                device.serial,
+                'shell',
+                buildAndroidAsyncStorageWriteCommand({ packageName, write: resolvedWrite }),
+            ]);
+            const writePassed = writeResult.exitCode === 0;
+            raw[rawFileName] = formatAndroidCommandRawOutput(writeResult);
+            checks.push({
+                name: 'android_async_storage_written',
+                status: writePassed ? 'passed' : 'failed',
+                source: 'runner',
+                code: writePassed ? 'android_async_storage_written' : 'android_async_storage_write_failed',
+                message: writePassed
+                    ? `Wrote Android AsyncStorage value ${write.label ?? index + 1}.`
+                    : `Failed to write Android AsyncStorage value ${write.label ?? index + 1}.`,
+                ...(!writePassed
+                    ? {
+                        metadata: nextActionHint('inspect_android_async_storage_write', `Inspect raw/${rawFileName}, confirm the app is debuggable and sqlite3 can access RKStorage through run-as, then rerun the capture.`),
+                    }
+                    : {}),
+            });
+            if (write.waitMs && write.waitMs > 0) {
+                await wait(write.waitMs);
+                checks.push({
+                    name: 'android_async_storage_waited',
+                    status: 'passed',
+                    source: 'runner',
+                    code: 'android_async_storage_waited',
+                    message: `Waited ${write.waitMs}ms after Android AsyncStorage write ${write.label ?? index + 1}.`,
+                });
+            }
+        }
+        for (const [index, deepLink] of deepLinks.entries()) {
+            const rawFileName = `adb-deep-link-${index + 1}.txt`;
+            const deepLinkResult = await driver.openDeepLink({
+                packageName,
+                rawFileName,
+                url: deepLink.url,
+            });
+            const deepLinkOpened = deepLinkResult.exitCode === 0;
+            raw[deepLinkResult.rawFileName] = formatAndroidAdbRawOutput(deepLinkResult);
+            checks.push({
+                name: 'android_deep_link_opened',
+                status: deepLinkOpened ? 'passed' : 'failed',
+                source: 'runner',
+                code: deepLinkOpened ? 'android_deep_link_opened' : 'android_deep_link_failed',
+                message: deepLinkOpened
+                    ? `Opened Android deep link ${deepLink.label ?? index + 1}.`
+                    : `Failed to open Android deep link ${deepLink.label ?? index + 1}.`,
+                ...(!deepLinkOpened
+                    ? {
+                        metadata: nextActionHint('inspect_android_deep_link', `Inspect raw/${deepLinkResult.rawFileName}, verify the app scheme/intent filter, and rerun with --package if the intent must target one app.`),
+                    }
+                    : {}),
+            });
+            if (deepLink.waitMs && deepLink.waitMs > 0) {
+                await wait(deepLink.waitMs);
+                checks.push({
+                    name: 'android_deep_link_waited',
+                    status: 'passed',
+                    source: 'runner',
+                    code: 'android_deep_link_waited',
+                    message: `Waited ${deepLink.waitMs}ms after Android deep link ${deepLink.label ?? index + 1}.`,
+                });
+            }
+            if (deepLinkOpened && packageName && !lifecyclePackageName) {
+                lifecyclePackageName = packageName;
+                const pidofAfterDeepLink = await executor(adbPath, [
+                    '-s',
+                    device.serial,
+                    'shell',
+                    'pidof',
+                    packageName,
+                ]);
+                const rawPath = 'raw/adb-app-pidof-after-deep-link.txt';
+                raw['adb-app-pidof-after-deep-link.txt'] = formatAndroidCommandRawOutput(pidofAfterDeepLink);
+                const afterDeepLinkPids = parseAndroidPidofOutput(pidofAfterDeepLink.stdout);
+                knownLifecyclePids = afterDeepLinkPids;
+                const runningAfterDeepLink = pidofAfterDeepLink.exitCode === 0 && afterDeepLinkPids.length > 0;
+                checks.push({
+                    name: 'android_app_process_running_after_deep_link',
+                    status: runningAfterDeepLink ? 'passed' : 'failed',
+                    source: 'runner',
+                    code: runningAfterDeepLink
+                        ? 'android_app_process_running_after_deep_link'
+                        : 'android_app_not_running_after_deep_link',
+                    message: runningAfterDeepLink
+                        ? `Package ${packageName} is running after deep link with PID ${afterDeepLinkPids.join(', ')}.`
+                        : `Package ${packageName} is not running after opening the deep link.`,
+                    ...(!runningAfterDeepLink
+                        ? {
+                            metadata: nextActionHint('inspect_android_deep_link_launch', `Inspect ${rawPath} and the app's device logs to find why the package-targeted deep link did not leave the app process running.`),
+                        }
+                        : {}),
+                });
+                Object.assign(appLifecycleMetadata, {
+                    afterDeepLinkPids,
+                    afterDeepLinkRawPath: rawPath,
+                });
+            }
+        }
+        const driverActionMetadata = [];
+        const logcatMetadata = [];
+        const selectorResolutionMetadata = [];
+        for (const [index, driverStep] of resolvedDriverSteps.entries()) {
+            if (driverStep.waitMs && driverStep.waitMs > 0) {
+                await wait(driverStep.waitMs);
+                checks.push({
+                    name: 'android_capture_window_waited',
+                    status: 'passed',
+                    source: 'runner',
+                    code: 'android_capture_window_waited',
+                    message: `Waited ${driverStep.waitMs}ms before running adb driver action ${driverStep.driverAction}.`,
+                    metadata: {
+                        driverAction: driverStep.driverAction,
+                        ...(driverStep.stepId ? { stepId: driverStep.stepId } : {}),
+                    },
+                });
+            }
+            let executableDriverStep = driverStep;
+            if (needsAndroidSelectorResolution(driverStep)) {
+                const selectorRawFileName = `adb-selector-tree-${index + 1}.xml`;
+                const treeResult = await driver.inspectTree({ rawFileName: selectorRawFileName });
+                raw[treeResult.rawFileName] = formatAndroidAdbRawOutput(treeResult);
+                const resolution = treeResult.exitCode === 0 && driverStep.selector
+                    ? resolveAndroidSelectorFromUiTree({
+                        selector: driverStep.selector,
+                        uiTreeXml: treeResult.stdout,
+                    })
+                    : null;
+                const resolved = Boolean(resolution);
+                if (resolution) {
+                    executableDriverStep = applyAndroidSelectorResolution({
+                        driverStep,
+                        resolution,
+                    });
+                }
+                checks.push({
+                    name: 'android_selector_resolved',
+                    status: resolved ? 'passed' : driverStep.required === false ? 'warning' : 'failed',
+                    source: 'runner',
+                    code: resolved ? 'android_selector_resolved' : 'android_selector_resolution_failed',
+                    message: resolved
+                        ? `Resolved Android selector for adb driver action ${driverStep.driverAction}.`
+                        : `Failed to resolve Android selector for adb driver action ${driverStep.driverAction}.`,
+                    metadata: {
+                        driverAction: driverStep.driverAction,
+                        ...buildAndroidSelectorHealthMetadata(driverStep.selector),
+                        ...(!resolved
+                            ? nextActionHint('fix_android_selector', `Inspect raw/${treeResult.rawFileName}, update the scenario selector, or provide explicit adb coordinates for this driver action.`)
+                            : {}),
+                        ...(driverStep.stepId ? { stepId: driverStep.stepId } : {}),
+                    },
+                });
+                selectorResolutionMetadata.push({
+                    ...(resolution ? { bounds: resolution.bounds } : {}),
+                    driverAction: driverStep.driverAction,
+                    rawPath: `raw/${treeResult.rawFileName}`,
+                    ...(driverStep.selector ? { selector: driverStep.selector } : {}),
+                    status: resolved ? 'passed' : 'failed',
+                    ...(driverStep.stepId ? { stepId: driverStep.stepId } : {}),
+                });
+            }
+            const driverResult = await runAndroidAdbDriverStep({
+                capturesDir: layout.captures,
+                driver,
+                driverStep: executableDriverStep,
+                logcatLines,
+            });
+            raw[driverResult.rawFileName] = formatAndroidAdbRawOutput(driverResult);
+            const failed = driverResult.exitCode !== 0;
+            const codeSuffix = androidDriverActionCode(driverStep.driverAction);
+            const isReadLogs = driverStep.driverAction === 'readLogs';
+            checks.push({
+                name: isReadLogs ? 'android_logcat_captured' : `android_${codeSuffix}`,
+                status: failed && driverStep.required === false ? 'warning' : failed ? 'failed' : 'passed',
+                source: 'runner',
+                code: isReadLogs
+                    ? driverResult.exitCode === 0 ? 'android_logcat_captured' : 'android_logcat_failed'
+                    : driverResult.exitCode === 0 ? `android_${codeSuffix}_completed` : `android_${codeSuffix}_failed`,
+                message: isReadLogs
+                    ? driverResult.exitCode === 0
+                        ? `Captured the last ${driverStep.lines ?? logcatLines} adb logcat lines.`
+                        : 'adb logcat capture failed.'
+                    : driverResult.exitCode === 0
+                        ? `Completed adb driver action ${driverStep.driverAction}.`
+                        : `adb driver action ${driverStep.driverAction} failed.`,
+                metadata: {
+                    driverAction: executableDriverStep.driverAction,
+                    ...buildAndroidSelectorHealthMetadata(executableDriverStep.selector),
+                    ...(failed ? buildAndroidDriverFailureMetadata({ driverResult, isReadLogs }) : {}),
+                    ...(executableDriverStep.stepId ? { stepId: executableDriverStep.stepId } : {}),
+                },
+            });
+            const actionMetadata = {
+                args: driverResult.args,
+                driverAction: executableDriverStep.driverAction,
+                exitCode: driverResult.exitCode,
+                ...(driverResult.capturePath
+                    ? { capturePath: `captures/${path.basename(driverResult.capturePath)}` }
+                    : {}),
+                rawPath: `raw/${driverResult.rawFileName}`,
+                ...(executableDriverStep.selector ? { selector: executableDriverStep.selector } : {}),
+                ...(executableDriverStep.stepId ? { stepId: executableDriverStep.stepId } : {}),
+            };
+            driverActionMetadata.push(actionMetadata);
+            if (executableDriverStep.driverAction === 'readLogs') {
+                logcatMetadata.push(actionMetadata);
+            }
+        }
+        if (selectorResolutionMetadata.length > 0) {
+            metadata.selectorResolutions = selectorResolutionMetadata;
+        }
+        if (driverActionMetadata.length > 0) {
+            metadata.driverActions = driverActionMetadata;
+        }
+        if (logcatMetadata.length === 1) {
+            metadata.logcat = logcatMetadata[0];
+        }
+        else if (logcatMetadata.length > 1) {
+            metadata.logcat = logcatMetadata;
+        }
+        if (lifecyclePackageName) {
+            const pidofAfterCapture = await executor(adbPath, [
+                '-s',
+                device.serial,
+                'shell',
+                'pidof',
+                lifecyclePackageName,
+            ]);
+            const pidofAfterCaptureRawPath = 'raw/adb-app-pidof-after-capture.txt';
+            raw['adb-app-pidof-after-capture.txt'] = formatAndroidCommandRawOutput(pidofAfterCapture);
+            const afterCapturePids = parseAndroidPidofOutput(pidofAfterCapture.stdout);
+            const lifecycleLogLines = Math.max(logcatLines, 200);
+            const lifecycleLog = await driver.readLogs({
+                lines: lifecycleLogLines,
+                rawFileName: 'adb-app-lifecycle-log.txt',
+            });
+            raw[lifecycleLog.rawFileName] = formatAndroidAdbRawOutput(lifecycleLog);
+            const allKnownPids = Array.from(new Set([...knownLifecyclePids, ...afterCapturePids]));
+            const scan = lifecycleLog.exitCode === 0
+                ? scanAndroidAppLifecycleLog({
+                    logText: `${lifecycleLog.stdout}\n${lifecycleLog.stderr}`,
+                    packageName: lifecyclePackageName,
+                    pids: allKnownPids,
+                })
+                : { crashed: false, evidence: [] };
+            const runningAfterCapture = pidofAfterCapture.exitCode === 0 && afterCapturePids.length > 0;
+            const lifecycleStatus = !runningAfterCapture || scan.crashed
+                ? 'failed'
+                : lifecycleLog.exitCode === 0
+                    ? 'passed'
+                    : 'warning';
+            checks.push({
+                name: 'android_app_lifecycle_stable',
+                status: lifecycleStatus,
+                source: 'runner',
+                code: !runningAfterCapture
+                    ? 'android_app_exited_during_capture'
+                    : scan.crashed
+                        ? 'android_app_crashed_during_capture'
+                        : lifecycleLog.exitCode === 0
+                            ? 'android_app_lifecycle_stable'
+                            : 'android_app_lifecycle_log_unavailable',
+                message: !runningAfterCapture
+                    ? `Package ${lifecyclePackageName} was not running after evidence capture.`
+                    : scan.crashed
+                        ? `Package ${lifecyclePackageName} emitted crash evidence during capture.`
+                        : lifecycleLog.exitCode === 0
+                            ? `Package ${lifecyclePackageName} remained running with no crash evidence in the bounded log window.`
+                            : `Could not read Android lifecycle logs for package ${lifecyclePackageName}.`,
+                ...(!runningAfterCapture || scan.crashed
+                    ? {
+                        metadata: nextActionHint('inspect_android_app_crash', `Inspect raw/${lifecycleLog.rawFileName} and ${pidofAfterCaptureRawPath}; scenario timing evidence is not trustworthy until the app stays alive.`),
+                    }
+                    : lifecycleLog.exitCode !== 0
+                        ? {
+                            metadata: nextActionHint('inspect_android_lifecycle_log', `Inspect raw/${lifecycleLog.rawFileName}; lifecycle log capture failed but the app process was still running.`),
+                        }
+                        : {}),
+            });
+            metadata.appLifecycle = {
+                ...appLifecycleMetadata,
+                afterCapturePids,
+                afterCaptureRawPath: pidofAfterCaptureRawPath,
+                crashEvidence: scan.evidence,
+                lifecycleLogLines,
+                lifecycleLogRawPath: `raw/${lifecycleLog.rawFileName}`,
+                packageName: lifecyclePackageName,
+            };
+        }
+    }
+    else {
+        if (clearLogcat || launch || startupDeepLinks.length > 0 || storageWrites.length > 0) {
+            checks.push({
+                name: 'android_capture_window_started',
+                status: 'failed',
+                source: 'runner',
+                code: 'android_capture_window_no_device',
+                message: 'Android capture window setup was requested, but no online Android device was selected.',
+                metadata: nextActionHint('select_android_device', 'Start or unlock an Android emulator/device, confirm it appears as `device` in adb devices -l, then rerun the capture.'),
+            });
+        }
+        if (resolvedDriverSteps.some((step) => step.driverAction === 'readLogs')) {
+            checks.push({
+                name: 'android_logcat_captured',
+                status: 'failed',
+                source: 'runner',
+                code: 'android_logcat_no_device',
+                message: 'adb logcat capture was requested, but no online Android device was selected.',
+                metadata: nextActionHint('select_android_device', 'Start or unlock an Android emulator/device before requesting logcat capture.'),
+            });
+        }
+        if (resolvedDriverSteps.some((step) => step.driverAction !== 'readLogs')) {
+            checks.push({
+                name: 'android_driver_actions_completed',
+                status: 'failed',
+                source: 'runner',
+                code: 'android_driver_actions_no_device',
+                message: 'adb driver actions were requested, but no online Android device was selected.',
+                metadata: nextActionHint('select_android_device', 'Start or unlock an Android emulator/device before running adb driver actions.'),
+            });
+        }
+    }
+    const health = buildAndroidHealth({ runId, checks });
+    const verdict = buildAndroidVerdict({ runId, health });
+    const agentSummary = buildAgentSummaryMarkdown({ health, verdict });
+    await Promise.all(Object.entries(raw).map(([fileName, content]) => fsp.writeFile(path.join(rawDir, fileName), `${content.trimEnd()}\n`, 'utf8')));
+    await fsp.writeFile(path.join(rawDir, 'android-metadata.json'), `${JSON.stringify(metadata, null, 2)}\n`, 'utf8');
+    await writeJsonArtifact({
+        filePath: layout.health,
+        value: health,
+        schema: SCHEMAS.health,
+        label: 'Health artifact',
+    });
+    await writeJsonArtifact({
+        filePath: layout.verdict,
+        value: verdict,
+        schema: SCHEMAS.verdict,
+        label: 'Verdict artifact',
+    });
+    await writeTextArtifact({
+        filePath: layout.agentSummary,
+        content: agentSummary,
+    });
+    return {
+        agentSummary,
+        device,
+        health,
+        metadata,
+        raw,
+        runDir,
+        verdict,
+    };
+}
+/**
+ * Runs the android-adb preflight CLI.
+ *
+ * @returns {Promise<void>}
+ */
+async function main() {
+    const argv = process.argv.slice(2);
+    if (hasHelpFlag(argv)) {
+        usage(process.stdout);
+        return;
+    }
+    const args = parseArgs(argv);
+    const result = await runAndroidAdbPreflight({
+        ...(typeof args.adb === 'string' ? { adbPath: args.adb } : {}),
+        captureLogcat: args['capture-logcat'] === true || args['capture-logcat'] === 'true',
+        clearLogcat: args['clear-logcat'] === true || args['clear-logcat'] === 'true',
+        launch: args.launch === true || args.launch === 'true',
+        launchWaitMs: parsePositiveInteger(args['launch-wait-ms'], 0),
+        logcatLines: parsePositiveInteger(args['logcat-lines'], 1000),
+        ...(typeof args.out === 'string' ? { outputDir: args.out } : {}),
+        ...(typeof args.package === 'string' ? { packageName: args.package } : {}),
+        ...(typeof args['react-native-debug-host'] === 'string'
+            ? { reactNativeDebugHost: args['react-native-debug-host'] }
+            : {}),
+        ...(typeof args['run-id'] === 'string' ? { runId: args['run-id'] } : {}),
+        ...(typeof args.serial === 'string' ? { serial: args.serial } : {}),
+        ...(typeof args['android-dev-client-url'] === 'string'
+            ? {
+                startupDeepLinks: [{
+                        label: 'android-dev-client-url',
+                        ...(typeof args['android-dev-client-ready-pattern'] === 'string'
+                            ? { readyLogPattern: args['android-dev-client-ready-pattern'] }
+                            : {}),
+                        readyLogQuietMs: parsePositiveInteger(args['android-dev-client-ready-quiet-ms'], 0),
+                        readyLogTimeoutMs: parsePositiveInteger(args['android-dev-client-ready-timeout-ms'], 60000),
+                        url: args['android-dev-client-url'],
+                        waitMs: parsePositiveInteger(args['android-dev-client-wait-ms'], 1000),
+                    }],
+            }
+            : {}),
+        waitMs: parsePositiveInteger(args['wait-ms'], 0),
+    });
+    process.stdout.write(`${result.runDir}\n`);
+    if (result.health.healthStatus !== 'passed') {
+        process.exitCode = 1;
+    }
+}
+if (require.main === module) {
+    main().catch((error) => {
+        console.error(error instanceof Error ? error.message : String(error));
+        process.exitCode = 1;
+    });
+}