rea-agents 6.3.0 → 6.4.0

package/dist/application/RegularFileRead.js

@@ -1,17 +1,103 @@
-import { openRegularFile } from "../filesystem/RegularFile.js";
+import { lstat, stat } from "node:fs/promises";
+import { RegularFileAdmissionFailure, openRegularFile, sameRegularFileState, RegularFileChangedError, } from "../filesystem/RegularFile.js";
+import { OwnedFileHandle } from "../filesystem/OwnedFileHandle.js";
+import { readBoundedFileBytes } from "../process/BoundedFileBytes.js";
+/** A close failed after reading; this error transfers the exact handle owner. */
+export class RegularFileCleanupFailure extends Error {
+    path;
+    owner;
+    outcome;
+    cleanupCause;
+    constructor(path, owner, outcome, cleanupCause) {
+        super(`Regular file cleanup failed: ${path}`, {
+            cause: outcome.kind === "failed" ? outcome.cause : cleanupCause,
+        });
+        this.path = path;
+        this.owner = owner;
+        this.outcome = outcome;
+        this.cleanupCause = cleanupCause;
+        this.name = "RegularFileCleanupFailure";
+    }
+}
+/** Retry a failed close through its retained owner and report any remaining cleanup. */
+export const retryRegularFileCleanup = async (failure, resources) => {
+    const released = await resources.release({
+        kind: "file-handle",
+        handle: failure.owner,
+        resource: failure.path,
+    });
+    if (released.kind === "released")
+        return { outcome: failure.outcome };
+    return {
+        outcome: failure.outcome,
+        cleanup: {
+            reason: `${failureMessage(failure.cleanupCause)}; retry: ${failureMessage(released.cause)}`,
+            resources: [failure.path],
+        },
+    };
+};
+const failureMessage = (cause) => cause instanceof Error ? cause.message : String(cause);
 /** Admit one regular-file handle, retain it through the consumer, and always close it. */
