rea-agents 6.5.0 → 6.7.0

package/dist/android/JadxConfiguration.js

@@ -1,14 +1,21 @@
+import { inspectJadxJava } from "./JadxJavaProbe.js";
+import { JadxInterruption, throwIfJadxInterrupted, } from "./JadxInterruption.js";
 import { constants } from "node:fs";
 import { access, realpath, stat } from "node:fs/promises";
 import { delimiter, isAbsolute, join, resolve } from "node:path";
 import { inspectWindowsNativeReadiness } from "../process/WindowsAuthority.js";
 import { systemWindowsNativeAuthority } from "../windows/WindowsNativeLoader.js";
-import { AnalysisCapabilityUnavailableError } from "../domain/analysisErrorCore.js";
+import { providerStartupTimeoutSchema } from "../config/providerStartupTimeout.js";
+import { AnalysisCancelledError, AnalysisTimeoutError, AnalysisCapabilityUnavailableError, } from "../domain/analysisErrorCore.js";
+import { err, ok } from "../domain/result.js";
+import { AnalysisError } from "../domain/analysisErrorBase.js";
+import { analysisErrorWithCleanupFailure } from "../domain/analysisErrorCleanup.js";
+import { ProviderCleanupError } from "../domain/providerCleanupError.js";
+import { ArtifactReaderFailure } from "../artifacts/ArtifactReader.js";
+import { ArtifactFileCancelled, ArtifactFileCleanupFailure, bindArtifactFileCleanup, withArtifactRegularFile, } from "../artifacts/ArtifactFileOperation.js";
+import { analysisClientFailureForOperation } from "../providers/AnalysisClientFailure.js";
 import { ZipArtifactReader } from "../artifacts/ZipArtifactReader.js";
-import { execFileOutput, execFileOutputFailure, } from "../process/ExecFileOutput.js";
-import { JADX_JAR_CONFIGURATION_REMEDIATION, JADX_JAVA_PROBE_REMEDIATION, JADX_JAVA_RUNTIME_REMEDIATION, JADX_JVM_OPTIONS_REMEDIATION, JADX_UNSUPPORTED_HOST_REMEDIATION, JADX_WINDOWS_NATIVE_REMEDIATION, } from "./JadxRelease.js";
-const JAVA_MODULE_LISTING_TIMEOUT_MS = 10_000;
-const JAVA_MODULE_LISTING_MAX_OUTPUT_BYTES = 1024 * 1024;
+import { DEFAULT_JADX_OPERATION_TIMEOUT_MS, JADX_JAR_CONFIGURATION_REMEDIATION, JADX_JAVA_PROBE_REMEDIATION, JADX_JAVA_RUNTIME_REMEDIATION, JADX_JVM_OPTIONS_REMEDIATION, JADX_OPERATION_TIMEOUT_REMEDIATION, JADX_UNSUPPORTED_HOST_REMEDIATION, JADX_WINDOWS_NATIVE_REMEDIATION, } from "./JadxRelease.js";
 // 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;
