@phnx-labs/agents-cli 1.19.1 → 1.20.0

package/dist/commands/setup.d.ts

@@ -9,6 +9,7 @@ import type { Command } from 'commander';
 export declare function runSetup(program: Command, options?: {
     force?: boolean;
     suppressFooter?: boolean;
+    systemRepo?: boolean;
 }): Promise<void>;
 /**
  * Ensure the system repo exists before running a command that needs it.

package/dist/commands/setup.js

@@ -68,38 +68,46 @@ export async function runSetup(program, options = {}) {
     for (const install of unmanaged) {
         sessionCounts[install.agentId] = countSessionFiles(install.agentId);
     }
+    const systemRepo = process.env.AGENTS_SYSTEM_REPO || DEFAULT_SYSTEM_REPO;
     console.log(chalk.bold('\nWelcome to agents-cli.'));
-    console.log(chalk.gray(`Cloning the system repo from ${systemRepoSlug(DEFAULT_SYSTEM_REPO)} into ~/.agents-system/.\n`));
-    ensureAgentsDir();
-    const spinner = ora('Cloning system repo...').start();
-    if (isGitRepo(agentsDir)) {
-        // --force on an existing repo: pull instead of re-clone
-        const result = await pullRepo(agentsDir);
-        if (!result.success) {
-            spinner.fail(`Pull failed: ${result.error}`);
-            console.log(chalk.gray('Fix the issue and re-run: agents setup --force'));
-            process.exit(1);
-        }
-        spinner.succeed(`Updated to ${result.commit}`);
+    if (options.systemRepo === false) {
+        ensureAgentsDir();
+        console.log(chalk.gray('Skipping system repo clone (--no-system-repo).'));
+        console.log(chalk.gray(`Populate ~/.agents-system/ yourself before running other commands that depend on it.\n`));
     }
     else {
-        // Check git is available
-        try {
-            const { execSync } = await import('child_process');
-            execSync('which git', { stdio: 'ignore' });
-        }
-        catch {
-            spinner.fail('git is not installed');
-            console.log(chalk.gray('Install git first: https://git-scm.com/downloads'));
-            process.exit(1);
+        console.log(chalk.gray(`Cloning the system repo from ${systemRepoSlug(systemRepo)} into ~/.agents-system/.\n`));
+        ensureAgentsDir();
+        const spinner = ora('Cloning system repo...').start();
+        if (isGitRepo(agentsDir)) {
+            // --force on an existing repo: pull instead of re-clone
+            const result = await pullRepo(agentsDir);
+            if (!result.success) {
+                spinner.fail(`Pull failed: ${result.error}`);
+                console.log(chalk.gray('Fix the issue and re-run: agents setup --force'));
+                process.exit(1);
+            }
+            spinner.succeed(`Updated to ${result.commit}`);
         }
-        const result = await cloneIntoExisting(DEFAULT_SYSTEM_REPO, agentsDir);
-        if (!result.success) {
-            spinner.fail(`Clone failed: ${result.error}`);
-            console.log(chalk.gray('Fix the issue and re-run: agents setup --force'));
-            process.exit(1);
+        else {
+            // Check git is available
+            try {
+                const { execSync } = await import('child_process');
+                execSync('which git', { stdio: 'ignore' });
+            }
+            catch {
+                spinner.fail('git is not installed');
+                console.log(chalk.gray('Install git first: https://git-scm.com/downloads'));
+                process.exit(1);
+            }
+            const result = await cloneIntoExisting(systemRepo, agentsDir);
+            if (!result.success) {
+                spinner.fail(`Clone failed: ${result.error}`);
+                console.log(chalk.gray('Fix the issue and re-run: agents setup --force'));
+                process.exit(1);
+            }
+            spinner.succeed(`Cloned ${systemRepoSlug(systemRepo)} (${result.commit})`);
         }
-        spinner.succeed(`Cloned ${systemRepoSlug(DEFAULT_SYSTEM_REPO)} (${result.commit})`);
     }
     // Offer to import existing unmanaged installations
     if (unmanaged.length > 0 && isInteractiveTerminal()) {
@@ -195,7 +203,8 @@ export function registerSetupCommand(program) {
     const setupCmd = program
         .command('setup')
         .description('First-time setup. Clones a config repo and installs agent CLIs.')
-        .option('-f, --force', 'Re-run setup even if ~/.agents-system/ already exists (use with caution)');
+        .option('-f, --force', 'Re-run setup even if ~/.agents-system/ already exists (use with caution)')
+        .option('--no-system-repo', 'Skip cloning the system repo (you must populate ~/.agents-system/ yourself)');
     setHelpSections(setupCmd, {
         examples: `
       # First-time setup (clones the system repo into ~/.agents-system/)

package/dist/commands/skills.js

@@ -394,17 +394,17 @@ Examples:
         .action(() => {
         console.error(chalk.red('"agents skills sync" is gone.'));
         console.error(chalk.gray('Sync runs automatically when you launch the agent.'));
-        console.error(chalk.gray('To remove orphans, use:  agents prune skills'));
+        console.error(chalk.gray('To remove orphans, use:  agents prune cleanup skills'));
         process.exit(1);
     });
-    // `skills prune` moved to the top-level `agents prune` command.
+    // `skills prune` moved to the top-level `agents prune cleanup` command.
     skillsCmd
         .command('prune', { hidden: true })
         .allowUnknownOption()
         .allowExcessArguments()
         .action(() => {
         console.error(chalk.red('"agents skills prune" moved.'));
-        console.error(chalk.gray('Use:  agents prune skills   (or `agents prune` for everything)'));
+        console.error(chalk.gray('Use:  agents prune cleanup skills   (or `agents prune cleanup` for everything)'));
         process.exit(1);
     });
     skillsCmd

package/dist/commands/teams.js

@@ -21,6 +21,8 @@ const AGENT_NAMES = {
     gemini: 'Gemini',
     cursor: 'Cursor',
     opencode: 'OpenCode',
+    grok: 'Grok',
+    antigravity: 'Antigravity',
 };
 const VALID_AGENTS = Object.keys(AGENT_NAMES);
 const VALID_MODES = ['plan', 'edit', 'full'];
@@ -756,6 +758,11 @@ export function registerTeamsCommands(program) {
                 die(`Invalid teammate name '${opts.name}'. Use letters, numbers, '-', or '_'.`);
             }
         }
+        if (opts.worktree !== undefined) {
+            if (!opts.worktree || !/^[A-Za-z0-9_-]+$/.test(opts.worktree)) {
+                die(`Invalid worktree name '${opts.worktree}'. Use letters, numbers, '-', or '_'.`);
+            }
+        }
         const after = opts.after
             ? opts.after.split(',').map((s) => s.trim()).filter(Boolean)
             : [];
@@ -899,6 +906,12 @@ export function registerTeamsCommands(program) {
             console.log();
             if (staged) {
                 console.log(chalk.gray(`Start the ready teammates:  agents teams start ${team}`));
+                if (after.length > 0) {
+                    process.stderr.write(chalk.yellow(`\nWarning: this teammate has --after dependencies and will NEVER start on its own.\n` +
+                        `  A supervisor watch process is required to launch it when its deps complete.\n` +
+                        `  Run this in another terminal:\n` +
+                        `    agents teams start ${team} --watch\n`));
+                }
             }
             else {
                 console.log(chalk.gray(`Check in later:  agents teams status ${team}`));

package/dist/commands/versions.d.ts

@@ -1,10 +1,11 @@
 /**
  * Version management commands for installing, switching, and removing agent CLIs.
  *
- * Implements `agents add`, `agents remove`, `agents use`, and the deprecated
- * `agents list`. Handles npm-based installation, shim creation, config symlink
+ * Implements `agents add`, `agents prune`, `agents remove` (alias),
+ * `agents use`, and the deprecated `agents list`. Handles npm-based installation,
+ * shim creation, config symlink
  * switching, resource sync prompts, and project-level version pinning.
  */
 import type { Command } from 'commander';
