rea-agents 4.0.1 → 5.0.0

package/dist/ghidra/GhidraSessionError.js

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

package/dist/ghidra/GhidraSessionValues.js

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

package/dist/ghidra/GhidraTargetSnapshot.js

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

package/dist/ghidra/GhidraTransport.js

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

package/dist/ghidra/extensions/GhidraExtensionFailures.js

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

package/dist/ghidra/extensions/GhidraExtensions.js

@@ -0,0 +1,170 @@
+import { createHash } from "node:crypto";
+import { constants } from "node:fs";
+import { open, realpath, writeFile, mkdir } from "node:fs/promises";
+import { isAbsolute, join } from "node:path";
+import { z } from "zod";
+import { AnalysisCancelledError } from "../../domain/analysisErrorCore.js";
+import { ProviderAdapterError } from "../../domain/providerAdapterError.js";
+import { jsonObjectSchema } from "../../domain/jsonValue.js";
+import { err, ok } from "../../domain/result.js";
+import { nativeAotAdapter } from "./nativeaot/NativeAotAdapter.js";
+const digest = z.string().regex(/^[a-f0-9]{64}$/u);
+/** Exact executable extension artifact committed before the session starts. */
+export const ghidraExtensionSchema = z.strictObject({
+    id: z.string().regex(/^[a-z][a-z0-9-]*$/u),
+    path: z.string().refine(isAbsolute, "Extension path must be absolute"),
+    configured_path: z
+        .string()
+        .refine(isAbsolute, "Extension path must be absolute"),
+    sha256: digest,
+    entry_class: z.string().min(1),
+    integration_api: z.literal(1),
+});
+/** Shared extension envelope; each adapter validates its own producer result. */
+export const ghidraExtensionResultSchema = z.strictObject({
+    id: z.string().min(1),
+    sha256: digest,
+    status: z.enum([
+        "complete",
+        "partial",
+        "not_applicable",
+        "unsupported",
+        "failed",
+    ]),
+    reason: z.string().nullable(),
+    result: jsonObjectSchema,
+});
+const adapters = [nativeAotAdapter];
+const MAX_EXTENSION_BYTES = 8 * 1024 * 1024;
+/** Read a bounded regular artifact through its open handle, without ambient state changes. */
+const readJar = async (path) => {
+    const file = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    try {
+        const stat = await file.stat();
+        if (!stat.isFile() || stat.size < 4 || stat.size > MAX_EXTENSION_BYTES)
+            throw new Error(`Ghidra extension must be a regular JAR of 4..${MAX_EXTENSION_BYTES} bytes: ${path}`);
+        const bytes = Buffer.alloc(stat.size);
+        let offset = 0;
+        while (offset < bytes.length) {
+            const read = await file.read(bytes, offset, bytes.length - offset, offset);
+            if (read.bytesRead === 0)
+                throw new Error(`Incomplete Ghidra extension read: ${path}`);
+            offset += read.bytesRead;
+        }
+        const extra = Buffer.alloc(1);
+        if ((await file.read(extra, 0, 1, offset)).bytesRead !== 0 ||
+            bytes.readUInt32LE(0) !== 0x04034b50)
+            throw new Error(`Ghidra extension changed during read or is not a JAR: ${path}`);
+        return bytes;
+    }
+    finally {
+        await file.close();
+    }
+};
+/** Resolve explicitly configured optional extensions into the immutable analysis profile. */
+export const resolveGhidraExtensions = async (config, target, platform, signal) => {
+    const extensions = [];
+    for (const adapter of adapters) {
+        if (signal?.aborted)
+            return err(new AnalysisCancelledError("open_binary"));
+        const configured = adapter.configuredPath(config);
+        if (configured === undefined)
+            continue;
+        const reason = adapter.unsupportedReason(target, platform);
+        if (reason !== null)
+            return err(new ProviderAdapterError("ghidra", "resolve_analysis_profile", {
+                diagnostics: { extension: adapter.id, reason, path: configured },
+            }));
+        try {
+            const path = await realpath(configured);
+            const bytes = await readJar(path);
+            extensions.push({
+                id: adapter.id,
+                path,
+                configured_path: configured,
+                sha256: createHash("sha256").update(bytes).digest("hex"),
+                entry_class: adapter.entryClass,
+                integration_api: 1,
+            });
+        }
+        catch (cause) {
+            return err(new ProviderAdapterError("ghidra", "resolve_analysis_profile", {
+                cause,
+                diagnostics: {
+                    extension: adapter.id,
+                    path: configured,
+                    reason: cause instanceof Error ? cause.message : String(cause),
+                },
+            }));
+        }
+    }
+    if (signal?.aborted)
+        return err(new AnalysisCancelledError("open_binary"));
+    return ok(extensions);
+};
+/** Require explicit local configuration before admitting executable code from a profile. */
+export const validateGhidraExtensionProfile = (extensions, config, target, platform) => {
+    const enabled = adapters.filter((adapter) => adapter.configuredPath(config) !== undefined);
+    if (enabled.length !== extensions.length ||
+        new Set(extensions.map((extension) => extension.id)).size !==
+            extensions.length)
+        return "Configured Ghidra extension inventory differs from the resolved analysis profile.";
+    for (const extension of extensions) {
+        const adapter = enabled.find((value) => value.id === extension.id);
+        if (adapter === undefined ||
+            adapter.entryClass !== extension.entry_class ||
+            adapter.configuredPath(config) !== extension.configured_path)
+            return `Ghidra extension profile lacks matching explicit local configuration: ${extension.id}`;
+        const reason = adapter.unsupportedReason(target, platform);
+        if (reason !== null)
+            return reason;
+    }
+    return null;
+};
+/** Snapshot committed extension bytes into the private runtime before Java loads them. */
+export const snapshotGhidraExtensions = async (extensions, runtimeRoot) => {
+    if (extensions.length === 0)
+        return [];
+    for (const extension of extensions) {
+        ghidraExtensionSchema.parse(extension);
+        const adapter = adapters.find((value) => value.id === extension.id);
+        if (adapter === undefined || adapter.entryClass !== extension.entry_class)
+            throw new Error(`Unregistered Ghidra extension identity: ${extension.id}`);
+        if ((await realpath(extension.configured_path)) !== extension.path)
+            throw new Error(`Ghidra extension resolved path differs from explicit configuration: ${extension.id}`);
+    }
+    const directory = join(runtimeRoot, "extensions");
+    await mkdir(directory, { mode: 0o700 });
+    const result = [];
+    for (const extension of extensions) {
+        const bytes = await readJar(extension.path);
+        if (createHash("sha256").update(bytes).digest("hex") !== extension.sha256)
+            throw new Error(`Ghidra extension digest differs from committed profile: ${extension.id} (${extension.path})`);
+        const path = join(directory, `${extension.id}.jar`);
+        await writeFile(path, bytes, { flag: "wx", mode: 0o600 });
+        result.push({ ...extension, path });
+    }
+    return result;
+};
+/** Require every configured producer result to match its artifact and registered ABI. */
+export const validateGhidraExtensionResults = (expected, results) => {
+    if (results.length !== expected.length ||
+        new Set(results.map((result) => result.id)).size !== results.length)
+        return "Ghidra extension result inventory differs from its committed profile.";
+    for (const extension of expected) {
+        const result = results.find((value) => value.id === extension.id);
+        const adapter = adapters.find((value) => value.id === extension.id);
+        if (result === undefined ||
+            adapter === undefined ||
+            result.sha256 !== extension.sha256)
+            return `Ghidra extension identity mismatch: ${extension.id}`;
+        const invalid = adapter.validate(result);
+        if (invalid !== null)
+            return invalid;
+    }
+    return null;
+};
+/** Exact adapter limitations for explicitly configured session extensions. */
+export const ghidraExtensionLimitations = (extensions) => adapters
+    .filter((adapter) => extensions.some((extension) => extension.id === adapter.id))
+    .flatMap((adapter) => adapter.limitations);

