@phnx-labs/agents-cli 1.20.27 → 1.20.29

package/dist/commands/ssh.js

@@ -0,0 +1,263 @@
+/**
+ * `agents devices` (registry) + `agents ssh` (smart wrapper).
+ *
+ * `agents devices` keeps a registry of SSH device profiles — platform, login
+ * user, address, and auth — self-populated from `tailscale status --json`.
+ * `agents ssh <name>` then connects through one hardened path: preflight
+ * (offline → fail fast instead of a 2-minute hang), platform-aware exec
+ * (PowerShell on Windows), and password-from-bundle auth via an askpass shim.
+ * Rendering the registry to an ssh_config include also lets plain ssh / scp /
+ * rsync / `agents sessions --host` resolve the same logical names.
+ */
+import { spawnSync } from 'child_process';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import chalk from 'chalk';
+import ora from 'ora';
+import { readAndResolveBundleEnv } from '../lib/secrets/bundles.js';
+import { getDevice, loadDevices, removeDevice, upsertDevice, } from '../lib/devices/registry.js';
+import { nodeToDeviceInput, parseTailscaleStatus, tailscaleStatusJson, } from '../lib/devices/tailscale.js';
+import { hostNameFor, renderSshConfig } from '../lib/devices/ssh-config.js';
+import { ASKPASS_BUNDLE_ENV, ASKPASS_KEY_ENV, buildSshInvocation, writeAskpassShim, } from '../lib/devices/connect.js';
+/** Parse `user@host` or `host` into pieces. */
+function parseTarget(target) {
+    const at = target.indexOf('@');
+    if (at === -1)
+        return { host: target };
+    return { user: target.slice(0, at), host: target.slice(at + 1) };
+}
+/** One-line summary of a device for `list`. */
+function deviceSummary(d) {
+    const addr = hostNameFor(d) ?? chalk.gray('no address');
+    const online = d.tailscale
+        ? d.tailscale.online
+            ? chalk.green('online')
+            : chalk.gray('offline')
+        : chalk.gray('unknown');
+    const reach = d.tailscale?.online && !d.tailscale.direct ? chalk.yellow(' (relayed)') : '';
+    return `  ${chalk.bold(d.name.padEnd(16))} ${String(d.platform).padEnd(8)} ${(d.user ? d.user + '@' : '') + addr}  ${online}${reach}`;
+}
+/** Resolve a device or exit with a clear error. */
+async function mustGetDevice(name) {
+    const d = await getDevice(name);
+    if (!d) {
+        console.error(chalk.red(`Unknown device '${name}'. See 'agents devices list'.`));
+        process.exit(1);
+    }
+    return d;
+}
+/** Register the `agents devices` command tree. */
+function registerDevicesCommands(program) {
+    const devicesCmd = program
+        .command('devices')
+        .description('Registry of SSH device profiles (platform, user, address, auth), self-populated from Tailscale.')
+        .addHelpText('after', `
+Typical workflow:
+  agents devices sync            # ingest tailscale nodes (auto-detect platform)
+  agents devices list            # see what's registered
+  agents devices set win-mini --auth password --bundle muqsit
+  agents devices render --write  # write ~/.ssh/config.d/agents include
+`);
+    devicesCmd
+        .command('sync')
+        .description('Ingest `tailscale status --json` and create/update device profiles (auto-detects platform, address, reachability).')
+        .action(async () => {
+        const spinner = ora('Reading tailscale status...').start();
+        try {
+            const nodes = parseTailscaleStatus(tailscaleStatusJson());
+            spinner.text = `Updating ${nodes.length} device${nodes.length === 1 ? '' : 's'}...`;
+            for (const node of nodes) {
+                await upsertDevice(node.name, nodeToDeviceInput(node));
+            }
+            spinner.succeed(`Synced ${nodes.length} device${nodes.length === 1 ? '' : 's'} from Tailscale`);
+        }
+        catch (err) {
+            spinner.fail(err.message);
+            process.exit(1);
+        }
+    });
+    devicesCmd
+        .command('list')
+        .alias('ls')
+        .description('List registered devices with platform, address, and reachability.')
+        .action(async () => {
+        const reg = await loadDevices();
+        const names = Object.keys(reg).sort();
+        if (names.length === 0) {
+            console.log(chalk.gray("No devices. Run 'agents devices sync' or 'agents devices add <name> <user@host>'."));
+            return;
+        }
+        console.log(chalk.bold(`Devices (${names.length})`));
+        for (const name of names)
+            console.log(deviceSummary(reg[name]));
+    });
+    devicesCmd
+        .command('show <name>')
+        .description('Show the full profile for one device.')
+        .action(async (name) => {
+        const d = await mustGetDevice(name);
+        console.log(JSON.stringify(d, null, 2));
+    });
+    devicesCmd
+        .command('add <name> <target>')
+        .description('Add a device manually (target is user@host or host).')
+        .option('--platform <platform>', 'windows | linux | macos')
+        .action(async (name, target, opts) => {
+        try {
+            const { host, user } = parseTarget(target);
+            const isIp = /^\d{1,3}(\.\d{1,3}){3}$/.test(host);
+            const d = await upsertDevice(name, {
+                platform: opts.platform ?? undefined,
+                user,
+                address: { via: 'manual', dnsName: isIp ? undefined : host, ip: isIp ? host : undefined },
+            });
+            console.log(chalk.green(`Added device '${name}'`) + chalk.gray(` (${d.platform}, ${user ? user + '@' : ''}${host})`));
+        }
+        catch (err) {
+            console.error(chalk.red(err.message));
+            process.exit(1);
+        }
+    });
+    devicesCmd
+        .command('set <name>')
+        .description('Update fields on an existing device (platform, user, auth).')
+        .option('--platform <platform>', 'windows | linux | macos')
+        .option('--user <user>', 'login user')
+        .option('--auth <method>', 'key | password')
+        .option('--bundle <bundle>', 'secrets bundle holding the password (for --auth password)')
+        .option('--bundle-key <key>', "key within the bundle (default 'password')")
+        .action(async (name, opts) => {
+        try {
+            const existing = await mustGetDevice(name);
+            const auth = opts.auth || opts.bundle || opts.bundleKey
+                ? {
+                    method: opts.auth ?? existing.auth.method,
+                    bundle: opts.bundle ?? existing.auth.bundle,
+                    bundleKey: opts.bundleKey ?? existing.auth.bundleKey,
+                }
+                : undefined;
+            const d = await upsertDevice(name, {
+                platform: opts.platform ?? undefined,
+                user: opts.user ?? undefined,
+                auth,
+            });
+            console.log(chalk.green(`Updated device '${name}'`) + chalk.gray(` (auth: ${d.auth.method}${d.auth.bundle ? ` via ${d.auth.bundle}` : ''})`));
+        }
+        catch (err) {
+            console.error(chalk.red(err.message));
+            process.exit(1);
+        }
+    });
+    devicesCmd
+        .command('rm <name>')
+        .alias('remove')
+        .description('Remove a device from the registry.')
+        .action(async (name) => {
+        const ok = await removeDevice(name);
+        if (!ok) {
+            console.error(chalk.red(`Unknown device '${name}'.`));
+            process.exit(1);
+        }
+        console.log(chalk.green(`Removed device '${name}'`));
+    });
+    devicesCmd
+        .command('render')
+        .description('Render the registry to ssh_config. Prints to stdout, or use --write to update ~/.ssh/config.d/agents.')
+        .option('--write', 'write to ~/.ssh/config.d/agents instead of printing')
+        .action(async (opts) => {
+        const reg = await loadDevices();
+        const text = renderSshConfig(reg);
+        if (!opts.write) {
+            process.stdout.write(text);
+            return;
+        }
+        const dir = path.join(os.homedir(), '.ssh', 'config.d');
+        const file = path.join(dir, 'agents');
+        fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+        fs.writeFileSync(file, text, { mode: 0o600 });
+        console.log(chalk.green(`Wrote ${file}`));
+        console.log(chalk.gray('Add this to ~/.ssh/config (once):  Include config.d/agents'));
+    });
+}
+/** Register the `agents ssh` smart wrapper. */
+function registerSshWrapper(program) {
+    const sshCmd = program
+        .command('ssh <name> [cmd...]')
+        .description('Connect to a registered device. Preflights reachability, picks the right shell, and authenticates (key or password-from-bundle).')
+        .allowUnknownOption()
+        .addHelpText('after', `
+Examples:
+  agents ssh win-mini                       # interactive login
+  agents ssh win-mini hostname              # run a command (PowerShell on Windows)
+  agents ssh yosemite-s0 uptime             # run a command (POSIX)
+
+Devices come from 'agents devices'. Password auth pulls the secret from a
+secrets bundle via an askpass shim — the password never touches argv.
+`)
+        .action(async (name, cmd) => {
+        // Hidden askpass bridge: ssh execs the shim, which re-invokes us here.
+        if (name === '__askpass') {
+            await runAskpass();
+            return;
+        }
+        const device = await mustGetDevice(name);
+        // Preflight: a device Tailscale last saw offline would otherwise hang
+        // for the full ConnectTimeout. Fail fast with a clear message instead.
+        if (device.tailscale && !device.tailscale.online) {
+            console.error(chalk.red(`Device '${name}' is offline (Tailscale last saw it ${device.tailscale.lastSeen ?? 'a while ago'}).`));
+            console.error(chalk.gray("Run 'agents devices sync' to refresh reachability."));
+            process.exit(1);
+        }
+        if (device.tailscale?.online && !device.tailscale.direct) {
+            console.error(chalk.yellow(`Note: connection to '${name}' is relayed (DERP ${device.tailscale.relay ?? '?'}) — expect higher latency.`));
+        }
+        try {
+            const shim = writeAskpassShim();
+            const { args, env } = buildSshInvocation(device, cmd, shim);
+            const res = spawnSync('ssh', args, {
+                stdio: 'inherit',
+                env: { ...process.env, ...env },
+            });
+            process.exit(res.status ?? 1);
+        }
+        catch (err) {
+            console.error(chalk.red(err.message));
+            process.exit(1);
+        }
+    });
+    // Keep the hidden askpass invocation out of help.
+    void sshCmd;
+}
+/**
+ * The askpass side of password auth. Invoked by the shim (which ssh execs with
+ * SSH_ASKPASS): read the target bundle/key from the environment the wrapper
+ * set, resolve it through the existing Keychain path, and print the password
+ * to stdout for ssh to consume.
+ */
+async function runAskpass() {
+    const bundle = process.env[ASKPASS_BUNDLE_ENV];
+    const key = process.env[ASKPASS_KEY_ENV] ?? 'password';
+    if (!bundle) {
+        console.error(`askpass: ${ASKPASS_BUNDLE_ENV} not set`);
+        process.exit(1);
+    }
+    try {
+        const { env } = readAndResolveBundleEnv(bundle, { caller: 'agents ssh' });
+        const value = env[key];
+        if (value === undefined) {
+            console.error(`askpass: key '${key}' not found in bundle '${bundle}'`);
+            process.exit(1);
+        }
+        process.stdout.write(value);
+    }
+    catch (err) {
+        console.error(`askpass: ${err?.message ?? err}`);
+        process.exit(1);
+    }
+}
+/** Register both `agents ssh` and `agents devices`. */
+export function registerSshCommands(program) {
+    registerSshWrapper(program);
+    registerDevicesCommands(program);
+}

