@phnx-labs/agents-cli 1.20.62 → 1.20.64

package/dist/commands/sessions-import.js

@@ -0,0 +1,230 @@
+/**
+ * `agents sessions import <bundle|->` — restore an export bundle (RUSH-1711).
+ *
+ * The inverse of `sessions export`: read a bundle (file or stdin), validate it,
+ * and place each transcript where the cross-machine sync would — a mirror keyed
+ * by the session's ORIGIN machine (see bundle.ts / mirrorPath). Placement dedups
+ * byte-exact against what is already on disk and never clobbers this machine's
+ * own live sessions ("local always wins" falls out of the scanner's
+ * live-home-first dedup), so a re-import or an overlapping bundle is safe.
+ */
+import * as fs from 'fs';
+import chalk from 'chalk';
+import { loadR2Config } from '../lib/session/sync/config.js';
+import { resolveSyncEncKey } from '../lib/session/sync/transcript-crypto.js';
+import { parseBundle, planImport, writeImport, mergeRecords, makeHeader, } from '../lib/session/bundle.js';
+import { pullBundlesFromHosts } from '../lib/session/remote-bundle.js';
+import { setHelpSections } from '../lib/help.js';
+export function registerSessionsImportCommand(sessionsCmd) {
+    const cmd = sessionsCmd
+        .command('import [bundle]')
+        .description('Restore an export bundle (file, - for stdin, or --from-host <h>) into the local session store, deduping against what you already have.')
+        .option('--dry-run', 'Show what would be placed without writing anything')
+        .option('--overwrite', 'Replace local files that differ from the bundle (default: keep local)')
+        .option('--decrypt [key]', 'Decrypt an encrypted bundle (key optional if the r2.backups sync key is configured)')
+        .option('--from-host <target...>', 'Pull sessions live from remote peer(s) over SSH instead of a file (repeatable)');
+    setHelpSections(cmd, {
+        examples: `# Preview what a bundle would restore
+agents sessions import week.bundle --dry-run
+
+# Restore it
+agents sessions import week.bundle
+
+# Pull straight off another machine (one command, over SSH)
+agents sessions import --from-host yosemite-s1 --since 7d
+
+# Or the equivalent raw pipe
+agents ssh boxB 'agents sessions export --since 7d --stdout' | agents sessions import -`,
+        notes: `Sessions land under the cross-machine mirror keyed by their origin machine, so
+they show up in 'agents sessions' tagged with that machine and never overwrite
+your own local sessions. Byte-exact duplicates are skipped. --from-host reuses
+the same SSH transport as the cross-machine listing (no R2, no daemon).`,
+    });
+    cmd.action(async (bundlePath, options, command) => {
+        const g = command.optsWithGlobals();
+        await runImport(bundlePath, { ...options, agent: g.agent }, g, command);
+    });
+}
+async function runImport(bundlePath, options, g, command) {
+    // 1. Obtain the bundle — from remote peer(s), stdin, or a file.
+    let bundle;
+    if (options.fromHost && options.fromHost.length > 0) {
+        bundle = await pullForImport(options.fromHost, bundlePath, g, command);
+    }
+    else {
+        if (!bundlePath) {
+            process.stderr.write(chalk.red('Provide a bundle path, - for stdin, or --from-host <host>.\n'));
+            process.exit(1);
+        }
+        let text;
+        try {
+            text = bundlePath === '-' ? await readStdin() : fs.readFileSync(bundlePath, 'utf-8');
+        }
+        catch (err) {
+            process.stderr.write(chalk.red(`Cannot read bundle: ${err.message}\n`));
+            process.exit(1);
+        }
+        try {
+            bundle = parseBundle(text);
+        }
+        catch (err) {
+            process.stderr.write(chalk.red(`${err.message}\n`));
+            process.exit(1);
+        }
+    }
+    // 2. Optional agent filter.
+    if (options.agent) {
+        bundle = { header: bundle.header, records: bundle.records.filter(r => r.agent === options.agent) };
+        if (bundle.records.length === 0) {
+            process.stderr.write(chalk.yellow(`No records for agent '${options.agent}' in this bundle.\n`));
+            process.exit(1);
+        }
+    }
+    // 3. Resolve the decryption key if the bundle is encrypted.
+    const decryptKey = bundle.header.encrypted ? resolveDecryptKey(options.decrypt) : null;
+    // 4. Plan.
+    let plan;
+    try {
+        plan = planImport(bundle, { decryptKey });
+    }
+    catch (err) {
+        process.stderr.write(chalk.red(`${err.message}\n`));
+        process.exit(1);
+    }
+    if (options.dryRun) {
+        printDryRun(plan, bundle);
+        return;
+    }
+    // 5. Write.
+    const res = writeImport(plan, { overwrite: options.overwrite === true, decryptKey });
+    const parts = [];
+    if (res.placed)
+        parts.push(`${res.placed} placed`);
+    if (res.overwritten)
+        parts.push(`${res.overwritten} overwritten`);
+    if (res.skipped)
+        parts.push(`${res.skipped} duplicate${res.skipped === 1 ? '' : 's'} skipped`);
+    if (res.conflicts)
+        parts.push(chalk.yellow(`${res.conflicts} conflict${res.conflicts === 1 ? '' : 's'} kept local (use --overwrite)`));
+    if (res.unknown)
+        parts.push(chalk.yellow(`${res.unknown} unknown-agent skipped`));
+    process.stderr.write(chalk.green(`Imported: ${parts.join(', ') || 'nothing to do'}.\n`));
+}
+/** Drain all of stdin to a string. Works for pipes (non-seekable) and redirects
+ *  alike — unlike readFileSync(0), which fails on a pipe. */
+async function readStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(Buffer.from(chunk));
+    return Buffer.concat(chunks).toString('utf-8');
+}
+/**
+ * --from-host: run `agents sessions export …` on each peer over SSH and merge
+ * the streamed bundles into one for import. The optional positional acts as a
+ * remote selector (id/query); the parent selection flags (--since, -a, --all,
+ * -n) forward too.
+ */
+async function pullForImport(hosts, selector, g, command) {
+    const args = [];
+    if (selector && selector !== '-')
+        args.push(selector);
+    if (g.since)
+        args.push('--since', g.since);
+    const agent = command.optsWithGlobals().agent;
+    if (agent)
+        args.push('-a', agent);
+    if (g.all !== false)
+        args.push('--all');
+    if (command.parent?.getOptionValueSource?.('limit') === 'cli' && g.limit)
+        args.push('-n', String(g.limit));
+    const { bundles, errors } = await pullBundlesFromHosts(hosts, args);
+    for (const e of errors)
+        process.stderr.write(chalk.yellow(`  ${e}\n`));
+    const records = mergeRecords(bundles.map(b => b.records));
+    if (records.length === 0) {
+        process.stderr.write(chalk.red('No sessions pulled from the given host(s).\n'));
+        process.exit(1);
+    }
+    const header = makeHeader({
+        origin: hosts.join(','),
+        exportedAt: new Date().toISOString(),
+        encrypted: false,
+        redacted: bundles.some(b => b.header.redacted),
+        records,
+    });
+    return { header, records };
+}
+/**
+ * Decrypt-key resolution: an explicit `--decrypt <key>` (base64 or hex) wins;
+ * otherwise fall back to the fleet-shared R2_SYNC_ENC_KEY from the r2.backups
+ * bundle. Fails loudly when an encrypted bundle has no usable key.
+ */
+function resolveDecryptKey(decrypt) {
+    if (typeof decrypt === 'string' && decrypt.trim()) {
+        const raw = decrypt.trim();
+        const key = /^[0-9a-f]{64}$/i.test(raw) ? Buffer.from(raw, 'hex') : Buffer.from(raw, 'base64');
+        if (key.length !== 32) {
+            process.stderr.write(chalk.red(`--decrypt key must decode to 32 bytes (got ${key.length}).\n`));
+            process.exit(1);
+        }
+        return key;
+    }
+    try {
+        const key = resolveSyncEncKey(loadR2Config());
+        if (key)
+            return key;
+    }
+    catch {
+        // sync bundle not configured
+    }
+    process.stderr.write(chalk.red('This bundle is encrypted but no key is available. Pass --decrypt <key>, ' +
+        'or configure the r2.backups sync bundle so its shared key is used.\n'));
+    process.exit(1);
+}
+/** Print the dry-run table, grouped by session. Reads disk, writes nothing. */
+function printDryRun(plan, bundle) {
+    // Group file-level plan items by session for a readable table.
+    const bySession = new Map();
+    for (const item of plan) {
+        const key = `${item.record.agent}:${item.record.machine}:${item.record.sessionId}`;
+        let row = bySession.get(key);
+        if (!row)
+            bySession.set(key, (row = { agent: item.record.agent, machine: item.record.machine, sessionId: item.record.sessionId, statuses: new Set(), files: 0 }));
+        row.statuses.add(item.status);
+        row.files++;
+    }
+    process.stdout.write(chalk.bold(`Bundle: ${bundle.header.sessions} session(s), ${bundle.header.count} file(s), origin ${bundle.header.origin}${bundle.header.encrypted ? ', encrypted' : ''}\n\n`));
+    const header = `${pad('SESSION', 22)}${pad('AGENT', 10)}${pad('ORIGIN', 16)}${pad('FILES', 7)}STATUS`;
+    process.stdout.write(chalk.dim(header) + '\n');
+    for (const row of bySession.values()) {
+        const status = aggregateStatus(row.statuses);
+        process.stdout.write(pad(row.sessionId.slice(0, 20), 22) +
+            pad(row.agent, 10) +
+            pad(row.machine, 16) +
+            pad(String(row.files), 7) +
+            colorStatus(status) + '\n');
+    }
+    process.stdout.write(chalk.dim('\n(dry run — nothing was written)\n'));
+}
+function aggregateStatus(statuses) {
+    if (statuses.has('conflict'))
+        return 'conflict';
+    if (statuses.has('unknown'))
+        return 'unknown';
+    if (statuses.has('new'))
+        return statuses.has('dup') ? 'partial' : 'new';
+    return 'dup';
+}
+function colorStatus(status) {
+    switch (status) {
+        case 'new': return chalk.green(status);
+        case 'dup': return chalk.dim(status);
+        case 'partial': return chalk.cyan(status);
+        case 'conflict': return chalk.yellow(status);
+        case 'unknown': return chalk.red(status);
+        default: return status;
+    }
+}
+function pad(s, w) {
+    return s.length >= w ? s.slice(0, w - 1) + ' ' : s + ' '.repeat(w - s.length);
+}

