@phnx-labs/agents-cli 1.20.17 → 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/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));
+}

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

@@ -0,0 +1,94 @@
+/**
+ * Live spend watcher + cap math (issue #346).
+ *
+ * This is the provider-agnostic shared surface the loop driver (#332) will
+ * reuse for its budget guard. It knows nothing about child processes, agents,
+ * or the ledger — it accepts parsed usage events and a caps object, accumulates
+ * cost via the canonical pricing module, and fires `onBreach` exactly once when
+ * any active cap is crossed.
+ *
+ * The accumulation is the cross-vendor primitive: feed Claude usage and Codex
+ * usage to the same watcher under one `per_project` / `per_run` cap and the
+ * spend aggregates across both — no single-vendor control can do that.
+ */
+import type { AgentId, BudgetConfig } from '../types.js';
+/** A parsed usage event from any agent's stream (fields match session/parse). */
+export interface UsageEvent {
+    agent?: AgentId | string;
+    model?: string;
+    inputTokens?: number;
+    outputTokens?: number;
+    cacheReadTokens?: number;
+    cacheCreationTokens?: number;
+}
+/**
+ * Caps the watcher enforces. `priorDaySpend` / `priorProjectSpend` seed the
+ * accumulators with spend already on the ledger BEFORE this run started, so a
+ * per_day cap counts today's earlier runs too — not just this process. Per-cap
+ * fields are USD; undefined means "not enforced".
+ */
+export interface LiveCaps {
+    perRun?: number;
+    perDay?: number;
+    perProject?: number;
+    /** Per-agent daily caps. Each agent's running spend is checked against its own cap. */
+    perAgent?: Partial<Record<string, number>>;
+    /** Day spend already on the ledger before this run (cross-vendor). */
+    priorDaySpend?: number;
+    /** Project spend already on the ledger before this run (cross-vendor). */
+    priorProjectSpend?: number;
+    /** Per-agent day spend already on the ledger before this run, keyed by agent. */
+    priorAgentDaySpend?: Partial<Record<string, number>>;
+}
+/** Which cap tripped, and the spend figures at the moment of the breach. */
+export interface BreachInfo {
+    cap: 'per_run' | 'per_day' | 'per_project' | 'per_agent';
+    /** The configured limit that was crossed (USD). */
+    limit: number;
+    /** The spend that crossed it (USD). */
+    spend: number;
+    /** Agent attributed to the breach (only meaningful for per_agent). */
+    agent?: string;
+    /** This run's accumulated spend so far (USD). */
+    runSpend: number;
+}
+/** Public watcher surface. `feedUsage` is idempotent after a breach (no double-fire). */
+export interface LiveSpendWatcher {
+    /** Feed one parsed usage event; accrues cost and may fire onBreach. */
+    feedUsage(event: UsageEvent): void;
+    /** Total USD this run has accumulated across all fed events. */
+    runSpend(): number;
+    /** True once a cap has been breached. */
+    breached(): boolean;
+    /** Stop accepting events / release references. Idempotent. */
+    dispose(): void;
+}
+/** Convert a resolved BudgetConfig + prior ledger spend into the caps the watcher needs. */
+export declare function capsFromConfig(cfg: BudgetConfig, prior?: {
+    daySpend?: number;
+    projectSpend?: number;
+    agentDaySpend?: Partial<Record<string, number>>;
+}): LiveCaps;
+/**
+ * Create a live spend watcher. `onBreach` fires at most once, on the first
+ * event that pushes any active cap from at-or-under to over. After it fires the
+ * watcher keeps accumulating (so `runSpend()` stays accurate for the final
+ * ledger record) but never calls `onBreach` again.
+ */
+export declare function makeLiveSpendWatcher(args: {
+    caps: LiveCaps;
+    onBreach: (breach: BreachInfo) => void;
+}): LiveSpendWatcher;
+/**
+ * Incrementally extract usage events from a stream-json chunk. Buffers a partial
+ * trailing line across calls (returned in `rest`), parses each complete line,
+ * and yields one UsageEvent per line that carries token counts. Provider shapes
+ * handled: Claude/`--json` assistant turns (`message.usage` with
+ * `input_tokens`/`output_tokens`/`cache_*_input_tokens`) and the flatter
+ * `usage.record` shape (`usage.input_tokens`/`output`). Lines that aren't JSON
+ * or carry no usage are skipped — this never throws on agent output.
+ */
+export declare function extractUsageEvents(chunk: string, pending: string, fallbackModel?: string, fallbackAgent?: string): {
+    events: UsageEvent[];
+    rest: string;
+};