rea-agents 6.4.0 → 6.7.0

package/dist/hopper/HopperMachOImage.js

@@ -4,11 +4,15 @@ import { z } from "zod";
 import { BinaryTargetError } from "../domain/configurationErrors.js";
 import { AnalysisCancelledError } from "../domain/analysisErrorCore.js";
 import { readFatSliceDeclarations, validateFatSlice, } from "../domain/apple/machoContainer.js";
+import { machoCpuSubtypeBase } from "../domain/apple/machoCpuIdentity.js";
 import { HopperCancelledError, HopperStartError, } from "../domain/hopperErrors.js";
 import { err, ok } from "../domain/result.js";
 /** Stable source coordinates committed before preparing an owned thin image. */
 export const hopperMachOImageSchema = z.strictObject({
-    method: z.literal("fat64_thin_slice"),
+    method: z.union([
+        z.literal("fat32_thin_slice"),
+        z.literal("fat64_thin_slice"),
+    ]),
     architecture_count: z.number().int().min(1).max(128),
     container_table_sha256: z.string().regex(/^[a-f0-9]{64}$/u),
     source_offset: z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER),
@@ -16,20 +20,20 @@ export const hopperMachOImageSchema = z.strictObject({
     cpu_type: z.number().int().nonnegative(),
     cpu_subtype: z.number().int().nonnegative(),
 });
-/** Validate the selected FAT64 slice without depending on Apple's lipo tool. */
+/** Validate the selected FAT slice without depending on Apple's lipo tool. */
 export const resolveHopperMachOImage = async (target, signal) => {
     const invalid = (reason, cause) => err(new BinaryTargetError(target.path, reason, cause === undefined ? undefined : { cause }));
     if (signal?.aborted)
         return err(new AnalysisCancelledError("open_binary"));
-    if (target.format !== "mach-o")
-        return invalid("Hopper FAT64 image preparation requires a Mach-O target");
+    if (target.format !== "mach-o" && target.format !== "mach-o-universal")
+        return invalid("Hopper FAT image preparation requires a Mach-O target");
     let file;
     try {
         file = await open(target.path, "r");
     }
     catch (cause) {
         // Keep the OS error so a read-permission denial reports access_denied.
-        return invalid(`Cannot read FAT64 source for Hopper image preparation: ${cause instanceof Error ? cause.message : String(cause)}`, cause);
+        return invalid(`Cannot read FAT source for Hopper image preparation: ${cause instanceof Error ? cause.message : String(cause)}`, cause);
     }
     try {
         const read = async (offset, length) => {
@@ -39,20 +43,25 @@ export const resolveHopperMachOImage = async (target, signal) => {
         };
         const header = await read(0, 8);
         const magic = header.length === 8 ? header.readUInt32BE(0) : 0;
-        if (magic !== 0xcafebabf && magic !== 0xbfbafeca)
-            return invalid("FAT64 source header changed before Hopper image preparation");
-        const littleEndian = magic === 0xbfbafeca;
+        const isFatMagic = [
+            0xcafebabe, 0xcafebabf, 0xbebafeca, 0xbfbafeca,
+        ].includes(magic);
+        if (!isFatMagic)
+            return invalid("FAT source header changed before Hopper image preparation");
+        const wide = magic === 0xcafebabf || magic === 0xbfbafeca;
+        const littleEndian = magic === 0xbebafeca || magic === 0xbfbafeca;
+        const entrySize = wide ? 32 : 20;
         const count = littleEndian
             ? header.readUInt32LE(4)
             : header.readUInt32BE(4);
         const size = (await file.stat()).size;
-        const tableEnd = 8 + count * 32;
+        const tableEnd = 8 + count * entrySize;
         if (count === 0 || count > 128 || tableEnd > size)
-            return invalid("FAT64 architecture table is truncated or exceeds the supported 128 entries");
-        const table = await read(8, count * 32);
+            return invalid("FAT architecture table is truncated or exceeds the supported 128 entries");
+        const table = await read(8, count * entrySize);
         const parsed = readFatSliceDeclarations(table, {
             count,
-            wide: true,
+            wide,
             littleEndian,
         });
         if (parsed.status === "malformed")
@@ -66,19 +75,21 @@ export const resolveHopperMachOImage = async (target, signal) => {
             const rangeError = validateFatSlice(slice, size, tableEnd);
             if (rangeError !== null)
                 return invalid(rangeError);
-            const reserved = littleEndian
-                ? table.readUInt32LE(slice.index * 32 + 28)
-                : table.readUInt32BE(slice.index * 32 + 28);
-            if (reserved !== 0)
-                return invalid(`FAT64 architecture ${slice.index} has a nonzero reserved field`);
+            if (wide) {
+                const reserved = littleEndian
+                    ? table.readUInt32LE(slice.index * 32 + 28)
+                    : table.readUInt32BE(slice.index * 32 + 28);
+                if (reserved !== 0)
+                    return invalid(`FAT64 architecture ${slice.index} has a nonzero reserved field`);
+            }
             if (slice.size < 12)
-                return invalid(`FAT64 architecture ${slice.index} has a truncated Mach-O header`);
+                return invalid(`FAT architecture ${slice.index} has a truncated Mach-O header`);
             const embedded = await read(slice.offset, 12);
             if (embedded.length !== 12)
-                return invalid(`FAT64 architecture ${slice.index} became truncated`);
+                return invalid(`FAT architecture ${slice.index} became truncated`);
             const thinMagic = embedded.readUInt32BE(0);
             if (![0xfeedface, 0xfeedfacf, 0xcefaedfe, 0xcffaedfe].includes(thinMagic))
-                return invalid(`FAT64 architecture ${slice.index} does not contain a Mach-O image`);
+                return invalid(`FAT architecture ${slice.index} does not contain a Mach-O image`);
             const little = thinMagic === 0xcefaedfe || thinMagic === 0xcffaedfe;
             const identity = {
                 cpuType: little ? embedded.readUInt32LE(4) : embedded.readUInt32BE(4),
@@ -100,13 +111,13 @@ export const resolveHopperMachOImage = async (target, signal) => {
             if (previous !== undefined &&
                 current !== undefined &&
                 current.offset < previous.offset + previous.size)
-                return invalid("FAT64 slices overlap");
+                return invalid("FAT slices overlap");
         }
-        const selected = matches.length === 1 ? matches[0] : undefined;
+        const selected = selectHopperSlice(matches, target.architecture);
         if (selected === undefined)
-            return invalid(`FAT64 selection for ${target.architecture} is ${matches.length === 0 ? "missing" : "ambiguous"}; extract the exact architecture into a thin image before opening it`);
+            return invalid(`FAT selection for ${target.architecture} is ${matches.length === 0 ? "missing" : "ambiguous"}; extract the exact architecture into a thin image before opening it`);
         return ok({
-            method: "fat64_thin_slice",
+            method: wide ? "fat64_thin_slice" : "fat32_thin_slice",
             architecture_count: count,
             container_table_sha256: createHash("sha256")
                 .update(header)
@@ -119,16 +130,37 @@ export const resolveHopperMachOImage = async (target, signal) => {
         });
     }
     catch (cause) {
-        return invalid(`Cannot validate FAT64 image: ${cause instanceof Error ? cause.message : String(cause)}`);
+        return invalid(`Cannot validate FAT image: ${cause instanceof Error ? cause.message : String(cause)}`);
     }
     finally {
         await file.close();
     }
 };
+/**
+ * Plain arm64 (cpusubtype 0) and arm64e (cpusubtype 2) function-entry encodings
+ * decode under Hopper's --aarch64; Apple's arm64e.x1 variant (cpusubtype 12)
+ * does not, so it is selected only when it is the arm64 family's only candidate.
+ * Every other ambiguity stays fail-closed.
+ */
+const selectHopperSlice = (matches, architecture) => {
+    if (matches.length === 1)
+        return matches[0];
+    if (architecture !== "arm64")
+        return undefined;
+    for (const cpuSubtype of [0, 2]) {
+        const preferred = matches.filter((slice) => machoCpuSubtypeBase(slice.cpuSubtype) === cpuSubtype);
+        if (preferred.length === 1)
+            return preferred[0];
+        if (preferred.length > 1)
+            return undefined;
+    }
+    return undefined;
+};
 /** Copy a selected slice and verify the entire original source in the same pass. */
 export const prepareHopperMachOImage = async (sourcePath, sourceSha256, image, destination, signal) => {
     if (signal?.aborted)
         return err(new HopperCancelledError());
+    const tableEntrySize = image.method === "fat64_thin_slice" ? 32 : 20;
     try {
         const source = await open(sourcePath, "r");
         try {
@@ -136,7 +168,7 @@ export const prepareHopperMachOImage = async (sourcePath, sourceSha256, image, d
             try {
                 const hash = createHash("sha256");
                 const tableHash = createHash("sha256");
-                const tableEnd = 8 + image.architecture_count * 32;
+                const tableEnd = 8 + image.architecture_count * tableEntrySize;
                 const thinHeader = [];
                 let position = 0;
                 let copied = 0;
@@ -172,11 +204,11 @@ export const prepareHopperMachOImage = async (sourcePath, sourceSha256, image, d
                 if (tableHash.digest("hex") !== image.container_table_sha256 ||
                     !headerMatches)
                     return err(new HopperStartError({
-                        userMessage: `FAT64 source ${sourcePath} no longer agrees with its committed architecture table or selected Mach-O header. Open the stable source again.`,
+                        userMessage: `FAT source ${sourcePath} no longer agrees with its committed architecture table or selected Mach-O header. Open the stable source again.`,
                     }));
                 if (observed !== sourceSha256 || copied !== image.byte_length)
                     return err(new HopperStartError({
-                        userMessage: `FAT64 source ${sourcePath} changed before launch: expected SHA-256 ${sourceSha256}, observed ${observed}; copied ${copied} of ${image.byte_length} selected bytes. Open the stable source again.`,
+                        userMessage: `FAT source ${sourcePath} changed before launch: expected SHA-256 ${sourceSha256}, observed ${observed}; copied ${copied} of ${image.byte_length} selected bytes. Open the stable source again.`,
                     }));
                 return ok(destination);
             }
@@ -193,7 +225,7 @@ export const prepareHopperMachOImage = async (sourcePath, sourceSha256, image, d
             ? err(new HopperCancelledError())
             : err(new HopperStartError({
                 cause,
-                userMessage: `Cannot prepare the selected FAT64 image from ${sourcePath}: ${cause instanceof Error ? cause.message : String(cause)}`,
+                userMessage: `Cannot prepare the selected FAT image from ${sourcePath}: ${cause instanceof Error ? cause.message : String(cause)}`,
             }));
     }
 };

package/dist/hopper/HopperProcessDiagnostic.js

@@ -1,5 +1,32 @@
 import { hopperStartupFailure, } from "../domain/hopperStartupFailure.js";
 import { parseLinuxPrivateDisplayDiagnostic } from "./LinuxPrivateDisplayDiagnostic.js";
+/** Recognize launcher stderr signatures only with complete, empty stdout. */
+const hasCompleteLauncherOutput = (outcome) => outcome.output_closed &&
+    !outcome.diagnostic_truncated &&
+    outcome.stdout.text === "" &&
+    outcome.stdout.bytes === 0 &&
+    outcome.stdout.retained_bytes === 0;
+/**
+ * Hopper's native helper sends activate before its open-document Apple event.
+ * Recognize its explicit authorization rejection. The launcher must separately
+ * establish that caller arguments could not alter the generated AppleScript.
+ * Other script errors, signals, and incomplete output leave ownership unknown.
+ */
+export const nativeHopperLaunchWasDenied = (outcome) => outcome !== undefined &&
+    outcome.exit_code === 2 &&
+    outcome.signal === null &&
+    hasCompleteLauncherOutput(outcome) &&
+    /^Cannot launch Hopper!\r?\nNot authorized to send Apple events to [^\r\n]+\.\r?\n?$/u.test(outcome.stderr.text);
+/**
+ * Recognize the launcher's complete Spotlight diagnostic for actionable setup
+ * guidance. Custom launchers may forward this report after a handoff, so the
+ * report does not establish whether a document exists or release ownership.
+ */
+export const hopperLauncherReportedApplicationNotFound = (outcome) => outcome !== undefined &&
+    outcome.exit_code === 3 &&
+    outcome.signal === null &&
+    hasCompleteLauncherOutput(outcome) &&
+    /^Hopper has not been found\.\r?\nPlease make sure that Spotlight is active in order for this tool to find Hopper's executable\.\r?\n?$/u.test(outcome.stderr.text);
 /** Extract only a matching Linux adapter failure record. */
 export const hopperLauncherFailureDiagnostic = (event) => {
     const parsed = parseLinuxPrivateDisplayDiagnostic(event.snapshot.stderr.text);

package/dist/hopper/HopperProvider.js

@@ -2,10 +2,11 @@ import { snapshotEnvironment } from "../process/snapshotEnvironment.js";
 import { fileURLToPath } from "node:url";
 import { accessSync, constants, statSync } from "node:fs";
 import { createAnalysisExecution } from "../application/AnalysisProvider.js";
+import { isElfMetadataArchitecture, } from "../domain/binaryTargetTypes.js";
 import { AnalysisCapabilityUnavailableError } from "../domain/analysisErrorCore.js";
 import { err, ok } from "../domain/result.js";
 import { HopperApplicationLauncher } from "./BridgeLauncher.js";
-import { hopperLoaderArgsForTarget, resolveHopperAnalysisProfile, } from "./HopperAnalysisProfile.js";
+import { hopperDeclinedArchitectureReason, hopperLoaderArgsForTarget, resolveHopperAnalysisProfile, } from "./HopperAnalysisProfile.js";
 import { mapHopperFileOffset } from "./HopperFileOffset.js";
 import { HopperRegexSearch } from "./HopperRegexSearch.js";
 import { HopperClient } from "./HopperClient.js";
@@ -83,6 +84,13 @@ export class HopperProvider {
                 reason: `Hopper cannot directly analyze ${target.kind} targets.`,
                 diagnostics,
             };
+        if (target.kind === "database" && this.platform === "darwin")
+            return {
+                status: "unsupported",
+                code: "target_kind_unsupported",
+                reason: "This Hopper macOS launcher cannot start REA's analysis bridge when opening a saved Hopper database. Open an executable target instead; saved-database analysis is unavailable until Hopper exposes a database launch route that runs the bridge script.",
+                diagnostics,
+            };
         if (target.kind === "database")
             return {
                 status: "supported",
@@ -90,11 +98,19 @@ export class HopperProvider {
                 reason: null,
                 diagnostics,
             };
-        if (target.architecture === "mips")
+        if (isElfMetadataArchitecture(target.architecture) ||
+            target.architecture === "hexagon")
             return {
                 status: "unsupported",
                 code: "architecture_unsupported",
-                reason: "REA's Hopper adapter does not admit MIPS targets.",
+                reason: hopperDeclinedArchitectureReason(target.architecture),
+                diagnostics,
+            };
+        if (target.format === "raw-binary")
+            return {
+                status: "unsupported",
+                code: "target_format_unsupported",
+                reason: "Headerless raw-binary analysis requires the Ghidra adapter with a caller-supplied architecture and entry point.",
                 diagnostics,
             };
         if (target.format === "dos-mz" || target.format === "dos-com")
@@ -173,10 +189,39 @@ export class HopperProvider {
                     : { launchMode: "native" }),
             }),
             ...(context === undefined ? {} : { runId: context.runId }),
+            startupTimeoutMs: this.config.hopperStartupTimeoutMs,
             logger: this.logger.child({ layer: "bridge" }),
             onDiagnostic: (diagnostic) => this.logger.info(diagnostic, "Hopper bridge reported a diagnostic"),
         });
         const regexSearch = new HopperRegexSearch(client);
+        const projectExecution = (operation, normalized, rawResult = null) => createAnalysisExecution(normalized, executionProvider, {
+            // Only the file-offset mapping differs from Hopper's reply.
+            rawResult,
+            ...(profile === undefined ? {} : { analysisProfile: profile }),
+            ...(operation === "procedure_callers" ||
+                operation === "procedure_callees" ||
+                operation === "analyze_function"
+                ? { relationshipCoverage: { status: "complete" } }
+                : {}),
+            limitations: [
+                ...(preparedImage === undefined
+                    ? []
+                    : [
+                        "REA loaded a verified thin Mach-O slice from the original FAT source. Identity and file offsets refer to the original file. The owned temporary image and its Hopper document close together, including on MCP shutdown.",
+                    ]),
+                ...(CAPABILITIES.find((descriptor) => descriptor.operation === operation)?.limitations ?? []),
+                ...(operation === "read_bytes"
+                    ? [
+                        "Hopper byte reads stop at the containing segment's exclusive end; a readable prefix is returned with complete=false when the requested range crosses it.",
+                    ]
+                    : []),
+                ...(operation === "procedure_references"
+                    ? [
+                        "Native CallReference classifications and unresolved targets are preserved. Detailed reference flags and coverage beyond reported CallReference objects remain unknown.",
+                    ]
+                    : []),
+            ],
+        });
         return {
             execute: async (operation, parameters, options) => {
                 const result = (operation === "search_strings" ||
@@ -190,34 +235,17 @@ export class HopperProvider {
                     ? await mapHopperFileOffset(target, result.value, options?.signal)
                     : result;
                 return mapped.ok
-                    ? {
-                        ok: true,
-                        value: createAnalysisExecution(mapped.value, executionProvider, {
-                            // Only the file-offset mapping differs from Hopper's reply.
-                            rawResult: mapped === result ? null : result.value,
-                            ...(profile === undefined ? {} : { analysisProfile: profile }),
-                            limitations: [
-                                ...(preparedImage === undefined
-                                    ? []
-                                    : [
-                                        "REA loaded a verified thin Mach-O slice from the original FAT64 source. Identity and file offsets refer to the original file. The owned temporary image and its Hopper document close together, including on MCP shutdown.",
-                                    ]),
-                                ...(CAPABILITIES.find((descriptor) => descriptor.operation === operation)?.limitations ?? []),
-                                ...(operation === "read_bytes"
-                                    ? [
-                                        "Hopper byte reads stop at the containing segment's exclusive end; a readable prefix is returned with complete=false when the requested range crosses it.",
-                                    ]
-                                    : []),
-                                ...(operation === "procedure_references"
-                                    ? [
-                                        "Native CallReference classifications and unresolved targets are preserved. Detailed reference flags and coverage beyond reported CallReference objects remain unknown.",
-                                    ]
-                                    : []),
-                            ],
-                        }),
-                    }
+                    ? ok(projectExecution(operation, mapped.value, mapped === result ? null : result.value))
                     : mapped;
             },
+            executeIfReady: async (operation, parameters, options) => {
+                if (operation !== "list_documents" && operation !== "list_procedures")
+                    return undefined;
+                const result = await client.callToolIfReady(operation, parameters, options?.signal === undefined ? {} : { signal: options.signal });
+                if (result === undefined || !result.ok)
+                    return result;
+                return ok(projectExecution(operation, result.value));
+            },
             runtimeLineageSnapshots: () => {
                 const observation = client.runtimeLineage();
                 return observation === null

package/dist/hopper/HopperProviderCapabilities.js

@@ -1,3 +1,4 @@
+import { REGEX_MATCHING_LIMITATION } from "../process/RegexMatcher.js";
 /** Public identity committed by every Hopper-backed observation. */
 export const HOPPER_PROVIDER_IDENTITY = Object.freeze({
     id: "hopper",
@@ -52,11 +53,15 @@ const MUTATING_OPERATIONS = new Set([
     "unset_bookmark",
 ]);
 /** Source-owned capabilities without acquiring or probing a Hopper session. */
-export const CAPABILITIES = Object.freeze(HOPPER_OPERATIONS.map((operation) => Object.freeze({
+export const CAPABILITIES = Object.freeze([...HOPPER_OPERATIONS, "search_bytes"].map((operation) => Object.freeze({
     provider: HOPPER_PROVIDER_IDENTITY,
     operation,
-    available: true,
-    reason: null,
+    ...(operation === "search_bytes"
+        ? {
+            available: false,
+            reason: "Masked byte search has not been verified for Hopper.",
+        }
+        : { available: true, reason: null }),
     effects: Object.freeze({
         mutatesArtifact: MUTATING_OPERATIONS.has(operation),
         launchesProcess: true,
@@ -75,7 +80,7 @@ export const CAPABILITIES = Object.freeze(HOPPER_OPERATIONS.map((operation) => O
             : []),
         ...(operation === "search_strings" || operation === "search_procedures"
             ? [
-                "Regex mode uses ECMAScript Unicode semantics in a supervised worker with a five-second matching deadline. Cancellation or deadline failure stops matching without blocking Hopper; literal mode retains native casefold semantics.",
+                `${REGEX_MATCHING_LIMITATION} Literal mode retains native casefold semantics.`,
             ]
             : []),
         ...(operation === "list_strings" ||

package/dist/hopper/HopperRegexSearch.js

@@ -1,22 +1,15 @@
-import { Worker } from "node:worker_threads";
 import { z } from "zod";
-import { AnalysisCancelledError, AnalysisOutputError, AnalysisResourceConstraintError, } from "../domain/analysisErrorCore.js";
+import { AnalysisCancelledError, AnalysisOutputError, } from "../domain/analysisErrorCore.js";
 import { analysisStringSchema } from "../domain/hopperValues.js";
 import { HopperRemoteError } from "../domain/hopperErrors.js";
 import { err, ok } from "../domain/result.js";
 import { analysisSearchInput } from "../contracts/analysisSearchContract.js";
-const MATCHING_DEADLINE_MS = 5_000;
+import { matchRegexValues } from "../process/RegexMatcher.js";
+import { analysisClientFailureForOperation } from "../providers/AnalysisClientFailure.js";
 const inputSchema = z.strictObject({
     ...analysisSearchInput,
     mode: z.literal("regex"),
 });
-const replySchema = z.discriminatedUnion("status", [
-    z.strictObject({
-        status: z.literal("matched"),
-        indices: z.array(z.number().int().nonnegative()),
-    }),
-    z.strictObject({ status: z.literal("invalid_pattern"), reason: z.string() }),
-]);
 /** Match collected native facts off Hopper's API thread, with cancellable lifetime. */
 export class HopperRegexSearch {
     client;
@@ -67,12 +60,12 @@ export class HopperRegexSearch {
             ? {}
             : { document: input.data.document }, inventoryOptions);
         if (!inventory.ok)
-            return inventory;
+            return err(analysisClientFailureForOperation(inventory.error, "hopper", operation));
         const parsed = z.array(analysisStringSchema).safeParse(inventory.value);
         if (!parsed.success)
             return err(new AnalysisOutputError(operation, "Hopper search inventory is malformed"));
         if (options.signal?.aborted)
-            return err(new AnalysisCancelledError(operation));
+            return err(new AnalysisCancelledError(operation, { cause: options.signal.reason }));
         await options.progress
             ?.report({
             phase: "hopper_regex",
@@ -82,53 +75,21 @@ export class HopperRegexSearch {
         })
             .catch(() => undefined);
         if (options.signal?.aborted)
-            return err(new AnalysisCancelledError(operation));
-        let worker;
-        try {
-            worker = new Worker(new URL("./HopperRegexWorker.js", import.meta.url), {
-                workerData: {
-                    pattern: input.data.pattern,
-                    caseSensitive: input.data.case_sensitive,
-                    values: parsed.data.map((item) => item.value),
-                },
-            });
-        }
-        catch (cause) {
-            return err(new AnalysisOutputError(operation, `Cannot start regex worker: ${cause instanceof Error ? cause.message : String(cause)}`, { cause }));
-        }
-        try {
-            return await new Promise((resolve) => {
-                const finish = (result) => {
-                    clearTimeout(timer);
-                    options.signal?.removeEventListener("abort", onAbort);
-                    resolve(result);
-                };
-                const onAbort = () => finish(err(new AnalysisCancelledError(operation)));
-                const timer = setTimeout(() => finish(err(new AnalysisResourceConstraintError(operation, "cpu", "Regex matching exceeded its supervised deadline; the Hopper API thread remains available.", { matching_deadline_ms: MATCHING_DEADLINE_MS }, {
-                    remediationAction: "Simplify the ECMAScript Unicode regex or use literal mode, then retry in the same session.",
-                }))), MATCHING_DEADLINE_MS);
-                options.signal?.addEventListener("abort", onAbort, { once: true });
-                if (options.signal?.aborted)
-                    onAbort();
-                worker.once("message", (message) => {
-                    const reply = replySchema.safeParse(message);
-                    if (!reply.success)
-                        return finish(err(new AnalysisOutputError(operation, "Regex worker reply is malformed")));
-                    if (reply.data.status === "invalid_pattern")
-                        return finish(err(new HopperRemoteError(-32000, `Invalid regex pattern: ${reply.data.reason}`, { diagnosticType: "invalid_request", operation })));
-                    const indices = reply.data.indices;
-                    if (indices.some((index, position) => index >= parsed.data.length ||
-                        (position > 0 && index <= (indices[position - 1] ?? -1))))
-                        return finish(err(new AnalysisOutputError(operation, "Regex worker returned invalid inventory indices")));
-                    const selected = new Set(indices);
-                    finish(ok(parsed.data.filter((_, index) => selected.has(index))));
-                });
-                worker.once("error", (cause) => finish(err(new AnalysisOutputError(operation, `Regex worker failed: ${cause.message}`, { cause }))));
-                worker.once("exit", (code) => finish(err(new AnalysisOutputError(operation, `Regex worker exited without a result (${code})`))));
-            });
-        }
-        finally {
-            await worker.terminate();
-        }
+            return err(new AnalysisCancelledError(operation, { cause: options.signal.reason }));
+        const matched = await matchRegexValues({
+            operation,
+            pattern: input.data.pattern,
+            caseSensitive: input.data.case_sensitive,
+            values: parsed.data.map((item) => item.value),
+            signal: options.signal,
+            invalidPattern: (reason) => new HopperRemoteError(-32000, `Invalid regex pattern: ${reason}`, {
+                diagnosticType: "invalid_request",
+                operation,
+            }),
+        });
+        if (!matched.ok)
+            return matched;
+        const selected = new Set(matched.value);
+        return ok(parsed.data.filter((_, index) => selected.has(index)));
     }
 }

package/dist/hopper/HopperRequestQueue.js

@@ -161,7 +161,12 @@ export class HopperRequestQueue {
         }, 1_000);
         try {
             entry.transmitted = true;
-            this.send({ id: entry.id, method: entry.method, params: entry.params }, () => this.accept(entry.id, err(new HopperProcessError(null, undefined, entry.method, entry.id, "unreachable", hopperOperationStage(entry.method)))));
+            this.send({ id: entry.id, method: entry.method, params: entry.params }, () => this.accept(entry.id, err(new HopperProcessError(null, {
+                operation: entry.method,
+                requestId: entry.id,
+                providerState: "unreachable",
+                stage: hopperOperationStage(entry.method),
+            }))));
         }
         catch (cause) {
             this.accept(entry.id, err(new HopperProtocolError("Hopper socket write failed", { cause })));
@@ -236,12 +241,19 @@ export class HopperRequestQueue {
 }
 const withRequestContext = (error, entry) => {
     if (error instanceof HopperProcessError)
-        return new HopperProcessError(error.exitCode, error.diagnostic, error.operation ?? entry.method, error.requestId ?? entry.id, error.providerState, error.operation === undefined && error.stage === "connection"
-            ? hopperOperationStage(entry.method)
-            : error.stage);
+        return new HopperProcessError(error.exitCode, {
+            ...error,
+            cause: error.cause,
+            operation: error.operation ?? entry.method,
+            requestId: error.requestId ?? entry.id,
+            stage: error.operation === undefined && error.stage === "connection"
+                ? hopperOperationStage(entry.method)
+                : error.stage,
+        });
     if (error instanceof HopperRemoteError)
         return new HopperRemoteError(error.code, error.safeMessage, {
-            diagnosticType: error.diagnosticType,
+            ...error,
+            cause: error.cause,
             operation: error.operation ?? entry.method,
             requestId: error.requestId ?? entry.id,
         });

package/dist/hopper/HopperSessionValues.js

@@ -1,5 +1,7 @@
 import { HopperProtocolError } from "../domain/hopperErrors.js";
 import { err, ok } from "../domain/result.js";
+/** Bound cleanup handshakes and the bridge's idle reconnection wait. */
+export const HOPPER_SHUTDOWN_TIMEOUT_MS = 30_000;
 /** Validate the bridge identity and exact per-launch run identifier. */
 export const parseHopperServerInfo = (value, expectedRunId) => {
     if (typeof value === "object" &&
@@ -7,8 +9,15 @@ export const parseHopperServerInfo = (value, expectedRunId) => {
         !Array.isArray(value) &&
         value.name === "REA Hopper bridge" &&
         typeof value.version === "string" &&
+        typeof value.process_id === "number" &&
+        Number.isSafeInteger(value.process_id) &&
+        value.process_id > 0 &&
         value.run_id === expectedRunId)
-        return ok({ name: value.name, version: value.version });
+        return ok({
+            name: value.name,
+            version: value.version,
+            processId: value.process_id,
+        });
     return err(new HopperProtocolError("Hopper bridge health result is invalid"));
 };
 /** Require confirmation that the REA bridge detached or its document closed. */

package/dist/ida/IdaBusyHealth.js

@@ -0,0 +1,78 @@
+import { setTimeout as sleep } from "node:timers/promises";
+import { AnalysisTimeoutError } from "../domain/analysisErrorCore.js";
+import { busyHealthSchema } from "./IdaProtocolValues.js";
+/** Pause between health reads while a freshly opened worker reports itself busy. */
+const BUSY_HEALTH_RETRY_MS = 100;
+/** Only a tool-name-shaped value is repeated; other producer text is not echoed into errors. */
+const BUSY_TOOL_NAME = /^[A-Za-z0-9_.:-]{1,64}$/u;
+const monotonicClock = {
+    now: () => performance.now(),
+    delay: (ms, signal) => sleep(ms, undefined, { signal }),
+};
+const busyToolName = (tool) => tool !== undefined && BUSY_TOOL_NAME.test(tool) ? tool : "unknown";
+const isBusyStatus = (raw) => typeof raw === "object" &&
+    raw !== null &&
+    !Array.isArray(raw) &&
+    raw["status"] === "busy";
+/**
+ * Reads `server_health` until the worker stops reporting a transient busy
+ * state. The wait ends when the worker answers, the caller aborts, or the
+ * registration's request deadline has elapsed; once it has elapsed no further
+ * read is started and the last busy observation is reported. Any other payload
+ * is returned for the caller's strict parse, except an invalid busy payload,
+ * which keeps its own diagnostic.
+ */
+export const readSettledHealth = async (connection, { database, timeoutMs, signal, clock = monotonicClock, }) => {
+    const started = clock.now();
+    const remaining = () => timeoutMs - (clock.now() - started);
+    let lastBusy;
+    for (;;) {
+        const budgetMs = remaining();
+        if (budgetMs <= 0)
+            throw lastBusy === undefined
+                ? new AnalysisTimeoutError("server_health", timeoutMs)
+                : busyTimeout(lastBusy, timeoutMs);
+        const requestTimeoutMs = Math.min(timeoutMs, Math.ceil(budgetMs));
+        let raw;
+        try {
+            raw = await connection.call("server_health", { database }, { timeoutMs: requestTimeoutMs });
+        }
+        catch (cause) {
+            if (lastBusy !== undefined &&
+                cause instanceof AnalysisTimeoutError &&
+                cause.timeoutMs === requestTimeoutMs &&
+                requestTimeoutMs < timeoutMs) {
+                throw new AnalysisTimeoutError(lastBusy.operation, timeoutMs, {
+                    cause: lastBusy.raw,
+                    capturedOutput: cause.capturedOutput,
+                    diagnostics: {
+                        health_request_operation: cause.operation,
+                        health_request_timeout_ms: cause.timeoutMs,
+                    },
+                });
+            }
+            throw cause;
+        }
+        const busy = busyHealthSchema.safeParse(raw);
+        if (!busy.success) {
+            if (isBusyStatus(raw))
+                throw busy.error;
+            return raw;
+        }
+        const observedBusy = {
+            raw,
+            operation: `server_health: headless worker still busy in ${busyToolName(busy.data.busy_tool)}`,
+        };
+        lastBusy = observedBusy;
+        const expired = () => busyTimeout(observedBusy, timeoutMs);
+        if (remaining() <= 0)
+            throw expired();
+        await clock.delay(Math.min(BUSY_HEALTH_RETRY_MS, remaining()), signal);
+        signal?.throwIfAborted();
+        if (remaining() <= 0)
+            throw expired();
+    }
+};
+const busyTimeout = (lastBusy, timeoutMs) => new AnalysisTimeoutError(lastBusy.operation, timeoutMs, {
+    cause: lastBusy.raw,
+});