package/dist/ghidra/extensions/nativeaot/NativeAotAdapter.js

@@ -0,0 +1,21 @@
+import { validateNativeAotReport } from "./NativeAotReport.js";
+/** NativeAOT-specific prerequisites and report interpretation behind the extension boundary. */
+export const nativeAotAdapter = {
+    id: "nativeaot",
+    entryClass: "rea.extensions.nativeaot.NativeAotExtension",
+    configuredPath: (config) => config.ghidraNativeAotJar,
+    unsupportedReason: (target, platform) => platform !== "linux"
+        ? "NativeAOT recovery is verified on Linux only; omit REA_GHIDRA_NATIVEAOT_JAR for ordinary native analysis."
+        : !["elf", "pe"].includes(target.format) ||
+            target.architecture !== "x86_64" ||
+            target.managed === true
+            ? "NativeAOT recovery requires an x86-64 ELF or native PE target on Linux; PE/CLI and ReadyToRun assemblies use inspect_managed_artifact; omit REA_GHIDRA_NATIVEAOT_JAR for ordinary native analysis."
+            : null,
+    validate: validateNativeAotReport,
+    limitations: [
+        "Optional NativeAOT recovery is verified for .NET 8.0.22 RTR 9.1 Linux x64 ELF and Windows x64 PE targets on a Linux host. Other runtime layouts, target architectures and hosts are unsupported.",
+        "Type names and relationships use recovery heuristics; original C# source and custom field layouts are not recovered. Rehydrated analysis-memory bytes are derived, without original file offsets or runtime observations.",
+        "Method prototypes are Ghidra inferences, not original signatures. Pre-recovery conventions are retained; new functions use the loaded compiler default. Verify parameter roles against instructions and call sites.",
+        "The configured extension retains its actual JAR digest. Its reported source revision is not an attestation of caller-supplied build bytes.",
+    ],
+};