-/** Register `agents add`, `agents remove`, `agents use`, and `agents list` (deprecated). */
+/** Register `agents add`, `agents prune`, `agents remove`, `agents use`, and `agents list` (deprecated). */
 export declare function registerVersionsCommands(program: Command): void;

package/dist/commands/versions.js

@@ -7,12 +7,27 @@ import { AGENTS, ALL_AGENT_IDS, getAccountEmail, getAccountInfo, agentLabel, } f
 import { formatUsageSummary, getUsageInfoForIdentity, getUsageInfoByIdentity, getUsageLookupKey, } from '../lib/usage.js';
 import { viewAction } from './view.js';
 import { readManifest, writeManifest, createDefaultManifest } from '../lib/manifest.js';
-import { installVersion, removeVersion, listInstalledVersions, isVersionInstalled, isLatestInstalled, getGlobalDefault, setGlobalDefault, getVersionHomePath, syncResourcesToVersion, parseAgentSpec, promptResourceSelection, promptNewResourceSelection, getAvailableResources, getActuallySyncedResources, getNewResources, hasNewResources, } from '../lib/versions.js';
+import { installVersion, removeVersion, listInstalledVersions, isVersionInstalled, isLatestInstalled, getGlobalDefault, setGlobalDefault, getVersionHomePath, getVersionDir, syncResourcesToVersion, parseAgentSpec, promptResourceSelection, promptNewResourceSelection, getAvailableResources, getActuallySyncedResources, getNewResources, hasNewResources, printTrashFooter, } from '../lib/versions.js';
 import { createShim, createVersionedAlias, removeShim, shimExists, getShimsDir, getShimPath, getPathShadowingExecutable, isShimsInPath, getPathSetupInstructions, addShimsToPath, switchConfigSymlink, switchHomeFileSymlinks, } from '../lib/shims.js';
 import { isInteractiveTerminal, isPromptCancelled, requireInteractiveSelection } from './utils.js';
 import { tryAutoPull } from '../lib/git.js';
