rea-agents 6.4.0 → 6.5.0

package/dist/pcap/PcapProvider.js

@@ -0,0 +1,424 @@
+import { createAnalysisExecution, } from "../application/AnalysisProvider.js";
+import { pcapResultSchemas, } from "../domain/pcap/pcapAnalysis.js";
+import { AnalysisCancelledError, AnalysisCapabilityUnavailableError, AnalysisProtocolError, } from "../domain/analysisErrorCore.js";
+import { AnalysisError } from "../domain/analysisErrorBase.js";
+import { projectAnalysisError } from "../domain/analysisErrorProjection.js";
+import { analysisErrorWithCleanupFailure } from "../domain/analysisErrorCleanup.js";
+import { err, ok } from "../domain/result.js";
+import { PcapConfigurationFailure, inspectPcapClient, resolvePcapTools, pcapConfigurationAvailability, pcapToolUnavailable, } from "./PcapConfiguration.js";
+import { parseCapinfosOutput, parseTsharkJsonOutput, TSHARK_JSON_MAX_BYTES, } from "./PcapOutput.js";
+import { runPcapCommand, } from "./PcapCommand.js";
+import { ProviderCleanupError } from "../domain/providerCleanupError.js";
+import { jsonValueSchema } from "../domain/jsonValue.js";
+import { createPcapEvidence } from "../domain/pcap/pcapEvidence.js";
+import { preparePcapNativeBound } from "./PcapNativeBound.js";
+import { PcapSnapshot } from "./PcapSnapshot.js";
+import { readStableArtifact } from "../artifacts/readStableArtifact.js";
+import { ArtifactAnalysisResources } from "../process/ArtifactAnalysisResources.js";
+import { readLinuxResourceLimits } from "../process/LinuxResourceLimits.js";
+export const PCAP_PROVIDER_IDENTITY = {
+    id: "pcap",
+    name: "Packet capture analysis",
+    version: null,
+};
+const FIELDS = [
+    "frame.number",
+    "frame.protocols",
+    "ip.src",
+    "ip.dst",
+    "ipv6.src",
+    "ipv6.dst",
+    "dns.flags.response",
+    "dns.qry.name",
+    "dns.a",
+    "dns.aaaa",
+    "tls.handshake.extensions_server_name",
+    "http.request.full_uri",
+];
+const pcapPartialEvidence = (request, provider, path, identity, result, limitations) => createPcapEvidence(request, {
+    subject: { path, format: "file", sha256: identity.sha256 },
+    provider,
+    result: jsonValueSchema.parse(result),
+    rawResult: null,
+    limitations,
+    locations: [{ kind: "artifact-path", path }],
+});
+const pcapCommandCleanupError = (operation, snapshotPath, cleanup, capturedOutput, partialObservation) => new ProviderCleanupError("pcap", [
+    ...new Set([
+        ...(snapshotPath === undefined ? [] : [snapshotPath]),
+        ...cleanup.resources,
+    ]),
+], {
+    reason: cleanup.reason,
+    previous_error: null,
+    captured_output: {
+        stdout: capturedOutput.stdout,
+        stderr: capturedOutput.stderr,
+        truncated: cleanup.capturedOutput.truncated,
+    },
+}, {
+    operation,
+    ...(partialObservation === undefined ? {} : { partialObservation }),
+});
+/** Inspect saved captures through bounded, owned tool processes and one stable input copy. */
+export class PcapProvider {
+    #resources = new ArtifactAnalysisResources("pcap", "inspect_pcap_capture", readStableArtifact, readLinuxResourceLimits, {
+        message: "A packet summary is already active; retry after it completes.",
+        details: { max_concurrent_inspections: 1 },
+    });
+    environment;
+    launcher;
+    snapshots = new Set();
+    commands = new Map();
+    constructor(options = {}) {
+        this.environment = options.environment ?? process.env;
+        this.launcher = options.launcher;
+    }
+    async run(operation, command, args, limits, signal, snapshot, inputPath) {
+        let cleanup;
+        const output = await runPcapCommand({
+            operation,
+            command,
+            arguments: args,
+            limits,
+            signal,
+            environment: snapshot === undefined
+                ? this.environment
+                : {
+                    ...this.environment,
+                    WIRESHARK_CONFIG_DIR: snapshot.configurationPath,
+                },
+            ...(inputPath === undefined ? {} : { inputPath }),
+            ...(inputPath === undefined || this.nativeBound === undefined
+                ? {}
+                : { nativeBound: this.nativeBound }),
+            ...(this.launcher === undefined ? {} : { launcher: this.launcher }),
+            retain: (owner, resources, reason, capturedOutput) => {
+                this.commands.set(owner, {
+                    snapshot,
+                    resources,
+                    reason,
+                    capturedOutput,
+                });
+                cleanup = { reason, resources, capturedOutput };
+            },
+        });
+        if (inputPath === undefined && cleanup !== undefined)
+            throw new ProviderCleanupError("pcap", cleanup.resources, {
+                reason: cleanup.reason,
+                previous_error: null,
+                captured_output: {
+                    stdout: output.stdout,
+                    stderr: output.stderr,
+                    truncated: cleanup.capturedOutput.truncated,
+                },
+            }, { operation });
+        return output;
+    }
+    nativeBound;
+    nativeLimitations = [];
+    async prepareCaptureBound() {
+        const prepared = await preparePcapNativeBound(this.environment, this.#resources);
+        this.nativeBound = prepared.nativeBound;
+        this.nativeLimitations = prepared.limitations;
+    }
+    async client(operation, signal) {
+        const selection = resolvePcapTools(this.environment);
+        const identity = await inspectPcapClient(selection, async (command) => (await this.run(operation, command, ["--version"], { timeoutMs: 20_000, maxOutputBytes: 64 * 1024 }, signal)).stdout);
+        for (const [name, version] of [
+            ["tshark", identity.tsharkVersion],
+            ["capinfos", identity.capinfosVersion],
+        ]) {
+            if (version === null)
+                throw new PcapConfigurationFailure(`${name}_version_unresolved`, `The selected ${name} command did not report a version. Set REA_${name.toUpperCase()}_COMMAND to its absolute executable path.`);
+        }
+        return {
+            selection,
+            client: {
+                tshark_command: selection.tshark.command,
+                tshark_source: selection.tshark.source,
+                tshark_version: identity.tsharkVersion,
+                capinfos_command: selection.capinfos.command,
+                capinfos_source: selection.capinfos.source,
+                capinfos_version: identity.capinfosVersion,
+            },
+        };
+    }
+    async inspectAvailability(signal) {
+        const result = await this.#resources.run(async () => ok(await this.inspectAvailabilityAdmitted(signal)), signal);
+        if (!result.ok)
+            throw result.error;
+        return result.value;
+    }
+    async inspectAvailabilityAdmitted(signal) {
+        try {
+            const { client } = await this.client("inspect_pcap_client", signal);
+            if (process.platform !== "linux" && process.platform !== "win32")
+                return {
+                    status: "unavailable",
+                    code: "unsupported_host",
+                    reason: "No enforceable native memory boundary is available for capture summaries on this host.",
+                    diagnostics: client,
+                };
+            await this.prepareCaptureBound();
+            return {
+                status: "available",
+                code: null,
+                reason: null,
+                diagnostics: client,
+            };
+        }
+        catch (cause) {
+            if (cause instanceof ProviderCleanupError)
+                throw cause;
+            if (signal?.aborted || cause instanceof AnalysisCancelledError)
+                throw new AnalysisCancelledError("inspect_pcap_client", { cause });
+            if (cause instanceof PcapConfigurationFailure)
+                return pcapConfigurationAvailability(cause);
+            return {
+                status: "unavailable",
+                code: cause instanceof AnalysisCapabilityUnavailableError
+                    ? "executable_missing"
+                    : "version_unresolved",
+                reason: cause instanceof Error ? cause.message : String(cause),
+                diagnostics: {},
+            };
+        }
+    }
+    async discard(snapshot) {
+        try {
+            if ([...this.commands.values()].some((command) => command.snapshot === snapshot))
+                throw new Error("An unreleased command still owns the capture snapshot");
+            await snapshot.close();
+            this.snapshots.delete(snapshot);
+            return undefined;
+        }
+        catch (cause) {
+            return new ProviderCleanupError("pcap", [snapshot.path], { reason: String(cause) }, { operation: "inspect_pcap_capture", cause });
+        }
+    }
+    async close() {
+        const failures = [];
+        try {
+            await this.#resources.close();
+        }
+        catch (cause) {
+            failures.push(cause);
+        }
+        for (const owner of this.commands.keys()) {
+            try {
+                const result = await owner.stop();
+                if (result.status === "incomplete")
+                    failures.push(result.reason);
+                else if (result.status === "not-owned")
+                    failures.push("Command ownership remains unresolved");
+                else
+                    this.commands.delete(owner);
+            }
+            catch (cause) {
+                failures.push(cause);
+            }
+        }
+        for (const snapshot of this.snapshots) {
+            const failure = await this.discard(snapshot);
+            if (failure !== undefined)
+                failures.push(failure);
+        }
+        if (failures.length > 0)
+            throw new ProviderCleanupError("pcap", [...this.snapshots]
+                .map((snapshot) => snapshot.path)
+                .concat([...this.commands.values()].flatMap((command) => command.resources)), { reason: "Owned process or snapshot cleanup failed" }, { operation: "pcap.close", cause: new AggregateError(failures) });
+    }
+    async execute(request, options) {
+        return this.#resources.run(() => this.executeAdmitted(request, options), options?.signal);
+    }
+    async executeAdmitted(request, options) {
+        const signal = options?.signal;
+        let snapshot;
+        let result;
+        try {
+            signal?.throwIfAborted();
+            const { selection, client } = await this.client(request.operation, signal);
+            const provider = {
+                ...PCAP_PROVIDER_IDENTITY,
+                version: client.tshark_version,
+            };
+            if (request.operation === "inspect_pcap_client")
+                result = ok(createAnalysisExecution(pcapResultSchemas.inspect_pcap_client.parse({ client }), provider));
+            else {
+                await this.prepareCaptureBound();
+                snapshot = await PcapSnapshot.create();
+                this.snapshots.add(snapshot);
+                const identity = await snapshot.capture(request.input.path, signal);
+                const captured = await this.inspectCapture(selection, snapshot, request.input.path, identity, signal, request, provider, client);
+                const data = pcapResultSchemas.inspect_pcap_capture.parse({
+                    client,
+                    ...captured.result,
+                });
+                result = ok(createAnalysisExecution(data, provider, {
+                    subject: {
+                        path: request.input.path,
+                        format: "file",
+                        sha256: identity.sha256,
+                    },
+                    limitations: captured.limitations,
+                }));
+            }
+        }
+        catch (cause) {
+            result = err(cause instanceof AnalysisError
+                ? cause
+                : signal?.aborted
+                    ? new AnalysisCancelledError(request.operation, { cause })
+                    : cause instanceof PcapConfigurationFailure
+                        ? pcapToolUnavailable(request.operation, cause.message, {
+                            cause,
+                        })
+                        : new AnalysisProtocolError(`Packet-capture analysis failed: ${cause instanceof Error ? cause.message : String(cause)}`, { cause }));
+        }
+        if (signal?.aborted && result.ok)
+            result = err(new AnalysisCancelledError(request.operation, {
+                cause: signal.reason,
+                partialObservation: createPcapEvidence(request, result.value),
+            }));
+        const pendingCommand = snapshot === undefined
+            ? undefined
+            : [...this.commands.values()].find((command) => command.snapshot === snapshot);
+        if (snapshot !== undefined && pendingCommand === undefined) {
+            const cleanup = await this.discard(snapshot);
+            if (signal?.aborted && result.ok)
+                result = err(new AnalysisCancelledError(request.operation, {
+                    cause: signal.reason,
+                    partialObservation: createPcapEvidence(request, result.value),
+                }));
+            if (cleanup !== undefined)
+                result = result.ok
+                    ? err(cleanup.retainPartialObservation(createPcapEvidence(request, result.value)))
+                    : err(analysisErrorWithCleanupFailure(result.error, cleanup, request.operation));
+        }
+        if (snapshot !== undefined &&
+            pendingCommand !== undefined &&
+            (result.ok || !(result.error instanceof ProviderCleanupError))) {
+            const partialObservation = result.ok
+                ? createPcapEvidence(request, result.value)
+                : result.error.partialObservation;
+            const capturedOutput = result.ok
+                ? undefined
+                : result.error.capturedOutput;
+            result = err(new ProviderCleanupError("pcap", [...new Set([snapshot.path, ...pendingCommand.resources])], {
+                reason: pendingCommand.reason,
+                previous_error: result.ok
+                    ? null
+                    : projectAnalysisError(result.error),
+                ...(capturedOutput === undefined &&
+                    pendingCommand.capturedOutput.stdout === "" &&
+                    pendingCommand.capturedOutput.stderr === ""
+                    ? {}
+                    : {
+                        captured_output: {
+                            ...(capturedOutput ?? pendingCommand.capturedOutput),
+                        },
+                    }),
+            }, {
+                operation: request.operation,
+                ...(partialObservation === undefined ? {} : { partialObservation }),
+            }));
+        }
+        return result;
+    }
+    async inspectCapture(selection, snapshot, path, identity, signal, request, provider, client) {
+        const info = await this.run("inspect_pcap_capture", selection.capinfos.command, ["-M", "--", snapshot.path], { timeoutMs: 60_000, maxOutputBytes: 64 * 1024 }, signal, snapshot, path);
+        const metadata = parseCapinfosOutput(info.stdout);
+        if (metadata.sha256 !== null && metadata.sha256 !== identity.sha256)
+            throw new AnalysisProtocolError("capinfos SHA256 disagrees with the owned capture snapshot");
+        if (info.cleanup !== undefined)
+            throw pcapCommandCleanupError(request.operation, snapshot.path, info.cleanup, info, pcapPartialEvidence(request, provider, path, identity, {
+                client,
+                target: { path, ...identity },
+                stage: "capinfos-complete-tshark-not-run",
+                file_type: metadata.fileType,
+                encapsulation: metadata.encapsulation,
+                packet_count: metadata.packetCount,
+                capture_start: metadata.captureStart,
+                capture_end: metadata.captureEnd,
+                capture_duration_seconds: metadata.captureDurationSeconds,
+                snapshot_length: metadata.snapshotLength,
+            }, [
+                "capinfos output was parsed from a complete bounded stream, but process-tree cleanup remains unconfirmed; tshark was not run",
+            ]));
+        const dissected = await this.run("inspect_pcap_capture", selection.tshark.command, [
+            "-n",
+            "-r",
+            snapshot.path,
+            "-T",
+            "json",
+            "--no-duplicate-keys",
+            `--temp-dir=${snapshot.configurationPath}`,
+            ...FIELDS.flatMap((field) => ["-e", field]),
+        ], { timeoutMs: 300_000, maxOutputBytes: TSHARK_JSON_MAX_BYTES }, signal, snapshot, path);
+        const fields = await parseTsharkJsonOutput(dissected.stdout, signal);
+        await snapshot.verify(identity, path, signal);
+        if (fields.packetCount !== metadata.packetCount)
+            throw new AnalysisProtocolError(`capinfos counted ${String(metadata.packetCount)} packets but tshark returned ${String(fields.packetCount)}`);
+        const captured = {
+            result: {
+                target: { path, ...identity },
+                file_type: metadata.fileType,
+                encapsulation: metadata.encapsulation,
+                packet_count: metadata.packetCount,
+                capture_start: metadata.captureStart,
+                capture_end: metadata.captureEnd,
+                capture_duration_seconds: metadata.captureDurationSeconds,
+                diagnostics: {
+                    capinfos_stderr: info.stderr,
+                    tshark_stderr: dissected.stderr,
+                },
+                snapshot_length: metadata.snapshotLength,
+                endpoints: fields.endpoints,
+                endpoint_count: fields.endpointCount,
+                dns_queries: fields.dnsQueries,
+                dns_query_count: fields.dnsQueryCount,
+                tls_sni_values: fields.tlsSniValues,
+                tls_sni_count: fields.tlsSniCount,
+                protocol_distribution: fields.protocolDistribution,
+                protocol_count: fields.protocolCount,
+                http_request_uris: fields.httpRequestUris,
+                http_request_uri_count: fields.httpRequestUriCount,
+                http_uri_redaction_count: fields.httpUriRedactionCount,
+                unattributed_dns_addresses: fields.unattributedDnsAddresses,
+                unattributed_dns_address_count: fields.unattributedDnsAddressCount,
+                unattributed_dns_packet_count: fields.unattributedDnsPackets,
+                coverage: fields.partial ? "partial" : "complete",
+            },
+            limitations: [
+                ...this.nativeLimitations,
+                "Both tools read one owned snapshot; target identity comes from its admitted source descriptor",
+                "DNS address values are associated only with a single question in the same response packet; values may include additional DNS records, not only final resolution answers",
+                "Only bytes present in the saved capture are examined; encryption and capture truncation can hide higher-level fields",
+                ...(fields.partial
+                    ? [
+                        "One or more projected categories were capped, credential-bearing URIs were omitted or coalesced, or DNS address attribution remains unresolved; counts retain the examined totals",
+                    ]
+                    : []),
+                ...(fields.httpUriRedactionCount > 0
+                    ? [
+                        "HTTP transport credentials were excluded; ambiguous credential spans cause the URI to be omitted",
+                    ]
+                    : []),
+                ...(fields.unattributedDnsPackets > 0
+                    ? [
+                        `DNS address attribution was unresolved in ${String(fields.unattributedDnsPackets)} packet(s); unattributed addresses are retained separately`,
+                    ]
+                    : []),
+            ],
+        };
+        if (dissected.cleanup !== undefined) {
+            const full = pcapResultSchemas.inspect_pcap_capture.parse({
+                client,
+                ...captured.result,
+            });
+            throw pcapCommandCleanupError(request.operation, snapshot.path, dissected.cleanup, dissected, pcapPartialEvidence(request, provider, path, identity, full, captured.limitations));
+        }
+        return captured;
+    }
+}

