@phnx-labs/agents-cli 1.20.11 → 1.20.13

package/dist/commands/trash.js

@@ -110,6 +110,61 @@ function humanSize(bytes) {
         return `${(bytes / 1024 / 1024).toFixed(1)} MB`;
     return `${(bytes / 1024 / 1024 / 1024).toFixed(2)} GB`;
 }
+/**
+ * Restore a soft-deleted version back into ~/.agents/.history/versions/.
+ * Shared by `agents trash restore` and the top-level `agents restore` alias.
+ * Exits the process with a non-zero code on any failure.
+ */
+export function restoreVersion(target) {
+    const parsed = parseAgentVersion(target);
+    if (!parsed) {
+        console.error(chalk.red(`Expected <agent>@<version>, got: ${target}`));
+        process.exit(1);
+    }
+    const { agent, version } = parsed;
+    const entries = listTrashEntries(agent);
+    const entry = pickLatest(entries, agent, version);
+    if (!entry) {
+        console.error(chalk.red(`No trashed copy found for ${agent}@${version}`));
+        console.error(chalk.gray('Run `agents trash list` to see what exists.'));
+        process.exit(1);
+    }
+    const dest = getVersionDir(agent, version);
+    if (fs.existsSync(dest)) {
+        console.error(chalk.red(`Cannot restore: ${dest} already exists.`));
+        console.error(chalk.gray('Move or remove the existing dir first, then re-run restore.'));
+        process.exit(1);
+    }
+    try {
+        fs.mkdirSync(path.dirname(dest), { recursive: true, mode: 0o700 });
+        fs.renameSync(entry.trashPath, dest);
+    }
+    catch (err) {
+        console.error(chalk.red(`Restore failed: ${err.message}`));
+        process.exit(1);
+    }
+    // Best-effort cleanup of empty stamp/version parents in trash.
+    try {
+        const verDir = path.dirname(entry.trashPath);
+        if (fs.readdirSync(verDir).length === 0)
+            fs.rmdirSync(verDir);
+        const agentDir = path.dirname(verDir);
+        if (fs.readdirSync(agentDir).length === 0)
+            fs.rmdirSync(agentDir);
+    }
+    catch { /* best-effort */ }
+    console.log(chalk.green(`Restored ${agentLabel(agent)}@${version} to ${dest}`));
+}
+/**
+ * Register the top-level `agents restore` command — a shorthand for
+ * `agents trash restore` so users can undo a `remove`/`prune` directly.
+ */
+export function registerRestoreCommand(program) {
+    program
+        .command('restore <target>')
+        .description('Restore a soft-deleted agent version (e.g. "codex@0.141.0") removed via prune/remove')
+        .action((target) => restoreVersion(target));
+}
 export function registerTrashCommands(program) {
     const trash = program
         .command('trash')
@@ -139,49 +194,10 @@ export function registerTrashCommands(program) {
                 chalk.gray(`${e.stamp}  ${size}  ${e.trashPath}`));
         }
         console.log();
-        console.log(chalk.gray('Restore with: agents trash restore <agent>@<version>'));
+        console.log(chalk.gray('Restore with: agents restore <agent>@<version>'));
     });
     trash
         .command('restore <target>')
         .description('Restore a soft-deleted version (e.g. "claude@2.1.110") back to ~/.agents/.history/versions/')
