@phnx-labs/agents-cli 1.20.67 → 1.20.69

package/dist/commands/doctor.js

@@ -1,13 +1,15 @@
 import { addHostOption } from '../lib/hosts/option.js';
 import { buildRemoteAgentsInvocation } from '../lib/hosts/remote-cmd.js';
 import { loadDevices, isControlDevice } from '../lib/devices/registry.js';
+import { fanOutDevices } from '../lib/devices/fleet.js';
 import { resolveHost } from '../lib/hosts/registry.js';
-import { sshExec } from '../lib/ssh-exec.js';
+import { sshExecAsync } from '../lib/ssh-exec.js';
 import { sshTargetFor } from '../lib/hosts/types.js';
 import { machineId } from '../lib/session/sync/config.js';
 import chalk from 'chalk';
 import { checkAllClis, collectTeamsDoctorData } from '../lib/teams/agents.js';
-import { AGENTS, ALL_AGENT_IDS, resolveAgentName, formatAgentError } from '../lib/agents.js';
+import { AGENTS, ALL_AGENT_IDS, resolveAgentName, formatAgentError, getAccountInfo } from '../lib/agents.js';
+import { formatSignInBadge } from '../lib/signin-badge.js';
 import { getGlobalDefault, getVersionHomePath, isVersionInstalled, listInstalledVersions, parseAgentSpec, } from '../lib/versions.js';
 import { loadManifest, isStale } from '../lib/staleness/index.js';
 import { diffVersionResources, DOCTOR_ALL_KINDS, } from '../lib/doctor-diff.js';
@@ -55,7 +57,7 @@ function printWrappedLine(prefix, text) {
     for (const line of wrapLine(prefix, text))
         console.log(chalk.gray(line));
 }
