rea-agents 6.4.0 → 6.7.0

package/dist/adb/AdbProvider.js

@@ -1,27 +1,39 @@
-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, link, mkdtemp, mkdir, open, 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 { ArtifactReaderFailure } from "../artifacts/ArtifactReader.js";
+import { ArtifactResourceRetryFailure, ArtifactResourceScope, } from "../artifacts/ArtifactResourceScope.js";
+import { AnalysisCleanupLease, AnalysisCleanupLeaseGroup, } from "../artifacts/AnalysisCleanupLease.js";
+import { adbResultSchemas } from "../domain/adb/adbDeviceAnalysis.js";
+import { AnalysisCapabilityUnavailableError, 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 { jsonObjectSchema } from "../domain/jsonValue.js";
+import { hashStableFile, stableFileHashCause, } from "../filesystem/StableFileHash.js";
+import { regularFileCancellation, RegularFileCancelled, RegularFileCleanupFailure, } from "../filesystem/OwnedRegularFile.js";
+import { RegularFileOperationCancelled } from "../filesystem/RegularFile.js";
+import { OwnedFileHandle } from "../filesystem/OwnedFileHandle.js";
+import { createEvidence } from "../domain/evidence.js";
+import { PrivateRuntimeRoot, } from "../process/PrivateRuntimeRoot.js";
 import { ProviderCleanupError } from "../domain/providerCleanupError.js";
-import { execFileOutput, execFileOutputFailure, } from "../process/ExecFileOutput.js";
+import { PrivateRuntimeRootUnavailableError } from "../process/PrivateRuntimeRootUnavailableError.js";
+import { adbArguments, runAdb, runAdbCapture, packageChangeRefusal, probeAdbPathExistence, } from "./AdbCommand.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 { AdbInputSnapshotFailure, snapshotAdbInput, } from "./AdbInputSnapshot.js";
+import { ADB_DIRECTORY_BATCH_SCRIPT, parseAdbDirectoryListing, } from "./AdbDirectoryListing.js";
+import { parseAmStartOutput, parseBugreportCopiedPath, parseDumpsysPackageOutput, parseFeatureListOutput, 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;
@@ -45,104 +57,164 @@ 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 STOP_GRACE_MS = 5_000;
-const hashAdbFile = async (path, operation, signal) => {
+/** Carry the exact digest owner through caller-specific partial-result mapping. */
+class AdbDigestFailure extends Error {
+    fileFailure;
+    bindCleanupError;
+    constructor(fileFailure, bindCleanupError) {
+        super(fileFailure.message, { cause: fileFailure });
+        this.fileFailure = fileFailure;
+        this.bindCleanupError = bindCleanupError;
+    }
+}
+const hashAdbFile = async (path, operation, signal, resources) => {
+    let closeLease;
     try {
-        return await hashStableFile(path, signal);
+        return await hashStableFile(path, {
+            ...(signal === undefined ? {} : { signal }),
+            retainFailedClose: (handle) => {
+                closeLease = new AnalysisCleanupLease(() => handle.close(), [path]);
+                resources.retain({
+                    kind: "lease",
+                    resource: `${path} (ADB digest handle)`,
+                    lease: closeLease,
+                });
+            },
+        });
     }
     catch (cause) {
-        if (signal?.aborted === true)
-            throw new AnalysisCancelledError(operation, { cause });
+        if (cause instanceof RegularFileCleanupFailure ||
+            cause instanceof RegularFileCancelled)
+            throw new AdbDigestFailure(cause, (error) => {
+                closeLease?.bindCleanupError(error);
+            });
+        if (cause instanceof RegularFileOperationCancelled)
+            throw new AnalysisCancelledError(operation, { cause: cause.reason });
         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];
+const adbDigestError = (cause, operation, partialObservation) => {
+    if (!(cause instanceof AdbDigestFailure))
+        return undefined;
+    const digestFailure = cause.fileFailure;
+    const digestOutcome = digestFailure.outcome;
+    if (digestOutcome.kind === "completed")
+        partialObservation = partialObservationWithDigest(partialObservation, digestOutcome.value);
+    if (digestFailure instanceof RegularFileCancelled)
+        return new AnalysisCancelledError(operation, {
+            cause: digestFailure.reason,
+            partialObservation,
+        });
+    const resource = `${digestFailure.path} (ADB digest handle)`;
+    const reason = digestFailure.cleanupCause instanceof Error
+        ? digestFailure.cleanupCause.message
+        : String(digestFailure.cleanupCause);
+    const cleanup = new ProviderCleanupError(ADB_PROVIDER_IDENTITY.id, [resource], { reason }, {
+        operation,
+        cause: digestFailure,
+        partialObservation,
+    });
+    const primaryCause = digestOutcome.kind === "failed" ? digestOutcome.cause : undefined;
+    const cancellation = regularFileCancellation(digestFailure);
+    if (cancellation !== undefined) {
+        const error = new AnalysisCancelledError(operation, {
+            cause: cancellation.reason,
+            cleanup: { reason, resources: [resource] },
+            partialObservation,
+        });
+        cause.bindCleanupError(error);
+        return error;
+    }
+    const primary = primaryCause instanceof AnalysisError
+        ? primaryCause
+        : new AnalysisOutputError(operation, `The pulled file could not be fully digested or its handle could not be closed: ${digestFailure.path}`, {
+            cause: digestOutcome.kind === "failed" ? primaryCause : digestFailure,
+            partialObservation,
+        });
+    primary.retainPartialObservation(partialObservation);
+    const error = analysisErrorWithCleanupFailure(primary, cleanup, operation);
+    cause.bindCleanupError(error);
+    return error;
 };
-/** Run one bounded adb invocation and keep its exact failure shape. */
-const runAdb = async (operation, targetPath, binary, arguments_, limits, signal) => {
-    if (signal?.aborted === true)
-        return err(new AnalysisCancelledError(operation));
+const partialObservationWithDigest = (observation, digest) => {
+    if (observation.operation === "pull_adb_file") {
+        const { result } = observation;
+        if (!("digest_status" in result))
+            return observation;
+        return {
+            ...observation,
+            result: {
+                client: result.client,
+                serial: result.serial,
+                local_path: result.local_path,
+                device_path: result.device_path,
+                bytes: digest.bytes,
+                sha256: digest.sha256,
+            },
+        };
+    }
+    if (observation.operation === "collect_adb_bugreport") {
+        const { result } = observation;
+        if (!("digest_status" in result))
+            return observation;
+        return {
+            ...observation,
+            result: {
+                client: result.client,
+                serial: result.serial,
+                local_path: result.local_path,
+                adb_reported_path: result.adb_reported_path,
+                bytes: digest.bytes,
+                sha256: digest.sha256,
+            },
+        };
+    }
+    return observation;
+};
+const syncStagedAdbFile = async (path, resources, operation) => {
+    let owner;
+    let primary;
     try {
-        return ok(await execFileOutput(binary, arguments_, {
-            timeout: limits.timeoutMs,
-            maxBuffer: limits.maxOutputBytes,
-            stopSignal: "SIGTERM",
-            ...(signal === undefined ? {} : { signal }),
-        }));
+        owner = new OwnedFileHandle(await open(path, "r+"));
+        await owner.handle.sync();
     }
     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 }));
+        primary = 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));
+    if (owner === undefined) {
+        if (primary !== undefined)
+            throw primary;
+        return;
+    }
+    const resource = `${path} (ADB staged-output handle)`;
+    const stagedOwner = owner;
+    const closeLease = new AnalysisCleanupLease(() => stagedOwner.close(), [resource]);
+    const released = await resources.release({
+        kind: "lease",
+        resource,
+        lease: closeLease,
     });
-    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);
-});
+    if (released.kind === "failed") {
+        const cleanup = new ProviderCleanupError(ADB_PROVIDER_IDENTITY.id, [resource], {
+            reason: released.cause instanceof Error
+                ? released.cause.message
+                : String(released.cause),
+        }, { operation, cause: released.cause });
+        let reported;
+        if (primary !== undefined) {
+            const failure = new AnalysisOutputError(operation, `The staged ADB output could not be synchronized: ${path}`, { cause: primary });
+            reported = analysisErrorWithCleanupFailure(failure, cleanup, operation);
+        }
+        else {
+            reported = cleanup;
+        }
+        closeLease.bindCleanupError(reported);
+        throw reported;
+    }
+    if (primary !== undefined)
+        throw primary;
+};
 const clientIdentityResult = (selection, identity) => ({
     binary_path: selection.binary,
     path_source: selection.pathSource,
@@ -175,9 +247,157 @@ const refuseExistingTarget = async (operation, path) => {
         return new AnalysisOutputError(operation, `The output file already exists: ${path}`);
     return undefined;
 };
-const removeOwnedPackageDirectory = async (path, identity) => {
+const hardLinksUnsupported = (cause) => cause instanceof Error &&
+    "code" in cause &&
+    ["EPERM", "EOPNOTSUPP", "ENOTSUP", "ENOSYS", "EXDEV"].includes(String(cause.code));
+const describeAdbFailure = (cause) => cause instanceof Error ? cause.message : String(cause);
+/** Exclusive-create fallback for filesystems that cannot hard-link staged files. */
+const publishScreenExclusively = async (outputPath, bytes, resources, operation, signal) => {
+    if (signal?.aborted === true)
+        throw new AnalysisCancelledError(operation, { cause: signal.reason });
+    const output = await open(outputPath, "wx", 0o600);
+    // Successful exclusive creation is this fallback's cutoff. Finish and sync
+    // the visible file despite later cancellation so its receipt remains known.
+    const ownedOutput = new OwnedFileHandle(output);
+    const handleResource = `${outputPath} (ADB publication handle)`;
+    const closeOnly = new AnalysisCleanupLease(() => ownedOutput.close(), [handleResource]);
+    const removeOutput = async (expected) => {
+        let current;
+        try {
+            current = await lstat(outputPath);
+        }
+        catch (cause) {
+            if (cause instanceof Error && Reflect.get(cause, "code") === "ENOENT")
+                return;
+            throw cause;
+        }
+        if (current.dev !== expected.dev ||
+            current.ino !== expected.ino ||
+            current.mode !== expected.mode)
+            throw new Error(`The screen output changed before cleanup: ${outputPath}`);
+        await rm(outputPath);
+    };
+    let rollbackIdentity;
+    const inspectCloseAndRollback = new AnalysisCleanupLease(async () => {
+        rollbackIdentity ??= await output.stat();
+        await ownedOutput.close();
+        await removeOutput(rollbackIdentity);
+    });
+    let identity;
+    try {
+        identity = await output.stat();
+    }
+    catch (cause) {
+        resources.retain({
+            kind: "lease",
+            resource: `${outputPath} (screen output and descriptor)`,
+            lease: inspectCloseAndRollback,
+        });
+        const error = new ProviderCleanupError(ADB_PROVIDER_IDENTITY.id, [handleResource, outputPath], {
+            reason: "The newly created screen output identity could not be established; its descriptor remains owned for cleanup retry",
+        }, { operation, cause });
+        inspectCloseAndRollback.bindCleanupError(error);
+        throw error;
+    }
+    let writeFailure;
+    try {
+        await output.writeFile(bytes);
+        await output.sync();
+    }
+    catch (cause) {
+        writeFailure = { cause };
+    }
+    if (writeFailure === undefined) {
+        try {
+            await ownedOutput.close();
+            return undefined;
+        }
+        catch (cause) {
+            resources.retain({
+                kind: "lease",
+                resource: handleResource,
+                lease: closeOnly,
+            });
+            return {
+                cause,
+                resource: handleResource,
+                bindCleanupError(error) {
+                    closeOnly.bindCleanupError(error);
+                },
+            };
+        }
+    }
+    const rollback = new AnalysisCleanupLease(async () => {
+        await ownedOutput.close();
+        await removeOutput(identity);
+    });
+    try {
+        await ownedOutput.close();
+    }
+    catch (closeCause) {
+        resources.retain({ kind: "lease", resource: outputPath, lease: rollback });
+        const error = new ProviderCleanupError(ADB_PROVIDER_IDENTITY.id, [outputPath], { reason: describeAdbFailure(closeCause) }, {
+            operation,
+            cause: new AggregateError([writeFailure.cause, closeCause], "Screen output write and descriptor cleanup failed", { cause: writeFailure.cause }),
+        });
+        rollback.bindCleanupError(error);
+        throw error;
+    }
+    const removed = await resources.release({
+        kind: "lease",
+        resource: outputPath,
+        lease: rollback,
+    });
+    if (removed.kind === "failed") {
+        const error = new ProviderCleanupError(ADB_PROVIDER_IDENTITY.id, [outputPath], { reason: describeAdbFailure(removed.cause) }, {
+            operation,
+            cause: new AggregateError([writeFailure.cause, removed.cause], "Screen output write and rollback failed", { cause: writeFailure.cause }),
+        });
+        rollback.bindCleanupError(error);
+        throw error;
+    }
+    throw writeFailure.cause;
+};
+const cancellationWithCleanupFailure = (primary, cleanup, resources) => new AnalysisCancelledError(primary.operation, {
+    cause: new AggregateError([primary, cleanup], "ADB cancellation cleanup failed", { cause: primary }),
+    diagnostics: primary.diagnostics,
+    ...(primary.capturedOutput === undefined
+        ? {}
+        : { capturedOutput: primary.capturedOutput }),
+    cleanup: {
+        reason: [primary.cleanup?.reason, cleanup.message]
+            .filter((reason) => reason !== undefined)
+            .join("; "),
+        resources: [...new Set([...primary.cleanupResources, ...resources])],
+    },
+    partialObservation: primary.partialObservation,
+});
+/** 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;
+        }
+    }
+};
+/** A root lease releases its children before removing their containing root. */
+const runtimeRootLease = (root, children) => new AnalysisCleanupLease(async () => {
+    await children.close();
+    await root.close();
+});
+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 +412,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,21 +499,27 @@ const removeOwnedPackageDirectory = async (path, identity) => {
  */
 export class AdbProvider {
     environment;
-    #pendingPackageDirectoryCleanup = new Set();
+    #createRuntimeRoot;
+    #resources = new ArtifactResourceScope();
+    #outputDirectoryRetryLeases = new WeakMap();
+    #pendingOutputDirectoryCleanup = new Set();
     #activeOperations = new Set();
     #closing = false;
     #closePromise;
-    #packageCleanupPromise;
+    #outputCleanupPromise;
     constructor(options = {}) {
         this.environment = options.environment ?? process.env;
+        this.#createRuntimeRoot =
+            options.createRuntimeRoot ??
+                ((rootOptions) => PrivateRuntimeRoot.create(rootOptions));
     }
     selection() {
         return resolveAdbBinary(this.environment);
     }
     /** 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 +537,53 @@ 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();
+            const failures = [];
+            const failedLeases = new Set();
+            let allFailuresHaveExactLeaseOwners = true;
+            // Directory errors may also depend on a retained digest descriptor.
+            // Settle those owners before deciding whether the directory error resolved.
+            for (const cleanup of [
+                () => this.#resources.close(),
+                () => this.#retryOutputDirectoryCleanup(),
+            ]) {
+                try {
+                    await cleanup();
+                }
+                catch (cause) {
+                    failures.push(cause);
+                    const leases = (cause instanceof AnalysisError
+                        ? this.#outputDirectoryRetryLeases.get(cause)
+                        : undefined) ??
+                        (cause instanceof ArtifactResourceRetryFailure
+                            ? cause.cleanupLeases
+                            : undefined);
+                    if (leases === undefined)
+                        allFailuresHaveExactLeaseOwners = false;
+                    for (const lease of leases ?? [])
+                        failedLeases.add(lease);
+                }
+            }
+            if (failures.length > 0) {
+                const resources = failures.flatMap((cause) => this.#cleanupResources(cause, "ADB provider-owned resource"));
+                const error = new ProviderCleanupError(ADB_PROVIDER_IDENTITY.id, [...new Set(resources)], {
+                    reason: failures
+                        .map((cause) => cause instanceof Error ? cause.message : String(cause))
+                        .join("; "),
+                }, {
+                    operation: "close_binary",
+                    cause: new AggregateError(failures, "ADB cleanup remains incomplete"),
+                });
+                if (allFailuresHaveExactLeaseOwners && failedLeases.size > 0)
+                    new AnalysisCleanupLeaseGroup(error, [...failedLeases]);
+                throw error;
+            }
         })().finally(() => {
             if (this.#closePromise === closing)
                 this.#closePromise = undefined;
@@ -253,43 +591,185 @@ 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;
+    #cleanupResources(cause, resource) {
+        if (cause instanceof ArtifactReaderFailure && cause.cleanup !== undefined)
+            return cause.cleanup.resources;
+        if (cause instanceof AnalysisError && cause.cleanupResources.length > 0)
+            return cause.cleanupResources;
+        return [resource];
+    }
+    #cleanupError(operation, parameters, causes, resources, execution) {
+        const partialObservation = execution === undefined
+            ? undefined
+            : createEvidence(execution.subject ?? undefined, execution.provider, {
+                operation,
+                parameters,
+                result: execution.result,
+                rawResult: execution.rawResult,
+                limitations: execution.limitations,
+                locations: execution.locations,
+                confidence: "observed",
+            });
+        return new ProviderCleanupError(ADB_PROVIDER_IDENTITY.id, resources, {
+            reason: causes
+                .map((cause) => cause instanceof Error ? cause.message : String(cause))
+                .join("; "),
+        }, {
+            operation,
+            cause: new AggregateError(causes, "ADB operation cleanup failed"),
+            ...(partialObservation === undefined ? {} : { partialObservation }),
         });
-        this.#packageCleanupPromise = cleanup;
+    }
+    async #withRuntimeRoot(operation, parameters, options, signal, work) {
+        let root;
+        try {
+            root = await this.#createRuntimeRoot(options);
+        }
+        catch (cause) {
+            return err(cause instanceof AnalysisError
+                ? cause
+                : cause instanceof PrivateRuntimeRootUnavailableError
+                    ? new AnalysisCapabilityUnavailableError(ADB_PROVIDER_IDENTITY.id, operation, cause.message, { cause, retryable: cause.retryable })
+                    : new AnalysisOutputError(operation, "Could not create an ADB private workspace", {
+                        cause,
+                    }));
+        }
+        let result;
+        let primary;
+        const children = new ArtifactResourceScope();
+        try {
+            result = await work(root, children);
+        }
+        catch (cause) {
+            if (cause instanceof AdbInputSnapshotFailure) {
+                primary =
+                    cause.primaryCause instanceof AnalysisError
+                        ? cause.primaryCause
+                        : new AnalysisOutputError(operation, `The caller input could not be staged for adb: ${cause.sourcePath}`, { cause: cause.primaryCause ?? cause });
+                // Snapshot handle cleanup may recover when the runtime-root lease is
+                // drained below. Keep that historical failure linked to the typed
+                // primary error while the lease owns and clears live cleanup state.
+                primary.retainSecondaryFailure(new AnalysisOutputError(operation, `ADB input snapshot cleanup previously failed for ${cause.sourcePath}`, { cause }), {});
+            }
+            else {
+                primary =
+                    cause instanceof AnalysisError
+                        ? cause
+                        : new AnalysisProtocolError(`ADB ${operation} failed`, { cause });
+            }
+        }
+        const rootLease = runtimeRootLease(root, children);
+        const released = await this.#resources.release({
+            kind: "lease",
+            resource: root.path,
+            lease: rootLease,
+        });
+        if (primary === undefined && result?.ok && signal?.aborted === true) {
+            const completed = result.value;
+            primary = new AnalysisCancelledError(operation, {
+                cause: signal.reason,
+                partialObservation: createEvidence(completed.subject ?? undefined, completed.provider, {
+                    operation,
+                    parameters,
+                    result: completed.result,
+                    rawResult: completed.rawResult,
+                    limitations: completed.limitations,
+                    locations: completed.locations,
+                    confidence: "observed",
+                }),
+            });
+        }
+        if (released.kind === "failed") {
+            const cleanupResources = [
+                root.path,
+                ...(released.cause instanceof ArtifactReaderFailure &&
+                    released.cause.cleanup !== undefined
+                    ? released.cause.cleanup.resources
+                    : []),
+            ];
+            const cleanup = this.#cleanupError(operation, parameters, [released.cause], cleanupResources, result?.ok ? result.value : undefined);
+            const returnCleanupError = (error) => {
+                rootLease.bindCleanupError(error);
+                return err(error);
+            };
+            if (primary instanceof AnalysisCancelledError) {
+                return returnCleanupError(cancellationWithCleanupFailure(primary, cleanup, cleanupResources));
+            }
+            if (primary !== undefined)
+                return returnCleanupError(analysisErrorWithCleanupFailure(primary, cleanup, operation));
+            if (result !== undefined && !result.ok) {
+                if (result.error instanceof AnalysisCancelledError) {
+                    return returnCleanupError(cancellationWithCleanupFailure(result.error, cleanup, cleanupResources));
+                }
+                return returnCleanupError(analysisErrorWithCleanupFailure(result.error, cleanup, operation));
+            }
+            return returnCleanupError(cleanup);
+        }
+        if (primary !== undefined)
+            return err(primary);
+        if (result === undefined)
+            return err(new AnalysisProtocolError(`ADB ${operation} returned no result`));
+        return result;
+    }
+    #retainOutputDirectoryCleanup(owner, cleanup) {
+        const lease = new AnalysisCleanupLease(async () => {
+            await owner.remove();
+            if (owner.primary.cleanupIncomplete)
+                throw new Error("ADB output directory primary cleanup remains incomplete");
+        });
+        const error = analysisErrorWithCleanupFailure(owner.primary, cleanup, owner.operation);
+        lease.bindCleanupError(error);
+        this.#pendingOutputDirectoryCleanup.add({ ...owner, lease });
+        return error;
+    }
+    #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 #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);
+                await owner.lease.release();
+                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 });
+                const error = analysisErrorWithCleanupFailure(owner.primary, cleanup, owner.operation);
+                owner.lease.bindCleanupError(error);
+                failures.push(error);
             }
         }
-        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",
-                failures: failures.map(({ message, cleanupResources }) => ({
-                    message,
-                    resources: [...cleanupResources],
-                })),
-            }, {
-                operation: "pull_adb_package",
-                cause: new AggregateError(failures, "Multiple ADB package rollback cleanups failed"),
-            });
+        if (failures.length > 0) {
+            const error = failures.length === 1
+                ? failures[0]
+                : new ProviderCleanupError(ADB_PROVIDER_IDENTITY.id, [
+                    ...new Set(failures.flatMap((failure) => failure.cleanupResources)),
+                ], {
+                    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"),
+                });
+            const leases = [...this.#pendingOutputDirectoryCleanup].map(({ lease }) => lease);
+            this.#outputDirectoryRetryLeases.set(error, leases);
+            if (failures.length > 1)
+                new AnalysisCleanupLeaseGroup(error, leases);
+            throw error;
+        }
     }
     async execute(request, options) {
         if (this.#closing)
@@ -300,14 +780,26 @@ export class AdbProvider {
         });
         this.#activeOperations.add(active);
         try {
-            if (this.#pendingPackageDirectoryCleanup.size > 0) {
+            try {
+                await this.#resources.retryCleanup();
+            }
+            catch (cause) {
+                const error = this.#cleanupError(request.operation, jsonObjectSchema.parse(request.input), [cause], this.#cleanupResources(cause, "ADB provider-owned resource"));
+                const leases = cause instanceof ArtifactResourceRetryFailure
+                    ? cause.cleanupLeases
+                    : undefined;
+                if (leases !== undefined)
+                    new AnalysisCleanupLeaseGroup(error, leases);
+                return err(error);
+            }
+            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 }));
                 }
@@ -322,19 +814,18 @@ export class AdbProvider {
     async #executeOperation(request, options) {
         const signal = options?.signal;
         if (signal?.aborted === true)
-            return err(new AnalysisCancelledError(request.operation));
-        const selection = this.selection();
+            return err(new AnalysisCancelledError(request.operation, { cause: signal.reason }));
+        let selection;
         let identity;
         try {
+            selection = this.selection();
             identity = await inspectAdbClient(selection, signal);
         }
         catch (cause) {
-            if (cause instanceof AnalysisCancelledError)
+            if (cause instanceof AnalysisError)
                 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 +845,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 +938,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"
@@ -482,13 +973,15 @@ export class AdbProvider {
                     user_id: details.userId,
                     pkg_flags: details.pkgFlags,
                     requested_permissions_count: details.requestedPermissions,
-                    coverage: details.versionCode === null && details.versionName === null
+                    coverage: details.requestedPermissions === null ||
+                        (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",
+                        "requested_permissions_count counts the listed requested permissions section; an absent section is zero only when dumpsys confirms a loaded parsed package",
+                        "A null requested_permissions_count means dumpsys reported pkg=null or did not establish that an omitted permission section is an empty inventory",
                     ],
                 }));
             }
@@ -517,13 +1010,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 +1033,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,25 +1099,41 @@ 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 focus = parseWindowFocusOutput(ran.value.stdout);
+                if (focus.focus_summary === "unavailable") {
+                    section = "displays";
+                    const fallback = await shell(["dumpsys", "window", section], {
+                        timeoutMs: SHELL_TIMEOUT_MS,
+                        maxOutputBytes: DUMPSYS_WINDOW_MAX_OUTPUT_BYTES,
+                    });
+                    if (!fallback.ok)
+                        return fallback;
+                    focus = parseWindowFocusOutput(fallback.value.stdout);
+                }
+                const declared = focus.focus_summary !== "unavailable";
                 return ok(createAnalysisExecution({
                     client,
                     serial: request.input.serial,
-                    focused_window: focusedWindow,
-                    focused_app: focusedApp,
-                    observed_lines: [
-                        ...(focusedWindow === null ? [] : [focusedWindow]),
-                        ...(focusedApp === null ? [] : [focusedApp]),
-                    ],
+                    source_section: section,
+                    ...focus,
                 }, 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",
+                        ...(focus.focus_summary === "ambiguous"
+                            ? [
+                                "Multiple focus contexts or repeated declarations prevent a singular focus summary; inspect focus_contexts for every declaration",
+                            ]
+                            : []),
                     ],
                 }));
             }
@@ -687,10 +1204,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,19 +1271,42 @@ 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);
             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));
+            return err(this.#retainOutputDirectoryCleanup(owner, cleanup));
         }
+        const failOwnedPackage = async (primary) => {
+            const owner = {
+                operation,
+                path: packageDirectory,
+                primary,
+                remove: () => removeOwnedOutputDirectory(packageDirectory, packageDirectoryIdentity),
+            };
+            try {
+                await owner.remove();
+            }
+            catch (cause) {
+                const cleanup = new ProviderCleanupError(ADB_PROVIDER_IDENTITY.id, [packageDirectory], { reason: cause instanceof Error ? cause.message : String(cause) }, { operation, cause });
+                return err(this.#retainOutputDirectoryCleanup(owner, cleanup));
+            }
+            return err(primary);
+        };
+        const destinationError = await reservePackageDestinations(operation, packageName, packageDirectory, parsed.paths, capturedOutput);
+        if (destinationError !== undefined)
+            return failOwnedPackage(destinationError);
         const artifacts = [];
         const failures = [];
+        const observedFailures = () => failures.map(({ device_path, stage, message }) => ({
+            device_path,
+            stage,
+            message,
+        }));
         const cancelledPackagePull = (error, localPath, devicePath, stage) => {
             error.retainPartialObservation({
                 provider_id: "adb",
@@ -740,7 +1318,7 @@ export class AdbProvider {
                     output_directory: directory.value,
                     artifacts,
                     failures: [
-                        ...failures,
+                        ...observedFailures(),
                         {
                             device_path: devicePath,
                             stage,
@@ -754,17 +1332,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) {
@@ -774,11 +1342,12 @@ export class AdbProvider {
                     device_path: entry.device_path,
                     stage: "pull",
                     message: pulled.error.message,
+                    cause: pulled.error,
                 });
                 continue;
             }
             try {
-                const digest = await hashAdbFile(localPath, operation, signal);
+                const digest = await hashAdbFile(localPath, operation, signal, this.#resources);
                 artifacts.push({
                     device_path: entry.device_path,
                     file_name: entry.file_name,
@@ -790,34 +1359,66 @@ export class AdbProvider {
                 });
             }
             catch (cause) {
+                const digestFailure = cause instanceof AdbDigestFailure ? cause.fileFailure : undefined;
+                const completedDigest = digestFailure?.outcome.kind === "completed"
+                    ? digestFailure.outcome.value
+                    : undefined;
+                const partialObservation = {
+                    provider_id: "adb",
+                    operation,
+                    result: {
+                        client,
+                        serial,
+                        package_name: packageName,
+                        output_directory: directory.value,
+                        artifacts: completedDigest === undefined
+                            ? artifacts
+                            : [
+                                ...artifacts,
+                                {
+                                    device_path: entry.device_path,
+                                    file_name: entry.file_name,
+                                    local_path: localPath,
+                                    bytes: completedDigest.bytes,
+                                    sha256: completedDigest.sha256,
+                                    role: entry.role,
+                                    role_basis: "file_name",
+                                },
+                            ],
+                        failures: [
+                            ...observedFailures(),
+                            {
+                                device_path: entry.device_path,
+                                stage: "digest",
+                                message: completedDigest === undefined
+                                    ? `The pulled file remains at ${localPath}, but its digest and descriptor cleanup are unconfirmed.`
+                                    : digestFailure instanceof RegularFileCancelled
+                                        ? `The pulled file digest and descriptor cleanup are confirmed; the request was cancelled: ${localPath}`
+                                        : `The pulled file digest is known, but its descriptor cleanup is unconfirmed: ${localPath}`,
+                            },
+                        ],
+                        coverage: "partial",
+                    },
+                };
+                const cleanupError = adbDigestError(cause, operation, partialObservation);
+                if (cleanupError !== undefined)
+                    return err(cleanupError);
                 if (cause instanceof AnalysisCancelledError)
                     return cancelledPackagePull(cause, localPath, entry.device_path, "digest");
+                const physicalCause = stableFileHashCause(cause);
                 failures.push({
                     device_path: entry.device_path,
                     stage: "digest",
-                    message: `The pulled file could not be read back after pulling: ${localPath}`,
+                    message: `The pulled file could not be read back after pulling: ${localPath}: ${physicalCause instanceof Error ? physicalCause.message : String(physicalCause)}`,
+                    cause,
                 });
             }
         }
         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);
+            const primary = new AnalysisProtocolError(`Every APK pull failed for ${packageName} on ${serial}: ${failures[0].message}`, {
+                cause: new AggregateError(failures.map(({ cause }) => cause), "APK pulls failed"),
+            });
+            return failOwnedPackage(primary);
         }
         return ok(createAnalysisExecution({
             client,
@@ -825,7 +1426,7 @@ export class AdbProvider {
             package_name: packageName,
             output_directory: directory.value,
             artifacts,
-            failures,
+            failures: observedFailures(),
             coverage: failures.length === 0 ? "complete" : "partial",
         }, provider, {
             limitations: [
@@ -835,11 +1436,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);
@@ -847,7 +1456,7 @@ export class AdbProvider {
         if (!pulled.ok)
             return pulled;
         try {
-            const digest = await hashAdbFile(localPath, operation, signal);
+            const digest = await hashAdbFile(localPath, operation, signal, this.#resources);
             return ok(createAnalysisExecution({
                 client,
                 serial: input.serial,
@@ -862,18 +1471,22 @@ export class AdbProvider {
             }));
         }
         catch (cause) {
+            const partialObservation = {
+                provider_id: "adb",
+                operation,
+                result: {
+                    client,
+                    serial: input.serial,
+                    local_path: localPath,
+                    device_path: input.device_path,
+                    digest_status: "unknown",
+                },
+            };
+            const cleanupError = adbDigestError(cause, operation, partialObservation);
+            if (cleanupError !== undefined)
+                return err(cleanupError);
             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",
-                    },
-                });
+                cause.retainPartialObservation(partialObservation);
                 return err(cause);
             }
             return err(new AnalysisOutputError(operation, `The pulled file could not be read back after pulling: ${localPath}`, { cause }));
@@ -886,71 +1499,74 @@ export class AdbProvider {
             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);
-        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)
-            return existsProbe;
-        else
-            deviceExists = true; // authorization/refusal states surface on push instead
-        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({
+        return this.#withRuntimeRoot(operation, {
+            serial: input.serial,
+            local_path: localPath,
+            device_path: input.device_path,
+            overwrite: input.overwrite,
+        }, { prefix: "rea-adb-input-" }, signal, async (root, resources) => {
+            const digest = await snapshotAdbInput(localPath, root, resources, operation, signal);
+            const existsProbe = await probeAdbPathExistence(operation, input.serial, input.device_path, selection.binary, { timeoutMs: SETTINGS_TIMEOUT_MS, maxOutputBytes: 1024 }, signal);
+            if (!existsProbe.ok)
+                return existsProbe;
+            const deviceExists = existsProbe.value;
+            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", digest.path, input.device_path]), { timeoutMs: PULL_TIMEOUT_MS, maxOutputBytes: PULL_MAX_OUTPUT_BYTES }, signal);
+            if (!pushed.ok)
+                return pushed;
+            const receipt = (deviceSha256, source, extra = []) => createAnalysisExecution({
                 client,
                 serial: input.serial,
                 local_path: localPath,
                 device_path: input.device_path,
                 bytes: digest.bytes,
                 sha256: digest.sha256,
-                device_sha256: digestMatch?.[1] ?? null,
+                device_sha256: deviceSha256,
                 overwritten: deviceExists,
-                device_digest_source: "device_sha256sum",
+                device_digest_source: source,
             }, provider, {
                 limitations: [
-                    "Push writes the caller's file to the device; this is the only device-mutating ADB tool",
+                    "Push writes a private snapshot of the caller's file to the device",
+                    ...extra,
                 ],
-            }));
-        }
-        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; this is the only device-mutating ADB tool",
-            ],
-        }));
+            });
+            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 cancelled = deviceDigest.error instanceof AnalysisCancelledError;
+                const completed = receipt(null, "unavailable", [
+                    cancelled
+                        ? "The device-side digest check was cancelled after push completed"
+                        : "The device did not answer sha256sum, so the transfer is not device-side verified",
+                ]);
+                if (cancelled)
+                    deviceDigest.error.retainPartialObservation(createEvidence(completed.subject ?? undefined, completed.provider, {
+                        operation,
+                        parameters: input,
+                        result: completed.result,
+                        rawResult: completed.rawResult,
+                        limitations: completed.limitations,
+                        locations: completed.locations,
+                        confidence: "observed",
+                    }));
+                return cancelled ? err(deviceDigest.error) : ok(completed);
+            }
+            const digestMatch = /^([a-f0-9]{64})\s/u.exec(deviceDigest.value.stdout);
+            const completed = receipt(digestMatch?.[1] ?? null, "device_sha256sum");
+            if (digestMatch !== null && digestMatch[1] !== digest.sha256)
+                return err(new AnalysisArtifactChangedError(operation, input.device_path, `The device-reported digest does not match the staged local file: ${localPath}`, {
+                    partialObservation: createEvidence(completed.subject ?? undefined, completed.provider, {
+                        operation,
+                        parameters: input,
+                        result: completed.result,
+                        rawResult: completed.rawResult,
+                        limitations: completed.limitations,
+                        locations: completed.locations,
+                        confidence: "observed",
+                    }),
+                }));
+            return ok(completed);
+        });
     }
     async installPackage(operation, selection, client, provider, input, signal) {
         const apkPath = resolve(input.apk_path);
@@ -959,45 +1575,54 @@ export class AdbProvider {
             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 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,
+        return this.#withRuntimeRoot(operation, {
             serial: input.serial,
             apk_path: apkPath,
-            bytes: digest.bytes,
-            sha256: digest.sha256,
-            replaced: input.replace,
-        }, provider, {
-            limitations: [
-                "Install changes device state; the installed APK's digest is the host file's digest",
-            ],
-        }));
+            replace: input.replace,
+        }, { prefix: "rea-adb-apk-" }, signal, async (root, resources) => {
+            const digest = await snapshotAdbInput(apkPath, root, resources, operation, signal);
+            const installed = await runAdb(operation, input.serial, selection.binary, adbArguments(input.serial, [
+                "install",
+                ...(input.replace ? ["-r"] : []),
+                digest.path,
+            ]), { 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 identifies the private host snapshot",
+                    "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]), {
+        const uninstalled = await runAdb(operation, input.serial, selection.binary, adbArguments(input.serial, [
+            "shell",
+            "pm",
+            "uninstall",
+            "--user",
+            "0",
+            input.package,
+        ]), {
             timeoutMs: PACKAGE_LIST_TIMEOUT_MS,
             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"));
@@ -1007,7 +1632,7 @@ export class AdbProvider {
             package_name: input.package,
         }, provider, {
             limitations: [
-                "Uninstall removes the package and its data for user 0; keeping data (-k) is not exposed",
+                "Uninstall explicitly requests user 0 without data retention (-k); device enforcement is not independently verified",
             ],
         }));
     }
@@ -1080,13 +1705,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,64 +1765,112 @@ 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);
+        if (signal?.aborted === true)
+            return err(new AnalysisCancelledError(operation, { cause: signal.reason }));
+        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" });
-        }
-        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");
-        return ok(createAnalysisExecution({
-            client,
-            serial: input.serial,
-            local_path: localPath,
-            bytes: captured.value.byteLength,
-            sha256,
-            width: dimensions.width,
-            height: dimensions.height,
-        }, provider, {
-            limitations: [
-                "The capture is one frame at read time; no recording or interaction occurred",
-            ],
-        }));
+        return this.#withRuntimeRoot(operation, { serial: input.serial, output_directory: directory.value }, { parent: directory.value, prefix: ".rea-screen-" }, signal, async (stage, resources) => {
+            let publicationCloseFailure;
+            let usedExclusiveFallback = false;
+            try {
+                const stagedPath = join(stage.path, "screen.png");
+                await writeFile(stagedPath, captured.value.stdout, { flag: "wx" });
+                await syncStagedAdbFile(stagedPath, resources, operation);
+                if (signal?.aborted === true)
+                    return err(new AnalysisCancelledError(operation, { cause: signal.reason }));
+                try {
+                    // A same-filesystem hard link atomically publishes without replacing
+                    // caller output. Its success is the publication cutoff.
+                    await link(stagedPath, localPath);
+                }
+                catch (cause) {
+                    if (!hardLinksUnsupported(cause))
+                        throw cause;
+                    // Exclusive creation prevents replacement, but makes the path
+                    // visible while the fallback writes the complete file.
+                    usedExclusiveFallback = true;
+                    publicationCloseFailure =
+                        (await publishScreenExclusively(localPath, captured.value.stdout, resources, operation, signal)) ?? undefined;
+                }
+            }
+            catch (cause) {
+                if (cause instanceof AnalysisError)
+                    return err(cause);
+                return err(new AnalysisOutputError(operation, `The screen output could not be published exclusively: ${localPath}`, { cause }));
+            }
+            const sha256 = createHash("sha256")
+                .update(captured.value.stdout)
+                .digest("hex");
+            const completed = 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",
+                    ...(usedExclusiveFallback
+                        ? [
+                            "The exclusive-create fallback makes the output path visible while its bytes are being written",
+                        ]
+                        : []),
+                ],
+            });
+            if (publicationCloseFailure !== undefined) {
+                const cleanupError = this.#cleanupError(operation, { serial: input.serial, output_directory: directory.value }, [publicationCloseFailure.cause], [publicationCloseFailure.resource], completed);
+                publicationCloseFailure.bindCleanupError(cleanupError);
+                return err(cleanupError);
+            }
+            return ok(completed);
+        });
     }
     async collectBugreport(operation, selection, client, provider, input, signal) {
         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 +1880,71 @@ 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, this.#resources);
+                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) {
+                const cleanupError = retainedObservation === undefined
+                    ? undefined
+                    : adbDigestError(cause, operation, retainedObservation);
+                if (cleanupError !== undefined)
+                    return err(cleanupError);
+                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 }));
             }
-            return err(new AnalysisOutputError(operation, `The reported bugreport archive could not be read back: ${reportedPath}`, { cause }));
+        })();
+        // 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);
+            return err(this.#retainOutputDirectoryCleanup({
+                operation,
+                path: stagingDirectory,
+                primary,
+                remove: () => removeOwnedOutputDirectory(stagingDirectory, stagingIdentity),
+            }, new ProviderCleanupError(ADB_PROVIDER_IDENTITY.id, [stagingDirectory], { reason: cause instanceof Error ? cause.message : String(cause) }, { operation, cause })));
         }
+        return collectedResult;
     }
 }