@phnx-labs/agents-cli 1.20.17 → 1.20.19

package/dist/commands/secrets.js

@@ -7,9 +7,12 @@
  */
 import chalk from 'chalk';
 import * as fs from 'fs';
-import { bundleExists, deleteBundle, describeBundle, keychainItemsForBundle, keychainRef, listBundles, migrateLegacyBundles, parseDotenv, readBundle, renameBundle, rotateBundleSecret, validateBundleName, validateEnvKey, validateExpiresFutureDated, validateSecretType, writeBundle, } from '../lib/secrets/bundles.js';
-import { deleteKeychainToken, getKeychainToken, getKeychainTokens, hasKeychainToken, secretsKeychainItem, setKeychainToken, } from '../lib/secrets/index.js';
+import { spawnSync } from 'child_process';
+import { bundleExists, bundleItemStore, bundleTier, deleteBundle, describeBundle, keychainItemsForBundle, keychainRef, listBundles, migrateLegacyBundles, parseDotenv, readAndResolveBundleEnv, readBundle, renameBundle, rotateBundleSecret, validateBundleName, validateEnvKey, validateExpiresFutureDated, validateSecretType, writeBundle, } from '../lib/secrets/bundles.js';
+import { getKeychainToken, getKeychainTokens, hasKeychainToken, secretsKeychainItem, setKeychainToken, } from '../lib/secrets/index.js';
 import { assertOpAvailable, createPasswordItem, deleteItemByTitle, extractSecrets, itemExistsByTitle, listItems, listVaults, } from '../lib/onepassword.js';
+import { DEFAULT_TTL_MS, agentLoad, agentLock, agentStatus, ensureAgentRunning, runAgentLoadFromStdin, runSecretsAgent, } from '../lib/secrets/agent.js';
+import { parseDuration } from '../lib/hooks/cache.js';
 import { registerCommandGroups, setHelpSections } from '../lib/help.js';
 import { isInteractiveTerminal, isPromptCancelled } from './utils.js';
 import { registerSecretsSyncCommands } from './secrets-sync.js';
@@ -130,6 +133,39 @@ function readStdinSync() {
     }
     return Buffer.concat(chunks).toString('utf-8').trim();
 }
