sinapse-ai 1.25.2 → 1.25.3

package/.sinapse-ai/data/entity-registry.yaml

@@ -1,7 +1,7 @@
 metadata:
   version: 1.0.0
-  lastUpdated: '2026-07-15T08:35:27.084Z'
-  entityCount: 817
+  lastUpdated: '2026-07-15T14:30:07.448Z'
+  entityCount: 818
   checksumAlgorithm: sha256
   resolutionRate: 100
 entities:
@@ -166,8 +166,8 @@ entities:
         score: 0.7
         constraints: []
         extensionPoints: []
-      checksum: sha256:1f385982ca84a8232f3f6b1fce4257ca3971a5fd24830b5389477f9a5a8e943a
-      lastVerified: '2026-07-15T08:12:47.676Z'
+      checksum: sha256:86db5a2578b6a0b4849fde4e0f4a197a41560a3a213b247f0edd8522d857ffea
+      lastVerified: '2026-07-15T13:41:11.702Z'
     local:
       path: bin/commands/local.js
       layer: L1
@@ -276,8 +276,8 @@ entities:
         score: 0.7
         constraints: []
         extensionPoints: []
-      checksum: sha256:b51998a172a91e134330847185c078d317ed9be2da6746de3af18d209b7e08d9
-      lastVerified: '2026-07-15T08:12:47.677Z'
+      checksum: sha256:05056e197ecb29e6f63a1d86d9d77d944e3083021bf632b48a76eb4cb2223b95
+      lastVerified: '2026-07-15T13:41:11.703Z'
     command-generator:
       path: bin/lib/command-generator.js
       layer: L1
@@ -299,6 +299,7 @@ entities:
         - constants
         - squads
         - fs-utils
+        - provider-contract
       externalDeps: []
       plannedDeps: []
       lifecycle: production
@@ -306,8 +307,8 @@ entities:
         score: 0.7
         constraints: []
         extensionPoints: []
-      checksum: sha256:ed3f86d0349e4a709240728c0872bf44c3ebb2f1b8f3522c83e2f43c9b8c5647
-      lastVerified: '2026-07-15T02:37:43.455Z'
+      checksum: sha256:837f10f3ce227b1f3ff9b3d4c9e824e8928cd67ec07b0dcebd78e85468eed003
+      lastVerified: '2026-07-15T13:41:11.703Z'
     constants:
       path: bin/lib/constants.js
       layer: L1
@@ -413,7 +414,8 @@ entities:
       usedBy:
         - install
         - update
-      dependencies: []
+      dependencies:
+        - provider-contract
       externalDeps: []
       plannedDeps: []
       lifecycle: production
@@ -421,8 +423,8 @@ entities:
         score: 0.7
         constraints: []
         extensionPoints: []
-      checksum: sha256:d28b19935a9c75408df9da7430fc3ca9568bdea0cfc1ae3c01d0025ad19fc2a3
-      lastVerified: '2026-07-15T07:09:56.286Z'
+      checksum: sha256:898fbe5a00cf1bb77bc8e8a34ee40337145912374a2e809789a02d5345fdd679
+      lastVerified: '2026-07-15T14:30:07.273Z'
     header:
       path: bin/lib/header.js
       layer: L1
@@ -475,6 +477,28 @@ entities:
         extensionPoints: []
       checksum: sha256:dc7cc1109f2bbdb7b3c5927df0de2418925842bdacdc0ba82815bfa2783d0b42
       lastVerified: '2026-06-22T02:41:18.152Z'
+    provider-contract:
+      path: bin/lib/provider-contract.js
+      layer: L1
+      type: script
+      purpose: Entity at bin\lib\provider-contract.js
+      keywords:
+        - provider
+        - contract
+      usedBy:
+        - command-generator
+        - global-provider-adapters
+        - provider-parity
+      dependencies: []
+      externalDeps: []
+      plannedDeps: []
+      lifecycle: production
+      adaptability:
+        score: 0.7
+        constraints: []
+        extensionPoints: []
+      checksum: sha256:a18d271a73b2f371213af4d9503e302e9237920057afd521b723c96efd28fda0
+      lastVerified: '2026-07-15T13:41:11.704Z'
     provider-parity:
       path: bin/lib/provider-parity.js
       layer: L1
@@ -486,7 +510,8 @@ entities:
       usedBy:
         - install
         - update
-      dependencies: []
+      dependencies:
+        - provider-contract
       externalDeps: []
       plannedDeps: []
       lifecycle: production
@@ -494,8 +519,8 @@ entities:
         score: 0.7
         constraints: []
         extensionPoints: []
-      checksum: sha256:592206326a2a3c5a3d89068d9ef065d698562aef40e6096d971fb793cea11c97
-      lastVerified: '2026-07-15T08:35:26.859Z'
+      checksum: sha256:5f0ff4517425fef01683f035afef1d139aede2fe47956773a398e7c761ace42d
+      lastVerified: '2026-07-15T13:41:11.704Z'
     setup-statusline:
       path: bin/lib/setup-statusline.js
       layer: L1

package/.sinapse-ai/install-manifest.yaml

@@ -7,7 +7,7 @@
 # - SHA256 hashes for change detection
 # - File types for categorization
 #
-version: 1.25.2
+version: 1.25.3
 generator: scripts/generate-install-manifest.js
 file_count: 1156
 files:
@@ -1368,9 +1368,9 @@ files:
     type: data
     size: 9671
   - path: data/entity-registry.yaml
-    hash: sha256:ed0919b2bc3479beb4e46d3ccfbbbda66e46161c7eebc9018b9f0c8e5278d7f1
+    hash: sha256:08edc9d3cde1bf956cce462004670a3d2924a691a16c27bdfd2bf1ce4de037f8
     type: data
-    size: 559991
+    size: 560701
   - path: data/learned-patterns.yaml
     hash: sha256:1a4cd045c087b9dfd7046ff1464a9d2edb85fba77cf0b6fba14f4bb9004c741e
     type: data

package/CHANGELOG.md

@@ -1,16 +1,8 @@
-## [1.25.2](https://github.com/caioimori/sinapse-ai/compare/1.25.1...1.25.2) (2026-07-15)
+## [1.25.3](https://github.com/caioimori/sinapse-ai/compare/1.25.2...1.25.3) (2026-07-15)
 
 ### Bug Fixes
 
