rea-agents 6.5.0 → 6.7.0

package/bridge/ghidra/ReaGhidraBridge.java

@@ -140,6 +140,7 @@ public final class ReaGhidraBridge extends HeadlessScript {
         "params"
     );
     private static final String[] CAPABILITIES = {
+        "read_binary_inventory_summary",
         "annotate_native_function",
         "set_address_name",
         "set_addresses_names",
@@ -427,6 +428,7 @@ public final class ReaGhidraBridge extends HeadlessScript {
             );
         }
         return switch (request.method) {
+            case "read_binary_inventory_summary" -> binaryInventorySummary(request.params);
             case "inspect_native_load_image" -> inspectNativeLoadImage(request.params);
             case "read_bytes" -> readMemoryBytes(request.params);
             case "search_bytes" -> searchMemoryBytes(request.params, descriptor);
@@ -934,7 +936,7 @@ public final class ReaGhidraBridge extends HeadlessScript {
             String value = decompiledText(decompile(function));
             JsonObject result = functionObservation(
                 value == null ? JsonNull.INSTANCE : GSON.toJsonTree(value),
-                noReturnCallLimitations(
+                functionBoundaryLimitations(
                     function,
                     currentProgram.getListing().getInstructions(function.getBody(), true)
                 )
@@ -1027,7 +1029,7 @@ public final class ReaGhidraBridge extends HeadlessScript {
         InstructionScan scan = scanInstructions(function, Integer.MAX_VALUE);
         return functionObservation(
             GSON.toJsonTree(renderAssembly(scan.instructions)),
-            noReturnCallLimitations(function, scan.instructions)
+            functionBoundaryLimitations(function, scan.instructions)
         );
     }
 
@@ -1046,7 +1048,7 @@ public final class ReaGhidraBridge extends HeadlessScript {
         limitations.add(
             "The fast path does not invoke the decompiler or scan whole-program names and strings."
         );
-        List<String> boundaryLimitations = noReturnCallLimitations(function, scan.instructions);
+        List<String> boundaryLimitations = functionBoundaryLimitations(function, scan.instructions);
         for (String limitation : boundaryLimitations) limitations.add(limitation);
         JsonObject result = new JsonObject();
         result.add("procedure", procedureIdentity(function));
@@ -1069,7 +1071,7 @@ public final class ReaGhidraBridge extends HeadlessScript {
             result.add(canonicalAddress(item.getEntryPoint()));
         }
         if (callers) {
-            JsonObject observation = functionObservation(result, noReturnCallLimitations(function,
+            JsonObject observation = functionObservation(result, functionBoundaryLimitations(function,
                 currentProgram.getListing().getInstructions(function.getBody(), true)
             ));
             observation.add("relationship_coverage", callRelationshipCoverage(null,
@@ -1099,7 +1101,7 @@ public final class ReaGhidraBridge extends HeadlessScript {
         result.add("classification", functionClassification(function));
         return functionObservation(
             result,
-            noReturnCallLimitations(
+            functionBoundaryLimitations(
                 function,
                 currentProgram.getListing().getInstructions(function.getBody(), true)
             )
@@ -1131,12 +1133,22 @@ public final class ReaGhidraBridge extends HeadlessScript {
         result.addProperty("direction", direction);
         result.add("references", edges);
         result.addProperty("reference_kinds_available", true);
-        JsonArray unresolvedCalls = direction.equals("outgoing")
-            ? callBoundaryObservation(
+        List<String> limitations;
+        JsonArray unresolvedCalls = new JsonArray();
+        if (direction.equals("outgoing")) {
+            CallBoundaryObservation calls = callBoundaryObservation(
                 function, currentProgram.getListing().getInstructions(function.getBody(), true), null, true, references
-            ).unresolvedCalls() : new JsonArray();
+            );
+            unresolvedCalls = calls.unresolvedCalls();
+            limitations = calls.limitations();
+        } else {
+            limitations = functionBoundaryLimitations(
+                function,
+                currentProgram.getListing().getInstructions(function.getBody(), true)
+            );
+        }
         result.add("unresolved_calls", unresolvedCalls);
-        return result;
+        return functionObservation(result, limitations);
     }
 
     private JsonObject inspectNativeDataType(JsonObject params) throws Exception {
@@ -1337,11 +1349,7 @@ public final class ReaGhidraBridge extends HeadlessScript {
         result.add("references", references);
         if (includeIncoming) {
             TreeMap<String, Reference> incoming = new TreeMap<>();
-            ReferenceIterator incomingIterator = currentProgram.getReferenceManager().getReferencesTo(address);
-            while (incomingIterator.hasNext()) {
-                monitor.checkCancelled();
-                addReference(incoming, incomingIterator.next());
-            }
+            visitObservedReferencesTo(address, reference -> addReference(incoming, reference));
             List<Reference> orderedIncoming = new ArrayList<>(incoming.values());
             orderedIncoming.sort(REFERENCE_ORDER);
             JsonArray incomingReferences = new JsonArray();
@@ -1393,16 +1401,8 @@ public final class ReaGhidraBridge extends HeadlessScript {
         requireKeys(params, Set.of("document", "address"));
         requireDocument(params);
         Address address = requireAddress(params, "address");
-        ReferenceIterator references = currentProgram.getReferenceManager().getReferencesTo(address);
         Set<Address> sources = new HashSet<>();
-        while (references.hasNext()) {
-            monitor.checkCancelled();
-            Reference reference = references.next();
-            if (reference.isEntryPointReference()) {
-                continue;
-            }
-            sources.add(reference.getFromAddress());
-            }
+        visitObservedReferencesTo(address, reference -> sources.add(reference.getFromAddress()));
         List<Address> ordered = new ArrayList<>(sources);
         ordered.sort(Address::compareTo);
         JsonArray result = new JsonArray();
@@ -1976,6 +1976,18 @@ public final class ReaGhidraBridge extends HeadlessScript {
         return result;
     }
 
+    private JsonObject binaryInventorySummary(JsonObject params) throws Exception {
+        requireKeys(params, Set.of());
+        JsonObject result = new JsonObject();
+        result.addProperty("document", currentProgram.getName());
+        result.add("segments", segments());
+        // Count the owning inventories, preserving their exact discovery rules
+        // without serializing function identities or string values for counts.
+        result.addProperty("procedure_count", procedures().size());
+        result.addProperty("string_count", strings().size());
+        return result;
+    }
+
     private JsonArray listNames(JsonObject params) throws Exception {
         requireKeys(params, Set.of("document", "address"));
         requireDocument(params);
@@ -2002,6 +2014,10 @@ public final class ReaGhidraBridge extends HeadlessScript {
     private JsonArray listSegments(JsonObject params) {
         requireKeys(params, Set.of("document"));
         requireDocument(params);
+        return segments();
+    }
+
+    private JsonArray segments() {
         JsonArray result = new JsonArray();
         String imageBase = canonicalAddress(currentProgram.getImageBase());
         MemoryBlock[] blocks = currentProgram.getMemory().getBlocks();
@@ -3430,51 +3446,27 @@ public final class ReaGhidraBridge extends HeadlessScript {
         return omitted[0];
     }
 
-    private List<String> noReturnCallLimitations(
+    private List<String> functionBoundaryLimitations(
             Function function, Iterable<Instruction> instructions)
             throws Exception {
-        List<String> limitations = new ArrayList<>();
-        Instruction beforePrevious = null;
-        Instruction previous = null;
-        for (Instruction instruction : instructions) {
-            monitor.checkCancelled();
-            String limitation = terminalCallLimitation(instruction);
-            if (limitation != null) limitations.add(limitation);
-            if (beforePrevious != null && previous != null) {
-                String seh = borlandSehHandlerLimitation(
-                    function, beforePrevious, previous, instruction);
-                if (seh != null) limitations.add(seh);
-            }
-            beforePrevious = previous;
-            previous = instruction;
-        }
-        return limitations;
+        FunctionBoundaryLimitations boundary = new FunctionBoundaryLimitations(function);
+        for (Instruction instruction : instructions) boundary.observe(instruction);
+        return boundary.values();
     }
 
     private CallBoundaryObservation callBoundaryObservation(
             Function function, Iterable<Instruction> instructions, Set<Function> returnedCallees,
             boolean includeUnresolvedSites, List<Reference> observedReferences)
             throws Exception {
-        List<String> limitations = new ArrayList<>();
+        FunctionBoundaryLimitations boundary = new FunctionBoundaryLimitations(function);
         CallBoundaryReferences calls = new CallBoundaryReferences(returnedCallees, includeUnresolvedSites);
-        Instruction beforePrevious = null;
-        Instruction previous = null;
         if (observedReferences == null) visitReferences(function, "outgoing", calls::observe);
         else for (Reference reference : observedReferences) {
             monitor.checkCancelled();
             calls.observe(reference);
         }
         for (Instruction instruction : instructions) {
-            monitor.checkCancelled();
-            String limitation = terminalCallLimitation(instruction);
-            if (limitation != null) limitations.add(limitation);
-            if (beforePrevious != null && previous != null) {
-                String seh = borlandSehHandlerLimitation(
-                    function, beforePrevious, previous, instruction);
-                if (seh != null) limitations.add(seh);
-            }
-            beforePrevious = previous;
-            previous = instruction;
+            boundary.observe(instruction);
             if (!instruction.getFlowType().isCall()) continue;
             boolean destination = false;
             for (Reference reference : instruction.getReferencesFrom()) {
@@ -3488,10 +3480,38 @@ public final class ReaGhidraBridge extends HeadlessScript {
                     "Instruction decoder identifies a call but ReferenceManager supplies no call destination");
             }
         }
-        return new CallBoundaryObservation(List.copyOf(limitations),
+        return new CallBoundaryObservation(boundary.values(),
             returnedCallees == null ? null : calls.unrepresented, calls.unresolvedCalls());
     }
 
+    private final class FunctionBoundaryLimitations {
+        private final Function function;
+        private final List<String> limitations = new ArrayList<>();
+        private Instruction beforePrevious;
+        private Instruction previous;
+
+        private FunctionBoundaryLimitations(Function function) {
+            this.function = function;
+        }
+
+        private void observe(Instruction instruction) throws Exception {
+            monitor.checkCancelled();
+            String limitation = terminalCallLimitation(instruction);
+            if (limitation != null) limitations.add(limitation);
+            if (beforePrevious != null && previous != null) {
+                String seh = borlandSehHandlerLimitation(
+                    function, beforePrevious, previous, instruction);
+                if (seh != null) limitations.add(seh);
+            }
+            beforePrevious = previous;
+            previous = instruction;
+        }
+
+        private List<String> values() {
+            return List.copyOf(limitations);
+        }
+    }
+
     private String borlandSehHandlerLimitation(
             Function function, Instruction handlerPush, Instruction framePush,
             Instruction frameLink) {
@@ -3673,24 +3693,36 @@ public final class ReaGhidraBridge extends HeadlessScript {
             monitor.checkCancelled();
             Address address = addresses.next();
             if (outgoing) {
-                for (Reference reference : currentProgram.getReferenceManager()
-                        .getReferencesFrom(address)) {
-                    monitor.checkCancelled();
-                    if (!reference.isEntryPointReference()) visitor.accept(reference);
-                }
+                visitObservedReferencesFrom(address, visitor);
             }
             else {
-                ReferenceIterator iterator = currentProgram.getReferenceManager()
-                    .getReferencesTo(address);
-                while (iterator.hasNext()) {
-                    monitor.checkCancelled();
-                    Reference reference = iterator.next();
-                    if (!reference.isEntryPointReference()) visitor.accept(reference);
-                }
+                visitObservedReferencesTo(address, visitor);
             }
         }
     }
 
+    private void visitObservedReferencesFrom(Address address, ReferenceVisitor visitor)
+            throws Exception {
+        for (Reference reference : currentProgram.getReferenceManager().getReferencesFrom(address)) {
+            monitor.checkCancelled();
+            visitObservedReference(reference, visitor);
+        }
+    }
+
+    private void visitObservedReferencesTo(Address address, ReferenceVisitor visitor)
+            throws Exception {
+        ReferenceIterator references = currentProgram.getReferenceManager().getReferencesTo(address);
+        while (references.hasNext()) {
+            monitor.checkCancelled();
+            visitObservedReference(references.next(), visitor);
+        }
+    }
+
+    private static void visitObservedReference(Reference reference, ReferenceVisitor visitor)
+            throws Exception {
+        if (!reference.isEntryPointReference()) visitor.accept(reference);
+    }
+
     private static void addReference(TreeMap<String, Reference> observed, Reference reference) {
         String key = canonicalAddress(reference.getFromAddress()) + "\u0000" +
             canonicalAddress(reference.getToAddress()) + "\u0000" +

package/bridge/hopper_bridge.py

@@ -1057,6 +1057,10 @@ def _serve_connection(connection):
                 ):
                     raise PermissionError("Invalid bridge capability")
                 authenticated = True
+                # The connection grace period only bounds unauthenticated idle
+                # clients. Native analysis and a connected owner's idle time
+                # remain unbounded after capability validation.
+                connection.settimeout(None)
                 _write_message(file, {"id": request_id, "event": {
                     "type": "progress",
                     "phase": "hopper_bridge",
@@ -1148,13 +1152,17 @@ def _run():
     server.bind(REA_SOCKET)
     os.chmod(REA_SOCKET, 0o600)
     server.listen(1)
+    # A bridge can start after its caller's startup/cleanup deadline. Bound
+    # the first accept as well as reconnects so an orphan cannot pin Hopper's
+    # dedicated Python thread and prevent later documents from starting REA.
+    server.settimeout(REA_RECONNECT_TIMEOUT_SECONDS)
     try:
         while True:
             try:
                 connection, _ = server.accept()
             except socket.timeout:
                 break
-            connection.settimeout(None)
+            connection.settimeout(REA_RECONNECT_TIMEOUT_SECONDS)
             if _serve_connection(connection):
                 break
             # Match REA's cleanup handshake budget without pinning Hopper's

package/bridge/native/rea_lldb_tracer.py

@@ -555,6 +555,38 @@ def _failed_launch_description(process):
     return None
 
 
+def _retire_failed_launch(process, config, listener, stdout, stderr):
+    """Reconcile an SBProcess returned alongside a failed Launch error."""
+    if not process.IsValid():
+        stdout.close()
+        stderr.close()
+        return False
+
+    pid = process.GetProcessID()
+    if pid > 0:
+        # Even an already-exited process needs its PID published so the host
+        # can distinguish a completed launch failure from an unknown target.
+        with open(config["pid_path"], "w") as handle:
+            handle.write(str(pid))
+
+    if process.GetState() != lldb.eStateExited:
+        stdout.mark_launched()
+        stderr.mark_launched()
+        if pid > 0:
+            # Hold a surviving target until the host has captured its start
+            # identity. If that proof is unavailable, Kill still addresses
+            # this exact SBProcess created by the current launch request.
+            _wait_for_identity_ack(config)
+        process.Kill()
+        _wait_for_exit(listener, process, 5)
+
+    exit_observed = process.GetState() == lldb.eStateExited
+    expected_exit = exit_observed
+    stdout.close(expected_exit=expected_exit)
+    stderr.close(expected_exit=expected_exit)
+    return exit_observed
+
+
 def trace(debugger, config):
     global _TRACE_CONTEXT
     debugger.SetAsync(True)
@@ -630,8 +662,9 @@ def trace(debugger, config):
             )
         process = target.Launch(_launch_info(target, config, listener), error)
         if not error.Success() or not process.IsValid():
-            stdout.close()
-            stderr.close()
+            exit_observed = _retire_failed_launch(
+                process, config, listener, stdout, stderr
+            )
             return {
                 "status": "launch-error",
                 "error": error.GetCString(),
@@ -640,15 +673,26 @@ def trace(debugger, config):
                     if process.IsValid()
                     else {}
                 ),
+                **(
+                    {"target_process_exit_observed": True}
+                    if exit_observed
+                    else {}
+                ),
             }
         launch_failure = _failed_launch_description(process)
         if launch_failure is not None:
-            stdout.close(expected_exit=True)
-            stderr.close(expected_exit=True)
+            exit_observed = _retire_failed_launch(
+                process, config, listener, stdout, stderr
+            )
             return {
                 "status": "launch-error",
                 "error": launch_failure,
                 "target_process_created": True,
+                **(
+                    {"target_process_exit_observed": True}
+                    if exit_observed
+                    else {}
+                ),
             }
         stdout.mark_launched()
         stderr.mark_launched()

package/bridge/pwndbg/core_context.py

@@ -20,8 +20,9 @@ def inspect(request):
     root = Path(os.environ["REA_CORE_CONTEXT_REQUEST"]).parent
     empty = root / "no-libraries"
     empty.mkdir(mode=0o700)
-    for command in ["set auto-load off", "set debuginfod enabled off", "set auto-solib-add off", "set history save off", "set pagination off",
-                    "set sysroot ./no-libraries", "set solib-search-path ./no-libraries"]:
+    for command in ["set auto-load off", "set debuginfod enabled off", "set auto-solib-add off", "set history save off", "set pagination off", "set target-file-system-kind unix",
+                    "set sysroot ./no-libraries", "set solib-search-path ./no-libraries",
+                    "set debug-file-directory ./no-libraries"]:
         gdb.execute(command, to_string=True)
     entry = request["gdbinit"]
     try:
@@ -38,7 +39,19 @@ def inspect(request):
     # relative filename in the owned cwd so no selected path becomes GDB syntax.
     if Path(request["snapshot_path"]) != root.parent / "object.snapshot":
         raise ContextFailure("decoder", "Core context request did not select the shared owned snapshot.")
+    # GDB 16 searches AT_EXECFN/NT_FILE outside sysroot when no executable BFD
+    # is selected. Occupy that slot with the already running, owned debugger;
+    # exec-file loads no symbols and never runs it. Clear it before any query.
+    # /proc/self/exe identifies this process, not the core's historical PID.
+    architecture = {"x86_64-little-endian": "i386:x86-64", "aarch64-little-endian": "aarch64"}.get(request["architecture"])
+    if architecture is None:
+        raise ContextFailure("unsupported", "Unsupported recorded core architecture.")
+    gdb.execute("exec-file /proc/self/exe", to_string=True)
+    # The placeholder must not select the core's architecture. Reuse the
+    # decoder's validated profile, including for cross-architecture GDB builds.
+    gdb.execute("set architecture " + architecture, to_string=True)
     gdb.execute("core-file ../object.snapshot", to_string=True)
+    gdb.execute("file", to_string=True)
     inferior = gdb.selected_inferior()
     if inferior.connection is None or inferior.connection.type != "core" or gdb.current_progspace().filename is not None:
         raise ContextFailure("decoder", "Requested core-only boundary was not established; no mapping query performed.")

package/dist/adb/AdbCommand.js

@@ -0,0 +1,148 @@
+import { AnalysisCancelledError, AnalysisProtocolError, AnalysisResourceConstraintError, AnalysisTimeoutError, AnalysisUnsupportedTargetError, } from "../domain/analysisErrorCore.js";
+import { err, ok } from "../domain/result.js";
+import { execFileBytes, ExecFileOutputCancelledError, execFileOutputFailure, } from "../process/ExecFileOutput.js";
+import { packageChangeFailureReason } from "./AdbShellOutput.js";
+const STDERR_EXCERPT_BYTES = 512;
+/** Project parsed command-owner facts without reinterpreting the rejection. */
+export const adbCommandCapturedOutput = (failure) => ({
+    stdout: failure.stdout,
+    stderr: failure.stderr,
+    ...(failure.stdoutBytes === undefined
+        ? {}
+        : { stdout_bytes: failure.stdoutBytes }),
+    ...(failure.stderrBytes === undefined
+        ? {}
+        : { stderr_bytes: failure.stderrBytes }),
+    exit_code: typeof failure.code === "number" ? failure.code : null,
+    signal: failure.signal,
+    truncated: failure.outputTruncated,
+});
+/** Parsed command failure owned by this adapter, separate from its public tag. */
+class AdbProtocolError extends AnalysisProtocolError {
+    commandFailure;
+    constructor(message, commandFailure, cause) {
+        super(message, { cause });
+        this.commandFailure = commandFailure;
+    }
+}
+/** 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("'", "'\\''") + "'";
+export const adbArguments = (serial, arguments_) => {
+    const operands = arguments_[0] === "shell"
+        ? ["shell", ...arguments_.slice(1).map(quoteShellOperand)]
+        : [...arguments_];
+    return serial === undefined ? operands : ["-s", serial, ...operands];
+};
+/** Run one bounded adb invocation and keep its exact failure shape. */
+export const runAdbCapture = async (operation, targetPath, binary, arguments_, limits, signal) => {
+    if (signal?.aborted === true)
+        return err(new AnalysisCancelledError(operation, { cause: signal.reason }));
+    try {
+        return ok(await execFileBytes(binary, arguments_, {
+            timeout: limits.timeoutMs,
+            maxBuffer: limits.maxOutputBytes,
+            stopSignal: "SIGTERM",
+            ...(signal === undefined ? {} : { signal }),
+        }));
+    }
+    catch (cause) {
+        const failure = execFileOutputFailure(cause);
+        if (cause instanceof ExecFileOutputCancelledError)
+            return err(new AnalysisCancelledError(operation, {
+                cause: cause.cause,
+                ...(failure === undefined
+                    ? {}
+                    : { capturedOutput: adbCommandCapturedOutput(failure) }),
+            }));
+        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 AdbProtocolError(excerpt === ""
+            ? `adb exited with code ${String(failure.code)} for ${operation}`
+            : excerpt, failure, cause));
+    }
+};
+/** Decode textual adb protocols after the shared byte capture and error boundary. */
+export const runAdb = async (...arguments_) => {
+    const captured = await runAdbCapture(...arguments_);
+    if (!captured.ok)
+        return captured;
+    return ok({
+        stdout: captured.value.stdout.toString("utf8"),
+        stderr: captured.value.stderr.toString("utf8"),
+        // Byte count of the captured output before UTF-8 decoding, so malformed
+        // sequences replaced by U+FFFD still report their true captured size.
+        stdoutBytes: captured.value.stdout.byteLength,
+    });
+};
+/**
+ * adb exits nonzero when the device refuses a package change, printing the
+ * `Failure [...]` verdict to stderr (install) or stdout (uninstall). Read the
+ * refusal from that failed run so it is not reported as unreadable output.
+ */
+export const packageChangeRefusal = (operation, serial, error) => {
+    if (!(error instanceof AdbProtocolError))
+        return undefined;
+    const failure = error.commandFailure;
+    const reason = packageChangeFailureReason(`${failure.stdout}\n${failure.stderr}`);
+    return reason === null
+        ? undefined
+        : err(new AnalysisUnsupportedTargetError(operation, serial, reason, {
+            cause: error,
+        }));
+};
+/** Only the clean false result of test -e establishes absence. */
+export const probeAdbPathExistence = async (operation, serial, path, binary, limits, signal) => {
+    const probed = await runAdbCapture(operation, path, binary, adbArguments(serial, ["shell", "test", "-e", path]), limits, signal);
+    if (probed.ok) {
+        if (probed.value.stdout.length === 0 && probed.value.stderr.length === 0)
+            return ok(true);
+        return err(new AnalysisProtocolError("The ADB path existence probe returned unexpected output; destination existence is unknown", {
+            diagnostics: { destination_existence: "unknown" },
+            capturedOutput: {
+                stdout: probed.value.stdout.toString("utf8"),
+                stderr: probed.value.stderr.toString("utf8"),
+                stdout_bytes: probed.value.stdout.length,
+                stderr_bytes: probed.value.stderr.length,
+                exit_code: 0,
+                signal: null,
+                truncated: false,
+            },
+        }));
+    }
+    const error = probed.error;
+    if (!(error instanceof AdbProtocolError))
+        return probed;
+    const failure = error.commandFailure;
+    if (failure.code === 1 &&
+        failure.signal === null &&
+        !failure.killed &&
+        !failure.outputTruncated &&
+        failure.collectionFailure !== true &&
+        failure.stdout === "" &&
+        failure.stderr === "")
+        return ok(false);
+    return err(new AnalysisProtocolError(error.message, {
+        cause: error.cause,
+        diagnostics: { destination_existence: "unknown" },
+        capturedOutput: adbCommandCapturedOutput(failure),
+    }));
+};

package/dist/adb/AdbConfiguration.js

@@ -1,6 +1,7 @@
-import { AnalysisCancelledError } from "../domain/analysisErrorCore.js";
+import { AnalysisCancelledError, AnalysisResourceConstraintError, AnalysisTimeoutError, } from "../domain/analysisErrorCore.js";
 import { isAbsolute } from "node:path";
-import { execFileOutput, execFileOutputFailure, } from "../process/ExecFileOutput.js";
+import { execFileOutput, ExecFileOutputCancelledError, execFileOutputFailure, } from "../process/ExecFileOutput.js";
+import { adbCommandCapturedOutput } from "./AdbCommand.js";
 /** Environment key selecting the caller's adb binary. */
 export const ADB_BINARY_ENV = "REA_ADB_PATH";
 const VERSION_TIMEOUT_MS = 10_000;
@@ -67,8 +68,29 @@ export const inspectAdbClient = async (selection, signal) => {
         if (cause instanceof AdbConfigurationFailure)
             throw cause;
         const failure = execFileOutputFailure(cause);
-        if (signal?.aborted || failure?.code === "ABORT_ERR")
-            throw new AnalysisCancelledError("inspect_adb_client", { cause });
+        if (cause instanceof ExecFileOutputCancelledError)
+            throw new AnalysisCancelledError("inspect_adb_client", {
+                cause: cause.cause,
+                ...(failure === undefined
+                    ? {}
+                    : { capturedOutput: adbCommandCapturedOutput(failure) }),
+            });
+        const diagnostics = {
+            selected_binary: selection.binary,
+            path_source: selection.pathSource,
+            ...(failure === undefined ? {} : { exit_code: failure.code }),
+        };
+        const options = {
+            cause,
+            diagnostics,
+            ...(failure === undefined
+                ? {}
+                : { capturedOutput: adbCommandCapturedOutput(failure) }),
+        };
+        if (failure?.outputTruncated === true)
+            throw new AnalysisResourceConstraintError("inspect_adb_client", "memory", `adb version output exceeded the ${String(VERSION_MAX_OUTPUT_BYTES)}-byte capture budget`, { max_output_bytes: VERSION_MAX_OUTPUT_BYTES }, options);
+        if (failure?.code === "ETIMEDOUT")
+            throw new AnalysisTimeoutError("inspect_adb_client", VERSION_TIMEOUT_MS, options);
         if (failure?.code === "ENOENT")
             throw new AdbConfigurationFailure("binary_missing", `The selected adb binary was not found: ${selection.binary}`, {
                 selected_binary: selection.binary,