package/dist/pcap/PcapSnapshot.js

@@ -0,0 +1,171 @@
+import { createHash } from "node:crypto";
+import { chmod, open, stat, mkdir } from "node:fs/promises";
+import { join } from "node:path";
+import { AnalysisError } from "../domain/analysisErrorBase.js";
+import { AnalysisAccessDeniedError, AnalysisArtifactChangedError, AnalysisCancelledError, AnalysisCapabilityUnavailableError, AnalysisInputError, AnalysisResourceConstraintError, } from "../domain/analysisErrorCore.js";
+import { OwnedFileHandle } from "../filesystem/OwnedFileHandle.js";
+import { openRegularFile, RegularFileAdmissionFailure, sameRegularFileState, } from "../filesystem/RegularFile.js";
+import { PrivateRuntimeRoot } from "../process/PrivateRuntimeRoot.js";
+import { PrivateRuntimeRootUnavailableError } from "../process/PrivateRuntimeRootUnavailableError.js";
+const OPERATION = "inspect_pcap_capture";
+const MAX_CAPTURE_BYTES = 2 * 1024 ** 3;
+/** An owned capture copy and every descriptor needed to release it safely. */
+export class PcapSnapshot {
+    root;
+    handles = new Set();
+    path;
+    configurationPath;
+    constructor(root) {
+        this.root = root;
+        this.path = join(root.path, "capture.pcap");
+        this.configurationPath = join(root.path, "configuration");
+    }
+    static async create() {
+        try {
+            return new PcapSnapshot(await PrivateRuntimeRoot.create({ prefix: "rea-pcap-" }));
+        }
+        catch (cause) {
+            if (cause instanceof PrivateRuntimeRootUnavailableError)
+                throw new AnalysisCapabilityUnavailableError("pcap", OPERATION, cause.message, { cause, retryable: cause.retryable });
+            throw new AnalysisResourceConstraintError(OPERATION, "file-size", "Cannot allocate the owned capture workspace", null, { cause });
+        }
+    }
+    own(handle) {
+        this.handles.add(handle);
+        return handle;
+    }
+    async release(handle) {
+        await handle.close();
+        this.handles.delete(handle);
+    }
+    async capture(path, signal) {
+        const sourceRead = async (read) => {
+            try {
+                return await read();
+            }
+            catch (cause) {
+                if (signal?.aborted)
+                    throw new AnalysisCancelledError(OPERATION, { cause });
+                if (cause instanceof AnalysisError)
+                    throw cause;
+                if (cause instanceof Error &&
+                    "code" in cause &&
+                    (cause.code === "EACCES" || cause.code === "EPERM"))
+                    throw new AnalysisAccessDeniedError(OPERATION, path, cause.code, {
+                        cause,
+                    });
+                throw new AnalysisInputError(OPERATION, { cause }, [
+                    {
+                        path: ["path"],
+                        reason: "invalid_value",
+                        message: `Cannot read selected capture ${path}: ${cause instanceof Error ? cause.message : String(cause)}`,
+                    },
+                ]);
+            }
+        };
+        try {
+            signal?.throwIfAborted();
+            await mkdir(this.configurationPath, { mode: 0o700 });
+            const source = await sourceRead(async () => {
+                try {
+                    return this.own(new OwnedFileHandle(await openRegularFile(path, { symlinks: "follow", signal })));
+                }
+                catch (cause) {
+                    if (cause instanceof RegularFileAdmissionFailure) {
+                        this.own(cause.owner);
+                        throw cause.cause;
+                    }
+                    throw cause;
+                }
+            });
+            const before = await sourceRead(() => source.handle.stat({ bigint: true }));
+            if (before.size > BigInt(MAX_CAPTURE_BYTES))
+                throw new AnalysisResourceConstraintError(OPERATION, "file-size", "Capture exceeds the owned-snapshot disk budget", { max_capture_bytes: MAX_CAPTURE_BYTES });
+            const destination = this.own(new OwnedFileHandle(await open(this.path, "wx", 0o600)));
+            const buffer = Buffer.alloc(64 * 1024);
+            const hash = createHash("sha256");
+            let copied = 0;
+            while (copied <= Number(before.size)) {
+                signal?.throwIfAborted();
+                const { bytesRead } = await sourceRead(() => source.handle.read(buffer, 0, Math.min(buffer.length, Number(before.size) - copied + 1), copied));
+                signal?.throwIfAborted();
+                if (bytesRead === 0)
+                    break;
+                copied += bytesRead;
+                if (BigInt(copied) > before.size)
+                    throw new AnalysisArtifactChangedError(OPERATION, path, "Capture grew during acquisition");
+                const chunk = buffer.subarray(0, bytesRead);
+                await destination.handle.writeFile(chunk);
+                hash.update(chunk);
+            }
+            const after = await sourceRead(() => source.handle.stat({ bigint: true }));
+            const selected = await stat(path, { bigint: true }).catch((cause) => {
+                if (cause instanceof Error &&
+                    "code" in cause &&
+                    (cause.code === "EACCES" || cause.code === "EPERM"))
+                    throw new AnalysisAccessDeniedError(OPERATION, path, cause.code, {
+                        cause,
+                    });
+                throw new AnalysisArtifactChangedError(OPERATION, path, "Selected path became unavailable during acquisition", { cause });
+            });
+            if (BigInt(copied) !== before.size ||
+                !sameRegularFileState(before, after) ||
+                !sameRegularFileState(before, selected))
+                throw new AnalysisArtifactChangedError(OPERATION, path, "Capture identity or contents changed during acquisition");
+            await this.release(source);
+            await this.release(destination);
+            await chmod(this.path, 0o400);
+            signal?.throwIfAborted();
+            return { bytes: copied, sha256: hash.digest("hex") };
+        }
+        catch (cause) {
+            if (signal?.aborted)
+                throw new AnalysisCancelledError(OPERATION, { cause });
+            if (cause instanceof AnalysisError)
+                throw cause;
+            throw new AnalysisResourceConstraintError(OPERATION, "file-size", "Owned capture snapshot I/O failed", null, { cause });
+        }
+    }
+    /** Recheck byte identity after both tools; a read-only mode alone is not proof. */
+    async verify(expected, selectedPath, signal) {
+        try {
+            const file = this.own(new OwnedFileHandle(await openRegularFile(this.path, { symlinks: "reject", signal })));
+            const before = await file.handle.stat({ bigint: true });
+            const buffer = Buffer.alloc(64 * 1024);
+            const hash = createHash("sha256");
+            let bytes = 0;
+            while (bytes <= expected.bytes) {
+                signal?.throwIfAborted();
+                const read = await file.handle.read(buffer, 0, Math.min(buffer.length, expected.bytes - bytes + 1), bytes);
+                if (read.bytesRead === 0)
+                    break;
+                bytes += read.bytesRead;
+                hash.update(buffer.subarray(0, read.bytesRead));
+            }
+            const after = await file.handle.stat({ bigint: true });
+            const selected = await stat(this.path, { bigint: true });
+            if (bytes !== expected.bytes ||
+                hash.digest("hex") !== expected.sha256 ||
+                !sameRegularFileState(before, after) ||
+                !sameRegularFileState(before, selected))
+                throw new AnalysisArtifactChangedError(OPERATION, selectedPath, "Owned packet snapshot changed during tool analysis.");
+            await this.release(file);
+        }
+        catch (cause) {
+            if (signal?.aborted)
+                throw new AnalysisCancelledError(OPERATION, { cause });
+            if (cause instanceof RegularFileAdmissionFailure)
+                this.own(cause.owner);
+            if (cause instanceof AnalysisError)
+                throw cause;
+            throw new AnalysisArtifactChangedError(OPERATION, selectedPath, "Cannot establish the owned packet snapshot's post-analysis identity.", { cause });
+        }
+    }
+    async close() {
+        const results = await Promise.allSettled([...this.handles].map((handle) => this.release(handle)));
+        const failures = results.flatMap((result) => result.status === "rejected" ? [result.reason] : []);
+        if (failures.length > 0)
+            throw new AggregateError(failures, "Capture descriptor cleanup failed");
+        await this.root.close();
+    }
+}