rea-agents 6.3.0 → 6.5.0

package/dist/ghidra/GhidraProviderClient.js

@@ -1,21 +1,181 @@
-import { analysisErrorWithCleanupFailure } from "../application/binary/AnalysisClientCleanup.js";
+import { analysisErrorWithCleanupFailure } from "../domain/analysisErrorCleanup.js";
 import { fileURLToPath } from "node:url";
 import { createAnalysisExecution, } from "../application/AnalysisProvider.js";
+import { ghidraSeedCommitmentSchema, ghidraSeedFailure, ghidraSeedLimitations, } from "./GhidraAnalysisSeeds.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";
 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 { 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 { ghidraPeCodeViewLimitations } from "./GhidraPeProfile.js";
 import { unverifiedGhidraBuildLimitation } from "./GhidraInstallationPolicy.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 { GHIDRA_PROVIDER_IDENTITY, healthLimitations, windowsP0Limitations, limitationsFor, } from "./GhidraProviderCapabilities.js";
+import { ghidraPdbLimitations, } from "./GhidraSessionValues.js";
 import { ghidraExtensionFailure } from "./extensions/GhidraExtensionFailures.js";
 import { ghidraExtensionSchema, validateGhidraExtensionProfile, ghidraExtensionLimitations, } from "./extensions/GhidraExtensions.js";
-import { windowsNativeAuthorityUnavailableReason, hasWindowsNativeAuthority, } from "../process/WindowsAuthority.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;
@@ -23,6 +183,28 @@ export const createGhidraProviderClient = (input) => {
     if (!prerequisites.ok)
         return unavailableClient(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 unavailableClient(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 unavailableClient(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 ?? []);
@@ -35,18 +217,97 @@ export const createGhidraProviderClient = (input) => {
             },
         }));
     const extensions = extensionProfile.data;
+    const seedProfile = ghidraSeedCommitmentSchema
+        .optional()
+        .safeParse(committedProfile.parameters.analysis_seeds);
+    if (!seedProfile.success ||
+        (config.ghidraSeedFile === undefined) !== (seedProfile.data === undefined))
+        return unavailableClient(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 parameterLanguage = ghidraProfileLanguageOverride(committedProfile.parameters);
+    const pinnedLanguage = ghidraPinnedMipsLanguage(committedProfile.parameters);
+    const targetLanguage = ghidraPinnedLanguage(target);
+    if (pinnedLanguage !== undefined && targetLanguage === undefined)
+        return unavailableClient(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 unavailableClient(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", {
+            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 unavailableClient(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", {
             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.",
-            "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.",
-        ]
-        : [];
+    // 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),
+    ];
+    const rawLanguage = target.format === "raw-binary"
+        ? ghidraRawBinaryLanguage(target.architecture)
+        : undefined;
+    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.",
+                "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.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.",
+                "Static analysis does not emulate reset vectors, memory-mapped I/O, or firmware boot sequences.",
+            ]
+            : []),
+        ...(target.kind === "executable" && 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
         : installation.platform === "darwin"
@@ -61,9 +322,32 @@ export const createGhidraProviderClient = (input) => {
             environment: input.environment,
             analyzeHeadlessPath: prerequisites.value.analyzeHeadlessPath,
             javaHome: prerequisites.value.javaHome,
+            ...(installation.javaVmName === undefined
+                ? {}
+                : { javaVmName: installation.javaVmName }),
             bridgeScriptPath: fileURLToPath(new URL("../../bridge/ghidra/ReaGhidraBridge.java", import.meta.url)),
+            ...(pspExtension?.success === true
+                ? { pspExtension: pspExtension.data }
+                : {}),
+            ...(softFloat ? { mipsSoftFloat: true } : {}),
             ...(target.format === "dos-mz" ? { dosMz: true } : {}),
             ...(target.format === "dos-com" ? { dosCom: true } : {}),
+            ...(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 }),
         }),
@@ -81,12 +365,50 @@ export const createGhidraProviderClient = (input) => {
                 expectedLanguageId: "x86:LE:16:Real Mode",
                 expectedCompilerSpecId: "default",
             }
