@phnx-labs/agents-cli 1.20.66 → 1.20.68

package/CHANGELOG.md

@@ -1,5 +1,93 @@
 # Changelog
 
+## 1.20.68
+
+- **MCP resource handler now syncs project-level agent configs alongside user-level configs (RUSH-671).** `McpHandler.sync` previously wrote resolved MCP servers only to the version-home (user-level) config path. It now also writes project-layer MCP servers to each agent CLI's project-level config path (e.g., `.mcp.json` for Claude, `.codex/config.toml` for Codex) so agent CLIs can discover project-scoped MCPs natively. User-level sync is unchanged. Source: `apps/cli/src/lib/resources/mcp.ts`, `apps/cli/src/lib/agents.ts` (`getProjectMcpConfigPath` exported), `apps/cli/src/lib/resources/mcp.test.ts`.
+- **Production MCP sync path also writes project-level configs.** `installMcpServers` now merges project-layer servers into the agent's project-level config file, using a shared `writeMcpConfig` serializer with overwrite/merge modes. OpenClaw serialization is corrected to nest under `mcp.servers`, matching the existing reader; Grok/OpenClaw user-level configs are written directly with merge mode so multiple servers don't clobber each other; and `installMcpServers` only reports `applied` for agents it actually wrote a config for. Source: `apps/cli/src/lib/mcp.ts`, `apps/cli/src/lib/mcp.test.ts`.
+
+- **Accurate account tier and legible usage limits in `agents view`.** Each row's plan
+  tier is now derived from `organizationType` (Max/Pro/Team/Enterprise) instead of a
+  billingType guess that mislabelled every Max account as "Pro", and the redundant tier
+  badge next to the email is dropped for personal plans (multi-seat orgs keep their org
+  name, which is real identity). The compact `S:`/`W:` usage bars now show the exact
+  percentage and a compact reset hint (`S: ███░░ 58% (3d)`), a signed-in account whose
+  usage can't be fetched reads `usage unavailable` instead of a blank gauge, and a new
+  `agents view --refresh` (`-r`) forces a live usage refresh past the cache. Source:
+  `apps/cli/src/lib/agents.ts`, `apps/cli/src/lib/usage.ts`, `apps/cli/src/commands/view.ts`.
+
+- **Fleet health status and drift gate.** `agents fleet status` now renders a fleet-wide warnings rollup plus a device matrix for reachability, resource headroom, sync drift, CLI readiness, and agents-cli version skew; `--json` emits the same report for scripts and `--strict` exits non-zero when any warning is present. `agents check --devices` now fans the existing drift gate across registered devices and exits non-zero when any device is drifted or unreachable. Source: `apps/cli/src/commands/ssh.ts`, `apps/cli/src/commands/check.ts`, `apps/cli/src/lib/devices/fleet.ts`, `apps/cli/src/lib/devices/health-report.ts`.
+
+- **Login state per agent — `agents doctor` shows signed-in/logged-out, and `agents run` warns before launching into a logged-out account.** `agents doctor`'s **Agent CLIs** section now renders a `✓ signed in <account>` / `✗ logged out` badge per installed agent (also surfaced in `--json` under `signIn`), and an interactive `agents run <agent>` now prints a one-line stderr warning — `⚠ <agent> looks logged out — log in with: <cmd>. Launching anyway...` — when the account looks logged out, so you find out **before** the TUI opens instead of after typing a prompt and getting `/login` back. It is advisory (file-based `getAccountInfo`, no Keychain ACL prompt) and **never blocks**: skipped for `--json`/`--quiet`, when a rotation already picked a signed-in account, for `--host`/`--lease`, and via `--no-auth-check` / `AGENTS_NO_AUTH_CHECK=1`. `agents view`'s logged-out line now names the exact login command too. One shared badge/hint renderer keeps all three surfaces consistent across claude, codex, kimi, grok, opencode, and gemini. Source: `apps/cli/src/lib/signin-badge.ts` (+ `signin-badge.test.ts`), `apps/cli/src/commands/exec.ts`, `apps/cli/src/commands/doctor.ts`, `apps/cli/src/commands/view.ts`.
+
+- **`agents repos add` adopts an existing checkout instead of dead-ending.** When
+  the target `~/.agents-<alias>/` already holds a git repo whose origin matches the
+  requested source, `repos add` now registers it in place (no re-clone) rather than
+  erroring `Directory already exists`. A repo with a *different* origin is left
+  untouched unless you pass `--adopt`. This removes the trap that forced a second,
+  inconsistent install method when a repo had been cloned by hand. Remote matching
+  is transport-agnostic (SSH and HTTPS forms of the same repo compare equal). Source:
+  `apps/cli/src/commands/repo.ts`, `apps/cli/src/lib/git.ts`.
+
+- **`--json` for `repos list` and `plugins list`.** Both list commands now emit
+  machine-readable JSON with `--json`, matching the `repos view --json` /
+  `plugins marketplaces --json` that already existed — so an agent can enumerate
+  registered repos (with per-repo sync/drift state) and installed plugins (with
+  per-agent-version sync targets) without scraping the human table. Source:
+  `apps/cli/src/commands/repo.ts`, `apps/cli/src/commands/plugins.ts`.
+
+- **`teams add --remote-cwd` now fails loud instead of silently doing nothing.** The
+  flag rides the shared `--host` option family but `teams add` treats
+  `--host`/`--device` as placement and never reads it, so passing it used to be a
+  silent no-op that misled you into thinking it set the teammate's repo path. It is
+  now rejected with guidance (place with `--device`, set the code with the team's
+  `--repo`, one team per repo). The shared `--remote-cwd` help also warns that a
+  local `~` expands on your machine, not the remote host — pass a single-quoted
+  `'$HOME/…'` path or a valid remote absolute path. Teams docs + skill lead with
+  this. Source: `apps/cli/src/commands/teams.ts` (`remoteCwdOnAddError`),
+  `apps/cli/src/lib/hosts/option.ts`, `apps/cli/docs/teams.md`, `skills/teams/SKILL.md`.
+
+- **No more CLIXML blobs from Windows hosts.** A remote `agents …` invocation
+  routed to a Windows box (`--host win-mini`, `agents doctor --devices`,
+  `agents fleet status`) no longer comes back wrapped in a raw `#< CLIXML <Objs …>`
+  envelope. PowerShell 5.1 serializes its progress stream ("Preparing modules for
+  first use.") to CLIXML when stderr is a captured pipe rather than a console; the
+  Windows command builder now silences that stream (`$ProgressPreference =
+  'SilentlyContinue'`) so failures read as plain text for humans and the JSON
+  parsers that consume the output. Source: `apps/cli/src/lib/hosts/remote-cmd.ts`.
+
+## 1.20.67
+
+- **Interactive session browser — `agents sessions --active` and a bare `agents sessions`
+  now open a live, filterable picker on a TTY (RUSH-1802).** One canonical filter driven by
+  single keys, re-pulled across the fleet as you toggle: `s` search, `r` running-only, `c`
+  teams, `a` agent (cycles), `d` device (cycles), `p` this-repo↔all-dirs, `w` time window;
+  filters **stack** (AND together) and the active set shows in the header, with a live
+  preview of the highlighted row and `⏎` to resume/attach via the existing dispatch. Every
+  hotkey mirrors a flag, so the view is reproducible as a command — `y` copies (and
+  `--print-cmd` prints) the exact `ag sessions …` line the filters map to, bridging the
+  human picker and the agent/script flag surface. The interactive front-end is TTY-only:
+  `--json`, a pipe, or the new `--no-interactive` keep the existing static listing verbatim,
+  so scripts and headless agents are unchanged. Adds `-p` as the short form of `--project`,
+  `--print-cmd`, `--preview` (`agents sessions <id> --preview` prints the compact digest
+  without the pager), and `--no-interactive`. Built on a new async-refetch `dynamicPicker`
+  variant that reuses the existing render/pagination/preview machinery, the fleet SSH
+  fan-out, and the resume/focus path. Source: `apps/cli/src/lib/picker.ts` (`dynamicPicker`),
+  `apps/cli/src/commands/sessions-browser.ts` (+ `sessions-browser.test.ts`),
+  `apps/cli/src/commands/sessions.ts`.
+
+- **kimi/grok headless `--mode plan` now auto-downgrades to `auto` instead of
+  crashing or stalling (RUSH-1810).** kimi's headless `-p` refuses to combine with
+  `--plan` (it hard-failed at spawn) and grok's `--permission-mode plan` silently
+  stalls a headless run at its ExitPlanMode gate. Both now model this honestly with
+  a `capabilities.headlessPlan: false` flag: a headless plan request degrades to
+  `auto` (kimi `-p` auto-runs; grok maps `auto`→`edit`) with a one-line stderr
+  warning, mirroring the graceful plan→edit degrade cursor/antigravity already get.
+  Interactive plan is unchanged, and claude/codex/droid/opencode keep read-only
+  plan headless. The same downgrade covers `agents run`, `agents teams add`
+  teammates, and routine jobs. Source: `apps/cli/src/lib/exec.ts`
+  (`resolveHeadlessMode`), `apps/cli/src/lib/runner.ts`, `apps/cli/src/lib/agents.ts`,
+  `apps/cli/src/lib/types.ts`.
+
 ## 1.20.66
 
 - **Fix (`agents monitors`, RUSH-1782 follow-up): `--watch-device` no longer silently watches the local machine on a bad name.** An unregistered or mistyped `--watch-device` name is now rejected at `add` time (same registry gate as `--device`/`--devices`), and the device source evaluator returns an explicit `device not registered` observation instead of falling back to local stats if a watched device is removed later — closing a "monitors the wrong box, silently" gap. The rate-limit firehose trip now also writes a fire record (`ok:false, error:'rate limited'`), so `agents monitors runs` reflects the auto-pause that `view`'s `last fired` already showed. Adds `sources/device.test.ts`. Source: `apps/cli/src/lib/monitors/sources/device.ts`, `apps/cli/src/commands/monitors.ts`, `apps/cli/src/lib/monitors/engine.ts`.

package/README.md

@@ -424,6 +424,9 @@ agents sync --host gpu-box              # make the remote machine current
 agents doctor --devices                 # readiness matrix for every registered device
 agents doctor --devices --json          # machine-readable fleet readiness
 agents doctor --device mac-mini         # same matrix, scoped to one device
+agents fleet status                     # warnings rollup + health/sync/version matrix
+agents fleet status --json --strict     # scriptable fleet health gate
+agents check --devices                  # CI drift gate across every registered device
 
 # Your Tailscale fleet, auto-discovered
 agents devices sync                     # ingest `tailscale status`

package/dist/commands/check.js

@@ -2,6 +2,11 @@ import chalk from 'chalk';
 import { AGENTS, ALL_AGENT_IDS } from '../lib/agents.js';
 import { setHelpSections } from '../lib/help.js';
 import { computeDrift } from '../lib/drift.js';
+import { loadDevices } from '../lib/devices/registry.js';
+import { fanOutDevices, planFleetTargets, remoteFleetTargets } from '../lib/devices/fleet.js';
+import { machineId } from '../lib/session/sync/config.js';
+import { buildRemoteAgentsInvocation } from '../lib/hosts/remote-cmd.js';
+import { sshExecAsync } from '../lib/ssh-exec.js';
 const AGENT_NAMES = Object.fromEntries(ALL_AGENT_IDS.map((id) => [id, AGENTS[id].name]));
 function label(row) {
     return `${AGENT_NAMES[row.agent] || row.agent}@${row.version}`;
@@ -12,7 +17,8 @@ export function registerCheckCommand(program) {
         .description('CI drift gate: exit non-zero when any installed version is out of sync (stale or never-synced), zero when clean.')
         .option('--json', 'Output machine-readable JSON')
         .option('-q, --quiet', 'Suppress per-version lines; print only the one-line verdict')
-        .option('--cwd <path>', 'Resolution cwd for project layer detection (default: process.cwd())');
+        .option('--cwd <path>', 'Resolution cwd for project layer detection (default: process.cwd())')
+        .option('--devices', 'Run the drift gate across every registered online device');
     setHelpSections(checkCmd, {
         examples: `
       # Fail the build if anything drifted (exit 1), pass if clean (exit 0)
@@ -24,12 +30,19 @@ export function registerCheckCommand(program) {
       # Machine-readable, for scripting
       agents check --json
 
+      # Gate every registered device
+      agents check --devices
+
       # Gate in a CI step
       agents check || { echo "resources drifted — run 'agents doctor --fix'"; exit 1; }
     `,
     });
-    checkCmd.action((opts) => {
+    checkCmd.action(async (opts) => {
         const cwd = opts.cwd ? opts.cwd : process.cwd();
+        if (opts.devices) {
+            await runDevicesCheck(opts, cwd);
+            return;
+        }
         const drift = computeDrift(cwd);
         if (opts.json) {
             console.log(JSON.stringify({
@@ -82,3 +95,84 @@ export function registerCheckCommand(program) {
         process.exit(1);
     });
 }
+function checkPayload(device, drift) {
+    return {
+        device,
+        hasDrift: drift.hasDrift,
+        stale: drift.staleCount,
+        neverSynced: drift.neverSyncedCount,
+        orphanVersions: drift.orphanVersionCount,
+    };
+}
+async function probeDeviceCheck(target) {
+    const isWin = /^win/i.test((target.platform ?? '').trim());
+    const remoteCmd = buildRemoteAgentsInvocation(['check', '--json'], undefined, isWin ? 'windows' : undefined, isWin ? undefined : { PATH: '$HOME/.agents/.cache/shims:$HOME/.local/bin:$PATH' });
+    const res = await sshExecAsync(target.name, remoteCmd, { timeoutMs: 30000, multiplex: true });
+    if (res.code !== 0 && !res.stdout.trim()) {
+        throw new Error(res.timedOut ? 'timed out' : (res.stderr.trim() || `exit ${res.code ?? 'unknown'}`));
+    }
+    try {
+        const parsed = JSON.parse(res.stdout);
+        return {
+            device: target.name,
+            hasDrift: Boolean(parsed.hasDrift),
+            stale: parsed.stale ?? 0,
+            neverSynced: parsed.neverSynced ?? 0,
+            orphanVersions: parsed.orphanVersions ?? 0,
+        };
+    }
+    catch (err) {
+        throw new Error(`invalid JSON (${err?.message ?? 'parse error'})`);
+    }
+}
+async function runDevicesCheck(opts, cwd) {
+    const registry = await loadDevices();
+    const self = machineId();
+    const planned = planFleetTargets(registry);
+    const local = checkPayload(self, computeDrift(cwd));
+    const remoteTargets = remoteFleetTargets(planned, self)
+        .map((t) => ({
+        name: t.device.name,
+        platform: t.device.platform,
+        skip: t.skip,
+    }));
+    const remote = await fanOutDevices(remoteTargets, probeDeviceCheck);
+    const devices = [local];
+    for (const result of remote) {
+        if (result.status === 'ok' && result.value) {
+            devices.push(result.value);
+        }
+        else {
+            devices.push({
+                device: result.name,
+                hasDrift: true,
+                stale: 0,
+                neverSynced: 0,
+                orphanVersions: 0,
+                error: result.error ?? String(result.reason ?? 'skipped'),
+            });
+        }
+    }
+    const hasDrift = devices.some((d) => d.hasDrift || d.error);
+    if (opts.json) {
+        console.log(JSON.stringify({ hasDrift, devices }, null, 2));
+        process.exit(hasDrift ? 1 : 0);
+    }
+    if (!hasDrift) {
+        console.log(chalk.green('ok') + chalk.gray(`  ${devices.length} device(s) in sync`));
+        process.exit(0);
+    }
+    console.error(chalk.red('drift') + chalk.gray(`  ${devices.filter((d) => d.hasDrift || d.error).length} of ${devices.length} device(s)`));
+    if (!opts.quiet) {
+        for (const d of devices) {
+            if (!d.hasDrift && !d.error)
+                continue;
+            const detail = d.error
+                ? d.error
+                : [`${d.stale} stale`, `${d.neverSynced} never-synced`].filter((p) => !p.startsWith('0 ')).join(', ');
+            console.error(`  ${chalk.yellow(d.device.padEnd(18))} ${detail || 'drift'}`);
+        }
+        console.error(chalk.gray('\nReconcile each device with `agents doctor --fix` or `agents repo pull user`.'));
+    }
+    process.exit(1);
+}

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

@@ -259,6 +259,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 +282,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.')
@@ -328,6 +329,12 @@ export function registerRunCommand(program) {
         skip  bypass every permission prompt (dangerously-skip-permissions)
         Legacy 'full' is silently rewritten to 'skip'.
 
+      Headless plan support (a prompt makes the run headless):
+        plan works headless on claude, codex, droid, opencode.
+        kimi, grok, cursor, antigravity have no headless plan mode — a headless
+        --mode plan auto-downgrades to --mode auto (with a stderr warning).
+        Interactive plan (omit the prompt) works everywhere it is listed.
+
       Run strategy (set via --strategy or run.<agent>.strategy in agents.yaml):
         pinned     use the workspace/global pinned version
         available  use pinned if it can run right now; otherwise switch to another signed-in version
@@ -1344,6 +1351,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,
+            });
+            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/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);
     });