-* **docs:** align public Claude and Codex guidance [Story Cross-Provider] ([8c005ec](https://github.com/caioimori/sinapse-ai/commit/8c005ec4f0c5702131564cb5d3d52fee8ed85b50))
-* **docs:** close public provider guidance gaps [Story Cross-Provider] ([43f76e2](https://github.com/caioimori/sinapse-ai/commit/43f76e2b405ffae61598d8999f043a1d24ea24a5))
-
-### Documentation
-
-* harden provider backup guidance [Story cross-provider-cli-quality] ([5f4bffd](https://github.com/caioimori/sinapse-ai/commit/5f4bffd351c7ac1c0ee5cde2d7388e34409e0566))
-* **story:** normalize validation terminology [Story sinapse-only-catalog-cleanup] ([7e0ecb9](https://github.com/caioimori/sinapse-ai/commit/7e0ecb9fb01a6626ccc7c665d262c38c61196120))
-* **story:** reconcile post-release evidence [Story sinapse-only-catalog-cleanup] ([3c10c65](https://github.com/caioimori/sinapse-ai/commit/3c10c65fcfdca77ec0d1c1af6a2831af39b0adf0))
-* **story:** record SINAPSE 1.25.1 release [Story sinapse-only-catalog-cleanup] ([ba9f776](https://github.com/caioimori/sinapse-ai/commit/ba9f77607879c6efe8511e38cfeab6c71d2335c4))
+* **installer:** restore provider adapter parity ([#385](https://github.com/caioimori/sinapse-ai/issues/385)) ([4c5c9fb](https://github.com/caioimori/sinapse-ai/commit/4c5c9fb1a60e5d8610da08f25f6f01a67a85a063))
 
 # Changelog
 

package/bin/commands/install.js

@@ -560,7 +560,7 @@ function installFatalPhases({ squads, squadsDir, isUpsert, llmChoice, existing,
   // 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, totalAgents } = regenerateAgentCommands({
+  const { writtenAgents, canonicalAgents } = regenerateAgentCommands({
     sinapseHome: SINAPSE_HOME,
     commandsDir: commandStagingDir,
     squads,
@@ -571,7 +571,11 @@ function installFatalPhases({ squads, squadsDir, isUpsert, llmChoice, existing,
 
   // Phase 2b: Install global agents based on LLM choice
   const globalAdapters = deliverGlobalProviderAdapters({ llmChoice, home: HOME, commandsDir: commandStagingDir });
-  const activeAgentCount = assertProviderAdapterParity(llmChoice, globalAdapters, totalAgents);
+  const activeAgentCount = assertProviderAdapterParity(
+    llmChoice,
+    globalAdapters,
+    canonicalAgents,
+  );
   const installedAgentFilenames = new Set([...globalAdapters.claude, ...globalAdapters.codex]);
   const installedIdes = [];
   if (globalAdapters.claude.length) installedIdes.push('claude-code');

package/bin/commands/update.js

@@ -170,7 +170,7 @@ async function cmdUpdateGlobal() {
   logger.always(`\n${CYAN}Phase 2:${NC} Regenerating commands`);
   const commandStagingDir = getGlobalCommandStagingDir({ llmChoice, sinapseHome: SINAPSE_HOME, claudeCommandsDir: CLAUDE_COMMANDS_DIR });
   rmDirSync(commandStagingDir);
-  const { writtenAgents, totalAgents } = regenerateAgentCommands({
+  const { writtenAgents, canonicalAgents, totalAgents } = regenerateAgentCommands({
     sinapseHome: SINAPSE_HOME,
     commandsDir: commandStagingDir,
     squads,
@@ -181,7 +181,11 @@ async function cmdUpdateGlobal() {
 
   // Phase 2b: Install global agents based on LLM choice
   const globalAdapters = deliverGlobalProviderAdapters({ llmChoice, home: HOME, commandsDir: commandStagingDir });
-  const activeAgentCount = assertProviderAdapterParity(llmChoice, globalAdapters, totalAgents);
+  const activeAgentCount = assertProviderAdapterParity(
+    llmChoice,
+    globalAdapters,
+    canonicalAgents,
+  );
   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)`);
 

package/bin/lib/command-generator.js

@@ -20,6 +20,7 @@ const { toForwardSlash, atomicWriteFileSync } = require('./fs-utils');
 // sync-counts uses so the master-stub headline can never drift from README/persona
 // (Constitution Article VII). Fails open to 0 if the dir is unavailable.
 const CORE_AGENTS_DIR = path.join(ROOT, '.sinapse-ai', 'development', 'agents');
+const { MASTER_ALIAS_ENTRY_POINTS } = require('./provider-contract');
 
 function countCoreAgents(dir = CORE_AGENTS_DIR) {
   try {
@@ -207,7 +208,7 @@ If the task requires expertise outside this squad:
  * @param {string} [deps.commandsDir] - Target commands dir.
  * @param {Array}  deps.squads - Squad descriptors ({ name, agents, ... }).
  * @param {string} [deps.sinapseMasterDest] - Path to the installed sinapse/ master squad.
- * @returns {{ writtenAgents: Set<string>, totalAgents: number }}
+ * @returns {{ writtenAgents: Set<string>, canonicalAgents: Array<{ id: string, file: string, origin: string }>, aliasEntryPoints: string[], totalAgents: number }}
  */
 function regenerateAgentCommands(deps = {}) {
   const {
@@ -222,20 +223,21 @@ function regenerateAgentCommands(deps = {}) {
     throw new Error('regenerateAgentCommands: `squads` array is required');
   }
 
-  fs.mkdirSync(commandsDir, { recursive: true });
-
-  // Clear old commands (dir may not exist on a fresh install — guarded).
-  try {
-    for (const f of fs.readdirSync(commandsDir)) {
-      fs.unlinkSync(path.join(commandsDir, f));
-    }
-  } catch { /* dir may not exist yet */ }
-
   const sinapseBase = toForwardSlash(sinapseHome);
   const writtenAgents = new Set();
+  const catalogById = new Map();
+  const definitions = [];
+
+  function registerDefinition(definition) {
+    const previous = catalogById.get(definition.id);
+    if (previous) {
+      throw new Error(`Duplicate canonical agent ID "${definition.id}" from ${previous.origin} and ${definition.origin}`);
+    }
+    catalogById.set(definition.id, definition);
+    definitions.push(definition);
+  }
 
-  // 1. A command/subagent for EVERY agent (not only -orqx), so every specialist
-  //    is invokable via @agent and /SINAPSE:agents:agent.
+  // Inventory every canonical definition before clearing or writing commands.
   for (const squad of squads) {
     const squadPath = `${sinapseBase}/${squad.name}`;
     const agentsDir = path.join(sinapseHome, squad.name, 'agents');
@@ -244,10 +246,14 @@ function regenerateAgentCommands(deps = {}) {
     const squadAgents = fs.readdirSync(agentsDir).filter(f => f.endsWith('.md'));
     for (const file of squadAgents) {
       const agentId = file.replace('.md', '');
-      const meta = extractAgentMeta(path.join(agentsDir, file));
-      const cmdContent = generateCommandMd(agentId, meta.name, meta.icon, squad.name, squadPath, file);
-      atomicWriteFileSync(path.join(commandsDir, `${agentId}.md`), cmdContent);
-      writtenAgents.add(file);
+      registerDefinition({
+        id: agentId,
+        file,
+        origin: path.join(agentsDir, file),
+        squadName: squad.name,
+        squadPath,
+        hasManifest: true,
+      });
     }
   }
 
@@ -257,29 +263,37 @@ function regenerateAgentCommands(deps = {}) {
   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;
+      if (file === 'README.md' || file === 'MEMORY.md' || file.startsWith('_')) 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);
+      registerDefinition({
+        id: agentId,
+        file,
+        origin: path.join(coreAgentsDir, file),
+        squadName: 'core',
+        squadPath: coreBase,
+        hasManifest: false,
+      });
     }
   }
 
-  // 2. Commands for sinapse/ master squad agents.
-  if (fs.existsSync(sinapseMasterDest)) {
-    const masterAgentsDir = path.join(sinapseMasterDest, 'agents');
-    if (fs.existsSync(masterAgentsDir)) {
-      for (const file of fs.readdirSync(masterAgentsDir).filter(f => f.endsWith('.md'))) {
-        if (writtenAgents.has(file)) continue;
-        const agentId = file.replace('.md', '');
-        const meta = extractAgentMeta(path.join(masterAgentsDir, file));
-        const squadPath = `${sinapseBase}/sinapse`;
-        const cmdContent = generateCommandMd(agentId, meta.name, meta.icon, 'sinapse', squadPath, file);
-        atomicWriteFileSync(path.join(commandsDir, `${agentId}.md`), cmdContent);
-        writtenAgents.add(file);
-      }
-    }
+  fs.mkdirSync(commandsDir, { recursive: true });
+  for (const file of fs.readdirSync(commandsDir)) {
+    fs.unlinkSync(path.join(commandsDir, file));
+  }
+
+  for (const definition of definitions) {
+    const meta = extractAgentMeta(definition.origin);
+    const cmdContent = generateCommandMd(
+      definition.id,
+      meta.name,
+      meta.icon,
+      definition.squadName,
+      definition.squadPath,
+      definition.file,
+      { hasManifest: definition.hasManifest },
+    );
+    atomicWriteFileSync(path.join(commandsDir, definition.file), cmdContent);
+    writtenAgents.add(definition.file);
   }
 
   // 3. Master entry points (@sinapse, @snps, @sinapse-orqx, @snps-orqx) → rich
@@ -301,7 +315,16 @@ function regenerateAgentCommands(deps = {}) {
     }
   }
 
-  return { writtenAgents, totalAgents: writtenAgents.size };
+  const aliasEntryPoints = [...MASTER_ALIAS_ENTRY_POINTS]
+    .filter((id) => writtenAgents.has(`${id}.md`));
+  const canonicalAgents = definitions.map(({ id, file, origin }) => ({ id, file, origin }));
+
+  return {
+    writtenAgents,
+    canonicalAgents,
+    aliasEntryPoints,
+    totalAgents: canonicalAgents.length,
+  };
 }
 
 module.exports = {
@@ -309,4 +332,5 @@ module.exports = {
   generateMasterStub,
   regenerateAgentCommands,
   countCoreAgents,
+  MASTER_ALIAS_ENTRY_POINTS,
 };

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sinapse-ai",
-  "version": "1.25.2",
+  "version": "1.25.3",
   "description": "SINAPSE AI: Framework de orquestracao de IA — 17 squads, 172 agentes especializados",
   "bin": {
     "sinapse": "bin/sinapse.js",