rea-agents 6.4.0 → 6.5.0

package/dist/adb/AdbProvider.js

@@ -1,27 +1,28 @@
-import { execFile } from "node:child_process";
 import { createHash } from "node:crypto";
 import { constants as fsConstants } from "node:fs";
-import { access, lstat, mkdir, rm, stat, writeFile } from "node:fs/promises";
-import { basename, join, resolve } from "node:path";
+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 { AnalysisArtifactChangedError, AnalysisCapabilityUnavailableError, AnalysisCancelledError, AnalysisInputError, AnalysisOutputError, AnalysisProtocolError, AnalysisResourceConstraintError, AnalysisTimeoutError, AnalysisUnsupportedTargetError, } from "../domain/analysisErrorCore.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 { execFileOutput, execFileOutputFailure, } from "../process/ExecFileOutput.js";
+import { execFileBytes, execFileOutputFailure, } from "../process/ExecFileOutput.js";
 import { AdbConfigurationFailure, adbConfigurationAvailability, inspectAdbClient, resolveAdbBinary, } from "./AdbConfiguration.js";
-import { parseAdbDevicesOutput, parseGetpropOutput, parsePackageListOutput, parsePmPathOutput, } from "./AdbDeviceOutput.js";
-import { parseAmStartOutput, parseBugreportCopiedPath, parseDumpsysPackageOutput, parseFeatureListOutput, parseLsOutput, parsePackageChangeOutput, parseProcessListOutput, parsePngDimensions, parseResolveActivityOutput, parseServiceListOutput, parseSettingsGetOutput, parseWindowFocusOutput, parseWmDensityOutput, parseWmSizeOutput, } from "./AdbShellOutput.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 VERSION_TIMEOUT_MS = 10_000;
-const VERSION_MAX_OUTPUT_BYTES = 64 * 1024;
 const DEVICES_TIMEOUT_MS = 20_000;
 const DEVICES_MAX_OUTPUT_BYTES = 1024 * 1024;
 const SHELL_TIMEOUT_MS = 30_000;
@@ -47,7 +48,6 @@ const BUGREPORT_TIMEOUT_MS = 600_000;
 const BUGREPORT_MAX_OUTPUT_BYTES = 1024 * 1024;
 const STDERR_EXCERPT_BYTES = 512;
 const UNPARSED_LINES_REPORTED = 10;