package/dist/ghidra/extensions/nativeaot/NativeAotReport.js

@@ -0,0 +1,100 @@
+import { z } from "zod";
+const report = z
+    .object({
+    id: z.literal("nativeaot"),
+    integration_api: z.literal(1),
+    source_revision: z.literal("effeb734fc570c32650f88b159608979dc7b423e"),
+    source_revision_authority: z.literal("build-reported-unattested"),
+    status: z.enum([
+        "complete",
+        "partial",
+        "not_applicable",
+        "unsupported",
+        "failed",
+    ]),
+    reason: z.string().nullable(),
+    method_tables: z.number().int().nonnegative(),
+    diagnostics: z.array(z.string()),
+    header_address: z
+        .string()
+        .regex(/^0x[0-9a-f]+$/u)
+        .optional(),
+    discovery: z.enum(["symbol", "signature-heuristic"]).optional(),
+    format_major: z.number().int().optional(),
+    format_minor: z.number().int().optional(),
+    derived_memory: z
+        .object({
+        address: z.string().regex(/^0x[0-9a-f]+$/u),
+        size_bytes: z.number().int().nonnegative(),
+        sha256: z.string().regex(/^[a-f0-9]{64}$/u),
+        file_offset: z.null(),
+    })
+        .optional(),
+    coverage: z
+        .strictObject({
+        frozen_object_candidates: z.number().int().nonnegative(),
+        frozen_objects_annotated: z.number().int().nonnegative(),
+        basis: z.literal("rehydrated-pointer-candidates-and-committed-instance-types"),
+    })
+        .optional(),
+    types: z
+        .array(z.object({
+        address: z.string().regex(/^0x[0-9a-f]+$/u),
+        type: z.string().min(1),
+    }))
+        .optional(),
+})
+    .strict();
+const validateNonRecoveryMetadata = (value, recovered) => {
+    if (recovered)
+        return null;
+    if (value.reason === null || value.reason.trim().length === 0)
+        return "NativeAOT non-recovery status omits its required reason.";
+    return value.method_tables !== 0 ||
+        value.types !== undefined ||
+        value.derived_memory !== undefined ||
+        value.coverage !== undefined
+        ? "NativeAOT non-recovery status carries recovered metadata."
+        : null;
+};
+/** Validate the pinned producer representation before its result enters Evidence. */
+export const validateNativeAotReport = (value) => {
+    if (value.status === "failed" &&
+        typeof value.result.loader_failure === "string" &&
+        value.result.loader_failure === value.reason)
+        return null;
+    const parsed = report.safeParse(value.result);
+    if (!parsed.success ||
+        parsed.data.status !== value.status ||
+        parsed.data.reason !== value.reason)
+        return "NativeAOT extension returned a malformed or inconsistent producer report.";
+    return validateRecoveredMetadata(parsed.data);
+};
+const validateRecoveredMetadata = (value) => {
+    const recovered = ["complete", "partial"].includes(value.status);
+    if (recovered &&
+        (value.method_tables === 0 ||
+            value.format_major !== 9 ||
+            value.format_minor !== 1 ||
+            value.types?.length !== value.method_tables ||
+            value.derived_memory === undefined ||
+            value.header_address === undefined ||
+            value.discovery === undefined ||
+            value.coverage === undefined ||
+            value.reason !== null))
+        return "NativeAOT recovery omitted its supported format, method-table inventory or derived-memory identity.";
+    const nonRecoveryInvalid = validateNonRecoveryMetadata(value, recovered);
+    if (nonRecoveryInvalid !== null)
+        return nonRecoveryInvalid;
+    const coverage = value.coverage;
+    if (coverage !== undefined &&
+        (coverage.frozen_objects_annotated > coverage.frozen_object_candidates ||
+            (value.status === "complete" &&
+                coverage.frozen_objects_annotated !==
+                    coverage.frozen_object_candidates)))
+        return "NativeAOT recovery coverage contradicts its reported completion status.";
+    const types = value.types ?? [];
+    if (new Set(types.map((type) => type.address)).size !== types.length)
+        return "NativeAOT recovery repeated a method-table identity.";
+    return null;
+};