-export const withRegularFile = async (path, read, signal) => {
-    const handle = await openRegularFile(path, { symlinks: "follow", signal });
+export const withRegularFile = async (path, read, options = {}) => {
+    const { signal } = options;
+    let handle;
+    try {
+        handle = await openRegularFile(path, {
+            symlinks: options.symlinks ?? "follow",
+            signal,
+        });
+    }
+    catch (cause) {
+        if (!(cause instanceof RegularFileAdmissionFailure))
+            throw cause;
+        throw new RegularFileCleanupFailure(path, cause.owner, { kind: "failed", cause: cause.cause }, cause.cleanupCause);
+    }
+    const owner = new OwnedFileHandle(handle);
+    let outcome;
     try {
         const stats = await handle.stat();
         signal?.throwIfAborted();
         const value = await read(handle, stats);
         signal?.throwIfAborted();
-        return value;
+        const [opened, currentPath] = await Promise.all([
+            handle.stat(),
+            options.symlinks === "reject" ? lstat(path) : stat(path),
+        ]);
+        if (!sameRegularFileState(stats, opened) ||
+            !sameRegularFileState(stats, currentPath))
+            throw new RegularFileChangedError(path);
+        outcome = { kind: "completed", value };
+    }
+    catch (cause) {
+        outcome = { kind: "failed", cause };
     }
-    finally {
-        await handle.close();
+    try {
+        await owner.close();
+    }
+    catch (cleanupCause) {
+        throw new RegularFileCleanupFailure(path, owner, outcome, cleanupCause);
     }
+    if (outcome.kind === "failed")
+        throw outcome.cause;
+    return outcome.value;
 };
 /** Admit a regular file without waiting for a pipe, then read its verified handle. */
-export const readRegularFile = (path, signal) => withRegularFile(path, (handle) => handle.readFile({ signal }), signal);
+export const readRegularFile = (path, options = {}) => withRegularFile(path, async (handle, stats) => {
+    const bytes = await readBoundedFileBytes(handle, stats.size, options.signal);
+    if (bytes === undefined || bytes.length !== stats.size)
+        throw new RegularFileChangedError(path);
+    return bytes;
+}, options);
+/** Read one admitted regular file as UTF-8 without waiting on a pipe. */
+export const readRegularFileText = async (path, options = {}) => {
+    try {
+        return (await readRegularFile(path, options)).toString("utf8");
+    }
+    catch (cause) {
+        if (cause instanceof RegularFileCleanupFailure &&
+            cause.outcome.kind === "completed" &&
+            Buffer.isBuffer(cause.outcome.value))
+            throw new RegularFileCleanupFailure(cause.path, cause.owner, { kind: "completed", value: cause.outcome.value.toString("utf8") }, cause.cleanupCause);
+        throw cause;
+    }
+};

package/dist/application/Setup.js

@@ -2,8 +2,49 @@ import { manualRegistrationRemediation, } from "./SupportedClients.js";
 import { configureDetectedClients } from "./SetupClients.js";
 import { discoverSetupState, planSetupActions } from "./SetupPlan.js";
 import { filterClientsNeedingConfigure, hostRemediation, systemSetupHost, } from "./SetupHost.js";
+import { AnalysisError } from "../domain/analysisErrorBase.js";
+import { analysisErrorWithCleanupFailure } from "../domain/analysisErrorCleanup.js";
+import { ProviderCleanupError } from "../domain/providerCleanupError.js";
 /** Discover, approve, and apply setup actions idempotently. */
 export const runSetup = async (options, host = systemSetupHost(), confirm) => {
+    let result;
+    let primaryFailure;
+    let threw = false;
+    try {
+        result = await runSetupWorkflow(options, host, confirm);
+    }
+    catch (cause) {
+        threw = true;
+        primaryFailure = cause;
+    }
+    let cleanupFailure;
+    try {
+        cleanupFailure = await host.close?.();
+    }
+    catch (cause) {
+        cleanupFailure = `Setup resource cleanup failed: ${failureMessage(cause)}`;
+    }
+    if (threw) {
+        if (cleanupFailure !== undefined && primaryFailure instanceof AnalysisError)
+            throw analysisErrorWithCleanupFailure(primaryFailure, new ProviderCleanupError("setup", primaryFailure.cleanupResources, { reason: cleanupFailure }, { operation: "setup" }), "setup");
+        if (cleanupFailure !== undefined)
+            throw new AggregateError([primaryFailure, new Error(cleanupFailure)], "Setup and resource cleanup failed.", { cause: primaryFailure });
+        throw primaryFailure;
+    }
+    if (result === undefined)
+        throw new Error("Setup returned no result.");
+    if (cleanupFailure === undefined)
+        return result;
+    return {
+        ...result,
+        status: "needs_human",
+        code: result.code ?? "cleanup_failed",
+        remediation: result.remediation
+            ? `${result.remediation} ${cleanupFailure}`
+            : cleanupFailure,
+    };
+};
+const runSetupWorkflow = async (options, host, confirm) => {
     const appliedActions = [];
     let plannedActions = [];
     const clients = {};
@@ -27,6 +68,7 @@ export const runSetup = async (options, host = systemSetupHost(), confirm) => {
         options.readinessScope?.clients === undefined &&
         options.allDetectedClients !== true &&
         options.installHopper !== true &&
+        options.skillClientIds === undefined &&
         options.installSkill === undefined;
     const interactiveSelection = confirm !== undefined && !options.structured && clientSelectionAllowed;
     let selectedClientIds = options.allDetectedClients
@@ -34,9 +76,11 @@ export const runSetup = async (options, host = systemSetupHost(), confirm) => {
         : (options.clientIds ??
             options.readinessScope?.clients ??
             discovery.defaultClientIds);
-    let skillNeedsInstall = await host.skillNeedsInstall(selectedClientIds);
+    let selectedSkillClientIds = options.skillClientIds ?? selectedClientIds;
+    let skillNeedsInstall = await host.skillNeedsInstall(selectedSkillClientIds);
     let skillSelected = options.installSkill === true ||
-        (options.installSkill !== false && selectedClientIds.length > 0);
+        (options.installSkill !== false &&
+            (selectedClientIds.length > 0 || selectedSkillClientIds.length > 0));
     let installSkill = skillSelected && skillNeedsInstall;
     let planDiscovery = discovery;
     if (interactiveSelection) {
@@ -89,6 +133,7 @@ export const runSetup = async (options, host = systemSetupHost(), confirm) => {
                     selectedClientIds.length === 0) ||
                 (options.installSkill !== false && selectedClientIds.length > 0);
         installSkill = skillSelected && skillNeedsInstall;
+        selectedSkillClientIds = selectedClientIds;
     }
     const planned = await planSetupActions({
         discovery: planDiscovery,
@@ -96,7 +141,7 @@ export const runSetup = async (options, host = systemSetupHost(), confirm) => {
         providerEnvironment,
         command: host.registrationCommand,
         clientIds: selectedClientIds,
-        skillClientIds: selectedClientIds,
+        skillClientIds: selectedSkillClientIds,
         installSkill,
     });
     plannedActions = planned.plannedActions;
@@ -188,7 +233,7 @@ export const runSetup = async (options, host = systemSetupHost(), confirm) => {
     if (clientFailure !== undefined)
         return fail(clientFailure);
     if (planSelection.installSkill &&
-        !(await installSkillAction(host, options, appliedActions, selectedClientIds)))
+        !(await installSkillAction(host, options, appliedActions, selectedSkillClientIds)))
         return fail("REA analysis skill could not be installed or verified. Check permissions for its planned skill directories, then rerun setup.");
     const doctor = summarizeDoctor(await host.doctor(readinessScope));
     const remediation = combineRemediation(finalSetupRemediation(host.platform, appliedActions.includes("installed_hopper"), doctor.healthy, hopperPath), manualRemediation);
@@ -234,8 +279,10 @@ const installHopperAction = async (input) => {
     emitProgress(input.options, {
         actionId: "install_hopper",
         label,
-        state: "completed",
-        detail: installed.launcherPath,
+        state: installed.cleanupFailure === undefined ? "completed" : "warning",
+        detail: installed.cleanupFailure === undefined
+            ? installed.launcherPath
+            : `${installed.launcherPath}; ${installed.cleanupFailure}`,
     });
     const providerEnvironment = {
         ...input.providerEnvironment,
@@ -345,3 +392,4 @@ const summarizeDoctor = (report) => ({
             },
         }),
 });
+const failureMessage = (cause) => cause instanceof Error ? cause.message : String(cause);

package/dist/application/SetupClientConfiguration.js

@@ -1,42 +1,82 @@
+import { readClientPolicyBlock } from "./GeminiClientSettings.js";
+import { readClientConfigurationFiles } from "./ClientConfigurationFiles.js";
 import { clientRegistrationEntry, clientConfigurationValuesEqual, clientServerListedDisabled, clientServerPath, legacyClientServerPath, OMP_DISABLED_SERVERS_KEY, parseClientConfiguration, serializeClientConfiguration, withClientServers, } from "./ClientConfigurationDocument.js";
 import { constants as fsConstants } from "node:fs";
-import { copyFile, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { copyFile, mkdir, rm, writeFile } from "node:fs/promises";
 import { dirname } from "node:path";
 import writeFileAtomic from "write-file-atomic";
+import { clientRegistrationEnvironment } from "./ClientRegistrationEnvironment.js";
 import { PRODUCT_IDENTITY } from "../identity.js";
 import { npxRegistrationCommand } from "./ClientRegistrationIdentity.js";
 import { MCP_STARTUP_POLICY } from "../mcpStartupPolicy.js";
 import { resolveClientConfigTransactionPath } from "./ClientConfigPath.js";
+import { readRegularFileText, RegularFileCleanupFailure, } from "./RegularFileRead.js";
 /** Configure one supported client's native stdio MCP registration shape. */
 export const configureClientConfiguration = (client, environment = {}, command = npxRegistrationCommand()) => {
-    if (client.format === undefined || client.format === "unsupported")
-        return Promise.resolve({ status: "failed", reason: "readback" });
-    return configureClientDocument(client, environment, command, client.format);
+    if (client.configPathError !== undefined)
+        return Promise.resolve({ status: "failed", reason: "path" });
+    return configureClientDocument(client, environment, command);
 };
-const configureClientDocument = async (client, environment, command, format) => {
+const configureClientDocument = async (client, environment, command) => {
+    const format = client.format;
+    if (format === undefined || format === "unsupported")
+        return { status: "failed", reason: "readback" };
+    const files = await readClientConfigurationFiles(client);
+    if (!files.ok) {
+        throwCleanupFailure(files.error);
+        return { status: "failed", reason: "readback" };
+    }
+    const policy = await readClientPolicyBlock(client, undefined, clientConfigurationDesired(client, environment, command, files.value.at(-1)));
+    if (!policy.ok) {
+        throwCleanupFailure(policy.error);
+        return { status: "failed", reason: "readback" };
+    }
+    if (policy.value !== undefined)
+        return { status: "failed", reason: "readback" };
     const transactionPath = await resolveClientConfigTransactionPath(client.configPath);
     if (transactionPath === undefined)
         return { status: "failed", reason: "path" };
     let original;
     try {
-        original = await readFile(transactionPath, "utf8");
+        original = await readRegularFileText(transactionPath);
     }
     catch (cause) {
+        if (cause instanceof RegularFileCleanupFailure)
+            throw cause;
         if (!isMissing(cause))
             return { status: "failed", reason: "readback" };
     }
     let parsed;
     try {
         parsed = parseClientConfiguration(original ?? (format === "toml" || format === "grok" ? "" : "{}"), format);
+        const policy = await readClientPolicyBlock(client, parsed, clientConfigurationDesired(client, environment, command, parsed));
+        if (!policy.ok) {
+            throwCleanupFailure(policy.error);
+            return { status: "failed", reason: "readback" };
+        }
+        if (policy.value !== undefined)
+            return { status: "failed", reason: "readback" };
     }
     catch (cause) {
+        if (cause instanceof RegularFileCleanupFailure)
+            throw cause;
         // Malformed existing configuration fails the readback gate.
         void cause;
         return { status: "failed", reason: "readback" };
     }
-    const desired = clientConfigurationDesired(client, environment, command, parsed.dialect);
+    const desired = clientConfigurationDesired(client, environment, command, parsed);
     if (registrationCurrent(parsed, desired))
         return { status: "unchanged" };
+    return persistClientConfiguration({
+        client,
+        transactionPath,
+        format,
+        original,
+        parsed,
+        desired,
+    });
+};
+const persistClientConfiguration = async ({ client, transactionPath, format, original, parsed, desired, }) => {
     const backupPath = original === undefined ? undefined : `${client.configPath}.rea.backup`;
     if (backupPath !== undefined &&
         !(await preserveConfigBackup(transactionPath, backupPath)))
@@ -74,13 +114,15 @@ const configureClientDocument = async (client, environment, command, format) =>
         return { status: "failed", reason: "write" };
     }
     try {
-        const readback = parseClientConfiguration(await readFile(transactionPath, "utf8"), format);
+        const readback = parseClientConfiguration(await readRegularFileText(transactionPath), format);
         if (!registrationCurrent(readback, desired)) {
             await restoreConfig(transactionPath, original);
             return { status: "failed", reason: "readback" };
         }
     }
     catch (cause) {
+        if (cause instanceof RegularFileCleanupFailure)
+            throw cause;
         // Readback failure restores the transaction before reporting.
         void cause;
         await restoreConfig(transactionPath, original);
@@ -93,12 +135,27 @@ const configureClientDocument = async (client, environment, command, format) =>
 };
 /** Determine whether an existing client configuration matches the desired registration. */
 export const clientConfigurationAligned = async (client, providerEnvironment, command) => {
+    if (client.configPathError !== undefined)
+        return false;
     try {
-        const original = await readFile(client.configPath, "utf8");
+        const files = await readClientConfigurationFiles(client);
+        if (!files.ok) {
+            throwCleanupFailure(files.error);
+            return false;
+        }
+        const original = await readRegularFileText(client.configPath);
         const parsed = parseClientConfiguration(original, client.format);
-        return registrationCurrent(parsed, clientConfigurationDesired(client, providerEnvironment, command, parsed.dialect));
+        const policy = await readClientPolicyBlock(client, parsed, clientConfigurationDesired(client, providerEnvironment, command, parsed));
+        if (!policy.ok) {
+            throwCleanupFailure(policy.error);
+            return false;
+        }
+        return (policy.value === undefined &&
+            registrationCurrent(parsed, clientConfigurationDesired(client, providerEnvironment, command, parsed)));
     }
     catch (cause) {
+        if (cause instanceof RegularFileCleanupFailure)
+            throw cause;
         // Unreadable configuration is treated as not aligned so setup repairs it.
         void cause;
         return false;
@@ -106,8 +163,28 @@ export const clientConfigurationAligned = async (client, providerEnvironment, co
 };
 /** Preflight one client configuration before setup presents any mutations. */
 export const inspectClientConfiguration = async (client, providerEnvironment, command) => {
+    if (client.configPathError !== undefined)
+        return { status: "invalid", remediation: client.configPathError };
     if (client.format === "unsupported")
         return { status: "already_current" };
+    const files = await readClientConfigurationFiles(client);
+    if (!files.ok) {
+        throwCleanupFailure(files.error);
+        return {
+            status: "invalid",
+            remediation: files.error.detail,
+        };
+    }
+    const policy = await readClientPolicyBlock(client, undefined, clientConfigurationDesired(client, providerEnvironment, command, files.value.at(-1)));
+    if (!policy.ok) {
+        throwCleanupFailure(policy.error);
+        return {
+            status: "invalid",
+            remediation: policy.error.detail,
+        };
+    }
+    if (policy.value !== undefined)
+        return { status: "invalid", remediation: policy.value };
     const transactionPath = await resolveClientConfigTransactionPath(client.configPath);
     if (transactionPath === undefined)
         return {
@@ -116,23 +193,37 @@ export const inspectClientConfiguration = async (client, providerEnvironment, co
         };
     let original;
     try {
-        original = await readFile(transactionPath, "utf8");
+        original = await readRegularFileText(transactionPath);
     }
     catch (cause) {
+        if (cause instanceof RegularFileCleanupFailure)
+            throw cause;
         if (isMissing(cause))
             return { status: "create" };
         return {
             status: "invalid",
-            remediation: "The configuration file could not be read. Check its permissions before rerunning setup.",
+            remediation: `The configuration file could not be read. Check its permissions before rerunning setup. ${cause instanceof Error ? cause.message : String(cause)}`,
         };
     }
     try {
         const parsed = parseClientConfiguration(original, client.format);
-        const desired = clientConfigurationDesired(client, providerEnvironment, command, parsed.dialect);
+        const policy = await readClientPolicyBlock(client, parsed, clientConfigurationDesired(client, providerEnvironment, command, parsed));
+        if (!policy.ok) {
+            throwCleanupFailure(policy.error);
+            return {
+                status: "invalid",
+                remediation: policy.error.detail,
+            };
+        }
+        if (policy.value !== undefined)
+            return { status: "invalid", remediation: policy.value };
+        const desired = clientConfigurationDesired(client, providerEnvironment, command, parsed);
         if (registrationCurrent(parsed, desired))
             return { status: "already_current" };
     }
     catch (cause) {
+        if (cause instanceof RegularFileCleanupFailure)
+            throw cause;
         // Malformed configuration is reported with the invalid remediation.
         void cause;
         return {
@@ -146,6 +237,10 @@ export const inspectClientConfiguration = async (client, providerEnvironment, co
     };
 };
 const isMissing = (cause) => cause instanceof Error && "code" in cause && cause.code === "ENOENT";
+const throwCleanupFailure = (error) => {
+    if (error.cleanupFailure !== undefined)
+        throw error.cleanupFailure;
+};
 const preserveConfigBackup = async (source, destination) => {
     try {
         await copyFile(source, destination, fsConstants.COPYFILE_EXCL);
@@ -171,9 +266,14 @@ const restoreConfig = async (path, original) => {
 const registrationCurrent = (parsed, desired) => clientConfigurationValuesEqual(parsed.servers[PRODUCT_IDENTITY.mcpServerKey], desired) &&
     !Object.hasOwn(parsed.legacyServers, PRODUCT_IDENTITY.mcpServerKey) &&
     !clientServerListedDisabled(parsed, PRODUCT_IDENTITY.mcpServerKey);
-const clientConfigurationDesired = (client, providerEnvironment, command, format) => {
-    const environment = Object.fromEntries(Object.entries(providerEnvironment).sort(([left], [right]) => left.localeCompare(right)));
-    const registration = clientRegistrationEntry(format ?? "json", command.length === 0 ? [PRODUCT_IDENTITY.cliBinary, "mcp"] : command, environment);
+const clientConfigurationDesired = (client, providerEnvironment, command, parsed) => {
+    const format = parsed?.dialect ?? client.format ?? "json";
+    // Preserve explicitly configured server settings, never the ambient process
+    // environment. Newly discovered provider paths win only for their own keys.
+    const environment = clientRegistrationEnvironment(parsed, providerEnvironment);
+    if (!environment.ok)
+        throw environment.error;
+    const registration = clientRegistrationEntry(format, command.length === 0 ? [PRODUCT_IDENTITY.cliBinary, "mcp"] : command, environment.value);
     return {
         ...registration,
         ...(client.name === "codex" || client.name === "grok_build"

package/dist/application/SetupHost.js

@@ -1,15 +1,19 @@
 import { access } from "node:fs/promises";
 import { resolve } from "node:path";
+import { ArtifactResourceScope } from "../artifacts/ArtifactResourceScope.js";
+import { ArtifactReaderFailure } from "../artifacts/ArtifactReader.js";
+import { ConfigurationError } from "../domain/configurationErrors.js";
 import { PRODUCT_IDENTITY } from "../identity.js";
 import { npxRegistrationCommand } from "./ClientRegistrationIdentity.js";
 import { SUPPORTED_NODE_VERSION_PROSE, supportsNodeVersion, } from "../domain/runtimeVersion.js";
 import { runDoctor, systemDoctorHost } from "./Doctor.js";
 import { installLinuxHopper, readLinuxDistribution, systemLinuxHopperInstallHost, } from "./LinuxHopper.js";
 import { installMacHopper, systemMacHopperInstallHost } from "./MacHopper.js";
-import { supportedClients } from "./SupportedClients.js";
-import { claudeCodeSkillsDirectory as resolveClaudeCodeSkillsDirectory, canonicalSkillNeedsInstall, installCanonicalSkill, } from "./SetupSkill.js";
+import { clientEvidencePaths, supportedClients, } from "./SupportedClients.js";
+import { skillDestinations, canonicalSkillNeedsInstall, installCanonicalSkill, } from "./SetupSkill.js";
 import { clientConfigurationAligned, configureClientConfiguration, inspectClientConfiguration, } from "./SetupClientConfiguration.js";
 import { setupInstallFailure } from "./SetupInstallFailure.js";
+import { RegularFileCleanupFailure, retryRegularFileCleanup, } from "./RegularFileRead.js";
 import { providerRegistrationEnvironment } from "./SetupRegistrationEnvironment.js";
 /** Resolve the executable and arguments used in a managed MCP registration. */
 export const setupRegistrationCommand = (platform, useNpmRunner) => useNpmRunner
@@ -40,22 +44,26 @@ export const hostRemediation = async (host, installHopper) => {
     }
     if ((await host.linuxDistribution())?.supported === true)
         return undefined;
-    return "Automated Hopper setup supports Ubuntu 24.04+, Fedora 41+, Nobara 44+, 64-bit Arch Linux, and CachyOS; configure an existing supported provider instead.";
+    return "Automated Hopper setup supports Ubuntu 24.04+, Fedora 41+, Nobara 44+, 64-bit Arch Linux, CachyOS, and Omarchy; configure an existing supported provider instead.";
 };
 /** Production setup effects for Hopper, agent configuration, and the canonical skill directory. */
 export const systemSetupHost = (selectedDoctorHost = undefined, environment = process.env) => {
     const doctorHost = selectedDoctorHost ?? systemDoctorHost({ environment });
     const platform = doctorHost.platform;
     const { homeDirectory } = doctorHost;
-    const claudeSkillsDirectory = resolveClaudeCodeSkillsDirectory(homeDirectory, environment);
+    const macHopperHost = platform === "darwin"
+        ? systemMacHopperInstallHost(homeDirectory, environment)
+        : undefined;
+    const resources = new ArtifactResourceScope();
     return {
         platform,
         homeDirectory,
-        claudeCodeSkillsDirectory: claudeSkillsDirectory,
+        skillDestinations: (clientIds) => skillDestinations(homeDirectory, clientIds, environment, platform),
         registrationCommand: setupRegistrationCommand(platform, environment.npm_command === "exec"),
         nodeVersion: process.versions.node,
         macosVersion: () => doctorHost.macosVersion(),
         linuxDistribution: readLinuxDistribution,
+        close: () => closeSetupResources(resources, macHopperHost),
         initialSetupState: async (scope) => {
             const diagnosis = await runDoctor(undefined, doctorHost, scope);
             return {
@@ -72,41 +80,111 @@ export const systemSetupHost = (selectedDoctorHost = undefined, environment = pr
             };
         },
         installHopper: async (replaceExisting) => {
-            const result = platform === "linux"
-                ? await installLinuxHopper(systemLinuxHopperInstallHost(environment))
-                : await installMacHopper({ replaceExisting }, systemMacHopperInstallHost(homeDirectory, environment));
+            if (platform === "linux") {
+                const result = await installLinuxHopper(systemLinuxHopperInstallHost(environment));
+                return result.status === "installed"
+                    ? result
+                    : setupInstallFailure(result.reason);
+            }
+            if (macHopperHost === undefined)
+                return setupInstallFailure("unsupported_host");
+            const result = await installMacHopper({ replaceExisting }, macHopperHost);
             if (result.status === "installed")
-                return result;
-            return setupInstallFailure(result.reason);
+                return {
+                    status: "installed",
+                    launcherPath: result.launcherPath,
+                    ...(result.cleanupFailure === undefined
+                        ? {}
+                        : { cleanupFailure: result.cleanupFailure }),
+                };
+            const failure = setupInstallFailure(result.reason);
+            if (result.cleanupFailure === undefined)
+                return failure;
+            return failure.status === "failed"
+                ? {
+                    ...failure,
+                    remediation: `${failure.remediation} ${result.cleanupFailure}`,
+                }
+                : failure;
         },
         detectedClients: () => detectClients(homeDirectory, platform, environment),
         supportedClients: () => Promise.resolve(supportedClients(homeDirectory, platform, environment)),
-        configureClient: (client, providerEnvironment, command) => client.format === "unsupported"
-            ? Promise.resolve({ status: "skipped" })
-            : configureClientConfiguration(client, providerEnvironment, command),
-        clientNeedsConfigure: (client, providerEnvironment, command) => client.format === "unsupported"
-            ? Promise.resolve(false)
-            : clientConfigurationAligned(client, providerEnvironment, command).then((aligned) => !aligned),
-        inspectClientConfiguration: inspectClientConfiguration,
-        skillNeedsInstall: (clientIds) => canonicalSkillNeedsInstall(homeDirectory, clientIds, claudeSkillsDirectory),
-        installSkill: (clientIds) => installCanonicalSkill(homeDirectory, clientIds, claudeSkillsDirectory),
+        ...clientConfigurationOperations(resources),
+        skillNeedsInstall: (clientIds) => canonicalSkillNeedsInstall(homeDirectory, clientIds, environment, platform),
+        installSkill: (clientIds) => installCanonicalSkill(homeDirectory, clientIds, environment, platform),
         doctor: (scope) => runDoctor(undefined, doctorHost, scope),
     };
 };
+const clientConfigurationOperations = (resources) => ({
+    configureClient: (client, providerEnvironment, command) => runClientConfigurationOperation(resources, async () => client.format === "unsupported"
+        ? { status: "skipped" }
+        : configureClientConfiguration(client, providerEnvironment, command)),
+    clientNeedsConfigure: (client, providerEnvironment, command) => runClientConfigurationOperation(resources, async () => client.format === "unsupported"
+        ? false
+        : !(await clientConfigurationAligned(client, providerEnvironment, command))),
+    inspectClientConfiguration: (client, providerEnvironment, command) => runClientConfigurationOperation(resources, () => inspectClientConfiguration(client, providerEnvironment, command)),
+});
+const closeSetupResources = async (resources, macHopperHost) => {
+    const [resourceCleanup, hopperCleanup] = await Promise.allSettled([
+        resources.close(),
+        Promise.resolve().then(() => macHopperHost?.close()),
+    ]);
+    const failures = [];
+    if (hopperCleanup.status === "rejected")
+        failures.push(`Hopper host cleanup failed: ${errorMessage(hopperCleanup.reason)}`);
+    else if (hopperCleanup.value !== undefined)
+        failures.push(hopperCleanup.value);
+    if (resourceCleanup.status === "rejected")
+        failures.push(errorMessage(resourceCleanup.reason));
+    return failures.length === 0 ? undefined : failures.join("; ");
+};
+const runClientConfigurationOperation = async (resources, operation) => {
+    try {
+        return await resources.run(async () => {
+            try {
+                return await operation();
+            }
+            catch (cause) {
+                if (!(cause instanceof RegularFileCleanupFailure))
+                    throw cause;
+                const cleanup = await retryRegularFileCleanup(cause, resources);
+                const primary = cleanup.outcome.kind === "failed"
+                    ? cleanup.outcome.cause
+                    : cause.cleanupCause;
+                throw configurationCleanupError(`Could not safely access client configuration at ${cause.path}: ${errorMessage(primary)}`, cause, cleanup.cleanup);
+            }
+        });
+    }
+    catch (cause) {
+        if (cause instanceof ArtifactReaderFailure)
+            throw configurationCleanupError(cause.message, cause, cause.cleanup);
+        throw cause;
+    }
+};
+const configurationCleanupError = (message, cause, cleanup) => new ConfigurationError(message, {
+    cause,
+    settings: [{ setting: "client configuration", constraint: message }],
+    ...(cleanup === undefined ? {} : { cleanup }),
+});
+const errorMessage = (cause) => cause instanceof Error ? cause.message : String(cause);
 /** Detect supported agents from their config files or stable installation markers. */
 export const detectClients = async (home, platform = process.platform, environment = process.env) => {
     const detected = [];
     for (const candidate of supportedClients(home, platform, environment)) {
-        const [hasConfig, hasMarker] = await Promise.all([
-            exists(candidate.configPath),
-            candidate.markerPath === undefined ? false : exists(candidate.markerPath),
-        ]);
-        if (hasConfig || hasMarker)
+        if (candidate.configPathError !== undefined)
+            continue;
+        if (await clientEvidencePresent(candidate))
             detected.push(candidate);
     }
     return detected;
 };
 const major = (version) => Number.parseInt(version.split(".")[0] ?? "0", 10);
+const clientEvidencePresent = async (client) => {
+    for (const path of clientEvidencePaths(client))
+        if (await exists(path))
+            return true;
+    return false;
+};
 const exists = async (path) => {
     try {
         await access(path);