-import { getAgentsDir } from '../lib/state.js';
+import { getAgentsDir, getTrashVersionsDir } from '../lib/state.js';
 import { setHelpSections } from '../lib/help.js';
+import { updateSessionFilePaths } from '../lib/session/db.js';
+/**
+ * After removeVersion soft-deletes a version dir to trash, rewrite session
+ * file_path entries in the DB so reads still work from the new trash location.
+ */
+function fixSessionFilePaths(agent, version, oldVersionDir) {
+    const trashAgentDir = path.join(getTrashVersionsDir(), agent, version);
+    if (!fs.existsSync(trashAgentDir))
+        return;
+    const stamps = fs.readdirSync(trashAgentDir).sort().reverse();
+    if (stamps.length === 0)
+        return;
+    const trashPath = path.join(trashAgentDir, stamps[0]);
+    updateSessionFilePaths(oldVersionDir, trashPath);
+}
 /**
  * Helper to get actual installed version for an agent.
  * Returns the latest installed version, or throws if none installed.
@@ -78,7 +93,130 @@ function warnIfShimShadowed(agent) {
     console.log(chalk.gray(`  Managed shim: ${getShimPath(agent)}`));
     console.log(chalk.gray(`  ${getPathSetupInstructions().split('\n').join('\n  ')}`));
 }
-/** Register `agents add`, `agents remove`, `agents use`, and `agents list` (deprecated). */
+async function versionPruneAction(specs, options, commandName) {
+    const isProject = options.project;
+    const moved = [];
+    for (const spec of specs) {
+        const parsed = parseAgentSpec(spec);
+        if (!parsed) {
+            console.log(chalk.red(`Invalid agent: ${spec}`));
+            console.log(chalk.gray(`Format: <agent>[@version]. Available: ${ALL_AGENT_IDS.join(', ')}`));
+            continue;
+        }
+        const { agent, version } = parsed;
+        const agentConfig = AGENTS[agent];
+        if (version === 'latest' || !spec.includes('@')) {
+            const versions = listInstalledVersions(agent);
+            if (versions.length === 0) {
+                console.log(chalk.gray(`No versions of ${agentLabel(agentConfig.id)} installed`));
+                continue;
+            }
+            if (!isInteractiveTerminal()) {
+                requireInteractiveSelection(`Selecting ${agentLabel(agentConfig.id)} versions to ${commandName}`, [
+                    `agents ${commandName} ${agent}@${versions[0]}`,
+                ]);
+            }
+            const globalDefault = getGlobalDefault(agent);
+            const sortedVersions = [...versions].sort((a, b) => {
+                if (a === globalDefault)
+                    return -1;
+                if (b === globalDefault)
+                    return 1;
+                return 0;
+            });
+            try {
+                const toRemove = await checkbox({
+                    message: `Select ${agentLabel(agentConfig.id)} versions to ${commandName}:`,
+                    choices: sortedVersions.map((v) => ({
+                        name: v === globalDefault ? `${v} ${chalk.green('(default)')}` : v,
+                        value: v,
+                        checked: false,
+                    })),
+                });
+                if (toRemove.length === 0) {
+                    console.log(chalk.gray('No versions selected'));
+                    continue;
+                }
+                for (const v of toRemove) {
+                    const versionDir = getVersionDir(agent, v);
+                    removeVersion(agent, v);
+                    fixSessionFilePaths(agent, v, versionDir);
+                    console.log(chalk.green(`Moved ${agentLabel(agentConfig.id)}@${v} to trash`));
+                    moved.push({ agent, version: v });
+                }
+                if (globalDefault && toRemove.includes(globalDefault)) {
+                    setGlobalDefault(agent, undefined);
+                    console.log(chalk.yellow(`Default version removed. Run: agents use ${agent}@<version> to set a new default`));
+                }
+                const remaining = listInstalledVersions(agent);
+                if (remaining.length === 0) {
+                    removeShim(agent);
+                }
+            }
+            catch (err) {
+                if (isPromptCancelled(err)) {
+                    console.log(chalk.gray('Cancelled'));
+                    continue;
+                }
+                throw err;
+            }
+        }
+        else if (!isVersionInstalled(agent, version)) {
+            console.log(chalk.gray(`${agentLabel(agentConfig.id)}@${version} not installed`));
+        }
+        else {
+            const versionDir = getVersionDir(agent, version);
+            removeVersion(agent, version);
+            fixSessionFilePaths(agent, version, versionDir);
+            console.log(chalk.green(`Moved ${agentLabel(agentConfig.id)}@${version} to trash`));
+            moved.push({ agent, version });
+            const remaining = listInstalledVersions(agent);
+            if (remaining.length === 0) {
+                removeShim(agent);
+            }
+        }
+        if (isProject) {
+            const projectManifestPath = path.join(process.cwd(), '.agents', 'agents.yaml');
+            if (fs.existsSync(projectManifestPath)) {
+                const manifest = readManifest(process.cwd());
+                if (manifest?.agents?.[agent]) {
+                    delete manifest.agents[agent];
+                    writeManifest(process.cwd(), manifest);
+                    console.log(chalk.gray(`  Removed from .agents/agents.yaml`));
+                }
+            }
+        }
+    }
+    printTrashFooter(moved);
+}
+function configureVersionPruneCommand(cmd, commandName) {
+    const isAlias = commandName === 'remove';
+    cmd
+        .description(isAlias
+        ? 'Alias for agents prune. Uninstalls agent CLI versions.'
+        : 'Uninstall agent CLI versions. Moves version data to trash for recovery.')
+        .option('-p, --project', 'Also clear the pinned version from .agents/agents.yaml in the current project');
+    setHelpSections(cmd, {
+        examples: `
+      # Prune a specific version
+      agents ${commandName} claude@2.0.50
+
+      # Pick interactively if you omit the version
+      agents ${commandName} claude
+
+      # Prune and also clear the project pin
+      agents ${commandName} claude@2.0.50 --project
+    `,
+        notes: `
+      - Pruned version directories move to trash with their home/ data intact.
+      - Session file paths are rewritten so session history remains readable.
+      - Removing the default version unsets the default; run 'agents use' to pick a new one.
+      - Reinstall any time with 'agents add'.
+    `,
+    });
+    cmd.action((specs, options) => versionPruneAction(specs, options, commandName));
+}
+/** Register `agents add`, `agents prune`, `agents remove`, `agents use`, and `agents list` (deprecated). */
 export function registerVersionsCommands(program) {
     const addCmd = program
         .command('add <specs...>')
@@ -180,9 +318,9 @@ export function registerVersionsCommands(program) {
                                 selection = userSelection;
                             }
                         }