-function renderOverviewText(clis, syncRows, orphanRows, hostClis) {
+function renderOverviewText(clis, syncRows, orphanRows, hostClis, signIn) {
     console.log(chalk.bold('Agent CLIs'));
     // Show the fleet you actually run — agents that are ready in PATH, plus any
     // you MANAGE (have installed versions) whose binary isn't resolving (a real
@@ -72,7 +74,9 @@ function renderOverviewText(clis, syncRows, orphanRows, hostClis) {
         for (const [name, entry] of shown) {
             const pretty = (AGENT_NAMES[name] || name).padEnd(11);
             if (entry.installed) {
-                console.log(`  ${chalk.green('ready')}  ${pretty} ${chalk.gray(entry.path || '')}`);
+                const badge = formatSignInBadge(signIn[name]);
+                const pathHint = entry.path ? chalk.gray(`  ${entry.path}`) : '';
+                console.log(`  ${chalk.green('ready')}  ${pretty} ${badge}${pathHint}`);
             }
             else {
                 console.log(`  ${chalk.red('no   ')}  ${pretty} ${chalk.gray(entry.error || 'not installed')}`);
@@ -266,7 +270,7 @@ async function probeFleetTarget(target) {
     // has it via the install profile, and our single-quote escaping would
     // prevent $HOME expansion there, so skip the bootstrap on Windows.
     isWin ? undefined : { PATH: '$HOME/.agents/.cache/shims:$HOME/.local/bin:$PATH' });
-    const res = sshExec(target.sshTarget, remoteCmd, { timeoutMs: 30000, multiplex: true });
+    const res = await sshExecAsync(target.sshTarget, remoteCmd, { timeoutMs: 30000, multiplex: true });
     if (res.code !== 0) {
         return {
             name: target.name,
@@ -298,9 +302,18 @@ async function runDevicesDoctor(opts) {
     if (!singleName) {
         results.push({ name: localName, online: true, agents: await collectTeamsDoctorData() });
     }
-    // Remote targets in parallel.
-    const remoteResults = await Promise.all(targets.map(probeFleetTarget));
-    results.push(...remoteResults);
+    // Remote targets in parallel, through the shared fleet fan-out helper.
+    const remoteResults = await fanOutDevices(targets, probeFleetTarget);
+    results.push(...remoteResults.map((r) => {
+        if (r.status === 'ok' && r.value)
+            return r.value;
+        return {
+            name: r.name,
+            online: false,
+            error: r.error ?? String(r.reason ?? 'skipped'),
+            agents: {},
+        };
+    }));
     if (opts.json) {
         console.log(JSON.stringify({ devices: results }, null, 2));
         return;
@@ -710,9 +723,24 @@ export function registerDoctorCommand(program) {
             const syncRows = checkSyncStatus(cwd);
             const orphanRows = countOrphans();
             const hostClis = listCliStatus(cwd);
+            // Advisory login state per installed agent (file-based getAccountInfo,
+            // no home → the account-global/active credential). Best-effort: a probe
+            // failure just leaves that agent's badge as "logged out".
+            const signIn = {};
+            await Promise.all(Object.entries(clis)
+                .filter(([, e]) => e.installed)
+                .map(async ([name]) => {
+                try {
+                    signIn[name] = await getAccountInfo(name);
+                }
+                catch {
+                    /* advisory only */
+                }
+            }));
             if (opts.json) {
                 console.log(JSON.stringify({
                     clis,
+                    signIn,
                     sync: syncRows,
                     orphans: orphanRows,
                     hostClis: {
@@ -727,7 +755,7 @@ export function registerDoctorCommand(program) {
                 }, null, 2));
                 return;
             }
-            renderOverviewText(clis, syncRows, orphanRows, hostClis);
+            renderOverviewText(clis, syncRows, orphanRows, hostClis, signIn);
             // Point at the interactive reconcile when anything is out of sync — the
             // report shouldn't be a dead end. `agents status` runs the unified
             // home-reading engine and offers to sync (opt-in, never auto-fires here).

package/dist/commands/exec.d.ts

@@ -8,6 +8,24 @@
 import { type Command } from 'commander';
 import type { ExecEffort } from '../lib/exec.js';
 import { type SshGResult } from '../lib/hosts/ssh-config.js';
+export interface RunAccountPickerRequest {
+    requested: boolean;
+    normalizedAgentSpec: string;
+    valid: boolean;
+}
+/** Distinguish a terminal account-picker marker from an explicit @version pin. */
+export declare function parseRunAccountPickerRequest(agentSpec: string): RunAccountPickerRequest;
+/** Return every option whose routing semantics conflict with a local account choice. */
+export declare function runAccountPickerConflicts(options: {
+    resume?: string | boolean;
+    strategy?: string;
+    balanced?: boolean;
+    lease?: string | boolean;
+    host?: string;
+    device?: string;
+    on?: string;
+    computer?: string;
+}): string[];
 /** The host descriptor fields the `--copy-creds` security gate reads. */
 export interface CopyCredsGateHost {
     name: string;

package/dist/commands/exec.js

@@ -18,6 +18,31 @@ import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
 import { randomUUID } from 'crypto';
+/** Distinguish a terminal account-picker marker from an explicit @version pin. */
+export function parseRunAccountPickerRequest(agentSpec) {
+    const requested = agentSpec.endsWith('@');
+    const normalizedAgentSpec = requested ? agentSpec.slice(0, -1) : agentSpec;
+    return {
+        requested,
+        normalizedAgentSpec,
+        valid: !requested || (!!normalizedAgentSpec && !normalizedAgentSpec.includes('@')),
+    };
+}
+/** Return every option whose routing semantics conflict with a local account choice. */
+export function runAccountPickerConflicts(options) {
+    const conflicts = [];
+    if (options.resume !== undefined)
+        conflicts.push('--resume');
+    if (options.strategy !== undefined)
+        conflicts.push('--strategy');
+    if (options.balanced)
+        conflicts.push('--balanced');
+    if (options.lease)
+        conflicts.push('--lease');
+    if (options.host || options.device || options.on || options.computer)
+        conflicts.push('--host/--device');
+    return conflicts;
+}
 /** Type guard that narrows a string to a known AgentId. */
 function isValidAgent(agent) {
     return agent in AGENTS;
@@ -259,6 +284,7 @@ export function registerRunCommand(program) {
         .option('--json', 'Stream events as JSON lines (for parsing by other tools)')
         .option('--quiet', 'Suppress preamble (rotation banner, "Running:" line). Useful when piping JSON events to a parser.', false)
         .option('--headless', 'Force headless mode. Auto-enabled when a prompt is provided; pass explicitly to stay headless with no prompt (reads the prompt from stdin).', false)
+        .option('--no-auth-check', 'Skip the pre-launch "looks logged out" warning on an interactive run (advisory; never blocks anyway). Also silenced by AGENTS_NO_AUTH_CHECK=1.')
         .option('-i, --interactive', 'Force interactive mode even when a prompt is provided. Mutually exclusive with --headless.')
         .option('--resume [id]', 'Resume a previous conversation. Accepts a full or partial session id (prefix-matched against the index); omit the id to pick from recent sessions interactively. Resumes under the version that started the session. claude/codex resume natively; other agents replay via a /continue first message. Pair with a prompt to continue headlessly.')
         .option('--session-id <id>', 'Force a NEW conversation to use this exact session UUID (Claude only). This CREATES a session — to resume an existing one, use --resume.')
@@ -281,7 +307,7 @@ export function registerRunCommand(program) {
         .option('--interval <dur>', 'Loop delay between iterations ("0" back-to-back, "30m" paces). Loop only.')
         .option('--host <name>', 'Offload this run onto another machine over SSH instead of running locally — a device, a registered agent host, or user@host. See `agents devices` / `agents hosts`.')
         .option('--device <name>', 'Alias of --host: offload this run onto a registered device (from `agents devices`).')
-        .option('--remote-cwd <dir>', 'Explicit host working directory for --host runs (overrides --cwd; usually --cwd suffices).')
+        .option('--remote-cwd <dir>', "Explicit host working directory for --host runs, used VERBATIM (overrides --cwd; usually --cwd suffices — it re-roots a local-home path onto the remote home). Pass a single-quoted '$HOME/…' or a valid remote absolute path; a local ~ expands here and won't exist there (/Users/you vs /home/you).")
         .option('--no-follow', 'With --host, dispatch detached and return immediately (track via `agents hosts ps/logs`).')
         .option('--any', 'With --host <cap> (a capability tag), pick any matching host instead of erroring when several match.')
         .option('--copy-creds', 'With --host, copy the picked runtime credentials (and Claude OAuth token) to the host, then shred them after the run. Opt-in per run.')
@@ -307,6 +333,9 @@ export function registerRunCommand(program) {
       # Interactive (TUI) with the pinned default version
       agents run claude
 
+      # Pick a signed-in account/version for only this run
+      agents run claude@
+
       # Pipe JSON events to a parser (--quiet drops the preamble)
       agents run claude "..." --json --quiet | jq
 
@@ -341,6 +370,10 @@ export function registerRunCommand(program) {
         A version/account is skipped when it is rate-limited right now — any usage window (incl. the 5-hour session window) at 100%, matching the 'agents view' badge.
         --balanced is shorthand for --strategy balanced. Ignored when @version is pinned, when a profile is used, or with --fallback.
 
+      Account picker: append @ with no version (agents run claude@) to choose one
+        installed account for this run. Rows show identity, login state, plan,
+        and available limits; unsafe accounts stay visible but disabled.
+
       Fallback: --fallback codex,gemini retries on rate-limit failure via /continue handoff. Each entry accepts @version.
 
       Resume: --resume <id> continues a prior conversation (full or partial id; omit to pick interactively). claude/codex resume natively; others replay via a /continue first message. Add a prompt to continue headlessly.
@@ -369,6 +402,24 @@ export function registerRunCommand(program) {
             // a native flag, not a prompt. Run interactively.
             prompt = undefined;
         }
+        // A trailing @ is an explicit request to choose one installed account.
+        // Strip only that terminal marker; concrete agent@version pins retain
+        // their existing meaning in every dispatch path below.
+        const accountPicker = parseRunAccountPickerRequest(agentSpec);
+        const accountPickerRequested = accountPicker.requested;
+        const normalizedAgentSpec = accountPicker.normalizedAgentSpec;
+        if (!accountPicker.valid) {
+            console.error(chalk.red(`Invalid account picker target: ${agentSpec}. Use agents run <agent>@.`));
+            process.exit(1);
+        }
+        if (accountPickerRequested) {
+            const conflicts = runAccountPickerConflicts(options);
+            if (conflicts.length > 0) {
+                console.error(chalk.red(`Account selection with ${agentSpec} cannot be combined with ${conflicts.join(', ')}. ` +
+                    'Pick the account locally, or use an explicit agent@version target.'));
+                process.exit(1);
+            }
+        }
         // --lease: invent a disposable cloud box for this run (via crabbox), run
         // the agent there, then tear it down. Unlike --host, nothing is registered.
         if (options.lease) {
@@ -392,7 +443,7 @@ export function registerRunCommand(program) {
             const { leaseAndRun } = await import('../lib/crabbox/lease.js');
             const { getConfiguredRunStrategy, resolveRunVersion } = await import('../lib/rotate.js');
             const detected = await detectSignedInRuntimes();
-            const agentName = agentSpec.split('@')[0];
+            const agentName = normalizedAgentSpec.split('@')[0];
             const leaseCwd = options.cwd ?? process.cwd();
             // `--lease` requires a prompt (guarded above), so it is headless by
             // contract — never block on an interactive picker. Provision exactly the
@@ -595,7 +646,7 @@ export function registerRunCommand(program) {
                 throw e;
             }
             try {
-                const [runAgent, rawRunVersion] = agentSpec.split('@');
+                const [runAgent, rawRunVersion] = normalizedAgentSpec.split('@');
                 // Forward the explicit @version pin verbatim. Resolving aliases like
                 // @latest locally would check local installs, but the remote host may
                 // have versions the laptop does not. The remote agents CLI resolves
@@ -893,7 +944,7 @@ export function registerRunCommand(program) {
                 await warnUnpushedWork(resumeExec.cwd ?? process.cwd());
             process.exit(resumeExit);
         }
-        const [{ buildExecCommand, parseExecEnv, execAgent, runWithFallback, normalizeMode, resolveMode, headlessPlanStallCommand, nativeResume, resolveInteractive }, { ALL_AGENT_IDS }, { profileExists, resolveProfileForRun }, { readAndResolveBundleEnv, describeBundle, assertRemoteBundleFlagsUnsupported, isHeadlessSecretsContext }, { splitBundleRef, resolveSshTarget, remoteResolveEnv }, { getConfiguredRunStrategy, normalizeRunStrategy, resolveRunVersion, rotationFailoverChain, shouldArmRotationFailover, RUN_STRATEGIES }, { getGlobalDefault, getVersionHomePath, resolveVersion, resolveVersionAlias, ensureAgentRunnable }, { buildDiscoveredPlugin, loadPluginManifest, syncPluginToVersion }, { parseWorkflowFrontmatter, resolveWorkflowRef, resolveAllowedSubagents, pruneStaleWorkflowSubagents, ensureSubagentDispatchTool }, { resolveRunDefaults }, { getMcpServersByName, buildWorkflowMcpConfig }, { supports },] = await Promise.all([
+        const [{ buildExecCommand, parseExecEnv, execAgent, runWithFallback, normalizeMode, resolveMode, headlessPlanStallCommand, nativeResume, resolveInteractive }, { ALL_AGENT_IDS, ACCOUNT_INSPECTION_AGENT_IDS, agentLabel, supportsAccountInspection }, { profileExists, resolveProfileForRun }, { readAndResolveBundleEnv, describeBundle, assertRemoteBundleFlagsUnsupported, isHeadlessSecretsContext }, { splitBundleRef, resolveSshTarget, remoteResolveEnv }, { getConfiguredRunStrategy, normalizeRunStrategy, resolveRunVersion, rotationFailoverChain, shouldArmRotationFailover, RUN_STRATEGIES }, { getGlobalDefault, getVersionHomePath, resolveVersion, resolveVersionAlias, ensureAgentRunnable }, { buildDiscoveredPlugin, loadPluginManifest, syncPluginToVersion }, { parseWorkflowFrontmatter, resolveWorkflowRef, resolveAllowedSubagents, pruneStaleWorkflowSubagents, ensureSubagentDispatchTool }, { resolveRunDefaults }, { getMcpServersByName, buildWorkflowMcpConfig }, { supports },] = await Promise.all([
             import('../lib/exec.js'),
             import('../lib/agents.js'),
             import('../lib/profiles.js'),
@@ -909,7 +960,7 @@ export function registerRunCommand(program) {
         ]);
         const isValidAgent = (agent) => ALL_AGENT_IDS.includes(agent);
         // Parse agent@version
-        const [rawAgent, rawVersion] = agentSpec.split('@');
+        const [rawAgent, rawVersion] = normalizedAgentSpec.split('@');
         let agent;
         let version = rawVersion || undefined;
         let profileEnv;
@@ -937,6 +988,16 @@ export function registerRunCommand(program) {
         // degenerates to a no-op ("I'll wait for the completion notification").
         let workflowHasSubagents = false;
         const cwd = options.cwd ?? process.cwd();
+        if (accountPickerRequested && !isValidAgent(rawAgent)) {
+            if (profileExists(rawAgent)) {
+                console.error(chalk.red(`Account selection is not available for profile '${rawAgent}'. Run its concrete host agent with @ instead.`));
+                process.exit(1);
+            }
+            if (resolveWorkflowRef(rawAgent, cwd)) {
+                console.error(chalk.red(`Account selection is not available for workflow '${rawAgent}'. Run a concrete agent with @ instead.`));
+                process.exit(1);
+            }
+        }
         if (isValidAgent(rawAgent)) {
             agent = rawAgent;
         }
@@ -1160,6 +1221,28 @@ export function registerRunCommand(program) {
                 process.exit(1);
             }
         }
+        if (accountPickerRequested) {
+            if (!supportsAccountInspection(agent)) {
+                console.error(chalk.red(`${agentLabel(agent)} does not expose local account state, so agents-cli cannot safely select an account.`));
+                console.error(chalk.gray(`Supported account pickers: ${ACCOUNT_INSPECTION_AGENT_IDS.join(', ')}`));
+                process.exit(1);
+            }
+            try {
+                const { pickRunAccountCandidate } = await import('./run-account-picker.js');
+                const selected = await pickRunAccountCandidate(agent);
+                if (!selected)
+                    return;
+                version = selected.version;
+                if (!options.quiet) {
+                    const identity = selected.accountLabel || 'signed-in account';
+                    process.stderr.write(chalk.gray(`[agents] selected ${identity} · ${agent}@${selected.version} for this run\n`));
+                }
+            }
+            catch (err) {
+                console.error(chalk.red(err.message));
+                process.exit(1);
+            }
+        }
         version = resolveVersionAlias(agent, version);
         // --resume: resolve a prior conversation and rewrite the run target to
         // continue it. `version` here is already the alias-resolved candidate-version
@@ -1297,7 +1380,7 @@ export function registerRunCommand(program) {
         // the bare primary still resolves through the strategy — otherwise every
         // `agents run claude --fallback codex` run lands on the pinned default
         // account and account rotation silently stops (the gh-monitor heal bug).
-        if (strategy !== 'pinned' || options.balanced || explicitStrategy) {
+        if (!accountPickerRequested && (strategy !== 'pinned' || options.balanced || explicitStrategy)) {
             if (version) {
                 process.stderr.write(chalk.yellow(`[agents] strategy ${strategy} ignored: version ${version} is pinned\n`));
             }
@@ -1350,6 +1433,43 @@ export function registerRunCommand(program) {
             }
         }
         const defaultVersion = version ?? resolveVersion(agent, cwd);
+        // Login preflight (advisory, warn + continue). On a local INTERACTIVE
+        // launch, probe whether this agent's account has a credential and print a
+        // one-line warning if it looks logged out — so you find out BEFORE the TUI
+        // opens, not after typing a prompt and getting "/login" back. Uses the same
+        // account-global probe as `checkCliSignedIn` / `agents doctor`
+        // (getAccountInfo with no home): file-based, no Keychain ACL prompt, and
+        // correct for HOME-global credential agents (grok/codex) where a per-version
+        // home would false-negative. It can still false-negative for opaque
+        // credentials, so this NEVER blocks — it warns and launches anyway. Skipped
+        // for --json/--quiet, when a rotation already picked a signed-in account,
+        // and via --no-auth-check / AGENTS_NO_AUTH_CHECK=1. (--host/--lease return
+        // earlier.)
+        {
+            const { shouldCheckLoginBeforeLaunch, loginHint } = await import('../lib/signin-badge.js');
+            const preflight = shouldCheckLoginBeforeLaunch({
+                interactive: options.interactive,
+                forceInteractive, // a resumed interactive session (e.g. `run kimi --resume`) opens the TUI too
+                headless: options.headless,
+                hasPrompt: prompt !== undefined,
+                json: options.json,
+                quiet: options.quiet,
+                authCheckDisabled: options.authCheck === false || process.env.AGENTS_NO_AUTH_CHECK === '1',
+                rotated: !!rotationResult || accountPickerRequested,
+            });
+            if (preflight) {
+                try {
+                    const { getAccountInfo } = await import('../lib/agents.js');
+                    const info = await getAccountInfo(agent);
+                    if (!info.signedIn) {
+                        process.stderr.write(chalk.yellow(`⚠  ${agent} looks logged out — log in with: ${loginHint(agent)}. Launching anyway...\n`));
+                    }
+                }
+                catch {
+                    // Advisory only — a probe failure must never block a launch.
+                }
+            }
+        }
         const runDefaults = fromProfile
             ? { sources: {} }
             : resolveRunDefaults(agent, defaultVersion, cwd);

package/dist/commands/fork.d.ts

@@ -0,0 +1,9 @@
+/**
+ * `agents fork <session>` — branch an existing conversation into a new,
+ * independent session you can continue separately. The original is untouched.
+ *
+ * Thin command layer; the copy/register logic lives in `lib/session/fork.ts`.
+ */
+import type { Command } from 'commander';
+/** Register the top-level `agents fork` command. */
+export declare function registerForkCommand(program: Command): void;

package/dist/commands/fork.js

@@ -0,0 +1,67 @@
+import chalk from 'chalk';
+import { setHelpSections } from '../lib/help.js';
+import { findSessionsById } from '../lib/session/db.js';
+import { discoverSessions } from '../lib/session/discover.js';
+import { forkSession, isForkableAgent, FORKABLE_AGENTS } from '../lib/session/fork.js';
+/** Register the top-level `agents fork` command. */
+export function registerForkCommand(program) {
+    const cmd = program
+        .command('fork <session>')
+        .description('Branch a session into a new, independent copy you can continue separately. The original is untouched.')
+        .option('--name <label>', 'Label for the fork (default: "fork of <original>")');
+    setHelpSections(cmd, {
+        examples: `
+      # Fork a session by (partial) id, then continue the fork
+      agents fork 4f3a9c21
+      agents resume <new-id>
+
+      # Give the fork a name
+      agents fork 4f3a9c21 --name "try redis instead"
+    `,
+        notes: `
+      - 'resume' continues the SAME conversation; 'fork' copies it under a new id so the two diverge.
+      - The fork is a full copy of the conversation so far; continuing it never touches the original.
+      - Resolve the session the same way as resume: an exact or prefix id fragment.
+      - Currently supports: ${FORKABLE_AGENTS.join(', ')}. Other agents are a planned follow-up.
+    `,
+    });
+    cmd.action(async (sessionArg, options) => {
+        // Resolve the source. Try the index first; only pay for a rescan if the id
+        // isn't found yet (mirrors the resume path's freshen-then-lookup).
+        let matches = findSessionsById(sessionArg, {});
+        if (matches.length === 0) {
+            await discoverSessions({});
+            matches = findSessionsById(sessionArg, {});
+        }
+        if (matches.length === 0) {
+            console.log(chalk.red(`No session matching "${sessionArg}".`));
+            console.log(chalk.gray('List candidates with: agents sessions'));
+            return;
+        }
+        if (matches.length > 1) {
+            console.log(chalk.yellow(`"${sessionArg}" is ambiguous — ${matches.length} sessions match. Use a longer id:`));
+            for (const m of matches.slice(0, 8)) {
+                console.log(chalk.gray(`  ${m.shortId}  ${m.agent}  ${m.label || m.topic || ''}`));
+            }
+            return;
+        }
+        const source = matches[0];
+        if (!isForkableAgent(source.agent)) {
+            console.log(chalk.yellow(`fork does not support ${source.agent} sessions yet.`));
+            console.log(chalk.gray(`  Supported: ${FORKABLE_AGENTS.join(', ')}.`));
+            return;
+        }
+        let result;
+        try {
+            result = forkSession(source, { name: options.name });
+        }
+        catch (err) {
+            console.log(chalk.red(`Could not fork ${source.shortId}: ${err.message}`));
+            return;
+        }
+        console.log(chalk.green(`Forked ${source.shortId} -> ${result.shortId}`));
+        console.log(chalk.gray(`  Label:    ${result.label}`));
+        console.log(chalk.gray(`  Continue: agents resume ${result.shortId}`));
+        console.log(chalk.gray(`  Original ${source.shortId} is untouched.`));
+    });
+}

package/dist/commands/plugins.js

@@ -58,8 +58,14 @@ When to use:
   - Team onboarding: distribute a full toolkit via a single plugin directory
 `);
     // Shared list implementation — reused by `list` and the bare `agents plugins` default.
-    const runList = async () => {
+    const runList = async (options = {}) => {
         const plugins = discoverPlugins();
+        if (options.json) {
+            // Structured dump (name/description + per-agent-version sync targets) — the
+            // same rows the table is built from, mirroring `plugins marketplaces --json`.
+            console.log(JSON.stringify(plugins.length === 0 ? [] : buildPluginRows(plugins), null, 2));
+            return;
+        }
         if (plugins.length === 0) {
             console.log(chalk.gray('No plugins found in ~/.agents/plugins/'));
             console.log(chalk.gray('Plugins are directories with .claude-plugin/plugin.json'));
@@ -75,12 +81,15 @@ When to use:
             centralPath: getPluginsDir(),
         });
     };
-    // Bare `agents plugins` → same as `list`.
+    // Bare `agents plugins` → same as `list`. (--json lives on the explicit `list`
+    // subcommand only; declaring it on both parent + child makes commander bind the
+    // flag to the parent for `plugins list --json`, dropping it from the subcommand.)
     pluginsCmd.action(runList);
     // agents plugins list
     pluginsCmd
         .command('list')
         .description('Show plugins in a table with sync status across agent versions')
+        .option('--json', 'Emit machine-readable JSON')
         .action(runList);
     // agents plugins marketplaces
     const marketplacesCmd = pluginsCmd

package/dist/commands/repo.js

@@ -1,5 +1,6 @@
 import chalk from 'chalk';
 import { visibleWidth, padVisible } from '../lib/format.js';
+import { stripAnsi } from '../lib/session/width.js';
 import ora from 'ora';
 import * as fs from 'fs';
 import * as path from 'path';
@@ -28,7 +29,7 @@ function resolveRepoPath(target) {
     return path.join(HOME, `.agents-${trimmed}`);
 }
 import { applyExtraAliasToVersions, ensureAgentsDir, getExtraRepoDir, getSystemAgentsDir, getUserAgentsDir, readMeta, resolveExtraRepoDir, updateMeta, } from '../lib/state.js';
-import { parseSource, pullRepo, commitAndPush, isGitRepo, isSystemRepoOrigin, adoptRepo, displayHomePath, } from '../lib/git.js';
+import { parseSource, pullRepo, commitAndPush, isGitRepo, isSystemRepoOrigin, adoptRepo, getRemoteUrl, sameGitRemote, displayHomePath, } from '../lib/git.js';
 import { DEFAULT_SYSTEM_REPO } from '../lib/types.js';
 import { ALL_AGENT_IDS, isAgentName, resolveAgentName } from '../lib/agents.js';
 import { refresh } from '../lib/refresh.js';
@@ -444,10 +445,22 @@ async function listRepos(alias, opts = {}) {
         return;
     }
     if (targets.length === 0) {
+        if (opts.json) {
+            console.log('[]');
+            return;
+        }
         console.log(chalk.gray('No repos to show.'));
         return;
     }
     const rows = await Promise.all(targets.map(renderRepoRow));
+    if (opts.json) {
+        // Structured dump of the same rows so agents can enumerate repos + sync state.
+        // `raw` (the missing / no-git-remote human label) is the only colored field —
+        // strip ANSI so the JSON stays clean; every other field is already structured.
+        const clean = rows.map((r) => (r.raw !== undefined ? { ...r, raw: stripAnsi(r.raw) } : r));
+        console.log(JSON.stringify(clean, null, 2));
+        return;
+    }
     // TTY width when interactive; fall back to $COLUMNS (honored when piped) then 80.
     const cols = process.stdout.columns || Number(process.env.COLUMNS) || 80;
     console.log('');
@@ -600,6 +613,7 @@ export function registerRepoCommands(program) {
         .command('add <source>')
         .description('Register an existing local repo or clone a remote repo into ~/.agents-<alias>/')
         .option('--as <alias>', 'Override the auto-derived alias (letters, digits, _ or -)')
+        .option('--adopt', 'If the target directory already holds a git checkout, register it in place instead of erroring (even if its origin differs)')
         .action(async (source, options) => {
         const meta = readMeta();
         const extras = { ...(meta.extraRepos || {}) };
@@ -637,7 +651,36 @@ export function registerRepoCommands(program) {
         ensureAgentsDir();
         const targetDir = getExtraRepoDir(alias);
         if (fs.existsSync(targetDir)) {
-            console.log(chalk.red(`Directory already exists: ${targetDir}`));
+            // Adopt an existing checkout instead of hard-erroring. The common case:
+            // the user already cloned ~/.agents-<alias> by hand, then ran `repos add`
+            // and hit a dead end — which forced a second, inconsistent install method.
+            // If it's already a git repo whose origin matches the requested source,
+            // register it in place (no re-clone); adopt a mismatched/remoteless repo
+            // only with an explicit --adopt.
+            if (isGitRepo(targetDir)) {
+                const existingUrl = await getRemoteUrl(targetDir);
+                const matches = sameGitRemote(existingUrl, parsed.url);
+                if (matches || options.adopt) {
+                    const log = await simpleGit(targetDir).log({ maxCount: 1 }).catch(() => null);
+                    const commit = log?.latest?.hash.slice(0, 8) || 'unknown';
+                    extras[alias] = { url: parsed.url, path: targetDir, enabled: true };
+                    updateMeta({ extraRepos: extras });
+                    syncExtraAliasAcrossVersions(alias, true);
+                    syncMarketplacesForDefaults();
+                    console.log(chalk.green(`Adopted existing repo "${alias}" -> ${targetDir} (${commit})`));
+                    if (!matches) {
+                        console.log(chalk.gray(`  note: its origin is ${existingUrl ?? '(none)'}, not ${parsed.url} — adopted via --adopt.`));
+                    }
+                    console.log(chalk.gray(`Skills and commands from this repo will be picked up the next time you launch any agent.`));
+                    return;
+                }
+                console.log(chalk.red(`Directory already exists and is a different repo: ${targetDir}`));
+                console.log(chalk.gray(`  its origin is ${existingUrl ?? '(none)'}, not ${parsed.url}.`));
+                console.log(chalk.gray('  Adopt it anyway with --adopt, or pick a different alias with --as.'));
+                process.exitCode = 1;
+                return;
+            }
+            console.log(chalk.red(`Directory already exists (and is not a git repo): ${targetDir}`));
             console.log(chalk.gray('Remove it manually or pick a different alias with --as.'));
             process.exitCode = 1;
             return;
@@ -676,6 +719,7 @@ export function registerRepoCommands(program) {
         .alias('ls')
         .description('Show all repos with resource-level sync (skills/commands/plugins to pull or push) and local changes.')
         .option('-v, --verbose', 'Full per-resource detail in a table, regardless of terminal width')
+        .option('--json', 'machine-readable JSON output')
         .action(async (alias, options) => {
         await listRepos(alias, options);
     });
@@ -951,6 +995,7 @@ export function registerRepoCommands(program) {
         .command('status [alias]', { hidden: true })
         .description('Alias of `list` (kept for muscle memory).')
         .option('-v, --verbose', 'Full per-resource detail in a table, regardless of terminal width')
+        .option('--json', 'machine-readable JSON output')
         .action(async (alias, options) => {
         await listRepos(alias, options);
     });

package/dist/commands/run-account-picker.d.ts

@@ -0,0 +1,14 @@
+import type { AgentId } from '../lib/types.js';
+import { type RotateCandidate } from '../lib/rotate.js';
+export interface RunAccountChoice {
+    name: string;
+    value: string;
+    disabled?: string;
+    ready: boolean;
+}
+/** Human-readable remaining capacity for every window the provider exposes. */
+export declare function formatAccountLimits(candidate: RotateCandidate): string;
+/** Build aligned picker rows with usable accounts first and unsafe rows disabled. */
+export declare function buildRunAccountChoices(candidates: RotateCandidate[], globalDefault: string | null): RunAccountChoice[];
+/** Prompt for one safe installed account/version. A cancelled picker launches nothing. */
+export declare function pickRunAccountCandidate(agent: AgentId): Promise<RotateCandidate | null>;