@phnx-labs/agents-cli 1.22.56 → 1.22.58

package/dist/lib/installations/versions.js

@@ -1,18 +1,6 @@
 /**
- * Version management module for agents-cli.
- *
- * Handles installing, removing, listing, and switching between agent CLI versions.
- * Each version is installed into an isolated directory under ~/.agents/.system/versions/{agent}/{version}/
- * with its own HOME directory for config isolation. Resources (commands, skills, hooks, memory,
- * MCP servers, permissions, subagents, plugins) from ~/.agents/ are synced into version homes
- * via copies or conversions (not symlinks).
- *
- * Key responsibilities:
- * - Version lifecycle: install, remove, list, resolve (project-level or global default)
- * - Resource discovery: scan ~/.agents/ for available resources across all types
- * - Resource sync: copy/convert resources into a version's isolated config directory
- * - Diff and reconciliation: detect new/unsynced resources and prompt users to sync them
- * - Agent/version target resolution: parse agent@version specs from CLI flags
+ * Version lifecycle, resource sync, and agent@version resolution for agents-cli.
+ * Each version lives in an isolated home under ~/.agents/.history/versions/{agent}/{version}/.
  */
 import * as fs from 'fs';
 import * as path from 'path';
@@ -121,12 +109,7 @@ function sourceMapFromWorkflows(cwd) {
         .filter(d => d.isDirectory() && fs.existsSync(path.join(dir, d.name, 'WORKFLOW.md')))
         .map(d => d.name));
 }