package/dist/commands/sessions-sync.d.ts

@@ -10,6 +10,7 @@ interface SyncCmdOptions {
     enable?: boolean;
     disable?: boolean;
     status?: boolean;
+    setup?: boolean;
 }
 export declare function runSessionsSync(options: SyncCmdOptions): Promise<void>;
 export declare function registerSessionsSyncCommand(sessionsCmd: Command): void;

package/dist/commands/sessions-sync.js

@@ -26,6 +26,11 @@ export async function runSessionsSync(options) {
             chalk.dim(' — the daemon resumes on its next cycle. (Same as: agents beta enable session-sync)'));
         return;
     }
+    if (options.setup) {
+        const { promptAndProvisionSessionSync } = await import('./sync-provision.js');
+        await promptAndProvisionSessionSync({ explicit: true });
+        return;
+    }
     if (options.status) {
         const enabled = isBetaEnabled(SYNC_BETA);
         const configured = isSyncConfigured();
@@ -47,7 +52,8 @@ export async function runSessionsSync(options) {
             `  agents secrets add ${SYNC_BUNDLE} R2_ACCOUNT_ID\n` +
             `  agents secrets add ${SYNC_BUNDLE} R2_BUCKET_NAME\n` +
             `  agents secrets add ${SYNC_BUNDLE} R2_ACCESS_KEY_ID\n` +
-            `  agents secrets add ${SYNC_BUNDLE} R2_SECRET_ACCESS_KEY`);
+            `  agents secrets add ${SYNC_BUNDLE} R2_SECRET_ACCESS_KEY\n` +
+            chalk.dim('\nOr let a guided prompt mint the bundle for you: ') + chalk.cyan('agents sessions sync --setup'));
         process.exitCode = 1;
         return;
     }
