@phnx-labs/agents-cli 1.20.28 → 1.20.30

package/dist/commands/sessions.js

@@ -17,6 +17,7 @@ import { SESSION_AGENTS } from '../lib/session/types.js';
 import { discoverArtifacts, readArtifact, resolveArtifact } from '../lib/session/artifacts.js';
 import { looksLikePath, toComparablePath, homeDir } from '../lib/platform/index.js';
 import { getActiveSessions } from '../lib/session/active.js';
+import { stringWidth, truncateToWidth, padToWidth, terminalWidth } from '../lib/session/width.js';
 import { discoverSessions, countSessionsInScope, resolveSessionById, searchContentIndex } from '../lib/session/discover.js';
 import { filterTeamSessions } from '../lib/session/team-filter.js';
 import { parseSession } from '../lib/session/parse.js';
@@ -162,43 +163,77 @@ function formatStartedAt(startedAtMs) {
         return '-';
     return formatRelativeTime(new Date(startedAtMs).toISOString());
 }
-/** Build a display-friendly description for an active session (label or topic). */
+/**
+ * Build the live description for an active session: prefer the state engine's
+ * preview (the latest turn), then a user label, then the first-prompt topic.
+ */
 function buildSessionDescription(s) {
     if (s.context === 'cloud') {
-        return `${s.cloudProvider ?? ''}${s.cloudTaskId ? ` · ${s.cloudTaskId.slice(0, 12)}` : ''}`;
+        return s.preview || `${s.cloudProvider ?? ''}${s.cloudTaskId ? ` · ${s.cloudTaskId.slice(0, 12)}` : ''}`;
     }
     if (s.context === 'teams') {
         const parts = [s.teamName];
-        if (s.label)
+        if (s.preview)
+            parts.push(s.preview);
+        else if (s.label)
             parts.push(s.label);
         else if (s.topic)
             parts.push(s.topic);
         return parts.filter(Boolean).join(' · ');
     }
-    // Terminal or headless: prefer label, then topic
-    if (s.label)
-        return s.label;
-    if (s.topic)
-        return s.topic;
-    return '';
+    // Terminal or headless: prefer the live preview, then label, then topic.
+    return s.preview || s.label || s.topic || '';
+}
+/** Short human word for a session's activity (falls back to the coarse status). */
+function activityLabel(s) {
+    if (s.activity === 'waiting_input')
+        return 'waiting';
+    if (s.activity === 'working')
+        return 'working';
+    if (s.activity === 'idle')
+        return 'idle';
+    return s.status === 'input_required' ? 'waiting' : s.status;
+}
+/**
+ * Compact, colour-coded badges for the durable/awaiting signals. Text-only (no
+ * emoji, per repo convention): `plan` / `ask` / `perm` for why it's waiting,
+ * `PR#N`, `wt:slug`, `TICKET-123`.
+ */
+function signalBadges(s) {
+    const parts = [];
+    if (s.awaitingReason === 'plan_review')
+        parts.push(chalk.yellow('plan'));
+    else if (s.awaitingReason === 'question')
+        parts.push(chalk.yellow('ask'));
+    else if (s.awaitingReason === 'permission')
+        parts.push(chalk.yellow('perm'));
+    if (s.ticket)
+        parts.push(chalk.cyan(s.ticket.id));
+    if (s.pr)
+        parts.push(chalk.blue(`PR#${s.pr.number ?? '?'}`));
+    if (s.worktree)
+        parts.push(chalk.magenta(`wt:${s.worktree.slug}`));
+    return parts.join(' ');
 }
 /**
  * Render a single agent-session row inside an already-printed group header.
  * Indent is the leading whitespace (2 spaces for flat groups, 4 inside a
- * window sub-group).
+ * window sub-group). Leads with the 8-char session id (the address to read or
+ * resume it); status, badges, and the live preview fill the rest, sized to the
+ * terminal width so the row never wraps.
  */
 function printActiveRow(s, indent) {
-    const kindCol = colorAgent(s.kind)(padRight(truncate(s.kind, 8), 9));
-    const hostCol = chalk.gray(padRight(truncate(s.host ?? '-', 8), 9));
-    const statusCol = statusColor(s.status)(padRight(truncate(s.status, 7), 8));
-    const pidCol = chalk.yellow(padRight(s.pid ? String(s.pid) : '-', 7));
-    const desc = buildSessionDescription(s);
-    console.log(indent +
-        pidCol +
-        kindCol +
-        hostCol +
-        statusCol +
-        chalk.white(truncate(desc || '-', 50)));
+    const idCol = chalk.dim(padToWidth((s.sessionId?.slice(0, 8)) ?? '-', 9));
+    const kindCol = colorAgent(s.kind)(padToWidth(truncateToWidth(s.kind, 8), 9));
+    const hostCol = chalk.gray(padToWidth(truncateToWidth(s.host ?? '-', 8), 9));
+    const statusCol = statusColor(s.status)(padToWidth(truncateToWidth(activityLabel(s), 8), 9));
+    const badges = signalBadges(s);
+    const desc = buildSessionDescription(s) || '-';
+    // Fill the remaining width with the preview so nothing wraps under tmux/SSH.
+    const fixed = stringWidth(indent) + 9 + 9 + 9 + 9 + (badges ? stringWidth(badges) + 1 : 0);
+    const room = Math.max(12, terminalWidth() - fixed - 1);
+    const descCol = chalk.white(truncateToWidth(desc, room));
+    console.log(indent + idCol + kindCol + hostCol + statusCol + (badges ? badges + ' ' : '') + descCol);
 }
 /**
  * Short label for an IDE window. The slice key in live-terminals.json is
@@ -266,14 +301,21 @@ export function groupActiveSessions(sessions) {
     return { workspaces };
 }
 /** Render the unified active-session view. */
