rea-agents 6.4.0 → 6.5.0

package/dist/adb/AdbShellOutput.js

@@ -35,48 +35,6 @@ export const parseProcessListOutput = (stdout) => {
     }
     return { columns, processes, unparsedLines };
 };
-const LS_LINE = /^([bcdlps-][rwxstST-]{9})\s+(?:(\d+)\s+)?(\S+)\s+(\S+)\s+(?:(\d+)\s+)?([\d-]{10})\s+([\d:]{4,8})\s+(.+)$/u;
-/** Parse `ls -la` output, including `total` headers and symlink targets. */
-export const parseLsOutput = (stdout) => {
-    const entries = [];
-    const unparsedLines = [];
-    for (const rawLine of stdout.split(/\r?\n/u)) {
-        const line = rawLine.trimEnd();
-        if (line === "" || line.startsWith("total "))
-            continue;
-        const match = LS_LINE.exec(line);
-        if (match === null) {
-            if (line.trim() !== "")
-                unparsedLines.push(line);
-            continue;
-        }
-        const permissions = match[1];
-        let name = match[8].trim();
-        let linkTarget = null;
-        const linkArrow = name.indexOf(" -> ");
-        if (linkArrow !== -1 && permissions.startsWith("l")) {
-            linkTarget = name.slice(linkArrow + 4);
-            name = name.slice(0, linkArrow);
-        }
-        entries.push({
-            name,
-            kind: permissions.startsWith("d")
-                ? "directory"
-                : permissions.startsWith("l")
-                    ? "symlink"
-                    : permissions.startsWith("-")
-                        ? "file"
-                        : "other",
-            permissions,
-            owner: match[3] ?? null,
-            group: match[4] ?? null,
-            bytes: match[5] === undefined ? null : Number(match[5]),
-            date: `${match[6] ?? ""} ${match[7] ?? ""}`.trim() || null,
-            link_target: linkTarget,
-        });
-    }
-    return { entries, unparsedLines };
-};
 const FEATURE_LINE = /^feature:([^=\s]+)(?:=(0x[0-9a-fA-F]+|\d+))?$/u;
 const parseFeatureVersion = (text) => text.startsWith("0x") ? Number.parseInt(text.slice(2), 16) : Number(text);
 /** Parse `pm list features` output, including hex GL versions. */
@@ -161,7 +119,7 @@ export const parseWmDensityOutput = (stdout) => {
     }
     return { physical, override };
 };
