@phnx-labs/agents-cli 1.20.27 → 1.20.28

package/dist/commands/repo.js

@@ -68,26 +68,117 @@ function deriveAlias(source) {
     // becomes ~/.agents-<alias>/ on disk (e.g. ".agents-work" -> "work").
     return base.replace(/^\.+/, '').replace(/^agents-/, '') || 'repo';
 }
+/** Top-level dir -> resource kind. Directory-based resources collapse to one unit. */
+const RESOURCE_DIRS = {
+    skills: 'skill', commands: 'command', prompts: 'command', plugins: 'plugin',
+    hooks: 'hook', mcp: 'mcp', subagents: 'subagent', rules: 'rule',
+    workflows: 'workflow', routines: 'routine', profiles: 'profile',
+    permissions: 'permission', cli: 'cli',
+};
+/** [singular, plural] display labels per kind. */
+const RESOURCE_LABELS = {
+    skill: ['skill', 'skills'], command: ['command', 'commands'],
+    plugin: ['plugin', 'plugins'], hook: ['hook', 'hooks'], mcp: ['MCP', 'MCPs'],
+    subagent: ['subagent', 'subagents'], rule: ['rule', 'rules'],
+    workflow: ['workflow', 'workflows'], routine: ['routine', 'routines'],
+    profile: ['profile', 'profiles'], permission: ['permission', 'permissions'],
+    cli: ['CLI', 'CLIs'], config: ['config file', 'config files'],
+    other: ['other file', 'other files'],
+};
+/** Display order — the resources a user cares about most come first. */
+const RESOURCE_ORDER = [
+    'skill', 'command', 'plugin', 'hook', 'mcp', 'subagent', 'rule',
+    'workflow', 'routine', 'profile', 'permission', 'cli', 'config', 'other',
+];
 /**
- * Categorized working-tree summary: `M:2 A:1 D:1 ?:3` — letters match the git
- * porcelain shorthand (Modified / Added / Deleted / Renamed / Unmerged /
- * Untracked). Zero counts are omitted so the column stays compact.
+ * Map a repo-relative path to the resource unit it belongs to. Directory-based
+ * resources (skills/foo/SKILL.md) collapse to `skills/foo` so all their files
+ * count as one unit; flat config files (agents.yaml, hooks.yaml) count alone.
  */
