rea-agents 6.4.0 → 6.7.0

package/dist/application/SetupClientConfiguration.js

@@ -1,23 +1,36 @@
 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 { ConfigurationError } from "../domain/configurationErrors.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 } from "node:fs/promises";
 import { dirname } from "node:path";
-import writeFileAtomic from "write-file-atomic";
-import { clientRegistrationEnvironment } from "./ClientRegistrationEnvironment.js";
+import { isClientConfigurationCleanupFailure } from "./ClientConfigurationCleanup.js";
+import { ClientConfigurationPublication } from "./ClientConfigurationPublication.js";
+import { clientRegistrationEnvironment, clientRegistrationEnvironmentDetails, } from "./ClientRegistrationEnvironment.js";
 import { PRODUCT_IDENTITY } from "../identity.js";
 import { npxRegistrationCommand } from "./ClientRegistrationIdentity.js";
-import { MCP_STARTUP_POLICY } from "../mcpStartupPolicy.js";
+import { MCP_STARTUP_POLICY, recommendedMcpToolTimeoutMs, recommendedMcpToolTimeoutSeconds, } from "../mcpStartupPolicy.js";
 import { resolveClientConfigTransactionPath } from "./ClientConfigPath.js";
+import { packageReadTargetChanged } from "./MsixPackageStorage.js";
 import { readRegularFileText, RegularFileCleanupFailure, } from "./RegularFileRead.js";