+/**
+ * SSH target for `export --to-ssh`: a bare ssh-config host alias (e.g. `yosemite-s0`)
+ * or `user@host`. The strict allowlist blocks shell metacharacters and a leading `-`
+ * so a target can't be smuggled in as an ssh argv flag.
+ */
+export const SSH_TARGET_RE = /^[a-zA-Z0-9._-]+(@[a-zA-Z0-9._-]+)?$/;
+export function assertValidSshTarget(host) {
+    if (!SSH_TARGET_RE.test(host)) {
+        throw new Error(`Invalid SSH target ${JSON.stringify(host)}. Expected a host alias or user@host (letters, digits, '.', '_', '-').`);
+    }
+}
+/** POSIX single-quote a string for safe interpolation into a remote shell command. */
+function shellQuote(s) {
+    return `'${s.replace(/'/g, `'\\''`)}'`;
+}
+/**
+ * Serialize a resolved env map to `.env` lines that round-trip losslessly through
+ * `parseDotenv` on the remote: `KEY="VALUE"`. parseDotenv strips exactly one outer
+ * quote pair and takes the inner bytes verbatim (no unescaping), so any single-line
+ * value survives unchanged with no escaping. Newlines would break its line-based
+ * parse, so multi-line values are rejected rather than silently corrupted.
+ */
+export function bundleEnvToDotenv(env) {
+    const lines = [];
+    for (const [k, v] of Object.entries(env)) {
+        if (/[\r\n]/.test(v)) {
+            throw new Error(`Key '${k}' has a multi-line value; the SSH .env transport can't carry newlines. ` +
+                `Set it directly on the remote with 'agents secrets add ${k} --value-stdin'.`);
+        }
+        lines.push(`${k}="${v}"`);
+    }
+    return lines.join('\n') + '\n';
+}
 /** Strip ANSI escape sequences so padding can be computed on visible width. */
 function visibleWidth(s) {
     // eslint-disable-next-line no-control-regex
@@ -199,7 +235,11 @@ function renderBundleRow(b) {
         `${padVisible(created, 9)} ` +
         `${padVisible(updated, 9)} ` +
         `${padVisible(used, 7)}`;
-    return b.description ? `${head} ${chalk.gray(safePrint(b.description))}` : head.trimEnd();
+    // Mark file-backed bundles so `list` distinguishes them from keychain ones.
+    const tag = b.backend === 'file' ? chalk.magenta('[file] ') : '';
+    const desc = b.description ? chalk.gray(safePrint(b.description)) : '';
+    const trailer = `${tag}${desc}`.trimEnd();
+    return trailer ? `${head} ${trailer}` : head.trimEnd();
 }
 /** Colorize a variable source kind (literal, keychain, env, file, exec). */
 function kindLabel(kind) {
@@ -346,6 +386,9 @@ export function registerSecretsCommands(program) {
       # Eval the bundle into your current shell
       eval "$(agents secrets export prod --plaintext)"
 
+      # Push the bundle to remote machine(s) over SSH (lands as a native bundle there)
+      agents secrets export prod --to-ssh --host yosemite-s0 --host yosemite-s1 --force
+
       # Run a one-off command with secrets injected
       agents secrets exec prod -- ./deploy.sh
     `,
@@ -354,7 +397,15 @@ export function registerSecretsCommands(program) {
       never touch disk in plaintext. Every item is device-local and gated by Touch ID
       or device passcode; cross-machine sync is handled by 'agents secrets push/pull'.
 
+      Touch ID noise: macOS pops a prompt per bundle per process, so concurrent
+      agents each re-prompt. 'agents secrets unlock <bundle>' holds the resolved
+      bundle in a local agent after one prompt; later runs read it silently until
+      it expires (default 24h), you 'lock' it, or the screen locks. Nothing on disk.
+
       See also:
+        agents secrets unlock <bundle>                 hold a bundle after one Touch ID
+        agents secrets lock                            wipe held bundles (re-prompt next read)
+        agents secrets status                          show held bundles + when they lock
         agents secrets rotate <bundle> <key>           rotate value, preserve metadata
         agents secrets import <bundle> --from .env     bulk import from .env
         agents secrets import <bundle> --from-1password --vault <name>
@@ -365,6 +416,7 @@ export function registerSecretsCommands(program) {
     registerCommandGroups(cmd, [
         { title: 'Bundle commands', names: ['list', 'view', 'create', 'rename', 'describe', 'delete'] },
         { title: 'Secret commands', names: ['add', 'rotate', 'remove', 'import', 'export'] },
+        { title: 'Agent commands', names: ['unlock', 'lock', 'status', 'tier'] },
         { title: 'Raw item commands', names: ['get', 'set'] },
         { title: 'Sync commands', names: ['push', 'pull', 'remote-list'] },
         { title: 'Utilities', names: ['exec', 'generate', 'migrate-acl'] },
@@ -401,6 +453,10 @@ export function registerSecretsCommands(program) {
                 console.log(chalk.gray(safePrint(bundle.description)));
             if (bundle.allow_exec)
                 console.log(chalk.yellow('allow_exec: true'));
+            if (bundle.backend === 'file')
+                console.log(chalk.gray('backend: file (passphrase-encrypted; reads need AGENTS_SECRETS_PASSPHRASE, no Touch ID)'));
+            if (bundleTier(bundle) === 'session')
+                console.log(chalk.gray('tier: session (secrets-agent eligible)'));
             if (bundle.created_at)
                 console.log(chalk.gray(`created_at: ${bundle.created_at} (${humanAge(bundle.created_at)})`));
             if (bundle.updated_at)
@@ -522,11 +578,15 @@ export function registerSecretsCommands(program) {
         .description('Create an empty bundle')
         .option('--description <text>', 'Free-form description')
         .option('--allow-exec', 'Allow exec: refs in this bundle (off by default)')
+        .option('--tier <tier>', 'secrets-agent tier: biometry (default) or session', 'biometry')
+        .option('--backend <backend>', 'storage backend: keychain (default) or file (passphrase-encrypted, headless-readable)', 'keychain')
         .option('--force', 'Overwrite an existing bundle')
         .action(async (name, opts) => {
         try {
             const resolvedName = name ?? (await promptBundleName());
             validateBundleName(resolvedName);
+            const tier = parseTierOpt(opts.tier);
+            const backend = parseBackendOpt(opts.backend);
             if (bundleExists(resolvedName) && !opts.force) {
                 console.error(chalk.red(`Bundle '${resolvedName}' already exists. Use --force to overwrite.`));
                 process.exit(1);
@@ -535,10 +595,16 @@ export function registerSecretsCommands(program) {
                 name: resolvedName,
                 description: opts.description,
                 allow_exec: opts.allowExec,
+                backend: backend === 'file' ? 'file' : undefined,
+                tier,
                 vars: {},
             };
             writeBundle(bundle);
-            console.log(chalk.green(`Bundle '${resolvedName}' created.`));
+            const tags = [tier === 'session' ? 'tier: session' : null, backend === 'file' ? 'backend: file' : null].filter(Boolean);
+            console.log(chalk.green(`Bundle '${resolvedName}' created${tags.length ? ` (${tags.join(', ')})` : ''}.`));
+            if (backend === 'file') {
+                console.log(chalk.gray('File-backed: items are AES-256-GCM encrypted under AGENTS_SECRETS_PASSPHRASE (no Touch ID).'));
+            }
             console.log(chalk.gray(`Try: agents secrets add ${resolvedName} MY_KEY`));
         }
         catch (err) {
@@ -658,7 +724,7 @@ export function registerSecretsCommands(program) {
                 console.log(chalk.green(`${resolvedBundleName}.${resolvedKey} = <literal>`));
                 return;
             }
-            // Default path: keychain-backed.
+            // Default path: stored in the bundle's backend (keychain or file).
             let secretValue;
             if (opts.valueStdin) {
                 secretValue = readStdinSync();
@@ -669,11 +735,12 @@ export function registerSecretsCommands(program) {
                 secretValue = await promptForSecret(`Enter value for ${resolvedBundleName}.${resolvedKey}`);
             }
             const item = secretsKeychainItem(resolvedBundleName, resolvedKey);
-            setKeychainToken(item, secretValue);
+            bundleItemStore(bundle.backend).set(item, secretValue);
             bundle.vars[resolvedKey] = keychainRef(resolvedKey);
             applyMeta();
             writeBundle(bundle);
-            console.log(chalk.green(`${resolvedBundleName}.${resolvedKey} stored in keychain (${item}).`));
+            const where = bundle.backend === 'file' ? 'encrypted file store' : 'keychain';
+            console.log(chalk.green(`${resolvedBundleName}.${resolvedKey} stored in ${where} (${item}).`));
         }
         catch (err) {
             if (isPromptCancelled(err))
@@ -778,9 +845,10 @@ Examples:
             writeBundle(bundle);
             if (willPurge) {
                 const item = secretsKeychainItem(resolvedBundleName, raw.slice('keychain:'.length));
-                const removed = deleteKeychainToken(item);
+                const removed = bundleItemStore(bundle.backend).delete(item);
                 if (removed) {
-                    console.log(chalk.green(`Removed ${resolvedBundleName}.${resolvedKey} and purged keychain item.`));
+                    const where = bundle.backend === 'file' ? 'encrypted file item' : 'keychain item';
+                    console.log(chalk.green(`Removed ${resolvedBundleName}.${resolvedKey} and purged ${where}.`));
                     return;
                 }
             }
@@ -822,8 +890,9 @@ Examples:
                 }
             }
             if (!opts.keepSecrets) {
+                const store = bundleItemStore(bundle.backend);
                 for (const { item } of keychainItemsForBundle(bundle)) {
-                    deleteKeychainToken(item);
+                    store.delete(item);
                 }
             }
             const existed = deleteBundle(resolvedName);
@@ -876,11 +945,12 @@ Examples:
     });
     cmd
         .command('import [bundle]')
-        .description('Import keys from a .env file or a 1Password vault into a bundle. By default every key is stored in keychain.')
+        .description('Import keys from a .env file or a 1Password vault into a bundle. The bundle is created if it does not exist. Values are stored in the bundle\'s backend (keychain by default).')
         .option('--from <path>', 'Path to a .env file')
         .option('--from-1password', 'Import secrets from a 1Password vault (requires the op CLI)')
         .option('--vault <name>', '1Password vault name (used with --from-1password)')
         .option('--all-plaintext', 'Store every imported value as a literal in the bundle metadata (skip keychain item creation)')
+        .option('--backend <backend>', 'When creating the bundle: keychain (default) or file (passphrase-encrypted, headless-readable)', 'keychain')
         .option('--force', 'Overwrite an existing key in the bundle')
         .action(async (bundleName, opts) => {
         try {
@@ -891,7 +961,27 @@ Examples:
                 throw new Error('--from and --from-1password are mutually exclusive.');
             }
             const resolvedBundleName = bundleName ?? (await pickBundleName('import into'));
-            const bundle = readBundle(resolvedBundleName);
+            const requestedBackend = parseBackendOpt(opts.backend);
+            // Read the bundle if it exists (inheriting its backend); otherwise
+            // create it with the requested backend so a single `import --backend
+            // file` works (this is what `export --to-ssh --remote-backend file`
+            // drives on the remote).
+            let bundle;
+            if (bundleExists(resolvedBundleName)) {
+                bundle = readBundle(resolvedBundleName);
+                if (requestedBackend === 'file' && bundle.backend !== 'file') {
+                    throw new Error(`Bundle '${resolvedBundleName}' already exists with a keychain backend; ` +
+                        `--backend file cannot change it. Delete it first to recreate as file-backed.`);
+                }
+            }
+            else {
+                bundle = {
+                    name: resolvedBundleName,
+                    backend: requestedBackend === 'file' ? 'file' : undefined,
+                    vars: {},
+                };
+            }
+            const store = bundleItemStore(bundle.backend);
             let added = 0;
             let skipped = 0;
             if (opts.from1password) {
@@ -909,7 +999,7 @@ Examples:
                     }
                     else {
                         const item = secretsKeychainItem(resolvedBundleName, envKey);
-                        setKeychainToken(item, value);
+                        store.set(item, value);
                         bundle.vars[envKey] = keychainRef(envKey);
                     }
                     added++;
@@ -933,7 +1023,7 @@ Examples:
                     }
                     else {
                         const item = secretsKeychainItem(resolvedBundleName, key);
-                        setKeychainToken(item, value);
+                        store.set(item, value);
                         bundle.vars[key] = keychainRef(key);
                     }
                     added++;
@@ -951,15 +1041,91 @@ Examples:
     });
     cmd
         .command('export [bundle]')
