rea-agents 6.4.0 → 6.5.0

package/dist/application/Setup.js

@@ -51,6 +51,10 @@ const runSetupWorkflow = async (options, host, confirm) => {
     let clientStates = [];
     let readinessScope = options.readinessScope;
     const fail = (remediation) => setupFailure(remediation, [host, plannedActions, appliedActions, clients, clientStates], readinessScope);
+    const failSkill = async (error) => ({
+        ...(await fail(error.remediation)),
+        code: "skill_install_failed",
+    });
     const unsupported = await hostRemediation(host, false);
     if (unsupported !== undefined)
         return fail(unsupported);
@@ -60,6 +64,7 @@ const runSetupWorkflow = async (options, host, confirm) => {
         host,
         providerEnvironment,
         forceHopperInstall: options.installHopper,
+        hopperLauncherConfigured: initialState.hopperLauncherConfigured === true,
         proposeHopper: options.proposeHopper ?? (confirm !== undefined && !options.structured),
         initialDoctor: initialState.doctor,
     });
@@ -76,7 +81,9 @@ const runSetupWorkflow = async (options, host, confirm) => {
         : (options.clientIds ??
             options.readinessScope?.clients ??
             discovery.defaultClientIds);
-    let selectedSkillClientIds = options.skillClientIds ?? selectedClientIds;
+    let selectedSkillClientIds = options.skillClientIds ??
+        options.readinessScope?.skillClients ??
+        selectedClientIds;
     let skillNeedsInstall = await host.skillNeedsInstall(selectedSkillClientIds);
     let skillSelected = options.installSkill === true ||
         (options.installSkill !== false &&
@@ -154,11 +161,17 @@ const runSetupWorkflow = async (options, host, confirm) => {
         installHopper: planDiscovery.installHopper,
         installSkill,
         skillSelected,
+        selectedSkillClientIds,
         selectedClients: planned.selectedClients,
         clientsToConfigure: planned.clientsToConfigure,
     };
     readinessScope = resolvedReadinessScope(options.readinessScope, planSelection);
     const manualRemediation = manualClientsRemediation(planned.selectedClients);
+    if (skillSelected) {
+        const admission = await host.validateSkillDirectories(selectedSkillClientIds);
+        if (!admission.ok)
+            return failSkill(admission.error);
+    }
     if (options.dryRun === true)
         return {
             status: "planned",
@@ -201,6 +214,12 @@ const runSetupWorkflow = async (options, host, confirm) => {
                 }
                 : {}),
         };
+    // Approval may pause while a skill manager changes a selected directory.
+    if (planSelection.skillSelected) {
+        const admission = await host.validateSkillDirectories(selectedSkillClientIds);
+        if (!admission.ok)
+            return failSkill(admission.error);
+    }
     let selectedClients = planSelection.clientsToConfigure;
     if (planSelection.installHopper &&
         (interactiveApproval || options.installHopper)) {
@@ -232,9 +251,12 @@ const runSetupWorkflow = async (options, host, confirm) => {
     });
     if (clientFailure !== undefined)
         return fail(clientFailure);
-    if (planSelection.installSkill &&
-        !(await installSkillAction(host, options, appliedActions, selectedSkillClientIds)))
-        return fail("REA analysis skill could not be installed or verified. Check permissions for its planned skill directories, then rerun setup.");
+    if (planSelection.installSkill) {
+        const skillFailure = await installSkillAction(host, options, appliedActions, selectedSkillClientIds);
+        if (skillFailure !== undefined) {
+            return failSkill(skillFailure);
+        }
+    }
     const doctor = summarizeDoctor(await host.doctor(readinessScope));
     const remediation = combineRemediation(finalSetupRemediation(host.platform, appliedActions.includes("installed_hopper"), doctor.healthy, hopperPath), manualRemediation);
     return {
@@ -302,23 +324,24 @@ const installSkillAction = async (host, options, appliedActions, skillClientIds)
         state: "started",
     });
     const skill = await host.installSkill(skillClientIds);