-/** Parse the focus declarations from `dumpsys window windows`. */
+/** Parse focus declarations from `dumpsys window windows` or `displays`. */
 export const parseWindowFocusOutput = (stdout) => {
     let focusedWindow = null;
     let focusedApp = null;
@@ -197,7 +155,9 @@ export const parseDumpsysPackageOutput = (stdout) => {
             inPermissions = true;
             continue;
         }
-        if (inPermissions && /^\s{2,}[A-Za-z0-9._]+$/.test(line)) {
+        // Android 10 and 11 mark restricted entries as "NAME: restricted=true".
+        if (inPermissions &&
+            /^\s{2,}[A-Za-z0-9._]+(?:: restricted=true)?$/u.test(line)) {
             permissions += 1;
             continue;
         }
@@ -246,6 +206,8 @@ export const parseBugreportCopiedPath = (stdout) => {
     const match = /^Bug report copied to (.+)\r?$/mu.exec(stdout.trim());
     return match === null ? null : match[1];
 };
+/** Read the device's `Failure [REASON]` verdict from package-change output. */
+export const packageChangeFailureReason = (output) => /Failure \[([^\]]+)\]/u.exec(output)?.[1] ?? null;
 /**
  * Parse `adb install`/`adb uninstall` output. adb can print `Failure [...]`
  * with a zero exit code, so the text decides, not the exit status.
@@ -254,10 +216,10 @@ export const parsePackageChangeOutput = (stdout) => {
     const text = stdout.trim();
     if (/^Success$/mu.test(text))
         return { status: "success", reason: null };
-    const failure = /Failure \[([^\]]+)\]/u.exec(text);
     return {
         status: "failure",
-        reason: failure?.[1] ?? (text === "" ? null : text.slice(0, 512)),
+        reason: packageChangeFailureReason(text) ??
+            (text === "" ? null : text.slice(0, 512)),
     };
 };
 /**
@@ -272,24 +234,60 @@ export const parseResolveActivityOutput = (stdout) => {
     return lines.length === 0 ? null : lines[lines.length - 1];
 };
 /**
- * Parse `am start` output. Success prints `Starting: Intent { ... }`;
- * refusals print lines starting with `Error:` or `Warning:` and activity
- * classes that do not exist name the component.
+ * Parse the complete `am start -W` report. `Starting:` records an attempt;
+ * hard errors and any non-ok Activity Manager status determine the verdict.
  */
-export const parseAmStartOutput = (stdout) => {
-    const text = stdout.trim();
-    const starting = /^Starting:\s+Intent\s*\{(.*)\}\s*$/mu.exec(text);
-    if (starting !== null)
+export const parseAmStartOutput = (stdout, stderr = "") => {
+    const normalizedStdout = stdout.replaceAll("\r\n", "\n");
+    const starting = /^Starting:[ \t]+Intent[ \t]*\{(.*)\}[ \t]*$/mu.exec(normalizedStdout);
+    const startedActivity = starting?.[1]?.trim() ?? null;
+    const activityMatch = /^Activity:[ \t]*(.*)$/mu.exec(normalizedStdout);
+    const activity = activityMatch?.[1]?.trim() || null;
+    const statuses = [...normalizedStdout.matchAll(/^Status:[ \t]*(.*)$/gmu)].map((match) => match[1].trim());
+    const nonOkStatus = statuses.find((status) => status.toLowerCase() !== "ok");
+    const reportedStatus = nonOkStatus ?? statuses[0] ?? null;
+    const error = [normalizedStdout, stderr.replaceAll("\r\n", "\n")]
+        .flatMap((stream) => stream.split("\n"))
+        .map((line) => line.trim())
+        .map((line) => ({
+        line,
+        match: /^(?:Error|Exception)(?::|\b)(.*)$/iu.exec(line),
+    }))
+        .find(({ match }) => match !== null);
+    const errorReason = error?.match?.[1]?.trim() || error?.line || null;
+    const statusReason = nonOkStatus === ""
+        ? "am start reported an empty status"
+        : nonOkStatus === undefined
+            ? null
+            : `am start reported status: ${nonOkStatus}`;
+    const reason = errorReason ??
+        statusReason ??
+        (/^Warning:/mu.test(normalizedStdout.trim())
+            ? normalizedStdout.trim().slice(0, 512)
+            : null);
+    if (errorReason !== null || nonOkStatus !== undefined)
+        return {
+            status: "refused",
+            startedActivity,
+            activity,
+            reportedStatus,
+            reason: reason ?? "am start did not report a successful launch",
+        };
+    if (startedActivity !== null)
         return {
             status: "started",
-            startedActivity: starting[1].trim(),
+            startedActivity,
+            activity,
+            reportedStatus,
             reason: null,
         };
-    const error = /^(?:Error|Warning|Exception)(?::|\b)(.*)$/mu.exec(text);
+    const text = `${normalizedStdout}\n${stderr.replaceAll("\r\n", "\n")}`.trim();
     return {
         status: "refused",
-        startedActivity: null,
-        reason: error?.[1]?.trim() ??
+        startedActivity,
+        activity,
+        reportedStatus,
+        reason: reason ??
             (text === "" ? "am start returned no activity" : text.slice(0, 512)),
     };
 };

package/dist/android/JadxAnalysis.js

@@ -12,7 +12,7 @@ const methodsOf = (summary) => {
             reported_signature: method.signature,
             overload_index: index,
             is_constructor: method.is_constructor,
-            dex_descriptor: null,
+            dex_descriptor: method.dex_descriptor,
         };
     });
 };
@@ -79,13 +79,21 @@ const searchClasses = async (tools, request, loaded, engine) => {
             (page.items.length === 0 && classes.length < total))
             throw new AnalysisOutputError(request.operation, "JADX class pagination is incomplete");
     } while (classes.length < total);
-    if (new Set(classes).size !== classes.length || total !== loaded.class_count)
-        throw new AnalysisOutputError(request.operation, "JADX class inventory is duplicated or differs from the loaded class count");
+    if (total !== loaded.class_count)
+        throw new AnalysisOutputError(request.operation, "JADX class inventory count differs from the loaded class count");
+    const occurrences = new Map();
+    for (const name of classes)
+        occurrences.set(name, (occurrences.get(name) ?? 0) + 1);
+    const matchingNames = classes.filter((name) => name.includes(request.input.query));
+    const duplicateNames = [...occurrences]
+        .filter(([name, count]) => count > 1 && name.includes(request.input.query))
+        .map(([name, count]) => ({ name, occurrences: count }));
     return androidResultSchemas.search_android_classes.parse({
         engine,
         query: request.input.query,
         total_classes: total,
-        matches: classes.filter((name) => name.includes(request.input.query)),
+        matches: matchingNames,
+        duplicate_names: duplicateNames,
         coverage: "complete",
     });
 };
