rea-agents 6.4.0 → 6.7.0

package/dist/application/SetupHost.js

@@ -1,30 +1,51 @@
+import { isClientConfigurationCleanupFailure, retryClientConfigurationCleanup, } from "./ClientConfigurationCleanup.js";
 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 { linuxHopperReleaseCacheDirectory } from "./LinuxHopperPublisher.js";
 import { clientEvidencePaths, supportedClients, } from "./SupportedClients.js";
-import { skillDestinations, canonicalSkillNeedsInstall, installCanonicalSkill, } from "./SetupSkill.js";
-import { clientConfigurationAligned, configureClientConfiguration, inspectClientConfiguration, } from "./SetupClientConfiguration.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 { RegularFileCleanupFailure } from "./RegularFileRead.js";
+import { explicitSetupRegistrationEnvironment, providerRegistrationEnvironment, } from "./SetupRegistrationEnvironment.js";
+import { msixPackagesDirectory, packagePrivateLauncherBlocker, } from "./MsixPackageStorage.js";
+import { CURRENT_ENTRYPOINT_PATH } from "../process/CurrentEntrypointPath.js";
+import { analysisProviderSelectorSchema } from "../contracts/providerSelection.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]);
@@ -42,7 +63,7 @@ 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, CachyOS, and Omarchy; configure an existing supported provider instead.";
 };
