rea-agents 6.5.0 → 6.7.0

package/dist/application/SetupHost.js

@@ -1,3 +1,4 @@
+import { isClientConfigurationCleanupFailure, retryClientConfigurationCleanup, } from "./ClientConfigurationCleanup.js";
 import { access } from "node:fs/promises";
 import { resolve } from "node:path";
 import { ArtifactResourceScope } from "../artifacts/ArtifactResourceScope.js";
@@ -9,15 +10,17 @@ import { SUPPORTED_NODE_VERSION_PROSE, supportsNodeVersion, } from "../domain/ru
 import { runDoctor, systemDoctorHost } from "./Doctor.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, 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, packageRunner, entrypointPath) => {
     if (packageRunner !== undefined)
@@ -78,14 +81,28 @@ export const systemSetupHost = (selectedDoctorHost = undefined, environment = pr
     return {
         platform,
         homeDirectory,
+        ...(platform === "linux"
+            ? {
+                linuxHopperReleaseCache: linuxHopperReleaseCacheDirectory(environment),
+            }
+            : {}),
         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)),
+        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
                     ? {}
@@ -95,13 +112,11 @@ export const systemSetupHost = (selectedDoctorHost = undefined, environment = pr
                     diagnosis.hopperPath === environment.HOPPER_LAUNCHER_PATH
                     ? { hopperLauncherConfigured: true }
                     : {}),
-                providerEnvironment: {
-                    ...providerRegistrationEnvironment(diagnosis.providerInspections ?? []),
-                    ...doctorHost.providerRegistrationEnvironment?.(),
-                    ...(diagnosis.hopperPath === undefined
-                        ? {}
-                        : { HOPPER_LAUNCHER_PATH: diagnosis.hopperPath }),
-                },
+                providerConfigured: diagnosis.hopperPath !== undefined ||
+                    diagnosis.providerInspections?.some(({ configured }) => configured) === true ||
+                    providerEnvironment.REA_JEB_MCP_URL !== undefined ||
+                    (requestedProvider.success && requestedProvider.data !== "auto"),
+                providerEnvironment,
                 doctor: diagnosis,
             };
         },
