rea-agents 6.0.0 → 6.1.0

package/dist/ghidra/GhidraProviderClient.js

@@ -1,11 +1,10 @@
 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 +54,11 @@ export const createGhidraProviderClient = (input) => {
             ]
             : [];
     const client = clientFactory({
+        startupTimeoutMs: config.ghidraStartupTimeoutMs,
         platform: installation.platform,
         launcher: new GhidraHeadlessLauncher({
             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 } : {}),
@@ -110,7 +108,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 +125,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 +140,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,6 +174,7 @@ const ghidraClientPrerequisites = (target, profile, installation) => {
         return err(new ProviderAdapterError("ghidra", "health"));
     return ok({
         analyzeHeadlessPath: installation.analyzeHeadlessPath,
+        javaHome: installation.javaHome,
         providerVersion: installation.providerVersion,
         profile,
     });
@@ -184,7 +183,11 @@ const unavailableClient = (failure) => ({
     execute: () => Promise.resolve(err(failure)),
     close: () => Promise.resolve(),
 });
-const projectSessionError = (operation, failure) => {
+const projectSessionError = (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 +197,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

@@ -14,13 +14,17 @@ export class GhidraSessionError extends Error {
     }
 }
 /** 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/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/hopper/BridgeLauncher.js

@@ -10,6 +10,7 @@ import { spawnOwnedProviderProcess, } from "../process/ProviderProcess.js";
 import { waitForAbortableDelay } from "../process/ProviderDeadline.js";
 import { selectLinuxPrivateDisplayStrategy, } from "./LinuxPrivateDisplayProbe.js";
 import writeFileAtomic from "write-file-atomic";
+import { prepareHopperMachOImage, } from "./HopperMachOImage.js";
 import { acquireHopperTargetLease } from "./HopperTargetLease.js";
 const execFileAsync = promisify(execFile);
 const HOPPER_BACKGROUND_STARTUP_MS = 5_000;
@@ -41,14 +42,22 @@ export class HopperApplicationLauncher {
         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 +78,7 @@ export class HopperApplicationLauncher {
             "-Y",
             bootstrapPath,
             action,
-            this.options.targetPath,
+            input.loadedPath,
         ];
         try {
             if (signal?.aborted === true)
@@ -108,15 +117,26 @@ export class HopperApplicationLauncher {
                 await cleanupOwnedProcessGroup(started.ownership);
                 return err(new HopperStartError({ cause }));
             }
-            return ok({
+            const ownedLauncher = {
+                ...(this.options.preparedImage === undefined
+                    ? {}
+                    : { preparedImagePath: input.loadedPath }),
                 process: started.process,
                 ownsProcessLifetime: true,
                 ownership: started.ownership,
-                shutdownMode: ownsProcessLifetime
-                    ? "process-cleanup"
-                    : "bridge-request",
                 cleanup,
-            });
+            };
+            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));
@@ -144,10 +164,10 @@ export class HopperApplicationLauncher {
             return err(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);
         }
@@ -173,11 +193,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'))`,
     "",

package/dist/hopper/HopperAnalysisProfile.js

@@ -1,15 +1,37 @@
 import { createHash } from "node:crypto";
 import { createReadStream } from "node:fs";
 import { createAnalysisProfile } from "../domain/analysisProfile.js";
-import { AnalysisCancelledError } from "../domain/analysisErrorCore.js";
+import { AnalysisCancelledError, AnalysisCapabilityUnavailableError, } from "../domain/analysisErrorCore.js";
+import { BinaryTargetError } from "../domain/configurationErrors.js";
 import { ProviderAdapterError } from "../domain/providerAdapterError.js";
 import {} from "../domain/analysisErrorBase.js";
 import { err, ok } from "../domain/result.js";
+import { resolveHopperMachOImage, } from "./HopperMachOImage.js";
 /** Resolve Hopper open semantics without placing its CLI flags in BinaryTarget. */
 export const resolveHopperAnalysisProfile = async (target, options) => {
     if (target.kind !== "executable" && target.kind !== "database")
         return ok({ profile: null, compatibility: {} });
-    const derived = hopperLoaderArgsForTarget(target);
+    let machoContainer;
+    if (target.kind === "executable" && target.format === "mach-o") {
+        const header = await readMachoMagic(target.path, options.signal);
+        if (!header.ok)
+            return header;
+        machoContainer = [0xcafebabf, 0xbfbafeca].includes(header.value)
+            ? "fat64"
+            : [0xcafebabe, 0xbebafeca].includes(header.value)
+                ? "fat32"
+                : "thin";
+    }
+    let preparedImage;
+    if (target.kind === "executable" &&
+        machoContainer === "fat64" &&
+        options.loaderArgsOverride.length === 0) {
+        const resolved = await resolveHopperMachOImage(target, options.signal);
+        if (!resolved.ok)
+            return resolved;
+        preparedImage = resolved.value;
+    }
+    const derived = hopperLoaderArgsForTarget(target, preparedImage === undefined ? machoContainer : "thin");
     if (!derived.ok)
         return derived;
     const loaderArgs = options.loaderArgsOverride.length === 0
@@ -34,6 +56,12 @@ export const resolveHopperAnalysisProfile = async (target, options) => {
             available_architectures: [
                 ...(target.availableArchitectures ?? []),
             ].sort(),
+            ...(machoContainer === undefined
+                ? {}
+                : { macho_container: machoContainer }),
+            ...(preparedImage === undefined
+                ? {}
+                : { prepared_image: { ...preparedImage } }),
             loader: {
                 source: options.loaderArgsOverride.length === 0
                     ? "derived"
@@ -48,7 +76,7 @@ export const resolveHopperAnalysisProfile = async (target, options) => {
     });
 };
 /** Derive Hopper's complete non-interactive CLI loader selection. */
-export const hopperLoaderArgsForTarget = (target) => {
+export const hopperLoaderArgsForTarget = (target, machoContainer) => {
     if (target.kind === "database")
         return ok([]);
     if (target.kind !== "executable")
@@ -57,7 +85,9 @@ export const hopperLoaderArgsForTarget = (target) => {
     const flag = hopperArchitectureFlag(architecture);
     switch (target.format) {
         case "mach-o":
-            return ok((target.availableArchitectures?.length ?? 0) > 1
+            if (machoContainer === undefined)
+                return err(new AnalysisCapabilityUnavailableError("hopper", "resolve_analysis_profile", "Mach-O container kind is unknown; resolve the Hopper analysis profile before starting its client."));
+            return ok(machoContainer === "fat32" || machoContainer === "fat64"
                 ? ["-l", "FAT", flag, "-l", "Mach-O"]
                 : ["-l", "Mach-O", flag]);
         case "elf":
@@ -81,6 +111,34 @@ const hopperArchitectureFlag = (architecture) => {
             return "--aarch64";
     }
 };
+const readMachoMagic = async (path, signal) => {
+    if (signalIsAborted(signal))
+        return err(new AnalysisCancelledError("open_binary"));
+    const stream = createReadStream(path, { start: 0, end: 3 });
+    const onAbort = () => {
+        stream.destroy();
+    };
+    signal?.addEventListener("abort", onAbort, { once: true });
+    try {
+        const chunks = [];
+        for await (const chunk of stream)
+            chunks.push(Buffer.from(chunk));
+        if (signalIsAborted(signal))
+            return err(new AnalysisCancelledError("open_binary"));
+        const bytes = Buffer.concat(chunks);
+        return bytes.length === 4
+            ? ok(bytes.readUInt32BE(0))
+            : err(new BinaryTargetError(path, "Mach-O header became truncated before Hopper loader selection"));
+    }
+    catch (cause) {
+        return signalIsAborted(signal)
+            ? err(new AnalysisCancelledError("open_binary"))
+            : err(new BinaryTargetError(path, `Cannot read the Mach-O container header: ${cause instanceof Error ? cause.message : String(cause)}`, { cause }));
+    }
+    finally {
+        signal?.removeEventListener("abort", onAbort);
+    }
+};
 const sha256File = async (path, signal) => {
     if (signalIsAborted(signal))
         return err(new AnalysisCancelledError("open_binary"));

package/dist/hopper/HopperCleanup.js

@@ -11,7 +11,7 @@ export const cleanupHopperSession = async (input) => {
         cleanupResult: undefined,
         shutdownConfirmed: false,
     };
-    await report(input.progress, 0, input.retainDocument
+    await report(input.progress, 0, input.retainDocument && input.launch?.preparedImagePath === undefined
         ? "detaching REA from the Hopper document"
         : "requesting Hopper document shutdown");
     await requestShutdown(input, state);
@@ -20,7 +20,18 @@ export const cleanupHopperSession = async (input) => {
     await stopProcess(input, state);
     recordUnconfirmedDocument(input, state);
     await report(input.progress, 0.75, "removing Hopper private runtime files");
-    await closeRuntimeRoot(input.runtimeRoot, state);
+    if (input.launch?.preparedImagePath !== undefined &&
+        !state.shutdownConfirmed) {
+        const resource = input.runtimeRoot?.path ?? input.launch.preparedImagePath;
+        state.resources.add(resource);
+        state.issues.push({
+            resource,
+            reason: "Prepared image retained because native document closure was not confirmed",
+        });
+    }
+    else {
+        await closeRuntimeRoot(input.runtimeRoot, state);
+    }
     return cleanupOutcome(input, state);
 };
 const requestShutdown = async (input, state) => {
@@ -34,7 +45,8 @@ const requestShutdown = async (input, state) => {
             }, "Hopper shutdown skipped because a bridge operation remained active");
         return;
     }
-    const method = input.retainDocument || input.launch?.shutdownMode === "process-cleanup"
+    const method = (input.retainDocument && input.launch?.preparedImagePath === undefined) ||
+        input.launch?.shutdownMode === "process-cleanup"
         ? "shutdown"
         : "shutdown_document";
     const shutdown = await input