@phnx-labs/agents-cli 1.20.21 → 1.20.22

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 ## Unreleased
 
+**Secrets prompt policy: human-readable `always` / `daily`, and `secrets list` now shows it**
+
+- Renamed the secrets-agent `tier` to a **prompt policy** with plain-language names: `biometry` → **`always`** (ask every time), `session` → **`daily`** (ask once, then held ~24h until screen-lock / sleep / logout). The old name `session` was misleading — it never meant "once per login session" — and collided with the half-dozen other "session" concepts in the CLI (`agents sessions`, sessions-sync, pty/browser sessions). Set it with `agents secrets policy <bundle> [always|daily]`.
+- **Disclosure fixed.** `agents secrets list` now has a `POLICY` column — previously there was no way to tell which bundles would Touch-ID-prompt you. `daily` bundles currently held by the agent show `daily · Nh left`. `agents secrets view` and `create` now always state the policy (before, only the quiet tier was shown; the noisy default printed nothing).
+- **Back-compat:** the policy still persists under the legacy `tier`/`session` token, so bundles stay readable across mixed CLI versions on synced machines. `agents secrets tier`, `--tier`, and the `biometry`/`session` values keep working as aliases.
+- A third **`never`** policy (silent, no biometry ACL) is tracked for later in #421.
+
+**Self-healing: long-running processes reload onto new code after an upgrade**
+
+- Root cause behind a class of "stale behavior" bugs: a routines daemon or secrets-agent broker keeps running **pre-upgrade code** for days. An in-place `npm i -g` swaps the files but not the running processes, so fixes (keychain read-memoization, the broker fast-path, etc.) silently never take effect — the daemon kept popping Touch ID from the keychain because it predated the fix.
+- **Heal-on-upgrade:** `postinstall` now bounces the routines daemon and kickstarts the persistent secrets-agent broker onto the just-installed code — the one moment we know the code changed. Best-effort, non-fatal, skipped in CI / with `AGENTS_NO_HEAL=1`.
+- **Broker version-skew self-heal:** the broker's `ping` reports the version of the code it's running; `ensureAgentRunning` (the unlock / auto-cache path, never per-read) restarts a broker found running stale code, and a persistent broker self-exits on detecting an in-place upgrade so launchd relaunches it fresh. New `getCliVersionFresh()` re-reads `package.json` to detect the swap.
+- No hot-path cost: all checks live on existing control-plane paths (postinstall, the broker sweep, `ensureAgentRunning`), never on a per-secret-read. macOS only. Complements #412 (daemon session-sync memoization) by ensuring the daemon actually *runs* that code.
+
 **`agents secrets start`: persistent secrets-agent service (fixes the broker under heavy load)**
 
 - On a heavily-loaded machine (many concurrent agents, high load average) the on-demand broker — a full CLI cold-start — couldn't get scheduled enough CPU to finish booting and bind its socket, so `unlock`/auto-cache silently failed and reads kept prompting. New `agents secrets start` installs the broker as a **launchd user service** (`RunAtLoad` + `KeepAlive`, `ProcessType: Interactive` for foreground scheduling priority): it starts once and stays up for the whole login session, so every read just connects — the cold start happens once (and launchd retries until it wins), never per read. `agents secrets stop` removes it; `agents secrets status` shows whether it's installed.

package/dist/commands/cloud.js

