@phnx-labs/agents-cli 1.20.21 → 1.20.23

package/dist/lib/secrets/bundles.d.ts

@@ -39,15 +39,21 @@ export interface VarMeta {
     note?: string;
 }
 /**
- * How a bundle interacts with the macOS secrets-agent:
- * - `biometry` (default): only an explicit `agents secrets unlock` populates the
- *   agent; every other read pops Touch ID. Use for high-value bundles you want
- *   to confirm each session.
- * - `session`: eligible for the agent — `unlock`, and (when `secrets.agent.auto`
- *   is enabled) the first real keychain read auto-loads it so concurrent runs
- *   read it silently.
+ * A bundle's prompt policy — how often macOS asks for Touch ID to read it:
+ * - `always` (default): asks every time. Only an explicit `agents secrets
+ *   unlock` ever holds it in the secrets-agent; every other read pops Touch ID.
+ *   Use for high-value bundles you want to confirm every time.
+ * - `daily`: ask once, then hold it silently. Eligible for the secrets-agent —
+ *   `unlock` it, or (when `secrets.agent.auto` is enabled) the first real
+ *   keychain read auto-loads it so concurrent runs read it silently. Held up to
+ *   ~24h from that unlock (not refreshed on use); re-asks sooner after
+ *   screen-lock, sleep, logout, or `agents secrets lock`.
+ *
+ * Stored on disk under the legacy `tier` key (`session` == `daily`; absent ==
+ * `always`) so bundles stay readable across mixed CLI versions on synced
+ * machines. The in-memory and user-facing vocabulary is `policy`/`always`/`daily`.
  */