@@ -68,6 +74,10 @@ export async function runSessionsSync(options) {
             console.log(chalk.green('synced') + ` ${result.machine}: ` + parts.join(', ') +
                 chalk.dim(` (${result.pushSkipped + result.pullSkipped} unchanged)`));
         }
+        if (!options.json && result.warnings.length > 0) {
+            for (const w of result.warnings)
+                console.error(chalk.yellow(`  warning: ${w}`));
+        }
         if (result.errors.length > 0) {
             for (const e of result.errors)
                 console.error(chalk.yellow(`  ! ${e}`));
@@ -82,14 +92,18 @@ export async function runSessionsSync(options) {
 export function registerSessionsSyncCommand(sessionsCmd) {
     const syncCmd = sessionsCmd
         .command('sync')
-        .description('Sync session transcripts across machines via R2 (CRDT merge). Claude and Codex.')
+        .description('Sync session transcripts across machines via R2 (CRDT merge). Claude, Codex, Droid, Grok, Kimi, and OpenCode.')
         .option('-v, --verbose', 'Log each pushed and pulled session')
         .option('--json', 'Output the sync result as JSON')
+        .option('--setup', 'Guided provisioning: mint the r2.backups bundle, verify connectivity, and enable sync')
         .option('--enable', 'Opt in to automatic background sync (beta; alias for: agents beta enable session-sync)')
         .option('--disable', 'Opt out of automatic background sync (alias for: agents beta disable session-sync)')
         .option('--status', 'Show whether automatic sync is opted-in (beta) and configured');
     setHelpSections(syncCmd, {
         examples: `
+      # Guided first-time setup (mint R2 bundle, verify, enable)
+      agents sessions sync --setup
+
       # One sync cycle (push local changes, pull + merge from other machines)
       agents sessions sync
 

package/dist/commands/sessions.js

@@ -44,6 +44,9 @@ import { registerSessionsResumeCommand } from './sessions-resume.js';
 import { registerGoCommand } from './go.js';
 import { registerFocusCommand } from './focus.js';
 import { registerSessionsInjectCommand } from './sessions-inject.js';
+import { registerSessionsExportCommand } from './sessions-export.js';
+import { registerSessionsImportCommand } from './sessions-import.js';
+import { runBrowserSessions } from '../lib/browser/sessions-list.js';
 const SESSION_AGENT_FILTER_HELP = `Filter by agent, e.g. claude, codex, claude@2.0.65`;
 /**
  * The prioritized harnesses that get a boolean shorthand flag (e.g. `--claude`
@@ -2065,7 +2068,8 @@ export function registerSessionsCommands(program) {
         .option('--no-live', 'Do not enrich the listing with live status/preview for running sessions')
         .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)')
-        .option('--device <target...>', 'Alias for --host (device alias from `agents devices`; repeatable)');
+        .option('--device <target...>', 'Alias for --host (device alias from `agents devices`; repeatable)')
+        .option('--browser', 'List browser-profile captures (screenshots, PDFs, recordings, downloads) instead of agent transcripts — alias of `agents browser sessions`');
     setHelpSections(sessionsCmd, {
         examples: `
       # Search prior sessions in this project by topic, file path, or command
@@ -2107,6 +2111,11 @@ export function registerSessionsCommands(program) {
     `,
     });
     sessionsCmd.action(async (query, options) => {
+        if (options.browser) {
+            // Alias for `agents browser sessions`: a profile positional narrows to one profile.
+            runBrowserSessions({ profile: query, json: options.json });
+            return;
+        }
         await sessionsAction(query, options);
     });
     registerSessionsTailCommand(sessionsCmd);
@@ -2115,6 +2124,8 @@ export function registerSessionsCommands(program) {
     registerGoCommand(sessionsCmd);
     registerFocusCommand(sessionsCmd);
     registerSessionsInjectCommand(sessionsCmd);
+    registerSessionsExportCommand(sessionsCmd);
+    registerSessionsImportCommand(sessionsCmd);
 }
 function formatNoSessionsMessage(showAll, project) {
     const projectQuery = project?.trim();

package/dist/commands/setup.js

@@ -119,6 +119,15 @@ export async function runSetup(program, options = {}) {
     if (dev.ok && dev.synced > 0) {
         console.log(chalk.gray(`Discovered ${dev.synced} device${dev.synced === 1 ? '' : 's'} on your tailnet (agents devices list).`));
     }
+    // Offer guided cross-machine session-sync provisioning (interactive, opt-in,
+    // and never blocking — any failure/decline falls through to the rest of setup).
+    try {
+        const { promptAndProvisionSessionSync } = await import('./sync-provision.js');
+        await promptAndProvisionSessionSync({ explicit: false });
+    }
+    catch (err) {
+        console.log(chalk.yellow(`Session-sync setup skipped: ${err.message}`));
+    }
     // Offer to import existing unmanaged installations
     if (unmanaged.length > 0 && isInteractiveTerminal()) {
         console.log(chalk.bold('\nFound existing installations:\n'));

package/dist/commands/ssh.js

@@ -25,6 +25,8 @@ import { clearPendingSentinel } from '../lib/devices/pending.js';
 import { isInteractiveTerminal, isPromptCancelled } from './utils.js';
 import { hostNameFor, renderSshConfig } from '../lib/devices/ssh-config.js';
 import { ASKPASS_BUNDLE_ENV, ASKPASS_KEY_ENV, buildSshInvocation, writeAskpassShim, } from '../lib/devices/connect.js';
+import { planFleetTargets, runFleet, skipLabel, upgradeCommand, } from '../lib/devices/fleet.js';
+import { fleetCapacity, fmtBytes, headroom, probeFleetStats, } from '../lib/devices/health.js';
 /** One-line summary of a device for `list`. `isSelf` marks the machine this
  * command is running on so it stands out from the rest of the tailnet. */
 function deviceSummary(d, isSelf = false) {
@@ -40,6 +42,80 @@ function deviceSummary(d, isSelf = false) {
     const here = isSelf ? chalk.cyan('  ← this machine') : '';
     return `${marker}${name} ${String(d.platform).padEnd(8)} ${(d.user ? d.user + '@' : '') + addr}  ${online}${reach}${here}`;
 }
+const HEADROOM_BADGE = {
+    idle: chalk.green('○ idle'),
+    light: chalk.green('● light'),
+    busy: chalk.yellow('● busy'),
+    loaded: chalk.red('● loaded'),
+    unknown: chalk.gray('· —'),
+};
+/** A right-aligned percentage cell, colored by severity (green/yellow/red). */
+function pctCell(v, width) {
+    if (v === undefined)
+        return chalk.gray('—'.padStart(width));
+    const s = `${Math.round(v)}%`.padStart(width);
+    if (v < 40)
+        return chalk.green(s);
+    if (v < 75)
+        return chalk.yellow(s);
+    return chalk.red(s);
+}
+/**
+ * Render the device list. When `statsMap` is provided, resource columns are
+ * appended — normalized load, memory, a headroom badge, and (in `full` mode)
+ * core count and free/total memory — so it's obvious which boxes have room.
+ * Without it (probe skipped) the classic reachability line is used. A fleet
+ * capacity summary is appended whenever stats were gathered.
+ */
+function renderDeviceTable(reg, names, self, statsMap, full = false) {
+    if (!statsMap)
+        return names.map((n) => deviceSummary(reg[n], n === self));
+    const lines = [];
+    const head = '  ' +
+        chalk.gray('device'.padEnd(16)) +
+        chalk.gray('platform'.padEnd(8)) +
+        ' ' +
+        (full ? chalk.gray('cores'.padStart(6)) : '') +
+        chalk.gray('load'.padStart(5)) +
+        chalk.gray('mem'.padStart(6)) +
+        (full ? '  ' + chalk.gray('free/total'.padEnd(12)) : '') +
+        '  ' +
+        chalk.gray('headroom');
+    lines.push(head);
+    for (const name of names) {
+        const d = reg[name];
+        const isSelf = name === self;
+        const marker = isSelf ? chalk.cyan('▸ ') : '  ';
+        const label = isSelf ? chalk.bold.cyan(name.padEnd(16)) : chalk.bold(name.padEnd(16));
+        const plat = String(d.platform).padEnd(8);
+        const offline = d.tailscale && !d.tailscale.online;
+        const stats = statsMap.get(name);
+        if (offline) {
+            lines.push(`${marker}${label}${plat} ${chalk.gray('offline')}`);
+            continue;
+        }
+        const relay = !isSelf && d.tailscale?.online && !d.tailscale.direct ? chalk.yellow(' relay') : '';
+        const cores = full ? chalk.gray(String(stats?.ncpu ?? '—').padStart(6)) : '';
+        const load = pctCell(stats?.loadPercent, 5);
+        const mem = pctCell(stats?.memPercent, 6);
+        const freeTotal = full
+            ? '  ' +
+                (stats?.reachable && stats.memTotalBytes
+                    ? `${fmtBytes(stats.memFreeBytes)}/${fmtBytes(stats.memTotalBytes)}`.padEnd(12)
+                    : chalk.gray('—'.padEnd(12)))
+            : '';
+        const badge = HEADROOM_BADGE[headroom(stats)];
+        const here = isSelf ? chalk.cyan('  ← this machine') : '';
+        lines.push(`${marker}${label}${plat} ${cores}${load}${mem}${freeTotal}  ${badge}${relay}${here}`);
+    }
+    // Fleet capacity summary — total cores + how much RAM is free right now.
+    const cap = fleetCapacity(statsMap.values());
+    if (cap.reachable > 0) {
+        const freePct = cap.memTotalBytes > 0 ? Math.round((cap.memFreeBytes / cap.memTotalBytes) * 100) : 0;
+        lines.push(chalk.gray(`  Fleet capacity: ${cap.cores} cores · ${fmtBytes(cap.memFreeBytes)} free / ${fmtBytes(cap.memTotalBytes)} RAM (${freePct}% free) across ${cap.reachable} reachable device${cap.reachable === 1 ? '' : 's'}`));
+    }
+    return lines;
+}
 /** Resolve a device or exit with a clear error. */
 async function mustGetDevice(name) {
     const d = await getDevice(name);
@@ -118,11 +194,34 @@ async function runInteractiveDeviceSync() {
     ].filter(Boolean);
     console.log(parts.join(chalk.gray(' · ')));
 }
-/** Register the `agents devices` command tree. */
+/** Print a per-device result table for fleet update/run. */
+function printFleetResults(results) {
+    const nameW = Math.max(8, ...results.map((r) => r.name.length));
+    console.log(chalk.bold('DEVICE'.padEnd(nameW)) + '  ' +
+        chalk.bold('STATUS'.padEnd(8)) + '  ' +
+        chalk.bold('DETAIL'));
+    for (const r of results) {
+        const status = r.status === 'ok' ? chalk.green('ok'.padEnd(8)) :
+            r.status === 'skipped' ? chalk.gray('skipped'.padEnd(8)) :
+                chalk.red('failed'.padEnd(8));
+        const detail = r.status === 'skipped' ? chalk.gray(skipLabel(r.reason)) :
+            r.status === 'failed' ? chalk.red(r.detail || `exit ${r.code ?? '?'}`) :
+                chalk.gray(r.code === 0 ? 'exit 0' : '');
+        console.log(`${r.name.padEnd(nameW)}  ${status}  ${detail}`);
+    }
+    const ok = results.filter((r) => r.status === 'ok').length;
+    const failed = results.filter((r) => r.status === 'failed').length;
+    const skipped = results.filter((r) => r.status === 'skipped').length;
+    console.log(chalk.gray(`${ok} ok · ${failed} failed · ${skipped} skipped`));
+    if (failed > 0)
+        process.exitCode = 1;
+}
+/** Register the `agents devices` command tree (also aliased as `fleet`). */
 function registerDevicesCommands(program) {
     const devicesCmd = program
         .command('devices')
-        .description('Registry of SSH device profiles (platform, user, address, auth), self-populated from Tailscale.')
+        .alias('fleet')
+        .description('Registry of SSH device profiles (platform, user, address, auth), self-populated from Tailscale. Alias: fleet.')
         .addHelpText('after', `
 Typical workflow:
   agents devices sync            # curate: pick which tailscale nodes to keep (TTY)
@@ -131,6 +230,10 @@ Typical workflow:
   agents devices ignore ipad165  # dismiss a node so it's never re-suggested
   agents devices set win-mini --auth password --bundle muqsit
   agents devices render --write  # write ~/.ssh/config.d/agents include
+  agents fleet update            # roll out latest agents-cli to every online device
+  agents fleet run uname -a      # run a command on every online device
+
+\`agents fleet\` is an alias for \`agents devices\` — same subcommands.
 `);
     devicesCmd
         .command('sync')
@@ -202,12 +305,15 @@ Typical workflow:
     devicesCmd
         .command('list')
         .alias('ls')
-        .description('List registered devices with platform, address, and reachability.')
+        .description('List registered devices with platform, address, reachability, and live resource headroom.')
         .option('--json', 'output the registry as a JSON array (for scripts and hooks)')
+        .option('--no-stats', 'skip the live resource probe (instant; names/addresses only)')
+        .option('-f, --full', 'full mode: add per-device core count and free/total memory')
         .action(async (opts) => {
         const reg = await loadDevices();
         const names = Object.keys(reg).sort();
         if (opts.json) {
+            // Registry-only, always fast — the Factory extension polls this path.
             process.stdout.write(JSON.stringify(names.map((n) => reg[n]), null, 2) + '\n');
             return;
         }
@@ -216,9 +322,26 @@ Typical workflow:
             return;
         }
         const self = machineId();
+        let statsMap;
+        if (opts.stats !== false) {
+            // Probe only reachable devices, in parallel, bounded by the per-probe
+            // timeout — a slow box degrades to "—", it never hangs the table.
+            const probeable = planFleetTargets(reg)
+                .filter((t) => !t.skip)
+                .map((t) => t.device);
+            const spinner = isInteractiveTerminal()
+                ? ora(`Probing ${probeable.length} device${probeable.length === 1 ? '' : 's'}…`).start()
+                : undefined;
+            try {
+                statsMap = await probeFleetStats(probeable, { selfName: self });
+            }
+            finally {
+                spinner?.stop();
+            }
+        }
         console.log(chalk.bold(`Devices (${names.length})`));
-        for (const name of names)
-            console.log(deviceSummary(reg[name], name === self));
+        for (const line of renderDeviceTable(reg, names, self, statsMap, opts.full))
+            console.log(line);
     });
     devicesCmd
         .command('show <name>')
@@ -307,6 +430,48 @@ Typical workflow:
         console.log(chalk.green(`Wrote ${file}`));
         console.log(chalk.gray('Add this to ~/.ssh/config (once):  Include config.d/agents'));
     });
+    devicesCmd
+        .command('update')
+        .description('Roll out agents-cli to every online registered device (`agents upgrade --yes` on each). Offline devices are skipped.')
+        .argument('[version]', 'Target version or dist-tag (default: latest)')
+        .action(async (version) => {
+        let cmd;
+        try {
+            cmd = upgradeCommand(version);
+        }
+        catch (err) {
+            console.error(chalk.red(err?.message ?? err));
+            process.exit(1);
+        }
+        const reg = await loadDevices();
+        const targets = planFleetTargets(reg);
+        if (targets.length === 0) {
+            console.log(chalk.gray("No devices. Run 'agents devices sync' first."));
+            return;
+        }
+        console.log(chalk.gray(`Running \`${cmd.join(' ')}\` on ${targets.filter((t) => !t.skip).length} online device(s)…`));
+        const results = runFleet(targets, cmd);
+        printFleetResults(results);
+    });
+    devicesCmd
+        .command('run <cmd...>')
+        .description('Run a command on every online registered device. Offline devices are skipped. Alias surface: agents fleet run …')
+        .allowUnknownOption()
+        .action(async (cmd) => {
+        if (!cmd.length) {
+            console.error(chalk.red('Usage: agents fleet run <cmd...>'));
+            process.exit(1);
+        }
+        const reg = await loadDevices();
+        const targets = planFleetTargets(reg);
+        if (targets.length === 0) {
+            console.log(chalk.gray("No devices. Run 'agents devices sync' first."));
+            return;
+        }
+        console.log(chalk.gray(`Running \`${cmd.join(' ')}\` on ${targets.filter((t) => !t.skip).length} online device(s)…`));
+        const results = runFleet(targets, cmd);
+        printFleetResults(results);
+    });
 }
 /** Register the `agents ssh` smart wrapper. */
 function registerSshWrapper(program) {

package/dist/commands/sync-provision.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Interactive provisioning flow for cross-machine session sync. Collects R2
+ * credentials, writes the `r2.backups` bundle (via the pure lib helper), probes
+ * connectivity, and opts the machine into the `session-sync` beta. Shared by
+ * `agents setup` (offered, opt-in) and `agents sessions sync --setup` (explicit).
+ *
+ * The prompt/UI lives here in the command layer; the credential-writing and
+ * connectivity logic is the pure, unit-tested `lib/session/sync/provision.ts`.
+ */
+export interface ProvisionFlowOptions {
+    /**
+     * True when invoked explicitly (`agents sessions sync --setup`): we go straight
+     * into provisioning. False when offered inside `agents setup`: we ask first,
+     * default to No, and silently skip when already configured.
+     */
+    explicit?: boolean;
+}
+/**
+ * Run the guided session-sync setup. Never throws for expected outcomes
+ * (non-interactive shell, user declines, cancels, or a failed probe) — returns
+ * quietly so a first-run `agents setup` is never blocked by the optional step.
+ */
+export declare function promptAndProvisionSessionSync(opts?: ProvisionFlowOptions): Promise<void>;