@@ -47,12 +47,16 @@ function isJsonMode(opts) {
 export function registerCloudCommands(program) {
     const cloud = program
         .command('cloud', { hidden: true })
-        .description('Dispatch and manage cloud agent tasks across providers (Rush Cloud, Codex Cloud, Factory).')
+        .description('Dispatch and manage cloud agent tasks across providers (Rush, Codex, Factory, Antigravity).')
         .addHelpText('after', `
+Each agent runs in its own cloud. Pass --agent and the provider is auto-selected
+(claude→rush, codex→codex, droid→factory, antigravity→antigravity); --provider overrides.
+
 Providers:
-  rush      Rush Cloud — dispatches against a GitHub repo + branch
-  codex     Codex Cloud — runs in a pre-built Codex environment
-  factory   Factory pods — Droid + computer-use targets
+  rush         Rush Cloud — Claude against a GitHub repo + branch → PR
+  codex        Codex Cloud — runs in a pre-built Codex environment (--env)
+  factory      Factory Droid Computer — droid exec on a cloud VM (--computer)
+  antigravity  Gemini Managed Agents — Antigravity harness in a remote sandbox
 
 Examples:
   # Dispatch a quick fix to Rush Cloud and stream the output
@@ -92,8 +96,8 @@ Examples:
     cloud
         .command('run [prompt]')
         .description('Dispatch a task to a cloud agent.')
-        .option('--provider <id>', 'Cloud backend: rush, codex, factory')
-        .option('--agent <name>', 'Agent to run: claude, codex, droid')
+        .option('--provider <id>', 'Cloud backend: rush, codex, factory, antigravity (overrides agent auto-routing)')
+        .option('--agent <name>', 'Agent to run: claude, codex, droid, antigravity (auto-routes to its native cloud)')
         .option('--repo <owner/repo>', 'GitHub repository. Repeatable for multi-repo dispatch (Rush Cloud only).', (value, previous) => {
         const acc = Array.isArray(previous) ? previous : [];
         acc.push(value);
@@ -105,6 +109,7 @@ Examples:
         .option('--model <model>', 'Model override')
         .option('--env <id>', 'Codex Cloud environment ID')
         .option('--computer <name>', 'Factory/Droid computer target')
+        .option('--autonomy <level>', 'Factory/Droid autonomy: low, medium, high (default high)')
         .option('--mode <mode>', 'Execution mode (e.g., plan, edit, full)')
         .option('-b, --balanced', 'Shortcut for --strategy balanced. Route the factory run across all healthy accounts.')
         .option('--strategy <strategy>', 'Account selection strategy for the factory: balanced. Sends all healthy accounts so the factory pod rotates between them on rate-limit.')
@@ -142,7 +147,9 @@ Examples:
                 process.stderr.write(chalk.dim(`Reading prompt from ${filePath} (${sizeKB} KB)\n`));
             }
         }
-        const provider = resolveProvider(options.provider);
+        // Agent-aware: with no --provider, the agent routes to its native cloud
+        // (claude→rush, codex→codex, droid→factory, antigravity→antigravity).
+        const provider = resolveProvider(options.provider, options.agent);
         // --repo is repeatable: commander gives us an array via our collector.
         // A single --repo value arrives as a one-element array; keep the legacy
         // singular `repo` field in sync so providers that only know that field
@@ -166,6 +173,8 @@ Examples:
             dispatchOptions.providerOptions.env = options.env;
         if (options.computer)
             dispatchOptions.providerOptions.computer = options.computer;
+        if (options.autonomy)
+            dispatchOptions.providerOptions.autonomy = options.autonomy;
         if (options.mode)
             dispatchOptions.providerOptions.mode = options.mode;
         if (options.balanced || options.strategy === 'balanced') {

package/dist/commands/menubar.d.ts

@@ -0,0 +1,10 @@
+/**
+ * `agents menubar` — manage the macOS menu-bar helper.
+ *
+ * The helper is a no-Dock status-bar app that surfaces running sessions, agents
+ * needing input, and routines, and launches new sessions. It auto-installs on
+ * upgrade (runMigration -> installMenubarLaunchAgentOnUpgrade) for every macOS
+ * user; these commands are the manual override.
+ */
+import type { Command } from 'commander';
+export declare function registerMenubarCommands(program: Command): void;

package/dist/commands/menubar.js

@@ -0,0 +1,83 @@
+/**
+ * `agents menubar` — manage the macOS menu-bar helper.
+ *
+ * The helper is a no-Dock status-bar app that surfaces running sessions, agents
+ * needing input, and routines, and launches new sessions. It auto-installs on
+ * upgrade (runMigration -> installMenubarLaunchAgentOnUpgrade) for every macOS
+ * user; these commands are the manual override.
+ */
+import chalk from 'chalk';
+import { enableMenubarService, disableMenubarService, getMenubarStatus, } from '../lib/menubar/install-menubar.js';
+function notMac() {
+    if (process.platform !== 'darwin') {
+        console.log(chalk.yellow('The menu bar helper is macOS only.'));
+        return true;
+    }
+    return false;
+}
+export function registerMenubarCommands(program) {
+    const menubar = program
+        .command('menubar')
+        .description('Manage the macOS menu-bar helper (running sessions, agents awaiting input, routines)');
+    menubar
+        .command('enable')
+        .description('Install and start the menu-bar helper (launches at login)')
+        .action(() => {
+        if (notMac())
+            return;
+        const ok = enableMenubarService({ clearOptOut: true });
+        if (!ok) {
+            console.log(chalk.red('Could not enable: no menu-bar helper bundle ships with this install.'));
+            console.log(chalk.gray('  This build may predate the helper, or be a non-macOS package.'));
+            return;
+        }
+        console.log(chalk.green('Menu bar helper enabled.') + chalk.gray('  Look for the agents mark in your menu bar.'));
+    });
+    menubar
+        .command('disable')
+        .description('Stop and remove the menu-bar helper (stays off across upgrades)')
+        .action(() => {
+        if (notMac())
+            return;
+        disableMenubarService();
+        console.log(chalk.green('Menu bar helper disabled.') + chalk.gray('  Re-enable any time with `agents menubar enable`.'));
+    });
+    menubar
+        .command('status')
+        .description('Show whether the menu-bar helper is installed and running')
+        .option('--json', 'Emit machine-readable JSON')
+        .action((options) => {
+        const s = getMenubarStatus();
+        if (options.json) {
+            process.stdout.write(JSON.stringify(s) + '\n');
+            return;
+        }
+        if (s.platform !== 'darwin') {
+            console.log(chalk.yellow('The menu bar helper is macOS only.'));
+            return;
+        }
+        const yn = (b) => (b ? chalk.green('yes') : chalk.gray('no'));
+        console.log(chalk.bold('Menu bar helper\n'));
+        console.log(`  running            ${yn(s.running)}`);
+        console.log(`  service installed  ${yn(s.serviceInstalled)}`);
+        console.log(`  app installed      ${s.installedApp ? chalk.gray(s.installedApp) : chalk.gray('no')}`);
+        console.log(`  bundle source      ${s.source ? chalk.gray(s.source) : chalk.red('missing (cannot enable)')}`);
+        console.log(`  disabled by user   ${yn(s.disabledByUser)}`);
+        if (!s.serviceInstalled && !s.disabledByUser) {
+            console.log(chalk.gray('\n  Enable it with `agents menubar enable`.'));
+        }
+    });
+    // Bare `agents menubar` -> status.
+    menubar.action(() => {
+        const s = getMenubarStatus();
+        if (s.platform !== 'darwin') {
+            console.log(chalk.yellow('The menu bar helper is macOS only.'));
+            return;
+        }
+        const yn = (b) => (b ? chalk.green('yes') : chalk.gray('no'));
+        console.log(chalk.bold('Menu bar helper\n'));
+        console.log(`  running            ${yn(s.running)}`);
+        console.log(`  service installed  ${yn(s.serviceInstalled)}`);
+        console.log(chalk.gray('\n  enable | disable | status'));
+    });
+}

package/dist/commands/routines.js

@@ -124,9 +124,14 @@ export function registerRoutinesCommands(program) {
     routinesCmd
         .command('list')
         .description('See all scheduled jobs, when they run next, and their last execution status')
-        .action(() => {
+        .option('--json', 'Emit machine-readable JSON instead of the table (used by the menu bar helper)')
+        .action((options) => {
         const jobs = listAllJobs(process.cwd());
         if (jobs.length === 0) {
+            if (options.json) {
+                process.stdout.write('[]\n');
+                return;
+            }
             console.log(chalk.gray('No jobs configured'));
             console.log(chalk.gray('  Add a job: agents routines add <path-to-job.yml>'));
             return;
@@ -142,6 +147,34 @@ export function registerRoutinesCommands(program) {
         catch {
             // Best-effort indicator; never block the list on detection errors.
         }
+        // Machine-readable path: same data the table renders, but structured.
+        // The menu bar helper relies on this so it never reimplements cron math.
+        if (options.json) {
+            const nowJson = new Date();
+            const payload = jobs.map((job) => {
+                const nextRun = scheduler.getNextRun(job.name);
+                const latestRun = getLatestRun(job.name);
+                return {
+                    name: job.name,
+                    agent: job.agent ?? null,
+                    workflow: job.workflow ?? null,
+                    repo: job.repo ?? null,
+                    schedule: job.schedule,
+                    scheduleHuman: humanizeCron(job.schedule, job.timezone),
+                    timezone: job.timezone ?? null,
+                    enabled: job.enabled,
+                    overdue: overdueSet.has(job.name),
+                    nextRun: nextRun ? nextRun.toISOString() : null,
+                    nextRunHuman: humanizeNextRun(nextRun ?? null, nowJson, job.timezone),
+                    lastStatus: latestRun?.status ?? null,
+                    lastRunStartedAt: latestRun?.startedAt ?? null,
+                    lastRunCompletedAt: latestRun?.completedAt ?? null,
+                };
+            });
+            scheduler.stopAll();
+            process.stdout.write(JSON.stringify(payload) + '\n');
+            return;
+        }
         console.log(chalk.bold('Scheduled Jobs\n'));
         // OSC 8 hyperlink helper — renders as a clickable link in supporting terminals.
         // Guarded on process.stdout.isTTY so that piped/redirected output never

package/dist/commands/secrets.d.ts

@@ -5,7 +5,7 @@
  * and managing named bundles of environment variables backed by macOS
  * Keychain. Bundles are injected at run time via `agents run --secrets`.
  */
-import type { Command } from 'commander';
+import { type Command } from 'commander';
 /**
  * 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 `-`

package/dist/commands/secrets.js

@@ -5,10 +5,11 @@
  * and managing named bundles of environment variables backed by macOS
  * Keychain. Bundles are injected at run time via `agents run --secrets`.
  */
+import { Option } from 'commander';
 import chalk from 'chalk';
 import * as fs from 'fs';
 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 { bundleExists, bundleItemStore, bundlePolicy, 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, installSecretsAgentService, runAgentLoadFromStdin, runSecretsAgent, secretsAgentServiceInstalled, uninstallSecretsAgentService, } from '../lib/secrets/agent.js';
@@ -212,8 +213,30 @@ function humanAge(iso) {
         return age;
     return `${age} ago`;
 }
+/** Compact remaining-time for the list POLICY column: "19h" / "45m" / "2d". */
+function compactRemaining(expiresAt) {
+    const ms = expiresAt - Date.now();
+    if (ms <= 0)
+        return 'expired';
+    const mins = Math.round(ms / 60000);
+    if (mins < 60)
+        return `${mins}m`;
+    const hours = Math.round(mins / 60);
+    if (hours < 24)
+        return `${hours}h`;
+    return `${Math.round(hours / 24)}d`;
+}
+/** The POLICY column for `secrets list`: the prompt policy, plus a "Nh left"
+ * hint when a `daily` bundle is currently held by the secrets-agent. `held`
+ * maps bundle name → expiry epoch-ms (from agentStatus()). */
+function renderPolicyCol(b, held) {
+    if (bundlePolicy(b) === 'always')
+        return chalk.yellow('always ask');
+    const exp = held?.get(b.name);
+    return exp ? chalk.green(`daily · ${compactRemaining(exp)} left`) : chalk.gray('daily');
+}
 /** Format a single bundle as a table row for the `secrets list` output. */
-function renderBundleRow(b) {
+function renderBundleRow(b, held) {
     const entries = describeBundle(b);
     const keys = entries.length;
     const expiringCount = countExpiringSoon(b.meta);
@@ -231,6 +254,7 @@ function renderBundleRow(b) {
         : (b.created_at ? chalk.gray('never') : chalk.gray('?'));
     const head = `${chalk.cyan(b.name.padEnd(20))} ` +
         `${String(keys).padEnd(5)} ` +
+        `${padVisible(renderPolicyCol(b, held), 18)} ` +
         `${padVisible(expiring, 9)} ` +
         `${padVisible(created, 9)} ` +
         `${padVisible(updated, 9)} ` +
@@ -380,9 +404,12 @@ export function registerSecretsCommands(program) {
       # Inject the bundle into an agent run
       agents run claude "deploy the worker" --secrets prod
 
-      # See what's in the bundle (values masked)
+      # See what's in the bundle (values masked); shows its prompt policy
       agents secrets view prod
 
+      # Stop a noisy automation bundle from prompting every run: ask once a day
+      agents secrets policy prod daily
+
       # Eval the bundle into your current shell
       eval "$(agents secrets export prod --plaintext)"
 
@@ -398,11 +425,16 @@ export function registerSecretsCommands(program) {
       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.
+      agents each re-prompt. Each bundle has a prompt policy, shown in the POLICY
+      column of 'agents secrets list':
+        always (default)  ask for Touch ID every time — never auto-held.
+        daily             ask once, then hold it silently in the local agent up
+                          to ~24h, until screen-lock / sleep / logout or 'lock'.
+      Set it with 'agents secrets policy <bundle> daily'. 'agents secrets unlock
+      <bundle>' holds any bundle after one prompt regardless of policy. Nothing on disk.
 
       See also:
+        agents secrets policy <bundle> daily           ask once a day, not every run
         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
@@ -416,7 +448,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: ['start', 'stop', 'unlock', 'lock', 'status', 'tier'] },
+        { title: 'Agent commands', names: ['start', 'stop', 'unlock', 'lock', 'status', 'policy'] },
         { title: 'Raw item commands', names: ['get', 'set'] },
         { title: 'Sync commands', names: ['push', 'pull', 'remote-list'] },
         { title: 'Utilities', names: ['exec', 'generate', 'migrate-acl'] },
@@ -425,16 +457,28 @@ export function registerSecretsCommands(program) {
         .command('list')
         .alias('ls')
         .description('List configured secrets bundles')
-        .action(() => {
+        .action(async () => {
         const bundles = listBundles();
         if (bundles.length === 0) {
             console.log(chalk.gray('No secrets bundles configured.'));
             console.log(chalk.gray('Try: agents secrets create <name>'));
             return;
         }
-        console.log(chalk.bold(`${'NAME'.padEnd(20)} ${'KEYS'.padEnd(5)} ${'EXPIRING'.padEnd(9)} ${'CREATED'.padEnd(9)} ${'UPDATED'.padEnd(9)} ${'USED'.padEnd(7)} DESCRIPTION`));
+        // Cross-reference the secrets-agent so `daily` bundles that are currently
+        // held can show "· Nh left". Soft-fails to no hint if the broker is down.
+        const held = new Map();
+        if (process.platform === 'darwin') {
+            try {
+                for (const e of await agentStatus())
+                    held.set(e.name, e.expiresAt);
+            }
+            catch {
+                /* broker not running — render policy without the countdown */
+            }
+        }
+        console.log(chalk.bold(`${'NAME'.padEnd(20)} ${'KEYS'.padEnd(5)} ${'POLICY'.padEnd(18)} ${'EXPIRING'.padEnd(9)} ${'CREATED'.padEnd(9)} ${'UPDATED'.padEnd(9)} ${'USED'.padEnd(7)} DESCRIPTION`));
         for (const b of bundles) {
-            console.log(renderBundleRow(b));
+            console.log(renderBundleRow(b, held));
         }
     });
     cmd
@@ -455,8 +499,9 @@ export function registerSecretsCommands(program) {
                 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)'));
+            console.log(bundlePolicy(bundle) === 'daily'
+                ? chalk.gray('policy: daily (ask once, then held ~24h until screen-lock / sleep / logout)')
+                : chalk.gray('policy: always (asks for Touch ID every time — never auto-held)'));
             if (bundle.created_at)
                 console.log(chalk.gray(`created_at: ${bundle.created_at} (${humanAge(bundle.created_at)})`));
             if (bundle.updated_at)
@@ -578,14 +623,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('--policy <policy>', 'prompt policy: always (default, ask every time) or daily (ask once a day)')
+        .addOption(new Option('--tier <policy>', 'deprecated alias for --policy').hideHelp())
         .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 policy = parsePolicyOpt(opts.policy ?? opts.tier);
             const backend = parseBackendOpt(opts.backend);
             if (bundleExists(resolvedName) && !opts.force) {
                 console.error(chalk.red(`Bundle '${resolvedName}' already exists. Use --force to overwrite.`));
@@ -596,12 +642,15 @@ export function registerSecretsCommands(program) {
                 description: opts.description,
                 allow_exec: opts.allowExec,
                 backend: backend === 'file' ? 'file' : undefined,
-                tier,
+                policy,
                 vars: {},
             };
             writeBundle(bundle);
-            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(', ')})` : ''}.`));
+            const tags = [
+                policy === 'daily' ? 'policy: daily' : 'policy: always ask',
+                backend === 'file' ? 'backend: file' : null,
+            ].filter(Boolean);
+            console.log(chalk.green(`Bundle '${resolvedName}' created (${tags.join(', ')}).`));
             if (backend === 'file') {
                 console.log(chalk.gray('File-backed: items are AES-256-GCM encrypted under AGENTS_SECRETS_PASSPHRASE (no Touch ID).'));
             }
@@ -1379,21 +1428,25 @@ Examples:
         }
     });
     cmd
-        .command('tier <bundle> [tier]')
-        .description("Show or set a bundle's secrets-agent tier: biometry (default) or session.")
-        .action((bundleName, tier) => {
+        .command('policy <bundle> [policy]')
+        .alias('tier')
+        .description("Show or set a bundle's prompt policy: always (default, ask every time) or daily (ask once a day).")
+        .action((bundleName, policyArg) => {
         try {
             const bundle = readBundle(bundleName);
-            if (tier === undefined) {
-                console.log(`${chalk.cyan(bundle.name)} tier: ${chalk.bold(bundleTier(bundle))}`);
+            if (policyArg === undefined) {
+                console.log(`${chalk.cyan(bundle.name)} policy: ${chalk.bold(bundlePolicy(bundle))}`);
                 return;
             }
-            const next = parseTierOpt(tier);
-            bundle.tier = next;
+            const next = parsePolicyOpt(policyArg);
+            bundle.policy = 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.'));
+            console.log(chalk.green(`${bundle.name} policy set to ${next}.`));
+            if (next === 'daily') {
+                console.log(chalk.gray('Held by the secrets-agent after one unlock: run `agents secrets unlock`, or enable auto-cache with `secrets.agent.auto: true` in agents.yaml.'));
+            }
+            else {
+                console.log(chalk.gray('Asks for Touch ID every time — never auto-held.'));
             }
         }
         catch (err) {
@@ -1411,7 +1464,7 @@ Examples:
         }
         process.stdout.write(chalk.gray('Installing launchd service…\n'));
         if (await installSecretsAgentService()) {
-            console.log(chalk.green('secrets-agent service running.') + chalk.gray(' It stays up across the session; unlock/auto-cache now connect instantly.'));
+            console.log(chalk.green('secrets-agent service running.') + chalk.gray(' It stays up across your macOS login session; unlock/auto-cache now connect instantly.'));
         }
         else {
             console.error(chalk.red('Service installed but did not become reachable in time (machine may be heavily loaded — launchd will keep retrying).'));
@@ -1443,18 +1496,22 @@ Examples:
     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'."));
+/** Validate a prompt-policy value, exiting with a clear message on a bad one.
+ * Accepts the legacy `biometry`/`session` tokens as aliases for `always`/`daily`
+ * so older flags and scripts keep working. `never`/`none` (no biometry ACL) is
+ * rejected explicitly — it needs a separate signed-helper change (see
+ * https://github.com/phnx-labs/agents-cli/issues/421). */
+function parsePolicyOpt(raw) {
+    const v = (raw ?? 'always').toLowerCase();
+    if (v === 'always' || v === 'biometry')
+        return 'always';
+    if (v === 'daily' || v === 'session')
+        return 'daily';
+    if (v === 'never' || v === 'none') {
+        console.error(chalk.red("policy 'never' (no biometry ACL) is not available yet — see https://github.com/phnx-labs/agents-cli/issues/421. Use 'always' or 'daily'."));
         process.exit(1);
     }
-    console.error(chalk.red(`Invalid --tier '${raw}'. Use 'biometry' or 'session'.`));
+    console.error(chalk.red(`Invalid policy '${raw}'. Use 'always' or 'daily'.`));
     process.exit(1);
 }
 /** Validate a --backend value, exiting with a clear message on a bad one. */

package/dist/index.js

@@ -23,7 +23,7 @@ const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const packageJsonPath = path.join(__dirname, '..', 'package.json');
 const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf-8'));
 const VERSION = packageJson.version;
-import { NPM_PACKAGE_NAME, deriveGlobalPrefix, installPackageIntoPrefix, verifyInstalledVersion, refreshAliasShims, } from './lib/self-update.js';
+import { NPM_PACKAGE_NAME, deriveGlobalPrefix, detectPackageManager, installPackageIntoPrefix, installPackageWithBun, verifyInstalledVersion, refreshAliasShims, } from './lib/self-update.js';
 // Detect dev/working-tree builds and default the noisy startup steps off.
 // Three cases trip this:
 //   1. Dev install (scripts/install.sh) — package.json version stamped 0.0.0-dev.<sha>
@@ -95,6 +95,7 @@ import { registerProfilesCommands } from './commands/profiles.js';
 import { registerSecretsCommands } from './commands/secrets.js';
 import { registerWalletCommands } from './commands/wallet.js';
 import { registerHelperCommand } from './commands/helper.js';
+import { registerMenubarCommands } from './commands/menubar.js';
 import { registerFactoryCommands } from './commands/factory.js';
 import { registerUsageCommand } from './commands/usage.js';
 import { registerCostCommand } from './commands/cost.js';
@@ -347,8 +348,17 @@ function printResolvedPackage(metadata) {
 }
 async function installResolvedPackage(metadata) {
     const packageRoot = path.resolve(__dirname, '..');
-    const prefix = deriveGlobalPrefix(packageRoot);
-    await installPackageIntoPrefix(`${NPM_PACKAGE_NAME}@${metadata.version}`, prefix);
+    const spec = `${NPM_PACKAGE_NAME}@${metadata.version}`;
+    // Upgrade with the package manager that owns this install. A bun global
+    // install lives at <bunGlobalDir>/node_modules/... (no `lib` segment), so an
+    // `npm install --prefix` would write to <bunGlobalDir>/lib/node_modules and
+    // never touch the running copy — npm exits 0, the verify below fails.
+    if (detectPackageManager(packageRoot) === 'bun') {
+        await installPackageWithBun(spec);
+    }
+    else {
+        await installPackageIntoPrefix(spec, deriveGlobalPrefix(packageRoot));
+    }
     verifyInstalledVersion(packageRoot, metadata.version);
     refreshAliasShims(packageRoot);
     // The npm install above runs with --ignore-scripts, so the postinstall that
@@ -675,6 +685,7 @@ registerProfilesCommands(program);
 registerSecretsCommands(program);
 registerWalletCommands(program);
 registerHelperCommand(program);
+registerMenubarCommands(program);
 registerBetaCommands(program);
 registerSyncCommand(program);
 registerRefreshRulesCommand(program);
@@ -916,6 +927,20 @@ if (process.env.AGENTS_SKIP_MIGRATION !== '1') {
     }
     catch { /* migration must never block CLI startup */ }
 }
+// Auto-enable the macOS menu-bar helper once, for every user. Best-effort and
+// idempotent: installMenubarLaunchAgentOnUpgrade() no-ops when not on darwin,
+// when the user ran `agents menubar disable` (sticky opt-out), when the service
+// is already installed, or when no helper bundle ships with this build. This is
+// a lightweight startup self-heal (two existsSync checks then return) rather
+// than a migration-sentinel bump, so it covers fresh installs AND upgrades
+// without re-running the full migration for the whole user base (issue #20).
+if (process.platform === 'darwin' && process.env.AGENTS_SKIP_MIGRATION !== '1') {
+    try {
+        const { installMenubarLaunchAgentOnUpgrade } = await import('./lib/menubar/install-menubar.js');
+        installMenubarLaunchAgentOnUpgrade();
+    }
+    catch { /* never block CLI startup on the menu bar */ }
+}
 try {
     await maybeBootstrapShimIntegration(requestedCommand, helpOrVersionRequested);
     await program.parseAsync();

package/dist/lib/agents.js

@@ -207,6 +207,9 @@ export const AGENTS = {
         format: 'markdown',
         variableSyntax: '$ARGUMENTS',
         supportsHooks: true,
+        // Claude Code has no headless Anthropic-hosted dispatch CLI (only
+        // --remote-control, which bridges a *local* session). Its cloud is Rush.
+        cloudProvider: 'rush',
         capabilities: { hooks: true, mcp: true, allowlist: true, skills: true, commands: true, plugins: true, subagents: true, rules: { file: 'CLAUDE.md' }, workflows: true, modes: ['plan', 'edit', 'auto', 'skip'], rulesImports: true },
     },
     // codex hooks: gated to >= 0.116.0 (introduced [features] codex_hooks flag).
@@ -226,6 +229,7 @@ export const AGENTS = {
         format: 'markdown',
         variableSyntax: '$ARGUMENTS',
         supportsHooks: true,
+        cloudProvider: 'codex',
         capabilities: { hooks: { since: '0.116.0' }, mcp: true, allowlist: false, skills: true, commands: { until: '0.117.0' }, plugins: { since: '0.128.0' }, subagents: false, rules: { file: 'AGENTS.md' }, workflows: false, modes: ['plan', 'edit', 'skip'] },
     },
     gemini: {
@@ -412,6 +416,7 @@ export const AGENTS = {
         format: 'markdown',
         variableSyntax: '{{args}}',
         supportsHooks: true,
+        cloudProvider: 'antigravity',
         capabilities: { hooks: true, mcp: true, allowlist: true, skills: true, commands: true, plugins: true, subagents: false, rules: { file: 'AGENTS.md' }, workflows: false, modes: ['edit', 'skip'], rulesImports: false },
     },
     // xAI Grok Build CLI (`grok`) — early beta, SuperGrok Heavy. Auth via OAuth on
@@ -509,6 +514,9 @@ export const AGENTS = {
         format: 'markdown',
         variableSyntax: '$ARGUMENTS',
         supportsHooks: false,
+        // Factory Droid Computers (cloud VMs) reached via `droid computer ssh` +
+        // remote headless `droid exec`.
+        cloudProvider: 'factory',
         capabilities: {
             hooks: false,
             mcp: true,