-                        else if (hasNewResources(newResources, agent)) {
+                        else if (hasNewResources(newResources, agent, installedVersion)) {
                             // Some synced, but NEW resources available - prompt for new only
-                            const userSelection = await promptNewResourceSelection(agent, newResources);
+                            const userSelection = await promptNewResourceSelection(agent, newResources, installedVersion);
                             if (userSelection) {
                                 selection = userSelection;
                             }
@@ -296,123 +434,8 @@ export function registerVersionsCommands(program) {
             }
         }
     });
-    const removeCmd = program
-        .command('remove <specs...>')
-        .description('Uninstall agent CLI versions. Frees disk space and removes the version\'s auth token.')
-        .option('-p, --project', 'Also clear the pinned version from .agents/agents.yaml in the current project');
-    setHelpSections(removeCmd, {
-        examples: `
-      # Remove a specific version
-      agents remove claude@2.0.50
-
-      # Pick interactively if you omit the version
-      agents remove claude
-
-      # Remove and also clear the project pin
-      agents remove claude@2.0.50 --project
-    `,
-        notes: `
-      - Removing the default version unsets the default; run 'agents use' to pick a new one.
-      - Reinstall any time with 'agents add'.
-    `,
-    });
-    removeCmd.action(async (specs, options) => {
-        const isProject = options.project;
-        for (const spec of specs) {
-            const parsed = parseAgentSpec(spec);
-            if (!parsed) {
-                console.log(chalk.red(`Invalid agent: ${spec}`));
-                console.log(chalk.gray(`Format: <agent>[@version]. Available: ${ALL_AGENT_IDS.join(', ')}`));
-                continue;
-            }
-            const { agent, version } = parsed;
-            const agentConfig = AGENTS[agent];
-            if (version === 'latest' || !spec.includes('@')) {
-                // Show picker for which versions to remove
-                const versions = listInstalledVersions(agent);
-                if (versions.length === 0) {
-                    console.log(chalk.gray(`No versions of ${agentLabel(agentConfig.id)} installed`));
-                    continue;
-                }
-                if (!isInteractiveTerminal()) {
-                    requireInteractiveSelection(`Selecting ${agentLabel(agentConfig.id)} versions to remove`, [
-                        `agents remove ${agent}@${versions[0]}`,
-                    ]);
-                }
-                const globalDefault = getGlobalDefault(agent);
-                // Sort versions with default first
-                const sortedVersions = [...versions].sort((a, b) => {
-                    if (a === globalDefault)
-                        return -1;
-                    if (b === globalDefault)
-                        return 1;
-                    return 0;
-                });
-                try {
-                    const toRemove = await checkbox({
-                        message: `Select ${agentLabel(agentConfig.id)} versions to remove:`,
-                        choices: sortedVersions.map((v) => ({
-                            name: v === globalDefault ? `${v} ${chalk.green('(default)')}` : v,
-                            value: v,
-                            checked: false, // All unchecked by default
-                        })),
-                    });
-                    if (toRemove.length === 0) {
-                        console.log(chalk.gray('No versions selected'));
-                        continue;
-                    }
-                    for (const v of toRemove) {
-                        removeVersion(agent, v);
-                        console.log(chalk.green(`Removed ${agentLabel(agentConfig.id)}@${v}`));
-                    }
-                    // Check if default was removed
-                    if (globalDefault && toRemove.includes(globalDefault)) {
-                        setGlobalDefault(agent, undefined);
-                        console.log(chalk.yellow(`Default version removed. Run: agents use ${agent}@<version> to set a new default`));
-                    }
-                    // Remove shim if no versions left
-                    const remaining = listInstalledVersions(agent);
-                    if (remaining.length === 0) {
-                        removeShim(agent);
-                    }
-                }
-                catch (err) {
-                    if (isPromptCancelled(err)) {
-                        console.log(chalk.gray('Cancelled'));
-                        continue;
-                    }
-                    throw err;
-                }
-            }
-            else {
-                // Remove specific version
-                if (!isVersionInstalled(agent, version)) {
-                    console.log(chalk.gray(`${agentLabel(agentConfig.id)}@${version} not installed`));
-                }
-                else {
-                    removeVersion(agent, version);
-                    console.log(chalk.green(`Removed ${agentLabel(agentConfig.id)}@${version}`));
-                    // Remove shim if no versions left
-                    const remaining = listInstalledVersions(agent);
-                    if (remaining.length === 0) {
-                        removeShim(agent);
-                    }
-                }
-            }
-            // Update project manifest if -p flag
-            if (isProject) {
-                const projectManifestPath = path.join(process.cwd(), '.agents', 'agents.yaml');
-                if (fs.existsSync(projectManifestPath)) {
-                    const manifest = readManifest(process.cwd());
-                    if (manifest?.agents?.[agent]) {
-                        delete manifest.agents[agent];
-                        writeManifest(process.cwd(), manifest);
-                        console.log(chalk.gray(`  Removed from .agents/agents.yaml`));
-                    }
-                }
-            }
-        }
-    });
+    configureVersionPruneCommand(program.command('prune <specs...>'), 'prune');
+    configureVersionPruneCommand(program.command('remove <specs...>', { hidden: true }), 'remove');
     const useCmd = program
         .command('use <agent> [version]')
         .description('Switch the active version for an agent. This is the only command that sets the default.')
