@phnx-labs/agents-cli 1.22.84 → 1.22.86

package/dist/commands/accounts.js

@@ -5,6 +5,7 @@ import { password, select } from '@inquirer/prompts';
 import { readClaudeAccountEmail, resolveClaudeSetupToken, resolveClaudeSetupTokenForEmail, seedClaudeWorkerHomeIdentity } from '../lib/claude-account-token.js';
 import { setHelpSections } from '../lib/help.js';
 import { readMeta, updateMeta } from '../lib/state.js';
+import { machineId } from '../lib/machine-id.js';
 import { ALL_AGENT_IDS, getAccountInfo, resolveAgentName } from '../lib/agents.js';
 import { getGlobalDefault, getVersionHomePath, listInstalledVersions } from '../lib/installations/versions.js';
 import { assertNativeAccountNameable, nativeAccountCapability, nativeIdentityKey } from '../lib/account-capabilities.js';
@@ -12,20 +13,56 @@ import { collectRunCandidates } from '../lib/accounting/rotate.js';
 import { isInteractiveTerminal, isPromptCancelled, requireInteractiveSelection } 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';
+import { assertCredentialTransportHostPinned, resolveHostSshTarget } from '../lib/hosts/credential-transport.js';
 import { resolveRemoteOsSync } from '../lib/hosts/remote-os.js';
-import { runDevicesAccounts } from './ssh.js';
-import { collectNativeHomeRows, loadAccountCatalog } from '../lib/account-catalog.js';
-import { connectRefusal, connectSupported, runConnect } from '../lib/accounts/connect.js';
+import { renderAccountFleetMatrix } from '../lib/devices/harness-inventory.js';
+import { accountListJson, collectNativeHomeRows, listDevicesWithoutAccountVerdicts, loadAccountCatalog, renderAccountRows, secretsUnavailableNote, } from '../lib/account-catalog.js';
+import { addRefusal, runAdd, runLogin, supportedAddHarnesses } from '../lib/accounts/add.js';
+import { applyAccountMigration, formatMigrationPlan, planAccountMigration } from '../lib/accounts/migrate.js';
+import { isSymlinkAdoptedHarness } from '../lib/installations/shims.js';
+import { ensureAdoptedDefaultRepoint } from '../lib/exec-account-home.js';
 import { acquireAuthOperationLock } from '../lib/accounts/auth-operation-lock.js';
-import { readAndResolveBundleEnv } from '../lib/secrets/bundles.js';
+import { isSecretsClientError, pushBundleToHost, readAndResolveBundleEnv, readBundle } from '../lib/secrets-client.js';
 import { getAccountProvider, listAccountProviders, providerAuthenticatesHarness } from '../lib/account-provider-registry.js';
 import { accountBindings, addAccount, addNativeAccount, assertUnambiguousNativeAccount, bindAccount, findAccount, findUnifiedAccount, inspectAccount, labelNativeAccount, listNativeAccounts, nativeAccountHome, parseAccountSelector, readAccountRegistry, removeAccount, renameAccount, setAccountSecret, unbindAccount } from '../lib/account-registry.js';
 import { registerMintCommand } from './auth-mint.js';
