@phnx-labs/agents-cli 1.20.63 → 1.20.64

package/dist/commands/sessions-export.js

@@ -0,0 +1,279 @@
+/**
+ * `agents sessions export` — bundle N selected sessions into a portable,
+ * self-describing archive (RUSH-1710).
+ *
+ * The successor to background R2/CRDT sync for the durable-archive / hand-off
+ * case: instead of an always-on merge daemon, the user explicitly bundles the
+ * sessions they want to carry to an offline box or keep as an archive. The
+ * bundle format + placement live in ../lib/session/bundle.ts; this command owns
+ * only the SELECTION (which sessions) and the OUTPUT (file or stdout).
+ *
+ * Selection flags (`--since`, `-n/--limit`, `--all`, `-a/--agent`,
+ * `--no-redact`) are inherited from the parent `sessions` command and read via
+ * optsWithGlobals(), so they never shadow the parent's parsing; this command
+ * adds only the export-specific flags (`-o/--output`, `--stdout`, `--encrypt`).
+ *
+ * Rendered markdown/json of a single session is already served by
+ * `agents sessions <id> --markdown|--json`; export is specifically the portable,
+ * re-importable BUNDLE, so it does not re-expose those render formats.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import chalk from 'chalk';
+import { discoverSessions, resolveSessionById } from '../lib/session/discover.js';
+import { filterSessionsByQuery, parseAgentFilter } from './sessions.js';
+import { listLocalTranscripts, SYNC_AGENTS } from '../lib/session/sync/agents.js';
+import { machineId } from '../lib/machine-id.js';
+import { getHistoryDir } from '../lib/state.js';
+import { loadR2Config } from '../lib/session/sync/config.js';
+import { resolveSyncEncKey, generateSyncEncKey } from '../lib/session/sync/transcript-crypto.js';
+import { buildRecord, makeHeader, mergeRecords, serializeBundle, specForAgent, } from '../lib/session/bundle.js';
+import { pullBundlesFromHosts } from '../lib/session/remote-bundle.js';
+import { setHelpSections } from '../lib/help.js';
+/** Default cap when exporting a scope (not explicit ids) and the user gave no -n. */
+const DEFAULT_LIMIT = 500;
+export function registerSessionsExportCommand(sessionsCmd) {
+    const cmd = sessionsCmd
+        .command('export [selectors...]')
+        .description('Bundle sessions (by id, query, or the parent selection flags like --since/-a) into a portable archive.')
+        .option('-o, --output <path>', 'Write the bundle to this file')
+        .option('--stdout', 'Write the bundle to stdout (for piping into `sessions import -`)')
+        .option('--encrypt', 'Seal each transcript body with AES-256-GCM before writing');
+    setHelpSections(cmd, {
+        examples: `# Bundle the last week of sessions to a file
+agents sessions export --since 7d -o week.bundle
+
+# Bundle two specific sessions
+agents sessions export 4f8a2b1c 9d3e7a55 -o pair.bundle
+
+# Encrypt + pipe straight into another machine over SSH
+agents sessions export --since 7d --stdout --encrypt | agents ssh boxB 'agents sessions import - --decrypt <key>'`,
+        notes: `Selection uses the same flags as 'agents sessions' (--since, -n/--limit, --all,
+-a/--agent, --no-redact). Bundles are self-describing NDJSON: a header line + one
+line per transcript file. Secrets are redacted by default. Dir-shaped sessions
+(Kimi) carry all their files. Restore with 'agents sessions import'.`,
+    });
+    cmd.action(async (selectors, _options, command) => {
+        await runExport(selectors, command);
+    });
+}
+async function runExport(selectors, command) {
+    const g = command.optsWithGlobals();
+    // --host: export sessions that live on remote peer(s) — run export there and
+    // stream the bundle back over the existing SSH transport (RUSH-1712).
+    if (g.host && g.host.length > 0) {
+        await runRemoteExport(g, selectors, command);
+        return;
+    }
+    const explicitLimit = command.parent?.getOptionValueSource?.('limit') === 'cli';
+    const limit = explicitLimit ? Math.max(1, parseInt(String(g.limit), 10) || DEFAULT_LIMIT) : DEFAULT_LIMIT;
+    const agentFilter = parseAgentFilter(resolveAgentShorthand(g));
+    // 1. Discover candidate sessions in scope.
+    const metas = await discoverSessions({
+        all: g.all !== false,
+        agent: agentFilter.agent ?? undefined,
+        since: g.since,
+        limit,
+    });
+    // 2. Narrow to the selection (ids > query > everything-in-scope).
+    const selected = selectSessions(metas, selectors);
+    if (selected.length === 0) {
+        process.stderr.write(chalk.yellow('No sessions matched the selection.\n'));
+        process.exit(1);
+    }
+    if (!selectors.length && selected.length >= limit) {
+        process.stderr.write(chalk.yellow(`Note: capped at ${limit} sessions. Raise -n to bundle more.\n`));
+    }
+    // 3. Resolve each selected session to its on-disk file(s).
+    const index = buildLocalIndex();
+    const self = machineId();
+    const files = [];
+    const skippedAgents = new Set();
+    for (const meta of selected) {
+        const spec = specForAgent(meta.agent);
+        if (!spec) {
+            skippedAgents.add(meta.agent);
+            continue;
+        }
+        const machine = meta.machine || self;
+        const lt = index.get(`${meta.agent}:${meta.id}`);
+        if (lt) {
+            for (const f of lt.files) {
+                files.push({ agent: meta.agent, machine, sessionId: meta.id, relKey: f.relKey, absPath: f.absPath, label: meta.label });
+            }
+        }
+        else if (meta.filePath && fs.existsSync(meta.filePath)) {
+            // Not in the live-home index (e.g. a mirror of another machine): fall back
+            // to the single discovered file, deriving its subdir-relative key.
+            const relKey = relKeyFromPath(meta.filePath, meta.agent, machine, spec.subdir);
+            files.push({ agent: meta.agent, machine, sessionId: meta.id, relKey, absPath: meta.filePath, label: meta.label });
+        }
+    }
+    if (skippedAgents.size > 0) {
+        process.stderr.write(chalk.yellow(`Skipped agents with no portable format: ${[...skippedAgents].sort().join(', ')}.\n`));
+    }
+    if (files.length === 0) {
+        process.stderr.write(chalk.red('Selected sessions have no exportable transcript files.\n'));
+        process.exit(1);
+    }
+    // 4. Resolve encryption key (opt-in) + redaction (default on via parent --no-redact).
+    const encryptKey = g.encrypt ? resolveExportKey() : null;
+    const redact = g.redact !== false;
+    // 5. Build records + header.
+    const records = [];
+    for (const f of files) {
+        try {
+            records.push(buildRecord(f, { redact, encryptKey }));
+        }
+        catch (err) {
+            process.stderr.write(chalk.yellow(`Skipped ${f.agent}/${f.sessionId} (${f.relKey}): ${err.message}\n`));
+        }
+    }
+    if (records.length === 0) {
+        process.stderr.write(chalk.red('Nothing to export after reading files.\n'));
+        process.exit(1);
+    }
+    const header = makeHeader({
+        origin: self,
+        exportedAt: new Date().toISOString(),
+        encrypted: encryptKey !== null,
+        redacted: redact,
+        records,
+    });
+    emitBundle(header, records, g);
+}
+/**
+ * --host path: run `agents sessions export …` on each peer over SSH, stream the
+ * bundles back, merge (dedup by origin machine) and emit one local bundle.
+ * Encryption is not combined with a remote pull (each peer would seal under its
+ * own key); the SSH transport already encrypts the stream in transit.
+ */
+async function runRemoteExport(g, selectors, command) {
+    if (g.encrypt) {
+        process.stderr.write(chalk.yellow('Note: --encrypt is ignored with --host (the SSH stream is already encrypted). Encrypt a local bundle instead.\n'));
+    }
+    const { bundles, errors } = await pullBundlesFromHosts(g.host, forwardExportArgs(g, selectors, command));
+    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: g.host.join(','),
+        exportedAt: new Date().toISOString(),
+        encrypted: false,
+        redacted: g.redact !== false,
+        records,
+    });
+    emitBundle(header, records, g);
+}
+/** Reconstruct the export flags to forward to a peer's own `sessions export`. */
+function forwardExportArgs(g, selectors, command) {
+    const args = [...selectors];
+    if (g.since)
+        args.push('--since', g.since);
+    const agent = resolveAgentShorthand(g);
+    if (agent)
+        args.push('-a', agent);
+    if (g.all !== false)
+        args.push('--all');
+    if (g.redact === false)
+        args.push('--no-redact');
+    if (command.parent?.getOptionValueSource?.('limit') === 'cli' && g.limit)
+        args.push('-n', String(g.limit));
+    return args;
+}
+/** Write the assembled bundle to stdout or a file. */
+function emitBundle(header, records, g) {
+    const wire = serializeBundle(header, records);
+    if (g.stdout) {
+        process.stdout.write(wire);
+        return;
+    }
+    const outPath = g.output || defaultBundlePath();
+    fs.writeFileSync(outPath, wire, 'utf-8');
+    process.stderr.write(chalk.green(`Exported ${header.sessions} session${header.sessions === 1 ? '' : 's'} ` +
+        `(${header.count} file${header.count === 1 ? '' : 's'}${header.encrypted ? ', encrypted' : ''}${header.redacted ? ', redacted' : ''}) ` +
+        `→ ${outPath}\n`));
+}
+/** Map the parent's agent shorthands (--claude, --codex, …) or -a/--agent to a filter string. */
+function resolveAgentShorthand(g) {
+    if (g.agent)
+        return g.agent;
+    if (g.claude)
+        return 'claude';
+    if (g.codex)
+        return 'codex';
+    if (g.kimi)
+        return 'kimi';
+    if (g.grok)
+        return 'grok';
+    if (g.opencode)
+        return 'opencode';
+    if (g.antigravity)
+        return 'antigravity';
+    return undefined;
+}
+/** ids > query > everything-in-scope. */
+function selectSessions(metas, selectors) {
+    if (selectors.length === 0)
+        return metas;
+    const byId = [];
+    const unmatched = [];
+    for (const sel of selectors) {
+        const hits = resolveSessionById(metas, sel);
+        if (hits.length > 0)
+            byId.push(...hits);
+        else
+            unmatched.push(sel);
+    }
+    if (byId.length > 0 && unmatched.length === 0) {
+        const seen = new Set();
+        return byId.filter(s => (seen.has(s.id) ? false : (seen.add(s.id), true)));
+    }
+    // Any selector that isn't an id → treat the whole thing as a text query.
+    return filterSessionsByQuery(metas, selectors.join(' '));
+}
+/** Build `${agent}:${sessionId}` → LocalTranscript across every sync agent (live home only). */
+function buildLocalIndex() {
+    const index = new Map();
+    for (const spec of SYNC_AGENTS) {
+        for (const lt of listLocalTranscripts(spec)) {
+            index.set(`${spec.id}:${lt.sessionId}`, lt);
+        }
+    }
+    return index;
+}
+/** Derive the subdir-relative key for a mirror file path, else fall back to the basename. */
+function relKeyFromPath(filePath, agent, machine, subdir) {
+    const prefix = path.join(getHistoryDir(), 'backups', agent, machine, subdir) + path.sep;
+    if (filePath.startsWith(prefix))
+        return filePath.slice(prefix.length);
+    return path.basename(filePath);
+}
+/**
+ * Resolve the AES key for --encrypt: prefer the fleet-shared R2_SYNC_ENC_KEY (so
+ * any machine on the sync bundle can decrypt), else mint an ephemeral key and
+ * print it once — it is NOT stored in the bundle.
+ */
+function resolveExportKey() {
+    try {
+        const key = resolveSyncEncKey(loadR2Config());
+        if (key)
+            return key;
+    }
+    catch {
+        // sync bundle not configured — fall through to an ephemeral key
+    }
+    const b64 = generateSyncEncKey();
+    process.stderr.write(chalk.yellow(`Bundle encrypted with a fresh key (not in the bundle). Decrypt with:\n` +
+        `  agents sessions import <bundle> --decrypt ${b64}\n`));
+    return Buffer.from(b64, 'base64');
+}
+/** Default output file when neither -o nor --stdout is given. */
+function defaultBundlePath() {
+    const stamp = new Date().toISOString().replace(/[:.]/g, '-').replace('T', '_').slice(0, 19);
+    return path.join(process.cwd(), `agents-sessions-${stamp}.bundle`);
+}

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

@@ -0,0 +1,2 @@
+import type { Command } from 'commander';
+export declare function registerSessionsImportCommand(sessionsCmd: Command): void;

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.js

@@ -44,6 +44,8 @@ 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`;
 /**
@@ -2122,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/ssh.js

@@ -26,6 +26,7 @@ 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) {
@@ -41,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);
@@ -230,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;
         }
@@ -244,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>')

package/dist/commands/usage.d.ts

@@ -4,6 +4,8 @@
  * Lists every installed agent with the best available usage snapshot:
  *   - claude: live OAuth API call (cached for 2 minutes)
  *   - codex:  parsed from latest session log's rate_limits event
+ *   - kimi:   live Kimi Code /usages API call (cached for 2 minutes)
+ *   - droid:  live Factory billing/limits API call (cached for 2 minutes)
  *   - others: marked as "not exposed by CLI" (Gemini, OpenCode, Cursor, etc.
  *     don't publish per-account usage today)
  */