rea-agents 6.1.0 → 6.3.0

package/dist/firmware/FirmwareCommand.js

@@ -9,6 +9,10 @@ import { spawnOwnedProviderProcess, ProviderProcessSupervisor, } from "../proces
 import { cleanupOwnedProcessGroup } from "../process/ProcessOwnership.js";
 import { FIRMWARE_LIMITS } from "./FirmwareRelease.js";
 import { hashFirmwareFile, inventoryFirmwareOutput, readFirmwareReport, } from "./FirmwareFiles.js";
+/** Refuse an unmet host or tool requirement, which another target cannot satisfy. */
+export const firmwareToolUnavailable = (engine, operation, reason) => new AnalysisCapabilityUnavailableError(engine, operation, reason, {
+    userMessage: reason,
+});
 /** Resolve explicitly supplied executable paths; never install or search for engines. */
 export const resolveFirmwareCommand = async (environment, engine, operation) => {
     const variable = engine === "binwalk" ? "REA_BINWALK_COMMAND" : "REA_UNBLOB_COMMAND";
@@ -16,9 +20,9 @@ export const resolveFirmwareCommand = async (environment, engine, operation) =>
     if (process.platform !== "linux" ||
         configured === undefined ||
         !isAbsolute(configured))
-        throw new AnalysisCapabilityUnavailableError(engine, operation, `This integration requires Linux and an absolute ${variable} path to the caller-supplied tool`);
+        throw firmwareToolUnavailable(engine, operation, `This integration requires Linux and an absolute ${variable} path to the caller-supplied tool`);
     const command = await realpath(configured).catch((cause) => {
-        throw new AnalysisCapabilityUnavailableError(engine, operation, `${variable} is unavailable: ${cause instanceof Error ? cause.message : String(cause)}`);
+        throw firmwareToolUnavailable(engine, operation, `${variable} is unavailable: ${cause instanceof Error ? cause.message : String(cause)}`);
     });
     let sha256;
     try {
@@ -28,18 +32,18 @@ export const resolveFirmwareCommand = async (environment, engine, operation) =>
         sha256 = await hashFirmwareFile(command);
     }
     catch (cause) {
-        throw new AnalysisCapabilityUnavailableError(engine, operation, `${variable} is not a readable executable regular file: ${command}: ${cause instanceof Error ? cause.message : String(cause)}`);
+        throw firmwareToolUnavailable(engine, operation, `${variable} is not a readable executable regular file: ${command}: ${cause instanceof Error ? cause.message : String(cause)}`);
     }
     const limiter = environment.REA_FIRMWARE_PRLIMIT_COMMAND ?? "/usr/bin/prlimit";
     if (!isAbsolute(limiter))
-        throw new AnalysisCapabilityUnavailableError(engine, operation, "REA_FIRMWARE_PRLIMIT_COMMAND must be absolute");
+        throw firmwareToolUnavailable(engine, operation, "REA_FIRMWARE_PRLIMIT_COMMAND must be absolute");
     try {
         await access(limiter, constants.X_OK);
         if (!(await stat(limiter)).isFile())
             throw new TypeError("Configured path is not a regular file");
     }
     catch (cause) {
-        throw new AnalysisCapabilityUnavailableError(engine, operation, `Resource limiter is not an executable regular file: ${limiter}: ${cause instanceof Error ? cause.message : String(cause)}; provide util-linux prlimit`);
+        throw firmwareToolUnavailable(engine, operation, `Resource limiter is not an executable regular file: ${limiter}: ${cause instanceof Error ? cause.message : String(cause)}; provide util-linux prlimit`);
     }
     return { command, limiter, sha256 };
 };

package/dist/firmware/FirmwareProvider.js

@@ -3,7 +3,7 @@ import { z } from "zod";
 import { createAnalysisExecution, } from "../application/AnalysisProvider.js";
 import { firmwareResultSchemas, } from "../domain/firmware/firmwareAnalysis.js";
 import { AnalysisError } from "../domain/analysisErrorBase.js";
-import { AnalysisCancelledError, AnalysisCapabilityUnavailableError, AnalysisInputError, AnalysisOutputError, AnalysisTimeoutError, } from "../domain/analysisErrorCore.js";
+import { AnalysisCancelledError, AnalysisInputError, AnalysisOutputError, AnalysisTimeoutError, } from "../domain/analysisErrorCore.js";
 import { ProviderAdapterError } from "../domain/providerAdapterError.js";
 import { ProviderCleanupError } from "../domain/providerCleanupError.js";
 import { err, ok } from "../domain/result.js";