-export type SecretsTier = 'biometry' | 'session';
+export type SecretsPolicy = 'always' | 'daily';
 /** A named set of environment variable definitions backed by various secret providers. */
 export interface SecretsBundle {
     name: string;
@@ -55,8 +61,9 @@ export interface SecretsBundle {
     allow_exec?: boolean;
     /** Which store carries this bundle's items. Absent ⇒ `keychain` (the default). */
     backend?: SecretsBackend;
-    /** Secrets-agent interaction tier. Absent ⇒ `biometry` (the safe default). */
-    tier?: SecretsTier;
+    /** Prompt policy. Absent ⇒ `always` (the safe default). Serialized under the
+     * legacy `tier` key — see SecretsPolicy. */
+    policy?: SecretsPolicy;
     /** ISO 8601 UTC timestamp. Set once on the first writeBundle() for a bundle. */
     created_at?: string;
     /** ISO 8601 UTC timestamp. Refreshed on every writeBundle(). */
@@ -90,8 +97,8 @@ export declare function validateSecretType(t: string): asserts t is SecretType;
 export declare function validateExpiresFutureDated(iso: string): void;
 export declare function bundleExists(name: string): boolean;
 export declare function readBundle(name: string): SecretsBundle;
-/** The effective tier of a bundle (absent ⇒ `biometry`). */
-export declare function bundleTier(bundle: SecretsBundle): SecretsTier;
+/** The effective prompt policy of a bundle (absent ⇒ `always`). */
+export declare function bundlePolicy(bundle: SecretsBundle): SecretsPolicy;
 export declare function writeBundle(bundle: SecretsBundle): void;
 export declare function deleteBundle(name: string): boolean;
 export declare function listBundles(): SecretsBundle[];

package/dist/lib/secrets/bundles.js

@@ -223,10 +223,11 @@ export function readBundle(name) {
         name,
         description: parsed.description,
         allow_exec: Boolean(parsed.allow_exec),
-        // Absent ⇒ keychain (mirrors `tier`); only set when file-backed so a
-        // keychain bundle round-trips byte-for-byte.
+        // Absent ⇒ keychain; only set when file-backed so a keychain bundle
+        // round-trips byte-for-byte.
         backend: backend === 'file' ? 'file' : undefined,
-        tier: parseTier(parsed.tier),
+        // Legacy wire key: the policy is persisted under `tier` (`session` == `daily`).
+        policy: parsePolicy(parsed.tier),
         vars: parsed.vars && typeof parsed.vars === 'object' ? parsed.vars : {},
     };
     if (typeof parsed.created_at === 'string')
@@ -243,13 +244,16 @@ export function readBundle(name) {
     }
     return bundle;
 }
-/** Normalize a persisted `tier` value; anything but `session` ⇒ default tier. */
-function parseTier(raw) {
-    return raw === 'session' ? 'session' : undefined;
+/** Normalize the persisted prompt policy. The on-disk `tier` key uses the
+ * legacy `session` token for `daily` (and `biometry`/absent for the default),
+ * so accept both the legacy and current tokens. Anything but `daily`/`session`
+ * ⇒ undefined (resolves to the `always` default). */
+function parsePolicy(raw) {
+    return raw === 'daily' || raw === 'session' ? 'daily' : undefined;
 }
-/** The effective tier of a bundle (absent ⇒ `biometry`). */
-export function bundleTier(bundle) {
-    return bundle.tier ?? 'biometry';
+/** The effective prompt policy of a bundle (absent ⇒ `always`). */
+export function bundlePolicy(bundle) {
+    return bundle.policy ?? 'always';
 }
 export function writeBundle(bundle) {
     validateBundleName(bundle.name);
@@ -288,7 +292,9 @@ export function writeBundle(bundle) {
         description: bundle.description,
         allow_exec: bundle.allow_exec ? true : undefined,
         backend: backend === 'file' ? 'file' : undefined,
-        tier: bundle.tier === 'session' ? 'session' : undefined,
+        // Wire format: persist `daily` under the legacy `tier`/`session` token so
+        // older CLI versions on other synced machines keep reading the policy.
+        tier: bundle.policy === 'daily' ? 'session' : undefined,
         created_at: bundle.created_at,
         updated_at: bundle.updated_at,
         last_used: bundle.last_used,
@@ -328,7 +334,8 @@ function parseBundleMeta(name, json, backend) {
         description: parsed.description,
         allow_exec: Boolean(parsed.allow_exec),
         backend: backend === 'file' ? 'file' : undefined,
-        tier: parseTier(parsed.tier),
+        // Legacy wire key: the policy is persisted under `tier` (`session` == `daily`).
+        policy: parsePolicy(parsed.tier),
         vars: parsed.vars && typeof parsed.vars === 'object' ? parsed.vars : {},
     };
     if (typeof parsed.created_at === 'string')
@@ -568,7 +575,8 @@ export function readAndResolveBundleEnv(name, opts = {}) {
         description: parsed.description,
         allow_exec: Boolean(parsed.allow_exec),
         backend: backend === 'file' ? 'file' : undefined,
-        tier: parseTier(parsed.tier),
+        // Legacy wire key: the policy is persisted under `tier` (`session` == `daily`).
+        policy: parsePolicy(parsed.tier),
         vars: parsed.vars && typeof parsed.vars === 'object' ? parsed.vars : {},
     };
     if (typeof parsed.created_at === 'string')
@@ -639,14 +647,14 @@ export function readAndResolveBundleEnv(name, opts = {}) {
         }
         emitReadAudit('success');
         // Auto-cache: this was a real keychain read (the agent fast-path returned
-        // earlier on a hit). If the bundle opts into the session tier and the user
+        // earlier on a hit). If the bundle opts into the `daily` policy and the user
         // enabled `secrets.agent.auto`, populate the broker in the background so the
         // next concurrent run reads silently. Skipped when noAgent (e.g. `unlock`,
         // which loads the agent itself). Fire-and-forget — never blocks this read.
         if (backend === 'keychain' &&
             !opts.noAgent &&
             process.env.AGENTS_SECRETS_NO_AGENT !== '1' &&
-            bundleTier(bundle) === 'session' &&
+            bundlePolicy(bundle) === 'daily' &&
             secretsAgentAutoEnabled()) {
             agentAutoLoadSync(name, bundle, env, DEFAULT_TTL_MS);
         }

package/dist/lib/self-update.d.ts

@@ -12,6 +12,31 @@
  * to PATH resolution.
  */
 export declare const NPM_PACKAGE_NAME = "@phnx-labs/agents-cli";
+export type PackageManager = 'npm' | 'bun';
+/**
+ * The directory bun installs global packages into:
+ *   <BUN_INSTALL>/install/global   (BUN_INSTALL defaults to ~/.bun)
+ *
+ * A globally-installed scoped package then lives at
+ * `<bunGlobalDir>/node_modules/@phnx-labs/agents-cli` — note there is NO `lib`
+ * segment, unlike npm's POSIX layout. That single difference is why an
+ * npm-based upgrade silently misses a bun install (see deriveGlobalPrefix).
+ */
+export declare function bunGlobalDir(): string;
+/**
+ * Identify which package manager owns the install at `packageRoot`, so the
+ * upgrade can shell out to the one that actually replaces this copy.
+ *
+ * bun lays a global package out as `<bunGlobalDir>/node_modules/<scoped pkg>`,
+ * so the prefix (the parent of `node_modules`) is the bun global dir itself.
+ * Everything else — npm's `<prefix>/lib/node_modules` and the Windows
+ * `<prefix>/node_modules` — is treated as npm.
+ *
+ * Detection is path-based (no subprocess): it matches the resolved bun global
+ * dir from BUN_INSTALL/$HOME, and falls back to the structural `.bun/install/
+ * global` tail for a relocated BUN_INSTALL not exported into this process.
+ */
+export declare function detectPackageManager(packageRoot: string): PackageManager;
 export interface UpdateCheckCache {
     lastCheck: number;
     latestVersion: string;
@@ -49,6 +74,15 @@ export declare function deriveGlobalPrefix(packageRoot: string): string;
  * refreshAliasShims().
  */
 export declare function installPackageIntoPrefix(spec: string, prefix: string): Promise<void>;
+/**
+ * Install `spec` into bun's global store with `bun add -g`. bun writes to
+ * `<bunGlobalDir>/node_modules/<pkg>`, which is exactly the running package
+ * root for a bun install — so verifyInstalledVersion() sees the new version
+ * in place. bun skips untrusted lifecycle scripts, so the caller refreshes
+ * alias shims afterwards via refreshAliasShims() rather than relying on the
+ * package's postinstall hook.
+ */
+export declare function installPackageWithBun(spec: string): Promise<void>;
 /** Read the version field of the package.json at `packageRoot`, fresh from disk. */
 export declare function readInstalledVersion(packageRoot: string): string;
 /**

package/dist/lib/self-update.js

@@ -12,10 +12,55 @@
  * to PATH resolution.
  */
 import * as fs from 'fs';
+import * as os from 'os';
 import * as path from 'path';
 import { spawnSync } from 'child_process';
 import { compareVersions } from './versions.js';
 export const NPM_PACKAGE_NAME = '@phnx-labs/agents-cli';
+/**
+ * The directory bun installs global packages into:
+ *   <BUN_INSTALL>/install/global   (BUN_INSTALL defaults to ~/.bun)
+ *
+ * A globally-installed scoped package then lives at
+ * `<bunGlobalDir>/node_modules/@phnx-labs/agents-cli` — note there is NO `lib`
+ * segment, unlike npm's POSIX layout. That single difference is why an
+ * npm-based upgrade silently misses a bun install (see deriveGlobalPrefix).
+ */
+export function bunGlobalDir() {
+    const bunInstall = process.env.BUN_INSTALL || path.join(os.homedir(), '.bun');
+    return path.join(bunInstall, 'install', 'global');
+}
+/**
+ * Identify which package manager owns the install at `packageRoot`, so the
+ * upgrade can shell out to the one that actually replaces this copy.
+ *
+ * bun lays a global package out as `<bunGlobalDir>/node_modules/<scoped pkg>`,
+ * so the prefix (the parent of `node_modules`) is the bun global dir itself.
+ * Everything else — npm's `<prefix>/lib/node_modules` and the Windows
+ * `<prefix>/node_modules` — is treated as npm.
+ *
+ * Detection is path-based (no subprocess): it matches the resolved bun global
+ * dir from BUN_INSTALL/$HOME, and falls back to the structural `.bun/install/
+ * global` tail for a relocated BUN_INSTALL not exported into this process.
+ */
+export function detectPackageManager(packageRoot) {
+    const resolved = path.resolve(packageRoot);
+    const prefix = path.dirname(path.dirname(path.dirname(resolved))); // strip <scope>/<pkg>/node_modules
+    if (prefix === path.resolve(bunGlobalDir()))
+        return 'bun';
+    const parts = prefix.split(path.sep);
+    const n = parts.length;
+    if (n >= 3 && parts[n - 1] === 'global' && parts[n - 2] === 'install' && parts[n - 3] === '.bun') {
+        return 'bun';
+    }
+    return 'npm';
+}
+/** The shell command a user can run by hand to reproduce the upgrade for `manager`. */
+function manualInstallHint(manager, packageRoot, spec) {
+    if (manager === 'bun')
+        return `bun add -g ${spec}`;
+    return `npm install -g --prefix ${deriveGlobalPrefix(packageRoot)} ${spec}`;
+}
 /** Read the cached update-check state from disk. Returns null if the file is missing or corrupt. */
 export function readUpdateCache(file) {
     try {
@@ -102,6 +147,20 @@ export async function installPackageIntoPrefix(spec, prefix) {
     const execFileAsync = promisify(execFile);
     await execFileAsync('npm', ['install', '-g', '--prefix', prefix, spec, '--ignore-scripts']);
 }
+/**
+ * Install `spec` into bun's global store with `bun add -g`. bun writes to
+ * `<bunGlobalDir>/node_modules/<pkg>`, which is exactly the running package
+ * root for a bun install — so verifyInstalledVersion() sees the new version
+ * in place. bun skips untrusted lifecycle scripts, so the caller refreshes
+ * alias shims afterwards via refreshAliasShims() rather than relying on the
+ * package's postinstall hook.
+ */
+export async function installPackageWithBun(spec) {
+    const { execFile } = await import('child_process');
+    const { promisify } = await import('util');
+    const execFileAsync = promisify(execFile);
+    await execFileAsync('bun', ['add', '-g', spec]);
+}
 /** Read the version field of the package.json at `packageRoot`, fresh from disk. */
 export function readInstalledVersion(packageRoot) {
     return JSON.parse(fs.readFileSync(path.join(packageRoot, 'package.json'), 'utf-8')).version;
@@ -113,8 +172,10 @@ export function readInstalledVersion(packageRoot) {
 export function verifyInstalledVersion(packageRoot, expectedVersion) {
     const actual = readInstalledVersion(packageRoot);
     if (actual !== expectedVersion) {
-        throw new Error(`npm reported success but ${packageRoot} is still ${actual} (expected ${expectedVersion}). ` +
-            `Run manually: npm install -g --prefix ${deriveGlobalPrefix(packageRoot)} ${NPM_PACKAGE_NAME}@${expectedVersion}`);
+        const manager = detectPackageManager(packageRoot);
+        const hint = manualInstallHint(manager, packageRoot, `${NPM_PACKAGE_NAME}@${expectedVersion}`);
+        throw new Error(`the package manager reported success but ${packageRoot} is still ${actual} (expected ${expectedVersion}). ` +
+            `Run manually: ${hint}`);
     }
 }
 /**

package/dist/lib/startup/command-registry.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Lazy command registry.
+ *
+ * The CLI entry point (src/index.ts) used to statically import every command
+ * module and call its `registerXCommand(program)` on every invocation. That
+ * loaded the entire command tree (~50 modules) before the first line of output,
+ * dominating cold-start latency.
+ *
+ * This module maps each user-typed top-level command name to a thunk that
+ * dynamically imports ONLY the module(s) that command needs. Fast commands
+ * (`--version`, `view`, ...) now pay for just the one module they use; the full
+ * tree is loaded only on the rare slow paths (unknown-command spellcheck, bare
+ * help) via `registerAllEagerCommands` in src/index.ts.
+ *
+ * Parity is non-negotiable: the name -> loader map below mirrors exactly which
+ * module registers which top-level command on `main`. Multi-command modules
+ * (versions, packages) map several names to the same loader; `prune` needs BOTH
+ * versions (which creates `prune <specs...>`) and prune.js (which attaches the
+ * `cleanup` subcommand to it), in that order — see commands/prune.ts.
+ */
+import type { Command } from 'commander';
+/** A function that registers one or more commands onto the root program. */
+export type Registrar = (program: Command) => void;
+/** A thunk that dynamically imports a command module and returns its registrar. */
+export type ModuleLoader = () => Promise<Registrar>;
+export declare const loadView: ModuleLoader;
+export declare const loadInspect: ModuleLoader;
+export declare const loadFeedback: ModuleLoader;
+export declare const loadCommands: ModuleLoader;
+export declare const loadHooks: ModuleLoader;
+export declare const loadSkills: ModuleLoader;
+export declare const loadRules: ModuleLoader;
+export declare const loadPermissions: ModuleLoader;
+export declare const loadMcp: ModuleLoader;
+export declare const loadCli: ModuleLoader;
+export declare const loadSubagents: ModuleLoader;
+export declare const loadPlugins: ModuleLoader;
+export declare const loadWorkflows: ModuleLoader;
+export declare const loadWorktree: ModuleLoader;
+export declare const loadVersions: ModuleLoader;
+export declare const loadImport: ModuleLoader;
+export declare const loadPackages: ModuleLoader;
+export declare const loadDaemon: ModuleLoader;
+export declare const loadRoutines: ModuleLoader;
+export declare const loadRun: ModuleLoader;
+export declare const loadDefaults: ModuleLoader;
+export declare const loadModels: ModuleLoader;
+export declare const loadPrune: ModuleLoader;
+export declare const loadTrash: ModuleLoader;
+export declare const loadRestore: ModuleLoader;
+export declare const loadDoctor: ModuleLoader;
+export declare const loadProfiles: ModuleLoader;
+export declare const loadSecrets: ModuleLoader;
+export declare const loadWallet: ModuleLoader;
+export declare const loadHelper: ModuleLoader;
+export declare const loadMenubar: ModuleLoader;
+export declare const loadBeta: ModuleLoader;
+export declare const loadSync: ModuleLoader;
+export declare const loadRefreshRules: ModuleLoader;
+export declare const loadDrive: ModuleLoader;
+export declare const loadFactory: ModuleLoader;
+export declare const loadUsage: ModuleLoader;
+export declare const loadCost: ModuleLoader;
+export declare const loadBudget: ModuleLoader;
+export declare const loadAlias: ModuleLoader;
+export declare const loadPty: ModuleLoader;
+export declare const loadTmux: ModuleLoader;
+export declare const loadBrowser: ModuleLoader;
+export declare const loadComputer: ModuleLoader;
+export declare const loadPull: ModuleLoader;
+export declare const loadPush: ModuleLoader;
+export declare const loadRepo: ModuleLoader;
+export declare const loadSetup: ModuleLoader;
+export declare const loadSessions: ModuleLoader;
+export declare const loadTeams: ModuleLoader;
+export declare const loadCloud: ModuleLoader;
+/**
+ * Commands whose modules pull in the SQLite-backed session/cloud stack. They are
+ * registered AFTER `applyGlobalHelpConventions` (mirroring main's order: help
+ * conventions at module top-level, lazy registration just before parse), so they
+ * inherit the root's custom help formatter rather than getting the per-command
+ * recursive pass. Keeping that ordering preserves their `--help` output exactly.
+ */
+export declare const LAZY_COMMAND_NAMES: ReadonlySet<string>;
+/**
+ * User-typed top-level command name -> ordered list of module loaders to run.
+ *
+ * Most names map to a single loader. The exceptions encode real coupling on main:
+ *  - `add`/`use`/`list`/`remove`/`rm`/`purge` all come from the versions module.
+ *  - `registry`/`search`/`install` all come from the packages module.
+ *  - `trash` and `restore` are separate registrars in the trash module.
+ *  - `prune` needs versions FIRST (it creates `prune <specs...>`) then prune.js
+ *    (which finds that command and attaches the `cleanup` subcommand).
+ *
+ * Inline deprecated aliases (memory/perms/exec/jobs/cron) and the inline
+ * `upgrade` command are NOT here — they are closures over entry-point state and
+ * are handled directly in src/index.ts.
+ */
+export declare const COMMAND_LOADERS: Record<string, ModuleLoader[]>;

package/dist/lib/startup/command-registry.js

@@ -0,0 +1,136 @@
+// One loader per command module. Each dynamically imports the module and hands
+// back its register function. Kept as named consts so src/index.ts can compose
+// them into the exact main-branch registration order for the slow path.
+export const loadView = async () => (await import('../../commands/view.js')).registerViewCommand;
+export const loadInspect = async () => (await import('../../commands/inspect.js')).registerInspectCommand;
+export const loadFeedback = async () => (await import('../../commands/feedback.js')).registerFeedbackCommand;
+export const loadCommands = async () => (await import('../../commands/commands.js')).registerCommandsCommands;
+export const loadHooks = async () => (await import('../../commands/hooks.js')).registerHooksCommands;
+export const loadSkills = async () => (await import('../../commands/skills.js')).registerSkillsCommands;
+export const loadRules = async () => (await import('../../commands/rules.js')).registerRulesCommands;
+export const loadPermissions = async () => (await import('../../commands/permissions.js')).registerPermissionsCommands;
+export const loadMcp = async () => (await import('../../commands/mcp.js')).registerMcpCommands;
+export const loadCli = async () => (await import('../../commands/cli.js')).registerCliCommands;
+export const loadSubagents = async () => (await import('../../commands/subagents.js')).registerSubagentsCommands;
+export const loadPlugins = async () => (await import('../../commands/plugins.js')).registerPluginsCommands;
+export const loadWorkflows = async () => (await import('../../commands/workflows.js')).registerWorkflowsCommands;
+export const loadWorktree = async () => (await import('../../commands/worktree.js')).registerWorktreeCommands;
+export const loadVersions = async () => (await import('../../commands/versions.js')).registerVersionsCommands;
+export const loadImport = async () => (await import('../../commands/import.js')).registerImportCommand;
+export const loadPackages = async () => (await import('../../commands/packages.js')).registerPackagesCommands;
+export const loadDaemon = async () => (await import('../../commands/daemon.js')).registerDaemonCommands;
+export const loadRoutines = async () => (await import('../../commands/routines.js')).registerRoutinesCommands;
+export const loadRun = async () => (await import('../../commands/exec.js')).registerRunCommand;
+export const loadDefaults = async () => (await import('../../commands/defaults.js')).registerDefaultsCommands;
+export const loadModels = async () => (await import('../../commands/models.js')).registerModelsCommand;
+export const loadPrune = async () => (await import('../../commands/prune.js')).registerPruneCommand;
+export const loadTrash = async () => (await import('../../commands/trash.js')).registerTrashCommands;
+export const loadRestore = async () => (await import('../../commands/trash.js')).registerRestoreCommand;
+export const loadDoctor = async () => (await import('../../commands/doctor.js')).registerDoctorCommand;
+export const loadProfiles = async () => (await import('../../commands/profiles.js')).registerProfilesCommands;
+export const loadSecrets = async () => (await import('../../commands/secrets.js')).registerSecretsCommands;
+export const loadWallet = async () => (await import('../../commands/wallet.js')).registerWalletCommands;
+export const loadHelper = async () => (await import('../../commands/helper.js')).registerHelperCommand;
+export const loadMenubar = async () => (await import('../../commands/menubar.js')).registerMenubarCommands;
+export const loadBeta = async () => (await import('../../commands/beta.js')).registerBetaCommands;
+export const loadSync = async () => (await import('../../commands/sync.js')).registerSyncCommand;
+export const loadRefreshRules = async () => (await import('../../commands/refresh-rules.js')).registerRefreshRulesCommand;
+export const loadDrive = async () => (await import('../../commands/drive.js')).registerDriveCommands;
+export const loadFactory = async () => (await import('../../commands/factory.js')).registerFactoryCommands;
+export const loadUsage = async () => (await import('../../commands/usage.js')).registerUsageCommand;
+export const loadCost = async () => (await import('../../commands/cost.js')).registerCostCommand;
+export const loadBudget = async () => (await import('../../commands/budget.js')).registerBudgetCommand;
+export const loadAlias = async () => (await import('../../commands/alias.js')).registerAliasCommand;
+export const loadPty = async () => (await import('../../commands/pty.js')).registerPtyCommands;
+export const loadTmux = async () => (await import('../../commands/tmux.js')).registerTmuxCommands;
+export const loadBrowser = async () => (await import('../../commands/browser.js')).registerBrowserCommand;
+export const loadComputer = async () => (await import('../../commands/computer.js')).registerComputerCommand;
+export const loadPull = async () => (await import('../../commands/pull.js')).registerPullCommand;
+export const loadPush = async () => (await import('../../commands/push.js')).registerPushCommand;
+export const loadRepo = async () => (await import('../../commands/repo.js')).registerRepoCommands;
+export const loadSetup = async () => (await import('../../commands/setup.js')).registerSetupCommand;
+export const loadSessions = async () => (await import('../../commands/sessions.js')).registerSessionsCommands;
+export const loadTeams = async () => (await import('../../commands/teams.js')).registerTeamsCommands;
+export const loadCloud = async () => (await import('../../commands/cloud.js')).registerCloudCommands;
+/**
+ * Commands whose modules pull in the SQLite-backed session/cloud stack. They are
+ * registered AFTER `applyGlobalHelpConventions` (mirroring main's order: help
+ * conventions at module top-level, lazy registration just before parse), so they
+ * inherit the root's custom help formatter rather than getting the per-command
+ * recursive pass. Keeping that ordering preserves their `--help` output exactly.
+ */
+export const LAZY_COMMAND_NAMES = new Set(['sessions', 'teams', 'cloud']);
+/**
+ * User-typed top-level command name -> ordered list of module loaders to run.
+ *
+ * Most names map to a single loader. The exceptions encode real coupling on main:
+ *  - `add`/`use`/`list`/`remove`/`rm`/`purge` all come from the versions module.
+ *  - `registry`/`search`/`install` all come from the packages module.
+ *  - `trash` and `restore` are separate registrars in the trash module.
+ *  - `prune` needs versions FIRST (it creates `prune <specs...>`) then prune.js
+ *    (which finds that command and attaches the `cleanup` subcommand).
+ *
+ * Inline deprecated aliases (memory/perms/exec/jobs/cron) and the inline
+ * `upgrade` command are NOT here — they are closures over entry-point state and
+ * are handled directly in src/index.ts.
+ */
+export const COMMAND_LOADERS = {
+    view: [loadView],
+    inspect: [loadInspect],
+    feedback: [loadFeedback],
+    commands: [loadCommands],
+    hooks: [loadHooks],
+    skills: [loadSkills],
+    rules: [loadRules],
+    permissions: [loadPermissions],
+    mcp: [loadMcp],
+    cli: [loadCli],
+    subagents: [loadSubagents],
+    plugins: [loadPlugins],
+    workflows: [loadWorkflows],
+    worktree: [loadWorktree],
+    add: [loadVersions],
+    use: [loadVersions],
+    list: [loadVersions],
+    remove: [loadVersions],
+    rm: [loadVersions],
+    purge: [loadVersions],
+    prune: [loadVersions, loadPrune],
+    import: [loadImport],
+    registry: [loadPackages],
+    search: [loadPackages],
+    install: [loadPackages],
+    daemon: [loadDaemon],
+    routines: [loadRoutines],
+    run: [loadRun],
+    defaults: [loadDefaults],
+    models: [loadModels],
+    trash: [loadTrash],
+    restore: [loadRestore],
+    doctor: [loadDoctor],
+    profiles: [loadProfiles],
+    secrets: [loadSecrets],
+    wallet: [loadWallet],
+    helper: [loadHelper],
+    menubar: [loadMenubar],
+    beta: [loadBeta],
+    sync: [loadSync],
+    'refresh-rules': [loadRefreshRules],
+    drive: [loadDrive],
+    factory: [loadFactory],
+    usage: [loadUsage],
+    cost: [loadCost],
+    budget: [loadBudget],
+    alias: [loadAlias],
+    pty: [loadPty],
+    tmux: [loadTmux],
+    browser: [loadBrowser],
+    computer: [loadComputer],
+    pull: [loadPull],
+    push: [loadPush],
+    repo: [loadRepo],
+    setup: [loadSetup],
+    sessions: [loadSessions],
+    teams: [loadTeams],
+    cloud: [loadCloud],
+};

package/dist/lib/types.d.ts

@@ -5,6 +5,7 @@
  * configuration schemas, resource tracking, registry types, and permission
  * formats for each supported agent.
  */
+import type { CloudProviderId } from './cloud/types.js';
 /** Unique identifier for a supported AI coding agent. */
 export type AgentId = 'claude' | 'codex' | 'gemini' | 'cursor' | 'opencode' | 'openclaw' | 'copilot' | 'amp' | 'kiro' | 'goose' | 'roo' | 'antigravity' | 'grok' | 'kimi' | 'droid';
 /** How `agents run <agent>` chooses an installed version when none is pinned. */
@@ -83,6 +84,13 @@ export interface AgentConfig {
     variableSyntax: string;
     supportsHooks: boolean;
     nativeAgentsSkillsDir?: boolean;
+    /**
+     * This agent's *own* cloud backend. `agents cloud run --agent <id>` routes
+     * here when no `--provider` is given (precedence: --provider > this >
+     * cloud.default_provider > rush). Undefined means the agent has no native
+     * cloud and falls back to the configured default.
+     */
+    cloudProvider?: CloudProviderId;
     capabilities: {
         hooks: Capability;
         mcp: Capability;

package/dist/lib/version.d.ts

@@ -5,3 +5,14 @@
  * get stale behavior without this check.
  */
 export declare function getCliVersion(): string;
+/**
+ * Read the version from package.json on disk every call, bypassing the cache.
+ *
+ * `getCliVersion()` memoizes the version a long-running process *started* with.
+ * After `npm i -g` overwrites the install in place, the on-disk package.json
+ * changes but the running process keeps its old in-memory code. Comparing this
+ * fresh read against the cached startup value is how a daemon/broker detects it
+ * is now stale and should reload onto the new code (self-healing). Returns
+ * 'unknown' on any error.
+ */
+export declare function getCliVersionFresh(): string;

package/dist/lib/version.js

@@ -23,3 +23,23 @@ export function getCliVersion() {
     }
     return cached;
 }
+/**
+ * Read the version from package.json on disk every call, bypassing the cache.
+ *
+ * `getCliVersion()` memoizes the version a long-running process *started* with.
+ * After `npm i -g` overwrites the install in place, the on-disk package.json
+ * changes but the running process keeps its old in-memory code. Comparing this
+ * fresh read against the cached startup value is how a daemon/broker detects it
+ * is now stale and should reload onto the new code (self-healing). Returns
+ * 'unknown' on any error.
+ */
+export function getCliVersionFresh() {
+    try {
+        const pkgPath = path.join(__dirname, '..', '..', 'package.json');
+        const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+        return String(pkg.version || 'unknown');
+    }
+    catch {
+        return 'unknown';
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phnx-labs/agents-cli",
-  "version": "1.20.21",
+  "version": "1.20.23",
   "description": "One CLI for all your AI coding agents - versions, config, cloud dispatch, sessions, and teams (now with first-class Grok Build CLI support)",
   "type": "module",
   "main": "dist/index.js",
@@ -25,6 +25,7 @@
     "dist/**/*.d.ts",
     "dist/**/*.json",
     "dist/lib/secrets/Agents CLI.app/**",
+    "dist/lib/menubar/MenubarHelper.app/**",
     "scripts/postinstall.js",
     "scripts/install-helper.js",
     "CHANGELOG.md",
@@ -43,8 +44,9 @@
     "url": "https://github.com/phnx-labs/agents-cli/issues"
   },
   "scripts": {
-    "build": "tsc && rm -rf 'dist/lib/secrets/AgentsKeychain.app' 'dist/lib/secrets/Agents CLI.app' && ([ \"$(uname)\" = \"Darwin\" ] && cp -R 'bin/Agents CLI.app' 'dist/lib/secrets/Agents CLI.app' || true)",
-    "prepack": "scripts/verify-keychain-helper.sh",
+    "build": "tsc && rm -rf 'dist/lib/secrets/AgentsKeychain.app' 'dist/lib/secrets/Agents CLI.app' 'dist/lib/menubar/MenubarHelper.app' && ([ \"$(uname)\" = \"Darwin\" ] && cp -R 'bin/Agents CLI.app' 'dist/lib/secrets/Agents CLI.app' || true) && ([ \"$(uname)\" = \"Darwin\" ] && [ -d 'bin/MenubarHelper.app' ] && mkdir -p 'dist/lib/menubar' && cp -R 'bin/MenubarHelper.app' 'dist/lib/menubar/MenubarHelper.app' || true)",
+    "build:bin": "scripts/build-bin.sh",
+    "prepack": "scripts/verify-keychain-helper.sh && scripts/verify-menubar-helper.sh",
     "postinstall": "node scripts/postinstall.js",
     "dev": "tsx src/index.ts",
     "start": "node dist/index.js",