@phnx-labs/agents-cli 1.22.41 → 1.22.43

package/dist/commands/accounts.js

@@ -4,7 +4,10 @@ import { setHelpSections } from '../lib/help.js';
 import { readMeta, updateMeta } from '../lib/state.js';
 import { ALL_AGENT_IDS, getAccountInfo, resolveAgentName } from '../lib/agents.js';
 import { getVersionHomePath, listInstalledVersions } from '../lib/installations/versions.js';
-import { nativeAccountCapability, nativeAccountNameable, nativeIdentityKey } from '../lib/account-capabilities.js';
+import { assertNativeAccountNameable, nativeAccountCapability, nativeIdentityKey } from '../lib/account-capabilities.js';
+import { collectRunCandidates } from '../lib/accounting/rotate.js';
+import { isInteractiveTerminal } from './utils.js';
+import { buildSwitchAccountChoices, formatAccountLimits, pickSwitchAccount } from './run-account-picker.js';
 import { profileExists, readProfile } from '../lib/profiles.js';
 import { pushBundleToHost } from '../lib/secrets/push.js';
 import { assertCredentialTransportHostPinned, resolveHostSshTarget } from '../lib/secrets/remote.js';
@@ -14,6 +17,7 @@ import { discoverNativeAccounts } from '../lib/account-catalog.js';
 import { readAndResolveBundleEnv } from '../lib/secrets/bundles.js';
 import { getAccountProvider, listAccountProviders } from '../lib/account-provider-registry.js';
 import { accountBindings, addAccount, addNativeAccount, bindAccount, findAccount, findUnifiedAccount, inspectAccount, listNativeAccounts, readAccountRegistry, removeAccount, renameAccount, setAccountSecret, unbindAccount } from '../lib/account-registry.js';