@@ -159,18 +167,29 @@ export const analyzeJadxRequest = async (tools, request, loaded, engine) => {
 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, `References require a unique method name; ${summary.full_name}.${methodName} has ${candidates.length} overloads. No unambiguous reference result is available.`);
+    if (methodName === undefined && request.input.overload_index !== undefined)
+        inputFailure(request, "overload_index", "Method name is required for an overload index.");
+    if (candidates.length > 1 && request.input.overload_index === undefined)
+        inputFailure(request, "overload_index", `Select one of ${candidates.length} overloads: ${candidates.map((method) => `${method.overload_index}: ${method.reported_signature}`).join("; ")}`);
+    const index = request.input.overload_index ?? 0;
+    const selected = methodName === undefined ? undefined : candidates[index];
+    if (methodName !== undefined && selected === undefined)
+        inputFailure(request, "overload_index", `Index ${index} is outside the ${candidates.length} matching overloads.`);
     const expectedTarget = methodName === undefined
         ? summary.full_name
         : `${summary.full_name}.${methodName}`;
     const xrefs = jadxXrefsSchema.parse(await tools.json(methodName === undefined ? "get_xrefs_to_class" : "get_xrefs_to_method", {
         class_name: summary.full_name,
-        ...(methodName === undefined ? {} : { method_name: methodName }),
+        ...(methodName === undefined
+            ? {}
+            : { method_name: methodName, overload_index: index }),
         limit: 2_147_483_647,
         resolve_line: false,
     }));
     if (xrefs.target !== expectedTarget ||
+        (selected !== undefined &&
+            (xrefs.overload_index !== index ||
+                xrefs.reported_signature !== selected.reported_signature)) ||
         xrefs.total !== xrefs.count ||
         xrefs.count !== xrefs.items.length)
         throw new AnalysisOutputError(request.operation, "JADX references are incomplete or refer to another target");
@@ -178,6 +197,9 @@ const traceReferences = async (tools, request, summary, engine) => {
         engine,
         class_name: summary.full_name,
         method_name: methodName ?? null,
+        overload_index: selected?.overload_index ?? null,
+        reported_signature: selected?.reported_signature ?? null,
+        dex_descriptor: selected?.dex_descriptor ?? null,
         total: xrefs.total,
         references: xrefs.items.map((reference) => ({
             kind: reference.kind,
@@ -187,7 +209,10 @@ const traceReferences = async (tools, request, summary, engine) => {
             top_class: reference.top_class,
             source_line: null,
             dex_offset: null,
+            direct_invokes: reference.direct_invokes ?? null,
+            direct_invokes_exhaustive: reference.direct_invokes_exhaustive ?? null,
         })),
         coverage: "complete",
+        reference_unit: "using_node",
     });
 };

package/dist/android/JadxConfiguration.js

@@ -1,23 +1,92 @@
 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 { ZipArtifactReader } from "../artifacts/ZipArtifactReader.js";
 import { execFileOutput, execFileOutputFailure, } from "../process/ExecFileOutput.js";
-import { JADX_JAR_CONFIGURATION_REMEDIATION } from "./JadxRelease.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;
 // 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;