-        .description('Resolve a bundle and print KEY=VALUE lines, or push it to a 1Password vault with --to-1password.')
+        .description('Resolve a bundle and print KEY=VALUE lines, push it to a 1Password vault with --to-1password, or push it to remote machine(s) over SSH with --to-ssh.')
         .option('--plaintext', 'Acknowledge that the resolved values will be printed in the clear (shell export mode)')
         .option('--to-1password', 'Push every key in the bundle as a PASSWORD item in a 1Password vault')
         .option('--vault <name>', '1Password vault name (used with --to-1password)')
-        .option('--force', 'Overwrite existing 1Password items (used with --to-1password)')
+        .option('--to-ssh', 'Push the bundle to remote machine(s) over SSH via their native agents-cli import')
+        .option('--host <target...>', 'SSH target(s) for --to-ssh: host alias or user@host (repeatable)')
+        .option('--remote-backend <backend>', 'Backend for the bundle on the remote: keychain (default) or file (passphrase-encrypted, headless-readable). file forwards AGENTS_SECRETS_PASSPHRASE over stdin.', 'keychain')
+        .option('--force', 'Overwrite existing keys/items on the target (used with --to-1password and --to-ssh)')
         .action(async (bundleName, opts) => {
         try {
             const { readAndResolveBundleEnv, bundleToEnvPrefix, isReservedEnvName } = await import('../lib/secrets/bundles.js');
             const resolvedBundleName = bundleName ?? (await pickBundleName('export'));
+            if (opts.toSsh) {
+                const hosts = opts.host ?? [];
+                if (hosts.length === 0) {
+                    throw new Error('--to-ssh requires at least one --host <target>.');
+                }
+                for (const h of hosts)
+                    assertValidSshTarget(h);
+                const remoteBackend = parseBackendOpt(opts.remoteBackend);
+                // For a file-backed remote bundle the remote must encrypt at rest with
+                // a passphrase. We forward the LOCAL AGENTS_SECRETS_PASSPHRASE — the
+                // operator unlocks it once on this (trusted, biometry-gated) machine —
+                // and ship it as the FIRST stdin line so it never lands in argv / `ps`
+                // / the remote shell history. The remote `read -r` consumes that line;
+                // `agents secrets import --from /dev/stdin` reads the .env remainder.
+                let remotePassphrase = '';
+                if (remoteBackend === 'file') {
+                    remotePassphrase = process.env.AGENTS_SECRETS_PASSPHRASE ?? '';
+                    if (!remotePassphrase) {
+                        throw new Error('--remote-backend file needs AGENTS_SECRETS_PASSPHRASE set locally to encrypt the ' +
+                            'bundle at rest on the remote. Set it for this command, then unlock it the same way per run.');
+                    }
+                }
+                const { env } = readAndResolveBundleEnv(resolvedBundleName, { caller: `ssh export` });
+                const dotenv = bundleEnvToDotenv(env);
+                const keyCount = Object.keys(env).length;
+                // Drive the remote's own `agents secrets` CLI so values land in its
+                // chosen backend. `bash -lc` so the login PATH resolves `agents`; the
+                // .env (and, for file, the passphrase) flow over ssh stdin and are
+                // never parsed by a remote shell.
+                const force = opts.force ? ' --force' : '';
+                const backendFlag = remoteBackend === 'file' ? ' --backend file' : '';
+                let remoteAgents;
+                let input;
+                if (remoteBackend === 'file') {
+                    // import --backend file auto-creates the file-backed bundle; no
+                    // separate `create` needed.
+                    remoteAgents =
+                        `IFS= read -r AGENTS_SECRETS_PASSPHRASE; export AGENTS_SECRETS_PASSPHRASE; ` +
+                            `agents secrets import ${shellQuote(resolvedBundleName)} --from /dev/stdin${backendFlag}${force}`;
+                    input = `${remotePassphrase}\n${dotenv}`;
+                }
+                else {
+                    remoteAgents =
+                        `agents secrets create ${shellQuote(resolvedBundleName)} >/dev/null 2>&1 || true; ` +
+                            `agents secrets import ${shellQuote(resolvedBundleName)} --from /dev/stdin${force}`;
+                    input = dotenv;
+                }
+                const remoteCmd = `bash -lc ${shellQuote(remoteAgents)}`;
+                let failures = 0;
+                for (const host of hosts) {
+                    const res = spawnSync('ssh', ['-o', 'BatchMode=yes', host, remoteCmd], {
+                        input,
+                        stdio: ['pipe', 'pipe', 'pipe'],
+                        encoding: 'utf-8',
+                    });
+                    if (res.error) {
+                        failures++;
+                        console.error(chalk.red(`${host}: ${res.error.message}`));
+                        continue;
+                    }
+                    if (res.status !== 0) {
+                        failures++;
+                        const msg = (res.stderr || res.stdout || '').trim();
+                        console.error(chalk.red(`${host}: remote import failed (exit ${res.status ?? 'signal'})${msg ? `: ${msg}` : ''}`));
+                        continue;
+                    }
+                    const remoteMsg = (res.stdout || '').trim().split('\n').map((l) => l.trim()).filter(Boolean).pop();
+                    console.log(chalk.green(`${host} -> '${resolvedBundleName}': ${remoteMsg || `${keyCount} key(s) exported`}`));
+                }
+                if (failures > 0)
+                    process.exit(1);
+                return;
+            }
             if (opts.to1password) {
                 assertOpAvailable();
                 const vault = await resolveVault(opts.vault);
@@ -1118,9 +1284,170 @@ Examples:
             console.log(password);
         }
     });
+    cmd
+        .command('unlock [names...]')
+        .description('Hold a bundle in the secrets-agent after one Touch ID, so concurrent runs read it without re-prompting (macOS).')
+        .option('--ttl <duration>', 'How long to hold it (e.g. 30m, 8h). Default 24h.')
+        .option('--all', 'Unlock every configured bundle')
+        .action(async (names, opts) => {
+        if (process.platform !== 'darwin') {
+            console.error(chalk.red('secrets-agent is macOS-only (no biometry prompt to deduplicate elsewhere).'));
+            process.exit(1);
+        }
+        let targets = opts.all ? listBundles().map((b) => b.name) : names;
+        if (!targets || targets.length === 0) {
+            console.error(chalk.red('Specify one or more bundle names, or --all.'));
+            process.exit(1);
+        }
+        let ttlMs = DEFAULT_TTL_MS;
+        if (opts.ttl) {
+            const secs = parseDuration(opts.ttl);
+            if (!secs) {
+                console.error(chalk.red(`Invalid --ttl '${opts.ttl}'. Use e.g. 30m, 2h, 8h.`));
+                process.exit(1);
+            }
+            ttlMs = secs * 1000;
+        }
+        if (!(await ensureAgentRunning())) {
+            console.error(chalk.red('Could not start the secrets-agent.'));
+            process.exit(1);
+        }
+        let loaded = 0;
+        for (const name of targets) {
+            try {
+                // noAgent: read the real keychain (one Touch ID) rather than the
+                // agent we're about to populate.
+                const { bundle, env } = readAndResolveBundleEnv(name, { noAgent: true, caller: 'unlock' });
+                if (await agentLoad(name, bundle, env, ttlMs)) {
+                    loaded++;
+                    console.log(`${chalk.green('unlocked')} ${chalk.cyan(name)} ${chalk.gray(`(${Object.keys(env).length} keys, ${humanRemaining(Date.now() + ttlMs)})`)}`);
+                }
+                else {
+                    console.error(chalk.red(`Failed to load '${name}' into the agent.`));
+                }
+            }
+            catch (err) {
+                if (isPromptCancelled(err)) {
+                    console.error(chalk.yellow(`Cancelled unlocking '${name}'.`));
+                    continue;
+                }
+                console.error(chalk.red(`${name}: ${err.message}`));
+            }
+        }
+        if (loaded === 0)
+            process.exit(1);
+    });
+    cmd
+        .command('lock [names...]')
+        .description('Wipe bundles from the secrets-agent (forces Touch ID again next read). Default: all.')
+        .option('--all', 'Wipe every unlocked bundle (same as no names)')
+        .action(async (names, opts) => {
+        if (process.platform !== 'darwin')
+            return; // nothing to lock off darwin
+        if (names && names.length > 0 && !opts.all) {
+            let total = 0;
+            for (const name of names)
+                total += await agentLock(name);
+            console.log(total > 0 ? chalk.green(`Locked ${total} bundle(s).`) : chalk.gray('Nothing to lock.'));
+        }
+        else {
+            const wiped = await agentLock();
+            console.log(wiped > 0 ? chalk.green(`Locked ${wiped} bundle(s).`) : chalk.gray('Nothing to lock.'));
+        }
+    });
+    cmd
+        .command('status')
+        .description('Show which bundles the secrets-agent currently holds and when they lock.')
+        .action(async () => {
+        if (process.platform !== 'darwin') {
+            console.log(chalk.gray('secrets-agent is macOS-only.'));
+            return;
+        }
+        const entries = await agentStatus();
+        if (entries.length === 0) {
+            console.log(chalk.gray('No bundles unlocked. The secrets-agent is idle or not running.'));
+            console.log(chalk.gray('Try: agents secrets unlock <bundle>'));
+            return;
+        }
+        console.log(chalk.bold(`${'BUNDLE'.padEnd(24)} ${'KEYS'.padEnd(5)} LOCKS IN`));
+        for (const e of entries) {
+            console.log(`${chalk.cyan(e.name.padEnd(24))} ${String(e.keyCount).padEnd(5)} ${humanRemaining(e.expiresAt)}`);
+        }
+    });
+    cmd
+        .command('tier <bundle> [tier]')
+        .description("Show or set a bundle's secrets-agent tier: biometry (default) or session.")
+        .action((bundleName, tier) => {
+        try {
+            const bundle = readBundle(bundleName);
+            if (tier === undefined) {
+                console.log(`${chalk.cyan(bundle.name)} tier: ${chalk.bold(bundleTier(bundle))}`);
+                return;
+            }
+            const next = parseTierOpt(tier);
+            bundle.tier = next;
+            writeBundle(bundle);
+            console.log(chalk.green(`${bundle.name} tier set to ${next}.`));
+            if (next === 'session') {
+                console.log(chalk.gray('Eligible for the secrets-agent: unlock it, or enable auto-cache with `secrets.agent.auto: true` in agents.yaml.'));
+            }
+        }
+        catch (err) {
+            console.error(chalk.red(err.message));
+            process.exit(1);
+        }
+    });
+    cmd
+        .command('_agent-run', { hidden: true })
+        .description('Run the secrets-agent broker in the foreground (internal)')
+        .action(async () => {
+        await runSecretsAgent();
+    });
+    cmd
+        .command('_agent-load', { hidden: true })
+        .description('Detached auto-cache worker: load a bundle from stdin into the broker (internal)')
+        .action(async () => {
+        await runAgentLoadFromStdin();
+    });
     registerSecretsSyncCommands(cmd);
     registerSecretsMigrateAclCommand(cmd);
 }
