rea-agents 2.0.0 → 2.1.0

package/dist/application/SetupClientConfiguration.js

@@ -0,0 +1,220 @@
+import { constants as fsConstants } from "node:fs";
+import { copyFile, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { z } from "zod";
+import writeFileAtomic from "write-file-atomic";
+import { parse as parseToml, stringify as stringifyToml } from "smol-toml";
+import { PRODUCT_IDENTITY } from "../identity.js";
+import { resolveClientConfigTransactionPath } from "./ClientConfigPath.js";
+const defaultCommand = () => [
+    "npx",
+    "-y",
+    PRODUCT_IDENTITY.packageSpecifier,
+    "mcp",
+];
+/** Back up, atomically update, and semantically read back one JSON MCP configuration. */
+export const configureJsonClient = async (client, environment = {}, command = defaultCommand()) => {
+    const transactionPath = await resolveClientConfigTransactionPath(client.configPath);
+    if (transactionPath === undefined)
+        return { status: "failed", reason: "path" };
+    let document = {};
+    let original;
+    try {
+        original = await readFile(transactionPath, "utf8");
+        document = parseObject(original);
+    }
+    catch (cause) {
+        if (!isMissing(cause))
+            return { status: "failed", reason: "readback" };
+    }
+    let servers;
+    try {
+        servers = parseOptionalObject(document.mcpServers);
+    }
+    catch {
+        return { status: "failed", reason: "readback" };
+    }
+    const desired = clientConfigurationDesired(normalizeProviderEnvironment(environment), command);
+    if (sameConfiguration(servers[PRODUCT_IDENTITY.mcpServerKey], desired))
+        return { status: "unchanged" };
+    let backupPath;
+    if (original !== undefined) {
+        backupPath = `${client.configPath}.rea.backup`;
+        if (!(await preserveConfigBackup(transactionPath, backupPath)))
+            return { status: "failed", reason: "backup" };
+    }
+    document.mcpServers = {
+        ...servers,
+        [PRODUCT_IDENTITY.mcpServerKey]: desired,
+    };
+    try {
+        await mkdir(dirname(client.configPath), { recursive: true });
+        await writeFileAtomic(transactionPath, `${JSON.stringify(document, null, 2)}\n`, {
+            encoding: "utf8",
+            mode: 0o600,
+        });
+    }
+    catch {
+        return { status: "failed", reason: "write" };
+    }
+    try {
+        const readback = parseObject(await readFile(transactionPath, "utf8"));
+        if (!sameConfiguration(parseOptionalObject(readback.mcpServers)[PRODUCT_IDENTITY.mcpServerKey], desired)) {
+            await restoreConfig(transactionPath, original);
+            return { status: "failed", reason: "readback" };
+        }
+    }
+    catch {
+        await restoreConfig(transactionPath, original);
+        return { status: "failed", reason: "readback" };
+    }
+    return {
+        status: "configured",
+        ...(backupPath === undefined ? {} : { backupPath }),
+    };
+};
+/** Back up, atomically update, and semantically read back Codex TOML configuration. */
+export const configureTomlClient = async (client, environment = {}, command = defaultCommand()) => {
+    const transactionPath = await resolveClientConfigTransactionPath(client.configPath);
+    if (transactionPath === undefined)
+        return { status: "failed", reason: "path" };
+    let document = {};
+    let original;
+    try {
+        original = await readFile(transactionPath, "utf8");
+        document = objectSchema.parse(parseToml(original));
+    }
+    catch (cause) {
+        if (!isMissing(cause))
+            return { status: "failed", reason: "readback" };
+    }
+    let servers;
+    try {
+        servers = parseOptionalObject(document.mcp_servers);
+    }
+    catch {
+        return { status: "failed", reason: "readback" };
+    }
+    const desired = clientConfigurationDesired(normalizeProviderEnvironment(environment), command);
+    if (sameConfiguration(servers[PRODUCT_IDENTITY.mcpServerKey], desired))
+        return { status: "unchanged" };
+    const backupPath = original === undefined ? undefined : `${client.configPath}.rea.backup`;
+    if (backupPath !== undefined &&
+        !(await preserveConfigBackup(transactionPath, backupPath)))
+        return { status: "failed", reason: "backup" };
+    document.mcp_servers = {
+        ...servers,
+        [PRODUCT_IDENTITY.mcpServerKey]: desired,
+    };
+    try {
+        await mkdir(dirname(client.configPath), { recursive: true });
+        await writeFileAtomic(transactionPath, stringifyToml(document), {
+            encoding: "utf8",
+            mode: 0o600,
+        });
+        const readback = objectSchema.parse(parseToml(await readFile(transactionPath, "utf8")));
+        if (!sameConfiguration(parseOptionalObject(readback.mcp_servers)[PRODUCT_IDENTITY.mcpServerKey], desired))
+            throw new Error("TOML readback mismatch");
+    }
+    catch {
+        await restoreConfig(transactionPath, original);
+        return { status: "failed", reason: "readback" };
+    }
+    return {
+        status: "configured",
+        ...(backupPath === undefined ? {} : { backupPath }),
+    };
+};
+/** Determine whether an existing client configuration matches the desired registration. */
+export const clientConfigurationAligned = async (client, providerEnvironment, command) => {
+    const desired = clientConfigurationDesired(providerEnvironment, command);
+    try {
+        const original = await readFile(client.configPath, "utf8");
+        const document = client.format === "toml"
+            ? objectSchema.parse(parseToml(original))
+            : parseObject(original);
+        const servers = parseOptionalObject(client.format === "toml" ? document.mcp_servers : document.mcpServers);
+        return sameConfiguration(servers[PRODUCT_IDENTITY.mcpServerKey], desired);
+    }
+    catch {
+        return false;
+    }
+};
+/** Preflight one client configuration before setup presents any mutations. */
+export const inspectClientConfiguration = async (client, providerEnvironment, command) => {
+    if (client.format === "unsupported")
+        return { status: "already_current" };
+    const transactionPath = await resolveClientConfigTransactionPath(client.configPath);
+    if (transactionPath === undefined)
+        return {
+            status: "invalid",
+            remediation: "The configuration path is unsafe or unresolved. Check ownership and symbolic links before rerunning setup.",
+        };
+    let original;
+    try {
+        original = await readFile(transactionPath, "utf8");
+    }
+    catch (cause) {
+        if (isMissing(cause))
+            return { status: "create" };
+        return {
+            status: "invalid",
+            remediation: "The configuration file could not be read. Check its permissions before rerunning setup.",
+        };
+    }
+    const desired = clientConfigurationDesired(providerEnvironment, command);
+    try {
+        const document = client.format === "toml"
+            ? objectSchema.parse(parseToml(original))
+            : parseObject(original);
+        const servers = parseOptionalObject(client.format === "toml" ? document.mcp_servers : document.mcpServers);
+        if (sameConfiguration(servers[PRODUCT_IDENTITY.mcpServerKey], desired))
+            return { status: "already_current" };
+    }
+    catch {
+        return {
+            status: "invalid",
+            remediation: "The existing configuration is malformed. Repair it before setup applies any other changes.",
+        };
+    }
+    return {
+        status: "update",
+        backupPath: `${client.configPath}.rea.backup`,
+    };
+};
+const objectSchema = z.record(z.string(), z.unknown());
+const parseOptionalObject = (value) => value === undefined ? {} : objectSchema.parse(value);
+const parseObject = (text) => objectSchema.parse(JSON.parse(text));
+const isMissing = (cause) => cause instanceof Error && "code" in cause && cause.code === "ENOENT";
+const sameConfiguration = (left, right) => JSON.stringify(left) === JSON.stringify(right);
+const preserveConfigBackup = async (source, destination) => {
+    try {
+        await copyFile(source, destination, fsConstants.COPYFILE_EXCL);
+        return true;
+    }
+    catch (cause) {
+        return cause instanceof Error && "code" in cause && cause.code === "EEXIST";
+    }
+};
+const restoreConfig = async (path, original) => {
+    try {
+        if (original === undefined)
+            await rm(path, { force: true });
+        else
+            await writeFile(path, original, { encoding: "utf8", mode: 0o600 });
+    }
+    catch {
+        // The backup remains available for the remediation reported by setup.
+    }
+};
+const clientConfigurationDesired = (providerEnvironment, command) => {
+    const environment = Object.fromEntries(Object.entries(providerEnvironment).sort(([left], [right]) => left.localeCompare(right)));
+    return {
+        command: command[0] ?? PRODUCT_IDENTITY.cliBinary,
+        args: command.slice(1),
+        ...(Object.keys(environment).length === 0 ? {} : { env: environment }),
+    };
+};
+const normalizeProviderEnvironment = (environment) => typeof environment === "string"
+    ? { HOPPER_LAUNCHER_PATH: environment }
+    : environment;

package/dist/application/SetupClients.js

@@ -11,12 +11,34 @@ const failedConfigurationMessage = (reason) => {
 export const configureDetectedClients = async (options) => {
     let failure;
     for (const client of options.detectedClients) {
+        const actionId = `configure_client:${client.name}`;
+        const label = client.displayName ?? client.name;
+        options.onProgress?.({ actionId, label, state: "started" });
         const result = await options.host.configureClient(client, options.providerEnvironment, options.command);
         options.clients[client.name] = result;
-        if (result.status === "failed")
+        if (result.status === "failed") {
             failure ??= failedConfigurationMessage(result.reason);
-        else if (result.status === "configured")
+            options.onProgress?.({
+                actionId,
+                label,
+                state: "failed",
+                detail: failedConfigurationMessage(result.reason),
+            });
+        }
+        else if (result.status === "configured") {
             options.appliedActions.push(`configured_${client.name}`);
+            options.onProgress?.({ actionId, label, state: "completed" });
+        }
+        else {
+            options.onProgress?.({
+                actionId,
+                label,
+                state: "warning",
+                detail: result.status === "unchanged"
+                    ? "Already current"
+                    : "Manual configuration required",
+            });
+        }
     }
     return failure;
 };

package/dist/application/SetupPlan.js

@@ -1,38 +1,149 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { PRODUCT_IDENTITY } from "../identity.js";
+import { linuxHopperInstallDisclosure, } from "./LinuxHopper.js";
+import { macHopperInstallDisclosure } from "./MacHopper.js";
 /** Build the complete setup mutation plan before approval. */
-export const setupPlan = (platform, installHopper, installSkill, clients, providerEnvironment) => [
-    ...(installHopper
+const setupPlan = (input) => [
+    ...(input.installHopper
         ? [
             {
+                id: "install_hopper",
                 kind: "install_hopper",
-                target: platform === "darwin"
-                    ? "~/Applications/Hopper Disassembler.app"
+                label: "Hopper deep-analysis provider",
+                target: input.platform === "darwin"
+                    ? join(homedir(), "Applications/Hopper Disassembler.app")
                     : "system package manager",
-                detail: platform === "linux"
+                detail: input.platform === "linux"
                     ? "Download, verify, and install Hopper plus its Xvfb demo-session dependencies. For the supported demo build, REA uses a private display and selects Hopper's offered demo mode for each analysis session."
                     : "Download the official Hopper package, verify it, and install it. Hopper may show its demo or license prompt when first opened.",
                 external: true,
+                operation: "install",
+                ...(input.platform === "linux"
+                    ? input.linuxPackageFamily === undefined
+                        ? {}
+                        : linuxDisclosure(input.linuxPackageFamily)
+                    : {
+                        networkOrigins: macHopperInstallDisclosure.networkOrigins,
+                        commands: macHopperInstallDisclosure.commands,
+                    }),
             },
         ]
         : []),
-    ...clients
-        .filter(({ format }) => format !== "unsupported")
-        .map((client) => ({
+    ...input.clients
+        .filter(({ client }) => client.format !== "unsupported")
+        .map(({ client, operation, backupPath }) => ({
+        id: `configure_client:${client.name}`,
         kind: "configure_client",
+        label: client.displayName ?? client.name,
         target: client.configPath,
-        detail: clientConfigurationDetail(client.name, providerEnvironment),
+        detail: clientConfigurationDetail(client.displayName ?? client.name, input.providerEnvironment),
         external: false,
+        operation,
+        ...(backupPath === undefined ? {} : { backupPath }),
     })),
-    ...(installSkill
+    ...(input.installSkill
         ? [
             {
+                id: "install_skill",
                 kind: "install_skill",
-                target: "~/.agents/skills/rea-analysis/SKILL.md",
-                detail: "Install or update the bundled REA analysis skill.",
+                label: "REA reverse-engineering skill",
+                target: join(homedir(), ".agents/skills", PRODUCT_IDENTITY.skillName, "SKILL.md"),
+                detail: "Install or update the bundled REA reverse-engineering skill.",
                 external: false,
+                operation: "install",
             },
         ]
         : []),
 ];
+/** Discover and preflight the complete set of selectable setup actions. */
+export const discoverSetupActions = async (input) => {
+    const { host, providerEnvironment, command } = input;
+    const initialDoctor = await host.doctor();
+    const linuxHopperRepairNeeded = initialDoctor.checks.some(({ name, ok, detail }) => !ok &&
+        (name === "hopper-demo-runtime" ||
+            (name === "hopper-version" && detail === "/opt/hopper/bin/Hopper")));
+    const installHopper = input.forceHopperInstall ||
+        (input.proposeHopper &&
+            (Object.keys(providerEnvironment).length === 0 ||
+                linuxHopperRepairNeeded));
+    const [allDetectedClients, skillNeedsInstall] = await Promise.all([
+        host.detectedClients(),
+        host.skillNeedsInstall(),
+    ]);
+    const selectedClientIdSet = input.selectedClientIds === undefined
+        ? undefined
+        : new Set(input.selectedClientIds);
+    const detectedClients = allDetectedClients.filter(({ name }) => selectedClientIdSet === undefined || selectedClientIdSet.has(name));
+    const installSkill = input.installSkillSelection === false ? false : skillNeedsInstall;
+    const clients = installHopper
+        ? detectedClients
+        : await filterClientsNeedingConfigure({
+            host,
+            clients: detectedClients,
+            providerEnvironment,
+            command,
+        });
+    const inspections = await inspectClients({
+        host,
+        clients,
+        providerEnvironment,
+        command,
+    });
+    const invalid = inspections.find(({ inspection }) => inspection.status === "invalid");
+    const blocker = invalid?.inspection.status === "invalid"
+        ? `${invalid.client.displayName ?? invalid.client.name}: ${invalid.inspection.remediation}`
+        : undefined;
+    const clientPlans = inspections.flatMap(({ client, inspection }) => inspection.status === "create" ||
+        inspection.status === "update" ||
+        (installHopper && inspection.status === "already_current")
+        ? [
+            {
+                client,
+                operation: inspection.status === "already_current"
+                    ? "update"
+                    : inspection.status,
+                ...(inspection.status !== "already_current" &&
+                    inspection.backupPath !== undefined
+                    ? { backupPath: inspection.backupPath }
+                    : {}),
+            },
+        ]
+        : []);
+    const linuxDistribution = host.platform === "linux" ? await host.linuxDistribution() : undefined;
+    return {
+        installHopper,
+        installSkill,
+        detectedClients: clientPlans.map(({ client }) => client),
+        plannedActions: setupPlan({
+            platform: host.platform,
+            installHopper,
+            installSkill,
+            clients: clientPlans,
+            providerEnvironment,
+            ...(linuxDistribution?.packageFamily === undefined
+                ? {}
+                : { linuxPackageFamily: linuxDistribution.packageFamily }),
+        }),
+        blocker,
+    };
+};
+const inspectClients = async (input) => Promise.all(input.clients.map(async (client) => ({
+    client,
+    inspection: (await input.host.inspectClientConfiguration?.(client, input.providerEnvironment, input.command)) ?? { status: "update" },
+})));
+const filterClientsNeedingConfigure = async (input) => {
+    const needs = await Promise.all(input.clients.map((client) => input.host.clientNeedsConfigure(client, input.providerEnvironment, input.command)));
+    return input.clients.filter((_, index) => needs[index]);
+};
+const linuxDisclosure = (family) => {
+    const disclosure = linuxHopperInstallDisclosure(family, process.getuid?.() === 0);
+    return {
+        networkOrigins: [disclosure.downloadUrl],
+        commands: disclosure.commands,
+        integrity: `${String(disclosure.expectedBytes)} bytes · SHA-1 ${disclosure.expectedSha1}`,
+    };
+};
 const clientConfigurationDetail = (client, environment) => {
     const entries = Object.entries(environment)
         .sort(([left], [right]) => left.localeCompare(right))

package/dist/application/SetupSkill.js

@@ -2,15 +2,26 @@ import { mkdir, readFile, rm } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import writeFileAtomic from "write-file-atomic";
 import { PRODUCT_IDENTITY } from "../identity.js";
+const skillDestination = (home, name) => join(home, ".agents/skills", name, "SKILL.md");
+const readOptionalText = async (path) => {
+    try {
+        return await readFile(path, "utf8");
+    }
+    catch (cause) {
+        if (cause instanceof Error && "code" in cause && cause.code === "ENOENT")
+            return undefined;
+        throw cause;
+    }
+};
 const canonicalSkillFiles = async (home) => ({
-    destination: join(home, ".agents/skills", PRODUCT_IDENTITY.skillName, "SKILL.md"),
+    destination: skillDestination(home, PRODUCT_IDENTITY.skillName),
     content: await readFile(new URL(`../../skills/${PRODUCT_IDENTITY.skillName}/SKILL.md`, import.meta.url), "utf8"),
 });
 /** Report whether setup would change the managed REA skill. */
 export const canonicalSkillNeedsInstall = async (home) => {
     try {
         const { content, destination } = await canonicalSkillFiles(home);
-        return (await readFile(destination, "utf8")) !== content;
+        return (await readOptionalText(destination)) !== content;
     }
     catch {
         return true;
@@ -18,43 +29,46 @@ export const canonicalSkillNeedsInstall = async (home) => {
 };
 /** Transactionally install or upgrade the versioned canonical REA skill. */
 export const installCanonicalSkill = async (home) => {
-    let destination = join(home, ".agents/skills", PRODUCT_IDENTITY.skillName, "SKILL.md");
+    let destination = skillDestination(home, PRODUCT_IDENTITY.skillName);
     let backup = `${destination}.rea.backup`;
     let original;
+    let canonicalChanged = false;
     try {
         const canonical = await canonicalSkillFiles(home);
         destination = canonical.destination;
         backup = `${destination}.rea.backup`;
         const { content } = canonical;
-        original = await readFile(destination, "utf8").catch(() => undefined);
+        original = await readOptionalText(destination);
         if (original === content)
             return "unchanged";
         await mkdir(dirname(destination), { recursive: true });
-        if (original !== undefined)
+        if (original !== undefined && original !== content)
             await writeFileAtomic(backup, original, {
                 encoding: "utf8",
                 mode: 0o600,
             });
-        await writeFileAtomic(destination, content, {
-            encoding: "utf8",
-            mode: 0o600,
-        });
+        canonicalChanged = original !== content;
+        if (canonicalChanged)
+            await writeFileAtomic(destination, content, {
+                encoding: "utf8",
+                mode: 0o600,
+            });
         if ((await readFile(destination, "utf8")) !== content)
             throw new Error("skill readback mismatch");
         return "installed";
     }
     catch {
         try {
-            if (original === undefined)
+            if (canonicalChanged && original === undefined)
                 await rm(destination, { force: true });
-            else
+            else if (canonicalChanged && original !== undefined)
                 await writeFileAtomic(destination, original, {
                     encoding: "utf8",
                     mode: 0o600,
                 });
         }
         catch {
-            // The backup remains beside the skill for explicit operator recovery.
+            // The canonical backup remains beside the skill for operator recovery.
         }
         return "failed";
     }

package/dist/application/SupportedClients.js

@@ -59,6 +59,7 @@ export const SUPPORTED_CLIENT_DEFINITIONS = [
 /** Describe every client location that setup, doctor, or uninstall may inspect. */
 export const supportedClients = (home) => SUPPORTED_CLIENT_DEFINITIONS.map((definition) => ({
     name: definition.name,
+    displayName: definition.displayName,
     configPath: join(home, ...definition.configPath),
     markerPath: join(home, ...definition.markerPath),
     format: definition.format,

package/dist/application/Uninstall.js

@@ -39,7 +39,7 @@ export const runUninstall = async (purgeData, host = systemUninstallHost()) => {
 export const systemUninstallHost = (home = homedir(), fileSystem = systemFileSystem) => ({
     clients: () => Promise.resolve(supportedClients(home)),
     removeClient: (client) => removeClient(client, fileSystem),
-    removeSkill: () => removeManagedPath(join(home, ".agents/skills", PRODUCT_IDENTITY.skillName), "skill", fileSystem),
+    removeSkill: () => removeManagedSkills(home, fileSystem),
     purgeData: async () => [
         await removeManagedPath(join(home, ".rea/cache"), "cache", fileSystem),
         await removeManagedPath(join(home, ".rea/state"), "state", fileSystem),
@@ -127,8 +127,10 @@ const isOwnedRegistration = (value) => {
         args.length === 1 &&
         args[0] === "mcp") ||
         (command === "npx" &&
-            JSON.stringify(args) ===
-                JSON.stringify(["-y", PRODUCT_IDENTITY.packageName, "mcp"])));
+            (JSON.stringify(args) ===
+                JSON.stringify(["-y", PRODUCT_IDENTITY.packageSpecifier, "mcp"]) ||
+                JSON.stringify(args) ===
+                    JSON.stringify(["-y", PRODUCT_IDENTITY.packageName, "mcp"]))));
 };
 const removeManagedPath = async (path, name, fileSystem) => {
     try {
@@ -144,6 +146,7 @@ const removeManagedPath = async (path, name, fileSystem) => {
             : item(name, "failed", "This item could not be removed. Check file permissions, then rerun uninstall.");
     }
 };
+const removeManagedSkills = async (home, fileSystem) => removeManagedPath(join(home, ".agents/skills", PRODUCT_IDENTITY.skillName), "skill", fileSystem);
 const item = (name, status, detail) => ({ name, status, detail });
 const objectSchema = z.record(z.string(), z.unknown());
 const optionalObject = (value) => value === undefined ? {} : objectSchema.parse(value);

package/dist/application/WindowsCapabilities.js

@@ -0,0 +1,86 @@
+import { constants } from "node:fs";
+import { mkdtemp, rm, symlink, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { probeProcessCaptureCapability, } from "./ProcessCaptureCapability.js";
+/** Probe named prerequisites without converting missing controls into support. */
+export const probeWindowsCapabilities = async (dependencies = systemDependencies()) => {
+    const [symlinkCreation, pty] = await Promise.all([
+        dependencies.probeSymlinkCreation(),
+        dependencies.probePty(),
+    ]);
+    return {
+        platform: dependencies.platform,
+        architecture: dependencies.architecture,
+        capabilities: {
+            symlink_creation: symlinkCreation,
+            no_follow_open: dependencies.probeNoFollowOpen(),
+            private_acl: dependencies.probePrivateAcl(),
+            unix_domain_socket: dependencies.probeUnixDomainSocket(),
+            pty: {
+                available: pty.available,
+                reason: pty.available ? null : pty.reason,
+            },
+        },
+    };
+};
+const systemDependencies = () => ({
+    platform: process.platform,
+    architecture: process.arch,
+    probeSymlinkCreation,
+    probeNoFollowOpen: () => systemNoFollowOpenCapability(process.platform, constants.O_NOFOLLOW),
+    probePrivateAcl: () => ({
+        available: false,
+        reason: "Windows ACL enforcement is not implemented by this REA build",
+    }),
+    probeUnixDomainSocket: () => process.platform === "win32"
+        ? {
+            available: false,
+            reason: "Node path-based IPC uses named pipes on Windows",
+        }
+        : { available: true, reason: null },
+    probePty: probeProcessCaptureCapability,
+});
+/** Report pathname no-follow support without treating it as Windows authority. */
+export const systemNoFollowOpenCapability = (platform, noFollow) => {
+    if (platform === "win32")
+        return {
+            available: false,
+            reason: "Windows reparse-safe handle admission is not implemented",
+        };
+    return typeof noFollow === "number"
+        ? { available: true, reason: null }
+        : {
+            available: false,
+            reason: "O_NOFOLLOW is unavailable in this Node runtime",
+        };
+};
+const probeSymlinkCreation = async () => {
+    const root = await mkdtemp(join(tmpdir(), "rea-symlink-probe-"));
+    const target = join(root, "target");
+    const link = join(root, "link");
+    try {
+        await writeFile(target, "probe");
+        await symlink(target, link, "file");
+        return { available: true, reason: null };
+    }
+    catch (cause) {
+        return {
+            available: false,
+            reason: cause instanceof Error &&
+                "code" in cause &&
+                typeof cause.code === "string"
+                ? cause.code
+                : "symlink creation failed",
+        };
+    }
+    finally {
+        try {
+            await rm(root, { recursive: true, force: true });
+        }
+        catch {
+            // Cleanup failure must not replace the machine-readable probe outcome.
+            // The probe root lives beneath the OS temporary directory and is unique.
+        }
+    }
+};

package/dist/artifacts/AsarArtifactReader.js

@@ -70,6 +70,13 @@ export class AsarArtifactReader {
             return Promise.resolve(Readable.from(extractFile(this.path, entry.adapterKey, false)));
         }
         catch (cause) {
+            if (entry.unpacked && isMissingFile(cause))
+                return Promise.reject(new ArtifactReaderFailure("unavailable", `ASAR unpacked entry bytes are unavailable: ${entry.path}`, { cause }, {
+                    logicalPath: entry.path,
+                    declaredSha256: entry.declaredSha256,
+                    calculatedSha256: null,
+                    unpacked: true,
+                }));
             return Promise.reject(asarFailure(this.path, `read ${entry.path}`, cause));
         }
     }
@@ -87,3 +94,7 @@ const abortIfNeeded = (signal) => {
 const asarFailure = (path, operation, cause) => cause instanceof ArtifactReaderFailure
     ? cause
     : new ArtifactReaderFailure("format", `Malformed or unreadable ASAR during ${operation}: ${path}`, { cause });
+const isMissingFile = (cause) => typeof cause === "object" &&
+    cause !== null &&
+    "code" in cause &&
+    cause.code === "ENOENT";