+/** Runtime mirror of JadxFailureKind for validating the loose diagnostics tag. */
+export const JADX_FAILURE_KINDS = [
+    "windows_native_artifact",
+    "windows_native_runtime",
+    "java_runtime",
+    "java_home",
+    "jvm_options",
+    "jar",
+    "java_probe",
+    "unsupported_host",
+];
+/**
+ * Project the boundary-owned remediation and classification for a failure
+ * kind. A null kind (missing or corrupt tag) keeps JAR guidance, matching
+ * the previous fallthrough for unclassified failures.
+ */
+export const projectJadxFailureOutcome = (kind, configured) => {
+    const drift = configured ? "config_drift" : "missing_analysis_engine";
+    switch (kind) {
+        case "windows_native_artifact":
+            return {
+                remediation: JADX_WINDOWS_NATIVE_REMEDIATION,
+                classification: "missing_dependency",
+            };
+        case "windows_native_runtime":
+            return {
+                remediation: JADX_WINDOWS_NATIVE_REMEDIATION,
+                classification: "runtime_failure",
+            };
+        case "java_runtime":
+            return {
+                remediation: JADX_JAVA_RUNTIME_REMEDIATION,
+                classification: "missing_dependency",
+            };
+        case "java_home":
+            return {
+                remediation: JADX_JAVA_RUNTIME_REMEDIATION,
+                classification: drift,
+            };
+        case "jvm_options":
+            return {
+                remediation: JADX_JVM_OPTIONS_REMEDIATION,
+                classification: drift,
+            };
+        case "jar":
+            return {
+                remediation: JADX_JAR_CONFIGURATION_REMEDIATION,
+                classification: drift,
+            };
+        case "java_probe":
+            return {
+                remediation: JADX_JAVA_PROBE_REMEDIATION,
+                classification: drift,
+            };
+        case "unsupported_host":
+            return {
+                remediation: JADX_UNSUPPORTED_HOST_REMEDIATION,
+                classification: "unsupported_host",
+            };
+        case null:
+            return {
+                remediation: JADX_JAR_CONFIGURATION_REMEDIATION,
+                classification: drift,
+            };
+    }
+};
 class JadxConfigurationFailure extends Error {
     code;
     diagnostics;
-    constructor(code, message, diagnostics, options) {
+    kind;
+    constructor(code, message, diagnostics, kind, options) {
         super(message, options);
         this.code = code;
         this.diagnostics = diagnostics;
+        this.kind = kind;
     }
 }
 /** Inspect the same JAR and Java prerequisites that gate actual execution. */
@@ -45,7 +114,7 @@ export const inspectJadxAvailability = async (environment, signal) => {
                 status: "unavailable",
                 code: cause.code,
                 reason: cause.message,
-                diagnostics: cause.diagnostics,
+                diagnostics: { ...cause.diagnostics, failure_kind: cause.kind },
             };
         throw cause;
     }
@@ -134,45 +203,66 @@ const requireEngineArchive = async (jar, signal) => {
             phase: "jar-inspection",
             archive_error: reason,
             maximum_metadata_read_bytes: JAR_METADATA_READ_MAX_BYTES,
-        }, cause);
+        }, "jar", 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] });
+    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 requireSupportedHost = () => {
     if (process.platform === "linux" || process.platform === "darwin")
         return;
     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, {
+        if (loaded.available) {
+            if (loaded.authority.inspection.protocolStdin === true)
+                return;
+            throw configurationFailure("runtime_missing", "The bundled Windows native artifact lacks owned protocol stdin; use a matching current Windows x64 REA package.", {
+                platform: process.platform,
+                architecture: process.arch,
+                phase: "process-ownership",
+                owned_protocol_stdin: false,
+            }, "windows_native_artifact");
+        }
+        const readiness = inspectWindowsNativeReadiness(process.platform, loaded);
+        throw configurationFailure(readiness.available ? "runtime_unavailable" : readiness.code, readiness.available
+            ? "Windows native readiness disagreed with the native loader result."
+            : readiness.reason, {
             platform: process.platform,
             architecture: process.arch,
             phase: "process-ownership",
             owned_protocol_stdin: false,
-        });
+            ...(readiness.available
+                ? {}
+                : {
+                    failure_stage: readiness.failureStage,
+                    remediation: readiness.remediation,
+                }),
+        }, readiness.available
+            ? "windows_native_runtime"
+            : readiness.code === "unsupported_host"
+                ? "unsupported_host"
+                : readiness.code === "runtime_missing"
+                    ? "windows_native_artifact"
+                    : "windows_native_runtime");
     }
-    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 });
+    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 }, "unsupported_host");
 };
 const resolveJar = async (environment) => {
     const jar = environment.REA_JADX_MCP_JAR;
     if (jar === undefined || !isAbsolute(jar))
-        throw configurationFailure("not_configured", JADX_JAR_CONFIGURATION_REMEDIATION, { jar_configured: false });
+        throw configurationFailure("not_configured", JADX_JAR_CONFIGURATION_REMEDIATION, { jar_configured: false }, "jar");
     try {
         await access(jar, constants.R_OK);
         if (!(await stat(jar)).isFile())
-            throw configurationFailure("executable_missing", `REA_JADX_MCP_JAR is not a regular file: ${jar}`, { jar_path: jar });
+            throw configurationFailure("executable_missing", `REA_JADX_MCP_JAR is not a regular file: ${jar}`, { jar_path: jar }, "jar");
         return await realpath(jar);
     }
     catch (cause) {
         if (cause instanceof JadxConfigurationFailure)
             throw cause;
-        throw configurationFailure("executable_missing", `Cannot read REA_JADX_MCP_JAR ${jar}: ${cause instanceof Error ? cause.message : String(cause)}`, { jar_path: jar }, cause);
+        throw configurationFailure("executable_missing", `Cannot read REA_JADX_MCP_JAR ${jar}: ${cause instanceof Error ? cause.message : String(cause)}`, { jar_path: jar }, "jar", cause);
     }
 };
 const resolveJava = async (environment, signal) => {
@@ -199,14 +289,14 @@ const resolveJava = async (environment, signal) => {
                     "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 inspect selected Java executable ${candidate}: ${errorText(cause)}`, { java_executable: candidate }, "java_runtime", 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 });
+        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 }, "java_runtime");
     }
     if (isAbsolute(environment.JAVA_HOME))
         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 });
