@phnx-labs/agents-cli 1.18.1 → 1.18.3

package/dist/lib/plugins.js

@@ -14,6 +14,7 @@ import { execSync } from 'child_process';
 import { getPluginsDir, getTrashPluginsDir } from './state.js';
 import { listInstalledVersions, getVersionHomePath } from './versions.js';
 import { AGENTS, PLUGINS_CAPABLE_AGENTS } from './agents.js';
+import { copyPluginToMarketplace, syncMarketplaceManifest, registerMarketplace, unregisterMarketplace, enablePluginInSettings, disablePluginInSettings, removePluginFromMarketplace, marketplaceIsEmpty, removeEmptyMarketplaceDir, isInstalledInMarketplace, marketplaceRoot, } from './plugin-marketplace.js';
 const PLUGIN_MANIFEST_DIR = '.claude-plugin';
 const PLUGIN_MANIFEST_FILE = 'plugin.json';
 const USER_CONFIG_FILE = '.user-config.json';
@@ -51,6 +52,9 @@ export function buildDiscoveredPlugin(pluginRoot, manifest) {
         commands: discoverPluginCommands(pluginRoot),
         agentDefs: discoverPluginAgentDefs(pluginRoot),
         bin: discoverPluginBin(pluginRoot),
+        mcpServers: discoverPluginMcpServers(pluginRoot),
+        lspServers: discoverPluginLspServers(pluginRoot),
+        monitors: discoverPluginMonitors(pluginRoot),
         hasMcp: fs.existsSync(path.join(pluginRoot, '.mcp.json')),
         hasSettings: pluginHasNonPermissionSettings(pluginRoot),
     };
@@ -149,6 +153,47 @@ export function discoverPluginBin(pluginRoot) {
         return [];
     return fs.readdirSync(binDir).filter(f => !f.startsWith('.'));
 }
