@phnx-labs/agents-cli 1.20.21 → 1.20.23

package/dist/index.js

@@ -7,12 +7,15 @@
  */
 import { Command } from 'commander';
 import chalk from 'chalk';
-import ora from 'ora';
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
 import { fileURLToPath } from 'url';
-import { confirm, select } from '@inquirer/prompts';
+// `ora`, `@inquirer/prompts`, `./commands/utils.js`, and the agents/versions/shims
+// modules are imported dynamically at their use sites: they are needed only on
+// interactive / update / shim-repair paths, never for fast commands like
+// `--version`, `--help`, or `view`. Keeping them off the module-eval path is
+// what gets cold starts under the target.
 // Force exit on Ctrl+C when no interactive prompt is handling it.
 process.on('SIGINT', () => process.exit(130));
 // Ignore SIGPIPE — prevents exit code 13 crashes in piped environments
@@ -23,7 +26,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>
@@ -54,58 +57,12 @@ if (IS_DEV_BUILD) {
     if (process.env.AGENTS_CLI_DISABLE_AUTO_UPDATE === undefined)
         process.env.AGENTS_CLI_DISABLE_AUTO_UPDATE = '1';
 }
-// Import command registrations
-import { registerPullCommand } from './commands/pull.js';
-import { registerPushCommand } from './commands/push.js';
-import { registerRepoCommands } from './commands/repo.js';
-import { registerSetupCommand, runSetup } from './commands/setup.js';
-import { registerFeedbackCommand } from './commands/feedback.js';
-import { registerViewCommand } from './commands/view.js';
-import { registerInspectCommand } from './commands/inspect.js';
-import { registerCommandsCommands } from './commands/commands.js';
-import { registerHooksCommands } from './commands/hooks.js';
-import { registerSkillsCommands } from './commands/skills.js';
-import { registerRulesCommands } from './commands/rules.js';
-import { registerPermissionsCommands } from './commands/permissions.js';
-import { registerMcpCommands } from './commands/mcp.js';
-import { registerCliCommands } from './commands/cli.js';
-import { registerVersionsCommands } from './commands/versions.js';
-import { registerImportCommand } from './commands/import.js';
-import { registerPackagesCommands } from './commands/packages.js';
-import { registerDaemonCommands } from './commands/daemon.js';
-import { registerRoutinesCommands } from './commands/routines.js';
-import { registerRunCommand } from './commands/exec.js';
-import { registerModelsCommand } from './commands/models.js';
-import { registerDefaultsCommands } from './commands/defaults.js';
-import { registerPruneCommand } from './commands/prune.js';
-import { registerTrashCommands, registerRestoreCommand } from './commands/trash.js';
-import { registerDoctorCommand } from './commands/doctor.js';
-import { registerSubagentsCommands } from './commands/subagents.js';
-import { registerPluginsCommands } from './commands/plugins.js';
-import { registerWorkflowsCommands } from './commands/workflows.js';
-import { registerWorktreeCommands } from './commands/worktree.js';
-import { registerSyncCommand } from './commands/sync.js';
-import { registerRefreshRulesCommand } from './commands/refresh-rules.js';
-import { registerDriveCommands } from './commands/drive.js';
-import { registerPtyCommands } from './commands/pty.js';
-import { registerTmuxCommands } from './commands/tmux.js';
-import { registerBrowserCommand } from './commands/browser.js';
-import { registerComputerCommand } from './commands/computer.js';
-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 { 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';
+// Command registration is lazy: instead of statically importing every command
+// module on each invocation (which loaded the whole ~50-module tree before the
+// first byte of output), the registry maps a command name to a thunk that
+// imports only what that command needs. See src/lib/startup/command-registry.ts.
+import { COMMAND_LOADERS, LAZY_COMMAND_NAMES, loadView, loadInspect, loadFeedback, loadCommands, loadHooks, loadSkills, loadRules, loadPermissions, loadMcp, loadCli, loadSubagents, loadPlugins, loadWorkflows, loadWorktree, loadVersions, loadImport, loadPackages, loadDaemon, loadRoutines, loadRun, loadDefaults, loadModels, loadPrune, loadTrash, loadRestore, loadDoctor, loadProfiles, loadSecrets, loadWallet, loadHelper, loadMenubar, loadBeta, loadSync, loadRefreshRules, loadDrive, loadFactory, loadUsage, loadCost, loadBudget, loadAlias, loadPty, loadTmux, loadBrowser, loadComputer, loadPull, loadPush, loadRepo, loadSetup, } from './lib/startup/command-registry.js';
 import { applyGlobalHelpConventions } from './lib/help.js';
-import { isInteractiveTerminal, isPromptCancelled } from './commands/utils.js';
-import { AGENTS } from './lib/agents.js';
-import { getGlobalDefault, listInstalledVersions } from './lib/versions.js';
-import { addShimsToPath, ensureShimCurrent, ensureVersionedAliasCurrent, getPathShadowingExecutable, getPathSetupInstructions, getShimsDir, isShimsInPath, listAgentsWithInstalledVersions, removeLegacyUserShim, } from './lib/shims.js';
 import { IS_WINDOWS } from './lib/platform/index.js';
 // Transparent shim delegate: the generated Windows `.cmd` shims invoke
 // `agents __shim <agent>[@version] <raw args>`. Intercept here, before commander
@@ -347,8 +304,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
@@ -372,6 +338,9 @@ async function installResolvedPackage(metadata) {
 }
 /** Present an interactive upgrade prompt (TTY) or a one-line hint (non-TTY). */
 async function promptUpgrade(latestVersion) {
+    const { default: ora } = await import('ora');
+    const { confirm, select } = await import('@inquirer/prompts');
+    const { isInteractiveTerminal, isPromptCancelled } = await import('./commands/utils.js');
     if (!isInteractiveTerminal()) {
         console.error(chalk.yellow(`Update available: ${VERSION} -> ${latestVersion}. Run: agents upgrade --yes`));
         return;
@@ -470,6 +439,7 @@ async function checkForUpdates() {
             await promptUpgrade(cache.latestVersion);
         }
         catch (err) {
+            const { isPromptCancelled } = await import('./commands/utils.js');
             if (isPromptCancelled(err))
                 return;
             /* prompt error, ignore */
@@ -490,6 +460,13 @@ async function maybeBootstrapShimIntegration(requestedCommand, helpOrVersionRequ
     if (requestedCommand === 'sync' || requestedCommand === 'refresh-rules') {
         return;
     }
+    // Past the documentation/non-TTY guards: only now load the shim + agent
+    // tables this interactive repair flow needs, so fast commands never pay for
+    // them at module-eval time.
+    const { confirm } = await import('@inquirer/prompts');
+    const { AGENTS } = await import('./lib/agents.js');
+    const { getGlobalDefault, listInstalledVersions } = await import('./lib/versions.js');
+    const { addShimsToPath, ensureShimCurrent, ensureVersionedAliasCurrent, getPathShadowingExecutable, getPathSetupInstructions, getShimsDir, isShimsInPath, listAgentsWithInstalledVersions, removeLegacyUserShim, } = await import('./lib/shims.js');
     const installedAgents = listAgentsWithInstalledVersions();
     if (installedAgents.length === 0) {
         return;
@@ -611,87 +588,50 @@ async function maybeBootstrapShimIntegration(requestedCommand, helpOrVersionRequ
     }
     catch { /* best-effort */ }
 }
-// Register all commands
-registerViewCommand(program);
-registerInspectCommand(program);
-registerFeedbackCommand(program);
-registerCommandsCommands(program);
-registerHooksCommands(program);
-registerSkillsCommands(program);
-registerRulesCommands(program);
-// Deprecated 'memory' command - hard error, force users to use 'rules'
-program
-    .command('memory', { hidden: true })
-    .allowUnknownOption()
-    .allowExcessArguments()
-    .action(() => {
-    console.error(chalk.red('"agents memory" has been renamed to "agents rules".'));
-    console.error(chalk.gray('Run "agents rules --help" for usage.\n'));
-    process.exit(1);
-});
-registerPermissionsCommands(program);
-// Deprecated 'perms' alias for 'permissions'
-program
-    .command('perms', { hidden: true })
-    .allowUnknownOption()
-    .allowExcessArguments()
-    .action(async (opts, cmd) => {
-    console.log(chalk.yellow('Deprecated: Use "agents permissions" instead of "agents perms"\n'));
-    // Re-parse with 'permissions' command
-    const args = process.argv.slice(2);
-    args[0] = 'permissions';
-    await program.parseAsync(['node', 'agents', ...args]);
-});
-registerMcpCommands(program);
-registerCliCommands(program);
-registerSubagentsCommands(program);
-registerPluginsCommands(program);
-registerWorkflowsCommands(program);
-registerWorktreeCommands(program);
-registerVersionsCommands(program);
-registerImportCommand(program);
-registerPackagesCommands(program);
-registerDaemonCommands(program);
-registerRoutinesCommands(program);
-registerRunCommand(program);
-registerDefaultsCommands(program);
-registerModelsCommand(program);
-registerPruneCommand(program);
-registerTrashCommands(program);
-registerRestoreCommand(program);
-registerDoctorCommand(program);
-// Deprecated 'exec' alias for 'run'
-program
-    .command('exec', { hidden: true })
-    .allowUnknownOption()
-    .allowExcessArguments()
-    .action(async () => {
-    console.log(chalk.yellow('Deprecated: Use "agents run" instead of "agents exec"\n'));
-    const args = process.argv.slice(2);
-    args[0] = 'run';
-    await program.parseAsync(['node', 'agents', ...args]);
-});
-registerProfilesCommands(program);
-registerSecretsCommands(program);
-registerWalletCommands(program);
-registerHelperCommand(program);
-registerBetaCommands(program);
-registerSyncCommand(program);
-registerRefreshRulesCommand(program);
-registerDriveCommands(program);
-registerFactoryCommands(program);
-registerUsageCommand(program);
-registerCostCommand(program);
-registerBudgetCommand(program);
-registerAliasCommand(program);
-registerPtyCommands(program);
-registerTmuxCommands(program);
-registerBrowserCommand(program);
-registerComputerCommand(program);
-// Deprecated 'jobs' and 'cron' aliases for 'routines'
-for (const alias of ['jobs', 'cron']) {
-    program
-        .command(alias, { hidden: true })
+// --- Inline command registrars ----------------------------------------------
+// These commands are defined here rather than in a command module because they
+// close over entry-point-local state (program re-parsing, VERSION, the npm
+// upgrade helpers). The lazy registrar and the all-commands fallback below both
+// call them, so the behavior is identical to the old eager registration.
+/** Deprecated `memory` command — hard error pointing users at `rules`. */
+function registerMemoryCommand(p) {
+    p.command('memory', { hidden: true })
+        .allowUnknownOption()
+        .allowExcessArguments()
+        .action(() => {
+        console.error(chalk.red('"agents memory" has been renamed to "agents rules".'));
+        console.error(chalk.gray('Run "agents rules --help" for usage.\n'));
+        process.exit(1);
+    });
+}
+/** Deprecated `perms` alias — re-parses as `permissions`. */
+function registerPermsAliasCommand(p) {
+    p.command('perms', { hidden: true })
+        .allowUnknownOption()
+        .allowExcessArguments()
+        .action(async () => {
+        console.log(chalk.yellow('Deprecated: Use "agents permissions" instead of "agents perms"\n'));
+        // Re-parse with 'permissions' command
+        const args = process.argv.slice(2);
+        args[0] = 'permissions';
+        await program.parseAsync(['node', 'agents', ...args]);
+    });
+}
+/** Deprecated `exec` alias — re-parses as `run`. */
+function registerExecAliasCommand(p) {
+    p.command('exec', { hidden: true })
+        .allowUnknownOption()
+        .allowExcessArguments()
+        .action(async () => {
+        console.log(chalk.yellow('Deprecated: Use "agents run" instead of "agents exec"\n'));
+        const args = process.argv.slice(2);
+        args[0] = 'run';
+        await program.parseAsync(['node', 'agents', ...args]);
+    });
+}
+/** Deprecated `jobs` / `cron` aliases — re-parse as `routines`. */
+function registerJobsCronAliasCommand(p, alias) {
+    p.command(alias, { hidden: true })
         .allowUnknownOption()
         .allowExcessArguments()
         .action(async () => {
@@ -701,60 +641,166 @@ for (const alias of ['jobs', 'cron']) {
         await program.parseAsync(['node', 'agents', ...args]);
     });
 }
-program
-    .command('upgrade')
-    .description('Upgrade agents-cli to the latest version (or a specific [version])')
-    .argument('[version]', 'Target version or dist-tag to install (default: latest)')
-    .option('-y, --yes', 'Install without an interactive confirmation prompt')
-    .action(async (version, options) => {
-    const target = version ?? 'latest';
-    let spinner = ora(version ? `Resolving ${NPM_PACKAGE_NAME}@${target}...` : 'Checking for updates...').start();
-    try {
-        const metadata = await fetchNpmPackageMetadata(target);
-        const resolvedVersion = metadata.version;
-        if (resolvedVersion === VERSION) {
-            spinner.succeed(`Already on ${VERSION}`);
-            return;
-        }
-        // For `latest` (no explicit version) skip when already ahead. When a
-        // version is named explicitly, honor it even if it's a downgrade.
-        if (!version && compareVersions(resolvedVersion, VERSION) <= 0) {
-            spinner.succeed(`Already ahead of latest (${VERSION} >= ${resolvedVersion})`);
-            return;
-        }
-        const direction = compareVersions(resolvedVersion, VERSION) < 0 ? 'Downgrade' : 'Upgrade';
-        spinner.succeed(`Resolved ${NPM_PACKAGE_NAME}@${resolvedVersion}`);
-        printResolvedPackage(metadata);
-        if (isInteractiveTerminal() && !options.yes) {
-            const approved = await confirm({
-                message: `Install ${NPM_PACKAGE_NAME}@${resolvedVersion}?`,
-                default: false,
-            });
-            if (!approved) {
-                console.log(chalk.gray('Upgrade cancelled'));
+/** Self-upgrade command (`agents upgrade [version]`). */
+function registerUpgradeCommand(p) {
+    p.command('upgrade')
+        .description('Upgrade agents-cli to the latest version (or a specific [version])')
+        .argument('[version]', 'Target version or dist-tag to install (default: latest)')
+        .option('-y, --yes', 'Install without an interactive confirmation prompt')
+        .action(async (version, options) => {
+        const { default: ora } = await import('ora');
+        const { confirm } = await import('@inquirer/prompts');
+        const { isInteractiveTerminal, isPromptCancelled } = await import('./commands/utils.js');
+        const target = version ?? 'latest';
+        let spinner = ora(version ? `Resolving ${NPM_PACKAGE_NAME}@${target}...` : 'Checking for updates...').start();
+        try {
+            const metadata = await fetchNpmPackageMetadata(target);
+            const resolvedVersion = metadata.version;
+            if (resolvedVersion === VERSION) {
+                spinner.succeed(`Already on ${VERSION}`);
                 return;
             }
+            // For `latest` (no explicit version) skip when already ahead. When a
+            // version is named explicitly, honor it even if it's a downgrade.
+            if (!version && compareVersions(resolvedVersion, VERSION) <= 0) {
+                spinner.succeed(`Already ahead of latest (${VERSION} >= ${resolvedVersion})`);
+                return;
+            }
+            const direction = compareVersions(resolvedVersion, VERSION) < 0 ? 'Downgrade' : 'Upgrade';
+            spinner.succeed(`Resolved ${NPM_PACKAGE_NAME}@${resolvedVersion}`);
+            printResolvedPackage(metadata);
+            if (isInteractiveTerminal() && !options.yes) {
+                const approved = await confirm({
+                    message: `Install ${NPM_PACKAGE_NAME}@${resolvedVersion}?`,
+                    default: false,
+                });
+                if (!approved) {
+                    console.log(chalk.gray('Upgrade cancelled'));
+                    return;
+                }
+            }
+            spinner = ora(`${direction === 'Downgrade' ? 'Downgrading' : 'Upgrading'} ${VERSION} -> ${resolvedVersion}...`).start();
+            await installResolvedPackage(metadata);
+            spinner.succeed(`${direction}d to ${resolvedVersion}`);
+            // Only show the changelog for a genuine upgrade range.
+            if (compareVersions(resolvedVersion, VERSION) > 0) {
+                await showWhatsNew(VERSION, resolvedVersion);
+            }
         }
-        spinner = ora(`${direction === 'Downgrade' ? 'Downgrading' : 'Upgrading'} ${VERSION} -> ${resolvedVersion}...`).start();
-        await installResolvedPackage(metadata);
-        spinner.succeed(`${direction}d to ${resolvedVersion}`);
-        // Only show the changelog for a genuine upgrade range.
-        if (compareVersions(resolvedVersion, VERSION) > 0) {
-            await showWhatsNew(VERSION, resolvedVersion);
+        catch (err) {
+            if (isPromptCancelled(err))
+                return;
+            spinner.fail(`Upgrade failed: ${err instanceof Error ? err.message : String(err)}`);
+            console.log(chalk.gray(`Run manually: agents upgrade ${version ? version + ' ' : ''}--yes`));
         }
-    }
-    catch (err) {
-        if (isPromptCancelled(err))
-            return;
-        spinner.fail(`Upgrade failed: ${err instanceof Error ? err.message : String(err)}`);
-        console.log(chalk.gray(`Run manually: agents upgrade ${version ? version + ' ' : ''}--yes`));
-    }
-});
-registerPullCommand(program);
-registerPushCommand(program);
-registerRepoCommands(program);
-registerSetupCommand(program);
-applyGlobalHelpConventions(program);
+    });
+}
+// --- Lazy registration orchestration -----------------------------------------
+/** Import a command module via its loader and register it on the program. */
+async function reg(loader) {
+    (await loader())(program);
+}
+/**
+ * Register exactly the command(s) the requested top-level name needs.
+ * Returns false when the name maps to no known command (typo / unknown) so the
+ * caller can fall back to registering everything for spellcheck.
+ *
+ * Lazy commands (sessions/teams/cloud) are intentionally NOT handled here — they
+ * must register after applyGlobalHelpConventions to match main's ordering.
+ */
+async function registerEagerForRequest(name) {
+    switch (name) {
+        case 'memory':
+            registerMemoryCommand(program);
+            return true;
+        case 'perms':
+            // The action re-parses as `permissions`, so that target must exist too.
+            registerPermsAliasCommand(program);
+            await reg(loadPermissions);
+            return true;
+        case 'exec':
+            registerExecAliasCommand(program);
+            await reg(loadRun);
+            return true;
+        case 'jobs':
+        case 'cron':
+            registerJobsCronAliasCommand(program, name);
+            await reg(loadRoutines);
+            return true;
+        case 'upgrade':
+            registerUpgradeCommand(program);
+            return true;
+    }
+    const loaders = COMMAND_LOADERS[name];
+    if (!loaders)
+        return false;
+    for (const loader of loaders)
+        await reg(loader);
+    return true;
+}
+/**
+ * Register every command in the EXACT order main does (old src/index.ts lines
+ * 691-844), including the inline deprecated aliases. Used only on the slow paths
+ * (unknown command spellcheck, "did you mean" auto-correct) where the full set
+ * of names — and their registration order, which breaks ties in the suggestion
+ * picker — must match main byte-for-byte.
+ */
+async function registerAllEagerCommands() {
+    await reg(loadView);
+    await reg(loadInspect);
+    await reg(loadFeedback);
+    await reg(loadCommands);
+    await reg(loadHooks);
+    await reg(loadSkills);
+    await reg(loadRules);
+    registerMemoryCommand(program);
+    await reg(loadPermissions);
+    registerPermsAliasCommand(program);
+    await reg(loadMcp);
+    await reg(loadCli);
+    await reg(loadSubagents);
+    await reg(loadPlugins);
+    await reg(loadWorkflows);
+    await reg(loadWorktree);
+    await reg(loadVersions);
+    await reg(loadImport);
+    await reg(loadPackages);
+    await reg(loadDaemon);
+    await reg(loadRoutines);
+    await reg(loadRun);
+    await reg(loadDefaults);
+    await reg(loadModels);
+    await reg(loadPrune);
+    await reg(loadTrash);
+    await reg(loadRestore);
+    await reg(loadDoctor);
+    registerExecAliasCommand(program);
+    await reg(loadProfiles);
+    await reg(loadSecrets);
+    await reg(loadWallet);
+    await reg(loadHelper);
+    await reg(loadMenubar);
+    await reg(loadBeta);
+    await reg(loadSync);
+    await reg(loadRefreshRules);
+    await reg(loadDrive);
+    await reg(loadFactory);
+    await reg(loadUsage);
+    await reg(loadCost);
+    await reg(loadBudget);
+    await reg(loadAlias);
+    await reg(loadPty);
+    await reg(loadTmux);
+    await reg(loadBrowser);
+    await reg(loadComputer);
+    registerJobsCronAliasCommand(program, 'jobs');
+    registerJobsCronAliasCommand(program, 'cron');
+    registerUpgradeCommand(program);
+    await reg(loadPull);
+    await reg(loadPush);
+    await reg(loadRepo);
+    await reg(loadSetup);
+}
 /** Calculate the Levenshtein edit distance between two strings. */
 function levenshtein(a, b) {
     const m = a.length;
@@ -801,45 +847,54 @@ program.on('command:*', (operands) => {
     }
     process.exit(1);
 });
-// Run update check on EVERY invocation before parsing
-await checkForUpdates();
-// Surface any "behind upstream" notices from the previous detached sync, then
-// fire-and-forget the next background sync. System repo gets a real fast-forward
-// pull (read-only locally, safe). User repo and extras get fetch-only + a
-// status marker that we'll print on the *next* invocation.
-const { spawnDetachedSync } = await import('./lib/auto-pull.js');
-spawnDetachedSync();
-// First-run experience: no args + no config yet + TTY -> launch interactive setup.
-// Skipped when stdin/stdout isn't a terminal (CI, pipes) or when user passes any args.
+// Parse the invocation shape up front: the first non-flag token is the command,
+// and the doc flags (--version/--help/-h) drive both the registration strategy
+// and whether the update check + background sync run at all.
 const passedArgs = process.argv.slice(2);
 const requestedCommand = passedArgs.find((arg) => !arg.startsWith('-'));
-/**
- * Lazily register command trees that pull in the SQLite-backed session/cloud
- * stack. This keeps lightweight commands like `agents view` from loading the
- * DB layer during CLI startup.
- */
-async function registerLazyCommands() {
-    switch (requestedCommand) {
-        case 'sessions': {
-            const { registerSessionsCommands } = await import('./commands/sessions.js');
-            registerSessionsCommands(program);
-            break;
-        }
-        case 'teams': {
-            const { registerTeamsCommands } = await import('./commands/teams.js');
-            registerTeamsCommands(program);
-            break;
-        }
-        case 'cloud': {
-            const { registerCloudCommands } = await import('./commands/cloud.js');
-            registerCloudCommands(program);
-            break;
-        }
-        default:
-            break;
+// Help and version output are pure documentation — they must never gate on
+// setup, otherwise `agents <cmd> --help` becomes useless on a fresh box.
+const helpOrVersionRequested = passedArgs.some((arg) => arg === '--help' || arg === '-h' || arg === '--version' || arg === '-V');
+// Register only the command(s) this invocation actually uses. Lazy commands
+// (sessions/teams/cloud) are handled after applyGlobalHelpConventions below.
+const isLazyRequest = requestedCommand !== undefined && LAZY_COMMAND_NAMES.has(requestedCommand);
+if (requestedCommand !== undefined && !isLazyRequest) {
+    const known = await registerEagerForRequest(requestedCommand);
+    if (!known) {
+        // Unknown top-level command: register the full tree so the "did you mean"
+        // spellcheck and edit-distance-1 auto-correct (the command:* handler above)
+        // see the same candidate set — and ordering — as main.
+        await registerAllEagerCommands();
     }
 }
-await registerLazyCommands();
+// When requestedCommand is undefined (bare invocation, --version, --help, -h) no
+// command modules are needed: --version is built in and the root help text is a
+// static string.
+// Mirror main: help conventions are applied after the eager command tree and
+// before the lazy commands, so the latter inherit the root's custom help
+// formatter instead of getting the per-command recursive pass.
+applyGlobalHelpConventions(program);
+// Lazy commands pull in the SQLite-backed session/cloud stack; register them
+// only when explicitly requested, keeping lightweight commands off that path.
+if (isLazyRequest) {
+    for (const loader of COMMAND_LOADERS[requestedCommand])
+        await reg(loader);
+}
+// Pure documentation paths (--version / --help / -h) return immediately: skip
+// the update check (PATH scan + cache read) and the detached background sync
+// (spawns a child process) that every other invocation runs.
+if (!helpOrVersionRequested) {
+    // Run update check before parsing so the upgrade notice/prompt precedes output.
+    await checkForUpdates();
+    // Surface any "behind upstream" notices from the previous detached sync, then
+    // fire-and-forget the next background sync. System repo gets a real fast-forward
+    // pull (read-only locally, safe). User repo and extras get fetch-only + a
+    // status marker that we'll print on the *next* invocation.
+    const { spawnDetachedSync } = await import('./lib/auto-pull.js');
+    spawnDetachedSync();
+}
+// First-run experience: no args + no config yet + TTY -> launch interactive setup.
+// Skipped when stdin/stdout isn't a terminal (CI, pipes) or when user passes any args.
 const metaFilePath = path.join(getUserAgentsDir(), 'agents.yaml');
 const firstRun = passedArgs.length === 0 &&
     !fs.existsSync(metaFilePath) &&
@@ -847,6 +902,7 @@ const firstRun = passedArgs.length === 0 &&
     process.stdout.isTTY;
 if (firstRun) {
     try {
+        const { runSetup } = await import('./commands/setup.js');
         await runSetup(program);
     }
     catch (err) {
@@ -859,9 +915,6 @@ if (firstRun) {
 // Every command requires the system repo to be cloned first. `setup` is the
 // only exemption — it's the command that does the cloning.
 const SETUP_EXEMPT_COMMANDS = new Set(['setup', 'help']);
-// Help and version output are pure documentation — they must never gate on
-// setup, otherwise `agents <cmd> --help` becomes useless on a fresh box.
-const helpOrVersionRequested = passedArgs.some((arg) => arg === '--help' || arg === '-h' || arg === '--version' || arg === '-V');
 // Fold legacy ~/.agents-system/ into ~/.agents/.system/ BEFORE ensureInitialized
 // runs. ensureInitialized checks for .git inside the new path; if the user is
 // upgrading from a layout where .git lives under the legacy path, the check
@@ -916,6 +969,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();