rea-agents 6.5.0 → 6.7.0

package/dist/ghidra/GhidraProviderClient.js

@@ -1,5 +1,7 @@
 import { analysisErrorWithCleanupFailure } from "../domain/analysisErrorCleanup.js";
+import { artifactFilePrimaryFailure } from "../artifacts/ArtifactFileOperation.js";
 import { fileURLToPath } from "node:url";
+import { GHIDRA_BRIDGE_SOURCES } from "./GhidraBridgeSources.js";
 import { createAnalysisExecution, } from "../application/AnalysisProvider.js";
 import { ghidraSeedCommitmentSchema, ghidraSeedFailure, ghidraSeedLimitations, } from "./GhidraAnalysisSeeds.js";
 import { ghidraPinnedLanguage, ghidraProfileDisabledAnalyzers, ghidraProfileLanguageOverride, sameGhidraDisabledAnalyzers, sameGhidraLanguageOverride, } from "./GhidraAnalysisProfile.js";
@@ -17,171 +19,24 @@ import { isGhidraPspTarget, GHIDRA_PSP_LIMITATIONS, } from "./GhidraPspProfile.j
 import { ghidraPspExtensionSchema } from "./GhidraPspExtension.js";
 import { GHIDRA_MIPS_SOFT_FLOAT_STORAGE, ghidraMipsSoftFloatFailure, ghidraMipsRelocatableLimitations, ghidraMipsSharedLimitations, ghidraMipsSoftFloatLimitations, isGhidraMipsSoftFloatTarget, } from "./GhidraMipsProfile.js";
 import { ghidraRiscvLimitations } from "./GhidraRiscvProfile.js";
-import { ghidraPeCodeViewLimitations } from "./GhidraPeProfile.js";
-import { unverifiedGhidraBuildLimitation } from "./GhidraInstallationPolicy.js";
+import { ghidraPePdbLimitations } from "./GhidraPeProfile.js";
+import { unverifiedGhidraBuildLimitation } from "./GhidraReleasePolicy.js";
 import { GhidraHeadlessLauncher } from "./GhidraLauncher.js";
 import { attestGhidraNativeLoadImage } from "./GhidraLoadImageAttest.js";
-import { NATIVE_AOT_MAX_REPORT_BYTES, NATIVE_AOT_MAX_SOURCE_BYTES, nativeAotSnapshotOverCapacity, parseNativeAotPe, } from "../domain/native/nativeAotPe.js";
-import { ABORTED, waitForAbortable } from "../process/AbortablePromise.js";
-import { nativeLoadImageObservationSchema } from "../domain/native/nativeLoadImage.js";
+import { GhidraNativeAotSnapshotOwner } from "./GhidraNativeAotSnapshotOwner.js";
 import { GHIDRA_PROVIDER_IDENTITY, healthLimitations, windowsP0Limitations, limitationsFor, } from "./GhidraProviderCapabilities.js";
-import { ghidraPdbLimitations, } from "./GhidraSessionValues.js";
+import { GHIDRA_STARTUP_DEADLINE_ELAPSED, } from "./GhidraSessionError.js";
 import { ghidraExtensionFailure } from "./extensions/GhidraExtensionFailures.js";
 import { ghidraExtensionSchema, validateGhidraExtensionProfile, ghidraExtensionLimitations, } from "./extensions/GhidraExtensions.js";
 import { inspectWindowsNativeReadiness } from "../process/WindowsAuthority.js";
 import { ghidraRawBinaryLanguage } from "./GhidraRawBinaryLanguage.js";