+/** Discover MCP server names from .mcp.json at the plugin root. */
+export function discoverPluginMcpServers(pluginRoot) {
+    const mcpFile = path.join(pluginRoot, '.mcp.json');
+    if (!fs.existsSync(mcpFile))
+        return [];
+    try {
+        const parsed = JSON.parse(fs.readFileSync(mcpFile, 'utf-8'));
+        return parsed.mcpServers ? Object.keys(parsed.mcpServers) : [];
+    }
+    catch {
+        return [];
+    }
+}
+/** Discover LSP server keys from .lsp.json at the plugin root. */
+export function discoverPluginLspServers(pluginRoot) {
+    const lspFile = path.join(pluginRoot, '.lsp.json');
+    if (!fs.existsSync(lspFile))
+        return [];
+    try {
+        const parsed = JSON.parse(fs.readFileSync(lspFile, 'utf-8'));
+        return Object.keys(parsed);
+    }
+    catch {
+        return [];
+    }
+}
+/** Discover monitor names from monitors/monitors.json. */
+export function discoverPluginMonitors(pluginRoot) {
+    const monitorsFile = path.join(pluginRoot, 'monitors', 'monitors.json');
+    if (!fs.existsSync(monitorsFile))
+        return [];
+    try {
+        const parsed = JSON.parse(fs.readFileSync(monitorsFile, 'utf-8'));
+        if (!Array.isArray(parsed))
+            return [];
+        return parsed.map(m => m.name).filter((n) => typeof n === 'string');
+    }
+    catch {
+        return [];
+    }
+}
 /** Return true if settings.json contains non-permission keys worth merging. */
 function pluginHasNonPermissionSettings(pluginRoot) {
     const settingsPath = path.join(pluginRoot, 'settings.json');
@@ -221,15 +266,18 @@ export function checkPluginDependencies(manifest) {
 /**
  * Sync a plugin to a specific agent version's home directory.
  *
- * For Claude:
- *   1. Copy plugin skills into version's skills dir (prefixed: pluginName--skillName)
- *   2. Copy plugin commands into version's commands dir (prefixed: pluginName--cmdName.md)
- *   3. Copy plugin agent defs into version's agents dir (prefixed: pluginName--agentName.md)
- *   4. Copy plugin bin/ into version home plugin-bin/<pluginName>/, note path in settings
- *   5. Read hooks/hooks.json, expand vars, merge into settings.json hooks
- *   6. Read .mcp.json, expand vars, merge mcpServers into settings.json
- *   7. Read settings.json, merge non-permission keys non-destructively into settings.json
- *   8. Read settings.json permissions, expand vars, merge into settings.json
+ * For plugins-capable agents (claude, openclaw):
+ *   1. Copy plugin source into <versionHome>/.<agent>/plugins/marketplaces/agents-cli/plugins/<name>/
+ *   2. Pre-expand ${user_config.*} variables in copied text files (Claude doesn't know this var).
+ *   3. (Re-)synthesize the marketplace.json catalog from the installed plugins.
+ *   4. Register the synthetic marketplace in known_marketplaces.json.
+ *   5. Mark <plugin>@agents-cli enabled in settings.json#enabledPlugins.
+ *   6. Migrate (remove) legacy dual-dash skills/commands/agents/bin/hooks/mcp entries.
+ *
+ * Claude/OpenClaw natively handle the plugin's skills, commands, agents, hooks,
+ * MCP servers, bin/, settings.json, and permissions once the plugin lives at the
+ * native install path and is marked enabled — see
+ * https://code.claude.com/docs/en/plugins.
  */
 export function syncPluginToVersion(plugin, agent, versionHome) {
     const result = {
@@ -247,522 +295,212 @@ export function syncPluginToVersion(plugin, agent, versionHome) {
         return result;
     }
     const userConfig = loadUserConfig(plugin.name);
-    // 1. Sync skills
-    result.skills = syncPluginSkills(plugin, agent, versionHome, userConfig);
-    // 2. Sync commands (Claude + compatible agents only)
-    if (agent === 'claude' || agent === 'openclaw') {
-        result.commands = syncPluginCommands(plugin, agent, versionHome, userConfig);
-    }
-    // 3. Sync agent defs (Claude only)
-    if (agent === 'claude') {
-        result.agentDefs = syncPluginAgentDefs(plugin, agent, versionHome, userConfig);
-    }
-    // 4. Sync bin executables (Claude only for now)
-    if (agent === 'claude') {
-        result.bin = syncPluginBin(plugin, agent, versionHome);
-    }
-    // 5. Sync hooks (Claude only - uses settings.json hook registration)
-    if (agent === 'claude') {
-        result.hooks = syncPluginHooks(plugin, agent, versionHome, userConfig);
-    }
-    // 6. Sync MCP servers (Claude only)
-    if (agent === 'claude') {
-        result.mcp = syncPluginMcp(plugin, agent, versionHome, userConfig);
-    }
-    // 7. Merge non-permission settings keys non-destructively (Claude only)
-    if (agent === 'claude') {
-        result.settings = syncPluginSettings(plugin, agent, versionHome);
-    }
-    // 8. Sync permissions (Claude only - uses settings.json permissions)
-    if (agent === 'claude') {
-        result.permissions = syncPluginPermissions(plugin, agent, versionHome, userConfig);
-    }
-    result.success =
-        result.skills.length > 0 ||
-            result.commands.length > 0 ||
-            result.agentDefs.length > 0 ||
-            result.bin.length > 0 ||
-            result.hooks.length > 0 ||
-            result.mcp ||
-            result.settings ||
-            result.permissions;
+    // 1. Copy plugin to native marketplace install dir.
+    const installDir = copyPluginToMarketplace(plugin, agent, versionHome);
+    // 2. Pre-expand ${user_config.*} in the copy. Leave ${CLAUDE_PLUGIN_ROOT} /
+    //    ${CLAUDE_PLUGIN_DATA} alone — Claude expands those natively at runtime.
+    if (Object.keys(userConfig).length > 0) {
+        expandUserConfigInDir(installDir, userConfig);
+    }
+    // 3-5. Synthesize manifest, register marketplace, enable plugin.
+    syncMarketplaceManifest(agent, versionHome);
+    registerMarketplace(agent, versionHome);
+    enablePluginInSettings(plugin.name, agent, versionHome);
+    // 6. Migrate legacy dual-dash flat layout from previous versions of agents-cli.
+    migrateLegacyFlatLayout(plugin, agent, versionHome);
+    // Populate the result shape for backward-compatible callers/reporting.
+    result.skills = plugin.skills.map(s => `${plugin.name}:${s}`);
+    result.commands = plugin.commands.map(c => `${plugin.name}:${c}`);
+    result.agentDefs = plugin.agentDefs.map(a => `${plugin.name}:${a}`);
+    result.bin = plugin.bin;
+    result.hooks = plugin.hooks;
+    result.mcp = plugin.hasMcp;
+    result.settings = plugin.hasSettings;
+    result.permissions = pluginHasPermissions(plugin);
+    result.success = true;
     return result;
 }
-// ─── Individual sync functions ────────────────────────────────────────────────
-/**
- * Copy plugin skills into the version's skills directory.
- * Skills are prefixed with the plugin name: pluginName--skillName
- */
-function syncPluginSkills(plugin, agent, versionHome, userConfig) {
-    const synced = [];
-    const pluginSkillsDir = path.join(plugin.root, 'skills');
-    if (!fs.existsSync(pluginSkillsDir))
-        return synced;
-    const targetSkillsDir = path.join(versionHome, `.${agent}`, 'skills');
-    fs.mkdirSync(targetSkillsDir, { recursive: true });
-    for (const skillName of plugin.skills) {
-        const srcDir = path.join(pluginSkillsDir, skillName);
-        const fsSafeName = `${plugin.name}--${skillName}`;
-        const destDir = path.join(targetSkillsDir, fsSafeName);
-        try {
-            if (fs.existsSync(destDir)) {
-                fs.rmSync(destDir, { recursive: true, force: true });
-            }
-            copyDirWithVarExpansion(srcDir, destDir, plugin.root, plugin.name, agent, versionHome, userConfig);
-            synced.push(`${plugin.name}:${skillName}`);
-        }
-        catch {
-            // Skip on error
-        }
+function pluginHasPermissions(plugin) {
+    const settingsPath = path.join(plugin.root, 'settings.json');
+    if (!fs.existsSync(settingsPath))
+        return false;
+    try {
+        const parsed = JSON.parse(fs.readFileSync(settingsPath, 'utf-8'));
+        return !!(parsed.permissions?.allow?.length || parsed.permissions?.deny?.length);
     }
-    return synced;
-}
-/**
- * Copy plugin commands into the version's commands directory.
- * Commands are namespaced: pluginName--commandName.md
- */
-function syncPluginCommands(plugin, agent, versionHome, userConfig) {
-    const synced = [];
-    const pluginCommandsDir = path.join(plugin.root, 'commands');
-    if (!fs.existsSync(pluginCommandsDir) || plugin.commands.length === 0)
-        return synced;
-    const agentConfig = AGENTS[agent];
-    const commandsTarget = path.join(versionHome, `.${agent}`, agentConfig.commandsSubdir);
-    fs.mkdirSync(commandsTarget, { recursive: true });
-    for (const cmdName of plugin.commands) {
-        const srcFile = path.join(pluginCommandsDir, `${cmdName}.md`);
-        if (!fs.existsSync(srcFile))
-            continue;
-        const destName = `${plugin.name}--${cmdName}.md`;
-        const destFile = path.join(commandsTarget, destName);
-        try {
-            let content = fs.readFileSync(srcFile, 'utf-8');
-            content = expandPluginVars(content, plugin.root, plugin.name, agent, versionHome, userConfig);
-            fs.writeFileSync(destFile, content, 'utf-8');
-            synced.push(`${plugin.name}:${cmdName}`);
-        }
-        catch {
-            // Skip on error
-        }
+    catch {
+        return false;
     }
-    return synced;
 }
 /**
- * Copy plugin agent definitions into the version's agents directory.
- * Agent defs are namespaced: pluginName--agentName.md
+ * Walk a directory and replace ${user_config.*} placeholders in text files.
+ * Leaves all other variables (${CLAUDE_PLUGIN_ROOT}, ${CLAUDE_PLUGIN_DATA}) alone.
  */
-function syncPluginAgentDefs(plugin, agent, versionHome, userConfig) {
-    const synced = [];
-    const pluginAgentsDir = path.join(plugin.root, 'agents');
-    if (!fs.existsSync(pluginAgentsDir) || plugin.agentDefs.length === 0)
-        return synced;
-    const agentsTarget = path.join(versionHome, `.${agent}`, 'agents');
-    fs.mkdirSync(agentsTarget, { recursive: true });
-    for (const agentDefName of plugin.agentDefs) {
-        const srcFile = path.join(pluginAgentsDir, `${agentDefName}.md`);
-        if (!fs.existsSync(srcFile))
+function expandUserConfigInDir(dir, userConfig) {
+    const textExtensions = new Set(['.md', '.json', '.sh', '.py', '.js', '.ts', '.yaml', '.yml', '.toml', '.txt']);
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        const full = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            expandUserConfigInDir(full, userConfig);
             continue;
-        const destName = `${plugin.name}--${agentDefName}.md`;
-        const destFile = path.join(agentsTarget, destName);
-        try {
-            let content = fs.readFileSync(srcFile, 'utf-8');
-            content = expandPluginVars(content, plugin.root, plugin.name, agent, versionHome, userConfig);
-            fs.writeFileSync(destFile, content, 'utf-8');
-            synced.push(`${plugin.name}:${agentDefName}`);
-        }
-        catch {
-            // Skip on error
         }
-    }
-    return synced;
-}
-/**
- * Copy plugin bin executables into the version home plugin-bin/<pluginName>/ directory.
- * Records the bin path in settings.json under pluginBinPaths so callers can add it to PATH.
- */
-function syncPluginBin(plugin, agent, versionHome) {
-    const synced = [];
-    const pluginBinDir = path.join(plugin.root, 'bin');
-    if (!fs.existsSync(pluginBinDir) || plugin.bin.length === 0)
-        return synced;
-    const targetBinDir = path.join(versionHome, `.${agent}`, 'plugin-bin', plugin.name);
-    fs.mkdirSync(targetBinDir, { recursive: true });
-    for (const binFile of plugin.bin) {
-        const srcFile = path.join(pluginBinDir, binFile);
-        if (!fs.existsSync(srcFile))
+        if (!textExtensions.has(path.extname(entry.name).toLowerCase()))
             continue;
-        const destFile = path.join(targetBinDir, binFile);
         try {
-            fs.copyFileSync(srcFile, destFile);
-            const stat = fs.statSync(srcFile);
-            fs.chmodSync(destFile, stat.mode | 0o111);
-            synced.push(binFile);
-        }
-        catch {
-            // Skip on error
-        }
-    }
-    if (synced.length === 0)
-        return synced;
-    // Note the bin path in settings.json so the calling shim can add it to PATH.
-    const configDir = path.join(versionHome, `.${agent}`);
-    const settingsPath = path.join(configDir, 'settings.json');
-    let settings = {};
-    if (fs.existsSync(settingsPath)) {
-        try {
-            settings = JSON.parse(fs.readFileSync(settingsPath, 'utf-8'));
+            const content = fs.readFileSync(full, 'utf-8');
+            if (!content.includes('${user_config.'))
+                continue;
+            const expanded = content.replace(/\$\{user_config\.([^}]+)\}/g, (_, key) => userConfig[key] ?? '');
+            if (expanded !== content) {
+                fs.writeFileSync(full, expanded, 'utf-8');
+            }
         }
-        catch { /* start fresh */ }
-    }
-    if (!Array.isArray(settings.pluginBinPaths)) {
-        settings.pluginBinPaths = [];
+        catch { /* skip unreadable */ }
     }
-    const binPaths = settings.pluginBinPaths;
-    if (!binPaths.includes(targetBinDir)) {
-        binPaths.push(targetBinDir);
-    }
-    try {
-        fs.mkdirSync(configDir, { recursive: true });
-        fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2), 'utf-8');
-    }
-    catch { /* ignore write errors */ }
-    return synced;
 }
 /**
- * Merge plugin hooks into Claude's settings.json.
- * Reads the plugin's hooks/hooks.json and merges each event's hooks
- * into the version's settings.json, expanding variables.
+ * Remove legacy <plugin>--* entries from a version home, left by the previous
+ * flatten-based sync. Safe to call repeatedly — only deletes paths matching the
+ * plugin's prefix.
  */
-function syncPluginHooks(plugin, agent, versionHome, userConfig) {
-    const synced = [];
-    const hooksFile = path.join(plugin.root, 'hooks', 'hooks.json');
-    if (!fs.existsSync(hooksFile))
-        return synced;
-    let pluginHooks;
-    try {
-        pluginHooks = JSON.parse(fs.readFileSync(hooksFile, 'utf-8'));
-    }
-    catch {
-        return synced;
-    }
-    const configDir = path.join(versionHome, `.${agent}`);
-    const settingsPath = path.join(configDir, 'settings.json');
-    let settings = {};
-    if (fs.existsSync(settingsPath)) {
-        try {
-            settings = JSON.parse(fs.readFileSync(settingsPath, 'utf-8'));
+function migrateLegacyFlatLayout(plugin, agent, versionHome) {
+    const prefix = `${plugin.name}--`;
+    const agentRoot = path.join(versionHome, `.${agent}`);
+    // 1. skills
+    const skillsDir = path.join(agentRoot, 'skills');
+    if (fs.existsSync(skillsDir)) {
+        for (const entry of fs.readdirSync(skillsDir, { withFileTypes: true })) {
+            if (entry.isDirectory() && entry.name.startsWith(prefix)) {
+                try {
+                    fs.rmSync(path.join(skillsDir, entry.name), { recursive: true, force: true });
+                }
+                catch { /* skip */ }
+            }
         }
-        catch { /* start fresh */ }
     }
-    if (!settings.hooks || typeof settings.hooks !== 'object') {
-        settings.hooks = {};
-    }
-    const hooksConfig = settings.hooks;
-    for (const [event, matcherGroups] of Object.entries(pluginHooks)) {
-        if (!hooksConfig[event]) {
-            hooksConfig[event] = [];
-        }
-        const eventEntries = hooksConfig[event];
-        for (const group of matcherGroups) {
-            const matcher = group.matcher || '';
-            const expandedHooks = (group.hooks || []).map(h => ({
-                ...h,
-                command: expandPluginVars(h.command, plugin.root, plugin.name, agent, versionHome, userConfig),
-            }));
-            let matcherGroup = eventEntries.find(e => (e.matcher || '') === matcher);
-            if (!matcherGroup) {
-                matcherGroup = { matcher, hooks: [] };
-                eventEntries.push(matcherGroup);
-            }
-            if (!matcherGroup.hooks) {
-                matcherGroup.hooks = [];
-            }
-            for (const hook of expandedHooks) {
-                const exists = matcherGroup.hooks.some(h => h.command === hook.command);
-                if (!exists) {
-                    matcherGroup.hooks.push(hook);
+    // 2. commands
+    if (agent === 'claude' || agent === 'openclaw') {
+        const cmdsDir = path.join(agentRoot, AGENTS[agent]?.commandsSubdir ?? 'commands');
+        if (fs.existsSync(cmdsDir)) {
+            for (const entry of fs.readdirSync(cmdsDir, { withFileTypes: true })) {
+                if (entry.isFile() && entry.name.startsWith(prefix) && entry.name.endsWith('.md')) {
+                    try {
+                        fs.unlinkSync(path.join(cmdsDir, entry.name));
+                    }
+                    catch { /* skip */ }
                 }
             }
         }
-        synced.push(event);
-    }
-    try {
-        fs.mkdirSync(configDir, { recursive: true });
-        fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2), 'utf-8');
-    }
-    catch { /* ignore write errors */ }
-    return synced;
-}
-/**
- * Merge plugin .mcp.json MCP server definitions into Claude's settings.json.
- * Server names are namespaced as pluginName--serverName to avoid collisions.
- * Expands ${CLAUDE_PLUGIN_ROOT}, ${CLAUDE_PLUGIN_DATA}, ${user_config.*} in args and env.
- */
-function syncPluginMcp(plugin, agent, versionHome, userConfig) {
-    const mcpFile = path.join(plugin.root, '.mcp.json');
-    if (!fs.existsSync(mcpFile))
-        return false;
-    let pluginMcp;
-    try {
-        pluginMcp = JSON.parse(fs.readFileSync(mcpFile, 'utf-8'));
     }
-    catch {
-        return false;
-    }
-    const servers = pluginMcp.mcpServers;
-    if (!servers || Object.keys(servers).length === 0)
-        return false;
-    const configDir = path.join(versionHome, `.${agent}`);
-    const settingsPath = path.join(configDir, 'settings.json');
-    let settings = {};
-    if (fs.existsSync(settingsPath)) {
-        try {
-            settings = JSON.parse(fs.readFileSync(settingsPath, 'utf-8'));
+    // 3. agent definitions
+    const agentsDir = path.join(agentRoot, 'agents');
+    if (fs.existsSync(agentsDir)) {
+        for (const entry of fs.readdirSync(agentsDir, { withFileTypes: true })) {
+            if (entry.isFile() && entry.name.startsWith(prefix) && entry.name.endsWith('.md')) {
+                try {
+                    fs.unlinkSync(path.join(agentsDir, entry.name));
+                }
+                catch { /* skip */ }
+            }
         }
-        catch { /* start fresh */ }
-    }
-    if (!settings.mcpServers || typeof settings.mcpServers !== 'object') {
-        settings.mcpServers = {};
     }
-    const existing = settings.mcpServers;
-    let merged = false;
-    for (const [serverName, serverConfig] of Object.entries(servers)) {
-        const namespacedName = `${plugin.name}--${serverName}`;
-        // Expand variables inside the server config
-        const configStr = expandPluginVars(JSON.stringify(serverConfig), plugin.root, plugin.name, agent, versionHome, userConfig);
-        existing[namespacedName] = JSON.parse(configStr);
-        merged = true;
-    }
-    if (merged) {
+    // 4. plugin-bin
+    const binDir = path.join(agentRoot, 'plugin-bin', plugin.name);
+    if (fs.existsSync(binDir)) {
         try {
-            fs.mkdirSync(configDir, { recursive: true });
-            fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2), 'utf-8');
-        }
-        catch {
-            return false;
+            fs.rmSync(binDir, { recursive: true, force: true });
         }
+        catch { /* skip */ }
     }
-    return merged;
-}
-/**
- * Merge non-permission keys from plugin's settings.json non-destructively into agent settings.
- * Only adds keys that don't already exist — never overwrites user config.
- * Permission keys are handled separately by syncPluginPermissions.
- */
-function syncPluginSettings(plugin, agent, versionHome) {
-    const pluginSettingsPath = path.join(plugin.root, 'settings.json');
-    if (!fs.existsSync(pluginSettingsPath))
-        return false;
-    let pluginSettings;
+    // 5. settings.json — strip namespaced mcpServers, hooks referencing plugin
+    //    root, permissions referencing plugin root, and pluginBinPaths entries.
+    const settingsPath = path.join(agentRoot, 'settings.json');
+    if (!fs.existsSync(settingsPath))
+        return;
+    let settings;
     try {
-        pluginSettings = JSON.parse(fs.readFileSync(pluginSettingsPath, 'utf-8'));
+        settings = JSON.parse(fs.readFileSync(settingsPath, 'utf-8'));
     }
     catch {
-        return false;
-    }
-    // Exclude permissions — those are handled by syncPluginPermissions
-    const keysToMerge = Object.entries(pluginSettings).filter(([k]) => k !== 'permissions');
-    if (keysToMerge.length === 0)
-        return false;
-    const configDir = path.join(versionHome, `.${agent}`);
-    const settingsPath = path.join(configDir, 'settings.json');
-    let settings = {};
-    if (fs.existsSync(settingsPath)) {
-        try {
-            settings = JSON.parse(fs.readFileSync(settingsPath, 'utf-8'));
-        }
-        catch { /* start fresh */ }
+        return;
     }
     let changed = false;
-    for (const [key, value] of keysToMerge) {
-        if (!(key in settings)) {
-            settings[key] = value;
-            changed = true;
-        }
-    }
-    if (changed) {
-        try {
-            fs.mkdirSync(configDir, { recursive: true });
-            fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2), 'utf-8');
-        }
-        catch {
-            return false;
-        }
-    }
-    return changed;
-}
-/**
- * Merge plugin permissions into Claude's settings.json.
- * Reads the plugin's settings.json and merges permissions.allow / deny entries.
- */
-function syncPluginPermissions(plugin, agent, versionHome, userConfig) {
-    const pluginSettingsPath = path.join(plugin.root, 'settings.json');
-    if (!fs.existsSync(pluginSettingsPath))
-        return false;
-    let pluginSettings;
-    try {
-        pluginSettings = JSON.parse(fs.readFileSync(pluginSettingsPath, 'utf-8'));
-    }
-    catch {
-        return false;
-    }
-    const pluginAllow = pluginSettings.permissions?.allow || [];
-    const pluginDeny = pluginSettings.permissions?.deny || [];
-    if (pluginAllow.length === 0 && pluginDeny.length === 0)
-        return false;
-    const expandedAllow = pluginAllow.map(rule => expandPluginVars(rule, plugin.root, plugin.name, agent, versionHome, userConfig));
-    const expandedDeny = pluginDeny.map(rule => expandPluginVars(rule, plugin.root, plugin.name, agent, versionHome, userConfig));
-    const configDir = path.join(versionHome, `.${agent}`);
-    const settingsPath = path.join(configDir, 'settings.json');
-    let settings = {};
-    if (fs.existsSync(settingsPath)) {
-        try {
-            settings = JSON.parse(fs.readFileSync(settingsPath, 'utf-8'));
-        }
-        catch { /* start fresh */ }
-    }
-    if (!settings.permissions || typeof settings.permissions !== 'object') {
-        settings.permissions = { allow: [], deny: [] };
-    }
-    const perms = settings.permissions;
-    if (!perms.allow)
-        perms.allow = [];
-    if (!perms.deny)
-        perms.deny = [];
-    for (const rule of expandedAllow) {
-        if (!perms.allow.includes(rule)) {
-            perms.allow.push(rule);
-        }
-    }
-    for (const rule of expandedDeny) {
-        if (!perms.deny.includes(rule)) {
-            perms.deny.push(rule);
-        }
-    }
-    try {
-        fs.mkdirSync(configDir, { recursive: true });
-        fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2), 'utf-8');
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
-// ─── Utility ──────────────────────────────────────────────────────────────────
-/**
- * Copy a directory recursively, expanding plugin variables in text file contents.
- * Only expands variables in text files (.md, .json, .sh, .py, .js, .ts, .yaml, .yml, .toml).
- */
-function copyDirWithVarExpansion(src, dest, pluginRoot, pluginName, agent, versionHome, userConfig) {
-    fs.mkdirSync(dest, { recursive: true });
-    const entries = fs.readdirSync(src, { withFileTypes: true });
-    const textExtensions = new Set(['.md', '.json', '.sh', '.py', '.js', '.ts', '.yaml', '.yml', '.toml', '.txt']);
-    for (const entry of entries) {
-        const srcPath = path.join(src, entry.name);
-        const destPath = path.join(dest, entry.name);
-        if (entry.isDirectory()) {
-            copyDirWithVarExpansion(srcPath, destPath, pluginRoot, pluginName, agent, versionHome, userConfig);
-        }
-        else {
-            const ext = path.extname(entry.name).toLowerCase();
-            if (textExtensions.has(ext)) {
-                let content = fs.readFileSync(srcPath, 'utf-8');
-                content = expandPluginVars(content, pluginRoot, pluginName, agent, versionHome, userConfig);
-                fs.writeFileSync(destPath, content, 'utf-8');
-            }
-            else {
-                fs.copyFileSync(srcPath, destPath);
+    const pluginRoot = plugin.root;
+    const hooksCfg = settings.hooks;
+    if (hooksCfg && typeof hooksCfg === 'object') {
+        for (const [event, entries] of Object.entries(hooksCfg)) {
+            if (!Array.isArray(entries))
+                continue;
+            const groups = entries;
+            for (const group of groups) {
+                if (!Array.isArray(group.hooks))
+                    continue;
+                const orig = group.hooks.length;
+                group.hooks = group.hooks.filter(h => !(typeof h.command === 'string' && h.command.includes(pluginRoot)));
+                if (group.hooks.length !== orig)
+                    changed = true;
             }
-            const stat = fs.statSync(srcPath);
-            if (stat.mode & 0o111) {
-                fs.chmodSync(destPath, stat.mode);
+            const kept = groups.filter(g => Array.isArray(g.hooks) && g.hooks.length > 0);
+            if (kept.length !== groups.length) {
+                hooksCfg[event] = kept;
+                changed = true;
             }
-        }
-    }
-}
-// ─── Sync status ──────────────────────────────────────────────────────────────
-/**
- * Check if a plugin is synced to a version by inspecting the version home.
- * Checks skills, commands, agent defs, bin, hook commands, and permissions.
- */
-export function isPluginSynced(plugin, agent, versionHome) {
-    const prefix = `${plugin.name}--`;
-    // Check 1: plugin skill directories
-    if (plugin.skills.length > 0) {
-        const skillsDir = path.join(versionHome, `.${agent}`, 'skills');
-        if (fs.existsSync(skillsDir)) {
-            for (const skillName of plugin.skills) {
-                if (fs.existsSync(path.join(skillsDir, `${prefix}${skillName}`))) {
-                    return true;
-                }
+            if (Array.isArray(hooksCfg[event]) && hooksCfg[event].length === 0) {
+                delete hooksCfg[event];
+                changed = true;
             }
         }
     }
-    // Check 2: plugin command files
-    if (plugin.commands.length > 0 && (agent === 'claude' || agent === 'openclaw')) {
-        const agentConfig = AGENTS[agent];
-        const commandsDir = path.join(versionHome, `.${agent}`, agentConfig.commandsSubdir);
-        if (fs.existsSync(commandsDir)) {
-            for (const cmdName of plugin.commands) {
-                if (fs.existsSync(path.join(commandsDir, `${prefix}${cmdName}.md`))) {
-                    return true;
-                }
+    const perms = settings.permissions;
+    if (perms && typeof perms === 'object') {
+        for (const key of ['allow', 'deny']) {
+            const list = perms[key];
+            if (!Array.isArray(list))
+                continue;
+            const kept = list.filter(r => !(typeof r === 'string' && r.includes(pluginRoot)));
+            if (kept.length !== list.length) {
+                perms[key] = kept;
+                changed = true;
             }
         }
     }
-    // Check 3: plugin agent definition files
-    if (plugin.agentDefs.length > 0 && agent === 'claude') {
-        const agentsDir = path.join(versionHome, `.${agent}`, 'agents');
-        if (fs.existsSync(agentsDir)) {
-            for (const agentDefName of plugin.agentDefs) {
-                if (fs.existsSync(path.join(agentsDir, `${prefix}${agentDefName}.md`))) {
-                    return true;
-                }
+    const mcp = settings.mcpServers;
+    if (mcp && typeof mcp === 'object') {
+        for (const key of Object.keys(mcp)) {
+            if (key.startsWith(prefix)) {
+                delete mcp[key];
+                changed = true;
             }
         }
     }
-    // Check 4: plugin bin directory
-    if (plugin.bin.length > 0 && agent === 'claude') {
-        const binDir = path.join(versionHome, `.${agent}`, 'plugin-bin', plugin.name);
-        if (fs.existsSync(binDir)) {
-            return true;
-        }
-    }
-    // Check 5: plugin hooks registered in settings.json (commands referencing plugin root)
-    if (plugin.hooks.length > 0 && agent === 'claude') {
-        const settingsPath = path.join(versionHome, `.${agent}`, 'settings.json');
-        if (fs.existsSync(settingsPath)) {
-            try {
-                const content = fs.readFileSync(settingsPath, 'utf-8');
-                if (content.includes(plugin.root)) {
-                    return true;
-                }
-            }
-            catch { /* ignore */ }
+    if (Array.isArray(settings.pluginBinPaths)) {
+        const targetBinDir = path.join(agentRoot, 'plugin-bin', plugin.name);
+        const before = settings.pluginBinPaths.length;
+        settings.pluginBinPaths = settings.pluginBinPaths.filter(p => p !== targetBinDir);
+        if (settings.pluginBinPaths.length !== before)
+            changed = true;
+        if (settings.pluginBinPaths.length === 0) {
+            delete settings.pluginBinPaths;
+            changed = true;
         }
     }
-    // Check 6: plugin permissions in settings.json
-    if (agent === 'claude') {
-        const settingsPath = path.join(versionHome, `.${agent}`, 'settings.json');
-        if (fs.existsSync(settingsPath)) {
-            try {
-                const settings = JSON.parse(fs.readFileSync(settingsPath, 'utf-8'));
-                const allow = settings.permissions?.allow || [];
-                if (allow.some((rule) => rule.includes(plugin.root))) {
-                    return true;
-                }
-                // Check MCP servers
-                const mcpServers = settings.mcpServers;
-                if (mcpServers) {
-                    const hasNamespacedServer = Object.keys(mcpServers).some(k => k.startsWith(prefix));
-                    if (hasNamespacedServer)
-                        return true;
-                }
-            }
-            catch { /* ignore */ }
+    if (changed) {
+        try {
+            fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2), 'utf-8');
         }
+        catch { /* ignore */ }
     }
-    return false;
+}
+// ─── Sync status ──────────────────────────────────────────────────────────────
+/**
+ * Check if a plugin is synced to a version. True when the plugin lives at the
+ * native marketplace install path. Legacy dual-dash entries are not counted —
+ * they're treated as stale and migrated away on the next sync.
+ */
+export function isPluginSynced(plugin, agent, versionHome) {
+    if (!PLUGINS_CAPABLE_AGENTS.includes(agent))
+        return false;
+    return isInstalledInMarketplace(plugin.name, agent, versionHome);
 }
 // ─── Removal ─────────────────────────────────────────────────────────────────
 /**
@@ -781,9 +519,32 @@ export function removePluginFromVersion(pluginName, pluginRoot, agent, versionHo
         permissions: 0,
         mcp: 0,
     };
+    // 1. Remove the plugin from the marketplace install dir + disable it.
+    const removed = removePluginFromMarketplace(pluginName, agent, versionHome);
+    if (removed) {
+        result.skills.push(pluginName);
+    }
+    disablePluginInSettings(pluginName, agent, versionHome);
+    // 2. Refresh marketplace.json so it reflects what's left under plugins/.
+    syncMarketplaceManifest(agent, versionHome);
+    // 3. If we just removed the last plugin, drop the marketplace dir and the
+    //    known_marketplaces.json entry too.
+    if (marketplaceIsEmpty(agent, versionHome)) {
+        removeEmptyMarketplaceDir(agent, versionHome);
+        unregisterMarketplace(agent, versionHome);
+    }
+    // 4. Strip any legacy dual-dash entries from prior agents-cli versions.
+    cleanLegacyFlatLayout(pluginName, pluginRoot, agent, versionHome, result);
+    return result;
+}
+/**
+ * Strip dual-dash flat-layout entries left behind by older agents-cli sync runs.
+ * Mutates `result` to record what was removed.
+ */
+function cleanLegacyFlatLayout(pluginName, pluginRoot, agent, versionHome, result) {
     const prefix = `${pluginName}--`;
-    // 1. Remove synced skill dirs
-    const skillsDir = path.join(versionHome, `.${agent}`, 'skills');
+    const agentRoot = path.join(versionHome, `.${agent}`);
+    const skillsDir = path.join(agentRoot, 'skills');
     if (fs.existsSync(skillsDir)) {
         for (const entry of fs.readdirSync(skillsDir, { withFileTypes: true })) {
             if (!entry.isDirectory() || !entry.name.startsWith(prefix))
@@ -792,92 +553,75 @@ export function removePluginFromVersion(pluginName, pluginRoot, agent, versionHo
                 fs.rmSync(path.join(skillsDir, entry.name), { recursive: true, force: true });
                 result.skills.push(entry.name);
             }
-            catch { /* skip on error */ }
+            catch { /* skip */ }
         }
     }
-    // 2. Remove synced command files
     if (agent === 'claude' || agent === 'openclaw') {
-        const agentConfig = AGENTS[agent];
-        const commandsDir = path.join(versionHome, `.${agent}`, agentConfig.commandsSubdir);
+        const commandsDir = path.join(agentRoot, AGENTS[agent]?.commandsSubdir ?? 'commands');
         if (fs.existsSync(commandsDir)) {
             for (const entry of fs.readdirSync(commandsDir, { withFileTypes: true })) {
-                if (!entry.isFile())
-                    continue;
-                if (!entry.name.startsWith(prefix) || !entry.name.endsWith('.md'))
+                if (!entry.isFile() || !entry.name.startsWith(prefix) || !entry.name.endsWith('.md'))
                     continue;
                 try {
                     fs.unlinkSync(path.join(commandsDir, entry.name));
                     result.commands.push(entry.name);
                 }
-                catch { /* skip on error */ }
-            }
-        }
-    }
-    // 3. Remove synced agent def files
-    if (agent === 'claude') {
-        const agentsDir = path.join(versionHome, `.${agent}`, 'agents');
-        if (fs.existsSync(agentsDir)) {
-            for (const entry of fs.readdirSync(agentsDir, { withFileTypes: true })) {
-                if (!entry.isFile())
-                    continue;
-                if (!entry.name.startsWith(prefix) || !entry.name.endsWith('.md'))
-                    continue;
-                try {
-                    fs.unlinkSync(path.join(agentsDir, entry.name));
-                    result.agentDefs.push(entry.name);
-                }
-                catch { /* skip on error */ }
+                catch { /* skip */ }
             }
         }
     }
-    // 4. Remove plugin-bin directory
-    if (agent === 'claude') {
-        const binDir = path.join(versionHome, `.${agent}`, 'plugin-bin', pluginName);
-        if (fs.existsSync(binDir)) {
+    const agentsDir = path.join(agentRoot, 'agents');
+    if (fs.existsSync(agentsDir)) {
+        for (const entry of fs.readdirSync(agentsDir, { withFileTypes: true })) {
+            if (!entry.isFile() || !entry.name.startsWith(prefix) || !entry.name.endsWith('.md'))
+                continue;
             try {
-                fs.rmSync(binDir, { recursive: true, force: true });
-                result.bin.push(binDir);
+                fs.unlinkSync(path.join(agentsDir, entry.name));
+                result.agentDefs.push(entry.name);
             }
-            catch { /* skip on error */ }
+            catch { /* skip */ }
         }
     }
-    if (agent !== 'claude') {
-        return result;
+    const binDir = path.join(agentRoot, 'plugin-bin', pluginName);
+    if (fs.existsSync(binDir)) {
+        try {
+            fs.rmSync(binDir, { recursive: true, force: true });
+            result.bin.push(binDir);
+        }
+        catch { /* skip */ }
     }
-    // 5 + 6 + 7: edit settings.json — strip hooks, permissions, mcpServers matching plugin
-    const settingsPath = path.join(versionHome, `.${agent}`, 'settings.json');
+    const settingsPath = path.join(agentRoot, 'settings.json');
     if (!fs.existsSync(settingsPath))
-        return result;
+        return;
     let settings;
     try {
         settings = JSON.parse(fs.readFileSync(settingsPath, 'utf-8'));
     }
     catch {
-        return result;
+        return;
     }
     let changed = false;
-    // Strip hooks referencing plugin root
     const hooksConfig = settings.hooks;
     if (hooksConfig && typeof hooksConfig === 'object') {
         for (const [event, entries] of Object.entries(hooksConfig)) {
             if (!Array.isArray(entries))
                 continue;
-            const eventEntries = entries;
-            for (const group of eventEntries) {
+            const groups = entries;
+            for (const group of groups) {
                 if (!Array.isArray(group.hooks))
                     continue;
-                const originalLen = group.hooks.length;
+                const orig = group.hooks.length;
                 group.hooks = group.hooks.filter(h => {
                     const matches = typeof h.command === 'string' && h.command.includes(pluginRoot);
                     if (matches)
                         result.hooks.push(`${event}: ${h.command}`);
                     return !matches;
                 });
-                if (group.hooks.length !== originalLen)
+                if (group.hooks.length !== orig)
                     changed = true;
             }
-            const kept = eventEntries.filter(g => Array.isArray(g.hooks) && g.hooks.length > 0);
-            if (kept.length !== eventEntries.length) {
+            const kept = groups.filter(g => Array.isArray(g.hooks) && g.hooks.length > 0);
+            if (kept.length !== groups.length) {
                 hooksConfig[event] = kept;
                 changed = true;
             }
@@ -887,15 +631,14 @@ export function removePluginFromVersion(pluginName, pluginRoot, agent, versionHo
             }
         }
     }
-    // Strip permissions referencing plugin root
     const perms = settings.permissions;
     if (perms && typeof perms === 'object') {
         for (const key of ['allow', 'deny']) {
             const list = perms[key];
             if (!Array.isArray(list))
                 continue;
-            const kept = list.filter(rule => {
-                const matches = typeof rule === 'string' && rule.includes(pluginRoot);
+            const kept = list.filter(r => {
+                const matches = typeof r === 'string' && r.includes(pluginRoot);
                 if (matches)
                     result.permissions += 1;
                 return !matches;
@@ -906,52 +649,83 @@ export function removePluginFromVersion(pluginName, pluginRoot, agent, versionHo
             }
         }
     }
-    // Strip namespaced MCP servers added by this plugin
-    const mcpServers = settings.mcpServers;
-    if (mcpServers && typeof mcpServers === 'object') {
-        for (const serverName of Object.keys(mcpServers)) {
-            if (serverName.startsWith(prefix)) {
-                delete mcpServers[serverName];
+    const mcp = settings.mcpServers;
+    if (mcp && typeof mcp === 'object') {
+        for (const key of Object.keys(mcp)) {
+            if (key.startsWith(prefix)) {
+                delete mcp[key];
                 result.mcp += 1;
                 changed = true;
             }
         }
     }
-    // Strip bin path from pluginBinPaths
     if (Array.isArray(settings.pluginBinPaths)) {
-        const binDir = path.join(versionHome, `.${agent}`, 'plugin-bin', pluginName);
+        const targetBin = path.join(agentRoot, 'plugin-bin', pluginName);
         const before = settings.pluginBinPaths.length;
-        settings.pluginBinPaths = settings.pluginBinPaths.filter(p => p !== binDir);
+        settings.pluginBinPaths = settings.pluginBinPaths.filter(p => p !== targetBin);
         if (settings.pluginBinPaths.length !== before)
             changed = true;
+        if (settings.pluginBinPaths.length === 0) {
+            delete settings.pluginBinPaths;
+            changed = true;
+        }
     }
     if (changed) {
         try {
             fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2), 'utf-8');
         }
-        catch { /* ignore write errors */ }
+        catch { /* ignore */ }
     }
-    return result;
 }
 // ─── Orphan cleanup ───────────────────────────────────────────────────────────
 /**
- * Remove orphaned plugin skill directories from a version home.
- * Soft-deletes to ~/.agents/.trash/plugins/.
+ * Remove orphaned plugin entries from a version home. An entry is "orphan" if
+ * its plugin name is not in the active plugin set. Soft-deletes the affected
+ * marketplace plugin dir to ~/.agents/.trash/plugins/. Also cleans up any
+ * legacy dual-dash skills/ directories from older agents-cli versions.
  */
 export function cleanOrphanedPluginSkills(agent, versionHome, activePluginNames, version) {
     const removed = [];
+    // 1. Walk the native marketplace install dir and trash entries no longer active.
+    const mktPluginsDir = path.join(marketplaceRoot(agent, versionHome), 'plugins');
+    if (fs.existsSync(mktPluginsDir)) {
+        for (const entry of fs.readdirSync(mktPluginsDir, { withFileTypes: true })) {
+            if (!entry.isDirectory() || entry.name.startsWith('.'))
+                continue;
+            if (activePluginNames.has(entry.name))
+                continue;
+            try {
+                const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+                const trashDir = path.join(getTrashPluginsDir(), agent, version || 'unknown', entry.name);
+                const trashDest = path.join(trashDir, stamp);
+                fs.mkdirSync(trashDir, { recursive: true, mode: 0o700 });
+                fs.renameSync(path.join(mktPluginsDir, entry.name), trashDest);
+                disablePluginInSettings(entry.name, agent, versionHome);
+                removed.push(entry.name);
+            }
+            catch { /* skip on error */ }
+        }
+        // Keep manifest in sync with on-disk state and drop the marketplace if empty.
+        if (removed.length > 0) {
+            syncMarketplaceManifest(agent, versionHome);
+            if (marketplaceIsEmpty(agent, versionHome)) {
+                removeEmptyMarketplaceDir(agent, versionHome);
+                unregisterMarketplace(agent, versionHome);
+            }
+        }
+    }
+    // 2. Sweep legacy dual-dash skills directories from older agents-cli versions.
     const skillsDir = path.join(versionHome, `.${agent}`, 'skills');
-    if (!fs.existsSync(skillsDir))
-        return removed;
-    const entries = fs.readdirSync(skillsDir, { withFileTypes: true });
-    for (const entry of entries) {
-        if (!entry.isDirectory())
-            continue;
-        const dashIdx = entry.name.indexOf('--');
-        if (dashIdx === -1)
-            continue;
-        const pluginName = entry.name.slice(0, dashIdx);
-        if (!activePluginNames.has(pluginName)) {
+    if (fs.existsSync(skillsDir)) {
+        for (const entry of fs.readdirSync(skillsDir, { withFileTypes: true })) {
+            if (!entry.isDirectory())
+                continue;
+            const dashIdx = entry.name.indexOf('--');
+            if (dashIdx === -1)
+                continue;
+            const pluginName = entry.name.slice(0, dashIdx);
+            if (activePluginNames.has(pluginName))
+                continue;
             try {
                 const stamp = new Date().toISOString().replace(/[:.]/g, '-');
                 const trashDir = path.join(getTrashPluginsDir(), agent, version || 'unknown', entry.name);
@@ -967,24 +741,34 @@ export function cleanOrphanedPluginSkills(agent, versionHome, activePluginNames,
 }
 export function diffVersionPlugins(agent, version) {
     const versionHome = getVersionHomePath(agent, version);
-    const skillsDir = path.join(versionHome, `.${agent}`, 'skills');
+    const activePlugins = new Set(discoverPlugins().map(p => p.name));
     const orphans = [];
-    if (!fs.existsSync(skillsDir)) {
-        return { agent, version, orphans };
+    const mktPluginsDir = path.join(marketplaceRoot(agent, versionHome), 'plugins');
+    if (fs.existsSync(mktPluginsDir)) {
+        for (const entry of fs.readdirSync(mktPluginsDir, { withFileTypes: true })) {
+            if (!entry.isDirectory() || entry.name.startsWith('.'))
+                continue;
+            if (!activePlugins.has(entry.name)) {
+                orphans.push(entry.name);
+            }
+        }
     }
-    const activePlugins = new Set(discoverPlugins().map(p => p.name));
-    for (const entry of fs.readdirSync(skillsDir, { withFileTypes: true })) {
-        if (!entry.isDirectory())
-            continue;
-        const dashIdx = entry.name.indexOf('--');
-        if (dashIdx === -1)
-            continue;
-        const pluginName = entry.name.slice(0, dashIdx);
-        if (!activePlugins.has(pluginName)) {
-            orphans.push(entry.name);
+    // Also surface legacy dual-dash skill dirs as orphans during migration period.
+    const skillsDir = path.join(versionHome, `.${agent}`, 'skills');
+    if (fs.existsSync(skillsDir)) {
+        for (const entry of fs.readdirSync(skillsDir, { withFileTypes: true })) {
+            if (!entry.isDirectory())
+                continue;
+            const dashIdx = entry.name.indexOf('--');
+            if (dashIdx === -1)
+                continue;
+            const pluginName = entry.name.slice(0, dashIdx);
+            if (!activePlugins.has(pluginName)) {
+                orphans.push(entry.name);
+            }
         }
     }
-    return { agent, version, orphans: orphans.sort() };
+    return { agent, version, orphans: Array.from(new Set(orphans)).sort() };
 }
 export function iterPluginsCapableVersions(filter) {
     const pairs = [];