@phnx-labs/agents-cli 1.20.32 → 1.20.33

package/dist/lib/session/provenance.js

@@ -0,0 +1,157 @@
+/**
+ * Session provenance — where an active agent process actually lives.
+ *
+ * `detectHost()` in active.ts walks the ppid chain to name the *terminal app*
+ * (iterm / code / tmux). That answers "what UI is above it" but not the three
+ * things the Agent Feed needs to group and route:
+ *
+ *   1. Which machine    — os.hostname(), for the HOSTS sidebar.
+ *   2. Local vs SSH     — is SSH_CONNECTION in the process env?
+ *   3. Exact tmux pane  — TMUX_PANE ('%3'), the send-keys target.
+ *
+ * All three are inherited env vars, so we read them straight off the running
+ * process (no cooperation from the agent needed): `/proc/<pid>/environ` on
+ * Linux, `ps eww` on macOS. The read is best-effort — a process we can't stat
+ * (gone, or owned by another uid) yields `undefined`, never a guess.
+ *
+ * `reply` is a read-only hint, not a send channel: it reports whether a rail
+ * that can type back into this session exists today (tmux pane => addressable;
+ * inherited/ignored stdin => null). The feed uses it to decide whether to show
+ * a Send box. Actually delivering the keystrokes is Gap 2 (pty/tmux send-keys).
+ */
+import * as os from 'os';
+import { execFile } from 'child_process';
+import { promisify } from 'util';
+import { readFile } from 'fs/promises';
+const execFileAsync = promisify(execFile);
+/** Env vars that carry provenance. Kept small so the macOS `ps` scan stays cheap. */
+export const PROVENANCE_ENV_KEYS = [
+    'SSH_CONNECTION',
+    'SSH_TTY',
+    'TMUX',
+    'TMUX_PANE',
+    'TERM_PROGRAM',
+    'STY',
+];
+/** Parse the NUL-separated body of /proc/<pid>/environ into a plain object. */
+export function parseProcEnviron(buf) {
+    const env = {};
+    for (const pair of buf.split('\0')) {
+        if (!pair)
+            continue;
+        const eq = pair.indexOf('=');
+        if (eq <= 0)
+            continue;
+        env[pair.slice(0, eq)] = pair.slice(eq + 1);
+    }
+    return env;
+}
+/**
+ * How many whitespace-separated tokens each key's value spans. macOS
+ * `ps eww -o command=` space-joins the env after the command, so a value that
+ * itself contains spaces (SSH_CONNECTION is four fields) can't be recovered by
+ * boundary-guessing when the next token is an *unknown* var. Every provenance
+ * key except SSH_CONNECTION is a single token, so we read exactly its arity.
+ */
+const ENV_VALUE_TOKENS = { SSH_CONNECTION: 4 };
+/**
+ * Pull known env vars out of a macOS `ps eww` command+env line. For each
+ * `KEY=` match we consume the declared number of tokens (default 1), so
+ * SSH_CONNECTION's internal spaces survive while a following unknown var
+ * (e.g. `PWD=…`) is not swallowed into the previous value.
+ */
+export function extractKnownEnv(text, keys) {
+    const alt = keys.map((k) => k.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('|');
+    const boundary = new RegExp(`(?:^|\\s)(${alt})=`, 'g');
+    const env = {};
+    let m;
+    while ((m = boundary.exec(text)) !== null) {
+        const key = m[1];
+        const rest = text.slice(m.index + m[0].length);
+        const tokens = rest.split(/\s+/);
+        const want = ENV_VALUE_TOKENS[key] ?? 1;
+        env[key] = tokens.slice(0, want).join(' ');
+    }
+    return env;
+}
+/** `<client_ip> <client_port> <server_ip> <server_port>` → structured origin. */
+export function parseSshConnection(value) {
+    const parts = value.trim().split(/\s+/);
+    if (parts.length < 4)
+        return undefined;
+    const clientPort = parseInt(parts[1], 10);
+    const serverPort = parseInt(parts[3], 10);
+    if (!Number.isFinite(clientPort) || !Number.isFinite(serverPort))
+        return undefined;
+    return { clientIp: parts[0], clientPort, serverIp: parts[2], serverPort };
+}
+/** Build a SessionProvenance from a raw env map + the local hostname. Pure. */
+export function deriveProvenance(env, hostname) {
+    const ssh = env.SSH_CONNECTION ? parseSshConnection(env.SSH_CONNECTION) : undefined;
+    let mux;
+    if (env.TMUX) {
+        mux = {
+            kind: 'tmux',
+            socket: env.TMUX.split(',')[0] || undefined,
+            pane: env.TMUX_PANE || undefined,
+        };
+    }
+    else if (env.STY) {
+        mux = { kind: 'screen', session: env.STY };
+    }
+    // A tmux pane is the one rail that lets an external process type into an
+    // already-running interactive agent (`tmux send-keys -t <pane>`). Everything
+    // else (inherited stdin from `agents run`, ignored stdin from teams) is not
+    // externally addressable without relaunching under a pty/tmux rail.
+    const reply = mux?.kind === 'tmux' && mux.pane
+        ? { rail: 'tmux', target: mux.pane, socket: mux.socket }
+        : null;
+    return {
+        host: hostname,
+        transport: ssh ? 'ssh' : 'local',
+        ssh,
+        term: env.TERM_PROGRAM || undefined,
+        mux,
+        reply,
+    };
+}
+/** Read a process's environment. Linux: /proc. macOS: `ps eww`. Best-effort. */
+async function readProcEnv(pid) {
+    if (process.platform === 'linux') {
+        try {
+            const buf = await readFile(`/proc/${pid}/environ`, 'utf8');
+            return parseProcEnviron(buf);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    if (process.platform === 'darwin') {
+        try {
+            const { stdout } = await execFileAsync('ps', ['eww', '-p', String(pid), '-o', 'command='], {
+                encoding: 'utf8',
+                maxBuffer: 1024 * 1024,
+            });
+            if (!stdout.trim())
+                return undefined;
+            return extractKnownEnv(stdout, PROVENANCE_ENV_KEYS);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    return undefined;
+}
+/**
+ * Resolve provenance for a live pid. Returns undefined when the process env
+ * can't be read (process gone, foreign uid, unsupported platform) — we never
+ * fabricate a 'local' answer we can't back with the env.
+ */
+export async function detectProvenance(pid) {
+    if (!pid || pid < 1)
+        return undefined;
+    const env = await readProcEnv(pid);
+    if (!env)
+        return undefined;
+    return deriveProvenance(env, os.hostname());
+}

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

@@ -19,6 +19,7 @@ export declare function assertValidSshTarget(host: string): void;
 export declare function shellQuote(s: string): string;
 /** Hardened ssh options applied to every connection. */
 export declare const SSH_OPTS: readonly string[];
+export declare function controlOpts(): string[];
 export interface SshExecOptions {
     /** Piped to the remote command's stdin (never interpolated into the shell). */
     input?: string;
@@ -26,6 +27,8 @@ export interface SshExecOptions {
     timeoutMs?: number;
     /** Extra ssh flags inserted before the target (e.g. `-tt`). */
     extraSshArgs?: string[];
+    /** Reuse a persistent control socket across calls (see `controlOpts`). */
+    multiplex?: boolean;
 }
 export interface SshExecResult {
     /** Remote exit status, or null if ssh itself failed / timed out. */
@@ -43,3 +46,22 @@ export interface SshExecResult {
 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;
+export interface SshStreamOptions {
+    /**
+     * Allocate a remote pseudo-terminal (`ssh -tt`) so an interactive remote
+     * command (a picker, a prompt) renders live on the local terminal. Callers
+     * pass this when the *local* process is itself a TTY; piped/scripted callers
+     * leave it off and forward a non-interactive invocation instead.
+     */
+    tty?: boolean;
+    /** Reuse a persistent control socket across calls (see `controlOpts`). */
+    multiplex?: boolean;
+}
+/**
+ * Foreground counterpart to `sshExec`: run `remoteCmd` on `target` with the
+ * local stdio wired straight through (`stdio: 'inherit'`), so output streams as
+ * it is produced and — with `tty` — keystrokes reach a remote picker. Blocks
+ * until the remote command exits and returns its exit code (255 is ssh's own
+ * connection-layer failure; any other non-zero is the remote command's code).
+ */
+export declare function sshStream(target: string, remoteCmd: string, opts?: SshStreamOptions): number;

package/dist/lib/ssh-exec.js

@@ -8,6 +8,9 @@
  * canonical definition; `commands/secrets.ts` re-exports it.
  */
 import { spawnSync } from 'child_process';
+import * as fs from 'fs';
+import * as path from 'path';
+import { getCacheDir } from './state.js';
 /**
  * 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
@@ -32,6 +35,42 @@ export const SSH_OPTS = [
     '-o', 'BatchMode=yes',
     '-o', 'ConnectTimeout=10',
 ];
+/**
+ * OpenSSH connection-multiplexing options. The first connection to a host opens
+ * a control socket; subsequent connections (even from a *separate* `agents`
+ * invocation) reuse it, skipping the TCP+auth handshake — so repeated
+ * `--host <name>` calls to the same box feel local instead of paying ~100-300ms
+ * each. `ControlPersist=60s` keeps the master alive briefly after the last
+ * client exits. `%C` (a short fixed-length hash of local-host/remote/port/user)
+ * keeps the socket path well under macOS's 104-char `sun_path` limit.
+ *
+ * The socket directory is created lazily; if ssh can't open the control socket
+ * it falls back to a normal connection (multiplexing is an optimisation, never a
+ * requirement), so this can never make a reachable host unreachable.
+ */
+let controlDirEnsured = false;
+export function controlOpts() {
+    // OpenSSH on Windows has no ControlMaster/ControlPath (unix-socket) support —
+    // passing those options makes ssh error out. Multiplexing is a pure latency
+    // optimisation, so on Windows we simply skip it and use a fresh connection.
+    if (process.platform === 'win32')
+        return [];
+    const dir = path.join(getCacheDir(), 'ssh');
+    if (!controlDirEnsured) {
+        try {
+            fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+        }
+        catch {
+            /* best-effort — ssh degrades to a fresh connection if the dir is missing */
+        }
+        controlDirEnsured = true;
+    }
+    return [
+        '-o', 'ControlMaster=auto',
+        '-o', `ControlPath=${path.join(dir, 'cm-%C')}`,
+        '-o', 'ControlPersist=60s',
+    ];
+}
 /**
  * Run `remoteCmd` on `target` over ssh and capture stdout/stderr/exit.
  *
@@ -40,7 +79,8 @@ export const SSH_OPTS = [
  */
 export function sshExec(target, remoteCmd, opts = {}) {
     assertValidSshTarget(target);
-    const args = [...SSH_OPTS, ...(opts.extraSshArgs ?? []), target, remoteCmd];
+    const mux = opts.multiplex ? controlOpts() : [];
+    const args = [...SSH_OPTS, ...mux, ...(opts.extraSshArgs ?? []), target, remoteCmd];
     const res = spawnSync('ssh', args, {
         input: opts.input,
         encoding: 'utf-8',
@@ -57,5 +97,22 @@ export function sshExec(target, remoteCmd, opts = {}) {
 }
 /** 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;
+    return sshExec(target, 'true', { timeoutMs, multiplex: true }).code === 0;
+}
+/**
+ * Foreground counterpart to `sshExec`: run `remoteCmd` on `target` with the
+ * local stdio wired straight through (`stdio: 'inherit'`), so output streams as
+ * it is produced and — with `tty` — keystrokes reach a remote picker. Blocks
+ * until the remote command exits and returns its exit code (255 is ssh's own
+ * connection-layer failure; any other non-zero is the remote command's code).
+ */
+export function sshStream(target, remoteCmd, opts = {}) {
+    assertValidSshTarget(target);
+    const mux = opts.multiplex ? controlOpts() : [];
+    const tty = opts.tty ? ['-tt'] : [];
+    const args = [...SSH_OPTS, ...mux, ...tty, target, remoteCmd];
+    const res = spawnSync('ssh', args, { stdio: 'inherit' });
+    if (typeof res.status === 'number')
+        return res.status;
+    return 255; // spawn error / signal — treat as a connection-layer failure
 }

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

@@ -90,11 +90,6 @@ export declare function buildPushScript(): string;
 export declare function buildRegisterTaskScript(port: number, taskName: string): string;
 /** PowerShell that unregisters the task and stops any running daemon process. */
 export declare function buildUnregisterTaskScript(taskName: string): string;
-/**
- * `setup --host`: push the exe, then register + start the LOGON task. Both hops
- * go through `sshExec` (BatchMode key auth — the same hardening the browser
- * driver and `agents ssh` use). Throws with the remote stderr on any failure.
- */
 export declare function setupRemoteHelper(name: string): Promise<{
     target: string;
     taskName: string;

package/dist/lib/ssh-tunnel.js

@@ -22,7 +22,8 @@ import * as fs from 'fs';
 import * as path from 'path';
 import { fileURLToPath } from 'url';
 import { randomBytes } from 'crypto';
-import { sshExec } from './ssh-exec.js';
+import { Transform } from 'stream';
+import { sshExec, SSH_OPTS } from './ssh-exec.js';
 import { encodePowerShell } from './browser/drivers/ssh.js';
 import { getDevice } from './devices/registry.js';
 import { sshTargetFor } from './devices/connect.js';
@@ -199,20 +200,76 @@ export function buildUnregisterTaskScript(taskName) {
  * go through `sshExec` (BatchMode key auth — the same hardening the browser
  * driver and `agents ssh` use). Throws with the remote stderr on any failure.
  */
+/**
+ * Base64-encode a byte stream in 3-byte-aligned chunks so the concatenated
+ * output is valid (every chunk boundary lands on a base64 quantum).
+ */
+class Base64Encode extends Transform {
+    leftover = Buffer.alloc(0);
+    _transform(chunk, _enc, cb) {
+        const buf = this.leftover.length ? Buffer.concat([this.leftover, chunk]) : chunk;
+        const usable = buf.length - (buf.length % 3);
+        this.leftover = Buffer.from(buf.subarray(usable));
+        if (usable > 0)
+            this.push(buf.subarray(0, usable).toString('base64'));
+        cb();
+    }
+    _flush(cb) {
+        if (this.leftover.length)
+            this.push(this.leftover.toString('base64'));
+        cb();
+    }
+}
+/**
+ * Stream a local file to a remote command's stdin over ssh, base64-encoded on
+ * the fly. Async spawn + piping honors backpressure; the previous
+ * `spawnSync({ input })` blob deadlocked once the ssh socket buffer filled
+ * (~4MB) on large files (the 157MB Windows helper reproduced this reliably),
+ * and worse, reported a false success leaving a 0-byte remote file. Rejects on
+ * any pipe error so a broken transfer fails loudly instead.
+ */
+function streamFileOverSsh(target, remoteCmd, filePath, timeoutMs = 600_000) {
+    return new Promise((resolve, reject) => {
+        const child = spawn('ssh', [...SSH_OPTS, target, remoteCmd], {
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        let stderr = '';
+        let stdout = '';
+        child.stderr.on('data', (d) => (stderr += d.toString()));
+        child.stdout.on('data', (d) => (stdout += d.toString()));
+        const timer = setTimeout(() => {
+            child.kill('SIGKILL');
+            reject(new Error(`ssh push to ${target} timed out after ${timeoutMs}ms`));
+        }, timeoutMs);
+        const fail = (e) => {
+            clearTimeout(timer);
+            child.kill('SIGKILL');
+            reject(e);
+        };
+        child.on('error', fail);
+        child.stdin.on('error', fail); // EPIPE if the remote decoder dies mid-stream
+        child.on('close', (code) => {
+            clearTimeout(timer);
+            resolve({ code, stderr: stderr || stdout });
+        });
+        const src = fs.createReadStream(filePath);
+        src.on('error', fail);
+        // disk -> aligned base64 -> ssh stdin; .pipe() applies backpressure
+        src.pipe(new Base64Encode()).pipe(child.stdin);
+    });
+}
 export async function setupRemoteHelper(name) {
     const { target } = await resolveRemoteDevice(name);
     const exe = resolveWinHelperExe();
     if (!exe) {
         throw new Error(`Windows helper exe not built. Run: bash scripts/build-win.sh`);
     }
-    // Push: base64 the exe locally, stream it over ssh stdin to the decoder.
-    const b64 = fs.readFileSync(exe).toString('base64');
-    const push = sshExec(target, encodePowerShell(buildPushScript()), {
-        input: b64,
-        timeoutMs: 600_000, // ~156MB over the wire — allow up to 10 minutes
-    });
+    // Push: stream the exe from disk, base64-encoded on the fly, to the remote
+    // decoder. Streaming (vs a single spawnSync `input` blob) honors ssh socket
+    // backpressure — the blob path deadlocks once the socket buffer fills (~4MB).
+    const push = await streamFileOverSsh(target, encodePowerShell(buildPushScript()), exe);
     if (push.code !== 0) {
-        throw new Error(`pushing helper exe to '${name}' failed (exit ${push.code ?? 'null'}): ${push.stderr.trim() || push.stdout.trim()}`);
+        throw new Error(`pushing helper exe to '${name}' failed (exit ${push.code ?? 'null'}): ${push.stderr.trim()}`);
     }
     // Register + start the LOGON task.
     const reg = sshExec(target, encodePowerShell(buildRegisterTaskScript(REMOTE_HELPER_PORT, REMOTE_TASK_NAME)), {

package/dist/lib/versions.d.ts

@@ -1,4 +1,5 @@
 import type { AgentId } from './types.js';
+import { compareVersions } from './agent-spec/primitives.js';
 /**
  * Resource selection for syncing to a version.
  * Each field can be:
@@ -279,10 +280,7 @@ export declare function resolveVersionAliasLoose(agent: AgentId, raw: string | u
  * Get version specified in a project-root agents.yaml (not the user ~/.agents/.system/agents.yaml).
  */
 export declare function getProjectVersion(agent: AgentId, startPath: string): string | null;
-/**
- * Compare semver versions for sorting.
- */
-export declare function compareVersions(a: string, b: string): number;
+export { compareVersions };
 /**
  * Get actual version from an installed 'latest' directory.
  */

package/dist/lib/versions.js

@@ -24,6 +24,10 @@ import { checkbox, select } from '@inquirer/prompts';
 import { getVersionsDir, ensureAgentsDir, readMeta, writeMeta, getCommandsDir, getSkillsDir, getHooksDir, getResolvedRulesDir, getUserRulesDir, getVersionResources, ensureVersionResourcePatterns, getProjectAgentsDir, getPromptcutsPath, getUserPromptcutsPath, getEnabledExtraRepos, getAgentsDir, getUserAgentsDir, getTrashVersionsDir, getActiveRulesPreset, getHomeDir } from './state.js';
 import { defaultPatterns, expandPatterns } from './resource-patterns.js';
 import { listResources } from './resources.js';
+// VERSION_RE + compareVersions are owned by the agent-spec engine primitives
+// (single source of truth). Re-exported below so existing importers of
+// `compareVersions` from './versions.js' keep working.
+import { VERSION_RE, compareVersions } from './agent-spec/primitives.js';
 import { AGENTS, agentConfigDirName, getAccountEmail, resolveAgentName, formatAgentError, findInPath } from './agents.js';
 import { discoverPermissionGroups, getActivePermissionPresetName, readPermissionPresetRecipe, PERMISSION_PRESET_ENV_VAR } from './permissions.js';
 import { parseMcpServerConfig } from './mcp.js';
@@ -41,11 +45,6 @@ import { getWriter, getDetector } from './staleness/registry.js';
 const execAsync = promisify(exec);
 const execFileAsync = promisify(execFile);
 const RULES_DOC_FILENAME = 'README.md';
-// Strict shape for an agent version string. Anything outside this is rejected
-// at parse time so it can't reach an exec/shell boundary or get interpolated
-// into a generated bash alias. Must allow "latest" plus npm-dist-tag /
-// semver-shaped values (digits, dots, dashes, +, _).
-const VERSION_RE = /^(?:latest|(?!.*\.\.)[A-Za-z0-9._+-]{1,64})$/;
 function getResourceBases(cwd) {
     const projectAgentsDir = getProjectAgentsDir(cwd);
     const userBase = getUserAgentsDir();
@@ -1475,21 +1474,9 @@ export function getProjectVersion(agent, startPath) {
     }
     return null;
 }
-/**
- * Compare semver versions for sorting.
- */
-export function compareVersions(a, b) {
-    const aParts = a.split('.').map((n) => parseInt(n, 10) || 0);
-    const bParts = b.split('.').map((n) => parseInt(n, 10) || 0);
-    for (let i = 0; i < Math.max(aParts.length, bParts.length); i++) {
-        const aVal = aParts[i] || 0;
-        const bVal = bParts[i] || 0;
-        if (aVal !== bVal) {
-            return aVal - bVal;
-        }
-    }
-    return 0;
-}
+// compareVersions is defined in ./agent-spec/primitives.ts and re-exported here
+// so existing `import { compareVersions } from './versions.js'` sites keep working.
+export { compareVersions };
 /**
  * Get actual version from an installed 'latest' directory.
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phnx-labs/agents-cli",
-  "version": "1.20.32",
+  "version": "1.20.33",
   "description": "One CLI for all your AI coding agents - versions, config, cloud dispatch, sessions, and teams (now with first-class Grok Build CLI support)",
   "type": "module",
   "main": "dist/index.js",
@@ -51,6 +51,7 @@
     "dev": "tsx src/index.ts",
     "start": "node dist/index.js",
     "test": "node ./node_modules/vitest/vitest.mjs run",
+    "test:remote": "scripts/sandbox.sh 'bun install && bun run build && bun run test'",
     "test:watch": "node ./node_modules/vitest/vitest.mjs"
   },
   "keywords": [

package/dist/lib/agent-spec.d.ts

@@ -1,36 +0,0 @@
-import type { AgentId } from './types.js';
-export interface AgentTarget {
-    agent: AgentId;
-    /** Resolved exact version, or null when the agent has no installed versions yet. */
-    version: string | null;
-}
-/** Canonical qualifier set, in help/display order. `pinned` ≡ `default`. */
-export declare const AGENT_QUALIFIERS: readonly ["latest", "oldest", "pinned", "default", "all"];
-export type AgentQualifier = (typeof AGENT_QUALIFIERS)[number];
-/** Shared `--help` epilog so every agent-spec command documents the same grammar. */
-export declare const AGENT_SPEC_HELP: string;
-export declare class AgentSpecError extends Error {
-    constructor(message: string);
-}
-export interface ResolveAgentTargetsOptions {
-    /** Project dir for resolving a bare spec's project pin. Defaults to process.cwd(). */
-    cwd?: string;
-    /** Restrict the agents a spec may name (e.g. only mcp-capable). Defaults to all. */
-    availableAgents?: readonly AgentId[];
-}
-/**
- * Resolve an agent spec (single or comma-list) into concrete installed targets.
- * Domain = installed: `@latest`/`@oldest`/`@all` range over installed versions
- * (`add`/`install` use a separate available-version path). Throws AgentSpecError
- * on bad input — never calls process.exit, so it is safe on the hot path and in
- * library contexts.
- */
-export declare function resolveAgentTargets(spec: string, opts?: ResolveAgentTargetsOptions): AgentTarget[];
-/**
- * Convenience for single-target commands (`use`, `run`): resolve a spec that
- * must name exactly one installed version. Rejects `@all` / multi-target specs.
- */
-export declare function resolveSingleAgentTarget(spec: string, opts?: ResolveAgentTargetsOptions): {
-    agent: AgentId;
-    version: string;
-};

package/dist/lib/agent-spec.js

@@ -1,157 +0,0 @@
-// Centralized agent-spec resolution — one vocabulary, one resolver, reused by
-// every subcommand that accepts `<agent>[@<qualifier>]`.
-//
-// The qualifier vocabulary used to be split across three functions in
-// versions.ts (parseAgentSpec, resolveVersionAlias, resolveInstalledAgentTargets)
-// with diverging support — `@latest`/`@oldest` in one, `@all`/`@default` in
-// another, `@pinned` nowhere. This module is the single source of truth.
-//
-// Built for the hot path (`--launch`, ~100ms budget): the common specs resolve
-// with NO directory enumeration —
-//   exact `claude@2.1.181`   → one isVersionInstalled() (existsSync)
-//   `claude@pinned|@default` → memoized getGlobalDefault() + existsSync
-//   bare `claude`            → resolveVersion() (memoized meta), no readdir
-// Only the relative qualifiers `@latest`/`@oldest`/`@all` enumerate, and even
-// then via the mtime-cached listInstalledVersions().
-import { AGENTS, ALL_AGENT_IDS, resolveAgentName, formatAgentError } from './agents.js';
-import { listInstalledVersions, getGlobalDefault, isVersionInstalled, resolveVersion, } from './versions.js';
-/** Canonical qualifier set, in help/display order. `pinned` ≡ `default`. */
-export const AGENT_QUALIFIERS = ['latest', 'oldest', 'pinned', 'default', 'all'];
-/** Shared `--help` epilog so every agent-spec command documents the same grammar. */
-export const AGENT_SPEC_HELP = 'Agent spec: <agent>[@<qualifier>]. Qualifiers: ' +
-    '@latest (highest installed), @oldest (lowest installed), ' +
-    '@pinned / @default (your configured default — synonyms), ' +
-    '@all (every installed version), or an exact @x.y.z. ' +
-    'Bare <agent> uses the resolved default (project pin → global default). ' +
-    'Comma-separate to combine: claude@all,codex@latest.';
-export class AgentSpecError extends Error {
-    constructor(message) {
-        super(message);
-        this.name = 'AgentSpecError';
-    }
-}
-/**
- * Resolve an agent spec (single or comma-list) into concrete installed targets.
- * Domain = installed: `@latest`/`@oldest`/`@all` range over installed versions
- * (`add`/`install` use a separate available-version path). Throws AgentSpecError
- * on bad input — never calls process.exit, so it is safe on the hot path and in
- * library contexts.
- */
-export function resolveAgentTargets(spec, opts = {}) {
-    const cwd = opts.cwd ?? process.cwd();
-    const available = opts.availableAgents ?? ALL_AGENT_IDS;
-    const rawEntries = spec
-        .split(',')
-        .map((s) => s.trim())
-        .filter(Boolean);
-    if (rawEntries.length === 0) {
-        throw new AgentSpecError('Empty agent spec.');
-    }
-    // Expand the bare literal `all` (or `all@all`) into every available agent that
-    // has at least one installed version. Lenient: agents with nothing installed
-    // are skipped rather than erroring.
-    const entries = [];
-    for (const e of rawEntries) {
-        if (e === 'all' || e === 'all@all') {
-            for (const a of available) {
-                if (listInstalledVersions(a).length > 0)
-                    entries.push(`${a}@all`);
-            }
-        }
-        else {
-            entries.push(e);
-        }
-    }
-    const out = [];
-    const seen = new Set();
-    const push = (agent, version) => {
-        const key = `${agent}@${version ?? ''}`;
-        if (!seen.has(key)) {
-            seen.add(key);
-            out.push({ agent, version });
-        }
-    };
-    for (const entry of entries) {
-        const at = entry.indexOf('@');
-        const agentToken = (at === -1 ? entry : entry.slice(0, at)).trim();
-        const qualifier = at === -1 ? null : entry.slice(at + 1).trim();
-        if (!agentToken)
-            continue;
-        if (at !== -1 && !qualifier) {
-            throw new AgentSpecError(`Missing version in '${entry}'. Use ${agentToken}@x.y.z, @latest, @oldest, @pinned, @default, or @all.`);
-        }
-        const agent = resolveAgentName(agentToken);
-        if (!agent || !available.includes(agent)) {
-            throw new AgentSpecError(formatAgentError(agentToken, [...available]));
-        }
-        const name = AGENTS[agent].name;
-        // ----- bare: resolved default, NO enumeration in the common case -----
-        if (qualifier === null) {
-            const resolved = resolveVersion(agent, cwd); // project pin → global default (meta-only)
-            if (resolved) {
-                push(agent, resolved);
-            }
-            else {
-                const installed = listInstalledVersions(agent);
-                if (installed.length === 0)
-                    push(agent, null);
-                else if (installed.length === 1)
-                    push(agent, installed[0]);
-                else
-                    throw new AgentSpecError(`No default version set for ${name}. Specify one (${agent}@<version>) or set it: agents use ${agent}@<version>.`);
-            }
-            continue;
-        }
-        // ----- @pinned / @default: synonyms, meta-only fast path -----
-        if (qualifier === 'pinned' || qualifier === 'default') {
-            const def = getGlobalDefault(agent);
-            if (!def) {
-                throw new AgentSpecError(`No default version set for ${name}. Run: agents use ${agent}@<version>`);
-            }
-            push(agent, def);
-            continue;
-        }
-        // ----- @all: every installed version -----
-        if (qualifier === 'all') {
-            const installed = listInstalledVersions(agent);
-            if (installed.length === 0) {
-                throw new AgentSpecError(`No managed versions are installed for ${name}. Run: agents add ${agent}@latest`);
-            }
-            for (const v of installed)
-                push(agent, v);
-            continue;
-        }
-        // ----- @latest / @oldest: enumerate (mtime-cached), pick an end -----
-        if (qualifier === 'latest' || qualifier === 'oldest') {
-            const installed = listInstalledVersions(agent); // already sorted ascending
-            if (installed.length === 0) {
-                throw new AgentSpecError(`No managed versions are installed for ${name}. Run: agents add ${agent}@latest`);
-            }
-            push(agent, qualifier === 'oldest' ? installed[0] : installed[installed.length - 1]);
-            continue;
-        }
-        // ----- exact version: one existsSync, NO enumeration -----
-        if (!isVersionInstalled(agent, qualifier)) {
-            const installed = listInstalledVersions(agent);
-            const hint = installed.length ? ` Installed: ${installed.join(', ')}.` : '';
-            throw new AgentSpecError(`${name}@${qualifier} is not installed.${hint} Install it: agents add ${agent}@${qualifier}`);
-        }
-        push(agent, qualifier);
-    }
-    return out;
-}
-/**
- * Convenience for single-target commands (`use`, `run`): resolve a spec that
- * must name exactly one installed version. Rejects `@all` / multi-target specs.
- */
-export function resolveSingleAgentTarget(spec, opts = {}) {
-    const targets = resolveAgentTargets(spec, opts);
-    if (targets.length !== 1) {
-        throw new AgentSpecError(`'${spec}' resolves to ${targets.length} targets; this command needs exactly one.`);
-    }
-    const t = targets[0];
-    if (t.version === null) {
-        throw new AgentSpecError(`No installed version for ${AGENTS[t.agent].name}. Run: agents add ${t.agent}@latest`);
-    }
-    return { agent: t.agent, version: t.version };
-}