fix(android): classify a pre-handshake JADX heap shortage as a resource limit

A worker heap too small for REA's bridge stops the JVM before the protocol
handshake, so the launcher's retained stderr is the only evidence, and the
failure was reported as capability_unavailable with configuration advice.
When that stderr carries HotSpot's java.lang.OutOfMemoryError heap reasons,
report resource_constraint for memory with observed_max_heap_bytes null and
the same REA_JADX_HEAP_MIB remediation the bridge-reported heap failure uses,
now shared and stating -Xmx precedence. Other launcher stops are unchanged.

Refs #3517
Supersedes #3573

Co-Authored-By: gensokyo-dev <342580529+gensokyo-dev@users.noreply.github.com>
This commit is contained in:
Antrulyandgensokyo-dev authored and Ysopwnable committed 2026-11-14 15:25:02 +01:00
1 parent 8296d81cd4
commit f8fc5be364
9 files changed
+104 -4

No files matched your search

+7 -3
View File
@@ -665,9 +665,13 @@ uses native memory. A typed JVM memory allocation failure during APK loading
reports `resource_constraint` with the observed maximum heap in bytes. Known
heap failures name `REA_JADX_HEAP_MIB` in remediation; other memory regions
remain unknown. A healthy doctor configuration check does not establish that
any particular APK fits. Failures before the bridge can report a typed result
and upstream errors from other operations retain their existing diagnostics;
error text alone does not establish memory exhaustion.
any particular APK fits. If the launcher stops before the bridge answers and
its retained stderr carries HotSpot's `java.lang.OutOfMemoryError: Java heap
space` or `GC overhead limit exceeded`, REA reports `resource_constraint` with
`observed_max_heap_bytes: null`, since no runtime fact measured the heap, and
the same `REA_JADX_HEAP_MIB` remediation. Other failures before the bridge can
report a typed result and upstream errors from other operations retain their
existing diagnostics; error text alone does not establish memory exhaustion.
Independent REA instances have independent queues. Whole
operations have a **120-second** execution deadline by default, starting after
+1
View File
@@ -124,3 +124,4 @@ Then rerun this installer.",implemented,verified by shell branch inspection
91,src/application/binaryDiagnostics/ByteEntropyService.ts (issues); src/domain/analysisErrorPresentation.ts (recovery),Invalid file or window,Expected a regular file.; Selected file could not be found.; Selected byte window starts beyond the end of the file.; Selected byte window extends beyond the end of the file.; File size exceeds exact numeric offset representation.,Invalid selection cannot produce complete entropy Evidence,"Read the declared input schema or CLI usage for inspect_byte_entropy; if using MCP and the catalog may be stale, call tools/list. Correct the listed fields, then retry. Do not repeat the unchanged call.",unchanged,Executed CLI/stdio MCP: path/offset/length refusals and tiny + system-binary controls; shared canonical recovery; service/MCP tests check classification and fields; remaining listed errors source-inspected
92,src/domain/analysisView/byteEntropyView.ts,Non-summary entropy view,Byte entropy Evidence supports the summary view; retrieve parent Evidence for the complete block series.,Unsupported view selection,Use the summary view or retrieve complete parent Evidence,implemented,typed input rejection
93,src/windows/WindowsNativeLoader.ts:load refused,Windows refuses to load the digest-verified native addon (for example Smart App Control or App Control policy),"REA Windows native controls are unavailable: Windows refused to load the verified native/windows/build/rea-windows-x64.node: {OS error} The file matched the package manifest, so restoring or reinstalling it will not help. ...",Previous artifact copy told users to restore or rebuild files that were already intact,"Name the OS refusal, say restoring cannot help, state that Ghidra and JADX need native controls while setup can still register clients, and point to a policy-allowed host or a maintainer-signed build",implemented,simulated loader refusal unit test; real Smart App Control block not reproduced
94,src/android/JadxFailure.ts:startup failure,"JADX worker heap too small for REA's bridge, so the JVM stops before the protocol handshake","Java could not start REA's Android bridge using <java>: Connection closed. Review the retained launcher diagnostics. 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.","Buried: reported as capability_unavailable, so a caller cannot tell a heap limit from a missing JDK","The JADX worker JVM ran out of heap before REA's Android bridge answered. Increase REA_JADX_HEAP_MIB (MiB) in the environment that starts REA, within the host or container memory budget. REA passes it as an explicit -Xmx, so JAVA_TOOL_OPTIONS and JDK_JAVA_OPTIONS set the heap only while it is unset, and _JAVA_OPTIONS overrides it. An observed heap is this run's limit, not the heap the APK requires.",implemented,child-process MCP fixture (start-heap-exhausted) integration test and stderr classification test
1 harm_rank location trigger current_copy user_risk proposed_replacement implementation_status verification_result
124
125
126
127
+18
View File
@@ -6,6 +6,7 @@ import {
AnalysisCancelledError,
AnalysisCapabilityUnavailableError,
AnalysisOutputError,
AnalysisResourceConstraintError,
AnalysisTimeoutError,
} from "../domain/analysisErrorCore.js";
import { ProviderAdapterError } from "../domain/providerAdapterError.js";
@@ -24,6 +25,8 @@ import {
import { androidSnapshotCopy } from "./AndroidTargetSnapshot.js";
import type { JadxSession } from "./JadxSession.js";
import type { JadxMcpTransport } from "./JadxMcpTransport.js";
import { jadxHeapExhausted } from "./JadxProtocol.js";
import { JADX_HEAP_REMEDIATION } from "./JadxRelease.js";
interface FailureContext {
readonly cause: unknown;
@@ -326,6 +329,21 @@ const presentDiagnosticFailure = (
if (failure.kind === "output")
return new AnalysisOutputError(failure.operation, failure.reason, options);
if (failure.kind === "startup") {
// Before the handshake the retained stderr is the only evidence of why the
// launcher stopped; a heap shortage there is a resource limit, not setup.
if (jadxHeapExhausted(output?.stderr ?? ""))
return new AnalysisResourceConstraintError(
failure.operation,
"memory",
"The JADX worker JVM ran out of heap before REA's Android bridge answered",
// The bridge never reported its heap, so the limit stays unknown.
{ observed_max_heap_bytes: null },
{
...options,
retryable: false,
remediationAction: JADX_HEAP_REMEDIATION,
},
);
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",
+13
View File
@@ -36,6 +36,19 @@ const bridgeFailureSchema = z.discriminatedUnion("kind", [
jadxReferenceLimitSchema,
]);
/**
* HotSpot's heap-exhaustion `OutOfMemoryError` reasons. Before the bridge
* answers there is no named failure, so a launcher's retained stderr is the
* only evidence. Other reasons (metaspace, direct buffers, native threads) are
* not remedied by the worker heap setting.
*/
const JADX_HEAP_EXHAUSTION =
/java\.lang\.OutOfMemoryError: (?:Java heap space|GC overhead limit exceeded)/u;
/** Whether a launcher's retained stderr reports JVM heap exhaustion. */
export const jadxHeapExhausted = (text: string): boolean =>
JADX_HEAP_EXHAUSTION.test(text);
/** Arbitrary upstream failure text stays text unless it matches a named bridge contract. */
export const parseJadxFailure = (
text: string,
+9
View File
@@ -24,6 +24,15 @@ export const JADX_JAVA_RUNTIME_REMEDIATION =
export const JADX_JVM_OPTIONS_REMEDIATION =
"Set REA_JADX_HEAP_MIB to a positive integer (heap size in MiB) and REA_JADX_ACTIVE_PROCESSOR_COUNT to a positive integer within the JVM's signed 32-bit range.";
/**
* Remediation for a JADX worker heap shortage, whether the bridge reported it or
* the launcher stopped before answering. REA passes REA_JADX_HEAP_MIB as an
* explicit command-line -Xmx, which outranks JAVA_TOOL_OPTIONS and
* JDK_JAVA_OPTIONS, while _JAVA_OPTIONS outranks the command line.
*/
export const JADX_HEAP_REMEDIATION =
"Increase REA_JADX_HEAP_MIB (MiB) in the environment that starts REA, within the host or container memory budget. REA passes it as an explicit -Xmx, so JAVA_TOOL_OPTIONS and JDK_JAVA_OPTIONS set the heap only while it is unset, and _JAVA_OPTIONS overrides it. An observed heap is this run's limit, not the heap the APK requires.";
/** Remediation when the host cannot run the Android JADX subprocess. */
export const JADX_UNSUPPORTED_HOST_REMEDIATION =
"Use Linux, macOS, or Windows x64 with its bundled native controls for Android JADX analysis.";
+2 -1
View File
@@ -48,6 +48,7 @@ import {
JADX_RELEASE,
JADX_PROVIDER_IDENTITY,
JADX_LIMITATIONS,
JADX_HEAP_REMEDIATION,
} from "./JadxRelease.js";
type JadxCall = {
@@ -406,7 +407,7 @@ export class JadxSession {
retryable: false,
remediationAction:
failure.memory_area === "heap"
? "Increase REA_JADX_HEAP_MIB (MiB) in the environment that starts REA, within the host or container memory budget. Review JAVA_TOOL_OPTIONS and other JVM heap overrides. The observed heap is this run's limit, not the heap the APK requires."
? JADX_HEAP_REMEDIATION
: "Review the JVM allocation failure and the host or container memory limits. The observed maximum heap does not establish which memory region was exhausted; increasing heap alone may not help.",
diagnostics: {
upstream_operation: name,
@@ -5,9 +5,28 @@ import {
parseJadxJson,
normalizeJadxText,
parseJadxFailure,
jadxHeapExhausted,
} from "../../../src/android/JadxProtocol.js";
import { androidInputSchemas } from "../../../src/domain/android/androidAnalysis.js";
it("recognizes only HotSpot heap-exhaustion OutOfMemoryError reasons", () => {
for (const text of [
'Exception in thread "main" java.lang.OutOfMemoryError: Java heap space',
"java.lang.OutOfMemoryError: GC overhead limit exceeded",
])
expect(jadxHeapExhausted(text), text).toBe(true);
// Other memory areas are not fixed by the worker heap, and unanchored text
// that merely mentions the heap is not a JVM failure.
for (const text of [
"java.lang.OutOfMemoryError: Metaspace",
"java.lang.OutOfMemoryError: Direct buffer memory",
"java.lang.OutOfMemoryError: unable to create new native thread",
"warning: Java heap space is low",
"",
])
expect(jadxHeapExhausted(text), text).toBe(false);
});
it("recognizes named bridge failures without reinterpreting arbitrary engine text", () => {
const failure = {
kind: "jvm-memory-failure",
@@ -1424,3 +1424,30 @@ it("retains parsed native body absence without claiming an empty implementation"
await provider.close();
await verifyCleanup(launches);
});
it("classifies a heap shortage that stops the bridge before the handshake", async () => {
const { service, apk, launches, provider } = await setup(
"start-heap-exhausted",
);
const outcome = await service.execute("inspect_android_package", {
path: apk,
});
if (outcome.ok) throw new Error("Expected a heap-exhaustion failure");
const projected = projectAnalysisError(outcome.error);
expect(projected).toMatchObject({
code: "resource_constraint",
retryable: false,
remediation: { action: expect.stringContaining("REA_JADX_HEAP_MIB") },
details: {
operation: "inspect_android_package",
resource: "memory",
// The bridge never answered, so nothing measured this run's heap.
reported_limits: { observed_max_heap_bytes: null },
captured_output: {
stderr: expect.stringContaining("OutOfMemoryError: Java heap space"),
},
},
});
await provider.close();
await verifyCleanup(launches);
});
+8
View File
@@ -6,6 +6,14 @@ import { JADX_BRIDGE_IDENTITY } from "../../../src/android/JadxRelease.ts";
// An actual child MCP server exercising the production stdio/process seam.
// It is a protocol fixture, not evidence of JADX decompiler support.
const mode = process.env.REA_FAKE_JADX_MODE ?? "normal";
// A worker heap too small for the bridge stops the JVM before the handshake,
// so the retained stderr is the only heap evidence.
if (mode === "start-heap-exhausted") {
process.stderr.write(
'Exception in thread "main" java.lang.OutOfMemoryError: Java heap space\n',
);
process.exit(1);
}
const server = new McpServer({
name: mode === "empty-server-identity" ? "" : "rea-jadx-bridge",
version: