@fitlab-ai/agent-infra 0.9.1 → 0.9.3

package/templates/.agents/skills/update-agent-infra/scripts/sync-templates.js

@@ -28,17 +28,35 @@ const DEFAULTS = {
   "platform": {
     "type": "github"
   },
+  "agentClients": [
+    {
+      "id": "claude-code",
+      "enabled": true,
+      "installInSandbox": true
+    },
+    {
+      "id": "codex",
+      "enabled": true,
+      "installInSandbox": true
+    },
+    {
+      "id": "antigravity-cli",
+      "enabled": true,
+      "installInSandbox": true
+    },
+    {
+      "id": "opencode",
+      "enabled": true,
+      "installInSandbox": true
+    }
+  ],
   "sandbox": {
     "engine": null,
     "runtimes": [
       "node22"
     ],
     "tools": [
-      "agent-infra",
-      "claude-code",
-      "codex",
-      "gemini-cli",
-      "opencode"
+      "agent-infra"
     ],
     "refreshIntervalDays": 7,
     "dockerfile": null,
@@ -65,16 +83,12 @@ const DEFAULTS = {
       ".agents/templates/",
       ".agents/workflows/",
       ".agents/workspace/README.md",
-      ".claude/commands/",
-      ".codex/hooks.json",
-      ".gemini/commands/",
       ".git-hooks/check-large-files.cjs",
       ".git-hooks/check-version-format.sh",
       ".github/scripts/",
       ".github/workflows/metadata-sync.yml",
       ".github/workflows/pr-label.yml",
-      ".github/workflows/status-label.yml",
-      ".opencode/commands/"
+      ".github/workflows/status-label.yml"
     ],
     "guardedManaged": [
       ".github/workflows/metadata-sync.yml",
@@ -93,8 +107,6 @@ const DEFAULTS = {
       ".agents/skills/test-integration/SKILL.*",
       ".agents/skills/test/SKILL.*",
       ".agents/skills/upgrade-dependency/SKILL.*",
-      ".claude/settings.json",
-      ".gemini/settings.json",
       ".git-hooks/pre-commit",
       ".gitignore"
     ],
@@ -102,64 +114,301 @@ const DEFAULTS = {
   }
 };
 
-const AGENT_INFRA_SANDBOX_TOOL = 'agent-infra';
-const LEGACY_DEFAULT_SANDBOX_TOOLS = ['claude-code', 'codex', 'gemini-cli', 'opencode'];
-const DEFAULT_SANDBOX_TOOLS = [AGENT_INFRA_SANDBOX_TOOL, ...LEGACY_DEFAULT_SANDBOX_TOOLS];
+const AGENT_CLIENT_MANIFEST = [
+  {
+    "id": "claude-code",
+    "displayName": "Claude Code",
+    "invocation": "/${skillName}",
+    "ownedPathPrefixes": [
+      ".claude/"
+    ],
+    "managed": [
+      ".claude/commands/",
+      ".claude/agents/"
+    ],
+    "merged": [
+      ".claude/settings.json"
+    ],
+    "ejected": []
+  },
+  {
+    "id": "codex",
+    "displayName": "Codex",
+    "invocation": "$${skillName}",
+    "ownedPathPrefixes": [
+      ".codex/"
+    ],
+    "managed": [
+      ".codex/hooks.json",
+      ".codex/agents/"
+    ],
+    "merged": [],
+    "ejected": []
+  },
+  {
+    "id": "antigravity-cli",
+    "displayName": "Antigravity CLI",
+    "invocation": "/${skillName}",
+    "ownedPathPrefixes": [],
+    "managed": [],
+    "merged": [],
+    "ejected": []
+  },
+  {
+    "id": "opencode",
+    "displayName": "OpenCode",
+    "invocation": "/${skillName}",
+    "ownedPathPrefixes": [
+      ".opencode/"
+    ],
+    "managed": [
+      ".opencode/commands/"
+    ],
+    "merged": [],
+    "ejected": []
+  }
+];
+const CUSTOM_TUI_CONTRACT = {
+  "requiredFields": [
+    "name",
+    "dir",
+    "invoke"
+  ],
+  "allowedPlaceholders": [
+    "skillName",
+    "projectName"
+  ]
+};
 // Add a new identifier here only after shipping matching .{platform}. template variants.
 const KNOWN_PLATFORMS = new Set(['github', 'none']);
 const KNOWN_LANGUAGES = new Set(['en', 'zh-CN']);
 
-// Single source of truth for built-in TUI ids and owned path prefixes.
-// Keep in sync with lib/builtin-tuis.ts (enforced by tests/unit/scripts/sync-templates-consts.test.ts).
-const BUILTIN_TUI_IDS = ['claude-code', 'codex', 'gemini-cli', 'opencode'];
-const BUILTIN_TUI_OWNED_PATH_PREFIXES = {
-  'claude-code': ['.claude/'],
-  'codex': ['.codex/'],
-  'gemini-cli': ['.gemini/'],
-  'opencode': ['.opencode/']
-};
-
-function resolveEnabledTUIs(value) {
-  // Missing field / null / non-array → full set (backward compat).
-  if (!Array.isArray(value)) return new Set(BUILTIN_TUI_IDS);
-  // Empty array is a meaningful user choice: no built-in TUI managed.
-  const set = new Set();
-  for (const v of value) {
-    if (typeof v === 'string' && BUILTIN_TUI_IDS.includes(v)) set.add(v);
+const BUILTIN_TUI_IDS = AGENT_CLIENT_MANIFEST.map((entry) => entry.id);
+
+function normalizeAgentClientConfig(cfg) {
+  const own = (value, key) => Object.prototype.hasOwnProperty.call(value, key);
+  const diagnostics = [];
+  const failure = (code, path) => ({
+    source: null,
+    state: null,
+    canonical: null,
+    remainingSandboxTools: undefined,
+    removeLegacyTuis: false,
+    changed: false,
+    diagnostics,
+    error: `${code} at ${path}`,
+    errorCode: code,
+    errorPath: path
+  });
+  const projectTuis = (value) => {
+    if (!Array.isArray(value)) {
+      return Object.fromEntries(BUILTIN_TUI_IDS.map((id) => [id, true]));
+    }
+    const enabled = new Set();
+    for (const [index, candidate] of value.entries()) {
+      if (BUILTIN_TUI_IDS.includes(candidate)) enabled.add(candidate);
+      else diagnostics.push({ code: 'LEGACY_VALUE_IGNORED', path: `tuis[${index}]` });
+    }
+    return Object.fromEntries(BUILTIN_TUI_IDS.map((id) => [id, enabled.has(id)]));
+  };
+  const projectSandbox = (value) => {
+    if (!Array.isArray(value) || value.length === 0) {
+      return {
+        installed: Object.fromEntries(BUILTIN_TUI_IDS.map((id) => [id, true])),
+        clientSignals: new Set(),
+        remainingTools: Array.isArray(value) ? [] : undefined
+      };
+    }
+    const installed = new Set();
+    const remainingTools = [];
+    for (const [index, candidate] of value.entries()) {
+      if (BUILTIN_TUI_IDS.includes(candidate)) installed.add(candidate);
+      else if (typeof candidate === 'string') remainingTools.push(candidate);
+      else diagnostics.push({ code: 'LEGACY_VALUE_IGNORED', path: `sandbox.tools[${index}]` });
+    }
+    return {
+      installed: Object.fromEntries(BUILTIN_TUI_IDS.map((id) => [id, installed.has(id)])),
+      clientSignals: installed,
+      remainingTools
+    };
+  };
+  const serialize = (state) => BUILTIN_TUI_IDS.map((id) => ({ id, ...state[id] }));
+  const hasCanonical = own(cfg, 'agentClients');
+  const hasLegacyTuis = own(cfg, 'tuis');
+  const sandbox = cfg.sandbox && typeof cfg.sandbox === 'object' && !Array.isArray(cfg.sandbox)
+    ? cfg.sandbox
+    : undefined;
+  const hasSandboxTools = sandbox !== undefined && own(sandbox, 'tools');
+  const tuiProjection = projectTuis(cfg.tuis);
+  const sandboxProjection = projectSandbox(sandbox?.tools);
+
+  if (!hasCanonical) {
+    const state = Object.fromEntries(BUILTIN_TUI_IDS.map((id) => [id, {
+      enabled: tuiProjection[id],
+      installInSandbox: sandboxProjection.installed[id]
+    }]));
+    return {
+      source: 'legacy',
+      state,
+      canonical: serialize(state),
+      remainingSandboxTools: sandboxProjection.remainingTools,
+      removeLegacyTuis: hasLegacyTuis,
+      changed: true,
+      diagnostics,
+      error: null,
+      errorCode: null,
+      errorPath: null
+    };
   }
-  return set;
-}
 
-function isPathOwnedByDisabledTUI(rel, enabledSet) {
-  const normalized = String(rel || '').replace(/\\/g, '/').replace(/^\.\//, '');
-  for (const tui of BUILTIN_TUI_IDS) {
-    if (enabledSet.has(tui)) continue;
-    for (const prefix of BUILTIN_TUI_OWNED_PATH_PREFIXES[tui]) {
-      const trimmed = prefix.replace(/\/$/, '');
-      if (normalized === trimmed || normalized.startsWith(prefix)) return true;
+  if (!Array.isArray(cfg.agentClients)) return failure('INVALID_AGENT_CLIENTS', 'agentClients');
+  const entries = new Map();
+  for (const [index, candidate] of cfg.agentClients.entries()) {
+    const entryPath = `agentClients[${index}]`;
+    if (typeof candidate !== 'object' || candidate === null || Array.isArray(candidate)) {
+      return failure('INVALID_AGENT_CLIENTS', entryPath);
+    }
+    const keys = Object.keys(candidate);
+    if (
+      (keys.length !== 3 && keys.length !== 4)
+      || !own(candidate, 'id')
+      || !own(candidate, 'enabled')
+      || !own(candidate, 'installInSandbox')
+      || (keys.length === 4 && !own(candidate, 'orchestration'))
+    ) {
+      return failure('INVALID_AGENT_CLIENTS', entryPath);
+    }
+    if (!BUILTIN_TUI_IDS.includes(candidate.id)) {
+      return failure('UNKNOWN_AGENT_CLIENT', `${entryPath}.id`);
+    }
+    if (entries.has(candidate.id)) return failure('DUPLICATE_AGENT_CLIENT', `${entryPath}.id`);
+    if (typeof candidate.enabled !== 'boolean' || typeof candidate.installInSandbox !== 'boolean') {
+      return failure('INVALID_AGENT_CLIENTS', entryPath);
     }
+    let orchestration;
+    if (own(candidate, 'orchestration')) {
+      const policy = candidate.orchestration;
+      const exact = (value) => typeof value === 'string' && value.length > 0 && value.trim() === value;
+      const validRole = (role) => role
+        && typeof role === 'object'
+        && !Array.isArray(role)
+        && Object.keys(role).length === 2
+        && exact(role.model)
+        && exact(role.reasoningEffort);
+      if (
+        !policy
+        || typeof policy !== 'object'
+        || Array.isArray(policy)
+        || Object.keys(policy).length !== 2
+        || !validRole(policy.executor)
+        || !validRole(policy.reviewer)
+      ) {
+        return failure('INVALID_AGENT_CLIENTS', `${entryPath}.orchestration`);
+      }
+      orchestration = structuredClone(policy);
+    }
+    entries.set(candidate.id, {
+      enabled: candidate.enabled,
+      installInSandbox: candidate.installInSandbox,
+      ...(orchestration ? { orchestration } : {})
+    });
   }
-  return false;
+  if (BUILTIN_TUI_IDS.some((id) => !entries.has(id))) {
+    return failure('MISSING_AGENT_CLIENT', 'agentClients');
+  }
+  const state = Object.fromEntries(BUILTIN_TUI_IDS.map((id) => [id, entries.get(id)]));
+  if (hasLegacyTuis && BUILTIN_TUI_IDS.some((id) => state[id].enabled !== tuiProjection[id])) {
+    return failure('LEGACY_CONFLICT', 'tuis');
+  }
+  if ([...sandboxProjection.clientSignals].some((id) => !state[id].installInSandbox)) {
+    return failure('LEGACY_CONFLICT', 'sandbox.tools');
+  }
+  const sameOrder = cfg.agentClients.every((entry, index) => entry.id === BUILTIN_TUI_IDS[index]);
+  return {
+    source: 'canonical',
+    state,
+    canonical: serialize(state),
+    remainingSandboxTools: hasSandboxTools ? sandboxProjection.remainingTools : undefined,
+    removeLegacyTuis: hasLegacyTuis,
+    changed: hasLegacyTuis || sandboxProjection.clientSignals.size > 0 || !sameOrder,
+    diagnostics,
+    error: null,
+    errorCode: null,
+    errorPath: null
+  };
 }
 
-function isLegacyDefaultSandboxTools(value) {
-  if (!Array.isArray(value) || value.length !== LEGACY_DEFAULT_SANDBOX_TOOLS.length) {
-    return false;
+function materializeAgentClientConfig(cfg, normalized) {
+  cfg.agentClients = normalized.canonical;
+  delete cfg.tuis;
+  if (normalized.remainingSandboxTools !== undefined) {
+    cfg.sandbox = {
+      ...(cfg.sandbox || {}),
+      tools: [
+        'agent-infra',
+        ...normalized.remainingSandboxTools.filter((tool) => tool !== 'agent-infra')
+      ]
+    };
   }
-  const tools = new Set(value);
-  return LEGACY_DEFAULT_SANDBOX_TOOLS.every(tool => tools.has(tool));
 }
 
-function migrateSandboxTools(cfg) {
-  const tools = cfg.sandbox?.tools;
-  if (!isLegacyDefaultSandboxTools(tools)) {
-    return false;
-  }
-  cfg.sandbox = {
-    ...cfg.sandbox,
-    tools: [...DEFAULT_SANDBOX_TOOLS]
+function assetMatches(entry, target) {
+  const normalizedEntry = norm(entry);
+  const normalizedTarget = norm(target);
+  return normalizedEntry.endsWith('/')
+    ? normalizedTarget.startsWith(normalizedEntry)
+    : normalizedTarget === normalizedEntry;
+}
+
+function adapterAssets(adapters, category) {
+  return adapters.flatMap((adapter) => adapter[category]);
+}
+
+function planProjectRegistry(current, sharedDefaults, enabledSet) {
+  const enabledAdapters = AGENT_CLIENT_MANIFEST.filter((adapter) => enabledSet.has(adapter.id));
+  const disabledAdapters = AGENT_CLIENT_MANIFEST.filter((adapter) => !enabledSet.has(adapter.id));
+  const allAdapterAssets = new Set(
+    AGENT_CLIENT_MANIFEST.flatMap((adapter) => [
+      ...adapter.managed,
+      ...adapter.merged,
+      ...adapter.ejected
+    ])
+  );
+  const enabled = {
+    managed: adapterAssets(enabledAdapters, 'managed'),
+    merged: adapterAssets(enabledAdapters, 'merged'),
+    ejected: adapterAssets(enabledAdapters, 'ejected')
+  };
+  const unique = (values) => [...new Set(values)];
+  const ejected = unique([
+    ...current.ejected,
+    ...enabled.ejected,
+    ...sharedDefaults.ejected
+  ]);
+  const ejectedSet = new Set(ejected);
+  const preserve = (values, enabledValues) => values.filter((entry) =>
+    !ejectedSet.has(entry)
+    && (!allAdapterAssets.has(entry) || enabledValues.includes(entry))
+  );
+  const managed = unique([
+    ...preserve(current.managed, enabled.managed),
+    ...enabled.managed.filter((entry) => !ejectedSet.has(entry)),
+    ...sharedDefaults.managed.filter((entry) => !ejectedSet.has(entry))
+  ]);
+  const managedSet = new Set(managed);
+  const merged = unique([
+    ...preserve(current.merged, enabled.merged),
+    ...enabled.merged.filter((entry) => !ejectedSet.has(entry) && !managedSet.has(entry)),
+    ...sharedDefaults.merged.filter((entry) => !ejectedSet.has(entry) && !managedSet.has(entry))
+  ]);
+
+  return {
+    registry: { managed, merged, ejected },
+    enabledManaged: enabled.managed,
+    enabledMerged: enabled.merged,
+    enabledEjected: enabled.ejected,
+    disabledManaged: adapterAssets(disabledAdapters, 'managed')
   };
-  return true;
 }
 
 function norm(p) { return p.replace(/\\/g, '/'); }
@@ -316,14 +565,13 @@ function detectCustomSkills(projectRoot, templateSkillNames) {
     .sort((left, right) => left.dirName.localeCompare(right.dirName));
 }
 
-function isCustomProtected(targetPath, customSkills, project, customTUICommandTargets) {
+function isCustomProtected(targetPath, customSkills, customTUICommandTargets) {
   const normalized = norm(targetPath);
 
   return customSkills.some(({ dirName }) => (
     normalized.startsWith(`.agents/skills/${dirName}/`) ||
     normalized === `.claude/commands/${dirName}.md` ||
     normalized === `.opencode/commands/${dirName}.md` ||
-    normalized === '.gemini/commands/' + project + '/' + dirName + '.toml' ||
     customTUICommandTargets.has(normalized)
   ));
 }
@@ -532,15 +780,6 @@ function formatYamlMetadata(key, value) {
   return [`${key}: |-`, ...value.split('\n').map((line) => `  ${line}`)];
 }
 
-function formatTomlMetadata(key, value) {
-  if (!value.includes('\n')) {
-    return `${key} = ${JSON.stringify(value)}`;
-  }
-
-  const lines = value.split('\n').map((line) => JSON.stringify(line).slice(1, -1));
-  return `${key} = """${lines.join('\n')}"""`;
-}
-
 function generateClaudeCommand(skill, lang) {
   const isZhCN = lang === 'zh-CN';
   const lines = ['---', ...formatYamlMetadata('description', skill.description)];
@@ -565,31 +804,6 @@ function generateClaudeCommand(skill, lang) {
   return `${lines.join('\n')}\n`;
 }
 
-function generateGeminiCommand(skill, lang) {
-  const isZhCN = lang === 'zh-CN';
-  const promptLines = [];
-
-  if (skill.args) {
-    promptLines.push(isZhCN ? '参数：{{args}}' : 'Arguments: {{args}}');
-    promptLines.push('');
-  }
-
-  promptLines.push(
-    isZhCN
-      ? `读取并执行 \`.agents/skills/${skill.dirName}/SKILL.md\` 中的 ${skill.dirName} 技能。`
-      : `Read and execute the ${skill.dirName} skill from \`.agents/skills/${skill.dirName}/SKILL.md\`.`
-  );
-  promptLines.push('');
-  promptLines.push(isZhCN ? '严格按照技能中定义的所有步骤执行。' : 'Follow all steps defined in the skill exactly.');
-
-  return [
-    formatTomlMetadata('description', skill.description),
-    'prompt = """',
-    ...promptLines,
-    '"""'
-  ].join('\n') + '\n';
-}
-
 function generateOpenCodeCommand(skill, lang) {
   const isZhCN = lang === 'zh-CN';
   const lines = [
@@ -618,9 +832,49 @@ function generateOpenCodeCommand(skill, lang) {
 }
 
 function validateCustomTUIs(projectRoot, customTUIs, report) {
-  const tools = Array.isArray(customTUIs) ? customTUIs : [];
+  if (customTUIs === undefined) return [];
+  if (!Array.isArray(customTUIs)) {
+    recordCustomTUISkipped(report, {
+      index: -1,
+      name: '',
+      dir: '',
+      reason: 'customTUIs must be an array'
+    });
+    return [];
+  }
+  const tools = customTUIs;
   return tools
     .map((tool, index) => {
+      if (
+        typeof tool !== 'object'
+        || tool === null
+        || Array.isArray(tool)
+      ) {
+        recordCustomTUISkipped(report, {
+          index,
+          name: '',
+          dir: '',
+          reason: 'invalid custom TUI'
+        });
+        return null;
+      }
+
+      for (const field of CUSTOM_TUI_CONTRACT.requiredFields) {
+        if (
+          typeof tool[field] !== 'string'
+          || tool[field].trim() === ''
+          || /[\r\n]/.test(tool[field])
+        ) {
+          recordCustomTUISkipped(report, {
+            index,
+            name: String(tool.name || ''),
+            dir: String(tool.dir || ''),
+            reason: `invalid ${field}`
+          });
+          return null;
+        }
+      }
+
       if (typeof tool?.dir !== 'string' || tool.dir.trim() === '') {
         recordCustomTUISkipped(report, {
           index,
@@ -631,6 +885,16 @@ function validateCustomTUIs(projectRoot, customTUIs, report) {
         return null;
       }
 
+      if (tool.dir.includes('\\')) {
+        recordCustomTUISkipped(report, {
+          index,
+          name: tool.name,
+          dir: tool.dir,
+          reason: 'dir must use POSIX separators'
+        });
+        return null;
+      }
+
       if (!isInsideProject(projectRoot, tool.dir)) {
         recordCustomTUISkipped(report, {
           index,
@@ -641,6 +905,27 @@ function validateCustomTUIs(projectRoot, customTUIs, report) {
         return null;
       }
 
+      const placeholders = [...tool.invoke.matchAll(/\$\{([^}]+)\}/g)]
+        .map((match) => match[1]);
+      if (
+        !placeholders.includes('skillName')
+        || placeholders.some((placeholder) =>
+          !CUSTOM_TUI_CONTRACT.allowedPlaceholders.includes(placeholder)
+        )
+        || tool.invoke
+          .replaceAll('${skillName}', '')
+          .replaceAll('${projectName}', '')
+          .includes('${')
+      ) {
+        recordCustomTUISkipped(report, {
+          index,
+          name: tool.name,
+          dir: tool.dir,
+          reason: 'invalid invoke placeholders'
+        });
+        return null;
+      }
+
       return { ...tool, index, dir: normDir(tool.dir) };
     })
     .filter(Boolean);
@@ -764,27 +1049,26 @@ function learnAndGenerateCommands(projectRoot, customSkills, tool, templateSkill
   }
 }
 
-function generateCustomCommands(projectRoot, customSkills, project, lang, report, customTUIs, templateSkillNames, enabledTUIs) {
+function generateCustomCommands(
+  projectRoot,
+  customSkills,
+  lang,
+  report,
+  customTUIs,
+  templateSkillNames,
+  enabledTUIs,
+  managedWriter
+) {
   for (const skill of customSkills) {
     if (enabledTUIs.has('claude-code')) {
-      writeIfChanged(
-        projectRoot,
+      managedWriter(
         `.claude/commands/${skill.dirName}.md`,
         generateClaudeCommand(skill, lang),
         report.custom.commands
       );
     }
-    if (enabledTUIs.has('gemini-cli')) {
-      writeIfChanged(
-        projectRoot,
-        '.gemini/commands/' + project + '/' + skill.dirName + '.toml',
-        generateGeminiCommand(skill, lang),
-        report.custom.commands
-      );
-    }
     if (enabledTUIs.has('opencode')) {
-      writeIfChanged(
-        projectRoot,
+      managedWriter(
         `.opencode/commands/${skill.dirName}.md`,
         generateOpenCodeCommand(skill, lang),
         report.custom.commands
@@ -935,7 +1219,8 @@ function syncTemplates(projectRoot, templateRootOverride) {
     return { error: 'No .agents/.airc.json in project root.' };
   }
 
-  const cfg = JSON.parse(fs.readFileSync(cfgPath, 'utf8'));
+  const originalConfigText = fs.readFileSync(cfgPath, 'utf8');
+  const cfg = JSON.parse(originalConfigText);
   const configPathRel = norm(path.relative(projectRoot, cfgPath));
   let templateRoot = templateRootOverride;
   if (!templateRoot) {
@@ -951,20 +1236,43 @@ function syncTemplates(projectRoot, templateRootOverride) {
     }
   }
   const version = resolveVersionFromTemplateRoot(templateRoot);
-  const hadTemplateSource = Object.prototype.hasOwnProperty.call(cfg, 'templateSource');
 
   const { project, org, language: lang = 'en' } = cfg;
   const platformType = cfg.platform?.type || DEFAULTS.platform.type;
-  const enabledTUIs = resolveEnabledTUIs(cfg.tuis);
+  const enabledResolution = normalizeAgentClientConfig(cfg);
+  if (enabledResolution.error) {
+    return { error: enabledResolution.error };
+  }
+  const enabledTUIs = new Set(
+    BUILTIN_TUI_IDS.filter((id) => enabledResolution.state[id].enabled)
+  );
+  materializeAgentClientConfig(cfg, enabledResolution);
   const customTUIsConfig = Array.isArray(cfg.customTUIs) ? cfg.customTUIs : [];
   const vars = { project, org };
   const templateSkillNames = listTemplateSkillNames(templateRoot);
   const protectedCustomSkills = detectCustomSkills(projectRoot, templateSkillNames);
 
-  const managed = [...(cfg.files.managed || [])];
-  const merged  = [...(cfg.files.merged  || [])];
-  const ejected = [...(cfg.files.ejected || [])];
+  cfg.files ||= {};
+  const currentRegistry = {
+    managed: [...(cfg.files.managed || [])],
+    merged: [...(cfg.files.merged || [])],
+    ejected: [...(cfg.files.ejected || [])]
+  };
+  const sharedDefaults = {
+    managed: (DEFAULTS.files.managed || []).filter(
+      (entry) => !isPathOwnedByOtherPlatform(entry, platformType)
+    ),
+    merged: (DEFAULTS.files.merged || []).filter(
+      (entry) => !isPathOwnedByOtherPlatform(entry, platformType)
+    ),
+    ejected: [...(DEFAULTS.files.ejected || [])]
+  };
+  const assetPlan = planProjectRegistry(currentRegistry, sharedDefaults, enabledTUIs);
+  const managed = [...assetPlan.registry.managed];
+  const merged = [...assetPlan.registry.merged];
+  const ejected = [...assetPlan.registry.ejected];
   const guardedManaged = new Set((DEFAULTS.files.guardedManaged || []).map(norm));
+  const allClientManaged = adapterAssets(AGENT_CLIENT_MANIFEST, 'managed');
   const managedBaselines = cfg.files.managedBaselines && typeof cfg.files.managedBaselines === 'object'
     && !Array.isArray(cfg.files.managedBaselines)
     ? { ...cfg.files.managedBaselines }
@@ -972,7 +1280,10 @@ function syncTemplates(projectRoot, templateRootOverride) {
   let baselinesChanged = false;
 
   for (const target of Object.keys(managedBaselines)) {
-    if (!guardedManaged.has(norm(target))) {
+    if (
+      !guardedManaged.has(norm(target))
+      && !allClientManaged.some((entry) => assetMatches(entry, target))
+    ) {
       delete managedBaselines[target];
       baselinesChanged = true;
     }
@@ -982,6 +1293,7 @@ function syncTemplates(projectRoot, templateRootOverride) {
     templateVersion: version,
     templateRoot: norm(templateRoot),
     registryAdded: [],
+    registryRemoved: [],
     templateSources: {
       configured: 0,
       loaded: 0,
@@ -1022,17 +1334,23 @@ function syncTemplates(projectRoot, templateRootOverride) {
     templateSkillNames
   );
 
-  const known = new Set([...managed, ...merged, ...ejected]);
-  for (const e of (DEFAULTS.files.managed || [])) {
-    if (isPathOwnedByOtherPlatform(e, platformType)) continue;
-    if (isPathOwnedByDisabledTUI(e, enabledTUIs)) continue;
-    if (!known.has(e)) { managed.push(e); known.add(e); report.registryAdded.push({ entry: e, list: 'managed' }); }
-  }
-  for (const e of (DEFAULTS.files.merged || [])) {
-    if (isPathOwnedByOtherPlatform(e, platformType)) continue;
-    if (isPathOwnedByDisabledTUI(e, enabledTUIs)) continue;
-    if (!known.has(e)) { merged.push(e); known.add(e); report.registryAdded.push({ entry: e, list: 'merged' }); }
+  for (const category of ['managed', 'merged', 'ejected']) {
+    const before = currentRegistry[category];
+    const after = assetPlan.registry[category];
+    for (const entry of after) {
+      if (!before.includes(entry)) report.registryAdded.push({ entry, list: category });
+    }
+    for (const entry of before) {
+      if (!after.includes(entry)) report.registryRemoved.push({ entry, list: category });
+    }
   }
+  report.managed.skippedTUI.push(
+    ...assetPlan.disabledManaged,
+    ...adapterAssets(
+      AGENT_CLIENT_MANIFEST.filter((adapter) => !enabledTUIs.has(adapter.id)),
+      'merged'
+    )
+  );
 
   const templateSources = Array.isArray(cfg.templates?.sources) ? cfg.templates.sources : [];
   report.templateSources.configured = templateSources.length;
@@ -1056,6 +1374,97 @@ function syncTemplates(projectRoot, templateRootOverride) {
       : renderContent(fs.readFileSync(srcFull, 'utf8'), vars);
   }
 
+  function selectedTargetsForEntry(entry) {
+    let entryRels;
+    if (entry.endsWith('/')) {
+      const builtinDir = path.join(templateRoot, entry);
+      const builtinRels = fs.existsSync(builtinDir)
+        ? walkDir(builtinDir).map((filePath) => norm(path.relative(templateRoot, filePath)))
+        : [];
+      const prefix = norm(entry);
+      const externalRels = allRels.filter((rel) =>
+        rel.startsWith(prefix) && !builtinRels.includes(rel)
+      );
+      entryRels = [...builtinRels, ...externalRels];
+    } else {
+      entryRels = entryVariantRels(entry, allSet, platformType);
+    }
+    return platformSelect(
+      langSelect(entryRels, lang, allSet, project),
+      platformType,
+      project
+    );
+  }
+
+  function writeProtectedManaged(target, content, bucket) {
+    const dstFull = path.join(projectRoot, target);
+    const exists = fs.existsSync(dstFull);
+    const rawBaseline = managedBaselines[target];
+    const baseline = trustedBaseline(rawBaseline);
+    const templateHash = sha256(content);
+    const localHash = exists ? sha256(fs.readFileSync(dstFull)) : null;
+
+    if (rawBaseline !== undefined && baseline === null) {
+      delete managedBaselines[target];
+      baselinesChanged = true;
+    }
+    if (baseline === null && localHash !== null && localHash !== templateHash) {
+      report.managed.conflicts.push({
+        target,
+        reason: 'unknown-origin',
+        baseline: null,
+        local: localHash,
+        template: templateHash
+      });
+      return false;
+    }
+    if (baseline !== null && templateHash === baseline && localHash !== baseline) {
+      report.managed.protected.push({
+        target,
+        reason: localHash === null ? 'user-deleted' : 'user-modified',
+        baseline,
+        local: localHash,
+        template: templateHash
+      });
+      return false;
+    }
+    if (
+      baseline !== null
+      && localHash !== baseline
+      && templateHash !== baseline
+      && localHash !== templateHash
+    ) {
+      report.managed.conflicts.push({
+        target,
+        reason: 'both-modified',
+        baseline,
+        local: localHash,
+        template: templateHash
+      });
+      return false;
+    }
+    if (localHash === templateHash) {
+      bucket.unchanged.push(target);
+      if (managedBaselines[target] !== templateHash) {
+        managedBaselines[target] = templateHash;
+        baselinesChanged = true;
+      }
+      return false;
+    }
+
+    const dir = path.dirname(dstFull);
+    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(dstFull, content);
+    managedBaselines[target] = templateHash;
+    baselinesChanged = true;
+    if (Object.prototype.hasOwnProperty.call(bucket, 'written')) {
+      (exists ? bucket.written : bucket.created).push(target);
+    } else {
+      (exists ? bucket.updated : bucket.generated).push(target);
+    }
+    return true;
+  }
+
   for (const entry of [...managed, ...merged, ...ejected]) {
     if (!isPathOwnedByOtherPlatform(entry, platformType)) continue;
 
@@ -1109,39 +1518,81 @@ function syncTemplates(projectRoot, templateRootOverride) {
     }
   }
 
-  // Cleanup files owned by disabled built-in TUIs. Iterates managed + merged
-  // only (ejected entries are explicitly user-retained, see ejected loop below).
-  //
-  // Protection rule: only skip files registered as customTUI command targets
-  // (e.g. a customTUI configured with dir=.codex/commands/ when codex is
-  // disabled). Built-in TUI custom-skill commands like
-  // .gemini/commands/<project>/<dirName>.toml are intentionally NOT protected
-  // here so that disabling gemini-cli actually frees the gemini directory —
-  // they will be regenerated only for still-enabled TUIs (see
-  // generateCustomCommands).
-  for (const entry of [...managed, ...merged]) {
-    if (!isPathOwnedByDisabledTUI(entry, enabledTUIs)) continue;
-
-    if (entry.endsWith('/')) {
-      const dir = path.join(projectRoot, entry);
-      if (!fs.existsSync(dir)) continue;
-
-      for (const filePath of walkDir(dir)) {
-        const relProj = norm(path.relative(projectRoot, filePath));
-        if (customTUICommandTargets.has(relProj)) continue;
-        fs.unlinkSync(filePath);
-        report.managed.removed.push(relProj);
+  // Disabled clients are converged conservatively: only exact manifest
+  // managed targets or previously baselined generated targets are candidates.
+  // Merged/ejected and content without trustworthy origin evidence are kept.
+  for (const entry of assetPlan.disabledManaged) {
+    const selectedTargets = selectedTargetsForEntry(entry);
+    const candidates = new Set(
+      Object.keys(managedBaselines).filter((target) => assetMatches(entry, target))
+    );
+    for (const target of selectedTargets.keys()) candidates.add(target);
+
+    for (const target of candidates) {
+      const dstFull = path.join(projectRoot, target);
+      const baseline = trustedBaseline(managedBaselines[target]);
+      const selectedSource = selectedTargets.get(target);
+      const sourceRoot = selectedSource ? (sourceMap.get(selectedSource) || templateRoot) : null;
+      const templateContent = selectedSource && sourceRoot === templateRoot
+        ? (
+            isBinary(path.join(sourceRoot, selectedSource))
+              ? fs.readFileSync(path.join(sourceRoot, selectedSource))
+              : renderContent(fs.readFileSync(path.join(sourceRoot, selectedSource), 'utf8'), vars)
+          )
+        : null;
+      const localHash = fs.existsSync(dstFull) ? sha256(fs.readFileSync(dstFull)) : null;
+      const templateHash = templateContent === null ? null : sha256(templateContent);
+      const protectedByEjection = ejected.some((pattern) =>
+        assetMatches(pattern, target) || globMatch(pattern, target)
+      );
+      const protectedByCustom = customTUICommandTargets.has(target);
+
+      if (protectedByEjection || protectedByCustom || (sourceRoot && sourceRoot !== templateRoot)) {
+        report.managed.protected.push({
+          target,
+          reason: protectedByEjection
+            ? 'ejected'
+            : protectedByCustom
+              ? 'custom'
+              : 'external-source',
+          baseline,
+          local: localHash,
+          template: templateHash
+        });
+        continue;
       }
-      removeEmptyDirs(dir);
-      continue;
+      if (localHash === null) {
+        if (Object.prototype.hasOwnProperty.call(managedBaselines, target)) {
+          delete managedBaselines[target];
+          baselinesChanged = true;
+        }
+        continue;
+      }
+      const legacyManaged = currentRegistry.managed.includes(entry);
+      if (
+        (baseline !== null && localHash === baseline)
+        || (baseline === null && legacyManaged && templateHash !== null && localHash === templateHash)
+      ) {
+        fs.unlinkSync(dstFull);
+        report.managed.removed.push(target);
+        if (Object.prototype.hasOwnProperty.call(managedBaselines, target)) {
+          delete managedBaselines[target];
+          baselinesChanged = true;
+        }
+        removeEmptyDirs(path.dirname(dstFull));
+        continue;
+      }
+      report.managed.protected.push({
+        target,
+        reason: baseline === null ? 'unknown-origin' : 'user-modified',
+        baseline,
+        local: localHash,
+        template: templateHash
+      });
+    }
+    if (entry.endsWith('/')) {
+      removeEmptyDirs(path.join(projectRoot, entry));
     }
-
-    const target = path.join(projectRoot, renderPathname(entry, project));
-    if (!fs.existsSync(target)) continue;
-    const relProj = norm(path.relative(projectRoot, target));
-    if (customTUICommandTargets.has(relProj)) continue;
-    fs.unlinkSync(target);
-    report.managed.removed.push(relProj);
   }
 
   for (const entry of managed) {
@@ -1149,11 +1600,6 @@ function syncTemplates(projectRoot, templateRootOverride) {
       report.managed.skippedPlatform.push(entry);
       continue;
     }
-    if (isPathOwnedByDisabledTUI(entry, enabledTUIs)) {
-      report.managed.skippedTUI.push(entry);
-      continue;
-    }
-
     const isDir = entry.endsWith('/');
     let entryRels;
     const expectedTargets = isDir ? new Set() : null;
@@ -1191,65 +1637,14 @@ function syncTemplates(projectRoot, templateRootOverride) {
         : renderContent(fs.readFileSync(srcFull, 'utf8'), vars);
 
       const exists = fs.existsSync(dstFull);
-      if (guardedManaged.has(tgt)) {
-        const rawBaseline = managedBaselines[tgt];
-        const baseline = trustedBaseline(rawBaseline);
-        const templateHash = sha256(content);
-        const localHash = exists ? sha256(fs.readFileSync(dstFull)) : null;
-
-        if (rawBaseline !== undefined && baseline === null) {
-          delete managedBaselines[tgt];
-          baselinesChanged = true;
-        }
-
-        if (baseline === null && localHash !== null && localHash !== templateHash) {
-          report.managed.conflicts.push({
-            target: tgt,
-            reason: 'unknown-origin',
-            baseline: null,
-            local: localHash,
-            template: templateHash
-          });
-          continue;
-        }
-
-        if (baseline !== null && templateHash === baseline && localHash !== baseline) {
-          report.managed.protected.push({
-            target: tgt,
-            reason: localHash === null ? 'user-deleted' : 'user-modified',
-            baseline,
-            local: localHash,
-            template: templateHash
-          });
-          continue;
-        }
-
-        if (baseline !== null && localHash !== baseline && templateHash !== baseline && localHash !== templateHash) {
-          report.managed.conflicts.push({
-            target: tgt,
-            reason: 'both-modified',
-            baseline,
-            local: localHash,
-            template: templateHash
-          });
-          continue;
-        }
-
-        if (localHash === templateHash) {
-          report.managed.unchanged.push(tgt);
-          if (managedBaselines[tgt] !== templateHash) {
-            managedBaselines[tgt] = templateHash;
-            baselinesChanged = true;
-          }
-          continue;
+      const clientManagedTarget = assetPlan.enabledManaged.some((asset) =>
+        assetMatches(asset, tgt)
+      );
+      if (guardedManaged.has(tgt) || (clientManagedTarget && srcRoot === templateRoot)) {
+        const written = writeProtectedManaged(tgt, content, report.managed);
+        if (written && tgt.endsWith('.sh')) {
+          try { fs.chmodSync(dstFull, 0o755); } catch { /* Windows */ }
         }
-
-        const dir = path.dirname(dstFull);
-        if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
-        fs.writeFileSync(dstFull, content);
-        managedBaselines[tgt] = templateHash;
-        baselinesChanged = true;
-        (exists ? report.managed.written : report.managed.created).push(tgt);
         continue;
       }
 
@@ -1279,9 +1674,27 @@ function syncTemplates(projectRoot, templateRootOverride) {
         for (const projFile of projFiles) {
           if (expectedTargets.has(projFile)) continue;
           if (projFile === configPathRel) continue;
-          if (isCustomProtected(projFile, protectedCustomSkills, project, customTUICommandTargets)) continue;
+          if (isCustomProtected(projFile, protectedCustomSkills, customTUICommandTargets)) continue;
           if (matchesAny(projFile, merged) || matchesAny(projFile, ejected)) continue;
-
+          if (assetPlan.enabledManaged.includes(entry)) {
+            const baseline = trustedBaseline(managedBaselines[projFile]);
+            const localHash = sha256(fs.readFileSync(path.join(projectRoot, projFile)));
+            if (baseline !== null && localHash === baseline) {
+              fs.unlinkSync(path.join(projectRoot, projFile));
+              delete managedBaselines[projFile];
+              baselinesChanged = true;
+              report.managed.removed.push(projFile);
+            } else {
+              report.managed.protected.push({
+                target: projFile,
+                reason: baseline === null ? 'unknown-origin' : 'user-modified',
+                baseline,
+                local: localHash,
+                template: null
+              });
+            }
+            continue;
+          }
           fs.unlinkSync(path.join(projectRoot, projFile));
           report.managed.removed.push(projFile);
         }
@@ -1300,7 +1713,16 @@ function syncTemplates(projectRoot, templateRootOverride) {
 
   const customSkills = detectCustomSkills(projectRoot, templateSkillNames);
   report.custom.detected = customSkills.map((skill) => skill.dirName);
-  generateCustomCommands(projectRoot, customSkills, project, lang, report, customTUIs, templateSkillNames, enabledTUIs);
+  generateCustomCommands(
+    projectRoot,
+    customSkills,
+    lang,
+    report,
+    customTUIs,
+    templateSkillNames,
+    enabledTUIs,
+    writeProtectedManaged
+  );
 
   for (const entry of ejected) {
     const dstFull = path.join(projectRoot, entry);
@@ -1310,7 +1732,11 @@ function syncTemplates(projectRoot, templateRootOverride) {
     }
     // Do not (re)create ejected files for disabled TUIs. Existing files are
     // never touched by sync (handled above); this guard only blocks creation.
-    if (isPathOwnedByDisabledTUI(entry, enabledTUIs)) continue;
+    const disabledEjected = AGENT_CLIENT_MANIFEST.some((adapter) =>
+      !enabledTUIs.has(adapter.id)
+      && adapter.ejected.some((asset) => assetMatches(asset, entry))
+    );
+    if (disabledEjected) continue;
 
     const selected = platformSelect(langSelect(entryVariantRels(entry, allSet, platformType), lang, allSet, project), platformType, project);
     const target = norm(renderPathname(entry, project));
@@ -1331,11 +1757,6 @@ function syncTemplates(projectRoot, templateRootOverride) {
       report.managed.skippedPlatform.push(entry);
       continue;
     }
-    if (isPathOwnedByDisabledTUI(entry, enabledTUIs)) {
-      report.managed.skippedTUI.push(entry);
-      continue;
-    }
-
     if (entry.includes('*')) {
       const hits = allRels.filter(r => {
         const t = norm(renderPathname(stripLangVariant(r), project));
@@ -1356,22 +1777,6 @@ function syncTemplates(projectRoot, templateRootOverride) {
     ([target, template]) => ({ target, template })
   );
 
-  const hasChanges = (
-    report.managed.written.length +
-    report.managed.created.length +
-    report.managed.removed.length +
-    report.custom.generated.length +
-    report.custom.updated.length +
-    report.custom.removed.length +
-    report.custom.commands.generated.length +
-    report.custom.commands.updated.length +
-    report.ejected.created.length +
-    report.registryAdded.length
-  ) > 0;
-
-  const prevVersion = cfg.templateVersion;
-  const sandboxToolsMigrated = migrateSandboxTools(cfg);
-
   cfg.files.managed = managed;
   cfg.files.merged  = merged;
   cfg.files.ejected = ejected;
@@ -1384,9 +1789,22 @@ function syncTemplates(projectRoot, templateRootOverride) {
   cfg.templateVersion = version;
   delete cfg.templateSource;
 
-  report.configUpdated = hasChanges || baselinesChanged || prevVersion !== version || hadTemplateSource || sandboxToolsMigrated;
-
-  fs.writeFileSync(cfgPath, JSON.stringify(cfg, null, 2) + '\n', 'utf8');
+  const nextConfigText = JSON.stringify(cfg, null, 2) + '\n';
+  report.configUpdated = originalConfigText !== nextConfigText;
+  if (report.configUpdated) {
+    const temporary = `${cfgPath}.tmp-${process.pid}-${Date.now()}`;
+    try {
+      fs.writeFileSync(temporary, nextConfigText, 'utf8');
+      fs.renameSync(temporary, cfgPath);
+    } catch (error) {
+      try {
+        if (fs.existsSync(temporary)) fs.unlinkSync(temporary);
+      } catch {
+        // Preserve the original write/rename failure.
+      }
+      throw error;
+    }
+  }
 
   return report;
 }
@@ -1399,4 +1817,4 @@ if (entryPath === fileURLToPath(import.meta.url)) {
   if (result.error) process.exitCode = 1;
 }
 
-export { syncTemplates };
+export { normalizeAgentClientConfig, syncTemplates };