sinapse-ai 1.23.0 → 1.25.0

package/bin/commands/install.js

@@ -36,7 +36,11 @@ const {
   warnNonInteractive,
 } = require('../lib/detection');
 const { promptLlmChoice } = require('../lib/prompts');
-const { recordInstalledAgents } = require('./uninstall');
+const {
+  recordInstalledAgents,
+  reconcileInstalledAgents,
+  removeManagedGlobalSkills,
+} = require('./uninstall');
 const { verifyInstall } = require('./status');
 // generateCommandMd is re-exported below for backward-compat (update.js imports it
 // from ./install). regenerateAgentCommands is the shared Phase 2 helper.
@@ -44,6 +48,7 @@ const {
   generateCommandMd,
   regenerateAgentCommands,
 } = require('../lib/command-generator');
+const { deliverGlobalProviderAdapters, getGlobalCommandStagingDir } = require('../lib/global-provider-adapters');
 // Follow-up #13 — wire the transactional backup/rollback engine into the
 // installer so an in-place UPGRADE (upsert) that fails mid-flight is restored
 // to its previous state instead of leaving ~/.sinapse half-updated.
@@ -300,19 +305,10 @@ async function cmdInstallGlobal(opts = {}) {
   // greeting on @sinapse/@snps/-orqx). Re-copy the generated command files LAST so the
   // rich, frontmatter'd stubs are always the final word. Idempotent.
   try {
-    const reTargets = [];
-    if (llmChoice === 'claude-code' || llmChoice === 'both') reTargets.push(path.join(HOME, '.claude', 'agents'));
-    if (llmChoice === 'codex' || llmChoice === 'both') reTargets.push(path.join(HOME, '.codex', 'agents'));
-    if (reTargets.length && fs.existsSync(CLAUDE_COMMANDS_DIR)) {
-      const cmdFiles = fs.readdirSync(CLAUDE_COMMANDS_DIR).filter(f => f.endsWith('.md'));
-      for (const dir of reTargets) {
-        fs.mkdirSync(dir, { recursive: true });
-        for (const f of cmdFiles) {
-          fs.copyFileSync(path.join(CLAUDE_COMMANDS_DIR, f), path.join(dir, f));
-        }
-      }
-      logger.always(`  ${GREEN}OK${NC} Global agents reconciled (${cmdFiles.length} files — rich stubs authoritative)`);
-    }
+    const commandsDir = getGlobalCommandStagingDir({ llmChoice, sinapseHome: SINAPSE_HOME, claudeCommandsDir: CLAUDE_COMMANDS_DIR });
+    const reconciled = deliverGlobalProviderAdapters({ llmChoice, home: HOME, commandsDir });
+    const total = reconciled.claude.length + reconciled.codex.length + reconciled.skills.length;
+    if (total) logger.always(`  ${GREEN}OK${NC} Global provider adapters reconciled (${total} artifacts)`);
   } catch (e) {
     logger.always(`  ${YELLOW}WARN${NC} Global agent reconciliation: ${e.message}`);
   }
@@ -324,9 +320,14 @@ async function cmdInstallGlobal(opts = {}) {
   // printed above: if any check failed (✗), show a warning banner instead of an
   // unconditional success banner. The exit code is intentionally left unchanged —
   // this only changes the message, not the process result.
+  const verificationCommandsDir = getGlobalCommandStagingDir({
+    llmChoice,
+    sinapseHome: SINAPSE_HOME,
+    claudeCommandsDir: CLAUDE_COMMANDS_DIR,
+  });
   const installVerified =
     fs.existsSync(SINAPSE_HOME) &&
-    fs.existsSync(CLAUDE_COMMANDS_DIR) &&
+    fs.existsSync(verificationCommandsDir) &&
     fs.existsSync(path.join(BIN_DIR, 'sinapse')) &&
     fs.existsSync(path.join(SINAPSE_HOME, '.claude', 'rules', 'squad-awareness.md'));
 
@@ -351,8 +352,13 @@ async function cmdInstallGlobal(opts = {}) {
   logger.always(`  ${startCmd}`);
   logger.always('');
   logger.always(`  ${BOLD}Try an agent:${NC}`);
-  logger.always(`    ${CYAN}/SINAPSE:agents:sinapse-orqx${NC}`);
-  logger.always(`    ${CYAN}/SINAPSE:agents:brand-orqx${NC}`);
+  if (llmChoice === 'codex') {
+    logger.always(`    ${CYAN}$snps${NC}`);
+    logger.always(`    ${CYAN}$sinapse-agent brand-orqx${NC}`);
+  } else {
+    logger.always(`    ${CYAN}@sinapse-orqx${NC}`);
+    logger.always(`    ${CYAN}@brand-orqx${NC}`);
+  }
   logger.always('');
 }
 
@@ -396,7 +402,10 @@ function buildTransactionPaths(llmChoice) {
     CLAUDE_COMMANDS_DIR,   // Phase 2 — generated /SINAPSE:agents:* command files
   ];
   if (llmChoice === 'claude-code' || llmChoice === 'both') dirs.push(path.join(HOME, '.claude', 'agents'));
-  if (llmChoice === 'codex' || llmChoice === 'both') dirs.push(path.join(HOME, '.codex', 'agents'));
+  if (llmChoice === 'codex' || llmChoice === 'both') {
+    dirs.push(path.join(HOME, '.codex', 'agents'));
+    dirs.push(path.join(HOME, '.agents', 'skills'));
+  }
   dirs.push(BIN_DIR);      // Phase 4 — launcher(s)
 
   const files = [path.join(HOME, '.claude', 'settings.json')]; // language save
@@ -520,43 +529,49 @@ function installFatalPhases({ squads, squadsDir, isUpsert, llmChoice, existing,
     logger.always(`  ${GREEN}OK${NC} sinapse (master, ${masterAgents} agents)`);
   }
 
+  const coreDevelopmentSrc = path.join(ROOT, '.sinapse-ai', 'development');
+  const coreDevelopmentDest = path.join(SINAPSE_HOME, 'core');
+  if (fs.existsSync(coreDevelopmentSrc)) {
+    if (isUpsert) {
+      const delta = syncDirSync(coreDevelopmentSrc, coreDevelopmentDest);
+      totalDelta.added += delta.added;
+      totalDelta.updated += delta.updated;
+      totalDelta.unchanged += delta.unchanged;
+      totalDelta.removed += delta.removed;
+    } else {
+      rmDirSync(coreDevelopmentDest);
+      copyDirSync(coreDevelopmentSrc, coreDevelopmentDest);
+    }
+    const coreAgents = getAgentFiles(coreDevelopmentDest).length;
+    totalAgents += coreAgents;
+    logger.always(`  ${GREEN}OK${NC} core development (${coreAgents} agents)`);
+  }
+
   // Phase 2: Generate agent commands (shared with `update` via command-generator).
   logger.always(`\n${CYAN}Phase 2:${NC} Generating agent commands`);
+  const commandStagingDir = getGlobalCommandStagingDir({ llmChoice, sinapseHome: SINAPSE_HOME, claudeCommandsDir: CLAUDE_COMMANDS_DIR });
   const { writtenAgents } = regenerateAgentCommands({
     sinapseHome: SINAPSE_HOME,
-    commandsDir: CLAUDE_COMMANDS_DIR,
+    commandsDir: commandStagingDir,
     squads,
     sinapseMasterDest,
+    coreDevelopmentDest,
   });
   logger.always(`  ${GREEN}OK${NC} ${writtenAgents.size} total command files`);
 
   // Phase 2b: Install global agents based on LLM choice
-  const installedAgentFilenames = new Set();
+  const globalAdapters = deliverGlobalProviderAdapters({ llmChoice, home: HOME, commandsDir: commandStagingDir });
+  const installedAgentFilenames = new Set([...globalAdapters.claude, ...globalAdapters.codex]);
   const installedIdes = [];
-  if (llmChoice === 'claude-code' || llmChoice === 'both') {
-    const globalAgentsDir = path.join(HOME, '.claude', 'agents');
-    fs.mkdirSync(globalAgentsDir, { recursive: true });
-    for (const f of fs.readdirSync(CLAUDE_COMMANDS_DIR).filter(f => f.endsWith('.md'))) {
-      fs.copyFileSync(path.join(CLAUDE_COMMANDS_DIR, f), path.join(globalAgentsDir, f));
-      installedAgentFilenames.add(f);
-    }
-    installedIdes.push('claude-code');
-    logger.always(`  ${GREEN}OK${NC} Claude Code global agents (${writtenAgents.size})`);
-  }
-
-  if (llmChoice === 'codex' || llmChoice === 'both') {
-    const codexAgentsDir = path.join(HOME, '.codex', 'agents');
-    fs.mkdirSync(codexAgentsDir, { recursive: true });
-    for (const f of fs.readdirSync(CLAUDE_COMMANDS_DIR).filter(f => f.endsWith('.md'))) {
-      fs.copyFileSync(path.join(CLAUDE_COMMANDS_DIR, f), path.join(codexAgentsDir, f));
-      installedAgentFilenames.add(f);
-    }
-    installedIdes.push('codex');
-    logger.always(`  ${GREEN}OK${NC} Codex global agents (${writtenAgents.size})`);
-  }
+  if (globalAdapters.claude.length) installedIdes.push('claude-code');
+  if (globalAdapters.codex.length) installedIdes.push('codex');
+  if (globalAdapters.claude.length) logger.always(`  ${GREEN}OK${NC} Claude Code global agents (${globalAdapters.claude.length})`);
+  if (globalAdapters.codex.length) logger.always(`  ${GREEN}OK${NC} Codex global agents (${globalAdapters.codex.length} TOML, ${globalAdapters.skills.length} skills)`);
 
   // Audit 1 P0 (UN-1) — record manifest so uninstall can remove every file
   // we wrote (not just `*-orqx.md`). Idempotent: re-install overwrites.
+  reconcileInstalledAgents(HOME, installedAgentFilenames);
+  if (llmChoice === 'claude-code') removeManagedGlobalSkills(HOME);
   recordInstalledAgents(installedAgentFilenames, installedIdes);
 
   // Phase 3: Generate squad-awareness.md

package/bin/commands/uninstall.js

@@ -82,12 +82,12 @@ function readInstalledAgentsManifest() {
   }
 }
 
-function removeInstalledAgentsFrom(dir) {
+function removeInstalledAgentsFrom(dir, manifestOverride = null) {
   if (!fs.existsSync(dir)) return { removed: 0, existed: false };
   let removed = 0;
   let candidates;
 
-  const manifest = readInstalledAgentsManifest();
+  const manifest = manifestOverride || readInstalledAgentsManifest();
   if (manifest && Array.isArray(manifest.filenames)) {
     // Manifest path — surgical removal of exactly what install wrote.
     candidates = manifest.filenames;
@@ -97,6 +97,9 @@ function removeInstalledAgentsFrom(dir) {
     // `-orqx.md`, OR start with `name: sinapse-` in their frontmatter.
     try {
       candidates = fs.readdirSync(dir).filter((f) => {
+        if (f.endsWith('.toml')) {
+          try { return /SINAPSE/i.test(fs.readFileSync(path.join(dir, f), 'utf8').slice(0, 4000)); } catch { return false; }
+        }
         if (!f.endsWith('.md')) return false;
         if (/-orqx\.md$/.test(f)) return true;
         try {
@@ -125,6 +128,46 @@ function removeOrqxAgentsFrom(dir) {
   return removeInstalledAgentsFrom(dir);
 }
 
+const MANAGED_GLOBAL_SKILL_IDS = ['snps', 'sinapse', 'snps-orqx', 'sinapse-agent'];
+const MANAGED_GLOBAL_SKILL_MARKER = 'SINAPSE-MANAGED:global-skill';
+
+function removeManagedGlobalSkills(home = HOME) {
+  let removed = 0;
+  for (const skillId of MANAGED_GLOBAL_SKILL_IDS) {
+    const skillDir = path.join(home, '.agents', 'skills', skillId);
+    const skillPath = path.join(skillDir, 'SKILL.md');
+    if (!fs.existsSync(skillPath)) continue;
+    try {
+      const content = fs.readFileSync(skillPath, 'utf8');
+      if (!content.includes(MANAGED_GLOBAL_SKILL_MARKER)) continue;
+      fs.unlinkSync(skillPath);
+      if (fs.readdirSync(skillDir).length === 0) fs.rmdirSync(skillDir);
+      removed++;
+    } catch { /* best-effort */ }
+  }
+  return { removed };
+}
+
+function reconcileInstalledAgents(home, desiredFilenames) {
+  const manifest = readInstalledAgentsManifest();
+  if (!manifest) return { removed: 0 };
+  const desired = new Set(desiredFilenames);
+  let removed = 0;
+  for (const filename of manifest.filenames) {
+    if (desired.has(filename)) continue;
+    const providerDir = filename.endsWith('.toml')
+      ? path.join(home, '.codex', 'agents')
+      : path.join(home, '.claude', 'agents');
+    const filepath = path.join(providerDir, filename);
+    if (!fs.existsSync(filepath)) continue;
+    try {
+      fs.unlinkSync(filepath);
+      removed++;
+    } catch { /* best-effort */ }
+  }
+  return { removed };
+}
+
 // Story 10.40 — Strip SINAPSE-owned keys from ~/.claude/settings.json without
 // touching anything else the user put there. Safe if the file is missing or
 // already clean.
@@ -176,6 +219,7 @@ async function cmdUninstall(opts = {}) {
   }
 
   logger.always(`${BOLD}Uninstalling Sinapse...${NC}\n`);
+  const installedAgentsManifest = readInstalledAgentsManifest();
 
   // Paths that are fully SINAPSE-owned (directory or launcher file)
   const ownedItems = [
@@ -210,7 +254,7 @@ async function cmdUninstall(opts = {}) {
   const claudeAgentsDir = path.join(HOME, '.claude', 'agents');
   const codexAgentsDir = path.join(HOME, '.codex', 'agents');
 
-  const claudeRemoved = removeInstalledAgentsFrom(claudeAgentsDir);
+  const claudeRemoved = removeInstalledAgentsFrom(claudeAgentsDir, installedAgentsManifest);
   if (!claudeRemoved.existed) {
     logger.always(`  ${YELLOW}-${NC} ~/.claude/agents/ SINAPSE files (dir not found)`);
   } else if (claudeRemoved.removed === 0) {
@@ -219,7 +263,7 @@ async function cmdUninstall(opts = {}) {
     logger.always(`  ${GREEN}✓${NC} Removed ~/.claude/agents/ SINAPSE files (${claudeRemoved.removed} files)`);
   }
 
-  const codexRemoved = removeInstalledAgentsFrom(codexAgentsDir);
+  const codexRemoved = removeInstalledAgentsFrom(codexAgentsDir, installedAgentsManifest);
   if (!codexRemoved.existed) {
     logger.always(`  ${YELLOW}-${NC} ~/.codex/agents/ SINAPSE files (dir not found)`);
   } else if (codexRemoved.removed === 0) {
@@ -229,6 +273,13 @@ async function cmdUninstall(opts = {}) {
   }
 
   // Story 10.40 — clean SINAPSE-owned keys from ~/.claude/settings.json
+  const skillsRemoved = removeManagedGlobalSkills(HOME);
+  if (skillsRemoved.removed > 0) {
+    logger.always(`  ${GREEN}OK${NC} Removed global SINAPSE skills (${skillsRemoved.removed})`);
+  } else {
+    logger.always(`  ${YELLOW}-${NC} Global SINAPSE skills (none present)`);
+  }
+
   const settingsPath = path.join(HOME, '.claude', 'settings.json');
   const settingsClean = cleanClaudeSettingsJson(settingsPath);
   if (settingsClean.touched) {
@@ -259,6 +310,8 @@ module.exports = {
   readInstalledAgentsManifest,
   removeInstalledAgentsFrom,
   removeOrqxAgentsFrom,
+  removeManagedGlobalSkills,
+  reconcileInstalledAgents,
   cleanClaudeSettingsJson,
   removeGitHooksConfig,
   INSTALLED_AGENTS_MANIFEST,

package/bin/commands/update.js

@@ -29,7 +29,13 @@ const {
 } = require('../lib/detection');
 const { promptLlmChoice } = require('../lib/prompts');
 const { generateSquadAwareness } = require('./install');
+const {
+  recordInstalledAgents,
+  reconcileInstalledAgents,
+  removeManagedGlobalSkills,
+} = require('./uninstall');
 const { regenerateAgentCommands } = require('../lib/command-generator');
+const { deliverGlobalProviderAdapters, getGlobalCommandStagingDir } = require('../lib/global-provider-adapters');
 const { execSync } = require('child_process');
 
 // Query the latest version published to npm. Returns null when npm is unreachable.
@@ -146,39 +152,44 @@ async function cmdUpdateGlobal() {
     logger.always(`  ${GREEN}OK${NC} sinapse (orqx)`);
   }
 
+  const coreDevelopmentSrc = path.join(ROOT, '.sinapse-ai', 'development');
+  const coreDevelopmentDest = path.join(SINAPSE_HOME, 'core');
+  if (fs.existsSync(coreDevelopmentSrc)) {
+    const delta = syncDirSync(coreDevelopmentSrc, coreDevelopmentDest);
+    totalDelta.added += delta.added;
+    totalDelta.updated += delta.updated;
+    totalDelta.unchanged += delta.unchanged;
+    totalDelta.removed += delta.removed;
+    logger.always(`  ${GREEN}OK${NC} core development`);
+  }
+
   // Phase 2: Regenerate commands — shared with `install` so `update` produces the
   // SAME complete set (every specialist command + the rich master Imperator stubs),
   // not just the `-orqx` subset it used to write.
   logger.always(`\n${CYAN}Phase 2:${NC} Regenerating commands`);
-  rmDirSync(CLAUDE_COMMANDS_DIR);
+  const commandStagingDir = getGlobalCommandStagingDir({ llmChoice, sinapseHome: SINAPSE_HOME, claudeCommandsDir: CLAUDE_COMMANDS_DIR });
+  rmDirSync(commandStagingDir);
   const { writtenAgents, totalAgents } = regenerateAgentCommands({
     sinapseHome: SINAPSE_HOME,
-    commandsDir: CLAUDE_COMMANDS_DIR,
+    commandsDir: commandStagingDir,
     squads,
     sinapseMasterDest: path.join(SINAPSE_HOME, 'sinapse'),
+    coreDevelopmentDest,
   });
   logger.always(`  ${GREEN}OK${NC} ${writtenAgents.size} command files (${totalAgents} agents total)`);
 
   // Phase 2b: Install global agents based on LLM choice
-  if (llmChoice === 'claude-code' || llmChoice === 'both') {
-    const globalAgentsDir = path.join(HOME, '.claude', 'agents');
-    fs.mkdirSync(globalAgentsDir, { recursive: true });
-    // Copy all generated agent commands as global agents
-    for (const f of fs.readdirSync(CLAUDE_COMMANDS_DIR).filter(f => f.endsWith('.md'))) {
-      fs.copyFileSync(path.join(CLAUDE_COMMANDS_DIR, f), path.join(globalAgentsDir, f));
-    }
-    logger.always(`  ${GREEN}OK${NC} Claude Code global agents (${writtenAgents.size})`);
-  }
-
-  if (llmChoice === 'codex' || llmChoice === 'both') {
-    const codexAgentsDir = path.join(HOME, '.codex', 'agents');
-    fs.mkdirSync(codexAgentsDir, { recursive: true });
-    // Copy all generated agent commands for Codex
-    for (const f of fs.readdirSync(CLAUDE_COMMANDS_DIR).filter(f => f.endsWith('.md'))) {
-      fs.copyFileSync(path.join(CLAUDE_COMMANDS_DIR, f), path.join(codexAgentsDir, f));
-    }
-    logger.always(`  ${GREEN}OK${NC} Codex global agents (${writtenAgents.size})`);
-  }
+  const globalAdapters = deliverGlobalProviderAdapters({ llmChoice, home: HOME, commandsDir: commandStagingDir });
+  if (globalAdapters.claude.length) logger.always(`  ${GREEN}OK${NC} Claude Code global agents (${globalAdapters.claude.length})`);
+  if (globalAdapters.codex.length) logger.always(`  ${GREEN}OK${NC} Codex global agents (${globalAdapters.codex.length} TOML, ${globalAdapters.skills.length} skills)`);
+
+  const installedAgentFilenames = new Set([...globalAdapters.claude, ...globalAdapters.codex]);
+  reconcileInstalledAgents(HOME, installedAgentFilenames);
+  if (llmChoice === 'claude-code') removeManagedGlobalSkills(HOME);
+  const installedIdes = [];
+  if (globalAdapters.claude.length) installedIdes.push('claude-code');
+  if (globalAdapters.codex.length) installedIdes.push('codex');
+  recordInstalledAgents(installedAgentFilenames, installedIdes);
 
   // Phase 3: Regenerate awareness
   logger.always(`\n${CYAN}Phase 3:${NC} Updating squad-awareness`);

package/bin/lib/command-generator.js

@@ -116,7 +116,7 @@ Tasks: \`${squadPath}/tasks/\` · Workflows: \`${squadPath}/workflows/\` · Mani
 `;
 }
 
-function generateCommandMd(agentId, agentName, agentIcon, squadName, squadPath, agentFile) {
+function generateCommandMd(agentId, agentName, agentIcon, squadName, squadPath, agentFile, options = {}) {
   // Detecta se é orquestrador: id termina em -orqx OU é Imperator (snps-orqx/sinapse-orqx)
   // ou um dos apelidos curtos do master (sinapse/snps).
   const isOrchestrator = /-orqx$/.test(agentId) || agentId === 'snps-orqx' || agentId === 'sinapse-orqx' || agentId === 'sinapse' || agentId === 'snps';
@@ -139,6 +139,12 @@ function generateCommandMd(agentId, agentName, agentIcon, squadName, squadPath,
   const fmDesc = (isOrchestrator
     ? `${agentName || agentId} — orchestrator for ${squadName}; diagnoses, routes to specialists and auto-generates an orchestration plan`
     : `${agentName || agentId} — ${squadName} specialist`).replace(/["\n\r]/g, ' ').trim();
+  const manifestActivation = options.hasManifest === false
+    ? '2. Use the installed core development module as canonical context'
+    : `2. Load the squad manifest at \`${squadPath}/squad.yaml\` for context`;
+  const manifestReference = options.hasManifest === false
+    ? `- **Canonical module:** \`${squadPath}/\``
+    : `- **Squad Manifest:** \`${squadPath}/squad.yaml\``;
 
   return `---
 name: ${agentId}
@@ -151,7 +157,7 @@ ACTIVATION-NOTICE: This command activates an agent from ${squadName}.
 
 CRITICAL: Read the agent definition file at \`${squadPath}/agents/${agentFile}\` to understand your full operating parameters. Then:
 1. Adopt the persona defined in that file (name: ${agentName}, icon: ${agentIcon})
-2. Load the squad manifest at \`${squadPath}/squad.yaml\` for context
+${manifestActivation}
 3. Display a greeting showing your agent name, role, and available commands
 ${step4}
 
@@ -159,7 +165,7 @@ ${step4}
 - **Agent ID:** ${agentId}
 - **Squad:** ${squadName}
 - **Definition:** \`${squadPath}/agents/${agentFile}\`
-- **Squad Manifest:** \`${squadPath}/squad.yaml\`
+${manifestReference}
 - **Tasks:** \`${squadPath}/tasks/\`
 - **Knowledge Bases:** \`${squadPath}/knowledge-base/\`
 - **Workflows:** \`${squadPath}/workflows/\`
@@ -209,6 +215,7 @@ function regenerateAgentCommands(deps = {}) {
     commandsDir = CLAUDE_COMMANDS_DIR,
     squads,
     sinapseMasterDest = path.join(sinapseHome, 'sinapse'),
+    coreDevelopmentDest = path.join(sinapseHome, 'core'),
   } = deps;
 
   if (!Array.isArray(squads)) {
@@ -244,6 +251,21 @@ function regenerateAgentCommands(deps = {}) {
     }
   }
 
+  // Core agents are mirrored by the global installer so definitions and tasks
+  // remain resolvable after the npm process exits.
+  const coreAgentsDir = path.join(coreDevelopmentDest, 'agents');
+  if (fs.existsSync(coreAgentsDir)) {
+    const coreBase = toForwardSlash(coreDevelopmentDest);
+    for (const file of fs.readdirSync(coreAgentsDir).filter(f => f.endsWith('.md'))) {
+      if (file === 'README.md' || file === 'MEMORY.md' || file.startsWith('_') || writtenAgents.has(file)) continue;
+      const agentId = file.replace('.md', '');
+      const meta = extractAgentMeta(path.join(coreAgentsDir, file));
+      const cmdContent = generateCommandMd(agentId, meta.name, meta.icon, 'core', coreBase, file, { hasManifest: false });
+      atomicWriteFileSync(path.join(commandsDir, `${agentId}.md`), cmdContent);
+      writtenAgents.add(file);
+    }
+  }
+
   // 2. Commands for sinapse/ master squad agents.
   if (fs.existsSync(sinapseMasterDest)) {
     const masterAgentsDir = path.join(sinapseMasterDest, 'agents');

package/bin/lib/global-provider-adapters.js

@@ -0,0 +1,136 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+function parseAgentMarkdown(content, fallbackName) {
+  const name = content.match(/^name:\s*([^\r\n]+)$/m)?.[1]?.trim() || fallbackName;
+  const raw = content.match(/^description:\s*(.+)$/m)?.[1]?.trim() || `SINAPSE ${name} agent`;
+  return { name, description: raw.replace(/^['"]|['"]$/g, '') };
+}
+
+function renderCodexToml(name, description, instructions) {
+  return [
+    `name = ${JSON.stringify(name)}`,
+    `description = ${JSON.stringify(description)}`,
+    `developer_instructions = ${JSON.stringify(instructions)}`,
+    '',
+  ].join('\n');
+}
+
+function renderGlobalSkill(skillId) {
+  const generic = skillId === 'sinapse-agent';
+  return [
+    '---',
+    `name: ${skillId}`,
+    `description: ${generic ? 'Resolve and activate any globally installed SINAPSE agent by ID.' : 'Activate the globally installed SINAPSE supreme orchestrator.'}`,
+    '---', '',
+    '<!-- SINAPSE-MANAGED:global-skill -->', '',
+    generic ? '# SINAPSE Global Agent Activator' : '# SINAPSE Global Orchestrator', '',
+    generic
+      ? 'Use the requested ID from `~/.codex/agents/<id>.toml`; reject unknown IDs without guessing.'
+      : 'Resolve this alias to the `sinapse-orqx` custom agent and preserve its delegation-only authority.',
+    'Canonical global persona and task sources live under `~/.sinapse/`.',
+    'Use native Codex delegation and never start a nested CLI.', '',
+  ].join('\n');
+}
+
+function writeFileAtomically(filePath, content) {
+  const temporaryPath = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+  let handle;
+  try {
+    handle = fs.openSync(temporaryPath, 'wx', 0o600);
+    fs.writeFileSync(handle, content, 'utf8');
+    fs.fsyncSync(handle);
+    fs.closeSync(handle);
+    handle = undefined;
+    fs.renameSync(temporaryPath, filePath);
+  } finally {
+    if (handle !== undefined) fs.closeSync(handle);
+    try { fs.unlinkSync(temporaryPath); } catch { /* already published or cleanup is best-effort */ }
+  }
+}
+
+function writeGlobalSkillIfManaged(skillPath, content) {
+  fs.mkdirSync(path.dirname(skillPath), { recursive: true });
+
+  let handle;
+  try {
+    const noFollow = fs.constants.O_NOFOLLOW || 0;
+    handle = fs.openSync(skillPath, fs.constants.O_RDONLY | noFollow);
+  } catch (error) {
+    if (error.code === 'ELOOP') return false;
+    if (error.code !== 'ENOENT') throw error;
+    try {
+      handle = fs.openSync(skillPath, 'wx');
+    } catch (createError) {
+      if (createError.code === 'EEXIST') return writeGlobalSkillIfManaged(skillPath, content);
+      throw createError;
+    }
+    try {
+      fs.writeFileSync(handle, content, 'utf8');
+      return true;
+    } finally {
+      fs.closeSync(handle);
+    }
+  }
+
+  try {
+    if (!fs.fstatSync(handle).isFile()) return false;
+    const existing = fs.readFileSync(handle, 'utf8');
+    if (!existing.includes('SINAPSE-MANAGED:global-skill')) return false;
+    fs.closeSync(handle);
+    handle = undefined;
+    writeFileAtomically(skillPath, content);
+    return true;
+  } finally {
+    if (handle !== undefined) fs.closeSync(handle);
+  }
+}
+
+function deliverGlobalProviderAdapters({ llmChoice, home, commandsDir }) {
+  const commandFiles = fs.existsSync(commandsDir)
+    ? fs.readdirSync(commandsDir).filter((file) => file.endsWith('.md')).sort()
+    : [];
+  const written = { claude: [], codex: [], skills: [] };
+
+  if (llmChoice === 'claude-code' || llmChoice === 'both') {
+    const targetDir = path.join(home, '.claude', 'agents');
+    fs.mkdirSync(targetDir, { recursive: true });
+    for (const file of commandFiles) {
+      fs.copyFileSync(path.join(commandsDir, file), path.join(targetDir, file));
+      written.claude.push(file);
+    }
+  }
+  if (llmChoice === 'codex' || llmChoice === 'both') {
+    const targetDir = path.join(home, '.codex', 'agents');
+    fs.mkdirSync(targetDir, { recursive: true });
+    for (const file of commandFiles) {
+      const markdown = fs.readFileSync(path.join(commandsDir, file), 'utf8');
+      const id = file.replace(/\.md$/, '');
+      const metadata = parseAgentMarkdown(markdown, id);
+      const tomlName = `${id}.toml`;
+      fs.writeFileSync(path.join(targetDir, tomlName), renderCodexToml(metadata.name, metadata.description, markdown), 'utf8');
+      const staleMarkdown = path.join(targetDir, file);
+      if (fs.existsSync(staleMarkdown)) fs.unlinkSync(staleMarkdown);
+      written.codex.push(tomlName);
+    }
+    const skillsRoot = path.join(home, '.agents', 'skills');
+    for (const skillId of ['snps', 'sinapse', 'snps-orqx', 'sinapse-agent']) {
+      const skillDir = path.join(skillsRoot, skillId);
+      const skillPath = path.join(skillDir, 'SKILL.md');
+      if (writeGlobalSkillIfManaged(skillPath, renderGlobalSkill(skillId))) {
+        written.skills.push(skillId);
+      }
+    }
+  }
+  return written;
+}
+
+function getGlobalCommandStagingDir({ llmChoice, sinapseHome, claudeCommandsDir }) {
+  return llmChoice === 'codex'
+    ? path.join(sinapseHome, '.generated', 'agents')
+    : claudeCommandsDir;
+}
+
+module.exports = { parseAgentMarkdown, renderCodexToml, renderGlobalSkill, writeGlobalSkillIfManaged, deliverGlobalProviderAdapters, getGlobalCommandStagingDir };