rea-agents 6.0.0 → 6.2.0

package/dist/artifacts/ArtifactProvider.js

@@ -1,3 +1,4 @@
+import { snapshotEnvironment } from "../process/snapshotEnvironment.js";
 import { createAnalysisExecution, } from "../application/AnalysisProvider.js";
 import { inspectBundleKeyedArchive } from "./apple/KeyedArchiveReader.js";
 import { traceDylibResolution } from "./apple/DylibResolutionReader.js";
@@ -7,7 +8,7 @@ import { extractArtifact } from "./extraction/ArtifactExtraction.js";
 import { analyzeInterfaceBuilderBundle } from "./apple/InterfaceBuilderAnalysis.js";
 import { analyzeAppleAssetCatalogs } from "./apple/AppleAssetCatalogAnalysis.js";
 import { ARTIFACT_ANALYSIS_OPERATIONS, artifactInventoryInputSchema, artifactExtractionExecutionSchema, } from "../contracts/artifactToolContracts.js";
-import { AnalysisCapabilityUnavailableError } from "../domain/analysisErrorCore.js";
+import { AnalysisCapabilityUnavailableError, AnalysisInputError, AnalysisUnsupportedTargetError, } from "../domain/analysisErrorCore.js";
 import { ArtifactOperationError } from "../domain/artifactOperationError.js";
 import {} from "../domain/analysisErrorBase.js";
 import { interfaceBuilderLimitsSchema } from "../domain/apple/interfaceBuilderGraph.js";
