rea-agents 6.1.0 → 6.2.0

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";
@@ -20,8 +21,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 +93,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 +157,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 +257,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 +268,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);
@@ -258,8 +295,7 @@ export class GhidraClient {
                 : 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 +304,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 +423,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 +444,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,8 +517,7 @@ export class GhidraClient {
     }
     async #startupInterrupted(deadline) {
         const failure = this.#interruptionFailure(deadline);
-        await this.#cleanup();
-        return err(failure);
+        return this.#startupFailure(failure);
     }
     #interruptionFailure(deadline) {
         return deadline.interruption === "cancelled"

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,9 +1,9 @@
+import { snapshotEnvironment } from "../process/snapshotEnvironment.js";
 import { spawnSync } from "node:child_process";
 import { constants } from "node:fs";
 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" },
@@ -97,17 +97,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,
@@ -149,6 +147,35 @@ const installationChecks = ({ coordinates, platform, architecture, javaHome, hos
     }),
     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 +196,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 +210,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

package/dist/ghidra/GhidraJavaLaunch.js

@@ -1,3 +1,4 @@
+import { snapshotEnvironment } from "../process/snapshotEnvironment.js";
 import { dirname, join } from "node:path";
 import { execFileOutput } from "../process/ExecFileOutput.js";
 /** Launch coordinates obtained from Ghidra's own release configuration helper. */
@@ -16,7 +17,9 @@ export const ghidraJavaLaunch = async (options) => {
         "LaunchSupport",
         installRoot,
     ];
-    const environment = { ...options.environment };
+    const environment = {
+        ...snapshotEnvironment(options.environment, options.platform),
+    };
     const configuredEnvironment = await execFileOutput(command, [...supportArguments, "-envvars"], {
         env: environment,
         ...(options.signal === undefined ? {} : { signal: options.signal }),
@@ -25,7 +28,8 @@ export const ghidraJavaLaunch = async (options) => {
         if (line === "")
             continue;
         const separator = line.indexOf("=");
-        const key = line.slice(0, separator);
+        const sourceKey = line.slice(0, separator);
+        const key = options.platform === "win32" ? sourceKey.toUpperCase() : sourceKey;
         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] ?? "") === "")

package/dist/ghidra/GhidraLauncher.js

@@ -1,3 +1,4 @@
+import { snapshotEnvironment } from "../process/snapshotEnvironment.js";
 import { mkdir } from "node:fs/promises";
 import { basename, dirname, join, win32 } from "node:path";
 import writeFileAtomic from "write-file-atomic";