@@ -11,7 +11,7 @@ import { PrivateRuntimeRoot } from "../process/PrivateRuntimeRoot.js";
 import { publishFirmwareExtraction } from "./FirmwarePublication.js";
 import { FIRMWARE_LIMITS, BINWALK_PROVIDER_IDENTITY, UNBLOB_PROVIDER_IDENTITY, } from "./FirmwareRelease.js";
 import { admitFirmwareVersion } from "./FirmwareVersion.js";
-import { resolveFirmwareCommand, runFirmwareCommand, readFirmwareCommandReport, } from "./FirmwareCommand.js";
+import { firmwareToolUnavailable, resolveFirmwareCommand, runFirmwareCommand, readFirmwareCommandReport, } from "./FirmwareCommand.js";
 import { inventoryFirmwareOutput, snapshotFirmware } from "./FirmwareFiles.js";
 import { normalizeBinwalkReport, normalizeUnblobReport, } from "./FirmwareReports.js";
 const waitForPredecessor = (predecessor, operation, signal) => new Promise((resolve, reject) => {
@@ -96,10 +96,10 @@ export class FirmwareProvider {
             const versionRun = await run(["--version"]);
             const version = versionRun.stdout.text.trim();
             if (versionRun.stdout.bytes > 1024)
-                throw new AnalysisCapabilityUnavailableError(engineName, request.operation, `Tool version banner is ${String(versionRun.stdout.bytes)} bytes; expected a short ${engineName} version line.`);
+                throw firmwareToolUnavailable(engineName, request.operation, `Tool version banner is ${String(versionRun.stdout.bytes)} bytes; expected a short ${engineName} version line.`);
             const admitted = admitFirmwareVersion(engineName, version);
             if (admitted.status === "unsupported" || admitted.status === "unresolved")
-                throw new AnalysisCapabilityUnavailableError(engineName, request.operation, admitted.message);
+                throw firmwareToolUnavailable(engineName, request.operation, admitted.message);
             const engine = {
                 name: engineName,
                 version: admitted.version,

package/dist/generatedPackageMetadata.js

@@ -1,9 +1,9 @@
 /** Generated from package.json and package-lock.json; do not edit. */
 export const PACKAGE_METADATA = {
     name: "rea-agents",
-    version: "6.1.0", // x-release-please-version
+    version: "6.3.0", // x-release-please-version
     serverSdkVersion: "2.3.1",
     clientSdkVersion: "2.3.1",
     coreSdkVersion: "2.3.1",
-    skillVersion: "33",
+    skillVersion: "34",
 };

package/dist/ghidra/GhidraAnalysisProfile.js

@@ -8,7 +8,7 @@ export const resolveGhidraAnalysisProfile = (target, identity, installation, sig
     if (signal?.aborted === true)
         return Promise.resolve(err(new AnalysisCancelledError("open_binary")));
     if (target.kind !== "executable")
-        return Promise.resolve(ok({ profile: null, compatibility: {} }));
+        return Promise.resolve(ok({ profile: null }));
     if (installation.status === "unavailable")
         return Promise.resolve(err(new ProviderAdapterError(identity.id, "resolve_analysis_profile")));
     const provider = { ...identity, version: installation.providerVersion };
@@ -28,7 +28,8 @@ export const resolveGhidraAnalysisProfile = (target, identity, installation, sig
             load_image_observations: "source-mappings-entry-context-v2",
             function_body_evidence: "complete-inclusive-ranges-v1",
             function_references: "complete-body-and-entry-reference-manager-v2",
-            location_resolution: "explicit-address-exact-name-first-v2",
+            location_resolution: "explicit-address-exact-entry-symbol-first-v3",
+            instruction_flow_evidence: "decoded-return-pcode-v1",
             process_launch: installation.platform === "win32"
                 ? "official-headless-script-v1"
                 : "inspected-jvm-launch-support-v1",
@@ -68,9 +69,5 @@ export const resolveGhidraAnalysisProfile = (target, identity, installation, sig
                 : {}),
             analyzer_preset: "ghidra-default",
         }),
-        compatibility: {
-            languageId: dos ? "x86:LE:16:Real Mode" : "auto",
-            compilerSpecId: dos ? "default" : "auto",
-        },
     }));
 };