@@ -20,8 +21,12 @@ import { resolveArtifactIntegrityPolicy } from "./inventory/policy.js";
 /** Read-only inventory and exclusively owned extraction provider. */
 export class ArtifactProvider {
     #capabilities;
-    constructor(platform = process.platform) {
+    #platform;
+    environment;
+    constructor(environment, platform = process.platform) {
+        this.environment = snapshotEnvironment(environment, platform);
         this.#capabilities = artifactCapabilities(platform);
+        this.#platform = platform;
     }
     identity() {
         return IDENTITY;
@@ -30,13 +35,17 @@ export class ArtifactProvider {
         return this.#capabilities;
     }
     createClient(target) {
-        return new ArtifactClient(target);
+        return new ArtifactClient(target, this.environment, this.#platform);
     }
 }
 class ArtifactClient {
     target;
-    constructor(target) {
+    environment;
+    platform;
+    constructor(target, environment, platform) {
         this.target = target;
+        this.environment = environment;
+        this.platform = platform;
     }
     async execute(operation, parameters, options) {
         if (operation === "health")
@@ -52,7 +61,7 @@ class ArtifactClient {
                 if (this.target.kind !== "executable" ||
                     this.target.sourcePath === undefined ||
                     !this.target.sourcePath.toLowerCase().endsWith(".app"))
-                    throw new ArtifactReaderFailure("unavailable", "decode_interface_builder requires an active .app bundle target");
+                    throw this.unsupportedTarget(operation, "decode_interface_builder requires an active .app bundle target");
                 const limits = interfaceBuilderLimitsSchema.parse(parameters);
                 const result = await analyzeInterfaceBuilderBundle({
                     bundlePath: this.target.sourcePath,
@@ -74,19 +83,27 @@ class ArtifactClient {
                     parameters.path !== undefined &&
                     parameters.path !== "." &&
                     parameters.path !== basename(this.target.path))
-                    throw new ArtifactReaderFailure("path", "For an active plist, path must select that archive (omit path or use its basename)");
+                    throw new AnalysisInputError(operation, undefined, [
+                        {
+                            path: ["path"],
+                            reason: "invalid_value",
+                            message: "For an active plist, path must select that archive (omit path or use its basename).",
+                            expected: basename(this.target.path),
+                        },
+                    ]);
                 const bundlePath = standalone
                     ? dirname(this.target.path)
                     : this.target.sourcePath;
                 if (bundlePath === undefined ||
                     (!standalone && !bundlePath.toLowerCase().endsWith(".app")))
-                    throw new ArtifactReaderFailure("unavailable", "inspect_keyed_archive requires an active plist or .app bundle");
+                    throw this.unsupportedTarget(operation, "inspect_keyed_archive requires an active plist or .app bundle");
                 const result = await inspectBundleKeyedArchive({
                     bundlePath,
                     targetSha256: this.target.sha256,
                     parameters: standalone
                         ? { ...parameters, path: basename(this.target.path) }
                         : parameters,
+                    platform: this.platform,
                     ...(options?.signal === undefined ? {} : { signal: options.signal }),
                 });
                 if (standalone && result.archive_sha256 !== this.target.sha256)
@@ -107,6 +124,7 @@ class ArtifactClient {
                     inputPath: this.target.sourcePath ?? this.target.path,
                     inputFormat: this.target.format,
                     outputRoot: parsed.output_root,
+                    environment: this.environment,
                 }, options?.signal);
                 return ok(createAnalysisExecution(result, IDENTITY, {
                     rawResult: null,
@@ -131,19 +149,24 @@ class ArtifactClient {
             }));
         }
         catch (cause) {
-            return err(translateFailure(operation, cause));
+            return err(translateArtifactFailure(operation, cause));
         }
     }
     close() {
-        return Promise.resolve();
+        return Promise.resolve(ok(null));
+    }
+    /** The active target's kind is outside this operation's supported targets. */
+    unsupportedTarget(operation, reason) {
+        return new AnalysisUnsupportedTargetError(operation, this.target.sourcePath ?? this.target.path, reason);
     }
     async inspectAssetCatalog(parameters, options) {
         const bundlePath = this.target.sourcePath;
         if (this.target.kind !== "executable" ||
             bundlePath === undefined ||
             !bundlePath.toLowerCase().endsWith(".app"))
-            throw new ArtifactReaderFailure("unavailable", "inspect_asset_catalog requires an active .app bundle target");
+            throw this.unsupportedTarget("inspect_asset_catalog", "inspect_asset_catalog requires an active .app bundle target");
         const result = await analyzeAppleAssetCatalogs({
+            environment: this.environment,
             bundlePath,
             targetSha256: this.target.sha256,
             page: parameters,
@@ -159,7 +182,7 @@ class ArtifactClient {
     }
     async traceDylibResolution(parameters, options) {
         if (this.target.kind !== "executable" || this.target.format !== "mach-o")
-            throw new ArtifactReaderFailure("unavailable", "trace_dylib_resolution requires an active Mach-O or .app bundle target");
+            throw this.unsupportedTarget("trace_dylib_resolution", "trace_dylib_resolution requires an active Mach-O or .app bundle target");
         // Only a target opened from an app bundle directory carries its Info.plist;
         // a regular file whose name ends in .app is a standalone image.
         const bundle = this.target.bundleInfoPlist === undefined
@@ -222,6 +245,7 @@ class ArtifactClient {
     }
     inventory(parsed, options) {
         return inventoryArtifact(this.target.sourcePath ?? this.target.path, {
+            environment: this.environment,
             ...(options?.signal === undefined ? {} : { signal: options.signal }),
             integrity: resolveArtifactIntegrityPolicy({
                 mode: parsed.integrity_policy,
@@ -230,9 +254,20 @@ class ArtifactClient {
     }
 }
 const isArtifactOperation = (operation) => ARTIFACT_ANALYSIS_OPERATIONS.includes(operation);
-const translateFailure = (operation, cause) => {
+/** Translate one artifact boundary failure while retaining cleanup evidence. */
+export const translateArtifactFailure = (operation, cause) => {
     if (cause instanceof ArtifactReaderFailure)
-        return new ArtifactOperationError(operation, cause.reason, cause.details, cause.message);
+        return new ArtifactOperationError(operation, cause.reason, cause.details, cause.message, {
+            ...(cause.cleanup === undefined ? {} : { cleanup: cause.cleanup }),
+            ...(cause.partialObservation === undefined
+                ? {}
+                : { partialObservation: cause.partialObservation }),
+        });
+    // Caller-selection and unsupported-target failures are already typed; keep
+    // their correction details instead of reducing them to an I/O failure.
+    if (cause instanceof AnalysisInputError ||
+        cause instanceof AnalysisUnsupportedTargetError)
+        return cause;
     return new ArtifactOperationError(operation, "io");
 };
 const subjectFor = (path, manifest) => ({

package/dist/artifacts/ArtifactReader.js

@@ -2,10 +2,41 @@
 export class ArtifactReaderFailure extends Error {
     reason;
     details;
+    cleanup;
+    partialObservation;
     constructor(reason, message, options, details) {
         super(message, options);
         this.reason = reason;
         this.details = details;
         this.name = "ArtifactReaderFailure";
+        this.cleanup = options?.cleanup;
+        this.partialObservation = options?.partialObservation;
+    }
+    /** Preserve the primary failure while attaching cleanup and any complete observation. */
+    static withCleanup(cause, cleanup, partialObservation) {
+        const primary = cause instanceof ArtifactReaderFailure
+            ? cause
+            : new ArtifactReaderFailure("io", errorMessage(cause), { cause });
+        const mergedObservation = partialObservation ?? primary.partialObservation;
+        return new ArtifactReaderFailure(primary.reason, primary.message, {
+            cause: primary,
+            cleanup: combineCleanup(primary.cleanup, cleanup),
+            ...(mergedObservation === undefined
+                ? {}
+                : { partialObservation: mergedObservation }),
+        }, primary.details);
+    }
+    /** Give otherwise opaque cleanup failures a concrete owned resource. */
+    static cleanupObservation(cause, resource) {
+        if (cause instanceof ArtifactReaderFailure && cause.cleanup !== undefined)
+            return cause.cleanup;
+        return { reason: errorMessage(cause), resources: [resource] };
     }
 }
+const combineCleanup = (primary, cleanup) => primary === undefined || primary === cleanup
+    ? cleanup
+    : {
+        reason: `${primary.reason}; ${cleanup.reason}`,
+        resources: [...new Set([...primary.resources, ...cleanup.resources])],
+    };
+const errorMessage = (cause) => cause instanceof Error ? cause.message : String(cause);

package/dist/artifacts/DirectoryArtifactReader.js

@@ -1,6 +1,7 @@
 import { constants } from "node:fs";
 import { lstat, open, opendir, realpath } from "node:fs/promises";
 import { isAbsolute, join, relative, sep } from "node:path";
+import { compareCodePoints } from "../domain/canonicalOrdering.js";
 import { ArtifactReaderFailure, } from "./ArtifactReader.js";
 /** Deterministic, non-symlink-following directory reader. */
 export class DirectoryArtifactReader {
@@ -38,7 +39,7 @@ export class DirectoryArtifactReader {
                 await handle.close().catch(() => undefined);
             }
             await withDirectoryIoContext("inspect directory", directory, () => assertContainedDirectory(root, directory));
-            children.sort((left, right) => left.localeCompare(right, "en"));
+            children.sort(compareCodePoints);
             const directories = [];
             for (const name of children) {
                 abortIfNeeded(signal);

package/dist/artifacts/MachOSliceArtifactReader.js

@@ -1,8 +1,9 @@
 import { createReadStream } from "node:fs";
-import { stat } from "node:fs/promises";
+import { open as openFile, stat } from "node:fs/promises";
 import { Readable } from "node:stream";
 import { XcrunCommandRunner, } from "../native/CommandRunner.js";
-import { parseLipoArchitectures } from "../native/parsers/lipo.js";
+import { parseLipoArchitectures, } from "../native/parsers/lipo.js";
+import { readMachoImage } from "./apple/MachoLoadCommandReader.js";
 import { ArtifactReaderFailure, } from "./ArtifactReader.js";
 import { streamChunkToBuffer } from "./StreamBytes.js";
 /** Read-only universal Mach-O slice reader backed by native lipo metadata. */
@@ -11,7 +12,7 @@ export class MachOSliceArtifactReader {
     runner;
     format = "file";
     #command;
-    constructor(path, runner = new XcrunCommandRunner()) {
+    constructor(path, environment, runner = new XcrunCommandRunner(environment)) {
         this.path = path;
         this.runner = runner;
     }
@@ -28,28 +29,75 @@ export class MachOSliceArtifactReader {
             effects: ["read"],
         };
         const fileSize = (await stat(this.path)).size;
-        for (const architecture of parseLipoArchitectures(captured.value.stdout)) {
-            if (architecture.file_offset === null || architecture.size === null)
+        const architectures = parseLipoArchitectures(captured.value.stdout);
+        const structural = await readStructuralSlices(this.path, fileSize);
+        if (structural.status === "malformed")
+            throw new ArtifactReaderFailure("integrity", `Mach-O structural slice index is malformed: ${structural.reason}`);
+        if (structural.status === "unsupported")
+            throw new ArtifactReaderFailure("format", `Mach-O structural slice index is unsupported: ${structural.reason}`);
+        const slices = structural.status === "parsed" ? structural.slices : null;
+        const matchingSlices = new Map();
+        if (slices !== null) {
+            if (slices.length !== architectures.length)
+                throw new ArtifactReaderFailure("integrity", "lipo architecture count disagrees with the Mach-O FAT table");
+            const unmatched = [...slices];
+            for (const reported of architectures) {
+                const match = unmatched.findIndex((observed) => lipoMatchesSlice(reported, observed, slices.length === 1));
+                if (match < 0)
+                    throw new ArtifactReaderFailure("integrity", `lipo slice metadata disagrees with the Mach-O FAT table: ${reported.name} (cputype=${reported.cpu_type ?? "unknown"}, cpusubtype=${reported.cpu_subtype ?? "unknown"}, offset=${reported.file_offset ?? "unknown"}, size=${reported.size ?? "unknown"}, alignment=${reported.alignment ?? "unknown"})`);
+                const [observed] = unmatched.splice(match, 1);
+                if (observed !== undefined)
+                    matchingSlices.set(reported, observed);
+            }
+        }
+        for (const architecture of architectures) {
+            const structuralSlice = matchingSlices.get(architecture);
+            const offset = architecture.file_offset ?? structuralSlice?.slice_offset;
+            const sliceSize = architecture.size ?? structuralSlice?.slice_size;
+            if (offset === undefined || sliceSize === undefined)
                 throw new ArtifactReaderFailure("integrity", "lipo omitted a universal slice byte range");
-            if (!Number.isSafeInteger(architecture.file_offset) ||
-                !Number.isSafeInteger(architecture.size) ||
-                architecture.file_offset < 0 ||
-                architecture.size <= 0 ||
-                !Number.isSafeInteger(architecture.file_offset + architecture.size) ||
-                architecture.file_offset + architecture.size > fileSize)
+            if (!Number.isSafeInteger(offset) ||
+                !Number.isSafeInteger(sliceSize) ||
+                offset < 0 ||
+                sliceSize <= 0 ||
+                !Number.isSafeInteger(offset + sliceSize) ||
+                offset + sliceSize > fileSize)
                 throw new ArtifactReaderFailure("integrity", `lipo reported an out-of-bounds Mach-O slice: ${architecture.name}`);
             yield {
                 path: `slices/${architecture.name}`,
                 kind: "slice",
-                declaredSize: architecture.size,
+                declaredSize: sliceSize,
                 compressedSize: null,
                 executable: true,
                 encrypted: false,
-                byteOffset: architecture.file_offset,
+                byteOffset: offset,
                 declaredSha256: null,
                 unpacked: false,
-                limitations: [],
-                adapterKey: `${String(architecture.file_offset)}:${String(architecture.size)}`,
+                limitations: [
+                    ...(structural.status === "not-mach-o"
+                        ? [
+                            "Structural Mach-O facts were unavailable; slice range is based on lipo output.",
+                        ]
+                        : []),
+                    ...(architecture.file_offset === null || architecture.size === null
+                        ? [
+                            "Slice range was derived from structural Mach-O facts because lipo omitted it.",
+                        ]
+                        : []),
+                    ...(architecture.cpu_type !== null &&
+                        architecture.cpu_type_code === null
+                        ? [
+                            `lipo CPU type is retained as unnormalized source text: ${architecture.cpu_type}`,
+                        ]
+                        : []),
+                    ...(architecture.cpu_subtype !== null &&
+                        architecture.cpu_subtype_code === null
+                        ? [
+                            `lipo CPU subtype is retained as unnormalized source text: ${architecture.cpu_subtype}${architecture.capabilities === null ? "" : `; capabilities ${architecture.capabilities}`}`,
+                        ]
+                        : []),
+                ],
+                adapterKey: `${String(offset)}:${String(sliceSize)}`,
             };
         }
     }
@@ -103,6 +151,49 @@ export class MachOSliceArtifactReader {
         return Promise.resolve();
     }
 }
+/** Compare lipo's independent ranges with structurally parsed slice identity. */
+const readStructuralSlices = async (path, size) => {
+    const file = await openFile(path, "r");
+    try {
+        const readAt = async (offset, length) => {
+            const bytes = Buffer.alloc(length);
+            const { bytesRead } = await file.read(bytes, 0, length, offset);
+            return bytes.subarray(0, bytesRead);
+        };
+        const facts = await readMachoImage(readAt, size);
+        return facts;
+    }
+    finally {
+        await file.close();
+    }
+};
+const lipoMatchesSlice = (reported, observed, structurallyUnique) => {
+    const observedCpuType = observed.fat_cpu_type ?? observed.cpu_type;
+    const observedCpuSubtype = observed.fat_cpu_subtype ?? observed.cpu_subtype;
+    const hasPhysicalIdentity = reported.file_offset !== null ||
+        reported.size !== null ||
+        reported.cpu_type_code !== null ||
+        reported.cpu_subtype_code !== null;
+    return ((hasPhysicalIdentity || structurallyUnique) &&
+        lipoNameMatches(reported.name, observed.architecture) &&
+        (reported.file_offset === null ||
+            reported.file_offset === observed.slice_offset) &&
+        (reported.size === null || reported.size === observed.slice_size) &&
+        (reported.cpu_type_code === null ||
+            reported.cpu_type_code === observedCpuType) &&
+        (reported.cpu_subtype_code === null ||
+            reported.cpu_subtype_code === observedCpuSubtype) &&
+        (reported.alignment === null ||
+            observed.fat_alignment_exponent === null ||
+            reported.alignment === 2 ** observed.fat_alignment_exponent));
+};
+/**
+ * Newer lipo names an arm64e ABI variant `arm64e.<variant>` (for example
+ * `arm64e.v1` for pointer-auth ABI version 1). The FAT table names that slice
+ * `arm64e`; its physical identity is still compared field by field.
+ */
+const lipoNameMatches = (reported, observed) => reported === observed ||
+    (observed === "arm64e" && /^arm64e\.[A-Za-z0-9_]+$/u.test(reported));
 const parseSliceKeyInteger = (value) => {
     if (value === undefined || !/^\d+$/u.test(value))
         return null;

package/dist/artifacts/NativeDmgArtifactReader.js

@@ -7,6 +7,13 @@ import { ArtifactReaderFailure, } from "./ArtifactReader.js";
 import { DirectoryArtifactReader } from "./DirectoryArtifactReader.js";
 import { execFileOutput } from "../process/ExecFileOutput.js";
 const DETACH_TIMEOUT_MS = 120_000;
+/**
+ * Waits before rechecking devices whose detach failed. A related device's
+ * later detach can eject one, `hdiutil info` can still list an ejected device
+ * briefly, and a volume can report busy just after it was read.
+ */
+const DETACH_SETTLE_DELAYS_MS = [250, 500, 1000];
+const delay = (milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds));
 const attachOutputSchema = z.object({
     "system-entities": z.array(z.object({
         "dev-entry": z.string().startsWith("/dev/"),
@@ -18,10 +25,12 @@ const infoOutputSchema = z.object({
         "system-entities": z.array(z.object({ "dev-entry": z.string() })),
     })),
 });
-const systemHost = {
+const createSystemHost = (environment) => ({
+    delay,
     async run(arguments_, signal, options) {
         try {
             const { stdout, stderr } = await execFileOutput("/usr/bin/hdiutil", [...arguments_], {
+                env: environment,
                 ...(options === undefined ? {} : { timeout: options.timeoutMs }),
                 ...(signal === undefined ? {} : { signal }),
             });
@@ -41,7 +50,7 @@ const systemHost = {
             throw new ArtifactReaderFailure(commandFailureReason(cause, arguments_[0]), `hdiutil ${arguments_[0] ?? "operation"} failed: ${describeCommandFailure(cause, arguments_)}`, { cause });
         }
     },
-};
+});
 /** Read-only macOS DMG adapter that owns attachment and reverse-order detach. */
 export class NativeDmgArtifactReader {
     path;
@@ -56,10 +65,10 @@ export class NativeDmgArtifactReader {
         this.host = host;
     }
     /** Verify and attach one image beneath an exclusively owned temporary root. */
-    static async create(path, signal, host = systemHost) {
-        if (process.platform !== "darwin" && host === systemHost)
+    static async create(path, environment, signal, host) {
+        if (process.platform !== "darwin" && host === undefined)
             throw new ArtifactReaderFailure("unavailable", "Native DMG traversal is available only on macOS");
-        const reader = new NativeDmgArtifactReader(path, host);
+        const reader = new NativeDmgArtifactReader(path, host ?? createSystemHost(environment));
         await reader.attach(signal);
         return reader;
     }
@@ -80,28 +89,70 @@ export class NativeDmgArtifactReader {
     }
     async close() {
         let detachFailure;
+        let remainingDevices = [];
         for (const device of [...this.#devices].reverse()) {
-            try {
-                await runChecked(this.host, ["detach", device], undefined, {
-                    timeoutMs: DETACH_TIMEOUT_MS,
-                });
-                this.#provenance.push(command(["detach", device], ["mount"]));
+            const failure = await this.#detach(device);
+            if (failure !== undefined) {
+                remainingDevices.push(device);
+                detachFailure ??= failure;
             }
-            catch (cause) {
-                // Detaching a synthesized APFS container also ejects the image that
-                // backs it, so a later whole disk of the same image may already be
-                // gone. Only a device that is still attached is a cleanup failure.
-                if (await this.#isAttached(device))
-                    detachFailure ??= cause;
+        }
+        // Detaching a synthesized APFS container also ejects the image that backs
+        // it, so a device whose own detach failed may be gone by the end of the
+        // pass, and hdiutil can list an ejected device or report busy briefly.
+        // Only a device that stays attached through every recheck is a failure.
+        for (const delayMs of DETACH_SETTLE_DELAYS_MS) {
+            if (remainingDevices.length === 0)
+                break;
+            await (this.host.delay ?? delay)(delayMs);
+            const stillAttached = [];
+            for (const device of remainingDevices) {
+                if (!(await this.#isAttached(device)))
+                    continue;
+                const failure = await this.#detach(device);
+                if (failure !== undefined) {
+                    stillAttached.push(device);
+                    detachFailure = failure;
+                }
             }
+            remainingDevices = stillAttached;
         }
-        this.#devices = [];
-        if (this.#mountRoot !== undefined)
-            await rm(this.#mountRoot, { recursive: true, force: true }).catch((cause) => {
+        if (remainingDevices.length === 0)
+            detachFailure = undefined;
+        this.#devices = remainingDevices.reverse();
+        if (this.#devices.length === 0 && this.#mountRoot !== undefined)
+            await rm(this.#mountRoot, { recursive: true, force: true }).then(() => {
+                this.#mountRoot = undefined;
+                this.#directory = undefined;
+            }, (cause) => {
                 detachFailure ??= cause;
             });
         if (detachFailure !== undefined)
-            throw new ArtifactReaderFailure("unavailable", "DMG detach or mount-root cleanup failed", { cause: detachFailure });
+            throw new ArtifactReaderFailure("unavailable", `DMG detach or mount-root cleanup failed for ${JSON.stringify(this.path)}: ${failureMessage(detachFailure)}`, {
+                cause: detachFailure,
+                cleanup: {
+                    reason: failureMessage(detachFailure),
+                    resources: [
+                        ...this.#devices.map((device) => `DMG device ${device}`),
+                        ...(this.#mountRoot === undefined
+                            ? []
+                            : [`DMG mount root ${this.#mountRoot}`]),
+                    ],
+                },
+            });
+    }
+    /** Detach one device; return the failure only while it remains attached. */
+    async #detach(device) {
+        try {
+            await runChecked(this.host, ["detach", device], undefined, {
+                timeoutMs: DETACH_TIMEOUT_MS,
+            });
+            this.#provenance.push(command(["detach", device], ["mount"]));
+            return undefined;
+        }
+        catch (cause) {
+            return (await this.#isAttached(device)) ? cause : undefined;
+        }
     }
     /**
      * Report whether hdiutil still lists a device; unknown state counts as
@@ -169,11 +220,12 @@ export class NativeDmgArtifactReader {
                 cleanupFailure = cleanupCause;
             }
             if (cleanupFailure !== undefined)
-                throw new ArtifactReaderFailure("unavailable", "DMG attach failed and cleanup could not detach every device", { cause: new AggregateError([cause, cleanupFailure]) });
+                throw ArtifactReaderFailure.withCleanup(cause, ArtifactReaderFailure.cleanupObservation(cleanupFailure, `DMG mount root ${this.#mountRoot ?? this.path}`));
             throw cause;
         }
     }
 }
+const failureMessage = (cause) => cause instanceof Error ? cause.message : String(cause);
 const runChecked = async (host, arguments_, signal, options) => {
     let result;
     try {

package/dist/artifacts/SafeOutputTree.js

@@ -129,7 +129,13 @@ export class SafeOutputTree {
     async rollback() {
         if (this.#published)
             return structuredClone(this.#cleanup);
-        await rm(this.#outputRoot, { recursive: true, force: true });
+        let removalFailure;
+        try {
+            await rm(this.#outputRoot, { recursive: true, force: true });
+        }
+        catch (cause) {
+            removalFailure = cause;
+        }
         const absent = await isAbsent(this.#outputRoot);
         this.#cleanup = absent
             ? { status: "complete", residualPaths: [] }
@@ -138,7 +144,15 @@ export class SafeOutputTree {
                 residualPaths: [basename(this.#outputRoot)],
             };
         if (!absent)
-            throw new ArtifactReaderFailure("integrity", "Extraction output cleanup could not be verified");
+            throw new ArtifactReaderFailure("integrity", `Extraction output cleanup could not be verified${removalFailure === undefined ? "" : `: ${removalFailure instanceof Error ? removalFailure.message : String(removalFailure)}`}`, {
+                cause: removalFailure,
+                cleanup: {
+                    reason: removalFailure instanceof Error
+                        ? removalFailure.message
+                        : "Extraction output root remains after rollback",
+                    resources: [this.#outputRoot],
+                },
+            });
         return structuredClone(this.#cleanup);
     }
     async #prepareParent(relativePath) {

package/dist/artifacts/ZipArtifactReader.js

@@ -5,10 +5,12 @@ import { Reader, ZipReader } from "@zip.js/zip.js";
 import { ArtifactReaderFailure, } from "./ArtifactReader.js";
 class NodeFileReader extends Reader {
     path;
+    maximumReadBytes;
     #handle;
-    constructor(path) {
+    constructor(path, maximumReadBytes) {
         super(path);
         this.path = path;
+        this.maximumReadBytes = maximumReadBytes;
     }
     async init() {
         this.#handle = await open(this.path, "r");
@@ -18,7 +20,11 @@ class NodeFileReader extends Reader {
         const handle = this.#handle;
         if (handle === undefined)
             throw new Error("ZIP reader is not initialized");
-        const bytes = Buffer.alloc(Math.min(length, this.size - index));
+        const readBytes = Math.min(length, this.size - index);
+        if (this.maximumReadBytes !== undefined &&
+            readBytes > this.maximumReadBytes)
+            throw new ArtifactReaderFailure("limit", `ZIP metadata read requires ${readBytes} bytes, exceeding the ${this.maximumReadBytes}-byte read budget`);
+        const bytes = Buffer.alloc(readBytes);
         const read = await handle.read(bytes, 0, bytes.length, index);
         return bytes.subarray(0, read.bytesRead);
     }
@@ -33,9 +39,10 @@ export class ZipArtifactReader {
     #source;
     #reader;
     #entries = new Map();
-    constructor(path, format) {
+    /** Optionally bound each metadata read before allocating its backing buffer. */
+    constructor(path, format, maximumMetadataReadBytes) {
         this.format = format;
-        this.#source = new NodeFileReader(path);
+        this.#source = new NodeFileReader(path, maximumMetadataReadBytes);
         this.#reader = new ZipReader(this.#source, {
             checkSignature: true,
             checkOverlappingEntry: true,