rea-agents 6.0.0 → 6.2.0

package/dist/ghidra/GhidraInstallation.js

@@ -1,9 +1,14 @@
+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" },
+    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
@@ -95,33 +97,28 @@ 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: 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,16 +139,43 @@ 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),
 ];
+/**
+ * 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,
@@ -172,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: "",
@@ -185,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/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,66 @@
+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. */
+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 = {
+        ...snapshotEnvironment(options.environment, options.platform),
+    };
+    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 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] ?? "") === "")
+            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

@@ -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";
@@ -7,6 +8,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 {
@@ -19,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))
@@ -58,7 +63,8 @@ export class GhidraHeadlessLauncher {
                     ? {}
                     : { dosMz: this.options.dosMz }),
             });
-            const command = ghidraHeadlessCommand({
+            const scriptCommand = ghidraHeadlessCommand({
+                environment: this.options.environment,
                 platform,
                 analyzeHeadlessPath: this.options.analyzeHeadlessPath,
                 arguments: headlessArguments,
@@ -66,25 +72,46 @@ export class GhidraHeadlessLauncher {
                     ? {}
                     : { comSpec: this.options.comSpec }),
             });
+            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
+                ? 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,
+                hostEnvironment: {},
                 ...(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)) {
@@ -124,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");
@@ -244,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,
@@ -267,22 +296,18 @@ const ghidraLaunchEnvironment = (paths, javaHome, platform, executable) => {
         XDG_DATA_HOME: paths.dataRoot,
     };
 };
-/** Encode provider-owned JVM paths for the parser that actually consumes them. */
+/** Encode provider-owned JVM paths for the platform launcher that consumes them. */
 export const ghidraHeadlessJavaOptions = (homeRoot, tempRoot, platform) => {
     const options = [`-Duser.home=${homeRoot}`, `-Djava.io.tmpdir=${tempRoot}`];
-    // analyzeHeadless.bat quotes VMARG_LIST, then launch.bat expands it again.
-    // Inner quotes fail in cmd.exe; unquoted paths with spaces split at the JVM.
-    // JDK_JAVA_OPTIONS is parsed by Java itself, outside that batch expansion.
-    return platform === "win32"
-        ? {
+    if (platform === "win32")
+        return {
             JDK_JAVA_OPTIONS: [...options, "-XX:-UsePerfData"]
                 .map(quoteWindowsBatchToken)
                 .join(" "),
             GHIDRA_HEADLESS_JAVA_OPTIONS: "",
-        }
-        : {
-            JDK_JAVA_OPTIONS: "",
-            GHIDRA_HEADLESS_JAVA_OPTIONS: options.join(" "),
         };
+    // POSIX launches the JVM directly, so these properties travel as separate
+    // argv items instead of the shell-split analyzeHeadless option list.
+    return { JDK_JAVA_OPTIONS: "", GHIDRA_HEADLESS_JAVA_OPTIONS: "" };
 };
 const isAborted = (signal) => signal?.aborted === true;

package/dist/ghidra/GhidraProvider.js

@@ -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

@@ -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.",
@@ -134,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,