@phnx-labs/agents-cli 1.20.31 → 1.20.33

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 ## Unreleased
 
+## 1.20.31
+
+**`agents sessions <id>`: a catch-up digest for switching between many agents (#502)**
+
+- Opening a single session now leads with its auto-inferred title (user `/rename` > Claude `ai-title` > first-prompt topic) and PR / worktree / ticket badges, then a **Changes** section that groups touched files by directory and tags each as created / modified / deleted (with a `+N ~N -N` summary) instead of the old flat "Modified" list, a **Tools** histogram (per-tool call counts), and a **Tests** verdict parsed from the last `vitest` / `jest` / `pytest` / `go test` / `cargo test` / `tsc` run. The same signals are folded into the interactive picker preview.
+- `agents sessions --active` now collapses the many subagent/fork PIDs of one session into a single row with a `×N` count instead of printing dozens of identical lines. Source: `src/lib/session/digest.ts`, `src/lib/session/render.ts`, `src/lib/session/active.ts`, `src/commands/sessions.ts`, `src/commands/sessions-picker.ts`.
+
+## 1.20.30
+
+**`agents sessions` live state engine: waiting / PR / worktree / ticket detection + reliable preview (#494)**
+
+- `agents sessions --active` infers real activity from each transcript's tail — **working** / **waiting** / **idle** — rather than the old mtime-only running/idle guess, using structural signals (Claude `ExitPlanMode` / `AskUserQuestion`) plus a question + mtime heuristic for Codex. It detects and badges a PR opened during the session (`gh pr create` + the resulting pull URL), a git worktree (`.agents/worktrees/<slug>/`), and a Linear/Jira ticket (from the prompt or branch), and shows the latest turn as the preview instead of the first prompt.
+- `--waiting` filters `--active` to only sessions blocked on your input and exits non-zero (a scriptable gate); `--tree` groups the listing by directory, dropping the id/version columns while keeping the short-id handle.
+- The preview line is now width-correct: measurement is ANSI- and wide-char-aware and reads `$COLUMNS` first, so it no longer wraps or drifts under tmux or over `--host` SSH (the remote is handed the caller's width). Session index schema v7 persists the PR / worktree / ticket signals so historical listings carry them too. Source: `src/lib/session/state.ts`, `src/lib/session/tail.ts`, `src/lib/session/width.ts`, `src/lib/session/{discover,db,active}.ts`, `src/commands/sessions.ts`.
+
 **`agents sessions --host <machine>`: query a remote machine's sessions live over SSH**
 
 - `agents sessions "<query>" --host <alias|user@host>` runs the same session query on a remote machine's own index over SSH and streams the result back — repeat `--host` (or pass several) to fan out across machines. SSH access is the only auth; there's no daemon or shared store. Targets are validated against a strict allowlist (`SSH_TARGET_RE`) to block flag-smuggling, and the forwarded invocation is double-quoted (`shellQuote`) so a query like `$(whoami)` survives as a literal string on both shell layers. Source: `src/lib/session/remote.ts`, `src/commands/sessions.ts`, `docs/05-sessions.md`.

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/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.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';
@@ -475,8 +476,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')

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/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
@@ -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];

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

@@ -20,6 +20,7 @@ import { machineId } from '../lib/session/sync/config.js';
 import { addIgnored, getDevice, loadDevices, loadIgnored, removeDevice, removeIgnored, upsertDevice, } from '../lib/devices/registry.js';
 import { nodeToDeviceInput, parseTailscaleStatus, tailscaleStatusJson, } from '../lib/devices/tailscale.js';
 import { planDeviceReconciliation, runDeviceSync } from '../lib/devices/sync.js';
+import { clearPendingSentinel } from '../lib/devices/pending.js';
 import { isInteractiveTerminal, isPromptCancelled } from './utils.js';
 import { hostNameFor, renderSshConfig } from '../lib/devices/ssh-config.js';
 import { ASKPASS_BUNDLE_ENV, ASKPASS_KEY_ENV, buildSshInvocation, writeAskpassShim, } from '../lib/devices/connect.js';
@@ -154,6 +155,27 @@ Typical workflow:
             process.exit(1);
         }
     });
+    devicesCmd
+        .command('register <name>')
+        .description('Register a discovered (pending) node by name — used by the menu-bar "NEW DEVICES → Register" action.')
+        .action(async (name) => {
+        try {
+            const nodes = parseTailscaleStatus(tailscaleStatusJson());
+            const node = nodes.find((n) => n.name === name);
+            if (!node) {
+                console.error(chalk.red(`'${name}' is not a current tailscale node. See 'agents devices sync'.`));
+                process.exit(1);
+            }
+            await removeIgnored(name); // a re-registered node is no longer dismissed
+            const d = await upsertDevice(name, nodeToDeviceInput(node));
+            clearPendingSentinel(name); // drop the notification immediately
+            console.log(chalk.green(`Registered '${name}'`) + chalk.gray(` (${d.platform})`));
+        }
+        catch (err) {
+            console.error(chalk.red(err.message));
+            process.exit(1);
+        }
+    });
     devicesCmd
         .command('ignore <name>')
         .description('Dismiss a node from auto-discovery so it is never re-suggested (and remove it from the registry if present).')
@@ -161,6 +183,7 @@ Typical workflow:
         try {
             await removeDevice(name);
             await addIgnored(name);
+            clearPendingSentinel(name); // drop the notification immediately
             console.log(chalk.green(`Ignored '${name}'`) + chalk.gray(" — it won't be suggested again. Undo with `agents devices unignore`."));
         }
         catch (err) {

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,5 +1,6 @@
 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 { resolveProvider } from '../lib/cloud/registry.js';
@@ -673,8 +674,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 +785,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 +824,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.')
@@ -1041,8 +1039,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,8 +1133,7 @@ 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.')
@@ -1190,8 +1186,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) => {

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,3 +1,4 @@
+import { addHostOption } from '../lib/hosts/option.js';
 import chalk from 'chalk';
 import ora from 'ora';
 import * as fs from 'fs';
@@ -762,8 +763,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'));