@phnx-labs/agents-cli 0.1.0 → 1.14.1

package/dist/commands/alias.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Alias command -- create top-level shim binaries that expand to `agents <subcommand>`.
+ *
+ * Generates executable scripts in ~/.agents/shims/ (already on PATH from the
+ * standard agents-cli install). Running `teams` becomes equivalent to
+ * `agents teams`. Aliases are tracked in ~/.agents/aliases.json so we can
+ * list, regenerate, or remove them without scanning the shims directory
+ * (which also holds agent CLI shims like claude/codex/gemini).
+ */
+import type { Command } from 'commander';
+export declare function registerAliasCommand(program: Command): void;

package/dist/commands/alias.js

@@ -0,0 +1,117 @@
+import chalk from 'chalk';
+import * as fs from 'fs';
+import * as path from 'path';
+import { getAgentsDir } from '../lib/state.js';
+import { getShimsDir } from '../lib/shims.js';
+import { ALL_AGENT_IDS, AGENTS } from '../lib/agents.js';
+const ALIASES_FILE = path.join(getAgentsDir(), 'aliases.json');
+/** Names that would clobber an agent CLI shim or the `agents` binary itself. */
+function reservedNames() {
+    const reserved = new Set(['agents']);
+    for (const id of ALL_AGENT_IDS)
+        reserved.add(AGENTS[id].cliCommand);
+    return reserved;
+}
+function readAliases() {
+    if (!fs.existsSync(ALIASES_FILE))
+        return {};
+    try {
+        const parsed = JSON.parse(fs.readFileSync(ALIASES_FILE, 'utf-8'));
+        return parsed && typeof parsed === 'object' ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+function writeAliases(map) {
+    fs.mkdirSync(path.dirname(ALIASES_FILE), { recursive: true });
+    fs.writeFileSync(ALIASES_FILE, JSON.stringify(map, null, 2) + '\n', 'utf-8');
+}
+function shimPath(name) {
+    return path.join(getShimsDir(), name);
+}
+function generateAliasShim(name, expansion) {
+    return `#!/bin/bash
+# Auto-generated by agents-cli - do not edit
+# Alias shim: ${name} -> agents ${expansion}
+exec agents ${expansion} "$@"
+`;
+}
+function isAliasShim(filePath) {
+    try {
+        const head = fs.readFileSync(filePath, 'utf-8').slice(0, 200);
+        return head.includes('# Alias shim:');
+    }
+    catch {
+        return false;
+    }
+}
+export function registerAliasCommand(program) {
+    const cmd = program
+        .command('alias')
+        .description('Create shorthand binaries that expand to `agents <subcommand>`');
+    cmd
+        .command('add <name> [expansion...]')
+        .description('Create an alias shim. If expansion is omitted, defaults to <name>.')
+        .action((name, expansion) => {
+        const expanded = expansion.length > 0 ? expansion.join(' ') : name;
+        if (!/^[a-zA-Z][a-zA-Z0-9_-]*$/.test(name)) {
+            console.error(chalk.red(`Invalid alias name "${name}". Use letters, digits, _ or -.`));
+            process.exit(1);
+        }
+        if (reservedNames().has(name)) {
+            console.error(chalk.red(`"${name}" is reserved (collides with an agent CLI or the agents binary).`));
+            process.exit(1);
+        }
+        const target = shimPath(name);
+        if (fs.existsSync(target) && !isAliasShim(target)) {
+            console.error(chalk.red(`Refusing to overwrite ${target} -- not an agents-cli alias shim.`));
+            process.exit(1);
+        }
+        fs.mkdirSync(getShimsDir(), { recursive: true });
+        fs.writeFileSync(target, generateAliasShim(name, expanded), 'utf-8');
+        fs.chmodSync(target, 0o755);
+        const map = readAliases();
+        map[name] = expanded;
+        writeAliases(map);
+        console.log(`${chalk.green('Created')} alias ${chalk.bold(name)} -> ${chalk.dim(`agents ${expanded}`)}`);
+    });
+    cmd
+        .command('remove <name>')
+        .alias('rm')
+        .description('Delete an alias shim')
+        .action((name) => {
+        const map = readAliases();
+        const target = shimPath(name);
+        if (!(name in map) && !fs.existsSync(target)) {
+            console.error(chalk.red(`No alias named "${name}".`));
+            process.exit(1);
+        }
+        if (fs.existsSync(target)) {
+            if (!isAliasShim(target)) {
+                console.error(chalk.red(`Refusing to delete ${target} -- not an agents-cli alias shim.`));
+                process.exit(1);
+            }
+            fs.unlinkSync(target);
+        }
+        delete map[name];
+        writeAliases(map);
+        console.log(`${chalk.yellow('Removed')} alias ${chalk.bold(name)}`);
+    });
+    cmd
+        .command('list')
+        .alias('ls')
+        .description('Show installed aliases')
+        .action(() => {
+        const map = readAliases();
+        const entries = Object.entries(map);
+        if (entries.length === 0) {
+            console.log(chalk.gray('No aliases. Try: agents alias add teams'));
+            return;
+        }
+        const width = entries.reduce((max, [n]) => Math.max(max, n.length), 0);
+        for (const [name, expansion] of entries) {
+            console.log(`  ${chalk.bold(name.padEnd(width))}  ${chalk.dim('->')} agents ${expansion}`);
+        }
+    });
+}

package/dist/commands/beta.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from 'commander';
+export declare function registerBetaCommands(program: Command): void;

package/dist/commands/beta.js

@@ -0,0 +1,53 @@
+import chalk from 'chalk';
+import { ALL_BETA_FEATURES, getBetaConfigLocation, getEnabledBetaFeatures, setBetaEnabled, } from '../lib/beta.js';
+function parseFeatures(values) {
+    const valid = new Set(ALL_BETA_FEATURES);
+    const invalid = values.filter((value) => !valid.has(value));
+    if (invalid.length > 0) {
+        console.error(chalk.red(`Unknown beta feature: ${invalid.join(', ')}`));
+        console.error(chalk.gray(`Valid features: ${ALL_BETA_FEATURES.join(', ')}`));
+        process.exit(1);
+    }
+    return values;
+}
+export function registerBetaCommands(program) {
+    const beta = program
+        .command('beta')
+        .description('Enable or disable preview features like drive and factory.')
+        .addHelpText('after', `
+Examples:
+  agents beta list
+  agents beta enable drive factory
+  agents beta disable drive
+`);
+    beta
+        .command('list')
+        .description('Show available beta features and whether they are enabled.')
+        .action(() => {
+        const enabled = new Set(getEnabledBetaFeatures());
+        const location = getBetaConfigLocation();
+        console.log(chalk.bold('Beta Features'));
+        for (const feature of ALL_BETA_FEATURES) {
+            const state = enabled.has(feature) ? chalk.green('enabled') : chalk.gray('disabled');
+            console.log(`  ${feature.padEnd(8)} ${state}`);
+        }
+        console.log('');
+        console.log(chalk.gray(`Config: ${location.path}`));
+    });
+    beta
+        .command('enable <features...>')
+        .description('Enable one or more beta features.')
+        .action((features) => {
+        const result = setBetaEnabled(parseFeatures(features), true);
+        console.log(chalk.green(`Enabled: ${features.join(', ')}`));
+        console.log(chalk.gray(`Saved to ${result.path}`));
+    });
+    beta
+        .command('disable <features...>')
+        .description('Disable one or more beta features.')
+        .action((features) => {
+        const result = setBetaEnabled(parseFeatures(features), false);
+        console.log(chalk.green(`Disabled: ${features.join(', ')}`));
+        console.log(chalk.gray(`Saved to ${result.path}`));
+    });
+}

package/dist/commands/cloud.d.ts

@@ -1,3 +1,10 @@
+/**
+ * Cloud dispatch commands for running agent tasks on remote infrastructure.
+ *
+ * Provides a unified CLI for dispatching, monitoring, and managing tasks
+ * across multiple cloud providers (Rush Cloud, Codex Cloud, Factory/Droid).
+ * All tasks are tracked locally in a SQLite database for cross-provider listing.
+ */
 import type { Command } from 'commander';
+/** Register the `agents cloud` command tree (run, list, status, logs, cancel, message, providers). */
 export declare function registerCloudCommands(program: Command): void;
-//# sourceMappingURL=cloud.d.ts.map

package/dist/commands/cloud.js

@@ -2,12 +2,14 @@ import chalk from 'chalk';
 import * as fs from 'fs';
 import ora from 'ora';
 import { resolveProvider, getAllProviders, getDefaultProviderId } from '../lib/cloud/registry.js';
-import { insertTask, updateTaskStatus, getTaskById, listTasks as listStoredTasks } from '../lib/cloud/store.js';
+import { insertTask, updateTaskStatus, getTaskById, listTasks as listStoredTasks, listActiveTasks } from '../lib/cloud/store.js';
 import { renderStream } from '../lib/cloud/stream.js';
+/** Print an error message to stderr and exit. */
 function die(msg, code = 1) {
     console.error(chalk.red(msg));
     process.exit(code);
 }
+/** Format an ISO timestamp as a human-readable relative time string. */
 function relTime(iso) {
     const secs = Math.floor((Date.now() - new Date(iso).getTime()) / 1000);
     if (secs < 10)
@@ -25,6 +27,7 @@ function truncate(s, n) {
         return s;
     return s.slice(0, n - 1) + '...';
 }
+/** Return a chalk color function appropriate for the given task status. */
 function statusColor(status) {
     switch (status) {
         case 'queued':
@@ -40,17 +43,62 @@ function statusColor(status) {
 function isJsonMode(opts) {
     return Boolean(opts.json) || !process.stdout.isTTY;
 }
+/** Register the `agents cloud` command tree (run, list, status, logs, cancel, message, providers). */
 export function registerCloudCommands(program) {
     const cloud = program
-        .command('cloud')
-        .description('Dispatch and manage cloud agent tasks across providers (Rush Cloud, Codex Cloud, Factory).');
+        .command('cloud', { hidden: true })
+        .description('Dispatch and manage cloud agent tasks across providers (Rush Cloud, Codex Cloud, Factory).')
+        .addHelpText('after', `
+Providers:
+  rush      Rush Cloud — dispatches against a GitHub repo + branch
+  codex     Codex Cloud — runs in a pre-built Codex environment
+  factory   Factory pods — Droid + computer-use targets
+
+Examples:
+  # Dispatch a quick fix to Rush Cloud and stream the output
+  agents cloud run "fix the flaky e2e in apps/web/tests/checkout.spec.ts" --provider rush --repo getrush/rush --branch main
+
+  # Fire-and-forget (returns the task id, no streaming)
+  agents cloud run "bump tailwind to v4 and fix the breaks" --provider rush --repo getrush/rush --no-follow
+
+  # Multi-repo dispatch: touch both rush and rush-extension in one task
+  agents cloud run "rename POST /v1/charge -> /v2/charge across server + extension" --provider rush --repo getrush/rush --repo getrush/rush-extension
+
+  # Codex Cloud against a saved environment
+  agents cloud run "add pytest fixtures for the new billing module" --provider codex --env env_a1b2c3 --agent codex --timeout 30m
+
+  # Factory pod targeting a specific computer (Droid)
+  agents cloud run "QA the new onboarding flow end-to-end" --provider factory --computer mac-mini-1 --agent droid
+
+  # See every cloud task you've dispatched (most recent first)
+  agents cloud list
+
+  # Inspect a specific task
+  agents cloud status tsk_4f2a91
+
+  # Live-tail logs for a running task
+  agents cloud logs tsk_4f2a91
+
+  # Send a follow-up while the task is in needs-review
+  agents cloud message tsk_4f2a91 "Looks good — also update the OpenAPI spec"
+
+  # Cancel a runaway task
+  agents cloud cancel tsk_4f2a91
+
+  # See which providers are signed in and ready
+  agents cloud providers
+`);
     // ── agents cloud run ──────────────────────────────────────────────────
     cloud
         .command('run [prompt]')
         .description('Dispatch a task to a cloud agent.')
         .option('--provider <id>', 'Cloud backend: rush, codex, factory')
         .option('--agent <name>', 'Agent to run: claude, codex, droid')
-        .option('--repo <owner/repo>', 'GitHub repository (required for Rush Cloud)')
+        .option('--repo <owner/repo>', 'GitHub repository. Repeatable for multi-repo dispatch (Rush Cloud only).', (value, previous) => {
+        const acc = Array.isArray(previous) ? previous : [];
+        acc.push(value);
+        return acc;
+    })
         .option('--branch <name>', 'Target git branch')
         .option('-p, --prompt <text>', 'Inline prompt (alternative to positional argument)')
         .option('--timeout <duration>', 'Kill after duration (e.g., 30m, 2h)')
@@ -66,10 +114,13 @@ Examples:
   agents cloud run "fix the flaky test" --provider rush --repo user/repo
   agents cloud run task.md --provider rush --repo org/project --agent codex
 
+  # Rush Cloud — multi-repo (clones each into /workspace/<owner>/<name>/)
+  agents cloud run "refactor shared logger" --provider rush --repo user/rush --repo user/agents
+
   # Codex Cloud
   agents cloud run "add auth tests" --provider codex --env env_abc123
 
-  # Default provider (set in ~/.agents/agents.yaml)
+  # Default provider (set in ~/.agents-system/agents.yaml)
   agents cloud run "refactor auth module" --repo user/repo
 `)
         .action(async (positionalPrompt, options) => {
@@ -78,15 +129,31 @@ Examples:
         let prompt = options.prompt || positionalPrompt;
         if (!prompt)
             die('Prompt is required. Pass it as an argument or with --prompt.');
-        // If prompt is a file path, read it
+        // If prompt is a file path, read it and tell the user
         if (fs.existsSync(prompt) && fs.statSync(prompt).isFile()) {
-            prompt = fs.readFileSync(prompt, 'utf-8').trim();
+            const filePath = prompt;
+            const stat = fs.statSync(filePath);
+            const sizeKB = (stat.size / 1024).toFixed(1);
+            prompt = fs.readFileSync(filePath, 'utf-8').trim();
+            if (process.stderr.isTTY) {
+                process.stderr.write(chalk.dim(`Reading prompt from ${filePath} (${sizeKB} KB)\n`));
+            }
         }
         const provider = resolveProvider(options.provider);
+        // --repo is repeatable: commander gives us an array via our collector.
+        // A single --repo value arrives as a one-element array; keep the legacy
+        // singular `repo` field in sync so providers that only know that field
+        // still dispatch correctly.
+        const repoValues = Array.isArray(options.repo)
+            ? options.repo
+            : options.repo
+                ? [options.repo]
+                : [];
         const dispatchOptions = {
             prompt,
             agent: options.agent,
-            repo: options.repo,
+            repo: repoValues[0],
+            repos: repoValues.length > 0 ? repoValues : undefined,
             branch: options.branch,
             timeout: options.timeout,
             model: options.model,
@@ -137,23 +204,43 @@ Examples:
         .option('--provider <id>', 'Filter by provider')
         .option('--status <status>', 'Filter by status')
         .option('--limit <n>', 'Max results', '20')
-        .option('--refresh', 'Fetch latest status from provider before displaying')
         .option('--json', 'JSON output')
         .action(async (options) => {
         const json = isJsonMode(options);
         const providerId = options.provider;
         const status = options.status;
         const limit = parseInt(options.limit, 10) || 20;
-        // If --refresh and a specific provider, fetch from remote
-        if (options.refresh && providerId) {
-            const provider = resolveProvider(providerId);
-            try {
-                const remoteTasks = await provider.list({ status });
-                for (const t of remoteTasks)
-                    insertTask(t);
+        // Auto-refresh tasks still in transient states (queued, allocating, running, input_required).
+        // Groups by provider to minimise resolver calls, refreshes each via provider.status().
+        const activeTasks = listActiveTasks();
+        if (activeTasks.length > 0) {
+            const byProvider = new Map();
+            for (const t of activeTasks) {
+                if (providerId && t.provider !== providerId)
+                    continue;
+                let ids = byProvider.get(t.provider);
+                if (!ids) {
+                    ids = [];
+                    byProvider.set(t.provider, ids);
+                }
+                ids.push(t.id);
+            }
+            const refreshJobs = [];
+            for (const [pid, ids] of byProvider) {
+                try {
+                    const provider = resolveProvider(pid);
+                    for (const id of ids) {
+                        refreshJobs.push(provider.status(id)
+                            .then((fresh) => { insertTask(fresh); })
+                            .catch(() => { }));
+                    }
+                }
+                catch {
+                    // provider not configured — skip
+                }
             }
-            catch (err) {
-                process.stderr.write(chalk.yellow(`Could not refresh from ${provider.name}: ${err.message}\n`));
+            if (refreshJobs.length > 0) {
+                await Promise.allSettled(refreshJobs);
             }
         }
         const tasks = listStoredTasks({ provider: providerId, status, limit });
@@ -241,7 +328,7 @@ Examples:
         const json = isJsonMode(options);
         const task = getTaskById(id);
         if (!task)
-            die(`Task ${id} not found locally. Run 'agents cloud list --refresh' first.`);
+            die(`Task ${id} not found locally. Run 'agents cloud list' first.`);
         const provider = resolveProvider(task.provider);
         try {
             const result = await renderStream(provider.stream(id), { json });
@@ -303,7 +390,7 @@ Examples:
             const data = providers.map((p) => ({
                 id: p.id,
                 name: p.name,
-                available: p.supports({}),
+                available: p.capabilities().available,
                 default: p.id === defaultId,
             }));
             process.stdout.write(JSON.stringify(data, null, 2) + '\n');
@@ -311,7 +398,7 @@ Examples:
         }
         console.log(chalk.bold('Cloud Providers\n'));
         for (const p of providers) {
-            const available = p.supports({});
+            const available = p.capabilities().available;
             const isDefault = p.id === defaultId;
             const status = available ? chalk.green('ready') : chalk.dim('not configured');
             const defaultTag = isDefault ? chalk.cyan(' (default)') : '';
@@ -319,4 +406,3 @@ Examples:
         }
     });
 }
-//# sourceMappingURL=cloud.js.map

package/dist/commands/commands.d.ts

@@ -1,3 +1,11 @@
+/**
+ * Slash command management for extending agents with custom markdown commands.
+ *
+ * Implements `agents commands` -- list, add, remove, sync, prune, and view
+ * markdown files that agents invoke mid-session as slash commands. Central
+ * storage lives in ~/.agents/commands/ and commands are synced to individual
+ * version homes (with TOML conversion for Gemini).
+ */
 import type { Command } from 'commander';
+/** Register the `agents commands` command tree (list, add, remove, sync, prune, view). */
 export declare function registerCommandsCommands(program: Command): void;
-//# sourceMappingURL=commands.d.ts.map

package/dist/commands/commands.js

@@ -3,15 +3,16 @@ import ora from 'ora';
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
-import { checkbox, confirm } from '@inquirer/prompts';
-import { ALL_AGENT_IDS, COMMANDS_CAPABLE_AGENTS, resolveAgentName, formatAgentError, agentLabel, } from '../lib/agents.js';
+import { checkbox } from '@inquirer/prompts';
+import { ALL_AGENT_IDS, resolveAgentName, formatAgentError, agentLabel, } from '../lib/agents.js';
 import { cloneRepo } from '../lib/git.js';
-import { discoverCommands, resolveCommandSource, installCommandCentrally, uninstallCommand, listCentralCommands, getCommandInfo, diffVersionCommands, installCommandToVersion, removeCommandFromVersion, iterCommandsCapableVersions, } from '../lib/commands.js';
+import { discoverCommands, resolveCommandSource, installCommandCentrally, uninstallCommand, listCentralCommands, getCommandInfo, diffVersionCommands, iterCommandsCapableVersions, } from '../lib/commands.js';
 import { getCommandsDir } from '../lib/state.js';
 import { showResourceList, buildTargetsSection, } from './resource-view.js';
-import { getGlobalDefault, syncResourcesToVersion, promptAgentVersionSelection, resolveAgentVersionTargets, } from '../lib/versions.js';
+import { getGlobalDefault, resolveVersionAlias, syncResourcesToVersion, promptAgentVersionSelection, resolveAgentVersionTargets, } from '../lib/versions.js';
 import { recordVersionResources } from '../lib/state.js';
 import { isPromptCancelled, isInteractiveTerminal, parseCommaSeparatedList, printWithPager, requireInteractiveSelection, } from './utils.js';
+/** Register the `agents commands` command tree (list, add, remove, sync, prune, view). */
 export function registerCommandsCommands(program) {
     const commandsCmd = program
         .command('commands')
@@ -58,7 +59,7 @@ When to use:
                 process.exit(1);
             }
             filterAgent = resolved;
-            filterVersion = parts[1] || undefined;
+            filterVersion = resolveVersionAlias(resolved, parts[1]);
         }
         const rows = buildCommandRows({ filterAgent, filterVersion });
         spinner.stop();
@@ -127,7 +128,7 @@ Examples:
                     }
                     // Build choices with descriptions
                     const choices = centralCommands.map((name) => {
-                        const cmdPath = path.join(os.homedir(), '.agents', 'commands', `${name}.md`);
+                        const cmdPath = path.join(getCommandsDir(), `${name}.md`);
                         let description = '';
                         if (fs.existsSync(cmdPath)) {
                             const content = fs.readFileSync(cmdPath, 'utf-8');
@@ -324,174 +325,26 @@ Examples:
             }
         }
     });
+    // `commands sync` is gone — sync runs automatically when the agent launches.
     commandsCmd
-        .command('sync')
-        .description('Reconcile version-home commands against central ~/.agents/commands/ (add + update, never delete)')
-        .option('-a, --agent <agent>', 'Scope to a specific agent or agent@version')
-        .option('-m, --method <method>', 'Install method: copy (default) or symlink (markdown-format agents only)', 'copy')
-        .addHelpText('after', `
-Examples:
-  # Sync every installed version
-  agents commands sync
-
-  # Scope to one agent or version
-  agents commands sync --agent claude
-  agents commands sync --agent claude@2.1.113
-
-  # Symlink into version homes (propagates central edits automatically, markdown agents only)
-  agents commands sync --method symlink
-
-Note: Gemini uses TOML — symlink is ignored and a fresh conversion is written
-on every sync. Sync is additive: to remove orphans, use 'agents commands prune'.
-`)
-        .action(async (options) => {
-        const method = (options.method === 'symlink' ? 'symlink' : 'copy');
-        let filter;
-        if (options.agent) {
-            const [name, version] = String(options.agent).split('@');
-            const agentId = resolveAgentName(name);
-            if (!agentId) {
-                console.log(chalk.red(formatAgentError(name, COMMANDS_CAPABLE_AGENTS)));
-                process.exit(1);
-            }
-            filter = { agent: agentId, version: version || undefined };
-        }
-        const pairs = iterCommandsCapableVersions(filter);
-        if (pairs.length === 0) {
-            console.log(chalk.gray('No matching installed versions.'));
-            return;
-        }
-        const diffs = pairs.map(({ agent, version }) => diffVersionCommands(agent, version));
-        const plan = diffs.filter((d) => d.toAdd.length > 0 || d.toUpdate.length > 0);
-        if (plan.length === 0) {
-            console.log(chalk.green('All version homes are up to date with central.'));
-            if (diffs.some((d) => d.orphans.length > 0)) {
-                console.log(chalk.gray('Orphan commands present. Run \'agents commands prune --dry-run\' to review.'));
-            }
-            return;
-        }
-        console.log(chalk.bold(`Syncing commands (method: ${method})\n`));
-        let adds = 0, updates = 0, failures = 0;
-        for (const diff of plan) {
-            const label = `${diff.agent}@${diff.version}`;
-            if (diff.toAdd.length > 0) {
-                console.log(`  ${chalk.cyan(label)} ${chalk.gray('add:')} ${diff.toAdd.join(', ')}`);
-                for (const name of diff.toAdd) {
-                    const r = installCommandToVersion(diff.agent, diff.version, name, method);
-                    if (r.success)
-                        adds++;
-                    else {
-                        failures++;
-                        console.log(chalk.red(`    ! ${name}: ${r.error}`));
-                    }
-                }
-            }
-            if (diff.toUpdate.length > 0) {
-                console.log(`  ${chalk.cyan(label)} ${chalk.gray('update:')} ${diff.toUpdate.join(', ')}`);
-                for (const name of diff.toUpdate) {
-                    const r = installCommandToVersion(diff.agent, diff.version, name, method);
-                    if (r.success)
-                        updates++;
-                    else {
-                        failures++;
-                        console.log(chalk.red(`    ! ${name}: ${r.error}`));
-                    }
-                }
-            }
-        }
-        console.log();
-        console.log(chalk.green(`Synced: ${adds} added, ${updates} updated${failures > 0 ? chalk.red(`, ${failures} failed`) : ''}.`));
-        const totalOrphans = diffs.reduce((n, d) => n + d.orphans.length, 0);
-        if (totalOrphans > 0) {
-            console.log(chalk.gray(`${totalOrphans} orphan(s) remain. Run 'agents commands prune --dry-run' to review.`));
-        }
+        .command('sync', { hidden: true })
+        .allowUnknownOption()
+        .allowExcessArguments()
+        .action(() => {
+        console.error(chalk.red('"agents commands 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 commands'));
+        process.exit(1);
     });
+    // `commands prune` moved to the top-level `agents prune` command.
     commandsCmd
-        .command('prune')
-        .description('Remove orphan commands from version homes (commands present locally but not in central)')
-        .option('-a, --agent <agent>', 'Scope to a specific agent or agent@version')
-        .option('--dry-run', 'Show orphans without deleting')
-        .option('-y, --yes', 'Skip confirmation prompt')
-        .addHelpText('after', `
-Examples:
-  # See what would be pruned
-  agents commands prune --dry-run
-
-  # Prune across every installed version (prompts for confirmation)
-  agents commands prune
-
-  # Scope to one agent or version
-  agents commands prune --agent claude@2.0.65
-
-  # Skip confirmation (for scripts)
-  agents commands prune -y
-`)
-        .action(async (options) => {
-        let filter;
-        if (options.agent) {
-            const [name, version] = String(options.agent).split('@');
-            const agentId = resolveAgentName(name);
-            if (!agentId) {
-                console.log(chalk.red(formatAgentError(name, COMMANDS_CAPABLE_AGENTS)));
-                process.exit(1);
-            }
-            filter = { agent: agentId, version: version || undefined };
-        }
-        const pairs = iterCommandsCapableVersions(filter);
-        const diffs = pairs
-            .map(({ agent, version }) => diffVersionCommands(agent, version))
-            .filter((d) => d.orphans.length > 0);
-        if (diffs.length === 0) {
-            console.log(chalk.green('No orphan commands.'));
-            return;
-        }
-        const total = diffs.reduce((n, d) => n + d.orphans.length, 0);
-        console.log(chalk.bold(`Orphans (in version home, not in central)\n`));
-        for (const d of diffs) {
-            console.log(`  ${chalk.cyan(`${d.agent}@${d.version}`)}  ${d.orphans.join(', ')}`);
-        }
-        console.log();
-        if (options.dryRun) {
-            console.log(chalk.gray(`${total} orphan(s). Run without --dry-run to delete.`));
-            return;
-        }
-        if (!options.yes) {
-            if (!isInteractiveTerminal()) {
-                console.log(chalk.yellow('Non-interactive shell: pass -y to confirm, or --dry-run to preview.'));
-                process.exit(1);
-            }
-            let ok = false;
-            try {
-                ok = await confirm({
-                    message: `Delete ${total} orphan command${total === 1 ? '' : 's'}?`,
-                    default: false,
-                });
-            }
-            catch (err) {
-                if (isPromptCancelled(err)) {
-                    console.log(chalk.gray('Cancelled'));
-                    return;
-                }
-                throw err;
-            }
-            if (!ok) {
-                console.log(chalk.gray('Cancelled'));
-                return;
-            }
-        }
-        let removed = 0, failures = 0;
-        for (const d of diffs) {
-            for (const name of d.orphans) {
-                const r = removeCommandFromVersion(d.agent, d.version, name);
-                if (r.success)
-                    removed++;
-                else {
-                    failures++;
-                    console.log(chalk.red(`  ! ${d.agent}@${d.version} ${name}: ${r.error}`));
-                }
-            }
-        }
-        console.log(chalk.green(`Pruned ${removed} orphan(s)${failures > 0 ? chalk.red(`, ${failures} failed`) : ''}.`));
+        .command('prune', { hidden: true })
+        .allowUnknownOption()
+        .allowExcessArguments()
+        .action(() => {
+        console.error(chalk.red('"agents commands prune" moved.'));
+        console.error(chalk.gray('Use:  agents prune commands   (or `agents prune` for everything)'));
+        process.exit(1);
     });
     commandsCmd
         .command('view [name]')
@@ -625,4 +478,3 @@ function formatCommandDetail(name, info, targets) {
     lines.push(buildTargetsSection(targets));
     return lines.join('\n');
 }
-//# sourceMappingURL=commands.js.map