@phnx-labs/agents-cli 1.20.26 → 1.20.28

package/dist/lib/session/remote.js

@@ -0,0 +1,221 @@
+/**
+ * `agents sessions --host <target>` — run the session query on a remote machine
+ * over SSH and stream its output back. Session transcripts and the index DB live
+ * on the machine that produced them (see `discover.ts`, all `os.homedir()`-rooted),
+ * so instead of syncing the bytes here we invoke the *remote's own* `agents
+ * sessions` against its already-built index and forward stdout verbatim.
+ *
+ * This is the live counterpart to `agents sessions sync` (R2/CRDT, eventual): no
+ * upfront copy, always current, but the peer must be reachable. SSH access is the
+ * only auth — if you can `ssh <host>`, you own the box (no identity layer by design).
+ *
+ * Offline degradation (no sync, still fetch-first): every *successful* fetch is
+ * cached to `~/.agents/.cache/remote-sessions/`, keyed by host + the exact query.
+ * When a later run finds the host unreachable, the cache is replayed with a clearly
+ * labelled "showing cached results" banner instead of returning nothing. The cache
+ * is a byproduct of fetches you already made — never a background job, freely
+ * deletable — so the fetch-don't-replicate model holds; this is just graceful
+ * degradation when the peer is asleep.
+ *
+ * Mirrors the transport already used by `agents secrets export --host`
+ * (`src/commands/secrets.ts`): `ssh -o BatchMode=yes <host> bash -lc '<cmd>'`,
+ * with `bash -lc` so the remote login PATH resolves `agents`.
+ */
+import { spawnSync } from 'child_process';
+import { mkdirSync, writeFileSync, readFileSync, existsSync, statSync } from 'fs';
+import { join } from 'path';
+import { createHash } from 'crypto';
+import chalk from 'chalk';
+import { getCacheDir } from '../state.js';
+import { formatRelativeTime } from './relative-time.js';
+/**
+ * SSH target: a bare ssh-config host alias (e.g. `yosemite-s1`) or `user@host`.
+ * The strict allowlist blocks shell metacharacters and a leading `-`, so a target
+ * can never be smuggled in as an ssh argv flag.
+ */
+export const SSH_TARGET_RE = /^[a-zA-Z0-9._-]+(@[a-zA-Z0-9._-]+)?$/;
+export function assertValidSshTarget(host) {
+    if (!SSH_TARGET_RE.test(host)) {
+        throw new Error(`Invalid SSH target ${JSON.stringify(host)}. Expected a host alias or user@host ` +
+            `(letters, digits, '.', '_', '-').`);
+    }
+}
+/** POSIX single-quote a string for safe interpolation into a remote shell command. */
+export function shellQuote(s) {
+    return `'${s.replace(/'/g, `'\\''`)}'`;
+}
+/**
+ * Strip the `--host`/`-H` flag (and its value) from a raw `agents sessions` argv,
+ * leaving the args to forward to the remote unchanged. The remote runs the same
+ * binary, so every other flag (`--since`, `--last`, `--json`, query, …) carries
+ * over for free. Handles every form commander accepts: `--host h`, `--host=h`,
+ * `-H h`, `-H=h`, and the glued short form `-Hh`.
+ *
+ * @param argv full process argv; the sessions args begin at index 2
+ *             (`[runtime, script, 'sessions', ...]`).
+ */
+export function buildForwardedArgs(argv, hosts = new Set()) {
+    const args = argv.slice(2);
+    const out = [];
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (a === '--host' || a === '-H') {
+            // Commander's `<target...>` variadic accepts both `--host a --host b` and
+            // `--host a b` — consume every consecutive token that is a known host so
+            // the variadic form doesn't leak the extra hosts into the remote argv.
+            // Fall back to consuming the single next token when we have no host set
+            // (e.g. malformed input) so the flag value never leaks either way.
+            if (hosts.size > 0) {
+                while (i + 1 < args.length && hosts.has(args[i + 1]))
+                    i++;
+            }
+            else {
+                i++; // also consume the separate value token
+            }
+            continue;
+        }
+        if (a.startsWith('--host=') || a.startsWith('-H='))
+            continue;
+        if (/^-H.+/.test(a))
+            continue; // glued short form: -Hyosemite-s1
+        out.push(a);
+    }
+    return out;
+}
+/**
+ * Build the single remote command string for `ssh <host> <cmd>`. Forwarded args
+ * are quoted for the inner login shell, then the whole `agents …` invocation is
+ * quoted again so it survives `bash -lc <...>`.
+ */
+export function buildRemoteCommand(forwardedArgs) {
+    const inner = ['agents', ...forwardedArgs].map(shellQuote).join(' ');
+    return `bash -lc ${shellQuote(inner)}`;
+}
+const SSH_OPTS = [
+    '-o', 'BatchMode=yes',
+    '-o', 'StrictHostKeyChecking=accept-new',
+    '-o', 'ConnectTimeout=10',
+];
+/**
+ * Classify an ssh `spawnSync` result. ssh(1) reserves exit 255 for its own
+ * connection-layer failures (host down, timeout, refused, auth, changed host
+ * key) — distinct from any other non-zero, which is the remote `agents sessions`
+ * exit code forwarded back (the query ran but failed). The two must be handled
+ * differently: 255 may fall back to cache, a forwarded failure must surface.
+ */
+export function classifySshFailure(res) {
+    if (res.error)
+        return 'spawn-error';
+    if (res.status === 0)
+        return 'ok';
+    if (res.status === 255)
+        return 'unreachable';
+    return 'query-failed';
+}
+/** Root of the offline-replay cache (`~/.agents/.cache/remote-sessions/`). */
+const REMOTE_CACHE_DIR = join(getCacheDir(), 'remote-sessions');
+/**
+ * Deterministic cache path for a (host, forwarded-args) pair. The forwarded args
+ * are hashed so distinct queries cache independently; the host stays readable in
+ * the filename (sanitised so `user@host` and aliases are filesystem-safe).
+ */
+export function remoteCachePath(host, forwardedArgs) {
+    const hash = createHash('sha256').update(forwardedArgs.join('\u0000')).digest('hex').slice(0, 16);
+    const safeHost = host.replace(/[^a-zA-Z0-9._@-]/g, '_');
+    return join(REMOTE_CACHE_DIR, `${safeHost}__${hash}.txt`);
+}
+/** Banner shown above replayed cache rows when the peer is offline. */
+export function formatStaleBanner(host, mtimeMs) {
+    const ago = formatRelativeTime(new Date(mtimeMs).toISOString());
+    return chalk.yellow(`${host}: offline — showing cached results from ${ago}`);
+}
+/** Message shown when a host is unreachable and there is no cache to fall back to. */
+export function formatUnreachable(host) {
+    return chalk.red(`${host}: unreachable over SSH (asleep, offline, or host key changed?) — ConnectTimeout 10s`);
+}
+/** Persist a successful fetch for later offline replay. Best-effort: a cache
+ * write must never break the live query. */
+function writeRemoteCache(host, forwardedArgs, output) {
+    try {
+        mkdirSync(REMOTE_CACHE_DIR, { recursive: true });
+        writeFileSync(remoteCachePath(host, forwardedArgs), output);
+    }
+    catch {
+        // ignore — caching is an optimisation, not a guarantee
+    }
+}
+/** Replay a cached fetch for an unreachable host. Banner goes to stderr (so a
+ * piped stdout stays exactly the cached rows); returns false when nothing is
+ * cached for this exact (host, query). */
+function replayRemoteCache(host, forwardedArgs) {
+    try {
+        const p = remoteCachePath(host, forwardedArgs);
+        if (!existsSync(p))
+            return false;
+        process.stderr.write(formatStaleBanner(host, statSync(p).mtimeMs) + '\n');
+        process.stdout.write(readFileSync(p, 'utf8'));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Run the current `agents sessions` invocation on one or more remote machines over
+ * SSH, writing each remote's output to the terminal. A successful fetch is cached;
+ * an unreachable host falls back to that cache (with a stale banner) when present.
+ * Sets `process.exitCode = 1` if any host could not be answered (live or cached).
+ * Reads the invocation from `process.argv` (override via `argv` for testing).
+ *
+ * Output is captured rather than `stdio: 'inherit'`-streamed so it can be cached.
+ * Session output is small and the remote returns quickly, so buffering is
+ * imperceptible; `maxBuffer` is generous for the rare large `--markdown <id>` dump.
+ */
+export function runRemoteSessions(hosts, argv = process.argv) {
+    for (const host of hosts)
+        assertValidSshTarget(host); // fail fast on any bad target
+    const forwarded = buildForwardedArgs(argv, new Set(hosts));
+    const remoteCmd = buildRemoteCommand(forwarded);
+    const multi = hosts.length > 1;
+    let failures = 0;
+    for (const host of hosts) {
+        if (multi)
+            process.stdout.write(chalk.cyan(`\n── ${host} ──\n`));
+        const res = spawnSync('ssh', [...SSH_OPTS, host, remoteCmd], {
+            encoding: 'utf8',
+            maxBuffer: 64 * 1024 * 1024,
+        });
+        switch (classifySshFailure(res)) {
+            case 'ok':
+                process.stdout.write(res.stdout ?? '');
+                if (res.stderr)
+                    process.stderr.write(res.stderr);
+                writeRemoteCache(host, forwarded, res.stdout ?? '');
+                break;
+            case 'unreachable':
+                // Served-from-cache counts as answered (degraded, but with data + a clear
+                // banner), so it does not increment failures. No cache → a real failure.
+                if (!replayRemoteCache(host, forwarded)) {
+                    failures++;
+                    console.error(formatUnreachable(host));
+                }
+                break;
+            case 'spawn-error':
+                failures++;
+                console.error(chalk.red(`${host}: ${res.error?.message ?? 'failed to launch ssh'}`));
+                break;
+            case 'query-failed':
+                // The remote ran but its query exited non-zero — surface its own output
+                // and exit code; never mask a genuine error with stale cache.
+                failures++;
+                if (res.stdout)
+                    process.stdout.write(res.stdout);
+                if (res.stderr)
+                    process.stderr.write(res.stderr);
+                console.error(chalk.red(`${host}: remote query failed (exit ${res.status ?? 'signal'}).`));
+                break;
+        }
+    }
+    if (failures > 0)
+        process.exitCode = 1;
+}

package/dist/lib/ssh-exec.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Shared SSH exec primitive — the single hardened choke point for running a
+ * command on a remote host over the system `ssh`.
+ *
+ * `agents hosts` dispatch and the browser driver both go through here so the
+ * connection hardening (`BatchMode`, `accept-new`, `ConnectTimeout`) and the
+ * target-injection guard live in exactly one place. Target validation is the
+ * canonical definition; `commands/secrets.ts` re-exports it.
+ */
+/**
+ * SSH target: a bare ssh-config host alias (e.g. `yosemite-s0`) or `user@host`.
+ * The strict allowlist blocks shell metacharacters so a target can't be
+ * smuggled in as part of a remote command, and `sshExec` additionally rejects a
+ * leading `-` so it can never be parsed as an ssh argv flag.
+ */
+export declare const SSH_TARGET_RE: RegExp;
+export declare function assertValidSshTarget(host: string): void;
+/** POSIX single-quote a string for safe interpolation into a remote shell command. */
+export declare function shellQuote(s: string): string;
+/** Hardened ssh options applied to every connection. */
+export declare const SSH_OPTS: readonly string[];
+export interface SshExecOptions {
+    /** Piped to the remote command's stdin (never interpolated into the shell). */
+    input?: string;
+    /** Kill the ssh process after this many ms. */
+    timeoutMs?: number;
+    /** Extra ssh flags inserted before the target (e.g. `-tt`). */
+    extraSshArgs?: string[];
+}
+export interface SshExecResult {
+    /** Remote exit status, or null if ssh itself failed / timed out. */
+    code: number | null;
+    stdout: string;
+    stderr: string;
+    timedOut: boolean;
+}
+/**
+ * Run `remoteCmd` on `target` over ssh and capture stdout/stderr/exit.
+ *
+ * `remoteCmd` is passed as a single argv to ssh (the remote login shell parses
+ * it); callers that build it from user input must `shellQuote` the pieces.
+ */
+export declare function sshExec(target: string, remoteCmd: string, opts?: SshExecOptions): SshExecResult;
+/** True if `target` is reachable over ssh (a passwordless `true` succeeds quickly). */
+export declare function sshReachable(target: string, timeoutMs?: number): boolean;

package/dist/lib/ssh-exec.js

@@ -0,0 +1,61 @@
+/**
+ * Shared SSH exec primitive — the single hardened choke point for running a
+ * command on a remote host over the system `ssh`.
+ *
+ * `agents hosts` dispatch and the browser driver both go through here so the
+ * connection hardening (`BatchMode`, `accept-new`, `ConnectTimeout`) and the
+ * target-injection guard live in exactly one place. Target validation is the
+ * canonical definition; `commands/secrets.ts` re-exports it.
+ */
+import { spawnSync } from 'child_process';
+/**
+ * SSH target: a bare ssh-config host alias (e.g. `yosemite-s0`) or `user@host`.
+ * The strict allowlist blocks shell metacharacters so a target can't be
+ * smuggled in as part of a remote command, and `sshExec` additionally rejects a
+ * leading `-` so it can never be parsed as an ssh argv flag.
+ */
+export const SSH_TARGET_RE = /^[a-zA-Z0-9._-]+(@[a-zA-Z0-9._-]+)?$/;
+export function assertValidSshTarget(host) {
+    if (host.startsWith('-') || !SSH_TARGET_RE.test(host)) {
+        throw new Error(`Invalid SSH target ${JSON.stringify(host)}. Expected a host alias or user@host (letters, digits, '.', '_', '-').`);
+    }
+}
+/** POSIX single-quote a string for safe interpolation into a remote shell command. */
+export function shellQuote(s) {
+    if (/^[A-Za-z0-9_./:=@%+-]+$/.test(s))
+        return s;
+    return "'" + s.replace(/'/g, "'\\''") + "'";
+}
+/** Hardened ssh options applied to every connection. */
+export const SSH_OPTS = [
+    '-o', 'StrictHostKeyChecking=accept-new',
+    '-o', 'BatchMode=yes',
+    '-o', 'ConnectTimeout=10',
+];
+/**
+ * Run `remoteCmd` on `target` over ssh and capture stdout/stderr/exit.
+ *
+ * `remoteCmd` is passed as a single argv to ssh (the remote login shell parses
+ * it); callers that build it from user input must `shellQuote` the pieces.
+ */
+export function sshExec(target, remoteCmd, opts = {}) {
+    assertValidSshTarget(target);
+    const args = [...SSH_OPTS, ...(opts.extraSshArgs ?? []), target, remoteCmd];
+    const res = spawnSync('ssh', args, {
+        input: opts.input,
+        encoding: 'utf-8',
+        timeout: opts.timeoutMs,
+        stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    const timedOut = !!(res.error && res.error.code === 'ETIMEDOUT');
+    return {
+        code: typeof res.status === 'number' ? res.status : null,
+        stdout: res.stdout ?? '',
+        stderr: res.stderr ?? '',
+        timedOut,
+    };
+}
+/** True if `target` is reachable over ssh (a passwordless `true` succeeds quickly). */
+export function sshReachable(target, timeoutMs = 10000) {
+    return sshExec(target, 'true', { timeoutMs }).code === 0;
+}

package/dist/lib/staleness/detectors/commands.js

@@ -1,8 +1,8 @@
 /**
  * Commands detector — mirrors versions.ts:343-357. Inspects the version home,
- * returns command names. Honors the commands-as-skills marker for grok and
- * Codex >= 0.117.0; falls back to scanning `{agentDir}/<commandsSubdir>/` for
- * the native path.
+ * returns command names. Honors the commands-as-skills marker for skills-only
+ * agents (grok, kimi, Codex >= 0.117.0, …); falls back to scanning
+ * `{agentDir}/<commandsSubdir>/` for the native path.
  */
 import * as fs from 'fs';
 import * as path from 'path';
@@ -29,13 +29,14 @@ function buildCommandsDetector(agent) {
         },
     };
 }
-// Detector registration mirrors writers/commands.ts — see that file for the
-// openclaw vs grok asymmetry.
+// Detector registration mirrors writers/commands.ts — skills-capable agents
+// with no native command-file dir convert commands to skills by default; only
+// agents with their own slash-command runtime (nativeCommandRuntime) opt out.
 export const commandsDetectors = lazyAgentMap(() => {
     const m = {};
     for (const id of Object.keys(AGENTS)) {
         const cfg = AGENTS[id];
-        if (cfg.capabilities.commands === false && (!cfg.commandsSubdir || cfg.commandsSubdir === '') && id !== 'grok')
+        if (cfg.capabilities.commands === false && (!cfg.commandsSubdir || cfg.commandsSubdir === '') && cfg.nativeCommandRuntime)
             continue;
         const hasCommands = cfg.capabilities.commands !== false;
         const hasSkills = cfg.capabilities.skills !== false;

package/dist/lib/staleness/writers/commands.js

@@ -80,25 +80,20 @@ function buildCommandsWriter(agent) {
 //   - commands-as-skills (grok, codex >= 0.117.0)
 //
 // Agents that have skills but use a NATIVE non-file slash-command system
-// (openclaw → Gateway-based commands) are NOT registered. The signal is an
-// empty `commandsSubdir`: there's no directory to write to AND the agent
-// doesn't want commands-as-skills either (it has its own runtime command
-// resolver).
+// (openclaw → Gateway-based commands) are NOT registered. They declare
+// `nativeCommandRuntime: true` to opt out — their own runtime resolves slash
+// commands, so there's nothing to write and nothing to convert.
 export const commandsWriters = lazyAgentMap(() => {
     const m = {};
     for (const id of Object.keys(AGENTS)) {
         const cfg = AGENTS[id];
         if (cfg.capabilities.commands === false && (!cfg.skillsDir || cfg.skillsDir === ''))
             continue;
-        // Native non-file slash-command runtime — no version-home write.
+        // Skills-capable agent with no native command-file dir: convert commands to
+        // skills by default (grok, kimi, …). Opt out only agents with their own
+        // slash-command runtime (openclaw).
         if (cfg.capabilities.commands === false && (!cfg.commandsSubdir || cfg.commandsSubdir === '')) {
-            // Grok has empty commandsSubdir AND wants commands-as-skills.
-            // Distinguish: grok has skillsDir set; openclaw also has skillsDir, so we
-            // can't use that. The cleanest signal is the agent's `cliCommand` set —
-            // openclaw flags `commands: false` AND has its Gateway runtime, while
-            // grok flags `commands: false` because grok's slash commands are skills.
-            // We opt in explicitly: only grok takes commands-as-skills today.
-            if (id !== 'grok')
+            if (cfg.nativeCommandRuntime)
                 continue;
         }
         const hasCommands = cfg.capabilities.commands !== false;

package/dist/lib/startup/command-registry.d.ts

@@ -67,6 +67,7 @@ export declare const loadPty: ModuleLoader;
 export declare const loadTmux: ModuleLoader;
 export declare const loadBrowser: ModuleLoader;
 export declare const loadComputer: ModuleLoader;
+export declare const loadHosts: ModuleLoader;
 export declare const loadPull: ModuleLoader;
 export declare const loadPush: ModuleLoader;
 export declare const loadRepo: ModuleLoader;

package/dist/lib/startup/command-registry.js

@@ -45,6 +45,7 @@ export const loadPty = async () => (await import('../../commands/pty.js')).regis
 export const loadTmux = async () => (await import('../../commands/tmux.js')).registerTmuxCommands;
 export const loadBrowser = async () => (await import('../../commands/browser.js')).registerBrowserCommand;
 export const loadComputer = async () => (await import('../../commands/computer.js')).registerComputerCommand;
+export const loadHosts = async () => (await import('../../commands/hosts.js')).registerHostsCommand;
 export const loadPull = async () => (await import('../../commands/pull.js')).registerPullCommand;
 export const loadPush = async () => (await import('../../commands/push.js')).registerPushCommand;
 export const loadRepo = async () => (await import('../../commands/repo.js')).registerRepoCommands;
@@ -126,6 +127,7 @@ export const COMMAND_LOADERS = {
     tmux: [loadTmux],
     browser: [loadBrowser],
     computer: [loadComputer],
+    hosts: [loadHosts],
     pull: [loadPull],
     push: [loadPush],
     repo: [loadRepo],

package/dist/lib/startup/dev-build.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Decide whether the CLI is running from a source checkout (a "dev build") vs an
+ * installed package. Dev builds suppress autopull / migrations / auto-update so
+ * iterating on the repo never mutates the user's real setup.
+ *
+ * Two signals:
+ *   1. A `0.0.0-dev*` version stamp (scripts/install.sh dev installs).
+ *   2. Running out of an actual agents-cli git checkout.
+ *
+ * Signal 2 must be precise. The naive check —
+ * `existsSync(dirname(dirname(argv[1])) + '/.git')` — false-positives badly:
+ *   - npm-global bins are symlinks. `/opt/homebrew/bin/agents` →
+ *     `…/node_modules/@phnx-labs/agents-cli/dist/index.js`. Without resolving the
+ *     symlink, `dirname(dirname())` walks to `/opt/homebrew`, which is **itself a
+ *     git repo** (Homebrew). So every Homebrew-node user looked like a dev build
+ *     and had migrations + the menu-bar self-heal silently disabled.
+ *
+ * Fix: resolve the symlink with realpath, then require the `.git`'s repo root to
+ * actually be the agents-cli package (its package.json `name`), not some
+ * unrelated ancestor that happens to be version-controlled.
+ */
+export declare function detectDevBuild(argv1: string, version: string): boolean;

package/dist/lib/startup/dev-build.js

@@ -0,0 +1,41 @@
+import * as fs from 'fs';
+import * as path from 'path';
+/**
+ * Decide whether the CLI is running from a source checkout (a "dev build") vs an
+ * installed package. Dev builds suppress autopull / migrations / auto-update so
+ * iterating on the repo never mutates the user's real setup.
+ *
+ * Two signals:
+ *   1. A `0.0.0-dev*` version stamp (scripts/install.sh dev installs).
+ *   2. Running out of an actual agents-cli git checkout.
+ *
+ * Signal 2 must be precise. The naive check —
+ * `existsSync(dirname(dirname(argv[1])) + '/.git')` — false-positives badly:
+ *   - npm-global bins are symlinks. `/opt/homebrew/bin/agents` →
+ *     `…/node_modules/@phnx-labs/agents-cli/dist/index.js`. Without resolving the
+ *     symlink, `dirname(dirname())` walks to `/opt/homebrew`, which is **itself a
+ *     git repo** (Homebrew). So every Homebrew-node user looked like a dev build
+ *     and had migrations + the menu-bar self-heal silently disabled.
+ *
+ * Fix: resolve the symlink with realpath, then require the `.git`'s repo root to
+ * actually be the agents-cli package (its package.json `name`), not some
+ * unrelated ancestor that happens to be version-controlled.
+ */
+export function detectDevBuild(argv1, version) {
+    if (version.startsWith('0.0.0-dev'))
+        return true;
+    try {
+        const cliPath = fs.realpathSync(argv1 || '');
+        const repoRoot = path.dirname(path.dirname(cliPath));
+        if (!fs.existsSync(path.join(repoRoot, '.git')))
+            return false;
+        const pkgPath = path.join(repoRoot, 'package.json');
+        if (!fs.existsSync(pkgPath))
+            return false;
+        const name = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'))?.name;
+        return name === '@phnx-labs/agents-cli';
+    }
+    catch {
+        return false;
+    }
+}

package/dist/lib/types.d.ts

@@ -77,6 +77,13 @@ export interface AgentConfig {
     commandsDir: string;
     commandsSubdir: string;
     skillsDir: string;
+    /**
+     * Agent resolves slash-commands through its own runtime (e.g. openclaw's
+     * Gateway), so agents-cli commands must NOT be converted into skills for it.
+     * Skills-capable agents WITHOUT a native command-file dir convert commands to
+     * skills by default; set this to opt such an agent out of that conversion.
+     */
+    nativeCommandRuntime?: boolean;
     hooksDir: string;
     pluginManifestDir?: string;
     instructionsFile: string;
@@ -605,6 +612,27 @@ export interface Meta {
      * lives separately in ~/.agents/.cache/browser/<profile>/.
      */
     browser?: Record<string, BrowserProfileConfig>;
+    /**
+     * Agent-host registry keyed by host name (`agents hosts`). Portable user
+     * config synced with `agents repo push/pull`. For `ssh-config` hosts this is
+     * just an overlay (caps/os) — the connection details stay in ~/.ssh/config and
+     * are never copied. `inline` hosts carry their own address/user.
+     */
+    hosts?: Record<string, HostEntry>;
+}
+/** Persisted agent-host entry in agents.yaml (overlay or inline). */
+export interface HostEntry {
+    /** `ssh-config`: reach via the bare name (ssh resolves). `inline`: use address/user below. */
+    source: 'ssh-config' | 'inline';
+    /** SSH-reachable target — inline hosts only (ssh-config hosts omit it). */
+    address?: string;
+    /** SSH user — inline hosts only. */
+    user?: string;
+    /** Captured at enroll probe. */
+    os?: string;
+    /** Free-form capability tags for routing (e.g. ['gpu']). */
+    caps?: string[];
+    addedAt?: string;
 }
 /** Browser profile definition stored in agents.yaml. */
 export interface BrowserProfileConfig {

package/dist/lib/versions.d.ts

@@ -144,8 +144,10 @@ export declare function isOldestInstalled(agent: AgentId): Promise<{
     installed: boolean;
     version: string | null;
 }>;
+/** Drop the installed-versions cache (call after install/remove mutations). */
+export declare function invalidateInstalledVersionsCache(agent?: AgentId): void;
 /**
- * List all installed versions for an agent.
+ * List all installed versions for an agent (cached by versions-dir mtime).
  */
 export declare function listInstalledVersions(agent: AgentId): string[];
 /**
@@ -239,12 +241,16 @@ export declare function resolveVersion(agent: AgentId, projectPath?: string): st
 /**
  * Normalize a user-supplied @version token across CLI subcommands.
  *
- *   undefined / "" / "default"  -> undefined  (caller falls back to project pin or global default)
+ *   undefined / "" / "default" / "pinned" -> undefined  (caller falls back to project pin or global default)
+ *   "any"                       -> undefined  (caller imposes no version constraint — e.g. resume across any version)
  *   "latest"                    -> highest installed version (process.exit if none installed)
  *   "oldest"                    -> lowest installed version (process.exit if none installed)
  *   "x.y.z" (installed)         -> "x.y.z"
  *   "x.y.z" (not installed)     -> process.exit with installed-list hint
  *
+ * `pinned` is a synonym for `default`: both name the project pin / global
+ * default, which the caller resolves.
+ *
  * Use this anywhere the user can type `agents <cmd> claude@<token>` to keep the
  * vocabulary consistent. Subcommands with different semantics for `latest`
  * (install/remove/use, where `latest` means npm-latest) keep their existing
@@ -253,7 +259,7 @@ export declare function resolveVersion(agent: AgentId, projectPath?: string): st
 export declare function resolveVersionAlias(agent: AgentId, raw: string | undefined | null): string | undefined;
 /**
  * Loose variant of resolveVersionAlias for record-filter contexts (sessions,
- * team history). Same `default`/`latest`/`oldest` semantics, but explicit
+ * team history). Same `default`/`pinned`/`latest`/`oldest` semantics, but explicit
  * versions pass through unchanged so historical records of uninstalled versions
  * remain queryable.
  */