@phnx-labs/agents-cli 1.20.32 → 1.20.34

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 ## Unreleased
 
+## 1.20.34
+
+**Test suite runs remotely on a crabbox VM (#525, #540)**
+
+- `scripts/release.sh`'s test gate now runs `bun install && bun run build && bun run test` on a leased crabbox VM via `scripts/sandbox.sh` instead of freezing the local machine, matching CI's Build→Test order (crabbox's sync honors `.gitignore`, so the gitignored `dist/` is built on the box). A new `bun run test:remote` offloads the suite the same way for local dev. Publishing still happens locally — only the signed macOS keychain helper can be produced and notarized here, and crabbox boxes are Linux. Source: `scripts/sandbox.sh`, `scripts/release.sh`, `package.json`.
+- `scripts/sandbox.sh` box acquisition is now robust: secrets load via `agents secrets export --plaintext` (the bare form now hard-errors), a missing `.crabbox.yaml` no longer aborts the script under `set -e`, and the agents-cli/claude install is gated to PR mode so test-mode runs match GitHub CI. Box selection gates on `crabbox status … ready=true` — skipping failed-bootstrap duds (which still report `status=running`) and warming a fresh box if none are ready — keyed on the stable `profile` label rather than an ephemeral slug. A dedicated `agents-cli` crabbox profile (`.crabbox.yaml`) isolates this repo's warm pool. Source: `scripts/sandbox.sh`, `.crabbox.yaml`.
+
 ## 1.20.31
 
 **`agents sessions <id>`: a catch-up digest for switching between many agents (#502)**

package/README.md

@@ -230,6 +230,30 @@ Profile YAML has no secrets -- safe to `agents repo push` to a shared repo. `age
 
 ---
 
+## Run on your own machines
+
+Dispatch any read-only or config command -- and `agents run` itself -- to another machine over SSH. No daemon.
+
+```bash
+# Enroll a machine (from ~/.ssh/config, or inline with user@address)
+agents hosts add gpu-box
+agents hosts check gpu-box              # reachable? which agents-cli version?
+
+# Run there instead of locally
+agents run claude --host gpu-box "profile this build"
+agents view claude --host gpu-box       # inspect the remote install
+agents sync --host gpu-box              # make the remote machine current
+
+# Your Tailscale fleet, auto-discovered
+agents devices sync                     # ingest `tailscale status`
+agents ssh mac-mini                     # hardened SSH: fails fast if offline,
+                                        # PowerShell on Windows, password-from-Keychain
+```
+
+**Hosts** (`agents hosts`) are git-synced dispatch targets in `agents.yaml`; **devices** (`agents devices`) are your Tailscale machines in a local registry. Both ride SSH. See [docs/00-concepts.md](docs/00-concepts.md#devices--hosts).
+
+---
+
 ## Teams
 
 ```bash
@@ -646,11 +670,13 @@ By default, secrets sync via iCloud Keychain to your other Macs. With `--no-iclo
 
 Which DotAgents resources each agent CLI can load. Source of truth: [src/lib/agents.ts](src/lib/agents.ts) (`capabilities`); gates use `supports(agent, cap, version)` from [src/lib/capabilities.ts](src/lib/capabilities.ts). Full matrix also in [docs/00-concepts.md](docs/00-concepts.md).
 
+> **† Gemini CLI is deprecated.** Google retired it for free, Pro, and Ultra tiers on **June 18, 2026** (announced at Google I/O 2026); the `gemini` command no longer serves requests on those tiers. agents-cli still manages existing installs, but warns on `agents add gemini` and `agents teams add … gemini`. New setups should use **Antigravity CLI** (`antigravity`), Google's official successor — see [the transition notice](https://developers.googleblog.com/an-important-update-transitioning-gemini-cli-to-antigravity-cli/).
+
 | Agent | Versions | Hooks | MCP | Permissions | Skills | Commands | Plugins | Subagents | Rules | Workflows |
 |-------|----------|-------|-----|-------------|--------|----------|---------|-----------|-------|-----------|
 | Claude Code | yes | yes | yes | yes | yes | yes | yes | yes | `CLAUDE.md` | yes |
 | Codex CLI | yes | >= 0.116.0 | yes | no | yes | < 0.117.0 · skills ($name, >= 0.117) | >= 0.128.0 | no | `AGENTS.md` | no |
-| Gemini CLI | yes | >= 0.26.0 | yes | no | yes | yes (.toml) | no | no | `GEMINI.md` | no |
+| Gemini CLI † | yes | >= 0.26.0 | yes | no | yes | yes (.toml) | no | no | `GEMINI.md` | no |
 | Antigravity | yes | yes | yes | yes | yes | yes | yes | no | `AGENTS.md` | no |
 | Grok Build | yes | yes | yes | yes | yes | skills ($name) | yes | no | `AGENTS.md` | no |
 | OpenClaw | yes | yes | yes | no | yes | gateway | yes | yes | `workspace/AGENTS.md` | no |
@@ -672,7 +698,7 @@ Which DotAgents resources each agent CLI can load. Source of truth: [src/lib/age
 |-------|----------|-------|---------------|
 | Claude Code | yes | yes | yes |
 | Codex CLI | yes | yes | yes |
-| Gemini CLI | yes | yes | yes |
+| Gemini CLI † | yes | yes | yes |
 | Cursor | -- | yes | -- |
 | OpenCode | -- | yes | -- |
 | Grok Build | -- | yes | yes |

package/dist/commands/commands.js

@@ -9,9 +9,9 @@ import { cloneRepo } from '../lib/git.js';
 import { discoverCommands, resolveCommandSource, installCommandCentrally, listCentralCommands, listInstalledCommandsWithScope, getCommandInfo, diffVersionCommands, iterCommandsCapableVersions, removeCommandFromVersion, } from '../lib/commands.js';
 import { getCommandsDir } from '../lib/state.js';
 import { showResourceList, buildTargetsSection, } from './resource-view.js';
-import { listInstalledVersions, getGlobalDefault, resolveVersionAlias, syncResourcesToVersion, promptAgentVersionSelection, getVersionHomePath, resolveInstalledAgentTargets, } from '../lib/versions.js';
+import { listInstalledVersions, getGlobalDefault, syncResourcesToVersion, promptAgentVersionSelection, getVersionHomePath, resolveInstalledAgentTargets, } from '../lib/versions.js';
 import { recordVersionResources } from '../lib/state.js';
-import { isPromptCancelled, isInteractiveTerminal, parseCommaSeparatedList, printWithPager, requireInteractiveSelection, promptRemovalTargets, resolveAgentTargetsAutoInstalling, } from './utils.js';
+import { isPromptCancelled, isInteractiveTerminal, parseCommaSeparatedList, printWithPager, requireInteractiveSelection, promptRemovalTargets, resolveAgentTargetsAutoInstalling, resolveListFilterOrExit, } from './utils.js';
 /** Register the `agents commands` command tree (list, add, remove, sync, prune, view). */
 export function registerCommandsCommands(program) {
     const commandsCmd = 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 = buildCommandRows({ filterAgent, filterVersion });
         spinner.stop();

package/dist/commands/computer-actions.js

@@ -485,6 +485,7 @@ export function registerActionCommands(program) {
         .option('--bundle <id>', 'Bundle id (e.g. com.apple.TextEdit)')
         .option('--path <p>', 'Path to the .app bundle')
         .option('--name <s>', 'App name (resolved via /Applications and LaunchServices)')
+        .option('--host <device>', 'Drive a remote Windows device (requires `agents computer start --host <device>` first)')
         .option('--json', 'Emit JSON')
         .action(async (opts) => {
         if (!opts.bundle && !opts.path && !opts.name) {

package/dist/commands/computer.d.ts

@@ -12,6 +12,29 @@ export declare function shouldBlockOffPlatform(opts: {
     tcpConfigured: boolean;
     host?: string;
 }): boolean;
+/**
+ * Sniff the image format from the leading magic bytes: PNG starts with the
+ * 8-byte signature `89 50 4E 47` ("\x89PNG"), JPEG with `FF D8 FF`. Returns the
+ * canonical file extension, or null for anything else.
+ */
+export declare function detectImageFormat(buf: Buffer): '.png' | '.jpg' | null;
+/**
+ * Make the screenshot filename honest about its bytes. The two helper backends
+ * encode DIFFERENT formats and neither re-encodes to match the requested name:
+ * the macOS helper (ScreenCaptureKit) returns JPEG
+ * (packages/computer-helper/Sources/ComputerHelper/Screenshot.swift:207,212),
+ * the Windows helper returns PNG
+ * (packages/computer-helper-win/Screenshot.cs:33). So a fixed default extension
+ * cannot be correct for both — the only honest path is to sniff the real format
+ * and swap the extension to match. Pure so it's unit-testable.
+ *
+ * Returns the path to write to (caller's path with its extension corrected) and
+ * whether a correction was made. Unknown formats pass through unchanged.
+ */
+export declare function reconcileScreenshotExt(outPath: string, buf: Buffer): {
+    path: string;
+    corrected: boolean;
+};
 export declare function registerComputerCommand(program: Command): void;
 export declare function registerComputerSubcommands(program: Command): void;
 export { resolveHelperExec as resolveHelperPath };

package/dist/commands/computer.js

@@ -33,6 +33,42 @@ export function shouldBlockOffPlatform(opts) {
         return false; // remote path resolves its own endpoint
     return true;
 }
+/**
+ * Sniff the image format from the leading magic bytes: PNG starts with the
+ * 8-byte signature `89 50 4E 47` ("\x89PNG"), JPEG with `FF D8 FF`. Returns the
+ * canonical file extension, or null for anything else.
+ */
+export function detectImageFormat(buf) {
+    if (buf.length >= 4 && buf[0] === 0x89 && buf[1] === 0x50 && buf[2] === 0x4e && buf[3] === 0x47)
+        return '.png';
+    if (buf.length >= 3 && buf[0] === 0xff && buf[1] === 0xd8 && buf[2] === 0xff)
+        return '.jpg';
+    return null;
+}
+/**
+ * Make the screenshot filename honest about its bytes. The two helper backends
+ * encode DIFFERENT formats and neither re-encodes to match the requested name:
+ * the macOS helper (ScreenCaptureKit) returns JPEG
+ * (packages/computer-helper/Sources/ComputerHelper/Screenshot.swift:207,212),
+ * the Windows helper returns PNG
+ * (packages/computer-helper-win/Screenshot.cs:33). So a fixed default extension
+ * cannot be correct for both — the only honest path is to sniff the real format
+ * and swap the extension to match. Pure so it's unit-testable.
+ *
+ * Returns the path to write to (caller's path with its extension corrected) and
+ * whether a correction was made. Unknown formats pass through unchanged.
+ */
+export function reconcileScreenshotExt(outPath, buf) {
+    const actual = detectImageFormat(buf);
+    if (!actual)
+        return { path: outPath, corrected: false };
+    const cur = path.extname(outPath).toLowerCase();
+    const alreadyMatches = cur === actual || (actual === '.jpg' && (cur === '.jpg' || cur === '.jpeg'));
+    if (alreadyMatches)
+        return { path: outPath, corrected: false };
+    const base = outPath.slice(0, outPath.length - path.extname(outPath).length);
+    return { path: base + actual, corrected: true };
+}
 export function registerComputerCommand(program) {
     const computer = program
         .command('computer')
@@ -128,8 +164,8 @@ function registerScreenshotCommand(program) {
         .option('--list', 'List the app\'s windows (id/title/layer/bounds) instead of capturing — reveals modals/popups')
         .option('--window-id <n>', 'Capture a specific window by id (from --list)', (v) => parseInt(v, 10))
         .option('--display', 'Capture the whole display the app is on (composites stacked modals)')
-        .option('--out <path>', 'Output JPEG path', './computer-screenshot.jpg')
-        .option('--quality <n>', 'JPEG quality 1-100', (v) => parseInt(v, 10), 85)
+        .option('--out <path>', 'Output image path — extension auto-corrected to the encoded format (JPEG on macOS, PNG on a Windows --host)', './computer-screenshot.jpg')
+        .option('--quality <n>', 'JPEG quality 1-100 (macOS capture only; the Windows helper encodes lossless PNG and ignores this)', (v) => parseInt(v, 10), 85)
         .option('--json', 'Emit JSON (metadata for captures; window list for --list)')
         .action(async (opts) => {
         const quality = Math.max(1, Math.min(100, opts.quality || 85));
@@ -176,7 +212,10 @@ function registerScreenshotCommand(program) {
                 process.exit(1);
             }
             const buf = Buffer.from(b64, 'base64');
-            const outPath = path.resolve(opts.out);
+            // Sniff the real format and correct the extension so the filename never
+            // lies about its bytes (macOS -> JPEG, Windows helper -> PNG).
+            const requested = path.resolve(opts.out);
+            const { path: outPath, corrected } = reconcileScreenshotExt(requested, buf);
             fs.writeFileSync(outPath, buf);
             if (opts.json) {
                 // Drop the heavy base64 from the metadata echo; report where it went.
@@ -184,6 +223,9 @@ function registerScreenshotCommand(program) {
                 console.log(JSON.stringify(meta, null, 2));
             }
             else {
+                if (corrected) {
+                    console.log(`note: bytes are ${path.extname(outPath).slice(1).toUpperCase()}; corrected extension from ${path.basename(requested)}`);
+                }
                 const origin = res.origin || [];
                 const originStr = origin.length === 2 ? `, origin [${origin.join(',')}], scale ${res.scale ?? '?'}` : '';
                 console.log(`saved: ${outPath} (${res.width ?? '?'}x${res.height ?? '?'}, ${buf.byteLength} bytes${originStr})`);

package/dist/commands/cost.js

@@ -1,11 +1,11 @@
+import { addHostOption } from '../lib/hosts/option.js';
 import chalk from 'chalk';
 import { discoverSessions, parseTimeFilter } from '../lib/session/discover.js';
 import { queryUsageRollup, topSessionsByCost, } from '../lib/session/db.js';
 import { formatUsd, PRICING_VERSION } from '../lib/pricing/index.js';
 import { formatDuration } from '../lib/session/render.js';
 export function registerCostCommand(program) {
-    program
-        .command('cost')
+    addHostOption(program.command('cost'))
         .description('Roll up $ cost and duration across local agent sessions')
         .option('--json', 'Output the rollup as JSON')
         .option('--since <time>', 'Only sessions newer than this (e.g., 7d, 4w, or ISO date)')

package/dist/commands/doctor.d.ts

@@ -22,4 +22,14 @@
  * apply pending sync.
  */
 import type { Command } from 'commander';
+/**
+ * Windows-only advisory lines. When the effective PowerShell execution policy
+ * blocks unsigned local `.ps1` scripts (`Restricted`/`AllSigned`), the generated
+ * `agents.ps1` launcher fails in PowerShell even when it is on PATH. Surface the
+ * remediation; the `.cmd` companion still works, so this is a warning, not an
+ * error, and doctor never auto-changes the policy. Pure — returns `[]` on
+ * non-Windows or a permissive policy, so it is testable without invoking
+ * PowerShell.
+ */
+export declare function execPolicyWarningLines(platform: NodeJS.Platform, policy: string | null): string[];
 export declare function registerDoctorCommand(program: Command): void;

package/dist/commands/doctor.js

@@ -1,3 +1,4 @@
+import { addHostOption } from '../lib/hosts/option.js';
 import chalk from 'chalk';
 import { checkAllClis } from '../lib/teams/agents.js';
 import { AGENTS, ALL_AGENT_IDS, resolveAgentName, formatAgentError } from '../lib/agents.js';
@@ -11,6 +12,7 @@ import { unifiedDiff, colorizeUnifiedDiff } from '../lib/diff-text.js';
 import { listCliStatus } from '../lib/cli-resources.js';
 import { setHelpSections } from '../lib/help.js';
 import { heal, healChangedAnything } from '../lib/heal.js';
+import { blocksLocalScripts, getEffectiveExecutionPolicy } from '../lib/platform/winpath.js';
 import * as fs from 'fs';
 const AGENT_NAMES = Object.fromEntries(ALL_AGENT_IDS.map((id) => [id, AGENTS[id].name]));
 // ─── overview mode (no target) ────────────────────────────────────────────────
@@ -207,6 +209,48 @@ function renderOverviewText(clis, syncRows, orphanRows, hostClis) {
     for (const err of hostClis.errors) {
         console.log(`  ${chalk.red('err  ')}  ${chalk.gray(err.file)}: ${chalk.gray(err.reason)}`);
     }
+    // On Windows a Restricted/AllSigned execution policy silently breaks the
+    // generated `agents.ps1` launcher — postinstall diagnoses it interactively,
+    // but a non-interactive install never sees that. Surface it here too.
+    renderExecPolicyAdvisory();
+}
+// ─── windows execution-policy advisory ─────────────────────────────────────────
+/**
+ * Windows-only advisory lines. When the effective PowerShell execution policy
+ * blocks unsigned local `.ps1` scripts (`Restricted`/`AllSigned`), the generated
+ * `agents.ps1` launcher fails in PowerShell even when it is on PATH. Surface the
+ * remediation; the `.cmd` companion still works, so this is a warning, not an
+ * error, and doctor never auto-changes the policy. Pure — returns `[]` on
+ * non-Windows or a permissive policy, so it is testable without invoking
+ * PowerShell.
+ */
+export function execPolicyWarningLines(platform, policy) {
+    if (platform !== 'win32')
+        return [];
+    if (!blocksLocalScripts(policy))
+        return [];
+    return [
+        `PowerShell execution policy is ${policy} — it blocks the generated agents.ps1 launcher.`,
+        'Fix: Set-ExecutionPolicy -Scope CurrentUser RemoteSigned',
+        'The agents.cmd shim still works regardless of the policy.',
+    ];
+}
+function renderExecPolicyAdvisory() {
+    // Only probe the policy on Windows — getEffectiveExecutionPolicy() spawns
+    // powershell, which is a wasted (doomed) process on POSIX where the advisory
+    // never applies.
+    if (process.platform !== 'win32')
+        return;
+    const lines = execPolicyWarningLines(process.platform, getEffectiveExecutionPolicy());
+    if (lines.length === 0)
+        return;
+    console.log();
+    console.log(chalk.bold('Execution policy (Windows)'));
+    const [headline, ...rest] = lines;
+    console.log(`  ${chalk.yellow('warn ')}  ${headline}`);
+    for (const line of rest) {
+        console.log(chalk.gray(`           ${line}`));
+    }
 }
 function parseTargetArg(arg) {
     const at = arg.indexOf('@');
@@ -475,8 +519,7 @@ async function runFix(parsed, opts) {
 }
 // ─── command registration ────────────────────────────────────────────────────
 export function registerDoctorCommand(program) {
-    const doctorCmd = program
-        .command('doctor [target]')
+    const doctorCmd = addHostOption(program.command('doctor [target]'))
         .description('Diagnose CLI availability, sync status, and resource divergence (optionally for a specific agent[@version]).')
         .option('--json', 'Output machine-readable JSON')
         .option('--diff', 'In target mode, include unified diffs for divergent files')
@@ -547,6 +590,12 @@ export function registerDoctorCommand(program) {
                 return;
             }
             renderOverviewText(clis, syncRows, orphanRows, hostClis);
+            // Point at the interactive reconcile when anything is out of sync — the
+            // report shouldn't be a dead end. `agents status` runs the unified
+            // home-reading engine and offers to sync (opt-in, never auto-fires here).
+            if (syncRows.some((r) => r.status !== 'fresh')) {
+                console.log(chalk.gray('\nRun `agents status` to review and sync what has drifted.'));
+            }
             return;
         }
         const parsed = parseTargetArg(target);

package/dist/commands/exec.js

@@ -136,7 +136,9 @@ export function registerRunCommand(program) {
         .option('--host <name>', 'Offload this run onto a registered agent host over SSH instead of running locally. See `agents hosts`.')
         .option('--remote-cwd <dir>', 'Working directory on the host for --host runs.')
         .option('--no-follow', 'With --host, dispatch detached and return immediately (track via `agents hosts ps/logs`).')
-        .option('--any', 'With --host <cap> (a capability tag), pick any matching host instead of erroring when several match.');
+        .option('--any', 'With --host <cap> (a capability tag), pick any matching host instead of erroring when several match.')
+        .option('--lease [backend]', 'Invent a disposable cloud box for this run and tear it down after (via crabbox). Optional backend selects the cloud (hetzner/aws/do). Unlike --host, no machine is registered.')
+        .option('--keep-box', 'With --lease, keep the box after the run instead of stopping it.');
     // `--on` and `--computer` are hidden aliases of `--host` — same behavior.
     runCmd.addOption(new Option('--on <name>', 'Alias of --host.').hideHelp());
     runCmd.addOption(new Option('--computer <name>', 'Alias of --host.').hideHelp());
@@ -191,6 +193,59 @@ export function registerRunCommand(program) {
         // Use command.args (all positional strings) and strip the declared positional args from the front.
         const declaredArgCount = prompt !== undefined ? 2 : 1;
         const passthroughArgs = command.args.slice(declaredArgCount);
+        // --lease: invent a disposable cloud box for this run (via crabbox), run
+        // the agent there, then tear it down. Unlike --host, nothing is registered.
+        if (options.lease) {
+            if (prompt === undefined) {
+                console.error(chalk.red('A prompt is required for leased runs: agents run <agent> "<task>" --lease'));
+                process.exit(1);
+            }
+            const backend = typeof options.lease === 'string' ? options.lease : undefined;
+            const { detectSignedInRuntimes, pickRuntimes } = await import('../lib/crabbox/runtimes.js');
+            const { leaseAndRun } = await import('../lib/crabbox/lease.js');
+            const { confirm } = await import('@inquirer/prompts');
+            const detected = await detectSignedInRuntimes();
+            const runtimes = await pickRuntimes(detected);
+            if (runtimes.length === 0) {
+                console.error(chalk.yellow('No runtimes selected. Sign into one locally (e.g. run `claude` once) then retry.'));
+                process.exit(1);
+            }
+            // Security gate: copying auth tokens to an ephemeral cloud box is opt-in
+            // per run. Name the runtimes + accounts so the user sees what ships.
+            const names = runtimes
+                .map((id) => {
+                const d = detected.find((x) => x.id === id);
+                return `${d?.label ?? id}${d?.email ? ` (${d.email})` : ''}`;
+            })
+                .join(', ');
+            const ok = await confirm({
+                message: `Copy credentials for ${names} to a disposable cloud box, run there, then destroy it?`,
+                default: false,
+            });
+            if (!ok) {
+                console.error(chalk.yellow('Aborted — no credentials pushed, no box leased.'));
+                process.exit(1);
+            }
+            try {
+                const { exitCode, box, toreDown } = await leaseAndRun({
+                    agent: agentSpec.split('@')[0],
+                    prompt,
+                    mode: options.mode,
+                    model: options.model,
+                    backend,
+                    runtimes,
+                    detected,
+                    secretsBundle: process.env.AGENTS_LEASE_SECRETS_BUNDLE,
+                    keep: options.keepBox,
+                });
+                console.error(chalk.gray(toreDown ? `Box ${box.slug} destroyed.` : `Box ${box.slug} kept${box.ip ? ` (${box.ip})` : ''}. Stop it: crabbox stop --id ${box.slug}`));
+                process.exit(exitCode === null ? 1 : exitCode);
+            }
+            catch (err) {
+                console.error(chalk.red(err.message));
+                process.exit(1);
+            }
+        }
         // --host/--on/--computer: offload this run onto a registered agent host
         // over SSH instead of running locally. The three flags are aliases.
         const hostGiven = [options.host, options.on, options.computer].filter((v) => !!v);

package/dist/commands/hooks.js

@@ -8,9 +8,9 @@ import { AGENTS, resolveAgentName, formatAgentError, agentLabel, } from '../lib/
 import { supports, capableAgents } from '../lib/capabilities.js';
 import { cloneRepo } from '../lib/git.js';
 import { discoverHooksFromRepo, installHooksCentrally, listCentralHooks, listInstalledHooksWithScope, getHookInfo, parseHookManifest, iterHooksCapableVersions, removeHookFromVersion, } from '../lib/hooks.js';
-import { listInstalledVersions, getGlobalDefault, resolveVersionAlias, syncResourcesToVersion, promptAgentVersionSelection, getVersionHomePath, resolveInstalledAgentTargets, } from '../lib/versions.js';
+import { listInstalledVersions, getGlobalDefault, syncResourcesToVersion, promptAgentVersionSelection, getVersionHomePath, resolveInstalledAgentTargets, } from '../lib/versions.js';
 import { recordVersionResources } from '../lib/state.js';
-import { isPromptCancelled, isInteractiveTerminal, parseCommaSeparatedList, printWithPager, requireInteractiveSelection, promptRemovalTargets, resolveAgentTargetsAutoInstalling, } from './utils.js';
+import { isPromptCancelled, isInteractiveTerminal, parseCommaSeparatedList, printWithPager, requireInteractiveSelection, promptRemovalTargets, resolveAgentTargetsAutoInstalling, resolveListFilterOrExit, } from './utils.js';
 /** Register the `agents hooks` command tree (list, add, remove, sync, prune, view). */
 export function registerHooksCommands(program) {
     const hooksCmd = program.command('hooks')
@@ -61,7 +61,7 @@ When to use:
                 console.log(chalk.red(formatAgentError(agentName, [...capableAgents('hooks')])));
                 process.exit(1);
             }
-            requestedVersion = resolveVersionAlias(agentId, parts[1]) ?? null;
+            requestedVersion = resolveListFilterOrExit(agentId, parts[1]) ?? null;
         }
         // Load hook manifest for event display
         const hookManifest = parseHookManifest();

package/dist/commands/import.js

@@ -263,7 +263,7 @@ When to use:
   pointing at the existing install — nothing is copied or moved (except the
   agent's config dir, which is moved into the version's home). Works for both
   npm-style packages (claude, codex, gemini, opencode, openclaw) and
-  installScript-based agents (grok, antigravity, cursor, kiro, goose, roo).
+  installScript-based agents (grok, antigravity, cursor, kiro, goose).
 `)
         .action(runImport);
 }

package/dist/commands/inspect.js

@@ -12,6 +12,7 @@
  * AGENT.md / the file itself) so users can click straight to the source.
  */
 import { execSync } from 'child_process';
