@phnx-labs/agents-cli 1.20.71 → 1.20.73

package/dist/lib/versions.js

@@ -24,6 +24,7 @@ import { checkbox, select } from '@inquirer/prompts';
 import { getVersionsDir, ensureAgentsDir, readMeta, writeMeta, getSkillsDir, getResolvedRulesDir, getUserRulesDir, getVersionResources, ensureVersionResourcePatterns, getProjectAgentsDir, getPromptcutsPath, getUserPromptcutsPath, getEnabledExtraRepos, getAgentsDir, getUserAgentsDir, getTrashVersionsDir, getActiveRulesPreset, getHomeDir } from './state.js';
 import { defaultPatterns, expandPatterns } from './resource-patterns.js';
 import { listResources } from './resources.js';
+import { activeRulesPreset, filterNamesForActiveResourceProfile } from './resource-profiles.js';
 // VERSION_RE + compareVersions are owned by the agent-spec engine primitives
 // (single source of truth). Re-exported below so existing importers of
 // `compareVersions` from './versions.js' keep working.
@@ -34,34 +35,44 @@ import { parseMcpServerConfig, isProjectMcpTrusted } from './mcp.js';
 import { createVersionedAlias, removeVersionedAlias, getConfigSymlinkVersion, ensureClaudeInsideSymlink } from './shims.js';
 import { importInstallScriptBinary } from './import.js';
 import { IS_WINDOWS, composeWin32CommandLine } from './platform/index.js';
+import { listInstalledSubagents } from './subagents.js';
+import { listInstalledWorkflows } from './workflows.js';
 import { pruneVersionHomeHookEntriesFromSettings } from './hooks.js';
 import { supports, explainSkip } from './capabilities.js';
-import { discoverPlugins } from './plugins.js';
+import { discoverPlugins, marketplaceSpecForName } from './plugins.js';
 import { loadManifest, saveManifest, buildManifest as buildSyncManifest, isStale } from './staleness/index.js';
 import { emit } from './events.js';
 import { safeJoin } from './paths.js';
 import { readSkillSourceCommandMarker, shouldInstallCommandAsSkill } from './command-skills.js';
 import { getWriter, getDetector } from './staleness/registry.js';
 import { syncMemoryToVersionHome } from './memory.js';
+import { listPluginSkillNames, resolveCommandSource, resolveSkillSource } from './staleness/writers/sources.js';
+import { syncProjectResourcesToAgent } from './project-resources.js';
 /** Promisified exec for running shell commands. */
 const execAsync = promisify(exec);
 const execFileAsync = promisify(execFile);
 const RULES_DOC_FILENAME = 'README.md';