+            : rawLanguage === undefined
+                ? importLanguage === undefined
+                    ? {}
+                    : {
+                        expectedLanguageId: importLanguage.languageId,
+                        ...(importLanguage.compilerSpecId === undefined
+                            ? {}
+                            : { expectedCompilerSpecId: importLanguage.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) => {
-        extensionFailure = ghidraExtensionFailure(extensions, info.analysis_extensions ?? [], operation);
+    // 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") {
+            pdbLoaded = info.pdb?.loaded;
+            pdbLimitations.splice(0, pdbLimitations.length, ...ghidraPdbLimitations(info.pdb));
+        }
+        const softFloatReason = ghidraMipsSoftFloatFailure(softFloat, info.mips_soft_float_storage);
+        extensionFailure =
+            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();
@@ -95,12 +417,45 @@ export const createGhidraProviderClient = (input) => {
             : analysisErrorWithCleanupFailure(extensionFailure, closed.error, operation);
     };
     const releaseLimitation = unverifiedGhidraBuildLimitation(prerequisites.value.providerVersion);
-    const sessionLimitations = [
+    const sessionLimitations = () => [
         ...providerLimitations,
         ...targetLimitations,
+        ...(psp ? GHIDRA_PSP_LIMITATIONS : []),
+        ...softFloatLimitations,
         ...ghidraExtensionLimitations(extensions),
+        ...seedLimitations,
+        ...pdbLimitations,
+        ...ghidraPeCodeViewLimitations(target, pdbLoaded),
         ...(releaseLimitation === undefined ? [] : [releaseLimitation]),
     ];
+    const nativeAotOwner = target.format === "pe"
+        ? createNativeAotSnapshotOwner({
+            client,
+            target,
+            startupTimeoutMs: config.ghidraStartupTimeoutMs,
+        })
+        : undefined;
+    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));
+    };
     return {
         execute: async (operation, parameters, options) => {
             if (extensionFailure !== undefined)
@@ -110,15 +465,17 @@ 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, {
                     analysisProfile: committedProfile,
-                    limitations: [...healthLimitations, ...sessionLimitations],
+                    limitations: [...healthLimitations, ...sessionLimitations()],
                 }));
             }
             const input = isGhidraFunctionOperation(operation)
@@ -126,42 +483,132 @@ export const createGhidraProviderClient = (input) => {
                 : parseGhidraInventoryInput(operation, parameters);
             if (!input.ok)
                 return input;
-            if (extensions.length > 0) {
-                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));
-            const result = isGhidraFunctionOperation(operation)
-                ? parseGhidraFunctionResult(operation, called.value)
-                : parseGhidraInventoryResult(operation, called.value);
-            if (!result.ok)
-                return result;
-            let normalized = result.value;
+                return err(projectSessionError(operation, called.error, config.ghidraStartupTimeoutMs, lostProviderHealth()));
+            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);
+                if (!result.ok)
+                    return result;
+                normalized = result.value;
+            }
+            if (operation === "inspect_native_data_type") {
+                const address = input.value.address;
+                if (typeof address === "string") {
+                    if (target.format === "pe" && nativeAotOwner !== undefined) {
+                        const started = await client.start(options?.signal, options?.progress);
+                        if (!started.ok)
+                            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,
+                            });
+                    }
+                }
+            }
             if (operation === "inspect_native_load_image") {
-                const attested = await attestGhidraNativeLoadImage(target, operation, result.value, client, (failure) => projectSessionError(operation, failure, config.ghidraStartupTimeoutMs));
+                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(createAnalysisExecution(normalized, committedProfile.provider, {
-                rawResult: called.value,
-                analysisProfile: committedProfile,
-                limitations: [...limitationsFor(operation), ...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
                 ? []
                 : [{ provider: committedProfile.provider, observation }];
         },
-        close: () => client.close(),
+        close: async () => {
+            nativeAotOwner?.close();
+            return client.close();
+        },
     };
 };
 const ghidraClientPrerequisites = (target, profile, installation) => {
@@ -171,9 +618,11 @@ const ghidraClientPrerequisites = (target, profile, installation) => {
         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)));
+    const readiness = installation.platform === "win32"
+        ? inspectWindowsNativeReadiness(installation.platform)
+        : 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"));
     return ok({
@@ -187,44 +636,59 @@ 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);
 };
-const projectPrimarySessionError = (operation, failure, startupTimeoutMs) => {
+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, { cause: failure });
+        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, { cause: failure });
+        return new AnalysisArtifactChangedError(operation, failure.cause.path, failure.cause.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 === "cancelled" ||
+        (failure.kind === "remote" && failure.remoteCode === "decompile_cancelled"))
+        return new AnalysisCancelledError(operation, context);
     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);
+        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 exited = exitedProviderMessage(operation, failure, health);
+    if (exited !== undefined)
+        return new ProviderAdapterError("ghidra", operation, {
+            ...context,
+            userMessage: exited,
+        });
+    return new ProviderAdapterError("ghidra", operation, context);
+};
+/** 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.`;
 };