package/dist/ghidra/GhidraClient.js

@@ -1,5 +1,6 @@
 import { randomBytes, randomUUID } from "node:crypto";
-import { tmpdir } from "node:os";
+import { AnalysisError } from "../domain/analysisErrorBase.js";
+import { ProviderCleanupError } from "../domain/providerCleanupError.js";
 import { err, ok } from "../domain/result.js";
 import { silentLogger } from "../logger.js";
 import { PendingOperations } from "../process/PendingOperations.js";
@@ -9,6 +10,7 @@ import { ProviderRunLineage } from "../process/ProviderRunLineage.js";
 import { ProviderProcessSupervisor, } from "../process/ProviderProcess.js";
 import { DEFAULT_GHIDRA_STARTUP_TIMEOUT_MS } from "../config/ghidraStartupTimeout.js";
 import { createGhidraDiagnostics } from "./GhidraDiagnostics.js";
+import { GhidraLaunchError } from "./GhidraLauncher.js";
 import { GhidraResponseBuffer } from "./GhidraResponseBuffer.js";
 import { GhidraResponseRouter } from "./GhidraResponseRouter.js";
 import { GhidraRequestQueue } from "./GhidraRequestQueue.js";
@@ -20,8 +22,9 @@ import { connectGhidraSocket } from "./GhidraSocketConnection.js";
 import { createGhidraEndpoint, } from "./GhidraTransport.js";
 import { GhidraWire } from "./GhidraClientWire.js";
 import { completeGhidraStartupHandshake } from "./GhidraClientStartup.js";
+import { ghidraSessionRoot } from "./GhidraSessionRoot.js";
 const SHUTDOWN_TIMEOUT_MS = 10_000;