+import { accountCapForTier, getTier } from '../lib/entitlement.js';
 function parseInstallation(raw) {
     const at = raw.lastIndexOf('@');
     if (at < 1 || at === raw.length - 1)
@@ -23,12 +27,10 @@ function parseInstallation(raw) {
         throw new Error(`Unknown agent '${raw.slice(0, at)}'.`);
     return { agent, version: raw.slice(at + 1) };
 }
-async function nativeIdentityFromSource(raw) {
+export async function nativeIdentityFromSource(raw) {
     const parsed = parseInstallation(raw);
     const capability = nativeAccountCapability(parsed.agent);
-    if (!nativeAccountNameable(parsed.agent)) {
-        throw new Error(`${parsed.agent} native accounts are ${capability.status}; agents-cli cannot safely name or attach this login.`);
-    }
+    assertNativeAccountNameable(parsed.agent);
     if (!listInstalledVersions(parsed.agent).includes(parsed.version))
         throw new Error(`${raw} is not installed.`);
     const info = await getAccountInfo(parsed.agent, getVersionHomePath(parsed.agent, parsed.version));
@@ -72,8 +74,8 @@ function secretFromBundle(raw) {
     const { bundle, key } = parseBundleKey(raw);
     return readAndResolveBundleEnv(bundle, { keys: [key], keyMode: 'storage', agentOnly: true, caller: 'accounts import' }).env[key];
 }
-function publicAccount(account) {
-    return { kind: 'provider', id: account.id, name: account.name, provider: account.provider, auth: account.auth, baseUrl: account.baseUrl, policy: account.policy, secretPresent: account.secretPresent };
+function publicAccount(account, dormant) {
+    return { kind: 'provider', id: account.id, name: account.name, provider: account.provider, auth: account.auth, baseUrl: account.baseUrl, policy: account.policy, secretPresent: account.secretPresent, dormant };
 }
 async function printAccounts(json, fleet = false) {
     if (fleet)
@@ -81,12 +83,16 @@ async function printAccounts(json, fleet = false) {
     const records = Object.values(readAccountRegistry().accounts).sort((a, b) => a.name.localeCompare(b.name));
     const discovered = await discoverNativeAccounts();
     const savedNative = listNativeAccounts(readMeta());
+    const dormantIds = new Set();
+    for (const agent of ALL_AGENT_IDS)
+        for (const account of await dormantAccountsForHarness(agent))
+            dormantIds.add(account.id);
     const native = discovered.map(row => {
         const saved = savedNative.find(account => account.agent === row.agent && account.identityKey === row.id);
-        return { ...row, name: saved?.name, id: saved?.id ?? row.id };
+        return { ...row, name: saved?.name, id: saved?.id ?? row.id, dormant: !!saved && dormantIds.has(saved.id) };
     });
     if (json) {
-        console.log(JSON.stringify([...records.map(account => publicAccount(inspectAccount(account.name))), ...native], null, 2));
+        console.log(JSON.stringify([...records.map(account => publicAccount(inspectAccount(account.name), dormantIds.has(account.id))), ...native], null, 2));
         return;
     }
     console.log(chalk.bold('Provider account bundles\n'));
@@ -94,19 +100,168 @@ async function printAccounts(json, fleet = false) {
         console.log(chalk.gray("  None. Add one with 'agents accounts add <name> --provider <provider> --auth <type>'."));
     for (const account of records) {
         const present = inspectAccount(account.name).secretPresent ? chalk.green('ready') : chalk.red('missing on this device');
-        console.log(`  ${chalk.cyan(account.name)}  ${account.provider}  ${account.auth}  ${present}`);
+        const dormantSuffix = dormantIds.has(account.id) ? chalk.gray('  — dormant (upgrade to reactivate)') : '';
+        console.log(`  ${chalk.cyan(account.name)}  ${account.provider}  ${account.auth}  ${present}${dormantSuffix}`);
     }
     console.log(chalk.bold('\nNative harness logins\n'));
     if (!native.length)
         console.log(chalk.gray('  No signed-in native accounts found.'));
     for (const account of native)
-        console.log(`  ${account.name ? `${chalk.cyan(account.name)} · ` : ''}${account.display}  ${account.agent}  ${account.versions.join(', ')}`);
+        console.log(`  ${account.name ? `${chalk.cyan(account.name)} · ` : ''}${account.display}  ${account.agent}  ${account.versions.join(', ')}${account.dormant ? chalk.gray('  — dormant (upgrade to reactivate)') : ''}`);
 }
 function parseAuth(raw) {
     if (raw === 'api-key' || raw === 'setup-token' || raw === 'bearer-token')
         return raw;
     throw new Error(`Unsupported auth type '${raw}'. Use api-key, setup-token, or bearer-token.`);
 }
+function parseHarness(agentRaw) {
+    if (!ALL_AGENT_IDS.includes(agentRaw))
+        throw new Error(`Unknown agent '${agentRaw}'.`);
+    return agentRaw;
+}
+function providerAuthenticatesHarness(provider, auth, agent) {
+    try {
+        getAccountProvider(provider).envFor(agent, auth);
+        return true;
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        if (message.includes('cannot authenticate'))
+            return false;
+        throw err;
+    }
+}
+/** Every account (native + provider) registered/usable for this harness, oldest-first by name — the full set a plan-tier cap slices into active vs dormant. */
+function accountsForHarness(agent) {
+    const meta = readMeta();
+    const native = listNativeAccounts(meta).filter(account => account.agent === agent);
+    const providers = Object.values(readAccountRegistry().accounts)
+        .filter(account => providerAuthenticatesHarness(account.provider, account.auth, agent))
+        .map(account => ({ ...account, kind: 'provider' }));
+    return [...native, ...providers].sort((a, b) => a.name.localeCompare(b.name));
+}
+/**
+ * Named accounts that `set-default` / `switch` can pin for this harness —
+ * capped to the caller's plan tier (RUSH-2424). Downgrading never deletes a
+ * credential: an over-cap account simply falls out of this list (see
+ * {@link dormantAccountsForHarness}) and stops being a switch/rotation target
+ * until the plan is upgraded.
+ */
+export async function listSwitchableAccounts(agent) {
+    const cap = accountCapForTier(await getTier());
+    return accountsForHarness(agent).slice(0, cap);
+}
+/** Accounts registered for this harness beyond the plan's cap — kept, never deleted, excluded from switch/rotation, reactivated by an upgrade. */
+export async function dormantAccountsForHarness(agent) {
+    const cap = accountCapForTier(await getTier());
+    return accountsForHarness(agent).slice(cap);
+}
+function accountCapRefusalMessage(agent, tier, cap) {
+    if (!tier.isPaid)
+        return `free plan is capped at 3 ${agent} accounts (3/3). agents upgrade — up to 10 per harness.`;
+    return `${tier.tierName} plan is capped at ${cap} ${agent} accounts (${cap}/${cap}).`;
+}
+/**
+ * Refuse BEFORE any write when adding a new account would push one of
+ * `harnesses` over the caller's plan cap. Returns the tier/cap/pre-add counts
+ * so the caller can print the exactly-at-cap notice after a successful write.
+ */
+async function assertAccountCapacityFor(harnesses) {
+    const tier = await getTier();
+    const cap = accountCapForTier(tier);
+    const existing = new Map();
+    for (const harness of harnesses)
+        existing.set(harness, accountsForHarness(harness).length);
+    const capped = harnesses.find(harness => (existing.get(harness) ?? 0) >= cap);
+    if (capped)
+        throw new Error(accountCapRefusalMessage(capped, tier, cap));
+    return { tier, cap, existing };
+}
+/** One-line, non-blocking notice for every harness a free-tier add just brought to exactly its cap. */
+function printCapNoticesFor(harnesses, tier, cap, existing) {
+    if (tier.isPaid)
+        return;
+    for (const harness of harnesses) {
+        if ((existing.get(harness) ?? 0) + 1 === cap) {
+            console.log(chalk.yellow(`${cap}/${cap} ${harness} accounts on the free plan. agents upgrade — up to 10 per harness.`));
+        }
+    }
+}
+/**
+ * Pin the per-harness default. Shared by `accounts set-default` and `accounts switch`.
+ * Provider accounts must authenticate the harness; native accounts must belong to it.
+ */
+export function setDefaultAccount(agentRaw, name) {
+    const agent = parseHarness(agentRaw);
+    const account = findUnifiedAccount(name, readMeta());
+    if (!account)
+        throw new Error(`Unknown account '${name}'.`);
+    if (account.kind === 'provider') {
+        getAccountProvider(account.provider).envFor(agent, account.auth);
+    }
+    else {
+        if (account.agent !== agent) {
+            throw new Error(`Account '${account.name}' is a ${account.agent} login and cannot be the default for ${agent}.`);
+        }
+        assertNativeAccountNameable(account.agent);
+    }
+    updateMeta(meta => ({ ...meta, accounts: { ...meta.accounts, defaults: { ...meta.accounts?.defaults, [agent]: account.id } } }));
+    return { agent, account };
+}
+async function switchAccountRows(agent) {
+    const accounts = await listSwitchableAccounts(agent);
+    const candidates = await collectRunCandidates(agent);
+    const defaultId = readMeta().accounts?.defaults?.[agent];
+    return accounts.map(account => {
+        const candidate = account.kind === 'native'
+            ? candidates.find(row => row.accountKey === account.identityKey) ?? null
+            : null;
+        return {
+            accountName: account.name,
+            kind: account.kind,
+            detail: account.kind === 'provider' ? account.provider : (account.identityLabel ?? account.identityKey),
+            current: account.id === defaultId,
+            candidate,
+        };
+    });
+}
+export async function runAccountsSwitch(harness, accountName, opts) {
+    const agent = parseHarness(harness);
+    const rows = await switchAccountRows(agent);
+    if (accountName) {
+        const { account } = setDefaultAccount(agent, accountName);
+        if (opts.json) {
+            console.log(JSON.stringify({ harness: agent, account: account.name, id: account.id }, null, 2));
+            return;
+        }
+        console.log(chalk.green(`${agent} now uses account '${account.name}' unless --account overrides it.`));
+        return;
+    }
+    if (opts.json) {
+        const choices = buildSwitchAccountChoices(rows);
+        console.log(JSON.stringify({
+            harness: agent,
+            default: rows.find(row => row.current)?.accountName ?? null,
+            accounts: rows.map((row, i) => ({
+                name: row.accountName,
+                kind: row.kind,
+                detail: row.detail,
+                current: row.current,
+                ready: choices[i].ready,
+                limits: row.candidate ? formatAccountLimits(row.candidate) : 'limits unavailable',
+            })),
+        }, null, 2));
+        return;
+    }
+    if (!isInteractiveTerminal()) {
+        throw new Error(`Selecting a ${agent} account requires an interactive terminal.\nUse: agents accounts switch ${agent} <account>\nOr:  agents accounts set-default ${agent} <account>`);
+    }
+    const selected = await pickSwitchAccount(agent, rows);
+    if (!selected)
+        return;
+    const { account } = setDefaultAccount(agent, selected);
+    console.log(chalk.green(`${agent} now uses account '${account.name}' unless --account overrides it.`));
+}
 export function registerAccountsCommand(program) {
     const accounts = program.command('accounts').description('Browse native logins and manage provider account bundles')
         .option('--json', 'Machine-readable account metadata')
@@ -124,10 +279,16 @@ export function registerAccountsCommand(program) {
         const provider = getAccountProvider(o.provider);
         if (!provider.authKinds.includes(auth))
             throw new Error(`Provider '${provider.provider}' does not support ${auth}. Supported: ${provider.authKinds.join(', ')}.`);
+        // A provider account may authenticate more than one harness (e.g. openrouter);
+        // it counts toward every harness it can authenticate, so refuse before any
+        // write if adding it would push ANY of those harnesses over the plan cap.
+        const harnesses = ALL_AGENT_IDS.filter(h => providerAuthenticatesHarness(provider.provider, auth, h));
+        const { tier, cap, existing } = await assertAccountCapacityFor(harnesses);
         const secret = o.fromSecrets ? secretFromBundle(o.fromSecrets) : await password({ message: `Enter ${provider.provider} ${auth} for '${name}':` });
         const account = addAccount(name, provider.provider, auth, secret, undefined, { baseUrl: o.baseUrl });
         console.log(chalk.green(`Added ${account.provider} ${account.auth} account '${account.name}'.`));
         console.log(chalk.gray(`Secret bundle '${account.name}' is the account and uses policy never, so agent launches never request Touch ID.`));
+        printCapNoticesFor(harnesses, tier, cap, existing);
     });
     accounts.command('set-key <name>')
         .description('Rotate an account credential without changing its identity')
@@ -140,17 +301,27 @@ export function registerAccountsCommand(program) {
         setAccountSecret(name, secret);
         console.log(chalk.green(`Updated credential for account '${name}'.`));
     });
-    accounts.command('view <name>').alias('inspect').description('Show safe account metadata, custody, and attachments').option('--json', 'Machine-readable output').action((name, o, command) => {
+    accounts.command('view <name>').alias('inspect').description('Show safe account metadata, custody, and attachments').option('--json', 'Machine-readable output').action(async (name, o, command) => {
         const meta = readMeta();
         const unified = findUnifiedAccount(name, meta);
         if (!unified)
             throw new Error(`Unknown account '${name}'.`);
+        const harnesses = unified.kind === 'provider'
+            ? ALL_AGENT_IDS.filter(h => providerAuthenticatesHarness(unified.provider, unified.auth, h))
+            : [unified.agent];
+        let dormant = false;
+        for (const harness of harnesses) {
+            if ((await dormantAccountsForHarness(harness)).some(a => a.id === unified.id)) {
+                dormant = true;
+                break;
+            }
+        }
         const account = unified.kind === 'provider'
-            ? { ...publicAccount(inspectAccount(unified.name)), custody: 'agents secrets (policy never)', attached: accountBindings(unified.id, meta) }
-            : { ...unified, custody: `${unified.agent} (not stored by agents-cli)`, attached: accountBindings(unified.id, meta) };
+            ? { ...publicAccount(inspectAccount(unified.name), dormant), custody: 'agents secrets (policy never)', attached: accountBindings(unified.id, meta) }
+            : { ...unified, dormant, custody: `${unified.agent} (not stored by agents-cli)`, attached: accountBindings(unified.id, meta) };
         if (o.json || command.optsWithGlobals().json)
             return console.log(JSON.stringify(account, null, 2));
-        console.log(chalk.bold(account.name));
+        console.log(chalk.bold(account.name) + (account.dormant ? chalk.gray('  — dormant (upgrade to reactivate)') : ''));
         console.log(`  kind: ${account.kind}`);
         console.log(`  id: ${account.id}`);
         console.log(`  custody: ${account.custody}`);
@@ -169,10 +340,12 @@ export function registerAccountsCommand(program) {
         .description('Name a signed-in native installation without copying its OAuth credentials')
         .action(async (source, name) => {
         const identity = await nativeIdentityFromSource(source);
+        const { tier, cap, existing } = await assertAccountCapacityFor([identity.agent]);
         const account = addNativeAccount(name, identity.agent, identity.identityKey, identity.identityLabel, identity.scope);
         console.log(chalk.green(`Named ${source} as ${account.name}.`));
         if (account.scope === 'device')
             console.log(chalk.gray(`${identity.agent} authentication is device-scoped; attach '${account.name}' to '${identity.agent}', not an individual version.`));
+        printCapNoticesFor([identity.agent], tier, cap, existing);
     });
     accounts.command('attach <account> <target>')
         .description('Attach a named account to a native installation or custom harness')
@@ -181,6 +354,8 @@ export function registerAccountsCommand(program) {
         const account = findUnifiedAccount(name, meta);
         if (!account)
             throw new Error(`Unknown account '${name}'.`);
+        if (account.kind === 'native')
+            assertNativeAccountNameable(account.agent);
         // Validate the target exists before mutating any binding.
         const t = classifyAttachTarget(target);
         const targetAgent = t.kind === 'profile' ? t.profile.host.agent : t.agent;
@@ -208,6 +383,17 @@ export function registerAccountsCommand(program) {
             // Provider account: it must be able to authenticate the target's harness.
             getAccountProvider(account.provider).envFor(targetAgent, account.auth);
         }
+        // Defense-in-depth cap check: by the point we get here `account` already
+        // authenticates/belongs to `targetAgent` (validated above), so it is
+        // already counted in accountsForHarness(targetAgent) from its `add`/`name`
+        // time — this can only refuse if that invariant is ever violated, never a
+        // normal re-attach of an account the harness is already at cap with.
+        const tier = await getTier();
+        const cap = accountCapForTier(tier);
+        const alreadyCounted = accountsForHarness(targetAgent).some(existing => existing.id === account.id);
+        const otherCount = accountsForHarness(targetAgent).length - (alreadyCounted ? 1 : 0);
+        if (otherCount >= cap)
+            throw new Error(accountCapRefusalMessage(targetAgent, tier, cap));
         bindAccount(name, target);
         console.log(chalk.green(`Attached ${account.name} to ${target}.`));
     });
@@ -220,25 +406,21 @@ export function registerAccountsCommand(program) {
     accounts.command('rename <old> <new>').description('Rename an account without changing its stable id').action((oldName, newName) => renameAccount(oldName, newName));
     accounts.command('remove <name>').description('Remove an account and its device-local credential').action((name) => removeAccount(name));
     accounts.command('set-default <agent> <name>')
-        .description('Use a provider account for a harness when --account is omitted')
+        .description('Use this account for a harness when --account is omitted')
         .action((agentRaw, name) => {
-        if (!ALL_AGENT_IDS.includes(agentRaw))
-            throw new Error(`Unknown agent '${agentRaw}'.`);
-        const agent = agentRaw;
-        const account = findAccount(name);
-        if (!account)
-            throw new Error(`Unknown provider account '${name}'.`);
-        getAccountProvider(account.provider).envFor(agent, account.auth);
-        // Defaults follow the stable account id, so renaming the bundle cannot
-        // strand bare runs on a deleted label. findAccount accepts ids and names.
-        updateMeta(meta => ({ ...meta, accounts: { ...meta.accounts, defaults: { ...meta.accounts?.defaults, [agent]: account.id } } }));
+        const { agent, account } = setDefaultAccount(agentRaw, name);
         console.log(chalk.green(`${agent} now uses account '${account.name}' unless --account overrides it.`));
     });
+    const switchCmd = accounts.command('switch <harness> [account]')
+        .description('Pick the default account for a harness')
+        .option('--json', 'Machine-readable account list or the resulting default')
+        .action(async (harness, account, o, command) => {
+        await runAccountsSwitch(harness, account, { json: !!(o.json || command.optsWithGlobals().json) });
+    });
     accounts.command('clear-default <agent>')
         .description('Return a harness to native login or balanced account selection')
         .action((agentRaw) => {
-        if (!ALL_AGENT_IDS.includes(agentRaw))
-            throw new Error(`Unknown agent '${agentRaw}'.`);
+        parseHarness(agentRaw);
         updateMeta(meta => {
             const defaults = { ...meta.accounts?.defaults };
             delete defaults[agentRaw];
@@ -309,6 +491,13 @@ export function registerAccountsCommand(program) {
             throw new Error(`${result.message}\nRetry: agents accounts sync ${account.name} ${device}${o.force ? ' --force' : ''}`);
         console.log(chalk.green(`${account.name} synced to ${device} (${result.keyCount} keys, ${remoteBackend} backend, policy never).`));
     });
+    setHelpSections(switchCmd, {
+        examples: `agents accounts switch claude
+agents accounts switch claude work
+agents accounts switch claude --json
+agents run claude`,
+        notes: 'Switch writes the existing per-harness default (same binding as set-default). Rotation already honors it. Pass an account name to skip the picker. Native name/attach is only for harnesses agents-cli can isolate (claude, codex, grok); provider add is unrestricted.',
+    });
     setHelpSections(accounts, {
         examples: `agents accounts add work --provider anthropic --auth setup-token
 agents accounts add openrouter-work --provider openrouter --auth api-key --from-secrets openrouter.ai:OPENROUTER_API_KEY
@@ -316,10 +505,12 @@ agents accounts set-key work
 agents accounts name claude@2.1.220 work
 agents accounts attach work claude@2.1.225
 agents accounts view work --json
+agents accounts switch claude
+agents accounts switch claude work
 agents accounts set-default claude work
 agents accounts sync openrouter-work yosemite-s0
 agents run claude --account work
 agents accounts logout claude`,
-        notes: 'Native account records contain metadata only; harness-owned OAuth credentials are never copied. Provider accounts are explicit portable bundles with policy never. Harness-native OAuth sign-out is `agents accounts logout <harness>` (API-key accounts use `accounts remove`). Synced vault unlock is `agents secrets vault unlock`.',
+        notes: 'Native account records contain metadata only; harness-owned OAuth credentials are never copied. Provider accounts are explicit portable bundles with policy never. `accounts switch` is the fast picker over the same default `set-default` writes. Harness-native OAuth sign-out is `agents accounts logout <harness>` (API-key accounts use `accounts remove`). Synced vault unlock is `agents secrets vault unlock`.',
     });
 }

package/dist/commands/alias.d.ts

@@ -1,11 +1,14 @@
 /**
- * Alias command -- create top-level shim binaries that expand to `agents <subcommand>`.
+ * `agents setup alias` -- create top-level shim binaries that expand to
+ * `agents <subcommand>`. Nested under setup because the user is configuring
+ * this machine's PATH shortcuts, not operating a separate noun (RUSH-2965).
  *
- * Generates executable scripts in ~/.agents/shims/ (already on PATH from the
- * standard agents-cli install). Running `teams` becomes equivalent to
+ * Generates executable scripts in ~/.agents/.cache/shims/ (already on PATH from
+ * the standard agents-cli install). Running `teams` becomes equivalent to
  * `agents teams`. Aliases are tracked in ~/.agents/aliases.json so we can
  * list, regenerate, or remove them without scanning the shims directory
  * (which also holds agent CLI shims like claude/codex/gemini).
  */
 import type { Command } from 'commander';
-export declare function registerAliasCommand(program: Command): void;
+/** Register `agents setup alias` under the parent `setup` command. */
+export declare function registerAliasCommand(setupCmd: Command): void;

package/dist/commands/alias.js

@@ -2,9 +2,12 @@ import chalk from 'chalk';
 import * as fs from 'fs';
 import * as path from 'path';
 import { getUserAgentsDir } from '../lib/state.js';
-import { getShimsDir } from '../lib/shims.js';
+import { getShimsDir } from '../lib/installations/shims.js';
 import { ALL_AGENT_IDS, AGENTS } from '../lib/agents.js';
-const ALIASES_FILE = path.join(getUserAgentsDir(), 'aliases.json');
+import { setHelpSections } from '../lib/help.js';
+function aliasesFile() {
+    return path.join(getUserAgentsDir(), 'aliases.json');
+}
 /** Names that would clobber an agent CLI shim or the `agents` binary itself. */
 function reservedNames() {
     const reserved = new Set(['agents']);
@@ -13,10 +16,11 @@ function reservedNames() {
     return reserved;
 }
 function readAliases() {
-    if (!fs.existsSync(ALIASES_FILE))
+    const file = aliasesFile();
+    if (!fs.existsSync(file))
         return {};
     try {
-        const parsed = JSON.parse(fs.readFileSync(ALIASES_FILE, 'utf-8'));
+        const parsed = JSON.parse(fs.readFileSync(file, 'utf-8'));
         return parsed && typeof parsed === 'object' ? parsed : {};
     }
     catch {
@@ -24,8 +28,9 @@ function readAliases() {
     }
 }
 function writeAliases(map) {
-    fs.mkdirSync(path.dirname(ALIASES_FILE), { recursive: true });
-    fs.writeFileSync(ALIASES_FILE, JSON.stringify(map, null, 2) + '\n', 'utf-8');
+    const file = aliasesFile();
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, JSON.stringify(map, null, 2) + '\n', 'utf-8');
 }
 function shimPath(name) {
     return path.join(getShimsDir(), name);
@@ -46,10 +51,30 @@ function isAliasShim(filePath) {
         return false;
     }
 }
-export function registerAliasCommand(program) {
-    const cmd = program
+/** Register `agents setup alias` under the parent `setup` command. */
+export function registerAliasCommand(setupCmd) {
+    const cmd = setupCmd
         .command('alias')
         .description('Create shorthand binaries that expand to `agents <subcommand>`');
+    setHelpSections(cmd, {
+        examples: `
+      # Make \`teams\` run \`agents teams\`
+      agents setup alias add teams
+
+      # Shorthand for a longer expansion
+      agents setup alias add sess sessions preview
+
+      agents setup alias list
+      agents setup alias remove teams
+    `,
+        notes: `
+      Writes an executable shim into ~/.agents/.cache/shims/ (already on PATH after
+      \`agents setup\`) and records it in ~/.agents/aliases.json.
+
+      Names that collide with the agents binary or an agent CLI (claude, codex,
+      grok, …) are refused. Top-level \`agents alias\` is gone — use this group.
+    `,
+    });
     cmd
         .command('add <name> [expansion...]')
         .description('Create an alias shim. If expansion is omitted, defaults to <name>.')
@@ -106,7 +131,7 @@ export function registerAliasCommand(program) {
         const map = readAliases();
         const entries = Object.entries(map);
         if (entries.length === 0) {
-            console.log(chalk.gray('No aliases. Try: agents alias add teams'));
+            console.log(chalk.gray('No aliases. Try: agents setup alias add teams'));
             return;
         }
         const width = entries.reduce((max, [n]) => Math.max(max, n.length), 0);

package/dist/commands/auth.d.ts

@@ -0,0 +1,9 @@
+import type { Command } from 'commander';
+/**
+ * `agents auth login` — RFC 8628 device-code flow against the already-shipped
+ * `/api/v1/auth/device/*` routes. If the live API rejects the request shape
+ * (a route this spec missed, or the endpoint moved), this fails loud with the
+ * `rush login` fallback rather than silently stubbing a fake session.
+ */
+export declare function runAuthLogin(): Promise<void>;
+export declare function registerAuthCommand(program: Command): void;

package/dist/commands/auth.js

@@ -0,0 +1,108 @@
+import chalk from 'chalk';
+import { setHelpSections } from '../lib/help.js';
+import { runOrDie } from '../lib/format.js';
+import { clearPrixSession, fetchWhoAmI, pollDeviceToken, PrixApiError, readPrixSession, resolvePrixToken, startDeviceAuthorization, writePrixSession, } from '../lib/prix-account.js';
+function sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+/**
+ * `agents auth login` — RFC 8628 device-code flow against the already-shipped
+ * `/api/v1/auth/device/*` routes. If the live API rejects the request shape
+ * (a route this spec missed, or the endpoint moved), this fails loud with the
+ * `rush login` fallback rather than silently stubbing a fake session.
+ */
+export async function runAuthLogin() {
+    let authorization;
+    try {
+        authorization = await startDeviceAuthorization();
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        const existing = resolvePrixToken();
+        if (existing?.source === 'rush') {
+            console.log(chalk.yellow(`Device login is unavailable right now (${message}), but you're already signed in via 'rush login'.`));
+            console.log("Run 'agents auth whoami' to confirm.");
+            return;
+        }
+        throw new Error(`Device login is unavailable right now (${message}). Run 'rush login' instead, then 'agents auth whoami' to confirm.`);
+    }
+    console.log(`To sign in, open:\n\n  ${chalk.cyan(authorization.verification_uri_complete)}\n`);
+    console.log(chalk.gray(`(code: ${authorization.user_code})`));
+    const deadline = Date.now() + authorization.expires_in * 1000;
+    let interval = Math.max(authorization.interval, 1) * 1000;
+    while (Date.now() < deadline) {
+        await sleep(interval);
+        const poll = await pollDeviceToken(authorization.device_code);
+        if (poll.status === 'pending')
+            continue;
+        if (poll.status === 'slow_down') {
+            interval += 1000;
+            continue;
+        }
+        if (poll.status === 'expired')
+            throw new Error('Login code expired. Run `agents auth login` again.');
+        if (poll.status === 'denied')
+            throw new Error('Login was denied.');
+        writePrixSession({
+            access_token: poll.access_token,
+            refresh_token: poll.refresh_token,
+            expires_at: poll.expires_in ? Date.now() + poll.expires_in * 1000 : undefined,
+            email: poll.user.email,
+            userId: poll.user.id,
+        });
+        console.log(chalk.green(`Signed in as ${poll.user.email}.`));
+        return;
+    }
+    throw new Error('Login code expired. Run `agents auth login` again.');
+}
+async function runAuthWhoami(json) {
+    const resolved = resolvePrixToken();
+    if (!resolved)
+        throw new Error("Not signed in. Run 'agents auth login' first.");
+    let who;
+    try {
+        who = await fetchWhoAmI(resolved.token);
+    }
+    catch (err) {
+        if (err instanceof PrixApiError && err.status === 401) {
+            throw new Error(`Signed-in token is no longer valid (${resolved.source === 'agents' ? "run 'agents auth login'" : "run 'rush login'"} again).`);
+        }
+        throw err;
+    }
+    if (json) {
+        console.log(JSON.stringify({ ...who, source: resolved.source }, null, 2));
+        return;
+    }
+    console.log(`${chalk.bold(who.email)}  ${chalk.gray(who.userId)}`);
+    console.log(chalk.gray(`signed in via ${resolved.source === 'agents' ? "'agents auth login'" : "'rush login' (shared session)"}`));
+}
+function runAuthLogout() {
+    const cleared = clearPrixSession();
+    const rushRemains = resolvePrixToken()?.source === 'rush';
+    if (!cleared && !readPrixSession()) {
+        console.log(chalk.gray('Not signed in via `agents auth login` — nothing to clear.'));
+    }
+    else {
+        console.log(chalk.green('Signed out.'));
+    }
+    if (rushRemains) {
+        console.log(chalk.gray("You're still signed in via `rush login` — `agents auth whoami` will use that session. Run `rush logout` to clear it too."));
+    }
+}
+export function registerAuthCommand(program) {
+    const auth = program.command('auth').description('Sign in to your Rush account (shared by `agents org` and paid tiers)');
+    auth.command('login').description('Sign in via the device-code flow').action(() => runOrDie(() => runAuthLogin()));
+    auth.command('whoami').description('Show the signed-in account').option('--json', 'Machine-readable output')
+        .action((o, command) => {
+        const json = !!(o.json || command.optsWithGlobals().json);
+        return runOrDie(() => runAuthWhoami(json), { json });
+    });
+    auth.command('logout').description('Clear the local `agents auth login` session').action(() => runOrDie(() => runAuthLogout()));
+    setHelpSections(auth, {
+        examples: `agents auth login
+agents auth whoami
+agents auth whoami --json
+agents auth logout`,
+        notes: "`agents auth login` writes its own session, separate from \`rush login\`'s \`~/.rush/user.yaml\` — \`agents auth logout\` never signs you out of \`rush\`. If you're already signed in via \`rush login\`, \`agents auth whoami\`/\`agents org\` use that session automatically; no separate login is required.",
+    });
+}