-        .action((target) => {
-        const parsed = parseAgentVersion(target);
-        if (!parsed) {
-            console.error(chalk.red(`Expected <agent>@<version>, got: ${target}`));
-            process.exit(1);
-        }
-        const { agent, version } = parsed;
-        const entries = listTrashEntries(agent);
-        const entry = pickLatest(entries, agent, version);
-        if (!entry) {
-            console.error(chalk.red(`No trashed copy found for ${agent}@${version}`));
-            console.error(chalk.gray('Run `agents trash list` to see what exists.'));
-            process.exit(1);
-        }
-        const dest = getVersionDir(agent, version);
-        if (fs.existsSync(dest)) {
-            console.error(chalk.red(`Cannot restore: ${dest} already exists.`));
-            console.error(chalk.gray('Move or remove the existing dir first, then re-run restore.'));
-            process.exit(1);
-        }
-        try {
-            fs.mkdirSync(path.dirname(dest), { recursive: true, mode: 0o700 });
-            fs.renameSync(entry.trashPath, dest);
-        }
-        catch (err) {
-            console.error(chalk.red(`Restore failed: ${err.message}`));
-            process.exit(1);
-        }
-        // Best-effort cleanup of empty stamp/version parents in trash.
-        try {
-            const verDir = path.dirname(entry.trashPath);
-            if (fs.readdirSync(verDir).length === 0)
-                fs.rmdirSync(verDir);
-            const agentDir = path.dirname(verDir);
-            if (fs.readdirSync(agentDir).length === 0)
-                fs.rmdirSync(agentDir);
-        }
-        catch { /* best-effort */ }
-        console.log(chalk.green(`Restored ${agentLabel(agent)}@${version} to ${dest}`));
-    });
+        .action((target) => restoreVersion(target));
 }

package/dist/commands/versions.js

@@ -7,7 +7,8 @@ import { AGENTS, ALL_AGENT_IDS, getAccountEmail, getAccountInfo, agentLabel, } f
 import { formatUsageSummary, getUsageInfoForIdentity, getUsageInfoByIdentity, getUsageLookupKey, } from '../lib/usage.js';
 import { viewAction } from './view.js';
 import { readManifest, writeManifest, createDefaultManifest } from '../lib/manifest.js';
-import { installVersion, removeVersion, listInstalledVersions, isVersionInstalled, isLatestInstalled, getGlobalDefault, setGlobalDefault, getVersionHomePath, getVersionDir, syncResourcesToVersion, parseAgentSpec, promptResourceSelection, promptNewResourceSelection, getAvailableResources, getActuallySyncedResources, getNewResources, getProjectOnlyResources, hasNewResources, printTrashFooter, } from '../lib/versions.js';
+import { installVersion, removeVersion, listInstalledVersions, isVersionInstalled, isLatestInstalled, isOldestInstalled, getGlobalDefault, setGlobalDefault, getVersionHomePath, getVersionDir, syncResourcesToVersion, parseAgentSpec, promptResourceSelection, promptNewResourceSelection, getAvailableResources, getActuallySyncedResources, getNewResources, getProjectOnlyResources, hasNewResources, printTrashFooter, } from '../lib/versions.js';
+import { carryForwardSettings } from '../lib/settings-manifest.js';
 import { createShim, createVersionedAlias, removeShim, shimExists, getShimsDir, getShimPath, getPathShadowingExecutable, isShimsInPath, getPathSetupInstructions, addShimsToPath, switchConfigSymlink, switchHomeFileSymlinks, } from '../lib/shims.js';
 import { isInteractiveTerminal, isPromptCancelled, requireInteractiveSelection } from './utils.js';
 import { tryAutoPull } from '../lib/git.js';
@@ -28,17 +29,6 @@ function fixSessionFilePaths(agent, version, oldVersionDir) {
     const trashPath = path.join(trashAgentDir, stamps[0]);
     updateSessionFilePaths(oldVersionDir, trashPath);
 }