@@ -20,7 +21,10 @@ export class GhidraLaunchError extends Error {
 export class GhidraHeadlessLauncher {
     options;
     constructor(options) {
-        this.options = options;
+        this.options = {
+            ...options,
+            environment: snapshotEnvironment(options.environment, options.platform),
+        };
     }
     async launch(session, options = {}) {
         if (isAborted(options.signal))
@@ -60,6 +64,7 @@ export class GhidraHeadlessLauncher {
                     : { dosMz: this.options.dosMz }),
             });
             const scriptCommand = ghidraHeadlessCommand({
+                environment: this.options.environment,
                 platform,
                 analyzeHeadlessPath: this.options.analyzeHeadlessPath,
                 arguments: headlessArguments,
@@ -67,7 +72,7 @@ export class GhidraHeadlessLauncher {
                     ? {}
                     : { comSpec: this.options.comSpec }),
             });
-            const environment = ghidraLaunchEnvironment(paths, this.options.javaHome, platform, scriptCommand.command);
+            const environment = ghidraLaunchEnvironment(paths, this.options.javaHome, platform, scriptCommand.command, this.options.environment);
             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
@@ -94,6 +99,7 @@ export class GhidraHeadlessLauncher {
                 windowsVerbatimArguments: platform === "win32",
                 platform,
                 env: command.environment,
+                hostEnvironment: {},
                 ...(options.signal === undefined ? {} : { signal: options.signal }),
             });
             await writeGhidraRuntimeFile(paths.ownershipPath, `${JSON.stringify({
@@ -145,11 +151,13 @@ export const ghidraHeadlessCommand = (options) => {
             command: options.analyzeHeadlessPath,
             arguments: [...options.arguments],
         };
+    const environment = snapshotEnvironment(options.environment, options.platform);
+    const systemRoot = environment.SYSTEMROOT;
     const comSpec = options.comSpec ??
-        process.env.ComSpec ??
-        (process.env.SystemRoot === undefined
+        environment.COMSPEC ??
+        (systemRoot === undefined
             ? "C:\\Windows\\System32\\cmd.exe"
-            : win32.join(process.env.SystemRoot, "System32", "cmd.exe"));
+            : win32.join(systemRoot, "System32", "cmd.exe"));
     if (!win32.isAbsolute(comSpec) ||
         win32.basename(comSpec).toLowerCase() !== "cmd.exe")
         throw new GhidraLaunchError("Windows ComSpec must be an absolute cmd.exe path");
@@ -265,9 +273,9 @@ const writeGhidraRuntimeFile = async (path, content, platform) => {
     }
     await writeFileAtomic(path, content, { encoding: "utf8", mode: 0o600 });
 };
-const ghidraLaunchEnvironment = (paths, javaHome, platform, executable) => {
+const ghidraLaunchEnvironment = (paths, javaHome, platform, executable, selectedEnvironment) => {
     return {
-        ...ghidraJavaEnvironment(javaHome, process.env, platform),
+        ...ghidraJavaEnvironment(javaHome, selectedEnvironment, platform),
         ...ghidraHeadlessJavaOptions(paths.homeRoot, paths.tempRoot, platform),
         HOME: paths.homeRoot,
         TMPDIR: paths.tempRoot,

package/dist/ghidra/GhidraProvider.js

@@ -1,3 +1,4 @@
+import { snapshotEnvironment } from "../process/snapshotEnvironment.js";
 import {} from "../application/AnalysisProvider.js";
 import { createAnalysisProfile, } from "../domain/analysisProfile.js";
 import { jsonObjectSchema, jsonValueSchema, } from "../domain/jsonValue.js";
@@ -9,7 +10,6 @@ import { resolveGhidraExtensions } from "./extensions/GhidraExtensions.js";
 import { CAPABILITIES, windowsP0Capabilities, GHIDRA_PROVIDER_IDENTITY, GHIDRA_OPERATIONS, } from "./GhidraProviderCapabilities.js";
 import { createGhidraProviderClient, } from "./GhidraProviderClient.js";
 import { windowsNativeAuthorityUnavailableReason, hasWindowsNativeAuthority, windowsNativeCapabilities, } from "../process/WindowsAuthority.js";
-export { GHIDRA_PROVIDER_IDENTITY, GHIDRA_OPERATIONS };
 const SUPPORTED_ARCHITECTURES = new Set(["x86", "x86_64", "arm", "arm64"]);
 /** Ghidra candidate backed by an isolated ephemeral headless import. */
 export class GhidraProvider {
@@ -18,11 +18,13 @@ export class GhidraProvider {
     installationHost;
     clientFactory;
     #installation;
-    constructor(config, logger, installationHost, clientFactory = (options) => new GhidraClient(options)) {
+    environment;
+    constructor(config, logger, environment, installationHost, clientFactory = (options) => new GhidraClient(options)) {
         this.config = config;
         this.logger = logger;
         this.installationHost = installationHost;
         this.clientFactory = clientFactory;
+        this.environment = snapshotEnvironment(environment, installationHost?.platform);
     }
     identity() {
         return GHIDRA_PROVIDER_IDENTITY;
@@ -125,6 +127,7 @@ export class GhidraProvider {
     createClient(target, profile, context) {
         return createGhidraProviderClient({
             config: this.config,
+            environment: this.environment,
             logger: this.logger,
             clientFactory: this.clientFactory,
             target,
@@ -135,6 +138,7 @@ export class GhidraProvider {
     }
     #inspectInstallation() {
         const options = {
+            environment: this.environment,
             ...(this.config.ghidraInstallDir === undefined
                 ? {}
                 : { installDir: this.config.ghidraInstallDir }),

package/dist/ghidra/GhidraProviderCapabilities.js

@@ -146,6 +146,12 @@ export const CAPABILITIES = Object.freeze(GHIDRA_OPERATIONS.map((operation) => {
         operation,
         available: true,
         reason: null,
+        // Project writes are private import machinery. Analysis reads are bound
+        // to the artifact/profile; session annotations disable snapshot replay.
+        ...(operation === "annotate_native_function" ||
+            operation === "list_documents"
+            ? {}
+            : { cachePolicy: "snapshot" }),
         effects: Object.freeze({
             mutatesArtifact: operation === "annotate_native_function",
             launchesProcess: true,

package/dist/ghidra/GhidraProviderClient.js

@@ -1,3 +1,4 @@
+import { analysisErrorWithCleanupFailure } from "../application/binary/AnalysisClientCleanup.js";
 import { fileURLToPath } from "node:url";
 import { createAnalysisExecution, } from "../application/AnalysisProvider.js";
 import { AnalysisCancelledError, AnalysisArtifactChangedError, AnalysisAccessDeniedError, AnalysisCapabilityUnavailableError, AnalysisInputError, AnalysisResourceConstraintError, AnalysisTimeoutError, } from "../domain/analysisErrorCore.js";
@@ -57,6 +58,7 @@ export const createGhidraProviderClient = (input) => {
         startupTimeoutMs: config.ghidraStartupTimeoutMs,
         platform: installation.platform,
         launcher: new GhidraHeadlessLauncher({
+            environment: input.environment,
             analyzeHeadlessPath: prerequisites.value.analyzeHeadlessPath,
             javaHome: prerequisites.value.javaHome,
             bridgeScriptPath: fileURLToPath(new URL("../../bridge/ghidra/ReaGhidraBridge.java", import.meta.url)),
@@ -87,8 +89,10 @@ export const createGhidraProviderClient = (input) => {
         extensionFailure = ghidraExtensionFailure(extensions, info.analysis_extensions ?? [], operation);
         if (extensionFailure === undefined)
             return undefined;
-        await client.close();
-        return extensionFailure;
+        const closed = await client.close();
+        return closed.ok
+            ? extensionFailure
+            : analysisErrorWithCleanupFailure(extensionFailure, closed.error, operation);
     };
     const releaseLimitation = unverifiedGhidraBuildLimitation(prerequisites.value.providerVersion);
     const sessionLimitations = [
@@ -181,9 +185,15 @@ const ghidraClientPrerequisites = (target, profile, installation) => {
 };
 const unavailableClient = (failure) => ({
     execute: () => Promise.resolve(err(failure)),
-    close: () => Promise.resolve(),
+    close: () => Promise.resolve(ok(null)),
 });
 const projectSessionError = (operation, failure, startupTimeoutMs) => {
+    const primary = projectPrimarySessionError(operation, failure, startupTimeoutMs);
+    return failure.cleanupFailure === undefined
+        ? primary
+        : analysisErrorWithCleanupFailure(primary, failure.cleanupFailure, operation);
+};
+const projectPrimarySessionError = (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)

package/dist/ghidra/GhidraSessionError.js

@@ -4,6 +4,7 @@ export class GhidraSessionError extends Error {
     diagnostics;
     timeoutMs;
     remoteCode;
+    cleanupFailure;
     constructor(kind, message, diagnostics = {}, options = {}) {
         super(message, options);
         this.kind = kind;
@@ -11,6 +12,7 @@ export class GhidraSessionError extends Error {
         this.diagnostics = structuredClone(diagnostics);
         this.timeoutMs = options.timeoutMs;
         this.remoteCode = options.remoteCode;
+        this.cleanupFailure = options.cleanupFailure;
     }
 }
 /** Build a session failure while preserving bounded remote failure metadata. */

package/dist/ghidra/GhidraSessionRoot.js

@@ -0,0 +1,39 @@
+import { dirname, isAbsolute, resolve, sep } from "node:path";
+import { tmpdir } from "node:os";
+/** Session roots may not contain a dot-prefixed path element. */
+const hasDotPrefixElement = (directory) => resolve(directory)
+    .split(sep)
+    .some((element) => element.startsWith("."));
+/** Nearest ancestor of `directory`, inclusive, that has no dot-prefixed element. */
+const nearestSafeAncestor = (directory) => {
+    let current = resolve(directory);
+    for (;;) {
+        if (!hasDotPrefixElement(current))
+            return current;
+        const parent = dirname(current);
+        if (parent === current)
+            return undefined;
+        current = parent;
+    }
+};
+/**
+ * Select a session root usable as the parent of a Ghidra project path.
+ *
+ * Ghidra validates every project path element with `NamingUtilities.checkName`
+ * and aborts the headless analyzer on any element that starts with `.`, so an
+ * inherited `TMPDIR` such as `~/.cache/<tool>` fails every Ghidra operation
+ * with a generic analysis failure. Prefer the inherited base when it is usable,
+ * then a dot-free platform temp directory, then the nearest dot-free ancestor.
+ */
+export const ghidraSessionRoot = (options = {}) => {
+    const base = resolve(options.base ?? tmpdir());
+    if (!hasDotPrefixElement(base))
+        return base;
+    const platform = options.platform ?? process.platform;
+    const fallback = options.fallback ?? (platform === "win32" ? undefined : "/tmp");
+    if (fallback !== undefined &&
+        isAbsolute(fallback) &&
+        !hasDotPrefixElement(fallback))
+        return resolve(fallback);
+    return nearestSafeAncestor(base) ?? base;
+};