@tacuchi/agent-workflow-cli 22.4.2 → 24.0.0

package/dist/application/mcp-host-writer.js

@@ -1,32 +1,84 @@
-import { existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync, } from "node:fs";
+import { closeSync, existsSync, fchmodSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync, } from "node:fs";
 import { dirname, join } from "node:path";
 import { isDeepStrictEqual } from "node:util";
 import { parse as parseToml } from "smol-toml";
-import { isDbhubManagedEntry, } from "../domain/mcp-entry.js";
+import { mcpEntryShapeForHost, } from "../domain/mcp-entry.js";
 import { crushGlobalMcpFile, opencodeGlobalMcpFile } from "./mcp-host-paths.js";
 import { backupFile, escapeRegex, purgeStaleBackups } from "./multiroot/paths.js";
 import { resolveWarpGlobalMcpPath, resolveWarpProjectMcpPath } from "./multiroot/warp.js";
 // Atomic replace: stage to a tmp sibling and rename over the target. At global
 // scope the targets are live user files (~/.claude.json is rewritten by any
 // running Claude Code session); rename keeps a concurrent reader from seeing a
-// truncated/half-written file. Lost-update between two writers remains possible
-// (would need locking) — accepted residual risk.
-let atomicWriteCounter = 0;
+// truncated/half-written file. `withHostConfigLock` serializes Workline
+// writers; an external host can still race, so every caller must read back.
+const MAX_ATOMIC_TEMP_ATTEMPTS = 64;
 function atomicWriteFileSync(path, content) {
-    const tmp = `${path}.${process.pid}.${++atomicWriteCounter}.tmp`;
+    let descriptor;
+    let tmp;
     try {
-        writeFileSync(tmp, content, "utf-8");
+        const staged = reserveAtomicTempFile(path);
+        descriptor = staged.descriptor;
+        tmp = staged.path;
+        // The temporary file is exclusively created with 0600. Tighten it again
+        // where POSIX permissions exist; Windows ACL filesystems can reject
+        // fchmod, and that must not turn an otherwise safe atomic replacement
+        // into a platform-specific setup failure.
+        try {
+            fchmodSync(descriptor, 0o600);
+        }
+        catch {
+            // The exclusive create mode above remains the only portable guarantee.
+        }
+        writeFileSync(descriptor, content, "utf-8");
+        closeSync(descriptor);
+        descriptor = undefined;
         renameSync(tmp, path);
+        tmp = undefined;
     }
     catch (err) {
+        if (descriptor !== undefined)
+            closeAtomicTempFile(descriptor);
+        if (tmp !== undefined)
+            discardAtomicTempFile(tmp);
+        throw err;
+    }
+}
+function reserveAtomicTempFile(path) {
+    for (let attempt = 0; attempt < MAX_ATOMIC_TEMP_ATTEMPTS; attempt += 1) {
+        const tmp = `${path}.${process.pid}.${attempt + 1}.tmp`;
         try {
-            unlinkSync(tmp);
+            return { path: tmp, descriptor: openSync(tmp, "wx", 0o600) };
         }
-        catch {
-            // tmp may not exist if writeFileSync failed before creating it
+        catch (error) {
+            if (filesystemErrorCode(error) === "EEXIST")
+                continue;
+            throw error;
         }
-        throw err;
     }
+    throw new McpWriterError("no se pudo reservar un archivo temporal seguro para la configuración MCP", path);
+}
+function closeAtomicTempFile(descriptor) {
+    try {
+        closeSync(descriptor);
+    }
+    catch {
+        // The failed write is reported below; cleanup is best-effort.
+    }
+}
+function discardAtomicTempFile(path) {
+    try {
+        unlinkSync(path);
+    }
+    catch {
+        // Only an exclusively-created temp reaches this branch. It may already
+        // have been removed by the filesystem after a failed write.
+    }
+}
+function filesystemErrorCode(error) {
+    if (error === null || typeof error !== "object")
+        return undefined;
+    const code = error.code;
+    return typeof code === "string" ? code : undefined;
 }
 function claudeMcpFile(scope) {
     return scope.kind === "global"
@@ -36,58 +88,69 @@ function claudeMcpFile(scope) {
 function legacyClaudeSettingsFile(scope) {
     return join(scope.scopeDir, ".claude", "settings.json");
 }
-function cleanupLegacyClaudeMcpEntry(scope, name, dryRun) {
-    if (dryRun)
-        return;
-    const legacy = legacyClaudeSettingsFile(scope);
-    if (!existsSync(legacy))
-        return;
+/**
+ * The old Claude settings location is still live user configuration. A
+ * same-named server there is ours only when it has the exact current generated
+ * Claude shape. Invalid containers are also a conflict: writing a second
+ * location while one cannot be safely interpreted would make the operation
+ * partially mutate the user's configuration.
+ */
+function inspectLegacyClaudeMcpEntry(scope, entry, replaceLegacy) {
+    const target = legacyClaudeSettingsFile(scope);
+    if (!existsSync(target))
+        return { state: "absent", target };
     let data;
     try {
-        const text = readFileSync(legacy, "utf-8");
+        const text = readFileSync(target, "utf-8");
         if (text.trim().length === 0)
-            return;
+            return { state: "absent", target };
         const parsed = JSON.parse(text);
-        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
-            return;
+        if (!isRecord(parsed))
+            return { state: "conflict", target };
         data = parsed;
     }
     catch {
-        return;
+        return { state: "conflict", target };
     }
-    const mcpServers = data.mcpServers;
-    if (!mcpServers || typeof mcpServers !== "object" || Array.isArray(mcpServers))
-        return;
-    const servers = mcpServers;
-    if (!(name in servers))
-        return;
-    // Ownership guard: at global scope this file is the user's real
-    // ~/.claude/settings.json — a same-named entry the tool never wrote stays.
-    const existing = servers[name];
-    if (!existing || typeof existing !== "object" || Array.isArray(existing))
+    const current = data.mcpServers;
+    if (current === undefined)
+        return { state: "absent", target };
+    if (!isRecord(current))
+        return { state: "conflict", target };
+    if (!(entry.name in current))
+        return { state: "absent", target };
+    const expected = mcpEntryShapeForHost("claude", entry);
+    const legacy = replaceLegacy === undefined ? undefined : mcpEntryShapeForHost("claude", replaceLegacy);
+    if (!isDeepStrictEqual(current[entry.name], expected) &&
+        !isDeepStrictEqual(current[entry.name], legacy)) {
+        return { state: "conflict", target };
+    }
+    return { state: "owned", target, data, servers: current };
+}
+function cleanupLegacyClaudeMcpEntry(scope, entry, dryRun, replaceLegacy) {
+    if (dryRun)
         return;
-    if (!isDbhubManagedEntry(existing))
+    const legacy = inspectLegacyClaudeMcpEntry(scope, entry, replaceLegacy);
+    if (legacy.state !== "owned")
         return;
-    servers[name] = undefined;
-    const remaining = Object.fromEntries(Object.entries(servers).filter(([, v]) => v !== undefined));
+    legacy.servers[entry.name] = undefined;
+    const remaining = Object.fromEntries(Object.entries(legacy.servers).filter(([, value]) => value !== undefined));
     if (Object.keys(remaining).length === 0) {
-        data.mcpServers = undefined;
+        legacy.data.mcpServers = undefined;
     }
     else {
-        data.mcpServers = remaining;
+        legacy.data.mcpServers = remaining;
     }
-    purgeStaleBackups(legacy);
-    const legacyBackup = backupFile(legacy);
-    atomicWriteFileSync(legacy, `${JSON.stringify(data, null, 2)}\n`);
+    purgeStaleBackups(legacy.target);
+    const legacyBackup = backupFile(legacy.target);
+    atomicWriteFileSync(legacy.target, `${JSON.stringify(legacy.data, null, 2)}\n`);
     discardBackup(legacyBackup);
 }
 export class McpWriterError extends Error {
     target;
-    cause;
-    constructor(message, target, cause) {
+    constructor(message, target) {
         super(message);
         this.target = target;
-        this.cause = cause;
         this.name = "McpWriterError";
     }
 }
@@ -100,6 +163,16 @@ export class McpWriterError extends Error {
  * `assertNeverHost` default turns that into a compile error instead.
  */
 export function writeMcpEntry(host, entry, scope, opts = {}) {
+    if (opts.dryRun)
+        return writeMcpEntryUnlocked(host, entry, scope, opts);
+    return withHostConfigLock(hostConfigTarget(host, scope), () => writeMcpEntryUnlocked(host, entry, scope, opts));
+}
+export function removeMcpEntry(host, entry, scope, opts = {}) {
+    if (opts.dryRun)
+        return removeMcpEntryUnlocked(host, entry, scope, opts);
+    return withHostConfigLock(hostConfigTarget(host, scope), () => removeMcpEntryUnlocked(host, entry, scope, opts));
+}
+function writeMcpEntryUnlocked(host, entry, scope, opts) {
     switch (host) {
         case "claude":
             return writeClaudeMcpEntry(entry, scope, opts);
@@ -119,7 +192,7 @@ export function writeMcpEntry(host, entry, scope, opts = {}) {
             return assertNeverHost(host);
     }
 }
-export function removeMcpEntry(host, entry, scope, opts = {}) {
+function removeMcpEntryUnlocked(host, entry, scope, opts) {
     switch (host) {
         case "claude":
             return removeClaudeMcpEntry(entry, scope, opts);
@@ -139,6 +212,62 @@ export function removeMcpEntry(host, entry, scope, opts = {}) {
             return assertNeverHost(host);
     }
 }
+function hostConfigTarget(host, scope) {
+    switch (host) {
+        case "claude":
+            return claudeMcpFile(scope);
+        case "codex":
+            return join(scope.scopeDir, ".codex", "config.toml");
+        case "warp":
+            return warpMcpFile(scope);
+        case "gemini":
+            return geminiMcpFile(scope);
+        case "kimi":
+            return kimiMcpFile(scope);
+        case "opencode":
+            return opencodeMcpFile(scope);
+        case "crush":
+            return crushMcpFile(scope);
+        default:
+            return assertNeverHost(host);
+    }
+}
+/**
+ * Serializes the whole read-modify-write window, not merely the final rename.
+ * A competing writer fails explicitly instead of silently dropping one host
+ * entry. A stale lock is intentionally not guessed away: removing it requires
+ * an operator decision because it may belong to another live process.
+ */
+function withHostConfigLock(target, work) {
+    const lock = `${target}.agent-workflow.lock`;
+    mkdirSync(dirname(lock), { recursive: true });
+    let descriptor;
+    try {
+        descriptor = openSync(lock, "wx", 0o600);
+    }
+    catch (error) {
+        if (filesystemErrorCode(error) === "EEXIST") {
+            throw new McpWriterError("otro proceso está actualizando esta configuración MCP; reintentá cuando termine", target);
+        }
+        throw error;
+    }
+    try {
+        return work();
+    }
+    finally {
+        try {
+            closeSync(descriptor);
+        }
+        finally {
+            try {
+                unlinkSync(lock);
+            }
+            catch {
+                // A remaining lock is safer than claiming a concurrent write succeeded.
+            }
+        }
+    }
+}
 /** Compile-time exhaustiveness; at runtime it refuses instead of writing somewhere wrong. */
 function assertNeverHost(host) {
     const id = String(host);
@@ -169,57 +298,30 @@ function crushMcpFile(scope) {
 function kimiMcpFile(scope) {
     return join(scope.scopeDir, ".kimi-code", "mcp.json");
 }
-// Per-host serialization of a dbhub McpEntry into the host's JSON schema.
-// Exhaustive for the same reason the dispatchers are: a new host must state its
-// shape, not inherit Claude's by falling off the end.
-function mcpShapeFor(host, entry) {
-    switch (host) {
-        case "opencode":
-            // OpenCode: { type: "local", command: [cmd, ...args], environment, enabled }
-            return {
-                type: "local",
-                command: [entry.command, ...entry.args],
-                environment: { ...entry.env },
-                enabled: true,
-            };
-        case "crush":
-            // Crush: { type: "stdio", command, args, env }
-            return {
-                type: "stdio",
-                command: entry.command,
-                args: [...entry.args],
-                env: { ...entry.env },
-            };
-        case "claude":
-        case "codex":
-        case "warp":
-        case "gemini":
-        // Kimi's stdio entry is `command` + optional `args`/`env`/`cwd` — the same
-        // shape, verified against v0.29.2's MCP config schema.
-        case "kimi":
-            return expectedClaudeShape(entry);
-        default:
-            return assertNeverHost(host);
-    }
-}
 // Generic writer for hosts whose MCP config is a JSON file with a top-level
 // object keyed by server name (Gemini `mcpServers`, OpenCode/Crush `mcp`).
 // Preserves other top-level keys and other server entries; idempotent; dry-run;
 // transient backup purged on success.
 function writeJsonMcpEntry(host, file, topKey, entry, opts) {
     const data = readJsonFile(file);
-    const bag = ensureRecord(data, topKey);
+    const bag = recordContainer(data, topKey, file) ?? {};
     const existing = bag[entry.name];
-    const expected = mcpShapeFor(host, entry);
+    const expected = mcpEntryShapeForHost(host, entry);
+    const legacy = opts.replaceLegacy === undefined ? undefined : mcpEntryShapeForHost(host, opts.replaceLegacy);
     if (isDeepStrictEqual(existing, expected)) {
         return resultSkipped(host, file, entry.name);
     }
+    // A matching name is not enough to establish ownership. Replacing a server
+    // whose shape differs would overwrite somebody else's configuration.
+    if (existing !== undefined && !isDeepStrictEqual(existing, legacy)) {
+        return resultConflict(host, file, entry.name);
+    }
     bag[entry.name] = expected;
     data[topKey] = bag;
     const newJson = `${JSON.stringify(data, null, 2)}\n`;
     if (opts.dryRun) {
         return resultDryRun(host, file, entry.name, [
-            `${topKey}.${entry.name}: ${existing ? "update" : "add"}`,
+            `${topKey}.${entry.name}: ${existing === undefined ? "add" : "replace known legacy"}`,
         ]);
     }
     mkdirSync(dirname(file), { recursive: true });
@@ -231,11 +333,18 @@ function writeJsonMcpEntry(host, file, topKey, entry, opts) {
 }
 function removeJsonMcpEntry(host, file, topKey, entry, opts) {
     const data = readJsonFile(file);
-    const bag = ensureRecord(data, topKey);
+    const bag = recordContainer(data, topKey, file);
+    if (bag === undefined)
+        return resultSkipped(host, file, entry.name);
     const existing = bag[entry.name];
+    const expected = mcpEntryShapeForHost(host, entry);
+    const legacy = opts.replaceLegacy === undefined ? undefined : mcpEntryShapeForHost(host, opts.replaceLegacy);
     if (existing === undefined) {
         return resultSkipped(host, file, entry.name);
     }
+    if (!isDeepStrictEqual(existing, expected) && !isDeepStrictEqual(existing, legacy)) {
+        return resultConflict(host, file, entry.name);
+    }
     bag[entry.name] = undefined;
     const remaining = Object.fromEntries(Object.entries(bag).filter(([, v]) => v !== undefined));
     data[topKey] = Object.keys(remaining).length === 0 ? undefined : remaining;
@@ -250,33 +359,60 @@ function removeJsonMcpEntry(host, file, topKey, entry, opts) {
     discardBackup(backup);
     return resultRemoved(host, file, entry.name, null);
 }
-// Claude = the generic JSON writer plus the legacy .claude/settings.json sweep,
-// which runs exactly when the original inline pipeline did: on idempotent skips
-// (respecting dry-run) and after a real write/remove — never on dry-run diffs.
+// Claude = the generic JSON writer plus an ownership-checked legacy
+// .claude/settings.json sweep. A foreign or malformed legacy entry stops before
+// the primary file changes; an exact own entry is swept on a real write/remove.
 function writeClaudeMcpEntry(entry, scope, opts) {
+    const legacy = inspectLegacyClaudeMcpEntry(scope, entry, opts.replaceLegacy);
+    if (legacy.state === "conflict")
+        return resultConflict("claude", legacy.target, entry.name);
     const res = writeJsonMcpEntry("claude", claudeMcpFile(scope), "mcpServers", entry, opts);
-    if (res.action === "skipped-idempotent")
-        cleanupLegacyClaudeMcpEntry(scope, entry.name, opts.dryRun ?? false);
-    if (res.action === "written")
-        cleanupLegacyClaudeMcpEntry(scope, entry.name, false);
+    // The canonical entry may already be present while the old location still
+    // needs a cleanup. That is still an observable write: report it as such so
+    // a caller's dry-run and first-mutation guard do not mistake it for a noop.
+    if (legacy.state === "owned" && res.action === "skipped-idempotent") {
+        if (opts.dryRun)
+            return resultDryRun("claude", legacy.target, entry.name, [
+                `mcpServers.${entry.name}: remove legacy entry`,
+            ]);
+        try {
+            cleanupLegacyClaudeMcpEntry(scope, entry, false, opts.replaceLegacy);
+            return resultWritten("claude", legacy.target, entry.name, null);
+        }
+        catch {
+            return partialLegacyCleanup(res, legacy.target);
+        }
+    }
+    if (legacy.state === "owned" && res.action === "written") {
+        try {
+            cleanupLegacyClaudeMcpEntry(scope, entry, false, opts.replaceLegacy);
+        }
+        catch {
+            // The primary descriptor is already durable. Do not hide that mutation
+            // or roll it back blindly: the old location might have been changed by a
+            // host meanwhile. The caller will fail readback, withhold the receipt,
+            // and a later explicit setup/migration can retry exact cleanup.
+            return partialLegacyCleanup(res, legacy.target);
+        }
+    }
     return res;
 }
 function writeCodexMcpEntry(entry, scope, opts) {
     const configFile = join(scope.scopeDir, ".codex", "config.toml");
     const oldContent = existsSync(configFile) ? readFileSync(configFile, "utf-8") : "";
-    let parsed;
-    try {
-        parsed = oldContent.length > 0 ? parseToml(oldContent) : {};
-    }
-    catch (err) {
-        throw new McpWriterError(`config.toml inválido en ${configFile}`, configFile, err.message);
-    }
-    const mcpServers = (parsed.mcp_servers ?? {});
+    const parsed = parseCodexConfig(oldContent, configFile);
+    const mcpServers = recordContainer(parsed, "mcp_servers", configFile) ?? {};
     const existing = mcpServers[entry.name];
-    const expected = expectedClaudeShape(entry);
+    const expected = mcpEntryShapeForHost("codex", entry);
+    const legacy = opts.replaceLegacy === undefined
+        ? undefined
+        : mcpEntryShapeForHost("codex", opts.replaceLegacy);
     if (isDeepStrictEqual(existing, expected)) {
         return resultSkipped("codex", configFile, entry.name);
     }
+    if (existing !== undefined && !isDeepStrictEqual(existing, legacy)) {
+        return resultConflict("codex", configFile, entry.name);
+    }
     const cleaned = removeCodexMcpBlocks(oldContent, entry.name);
     const newContent = appendCodexMcpBlocks(cleaned, entry);
     if (newContent === oldContent) {
@@ -284,8 +420,8 @@ function writeCodexMcpEntry(entry, scope, opts) {
     }
     if (opts.dryRun) {
         return resultDryRun("codex", configFile, entry.name, [
-            `[mcp_servers.${entry.name}]: ${existing ? "update" : "add"}`,
-            `[mcp_servers.${entry.name}.env]: ${existing ? "update" : "add"}`,
+            `[mcp_servers.${entry.name}]: ${existing === undefined ? "add" : "replace known legacy"}`,
+            `[mcp_servers.${entry.name}.env]: add`,
         ]);
     }
     mkdirSync(dirname(configFile), { recursive: true });
@@ -296,23 +432,55 @@ function writeCodexMcpEntry(entry, scope, opts) {
     return resultWritten("codex", configFile, entry.name, null);
 }
 function removeClaudeMcpEntry(entry, scope, opts) {
+    const legacy = inspectLegacyClaudeMcpEntry(scope, entry, opts.replaceLegacy);
+    if (legacy.state === "conflict")
+        return resultConflict("claude", legacy.target, entry.name);
     const res = removeJsonMcpEntry("claude", claudeMcpFile(scope), "mcpServers", entry, opts);
-    if (res.action === "skipped-idempotent")
-        cleanupLegacyClaudeMcpEntry(scope, entry.name, opts.dryRun ?? false);
-    if (res.action === "removed")
-        cleanupLegacyClaudeMcpEntry(scope, entry.name, false);
+    // See the matching setup path above: removing an own entry left only in the
+    // legacy file is a removal, not an idempotent skip.
+    if (legacy.state === "owned" && res.action === "skipped-idempotent") {
+        if (opts.dryRun)
+            return resultDryRun("claude", legacy.target, entry.name, [
+                `mcpServers.${entry.name}: remove legacy entry`,
+            ]);
+        try {
+            cleanupLegacyClaudeMcpEntry(scope, entry, false, opts.replaceLegacy);
+            return resultRemoved("claude", legacy.target, entry.name, null);
+        }
+        catch {
+            return partialLegacyCleanup(res, legacy.target);
+        }
+    }
+    if (legacy.state === "owned" && res.action === "removed") {
+        try {
+            cleanupLegacyClaudeMcpEntry(scope, entry, false, opts.replaceLegacy);
+        }
+        catch {
+            // As in setup, the primary removal is real but legacy retirement is not
+            // complete. Keep the receipt and registry through the caller's partial
+            // error path so the next explicit remove can recover safely.
+            return partialLegacyCleanup(res, legacy.target);
+        }
+    }
     return res;
 }
 function removeCodexMcpEntry(entry, scope, opts) {
     const configFile = join(scope.scopeDir, ".codex", "config.toml");
     const oldContent = existsSync(configFile) ? readFileSync(configFile, "utf-8") : "";
-    if (oldContent.length > 0) {
-        try {
-            parseToml(oldContent);
-        }
-        catch (err) {
-            throw new McpWriterError(`config.toml inválido en ${configFile}`, configFile, err.message);
-        }
+    const parsed = parseCodexConfig(oldContent, configFile);
+    const mcpServers = recordContainer(parsed, "mcp_servers", configFile);
+    if (mcpServers === undefined)
+        return resultSkipped("codex", configFile, entry.name);
+    const existing = mcpServers[entry.name];
+    if (existing === undefined) {
+        return resultSkipped("codex", configFile, entry.name);
+    }
+    const legacy = opts.replaceLegacy === undefined
+        ? undefined
+        : mcpEntryShapeForHost("codex", opts.replaceLegacy);
+    if (!isDeepStrictEqual(existing, mcpEntryShapeForHost("codex", entry)) &&
+        !isDeepStrictEqual(existing, legacy)) {
+        return resultConflict("codex", configFile, entry.name);
     }
     const newContent = removeCodexMcpBlocks(oldContent, entry.name);
     if (newContent === oldContent) {
@@ -352,30 +520,42 @@ function readJsonFile(file) {
         return {};
     try {
         const parsed = JSON.parse(text);
-        if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+        if (isRecord(parsed))
             return parsed;
-        }
         throw new Error("contenido no es un objeto JSON");
     }
-    catch (err) {
-        throw new McpWriterError(`JSON inválido en ${file}`, file, err.message);
+    catch {
+        throw new McpWriterError(`JSON inválido en ${file}`, file);
     }
 }
-function ensureRecord(parent, key) {
+function parseCodexConfig(content, configFile) {
+    if (content.trim().length === 0)
+        return {};
+    try {
+        const parsed = parseToml(content);
+        if (isRecord(parsed))
+            return parsed;
+        throw new Error("contenido TOML no es un objeto");
+    }
+    catch {
+        throw new McpWriterError(`config.toml inválido en ${configFile}`, configFile);
+    }
+}
+/**
+ * Missing MCP containers are created only by a successful write. A present
+ * scalar, null, or array is malformed user configuration and must never be
+ * replaced with an empty object behind their back.
+ */
+function recordContainer(parent, key, file) {
     const current = parent[key];
-    if (current && typeof current === "object" && !Array.isArray(current)) {
+    if (current === undefined)
+        return undefined;
+    if (isRecord(current))
         return current;
-    }
-    const fresh = {};
-    parent[key] = fresh;
-    return fresh;
+    throw new McpWriterError(`contenedor '${key}' inválido en ${file}`, file);
 }
-function expectedClaudeShape(entry) {
-    return {
-        command: entry.command,
-        args: [...entry.args],
-        env: { ...entry.env },
-    };
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
 }
 // backupFile/purgeStaleBackups/escapeRegex live in multiroot/paths.ts (single
 // backup mechanism for host-config files: keep-latest, purge-then-copy).
@@ -420,6 +600,8 @@ export function appendCodexMcpBlocks(text, entry) {
     buffer.push(`[mcp_servers.${entry.name}]`);
     buffer.push(`command = ${tomlString(entry.command)}`);
     buffer.push(`args = [${entry.args.map(tomlString).join(", ")}]`);
+    if (entry.optional)
+        buffer.push("required = false");
     buffer.push("");
     buffer.push(`[mcp_servers.${entry.name}.env]`);
     for (const [k, v] of Object.entries(entry.env)) {
@@ -444,6 +626,19 @@ function resultSkipped(host, target, name) {
 function resultDryRun(host, target, name, diff) {
     return { ...action(host, target, name, "dry-run", null), diff };
 }
+function resultConflict(host, target, name) {
+    return action(host, target, name, "conflict", null);
+}
+function partialLegacyCleanup(result, target) {
+    return {
+        ...result,
+        partial: {
+            code: "MCP_LEGACY_CLEANUP_FAILED",
+            target,
+            message: "No se pudo retirar la ubicación legacy de Claude; no recargues el host y reintentá la operación.",
+        },
+    };
+}
 function action(host, target, name, status, backup) {
     return { host, target, name, action: status, backup };
 }