rea-agents 4.0.1 → 5.0.0

package/dist/dotnet/ManagedArtifactInspector.js

@@ -1,4 +1,4 @@
-import { managedArtifactInspectionSchema, } from "../domain/managedArtifact.js";
+import { managedArtifactInspectionSchema, } from "../domain/managed/managedArtifact.js";
 import { readManagedPeLayout, } from "./ManagedPeReader.js";
 import { managedTableRowCounts, readManagedMetadataInventory, } from "./ManagedMetadataInventory.js";
 import { readManagedMetadataLayout, } from "./ManagedMetadataLayout.js";

package/dist/dotnet/ManagedMemberInspector.js

@@ -1,4 +1,4 @@
-import { managedMemberInspectionSchema, } from "../domain/managedArtifact.js";
+import { managedMemberInspectionSchema, } from "../domain/managed/managedArtifact.js";
 import { readManagedPeLayout, } from "./ManagedPeReader.js";
 import { managedTableRowCounts, readManagedMetadataInventory, } from "./ManagedMetadataInventory.js";
 import { readManagedMetadataLayout } from "./ManagedMetadataLayout.js";

package/dist/dotnet/ManagedMemberInspectorCore.js

@@ -58,6 +58,40 @@ export const declaringType = (ranges, table, row) => {
     }
     return null;
 };