-// A plugin is a directory whose marker is `.claude-plugin/plugin.json`. Attribute
-// each to the layer it actually resolves from (system / user / project / extra) —
-// the same first-wins resolution the plugins staleness checker uses. Hardcoding
-// 'user' here made a `system:*` selection expand to zero plugins, so
-// `agents sync <agent> system` silently skipped system-layer plugins like `swarm`
-// (RUSH-3207).
+// Attribute each plugin to the layer it resolves from so `system:*` selections include system-layer plugins.
 function sourceMapFromPlugins(cwd) {
     return sourceMapFromLayeredDirectory(cwd, ['plugins'], (dir) => fs.readdirSync(dir, { withFileTypes: true })
         .filter(d => d.isDirectory() && fs.existsSync(path.join(dir, d.name, '.claude-plugin', 'plugin.json')))
@@ -155,9 +138,7 @@ function sourceMapFromPluginSkills(plugins, activePluginNames, cwd) {
     }
     return sources;
 }
-/**
- * Get all available resources from ~/.agents/.
- */
+/** Discover all resources available for syncing from ~/.agents/. */
 export function getAvailableResources(cwd = process.cwd()) {
     const result = {
         commands: [],
@@ -201,14 +182,7 @@ export function getAvailableResources(cwd = process.cwd()) {
         }
     }
     result.skills = filterNamesForActiveResourceProfile('skills', Array.from(skillNames), sourceMapFromResources('skills', cwd));
-    // Hooks:
-    //   - top-level script files
-    //   - one-level *group* dirs that contain top-level scripts (session-starts/*.sh)
-    //     → each script is its own hook resource (install name = basename)
-    //   - other directories (e.g. tests/ with fixtures only) → directory bundles,
-    //     copied wholesale as one resource (pre-existing layout)
-    // Auxiliary content like README.md / promptcuts.yaml is not a hook. Older sync
-    // runs chmod 0o755'd everything, so an exec bit alone is not the signal.
+    // Hooks: top-level scripts, expanded one-level group dirs, or whole-dir bundles. Exec bit alone is not the signal (older syncs chmod'd everything).
     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 HOOK_GROUP_SKIP = new Set(['node_modules', '.git', '.cache']);
@@ -238,8 +212,7 @@ export function getAvailableResources(cwd = process.cwd()) {
                 }
                 if (!stat.isDirectory() || HOOK_GROUP_SKIP.has(name))
                     continue;
-                // Group vs bundle: if the dir has any top-level script files, expand
-                // them; otherwise treat the whole dir as one hook resource.
+                // Expand dirs containing top-level scripts; bundle dirs without any.
                 let nestedNames;
                 try {
                     nestedNames = fs.readdirSync(full);
@@ -273,10 +246,7 @@ export function getAvailableResources(cwd = process.cwd()) {
         }
     }
     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
-    // the rules-dir getters so test mocks work the same as production paths.
+    // Rules — list available presets across layers.
     const presetNames = new Set();
     const rulesDirs = [];
     if (projectAgentsDir)
@@ -303,10 +273,8 @@ export function getAvailableResources(cwd = process.cwd()) {
     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 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) {
         const subagentsDir = path.join(base, 'subagents');
@@ -320,7 +288,6 @@ export function getAvailableResources(cwd = process.cwd()) {
         }
     }
     result.subagents = filterNamesForActiveResourceProfile('subagents', Array.from(subagentNames), sourceMapFromResources('subagents', cwd));
-    // Workflows (directories with WORKFLOW.md)
     const workflowSources = sourceMapFromWorkflows(cwd);
     result.workflows = filterNamesForActiveResourceProfile('workflows', Array.from(workflowSources.keys()), workflowSources);
     // Plugins (directories with .claude-plugin/plugin.json)
@@ -342,10 +309,7 @@ const SKILL_COPY_IGNORE = new Set(['.DS_Store', '.git', '.gitignore', '.venv', '
 function shouldSkillEntryBeSkipped(name) {
     return SKILL_COPY_IGNORE.has(name);
 }
-/**
- * Recursively compare two directories: every file in src must exist in dest with identical content.
- * Skips the same entries that copyDir skips (symlinks and SKILL_COPY_IGNORE members).
- */
+/** Recursively compare two directories for identical content, skipping symlinks and ignored entries. */
 function skillDirsMatch(src, dest) {
     const entries = fs.readdirSync(src, { withFileTypes: true });
     for (const entry of entries) {
@@ -362,9 +326,7 @@ function skillDirsMatch(src, dest) {
                 return false;
         }
         else {
-            // Stat-first (RUSH-2320 #2): size mismatch = definitive miss, no reads.
-            // Equal mtimes across different trees are accidental — content-compare
-            // whenever sizes match.
+            // Size-first check avoids reads on mismatch; equal mtimes are unreliable across trees.
             let srcStat;
             let destStat;
             try {
@@ -382,10 +344,7 @@ function skillDirsMatch(src, dest) {
     }
     return true;
 }
-/**
- * Get what's ACTUALLY synced to a version by inspecting the version home.
- * This is the source of truth - not the tracking in agents.yaml.
- */
+/** Return what's actually synced to a version home (source of truth, not agents.yaml tracking). */
 export function getActuallySyncedResources(agent, version, options = {}) {
     const versionHome = path.join(getVersionsDir(), agent, version, 'home');
     const cwd = options.cwd || process.cwd();
@@ -401,10 +360,7 @@ export function getActuallySyncedResources(agent, version, options = {}) {
         workflows: [],
         promptcuts: false,
     };
-    // Dispatch each kind through DETECTORS. The registry guarantees a detector
-    // exists for every supported (agent, kind) pair; unsupported pairs leave
-    // the field empty. The previous per-agent if-ladder silently dropped
-    // antigravity/gemini/grok detection — see PR description for details.
+    // Dispatch through per-kind detectors; unsupported (agent, kind) pairs leave the field empty.
     const ctx = { version, versionHome, cwd };
     result.commands = getDetector('commands', agent)?.list(ctx) ?? [];
     result.skills = getDetector('skills', agent)?.list(ctx) ?? [];
@@ -417,14 +373,7 @@ export function getActuallySyncedResources(agent, version, options = {}) {
     result.workflows = getDetector('workflows', agent)?.list(ctx) ?? [];
     return result;
 }
-/**
- * Names that exist ONLY in the project's `.agents/` layer (no matching entry in
- * user/system/extra layers). Sync intentionally skips project-layer commands,
- * skills, hooks, subagents, plugins, and workflows for security — see the
- * defense comments above each sync branch in syncResourcesToVersion. Without
- * this filter, those names would forever appear in the "New resources" diff
- * because they live in `available` but never reach `actuallySynced`.
- */
+/** Names that exist only in the project's `.agents/` layer. Sync skips project-layer resources for security, so filter them out of the "new resources" diff. */
 export function getProjectOnlyResources(cwd = process.cwd()) {
     const empty = {
         commands: new Set(), skills: new Set(), hooks: new Set(),
@@ -522,16 +471,7 @@ export function getProjectOnlyResources(cwd = process.cwd()) {
     }
     return empty;
 }
-/**
- * Compare available resources with what's ACTUALLY synced to version home.
- * Returns only NEW resources that haven't been synced yet.
- * Source of truth: the actual files/config, NOT agents.yaml tracking.
- *
- * `projectOnly` (recommended): the result of `getProjectOnlyResources(cwd)`.
- * Names listed there are filtered out for kinds that sync intentionally
- * excludes the project layer — otherwise they would re-appear as "new"
- * on every run and "Yes, sync all new" would silently do nothing for them.
- */
+/** Return resources in `available` that are not yet synced to the version home. `projectOnly` filters project-layer resources that sync skips for security. */
 export function getNewResources(available, actuallySynced, projectOnly) {
     const exclude = projectOnly || {
         commands: new Set(), skills: new Set(), hooks: new Set(),
@@ -541,8 +481,7 @@ export function getNewResources(available, actuallySynced, projectOnly) {
         commands: available.commands.filter(c => !actuallySynced.commands.includes(c) && !exclude.commands.has(c)),
         skills: available.skills.filter(s => !actuallySynced.skills.includes(s) && !exclude.skills.has(s)),
         hooks: available.hooks.filter(h => !actuallySynced.hooks.includes(h) && !exclude.hooks.has(h)),
-        // Memory/rules presets are mutually exclusive — only one can be active.
-        // If any preset is synced, don't report others as "new".
+        // Only one rules preset can be active; if any is synced, don't report others as new.
         memory: actuallySynced.memory.length > 0
             ? []
             : available.memory.filter(m => !actuallySynced.memory.includes(m)),
@@ -551,15 +490,11 @@ export function getNewResources(available, actuallySynced, projectOnly) {
         subagents: available.subagents.filter(s => !actuallySynced.subagents.includes(s) && !exclude.subagents.has(s)),
         plugins: available.plugins.filter(p => !actuallySynced.plugins.includes(p) && !exclude.plugins.has(p)),
         workflows: available.workflows.filter(w => !actuallySynced.workflows.includes(w) && !exclude.workflows.has(w)),
-        // Promptcuts aren't version-scoped — the hook reads ~/.agents/promptcuts.yaml
-        // directly, so there is never a "new" per-version state to reconcile.
+        // Promptcuts are not version-scoped; the hook reads the user/system file directly.
         promptcuts: false,
     };
 }
-/**
- * Check if there are any new resources to sync.
- * When version is provided, uses version-specific capability checks.
- */
+/** Return true when `diff` contains any resources the agent/version actually supports. */
 export function hasNewResources(diff, agent, version) {
     const commandsApply = agent ? supports(agent, 'commands', version).ok : true;
     const hooksApply = agent ? supports(agent, 'hooks', version).ok : true;
@@ -578,16 +513,11 @@ export function hasNewResources(diff, agent, version) {
         (diff.plugins.length > 0 && pluginsApply) ||
         (diff.workflows.length > 0 && workflowsApply));
 }
-/**
- * Build a summary string of new resources.
- * E.g., "2 commands, 5 permission groups"
- */
+/** Build a human-readable summary of new resources, e.g. "2 commands, 5 permission groups". */
 function buildNewResourcesSummary(newResources, agent, version) {
     const agentConfig = AGENTS[agent];
     const parts = [];
-    // Use version-aware gates so Codex >= 0.117.0 (which converts commands to skills) doesn't
-    // double-count and so "16 commands" never appears in the summary when commands have
-    // already been emitted as skills in the version home.
+    // Version-aware gates avoid double-counting commands already emitted as skills (Codex >= 0.117.0).
     const commandsApply = supports(agent, 'commands', version).ok;
     const commandsAsSkills = version ? shouldInstallCommandAsSkill(agent, version) : false;
     const rulesApply = supports(agent, 'rules', version).ok;
@@ -620,10 +550,7 @@ function buildNewResourcesSummary(newResources, agent, version) {
     }
     return parts.join(', ');
 }
-/**
- * Prompt user to select which NEW resources to sync.
- * Only shows resources that haven't been synced yet.
- */
+/** Prompt the user to select which new resources to sync. */
 export async function promptNewResourceSelection(agent, newResources, version) {
     const agentConfig = AGENTS[agent];
     const selection = {};
@@ -634,15 +561,12 @@ export async function promptNewResourceSelection(agent, newResources, version) {
     const commandsAsSkills = version ? shouldInstallCommandAsSkill(agent, version) : false;
     const commandsBranch = commandsApply || commandsAsSkills;
     const rulesBranch = supports(agent, 'rules', version).ok;
-    // Get permission group info for display
     const permissionGroups = discoverPermissionGroups();
     const newPermissionGroups = permissionGroups.filter(g => newResources.permissions.includes(g.name));
     const totalNewPermissionRules = newPermissionGroups.reduce((sum, g) => sum + g.ruleCount, 0);
-    // Build the summary
     const summary = buildNewResourcesSummary(newResources, agent, version);
     console.log(chalk.cyan(`\nNew resources available:`));
     console.log(chalk.gray(`  ${summary}`));
-    // Ask how to handle new resources
     const action = await select({
         message: 'Sync new resources?',
         choices: [
@@ -656,7 +580,6 @@ export async function promptNewResourceSelection(agent, newResources, version) {
         return null;
     }
     if (action === 'all') {
-        // Sync all new resources
         if (newResources.commands.length > 0 && commandsBranch)
             selection.commands = newResources.commands;
         if (newResources.skills.length > 0)
@@ -677,7 +600,6 @@ export async function promptNewResourceSelection(agent, newResources, version) {
             selection.workflows = newResources.workflows;
         return selection;
     }
-    // Select specific items for each category
     if (newResources.commands.length > 0 && commandsBranch) {
         const selected = await checkbox({
             message: 'Select new commands to sync:',
@@ -762,15 +684,11 @@ export async function promptNewResourceSelection(agent, newResources, version) {
     }
     return selection;
 }
-/**
- * Prompt user to select which resources to sync from ~/.agents/.
- * Returns the selection, or null if user cancels.
- */
+/** Prompt the user to select which resources to sync from ~/.agents/. */
 export async function promptResourceSelection(agent) {
     const available = getAvailableResources();
     const agentConfig = AGENTS[agent];
     const selection = {};
-    // Get permission group info for display
     const permissionGroups = discoverPermissionGroups();
     const totalPermissionRules = permissionGroups.reduce((sum, g) => sum + g.ruleCount, 0);
     const categories = [
@@ -788,7 +706,6 @@ export async function promptResourceSelection(agent) {
         console.log(chalk.gray('No resources available to sync.'));
         return {};
     }
-    // Step 1: Select categories (with "Select All" shortcut at the top)
     console.log();
     const SELECT_ALL_KEY = '__select_all__';
     const selectedCategories = await checkbox({
@@ -805,7 +722,6 @@ export async function promptResourceSelection(agent) {
     if (selectedCategories.length === 0) {
         return {};
     }
-    // If "Select All" was picked, or all individual categories are selected, sync everything without per-category prompts
     const allCategoryKeys = availableCategories.map(c => c.key);
     if (selectedCategories.includes(SELECT_ALL_KEY) || allCategoryKeys.every(k => selectedCategories.includes(k))) {
         for (const c of availableCategories) {
@@ -813,10 +729,8 @@ export async function promptResourceSelection(agent) {
         }
         return selection;
     }
-    // Step 2: For each selected category, ask all/specific/skip
     for (const category of selectedCategories) {
         const categoryLabel = categories.find(c => c.key === category).label;
-        // Special handling for permissions - show groups
         if (category === 'permissions') {
             const choice = await select({
                 message: `${categoryLabel}:`,
@@ -845,7 +759,6 @@ export async function promptResourceSelection(agent) {
             }
         }
         else {
-            // Standard handling for other categories
             const items = available[category];
             const choice = await select({
                 message: `${categoryLabel}:`,
@@ -877,13 +790,7 @@ export async function promptResourceSelection(agent) {
     }
     return selection;
 }
-/**
- * Parse agent@version syntax.
- * Examples:
- *   "claude@1.5.0" -> { agent: "claude", version: "1.5.0" }
- *   "claude" -> { agent: "claude", version: "latest" }
- *   "codex@latest" -> { agent: "codex", version: "latest" }
- */
+/** Parse an `agent@version` spec; bare agent means `latest`. */
 export function parseAgentSpec(spec) {
     const parts = spec.split('@');
     if (parts.length > 2) {
@@ -904,9 +811,6 @@ export function parseAgentSpec(spec) {
         version,
     };
 }
-/**
- * Get the latest available version from npm for an agent.
- */
 export async function getLatestNpmVersion(agent) {
     const agentConfig = AGENTS[agent];
     if (!agentConfig.npmPackage)
@@ -919,9 +823,6 @@ export async function getLatestNpmVersion(agent) {
         return null;
     }
 }
-/**
- * Get the oldest published version from npm for an agent.
- */
 export async function getOldestNpmVersion(agent) {
     const agentConfig = AGENTS[agent];
     if (!agentConfig.npmPackage)
@@ -929,8 +830,7 @@ export async function getOldestNpmVersion(agent) {
     try {
         const { stdout } = await execFileAsync('npm', ['view', agentConfig.npmPackage, 'versions', '--json'], { shell: process.platform === 'win32' });
         const parsed = JSON.parse(stdout.trim());
-        // `npm view ... versions --json` returns an array (multiple versions) or a
-        // bare string (single published version). Normalize to an array.
+        // npm view returns an array for multiple versions or a bare string for one.
         const versions = Array.isArray(parsed) ? parsed : [parsed];
         const sorted = versions.filter((v) => VERSION_RE.test(v)).sort(compareVersions);
         return sorted[0] ?? null;
@@ -939,9 +839,7 @@ export async function getOldestNpmVersion(agent) {
         return null;
     }
 }
-/**
- * Check if 'latest' version is already installed (by resolving to actual version).
- */
+/** Check whether the npm `latest` version is installed. */
 export async function isLatestInstalled(agent) {
     const latestVersion = await getLatestNpmVersion(agent);
     if (!latestVersion) {
@@ -949,9 +847,7 @@ export async function isLatestInstalled(agent) {
     }
     return { installed: isVersionInstalled(agent, latestVersion), version: latestVersion };
 }
-/**
- * Check if 'oldest' published version is already installed (by resolving to actual version).
- */
+/** Check whether the npm `oldest` version is installed. */
 export async function isOldestInstalled(agent) {
     const oldestVersion = await getOldestNpmVersion(agent);
     if (!oldestVersion) {
@@ -960,12 +856,9 @@ export async function isOldestInstalled(agent) {
     return { installed: isVersionInstalled(agent, oldestVersion), version: oldestVersion };
 }
 /**
- * List every version directory for an agent, including ones missing the
- * binary (typically home-only leftovers from a prior `removeVersion`).
- *
- * Used by `agents prune cleanup` to surface stale installs that the regular
- * `listInstalledVersions` filters out. Do NOT use elsewhere — every other
- * call site assumes a working binary.
+ * List every version directory for an agent, including home-only leftovers, for
+ * `agents prune cleanup` only. Do NOT use elsewhere — every other call site
+ * assumes a working binary.
  */
 export function listInstalledVersionDirs(agent) {
     const agentVersionsDir = path.join(getVersionsDir(), agent);
@@ -984,15 +877,9 @@ export function listInstalledVersionDirs(agent) {
     }
     return out.sort((a, b) => compareVersions(a.version, b.version));
 }
-/**
- * Set the global default version for an agent.
- */
+/** Set (or clear) the global default version for an agent. */
 export function setGlobalDefault(agent, version) {
-    // A global default is what owns the launcher and arms the self-heal `shadowing`
-    // check, so recording one for an isolated-only agent is the root of the original
-    // breach. Clearing is always allowed — `removeVersion` legitimately clears a
-    // default as the last non-isolated version goes away, which is the very moment
-    // an agent BECOMES isolated-only.
+    // Setting a global default for an isolated-only agent would breach the isolation boundary; clearing is allowed.
     if (version !== undefined) {
         assertIsolationBoundary(agent, 'set a global default');
     }
@@ -1009,13 +896,7 @@ export function setGlobalDefault(agent, version) {
     }
     writeMeta(meta);
 }
-/**
- * Set (or clear, with `undefined`) the preferred isolated version.
- *
- * Deliberately does NOT touch the launcher, the bare shim, the `~/.<agent>` config
- * symlink or the global default — the five things `setDefaultVersion` does. This is
- * a pointer inside the sandbox, so it stays inside the sandbox.
- */
+/** Set (or clear) the preferred isolated version without touching the launcher, shim, or global default. */
 export function setIsolatedDefault(agent, version) {
     const meta = readMeta();
     if (!meta.isolatedAgents) {
@@ -1147,18 +1028,14 @@ async function checkGrokAccountCollision(installedVersion) {
         `Grok's self-updater can't distinguish two accounts that land on the same release — sign in to ${targetEmail}'s ` +
         `install (agents use grok@${installedVersion}) before updating it, or wait until the releases diverge.`);
 }
-/**
- * Install a specific version of an agent.
- */
+/** Install a specific version of an agent. */
 export async function installVersion(agent, version, onProgress, opts) {
     const agentConfig = AGENTS[agent];
     const requestedLabel = version;
     if (isAgentHardDeprecated(agent)) {
         return { success: false, installedVersion: version, error: hardDeprecationError(agent) };
     }
-    // Validate before deriving filesystem paths or npm package specs. The CLI
-    // parser already enforces this for user input; this guard protects direct
-    // callers and tests the critical install path at the source.
+    // Also validate at the source so direct callers and tests cannot pass invalid versions.
     if (!VERSION_RE.test(version)) {
         throw new Error(`Invalid version: ${JSON.stringify(version)}`);
     }
@@ -1166,12 +1043,7 @@ export async function installVersion(agent, version, onProgress, opts) {
         if (!agentConfig.installScript) {
             return { success: false, installedVersion: version, error: 'Agent has no npm package' };
         }
-        // A self-updating agent (droid, grok, …) is a single global binary whose
-        // installer only ever fetches the CURRENT release — there is no semver to
-        // pin. Rather than hard-refuse `<agent>@1.2.3` (the old behavior):
-        //   - if the binary is already installed, a pin is a no-op — it self-updates
-        //     in place, so skip the installer and just refresh our bookkeeping;
-        //   - otherwise redirect the pin to a current-release install.
+        // Self-updating agents have no pinnable semver; an installed binary is a no-op, otherwise redirect to latest.
         let runInstaller = true;
         if (version !== 'latest' && isSelfUpdatingAgent(agent)) {
             const liveVersion = await getLiveVersion(agent);
@@ -1624,7 +1496,7 @@ export async function reconcileStaleLatestDir(agent, installedVersion) {
  * re-install) without collision and gives a chronological audit trail.
  *
  * The whole versionDir moves — including `home/` (transcripts, sessions). The
- * user can recover everything via `agents trash restore <agent>@<version>`.
+ * user can recover everything via `agents restore <agent>@<version>`.
  * Nothing is ever hard-deleted.
  */
 export function softDeleteVersionDir(agent, version) {
@@ -1658,7 +1530,7 @@ export function softDeleteVersionDir(agent, version) {
  * Remove a specific version of an agent.
  *
  * Soft-delete only: moves the entire version directory (including `home/`)
- * to ~/.agents/.system/trash/versions/. Recoverable via `agents trash restore`.
+ * to ~/.agents/.system/trash/versions/. Recoverable via `agents restore`.
  * Nothing is hard-deleted.
  */
 export function removeVersion(agent, version) {
@@ -1814,24 +1686,7 @@ export async function healDanglingVersionPointers(agent, cwd) {
     }
     return healed;
 }
-/**
- * Normalize a user-supplied @version token across CLI subcommands.
- *
- *   undefined / "" / "default" / "pinned" -> undefined  (caller falls back to project pin or global default)
- *   "any"                       -> undefined  (caller imposes no version constraint — e.g. resume across any version)
- *   "latest"                    -> highest installed version (process.exit if none installed)
- *   "oldest"                    -> lowest installed version (process.exit if none installed)
- *   "x.y.z" (installed)         -> "x.y.z"
- *   "x.y.z" (not installed)     -> process.exit with installed-list hint
- *
- * `pinned` is a synonym for `default`: both name the project pin / global
- * default, which the caller resolves.
- *
- * Use this anywhere the user can type `agents <cmd> claude@<token>` to keep the
- * vocabulary consistent. Subcommands with different semantics for `latest`
- * (install/remove/use, where `latest` means npm-latest) keep their existing
- * parsing.
- */
+/** Normalize a user-supplied `@version` token. `default`/`pinned`/`any` → undefined; `latest`/`oldest` → extreme installed version; concrete versions must be installed. */
 export function resolveVersionAlias(agent, raw) {
     if (!raw || raw === 'default' || raw === 'pinned' || raw === 'any')
         return undefined;
@@ -2911,11 +2766,7 @@ export function syncResourcesToVersion(agent, version, selection, options = {})
     }
     return result;
 }
-/**
- * Thrown when the user references an agent@version that is not installed.
- * Carries the parsed (agentId, version) so callers can react — e.g. prompt
- * to install it on demand — without having to parse the error message.
- */
+/** Thrown when an `agent@version` target is not installed; carries the parsed ids so callers can react without parsing the message. */
 export class VersionNotInstalledError extends Error {
     agentId;
     version;
@@ -2929,11 +2780,7 @@ export class VersionNotInstalledError extends Error {
         this.name = 'VersionNotInstalledError';
     }
 }
-/**
- * Resolve a comma-separated --agents list into concrete version selections.
- * Bare agents target the default version, or the newest installed version when no default exists.
- * Explicit agent@version targets only that installed version.
- */
+/** Resolve a comma-separated `--agents` list into concrete installed version selections. */
 export function resolveAgentVersionTargets(value, availableAgents, options = {}) {
     const selectedAgents = [];
     const versionSelections = new Map();
@@ -3025,12 +2872,7 @@ export function resolveAgentVersionTargets(value, availableAgents, options = {})
     }
     return { selectedAgents, versionSelections };
 }
-/**
- * Resolve a comma-separated --agents list into install/apply targets.
- * Bare agents target the default version (or newest installed version) when managed,
- * and fall back to the agent's effective HOME when unmanaged.
- * Explicit agent@version targets only that installed version.
- */
+/** Resolve a comma-separated `--agents` list into install/apply targets, distinguishing managed versions from direct homes. */
 export function resolveInstalledAgentTargets(value, availableAgents, options = {}) {
     const selectedAgents = [];
     const directAgents = [];
@@ -3128,9 +2970,7 @@ export function resolveInstalledAgentTargets(value, availableAgents, options = {
     }
     return { selectedAgents, directAgents, versionSelections };
 }
-/**
- * Resolve configured manifest targets into direct homes and managed versions.
- */
+/** Resolve configured manifest targets into direct homes and managed versions. */
 export function resolveConfiguredAgentTargets(agents, agentVersions, availableAgents, options = {}) {
     const targetSpecs = [];
     const broadTargets = agents ? [...agents] : [...availableAgents];
@@ -3157,10 +2997,7 @@ export function resolveConfiguredAgentTargets(agents, agentVersions, availableAg
     }
     return resolveInstalledAgentTargets(targetSpecs.join(','), availableAgents, options);
 }
-/**
- * Prompt user to select agents and versions for resource installation.
- * Returns selected agents and their version selections.
- */
+/** Prompt the user to select agents and versions for resource installation. */
 export async function promptAgentVersionSelection(availableAgents, options = {}) {
     const versionSelections = new Map();
     // Filter to installed agents (only those with versions managed by agents CLI)

package/dist/lib/perf/db.d.ts

@@ -1,7 +1,7 @@
 /**
  * Disposable performance warehouse — SQLite under ~/.agents/.cache/perf/.
  *
- * Opened only by `agents perf` / `hooks profile` (read path). Writers use
+ * Opened only by `agents insights perf` / `hooks profile` (read path). Writers use
  * {@link recordSample} in `./spool.ts` (NDJSON, no SQLite).
  */
 import Database from '../sqlite.js';

package/dist/lib/perf/db.js

@@ -1,7 +1,7 @@
 /**
  * Disposable performance warehouse — SQLite under ~/.agents/.cache/perf/.
  *
- * Opened only by `agents perf` / `hooks profile` (read path). Writers use
+ * Opened only by `agents insights perf` / `hooks profile` (read path). Writers use
  * {@link recordSample} in `./spool.ts` (NDJSON, no SQLite).
  */
 import * as fs from 'fs';

package/dist/lib/plugins/skills.d.ts

@@ -79,7 +79,14 @@ export declare function skillContentMatches(agentId: AgentId, skillName: string,
 export declare function listCentralSkills(): string[];
 /**
  * Resolve a skill name to its source directory. Searches user dir first,
- * then system dir, then extra repos. Returns null if no source has a SKILL.md.
+ * then system dir, then extra repos, then plugin-bundled skills
+ * (`plugins/<plugin>/skills/<name>` under any trusted base). Returns null if no
+ * source has a SKILL.md.
+ *
+ * Crediting plugins here is load-bearing (PHNX-3185): a skill materialized from
+ * `plugins/design/skills/design` has a real source, so it must resolve — else
+ * `versionSkillMatches` finds no source and the skill reads as drifted, and
+ * {@link diffVersionSkills} classes it an orphan `prune cleanup` would delete.
  */
 export declare function resolveSkillSourcePath(skillName: string): string | null;
 /**

package/dist/lib/plugins/skills.js

@@ -16,6 +16,7 @@ import { capableAgents, isCapable } from '../capabilities.js';
 import { getUserSkillsDir, getSkillsDir as getSystemSkillsDir, getProjectAgentsDir, getEnabledExtraRepos, getTrashSkillsDir } from '../state.js';
 import { getEffectiveHome, getVersionHomePath, listInstalledVersions } from '../installations/store.js';
 import { listCommandSkillsInVersion } from '../command-skills.js';
+import { pluginSkillDirs, listPluginSkillNames } from '../staleness/writers/sources.js';
 import { emit } from '../feed/events.js';
 const HOME = os.homedir();
 /** User-scoped skills dir (~/.agents/skills/). Used for installs. */
@@ -352,7 +353,14 @@ export function listCentralSkills() {
 }
 /**
  * Resolve a skill name to its source directory. Searches user dir first,
- * then system dir, then extra repos. Returns null if no source has a SKILL.md.
+ * then system dir, then extra repos, then plugin-bundled skills
+ * (`plugins/<plugin>/skills/<name>` under any trusted base). Returns null if no
+ * source has a SKILL.md.
+ *
+ * Crediting plugins here is load-bearing (PHNX-3185): a skill materialized from
+ * `plugins/design/skills/design` has a real source, so it must resolve — else
+ * `versionSkillMatches` finds no source and the skill reads as drifted, and
+ * {@link diffVersionSkills} classes it an orphan `prune cleanup` would delete.
  */
 export function resolveSkillSourcePath(skillName) {
     for (const dir of [getUserSkillsDir(), getSystemSkillsDir()]) {
@@ -365,6 +373,11 @@ export function resolveSkillSourcePath(skillName) {
         if (fs.existsSync(path.join(candidate, 'SKILL.md')))
             return candidate;
     }
+    for (const skillsDir of pluginSkillDirs()) {
+        const candidate = path.join(skillsDir, skillName);
+        if (fs.existsSync(path.join(candidate, 'SKILL.md')))
+            return candidate;
+    }
     return null;
 }
 /**
@@ -443,7 +456,10 @@ function versionSkillMatches(agent, version, skillName) {
  * Compare a version home's skills against central. Returns the reconciliation diff.
  */
 export function diffVersionSkills(agent, version) {
-    const available = new Set(listAllSkills());
+    // Plugin-provided skills (`plugins/<plugin>/skills`) are legitimate sources too, so a
+    // skill materialized from a plugin is NOT an orphan (PHNX-3185). Without this
+    // the detector offered to delete the entire plugin-installed skill library.
+    const available = new Set([...listAllSkills(), ...listPluginSkillNames({ agent })]);
     // Goose and other native ~/.agents/skills consumers read central storage
     // directly. They intentionally have no per-version copy to diff, so every
     // available central skill is already current for every supported version.