-/** Own one session's captured PE snapshot and immutable NativeAOT derivation. */
-const createNativeAotSnapshotOwner = (input) => {
-    const { client, target, startupTimeoutMs } = input;
-    const controller = new AbortController();
-    let identity;
-    let result;
-    let pending;
-    let closed = false;
-    let identityConflict = false;
-    let identityConflictObservation;
-    const identityError = (operation, reason, observedBase, observations) => new ProviderAdapterError("ghidra", operation, {
-        diagnostics: {
-            reason,
-            artifact_sha256: target.sha256,
-            bound_image_base: identity === undefined
-                ? null
-                : `0x${identity.slice(target.sha256.length + 1)}`,
-            observed_image_base: observedBase,
-            measured_observation: observations,
-            conflicting_image_base: identityConflictObservation?.imageBase ?? null,
-            conflicting_observation: identityConflictObservation?.observations ?? null,
-        },
-    });
-    const identityConflictFailure = (operation, observedBase, observations) => {
-        return err(identityError(operation, "The Ghidra session reported conflicting loaded image bases; reopen the analysis session to establish a new identity.", observedBase, observations));
-    };
-    const derive = async (imageBase, operation, callerSignal, observations) => {
-        if (callerSignal?.aborted || closed)
-            return err(new AnalysisCancelledError(operation));
-        if (identityConflict)
-            return identityConflictFailure(operation, imageBase, observations);
-        if (controller.signal.aborted)
-            return err(new AnalysisCancelledError(operation));
-        let normalizedBase;
-        try {
-            normalizedBase = BigInt(imageBase).toString(16);
-        }
-        catch (cause) {
-            return err(new ProviderAdapterError("ghidra", operation, {
-                diagnostics: {
-                    reason: "Ghidra returned an invalid loaded image base for NativeAOT identity binding.",
-                    artifact_sha256: target.sha256,
-                    observed_image_base: imageBase,
-                    measured_observation: observations,
-                },
-                cause,
-            }));
-        }
-        const key = `${target.sha256}:${normalizedBase}`;
-        if (identity !== undefined && identity !== key) {
-            identityConflict = true;
-            identityConflictObservation = { imageBase, observations };
-            result = undefined;
-            controller.abort();
-            return err(identityError(operation, "The Ghidra session reported a different loaded image base after NativeAOT metadata was bound to its captured snapshot; reopen the analysis session to establish a new identity.", imageBase, observations));
-        }
-        identity ??= key;
-        if (result !== undefined) {
-            const settled = await waitForAbortable(Promise.resolve(ok(result)), callerSignal);
-            if (closed)
-                return err(new AnalysisCancelledError(operation));
-            if (identityConflict)
-                return identityConflictFailure(operation, imageBase, observations);
-            if (controller.signal.aborted)
-                return err(new AnalysisCancelledError(operation));
-            return settled === ABORTED
-                ? err(new AnalysisCancelledError(operation))
-                : settled;
-        }
-        if (pending !== undefined && pending.identity !== key)
-            return err(identityError(operation, "A NativeAOT snapshot derivation is already bound to a different loaded image base.", imageBase, observations));
-        if (pending === undefined) {
-            const promise = (async () => {
-                try {
-                    if (client.readTargetSnapshot === undefined)
-                        return err(new ProviderAdapterError("ghidra", operation, {
-                            diagnostics: {
-                                reason: "The Ghidra client does not expose its immutable target snapshot for NativeAOT metadata inspection.",
-                            },
-                        }));
-                    const snapshot = await client.readTargetSnapshot(NATIVE_AOT_MAX_SOURCE_BYTES, controller.signal);
-                    if (!snapshot.ok)
-                        return err(projectSessionError(operation, snapshot.error, startupTimeoutMs));
-                    if (closed)
-                        return err(new AnalysisCancelledError(operation));
-                    if (identityConflict)
-                        return identityConflictFailure(operation, imageBase, observations);
-                    if (controller.signal.aborted)
-                        return err(new AnalysisCancelledError(operation));
-                    const parsed = snapshot.value.kind === "over-capacity"
-                        ? {
-                            summary: nativeAotSnapshotOverCapacity(target.sha256, snapshot.value.sourceBytesAtLeast, NATIVE_AOT_MAX_REPORT_BYTES),
-                            readTypeDetail: () => undefined,
-                        }
-                        : parseNativeAotPe(snapshot.value.bytes, target.sha256, NATIVE_AOT_MAX_REPORT_BYTES, imageBase);
-                    if (closed)
-                        return err(new AnalysisCancelledError(operation));
-                    if (identityConflict)
-                        return identityConflictFailure(operation, imageBase, observations);
-                    if (controller.signal.aborted)
-                        return err(new AnalysisCancelledError(operation));
-                    return ok(parsed);
-                }
-                catch (cause) {
-                    return err(new ProviderAdapterError("ghidra", operation, {
-                        diagnostics: {
-                            reason: cause instanceof Error
-                                ? cause.message
-                                : "NativeAOT metadata could not be derived from the captured target snapshot.",
-                        },
-                        cause,
-                    }));
-                }
-            })();
-            const current = { identity: key, promise };
-            pending = current;
-            void promise.then((settled) => {
-                if (pending !== current)
-                    return;
-                pending = undefined;
-                if (settled.ok && !closed && !identityConflict)
-                    result = settled.value;
-            });
-        }
-        const settled = await waitForAbortable(pending.promise, callerSignal);
-        if (closed)
-            return err(new AnalysisCancelledError(operation));
-        if (identityConflict)
-            return identityConflictFailure(operation, imageBase, observations);
-        if (controller.signal.aborted)
-            return err(new AnalysisCancelledError(operation));
-        return settled === ABORTED
-            ? err(new AnalysisCancelledError(operation))
-            : settled;
-    };
-    return {
-        derive,
-        readTypeDetail: (address) => result?.readTypeDetail(address, NATIVE_AOT_MAX_REPORT_BYTES),
-        close: () => {
-            closed = true;
-            controller.abort();
-            result = undefined;
-            pending = undefined;
-        },
-    };
-};
 /** Build one AnalysisClient for an admitted Ghidra target and profile. */
 export const createGhidraProviderClient = (input) => {
-    const { config, logger, clientFactory, target, context, installation } = input;
-    const prerequisites = ghidraClientPrerequisites(target, input.profile, installation);
+    const { config, logger, clientFactory, context, installation } = input;
+    const { target, profile } = input.admission;
+    const prerequisites = ghidraClientPrerequisites(profile, installation);
     if (!prerequisites.ok)
-        return unavailableClient(prerequisites.error);
+        return err(prerequisites.error);
     const committedProfile = prerequisites.value.profile;
     const psp = isGhidraPspTarget(target);
     const pspExtension = psp
@@ -191,7 +46,7 @@ export const createGhidraProviderClient = (input) => {
         (!pspExtension.success ||
             committedProfile.parameters.language_id !== "Allegrex:LE:32:default" ||
             committedProfile.parameters.loader !== "PspElfLoader"))
-        return unavailableClient(new ProviderAdapterError("ghidra", "open_binary", {
+        return err(new ProviderAdapterError("ghidra", "open_binary", {
             diagnostics: {
                 reason: "Resolve the supported PSP profile and installed Allegrex extension before opening the session.",
             },
@@ -200,7 +55,7 @@ export const createGhidraProviderClient = (input) => {
     if (softFloat !==
         (committedProfile.parameters.mips_soft_float_storage ===
             GHIDRA_MIPS_SOFT_FLOAT_STORAGE))
-        return unavailableClient(new ProviderAdapterError("ghidra", "open_binary", {
+        return err(new ProviderAdapterError("ghidra", "open_binary", {
             diagnostics: {
                 reason: "Resolve the soft-float MIPS storage policy into the analysis profile before opening the session.",
             },
@@ -211,7 +66,7 @@ export const createGhidraProviderClient = (input) => {
     if (!extensionProfile.success ||
         (config.ghidraNativeAotJar !== undefined &&
             extensionProfile.data.length === 0))
-        return unavailableClient(new ProviderAdapterError("ghidra", "open_binary", {
+        return err(new ProviderAdapterError("ghidra", "open_binary", {
             diagnostics: {
                 reason: "Resolve the configured Ghidra extensions into an analysis profile before opening the session.",
             },
@@ -222,7 +77,7 @@ export const createGhidraProviderClient = (input) => {
         .safeParse(committedProfile.parameters.analysis_seeds);
     if (!seedProfile.success ||
         (config.ghidraSeedFile === undefined) !== (seedProfile.data === undefined))
-        return unavailableClient(new ProviderAdapterError("ghidra", "open_binary", {
+        return err(new ProviderAdapterError("ghidra", "open_binary", {
             diagnostics: {
                 reason: "Resolve REA_GHIDRA_SEED_FILE into an analysis profile before opening the session.",
             },
@@ -232,7 +87,7 @@ export const createGhidraProviderClient = (input) => {
     const pinnedLanguage = ghidraPinnedMipsLanguage(committedProfile.parameters);
     const targetLanguage = ghidraPinnedLanguage(target);
     if (pinnedLanguage !== undefined && targetLanguage === undefined)
-        return unavailableClient(new ProviderAdapterError("ghidra", "open_binary", {
+        return err(new ProviderAdapterError("ghidra", "open_binary", {
             diagnostics: {
                 reason: "The committed profile pins a MIPS language that the current target does not establish; reopen an admitted target to resolve a new profile.",
             },
@@ -242,13 +97,13 @@ export const createGhidraProviderClient = (input) => {
     // override conflicts with the legacy pin; the slot itself carries it.
     if (pinnedLanguage !== undefined &&
         config.ghidraLanguageOverride !== undefined)
-        return unavailableClient(new ProviderAdapterError("ghidra", "open_binary", {
+        return err(new ProviderAdapterError("ghidra", "open_binary", {
             diagnostics: {
                 reason: "The committed legacy MIPS profile pins its import language; REA_GHIDRA_LANGUAGE_ID/REA_GHIDRA_COMPILER_SPEC_ID cannot be combined with it. Reopen the target without the override.",
             },
         }));
     if (!sameGhidraLanguageOverride(parameterLanguage, config.ghidraLanguageOverride ?? targetLanguage))
-        return unavailableClient(new ProviderAdapterError("ghidra", "open_binary", {
+        return err(new ProviderAdapterError("ghidra", "open_binary", {
             diagnostics: {
                 reason: "The committed analysis profile and REA_GHIDRA_LANGUAGE_ID/REA_GHIDRA_COMPILER_SPEC_ID differ; reopen the target to resolve a new profile.",
             },
@@ -258,21 +113,20 @@ export const createGhidraProviderClient = (input) => {
     const importLanguage = parameterLanguage;
     const disabledAnalyzers = ghidraProfileDisabledAnalyzers(committedProfile.parameters);
     if (!sameGhidraDisabledAnalyzers(disabledAnalyzers, config.ghidraDisabledAnalyzers))
-        return unavailableClient(new ProviderAdapterError("ghidra", "open_binary", {
+        return err(new ProviderAdapterError("ghidra", "open_binary", {
             diagnostics: {
                 reason: "The committed analysis profile and REA_GHIDRA_DISABLED_ANALYZERS differ; reopen the target to resolve a new profile.",
             },
         }));
     const invalidProfile = validateGhidraExtensionProfile(extensions, config, target, installation.platform);
     if (invalidProfile !== null)
-        return unavailableClient(new ProviderAdapterError("ghidra", "open_binary", {
+        return err(new ProviderAdapterError("ghidra", "open_binary", {
             diagnostics: { reason: invalidProfile },
         }));
     let extensionFailure;
     // Replaced by the reported outcome once the session handshake is checked.
     const seedLimitations = [...ghidraSeedLimitations(seeds)];
     const pdbLimitations = [];
-    let pdbLoaded;
     // Replaced by the reported storage outcome once the handshake is checked.
     const softFloatLimitations = [
         ...ghidraMipsSoftFloatLimitations(softFloat),
@@ -290,13 +144,11 @@ export const createGhidraProviderClient = (input) => {
         ...(target.format === "raw-binary"
             ? [
                 "Headerless raw-binary analysis uses the caller-supplied architecture and entry address; file offset 0 is mapped at that address. Headers are not discovered from file bytes.",
-                "Little-endian generic Ghidra languages are used for x86, x86_64, arm, arm64, and NMOS 6502. Big-endian, Thumb-only, Cortex-M, 65C02, 65816, and other processor variants are unsupported in this increment.",
+                "Little-endian generic Ghidra languages are used for x86, x86_64, arm, arm64, and NMOS 6502; m68k uses the big-endian 68000 default language, which decodes the 68040 superset. Big-endian ARM, Thumb-only, Cortex-M, 65C02, 65816, separate 68020/68030/CPU32/ColdFire variants, and other processor variants are unsupported in this increment.",
                 "Static analysis does not emulate reset vectors, memory-mapped I/O, or firmware boot sequences.",
             ]
             : []),
-        ...(target.kind === "executable" && target.architecture === "mips"
-            ? (target.mips.limitations ?? [])
-            : []),
+        ...(target.architecture === "mips" ? (target.mips.limitations ?? []) : []),
         ...(committedProfile.parameters.mips_abi_basis ===
             "inferred-o32-assumption-v1"
             ? [
@@ -315,17 +167,23 @@ export const createGhidraProviderClient = (input) => {
                 "macOS sessions require a matching executable Ghidra native decompiler; REA checks for it but does not build native components or change Gatekeeper quarantine state.",
             ]
             : [];
+    if (input.signal.aborted)
+        return err(new AnalysisCancelledError("create_analysis_client", {
+            cause: input.signal.reason,
+            diagnostics: ghidraInstallationDiagnostics(installation),
+        }));
     const client = clientFactory({
         startupTimeoutMs: config.ghidraStartupTimeoutMs,
         platform: installation.platform,
         launcher: new GhidraHeadlessLauncher({
             environment: input.environment,
             analyzeHeadlessPath: prerequisites.value.analyzeHeadlessPath,
+            configurationDirectoryName: prerequisites.value.configurationDirectoryName,
             javaHome: prerequisites.value.javaHome,
             ...(installation.javaVmName === undefined
                 ? {}
                 : { javaVmName: installation.javaVmName }),
-            bridgeScriptPath: fileURLToPath(new URL("../../bridge/ghidra/ReaGhidraBridge.java", import.meta.url)),
+            bridgeScriptPath: fileURLToPath(new URL(`../../bridge/ghidra/${GHIDRA_BRIDGE_SOURCES.bridge}`, import.meta.url)),
             ...(pspExtension?.success === true
                 ? { pspExtension: pspExtension.data }
                 : {}),
@@ -393,8 +251,7 @@ export const createGhidraProviderClient = (input) => {
     const lostProviderHealth = () => providerStarted ? client.operationHealthSnapshot?.() : undefined;
     const checkSessionObservations = async (operation, info) => {
         if (target.format === "pe") {
-            pdbLoaded = info.pdb?.loaded;
-            pdbLimitations.splice(0, pdbLimitations.length, ...ghidraPdbLimitations(info.pdb));
+            pdbLimitations.splice(0, pdbLimitations.length, ...ghidraPePdbLimitations(target, info.pdb));
         }
         const softFloatReason = ghidraMipsSoftFloatFailure(softFloat, info.mips_soft_float_storage);
         extensionFailure =
@@ -425,14 +282,13 @@ export const createGhidraProviderClient = (input) => {
         ...ghidraExtensionLimitations(extensions),
         ...seedLimitations,
         ...pdbLimitations,
-        ...ghidraPeCodeViewLimitations(target, pdbLoaded),
         ...(releaseLimitation === undefined ? [] : [releaseLimitation]),
     ];
     const nativeAotOwner = target.format === "pe"
-        ? createNativeAotSnapshotOwner({
-            client,
-            target,
-            startupTimeoutMs: config.ghidraStartupTimeoutMs,
+        ? new GhidraNativeAotSnapshotOwner({
+            targetSha256: target.sha256,
+            readSnapshot: client.readTargetSnapshot?.bind(client),
+            projectFailure: (operation, failure) => projectSessionError(operation, failure, config.ghidraStartupTimeoutMs),
         })
         : undefined;
     const projectExecution = (operation, normalized, rawResult, observationLimitations = [], locations = [], relationshipCoverage) => {
@@ -456,7 +312,38 @@ export const createGhidraProviderClient = (input) => {
             return parsed;
         return ok(projectExecution(operation, parsed.value, called.value));
     };
-    return {
+    const loadImageExecution = async (raw, signal) => {
+        const operation = "inspect_native_load_image";
+        const measured = parseGhidraInventoryResult(operation, raw);
+        if (!measured.ok)
+            return measured;
+        let derived;
+        if (target.format === "pe") {
+            if (nativeAotOwner === undefined)
+                return err(new ProviderAdapterError("ghidra", operation, {
+                    diagnostics: {
+                        reason: "The admitted PE session has no read-only NativeAOT snapshot owner.",
+                    },
+                }));
+            const result = await nativeAotOwner.derive(measured.value.image_base, operation, signal, raw);
+            if (!result.ok)
+                return result;
+            derived = result.value;
+        }
+        const attested = await attestGhidraNativeLoadImage({
+            target,
+            operation,
+            measured: measured.value,
+            client,
+            mapSessionError: (failure) => projectSessionError(operation, failure, config.ghidraStartupTimeoutMs, lostProviderHealth()),
+            nativeAotResult: derived,
+            signal,
+        });
+        return attested.ok
+            ? ok(projectExecution(operation, jsonValueSchema.parse(attested.value), raw))
+            : attested;
+    };
+    return ok({
         execute: async (operation, parameters, options) => {
             if (extensionFailure !== undefined)
                 return err(extensionFailure);
@@ -508,6 +395,8 @@ export const createGhidraProviderClient = (input) => {
                 return inventoryExecution(operation, called);
             if (!called.ok)
                 return err(projectSessionError(operation, called.error, config.ghidraStartupTimeoutMs, lostProviderHealth()));
+            if (operation === "inspect_native_load_image")
+                return loadImageExecution(called.value, options?.signal);
             let normalized;
             let observationLimitations = [];
             let observationLocations = [];
@@ -527,8 +416,14 @@ export const createGhidraProviderClient = (input) => {
                     return result;
                 normalized = result.value;
             }
-            if (operation === "inspect_native_data_type") {
-                const address = input.value.address;
+            if (operation === "inspect_native_data_type" &&
+                normalized !== null &&
+                typeof normalized === "object" &&
+                !Array.isArray(normalized) &&
+                normalized.metadata_recovery === undefined) {
+                // The bridge owns address-space resolution. Enrich its parsed identity;
+                // request parameters retain the caller's spelling.
+                const address = normalized.address;
                 if (typeof address === "string") {
                     if (target.format === "pe" && nativeAotOwner !== undefined) {
                         const started = await client.start(options?.signal, options?.progress);
@@ -538,49 +433,14 @@ export const createGhidraProviderClient = (input) => {
                         if (!derived.ok)
                             return derived;
                     }
-                    let metadata;
-                    metadata = nativeAotOwner?.readTypeDetail(address);
-                    if (metadata !== undefined &&
-                        normalized !== null &&
-                        typeof normalized === "object" &&
-                        !Array.isArray(normalized)) {
-                        const nativeResult = normalized;
-                        if (nativeResult.metadata_recovery === undefined)
-                            normalized = jsonValueSchema.parse({
-                                ...nativeResult,
-                                metadata_recovery: metadata,
-                            });
-                    }
+                    const metadata = nativeAotOwner?.readTypeDetail(address);
+                    if (metadata !== undefined)
+                        normalized = jsonValueSchema.parse({
+                            ...normalized,
+                            metadata_recovery: metadata,
+                        });
                 }
             }
-            if (operation === "inspect_native_load_image") {
-                let derived;
-                if (target.format === "pe") {
-                    const observations = nativeLoadImageObservationSchema.parse(normalized);
-                    if (nativeAotOwner === undefined)
-                        return err(new ProviderAdapterError("ghidra", operation, {
-                            diagnostics: {
-                                reason: "The admitted PE session has no read-only NativeAOT snapshot owner.",
-                            },
-                        }));
-                    const result = await nativeAotOwner.derive(observations.image_base, operation, options?.signal, normalized);
-                    if (!result.ok)
-                        return result;
-                    derived = result.value;
-                }
-                const attested = await attestGhidraNativeLoadImage({
-                    target,
-                    operation,
-                    measured: normalized,
-                    client,
-                    mapSessionError: (failure) => projectSessionError(operation, failure, config.ghidraStartupTimeoutMs, lostProviderHealth()),
-                    nativeAotResult: derived,
-                    signal: options?.signal,
-                });
-                if (!attested.ok)
-                    return attested;
-                normalized = attested.value;
-            }
             return ok(projectExecution(operation, normalized, called.value, observationLimitations, observationLocations, relationshipCoverage));
         },
         executeIfReady: async (operation, parameters, options) => {
@@ -606,14 +466,31 @@ export const createGhidraProviderClient = (input) => {
                 : [{ provider: committedProfile.provider, observation }];
         },
         close: async () => {
-            nativeAotOwner?.close();
-            return client.close();
+            await nativeAotOwner?.close();
+            const closed = await client.close();
+            const retained = nativeAotOwner?.cleanupFailure;
+            if (retained === undefined)
+                return closed;
+            return closed.ok
+                ? err(retained)
+                : err(analysisErrorWithCleanupFailure(closed.error, retained).bindCleanupDependencies([closed.error, retained]));
         },
-    };
+    });
 };
-const ghidraClientPrerequisites = (target, profile, installation) => {
+/** Admit caller inputs and native authority before Java work starts. */
+export const admitGhidraClient = (target, profile, platform) => {
     if (target.kind !== "executable")
         return err(new AnalysisCapabilityUnavailableError("ghidra", "health", `Ghidra cannot import ${target.kind} targets through this adapter.`));
+    if (platform === "win32") {
+        const readiness = inspectWindowsNativeReadiness(platform);
+        if (!readiness.available)
+            return err(new AnalysisCapabilityUnavailableError("ghidra", "health", readiness.reason));
+    }
+    if (profile === undefined || profile.provider.id !== "ghidra")
+        return err(new ProviderAdapterError("ghidra", "health"));
+    return ok({ target, profile });
+};
+const ghidraClientPrerequisites = (profile, installation) => {
     if (installation.status === "unavailable")
         return err(new ProviderAdapterError("ghidra", "health", {
             diagnostics: ghidraInstallationDiagnostics(installation),
@@ -623,31 +500,41 @@ const ghidraClientPrerequisites = (target, profile, installation) => {
         : undefined;
     if (readiness?.available === false)
         return err(new AnalysisCapabilityUnavailableError("ghidra", "health", readiness.reason));
-    if (profile === undefined || profile.provider.id !== "ghidra")
-        return err(new ProviderAdapterError("ghidra", "health"));
+    if (profile.provider.version !== installation.providerVersion)
+        return err(new ProviderAdapterError("ghidra", "health", {
+            diagnostics: {
+                reason: "The current installation version differs from the selected analysis profile; resolve the profile again.",
+                selected_provider_version: profile.provider.version,
+                current_installation: ghidraInstallationDiagnostics(installation),
+            },
+        }));
     return ok({
         analyzeHeadlessPath: installation.analyzeHeadlessPath,
+        configurationDirectoryName: installation.configurationDirectoryName,
         javaHome: installation.javaHome,
         providerVersion: installation.providerVersion,
         profile,
     });
 };
-const unavailableClient = (failure) => ({
-    execute: () => Promise.resolve(err(failure)),
-    close: () => Promise.resolve(ok(null)),
-});
 const projectSessionError = (operation, failure, startupTimeoutMs, health) => {
     const primary = projectPrimarySessionError(operation, failure, startupTimeoutMs, health);
     return failure.cleanupFailure === undefined
         ? primary
-        : analysisErrorWithCleanupFailure(primary, failure.cleanupFailure, operation);
+        : analysisErrorWithCleanupFailure(primary, failure.cleanupFailure, operation).bindCleanupDependencies([primary, failure.cleanupFailure]);
 };
 const projectPrimarySessionError = (operation, failure, startupTimeoutMs, health) => {
-    const context = { cause: failure, diagnostics: failure.diagnostics };
-    if (failure.cause instanceof AnalysisAccessDeniedError)
-        return new AnalysisAccessDeniedError(operation, failure.cause.path, failure.cause.systemCode, context);
-    if (failure.cause instanceof AnalysisArtifactChangedError)
-        return new AnalysisArtifactChangedError(operation, failure.cause.path, failure.cause.reason, context);
+    const context = {
+        cause: failure,
+        diagnostics: failure.diagnostics,
+        ...(failure.partialObservation === undefined
+            ? {}
+            : { partialObservation: failure.partialObservation }),
+    };
+    const physicalCause = artifactFilePrimaryFailure(failure.cause);
+    if (physicalCause instanceof AnalysisAccessDeniedError)
+        return new AnalysisAccessDeniedError(operation, physicalCause.path, physicalCause.systemCode, context);
+    if (physicalCause instanceof AnalysisArtifactChangedError)
+        return new AnalysisArtifactChangedError(operation, physicalCause.path, physicalCause.reason, context);
     if (operation === "annotate_native_function" &&
         failure.kind === "remote" &&
         failure.remoteCode === "invalid_function_name")
@@ -656,8 +543,13 @@ const projectPrimarySessionError = (operation, failure, startupTimeoutMs, health
         ]);
     if (failure.kind === "cancelled" ||
         (failure.kind === "remote" && failure.remoteCode === "decompile_cancelled"))
-        return new AnalysisCancelledError(operation, context);
-    if (failure.kind === "timeout" || failure.kind === "analysis_timeout")
+        return new AnalysisCancelledError(operation, {
+            ...context,
+            cause: failure.cancellation === undefined
+                ? failure
+                : failure.cancellation.reason,
+        });
+    if (failure.kind === "analysis_timeout")
         return new AnalysisTimeoutError(operation, failure.timeoutMs ?? startupTimeoutMs, context);
     if (failure.kind === "remote" &&
         failure.remoteCode === "regex_stack_exhausted")
@@ -672,6 +564,15 @@ const projectPrimarySessionError = (operation, failure, startupTimeoutMs, health
         ]);
     if (failure.kind === "remote" && failure.remoteCode === "method_unavailable")
         return new AnalysisCapabilityUnavailableError("ghidra", operation, failure.message, context);
+    const memoryFailure = projectObservedJvmMemoryFailure(operation, failure, context);
+    if (memoryFailure !== undefined)
+        return memoryFailure;
+    if (failure.kind === "timeout") {
+        const timeoutMs = failure.timeoutMs ?? startupTimeoutMs;
+        return new AnalysisTimeoutError(operation, timeoutMs, failure.message === GHIDRA_STARTUP_DEADLINE_ELAPSED
+            ? { ...context, ...ghidraStartupTimeoutGuidance(timeoutMs) }
+            : context);
+    }
     const exited = exitedProviderMessage(operation, failure, health);
     if (exited !== undefined)
         return new ProviderAdapterError("ghidra", operation, {
@@ -680,6 +581,65 @@ const projectPrimarySessionError = (operation, failure, startupTimeoutMs, health
         });
     return new ProviderAdapterError("ghidra", operation, context);
 };
+/** Project only OOME evidence captured during the operation that failed. */
+const projectObservedJvmMemoryFailure = (operation, failure, context) => {
+    if (failure.kind !== "start" &&
+        failure.kind !== "process" &&
+        failure.kind !== "protocol" &&
+        failure.kind !== "timeout")
+        return undefined;
+    const scoped = failure.diagnostics.failure_output;
+    if (scoped === null ||
+        typeof scoped !== "object" ||
+        Array.isArray(scoped) ||
+        typeof scoped.stdout !== "object" ||
+        scoped.stdout === null ||
+        typeof scoped.stderr !== "object" ||
+        scoped.stderr === null)
+        return undefined;
+    const streamText = (value) => typeof value === "object" &&
+        value !== null &&
+        !Array.isArray(value) &&
+        typeof value.text === "string"
+        ? value.text
+        : "";
+    const output = `${streamText(scoped.stdout)}\n${streamText(scoped.stderr)}`;
+    if (!/java\.lang\.OutOfMemoryError(?:\s*:|\b)/u.test(output))
+        return undefined;
+    const threadCapacity = /unable to create native thread/iu.test(output);
+    const heapExhaustion = /Java heap space|GC overhead limit exceeded/iu.test(output);
+    const detail = [
+        "Java heap space",
+        "GC overhead limit exceeded",
+        "Metaspace",
+        "Requested array size exceeds VM limit",
+        "unable to create native thread",
+    ].find((candidate) => output.includes(candidate));
+    if (threadCapacity)
+        return new AnalysisResourceConstraintError(operation, "capacity", "Ghidra's process output reports an OutOfMemoryError while creating a native thread. This is observed capacity evidence; it does not establish a process limit or the precise cause.", null, {
+            ...context,
+            remediationAction: "Reduce concurrent analysis processes or review the host's available thread and process capacity, then retry.",
+        });
+    const configuredHeap = failure.diagnostics.configured_jvm_max_heap;
+    const reportedLimits = heapExhaustion
+        ? {
+            configured_jvm_max_heap: typeof configuredHeap === "string" ? configuredHeap : null,
+        }
+        : null;
+    return new AnalysisResourceConstraintError(operation, "memory", `Ghidra's operation-scoped process output reports java.lang.OutOfMemoryError${detail === undefined ? "" : `: ${detail}`}. This is reported evidence and does not prove the exact allocation failure.`, reportedLimits, {
+        ...context,
+        ...(heapExhaustion
+            ? {
+                remediationAction: "If the host has available memory, consider increasing GHIDRA_HEADLESS_MAXMEM or disabling expensive analyzers with REA_GHIDRA_DISABLED_ANALYZERS, then retry.",
+            }
+            : {}),
+    });
+};
+/** Name the settings that change Ghidra's import-and-analysis startup deadline. */
+const ghidraStartupTimeoutGuidance = (timeoutMs) => ({
+    userMessage: `Ghidra did not finish importing and analyzing the target within its ${String(timeoutMs)} ms startup deadline (REA_GHIDRA_STARTUP_TIMEOUT_MS).`,
+    remediationAction: `Large binaries can need longer: set REA_GHIDRA_STARTUP_TIMEOUT_MS above ${String(timeoutMs)} in the environment that starts REA, or skip expensive analyzers with REA_GHIDRA_DISABLED_ANALYZERS, then open the target again. An MCP client's own tool-call timeout is separate and may also need raising.`,
+});
 /** A provider already observed as running can be restarted by reopening. */
 const exitedProviderMessage = (operation, failure, health) => {
     if (failure.kind !== "process" && failure.kind !== "protocol")