-function getResourceBases(cwd) {
+function getLayeredResourceBases(cwd) {
     const projectAgentsDir = getProjectAgentsDir(cwd);
     const userBase = getUserAgentsDir();
     const systemBase = getAgentsDir();
     const resourceBases = [];
     if (projectAgentsDir) {
-        resourceBases.push({ scope: 'project', base: projectAgentsDir });
+        resourceBases.push({ source: 'project', base: projectAgentsDir });
     }
-    resourceBases.push({ scope: 'user', base: userBase });
-    resourceBases.push({ scope: 'user', base: systemBase });
+    resourceBases.push({ source: 'user', base: userBase });
+    resourceBases.push({ source: 'system', base: systemBase });
     for (const extra of getEnabledExtraRepos()) {
-        resourceBases.push({ scope: 'user', base: extra.dir });
+        resourceBases.push({ source: extra.alias, base: extra.dir });
     }
     return resourceBases;
 }
+function getResourceBases(cwd) {
+    return getLayeredResourceBases(cwd).map(({ base, source }) => ({
+        base,
+        scope: source === 'project' ? 'project' : 'user',
+    }));
+}
 function getScopedMcpResources(cwd) {
     const resources = new Map();
     for (const { base, scope } of getResourceBases(cwd)) {
@@ -79,6 +90,55 @@ function getScopedMcpResources(cwd) {
     }
     return Array.from(resources.values());
 }
+function sourceMapFromResources(kind, cwd) {
+    return new Map(listResources(kind, cwd).map(r => [r.name, r.source]));
+}
+function sourceMapFromLayeredDirectory(cwd, relativePath, listNames) {
+    const resources = new Map();
+    for (const { base, source } of getLayeredResourceBases(cwd)) {
+        const dir = path.join(base, ...relativePath);
+        if (!fs.existsSync(dir))
+            continue;
+        for (const name of listNames(dir)) {
+            if (!resources.has(name))
+                resources.set(name, source);
+        }
+    }
+    return resources;
+}
+function sourceMapFromPermissionGroups(cwd) {
+    return sourceMapFromLayeredDirectory(cwd, ['permissions', 'groups'], (dir) => fs.readdirSync(dir)
+        .filter(f => f.endsWith('.yaml') || f.endsWith('.yml'))
+        .map(f => f.replace(/\.(yaml|yml)$/, '')));
+}
+function sourceMapFromWorkflows(cwd) {
+    return sourceMapFromLayeredDirectory(cwd, ['workflows'], (dir) => fs.readdirSync(dir, { withFileTypes: true })
+        .filter(d => d.isDirectory() && fs.existsSync(path.join(dir, d.name, 'WORKFLOW.md')))
+        .map(d => d.name));
+}
+function sourceMapFromPluginSkills(plugins, activePluginNames, cwd) {
+    const sourceRank = new Map([
+        ['user', 0],
+        ['system', 1],
+        ['project', 3],
+    ]);
+    const entries = plugins
+        .filter(plugin => activePluginNames.has(plugin.name))
+        .map(plugin => {
+        const spec = marketplaceSpecForName(plugin.marketplace, cwd);
+        const source = spec.kind === 'extra' ? spec.alias : spec.kind;
+        return { plugin, source, rank: sourceRank.get(source) ?? 2 };
+    })
+        .sort((a, b) => a.rank - b.rank);
+    const sources = new Map();
+    for (const { plugin, source } of entries) {
+        for (const skill of plugin.skills) {
+            if (!sources.has(skill))
+                sources.set(skill, source);
+        }
+    }
+    return sources;
+}
 /**
  * Get all available resources from ~/.agents/.
  */
@@ -110,7 +170,7 @@ export function getAvailableResources(cwd = process.cwd()) {
             commandNames.add(name);
         }
     }
-    result.commands = Array.from(commandNames);
+    result.commands = filterNamesForActiveResourceProfile('commands', Array.from(commandNames), sourceMapFromResources('commands', cwd));
     // Skills (directories, excluding hidden)
     const skillNames = new Set();
     for (const { base } of resourceBases) {
@@ -124,13 +184,13 @@ export function getAvailableResources(cwd = process.cwd()) {
             skillNames.add(name);
         }
     }
-    result.skills = Array.from(skillNames);
-    // Hooks (files). A hook is an actual script: known script extension, OR
-    // executable bit on a file with a non-data extension. Auxiliary content
-    // like `README.md` (docs) or `promptcuts.yaml` (data read directly by the
-    // expand-promptcuts script) lives in hooks/ but is not a hook. Older sync
-    // runs chmod 0o755'd everything they copied, so an exec bit alone can no
-    // longer be trusted as the signal.
+    result.skills = filterNamesForActiveResourceProfile('skills', Array.from(skillNames), sourceMapFromResources('skills', cwd));
+    // Hooks. A hook is either a directory bundle or an actual script file: known
+    // script extension, OR executable bit on a file with a non-data extension.
+    // Auxiliary content like `README.md` (docs) or `promptcuts.yaml` (data read
+    // directly by the expand-promptcuts script) lives in hooks/ but is not a
+    // hook. Older sync runs chmod 0o755'd everything they copied, so an exec bit
+    // alone can no longer be trusted as the signal.
     const NON_SCRIPT_EXTS = new Set(['.md', '.markdown', '.rst', '.txt', '.yaml', '.yml', '.json', '.toml', '.ini', '.conf']);
     const SCRIPT_EXTS = new Set(['.sh', '.bash', '.zsh', '.py', '.js', '.ts', '.mjs', '.cjs', '.rb', '.pl', '.ps1']);
     const hookNames = new Set();
@@ -142,7 +202,13 @@ export function getAvailableResources(cwd = process.cwd()) {
             if (name.startsWith('.'))
                 continue;
             try {
-                const stat = fs.statSync(path.join(hooksDir, name));
+                const stat = fs.lstatSync(path.join(hooksDir, name));
+                if (stat.isSymbolicLink())
+                    continue;
+                if (stat.isDirectory()) {
+                    hookNames.add(name);
+                    continue;
+                }
                 if (!stat.isFile())
                     continue;
                 const ext = path.extname(name).toLowerCase();
@@ -156,7 +222,7 @@ export function getAvailableResources(cwd = process.cwd()) {
             catch { /* ignore unreadable */ }
         }
     }
-    result.hooks = Array.from(hookNames);
+    result.hooks = filterNamesForActiveResourceProfile('hooks', Array.from(hookNames), sourceMapFromResources('hooks', cwd));
     // Rules — list available presets across layers (project > user > extras > system).
     // The composer selects exactly one preset per sync; this list drives the
     // resource-count display and `agents rules switch` picker. Routes through
@@ -184,22 +250,12 @@ export function getAvailableResources(cwd = process.cwd()) {
             // malformed rules.yaml — skip silently; the composer will surface the error.
         }
     }
-    result.memory = Array.from(presetNames);
-    result.mcp = getScopedMcpResources(cwd).map(resource => resource.name);
+    result.memory = filterNamesForActiveResourceProfile('memory', Array.from(presetNames));
+    const scopedMcp = getScopedMcpResources(cwd);
+    result.mcp = filterNamesForActiveResourceProfile('mcp', scopedMcp.map(resource => resource.name), new Map(scopedMcp.map(resource => [resource.name, resource.scope])));
     // Permission groups (from permissions/groups/*.yaml)
-    const permissionNames = new Set();
-    for (const { base } of resourceBases) {
-        const permsGroupsDir = path.join(base, 'permissions', 'groups');
-        if (!fs.existsSync(permsGroupsDir))
-            continue;
-        const names = fs.readdirSync(permsGroupsDir)
-            .filter(f => f.endsWith('.yaml') || f.endsWith('.yml'))
-            .map(f => f.replace(/\.(yaml|yml)$/, ''));
-        for (const name of names) {
-            permissionNames.add(name);
-        }
-    }
-    result.permissions = Array.from(permissionNames);
+    const permissionSources = sourceMapFromPermissionGroups(cwd);
+    result.permissions = filterNamesForActiveResourceProfile('permissions', Array.from(permissionSources.keys()), permissionSources);
     // Subagents (directories with AGENT.md)
     const subagentNames = new Set();
     for (const { base } of resourceBases) {
@@ -213,24 +269,19 @@ export function getAvailableResources(cwd = process.cwd()) {
             subagentNames.add(name);
         }
     }
-    result.subagents = Array.from(subagentNames);
+    result.subagents = filterNamesForActiveResourceProfile('subagents', Array.from(subagentNames), sourceMapFromResources('subagents', cwd));
     // Workflows (directories with WORKFLOW.md)
-    const workflowNames = new Set();
-    for (const { base } of resourceBases) {
-        const workflowsDir = path.join(base, 'workflows');
-        if (!fs.existsSync(workflowsDir))
-            continue;
-        const names = fs.readdirSync(workflowsDir, { withFileTypes: true })
-            .filter(d => d.isDirectory() && fs.existsSync(path.join(workflowsDir, d.name, 'WORKFLOW.md')))
-            .map(d => d.name);
-        for (const name of names) {
-            workflowNames.add(name);
-        }
-    }
-    result.workflows = Array.from(workflowNames);
+    const workflowSources = sourceMapFromWorkflows(cwd);
+    result.workflows = filterNamesForActiveResourceProfile('workflows', Array.from(workflowSources.keys()), workflowSources);
     // Plugins (directories with .claude-plugin/plugin.json)
     const allPlugins = discoverPlugins();
-    result.plugins = allPlugins.map(p => p.name);
+    result.plugins = filterNamesForActiveResourceProfile('plugins', allPlugins.map(p => p.name), new Map(allPlugins.map(p => [p.name, 'user'])));
+    const activePlugins = new Set(result.plugins);
+    const pluginSkillNames = filterNamesForActiveResourceProfile('skills', listPluginSkillNames({ plugins: activePlugins }), sourceMapFromPluginSkills(allPlugins, activePlugins, cwd));
+    for (const name of pluginSkillNames) {
+        if (!skillNames.has(name))
+            result.skills.push(name);
+    }
     // Promptcuts — present if either layer exists. Reads merge user + system
     // with user precedence (see readMergedPromptcuts); writes always go to user.
     result.promptcuts = fs.existsSync(getUserPromptcutsPath()) || fs.existsSync(getPromptcutsPath());
@@ -1148,6 +1199,37 @@ export function setGlobalDefault(agent, version) {
     }
     writeMeta(meta);
 }
