oh-my-codex 0.16.2 → 0.16.4

package/dist/cli/setup.js

@@ -9,7 +9,7 @@ import { spawnSync } from "child_process";
 import { createInterface } from "readline/promises";
 import { homedir } from "os";
 import { codexHome, codexConfigPath, codexPromptsDir, codexAgentsDir, userSkillsDir, omxStateDir, detectLegacySkillRootOverlap, omxPlansDir, omxLogsDir, } from "../utils/paths.js";
-import { buildMergedConfig, getRootModelName, hasLegacyOmxTeamRunTable, stripExistingOmxBlocks, stripExistingSharedMcpRegistryBlock, stripOmxEnvSettings, stripOmxFeatureFlags, stripOmxSeededBehavioralDefaults, upsertPluginModeRuntimeFeatureFlags, upsertManagedCodexHookTrustState, stripManagedCodexHookTrustState, OMX_PLUGIN_DEVELOPER_INSTRUCTIONS, } from "../config/generator.js";
+import { buildMergedConfig, getRootModelName, getRootTomlArray, hasLegacyOmxTeamRunTable, isOmxManagedNotifyCommand, sanitizePreviousNotifyCommand, stripExistingOmxBlocks, stripExistingSharedMcpRegistryBlock, mergeSharedMcpRegistryBlock, stripOmxEnvSettings, stripOmxFeatureFlags, stripOmxSeededBehavioralDefaults, upsertPluginModeRuntimeFeatureFlags, upsertManagedCodexHookTrustState, stripManagedCodexHookTrustState, OMX_PLUGIN_DEVELOPER_INSTRUCTIONS, } from "../config/generator.js";
 import { mergeManagedCodexHooksConfig } from "../config/codex-hooks.js";
 import { getLegacyUnifiedMcpRegistryCandidate, getUnifiedMcpRegistryCandidates, loadUnifiedMcpRegistry, planClaudeCodeMcpSettingsSync, } from "../config/mcp-registry.js";
 import { generateAgentToml } from "../agents/native-config.js";
@@ -22,8 +22,9 @@ import { tryReadCatalogManifest } from "../catalog/reader.js";
 import { DEFAULT_FRONTIER_MODEL } from "../config/models.js";
 import { addGeneratedAgentsMarker, hasOmxManagedAgentsSections, isOmxGeneratedAgentsMd, upsertManagedAgentsBlock, } from "../utils/agents-md.js";
 import { DEFAULT_HUD_CONFIG } from "../hud/types.js";
