rea-agents 5.0.0 → 6.1.0

package/dist/ghidra/GhidraInstallation.js

@@ -4,6 +4,11 @@ import { accessSync, readFileSync } from "node:fs";
 import { posix, win32 } from "node:path";
 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" },
+};
 /** Inspect an installation without importing a target or modifying Ghidra. */
 export const inspectGhidraInstallation = (options, host = systemGhidraInstallationHost()) => {
     const platform = options.platform ?? process.platform;
@@ -67,16 +72,13 @@ const installationCoordinates = (options, platform, architecture, host) => {
     const analyzeHeadlessPath = installDir === null
         ? null
         : path.join(installDir, "support", platform === "win32" ? "analyzeHeadless.bat" : "analyzeHeadless");
-    const decompilerPlatform = platform === "darwin"
-        ? architecture === "arm64"
-            ? "mac_arm_64"
-            : "mac_x86_64"
-        : null;
-    const nativeDecompilerPath = installDir === null || decompilerPlatform === null
+    const decompilerPlatform = NATIVE_PLATFORMS[platform]?.[architecture];
+    const decompilerExecutable = platform === "win32" ? "decompile.exe" : "decompile";
+    const nativeDecompilerPath = installDir === null || decompilerPlatform === undefined
         ? null
         : ([
-            path.join(installDir, "Ghidra", "Features", "Decompiler", "os", decompilerPlatform, "decompile"),
-            path.join(installDir, "Ghidra", "Features", "Decompiler", "build", "os", decompilerPlatform, "decompile"),
+            path.join(installDir, "Ghidra", "Features", "Decompiler", "os", decompilerPlatform, decompilerExecutable),
+            path.join(installDir, "Ghidra", "Features", "Decompiler", "build", "os", decompilerPlatform, decompilerExecutable),
         ].find((candidate) => host.executable(candidate)) ?? null);
     const properties = applicationPropertiesPath === null
         ? undefined
@@ -108,20 +110,17 @@ const installationChecks = ({ coordinates, platform, architecture, javaHome, hos
     }),
     installationCheck({
         name: "platform",
-        passed: platform === "linux" || platform === "win32" || platform === "darwin",
+        passed: NATIVE_PLATFORMS[platform] !== undefined,
         code: "unsupported_host",
         detail: platform,
-        remediation: "Use Linux or Windows x64, or macOS x64/arm64 with matching native Ghidra tools.",
+        remediation: "Use Linux or macOS x64/arm64, or Windows x64 with matching native Ghidra tools.",
     }),
     installationCheck({
         name: "architecture",
-        passed: ((platform === "linux" || platform === "win32") &&
-            architecture === "x64") ||
-            (platform === "darwin" &&
-                (architecture === "x64" || architecture === "arm64")),
+        passed: NATIVE_PLATFORMS[platform]?.[architecture] !== undefined,
         code: "unsupported_host",
         detail: architecture,
-        remediation: "Use x64 on Linux or Windows, or x64/arm64 on macOS.",
+        remediation: "Use x64/arm64 on Linux or macOS, or x64 on Windows.",
     }),
     installationCheck({
         name: "installation",
@@ -142,13 +141,11 @@ const installationChecks = ({ coordinates, platform, architecture, javaHome, hos
     }),
     installationCheck({
         name: "native_decompiler",
-        passed: platform !== "darwin" || coordinates.nativeDecompilerPath !== null,
+        passed: coordinates.nativeDecompilerPath !== null,
         code: "executable_missing",
-        detail: platform !== "darwin"
-            ? "not required on this platform"
-            : (coordinates.nativeDecompilerPath ??
-                "matching macOS native decompiler was not found"),
-        remediation: "REA does not build native tools. Build Ghidra's native components for this macOS architecture or provide an installation containing Ghidra/Features/Decompiler/os/<platform>/decompile.",
+        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.`,
     }),
     javaCheck(coordinates.java, coordinates.javaCommand, javaHome, coordinates.properties),
 ];

package/dist/ghidra/GhidraInventoryValues.js

@@ -1,9 +1,10 @@
 import { z } from "zod";
 import { nativeLoadImageObservationSchema } from "../domain/native/nativeLoadImage.js";
-import { AnalysisInputError, AnalysisOutputError, } from "../domain/analysisErrorCore.js";
+import { AnalysisOutputError, } from "../domain/analysisErrorCore.js";
 import { functionBodySchema, functionBodyEntryAgrees, } from "../domain/hopperValues.js";
 import { jsonValueSchema } from "../domain/jsonValue.js";
 import { err, ok } from "../domain/result.js";
+import { analysisInputErrorFromIssues } from "../domain/inputIssueProjection.js";
 /** Read-only direct inventory operations admitted by the Ghidra adapter. */
 export const GHIDRA_INVENTORY_OPERATIONS = [
     "inspect_native_load_image",
@@ -26,7 +27,11 @@ export const isGhidraInventoryOperation = (operation) => operationSet.has(operat
 export const ghidraIdentifierSchema = z.string().min(1);
 const identifier = ghidraIdentifierSchema;
 const document = identifier.nullable().default(null);
-const explicitAddress = identifier;
+/** Caller address spelling; the bridge resolves its space and emits canonical output. */
+export const ghidraInputAddressSchema = z
+    .string()
+    .regex(/^(?:(?:0[xX])?[0-9a-fA-F]+|(?:[A-Za-z0-9._~-]|%[0-9a-fA-F]{2})+:0[xX][0-9a-fA-F]+)$/u, "Use hexadecimal digits, optionally prefixed with 0x, or an encoded address-space name followed by :0x and hexadecimal digits");
+const explicitAddress = ghidraInputAddressSchema;
 const filteredAddress = explicitAddress.nullable().default(null);
 const searchInput = {
     pattern: z.string().min(1),
@@ -62,7 +67,9 @@ const inputSchemas = {
 export const parseGhidraInventoryInput = (operation, value) => {
     const parsed = inputSchemas[operation].safeParse(value);
     if (!parsed.success)
-        return err(new AnalysisInputError(operation, { cause: parsed.error }));
+        return err(analysisInputErrorFromIssues(operation, parsed.error.issues, value, {
+            cause: parsed.error,
+        }));
     return ok(parsed.data);
 };
 export const ghidraCanonicalAddressSchema = z
@@ -171,7 +178,10 @@ const containingProcedure = z.discriminatedUnion("found", [
         .strict()
         .superRefine((value, context) => {
         const body = value.procedure.body;
-        if (body.available &&
+        const exactExternalEntry = value.procedure.classification.external &&
+            value.query_address === value.procedure.address;
+        if (!exactExternalEntry &&
+            body.available &&
             !functionBodyEntryAgrees({ ...body, contains_entry: true }, value.query_address))
             context.addIssue({
                 code: "custom",

package/dist/ghidra/GhidraJavaLaunch.js

@@ -0,0 +1,62 @@
+import { dirname, join } from "node:path";
+import { execFileOutput } from "../process/ExecFileOutput.js";
+/** Launch coordinates obtained from Ghidra's own release configuration helper. */
+export const ghidraJavaLaunch = async (options) => {
+    const supportRoot = dirname(options.analyzeHeadlessPath);
+    const installRoot = dirname(supportRoot);
+    const command = join(options.javaHome, "bin", "java");
+    const isolatedProperties = [
+        `-Duser.home=${options.homeRoot}`,
+        `-Djava.io.tmpdir=${options.tempRoot}`,
+    ];
+    const supportArguments = [
+        ...isolatedProperties,
+        "-cp",
+        join(supportRoot, "LaunchSupport.jar"),
+        "LaunchSupport",
+        installRoot,
+    ];
+    const environment = { ...options.environment };
+    const configuredEnvironment = await execFileOutput(command, [...supportArguments, "-envvars"], {
+        env: environment,
+        ...(options.signal === undefined ? {} : { signal: options.signal }),
+    });
+    for (const line of configuredEnvironment.stdout.split(/\r?\n/u)) {
+        if (line === "")
+            continue;
+        const separator = line.indexOf("=");
+        const key = line.slice(0, separator);
+        if (separator < 1 || !/^[A-Za-z_][A-Za-z0-9_]*$/u.test(key))
+            throw new Error(`Invalid Ghidra LaunchSupport environment entry: ${line}`);
+        if ((environment[key] ?? "") === "")
+            environment[key] = line.slice(separator + 1);
+    }
+    const configuredArguments = await execFileOutput(command, [...supportArguments, "-vmargs"], {
+        env: environment,
+        ...(options.signal === undefined ? {} : { signal: options.signal }),
+    });
+    const vmArguments = configuredArguments.stdout
+        .split(/\r?\n/u)
+        .filter((line) => line !== "");
+    if (vmArguments.some((argument) => !argument.startsWith("-") || argument.includes("\0")))
+        throw new Error("Invalid Ghidra LaunchSupport JVM argument");
+    return {
+        command,
+        environment,
+        arguments: [
+            ...vmArguments,
+            ...(options.platform === "darwin" ? ["-Xdock:name=Ghidra-Headless"] : []),
+            `-Xmx${environment.GHIDRA_HEADLESS_MAXMEM || environment.GHIDRA_MAXMEM || "2G"}`,
+            "-XX:ParallelGCThreads=2",
+            "-XX:CICompilerCount=2",
+            "-Djava.awt.headless=true",
+            ...isolatedProperties,
+            "-showversion",
+            "-cp",
+            join(installRoot, "Ghidra", "Framework", "Utility", "lib", "Utility.jar"),
+            "ghidra.Ghidra",
+            "ghidra.app.util.headless.AnalyzeHeadless",
+            ...options.arguments,
+        ],
+    };
+};

package/dist/ghidra/GhidraLauncher.js

@@ -7,6 +7,7 @@ import { err, ok } from "../domain/result.js";
 import { cleanupOwnedProcessGroup, cleanupWindowsProcessTree, } from "../process/ProcessOwnership.js";
 import { spawnOwnedProviderProcess, } from "../process/ProviderProcess.js";
 import { ghidraJavaEnvironment } from "./GhidraInstallation.js";
+import { ghidraJavaLaunch } from "./GhidraJavaLaunch.js";
 import { snapshotGhidraExtensions, } from "./extensions/GhidraExtensions.js";
 /** Local launch failure retained as the cause of a provider-neutral error. */
 export class GhidraLaunchError extends Error {
@@ -58,7 +59,7 @@ export class GhidraHeadlessLauncher {
                     ? {}
                     : { dosMz: this.options.dosMz }),
             });
-            const command = ghidraHeadlessCommand({
+            const scriptCommand = ghidraHeadlessCommand({
                 platform,
                 analyzeHeadlessPath: this.options.analyzeHeadlessPath,
                 arguments: headlessArguments,
@@ -66,24 +67,45 @@ export class GhidraHeadlessLauncher {
                     ? {}
                     : { comSpec: this.options.comSpec }),
             });
+            const environment = ghidraLaunchEnvironment(paths, this.options.javaHome, platform, scriptCommand.command);
+            if (platform !== "win32" && this.options.javaHome === undefined)
+                throw new GhidraLaunchError("POSIX Ghidra requires its inspected JDK home");
+            const command = platform !== "win32" && this.options.javaHome !== undefined
+                ? await ghidraJavaLaunch({
+                    platform,
+                    analyzeHeadlessPath: this.options.analyzeHeadlessPath,
+                    javaHome: this.options.javaHome,
+                    homeRoot: paths.homeRoot,
+                    tempRoot: paths.tempRoot,
+                    arguments: headlessArguments,
+                    environment,
+                    ...(options.signal === undefined
+                        ? {}
+                        : { signal: options.signal }),
+                })
+                : { ...scriptCommand, environment };
             started = await spawnOwnedProviderProcess({
                 command: command.command,
                 arguments: command.arguments,
                 runId: session.runId,
-                // analyzeHeadless is an interpreter-driven script. Parent identity and
-                // the per-process run token remain the cleanup authority.
-                expectedCommand: null,
+                // POSIX launches the inspected JVM directly; script wrappers cannot
+                // preserve JVM property paths containing spaces as single arguments.
+                expectedCommand: platform !== "win32" ? command.command : null,
                 windowsVerbatimArguments: platform === "win32",
                 platform,
-                env: ghidraLaunchEnvironment(paths, this.options.javaHome, platform, command.command),
+                env: command.environment,
+                ...(options.signal === undefined ? {} : { signal: options.signal }),
             });
             await writeGhidraRuntimeFile(paths.ownershipPath, `${JSON.stringify({
                 run_id: session.runId,
+                transport: session.transport,
+                endpoint_path: session.endpointPath,
                 pid: started.ownership.leaderPid,
                 process_group_id: started.ownership.processGroupId,
                 parent_pid: process.pid,
                 ownership_kind: platform === "win32" ? "windows-job-object" : "posix-process-group",
-                launcher: this.options.analyzeHeadlessPath,
+                launcher: command.command,
+                headless_script: this.options.analyzeHeadlessPath,
                 created_at: new Date().toISOString(),
             })}\n`, platform);
             if (isAborted(options.signal)) {
@@ -266,22 +288,18 @@ const ghidraLaunchEnvironment = (paths, javaHome, platform, executable) => {
         XDG_DATA_HOME: paths.dataRoot,
     };
 };
-/** Encode provider-owned JVM paths for the parser that actually consumes them. */
+/** Encode provider-owned JVM paths for the platform launcher that consumes them. */
 export const ghidraHeadlessJavaOptions = (homeRoot, tempRoot, platform) => {
     const options = [`-Duser.home=${homeRoot}`, `-Djava.io.tmpdir=${tempRoot}`];
-    // analyzeHeadless.bat quotes VMARG_LIST, then launch.bat expands it again.
-    // Inner quotes fail in cmd.exe; unquoted paths with spaces split at the JVM.
-    // JDK_JAVA_OPTIONS is parsed by Java itself, outside that batch expansion.
-    return platform === "win32"
-        ? {
+    if (platform === "win32")
+        return {
             JDK_JAVA_OPTIONS: [...options, "-XX:-UsePerfData"]
                 .map(quoteWindowsBatchToken)
                 .join(" "),
             GHIDRA_HEADLESS_JAVA_OPTIONS: "",
-        }
-        : {
-            JDK_JAVA_OPTIONS: "",
-            GHIDRA_HEADLESS_JAVA_OPTIONS: options.join(" "),
         };
+    // POSIX launches the JVM directly, so these properties travel as separate
+    // argv items instead of the shell-split analyzeHeadless option list.
+    return { JDK_JAVA_OPTIONS: "", GHIDRA_HEADLESS_JAVA_OPTIONS: "" };
 };
 const isAborted = (signal) => signal?.aborted === true;

package/dist/ghidra/GhidraProvider.js

@@ -163,11 +163,11 @@ const inspectWindowsP0TargetSupport = (target, diagnostics) => {
             reason: "Windows Ghidra P0 accepts PE targets only.",
             diagnostics,
         };
-    if (target.architecture !== "x86_64")
+    if (target.architecture !== "x86" && target.architecture !== "x86_64")
         return {
             status: "unsupported",
             code: "architecture_unsupported",
-            reason: "Windows Ghidra P0 accepts x86-64 PE targets only.",
+            reason: "Windows Ghidra P0 accepts x86 and x86-64 PE targets only.",
             diagnostics,
         };
     if (target.executableRole !== "application")

package/dist/ghidra/GhidraProviderCapabilities.js

@@ -16,10 +16,11 @@ export const GHIDRA_OPERATIONS = Object.freeze([
 export const healthLimitations = Object.freeze([
     "The session serves operations only after Ghidra reports default auto-analysis complete; incomplete analysis does not expose partial results.",
     "The imported Program and temporary project are ephemeral and deleted on close. Annotation operations edit session database metadata; original executable bytes are never written.",
+    "Cancelling an active Ghidra request terminates its ephemeral database and discards session annotations. The selected target remains open; the next provider query imports the original artifact again.",
 ]);
 /** Additional limitations applied to the experimental Windows x64 P0 boundary. */
 export const windowsP0Limitations = Object.freeze([
-    "Windows Ghidra P0 accepts approved native x86-64 PE applications only; DLL, managed, hostile, sensitive, and mutable-path targets are unsupported.",
+    "Windows Ghidra P0 accepts approved native x86 and x86-64 PE applications only; DLL, managed, hostile, sensitive, and mutable-path targets are unsupported.",
     "The Windows bridge uses authenticated IPv4 loopback because Node path-based IPC does not expose Java AF_UNIX sockets; the endpoint file contains no bearer token.",
     "Windows sessions require the matching packaged Windows x64 native addon, local NTFS targets and runtimes, and Windows 10 or later. Native handles enforce path admission, private DACLs, and Job Object ownership automatically.",
 ]);
@@ -33,7 +34,8 @@ export const limitationsFor = (operation) => {
         case "annotate_native_function":
             return [
                 ...common,
-                "Names use Ghidra USER_DEFINED source. Name writes preserve the existing namespace; readback uses the fully qualified name. Regular comments map to PRE and inline comments to EOL at the exact function entry. Changes commit together after readback and refreshed analysis; failure rolls them all back.",
+                "Names use Ghidra USER_DEFINED source. Name writes accept a leaf name or a fully qualified name within the existing namespace; readback uses the fully qualified name and can be reused without adding namespace prefixes. Edits retain the current namespace; other namespace-like text remains literal leaf-name text. Regular comments map to PRE and inline comments to EOL at the exact function entry. Changes commit together after readback and refreshed analysis; failure rolls them all back.",
+                "Annotation text rejects NUL and unpaired Unicode surrogates before mutation, with the field and UTF-16 index in the error. Supported Unicode and line endings are preserved.",
                 "Metadata edits invalidate immutable analysis snapshots and are discarded on close. CLI returns the updated dossier before session cleanup; this is not a saved Ghidra project.",
             ];
         case "inspect_native_load_image":
@@ -72,6 +74,11 @@ export const limitationsFor = (operation) => {
                 ...common,
                 "Only Ghidra-defined string Data is observed; charset is reported, while a non-missing terminator cannot distinguish a present terminator from a fixed or Pascal layout.",
             ];
+        case "resolve_containing_procedure":
+            return [
+                ...common,
+                "An exact external entry resolves to its observed function identity even when its body is empty. This does not establish mapped executable bytes or containment of nearby external addresses.",
+            ];
         case "list_segments":
             return [
                 ...common,
@@ -79,7 +86,10 @@ export const limitationsFor = (operation) => {
             ];
         case "search_procedures":
         case "search_strings":
-            return common;
+            return [
+                ...common,
+                "Regex mode uses Java Pattern semantics. Matcher or compiler stack exhaustion returns a resource constraint without closing the session; literal mode avoids regex recursion and returns complete matching values.",
+            ];
         case "procedure_pseudo_code":
             return [
                 ...common,
@@ -112,12 +122,14 @@ export const limitationsFor = (operation) => {
         case "procedure_references":
             return [
                 ...common,
+                "References cover the complete Ghidra function-body AddressSet and exact entry, including instruction-interior destinations and embedded-data sources; an enclosing address span does not establish function ownership.",
                 "Reference kinds are direct Ghidra ReferenceManager observations; unresolved computed flows without a target are absent and remain unknown.",
                 "Synthetic Ghidra entry-point references without actionable memory sources are omitted.",
             ];
         case "analyze_function":
             return [
                 ...common,
+                "References cover the complete Ghidra function-body AddressSet and exact entry. Dossier incoming edges omit sources owned by that function; procedure_references also retains those internal edges.",
                 "The dossier combines Ghidra FunctionManager, Listing, ReferenceManager, BasicBlockModel, and decompiler observations; provider-specific pseudocode and assembly are not cross-provider text invariants.",
                 "Resolved reference metadata identifies computed, indirect, external, call, jump, and data edges; unresolved targetless flows remain unknown, and function classifications distinguish thunks and externals.",
                 "Synthetic Ghidra entry-point references without actionable memory sources are omitted.",

package/dist/ghidra/GhidraProviderClient.js

@@ -1,11 +1,10 @@
 import { fileURLToPath } from "node:url";
 import { createAnalysisExecution, } from "../application/AnalysisProvider.js";
-import { AnalysisCancelledError, AnalysisCapabilityUnavailableError, AnalysisInputError, AnalysisTimeoutError, } from "../domain/analysisErrorCore.js";
+import { AnalysisCancelledError, AnalysisArtifactChangedError, AnalysisAccessDeniedError, AnalysisCapabilityUnavailableError, AnalysisInputError, AnalysisResourceConstraintError, AnalysisTimeoutError, } from "../domain/analysisErrorCore.js";
 import {} from "../domain/analysisErrorBase.js";
 import { ProviderAdapterError } from "../domain/providerAdapterError.js";
 import { err, ok } from "../domain/result.js";
 import { GhidraClient } from "./GhidraClient.js";
-import { GHIDRA_STARTUP_TIMEOUT_MS } from "./GhidraDefaults.js";
 import { isGhidraFunctionOperation, parseGhidraFunctionInput, parseGhidraFunctionResult, } from "./GhidraFunctionValues.js";
 import { isGhidraInventoryOperation, parseGhidraInventoryInput, parseGhidraInventoryResult, } from "./GhidraInventoryValues.js";
 import { ghidraInstallationDiagnostics, } from "./GhidraInstallation.js";
@@ -55,12 +54,11 @@ export const createGhidraProviderClient = (input) => {
             ]
             : [];
     const client = clientFactory({
+        startupTimeoutMs: config.ghidraStartupTimeoutMs,
         platform: installation.platform,
         launcher: new GhidraHeadlessLauncher({
             analyzeHeadlessPath: prerequisites.value.analyzeHeadlessPath,
-            ...(config.ghidraJavaHome === undefined
-                ? {}
-                : { javaHome: config.ghidraJavaHome }),
+            javaHome: prerequisites.value.javaHome,
             bridgeScriptPath: fileURLToPath(new URL("../../bridge/ghidra/ReaGhidraBridge.java", import.meta.url)),
             ...(target.format === "dos-mz" ? { dosMz: true } : {}),
             ...(target.format === "dos-com" ? { dosCom: true } : {}),
@@ -110,7 +108,7 @@ export const createGhidraProviderClient = (input) => {
             if (operation === "health") {
                 const started = await client.start(options?.signal);
                 if (!started.ok)
-                    return err(projectSessionError(operation, started.error));
+                    return err(projectSessionError(operation, started.error, config.ghidraStartupTimeoutMs));
                 const failed = await checkExtensions(operation, started.value);
                 if (failed !== undefined)
                     return err(failed);
@@ -127,14 +125,14 @@ export const createGhidraProviderClient = (input) => {
             if (extensions.length > 0) {
                 const started = await client.start(options?.signal);
                 if (!started.ok)
-                    return err(projectSessionError(operation, started.error));
+                    return err(projectSessionError(operation, started.error, config.ghidraStartupTimeoutMs));
                 const failed = await checkExtensions(operation, started.value);
                 if (failed !== undefined)
                     return err(failed);
             }
             const called = await client.callTool(operation, input.value, options?.signal === undefined ? {} : { signal: options.signal });
             if (!called.ok)
-                return err(projectSessionError(operation, called.error));
+                return err(projectSessionError(operation, called.error, config.ghidraStartupTimeoutMs));
             const result = isGhidraFunctionOperation(operation)
                 ? parseGhidraFunctionResult(operation, called.value)
                 : parseGhidraInventoryResult(operation, called.value);
@@ -142,7 +140,7 @@ export const createGhidraProviderClient = (input) => {
                 return result;
             let normalized = result.value;
             if (operation === "inspect_native_load_image") {
-                const attested = await attestGhidraNativeLoadImage(target, operation, result.value, client, (failure) => projectSessionError(operation, failure));
+                const attested = await attestGhidraNativeLoadImage(target, operation, result.value, client, (failure) => projectSessionError(operation, failure, config.ghidraStartupTimeoutMs));
                 if (!attested.ok)
                     return attested;
                 normalized = attested.value;
@@ -176,6 +174,7 @@ const ghidraClientPrerequisites = (target, profile, installation) => {
         return err(new ProviderAdapterError("ghidra", "health"));
     return ok({
         analyzeHeadlessPath: installation.analyzeHeadlessPath,
+        javaHome: installation.javaHome,
         providerVersion: installation.providerVersion,
         profile,
     });
@@ -184,7 +183,11 @@ const unavailableClient = (failure) => ({
     execute: () => Promise.resolve(err(failure)),
     close: () => Promise.resolve(),
 });
-const projectSessionError = (operation, failure) => {
+const projectSessionError = (operation, failure, startupTimeoutMs) => {
+    if (failure.cause instanceof AnalysisAccessDeniedError)
+        return new AnalysisAccessDeniedError(operation, failure.cause.path, failure.cause.systemCode, { cause: failure });
+    if (failure.cause instanceof AnalysisArtifactChangedError)
+        return new AnalysisArtifactChangedError(operation, failure.cause.path, failure.cause.reason, { cause: failure });
     if (operation === "annotate_native_function" &&
         failure.kind === "remote" &&
         failure.remoteCode === "invalid_function_name")
@@ -194,12 +197,20 @@ const projectSessionError = (operation, failure) => {
     if (failure.kind === "cancelled")
         return new AnalysisCancelledError(operation);
     if (failure.kind === "timeout" || failure.kind === "analysis_timeout")
-        return new AnalysisTimeoutError(operation, failure.timeoutMs ?? GHIDRA_STARTUP_TIMEOUT_MS);
+        return new AnalysisTimeoutError(operation, failure.timeoutMs ?? startupTimeoutMs);
     if (failure.kind === "remote" && failure.remoteCode === "decompile_cancelled")
         return new AnalysisCancelledError(operation);
+    if (failure.kind === "remote" &&
+        failure.remoteCode === "regex_stack_exhausted")
+        return new AnalysisResourceConstraintError(operation, "memory", failure.message, null, {
+            cause: failure,
+            remediationAction: "Retry this search in literal mode or simplify the regex. The active analysis session and annotations remain available.",
+        });
     if (failure.kind === "remote" &&
         ["invalid_request", "not_found", "ambiguous"].includes(failure.remoteCode ?? ""))
-        return new AnalysisInputError(operation, { cause: failure });
+        return new AnalysisInputError(operation, { cause: failure }, [
+            { path: [], reason: "invalid_value", message: failure.message },
+        ]);
     if (failure.kind === "remote" && failure.remoteCode === "method_unavailable")
         return new AnalysisCapabilityUnavailableError("ghidra", operation, failure.message);
     return new ProviderAdapterError("ghidra", operation, {

package/dist/ghidra/GhidraSessionError.js

@@ -14,13 +14,17 @@ export class GhidraSessionError extends Error {
     }
 }
 /** Build a session failure while preserving bounded remote failure metadata. */
-const createGhidraSessionError = (failure) => new GhidraSessionError(failure.kind, failure.message, failure.remoteCode === undefined
-    ? failure.diagnostics
-    : {
-        ...failure.diagnostics,
-        remote_code: failure.redact(failure.remoteCode),
-        remote_message: failure.message,
-    }, {
+const createGhidraSessionError = (failure) => new GhidraSessionError(failure.kind, failure.message, {
+    ...failure.diagnostics,
+    failure_kind: failure.kind,
+    failure_message: failure.message,
+    ...(failure.remoteCode === undefined
+        ? {}
+        : {
+            remote_code: failure.redact(failure.remoteCode),
+            remote_message: failure.message,
+        }),
+}, {
     ...(failure.cause === undefined ? {} : { cause: failure.cause }),
     ...(failure.timeoutMs === undefined
         ? {}

package/dist/ghidra/GhidraTargetSnapshot.js

@@ -1,7 +1,10 @@
 import { createHash } from "node:crypto";
-import { constants, createReadStream } from "node:fs";
-import { chmod, copyFile, rm } from "node:fs/promises";
+import { constants } from "node:fs";
+import { open, rm } from "node:fs/promises";
 import { extname, join } from "node:path";
+import { Transform } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { AnalysisArtifactChangedError, AnalysisAccessDeniedError, } from "../domain/analysisErrorCore.js";
 import { windowsPrivateRuntime } from "../windows/WindowsPrivateRuntime.js";
 /** Copy one target and require its bytes to match the parsed target identity. */
 export const createGhidraTargetSnapshot = async (sourcePath, runtimeRoot, expectedSha256, options = {}) => {
@@ -12,29 +15,61 @@ export const createGhidraTargetSnapshot = async (sourcePath, runtimeRoot, expect
     if ((options.platform ?? process.platform) === "win32") {
         const observed = await windowsPrivateRuntime(runtimeRoot).snapshot(sourcePath, `target-${expectedSha256.slice(0, 12)}${suffix}`, options.signal);
         if (observed.sha256 !== expectedSha256)
-            throw new Error(`Ghidra target snapshot digest mismatch: expected ${expectedSha256}, observed ${observed.sha256}`);
+            throw new AnalysisArtifactChangedError("open_binary", sourcePath, `Ghidra target snapshot digest mismatch: expected ${expectedSha256}, observed ${observed.sha256}`);
         return {
             path: snapshotPath,
             sha256: observed.sha256,
             admission: { source: observed.source, snapshot: observed.snapshot },
         };
     }
+    let source;
+    let destination;
     try {
-        await copyFile(sourcePath, snapshotPath, constants.COPYFILE_EXCL);
-        await chmod(snapshotPath, 0o600);
+        source = await openSnapshotSource(sourcePath);
+        if (!(await source.stat()).isFile())
+            throw new AnalysisArtifactChangedError("open_binary", sourcePath, "The selected Ghidra source is no longer a regular file");
+        destination = await open(snapshotPath, "wx", 0o600);
+        await destination.chmod(0o600);
         const hash = createHash("sha256");
-        for await (const chunk of createReadStream(snapshotPath))
-            hash.update(chunk);
+        const digest = new Transform({
+            transform(chunk, _encoding, done) {
+                if (!Buffer.isBuffer(chunk)) {
+                    done(new TypeError("Ghidra snapshot stream must contain bytes"));
+                    return;
+                }
+                hash.update(chunk);
+                done(null, chunk);
+            },
+        });
+        await pipeline(source.createReadStream(), digest, destination.createWriteStream(), options.signal === undefined ? {} : { signal: options.signal });
         const observedSha256 = hash.digest("hex");
         if (observedSha256 !== expectedSha256)
-            throw new Error(`Ghidra target snapshot digest mismatch: expected ${expectedSha256}, observed ${observedSha256}`);
+            throw new AnalysisArtifactChangedError("open_binary", sourcePath, `Ghidra target snapshot digest mismatch: expected ${expectedSha256}, observed ${observedSha256}`);
         return { path: snapshotPath, sha256: observedSha256 };
     }
     catch (cause) {
-        await rm(snapshotPath, { force: true }).catch((cause) => {
-            // best-effort cleanup: snapshot removal must not mask the copy failure.
-            void cause;
-        });
+        if (destination !== undefined)
+            await rm(snapshotPath, { force: true }).catch((cause) => {
+                // best-effort cleanup: snapshot removal must not mask the copy failure.
+                void cause;
+            });
+        throw cause;
+    }
+    finally {
+        await Promise.all([source?.close(), destination?.close()]);
+    }
+};
+const openSnapshotSource = async (path) => {
+    try {
+        // A path replaced by a FIFO must not block startup before its type is checked.
+        return await open(path, constants.O_RDONLY | constants.O_NONBLOCK);
+    }
+    catch (cause) {
+        const code = cause instanceof Error && "code" in cause ? cause.code : undefined;
+        if (code === "EACCES" || code === "EPERM")
+            throw new AnalysisAccessDeniedError("open_binary", path, code, { cause });
+        if (code === "ENOENT" || code === "ENOTDIR" || code === "ELOOP")
+            throw new AnalysisArtifactChangedError("open_binary", path, `The selected Ghidra source could not be opened (${code})`, { cause });
         throw cause;
     }
 };

package/dist/ghidra/GhidraTransport.js

@@ -1,7 +1,27 @@
 import { access, open } from "node:fs/promises";
+import { join } from "node:path";
+import { PrivateRuntimeRoot } from "../process/PrivateRuntimeRoot.js";
 import { readWindowsPrivateRuntimeFile } from "../windows/WindowsPrivateRuntime.js";
 import { err, ok } from "../domain/result.js";
 import { GhidraSessionError } from "./GhidraSessionError.js";
+/** Allocate an endpoint that fits the host's Unix sockaddr without moving the project. */
+export const createGhidraEndpoint = async (runtimeRoot, transport, platform) => {
+    const path = join(runtimeRoot, transport === "unix-socket" ? "bridge.sock" : "bridge-endpoint.json");
+    // sockaddr_un includes a terminating NUL: macOS has 104 bytes, Linux 108.
+    const maximumPathBytes = platform === "darwin" ? 103 : 107;
+    if (transport !== "unix-socket" ||
+        Buffer.byteLength(path, "utf8") <= maximumPathBytes)
+        return { endpoint: { transport, path } };
+    const socketRoot = await PrivateRuntimeRoot.create({
+        parent: "/tmp",
+        prefix: "rea-ghidra-socket-",
+        platform,
+    });
+    return {
+        endpoint: { transport, path: join(socketRoot.path, "s") },
+        socketRoot,
+    };
+};
 /** Observe a ready endpoint, returning null while its bridge is not listening. */
 export const observeGhidraEndpoint = async (endpoint) => {
     if (endpoint.transport === "unix-socket") {