+    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 }, "java_home");
 };
 const requireJavaHomeExecutable = async (javaHome, java) => {
     if (javaHome === undefined)
@@ -215,12 +305,12 @@ const requireJavaHomeExecutable = async (javaHome, java) => {
         await access(java, constants.R_OK | constants.X_OK);
         if ((await stat(java)).isFile())
             return;
-        throw configurationFailure("runtime_missing", `JAVA_HOME java is not a regular file: ${java}`, { java_executable: java });
+        throw configurationFailure("runtime_missing", `JAVA_HOME java is not a regular file: ${java}`, { java_executable: java }, "java_runtime");
     }
     catch (cause) {
         if (cause instanceof JadxConfigurationFailure)
             throw cause;
-        throw configurationFailure("runtime_missing", `Cannot execute JAVA_HOME java ${java}: ${cause instanceof Error ? cause.message : String(cause)}`, { java_executable: java }, cause);
+        throw configurationFailure("runtime_missing", `Cannot execute JAVA_HOME java ${java}: ${cause instanceof Error ? cause.message : String(cause)}`, { java_executable: java }, "java_runtime", cause);
     }
 };
 const resolveJvmArguments = (environment) => {
@@ -233,10 +323,10 @@ const resolveJvmArguments = (environment) => {
         if (value === undefined)
             continue;
         if (!/^[1-9]\d*$/u.test(value) || !Number.isSafeInteger(Number(value)))
-            throw configurationFailure("open_options_invalid", `${name} must be a positive safe integer; received ${value}.`, { setting: name, value });
+            throw configurationFailure("open_options_invalid", `${name} must be a positive safe integer; received ${value}.`, { setting: name, value }, "jvm_options");
         if (name === "REA_JADX_ACTIVE_PROCESSOR_COUNT" &&
             Number(value) > 2_147_483_647)
-            throw configurationFailure("open_options_invalid", `${name} exceeds the JVM's signed 32-bit processor-count range.`, { setting: name, value });
+            throw configurationFailure("open_options_invalid", `${name} exceeds the JVM's signed 32-bit processor-count range.`, { setting: name, value }, "jvm_options");
         result.push(`${prefix}${value}${suffix}`);
     }
     return result;
@@ -275,14 +365,14 @@ const inspectJavaRuntime = async (java, environment, signal) => {
                 ...diagnostics,
                 failure: "output_limit",
                 output_limit_bytes: JAVA_MODULE_LISTING_MAX_OUTPUT_BYTES,
-            }, cause);
+            }, "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,
-            }, 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, cause);
+            }, "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 compiler = /^jdk\.compiler(?:@|$)/mu.test(stdout);
     if (!compiler)
