sinapse-ai 1.25.1 → 1.25.3

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

@@ -2,17 +2,73 @@
 
 const fs = require('fs');
 const path = require('path');
+const crypto = require('crypto');
+const {
+  MASTER_ALIAS_ENTRY_POINTS,
+  GLOBAL_PROVIDER_SKILL_IDS,
+  SUPREME_ORCHESTRATOR_ID,
+  SUPREME_PUBLIC_ID,
+} = require('./provider-contract');
 
 const NOFOLLOW_READ_FLAGS = fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW || 0);
 
+function isPathInside(root, candidate) {
+  const relative = path.relative(root, candidate);
+  return relative === '' || (!relative.startsWith(`..${path.sep}`) && relative !== '..' && !path.isAbsolute(relative));
+}
+
+function ensureSafeDirectoryWithinHome(home, directory) {
+  const absoluteHome = path.resolve(home);
+  const absoluteDirectory = path.resolve(directory);
+  if (!isPathInside(absoluteHome, absoluteDirectory)) {
+    throw new Error(`Refusing provider write outside HOME: ${absoluteDirectory}`);
+  }
+  fs.mkdirSync(absoluteHome, { recursive: true });
+  const homeStat = fs.lstatSync(absoluteHome);
+  if (homeStat.isSymbolicLink() || !homeStat.isDirectory()) {
+    throw new Error(`Refusing provider write through unsafe HOME: ${absoluteHome}`);
+  }
+  const realHome = fs.realpathSync.native(absoluteHome);
+  let current = absoluteHome;
+  const relative = path.relative(absoluteHome, absoluteDirectory);
+  for (const segment of relative.split(path.sep).filter(Boolean)) {
+    current = path.join(current, segment);
+    if (!fs.existsSync(current)) fs.mkdirSync(current);
+    const stat = fs.lstatSync(current);
+    if (stat.isSymbolicLink() || !stat.isDirectory()) {
+      throw new Error(`Refusing provider write through link/reparse path: ${current}`);
+    }
+    const realCurrent = fs.realpathSync.native(current);
+    if (!isPathInside(realHome, realCurrent)) {
+      throw new Error(`Refusing provider write outside HOME through reparse path: ${current}`);
+    }
+  }
+  return absoluteDirectory;
+}
+
+function assertSafeFileWithinHome(home, filePath) {
+  ensureSafeDirectoryWithinHome(home, path.dirname(filePath));
+  if (fs.existsSync(filePath)) {
+    const stat = fs.lstatSync(filePath);
+    if (stat.isSymbolicLink() || !stat.isFile()) {
+      throw new Error(`Refusing provider write through unsafe file: ${filePath}`);
+    }
+    return stat;
+  }
+  return null;
+}
+
 function readRegularFileNoFollowSync(filePath, encoding = null) {
   let handle;
   try {
     handle = fs.openSync(filePath, NOFOLLOW_READ_FLAGS);
-    if (!fs.fstatSync(handle).isFile()) return null;
+    const opened = fs.fstatSync(handle);
+    const after = fs.lstatSync(filePath);
+    if (!opened.isFile() || after.isSymbolicLink() || !after.isFile()) return null;
+    if (after.dev !== opened.dev || after.ino !== opened.ino) return null;
     return fs.readFileSync(handle, encoding || undefined);
   } catch (error) {
-    if (['ENOENT', 'ELOOP', 'EISDIR'].includes(error.code)) return null;
+    if (['ENOENT', 'ELOOP', 'EISDIR', 'EINVAL', 'UNKNOWN'].includes(error.code)) return null;
     throw error;
   } finally {
     if (handle !== undefined) fs.closeSync(handle);
@@ -36,8 +92,11 @@ function renderCodexToml(name, description, instructions) {
 
 function markGlobalAgent(markdown, fileName = '') {
   let content = markdown;
-  if (fileName === 'snps-orqx.md') {
-    content = content.replace(/^name:\s*snps-orqx\s*$/m, 'name: sinapse-orqx');
+  if (fileName === `${SUPREME_ORCHESTRATOR_ID}.md`) {
+    content = content.replace(
+      new RegExp(`^name:\\s*${SUPREME_ORCHESTRATOR_ID}\\s*$`, 'm'),
+      `name: ${SUPREME_PUBLIC_ID}`,
+    );
   }
   if (content.includes('SINAPSE-MANAGED:global-agent')) return content;
   return `${content.trimEnd()}\n\n<!-- SINAPSE-MANAGED:global-agent -->\n`;
@@ -54,137 +113,273 @@ function renderGlobalSkill(skillId) {
     generic ? '# SINAPSE Global Agent Activator' : '# SINAPSE Global Orchestrator', '',
     generic
       ? 'Resolve the requested ID through the native agent catalog of the active provider; reject unknown IDs without guessing.'
-      : 'Resolve this alias to the `sinapse-orqx` custom agent and preserve its delegation-only authority.',
+      : `Activate the public adapter \`${SUPREME_PUBLIC_ID}\`, backed by canonical source ID \`${SUPREME_ORCHESTRATOR_ID}\`, 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`;
+function captureParentBinding(home, parentPath) {
+  ensureSafeDirectoryWithinHome(home, parentPath);
+  const handle = fs.openSync(parentPath, fs.constants.O_RDONLY);
+  const opened = fs.fstatSync(handle);
+  const current = fs.lstatSync(parentPath);
+  if (!opened.isDirectory() || current.isSymbolicLink() || !current.isDirectory()
+    || opened.dev !== current.dev || opened.ino !== current.ino) {
+    fs.closeSync(handle);
+    throw new Error(`Refusing provider write through unstable parent: ${parentPath}`);
+  }
+  return { handle, dev: opened.dev, ino: opened.ino, realPath: fs.realpathSync.native(parentPath) };
+}
+
+function assertParentBinding(home, parentPath, binding) {
+  ensureSafeDirectoryWithinHome(home, parentPath);
+  const current = fs.lstatSync(parentPath);
+  const opened = fs.fstatSync(binding.handle);
+  const realPath = fs.realpathSync.native(parentPath);
+  if (current.isSymbolicLink() || !current.isDirectory() || !opened.isDirectory()
+    || current.dev !== binding.dev || current.ino !== binding.ino
+    || opened.dev !== binding.dev || opened.ino !== binding.ino
+    || realPath !== binding.realPath) {
+    throw new Error(`Refusing provider publish after parent path changed: ${parentPath}`);
+  }
+}
+
+function unlinkFileWithBinding(home, filePath, binding, expected, beforeDelete) {
+  if (typeof beforeDelete === 'function') beforeDelete({ filePath, parentPath: path.dirname(filePath) });
+  assertParentBinding(home, path.dirname(filePath), binding);
+  let current;
+  try {
+    current = fs.lstatSync(filePath);
+  } catch (error) {
+    if (error.code === 'ENOENT') return false;
+    throw error;
+  }
+  if (current.isSymbolicLink() || !current.isFile()
+    || current.dev !== expected.dev || current.ino !== expected.ino) {
+    throw new Error(`Refusing provider delete after file identity changed: ${filePath}`);
+  }
+  fs.unlinkSync(filePath);
+  assertParentBinding(home, path.dirname(filePath), binding);
+  return true;
+}
+
+function writeFileAtomically(filePath, content, home = path.dirname(filePath), options = {}) {
+  const destinationIdentity = assertSafeFileWithinHome(home, filePath);
+  const parentPath = path.dirname(filePath);
+  const binding = captureParentBinding(home, parentPath);
+  const temporaryPath = path.join(
+    parentPath,
+    `.${path.basename(filePath)}.${crypto.randomBytes(24).toString('hex')}.tmp`,
+  );
   let handle;
+  let temporaryIdentity;
+  let temporaryExists = false;
   try {
     handle = fs.openSync(temporaryPath, 'wx', 0o600);
+    temporaryIdentity = fs.fstatSync(handle);
+    temporaryExists = true;
     fs.writeFileSync(handle, content, 'utf8');
     fs.fsyncSync(handle);
     fs.closeSync(handle);
     handle = undefined;
-    fs.renameSync(temporaryPath, filePath);
+    if (typeof options.beforePublish === 'function') {
+      options.beforePublish({ filePath, parentPath, temporaryPath });
+    }
+    assertParentBinding(home, parentPath, binding);
+    if (options.exclusive) {
+      fs.linkSync(temporaryPath, filePath);
+      assertParentBinding(home, parentPath, binding);
+      unlinkFileWithBinding(home, temporaryPath, binding, temporaryIdentity, options.beforeTempCleanup);
+      temporaryExists = false;
+    } else {
+      const currentDestination = assertSafeFileWithinHome(home, filePath);
+      if (destinationIdentity && (!currentDestination
+        || currentDestination.dev !== destinationIdentity.dev
+        || currentDestination.ino !== destinationIdentity.ino)) {
+        throw new Error(`Refusing provider overwrite after file identity changed: ${filePath}`);
+      }
+      if (!destinationIdentity && currentDestination) {
+        throw new Error(`Refusing provider overwrite of a newly appeared file: ${filePath}`);
+      }
+      assertParentBinding(home, parentPath, binding);
+      fs.renameSync(temporaryPath, filePath);
+      temporaryExists = false;
+    }
+    assertParentBinding(home, parentPath, binding);
   } finally {
     if (handle !== undefined) fs.closeSync(handle);
-    try { fs.unlinkSync(temporaryPath); } catch { /* already published or cleanup is best-effort */ }
+    let parentStillBound = false;
+    try {
+      assertParentBinding(home, parentPath, binding);
+      parentStillBound = true;
+    } catch { /* never traverse the temporary pathname after an ancestor swap */ }
+    if (parentStillBound && temporaryExists) {
+      try {
+        unlinkFileWithBinding(home, temporaryPath, binding, temporaryIdentity, options.beforeTempCleanup);
+      } catch { /* fail closed: leave an untrusted temporary path untouched */ }
+    }
+    fs.closeSync(binding.handle);
   }
 }
 
-function writeGlobalSkillIfManaged(skillPath, content) {
-  fs.mkdirSync(path.dirname(skillPath), { recursive: true });
+function writeGlobalSkillIfManaged(skillPath, content, home = path.dirname(skillPath), options = {}) {
+  ensureSafeDirectoryWithinHome(home, path.dirname(skillPath));
 
   let handle;
   try {
+    try {
+      const existingStat = fs.lstatSync(skillPath);
+      if (existingStat.isSymbolicLink() || !existingStat.isFile()) return false;
+    } catch (error) {
+      if (error.code !== 'ENOENT') throw error;
+    }
     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');
+      writeFileAtomically(skillPath, content, home, { ...options, exclusive: true });
+      return true;
     } catch (createError) {
-      if (createError.code === 'EEXIST') return writeGlobalSkillIfManaged(skillPath, content);
+      if (createError.code === 'EEXIST') return writeGlobalSkillIfManaged(skillPath, content, home, options);
       throw createError;
     }
-    try {
-      fs.writeFileSync(handle, content, 'utf8');
-      return true;
-    } finally {
-      fs.closeSync(handle);
-    }
   }
 
   try {
-    if (!fs.fstatSync(handle).isFile()) return false;
+    const opened = fs.fstatSync(handle);
+    const current = fs.lstatSync(skillPath);
+    if (!opened.isFile() || current.isSymbolicLink() || !current.isFile()) return false;
+    if (current.dev !== opened.dev || current.ino !== opened.ino) 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);
+    writeFileAtomically(skillPath, content, home);
     return true;
   } finally {
     if (handle !== undefined) fs.closeSync(handle);
   }
 }
 
-function removeStaleManagedAgents(targetDir, expectedFiles, extension) {
+function isValidGlobalSkill(skillId, skillPath) {
+  const content = readRegularFileNoFollowSync(skillPath, 'utf8');
+  return content !== null && content === renderGlobalSkill(skillId);
+}
+
+function removeStaleManagedAgents(targetDir, expectedFiles, extension, options = {}) {
   if (!fs.existsSync(targetDir)) return [];
+  const home = options.home || path.dirname(targetDir);
+  const binding = captureParentBinding(home, targetDir);
   const expected = new Set(expectedFiles);
   const removed = [];
-  for (const file of fs.readdirSync(targetDir).filter((name) => name.endsWith(extension))) {
-    if (expected.has(file)) continue;
-    const filePath = path.join(targetDir, file);
-    const content = readRegularFileNoFollowSync(filePath, 'utf8');
-    if (content === null) continue;
-    const explicitlyManaged = content.includes('SINAPSE-MANAGED:global-agent');
-    const legacyManaged = content.includes('ACTIVATION-NOTICE: This command activates an agent from sinapse.')
-      && /\.sinapse[\\/]sinapse[\\/]agents[\\/]/.test(content)
-      && content.includes('Load the squad manifest');
-    if (!explicitlyManaged && !legacyManaged) continue;
-    fs.unlinkSync(filePath);
-    removed.push(file);
+  try {
+    for (const file of fs.readdirSync(targetDir).filter((name) => name.endsWith(extension))) {
+      if (expected.has(file)) continue;
+      const filePath = path.join(targetDir, file);
+      const identity = fs.lstatSync(filePath);
+      const content = readRegularFileNoFollowSync(filePath, 'utf8');
+      if (content === null) continue;
+      const explicitlyManaged = content.includes('SINAPSE-MANAGED:global-agent');
+      const legacyManaged = content.includes('ACTIVATION-NOTICE: This command activates an agent from sinapse.')
+        && /\.sinapse[\\/]sinapse[\\/]agents[\\/]/.test(content)
+        && content.includes('Load the squad manifest');
+      if (!explicitlyManaged && !legacyManaged) continue;
+      if (unlinkFileWithBinding(home, filePath, binding, identity, options.beforeDelete)) removed.push(file);
+    }
+  } finally {
+    fs.closeSync(binding.handle);
   }
   return removed;
 }
 
-function deliverGlobalProviderAdapters({ llmChoice, home, commandsDir }) {
+function removeManagedFileWithBinding(home, filePath, beforeDelete) {
+  let identity;
+  try {
+    identity = fs.lstatSync(filePath);
+  } catch (error) {
+    if (error.code === 'ENOENT') return false;
+    throw error;
+  }
+  const content = readRegularFileNoFollowSync(filePath, 'utf8');
+  if (content === null || !content.includes('SINAPSE-MANAGED:global-agent')) return false;
+  const afterRead = fs.lstatSync(filePath);
+  if (afterRead.isSymbolicLink() || !afterRead.isFile()
+    || afterRead.dev !== identity.dev || afterRead.ino !== identity.ino) {
+    throw new Error(`Refusing provider delete after file identity changed: ${filePath}`);
+  }
+  const binding = captureParentBinding(home, path.dirname(filePath));
+  try {
+    return unlinkFileWithBinding(home, filePath, binding, identity, beforeDelete);
+  } finally {
+    fs.closeSync(binding.handle);
+  }
+}
+
+function deliverGlobalProviderAdapters({ llmChoice, home, commandsDir, testHooks = {} }) {
   let commandFiles = fs.existsSync(commandsDir)
     ? fs.readdirSync(commandsDir).filter((file) => file.endsWith('.md')).sort()
     : [];
-  if (commandFiles.includes('snps-orqx.md')) {
-    const aliasFiles = new Set(['sinapse.md', 'sinapse-orqx.md', 'snps.md']);
+  if (commandFiles.includes(`${SUPREME_ORCHESTRATOR_ID}.md`)) {
+    const aliasFiles = new Set(MASTER_ALIAS_ENTRY_POINTS.map((id) => `${id}.md`));
     commandFiles = commandFiles.filter((file) => !aliasFiles.has(file));
   }
-  const written = { claude: [], claudeSkills: [], codex: [], skills: [] };
+  const written = {
+    claude: [],
+    claudeSkills: [],
+    claudeAvailableSkills: [],
+    codex: [],
+    skills: [],
+    availableSkills: [],
+  };
 
   if (llmChoice === 'claude-code' || llmChoice === 'both') {
     const targetDir = path.join(home, '.claude', 'agents');
-    fs.mkdirSync(targetDir, { recursive: true });
-    removeStaleManagedAgents(targetDir, commandFiles, '.md');
+    ensureSafeDirectoryWithinHome(home, targetDir);
+    removeStaleManagedAgents(targetDir, commandFiles, '.md', { home, beforeDelete: testHooks.beforeStaleAgentDelete });
     for (const file of commandFiles) {
       const markdown = markGlobalAgent(fs.readFileSync(path.join(commandsDir, file), 'utf8'), file);
-      fs.writeFileSync(path.join(targetDir, file), markdown, 'utf8');
+      writeFileAtomically(path.join(targetDir, file), markdown, home);
       written.claude.push(file);
     }
     const skillsRoot = path.join(home, '.claude', 'skills');
-    for (const skillId of ['snps', 'sinapse', 'snps-orqx', 'sinapse-orqx', 'sinapse-agent']) {
+    for (const skillId of GLOBAL_PROVIDER_SKILL_IDS) {
       const skillPath = path.join(skillsRoot, skillId, 'SKILL.md');
-      if (writeGlobalSkillIfManaged(skillPath, renderGlobalSkill(skillId))) {
+      if (writeGlobalSkillIfManaged(skillPath, renderGlobalSkill(skillId), home, { beforePublish: testHooks.beforeSkillPublish })) {
         written.claudeSkills.push(skillId);
       }
+      if (isValidGlobalSkill(skillId, skillPath)) written.claudeAvailableSkills.push(skillId);
     }
   }
   if (llmChoice === 'codex' || llmChoice === 'both') {
     const targetDir = path.join(home, '.codex', 'agents');
-    fs.mkdirSync(targetDir, { recursive: true });
+    ensureSafeDirectoryWithinHome(home, targetDir);
     removeStaleManagedAgents(
       targetDir,
       commandFiles.map((file) => file.replace(/\.md$/, '.toml')),
       '.toml',
+      { home, beforeDelete: testHooks.beforeStaleAgentDelete },
     );
     for (const file of commandFiles) {
       const markdown = markGlobalAgent(fs.readFileSync(path.join(commandsDir, file), 'utf8'), file);
       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');
+      writeFileAtomically(path.join(targetDir, tomlName), renderCodexToml(metadata.name, metadata.description, markdown), home);
       const staleMarkdown = path.join(targetDir, file);
-      if (fs.existsSync(staleMarkdown)) fs.unlinkSync(staleMarkdown);
+      removeManagedFileWithBinding(home, staleMarkdown, testHooks.beforeStaleMarkdownDelete);
       written.codex.push(tomlName);
     }
     const skillsRoot = path.join(home, '.agents', 'skills');
-    for (const skillId of ['snps', 'sinapse', 'snps-orqx', 'sinapse-orqx', 'sinapse-agent']) {
+    for (const skillId of GLOBAL_PROVIDER_SKILL_IDS) {
       const skillDir = path.join(skillsRoot, skillId);
       const skillPath = path.join(skillDir, 'SKILL.md');
-      if (writeGlobalSkillIfManaged(skillPath, renderGlobalSkill(skillId))) {
+      if (writeGlobalSkillIfManaged(skillPath, renderGlobalSkill(skillId), home, { beforePublish: testHooks.beforeSkillPublish })) {
         written.skills.push(skillId);
       }
+      if (isValidGlobalSkill(skillId, skillPath)) written.availableSkills.push(skillId);
     }
   }
   return written;
@@ -196,4 +391,4 @@ function getGlobalCommandStagingDir({ llmChoice, sinapseHome, claudeCommandsDir
   return path.join(sinapseHome, '.generated', 'agents');
 }
 
-module.exports = { parseAgentMarkdown, renderCodexToml, markGlobalAgent, renderGlobalSkill, writeGlobalSkillIfManaged, removeStaleManagedAgents, deliverGlobalProviderAdapters, getGlobalCommandStagingDir };
+module.exports = { parseAgentMarkdown, renderCodexToml, markGlobalAgent, renderGlobalSkill, readRegularFileNoFollowSync, writeFileAtomically, writeGlobalSkillIfManaged, isValidGlobalSkill, ensureSafeDirectoryWithinHome, removeStaleManagedAgents, deliverGlobalProviderAdapters, getGlobalCommandStagingDir };

package/bin/lib/provider-contract.js

@@ -0,0 +1,23 @@
+'use strict';
+
+const CANONICAL_AGENT_COUNT = 172;
+const SUPREME_ORCHESTRATOR_ID = 'snps-orqx';
+const SUPREME_PUBLIC_ID = SUPREME_ORCHESTRATOR_ID.replace(/^snps/, 'sinapse');
+const MASTER_ALIAS_ENTRY_POINTS = Object.freeze([
+  SUPREME_PUBLIC_ID.replace(/-orqx$/, ''),
+  SUPREME_PUBLIC_ID,
+  SUPREME_ORCHESTRATOR_ID.replace(/-orqx$/, ''),
+]);
+const GLOBAL_PROVIDER_SKILL_IDS = Object.freeze([
+  ...MASTER_ALIAS_ENTRY_POINTS,
+  SUPREME_ORCHESTRATOR_ID,
+  'sinapse-agent',
+]);
+
+module.exports = {
+  CANONICAL_AGENT_COUNT,
+  SUPREME_ORCHESTRATOR_ID,
+  SUPREME_PUBLIC_ID,
+  MASTER_ALIAS_ENTRY_POINTS,
+  GLOBAL_PROVIDER_SKILL_IDS,
+};

package/bin/lib/provider-parity.js

@@ -1,22 +1,73 @@
 'use strict';
 
-function assertProviderAdapterParity(llmChoice, adapters, canonicalCount) {
+const {
+  CANONICAL_AGENT_COUNT,
+  GLOBAL_PROVIDER_SKILL_IDS,
+} = require('./provider-contract');
+
+function normalizeCanonicalCatalog(canonicalCatalog, extension) {
+  if (!canonicalCatalog || typeof canonicalCatalog === 'number') {
+    throw new Error('Provider adapter parity requires the canonical agent ID catalog');
+  }
+  const entries = [...canonicalCatalog].map((entry) => (typeof entry === 'string'
+    ? { id: entry.replace(/\.md$/, ''), file: entry }
+    : entry));
+  const sourceIds = entries.map((entry) => entry.id);
+  const sourceSet = new Set(sourceIds);
+  if (sourceSet.size !== sourceIds.length) {
+    const duplicates = [...sourceSet]
+      .filter((id) => sourceIds.filter((item) => item === id).length > 1);
+    throw new Error(`Canonical agent catalog contains duplicate IDs: ${duplicates.join(', ')}`);
+  }
+  if (entries.length !== CANONICAL_AGENT_COUNT) {
+    throw new Error(`Canonical agent catalog must contain exactly ${CANONICAL_AGENT_COUNT} unique IDs, found ${entries.length}`);
+  }
+  const files = entries.map((entry) => entry.file.replace(/\.md$/, extension));
+  return { count: CANONICAL_AGENT_COUNT, files: new Set(files) };
+}
+
+function describeCatalogDivergence(provider, actualFiles, canonical) {
+  const actual = new Set(actualFiles);
+  const problems = [];
+  if (actualFiles.length !== canonical.count) {
+    problems.push(`${provider}: ${actualFiles.length}/${canonical.count}`);
+  }
+  if (canonical.files) {
+    if (actual.size !== actualFiles.length) {
+      const duplicates = [...actual].filter((file) => actualFiles.filter((item) => item === file).length > 1);
+      problems.push(`${provider} duplicate: ${duplicates.join(', ')}`);
+    }
+    const missing = [...canonical.files].filter((file) => !actual.has(file));
+    const orphaned = [...actual].filter((file) => !canonical.files.has(file));
+    if (missing.length) problems.push(`${provider} missing: ${missing.join(', ')}`);
+    if (orphaned.length) problems.push(`${provider} orphaned: ${orphaned.join(', ')}`);
+  }
+  return problems;
+}
+
+function assertProviderAdapterParity(llmChoice, adapters, canonicalCatalog) {
   if (!['claude-code', 'codex', 'both'].includes(llmChoice)) {
     throw new Error(`Invalid LLM choice for provider parity: ${llmChoice}`);
   }
-  const providerCounts = [];
+  const problems = [];
+  const claudeCatalog = normalizeCanonicalCatalog(canonicalCatalog, '.md');
+  const codexCatalog = normalizeCanonicalCatalog(canonicalCatalog, '.toml');
   if (llmChoice === 'claude-code' || llmChoice === 'both') {
-    providerCounts.push(['Claude Code', adapters.claude.length]);
+    problems.push(...describeCatalogDivergence('Claude Code', adapters.claude, claudeCatalog));
+    const claudeSkills = new Set(adapters.claudeAvailableSkills || adapters.claudeSkills || []);
+    const missingAliases = GLOBAL_PROVIDER_SKILL_IDS.filter((alias) => !claudeSkills.has(alias));
+    if (missingAliases.length) problems.push(`Claude Code alias skills missing: ${missingAliases.join(', ')}`);
   }
   if (llmChoice === 'codex' || llmChoice === 'both') {
-    providerCounts.push(['Codex', adapters.codex.length]);
+    problems.push(...describeCatalogDivergence('Codex', adapters.codex, codexCatalog));
+    const codexSkills = new Set(adapters.availableSkills || adapters.skills || []);
+    const missingAliases = GLOBAL_PROVIDER_SKILL_IDS.filter((alias) => !codexSkills.has(alias));
+    if (missingAliases.length) problems.push(`Codex alias skills missing: ${missingAliases.join(', ')}`);
   }
-  const divergent = providerCounts.filter(([, count]) => count !== canonicalCount);
-  if (divergent.length) {
-    const details = divergent.map(([provider, count]) => `${provider}: ${count}/${canonicalCount}`).join(', ');
-    throw new Error(`Provider adapter parity failed (${details})`);
+  if (problems.length) {
+    throw new Error(`Provider adapter parity failed (${problems.join('; ')})`);
   }
-  return canonicalCount;
+  return claudeCatalog.count;
 }
 
 module.exports = { assertProviderAdapterParity };

package/docs/getting-started.md

@@ -27,14 +27,22 @@ Se algo falhar: `npx sinapse-ai doctor --fix` corrige automaticamente.
 
 ## Ativar primeiro agente
 
-No prompt do Claude Code ou Codex:
+No Claude Code:
 
-```
+```text
 @developer
 *help
 ```
 
-`@developer` ativa o agente de implementação. `*help` lista comandos disponíveis.
+No Codex, use o roteador ou a ativação direta:
+
+```text
+$snps
+$sinapse-agent developer
+```
+
+`@developer` e `*help` pertencem à superfície do Claude Code. No Codex, `$snps`
+roteia a solicitação e `$sinapse-agent developer` ativa o agente de implementação.
 
 ## Próximos passos
 
@@ -61,9 +69,9 @@ npx sinapse-ai uninstall               # remove tudo
 ## Conceitos chave (em 30 segundos)
 
 - **Squad**: equipe de agentes especializados (ex: squad-design tem 15 agentes de design/UX)
-- **Agente**: persona de IA com expertise e comandos específicos (`@developer`, `@architect`, etc.)
+- **Agente**: persona de IA com especialização e comandos específicos (`@developer` no Claude Code; `$sinapse-agent developer` no Codex)
 - **Hook**: enforcement runtime que bloqueia violações da Constitution (ex: PR sem story)
-- **Constitution**: 10 artigos que governam o framework (ver `.sinapse-ai/constitution.md`)
+- **Constitution**: 11 artigos que governam o framework (ver `.sinapse-ai/constitution.md`)
 - **Story**: arquivo `.md` que documenta requisitos antes do código (Documentation-First)
 
 ---