rea-agents 4.0.0 → 4.1.0

package/dist/firmware/FirmwareCommand.js

@@ -0,0 +1,163 @@
+import { randomUUID } from "node:crypto";
+import { access, realpath, stat } from "node:fs/promises";
+import { constants } from "node:fs";
+import { isAbsolute } from "node:path";
+import { AnalysisCapabilityUnavailableError, AnalysisCancelledError, AnalysisTimeoutError, AnalysisOutputError, } from "../domain/analysisErrorCore.js";
+import { ProviderAdapterError } from "../domain/providerAdapterError.js";
+import { ProviderCleanupError } from "../domain/providerCleanupError.js";
+import { spawnOwnedProviderProcess, ProviderProcessSupervisor, } from "../process/ProviderProcess.js";
+import { cleanupOwnedProcessGroup } from "../process/ProcessOwnership.js";
+import { FIRMWARE_LIMITS } from "./FirmwareRelease.js";
+import { hashFirmwareFile, inventoryFirmwareOutput, readFirmwareReport, } from "./FirmwareFiles.js";
+/** Resolve explicitly supplied executable paths; never install or search for engines. */
+export const resolveFirmwareCommand = async (environment, engine, operation) => {
+    const variable = engine === "binwalk" ? "REA_BINWALK_COMMAND" : "REA_UNBLOB_COMMAND";
+    const configured = environment[variable];
+    if (process.platform !== "linux" ||
+        configured === undefined ||
+        !isAbsolute(configured))
+        throw new AnalysisCapabilityUnavailableError(engine, operation, `This integration requires Linux and an absolute ${variable} path to the caller-supplied tool`);
+    const command = await realpath(configured).catch((cause) => {
+        throw new AnalysisCapabilityUnavailableError(engine, operation, `${variable} is unavailable: ${cause instanceof Error ? cause.message : String(cause)}`);
+    });
+    let sha256;
+    try {
+        await access(command, constants.R_OK | constants.X_OK);
+        if (!(await stat(command)).isFile())
+            throw new TypeError("Configured path is not a regular file");
+        sha256 = await hashFirmwareFile(command);
+    }
+    catch (cause) {
+        throw new AnalysisCapabilityUnavailableError(engine, operation, `${variable} is not a readable executable regular file: ${command}: ${cause instanceof Error ? cause.message : String(cause)}`);
+    }
+    const limiter = environment.REA_FIRMWARE_PRLIMIT_COMMAND ?? "/usr/bin/prlimit";
+    if (!isAbsolute(limiter))
+        throw new AnalysisCapabilityUnavailableError(engine, operation, "REA_FIRMWARE_PRLIMIT_COMMAND must be absolute");
+    try {
+        await access(limiter, constants.X_OK);
+        if (!(await stat(limiter)).isFile())
+            throw new TypeError("Configured path is not a regular file");
+    }
+    catch (cause) {
+        throw new AnalysisCapabilityUnavailableError(engine, operation, `Resource limiter is not an executable regular file: ${limiter}: ${cause instanceof Error ? cause.message : String(cause)}; provide util-linux prlimit`);
+    }
+    return { command, limiter, sha256 };
+};
+/** Execute one bounded provider command and verify its owned descendants have stopped. */
+export const runFirmwareCommand = async (context) => {
+    const { engine, operation, signal } = context;
+    signal.throwIfAborted();
+    const runId = `rea-firmware-${randomUUID()}`;
+    const spawned = await (context.launcher ?? spawnOwnedProviderProcess)({
+        command: context.limiter,
+        arguments: [
+            `--as=${FIRMWARE_LIMITS.addressSpaceBytes}`,
+            `--fsize=${context.outputBudget?.bytes ?? FIRMWARE_LIMITS.reportBytes}`,
+            "--core=0",
+            "--cpu=120",
+            "--",
+            context.command,
+            ...context.args,
+        ],
+        expectedCommand: null,
+        runId,
+        cwd: context.cwd,
+        hostEnvironment: context.environment,
+        env: {
+            TMPDIR: context.cwd,
+            OMP_NUM_THREADS: "1",
+            OPENBLAS_NUM_THREADS: "1",
+            RAYON_NUM_THREADS: "1",
+            NO_COLOR: "1",
+        },
+    });
+    const supervisor = new ProviderProcessSupervisor({
+        ...spawned,
+        ownsProcessLifetime: true,
+        cleanup: spawned.cleanup ?? (() => cleanupOwnedProcessGroup(spawned.ownership)),
+    });
+    let failure;
+    try {
+        const deadline = Date.now() + FIRMWARE_LIMITS.timeoutMs;
+        while (!(await supervisor.waitForExit(100))) {
+            if (signal.aborted)
+                throw new AnalysisCancelledError(operation);
+            if (Date.now() >= deadline)
+                throw new AnalysisTimeoutError(operation, FIRMWARE_LIMITS.timeoutMs);
+            if (context.outputBudget !== undefined)
+                await inventoryFirmwareOutput(context.outputBudget.root, context.outputBudget.bytes, context.outputBudget.entries, operation, signal);
+        }
+        if (signal.aborted)
+            throw new AnalysisCancelledError(operation);
+    }
+    catch (cause) {
+        failure = cause;
+    }
+    const stopped = await supervisor.stop();
+    const snapshot = supervisor.snapshot();
+    supervisor.dispose();
+    if (stopped.status === "incomplete")
+        throw new ProviderCleanupError(engine, [runId, context.cwd], {
+            reason: stopped.reason,
+            leader_pid: spawned.ownership.leaderPid,
+            process_group_id: spawned.ownership.processGroupId,
+            exit_code: snapshot.exitCode ?? null,
+            signal: snapshot.signal ?? null,
+            stdout: snapshot.stdout.text,
+            stderr: snapshot.stderr.text,
+            stdout_bytes: snapshot.stdout.bytes,
+            stderr_bytes: snapshot.stderr.bytes,
+            previous_error: failure instanceof Error ? failure.message : null,
+        });
+    if (failure !== undefined)
+        throw failure;
+    if (snapshot.exitCode !== 0 &&
+        !(context.acceptReportedExtractionFailure === true &&
+            snapshot.exitCode === 1))
+        throw new ProviderAdapterError(engine, operation, {
+            diagnostics: {
+                reason: "Tool failed; inspect exit status and stderr for format, dependency, sandbox or resource-limit failures",
+                exit_code: snapshot.exitCode ?? null,
+                signal: snapshot.signal ?? null,
+                stdout: snapshot.stdout.text,
+                stderr: snapshot.stderr.text,
+                stdout_bytes: snapshot.stdout.bytes,
+                stderr_bytes: snapshot.stderr.bytes,
+            },
+        });
+    return {
+        stdout: snapshot.stdout,
+        stderr: snapshot.stderr,
+        exit_code: snapshot.exitCode,
+        signal: snapshot.signal ?? null,
+        command: context.command,
+        args: [...context.args],
+        resource_limiter: context.limiter,
+    };
+};
+/** Preserve tool failure diagnostics when an accepted exit 1 has no usable report. */
+export const readFirmwareCommandReport = async (context) => {
+    try {
+        return await readFirmwareReport(context.path, context.operation);
+    }
+    catch (cause) {
+        if (context.execution.exit_code === 1)
+            throw new ProviderAdapterError(context.engine, context.operation, {
+                cause,
+                diagnostics: {
+                    reason: "Tool exited 1 without a usable analysis report; inspect stderr for startup, sandbox or dependency failures",
+                    report_failure: cause instanceof Error ? cause.message : String(cause),
+                    exit_code: 1,
+                    signal: context.execution.signal,
+                    stdout: context.execution.stdout.text,
+                    stderr: context.execution.stderr.text,
+                    stdout_bytes: context.execution.stdout.bytes,
+                    stderr_bytes: context.execution.stderr.bytes,
+                },
+            });
+        const diagnostics = `stdout (${context.execution.stdout.bytes} bytes): ${context.execution.stdout.text}; stderr (${context.execution.stderr.bytes} bytes): ${context.execution.stderr.text}`;
+        if (cause instanceof AnalysisOutputError)
+            throw new AnalysisOutputError(context.operation, `${cause.reason}; ${diagnostics}`, { cause });
+        throw new AnalysisOutputError(context.operation, `Tool did not produce the expected complete report: ${context.path}; ${diagnostics}`, { cause });
+    }
+};