@@ -110,9 +125,15 @@ export const systemSetupHost = (selectedDoctorHost = undefined, environment = pr
                 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 (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");
@@ -121,37 +142,61 @@ 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),
+        ...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, doctorHost, retryLinuxHopperCleanup) => {
     const [resourceCleanup, hopperCleanup, doctorCleanup, linuxCleanup] = await Promise.allSettled([
@@ -184,16 +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;
-                const rollbackMessage = cause instanceof ClientConfigurationCleanupRollbackFailure
-                    ? ` ${failedConfigurationMessage(cause.configurationFailure)}`
+                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(primary)}.${rollbackMessage}`, cause, cleanup.cleanup);
+                throw configurationCleanupError(`Could not safely access client configuration at ${cause.path}: ${errorMessage(cleanup.primary)}.${rollbackMessage}`, cause, cleanup.cleanup);
             }
         });
     }
@@ -209,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,4 +1,5 @@
 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, "")
@@ -33,7 +34,7 @@ const packageManagerRemediation = (failure) => {
     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, packageFailure) => {
+export const setupInstallFailure = (reason, packageFailure, platform = "darwin") => {
     switch (reason) {
         case "unsupported_host":
             return {
@@ -69,7 +70,7 @@ export const setupInstallFailure = (reason, packageFailure) => {
             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 {
@@ -99,7 +100,21 @@ export const setupInstallFailure = (reason, packageFailure) => {
             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.`,
+                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 {

package/dist/application/SetupPlan.js

@@ -23,8 +23,7 @@ export const discoverSetupState = async (input) => {
     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(),
@@ -90,6 +89,14 @@ 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 {
@@ -115,6 +122,9 @@ export const planSetupActions = async (input) => {
     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,
@@ -169,7 +179,7 @@ const setupPlan = (input) => [
                     ? 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",
@@ -215,9 +225,9 @@ 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);

package/dist/application/SetupRecoveryBackup.js

@@ -6,15 +6,17 @@ import { readRegularFile, RegularFileCleanupFailure, } from "./RegularFileRead.j
 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) => {
+export const selectCurrentRecoveryBackup = async (firstBackupPath, original, resources) => {
+    const read = (path) => readRegularFile(path, {
+        symlinks: "reject",
+        ...(resources === undefined ? {} : { resources }),
+    });
     const expected = Buffer.isBuffer(original)
         ? original
         : Buffer.from(original, "utf8");
     let firstBackup;
     try {
-        firstBackup = await readRegularFile(firstBackupPath, {
-            symlinks: "reject",
-        });
+        firstBackup = await read(firstBackupPath);
     }
     catch (cause) {
         if (cause instanceof RegularFileCleanupFailure)
@@ -34,7 +36,7 @@ export const selectCurrentRecoveryBackup = async (firstBackupPath, original) =>
     const recoveryPath = `${firstBackupPath}.${digest}.recovery`;
     let recovery;
     try {
-        recovery = await readRegularFile(recoveryPath, { symlinks: "reject" });
+        recovery = await read(recoveryPath);
     }
     catch (cause) {
         if (cause instanceof RegularFileCleanupFailure)
@@ -54,13 +56,38 @@ export const selectCurrentRecoveryBackup = async (firstBackupPath, original) =>
         });
     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";
+const copyExclusive = (source, destination) => copyFile(source, destination, fsConstants.COPYFILE_EXCL);
+/**
+ * Preserve a transaction's original bytes before it edits the file: keep a
+ * matching first backup, otherwise copy them to the content-addressed recovery
+ * path without replacing an earlier file, then verify the selected snapshot.
+ */
+export const preserveCurrentRecoveryBackup = async (firstBackupPath, source, original, { copy = copyExclusive, resources } = {}) => {
+    const selection = await selectCurrentRecoveryBackup(firstBackupPath, original, resources);
+    if (!selection.ok)
+        return selection;
+    const { backupPath } = selection.value;
+    if (!selection.value.present) {
+        try {
+            await copy(source, backupPath);
+        }
+        catch (cause) {
+            if (!(cause instanceof Error && "code" in cause && cause.code === "EEXIST"))
+                return err({
+                    kind: "copy",
+                    path: backupPath,
+                    detail: `The recovery backup could not be written: ${errorDetail(cause)}`,
+                });
+        }
     }
+    const verified = await selectCurrentRecoveryBackup(firstBackupPath, original, resources);
+    if (!verified.ok)
+        return verified;
+    if (verified.value.backupPath !== backupPath || !verified.value.present)
+        return err({
+            kind: "unverified",
+            path: backupPath,
+            detail: `The recovery backup does not match the configuration it preserves: ${backupPath}`,
+        });
+    return ok(backupPath);
 };

package/dist/application/SetupRegistrationEnvironment.js

@@ -1,4 +1,16 @@
 import { compareUnicodeCodePoints } from "../domain/unicodeCodePointOrder.js";
+const SELECTED_REGISTRATION_SETTINGS = [
+    "REA_ANALYSIS_PROVIDER",
+    "REA_GHIDRA_STARTUP_TIMEOUT_MS",
+    "REA_HOPPER_STARTUP_TIMEOUT_MS",
+    "REA_JEB_MCP_TIMEOUT_MS",
+    "REA_MCP_INPUT_SCHEMA_PROFILE",
+];
+/** Preserve selected setup settings without copying unrelated process values. */
+export const explicitSetupRegistrationEnvironment = (environment) => Object.fromEntries(SELECTED_REGISTRATION_SETTINGS.flatMap((key) => {
+    const value = environment[key];
+    return value === undefined ? [] : [[key, value]];
+}));
 /** Preserve adapter-published settings independently of runtime readiness. */
 export const providerRegistrationEnvironment = (inspections) => Object.fromEntries(inspections
     .flatMap(({ registrationEnvironment }) => Object.entries(registrationEnvironment))

package/dist/application/SetupSkill.js

@@ -9,7 +9,7 @@ import { PRODUCT_IDENTITY } from "../identity.js";
 import { NonRegularFileReadError, RegularFileChangedError, } from "../filesystem/RegularFile.js";
 import { RegularFileCleanupFailure, withRegularFile, } from "./RegularFileRead.js";
 import { clientSkillDirectories } from "./SupportedClients.js";
-import { selectCurrentRecoveryBackup } from "./SetupRecoveryBackup.js";
+import { preserveCurrentRecoveryBackup } from "./SetupRecoveryBackup.js";
 export const MANAGED_SKILL_FILES = [
     "SKILL.md",
     "references/connection-and-recovery.md",
@@ -69,16 +69,7 @@ const systemSkillInstallFileOperations = {
     mkdir: async (path) => {
         await mkdir(path, { recursive: true });
     },
-    backup: async (source, destination) => {
-        try {
-            await copyFile(source, destination, fsConstants.COPYFILE_EXCL);
-        }
-        catch (cause) {
-            if (cause instanceof Error && "code" in cause && cause.code === "EEXIST")
-                return;
-            throw cause;
-        }
-    },
+    backup: (source, destination) => copyFile(source, destination, fsConstants.COPYFILE_EXCL),
     write: (path, content, mode) => writeFileAtomic(path, content, { encoding: "utf8", mode }),
     remove: (path) => rm(path, { force: true }),
 };
@@ -259,7 +250,7 @@ const inspectCanonicalSkill = async (home, clientIds, environment, platform, res
             }
         }
         if (clientIds !== undefined || rootHasFiles || rootIssues.length > 0) {
-            installedDestination = true;
+            installedDestination ||= rootHasFiles;
             canonical = canonical && rootCanonical;
             issues.push(...rootIssues);
         }
@@ -307,21 +298,6 @@ const restoreSkillFiles = async (attempted, operations) => {
     }
     return failures;
 };
-const preserveCurrentSkillBackup = async (destination, original, operations) => {
-    const firstBackupPath = `${destination}.rea.backup`;
-    const selection = await selectCurrentRecoveryBackup(firstBackupPath, original);
-    if (!selection.ok)
-        throw new Error(selection.error.detail);
-    if (selection.value.present)
-        return selection.value.backupPath;
-    await operations.backup(destination, selection.value.backupPath);
-    const verified = await selectCurrentRecoveryBackup(firstBackupPath, original);
-    if (!verified.ok ||
-        verified.value.backupPath !== selection.value.backupPath ||
-        !verified.value.present)
-        throw new Error(`The current file was not preserved at ${selection.value.backupPath}`);
-    return verified.value.backupPath;
-};
 /** Transactionally install the canonical skill bundle and optional references. */
 export const installCanonicalSkill = async (home, clientIds = [], environment = {}, platform = process.platform, operations = systemSkillInstallFileOperations, resources) => {
     let attempted = [];
@@ -338,7 +314,13 @@ export const installCanonicalSkill = async (home, clientIds = [], environment =
             failingPath = destination;
             await operations.mkdir(dirname(destination));
             if (original !== undefined) {
-                recoveryPaths.set(destination, await preserveCurrentSkillBackup(destination, original.bytes, operations));
+                const preserved = await preserveCurrentRecoveryBackup(`${destination}.rea.backup`, destination, original.bytes, {
+                    copy: operations.backup,
+                    ...(resources === undefined ? {} : { resources }),
+                });
+                if (!preserved.ok)
+                    throw new Error(preserved.error.detail);
+                recoveryPaths.set(destination, preserved.value);
             }
         }
         stage = "write";
@@ -383,8 +365,6 @@ export const readInstalledSkillIdentity = async (home, clientIds, environment =
         ? inspection.value.manifest
         : inspection.error.manifest;
     const issues = inspection.ok ? [] : inspection.error.issues;
-    if (content === undefined && issues.length === 0)
-        return undefined;
     const toolCount = content === undefined
         ? undefined
         : /^\s{2}tool_count:\s*(\d+)\s*$/mu.exec(content)?.[1];

package/dist/application/SourceLimitations.js

@@ -0,0 +1,35 @@
+import { compareUnicodeCodePoints } from "../domain/unicodeCodePointOrder.js";
+/** Stable exact-provenance key for deduplication before rendering. */
+export const sourceLimitationKey = ({ provider, operation, limitation, }) => JSON.stringify([
+    provider.id,
+    provider.name,
+    provider.version,
+    operation,
+    limitation,
+]);
+/** Render unique source caveats without losing their provider or operation. */
+export const renderSourceLimitations = (limitations) => {
+    const groups = new Map();
+    for (const { provider, operation, limitation } of limitations) {
+        const key = JSON.stringify([
+            provider.id,
+            provider.name,
+            provider.version,
+            limitation,
+        ]);
+        const group = groups.get(key) ?? {
+            provider,
+            limitation,
+            operations: new Set(),
+        };
+        group.operations.add(operation);
+        groups.set(key, group);
+    }
+    return [...groups.values()]
+        .map(({ provider, limitation, operations }) => {
+        const version = provider.version === null ? "" : ` ${provider.version}`;
+        const operationList = [...operations].sort(compareUnicodeCodePoints);
+        return `${provider.name} (${provider.id}${version}) ${operationList.join(", ")}: ${limitation}`;
+    })
+        .sort(compareUnicodeCodePoints);
+};

package/dist/application/SupportedClients.js

@@ -33,8 +33,8 @@ const claudeDesktopLocation = (context) => {
         markerPath: directory,
     });
 };
-const claudeCodeConfigDirectory = ({ home, env }) => env.CLAUDE_CONFIG_DIR ?? home;
-const claudeCodeMarkerDirectory = ({ home, env }) => env.CLAUDE_CONFIG_DIR ?? join(home, ".claude");
+const claudeCodeConfigDirectory = ({ home, env }) => env.CLAUDE_CONFIG_DIR || home;
+const claudeCodeMarkerDirectory = ({ home, env }) => env.CLAUDE_CONFIG_DIR || join(home, ".claude");
 const codexDirectory = ({ home, env }) => env.CODEX_HOME || join(home, ".codex");
 /** Kimi Code stores MCP declarations beside the rest of its home data. */
 const kimiDirectory = ({ home, env }) => env.KIMI_CODE_HOME || join(home, ".kimi-code");
@@ -265,10 +265,10 @@ export const SUPPORTED_CLIENT_DEFINITIONS = [
     {
         name: "claude_code",
         displayName: "Claude Code",
-        skillPath: ({ home, env }) => join(env.CLAUDE_CONFIG_DIR ?? join(home, ".claude"), "skills"),
+        skillPath: (context) => join(claudeCodeMarkerDirectory(context), "skills"),
         configPath: (context) => join(claudeCodeConfigDirectory(context), ".claude.json"),
         markerPath: claudeCodeMarkerDirectory,
-        format: "json",
+        format: "claude_code",
     },
     {
         name: "claude_desktop",