-import { SETUP_INSTALL_MODES, SETUP_SCOPES, getSetupScopeFilePath, readPersistedSetupPreferences, } from "./setup-preferences.js";
-import { OMX_LOCAL_MARKETPLACE_NAME, resolvePackagedOmxMarketplace, upsertLocalOmxMarketplaceRegistration, } from "./plugin-marketplace.js";
+import { SETUP_INSTALL_MODES, SETUP_MCP_MODES, SETUP_SCOPES, getSetupScopeFilePath, readPersistedSetupPreferences, } from "./setup-preferences.js";
+import { OMX_LOCAL_MARKETPLACE_NAME, resolvePackagedOmxMarketplace, upsertLocalOmxMarketplaceRegistration, upsertLocalOmxPluginEnablement, upsertLocalOmxPluginMcpServerEnablement, } from "./plugin-marketplace.js";
+import { resolveCodexHookFeatureFlagForCli } from "./codex-feature-probe.js";
 async function resolveStatusLinePresetForSetup(projectRoot, options) {
     if (options.force) {
         return DEFAULT_HUD_CONFIG.statusLine.preset;
@@ -44,7 +45,7 @@ async function resolveStatusLinePresetForSetup(projectRoot, options) {
     return undefined;
 }
 import { resolveAgentsModelTableContext, upsertAgentsModelTable, } from "../utils/agents-model-table.js";
-export { SETUP_INSTALL_MODES, SETUP_SCOPES };
+export { SETUP_INSTALL_MODES, SETUP_MCP_MODES, SETUP_SCOPES };
 const PROJECT_GITIGNORE_ENTRIES = [
     ".omx/",
     ".codex/*",
@@ -58,6 +59,7 @@ const PROJECT_GITIGNORE_ENTRIES = [
 ];
 const LEGACY_PROJECT_GITIGNORE_ENTRIES = [".codex/"];
 const SETUP_ONLY_INSTALLABLE_SKILLS = new Set(["wiki"]);
+const DEFAULT_SETUP_MCP_MODE = "none";
 const HARD_DEPRECATED_SKILL_NAMES = new Set(["web-clone"]);
 function isCatalogInstallableStatus(status) {
     return status === "active" || status === "internal";
@@ -354,6 +356,7 @@ function formatPersistedSetupPreferenceSummary(preferences) {
     return [
         `scope=${preferences.scope ?? "not recorded"}`,
         `installMode=${preferences.installMode ?? "not recorded"}`,
+        `mcpMode=${preferences.mcpMode ?? "not recorded"}`,
     ].join(", ");
 }
 async function promptForPersistedSetupReview(preferences) {
@@ -628,6 +631,17 @@ async function refreshOmxPluginDiscoveryCache(pkgRoot, options) {
         staleDirs,
     };
 }
+function resolveSetupMcpMode(scope, requestedMcpMode, persistedReviewDecision, persistedPreferences) {
+    if (requestedMcpMode) {
+        return { mcpMode: requestedMcpMode, source: "cli" };
+    }
+    if (persistedPreferences?.mcpMode &&
+        persistedReviewDecision === "keep" &&
+        persistedPreferences.scope === scope) {
+        return { mcpMode: persistedPreferences.mcpMode, source: "persisted" };
+    }
+    return { mcpMode: DEFAULT_SETUP_MCP_MODE, source: "default" };
+}
 async function resolveSetupInstallMode(projectRoot, scope, requestedInstallMode, installModePrompt, persistedReviewDecision = "keep", persistedPreferences) {
     if (requestedInstallMode) {
         return { installMode: requestedInstallMode, source: "cli" };
@@ -888,7 +902,7 @@ function insertRootTomlKey(config, line) {
     const after = lines.slice(firstTableIndex);
     return [...before, line, "", ...after].join("\n") + "\n";
 }
-async function ensurePluginMarketplaceRegistration(configPath, pkgRoot, backupContext, summary, options) {
+async function ensurePluginMarketplaceRegistration(configPath, pkgRoot, mcpMode, backupContext, summary, options) {
     const packagedMarketplace = await resolvePackagedOmxMarketplace(pkgRoot);
     if (!packagedMarketplace) {
         summary.skipped += 1;
@@ -897,7 +911,7 @@ async function ensurePluginMarketplaceRegistration(configPath, pkgRoot, backupCo
     const existingConfig = existsSync(configPath)
         ? await readFile(configPath, "utf-8")
         : "";
-    const nextConfig = upsertLocalOmxMarketplaceRegistration(existingConfig, pkgRoot);
+    const nextConfig = upsertLocalOmxMarketplaceRegistration(upsertLocalOmxPluginMcpServerEnablement(upsertLocalOmxPluginEnablement(existingConfig), mcpMode === "compat"), pkgRoot);
     const destinationExists = existsSync(configPath);
     if (nextConfig === existingConfig) {
         summary.unchanged += 1;
@@ -920,7 +934,7 @@ async function applyPluginModeHooksConfig(configPath, hooksPath, pkgRoot, backup
     const existingConfig = existsSync(configPath)
         ? await readFile(configPath, "utf-8")
         : "";
-    const nextConfig = upsertManagedCodexHookTrustState(upsertPluginModeRuntimeFeatureFlags(stripManagedCodexHookTrustState(existingConfig)), pkgRoot, hooksPath);
+    const nextConfig = upsertManagedCodexHookTrustState(upsertPluginModeRuntimeFeatureFlags(stripManagedCodexHookTrustState(existingConfig), options.codexHookFeatureFlag), pkgRoot, hooksPath);
     if (nextConfig !== existingConfig) {
         if (await ensureBackup(configPath, existsSync(configPath), backupContext, options)) {
             summary.backedUp += 1;
@@ -1028,7 +1042,7 @@ async function cleanupPluginModeLegacyAgentsMd(agentsMdPath, backupContext, opti
     return true;
 }
 export async function setup(options = {}) {
-    const { force = false, dryRun = false, installMode: requestedInstallMode, scope: requestedScope, verbose = false, setupScopePrompt, persistedSetupReviewPrompt, installModePrompt, modelUpgradePrompt, pluginAgentsMdPrompt, pluginDeveloperInstructionsPrompt, pluginDeveloperInstructionsOverwritePrompt, } = options;
+    const { force = false, dryRun = false, installMode: requestedInstallMode, mcpMode: requestedMcpMode, scope: requestedScope, verbose = false, setupScopePrompt, persistedSetupReviewPrompt, installModePrompt, modelUpgradePrompt, pluginAgentsMdPrompt, pluginDeveloperInstructionsPrompt, pluginDeveloperInstructionsOverwritePrompt, } = options;
     const pkgRoot = getPackageRoot();
     const projectRoot = process.cwd();
     const persistedPreferences = await readPersistedSetupPreferences(projectRoot, { warnOnLegacyScope: true });
@@ -1039,8 +1053,12 @@ export async function setup(options = {}) {
         Boolean(persistedPreferences?.installMode) &&
         (!persistedPreferences?.scope ||
             persistedPreferences.scope === effectiveScopeForInstallMode);
+    const wouldUsePersistedMcpMode = !requestedMcpMode &&
+        Boolean(persistedPreferences?.mcpMode) &&
+        (!persistedPreferences?.scope ||
+            persistedPreferences.scope === effectiveScopeForInstallMode);
     const shouldReviewPersistedSetup = hasPersistedSetupPreferences(persistedPreferences) &&
-        (wouldUsePersistedScope || wouldUsePersistedInstallMode) &&
+        (wouldUsePersistedScope || wouldUsePersistedInstallMode || wouldUsePersistedMcpMode) &&
         (typeof persistedSetupReviewPrompt === "function" ||
             (process.stdin.isTTY && process.stdout.isTTY));
     if (shouldReviewPersistedSetup) {
@@ -1051,6 +1069,7 @@ export async function setup(options = {}) {
     }
     const resolvedScope = await resolveSetupScope(projectRoot, requestedScope, persistedReviewDecision, persistedPreferences, setupScopePrompt);
     const resolvedInstallMode = await resolveSetupInstallMode(projectRoot, resolvedScope.scope, requestedInstallMode, installModePrompt, persistedReviewDecision, persistedPreferences);
+    const resolvedMcpMode = resolveSetupMcpMode(resolvedScope.scope, requestedMcpMode, persistedReviewDecision, persistedPreferences);
     const scopeDirs = resolveScopeDirectories(resolvedScope.scope, projectRoot);
     const scopeSourceMessage = resolvedScope.source === "persisted" ? " (from .omx/setup-scope.json)" : "";
     const backupContext = getBackupContext(resolvedScope.scope, projectRoot);
@@ -1077,6 +1096,10 @@ export async function setup(options = {}) {
             : "";
         console.log(`Using setup install mode: ${resolvedInstallMode.installMode}${installModeSourceMessage}\n`);
     }
+    const mcpModeSourceMessage = resolvedMcpMode.source === "persisted"
+        ? " (from .omx/setup-scope.json)"
+        : "";
+    console.log(`Using setup MCP mode: ${resolvedMcpMode.mcpMode}${mcpModeSourceMessage}\n`);
     // Step 1: Ensure directories exist
     console.log("[1/8] Creating directories...");
     const dirs = isPluginInstallMode
@@ -1102,16 +1125,15 @@ export async function setup(options = {}) {
         if (verbose)
             console.log(`  mkdir ${dir}`);
     }
-    const setupPreferencesToPersist = resolvedInstallMode &&
-        (resolvedScope.scope === "user" ||
-            resolvedInstallMode.installMode === "plugin")
-        ? {
-            scope: resolvedScope.scope,
-            installMode: resolvedInstallMode.installMode,
-        }
-        : {
-            scope: resolvedScope.scope,
-        };
+    const setupPreferencesToPersist = {
+        scope: resolvedScope.scope,
+        mcpMode: resolvedMcpMode.mcpMode,
+        ...(resolvedInstallMode &&
+            (resolvedScope.scope === "user" ||
+                resolvedInstallMode.installMode === "plugin")
+            ? { installMode: resolvedInstallMode.installMode }
+            : {}),
+    };
     await persistSetupPreferences(projectRoot, setupPreferencesToPersist, {
         dryRun,
         verbose,
@@ -1217,6 +1239,35 @@ export async function setup(options = {}) {
     console.log("[5/8] Updating config.toml...");
     let resolvedConfig = "";
     let omxManagesTui = false;
+    const codexHookFeatureFlag = resolveCodexHookFeatureFlagForCli({
+        codexFeaturesProbe: options.codexFeaturesProbe,
+        codexVersionProbe: options.codexVersionProbe,
+    });
+    if (verbose) {
+        console.log(`  Native Codex hook feature flag: [features].${codexHookFeatureFlag}`);
+    }
+    const shouldSyncSharedMcpRegistry = resolvedMcpMode.mcpMode === "compat";
+    const registryCandidates = getUnifiedMcpRegistryCandidates();
+    const defaultRegistryCandidates = registryCandidates.slice(0, 1);
+    const sharedMcpRegistry = shouldSyncSharedMcpRegistry
+        ? await loadUnifiedMcpRegistry({
+            candidates: options.mcpRegistryCandidates ?? defaultRegistryCandidates,
+        })
+        : { servers: [], warnings: [] };
+    const legacyRegistryCandidate = getLegacyUnifiedMcpRegistryCandidate();
+    if (shouldSyncSharedMcpRegistry &&
+        !options.mcpRegistryCandidates &&
+        !sharedMcpRegistry.sourcePath &&
+        existsSync(legacyRegistryCandidate) &&
+        !existsSync(defaultRegistryCandidates[0])) {
+        console.log(`  warning: legacy shared MCP registry detected at ${legacyRegistryCandidate} but ignored by default; move or copy it to ${defaultRegistryCandidates[0]} and rerun setup with --mcp compat if you still want setup to sync those servers`);
+    }
+    if (verbose && sharedMcpRegistry.sourcePath) {
+        console.log(`  shared MCP registry: ${sharedMcpRegistry.sourcePath} (${sharedMcpRegistry.servers.length} servers)`);
+    }
+    for (const warning of sharedMcpRegistry.warnings) {
+        console.log(`  warning: ${warning}`);
+    }
     if (isPluginInstallMode) {
         const configCleaned = await cleanupPluginModeLegacyConfig(scopeDirs.codexConfigFile, backupContext, { dryRun, verbose });
         if (configCleaned)
@@ -1224,8 +1275,8 @@ export async function setup(options = {}) {
         console.log(configCleaned
             ? `  ${dryRun ? "Would clean" : "Cleaned"} legacy OMX config entries for plugin mode.\n`
             : "  Config refresh skipped; no legacy OMX config entries found.\n");
-        await applyPluginModeHooksConfig(scopeDirs.codexConfigFile, scopeDirs.codexHooksFile, pkgRoot, backupContext, summary.config, { dryRun, verbose });
-        const pluginMarketplaceResult = await ensurePluginMarketplaceRegistration(scopeDirs.codexConfigFile, pkgRoot, backupContext, summary.config, { dryRun, verbose });
+        await applyPluginModeHooksConfig(scopeDirs.codexConfigFile, scopeDirs.codexHooksFile, pkgRoot, backupContext, summary.config, { dryRun, verbose, codexHookFeatureFlag });
+        const pluginMarketplaceResult = await ensurePluginMarketplaceRegistration(scopeDirs.codexConfigFile, pkgRoot, resolvedMcpMode.mcpMode, backupContext, summary.config, { dryRun, verbose });
         if (pluginMarketplaceResult === "unavailable") {
             console.log(`  warning: packaged ${OMX_LOCAL_MARKETPLACE_NAME} Codex plugin marketplace metadata not found; /skills plugin discovery was not registered.`);
         }
@@ -1245,10 +1296,16 @@ export async function setup(options = {}) {
         else if (pluginCacheRefresh.status === "unchanged") {
             console.log("  Codex plugin discovery cache already matches packaged plugin metadata.");
         }
+        if (shouldSyncSharedMcpRegistry) {
+            resolvedConfig = await syncSharedMcpRegistryIntoConfig(scopeDirs.codexConfigFile, sharedMcpRegistry, summary.config, backupContext, { dryRun, verbose });
+            if (resolvedScope.scope === "user") {
+                await syncClaudeCodeMcpSettings(sharedMcpRegistry, summary.config, backupContext, { dryRun, verbose });
+            }
+        }
         resolvedConfig = existsSync(scopeDirs.codexConfigFile)
             ? await readFile(scopeDirs.codexConfigFile, "utf-8")
             : "";
-        console.log(`  Native Codex hooks and runtime feature flags refresh complete (${scopeDirs.codexHooksFile}; codex_hooks, goals).\n`);
+        console.log(`  Native Codex hooks and runtime feature flags refresh complete (${scopeDirs.codexHooksFile}; hooks, goals).\n`);
         if (usePluginDeveloperInstructionsDefault) {
             const developerInstructionsResult = await applyPluginDeveloperInstructionsDefault(scopeDirs.codexConfigFile, backupContext, summary.config, {
                 dryRun,
@@ -1270,38 +1327,21 @@ export async function setup(options = {}) {
         }
     }
     else {
-        const registryCandidates = getUnifiedMcpRegistryCandidates();
-        const defaultRegistryCandidates = registryCandidates.slice(0, 1);
-        const legacyRegistryCandidate = getLegacyUnifiedMcpRegistryCandidate();
-        const sharedMcpRegistry = await loadUnifiedMcpRegistry({
-            candidates: options.mcpRegistryCandidates ?? defaultRegistryCandidates,
-        });
-        if (!options.mcpRegistryCandidates &&
-            !sharedMcpRegistry.sourcePath &&
-            existsSync(legacyRegistryCandidate) &&
-            !existsSync(defaultRegistryCandidates[0])) {
-            console.log(`  warning: legacy shared MCP registry detected at ${legacyRegistryCandidate} but ignored by default; move it to ${defaultRegistryCandidates[0]} if you still want setup to sync those servers`);
-        }
-        if (verbose && sharedMcpRegistry.sourcePath) {
-            console.log(`  shared MCP registry: ${sharedMcpRegistry.sourcePath} (${sharedMcpRegistry.servers.length} servers)`);
-        }
-        for (const warning of sharedMcpRegistry.warnings) {
-            console.log(`  warning: ${warning}`);
-        }
         const statusLinePreset = await resolveStatusLinePresetForSetup(projectRoot, { force });
-        const managedConfig = await updateManagedConfig(scopeDirs.codexConfigFile, scopeDirs.codexHooksFile, pkgRoot, sharedMcpRegistry, summary.config, backupContext, {
+        const managedConfig = await updateManagedConfig(scopeDirs.codexConfigFile, scopeDirs.codexHooksFile, pkgRoot, sharedMcpRegistry, resolvedMcpMode.mcpMode, resolvedScope.scope, scopeDirs.codexHomeDir, summary.config, backupContext, {
             dryRun,
             modelUpgradePrompt,
             verbose,
             statusLinePreset,
             forceStatusLinePreset: force,
+            codexHookFeatureFlag,
         });
         resolvedConfig = managedConfig.finalConfig;
         omxManagesTui = managedConfig.omxManagesTui;
         if (managedConfig.repairedLegacyTeamRunTable) {
             console.log("  Removed retired [mcp_servers.omx_team_run] config during refresh.");
         }
-        if (resolvedScope.scope === "user") {
+        if (shouldSyncSharedMcpRegistry && resolvedScope.scope === "user") {
             await syncClaudeCodeMcpSettings(sharedMcpRegistry, summary.config, backupContext, { dryRun, verbose });
         }
         console.log(`  Config refresh complete (${scopeDirs.codexConfigFile}).\n`);
@@ -2031,7 +2071,69 @@ async function cleanupLegacyManagedSkills(srcDir, dstDir, backupContext, options
     }
     return result;
 }
-async function updateManagedConfig(configPath, hooksPath, pkgRoot, sharedMcpRegistry, summary, backupContext, options) {
+function getNotifyMetadataPath(codexHomeDir) {
+    return join(codexHomeDir, ".omx", "notify-dispatch.json");
+}
+async function buildNotifyMergePlan(existingConfig, pkgRoot, codexHomeDir, scope) {
+    if (scope === "project") {
+        return { notifyCommand: false };
+    }
+    const omxNotify = ["node", join(pkgRoot, "dist", "scripts", "notify-hook.js")];
+    const metadataPath = getNotifyMetadataPath(codexHomeDir);
+    const dispatcherNotify = [
+        "node",
+        join(pkgRoot, "dist", "scripts", "notify-dispatcher.js"),
+        "--metadata",
+        metadataPath,
+    ];
+    const existingNotify = getRootTomlArray(existingConfig, "notify");
+    if (!existingNotify) {
+        return { notifyCommand: omxNotify };
+    }
+    if (isOmxManagedNotifyCommand(existingNotify, pkgRoot)) {
+        if (!existingNotify.some((part) => /(?:^|[\\/])notify-dispatcher\.js$/.test(part))) {
+            return { notifyCommand: omxNotify };
+        }
+        try {
+            const metadata = JSON.parse(await readFile(metadataPath, "utf-8"));
+            const previousNotify = metadata.previousNotify;
+            if (Array.isArray(previousNotify) &&
+                previousNotify.every((item) => typeof item === "string")) {
+                const sanitizedPreviousNotify = sanitizePreviousNotifyCommand(previousNotify, pkgRoot);
+                if (!sanitizedPreviousNotify) {
+                    return { notifyCommand: omxNotify };
+                }
+                return {
+                    notifyCommand: dispatcherNotify,
+                    metadataPath,
+                    metadata: {
+                        managedBy: "oh-my-codex",
+                        version: 1,
+                        previousNotify: sanitizedPreviousNotify,
+                        omxNotify,
+                        dispatcherNotify,
+                    },
+                };
+            }
+        }
+        catch {
+            // Missing dispatcher metadata: fall back to plain OMX notify instead of nesting.
+        }
+        return { notifyCommand: omxNotify };
+    }
+    return {
+        notifyCommand: dispatcherNotify,
+        metadataPath,
+        metadata: {
+            managedBy: "oh-my-codex",
+            version: 1,
+            previousNotify: sanitizePreviousNotifyCommand(existingNotify, pkgRoot),
+            omxNotify,
+            dispatcherNotify,
+        },
+    };
+}
+async function updateManagedConfig(configPath, hooksPath, pkgRoot, sharedMcpRegistry, mcpMode, scope, codexHomeDir, summary, backupContext, options) {
     const existing = existsSync(configPath)
         ? await readFile(configPath, "utf-8")
         : "";
@@ -2051,15 +2153,19 @@ async function updateManagedConfig(configPath, hooksPath, pkgRoot, sharedMcpRegi
             }
         }
     }
+    const notifyPlan = await buildNotifyMergePlan(existing, pkgRoot, codexHomeDir, scope);
     const finalConfig = buildMergedConfig(existing, pkgRoot, {
         includeTui: omxManagesTui,
         codexHooksFile: hooksPath,
+        codexHookFeatureFlag: options.codexHookFeatureFlag,
         modelOverride,
         sharedMcpServers: sharedMcpRegistry.servers,
         sharedMcpRegistrySource: sharedMcpRegistry.sourcePath,
         verbose: options.verbose,
         statusLinePreset: options.statusLinePreset,
         forceStatusLinePreset: options.forceStatusLinePreset,
+        notifyCommand: notifyPlan.notifyCommand,
+        includeFirstPartyMcp: mcpMode === "compat",
     });
     const changed = existing !== finalConfig;
     if (!changed) {
@@ -2075,6 +2181,10 @@ async function updateManagedConfig(configPath, hooksPath, pkgRoot, sharedMcpRegi
     }
     if (!options.dryRun) {
         await writeFile(configPath, finalConfig);
+        if (notifyPlan.metadataPath && notifyPlan.metadata) {
+            await mkdir(dirname(notifyPlan.metadataPath), { recursive: true });
+            await writeFile(notifyPlan.metadataPath, JSON.stringify(notifyPlan.metadata, null, 2) + "\n");
+        }
     }
     if (options.verbose &&
         modelOverride &&
@@ -2092,6 +2202,30 @@ async function updateManagedConfig(configPath, hooksPath, pkgRoot, sharedMcpRegi
         repairedLegacyTeamRunTable: hadLegacyTeamRunTable && !hasLegacyOmxTeamRunTable(finalConfig),
     };
 }
+async function syncSharedMcpRegistryIntoConfig(configPath, sharedMcpRegistry, summary, backupContext, options) {
+    if (sharedMcpRegistry.servers.length === 0) {
+        return existsSync(configPath) ? await readFile(configPath, "utf-8") : "";
+    }
+    const existing = existsSync(configPath)
+        ? await readFile(configPath, "utf-8")
+        : "";
+    const finalConfig = mergeSharedMcpRegistryBlock(existing, sharedMcpRegistry.servers, sharedMcpRegistry.sourcePath);
+    if (existing === finalConfig) {
+        summary.unchanged += 1;
+        return finalConfig;
+    }
+    if (await ensureBackup(configPath, existsSync(configPath), backupContext, options)) {
+        summary.backedUp += 1;
+    }
+    if (!options.dryRun) {
+        await writeFile(configPath, finalConfig);
+    }
+    summary.updated += 1;
+    if (options.verbose) {
+        console.log(`  ${options.dryRun ? "would sync" : "synced"} shared MCP registry servers into ${configPath}`);
+    }
+    return finalConfig;
+}
 function getClaudeCodeSettingsPath(homeDir = homedir()) {
     return join(homeDir, ".claude", "settings.json");
 }