@@ -293,7 +383,7 @@ const inspectJavaRuntime = async (java, environment, signal) => {
             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.`, {
@@ -304,7 +394,7 @@ const inspectJavaRuntime = async (java, environment, signal) => {
             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,
@@ -314,7 +404,7 @@ const inspectJavaRuntime = async (java, environment, signal) => {
             stdout,
             stderr,
             output_truncated: false,
-        });
+        }, "java_runtime");
 };
-const configurationFailure = (code, message, diagnostics, cause) => new JadxConfigurationFailure(code, message, diagnostics, cause === undefined ? undefined : { cause });
+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

@@ -0,0 +1,115 @@
+import { inspectJadxAvailability, JADX_FAILURE_KINDS, projectJadxFailureOutcome, } from "./JadxConfiguration.js";
+/** Project the validated JADX configuration into the doctor contract. */
+export const inspectJadxProvider = async (environment) => {
+    const configured = environment.REA_JADX_MCP_JAR !== undefined;
+    const availability = await inspectJadxAvailability(environment);
+    // 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" &&
+        typeof availability.diagnostics["jar_path"] === "string"
+        ? availability.diagnostics["jar_path"]
+        : undefined;
+    const available = availability.status === "available" && jarPath !== undefined;
+    // Preserve the caller-selected JAR path (it may be a stable symlink) and
+    // the validated JAVA_HOME selection; the resolved jarPath stays in
+    // diagnostics as inspection evidence.
+    const configuredJar = environment.REA_JADX_MCP_JAR;
+    return {
+        id: "jadx",
+        configured,
+        available,
+        providerVersion: null,
+        registrationEnvironment: jarPath === undefined || configuredJar === undefined
+            ? {}
+            : {
+                REA_JADX_MCP_JAR: configuredJar,
+                ...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),
+            },
+        checks: [configurationCheck(configured, availability, jarPath)],
+    };
+};
+/**
+ * Publish a caller-selected variable only when explicitly set; never persist
+ * ambient inheritance. Values are validated before this point.
+ */
+const optionalEntry = (name, value) => (value === undefined ? {} : { [name]: value });
+const configurationCheck = (configured, availability, jarPath) => {
+    const code = availability.status === "unavailable" ? availability.code : null;
+    if (availability.status === "available" && jarPath !== undefined) {
+        return {
+            name: "configuration",
+            ok: true,
+            code: null,
+            detail: `JADX MCP bridge JAR validated at ${jarPath}; its path is recorded for agent registrations.`,
+            remediation: null,
+            classification: "config_drift",
+        };
+    }
+    // The failure kind is tagged at the configuration boundary; project its
+    // remediation and classification here instead of reinterpreting the
+    // phase/setting evidence. Every failed check keeps a remediation.
+    const kind = availability.status === "unavailable"
+        ? asFailureKind(availability.diagnostics["failure_kind"])
+        : null;
+    const outcome = projectJadxFailureOutcome(kind, configured);
+    return {
+        name: "configuration",
+        ok: false,
+        code,
+        detail: availability.status === "available"
+            ? "Validated JADX configuration reported no JAR path."
+            : availability.reason,
+        remediation: outcome.remediation,
+        classification: outcome.classification,
+        ...(kind === "java_probe" && availability.status === "unavailable"
+            ? { details: probeDetails(availability.diagnostics) }
+            : kind !== null &&
+                kind.startsWith("windows_native_") &&
+                availability.status === "unavailable"
+                ? { details: windowsNativeFailureDetails(availability.diagnostics) }
+                : {}),
+    };
+};
+const windowsNativeFailureDetails = (diagnostics) => {
+    const details = {};
+    for (const key of ["failure_stage", "remediation"]) {
+        const value = diagnostics[key];
+        if (value !== undefined)
+            details[key] = value;
+    }
+    return details;
+};
+/** Validate the loose diagnostics tag against the boundary's failure kinds. */
+const asFailureKind = (value) => typeof value === "string" &&
+    JADX_FAILURE_KINDS.includes(value)
+    ? value
+    : null;
+/**
+ * Project bounded Java probe metadata for the doctor report. The full
+ * stdout/stderr can reach the 1 MiB probe budget, so only the bounded
+ * outcome metadata is carried; the message already references the retained
+ * output.
+ */
+const probeDetails = (diagnostics) => {
+    const details = {};
+    for (const key of [
+        "java_executable",
+        "failure",
+        "output_truncated",
+        "exit_code",
+        "process_error_code",
+        "signal",
+        "killed",
+        "output_limit_bytes",
+        "deadline_ms",
+        "jdk_compiler",
+        "java_major",
+    ]) {
+        const value = diagnostics[key];
+        if (value !== undefined)
+            details[key] = value;
+    }
+    return details;
+};

package/dist/android/JadxMcpTransport.js

@@ -155,9 +155,11 @@ export class JadxMcpTransport {
                 this.#appendFrame(fragment, frameBytes);
                 if (newline === -1)
                     return;
-                const line = this.#frameBuffer
-                    .subarray(0, this.#frameLength)
-                    .toString("utf8");
+                const line = new TextDecoder("utf-8", {
+                    fatal: true,
+                    // Preserve a leading BOM so the JSON-RPC parser can reject it.
+                    ignoreBOM: true,
+                }).decode(this.#frameBuffer.subarray(0, this.#frameLength));
                 this.#frameBuffer = Buffer.alloc(0);
                 this.#frameLength = 0;
                 this.onmessage?.(deserializeMessage(line));