package/dist/hopper/BridgeLauncher.js

@@ -2,7 +2,7 @@ import { execFile } from "node:child_process";
 import { chmod, writeFile } from "node:fs/promises";
 import { basename, dirname, extname, join } from "node:path";
 import { promisify } from "node:util";
-import { HopperCancelledError, HopperProcessError, HopperStartError, } from "../domain/errors.js";
+import { HopperCancelledError, HopperProcessError, HopperStartError, } from "../domain/hopperErrors.js";
 import { err, ok } from "../domain/result.js";
 import { cleanupOwnedProcessGroup } from "../process/ProcessOwnership.js";
 import { execFileOutput } from "../process/ExecFileOutput.js";
@@ -275,7 +275,9 @@ const processIsRunning = async (executablePath) => {
             .split("\n")
             .some((command) => command.trim() === executablePath);
     }
-    catch {
+    catch (cause) {
+        // best-effort cleanup: optional process probing; failure means not running.
+        void cause;
         return false;
     }
 };

package/dist/hopper/HopperAnalysisProfile.js

@@ -1,7 +1,9 @@
 import { createHash } from "node:crypto";
 import { createReadStream } from "node:fs";
 import { createAnalysisProfile } from "../domain/analysisProfile.js";
-import { AnalysisCancelledError, ProviderAdapterError, } from "../domain/errors.js";
+import { AnalysisCancelledError } from "../domain/analysisErrorCore.js";
+import { ProviderAdapterError } from "../domain/providerAdapterError.js";
+import {} from "../domain/analysisErrorBase.js";
 import { err, ok } from "../domain/result.js";
 /** Resolve Hopper open semantics without placing its CLI flags in BinaryTarget. */
 export const resolveHopperAnalysisProfile = async (target, options) => {
@@ -63,6 +65,7 @@ export const hopperLoaderArgsForTarget = (target) => {
         case "pe":
             return ok(["-l", "WinPE", flag]);
         case "dos-mz":
+        case "dos-com":
             return err(new ProviderAdapterError("hopper", "resolve_analysis_profile"));
     }
 };
@@ -94,7 +97,9 @@ const sha256File = async (path, signal) => {
             ? err(new AnalysisCancelledError("open_binary"))
             : ok(hash.digest("hex"));
     }
-    catch {
+    catch (cause) {
+        // best-effort cleanup: unreadable targets mean no digest; abort still cancels.
+        void cause;
         return signalIsAborted(signal)
             ? err(new AnalysisCancelledError("open_binary"))
             : ok(undefined);

package/dist/hopper/HopperCleanup.js

@@ -1,4 +1,4 @@
-import { HopperProcessError } from "../domain/errors.js";
+import { HopperProcessError } from "../domain/hopperErrors.js";
 import { ProviderCleanupError } from "../domain/providerCleanupError.js";
 import { err, ok } from "../domain/result.js";
 import { createOwnedHopperShutdownDiagnostic, providerCleanupFailure, } from "./HopperDiagnostics.js";
@@ -34,11 +34,12 @@ const requestShutdown = async (input, state) => {
             }, "Hopper shutdown skipped because a bridge operation remained active");
         return;
     }
