rea-agents 6.4.0 → 6.7.0

package/dist/ghidra/GhidraProviderClient.js

@@ -1,10 +1,13 @@
 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 { ghidraProfileLanguageOverride, sameGhidraLanguageOverride, } from "./GhidraAnalysisProfile.js";
+import { ghidraPinnedLanguage, ghidraProfileDisabledAnalyzers, ghidraProfileLanguageOverride, sameGhidraDisabledAnalyzers, sameGhidraLanguageOverride, } from "./GhidraAnalysisProfile.js";
+import { ghidraPinnedMipsLanguage } from "./GhidraMipsProfile.js";
 import { AnalysisCancelledError, AnalysisArtifactChangedError, AnalysisAccessDeniedError, AnalysisCapabilityUnavailableError, AnalysisInputError, AnalysisResourceConstraintError, AnalysisTimeoutError, } from "../domain/analysisErrorCore.js";
-import {} from "../domain/analysisErrorBase.js";
+import { providerRetryAction, } from "../domain/providerOperationHealth.js";
 import { jsonValueSchema } from "../domain/jsonValue.js";
 import { ProviderAdapterError } from "../domain/providerAdapterError.js";
 import { err, ok } from "../domain/result.js";
@@ -12,176 +15,58 @@ import { GhidraClient } from "./GhidraClient.js";
 import { isGhidraFunctionOperation, parseGhidraFunctionInput, parseGhidraFunctionResult, } from "./GhidraFunctionValues.js";
 import { isGhidraInventoryOperation, parseGhidraInventoryInput, parseGhidraInventoryResult, } from "./GhidraInventoryValues.js";
 import { ghidraInstallationDiagnostics, } from "./GhidraInstallation.js";