@@ -55,36 +76,64 @@ export const systemSetupHost = (selectedDoctorHost = undefined, environment = pr
         ? systemMacHopperInstallHost(homeDirectory, environment)
         : undefined;
     const resources = new ArtifactResourceScope();
+    const linuxHopperHost = systemLinuxHopperInstallHost(environment);
+    const pendingLinuxHopperCleanup = new LinuxHopperTemporaryCleanupOwner();
     return {
         platform,
         homeDirectory,
+        ...(platform === "linux"
+            ? {
+                linuxHopperReleaseCache: linuxHopperReleaseCacheDirectory(environment),
+            }
+            : {}),
         skillDestinations: (clientIds) => skillDestinations(homeDirectory, clientIds, environment, platform),
-        registrationCommand: setupRegistrationCommand(platform, environment.npm_command === "exec"),
+        ...setupRegistration(platform, homeDirectory, environment),
         nodeVersion: process.versions.node,
         macosVersion: () => doctorHost.macosVersion(),
         linuxDistribution: readLinuxDistribution,
-        close: () => closeSetupResources(resources, macHopperHost),
+        close: () => closeSetupResources(resources, macHopperHost, doctorHost, () => closeLinuxHopperInstallHost(linuxHopperHost, pendingLinuxHopperCleanup)),
         initialSetupState: async (scope) => {
             const diagnosis = await runDoctor(undefined, doctorHost, scope);
+            const providerEnvironment = {
+                ...providerRegistrationEnvironment(diagnosis.providerInspections ?? []),
+                ...doctorHost.providerRegistrationEnvironment?.(),
+                ...explicitSetupRegistrationEnvironment(environment),
+                ...(diagnosis.hopperPath === undefined
+                    ? {}
+                    : { HOPPER_LAUNCHER_PATH: diagnosis.hopperPath }),
+            };
+            const requestedProvider = analysisProviderSelectorSchema.safeParse(environment.REA_ANALYSIS_PROVIDER);
             return {
                 ...(diagnosis.hopperPath === undefined
                     ? {}
                     : { hopperPath: diagnosis.hopperPath }),
-                providerEnvironment: {
-                    ...providerRegistrationEnvironment(diagnosis.providerInspections ?? []),
-                    ...(diagnosis.hopperPath === undefined
-                        ? {}
-                        : { HOPPER_LAUNCHER_PATH: diagnosis.hopperPath }),
-                },
+                ...(typeof environment.HOPPER_LAUNCHER_PATH === "string" &&
+                    environment.HOPPER_LAUNCHER_PATH.trim() !== "" &&
+                    diagnosis.hopperPath === environment.HOPPER_LAUNCHER_PATH
+                    ? { hopperLauncherConfigured: true }
+                    : {}),
+                providerConfigured: diagnosis.hopperPath !== undefined ||
+                    diagnosis.providerInspections?.some(({ configured }) => configured) === true ||
+                    providerEnvironment.REA_JEB_MCP_URL !== undefined ||
+                    (requestedProvider.success && requestedProvider.data !== "auto"),
+                providerEnvironment,
                 doctor: diagnosis,
             };
         },
         installHopper: async (replaceExisting) => {
             if (platform === "linux") {
-                const result = await installLinuxHopper(systemLinuxHopperInstallHost(environment));
-                return result.status === "installed"
-                    ? result
-                    : setupInstallFailure(result.reason);
+                const result = await installLinuxHopper(linuxHopperHost);
+                if (result.cleanupFailure !== undefined)
+                    pendingLinuxHopperCleanup.retain(result.cleanupFailure);
+                if (result.status === "installed")
+                    return { status: "installed", launcherPath: result.launcherPath };
+                const failure = setupInstallFailure(result.reason, result.packageFailure, "linux");
+                return result.verificationFailure !== undefined
+                    ? {
+                        ...failure,
+                        remediation: `${result.verificationFailure.message} ${failure.remediation}`,
+                    }
+                    : failure;
             }
             if (macHopperHost === undefined)
                 return setupInstallFailure("unsupported_host");
@@ -93,47 +142,82 @@ export const systemSetupHost = (selectedDoctorHost = undefined, environment = pr
                 return {
                     status: "installed",
                     launcherPath: result.launcherPath,
+                    ...(result.openFailure === undefined
+                        ? {}
+                        : {
+                            warning: `Hopper was installed, but macOS could not open it: ${result.openFailure}. Open ${result.launcherPath} manually to complete first-run setup.`,
+                        }),
                     ...(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;
+            const diagnostic = setupInstallerDiagnostic(result.diagnostic);
+            return {
+                ...failure,
+                remediation: [
+                    failure.remediation,
+                    ...(diagnostic === undefined
+                        ? []
+                        : [`Installer detail: ${diagnostic}`]),
+                    ...(result.cleanupFailure === undefined
+                        ? []
+                        : [result.cleanupFailure]),
+                ].join(" "),
+            };
         },
         detectedClients: () => detectClients(homeDirectory, platform, environment),
         supportedClients: () => Promise.resolve(supportedClients(homeDirectory, platform, environment)),
-        ...clientConfigurationOperations(resources),
-        skillNeedsInstall: (clientIds) => canonicalSkillNeedsInstall(homeDirectory, clientIds, environment, platform),
-        installSkill: (clientIds) => installCanonicalSkill(homeDirectory, clientIds, environment, platform),
+        ...clientConfigurationOperations(resources, doctorHost.resolveProviderRequestBudget),
+        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) => ({
+const setupInstallerDiagnostic = (value) => {
+    if (value === undefined)
+        return undefined;
+    const normalized = value
+        .replace(/\u001b(?:\[[0-9;?]*[ -/]*[@-~]|\([0-9A-Za-z]|[@-Z\\^_])/gu, "")
+        .replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/gu, "")
+        .replace(/\s+/gu, " ")
+        .trim();
+    if (normalized === "")
+        return undefined;
+    return normalized.length <= 400
+        ? normalized
+        : `${normalized.slice(0, 397).trimEnd()}...`;
+};
+const clientConfigurationOperations = (resources, resolveProviderRequestBudget) => ({
     configureClient: (client, providerEnvironment, command) => runClientConfigurationOperation(resources, async () => client.format === "unsupported"
         ? { status: "skipped" }
-        : configureClientConfiguration(client, providerEnvironment, command)),
+        : configureClientConfiguration(client, providerEnvironment, command, resolveProviderRequestBudget)),
     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)),
+        : !(await clientConfigurationAligned(client, providerEnvironment, command, resolveProviderRequestBudget))),
+    inspectClientConfiguration: (client, providerEnvironment, command) => runClientConfigurationOperation(resources, () => inspectClientConfiguration(client, providerEnvironment, command, resolveProviderRequestBudget)),
 });
-const closeSetupResources = async (resources, macHopperHost) => {
-    const [resourceCleanup, hopperCleanup] = await Promise.allSettled([
+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("; ");
@@ -145,13 +229,14 @@ const runClientConfigurationOperation = async (resources, operation) => {
                 return await operation();
             }
             catch (cause) {
-                if (!(cause instanceof RegularFileCleanupFailure))
+                if (!isClientConfigurationCleanupFailure(cause))
                     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);
+                const cleanup = await retryClientConfigurationCleanup(cause, resources);
+                const rollback = cleanup.failures.find((failure) => failure instanceof ClientConfigurationCleanupRollbackFailure);
+                const rollbackMessage = rollback instanceof ClientConfigurationCleanupRollbackFailure
+                    ? ` ${failedConfigurationMessage(rollback.configurationFailure)}`
+                    : "";
+                throw configurationCleanupError(`Could not safely access client configuration at ${cause.path}: ${errorMessage(cleanup.primary)}.${rollbackMessage}`, cause, cleanup.cleanup);
             }
         });
     }
@@ -167,6 +252,19 @@ const configurationCleanupError = (message, cause, cleanup) => new Configuration
     ...(cleanup === undefined ? {} : { cleanup }),
 });
 const errorMessage = (cause) => cause instanceof Error ? cause.message : String(cause);