package/dist/commands/sync.d.ts

@@ -9,6 +9,8 @@
  *   agents sync claude                                  # one agent: uses default/sole installed version
  *   agents sync claude@2.1.142                          # one agent: explicit version
  *   agents sync claude@latest                           # one agent: newest installed
+ *   agents sync claude@oldest                           # one agent: oldest installed
+ *   agents sync claude@pinned   (= claude@default)      # one agent: the pinned default version
  *   agents sync --agent claude --agent-version 2.1.142  # legacy form, still supported
  *
  * The umbrella stages live in lib/sync-umbrella.ts; this file dispatches to them

package/dist/commands/sync.js

@@ -9,6 +9,8 @@
  *   agents sync claude                                  # one agent: uses default/sole installed version
  *   agents sync claude@2.1.142                          # one agent: explicit version
  *   agents sync claude@latest                           # one agent: newest installed
+ *   agents sync claude@oldest                           # one agent: oldest installed
+ *   agents sync claude@pinned   (= claude@default)      # one agent: the pinned default version
  *   agents sync --agent claude --agent-version 2.1.142  # legacy form, still supported
  *
  * The umbrella stages live in lib/sync-umbrella.ts; this file dispatches to them
@@ -28,7 +30,7 @@
 import * as path from 'path';
 import chalk from 'chalk';
 import { agentLabel, resolveAgentName } from '../lib/agents.js';
