@phnx-labs/agents-cli 1.19.2 → 1.20.0

package/dist/commands/commands.js

@@ -383,17 +383,17 @@ Examples:
         .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'));
+        console.error(chalk.gray('To remove orphans, use:  agents prune cleanup commands'));
         process.exit(1);
     });
-    // `commands prune` moved to the top-level `agents prune` command.
+    // `commands prune` moved to the top-level `agents prune cleanup` command.
     commandsCmd
         .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)'));
+        console.error(chalk.gray('Use:  agents prune cleanup commands   (or `agents prune cleanup` for everything)'));
         process.exit(1);
     });
     commandsCmd

package/dist/commands/computer.js

@@ -3,7 +3,7 @@ import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
 import { registerCommandGroups } from '../lib/help.js';
-import { openComputerClient, resolveHelperApp, resolveHelperExec, resolveSocketPath, resolveLogPath, resolvePolicyPath, describeTransport, loadComputerAllowList, writeComputerPolicy, } from '../lib/computer-rpc.js';
+import { openComputerClient, resolveHelperApp, resolveHelperExec, resolveSocketPath, resolveLogPath, resolvePolicyPath, resolvePeersPath, describeTransport, loadComputerAllowList, loadDefaultPeers, writeComputerPolicy, writeComputerPeers, } from '../lib/computer-rpc.js';
 // Help groups — mirror `agents browser` so the mental model carries over.
 const COMPUTER_HELP_GROUPS = [
     { title: 'Installation', names: ['install-helper'] },
@@ -46,6 +46,8 @@ function registerStatusCommand(program) {
         const previewParts = allowed.slice(0, 5);
         const previewSuffix = allowed.length > 5 ? ` (+${allowed.length - 5} more)` : '';
         console.log(`policy:    ${allowed.length} app${allowed.length === 1 ? '' : 's'} allowed${allowed.length > 0 ? `: ${previewParts.join(', ')}${previewSuffix}` : ''}`);
+        const callers = loadDefaultPeers();
+        console.log(`peers:     ${callers.length} caller${callers.length === 1 ? '' : 's'} (peer-auth on socket)`);
         if (!installed) {
             console.log('');
             console.log('Run:  agents computer install-helper');
@@ -284,6 +286,15 @@ function registerStartCommand(program) {
             console.log(`        add to ~/.agents/permissions/groups/<name>.yaml under allow:`);
             console.log(`          - "Computer(com.apple.finder)"`);
         }
+        // Peer-auth allow list — which caller executables may connect to
+        // the socket. Default: this CLI's Node binary, plus Rush.app if
+        // installed. A `nc -U socket` from a malicious npm postinstall has
+        // a different exec path and gets refused at accept().
+        const callers = loadDefaultPeers();
+        writeComputerPeers(callers);
+        console.log(`peers:  ${callers.length} caller${callers.length === 1 ? '' : 's'} allowed (${resolvePeersPath()})`);
+        for (const p of callers)
+            console.log(`        ${p}`);
         // Bootout first to clear any prior registration. Best-effort.
         try {
             execFileSync('/bin/launchctl', ['bootout', domain, plistPath], { stdio: 'pipe' });
@@ -356,6 +367,12 @@ function registerReloadCommand(program) {
         const allowed = loadComputerAllowList();
         writeComputerPolicy(allowed);
         console.log(`policy: ${allowed.length} app${allowed.length === 1 ? '' : 's'} allowed (${resolvePolicyPath()})`);
+        // Rewrite peers list too — an upgrade of the npm-global CLI moves
+        // its node path; without this the reloaded daemon would reject the
+        // very binary that just signaled it.
+        const callers = loadDefaultPeers();
+        writeComputerPeers(callers);
+        console.log(`peers:  ${callers.length} caller${callers.length === 1 ? '' : 's'} allowed (${resolvePeersPath()})`);
         // Resolve the daemon's pid via `launchctl list <label>`. The plist
         // output includes a "PID" key when the service is running.
         const uid = process.getuid?.();

package/dist/commands/doctor.d.ts

@@ -15,7 +15,7 @@
  *      unified diff body for each divergent file. Mirrors the resolution that
  *      the shim drives at runtime: project > user > system > extras.
  *
- * Read-only: doctor never mutates state. Run `agents prune` to act on orphan
+ * Read-only: doctor never mutates state. Run `agents prune cleanup` to act on orphan
  * readouts, or just launch the agent to apply pending sync.
  */
 import type { Command } from 'commander';

package/dist/commands/doctor.js

@@ -114,7 +114,7 @@ function renderOverviewText(clis, syncRows, orphanRows) {
             const label = `${AGENT_NAMES[row.agent] || row.agent}@${row.version}`;
             console.log(`  ${chalk.yellow('warn ')}  ${label}  ${chalk.gray(parts.join(', '))}`);
         }
-        console.log(chalk.gray('  Run `agents prune` to remove.'));
+        console.log(chalk.gray('  Run `agents prune cleanup` to remove.'));
     }
 }
 function parseTargetArg(arg) {
@@ -310,7 +310,7 @@ function renderTargetText(report, options) {
     }
     else {
         console.log(`  Verdict: ${verdictParts.join(', ')}.`);
-        console.log(chalk.gray(`  Run \`agents sync --agent ${report.agent} --agent-version ${report.version}\` to reconcile, or \`agents prune\` to drop extras.`));
+        console.log(chalk.gray(`  Run \`agents sync --agent ${report.agent} --agent-version ${report.version}\` to reconcile, or \`agents prune cleanup\` to drop extras.`));
     }
 }
 // ─── command registration ────────────────────────────────────────────────────

package/dist/commands/exec.js

@@ -9,7 +9,7 @@ import chalk from 'chalk';
 import { buildExecCommand, parseExecEnv, execAgent, runWithFallback, AGENT_COMMANDS, } from '../lib/exec.js';
 import { profileExists, resolveProfileForRun } from '../lib/profiles.js';
 import { setHelpSections } from '../lib/help.js';
-import { readBundle, resolveBundleEnv, describeBundle } from '../lib/secrets/bundles.js';
+import { readAndResolveBundleEnv, describeBundle } from '../lib/secrets/bundles.js';
 import { getConfiguredRunStrategy, normalizeRunStrategy, resolveRunVersion, RUN_STRATEGIES, } from '../lib/rotate.js';
 import { getGlobalDefault, getVersionHomePath, resolveVersionAlias } from '../lib/versions.js';
 import { buildDiscoveredPlugin, loadPluginManifest, syncPluginToVersion } from '../lib/plugins.js';
@@ -268,7 +268,7 @@ export function registerRunCommand(program) {
         let secretsEnv = {};
         for (const bundleName of options.secrets) {
             try {
-                const bundle = readBundle(bundleName);
+                const { bundle, env: bundleEnv } = readAndResolveBundleEnv(bundleName, { caller: `agent ${agent}` });
                 const entries = describeBundle(bundle);
                 const counts = {};
                 for (const e of entries) {
@@ -276,7 +276,7 @@ export function registerRunCommand(program) {
                 }
                 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, { caller: `agent ${agent}` }) };
+                secretsEnv = { ...secretsEnv, ...bundleEnv };
             }
             catch (err) {
                 console.error(chalk.red(err.message));

package/dist/commands/factory.d.ts

@@ -1,19 +1,8 @@
 /**
- * Software Factory CLI -- thin client over `prix/factory/service`.
+ * Software Factory CLI — submits Linear issues to a remote orchestrator.
  *
- * One verb today:
- *
- *   agents factory submit <linear-ref>   POST /factory/submit
- *
- * Everything else (planner pod, worker dispatch, PR-merged/CI-failed
- * webhooks, retry caps, heartbeat reaper) lives server-side in
- * `agents/prix/factory/service/src/factory.ts`, driven by the
- * `factory-tick` k8s CronJob. The laptop is optional after submit.
- *
- * Future verbs (list / status / tail / cancel / message) are intentionally
- * deferred until the matching server endpoints land; they'll be thin
- * clients too. No supervisor, ledger, oracle, or `~/.agents/factory/`
- * registry on the laptop -- ever.
+ * Requires FACTORY_FLOOR_URL pointing at a Factory-compatible endpoint.
+ * Beta-gated; enable with `agents beta enable factory`.
  */
 import type { Command } from 'commander';
 export declare function registerFactoryCommands(program: Command): void;

package/dist/commands/factory.js

@@ -51,8 +51,8 @@ export function registerFactoryCommands(program) {
         .description('Software Factory -- submit Linear tickets to the cloud orchestrator.')
         .addHelpText('after', `
 Examples:
-  agents factory submit EXAMPLE-2451
-  agents factory submit https://linear.app/example/issue/EXAMPLE-2451
+  agents factory submit PROJ-123
+  agents factory submit https://linear.app/example/issue/PROJ-123
 `);
     factory.hook('preAction', () => {
         if (enabled)
@@ -63,7 +63,7 @@ Examples:
     });
     factory
         .command('submit <linear-ref>')
-        .description('Submit a Linear issue (EXAMPLE-123 or URL) to the Software Factory.')
+        .description('Submit a Linear issue (PROJ-123 or URL) to the Software Factory.')
         .option('--json', 'Output machine-readable JSON')
         .action(async (ref, opts) => {
         const result = await postFactorySubmit(ref);

package/dist/commands/hooks.js

@@ -508,17 +508,17 @@ Examples:
         .action(() => {
         console.error(chalk.red('"agents hooks 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 hooks'));
+        console.error(chalk.gray('To remove orphans, use:  agents prune cleanup hooks'));
         process.exit(1);
     });
-    // `hooks prune` moved to the top-level `agents prune` command.
+    // `hooks prune` moved to the top-level `agents prune cleanup` command.
     hooksCmd
         .command('prune', { hidden: true })
         .allowUnknownOption()
         .allowExcessArguments()
         .action(() => {
         console.error(chalk.red('"agents hooks prune" moved.'));
-        console.error(chalk.gray('Use:  agents prune hooks   (or `agents prune` for everything)'));
+        console.error(chalk.gray('Use:  agents prune cleanup hooks   (or `agents prune cleanup` for everything)'));
         process.exit(1);
     });
     hooksCmd

package/dist/commands/plugins.js

@@ -237,6 +237,7 @@ Examples:
     pluginsCmd
         .command('sync <name> [agent]')
         .description('Apply a plugin to the default version of an agent (or all supported agents if none specified)')
+        .option('--allow-exec-surfaces', 'Enable the plugin even when it ships hooks/, .mcp.json, bin/, scripts/, settings.json, or permissions/')
         .addHelpText('after', `
 Examples:
   # Sync a plugin to a specific agent (default version)
@@ -244,8 +245,11 @@ Examples:
 
   # Sync to all supported agents
   agents plugins sync rush-toolkit
+
+  # Re-affirm consent for a hooks-bearing plugin
+  agents plugins sync hivemind claude --allow-exec-surfaces
 `)
-        .action(async (name, agentArg) => {
+        .action(async (name, agentArg, options) => {
         const plugin = getPlugin(name);
         if (!plugin) {
             console.log(chalk.red(`Plugin '${name}' not found`));
@@ -268,6 +272,7 @@ Examples:
         else {
             targetAgents = PLUGINS_CAPABLE_AGENTS.filter(a => pluginSupportsAgent(plugin, a));
         }
+        const allowExec = options.allowExecSurfaces === true;
         for (const agentId of targetAgents) {
             const versions = listInstalledVersions(agentId);
             if (versions.length === 0)
@@ -275,9 +280,11 @@ Examples:
             const defaultVer = getGlobalDefault(agentId);
             const targetVersions = defaultVer ? [defaultVer] : [versions[versions.length - 1]];
             for (const version of targetVersions) {
-                const syncResult = syncResourcesToVersion(agentId, version, { plugins: [name] });
-                if (syncResult.plugins.length > 0) {
-                    console.log(chalk.green(`Synced ${name} to ${agentLabel(agentId)}@${version}`));
+                const didSync = allowExec
+                    ? syncPluginToVersion(plugin, agentId, getVersionHomePath(agentId, version), { allowExecSurfaces: true, version }).success
+                    : syncResourcesToVersion(agentId, version, { plugins: [name] }).plugins.length > 0;
+                if (didSync) {
+                    console.log(chalk.green(`Synced ${name} to ${agentLabel(agentId)}@${version}${allowExec ? ' (exec surfaces enabled)' : ''}`));
                 }
                 else {
                     console.log(chalk.gray(`${name} already synced to ${agentLabel(agentId)}@${version}`));

package/dist/commands/profiles.js

@@ -116,7 +116,7 @@ Examples:
 
   # Add MiniMax for SWE-bench style fixes; reuses the same OpenRouter key
   agents profiles add minimax
-  agents run minimax "investigate EXAMPLE-2317 and patch the off-by-one in pagination"
+  agents run minimax "investigate PROJ-456 and patch the off-by-one in pagination"
 
   # Add DeepSeek for cheap, fast non-reasoning work
   agents profiles add deepseek

package/dist/commands/prune.js

@@ -1,5 +1,5 @@
 /**
- * Top-level `agents prune` — destructive cleanup across the install.
+ * `agents prune cleanup` — destructive cleanup across the install.
  *
  * Cleanup targets:
  *   - Resource orphans: command/skill/hook files inside a version home that no
@@ -7,8 +7,9 @@
  *     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.
+ *   - Trash/session targets are retained as no-op compatibility shims: version
+ *     homes and session history are durable and must not be hard-deleted by
+ *     agents-cli.
  *   - Runs: routine execution logs, keeping only the last N per job.
  *
  * Sync (additive: copy missing/changed files into version homes) is no longer
@@ -21,7 +22,6 @@
  * 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';
@@ -34,7 +34,6 @@ 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', 'plugins', 'subagents'];
 const STATE_TYPES = ['trash', 'sessions', 'runs'];
@@ -125,12 +124,6 @@ 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`;
@@ -140,137 +133,25 @@ function formatBytes(bytes) {
         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 */ }
+    if (options.olderThan || options.yes || options.dryRun) {
+        console.log(chalk.gray('Trash expiry flags are accepted for compatibility but do not delete data.'));
     }
-    console.log(chalk.green(`Pruned ${deleted} trash entries (${formatBytes(totalSize)}).`));
+    console.log(chalk.yellow('Trash is durable. agents-cli does not hard-delete soft-deleted version data.'));
+    console.log(chalk.gray('Inspect recoverable versions with: agents trash list'));
+    console.log(chalk.gray(`Trash path: ${trashDir}`));
 }
 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;
+    if (options.olderThan || options.yes || options.dryRun) {
+        console.log(chalk.gray('Session prune flags are accepted for compatibility but do not delete data.'));
     }
-    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.`));
+    console.log(chalk.yellow('Session history is durable. agents-cli does not hard-delete session records.'));
+    console.log(chalk.gray('Browse sessions with: agents sessions'));
 }
 async function runRunsPrune(options) {
     const keep = options.keep ? parseInt(options.keep, 10) : 10;
@@ -380,13 +261,16 @@ async function runOrphanPrune(resourceTypes, options) {
     console.log(chalk.green(summary) + (failures > 0 ? chalk.red(`, ${failures} failed`) : '') + '.');
 }
 export function registerPruneCommand(program) {
-    program
-        .command('prune [target]')
-        .description('Remove orphan resources, old versions, trash, sessions, or routine runs')
+    const pruneCmd = program.commands.find((cmd) => cmd.name() === 'prune') ?? program
+        .command('prune <specs...>')
+        .description('Uninstall agent CLI versions. Moves version data to trash for recovery.');
+    pruneCmd
+        .command('cleanup [target]')
+        .description('Remove orphan resources, old versions, 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 (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('--older-than <days>', 'Deprecated for trash/sessions; accepted but no data is deleted')
         .option('--keep <n>', 'For runs: keep the last N runs per job (default: 10)')
         .addHelpText('after', `
 Targets:
@@ -396,46 +280,40 @@ 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)
+  trash      No-op compatibility target; trash is durable
+  sessions   No-op compatibility target; session history is durable
   runs       Routine execution logs, keeping only --keep per job (default 10)
 
 Examples:
   # Full sweep: orphan resources + duplicate versions for current defaults
-  agents prune
+  agents prune cleanup
 
   # Preview what a full sweep would remove
-  agents prune --dry-run
+  agents prune cleanup --dry-run
 
   # Just orphan skills
-  agents prune skills
+  agents prune cleanup skills
 
   # Just version dedup
-  agents prune versions
+  agents prune cleanup versions
 
   # Deduplicate versions for one agent only
-  agents prune claude
+  agents prune cleanup claude
 
   # Sweep every installed version's orphans, not only the defaults
-  agents prune --all
-
-  # 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
+  agents prune cleanup --all
 
-  # Preview session cleanup (90+ days old)
-  agents prune sessions --dry-run
+  # Show the durable-trash notice
+  agents prune cleanup trash --dry-run
 
-  # Delete sessions older than 180 days
-  agents prune sessions --older-than 180 -y
+  # Show the durable-session notice
+  agents prune cleanup sessions --dry-run
 
   # Preview runs cleanup (keeping last 10)
-  agents prune runs --dry-run
+  agents prune cleanup runs --dry-run
 
   # Keep only the last 5 runs per job
-  agents prune runs --keep 5 -y
+  agents prune cleanup runs --keep 5 -y
 
 What's an orphan?
   A command, skill, or hook present inside a version home but missing from every
@@ -443,10 +321,11 @@ What's an orphan?
   repos). Usually leftovers from a resource that was deleted or moved but never
   reconciled into the version install.
 
-Soft-delete:
-  Version directories are NEVER hard-deleted. \`prune\` moves them to
-  ~/.agents/.trash/versions/<agent>/<version>/<timestamp>/. Use
-  \`agents prune trash\` to expire old trash entries.
+Durability:
+  Version directories are NEVER hard-deleted by agents-cli. Version prune and
+  cleanup move them to ~/.agents/.history/trash/versions/<agent>/<version>/<timestamp>/.
+  Session records are also durable; the sessions target remains only as a no-op
+  compatibility shim.
 `)
         .action(async (target, options) => {
         const parsed = parseTarget(target);

package/dist/commands/pull.js

@@ -14,10 +14,11 @@ import { isGitRepo, pullRepo, isSystemRepoOrigin, } from '../lib/git.js';
 import * as fs from 'fs';
 import * as path from 'path';
 import { installVersion, listInstalledVersions, getGlobalDefault, setGlobalDefault, getVersionHomePath, syncResourcesToVersion, getAvailableResources, getActuallySyncedResources, getNewResources, hasNewResources, promptNewResourceSelection, promptResourceSelection, resolveConfiguredAgentTargets, } from '../lib/versions.js';
+import { listCliStatus, installCli, describeMethod, selectInstallMethod, } from '../lib/cli-resources.js';
 import { ensureShimCurrent, isShimsInPath, addShimsToPath, getPathSetupInstructions, switchConfigSymlink, switchHomeFileSymlinks, } from '../lib/shims.js';
 import { parseHookManifest, registerHooksToSettings } from '../lib/hooks.js';
 import { setHelpSections } from '../lib/help.js';
-import { select } from '@inquirer/prompts';
+import { select, confirm } from '@inquirer/prompts';
 import { isInteractiveTerminal, isPromptCancelled } from './utils.js';
 /**
  * Old repo layout stored promptcuts under claude/promptcuts.yaml (agent-scoped).
@@ -244,10 +245,10 @@ export function registerPullCommand(program) {
                         if (userSelection)
                             selection = userSelection;
                     }
-                    else if (hasNewResources(newResources, agentId)) {
+                    else if (hasNewResources(newResources, agentId, defaultVer)) {
                         // Has synced before, but NEW items available
                         console.log(chalk.cyan(`\n${agentLabel(agentId)}@${defaultVer}:`));
-                        const userSelection = await promptNewResourceSelection(agentId, newResources);
+                        const userSelection = await promptNewResourceSelection(agentId, newResources, defaultVer);
                         if (userSelection)
                             selection = userSelection;
                     }
@@ -366,6 +367,58 @@ export function registerPullCommand(program) {
                     console.log(chalk.green(`Set ${agentLabel(agent.id)}@${version} as default`));
                 }
             }
+            // Report (and optionally install) any declared CLIs that are missing
+            // from the host. Skipped under -y so non-interactive pulls don't trigger
+            // package-manager prompts.
+            try {
+                const { statuses, errors } = listCliStatus(process.cwd());
+                for (const err of errors) {
+                    console.log(chalk.yellow(`  CLI manifest parse error: ${err.file}: ${err.reason}`));
+                }
+                const missing = statuses.filter((s) => !s.installed);
+                if (missing.length > 0) {
+                    console.log(chalk.bold('\nDeclared CLIs missing from this host:'));
+                    for (const s of missing) {
+                        const method = selectInstallMethod(s.manifest);
+                        const action = method ? describeMethod(method) : chalk.red('no compatible install method');
+                        console.log(`  ${chalk.cyan(s.manifest.name.padEnd(20))} ${chalk.gray(action)}`);
+                    }
+                    console.log('');
+                    if (!skipPrompts) {
+                        const proceed = await confirm({ message: `Install ${missing.length} missing CLI(s) now?`, default: true });
+                        if (proceed) {
+                            for (const s of missing) {
+                                console.log(chalk.bold(`\n→ ${s.manifest.name}`));
+                                const result = installCli(s.manifest);
+                                if (result.error) {
+                                    console.log(chalk.red(`  ${result.error}`));
+                                    continue;
+                                }
+                                if (result.installed) {
+                                    console.log(chalk.green(`  installed`));
+                                    if (s.manifest.postInstall) {
+                                        console.log(chalk.gray(s.manifest.postInstall.trim().split('\n').map((l) => '  ' + l).join('\n')));
+                                    }
+                                }
+                                else {
+                                    console.log(chalk.yellow(`  install ran but \`${s.manifest.check}\` still fails`));
+                                }
+                            }
+                        }
+                        else {
+                            console.log(chalk.gray(`Skipped. Run 'agents cli install' later.`));
+                        }
+                    }
+                    else {
+                        console.log(chalk.gray(`Run 'agents cli install' to install them.`));
+                    }
+                }
+            }
+            catch (err) {
+                if (!isPromptCancelled(err)) {
+                    console.log(chalk.yellow(`CLI install skipped: ${err.message}`));
+                }
+            }
             console.log(chalk.green('\nPull complete'));
         }
         catch (err) {