rea-agents 6.2.0 → 6.4.0

package/dist/artifacts/NativeDmgArtifactReader.js

@@ -1,94 +1,103 @@
 import { mkdtemp, realpath, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { basename, join } from "node:path";
-import { parse } from "plist";
-import { z } from "zod";
 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.
- */
+import { execFileOutput, execFileOutputFailure, } from "../process/ExecFileOutput.js";
+import { parseNativeDmgAttachOutput, parseNativeDmgInfo, resolveNativeDmgOwnership, } from "./NativeDmgOwnership.js";
+const HDIUTIL_COMMAND_TIMEOUT_MS = 120_000;
+// APFS ejects and busy reporting can lag a detach attempt.
 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/"),
-        "mount-point": z.string().optional(),
-    })),
-});
-const infoOutputSchema = z.object({
-    images: z.array(z.object({
-        "system-entities": z.array(z.object({ "dev-entry": z.string() })),
-    })),
-});
+class NativeDmgCommandFailure extends ArtifactReaderFailure {
+    stdout;
+    processNotStarted;
+    constructor(reason, message, stdout, options) {
+        super(reason, message, options?.cause === undefined ? undefined : { cause: options.cause });
+        this.stdout = stdout;
+        this.processNotStarted = options?.processNotStarted ?? false;
+    }
+}
 const createSystemHost = (environment) => ({
     delay,
     async run(arguments_, signal, options) {
         try {
             const { stdout, stderr } = await execFileOutput("/usr/bin/hdiutil", [...arguments_], {
                 env: environment,
+                stopSignal: "SIGTERM",
                 ...(options === undefined ? {} : { timeout: options.timeoutMs }),
                 ...(signal === undefined ? {} : { signal }),
             });
             return { stdout, stderr, exitCode: 0 };
         }
         catch (cause) {
+            const output = execFileOutputFailure(cause);
             if (cause instanceof Error && cause.name === "AbortError")
-                throw new ArtifactReaderFailure("cancelled", "DMG operation cancelled");
-            const exitCode = processExitCode(cause);
+                throw new NativeDmgCommandFailure("cancelled", "DMG operation cancelled", output?.stdout ?? "", { cause });
+            const exitCode = typeof output?.code === "number" ? output.code : processExitCode(cause);
             if (exitCode !== undefined)
                 return {
-                    stdout: processOutput(cause, "stdout"),
-                    stderr: processOutput(cause, "stderr"),
+                    stdout: output?.stdout ?? processOutput(cause, "stdout"),
+                    stderr: output?.stderr ?? processOutput(cause, "stderr"),
                     exitCode,
                     cause,
                 };
-            throw new ArtifactReaderFailure(commandFailureReason(cause, arguments_[0]), `hdiutil ${arguments_[0] ?? "operation"} failed: ${describeCommandFailure(cause, arguments_)}`, { cause });
+            throw new NativeDmgCommandFailure(commandFailureReason(cause, arguments_[0]), `hdiutil ${arguments_[0] ?? "operation"} failed: ${describeCommandFailure(cause, arguments_)}`, output?.stdout ?? "", { cause, processNotStarted: processNotStarted(cause) });
         }
     },
 });
 /** Read-only macOS DMG adapter that owns attachment and reverse-order detach. */
 export class NativeDmgArtifactReader {
     path;
-    host;
     format = "file";
+    host;
     #provenance = [];
+    #initialization;
     #directory;
     #devices = [];
+    #inventoryConfirmedDevices = new Set();
     #mountRoot;
-    constructor(path, host) {
+    #baselineDevices = new Set();
+    #attachOutput;
+    #attachOutputReturned = false;
+    #attachMayHaveMounted = false;
+    #ownershipUncertainty;
+    #closed = false;
+    #closePromise;
+    constructor(path, environment, host) {
         this.path = path;
-        this.host = host;
-    }
-    /** Verify and attach one image beneath an exclusively owned temporary root. */
-    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 ?? createSystemHost(environment));
-        await reader.attach(signal);
-        return reader;
+        this.host = host ?? createSystemHost(environment);
     }
     async *entries(signal) {
+        await this.#ensureAttached(signal);
         if (this.#directory === undefined)
             throw new ArtifactReaderFailure("unavailable", "DMG is not attached");
         const prefix = basename(this.path);
         for await (const entry of this.#directory.entries(signal))
             yield { ...entry, path: `${prefix}/${entry.path}` };
     }
-    open(entry, signal) {
+    async open(entry, signal) {
+        await this.#ensureAttached(signal);
         if (this.#directory === undefined)
-            return Promise.reject(new ArtifactReaderFailure("unavailable", "DMG is not attached"));
+            throw new ArtifactReaderFailure("unavailable", "DMG is not attached");
         return this.#directory.open(entry, signal);
     }
     provenance() {
         return structuredClone(this.#provenance);
     }
-    async close() {
-        let detachFailure;
+    close() {
+        this.#closed = true;
+        this.#closePromise ??= this.#closeOwnedResources().catch((cause) => {
+            this.#closePromise = undefined;
+            throw cause;
+        });
+        return this.#closePromise;
+    }
+    async #closeOwnedResources() {
+        await this.#initialization?.catch(() => undefined);
+        let detachFailure = await this.#reconcileAttachState();
         let remainingDevices = [];
         for (const device of [...this.#devices].reverse()) {
             const failure = await this.#detach(device);
@@ -97,10 +106,7 @@ export class NativeDmgArtifactReader {
                 detachFailure ??= failure;
             }
         }
-        // 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.
+        // APFS container detach may briefly leave its backing image listed.
         for (const delayMs of DETACH_SETTLE_DELAYS_MS) {
             if (remainingDevices.length === 0)
                 break;
@@ -120,13 +126,19 @@ export class NativeDmgArtifactReader {
         if (remainingDevices.length === 0)
             detachFailure = undefined;
         this.#devices = remainingDevices.reverse();
-        if (this.#devices.length === 0 && this.#mountRoot !== undefined)
+        if (this.#devices.length === 0 &&
+            this.#mountRoot !== undefined &&
+            !this.#attachMayHaveMounted)
             await rm(this.#mountRoot, { recursive: true, force: true }).then(() => {
                 this.#mountRoot = undefined;
                 this.#directory = undefined;
             }, (cause) => {
                 detachFailure ??= cause;
             });
+        if (this.#attachMayHaveMounted) {
+            detachFailure ??= new Error(this.#ownershipUncertainty ??
+                "hdiutil attachment ownership remains unknown");
+        }
         if (detachFailure !== undefined)
             throw new ArtifactReaderFailure("unavailable", `DMG detach or mount-root cleanup failed for ${JSON.stringify(this.path)}: ${failureMessage(detachFailure)}`, {
                 cause: detachFailure,
@@ -134,6 +146,11 @@ export class NativeDmgArtifactReader {
                     reason: failureMessage(detachFailure),
                     resources: [
                         ...this.#devices.map((device) => `DMG device ${device}`),
+                        ...(this.#attachMayHaveMounted
+                            ? [
+                                `DMG attachment ownership unknown at mount root ${this.#mountRoot ?? this.path}`,
+                            ]
+                            : []),
                         ...(this.#mountRoot === undefined
                             ? []
                             : [`DMG mount root ${this.#mountRoot}`]),
@@ -145,7 +162,7 @@ export class NativeDmgArtifactReader {
     async #detach(device) {
         try {
             await runChecked(this.host, ["detach", device], undefined, {
-                timeoutMs: DETACH_TIMEOUT_MS,
+                timeoutMs: HDIUTIL_COMMAND_TIMEOUT_MS,
             });
             this.#provenance.push(command(["detach", device], ["mount"]));
             return undefined;
@@ -154,78 +171,154 @@ export class NativeDmgArtifactReader {
             return (await this.#isAttached(device)) ? cause : undefined;
         }
     }
-    /**
-     * Report whether hdiutil still lists a device; unknown state counts as
-     * attached. Like detach, this cleanup query runs after the inventory
-     * snapshot has captured provenance, so it is not recorded there.
-     */
+    async #reconcileAttachState() {
+        if (!this.#attachMayHaveMounted)
+            return undefined;
+        try {
+            await this.#resolveAttachOwnership();
+            return undefined;
+        }
+        catch (cause) {
+            this.#ownershipUncertainty = failureMessage(cause);
+            return cause;
+        }
+    }
+    /** Treat unknown hdiutil state as attached during cleanup. */
     async #isAttached(device) {
         try {
-            const info = await runChecked(this.host, ["info", "-plist"], undefined, {
-                timeoutMs: DETACH_TIMEOUT_MS,
-            });
-            const parsed = infoOutputSchema.parse(parse(info.stdout));
-            return parsed.images.some((image) => image["system-entities"].some((entity) => entity["dev-entry"] === device));
+            const parsed = await this.#readInfo();
+            const isListed = parsed.images.some((image) => image["system-entities"].some((entity) => entity["dev-entry"] === device));
+            if (isListed) {
+                this.#inventoryConfirmedDevices.add(device);
+                return true;
+            }
+            return !this.#inventoryConfirmedDevices.has(device);
         }
         catch {
             return true;
         }
     }
-    async attach(signal) {
+    async #ensureAttached(signal) {
+        if (this.#closed)
+            throw new ArtifactReaderFailure("unavailable", "DMG reader is closed");
+        this.#initialization ??= this.#attach(signal);
+        await this.#initialization;
+        if (this.#closed)
+            throw new ArtifactReaderFailure("unavailable", "DMG reader is closed");
+    }
+    async #attach(signal) {
         await runChecked(this.host, ["verify", this.path], signal);
         this.#provenance.push(command(["verify", this.path], ["read"]));
-        this.#mountRoot = await realpath(await mkdtemp(join(tmpdir(), "rea-dmg-")));
+        const baseline = await this.#readInfo();
+        this.#baselineDevices = new Set(baseline.images.flatMap((image) => image["system-entities"].map(({ "dev-entry": device }) => device)));
+        const mountRoot = await realpath(await mkdtemp(join(tmpdir(), "rea-dmg-")));
+        this.#mountRoot = mountRoot;
         try {
+            this.#attachMayHaveMounted = true;
             const attached = await runChecked(this.host, [
                 "attach",
                 "-readonly",
                 "-nobrowse",
                 "-plist",
                 "-mountroot",
-                this.#mountRoot,
+                mountRoot,
                 this.path,
-            ], signal);
-            const parsed = attachOutputSchema.parse(parse(attached.stdout));
-            const devices = [
-                ...new Set(parsed["system-entities"].map((entity) => entity["dev-entry"])),
-            ];
-            // Detaching an observed whole disk also detaches its partitions. Do not
-            // subsequently detach the now-unavailable child devices.
-            this.#devices = devices.filter((device) => !devices.some((parent) => /^\/dev\/disk\d+$/u.test(parent) &&
-                device.startsWith(`${parent}s`) &&
-                /^\d+$/u.test(device.slice(parent.length + 1))));
-            if (this.#devices.length === 0)
+            ], signal, { timeoutMs: HDIUTIL_COMMAND_TIMEOUT_MS });
+            this.#attachOutputReturned = true;
+            let parsed;
+            try {
+                parsed = parseNativeDmgAttachOutput(attached.stdout);
+            }
+            catch (cause) {
+                throw new ArtifactReaderFailure("format", "hdiutil returned a malformed attachment plist", { cause });
+            }
+            if (parsed["system-entities"].length === 0)
                 throw new ArtifactReaderFailure("format", "hdiutil returned no attached devices");
-            for (const entity of parsed["system-entities"])
-                if (entity["mount-point"] !== undefined &&
-                    !entity["mount-point"].startsWith(`${this.#mountRoot}/`))
-                    throw new ArtifactReaderFailure("path", "hdiutil mounted outside the owned root");
+            this.#attachOutput = parsed;
+            const ownership = await this.#resolveAttachOwnership();
+            if (ownership !== "owned")
+                throw new ArtifactReaderFailure(ownership === "unknown" ? "unavailable" : "path", ownership === "unknown"
+                    ? `DMG attachment ownership is uncertain: ${this.#ownershipUncertainty ?? "no unique mount under the owned root"}`
+                    : "hdiutil did not mount a new image beneath the owned root");
             this.#provenance.push(command([
                 "attach",
                 "-readonly",
                 "-nobrowse",
                 "-plist",
                 "-mountroot",
-                this.#mountRoot,
+                mountRoot,
                 this.path,
             ], ["read", "mount"]));
-            this.#directory = new DirectoryArtifactReader(this.#mountRoot);
+            this.#directory = new DirectoryArtifactReader(mountRoot);
         }
         catch (cause) {
-            let cleanupFailure;
-            try {
-                await this.close();
+            if (cause instanceof NativeDmgCommandFailure && cause.stdout !== "") {
+                try {
+                    this.#attachOutput = parseNativeDmgAttachOutput(cause.stdout);
+                    this.#attachOutputReturned = true;
+                }
+                catch {
+                    // The original command failure remains primary; fresh info still recovers mounts.
+                }
             }
-            catch (cleanupCause) {
-                cleanupFailure = cleanupCause;
+            if (cause instanceof NativeDmgCommandFailure && cause.processNotStarted) {
+                this.#attachMayHaveMounted = false;
+                this.#ownershipUncertainty = undefined;
             }
-            if (cleanupFailure !== undefined)
-                throw ArtifactReaderFailure.withCleanup(cause, ArtifactReaderFailure.cleanupObservation(cleanupFailure, `DMG mount root ${this.#mountRoot ?? this.path}`));
             throw cause;
         }
     }
+    async #readInfo() {
+        const info = await runChecked(this.host, ["info", "-plist"], undefined, {
+            timeoutMs: HDIUTIL_COMMAND_TIMEOUT_MS,
+        });
+        return parseNativeDmgInfo(info.stdout);
+    }
+    async #resolveAttachOwnership() {
+        const mountRoot = this.#mountRoot;
+        if (mountRoot === undefined)
+            throw new Error("DMG mount root is unavailable for ownership discovery");
+        const ownership = resolveNativeDmgOwnership({
+            info: await this.#readInfo(),
+            ...(this.#attachOutput === undefined
+                ? {}
+                : { attachOutput: this.#attachOutput }),
+            attachOutputReturned: this.#attachOutputReturned,
+            mountRoot,
+            baselineDevices: this.#baselineDevices,
+        });
+        if (ownership.status === "owned") {
+            this.#devices = [...ownership.devices];
+            if (ownership.source === "info")
+                for (const device of ownership.devices)
+                    this.#inventoryConfirmedDevices.add(device);
+            this.#attachMayHaveMounted = false;
+            this.#ownershipUncertainty = undefined;
+            return "owned";
+        }
+        if (ownership.status === "unknown") {
+            this.#ownershipUncertainty = ownership.reason;
+            return "unknown";
+        }
+        this.#attachMayHaveMounted = false;
+        this.#ownershipUncertainty = undefined;
+        this.#devices = [];
+        return "none";
+    }
 }
 const failureMessage = (cause) => cause instanceof Error ? cause.message : String(cause);
+const processNotStarted = (cause) => {
+    if (!(cause instanceof Error))
+        return false;
+    const syscall = Reflect.get(cause, "syscall");
+    const code = Reflect.get(cause, "code");
+    const errno = Reflect.get(cause, "errno");
+    return (typeof syscall === "string" &&
+        syscall.startsWith("spawn ") &&
+        (typeof code === "string" ||
+            typeof code === "number" ||
+            typeof errno === "number"));
+};
 const runChecked = async (host, arguments_, signal, options) => {
     let result;
     try {
@@ -235,10 +328,9 @@ const runChecked = async (host, arguments_, signal, options) => {
         if (cause instanceof ArtifactReaderFailure)
             throw cause;
         if (cause instanceof Error && cause.name === "AbortError")
-            throw new ArtifactReaderFailure("cancelled", "DMG operation cancelled", {
-                cause,
-            });
-        throw new ArtifactReaderFailure(commandFailureReason(cause, arguments_[0]), `hdiutil ${arguments_[0] ?? "operation"} failed: ${describeCommandFailure(cause, arguments_)}`, { cause });
+            throw new NativeDmgCommandFailure("cancelled", "DMG operation cancelled", execFileOutputFailure(cause)?.stdout ?? "", { cause });
+        const output = execFileOutputFailure(cause);
+        throw new NativeDmgCommandFailure(commandFailureReason(cause, arguments_[0]), `hdiutil ${arguments_[0] ?? "operation"} failed: ${describeCommandFailure(cause, arguments_)}`, output?.stdout ?? "", { cause, processNotStarted: processNotStarted(cause) });
     }
     if (result.exitCode !== 0) {
         const failure = {
@@ -253,9 +345,9 @@ const runChecked = async (host, arguments_, signal, options) => {
         const reason = commandFailureReason(failure, arguments_[0]);
         const details = describeCommandFailure(failure, arguments_);
         const unknownVerifyFailure = arguments_[0] === "verify" && reason === "unavailable";
-        throw new ArtifactReaderFailure(reason, unknownVerifyFailure
+        throw new NativeDmgCommandFailure(reason, unknownVerifyFailure
             ? `hdiutil verify failed; captured diagnostics do not establish the failure cause: ${details}`
-            : `hdiutil ${arguments_[0] ?? "operation"} failed: ${details}`, result.cause === undefined ? undefined : { cause: result.cause });
+            : `hdiutil ${arguments_[0] ?? "operation"} failed: ${details}`, result.stdout, { cause: result.cause ?? failure });
     }
     return { stdout: result.stdout, exitCode: 0 };
 };

package/dist/artifacts/NativeDmgOwnership.js

@@ -0,0 +1,109 @@
+import { relative, resolve, sep } from "node:path";
+import { parse } from "plist";
+import { z } from "zod";
+const systemEntitySchema = z.object({
+    "dev-entry": z.string().startsWith("/dev/"),
+    "mount-point": z.string().optional(),
+});
+const attachOutputSchema = z.object({
+    "system-entities": z.array(systemEntitySchema),
+});
+const infoOutputSchema = z.object({
+    images: z.array(z.object({
+        "system-entities": z.array(systemEntitySchema),
+    })),
+});
+/** Parse hdiutil's current image inventory. */
+export const parseNativeDmgInfo = (stdout) => infoOutputSchema.parse(parse(stdout));
+/** Parse hdiutil's attach response while preserving device and mount facts. */
+export const parseNativeDmgAttachOutput = (stdout) => attachOutputSchema.parse(parse(stdout));
+/** Classify only fresh image groups tied to the exclusively owned mount root. */
+export const resolveNativeDmgOwnership = (input) => {
+    const rootedImages = input.info.images.filter((image) => image["system-entities"].some(({ "mount-point": mountPoint }) => mountPoint !== undefined && isBelowRoot(input.mountRoot, mountPoint)));
+    if (rootedImages.length > 1)
+        return {
+            status: "unknown",
+            reason: "multiple hdiutil image groups report mounts beneath the owned root",
+        };
+    const rootedImage = rootedImages[0];
+    if (rootedImage !== undefined) {
+        const hasOutsideMount = rootedImage["system-entities"].some(({ "mount-point": mountPoint }) => mountPoint !== undefined && !isBelowRoot(input.mountRoot, mountPoint));
+        const groupDevices = rootedImage["system-entities"].map(({ "dev-entry": device }) => device);
+        const devices = topLevelDevices(groupDevices);
+        const overlapsBaseline = groupDevices.some((device) => input.baselineDevices.has(device));
+        if (hasOutsideMount || overlapsBaseline || devices.length === 0)
+            return {
+                status: "unknown",
+                reason: hasOutsideMount
+                    ? "the image group contains a mount outside the owned root"
+                    : overlapsBaseline
+                        ? "the image group includes a device present before attachment"
+                        : "the owned mount group contains no detachable device",
+            };
+        return { status: "owned", devices, source: "info" };
+    }
+    if (input.attachOutputReturned) {
+        const attachOwnership = ownershipFromAttachOutput(input.attachOutput, input.mountRoot, input.baselineDevices);
+        if (attachOwnership.status === "owned") {
+            return attachOwnership;
+        }
+        if (attachOwnership.status === "unknown")
+            return attachOwnership;
+    }
+    const newlyListedDevice = input.info.images.some((image) => image["system-entities"].some(({ "dev-entry": device }) => !input.baselineDevices.has(device)));
+    if (newlyListedDevice)
+        return {
+            status: "unknown",
+            reason: "hdiutil lists devices absent from the pre-attach baseline, but none is tied uniquely to the owned root; ownership is unknown",
+        };
+    return { status: "none" };
+};
+const ownershipFromAttachOutput = (output, mountRoot, baselineDevices) => {
+    if (output === undefined)
+        return {
+            status: "unknown",
+            reason: "hdiutil attach succeeded but its ownership facts were malformed",
+        };
+    const entities = output["system-entities"];
+    const hasRootMount = entities.some(({ "mount-point": mountPoint }) => mountPoint !== undefined && isBelowRoot(mountRoot, mountPoint));
+    const hasOutsideMount = entities.some(({ "mount-point": mountPoint }) => mountPoint !== undefined && !isBelowRoot(mountRoot, mountPoint));
+    const devices = entities.map(({ "dev-entry": device }) => device);
+    const uniqueDevices = topLevelDevices(devices);
+    const overlapsBaseline = devices.some((device) => baselineDevices.has(device));
+    if (hasRootMount) {
+        if (hasOutsideMount || overlapsBaseline || uniqueDevices.length === 0)
+            return {
+                status: "unknown",
+                reason: hasOutsideMount
+                    ? "the attach result includes a mount outside the owned root"
+                    : overlapsBaseline
+                        ? "the attach result includes a device present before attachment"
+                        : "the attach result's owned mount has no detachable device",
+            };
+        return { status: "owned", devices: uniqueDevices, source: "attach" };
+    }
+    if (devices.length === 0)
+        return {
+            status: "unknown",
+            reason: "hdiutil attach succeeded without reporting device ownership facts",
+        };
+    if (devices.some((device) => !baselineDevices.has(device)))
+        return {
+            status: "unknown",
+            reason: "the attach result reports new devices without a mount beneath the owned root",
+        };
+    return { status: "none" };
+};
+const topLevelDevices = (devices) => {
+    const unique = [...new Set(devices)];
+    return unique.filter((device) => !unique.some((parent) => /^\/dev\/disk\d+$/u.test(parent) &&
+        device.startsWith(`${parent}s`) &&
+        /^\d+$/u.test(device.slice(parent.length + 1))));
+};
+const isBelowRoot = (root, path) => {
+    const child = relative(root, resolve(path));
+    return (child !== "" &&
+        child !== "." &&
+        child !== ".." &&
+        !child.startsWith(`..${sep}`));
+};