-function formatDirtyCounts(status) {
+export function resourceUnit(file) {
+    const parts = file.split('/');
+    const top = parts[0];
+    if (top === 'agents.yaml' || top === 'hooks.yaml')
+        return { kind: 'config', unit: top };
+    const kind = RESOURCE_DIRS[top];
+    if (kind)
+        return { kind, unit: parts.length > 1 ? `${top}/${parts[1]}` : file };
+    return { kind: 'other', unit: file };
+}
+/**
+ * Render a set of changed files as a resource-level summary, e.g.
+ * `2 new skills, 1 changed hook`. Counts distinct resource units (a skill whose
+ * three files all changed is "1 changed skill"), grouped by action then kind,
+ * and colors each phrase green/yellow/red for new/changed/removed. Caps at
+ * `maxParts` phrases, appending `+N more` so a big diff stays scannable.
+ */
+export function formatResourceDelta(entries, maxParts = 5) {
+    // Gather every action seen across a unit's files, then collapse to one action.
+    const units = new Map();
+    for (const { action, file } of entries) {
+        const { kind, unit } = resourceUnit(file);
+        const key = `${kind} ${unit}`;
+        const cur = units.get(key) ?? { kind, actions: new Set() };
+        cur.actions.add(action);
+        units.set(key, cur);
+    }
+    const counts = new Map(); // `${action} ${kind}` -> count
+    for (const { kind, actions } of units.values()) {
+        let action;
+        if (actions.size === 1)
+            action = [...actions][0];
+        else if ([...actions].every((a) => a === 'new'))
+            action = 'new';
+        else if ([...actions].every((a) => a === 'removed'))
+            action = 'removed';
+        else
+            action = 'changed'; // mixed add+modify within one unit reads as a change
+        const key = `${action} ${kind}`;
+        counts.set(key, (counts.get(key) ?? 0) + 1);
+    }
+    const COLOR = {
+        new: chalk.green, changed: chalk.yellow, removed: chalk.red,
+    };
     const parts = [];
-    if (status.modified.length)
-        parts.push(chalk.yellow(`M:${status.modified.length}`));
-    if (status.created.length)
-        parts.push(chalk.green(`A:${status.created.length}`));
-    if (status.deleted.length)
-        parts.push(chalk.red(`D:${status.deleted.length}`));
-    if (status.renamed.length)
-        parts.push(chalk.cyan(`R:${status.renamed.length}`));
-    if (status.conflicted.length)
-        parts.push(chalk.magenta(`U:${status.conflicted.length}`));
-    if (status.not_added.length)
-        parts.push(chalk.gray(`?:${status.not_added.length}`));
-    return parts.join(' ');
+    for (const action of ['new', 'changed', 'removed']) {
+        for (const kind of RESOURCE_ORDER) {
+            const n = counts.get(`${action} ${kind}`);
+            if (!n)
+                continue;
+            const [singular, plural] = RESOURCE_LABELS[kind];
+            parts.push(COLOR[action](`${n} ${action} ${n === 1 ? singular : plural}`));
+        }
+    }
+    if (parts.length > maxParts) {
+        const shown = parts.slice(0, maxParts);
+        shown.push(chalk.gray(`+${parts.length - maxParts} more`));
+        return shown.join(', ');
+    }
+    return parts.join(', ');
+}
+/** Parse `git diff --name-status <range>` into resource-delta entries. */
+async function diffResourceEntries(git, range) {
+    let raw;
+    try {
+        raw = await git.diff(['--name-status', range]);
+    }
+    catch {
+        return []; // no upstream resolvable / range invalid — caller falls back to counts
+    }
+    const out = [];
+    for (const line of raw.split('\n')) {
+        if (!line.trim())
+            continue;
+        const cols = line.split('\t');
+        const code = cols[0] ?? '';
+        const file = cols[cols.length - 1] ?? ''; // renames put the new path last
+        if (!file)
+            continue;
+        const c = code[0];
+        const action = c === 'A' ? 'new' : c === 'D' ? 'removed' : 'changed';
+        out.push({ action, file });
+    }
+    return out;
 }
 /** Visible character width of a string with embedded ANSI color codes. */
 function visibleWidth(s) {
@@ -98,46 +189,75 @@ function padVisible(s, width) {
     return s + ' '.repeat(Math.max(0, width - visibleWidth(s)));
 }
 /**
- * Render one row of the unified repo table: alias / branch / ahead-behind /
- * dirty counts / url+commit. Used by `agents repo list` and the hidden
- * `agents repo status` alias.
+ * Render one repo's row data: branch, resource-level sync (what a pull/push would
+ * move), resource-level local edits, and the remote URL + commit. Used by
+ * `agents repo list` and the hidden `agents repo status` alias.
  */
 async function renderRepoRow(t) {
-    const aliasCol = chalk.cyan(t.alias.padEnd(12));
     if (!fs.existsSync(t.dir)) {
-        return `  ${aliasCol} ${chalk.red('missing')} ${chalk.gray(t.dir)}`;
+        return { alias: t.alias, raw: `${chalk.red('missing')} ${chalk.gray(t.dir)}` };
     }
     if (!isGitRepo(t.dir)) {
-        return `  ${aliasCol} ${chalk.gray('local (no git remote)')} ${chalk.gray(t.dir)}`;
+        return { alias: t.alias, raw: `${chalk.gray('local (no git remote)')} ${chalk.gray(t.dir)}` };
     }
     try {
         const git = simpleGit(t.dir);
         const status = await git.status();
-        const branch = status.tracking || status.current || '(detached)';
-        const inSync = (status.ahead ?? 0) === 0 && (status.behind ?? 0) === 0;
-        const remoteRaw = inSync ? 'in sync' : `+${status.ahead ?? 0} -${status.behind ?? 0}`;
-        const remoteColored = inSync ? chalk.green(remoteRaw) : chalk.yellow(remoteRaw);
-        const remotePad = ' '.repeat(Math.max(0, 12 - remoteRaw.length));
-        const tree = status.isClean() ? chalk.green('clean') : formatDirtyCounts(status);
+        // Show the local branch name; the upstream remote is already implied by URL.
+        const branch = status.current || (status.tracking ? status.tracking.replace(/^origin\//, '') : '(detached)');
+        // SYNC: what a pull brings in / a push sends out, described by resource.
+        const ahead = status.ahead ?? 0;
+        const behind = status.behind ?? 0;
+        let sync;
+        if (!status.tracking) {
+            sync = chalk.gray('no upstream');
+        }
+        else if (ahead === 0 && behind === 0) {
+            sync = chalk.green('up to date');
+        }
+        else {
+            const pieces = [];
+            if (behind > 0) {
+                // Three-dot isolates upstream's side via the merge-base, so a diverged
+                // branch reports exactly what a pull adds (not the inverse of local commits).
+                const incoming = formatResourceDelta(await diffResourceEntries(git, 'HEAD...@{upstream}'));
+                pieces.push(`${incoming || chalk.yellow(`${behind} commit${behind > 1 ? 's' : ''}`)} ${chalk.gray('to pull')}`);
+            }
+            if (ahead > 0) {
+                const outgoing = formatResourceDelta(await diffResourceEntries(git, '@{upstream}...HEAD'));
+                pieces.push(`${outgoing || chalk.yellow(`${ahead} commit${ahead > 1 ? 's' : ''}`)} ${chalk.gray('to push')}`);
+            }
+            sync = pieces.join(chalk.gray('  ·  '));
+        }
+        // CHANGES: uncommitted working-tree edits, described by resource.
+        const localEntries = [
+            ...status.created.map((f) => ({ action: 'new', file: f })),
+            ...status.not_added.map((f) => ({ action: 'new', file: f })),
+            ...status.modified.map((f) => ({ action: 'changed', file: f })),
+            ...status.conflicted.map((f) => ({ action: 'changed', file: f })),
+            ...status.renamed.map((r) => ({ action: 'changed', file: r.to })),
+            ...status.deleted.map((f) => ({ action: 'removed', file: f })),
+        ];
+        const changes = status.isClean() ? chalk.green('clean') : formatResourceDelta(localEntries);
         const remotes = await git.getRemotes(true);
         const origin = remotes.find((r) => r.name === 'origin');
         const url = origin?.refs?.fetch || '';
         const commit = (await git.log({ maxCount: 1 })).latest?.hash.slice(0, 8) || '';
-        const tail = url
+        const remote = url
             ? chalk.gray(`${url}${commit ? ` (${commit})` : ''}`)
             : commit
                 ? chalk.gray(`(${commit})`)
                 : '';
-        return `  ${aliasCol} ${branch.padEnd(28)}  ${remoteColored}${remotePad}  ${padVisible(tree, 14)}  ${tail}`;
+        return { alias: t.alias, cells: [branch, sync, changes, remote] };
     }
     catch (err) {
-        return `  ${aliasCol} ${chalk.red('error')} ${err.message}`;
+        return { alias: t.alias, raw: `${chalk.red('error')} ${err.message}` };
     }
 }
 /**
  * Shared action body for `agents repo list` and the hidden `agents repo status`
- * alias. Prints a unified table: alias, branch, ahead/behind, dirty counts,
- * remote URL and short commit hash.
+ * alias. Prints an aligned table: repo, branch, resource-level sync (to pull /
+ * to push), resource-level local changes, and remote URL + short commit.
  */
 async function listRepos(alias) {
     const targets = collectRepoTargets(alias);
@@ -149,10 +269,26 @@ async function listRepos(alias) {
         console.log(chalk.gray('No repos to show.'));
         return;
     }
+    const rows = await Promise.all(targets.map(renderRepoRow));
+    const tableRows = rows.filter((r) => r.cells);
+    // Column widths grow to fit the widest visible content (resource summaries vary
+    // a lot in length), so the table stays aligned without truncating detail.
+    const headers = ['REPO', 'BRANCH', 'SYNC', 'CHANGES'];
+    const aliasW = Math.max(headers[0].length, ...rows.map((r) => r.alias.length));
+    const branchW = Math.max(headers[1].length, 0, ...tableRows.map((r) => visibleWidth(r.cells[0])));
+    const syncW = Math.max(headers[2].length, 0, ...tableRows.map((r) => visibleWidth(r.cells[1])));
+    const changesW = Math.max(headers[3].length, 0, ...tableRows.map((r) => visibleWidth(r.cells[2])));
     console.log('');
-    console.log(`  ${chalk.gray('REPO'.padEnd(12))} ${chalk.gray('BRANCH'.padEnd(28))}  ${chalk.gray('REMOTE'.padEnd(12))}  ${chalk.gray('LOCAL'.padEnd(14))}  ${chalk.gray('URL')}`);
-    for (const t of targets) {
-        console.log(await renderRepoRow(t));
+    console.log(`  ${chalk.gray(headers[0].padEnd(aliasW))}  ${chalk.gray(headers[1].padEnd(branchW))}  ${chalk.gray(headers[2].padEnd(syncW))}  ${chalk.gray(headers[3].padEnd(changesW))}  ${chalk.gray('REMOTE')}`);
+    for (const r of rows) {
+        const aliasCol = chalk.cyan(r.alias.padEnd(aliasW));
+        if (r.cells) {
+            const [branch, sync, changes, remote] = r.cells;
+            console.log(`  ${aliasCol}  ${padVisible(branch, branchW)}  ${padVisible(sync, syncW)}  ${padVisible(changes, changesW)}  ${remote}`);
+        }
+        else {
+            console.log(`  ${aliasCol}  ${r.raw}`);
+        }
     }
     const userDir = getUserAgentsDir();
     if (!isGitRepo(userDir) && fs.existsSync(userDir)) {
@@ -358,7 +494,7 @@ export function registerRepoCommands(program) {
     repoCmd
         .command('list [alias]')
         .alias('ls')
-        .description('Show all repos: branch, ahead/behind, dirty counts, URL, commit.')
+        .description('Show all repos with resource-level sync (skills/commands/plugins to pull or push) and local changes.')
         .action(async (alias) => {
         await listRepos(alias);
     });

package/dist/commands/secrets.d.ts

@@ -6,13 +6,8 @@
  * Keychain. Bundles are injected at run time via `agents run --secrets`.
  */
 import { type Command } from 'commander';
-/**
- * SSH target for `export --to-ssh`: a bare ssh-config host alias (e.g. `yosemite-s0`)
- * or `user@host`. The strict allowlist blocks shell metacharacters and a leading `-`
- * so a target can't be smuggled in as an ssh argv flag.
- */
-export declare const SSH_TARGET_RE: RegExp;
-export declare function assertValidSshTarget(host: string): void;
+import { SSH_TARGET_RE, assertValidSshTarget } from '../lib/ssh-exec.js';
+export { SSH_TARGET_RE, assertValidSshTarget };
 /**
  * Serialize a resolved env map to `.env` lines that round-trip losslessly through
  * `parseDotenv` on the remote: `KEY="VALUE"`. parseDotenv strips exactly one outer

package/dist/commands/secrets.js

@@ -9,6 +9,7 @@ import { Option } from 'commander';
 import chalk from 'chalk';
 import * as fs from 'fs';
 import { spawnSync } from 'child_process';
+import { SSH_TARGET_RE, assertValidSshTarget } from '../lib/ssh-exec.js';
 import { bundleExists, bundleItemStore, bundlePolicy, deleteBundle, describeBundle, keychainItemsForBundle, keychainRef, listBundles, migrateLegacyBundles, parseDotenv, readAndResolveBundleEnv, readBundle, renameBundle, rotateBundleSecret, validateBundleName, validateEnvKey, validateExpiresFutureDated, validateSecretType, writeBundle, } from '../lib/secrets/bundles.js';
 import { getKeychainToken, getKeychainTokens, hasKeychainToken, secretsKeychainItem, setKeychainToken, } from '../lib/secrets/index.js';
 import { assertOpAvailable, createPasswordItem, deleteItemByTitle, extractSecrets, itemExistsByTitle, listItems, listVaults, } from '../lib/onepassword.js';
@@ -134,17 +135,9 @@ function readStdinSync() {
     }
     return Buffer.concat(chunks).toString('utf-8').trim();
 }
-/**
- * SSH target for `export --to-ssh`: a bare ssh-config host alias (e.g. `yosemite-s0`)
- * or `user@host`. The strict allowlist blocks shell metacharacters and a leading `-`
- * so a target can't be smuggled in as an ssh argv flag.
- */
-export const SSH_TARGET_RE = /^[a-zA-Z0-9._-]+(@[a-zA-Z0-9._-]+)?$/;
-export function assertValidSshTarget(host) {
-    if (!SSH_TARGET_RE.test(host)) {
-        throw new Error(`Invalid SSH target ${JSON.stringify(host)}. Expected a host alias or user@host (letters, digits, '.', '_', '-').`);
-    }
-}
+// SSH target validation is defined canonically in src/lib/ssh-exec.ts and
+// re-exported here for back-compat with existing importers of these symbols.
+export { SSH_TARGET_RE, assertValidSshTarget };
 /** POSIX single-quote a string for safe interpolation into a remote shell command. */
 function shellQuote(s) {
     return `'${s.replace(/'/g, `'\\''`)}'`;
@@ -414,7 +407,7 @@ export function registerSecretsCommands(program) {
       eval "$(agents secrets export prod --plaintext)"
 
       # Push the bundle to remote machine(s) over SSH (lands as a native bundle there)
-      agents secrets export prod --to-ssh --host yosemite-s0 --host yosemite-s1 --force
+      agents secrets export prod --host yosemite-s0 --host yosemite-s1 --force
 
       # Run a one-off command with secrets injected
       agents secrets exec prod -- ./deploy.sh
@@ -1017,7 +1010,7 @@ Examples:
             const requestedBackend = parseBackendOpt(opts.backend);
             // Read the bundle if it exists (inheriting its backend); otherwise
             // create it with the requested backend so a single `import --backend
-            // file` works (this is what `export --to-ssh --remote-backend file`
+            // file` works (this is what `export --host ... --remote-backend file`
             // drives on the remote).
             let bundle;
             if (bundleExists(resolvedBundleName)) {
@@ -1094,23 +1087,22 @@ Examples:
     });
     cmd
         .command('export [bundle]')
-        .description('Resolve a bundle and print KEY=VALUE lines, push it to a 1Password vault with --to-1password, or push it to remote machine(s) over SSH with --to-ssh.')
+        .description('Resolve a bundle and print KEY=VALUE lines, push it to a 1Password vault with --to-1password, or push it to remote machine(s) over SSH with --host.')
         .option('--plaintext', 'Acknowledge that the resolved values will be printed in the clear (shell export mode)')
         .option('--to-1password', 'Push every key in the bundle as a PASSWORD item in a 1Password vault')
         .option('--vault <name>', '1Password vault name (used with --to-1password)')
-        .option('--to-ssh', 'Push the bundle to remote machine(s) over SSH via their native agents-cli import')
-        .option('--host <target...>', 'SSH target(s) for --to-ssh: host alias or user@host (repeatable)')
-        .option('--remote-backend <backend>', 'Backend for the bundle on the remote: keychain (default) or file (passphrase-encrypted, headless-readable). file forwards AGENTS_SECRETS_PASSPHRASE over stdin.', 'keychain')
-        .option('--force', 'Overwrite existing keys/items on the target (used with --to-1password and --to-ssh)')
+        .option('--host <target...>', 'Push the bundle over SSH to this target (host alias or user@host); repeatable for multiple machines')
+        .option('--remote-backend <backend>', 'Backend for the bundle on the remote (with --host): keychain (default) or file (passphrase-encrypted, headless-readable). file forwards AGENTS_SECRETS_PASSPHRASE over stdin.', 'keychain')
+        .option('--force', 'Overwrite existing keys/items on the target (used with --to-1password and --host)')
         .action(async (bundleName, opts) => {
         try {
             const { readAndResolveBundleEnv, bundleToEnvPrefix, isReservedEnvName } = await import('../lib/secrets/bundles.js');
             const resolvedBundleName = bundleName ?? (await pickBundleName('export'));
-            if (opts.toSsh) {
-                const hosts = opts.host ?? [];
-                if (hosts.length === 0) {
-                    throw new Error('--to-ssh requires at least one --host <target>.');
-                }
+            // The presence of --host selects SSH push: --host is the destination
+            // and carries the mode (no separate --to-ssh needed — it would be
+            // strictly redundant since SSH always requires at least one host).
+            const hosts = opts.host ?? [];
+            if (hosts.length > 0) {
                 for (const h of hosts)
                     assertValidSshTarget(h);
                 const remoteBackend = parseBackendOpt(opts.remoteBackend);

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

@@ -21,6 +21,7 @@ import { discoverSessions, countSessionsInScope, resolveSessionById, searchConte
 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';
@@ -656,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)));
     }
@@ -1332,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)
@@ -1360,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) {