+import { preserveCurrentRecoveryBackup, 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}`), failure.retention, failure.completionCancellation);
+        this.configurationFailure = configurationFailure;
+    }
+}
 /** Configure one supported client's native stdio MCP registration shape. */
-export const configureClientConfiguration = (client, environment = {}, command = npxRegistrationCommand()) => {
+export const configureClientConfiguration = (client, environment = {}, command = npxRegistrationCommand(), resolveProviderRequestBudget) => {
     if (client.configPathError !== undefined)
         return Promise.resolve({ status: "failed", reason: "path" });
-    return configureClientDocument(client, environment, command);
+    return configureClientDocument(client, environment, command, resolveProviderRequestBudget);
 };
-const configureClientDocument = async (client, environment, command) => {
+const configureClientDocument = async (client, environment, command, resolveProviderRequestBudget) => {
     const format = client.format;
     if (format === undefined || format === "unsupported")
         return { status: "failed", reason: "readback" };
@@ -26,7 +39,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, resolveProviderRequestBudget));
     if (!policy.ok) {
         throwCleanupFailure(policy.error);
         return { status: "failed", reason: "readback" };
@@ -48,8 +67,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, resolveProviderRequestBudget));
         if (!policy.ok) {
             throwCleanupFailure(policy.error);
             return { status: "failed", reason: "readback" };
@@ -64,7 +86,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, resolveProviderRequestBudget);
     if (registrationCurrent(parsed, desired))
         return { status: "unchanged" };
     return persistClientConfiguration({
@@ -74,17 +104,35 @@ const configureClientDocument = async (client, environment, command) => {
         original,
         parsed,
         desired,
+        fallbackServers: fallback.value,
     });
 };
-const persistClientConfiguration = async ({ client, transactionPath, format, original, parsed, desired, }) => {
-    const backupPath = original === undefined ? undefined : `${client.configPath}.rea.backup`;
-    if (backupPath !== undefined &&
-        !(await preserveConfigBackup(transactionPath, backupPath)))
-        return { status: "failed", reason: "backup" };
+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) {
+        const target = await packageReadTargetChanged(client.msixPackage, client.configPath);
+        if (!target.ok)
+            return {
+                status: "failed",
+                reason: "target_unavailable",
+                failure: {
+                    kind: "inspect",
+                    path: target.error.path,
+                    detail: target.error.detail,
+                },
+            };
+        if (target.value)
+            return { status: "failed", reason: "target_changed" };
+    }
     // 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]
@@ -97,44 +145,85 @@ const persistClientConfiguration = async ({ client, transactionPath, format, ori
             [OMP_DISABLED_SERVERS_KEY]: ompDisabled.filter((name) => name !== PRODUCT_IDENTITY.mcpServerKey),
         }
         : registered;
+    let serialized;
     try {
-        await mkdir(dirname(client.configPath), { recursive: true });
-        await writeFileAtomic(transactionPath, serializeClientConfiguration(document, format, original, [
+        serialized = 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]] : []),
-        ]), {
-            encoding: "utf8",
-            mode: 0o600,
-        });
+        ]);
     }
     catch (cause) {
-        // Write failure is reported by the status reason.
+        // An unserializable edit is reported before any file is written.
         void cause;
         return { status: "failed", reason: "write" };
     }
+    if (!serialized.ok)
+        return {
+            status: "failed",
+            reason: "shadowed_member",
+            path: serialized.error.path,
+        };
+    let recoveryBackupPath;
+    if (original !== undefined) {
+        const preserved = await preserveCurrentRecoveryBackup(`${client.configPath}.rea.backup`, transactionPath, original);
+        if (!preserved.ok)
+            return { status: "failed", reason: "backup" };
+        recoveryBackupPath = preserved.value;
+    }
+    let publication;
     try {
-        const readback = parseClientConfiguration(await readRegularFileText(transactionPath), format);
-        if (!registrationCurrent(readback, desired)) {
-            await restoreConfig(transactionPath, original);
-            return { status: "failed", reason: "readback" };
-        }
+        await mkdir(dirname(client.configPath), { recursive: true });
+        publication = await ClientConfigurationPublication.write(transactionPath, serialized.value, original, 0o600);
     }
     catch (cause) {
-        if (cause instanceof RegularFileCleanupFailure)
+        if (isClientConfigurationCleanupFailure(cause))
             throw cause;
-        // Readback failure restores the transaction before reporting.
+        // Write failure is reported by the status reason.
         void cause;
-        await restoreConfig(transactionPath, original);
-        return { status: "failed", reason: "readback" };
+        return { status: "failed", reason: "write" };
     }
-    return {
-        status: "configured",
-        ...(backupPath === undefined ? {} : { backupPath }),
-    };
+    return publication.verify(async () => {
+        try {
+            const readback = parseClientConfiguration(await readRegularFileText(publication.path), format);
+            await publication.assertCurrent();
+            if (!registrationCurrent(readback, desired) ||
+                Object.entries(fallbackServers).some(([name, entry]) => name !== PRODUCT_IDENTITY.mcpServerKey &&
+                    !clientConfigurationValuesEqual(readback.servers[name], entry))) {
+                return rollbackOrReadbackFailure(publication, original, recoveryBackupPath);
+            }
+        }
+        catch (cause) {
+            if (cause instanceof RegularFileCleanupFailure) {
+                const rollback = await restoreConfig(publication, 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;
+            return rollbackOrReadbackFailure(publication, original, recoveryBackupPath);
+        }
+        return {
+            status: "configured",
+            ...(recoveryBackupPath === undefined
+                ? {}
+                : { backupPath: recoveryBackupPath }),
+        };
+    });
 };
 /** Determine whether an existing client configuration matches the desired registration. */
-export const clientConfigurationAligned = async (client, providerEnvironment, command) => {
+export const clientConfigurationAligned = async (client, providerEnvironment, command, resolveProviderRequestBudget) => {
     if (client.configPathError !== undefined)
         return false;
     try {
@@ -145,13 +234,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, resolveProviderRequestBudget));
         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, resolveProviderRequestBudget)));
     }
     catch (cause) {
         if (cause instanceof RegularFileCleanupFailure)
@@ -162,7 +251,17 @@ export const clientConfigurationAligned = async (client, providerEnvironment, co
     }
 };
 /** Preflight one client configuration before setup presents any mutations. */
-export const inspectClientConfiguration = async (client, providerEnvironment, command) => {
+export const inspectClientConfiguration = async (client, providerEnvironment, command, resolveProviderRequestBudget) => {
+    const inspection = await inspectClientDocument(client, providerEnvironment, command, resolveProviderRequestBudget);
+    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, resolveProviderRequestBudget) => {
     if (client.configPathError !== undefined)
         return { status: "invalid", remediation: client.configPathError };
     if (client.format === "unsupported")
@@ -175,7 +274,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, resolveProviderRequestBudget));
     if (!policy.ok) {
         throwCleanupFailure(policy.error);
         return {
@@ -198,8 +306,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 +321,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, resolveProviderRequestBudget));
         if (!policy.ok) {
             throwCleanupFailure(policy.error);
             return {
@@ -217,13 +331,20 @@ 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, resolveProviderRequestBudget);
         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)
             throw cause;
+        if (cause instanceof ConfigurationError)
+            return { status: "invalid", remediation: cause.message };
         // Malformed configuration is reported with the invalid remediation.
         void cause;
         return {
@@ -231,9 +352,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,45 +368,153 @@ 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) => {
+const restoreConfig = async (publication, original) => {
     try {
-        if (original === undefined)
-            await rm(path, { force: true });
-        else
-            await writeFile(path, original, { encoding: "utf8", mode: 0o600 });
+        await publication.restore(original);
+        return ok(undefined);
     }
     catch (cause) {
-        // The backup remains available for the remediation reported by setup.
-        void cause;
+        return err({
+            kind: "restore",
+            path: publication.path,
+            detail: errorDetail(cause),
+        });
     }
 };
+const rollbackOrReadbackFailure = async (publication, original, backupPath) => {
+    const rollback = await restoreConfig(publication, original);
+    return rollback.ok
+        ? {
+            status: "failed",
+            reason: "readback",
+            ...(backupPath === undefined ? {} : { backupPath }),
+        }
+        : {
+            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, resolveProviderRequestBudget) => {
+    const effective = effectiveClientConfiguration(sources, {
+        client,
+        document: parsed,
+    });
     const format = parsed?.dialect ?? client.format ?? "json";
+    const launcher = command.length === 0 ? [PRODUCT_IDENTITY.cliBinary, "mcp"] : command;
+    if (format === "dsh") {
+        const validated = clientRegistrationEnvironment(effective, providerEnvironment);
+        if (!validated.ok)
+            throw validated.error;
+        const desired = (parsed === undefined
+            ? new DshCordisDocument("")
+            : dshDocument(parsed.document)).desired(launcher, providerEnvironment);
+        if (!desired.ok)
+            throw desired.error;
+        return desired.value;
+    }
+    const validated = clientRegistrationEnvironmentDetails(effective, providerEnvironment, "effective", client.name === "codex" || client.name === "kimi"
+        ? resolveProviderRequestBudget
+        : undefined);
+    if (!validated.ok)
+        throw validated.error;
     // 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);
+    // environment. The effective layered view validates precedence and supplies
+    // timeout facts; the target file's fragment remains the value being written.
+    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 registrationEnvironment = client.name === "kimi" &&
+        environment.value.REA_MCP_INPUT_SCHEMA_PROFILE === undefined
+        ? {
+            ...environment.value,
+            REA_MCP_INPUT_SCHEMA_PROFILE: "compact",
+        }
+        : environment.value;
+    const registration = clientRegistrationEntry(format, launcher, registrationEnvironment);
+    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"
             ? {
-                startup_timeout_sec: MCP_STARTUP_POLICY.codexStartupTimeoutSeconds,
+                startup_timeout_sec: client.name === "codex"
+                    ? (positiveTimeout(previous, "startup_timeout_sec") ??
+                        MCP_STARTUP_POLICY.codexStartupTimeoutSeconds)
+                    : MCP_STARTUP_POLICY.codexStartupTimeoutSeconds,
+            }
+            : {}),
+        ...(client.name === "codex"
+            ? {
+                tool_timeout_sec: positiveTimeout(previous, "tool_timeout_sec") ??
+                    recommendedMcpToolTimeoutSeconds(validated.value.timeoutInputs),
+            }
+            : {}),
+        ...(client.name === "kimi"
+            ? {
+                startupTimeoutMs: positiveTimeout(previous, "startupTimeoutMs") ??
+                    MCP_STARTUP_POLICY.kimiStartupTimeoutMs,
+                toolTimeoutMs: positiveTimeout(previous, "toolTimeoutMs") ??
+                    recommendedMcpToolTimeoutMs(validated.value.timeoutInputs),
             }
             : {}),
     };
 };
+const positiveTimeout = (registration, key) => {
+    if (typeof registration !== "object" || registration === null)
+        return;
+    const value = Reflect.get(registration, key);
+    // TOML keeps integers beyond the safe Number range exact as bigint.
+    if (typeof value === "bigint")
+        return value > 0n ? value : undefined;
+    return typeof value === "number" && Number.isFinite(value) && value > 0
+        ? value
+        : undefined;
+};

package/dist/application/SetupClients.js

@@ -1,11 +1,26 @@
-const failedConfigurationMessage = (reason) => {
-    if (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")
-        return "Agent configuration could not be backed up, so no change was made. Check file permissions, then rerun setup.";
-    if (reason === "write")
-        return "Agent configuration could not be updated. Check file permissions, then rerun setup.";
-    return "Agent configuration could not be verified after writing. Repair the configuration file or restore its `.rea.backup`, then rerun setup.";
+export const failedConfigurationMessage = (result) => {
+    switch (result.reason) {
+        case "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.";
+        case "target_unavailable":
+            return `The client configuration read target could not be established because ${result.failure.path} could not be inspected: ${result.failure.detail}. Repair access to that path, then rerun setup.`;
+        case "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.";
+        case "backup":
+            return "Agent configuration could not be backed up, so no change was made. Check file permissions, then rerun setup.";
+        case "write":
+            return "Agent configuration could not be updated. Check file permissions, then rerun setup.";
+        case "shadowed_member":
+            return `Agent configuration repeats the member at ${JSON.stringify(result.path)}; removing the member the client reads would activate an earlier duplicate, so no change was made. Remove the duplicate members, then rerun setup.`;
+        case "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.`;
+        case "readback":
+            return result.backupPath === undefined
+                ? "Agent configuration could not be verified. Repair the configuration file, then rerun setup."
+                : `Agent configuration could not be verified after writing. The original was restored and its backup at ${result.backupPath} was retained. Repair the configuration file or restore that backup, then rerun setup.`;
+    }
 };
 /** Configure every detected agent and report the first failed transaction. */
 export const configureDetectedClients = async (options) => {
@@ -17,12 +32,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") {