@phnx-labs/agents-cli 1.22.41 → 1.22.42

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 1.22.42
+
+- **Plan-tier gates for `agents accounts` and `agents insights` (RUSH-2424).** A new `apps/cli/src/lib/entitlement.ts` reads the live subscription tier from `GET /api/v1/billing/subscription?agent=agi-cli` (the session token in `~/.rush/user.yaml`), caches it on disk for 15 minutes, and stays offline-tolerant: a stale cache is honored over a failed network call, and no session file at all resolves straight to the free tier. `agents accounts add` / `name` / `attach` now cap registered accounts at 3 per harness on free, 10 on paid/admin — a 4th add on free refuses before any write (`free plan is capped at 3 claude accounts (3/3). agents upgrade — up to 10 per harness.`) and the 3rd prints a one-line notice. Downgrading a plan never deletes a credential: over-cap accounts fall out of `accounts switch`/`set-default` (excluded from `listSwitchableAccounts`) and are listed `dormant (upgrade to reactivate)` in `agents accounts`. `agents insights` keeps top-line counts, harness mix, `insights mix`, and `agents perf` free on every tier; the Friction / Friction-thrash / Dissatisfaction-corrections sections, grouping `--by account` (the default), and `--narrative` are paid — a gated section is replaced by the in-voice notice `Friction and account-split analysis are on the paid plan.` in both the text report and `--json` (a new `plan: {tierName, isPaid}` field, `groups: null` when the account breakdown is gated, and the friction/correction facet keys stripped per group otherwise). Source: `apps/cli/src/lib/entitlement.ts`, `apps/cli/src/commands/accounts.ts`, `apps/cli/src/commands/insights.ts`.
+
+- **`--profile <name>` means the same profile in every browser command, and a profile's name never carries its endpoint (RUSH-2709).** `BrowserService.start` used to overwrite `BrowserProfile.name` with the composite `<profile>@<endpoint>` runtime key, so the key leaked into `profiles list`, `status`, `history`, and the feed, and six consumers each invented their own rule for turning one back into the other — which is why `status --profile default` could report "No browser tasks running" while that profile was running. The two concepts are now distinct types: `ProfileName` (user-facing, always bare), `EndpointName`, and a **branded** `ConnectionKey` built at exactly one site, so `connections.get(someProfileName)` — the original miss — no longer compiles. One rule, `keyBelongsToProfile`, replaces the four ad-hoc reconciliations in `status`, `stopProfile`, `findTask`, and `listProfileCacheDirs`, which also fixes a legacy `<name>.<n>` fork directory being matched by some of those paths and missed by others. `status` renders `comet-local (endpoint: endpoint-0, port 9222, pid …)` instead of the raw key, and `status --json` carries `name` (bare), `endpoint`, and `key` as separate fields. Source: `apps/cli/src/lib/browser/{types,service,profiles,runtime-state}.ts`, `apps/cli/src/lib/browser/drivers/{local,ssh}.ts`, `apps/cli/src/commands/browser.ts`, `apps/cli/docs/browser.md`.
+
+- **`default` is now purely an alias, and the auto-detected browser profile is named `auto-chrome` (RUSH-2709).** `default` used to name BOTH a concrete auto-detected profile and the "whatever you configured" alias, and only `start` honored the alias (its own comment: "narrowly scoped … only here in `start`") — so `--profile default` reached one profile in `start` and a different one, or nothing, in `stop` / `status` / `navigate`. One resolver, `resolveProfileRef`, now serves every command. Nothing existing breaks: a `browser.profile` config value of `default` still resolves (to the auto-detected profile), a profile you literally named `default` still resolves to itself and outranks the alias, and a machine that already carries a `default` profile keeps using it — `ensureDefaultBrowserProfile` reuses and regenerates it in place rather than creating a second one, so a running browser and its on-disk runtime dirs are not orphaned. Source: `apps/cli/src/lib/browser/profiles.ts`, `apps/cli/src/commands/{browser,setup,setup-browser,setup-preferences}.ts`, `apps/cli/src/lib/installations/migrate.ts`.
+
+- **`agents auth login/whoami/logout` and `agents org create/list/view/invite/members/role/remove/leave` — the account-layer client over the existing `api.prix.dev` backend.** `agents auth login` runs the already-shipped RFC 8628 device-code flow (`POST /api/v1/auth/device/authorization` + poll `/token`) and writes its own session file, separate from `rush login`'s `~/.rush/user.yaml` — so `agents auth logout` never signs you out of `rush`, while `agents auth whoami`/`agents org` fall back to a live `rush login` session automatically if you never ran `agents auth login`. `agents org` maps to the backend's `/api/v1/spaces` routes (not `/api/v1/orgs` — spaces already enforce the free-tier caps of 1 owned space / 3 members and can exist standalone). Every subcommand takes `--json`; `--space <id-or-slug>` is optional and defaults to your sole space. Source: `apps/cli/src/lib/prix-account.ts`, `apps/cli/src/commands/{auth,org}.ts`.
+
+- **`agents accounts switch <harness> [account]` picks the default account for a harness.** Interactive mode reuses the run-account picker layout (usage %, headroom, signed-out / rate-limited) and writes the existing per-harness default — the same binding as `accounts set-default`, which balanced rotation already honors. Pass an account name to skip the picker; `--json` lists or reports the result. Native `accounts name` / `attach` now refuse an unsupported harness with a named reason (`kimi accounts can't be isolated by agents-cli yet (device-scoped login). Supported today: claude, codex, grok.`); provider `accounts add --provider` is unchanged. Source: `apps/cli/src/commands/accounts.ts`, `apps/cli/src/commands/run-account-picker.ts`, `apps/cli/src/lib/account-capabilities.ts`.
+
+- **`agents browser navigate` now reuses a tab in Arc instead of refusing outright (#2786, #2778).** Arc crashes on `Target.createTarget`, so every navigate was answered with "use a Chromium-family browser" — which meant the document was never shown at all and callers fell back to a raw `open`, a new tab per call, i.e. exactly the tab-spam #2779 set out to end. Arc does expose page targets and does honor `Page.navigate` on them (measured against a live Arc: 33 targets, navigate reused one, tab count unchanged, no crash), so navigate now reuses in place, the same shape as the existing Electron branch. Reuse is narrow and non-destructive: only a tab ALREADY showing the requested URL, or an empty new-tab page, and a target another task owns is left alone. A reused tab is recorded as **borrowed** — the task drives it but never closes it, so a tab that was open before the task survives `done` (the rule `adoptTabShowing` states for unowned pages, kept here where reuse is unavoidable). When nothing is safe to reuse the actionable refusal stands. The `Target.createTarget` guard from #2778 is unchanged. Source: `apps/cli/src/lib/browser/service.ts`.
+
 ## 1.22.41
 
 - **BREAKING: the top-level `agents timeline` command is removed — use `agents feed --filter updates` (RUSH-2692).** `timeline` was a pure alias of `agents feed --filter updates` (its own description said so), a second door to one stream against the CLI-surface convention of one owned noun with no duplicated surface. It is gone entirely, not deprecated: `agents timeline` now reports `unknown command`, and `timeline` is retired from distance-1 auto-correct so a stale invocation fails loudly instead of running a neighbouring command. `agents feed --filter updates` is unchanged, and the sibling observe aliases `agents inbox` and `agents roster` are unaffected. Source: `apps/cli/src/commands/feed.ts`, `apps/cli/src/lib/observe-aliases.ts`, `apps/cli/src/lib/startup/command-registry.ts`, `apps/cli/src/bootstrap.ts`.

package/README.md

@@ -39,7 +39,11 @@
   <a href="https://docs.warp.dev/reference/cli" title="Warp Agent CLI (Oz)"><picture><source media="(prefers-color-scheme: dark)" srcset="assets/harnesses/warp.svg"><img src="assets/harnesses/warp-light.svg" height="32" alt="Warp Agent CLI" /></picture></a>
 </p>
 
-https://agi-cli.sh/demo.mp4
+<p align="center">
+  <img src="assets/demos/hero.gif" alt="agents CLI: sessions across every agent and project, chaining agents in a Unix pipeline, dispatching to the cloud, and one team spread across machines" width="860" />
+</p>
+
+<p align="center"><a href="https://agi-cli.sh/demo.mp4">Watch the full 56-second demo</a></p>
 
 ## Quickstart
 
@@ -1006,15 +1010,17 @@ agents accounts add gateway --provider openrouter --auth api-key \
   --from-secrets openrouter.ai:OPENROUTER_API_KEY  # import from an existing secrets bundle
 agents accounts add deepinfra --provider deepinfra --auth api-key
 
+agents accounts switch claude             # picker: usage %, headroom, signed-out / rate-limited
+agents accounts switch claude work        # skip the picker; same write as set-default
 agents accounts set-default claude work   # claude uses `work` when --account is omitted
 agents accounts sync work --device yosemite-s0   # explicitly copy the bundle to a worker device
 agents run claude --account work
 agents harness add deepinfra --account deepinfra
 ```
 
-One provider account **is** one `agents secrets` bundle -- `agents accounts add` creates it with secrets policy `never`, so a background agent launch on that account never raises Touch ID. `agents accounts` (no subcommand) lists provider bundles next to harness-native signed-in identities so you see both kinds of credential together; `accounts list` / `inspect <name>` / `set-key <name>` (rotate) / `rename` / `remove` manage a bundle by its stable id, independent of its current label.
+One provider account **is** one `agents secrets` bundle -- `agents accounts add` creates it with secrets policy `never`, so a background agent launch on that account never raises Touch ID. `agents accounts` (no subcommand) lists provider bundles next to harness-native signed-in identities so you see both kinds of credential together; `accounts list` / `inspect <name>` / `set-key <name>` (rotate) / `rename` / `remove` manage a bundle by its stable id, independent of its current label. `accounts switch <harness>` is the fast picker over that default -- it writes the same binding as `set-default`, and balanced rotation already honors it.
 
-Harness-native OAuth logins (Claude Code's own `/login`, `codex login`, and so on) stay exactly where the harness put them -- agi-cli discovers and displays them but never copies, renames, or converts them into a provider bundle. `accounts sync <name> --device <device>` is the only way a provider account crosses machines, and it's explicit: nothing syncs automatically. Selection order for a run is explicit `--account`, then `accounts set-default` for that harness, then the harness's native/balanced account behavior.
+Harness-native OAuth logins (Claude Code's own `/login`, `codex login`, and so on) stay exactly where the harness put them -- agi-cli discovers and displays them but never copies, renames, or converts them into a provider bundle. Native `accounts name` / `attach` is only for harnesses agents-cli can isolate today (claude, codex, grok; muse when an email is present). A device-scoped login (kimi, droid, …) is refused with a named reason; provider `accounts add --provider` is unrestricted. `accounts sync <name> --device <device>` is the only way a provider account crosses machines, and it's explicit: nothing syncs automatically. Selection order for a run is explicit `--account`, then `accounts set-default` / `switch` for that harness, then the harness's native/balanced account behavior.
 
 ---
 

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

@@ -98,6 +98,8 @@ export declare const loadWebhooks: ModuleLoader;
 export declare const loadHumans: ModuleLoader;
 export declare const loadAccounts: ModuleLoader;
 export declare const loadDaemon: ModuleLoader;
+export declare const loadAuth: ModuleLoader;
+export declare const loadOrg: ModuleLoader;
 /**
  * Commands whose modules pull in the SQLite-backed session/cloud stack. They are
  * registered AFTER `applyGlobalHelpConventions` (mirroring main's order: help

package/dist/cli/command-registry.js

@@ -103,6 +103,8 @@ export const loadWebhooks = async () => (await import('../commands/webhook.js'))
 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;
+export const loadAuth = async () => (await import('../commands/auth.js')).registerAuthCommand;
+export const loadOrg = async () => (await import('../commands/org.js')).registerOrgCommand;
 /**
  * Commands whose modules pull in the SQLite-backed session/cloud stack. They are
  * registered AFTER `applyGlobalHelpConventions` (mirroring main's order: help
@@ -135,6 +137,8 @@ export const LAZY_COMMAND_NAMES = new Set([
  */
 export const COMMAND_LOADERS = {
     accounts: [loadAccounts],
+    auth: [loadAuth],
+    org: [loadOrg],
     view: [loadView],
     inspect: [loadInspect],
     feedback: [loadFeedback],

package/dist/commands/accounts.d.ts

@@ -1,6 +1,14 @@
 import type { Command } from 'commander';
 import type { AgentId } from '../lib/types.js';
 import { type Profile } from '../lib/profiles.js';
+import { type UnifiedAccount } from '../lib/account-registry.js';
+export declare function nativeIdentityFromSource(raw: string): Promise<{
+    agent: AgentId;
+    version: string;
+    identityKey: string;
+    identityLabel?: string;
+    scope: 'version' | 'device';
+}>;
 type AttachTarget = {
     kind: 'installation';
     agent: AgentId;
@@ -22,5 +30,26 @@ export declare function parseBundleKey(raw: string): {
     bundle: string;
     key: string;
 };
+/**
+ * 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 declare function listSwitchableAccounts(agent: AgentId): Promise<UnifiedAccount[]>;
+/** Accounts registered for this harness beyond the plan's cap — kept, never deleted, excluded from switch/rotation, reactivated by an upgrade. */
+export declare function dormantAccountsForHarness(agent: AgentId): Promise<UnifiedAccount[]>;
+/**
+ * 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 declare function setDefaultAccount(agentRaw: string, name: string): {
+    agent: AgentId;
+    account: UnifiedAccount;
+};
+export declare function runAccountsSwitch(harness: string, accountName: string | undefined, opts: {
+    json: boolean;
+}): Promise<void>;
 export declare function registerAccountsCommand(program: Command): void;
 export {};

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.js

@@ -2,7 +2,7 @@ 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');
 /** Names that would clobber an agent CLI shim or the `agents` binary itself. */

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;