+/**
+ * Path to the sentinel file that marks a version as an isolated install.
+ *
+ * It lives at the version-dir root (a sibling of `home/`), so it is carried
+ * along when `softDeleteVersionDir` moves the whole directory to trash and is
+ * restored intact by `agents trash restore`. Its mere presence is the marker;
+ * the contents are an informational timestamp only.
+ */
+function getIsolatedMarkerPath(agent, version) {
+    return path.join(getVersionDir(agent, version), '.isolated');
+}
+/**
+ * Mark an installed version as an isolated install (`agents add --isolated`).
+ *
+ * Isolated versions are fully self-contained: they never become the global
+ * default and never own the user's real `~/.<agent>` config directory. This
+ * flag is what keeps every "adopting" code path away from them.
+ */
+export function markVersionIsolated(agent, version) {
+    fs.writeFileSync(getIsolatedMarkerPath(agent, version), `${new Date().toISOString()}\n`, { mode: 0o600 });
+}
+/**
+ * Whether a version was installed as an isolated install (`agents add --isolated`).
+ *
+ * Used to exclude such versions from global-default promotion and from any
+ * flow that would touch the user's real `~/.<agent>` directory, and to gate the
+ * `--isolated` safety check on `agents remove`.
+ */
+export function isVersionIsolated(agent, version) {
+    return fs.existsSync(getIsolatedMarkerPath(agent, version));
+}
 /**
  * Grok's official installer writes into ~/.grok/downloads, which (because we
  * symlink ~/.grok to the active version home) resolves to the PREVIOUS default
@@ -1459,16 +1541,23 @@ export async function installVersion(agent, version, onProgress, opts) {
         return { success: false, installedVersion: version, error: err.message };
     }
 }
+// Version-dir entries that are STATE, not install output, and so must survive a
+// clean reinstall: `home/`, and the `.isolated` marker that is the single source
+// of truth for "this copy is walled off". Losing the marker would silently demote
+// an isolated copy to a normal one on its first repair — after which shim
+// self-heal would hand it a bare `<agent>` shim and a PATH entry.
+const PRESERVED_ON_CLEAN_REINSTALL = new Set(['home', '.isolated']);
 /**
  * Remove install artifacts from a version directory, preserving `home/` which
  * contains the user's conversation history, sessions, history.jsonl, tasks,
- * todos, file-history, etc. Used by the install pipeline (NOT by removeVersion)
- * to clean up staging artifacts when a fresh install collides with an existing
- * dir. removeVersion uses soft-delete instead.
+ * todos, file-history, etc. (and the `.isolated` marker — see
+ * PRESERVED_ON_CLEAN_REINSTALL). Used by the install pipeline (NOT by
+ * removeVersion) to clean up staging artifacts when a fresh install collides
+ * with an existing dir. removeVersion uses soft-delete instead.
  */
 function removeInstallArtifacts(versionDir) {
     for (const entry of fs.readdirSync(versionDir)) {
-        if (entry === 'home')
+        if (PRESERVED_ON_CLEAN_REINSTALL.has(entry))
             continue;
         fs.rmSync(path.join(versionDir, entry), { recursive: true, force: true });
     }
@@ -1580,9 +1669,12 @@ async function reconcileGlobalBinaryVersions(agent) {
     }
     if (foldedAny) {
         invalidateInstalledVersionsCache(agent);
-        // Keep the recorded default pointing at a dir that still exists on disk.
+        // Keep the recorded default pointing at a dir that still exists on disk —
+        // but never promote an isolated copy into the default slot (same rule as the
+        // post-removal promotion filter and `agents use`). Leaving it unset is right:
+        // an isolated-only agent has no default by design.
         const def = getGlobalDefault(agent);
-        if (!def || !fs.existsSync(getVersionDir(agent, def))) {
+        if ((!def || !fs.existsSync(getVersionDir(agent, def))) && !isVersionIsolated(agent, survivor)) {
             setGlobalDefault(agent, survivor);
         }
     }
@@ -1676,14 +1768,20 @@ export function removeVersion(agent, version) {
     // broke every launcher after removing the pinned default.
     if (getGlobalDefault(agent) === version) {
         const remaining = listInstalledVersions(agent);
-        if (remaining.length > 0) {
-            const newestRemaining = remaining[remaining.length - 1];
+        // Never auto-promote an isolated install to the global default: it was
+        // installed to stay separate from the user's setup, and promoting it would
+        // silently make `<agent>` resolve to it (and let a later `use` adopt its
+        // home into `~/.<agent>`). Prefer the newest NON-isolated survivor; if every
+        // survivor is isolated, clear the default rather than adopt one.
+        const promotable = remaining.filter((v) => !isVersionIsolated(agent, v));
+        if (promotable.length > 0) {
+            const newestRemaining = promotable[promotable.length - 1];
             setGlobalDefault(agent, newestRemaining);
             console.log(chalk.yellow(`Default ${agent} was ${version} (removed); reassigned to ${newestRemaining}. Change it with: agents use ${agent}@<version>`));
         }
         else {
             setGlobalDefault(agent, undefined);
-            console.log(chalk.yellow(`Removed the last installed ${agent} version and cleared its default. Reinstall with: agents add ${agent}, then set one with: agents use ${agent}@<version>`));
+            console.log(chalk.yellow(`Removed the last non-isolated ${agent} version and cleared its default. Reinstall with: agents add ${agent}, then set one with: agents use ${agent}@<version>`));
         }
     }
     // Clean up dangling config symlink if it pointed to the removed version
@@ -1977,6 +2075,17 @@ export async function verifyInstalledBinaryLaunches(agent, version) {
  *   4. Nothing runnable installed → install `latest`, pin it, return it.
  *   5. Give up → return null (caller surfaces a clear error).
  *
+ * Isolation boundary (both directions — steps 3/4 are the only mutating ones):
+ *   - An ISOLATED target gets step 2 and nothing else. Falling back would let
+ *     `agents run <agent>@<isolated>` silently repoint the user's NORMAL default,
+ *     and installing `latest` would materialize a version they never asked for.
+ *     A failed repair returns null so the caller says so plainly.
+ *   - An isolated version is never a fallback CANDIDATE either, whatever the
+ *     target is: promoting one to the global default is exactly what `agents use`
+ *     refuses and what removeVersion's promotion filter excludes, so it must not
+ *     happen here by the back door (the daemon's launch-health pass calls this
+ *     unattended every ~6h).
+ *
  * Gated to npm-package agents: their native binary ships as an optional per-arch
  * dependency whose tarball can extract partially (interrupted/raced install) —
  * the exact failure this repairs. Agents with a global/native binary (grok,
@@ -1988,14 +2097,28 @@ export async function ensureAgentRunnable(agent, version, log) {
         return version;
     if ((await verifyInstalledBinaryLaunches(agent, version)).ok)
         return version;
+    // Read the marker BEFORE the repair: the reinstall rewrites the version dir,
+    // so isolation must be decided from the pre-repair state, not re-read after.
+    const targetIsolated = isVersionIsolated(agent, version);
     log?.(`${cfg.name}@${version} is broken (platform binary missing) — repairing…`);
     const repair = await installVersion(agent, version, undefined, { clean: true });
     if (repair.success && (await verifyInstalledBinaryLaunches(agent, version)).ok) {
         log?.(`repaired ${cfg.name}@${version}.`);
         return version;
     }
+    // An isolated copy is walled off from the rest of the setup: repairing it in
+    // place is the ONLY thing we may do. No fallback, no install, no default
+    // switch — surface the failure and let the caller tell the user.
+    if (targetIsolated) {
+        log?.(`${cfg.name}@${version} is an isolated install and could not be repaired — leaving your default ${cfg.name} untouched.`);
+        return null;
+    }
     // In-place repair failed → adopt another installed version that launches.
-    const others = listInstalledVersions(agent).filter(v => v !== version).sort(compareVersions).reverse();
+    // Isolated copies are excluded: they are deliberately not promotable.
+    const others = listInstalledVersions(agent)
+        .filter(v => v !== version && !isVersionIsolated(agent, v))
+        .sort(compareVersions)
+        .reverse();
     for (const cand of others) {
         if ((await verifyInstalledBinaryLaunches(agent, cand)).ok) {
             setGlobalDefault(agent, cand);
@@ -2004,9 +2127,28 @@ export async function ensureAgentRunnable(agent, version, log) {
         }
     }
     // Nothing runnable installed → last resort: install latest and pin it.
+    //
+    // …unless `latest` is a version the user already holds as an ISOLATED copy. A
+    // normal and an isolated install of the same version share one on-disk dir
+    // (see the coexistence refusal in commands/versions.ts), so installing would
+    // commandeer that copy and pinning it would hand an isolated install the
+    // global default — the same breach the candidate filter above prevents.
+    // Resolved BEFORE installing so the isolated copy is not even rebuilt.
+    const latestVersion = await getLatestNpmVersion(agent);
+    if (latestVersion && isVersionIsolated(agent, latestVersion)) {
+        log?.(`no runnable ${cfg.name} version installed — ${cfg.name}@${latestVersion} is the latest, but you hold it as an isolated copy, so it can't become your default.`);
+        log?.(`install one explicitly: agents add ${agent}@latest`);
+        return null;
+    }
     log?.(`no runnable ${cfg.name} version installed — installing ${cfg.name}@latest…`);
     const latest = await installVersion(agent, 'latest', undefined, { clean: true });
     if (latest.success) {
+        // Belt-and-braces: `latest` could have moved between the probe above and the
+        // install. Never pin an isolated version, whatever the resolution said.
+        if (isVersionIsolated(agent, latest.installedVersion)) {
+            log?.(`${cfg.name}@${latest.installedVersion} is an isolated copy and can't be set as your default.`);
+            return null;
+        }
         setGlobalDefault(agent, latest.installedVersion);
         log?.(`installed ${cfg.name}@${latest.installedVersion} and set it as the default.`);
         return latest.installedVersion;
@@ -2082,9 +2224,10 @@ export function listRepoNames() {
  * `expandPatterns` matches `source:*` patterns against. This is the single
  * source of truth for how each kind attributes its source layer:
  *   - commands/skills/hooks/subagents → real layer from `listResources`
- *   - permissions                     → always the system repo
+ *   - permissions                     → real layer from permissions/groups
  *   - mcp                             → project vs user scope preserved
- *   - plugins/workflows               → user repo
+ *   - plugins                         → user repo
+ *   - workflows                       → real layer from workflow directories
  * Both the persisted-pattern sync path and `buildRepoScopedSelection` use it
  * so the attribution can't drift between the two.
  */
@@ -2095,14 +2238,24 @@ function resourceSourceMap(kind, cwd, available) {
         case 'hooks':
         case 'subagents':
             return new Map(listResources(kind, cwd).map(r => [r.name, r.source]));
-        case 'permissions':
-            return new Map(available.permissions.map(n => [n, 'system']));
+        case 'permissions': {
+            const sources = sourceMapFromPermissionGroups(cwd);
+            return new Map(available.permissions.flatMap((n) => {
+                const source = sources.get(n);
+                return source ? [[n, source]] : [];
+            }));
+        }
         case 'mcp':
             return new Map(getScopedMcpResources(cwd).map(r => [r.name, r.scope]));
         case 'plugins':
             return new Map(available.plugins.map(n => [n, 'user']));
-        case 'workflows':
-            return new Map(available.workflows.map(n => [n, 'user']));
+        case 'workflows': {
+            const sources = sourceMapFromWorkflows(cwd);
+            return new Map(available.workflows.flatMap((n) => {
+                const source = sources.get(n);
+                return source ? [[n, source]] : [];
+            }));
+        }
     }
 }
 /**
@@ -2202,11 +2355,10 @@ export function syncResourcesToVersion(agent, version, selection, options = {})
     // only sets fields that aren't already present, preserving user edits).
     {
         const extraAliases = extraRepos.map(e => e.alias);
-        const allLayers = defaultPatterns(extraAliases);
         const noProject = defaultPatterns(extraAliases, false);
         ensureVersionResourcePatterns(agent, version, {
-            commands: allLayers,
-            skills: allLayers,
+            commands: noProject,
+            skills: noProject,
             hooks: noProject, // hooks: no project layer (security)
             subagents: noProject,
             plugins: noProject,
@@ -2258,6 +2410,9 @@ export function syncResourcesToVersion(agent, version, selection, options = {})
             }
         }
     }
+    if (projectAgentsDir) {
+        syncProjectResourcesToAgent(agent, version, projectAgentsDir);
+    }
     // Fast guard: skip the entire sync when the caller requested a full sync and
     // nothing has changed since the last full sync. Pattern-derived selections
     // still count as full syncs because they are the persisted intended scope,
@@ -2310,6 +2465,7 @@ export function syncResourcesToVersion(agent, version, selection, options = {})
         }
         return [];
     };
+    const trustedCommandNames = (names) => names.filter((name) => resolveCommandSource(name) !== null);
     // Sync commands — dispatch through WRITERS.commands. The writer dispatches
     // between native (file copy / TOML conversion) and commands-as-skills
     // (grok, Codex >= 0.117.0) based on `shouldInstallCommandAsSkill`. The
@@ -2317,8 +2473,8 @@ export function syncResourcesToVersion(agent, version, selection, options = {})
     // takes the commands-as-skills path — silently dropping every command.
     const commandsWriter = getWriter('commands', agent);
     const commandsToSync = selection
-        ? resolveSelection(selection.commands, available.commands)
-        : available.commands; // No selection = sync all
+        ? trustedCommandNames(resolveSelection(selection.commands, available.commands))
+        : trustedCommandNames(available.commands); // No selection = sync all trusted commands, excluding project-only commands
     const commandsAsSkills = shouldInstallCommandAsSkill(agent, version);
     if (commandsToSync.length > 0 && commandsWriter) {
         const commandsTarget = path.join(agentDir, agentConfig.commandsSubdir);
@@ -2356,9 +2512,18 @@ export function syncResourcesToVersion(agent, version, selection, options = {})
     // ~/.agents/skills/ (Gemini) are not registered; we clear the version-home
     // skills dir for them so a stale per-version copy never shadows central.
     const skillsWriter = getWriter('skills', agent);
-    let skillsToSync = selection
-        ? resolveSelection(selection.skills, available.skills)
-        : available.skills;
+    const pluginsWriter = getWriter('plugins', agent);
+    const pluginsToSync = selection
+        ? resolveSelection(selection.plugins, available.plugins)
+        : (pluginsWriter ? available.plugins : []);
+    const pluginSkillsToSync = listPluginSkillNames({ agent, plugins: new Set(pluginsToSync) });
+    const trustedSkillNames = (names) => names.filter((name) => resolveSkillSource(name, { agent, plugins: new Set(pluginsToSync) }) !== null);
+    const selectedSkillsToSync = selection
+        ? trustedSkillNames(resolveSelection(selection.skills, available.skills))
+        : trustedSkillNames(available.skills);
+    let skillsToSync = userPassedSelection
+        ? selectedSkillsToSync
+        : Array.from(new Set([...selectedSkillsToSync, ...pluginSkillsToSync]));
     if (commandsAsSkills && commandsToSync.length > 0 && skillsToSync.length > 0) {
         const commandNames = new Set(commandsToSync);
         const skillRoots = [
@@ -2451,7 +2616,7 @@ export function syncResourcesToVersion(agent, version, selection, options = {})
             const overridePreset = Array.isArray(selection?.memory) && selection.memory.length === 1 && selection.memory[0] !== 'AGENTS'
                 ? selection.memory[0]
                 : null;
-            const preset = overridePreset || getActiveRulesPreset(agent, version);
+            const preset = overridePreset || activeRulesPreset() || getActiveRulesPreset(agent, version);
             const r = rulesWriter.write({ version, versionHome, selection: { preset }, cwd });
             result.memory.push(...r.synced);
             // rulesPreset is tracked separately via setActiveRulesPreset.
@@ -2538,9 +2703,11 @@ export function syncResourcesToVersion(agent, version, selection, options = {})
     // as commands/skills/hooks).
     const subagentsWriter = getWriter('subagents', agent);
     const subagentsGate = supports(agent, 'subagents', version);
+    const installedSubagentNames = new Set(listInstalledSubagents().map((subagent) => subagent.name));
+    const trustedSubagentNames = (names) => names.filter((name) => installedSubagentNames.has(name));
     const subagentsRequested = selection
-        ? resolveSelection(selection.subagents, available.subagents)
-        : (subagentsWriter ? available.subagents : []);
+        ? trustedSubagentNames(resolveSelection(selection.subagents, available.subagents))
+        : (subagentsWriter ? trustedSubagentNames(available.subagents) : []);
     const subagentsToSync = subagentsGate.ok ? subagentsRequested : [];
     if (subagentsRequested.length > 0 && !subagentsGate.ok) {
         console.warn(explainSkip(agent, 'subagents', subagentsGate, version) + ' -- skipped');
@@ -2569,10 +2736,6 @@ export function syncResourcesToVersion(agent, version, selection, options = {})
         }
     }
     // Sync plugins — dispatch through WRITERS.plugins.
-    const pluginsWriter = getWriter('plugins', agent);
-    const pluginsToSync = selection
-        ? resolveSelection(selection.plugins, available.plugins)
-        : (pluginsWriter ? available.plugins : []);
     if (pluginsToSync.length > 0 && pluginsWriter) {
         const r = pluginsWriter.write({ version, versionHome, selection: pluginsToSync, cwd });
         result.plugins.push(...r.synced);
@@ -2580,9 +2743,15 @@ export function syncResourcesToVersion(agent, version, selection, options = {})
     // Sync workflows — dispatch through WRITERS.workflows.
     const workflowsWriter = getWriter('workflows', agent);
     const workflowsGate = supports(agent, 'workflows', version);
+    const trustedWorkflowNames = (names) => {
+        if (names.length === 0)
+            return [];
+        const installedWorkflowNames = new Set(listInstalledWorkflows().keys());
+        return names.filter((name) => installedWorkflowNames.has(name));
+    };
     const workflowsRequested = selection
-        ? resolveSelection(selection.workflows, available.workflows)
-        : (workflowsWriter ? available.workflows : []);
+        ? trustedWorkflowNames(resolveSelection(selection.workflows, available.workflows))
+        : (workflowsWriter ? trustedWorkflowNames(available.workflows) : []);
     const workflowsToSync = workflowsGate.ok ? workflowsRequested : [];
     if (workflowsRequested.length > 0 && !workflowsGate.ok) {
         console.warn(explainSkip(agent, 'workflows', workflowsGate, version) + ' -- skipped');

package/dist/lib/workflows.d.ts

@@ -294,6 +294,8 @@ export declare function transformWorkflowForKimi(workflowPath: string, name: str
  * user-authored workflow of the same name.
  */
 export declare function transformWorkflowForAntigravity(workflowPath: string, name: string): string;
+/** Convert a canonical agents-cli workflow bundle into an OpenClaw Lobster file. */
+export declare function transformWorkflowForOpenClaw(workflowPath: string, name: string): string;
 /**
  * Resolve an `agents run <workflow>` reference.
  *