rea-agents 4.0.0 → 4.1.0

package/dist/ghidra/GhidraProvider.js

@@ -1,7 +1,13 @@
+import { ghidraExtensionFailure } from "./extensions/GhidraExtensionFailures.js";
 import { fileURLToPath } from "node:url";
 import { createAnalysisExecution, } from "../application/AnalysisProvider.js";
-import { jsonObjectSchema } from "../domain/jsonValue.js";
-import { AnalysisCancelledError, AnalysisCapabilityUnavailableError, AnalysisInputError, AnalysisTimeoutError, ProviderAdapterError, } from "../domain/errors.js";
+import { createAnalysisProfile } from "../domain/analysisProfile.js";
+import { jsonObjectSchema, jsonValueSchema, } from "../domain/jsonValue.js";
+import { nativeLoadImageObservationSchema, nativeLoadImageSchema, } from "../domain/nativeLoadImage.js";
+import { attestGhidraDosLoadImage, attestGhidraDosComLoadImage, } from "./GhidraLoadImageValues.js";
+import { AnalysisCancelledError, AnalysisCapabilityUnavailableError, AnalysisInputError, AnalysisTimeoutError, } from "../domain/analysisErrorCore.js";
+import {} from "../domain/analysisErrorBase.js";
+import { ProviderAdapterError } from "../domain/providerAdapterError.js";
 import { err, ok } from "../domain/result.js";
 import { GhidraClient } from "./GhidraClient.js";
 import { GHIDRA_STARTUP_TIMEOUT_MS } from "./GhidraDefaults.js";
