@phnx-labs/agents-cli 1.20.16 → 1.20.18

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 { spawnSync } from 'child_process';
+import { bundleExists, bundleTier, deleteBundle, describeBundle, keychainItemsForBundle, keychainRef, listBundles, migrateLegacyBundles, parseDotenv, readAndResolveBundleEnv, 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 { assertOpAvailable, createPasswordItem, deleteItemByTitle, extractSecrets, itemExistsByTitle, listItems, listVaults, } from '../lib/onepassword.js';
+import { DEFAULT_TTL_MS, agentLoad, agentLock, agentStatus, ensureAgentRunning, 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
@@ -346,6 +382,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 +393,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 +412,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 +449,8 @@ export function registerSecretsCommands(program) {
                 console.log(chalk.gray(safePrint(bundle.description)));
             if (bundle.allow_exec)
                 console.log(chalk.yellow('allow_exec: true'));
+            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 +572,13 @@ 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('--force', 'Overwrite an existing bundle')
         .action(async (name, opts) => {
         try {
             const resolvedName = name ?? (await promptBundleName());
             validateBundleName(resolvedName);
+            const tier = parseTierOpt(opts.tier);
             if (bundleExists(resolvedName) && !opts.force) {
                 console.error(chalk.red(`Bundle '${resolvedName}' already exists. Use --force to overwrite.`));
                 process.exit(1);
@@ -535,10 +587,11 @@ export function registerSecretsCommands(program) {
                 name: resolvedName,
                 description: opts.description,
                 allow_exec: opts.allowExec,
+                tier,
                 vars: {},
             };
             writeBundle(bundle);
-            console.log(chalk.green(`Bundle '${resolvedName}' created.`));
+            console.log(chalk.green(`Bundle '${resolvedName}' created${tier === 'session' ? ' (tier: session)' : ''}.`));
             console.log(chalk.gray(`Try: agents secrets add ${resolvedName} MY_KEY`));
         }
         catch (err) {
@@ -951,15 +1004,61 @@ 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('--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 { 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 native
+                // backend (Keychain on macOS, libsecret / encrypted-file on Linux). Create
+                // the bundle if missing, then import the piped .env. `bash -lc` so the login
+                // PATH resolves `agents`; the .env flows over ssh stdin and is never parsed
+                // by a remote shell.
+                const force = opts.force ? ' --force' : '';
+                const remoteAgents = `agents secrets create ${shellQuote(resolvedBundleName)} >/dev/null 2>&1 || true; ` +
+                    `agents secrets import ${shellQuote(resolvedBundleName)} --from /dev/stdin${force}`;
+                const remoteCmd = `bash -lc ${shellQuote(remoteAgents)}`;
+                let failures = 0;
+                for (const host of hosts) {
+                    const res = spawnSync('ssh', ['-o', 'BatchMode=yes', host, remoteCmd], {
+                        input: dotenv,
+                        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 +1217,156 @@ 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();
+    });
     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);
+}
+/** 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/commands/sync.d.ts

@@ -2,11 +2,18 @@
  * `agents sync` — synchronize central resources into an installed agent version.
  *
  * Forms:
- *   agents sync claude                                  # uses default/sole installed version
- *   agents sync claude@2.1.142                          # explicit version
- *   agents sync claude@latest                           # newest installed
+ *   agents sync                                         # umbrella: fetch remote (repos+secrets+sessions) -> reconcile all
+ *   agents sync --repos|--secrets|--sessions            # umbrella: fetch only those, then reconcile
+ *   agents sync --cloud                                 # umbrella: fetch all, skip reconcile
+ *   agents sync --local                                 # umbrella: reconcile all, no fetch
+ *   agents sync claude                                  # one agent: uses default/sole installed version
+ *   agents sync claude@2.1.142                          # one agent: explicit version
+ *   agents sync claude@latest                           # one agent: newest installed
  *   agents sync --agent claude --agent-version 2.1.142  # legacy form, still supported
  *
+ * The umbrella stages live in lib/sync-umbrella.ts; this file dispatches to them
+ * when no agent is given.
+ *
  * In a TTY the command previews available/new resources and lets the user
  * select what to sync (same prompts shown after `agents add`). Pass
  * --yes for non-interactive auto-sync, --force to re-sync when nothing

package/dist/commands/sync.js

@@ -2,11 +2,18 @@
  * `agents sync` — synchronize central resources into an installed agent version.
  *
  * Forms:
- *   agents sync claude                                  # uses default/sole installed version
- *   agents sync claude@2.1.142                          # explicit version
- *   agents sync claude@latest                           # newest installed
+ *   agents sync                                         # umbrella: fetch remote (repos+secrets+sessions) -> reconcile all
+ *   agents sync --repos|--secrets|--sessions            # umbrella: fetch only those, then reconcile
+ *   agents sync --cloud                                 # umbrella: fetch all, skip reconcile
+ *   agents sync --local                                 # umbrella: reconcile all, no fetch
+ *   agents sync claude                                  # one agent: uses default/sole installed version
+ *   agents sync claude@2.1.142                          # one agent: explicit version
+ *   agents sync claude@latest                           # one agent: newest installed
  *   agents sync --agent claude --agent-version 2.1.142  # legacy form, still supported
  *
+ * The umbrella stages live in lib/sync-umbrella.ts; this file dispatches to them
+ * when no agent is given.
+ *
  * In a TTY the command previews available/new resources and lets the user
  * select what to sync (same prompts shown after `agents add`). Pass
  * --yes for non-interactive auto-sync, --force to re-sync when nothing
@@ -25,12 +32,13 @@ import { isVersionInstalled, syncResourcesToVersion, parseAgentSpec, resolveVers
 import { compileRulesForProject } from '../lib/rules/compile.js';
 import { runLaunchSync } from '../lib/project-launch.js';
 import { isInteractiveTerminal, isPromptCancelled } from './utils.js';
+import { runUmbrellaSync } from '../lib/sync-umbrella.js';
 /** Register the `agents sync` command. */
 export function registerSyncCommand(program) {
     program
         .command('sync [agentSpec]')
-        .summary('Sync resources into an installed agent version')
-        .description('Sync resources (commands, skills, hooks, rules, MCPs, plugins, etc.) into an installed agent version. Previews what will change and lets you pick.\n\n[agentSpec] is the agent name with an optional @version, e.g. "claude" or "claude@2.1.142". Omit the version to sync into the active (or sole installed) one.')
+        .summary('Make this machine current, or sync resources into one agent')
+        .description('With an [agentSpec], syncs resources (commands, skills, hooks, rules, MCPs, plugins, etc.) into that installed agent version — previews changes and lets you pick. e.g. "claude" or "claude@2.1.142".\n\nWith NO agent, runs the umbrella verb: fetch remote state (config repos + secrets + sessions) then reconcile it into every installed agent. Scope it with --repos / --secrets / --sessions, --cloud (fetch only), or --local (reconcile only).')
         .option('--agent <agent>', 'Agent identifier (legacy form; prefer the positional spec)')
         .option('--agent-version <version>', 'Version to sync into (legacy form; prefer "agent@version")')
         .option('--project-dir <path>', 'Path to project-level .agents/ directory containing project-scoped resources')
@@ -39,10 +47,66 @@ export function registerSyncCommand(program) {
         .option('-y, --yes', 'Skip the interactive preview and auto-sync all detected resources', false)
         .option('--force', 'Re-sync even if no changes are detected since the last sync', false)
         .option('--quiet', 'Suppress all output (exit code indicates success)', false)
+        // Umbrella verb (no agent given): make this machine current.
+        .option('--repos', 'Umbrella: git-pull ~/.agents + enabled ~/.agents-* extras', false)
+        .option('--secrets', 'Umbrella: pull encrypted secret bundles from the remote', false)
+        .option('--sessions', 'Umbrella: sync session transcripts across machines', false)
+        .option('--cloud', 'Umbrella: fetch all remote state but skip the local reconcile', false)
+        .option('--local', "Umbrella: reconcile resources into installed agents only (no fetch)", false)
         .action(async (agentSpec, opts) => {
         await runSync(agentSpec, opts);
     });
 }
+/**
+ * The umbrella verb: bare `agents sync` (no agent) makes this machine current.
+ * Resolves the flags + a secrets passphrase (env-only for now; tokenized auth
+ * arrives with `agents login`) and runs the fetch+reconcile stages, then prints
+ * a one-line summary. Stage failures are non-fatal and surfaced as warnings.
+ */
+async function runUmbrella(opts, quiet, outLog, errLog) {
+    const flags = {
+        repos: opts.repos,
+        secrets: opts.secrets,
+        sessions: opts.sessions,
+        cloud: opts.cloud,
+        local: opts.local,
+    };
+    const passphrase = process.env.AGENTS_SECRETS_PASSPHRASE || undefined;
+    if (!quiet)
+        outLog(chalk.bold('Syncing this machine…'));
+    try {
+        const result = await runUmbrellaSync({
+            flags,
+            yes: !!opts.yes,
+            passphrase,
+            log: (msg) => { if (!quiet)
+                outLog(chalk.gray(`  ${msg}`)); },
+        });
+        if (!quiet) {
+            const parts = [];
+            if (result.repos) {
+                parts.push(`repos ${result.repos.pulled} pulled` +
+                    (result.repos.errors.length ? `, ${result.repos.errors.length} failed` : ''));
+            }
+            if (result.secrets) {
+                parts.push(result.secrets.skipped ? 'secrets skipped' : `secrets ${result.secrets.pulled} pulled`);
+            }
+            if (result.sessions) {
+                parts.push(result.sessions.ran ? `sessions ${result.sessions.merged} merged` : 'sessions off');
+            }
+            if (result.reconciled)
+                parts.push('reconciled');
+            outLog(chalk.green(`✓ sync: ${parts.join(' · ') || 'nothing to do'}`));
+            const errs = [...(result.repos?.errors ?? []), ...(result.secrets?.errors ?? [])];
+            for (const e of errs)
+                errLog(chalk.yellow(`  ! ${e}`));
+        }
+    }
+    catch (err) {
+        errLog(chalk.red(`sync failed: ${err.message}`));
+        process.exitCode = 1;
+    }
+}
 async function runSync(agentSpec, opts) {
     const quiet = !!opts.quiet;
     const errLog = (msg) => { if (!quiet)
@@ -77,10 +141,9 @@ async function runSync(agentSpec, opts) {
         version = opts.agentVersion;
     }
     if (!agentId) {
-        errLog(chalk.red('Usage: agents sync <agent>[@version]'));
-        errLog(chalk.gray('       agents sync claude'));
-        errLog(chalk.gray('       agents sync claude@2.1.142'));
-        process.exitCode = 1;
+        // No agent specified → the umbrella verb: make this machine current
+        // (fetch repos + secrets + sessions, then reconcile all installed agents).
+        await runUmbrella(opts, quiet, outLog, errLog);
         return;
     }
     // ---------- 2. Resolve version (project pin → global default → sole installed) ----------

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;

package/dist/lib/budget/config.js

@@ -0,0 +1,115 @@
+/**
+ * Budget config resolution (issue #346).
+ *
+ * The `budget:` block can live in the user/global agents.yaml (`readMeta().budget`)
+ * and in any project-local agents.yaml walked from cwd upward. Precedence is
+ * project > user, matching `run:` resolution (lib/run-config.ts). Caps merge
+ * field-by-field — a project that sets only `per_run` inherits the user's
+ * `per_day`/`per_project`/`per_agent` rather than wiping them.
+ *
+ * This is the single resolver the pre-flight gate, the live watcher, and the
+ * `agents budget` command all route through, so the effective cap set is
+ * computed in exactly one place.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import * as yaml from 'yaml';
+import { getUserAgentsDir, readMeta } from '../state.js';
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * Coerce a raw parsed `budget:` block into a typed BudgetConfig, dropping any
+ * field whose value is the wrong shape. Malformed entries are ignored, not
+ * thrown — a typo in one cap must never crash a run (no-fallbacks applies to
+ * the data path, not to user-typed config we choose to be lenient about).
+ */
+function coerceBudget(raw) {
+    if (!isRecord(raw))
+        return {};
+    const out = {};
+    if (typeof raw.currency === 'string')
+        out.currency = raw.currency;
+    if (typeof raw.per_run === 'number' && raw.per_run >= 0)
+        out.per_run = raw.per_run;
+    if (typeof raw.per_day === 'number' && raw.per_day >= 0)
+        out.per_day = raw.per_day;
+    if (typeof raw.per_project === 'number' && raw.per_project >= 0)
+        out.per_project = raw.per_project;
+    if (raw.on_exceed === 'block' || raw.on_exceed === 'warn')
+        out.on_exceed = raw.on_exceed;
+    if (typeof raw.require_confirm_over === 'number' && raw.require_confirm_over >= 0) {
+        out.require_confirm_over = raw.require_confirm_over;
+    }
+    if (isRecord(raw.per_agent)) {
+        const perAgent = {};
+        for (const [k, v] of Object.entries(raw.per_agent)) {
+            if (typeof v === 'number' && v >= 0)
+                perAgent[k] = v;
+        }
+        if (Object.keys(perAgent).length > 0)
+            out.per_agent = perAgent;
+    }
+    return out;
+}
+/** Merge a higher-precedence budget over a base. Set fields win; per_agent merges key-by-key. */
+function mergeBudget(base, over) {
+    const merged = { ...base, ...stripUndefined(over) };
+    if (base.per_agent || over.per_agent) {
+        merged.per_agent = { ...(base.per_agent ?? {}), ...(over.per_agent ?? {}) };
+    }
+    return merged;
+}
+function stripUndefined(cfg) {
+    const out = {};
+    for (const [k, v] of Object.entries(cfg)) {
+        if (v !== undefined)
+            out[k] = v;
+    }
+    return out;
+}
+/** Read project-local `budget:` blocks from nearest dir upward, nearest LAST (highest precedence). */
+function getProjectBudgets(startPath) {
+    const configs = [];
+    let dir = path.resolve(startPath);
+    const userAgentsYaml = path.join(getUserAgentsDir(), 'agents.yaml');
+    while (dir !== path.dirname(dir)) {
+        const manifestPath = path.join(dir, 'agents.yaml');
+        if (manifestPath !== userAgentsYaml && fs.existsSync(manifestPath)) {
+            try {
+                const parsed = yaml.parse(fs.readFileSync(manifestPath, 'utf-8'));
+                if (isRecord(parsed) && parsed.budget !== undefined) {
+                    configs.push(coerceBudget(parsed.budget));
+                }
+            }
+            catch {
+                // Malformed project config — ignore and keep walking.
+            }
+        }
+        dir = path.dirname(dir);
+    }
+    // configs[0] is the nearest dir. Reverse so the nearest applies LAST (wins).
+    return configs.reverse();
+}
+/**
+ * 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 function resolveBudgetConfig(cwd = process.cwd()) {
+    const userBudget = coerceBudget(readMeta().budget);
+    let merged = userBudget;
+    for (const projectBudget of getProjectBudgets(cwd)) {
+        merged = mergeBudget(merged, projectBudget);
+    }
+    if (merged.on_exceed === undefined)
+        merged.on_exceed = 'block';
+    return merged;
+}
+/** True when at least one enforceable cap is set. No caps => budget feature is dormant. */
+export function hasAnyCap(cfg) {
+    return (cfg.per_run !== undefined ||
+        cfg.per_day !== undefined ||
+        cfg.per_project !== undefined ||
+        (cfg.per_agent !== undefined && Object.keys(cfg.per_agent).length > 0));
+}