package/dist/firmware/FirmwareFiles.js

@@ -0,0 +1,190 @@
+import { createHash } from "node:crypto";
+import { constants, createReadStream, createWriteStream } from "node:fs";
+import { chmod, lstat, open, readdir, readlink, realpath, } from "node:fs/promises";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
+import { Transform } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { AnalysisCancelledError, AnalysisInputError, AnalysisOutputError, } from "../domain/analysisErrorCore.js";
+import { readBoundedFileBytes } from "../process/BoundedFileBytes.js";
+import { FIRMWARE_LIMITS } from "./FirmwareRelease.js";
+/** Hash a regular tool or extracted file without retaining its bytes in memory. */
+export const hashFirmwareFile = async (path, signal) => {
+    const handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+    const hash = createHash("sha256");
+    try {
+        if (!(await handle.stat()).isFile())
+            throw new Error(`Not a regular file: ${path}`);
+        for await (const chunk of handle.createReadStream({ autoClose: false })) {
+            signal?.throwIfAborted();
+            hash.update(chunk);
+        }
+    }
+    finally {
+        await handle.close();
+    }
+    return hash.digest("hex");
+};
+/** Copy and identify the exact bytes consumed by firmware providers. */
+export const snapshotFirmware = async (request, root, signal) => {
+    const sourcePath = resolve(request.input.path);
+    const source = await realpath(sourcePath);
+    const handle = await open(source, constants.O_RDONLY | constants.O_NOFOLLOW);
+    const fullPath = join(root, "firmware.bin");
+    const hash = createHash("sha256");
+    let size = 0;
+    try {
+        const stat = await handle.stat();
+        if (!stat.isFile() ||
+            stat.size === 0 ||
+            stat.size > FIRMWARE_LIMITS.inputBytes)
+            throw new AnalysisInputError(request.operation, undefined, [
+                {
+                    path: ["path"],
+                    reason: "out_of_range",
+                    message: `Firmware must be a nonempty regular file no larger than ${FIRMWARE_LIMITS.inputBytes} bytes`,
+                },
+            ]);
+        const meter = new Transform({
+            transform(chunk, _encoding, callback) {
+                size += chunk.length;
+                if (size > FIRMWARE_LIMITS.inputBytes) {
+                    callback(new Error("Firmware grew beyond the input byte budget"));
+                    return;
+                }
+                hash.update(chunk);
+                callback(null, chunk);
+            },
+        });
+        await pipeline(handle.createReadStream({ autoClose: false }), meter, createWriteStream(fullPath, { flags: "wx", mode: 0o600 }), { signal });
+    }
+    finally {
+        await handle.close();
+    }
+    await chmod(fullPath, 0o400);
+    const sha256 = hash.digest("hex");
+    const selected = request.operation === "extract_firmware" ? request.input.range : undefined;
+    const offset = selected?.offset ?? 0;
+    const length = selected?.length ?? size;
+    if (length === 0 || offset > size || length > size - offset)
+        throw new AnalysisInputError(request.operation, undefined, [
+            {
+                path: ["range"],
+                reason: "out_of_range",
+                message: `Selected range must be within the ${size}-byte firmware file`,
+            },
+        ]);
+    let inputPath = fullPath;
+    if (selected !== undefined) {
+        inputPath = join(root, "selected.bin");
+        await pipeline(createReadStream(fullPath, { start: offset, end: offset + length - 1 }), createWriteStream(inputPath, { flags: "wx", mode: 0o600 }), { signal });
+        await chmod(inputPath, 0o400);
+    }
+    return {
+        subject: { path: sourcePath, sha256, format: "file" },
+        size,
+        inputPath,
+        selection: {
+            offset,
+            length,
+            sha256: selected === undefined
+                ? sha256
+                : await hashFirmwareFile(inputPath, signal),
+        },
+    };
+};
+/** Read a complete bounded report; oversized data is never reported as complete. */
+export const readFirmwareReport = async (path, operation) => {
+    const handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+        if (!(await handle.stat()).isFile())
+            throw new AnalysisOutputError(operation, "Report is not a regular file");
+        const bytes = await readBoundedFileBytes(handle, FIRMWARE_LIMITS.reportBytes);
+        if (bytes === undefined)
+            throw new AnalysisOutputError(operation, `Report exceeded ${FIRMWARE_LIMITS.reportBytes} bytes`);
+        try {
+            const value = JSON.parse(bytes.toString("utf8"));
+            return value;
+        }
+        catch (cause) {
+            throw new AnalysisOutputError(operation, "Tool report is not valid complete JSON", { cause });
+        }
+    }
+    finally {
+        await handle.close();
+    }
+};
+/** Inventory private output without following links, enforcing aggregate staging budgets. */
+export const inventoryFirmwareOutput = async (root, maxBytes, maxEntries, operation, signal) => {
+    const entries = [];
+    const pending = [root];
+    let bytes = 0;
+    let count = 0;
+    while (pending.length > 0) {
+        if (signal?.aborted === true)
+            throw new AnalysisCancelledError(operation);
+        const directory = pending.pop();
+        if (directory === undefined)
+            break;
+        const directoryStat = await lstat(directory).catch((cause) => {
+            if (cause instanceof Error && "code" in cause && cause.code === "ENOENT")
+                return undefined;
+            throw cause;
+        });
+        if (directoryStat === undefined ||
+            !directoryStat.isDirectory() ||
+            directoryStat.isSymbolicLink())
+            continue;
+        const names = await readdir(directory).catch((cause) => {
+            if (cause instanceof Error && "code" in cause && cause.code === "ENOENT")
+                return [];
+            throw cause;
+        });
+        for (const name of names.sort()) {
+            count++;
+            if (count > maxEntries)
+                throw new AnalysisOutputError(operation, `Staging entry budget exceeded (${maxEntries})`);
+            const path = join(directory, name);
+            const stat = await lstat(path).catch((cause) => {
+                if (cause instanceof Error &&
+                    "code" in cause &&
+                    cause.code === "ENOENT")
+                    return undefined;
+                throw cause;
+            });
+            if (stat === undefined)
+                continue;
+            if (stat.isDirectory()) {
+                pending.push(path);
+                continue;
+            }
+            if (stat.isFile())
+                bytes += stat.size;
+            if (bytes > maxBytes)
+                throw new AnalysisOutputError(operation, `Staging byte budget exceeded (${maxBytes})`);
+            entries.push({
+                path,
+                relativePath: relative(root, path).split(sep).join("/"),
+                size: stat.size,
+                kind: stat.isSymbolicLink()
+                    ? "symlink"
+                    : stat.isFile()
+                        ? "file"
+                        : "special",
+                linkTarget: stat.isSymbolicLink() ? await readlink(path) : null,
+            });
+        }
+    }
+    return entries.sort((a, b) => a.relativePath.localeCompare(b.relativePath));
+};
+/** Bind producer paths to the selected input or private extraction tree. */
+export const firmwareLogicalPath = (path, inputPath, outputRoot) => {
+    if (path === inputPath)
+        return "$input";
+    const rel = relative(outputRoot, path);
+    if (!isAbsolute(path) ||
+        rel === ".." ||
+        rel.startsWith(`..${sep}`) ||
+        isAbsolute(rel))
+        throw new AnalysisOutputError("extract_firmware", `Provider reported a path outside its owned output: ${path}`);
+    return rel === "" ? "$output" : `$output/${rel.split(sep).join("/")}`;
+};