-async function renderActiveSessions(asJson) {
-    const sessions = await getActiveSessions();
+async function renderActiveSessions(asJson, waitingOnly = false) {
+    const all = await getActiveSessions();
+    // --waiting: only sessions blocked on the user. Exits non-zero when any are
+    // present so a supervising agent or hook can poll it as a gate.
+    const sessions = waitingOnly
+        ? all.filter(s => s.status === 'input_required')
+        : all;
     if (asJson) {
         process.stdout.write(JSON.stringify(sessions, null, 2) + '\n');
+        if (waitingOnly && sessions.length > 0)
+            process.exitCode = 1;
         return;
     }
     if (sessions.length === 0) {
-        console.log(chalk.gray('No active agent sessions.'));
+        console.log(chalk.gray(waitingOnly ? 'No sessions waiting on input.' : 'No active agent sessions.'));
         return;
     }
     const layout = groupActiveSessions(sessions);
@@ -312,6 +354,9 @@ async function renderActiveSessions(asJson) {
     if (queuedCount > 0)
         parts.push(`${queuedCount} queued`);
     console.log(chalk.gray(`\n${sessions.length} active (${parts.join(', ')}).`));
+    // Scriptable gate: a non-zero exit when anything is waiting on the user.
+    if (waitingOnly && sessions.length > 0)
+        process.exitCode = 1;
 }
 /** Main action handler for `agents sessions`. Routes to picker, table, or single-session render. */
 async function sessionsAction(query, options) {
@@ -326,7 +371,7 @@ async function sessionsAction(query, options) {
         return;
     }
     if (options.active) {
-        await renderActiveSessions(options.json === true);
+        await renderActiveSessions(options.json === true, options.waiting === true);
         return;
     }
     if (options.cloud) {
@@ -455,7 +500,9 @@ async function sessionsAction(query, options) {
             }
             return;
         }
-        if (isInteractiveTerminal()) {
+        // --tree is a printed grouped listing, not an interactive pick — render it
+        // directly even in a TTY.
+        if (isInteractiveTerminal() && !options.tree) {
             const message = pathFilter
                 ? `Search sessions (${path.basename(pathFilter)}):`
                 : formatSearchMessage(options);
@@ -468,7 +515,7 @@ async function sessionsAction(query, options) {
         }
         // Non-interactive fallback (piped output)
         const filtered = searchQuery ? filterSessionsByQuery(sessions, searchQuery) : sessions;
-        printSessionTable(filtered, hiddenCount);
+        printSessionTable(filtered, hiddenCount, options.tree === true);
     }
     catch (err) {
         tracker.stop();
@@ -487,22 +534,83 @@ function teamTag(session) {
     const parts = [origin.handle, origin.mode].filter(Boolean).join(' · ');
     return parts ? `[${parts}] ` : '[team] ';
 }
-function printSessionTable(sessions, hiddenCount = 0) {
-    for (const session of sessions) {
-        const agentColor = colorAgent(session.agent);
-        const when = formatRelativeTime(session.timestamp);
-        const project = session.project || '-';
-        const tag = teamTag(session);
-        const label = session.label;
-        const topic = tag ? `${tag}${session.topic ?? ''}` : session.topic;
-        const versionStr = session.version || '-';
-        console.log(chalk.white(padRight(session.shortId, 10)) +
-            agentColor(padRight(truncate(session.agent, 8), 9)) +
-            chalk.yellow(padRight(truncate(versionStr, 7), 8)) +
-            chalk.cyan(padRight(truncate(project, 14), 16)) +
-            renderTopicCell(label, topic, '', 48, 50) +
-            chalk.gray(when));
+/** Adapt a SessionMeta's persisted signals to the badge renderer's shape. */
+function metaSignals(s) {
+    return {
+        pr: s.prUrl ? { url: s.prUrl, number: s.prNumber } : undefined,
+        worktree: s.worktreeSlug ? { path: s.cwd ?? '', slug: s.worktreeSlug } : undefined,
+        ticket: s.ticketId ? { id: s.ticketId } : undefined,
+    };
+}
+/** One flat table row: shortId · agent · version · project · topic(+badges) · time. */
+function flatSessionRow(session) {
+    const agentColor = colorAgent(session.agent);
+    const when = formatRelativeTime(session.timestamp);
+    const project = session.project || '-';
+    const tag = teamTag(session);
+    const label = session.label;
+    const topic = tag ? `${tag}${session.topic ?? ''}` : session.topic;
+    const versionStr = session.version || '-';
+    const badges = signalBadges(metaSignals(session));
+    const badgeW = badges ? stringWidth(badges) + 1 : 0;
+    const topicW = Math.max(16, terminalWidth() - (10 + 9 + 8 + 16) - badgeW - stringWidth(when) - 1);
+    return (chalk.white(padToWidth(truncateToWidth(session.shortId, 9), 10)) +
+        agentColor(padToWidth(truncateToWidth(session.agent, 8), 9)) +
+        chalk.yellow(padToWidth(truncateToWidth(versionStr, 7), 8)) +
+        chalk.cyan(padToWidth(truncateToWidth(project, 14), 16)) +
+        renderTopicCell(label, topic, '', topicW, topicW) +
+        (badges ? badges + ' ' : '') +
+        chalk.gray(when));
+}
+/** One tree-mode row (grouped under a dir header): id · agent · badges · topic · time. No version/project column. */
+function treeSessionRow(session) {
+    const agentColor = colorAgent(session.agent);
+    const when = formatRelativeTime(session.timestamp);
+    const tag = teamTag(session);
+    const label = session.label;
+    const topic = (tag ? `${tag}${session.topic ?? ''}` : session.topic) || '-';
+    const badges = signalBadges(metaSignals(session));
+    const badgeW = badges ? stringWidth(badges) + 1 : 0;
+    const head = label ? `${label} · ${topic}` : topic;
+    const topicW = Math.max(12, terminalWidth() - (2 + 9 + 8) - badgeW - stringWidth(when) - 1);
+    return ('  ' +
+        chalk.dim(padToWidth(session.shortId, 9)) +
+        agentColor(padToWidth(truncateToWidth(session.agent, 7), 8)) +
+        (badges ? badges + ' ' : '') +
+        padToWidth(chalk.white(truncateToWidth(head, topicW)), topicW) +
+        ' ' + chalk.gray(when));
+}
+function printSessionTable(sessions, hiddenCount = 0, tree = false) {
+    if (tree) {
+        // Group by directory; drop the id/version columns from view. The short id
+        // stays as each row's leading handle (the address to read/resume it).
+        const byDir = new Map();
+        for (const s of sessions) {
+            const key = s.cwd || s.project || 'unknown';
+            (byDir.get(key) ?? byDir.set(key, []).get(key)).push(s);
+        }
+        const keys = [...byDir.keys()].sort((a, b) => {
+            const d = byDir.get(b).length - byDir.get(a).length;
+            return d !== 0 ? d : a.localeCompare(b);
+        });
+        let first = true;
+        for (const key of keys) {
+            if (!first)
+                console.log();
+            first = false;
+            const group = byDir.get(key);
+            console.log(`${chalk.cyan.bold(shortCwd(key))} ${chalk.gray(`(${group.length})`)}`);
+            for (const s of group)
+                console.log(treeSessionRow(s));
+        }
+        const dirWord = keys.length === 1 ? 'directory' : 'directories';
+        console.log(chalk.gray(`\n${sessions.length} session${sessions.length === 1 ? '' : 's'} across ${keys.length} ${dirWord}.`));
+        if (hiddenCount > 0)
+            console.log(chalk.gray(formatTeamHiddenFooter(hiddenCount)));
+        return;
     }
+    for (const session of sessions)
+        console.log(flatSessionRow(session));
     const countLine = `${sessions.length} session${sessions.length === 1 ? '' : 's'}.`;
     console.log(chalk.gray(`\n${countLine}`));
     if (hiddenCount > 0) {
@@ -608,8 +716,10 @@ function renderTopicCell(label, topic, query, visibleWidth, paddedWidth) {
     const tpc = (topic ?? '').trim();
     const sep = ' · ';
     const raw = lbl && tpc ? `${lbl}${sep}${tpc}` : (lbl || tpc);
-    const visible = truncate(raw, visibleWidth);
-    const padding = ' '.repeat(Math.max(0, paddedWidth - visible.length));
+    // Width-aware: measure/truncate/pad by display cells, not String.length, so
+    // ANSI escapes and wide (CJK/emoji) glyphs don't drift the column.
+    const visible = truncateToWidth(raw, visibleWidth);
+    const padding = ' '.repeat(Math.max(0, paddedWidth - stringWidth(visible)));
     const labelEnd = lbl ? Math.min(lbl.length, visible.length) : 0;
     let matchStart = -1, matchEnd = -1;
     const q = query.trim().toLowerCase();
@@ -753,6 +863,7 @@ export function buildResumeCommand(session) {
         case 'hermes':
         case 'grok':
         case 'kimi':
+        case 'droid':
             // Grok (and some others) sessions are captured artifacts, not resumable the same way.
             return null;
     }
@@ -1128,6 +1239,8 @@ export function registerSessionsCommands(program) {
         .option('--artifacts', 'List all files written or edited during a session')
         .option('--artifact <name>', 'Read a specific artifact by filename or path (outputs to stdout)')
         .option('--active', 'Show only sessions running right now across terminals, teams, cloud, and headless agents')
+        .option('--waiting', 'With --active: show only sessions waiting on your input (exits non-zero if any)')
+        .option('--tree', 'Group the listing by directory; drops the id/version columns for readability')
         .option('--cloud', 'Source sessions from Rush Cloud (captured runs) instead of local disk')
         .option('-H, --host <target...>', 'Run this query on remote machine(s) over SSH (host alias or user@host; repeatable)');
     setHelpSections(sessionsCmd, {

package/dist/commands/ssh.d.ts

@@ -0,0 +1,14 @@
+/**
+ * `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 type { Command } from 'commander';
+/** Register both `agents ssh` and `agents devices`. */
+export declare function registerSshCommands(program: Command): void;

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);
+}