rea-agents 4.0.0 → 4.1.0

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,84 @@
+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();
+/** 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) => {
+    if (["complete", "partial"].includes(value.status) &&
+        (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 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",

package/dist/hopper/HopperClient.js

@@ -2,7 +2,10 @@ import { randomBytes, randomUUID } from "node:crypto";
 import { access } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { AnalysisCapabilityUnavailableError, HopperCancelledError, HopperProcessError, HopperProtocolError, HopperRemoteError, HopperStartError, hopperStartupFailure, HopperTimeoutError, } from "../domain/errors.js";
+import { AnalysisCapabilityUnavailableError } from "../domain/analysisErrorCore.js";
+import { HopperCancelledError, HopperProcessError, HopperProtocolError, HopperRemoteError, HopperStartError, HopperTimeoutError, } from "../domain/hopperErrors.js";
+import {} from "../domain/analysisErrorBase.js";
+import { hopperStartupFailure, } from "../domain/hopperStartupFailure.js";
 import { err, ok } from "../domain/result.js";
 import { silentLogger } from "../logger.js";
 import { PrivateRuntimeRoot } from "../process/PrivateRuntimeRoot.js";
@@ -119,7 +122,8 @@ export class HopperClient {
             release();
             if (!result.ok)
                 reset();
-        }, () => {
+        }, (cause) => {
+            this.#logger.debug({ error: cause instanceof Error ? cause.message : String(cause) }, "Hopper startup promise rejected during bookkeeping");
             release();
             reset();
         });
@@ -228,6 +232,8 @@ export class HopperClient {
     }
     async #close(starting, controller, options) {
         try {
+            // best-effort cleanup: a rejected startup must not mask close/cleanup;
+            // #cleanup reports the authoritative close result.
             await starting?.catch(() => undefined);
             return await this.#cleanup(options);
         }
@@ -286,7 +292,9 @@ export class HopperClient {
             try {
                 await access(socketPath);
             }
-            catch {
+            catch (cause) {
+                // best-effort cleanup: socket polling; absence means keep waiting.
+                void cause;
                 if ((await deadline.wait(50)) === "aborted")
                     return err(startupInterruption(deadline));
                 continue;
@@ -350,7 +358,9 @@ export class HopperClient {
                 message: message.event.error.message,
             });
         }
-        catch {
+        catch (cause) {
+            // best-effort cleanup: diagnostic consumers must not break the client.
+            void cause;
             this.#logger.warn({ requestId: message.id }, "Hopper bridge diagnostic consumer rejected an event");
         }
     }

package/dist/hopper/HopperProcessDiagnostic.js

@@ -1,4 +1,4 @@
-import { hopperStartupFailure, } from "../domain/errors.js";
+import { hopperStartupFailure, } from "../domain/hopperStartupFailure.js";
 import { parseLinuxPrivateDisplayDiagnostic } from "./LinuxPrivateDisplayDiagnostic.js";
 /** Extract only a matching Linux adapter failure record. */
 export const hopperLauncherFailureDiagnostic = (event) => {

package/dist/hopper/HopperProvider.js

@@ -1,7 +1,7 @@
 import { fileURLToPath } from "node:url";
 import { accessSync, constants } from "node:fs";
 import { createAnalysisExecution } from "../application/AnalysisProvider.js";
-import { AnalysisCapabilityUnavailableError } from "../domain/errors.js";
+import { AnalysisCapabilityUnavailableError } from "../domain/analysisErrorCore.js";
 import { err } from "../domain/result.js";
 import { GENERATED_MCP_TOOL_CATALOG } from "../generatedMcpToolCatalog.js";
 import { HopperApplicationLauncher } from "./BridgeLauncher.js";
@@ -25,6 +25,8 @@ const MUTATING_OPERATIONS = new Set([
 /** Tool contracts implemented directly by the Hopper adapter. */
 export const HOPPER_PROVIDER_TOOL_CONTRACTS = Object.freeze([
     ...GENERATED_MCP_TOOL_CATALOG.filter(({ kind, name }) => kind === "official-proxy" &&
+        name !== "annotate_native_function" &&
+        name !== "inspect_native_load_image" &&
         name !== "inspect_native_data_type" &&
         name !== "inspect_native_instruction" &&
         name !== "resolve_native_call_targets"),
@@ -96,7 +98,9 @@ export class HopperProvider {
                 diagnostics,
             };
         }
-        catch {
+        catch (cause) {
+            // best-effort cleanup: optional launcher probing; failure means unavailable.
+            void cause;
             return {
                 status: "unavailable",
                 code: "executable_missing",
@@ -125,11 +129,11 @@ export class HopperProvider {
                 reason: null,
                 diagnostics,
             };
-        if (target.format === "dos-mz")
+        if (target.format === "dos-mz" || target.format === "dos-com")
             return {
                 status: "unsupported",
                 code: "target_format_unsupported",
-                reason: "DOS MZ analysis requires the Ghidra 16-bit real-mode adapter.",
+                reason: "DOS MZ/COM analysis requires the Ghidra 16-bit real-mode adapter.",
                 diagnostics,
             };
         return {

package/dist/hopper/HopperRequestQueue.js

@@ -1,4 +1,4 @@
-import { HopperCancelledError, HopperProcessError, HopperProtocolError, HopperRemoteError, } from "../domain/errors.js";
+import { HopperCancelledError, HopperProcessError, HopperProtocolError, HopperRemoteError, } from "../domain/hopperErrors.js";
 import { err } from "../domain/result.js";
 /** FIFO that keeps the wire serialized until Hopper actually replies. */
 export class HopperRequestQueue {
@@ -184,10 +184,14 @@ export class HopperRequestQueue {
     }
     #reportUpdate(entry, update) {
         try {
-            void Promise.resolve(entry.progress?.report(update)).catch(() => undefined);
+            void Promise.resolve(entry.progress?.report(update)).catch((cause) => {
+                // best-effort cleanup: progress rejection bookkeeping only.
+                void cause;
+            });
         }
-        catch {
+        catch (cause) {
             // Progress observation cannot change the request outcome.
+            void cause;
         }
     }
 }

package/dist/hopper/HopperSessionValues.js

@@ -1,4 +1,4 @@
-import { HopperProtocolError } from "../domain/errors.js";
+import { HopperProtocolError } from "../domain/hopperErrors.js";
 import { err, ok } from "../domain/result.js";
 /** Validate the bridge identity and exact per-launch run identifier. */
 export const parseHopperServerInfo = (value, expectedRunId) => {

package/dist/hopper/HopperSocketConnection.js

@@ -1,5 +1,5 @@
 import { createConnection } from "node:net";
-import { HopperCancelledError, HopperStartError } from "../domain/errors.js";
+import { HopperCancelledError, HopperStartError, } from "../domain/hopperErrors.js";
 import { err, ok } from "../domain/result.js";
 /** Open one abort-aware Hopper Unix-socket connection attempt. */
 export const connectHopperSocketOnce = (socketPath, signal) => new Promise((resolve) => {

package/dist/hopper/HopperTargetLease.js

@@ -2,12 +2,20 @@ import { createHash } from "node:crypto";
 import { chmod, lstat, mkdir, realpath, rm } from "node:fs/promises";
 import { createConnection, createServer, } from "node:net";
 import { join, resolve } from "node:path";
-import { HopperStartError } from "../domain/errors.js";
+import { HopperStartError } from "../domain/hopperErrors.js";
+import { safeParseJson } from "../domain/safeJson.js";
 const leaseDirectory = join("/tmp", `rea-hopper-${process.getuid?.() ?? 0}`);
 /** Keep two REA processes from opening duplicate Hopper documents for one target/profile. */
 export const acquireHopperTargetLease = async (input) => {
     const directory = input.directory ?? leaseDirectory;
     await ensureLeaseDirectory(directory);
+    // The canonical path only derives the lease key; it never authorizes access.
+    // Common expected `realpath` failures include a missing target or path
+    // component (ENOENT, ENOTDIR), an unreadable component (EACCES), or a
+    // symlink loop (ELOOP). This catch also falls back for every other error,
+    // which may hide a real filesystem problem. The lexical `resolve` fallback
+    // still yields a deterministic key, but aliases may take separate leases
+    // whenever `realpath` cannot resolve them.
     const targetPath = await realpath(input.targetPath).catch(() => resolve(input.targetPath));
     const key = createHash("sha256")
         .update(JSON.stringify({
@@ -104,22 +112,22 @@ const readOwner = (socketPath) => new Promise((resolveOwner) => {
         const newline = response.indexOf("\n");
         if (newline < 0)
             return;
-        try {
-            const value = JSON.parse(response.slice(0, newline));
-            if (typeof value === "object" &&
-                value !== null &&
-                typeof Reflect.get(value, "runId") === "string" &&
-                typeof Reflect.get(value, "processId") === "number")
-                finish({
-                    runId: Reflect.get(value, "runId"),
-                    processId: Reflect.get(value, "processId"),
-                });
-            else
-                finish(undefined);
-        }
-        catch {
+        const parsed = safeParseJson(response.slice(0, newline));
+        if (!parsed.ok) {
             finish(undefined);
+            return;
         }
+        const value = parsed.value;
+        if (typeof value === "object" &&
+            value !== null &&
+            typeof Reflect.get(value, "runId") === "string" &&
+            typeof Reflect.get(value, "processId") === "number")
+            finish({
+                runId: Reflect.get(value, "runId"),
+                processId: Reflect.get(value, "processId"),
+            });
+        else
+            finish(undefined);
     });
     socket.on("error", () => finish(undefined));
     socket.on("end", () => finish(undefined));

package/dist/hopper/LinuxPrivateDisplayDiagnostic.js

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { isHopperStartupFailureCode, } from "../domain/hopperStartupFailure.js";
+import { safeParseJson } from "../domain/safeJson.js";
 export const LINUX_PRIVATE_DISPLAY_DIAGNOSTIC_PREFIX = "REA_X11_DIAGNOSTIC=";
 const diagnosticContextSchema = z.object({
     component: z.literal("hopper_private_display"),
@@ -53,13 +54,11 @@ export const parseLinuxPrivateDisplayDiagnostic = (stderr) => {
     const record = records[0];
     if (record === undefined)
         return { ok: false, reason: "diagnostic_missing" };
-    try {
-        const parsed = diagnosticSchema.safeParse(JSON.parse(record.slice(LINUX_PRIVATE_DISPLAY_DIAGNOSTIC_PREFIX.length)));
-        if (!parsed.success)
-            return { ok: false, reason: "diagnostic_malformed" };
-        return { ok: true, value: parsed.data };
-    }
-    catch {
+    const decoded = safeParseJson(record.slice(LINUX_PRIVATE_DISPLAY_DIAGNOSTIC_PREFIX.length));
+    if (!decoded.ok)
         return { ok: false, reason: "diagnostic_malformed" };
-    }
+    const parsed = diagnosticSchema.safeParse(decoded.value);
+    if (!parsed.success)
+        return { ok: false, reason: "diagnostic_malformed" };
+    return { ok: true, value: parsed.data };
 };