rea-agents 5.0.0 → 6.1.0

package/dist/evm/EvmoleInterfaceProvider.js

@@ -0,0 +1,273 @@
+import { createHash, randomUUID } from "node:crypto";
+import { access, readFile, stat, writeFile } from "node:fs/promises";
+import { constants } from "node:fs";
+import { isAbsolute, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { z } from "zod";
+import { createAnalysisExecution, } from "../application/AnalysisProvider.js";
+import { readStableArtifact } from "../artifacts/readStableArtifact.js";
+import { OwnedCommandFailure } from "../process/OwnedCommand.js";
+import { AnalysisCancelledError, AnalysisCapabilityUnavailableError, AnalysisUnsupportedTargetError, AnalysisInputError, AnalysisOutputError, } from "../domain/analysisErrorCore.js";
+import { projectAnalysisError } from "../domain/analysisErrorProjection.js";
+import { evmInterfaceSchema } from "../domain/evm/evmInterface.js";
+import { ProviderAdapterError } from "../domain/providerAdapterError.js";
+import { ProviderCleanupError } from "../domain/providerCleanupError.js";
+import { err, ok } from "../domain/result.js";
+import { runOwnedCommand } from "../process/OwnedCommand.js";
+import { PrivateRuntimeRoot } from "../process/PrivateRuntimeRoot.js";
+import { evmInterfaceFailure, capturedEvmOutput, } from "./EvmoleFailures.js";
+import { evmoleInterfaceReplySchema, projectEvmoleInterface, } from "./EvmoleInterfaceAdapter.js";
+import { EVMOLE_PROVIDER_IDENTITY, EVM_INTERFACE_LIMITS, EVM_FILE_SIZE_FAILURE_EXIT, } from "./EvmoleRelease.js";
+import { decodeEvmBytecodeCarrier } from "./EvmBytecodeCarrier.js";
+import { selectEvmWorkerLimits, } from "./EvmWorkerLimits.js";
+const OPERATION = "inspect_evm_interface";
+const replySchema = z.discriminatedUnion("ok", [
+    z.strictObject({
+        ok: z.literal(true),
+        version: z.literal("0.9.3"),
+        bytecode: z.strictObject({
+            sha256: z.string().regex(/^[a-f0-9]{64}$/),
+            bytes: z.number().int().nonnegative(),
+            hex: z.string().regex(/^(?:[a-f0-9]{2})*$/),
+        }),
+        raw: evmoleInterfaceReplySchema,
+    }),
+    z.strictObject({
+        ok: z.literal(false),
+        reason: z.enum(["format", "decoder", "output-limit", "unsupported"]),
+        message: z.string(),
+    }),
+]);
+/** Run unchanged EVMole/WASM in an owned worker; no target, chain or network execution. */
+export class EvmoleInterfaceProvider {
+    environment;
+    launcher;
+    createRuntime;
+    constructor(environment = process.env, launcher, createRuntime = () => PrivateRuntimeRoot.create({ prefix: "rea-evm-interface-" })) {
+        this.environment = environment;
+        this.launcher = launcher;
+        this.createRuntime = createRuntime;
+    }
+    /** Bind recovered interface candidates to both original carrier and decoded byte identity. */
+    async inspect(input, options) {
+        let root;
+        let retainedOutput;
+        let phase = "configuration";
+        let workerLimits;
+        const limiter = this.environment.REA_EVM_PRLIMIT_COMMAND ?? "/usr/bin/prlimit";
+        let result;
+        try {
+            if (options?.signal?.aborted)
+                throw new AnalysisCancelledError(OPERATION);
+            if (process.platform !== "linux" || process.arch !== "x64")
+                throw new AnalysisCapabilityUnavailableError(EVMOLE_PROVIDER_IDENTITY.id, OPERATION, "Initial real-verified offline EVM interface profile supports Linux x64 only.");
+            try {
+                if (!isAbsolute(limiter))
+                    throw new Error("REA_EVM_PRLIMIT_COMMAND must be an absolute executable path.");
+                await access(limiter, constants.X_OK);
+                if (!(await stat(limiter)).isFile())
+                    throw new Error("Configured prlimit must be a regular executable file, not a directory.");
+            }
+            catch (cause) {
+                const reason = `Offline EVM interface inspection requires caller-supplied util-linux prlimit: ${limiter}; ${cause instanceof Error ? cause.message : String(cause)}`;
+                throw new AnalysisCapabilityUnavailableError(EVMOLE_PROVIDER_IDENTITY.id, OPERATION, reason, { cause, userMessage: reason });
+            }
+            let inheritedLimits;
+            try {
+                inheritedLimits = await readFile("/proc/self/limits", "utf8");
+            }
+            catch (cause) {
+                const reason = `Could not read inherited Linux resource limits at /proc/self/limits: ${cause instanceof Error ? cause.message : String(cause)}`;
+                throw new AnalysisCapabilityUnavailableError(EVMOLE_PROVIDER_IDENTITY.id, OPERATION, reason, { cause, userMessage: reason });
+            }
+            const limits = selectEvmWorkerLimits(inheritedLimits);
+            if (!limits.ok)
+                throw new AnalysisCapabilityUnavailableError(EVMOLE_PROVIDER_IDENTITY.id, OPERATION, limits.error, { userMessage: limits.error });
+            workerLimits = limits.value;
+            phase = "artifact-read";
+            const carrier = await readStableArtifact(input.path, EVM_INTERFACE_LIMITS.inputBytes, options?.signal);
+            phase = "worker";
+            root = await this.createRuntime();
+            const snapshotPath = join(root.path, "carrier.snapshot");
+            const requestPath = join(root.path, "request.json");
+            const replyPath = join(root.path, "reply.json");
+            await writeFile(snapshotPath, carrier.bytes, {
+                flag: "wx",
+                mode: 0o600,
+                ...(options?.signal === undefined ? {} : { signal: options.signal }),
+            });
+            await writeFile(requestPath, JSON.stringify({
+                snapshot_path: snapshotPath,
+                reply_path: replyPath,
+                failure_marker_path: join(root.path, "resource.failure"),
+                encoding: input.encoding,
+            }), { flag: "wx", mode: 0o600 });
+            const { NODE_OPTIONS: _ambientNodeOptions, ...environment } = this.environment;
+            const execution = await runOwnedCommand({
+                command: limiter,
+                arguments: [
+                    `--as=${String(workerLimits.addressSpaceBytes)}:`,
+                    `--fsize=${String(workerLimits.fileSizeBytes)}:`,
+                    "--core=0:",
+                    `--cpu=${String(workerLimits.cpuSeconds)}:`,
+                    "--",
+                    process.execPath,
+                    "--max-old-space-size=256",
+                    "--v8-pool-size=1",
+                    "--disable-wasm-trap-handler",
+                    fileURLToPath(new URL("./EvmoleInterfaceWorker.js", import.meta.url)),
+                    requestPath,
+                ],
+                cwd: root.path,
+                expectedCommand: null,
+                runId: `rea-evm-interface-${randomUUID()}`,
+                hostEnvironment: environment,
+            }, {
+                timeoutMs: EVM_INTERFACE_LIMITS.timeoutMs,
+                diagnosticBytes: EVM_INTERFACE_LIMITS.diagnosticBytes,
+            }, {
+                ...(options?.signal === undefined ? {} : { signal: options.signal }),
+                ...(this.launcher === undefined ? {} : { launcher: this.launcher }),
+            });
+            const capturedOutput = capturedEvmOutput(execution);
+            retainedOutput = capturedOutput;
+            let reply;
+            try {
+                const file = await readStableArtifact(replyPath, EVM_INTERFACE_LIMITS.outputBytes, options?.signal);
+                reply = replySchema.parse(JSON.parse(file.bytes.toString("utf8")));
+            }
+            catch (cause) {
+                if (options?.signal?.aborted)
+                    throw new AnalysisCancelledError(OPERATION, { capturedOutput });
+                throw new AnalysisOutputError(OPERATION, `Owned interface worker reply failed for ${input.path}: ${cause instanceof Error ? cause.message : String(cause)}`, { cause, capturedOutput });
+            }
+            if (!reply.ok) {
+                if (reply.reason === "unsupported")
+                    throw new AnalysisUnsupportedTargetError(OPERATION, input.path, reply.message, { capturedOutput });
+                if (reply.reason === "format")
+                    throw new AnalysisInputError(OPERATION, { capturedOutput }, [
+                        {
+                            path: ["path"],
+                            reason: "invalid_format",
+                            message: reply.message,
+                        },
+                    ]);
+                if (reply.reason === "output-limit")
+                    throw new AnalysisOutputError(OPERATION, reply.message, {
+                        capturedOutput,
+                    });
+                throw new ProviderAdapterError(EVMOLE_PROVIDER_IDENTITY.id, OPERATION, {
+                    diagnostics: {
+                        phase,
+                        failure_kind: reply.reason,
+                        reason: reply.message,
+                        stdout: execution.stdout.text,
+                        stderr: execution.stderr.text,
+                        captured_output: { ...capturedOutput },
+                    },
+                });
+            }
+            const selectedBytes = decodeEvmBytecodeCarrier(carrier.bytes, input.encoding);
+            const selectedHex = Buffer.from(selectedBytes).toString("hex");
+            const decodedHash = createHash("sha256")
+                .update(selectedBytes)
+                .digest("hex");
+            if (decodedHash !== reply.bytecode.sha256 ||
+                selectedHex !== reply.bytecode.hex ||
+                selectedBytes.length !== reply.bytecode.bytes)
+                throw new AnalysisOutputError(OPERATION, "Decoded bytecode representation does not match the selected carrier, encoding or reported SHA-256.", { capturedOutput });
+            const limitations = [
+                `Configured worker resource soft limits: address_space_bytes=${String(workerLimits.addressSpaceBytes)}, cpu_seconds=${String(workerLimits.cpuSeconds)}, file_size_bytes=${String(workerLimits.fileSizeBytes)}. Selected from inherited tighter limits; original hard limits are retained. Effective worker limits are not independently probed.`,
+                "Upstream may also report terminal metadata while recovering selectors. Its reported values are retained in raw_result, but integer precision and non-text-key coverage are unknown in the JS binding; complete original bytecode remains available.",
+                "Recovered selectors, argument strings and mutability are upstream inferences, not verified ABI signatures or names. Empty results do not prove the absence of callable dispatch.",
+                "Bytecode kind, hardfork and deployed-contract authenticity are unknown. This inspection performs no target runtime execution, chain/RPC lookup or network request.",
+                "Original carrier and decoded bytecode SHA-256 are distinct identities; SHA-256 is not the Ethereum Keccak code hash.",
+                "The owned worker has a 256 MiB JavaScript heap, 3 GiB virtual address-space limit and 30-second deadline. Virtual address space is distinct from resident memory; limits fail without partial success.",
+            ];
+            const validated = evmInterfaceSchema.safeParse({
+                artifact: {
+                    path: input.path,
+                    sha256: carrier.sha256,
+                    bytes: carrier.bytes.length,
+                    encoding: input.encoding,
+                },
+                bytecode: {
+                    ...reply.bytecode,
+                    digest_algorithm: "sha256",
+                    kind: "unknown",
+                    deployment_authenticity: "unknown",
+                    hardfork: "unknown",
+                },
+                evidence_kind: "inferred",
+                functions: projectEvmoleInterface(reply.raw).functions,
+                discovery_completeness: "unknown",
+                runtime_execution: "not-performed",
+                diagnostics: {
+                    stdout: execution.stdout.text,
+                    stderr: execution.stderr.text,
+                    truncated: capturedOutput.truncated,
+                },
+                limitations,
+            });
+            if (!validated.success)
+                throw new AnalysisOutputError(OPERATION, `Interface worker returned invalid bytecode-relative evidence: ${validated.error.issues[0]?.message ?? "schema mismatch"}`, { capturedOutput });
+            const report = validated.data;
+            result = ok(createAnalysisExecution(report, EVMOLE_PROVIDER_IDENTITY, {
+                rawResult: reply.raw,
+                subject: { path: input.path, format: "file", sha256: carrier.sha256 },
+                locations: [{ kind: "artifact-path", path: input.path }],
+                limitations,
+            }));
+        }
+        catch (cause) {
+            let fileFailure;
+            if (cause instanceof OwnedCommandFailure &&
+                cause.snapshot?.exitCode === EVM_FILE_SIZE_FAILURE_EXIT &&
+                cause.snapshot.signal === null &&
+                root !== undefined) {
+                try {
+                    const marker = await readStableArtifact(join(root.path, "resource.failure"), 1);
+                    if (!marker.bytes.equals(Buffer.from("F")))
+                        throw new Error("Private worker failure marker does not match the observed exit status.");
+                    fileFailure = { verified: true, failure: null };
+                }
+                catch (markerFailure) {
+                    fileFailure = {
+                        verified: false,
+                        failure: markerFailure instanceof Error
+                            ? markerFailure.message
+                            : String(markerFailure),
+                    };
+                }
+            }
+            result = err(options?.signal?.aborted &&
+                (cause === options.signal.reason ||
+                    (cause instanceof Error && cause.name === "AbortError"))
+                ? new AnalysisCancelledError(OPERATION, retainedOutput === undefined
+                    ? undefined
+                    : { capturedOutput: retainedOutput })
+                : evmInterfaceFailure(cause, phase, input.path, workerLimits, limiter, fileFailure));
+        }
+        if (root !== undefined) {
+            try {
+                await root.close();
+            }
+            catch (cause) {
+                return err(new ProviderCleanupError(EVMOLE_PROVIDER_IDENTITY.id, [root.path], {
+                    reason: cause instanceof Error ? cause.message : String(cause),
+                    previous_error: result.ok
+                        ? null
+                        : projectAnalysisError(result.error),
+                    ...(retainedOutput === undefined
+                        ? {}
+                        : { captured_output: { ...retainedOutput } }),
+                }, { operation: OPERATION }));
+            }
+        }
+        return result.ok && options?.signal?.aborted
+            ? err(new AnalysisCancelledError(OPERATION, retainedOutput === undefined
+                ? undefined
+                : { capturedOutput: retainedOutput }))
+            : result;
+    }
+}

package/dist/evm/EvmoleInterfaceWorker.js

@@ -0,0 +1,87 @@
+import { createHash } from "node:crypto";
+import { readFile, writeFile } from "node:fs/promises";
+import { z } from "zod";
+import { decodeEvmBytecodeCarrier, EvmCarrierFailure, } from "./EvmBytecodeCarrier.js";
+import { projectEvmoleInterface } from "./EvmoleInterfaceAdapter.js";
+import { EVM_INTERFACE_LIMITS, EVM_FILE_SIZE_FAILURE_EXIT, } from "./EvmoleRelease.js";
+const requestSchema = z.strictObject({
+    snapshot_path: z.string(),
+    reply_path: z.string(),
+    failure_marker_path: z.string(),
+    encoding: z.enum(["raw", "hex"]),
+});
+class UnsupportedContainer extends Error {
+}
+const main = async () => {
+    const requestPath = process.argv[2];
+    if (requestPath === undefined)
+        throw new Error("Owned worker request path missing.");
+    const request = requestSchema.parse(JSON.parse(await readFile(requestPath, "utf8")));
+    let reply;
+    try {
+        const bytes = decodeEvmBytecodeCarrier(await readFile(request.snapshot_path), request.encoding);
+        if (bytes[0] === 0xef && bytes[1] === 0x00)
+            throw new UnsupportedContainer("Container marker EF00 is outside the verified flat-bytecode interface profile.");
+        const modulePath = import.meta.resolve("evmole/no_tla");
+        const metadata = z
+            .object({ version: z.literal("0.9.3") })
+            .parse(JSON.parse(await readFile(new URL("../package.json", modulePath), "utf8")));
+        const engine = await import("evmole/no_tla");
+        engine.initSync({
+            module: await readFile(new URL(import.meta.resolve("evmole/evmole_bg.wasm"))),
+        });
+        const inferred = projectEvmoleInterface(engine.contractInfo(Buffer.from(bytes).toString("hex"), {
+            selectors: true,
+            arguments: true,
+            stateMutability: true,
+        }));
+        reply = {
+            ok: true,
+            version: metadata.version,
+            bytecode: {
+                sha256: createHash("sha256").update(bytes).digest("hex"),
+                bytes: bytes.length,
+                hex: Buffer.from(bytes).toString("hex"),
+            },
+            raw: inferred.raw,
+        };
+    }
+    catch (cause) {
+        reply = {
+            ok: false,
+            reason: cause instanceof EvmCarrierFailure
+                ? "format"
+                : cause instanceof UnsupportedContainer
+                    ? "unsupported"
+                    : "decoder",
+            message: cause instanceof Error ? cause.message : String(cause),
+        };
+    }
+    let encoded = JSON.stringify(reply);
+    if (Buffer.byteLength(encoded) > EVM_INTERFACE_LIMITS.outputBytes)
+        encoded = JSON.stringify({
+            ok: false,
+            reason: "output-limit",
+            message: "Complete interface evidence exceeds the 16 MiB reply budget.",
+        });
+    try {
+        await writeFile(request.reply_path, encoded, { flag: "wx", mode: 0o600 });
+    }
+    catch (cause) {
+        if (cause instanceof Error && "code" in cause && cause.code === "EFBIG") {
+            try {
+                await writeFile(request.failure_marker_path, "F", {
+                    flag: "wx",
+                    mode: 0o600,
+                });
+            }
+            catch (markerFailure) {
+                process.stderr.write(`File-size failure marker unavailable: ${markerFailure instanceof Error ? markerFailure.message : String(markerFailure)}\n`);
+            }
+            process.exitCode = EVM_FILE_SIZE_FAILURE_EXIT;
+        }
+        else
+            throw cause;
+    }
+};
+await main();

package/dist/evm/EvmoleRelease.js

@@ -0,0 +1,16 @@
+/** Unchanged locked npm/WASM profile; provenance is independent of chain deployment authenticity. */
+export const EVMOLE_PROVIDER_IDENTITY = {
+    id: "evmole-interface",
+    name: "REA EVM interface adapter",
+    version: "evmole@0.9.3",
+};
+/** Worker-reserved status for an observed EFBIG write without a complete reply. */
+export const EVM_FILE_SIZE_FAILURE_EXIT = 76;
+/** Complete offline inspection budgets; worker JavaScript heap is bounded separately. */
+export const EVM_INTERFACE_LIMITS = {
+    inputBytes: 4 * 1024 * 1024,
+    outputBytes: 16 * 1024 * 1024,
+    timeoutMs: 30_000,
+    diagnosticBytes: 1024 * 1024,
+    addressSpaceBytes: 3 * 1024 * 1024 * 1024,
+};

package/dist/firmware/FirmwareCommand.js

@@ -63,6 +63,7 @@ export const runFirmwareCommand = async (context) => {
         runId,
         cwd: context.cwd,
         hostEnvironment: context.environment,
+        signal,
         env: {
             TMPDIR: context.cwd,
             OMP_NUM_THREADS: "1",

package/dist/firmware/FirmwareFiles.js

@@ -102,7 +102,7 @@ export const readFirmwareReport = async (path, operation) => {
         if (bytes === undefined)
             throw new AnalysisOutputError(operation, `Report exceeded ${FIRMWARE_LIMITS.reportBytes} bytes`);
         try {
-            const value = JSON.parse(bytes.toString("utf8"));
+            const value = JSON.parse(new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes));
             return value;
         }
         catch (cause) {

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: "5.0.0", // x-release-please-version
+    version: "6.1.0", // x-release-please-version
     serverSdkVersion: "2.3.1",
     clientSdkVersion: "2.3.1",
     coreSdkVersion: "2.3.1",
-    skillVersion: "27",
+    skillVersion: "33",
 };

package/dist/ghidra/GhidraAnalysisProfile.js

@@ -27,6 +27,11 @@ export const resolveGhidraAnalysisProfile = (target, identity, installation, sig
             annotation_policy: "atomic-function-entry-metadata-v1",
             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",
+            process_launch: installation.platform === "win32"
+                ? "official-headless-script-v1"
+                : "inspected-jvm-launch-support-v1",
             ...(dos
                 ? {
                     load_image_evidence: dosCom

package/dist/ghidra/GhidraClient.js

@@ -1,6 +1,5 @@
 import { randomBytes, randomUUID } from "node:crypto";
 import { tmpdir } from "node:os";
-import { join } from "node:path";
 import { err, ok } from "../domain/result.js";
 import { silentLogger } from "../logger.js";
 import { PendingOperations } from "../process/PendingOperations.js";
@@ -8,7 +7,7 @@ import { PrivateRuntimeRoot } from "../process/PrivateRuntimeRoot.js";
 import { ProviderStartupDeadline } from "../process/ProviderDeadline.js";
 import { ProviderRunLineage } from "../process/ProviderRunLineage.js";
 import { ProviderProcessSupervisor, } from "../process/ProviderProcess.js";
-import { GHIDRA_STARTUP_TIMEOUT_MS } from "./GhidraDefaults.js";
+import { DEFAULT_GHIDRA_STARTUP_TIMEOUT_MS } from "../config/ghidraStartupTimeout.js";
 import { createGhidraDiagnostics } from "./GhidraDiagnostics.js";
 import { GhidraResponseBuffer } from "./GhidraResponseBuffer.js";
 import { GhidraResponseRouter } from "./GhidraResponseRouter.js";
@@ -18,6 +17,7 @@ import { isGhidraShutdownAcknowledgement, parseGhidraSessionInfo, } from "./Ghid
 import { createGhidraTargetSnapshot } from "./GhidraTargetSnapshot.js";
 import { readFile } from "node:fs/promises";
 import { connectGhidraSocket } from "./GhidraSocketConnection.js";
+import { createGhidraEndpoint, } from "./GhidraTransport.js";
 import { GhidraWire } from "./GhidraClientWire.js";
 import { completeGhidraStartupHandshake } from "./GhidraClientStartup.js";
 const SHUTDOWN_TIMEOUT_MS = 10_000;
@@ -32,6 +32,8 @@ export class GhidraClient {
     #launch;
     #process;
     #runtimeRoot;
+    #socketRoot;
+    #endpointPath;
     #snapshotPath;
     #targetAdmission;
     #token;
@@ -71,7 +73,7 @@ export class GhidraClient {
     constructor(options) {
         this.#options = {
             ...options,
-            startupTimeoutMs: options.startupTimeoutMs ?? GHIDRA_STARTUP_TIMEOUT_MS,
+            startupTimeoutMs: options.startupTimeoutMs ?? DEFAULT_GHIDRA_STARTUP_TIMEOUT_MS,
             platform: options.platform ?? process.platform,
             transport: options.transport ?? "unix-socket",
         };
@@ -90,8 +92,11 @@ export class GhidraClient {
     start(signal) {
         if (this.#closePromise !== undefined)
             return this.#closePromise.then(() => this.start(signal));
-        if (this.#startPromise !== undefined)
+        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;
+        }
         const controller = new AbortController();
         const onAbort = () => controller.abort(signal?.reason);
         if (signal?.aborted === true)
@@ -177,10 +182,16 @@ export class GhidraClient {
             return err(this.#failure("cancelled", "Ghidra startup was cancelled"));
         if (this.#socket !== undefined || this.#runtimeRoot !== undefined)
             return err(this.#failure("protocol", "Ghidra client is already started"));
+        this.#processSnapshot = undefined;
         const deadline = new ProviderStartupDeadline(this.#options.startupTimeoutMs, signal);
         try {
             return await this.#startWithin(deadline);
         }
+        catch (cause) {
+            if (cause instanceof GhidraSessionError)
+                return err(cause);
+            throw cause;
+        }
         finally {
             deadline.dispose();
         }
@@ -198,12 +209,18 @@ export class GhidraClient {
         }
         if (deadline.signal.aborted)
             return this.#startupInterrupted(deadline);
-        const endpoint = {
-            transport: this.#options.transport,
-            path: join(this.#runtimeRoot.path, this.#options.transport === "unix-socket"
-                ? "bridge.sock"
-                : "bridge-endpoint.json"),
-        };
+        let endpoint;
+        try {
+            const allocated = await createGhidraEndpoint(this.#runtimeRoot.path, this.#options.transport, this.#options.platform);
+            endpoint = allocated.endpoint;
+            this.#socketRoot = allocated.socketRoot;
+            this.#endpointPath = endpoint.path;
+        }
+        catch (cause) {
+            const failure = this.#failure("start", "Ghidra private endpoint allocation failed", cause);
+            await this.#cleanup();
+            return err(failure);
+        }
         try {
             const snapshot = await createGhidraTargetSnapshot(this.#options.targetPath, this.#runtimeRoot.path, this.#options.targetSha256, { signal: deadline.signal, platform: this.#options.platform });
             this.#snapshotPath = snapshot.path;
@@ -274,7 +291,7 @@ export class GhidraClient {
             deadline,
             failure: this.#failure,
             isClosed: () => this.#closing,
-            processExited: () => this.#processSnapshot?.exitCode !== undefined,
+            processExited: () => this.#process?.snapshot().exitCode !== undefined,
             startupTimeoutMs: this.#options.startupTimeoutMs,
             handlers: {
                 data: this.#onSocketData,
@@ -364,17 +381,26 @@ export class GhidraClient {
                         reason: stopped.reason,
                     });
                     this.#logger.warn({ reason: stopped.reason }, "Ghidra process cleanup failed closed");
-                    if (forceStop)
-                        forcedStopFailure = this.#failure("process", `Ghidra process cleanup after cancellation was incomplete: ${stopped.reason}`);
+                    // Keep the supervisor and private files available for a later close.
+                    // A still-live JVM can recreate files if its runtime is removed here.
+                    throw this.#failure("process", `Ghidra process cleanup was incomplete: ${stopped.reason}`);
                 }
             }
             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 {
-                await runtimeRoot?.close();
+                const removed = await Promise.allSettled([
+                    runtimeRoot?.close(),
+                    socketRoot?.close(),
+                ]);
+                const failed = removed.find((result) => result.status === "rejected");
+                if (failed?.status === "rejected")
+                    throw failed.reason;
             }
             catch (cause) {
                 if (forceStop)
@@ -383,6 +409,7 @@ export class GhidraClient {
                     throw cause;
             }
             this.#snapshotPath = undefined;
+            this.#endpointPath = undefined;
             this.#token = undefined;
             this.#runId = undefined;
             this.#responseBuffer.reset();
@@ -455,6 +482,12 @@ export class GhidraClient {
             ...(this.#runtimeRoot === undefined
                 ? {}
                 : { runtimeRoot: this.#runtimeRoot.path }),
+            ...(this.#socketRoot === undefined
+                ? {}
+                : { socketRoot: this.#socketRoot.path }),
+            ...(this.#endpointPath === undefined
+                ? {}
+                : { endpointPath: this.#endpointPath }),
             ...(this.#launch === undefined ? {} : { launch: this.#launch }),
             ...(snapshot === undefined ? {} : { snapshot }),
             ...(this.#token === undefined ? {} : { token: this.#token }),

package/dist/ghidra/GhidraDiagnostics.js

@@ -1,4 +1,3 @@
-import { join } from "node:path";
 /** Preserve actionable runtime coordinates after cleanup and redact bearer data. */
 export const createGhidraDiagnostics = (options) => {
     if (options.runtimeRoot === undefined &&
@@ -20,12 +19,13 @@ export const createGhidraDiagnostics = (options) => {
         ...(options.runId === undefined ? {} : { run_id: options.runId }),
         ...(options.runtimeRoot === undefined
             ? {}
-            : {
-                runtime_root: options.runtimeRoot,
-                endpoint_path: join(options.runtimeRoot, options.transport === "unix-socket"
-                    ? "bridge.sock"
-                    : "bridge-endpoint.json"),
-            }),
+            : { runtime_root: options.runtimeRoot }),
+        ...(options.socketRoot === undefined
+            ? {}
+            : { socket_root: options.socketRoot }),
+        ...(options.endpointPath === undefined
+            ? {}
+            : { endpoint_path: options.endpointPath }),
         ...(options.launch === undefined
             ? {}
             : {

package/dist/ghidra/GhidraFunctionValues.js

@@ -2,13 +2,14 @@ import { z } from "zod";
 import { nativeFunctionAnnotationsInputSchema, nativeFunctionAnnotationsSchema, } from "../domain/native/nativeFunctionAnnotations.js";
 import { nativeDataTypeSchema } from "../domain/native/nativeDataType.js";
 import { nativeInstructionSchema, nativeCallTargetsSchema, } from "../domain/native/nativeInstruction.js";
-import { AnalysisInputError, AnalysisOutputError, } from "../domain/analysisErrorCore.js";
+import { AnalysisOutputError, } from "../domain/analysisErrorCore.js";
 import { functionBodyEntryAgrees, functionInstructionWindowSchema, functionDossierSchema, } from "../domain/hopperValues.js";
 import { jsonObjectSchema, jsonValueSchema, } from "../domain/jsonValue.js";
 import { nativeApiBoundarySchema } from "../domain/native/nativeApiBoundary.js";
 import { nativeValueFlowSchema } from "../domain/native/nativeValueFlow.js";
 import { err, ok } from "../domain/result.js";
-import { ghidraIdentifierSchema, ghidraCanonicalAddressSchema, ghidraFunctionClassificationSchema as classification, ghidraFunctionBodySchema as ghidraFunctionBody, ghidraProcedureIdentitySchema as procedureIdentity, } from "./GhidraInventoryValues.js";
+import { analysisInputErrorFromIssues } from "../domain/inputIssueProjection.js";
+import { ghidraIdentifierSchema, ghidraInputAddressSchema, ghidraCanonicalAddressSchema, ghidraFunctionClassificationSchema as classification, ghidraFunctionBodySchema as ghidraFunctionBody, ghidraProcedureIdentitySchema as procedureIdentity, } from "./GhidraInventoryValues.js";
 /** Function analysis and annotation operations admitted by the Ghidra adapter. */
 export const GHIDRA_FUNCTION_OPERATIONS = [
     "annotate_native_function",
@@ -37,15 +38,15 @@ const inputSchemas = {
         .object({
         document,
         type: z.string().min(1).nullable().default(null),
-        address: ghidraCanonicalAddressSchema.nullable().default(null),
+        address: ghidraInputAddressSchema.nullable().default(null),
     })
         .strict()
         .refine((value) => (value.type === null) !== (value.address === null), "Supply exactly one of type or address"),
     inspect_native_instruction: z
-        .object({ document, address: ghidraCanonicalAddressSchema })
+        .object({ document, address: ghidraInputAddressSchema })
         .strict(),
     resolve_native_call_targets: z
-        .object({ document, address: ghidraCanonicalAddressSchema })
+        .object({ document, address: ghidraInputAddressSchema })
         .strict(),
     analyze_function: z.object({ procedure }).strict(),
     procedure_assembly: z.object(directProcedure).strict(),
@@ -60,14 +61,16 @@ const inputSchemas = {
         direction: z.enum(["incoming", "outgoing"]).default("outgoing"),
     })
         .strict(),
-    xrefs: z.object({ document, address: ghidraCanonicalAddressSchema }).strict(),
+    xrefs: z.object({ document, address: ghidraInputAddressSchema }).strict(),
 };
 /** Validate and default one function request before it crosses the socket. */
 export const parseGhidraFunctionInput = (operation, value) => {
     const parsed = inputSchemas[operation].safeParse(value);
     return parsed.success
         ? ok(jsonObjectSchema.parse(Object.fromEntries(Object.entries(parsed.data).filter(([, value]) => value !== undefined))))
-        : err(new AnalysisInputError(operation, { cause: parsed.error }));
+        : err(analysisInputErrorFromIssues(operation, parsed.error.issues, value, {
+            cause: parsed.error,
+        }));
 };
 const localVariable = z
     .object({