-import { unverifiedGhidraBuildLimitation } from "./GhidraInstallationPolicy.js";
+import { isGhidraPspTarget, GHIDRA_PSP_LIMITATIONS, } from "./GhidraPspProfile.js";
+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 { 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 "../application/binary/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 { GHIDRA_STARTUP_DEADLINE_ELAPSED, } from "./GhidraSessionError.js";
 import { ghidraExtensionFailure } from "./extensions/GhidraExtensionFailures.js";
 import { ghidraExtensionSchema, validateGhidraExtensionProfile, ghidraExtensionLimitations, } from "./extensions/GhidraExtensions.js";
-import { windowsNativeAuthorityUnavailableReason, hasWindowsNativeAuthority, } from "../process/WindowsAuthority.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;
-        },
-    };
-};
+import { inspectWindowsNativeReadiness } from "../process/WindowsAuthority.js";
+import { ghidraRawBinaryLanguage } from "./GhidraRawBinaryLanguage.js";
 /** 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
+        ? ghidraPspExtensionSchema.safeParse(committedProfile.parameters.psp_extension)
+        : null;
+    if (pspExtension !== null &&
+        (!pspExtension.success ||
+            committedProfile.parameters.language_id !== "Allegrex:LE:32:default" ||
+            committedProfile.parameters.loader !== "PspElfLoader"))
+        return err(new ProviderAdapterError("ghidra", "open_binary", {
+            diagnostics: {
+                reason: "Resolve the supported PSP profile and installed Allegrex extension before opening the session.",
+            },
+        }));
+    const softFloat = isGhidraMipsSoftFloatTarget(target);
+    if (softFloat !==
+        (committedProfile.parameters.mips_soft_float_storage ===
+            GHIDRA_MIPS_SOFT_FLOAT_STORAGE))
+        return err(new ProviderAdapterError("ghidra", "open_binary", {
+            diagnostics: {
+                reason: "Resolve the soft-float MIPS storage policy into the analysis profile before opening the session.",
+            },
+        }));
     const extensionProfile = ghidraExtensionSchema
         .array()
         .safeParse(committedProfile.parameters.analysis_extensions ?? []);
     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.",
             },
@@ -192,27 +77,63 @@ 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.",
             },
         }));
     const seeds = seedProfile.data;
-    const languageOverride = ghidraProfileLanguageOverride(committedProfile.parameters);
-    if (!sameGhidraLanguageOverride(languageOverride, config.ghidraLanguageOverride))
-        return unavailableClient(new ProviderAdapterError("ghidra", "open_binary", {
+    const parameterLanguage = ghidraProfileLanguageOverride(committedProfile.parameters);
+    const pinnedLanguage = ghidraPinnedMipsLanguage(committedProfile.parameters);
+    const targetLanguage = ghidraPinnedLanguage(target);
+    if (pinnedLanguage !== undefined && targetLanguage === undefined)
+        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.",
+            },
+        }));
+    // Provider-pinned profiles declare their language through the same
+    // parameter slot caller-configured profiles use, so only an environment
+    // override conflicts with the legacy pin; the slot itself carries it.
+    if (pinnedLanguage !== undefined &&
+        config.ghidraLanguageOverride !== undefined)
+        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 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.",
             },
         }));
+    // Both caller-selected and provider-pinned languages use the validated
+    // committed slot; the profile cannot supply its own applicability proof.
+    const importLanguage = parameterLanguage;
+    const disabledAnalyzers = ghidraProfileDisabledAnalyzers(committedProfile.parameters);
+    if (!sameGhidraDisabledAnalyzers(disabledAnalyzers, config.ghidraDisabledAnalyzers))
+        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 = [];
+    // Replaced by the reported storage outcome once the handshake is checked.
+    const softFloatLimitations = [
+        ...ghidraMipsSoftFloatLimitations(softFloat),
+    ];
+    const rawLanguage = target.format === "raw-binary"
+        ? ghidraRawBinaryLanguage(target.architecture)
+        : undefined;
     const targetLimitations = [
         ...(target.format === "dos-mz"
             ? [
@@ -220,9 +141,24 @@ export const createGhidraProviderClient = (input) => {
                 "Static DOS analysis does not emulate BIOS, DOS interrupts, device ports, or self-modifying unpacking code. Packed targets require a separately identified unpacked artifact for original-program analysis; appended overlays are not the initialized load module.",
             ]
             : []),
-        ...(target.kind === "executable" && target.architecture === "mips"
-            ? (target.mips.limitations ?? [])
+        ...(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; 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.architecture === "mips" ? (target.mips.limitations ?? []) : []),
+        ...(committedProfile.parameters.mips_abi_basis ===
+            "inferred-o32-assumption-v1"
+            ? [
+                "The ELF header declares no ABI field and no ABI flags record was observed; o32 calling conventions are an analysis assumption of this lane, not a declared fact.",
+                "Floating-point ABI semantics are unverified for this recordless legacy admission.",
+            ]
             : []),
+        ...ghidraMipsRelocatableLimitations(target),
+        ...ghidraMipsSharedLimitations(target),
+        ...ghidraRiscvLimitations(target),
     ];
     const providerLimitations = installation.platform === "win32"
         ? windowsP0Limitations
@@ -231,17 +167,44 @@ 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,
-            bridgeScriptPath: fileURLToPath(new URL("../../bridge/ghidra/ReaGhidraBridge.java", import.meta.url)),
+            ...(installation.javaVmName === undefined
+                ? {}
+                : { javaVmName: installation.javaVmName }),
+            bridgeScriptPath: fileURLToPath(new URL(`../../bridge/ghidra/${GHIDRA_BRIDGE_SOURCES.bridge}`, import.meta.url)),
+            ...(pspExtension?.success === true
+                ? { pspExtension: pspExtension.data }
+                : {}),
+            ...(softFloat ? { mipsSoftFloat: true } : {}),
             ...(target.format === "dos-mz" ? { dosMz: true } : {}),
             ...(target.format === "dos-com" ? { dosCom: true } : {}),
-            ...(languageOverride === undefined ? {} : { languageOverride }),
+            ...(rawLanguage === undefined || target.format !== "raw-binary"
+                ? {}
+                : {
+                    rawBinary: {
+                        languageId: rawLanguage.languageId,
+                        compilerSpecId: rawLanguage.compilerSpecId,
+                        baseAddr: target.entryPoint,
+                    },
+                }),
+            ...(importLanguage === undefined
+                ? {}
+                : { languageOverride: importLanguage }),
+            ...(config.ghidraDisabledAnalyzers === undefined
+                ? {}
+                : { disabledAnalyzers: config.ghidraDisabledAnalyzers }),
             ...(seeds === undefined ? {} : { analysisSeeds: seeds }),
             platform: installation.platform,
             ...(extensions.length === 0 ? {} : { analysisExtensions: extensions }),
@@ -260,22 +223,49 @@ export const createGhidraProviderClient = (input) => {
                 expectedLanguageId: "x86:LE:16:Real Mode",
                 expectedCompilerSpecId: "default",
             }
-            : languageOverride === undefined
-                ? {}
+            : rawLanguage === undefined
+                ? importLanguage === undefined
+                    ? {}
+                    : {
+                        expectedLanguageId: importLanguage.languageId,
+                        ...(importLanguage.compilerSpecId === undefined
+                            ? {}
+                            : { expectedCompilerSpecId: importLanguage.compilerSpecId }),
+                    }
                 : {
-                    expectedLanguageId: languageOverride.languageId,
-                    ...(languageOverride.compilerSpecId === undefined
-                        ? {}
-                        : { expectedCompilerSpecId: languageOverride.compilerSpecId }),
+                    expectedLanguageId: rawLanguage.languageId,
+                    expectedCompilerSpecId: rawLanguage.compilerSpecId,
                 }),
+        ...(psp
+            ? {
+                expectedLanguageId: "Allegrex:LE:32:default",
+                expectedCompilerSpecId: "default",
+            }
+            : {}),
         ...(context === undefined ? {} : { runId: context.runId }),
         logger: logger.child({ layer: "ghidra-bridge" }),
     });
-    const checkExtensions = async (operation, info) => {
+    // Startup failures retain installation guidance; only a previously running
+    // provider can be described as lost and reopened.
+    let providerStarted = false;
+    const lostProviderHealth = () => providerStarted ? client.operationHealthSnapshot?.() : undefined;
+    const checkSessionObservations = async (operation, info) => {
+        if (target.format === "pe") {
+            pdbLimitations.splice(0, pdbLimitations.length, ...ghidraPePdbLimitations(target, info.pdb));
+        }
+        const softFloatReason = ghidraMipsSoftFloatFailure(softFloat, info.mips_soft_float_storage);
         extensionFailure =
-            ghidraExtensionFailure(extensions, info.analysis_extensions ?? [], operation) ?? ghidraSeedFailure(seeds, info.analysis_seeds, operation);
+            ghidraExtensionFailure(extensions, info.analysis_extensions ?? [], operation) ??
+                ghidraSeedFailure(seeds, info.analysis_seeds, operation) ??
+                (softFloatReason === undefined
+                    ? undefined
+                    : new ProviderAdapterError("ghidra", operation, {
+                        diagnostics: { reason: softFloatReason },
+                    }));
         if (extensionFailure === undefined && info.analysis_seeds !== undefined)
             seedLimitations.splice(0, seedLimitations.length, ...ghidraSeedLimitations(seeds, info.analysis_seeds));
+        if (extensionFailure === undefined)
+            softFloatLimitations.splice(0, softFloatLimitations.length, ...ghidraMipsSoftFloatLimitations(softFloat, info.mips_soft_float_storage));
         if (extensionFailure === undefined)
             return undefined;
         const closed = await client.close();
@@ -287,18 +277,73 @@ export const createGhidraProviderClient = (input) => {
     const sessionLimitations = () => [
         ...providerLimitations,
         ...targetLimitations,
+        ...(psp ? GHIDRA_PSP_LIMITATIONS : []),
+        ...softFloatLimitations,
         ...ghidraExtensionLimitations(extensions),
         ...seedLimitations,
+        ...pdbLimitations,
         ...(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;
-    return {
+    const projectExecution = (operation, normalized, rawResult, observationLimitations = [], locations = [], relationshipCoverage) => {
+        return createAnalysisExecution(normalized, committedProfile.provider, {
+            rawResult,
+            locations,
+            analysisProfile: committedProfile,
+            ...(relationshipCoverage === undefined ? {} : { relationshipCoverage }),
+            limitations: [
+                ...limitationsFor(operation),
+                ...observationLimitations,
+                ...sessionLimitations(),
+            ],
+        });
+    };
+    const inventoryExecution = (operation, called) => {
+        if (!called.ok)
+            return err(projectSessionError(operation, called.error, config.ghidraStartupTimeoutMs, lostProviderHealth()));
+        const parsed = parseGhidraInventoryResult(operation, called.value);
+        if (!parsed.ok)
+            return parsed;
+        return ok(projectExecution(operation, parsed.value, called.value));
+    };
+    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);
@@ -307,10 +352,12 @@ export const createGhidraProviderClient = (input) => {
                 !isGhidraFunctionOperation(operation))
                 return err(new AnalysisCapabilityUnavailableError(GHIDRA_PROVIDER_IDENTITY.id, operation, "The Ghidra adapter does not declare this operation."));
             if (operation === "health") {
-                const started = await client.start(options?.signal);
+                const started = await client.start(options?.signal, options?.progress);
+                if (started.ok)
+                    providerStarted = true;
                 if (!started.ok)
-                    return err(projectSessionError(operation, started.error, config.ghidraStartupTimeoutMs));
-                const failed = await checkExtensions(operation, started.value);
+                    return err(projectSessionError(operation, started.error, config.ghidraStartupTimeoutMs, lostProviderHealth()));
+                const failed = await checkSessionObservations(operation, started.value);
                 if (failed !== undefined)
                     return err(failed);
                 return ok(createAnalysisExecution(started.value, committedProfile.provider, {
@@ -323,25 +370,45 @@ export const createGhidraProviderClient = (input) => {
                 : parseGhidraInventoryInput(operation, parameters);
             if (!input.ok)
                 return input;
-            if (extensions.length > 0 || seeds !== undefined) {
-                const started = await client.start(options?.signal);
+            if (target.format === "pe" ||
+                extensions.length > 0 ||
+                seeds !== undefined ||
+                softFloat) {
+                const started = await client.start(options?.signal, options?.progress);
+                if (started.ok)
+                    providerStarted = true;
                 if (!started.ok)
-                    return err(projectSessionError(operation, started.error, config.ghidraStartupTimeoutMs));
-                const failed = await checkExtensions(operation, started.value);
+                    return err(projectSessionError(operation, started.error, config.ghidraStartupTimeoutMs, lostProviderHealth()));
+                const failed = await checkSessionObservations(operation, started.value);
                 if (failed !== undefined)
                     return err(failed);
             }
-            const called = await client.callTool(operation, input.value, options?.signal === undefined ? {} : { signal: options.signal });
+            const called = await client.callTool(operation, input.value, {
+                ...(options?.signal === undefined ? {} : { signal: options.signal }),
+                ...(options?.progress === undefined
+                    ? {}
+                    : { progress: options.progress }),
+            });
+            if (called.ok)
+                providerStarted = true;
+            if (operation === "list_documents" || operation === "list_procedures")
+                return inventoryExecution(operation, called);
             if (!called.ok)
-                return err(projectSessionError(operation, called.error, config.ghidraStartupTimeoutMs));
+                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 = [];
+            let relationshipCoverage;
             if (isGhidraFunctionOperation(operation)) {
                 const result = parseGhidraFunctionResult(operation, called.value);
                 if (!result.ok)
                     return result;
                 normalized = result.value.value;
                 observationLimitations = result.value.limitations;
+                observationLocations = result.value.locations ?? [];
+                relationshipCoverage = result.value.relationshipCoverage;
             }
             else {
                 const result = parseGhidraInventoryResult(operation, called.value);
@@ -349,70 +416,49 @@ 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);
+                        const started = await client.start(options?.signal, options?.progress);
                         if (!started.ok)
-                            return err(projectSessionError(operation, started.error, config.ghidraStartupTimeoutMs));
+                            return err(projectSessionError(operation, started.error, config.ghidraStartupTimeoutMs, lostProviderHealth()));
                         const derived = await nativeAotOwner.derive(started.value.target.image_base, operation, options?.signal, normalized);
                         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),
-                    nativeAotResult: derived,
-                    signal: options?.signal,
-                });
-                if (!attested.ok)
-                    return attested;
-                normalized = attested.value;
-            }
-            return ok(createAnalysisExecution(normalized, committedProfile.provider, {
-                rawResult: called.value,
-                analysisProfile: committedProfile,
-                limitations: [
-                    ...limitationsFor(operation),
-                    ...observationLimitations,
-                    ...sessionLimitations(),
-                ],
-            }));
+            return ok(projectExecution(operation, normalized, called.value, observationLimitations, observationLocations, relationshipCoverage));
         },
+        executeIfReady: async (operation, parameters, options) => {
+            if (operation !== "list_documents" && operation !== "list_procedures")
+                return undefined;
+            if (extensionFailure !== undefined)
+                return err(extensionFailure);
+            const input = parseGhidraInventoryInput(operation, parameters);
+            if (!input.ok)
+                return input;
+            if (client.callToolIfReady === undefined)
+                return undefined;
+            const called = await client.callToolIfReady(operation, input.value, options?.signal === undefined ? {} : { signal: options.signal });
+            if (called === undefined)
+                return undefined;
+            return inventoryExecution(operation, called);
+        },
+        operationHealthSnapshot: () => client.operationHealthSnapshot?.(),
         runtimeLineageSnapshots: () => {
             const observation = client.runtimeLineage?.() ?? null;
             return observation === null
@@ -420,72 +466,189 @@ 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),
         }));
-    if (installation.platform === "win32" &&
-        !hasWindowsNativeAuthority(installation.platform))
-        return err(new AnalysisCapabilityUnavailableError("ghidra", "health", windowsNativeAuthorityUnavailableReason(installation.platform)));
-    if (profile === undefined || profile.provider.id !== "ghidra")
-        return err(new ProviderAdapterError("ghidra", "health"));
+    const readiness = installation.platform === "win32"
+        ? inspectWindowsNativeReadiness(installation.platform)
+        : undefined;
+    if (readiness?.available === false)
+        return err(new AnalysisCapabilityUnavailableError("ghidra", "health", readiness.reason));
+    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) => {
-    const primary = projectPrimarySessionError(operation, failure, startupTimeoutMs);
+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) => {
-    if (failure.cause instanceof AnalysisAccessDeniedError)
-        return new AnalysisAccessDeniedError(operation, failure.cause.path, failure.cause.systemCode, { cause: failure });
-    if (failure.cause instanceof AnalysisArtifactChangedError)
-        return new AnalysisArtifactChangedError(operation, failure.cause.path, failure.cause.reason, { cause: failure });
+const projectPrimarySessionError = (operation, failure, startupTimeoutMs, health) => {
+    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")
-        return new AnalysisInputError(operation, { cause: failure }, [
+        return new AnalysisInputError(operation, context, [
             { path: ["name"], reason: "invalid_value", message: failure.message },
         ]);
-    if (failure.kind === "cancelled")
-        return new AnalysisCancelledError(operation);
-    if (failure.kind === "timeout" || failure.kind === "analysis_timeout")
-        return new AnalysisTimeoutError(operation, failure.timeoutMs ?? startupTimeoutMs);
-    if (failure.kind === "remote" && failure.remoteCode === "decompile_cancelled")
-        return new AnalysisCancelledError(operation);
+    if (failure.kind === "cancelled" ||
+        (failure.kind === "remote" && failure.remoteCode === "decompile_cancelled"))
+        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")
         return new AnalysisResourceConstraintError(operation, "memory", failure.message, null, {
-            cause: failure,
+            ...context,
             remediationAction: "Retry this search in literal mode or simplify the regex. The active analysis session and annotations remain available.",
         });
     if (failure.kind === "remote" &&
         ["invalid_request", "not_found", "ambiguous"].includes(failure.remoteCode ?? ""))
-        return new AnalysisInputError(operation, { cause: failure }, [
+        return new AnalysisInputError(operation, context, [
             { path: [], reason: "invalid_value", message: failure.message },
         ]);
     if (failure.kind === "remote" && failure.remoteCode === "method_unavailable")
-        return new AnalysisCapabilityUnavailableError("ghidra", operation, failure.message);
-    return new ProviderAdapterError("ghidra", operation, {
-        cause: failure,
-        diagnostics: failure.diagnostics,
+        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, {
+            ...context,
+            userMessage: exited,
+        });
+    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")
+        return undefined;
+    if (health === undefined ||
+        providerRetryAction(health.state) !== "restart_provider")
+        return undefined;
+    const observed = health.state === "exited"
+        ? `exited${health.exitCode === null ? "" : ` with code ${String(health.exitCode)}`}`
+        : "became unreachable";
+    return `The Ghidra provider for this session ${observed} before ${operation} could complete. Call open_binary for the same target to start a new Ghidra session, then retry; session-only annotations from the previous provider are not retained.`;
+};