rea-agents 6.3.0 → 6.5.0

package/dist/application/SetupHost.js

@@ -1,26 +1,48 @@
 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 { invokingPackageRunner, packageRunnerRegistrationCommand, } 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 { installLinuxHopper, LinuxHopperTemporaryCleanupOwner, 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 { clientConfigurationAligned, configureClientConfiguration, inspectClientConfiguration, } from "./SetupClientConfiguration.js";
+import { clientEvidencePaths, supportedClients, } from "./SupportedClients.js";
+import { skillDestinations, canonicalSkillNeedsInstall, installCanonicalSkill, validateCanonicalSkillDirectories, } from "./SetupSkill.js";
+import { clientConfigurationAligned, ClientConfigurationCleanupRollbackFailure, configureClientConfiguration, inspectClientConfiguration, } from "./SetupClientConfiguration.js";
+import { failedConfigurationMessage } from "./SetupClients.js";
 import { setupInstallFailure } from "./SetupInstallFailure.js";
+import { RegularFileCleanupFailure, retryRegularFileCleanup, } from "./RegularFileRead.js";
 import { providerRegistrationEnvironment } from "./SetupRegistrationEnvironment.js";
+import { msixPackagesDirectory, packagePrivateLauncherBlocker, } from "./MsixPackageStorage.js";
+import { CURRENT_ENTRYPOINT_PATH } from "../process/CurrentEntrypointPath.js";
 /** Resolve the executable and arguments used in a managed MCP registration. */
-export const setupRegistrationCommand = (platform, useNpmRunner) => useNpmRunner
-    ? npxRegistrationCommand(platform)
-    : platform === "win32"
-        ? [
-            process.execPath,
-            resolve(process.argv[1] ?? PRODUCT_IDENTITY.cliBinary),
-            "mcp",
-        ]
-        : [resolve(process.argv[1] ?? PRODUCT_IDENTITY.cliBinary), "mcp"];
+export const setupRegistrationCommand = (platform, packageRunner, entrypointPath) => {
+    if (packageRunner !== undefined)
+        return packageRunnerRegistrationCommand(packageRunner, platform);
+    if (entrypointPath === undefined || entrypointPath.length === 0)
+        return [];
+    return platform === "win32"
+        ? [process.execPath, entrypointPath, "mcp"]
+        : [entrypointPath, "mcp"];
+};
+/**
+ * The launcher setup registers, and why it must not be registered when it
+ * exists only inside one MSIX package's private storage.
+ */
+const setupRegistration = (platform, homeDirectory, environment) => {
+    const registrationCommand = setupRegistrationCommand(platform, invokingPackageRunner(environment, platform), CURRENT_ENTRYPOINT_PATH);
+    const registrationCommandBlocker = registrationCommand.length === 0
+        ? "REA could not determine the current executable entrypoint. Run setup through the installed REA CLI or a supported package runner before configuring clients."
+        : platform === "win32"
+            ? packagePrivateLauncherBlocker(registrationCommand, msixPackagesDirectory(homeDirectory, environment))
+            : undefined;
+    return registrationCommandBlocker === undefined
+        ? { registrationCommand }
+        : { registrationCommand, registrationCommandBlocker };
+};
 export const filterClientsNeedingConfigure = async (host, detectedClients, providerEnvironment, command) => {
     const needs = await Promise.all(detectedClients.map((client) => host.clientNeedsConfigure(client, providerEnvironment, command)));
     return detectedClients.filter((_, index) => needs[index]);
@@ -38,32 +60,44 @@ export const hostRemediation = async (host, installHopper) => {
             ? "Upgrade to macOS 12 or newer."
             : undefined;
     }
-    if ((await host.linuxDistribution())?.supported === true)
+    if ((await host.linuxDistribution())?.hopperSetupSupported === 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();
+    const linuxHopperHost = systemLinuxHopperInstallHost(environment);
+    const pendingLinuxHopperCleanup = new LinuxHopperTemporaryCleanupOwner();
     return {
         platform,
         homeDirectory,
-        claudeCodeSkillsDirectory: claudeSkillsDirectory,
-        registrationCommand: setupRegistrationCommand(platform, environment.npm_command === "exec"),
+        skillDestinations: (clientIds) => skillDestinations(homeDirectory, clientIds, environment, platform),
+        ...setupRegistration(platform, homeDirectory, environment),
         nodeVersion: process.versions.node,
         macosVersion: () => doctorHost.macosVersion(),
         linuxDistribution: readLinuxDistribution,
+        close: () => closeSetupResources(resources, macHopperHost, doctorHost, () => pendingLinuxHopperCleanup.retry(linuxHopperHost.cleanup)),
         initialSetupState: async (scope) => {
             const diagnosis = await runDoctor(undefined, doctorHost, scope);
             return {
                 ...(diagnosis.hopperPath === undefined
                     ? {}
                     : { hopperPath: diagnosis.hopperPath }),
+                ...(typeof environment.HOPPER_LAUNCHER_PATH === "string" &&
+                    environment.HOPPER_LAUNCHER_PATH.trim() !== "" &&
+                    diagnosis.hopperPath === environment.HOPPER_LAUNCHER_PATH
+                    ? { hopperLauncherConfigured: true }
+                    : {}),
                 providerEnvironment: {
                     ...providerRegistrationEnvironment(diagnosis.providerInspections ?? []),
+                    ...doctorHost.providerRegistrationEnvironment?.(),
                     ...(diagnosis.hopperPath === undefined
                         ? {}
                         : { HOPPER_LAUNCHER_PATH: diagnosis.hopperPath }),
@@ -72,41 +106,127 @@ 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(linuxHopperHost);
+                if (result.cleanupFailure !== undefined)
+                    pendingLinuxHopperCleanup.retain(result.cleanupFailure);
+                return result.status === "installed"
+                    ? { status: "installed", launcherPath: result.launcherPath }
+                    : setupInstallFailure(result.reason, result.packageFailure);
+            }
+            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, resources),
+        validateSkillDirectories: (clientIds) => validateCanonicalSkillDirectories(homeDirectory, clientIds, environment, platform),
+        installSkill: (clientIds) => installCanonicalSkill(homeDirectory, clientIds, environment, platform, undefined, resources),
         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, doctorHost, retryLinuxHopperCleanup) => {
+    const [resourceCleanup, hopperCleanup, doctorCleanup, linuxCleanup] = await Promise.allSettled([
+        resources.close(),
+        Promise.resolve().then(() => macHopperHost?.close()),
+        Promise.resolve().then(() => doctorHost.close?.()),
+        retryLinuxHopperCleanup(),
+    ]);
+    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 (doctorCleanup.status === "rejected")
+        failures.push(`Doctor host cleanup failed: ${errorMessage(doctorCleanup.reason)}`);
+    else if (doctorCleanup.value !== undefined)
+        failures.push(doctorCleanup.value);
+    if (linuxCleanup.status === "rejected")
+        failures.push(`Linux Hopper cleanup retry failed: ${errorMessage(linuxCleanup.reason)}`);
+    else if (linuxCleanup.value !== undefined)
+        failures.push(linuxCleanup.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;
+                const rollbackMessage = cause instanceof ClientConfigurationCleanupRollbackFailure
+                    ? ` ${failedConfigurationMessage(cause.configurationFailure)}`
+                    : "";
+                throw configurationCleanupError(`Could not safely access client configuration at ${cause.path}: ${errorMessage(primary)}.${rollbackMessage}`, 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);

package/dist/application/SetupInstallFailure.js

@@ -1,5 +1,39 @@
+import { HOPPER_PUBLISHER } from "../domain/hopperPublisher.js";
+const normalizePackageOutput = (output) => output
+    .replace(/\u001b(?:\[[0-9;?]*[ -/]*[@-~]|\([0-9A-Za-z]|[@-Z\\^_])/gu, "")
+    .replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/gu, "")
+    .replace(/\s+/gu, " ")
+    .trim();
+const packageOutputExcerpt = (failure, limit = 400) => {
+    const output = [failure.stderr, failure.stdout]
+        .map(normalizePackageOutput)
+        .filter((text) => text !== "")
+        .join(" ");
+    const suffix = failure.outputTruncated ? " (output truncated)" : "";
+    const bodyLimit = limit - suffix.length;
+    if (output.length <= bodyLimit)
+        return `${output}${suffix}`;
+    const half = Math.floor((bodyLimit - 3) / 2);
+    const head = output
+        .slice(0, half)
+        .replace(/\s+\S*$/u, "")
+        .trimEnd();
+    const tail = output
+        .slice(-half)
+        .replace(/^\S*\s+/u, "")
+        .trimStart();
+    return `${head} … ${tail}${suffix}`;
+};
+const packageManagerRemediation = (failure) => {
+    if (failure === undefined)
+        return "Allow the system package-manager operation or install the planned Hopper package and Linux runtime dependencies, then rerun rea setup.";
+    const status = failure.exitCode === null ? "no exit status" : `exit ${failure.exitCode}`;
+    const excerpt = packageOutputExcerpt(failure);
+    const observed = excerpt === "" ? "no output was captured." : `its output: ${excerpt}`;
+    return `The system package-manager command failed (${failure.command}; ${status}); ${observed} Resolve the reported problem, grant the authorization the command needs, or install the planned Hopper package and Linux runtime dependencies manually, then rerun rea setup.`;
+};
 /** Map provider installer failures to stable setup codes and safe recovery. */
-export const setupInstallFailure = (reason) => {
+export const setupInstallFailure = (reason, packageFailure) => {
     switch (reason) {
         case "unsupported_host":
             return {
@@ -17,7 +51,7 @@ export const setupInstallFailure = (reason) => {
             return {
                 status: "failed",
                 code: "authorization_or_package_manager_failed",
-                remediation: "Allow the system package-manager operation or install the planned Hopper package and Linux runtime dependencies, then rerun rea setup.",
+                remediation: packageManagerRemediation(packageFailure),
             };
         case "launcher_missing":
             return {
@@ -61,6 +95,12 @@ export const setupInstallFailure = (reason) => {
                 code: "bundle_invalid",
                 remediation: "The mounted package did not contain the expected Hopper application bundle. Retry setup; if it repeats, update REA before installing.",
             };
+        case "publisher_verification_failed":
+            return {
+                status: "failed",
+                code: "publisher_verification_failed",
+                remediation: `The mounted Hopper application is not signed by the publisher REA pins (${HOPPER_PUBLISHER.bundleIdentifier}, Apple team ${HOPPER_PUBLISHER.teamIdentifier}); nothing was copied or launched. Install Hopper yourself and set HOPPER_LAUNCHER_PATH to its launcher, then rerun rea setup.`,
+            };
         case "copy":
             return {
                 status: "failed",

package/dist/application/SetupPlan.js

@@ -1,20 +1,25 @@
-import { join } from "node:path";
-import { isOwnedClientRegistrationCommand } from "./ClientRegistrationIdentity.js";
+import { classifyClientRegistrationCommand } from "./ClientRegistrationIdentity.js";
 import { linuxHopperInstallDisclosure, } from "./LinuxHopper.js";
-import { skillDestinations } from "./SetupSkill.js";
 import { macHopperInstallDisclosure } from "./MacHopper.js";
+import { macHopperUserApplicationPath } from "./MacHopperPaths.js";
+import { appDataRedirection, registrationPersistenceDetail, } from "./SupportedClients.js";
+import { redirectedWriteBlocker } from "./MsixPackageStorage.js";
+import { compareUnicodeCodePoints } from "../domain/unicodeCodePointOrder.js";
+import { CURRENT_ENTRYPOINT_PATH } from "../process/CurrentEntrypointPath.js";
 /** Discover supported clients and current registrations without mutation. */
 export const discoverSetupState = async (input) => {
     const { initialDoctor } = input;
-    const linuxHopperRepairNeeded = initialDoctor.checks.some(({ name, ok, detail }) => !ok &&
-        (name === "hopper-demo-runtime" ||
-            (name === "hopper-version" && detail === "/opt/hopper/bin/Hopper")));
+    const linuxHopperRepairNeeded = input.hopperLauncherConfigured !== true &&
+        initialDoctor.checks.some(({ name, ok, detail }) => !ok &&
+            (name === "hopper-demo-runtime" ||
+                (name === "hopper-version" && detail === "/opt/hopper/bin/Hopper")));
     const linuxDistribution = input.host.platform === "linux"
         ? await input.host.linuxDistribution()
         : undefined;
     const hopperInstallSupported = (input.host.platform === "darwin" &&
         majorVersion((await input.host.macosVersion()) ?? "0") >= 12) ||
-        (input.host.platform === "linux" && linuxDistribution?.supported === true);
+        (input.host.platform === "linux" &&
+            linuxDistribution?.hopperSetupSupported === true);
     const installHopper = input.forceHopperInstall ||
         (hopperInstallSupported &&
             input.proposeHopper &&
@@ -29,18 +34,23 @@ export const discoverSetupState = async (input) => {
     const registrationByClient = new Map(registrations.map((registration) => [registration.client, registration]));
     const clientStates = clients.map((client) => {
         const registration = registrationByClient.get(client.name);
+        const commandIdentity = registration === undefined
+            ? undefined
+            : classifyClientRegistrationCommand(registration.command, CURRENT_ENTRYPOINT_PATH);
         const ownedRegistration = (registration?.state === "aligned" || registration?.state === "stale") &&
-            isOwnedClientRegistrationCommand(registration.command);
+            commandIdentity === "owned";
         const configured = ownedRegistration;
         const status = registration?.state === "invalid"
             ? "invalid"
-            : ownedRegistration && registration.state === "aligned"
-                ? "configured"
-                : ownedRegistration && registration.state === "stale"
-                    ? "needs_configuration"
-                    : detectedIds.has(client.name)
+            : registration?.state === "unknown" || commandIdentity === "unknown"
+                ? "unknown"
+                : ownedRegistration && registration.state === "aligned"
+                    ? "configured"
+                    : ownedRegistration && registration.state === "stale"
                         ? "needs_configuration"
-                        : "missing";
+                        : detectedIds.has(client.name)
+                            ? "needs_configuration"
+                            : "missing";
         return {
             client,
             detected: detectedIds.has(client.name),
@@ -50,7 +60,7 @@ export const discoverSetupState = async (input) => {
     });
     const defaultClientIds = registrations
         .filter((registration) => (registration.state === "aligned" || registration.state === "stale") &&
-        isOwnedClientRegistrationCommand(registration.command))
+        classifyClientRegistrationCommand(registration.command, CURRENT_ENTRYPOINT_PATH) === "owned")
         .map(({ client }) => client);
     return {
         initialDoctor,
@@ -80,6 +90,14 @@ export const planSetupActions = async (input) => {
         const client = byId.get(id);
         return client === undefined ? [] : [client];
     });
+    if (selectedClients.length > 0 &&
+        input.host.registrationCommandBlocker !== undefined)
+        return {
+            plannedActions: [],
+            selectedClients,
+            clientsToConfigure: [],
+            blocker: input.host.registrationCommandBlocker,
+        };
     const inspections = await Promise.all(selectedClients.map(async (client) => ({
         client,
         inspection: await input.host.inspectClientConfiguration(client, input.providerEnvironment, input.command),
@@ -93,43 +111,52 @@ export const planSetupActions = async (input) => {
             blocker: `${invalid.client.displayName ?? invalid.client.name}: ${invalid.inspection.remediation}`,
         };
     }
-    const clientPlans = inspections.flatMap(({ client, inspection }) => client.format !== "unsupported" &&
-        (inspection.status === "create" ||
-            inspection.status === "update" ||
-            (input.discovery.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 clientPlans = plannedClientWrites(inspections, input.discovery.installHopper);
+    const plannedActions = setupPlan({
+        platform: input.host.platform,
+        homeDirectory: input.host.homeDirectory,
+        installHopper: input.discovery.installHopper,
+        installSkill: input.installSkill,
+        skillClientIds: input.skillClientIds,
+        skillDestinations: input.host.skillDestinations(input.skillClientIds),
+        clients: clientPlans,
+        providerEnvironment: input.providerEnvironment,
+        ...(input.discovery.linuxPackageFamily === undefined
+            ? {}
+            : { linuxPackageFamily: input.discovery.linuxPackageFamily }),
+        command: input.command,
+    });
+    const blocker = (clientPlans.length > 0
+        ? input.host.registrationCommandBlocker
+        : undefined) ??
+        redirectedWriteBlocker(appDataRedirection(input.discovery.clients), plannedActions
+            .filter(({ kind }) => kind !== "install_hopper")
+            .map(({ target }) => target), "setup");
     return {
-        plannedActions: setupPlan({
-            platform: input.host.platform,
-            homeDirectory: input.host.homeDirectory,
-            installHopper: input.discovery.installHopper,
-            installSkill: input.installSkill,
-            skillClientIds: input.skillClientIds,
-            claudeCodeSkillsDirectory: input.host.claudeCodeSkillsDirectory,
-            clients: clientPlans,
-            providerEnvironment: input.providerEnvironment,
-            ...(input.discovery.linuxPackageFamily === undefined
-                ? {}
-                : { linuxPackageFamily: input.discovery.linuxPackageFamily }),
-            command: input.command,
-        }),
+        plannedActions,
         selectedClients,
         clientsToConfigure: selectedClients.filter((client) => clientPlans.some(({ client: planned }) => planned.name === client.name)),
+        ...(blocker === undefined ? {} : { blocker }),
     };
 };
+/** Selected clients whose registration setup writes, with the disclosed operation. */
+const plannedClientWrites = (inspections, installHopper) => inspections.flatMap(({ client, inspection }) => client.format !== "unsupported" &&
+    (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 }
+                : {}),
+        },
+    ]
+    : []);
 /** Describe every selected setup mutation before user approval. */
 const setupPlan = (input) => [
     ...(input.installHopper
@@ -139,7 +166,7 @@ const setupPlan = (input) => [
                 kind: "install_hopper",
                 label: "Hopper deep-analysis provider",
                 target: input.platform === "darwin"
-                    ? join(input.homeDirectory, "Applications/Hopper Disassembler.app")
+                    ? macHopperUserApplicationPath(input.homeDirectory)
                     : "system package manager",
                 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."
@@ -164,16 +191,14 @@ const setupPlan = (input) => [
         kind: "configure_client",
         label: client.displayName ?? client.name,
         target: client.configPath,
-        detail: clientConfigurationDetail(client.displayName ?? client.name, input.command, input.providerEnvironment, input.installHopper),
+        detail: clientConfigurationDetail(client, input.command, input.providerEnvironment, input.installHopper),
         external: false,
         operation,
         ...(backupPath === undefined ? {} : { backupPath }),
     })),
     ...(input.installSkill
-        ? skillDestinations(input.homeDirectory, input.skillClientIds, input.claudeCodeSkillsDirectory).map(({ client, path }) => ({
-            id: client === "claude_code"
-                ? "install_skill:claude_code"
-                : "install_skill",
+        ? input.skillDestinations.map(({ client, path }) => ({
+            id: client === "shared" ? "install_skill" : `install_skill:${client}`,
             kind: "install_skill",
             label: client === "claude_code"
                 ? "REA skill for Claude Code"
@@ -198,15 +223,16 @@ const linuxDisclosure = (family) => {
 const majorVersion = (version) => Number.parseInt(version.split(".")[0] ?? "0", 10);
 const clientConfigurationDetail = (client, command, environment, installHopper) => {
     const entries = Object.entries(environment)
-        .sort(([left], [right]) => left.localeCompare(right))
+        .sort(([left], [right]) => compareUnicodeCodePoints(left, right))
         .map(([name, value]) => `${name}=${value}`);
     const environmentDetail = entries.length === 0
-        ? " No additional environment variables."
-        : ` Environment: ${entries.join(", ")}.`;
+        ? " No additional provider environment variables. Existing server environment overrides are retained."
+        : ` Detected provider environment: ${entries.join(", ")}. Existing server environment overrides are retained; detected values replace matching keys.`;
     const hopperDetail = installHopper
         ? environment.HOPPER_LAUNCHER_PATH === undefined
             ? " If this plan installs Hopper, REA will add HOPPER_LAUNCHER_PATH using the launcher path reported by that installation."
             : " The HOPPER_LAUNCHER_PATH value shown above is the current fallback; if this plan installs Hopper, REA will replace it with the launcher path reported by that installation."
         : "";
-    return `Add the REA MCP registration for ${client}; preserve unrelated configuration. Command: ${command.map((part) => JSON.stringify(part)).join(" ")}.${environmentDetail}${hopperDetail}`;
+    const persistence = registrationPersistenceDetail(client);
+    return `Add the REA MCP registration for ${client.displayName ?? client.name}; preserve unrelated configuration. The backup path reflects the configuration inspected for this plan; if that file changes before execution, setup will select a recovery path for its current contents. Command: ${command.map((part) => JSON.stringify(part)).join(" ")}.${environmentDetail}${hopperDetail}${persistence === undefined ? "" : ` ${persistence}`}`;
 };

package/dist/application/SetupRecoveryBackup.js

@@ -0,0 +1,66 @@
+import { createHash } from "node:crypto";
+import { constants as fsConstants } from "node:fs";
+import { copyFile } from "node:fs/promises";
+import { err, ok } from "../domain/result.js";
+import { readRegularFile, RegularFileCleanupFailure, } from "./RegularFileRead.js";
+const isMissing = (cause) => cause instanceof Error && "code" in cause && cause.code === "ENOENT";
+const errorDetail = (cause) => cause instanceof Error ? cause.message : String(cause);
+/** Select a persistent snapshot only when its bytes match this transaction's original. */
+export const selectCurrentRecoveryBackup = async (firstBackupPath, original) => {
+    const expected = Buffer.isBuffer(original)
+        ? original
+        : Buffer.from(original, "utf8");
+    let firstBackup;
+    try {
+        firstBackup = await readRegularFile(firstBackupPath, {
+            symlinks: "reject",
+        });
+    }
+    catch (cause) {
+        if (cause instanceof RegularFileCleanupFailure)
+            throw cause;
+        if (!isMissing(cause))
+            return err({
+                kind: "unreadable",
+                path: firstBackupPath,
+                detail: `The recovery backup could not be checked: ${errorDetail(cause)}`,
+            });
+    }
+    if (firstBackup === undefined)
+        return ok({ backupPath: firstBackupPath, present: false });
+    if (firstBackup.equals(expected))
+        return ok({ backupPath: firstBackupPath, present: true });
+    const digest = createHash("sha256").update(expected).digest("hex");
+    const recoveryPath = `${firstBackupPath}.${digest}.recovery`;
+    let recovery;
+    try {
+        recovery = await readRegularFile(recoveryPath, { symlinks: "reject" });
+    }
+    catch (cause) {
+        if (cause instanceof RegularFileCleanupFailure)
+            throw cause;
+        if (!isMissing(cause))
+            return err({
+                kind: "unreadable",
+                path: recoveryPath,
+                detail: `The recovery backup could not be checked: ${errorDetail(cause)}`,
+            });
+    }
+    if (recovery !== undefined && !recovery.equals(expected))
+        return err({
+            kind: "occupied",
+            path: recoveryPath,
+            detail: `The recovery path already contains different data: ${recoveryPath}`,
+        });
+    return ok({ backupPath: recoveryPath, present: recovery !== undefined });
+};
+/** Preserve a snapshot without replacing an earlier recovery file. */
+export const preserveRecoveryBackup = 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";
+    }
+};

package/dist/application/SetupRegistrationEnvironment.js

@@ -1,4 +1,5 @@
+import { compareUnicodeCodePoints } from "../domain/unicodeCodePointOrder.js";
 /** Preserve adapter-published settings independently of runtime readiness. */
 export const providerRegistrationEnvironment = (inspections) => Object.fromEntries(inspections
     .flatMap(({ registrationEnvironment }) => Object.entries(registrationEnvironment))
-    .sort(([left], [right]) => left.localeCompare(right)));
+    .sort(([left], [right]) => compareUnicodeCodePoints(left, right)));