rea-agents 6.3.0 → 6.5.0

package/dist/adb/AdbProvider.js

@@ -0,0 +1,1433 @@
+import { createHash } from "node:crypto";
+import { constants as fsConstants } from "node:fs";
+import { access, copyFile, lstat, mkdtemp, mkdir, rmdir, rm, stat, writeFile, } from "node:fs/promises";
+import { basename, dirname, extname, join, resolve } from "node:path";
+import { providerConfigurationRefusal } from "../domain/providerConfigurationRefusal.js";
+import { createAnalysisExecution, } from "../application/AnalysisProvider.js";
+import { adbResultSchemas } from "../domain/adb/adbDeviceAnalysis.js";
+import { AnalysisArtifactChangedError, AnalysisCancelledError, AnalysisInputError, AnalysisOutputError, AnalysisProtocolError, AnalysisResourceConstraintError, AnalysisTimeoutError, AnalysisUnsupportedTargetError, } from "../domain/analysisErrorCore.js";
+import { AnalysisError } from "../domain/analysisErrorBase.js";
+import { analysisErrorWithCleanupFailure } from "../domain/analysisErrorCleanup.js";
+import { err, ok } from "../domain/result.js";
+import { hashStableFile } from "../filesystem/StableFileHash.js";
+import { ProviderCleanupError } from "../domain/providerCleanupError.js";
+import { execFileBytes, execFileOutputFailure, } from "../process/ExecFileOutput.js";
+import { AdbConfigurationFailure, adbConfigurationAvailability, inspectAdbClient, resolveAdbBinary, } from "./AdbConfiguration.js";
+import { displayDevicePath, parseAdbDevicesOutput, parseGetpropOutput, parsePackageListOutput, parsePmPathOutput, } from "./AdbDeviceOutput.js";
+import { adbHostFileName } from "./AdbHostFileName.js";
+import { ADB_DIRECTORY_BATCH_SCRIPT, parseAdbDirectoryListing, } from "./AdbDirectoryListing.js";
+import { parseAmStartOutput, parseBugreportCopiedPath, parseDumpsysPackageOutput, parseFeatureListOutput, packageChangeFailureReason, parsePackageChangeOutput, parseProcessListOutput, parsePngDimensions, parseResolveActivityOutput, parseServiceListOutput, parseSettingsGetOutput, parseWindowFocusOutput, parseWmDensityOutput, parseWmSizeOutput, } from "./AdbShellOutput.js";
+/** Stable identity for the ADB device-acquisition provider. */
+export const ADB_PROVIDER_IDENTITY = {
+    id: "adb",
+    name: "Android Debug Bridge",
+    version: null,
+};
+const DEVICES_TIMEOUT_MS = 20_000;
+const DEVICES_MAX_OUTPUT_BYTES = 1024 * 1024;
+const SHELL_TIMEOUT_MS = 30_000;
+const GETPROP_MAX_OUTPUT_BYTES = 2 * 1024 * 1024;
+const PACKAGE_LIST_TIMEOUT_MS = 60_000;
+const PACKAGE_LIST_MAX_OUTPUT_BYTES = 8 * 1024 * 1024;
+const PM_PATH_TIMEOUT_MS = 30_000;
+const PM_PATH_MAX_OUTPUT_BYTES = 64 * 1024;
+const PULL_TIMEOUT_MS = 600_000;
+const PULL_MAX_OUTPUT_BYTES = 1024 * 1024;
+const LOGCAT_TIMEOUT_MS = 60_000;
+const LOGCAT_MAX_OUTPUT_BYTES = 4 * 1024 * 1024;
+const DUMPSYS_PACKAGE_TIMEOUT_MS = 60_000;
+const DUMPSYS_PACKAGE_MAX_OUTPUT_BYTES = 8 * 1024 * 1024;
+const DUMPSYS_WINDOW_MAX_OUTPUT_BYTES = 8 * 1024 * 1024;
+const LISTING_TIMEOUT_MS = 30_000;
+const LISTING_MAX_OUTPUT_BYTES = 4 * 1024 * 1024;
+const SETTINGS_TIMEOUT_MS = 20_000;
+const SETTINGS_MAX_OUTPUT_BYTES = 1024 * 1024;
+const SCREEN_TIMEOUT_MS = 60_000;
+const SCREEN_MAX_OUTPUT_BYTES = 32 * 1024 * 1024;
+const BUGREPORT_TIMEOUT_MS = 600_000;
+const BUGREPORT_MAX_OUTPUT_BYTES = 1024 * 1024;
+const STDERR_EXCERPT_BYTES = 512;
+const UNPARSED_LINES_REPORTED = 10;
+const hashAdbFile = async (path, operation, signal) => {
+    try {
+        return await hashStableFile(path, signal);
+    }
+    catch (cause) {
+        if (signal?.aborted === true)
+            throw new AnalysisCancelledError(operation, { cause });
+        throw cause;
+    }
+};
+/** adb joins shell operands into a remote POSIX command; quote at that boundary. */
+const quoteShellOperand = (value) => /^[A-Za-z0-9_./:=@+,-]+$/u.test(value)
+    ? value
+    : "'" + value.replaceAll("'", "'\\''") + "'";
+const adbArguments = (serial, arguments_) => {
+    const operands = arguments_[0] === "shell"
+        ? ["shell", ...arguments_.slice(1).map(quoteShellOperand)]
+        : [...arguments_];
+    return serial === undefined ? operands : ["-s", serial, ...operands];
+};
+/** Run one bounded adb invocation and keep its exact failure shape. */
+const runAdbCapture = async (operation, targetPath, binary, arguments_, limits, signal) => {
+    if (signal?.aborted === true)
+        return err(new AnalysisCancelledError(operation));
+    try {
+        return ok(await execFileBytes(binary, arguments_, {
+            timeout: limits.timeoutMs,
+            maxBuffer: limits.maxOutputBytes,
+            stopSignal: "SIGTERM",
+            ...(signal === undefined ? {} : { signal }),
+        }));
+    }
+    catch (cause) {
+        if (signal?.aborted || execFileOutputFailure(cause)?.code === "ABORT_ERR")
+            return err(new AnalysisCancelledError(operation, { cause }));
+        const failure = execFileOutputFailure(cause);
+        if (failure === undefined)
+            return err(new AnalysisProtocolError(`adb failed for ${operation}`, { cause }));
+        if (failure.outputTruncated)
+            return err(new AnalysisResourceConstraintError(operation, "memory", `adb output exceeded the ${String(limits.maxOutputBytes)}-byte capture budget`, { max_output_bytes: limits.maxOutputBytes }, { cause }));
+        const excerpt = failure.stderr.trim().slice(0, STDERR_EXCERPT_BYTES);
+        if (/unauthorized/iu.test(excerpt))
+            return err(new AnalysisUnsupportedTargetError(operation, targetPath, excerpt, {
+                cause,
+            }));
+        if (/device[^\n]*not found|device offline|still authorizing|more than one device/iu.test(excerpt))
+            return err(new AnalysisUnsupportedTargetError(operation, targetPath, excerpt, {
+                cause,
+            }));
+        if (/No such file or directory|Permission denied|read: Permission denied/iu.test(excerpt))
+            return err(new AnalysisUnsupportedTargetError(operation, targetPath, excerpt, {
+                cause,
+            }));
+        if (failure.killed)
+            return err(new AnalysisTimeoutError(operation, limits.timeoutMs, { cause }));
+        return err(new AnalysisProtocolError(excerpt === ""
+            ? `adb exited with code ${String(failure.code)} for ${operation}`
+            : excerpt, { cause }));
+    }
+};
+/** Decode textual adb protocols after the shared byte capture and error boundary. */
+const runAdb = async (...arguments_) => {
+    const captured = await runAdbCapture(...arguments_);
+    if (!captured.ok)
+        return captured;
+    return ok({
+        stdout: captured.value.stdout.toString("utf8"),
+        stderr: captured.value.stderr.toString("utf8"),
+        // Byte count of the captured output before UTF-8 decoding, so malformed
+        // sequences replaced by U+FFFD still report their true captured size.
+        stdoutBytes: captured.value.stdout.byteLength,
+    });
+};
+/**
+ * adb exits nonzero when the device refuses a package change, printing the
+ * `Failure [...]` verdict to stderr (install) or stdout (uninstall). Read the
+ * refusal from that failed run so it is not reported as unreadable output.
+ */
+const packageChangeRefusal = (operation, serial, error) => {
+    if (!(error instanceof AnalysisProtocolError))
+        return undefined;
+    const failure = execFileOutputFailure(error.cause);
+    if (failure === undefined)
+        return undefined;
+    const reason = packageChangeFailureReason(`${failure.stdout}\n${failure.stderr}`);
+    return reason === null
+        ? undefined
+        : err(new AnalysisUnsupportedTargetError(operation, serial, reason, {
+            cause: error,
+        }));
+};
+const clientIdentityResult = (selection, identity) => ({
+    binary_path: selection.binary,
+    path_source: selection.pathSource,
+    version: identity.version,
+    installed_path: identity.installedPath,
+});
+const reported = (unparsedLines, coverage) => ({
+    unparsed_lines: unparsedLines.slice(0, UNPARSED_LINES_REPORTED),
+    coverage: coverage === "partial" || unparsedLines.length > 0 ? "partial" : "complete",
+});
+const unparsedOverflowLimitation = (unparsedLines) => unparsedLines.length > UNPARSED_LINES_REPORTED
+    ? [
+        `unparsed_lines reports the first ${String(UNPARSED_LINES_REPORTED)} of ${String(unparsedLines.length)} unrecognized lines`,
+    ]
+    : [];
+/** Materialize the caller's output directory, refusing existing files inside. */
+const prepareOutputDirectory = async (operation, directory) => {
+    const root = resolve(directory);
+    try {
+        await mkdir(root, { recursive: true });
+        await access(root, fsConstants.W_OK);
+    }
+    catch (cause) {
+        return err(new AnalysisOutputError(operation, `The output directory is not writable or could not be created: ${root}`, { cause }));
+    }
+    return ok(root);
+};
+const refuseExistingTarget = async (operation, path) => {
+    if (await lstat(path).then(() => true, () => false))
+        return new AnalysisOutputError(operation, `The output file already exists: ${path}`);
+    return undefined;
+};
+/** Publish an ADB-produced archive without replacing an existing caller file. */
+const publishBugreport = async (source, directory) => {
+    const fileName = basename(source);
+    const extension = extname(fileName);
+    const stem = extension === "" ? fileName : fileName.slice(0, -extension.length);
+    for (let suffix = 0;; suffix += 1) {
+        const destination = join(directory, suffix === 0 ? fileName : `${stem} (${String(suffix)})${extension}`);
+        try {
+            await copyFile(source, destination, fsConstants.COPYFILE_EXCL);
+            return destination;
+        }
+        catch (cause) {
+            if (cause instanceof Error && "code" in cause && cause.code === "EEXIST")
+                continue;
+            throw cause;
+        }
+    }
+};
+const removeOwnedOutputDirectory = async (path, identity) => {
+    if (identity === undefined)
+        throw new Error(`Cannot verify the created output directory identity; refusing to remove ${path}`);
+    let current;
+    try {
+        current = await lstat(path);
+    }
+    catch (cause) {
+        if (cause instanceof Error && Reflect.get(cause, "code") === "ENOENT")
+            return;
+        throw cause;
+    }
+    if (!current.isDirectory() ||
+        current.isSymbolicLink() ||
+        current.dev !== identity.dev ||
+        current.ino !== identity.ino ||
+        current.mode !== identity.mode)
+        throw new Error(`The created output directory was replaced or changed; refusing to remove ${path}`);
+    await rm(path, { recursive: true, force: true });
+};
+const reservePackageDestinations = async (operation, packageName, packageDirectory, entries, capturedOutput) => {
+    const reservations = [];
+    for (const entry of entries) {
+        const path = join(packageDirectory, entry.file_name);
+        try {
+            await mkdir(path);
+            const created = await lstat(path);
+            if (!created.isDirectory() || created.isSymbolicLink())
+                throw new Error(`Could not reserve local filename ${entry.file_name}`);
+            reservations.push({
+                path,
+                file_name: entry.file_name,
+                device_path: entry.device_path,
+                identity: {
+                    dev: created.dev,
+                    ino: created.ino,
+                    mode: created.mode,
+                },
+            });
+        }
+        catch (cause) {
+            const errorCode = cause instanceof Error &&
+                "code" in cause &&
+                typeof cause.code === "string"
+                ? cause.code
+                : null;
+            return new AnalysisOutputError(operation, "local_destination_unavailable", {
+                cause,
+                capturedOutput,
+                userMessage: `pm path for ${packageName} reported ${displayDevicePath(entry.device_path)}, whose file name ${displayDevicePath(entry.file_name)} cannot be written to a unique local destination (${errorCode ?? "unknown error"}). No APK was pulled.`,
+                remediationAction: "Review details.diagnostics and details.captured_output for the refused destination. Correct the output filesystem conflict before retrying; REA does not rename APKs.",
+                diagnostics: {
+                    package_name: packageName,
+                    device_path: entry.device_path,
+                    file_name: entry.file_name,
+                    error_code: errorCode,
+                },
+            });
+        }
+    }
+    for (const reservation of reservations) {
+        try {
+            const current = await lstat(reservation.path);
+            if (!current.isDirectory() ||
+                current.isSymbolicLink() ||
+                current.dev !== reservation.identity.dev ||
+                current.ino !== reservation.identity.ino ||
+                current.mode !== reservation.identity.mode)
+                throw new Error(`The local filename reservation changed before release: ${reservation.path}`);
+            await rmdir(reservation.path);
+        }
+        catch (cause) {
+            const errorCode = cause instanceof Error &&
+                "code" in cause &&
+                typeof cause.code === "string"
+                ? cause.code
+                : null;
+            return new AnalysisOutputError(operation, "local_destination_unavailable", {
+                cause,
+                capturedOutput,
+                userMessage: `Could not release the local filename reservation for ${displayDevicePath(reservation.device_path)} (${errorCode ?? "unknown error"}); no APK was pulled.`,
+                remediationAction: "Review details.diagnostics and details.captured_output for the refused destination. Correct the output filesystem conflict before retrying; REA does not rename APKs.",
+                diagnostics: {
+                    package_name: packageName,
+                    device_path: reservation.device_path,
+                    file_name: reservation.file_name,
+                    error_code: errorCode,
+                },
+            });
+        }
+    }
+    return undefined;
+};
+/**
+ * ADB device inspection and acquisition over a caller-selected adb binary.
+ *
+ * Every operation composes fixed adb argument vectors: caller values occupy
+ * positional arguments, escaped when adb forwards them to the device shell. The provider never
+ * starts an emulator, installs platform tools, or drives the device UI; the
+ * only device mutation is the caller-requested file push, which requires an
+ * explicit overwrite choice and verifies its transfer digest.
+ */
+export class AdbProvider {
+    environment;
+    #pendingOutputDirectoryCleanup = new Set();
+    #activeOperations = new Set();
+    #closing = false;
+    #closePromise;
+    #outputCleanupPromise;
+    constructor(options = {}) {
+        this.environment = options.environment ?? process.env;
+    }
+    selection() {
+        return resolveAdbBinary(this.environment);
+    }
+    /** Probe the selected adb binary; never contacts devices or the server. */
+    async inspectAvailability(signal) {
+        try {
+            const selection = this.selection();
+            await inspectAdbClient(selection, signal);
+            return {
+                status: "available",
+                code: null,
+                reason: null,
+                diagnostics: {
+                    selected_binary: selection.binary,
+                    path_source: selection.pathSource,
+                },
+            };
+        }
+        catch (cause) {
+            if (cause instanceof AdbConfigurationFailure)
+                return adbConfigurationAvailability(cause);
+            throw cause;
+        }
+    }
+    /** Retry removal of owned output directories retained after failed cleanup. */
+    close() {
+        this.#closing = true;
+        if (this.#closePromise !== undefined)
+            return this.#closePromise;
+        const closing = (async () => {
+            await Promise.all(this.#activeOperations);
+            await this.#retryOutputDirectoryCleanup();
+        })().finally(() => {
+            if (this.#closePromise === closing)
+                this.#closePromise = undefined;
+        });
+        this.#closePromise = closing;
+        return this.#closePromise;
+    }
+    #retryOutputDirectoryCleanup() {
+        if (this.#outputCleanupPromise !== undefined)
+            return this.#outputCleanupPromise;
+        const cleanup = this.#performOutputDirectoryCleanup().finally(() => {
+            if (this.#outputCleanupPromise === cleanup)
+                this.#outputCleanupPromise = undefined;
+        });
+        this.#outputCleanupPromise = cleanup;
+        return cleanup;
+    }
+    async #performOutputDirectoryCleanup() {
+        const failures = [];
+        for (const owner of this.#pendingOutputDirectoryCleanup) {
+            try {
+                await owner.remove();
+                this.#pendingOutputDirectoryCleanup.delete(owner);
+            }
+            catch (cause) {
+                const cleanup = new ProviderCleanupError(ADB_PROVIDER_IDENTITY.id, [owner.path], {
+                    reason: cause instanceof Error ? cause.message : String(cause),
+                }, { operation: owner.operation, cause });
+                failures.push(analysisErrorWithCleanupFailure(owner.primary, cleanup, owner.operation));
+            }
+        }
+        if (failures.length === 1)
+            throw failures[0];
+        if (failures.length > 1)
+            throw new ProviderCleanupError(ADB_PROVIDER_IDENTITY.id, [...this.#pendingOutputDirectoryCleanup].map(({ path }) => path), {
+                reason: "Failed ADB output directories remain after cleanup retry",
+                operations: [...this.#pendingOutputDirectoryCleanup].map(({ operation }) => operation),
+                failures: failures.map(({ message, cleanupResources }) => ({
+                    message,
+                    resources: [...cleanupResources],
+                })),
+            }, {
+                operation: "close_binary",
+                cause: new AggregateError(failures, "Multiple ADB output directory cleanups failed"),
+            });
+    }
+    async execute(request, options) {
+        if (this.#closing)
+            return err(new AnalysisCancelledError(request.operation));
+        let release;
+        const active = new Promise((resolve) => {
+            release = resolve;
+        });
+        this.#activeOperations.add(active);
+        try {
+            if (this.#pendingOutputDirectoryCleanup.size > 0) {
+                try {
+                    await this.#retryOutputDirectoryCleanup();
+                }
+                catch (cause) {
+                    return err(cause instanceof AnalysisError
+                        ? cause
+                        : new ProviderCleanupError(ADB_PROVIDER_IDENTITY.id, [...this.#pendingOutputDirectoryCleanup].map(({ path }) => path), {
+                            reason: cause instanceof Error ? cause.message : String(cause),
+                        }, { operation: request.operation, cause }));
+                }
+            }
+            return await this.#executeOperation(request, options);
+        }
+        finally {
+            this.#activeOperations.delete(active);
+            release();
+        }
+    }
+    async #executeOperation(request, options) {
+        const signal = options?.signal;
+        if (signal?.aborted === true)
+            return err(new AnalysisCancelledError(request.operation));
+        let selection;
+        let identity;
+        try {
+            selection = this.selection();
+            identity = await inspectAdbClient(selection, signal);
+        }
+        catch (cause) {
+            if (cause instanceof AnalysisCancelledError)
+                return err(cause);
+            if (cause instanceof AdbConfigurationFailure)
+                return err(providerConfigurationRefusal(ADB_PROVIDER_IDENTITY.id, request.operation, cause));
+            return err(new AnalysisProtocolError(`adb version probe failed for ${request.operation}`, { cause }));
+        }
+        const client = clientIdentityResult(selection, identity);
+        const provider = {
+            ...ADB_PROVIDER_IDENTITY,
+            version: identity.version,
+        };
+        const { operation } = request;
+        const shell = (arguments_, limits) => runAdb(operation, "serial" in request.input ? request.input.serial : operation, selection.binary, adbArguments("serial" in request.input ? request.input.serial : undefined, ["shell", ...arguments_]), limits, signal);
+        switch (operation) {
+            case "inspect_adb_client":
+                return ok(createAnalysisExecution({ client, contacted_adb_server: false }, provider));
+            case "list_adb_devices": {
+                const ran = await runAdb(operation, "adb-devices", selection.binary, ["devices", "-l"], {
+                    timeoutMs: DEVICES_TIMEOUT_MS,
+                    maxOutputBytes: DEVICES_MAX_OUTPUT_BYTES,
+                }, signal);
+                if (!ran.ok)
+                    return ran;
+                const { devices, unparsedLines, daemonStarted } = parseAdbDevicesOutput(ran.value.stdout, ran.value.stderr);
+                if (unparsedLines.length > 0)
+                    return err(new AnalysisProtocolError(`adb devices reported an unrecognized line: ${unparsedLines[0]}`));
+                return ok(createAnalysisExecution({ client, devices, may_have_started_adb_server: daemonStarted }, provider, {
+                    limitations: [
+                        "Device kind is inferred from the emulator serial prefix and USB transport metadata, not from device attestation",
+                        "Kind stays unknown for TCP transports unless the serial is an emulator port",
+                    ],
+                }));
+            }
+            case "inspect_adb_device": {
+                const ran = await runAdb(operation, request.input.serial, selection.binary, adbArguments(request.input.serial, ["shell", "getprop"]), {
+                    timeoutMs: SHELL_TIMEOUT_MS,
+                    maxOutputBytes: GETPROP_MAX_OUTPUT_BYTES,
+                }, signal);
+                if (!ran.ok)
+                    return ran;
+                const { properties, emulatorObserved } = parseGetpropOutput(ran.value.stdout);
+                return ok(createAnalysisExecution({
+                    client,
+                    serial: request.input.serial,
+                    properties,
+                    property_count: properties.length,
+                    emulator_observed: emulatorObserved,
+                }, provider, {
+                    limitations: [
+                        "Properties are a fixed whitelist of build identity facts, not the full getprop dump",
+                        "emulator_observed is null when the build does not report ro.kernel.qemu",
+                    ],
+                }));
+            }
+            case "list_adb_packages": {
+                const scopeFlag = request.input.scope === "third_party"
+                    ? "-3"
+                    : request.input.scope === "system"
+                        ? "-s"
+                        : null;
+                const ran = await shell([
+                    "pm",
+                    "list",
+                    "packages",
+                    "-f",
+                    ...(scopeFlag === null ? [] : [scopeFlag]),
+                ], {
+                    timeoutMs: PACKAGE_LIST_TIMEOUT_MS,
+                    maxOutputBytes: PACKAGE_LIST_MAX_OUTPUT_BYTES,
+                });
+                if (!ran.ok)
+                    return ran;
+                const { packages, unparsedLines } = parsePackageListOutput(ran.value.stdout);
+                return ok(createAnalysisExecution({
+                    client,
+                    serial: request.input.serial,
+                    scope: request.input.scope,
+                    packages,
+                    ...reported(unparsedLines, "complete"),
+                }, provider, {
+                    limitations: [
+                        "base_apk_device_path is a device filesystem path, not a host-local path",
+                        ...unparsedOverflowLimitation(unparsedLines),
+                    ],
+                }));
+            }
+            case "pull_adb_package":
+                return this.pullPackage(operation, selection, client, provider, request.input, signal);
+            case "read_adb_logcat": {
+                const ran = await shell([
+                    "logcat",
+                    "-d",
+                    "-b",
+                    request.input.buffer,
+                    "-t",
+                    String(request.input.count),
+                    ...(request.input.pid === undefined
+                        ? []
+                        : ["--pid", String(request.input.pid)]),
+                ], {
+                    timeoutMs: LOGCAT_TIMEOUT_MS,
+                    maxOutputBytes: LOGCAT_MAX_OUTPUT_BYTES,
+                });
+                if (!ran.ok)
+                    return ran;
+                const lines = ran.value.stdout.split(/\r?\n/u);
+                if (lines.length > 0 && lines[lines.length - 1] === "")
+                    lines.pop();
+                const bounded = lines.slice(-request.input.count);
+                return ok(createAnalysisExecution({
+                    client,
+                    serial: request.input.serial,
+                    count: request.input.count,
+                    buffer: request.input.buffer,
+                    pid: request.input.pid ?? null,
+                    lines: bounded,
+                    total_bytes: ran.value.stdoutBytes,
+                    coverage: bounded.length !== lines.length ||
+                        bounded.length === request.input.count
+                        ? "partial"
+                        : "complete",
+                }, provider, {
+                    limitations: [
+                        "Reads a bounded dump (logcat -d); the newest lines are kept when the count cap trims",
+                        "coverage is partial when the requested count or capture budget truncated the dump",
+                    ],
+                }));
+            }
+            case "inspect_adb_package": {
+                const ran = await shell(["dumpsys", "package", request.input.package], {
+                    timeoutMs: DUMPSYS_PACKAGE_TIMEOUT_MS,
+                    maxOutputBytes: DUMPSYS_PACKAGE_MAX_OUTPUT_BYTES,
+                });
+                if (!ran.ok)
+                    return ran;
+                const stdout = ran.value.stdout;
+                if (/Unable to find package:/u.test(stdout) || stdout.trim() === "")
+                    return err(new AnalysisUnsupportedTargetError(operation, request.input.serial, `Package Manager did not report details for ${request.input.package}; it may not be installed for user 0`));
+                const details = parseDumpsysPackageOutput(stdout);
+                return ok(createAnalysisExecution({
+                    client,
+                    serial: request.input.serial,
+                    package_name: request.input.package,
+                    version_name: details.versionName,
+                    version_code: details.versionCode,
+                    first_install_time: details.firstInstallTime,
+                    last_update_time: details.lastUpdateTime,
+                    installer_package_name: details.installerPackageName,
+                    user_id: details.userId,
+                    pkg_flags: details.pkgFlags,
+                    requested_permissions_count: details.requestedPermissions,
+                    coverage: details.versionCode === null && details.versionName === null
+                        ? "partial"
+                        : "complete",
+                }, provider, {
+                    limitations: [
+                        "Fields are a fixed projection of dumpsys package output; version-dependent sections are ignored rather than guessed",
+                        "requested_permissions_count counts the listed requested permissions section only",
+                    ],
+                }));
+            }
+            case "pull_adb_file":
+                return this.pullFile(operation, selection, client, provider, request.input, signal);
+            case "push_adb_file":
+                return this.pushFile(operation, selection, client, provider, request.input, signal);
+            case "capture_adb_screen":
+                return this.captureScreen(operation, selection, client, provider, request.input, signal);
+            case "collect_adb_bugreport":
+                return this.collectBugreport(operation, selection, client, provider, request.input, signal);
+            case "list_adb_processes": {
+                const ran = await shell(["ps", "-A"], {
+                    timeoutMs: LISTING_TIMEOUT_MS,
+                    maxOutputBytes: LISTING_MAX_OUTPUT_BYTES,
+                });
+                if (!ran.ok)
+                    return ran;
+                const { columns, processes, unparsedLines } = parseProcessListOutput(ran.value.stdout);
+                return ok(createAnalysisExecution({
+                    client,
+                    serial: request.input.serial,
+                    columns,
+                    processes,
+                    ...reported(unparsedLines, "complete"),
+                }, provider, { limitations: unparsedOverflowLimitation(unparsedLines) }));
+            }
+            case "list_adb_directory": {
+                const ran = await runAdbCapture(operation, request.input.serial, selection.binary, adbArguments(request.input.serial, [
+                    "shell",
+                    "sh",
+                    "-c",
+                    'cd "$1" || exit\nexec find . -mindepth 1 -maxdepth 1 -exec sh -c "$2" rea-list-directory {} +',
+                    "rea-list-directory",
+                    request.input.device_path,
+                    ADB_DIRECTORY_BATCH_SCRIPT,
+                ]), {
+                    timeoutMs: LISTING_TIMEOUT_MS,
+                    maxOutputBytes: LISTING_MAX_OUTPUT_BYTES,
+                }, signal);
+                if (!ran.ok)
+                    return ran;
+                const { entries, unparsedLines } = parseAdbDirectoryListing(ran.value.stdout);
+                return ok(createAnalysisExecution({
+                    client,
+                    serial: request.input.serial,
+                    device_path: request.input.device_path,
+                    entries,
+                    ...reported(unparsedLines, "complete"),
+                }, provider, {
+                    limitations: [
+                        "Entry kinds derive from stat permission mode; directory contents and link targets may change during capture",
+                        ...unparsedOverflowLimitation(unparsedLines),
+                    ],
+                }));
+            }
+            case "list_adb_features": {
+                const ran = await shell(["pm", "list", "features"], {
+                    timeoutMs: LISTING_TIMEOUT_MS,
+                    maxOutputBytes: LISTING_MAX_OUTPUT_BYTES,
+                });
+                if (!ran.ok)
+                    return ran;
+                const { features, unparsedLines } = parseFeatureListOutput(ran.value.stdout);
+                return ok(createAnalysisExecution({
+                    client,
+                    serial: request.input.serial,
+                    features,
+                    ...reported(unparsedLines, "complete"),
+                }, provider, { limitations: unparsedOverflowLimitation(unparsedLines) }));
+            }
+            case "list_adb_services": {
+                const ran = await shell(["service", "list"], {
+                    timeoutMs: LISTING_TIMEOUT_MS,
+                    maxOutputBytes: LISTING_MAX_OUTPUT_BYTES,
+                });
+                if (!ran.ok)
+                    return ran;
+                const { services, unparsedLines } = parseServiceListOutput(ran.value.stdout);
+                return ok(createAnalysisExecution({
+                    client,
+                    serial: request.input.serial,
+                    services,
+                    ...reported(unparsedLines, "complete"),
+                }, provider, { limitations: unparsedOverflowLimitation(unparsedLines) }));
+            }
+            case "inspect_adb_display": {
+                const size = await shell(["wm", "size"], {
+                    timeoutMs: SETTINGS_TIMEOUT_MS,
+                    maxOutputBytes: SETTINGS_MAX_OUTPUT_BYTES,
+                });
+                if (!size.ok)
+                    return size;
+                const density = await shell(["wm", "density"], {
+                    timeoutMs: SETTINGS_TIMEOUT_MS,
+                    maxOutputBytes: SETTINGS_MAX_OUTPUT_BYTES,
+                });
+                if (!density.ok)
+                    return density;
+                const parsedSize = parseWmSizeOutput(size.value.stdout);
+                if (parsedSize.physical === null)
+                    return err(new AnalysisProtocolError("wm size did not report a physical size; the build may use an unsupported format"));
+                const parsedDensity = parseWmDensityOutput(density.value.stdout);
+                return ok(createAnalysisExecution({
+                    client,
+                    serial: request.input.serial,
+                    physical_size: parsedSize.physical,
+                    override_size: parsedSize.override,
+                    physical_density: parsedDensity.physical,
+                    override_density: parsedDensity.override,
+                }, provider, {
+                    limitations: [
+                        "Override values are present only when a build has overridden the physical values",
+                    ],
+                }));
+            }
+            case "inspect_adb_window": {
+                let section = "windows";
+                const ran = await shell(["dumpsys", "window", section], {
+                    timeoutMs: SHELL_TIMEOUT_MS,
+                    maxOutputBytes: DUMPSYS_WINDOW_MAX_OUTPUT_BYTES,
+                });
+                if (!ran.ok)
+                    return ran;
+                let { focusedWindow, focusedApp } = parseWindowFocusOutput(ran.value.stdout);
+                if (focusedWindow === null && focusedApp === null) {
+                    section = "displays";
+                    const fallback = await shell(["dumpsys", "window", section], {
+                        timeoutMs: SHELL_TIMEOUT_MS,
+                        maxOutputBytes: DUMPSYS_WINDOW_MAX_OUTPUT_BYTES,
+                    });
+                    if (!fallback.ok)
+                        return fallback;
+                    ({ focusedWindow, focusedApp } = parseWindowFocusOutput(fallback.value.stdout));
+                }
+                const declared = focusedWindow !== null || focusedApp !== null;
+                return ok(createAnalysisExecution({
+                    client,
+                    serial: request.input.serial,
+                    focused_window: focusedWindow,
+                    focused_app: focusedApp,
+                    observed_lines: [
+                        ...(focusedWindow === null ? [] : [focusedWindow]),
+                        ...(focusedApp === null ? [] : [focusedApp]),
+                    ],
+                }, provider, {
+                    limitations: [
+                        "Focus values are the window manager's declarations at read time; no interaction occurred",
+                        declared
+                            ? `Focus declarations were read from \`dumpsys window ${section}\``
+                            : "Neither `dumpsys window windows` nor `dumpsys window displays` declared mCurrentFocus or mFocusedApp; focus is unknown, not absent",
+                    ],
+                }));
+            }
+            case "read_adb_setting": {
+                const ran = await shell(["settings", "get", request.input.namespace, request.input.key], {
+                    timeoutMs: SETTINGS_TIMEOUT_MS,
+                    maxOutputBytes: SETTINGS_MAX_OUTPUT_BYTES,
+                });
+                if (!ran.ok)
+                    return ran;
+                const { value, deviceReportedNull } = parseSettingsGetOutput(ran.value.stdout);
+                return ok(createAnalysisExecution({
+                    client,
+                    serial: request.input.serial,
+                    namespace: request.input.namespace,
+                    key: request.input.key,
+                    value,
+                    device_reported_null: deviceReportedNull,
+                }, provider, {
+                    limitations: [
+                        "Android prints the literal string null for absent keys; that is reported as a device-side null observation",
+                    ],
+                }));
+            }
+            case "resolve_adb_packages": {
+                const ran = await shell(["pm", "list", "packages", "-f"], {
+                    timeoutMs: PACKAGE_LIST_TIMEOUT_MS,
+                    maxOutputBytes: PACKAGE_LIST_MAX_OUTPUT_BYTES,
+                });
+                if (!ran.ok)
+                    return ran;
+                const { packages, unparsedLines } = parsePackageListOutput(ran.value.stdout);
+                const needle = request.input.query.toLowerCase();
+                const matches = packages.filter((entry) => entry.package_name.toLowerCase().includes(needle));
+                return ok(createAnalysisExecution({
+                    client,
+                    serial: request.input.serial,
+                    query: request.input.query,
+                    matches,
+                    exact_match: matches.length === 1 &&
+                        matches[0].package_name.toLowerCase() === needle,
+                    coverage: unparsedLines.length > 0 ? "partial" : "complete",
+                }, provider, {
+                    limitations: [
+                        "Matching is a case-insensitive substring over package names; application display labels are not part of pm output",
+                        ...unparsedOverflowLimitation(unparsedLines),
+                    ],
+                }));
+            }
+            case "install_adb_package":
+                return this.installPackage(operation, selection, client, provider, request.input, signal);
+            case "uninstall_adb_package":
+                return this.uninstallPackage(operation, selection, client, provider, request.input, signal);
+            case "start_adb_app":
+                return this.startApp(operation, selection, client, provider, request.input, signal);
+            case "start_adb_activity":
+                return this.startActivity(operation, selection, client, provider, request.input, signal);
+            case "stop_adb_app":
+                return this.stopApp(operation, selection, client, provider, request.input, signal);
+        }
+    }
+    async pullPackage(operation, selection, client, provider, input, signal) {
+        const { serial, package: packageName } = input;
+        const paths = await runAdb(operation, serial, selection.binary, adbArguments(serial, ["shell", "pm", "path", packageName]), {
+            timeoutMs: PM_PATH_TIMEOUT_MS,
+            maxOutputBytes: PM_PATH_MAX_OUTPUT_BYTES,
+        }, signal);
+        if (!paths.ok)
+            return paths;
+        const parsed = parsePmPathOutput(paths.value.stdout);
+        const capturedOutput = {
+            stdout: paths.value.stdout,
+            stderr: paths.value.stderr,
+            truncated: false,
+        };
+        if (parsed.rejectedPaths.length > 0) {
+            const first = parsed.rejectedPaths[0];
+            const otherCount = parsed.rejectedPaths.length - 1;
+            return err(new AnalysisOutputError(operation, "unsafe_device_path", {
+                capturedOutput,
+                userMessage: `pm path for ${packageName} reported an APK path that cannot be written as a file on this host: ${displayDevicePath(first.device_path)} (${first.reason})${otherCount > 0 ? ` and ${String(otherCount)} other path(s)` : ""}. No APK was pulled.`,
+                remediationAction: "Review details.diagnostics for the refused device paths and details.captured_output for the retained pm path output. REA does not rename device-reported APK paths; correct the device path policy before retrying.",
+                diagnostics: {
+                    package_name: packageName,
+                    rejected_paths: parsed.rejectedPaths.map(({ device_path, reason }) => ({
+                        device_path,
+                        reason,
+                    })),
+                },
+            }));
+        }
+        if (parsed.paths.length === 0 && parsed.unparsedLines.length === 0)
+            return err(new AnalysisUnsupportedTargetError(operation, serial, `Package Manager reported no APK paths for ${packageName}; it may not be installed for user 0`));
+        if (parsed.unparsedLines.length > 0)
+            return err(new AnalysisProtocolError(`pm path reported an unrecognized line: ${parsed.unparsedLines[0]}`, { capturedOutput }));
+        const destinationNames = new Set();
+        for (const entry of parsed.paths) {
+            if (destinationNames.has(entry.file_name))
+                return err(new AnalysisOutputError(operation, "duplicate_local_destination", {
+                    capturedOutput,
+                    userMessage: `pm path for ${packageName} reported multiple APK paths with the same local file name ${displayDevicePath(entry.file_name)}; no APK was pulled.`,
+                    remediationAction: "Review details.diagnostics and details.captured_output for the conflicting device paths. REA does not rename device-reported paths; correct Package Manager's path response before retrying.",
+                    diagnostics: {
+                        package_name: packageName,
+                        file_name: entry.file_name,
+                        device_paths: parsed.paths
+                            .filter((candidate) => candidate.file_name === entry.file_name)
+                            .map((candidate) => candidate.device_path),
+                    },
+                }));
+            destinationNames.add(entry.file_name);
+        }
+        const directory = await prepareOutputDirectory(operation, input.output_directory);
+        if (!directory.ok)
+            return directory;
+        const packageDirectory = join(directory.value, packageName);
+        let packageDirectoryCreated = false;
+        let packageDirectoryIdentity;
+        try {
+            if (await lstat(packageDirectory).then(() => true, () => false))
+                throw new Error(`The package output directory already exists: ${packageDirectory}`);
+            await mkdir(packageDirectory);
+            packageDirectoryCreated = true;
+            const created = await lstat(packageDirectory);
+            if (!created.isDirectory() || created.isSymbolicLink())
+                throw new Error(`The created package output is not a regular directory: ${packageDirectory}`);
+            packageDirectoryIdentity = {
+                dev: created.dev,
+                ino: created.ino,
+                mode: created.mode,
+            };
+        }
+        catch (cause) {
+            const primary = new AnalysisOutputError(operation, cause instanceof Error ? cause.message : String(cause), { cause });
+            if (!packageDirectoryCreated)
+                return err(primary);
+            const owner = {
+                operation,
+                path: packageDirectory,
+                identity: packageDirectoryIdentity,
+                primary,
+                remove: () => removeOwnedOutputDirectory(packageDirectory, packageDirectoryIdentity),
+            };
+            this.#pendingOutputDirectoryCleanup.add(owner);
+            const cleanup = new ProviderCleanupError(ADB_PROVIDER_IDENTITY.id, [packageDirectory], {
+                reason: "Could not establish an owned package directory identity",
+            }, { operation, cause });
+            return err(analysisErrorWithCleanupFailure(primary, cleanup, operation));
+        }
+        const failOwnedPackage = async (primary) => {
+            const owner = {
+                operation,
+                path: packageDirectory,
+                identity: packageDirectoryIdentity,
+                primary,
+                remove: () => removeOwnedOutputDirectory(packageDirectory, packageDirectoryIdentity),
+            };
+            try {
+                await owner.remove();
+            }
+            catch (cause) {
+                this.#pendingOutputDirectoryCleanup.add(owner);
+                const cleanup = new ProviderCleanupError(ADB_PROVIDER_IDENTITY.id, [packageDirectory], { reason: cause instanceof Error ? cause.message : String(cause) }, { operation, cause });
+                return err(analysisErrorWithCleanupFailure(primary, cleanup, operation));
+            }
+            return err(primary);
+        };
+        const destinationError = await reservePackageDestinations(operation, packageName, packageDirectory, parsed.paths, capturedOutput);
+        if (destinationError !== undefined)
+            return failOwnedPackage(destinationError);
+        const artifacts = [];
+        const failures = [];
+        const cancelledPackagePull = (error, localPath, devicePath, stage) => {
+            error.retainPartialObservation({
+                provider_id: "adb",
+                operation,
+                result: {
+                    client,
+                    serial,
+                    package_name: packageName,
+                    output_directory: directory.value,
+                    artifacts,
+                    failures: [
+                        ...failures,
+                        {
+                            device_path: devicePath,
+                            stage,
+                            message: stage === "pull"
+                                ? `Pull cancelled; any incomplete file is retained at ${localPath}. Remaining APKs were not attempted.`
+                                : `Digesting the pulled file was cancelled; the file is retained at ${localPath}. Remaining APKs were not attempted.`,
+                        },
+                    ],
+                    coverage: "partial",
+                },
+            });
+            return err(error);
+        };
+        for (const entry of parsed.paths) {
+            const localPath = join(packageDirectory, entry.file_name);
+            const pulled = await runAdb(operation, serial, selection.binary, adbArguments(serial, ["pull", entry.device_path, localPath]), { timeoutMs: PULL_TIMEOUT_MS, maxOutputBytes: PULL_MAX_OUTPUT_BYTES }, signal);
+            if (!pulled.ok) {
+                if (pulled.error instanceof AnalysisCancelledError)
+                    return cancelledPackagePull(pulled.error, localPath, entry.device_path, "pull");
+                failures.push({
+                    device_path: entry.device_path,
+                    stage: "pull",
+                    message: pulled.error.message,
+                });
+                continue;
+            }
+            try {
+                const digest = await hashAdbFile(localPath, operation, signal);
+                artifacts.push({
+                    device_path: entry.device_path,
+                    file_name: entry.file_name,
+                    local_path: localPath,
+                    bytes: digest.bytes,
+                    sha256: digest.sha256,
+                    role: entry.role,
+                    role_basis: "file_name",
+                });
+            }
+            catch (cause) {
+                if (cause instanceof AnalysisCancelledError)
+                    return cancelledPackagePull(cause, localPath, entry.device_path, "digest");
+                failures.push({
+                    device_path: entry.device_path,
+                    stage: "digest",
+                    message: `The pulled file could not be read back after pulling: ${localPath}`,
+                });
+            }
+        }
+        if (artifacts.length === 0 && failures.length > 0) {
+            const primary = new AnalysisProtocolError(`Every APK pull failed for ${packageName} on ${serial}: ${failures[0].message}`);
+            return failOwnedPackage(primary);
+        }
+        return ok(createAnalysisExecution({
+            client,
+            serial,
+            package_name: packageName,
+            output_directory: directory.value,
+            artifacts,
+            failures,
+            coverage: failures.length === 0 ? "complete" : "partial",
+        }, provider, {
+            limitations: [
+                "APK role names derive from the pulled file names (base.apk, split_*.apk)",
+                "Pulled artifacts are host-local copies; the device retains the originals",
+            ],
+        }));
+    }
+    async pullFile(operation, selection, client, provider, input, signal) {
+        const derived = adbHostFileName(input.device_path);
+        if (!derived.ok)
+            return err(new AnalysisInputError(operation, undefined, [
+                {
+                    path: ["device_path"],
+                    reason: "invalid_value",
+                    message: `The device path ${JSON.stringify(input.device_path)} does not name a file that can be written on this host (${derived.reason}); REA never renames a device-reported file.`,
+                },
+            ]));
+        const directory = await prepareOutputDirectory(operation, input.output_directory);
+        if (!directory.ok)
+            return directory;
+        const localPath = join(directory.value, derived.fileName);
+        const existing = await refuseExistingTarget(operation, localPath);
+        if (existing !== undefined)
+            return err(existing);
+        const pulled = await runAdb(operation, input.serial, selection.binary, adbArguments(input.serial, ["pull", input.device_path, localPath]), { timeoutMs: PULL_TIMEOUT_MS, maxOutputBytes: PULL_MAX_OUTPUT_BYTES }, signal);
+        if (!pulled.ok)
+            return pulled;
+        try {
+            const digest = await hashAdbFile(localPath, operation, signal);
+            return ok(createAnalysisExecution({
+                client,
+                serial: input.serial,
+                device_path: input.device_path,
+                local_path: localPath,
+                bytes: digest.bytes,
+                sha256: digest.sha256,
+            }, provider, {
+                limitations: [
+                    "The pulled file is a host-local copy; the device retains the original",
+                ],
+            }));
+        }
+        catch (cause) {
+            if (cause instanceof AnalysisCancelledError) {
+                cause.retainPartialObservation({
+                    provider_id: "adb",
+                    operation,
+                    result: {
+                        client,
+                        serial: input.serial,
+                        local_path: localPath,
+                        device_path: input.device_path,
+                        digest_status: "unknown",
+                    },
+                });
+                return err(cause);
+            }
+            return err(new AnalysisOutputError(operation, `The pulled file could not be read back after pulling: ${localPath}`, { cause }));
+        }
+    }
+    async pushFile(operation, selection, client, provider, input, signal) {
+        const localPath = resolve(input.local_path);
+        const info = await stat(localPath).then((value) => value, () => null);
+        if (info === null || !info.isFile())
+            return err(new AnalysisInputError(operation, {
+                cause: new Error(`The local file does not exist: ${localPath}`),
+            }));
+        let digest;
+        try {
+            digest = await hashAdbFile(localPath, operation, signal);
+        }
+        catch (cause) {
+            if (cause instanceof AnalysisCancelledError)
+                return err(cause);
+            throw cause;
+        }
+        const existsProbe = await runAdb(operation, input.device_path, selection.binary, adbArguments(input.serial, ["shell", "test", "-e", input.device_path]), { timeoutMs: SETTINGS_TIMEOUT_MS, maxOutputBytes: 1024 }, signal);
+        // `test -e` exits nonzero with no adb diagnosis when the path is absent.
+        // Any other probe failure leaves existence unknown, so it is reported as
+        // is rather than read as an existing path or followed by a push.
+        if (!existsProbe.ok &&
+            !(existsProbe.error instanceof AnalysisProtocolError))
+            return existsProbe;
+        const deviceExists = existsProbe.ok;
+        if (deviceExists && !input.overwrite)
+            return err(new AnalysisOutputError(operation, `The device path already exists and overwrite was not requested: ${input.device_path}`));
+        const pushed = await runAdb(operation, input.device_path, selection.binary, adbArguments(input.serial, ["push", localPath, input.device_path]), { timeoutMs: PULL_TIMEOUT_MS, maxOutputBytes: PULL_MAX_OUTPUT_BYTES }, signal);
+        if (!pushed.ok)
+            return pushed;
+        const deviceDigest = await runAdb(operation, input.device_path, selection.binary, adbArguments(input.serial, ["shell", "sha256sum", input.device_path]), { timeoutMs: SHELL_TIMEOUT_MS, maxOutputBytes: 1024 }, signal);
+        if (deviceDigest.ok) {
+            const digestMatch = /^([a-f0-9]{64})\s/u.exec(deviceDigest.value.stdout);
+            if (digestMatch !== null && digestMatch[1] !== digest.sha256)
+                return err(new AnalysisArtifactChangedError(operation, input.device_path, `The device-reported digest does not match the pushed local file: ${localPath}`));
+            return ok(createAnalysisExecution({
+                client,
+                serial: input.serial,
+                local_path: localPath,
+                device_path: input.device_path,
+                bytes: digest.bytes,
+                sha256: digest.sha256,
+                device_sha256: digestMatch?.[1] ?? null,
+                overwritten: deviceExists,
+                device_digest_source: "device_sha256sum",
+            }, provider, {
+                limitations: ["Push writes the caller's file to the device"],
+            }));
+        }
+        return ok(createAnalysisExecution({
+            client,
+            serial: input.serial,
+            local_path: localPath,
+            device_path: input.device_path,
+            bytes: digest.bytes,
+            sha256: digest.sha256,
+            device_sha256: null,
+            overwritten: deviceExists,
+            device_digest_source: "unavailable",
+        }, provider, {
+            limitations: [
+                "The device did not answer sha256sum, so the transfer is not device-side verified",
+                "Push writes the caller's file to the device",
+            ],
+        }));
+    }
+    async installPackage(operation, selection, client, provider, input, signal) {
+        const apkPath = resolve(input.apk_path);
+        const info = await stat(apkPath).then((value) => value, () => null);
+        if (info === null || !info.isFile())
+            return err(new AnalysisInputError(operation, {
+                cause: new Error(`The local APK does not exist: ${apkPath}`),
+            }));
+        let digest;
+        try {
+            digest = await hashAdbFile(apkPath, operation, signal);
+        }
+        catch (cause) {
+            if (cause instanceof AnalysisCancelledError)
+                return err(cause);
+            throw cause;
+        }
+        const installed = await runAdb(operation, input.serial, selection.binary, adbArguments(input.serial, [
+            "install",
+            ...(input.replace ? ["-r"] : []),
+            apkPath,
+        ]), { timeoutMs: PULL_TIMEOUT_MS, maxOutputBytes: PULL_MAX_OUTPUT_BYTES }, signal);
+        if (!installed.ok)
+            return (packageChangeRefusal(operation, input.serial, installed.error) ??
+                installed);
+        const verdict = parsePackageChangeOutput(installed.value.stdout);
+        if (verdict.status === "failure")
+            return err(new AnalysisUnsupportedTargetError(operation, input.serial, verdict.reason ?? "the device refused the installation"));
+        return ok(createAnalysisExecution({
+            client,
+            serial: input.serial,
+            apk_path: apkPath,
+            bytes: digest.bytes,
+            sha256: digest.sha256,
+            replace_requested: input.replace,
+            replaced: null,
+        }, provider, {
+            limitations: [
+                "Install changes device state; the installed APK's digest is the host file's digest",
+                "Whether an existing package was replaced is unknown; replace_requested records only the adb install mode",
+            ],
+        }));
+    }
+    async uninstallPackage(operation, selection, client, provider, input, signal) {
+        const uninstalled = await runAdb(operation, input.serial, selection.binary, adbArguments(input.serial, ["uninstall", input.package]), {
+            timeoutMs: PACKAGE_LIST_TIMEOUT_MS,
+            maxOutputBytes: PULL_MAX_OUTPUT_BYTES,
+        }, signal);
+        if (!uninstalled.ok)
+            return (packageChangeRefusal(operation, input.serial, uninstalled.error) ??
+                uninstalled);
+        const verdict = parsePackageChangeOutput(uninstalled.value.stdout);
+        if (verdict.status === "failure")
+            return err(new AnalysisUnsupportedTargetError(operation, input.serial, verdict.reason ?? "the device refused the removal"));
+        return ok(createAnalysisExecution({
+            client,
+            serial: input.serial,
+            package_name: input.package,
+        }, provider, {
+            limitations: [
+                "Uninstall removes the package and its data for user 0; keeping data (-k) is not exposed",
+            ],
+        }));
+    }
+    async startApp(operation, selection, client, provider, input, signal) {
+        const resolved = await runAdb(operation, input.serial, selection.binary, adbArguments(input.serial, [
+            "shell",
+            "cmd",
+            "package",
+            "resolve-activity",
+            "--brief",
+            "-c",
+            "android.intent.category.LAUNCHER",
+            input.package,
+        ]), { timeoutMs: SHELL_TIMEOUT_MS, maxOutputBytes: PM_PATH_MAX_OUTPUT_BYTES }, signal);
+        if (!resolved.ok)
+            return resolved;
+        const component = parseResolveActivityOutput(resolved.value.stdout);
+        if (component === null)
+            return err(new AnalysisUnsupportedTargetError(operation, input.serial, `No launcher activity is declared for ${input.package}`));
+        return this.runAmStart(operation, selection, client, provider, input.serial, ["-n", component], {
+            client,
+            serial: input.serial,
+            package_name: input.package,
+            component,
+        }, signal);
+    }
+    async startActivity(operation, selection, client, provider, input, signal) {
+        const extraFlags = {
+            string: "--es",
+            boolean: "--ez",
+            int: "--ei",
+            long: "--el",
+            float: "--ef",
+        };
+        for (const extra of input.extras)
+            if (extra.type === "boolean" && !/^(true|false)$/u.test(extra.value))
+                return err(new AnalysisInputError(operation, {
+                    cause: new Error(`Boolean extra ${extra.key} must be true or false`),
+                }));
+            else if ((extra.type === "int" || extra.type === "long") &&
+                !/^-?\d+$/u.test(extra.value))
+                return err(new AnalysisInputError(operation, {
+                    cause: new Error(`${extra.type === "int" ? "Integer" : "Long"} extra ${extra.key} must be an integer`),
+                }));
+            else if (extra.type === "float" && !/^-?\d+(\.\d+)?$/u.test(extra.value))
+                return err(new AnalysisInputError(operation, {
+                    cause: new Error(`Float extra ${extra.key} must be a number`),
+                }));
+        const arguments_ = [
+            "-a",
+            input.action,
+            ...(input.data_uri === undefined ? [] : ["-d", input.data_uri]),
+            ...(input.component === undefined ? [] : ["-n", input.component]),
+            ...input.extras.flatMap((extra) => [
+                extraFlags[extra.type],
+                extra.key,
+                extra.value,
+            ]),
+        ];
+        return this.runAmStart(operation, selection, client, provider, input.serial, arguments_, {
+            client,
+            serial: input.serial,
+            action: input.action,
+            data_uri: input.data_uri ?? null,
+            component: input.component ?? null,
+            extras: input.extras.map((extra) => ({ ...extra })),
+        }, signal);
+    }
+    async runAmStart(operation, selection, client, provider, serial, arguments_, resultFields, signal) {
+        const started = await runAdb(operation, serial, selection.binary, adbArguments(serial, ["shell", "am", "start", "-W", ...arguments_]), { timeoutMs: SHELL_TIMEOUT_MS, maxOutputBytes: PM_PATH_MAX_OUTPUT_BYTES }, signal);
+        if (!started.ok)
+            return started;
+        const verdict = parseAmStartOutput(started.value.stdout, started.value.stderr);
+        const result = {
+            ...resultFields,
+            started_activity: verdict.startedActivity,
+            reported_activity: verdict.activity,
+            reported_status: verdict.reportedStatus,
+        };
+        if (verdict.status === "refused") {
+            const partialObservation = operation === "start_adb_app"
+                ? {
+                    provider_id: "adb",
+                    operation,
+                    result: adbResultSchemas.start_adb_app.parse(result),
+                }
+                : {
+                    provider_id: "adb",
+                    operation,
+                    result: adbResultSchemas.start_adb_activity.parse(result),
+                };
+            return err(new AnalysisUnsupportedTargetError(operation, serial, verdict.reason ?? "am start refused the intent", {
+                capturedOutput: {
+                    stdout: started.value.stdout,
+                    stderr: started.value.stderr,
+                    truncated: false,
+                },
+                partialObservation,
+            }));
+        }
+        return ok(createAnalysisExecution(result, provider, {
+            rawResult: {
+                stdout: started.value.stdout,
+                stderr: started.value.stderr,
+            },
+            limitations: [
+                "Starting an activity changes device state; am start -W waits for launch completion but no lifecycle observation is captured",
+            ],
+        }));
+    }
+    async stopApp(operation, selection, client, provider, input, signal) {
+        const stopped = await runAdb(operation, input.serial, selection.binary, adbArguments(input.serial, ["shell", "am", "force-stop", input.package]), { timeoutMs: SHELL_TIMEOUT_MS, maxOutputBytes: PM_PATH_MAX_OUTPUT_BYTES }, signal);
+        if (!stopped.ok)
+            return stopped;
+        return ok(createAnalysisExecution({
+            client,
+            serial: input.serial,
+            package_name: input.package,
+        }, provider, {
+            limitations: [
+                "Force-stop succeeds even for packages with no running process; it reports completion, not prior state",
+            ],
+        }));
+    }
+    async captureScreen(operation, selection, client, provider, input, signal) {
+        const directory = await prepareOutputDirectory(operation, input.output_directory);
+        if (!directory.ok)
+            return directory;
+        const localPath = join(directory.value, "screen.png");
+        const existing = await refuseExistingTarget(operation, localPath);
+        if (existing !== undefined)
+            return err(existing);
+        const captured = await runAdbCapture(operation, input.serial, selection.binary, adbArguments(input.serial, ["exec-out", "screencap", "-p"]), { timeoutMs: SCREEN_TIMEOUT_MS, maxOutputBytes: SCREEN_MAX_OUTPUT_BYTES }, signal);
+        if (!captured.ok)
+            return captured;
+        const dimensions = parsePngDimensions(captured.value.stdout);
+        if (dimensions.width === null)
+            return err(new AnalysisProtocolError("screencap did not return a PNG payload; the device may not expose a display"));
+        try {
+            await writeFile(localPath, captured.value.stdout, { flag: "wx" });
+        }
+        catch (cause) {
+            return err(new AnalysisOutputError(operation, `The screen output could not be created exclusively: ${localPath}`, { cause }));
+        }
+        const sha256 = createHash("sha256")
+            .update(captured.value.stdout)
+            .digest("hex");
+        return ok(createAnalysisExecution({
+            client,
+            serial: input.serial,
+            local_path: localPath,
+            bytes: captured.value.stdout.byteLength,
+            sha256,
+            width: dimensions.width,
+            height: dimensions.height,
+        }, provider, {
+            limitations: [
+                "The capture is one frame at read time; no recording or interaction occurred",
+            ],
+        }));
+    }
+    async collectBugreport(operation, selection, client, provider, input, signal) {
+        const directory = await prepareOutputDirectory(operation, input.output_directory);
+        if (!directory.ok)
+            return directory;
+        let stagingDirectory;
+        let stagingIdentity;
+        let retainedObservation;
+        let publishedPath;
+        try {
+            stagingDirectory = await mkdtemp(join(directory.value, ".rea-bugreport-"));
+        }
+        catch (cause) {
+            return err(new AnalysisOutputError(operation, "The bugreport staging directory could not be created", { cause }));
+        }
+        const collectedResult = await (async () => {
+            let reportedPath = null;
+            try {
+                const created = await lstat(stagingDirectory);
+                if (!created.isDirectory() || created.isSymbolicLink())
+                    throw new Error(`The created bugreport staging output is not a regular directory: ${stagingDirectory}`);
+                stagingIdentity = {
+                    dev: created.dev,
+                    ino: created.ino,
+                    mode: created.mode,
+                };
+                const collected = await runAdb(operation, input.serial, selection.binary, adbArguments(input.serial, ["bugreport", stagingDirectory]), {
+                    timeoutMs: BUGREPORT_TIMEOUT_MS,
+                    maxOutputBytes: BUGREPORT_MAX_OUTPUT_BYTES,
+                }, signal);
+                if (!collected.ok)
+                    return collected;
+                reportedPath = parseBugreportCopiedPath(collected.value.stdout);
+                if (reportedPath === null)
+                    return err(new AnalysisProtocolError("adb bugreport did not report an archive path; the build may use an unsupported format"));
+                if (dirname(resolve(reportedPath)) !== stagingDirectory)
+                    return err(new AnalysisProtocolError(`adb bugreport reported an archive outside its staging directory: ${reportedPath}`));
+                const archive = await lstat(reportedPath);
+                if (!archive.isFile() || archive.isSymbolicLink())
+                    return err(new AnalysisProtocolError(`adb bugreport did not report a regular archive file: ${reportedPath}`));
+                retainedObservation = {
+                    provider_id: "adb",
+                    operation,
+                    result: {
+                        client,
+                        serial: input.serial,
+                        local_path: reportedPath,
+                        adb_reported_path: reportedPath,
+                        digest_status: "unknown",
+                    },
+                };
+                try {
+                    publishedPath = await publishBugreport(reportedPath, directory.value);
+                }
+                catch (cause) {
+                    return err(new AnalysisOutputError(operation, `The reported bugreport archive could not be published: ${reportedPath}`, { cause, partialObservation: retainedObservation }));
+                }
+                retainedObservation = {
+                    ...retainedObservation,
+                    result: { ...retainedObservation.result, local_path: publishedPath },
+                };
+                const digest = await hashAdbFile(publishedPath, operation, signal);
+                const report = {
+                    client,
+                    serial: input.serial,
+                    local_path: publishedPath,
+                    bytes: digest.bytes,
+                    sha256: digest.sha256,
+                    adb_reported_path: reportedPath,
+                };
+                retainedObservation = {
+                    provider_id: "adb",
+                    operation,
+                    result: report,
+                };
+                return ok(createAnalysisExecution(report, provider, {
+                    limitations: [
+                        "The archive is device-generated: dumpstate, dumpsys, and logcat content is the device's own report",
+                    ],
+                }));
+            }
+            catch (cause) {
+                if (cause instanceof AnalysisCancelledError) {
+                    if (retainedObservation !== undefined)
+                        cause.retainPartialObservation(retainedObservation);
+                    return err(cause);
+                }
+                return err(new AnalysisOutputError(operation, `The reported bugreport archive could not be read back: ${reportedPath ?? stagingDirectory}`, { cause, partialObservation: retainedObservation }));
+            }
+        })();
+        // A completed acquisition becomes caller evidence even if publication fails.
+        // Its staging directory must not enter automatic cleanup or cleanup retries.
+        if (retainedObservation !== undefined && publishedPath === undefined)
+            return collectedResult;
+        try {
+            await removeOwnedOutputDirectory(stagingDirectory, stagingIdentity);
+        }
+        catch (cause) {
+            const primary = collectedResult.ok
+                ? new AnalysisOutputError(operation, "The archive was published, but its staging directory could not be removed")
+                : collectedResult.error;
+            if (retainedObservation !== undefined)
+                primary.retainPartialObservation(retainedObservation);
+            this.#pendingOutputDirectoryCleanup.add({
+                operation,
+                path: stagingDirectory,
+                identity: stagingIdentity,
+                primary,
+                remove: () => removeOwnedOutputDirectory(stagingDirectory, stagingIdentity),
+            });
+            return err(analysisErrorWithCleanupFailure(primary, new ProviderCleanupError(ADB_PROVIDER_IDENTITY.id, [stagingDirectory], { reason: cause instanceof Error ? cause.message : String(cause) }, { operation, cause }), operation));
+        }
+        return collectedResult;
+    }
+}