@phnx-labs/agents-cli 1.20.31 → 1.20.33

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/state.d.ts

@@ -158,6 +158,8 @@ export declare function getTeamsRegistryPath(): string;
 export declare function getDevicesRegistryPath(): string;
 /** Path to the device ignore-list — tailscale node names the user dismissed, so auto-discovery never re-suggests them. Per-machine, same dir as the registry. */
 export declare function getDevicesIgnoredPath(): string;
+/** Dir of "pending device" sentinels (~/.agents/.cache/state/devices-pending/) — one empty-ish file per newly-discovered, not-yet-approved tailnet node. Written by the daemon probe, read by the menu-bar helper (mirrors the attention sentinel dir). */
+export declare function getDevicesPendingDir(): string;
 /** Path to cloud dispatch cache (~/.agents/.cache/cloud/). */
 export declare function getCloudDir(): string;
 /** Path to terminal session metadata (~/.agents/.cache/terminals/). */

package/dist/lib/state.js

@@ -354,6 +354,8 @@ export function getTeamsRegistryPath() { return path.join(HISTORY_DIR, 'teams',
 export function getDevicesRegistryPath() { return path.join(HISTORY_DIR, 'devices', 'registry.json'); }
 /** Path to the device ignore-list — tailscale node names the user dismissed, so auto-discovery never re-suggests them. Per-machine, same dir as the registry. */
 export function getDevicesIgnoredPath() { return path.join(HISTORY_DIR, 'devices', 'ignored.json'); }
+/** Dir of "pending device" sentinels (~/.agents/.cache/state/devices-pending/) — one empty-ish file per newly-discovered, not-yet-approved tailnet node. Written by the daemon probe, read by the menu-bar helper (mirrors the attention sentinel dir). */
+export function getDevicesPendingDir() { return path.join(RUNTIME_STATE_DIR, 'devices-pending'); }
 /** Path to cloud dispatch cache (~/.agents/.cache/cloud/). */
 export function getCloudDir() { return CLOUD_DIR; }
 /** Path to terminal session metadata (~/.agents/.cache/terminals/). */

package/dist/lib/sync-umbrella.js

@@ -120,15 +120,19 @@ export async function runUmbrellaSync(args) {
         const { refresh } = await import('./refresh.js');
         await refresh({ skipPrompts: yes });
         result.reconciled = true;
-        // Keep the local device registry current with the tailnet. Soft: a machine
-        // without tailscale is a clean no-op, never a sync failure. This is the
-        // wiring that fixes the "registry stays empty until you remember to run
-        // `agents devices sync`" gap — the SessionStart autosync now populates it.
+        // Keep already-registered devices' reachability current, and surface newly
+        // appeared tailnet nodes as "pending" for the menu-bar Register/Ignore gate
+        // rather than silently adding them (refresh mode). Soft: a machine without
+        // tailscale is a clean no-op, never a sync failure. First-run population is
+        // `agents setup` / manual `agents devices sync` (bootstrap).
         const { runDeviceSync } = await import('./devices/sync.js');
-        const dev = await runDeviceSync({ soft: true });
+        const { reconcilePendingSentinels } = await import('./devices/pending.js');
+        const dev = await runDeviceSync({ soft: true, mode: 'refresh' });
+        if (dev.ok)
+            reconcilePendingSentinels(dev.pending);
         result.devices = { synced: dev.synced, pending: dev.pending.length, skipped: !dev.ok };
         if (dev.ok) {
-            log(`devices: ${dev.synced} synced${dev.pending.length ? `, ${dev.pending.length} new` : ''}`);
+            log(`devices: ${dev.synced} refreshed${dev.pending.length ? `, ${dev.pending.length} new pending` : ''}`);
         }
     }
     return result;

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:
@@ -197,6 +198,17 @@ export declare function installVersion(agent: AgentId, version: string, onProgre
  * when nothing was resolved or no stale dir is present, so it is safe to call
  * on every script-based install. Returns the action taken (for tests/logging).
  */
+/**
+ * Proactively fold a stale `latest` version-home into its concrete version,
+ * WITHOUT needing a fresh install (RUSH-1320). `reconcileStaleLatestDir` only
+ * fires at install time, so a `latest` dir left by an old probe-failed install
+ * lingers in `agents view` indefinitely. This resolves the live CLI version and
+ * reconciles — cheap no-op when there's no `latest` dir (the common case, so
+ * `agents view` pays a `--version` shell-out only the once, until it's folded).
+ * Skipped when the active config symlink still points at `latest`, since
+ * renaming that dir would dangle the live symlink.
+ */
+export declare function reconcileStaleLatestForAgent(agent: AgentId): Promise<void>;
 export declare function reconcileStaleLatestDir(agent: AgentId, installedVersion: string): Promise<'none' | 'renamed' | 'trashed'>;
 /**
  * Soft-delete a version directory by moving it to ~/.agents/.system/trash/versions/.
@@ -268,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();
@@ -1209,6 +1208,26 @@ function removeInstallArtifacts(versionDir) {
  * when nothing was resolved or no stale dir is present, so it is safe to call
  * on every script-based install. Returns the action taken (for tests/logging).
  */
+/**
+ * Proactively fold a stale `latest` version-home into its concrete version,
+ * WITHOUT needing a fresh install (RUSH-1320). `reconcileStaleLatestDir` only
+ * fires at install time, so a `latest` dir left by an old probe-failed install
+ * lingers in `agents view` indefinitely. This resolves the live CLI version and
+ * reconciles — cheap no-op when there's no `latest` dir (the common case, so
+ * `agents view` pays a `--version` shell-out only the once, until it's folded).
+ * Skipped when the active config symlink still points at `latest`, since
+ * renaming that dir would dangle the live symlink.
+ */
+export async function reconcileStaleLatestForAgent(agent) {
+    if (!fs.existsSync(getVersionDir(agent, 'latest')))
+        return;
+    if (getConfigSymlinkVersion(agent) === 'latest')
+        return;
+    const concrete = await getCliVersionFromPath(agent);
+    if (concrete && concrete !== 'latest') {
+        await reconcileStaleLatestDir(agent, concrete);
+    }
+}
 export async function reconcileStaleLatestDir(agent, installedVersion) {
     if (installedVersion === 'latest')
         return 'none';
@@ -1455,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.31",
+  "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 };
-}