rea-agents 6.3.0 → 6.5.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,18 +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" && 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) => {
@@ -37,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")
@@ -64,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),
@@ -98,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)
@@ -117,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 {
@@ -134,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;
@@ -170,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);
             }
@@ -191,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

@@ -1,7 +1,8 @@
 import { snapshotEnvironment } from "../process/snapshotEnvironment.js";
 import { fileURLToPath } from "node:url";
-import { accessSync, constants } from "node:fs";
+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";
@@ -49,6 +50,9 @@ export class HopperProvider {
             };
         try {
             accessSync(this.config.hopperLauncherPath, constants.X_OK);
+            // A searchable directory, such as an .app bundle, also passes X_OK.
+            if (!statSync(this.config.hopperLauncherPath).isFile())
+                throw new TypeError("Hopper launcher is not a regular file");
             return {
                 status: "available",
                 code: null,
@@ -80,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",
@@ -87,6 +98,24 @@ export class HopperProvider {
                 reason: null,
                 diagnostics,
             };
+        if (isElfMetadataArchitecture(target.architecture))
+            return {
+                status: "unsupported",
+                code: "architecture_unsupported",
+                reason: `REA's Hopper adapter does not admit ${target.architecture === "mips"
+                    ? "MIPS"
+                    : target.architecture === "riscv"
+                        ? "RISC-V"
+                        : "PowerPC"} targets.`,
+                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")
             return {
                 status: "unsupported",
@@ -163,10 +192,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" ||
@@ -180,33 +238,17 @@ export class HopperProvider {
                     ? await mapHopperFileOffset(target, result.value, options?.signal)
                     : result;
                 return mapped.ok
-                    ? {
-                        ok: true,
-                        value: createAnalysisExecution(mapped.value, executionProvider, {
-                            rawResult: 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

@@ -52,11 +52,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,

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/hopper/HopperTargetLease.js

@@ -1,21 +1,26 @@
 import { createHash } from "node:crypto";
-import { chmod, lstat, mkdir, realpath, rm, rmdir } from "node:fs/promises";
+import { chmod, mkdir, open, realpath, rm, rmdir } from "node:fs/promises";
+import { constants as fsConstants } from "node:fs";
 import { createConnection, createServer, } from "node:net";
-import { join, resolve } from "node:path";
+import { join } from "node:path";
 import { HopperStartError } from "../domain/hopperErrors.js";
 import { safeParseJson } from "../domain/safeJson.js";
 /** Shared private parent of Hopper lease sockets; it outlives individual sessions. */
 export const HOPPER_TARGET_LEASE_DIRECTORY = 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) => {
-    // 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));
+    // Canonicalization is required for lease identity. A lexical fallback could
+    // let two aliases reserve independent sockets for the same Hopper document.
+    let targetPath;
+    try {
+        targetPath = await realpath(input.targetPath);
+    }
+    catch (cause) {
+        throw new HopperStartError({
+            cause,
+            userMessage: `REA could not resolve Hopper target ${JSON.stringify(input.targetPath)} to a canonical path before reserving the document. Confirm that the target exists and its path is accessible.`,
+        });
+    }
     return acquireLease({
         ...input,
         identity: {
@@ -88,6 +93,10 @@ const reserveRecovery = async (recoveryPath) => {
 };
 const tryAcquireLease = async (socketPath, owner) => {
     const server = createServer((socket) => sendOwner(socket, owner));
+    // The lease lives exactly as long as its owning process. A lease retained
+    // after unconfirmed cleanup must not keep a completed one-shot command
+    // alive; process exit leaves a stale socket that later acquirers recover.
+    server.unref();
     if (!(await bind(server, socketPath))) {
         const existingOwner = await readOwner(socketPath);
         return typeof existingOwner === "string"
@@ -117,25 +126,63 @@ const tryAcquireLease = async (socketPath, owner) => {
     };
 };
 const ensureLeaseDirectory = async (directory) => {
-    let directoryStat;
     try {
         await mkdir(directory, { recursive: true, mode: 0o700 });
-        directoryStat = await lstat(directory);
     }
     catch (cause) {
         throw new HopperStartError({
             cause,
-            userMessage: "REA could not create or inspect its private Hopper lease directory.",
+            userMessage: "REA could not create its private Hopper lease directory.",
         });
     }
-    if (directoryStat.isSymbolicLink() ||
-        directoryStat.isDirectory() === false ||
-        (process.getuid !== undefined && directoryStat.uid !== process.getuid()))
+    // Use O_DIRECTORY|O_NOFOLLOW to open the directory without following symlinks,
+    // then inspect and secure that descriptor. Later socket operations still use
+    // the path and are not made atomic by this directory validation.
+    let handle;
+    try {
+        handle = await open(directory, fsConstants.O_RDONLY |
+            (fsConstants.O_DIRECTORY ?? 0) |
+            (fsConstants.O_NOFOLLOW ?? 0));
+        const directoryStat = await handle.stat();
+        if (directoryStat.isSymbolicLink() ||
+            directoryStat.isDirectory() === false ||
+            (process.getuid !== undefined && directoryStat.uid !== process.getuid()))
+            throw new HopperStartError({
+                userMessage: "REA's Hopper lease directory is not a private directory owned by this user.",
+            });
+        // POSIX permission hardening: chmod on the already-opened descriptor avoids
+        // a second TOCTOU window where the directory could be swapped between check
+        // and permission fix. Windows DACL-based security is handled separately.
+        const posixPermissionsApply = process.getuid !== undefined;
+        if (posixPermissionsApply && (directoryStat.mode & 0o077) !== 0) {
+            await handle.chmod(0o700);
+            // Re-verify permissions on the same opened directory.
+            const afterChmod = await handle.stat();
+            if (afterChmod.isSymbolicLink() ||
+                afterChmod.isDirectory() === false ||
+                (afterChmod.mode & 0o077) !== 0)
+                throw new HopperStartError({
+                    userMessage: "REA's Hopper lease directory permissions could not be secured.",
+                });
+        }
+    }
+    catch (cause) {
+        if (cause instanceof HopperStartError)
+            throw cause;
+        const accessDenied = process.getuid !== undefined &&
+            cause instanceof Error &&
+            "code" in cause &&
+            cause.code === "EACCES";
         throw new HopperStartError({
-            userMessage: "REA's Hopper lease directory is not a private directory owned by this user.",
+            cause,
+            userMessage: accessDenied
+                ? `REA could not access its Hopper lease directory at ${JSON.stringify(directory)}. Check its ownership and parent-directory access. For a directory you own, restore owner-only read, write, and search permissions (0700), then retry.`
+                : "REA could not inspect its private Hopper lease directory.",
         });
-    if ((directoryStat.mode & 0o077) !== 0)
-        await chmod(directory, 0o700);
+    }
+    finally {
+        await handle?.close();
+    }
 };
 const bind = (server, socketPath) => new Promise((resolveBind, reject) => {
     const onError = (error) => {

package/dist/ida/IdaBusyHealth.js

@@ -0,0 +1,44 @@
+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);
+    for (;;) {
+        const raw = await connection.call("server_health", { database });
+        const busy = busyHealthSchema.safeParse(raw);
+        if (!busy.success) {
+            if (isBusyStatus(raw))
+                throw busy.error;
+            return raw;
+        }
+        const expired = () => new AnalysisTimeoutError(`server_health: headless worker still busy in ${busyToolName(busy.data.busy_tool)}`, timeoutMs, { cause: raw });
+        if (remaining() <= 0)
+            throw expired();
+        await clock.delay(Math.min(BUSY_HEALTH_RETRY_MS, remaining()), signal);
+        signal?.throwIfAborted();
+        if (remaining() <= 0)
+            throw expired();
+    }
+};