-/**
- * Helper to get actual installed version for an agent.
- * Returns the latest installed version, or throws if none installed.
- */
-async function getInstalledVersionForAgent(agent) {
-    const versions = listInstalledVersions(agent);
-    if (versions.length > 0) {
-        return versions[versions.length - 1];
-    }
-    throw new Error(`No versions of ${agent} installed`);
-}
 function formatAccountHint(info, usage) {
     const parts = [];
     if (info.email)
@@ -91,7 +81,17 @@ function warnIfShimShadowed(agent) {
     }
     console.log(chalk.yellow(`  Warning: ${AGENTS[agent].cliCommand} currently resolves to ${shadowedBy}`));
     console.log(chalk.gray(`  Managed shim: ${getShimPath(agent)}`));
-    console.log(chalk.gray(`  ${getPathSetupInstructions().split('\n').join('\n  ')}`));
+    const result = addShimsToPath();
+    if (!result.success) {
+        console.log(chalk.gray(`  ${getPathSetupInstructions().split('\n').join('\n  ')}`));
+        return;
+    }
+    if (result.alreadyPresent) {
+        console.log(chalk.gray(`  Shim PATH entry already set — ${AGENTS[agent].cliCommand} is shadowed by another binary. Remove or reorder it so ${getShimPath(agent)} takes priority.`));
+        return;
+    }
+    console.log(chalk.green(`  Added shim directory to ${result.location}.`));
+    console.log(chalk.gray(`  ${result.reloadHint}`));
 }
 async function versionPruneAction(specs, options, commandName) {
     const isProject = options.project;
@@ -105,7 +105,7 @@ async function versionPruneAction(specs, options, commandName) {
         }
         const { agent, version } = parsed;
         const agentConfig = AGENTS[agent];
-        if (version === 'latest' || !spec.includes('@')) {
+        if (version === 'latest' || version === 'oldest' || !spec.includes('@')) {
             const versions = listInstalledVersions(agent);
             if (versions.length === 0) {
                 console.log(chalk.gray(`No versions of ${agentLabel(agentConfig.id)} installed`));
@@ -139,7 +139,11 @@ async function versionPruneAction(specs, options, commandName) {
                 }
                 for (const v of toRemove) {
                     const versionDir = getVersionDir(agent, v);
-                    removeVersion(agent, v);
+                    const removed = removeVersion(agent, v);
+                    if (!removed) {
+                        console.log(chalk.red(`Failed to move ${agentLabel(agentConfig.id)}@${v} to trash — a file may be locked by a running process. Close any active sessions and try again.`));
+                        continue;
+                    }
                     fixSessionFilePaths(agent, v, versionDir);
                     console.log(chalk.green(`Moved ${agentLabel(agentConfig.id)}@${v} to trash`));
                     moved.push({ agent, version: v });
@@ -166,7 +170,11 @@ async function versionPruneAction(specs, options, commandName) {
         }
         else {
             const versionDir = getVersionDir(agent, version);
-            removeVersion(agent, version);
+            const removed = removeVersion(agent, version);
+            if (!removed) {
+                console.log(chalk.red(`Failed to move ${agentLabel(agentConfig.id)}@${version} to trash — a file may be locked by a running process. Close any active sessions and try again.`));
+                continue;
+            }
             fixSessionFilePaths(agent, version, versionDir);
             console.log(chalk.green(`Moved ${agentLabel(agentConfig.id)}@${version} to trash`));
             moved.push({ agent, version });
@@ -228,6 +236,9 @@ export function registerVersionsCommands(program) {
       # Install the latest version of an agent
       agents add claude@latest
 
+      # Install the oldest published version of an agent
+      agents add claude@oldest
+
       # Install a specific version (reproducibility)
       agents add claude@2.1.112
 
@@ -259,7 +270,7 @@ export function registerVersionsCommands(program) {
                 console.log(chalk.yellow(`${agentLabel(agentConfig.id)} has no npm package. Install manually.`));
                 continue;
             }
-            // Check if already installed (handle 'latest' specially)
+            // Check if already installed (resolve 'latest'/'oldest' against npm first)
             let alreadyInstalled = false;
             let installedAsVersion = version;
             if (version === 'latest') {
@@ -269,6 +280,13 @@ export function registerVersionsCommands(program) {
                     installedAsVersion = latestCheck.version;
                 }
             }
+            else if (version === 'oldest') {
+                const oldestCheck = await isOldestInstalled(agent);
+                if (oldestCheck.installed && oldestCheck.version) {
+                    alreadyInstalled = true;
+                    installedAsVersion = oldestCheck.version;
+                }
+            }
             else {
                 alreadyInstalled = isVersionInstalled(agent, version);
             }
@@ -290,6 +308,19 @@ export function registerVersionsCommands(program) {
                         console.log(chalk.gray(`  Created shim: ${getShimsDir()}/${agentConfig.cliCommand}`));
                     }
                     const installedVersion = result.installedVersion || version;
+                    // Track the concrete version so a `--project` pin records it instead
+                    // of the `latest`/`oldest` alias.
+                    installedAsVersion = installedVersion;
+                    // Seed the fresh version home with user settings from the current
+                    // default version (settings.json, keybindings, codex config/auth).
+                    // Gap-filling only — never overwrites what the new home has.
+                    const carrySource = getGlobalDefault(agent);
+                    if (carrySource && carrySource !== installedVersion) {
+                        const carried = carryForwardSettings(agent, getVersionHomePath(agent, carrySource), getVersionHomePath(agent, installedVersion));
+                        if (carried.applied.length > 0) {
+                            console.log(chalk.gray(`  Carried settings from ${agent}@${carrySource}: ${carried.applied.map(r => path.basename(r)).join(', ')}`));
+                        }
+                    }
                     // Smart resource detection: compare available vs ACTUALLY synced (source of truth: files)
                     const available = getAvailableResources();
                     const actuallySynced = getActuallySyncedResources(agent, installedVersion);
@@ -428,14 +459,19 @@ export function registerVersionsCommands(program) {
                     ? readManifest(process.cwd()) || createDefaultManifest()
                     : createDefaultManifest();
                 manifest.agents = manifest.agents || {};
-                manifest.agents[agent] = version === 'latest' ? (await getInstalledVersionForAgent(agent)) : version;
+                manifest.agents[agent] = (version === 'latest' || version === 'oldest')
+                    ? installedAsVersion
+                    : version;
                 writeManifest(process.cwd(), manifest);
                 console.log(chalk.green(`  Pinned ${agentLabel(agentConfig.id)}@${version} in .agents/agents.yaml`));
             }
         }
     });
     configureVersionPruneCommand(program.command('prune <specs...>'), 'prune');
-    configureVersionPruneCommand(program.command('remove <specs...>', { hidden: true }), 'remove');
+    // `rm` and `purge` are commander aliases for `remove` (which is itself an
+    // alias for `prune`). Native `.aliases()` keeps them in lockstep — same
+    // action, same options, no duplicate registration.
+    configureVersionPruneCommand(program.command('remove <specs...>', { hidden: true }).aliases(['rm', 'purge']), 'remove');
     const useCmd = program
         .command('use <agent> [version]')
         .description('Switch the active version for an agent. This is the only command that sets the default.')
@@ -478,7 +514,7 @@ export function registerVersionsCommands(program) {
                     return;
                 }
                 agent = parsed.agent;
-                version = parsed.version === 'latest' ? undefined : parsed.version;
+                version = (parsed.version === 'latest' || parsed.version === 'oldest') ? undefined : parsed.version;
             }
             else {
                 const agentLower = agentArg.toLowerCase();
@@ -679,6 +715,18 @@ export function registerVersionsCommands(program) {
                     }
                 }
                 const previousDefault = getGlobalDefault(agentId);
+                // Carry user settings from the outgoing default into the target
+                // version home before switching. Gap-filling only, so versions that
+                // already have their own settings are left untouched.
+                if (previousDefault && previousDefault !== finalVersion) {
+                    const carried = carryForwardSettings(agentId, getVersionHomePath(agentId, previousDefault), getVersionHomePath(agentId, finalVersion));
+                    if (carried.applied.length > 0) {
+                        console.log(chalk.gray(`Carried settings from ${agentId}@${previousDefault}: ${carried.applied.map(r => path.basename(r)).join(', ')}`));
+                        if (carried.backupDir) {
+                            console.log(chalk.gray(`  Pre-merge backup: ${carried.backupDir}`));
+                        }
+                    }
+                }
                 // Set global default
                 setGlobalDefault(agentId, finalVersion);
                 // Regenerate shim so it uses the latest script format

package/dist/commands/view.js

@@ -6,7 +6,7 @@ import { AGENTS, ALL_AGENT_IDS, getAllCliStates, getAccountInfo, resolveAgentNam
 import { formatUsageSection, formatUsageSummary, formatUsageStatusBadge, getUsageInfoForIdentity, getUsageInfoByIdentity, getUsageLookupKey, } from '../lib/usage.js';
 import { readManifest } from '../lib/manifest.js';
 import { listInstalledVersions, listInstalledVersionDirs, getGlobalDefault, getVersionHomePath, getVersionDir, resolveVersionAlias, getAvailableResources, getActuallySyncedResources, getNewResources, getProjectOnlyResources, hasNewResources, promptNewResourceSelection, syncResourcesToVersion, removeVersion, printTrashFooter, } from '../lib/versions.js';
-import { getShimsDir, isShimsInPath, ensureVersionedAliasCurrent, removeShim, } from '../lib/shims.js';
+import { ensureVersionedAliasCurrent, removeShim, } from '../lib/shims.js';
 import { getAgentResources } from '../lib/resources.js';
 import { isCapable } from '../lib/capabilities.js';
 import { discoverPlugins, pluginSupportsAgent } from '../lib/plugins.js';
@@ -537,17 +537,6 @@ async function showInstalledVersions(filterAgentId) {
         console.log(chalk.gray('  Run: agents add claude@latest'));
         console.log();
     }
-    // Show shims path status at the end (only for full list with managed versions)
-    if (versionManaged.length > 0 && !filterAgentId) {
-        const shimsDir = getShimsDir();
-        if (isShimsInPath()) {
-            console.log(chalk.gray(`Shims: ${shimsDir} (in PATH)`));
-        }
-        else {
-            console.log(chalk.yellow(`Shims: ${shimsDir} (not in PATH)`));
-            console.log(chalk.gray('Add to PATH for automatic version switching'));
-        }
-    }
     // Check for new resources when viewing a specific agent
     if (filterAgentId && versionManaged.length > 0) {
         const defaultVersion = getGlobalDefault(filterAgentId);

package/dist/commands/wallet.d.ts

@@ -0,0 +1,14 @@
+/**
+ * `agents wallet` — a device-local credit-card vault backed by macOS Keychain.
+ *
+ * UX intent matches Apple Wallet: list cards freely (no biometric), reveal
+ * a card with Touch ID. Card numbers never leave the device. This is NOT
+ * Apple Pay — we store the real PAN, not a network DPAN, and do not generate
+ * per-transaction cryptograms. The help text reflects this.
+ *
+ * Bundle layout:
+ *   ~/.agents/wallet/cards.json                   metadata (id, last4, brand, exp)
+ *   agents-cli.secrets.wallet.<id>                JSON {pan, cvc, cardholder}
+ */
+import type { Command } from 'commander';
+export declare function registerWalletCommands(program: Command): void;

package/dist/commands/wallet.js

@@ -0,0 +1,199 @@
+/**
+ * `agents wallet` — a device-local credit-card vault backed by macOS Keychain.
+ *
+ * UX intent matches Apple Wallet: list cards freely (no biometric), reveal
+ * a card with Touch ID. Card numbers never leave the device. This is NOT
+ * Apple Pay — we store the real PAN, not a network DPAN, and do not generate
+ * per-transaction cryptograms. The help text reflects this.
+ *
+ * Bundle layout:
+ *   ~/.agents/wallet/cards.json                   metadata (id, last4, brand, exp)
+ *   agents-cli.secrets.wallet.<id>                JSON {pan, cvc, cardholder}
+ */
+import chalk from 'chalk';
+import { addCard, detectBrand, isValidLuhn, listCards, removeCard, renameCard, showCard, } from '../lib/wallet/index.js';
+import { isInteractiveTerminal, isPromptCancelled } from './utils.js';
+import { setHelpSections } from '../lib/help.js';
+function brandLabel(b) {
+    switch (b) {
+        case 'visa': return 'Visa';
+        case 'mastercard': return 'Mastercard';
+        case 'amex': return 'American Express';
+        case 'discover': return 'Discover';
+        case 'diners': return 'Diners Club';
+        case 'jcb': return 'JCB';
+        case 'unionpay': return 'UnionPay';
+        default: return 'Card';
+    }
+}
+function formatExp(month, year) {
+    return `${month}/${year.slice(-2)}`;
+}
+function renderRow(c) {
+    const nick = c.nickname.padEnd(24);
+    const brand = brandLabel(c.brand).padEnd(18);
+    const last4 = `•••• ${c.last4}`.padEnd(10);
+    const exp = formatExp(c.exp_month, c.exp_year);
+    return `  ${chalk.cyan(nick)} ${brand} ${last4} ${chalk.gray('exp ' + exp)}  ${chalk.gray(c.id)}`;
+}
+async function promptString(message, validate) {
+    const { input } = await import('@inquirer/prompts');
+    return await input({ message, validate });
+}
+async function promptSecret(message) {
+    const { password } = await import('@inquirer/prompts');
+    return await password({ message, mask: true });
+}
+function requireTTY(action) {
+    if (!isInteractiveTerminal()) {
+        throw new Error(`'agents wallet ${action}' requires an interactive terminal.`);
+    }
+}
+export function registerWalletCommands(program) {
+    const cmd = program
+        .command('wallet')
+        .description('Device-local credit-card vault backed by macOS Keychain (Touch ID required to reveal). ' +
+        'Encrypted at rest, never leaves your device. Not Apple Pay — stores real PANs, no tokenization.');
+    setHelpSections(cmd, {
+        examples: `
+      $ agents wallet add                              # interactive: PAN, CVC, expiry, nickname
+      $ agents wallet list                             # last 4 only, no Touch ID prompt
+      $ agents wallet show personal-amex               # Touch ID required, reveals full card
+      $ agents wallet rename personal-amex "Travel"
+      $ agents wallet remove personal-amex
+    `,
+    });
+    cmd
+        .command('add')
+        .description('Add a card to the vault. Interactive prompt for PAN, CVC, expiry, cardholder, nickname.')
+        .option('--nickname <name>', 'Set the nickname non-interactively (still prompts for PAN/CVC)')
+        .option('--stdin-json', 'Read all fields as a JSON object on stdin (for IPC callers). Emits the new card metadata as JSON to stdout.')
+        .action(async (opts) => {
+        try {
+            if (opts.stdinJson) {
+                const raw = await new Promise((resolve, reject) => {
+                    const chunks = [];
+                    process.stdin.on('data', (c) => {
+                        chunks.push(typeof c === 'string' ? Buffer.from(c) : c);
+                    });
+                    process.stdin.on('end', () => resolve(Buffer.concat(chunks).toString('utf-8')));
+                    process.stdin.on('error', reject);
+                });
+                const input = JSON.parse(raw);
+                const meta = addCard(input);
+                process.stdout.write(JSON.stringify({ card: meta }) + '\n');
+                return;
+            }
+            requireTTY('add');
+            const pan = (await promptSecret('Card number')).replace(/\s+/g, '');
+            if (!/^\d+$/.test(pan))
+                throw new Error('PAN must contain only digits.');
+            if (!isValidLuhn(pan))
+                throw new Error('PAN failed Luhn checksum — typo?');
+            const brand = detectBrand(pan);
+            console.log(chalk.gray(`Detected: ${brandLabel(brand)} •••• ${pan.slice(-4)}`));
+            const exp_month = await promptString('Expiration month (MM)', (v) => {
+                const n = Number(v);
+                return Number.isInteger(n) && n >= 1 && n <= 12 ? true : 'Month must be 1-12';
+            });
+            const exp_year = await promptString('Expiration year (YY or YYYY)', (v) => {
+                const d = v.replace(/\D/g, '');
+                return d.length === 2 || d.length === 4 ? true : 'Year must be 2 or 4 digits';
+            });
+            const cvc = (await promptSecret('CVC')).replace(/\s+/g, '');
+            if (!/^\d{3,4}$/.test(cvc))
+                throw new Error('CVC must be 3 or 4 digits.');
+            const cardholder = await promptString('Cardholder name (as printed)');
+            const nickname = opts.nickname?.trim() || await promptString('Nickname (e.g. Personal Amex)', (v) => v.trim() ? true : 'Required');
+            const meta = addCard({ nickname, pan, cvc, cardholder, exp_month, exp_year });
+            console.log(chalk.green(`Added ${brandLabel(meta.brand)} •••• ${meta.last4} as '${meta.nickname}' (id: ${meta.id})`));
+        }
+        catch (err) {
+            if (isPromptCancelled(err))
+                return;
+            console.error(chalk.red(err.message));
+            process.exit(1);
+        }
+    });
+    cmd
+        .command('list')
+        .alias('ls')
+        .description('List stored cards (metadata only — last 4, brand, expiry). No biometric prompt.')
+        .option('--json', 'Emit JSON to stdout')
+        .action((opts) => {
+        try {
+            const cards = listCards();
+            if (opts.json) {
+                process.stdout.write(JSON.stringify({ cards }, null, 2) + '\n');
+                return;
+            }
+            if (cards.length === 0) {
+                console.log(chalk.gray('No cards in wallet. Try: agents wallet add'));
+                return;
+            }
+            console.log(chalk.bold(`  ${'NICKNAME'.padEnd(24)} ${'BRAND'.padEnd(18)} ${'LAST4'.padEnd(10)} EXP        ID`));
+            for (const c of cards)
+                console.log(renderRow(c));
+        }
+        catch (err) {
+            console.error(chalk.red(err.message));
+            process.exit(1);
+        }
+    });
+    cmd
+        .command('show <id>')
+        .description('Reveal a card. Touch ID required. Argument is a card id or nickname.')
+        .option('--json', 'Emit JSON to stdout (still triggers Touch ID)')
+        .action((id, opts) => {
+        try {
+            const full = showCard(id);
+            if (opts.json) {
+                process.stdout.write(JSON.stringify(full, null, 2) + '\n');
+                return;
+            }
+            console.log();
+            console.log(chalk.bold(`  ${full.nickname}`));
+            console.log(`  ${chalk.gray('Brand     ')} ${brandLabel(full.brand)}`);
+            console.log(`  ${chalk.gray('Number    ')} ${full.pan.match(/.{1,4}/g)?.join(' ') ?? full.pan}`);
+            console.log(`  ${chalk.gray('CVC       ')} ${full.cvc}`);
+            console.log(`  ${chalk.gray('Expires   ')} ${formatExp(full.exp_month, full.exp_year)}`);
+            console.log(`  ${chalk.gray('Holder    ')} ${full.cardholder}`);
+            console.log();
+        }
+        catch (err) {
+            console.error(chalk.red(err.message));
+            process.exit(1);
+        }
+    });
+    cmd
+        .command('remove <id>')
+        .alias('rm')
+        .description('Remove a card from the vault. Argument is a card id or nickname.')
+        .action((id) => {
+        try {
+            const meta = removeCard(id);
+            if (!meta) {
+                console.error(chalk.red(`No card found matching '${id}'.`));
+                process.exit(1);
+            }
+            console.log(chalk.green(`Removed '${meta.nickname}' (${brandLabel(meta.brand)} •••• ${meta.last4}).`));
+        }
+        catch (err) {
+            console.error(chalk.red(err.message));
+            process.exit(1);
+        }
+    });
+    cmd
+        .command('rename <id> <new-nickname>')
+        .description('Rename a card. Argument is the current id or nickname.')
+        .action((id, newNickname) => {
+        try {
+            const meta = renameCard(id, newNickname);
+            console.log(chalk.green(`Renamed to '${meta.nickname}'.`));
+        }
+        catch (err) {
+            console.error(chalk.red(err.message));
+            process.exit(1);
+        }
+    });
+}

package/dist/index.js

@@ -78,7 +78,7 @@ import { registerRunCommand } from './commands/exec.js';
 import { registerModelsCommand } from './commands/models.js';
 import { registerDefaultsCommands } from './commands/defaults.js';
 import { registerPruneCommand } from './commands/prune.js';
-import { registerTrashCommands } from './commands/trash.js';
+import { registerTrashCommands, registerRestoreCommand } from './commands/trash.js';
 import { registerDoctorCommand } from './commands/doctor.js';
 import { registerSubagentsCommands } from './commands/subagents.js';
 import { registerPluginsCommands } from './commands/plugins.js';
@@ -93,6 +93,7 @@ import { registerBrowserCommand } from './commands/browser.js';
 import { registerComputerCommand } from './commands/computer.js';
 import { registerProfilesCommands } from './commands/profiles.js';
 import { registerSecretsCommands } from './commands/secrets.js';
+import { registerWalletCommands } from './commands/wallet.js';
 import { registerHelperCommand } from './commands/helper.js';
 import { registerFactoryCommands } from './commands/factory.js';
 import { registerUsageCommand } from './commands/usage.js';
@@ -348,6 +349,24 @@ async function installResolvedPackage(metadata) {
     await installPackageIntoPrefix(`${NPM_PACKAGE_NAME}@${metadata.version}`, prefix);
     verifyInstalledVersion(packageRoot, metadata.version);
     refreshAliasShims(packageRoot);
+    // The npm install above runs with --ignore-scripts, so the postinstall that
+    // installs the macOS Keychain helper never fires on upgrade. Force-refresh the
+    // helper here so a user upgrading FROM a broken build (e.g. the entitlement-less
+    // 1.20.4 helper that fails SecItemAdd with -34018) gets the fixed, signed bundle
+    // immediately — instead of waiting for the lazy staleness check in
+    // getKeychainHelperPath() to repair it on their next secret operation. The new
+    // package is already on disk, so the dynamic import resolves the freshly-installed
+    // helper module + bundle. Best-effort: an upgrade must never fail because the
+    // helper could not be reinstalled (`agents helper install --force` stays available).
+    if (process.platform === 'darwin') {
+        try {
+            const { ensureKeychainHelperInstalled } = await import('./lib/secrets/install-helper.js');
+            ensureKeychainHelperInstalled({ forceReinstall: true });
+        }
+        catch {
+            // Non-fatal.
+        }
+    }
 }
 /** Present an interactive upgrade prompt (TTY) or a one-line hint (non-TTY). */
 async function promptUpgrade(latestVersion) {
@@ -637,6 +656,7 @@ registerDefaultsCommands(program);
 registerModelsCommand(program);
 registerPruneCommand(program);
 registerTrashCommands(program);
+registerRestoreCommand(program);
 registerDoctorCommand(program);
 // Deprecated 'exec' alias for 'run'
 program
@@ -651,6 +671,7 @@ program
 });
 registerProfilesCommands(program);
 registerSecretsCommands(program);
+registerWalletCommands(program);
 registerHelperCommand(program);
 registerBetaCommands(program);
 registerSyncCommand(program);