rea-agents 6.0.0 → 6.2.0

package/dist/ghidra/GhidraProviderClient.js

@@ -1,11 +1,11 @@
+import { analysisErrorWithCleanupFailure } from "../application/binary/AnalysisClientCleanup.js";
 import { fileURLToPath } from "node:url";
 import { createAnalysisExecution, } from "../application/AnalysisProvider.js";
-import { AnalysisCancelledError, AnalysisCapabilityUnavailableError, AnalysisInputError, AnalysisTimeoutError, } from "../domain/analysisErrorCore.js";
+import { AnalysisCancelledError, AnalysisArtifactChangedError, AnalysisAccessDeniedError, AnalysisCapabilityUnavailableError, AnalysisInputError, AnalysisResourceConstraintError, AnalysisTimeoutError, } from "../domain/analysisErrorCore.js";
 import {} from "../domain/analysisErrorBase.js";
 import { ProviderAdapterError } from "../domain/providerAdapterError.js";
 import { err, ok } from "../domain/result.js";
 import { GhidraClient } from "./GhidraClient.js";
-import { GHIDRA_STARTUP_TIMEOUT_MS } from "./GhidraDefaults.js";
 import { isGhidraFunctionOperation, parseGhidraFunctionInput, parseGhidraFunctionResult, } from "./GhidraFunctionValues.js";
 import { isGhidraInventoryOperation, parseGhidraInventoryInput, parseGhidraInventoryResult, } from "./GhidraInventoryValues.js";
 import { ghidraInstallationDiagnostics, } from "./GhidraInstallation.js";