-const SESSION_ROOT = tmpdir();
+const SESSION_ROOT = ghidraSessionRoot();
 /** Owns an authenticated private Ghidra session with transport-bound mutation authority. */
 export class GhidraClient {
     #options;
@@ -91,10 +94,12 @@ export class GhidraClient {
     /** Launch Ghidra once and require its exact post-analysis handshake. */
     start(signal) {
         if (this.#closePromise !== undefined)
-            return this.#closePromise.then(() => this.start(signal));
+            return this.#closePromise.then(() => this.start(signal), (cause) => err(new GhidraSessionError("process", "Ghidra cleanup remains incomplete", this.#diagnostics(), { cause, cleanupFailure: this.#cleanupError(cause) })));
         if (this.#startPromise !== undefined) {
             if (this.#startupController?.signal.aborted && !signal?.aborted)
-                return this.#startPromise.then((result) => result.ok ? result : this.start(signal));
+                return this.#startPromise.then((result) => result.ok || result.error.cleanupFailure !== undefined
+                    ? result
+                    : this.start(signal));
             return this.#startPromise;
         }
         const controller = new AbortController();
@@ -153,8 +158,43 @@ export class GhidraClient {
         }
     }
     /** Stop the owned process group and remove all project/runtime artifacts. */
-    close() {
-        return this.#requestClose(false);
+    async close() {
+        try {
+            await this.#requestClose(false);
+            return ok(null);
+        }
+        catch (cause) {
+            return err(this.#cleanupError(cause));
+        }
+    }
+    #cleanupError(cause) {
+        if (cause instanceof AnalysisError && cause.cleanupIncomplete)
+            return cause;
+        return new ProviderCleanupError("ghidra", [
+            ...(this.#process === undefined ? [] : ["ghidra-process"]),
+            ...[this.#runtimeRoot, this.#socketRoot].flatMap((root) => root === undefined ? [] : [root.path]),
+        ], {
+            reason: cause instanceof Error ? cause.message : String(cause),
+            diagnostics: this.#diagnostics(),
+        }, { cause });
+    }
+    async #startupFailure(primary) {
+        try {
+            await this.#cleanup();
+            return err(primary);
+        }
+        catch (cause) {
+            return err(new GhidraSessionError(primary.kind, primary.message, primary.diagnostics, {
+                ...(primary.cause === undefined ? {} : { cause: primary.cause }),
+                ...(primary.timeoutMs === undefined
+                    ? {}
+                    : { timeoutMs: primary.timeoutMs }),
+                ...(primary.remoteCode === undefined
+                    ? {}
+                    : { remoteCode: primary.remoteCode }),
+                cleanupFailure: this.#cleanupError(cause),
+            }));
+        }
     }
     #requestClose(forceStop) {
         const starting = this.#startPromise;
@@ -218,8 +258,7 @@ export class GhidraClient {
         }
         catch (cause) {
             const failure = this.#failure("start", "Ghidra private endpoint allocation failed", cause);
-            await this.#cleanup();
-            return err(failure);
+            return this.#startupFailure(failure);
         }
         try {
             const snapshot = await createGhidraTargetSnapshot(this.#options.targetPath, this.#runtimeRoot.path, this.#options.targetSha256, { signal: deadline.signal, platform: this.#options.platform });
@@ -230,8 +269,7 @@ export class GhidraClient {
             if (deadline.signal.aborted)
                 return this.#startupInterrupted(deadline);
             const failure = this.#failure("start", "Ghidra target snapshot failed admission", cause);
-            await this.#cleanup();
-            return err(failure);
+            return this.#startupFailure(failure);
         }
         if (deadline.signal.aborted)
             return this.#startupInterrupted(deadline);
@@ -253,13 +291,21 @@ export class GhidraClient {
         }, { signal: deadline.signal })
             .catch((cause) => err(this.#failure("start", "Ghidra launcher failed", cause)));
         if (!launched.ok) {
+            const partialLaunch = launched.error instanceof GhidraLaunchError
+                ? launched.error.partialLaunch
+                : undefined;
+            if (partialLaunch !== undefined) {
+                this.#launch = partialLaunch;
+                this.#process = new ProviderProcessSupervisor(partialLaunch, {
+                    onDiagnostic: (event) => this.#onProcessDiagnostic(event),
+                });
+            }
             const failure = deadline.signal.aborted
-                ? this.#interruptionFailure(deadline)
+                ? this.#interruptionFailure(deadline, launched.error)
                 : launched.error instanceof GhidraSessionError
                     ? launched.error
                     : this.#failure("start", launched.error.message, launched.error);
-            await this.#cleanup();
-            return err(failure);
+            return this.#startupFailure(failure);
         }
         this.#launch = launched.value;
         this.#process = new ProviderProcessSupervisor(launched.value, {
@@ -268,21 +314,19 @@ export class GhidraClient {
         const connected = await this.#connect(endpoint, deadline);
         if (!connected.ok) {
             const failure = connected.error;
-            await this.#cleanup();
-            return err(failure);
+            return this.#startupFailure(failure);
         }
         const completed = await completeGhidraStartupHandshake({
             deadline,
             request: (method, params, requestOptions) => this.#wire.request(method, params, requestOptions),
             parseSessionInfo: (value) => this.#parseSessionInfo(value),
-            cleanup: () => this.#cleanup(),
             failure: this.#failure,
             startupTimeoutMs: this.#options.startupTimeoutMs,
         });
-        if (completed.ok) {
-            await this.#lineage.observe(this.#launch);
-            this.#requestQueue.reopen();
-        }
+        if (!completed.ok)
+            return this.#startupFailure(completed.error);
+        await this.#lineage.observe(this.#launch);
+        this.#requestQueue.reopen();
         return completed;
     }
     async #connect(endpoint, deadline) {
@@ -389,18 +433,8 @@ export class GhidraClient {
             this.#lastDiagnostics = this.#diagnostics();
             this.#process = undefined;
             this.#launch = undefined;
-            const runtimeRoot = this.#runtimeRoot;
-            const socketRoot = this.#socketRoot;
-            this.#runtimeRoot = undefined;
-            this.#socketRoot = undefined;
             try {
-                const removed = await Promise.allSettled([
-                    runtimeRoot?.close(),
-                    socketRoot?.close(),
-                ]);
-                const failed = removed.find((result) => result.status === "rejected");
-                if (failed?.status === "rejected")
-                    throw failed.reason;
+                await this.#removeRuntimeRoots();
             }
             catch (cause) {
                 if (forceStop)
@@ -420,6 +454,42 @@ export class GhidraClient {
             this.#closing = false;
         }
     }
+    /**
+     * Remove the runtime and socket roots, keeping each one that could not be
+     * removed so a later close retries it rather than reporting success.
+     */
+    async #removeRuntimeRoots() {
+        const roots = [
+            {
+                root: this.#runtimeRoot,
+                release: () => (this.#runtimeRoot = undefined),
+            },
+            { root: this.#socketRoot, release: () => (this.#socketRoot = undefined) },
+        ];
+        const leftovers = [];
+        let firstCause;
+        for (const { root, release } of roots) {
+            if (root === undefined)
+                continue;
+            try {
+                await root.close();
+                release();
+            }
+            catch (cause) {
+                firstCause ??= cause;
+                leftovers.push({
+                    path: root.path,
+                    reason: cause instanceof Error ? cause.message : String(cause),
+                });
+            }
+        }
+        if (leftovers.length > 0)
+            throw new ProviderCleanupError("ghidra", leftovers.map(({ path }) => path), {
+                reason: "Ghidra's private runtime directory could not be removed; it is retained for a later close.",
+                leftover_paths: leftovers.map(({ path }) => path),
+                failures: leftovers.map(({ path, reason }) => `${path}: ${reason}`),
+            }, { cause: firstCause });
+    }
     #redactAuthentication(value) {
         for (const token of this.#authenticationTokens)
             value = value.replaceAll(token, "[REDACTED]");
@@ -457,13 +527,12 @@ export class GhidraClient {
     }
     async #startupInterrupted(deadline) {
         const failure = this.#interruptionFailure(deadline);
-        await this.#cleanup();
-        return err(failure);
+        return this.#startupFailure(failure);
     }
-    #interruptionFailure(deadline) {
+    #interruptionFailure(deadline, cause) {
         return deadline.interruption === "cancelled"
-            ? this.#failure("cancelled", "Ghidra startup was cancelled")
-            : this.#failure("timeout", "Ghidra startup deadline elapsed", undefined, {
+            ? this.#failure("cancelled", "Ghidra startup was cancelled", cause)
+            : this.#failure("timeout", "Ghidra startup deadline elapsed", cause, {
                 timeoutMs: deadline.timeoutMs,
             });
     }

package/dist/ghidra/GhidraClientStartup.js

@@ -9,7 +9,6 @@ export async function completeGhidraStartupHandshake(options) {
         const failure = options.deadline.signal.aborted
             ? interruptionFailure(options)
             : ping.error;
-        await options.cleanup();
         return err(failure);
     }
     const parsed = options.parseSessionInfo(ping.value);
@@ -17,7 +16,6 @@ export async function completeGhidraStartupHandshake(options) {
         const failure = parsed.ok
             ? options.failure("analysis_timeout", "Ghidra auto-analysis reached its per-file deadline")
             : parsed.error;
-        await options.cleanup();
         return err(failure);
     }
     return parsed;

package/dist/ghidra/GhidraDoctor.js

@@ -38,13 +38,14 @@ export const projectGhidraDoctorInspection = (inspection) => {
     };
 };
 /** Inspect the process-configured BYO Ghidra installation for `rea doctor`. */
-export const inspectSystemGhidraProvider = () => Promise.resolve(projectGhidraDoctorInspection(inspectGhidraInstallation({
-    ...(process.env.GHIDRA_INSTALL_DIR === undefined
+export const inspectSystemGhidraProvider = (environment) => Promise.resolve(projectGhidraDoctorInspection(inspectGhidraInstallation({
+    environment,
+    ...(environment.GHIDRA_INSTALL_DIR === undefined
         ? {}
-        : { installDir: process.env.GHIDRA_INSTALL_DIR }),
-    ...(process.env.JAVA_HOME === undefined
+        : { installDir: environment.GHIDRA_INSTALL_DIR }),
+    ...(environment.JAVA_HOME === undefined
         ? {}
-        : { javaHome: process.env.JAVA_HOME }),
+        : { javaHome: environment.JAVA_HOME }),
 })));
 const selectedChecks = (inspection) => {
     const byName = new Map(inspection.checks.map((candidate) => [candidate.name, candidate]));

package/dist/ghidra/GhidraFunctionValues.js

@@ -112,13 +112,11 @@ const procedureReferences = z
     procedure: procedureIdentity,
     direction: z.enum(["incoming", "outgoing"]),
     references: z.array(referenceEdge),
-    reference_kinds_available: z.boolean().default(true),
-    unresolved_calls: z
-        .array(z.strictObject({
+    reference_kinds_available: z.boolean(),
+    unresolved_calls: z.array(z.strictObject({
         address: ghidraCanonicalAddressSchema,
         reason: z.string(),
-    }))
-        .default([]),
+    })),
 })
     .strict();
 const procedureInfo = z

package/dist/ghidra/GhidraInstallation.js

@@ -1,14 +1,84 @@
+import { snapshotEnvironment } from "../process/snapshotEnvironment.js";
 import { spawnSync } from "node:child_process";
 import { constants } from "node:fs";
-import { accessSync, readFileSync } from "node:fs";
+import { accessSync, closeSync, fstatSync, openSync, readFileSync, readSync, statSync, } from "node:fs";
 import { posix, win32 } from "node:path";
+import { parseExecutableHeader, } from "../domain/binaryTarget.js";
 import { ghidraApplicationProperties, ghidraJavaMajorAccepted, ghidraJavaRangeLabel, ghidraJavaRequirement, ghidraReleaseAccepted, ghidraReleaseCompatibility, ghidraReleaseLine, ghidraVersionDetail, SUPPORTED_GHIDRA_JAVA_MAJOR, SUPPORTED_GHIDRA_VERSION, } from "./GhidraInstallationPolicy.js";
-export { SUPPORTED_GHIDRA_JAVA_MAJOR, SUPPORTED_GHIDRA_VERSION };
 const NATIVE_PLATFORMS = {
     linux: { x64: "linux_x86_64", arm64: "linux_arm_64" },
     darwin: { x64: "mac_x86_64", arm64: "mac_arm_64" },
     win32: { x64: "win_x86_64" },
 };
+/** Executable format each supported host runs its own Ghidra native tools as. */
+const NATIVE_TOOL_FORMATS = {
+    linux: "elf",
+    darwin: "mach-o",
+    win32: "pe",
+};
+/** Node architecture identifiers as the executable-header parser reports them. */
+const NATIVE_ARCHITECTURES = [
+    { node: "x64", binary: "x86_64" },
+    { node: "ia32", binary: "x86" },
+    { node: "arm", binary: "arm" },
+    { node: "arm64", binary: "arm64" },
+];
+/** Bound installation discovery reads; larger headers remain unknown. */
+const EXECUTABLE_HEADER_PROBE_BYTES = 4096;
+/**
+ * Judge a native decompiler by its own executable header instead of the
+ * directory name that admits it.
+ *
+ * Only a header that positively contradicts the host is `incompatible`. An
+ * absent, unreadable, truncated, or unrecognized header stays `unknown`, so a
+ * file the other checks already accept is never refused on missing evidence.
+ */
+const assessNativeDecompiler = (path, platform, architecture, probe) => {
+    const expectedFormat = NATIVE_TOOL_FORMATS[platform];
+    const expectedArchitecture = NATIVE_ARCHITECTURES.find(({ node }) => node === architecture)?.binary;
+    if (expectedFormat === undefined || expectedArchitecture === undefined)
+        return {
+            status: "unknown",
+            detail: `${path} is executable, but no native tool format is defined for ${platform}/${architecture}`,
+        };
+    let parsed = probe === undefined
+        ? undefined
+        : parseExecutableHeader(probe.bytes, architecture, probe.size);
+    if (probe !== undefined && parsed !== undefined && !parsed.ok) {
+        // FAT parsing selects a host slice. A validated foreign slice can still
+        // prove that its complete architecture table excludes this host. If the
+        // host is listed but its slice is malformed, preserve the unknown outcome.
+        for (const { node } of NATIVE_ARCHITECTURES) {
+            if (node === architecture)
+                continue;
+            const alternative = parseExecutableHeader(probe.bytes, node, probe.size);
+            if (alternative.ok &&
+                !alternative.value.availableArchitectures.includes(expectedArchitecture)) {
+                parsed = alternative;
+                break;
+            }
+        }
+    }
+    if (parsed === undefined || !parsed.ok)
+        return {
+            status: "unknown",
+            detail: `${path} is executable, but its executable format for ${platform}/${architecture} could not be established`,
+        };
+    const observed = `${parsed.value.format} ${parsed.value.architecture}`;
+    const expected = `${expectedFormat} ${expectedArchitecture}`;
+    if (observed === expected)
+        return {
+            status: "compatible",
+            detail: `${path} reports ${observed}, which matches ${platform}/${architecture}`,
+        };
+    const nativeDirectory = NATIVE_PLATFORMS[platform]?.[architecture];
+    const executable = platform === "win32" ? "decompile.exe" : "decompile";
+    return {
+        status: "incompatible",
+        detail: `${path} reports ${observed}, but ${platform}/${architecture} requires ${expected}`,
+        remediation: `Provide an executable Ghidra/Features/Decompiler/os/${nativeDirectory ?? "<platform>"}/${executable} built for ${expected}, or its build/os equivalent. REA does not build or install native tools.`,
+    };
+};
 /** Inspect an installation without importing a target or modifying Ghidra. */
 export const inspectGhidraInstallation = (options, host = systemGhidraInstallationHost()) => {
     const platform = options.platform ?? process.platform;
@@ -97,17 +167,15 @@ const installationCoordinates = (options, platform, architecture, host) => {
             ? undefined
             : ghidraApplicationProperties(properties),
         javaCommand,
-        java: host.probeJava(javaCommand, ghidraJavaEnvironment(options.javaHome, process.env, platform)),
+        // The configuration check rejects a relative JAVA_HOME. Probing it would
+        // run whatever `bin/java` the current directory holds.
+        java: options.javaHome === undefined || path.isAbsolute(options.javaHome)
+            ? host.probeJava(javaCommand, ghidraJavaEnvironment(options.javaHome, options.environment, platform))
+            : undefined,
     };
 };
 const installationChecks = ({ coordinates, platform, architecture, javaHome, host, }) => [
-    installationCheck({
-        name: "configuration",
-        passed: coordinates.installDir !== null,
-        code: "not_configured",
-        detail: coordinates.installDir ?? "GHIDRA_INSTALL_DIR is not set",
-        remediation: `Set GHIDRA_INSTALL_DIR to an extracted Ghidra ${ghidraReleaseLine()} release directory.`,
-    }),
+    configurationCheck(coordinates.installDir, javaHome, platform),
     installationCheck({
         name: "platform",
         passed: NATIVE_PLATFORMS[platform] !== undefined,
@@ -139,16 +207,38 @@ const installationChecks = ({ coordinates, platform, architecture, javaHome, hos
         detail: coordinates.analyzeHeadlessPath ?? "analyzeHeadless unavailable",
         remediation: "Restore support/analyzeHeadless or support/analyzeHeadless.bat from the official Ghidra release.",
     }),
-    installationCheck({
-        name: "native_decompiler",
-        passed: coordinates.nativeDecompilerPath !== null,
-        code: "executable_missing",
-        detail: coordinates.nativeDecompilerPath ??
-            `Matching native decompiler for ${platform}/${architecture} was not found`,
-        remediation: `Provide an executable Ghidra/Features/Decompiler/os/${NATIVE_PLATFORMS[platform]?.[architecture] ?? "<platform>"}/${platform === "win32" ? "decompile.exe" : "decompile"}, or its build/os equivalent. REA does not build or install native tools.`,
-    }),
+    nativeDecompilerCheck({ coordinates, platform, architecture, host }),
     javaCheck(coordinates.java, coordinates.javaCommand, javaHome, coordinates.properties),
 ];
+/**
+ * REA's configuration parser, and so the MCP server and analysis, accept only
+ * absolute paths; a relative one that happens to resolve here must not pass.
+ */
+const configurationCheck = (installDir, javaHome, platform) => {
+    const { isAbsolute } = platform === "win32" ? win32 : posix;
+    const relative = [
+        ...(installDir !== null && !isAbsolute(installDir)
+            ? ["GHIDRA_INSTALL_DIR"]
+            : []),
+        ...(javaHome !== undefined && !isAbsolute(javaHome) ? ["JAVA_HOME"] : []),
+    ];
+    if (installDir === null || relative.length === 0)
+        return installationCheck({
+            name: "configuration",
+            passed: installDir !== null,
+            code: "not_configured",
+            detail: installDir ?? "GHIDRA_INSTALL_DIR is not set",
+            remediation: `Set GHIDRA_INSTALL_DIR to an extracted Ghidra ${ghidraReleaseLine()} release directory.`,
+        });
+    const settings = relative.join(" and ");
+    return installationCheck({
+        name: "configuration",
+        passed: false,
+        code: "not_configured",
+        detail: `${settings} must be absolute`,
+        remediation: `Set ${settings} to ${relative.length === 1 ? "an absolute path" : "absolute paths"}. REA's analysis and MCP server reject relative paths even when they resolve from the current directory.`,
+    });
+};
 /** Project an installation probe into caller-visible, secret-free diagnostics. */
 export const ghidraInstallationDiagnostics = (inspection) => ({
     install_dir: inspection.installDir,
@@ -169,9 +259,10 @@ export const ghidraInstallationDiagnostics = (inspection) => ({
     })),
 });
 /** Environment that makes an explicitly selected JDK win over PATH discovery. */
-export const ghidraJavaEnvironment = (javaHome, environment = process.env, platform = process.platform) => {
+export const ghidraJavaEnvironment = (javaHome, environment, platform = process.platform) => {
+    const selectedEnvironment = snapshotEnvironment(environment, platform);
     const boundedEnvironment = {
-        ...environment,
+        ...selectedEnvironment,
         _JAVA_OPTIONS: "",
         JAVA_TOOL_OPTIONS: "",
         JDK_JAVA_OPTIONS: "",
@@ -182,7 +273,7 @@ export const ghidraJavaEnvironment = (javaHome, environment = process.env, platf
         : {
             ...boundedEnvironment,
             JAVA_HOME: javaHome,
-            PATH: `${(platform === "win32" ? win32 : posix).join(javaHome, "bin")}${platform === "win32" ? win32.delimiter : posix.delimiter}${environment.PATH ?? ""}`,
+            PATH: `${(platform === "win32" ? win32 : posix).join(javaHome, "bin")}${platform === "win32" ? win32.delimiter : posix.delimiter}${selectedEnvironment.PATH ?? ""}`,
         };
 };
 const installationCheck = (options) => options.passed
@@ -198,6 +289,23 @@ const installationCheck = (options) => options.passed
         detail: options.detail,
         remediation: options.remediation,
     };
+/** Require a present native decompiler without positively incompatible bytes. */
+const nativeDecompilerCheck = ({ coordinates, platform, architecture, host, }) => {
+    const path = coordinates.nativeDecompilerPath;
+    const compatibility = path === null
+        ? undefined
+        : assessNativeDecompiler(path, platform, architecture, host.executableHeader?.(path));
+    return installationCheck({
+        name: "native_decompiler",
+        passed: path !== null && compatibility?.status !== "incompatible",
+        code: "executable_missing",
+        detail: compatibility?.detail ??
+            `Matching native decompiler for ${platform}/${architecture} was not found`,
+        remediation: compatibility?.status === "incompatible"
+            ? compatibility.remediation
+            : `Provide an executable Ghidra/Features/Decompiler/os/${NATIVE_PLATFORMS[platform]?.[architecture] ?? "<platform>"}/${platform === "win32" ? "decompile.exe" : "decompile"}, or its build/os equivalent. REA does not build or install native tools.`,
+    });
+};
 const versionCheck = (properties) => {
     const raw = properties?.providerVersion;
     return installationCheck({
@@ -252,10 +360,31 @@ const systemGhidraInstallationHost = () => ({
             return undefined;
         }
     },
+    executableHeader(path) {
+        let handle;
+        try {
+            handle = openSync(path, constants.O_RDONLY | constants.O_NONBLOCK | constants.O_NOCTTY);
+            const metadata = fstatSync(handle);
+            if (!metadata.isFile())
+                return undefined;
+            const bytes = Buffer.alloc(EXECUTABLE_HEADER_PROBE_BYTES);
+            const read = readSync(handle, bytes, 0, bytes.length, 0);
+            return { bytes: bytes.subarray(0, read), size: metadata.size };
+        }
+        catch (cause) {
+            // best-effort cleanup: a header that cannot be read stays unknown.
+            void cause;
+            return undefined;
+        }
+        finally {
+            if (handle !== undefined)
+                closeSync(handle);
+        }
+    },
     executable(path) {
         try {
             accessSync(path, constants.X_OK);
-            return true;
+            return statSync(path).isFile();
         }
         catch (cause) {
             // best-effort cleanup: optional executable probing; failure means missing.