rea-agents 6.1.0 → 6.3.0

package/README.md

@@ -1,6 +1,6 @@
 <div align="center">
 
-**English** · [简体中文](README_zh.md) · [繁體中文](README_zh-TW.md) · [日本語](README_ja.md) · [한국어](README_ko.md) · [Türkçe](README_tr.md) · [Русский](README_ru.md) · [Tiếng Việt](README_vi.md) · [ไทย](README_th.md) · [Deutsch](README_de.md) · [Español](README_es.md) · [Українська](README_uk.md) · [Polski](README_pl.md) · [Português (Brasil)](README_pt-BR.md) · [العربية](README_ar.md) · [فارسی](README_fa.md)
+**English** · [简体中文](README_zh.md) · [繁體中文](README_zh-TW.md) · [日本語](README_ja.md) · [한국어](README_ko.md) · [Türkçe](README_tr.md) · [Русский](README_ru.md) · [Tiếng Việt](README_vi.md) · [ไทย](README_th.md) · [Deutsch](README_de.md) · [Español](README_es.md) · [Français](README_fr.md) · [Українська](README_uk.md) · [Polski](README_pl.md) · [Português (Brasil)](README_pt-BR.md) · [العربية](README_ar.md) · [فارسی](README_fa.md)
 
 # REA: Reverse Engineer Anything
 
