@phnx-labs/agents-cli 1.14.6 → 1.15.0

package/README.md

@@ -47,11 +47,13 @@ Also available as `ag` -- all commands work with both `agents` and `ag`.
 - [Sessions across agents](#sessions-across-agents)
 - [Run open models through Claude Code](#run-open-models-through-claude-code)
 - [Teams](#teams)
+- [Browser](#browser)
 - [Secrets](#secrets)
 - [Routines](#routines)
 - [PTY](#pty)
 - [Portable setup](#portable-setup)
 - [Private skills](#private-skills)
+- [Security & Privacy](#security--privacy)
 - [Compatibility](#compatibility)
 - [FAQ](#faq)
 
@@ -242,6 +244,85 @@ Team state is observable via `agents teams list --json` / `agents teams status -
 
 ---
 
+## Browser
+
+Give agents access to a real browser — no relay extension, no cloud service, no Playwright getting blocked.
+
+```bash
+# Create an isolated profile for automation
+agents browser profiles create work --browser chrome
+
+# Start a task, navigate, interact
+agents browser start login-flow --profile work
+agents browser navigate login-flow https://app.example.com
+agents browser refs login-flow              # Get interactive element refs
+agents browser click login-flow <tab> 42    # Click element ref 42
+agents browser type login-flow <tab> 15 "hello"
+agents browser screenshot login-flow        # Smart resizing, token-efficient
+```
+
+### Why this works where Playwright fails
+
+Playwright and Puppeteer spin up fresh browser instances with automation flags. Sites like LinkedIn, Google, and most finance apps detect and block them immediately.
+
+`agents browser` launches your existing residential Chrome (or Brave, Edge, Chromium) on your machine via CDP. Same browser fingerprint, same IP, same everything. Sites can't detect automation because you're using the same browser you'd use manually.
+
+### Token-efficient automation
+
+The CLI handles the mechanical work so agents don't burn tokens on low-level browser commands. Screenshots are automatically resized without excessive compression — agents process smaller images while keeping the detail they need to make decisions.
+
+### Profile isolation
+
+Multiple agents can run browser tasks simultaneously without stepping on each other. Each profile gets its own user data directory, cookies, and state. One agent logs into your work Slack, another into your personal email — no conflicts, no shared state.
+
+```bash
+agents browser profiles create work-slack --browser chrome
+agents browser profiles create personal-gmail --browser chrome
+# Two agents, two profiles, no interference
+```
+
+### Safe credential access
+
+Attach a [secrets bundle](#secrets) to a profile. The agent can log in without credentials in plaintext, and every secret access is recorded in the session log.
+
+```bash
+agents browser profiles create bank --browser chrome --secrets bank-creds
+```
+
+### Electron apps
+
+Control Electron apps (Slack, Discord, VS Code, your own app) with custom binaries:
+
+```bash
+agents browser profiles create rush \
+  --browser custom \
+  --binary "/Applications/Rush.app/Contents/MacOS/Rush" \
+  --electron
+```
+
+### Remote browsers
+
+Connect to browsers running anywhere — local, SSH tunnels, or cloud services:
+
+```bash
+# Local CDP (discovers WebSocket URL automatically)
+agents browser profiles create local-debug \
+  --browser chrome \
+  --endpoint "http://localhost:9222"
+
+# SSH tunnel to a remote machine
+agents browser profiles create staging \
+  --browser chrome \
+  --endpoint "ssh://deploy@staging.example.com?port=9222"
+
+# Cloud browser services (BrowserBase, Steel, etc.)
+agents browser profiles create cloud \
+  --browser chrome \
+  --endpoint "wss://connect.browserbase.com?apiKey=..."
+```
+
+---
+
 ## Secrets
 
 ```bash
@@ -373,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 |
@@ -425,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)