@@ -619,9 +642,9 @@ export function registerVersionsCommands(program) {
                             }
                         }
                     }
-                    else if (hasNewResources(newResources, agentId)) {
+                    else if (hasNewResources(newResources, agentId, finalVersion)) {
                         // Has synced before, but NEW items available
-                        const userSelection = await promptNewResourceSelection(agentId, newResources);
+                        const userSelection = await promptNewResourceSelection(agentId, newResources, finalVersion);
                         if (userSelection && Object.keys(userSelection).length > 0) {
                             const syncResult = syncResourcesToVersion(agentId, finalVersion, userSelection);
                             const syncedTypes = [];

package/dist/commands/view.js

@@ -5,7 +5,7 @@ import * as path from 'path';
 import { AGENTS, ALL_AGENT_IDS, getAllCliStates, getAccountInfo, resolveAgentName, formatAgentError, agentLabel, colorAgent, } from '../lib/agents.js';
 import { formatUsageSection, formatUsageSummary, getUsageInfoForIdentity, getUsageInfoByIdentity, getUsageLookupKey, } from '../lib/usage.js';
 import { readManifest } from '../lib/manifest.js';
-import { listInstalledVersions, listInstalledVersionDirs, getGlobalDefault, getVersionHomePath, getVersionDir, resolveVersionAlias, getAvailableResources, getActuallySyncedResources, getNewResources, hasNewResources, promptNewResourceSelection, syncResourcesToVersion, removeVersion, } from '../lib/versions.js';
+import { listInstalledVersions, listInstalledVersionDirs, getGlobalDefault, getVersionHomePath, getVersionDir, resolveVersionAlias, getAvailableResources, getActuallySyncedResources, getNewResources, hasNewResources, promptNewResourceSelection, syncResourcesToVersion, removeVersion, printTrashFooter, } from '../lib/versions.js';
 import { getShimsDir, isShimsInPath, ensureVersionedAliasCurrent, removeShim, } from '../lib/shims.js';
 import { getAgentResources } from '../lib/resources.js';
 import { WORKFLOW_CAPABLE_AGENTS } from '../lib/workflows.js';
@@ -366,7 +366,7 @@ async function showInstalledVersions(filterAgentId) {
             const newResources = getNewResources(available, synced);
             if (hasNewResources(newResources, filterAgentId, defaultVersion)) {
                 try {
-                    const selection = await promptNewResourceSelection(filterAgentId, newResources);
+                    const selection = await promptNewResourceSelection(filterAgentId, newResources, defaultVersion);
                     if (selection && Object.keys(selection).length > 0) {
                         const result = syncResourcesToVersion(filterAgentId, defaultVersion, selection);
                         const synced = [];
@@ -833,13 +833,12 @@ async function buildAgentPrunePlan(agentId) {
     return { agentId, toPrune, skippedDefaults };
 }
 async function executePrunePlan(plan) {
-    let removed = 0;
+    const moved = [];
     for (const p of plan.toPrune) {
-        console.log(chalk.gray(`Removing ${agentLabel(p.agentId)}@${p.version}...`));
         const ok = removeVersion(p.agentId, p.version);
         if (ok) {
-            console.log(chalk.green(`Removed ${agentLabel(p.agentId)}@${p.version}`));
-            removed++;
+            console.log(chalk.green(`Moved ${agentLabel(p.agentId)}@${p.version} to trash`));
+            moved.push({ agent: p.agentId, version: p.version });
         }
         else {
             console.log(chalk.yellow(`Already gone: ${agentLabel(p.agentId)}@${p.version}`));
@@ -848,7 +847,7 @@ async function executePrunePlan(plan) {
     if (listInstalledVersions(plan.agentId).length === 0) {
         removeShim(plan.agentId);
     }
-    return removed;
+    return moved;
 }
 function printPrunePlan(plan, isFirst) {
     if (plan.skippedDefaults.length > 0) {
@@ -897,7 +896,7 @@ export async function pruneDuplicates(filterAgentId, yes, dryRun) {
         return;
     }
     const totalCandidates = actionable.reduce((n, plan) => n + plan.toPrune.length, 0);
-    let totalRemoved = 0;
+    const allMoved = [];
     let isFirst = true;
     let processedAny = false;
     for (const plan of actionable) {
@@ -916,10 +915,10 @@ export async function pruneDuplicates(filterAgentId, yes, dryRun) {
             if (!isInteractiveTerminal()) {
                 console.log(chalk.red('Refusing to prune in a non-interactive shell without --yes.'));
                 if (filterAgentId) {
-                    console.log(chalk.gray(`Re-run with: agents prune ${filterAgentId} --dry-run`));
+                    console.log(chalk.gray(`Re-run with: agents prune cleanup ${filterAgentId} --dry-run`));
                 }
                 else {
-                    console.log(chalk.gray('Re-run with: agents prune --dry-run'));
+                    console.log(chalk.gray('Re-run with: agents prune cleanup --dry-run'));
                 }
                 process.exit(1);
             }
@@ -943,7 +942,7 @@ export async function pruneDuplicates(filterAgentId, yes, dryRun) {
                 break;
             }
         }
-        totalRemoved += await executePrunePlan(plan);
+        allMoved.push(...(await executePrunePlan(plan)));
         processedAny = true;
         isFirst = false;
         console.log();
@@ -953,7 +952,8 @@ export async function pruneDuplicates(filterAgentId, yes, dryRun) {
         return;
     }
     if (processedAny) {
-        console.log(chalk.bold(`Pruned ${totalRemoved} version${totalRemoved === 1 ? '' : 's'}.`));
+        console.log(chalk.bold(`Pruned ${allMoved.length} version${allMoved.length === 1 ? '' : 's'}.`));
+        printTrashFooter(allMoved);
     }
 }
 /**

package/dist/index.js

@@ -66,6 +66,7 @@ import { registerSkillsCommands } from './commands/skills.js';
 import { registerRulesCommands } from './commands/rules.js';
 import { registerPermissionsCommands } from './commands/permissions.js';
 import { registerMcpCommands } from './commands/mcp.js';
+import { registerCliCommands } from './commands/cli.js';
 import { registerVersionsCommands } from './commands/versions.js';
 import { registerImportCommand } from './commands/import.js';
 import { registerPackagesCommands } from './commands/packages.js';
@@ -120,11 +121,12 @@ Quick start:
   agents sessions                 Browse past sessions across all agents
 
 Agent versions:
-  add <agent>[@version]           Install an agent CLI (e.g. agents add codex)
+  add <agent>[@version]           Install an agent CLI (e.g. agents add grok or agents add codex)
   import <agent>                  Adopt an existing global install (npm/homebrew) into agents-cli
-  remove <agent>[@version]        Uninstall a version
+  prune <agent>[@version]         Uninstall a version
+  remove <agent>[@version]        Alias for prune
   use <agent>@<version>           Set the default version
-  prune [target]                  Remove orphan resources and older duplicate version installs (targets: commands, sessions, runs, trash)
+  prune cleanup [target]          Remove orphan resources and older duplicate version installs
   trash                           Inspect and restore soft-deleted version directories
   view [agent[@version]]          List versions, or inspect one in detail
 
@@ -171,7 +173,7 @@ Automation tips:
   Pass explicit names/IDs         Avoid pickers: agents sessions <id> --markdown
   Use --yes for defaults          Auto-accept sync/default prompts on add/use/pull
   Use --names for central items   e.g. agents commands add --names review-pr,debug
-  Use agent@version targets       e.g. --agents claude@2.1.79,codex@default
+  Use agent@version targets       e.g. --agents grok@0.1.218,claude@2.1.79,codex@default
   Non-TTY shells apply defaults   Omitted required selections fail with a plain hint
 
 Options:
@@ -361,7 +363,13 @@ async function promptUpgrade(latestVersion) {
         console.log();
     }
 }
-/** Fire-and-forget: refresh the registry cache in background. Never blocks the command. */
+/**
+ * Background update check — fires once per 24h cache window.
+ * Network: GET registry.npmjs.org/@phnx-labs/agents-cli/latest.
+ * Disable: set AGENTS_CLI_DISABLE_AUTO_UPDATE=1 in shell rc.
+ *
+ * Fire-and-forget; never blocks the CLI's foreground operation.
+ */
 function refreshUpdateCacheInBackground() {
     fetch('https://registry.npmjs.org/@phnx-labs/agents-cli/latest', {
         signal: AbortSignal.timeout(2000),
@@ -529,6 +537,7 @@ program
     await program.parseAsync(['node', 'agents', ...args]);
 });
 registerMcpCommands(program);
+registerCliCommands(program);
 registerSubagentsCommands(program);
 registerPluginsCommands(program);
 registerWorkflowsCommands(program);
@@ -726,7 +735,13 @@ if (firstRun) {
 // Every command requires the system repo to be cloned first. `setup` is the
 // only exemption — it's the command that does the cloning.
 const SETUP_EXEMPT_COMMANDS = new Set(['setup', 'help']);
-if (!firstRun && requestedCommand && !SETUP_EXEMPT_COMMANDS.has(requestedCommand)) {
+// Help and version output are pure documentation — they must never gate on
+// setup, otherwise `agents <cmd> --help` becomes useless on a fresh box.
+const helpOrVersionRequested = passedArgs.some((arg) => arg === '--help' || arg === '-h' || arg === '--version' || arg === '-V');
+if (!firstRun &&
+    requestedCommand &&
+    !SETUP_EXEMPT_COMMANDS.has(requestedCommand) &&
+    !helpOrVersionRequested) {
     const { ensureInitialized } = await import('./commands/setup.js');
     await ensureInitialized(program);
 }
@@ -771,5 +786,18 @@ catch (err) {
     if (err instanceof Error && err.name === 'ExitPromptError') {
         process.exit(130);
     }
+    // Browser-daemon-not-running and CDP-not-reachable surface as typed errors
+    // from src/lib/browser/. Don't dump a Node stacktrace for these — they are
+    // user-actionable, not engineering bugs. See issues #41 and #43.
+    if (err instanceof Error) {
+        const isBrowserDaemonNotRunning = err.name === 'BrowserDaemonNotRunningError';
+        const isBrowserCdpUnreachable = err.name === 'BrowserCdpConnectionError';
+        const isBrowserIpcDown = err.message.startsWith('IPC error:') &&
+            (err.message.includes('ECONNREFUSED') || err.message.includes('ENOENT'));
+        if (isBrowserDaemonNotRunning || isBrowserCdpUnreachable || isBrowserIpcDown) {
+            console.error(err.message);
+            process.exit(1);
+        }
+    }
     throw err;
 }