@@ -55,12 +55,12 @@ export const createGhidraProviderClient = (input) => {
             ]
             : [];
     const client = clientFactory({
+        startupTimeoutMs: config.ghidraStartupTimeoutMs,
         platform: installation.platform,
         launcher: new GhidraHeadlessLauncher({
+            environment: input.environment,
             analyzeHeadlessPath: prerequisites.value.analyzeHeadlessPath,
-            ...(config.ghidraJavaHome === undefined
-                ? {}
-                : { javaHome: config.ghidraJavaHome }),
+            javaHome: prerequisites.value.javaHome,
             bridgeScriptPath: fileURLToPath(new URL("../../bridge/ghidra/ReaGhidraBridge.java", import.meta.url)),
             ...(target.format === "dos-mz" ? { dosMz: true } : {}),
             ...(target.format === "dos-com" ? { dosCom: true } : {}),
@@ -89,8 +89,10 @@ export const createGhidraProviderClient = (input) => {
         extensionFailure = ghidraExtensionFailure(extensions, info.analysis_extensions ?? [], operation);
         if (extensionFailure === undefined)
             return undefined;
-        await client.close();
-        return extensionFailure;
+        const closed = await client.close();
+        return closed.ok
+            ? extensionFailure
+            : analysisErrorWithCleanupFailure(extensionFailure, closed.error, operation);
     };
     const releaseLimitation = unverifiedGhidraBuildLimitation(prerequisites.value.providerVersion);
     const sessionLimitations = [
@@ -110,7 +112,7 @@ export const createGhidraProviderClient = (input) => {
             if (operation === "health") {
                 const started = await client.start(options?.signal);
                 if (!started.ok)
-                    return err(projectSessionError(operation, started.error));
+                    return err(projectSessionError(operation, started.error, config.ghidraStartupTimeoutMs));
                 const failed = await checkExtensions(operation, started.value);
                 if (failed !== undefined)
                     return err(failed);
@@ -127,14 +129,14 @@ export const createGhidraProviderClient = (input) => {
             if (extensions.length > 0) {
                 const started = await client.start(options?.signal);
                 if (!started.ok)
-                    return err(projectSessionError(operation, started.error));
+                    return err(projectSessionError(operation, started.error, config.ghidraStartupTimeoutMs));
                 const failed = await checkExtensions(operation, started.value);
                 if (failed !== undefined)
                     return err(failed);
             }
             const called = await client.callTool(operation, input.value, options?.signal === undefined ? {} : { signal: options.signal });
             if (!called.ok)
-                return err(projectSessionError(operation, called.error));
+                return err(projectSessionError(operation, called.error, config.ghidraStartupTimeoutMs));
             const result = isGhidraFunctionOperation(operation)
                 ? parseGhidraFunctionResult(operation, called.value)
                 : parseGhidraInventoryResult(operation, called.value);
@@ -142,7 +144,7 @@ export const createGhidraProviderClient = (input) => {
                 return result;
             let normalized = result.value;
             if (operation === "inspect_native_load_image") {
-                const attested = await attestGhidraNativeLoadImage(target, operation, result.value, client, (failure) => projectSessionError(operation, failure));
+                const attested = await attestGhidraNativeLoadImage(target, operation, result.value, client, (failure) => projectSessionError(operation, failure, config.ghidraStartupTimeoutMs));
                 if (!attested.ok)
                     return attested;
                 normalized = attested.value;
@@ -176,15 +178,26 @@ const ghidraClientPrerequisites = (target, profile, installation) => {
         return err(new ProviderAdapterError("ghidra", "health"));
     return ok({
         analyzeHeadlessPath: installation.analyzeHeadlessPath,
+        javaHome: installation.javaHome,
         providerVersion: installation.providerVersion,
         profile,
     });
 };
 const unavailableClient = (failure) => ({
     execute: () => Promise.resolve(err(failure)),
-    close: () => Promise.resolve(),
+    close: () => Promise.resolve(ok(null)),
 });
-const projectSessionError = (operation, failure) => {
+const projectSessionError = (operation, failure, startupTimeoutMs) => {
+    const primary = projectPrimarySessionError(operation, failure, startupTimeoutMs);
+    return failure.cleanupFailure === undefined
+        ? primary
+        : analysisErrorWithCleanupFailure(primary, failure.cleanupFailure, operation);
+};
+const projectPrimarySessionError = (operation, failure, startupTimeoutMs) => {
+    if (failure.cause instanceof AnalysisAccessDeniedError)
+        return new AnalysisAccessDeniedError(operation, failure.cause.path, failure.cause.systemCode, { cause: failure });
+    if (failure.cause instanceof AnalysisArtifactChangedError)
+        return new AnalysisArtifactChangedError(operation, failure.cause.path, failure.cause.reason, { cause: failure });
     if (operation === "annotate_native_function" &&
         failure.kind === "remote" &&
         failure.remoteCode === "invalid_function_name")
@@ -194,12 +207,20 @@ const projectSessionError = (operation, failure) => {
     if (failure.kind === "cancelled")
         return new AnalysisCancelledError(operation);
     if (failure.kind === "timeout" || failure.kind === "analysis_timeout")
-        return new AnalysisTimeoutError(operation, failure.timeoutMs ?? GHIDRA_STARTUP_TIMEOUT_MS);
+        return new AnalysisTimeoutError(operation, failure.timeoutMs ?? startupTimeoutMs);
     if (failure.kind === "remote" && failure.remoteCode === "decompile_cancelled")
         return new AnalysisCancelledError(operation);
+    if (failure.kind === "remote" &&
+        failure.remoteCode === "regex_stack_exhausted")
+        return new AnalysisResourceConstraintError(operation, "memory", failure.message, null, {
+            cause: failure,
+            remediationAction: "Retry this search in literal mode or simplify the regex. The active analysis session and annotations remain available.",
+        });
     if (failure.kind === "remote" &&
         ["invalid_request", "not_found", "ambiguous"].includes(failure.remoteCode ?? ""))
-        return new AnalysisInputError(operation, { cause: failure });
+        return new AnalysisInputError(operation, { cause: failure }, [
+            { path: [], reason: "invalid_value", message: failure.message },
+        ]);
     if (failure.kind === "remote" && failure.remoteCode === "method_unavailable")
         return new AnalysisCapabilityUnavailableError("ghidra", operation, failure.message);
     return new ProviderAdapterError("ghidra", operation, {

package/dist/ghidra/GhidraSessionError.js

@@ -4,6 +4,7 @@ export class GhidraSessionError extends Error {
     diagnostics;
     timeoutMs;
     remoteCode;
+    cleanupFailure;
     constructor(kind, message, diagnostics = {}, options = {}) {
         super(message, options);
         this.kind = kind;
@@ -11,16 +12,21 @@ export class GhidraSessionError extends Error {
         this.diagnostics = structuredClone(diagnostics);
         this.timeoutMs = options.timeoutMs;
         this.remoteCode = options.remoteCode;
+        this.cleanupFailure = options.cleanupFailure;
     }
 }
 /** Build a session failure while preserving bounded remote failure metadata. */
-const createGhidraSessionError = (failure) => new GhidraSessionError(failure.kind, failure.message, failure.remoteCode === undefined
-    ? failure.diagnostics
-    : {
-        ...failure.diagnostics,
-        remote_code: failure.redact(failure.remoteCode),
-        remote_message: failure.message,
-    }, {
+const createGhidraSessionError = (failure) => new GhidraSessionError(failure.kind, failure.message, {
+    ...failure.diagnostics,
+    failure_kind: failure.kind,
+    failure_message: failure.message,
+    ...(failure.remoteCode === undefined
+        ? {}
+        : {
+            remote_code: failure.redact(failure.remoteCode),
+            remote_message: failure.message,
+        }),
+}, {
     ...(failure.cause === undefined ? {} : { cause: failure.cause }),
     ...(failure.timeoutMs === undefined
         ? {}

package/dist/ghidra/GhidraSessionRoot.js

@@ -0,0 +1,39 @@
+import { dirname, isAbsolute, resolve, sep } from "node:path";
+import { tmpdir } from "node:os";
+/** Session roots may not contain a dot-prefixed path element. */
+const hasDotPrefixElement = (directory) => resolve(directory)
+    .split(sep)
+    .some((element) => element.startsWith("."));
+/** Nearest ancestor of `directory`, inclusive, that has no dot-prefixed element. */
+const nearestSafeAncestor = (directory) => {
+    let current = resolve(directory);
+    for (;;) {
+        if (!hasDotPrefixElement(current))
+            return current;
+        const parent = dirname(current);
+        if (parent === current)
+            return undefined;
+        current = parent;
+    }
+};
+/**
+ * Select a session root usable as the parent of a Ghidra project path.
+ *
+ * Ghidra validates every project path element with `NamingUtilities.checkName`
+ * and aborts the headless analyzer on any element that starts with `.`, so an
+ * inherited `TMPDIR` such as `~/.cache/<tool>` fails every Ghidra operation
+ * with a generic analysis failure. Prefer the inherited base when it is usable,
+ * then a dot-free platform temp directory, then the nearest dot-free ancestor.
+ */
+export const ghidraSessionRoot = (options = {}) => {
+    const base = resolve(options.base ?? tmpdir());
+    if (!hasDotPrefixElement(base))
+        return base;
+    const platform = options.platform ?? process.platform;
+    const fallback = options.fallback ?? (platform === "win32" ? undefined : "/tmp");
+    if (fallback !== undefined &&
+        isAbsolute(fallback) &&
+        !hasDotPrefixElement(fallback))
+        return resolve(fallback);
+    return nearestSafeAncestor(base) ?? base;
+};

package/dist/ghidra/GhidraTargetSnapshot.js

@@ -1,7 +1,10 @@
 import { createHash } from "node:crypto";
-import { constants, createReadStream } from "node:fs";
-import { chmod, copyFile, rm } from "node:fs/promises";
+import { constants } from "node:fs";
+import { open, rm } from "node:fs/promises";
 import { extname, join } from "node:path";
+import { Transform } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { AnalysisArtifactChangedError, AnalysisAccessDeniedError, } from "../domain/analysisErrorCore.js";
 import { windowsPrivateRuntime } from "../windows/WindowsPrivateRuntime.js";
 /** Copy one target and require its bytes to match the parsed target identity. */
 export const createGhidraTargetSnapshot = async (sourcePath, runtimeRoot, expectedSha256, options = {}) => {
@@ -12,29 +15,61 @@ export const createGhidraTargetSnapshot = async (sourcePath, runtimeRoot, expect
     if ((options.platform ?? process.platform) === "win32") {
         const observed = await windowsPrivateRuntime(runtimeRoot).snapshot(sourcePath, `target-${expectedSha256.slice(0, 12)}${suffix}`, options.signal);
         if (observed.sha256 !== expectedSha256)
-            throw new Error(`Ghidra target snapshot digest mismatch: expected ${expectedSha256}, observed ${observed.sha256}`);
+            throw new AnalysisArtifactChangedError("open_binary", sourcePath, `Ghidra target snapshot digest mismatch: expected ${expectedSha256}, observed ${observed.sha256}`);
         return {
             path: snapshotPath,
             sha256: observed.sha256,
             admission: { source: observed.source, snapshot: observed.snapshot },
         };
     }
+    let source;
+    let destination;
     try {
-        await copyFile(sourcePath, snapshotPath, constants.COPYFILE_EXCL);
-        await chmod(snapshotPath, 0o600);
+        source = await openSnapshotSource(sourcePath);
+        if (!(await source.stat()).isFile())
+            throw new AnalysisArtifactChangedError("open_binary", sourcePath, "The selected Ghidra source is no longer a regular file");
+        destination = await open(snapshotPath, "wx", 0o600);
+        await destination.chmod(0o600);
         const hash = createHash("sha256");
-        for await (const chunk of createReadStream(snapshotPath))
-            hash.update(chunk);
+        const digest = new Transform({
+            transform(chunk, _encoding, done) {
+                if (!Buffer.isBuffer(chunk)) {
+                    done(new TypeError("Ghidra snapshot stream must contain bytes"));
+                    return;
+                }
+                hash.update(chunk);
+                done(null, chunk);
+            },
+        });
+        await pipeline(source.createReadStream(), digest, destination.createWriteStream(), options.signal === undefined ? {} : { signal: options.signal });
         const observedSha256 = hash.digest("hex");
         if (observedSha256 !== expectedSha256)
-            throw new Error(`Ghidra target snapshot digest mismatch: expected ${expectedSha256}, observed ${observedSha256}`);
+            throw new AnalysisArtifactChangedError("open_binary", sourcePath, `Ghidra target snapshot digest mismatch: expected ${expectedSha256}, observed ${observedSha256}`);
         return { path: snapshotPath, sha256: observedSha256 };
     }
     catch (cause) {
-        await rm(snapshotPath, { force: true }).catch((cause) => {
-            // best-effort cleanup: snapshot removal must not mask the copy failure.
-            void cause;
-        });
+        if (destination !== undefined)
+            await rm(snapshotPath, { force: true }).catch((cause) => {
+                // best-effort cleanup: snapshot removal must not mask the copy failure.
+                void cause;
+            });
+        throw cause;
+    }
+    finally {
+        await Promise.all([source?.close(), destination?.close()]);
+    }
+};
+const openSnapshotSource = async (path) => {
+    try {
+        // A path replaced by a FIFO must not block startup before its type is checked.
+        return await open(path, constants.O_RDONLY | constants.O_NONBLOCK);
+    }
+    catch (cause) {
+        const code = cause instanceof Error && "code" in cause ? cause.code : undefined;
+        if (code === "EACCES" || code === "EPERM")
+            throw new AnalysisAccessDeniedError("open_binary", path, code, { cause });
+        if (code === "ENOENT" || code === "ENOTDIR" || code === "ELOOP")
+            throw new AnalysisArtifactChangedError("open_binary", path, `The selected Ghidra source could not be opened (${code})`, { cause });
         throw cause;
     }
 };

package/dist/ghidra/GhidraTransport.js

@@ -1,7 +1,27 @@
 import { access, open } from "node:fs/promises";
+import { join } from "node:path";
+import { PrivateRuntimeRoot } from "../process/PrivateRuntimeRoot.js";
 import { readWindowsPrivateRuntimeFile } from "../windows/WindowsPrivateRuntime.js";
 import { err, ok } from "../domain/result.js";
 import { GhidraSessionError } from "./GhidraSessionError.js";
+/** Allocate an endpoint that fits the host's Unix sockaddr without moving the project. */
+export const createGhidraEndpoint = async (runtimeRoot, transport, platform) => {
+    const path = join(runtimeRoot, transport === "unix-socket" ? "bridge.sock" : "bridge-endpoint.json");
+    // sockaddr_un includes a terminating NUL: macOS has 104 bytes, Linux 108.
+    const maximumPathBytes = platform === "darwin" ? 103 : 107;
+    if (transport !== "unix-socket" ||
+        Buffer.byteLength(path, "utf8") <= maximumPathBytes)
+        return { endpoint: { transport, path } };
+    const socketRoot = await PrivateRuntimeRoot.create({
+        parent: "/tmp",
+        prefix: "rea-ghidra-socket-",
+        platform,
+    });
+    return {
+        endpoint: { transport, path: join(socketRoot.path, "s") },
+        socketRoot,
+    };
+};
 /** Observe a ready endpoint, returning null while its bridge is not listening. */
 export const observeGhidraEndpoint = async (endpoint) => {
     if (endpoint.transport === "unix-socket") {

package/dist/ghidra/extensions/GhidraExtensions.js

@@ -3,7 +3,7 @@ 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 { AnalysisCancelledError, AnalysisCapabilityUnavailableError, AnalysisUnsupportedTargetError, } from "../../domain/analysisErrorCore.js";
 import { ProviderAdapterError } from "../../domain/providerAdapterError.js";
 import { jsonObjectSchema } from "../../domain/jsonValue.js";
 import { err, ok } from "../../domain/result.js";
@@ -11,7 +11,7 @@ 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),
+    id: z.string().regex(/^[a-z][a-z0-9\x2d]*$/u),
     path: z.string().refine(isAbsolute, "Extension path must be absolute"),
     configured_path: z
         .string()
@@ -70,11 +70,9 @@ export const resolveGhidraExtensions = async (config, target, platform, signal)
         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 },
-            }));
+        const refusal = adapter.unsupportedReason(target, platform);
+        if (refusal !== null)
+            return err(extensionRefusalError(refusal, target));
         try {
             const path = await realpath(configured);
             const bytes = await readJar(path);
@@ -115,12 +113,21 @@ export const validateGhidraExtensionProfile = (extensions, config, target, platf
             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;
+        const refusal = adapter.unsupportedReason(target, platform);
+        if (refusal !== null)
+            return refusal.reason;
     }
     return null;
 };
+/**
+ * A deliberate host or target refusal is not an execution failure: retrying
+ * cannot change it, and its reason already names the remedy.
+ */
+const extensionRefusalError = (refusal, target) => refusal.constraint === "host"
+    ? new AnalysisCapabilityUnavailableError("ghidra", "resolve_analysis_profile", refusal.reason, { userMessage: refusal.reason })
+    : new AnalysisUnsupportedTargetError("resolve_analysis_profile", target.path, refusal.reason, 
+    // The reason names the workflows that remain available.
+    { remediationAction: refusal.reason });
 /** Snapshot committed extension bytes into the private runtime before Java loads them. */
 export const snapshotGhidraExtensions = async (extensions, runtimeRoot) => {
     if (extensions.length === 0)

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

@@ -5,11 +5,17 @@ export const nativeAotAdapter = {
     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."
+        ? {
+            constraint: "host",
+            reason: "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."
+            ? {
+                constraint: "target",
+                reason: "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: [

package/dist/hopper/BridgeLauncher.js

@@ -9,8 +9,8 @@ import { execFileOutput } from "../process/ExecFileOutput.js";
 import { spawnOwnedProviderProcess, } from "../process/ProviderProcess.js";
 import { waitForAbortableDelay } from "../process/ProviderDeadline.js";
 import { selectLinuxPrivateDisplayStrategy, } from "./LinuxPrivateDisplayProbe.js";
-import writeFileAtomic from "write-file-atomic";
-import { acquireHopperTargetLease } from "./HopperTargetLease.js";
+import { prepareHopperMachOImage, } from "./HopperMachOImage.js";
+import { acquireHopperTargetLease, acquireLinuxHopperApplicationLease, } from "./HopperTargetLease.js";
 const execFileAsync = promisify(execFile);
 const HOPPER_BACKGROUND_STARTUP_MS = 5_000;
 /**
@@ -35,20 +35,28 @@ export class HopperApplicationLauncher {
         this.dependencies = dependencies;
     }
     async launch(session, options = {}) {
-        const leaseResult = await this.#acquireTargetLease(session.runId);
+        const leaseResult = await this.#acquireLaunchLease(session.runId);
         if (!leaseResult.ok)
             return leaseResult;
         const lease = leaseResult.value;
         let leaseTransferred = false;
         try {
+            let loadedPath = this.options.targetPath;
+            if (this.options.preparedImage !== undefined) {
+                const prepared = await prepareHopperMachOImage(this.options.targetPath, this.options.preparedImage.sourceSha256, this.options.preparedImage.image, join(session.directory, "image.macho"), options.signal);
+                if (!prepared.ok)
+                    return prepared;
+                loadedPath = prepared.value;
+            }
             const ownsProcessLifetime = usesLinuxDemo(this.options);
-            const bootstrap = await this.#writeBootstrap(session, ownsProcessLifetime);
+            const bootstrap = await this.#writeBootstrap(session, ownsProcessLifetime, loadedPath);
             if (!bootstrap.ok)
                 return bootstrap;
             const launched = await this.#launchPreparedTarget({
                 session,
                 signal: options.signal,
                 bootstrapPath: bootstrap.value,
+                loadedPath,
                 ownsProcessLifetime,
                 lease,
             });
@@ -69,7 +77,7 @@ export class HopperApplicationLauncher {
             "-Y",
             bootstrapPath,
             action,
-            this.options.targetPath,
+            input.loadedPath,
         ];
         try {
             if (signal?.aborted === true)
@@ -77,7 +85,7 @@ export class HopperApplicationLauncher {
             const display = await this.#privateDisplay(signal);
             if (!display.ok)
                 return err(display.error);
-            const prepared = await prepareHopperApplication(this.options.launcherPath, signal);
+            const prepared = await prepareHopperApplication(this.options.launcherPath, this.options.environment, signal);
             if (!prepared)
                 return err(new HopperCancelledError());
             const linuxDemo = linuxDemoLaunch(this.options, session, argumentsForTarget, display.strategy);
@@ -92,62 +100,69 @@ export class HopperApplicationLauncher {
             });
             if (started === null)
                 return err(new HopperCancelledError());
-            const cleanup = () => cleanupOwnedProcessGroup(started.ownership).finally(() => lease?.release());
-            const ownership = {
-                run_id: session.runId,
-                pid: started.ownership.leaderPid,
-                process_group_id: started.ownership.leaderPid,
-                parent_pid: process.pid,
-                launcher: linuxDemo?.command ?? this.options.launcherPath,
-                created_at: new Date().toISOString(),
-            };
-            try {
-                await writeFileAtomic(join(session.directory, "ownership.json"), `${JSON.stringify(ownership)}\n`, { encoding: "utf8", mode: 0o600 });
-            }
-            catch (cause) {
-                await cleanupOwnedProcessGroup(started.ownership);
-                return err(new HopperStartError({ cause }));
-            }
-            return ok({
+            const cleanup = () => cleanupOwnedProcessGroup(started.ownership);
+            const ownedLauncher = {
+                ...(this.options.preparedImage === undefined
+                    ? {}
+                    : { preparedImagePath: input.loadedPath }),
                 process: started.process,
                 ownsProcessLifetime: true,
                 ownership: started.ownership,
-                shutdownMode: ownsProcessLifetime
-                    ? "process-cleanup"
-                    : "bridge-request",
                 cleanup,
-            });
+                launcherCommand: linuxDemo?.command ?? this.options.launcherPath,
+                ...(lease === undefined ? {} : { releaseLease: () => lease.release() }),
+            };
+            return ownsProcessLifetime
+                ? ok({
+                    ...ownedLauncher,
+                    providerLifetime: "launcher-process",
+                    shutdownMode: "process-cleanup",
+                })
+                : ok({
+                    ...ownedLauncher,
+                    providerLifetime: "external-application",
+                    shutdownMode: "bridge-request",
+                });
         }
         catch (cause) {
             return err(hopperLaunchFailure(cause, signal));
         }
     }
-    async #acquireTargetLease(runId) {
-        if ((this.dependencies.platform ?? process.platform) !== "darwin")
+    async #acquireLaunchLease(runId) {
+        const platform = this.dependencies.platform ?? process.platform;
+        const applicationLease = platform === "linux" && usesLinuxDemo(this.options);
+        if (!applicationLease && platform !== "darwin")
             return ok(undefined);
         try {
-            const acquisition = await (this.dependencies.acquireTargetLease ?? acquireHopperTargetLease)({
-                targetPath: this.options.targetPath,
-                targetKind: this.options.targetKind,
-                loaderArgs: this.options.loaderArgs,
-                runId,
-            });
+            const acquisition = applicationLease
+                ? await (this.dependencies.acquireApplicationLease ??
+                    acquireLinuxHopperApplicationLease)({ runId })
+                : await (this.dependencies.acquireTargetLease ?? acquireHopperTargetLease)({
+                    targetPath: this.options.targetPath,
+                    targetKind: this.options.targetKind,
+                    loaderArgs: this.options.loaderArgs,
+                    runId,
+                });
             if (!acquisition.acquired)
                 return err(new HopperStartError({
                     ownerRunId: acquisition.owner.runId,
-                    userMessage: `This Hopper target is already open in REA session ${acquisition.owner.runId}. ` +
-                        "Use that REA session or close it before opening this target again.",
+                    userMessage: applicationLease
+                        ? `Linux Hopper is already active in REA session ${acquisition.owner.runId}; it cannot open ${this.options.targetPath} in another session. This build forwards new launches to the existing application. Use the owning REA session to switch targets, or close it before retrying.`
+                        : `This Hopper target is already open in REA session ${acquisition.owner.runId}. ` +
+                            "Use that REA session or close it before opening this target again.",
                 }));
             return ok(acquisition.lease);
         }
         catch (cause) {
-            return err(new HopperStartError({ cause }));
+            return err(cause instanceof HopperStartError
+                ? cause
+                : new HopperStartError({ cause }));
         }
     }
-    async #writeBootstrap(session, ownsProcessLifetime) {
+    async #writeBootstrap(session, ownsProcessLifetime, loadedPath) {
         const bootstrapPath = `${session.directory}/bootstrap.py`;
         try {
-            await writeFile(bootstrapPath, bridgeBootstrapSource(session, this.options, ownsProcessLifetime), { encoding: "utf8", mode: 0o600 });
+            await writeFile(bootstrapPath, bridgeBootstrapSource(session, this.options, ownsProcessLifetime, loadedPath), { encoding: "utf8", mode: 0o600 });
             await chmod(bootstrapPath, 0o600);
             return ok(bootstrapPath);
         }
@@ -161,6 +176,7 @@ export class HopperApplicationLauncher {
         const selection = await (this.dependencies.selectPrivateDisplay ??
             selectLinuxPrivateDisplayStrategy)({
             helperPath: this.options.demoHelperPath,
+            environment: this.options.environment,
             ...(signal === undefined ? {} : { signal }),
         });
         if (signal?.aborted === true)
@@ -173,11 +189,11 @@ export class HopperApplicationLauncher {
             };
     }
 }
-const bridgeBootstrapSource = (session, options, ownsProcessLifetime) => [
+const bridgeBootstrapSource = (session, options, ownsProcessLifetime, loadedPath) => [
     `REA_SOCKET = ${JSON.stringify(session.socketPath)}`,
     `REA_TOKEN = ${JSON.stringify(session.token)}`,
     `REA_RUN_ID = ${JSON.stringify(session.runId)}`,
-    `REA_TARGET_PATH = ${JSON.stringify(options.targetPath)}`,
+    `REA_TARGET_PATH = ${JSON.stringify(loadedPath)}`,
     `REA_OWNS_PROCESS_LIFETIME = ${ownsProcessLifetime ? "True" : "False"}`,
     `exec(compile(open(${JSON.stringify(options.bridgeScriptPath)}, 'rb').read(), ${JSON.stringify(options.bridgeScriptPath)}, 'exec'))`,
     "",
@@ -189,6 +205,7 @@ const launchHopperProcess = async (input) => {
         arguments: arguments_,
         runId: input.session.runId,
         expectedCommand: ownershipCommand,
+        hostEnvironment: input.options.environment,
         ...(input.signal === undefined ? {} : { signal: input.signal }),
     });
     if (input.linuxDemo !== undefined)
@@ -197,6 +214,7 @@ const launchHopperProcess = async (input) => {
             arguments: input.linuxDemo.args,
             runId: input.session.runId,
             expectedCommand: ownershipCommand,
+            hostEnvironment: input.options.environment,
             ...(input.signal === undefined ? {} : { signal: input.signal }),
         });
     return spawn(input.argumentsForTarget);
@@ -242,21 +260,16 @@ const hopperLaunchFailure = (cause, signal) => signal?.aborted === true
     : new HopperStartError({ cause });
 /** Select the version-pinned adapter from the caller's explicit launch mode. */
 export const usesLinuxDemo = (options) => options.launchMode === "verified_linux_demo";
-const prepareHopperApplication = async (launcherPath, signal) => {
+const prepareHopperApplication = async (launcherPath, environment, signal) => {
     const appBundle = hopperApplicationBundle(launcherPath);
     if (appBundle === undefined)
         return signal?.aborted !== true;
     const executablePath = join(appBundle, "Contents/MacOS/Hopper Disassembler");
-    if (await processIsRunning(executablePath))
+    if (await processIsRunning(executablePath, environment))
         return signal?.aborted !== true;
     // This reduces activation when Hopper is cold, but the vendor launcher that
     // follows may still activate its window. See HopperApplicationLauncher.
-    await execFileAsync("/usr/bin/open", [
-        "--hide",
-        "--background",
-        "-a",
-        appBundle,
-    ]);
+    await execFileAsync("/usr/bin/open", ["--hide", "--background", "-a", appBundle], { env: environment });
     return ((await waitForAbortableDelay(HOPPER_BACKGROUND_STARTUP_MS, signal)) ===
         "elapsed");
 };
@@ -266,13 +279,9 @@ const hopperApplicationBundle = (launcherPath) => {
     const candidate = dirname(dirname(dirname(launcherPath)));
     return extname(candidate) === ".app" ? candidate : undefined;
 };
-const processIsRunning = async (executablePath) => {
+const processIsRunning = async (executablePath, environment) => {
     try {
-        const processes = await execFileOutput("/bin/ps", [
-            "-ax",
-            "-o",
-            "command=",
-        ]);
+        const processes = await execFileOutput("/bin/ps", ["-ax", "-o", "command="], { env: environment });
         return processes.stdout
             .split("\n")
             .some((command) => command.trim() === executablePath);