@@ -11,7 +11,7 @@
 [![npm version](https://img.shields.io/npm/v/rea-agents?style=flat-square&color=cb3837)](https://www.npmjs.com/package/rea-agents)
 [![CI](https://img.shields.io/github/actions/workflow/status/morluto/rea/ci.yml?branch=main&style=flat-square&label=CI)](https://github.com/morluto/rea/actions/workflows/ci.yml)
 [![MCP tool catalog](https://img.shields.io/badge/MCP-tool_catalog-5c4ee5?style=flat-square)](docs/mcp-contracts.md#generated-catalog)
-[![Node.js 22+](https://img.shields.io/badge/Node.js-22.19%2B-339933?style=flat-square&logo=nodedotjs&logoColor=white)](https://nodejs.org/)
+[![Node.js requirements](https://img.shields.io/badge/Node.js-requirements-339933?style=flat-square&logo=nodedotjs&logoColor=white)](#what-you-can-analyze)
 [![skills.sh](https://skills.sh/b/morluto/rea?style=flat-square)](https://skills.sh/morluto/rea/reverse-engineer-anything)
 [![MIT license](https://img.shields.io/badge/license-MIT-f4c430?style=flat-square)](LICENSE)
 [![Discord](https://img.shields.io/discord/1556595354999332884?logo=discord&logoColor=white&label=Discord&color=5865F2)](https://discord.gg/GkcryMnJDM)
@@ -28,7 +28,7 @@
 
 <img src="docs/assets/rea-hopper-analysis.png" alt="REA launching its analysis bridge inside Hopper while inspecting a native binary" width="1200" />
 
-<br />
+<br /><br />
 
 <table aria-label="REA community">
 <tr>
@@ -52,7 +52,7 @@ See a feature in an app that you want in your own product? Ask your agent to inv
 
 REA connects your agent to tools for inspecting native binaries, JavaScript and Electron apps, .NET assemblies, and websites. You can also use the same tools from your terminal. Analysis runs locally, and results include the evidence and limitations behind each conclusion.
 
-Setup registers REA with your agent and installs matching workflow instructions. Native analysis can use an existing Hopper or Ghidra installation; setup can optionally install Hopper with approval. Static JavaScript analysis needs neither engine.
+Setup registers REA with your agent and installs matching workflow instructions. Native analysis can use an existing Hopper, Ghidra, or IDA installation; setup can optionally install Hopper with approval. Static JavaScript analysis needs no native analysis engine.
 
 > **[Visit the REA website](https://rea.tools/)** for setup instructions, illustrated guides, and real case studies.
 
@@ -156,8 +156,8 @@ Additional tools and host support depend on the target:
 | JavaScript / Electron  | Modules, imports, source maps, routes, IPC and native add-on relationships           | Node.js and npm; [application analysis](https://rea.tools/guides/javascript/)                                                         |
 | Websites               | Page structure, scripts, network observations and requested screenshots              | A Chrome-family browser; [browser analysis](https://rea.tools/guides/browser/)                                                        |
 | Saved network captures | Requests, responses, exposed payloads and source locations                           | HAR; mitmdump on Linux for native mitmproxy captures; [capture guide](docs/web-network-captures.md)                                   |
-| .NET assemblies        | Metadata, CIL instructions, declared native dependencies and build comparisons       | Static inspection; [managed-code guide](docs/managed-code-analysis.md)                                                                |
-| Android APKs           | Manifest declarations, classes, decompiled methods and references                    | Headless JADX and a full JDK on Linux/macOS; [Android guide](docs/android-analysis.md)                                                |
+| .NET assemblies        | Metadata, CIL instructions, declared native dependencies and build comparisons       | None (static only); [managed-code guide](docs/managed-code-analysis.md)                                                               |
+| Android APKs           | Manifest declarations, classes, decompiled methods and references                    | Headless JADX and a full JDK on Linux/macOS/Windows x64; [Android guide](docs/android-analysis.md)                                    |
 | Firmware               | Regions, extraction results and native-analysis handoffs                             | Binwalk / Unblob on Linux; [firmware guide](docs/firmware-analysis.md)                                                                |
 | Packages and resources | File inventories, digests, plists, Apple bundle anatomy and extracted resources      | [Artifact and JavaScript guide](docs/javascript-artifact-reconstruction.md), [Apple applications](docs/apple-application-analysis.md) |
 | Process behavior       | Terminal output, interactions, exit and filesystem observations, and run comparisons | Linux/macOS with a native PTY; [process capture](docs/process-capture.md)                                                             |
@@ -181,6 +181,8 @@ for features added since the latest npm release.
 
 ## Showcases
 
+[![Illustrations of the DX-Ball sound-pan, Notion clipboard-bridge, and TH04 bullet-ring showcases](docs/assets/rea-showcases.png)](https://rea.tools/showcase/)
+
 ### DX-Ball: reconstruct a sound-pan calculation
 
 Follow a sound call into its position-to-pan helper, inspect the instructions,
@@ -243,7 +245,7 @@ ask you to choose demo mode or activate your license. See
 <details>
 <summary><strong>What does installing the skill from skills.sh do?</strong></summary>
 
-The skill supplies investigation instructions for your agent. Use `rea setup`
+The skill supplies investigation instructions for your agent. Use `npx rea-agents setup`
 to register REA's MCP server and install the matching instructions, then restart
 your agent. See [skill-only installation](docs/installation.md#skill-only-installation).
 
@@ -298,30 +300,16 @@ For exact options, prerequisites and result contracts:
 - [Readiness and troubleshooting](docs/installation.md#check-readiness-for-your-task): diagnose one agent or analysis engine.
 - [CLI and Evidence](docs/cli.md): commands, provider selection, snapshots, import/export and exit statuses.
 - [MCP contracts](docs/mcp-contracts.md) and [agent prompts](docs/mcp-prompts.md): tool results, sessions and guided investigations.
-- [Tool catalog](docs/mcp-contracts.md#generated-catalog): build-generated inventory of tools, providers and CLI commands.
+- [Tool catalog](docs/mcp-contracts.md#generated-catalog): generated inventory of tools, providers and CLI commands.
 - [Roadmap](docs/roadmap.md): planned work and capability trackers.
 
 Report vulnerabilities through [SECURITY.md](SECURITY.md).
 
-## Contributing
-
-We'd love your help with REA! [Open an issue](https://github.com/morluto/rea/issues) to
-report a bug or suggest a feature, or [send a pull request](https://github.com/morluto/rea/pulls)
-to improve the code or docs.
-
-See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and checks,
-[testing](docs/testing.md) for verification lanes, and the
-[architecture map](docs/architecture.mermaid) for the project structure.
-
-## Project links
-
-[Website](https://rea.tools/) · [npm](https://www.npmjs.com/package/rea-agents) · [skills.sh](https://skills.sh/morluto/rea/reverse-engineer-anything) · [Issues](https://github.com/morluto/rea/issues) · [Security](SECURITY.md)
-
 ## Star history
 
-🎉 **20,000 GitHub stars — thank you!**
+🎉 **40,000 GitHub stars — thank you!**
 
-Thanks to everyone using REA, reporting bugs, testing builds, and contributing fixes.
+Thanks to everyone using REA, reporting bugs, requesting features, testing builds, and contributing fixes.
 
 <a href="https://www.star-history.com/?repos=morluto%2Frea&amp;type=date">
   <picture>
@@ -335,6 +323,18 @@ Thanks to everyone using REA, reporting bugs, testing builds, and contributing f
 
 REA provides tools for lawful reverse-engineering research, analysis, and reconstruction. You are responsible for obtaining any required authorization and complying with applicable laws. The project does not endorse illegal or unauthorized use.
 
+REA is an open-source software project. We have not issued or endorsed any cryptocurrency or token. Tokens using the REA name are not affiliated with the project.
+
+## Contributing
+
+We'd love your help with REA! [Open an issue](https://github.com/morluto/rea/issues) to
+report a bug or suggest a feature, or [send a pull request](https://github.com/morluto/rea/pulls)
+to improve the code or docs.
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and checks,
+[testing](docs/testing.md) for verification lanes, and the
+[architecture map](docs/architecture.mermaid) for the project structure.
+
 ## License
 
 [MIT](LICENSE)

package/bridge/ghidra/ReaGhidraBridge.java

@@ -866,6 +866,7 @@ public final class ReaGhidraBridge extends HeadlessScript {
         JsonArray operands = new JsonArray();
         JsonArray references = new JsonArray();
         JsonArray destinations = new JsonArray();
+        JsonArray flowEvidence = new JsonArray();
         JsonObject flow = new JsonObject();
         flow.addProperty("kind", "unavailable");
         flow.addProperty("conditional", false);
@@ -881,7 +882,20 @@ public final class ReaGhidraBridge extends HeadlessScript {
             result.addProperty("mnemonic", instruction.getMnemonicString());
             result.addProperty("raw_disassembly", instruction.toString());
             RefType type = instruction.getFlowType();
-            flow.addProperty("kind", type.isCall() ? "call" : type.isJump() ? "jump" : type.isTerminal() ? "terminal" : "fallthrough");
+            JsonObject listingFlow = new JsonObject();
+            listingFlow.addProperty("source", "ghidra-listing-flow-type");
+            listingFlow.addProperty("value", type.getName());
+            flowEvidence.add(listingFlow);
+            boolean decodedReturn = false;
+            for (PcodeOp operation : instruction.getPcode()) {
+                if (operation.getOpcode() != PcodeOp.RETURN) continue;
+                decodedReturn = true;
+                JsonObject returnEvidence = new JsonObject();
+                returnEvidence.addProperty("source", "ghidra-instruction-pcode");
+                returnEvidence.addProperty("value", operation.getMnemonic());
+                flowEvidence.add(returnEvidence);
+            }
+            flow.addProperty("kind", type.isCall() ? "call" : type.isJump() ? "jump" : decodedReturn ? "return" : type.isTerminal() ? "terminal" : "fallthrough");
             flow.addProperty("conditional", type.isConditional());
             flow.addProperty("computed", type.isComputed());
             if (!type.isComputed()) for (Address target : instruction.getFlows()) destinations.add(canonicalAddress(target));
@@ -917,10 +931,13 @@ public final class ReaGhidraBridge extends HeadlessScript {
             }
         }
         flow.add("direct_destinations", destinations);
+        flow.add("classification_evidence", flowEvidence);
         result.add("operands", operands);
         result.add("flow", flow);
         result.add("references", references);
-        result.add("limitations", GSON.toJsonTree(List.of("Operand components are Ghidra Listing decoder tokens; effective memory base/index/displacement roles and per-instruction context mode are unavailable. The mode field is the program language variant.", "Terminal flow is not classified as a return without provider evidence.")));
+        List<String> limitations = new ArrayList<>(List.of("Operand components are Ghidra Listing decoder tokens; effective memory base/index/displacement roles and per-instruction context mode are unavailable. The mode field is the program language variant."));
+        if (flow.get("kind").getAsString().equals("terminal")) limitations.add("No RETURN operation was observed in the provider's instruction p-code; terminal classification remains generic.");
+        result.add("limitations", GSON.toJsonTree(limitations));
         return result;
     }
 
@@ -1629,9 +1646,20 @@ public final class ReaGhidraBridge extends HeadlessScript {
                 Function function = entry.function;
                 Symbol symbol = function.getSymbol();
                 String qualified = symbol == null ? function.getName() : symbol.getName(true);
-                if (function.getName().equals(value) || qualified.equals(value)) {
-                    matches.add(function);
+                boolean matchesName = function.getName().equals(value) || qualified.equals(value);
+                if (!matchesName) {
+                    // Imported labels (for example Mach-O _main) can share a
+                    // function entry without becoming its primary symbol. Only
+                    // exact entries qualify; an interior label is not a selector.
+                    for (Symbol entrySymbol : currentProgram.getSymbolTable().getSymbols(function.getEntryPoint())) {
+                        monitor.checkCancelled();
+                        if (entrySymbol.getName().equals(value) || entrySymbol.getName(true).equals(value)) {
+                            matchesName = true;
+                            break;
+                        }
+                    }
                 }
+                if (matchesName) matches.add(function);
             }
             if (matches.size() > 1)
                 throw new RequestFailure("ambiguous", "Ghidra procedure name is ambiguous: " + value +

package/bridge/hopper_bridge.py

@@ -553,7 +553,12 @@ def _search_results(document, kind, params):
         if not matches(item[1]):
             continue
         selected.append(item)
-    return [{"address": address, **_string_inventory(document)[address]} for address, _ in selected] if kind == "string" else [
+    if not selected:
+        return []
+    if kind == "string":
+        records = _string_inventory(document)
+        return [{"address": address, **records[address]} for address, _ in selected]
+    return [
             {
                 "address": address,
                 "value": value,
@@ -711,6 +716,8 @@ def _analyze_function(document, params):
         "referenced_strings": referenced_strings,
         "referenced_names": referenced_names,
         "basic_blocks": blocks,
+        "native_api": None,
+        "native_value_flow": None,
         "limitations": [
             "Native CallReference classifications are observed where available; detailed reference flags remain unknown.",
             "Hopper's public Python API does not expose equivalent external or thunk classification in this dossier.",

package/dist/android/JadxConfiguration.js

@@ -1,11 +1,16 @@
 import { constants } from "node:fs";
 import { access, realpath, stat } from "node:fs/promises";
-import { isAbsolute, join } from "node:path";
+import { delimiter, isAbsolute, join, resolve } from "node:path";
+import { systemWindowsNativeAuthority } from "../windows/WindowsNativeLoader.js";
 import { AnalysisCapabilityUnavailableError } from "../domain/analysisErrorCore.js";
+import { ZipArtifactReader } from "../artifacts/ZipArtifactReader.js";
 import { execFileOutput, execFileOutputFailure, } from "../process/ExecFileOutput.js";
 import { JADX_JAR_CONFIGURATION_REMEDIATION } from "./JadxRelease.js";
 const JAVA_MODULE_LISTING_TIMEOUT_MS = 10_000;
 const JAVA_MODULE_LISTING_MAX_OUTPUT_BYTES = 1024 * 1024;
+// Bound ZIP metadata allocation during discovery. The audited 0.7.1 JAR's
+// central directory occupies 2,294,350 bytes; class bodies are not read here.
+const JAR_METADATA_READ_MAX_BYTES = 8 * 1024 * 1024;
 class JadxConfigurationFailure extends Error {
     code;
     diagnostics;
@@ -74,16 +79,65 @@ export const resolveJadxConfiguration = async (environment, operation, signal) =
 const readJadxConfiguration = async (environment, signal) => {
     requireSupportedHost();
     const jar = await resolveJar(environment);
-    const java = resolveJava(environment);
+    const java = await resolveJava(environment, signal);
     await requireJavaHomeExecutable(environment.JAVA_HOME, java);
     const jvmArguments = resolveJvmArguments(environment);
     await inspectJavaRuntime(java, environment, signal);
+    await requireEngineArchive(jar, signal);
     return { jar, java, jvmArguments };
 };
+const requireEngineArchive = async (jar, signal) => {
+    // These classes are consumed directly by ReaJadxBridge.java. This checks the
+    // classpath inventory without loading engine code or starting a JADX session.
+    const missing = new Set([
+        "com/atxx/jhmcp/JadxSession.class",
+        "com/atxx/jhmcp/SessionHolder.class",
+        "jadx/api/JadxDecompiler.class",
+        "com/google/gson/Gson.class",
+        "io/modelcontextprotocol/kotlin/sdk/server/Server.class",
+    ]);
+    const reader = new ZipArtifactReader(jar, "zip", JAR_METADATA_READ_MAX_BYTES);
+    try {
+        for await (const entry of reader.entries(signal)) {
+            if (entry.kind === "file" && !entry.encrypted)
+                missing.delete(entry.path);
+            if (missing.size === 0)
+                return;
+        }
+    }
+    catch (cause) {
+        if (signal?.aborted === true)
+            throw cause;
+        const reason = cause instanceof Error ? cause.message : String(cause);
+        throw configurationFailure("version_unresolved", `Cannot inspect REA_JADX_MCP_JAR ${jar} as a Java archive: ${reason}. ${JADX_JAR_CONFIGURATION_REMEDIATION}`, {
+            jar_path: jar,
+            phase: "jar-inspection",
+            archive_error: reason,
+            maximum_metadata_read_bytes: JAR_METADATA_READ_MAX_BYTES,
+        }, cause);
+    }
+    finally {
+        await reader.close();
+    }
+    throw configurationFailure("unsupported_version", `REA_JADX_MCP_JAR ${jar} does not contain the required metadata bridge classes: ${[...missing].join(", ")}. ${JADX_JAR_CONFIGURATION_REMEDIATION}`, { jar_path: jar, phase: "jar-inspection", missing_classes: [...missing] });
+};
 const requireSupportedHost = () => {
     if (process.platform === "linux" || process.platform === "darwin")
         return;
-    throw configurationFailure("unsupported_host", `Android JADX subprocess ownership is unsupported on ${process.platform}; use Linux or macOS. The metadata bridge has real-provider verification on macOS arm64.`, { platform: process.platform });
+    if (process.platform === "win32" && process.arch === "x64") {
+        const loaded = systemWindowsNativeAuthority();
+        if (loaded.available && loaded.authority.inspection.protocolStdin === true)
+            return;
+        throw configurationFailure("runtime_missing", loaded.available
+            ? "The bundled Windows native artifact lacks owned protocol stdin; use a matching current Windows x64 REA package."
+            : loaded.reason, {
+            platform: process.platform,
+            architecture: process.arch,
+            phase: "process-ownership",
+            owned_protocol_stdin: false,
+        });
+    }
+    throw configurationFailure("unsupported_host", `Android JADX subprocess ownership is unsupported on ${process.platform}/${process.arch}; use Linux, macOS, or Windows x64 with its bundled native controls.`, { platform: process.platform });
 };
 const resolveJar = async (environment) => {
     const jar = environment.REA_JADX_MCP_JAR;
@@ -101,11 +155,37 @@ const resolveJar = async (environment) => {
         throw configurationFailure("executable_missing", `Cannot read REA_JADX_MCP_JAR ${jar}: ${cause instanceof Error ? cause.message : String(cause)}`, { jar_path: jar }, cause);
     }
 };
-const resolveJava = (environment) => {
-    if (environment.JAVA_HOME === undefined)
-        return "java";
+const resolveJava = async (environment, signal) => {
+    const executable = process.platform === "win32" ? "java.exe" : "java";
+    if (environment.JAVA_HOME === undefined) {
+        if (process.platform !== "win32")
+            return executable;
+        const path = Object.entries(environment).find(([key]) => key.toLowerCase() === "path")?.[1] ?? "";
+        for (const directory of [process.cwd(), ...path.split(delimiter)]) {
+            signal?.throwIfAborted();
+            // Windows PATH commonly quotes individual entries containing spaces.
+            const selected = directory.startsWith('"') && directory.endsWith('"')
+                ? directory.slice(1, -1)
+                : directory;
+            const candidate = resolve(selected, executable);
+            try {
+                await access(candidate, constants.R_OK | constants.X_OK);
+                if ((await stat(candidate)).isFile())
+                    return await realpath(candidate);
+            }
+            catch (cause) {
+                if (typeof cause === "object" &&
+                    cause !== null &&
+                    "code" in cause &&
+                    (cause.code === "ENOENT" || cause.code === "ENOTDIR"))
+                    continue;
+                throw configurationFailure("runtime_missing", `Cannot inspect selected Java executable ${candidate}: ${errorText(cause)}`, { java_executable: candidate }, cause);
+            }
+        }
+        throw configurationFailure("runtime_missing", "Cannot find java.exe on the selected Windows PATH. Select a full JDK with JAVA_HOME or PATH, then verify it with java --list-modules. REA does not install Java.", { java_executable: executable });
+    }
     if (isAbsolute(environment.JAVA_HOME))
-        return join(environment.JAVA_HOME, "bin", "java");
+        return join(environment.JAVA_HOME, "bin", executable);
     throw configurationFailure("open_options_invalid", "JAVA_HOME must select an existing JDK by absolute path; omit it to use java on PATH.", { java_home: environment.JAVA_HOME });
 };
 const requireJavaHomeExecutable = async (javaHome, java) => {

package/dist/android/JadxMcpTransport.js

@@ -1,5 +1,6 @@
 import { deserializeMessage, serializeMessage, } from "@modelcontextprotocol/client";
 import { randomUUID } from "node:crypto";
+import { finished } from "node:stream/promises";
 import { ProviderProcessSupervisor, spawnOwnedProviderProcess, } from "../process/ProviderProcess.js";
 import { cleanupOwnedProcessGroup } from "../process/ProcessOwnership.js";
 import { ProviderCleanupError } from "../domain/providerCleanupError.js";
@@ -71,7 +72,10 @@ export class JadxMcpTransport {
     }
     /** Verifies owned process exit before declaring the transport closed. */
     close() {
-        this.#closePromise ??= this.#stop();
+        this.#closePromise ??= this.#stop().catch((cause) => {
+            this.#closePromise = undefined;
+            throw cause;
+        });
         return this.#closePromise;
     }
     /** Captured provider stderr without persisting inherited environment values. */
@@ -102,8 +106,16 @@ export class JadxMcpTransport {
         process?.stderr?.off("data", this.#countStderr);
         process?.off("error", this.#error);
         process?.off("exit", this.#exit);
-        process?.stdin?.off("error", this.#error);
+        const input = process?.stdin;
+        // A job termination can complete an in-flight pipe write asynchronously.
+        // Observe its errors until the owned Writable has finished closing.
+        const inputClosed = input === undefined || input === null
+            ? undefined
+            : finished(input, { readable: false, cleanup: true }).catch(() => undefined);
         const stopped = await this.#supervisor?.stop();
+        input?.destroy();
+        await inputClosed;
+        input?.off("error", this.#error);
         this.onclose?.();
         if (stopped?.status === "incomplete")
             throw new ProviderCleanupError("jadx", [this.runId], {

package/dist/android/JadxProvider.js

@@ -6,6 +6,7 @@ import { AnalysisError } from "../domain/analysisErrorBase.js";
 import { AnalysisCancelledError, AnalysisCapabilityUnavailableError, AnalysisOutputError, AnalysisInputError, AnalysisTimeoutError, } from "../domain/analysisErrorCore.js";
 import { ProviderAdapterError } from "../domain/providerAdapterError.js";
 import { ProviderCleanupError } from "../domain/providerCleanupError.js";
+import { projectAnalysisError } from "../domain/analysisErrorProjection.js";
 import { err, ok } from "../domain/result.js";
 import { PrivateRuntimeRoot } from "../process/PrivateRuntimeRoot.js";
 import { snapshotAndroidEngine, hashAndroidFile, snapshotAndroidTarget, } from "./AndroidTargetSnapshot.js";
@@ -59,18 +60,18 @@ const executionError = (context) => {
         },
     });
 };
-const cleanup = async (session, root, previous) => {
+const cleanup = async (resources) => {
+    const { session, root, previousError } = resources;
     const diagnostics = {
-        previous_error: previous.ok
-            ? null
-            : { tag: previous.error._tag, message: previous.error.message },
+        previous_error: previousError === undefined ? null : projectAnalysisError(previousError),
     };
     try {
         await session?.close();
+        resources.session = undefined;
     }
     catch (cause) {
         // Retain an uncertain workspace until the caller can resolve process ownership.
-        return err(new ProviderCleanupError("jadx", [
+        const error = new ProviderCleanupError("jadx", [
             session?.transport.runId ?? "unknown",
             ...(root === undefined ? [] : [root.path]),
         ], {
@@ -79,30 +80,34 @@ const cleanup = async (session, root, previous) => {
             provider_cleanup: cause instanceof ProviderCleanupError
                 ? (cause.diagnostics ?? null)
                 : null,
-        }, { cause }));
+        }, { cause: previousError ?? cause });
+        if (previousError?.partialObservation !== undefined)
+            error.retainPartialObservation(previousError.partialObservation);
+        return err(error);
     }
     try {
         await root?.close();
+        resources.root = undefined;
     }
     catch (cause) {
         return err(new ProviderCleanupError("jadx", [root?.path ?? "unknown"], {
             ...diagnostics,
             reason: cause instanceof Error ? cause.message : String(cause),
-        }, { cause }));
+        }, { cause: previousError ?? cause }));
     }
-    return previous;
+    return ok(undefined);
 };
 /** One serialized, immutable APK session per REA instance, retired on idle or shutdown. */
 export class JadxProvider {
     environment;
     launcher;
     #tail = Promise.resolve();
-    #cleanupFailure;
+    #pendingCleanup;
     #retained;
     #idle;
     #shutdown = new AbortController();
     #closePromise;
-    constructor(environment = process.env, launcher) {
+    constructor(environment, launcher) {
         this.environment = environment;
         this.launcher = launcher;
     }
@@ -132,12 +137,13 @@ export class JadxProvider {
         try {
             if (signal.aborted)
                 return err(new AnalysisCancelledError(request.operation));
-            if (this.#cleanupFailure !== undefined)
-                return err(this.#cleanupFailure);
             clearTimeout(this.#idle);
+            if (this.#pendingCleanup !== undefined) {
+                const retired = await this.#retire();
+                if (!retired.ok)
+                    return retired;
+            }
             const outcome = await this.#execute(target, request, { signal });
-            if (!outcome.ok && outcome.error.cleanupIncomplete)
-                this.#cleanupFailure = outcome.error;
             if (outcome.ok)
                 this.#scheduleIdle();
             return outcome;
@@ -150,24 +156,39 @@ export class JadxProvider {
     close() {
         this.#shutdown.abort();
         clearTimeout(this.#idle);
-        this.#closePromise ??= this.#tail.then(() => this.#retire());
+        this.#closePromise ??= this.#tail
+            .then(async () => {
+            const retired = await this.#retire();
+            if (!retired.ok)
+                throw retired.error;
+        })
+            .catch((cause) => {
+            this.#closePromise = undefined;
+            throw cause;
+        });
         return this.#closePromise;
     }
     async #retire() {
-        if (this.#cleanupFailure !== undefined)
-            throw this.#cleanupFailure;
-        const retained = this.#retained;
-        this.#retained = undefined;
-        const result = await cleanup(retained?.session, retained?.root, ok(undefined));
-        if (!result.ok) {
-            this.#cleanupFailure = result.error;
-            throw result.error;
+        if (this.#pendingCleanup === undefined && this.#retained !== undefined) {
+            this.#pendingCleanup = {
+                session: this.#retained.session,
+                root: this.#retained.root,
+                previousError: undefined,
+            };
+            this.#retained = undefined;
         }
+        if (this.#pendingCleanup === undefined)
+            return ok(undefined);
+        const result = await cleanup(this.#pendingCleanup);
+        if (result.ok)
+            this.#pendingCleanup = undefined;
+        return result;
     }
     #scheduleIdle() {
         this.#idle = setTimeout(() => {
-            const retirement = this.#tail.then(() => this.#retire());
-            this.#tail = retirement.catch(() => undefined);
+            this.#tail = this.#tail.then(async () => {
+                await this.#retire();
+            });
         }, 60_000);
         this.#idle.unref();
     }
@@ -178,7 +199,6 @@ export class JadxProvider {
             : AbortSignal.any([options.signal, timeout]);
         let root;
         let session;
-        let outcome;
         try {
             if (target.format !== "apk")
                 throw new AnalysisCapabilityUnavailableError("jadx", request.operation, `Target ${target.path} is ${target.format}; provide one standalone APK.`);
@@ -210,8 +230,11 @@ export class JadxProvider {
                     this.environment.JAVA_HOME,
                 ],
             });
-            if (this.#retained !== undefined && this.#retained.key !== key)
-                await this.#retire();
+            if (this.#retained !== undefined && this.#retained.key !== key) {
+                const retired = await this.#retire();
+                if (!retired.ok)
+                    return retired;
+            }
             let retained = this.#retained;
             if (retained === undefined) {
                 root = await PrivateRuntimeRoot.create({ prefix: "rea-android-" });
@@ -247,7 +270,7 @@ export class JadxProvider {
             root = retained.root;
             session = retained.session;
             const { snapshot } = retained;
-            outcome = ok(await session.execute({
+            const outcome = ok(await session.execute({
                 request,
                 target,
                 snapshot,
@@ -260,18 +283,23 @@ export class JadxProvider {
             return outcome;
         }
         catch (cause) {
-            outcome = err(executionError({
+            const previousError = executionError({
                 cause,
                 request,
                 timeout,
                 signal: options?.signal,
                 session,
-            }));
+            });
+            const partialObservation = session?.partialObservation();
+            if (partialObservation !== undefined)
+                previousError.retainPartialObservation(partialObservation);
+            // Admission can fail before selecting an existing session for execution.
+            root ??= this.#retained?.root;
+            session ??= this.#retained?.session;
+            this.#retained = undefined;
+            this.#pendingCleanup = { session, root, previousError };
+            const retired = await this.#retire();
+            return retired.ok ? err(previousError) : retired;
         }
-        // An existing session also needs retirement when admission fails before selection.
-        root ??= this.#retained?.root;
-        session ??= this.#retained?.session;
-        this.#retained = undefined;
-        return cleanup(session, root, outcome);
     }
 }