@phnx-labs/agents-cli 1.22.39 → 1.22.41

package/dist/bootstrap.js

@@ -53,18 +53,18 @@ if (IS_DEV_BUILD) {
 // 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.
+// imports only what that command needs. See src/cli/command-registry.ts.
 // Individual load* registrars are not imported here — registerEagerForRequest
 // and the lazy path pull them via COMMAND_LOADERS. The full-tree
 // registerAllEagerCommands path was removed (RUSH-2329): unknown/typo commands
 // spellcheck against KNOWN_TOP_LEVEL_COMMANDS and register only the corrected
 // name.
-import { COMMAND_LOADERS, LAZY_COMMAND_NAMES, KNOWN_TOP_LEVEL_COMMANDS, RETIRED_TOP_LEVEL_COMMANDS, } from './lib/startup/command-registry.js';
+import { COMMAND_LOADERS, LAZY_COMMAND_NAMES, KNOWN_TOP_LEVEL_COMMANDS, RETIRED_TOP_LEVEL_COMMANDS, } from './cli/command-registry.js';
 import { closestTopLevelCommand } from './lib/startup/spellcheck.js';
 import { applyGlobalHelpConventions } from './lib/help.js';
 import { renderWhatsNew } from './lib/whats-new.js';
 import { getCliLaunch } from './lib/cli-entry.js';
-import { emit, emitFriction, redactArgs } from './lib/events.js';
+import { emit, emitFriction, redactArgs } from './lib/feed/events.js';
 import { stampProvenance } from './lib/event-provenance.js';
 import { die } from './lib/format.js';
 // Leaf (zero imports). Gates the dynamic passthrough import so the ~187ms
@@ -244,7 +244,7 @@ Packages:
 
 Run and dispatch:
   run <agent|profile> [prompt]    Run an agent. Omit prompt for interactive mode.
-  config                          Configure run defaults, project root, and device options
+  config                          Configure run defaults, project root, device options, and spend caps (config budget)
   teams                           Coordinate multiple agents on shared work
   routines                        Run agents on a cron schedule (scheduler auto-starts)
   daemon                          Runtime status/control for the always-on daemon (secrets broker, browser IPC, scheduler)
@@ -258,22 +258,21 @@ Run and dispatch:
 
 Observe (read the fleet — no store merge; aliases point at the real readers):
   feed / inbox                    Needs-you inbox (open blocks waiting on you)
-  timeline                        Agent progress stream (= feed --filter updates)
-  roster                          Live agents (= sessions --active)
+  sessions --active               Live agents (who is running right now)
   events                          Unified ops + activity event trail
   audit                           Tamper-evident run-dispatch log (not events)
-  snapshot                        One-process inventory + active sessions poll
   status                          Sync/drift only (not the live fleet snapshot)
+  devices snapshot                One-process inventory + active sessions poll
 
-Credentials and profiles:
-  profile                         Activate resource profiles across skills, MCP, permissions, and secrets
-  profiles                        Bundles of (host CLI, endpoint, model, auth)
-  secrets                         Keychain-backed env bundles; use 'secrets exec <bundle> -- <cmd>' to inject into a subprocess
+Credentials:
+  harness                         Custom (host CLI + model + auth) harnesses; replaces former profiles command
+  secrets                         Keychain-backed env bundles; synced vault: secrets vault unlock|lock
+  accounts                        Provider credentials + native OAuth logout
 
 Diagnostics:
   doctor [agent[@version]]        Diagnose CLI availability, sync status, and resource divergence; --check for the CI drift gate
   usage [agent]                   Show rate-limit and quota usage per agent
-  insights                        How work looks — behaviour (default) or counter mix (insights mix)
+  insights                        How work looks — behaviour (default), mix, cost, and output
   perf                            Latency rollups (hooks, commands, runs) from the disposable perf warehouse
 
 Config sync:
@@ -337,7 +336,7 @@ async function showWhatsNew(fromVersion, toVersion) {
 const UPDATE_CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000; // 24 hours
 import { getUpdateCheckPath, getMigratedSentinelPath, getUserAgentsDir, getRuntimeStateDir } from './lib/state.js';
 import { resolveBrandName, disabledCommandsForActiveBrand } from './lib/brand.js';
-import { readUpdateCache, saveUpdateCheck, dismissUpdateVersion, shouldPromptUpgrade, resolveMultiInstallInventory, remediateStaleAgentsCliInstalls, resolveRunningPackageRoot, } from './lib/self-update.js';
+import { readUpdateCache, saveUpdateCheck, dismissUpdateVersion, shouldPromptUpgrade, resolveMultiInstallInventory, remediateStaleAgentsCliInstalls, resolveRunningPackageRoot, manualUninstallCommand, } from './lib/self-update.js';
 const UPDATE_CHECK_FILE = getUpdateCheckPath();
 // Beside the existing update-check cache (RUSH-2324): short-TTL memo of the
 // multi-install PATH scan so every ordinary CLI invocation does not re-walk
@@ -386,7 +385,19 @@ function maybeWarnMultiInstall() {
     for (const info of inventory) {
         console.error(chalk.gray(`  ${info.packageRoot}  ${info.version}  (${info.note})`));
     }
-    console.error(chalk.gray('Upgrades apply to the running copy. Purge npx-cache / legacy / pre-1.22.30 copies with: agents doctor --fix'));
+    // RUSH-2705/2713: only advertise `agents doctor --fix` for copies it will
+    // really delete. A duplicate --fix won't auto-purge (a healthy >=1.22.30 peer,
+    // OR a pre-1.22.30 copy left alone only because no fixed peer exists — the
+    // latter is genuinely vulnerable, not healthy) makes --fix a remedy that
+    // no-ops forever — name the manual removal command instead.
+    const peers = inventory.filter((info) => !info.running);
+    console.error(chalk.gray('Upgrades apply to the running copy.'));
+    if (peers.some((info) => info.autoPurgeable)) {
+        console.error(chalk.gray('Purge npx-cache / legacy / pre-1.22.30 copies with: agents doctor --fix'));
+    }
+    for (const peer of peers.filter((info) => !info.autoPurgeable)) {
+        console.error(chalk.gray(`Remove the ${peer.version} copy at ${peer.packageRoot} with: ${manualUninstallCommand(peer.packageRoot)}`));
+    }
     try {
         fs.mkdirSync(path.dirname(sentinel), { recursive: true });
         fs.writeFileSync(sentinel, key);
@@ -789,6 +800,13 @@ async function runUpgrade(version, options) {
             if (purge.failed.length > 0) {
                 console.log(chalk.yellow(`Could not purge ${purge.failed.length} stale install${purge.failed.length === 1 ? '' : 's'}; re-run agents doctor --fix.`));
             }
+            // RUSH-2705/2713: duplicates --fix won't auto-purge (a healthy
+            // >=1.22.30 peer, or a pre-1.22.30 copy with no fixed peer to fall back
+            // to — not healthy) — name the command that removes them instead of
+            // leaving a silent nag behind.
+            for (const u of purge.unresolved) {
+                console.log(chalk.gray(`Duplicate ${u.version} at ${u.packageRoot} left in place; remove it with: ${u.manualRemoveCommand}`));
+            }
         }
         catch {
             /* best-effort; upgrade already succeeded */
@@ -879,14 +897,14 @@ program.on('command:*', (operands) => {
     if (minDist === 1 && closest && !RETIRED_TOP_LEVEL_COMMANDS.has(unknown)) {
         const args = process.argv.slice(2);
         args[0] = closest;
-        // The typo'd name was unknown, so the top-level --host router (which ran
+        // The typo'd name was unknown, so the top-level --device router (which ran
         // before commander parsing, against the ORIGINAL name) could not have
         // routed it - it correctly fell through to reach this handler at all
         // (that fallthrough is this ticket's own fix). But falling through to a
         // plain local re-parse means a routing flag on a corrected REAL
-        // host-routable command (e.g. `docto --host box`, corrected to `doctor`)
+        // host-routable command (e.g. `docto --device box`, corrected to `doctor`)
         // silently ran LOCALLY instead of remotely, with no error - worse than
-        // the loud "does not support --host" this ticket replaced. Re-run the
+        // the loud "does not support --device" this ticket replaced. Re-run the
         // router with the CORRECTED name before falling through to local parse;
         // it already no-ops when no routing flag is present. RUSH-2022 review r2.
         void (async () => {
@@ -947,11 +965,11 @@ const helpOrVersionRequested = passedArgs.some((arg) => arg === '--help' || arg
 // the unbranded CLI, so all of this is a no-op there.
 const brandDisabled = disabledCommandsForActiveBrand();
 const requestedIsDisabled = requestedCommand !== undefined && brandDisabled.has(requestedCommand);
-// `--host` passthrough: run this invocation on a remote machine over SSH instead
+// `--device` passthrough: run this invocation on a remote machine over SSH instead
 // of locally. Handled before any local command registration / update check /
 // background sync — a remote run needs none of that. Only the allowlisted
 // read-only + config + teams commands route here; `run`/`sessions` are absent
-// from the table and fall through to their own richer `--host` handling below.
+// from the table and fall through to their own richer `--device` handling below.
 // `--help`/`--version` stay local (docs must work without a reachable host).
 //
 // RUSH-2374: gate the dynamic import on a routing flag actually being present.
@@ -1010,7 +1028,7 @@ else if (requestedIsUnknown && requestedCommand) {
         closest &&
         !requestedIsDisabled &&
         !RETIRED_TOP_LEVEL_COMMANDS.has(requestedCommand)) {
-        // Auto-correct: register ONLY the corrected command, then re-route --host
+        // Auto-correct: register ONLY the corrected command, then re-route --device
         // and reparse under the real name (RUSH-2329 + RUSH-2022 review r2).
         passedArgs[0] = closest;
         // Keep process.argv in sync for the command:* safety-net and any code that
@@ -1121,7 +1139,7 @@ if (!firstRun &&
 // Skipped for --help/--version (RUSH-2454): same pure-docs gate as fold, the
 // update check, background sync, ensureInitialized, and the menu-bar self-heal.
 // The sentinel check itself is pure fs and does not load migrate.js — only a
-// missing/stale sentinel pays for `await import('./lib/migrate.js')` (which
+// missing/stale sentinel pays for `await import('./lib/installations/migrate.js')` (which
 // pulls the hosts/routine/teams/daemon/menubar graph).
 if (process.env.AGENTS_SKIP_MIGRATION !== '1' && !helpOrVersionRequested) {
     try {
@@ -1130,7 +1148,7 @@ if (process.env.AGENTS_SKIP_MIGRATION !== '1' && !helpOrVersionRequested) {
         // Bumping the suffix re-runs migrations for every user; binary releases that
         // don't change the schema must NOT re-run (they would destroy user content
         // when migration steps overlap with user-authored paths). See issue #20.
-        const sentinelValue = 'v20';
+        const sentinelValue = 'v21';
         let needRun = true;
         try {
             if (fs.existsSync(sentinel) && fs.readFileSync(sentinel, 'utf-8').trim() === sentinelValue) {
@@ -1139,7 +1157,7 @@ if (process.env.AGENTS_SKIP_MIGRATION !== '1' && !helpOrVersionRequested) {
         }
         catch { /* best-effort — fall through to run */ }
         if (needRun) {
-            const { runMigration } = await import('./lib/migrate.js');
+            const { runMigration } = await import('./lib/installations/migrate.js');
             await runMigration();
             try {
                 fs.mkdirSync(path.dirname(sentinel), { recursive: true });
@@ -1199,10 +1217,10 @@ catch (err) {
             console.error(err.message);
             process.exit(1);
         }
-        // A --host targeting a password-auth device throws this from resolveHost.
-        // It carries an actionable message (switch to key auth);
-        // handling it here covers every resolveHost caller (run, teams,
-        // secrets --host) at the source instead of a catch at each call site.
+        // A --device targeting a password-auth device throws this from resolveHost.
+        // It carries an actionable message (switch to key auth / enroll as a host);
+        // handling it here covers every resolveHost caller (run, hosts check/rm,
+        // secrets --device) at the source instead of a catch at each call site.
         if (err.name === 'DeviceOffloadUnsupportedError') {
             console.error(err.message);
             process.exit(1);

package/dist/browser.js

@@ -3,8 +3,8 @@ import { Command } from 'commander';
 import { registerBrowserSubcommands } from './commands/browser.js';
 import { maybeRunStandaloneOnHost } from './lib/hosts/passthrough.js';
 async function main() {
-    // `browser … --host <box>` routes to a remote over SSH, exactly like
-    // `agents browser … --host <box>` does through index.ts. Standalone-only:
+    // `browser … --device <box>` routes to a remote over SSH, exactly like
+    // `agents browser … --device <box>` does through index.ts. Standalone-only:
     // this binary never enters index.ts, so without this the flag was dropped.
     if (await maybeRunStandaloneOnHost('browser')) {
         process.exit(process.exitCode ?? 0);

package/dist/cli/command-registry.d.ts

@@ -0,0 +1,135 @@
+/**
+ * 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 { Command } from 'commander';
+export { KNOWN_TOP_LEVEL_COMMANDS, RETIRED_TOP_LEVEL_COMMANDS } from '../lib/startup/command-registry.js';
+/** 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 loadMemory: 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 loadVersions: ModuleLoader;
+export declare const loadUpdate: ModuleLoader;
+export declare const loadImport: ModuleLoader;
+export declare const loadPackages: ModuleLoader;
+export declare const loadRoutines: ModuleLoader;
+export declare const loadMonitors: ModuleLoader;
+export declare const loadProjects: ModuleLoader;
+export declare const loadRun: ModuleLoader;
+export declare const loadOpen: ModuleLoader;
+export declare const loadReconnect: ModuleLoader;
+export declare const loadFork: ModuleLoader;
+export declare const loadConfig: ModuleLoader;
+export declare const loadModels: ModuleLoader;
+export declare const loadModes: ModuleLoader;
+export declare const loadPrune: ModuleLoader;
+export declare const loadTrash: ModuleLoader;
+export declare const loadRestore: ModuleLoader;
+export declare const loadDoctor: ModuleLoader;
+export declare const loadApply: ModuleLoader;
+export declare const loadStatus: ModuleLoader;
+export declare const loadRoute: ModuleLoader;
+export declare const loadHarness: ModuleLoader;
+export declare const loadSecrets: ModuleLoader;
+export declare const loadMenubar: ModuleLoader;
+export declare const loadBeta: ModuleLoader;
+export declare const loadSync: ModuleLoader;
+export declare const loadRefreshRules: ModuleLoader;
+export declare const loadFactory: ModuleLoader;
+export declare const loadUsage: ModuleLoader;
+export declare const loadInsights: ModuleLoader;
+export declare const loadPerf: ModuleLoader;
+export declare const loadTrends: ModuleLoader;
+export declare const loadAlias: ModuleLoader;
+export declare const loadPty: ModuleLoader;
+export declare const loadTmux: ModuleLoader;
+export declare const loadWatchdog: ModuleLoader;
+export declare const loadBrowser: ModuleLoader;
+export declare const loadComputer: ModuleLoader;
+export declare const loadLogs: ModuleLoader;
+export declare const loadEvents: ModuleLoader;
+export declare const loadSsh: ModuleLoader;
+export declare const loadRepo: ModuleLoader;
+export declare const loadSetup: ModuleLoader;
+export declare const loadUninstall: ModuleLoader;
+export declare const loadUpgrade: ModuleLoader;
+export declare const loadSessions: ModuleLoader;
+export declare const loadTeams: ModuleLoader;
+export declare const loadTickets: ModuleLoader;
+export declare const loadCloud: ModuleLoader;
+export declare const loadMessage: ModuleLoader;
+export declare const loadSend: ModuleLoader;
+export declare const loadFeed: ModuleLoader;
+export declare const loadMailboxes: ModuleLoader;
+export declare const loadServe: ModuleLoader;
+export declare const loadArtifacts: ModuleLoader;
+export declare const loadAudit: ModuleLoader;
+export declare const loadWebhooks: ModuleLoader;
+export declare const loadHumans: ModuleLoader;
+export declare const loadAccounts: ModuleLoader;
+export declare const loadDaemon: 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[]>;
+/**
+ * Register every module in {@link COMMAND_LOADERS} onto one fresh program and
+ * return it — the full public command tree, deduped by loader identity so a
+ * loader mapped to several names (e.g. `add`/`use`/`list` -> versions) runs once.
+ *
+ * Off the hot path only: the command-index generator (`scripts/gen-command-index.ts`)
+ * and the tests build the tree from this. Startup never calls it — src/index.ts
+ * registers just the one requested command via `registerEagerForRequest`. The
+ * inline aliases/tombstones ({@link INLINE_COMMAND_NAMES}) are NOT included: they
+ * are closures over entry-point state that src/index.ts registers directly.
+ */
+export declare function buildFullCommandTree(): Promise<Command>;

package/dist/cli/command-registry.js

@@ -0,0 +1,259 @@
+/**
+ * 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 { Command } from 'commander';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { configureRootCommand } from '../lib/startup/root-command.js';
+export { KNOWN_TOP_LEVEL_COMMANDS, RETIRED_TOP_LEVEL_COMMANDS } from '../lib/startup/command-registry.js';
+// 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 loadMemory = async () => (await import('../commands/memory.js')).registerMemoryCommands;
+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 loadVersions = async () => (await import('../commands/versions.js')).registerVersionsCommands;
+export const loadUpdate = async () => (await import('../commands/update.js')).registerUpdateCommand;
+export const loadImport = async () => (await import('../commands/import.js')).registerImportCommand;
+export const loadPackages = async () => (await import('../commands/packages.js')).registerPackagesCommands;
+export const loadRoutines = async () => (await import('../commands/routines.js')).registerRoutinesCommands;
+export const loadMonitors = async () => (await import('../commands/monitors.js')).registerMonitorsCommands;
+export const loadProjects = async () => (await import('../commands/projects.js')).registerProjectsCommands;
+export const loadRun = async () => (await import('../commands/exec.js')).registerRunCommand;
+export const loadOpen = async () => (await import('../commands/open.js')).registerOpenCommand;
+export const loadReconnect = async () => (await import('../commands/reconnect.js')).registerReconnectCommand;
+export const loadFork = async () => (await import('../commands/fork.js')).registerForkCommand;
+export const loadConfig = async () => (await import('../commands/config.js')).registerConfigCommand;
+export const loadModels = async () => (await import('../commands/models.js')).registerModelsCommand;
+export const loadModes = async () => (await import('../commands/modes.js')).registerModesCommand;
+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 loadApply = async () => (await import('../commands/apply.js')).registerApplyCommand;
+export const loadStatus = async () => (await import('../commands/status.js')).registerStatusCommand;
+export const loadRoute = async () => (await import('../commands/route.js')).registerRouteCommands;
+export const loadHarness = async () => (await import('../commands/harness.js')).registerHarnessCommands;
+export const loadSecrets = async () => (await import('../commands/secrets.js')).registerSecretsCommands;
+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 loadFactory = async () => (await import('../commands/factory.js')).registerFactoryCommands;
+export const loadUsage = async () => (await import('../commands/usage.js')).registerUsageCommand;
+export const loadInsights = async () => (await import('../commands/insights.js')).registerInsightsCommand;
+export const loadPerf = async () => (await import('../commands/perf.js')).registerPerfCommand;
+// Thin deprecated alias of `agents insights mix` — no second mix implementation.
+export const loadTrends = async () => (await import('../commands/trends.js')).registerTrendsCommand;
+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 loadWatchdog = async () => (await import('../commands/watchdog.js')).registerWatchdogCommand;
+export const loadBrowser = async () => (await import('../commands/browser.js')).registerBrowserCommand;
+export const loadComputer = async () => (await import('../commands/computer.js')).registerComputerCommand;
+export const loadLogs = async () => (await import('../commands/logs.js')).registerLogsCommand;
+export const loadEvents = async () => (await import('../commands/events.js')).registerEventsCommand;
+export const loadSsh = async () => (await import('../commands/ssh.js')).registerSshCommands;
+export const loadRepo = async () => (await import('../commands/repo.js')).registerRepoCommands;
+export const loadSetup = async () => (await import('../commands/setup.js')).registerSetupCommand;
+export const loadUninstall = async () => (await import('../commands/uninstall.js')).registerUninstallCommands;
+export const loadUpgrade = async () => (await import('../commands/upgrade.js')).registerUpgradeCommand;
+export const loadSessions = async () => (await import('../commands/sessions.js')).registerSessionsCommands;
+export const loadTeams = async () => (await import('../commands/teams.js')).registerTeamsCommands;
+export const loadTickets = async () => (await import('../commands/tickets.js')).registerTicketsCommand;
+export const loadCloud = async () => (await import('../commands/cloud.js')).registerCloudCommands;
+export const loadMessage = async () => (await import('../commands/message.js')).registerMessageCommand;
+export const loadSend = async () => (await import('../commands/send.js')).registerSendCommand;
+export const loadFeed = async () => (await import('../commands/feed.js')).registerFeedCommand;
+export const loadMailboxes = async () => (await import('../commands/mailboxes.js')).registerMailboxesCommand;
+export const loadServe = async () => (await import('../commands/serve.js')).registerServeCommand;
+// Registers the `artifacts` group (with `share` + `setup` under it) AND the
+// top-level `unshare` alias — see commands/artifacts.ts.
+export const loadArtifacts = async () => (await import('../commands/artifacts.js')).registerArtifactsCommands;
+export const loadAudit = async () => (await import('../commands/audit.js')).registerAuditCommands;
+export const loadWebhooks = async () => (await import('../commands/webhook.js')).registerWebhooksCommand;
+export const loadHumans = async () => (await import('../commands/humans.js')).registerHumansCommands;
+export const loadAccounts = async () => (await import('../commands/accounts.js')).registerAccountsCommand;
+export const loadDaemon = async () => (await import('../commands/daemon.js')).registerDaemonCommand;
+/**
+ * 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.
+ */
+// `roster` was a sessions --active alias — removed; use sessions --active.
+export const LAZY_COMMAND_NAMES = new Set([
+    'sessions',
+    'reconnect',
+    'teams',
+    'cloud',
+    'message',
+    'serve',
+]);
+/**
+ * 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 = {
+    accounts: [loadAccounts],
+    view: [loadView],
+    inspect: [loadInspect],
+    feedback: [loadFeedback],
+    commands: [loadCommands],
+    hooks: [loadHooks],
+    skills: [loadSkills],
+    rules: [loadRules],
+    memory: [loadMemory],
+    permissions: [loadPermissions],
+    mcp: [loadMcp],
+    clis: [loadCli],
+    subagents: [loadSubagents],
+    plugins: [loadPlugins],
+    workflows: [loadWorkflows],
+    add: [loadVersions],
+    use: [loadVersions],
+    list: [loadVersions],
+    remove: [loadVersions],
+    rm: [loadVersions],
+    purge: [loadVersions],
+    update: [loadUpdate],
+    prune: [loadVersions, loadPrune],
+    import: [loadImport],
+    registry: [loadPackages],
+    search: [loadPackages],
+    install: [loadPackages],
+    routines: [loadRoutines],
+    monitors: [loadMonitors],
+    projects: [loadProjects],
+    run: [loadRun],
+    open: [loadOpen],
+    reconnect: [loadReconnect],
+    fork: [loadFork],
+    config: [loadConfig],
+    models: [loadModels],
+    modes: [loadModes],
+    trash: [loadTrash],
+    restore: [loadRestore],
+    doctor: [loadDoctor],
+    apply: [loadApply],
+    status: [loadStatus],
+    route: [loadRoute],
+    harness: [loadHarness],
+    harnesses: [loadHarness],
+    secrets: [loadSecrets],
+    menubar: [loadMenubar],
+    beta: [loadBeta],
+    sync: [loadSync],
+    'refresh-rules': [loadRefreshRules],
+    factory: [loadFactory],
+    usage: [loadUsage],
+    insights: [loadInsights],
+    perf: [loadPerf],
+    trends: [loadTrends],
+    alias: [loadAlias],
+    pty: [loadPty],
+    tmux: [loadTmux],
+    watchdog: [loadWatchdog],
+    browser: [loadBrowser],
+    computer: [loadComputer],
+    logs: [loadLogs],
+    events: [loadEvents],
+    ssh: [loadSsh],
+    devices: [loadSsh],
+    // `fleet` is a commander alias of `devices` (see commands/ssh.ts); list it so
+    // lazy registration loads the devices tree when the user types `agents fleet`.
+    fleet: [loadSsh],
+    // `repos` is the canonical command name; `repo` remains a convenience alias
+    // (see commands/repo.ts). List both so lazy registration loads the tree
+    // whichever the user types.
+    repos: [loadRepo],
+    repo: [loadRepo],
+    setup: [loadSetup],
+    uninstall: [loadUninstall],
+    upgrade: [loadUpgrade],
+    sessions: [loadSessions],
+    teams: [loadTeams],
+    tickets: [loadTickets],
+    cloud: [loadCloud],
+    message: [loadMessage],
+    send: [loadSend],
+    notify: [loadSend],
+    feed: [loadFeed],
+    // Observe-umbrella alias of feed (the `timeline` alias was removed in RUSH-2692).
+    inbox: [loadFeed],
+    mailboxes: [loadMailboxes],
+    mailbox: [loadMailboxes],
+    serve: [loadServe],
+    artifacts: [loadArtifacts],
+    // `unshare` is a top-level convenience alias of `artifacts share delete` (see
+    // commands/share.ts) — same module, registered as its own program.command().
+    unshare: [loadArtifacts],
+    audit: [loadAudit],
+    webhooks: [loadWebhooks],
+    humans: [loadHumans],
+    daemon: [loadDaemon],
+};
+/**
+ * Register every module in {@link COMMAND_LOADERS} onto one fresh program and
+ * return it — the full public command tree, deduped by loader identity so a
+ * loader mapped to several names (e.g. `add`/`use`/`list` -> versions) runs once.
+ *
+ * Off the hot path only: the command-index generator (`scripts/gen-command-index.ts`)
+ * and the tests build the tree from this. Startup never calls it — src/index.ts
+ * registers just the one requested command via `registerEagerForRequest`. The
+ * inline aliases/tombstones ({@link INLINE_COMMAND_NAMES}) are NOT included: they
+ * are closures over entry-point state that src/index.ts registers directly.
+ */
+export async function buildFullCommandTree() {
+    const packageJson = JSON.parse(readFileSync(fileURLToPath(new URL('../../package.json', import.meta.url)), 'utf8'));
+    const program = configureRootCommand(new Command(), 'agents', packageJson.version);
+    const done = new Set();
+    for (const loaders of Object.values(COMMAND_LOADERS)) {
+        for (const loader of loaders) {
+            if (done.has(loader))
+                continue;
+            done.add(loader);
+            (await loader())(program);
+        }
+    }
+    return program;
+}

package/dist/commands/accounts.d.ts

@@ -1,6 +1,26 @@
 import type { Command } from 'commander';
+import type { AgentId } from '../lib/types.js';
+import { type Profile } from '../lib/profiles.js';
+type AttachTarget = {
+    kind: 'installation';
+    agent: AgentId;
+    version: string;
+} | {
+    kind: 'device-agent';
+    agent: AgentId;
+} | {
+    kind: 'profile';
+    profile: Profile;
+};
+/**
+ * Classify + validate an attach target, rejecting a typo BEFORE any binding is
+ * written: it must be an existing custom-harness profile, an installed
+ * `agent@version`, or a known harness id.
+ */
+export declare function classifyAttachTarget(target: string): AttachTarget;
 export declare function parseBundleKey(raw: string): {
     bundle: string;
     key: string;
 };
 export declare function registerAccountsCommand(program: Command): void;
+export {};