rea-agents 4.1.0 → 6.0.0

package/bridge/pwntools/recorded_crash_impl.py

@@ -0,0 +1,143 @@
+"""Bounded Linux core evidence via unchanged ELFFile/structs and pwntools ctypes.
+
+No Corefile-selected thread, executable guessing, process lookup or target launch.
+"""
+import base64
+import ctypes
+import importlib.metadata
+import io
+from pathlib import Path
+import sys
+
+PROFILE = "pwntools@4.15.0;pyelftools@0.33;unicorn@2.1.2"
+
+
+class CoreFailure(Exception):
+    def __init__(self, reason, message):
+        super().__init__(message)
+        self.reason = reason
+
+
+def encoded(value):
+    return base64.b64encode(value).decode("ascii")
+
+
+def location(offset, size, limit):
+    if not 0 <= offset <= limit or not 0 <= size <= limit - offset:
+        raise CoreFailure("format", "Recorded source range exceeds its declared container.")
+    return {"offset": hex(offset), "bytes": hex(size)}
+
+
+def inspect_core(path, cache):
+    for package, required in {"pwntools": "4.15.0", "pyelftools": "0.33", "unicorn": "2.1.2"}.items():
+        try:
+            actual = importlib.metadata.version(package)
+        except importlib.metadata.PackageNotFoundError as error:
+            raise CoreFailure("unavailable", "Selected Python lacks " + package + " " + required + ".") from error
+        if actual != required:
+            raise CoreFailure("unsupported", "Expected " + package + " " + required + "; selected Python reports " + actual + ".")
+    content = path.read_bytes()
+    if len(content) < 16 or content[:4] != b"\x7fELF":
+        raise CoreFailure("format", "Selected recording lacks a complete ELF identification.")
+    if content[4:6] != b"\x02\x01":
+        raise CoreFailure("unsupported-target", "Initial recorded-core profile requires ELF64 little-endian.")
+    if len(content) < 64:
+        raise CoreFailure("format", "Selected ELF64 core header is truncated.")
+    # Linux commonly emits ELFOSABI_NONE (0), also accepted as GNU/Linux (3).
+    # Other declared OSABIs must never select Linux note ctypes.
+    if content[7] not in (0, 3) or content[8] != 0:
+        raise CoreFailure("unsupported-target", "Initial recorded-core profile requires System V or GNU/Linux OSABI with ABI version zero; selected OSABI=" + str(content[7]) + ", ABI version=" + str(content[8]) + ".")
+    if int.from_bytes(content[16:18], "little") != 4 or int.from_bytes(content[18:20], "little") != 62:
+        raise CoreFailure("unsupported-target", "Initial recorded-core profile requires x86-64 ET_CORE.")
+    from elftools.common.exceptions import ELFError
+    from elftools.common.utils import struct_parse
+    from elftools.elf.elffile import ELFFile
+    from pwnlib.elf.datatypes import elf_prstatus_amd64, elf_siginfo_64, user_regs_struct_amd64
+    try:
+        image = ELFFile(io.BytesIO(content))
+        header = image.header
+        count = image.num_segments()
+        if count and header.e_phentsize < image.structs.Elf_Phdr.sizeof():
+            raise CoreFailure("format", "Program-header entry is shorter than the required ELF64 structure.")
+        location(header.e_phoff, count * header.e_phentsize, len(content))
+        segments, notes, padding, threads, signals = [], [], [], [], []
+        for segment_index, segment in enumerate(image.iter_segments()):
+            h = segment.header
+            backing = h.p_type != "PT_NULL" and h.p_filesz > 0
+            if backing:
+                location(h.p_offset, h.p_filesz, len(content))
+            if h.p_type == "PT_LOAD" and h.p_filesz > h.p_memsz:
+                raise CoreFailure("format", "Recorded PT_LOAD file bytes exceed memory size.")
+            segments.append({"index": segment_index, "type": h.p_type,
+                             "header_location": location(header.e_phoff + segment_index * header.e_phentsize, header.e_phentsize, len(content)),
+                             "offset": hex(h.p_offset), "file_size": hex(h.p_filesz), "memory_size": hex(h.p_memsz),
+                             "virtual_address": hex(h.p_vaddr), "physical_address": hex(h.p_paddr), "alignment": hex(h.p_align), "flags": hex(h.p_flags), "file_backing": "file" if backing else "none"})
+            if h.p_type != "PT_NOTE" or h.p_filesz == 0:
+                continue
+            position, end = h.p_offset, h.p_offset + h.p_filesz
+            header_size = image.structs.Elf_Nhdr.sizeof()
+            while position < end:
+                if end - position < header_size:
+                    raw = content[position:end]
+                    if any(raw):
+                        raise CoreFailure("format", "Nonzero trailing note bytes lack a complete note header.")
+                    padding.append({"segment_index": segment_index, "location": location(position, len(raw), end), "bytes_base64": encoded(raw)})
+                    break
+                note = struct_parse(image.structs.Elf_Nhdr, image.stream, stream_pos=position)
+                owner_start = position + header_size
+                descriptor_start = owner_start + ((note.n_namesz + 3) // 4) * 4
+                note_end = descriptor_start + ((note.n_descsz + 3) // 4) * 4
+                location(position, note_end - position, end)
+                owner = content[owner_start:owner_start + note.n_namesz]
+                if owner and b"\0" not in owner:
+                    raise CoreFailure("format", "Declared note owner has no NUL terminator.")
+                display = owner.split(b"\0", 1)[0].decode("utf-8", "replace") if owner else None
+                descriptor = content[descriptor_start:descriptor_start + note.n_descsz]
+                note_index = len(notes)
+                notes.append({"index": note_index, "segment_index": segment_index, "type": note.n_type,
+                              "location": location(position, note_end - position, end),
+                              "owner_location": location(owner_start, len(owner), end), "owner_bytes_base64": encoded(owner), "owner_display": display,
+                              "descriptor_location": location(descriptor_start, len(descriptor), end), "descriptor_bytes_base64": encoded(descriptor)})
+                position = note_end
+                # Only the initial Linux CORE ABI is interpreted. Other owners retain exact bytes.
+                if owner != b"CORE\0":
+                    continue
+                if note.n_type == "NT_PRSTATUS":
+                    if len(descriptor) < ctypes.sizeof(elf_prstatus_amd64):
+                        raise CoreFailure("format", "Linux amd64 NT_PRSTATUS descriptor is truncated.")
+                    status = elf_prstatus_amd64.from_buffer_copy(descriptor)
+                    registers = []
+                    for name, kind in user_regs_struct_amd64._fields_:
+                        relative = elf_prstatus_amd64.pr_reg.offset + getattr(user_regs_struct_amd64, name).offset
+                        registers.append({"name": name, "value": hex(getattr(status.pr_reg, name)), "location": location(descriptor_start + relative, ctypes.sizeof(kind), end)})
+                    threads.append({"note_index": note_index, "historical_pid": ctypes.c_int32(status.pr_pid).value, "recorded_current_signal": status.pr_cursig, "registers": registers})
+                elif note.n_type == "NT_SIGINFO":
+                    if len(descriptor) < ctypes.sizeof(elf_siginfo_64):
+                        raise CoreFailure("format", "Linux amd64 NT_SIGINFO descriptor is truncated.")
+                    signal = elf_siginfo_64.from_buffer_copy(descriptor)
+                    number = ctypes.c_int32(signal.si_signo).value
+                    code = ctypes.c_int32(signal.si_code).value
+                    known = number == 11 and code in (1, 2)
+                    signals.append({"note_index": note_index, "number": number, "code": code, "errno": ctypes.c_int32(signal.si_errno).value,
+                                    "fault_address": hex(signal.sigfault_addr) if known else None,
+                                    "fault_address_meaning": "recorded-sigsegv-address" if known else "unknown", "thread_association": "unknown"})
+        return {"format": "elf-core", "architecture": "x86_64-little-endian", "target_execution": "not-performed", "live_process_identity": "unknown",
+                "segments": segments, "notes": notes, "note_padding": padding, "threads": threads, "signals": signals,
+                "note_interpretation_completeness": "unknown",
+                "limitations": ["The initial Linux note profile accepts System V/unspecified or GNU/Linux OSABI with ABI version zero; an unspecified OSABI alone does not prove operating-system origin.",
+                                "Historical PID and signal values are recorded metadata, not current process identity or attach authority.",
+                                "Only exact Linux CORE NT_PRSTATUS/NT_SIGINFO owners are interpreted; every descriptor and owner retains original bytes. Other note semantics remain unknown.",
+                                "NT_SIGINFO thread association is unknown. Only SIGSEGV SEGV_MAPERR/SEGV_ACCERR initially establish a fault-address union meaning.",
+                                "PT_LOAD file bytes are recorded bytes. Undumped memory and current executable/library identity remain unknown; no current host file is resolved from a recorded pathname.",
+                                "Missing notes/registers/signals do not establish their absence at the original crash. Full unwinding, executable pairing and live control are not provided."]}
+    except CoreFailure:
+        raise
+    except (ELFError, ValueError, AssertionError, IndexError) as error:
+        raise CoreFailure("format", "Recorded core failed unchanged upstream structural parsing: " + str(error)) from error
+
+
+if __name__ == "__main__":
+    runtime_path = Path(__file__).with_name("decoder_runtime.py")
+    runtime = {"__file__": str(runtime_path), "__name__": "rea_decoder_runtime"}
+    exec(compile(runtime_path.read_bytes(), str(runtime_path), "exec"), runtime)
+    runtime["main"](sys.argv[-1], inspect_core, CoreFailure, PROFILE)

package/dist/android/AndroidTargetSnapshot.js

@@ -2,7 +2,7 @@ import { constants, createReadStream } from "node:fs";
 import { chmod, copyFile } from "node:fs/promises";
 import { createHash } from "node:crypto";
 import { join } from "node:path";
-import { AnalysisInputError } from "../domain/analysisErrorCore.js";
+import { AnalysisInputError, AnalysisCapabilityUnavailableError, } from "../domain/analysisErrorCore.js";
 /** Stream a local file digest without retaining the APK or JAR in memory. */
 export const hashAndroidFile = async (path) => {
     const hash = createHash("sha256");
@@ -26,9 +26,11 @@ export const snapshotAndroidTarget = async (path, sha256, root, operation) => {
     return snapshot;
 };
 /** Fingerprint the actual immutable engine bytes executed for this observation. */
-export const snapshotAndroidEngine = async (source, root) => {
+export const snapshotAndroidEngine = async (source, sha256, root, operation) => {
     const path = join(root, "engine.jar");
     await copyFile(source, path, constants.COPYFILE_EXCL);
     await chmod(path, 0o400);
-    return { path, sha256: await hashAndroidFile(path) };
+    if ((await hashAndroidFile(path)) !== sha256)
+        throw new AnalysisCapabilityUnavailableError("jadx", operation, "REA_JADX_MCP_JAR bytes changed during admission; retry with a stable engine file.");
+    return { path, sha256 };
 };

package/dist/android/JadxAnalysis.js

@@ -1,6 +1,7 @@
-import { androidResultSchemas } from "../domain/androidAnalysis.js";
+import { androidResultSchemas } from "../domain/android/androidAnalysis.js";
 import { AnalysisCapabilityUnavailableError, AnalysisInputError, AnalysisOutputError, } from "../domain/analysisErrorCore.js";
 import { jadxAppSchema, jadxClassPageSchema, jadxClassSchema, jadxLoadSchema, jadxMethodSchema, jadxXrefsSchema, normalizeJadxText, } from "./JadxProtocol.js";
+import { JADX_RELEASE } from "./JadxRelease.js";
 const methodsOf = (summary) => {
     const seen = new Map();
     return summary.methods.map((method) => {
@@ -60,16 +61,17 @@ const inspectPackage = async (tools, loaded, engine) => {
 };
 const searchClasses = async (tools, request, loaded, engine) => {
     const classes = [];
+    const pageSize = 4096;
     let total;
     do {
         const page = jadxClassPageSchema.parse(await tools.json("list_classes", {
             offset: classes.length,
-            limit: 200,
+            limit: pageSize,
         }));
         if ((total !== undefined && total !== page.total) ||
             page.offset !== classes.length ||
-            page.limit !== 200 ||
-            page.items.length > 200)
+            page.limit !== pageSize ||
+            page.items.length > pageSize)
             throw new AnalysisOutputError(request.operation, "JADX class pagination changed identity or counts");
         total = page.total;
         classes.push(...page.items);
@@ -115,7 +117,7 @@ const inspectMethod = async (tools, request, summary, engine) => {
     if (body.body.startsWith("// ERROR:"))
         throw new AnalysisOutputError(request.operation, `JADX did not produce method source: ${body.body}`);
     if (body.mode === "smali" && candidates.length > 1)
-        throw new AnalysisCapabilityUnavailableError("jadx", request.operation, `JADX 0.7.1 smali fallback joins all same-name overloads for ${summary.full_name}.${request.input.method_name}; it cannot establish source for only overload ${index}.`);
+        throw new AnalysisCapabilityUnavailableError("jadx", request.operation, `JADX ${JADX_RELEASE.version} smali fallback joins all same-name overloads for ${summary.full_name}.${request.input.method_name}; it cannot establish source for only overload ${index}.`);
     return androidResultSchemas.inspect_android_method.parse({
         engine,
         class_name: summary.full_name,
@@ -158,7 +160,7 @@ const traceReferences = async (tools, request, summary, engine) => {
     const methodName = request.input.method_name;
     const candidates = matchingMethods(summary, request);
     if (candidates.length > 1)
-        throw new AnalysisCapabilityUnavailableError("jadx", request.operation, `JADX 0.7.1 references select the first same-name method; ${summary.full_name}.${methodName} has ${candidates.length} overloads. No unambiguous reference result is available.`);
+        throw new AnalysisCapabilityUnavailableError("jadx", request.operation, `References require a unique method name; ${summary.full_name}.${methodName} has ${candidates.length} overloads. No unambiguous reference result is available.`);
     const expectedTarget = methodName === undefined
         ? summary.full_name
         : `${summary.full_name}.${methodName}`;

package/dist/android/JadxConfiguration.js

@@ -2,16 +2,17 @@ import { access, realpath, stat } from "node:fs/promises";
 import { constants } from "node:fs";
 import { isAbsolute, join } from "node:path";
 import { AnalysisCapabilityUnavailableError } from "../domain/analysisErrorCore.js";
+import { JADX_JAR_CONFIGURATION_REMEDIATION } from "./JadxRelease.js";
 /** Admit explicit local tooling without installing or changing host configuration. */
 export const resolveJadxConfiguration = async (environment, operation) => {
     const unavailable = (reason) => new AnalysisCapabilityUnavailableError("jadx", operation, reason);
     if (process.platform !== "linux" && process.platform !== "darwin")
-        throw unavailable(`Android JADX subprocess ownership is unsupported on ${process.platform}; use Linux or macOS. Only Linux has real-provider verification.`);
+        throw unavailable(`Android JADX subprocess ownership is unsupported on ${process.platform}; use Linux or macOS. The metadata bridge has real-provider verification on macOS arm64.`);
     const jar = environment.REA_JADX_MCP_JAR;
     if (environment.JAVA_HOME !== undefined && !isAbsolute(environment.JAVA_HOME))
         throw unavailable("JAVA_HOME must select an existing JDK by absolute path; omit it to use java on PATH.");
     if (jar === undefined || !isAbsolute(jar))
-        throw unavailable("Set REA_JADX_MCP_JAR to the absolute path of a caller-supplied jadx-headless-mcp 0.7.1 JAR. REA does not download or install it.");
+        throw unavailable(JADX_JAR_CONFIGURATION_REMEDIATION);
     const java = environment.JAVA_HOME === undefined
         ? "java"
         : join(environment.JAVA_HOME, "bin", "java");
@@ -37,5 +38,20 @@ export const resolveJadxConfiguration = async (environment, operation) => {
             throw unavailable(`Cannot execute JAVA_HOME java ${java}: ${cause instanceof Error ? cause.message : String(cause)}`);
         }
     }
-    return { jar: await realpath(jar), java };
+    const jvmArguments = [];
+    for (const [name, prefix, suffix] of [
+        ["REA_JADX_HEAP_MIB", "-Xmx", "m"],
+        ["REA_JADX_ACTIVE_PROCESSOR_COUNT", "-XX:ActiveProcessorCount=", ""],
+    ]) {
+        const value = environment[name];
+        if (value === undefined)
+            continue;
+        if (!/^[1-9]\d*$/u.test(value) || !Number.isSafeInteger(Number(value)))
+            throw unavailable(`${name} must be a positive safe integer; received ${value}.`);
+        if (name === "REA_JADX_ACTIVE_PROCESSOR_COUNT" &&
+            Number(value) > 2_147_483_647)
+            throw unavailable(`${name} exceeds the JVM's signed 32-bit processor-count range.`);
+        jvmArguments.push(`${prefix}${value}${suffix}`);
+    }
+    return { jar: await realpath(jar), java, jvmArguments };
 };

package/dist/android/JadxMcpTransport.js

@@ -4,7 +4,7 @@ import { ProviderProcessSupervisor, spawnOwnedProviderProcess, } from "../proces
 import { cleanupOwnedProcessGroup } from "../process/ProcessOwnership.js";
 import { ProviderCleanupError } from "../domain/providerCleanupError.js";
 const MAX_FRAME_BYTES = 8 * 1024 * 1024;
-const MAX_SESSION_BYTES = 32 * 1024 * 1024;
+const MAX_OPERATION_BYTES = 32 * 1024 * 1024;
 /** SDK-framed stdio with REA-owned process cleanup rather than an unowned child. */
 export class JadxMcpTransport {
     options;
@@ -15,7 +15,8 @@ export class JadxMcpTransport {
     runId = randomUUID();
     #spawned;
     #supervisor;
-    #buffer = Buffer.alloc(0);
+    #frameBuffer = Buffer.alloc(0);
+    #frameLength = 0;
     #bytes = 0;
     #started = false;
     #closed = false;
@@ -44,8 +45,9 @@ export class JadxMcpTransport {
         this.#supervisor = new ProviderProcessSupervisor({
             ...spawned,
             ownsProcessLifetime: true,
-            cleanup: spawned.cleanup ?? (() => cleanupOwnedProcessGroup(spawned.ownership)),
-        });
+            cleanup: spawned.cleanup ??
+                (() => cleanupOwnedProcessGroup(spawned.ownership)),
+        }, { captureStdout: false });
         if (spawned.process.stdin === undefined ||
             spawned.process.stdin === null ||
             spawned.process.stdout === null)
@@ -80,8 +82,15 @@ export class JadxMcpTransport {
     failureReason() {
         return this.#failure;
     }
+    /** Scope both the byte budget and diagnostic retention to the next serialized request. */
+    beginOperation() {
+        this.#bytes = 0;
+        this.#supervisor?.resetOutput();
+    }
     async #stop() {
         this.#closed = true;
+        this.#frameBuffer = Buffer.alloc(0);
+        this.#frameLength = 0;
         // A cancellation may race acquisition. Join it before inspecting ownership.
         await this.#starting?.catch(() => undefined);
         const process = this.#spawned?.process;
@@ -106,35 +115,53 @@ export class JadxMcpTransport {
     };
     #countStderr = (chunk) => {
         this.#bytes += Buffer.byteLength(chunk);
-        if (this.#bytes > MAX_SESSION_BYTES)
-            this.#fail(new Error(`JADX session output exceeds ${MAX_SESSION_BYTES} bytes; no complete result is available`));
+        if (this.#bytes > MAX_OPERATION_BYTES)
+            this.#fail(new Error(`JADX operation output exceeds ${MAX_OPERATION_BYTES} bytes; no complete result is available`));
     };
     #read = (chunk) => {
         if (this.#closed)
             return;
         const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
         this.#bytes += bytes.length;
-        if (this.#bytes > MAX_SESSION_BYTES) {
-            this.#fail(new Error(`JADX session output exceeds ${MAX_SESSION_BYTES} bytes; no complete result is available`));
+        if (this.#bytes > MAX_OPERATION_BYTES) {
+            this.#fail(new Error(`JADX operation output exceeds ${MAX_OPERATION_BYTES} bytes; no complete result is available`));
             return;
         }
-        this.#buffer = Buffer.concat([this.#buffer, bytes]);
         try {
-            let newline;
-            while ((newline = this.#buffer.indexOf(10)) !== -1) {
-                if (newline > MAX_FRAME_BYTES)
+            let offset = 0;
+            while (offset < bytes.length) {
+                const newline = bytes.indexOf(10, offset);
+                const end = newline === -1 ? bytes.length : newline;
+                const fragment = bytes.subarray(offset, end);
+                const frameBytes = this.#frameLength + fragment.length;
+                if (frameBytes > MAX_FRAME_BYTES)
                     throw new Error(`JADX MCP frame exceeds ${MAX_FRAME_BYTES} bytes`);
-                const line = this.#buffer.subarray(0, newline).toString("utf8");
-                this.#buffer = this.#buffer.subarray(newline + 1);
+                this.#appendFrame(fragment, frameBytes);
+                if (newline === -1)
+                    return;
+                const line = this.#frameBuffer
+                    .subarray(0, this.#frameLength)
+                    .toString("utf8");
+                this.#frameBuffer = Buffer.alloc(0);
+                this.#frameLength = 0;
                 this.onmessage?.(deserializeMessage(line));
+                offset = newline + 1;
             }
-            if (this.#buffer.length > MAX_FRAME_BYTES)
-                throw new Error(`JADX MCP frame exceeds ${MAX_FRAME_BYTES} bytes`);
         }
         catch (cause) {
             this.#fail(cause instanceof Error ? cause : new Error(String(cause)));
         }
     };
+    #appendFrame(fragment, frameBytes) {
+        if (frameBytes > this.#frameBuffer.length) {
+            const capacity = Math.min(MAX_FRAME_BYTES, Math.max(frameBytes, this.#frameBuffer.length * 2, 1));
+            const grown = Buffer.allocUnsafe(capacity);
+            this.#frameBuffer.copy(grown, 0, 0, this.#frameLength);
+            this.#frameBuffer = grown;
+        }
+        fragment.copy(this.#frameBuffer, this.#frameLength);
+        this.#frameLength = frameBytes;
+    }
     #fail(error) {
         this.#failure ??= error.message;
         this.onerror?.(error);

package/dist/android/JadxProtocol.js

@@ -2,6 +2,14 @@ import { z } from "zod";
 import { AnalysisOutputError } from "../domain/analysisErrorCore.js";
 import { jsonValueSchema } from "../domain/jsonValue.js";
 const count = z.number().int().nonnegative();
+/** Values observed inside the exact JVM producing the analysis. */
+export const jadxRuntimeSchema = z.object({
+    engine_reported_version: z.string().min(1),
+    max_heap_bytes: z.number().int().positive().safe(),
+    available_processors: z.number().int().positive(),
+    java_version: z.string().min(1),
+    metadata_scope: z.literal("parsed_members"),
+});
 export const jadxLoadSchema = z.object({
     state: z.literal("LOADED"),
     apk_path: z.string(),

package/dist/android/JadxProvider.js

@@ -1,14 +1,18 @@
 import { z } from "zod";
+import { chmod, copyFile } from "node:fs/promises";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
 import { AnalysisError } from "../domain/analysisErrorBase.js";
-import { AnalysisCancelledError, AnalysisCapabilityUnavailableError, AnalysisOutputError, AnalysisTimeoutError, } from "../domain/analysisErrorCore.js";
+import { AnalysisCancelledError, AnalysisCapabilityUnavailableError, AnalysisOutputError, AnalysisInputError, AnalysisTimeoutError, } from "../domain/analysisErrorCore.js";
 import { ProviderAdapterError } from "../domain/providerAdapterError.js";
 import { ProviderCleanupError } from "../domain/providerCleanupError.js";
 import { err, ok } from "../domain/result.js";
 import { PrivateRuntimeRoot } from "../process/PrivateRuntimeRoot.js";
-import { snapshotAndroidEngine, snapshotAndroidTarget, } from "./AndroidTargetSnapshot.js";
+import { snapshotAndroidEngine, hashAndroidFile, snapshotAndroidTarget, } from "./AndroidTargetSnapshot.js";
 import { resolveJadxConfiguration } from "./JadxConfiguration.js";
 import { JadxSession } from "./JadxSession.js";
 const OPERATION_TIMEOUT_MS = 120_000;
+const BRIDGE_SOURCE = fileURLToPath(new URL("../../bridge/android/ReaJadxBridge.java", import.meta.url));
 const waitForTurn = (predecessor, request, signal) => new Promise((resolve, reject) => {
     const abort = () => reject(new AnalysisCancelledError(request.operation));
     signal?.addEventListener("abort", abort, { once: true });
@@ -75,44 +79,81 @@ const cleanup = async (session, root, previous) => {
     }
     return previous;
 };
-/** One queued engine per REA instance, with a fresh owned workspace for every request. */
+/** One serialized, immutable APK session per REA instance, retired on idle or shutdown. */
 export class JadxProvider {
     environment;
     launcher;
     #tail = Promise.resolve();
     #cleanupFailure;
+    #retained;
+    #idle;
+    #shutdown = new AbortController();
+    #closePromise;
     constructor(environment = process.env, launcher) {
         this.environment = environment;
         this.launcher = launcher;
     }
     /** Serialize expensive work and bind both raw and normalized results to the APK. */
     async execute(target, request, options) {
+        if (this.#shutdown.signal.aborted)
+            return err(new AnalysisCancelledError(request.operation));
+        const signal = options?.signal === undefined
+            ? this.#shutdown.signal
+            : AbortSignal.any([options.signal, this.#shutdown.signal]);
         const predecessor = this.#tail;
         let release = () => { };
         this.#tail = new Promise((resolve) => {
             release = resolve;
         });
         try {
-            await waitForTurn(predecessor, request, options?.signal);
+            await waitForTurn(predecessor, request, signal);
         }
         catch {
             void predecessor.then(release);
             return err(new AnalysisCancelledError(request.operation));
         }
         try {
-            if (options?.signal?.aborted === true)
+            if (signal.aborted)
                 return err(new AnalysisCancelledError(request.operation));
             if (this.#cleanupFailure !== undefined)
                 return err(this.#cleanupFailure);
-            const outcome = await this.#execute(target, request, options);
+            clearTimeout(this.#idle);
+            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;
         }
         finally {
             release();
         }
     }
+    /** Cancel queued/active operations and join the owned engine and workspace cleanup. */
+    close() {
+        this.#shutdown.abort();
+        clearTimeout(this.#idle);
+        this.#closePromise ??= this.#tail.then(() => this.#retire());
+        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;
+        }
+    }
+    #scheduleIdle() {
+        this.#idle = setTimeout(() => {
+            const retirement = this.#tail.then(() => this.#retire());
+            this.#tail = retirement.catch(() => undefined);
+        }, 60_000);
+        this.#idle.unref();
+    }
     async #execute(target, request, options) {
         const timeout = AbortSignal.timeout(OPERATION_TIMEOUT_MS);
         const signal = options?.signal === undefined
@@ -126,35 +167,80 @@ export class JadxProvider {
                 throw new AnalysisCapabilityUnavailableError("jadx", request.operation, `Target ${target.path} is ${target.format}; provide one standalone APK.`);
             const configuration = await resolveJadxConfiguration(this.environment, request.operation);
             signal.throwIfAborted();
-            root = await PrivateRuntimeRoot.create({ prefix: "rea-android-" });
-            const engine = await snapshotAndroidEngine(configuration.jar, root.path);
-            const snapshot = await snapshotAndroidTarget(target.path, target.sha256, root.path, request.operation);
-            signal.throwIfAborted();
-            session = new JadxSession({
-                command: configuration.java,
-                arguments: [
-                    "-Xmx512m",
-                    "-XX:ActiveProcessorCount=1",
-                    "-jar",
-                    engine.path,
-                    "--threads",
-                    "1",
-                    "--max-source-bytes",
-                    "1048576",
-                    "--decompile-timeout-ms",
-                    "90000",
+            const jarHash = await hashAndroidFile(configuration.jar);
+            const bridgeHash = await hashAndroidFile(BRIDGE_SOURCE);
+            if ((await hashAndroidFile(target.path)) !== target.sha256)
+                throw new AnalysisInputError(request.operation, undefined, [
+                    {
+                        path: ["path"],
+                        reason: "invalid_value",
+                        message: "APK bytes changed after admission; retry against a stable file.",
+                    },
+                ]);
+            const key = JSON.stringify({
+                path: target.path,
+                sha256: target.sha256,
+                jar: configuration.jar,
+                jarHash,
+                bridgeHash,
+                java: configuration.java,
+                arguments: configuration.jvmArguments,
+                options: [
+                    this.environment.JAVA_TOOL_OPTIONS,
+                    this.environment._JAVA_OPTIONS,
+                    this.environment.JDK_JAVA_OPTIONS,
+                    this.environment.PATH,
+                    this.environment.JAVA_HOME,
                 ],
-                cwd: root.path,
-                hostEnvironment: this.environment,
-                env: { _JAVA_OPTIONS: "-Xmx512m -XX:ActiveProcessorCount=1" },
-            }, this.launcher);
+            });
+            if (this.#retained !== undefined && this.#retained.key !== key)
+                await this.#retire();
+            let retained = this.#retained;
+            if (retained === undefined) {
+                root = await PrivateRuntimeRoot.create({ prefix: "rea-android-" });
+                const engine = await snapshotAndroidEngine(configuration.jar, jarHash, root.path, request.operation);
+                const snapshot = await snapshotAndroidTarget(target.path, target.sha256, root.path, request.operation);
+                const bridge = join(root.path, "ReaJadxBridge.java");
+                await copyFile(BRIDGE_SOURCE, bridge);
+                await chmod(bridge, 0o400);
+                if ((await hashAndroidFile(bridge)) !== bridgeHash)
+                    throw new AnalysisCapabilityUnavailableError("jadx", request.operation, "REA Android bridge bytes changed during admission; retry with a stable installation.");
+                signal.throwIfAborted();
+                session = new JadxSession({
+                    command: configuration.java,
+                    arguments: [
+                        ...configuration.jvmArguments,
+                        "--class-path",
+                        engine.path,
+                        bridge,
+                    ],
+                    cwd: root.path,
+                    hostEnvironment: this.environment,
+                    signal,
+                }, this.launcher);
+                retained = {
+                    key,
+                    root,
+                    session,
+                    snapshot,
+                    jarHash: engine.sha256,
+                    bridgeHash,
+                };
+            }
+            root = retained.root;
+            session = retained.session;
+            const { snapshot } = retained;
             outcome = ok(await session.execute({
                 request,
                 target,
                 snapshot,
-                jarHash: engine.sha256,
+                jarHash: retained.jarHash,
+                bridgeHash: retained.bridgeHash,
                 signal,
             }));
+            signal.throwIfAborted();
+            this.#retained = retained;
+            return outcome;
         }
         catch (cause) {
             outcome = err(executionError({
@@ -165,6 +251,10 @@ export class JadxProvider {
                 session,
             }));
         }
+        // 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);
     }
 }

package/dist/android/JadxRelease.js

@@ -5,6 +5,13 @@ export const JADX_RELEASE = Object.freeze({
     sha256: "6e5eacf500b64292bfb73c49797c1958f6ee44646e43e868039ae7feb573ff75",
     url: "https://github.com/1013503897/jadx-headless-mcp/releases/download/v0.7.1/jadx-headless-mcp-0.7.1-all.jar",
 });
+/** Identity of REA's metadata bridge, distinct from the producing engine. */
+export const JADX_BRIDGE_IDENTITY = Object.freeze({
+    name: "rea-jadx-bridge",
+    version: "1",
+});
+/** Remediation when `REA_JADX_MCP_JAR` is missing or not an absolute path. */
+export const JADX_JAR_CONFIGURATION_REMEDIATION = `Set REA_JADX_MCP_JAR to the absolute path of a caller-supplied jadx-headless-mcp ${JADX_RELEASE.version} JAR. REA does not download or install it.`;
 /** Producing engine identity used by Evidence and the generated product catalog. */
 export const JADX_PROVIDER_IDENTITY = Object.freeze({
     id: "jadx",
@@ -15,5 +22,6 @@ export const JADX_PROVIDER_IDENTITY = Object.freeze({
 export const JADX_LIMITATIONS = [
     "Static decompiler observations do not establish runtime behavior; the APK is never executed.",
     "Method signatures use provider display types; exact DEX descriptors and instruction offsets are unavailable. Overload indices are local to this engine and artifact.",
+    "Class inventories use parsed metadata before code generation, including synthetic members that may be omitted from decompiled source. Source positions remain unknown.",
     "Manifest summary fields are extracted by the upstream engine; decoded XML is retained for verification. APK signatures, split APKs, native libraries and Android runtime capture are not verified by this provider.",
 ];