@@ -19,6 +26,7 @@ export const JADX_FAILURE_KINDS = [
     "java_runtime",
     "java_home",
     "jvm_options",
+    "operation_timeout",
     "jar",
     "java_probe",
     "unsupported_host",
@@ -56,6 +64,11 @@ export const projectJadxFailureOutcome = (kind, configured) => {
                 remediation: JADX_JVM_OPTIONS_REMEDIATION,
                 classification: drift,
             };
+        case "operation_timeout":
+            return {
+                remediation: JADX_OPERATION_TIMEOUT_REMEDIATION,
+                classification: drift,
+            };
         case "jar":
             return {
                 remediation: JADX_JAR_CONFIGURATION_REMEDIATION,
@@ -90,10 +103,11 @@ class JadxConfigurationFailure extends Error {
     }
 }
 /** Inspect the same JAR and Java prerequisites that gate actual execution. */
-export const inspectJadxAvailability = async (environment, signal) => {
+export const inspectJadxAvailability = async (environment, options) => {
     try {
-        const configuration = await readJadxConfigurationInputs(environment, signal);
-        await validateJadxConfigurationContents(configuration, environment, signal);
+        const operationTimeoutMs = readOperationTimeout(environment);
+        const configuration = await readJadxConfigurationInputs(environment, options.signal);
+        await validateJadxConfigurationContents(configuration, environment, options);
         return {
             status: "available",
             code: null,
@@ -103,12 +117,13 @@ export const inspectJadxAvailability = async (environment, signal) => {
                 java_executable: configuration.java,
                 jdk_compiler: true,
                 jar_path: configuration.jar,
+                operation_timeout_ms: operationTimeoutMs,
             },
         };
     }
     catch (cause) {
-        if (signal?.aborted === true)
-            throw cause;
+        if (cause instanceof JadxInterruption)
+            throw new AnalysisCancelledError(options.operation ?? "inspect_jadx_configuration", { cause: cause.reason });
         if (cause instanceof JadxConfigurationFailure)
             return {
                 status: "unavailable",
@@ -119,51 +134,70 @@ export const inspectJadxAvailability = async (environment, signal) => {
         throw cause;
     }
 };
+/**
+ * Resolve the whole-operation deadline before any admission work starts, so
+ * one value bounds the provider operation and each upstream call.
+ */
+export const resolveJadxOperationTimeout = (environment, operation) => {
+    try {
+        return ok(readOperationTimeout(environment));
+    }
+    catch (cause) {
+        if (!(cause instanceof JadxConfigurationFailure))
+            throw cause;
+        return err(projectConfigurationFailure(operation, cause));
+    }
+};
 /** Resolve caller-selected paths and JVM options without probing their contents. */
 export const resolveJadxConfigurationInputs = async (environment, operation, signal) => {
     try {
         return await readJadxConfigurationInputs(environment, signal);
     }
     catch (cause) {
-        if (signal?.aborted === true)
-            throw cause;
         if (!(cause instanceof JadxConfigurationFailure))
             throw cause;
         throw projectConfigurationFailure(operation, cause);
     }
 };
 /** Probe Java and archive prerequisites before starting a new engine session. */
-export const validateJadxConfiguration = async (configuration, environment, operation, signal) => {
+export const validateJadxConfiguration = async (configuration, environment, operation, options) => {
     try {
-        await validateJadxConfigurationContents(configuration, environment, signal);
+        await validateJadxConfigurationContents(configuration, environment, {
+            ...options,
+            operation,
+        });
     }
     catch (cause) {
-        if (signal?.aborted === true)
-            throw cause;
         if (!(cause instanceof JadxConfigurationFailure))
             throw cause;
         throw projectConfigurationFailure(operation, cause);
     }
 };
 const readJadxConfigurationInputs = async (environment, signal) => {
-    signal?.throwIfAborted();
+    throwIfJadxInterrupted(signal);
     requireSupportedHost();
     const jar = await resolveJar(environment);
     const java = await resolveJava(environment, signal);
     await requireJavaHomeExecutable(environment.JAVA_HOME, java);
-    signal?.throwIfAborted();
+    throwIfJadxInterrupted(signal);
     return { jar, java, jvmArguments: resolveJvmArguments(environment) };
 };
-const validateJadxConfigurationContents = async (configuration, environment, signal) => {
-    signal?.throwIfAborted();
-    await inspectJavaRuntime(configuration.java, environment, signal);
-    await requireEngineArchive(configuration.jar, signal);
+const validateJadxConfigurationContents = async (configuration, environment, options) => {
+    throwIfJadxInterrupted(options.signal);
+    await inspectJavaRuntime(configuration.java, environment, options);
+    await requireEngineArchive(configuration.jar, options);
 };
 const projectConfigurationFailure = (operation, cause) => {
     const output = cause.diagnostics;
+    const { stdout: _stdout, stderr: _stderr, ...facts } = output;
     return new AnalysisCapabilityUnavailableError("jadx", operation, cause.message, {
         cause,
         userMessage: cause.message,
+        diagnostics: {
+            ...facts,
+            failure_kind: cause.kind,
+            failure_code: cause.code,
+        },
         ...(typeof output.stdout === "string" && typeof output.stderr === "string"
             ? {
                 capturedOutput: {
@@ -175,40 +209,113 @@ const projectConfigurationFailure = (operation, cause) => {
             : {}),
     });
 };
-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);
+const requireEngineArchive = async (jar, options) => {
+    const operation = options.operation ?? "inspect_jadx_configuration";
     try {
-        for await (const entry of reader.entries(signal)) {
-            if (entry.kind === "file" && !entry.encrypted)
-                missing.delete(entry.path);
-            if (missing.size === 0)
-                return;
-        }
+        await options.resourceOwner.run(() => withArtifactRegularFile(jar, {
+            retain: ({ lease, resource }) => options.resourceOwner.retain({
+                close: () => lease.release(),
+            }, resource),
+        }, options.signal, async (handle) => {
+            try {
+                // Metadata enumeration borrows this descriptor. The file workflow
+                // alone owns admission, final close, cancellation and failed retry.
+                const reader = new ZipArtifactReader(jar, "zip", JAR_METADATA_READ_MAX_BYTES, { handle, initial: await handle.stat() });
+                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",
+                ]);
+                for await (const entry of reader.entries(options.signal)) {
+                    if (entry.kind === "file" && !entry.encrypted)
+                        missing.delete(entry.path);
+                    if (missing.size === 0)
+                        return;
+                }
+                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],
+                }, "jar");
+            }
+            catch (cause) {
+                if (cause instanceof JadxConfigurationFailure ||
+                    (cause instanceof ArtifactReaderFailure &&
+                        cause.reason === "cancelled"))
+                    throw cause;
+                throw archiveInspectionFailure(jar, cause);
+            }
+        }));
     }
     catch (cause) {
-        if (signal?.aborted === true)
+        if (cause instanceof ArtifactFileCleanupFailure) {
+            const physical = cause.fileCleanupFailure;
+            const cleanup = new ProviderCleanupError("jadx", [jar], {
+                phase: "jar-inspection",
+                ...(physical.outcome.kind === "completed"
+                    ? { archive_observation: { jar_path: jar, required_classes: true } }
+                    : {}),
+            }, { operation, cause: physical.cleanupCause });
+            bindArtifactFileCleanup(cause, cleanup);
+            const primary = physical.outcome.kind === "failed"
+                ? archiveAnalysisFailure(jar, physical.outcome.cause, options)
+                : physical.completionCancellation === undefined
+                    ? undefined
+                    : archiveCancellation(physical.completionCancellation.reason, options, {
+                        archive_observation: {
+                            jar_path: jar,
+                            required_classes: true,
+                        },
+                    });
+            if (primary === undefined)
+                throw cleanup;
+            throw analysisErrorWithCleanupFailure(primary, cleanup, operation).bindCleanupDependencies([primary, cleanup]);
+        }
+        if (cause instanceof ArtifactFileCancelled) {
+            throw archiveCancellation(cause.fileCancellation.reason, options, {
+                archive_observation: { jar_path: jar, required_classes: true },
+            });
+        }
+        if (cause instanceof ArtifactReaderFailure) {
+            if (cause.reason === "cancelled")
+                throw archiveCancellation(cause.cancellation?.reason, options);
+            throw analysisClientFailureForOperation(cause, "jadx", operation);
+        }
+        if (cause instanceof AnalysisError ||
+            cause instanceof JadxConfigurationFailure)
             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,
-        }, "jar", cause);
-    }
-    finally {
-        await reader.close();
+        throw archiveInspectionFailure(jar, cause);
     }
-    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] }, "jar");
+};
+const archiveInspectionFailure = (jar, cause) => {
+    const reason = cause instanceof Error ? cause.message : String(cause);
+    return 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,
+    }, "jar", cause);
+};
+const archiveAnalysisFailure = (jar, cause, options) => {
+    if (cause instanceof AnalysisError)
+        return cause;
+    if (cause instanceof ArtifactReaderFailure && cause.reason === "cancelled")
+        return archiveCancellation(cause.cancellation?.reason, options);
+    return projectConfigurationFailure(options.operation ?? "inspect_jadx_configuration", cause instanceof JadxConfigurationFailure
+        ? cause
+        : archiveInspectionFailure(jar, cause));
+};
+const archiveCancellation = (reason, options, diagnostics) => {
+    const operation = options.operation ?? "inspect_jadx_configuration";
+    return options.operationDeadline?.signal.aborted === true &&
+        reason === options.operationDeadline.signal.reason
+        ? new AnalysisTimeoutError(operation, options.operationDeadline.timeoutMs, {
+            cause: reason,
+            diagnostics,
+        })
+        : new AnalysisCancelledError(operation, { cause: reason, diagnostics });
 };
 const requireSupportedHost = () => {
     if (process.platform === "linux" || process.platform === "darwin")
@@ -272,7 +379,7 @@ const resolveJava = async (environment, signal) => {
             return executable;
         const path = Object.entries(environment).find(([key]) => key.toLowerCase() === "path")?.[1] ?? "";
         for (const directory of [process.cwd(), ...path.split(delimiter)]) {
-            signal?.throwIfAborted();
+            throwIfJadxInterrupted(signal);
             // Windows PATH commonly quotes individual entries containing spaces.
             const selected = directory.startsWith('"') && directory.endsWith('"')
                 ? directory.slice(1, -1)
@@ -331,80 +438,21 @@ const resolveJvmArguments = (environment) => {
     }
     return result;
 };
-const inspectJavaRuntime = async (java, environment, signal) => {
-    let stdout;
-    let stderr;
-    try {
-        ({ stdout, stderr } = await execFileOutput(java, ["--list-modules"], {
-            env: { ...environment },
-            timeout: JAVA_MODULE_LISTING_TIMEOUT_MS,
-            maxBuffer: JAVA_MODULE_LISTING_MAX_OUTPUT_BYTES,
-            ...(signal === undefined ? {} : { signal }),
-        }));
-    }
-    catch (cause) {
-        if (signal?.aborted === true)
-            throw cause;
-        const output = execFileOutputFailure(cause);
-        if (output === undefined)
-            throw cause;
-        const diagnostics = {
-            java_executable: java,
-            phase: "module-inspection",
-            exit_code: typeof output.code === "number" ? output.code : null,
-            process_error_code: typeof output.code === "string" ? output.code : null,
-            signal: output.signal,
-            killed: output.killed,
-            stdout: output.stdout,
-            stderr: output.stderr,
-            output_truncated: output.outputTruncated,
-        };
-        if (output.outputTruncated)
-            throw configurationFailure("version_unresolved", `The selected Java launcher ${java} exceeded the ${JAVA_MODULE_LISTING_MAX_OUTPUT_BYTES / (1024 * 1024)} MiB output budget while listing modules. REA retained partial output but could not establish compiler or version availability. Inspect the selected launcher for verbose or unbounded output; ` +
-                "java --list-modules should return a concise module listing.", {
-                ...diagnostics,
-                failure: "output_limit",
-                output_limit_bytes: JAVA_MODULE_LISTING_MAX_OUTPUT_BYTES,
-            }, "java_probe", cause);
-        if (output.killed)
-            throw configurationFailure("version_unresolved", `The selected Java launcher ${java} was terminated or did not finish the module-listing probe within ${JAVA_MODULE_LISTING_TIMEOUT_MS / 1000} seconds. Inspect the launcher and its startup responsiveness, then verify it returns compiler and version modules with java --list-modules.`, {
-                ...diagnostics,
-                failure: "probe_terminated",
-                deadline_ms: JAVA_MODULE_LISTING_TIMEOUT_MS,
-            }, "java_probe", cause);
-        throw configurationFailure("runtime_missing", `Cannot inspect selected Java runtime ${java}: ${output.stderr.trim() || errorText(cause)}. Select a full JDK including jdk.compiler via JAVA_HOME or PATH; verify it with java --list-modules.`, diagnostics, "java_runtime", cause);
+const readOperationTimeout = (environment) => {
+    const value = environment.REA_JADX_OPERATION_TIMEOUT_MS;
+    if (value === undefined)
+        return DEFAULT_JADX_OPERATION_TIMEOUT_MS;
+    const parsed = providerStartupTimeoutSchema.safeParse(value);
+    if (parsed.success)
+        return parsed.data;
+    throw configurationFailure("open_options_invalid", `REA_JADX_OPERATION_TIMEOUT_MS must be a decimal millisecond count from 1 to 2147483647; received ${value}.`, { setting: "REA_JADX_OPERATION_TIMEOUT_MS", value }, "operation_timeout");
+};
+const inspectJavaRuntime = async (java, environment, options) => {
+    const result = await inspectJadxJava(java, environment, options);
+    if (!result.ok) {
+        const failure = result.error;
+        throw configurationFailure(failure.code, failure.message, failure.diagnostics, failure.kind);
     }
-    const compiler = /^jdk\.compiler(?:@|$)/mu.test(stdout);
-    if (!compiler)
-        throw configurationFailure("runtime_missing", `Selected Java runtime ${java} does not provide jdk.compiler. Select a full JDK including jdk.compiler via JAVA_HOME or PATH; verify it with java --list-modules. A JRE cannot compile REA's source bridge.`, {
-            java_executable: java,
-            phase: "module-inspection",
-            jdk_compiler: false,
-            stdout,
-            stderr,
-            output_truncated: false,
-        }, "java_runtime");
-    const major = /^java\.base@(\d+)(?:[.+_-]|$)/mu.exec(stdout)?.[1];
-    if (major === undefined)
-        throw configurationFailure("version_unresolved", `The selected Java launcher ${java} did not report a parseable java.base version in its module listing. Inspect the launcher output and verify it with java --list-modules.`, {
-            java_executable: java,
-            phase: "module-inspection",
-            jdk_compiler: true,
-            java_major: null,
-            stdout,
-            stderr,
-            output_truncated: false,
-        }, "java_probe");
-    if (Number(major) < 17)
-        throw configurationFailure("unsupported_version", `Selected Java runtime ${java} must be JDK 17 or newer and include jdk.compiler; verify it with java --list-modules.`, {
-            java_executable: java,
-            phase: "module-inspection",
-            jdk_compiler: true,
-            java_major: major ?? null,
-            stdout,
-            stderr,
-            output_truncated: false,
-        }, "java_runtime");
 };
 const configurationFailure = (code, message, diagnostics, kind, cause) => new JadxConfigurationFailure(code, message, diagnostics, kind, cause === undefined ? undefined : { cause });
 const errorText = (cause) => cause instanceof Error ? cause.message : String(cause);

package/dist/android/JadxDoctor.js

@@ -1,8 +1,11 @@
 import { inspectJadxAvailability, JADX_FAILURE_KINDS, projectJadxFailureOutcome, } from "./JadxConfiguration.js";
 /** Project the validated JADX configuration into the doctor contract. */
-export const inspectJadxProvider = async (environment) => {
+export const inspectJadxProvider = async (environment, resourceOwner, signal) => {
     const configured = environment.REA_JADX_MCP_JAR !== undefined;
-    const availability = await inspectJadxAvailability(environment);
+    const availability = await inspectJadxAvailability(environment, {
+        resourceOwner,
+        signal,
+    });
     // diagnostics is a loosely-typed JsonValue map; guard the published path
     // even though the success path always sets jar_path today.
     const jarPath = availability.status === "available" &&
@@ -26,6 +29,7 @@ export const inspectJadxProvider = async (environment) => {
                 ...optionalEntry("JAVA_HOME", environment.JAVA_HOME),
                 ...optionalEntry("REA_JADX_HEAP_MIB", environment.REA_JADX_HEAP_MIB),
                 ...optionalEntry("REA_JADX_ACTIVE_PROCESSOR_COUNT", environment.REA_JADX_ACTIVE_PROCESSOR_COUNT),
+                ...optionalEntry("REA_JADX_OPERATION_TIMEOUT_MS", environment.REA_JADX_OPERATION_TIMEOUT_MS),
             },
         checks: [configurationCheck(configured, availability, jarPath)],
     };
@@ -38,13 +42,17 @@ const optionalEntry = (name, value) => (value === undefined ? {} : { [name]: val
 const configurationCheck = (configured, availability, jarPath) => {
     const code = availability.status === "unavailable" ? availability.code : null;
     if (availability.status === "available" && jarPath !== undefined) {
+        const operationTimeout = availability.diagnostics["operation_timeout_ms"];
         return {
             name: "configuration",
             ok: true,
             code: null,
-            detail: `JADX MCP bridge JAR validated at ${jarPath}; its path is recorded for agent registrations.`,
+            detail: `JADX MCP bridge JAR validated at ${jarPath}; its path is recorded for agent registrations. This checks configuration, not whether a selected APK fits in the worker's memory.`,
             remediation: null,
             classification: "config_drift",
+            ...(typeof operationTimeout === "number"
+                ? { details: { operation_timeout_ms: operationTimeout } }
+                : {}),
         };
     }
     // The failure kind is tagged at the configuration boundary; project its

package/dist/android/JadxFailure.js

@@ -0,0 +1,154 @@
+import { JadxInterruption } from "./JadxInterruption.js";
+import { z } from "zod";
+import { AnalysisError } from "../domain/analysisErrorBase.js";
+import { AnalysisCancelledError, AnalysisCapabilityUnavailableError, AnalysisOutputError, AnalysisTimeoutError, } from "../domain/analysisErrorCore.js";
+import { ProviderAdapterError } from "../domain/providerAdapterError.js";
+import { ProviderCleanupError } from "../domain/providerCleanupError.js";
+import { analysisErrorWithCleanupFailure } from "../domain/analysisErrorCleanup.js";
+import { stableFileHashCause, StableFileHashFailure, } from "../filesystem/StableFileHash.js";
+import { RegularFileCleanupFailure, regularFileCancellation, } from "../filesystem/OwnedRegularFile.js";
+/** Freeze failure selection now; read diagnostics once after owned finalization. */
+export const captureJadxFailure = (context) => {
+    const observed = observeJadxFailure(context);
+    const partial = context.session?.partialObservation();
+    let projected;
+    return () => {
+        if (projected === undefined) {
+            projected =
+                observed instanceof AnalysisError
+                    ? observed
+                    : presentDiagnosticFailure(observed);
+            if (partial !== undefined)
+                projected.retainPartialObservation(partial);
+        }
+        return projected;
+    };
+};
+const observeJadxFailure = (context) => {
+    const { cause, request, timeout, timeoutMs, signal, session } = context;
+    const transport = session?.transport;
+    const observed = transport?.observedFailure();
+    const diagnostic = {
+        operation: request.operation,
+        transport,
+        cause,
+    };
+    const physicalFailure = (failureCause) => session !== undefined && !session.initialized()
+        ? {
+            ...diagnostic,
+            cause: failureCause,
+            kind: "startup",
+            command: session.transport.options.command,
+        }
+        : { ...diagnostic, cause: failureCause, kind: "execution" };
+    const interruptionFailure = (reason) => {
+        if (timeout.aborted && reason === timeout.reason)
+            return {
+                ...diagnostic,
+                cause: reason,
+                kind: "timeout",
+                timeoutMs,
+            };
+        if (signal?.aborted === true && reason === signal.reason)
+            return { ...diagnostic, cause: reason, kind: "cancelled" };
+        return physicalFailure(reason);
+    };
+    // Caller reasons are opaque even when they are instances of our own errors.
+    // Only the owning interruption boundary can select this path; a recorded
+    // physical failure keeps precedence over a later abort using the same object.
+    if (observed?.kind === "interrupted" && cause === observed.reason)
+        return interruptionFailure(observed.reason);
+    if (cause instanceof JadxInterruption && observed === undefined)
+        return interruptionFailure(cause.reason);
+    const cancellation = regularFileCancellation(cause);
+    const cancellationError = cancellation === undefined
+        ? undefined
+        : timeout.aborted && cancellation.reason === timeout.reason
+            ? new AnalysisTimeoutError(request.operation, timeoutMs, {
+                cause: cancellation.reason,
+            })
+            : new AnalysisCancelledError(request.operation, {
+                cause: cancellation.reason,
+            });
+    if (cause instanceof RegularFileCleanupFailure) {
+        const primaryCause = cause.outcome.kind === "failed"
+            ? stableFileHashCause(cause.outcome.cause)
+            : cause;
+        const primary = cancellationError ??
+            (primaryCause instanceof AnalysisError
+                ? primaryCause
+                : new ProviderAdapterError("jadx", request.operation, {
+                    cause: primaryCause,
+                    userMessage: primaryCause instanceof Error
+                        ? primaryCause.message
+                        : String(primaryCause),
+                }));
+        const cleanup = new ProviderCleanupError("jadx", [cause.path], {
+            reason: cause.cleanupCause instanceof Error
+                ? cause.cleanupCause.message
+                : String(cause.cleanupCause),
+        }, { operation: request.operation, cause });
+        return analysisErrorWithCleanupFailure(primary, cleanup, request.operation);
+    }
+    if (cancellationError !== undefined)
+        return cancellationError;
+    if (cause instanceof StableFileHashFailure)
+        return new ProviderAdapterError("jadx", request.operation, {
+            cause: cause.cause,
+            userMessage: cause.message,
+        });
+    if (cause instanceof AnalysisError)
+        return cause;
+    if (cause instanceof z.ZodError)
+        return {
+            ...diagnostic,
+            kind: "output",
+            reason: "JADX response violated the pinned upstream protocol",
+        };
+    if (observed?.kind === "protocol")
+        return {
+            ...diagnostic,
+            cause: observed.cause,
+            kind: "output",
+            reason: observed.cause.message,
+        };
+    if (observed?.kind === "process")
+        return physicalFailure(observed.cause);
+    if (observed?.kind === "exit")
+        return physicalFailure(cause);
+    if (observed?.kind === "interrupted")
+        return interruptionFailure(observed.reason);
+    if (signal?.aborted === true)
+        return { ...diagnostic, cause: signal.reason, kind: "cancelled" };
+    if (timeout.aborted)
+        return { ...diagnostic, cause: timeout.reason, kind: "timeout", timeoutMs };
+    return physicalFailure(cause instanceof JadxInterruption ? cause.reason : cause);
+};
+const presentDiagnosticFailure = (failure) => {
+    const output = failure.transport?.diagnostics();
+    const options = {
+        cause: failure.cause,
+        ...(output === undefined ? {} : { capturedOutput: output }),
+    };
+    if (failure.kind === "cancelled")
+        return new AnalysisCancelledError(failure.operation, options);
+    if (failure.kind === "timeout")
+        return new AnalysisTimeoutError(failure.operation, failure.timeoutMs, options);
+    if (failure.kind === "output")
+        return new AnalysisOutputError(failure.operation, failure.reason, options);
+    if (failure.kind === "startup") {
+        const reason = `Java could not start REA's Android bridge using ${failure.command}: ${failure.cause instanceof Error ? failure.cause.message : String(failure.cause)}. ${output === undefined || output.stderr.length === 0 ? "No launcher stderr was observed." : "Review the retained launcher diagnostics."}${output?.truncated === true ? " Diagnostics are incomplete." : ""} Review the selected Java/JADX configuration; for a JVM memory limit, review REA_JADX_HEAP_MIB and inherited JVM options such as JAVA_TOOL_OPTIONS.`;
+        return new AnalysisCapabilityUnavailableError("jadx", failure.operation, reason, {
+            ...options,
+            userMessage: reason,
+        });
+    }
+    return new ProviderAdapterError("jadx", failure.operation, {
+        ...options,
+        diagnostics: {
+            reason: failure.cause instanceof Error
+                ? failure.cause.message
+                : String(failure.cause),
+        },
+    });
+};

package/dist/android/JadxInterruption.js

@@ -0,0 +1,13 @@
+/** An Android checkpoint observed interruption; the caller's reason stays opaque. */
+export class JadxInterruption extends Error {
+    reason;
+    constructor(reason) {
+        super("Android operation interrupted", { cause: reason });
+        this.reason = reason;
+        this.name = "AbortError";
+    }
+}
+export const throwIfJadxInterrupted = (signal) => {
+    if (signal?.aborted === true)
+        throw new JadxInterruption(signal.reason);
+};