package/dist/firmware/FirmwareProvider.js

@@ -0,0 +1,258 @@
+import { join, isAbsolute } from "node:path";
+import { z } from "zod";
+import { createAnalysisExecution, } from "../application/AnalysisProvider.js";
+import { firmwareResultSchemas, } from "../domain/firmwareAnalysis.js";
+import { AnalysisError } from "../domain/analysisErrorBase.js";
+import { AnalysisCancelledError, AnalysisCapabilityUnavailableError, AnalysisInputError, AnalysisOutputError, AnalysisTimeoutError, } from "../domain/analysisErrorCore.js";
+import { ProviderAdapterError } from "../domain/providerAdapterError.js";
+import { ProviderCleanupError } from "../domain/providerCleanupError.js";
+import { err, ok } from "../domain/result.js";
+import { PrivateRuntimeRoot } from "../process/PrivateRuntimeRoot.js";
+import { publishFirmwareExtraction } from "./FirmwarePublication.js";
+import { FIRMWARE_LIMITS, FIRMWARE_RELEASES, BINWALK_PROVIDER_IDENTITY, UNBLOB_PROVIDER_IDENTITY, } from "./FirmwareRelease.js";
+import { resolveFirmwareCommand, runFirmwareCommand, readFirmwareCommandReport, } from "./FirmwareCommand.js";
+import { inventoryFirmwareOutput, snapshotFirmware } from "./FirmwareFiles.js";
+import { normalizeBinwalkReport, normalizeUnblobReport, } from "./FirmwareReports.js";
+const waitForPredecessor = (predecessor, operation, signal) => new Promise((resolve, reject) => {
+    const abort = () => reject(new AnalysisCancelledError(operation));
+    signal?.addEventListener("abort", abort, { once: true });
+    if (signal?.aborted === true)
+        abort();
+    void predecessor.then(() => {
+        signal?.removeEventListener("abort", abort);
+        resolve();
+    });
+});
+const limitations = [
+    "Signature matches and reported sizes do not establish partition validity, encryption or runtime mappings. Binwalk may infer unknown lengths before emitting its report.",
+    "Only Linux is supported by this integration. One worker, inherited per-process address-space/file-size/CPU limits and a deadline constrain execution; staging byte and entry budgets are polled and may transiently overshoot. Limits are not aggregate process-memory or filesystem quotas.",
+    "Unblob's default sandbox and skip rules remain enabled. Missing external extractors, unknown chunks, encrypted chunks and depth limits yield partial coverage. Extracted code is never executed; only regular files are published, without executable permission bits.",
+    "The actual launcher executable is hashed. Interpreter, shared libraries and installed Python package dependencies are not independently attested; source revision remains unknown for caller-supplied builds.",
+];
+/** Queued bring-your-own firmware adapters with private snapshots and owned cleanup. */
+export class FirmwareProvider {
+    environment;
+    launcher;
+    #tail = Promise.resolve();
+    #cleanupFailure;
+    constructor(environment = process.env, launcher) {
+        this.environment = environment;
+        this.launcher = launcher;
+    }
+    /** Inspect regions or explicitly extract selected bytes without changing the source. */
+    async execute(request, options) {
+        const predecessor = this.#tail;
+        let release = () => { };
+        this.#tail = new Promise((resolve) => {
+            release = resolve;
+        });
+        // Cancel the caller promptly without letting a later request bypass its predecessor.
+        try {
+            await waitForPredecessor(predecessor, request.operation, options?.signal);
+        }
+        catch (cause) {
+            void predecessor.then(release);
+            return err(cause instanceof AnalysisError
+                ? cause
+                : new AnalysisCancelledError(request.operation));
+        }
+        try {
+            return await this.#execute(request, options);
+        }
+        finally {
+            release();
+        }
+    }
+    async #execute(request, options) {
+        let root;
+        const engineName = request.operation === "inspect_firmware_regions" ? "binwalk" : "unblob";
+        const deadline = AbortSignal.timeout(FIRMWARE_LIMITS.timeoutMs);
+        const signal = options?.signal === undefined
+            ? deadline
+            : AbortSignal.any([options.signal, deadline]);
+        let outcome;
+        try {
+            if (this.#cleanupFailure !== undefined)
+                return err(this.#cleanupFailure);
+            if (signal.aborted)
+                throw new AnalysisCancelledError(request.operation);
+            const command = await resolveFirmwareCommand(this.environment, engineName, request.operation);
+            root = await PrivateRuntimeRoot.create({ prefix: "rea-firmware-" });
+            const target = await snapshotFirmware(request, root.path, signal);
+            const run = (args, outputBudget) => runFirmwareCommand({
+                engine: engineName,
+                operation: request.operation,
+                ...command,
+                args,
+                cwd: root?.path ?? "",
+                environment: this.environment,
+                signal,
+                ...(this.launcher === undefined ? {} : { launcher: this.launcher }),
+                ...(outputBudget === undefined
+                    ? {}
+                    : { outputBudget, acceptReportedExtractionFailure: true }),
+            });
+            const versionRun = await run(["--version"]);
+            const version = versionRun.stdout.text.trim();
+            const expected = FIRMWARE_RELEASES[engineName].version;
+            if (versionRun.stdout.bytes > 1024 ||
+                (engineName === "binwalk"
+                    ? version !== `binwalk ${expected}`
+                    : version !== expected))
+                throw new AnalysisCapabilityUnavailableError(engineName, request.operation, `Unsupported tool version ${version}; this adapter is verified against ${expected}`);
+            const engine = {
+                name: engineName,
+                version: expected,
+                executable_path: command.command,
+                executable_sha256: command.sha256,
+                source_revision: null,
+                worker_count: 1,
+            };
+            const reportPath = join(root.path, "report.json");
+            let result;
+            let raw;
+            if (request.operation === "inspect_firmware_regions") {
+                const processRun = await run([
+                    "--quiet",
+                    "--search-all",
+                    "--threads",
+                    "1",
+                    "--log",
+                    reportPath,
+                    target.inputPath,
+                ]);
+                const report = await readFirmwareCommandReport({
+                    path: reportPath,
+                    engine: engineName,
+                    operation: request.operation,
+                    execution: processRun,
+                });
+                result = firmwareResultSchemas.inspect_firmware_regions.parse({
+                    engine,
+                    input_size: target.size,
+                    regions: normalizeBinwalkReport(report, target.inputPath, target.size),
+                    coverage: "signature_scan",
+                });
+                raw = { report, execution: processRun, version_execution: versionRun };
+            }
+            else {
+                if (!isAbsolute(request.input.output_directory))
+                    throw new AnalysisInputError(request.operation, undefined, [
+                        {
+                            path: ["output_directory"],
+                            reason: "invalid_format",
+                            message: "Extraction output directory must be absolute",
+                        },
+                    ]);
+                const outputRoot = join(root.path, "extracted");
+                const processRun = await run([
+                    "--process-num",
+                    "1",
+                    "--depth",
+                    String(request.input.max_depth),
+                    "--randomness-depth",
+                    "0",
+                    "--report",
+                    reportPath,
+                    "--log",
+                    join(root.path, "unblob.log"),
+                    "--extract-dir",
+                    outputRoot,
+                    target.inputPath,
+                ], {
+                    root: outputRoot,
+                    bytes: request.input.max_output_bytes,
+                    entries: request.input.max_output_files,
+                });
+                const report = await readFirmwareCommandReport({
+                    path: reportPath,
+                    engine: engineName,
+                    operation: request.operation,
+                    execution: processRun,
+                });
+                const normalized = normalizeUnblobReport(report, {
+                    inputPath: target.inputPath,
+                    outputRoot,
+                    ...target.selection,
+                    maxDepth: request.input.max_depth,
+                });
+                if (processRun.exit_code === 1 && normalized.diagnostics.length === 0)
+                    throw new AnalysisOutputError(request.operation, "Unblob failed without a reported extraction diagnostic");
+                const entries = await inventoryFirmwareOutput(outputRoot, request.input.max_output_bytes, request.input.max_output_files, request.operation, signal);
+                result = await publishFirmwareExtraction({
+                    outputDirectory: request.input.output_directory,
+                    entries,
+                    normalized,
+                    selection: target.selection,
+                    engine,
+                    signal,
+                });
+                raw = { report, execution: processRun, version_execution: versionRun };
+            }
+            outcome = ok(createAnalysisExecution(result, engineName === "binwalk"
+                ? BINWALK_PROVIDER_IDENTITY
+                : UNBLOB_PROVIDER_IDENTITY, {
+                subject: target.subject,
+                rawResult: raw,
+                limitations,
+                locations: [
+                    {
+                        kind: "file-offset-range",
+                        start: target.selection.offset,
+                        end: target.selection.offset + target.selection.length,
+                    },
+                ],
+            }));
+        }
+        catch (cause) {
+            outcome = err(cause instanceof ProviderCleanupError
+                ? cause
+                : options?.signal?.aborted === true
+                    ? new AnalysisCancelledError(request.operation)
+                    : deadline.aborted
+                        ? new AnalysisTimeoutError(request.operation, FIRMWARE_LIMITS.timeoutMs)
+                        : cause instanceof AnalysisError
+                            ? cause
+                            : cause instanceof z.ZodError
+                                ? new AnalysisOutputError(request.operation, "Tool report violated the pinned producer protocol", { cause })
+                                : new ProviderAdapterError(engineName, request.operation, {
+                                    cause,
+                                    diagnostics: {
+                                        reason: cause instanceof Error
+                                            ? cause.message
+                                            : String(cause),
+                                    },
+                                }));
+            if (!outcome.ok && outcome.error.cleanupIncomplete) {
+                this.#cleanupFailure =
+                    root === undefined ||
+                        outcome.error.cleanupResources.includes(root.path)
+                        ? outcome.error
+                        : new ProviderCleanupError(engineName, [...outcome.error.cleanupResources, root.path], outcome.error instanceof ProviderAdapterError
+                            ? (outcome.error.diagnostics ?? {
+                                reason: outcome.error.message,
+                            })
+                            : { reason: outcome.error.message }, { cause: outcome.error });
+            }
+        }
+        // Never remove a workspace while process ownership remains uncertain.
+        if (this.#cleanupFailure !== undefined)
+            return err(this.#cleanupFailure);
+        try {
+            await root?.close();
+        }
+        catch (cause) {
+            this.#cleanupFailure = new ProviderCleanupError(engineName, [
+                root?.path ?? "unknown",
+                ...(outcome.ok && request.operation === "extract_firmware"
+                    ? [request.input.output_directory]
+                    : []),
+            ], {
+                reason: cause instanceof Error ? cause.message : String(cause),
+                previous_result: outcome.ok ? outcome.value.result : null,
+            });
+            return err(this.#cleanupFailure);
+        }
+        return outcome;
+    }
+}