+/** Resolve member ownership without rescanning ordered type ranges per row. */
+export const createDeclaringTypeLookup = (ranges, table) => {
+    const entries = ranges.map((range) => ({
+        range,
+        start: table === "field" ? range.fieldStart : range.methodStart,
+        end: table === "field" ? range.fieldEnd : range.methodEnd,
+    }));
+    const ordered = entries.every((entry, index) => {
+        const previous = entries[index - 1];
+        return (entry.start <= entry.end &&
+            (previous === undefined || previous.end <= entry.start));
+    });
+    // Malformed metadata can overlap or reverse ranges. Retain the original
+    // first-match interpretation rather than guessing a different owner.
+    if (!ordered)
+        return (row) => declaringType(ranges, table, row);
+    return (row) => {
+        let first = 0;
+        let end = entries.length;
+        while (first < end) {
+            const middle = first + Math.floor((end - first) / 2);
+            const entry = entries[middle];
+            if (entry === undefined)
+                return null;
+            if (row >= entry.start && row < entry.end)
+                return { token: entry.range.token, fullName: entry.range.fullName };
+            if (row < entry.start)
+                end = middle;
+            else
+                first = middle + 1;
+        }
+        return null;
+    };
+};
 export const parseTypes = (bytes, layout, ranges) => {
     const typeTable = layout.table(2);
     const fields = layout.table(4);

package/dist/dotnet/ManagedMemberRows.js

@@ -1,16 +1,17 @@
-import { declaringType, signature, } from "./ManagedMemberInspectorCore.js";
+import { createDeclaringTypeLookup, signature, } from "./ManagedMemberInspectorCore.js";
 import { metadataToken, metadataRowCursor, metadataCodedToken, readMetadataBlob, readMetadataString, } from "./ManagedMetadataHeaps.js";
 import { methodBody } from "./ManagedMethodBodyReader.js";
 export const parseFields = (bytes, layout, ranges) => {
     const fields = [];
     const core = new Map();
     const table = layout.table(4);
+    const declaringType = createDeclaringTypeLookup(ranges, "field");
     for (let row = 1; row <= (table?.rowCount ?? 0); row += 1) {
         const cursor = metadataRowCursor(bytes, layout, 4, row);
         const flags = cursor.readUInt16();
         const name = readMetadataString(bytes, layout, cursor.readIndex(layout.stringIndexSize), layout.strings.size);
         const sig = readMetadataBlob(bytes, layout, cursor.readIndex(layout.blobIndexSize), layout.blob.size);
-        const declared = declaringType(ranges, "field", row);
+        const declared = declaringType(row);
         const token = metadataToken(4, row);
         fields.push({
             token,
@@ -50,6 +51,7 @@ export const parseMethods = ({ bytes, layout, pe, ranges, }) => {
     const methods = [];
     const core = new Map();
     const table = layout.table(6);
+    const declaringType = createDeclaringTypeLookup(ranges, "method");
     for (let row = 1; row <= (table?.rowCount ?? 0); row += 1) {
         const cursor = metadataRowCursor(bytes, layout, 6, row);
         const rva = cursor.readUInt32();
@@ -58,7 +60,7 @@ export const parseMethods = ({ bytes, layout, pe, ranges, }) => {
         const name = readMetadataString(bytes, layout, cursor.readIndex(layout.stringIndexSize), layout.strings.size);
         const sig = readMetadataBlob(bytes, layout, cursor.readIndex(layout.blobIndexSize), layout.blob.size);
         cursor.readIndex(layout.tableIndexSize(8));
-        const declared = declaringType(ranges, "method", row);
+        const declared = declaringType(row);
         const token = metadataToken(6, row);
         methods.push({
             token,
@@ -70,7 +72,7 @@ export const parseMethods = ({ bytes, layout, pe, ranges, }) => {
             impl_flags: implFlags,
             flags,
             signature: signature(sig),
-            body: methodBody(bytes, pe, rva),
+            body: methodBody(bytes, pe, rva, { implFlags, flags }),
         });
         core.set(token, { token, name, declaringType: declared?.fullName ?? null });
     }

package/dist/dotnet/ManagedMetadataHeaps.js

@@ -80,9 +80,10 @@ export const readMetadataString = (bytes, layout, index, heapExtent) => {
     if (end === maximum)
         throw managedFailure("invalid-string", "metadata.#Strings", "String heap item has no terminator within #Strings", start);
     try {
-        return new TextDecoder("utf-8", { fatal: true }).decode(bytes.subarray(start, end));
+        return new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes.subarray(start, end));
     }
-    catch {
+    catch (cause) {
+        void cause;
         throw managedFailure("invalid-string", "metadata.#Strings", "String heap item is not valid UTF-8", start);
     }
 };

package/dist/dotnet/ManagedMetadataInventoryRows.js

@@ -201,9 +201,11 @@ const decodeFixedString = (blob) => {
     if (start > blob.length - length.length)
         return null;
     try {
-        return new TextDecoder("utf-8", { fatal: true }).decode(blob.subarray(start, start + length.length));
+        return new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(blob.subarray(start, start + length.length));
     }
-    catch {
+    catch (cause) {
+        // Invalid UTF-8 blobs decode as null.
+        void cause;
         return null;
     }
 };

package/dist/dotnet/ManagedMethodBodyReader.js

@@ -38,9 +38,16 @@ const readMethodBodyHeader = (bytes, offset) => {
         localSig: bytes.readUInt32LE(offset + 8),
     };
 };
-export const methodBody = (bytes, pe, rva) => {
+/** Decode admitted managed CIL, retaining unavailable implementation metadata as partial. */
+export const methodBody = (bytes, pe, rva, implementation = {
+    implFlags: 0,
+    flags: 0,
+}) => {
     if (rva === 0)
         return emptyMethodBody(rva, "absent", null);
+    if ((implementation.implFlags & 7) !== 0 ||
+        (implementation.flags & 0x2000) !== 0)
+        return emptyMethodBody(rva, "partial", "CIL decoding is unavailable for native, runtime, unmanaged, or P/Invoke implementations");
     try {
         const offset = pe.rvaToOffset(rva, 1, "method.body");
         const header = readMethodBodyHeader(bytes, offset);

package/dist/dotnet/ManagedNativeBoundaryHelpers.js

@@ -1,4 +1,4 @@
-import { managedNativeBoundaryInspectionSchema, } from "../domain/managedArtifact.js";
+import { managedNativeBoundaryInspectionSchema, } from "../domain/managed/managedArtifact.js";
 import {} from "./ManagedMetadataLayout.js";
 import { metadataRowCursor, metadataCodedToken, metadataToken, readMetadataString, } from "./ManagedMetadataHeaps.js";
 import { managedTableRowCounts } from "./ManagedMetadataInventory.js";
@@ -217,17 +217,19 @@ const boundaryKind = (pinvokeDeclared, codeType, managedKind) => {
         return "unmanaged-method";
     return "mixed-or-unknown";
 };
+/** CLI header facets of a PE without an admitted CLI header. */
+export const NO_CLI_NATIVE = {
+    il_only: false,
+    requires_32bit: false,
+    strong_name_signed: false,
+    native_entry_point: false,
+    ready_to_run_signature: false,
+    managed_native_header_rva: 0,
+    managed_native_header_size: 0,
+};
 export const cliNative = (pe) => {
     if (pe.cli === null)
-        return {
-            il_only: false,
-            requires_32bit: false,
-            strong_name_signed: false,
-            native_entry_point: false,
-            ready_to_run_signature: false,
-            managed_native_header_rva: 0,
-            managed_native_header_size: 0,
-        };
+        return NO_CLI_NATIVE;
     return {
         il_only: (pe.cli.flags & 0x0000_0001) !== 0,
         requires_32bit: (pe.cli.flags & 0x0000_0002) !== 0,
@@ -238,6 +240,14 @@ export const cliNative = (pe) => {
         managed_native_header_size: pe.cli.managedNativeHeader.size,
     };
 };
+/** Summarize declaration counts with the native facets of the CLI header. */
+export const nativeBoundarySummary = (native, counts) => ({
+    ...counts,
+    ready_to_run: native.ready_to_run_signature,
+    mixed_mode_or_native_header: native.managed_native_header_rva !== 0 ||
+        native.managed_native_header_size !== 0 ||
+        native.native_entry_point,
+});
 export const buildNativeBoundaryInspection = ({ target, bytes, layout, inventory, moduleRefs, imports, implementations, native, issues, }) => managedNativeBoundaryInspectionSchema.parse({
     artifact: {
         path: target.path,
@@ -260,15 +270,11 @@ export const buildNativeBoundaryInspection = ({ target, bytes, layout, inventory
     module_refs: moduleRefs,
     pinvoke_imports: imports,
     native_implementations: implementations,
-    summary: {
+    summary: nativeBoundarySummary(native, {
         module_ref_count: moduleRefs.length,
         pinvoke_import_count: imports.length,
         native_implementation_count: implementations.length,
-        ready_to_run: native.ready_to_run_signature,
-        mixed_mode_or_native_header: native.managed_native_header_rva !== 0 ||
-            native.managed_native_header_size !== 0 ||
-            native.native_entry_point,
-    },
+    }),
     coverage: {
         state: issues.length === 0 ? "complete" : "partial",
         issues,

package/dist/dotnet/ManagedNativeBoundaryInspector.js

@@ -1,54 +1,55 @@
-import { managedNativeBoundaryInspectionSchema, } from "../domain/managedArtifact.js";
+import { managedNativeBoundaryInspectionSchema, } from "../domain/managed/managedArtifact.js";
 import { readManagedMetadataInventory, } from "./ManagedMetadataInventory.js";
 import { readManagedMetadataLayout, } from "./ManagedMetadataLayout.js";
 import { readManagedPeLayout, } from "./ManagedPeReader.js";
 import { ManagedReaderFailure } from "./ManagedReaderFailure.js";
-import { buildNativeBoundaryInspection, cliNative, nativeImplementations, parseFields, parseImplMaps, parseMethods, parseModuleRefs, } from "./ManagedNativeBoundaryHelpers.js";
-const emptyInspection = (target, bytes, classification, issues = []) => managedNativeBoundaryInspectionSchema.parse({
-    artifact: {
-        path: target.path,
-        sha256: target.sha256,
-        byte_length: bytes.length,
-        format: "pe",
-    },
-    module: null,
-    metadata: {
-        status: classification === "malformed" || classification === "not-available"
-            ? "malformed"
-            : "absent",
-        version: null,
-        table_row_counts: {},
-    },
-    identity_scope: {
-        token_identity: "build-local",
-        requires_artifact_sha256: target.sha256,
-        requires_mvid: null,
-    },
-    cli_native: {
-        il_only: false,
-        requires_32bit: false,
-        strong_name_signed: false,
-        native_entry_point: false,
-        ready_to_run_signature: false,
-        managed_native_header_rva: 0,
-        managed_native_header_size: 0,
-    },
-    module_refs: [],
-    pinvoke_imports: [],
-    native_implementations: [],
-    summary: {
-        module_ref_count: 0,
-        pinvoke_import_count: 0,
-        native_implementation_count: 0,
-        ready_to_run: false,
-        mixed_mode_or_native_header: false,
-    },
-    coverage: { state: classification, issues },
-    limitations: [
-        "No CLI data was admitted; native boundary declarations are unavailable.",
-        "Static inspection does not load or execute target code, so native export resolution is not performed.",
-    ],
-});
+import { buildNativeBoundaryInspection, cliNative, NO_CLI_NATIVE, nativeBoundarySummary, nativeImplementations, parseFields, parseImplMaps, parseMethods, parseModuleRefs, } from "./ManagedNativeBoundaryHelpers.js";
+/**
+ * Report a PE whose CLI metadata is absent or cannot be admitted. `native`
+ * holds the CLI header facts when the header itself was admitted; otherwise
+ * the header is absent (`not-managed`) or unreadable (`malformed`).
+ */
+const emptyInspection = (target, bytes, classification, { native = null, issues = [], } = {}) => {
+    const header = native ?? NO_CLI_NATIVE;
+    return managedNativeBoundaryInspectionSchema.parse({
+        artifact: {
+            path: target.path,
+            sha256: target.sha256,
+            byte_length: bytes.length,
+            format: "pe",
+        },
+        module: null,
+        metadata: {
+            status: classification === "malformed" ? "malformed" : "absent",
+            version: null,
+            table_row_counts: {},
+        },
+        identity_scope: {
+            token_identity: "build-local",
+            requires_artifact_sha256: target.sha256,
+            requires_mvid: null,
+        },
+        cli_native: header,
+        module_refs: [],
+        pinvoke_imports: [],
+        native_implementations: [],
+        summary: nativeBoundarySummary(header, {
+            module_ref_count: 0,
+            pinvoke_import_count: 0,
+            native_implementation_count: 0,
+        }),
+        coverage: { state: "unavailable", issues },
+        limitations: [
+            "No CLI metadata was admitted; native boundary declarations are unavailable.",
+            ...(native === null && classification === "malformed"
+                ? [
+                    "The CLI header was not admitted, so cli_native and the summary's ready_to_run and mixed_mode_or_native_header values are defaults, not observations.",
+                ]
+                : []),
+            "Static inspection does not load or execute target code, so native export resolution is not performed.",
+        ],
+    });
+};
 const readBoundaryInventory = (bytes, pe, cli) => {
     const metadataOffset = pe.rvaToOffset(cli.metadata.rva, cli.metadata.size, "cli.metadata");
     const layout = readManagedMetadataLayout(bytes, metadataOffset, cli.metadata.size);
@@ -68,10 +69,12 @@ export const inspectManagedNativeBoundariesBytes = (bytes, target) => {
     catch (cause) {
         if (!(cause instanceof ManagedReaderFailure))
             throw cause;
-        return emptyInspection(target, bytes, "malformed", [cause.issue]);
+        return emptyInspection(target, bytes, "malformed", {
+            issues: [cause.issue],
+        });
     }
     if (pe.cli === null)
-        return emptyInspection(target, bytes, pe.cliDirectoryPresent ? "malformed" : "not-managed", pe.cliIssue === null ? [] : [pe.cliIssue]);
+        return emptyInspection(target, bytes, pe.cliDirectoryPresent ? "malformed" : "not-managed", { issues: pe.cliIssue === null ? [] : [pe.cliIssue] });
     let layout;
     let inventory;
     try {
@@ -80,7 +83,10 @@ export const inspectManagedNativeBoundariesBytes = (bytes, target) => {
     catch (cause) {
         if (!(cause instanceof ManagedReaderFailure))
             throw cause;
-        return emptyInspection(target, bytes, "malformed", [cause.issue]);
+        return emptyInspection(target, bytes, "malformed", {
+            native: cliNative(pe),
+            issues: [cause.issue],
+        });
     }
     const heapExtent = Math.max(layout.strings.size, layout.blob.size);
     const moduleRefs = parseModuleRefs(bytes, layout, heapExtent);

package/dist/dotnet/ManagedStaticProvider.js

@@ -2,32 +2,18 @@ import { createHash } from "node:crypto";
 import { createReadStream } from "node:fs";
 import { readFile } from "node:fs/promises";
 import { createAnalysisExecution, } from "../application/AnalysisProvider.js";
-import { MANAGED_STATIC_PROVIDER } from "../application/InvestigationProviders.js";
-import { MANAGED_TOOL_CONTRACTS, managedArtifactInputSchema, managedMemberInputSchema, managedNativeBoundaryInputSchema, } from "../contracts/managedToolContracts.js";
-import { AnalysisCancelledError, AnalysisCapabilityUnavailableError, EvidenceIntegrityError, ProviderAdapterError, } from "../domain/errors.js";
+import { MANAGED_STATIC_PROVIDER_IDENTITY as IDENTITY, managedStaticCapabilities, } from "./ManagedStaticProviderMetadata.js";
+import { MANAGED_TOOL_CONTRACTS, managedArtifactInputSchema, managedMemberInputSchema, managedNativeBoundaryInputSchema, } from "../contracts/managed/managedToolContracts.js";
+import { AnalysisCancelledError, AnalysisCapabilityUnavailableError, } from "../domain/analysisErrorCore.js";
+import { EvidenceIntegrityError } from "../domain/evidenceErrors.js";
+import { ProviderAdapterError } from "../domain/providerAdapterError.js";
 import { err, ok } from "../domain/result.js";
 import { inspectManagedArtifactBytes } from "./ManagedArtifactInspector.js";
 import { inspectManagedMembersBytes } from "./ManagedMemberInspector.js";
 import { inspectManagedNativeBoundariesBytes } from "./ManagedNativeBoundaryInspector.js";
-const IDENTITY = Object.freeze(MANAGED_STATIC_PROVIDER);
 /** Execution-free managed PE/CLI auxiliary provider. */
 export class ManagedStaticProvider {
-    #capabilities = Object.freeze(MANAGED_TOOL_CONTRACTS.map((contract) => Object.freeze({
-        provider: IDENTITY,
-        operation: contract.name,
-        available: true,
-        reason: null,
-        effects: Object.freeze({
-            mutatesArtifact: false,
-            launchesProcess: false,
-            mayShowUi: false,
-            mayAccessNetwork: false,
-            mayWriteFilesystem: false,
-            changesPermissions: false,
-            requiresRoot: false,
-        }),
-        limitations: limitationsFor(contract.name),
-    })));
+    #capabilities = managedStaticCapabilities();
     identity() {
         return IDENTITY;
     }
@@ -106,20 +92,6 @@ const hashManagedSource = async (path, signal) => {
     return { byteLength, sha256: digest.digest("hex") };
 };
 const isManagedOperation = (operation) => MANAGED_TOOL_CONTRACTS.some(({ name }) => name === operation);
-const limitationsFor = (operation) => Object.freeze(operation === "inspect_managed_artifact"
-    ? [
-        "This capability inventories PE/CLI identity only; inspect_managed_members admits metadata members, signatures, and CIL anchors.",
-        "It never loads the target assembly, resolves dependencies through a CLR, decompiles C#, or executes target code.",
-    ]
-    : operation === "inspect_managed_native_boundaries"
-        ? [
-            "This capability inventories managed declarations for native boundaries only; native exports, thunks, and addresses require separate native-provider evidence.",
-            "It never loads the target assembly, resolves dependencies through a CLR, decompiles C#, or executes target code.",
-        ]
-        : [
-            "This capability decodes PE/CLI metadata members, signatures, and file-backed method bodies; decompiled C# reconstruction and cross-build member comparison are separate operations.",
-            "It never loads the target assembly, resolves dependencies through a CLR, decompiles C#, or executes target code.",
-        ]);
 const inspectManagedOperation = (operation, parameters, bytes, target) => {
     if (operation === "inspect_managed_artifact") {
         managedArtifactInputSchema.parse(parameters);

package/dist/dotnet/ManagedStaticProviderMetadata.js

@@ -0,0 +1,36 @@
+import { MANAGED_STATIC_PROVIDER } from "../application/InvestigationProviders.js";
+import { MANAGED_TOOL_CONTRACTS, } from "../contracts/managed/managedToolContracts.js";
+/** Identity of execution-free managed metadata observations. */
+export const MANAGED_STATIC_PROVIDER_IDENTITY = Object.freeze(MANAGED_STATIC_PROVIDER);
+const IDENTITY = MANAGED_STATIC_PROVIDER_IDENTITY;
+/** Declare managed metadata coverage without opening or loading an assembly. */
+export const managedStaticCapabilities = () => Object.freeze(MANAGED_TOOL_CONTRACTS.map((contract) => Object.freeze({
+    provider: IDENTITY,
+    operation: contract.name,
+    available: true,
+    reason: null,
+    effects: Object.freeze({
+        mutatesArtifact: false,
+        launchesProcess: false,
+        mayShowUi: false,
+        mayAccessNetwork: false,
+        mayWriteFilesystem: false,
+        changesPermissions: false,
+        requiresRoot: false,
+    }),
+    limitations: limitationsFor(contract.name),
+})));
+const limitationsFor = (operation) => Object.freeze(operation === "inspect_managed_artifact"
+    ? [
+        "This capability inventories PE/CLI identity only; inspect_managed_members admits metadata members, signatures, and CIL anchors.",
+        "It never loads the target assembly, resolves dependencies through a CLR, decompiles C#, or executes target code.",
+    ]
+    : operation === "inspect_managed_native_boundaries"
+        ? [
+            "This capability inventories managed declarations for native boundaries only; native exports, thunks, and addresses require separate native-provider evidence.",
+            "It never loads the target assembly, resolves dependencies through a CLR, decompiles C#, or executes target code.",
+        ]
+        : [
+            "This capability decodes PE/CLI metadata members, signatures, and file-backed method bodies; decompiled C# reconstruction and cross-build member comparison are separate operations.",
+            "It never loads the target assembly, resolves dependencies through a CLR, decompiles C#, or executes target code.",
+        ]);

package/dist/evaluation/CodexAgentEval.js

@@ -1,3 +1,4 @@
+import { compareUnicodeCodePoints } from "../domain/unicodeCodePointOrder.js";
 const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 const record = (value) => isRecord(value) ? value : undefined;
 const textValue = (value) => typeof value === "string" && value.length > 0 ? value : undefined;
@@ -9,7 +10,7 @@ const canonicalValue = (value) => {
     if (object === undefined)
         return value;
     return Object.fromEntries(Object.entries(object)
-        .sort(([left], [right]) => left.localeCompare(right))
+        .sort(([left], [right]) => compareUnicodeCodePoints(left, right))
         .map(([key, child]) => [key, canonicalValue(child)]));
 };
 const evidenceIdsFrom = (value) => {

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 });
+    }
+};