@phnx-labs/agents-cli 1.20.32 → 1.20.34

package/dist/commands/secrets-migrate.js

@@ -23,7 +23,7 @@ import chalk from 'chalk';
 import * as crypto from 'crypto';
 import * as fs from 'fs';
 import * as path from 'path';
-import { deleteKeychainToken, getKeychainToken, hasKeychainToken, listKeychainItems, setKeychainToken, } from '../lib/secrets/index.js';
+import { deleteKeychainToken, getKeychainToken, getKeychainTokens, hasKeychainToken, listKeychainItems, listLegacyKeychainItems, setKeychainToken, } from '../lib/secrets/index.js';
 import { getBackupsDir } from '../lib/state.js';
 import { encryptBlob, MIN_PASSPHRASE_LEN } from '../lib/secrets/sync.js';
 import { isInteractiveTerminal, isPromptCancelled } from './utils.js';
@@ -104,6 +104,7 @@ export function registerSecretsMigrateAclCommand(secrets) {
         .description('Refresh existing keychain ACLs to use the signed Agents CLI helper. Dry-run by default.')
         .option('--commit', 'Perform writes (default is dry-run reporting only)')
         .option('--prefix <p>', `Restrict to items beginning with PREFIX (default ${ITEM_PREFIX})`, ITEM_PREFIX)
+        .option('--all', 'Rewrite EVERY matching item, not just legacy stragglers (slower; a Touch ID prompt per item)')
         .option('--passphrase-env <var>', 'Read the backup passphrase from this env var instead of prompting')
         .action(async (opts) => {
         try {
@@ -114,15 +115,24 @@ export function registerSecretsMigrateAclCommand(secrets) {
             if (!prefix.startsWith(ITEM_PREFIX)) {
                 throw new Error(`--prefix must start with '${ITEM_PREFIX}' to avoid touching unrelated Keychain items (got '${prefix}').`);
             }
-            const items = listKeychainItems(prefix).map((item) => {
+            // Default: migrate ONLY legacy stragglers (items still in the file-based
+            // keychain) — modern DP items need no rewrite and touching them is a
+            // Touch ID prompt per item for nothing. `--all` forces the old full
+            // rewrite. Either way this is one command over every matching item — no
+            // one-by-one invocation.
+            const names = opts.all ? listKeychainItems(prefix) : listLegacyKeychainItems(prefix);
+            const items = names.map((item) => {
                 const localExists = hasKeychainToken(item);
                 return { item, sync: !localExists };
             });
             if (items.length === 0) {
-                console.log(chalk.gray(`No keychain items with prefix '${prefix}'.`));
+                console.log(opts.all
+                    ? chalk.gray(`No keychain items with prefix '${prefix}'.`)
+                    : chalk.green(`Nothing to migrate — all items under '${prefix}' already use the modern ACL.`));
                 return;
             }
-            console.log(chalk.bold(`Found ${items.length} item(s) under '${prefix}'.`));
+            const label = opts.all ? 'item' : 'legacy item';
+            console.log(chalk.bold(`Found ${items.length} ${label}(s) under '${prefix}' to migrate.`));
             if (!opts.commit) {
                 for (const { item, sync } of items) {
                     console.log(`  ${chalk.cyan(item)} ${chalk.gray(sync ? '(synced)' : '(local)')}`);
@@ -131,16 +141,18 @@ export function registerSecretsMigrateAclCommand(secrets) {
                 console.log(chalk.gray('Dry-run — pass --commit to perform the migration.'));
                 return;
             }
-            // Commit phase. Snapshot every value first, encrypt, then mutate.
+            // Commit phase. Snapshot every value first (one batched read behind a
+            // single helper process, so DP items share one auth context), encrypt,
+            // then mutate.
+            const fetched = getKeychainTokens(items.map((i) => i.item));
             const records = [];
             for (const { item, sync } of items) {
-                try {
-                    const value = getKeychainToken(item);
-                    records.push({ item, sync, value });
-                }
-                catch (err) {
-                    console.error(chalk.red(`Skipping '${item}': read failed (${err.message}).`));
+                const value = fetched.get(item);
+                if (value === undefined) {
+                    console.error(chalk.red(`Skipping '${item}': read failed or item absent.`));
+                    continue;
                 }
+                records.push({ item, sync, value });
             }
             if (records.length === 0) {
                 console.error(chalk.red('No items could be read. Aborting before any writes.'));

package/dist/commands/secrets.d.ts

@@ -18,3 +18,23 @@ export { SSH_TARGET_RE, assertValidSshTarget };
 export declare function bundleEnvToDotenv(env: Record<string, string>): string;
 /** Register the `agents secrets` command tree. */
 export declare function registerSecretsCommands(program: Command): void;
+/**
+ * Quote one argument for a Windows `cmd.exe` command line, as built by Node's
+ * `spawn(..., { shell: true })` on win32 (`agents secrets exec`). cmd.exe does
+ * NO quoting of its own, so an unquoted arg with a space is split into several
+ * args, and a cmd metacharacter (`&|<>()^`) would be interpreted by the shell.
+ * We wrap any arg with whitespace, a quote, or a metacharacter in double quotes
+ * and escape embedded quotes / trailing backslashes per the CommandLineToArgvW
+ * rules, so the *child's* argv parse reconstructs the original argument.
+ *
+ * CAVEAT: cmd.exe expands `%VAR%` (always) and `!VAR!` (under delayed expansion)
+ * BEFORE argv parsing, and double-quoting does NOT suppress `%`/`!` (the
+ * "BatBadBut" / CVE-2024-1874 class). We deliberately do not escape `%`/`!`:
+ * `agents secrets exec` runs a caller-supplied command against a bundle the
+ * caller owns, so caller-controlled `%`/`!` is not a privilege boundary. If that
+ * ever changes (exec'ing an untrusted command line), route through a shell that
+ * disables expansion rather than relying on this quoter. An empty arg becomes
+ * `""`. Exported for tests. No-ops on non-Windows (the caller only invokes it
+ * under `process.platform === 'win32'`).
+ */
+export declare function quoteWin32ExecArg(arg: string): string;

package/dist/commands/secrets.js

@@ -1325,8 +1325,18 @@ Examples:
                 secretEnv = readAndResolveBundleEnv(bundleName, { caller: `command ${cmd}` }).env;
             }
             const { spawn } = await import('child_process');
-            const proc = spawn(cmd, args, {
+            // On Windows, spawn without a shell ENOENTs for `.cmd`/`.bat` launchers
+            // (npm, yarn, most JS CLIs) and shell built-ins, so we set shell:true.
+            // With shell:true Node hands cmd.exe a single command line with NO quoting
+            // of its own, so args containing spaces or cmd metacharacters must be
+            // quoted here (quoteWin32ExecArg) or they'd be split. See that helper for
+            // the cmd.exe %VAR%/!VAR! expansion caveat.
+            const useShell = process.platform === 'win32';
+            const spawnCmd = useShell ? quoteWin32ExecArg(cmd) : cmd;
+            const spawnArgs = useShell ? args.map(quoteWin32ExecArg) : args;
+            const proc = spawn(spawnCmd, spawnArgs, {
                 stdio: 'inherit',
+                shell: useShell,
                 env: { ...process.env, ...secretEnv },
             });
             proc.on('close', (code) => process.exit(code ?? 0));
@@ -1619,6 +1629,48 @@ function humanRemaining(expiresAt) {
     const days = Math.round(hours / 24);
     return `locks in ${days} day${days === 1 ? '' : 's'}`;
 }
+/**
+ * Quote one argument for a Windows `cmd.exe` command line, as built by Node's
+ * `spawn(..., { shell: true })` on win32 (`agents secrets exec`). cmd.exe does
+ * NO quoting of its own, so an unquoted arg with a space is split into several
+ * args, and a cmd metacharacter (`&|<>()^`) would be interpreted by the shell.
+ * We wrap any arg with whitespace, a quote, or a metacharacter in double quotes
+ * and escape embedded quotes / trailing backslashes per the CommandLineToArgvW
+ * rules, so the *child's* argv parse reconstructs the original argument.
+ *
+ * CAVEAT: cmd.exe expands `%VAR%` (always) and `!VAR!` (under delayed expansion)
+ * BEFORE argv parsing, and double-quoting does NOT suppress `%`/`!` (the
+ * "BatBadBut" / CVE-2024-1874 class). We deliberately do not escape `%`/`!`:
+ * `agents secrets exec` runs a caller-supplied command against a bundle the
+ * caller owns, so caller-controlled `%`/`!` is not a privilege boundary. If that
+ * ever changes (exec'ing an untrusted command line), route through a shell that
+ * disables expansion rather than relying on this quoter. An empty arg becomes
+ * `""`. Exported for tests. No-ops on non-Windows (the caller only invokes it
+ * under `process.platform === 'win32'`).
+ */
+export function quoteWin32ExecArg(arg) {
+    if (arg.length > 0 && !/[\s"&|<>()^]/.test(arg))
+        return arg;
+    let result = '"';
+    let backslashes = 0;
+    for (const ch of arg) {
+        if (ch === '\\') {
+            backslashes += 1;
+            continue;
+        }
+        if (ch === '"') {
+            // Double the run of backslashes, then escape this quote.
+            result += '\\'.repeat(backslashes * 2 + 1) + '"';
+            backslashes = 0;
+            continue;
+        }
+        result += '\\'.repeat(backslashes) + ch;
+        backslashes = 0;
+    }
+    // Trailing backslashes precede the closing quote → must be doubled.
+    result += '\\'.repeat(backslashes * 2) + '"';
+    return result;
+}
 /**
  * Copy text to the system clipboard, cross-platform.
  * macOS: `pbcopy`. Windows: `clip`. Linux: tries `wl-copy` (Wayland), then

package/dist/commands/sessions.js

@@ -215,6 +215,23 @@ function signalBadges(s) {
         parts.push(chalk.magenta(`wt:${s.worktree.slug}`));
     return parts.join(' ');
 }
+/**
+ * Compact provenance badge: how to reach the session, not what it's doing.
+ * `ssh` flags a remote host; the tmux pane id is the send-keys target the feed
+ * would type back into. Local, non-tmux sessions add nothing (the common case).
+ */
+function provenanceBadge(p) {
+    if (!p)
+        return '';
+    const parts = [];
+    if (p.transport === 'ssh')
+        parts.push(chalk.red('ssh'));
+    if (p.mux?.kind === 'tmux' && p.mux.pane)
+        parts.push(chalk.green(`tmux ${p.mux.pane}`));
+    else if (p.mux?.kind === 'screen')
+        parts.push(chalk.green('screen'));
+    return parts.join(' ');
+}
 /**
  * Render a single agent-session row inside an already-printed group header.
  * Indent is the leading whitespace (2 spaces for flat groups, 4 inside a
@@ -228,7 +245,7 @@ function printActiveRow(s, indent) {
     const hostCol = chalk.gray(padToWidth(truncateToWidth(s.host ?? '-', 8), 9));
     const statusCol = statusColor(s.status)(padToWidth(truncateToWidth(activityLabel(s), 8), 9));
     const fork = s.pidCount && s.pidCount > 1 ? chalk.dim(`×${s.pidCount} `) : '';
-    const badges = (fork ? fork : '') + signalBadges(s);
+    const badges = (fork ? fork : '') + [signalBadges(s), provenanceBadge(s.provenance)].filter(Boolean).join(' ');
     const desc = buildSessionDescription(s) || '-';
     // Fill the remaining width with the preview so nothing wraps under tmux/SSH.
     const fixed = stringWidth(indent) + 9 + 9 + 9 + 9 + (badges ? stringWidth(badges) + 1 : 0);

package/dist/commands/skills.js

@@ -8,9 +8,9 @@ import { AGENTS, resolveAgentName, formatAgentError, agentLabel, } from '../lib/
 import { capableAgents } from '../lib/capabilities.js';
 import { cloneRepo } from '../lib/git.js';
 import { discoverSkillsFromRepo, installSkillCentrally, listInstalledSkills, listInstalledSkillsWithScope, getSkillInfo, getSkillRules, getSkillsDir, countSkillFiles, tryParseSkillMetadata, diffVersionSkills, iterSkillsCapableVersions, removeSkillFromVersion, } from '../lib/skills.js';
-import { getGlobalDefault, resolveVersionAlias, syncResourcesToVersion, promptAgentVersionSelection, getVersionHomePath, } from '../lib/versions.js';
+import { getGlobalDefault, syncResourcesToVersion, promptAgentVersionSelection, getVersionHomePath, } from '../lib/versions.js';
 import { recordVersionResources } from '../lib/state.js';
-import { isPromptCancelled, isInteractiveTerminal, parseCommaSeparatedList, printWithPager, requireInteractiveSelection, resolveAgentTargetsAutoInstalling, promptRemovalTargets, } from './utils.js';
+import { isPromptCancelled, isInteractiveTerminal, parseCommaSeparatedList, printWithPager, requireInteractiveSelection, resolveAgentTargetsAutoInstalling, promptRemovalTargets, resolveListFilterOrExit, } from './utils.js';
 import { showResourceList, buildTargetsSection, } from './resource-view.js';
 /** Register the `agents skills` command tree (list, add, remove, sync, prune, view). */
 export function registerSkillsCommands(program) {
@@ -59,7 +59,7 @@ When to use:
                 process.exit(1);
             }
             filterAgent = resolved;
-            filterVersion = resolveVersionAlias(resolved, parts[1]);
+            filterVersion = resolveListFilterOrExit(resolved, parts[1]);
         }
         const rows = await buildSkillRows({ filterAgent, filterVersion });
         spinner.stop();

package/dist/commands/status.d.ts

@@ -0,0 +1,12 @@
+/**
+ * `agents status` — the unified sync-status surface.
+ *
+ * One command that answers "is my fleet in sync?" the same way every other
+ * surface does, because it reads the same engine (computeSyncStatus). Human mode
+ * renders the summary and, when a TTY finds drift, offers the interactive
+ * "sync now?" flow (promptDriftSync). `--json` emits the stable UnifiedSyncStatus
+ * contract the menu-bar and Agency consume. `--yes` reconciles everything with no
+ * prompts (the "kick it" path, safe in scripts).
+ */
+import { Command } from 'commander';
+export declare function registerStatusCommand(program: Command): void;

package/dist/commands/status.js

@@ -0,0 +1,81 @@
+/**
+ * `agents status` — the unified sync-status surface.
+ *
+ * One command that answers "is my fleet in sync?" the same way every other
+ * surface does, because it reads the same engine (computeSyncStatus). Human mode
+ * renders the summary and, when a TTY finds drift, offers the interactive
+ * "sync now?" flow (promptDriftSync). `--json` emits the stable UnifiedSyncStatus
+ * contract the menu-bar and Agency consume. `--yes` reconciles everything with no
+ * prompts (the "kick it" path, safe in scripts).
+ */
+import chalk from 'chalk';
+import { AGENTS } from '../lib/agents.js';
+import { setHelpSections } from '../lib/help.js';
+import { computeSyncStatus } from '../lib/sync-status.js';
+import { promptDriftSync } from '../lib/drift-sync.js';
+const agentName = (id) => AGENTS[id]?.name ?? id;
+function versionSummary(v) {
+    if (!v.everSynced)
+        return chalk.gray('never synced');
+    if (v.needsSync) {
+        const bits = [];
+        if (v.counts.drifted)
+            bits.push(`${v.counts.drifted} drifted`);
+        if (v.counts.missing)
+            bits.push(`${v.counts.missing} missing`);
+        return chalk.yellow(bits.join(' · '));
+    }
+    return chalk.green('in sync');
+}
+export function registerStatusCommand(program) {
+    const cmd = program
+        .command('status')
+        .description('Unified sync status across the fleet — what is drifted, missing, or behind, with an option to sync it.')
+        .option('--json', 'Output the machine-readable UnifiedSyncStatus contract')
+        .option('--yes', 'Reconcile everything detected (pull .system if behind + sync drifted/missing resources) without prompting')
+        .option('--cwd <path>', 'Resolution cwd for project layer detection (default: process.cwd())');
+    setHelpSections(cmd, {
+        examples: `
+      # Show what's out of sync; offer to fix it (interactive)
+      agents status
+
+      # Machine-readable status for the menu-bar / Agency
+      agents status --json
+
+      # Reconcile everything with no prompts (CI / scripts / the "kick it" path)
+      agents status --yes
+    `,
+    });
+    cmd.action(async (opts) => {
+        const cwd = opts.cwd ?? process.cwd();
+        if (opts.json) {
+            const status = await computeSyncStatus({ cwd });
+            console.log(JSON.stringify(status, null, 2));
+            return;
+        }
+        const status = await computeSyncStatus({ cwd });
+        // Human summary header (always) — the per-version readout.
+        console.log(chalk.bold('Fleet sync status'));
+        if (status.system.unknown) {
+            console.log(`  ${'.system repo'.padEnd(28)} ${chalk.gray('freshness unknown (no upstream)')}`);
+        }
+        else if (status.system.behind > 0) {
+            console.log(`  ${'.system repo'.padEnd(28)} ${chalk.yellow(`${status.system.behind} behind`)}`);
+        }
+        else {
+            console.log(`  ${'.system repo'.padEnd(28)} ${chalk.green('up to date')}`);
+        }
+        if (status.agents.length === 0) {
+            console.log(chalk.gray('  (no installed agent versions)'));
+        }
+        for (const v of status.agents) {
+            const label = `${agentName(v.agent)}@${v.version}${v.isDefault ? chalk.gray(' (default)') : ''}`;
+            console.log(`  ${label.padEnd(28)} ${versionSummary(v)}`);
+        }
+        if (status.totals.orphan > 0) {
+            console.log(chalk.gray(`  (${status.totals.orphan} orphan${status.totals.orphan === 1 ? '' : 's'} — run \`agents prune cleanup\`)`));
+        }
+        // Hand off to the shared interactive/apply flow (summary already printed above).
+        await promptDriftSync({ cwd, yes: opts.yes, status, quiet: true });
+    });
+}

package/dist/commands/sync.js

@@ -35,10 +35,10 @@ import { compileRulesForProject } from '../lib/rules/compile.js';
 import { runLaunchSync } from '../lib/project-launch.js';
 import { isInteractiveTerminal, isPromptCancelled } from './utils.js';
 import { runUmbrellaSync } from '../lib/sync-umbrella.js';
+import { addHostOption } from '../lib/hosts/option.js';
 /** Register the `agents sync` command. */
 export function registerSyncCommand(program) {
-    program
-        .command('sync [agentSpec] [repo]')
+    addHostOption(program.command('sync [agentSpec] [repo]'))
         .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", "claude@2.1.142", a selector: @latest / @oldest / @pinned (= @default), or @all for every installed version.\n\nAppend a [repo] (or pass --repo) to scope the sync to a single DotAgent repo — system / user / project / <alias>. e.g. "agents sync claude@all system" reconciles only the system repo\'s resources into every installed Claude.\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)')

package/dist/commands/teams.js

@@ -1,7 +1,8 @@
 import chalk from 'chalk';
 import * as fs from 'fs/promises';
+import { addHostOption } from '../lib/hosts/option.js';
 import * as path from 'path';
-import { AgentManager, checkAllClis, getAgentsDir, VALID_TASK_TYPES, } from '../lib/teams/agents.js';
+import { AgentManager, checkAllClis, checkCliSignedIn, getAgentsDir, resolveSignInAdvisory, VALID_TASK_TYPES, } from '../lib/teams/agents.js';
 import { resolveProvider } from '../lib/cloud/registry.js';
 import { runSupervisor } from '../lib/teams/supervisor.js';
 import { handleSpawn, handleStatus, handleStop, handleTasks, toTaskStatusSummary, } from '../lib/teams/api.js';
@@ -9,6 +10,7 @@ import { createTeam, ensureTeam, getTeam, loadTeams, removeTeam, teamExists, } f
 import { setHelpSections } from '../lib/help.js';
 import { createWorktree, isGitRepo, hasUncommittedChanges, removeWorktree, } from '../lib/teams/worktree.js';
 import { isVersionInstalled, resolveVersionAlias, resolveVersionAliasLoose } from '../lib/versions.js';
+import { AGENTS, warnAgentDeprecated } from '../lib/agents.js';
 import { discoverSessions, parseTimeFilter, resolveSessionById } from '../lib/session/discover.js';
 import { buildPreview as buildSessionPreview } from './sessions-picker.js';
 import { parseExecEnv } from '../lib/exec.js';
@@ -132,7 +134,7 @@ function parseTeammate(spec) {
         }
     }
     die(`Unknown teammate '${spec}'. Available agents: ${VALID_AGENTS.join(', ')}.\n` +
-        `  Use 'claude', 'claude@2.1.112', or the name of a profile from 'agents view'.`);
+        `  Use 'claude', 'kimi@latest', 'kimi@0.19.2' (a version from 'agents view'), or a profile name.`);
 }
 function shortId(id) {
     return id.slice(0, 8);
@@ -182,6 +184,31 @@ export function wireCloudDispatcher(mgr) {
         return { cloudSessionId: cloudTask.id };
     });
 }
+/**
+ * Advisory: warn once per agent type of any still-pending (staged `--after`)
+ * teammate whose CLI may not be signed in. Warn-only — never blocks `start`.
+ * Local teammates only; cloud teammates authenticate through their provider.
+ */
+async function warnUnsignedTeammates(mgr, team) {
+    let pending;
+    try {
+        pending = (await mgr.listByTask(team)).filter((a) => a.status === 'pending' && !a.cloudProvider);
+    }
+    catch {
+        return; // team not loadable yet — nothing to warn about
+    }
+    const seen = new Set();
+    for (const a of pending) {
+        const agent = a.agentType;
+        if (seen.has(agent) || !AGENT_NAMES[agent])
+            continue;
+        seen.add(agent);
+        if (!(await checkCliSignedIn(agent))) {
+            console.error(chalk.yellow(`⚠ ${AGENT_NAMES[agent]} may not be signed in (detection is unreliable). Launching anyway.`) +
+                chalk.gray(`\n  If it fails to start, run \`${AGENTS[agent].cliCommand}\` to log in, or pass --force to silence this.`));
+        }
+    }
+}
 /** Single-wave start used by `teams start` without --watch. */
 async function runOneWave(mgr, team, json) {
     const launched = await mgr.startReady(team);
@@ -673,8 +700,7 @@ export function registerTeamsCommands(program) {
     `,
     });
     // list
-    teams
-        .command('list [query]')
+    addHostOption(teams.command('list [query]'))
         .alias('ls')
         .description('List your teams, most recent activity first')
         .option('-a, --agent <agent>', 'Filter: only teams with this agent (e.g. claude or claude@2.1.112)')
@@ -785,8 +811,7 @@ export function registerTeamsCommands(program) {
         printTeamTable(rows);
     });
     // create
-    teams
-        .command('create <team>')
+    addHostOption(teams.command('create <team>'))
         .aliases(['c', 'new'])
         .description('Start a new team. No teammates yet; add them with `teams add`.')
         .option('-d, --description <text>', 'One-line summary of what this team is working on')
@@ -825,8 +850,7 @@ export function registerTeamsCommands(program) {
         }
     });
     // add
-    teams
-        .command('add <team> <teammate> <task>')
+    addHostOption(teams.command('add <team> <teammate> <task>'))
         .alias('a')
         .description("Add a teammate to work on a task. Runs in background; returns immediately. Use 'status' to check in.")
         .option('-n, --name <name>', 'Friendly name for this teammate (e.g. alice). Required if using --after. Unique within team.')
@@ -841,6 +865,7 @@ export function registerTeamsCommands(program) {
         .option('--cloud <provider>', `Dispatch to cloud backend instead of local CLI: ${VALID_CLOUD_PROVIDERS.join('|')}`)
         .option('--repo <owner/repo>', 'GitHub repository (required for --cloud rush)')
         .option('--branch <name>', 'Target git branch for cloud dispatch')
+        .option('--force', "Skip the advisory 'may not be signed in' warning (detection is unreliable)")
         .option('--json', 'Output machine-readable JSON')
         .action(async (team, teammate, task, opts) => {
         if (!VALID_MODES.includes(opts.mode)) {
@@ -867,10 +892,18 @@ export function registerTeamsCommands(program) {
             }
         }
         const { agent, version, profileName } = parseTeammate(teammate);
+        warnAgentDeprecated(agent);
         if (version && !isVersionInstalled(agent, version)) {
             die(`${AGENT_NAMES[agent]} ${version} isn't installed.\n` +
                 `  Install it:  agents add ${agent}@${version}\n` +
-                `  Or see what's installed:  agents view ${agent}`);
+                `  Or see what's installed (incl. @latest):  agents view ${agent}`);
+        }
+        // Advisory sign-in check: warn but NEVER block. Detection is unreliable
+        // for opaque-cred agents, so a false negative must not stop a team. Cloud
+        // dispatch authenticates through the provider, not the local CLI — skip it.
+        if (!opts.force && !cloudProviderId && !(await checkCliSignedIn(agent))) {
+            console.error(chalk.yellow(`⚠ ${AGENT_NAMES[agent]} may not be signed in (detection is unreliable). Adding anyway.`) +
+                chalk.gray(`\n  If it fails to start, run \`${AGENTS[agent].cliCommand}\` to log in, or pass --force to silence this.`));
         }
         if (opts.name !== undefined) {
             if (!opts.name || !/^[A-Za-z0-9_-]+$/.test(opts.name)) {
@@ -1041,8 +1074,7 @@ export function registerTeamsCommands(program) {
         }
     });
     // status
-    teams
-        .command('status [team]')
+    addHostOption(teams.command('status [team]'))
         .aliases(['s', 'st', 'check'])
         .description("Check in on a team: status, files touched, recent commands, last messages. Pass --verbose for the full per-teammate dump; --since for delta polling.")
         .option('-f, --filter <state>', 'Show only teammates in this state: running, completed, failed, stopped, or all (default: all)', 'all')
@@ -1136,13 +1168,13 @@ export function registerTeamsCommands(program) {
         console.log(chalk.gray(`${running.length} teammate${running.length === 1 ? '' : 's'} running. See 'agents sessions --active' for the full cross-context view.`));
     });
     // start — fire any staged teammates whose --after deps have all completed
-    teams
-        .command('start [team]')
+    addHostOption(teams.command('start [team]'))
         .description('Launch any pending teammates whose --after dependencies are satisfied. Use --watch to keep draining the DAG as teammates finish and as new tasks are added mid-flight.')
         .option('--json', 'Output machine-readable JSON')
         .option('--watch', 'Keep running: poll every --interval seconds, fire new waves, exit when the DAG drains.')
         .option('--interval <seconds>', 'Seconds between waves in --watch mode (default 8)', '8')
         .option('--max-waves <n>', 'Safety cap on waves in --watch mode (default 1000)', '1000')
+        .option('--force', "Skip the advisory 'may not be signed in' warning for staged teammates (detection is unreliable)")
         .action(async (team, opts) => {
         const mgr = mkManager();
         wireCloudDispatcher(mgr);
@@ -1152,6 +1184,8 @@ export function registerTeamsCommands(program) {
                 return;
             team = picked;
         }
+        if (!opts.force && !isJsonMode(opts))
+            await warnUnsignedTeammates(mgr, team);
         if (!opts.watch) {
             await runOneWave(mgr, team, Boolean(opts.json));
             return;
@@ -1190,8 +1224,7 @@ export function registerTeamsCommands(program) {
         }
     });
     // stop
-    teams
-        .command('stop [team] [teammate]')
+    addHostOption(teams.command('stop [team] [teammate]'))
         .description('Stop a running teammate. Can be restarted later. Cleans up worktree if no uncommitted changes.')
         .option('--json', 'Output machine-readable JSON')
         .action(async (team, ref, opts) => {
@@ -1451,19 +1484,45 @@ export function registerTeamsCommands(program) {
     teams
         .command('doctor')
         .alias('dr')
-        .description('Check which agents are installed and available to join a team. Verifies CLI paths.')
+        .description('Check which agents are installed and available to join a team. Verifies CLI paths and shows an advisory sign-in hint.')
         .option('--json', 'Output machine-readable JSON')
         .action(async (opts) => {
         const info = checkAllClis();
+        // Advisory enrichment only. Sign-in detection is UNRELIABLE, so it never
+        // changes the authoritative installed/ready column — it annotates. And an
+        // agent that is actually running in a team is treated as signed in
+        // regardless of the probe, so doctor never reports a working agent as
+        // logged out ("don't show wrong stuff").
+        const running = new Set();
+        try {
+            for (const a of await mkManager().listRunning())
+                running.add(a.agentType);
+        }
+        catch { /* no teams yet — leave running empty */ }
+        const auth = {};
+        await Promise.all(Object.entries(info).map(async ([name, entry]) => {
+            const isRunning = running.has(name);
+            const probe = entry.installed && !isRunning ? await checkCliSignedIn(name) : false;
+            auth[name] = resolveSignInAdvisory(entry.installed, isRunning, probe);
+        }));
         if (isJsonMode(opts)) {
-            console.log(JSON.stringify(info, null, 2));
+            const merged = {};
+            for (const [name, entry] of Object.entries(info))
+                merged[name] = { ...entry, ...auth[name] };
+            console.log(JSON.stringify(merged, null, 2));
             return;
         }
         console.log(chalk.bold('Who can join a team:'));
         for (const [name, entry] of Object.entries(info)) {
             const pretty = AGENT_NAMES[name] || name;
             if (entry.installed) {
-                console.log(`  ${chalk.green('ready')}  ${pretty.padEnd(10)} ${chalk.gray(entry.path || '')}`);
+                const { signedIn, running: isRunning } = auth[name];
+                const hint = isRunning
+                    ? chalk.gray('in use')
+                    : signedIn
+                        ? chalk.gray('signed in')
+                        : chalk.gray('sign-in unverified');
+                console.log(`  ${chalk.green('ready')}  ${pretty.padEnd(10)} ${chalk.gray(entry.path || '')}  ${hint}`);
             }
             else {
                 console.log(`  ${chalk.red('no   ')}  ${pretty.padEnd(10)} ${chalk.gray(entry.error || 'not installed')}`);

package/dist/commands/usage.js

@@ -1,3 +1,4 @@
+import { addHostOption } from '../lib/hosts/option.js';
 import chalk from 'chalk';
 import { ALL_AGENT_IDS, AGENTS, getAccountInfo, agentLabel, resolveAgentName, formatAgentError, } from '../lib/agents.js';
 import { listInstalledVersions, getGlobalDefault, getVersionHomePath } from '../lib/versions.js';
@@ -5,8 +6,7 @@ import { formatUsageSection, getUsageInfoForIdentity } from '../lib/usage.js';
 /** Agents whose CLI surfaces usage data we can read today. */
 const USAGE_SUPPORTED = new Set(['claude', 'codex']);
 export function registerUsageCommand(program) {
-    program
-        .command('usage [agent]')
+    addHostOption(program.command('usage [agent]'))
         .description('Show rate-limit / quota usage per agent')
         .addHelpText('after', `
 Examples:

package/dist/commands/utils.d.ts

@@ -6,6 +6,14 @@
  */
 import type { AgentId } from '../lib/types.js';
 import { type InstalledAgentTargetResult, type VersionSelectionResult } from '../lib/versions.js';
+/**
+ * Resolve a read/list command's `@version` filter through the agent-spec engine,
+ * exiting cleanly on a bad spec. Drop-in for the old
+ * `resolveVersionAlias(agent, parts[1])`:
+ *   undefined → show all · @default/@pinned → the default version ·
+ *   @latest/@oldest/@x.y.z → concrete.
+ */
+export declare function resolveListFilterOrExit(agent: AgentId, qualifier: string | undefined | null): string | undefined;
 /**
  * Check if an error is from user cancelling a prompt (Ctrl+C)
  */

package/dist/commands/utils.js

@@ -11,6 +11,26 @@ import ora from 'ora';
 import { confirm } from '@inquirer/prompts';
 import { agentLabel, resolveAgentName } from '../lib/agents.js';
 import { installVersion, listInstalledVersions, resolveAgentVersionTargets, resolveInstalledAgentTargets, } from '../lib/versions.js';
+import { resolveListFilter, AgentSpecError } from '../lib/agent-spec/index.js';
+/**
+ * Resolve a read/list command's `@version` filter through the agent-spec engine,
+ * exiting cleanly on a bad spec. Drop-in for the old
+ * `resolveVersionAlias(agent, parts[1])`:
+ *   undefined → show all · @default/@pinned → the default version ·
+ *   @latest/@oldest/@x.y.z → concrete.
+ */
+export function resolveListFilterOrExit(agent, qualifier) {
+    try {
+        return resolveListFilter(agent, qualifier);
+    }
+    catch (e) {
+        if (e instanceof AgentSpecError) {
+            console.error(chalk.red(e.message));
+            process.exit(1);
+        }
+        throw e;
+    }
+}
 /**
  * Check if an error is from user cancelling a prompt (Ctrl+C)
  */

package/dist/commands/versions.js

@@ -1,9 +1,10 @@
+import { addHostOption } from '../lib/hosts/option.js';
 import chalk from 'chalk';
 import ora from 'ora';
 import * as fs from 'fs';
 import * as path from 'path';
 import { select, confirm, checkbox } from '@inquirer/prompts';
-import { AGENTS, ALL_AGENT_IDS, getAccountEmail, getAccountInfo, agentLabel, } from '../lib/agents.js';
+import { AGENTS, ALL_AGENT_IDS, getAccountEmail, getAccountInfo, agentLabel, warnAgentDeprecated, } from '../lib/agents.js';
 import { formatUsageSummary, getUsageInfoForIdentity, getUsageInfoByIdentity, getUsageLookupKey, } from '../lib/usage.js';
 import { viewAction } from './view.js';
 import { readManifest, writeManifest, createDefaultManifest } from '../lib/manifest.js';
@@ -272,6 +273,7 @@ export function registerVersionsCommands(program) {
             }
             const { agent, version } = parsed;
             const agentConfig = AGENTS[agent];
+            warnAgentDeprecated(agent);
             if (!agentConfig.npmPackage && !agentConfig.installScript) {
                 console.log(chalk.yellow(`${agentLabel(agentConfig.id)} has no npm package. Install manually.`));
                 continue;
@@ -762,8 +764,7 @@ export function registerVersionsCommands(program) {
         }
     });
     // Deprecated: use `agents view` instead
-    program
-        .command('list [agent]')
+    addHostOption(program.command('list [agent]'))
         .description('List installed agent CLI versions')
         .action(async (agentArg) => {
         console.log(chalk.red('Deprecated: "agents list" is now "agents view"\n'));