-const STOP_GRACE_MS = 5_000;
 const hashAdbFile = async (path, operation, signal) => {
     try {
         return await hashStableFile(path, signal);
@@ -69,11 +69,11 @@ const adbArguments = (serial, arguments_) => {
     return serial === undefined ? operands : ["-s", serial, ...operands];
 };
 /** Run one bounded adb invocation and keep its exact failure shape. */
-const runAdb = async (operation, targetPath, binary, arguments_, limits, signal) => {
+const runAdbCapture = async (operation, targetPath, binary, arguments_, limits, signal) => {
     if (signal?.aborted === true)
         return err(new AnalysisCancelledError(operation));
     try {
-        return ok(await execFileOutput(binary, arguments_, {
+        return ok(await execFileBytes(binary, arguments_, {
             timeout: limits.timeoutMs,
             maxBuffer: limits.maxOutputBytes,
             stopSignal: "SIGTERM",
@@ -108,41 +108,37 @@ const runAdb = async (operation, targetPath, binary, arguments_, limits, signal)
             : excerpt, { cause }));
     }
 };
-/** Capture one adb invocation's raw binary stdout (screencap PNG). */
-const runAdbBinary = (operation, binary, arguments_, limits, signal) => new Promise((settle) => {
-    if (signal?.aborted === true)
-        return settle(err(new AnalysisCancelledError(operation)));
-    let stopped;
-    let deadline;
-    let grace;
-    const child = execFile(binary, [...arguments_], {
-        encoding: "buffer",
-        maxBuffer: limits.maxOutputBytes,
-        killSignal: "SIGTERM",
-        timeout: 0,
-    }, (error, stdout) => {
-        signal?.removeEventListener("abort", onAbort);
-        clearTimeout(deadline);
-        clearTimeout(grace);
-        if (stopped === "abort")
-            return settle(err(new AnalysisCancelledError(operation)));
-        if (stopped === "timeout")
-            return settle(err(new AnalysisTimeoutError(operation, limits.timeoutMs)));
-        if (error !== null)
-            return settle(err(new AnalysisProtocolError(`adb failed for ${operation}: ${error.message}`, { cause: error })));
-        settle(ok(stdout));
+/** 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,
     });
-    const stop = (reason) => {
-        if (stopped !== undefined)
-            return;
-        stopped = reason;
-        child.kill("SIGTERM");
-        grace = setTimeout(() => child.kill("SIGKILL"), STOP_GRACE_MS);
-    };
-    const onAbort = () => stop("abort");
-    signal?.addEventListener("abort", onAbort, { once: true });
-    deadline = setTimeout(() => stop("timeout"), limits.timeoutMs);
-});
+};
+/**
+ * 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,
@@ -175,9 +171,27 @@ const refuseExistingTarget = async (operation, path) => {
         return new AnalysisOutputError(operation, `The output file already exists: ${path}`);
     return undefined;
 };
-const removeOwnedPackageDirectory = async (path, identity) => {
+/** 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 package directory identity; refusing to remove ${path}`);
+        throw new Error(`Cannot verify the created output directory identity; refusing to remove ${path}`);
     let current;
     try {
         current = await lstat(path);
@@ -192,9 +206,82 @@ const removeOwnedPackageDirectory = async (path, identity) => {
         current.dev !== identity.dev ||
         current.ino !== identity.ino ||
         current.mode !== identity.mode)
-        throw new Error(`The created package directory was replaced or changed; refusing to remove ${path}`);
+        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.
  *
@@ -206,11 +293,11 @@ const removeOwnedPackageDirectory = async (path, identity) => {
  */
 export class AdbProvider {
     environment;
-    #pendingPackageDirectoryCleanup = new Set();
+    #pendingOutputDirectoryCleanup = new Set();
     #activeOperations = new Set();
     #closing = false;
     #closePromise;
-    #packageCleanupPromise;
+    #outputCleanupPromise;
     constructor(options = {}) {
         this.environment = options.environment ?? process.env;
     }
@@ -219,8 +306,8 @@ export class AdbProvider {
     }
     /** Probe the selected adb binary; never contacts devices or the server. */
     async inspectAvailability(signal) {
-        const selection = this.selection();
         try {
+            const selection = this.selection();
             await inspectAdbClient(selection, signal);
             return {
                 status: "available",
@@ -238,14 +325,14 @@ export class AdbProvider {
             throw cause;
         }
     }
-    /** Retry removal of package directories retained after failed rollback. */
+    /** 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.#retryPackageDirectoryCleanup();
+            await this.#retryOutputDirectoryCleanup();
         })().finally(() => {
             if (this.#closePromise === closing)
                 this.#closePromise = undefined;
@@ -253,42 +340,43 @@ export class AdbProvider {
         this.#closePromise = closing;
         return this.#closePromise;
     }
-    #retryPackageDirectoryCleanup() {
-        if (this.#packageCleanupPromise !== undefined)
-            return this.#packageCleanupPromise;
-        const cleanup = this.#performPackageDirectoryCleanup().finally(() => {
-            if (this.#packageCleanupPromise === cleanup)
-                this.#packageCleanupPromise = undefined;
+    #retryOutputDirectoryCleanup() {
+        if (this.#outputCleanupPromise !== undefined)
+            return this.#outputCleanupPromise;
+        const cleanup = this.#performOutputDirectoryCleanup().finally(() => {
+            if (this.#outputCleanupPromise === cleanup)
+                this.#outputCleanupPromise = undefined;
         });
-        this.#packageCleanupPromise = cleanup;
+        this.#outputCleanupPromise = cleanup;
         return cleanup;
     }
-    async #performPackageDirectoryCleanup() {
+    async #performOutputDirectoryCleanup() {
         const failures = [];
-        for (const owner of this.#pendingPackageDirectoryCleanup) {
+        for (const owner of this.#pendingOutputDirectoryCleanup) {
             try {
                 await owner.remove();
-                this.#pendingPackageDirectoryCleanup.delete(owner);
+                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: "pull_adb_package", cause });
-                failures.push(analysisErrorWithCleanupFailure(owner.primary, cleanup, "pull_adb_package"));
+                }, { 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.#pendingPackageDirectoryCleanup].map(({ path }) => path), {
-                reason: "Failed package output directories remain after cleanup retry",
+            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: "pull_adb_package",
-                cause: new AggregateError(failures, "Multiple ADB package rollback cleanups failed"),
+                operation: "close_binary",
+                cause: new AggregateError(failures, "Multiple ADB output directory cleanups failed"),
             });
     }
     async execute(request, options) {
@@ -300,14 +388,14 @@ export class AdbProvider {
         });
         this.#activeOperations.add(active);
         try {
-            if (this.#pendingPackageDirectoryCleanup.size > 0) {
+            if (this.#pendingOutputDirectoryCleanup.size > 0) {
                 try {
-                    await this.#retryPackageDirectoryCleanup();
+                    await this.#retryOutputDirectoryCleanup();
                 }
                 catch (cause) {
                     return err(cause instanceof AnalysisError
                         ? cause
-                        : new ProviderCleanupError(ADB_PROVIDER_IDENTITY.id, [...this.#pendingPackageDirectoryCleanup].map(({ path }) => path), {
+                        : new ProviderCleanupError(ADB_PROVIDER_IDENTITY.id, [...this.#pendingOutputDirectoryCleanup].map(({ path }) => path), {
                             reason: cause instanceof Error ? cause.message : String(cause),
                         }, { operation: request.operation, cause }));
                 }
@@ -323,18 +411,17 @@ export class AdbProvider {
         const signal = options?.signal;
         if (signal?.aborted === true)
             return err(new AnalysisCancelledError(request.operation));
-        const selection = this.selection();
+        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(new AnalysisCapabilityUnavailableError(ADB_PROVIDER_IDENTITY.id, request.operation, typeof cause.diagnostics.remediation === "string"
-                    ? `${cause.message} ${cause.diagnostics.remediation}`
-                    : cause.message, { cause }));
+                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);
@@ -354,7 +441,7 @@ export class AdbProvider {
                 }, signal);
                 if (!ran.ok)
                     return ran;
-                const { devices, unparsedLines, daemonStarted } = parseAdbDevicesOutput(ran.value.stdout);
+                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, {
@@ -447,7 +534,7 @@ export class AdbProvider {
                     buffer: request.input.buffer,
                     pid: request.input.pid ?? null,
                     lines: bounded,
-                    total_bytes: ran.value.stdout.length,
+                    total_bytes: ran.value.stdoutBytes,
                     coverage: bounded.length !== lines.length ||
                         bounded.length === request.input.count
                         ? "partial"
@@ -517,13 +604,21 @@ export class AdbProvider {
                 }, provider, { limitations: unparsedOverflowLimitation(unparsedLines) }));
             }
             case "list_adb_directory": {
-                const ran = await shell(["ls", "-la", request.input.device_path], {
+                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 } = parseLsOutput(ran.value.stdout);
+                const { entries, unparsedLines } = parseAdbDirectoryListing(ran.value.stdout);
                 return ok(createAnalysisExecution({
                     client,
                     serial: request.input.serial,
@@ -532,7 +627,7 @@ export class AdbProvider {
                     ...reported(unparsedLines, "complete"),
                 }, provider, {
                     limitations: [
-                        "Entry kinds derive from the permission string's type character",
+                        "Entry kinds derive from stat permission mode; directory contents and link targets may change during capture",
                         ...unparsedOverflowLimitation(unparsedLines),
                     ],
                 }));
@@ -598,13 +693,25 @@ export class AdbProvider {
                 }));
             }
             case "inspect_adb_window": {
-                const ran = await shell(["dumpsys", "window", "windows"], {
+                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;
-                const { focusedWindow, focusedApp } = parseWindowFocusOutput(ran.value.stdout);
+                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,
@@ -617,6 +724,9 @@ export class AdbProvider {
                 }, 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",
                     ],
                 }));
             }
@@ -687,10 +797,48 @@ export class AdbProvider {
         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]}`));
+            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;
@@ -716,17 +864,39 @@ export class AdbProvider {
             if (!packageDirectoryCreated)
                 return err(primary);
             const owner = {
+                operation,
                 path: packageDirectory,
                 identity: packageDirectoryIdentity,
                 primary,
-                remove: () => removeOwnedPackageDirectory(packageDirectory, packageDirectoryIdentity),
+                remove: () => removeOwnedOutputDirectory(packageDirectory, packageDirectoryIdentity),
             };
-            this.#pendingPackageDirectoryCleanup.add(owner);
+            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) => {
@@ -754,17 +924,7 @@ export class AdbProvider {
             });
             return err(error);
         };
-        const seenFileNames = new Set();
         for (const entry of parsed.paths) {
-            if (seenFileNames.has(entry.file_name)) {
-                failures.push({
-                    device_path: entry.device_path,
-                    stage: "pull",
-                    message: `Duplicate file name ${entry.file_name} in the APK set; refusing to overwrite`,
-                });
-                continue;
-            }
-            seenFileNames.add(entry.file_name);
             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) {
@@ -801,23 +961,7 @@ export class AdbProvider {
         }
         if (artifacts.length === 0 && failures.length > 0) {
             const primary = new AnalysisProtocolError(`Every APK pull failed for ${packageName} on ${serial}: ${failures[0].message}`);
-            const owner = {
-                path: packageDirectory,
-                identity: packageDirectoryIdentity,
-                primary,
-                remove: () => removeOwnedPackageDirectory(packageDirectory, packageDirectoryIdentity),
-            };
-            try {
-                await owner.remove();
-            }
-            catch (cause) {
-                this.#pendingPackageDirectoryCleanup.add(owner);
-                const cleanup = new ProviderCleanupError(ADB_PROVIDER_IDENTITY.id, [packageDirectory], {
-                    reason: cause instanceof Error ? cause.message : String(cause),
-                }, { operation: operation, cause });
-                return err(analysisErrorWithCleanupFailure(primary, cleanup, operation));
-            }
-            return err(primary);
+            return failOwnedPackage(primary);
         }
         return ok(createAnalysisExecution({
             client,
@@ -835,11 +979,19 @@ export class AdbProvider {
         }));
     }
     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 fileName = basename(input.device_path) || "pulled";
-        const localPath = join(directory.value, fileName);
+        const localPath = join(directory.value, derived.fileName);
         const existing = await refuseExistingTarget(operation, localPath);
         if (existing !== undefined)
             return err(existing);
@@ -896,19 +1048,13 @@ export class AdbProvider {
             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);
-        let deviceExists;
-        if (existsProbe.ok)
-            deviceExists = true;
-        else if (existsProbe.error instanceof AnalysisProtocolError)
-            deviceExists = false;
-        else if (existsProbe.error instanceof AnalysisTimeoutError)
-            return existsProbe;
-        else if (existsProbe.error instanceof AnalysisCancelledError)
-            return existsProbe;
-        else if (existsProbe.error instanceof AnalysisResourceConstraintError)
+        // `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;
-        else
-            deviceExists = true; // authorization/refusal states surface on push instead
+        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);
@@ -930,9 +1076,7 @@ export class AdbProvider {
                 overwritten: deviceExists,
                 device_digest_source: "device_sha256sum",
             }, provider, {
-                limitations: [
-                    "Push writes the caller's file to the device; this is the only device-mutating ADB tool",
-                ],
+                limitations: ["Push writes the caller's file to the device"],
             }));
         }
         return ok(createAnalysisExecution({
@@ -948,7 +1092,7 @@ export class AdbProvider {
         }, 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; this is the only device-mutating ADB tool",
+                "Push writes the caller's file to the device",
             ],
         }));
     }
@@ -974,7 +1118,8 @@ export class AdbProvider {
             apkPath,
         ]), { timeoutMs: PULL_TIMEOUT_MS, maxOutputBytes: PULL_MAX_OUTPUT_BYTES }, signal);
         if (!installed.ok)
-            return installed;
+            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"));
@@ -984,10 +1129,12 @@ export class AdbProvider {
             apk_path: apkPath,
             bytes: digest.bytes,
             sha256: digest.sha256,
-            replaced: input.replace,
+            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",
             ],
         }));
     }
@@ -997,7 +1144,8 @@ export class AdbProvider {
             maxOutputBytes: PULL_MAX_OUTPUT_BYTES,
         }, signal);
         if (!uninstalled.ok)
-            return uninstalled;
+            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"));
@@ -1080,13 +1228,39 @@ export class AdbProvider {
         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);
-        if (verdict.status === "refused")
-            return err(new AnalysisUnsupportedTargetError(operation, serial, verdict.reason ?? "am start refused the intent"));
-        return ok(createAnalysisExecution({
+        const verdict = parseAmStartOutput(started.value.stdout, started.value.stderr);
+        const result = {
             ...resultFields,
             started_activity: verdict.startedActivity,
-        }, provider, {
+            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",
             ],
@@ -1114,24 +1288,26 @@ export class AdbProvider {
         const existing = await refuseExistingTarget(operation, localPath);
         if (existing !== undefined)
             return err(existing);
-        const captured = await runAdbBinary(operation, selection.binary, adbArguments(input.serial, ["exec-out", "screencap", "-p"]), { timeoutMs: SCREEN_TIMEOUT_MS, maxOutputBytes: SCREEN_MAX_OUTPUT_BYTES }, signal);
+        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);
+        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, { flag: "wx" });
+            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).digest("hex");
+        const sha256 = createHash("sha256")
+            .update(captured.value.stdout)
+            .digest("hex");
         return ok(createAnalysisExecution({
             client,
             serial: input.serial,
             local_path: localPath,
-            bytes: captured.value.byteLength,
+            bytes: captured.value.stdout.byteLength,
             sha256,
             width: dimensions.width,
             height: dimensions.height,
@@ -1145,33 +1321,42 @@ export class AdbProvider {
         const directory = await prepareOutputDirectory(operation, input.output_directory);
         if (!directory.ok)
             return directory;
-        const collected = await runAdb(operation, input.serial, selection.binary, adbArguments(input.serial, ["bugreport", directory.value]), {
-            timeoutMs: BUGREPORT_TIMEOUT_MS,
-            maxOutputBytes: BUGREPORT_MAX_OUTPUT_BYTES,
-        }, signal);
-        if (!collected.ok)
-            return collected;
-        const 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"));
+        let stagingDirectory;
+        let stagingIdentity;
+        let retainedObservation;
+        let publishedPath;
         try {
-            const digest = await hashAdbFile(reportedPath, operation, signal);
-            return ok(createAnalysisExecution({
-                client,
-                serial: input.serial,
-                local_path: reportedPath,
-                bytes: digest.bytes,
-                sha256: digest.sha256,
-                adb_reported_path: reportedPath,
-            }, provider, {
-                limitations: [
-                    "The archive is device-generated: dumpstate, dumpsys, and logcat content is the device's own report",
-                ],
-            }));
+            stagingDirectory = await mkdtemp(join(directory.value, ".rea-bugreport-"));
         }
         catch (cause) {
-            if (cause instanceof AnalysisCancelledError) {
-                cause.retainPartialObservation({
+            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: {
@@ -1181,10 +1366,68 @@ export class AdbProvider {
                         adb_reported_path: reportedPath,
                         digest_status: "unknown",
                     },
-                });
-                return err(cause);
+                };
+                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",
+                    ],
+                }));
             }
-            return err(new AnalysisOutputError(operation, `The reported bugreport archive could not be read back: ${reportedPath}`, { cause }));
+            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;
     }
 }