+const closeLinuxHopperInstallHost = async (host, temporaryOwner) => {
+    const reasons = [];
+    const temporary = await temporaryOwner.retry(host.cleanup);
+    if (temporary !== undefined)
+        reasons.push(temporary);
+    try {
+        await host.close?.();
+    }
+    catch (cause) {
+        reasons.push(`Linux Hopper publisher cleanup failed: ${errorMessage(cause)}`);
+    }
+    return reasons.length === 0 ? undefined : reasons.join("; ");
+};
 /** Detect supported agents from their config files or stable installation markers. */
 export const detectClients = async (home, platform = process.platform, environment = process.env) => {
     const detected = [];

package/dist/application/SetupInstallFailure.js

@@ -1,5 +1,40 @@
+import { HOPPER_PUBLISHER } from "../domain/hopperPublisher.js";
+import { HOPPER_LINUX_PRIMARY_FINGERPRINT } from "./HopperReleaseFeed.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, platform = "darwin") => {
     switch (reason) {
         case "unsupported_host":
             return {
@@ -17,7 +52,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 {
@@ -35,7 +70,7 @@ export const setupInstallFailure = (reason) => {
             return {
                 status: "failed",
                 code: "unsupported_hopper_build",
-                remediation: "The installed Hopper launcher does not match the build supported by this REA release. Unset HOPPER_LAUNCHER_PATH, reinstall through rea setup, or update REA.",
+                remediation: "The installed Hopper launcher does not match the authenticated vendor package. Check HOPPER_LAUNCHER_PATH and reinstall the official Hopper demo through rea setup.",
             };
         case "cancelled":
             return {
@@ -61,6 +96,26 @@ 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: platform === "linux"
+                    ? `The Hopper package signature did not verify under the pinned primary PGP fingerprint ${HOPPER_LINUX_PRIMARY_FINGERPRINT}; the package manager was not run. Download the official package and retry setup.`
+                    : `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 "verification_unavailable":
+            return {
+                status: "failed",
+                code: "publisher_verification_failed",
+                remediation: "REA could not authenticate or retain the signed Hopper package. Check vendor access, native package inspection tools and caller-owned cache permissions, then retry setup.",
+            };
+        case "cleanup_failed":
+            return {
+                status: "failed",
+                code: "cleanup_failed",
+                remediation: "Hopper publisher verification retained temporary cleanup ownership. Retry cleanup before running setup again.",
+            };
         case "copy":
             return {
                 status: "failed",

package/dist/application/SetupPlan.js

@@ -1,24 +1,29 @@
-import { join } from "node:path";
-import { isOwnedClientRegistrationCommand } from "./ClientRegistrationIdentity.js";
+import { classifyClientRegistrationCommand } from "./ClientRegistrationIdentity.js";
 import { linuxHopperInstallDisclosure, } from "./LinuxHopper.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 &&
-            (Object.keys(input.providerEnvironment).length === 0 ||
-                linuxHopperRepairNeeded));
+            (!input.providerConfigured || linuxHopperRepairNeeded));
     const [clients, detectedClients] = await Promise.all([
         input.host.supportedClients(),
         input.host.detectedClients(),
@@ -28,18 +33,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),
@@ -49,7 +59,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,
@@ -79,6 +89,22 @@ export const planSetupActions = async (input) => {
         const client = byId.get(id);
         return client === undefined ? [] : [client];
     });
+    const hopperCache = input.host.linuxHopperReleaseCache;
+    if (input.discovery.installHopper && hopperCache?.ok === false)
+        return {
+            plannedActions: [],
+            selectedClients,
+            clientsToConfigure: [],
+            blocker: hopperCache.error.message,
+        };
+    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),
@@ -92,43 +118,55 @@ 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,
+        ...(hopperCache?.ok === true
+            ? { hopperCacheDirectory: hopperCache.value }
+            : {}),
+        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,
-            skillDestinations: input.host.skillDestinations(input.skillClientIds),
-            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
@@ -138,10 +176,10 @@ 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."
+                    ? `Download the current official Hopper demo, verify its PGP publisher and launcher bytes, and retain archive, public-key.asc and release.json under ${input.hopperCacheDirectory ?? `${input.homeDirectory}/.cache/rea/hopper-releases`}/<launcher-sha256> for offline verification. Preserve replaced damaged evidence beside it as <launcher-sha256>.backup-<id>. Install Hopper plus its Xvfb demo-session dependencies. 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",
@@ -163,7 +201,7 @@ 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 }),
@@ -187,15 +225,15 @@ const setupPlan = (input) => [
 const linuxDisclosure = (family) => {
     const disclosure = linuxHopperInstallDisclosure(family, process.getuid?.() === 0);
     return {
-        networkOrigins: [disclosure.downloadUrl],
+        networkOrigins: disclosure.networkOrigins,
         commands: disclosure.commands,
-        integrity: `${String(disclosure.expectedBytes)} bytes · SHA-1 ${disclosure.expectedSha1}`,
+        integrity: disclosure.integrity,
     };
 };
 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 provider environment variables. Existing server environment overrides are retained."
@@ -205,5 +243,6 @@ const clientConfigurationDetail = (client, command, environment, installHopper)
             ? " 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}`}`;
 };