sinapse-ai 1.24.0 → 1.25.1

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,8 @@ const {
   generateCommandMd,
   regenerateAgentCommands,
 } = require('../lib/command-generator');
+const { deliverGlobalProviderAdapters, getGlobalCommandStagingDir } = require('../lib/global-provider-adapters');
+const { assertProviderAdapterParity } = require('../lib/provider-parity');
 // 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.
@@ -59,6 +65,11 @@ async function cmdInstallGlobal(opts = {}) {
   // Story 10.20 — Upsert detection
   const force = Boolean(opts.force);
   const reconfigure = Boolean(opts.reconfigure);
+  const globalOnly = Boolean(opts.globalOnly);
+  const requestedLlm = opts.llm || null;
+  if (requestedLlm && !['claude-code', 'codex', 'both'].includes(requestedLlm)) {
+    throw new Error(`Invalid --llm value: ${requestedLlm}. Use claude-code, codex, or both.`);
+  }
   const existing = force ? { upsert: false } : detectExistingInstall();
   const isUpsert = existing.upsert;
 
@@ -121,7 +132,9 @@ async function cmdInstallGlobal(opts = {}) {
   // Story 10.35: --reconfigure forces prompt even in upsert mode
   let llmChoice;
   let llmWasReused = false;
-  if (isUpsert && !reconfigure && existing.llm) {
+  if (requestedLlm) {
+    llmChoice = requestedLlm;
+  } else if (isUpsert && !reconfigure && existing.llm) {
     llmChoice = existing.llm;
     llmWasReused = true;
     const ideLabel = Array.isArray(llmChoice) ? llmChoice.join(', ') : String(llmChoice);
@@ -217,7 +230,7 @@ async function cmdInstallGlobal(opts = {}) {
   // project-wizard WARN must NOT revert an otherwise-good global install.
   const tx = createInstallTransaction();
   const txPaths = buildTransactionPaths(llmChoice);
-  const { writtenAgents, totalAgents, totalDelta, squadsRefreshed, squadsAdded, meta } =
+  const { activeAgentCount, totalDelta, squadsRefreshed, squadsAdded, meta } =
     await runFatalPhasesTransactional({
       tx,
       isUpsert,
@@ -264,7 +277,10 @@ async function cmdInstallGlobal(opts = {}) {
 
   // Phase 8: Install project-local files (.sinapse-ai/, .claude/, .env)
   logger.always(`\n${CYAN}Phase 8:${NC} Installing project files in current directory`);
-  try {
+  const skipProjectInstall = globalOnly || path.resolve(process.cwd()) === path.resolve(ROOT);
+  if (skipProjectInstall) {
+    logger.always(`  ${YELLOW}SKIP${NC} Project files (${globalOnly ? '--global-only' : 'source checkout detected'})`);
+  } else try {
     const wizardPath = path.join(ROOT, 'packages', 'installer', 'src', 'wizard', 'index.js');
     if (fs.existsSync(wizardPath)) {
       const { runWizard: executeWizard } = require(wizardPath);
@@ -300,19 +316,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 +331,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'));
 
@@ -347,12 +359,17 @@ async function cmdInstallGlobal(opts = {}) {
     logger.always(`${YELLOW}══════════════════════════════════════════════════════════════${NC}`);
   }
   logger.always('');
-  logger.always(`  ${BOLD}${squads.length} squads${NC} | ${BOLD}${totalAgents} agents${NC} | ${BOLD}${writtenAgents.size} command files${NC}`);
+  logger.always(`  ${BOLD}${squads.length} squads${NC} | ${BOLD}${activeAgentCount} agents${NC} | ${BOLD}${activeAgentCount} native adapters${NC}`);
   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 +413,13 @@ 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'));
+  // A Claude-only provider switch removes stale Codex aliases during the fatal
+  // phases, so that cleanup must be covered by the same upgrade rollback.
+  if (llmChoice === 'claude-code') dirs.push(path.join(HOME, '.agents', 'skills'));
+  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
@@ -469,7 +492,7 @@ async function runFatalPhasesTransactional({ tx, isUpsert, paths, runPhases, onR
  * @param {string} ctx.llmChoice
  * @param {Object} ctx.existing  - detectExistingInstall() result
  * @param {Object} ctx.logger
- * @returns {{ writtenAgents: Set, totalAgents: number, totalDelta: Object, squadsRefreshed: number, squadsAdded: number, meta: Object }}
+ * @returns {{ writtenAgents: Set, activeAgentCount: number, totalDelta: Object, squadsRefreshed: number, squadsAdded: number, meta: Object }}
  */
 function installFatalPhases({ squads, squadsDir, isUpsert, llmChoice, existing, logger }) {
   // Phase 1: Copy squads to ~/.sinapse/
@@ -477,7 +500,6 @@ function installFatalPhases({ squads, squadsDir, isUpsert, llmChoice, existing,
   fs.mkdirSync(SINAPSE_HOME, { recursive: true });
 
   const squadsSrcBase = fs.existsSync(squadsDir) ? squadsDir : ROOT;
-  let totalAgents = 0;
   const totalDelta = { added: 0, updated: 0, unchanged: 0, removed: 0 };
   let squadsRefreshed = 0;
   let squadsAdded = 0;
@@ -498,7 +520,6 @@ function installFatalPhases({ squads, squadsDir, isUpsert, llmChoice, existing,
       copyDirSync(src, dest);
       logger.always(`  ${GREEN}OK${NC} ${squad.name} (${squad.agents} agents)`);
     }
-    totalAgents += squad.agents;
   }
 
   // Copy sinapse/ orqx squad
@@ -516,47 +537,52 @@ function installFatalPhases({ squads, squadsDir, isUpsert, llmChoice, existing,
       copyDirSync(sinapseMasterSrc, sinapseMasterDest);
     }
     const masterAgents = getAgentFiles(sinapseMasterDest).length;
-    totalAgents += masterAgents;
     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;
+    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 { writtenAgents } = regenerateAgentCommands({
+  const commandStagingDir = getGlobalCommandStagingDir({ llmChoice, sinapseHome: SINAPSE_HOME, claudeCommandsDir: CLAUDE_COMMANDS_DIR });
+  const { writtenAgents, totalAgents } = 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 activeAgentCount = assertProviderAdapterParity(llmChoice, globalAdapters, totalAgents);
+  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, { providers: ['codex'] });
   recordInstalledAgents(installedAgentFilenames, installedIdes);
 
   // Phase 3: Generate squad-awareness.md
@@ -580,8 +606,8 @@ function installFatalPhases({ squads, squadsDir, isUpsert, llmChoice, existing,
       ? existing.prevMeta.installedAt
       : nowIso,
     squads: squads.length,
-    agents: totalAgents,
-    commands: writtenAgents.size,
+    agents: activeAgentCount,
+    commands: activeAgentCount,
     llm: llmChoice,
     platform: process.platform,
   };
@@ -590,7 +616,7 @@ function installFatalPhases({ squads, squadsDir, isUpsert, llmChoice, existing,
   }
   atomicWriteFileSync(path.join(SINAPSE_HOME, 'metadata.json'), JSON.stringify(meta, null, 2));
 
-  return { writtenAgents, totalAgents, totalDelta, squadsRefreshed, squadsAdded, meta };
+  return { writtenAgents, activeAgentCount, totalDelta, squadsRefreshed, squadsAdded, meta };
 }
 
 function generateSquadAwareness(sinapseDir, squads) {

package/bin/commands/status.js

@@ -5,9 +5,9 @@ const fs = require('fs');
 const path = require('path');
 const { getLogger } = require('../../.sinapse-ai/core/logger');
 const {
+  HOME,
   ROOT,
   SINAPSE_HOME,
-  CLAUDE_COMMANDS_DIR,
   BIN_DIR,
   CYAN,
   GREEN,
@@ -18,12 +18,13 @@ const {
 } = require('../lib/constants');
 const { header } = require('../lib/header');
 const { getSquads } = require('../lib/squads');
+const { hasManagedInstalledAgents } = require('./uninstall');
 
 function verifyInstall() {
   const logger = getLogger();
   const checks = [
     [fs.existsSync(SINAPSE_HOME), `${getSquads(SINAPSE_HOME).length} squads in ~/.sinapse/`],
-    [fs.existsSync(CLAUDE_COMMANDS_DIR), 'Commands in ~/.claude/commands/SINAPSE/agents/'],
+    [hasManagedInstalledAgents(HOME), 'Native provider agents installed'],
     [fs.existsSync(path.join(BIN_DIR, 'sinapse')), 'Launcher at ~/bin/sinapse'],
     [fs.existsSync(path.join(SINAPSE_HOME, '.claude', 'rules', 'squad-awareness.md')), 'squad-awareness.md'],
   ];
@@ -52,7 +53,7 @@ function cmdList() {
 
   logger.always('');
   logger.always(`  ${BOLD}Total: ${GREEN}${totalAgents} agents${NC} | ${YELLOW}${totalTasks} tasks${NC}`);
-  logger.always(`  ${BOLD}Invoke: ${CYAN}/SINAPSE:agents:{agent-id}${NC}`);
+  logger.always(`  ${BOLD}Invoke: ${CYAN}$sinapse-agent <agent-id>${NC}`);
   logger.always('');
 }
 

package/bin/commands/uninstall.js

@@ -3,6 +3,8 @@
 
 const fs = require('fs');
 const path = require('path');
+const crypto = require('crypto');
+const legacyClaudeCommandHashes = require('../../packages/installer/src/migrations/legacy-claude-agent-command-hashes.json');
 const { getLogger } = require('../../.sinapse-ai/core/logger');
 const {
   HOME,
@@ -58,22 +60,61 @@ async function removeGitHooksConfig(projectDir = process.cwd()) {
 // and removes only those files (preserving anything the user added by hand).
 const INSTALLED_AGENTS_MANIFEST = path.join(SINAPSE_HOME, 'installed-agents.json');
 
-function recordInstalledAgents(filenames, ides) {
+function installedAgentsManifestPath(home = HOME) {
+  return home === HOME
+    ? INSTALLED_AGENTS_MANIFEST
+    : path.join(home, '.sinapse', 'installed-agents.json');
+}
+
+function digestFile(filePath) {
   try {
-    fs.mkdirSync(SINAPSE_HOME, { recursive: true });
-    fs.writeFileSync(INSTALLED_AGENTS_MANIFEST, JSON.stringify({
-      version: 1,
+    return crypto.createHash('sha256').update(fs.readFileSync(filePath)).digest('hex');
+  } catch {
+    return null;
+  }
+}
+
+function providerAgentPath(home, provider, filename) {
+  const providerDir = provider === 'codex'
+    ? path.join(home, '.codex', 'agents')
+    : path.join(home, '.claude', 'agents');
+  return path.join(providerDir, filename);
+}
+
+function inferProviderFromAgentDir(dir) {
+  const normalized = path.resolve(dir).replace(/\\/g, '/').toLowerCase();
+  if (normalized.includes('/.codex/agents')) return 'codex';
+  if (normalized.includes('/.claude/agents')) return 'claude-code';
+  return null;
+}
+
+function recordInstalledAgents(filenames, ides, home = HOME) {
+  try {
+    const manifestPath = installedAgentsManifestPath(home);
+    fs.mkdirSync(path.dirname(manifestPath), { recursive: true });
+    const artifacts = [...filenames].map((filename) => {
+      const provider = filename.endsWith('.toml') ? 'codex' : 'claude-code';
+      return {
+        provider,
+        filename,
+        sha256: digestFile(providerAgentPath(home, provider, filename)),
+      };
+    });
+    fs.writeFileSync(manifestPath, JSON.stringify({
+      version: 2,
       timestamp: new Date().toISOString(),
       ides,
       filenames: [...filenames].sort(),
+      artifacts: artifacts.sort((a, b) => `${a.provider}/${a.filename}`.localeCompare(`${b.provider}/${b.filename}`)),
     }, null, 2));
   } catch { /* non-critical */ }
 }
 
-function readInstalledAgentsManifest() {
+function readInstalledAgentsManifest(home = HOME) {
   try {
-    if (!fs.existsSync(INSTALLED_AGENTS_MANIFEST)) return null;
-    const raw = fs.readFileSync(INSTALLED_AGENTS_MANIFEST, 'utf8');
+    const manifestPath = installedAgentsManifestPath(home);
+    if (!fs.existsSync(manifestPath)) return null;
+    const raw = fs.readFileSync(manifestPath, 'utf8');
     const parsed = JSON.parse(raw);
     if (!parsed || !Array.isArray(parsed.filenames)) return null;
     return parsed;
@@ -82,35 +123,39 @@ function readInstalledAgentsManifest() {
   }
 }
 
-function removeInstalledAgentsFrom(dir) {
+function removeInstalledAgentsFrom(dir, manifestOverride = null) {
   if (!fs.existsSync(dir)) return { removed: 0, existed: false };
   let removed = 0;
+  const manifest = manifestOverride || readInstalledAgentsManifest();
+  const provider = inferProviderFromAgentDir(dir);
   let candidates;
 
-  const manifest = readInstalledAgentsManifest();
-  if (manifest && Array.isArray(manifest.filenames)) {
-    // Manifest path — surgical removal of exactly what install wrote.
-    candidates = manifest.filenames;
+  if (manifest?.version >= 2 && Array.isArray(manifest.artifacts)) {
+    candidates = manifest.artifacts.filter((artifact) => {
+      if (!artifact || typeof artifact.filename !== 'string') return false;
+      return provider ? artifact.provider === provider : true;
+    });
   } else {
-    // Backward-compat fallback for installs predating the manifest
-    // (rc.10 and earlier). Heuristic: SINAPSE-authored files end in
-    // `-orqx.md`, OR start with `name: sinapse-` in their frontmatter.
-    try {
-      candidates = fs.readdirSync(dir).filter((f) => {
-        if (!f.endsWith('.md')) return false;
-        if (/-orqx\.md$/.test(f)) return true;
-        try {
-          const head = fs.readFileSync(path.join(dir, f), 'utf8').slice(0, 600);
-          return /^\s*name:\s*sinapse-/im.test(head);
-        } catch { return false; }
-      });
-    } catch { return { removed: 0, existed: true }; }
+    // Legacy manifests did not record provider or digests. Ownership must be
+    // proven by the marker in the actual provider directory before deletion.
+    const filenames = Array.isArray(manifest?.filenames)
+      ? manifest.filenames
+      : fs.readdirSync(dir);
+    candidates = filenames.map((filename) => ({ filename, sha256: null, legacy: true }));
   }
 
-  for (const f of candidates) {
-    const filepath = path.join(dir, f);
+  for (const { filename, sha256, legacy } of candidates) {
+    const filepath = path.join(dir, filename);
     if (!fs.existsSync(filepath)) continue;
     try {
+      if (sha256) {
+        if (digestFile(filepath) !== sha256) continue;
+      } else {
+        // A v2 entry without a digest does not prove the installer wrote it.
+        if (!legacy) continue;
+        const content = fs.readFileSync(filepath, 'utf8');
+        if (!content.includes('SINAPSE-MANAGED:global-agent')) continue;
+      }
       fs.unlinkSync(filepath);
       removed++;
     } catch { /* best-effort */ }
@@ -125,6 +170,168 @@ function removeOrqxAgentsFrom(dir) {
   return removeInstalledAgentsFrom(dir);
 }
 
+const MANAGED_GLOBAL_SKILL_IDS = ['snps', 'sinapse', 'snps-orqx', 'sinapse-orqx', 'sinapse-agent'];
+const MANAGED_GLOBAL_SKILL_MARKER = 'SINAPSE-MANAGED:global-skill';
+
+function removeManagedGlobalSkills(home = HOME, options = {}) {
+  let removed = 0;
+  const providers = options.providers || ['codex', 'claude-code'];
+  const skillRoots = [];
+  if (providers.includes('codex')) skillRoots.push(path.join(home, '.agents', 'skills'));
+  if (providers.includes('claude-code')) skillRoots.push(path.join(home, '.claude', 'skills'));
+  for (const skillsRoot of skillRoots) {
+    for (const skillId of MANAGED_GLOBAL_SKILL_IDS) {
+      const skillDir = path.join(skillsRoot, 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(home);
+  const desired = new Set(desiredFilenames);
+  const desiredByProvider = {
+    'claude-code': new Set([...desired].filter((name) => name.endsWith('.md'))),
+    codex: new Set([...desired].filter((name) => name.endsWith('.toml'))),
+  };
+  let removed = 0;
+  const legacyArtifacts = (manifest?.filenames || []).map((filename) => ({
+    provider: filename.endsWith('.toml') ? 'codex' : 'claude-code',
+    filename,
+    sha256: null,
+  }));
+  const manifestArtifacts = Array.isArray(manifest?.artifacts) ? manifest.artifacts : legacyArtifacts;
+  const manifestOwned = new Set(manifestArtifacts.map(({ provider, filename }) => `${provider}/${filename}`));
+  const versionedOwned = new Set(Array.isArray(manifest?.artifacts)
+    ? manifestArtifacts.map(({ provider, filename }) => `${provider}/${filename}`)
+    : []);
+  const managedMarker = 'SINAPSE-MANAGED:global-agent';
+  for (const { provider, filename, sha256 } of manifestArtifacts) {
+    if (!desiredByProvider[provider] || desiredByProvider[provider].has(filename)) continue;
+    const filepath = providerAgentPath(home, provider, filename);
+    if (!fs.existsSync(filepath)) continue;
+    try {
+      const content = fs.readFileSync(filepath, 'utf8');
+      const digestMatches = Boolean(sha256) && digestFile(filepath) === sha256;
+      const legacyMarkerMatches = !Array.isArray(manifest?.artifacts) && content.includes(managedMarker);
+      if (sha256 ? !digestMatches : !legacyMarkerMatches) continue;
+      fs.unlinkSync(filepath);
+      removed++;
+    } catch { /* best-effort */ }
+  }
+
+  for (const [provider, providerDir, extension] of [
+    ['claude-code', path.join(home, '.claude', 'agents'), '.md'],
+    ['codex', path.join(home, '.codex', 'agents'), '.toml'],
+    ['codex', path.join(home, '.codex', 'agents'), '.md'],
+  ]) {
+    if (!fs.existsSync(providerDir)) continue;
+    for (const filename of fs.readdirSync(providerDir).filter((name) => name.endsWith(extension))) {
+      if (desiredByProvider[provider].has(filename)) continue;
+      const filepath = path.join(providerDir, filename);
+      try {
+        const content = fs.readFileSync(filepath, 'utf8');
+        if (versionedOwned.has(`${provider}/${filename}`)) continue;
+        if (!manifestOwned.has(`${provider}/${filename}`) && !content.includes(managedMarker)) continue;
+        // A manifest entry alone is not proof of current ownership: users can
+        // replace a formerly managed file. Only marked artifacts reach this
+        // sweep; exact recorded content was handled by the digest path above.
+        if (!content.includes(managedMarker)) continue;
+        fs.unlinkSync(filepath);
+        removed++;
+      } catch { /* best-effort */ }
+    }
+  }
+
+  const legacyCommands = path.join(home, '.claude', 'commands', 'SINAPSE', 'agents');
+  let legacyCommandDirectoryRemoved = false;
+  let legacyCommandsRemoved = 0;
+  let legacyCommandsPreserved = 0;
+  if (fs.existsSync(legacyCommands)) {
+    for (const entry of fs.readdirSync(legacyCommands, { withFileTypes: true })) {
+      const filePath = path.join(legacyCommands, entry.name);
+      if (!entry.isFile()) {
+        legacyCommandsPreserved++;
+        continue;
+      }
+      try {
+        const content = fs.readFileSync(filePath);
+        const digest = crypto.createHash('sha256').update(content).digest('hex');
+        const knownHashes = legacyClaudeCommandHashes.files[entry.name] || [];
+        if (!knownHashes.includes(digest)) {
+          legacyCommandsPreserved++;
+          continue;
+        }
+        fs.unlinkSync(filePath);
+        legacyCommandsRemoved++;
+      } catch {
+        legacyCommandsPreserved++;
+      }
+    }
+    try {
+      if (fs.readdirSync(legacyCommands).length === 0) {
+        fs.rmdirSync(legacyCommands);
+        legacyCommandDirectoryRemoved = true;
+      }
+    } catch { /* best-effort */ }
+  }
+  return {
+    removed,
+    legacyCommandDirectoryRemoved,
+    legacyCommandsRemoved,
+    legacyCommandsPreserved,
+  };
+}
+
+function hasManagedInstalledAgents(home = HOME) {
+  const manifest = readInstalledAgentsManifest(home);
+  if (!manifest) {
+    for (const [providerDir, extensions] of [
+      [path.join(home, '.claude', 'agents'), new Set(['.md'])],
+      [path.join(home, '.codex', 'agents'), new Set(['.toml', '.md'])],
+    ]) {
+      try {
+        for (const filename of fs.readdirSync(providerDir)) {
+          if (!extensions.has(path.extname(filename))) continue;
+          try {
+            const content = fs.readFileSync(path.join(providerDir, filename), 'utf8');
+            if (content.includes('SINAPSE-MANAGED:global-agent')) return true;
+          } catch { /* unreadable or non-regular entries are not evidence */ }
+        }
+      } catch { /* missing or unreadable provider dir */ }
+    }
+    return false;
+  }
+  const versioned = Array.isArray(manifest?.artifacts);
+  const artifacts = versioned
+    ? manifest.artifacts
+    : (manifest?.filenames || []).map((filename) => ({
+      provider: filename.endsWith('.toml') ? 'codex' : 'claude-code',
+      filename,
+      sha256: null,
+    }));
+  return artifacts.some(({ provider, filename, sha256 }) => {
+    const filePath = providerAgentPath(home, provider, filename);
+    try {
+      const content = fs.readFileSync(filePath, 'utf8');
+      return sha256
+        ? digestFile(filePath) === sha256
+        : !versioned && content.includes('SINAPSE-MANAGED:global-agent');
+    } catch {
+      return false;
+    }
+  });
+}
+
 // 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 +383,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 +418,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 +427,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 +437,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 +474,9 @@ module.exports = {
   readInstalledAgentsManifest,
   removeInstalledAgentsFrom,
   removeOrqxAgentsFrom,
+  removeManagedGlobalSkills,
+  reconcileInstalledAgents,
+  hasManagedInstalledAgents,
   cleanClaudeSettingsJson,
   removeGitHooksConfig,
   INSTALLED_AGENTS_MANIFEST,