+/** Validate a --tier value, exiting with a clear message on a bad one. `none`
+ * is rejected explicitly: it would require storing items without the biometry
+ * ACL (a separate signed-helper change), so it isn't offered yet. */
+function parseTierOpt(raw) {
+    const v = (raw ?? 'biometry').toLowerCase();
+    if (v === 'biometry' || v === 'session')
+        return v;
+    if (v === 'none') {
+        console.error(chalk.red("tier 'none' (no biometry ACL) is not available yet — use 'biometry' or 'session'."));
+        process.exit(1);
+    }
+    console.error(chalk.red(`Invalid --tier '${raw}'. Use 'biometry' or 'session'.`));
+    process.exit(1);
+}
+/** Validate a --backend value, exiting with a clear message on a bad one. */
+function parseBackendOpt(raw) {
+    const v = (raw ?? 'keychain').toLowerCase();
+    if (v === 'keychain' || v === 'file')
+        return v;
+    console.error(chalk.red(`Invalid --backend '${raw}'. Use 'keychain' or 'file'.`));
+    process.exit(1);
+}
+/** Human-readable "locks in 3 hours" / "locks in 5 minutes" from an epoch-ms expiry. */
+function humanRemaining(expiresAt) {
+    const ms = expiresAt - Date.now();
+    if (ms <= 0)
+        return 'expired';
+    const mins = Math.round(ms / 60000);
+    if (mins < 60)
+        return `locks in ${mins} minute${mins === 1 ? '' : 's'}`;
+    const hours = Math.round(mins / 60);
+    if (hours < 24)
+        return `locks in ${hours} hour${hours === 1 ? '' : 's'}`;
+    const days = Math.round(hours / 24);
+    return `locks in ${days} day${days === 1 ? '' : 's'}`;
+}
 /**
  * Copy text to the system clipboard, cross-platform.
  * macOS: `pbcopy`. Windows: `clip`. Linux: tries `wl-copy` (Wayland), then

package/dist/commands/sessions.js

@@ -376,6 +376,8 @@ async function sessionsAction(query, options) {
         // Without this, a dev dir with heavy SDK spawn activity (Task subagents,
         // `agents run`, team agents) can fill the top-N window entirely with
         // hidden rows and make real CLI sessions appear to vanish.
+        // 'recent' is the user-facing alias for the default timestamp sort.
+        const sortBy = options.sort === 'cost' ? 'cost' : options.sort === 'duration' ? 'duration' : 'timestamp';
         const scope = {
             agent,
             version,
@@ -385,6 +387,7 @@ async function sessionsAction(query, options) {
             project: options.project,
             since,
             until: options.until,
+            sortBy,
         };
         let sessions = await discoverSessions({
             ...scope,
@@ -1102,6 +1105,7 @@ export function registerSessionsCommands(program) {
         .option('--since <time>', 'Only sessions newer than this (e.g., 2h, 7d, 4w, or ISO date)')
         .option('--until <time>', 'Only sessions older than this (ISO timestamp)')
         .option('-n, --limit <n>', 'Maximum number of sessions to return', '50')
+        .option('--sort <field>', 'Sort the list by: recent (default), cost, or duration')
         .option('--markdown', 'Render the session as markdown (user, assistant, thinking, tool calls)')
         .option('--no-redact', 'Disable default secret redaction in markdown session output')
         .option('--json', 'Output JSON (session list when browsing, event array when rendering one session)')

package/dist/index.js

@@ -97,6 +97,8 @@ import { registerWalletCommands } from './commands/wallet.js';
 import { registerHelperCommand } from './commands/helper.js';
 import { registerFactoryCommands } from './commands/factory.js';
 import { registerUsageCommand } from './commands/usage.js';
+import { registerCostCommand } from './commands/cost.js';
+import { registerBudgetCommand } from './commands/budget.js';
 import { registerAliasCommand } from './commands/alias.js';
 import { registerBetaCommands } from './commands/beta.js';
 import { applyGlobalHelpConventions } from './lib/help.js';
@@ -679,6 +681,8 @@ registerRefreshRulesCommand(program);
 registerDriveCommands(program);
 registerFactoryCommands(program);
 registerUsageCommand(program);
+registerCostCommand(program);
+registerBudgetCommand(program);
 registerAliasCommand(program);
 registerPtyCommands(program);
 registerTmuxCommands(program);

package/dist/lib/budget/config.d.ts

@@ -0,0 +1,9 @@
+import type { BudgetConfig } from '../types.js';
+/**
+ * Effective budget for `cwd`: user/global base, then each project-local block
+ * from farthest ancestor to nearest, nearest winning. `on_exceed` defaults to
+ * `block` when nothing sets it (fail-closed: the safe default is to enforce).
+ */
+export declare function resolveBudgetConfig(cwd?: string): BudgetConfig;
+/** True when at least one enforceable cap is set. No caps => budget feature is dormant. */
+export declare function hasAnyCap(cfg: BudgetConfig): boolean;