-    if (skill === "failed") {
+    if (!skill.ok) {
         emitProgress(options, {
             actionId: "install_skill",
             label,
             state: "failed",
+            detail: skill.error.message,
         });
-        return false;
+        return skill.error;
     }
-    if (skill === "installed")
+    if (skill.value === "installed")
         appliedActions.push("installed_skill");
     emitProgress(options, {
         actionId: "install_skill",
         label,
-        state: skill === "installed" ? "completed" : "warning",
-        ...(skill === "unchanged" ? { detail: "Already current" } : {}),
+        state: skill.value === "installed" ? "completed" : "warning",
+        ...(skill.value === "unchanged" ? { detail: "Already current" } : {}),
     });
-    return true;
+    return undefined;
 };
 const setupFailure = async (remediation, [host, plannedActions, appliedActions, clients, clientStates], scope) => {
     return {
@@ -363,6 +386,9 @@ const resolvedReadinessScope = (requested, selection) => ({
         ? ["hopper"]
         : (requested?.providers ?? []),
     skill: selection.skillSelected === true || requested?.skill === true,
+    ...(selection.skillSelected === true || requested?.skill === true
+        ? { skillClients: selection.selectedSkillClientIds }
+        : {}),
 });
 const summarizeDoctor = (report) => ({
     healthy: report.healthy,

package/dist/application/SetupClientConfiguration.js

@@ -1,8 +1,9 @@
 import { readClientPolicyBlock } from "./GeminiClientSettings.js";
-import { readClientConfigurationFiles } from "./ClientConfigurationFiles.js";
-import { clientRegistrationEntry, clientConfigurationValuesEqual, clientServerListedDisabled, clientServerPath, legacyClientServerPath, OMP_DISABLED_SERVERS_KEY, parseClientConfiguration, serializeClientConfiguration, withClientServers, } from "./ClientConfigurationDocument.js";
-import { constants as fsConstants } from "node:fs";
-import { copyFile, mkdir, rm, writeFile } from "node:fs/promises";
+import { readClientConfigurationFiles, effectiveClientConfiguration, readConfigurationText, } from "./ClientConfigurationFiles.js";
+import { err, ok } from "../domain/result.js";
+import { clientRegistrationEntry, clientConfigurationValuesEqual, clientServerListedDisabled, clientServerPath, legacyClientServerPath, OMP_DISABLED_SERVERS_KEY, parseClientConfiguration, parseZcodeFallbackConfiguration, serializeClientConfiguration, withClientServers, } from "./ClientConfigurationDocument.js";
+import { dshDocument, DshCordisDocument } from "./DshCordisPatch.js";
+import { mkdir, rm, writeFile } from "node:fs/promises";
 import { dirname } from "node:path";
 import writeFileAtomic from "write-file-atomic";
 import { clientRegistrationEnvironment } from "./ClientRegistrationEnvironment.js";
@@ -10,7 +11,17 @@ import { PRODUCT_IDENTITY } from "../identity.js";
 import { npxRegistrationCommand } from "./ClientRegistrationIdentity.js";
 import { MCP_STARTUP_POLICY } from "../mcpStartupPolicy.js";
 import { resolveClientConfigTransactionPath } from "./ClientConfigPath.js";
+import { packageReadTargetChanged } from "./MsixPackageStorage.js";
 import { readRegularFileText, RegularFileCleanupFailure, } from "./RegularFileRead.js";
+import { preserveRecoveryBackup, selectCurrentRecoveryBackup, } from "./SetupRecoveryBackup.js";
+import { registrationWriteBlocker, } from "./SupportedClients.js";
+export class ClientConfigurationCleanupRollbackFailure extends RegularFileCleanupFailure {
+    configurationFailure;
+    constructor(failure, configurationFailure) {
+        super(failure.path, failure.owner, failure.outcome, new AggregateError([failure.cleanupCause, new Error(configurationFailure.failure.detail)], `Configuration readback cleanup and rollback failed: ${configurationFailure.failure.path}`));
+        this.configurationFailure = configurationFailure;
+    }
+}
 /** Configure one supported client's native stdio MCP registration shape. */
 export const configureClientConfiguration = (client, environment = {}, command = npxRegistrationCommand()) => {
     if (client.configPathError !== undefined)
@@ -26,7 +37,13 @@ const configureClientDocument = async (client, environment, command) => {
         throwCleanupFailure(files.error);
         return { status: "failed", reason: "readback" };
     }
-    const policy = await readClientPolicyBlock(client, undefined, clientConfigurationDesired(client, environment, command, files.value.at(-1)));
+    const existing = files.value.find(({ sourcePath }) => sourcePath === client.configPath);
+    const editabilityError = existing?.dialect === "dsh"
+        ? dshDocument(existing.document).editabilityError
+        : undefined;
+    if (editabilityError !== undefined)
+        return { status: "failed", reason: "readback" };
+    const policy = await readClientPolicyBlock(client, undefined, clientConfigurationDesired(client, environment, command, existing, files.value));
     if (!policy.ok) {
         throwCleanupFailure(policy.error);
         return { status: "failed", reason: "readback" };
@@ -48,8 +65,11 @@ const configureClientDocument = async (client, environment, command) => {
     }
     let parsed;
     try {
-        parsed = parseClientConfiguration(original ?? (format === "toml" || format === "grok" ? "" : "{}"), format);
-        const policy = await readClientPolicyBlock(client, parsed, clientConfigurationDesired(client, environment, command, parsed));
+        parsed = parseClientConfiguration(original ??
+            (format === "toml" || format === "grok" || format === "dsh"
+                ? ""
+                : "{}"), format);
+        const policy = await readClientPolicyBlock(client, parsed, clientConfigurationDesired(client, environment, command, parsed, files.value));
         if (!policy.ok) {
             throwCleanupFailure(policy.error);
             return { status: "failed", reason: "readback" };
@@ -64,7 +84,15 @@ const configureClientDocument = async (client, environment, command) => {
         void cause;
         return { status: "failed", reason: "readback" };
     }
-    const desired = clientConfigurationDesired(client, environment, command, parsed);
+    const fallback = await readZcodeFallbackServers(client, parsed);
+    if (!fallback.ok) {
+        throwCleanupFailure(fallback.error);
+        return { status: "failed", reason: "readback" };
+    }
+    const desired = clientConfigurationDesired(client, environment, command, {
+        ...parsed,
+        servers: { ...fallback.value, ...parsed.servers },
+    }, files.value);
     if (registrationCurrent(parsed, desired))
         return { status: "unchanged" };
     return persistClientConfiguration({
@@ -74,17 +102,38 @@ const configureClientDocument = async (client, environment, command) => {
         original,
         parsed,
         desired,
+        fallbackServers: fallback.value,
     });
 };
-const persistClientConfiguration = async ({ client, transactionPath, format, original, parsed, desired, }) => {
+const persistClientConfiguration = async ({ client, transactionPath, format, original, parsed, desired, fallbackServers, }) => {
+    // The plan chose this file; an MSIX package may have switched to its
+    // private copy since, for example when it quit.
+    if (client.msixPackage !== undefined &&
+        (await packageReadTargetChanged(client.msixPackage, client.configPath)))
+        return { status: "failed", reason: "target_changed" };
     const backupPath = original === undefined ? undefined : `${client.configPath}.rea.backup`;
-    if (backupPath !== undefined &&
-        !(await preserveConfigBackup(transactionPath, backupPath)))
-        return { status: "failed", reason: "backup" };
+    let recoveryBackupPath;
+    if (backupPath !== undefined && original !== undefined) {
+        const selection = await selectCurrentRecoveryBackup(backupPath, original);
+        if (!selection.ok)
+            return { status: "failed", reason: "backup" };
+        if (!(await preserveRecoveryBackup(transactionPath, selection.value.backupPath)))
+            return { status: "failed", reason: "backup" };
+        const verified = await selectCurrentRecoveryBackup(backupPath, original);
+        if (!verified.ok ||
+            verified.value.backupPath !== selection.value.backupPath ||
+            !verified.value.present)
+            return { status: "failed", reason: "backup" };
+        recoveryBackupPath = verified.value.backupPath;
+    }
     // A native OpenCode V2 entry replaces REA's legacy V1 entry, which would
     // otherwise conflict with it.
     const legacyPath = legacyClientServerPath(parsed, PRODUCT_IDENTITY.mcpServerKey);
-    const registered = withClientServers(parsed, { ...parsed.servers, [PRODUCT_IDENTITY.mcpServerKey]: desired }, PRODUCT_IDENTITY.mcpServerKey);
+    const registered = withClientServers(parsed, {
+        ...fallbackServers,
+        ...parsed.servers,
+        [PRODUCT_IDENTITY.mcpServerKey]: desired,
+    }, PRODUCT_IDENTITY.mcpServerKey);
     // OMP's denylist would hide the registration; keep every other listed name.
     const ompDisabled = parsed.dialect === "omp"
         ? parsed.document[OMP_DISABLED_SERVERS_KEY]
@@ -100,6 +149,9 @@ const persistClientConfiguration = async ({ client, transactionPath, format, ori
     try {
         await mkdir(dirname(client.configPath), { recursive: true });
         await writeFileAtomic(transactionPath, serializeClientConfiguration(document, format, original, [
+            ...Object.keys(fallbackServers)
+                .filter((name) => name !== PRODUCT_IDENTITY.mcpServerKey)
+                .map((name) => clientServerPath(parsed, name)),
             clientServerPath(parsed, PRODUCT_IDENTITY.mcpServerKey),
             ...(legacyPath === undefined ? [] : [legacyPath]),
             ...(enableOmp ? [[OMP_DISABLED_SERVERS_KEY]] : []),
@@ -115,22 +167,35 @@ const persistClientConfiguration = async ({ client, transactionPath, format, ori
     }
     try {
         const readback = parseClientConfiguration(await readRegularFileText(transactionPath), format);
-        if (!registrationCurrent(readback, desired)) {
-            await restoreConfig(transactionPath, original);
-            return { status: "failed", reason: "readback" };
+        if (!registrationCurrent(readback, desired) ||
+            Object.entries(fallbackServers).some(([name, entry]) => name !== PRODUCT_IDENTITY.mcpServerKey &&
+                !clientConfigurationValuesEqual(readback.servers[name], entry))) {
+            return rollbackOrReadbackFailure(transactionPath, original, recoveryBackupPath);
         }
     }
     catch (cause) {
-        if (cause instanceof RegularFileCleanupFailure)
+        if (cause instanceof RegularFileCleanupFailure) {
+            const rollback = await restoreConfig(transactionPath, original);
+            if (!rollback.ok)
+                throw new ClientConfigurationCleanupRollbackFailure(cause, {
+                    status: "failed",
+                    reason: "rollback",
+                    ...(recoveryBackupPath === undefined
+                        ? {}
+                        : { backupPath: recoveryBackupPath }),
+                    failure: rollback.error,
+                });
             throw cause;
+        }
         // Readback failure restores the transaction before reporting.
         void cause;
-        await restoreConfig(transactionPath, original);
-        return { status: "failed", reason: "readback" };
+        return rollbackOrReadbackFailure(transactionPath, original, recoveryBackupPath);
     }
     return {
         status: "configured",
-        ...(backupPath === undefined ? {} : { backupPath }),
+        ...(recoveryBackupPath === undefined
+            ? {}
+            : { backupPath: recoveryBackupPath }),
     };
 };
 /** Determine whether an existing client configuration matches the desired registration. */
@@ -145,13 +210,13 @@ export const clientConfigurationAligned = async (client, providerEnvironment, co
         }
         const original = await readRegularFileText(client.configPath);
         const parsed = parseClientConfiguration(original, client.format);
-        const policy = await readClientPolicyBlock(client, parsed, clientConfigurationDesired(client, providerEnvironment, command, parsed));
+        const policy = await readClientPolicyBlock(client, parsed, clientConfigurationDesired(client, providerEnvironment, command, parsed, files.value));
         if (!policy.ok) {
             throwCleanupFailure(policy.error);
             return false;
         }
         return (policy.value === undefined &&
-            registrationCurrent(parsed, clientConfigurationDesired(client, providerEnvironment, command, parsed)));
+            registrationCurrent(parsed, clientConfigurationDesired(client, providerEnvironment, command, parsed, files.value)));
     }
     catch (cause) {
         if (cause instanceof RegularFileCleanupFailure)
@@ -163,6 +228,16 @@ export const clientConfigurationAligned = async (client, providerEnvironment, co
 };
 /** Preflight one client configuration before setup presents any mutations. */
 export const inspectClientConfiguration = async (client, providerEnvironment, command) => {
+    const inspection = await inspectClientDocument(client, providerEnvironment, command);
+    if (inspection.status !== "create" && inspection.status !== "update")
+        return inspection;
+    // A change the running client would overwrite is not a persisted registration.
+    const blocker = registrationWriteBlocker(client, "setup");
+    return blocker === undefined
+        ? inspection
+        : { status: "invalid", remediation: blocker };
+};
+const inspectClientDocument = async (client, providerEnvironment, command) => {
     if (client.configPathError !== undefined)
         return { status: "invalid", remediation: client.configPathError };
     if (client.format === "unsupported")
@@ -175,7 +250,16 @@ export const inspectClientConfiguration = async (client, providerEnvironment, co
             remediation: files.error.detail,
         };
     }
-    const policy = await readClientPolicyBlock(client, undefined, clientConfigurationDesired(client, providerEnvironment, command, files.value.at(-1)));
+    const existing = files.value.find(({ sourcePath }) => sourcePath === client.configPath);
+    const editabilityError = existing?.dialect === "dsh"
+        ? dshDocument(existing.document).editabilityError
+        : undefined;
+    if (editabilityError !== undefined)
+        return {
+            status: "invalid",
+            remediation: editabilityError.message,
+        };
+    const policy = await readClientPolicyBlock(client, undefined, clientConfigurationDesired(client, providerEnvironment, command, existing, files.value));
     if (!policy.ok) {
         throwCleanupFailure(policy.error);
         return {
@@ -198,8 +282,14 @@ export const inspectClientConfiguration = async (client, providerEnvironment, co
     catch (cause) {
         if (cause instanceof RegularFileCleanupFailure)
             throw cause;
-        if (isMissing(cause))
+        if (isMissing(cause)) {
+            const fallback = await readZcodeFallbackServers(client);
+            if (!fallback.ok) {
+                throwCleanupFailure(fallback.error);
+                return { status: "invalid", remediation: fallback.error.detail };
+            }
             return { status: "create" };
+        }
         return {
             status: "invalid",
             remediation: `The configuration file could not be read. Check its permissions before rerunning setup. ${cause instanceof Error ? cause.message : String(cause)}`,
@@ -207,7 +297,7 @@ export const inspectClientConfiguration = async (client, providerEnvironment, co
     }
     try {
         const parsed = parseClientConfiguration(original, client.format);
-        const policy = await readClientPolicyBlock(client, parsed, clientConfigurationDesired(client, providerEnvironment, command, parsed));
+        const policy = await readClientPolicyBlock(client, parsed, clientConfigurationDesired(client, providerEnvironment, command, parsed, files.value));
         if (!policy.ok) {
             throwCleanupFailure(policy.error);
             return {
@@ -217,9 +307,14 @@ export const inspectClientConfiguration = async (client, providerEnvironment, co
         }
         if (policy.value !== undefined)
             return { status: "invalid", remediation: policy.value };
-        const desired = clientConfigurationDesired(client, providerEnvironment, command, parsed);
+        const desired = clientConfigurationDesired(client, providerEnvironment, command, parsed, files.value);
         if (registrationCurrent(parsed, desired))
             return { status: "already_current" };
+        const fallback = await readZcodeFallbackServers(client, parsed);
+        if (!fallback.ok) {
+            throwCleanupFailure(fallback.error);
+            return { status: "invalid", remediation: fallback.error.detail };
+        }
     }
     catch (cause) {
         if (cause instanceof RegularFileCleanupFailure)
@@ -231,9 +326,15 @@ export const inspectClientConfiguration = async (client, providerEnvironment, co
             remediation: "The existing configuration is malformed. Repair it before setup applies any other changes.",
         };
     }
+    const backupSelection = await selectCurrentRecoveryBackup(`${client.configPath}.rea.backup`, original);
+    if (!backupSelection.ok)
+        return {
+            status: "invalid",
+            remediation: backupSelection.error.detail,
+        };
     return {
         status: "update",
-        backupPath: `${client.configPath}.rea.backup`,
+        backupPath: backupSelection.value.backupPath,
     };
 };
 const isMissing = (cause) => cause instanceof Error && "code" in cause && cause.code === "ENOENT";
@@ -241,13 +342,40 @@ const throwCleanupFailure = (error) => {
     if (error.cleanupFailure !== undefined)
         throw error.cleanupFailure;
 };
-const preserveConfigBackup = async (source, destination) => {
+/** Admit the fallback only when the first native ZCode server would suppress it. */
+const readZcodeFallbackServers = async (client, parsed) => {
+    if (client.format !== "zcode" ||
+        (parsed !== undefined && Object.keys(parsed.servers).length > 0))
+        return ok({});
+    const path = client.zcodeFallbackPath;
+    const detail = `The ZCode fallback configuration ${path ?? "path"} is unresolved, malformed or unreadable. Repair it before rerunning setup: the first native server would suppress that fallback.`;
+    if (path === undefined)
+        return err({ kind: "unreadable", path: client.configPath, detail });
+    const transactionPath = await resolveClientConfigTransactionPath(path);
+    if (transactionPath === undefined)
+        return err({ kind: "unreadable", path, detail });
+    const source = await readConfigurationText(transactionPath);
+    if (!source.ok)
+        return err({ ...source.error, detail: `${detail} ${source.error.detail}` });
+    if (source.value === undefined)
+        return ok({});
     try {
-        await copyFile(source, destination, fsConstants.COPYFILE_EXCL);
-        return true;
+        const parsed = parseZcodeFallbackConfiguration(source.value);
+        const environment = clientRegistrationEnvironment(parsed);
+        if (!environment.ok)
+            return err({
+                kind: "malformed",
+                path,
+                detail: `${detail} ${environment.error.settings.map(({ setting, constraint }) => `${setting}: ${constraint}`).join("; ")}`,
+            });
+        return ok(parsed.servers);
     }
     catch (cause) {
-        return cause instanceof Error && "code" in cause && cause.code === "EEXIST";
+        return err({
+            kind: "malformed",
+            path,
+            detail: `${detail} ${cause instanceof Error ? cause.message : String(cause)}`,
+        });
     }
 };
 const restoreConfig = async (path, original) => {
@@ -256,24 +384,59 @@ const restoreConfig = async (path, original) => {
             await rm(path, { force: true });
         else
             await writeFile(path, original, { encoding: "utf8", mode: 0o600 });
+        return ok(undefined);
     }
     catch (cause) {
-        // The backup remains available for the remediation reported by setup.
-        void cause;
+        return err({ kind: "restore", path, detail: errorDetail(cause) });
     }
 };
+const rollbackOrReadbackFailure = async (targetPath, original, backupPath) => {
+    const rollback = await restoreConfig(targetPath, original);
+    return rollback.ok
+        ? { status: "failed", reason: "readback" }
+        : {
+            status: "failed",
+            reason: "rollback",
+            ...(backupPath === undefined ? {} : { backupPath }),
+            failure: rollback.error,
+        };
+};
+const errorDetail = (cause) => cause instanceof Error ? cause.message : String(cause);
 /** Whether REA's entry matches, no legacy entry remains, and no client disable list suppresses it. */
-const registrationCurrent = (parsed, desired) => clientConfigurationValuesEqual(parsed.servers[PRODUCT_IDENTITY.mcpServerKey], desired) &&
+const registrationCurrent = (parsed, desired) => (parsed.dialect !== "dsh" || dshDocument(parsed.document).ready) &&
+    clientConfigurationValuesEqual(parsed.servers[PRODUCT_IDENTITY.mcpServerKey], desired) &&
     !Object.hasOwn(parsed.legacyServers, PRODUCT_IDENTITY.mcpServerKey) &&
     !clientServerListedDisabled(parsed, PRODUCT_IDENTITY.mcpServerKey);
-const clientConfigurationDesired = (client, providerEnvironment, command, parsed) => {
+const clientConfigurationDesired = (client, providerEnvironment, command, parsed, sources) => {
+    const effective = effectiveClientConfiguration(sources, {
+        client,
+        document: parsed,
+    });
+    const validated = clientRegistrationEnvironment(effective, providerEnvironment);
+    if (!validated.ok)
+        throw validated.error;
     const format = parsed?.dialect ?? client.format ?? "json";
+    const launcher = command.length === 0 ? [PRODUCT_IDENTITY.cliBinary, "mcp"] : command;
+    if (format === "dsh") {
+        const desired = (parsed === undefined
+            ? new DshCordisDocument("")
+            : dshDocument(parsed.document)).desired(launcher, providerEnvironment);
+        if (!desired.ok)
+            throw desired.error;
+        return desired.value;
+    }
     // Preserve explicitly configured server settings, never the ambient process
     // environment. Newly discovered provider paths win only for their own keys.
-    const environment = clientRegistrationEnvironment(parsed, providerEnvironment);
+    const environment = clientRegistrationEnvironment(parsed, providerEnvironment, "fragment");
     if (!environment.ok)
         throw environment.error;
-    const registration = clientRegistrationEntry(format, command.length === 0 ? [PRODUCT_IDENTITY.cliBinary, "mcp"] : command, environment.value);
+    const registration = clientRegistrationEntry(format, launcher, environment.value);
+    const previous = parsed?.servers[PRODUCT_IDENTITY.mcpServerKey];
+    if (client.name === "kimi" &&
+        typeof previous === "object" &&
+        previous !== null &&
+        "enabledTools" in previous)
+        registration.enabledTools = previous.enabledTools;
     return {
         ...registration,
         ...(client.name === "codex" || client.name === "grok_build"
@@ -281,5 +444,11 @@ const clientConfigurationDesired = (client, providerEnvironment, command, parsed
                 startup_timeout_sec: MCP_STARTUP_POLICY.codexStartupTimeoutSeconds,
             }
             : {}),
+        ...(client.name === "kimi"
+            ? {
+                startupTimeoutMs: MCP_STARTUP_POLICY.kimiStartupTimeoutMs,
+                toolTimeoutMs: MCP_STARTUP_POLICY.kimiToolTimeoutMs,
+            }
+            : {}),
     };
 };

package/dist/application/SetupClients.js

@@ -1,10 +1,16 @@
-const failedConfigurationMessage = (reason) => {
-    if (reason === "path")
+export const failedConfigurationMessage = (result) => {
+    if (result.reason === "target_changed")
+        return "The client began reading a different configuration file after the plan was shown, so no change was made. Rerun setup to review the new target.";
+    if (result.reason === "path")
         return "Agent configuration path could not be safely verified. Check its permissions and, if it is a symbolic link, verify that the link resolves to a regular file owned by the current user, then rerun setup.";
-    if (reason === "backup")
+    if (result.reason === "backup")
         return "Agent configuration could not be backed up, so no change was made. Check file permissions, then rerun setup.";
-    if (reason === "write")
+    if (result.reason === "write")
         return "Agent configuration could not be updated. Check file permissions, then rerun setup.";
+    if (result.reason === "rollback")
+        return result.backupPath === undefined
+            ? `Agent configuration rollback failed at ${result.failure.path}: ${result.failure.detail}; the failed first-run file may remain. Remove or repair it before rerunning setup.`
+            : `Agent configuration rollback failed at ${result.failure.path}: ${result.failure.detail}. Inspect the preserved backup at ${result.backupPath} and restore the intended configuration, then rerun setup.`;
     return "Agent configuration could not be verified after writing. Repair the configuration file or restore its `.rea.backup`, then rerun setup.";
 };
 /** Configure every detected agent and report the first failed transaction. */
@@ -17,12 +23,12 @@ export const configureDetectedClients = async (options) => {
         const result = await options.host.configureClient(client, options.providerEnvironment, options.command);
         options.clients[client.name] = result;
         if (result.status === "failed") {
-            failure ??= failedConfigurationMessage(result.reason);
+            failure ??= failedConfigurationMessage(result);
             options.onProgress?.({
                 actionId,
                 label,
                 state: "failed",
-                detail: failedConfigurationMessage(result.reason),
+                detail: failedConfigurationMessage(result),
             });
         }
         else if (result.status === "configured") {