-    const shutdown = await input
-        .request(input.retainDocument || input.launch?.shutdownMode === "process-cleanup"
+    const method = input.retainDocument || input.launch?.shutdownMode === "process-cleanup"
         ? "shutdown"
-        : "shutdown_document")
-        .catch(() => err(new HopperProcessError(null)));
+        : "shutdown_document";
+    const shutdown = await input
+        .request(method)
+        .catch((cause) => err(shutdownRequestFailure(method, cause)));
     if (shutdown.ok &&
         isHopperCleanupRequired(shutdown.value) &&
         input.launch?.shutdownMode === "process-cleanup") {
@@ -57,17 +58,60 @@ const requestShutdown = async (input, state) => {
     }
     if (!shutdown.ok ||
         (!state.shutdownConfirmed && state.cleanupResult === undefined))
-        input.logger.warn({ status: shutdown.ok ? "invalid-acknowledgement" : "failed" }, "Hopper document shutdown was not confirmed");
+        input.logger.warn({
+            status: shutdown.ok ? "invalid-acknowledgement" : "failed",
+            ...(shutdown.ok ? {} : shutdownFailureDetails(shutdown.error)),
+        }, "Hopper document shutdown was not confirmed");
 };
 const fallbackDocumentShutdown = async (input) => {
     const fallback = await input
         .request("shutdown_document")
-        .catch(() => err(new HopperProcessError(null)));
+        .catch((cause) => err(shutdownRequestFailure("shutdown_document", cause)));
     const confirmed = fallback.ok && isHopperShutdownAcknowledgement(fallback.value);
     if (!confirmed)
-        input.logger.warn({ status: fallback.ok ? "invalid-acknowledgement" : "failed" }, "Hopper document shutdown fallback was not confirmed");
+        input.logger.warn({
+            status: fallback.ok ? "invalid-acknowledgement" : "failed",
+            ...(fallback.ok ? {} : shutdownFailureDetails(fallback.error)),
+        }, "Hopper document shutdown fallback was not confirmed");
     return confirmed;
 };
+const shutdownRequestFailure = (operation, cause) => {
+    const failure = new HopperProcessError(null, undefined, operation);
+    failure.cause = cause;
+    return failure;
+};
+const shutdownFailureDetails = (error) => ({
+    errorTag: error._tag,
+    ...(error instanceof HopperProcessError && error.operation !== undefined
+        ? { operation: error.operation }
+        : {}),
+    ...(error instanceof HopperProcessError && error.requestId !== undefined
+        ? { requestId: error.requestId }
+        : {}),
+    ...(error.cause === undefined
+        ? {}
+        : { failure_cause: describeFailureCause(error.cause) }),
+});
+const describeFailureCause = (cause) => {
+    if (cause instanceof Error) {
+        const code = "code" in cause ? cause.code : undefined;
+        return {
+            name: cause.name,
+            message: cause.message,
+            ...(typeof code === "string" ||
+                (typeof code === "number" && Number.isFinite(code))
+                ? { code }
+                : {}),
+        };
+    }
+    if (typeof cause === "string")
+        return { type: "string", message: cause };
+    if (cause === null ||
+        typeof cause === "boolean" ||
+        (typeof cause === "number" && Number.isFinite(cause)))
+        return { type: cause === null ? "null" : typeof cause, value: cause };
+    return { type: typeof cause };
+};
 const stopProcess = async (input, state) => {
     const supervisor = input.processSupervisor;
     if (supervisor === undefined)
@@ -79,8 +123,9 @@ const stopProcess = async (input, state) => {
     try {
         input.onDiagnostic?.(diagnostic);
     }
-    catch {
+    catch (cause) {
         // Diagnostic consumers cannot change the already-observed cleanup result.
+        void cause;
     }
     input.logger.info(diagnostic, "Owned Hopper launcher shutdown completed");
     if (stopped.status !== "incomplete") {
@@ -149,6 +194,7 @@ const activityDetails = (activity) => ({
     queued_requests: activity.queuedRequests,
 });
 const report = async (progress, completed, message) => {
+    // best-effort cleanup: progress reporting must not fail session cleanup.
     await progress
         ?.report({
         phase: "hopper_cleanup",