rea-agents 6.5.0 → 6.7.0

package/dist/artifacts/ArtifactProvider.js

@@ -9,12 +9,13 @@ import { analyzeInterfaceBuilderBundle } from "./apple/InterfaceBuilderAnalysis.
 import { analyzeAppleAssetCatalogs } from "./apple/AppleAssetCatalogAnalysis.js";
 import { ARTIFACT_ANALYSIS_OPERATIONS, artifactInventoryInputSchema, artifactExtractionExecutionSchema, } from "../contracts/artifactToolContracts.js";
 import { isMachOFormat, } from "../domain/binaryTargetTypes.js";
-import { AnalysisCapabilityUnavailableError, AnalysisInputError, AnalysisUnsupportedTargetError, } from "../domain/analysisErrorCore.js";
+import { AnalysisCapabilityUnavailableError, AnalysisCancelledError, AnalysisInputError, AnalysisUnsupportedTargetError, } from "../domain/analysisErrorCore.js";
 import { ArtifactOperationError } from "../domain/artifactOperationError.js";
 import { interfaceBuilderLimitsSchema } from "../domain/apple/interfaceBuilderGraph.js";
 import { err, ok } from "../domain/result.js";
 import { ArtifactReaderFailure } from "./ArtifactReader.js";
 import { ArtifactResourceScope } from "./ArtifactResourceScope.js";
+import { artifactFileCancellationCause, bindArtifactFileCleanup, } from "./ArtifactFileOperation.js";
 import { artifactCapabilities } from "./ArtifactProviderMetadata.js";
 import { ARTIFACT_GRAPH_PROVIDER } from "../application/InvestigationProviders.js";
 import { createEvidence } from "../domain/evidence.js";
@@ -157,10 +158,12 @@ class ArtifactClient {
     close() {
         return this.#resourceScope.close().then(() => ok(null), (cause) => {
             const failure = cause instanceof ArtifactReaderFailure ? cause : undefined;
-            return err(new ProviderCleanupError(ARTIFACT_GRAPH_PROVIDER.id, failure?.cleanup?.resources ?? ["artifact resources"], {
+            const error = new ProviderCleanupError(ARTIFACT_GRAPH_PROVIDER.id, failure?.cleanup?.resources ?? ["artifact resources"], {
                 reason: failure?.cleanup?.reason ??
                     (cause instanceof Error ? cause.message : String(cause)),
-            }, { cause, operation: "close_binary" }));
+            }, { cause, operation: "close_binary" });
+            bindArtifactFileCleanup(cause, error);
+            return err(error);
         });
     }
     /** The active target's kind is outside this operation's supported targets. */
