@phnx-labs/agents-cli 1.14.7 → 1.15.0

package/README.md

@@ -53,6 +53,7 @@ Also available as `ag` -- all commands work with both `agents` and `ag`.
 - [PTY](#pty)
 - [Portable setup](#portable-setup)
 - [Private skills](#private-skills)
+- [Security & Privacy](#security--privacy)
 - [Compatibility](#compatibility)
 - [FAQ](#faq)
 
@@ -453,6 +454,70 @@ Extras clone into `~/.agents-system/.repos/<alias>/` and ship the same layout as
 
 ---
 
+## Security & Privacy
+
+**Everything stays on your machine.** No telemetry, no cloud sync (unless you opt into iCloud Keychain for secrets), no phone-home. Here's exactly what `agents-cli` stores locally and why.
+
+### Event log
+
+Every agent run, version install, browser launch, and secrets access is logged to `~/.agents/logs/events-YYYY-MM-DD.jsonl`. This gives you a complete record of what agents did on your machine.
+
+```bash
+# What gets logged (example event):
+{
+  "ts": "2026-05-09T10:23:45Z",
+  "event": "agent.run.end",
+  "agent": "claude",
+  "version": "2.1.121",
+  "prompt": "Fix the auth bug in...",  # truncated to 200 chars
+  "durationMs": 45230,
+  "exitCode": 0,
+  "hostname": "your-mac",
+  "platform": "darwin"
+}
+```
+
+**What's logged:** Operation type, agent, version, timing, truncated prompts (first 200 chars), exit codes, errors. **What's NOT logged:** Full prompts, outputs, file contents, secret values (only bundle names).
+
+**Permissions:** Logs directory is `0700` (owner-only), files are `0600`. Only you can read them.
+
+**Retention:** 30 days by default, then auto-pruned.
+
+**Opt out:** Set `AGENTS_DISABLE_EVENT_LOG=1` in your shell to disable completely.
+
+### Session search
+
+Conversations with Claude, Codex, Gemini, and other agents scatter across their native storage. Session search indexes them locally so you can find any conversation:
+
+```bash
+agents sessions "auth middleware"     # Full-text search across all agents
+agents sessions --agent claude --since 7d
+```
+
+The index lives at `~/.agents/sessions/sessions.db` (SQLite + FTS5). Nothing leaves your machine. See [Sessions](#sessions-across-agents) for full usage.
+
+### Secrets
+
+API keys and credentials are stored in macOS Keychain, never in plaintext files. Bundle definitions also live in Keychain.
+
+```bash
+agents secrets create my-keys
+agents secrets add my-keys API_KEY    # Prompts for value, stores in Keychain
+```
+
+With `--icloud-sync`, secrets sync via iCloud Keychain to your other Macs. Without it, they stay device-local. See [Secrets](#secrets) for full usage.
+
+### Summary
+
+| Data | Location | Who can read | Opt out |
+|------|----------|--------------|---------|
+| Event log | `~/.agents/logs/` | You only (0600) | `AGENTS_DISABLE_EVENT_LOG=1` |
+| Session index | `~/.agents/sessions/` | You only | Delete the directory |
+| Secrets | macOS Keychain | You + apps you authorize | Don't use `agents secrets` |
+| Config | `~/.agents/` | You only | N/A |
+
+---
+
 ## Compatibility
 
 | Agent | Versions | MCP | Commands | Skills | Rules | Hooks | Plugins | Permissions | Routines | Teams |
@@ -505,7 +570,9 @@ Your choice. We hand off to the original CLI process — use your existing subsc
 
 ### Does it store my API keys or send telemetry?
 
-No. API keys come from your shell environment or each agent CLI's existing auth. No telemetry, no phone-home. User content lives in `~/.agents/`; operational state (versions, shims, sessions, caches) lives in `~/.agents-system/`.
+**No telemetry, no phone-home.** Everything stays local. API keys come from your shell environment or each agent CLI's existing auth.
+
+For full transparency: `agents-cli` keeps a local event log at `~/.agents/logs/` so you can see exactly what agents did on your machine. Logs are owner-readable only (0600) and auto-prune after 30 days. Set `AGENTS_DISABLE_EVENT_LOG=1` to disable. See [Security & Privacy](#security--privacy) for details.
 
 ### Which platforms?
 

package/dist/commands/beta.js

@@ -1,5 +1,9 @@
 import chalk from 'chalk';
 import { ALL_BETA_FEATURES, getBetaConfigLocation, getEnabledBetaFeatures, setBetaEnabled, } from '../lib/beta.js';
+const BETA_DESCRIPTIONS = {
+    drive: 'Google Drive integration for reading and writing files',
+    factory: 'Cloud-based agent dispatch via Rush Factory',
+};
 function parseFeatures(values) {
     const valid = new Set(ALL_BETA_FEATURES);
     const invalid = values.filter((value) => !valid.has(value));
@@ -29,7 +33,8 @@ Examples:
         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}`);
+            const desc = BETA_DESCRIPTIONS[feature] || '';
+            console.log(`  ${feature.padEnd(10)} ${state.padEnd(18)} ${chalk.dim(desc)}`);
         }
         console.log('');
         console.log(chalk.gray(`Config: ${location.path}`));

package/dist/commands/exec.js

@@ -8,7 +8,7 @@
 import chalk from 'chalk';
 import { buildExecCommand, parseExecEnv, execAgent, runWithFallback, AGENT_COMMANDS, } from '../lib/exec.js';
 import { profileExists, resolveProfileForRun } from '../lib/profiles.js';
-import { readBundle, resolveBundleEnv } from '../lib/secrets/bundles.js';
+import { readBundle, resolveBundleEnv, describeBundle } from '../lib/secrets/bundles.js';
 import { getConfiguredRunStrategy, normalizeRunStrategy, resolveRunVersion, RUN_STRATEGIES, } from '../lib/rotate.js';
 import { resolveVersionAlias } from '../lib/versions.js';
 const VALID_AGENTS = Object.keys(AGENT_COMMANDS);
@@ -36,7 +36,7 @@ export function registerRunCommand(program) {
         .option('--cwd <dir>', 'Working directory for the agent (defaults to current directory)')
         .option('--add-dir <dir>', 'Grant access to an additional directory outside the project (Claude only, repeatable)', (val, prev) => [...prev, val], [])
         .option('--json', 'Stream events as JSON lines (for parsing by other tools)')
-        .option('--headless', 'Non-interactive mode (default for run)', true)
+        .option('--headless', 'Non-interactive mode (auto-enabled when prompt provided)', false)
         .option('-i, --interactive', 'Force interactive mode even when a prompt is provided')
         .option('--session-id <id>', 'Resume a previous conversation (Claude only)')
         .option('--verbose', 'Show detailed execution logs')
@@ -197,6 +197,13 @@ Examples:
         for (const bundleName of options.secrets) {
             try {
                 const bundle = readBundle(bundleName);
+                const entries = describeBundle(bundle);
+                const counts = {};
+                for (const e of entries) {
+                    counts[e.kind] = (counts[e.kind] || 0) + 1;
+                }
+                const breakdown = Object.entries(counts).map(([k, v]) => `${v} ${k}`).join(', ');
+                console.log(chalk.gray(`[secrets] Resolved ${bundleName}: ${entries.length} keys (${breakdown})`));
                 secretsEnv = { ...secretsEnv, ...resolveBundleEnv(bundle) };
             }
             catch (err) {

package/dist/commands/init.js

@@ -82,6 +82,16 @@ export async function runInit(program, options = {}) {
         spinner.succeed(`Updated to ${result.commit}`);
     }
     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(DEFAULT_SYSTEM_REPO, agentsDir);
         if (!result.success) {
             spinner.fail(`Clone failed: ${result.error}`);

package/dist/commands/mcp.js

@@ -6,7 +6,7 @@ import { readManifest, writeManifest, createDefaultManifest } from '../lib/manif
 import { listMcpServerConfigs } from '../lib/mcp.js';
 import { getMcpDir } from '../lib/state.js';
 import { getEffectiveHome, getGlobalDefault, listInstalledVersions, getVersionHomePath, resolveInstalledAgentTargets, resolveConfiguredAgentTargets, resolveVersionAlias, } from '../lib/versions.js';
-import { getAgentsDir } from '../lib/state.js';
+import { getUserAgentsDir } from '../lib/state.js';
 import { isPromptCancelled, isInteractiveTerminal, requireInteractiveSelection } from './utils.js';
 import { showResourceList, buildTargetsSection, } from './resource-view.js';
 /** Parse a comma-separated --agents string into validated agent IDs and optional version targets. */
@@ -163,7 +163,7 @@ Examples:
             console.log(chalk.gray('HTTP:  agents mcp add <name> <url> --transport http'));
             process.exit(1);
         }
-        const localPath = getAgentsDir();
+        const localPath = getUserAgentsDir();
         const manifest = readManifest(localPath) || createDefaultManifest();
         manifest.mcp = manifest.mcp || {};
         const targetConfig = parseMcpAgentTargets(options.agents);
@@ -400,7 +400,7 @@ Examples:
   agents mcp register --agents codex@0.116.0
 `)
         .action(async (name, options) => {
-        const localPath = getAgentsDir();
+        const localPath = getUserAgentsDir();
         const manifest = readManifest(localPath);
         if (!manifest?.mcp) {
             console.log(chalk.yellow('No MCP servers in manifest'));
@@ -467,7 +467,7 @@ function buildMcpRows(opts) {
     const centralServers = new Map();
     for (const s of listMcpServerConfigs())
         centralServers.set(s.name, s);
-    const manifest = readManifest(getAgentsDir());
+    const manifest = readManifest(getUserAgentsDir());
     const manifestEntries = manifest?.mcp || {};
     const targetPairs = iterMcpCapableVersions({
         agent: opts.filterAgent,

package/dist/commands/prune.d.ts

@@ -1,22 +1,2 @@
-/**
- * Top-level `agents prune` — destructive cleanup across the install.
- *
- * Two kinds of cleanup, one verb:
- *   - Resource orphans: command/skill/hook files inside a version home that no
- *     longer come from any source (deleted from ~/.agents/ but never reconciled
- *     into the version install).
- *   - Version duplicates: older installed versions of an agent that share an
- *     account with a newer installed version of the same agent (the older copy
- *     is redundant; the newer one is what's signed in and active).
- *
- * Sync (additive: copy missing/changed files into version homes) is no longer
- * a user-facing verb — `syncResourcesToVersion` runs at agent launch and
- * applies adds/updates automatically. Pruning, however, is destructive, so it
- * stays explicit.
- *
- * Default scope: each agent's currently-pinned default version for orphan
- * cleanup, plus the standard cross-agent version-dedup pass. Pass `--all`
- * to widen orphan cleanup to every installed version.
- */
 import type { Command } from 'commander';
 export declare function registerPruneCommand(program: Command): void;

package/dist/commands/prune.js

@@ -1,3 +1,27 @@
+/**
+ * Top-level `agents prune` — destructive cleanup across the install.
+ *
+ * Cleanup targets:
+ *   - Resource orphans: command/skill/hook files inside a version home that no
+ *     longer come from any source (deleted from ~/.agents/ but never reconciled
+ *     into the version install).
+ *   - Version duplicates: older installed versions of an agent that share an
+ *     account with a newer installed version of the same agent.
+ *   - Trash: soft-deleted resources in ~/.agents/.trash/ older than N days.
+ *   - Sessions: session records in sessions.db older than N days.
+ *   - Runs: routine execution logs, keeping only the last N per job.
+ *
+ * Sync (additive: copy missing/changed files into version homes) is no longer
+ * a user-facing verb — `syncResourcesToVersion` runs at agent launch and
+ * applies adds/updates automatically. Pruning, however, is destructive, so it
+ * stays explicit.
+ *
+ * Default scope: each agent's currently-pinned default version for orphan
+ * cleanup, plus the standard cross-agent version-dedup pass. Pass `--all`
+ * to widen orphan cleanup to every installed version.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
 import chalk from 'chalk';
 import { confirm } from '@inquirer/prompts';
 import { diffVersionCommands, iterCommandsCapableVersions, removeCommandFromVersion, } from '../lib/commands.js';
@@ -7,8 +31,12 @@ import { getGlobalDefault } from '../lib/versions.js';
 import { resolveAgentName, formatAgentError } from '../lib/agents.js';
 import { pruneDuplicates } from './view.js';
 import { isInteractiveTerminal, isPromptCancelled } from './utils.js';
+import { getTrashDir } from '../lib/state.js';
+import { countSessionsOlderThan, deleteSessionsOlderThan } from '../lib/session/db.js';
+import { previewRunsPrune, pruneRuns, countAllRuns } from '../lib/routines.js';
 const RESOURCE_TYPES = ['commands', 'skills', 'hooks'];
-const ALL_TYPES = [...RESOURCE_TYPES, 'versions'];
+const STATE_TYPES = ['trash', 'sessions', 'runs'];
+const ALL_TYPES = [...RESOURCE_TYPES, 'versions', ...STATE_TYPES];
 function scopePairs(pairs, all) {
     if (all)
         return pairs;
@@ -59,6 +87,9 @@ function parseTarget(arg) {
     if (RESOURCE_TYPES.includes(arg)) {
         return { resourceTypes: [arg], includeVersions: false };
     }
+    if (STATE_TYPES.includes(arg)) {
+        return { resourceTypes: [], includeVersions: false, stateType: arg };
+    }
     if (arg === 'versions') {
         return { resourceTypes: [], includeVersions: true };
     }
@@ -72,6 +103,202 @@ function parseTarget(arg) {
     console.log(chalk.gray(formatAgentError(arg)));
     process.exit(1);
 }
+function parseDays(value, defaultDays) {
+    const match = value.match(/^(\d+)d?$/);
+    if (match)
+        return parseInt(match[1], 10);
+    return defaultDays;
+}
+function formatBytes(bytes) {
+    if (bytes < 1024)
+        return `${bytes} B`;
+    if (bytes < 1024 * 1024)
+        return `${(bytes / 1024).toFixed(1)} KB`;
+    if (bytes < 1024 * 1024 * 1024)
+        return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+    return `${(bytes / (1024 * 1024 * 1024)).toFixed(2)} GB`;
+}
+function getDirSize(dirPath) {
+    if (!fs.existsSync(dirPath))
+        return 0;
+    let size = 0;
+    const entries = fs.readdirSync(dirPath, { withFileTypes: true });
+    for (const entry of entries) {
+        const fullPath = path.join(dirPath, entry.name);
+        if (entry.isDirectory()) {
+            size += getDirSize(fullPath);
+        }
+        else {
+            try {
+                size += fs.statSync(fullPath).size;
+            }
+            catch { /* ignore */ }
+        }
+    }
+    return size;
+}
+async function runTrashPrune(options) {
+    const trashDir = getTrashDir();
+    if (!fs.existsSync(trashDir)) {
+        console.log(chalk.green('Trash is empty.'));
+        return;
+    }
+    const days = parseDays(options.olderThan || '30d', 30);
+    const cutoffMs = Date.now() - days * 24 * 60 * 60 * 1000;
+    const toPrune = [];
+    function scanDir(dir) {
+        if (!fs.existsSync(dir))
+            return;
+        for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+            const fullPath = path.join(dir, entry.name);
+            try {
+                const stat = fs.statSync(fullPath);
+                if (stat.mtimeMs < cutoffMs) {
+                    toPrune.push({ path: fullPath, mtime: stat.mtimeMs, size: entry.isDirectory() ? getDirSize(fullPath) : stat.size });
+                }
+                else if (entry.isDirectory()) {
+                    scanDir(fullPath);
+                }
+            }
+            catch { /* skip inaccessible */ }
+        }
+    }
+    scanDir(trashDir);
+    if (toPrune.length === 0) {
+        console.log(chalk.green(`No trash entries older than ${days} days.`));
+        return;
+    }
+    const totalSize = toPrune.reduce((sum, e) => sum + e.size, 0);
+    console.log(chalk.bold(`Trash entries older than ${days} days\n`));
+    for (const entry of toPrune.slice(0, 20)) {
+        const age = Math.floor((Date.now() - entry.mtime) / (24 * 60 * 60 * 1000));
+        console.log(`  ${chalk.gray(`${age}d ago`)}  ${path.relative(trashDir, entry.path)}`);
+    }
+    if (toPrune.length > 20) {
+        console.log(chalk.gray(`  ... and ${toPrune.length - 20} more`));
+    }
+    console.log();
+    if (options.dryRun) {
+        console.log(chalk.gray(`${toPrune.length} entries (${formatBytes(totalSize)}). 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 ${toPrune.length} entries (${formatBytes(totalSize)})?`, default: false });
+        }
+        catch (err) {
+            if (isPromptCancelled(err)) {
+                console.log(chalk.gray('Cancelled'));
+                return;
+            }
+            throw err;
+        }
+        if (!ok) {
+            console.log(chalk.gray('Cancelled'));
+            return;
+        }
+    }
+    let deleted = 0;
+    for (const entry of toPrune) {
+        try {
+            fs.rmSync(entry.path, { recursive: true, force: true });
+            deleted++;
+        }
+        catch { /* ignore */ }
+    }
+    console.log(chalk.green(`Pruned ${deleted} trash entries (${formatBytes(totalSize)}).`));
+}
+async function runSessionsPrune(options) {
+    const days = parseDays(options.olderThan || '90d', 90);
+    const cutoffMs = Date.now() - days * 24 * 60 * 60 * 1000;
+    const count = countSessionsOlderThan(cutoffMs);
+    if (count === 0) {
+        console.log(chalk.green(`No sessions older than ${days} days.`));
+        return;
+    }
+    console.log(chalk.bold(`Sessions older than ${days} days: ${count}\n`));
+    if (options.dryRun) {
+        console.log(chalk.gray(`${count} session(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 ${count} session records?`, default: false });
+        }
+        catch (err) {
+            if (isPromptCancelled(err)) {
+                console.log(chalk.gray('Cancelled'));
+                return;
+            }
+            throw err;
+        }
+        if (!ok) {
+            console.log(chalk.gray('Cancelled'));
+            return;
+        }
+    }
+    const deleted = deleteSessionsOlderThan(cutoffMs);
+    console.log(chalk.green(`Pruned ${deleted} session records.`));
+}
+async function runRunsPrune(options) {
+    const keep = options.keep ? parseInt(options.keep, 10) : 10;
+    if (isNaN(keep) || keep < 0) {
+        console.log(chalk.red('--keep must be a non-negative integer'));
+        process.exit(1);
+    }
+    const preview = previewRunsPrune(keep);
+    const total = countAllRuns();
+    if (preview.length === 0) {
+        console.log(chalk.green(`All jobs have ${keep} or fewer runs. Nothing to prune.`));
+        return;
+    }
+    console.log(chalk.bold(`Routine runs to prune (keeping last ${keep} per job)\n`));
+    const byJob = new Map();
+    for (const run of preview) {
+        byJob.set(run.jobName, (byJob.get(run.jobName) || 0) + 1);
+    }
+    for (const [job, count] of byJob) {
+        console.log(`  ${chalk.cyan(job)}: ${count} old runs`);
+    }
+    console.log();
+    if (options.dryRun) {
+        console.log(chalk.gray(`${preview.length} of ${total} runs would be deleted. 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 ${preview.length} old runs?`, default: false });
+        }
+        catch (err) {
+            if (isPromptCancelled(err)) {
+                console.log(chalk.gray('Cancelled'));
+                return;
+            }
+            throw err;
+        }
+        if (!ok) {
+            console.log(chalk.gray('Cancelled'));
+            return;
+        }
+    }
+    const { deleted, bytesFreed } = pruneRuns(keep);
+    console.log(chalk.green(`Pruned ${deleted} runs (${formatBytes(bytesFreed)}).`));
+}
 async function runOrphanPrune(resourceTypes, options) {
     const groups = collectOrphans(resourceTypes, options.all === true);
     if (groups.length === 0) {
@@ -133,10 +360,12 @@ async function runOrphanPrune(resourceTypes, options) {
 export function registerPruneCommand(program) {
     program
         .command('prune [target]')
-        .description('Remove orphan resources (commands/skills/hooks) and/or older duplicate version installs (versions soft-deleted to ~/.agents-system/trash/)')
+        .description('Remove orphan resources, old versions, trash, sessions, or routine runs')
         .option('--all', 'For orphan cleanup: sweep every installed version (default: current default version per agent)')
-        .option('--dry-run', 'Show what would be removed without deleting')
+        .option('--dry-run', 'Show what would be removed without deleting (default for state targets)')
         .option('-y, --yes', 'Skip confirmation prompt')
+        .option('--older-than <days>', 'For trash/sessions: delete entries older than N days (default: 30d for trash, 90d for sessions)')
+        .option('--keep <n>', 'For runs: keep the last N runs per job (default: 10)')
         .addHelpText('after', `
 Targets:
   (none)     Orphans across commands, skills, hooks + duplicate versions
@@ -145,6 +374,9 @@ Targets:
   hooks      Orphan hook scripts only
   versions   Older duplicate version installs only
   <agent>    Older duplicate versions for one agent (e.g. 'claude')
+  trash      Soft-deleted resources older than --older-than days (default 30)
+  sessions   Session records in sessions.db older than --older-than days (default 90)
+  runs       Routine execution logs, keeping only --keep per job (default 10)
 
 Examples:
   # Full sweep: orphan resources + duplicate versions for current defaults
@@ -156,14 +388,26 @@ Examples:
   # Just version dedup
   agents prune versions
 
-  # Just version dedup for one agent
-  agents prune claude
-
   # Sweep every installed version's orphans, not only the defaults
   agents prune --all
 
-  # Preview without deleting
-  agents prune --dry-run
+  # Preview trash entries older than 30 days
+  agents prune trash --dry-run
+
+  # Delete trash entries older than 60 days
+  agents prune trash --older-than 60 -y
+
+  # Preview session cleanup (90+ days old)
+  agents prune sessions --dry-run
+
+  # Delete sessions older than 180 days
+  agents prune sessions --older-than 180 -y
+
+  # Preview runs cleanup (keeping last 10)
+  agents prune runs --dry-run
+
+  # Keep only the last 5 runs per job
+  agents prune runs --keep 5 -y
 
 What's an orphan?
   A command, skill, or hook present inside a version home but missing from every
@@ -171,18 +415,27 @@ What's an orphan?
   repos). Usually leftovers from a resource that was deleted or moved but never
   reconciled into the version install.
 
-What this does NOT do:
-  Adds and updates flow through the auto-sync that runs when you launch the
-  agent — there is no manual sync verb.
-
 Soft-delete:
   Version directories are NEVER hard-deleted. \`prune\` moves them to
-  ~/.agents-system/trash/versions/<agent>/<version>/<timestamp>/. Recover
-  with \`agents trash list\` and \`agents trash restore <agent>@<version>\`.
-  The trash never auto-expires; \`rm -rf\` it manually when you're sure.
+  ~/.agents/.trash/versions/<agent>/<version>/<timestamp>/. Use
+  \`agents prune trash\` to expire old trash entries.
 `)
         .action(async (target, options) => {
         const parsed = parseTarget(target);
+        if (parsed.stateType) {
+            switch (parsed.stateType) {
+                case 'trash':
+                    await runTrashPrune(options);
+                    break;
+                case 'sessions':
+                    await runSessionsPrune(options);
+                    break;
+                case 'runs':
+                    await runRunsPrune(options);
+                    break;
+            }
+            return;
+        }
         if (parsed.resourceTypes.length > 0) {
             await runOrphanPrune(parsed.resourceTypes, options);
             if (parsed.includeVersions)

package/dist/commands/teams.js

@@ -922,13 +922,12 @@ Name teammates with --name alice to refer to them as 'alice' instead of a UUID.
         .command('status [team]')
         .aliases(['s', 'st', 'check'])
         .description("Check in on a team: who's working, what files they touched, recent commands, last output. Pass --since for efficient delta polling.")
-        .option('-f, --filter <state>', 'Show only teammates in this state: working, completed, failed, stopped, or all (default: all)', 'all')
+        .option('-f, --filter <state>', 'Show only teammates in this state: running, completed, failed, stopped, or all (default: all)', 'all')
         .option('-s, --since <iso>', 'Cursor from a previous status call; only show updates after this timestamp (enables efficient polling)')
         .option('--agent-id <id>', 'Show only this one teammate (by UUID or UUID prefix)')
         .option('--json', 'Output machine-readable JSON')
         .action(async (team, opts) => {
-        // Map friendly 'working' → internal 'running' for filter.
-        const filter = opts.filter === 'working' ? 'running' : opts.filter;
+        const filter = opts.filter;
         const mgr = mkManager();
         // No team given → drop into the picker (TTY) or fail clearly (script).
         if (!team) {

package/dist/commands/usage.js

@@ -8,6 +8,12 @@ export function registerUsageCommand(program) {
     program
         .command('usage [agent]')
         .description('Show rate-limit / quota usage per agent')
+        .addHelpText('after', `
+Examples:
+  agents usage              Show usage for all installed agents
+  agents usage claude       Show usage for Claude only
+  agents usage codex        Show usage for Codex only
+`)
         .action(async (agentFilter) => {
         const filter = agentFilter;
         const targets = filter

package/dist/commands/versions.js

@@ -104,7 +104,7 @@ When to use:
   - Multi-account: install different versions for different accounts (each version has its own auth)
   - Project-specific: lock a version for a repo with --project
 
-Note: The first version you install is NOT set as default automatically. Run 'agents use' to set it.
+Note: The first version you install becomes the default automatically.
 `)
         .action(async (specs, options) => {
         const isProject = options.project;
@@ -220,10 +220,14 @@ Note: The first version you install is NOT set as default automatically. Run 'ag
                             console.log(chalk.green(`  Synced: ${synced.join(', ')}`));
                         }
                     }
-                    // Prompt to set as default
+                    // Set as default: auto-set if no default exists, otherwise prompt
                     const currentDefault = getGlobalDefault(agent);
                     if (currentDefault !== installedVersion) {
-                        if (skipPrompts) {
+                        if (!currentDefault) {
+                            // First install for this agent - auto-set without prompting
+                            await setDefaultVersion(agent, installedVersion);
+                        }
+                        else if (skipPrompts) {
                             await setDefaultVersion(agent, installedVersion);
                         }
                         else {
@@ -238,9 +242,7 @@ Note: The first version you install is NOT set as default automatically. Run 'ag
                                     info,
                                 });
                                 const accountHint = formatAccountHint(info, usage.snapshot);
-                                const message = currentDefault
-                                    ? `Switch default from ${agentLabel(agentConfig.id)}@${currentDefault} to ${agentLabel(agentConfig.id)}@${installedVersion}${accountHint}?`
-                                    : `Set ${agentLabel(agentConfig.id)}@${installedVersion}${accountHint} as default?`;
+                                const message = `Switch default from ${agentLabel(agentConfig.id)}@${currentDefault} to ${agentLabel(agentConfig.id)}@${installedVersion}${accountHint}?`;
                                 const setAsDefault = await confirm({
                                     message,
                                     default: true,

package/dist/lib/browser/chrome.js

@@ -120,7 +120,7 @@ export async function attachToChrome(port) {
 }
 export function killChrome(pid) {
     try {
-        process.kill(pid, 'SIGTERM');
+        process.kill(pid, 'SIGINT');
     }
     catch {
         // Process already dead

package/dist/lib/browser/drivers/ssh.d.ts

@@ -7,3 +7,4 @@ export interface SSHConnection {
     cleanup: () => void;
 }
 export declare function connectSSH(endpoint: string, profile: BrowserProfile): Promise<SSHConnection>;
+export declare function restartRemoteBrowser(user: string, host: string, browserType: string, port: number, customBinary?: string): Promise<void>;