-import { isVersionInstalled, syncResourcesToVersion, parseAgentSpec, resolveVersion, listInstalledVersions, getAvailableResources, getActuallySyncedResources, getProjectOnlyResources, getNewResources, hasNewResources, promptResourceSelection, promptNewResourceSelection, } from '../lib/versions.js';
+import { isVersionInstalled, syncResourcesToVersion, parseAgentSpec, resolveVersion, resolveVersionAlias, listInstalledVersions, getAvailableResources, getActuallySyncedResources, getProjectOnlyResources, getNewResources, hasNewResources, promptResourceSelection, promptNewResourceSelection, } from '../lib/versions.js';
 import { compileRulesForProject } from '../lib/rules/compile.js';
 import { runLaunchSync } from '../lib/project-launch.js';
 import { isInteractiveTerminal, isPromptCancelled } from './utils.js';
@@ -38,7 +40,7 @@ export function registerSyncCommand(program) {
     program
         .command('sync [agentSpec]')
         .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" or "claude@2.1.142".\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).')
+        .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", or a selector: @latest / @oldest / @pinned (= @default).\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)')
         .option('--agent-version <version>', 'Version to sync into (legacy form; prefer "agent@version")')
         .option('--project-dir <path>', 'Path to project-level .agents/ directory containing project-scoped resources')
@@ -116,17 +118,23 @@ async function runSync(agentSpec, opts) {
     // ---------- 1. Resolve agent + version ----------
     let agentId;
     let version;
+    // A positional @selector typed by the user (latest/oldest/pinned/default/
+    // explicit). parseAgentSpec defaults a missing version to 'latest', so a bare
+    // `agents sync claude` and `agents sync claude@latest` are indistinguishable
+    // after parsing — we only treat the version as a selector when an '@' was
+    // actually typed, keeping bare `claude` on the default-version path.
+    let selector;
     if (agentSpec) {
         const parsed = parseAgentSpec(agentSpec);
         if (!parsed) {
             errLog(chalk.red(`Invalid agent spec '${agentSpec}'.`));
-            errLog(chalk.gray('Examples: claude, claude@2.1.142, codex@latest'));
+            errLog(chalk.gray('Examples: claude, claude@2.1.142, claude@latest, claude@oldest, claude@pinned'));
             process.exitCode = 1;
             return;
         }
         agentId = parsed.agent;
-        if (parsed.version !== 'latest' && parsed.version !== 'oldest')
-            version = parsed.version;
+        if (agentSpec.includes('@'))
+            selector = parsed.version;
     }
     if (opts.agent) {
         const resolved = resolveAgentName(opts.agent);
@@ -138,6 +146,8 @@ async function runSync(agentSpec, opts) {
         agentId = resolved;
     }
     if (opts.agentVersion) {
+        // Legacy flag and the launch-shim hot path (`--agent-version <concrete>`):
+        // pass through verbatim. Selector aliases are a positional-spec feature.
         version = opts.agentVersion;
     }
     if (!agentId) {
@@ -147,6 +157,13 @@ async function runSync(agentSpec, opts) {
         return;
     }
     // ---------- 2. Resolve version (project pin → global default → sole installed) ----------
+    // A positional @selector wins over the default-resolution below.
+    //   @latest / @oldest        → newest / oldest installed (process.exit if none)
+    //   @pinned / @default       → undefined → fall through to the default path
+    //   @x.y.z                   → that version (process.exit if not installed)
+    if (selector !== undefined && !version) {
+        version = resolveVersionAlias(agentId, selector);
+    }
     if (!version) {
         version = resolveVersion(agentId, process.cwd()) || undefined;
         if (!version) {

package/dist/commands/view.js

@@ -21,6 +21,9 @@ import { listProfiles, profileSummary } from '../lib/profiles.js';
 import { loadManifest, isStale } from '../lib/staleness/index.js';
 import { confirm } from '@inquirer/prompts';
 import { formatPath, isInteractiveTerminal, isPromptCancelled } from './utils.js';
+// Shown in the email column for agents that are signed in but expose no email
+// address locally (Antigravity, Kimi store an opaque OAuth/JWT credential).
+const SIGNED_IN_LABEL = 'signed in';
 /**
  * Group profile summaries by their host harness, optionally filtered to a
  * single agent. Profile YAMLs that fail validation are silently skipped by
@@ -350,6 +353,8 @@ async function showInstalledVersions(filterAgentId) {
                 const info = rawInfo ? mergeCanonical(rawInfo) : undefined;
                 if (info?.email)
                     maxEmail = Math.max(maxEmail, info.email.length);
+                else if (info?.signedIn)
+                    maxEmail = Math.max(maxEmail, SIGNED_IN_LABEL.length);
                 if (info?.plan)
                     maxPlanWidth = Math.max(maxPlanWidth, info.plan.length);
             }
@@ -406,6 +411,7 @@ async function showInstalledVersions(filterAgentId) {
                 // Build columns, trimming trailing whitespace when columns are empty
                 const parts = [`    ${label}`];
                 const hasEmail = !!vInfo?.email;
+                const signedIn = !!vInfo?.signedIn;
                 const usageStr = formatUsageSummary(vInfo?.plan || null, usageInfo?.snapshot || null, maxPlanWidth);
                 const hasUsage = usageStr.length > 0;
                 // Only show lastActive for versions with an actual logged-in account.
@@ -418,14 +424,17 @@ async function showInstalledVersions(filterAgentId) {
                     runDefaultBits.push(`mode:${runDefaults.mode}`);
                 if (runDefaults.model)
                     runDefaultBits.push(`model:${runDefaults.model}`);
-                if (!hasEmail && !hasUsage) {
+                if (!hasEmail && !hasUsage && !signedIn) {
                     // Installed but never signed in
                     parts.push(chalk.gray('(not signed in — run ' + agent.cliCommand + ' to log in)'));
                 }
                 else {
-                    if (hasEmail || hasUsage || hasActive) {
-                        const emailCol = (vInfo?.email || '').padEnd(maxEmail);
-                        parts.push(hasEmail ? chalk.cyan(emailCol) : ' '.repeat(maxEmail));
+                    if (hasEmail || hasUsage || hasActive || signedIn) {
+                        // Signed-in agents without a local email (Antigravity, Kimi) show a
+                        // "signed in" placeholder so they read as logged in, not blank.
+                        const display = vInfo?.email || (signedIn ? SIGNED_IN_LABEL : '');
+                        const emailCol = display.padEnd(maxEmail);
+                        parts.push(display ? chalk.cyan(emailCol) : ' '.repeat(maxEmail));
                     }
                     if (hasUsage || hasActive) {
                         const usagePad = ' '.repeat(Math.max(0, maxUsageWidth - visibleWidth(usageStr)));
@@ -503,8 +512,10 @@ async function showInstalledVersions(filterAgentId) {
             const gUsage = gUsageKey ? usageByKey.get(gUsageKey) : undefined;
             const gUsageStr = formatUsageSummary(gInfo?.plan || null, gUsage?.snapshot || null);
             const gActiveStr = gInfo ? formatLastActive(gInfo.lastActive) : '';
-            if (gInfo?.email || gUsageStr || gActiveStr)
-                parts.push(gInfo?.email ? chalk.cyan(gInfo.email) : '');
+            if (gInfo?.email || gUsageStr || gActiveStr || gInfo?.signedIn) {
+                const gDisplay = gInfo?.email || (gInfo?.signedIn ? SIGNED_IN_LABEL : '');
+                parts.push(gDisplay ? chalk.cyan(gDisplay) : '');
+            }
             if (gUsageStr || gActiveStr)
                 parts.push(gUsageStr);
             const gStatusStr = formatUsageStatusBadge(gInfo?.usageStatus);
@@ -814,7 +825,11 @@ async function showAgentResources(agentId, requestedVersion, filter) {
             cliVersion: version,
             info: accountInfo,
         });
-        const emailStr = accountInfo.email ? chalk.cyan(`  ${accountInfo.email}`) : '';
+        const emailStr = accountInfo.email
+            ? chalk.cyan(`  ${accountInfo.email}`)
+            : accountInfo.signedIn
+                ? chalk.cyan(`  ${SIGNED_IN_LABEL}`)
+                : '';
         const status = chalk.green(version);
         const usageStr = formatUsageSummary(accountInfo.plan, null);
         const usagePart = usageStr ? `  ${usageStr}` : '';
@@ -1006,7 +1021,7 @@ async function collectAgentsJson(filterAgentId) {
         const entry = {
             version,
             isDefault: version === globalDefault,
-            signedIn: !!info.email,
+            signedIn: info.signedIn,
             email: info.email,
             plan: info.plan,
             usageStatus: info.usageStatus,
@@ -1273,9 +1288,10 @@ export async function viewAction(agentArg, options) {
         console.log(chalk.red(formatAgentError(agentName)));
         process.exit(1);
     }
-    // Keep 'default' as-is since showAgentResources handles it; resolveVersionAlias
-    // returns undefined for 'default' which would skip the detailed view.
-    const requestedVersion = parts[1] === 'default'
+    // Keep 'default'/'pinned' as-is since showAgentResources handles 'default';
+    // resolveVersionAlias returns undefined for both (they're synonyms), which
+    // would otherwise skip the detailed view.
+    const requestedVersion = (parts[1] === 'default' || parts[1] === 'pinned')
         ? 'default'
         : (resolveVersionAlias(agentId, parts[1]) ?? null);
     if (prune) {

package/dist/index.js

@@ -51,7 +51,7 @@ if (IS_DEV_BUILD) {
 // module on each invocation (which loaded the whole ~50-module tree before the
 // first byte of output), the registry maps a command name to a thunk that
 // imports only what that command needs. See src/lib/startup/command-registry.ts.
-import { COMMAND_LOADERS, LAZY_COMMAND_NAMES, loadView, loadInspect, loadFeedback, loadCommands, loadHooks, loadSkills, loadRules, loadPermissions, loadMcp, loadCli, loadSubagents, loadPlugins, loadWorkflows, loadWorktree, loadVersions, loadImport, loadPackages, loadDaemon, loadRoutines, loadRun, loadDefaults, loadModels, loadPrune, loadTrash, loadRestore, loadDoctor, loadProfiles, loadSecrets, loadWallet, loadHelper, loadMenubar, loadBeta, loadSync, loadRefreshRules, loadDrive, loadFactory, loadUsage, loadCost, loadBudget, loadAlias, loadPty, loadTmux, loadBrowser, loadComputer, loadPull, loadPush, loadRepo, loadSetup, } from './lib/startup/command-registry.js';
+import { COMMAND_LOADERS, LAZY_COMMAND_NAMES, loadView, loadInspect, loadFeedback, loadCommands, loadHooks, loadSkills, loadRules, loadPermissions, loadMcp, loadCli, loadSubagents, loadPlugins, loadWorkflows, loadWorktree, loadVersions, loadImport, loadPackages, loadDaemon, loadRoutines, loadRun, loadDefaults, loadModels, loadPrune, loadTrash, loadRestore, loadDoctor, loadProfiles, loadSecrets, loadWallet, loadHelper, loadMenubar, loadBeta, loadSync, loadRefreshRules, loadDrive, loadFactory, loadUsage, loadCost, loadBudget, loadAlias, loadPty, loadTmux, loadBrowser, loadComputer, loadHosts, loadSsh, loadPull, loadPush, loadRepo, loadSetup, } from './lib/startup/command-registry.js';
 import { applyGlobalHelpConventions } from './lib/help.js';
 import { IS_WINDOWS } from './lib/platform/index.js';
 // Transparent shim delegate: the generated Windows `.cmd` shims invoke
@@ -783,6 +783,8 @@ async function registerAllEagerCommands() {
     await reg(loadTmux);
     await reg(loadBrowser);
     await reg(loadComputer);
+    await reg(loadHosts);
+    await reg(loadSsh);
     registerJobsCronAliasCommand(program, 'jobs');
     registerJobsCronAliasCommand(program, 'cron');
     registerUpgradeCommand(program);

package/dist/lib/agents.d.ts

@@ -107,6 +107,7 @@ export interface AccountInfo {
         currency: string;
     } | null;
     lastActive: Date | null;
+    signedIn: boolean;
 }
 /** Return the email address associated with the agent's auth config, or null. */
 export declare function getAccountEmail(agentId: AgentId, home?: string): Promise<string | null>;

package/dist/lib/agents.js

@@ -15,6 +15,7 @@ import * as path from 'path';
 import * as os from 'os';
 import * as TOML from 'smol-toml';
 import chalk from 'chalk';
+import { needsWindowsShell } from './platform/index.js';
 import { latestFileMtimeMs } from './fs-walk.js';
 import { damerauLevenshtein } from './fuzzy.js';
 import { getCacheDir, getVersionsDir, getShimsDir, getCliVersionCachePath } from './state.js';
@@ -782,6 +783,7 @@ export async function getAccountInfo(agentId, home) {
         usageStatus: null,
         overageCredits: null,
         lastActive: null,
+        signedIn: false,
     };
     const configFiles = {
         claude: path.join(base, '.claude.json'),
@@ -853,6 +855,7 @@ export async function getAccountInfo(agentId, home) {
                     usageStatus,
                     overageCredits,
                     lastActive,
+                    signedIn: !!email,
                 };
             }
             case 'codex': {
@@ -894,11 +897,13 @@ export async function getAccountInfo(agentId, home) {
                     usageStatus,
                     overageCredits: null,
                     lastActive,
+                    signedIn: !!email,
                 };
             }
             case 'gemini': {
                 const data = JSON.parse(await fs.promises.readFile(path.join(base, '.gemini', 'google_accounts.json'), 'utf-8'));
-                return { ...empty, email: data.active || null, lastActive };
+                const email = data.active || null;
+                return { ...empty, email, signedIn: !!email, lastActive };
             }
             case 'grok': {
                 // Grok stores auth in ~/.grok/auth.json
@@ -907,12 +912,44 @@ export async function getAccountInfo(agentId, home) {
                     if (fs.existsSync(authPath)) {
                         const data = JSON.parse(await fs.promises.readFile(authPath, 'utf-8'));
                         const email = data.email || data.user?.email || data.account?.email || null;
-                        return { ...empty, email, lastActive };
+                        return { ...empty, email, signedIn: !!email, lastActive };
                     }
                 }
                 catch { }
                 return { ...empty, lastActive };
             }
+            case 'antigravity': {
+                // Antigravity (`agy`) stores a Google OAuth token at
+                // ~/.gemini/antigravity-cli/antigravity-oauth-token. It's a consumer
+                // OAuth grant (access + refresh token, no id_token), so there's no email
+                // claim to read locally — presence of a refresh token is the only
+                // signed-in signal we can derive without a network call.
+                const tokenPath = path.join(base, '.gemini', 'antigravity-cli', 'antigravity-oauth-token');
+                if (!fs.existsSync(tokenPath))
+                    return { ...empty, lastActive };
+                const data = JSON.parse(await fs.promises.readFile(tokenPath, 'utf-8'));
+                const hasToken = typeof data?.token?.refresh_token === 'string' && !!data.token.refresh_token;
+                if (!hasToken)
+                    return { ...empty, lastActive };
+                return { ...empty, signedIn: true, lastActive };
+            }
+            case 'kimi': {
+                // Kimi Code stores OAuth credentials at
+                // ~/.kimi-code/credentials/kimi-code.json. The access token is a JWT
+                // whose payload carries an opaque user_id (no email), so we report
+                // signed-in state plus a stable account key for usage dedup.
+                const credPath = path.join(base, '.kimi-code', 'credentials', 'kimi-code.json');
+                if (!fs.existsSync(credPath))
+                    return { ...empty, lastActive };
+                const data = JSON.parse(await fs.promises.readFile(credPath, 'utf-8'));
+                const accessToken = data?.access_token;
+                if (typeof accessToken !== 'string' || !accessToken)
+                    return { ...empty, lastActive };
+                const decoded = decodeJwtPayload(accessToken);
+                const userId = normalizeIdentityPart(decoded?.user_id ?? decoded?.sub);
+                const accountKey = buildIdentityKey(agentId, [['user', userId]]);
+                return { ...empty, signedIn: true, accountId: userId, accountKey, lastActive };
+            }
             default:
                 return { ...empty, lastActive };
         }
@@ -1151,7 +1188,10 @@ export async function registerMcp(agentId, name, command, scope = 'user', transp
         }
         // When home is specified, override HOME so MCP config writes to the version's config dir
         const env = options?.home ? { ...process.env, HOME: options.home } : undefined;
-        await execFileAsync(bin, args, env ? { env } : undefined);
+        // On Windows a bare command name / `.cmd` wrapper (the npm-installed agent
+        // CLI) can't be exec'd directly — it needs shell:true for PATHEXT/cmd. Off
+        // Windows this is always false, so the no-shell argv path is unchanged.
+        await execFileAsync(bin, args, { ...(env ? { env } : {}), shell: needsWindowsShell(bin) });
         return { success: true };
     }
     catch (err) {
@@ -1170,7 +1210,7 @@ export async function unregisterMcp(agentId, name, options) {
     try {
         const bin = options?.binary || agent.cliCommand;
         const env = options?.home ? { ...process.env, HOME: options.home } : undefined;
-        await execFileAsync(bin, ['mcp', 'remove', name], env ? { env } : undefined);
+        await execFileAsync(bin, ['mcp', 'remove', name], { ...(env ? { env } : {}), shell: needsWindowsShell(bin) });
         return { success: true };
     }
     catch (err) {

package/dist/lib/browser/drivers/ssh.d.ts

@@ -1,11 +1,56 @@
 import { CDPClient } from '../cdp.js';
 import type { BrowserProfile } from '../types.js';
+import { shellQuote } from '../../ssh-exec.js';
+export { shellQuote };
 export interface SSHConnection {
     cdp: CDPClient;
     port: number;
     pid: number;
     cleanup: () => void;
 }
-export declare function shellQuote(s: string): string;
+/**
+ * Which shell dialect the *remote* host speaks. Selected per-endpoint via the
+ * `&os=windows` query param on an `ssh://` target. POSIX is the default — the
+ * historical behavior for macOS/Linux remotes. Windows remotes run OpenSSH
+ * Server with cmd.exe as the default shell, so the launch/teardown command
+ * strings differ (no `&` backgrounding, no `lsof`, `.exe` instead of `.app`).
+ */
+export type RemoteOs = 'windows' | 'posix';
 export declare function connectSSH(endpoint: string, profile: BrowserProfile): Promise<SSHConnection>;
-export declare function restartRemoteBrowser(user: string, host: string, browserType: string, port: number, customBinary?: string): Promise<void>;
+/**
+ * Wrap a PowerShell script as a `-EncodedCommand` invocation. Base64 of the
+ * UTF-16LE bytes is a single quote-free token, so it rides through Node spawn
+ * → Windows sshd → cmd.exe with zero escaping hazards (hand-quoted
+ * `powershell -Command "…"` is fragile the moment a path or URL is involved).
+ */
+export declare function encodePowerShell(script: string): string;
+/**
+ * The PowerShell that launches the browser on a Windows remote. Two hard
+ * requirements shaped this:
+ *   1. The browser must OUTLIVE the ssh session. Windows OpenSSH terminates
+ *      the session's job tree on disconnect, which reaps both `start /B` and
+ *      `Start-Process` children (verified against a real box). WMI
+ *      `Win32_Process.Create` spawns under the WMI provider service instead,
+ *      so the process survives after we drop the ssh connection and reconnect
+ *      over the CDP tunnel.
+ *   2. A distinct `--user-data-dir` so a fresh instance bound to the debugging
+ *      port comes up even when the user already has Edge open.
+ * CreateProcess ignores App Paths, so we resolve the real `.exe` from the
+ * registry at runtime rather than relying on a bare `msedge` name.
+ */
+export declare function buildWindowsLaunchScript(browserType: string, port: number, customBinary?: string): string;
+/** The PowerShell that kills whatever holds the CDP port on a Windows remote. */
+export declare function buildWindowsKillScript(port: number): string;
+/**
+ * Build the remote command that launches the browser detached with a CDP port.
+ * POSIX backgrounds the `.app` binary with `… &`; Windows resolves the exe and
+ * spawns it via WMI (encoded PowerShell) so it survives the ssh session.
+ */
+export declare function buildLaunchCmd(remoteOs: RemoteOs, browserType: string, port: number, customBinary?: string): string;
+/**
+ * Build the remote command that kills whatever holds the CDP port.
+ * POSIX uses `lsof`+`kill`; Windows uses encoded PowerShell
+ * (Get-NetTCPConnection → Stop-Process).
+ */
+export declare function buildKillCmd(remoteOs: RemoteOs, port: number): string;
+export declare function restartRemoteBrowser(user: string, host: string, browserType: string, port: number, remoteOs: RemoteOs, customBinary?: string): Promise<void>;