@phnx-labs/agents-cli 1.20.26 → 1.20.28

package/dist/commands/sessions.d.ts

@@ -1,6 +1,7 @@
 import type { Command } from 'commander';
 import type { SessionMeta } from '../lib/session/types.js';
 import { type ActiveSession } from '../lib/session/active.js';
+import { type PickedSession } from './sessions-picker.js';
 /** Grouped + sorted view of active sessions for the --active renderer. */
 export interface ActiveSessionsLayout {
     workspaces: Array<{
@@ -28,6 +29,7 @@ export interface ActiveSessionsLayout {
  *   - sessions within a window/flat bucket: input order preserved
  */
 export declare function groupActiveSessions(sessions: ActiveSession[]): ActiveSessionsLayout;
+export declare function pickSessionInteractive(sessions: SessionMeta[], message?: string, initialSearch?: string, hiddenCount?: number): Promise<PickedSession | null>;
 /**
  * Build the shell command that resumes a picked session.
  *

package/dist/commands/sessions.js

@@ -20,6 +20,8 @@ import { getActiveSessions } from '../lib/session/active.js';
 import { discoverSessions, countSessionsInScope, resolveSessionById, searchContentIndex } from '../lib/session/discover.js';
 import { filterTeamSessions } from '../lib/session/team-filter.js';
 import { parseSession } from '../lib/session/parse.js';
+import { runRemoteSessions } from '../lib/session/remote.js';
+import { formatRelativeTime } from '../lib/session/relative-time.js';
 import { renderConversationMarkdown, renderSummary, renderSummaryHeader, computeSummaryStats, renderJson, filterEvents, parseRoleList } from '../lib/session/render.js';
 import { renderMarkdown } from '../lib/markdown.js';
 import { colorAgent, resolveAgentName } from '../lib/agents.js';
@@ -313,6 +315,16 @@ async function renderActiveSessions(asJson) {
 }
 /** Main action handler for `agents sessions`. Routes to picker, table, or single-session render. */
 async function sessionsAction(query, options) {
+    if (options.host && options.host.length > 0) {
+        try {
+            runRemoteSessions(options.host);
+        }
+        catch (err) {
+            console.error(chalk.red(err.message));
+            process.exit(1);
+        }
+        return;
+    }
     if (options.active) {
         await renderActiveSessions(options.json === true);
         return;
@@ -645,7 +657,7 @@ function formatPickerLabel(s, query) {
         renderTopicCell(label, topic, query, 48, 50) +
         chalk.gray(when));
 }
-async function pickSessionInteractive(sessions, message = 'Search sessions:', initialSearch, hiddenCount = 0) {
+export async function pickSessionInteractive(sessions, message = 'Search sessions:', initialSearch, hiddenCount = 0) {
     if (hiddenCount > 0) {
         console.log(chalk.gray(formatTeamHiddenFooter(hiddenCount)));
     }
@@ -1116,7 +1128,8 @@ export function registerSessionsCommands(program) {
         .option('--artifacts', 'List all files written or edited during a session')
         .option('--artifact <name>', 'Read a specific artifact by filename or path (outputs to stdout)')
         .option('--active', 'Show only sessions running right now across terminals, teams, cloud, and headless agents')
-        .option('--cloud', 'Source sessions from Rush Cloud (captured runs) instead of local disk');
+        .option('--cloud', 'Source sessions from Rush Cloud (captured runs) instead of local disk')
+        .option('-H, --host <target...>', 'Run this query on remote machine(s) over SSH (host alias or user@host; repeatable)');
     setHelpSections(sessionsCmd, {
         examples: `
       # Search prior sessions in this project by topic, file path, or command
@@ -1136,8 +1149,15 @@ export function registerSessionsCommands(program) {
 
       # Export for analysis
       agents sessions --since 30d --limit 200 --json > sessions.json
+
+      # Search another machine's sessions live over SSH (no sync needed)
+      agents sessions "auth bug" --last 3 --host yosemite-s1
+
+      # Fan the same query out across several machines
+      agents sessions --all "deploy script" --host box-a --host box-b
     `,
         notes: `
+      - --host runs the query on the remote's own index over SSH (host alias or user@host); repeat or pass several to fan out. SSH access is the only auth.
       - --include and --exclude are mutually exclusive.
       - --first and --last are mutually exclusive.
       - A filter flag (--include/--exclude/--first/--last) without --markdown/--json defaults to --markdown output.
@@ -1313,7 +1333,11 @@ function findClaudeResumeTimestamp(filePath, targetTimestampMs) {
     }
 }
 function isWithinProject(sessionCwd, projectRoot) {
-    return sessionCwd === projectRoot || sessionCwd.startsWith(projectRoot + path.sep);
+    // Compare separator- and case-normalized (Windows folds `\`→`/` and lowercases)
+    // so a backslash session cwd matches a forward-slash project root and vice versa.
+    const cwd = toComparablePath(sessionCwd);
+    const root = toComparablePath(projectRoot);
+    return cwd === root || cwd.startsWith(root + '/');
 }
 function sessionDistance(session, historyEntry) {
     if (!historyEntry.timestampMs)
@@ -1341,25 +1365,3 @@ function padRight(s, width) {
 function truncate(s, max) {
     return s.length > max ? s.slice(0, max - 1) + '.' : s;
 }
-function formatRelativeTime(isoTimestamp) {
-    const now = Date.now();
-    const then = new Date(isoTimestamp).getTime();
-    if (isNaN(then))
-        return isoTimestamp;
-    const diffMs = now - then;
-    const diffMin = Math.floor(diffMs / 60_000);
-    const diffHrs = Math.floor(diffMs / 3_600_000);
-    const diffDays = Math.floor(diffMs / 86_400_000);
-    if (diffMin < 1)
-        return 'just now';
-    if (diffMin < 60)
-        return `${diffMin} min ago`;
-    if (diffHrs < 24)
-        return `${diffHrs} hour${diffHrs === 1 ? '' : 's'} ago`;
-    if (diffDays < 7)
-        return `${diffDays} day${diffDays === 1 ? '' : 's'} ago`;
-    // Older: show date
-    const d = new Date(then);
-    const months = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
-    return `${months[d.getMonth()]} ${d.getDate()}`;
-}

package/dist/commands/sync.d.ts

@@ -9,6 +9,8 @@
  *   agents sync claude                                  # one agent: uses default/sole installed version
  *   agents sync claude@2.1.142                          # one agent: explicit version
  *   agents sync claude@latest                           # one agent: newest installed
+ *   agents sync claude@oldest                           # one agent: oldest installed
+ *   agents sync claude@pinned   (= claude@default)      # one agent: the pinned default version
  *   agents sync --agent claude --agent-version 2.1.142  # legacy form, still supported
  *
  * The umbrella stages live in lib/sync-umbrella.ts; this file dispatches to them

package/dist/commands/sync.js

@@ -9,6 +9,8 @@
  *   agents sync claude                                  # one agent: uses default/sole installed version
  *   agents sync claude@2.1.142                          # one agent: explicit version
  *   agents sync claude@latest                           # one agent: newest installed
+ *   agents sync claude@oldest                           # one agent: oldest installed
+ *   agents sync claude@pinned   (= claude@default)      # one agent: the pinned default version
  *   agents sync --agent claude --agent-version 2.1.142  # legacy form, still supported
  *
  * The umbrella stages live in lib/sync-umbrella.ts; this file dispatches to them
@@ -28,7 +30,7 @@
 import * as path from 'path';
 import chalk from 'chalk';
 import { agentLabel, resolveAgentName } from '../lib/agents.js';
-import { isVersionInstalled, syncResourcesToVersion, parseAgentSpec, resolveVersion, listInstalledVersions, getAvailableResources, getActuallySyncedResources, getProjectOnlyResources, getNewResources, hasNewResources, promptResourceSelection, promptNewResourceSelection, } from '../lib/versions.js';
+import { isVersionInstalled, syncResourcesToVersion, parseAgentSpec, resolveVersion, resolveVersionAlias, listInstalledVersions, getAvailableResources, getActuallySyncedResources, getProjectOnlyResources, getNewResources, hasNewResources, promptResourceSelection, promptNewResourceSelection, } from '../lib/versions.js';
 import { compileRulesForProject } from '../lib/rules/compile.js';
 import { runLaunchSync } from '../lib/project-launch.js';
 import { isInteractiveTerminal, isPromptCancelled } from './utils.js';
@@ -38,7 +40,7 @@ export function registerSyncCommand(program) {
     program
         .command('sync [agentSpec]')
         .summary('Make this machine current, or sync resources into one agent')
-        .description('With an [agentSpec], syncs resources (commands, skills, hooks, rules, MCPs, plugins, etc.) into that installed agent version — previews changes and lets you pick. e.g. "claude" or "claude@2.1.142".\n\nWith NO agent, runs the umbrella verb: fetch remote state (config repos + secrets + sessions) then reconcile it into every installed agent. Scope it with --repos / --secrets / --sessions, --cloud (fetch only), or --local (reconcile only).')
+        .description('With an [agentSpec], syncs resources (commands, skills, hooks, rules, MCPs, plugins, etc.) into that installed agent version — previews changes and lets you pick. e.g. "claude", "claude@2.1.142", or a selector: @latest / @oldest / @pinned (= @default).\n\nWith NO agent, runs the umbrella verb: fetch remote state (config repos + secrets + sessions) then reconcile it into every installed agent. Scope it with --repos / --secrets / --sessions, --cloud (fetch only), or --local (reconcile only).')
         .option('--agent <agent>', 'Agent identifier (legacy form; prefer the positional spec)')
         .option('--agent-version <version>', 'Version to sync into (legacy form; prefer "agent@version")')
         .option('--project-dir <path>', 'Path to project-level .agents/ directory containing project-scoped resources')
@@ -116,17 +118,23 @@ async function runSync(agentSpec, opts) {
     // ---------- 1. Resolve agent + version ----------
     let agentId;
     let version;
+    // A positional @selector typed by the user (latest/oldest/pinned/default/
+    // explicit). parseAgentSpec defaults a missing version to 'latest', so a bare
+    // `agents sync claude` and `agents sync claude@latest` are indistinguishable
+    // after parsing — we only treat the version as a selector when an '@' was
+    // actually typed, keeping bare `claude` on the default-version path.
+    let selector;
     if (agentSpec) {
         const parsed = parseAgentSpec(agentSpec);
         if (!parsed) {
             errLog(chalk.red(`Invalid agent spec '${agentSpec}'.`));
-            errLog(chalk.gray('Examples: claude, claude@2.1.142, codex@latest'));
+            errLog(chalk.gray('Examples: claude, claude@2.1.142, claude@latest, claude@oldest, claude@pinned'));
             process.exitCode = 1;
             return;
         }
         agentId = parsed.agent;
-        if (parsed.version !== 'latest' && parsed.version !== 'oldest')
-            version = parsed.version;
+        if (agentSpec.includes('@'))
+            selector = parsed.version;
     }
     if (opts.agent) {
         const resolved = resolveAgentName(opts.agent);
@@ -138,6 +146,8 @@ async function runSync(agentSpec, opts) {
         agentId = resolved;
     }
     if (opts.agentVersion) {
+        // Legacy flag and the launch-shim hot path (`--agent-version <concrete>`):
+        // pass through verbatim. Selector aliases are a positional-spec feature.
         version = opts.agentVersion;
     }
     if (!agentId) {
@@ -147,6 +157,13 @@ async function runSync(agentSpec, opts) {
         return;
     }
     // ---------- 2. Resolve version (project pin → global default → sole installed) ----------
+    // A positional @selector wins over the default-resolution below.
+    //   @latest / @oldest        → newest / oldest installed (process.exit if none)
+    //   @pinned / @default       → undefined → fall through to the default path
+    //   @x.y.z                   → that version (process.exit if not installed)
+    if (selector !== undefined && !version) {
+        version = resolveVersionAlias(agentId, selector);
+    }
     if (!version) {
         version = resolveVersion(agentId, process.cwd()) || undefined;
         if (!version) {

package/dist/commands/view.js

@@ -21,6 +21,9 @@ import { listProfiles, profileSummary } from '../lib/profiles.js';
 import { loadManifest, isStale } from '../lib/staleness/index.js';
 import { confirm } from '@inquirer/prompts';
 import { formatPath, isInteractiveTerminal, isPromptCancelled } from './utils.js';
+// Shown in the email column for agents that are signed in but expose no email
+// address locally (Antigravity, Kimi store an opaque OAuth/JWT credential).
+const SIGNED_IN_LABEL = 'signed in';
 /**
  * Group profile summaries by their host harness, optionally filtered to a
  * single agent. Profile YAMLs that fail validation are silently skipped by
@@ -350,6 +353,8 @@ async function showInstalledVersions(filterAgentId) {
                 const info = rawInfo ? mergeCanonical(rawInfo) : undefined;
                 if (info?.email)
                     maxEmail = Math.max(maxEmail, info.email.length);
+                else if (info?.signedIn)
+                    maxEmail = Math.max(maxEmail, SIGNED_IN_LABEL.length);
                 if (info?.plan)
                     maxPlanWidth = Math.max(maxPlanWidth, info.plan.length);
             }
@@ -406,6 +411,7 @@ async function showInstalledVersions(filterAgentId) {
                 // Build columns, trimming trailing whitespace when columns are empty
                 const parts = [`    ${label}`];
                 const hasEmail = !!vInfo?.email;
+                const signedIn = !!vInfo?.signedIn;
                 const usageStr = formatUsageSummary(vInfo?.plan || null, usageInfo?.snapshot || null, maxPlanWidth);
                 const hasUsage = usageStr.length > 0;
                 // Only show lastActive for versions with an actual logged-in account.
@@ -418,14 +424,17 @@ async function showInstalledVersions(filterAgentId) {
                     runDefaultBits.push(`mode:${runDefaults.mode}`);
                 if (runDefaults.model)
                     runDefaultBits.push(`model:${runDefaults.model}`);
-                if (!hasEmail && !hasUsage) {
+                if (!hasEmail && !hasUsage && !signedIn) {
                     // Installed but never signed in
                     parts.push(chalk.gray('(not signed in — run ' + agent.cliCommand + ' to log in)'));
                 }
                 else {
-                    if (hasEmail || hasUsage || hasActive) {
-                        const emailCol = (vInfo?.email || '').padEnd(maxEmail);
-                        parts.push(hasEmail ? chalk.cyan(emailCol) : ' '.repeat(maxEmail));
+                    if (hasEmail || hasUsage || hasActive || signedIn) {
+                        // Signed-in agents without a local email (Antigravity, Kimi) show a
+                        // "signed in" placeholder so they read as logged in, not blank.
+                        const display = vInfo?.email || (signedIn ? SIGNED_IN_LABEL : '');
+                        const emailCol = display.padEnd(maxEmail);
+                        parts.push(display ? chalk.cyan(emailCol) : ' '.repeat(maxEmail));
                     }
                     if (hasUsage || hasActive) {
                         const usagePad = ' '.repeat(Math.max(0, maxUsageWidth - visibleWidth(usageStr)));
@@ -503,8 +512,10 @@ async function showInstalledVersions(filterAgentId) {
             const gUsage = gUsageKey ? usageByKey.get(gUsageKey) : undefined;
             const gUsageStr = formatUsageSummary(gInfo?.plan || null, gUsage?.snapshot || null);
             const gActiveStr = gInfo ? formatLastActive(gInfo.lastActive) : '';
-            if (gInfo?.email || gUsageStr || gActiveStr)
-                parts.push(gInfo?.email ? chalk.cyan(gInfo.email) : '');
+            if (gInfo?.email || gUsageStr || gActiveStr || gInfo?.signedIn) {
+                const gDisplay = gInfo?.email || (gInfo?.signedIn ? SIGNED_IN_LABEL : '');
+                parts.push(gDisplay ? chalk.cyan(gDisplay) : '');
+            }
             if (gUsageStr || gActiveStr)
                 parts.push(gUsageStr);
             const gStatusStr = formatUsageStatusBadge(gInfo?.usageStatus);
@@ -814,7 +825,11 @@ async function showAgentResources(agentId, requestedVersion, filter) {
             cliVersion: version,
             info: accountInfo,
         });
-        const emailStr = accountInfo.email ? chalk.cyan(`  ${accountInfo.email}`) : '';
+        const emailStr = accountInfo.email
+            ? chalk.cyan(`  ${accountInfo.email}`)
+            : accountInfo.signedIn
+                ? chalk.cyan(`  ${SIGNED_IN_LABEL}`)
+                : '';
         const status = chalk.green(version);
         const usageStr = formatUsageSummary(accountInfo.plan, null);
         const usagePart = usageStr ? `  ${usageStr}` : '';
@@ -1006,7 +1021,7 @@ async function collectAgentsJson(filterAgentId) {
         const entry = {
             version,
             isDefault: version === globalDefault,
-            signedIn: !!info.email,
+            signedIn: info.signedIn,
             email: info.email,
             plan: info.plan,
             usageStatus: info.usageStatus,
@@ -1273,9 +1288,10 @@ export async function viewAction(agentArg, options) {
         console.log(chalk.red(formatAgentError(agentName)));
         process.exit(1);
     }
-    // Keep 'default' as-is since showAgentResources handles it; resolveVersionAlias
-    // returns undefined for 'default' which would skip the detailed view.
-    const requestedVersion = parts[1] === 'default'
+    // Keep 'default'/'pinned' as-is since showAgentResources handles 'default';
+    // resolveVersionAlias returns undefined for both (they're synonyms), which
+    // would otherwise skip the detailed view.
+    const requestedVersion = (parts[1] === 'default' || parts[1] === 'pinned')
         ? 'default'
         : (resolveVersionAlias(agentId, parts[1]) ?? null);
     if (prune) {

package/dist/index.js

@@ -11,6 +11,7 @@ import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
 import { fileURLToPath } from 'url';
+import { detectDevBuild } from './lib/startup/dev-build.js';
 // `ora`, `@inquirer/prompts`, `./commands/utils.js`, and the agents/versions/shims
 // modules are imported dynamically at their use sites: they are needed only on
 // interactive / update / shim-repair paths, never for fast commands like
@@ -37,18 +38,7 @@ import { NPM_PACKAGE_NAME, deriveGlobalPrefix, detectPackageManager, installPack
 // must not scribble on the user's real ~/.agents/), and skip the update prompt
 // (the "0.0.0-dev -> 1.x.y" message is misleading). Each individual env var
 // can still be set explicitly to override (set to '0' to re-enable).
-const IS_DEV_BUILD = (() => {
-    if (VERSION.startsWith('0.0.0-dev'))
-        return true;
-    try {
-        const cliPath = process.argv[1] || '';
-        const repoRoot = path.dirname(path.dirname(cliPath));
-        return fs.existsSync(path.join(repoRoot, '.git'));
-    }
-    catch {
-        return false;
-    }
-})();
+const IS_DEV_BUILD = detectDevBuild(process.argv[1] || '', VERSION);
 if (IS_DEV_BUILD) {
     if (process.env.AGENTS_NO_AUTOPULL === undefined)
         process.env.AGENTS_NO_AUTOPULL = '1';
@@ -61,7 +51,7 @@ if (IS_DEV_BUILD) {
 // module on each invocation (which loaded the whole ~50-module tree before the
 // first byte of output), the registry maps a command name to a thunk that
 // imports only what that command needs. See src/lib/startup/command-registry.ts.
-import { COMMAND_LOADERS, LAZY_COMMAND_NAMES, loadView, loadInspect, loadFeedback, loadCommands, loadHooks, loadSkills, loadRules, loadPermissions, loadMcp, loadCli, loadSubagents, loadPlugins, loadWorkflows, loadWorktree, loadVersions, loadImport, loadPackages, loadDaemon, loadRoutines, loadRun, loadDefaults, loadModels, loadPrune, loadTrash, loadRestore, loadDoctor, loadProfiles, loadSecrets, loadWallet, loadHelper, loadMenubar, loadBeta, loadSync, loadRefreshRules, loadDrive, loadFactory, loadUsage, loadCost, loadBudget, loadAlias, loadPty, loadTmux, loadBrowser, loadComputer, loadPull, loadPush, loadRepo, loadSetup, } from './lib/startup/command-registry.js';
+import { COMMAND_LOADERS, LAZY_COMMAND_NAMES, loadView, loadInspect, loadFeedback, loadCommands, loadHooks, loadSkills, loadRules, loadPermissions, loadMcp, loadCli, loadSubagents, loadPlugins, loadWorkflows, loadWorktree, loadVersions, loadImport, loadPackages, loadDaemon, loadRoutines, loadRun, loadDefaults, loadModels, loadPrune, loadTrash, loadRestore, loadDoctor, loadProfiles, loadSecrets, loadWallet, loadHelper, loadMenubar, loadBeta, loadSync, loadRefreshRules, loadDrive, loadFactory, loadUsage, loadCost, loadBudget, loadAlias, loadPty, loadTmux, loadBrowser, loadComputer, loadHosts, loadPull, loadPush, loadRepo, loadSetup, } from './lib/startup/command-registry.js';
 import { applyGlobalHelpConventions } from './lib/help.js';
 import { IS_WINDOWS } from './lib/platform/index.js';
 // Transparent shim delegate: the generated Windows `.cmd` shims invoke
@@ -793,6 +783,7 @@ async function registerAllEagerCommands() {
     await reg(loadTmux);
     await reg(loadBrowser);
     await reg(loadComputer);
+    await reg(loadHosts);
     registerJobsCronAliasCommand(program, 'jobs');
     registerJobsCronAliasCommand(program, 'cron');
     registerUpgradeCommand(program);

package/dist/lib/agent-spec.d.ts

@@ -0,0 +1,36 @@
+import type { AgentId } from './types.js';
+export interface AgentTarget {
+    agent: AgentId;
+    /** Resolved exact version, or null when the agent has no installed versions yet. */
+    version: string | null;
+}
+/** Canonical qualifier set, in help/display order. `pinned` ≡ `default`. */
+export declare const AGENT_QUALIFIERS: readonly ["latest", "oldest", "pinned", "default", "all"];
+export type AgentQualifier = (typeof AGENT_QUALIFIERS)[number];
+/** Shared `--help` epilog so every agent-spec command documents the same grammar. */
+export declare const AGENT_SPEC_HELP: string;
+export declare class AgentSpecError extends Error {
+    constructor(message: string);
+}
+export interface ResolveAgentTargetsOptions {
+    /** Project dir for resolving a bare spec's project pin. Defaults to process.cwd(). */
+    cwd?: string;
+    /** Restrict the agents a spec may name (e.g. only mcp-capable). Defaults to all. */
+    availableAgents?: readonly AgentId[];
+}
+/**
+ * Resolve an agent spec (single or comma-list) into concrete installed targets.
+ * Domain = installed: `@latest`/`@oldest`/`@all` range over installed versions
+ * (`add`/`install` use a separate available-version path). Throws AgentSpecError
+ * on bad input — never calls process.exit, so it is safe on the hot path and in
+ * library contexts.
+ */
+export declare function resolveAgentTargets(spec: string, opts?: ResolveAgentTargetsOptions): AgentTarget[];
+/**
+ * Convenience for single-target commands (`use`, `run`): resolve a spec that
+ * must name exactly one installed version. Rejects `@all` / multi-target specs.
+ */
+export declare function resolveSingleAgentTarget(spec: string, opts?: ResolveAgentTargetsOptions): {
+    agent: AgentId;
+    version: string;
+};

package/dist/lib/agent-spec.js

@@ -0,0 +1,157 @@
+// Centralized agent-spec resolution — one vocabulary, one resolver, reused by
+// every subcommand that accepts `<agent>[@<qualifier>]`.
+//
+// The qualifier vocabulary used to be split across three functions in
+// versions.ts (parseAgentSpec, resolveVersionAlias, resolveInstalledAgentTargets)
+// with diverging support — `@latest`/`@oldest` in one, `@all`/`@default` in
+// another, `@pinned` nowhere. This module is the single source of truth.
+//
+// Built for the hot path (`--launch`, ~100ms budget): the common specs resolve
+// with NO directory enumeration —
+//   exact `claude@2.1.181`   → one isVersionInstalled() (existsSync)
+//   `claude@pinned|@default` → memoized getGlobalDefault() + existsSync
+//   bare `claude`            → resolveVersion() (memoized meta), no readdir
+// Only the relative qualifiers `@latest`/`@oldest`/`@all` enumerate, and even
+// then via the mtime-cached listInstalledVersions().
+import { AGENTS, ALL_AGENT_IDS, resolveAgentName, formatAgentError } from './agents.js';
+import { listInstalledVersions, getGlobalDefault, isVersionInstalled, resolveVersion, } from './versions.js';
+/** Canonical qualifier set, in help/display order. `pinned` ≡ `default`. */
+export const AGENT_QUALIFIERS = ['latest', 'oldest', 'pinned', 'default', 'all'];
+/** Shared `--help` epilog so every agent-spec command documents the same grammar. */
+export const AGENT_SPEC_HELP = 'Agent spec: <agent>[@<qualifier>]. Qualifiers: ' +
+    '@latest (highest installed), @oldest (lowest installed), ' +
+    '@pinned / @default (your configured default — synonyms), ' +
+    '@all (every installed version), or an exact @x.y.z. ' +
+    'Bare <agent> uses the resolved default (project pin → global default). ' +
+    'Comma-separate to combine: claude@all,codex@latest.';
+export class AgentSpecError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'AgentSpecError';
+    }
+}
+/**
+ * Resolve an agent spec (single or comma-list) into concrete installed targets.
+ * Domain = installed: `@latest`/`@oldest`/`@all` range over installed versions
+ * (`add`/`install` use a separate available-version path). Throws AgentSpecError
+ * on bad input — never calls process.exit, so it is safe on the hot path and in
+ * library contexts.
+ */
+export function resolveAgentTargets(spec, opts = {}) {
+    const cwd = opts.cwd ?? process.cwd();
+    const available = opts.availableAgents ?? ALL_AGENT_IDS;
+    const rawEntries = spec
+        .split(',')
+        .map((s) => s.trim())
+        .filter(Boolean);
+    if (rawEntries.length === 0) {
+        throw new AgentSpecError('Empty agent spec.');
+    }
+    // Expand the bare literal `all` (or `all@all`) into every available agent that
+    // has at least one installed version. Lenient: agents with nothing installed
+    // are skipped rather than erroring.
+    const entries = [];
+    for (const e of rawEntries) {
+        if (e === 'all' || e === 'all@all') {
+            for (const a of available) {
+                if (listInstalledVersions(a).length > 0)
+                    entries.push(`${a}@all`);
+            }
+        }
+        else {
+            entries.push(e);
+        }
+    }
+    const out = [];
+    const seen = new Set();
+    const push = (agent, version) => {
+        const key = `${agent}@${version ?? ''}`;
+        if (!seen.has(key)) {
+            seen.add(key);
+            out.push({ agent, version });
+        }
+    };
+    for (const entry of entries) {
+        const at = entry.indexOf('@');
+        const agentToken = (at === -1 ? entry : entry.slice(0, at)).trim();
+        const qualifier = at === -1 ? null : entry.slice(at + 1).trim();
+        if (!agentToken)
+            continue;
+        if (at !== -1 && !qualifier) {
+            throw new AgentSpecError(`Missing version in '${entry}'. Use ${agentToken}@x.y.z, @latest, @oldest, @pinned, @default, or @all.`);
+        }
+        const agent = resolveAgentName(agentToken);
+        if (!agent || !available.includes(agent)) {
+            throw new AgentSpecError(formatAgentError(agentToken, [...available]));
+        }
+        const name = AGENTS[agent].name;
+        // ----- bare: resolved default, NO enumeration in the common case -----
+        if (qualifier === null) {
+            const resolved = resolveVersion(agent, cwd); // project pin → global default (meta-only)
+            if (resolved) {
+                push(agent, resolved);
+            }
+            else {
+                const installed = listInstalledVersions(agent);
+                if (installed.length === 0)
+                    push(agent, null);
+                else if (installed.length === 1)
+                    push(agent, installed[0]);
+                else
+                    throw new AgentSpecError(`No default version set for ${name}. Specify one (${agent}@<version>) or set it: agents use ${agent}@<version>.`);
+            }
+            continue;
+        }
+        // ----- @pinned / @default: synonyms, meta-only fast path -----
+        if (qualifier === 'pinned' || qualifier === 'default') {
+            const def = getGlobalDefault(agent);
+            if (!def) {
+                throw new AgentSpecError(`No default version set for ${name}. Run: agents use ${agent}@<version>`);
+            }
+            push(agent, def);
+            continue;
+        }
+        // ----- @all: every installed version -----
+        if (qualifier === 'all') {
+            const installed = listInstalledVersions(agent);
+            if (installed.length === 0) {
+                throw new AgentSpecError(`No managed versions are installed for ${name}. Run: agents add ${agent}@latest`);
+            }
+            for (const v of installed)
+                push(agent, v);
+            continue;
+        }
+        // ----- @latest / @oldest: enumerate (mtime-cached), pick an end -----
+        if (qualifier === 'latest' || qualifier === 'oldest') {
+            const installed = listInstalledVersions(agent); // already sorted ascending
+            if (installed.length === 0) {
+                throw new AgentSpecError(`No managed versions are installed for ${name}. Run: agents add ${agent}@latest`);
+            }
+            push(agent, qualifier === 'oldest' ? installed[0] : installed[installed.length - 1]);
+            continue;
+        }
+        // ----- exact version: one existsSync, NO enumeration -----
+        if (!isVersionInstalled(agent, qualifier)) {
+            const installed = listInstalledVersions(agent);
+            const hint = installed.length ? ` Installed: ${installed.join(', ')}.` : '';
+            throw new AgentSpecError(`${name}@${qualifier} is not installed.${hint} Install it: agents add ${agent}@${qualifier}`);
+        }
+        push(agent, qualifier);
+    }
+    return out;
+}
+/**
+ * Convenience for single-target commands (`use`, `run`): resolve a spec that
+ * must name exactly one installed version. Rejects `@all` / multi-target specs.
+ */
+export function resolveSingleAgentTarget(spec, opts = {}) {
+    const targets = resolveAgentTargets(spec, opts);
+    if (targets.length !== 1) {
+        throw new AgentSpecError(`'${spec}' resolves to ${targets.length} targets; this command needs exactly one.`);
+    }
+    const t = targets[0];
+    if (t.version === null) {
+        throw new AgentSpecError(`No installed version for ${AGENTS[t.agent].name}. Run: agents add ${t.agent}@latest`);
+    }
+    return { agent: t.agent, version: t.version };
+}

package/dist/lib/agents.d.ts

@@ -107,6 +107,7 @@ export interface AccountInfo {
         currency: string;
     } | null;
     lastActive: Date | null;
+    signedIn: boolean;
 }
 /** Return the email address associated with the agent's auth config, or null. */
 export declare function getAccountEmail(agentId: AgentId, home?: string): Promise<string | null>;