-/** Comma-joined list of harnesses `accounts connect` can drive today. */
-function connectSupportedList() {
-    return ALL_AGENT_IDS.filter(connectSupported).join(', ');
+/** Comma-joined list of harnesses `accounts add` can drive today. */
+function addSupportedList() {
+    return supportedAddHarnesses().join(', ');
+}
+/**
+ * Legacy-verb retirement: the command is created with `{ hidden: true }` (help
+ * no longer lists it) and this hook prints the pointer to its replacement when
+ * it runs. Verbs keep executing for one release.
+ */
+function retireVerb(cmd, pointer) {
+    cmd.hook('preAction', () => {
+        console.error(chalk.gray(`'agents accounts ${cmd.name()}' is replaced by '${pointer}' — still works this release.`));
+    });
+}
+/** Shared result printer for `accounts add` / `accounts login` / hidden `connect`. */
+function printAddResult(result, json) {
+    if (json) {
+        console.log(JSON.stringify(result, null, 2));
+        return;
+    }
+    const who = result.email ?? result.identityKey;
+    const verb = result.mode === 'reconnect' ? 'Re-authenticated' : 'Added';
+    console.log(chalk.green(`${verb} ${result.agent}#${result.name} (${who}).`));
+    const credentialLine = {
+        minted: 'worker credential minted for workers',
+        stored: 'worker credential stored for workers',
+        kept: 'worker credential unchanged',
+        skipped: 'no worker credential — runs on this device only',
+        'per-device': 'per-device login — each box signs in for itself',
+    };
+    console.log(chalk.gray(`  ${credentialLine[result.workerCredential]} · provisioning: ${result.provisioning}`));
+    if (result.becameDefault)
+        console.log(chalk.gray(`  Default account for ${result.agent} (first one added).`));
+    for (const warning of result.warnings)
+        console.log(chalk.yellow(`  warning: ${warning}`));
+    console.log(chalk.gray(`  The native OAuth login stays owned by the harness in its slot; nothing was copied.`));
+    console.log(chalk.gray(`  Run: agents run ${result.agent}#${result.name}`));
 }
 function cleanCommandError(command, err) {
     command.error(err instanceof Error ? err.message : String(err), { exitCode: 1, code: 'accounts.error' });
@@ -126,9 +163,38 @@ export function parseBundleKey(raw) {
         throw new Error(`Expected bundle:key, got '${raw}'.`);
     return { bundle: raw.slice(0, colon), key: raw.slice(colon + 1) };
 }
-function secretFromBundle(raw) {
+/**
+ * Copy one value out of an `agents secrets` bundle for `--from-secrets`. The
+ * standalone reports failures only as codes, so the bundle, the key, and the
+ * repair are named here — and existence is checked first, because a
+ * prompt-free (`agentOnly`) read of a bundle that does not exist reports
+ * LOCKED rather than NOT_FOUND.
+ */
+async function secretFromBundle(raw) {
     const { bundle, key } = parseBundleKey(raw);
-    return readAndResolveBundleEnv(bundle, { keys: [key], keyMode: 'storage', agentOnly: true, caller: 'accounts import' }).env[key];
+    let vars;
+    try {
+        vars = (await readBundle(bundle)).vars;
+    }
+    catch (err) {
+        if (!isSecretsClientError(err, 'NOT_FOUND'))
+            throw err;
+        throw new Error(`Secrets bundle '${bundle}' not found. List bundles with 'agents secrets list'.`);
+    }
+    if (!(key in vars)) {
+        const available = Object.keys(vars).join(', ') || '(none)';
+        throw new Error(`Secrets bundle '${bundle}' has no key '${key}'. Available: ${available}.`);
+    }
+    try {
+        const { env } = await readAndResolveBundleEnv(bundle, { keys: [key], keyMode: 'storage', agentOnly: true, caller: 'accounts import' });
+        return env[key];
+    }
+    catch (err) {
+        if (!isSecretsClientError(err, 'LOCKED'))
+            throw err;
+        throw new Error(`Secrets bundle '${bundle}' is not unlocked for a prompt-free read. ` +
+            `Unlock it first with 'agents secrets unlock ${bundle}', then retry.`);
+    }
 }
 /** Interactive secret entry for add/set-key. Ctrl+C must not become accounts.error. */
 async function promptAccountSecret(message) {
@@ -144,73 +210,37 @@ async function promptAccountSecret(message) {
 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 };
 }
-async function printAccounts(json, fleet = false) {
-    if (fleet)
-        return runDevicesAccounts({ json });
-    const records = Object.values(readAccountRegistry().accounts).sort((a, b) => a.name.localeCompare(b.name));
+async function printAccounts(json, fleet = false, harnessRaw) {
+    const harness = harnessRaw ? parseHarness(harnessRaw) : undefined;
     const catalog = await loadAccountCatalog();
-    const native = catalog.native.map(row => ({
-        ...row, name: row.name ?? undefined, id: row.id ?? row.identityKey,
-        versions: row.installations.map(home => home.label),
-    }));
+    const note = secretsUnavailableNote(catalog);
+    if (note)
+        console.error(chalk.yellow(note)); // stderr — never corrupts --json stdout
+    const native = harness ? catalog.native.filter((row) => row.agent === harness) : catalog.native;
+    const providers = harness
+        ? catalog.provider.filter((row) => row.harnesses.includes(harness))
+        : catalog.provider;
     if (json) {
-        console.log(JSON.stringify([...records.map(account => publicAccount(inspectAccount(account.name))), ...native], null, 2));
+        console.log(JSON.stringify(accountListJson(native, providers, harness), null, 2));
         return;
     }
-    console.log(renderAccountList(records, native));
-}
-/** Pure text renderer for `agents accounts list` — grouped, column-aligned, labels first-class. */
-export function renderAccountList(records, native) {
-    const out = [];
-    // Native logins, grouped by harness — the selection surface for `<harness>#<label>`.
-    out.push(chalk.bold('Native logins') + chalk.gray('     ') + chalk.gray('run <harness>#<label>'));
-    if (!native.length) {
-        out.push(chalk.gray('  No native accounts found. Connect one: agents accounts connect <harness> [name]'));
-    }
-    else {
-        const byHarness = new Map();
-        for (const acct of native) {
-            const list = byHarness.get(acct.agent) ?? [];
-            list.push(acct);
-            byHarness.set(acct.agent, list);
-        }
-        const harnessW = Math.max(6, ...[...byHarness.keys()].map(h => h.length));
-        const labelW = Math.max(6, ...native.map(a => (a.name ?? '—').length));
-        const idW = Math.max(8, ...native.map(a => a.display.length));
-        let sawDefault = false;
-        for (const [harness, list] of [...byHarness.entries()].sort((a, b) => a[0].localeCompare(b[0]))) {
-            const defaultVersion = getGlobalDefault(harness);
-            list.forEach((acct, i) => {
-                const harnessCell = chalk.gray((i === 0 ? harness : '').padEnd(harnessW));
-                const rawLabel = acct.name ?? '—';
-                const labelCell = acct.name ? chalk.cyan(rawLabel.padEnd(labelW)) : chalk.gray(rawLabel.padEnd(labelW));
-                const isDefault = acct.isDefault ?? (defaultVersion ? acct.versions.includes(defaultVersion) : false);
-                if (isDefault)
-                    sawDefault = true;
-                const marker = isDefault ? chalk.green('*') : ' ';
-                const state = acct.state === 'reconnect-needed' ? 'not connected here' : 'connected';
-                out.push(`  ${harnessCell}  ${labelCell}${marker} ${acct.display.padEnd(idW)}  ${chalk.gray(state)}`);
-            });
-        }
-        if (sawDefault)
-            out.push(chalk.gray('\n  * default account for that harness (used when you pass neither @version nor #label)'));
-    }
-    // Provider bundles — the durable API-key/setup-token accounts, selected with `--account <name>`.
-    out.push('');
-    out.push(chalk.bold('Provider bundles') + chalk.gray('  run <harness> --account <name>'));
-    if (!records.length) {
-        out.push(chalk.gray("  None. Add one with 'agents accounts add <name> --provider <provider> --auth <type>'."));
-    }
-    else {
-        const nameW = Math.max(4, ...records.map(a => a.name.length));
-        const provW = Math.max(8, ...records.map(a => a.provider.length));
-        const authW = Math.max(10, ...records.map(a => a.auth.length));
-        for (const account of records) {
-            const present = inspectAccount(account.name).secretPresent ? chalk.green('ready') : chalk.red('missing on this device');
-            out.push(`  ${chalk.cyan(account.name.padEnd(nameW))}  ${account.provider.padEnd(provW)}  ${account.auth.padEnd(authW)}  ${present}`);
-        }
+    if (fleet) {
+        const matrixRows = native.map((row) => ({
+            harness: row.agent,
+            name: row.name,
+            identityLabel: row.identityLabel,
+            devices: row.devices,
+        }));
+        const covered = new Set(matrixRows.flatMap((row) => row.devices.map((device) => device.device)));
+        const uncoveredDevices = listDevicesWithoutAccountVerdicts().filter((device) => !covered.has(device));
+        console.log(renderAccountFleetMatrix(matrixRows, { uncoveredDevices }).join('\n'));
+        return;
     }
-    return out.join('\n');
+    console.log(renderAccountRows(native, { providers, harness, localDevice: machineId() }));
+}
+/** Compatibility export for tests/consumers; the canonical renderer is shared with view. */
+export function renderAccountList(native, providers = [], opts = {}) {
+    return renderAccountRows(native, { providers, localDevice: '', ...opts });
 }
 function parseAuth(raw) {
     if (raw === 'api-key' || raw === 'setup-token' || raw === 'bearer-token')
@@ -355,12 +385,19 @@ export function setDefaultAccount(agentRaw, name) {
         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);
+        // Adopted harnesses isolate by slot + symlink, not a version home, so the
+        // nameable-by-version-home gate does not apply to `accounts default`.
+        if (!isSymlinkAdoptedHarness(agent))
+            assertNativeAccountNameable(account.agent);
     }
     // Reference by NAME, not id: defaults sync fleet-wide with `agents repo push/pull`
     // while account ids are minted per-device, so an id ref breaks on every other
     // machine ("Unknown account '<uuid>'"). Names are the portable handle — the
     // registry resolves both, and existing uuid entries still resolve.
+    // Repoint first: a written default whose symlink still points at another
+    // account is a wrong home that looks like success.
+    if (account.kind === 'native')
+        ensureAdoptedDefaultRepoint(agent, account, readMeta());
     updateMeta(meta => ({ ...meta, accounts: { ...meta.accounts, defaults: { ...meta.accounts?.defaults, [agent]: account.name } } }));
     return { agent, account };
 }
@@ -410,7 +447,7 @@ export async function runAccountsSwitch(harness, accountName, opts) {
         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>`);
+        throw new Error(`Selecting a ${agent} account requires an interactive terminal.\nUse: agents accounts default ${agent} <account>`);
     }
     const selected = await pickSwitchAccount(agent, rows);
     if (!selected)
@@ -498,69 +535,221 @@ export async function resolveLogoutTarget(target) {
     throw new Error(`Unknown target '${target}'. Pass a native harness (claude, codex, …), <harness>@<label>, <harness>#<account>, or a native account name. Provider API-key accounts use \`agents accounts remove\`.`);
 }
 export function registerAccountsCommand(program) {
-    const accounts = program.command('accounts').description('Browse native logins and manage provider account bundles')
+    const accounts = program.command('accounts').description('Browse and manage harness accounts')
         .option('--json', 'Machine-readable account metadata')
-        .option('--fleet', 'Show harness-native signed-in identities across reachable devices')
+        .option('--fleet', 'Show accounts as rows and devices as columns')
         .action(async (o, command) => {
         await runAccountsAction(command, () => printAccounts(!!o.json, !!o.fleet));
     });
-    accounts.command('list').description('List credential accounts').option('--json', 'Machine-readable account metadata').action(async (o, command) => {
-        await runAccountsAction(command, () => printAccounts(!!(o.json || command.optsWithGlobals().json)));
-    });
-    registerMintCommand(accounts);
-    const connectCmd = accounts.command('connect <harness> [name]')
-        .description('Connect a stable account: install the current release into a fresh isolated home and drive the harness native login (reconnect an existing account by name to reuse its home)')
-        .option('--json', 'Machine-readable connect result')
-        .action(async (harness, name, o, command) => {
-        await runAccountsAction(command, async () => {
-            const agent = parseHarness(harness);
-            const reason = connectRefusal(agent);
-            if (reason)
-                throw new Error(reason);
-            const result = await runConnect(agent, name, {
-                meta: readMeta(),
-                onProgress: (m) => console.log(chalk.gray(`  ${m}`)),
-            });
-            if (o.json || command.optsWithGlobals().json)
-                return console.log(JSON.stringify(result, null, 2));
-            const who = result.email ?? result.identityKey;
-            const named = result.name ? `'${result.name}' ` : '';
-            const release = result.releaseVersion ? ` [${result.releaseVersion}]` : '';
-            console.log(chalk.green(`${result.mode === 'reconnect' ? 'Reconnected' : 'Connected'} ${agent} account ${named}(${who}) in ${agent}@${result.label}${release}.`));
-            console.log(chalk.gray('  The native OAuth login stays owned by the harness in that home; nothing was copied.'));
-        });
+    const listCmd = accounts.command('list [harness]')
+        .description('List accounts with authentication verdict, device coverage, usage, and exact repair command')
+        .option('--json', 'Machine-readable account metadata')
+        .option('--fleet', 'Show accounts as rows and devices as columns')
+        .action(async (harness, o, command) => {
+        const globals = command.optsWithGlobals();
+        await runAccountsAction(command, () => printAccounts(!!(o.json || globals.json), !!(o.fleet || globals.fleet), harness));
     });
-    setHelpSections(connectCmd, {
-        examples: `agents accounts connect claude work
-agents accounts connect codex personal
-agents accounts connect claude work   # again → reuses work's home, fails closed on a different identity
-agents run claude --account work`,
-        notes: `Each NEW account gets a fresh opaque installation label and its own isolated home, so ten accounts can share the same upstream release while keeping separate logins. Connect installs the current release even when it is already installed under another label, then launches the harness's native login there — the OAuth credential is never copied or fleet-synced. Reconnecting an existing account by name reuses its home and refuses to overwrite a home now signed in as a different identity. Headed devices only: on a worker connect refuses before any slot, install, or browser — add the account on a personal/desktop box and provision workers from the durable credential. Supported for version-scoped, isolable harnesses (${connectSupportedList()}); others fail with a clear reason. Provider API-key/token accounts use 'agents accounts add' instead.`,
+    setHelpSections(listCmd, {
+        examples: `agents accounts list
+agents accounts list claude
+agents accounts list --json
+agents accounts list --fleet`,
+        notes: 'One row per account per harness. STATE is the daemon verdict. WHERE is `this box` when only this device reports (peers on an older release publish no slot verdicts), else live-device coverage. USAGE is the bar + percent. FIX is the exact repair command — empty when there is none. Reserved credential stores are not listed here; `agents secrets` is the place those show.',
     });
-    accounts.command('add <name>')
-        .description('Add a durable API key, setup token, or bearer token')
-        .requiredOption('--provider <provider>', `Credential provider (${listAccountProviders().join(', ')})`)
-        .requiredOption('--auth <type>', 'Credential type: api-key | setup-token | bearer-token')
-        .option('--base-url <url>', 'Optional endpoint override stored with the account')
-        .option('--from-secrets <bundle:key>', 'Import from an existing agents secrets entry')
-        .action(async (name, o, command) => {
+    registerMintCommand(accounts, undefined, { hidden: true });
+    const addCmd = accounts.command('add <target> [name]')
+        .description('Add an account. Harness form: add <harness> [name] runs the native login in a fresh credential slot and provisions workers. Provider form: add <name> --provider <p> --auth <t> stores a durable credential.')
+        .option('--api-key <key>', 'Worker credential for api-key harnesses (codex/grok/cursor/opencode); prompted when omitted')
+        .option('--per-device', 'codex: ChatGPT-plan account — no API key stored; workers log in per box')
+        .option('--no-worker-token', 'Skip minting/collecting the worker credential (this device only)')
+        .option('--provider <provider>', `Provider form: credential provider (${listAccountProviders().join(', ')})`)
+        .option('--auth <type>', 'Provider form: api-key | setup-token | bearer-token')
+        .option('--base-url <url>', 'Provider form: optional endpoint override stored with the account')
+        .option('--from-secrets <bundle:key>', 'Provider form: import from an existing agents secrets entry')
+        .option('--json', 'Machine-readable result (never includes a credential)')
+        .action(async (target, name, o, command) => {
         await runAccountsAction(command, async () => {
+            const json = !!(o.json || command.optsWithGlobals().json);
+            const agent = resolveAgentName(target);
+            const providerFlags = o.provider !== undefined || o.auth !== undefined || o.baseUrl !== undefined || o.fromSecrets !== undefined;
+            if (agent) {
+                // Harness form: an account is a credential slot, not a bundle.
+                if (providerFlags) {
+                    throw new Error(`'${target}' is a harness id — mixing the harness and provider forms is ambiguous. `
+                        + `Harness form: agents accounts add ${agent} [name]. `
+                        + `Provider form: agents accounts add <non-harness-name> --provider <p> --auth <t>.`);
+                }
+                const reason = addRefusal(agent);
+                if (reason)
+                    throw new Error(reason);
+                const result = await runAdd(agent, name, {
+                    meta: readMeta(),
+                    onProgress: (m) => { if (!json)
+                        console.log(chalk.gray(`  ${m}`)); },
+                    apiKey: o.apiKey,
+                    noWorkerToken: o.workerToken === false,
+                    perDevice: o.perDevice,
+                });
+                printAddResult(result, json);
+                return;
+            }
+            // Provider form (the pre-v2 `accounts add <name> --provider …`).
+            if (o.apiKey !== undefined || o.perDevice || o.workerToken === false) {
+                throw new Error(`'${target}' is not a harness id — --api-key/--per-device/--no-worker-token belong to the harness form: agents accounts add <harness> [name].`);
+            }
+            if (!o.provider || !o.auth) {
+                throw new Error(`'${target}' is not a harness id. Store a provider credential with: agents accounts add ${target} --provider <provider> --auth <type>. `
+                    + `Add a harness login with: agents accounts add <harness> [name].`);
+            }
             const auth = parseAuth(o.auth);
             const provider = getAccountProvider(o.provider);
             if (!provider.authKinds.includes(auth))
                 throw new Error(`Provider '${provider.provider}' does not support ${auth}. Supported: ${provider.authKinds.join(', ')}.`);
             const secret = o.fromSecrets
-                ? secretFromBundle(o.fromSecrets)
-                : await promptAccountSecret(`Enter ${provider.provider} ${auth} for '${name}':`);
+                ? await secretFromBundle(o.fromSecrets)
+                : await promptAccountSecret(`Enter ${provider.provider} ${auth} for '${target}':`);
             if (secret === null) {
                 process.exit(130);
                 return;
             }
-            const account = addAccount(name, provider.provider, auth, secret, undefined, { baseUrl: o.baseUrl });
+            const account = addAccount(target, 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.`));
         });
     });
+    setHelpSections(addCmd, {
+        examples: `agents accounts add claude work
+agents accounts add codex personal --api-key sk-…   # or omit --api-key to be prompted
+agents accounts add codex gmail --per-device        # ChatGPT-plan seat; workers log in per box
+agents accounts add claude                          # name derived from the login's email
+agents accounts add work --provider anthropic --auth setup-token   # provider form (non-harness name)
+agents run claude#work`,
+        notes: `Headed devices only: on a worker, add refuses before any slot, install, or browser — workers are provisioned automatically from the durable credential the add mints (claude: a setup-token; codex/grok/cursor/opencode: an API key via --api-key or a prompt; codex also accepts --per-device for a ChatGPT-plan seat; kimi/antigravity log in per box). An account is a credential SLOT, not a second installation: the harness has one managed install and each account is a HOME-shaped slot with its own native OAuth login (never copied, never fleet-synced). Re-running add for an already-added identity points at 'agents accounts login <harness>#<name>'. Supported: ${addSupportedList()}; other harnesses fail with the reason. An ambient CLAUDE_CODE_OAUTH_TOKEN in your shell refuses the mint (unset it or pass --no-worker-token).`,
+    });
+    const loginCmd = accounts.command('login <account>')
+        .description('Re-authenticate an account into its slot on this device (<harness>#<name>); re-mints and re-syncs the worker credential')
+        .option('--api-key <key>', 'Rotate the stored worker API key (api-key harnesses)')
+        .option('--no-worker-token', 'Skip re-minting the worker credential')
+        .option('--json', 'Machine-readable result (never includes a credential)')
+        .action(async (selector, o, command) => {
+        await runAccountsAction(command, async () => {
+            const json = !!(o.json || command.optsWithGlobals().json);
+            const parsed = parseAccountSelector(selector);
+            if (!parsed.agent) {
+                throw new Error(`Use the harness-qualified form: agents accounts login <harness>#<name> (e.g. claude#work).`);
+            }
+            const result = await runLogin(parsed.agent, parsed.name, {
+                meta: readMeta(),
+                onProgress: (m) => { if (!json)
+                    console.log(chalk.gray(`  ${m}`)); },
+                apiKey: o.apiKey,
+                noWorkerToken: o.workerToken === false,
+            });
+            printAddResult(result, json);
+        });
+    });
+    setHelpSections(loginCmd, {
+        examples: `agents accounts login claude#work
+agents accounts login codex#personal --api-key sk-…   # rotate the worker key
+agents accounts login kimi#main                       # per-device: logs THIS box in`,
+        notes: 'Re-runs the native login into the SAME slot (never a new home) and fails closed when the completed login is a different identity than the account. Headed devices only for harnesses with a portable worker credential; a per-device harness (kimi) may log in on any box — that is how that box gets its login. The daemon re-syncs the account row and worker credential after a successful login.',
+    });
+    const defaultCmd = accounts.command('default <harness> [name]')
+        .description('Set the fleet-wide default account for a harness (picker when no name)')
+        .option('--json', 'Machine-readable account list or the resulting default')
+        .action(async (harness, name, o, command) => {
+        await runAccountsAction(command, () => runAccountsSwitch(harness, name, { json: !!(o.json || command.optsWithGlobals().json) }));
+    });
+    setHelpSections(defaultCmd, {
+        examples: `agents accounts default claude
+agents accounts default claude work
+agents accounts default claude --json`,
+        notes: 'The one write path for the per-harness default (the hidden set-default/switch share it). Pass a name to skip the picker. Rotation already honors the default.',
+    });
+    const migrateCmd = accounts.command('migrate')
+        .description('Fold leftover per-account installations into 1 harness install + N credential slots')
+        .option('--dry-run', 'Print the plan and touch nothing (default)')
+        .option('--apply', 'Execute the plan: move homes into slots, trash empties/duplicates, re-index sessions')
+        .option('--json', 'Machine-readable plan or apply result')
+        .option('--device <name>', 'Run the migration on a fleet device over SSH')
+        .action(async (o, command) => {
+        await runAccountsAction(command, async () => {
+            const json = !!(o.json || command.optsWithGlobals().json);
+            if (o.dryRun && o.apply) {
+                throw new Error('Pass only one of --dry-run or --apply.');
+            }
+            const apply = !!o.apply;
+            if (o.device) {
+                const { isSelfHost } = await import('../lib/devices/self-host.js');
+                if (!isSelfHost(o.device)) {
+                    const { resolveHost } = await import('../lib/hosts/registry.js');
+                    const { streamAgentsOnHost } = await import('../lib/hosts/passthrough.js');
+                    const host = await resolveHost(o.device);
+                    if (!host)
+                        throw new Error(`Unknown device '${o.device}'.`);
+                    const flags = [apply ? '--apply' : '--dry-run'];
+                    if (json)
+                        flags.push('--json');
+                    const code = streamAgentsOnHost(host, ['accounts', 'migrate', ...flags], { interactive: false });
+                    process.exit(code);
+                    return;
+                }
+            }
+            if (!apply) {
+                const plan = await planAccountMigration();
+                if (json) {
+                    console.log(JSON.stringify(plan, null, 2));
+                    return;
+                }
+                console.log(formatMigrationPlan(plan));
+                if (plan.totals.slots + plan.totals.trash + plan.totals.deferred > 0) {
+                    console.log();
+                    console.log('Dry-run: nothing written. Re-run with --apply to execute.');
+                    console.log('Restore a trashed install with: agents trash restore <agent>@<label>');
+                }
+                return;
+            }
+            const result = await applyAccountMigration();
+            if (json) {
+                console.log(JSON.stringify({
+                    manifestPath: result.manifestPath,
+                    sessionsReindexed: result.sessionsReindexed,
+                    plan: result.plan,
+                    manifest: result.manifest,
+                }, null, 2));
+                return;
+            }
+            console.log(formatMigrationPlan(result.plan));
+            console.log();
+            console.log(`Wrote manifest: ${result.manifestPath}`);
+            console.log(`Re-indexed ${result.sessionsReindexed} session path${result.sessionsReindexed === 1 ? '' : 's'}.`);
+            console.log('Restore a trashed install with: agents trash restore <agent>@<label>');
+        });
+    });
+    setHelpSections(migrateCmd, {
+        examples: `agents accounts migrate --dry-run
+agents accounts migrate --apply
+agents accounts migrate --dry-run --device worker-1`,
+        notes: 'Folds leftover per-account installations (the old connect homes) into one managed install plus a HOME-shaped slot per identity. Empty logged-out homes and duplicate identities go to trash (agents trash restore reverses). A busy home is deferred, never moved. --apply is required to write; this upgrade only prints the dry-run report. Native OAuth files stay on this device inside the moved home.',
+    });
+    // Hidden legacy verb: connect is the old spelling of add.
+    const connectCmd = accounts.command('connect <harness> [name]', { hidden: true })
+        .description('Legacy alias of accounts add')
+        .option('--json', 'Machine-readable result')
+        .action(async (harness, name, o, command) => {
+        await runAccountsAction(command, async () => {
+            const agent = parseHarness(harness);
+            const reason = addRefusal(agent);
+            if (reason)
+                throw new Error(reason);
+            const result = await runAdd(agent, name, {
+                meta: readMeta(),
+                onProgress: (m) => console.log(chalk.gray(`  ${m}`)),
+            });
+            printAddResult(result, !!(o.json || command.optsWithGlobals().json));
+        });
+    });
+    retireVerb(connectCmd, 'agents accounts add <harness> [name]');
     accounts.command('set-key <name>')
         .description('Rotate an account credential without changing its identity')
         .option('--from-secrets <bundle:key>', 'Import from an existing agents secrets entry')
@@ -570,7 +759,7 @@ agents run claude --account work`,
             if (!account)
                 throw new Error(`Unknown provider account '${name}'.`);
             const secret = o.fromSecrets
-                ? secretFromBundle(o.fromSecrets)
+                ? await secretFromBundle(o.fromSecrets)
                 : await promptAccountSecret(`Enter new ${account.provider} ${account.auth} for '${name}':`);
             if (secret === null) {
                 process.exit(130);
@@ -621,7 +810,7 @@ agents run claude --account work`,
 agents accounts view codex#icloud`,
         notes: 'Native names are unique per harness. A bare name that exists for several harnesses is refused — pick one with <harness>#<name>.',
     });
-    accounts.command('name <source> <name>')
+    retireVerb(accounts.command('name <source> <name>', { hidden: true })
         .description('Name a signed-in native installation without copying its OAuth credentials')
         .action(async (source, name, _o, command) => {
         await runAccountsAction(command, async () => {
@@ -631,13 +820,14 @@ agents accounts view codex#icloud`,
             if (account.scope === 'device')
                 console.log(chalk.gray(`${identity.agent} authentication is device-scoped; attach '${account.name}' to '${identity.agent}', not an individual version.`));
         });
-    });
-    const labelCmd = accounts.command('label <source> [label]')
+    }), 'agents accounts add <harness> <name> (names are chosen at add time)');
+    const labelCmd = accounts.command('label <source> [label]', { hidden: true })
         .description('Label a native login by harness or <harness>@<version>; the label binds to the account identity, not the version')
         .option('--account <email-or-id>', 'Native identity to label when the harness has multiple logins')
         .action(async (source, label, o, command) => {
         await runAccountsAction(command, () => runAccountsLabel(source, label, o));
     });
+    retireVerb(labelCmd, 'agents accounts add <harness> <name> (rename: agents accounts rename <harness>#<old> <new>)');
     setHelpSections(labelCmd, {
         examples: `agents accounts label codex work
 agents accounts label codex@0.146.0 personal
@@ -645,7 +835,7 @@ agents accounts label codex work --account you@example.com
 agents run codex#work`,
         notes: 'The label binds to the signed-in account identity, not the version — codex#work keeps selecting that account after it moves to a newer install. Labels live on the central account rows in agents.yaml, which `agents repo push/pull` already syncs fleet-wide, keyed by (agent, identityKey). One signed-in login needs no selector; with several, an interactive terminal opens a picker, while scripts pass --account or <harness>@<version>.',
     });
-    accounts.command('attach <account> <target>')
+    retireVerb(accounts.command('attach <account> <target>', { hidden: true })
         .description('Attach a named account to a native installation or custom harness')
         .action(async (name, target, _o, command) => {
         await runAccountsAction(command, async () => {
@@ -712,8 +902,8 @@ agents run codex#work`,
             writeClaudeInteractiveOauthToken(t, targetAgent, account.kind === 'native' && account.agent === 'claude' ? account.identityLabel : undefined);
             console.log(chalk.green(`Attached ${account.name} to ${target}.`));
         });
-    });
-    accounts.command('detach <account> <target>')
+    }), 'agents run <harness>#<name> (accounts select by name; installation bindings are legacy)');
+    retireVerb(accounts.command('detach <account> <target>', { hidden: true })
         .description('Remove one account attachment')
         .action(async (name, target, _o, command) => {
         await runAccountsAction(command, () => {
@@ -736,7 +926,7 @@ agents run codex#work`,
             catch { /* an unresolvable target has no version home to clean */ }
             console.log(chalk.green(`Detached ${name} from ${target}.`));
         });
-    });
+    }), 'agents run <harness>#<name> (accounts select by name; installation bindings are legacy)');
     const renameCmd = accounts.command('rename <old> <new>')
         .description('Rename an account without changing its stable id. Target may be <harness>#<name> when the name exists for several harnesses')
         .action(async (oldName, newName, _o, command) => {
@@ -756,20 +946,21 @@ agents accounts rename codex#icloud cloud`,
         examples: `agents accounts remove claude#icloud`,
         notes: 'Native names are unique per harness. A bare name that exists for several harnesses is refused — pick one with <harness>#<name>.',
     });
-    accounts.command('set-default <agent> <name>')
+    retireVerb(accounts.command('set-default <agent> <name>', { hidden: true })
         .description('Use this account for a harness when --account is omitted')
         .action(async (agentRaw, name, _o, command) => {
         await runAccountsAction(command, () => {
             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]')
+    }), 'agents accounts default <harness> <name>');
+    const switchCmd = accounts.command('switch <harness> [account]', { hidden: true })
         .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 runAccountsAction(command, () => runAccountsSwitch(harness, account, { json: !!(o.json || command.optsWithGlobals().json) }));
     });
+    retireVerb(switchCmd, 'agents accounts default <harness> [name]');
     accounts.command('clear-default <agent>')
         .description('Return a harness to native login or balanced account selection')
         .action(async (agentRaw, _o, command) => {
@@ -844,7 +1035,7 @@ agents accounts rename codex#icloud cloud`,
                 AUTH_TYPE: account.auth,
                 ...(account.baseUrl ? { BASE_URL: account.baseUrl } : {}),
             };
-            const result = pushBundleToHost(account.name, device, {
+            const result = await pushBundleToHost(account.name, device, {
                 remoteBackend,
                 force: o.force,
                 operation: 'accounts sync',
@@ -865,24 +1056,20 @@ 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 connect claude work
-agents accounts connect codex personal
-agents accounts mint claude
-agents accounts mint claude --account work --email ada@example.com --fleet
+        examples: `agents accounts add claude work
+agents accounts add codex personal --api-key sk-…
+agents accounts login claude#work
+agents accounts default claude work
 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
 agents accounts set-key work
-agents accounts name claude@2.1.220 work
-agents accounts label codex@0.146.0 personal
-agents accounts attach work claude@2.1.225
 agents accounts view work --json
 agents accounts view codex#icloud
-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: 'Accounts are stable independent of releases: `accounts connect <harness> [name]` gives each new account a fresh isolated home on the current release and drives its native login (reconnect by name to reuse the home). Native account records contain metadata only; harness-owned OAuth credentials are never copied. Provider accounts are explicit portable bundles with policy never. `accounts mint claude` drives `claude setup-token` and seeds both the named account and the reserved file-based auth bundle (same command as `agents auth mint`). `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`.',
+agents run claude#work
+agents accounts logout claude
+agents accounts migrate --dry-run
+agents accounts migrate --apply`,
+        notes: 'An account is a credential SLOT, not an installation: `accounts add <harness> [name]` runs the native login in a fresh HOME-shaped slot of the one managed install, registers the fleet-wide row, and mints the durable worker credential (claude: setup-token; codex/grok/cursor/opencode: --api-key or a prompt) in one step. Headed devices only — workers are provisioned automatically. `accounts login <harness>#<name>` re-auths into the same slot and re-mints; `accounts default <harness> [name]` is the one default write path. 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`). Leftover per-account installations fold with `agents accounts migrate --dry-run|--apply`. Synced vault unlock is `agents secrets vault unlock`. The legacy connect/name/label/mint/attach/detach/switch/set-default verbs still work this release and print their replacement.',
     });
 }