+import { addHostOption } from '../lib/hosts/option.js';
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
@@ -19,6 +20,7 @@ import chalk from 'chalk';
 import * as yaml from 'yaml';
 import { AGENTS, getCliState, resolveAgentName } from '../lib/agents.js';
 import { supports } from '../lib/capabilities.js';
+import { resolveSingleAgentTarget, AgentSpecError } from '../lib/agent-spec/index.js';
 import { readMeta, getUserAgentsDir, getSystemAgentsDir, getProjectAgentsDir, getEnabledExtraRepos, } from '../lib/state.js';
 import { getVersionHomePath } from '../lib/versions.js';
 import { getShimsDir, getVersionedAliasPath } from '../lib/shims.js';
@@ -68,8 +70,7 @@ const CAPABILITY_NAMES = [
 ];
 // ─── Command registration ────────────────────────────────────────────────────
 export function registerInspectCommand(program) {
-    const cmd = program
-        .command('inspect <target>')
+    const cmd = addHostOption(program.command('inspect <target>'))
         .description('Inspect one installed agent at one version, or a DotAgents repo (user|system|project|alias|path) — paths, capabilities, resources, drill into any kind.')
         .option('--brief', 'header + capabilities only; skip resources/sessions')
         .option('--json', 'machine-readable JSON output');
@@ -125,25 +126,20 @@ export async function inspectAction(target, options) {
     await renderSummary(agent, version, versionHome, options);
 }
 function parseTarget(target) {
-    const [rawAgent, rawVersion] = target.split('@');
-    const agent = resolveAgentName(rawAgent || '');
-    if (!agent) {
-        console.error(chalk.red(`Unknown agent: ${rawAgent}`));
-        console.error(chalk.gray(`Known agents: ${Object.keys(AGENTS).join(', ')}`));
-        process.exit(1);
+    // Route through the agent-spec engine: bare resolves project pin → global
+    // default → sole installed (the meta-only lookup here previously ignored
+    // project pins); @default/@latest/@oldest/@x.y.z all handled uniformly.
+    try {
+        const { agent, version } = resolveSingleAgentTarget(target);
+        return { agent, version };
     }
-    let version = rawVersion;
-    if (!version || version === 'default') {
-        const meta = readMeta();
-        const def = meta.agents?.[agent];
-        if (!def) {
-            console.error(chalk.red(`No default version set for ${agent}.`));
-            console.error(chalk.gray(`Pass a version: agents inspect ${agent}@<version>`));
+    catch (e) {
+        if (e instanceof AgentSpecError) {
+            console.error(chalk.red(e.message));
             process.exit(1);
         }
-        version = def;
+        throw e;
     }
-    return { agent, version };
 }
 function pickDrillKind(options) {
     const active = [];

package/dist/commands/mcp.js

@@ -7,9 +7,9 @@ import { readManifest, writeManifest, createDefaultManifest } from '../lib/manif
 import { listMcpServerConfigs, discoverMcpConfigsFromRepo, installMcpConfigCentrally, } from '../lib/mcp.js';
 import { cloneRepo } from '../lib/git.js';
 import { getMcpDir } from '../lib/state.js';
-import { getEffectiveHome, getGlobalDefault, listInstalledVersions, getVersionHomePath, resolveInstalledAgentTargets, resolveConfiguredAgentTargets, resolveVersionAlias, syncResourcesToVersion, } from '../lib/versions.js';
+import { getEffectiveHome, getGlobalDefault, listInstalledVersions, getVersionHomePath, resolveInstalledAgentTargets, resolveConfiguredAgentTargets, syncResourcesToVersion, } from '../lib/versions.js';
 import { getUserAgentsDir } from '../lib/state.js';
-import { isPromptCancelled, isInteractiveTerminal, requireInteractiveSelection, promptRemovalTargets, parseCommaSeparatedList, ensureAgentVersionsInstalled, resolveAgentTargetsAutoInstalling, resolveInstalledAgentTargetsAutoInstalling, VersionNotInstalledError, } from './utils.js';
+import { isPromptCancelled, isInteractiveTerminal, requireInteractiveSelection, promptRemovalTargets, parseCommaSeparatedList, ensureAgentVersionsInstalled, resolveAgentTargetsAutoInstalling, resolveInstalledAgentTargetsAutoInstalling, VersionNotInstalledError, resolveListFilterOrExit, } from './utils.js';
 import { showResourceList, buildTargetsSection, } from './resource-view.js';
 /**
  * Parse a comma-separated --agents string into validated agent IDs and
@@ -159,7 +159,7 @@ When to use:
                 process.exit(1);
             }
             filterAgent = resolved;
-            filterVersion = resolveVersionAlias(resolved, parts[1]);
+            filterVersion = resolveListFilterOrExit(resolved, parts[1]);
         }
         const rows = buildMcpRows({ filterAgent, filterVersion });
         spinner.stop();

package/dist/commands/permissions.js

@@ -8,9 +8,9 @@ import { AGENTS, resolveAgentName, formatAgentError, agentLabel, } from '../lib/
 import { cloneRepo } from '../lib/git.js';
 import { capableAgents, isCapable } from '../lib/capabilities.js';
 import { listInstalledPermissions, discoverPermissionsFromRepo, installPermissionSet, removePermissionSet, applyPermissionsToVersion, readAgentPermissions, exportPermissionsFromPath, getDefaultPermissionSet, computePermissionsDiff, mergePermissionSets, saveDefaultPermissionSet, containsBroadGrants, } from '../lib/permissions.js';
-import { listInstalledVersions, getGlobalDefault, getVersionHomePath, promptAgentVersionSelection, resolveVersionAlias, } from '../lib/versions.js';
+import { listInstalledVersions, getGlobalDefault, getVersionHomePath, promptAgentVersionSelection, } from '../lib/versions.js';
 import { recordVersionResources } from '../lib/state.js';
-import { isPromptCancelled, isInteractiveTerminal, parseCommaSeparatedList, printWithPager, requireInteractiveSelection, resolveAgentTargetsAutoInstalling, } from './utils.js';
+import { isPromptCancelled, isInteractiveTerminal, parseCommaSeparatedList, printWithPager, requireInteractiveSelection, resolveAgentTargetsAutoInstalling, resolveListFilterOrExit, } from './utils.js';
 export function shouldRefuseBroadPermissions(permissions, allowBroadPermissions) {
     return !allowBroadPermissions && permissions.some((perm) => containsBroadGrants(perm.set) !== null);
 }
@@ -116,7 +116,7 @@ When to use:
                 console.log(chalk.red(formatAgentError(agentName, capableAgents('allowlist'))));
                 process.exit(1);
             }
-            const requestedVersion = resolveVersionAlias(agentId, parts[1]) ?? null;
+            const requestedVersion = resolveListFilterOrExit(agentId, parts[1]) ?? null;
             if (!isCapable(agentId, 'allowlist')) {
                 console.log(chalk.yellow(`${AGENTS[agentId].name} does not support fine-grained permissions`));
                 return;

package/dist/commands/rules.js

@@ -11,7 +11,7 @@ import { listInstalledVersions, getGlobalDefault, resolveVersionAlias, syncResou
 import { recordVersionResources, getActiveRulesPreset, setActiveRulesPreset } from '../lib/state.js';
 import { discoverRulesLayers } from '../lib/rules/compose.js';
 import * as yaml from 'yaml';
-import { isPromptCancelled, formatPath, isInteractiveTerminal, parseCommaSeparatedList, printWithPager, requireInteractiveSelection, requireDestructiveArg, resolveAgentTargetsAutoInstalling, } from './utils.js';
+import { isPromptCancelled, formatPath, isInteractiveTerminal, parseCommaSeparatedList, printWithPager, requireInteractiveSelection, requireDestructiveArg, resolveAgentTargetsAutoInstalling, resolveListFilterOrExit, } from './utils.js';
 /** Register the `agents rules` command tree (list, add, view, remove). */
 export function registerRulesCommands(program) {
     const rulesCmd = program
@@ -51,7 +51,7 @@ Project rules & @-imports:
   @path imports inside AGENTS.md/CLAUDE.md are resolved at session start by the agent
   itself, not by agents-cli. Support is per-agent:
     Inlined natively:  claude, gemini
-    Literal text:      codex, cursor, opencode, copilot, amp, kiro, goose, roo
+    Literal text:      codex, cursor, opencode, copilot, amp, kiro, goose
 
   For rules that need to work across all agents, inline the content rather than using
   @-imports — the second group will load '@path/to/file.md' as a literal string.
@@ -73,7 +73,7 @@ Project rules & @-imports:
                 console.log(chalk.red(formatAgentError(agentName)));
                 process.exit(1);
             }
-            requestedVersion = resolveVersionAlias(agentId, parts[1]) ?? null;
+            requestedVersion = resolveListFilterOrExit(agentId, parts[1]) ?? null;
         }
         const renderVersionRules = (agentId, version, isDefault, home) => {
             const agent = AGENTS[agentId];