rea-agents 6.0.0 → 6.1.0

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({

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,25 +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)) {
@@ -267,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/GhidraProviderCapabilities.js

@@ -16,6 +16,7 @@ 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([
@@ -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.",