@@ -10,11 +16,12 @@ import { isGhidraInventoryOperation, parseGhidraInventoryInput, parseGhidraInven
 import { ghidraInstallationDiagnostics, inspectGhidraInstallation, } from "./GhidraInstallation.js";
 import { GhidraHeadlessLauncher } from "./GhidraLauncher.js";
 import { resolveGhidraAnalysisProfile } from "./GhidraAnalysisProfile.js";
-import { CAPABILITIES, WINDOWS_P0_CAPABILITIES, GHIDRA_PROVIDER_IDENTITY, GHIDRA_PROVIDER_TOOL_CONTRACTS, healthLimitations, windowsP0Limitations, limitationsFor, } from "./GhidraProviderCapabilities.js";
-import { WINDOWS_NATIVE_AUTHORITY_UNAVAILABLE_REASON, hasWindowsNativeAuthority, windowsNativeCapabilities, } from "../process/WindowsAuthority.js";
+import { ghidraExtensionSchema, resolveGhidraExtensions, validateGhidraExtensionProfile, ghidraExtensionLimitations, } from "./extensions/GhidraExtensions.js";
+import { CAPABILITIES, windowsP0Capabilities, GHIDRA_PROVIDER_IDENTITY, GHIDRA_PROVIDER_TOOL_CONTRACTS, healthLimitations, windowsP0Limitations, limitationsFor, } from "./GhidraProviderCapabilities.js";
+import { windowsNativeAuthorityUnavailableReason, hasWindowsNativeAuthority, windowsNativeCapabilities, } from "../process/WindowsAuthority.js";
 export { GHIDRA_PROVIDER_IDENTITY, GHIDRA_PROVIDER_TOOL_CONTRACTS };
 const SUPPORTED_ARCHITECTURES = new Set(["x86", "x86_64", "arm", "arm64"]);
-/** Ghidra candidate backed by an isolated read-only headless import. */
+/** Ghidra candidate backed by an isolated ephemeral headless import. */
 export class GhidraProvider {
     config;
     logger;
@@ -32,7 +39,7 @@ export class GhidraProvider {
     }
     capabilities() {
         return (this.installationHost?.platform ?? process.platform) === "win32"
-            ? WINDOWS_P0_CAPABILITIES
+            ? windowsP0Capabilities()
             : CAPABILITIES;
     }
     inspectAvailability() {
@@ -44,7 +51,7 @@ export class GhidraProvider {
             return {
                 status: "unavailable",
                 code: "unsupported_host",
-                reason: WINDOWS_NATIVE_AUTHORITY_UNAVAILABLE_REASON,
+                reason: windowsNativeAuthorityUnavailableReason(installation.platform),
                 diagnostics: {
                     ...diagnostics,
                     windows_security: jsonObjectSchema.parse(windowsNativeCapabilities(installation.platform)),
@@ -71,6 +78,9 @@ export class GhidraProvider {
             target_kind: target.kind,
             target_format: target.format,
             architecture: target.architecture ?? null,
+            available_architectures: target.kind === "executable"
+                ? [...target.availableArchitectures]
+                : null,
             executable_role: target.executableRole ?? null,
             managed: target.managed ?? null,
         };
@@ -83,6 +93,13 @@ export class GhidraProvider {
             };
         if (hostPlatform === "win32")
             return inspectWindowsP0TargetSupport(target, diagnostics);
+        if (target.format === "mach-o" && target.availableArchitectures.length > 1)
+            return {
+                status: "unsupported",
+                code: "architecture_unsupported",
+                reason: "Ghidra v1 cannot enforce the selected architecture when importing a universal Mach-O; analyze a thinned Mach-O slice instead.",
+                diagnostics,
+            };
         if (!SUPPORTED_ARCHITECTURES.has(target.architecture))
             return {
                 status: "unsupported",
@@ -97,8 +114,23 @@ export class GhidraProvider {
             diagnostics,
         };
     }
-    resolveAnalysisProfile(target, options) {
-        return resolveGhidraAnalysisProfile(target, GHIDRA_PROVIDER_IDENTITY, this.#inspectInstallation(), options?.signal);
+    async resolveAnalysisProfile(target, options) {
+        const installation = this.#inspectInstallation();
+        const resolved = await resolveGhidraAnalysisProfile(target, GHIDRA_PROVIDER_IDENTITY, installation, options?.signal);
+        if (!resolved.ok || resolved.value.profile === null)
+            return resolved;
+        const extensions = await resolveGhidraExtensions(this.config, target, installation.platform, options?.signal);
+        if (!extensions.ok)
+            return extensions;
+        if (extensions.value.length === 0)
+            return resolved;
+        return ok({
+            ...resolved.value,
+            profile: createAnalysisProfile(resolved.value.profile.provider, {
+                ...resolved.value.profile.parameters,
+                analysis_extensions: jsonValueSchema.parse(extensions.value),
+            }),
+        });
     }
     createClient(target, profile, context) {
         const installation = this.#inspectInstallation();
@@ -106,6 +138,24 @@ export class GhidraProvider {
         if (!prerequisites.ok)
             return unavailableClient(prerequisites.error);
         const committedProfile = prerequisites.value.profile;
+        const extensionProfile = ghidraExtensionSchema
+            .array()
+            .safeParse(committedProfile.parameters.analysis_extensions ?? []);
+        if (!extensionProfile.success ||
+            (this.config.ghidraNativeAotJar !== undefined &&
+                extensionProfile.data.length === 0))
+            return unavailableClient(new ProviderAdapterError("ghidra", "open_binary", {
+                diagnostics: {
+                    reason: "Resolve the configured Ghidra extensions into an analysis profile before opening the session.",
+                },
+            }));
+        const extensions = extensionProfile.data;
+        const invalidProfile = validateGhidraExtensionProfile(extensions, this.config, target, installation.platform);
+        if (invalidProfile !== null)
+            return unavailableClient(new ProviderAdapterError("ghidra", "open_binary", {
+                diagnostics: { reason: invalidProfile },
+            }));
+        let extensionFailure;
         const targetLimitations = target.format === "dos-mz"
             ? [
                 "DOS MZ uses 16-bit x86 real mode with the Ghidra load segment 0x1000. Returned addresses are linear byte coordinates; they do not identify a unique segment:offset alias.",
@@ -120,6 +170,7 @@ export class GhidraProvider {
                 ]
                 : [];
         const client = this.clientFactory({
+            platform: installation.platform,
             launcher: new GhidraHeadlessLauncher({
                 analyzeHeadlessPath: prerequisites.value.analyzeHeadlessPath,
                 ...(this.config.ghidraJavaHome === undefined
@@ -127,16 +178,20 @@ export class GhidraProvider {
                     : { javaHome: this.config.ghidraJavaHome }),
                 bridgeScriptPath: fileURLToPath(new URL("../../bridge/ghidra/ReaGhidraBridge.java", import.meta.url)),
                 ...(target.format === "dos-mz" ? { dosMz: true } : {}),
+                ...(target.format === "dos-com" ? { dosCom: true } : {}),
                 platform: installation.platform,
+                ...(extensions.length === 0 ? {} : { analysisExtensions: extensions }),
             }),
-            targetPath: target.path,
+            targetPath: installation.platform === "win32"
+                ? (target.sourcePath ?? target.path)
+                : target.path,
             targetSha256: target.sha256,
             transport: installation.platform === "win32"
                 ? "authenticated-loopback-tcp"
                 : "unix-socket",
             providerVersion: prerequisites.value.providerVersion,
             profileDigest: committedProfile.digest,
-            ...(target.format === "dos-mz"
+            ...(["dos-mz", "dos-com"].includes(target.format)
                 ? {
                     expectedLanguageId: "x86:LE:16:Real Mode",
                     expectedCompilerSpecId: "default",
@@ -145,8 +200,17 @@ export class GhidraProvider {
             ...(context === undefined ? {} : { runId: context.runId }),
             logger: this.logger.child({ layer: "ghidra-bridge" }),
         });
+        const checkExtensions = async (operation, info) => {
+            extensionFailure = ghidraExtensionFailure(extensions, info.analysis_extensions ?? [], operation);
+            if (extensionFailure === undefined)
+                return undefined;
+            await client.close();
+            return extensionFailure;
+        };
         return {
             execute: async (operation, parameters, options) => {
+                if (extensionFailure !== undefined)
+                    return err(extensionFailure);
                 if (operation !== "health" &&
                     !isGhidraInventoryOperation(operation) &&
                     !isGhidraFunctionOperation(operation))
@@ -155,12 +219,16 @@ export class GhidraProvider {
                     const started = await client.start(options?.signal);
                     if (!started.ok)
                         return err(projectSessionError(operation, started.error));
+                    const failed = await checkExtensions(operation, started.value);
+                    if (failed !== undefined)
+                        return err(failed);
                     return ok(createAnalysisExecution(started.value, committedProfile.provider, {
                         analysisProfile: committedProfile,
                         limitations: [
                             ...healthLimitations,
                             ...providerLimitations,
                             ...targetLimitations,
+                            ...ghidraExtensionLimitations(extensions),
                         ],
                     }));
                 }
@@ -169,6 +237,14 @@ export class GhidraProvider {
                     : parseGhidraInventoryInput(operation, parameters);
                 if (!input.ok)
                     return input;
+                if (extensions.length > 0) {
+                    const started = await client.start(options?.signal);
+                    if (!started.ok)
+                        return err(projectSessionError(operation, started.error));
+                    const failed = await checkExtensions(operation, started.value);
+                    if (failed !== undefined)
+                        return err(failed);
+                }
                 const called = await client.callTool(operation, input.value, options?.signal === undefined ? {} : { signal: options.signal });
                 if (!called.ok)
                     return err(projectSessionError(operation, called.error));
@@ -177,13 +253,47 @@ export class GhidraProvider {
                     : parseGhidraInventoryResult(operation, called.value);
                 if (!result.ok)
                     return result;
-                return ok(createAnalysisExecution(result.value, committedProfile.provider, {
+                let normalized = result.value;
+                if (operation === "inspect_native_load_image") {
+                    const observations = nativeLoadImageObservationSchema.parse(result.value);
+                    if (target.format !== "dos-mz" && target.format !== "dos-com") {
+                        normalized = jsonValueSchema.parse(nativeLoadImageSchema.parse({
+                            status: "unsupported",
+                            reason: "Independent load-image verification currently supports DOS MZ and explicit DOS COM targets only.",
+                            observations,
+                            limitations: [
+                                "Other formats expose measured mappings and source identities; no format-specific verification was performed.",
+                            ],
+                        }));
+                    }
+                    else {
+                        if (client.readTargetSnapshot === undefined)
+                            return err(new ProviderAdapterError("ghidra", operation, {
+                                diagnostics: {
+                                    reason: "The Ghidra client does not expose its immutable target snapshot for independent load-image verification.",
+                                },
+                            }));
+                        const snapshot = await client.readTargetSnapshot();
+                        if (!snapshot.ok)
+                            return err(projectSessionError(operation, snapshot.error));
+                        const attested = (target.format === "dos-com"
+                            ? attestGhidraDosComLoadImage
+                            : attestGhidraDosLoadImage)(snapshot.value, target.sha256 ?? "", observations);
+                        if (!attested.ok)
+                            return err(new ProviderAdapterError("ghidra", operation, {
+                                diagnostics: { reason: attested.error },
+                            }));
+                        normalized = jsonValueSchema.parse(attested.value);
+                    }
+                }
+                return ok(createAnalysisExecution(normalized, committedProfile.provider, {
                     rawResult: called.value,
                     analysisProfile: committedProfile,
                     limitations: [
                         ...limitationsFor(operation),
                         ...providerLimitations,
                         ...targetLimitations,
+                        ...ghidraExtensionLimitations(extensions),
                     ],
                 }));
             },
@@ -263,7 +373,7 @@ const ghidraClientPrerequisites = (target, profile, installation) => {
         }));
     if (installation.platform === "win32" &&
         !hasWindowsNativeAuthority(installation.platform))
-        return err(new AnalysisCapabilityUnavailableError("ghidra", "health", WINDOWS_NATIVE_AUTHORITY_UNAVAILABLE_REASON));
+        return err(new AnalysisCapabilityUnavailableError("ghidra", "health", windowsNativeAuthorityUnavailableReason(installation.platform)));
     if (profile === undefined || profile.provider.id !== "ghidra")
         return err(new ProviderAdapterError("ghidra", "health"));
     return ok({
@@ -277,6 +387,12 @@ const unavailableClient = (failure) => ({
     close: () => Promise.resolve(),
 });
 const projectSessionError = (operation, failure) => {
+    if (operation === "annotate_native_function" &&
+        failure.kind === "remote" &&
+        failure.remoteCode === "invalid_function_name")
+        return new AnalysisInputError(operation, { cause: failure }, [
+            { path: ["name"], reason: "invalid_value", message: failure.message },
+        ]);
     if (failure.kind === "cancelled")
         return new AnalysisCancelledError(operation);
     if (failure.kind === "timeout" || failure.kind === "analysis_timeout")

package/dist/ghidra/GhidraProviderCapabilities.js

@@ -1,4 +1,4 @@
-import { WINDOWS_NATIVE_AUTHORITY_UNAVAILABLE_REASON } from "../process/WindowsAuthority.js";
+import { hasWindowsNativeAuthority, windowsNativeAuthorityUnavailableReason, } from "../process/WindowsAuthority.js";
 import { GENERATED_MCP_TOOL_CATALOG } from "../generatedMcpToolCatalog.js";
 import { GHIDRA_FUNCTION_OPERATIONS } from "./GhidraFunctionValues.js";
 import { GHIDRA_INVENTORY_OPERATIONS } from "./GhidraInventoryValues.js";
@@ -9,7 +9,7 @@ export const GHIDRA_PROVIDER_IDENTITY = Object.freeze({
     version: null,
 });
 const providerContractByName = new Map(GENERATED_MCP_TOOL_CATALOG.filter(({ kind }) => kind === "official-proxy" || kind === "enhanced").map((contract) => [contract.name, contract]));
-/** Provider-neutral read-only contracts implemented by the Ghidra adapter. */
+/** Provider-neutral contracts implemented by the Ghidra adapter. */
 export const GHIDRA_PROVIDER_TOOL_CONTRACTS = Object.freeze([...GHIDRA_INVENTORY_OPERATIONS, ...GHIDRA_FUNCTION_OPERATIONS].map((operation) => {
     const contract = providerContractByName.get(operation);
     if (contract === undefined)
@@ -19,13 +19,13 @@ export const GHIDRA_PROVIDER_TOOL_CONTRACTS = Object.freeze([...GHIDRA_INVENTORY
 /** Health limitations shared by every Ghidra-backed capability. */
 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, read-only to REA, and deleted on close.",
+    "The imported Program and temporary project are ephemeral and deleted on close. Annotation operations edit session database metadata; original executable bytes are never written.",
 ]);
 /** Additional limitations applied to the experimental Windows x64 P0 boundary. */
 export const windowsP0Limitations = Object.freeze([
     "Windows Ghidra P0 accepts approved native x86-64 PE applications only; DLL, managed, hostile, sensitive, and mutable-path targets are unsupported.",
     "The Windows bridge uses authenticated IPv4 loopback because Node path-based IPC does not expose Java AF_UNIX sockets; the endpoint file contains no bearer token.",
-    "Windows P0 is not admitted until a native authority proves Job Object ownership, private DACL enforcement, and reparse-safe path admission; bounded taskkill cleanup and chmod(0700) do not prove those controls.",
+    "Windows sessions require the matching packaged Windows x64 native addon, local NTFS targets and runtimes, and Windows 10 or later. Native handles enforce path admission, private DACLs, and Job Object ownership automatically.",
 ]);
 /** Limitation text for one admitted operation, including the common base. */
 export const limitationsFor = (operation) => {
@@ -34,6 +34,27 @@ export const limitationsFor = (operation) => {
         "Default-space addresses use lowercase 0x-prefixed hexadecimal; other address spaces use <percent-encoded-space>:0x<hex>.",
     ];
     switch (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.",
+                "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":
+            return [
+                ...common,
+                "Independent verification supports DOS MZ and explicitly selected COM, including measured COM entry context. Measured source mappings use inclusive end addresses and complete region digests; no target execution or project mutation occurs.",
+            ];
+        case "read_bytes":
+            return [
+                ...common,
+                "Bytes reflect Ghidra's initialized memory, including loader fixups. Reads stop at an unmapped or uninitialized byte and report completeness explicitly.",
+            ];
+        case "address_to_file_offset":
+            return [
+                ...common,
+                "Offsets come from Ghidra source-byte mappings, not virtual-address arithmetic. Uninitialized memory, missing mappings and ambiguous mappings fail explicitly.",
+            ];
         case "list_documents":
             return [
                 ...common,
@@ -121,7 +142,7 @@ export const CAPABILITIES = Object.freeze(GHIDRA_PROVIDER_TOOL_CONTRACTS.map((co
         available: true,
         reason: null,
         effects: Object.freeze({
-            mutatesArtifact: false,
+            mutatesArtifact: operation === "annotate_native_function",
             launchesProcess: true,
             mayShowUi: false,
             mayAccessNetwork: false,
@@ -133,13 +154,29 @@ export const CAPABILITIES = Object.freeze(GHIDRA_PROVIDER_TOOL_CONTRACTS.map((co
     });
 }));
 /** Capabilities advertised for the experimental Windows x64 P0 boundary. */
-export const WINDOWS_P0_CAPABILITIES = Object.freeze(CAPABILITIES.map((capability) => Object.freeze({
-    ...capability,
-    available: false,
-    reason: WINDOWS_NATIVE_AUTHORITY_UNAVAILABLE_REASON,
-    availabilityCode: "unsupported_host",
-    limitations: Object.freeze([
-        ...capability.limitations,
-        ...windowsP0Limitations,
-    ]),
-})));
+export const windowsP0Capabilities = () => {
+    const available = hasWindowsNativeAuthority("win32");
+    return Object.freeze(CAPABILITIES.map((capability) => {
+        const limitations = Object.freeze([
+            ...capability.limitations,
+            ...windowsP0Limitations,
+        ]);
+        if (capability.effects.mutatesArtifact)
+            return Object.freeze({
+                ...capability,
+                available: false,
+                reason: "Windows Ghidra P0 does not admit database mutation.",
+                availabilityCode: "unsupported_host",
+                limitations,
+            });
+        return available
+            ? Object.freeze({ ...capability, limitations })
+            : Object.freeze({
+                ...capability,
+                available: false,
+                reason: windowsNativeAuthorityUnavailableReason("win32"),
+                availabilityCode: "unsupported_host",
+                limitations,
+            });
+    }));
+};

package/dist/ghidra/GhidraRequestQueue.js

@@ -88,9 +88,9 @@ export class GhidraRequestQueue {
             executionSettled = true;
             entry.resolve(result);
         })
-            .catch(() => {
+            .catch((cause) => {
             executionSettled = true;
-            entry.resolve(err(this.failure("protocol", "Ghidra serial request execution rejected unexpectedly")));
+            entry.resolve(err(this.failure("protocol", "Ghidra serial request execution rejected unexpectedly", cause)));
         })
             .finally(() => {
             if (entry.signal !== undefined && onAbort !== undefined)

package/dist/ghidra/GhidraSessionError.js

@@ -18,7 +18,7 @@ const createGhidraSessionError = (failure) => new GhidraSessionError(failure.kin
     ? failure.diagnostics
     : {
         ...failure.diagnostics,
-        remote_code: failure.remoteCode,
+        remote_code: failure.redact(failure.remoteCode),
         remote_message: failure.message,
     }, {
     ...(failure.cause === undefined ? {} : { cause: failure.cause }),
@@ -30,10 +30,37 @@ const createGhidraSessionError = (failure) => new GhidraSessionError(failure.kin
         : { remoteCode: failure.remoteCode }),
 });
 /** Bind session-failure construction to a live, token-redacted diagnostic view. */
-export const bindGhidraSessionFailure = (diagnostics) => (kind, message, cause, options = {}) => createGhidraSessionError({
+export const bindGhidraSessionFailure = (diagnostics, redact = (value) => value) => (kind, message, cause, options = {}) => createGhidraSessionError({
     kind,
-    message,
-    diagnostics: diagnostics(),
+    message: redact(message),
+    diagnostics: {
+        ...diagnostics(),
+        ...(cause === undefined
+            ? {}
+            : { failure_cause: describeCause(cause, redact) }),
+    },
+    redact,
     ...(cause === undefined ? {} : { cause }),
     ...options,
 });
+const describeCause = (cause, redact) => {
+    if (cause instanceof Error) {
+        const code = "code" in cause ? cause.code : undefined;
+        return {
+            name: redact(cause.name),
+            message: redact(cause.message),
+            ...(typeof code === "string"
+                ? { code: redact(code) }
+                : typeof code === "number" && Number.isFinite(code)
+                    ? { code }
+                    : {}),
+        };
+    }
+    if (typeof cause === "string")
+        return { type: "string", message: redact(cause) };
+    if (cause === null || typeof cause === "boolean")
+        return { type: cause === null ? "null" : "boolean", value: cause };
+    if (typeof cause === "number" && Number.isFinite(cause))
+        return { type: "number", value: cause };
+    return { type: typeof cause };
+};

package/dist/ghidra/GhidraSessionValues.js

@@ -2,6 +2,7 @@ import { z } from "zod";
 import { err, ok } from "../domain/result.js";
 import { GHIDRA_INVENTORY_OPERATIONS } from "./GhidraInventoryValues.js";
 import { GHIDRA_FUNCTION_OPERATIONS } from "./GhidraFunctionValues.js";
+import { ghidraExtensionResultSchema } from "./extensions/GhidraExtensions.js";
 /** Exact methods proved by the bridge handshake after auto-analysis. */
 export const GHIDRA_SESSION_CAPABILITIES = [
     "ping",
@@ -21,12 +22,11 @@ const sessionInfoSchema = z
         version: z.string().min(1),
     })
         .strict(),
-    read_only: z.literal(true),
+    read_only: z.boolean(),
     analysis_complete: z.boolean(),
     analysis_timed_out: z.boolean(),
-    capabilities: z
-        .array(capabilitySchema)
-        .length(GHIDRA_SESSION_CAPABILITIES.length),
+    analysis_extensions: z.array(ghidraExtensionResultSchema).optional(),
+    capabilities: z.array(capabilitySchema),
     target: z
         .object({
         name: z.string().min(1),
@@ -42,8 +42,12 @@ const sessionInfoSchema = z
 /** Require exact run, provider, and profile identity from the Java bridge. */
 export const parseGhidraSessionInfo = (value, expected) => {
     const parsed = sessionInfoSchema.safeParse(value);
+    const readOnly = expected.expectedReadOnly ?? false;
+    const expectedCapabilities = GHIDRA_SESSION_CAPABILITIES.filter((capability) => !readOnly || capability !== "annotate_native_function");
     if (!parsed.success ||
         parsed.data.run_id !== expected.runId ||
+        parsed.data.read_only !== readOnly ||
+        parsed.data.capabilities.length !== expectedCapabilities.length ||
         parsed.data.provider.version !== expected.providerVersion ||
         parsed.data.profile_digest !== expected.profileDigest ||
         parsed.data.target.sha256 !== expected.targetSha256 ||
@@ -52,9 +56,8 @@ export const parseGhidraSessionInfo = (value, expected) => {
         (expected.expectedCompilerSpecId !== undefined &&
             parsed.data.target.compiler_spec_id !==
                 expected.expectedCompilerSpecId) ||
-        new Set(parsed.data.capabilities).size !==
-            GHIDRA_SESSION_CAPABILITIES.length ||
-        GHIDRA_SESSION_CAPABILITIES.some((capability) => !parsed.data.capabilities.includes(capability)) ||
+        new Set(parsed.data.capabilities).size !== expectedCapabilities.length ||
+        expectedCapabilities.some((capability) => !parsed.data.capabilities.includes(capability)) ||
         parsed.data.analysis_complete === parsed.data.analysis_timed_out)
         return err(new Error("Ghidra bridge handshake identity is invalid"));
     return ok(parsed.data);

package/dist/ghidra/GhidraTargetSnapshot.js

@@ -2,12 +2,23 @@ import { createHash } from "node:crypto";
 import { constants, createReadStream } from "node:fs";
 import { chmod, copyFile, rm } from "node:fs/promises";
 import { extname, join } from "node:path";
+import { windowsPrivateRuntime } from "../windows/WindowsPrivateRuntime.js";
 /** Copy one target and require its bytes to match the parsed target identity. */
-export const createGhidraTargetSnapshot = async (sourcePath, runtimeRoot, expectedSha256) => {
+export const createGhidraTargetSnapshot = async (sourcePath, runtimeRoot, expectedSha256, options = {}) => {
     if (!/^[a-f0-9]{64}$/u.test(expectedSha256))
         throw new TypeError("Ghidra target SHA-256 commitment is invalid");
     const suffix = safeExtension(sourcePath);
     const snapshotPath = join(runtimeRoot, `target-${expectedSha256.slice(0, 12)}${suffix}`);
+    if ((options.platform ?? process.platform) === "win32") {
+        const observed = await windowsPrivateRuntime(runtimeRoot).snapshot(sourcePath, `target-${expectedSha256.slice(0, 12)}${suffix}`, options.signal);
+        if (observed.sha256 !== expectedSha256)
+            throw new Error(`Ghidra target snapshot digest mismatch: expected ${expectedSha256}, observed ${observed.sha256}`);
+        return {
+            path: snapshotPath,
+            sha256: observed.sha256,
+            admission: { source: observed.source, snapshot: observed.snapshot },
+        };
+    }
     try {
         await copyFile(sourcePath, snapshotPath, constants.COPYFILE_EXCL);
         await chmod(snapshotPath, 0o600);
@@ -20,7 +31,10 @@ export const createGhidraTargetSnapshot = async (sourcePath, runtimeRoot, expect
         return { path: snapshotPath, sha256: observedSha256 };
     }
     catch (cause) {
-        await rm(snapshotPath, { force: true }).catch(() => undefined);
+        await rm(snapshotPath, { force: true }).catch((cause) => {
+            // best-effort cleanup: snapshot removal must not mask the copy failure.
+            void cause;
+        });
         throw cause;
     }
 };

package/dist/ghidra/GhidraTransport.js

@@ -1,4 +1,5 @@
 import { access, open } from "node:fs/promises";
+import { readWindowsPrivateRuntimeFile } from "../windows/WindowsPrivateRuntime.js";
 import { err, ok } from "../domain/result.js";
 import { GhidraSessionError } from "./GhidraSessionError.js";
 /** Observe a ready endpoint, returning null while its bridge is not listening. */
@@ -14,6 +15,16 @@ export const observeGhidraEndpoint = async (endpoint) => {
                 : err(endpointFailure(endpoint, "Ghidra socket observation failed", cause));
         }
     }
+    if (process.platform === "win32") {
+        try {
+            return parseTcpEndpoint(endpoint, readWindowsPrivateRuntimeFile(endpoint.path));
+        }
+        catch (cause) {
+            return isMissing(cause) || isWindowsEndpointWriterBusy(cause)
+                ? ok(null)
+                : err(endpointFailure(endpoint, "Ghidra endpoint observation failed", cause));
+        }
+    }
     let handle;
     try {
         handle = await open(endpoint.path, "r");
@@ -66,3 +77,4 @@ const endpointFailure = (endpoint, message, cause) => new GhidraSessionError("st
     ...(cause instanceof Error ? { error: cause.message } : {}),
 }, cause instanceof Error ? { cause } : undefined);
 const isMissing = (cause) => cause instanceof Error && "code" in cause && cause.code === "ENOENT";
+const isWindowsEndpointWriterBusy = (cause) => cause instanceof Error && "win32Code" in cause && cause.win32Code === 32;

package/dist/ghidra/extensions/GhidraExtensionFailures.js

@@ -0,0 +1,20 @@
+import { AnalysisCapabilityUnavailableError } from "../../domain/analysisErrorCore.js";
+import { ProviderAdapterError } from "../../domain/providerAdapterError.js";
+import { jsonValueSchema } from "../../domain/jsonValue.js";
+import { validateGhidraExtensionResults, } from "./GhidraExtensions.js";
+/** Preserve unsupported recovery separately from malformed or failed producers. */
+export const ghidraExtensionFailure = (extensions, results, operation) => {
+    const reports = results;
+    const invalid = validateGhidraExtensionResults(extensions, reports);
+    const failed = reports.find((value) => value.status === "unsupported" || value.status === "failed");
+    if (invalid === null && failed === undefined)
+        return undefined;
+    return invalid === null && failed?.status === "unsupported"
+        ? new AnalysisCapabilityUnavailableError("ghidra", operation, `${failed.id}: ${failed.reason}. Omit REA_GHIDRA_NATIVEAOT_JAR to continue ordinary native analysis.`)
+        : new ProviderAdapterError("ghidra", operation, {
+            diagnostics: {
+                reason: invalid ?? failed?.reason ?? "Ghidra extension failed",
+                analysis_extensions: jsonValueSchema.parse(reports),
+            },
+        });
+};