@@ -202,6 +205,7 @@ class ArtifactClient {
             targetSha256: this.target.sha256,
             enumerateRoots: bundle !== undefined,
             parameters,
+            resourceScope: this.#resourceScope,
             ...(options?.signal === undefined ? {} : { signal: options.signal }),
         });
         return ok(createAnalysisExecution(result, ARTIFACT_GRAPH_PROVIDER, {
@@ -263,16 +267,23 @@ class ArtifactClient {
 const isArtifactOperation = (operation) => ARTIFACT_ANALYSIS_OPERATIONS.includes(operation);
 /** 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, {
+    if (cause instanceof ArtifactReaderFailure) {
+        const error = new ArtifactOperationError(operation, cause.reason, cause.details, cause.message, {
+            cause: cause.reason === "cancelled"
+                ? artifactFileCancellationCause(cause)
+                : cause,
             ...(cause.cleanup === undefined ? {} : { cleanup: cause.cleanup }),
             ...(cause.partialObservation === undefined
                 ? {}
                 : { partialObservation: cause.partialObservation }),
         });
+        bindArtifactFileCleanup(cause, error);
+        return error;
+    }
     // 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 AnalysisCancelledError ||
         cause instanceof AnalysisUnsupportedTargetError)
         return cause;
     return new ArtifactOperationError(operation, "io");

package/dist/artifacts/ArtifactReader.js

@@ -1,3 +1,4 @@
+import { AnalysisError } from "../domain/analysisErrorBase.js";
 /** Compare captured filesystem identity and mutable metadata at a read boundary. */
 export const sameArtifactSourceIdentity = (expected, observed) => expected !== undefined &&
     observed.dev === expected.device &&
@@ -37,25 +38,56 @@ export const sameArtifactEntry = (entry, produced) => entry.path === produced.pa
 export class ArtifactReaderFailure extends Error {
     reason;
     details;
+    cancellation;
     cleanup;
+    cleanupLeases;
     partialObservation;
+    /** The constrained bound for a `limit` reason, when the reader knows it. */
+    boundary;
     constructor(reason, message, options, details) {
         super(message, options);
         this.reason = reason;
         this.details = details;
         this.name = "ArtifactReaderFailure";
+        this.cancellation =
+            reason === "cancelled"
+                ? (options?.cancellation ?? { reason: options?.cause })
+                : undefined;
         this.cleanup = options?.cleanup;
+        this.cleanupLeases =
+            options?.cleanupLeases ?? (this.cleanup === undefined ? [] : undefined);
         this.partialObservation = options?.partialObservation;
+        this.boundary = options?.boundary;
     }
-    /** Preserve the primary failure while attaching cleanup and any complete observation. */
-    static withCleanup(cause, cleanup, partialObservation) {
+    /** Preserve the primary failure and observation. Supplied leases must cover all merged cleanup. */
+    static withCleanup(cause, cleanup, partialObservation, cleanupLeases) {
         const primary = cause instanceof ArtifactReaderFailure
             ? cause
-            : new ArtifactReaderFailure("io", errorMessage(cause), { cause });
+            : new ArtifactReaderFailure("io", errorMessage(cause), {
+                cause,
+                ...(cause instanceof AnalysisError
+                    ? {
+                        partialObservation: cause.partialObservation,
+                        ...(cause.cleanupIncomplete
+                            ? {
+                                cleanup: ArtifactReaderFailure.cleanupObservation(cause, []),
+                            }
+                            : {}),
+                    }
+                    : {}),
+            });
         const mergedObservation = partialObservation ?? primary.partialObservation;
         return new ArtifactReaderFailure(primary.reason, primary.message, {
             cause: primary,
+            cancellation: primary.cancellation,
             cleanup: combineCleanup(primary.cleanup, cleanup),
+            cleanupLeases: cleanupLeases ??
+                (cleanup === primary.cleanup ? primary.cleanupLeases : undefined),
+            // The constrained bound survives cleanup wrapping, or a file-size
+            // refusal would be reported as a memory constraint once a close fails.
+            ...(primary.boundary === undefined
+                ? {}
+                : { boundary: primary.boundary }),
             ...(mergedObservation === undefined
                 ? {}
                 : { partialObservation: mergedObservation }),
@@ -65,7 +97,15 @@ export class ArtifactReaderFailure extends Error {
     static cleanupObservation(cause, resource) {
         if (cause instanceof ArtifactReaderFailure && cause.cleanup !== undefined)
             return cause.cleanup;
-        return { reason: errorMessage(cause), resources: [resource] };
+        if (cause instanceof AnalysisError && cause.cleanupIncomplete)
+            return {
+                reason: cause.cleanup?.reason ?? cause.message,
+                resources: [...cause.cleanupResources],
+            };
+        return {
+            reason: errorMessage(cause),
+            resources: typeof resource === "string" ? [resource] : [...resource],
+        };
     }
 }
 const combineCleanup = (primary, cleanup) => primary === undefined || primary === cleanup
@@ -75,3 +115,9 @@ const combineCleanup = (primary, cleanup) => primary === undefined || primary ==
         resources: [...new Set([...primary.resources, ...cleanup.resources])],
     };
 const errorMessage = (cause) => cause instanceof Error ? cause.message : String(cause);
+/** Read explicit source authority; unrelated domain cleanup remains unresolved. */
+export const artifactPrimaryCleanupLeases = (cause) => cause instanceof ArtifactReaderFailure
+    ? cause.cleanupLeases
+    : cause instanceof AnalysisError && cause.cleanupIncomplete
+        ? undefined
+        : [];

package/dist/artifacts/ArtifactResourceScope.js

@@ -1,13 +1,36 @@
-import { ArtifactReaderFailure } from "./ArtifactReader.js";
+import { ArtifactReaderFailure, artifactPrimaryCleanupLeases, } from "./ArtifactReader.js";
+import { AnalysisCleanupLease } from "./AnalysisCleanupLease.js";
+/** Retry failure carrying the exact retained owners that did not release. */
+export class ArtifactResourceRetryFailure extends ArtifactReaderFailure {
+    failedOwners;
+    cleanupLeases;
+    constructor(failures, message, options) {
+        super("unavailable", message, options);
+        this.failedOwners = failures.map(({ owner }) => owner);
+        this.cleanupLeases = [...new Set(failures.map(({ lease }) => lease))];
+    }
+}
 /** Caller-owned scope that retains failed artifact cleanup for a later close. */
 export class ArtifactResourceScope {
     #pending = new Set();
+    #leases = new WeakMap();
     #active = new Set();
     #draining;
     #closed = false;
     get hasPending() {
         return this.#pending.size > 0;
     }
+    /** Labels come from the exact retained owners, never from diagnostic text. */
+    get cleanupResources() {
+        return [
+            ...new Set([...this.#pending].flatMap((owner) => {
+                const lease = this.#lease(owner);
+                return lease.released
+                    ? []
+                    : (lease.cleanupResources ?? [owner.resource]);
+            })),
+        ];
+    }
     /** Admit a resource operation while the scope remains open. */
     async run(operation) {
         while (true) {
@@ -34,15 +57,34 @@ export class ArtifactResourceScope {
     /** Attempt cleanup now and retain the same owner if it fails. */
     async release(owner) {
         try {
-            await cleanup(owner);
+            await this.#lease(owner).release();
             this.#pending.delete(owner);
             return { kind: "released" };
         }
         catch (cause) {
             this.#pending.add(owner);
-            return { kind: "failed", cause };
+            this.#observeCleanupFailure(owner, cause);
+            return { kind: "failed", cause, owner, lease: this.#lease(owner) };
         }
     }
+    /** Compose initial cleanup authority without confusing it with an independent primary. */
+    cleanupFailure(outcome, failures, partialObservation) {
+        const observations = failures.map(({ cause, owner }) => ArtifactReaderFailure.cleanupObservation(cause, owner.resource));
+        const primary = outcome.kind === "failed" ? outcome.cause : failures[0].cause;
+        const inherited = outcome.kind === "failed" ? artifactPrimaryCleanupLeases(primary) : [];
+        return ArtifactReaderFailure.withCleanup(primary, {
+            reason: observations.map(({ reason }) => reason).join("; "),
+            resources: [
+                ...new Set(observations.flatMap(({ resources }) => resources)),
+            ],
+        }, partialObservation, inherited === undefined
+            ? undefined
+            : [...new Set([...inherited, ...failures.map(({ lease }) => lease)])]);
+    }
+    /** Adopt an owner after another boundary's cleanup attempt failed. */
+    retain(owner) {
+        this.#pending.add(owner);
+    }
     /** Retry retained owners without closing resource admission. */
     retryCleanup() {
         if (this.#draining !== undefined)
@@ -63,20 +105,23 @@ export class ArtifactResourceScope {
         const failures = [];
         for (const owner of this.#pending) {
             try {
-                await cleanup(owner);
+                await this.#lease(owner).release();
                 this.#pending.delete(owner);
             }
             catch (cause) {
+                this.#observeCleanupFailure(owner, cause);
                 failures.push({ owner, cause });
             }
         }
         if (failures.length === 0)
             return;
-        const observations = failures.map(({ owner, cause }) => ArtifactReaderFailure.cleanupObservation(cause, owner.resource));
+        const observations = failures.map(({ owner, cause }) => ArtifactReaderFailure.cleanupObservation(cause, owner.kind === "lease" && owner.lease instanceof AnalysisCleanupLease
+            ? (owner.lease.cleanupResources ?? owner.resource)
+            : owner.resource));
         const resources = [
             ...new Set(observations.flatMap(({ resources }) => resources)),
         ];
-        throw new ArtifactReaderFailure("unavailable", `Artifact cleanup remains incomplete: ${resources.join(", ")}`, {
+        throw new ArtifactResourceRetryFailure(failures.map(({ owner }) => ({ owner, lease: this.#lease(owner) })), `Artifact cleanup remains incomplete: ${resources.join(", ")}`, {
             cause: new AggregateError(failures.map(({ cause }) => cause), "One or more artifact resources remain owned"),
             cleanup: {
                 reason: observations.map(({ reason }) => reason).join("; "),
@@ -84,9 +129,38 @@ export class ArtifactResourceScope {
             },
         });
     }
+    /** This boundary owns the latest parsed child cleanup facts for a composite owner. */
+    #observeCleanupFailure(owner, cause) {
+        const retained = this.#leases.get(owner);
+        if (retained !== undefined)
+            retained.resources = [
+                ...ArtifactReaderFailure.cleanupObservation(cause, owner.resource)
+                    .resources,
+            ];
+    }
+    #lease(owner) {
+        if (owner.kind === "lease" && owner.lease instanceof AnalysisCleanupLease)
+            return owner.lease;
+        const previous = this.#leases.get(owner);
+        if (previous !== undefined)
+            return previous.lease;
+        const retained = {
+            resources: [owner.resource],
+            lease: new AnalysisCleanupLease(() => cleanup(owner), {
+                get cleanupResources() {
+                    return retained.resources;
+                },
+            }),
+        };
+        this.#leases.set(owner, retained);
+        return retained.lease;
+    }
 }
 const cleanup = async (owner) => {
     switch (owner.kind) {
+        case "lease":
+            await owner.lease.release();
+            return;
         case "javascript-source-analysis":
             await owner.analysis.close();
             return;

package/dist/artifacts/AsarArtifactReader.js

@@ -10,7 +10,7 @@ import { ArtifactReaderFailure, copyArtifactEntry, sameArtifactEntry, } from "./
 import { closeAsarHandle, readValidatedAsarEntry } from "./AsarEntryStream.js";
 import { admitAsarHeader } from "./AsarHeader.js";
 import { OwnedFileHandle } from "../filesystem/OwnedFileHandle.js";
-import { readFileHandleChunks } from "../filesystem/readFileHandleChunks.js";
+import { readArtifactFileChunks } from "./readArtifactFileChunks.js";
 import { readAsarListing, } from "./AsarListing.js";
 /**
  * Official Electron ASAR adapter with range-streamed member reads.
@@ -227,18 +227,15 @@ export class AsarArtifactReader {
                     callback(null, chunk);
                 },
             });
-            await pipeline(source, digesting, createWriteStream(snapshotPath, { flags: "wx", mode: 0o600 }), signal === undefined ? {} : { signal });
+            await pipeline(source, digesting, createWriteStream(snapshotPath, { flags: "wx", mode: 0o600 }));
             const completedInput = inputHandle;
             inputHandle = undefined;
             await this.#closeOwnedHandle(completedInput);
+            abortIfNeeded(signal);
             this.#snapshot = { path: snapshotPath, sha256: hash.digest("hex") };
         }
         catch (cause) {
-            let failure = signal?.aborted === true
-                ? new ArtifactReaderFailure("cancelled", "ASAR operation cancelled", {
-                    cause,
-                })
-                : asarFailure(this.path, "snapshot", cause);
+            let failure = asarFailure(this.path, "snapshot", cause);
             if (inputHandle !== undefined) {
                 const failedInput = inputHandle;
                 inputHandle = undefined;
@@ -345,7 +342,7 @@ export class AsarArtifactReader {
                 });
             }
             abortIfNeeded(signal);
-            const source = this.#ownedReadStream(openedHandle, { start: 0 });
+            const source = this.#ownedReadStream(openedHandle, { start: 0, signal });
             handle = undefined;
             const output = readValidatedAsarEntry(source, undefined, entry.path, this.path, signal);
             this.#setOwnedOutput(openedHandle, output);
@@ -404,7 +401,7 @@ export class AsarArtifactReader {
     }
     #ownedReadStream(handle, options) {
         const { releaseOnClose, ...readOptions } = options;
-        const source = readFileHandleChunks(handle, readOptions);
+        const source = readArtifactFileChunks(handle, readOptions);
         const owned = this.#ownedHandles.get(handle);
         if (owned === undefined)
             throw new ArtifactReaderFailure("integrity", "ASAR handle has no owner");
@@ -450,7 +447,9 @@ const parseArchiveOffset = (value) => {
 };
 const abortIfNeeded = (signal) => {
     if (signal?.aborted === true)
-        throw new ArtifactReaderFailure("cancelled", "ASAR operation cancelled");
+        throw new ArtifactReaderFailure("cancelled", "ASAR operation cancelled", {
+            cause: signal.reason,
+        });
 };
 const waitForOperation = async (operation, signal) => {
     if (signal === undefined)
@@ -460,7 +459,9 @@ const waitForOperation = async (operation, signal) => {
         const removeAbortListener = () => signal.removeEventListener("abort", onAbort);
         const onAbort = () => {
             removeAbortListener();
-            reject(new ArtifactReaderFailure("cancelled", "ASAR operation cancelled"));
+            reject(new ArtifactReaderFailure("cancelled", "ASAR operation cancelled", {
+                cause: signal.reason,
+            }));
         };
         signal.addEventListener("abort", onAbort, { once: true });
         operation.then(() => {

package/dist/artifacts/AsarEntryStream.js

@@ -7,27 +7,40 @@ export const closeAsarHandle = async (close, signal) => {
 };
 /** Validate and contextualize bytes read from one ASAR member source. */
 export const readValidatedAsarEntry = (source, expectedBytes, entryPath, archivePath, signal) => {
+    const expectedExtent = expectedBytes === undefined ? undefined : BigInt(expectedBytes);
+    const completionFailure = () => {
+        const coverage = source.readCoverage();
+        if (coverage.kind !== "complete")
+            return new ArtifactReaderFailure("integrity", `ASAR entry read coverage is incomplete: ${entryPath}`);
+        if (expectedExtent !== undefined && coverage.bytes !== expectedExtent)
+            return new ArtifactReaderFailure("integrity", `ASAR entry size disagrees with its header: ${entryPath}`);
+        if (signal?.aborted)
+            return new ArtifactReaderFailure("cancelled", "ASAR operation cancelled", { cause: signal.reason });
+        return undefined;
+    };
     const output = Readable.from((async function* () {
-        let observedBytes = 0;
         const iterator = source[Symbol.asyncIterator]();
         try {
             while (true) {
-                abortIfNeeded(signal);
                 const next = await iterator.next();
                 if (next.done)
                     break;
                 const chunk = next.value;
                 if (!Buffer.isBuffer(chunk) && !(chunk instanceof Uint8Array))
                     throw new ArtifactReaderFailure("format", `ASAR entry did not return bytes: ${entryPath}`);
-                observedBytes += Buffer.isBuffer(chunk)
-                    ? chunk.length
-                    : chunk.byteLength;
-                if (expectedBytes !== undefined && observedBytes > expectedBytes)
+                const coverage = source.readCoverage();
+                if (expectedExtent !== undefined && coverage.bytes > expectedExtent)
                     throw new ArtifactReaderFailure("integrity", `ASAR entry exceeded its declared size: ${entryPath}`);
+                if (coverage.kind === "complete" && signal?.aborted) {
+                    const failure = completionFailure();
+                    if (failure !== undefined)
+                        throw failure;
+                }
                 yield chunk;
             }
-            if (expectedBytes !== undefined && observedBytes !== expectedBytes)
-                throw new ArtifactReaderFailure("integrity", `ASAR entry size disagrees with its header: ${entryPath}`);
+            const failure = completionFailure();
+            if (failure !== undefined)
+                throw failure;
         }
         catch (cause) {
             throw asarFailure(archivePath, `read ${entryPath}`, cause);
@@ -43,24 +56,43 @@ export const readValidatedAsarEntry = (source, expectedBytes, entryPath, archive
                 source.destroy();
         }
     })());
-    const closeSource = () => {
-        signal?.removeEventListener("abort", onAbort);
-        if (!source.destroyed)
-            source.destroy();
+    const onSourceError = (cause) => {
+        const completedCancellation = cause instanceof ArtifactReaderFailure &&
+            cause.reason === "cancelled" &&
+            source.readCoverage().kind === "complete"
+            ? completionFailure()
+            : undefined;
+        output.destroy(completedCancellation ??
+            asarFailure(archivePath, `read ${entryPath}`, cause));
     };
+    source.on("error", onSourceError);
+    source.once("close", () => source.removeListener("error", onSourceError));
     const onAbort = () => {
-        closeSource();
-        output.destroy(new ArtifactReaderFailure("cancelled", "ASAR operation cancelled"));
+        if (source.readCoverage().kind === "complete" &&
+            !output.destroyed &&
+            (source.errored === null ||
+                (source.errored instanceof ArtifactReaderFailure &&
+                    source.errored.reason === "cancelled"))) {
+            const failure = completionFailure();
+            if (failure !== undefined)
+                output.destroy(failure);
+        }
     };
-    output.once("close", closeSource);
     signal?.addEventListener("abort", onAbort, { once: true });
-    if (signal?.aborted === true)
+    output.once("close", () => {
+        signal?.removeEventListener("abort", onAbort);
+        if (!source.destroyed)
+            source.destroy();
+    });
+    if (signal?.aborted)
         onAbort();
     return output;
 };
 const abortIfNeeded = (signal) => {
     if (signal?.aborted === true)
-        throw new ArtifactReaderFailure("cancelled", "ASAR operation cancelled");
+        throw new ArtifactReaderFailure("cancelled", "ASAR operation cancelled", {
+            cause: signal.reason,
+        });
 };
 const asarFailure = (path, operation, cause) => {
     if (cause instanceof ArtifactReaderFailure)

package/dist/artifacts/DirectoryArtifactReader.js

@@ -6,7 +6,19 @@ import { ArtifactReaderFailure, sameArtifactSourceIdentity, } from "./ArtifactRe
 import { hostExecutableMarking } from "./hostExecutableMarking.js";
 import { OwnedDirectoryHandle } from "../filesystem/OwnedDirectoryHandle.js";
 import { OwnedFileHandle } from "../filesystem/OwnedFileHandle.js";
-import { readFileHandleChunks } from "../filesystem/readFileHandleChunks.js";
+import { readArtifactFileChunks } from "./readArtifactFileChunks.js";
+/** Exhausted an examined-entry budget; unrelated I/O and cleanup failures stay distinct. */
+export class DirectoryArtifactTraversalLimit extends ArtifactReaderFailure {
+    examinedEntries;
+    maximumEntries;
+    constructor(examinedEntries, maximumEntries) {
+        super("limit", "Directory traversal reached its examined-entry budget", {
+            boundary: "capacity",
+        });
+        this.examinedEntries = examinedEntries;
+        this.maximumEntries = maximumEntries;
+    }
+}
 /** Non-symlink-following directory reader. */
 export class DirectoryArtifactReader {
     format = "directory";
@@ -22,6 +34,16 @@ export class DirectoryArtifactReader {
     async *entries(signal, selection) {
         const root = await this.#resolveRoot();
         const options = typeof selection === "function" ? { descendInto: selection } : selection;
+        const maximum = options?.maximumEntries;
+        if (maximum !== undefined &&
+            (!Number.isSafeInteger(maximum) || maximum < 0))
+            throw new RangeError("Directory traversal maximumEntries must be a nonnegative safe integer");
+        let examined = 0;
+        const examine = () => {
+            if (maximum !== undefined && examined >= maximum)
+                throw new DirectoryArtifactTraversalLimit(examined, maximum);
+            examined += 1;
+        };
         const pending = [root];
         while (pending.length > 0) {
             abortIfNeeded(signal);
@@ -29,7 +51,7 @@ export class DirectoryArtifactReader {
             if (directory === undefined)
                 break;
             await withDirectoryIoContext("inspect directory", directory, () => assertContainedDirectory(root, directory, this.#rootIdentity));
-            for await (const entry of this.#readDirectory(directory, pending, signal, options))
+            for await (const entry of this.#readDirectory(directory, pending, signal, options, examine))
                 yield entry;
             await withDirectoryIoContext("inspect directory", directory, () => assertContainedDirectory(root, directory, this.#rootIdentity));
         }
@@ -48,7 +70,7 @@ export class DirectoryArtifactReader {
             throw directoryIoFailure("resolve artifact root", this.#rootPath, cause);
         }));
     }
-    async *#readDirectory(directory, pending, signal, options) {
+    async *#readDirectory(directory, pending, signal, options, examine) {
         const root = await this.#resolveRoot();
         const handle = new OwnedDirectoryHandle(await opendir(directory).catch((cause) => {
             throw directoryIoFailure("open directory", directory, cause);
@@ -64,6 +86,7 @@ export class DirectoryArtifactReader {
                 const child = await handle.handle.read();
                 if (child === null)
                     break;
+                examine();
                 abortIfNeeded(signal);
                 const absolute = join(directory, child.name);
                 const metadata = await lstat(absolute, { bigint: true }).catch((cause) => {
@@ -260,7 +283,7 @@ const mapStableFileRead = async function* (handle, entry, signal) {
         const expectedBytes = entry.sourceIdentity?.size;
         if (expectedBytes === undefined)
             throw new ArtifactReaderFailure("integrity", `Directory entry has no captured file state: ${entry.path}`);
-        for await (const chunk of readFileHandleChunks(handle, {
+        for await (const chunk of readArtifactFileChunks(handle, {
             // Include one extra byte so a growing file cannot make this read unbounded.
             end: expectedBytes,
             signal,
@@ -283,8 +306,6 @@ const mapStableFileRead = async function* (handle, entry, signal) {
             throw new ArtifactReaderFailure("integrity", `Directory entry changed during read: ${entry.path}`);
     }
     catch (cause) {
-        if (signal?.aborted === true)
-            throw new ArtifactReaderFailure("cancelled", "Directory artifact read cancelled", { cause });
         if (cause instanceof Error &&
             "code" in cause &&
             ["ENOENT", "ENOTDIR", "ELOOP"].includes(String(cause.code)))
@@ -304,7 +325,7 @@ const withDirectoryIoContext = async (operation, path, action) => {
 };
 const abortIfNeeded = (signal) => {
     if (signal?.aborted === true)
-        throw new ArtifactReaderFailure("cancelled", "Artifact traversal cancelled");
+        throw new ArtifactReaderFailure("cancelled", "Artifact traversal cancelled", { cause: signal.reason });
 };
 const assertContainedDirectory = async (root, directory, rootIdentity) => {
     const canonical = await realpath(directory);