@phnx-labs/agents-cli 1.22.34 → 1.22.37

package/dist/commands/secrets.js

@@ -25,7 +25,7 @@ import { getKeychainToken, hasKeychainToken, secretsKeychainItem, setKeychainTok
 import { assertOpAvailable, createPasswordItem, deleteItemByTitle, extractSecrets, itemExistsByTitle, listItems, listVaults, } from '../lib/onepassword.js';
 import { GLOBAL_HARNESS } from '../lib/secrets/scope.js';
 import { createSecretLease, selectLeasedEnv } from '../lib/secrets/lease.js';
-import { secretsHoldMs, secretsAgentDurable, agentLoad, agentLock, agentPing, agentStatus, ensureAgentRunning, runAgentLoadFromStdin, runSecretsAgent, uninstallSecretsAgentService, } from '../lib/secrets/agent.js';
+import { secretsHoldMs, secretsAgentDurable, agentLoad, agentLock, agentPing, agentStatus, ensureAgentRunning, runAgentLoadFromStdin, runSecretsAgent, uninstallSecretsAgentService, isSecretsBrokerEnabled, } from '../lib/secrets/agent.js';
 import { saveSession, deleteBundleSessions, deleteAllSessions } from '../lib/secrets/session-store.js';
 import { getCliVersionFresh } from '../lib/version.js';
 import { readMeta } from '../lib/state.js';
@@ -432,8 +432,14 @@ export function importBundleFromFile(filePath, passphrase) {
  * session (run sequentially) so a remote Touch-ID / passphrase prompt can
  * surface (e.g. `view --reveal`); otherwise hosts are queried in parallel.
  * Exits non-zero if any host fails.
+ *
+ * `secret` marks a browse that streams plaintext VALUES back (`view --reveal`)
+ * rather than only key names (`list`, masked `view`). A secret browse rides the
+ * credential-transport posture — managed host-key pinning + no multiplex — so a
+ * revealed value can't be intercepted on an unpinned/multiplexed connection
+ * (RUSH-2527). It composes with `tty`: `view --reveal` at a terminal is both.
  */
-async function browseRemote(targets, args, tty) {
+async function browseRemote(targets, args, tty, secret = false) {
     const multi = targets.length > 1;
     let failures = 0;
     const render = (name, res) => {
@@ -455,12 +461,12 @@ async function browseRemote(targets, args, tty) {
     if (tty) {
         for (const t of targets) {
             const target = await resolveHostSshTarget(t);
-            render(t, remoteSecretsRaw(target, args, { tty: true, osLookupName: t }));
+            render(t, remoteSecretsRaw(target, args, { tty: true, osLookupName: t, secret }));
         }
     }
     else {
         const resolved = await Promise.all(targets.map(async (t) => ({ name: t, target: await resolveHostSshTarget(t) })));
-        const results = resolved.map(({ name, target }) => remoteSecretsRaw(target, args, { osLookupName: name }));
+        const results = resolved.map(({ name, target }) => remoteSecretsRaw(target, args, { osLookupName: name, secret }));
         targets.forEach((t, i) => render(t, results[i]));
     }
     if (failures > 0)
@@ -1241,7 +1247,10 @@ export function registerSecretsCommands(program) {
                 // (and the remote's "--reveal in a non-TTY needs --plaintext" gate is
                 // satisfied) — only when this side is itself interactive.
                 const tty = Boolean(opts.reveal) && Boolean(process.stdin.isTTY) && Boolean(process.stdout.isTTY);
-                await browseRemote(targets, args, tty);
+                // `--reveal` streams the plaintext value back over ssh stdout — a
+                // secret-bearing read that must pin the host key and not multiplex,
+                // whether it runs on the interactive (tty) or `--plaintext` non-tty path.
+                await browseRemote(targets, args, tty, Boolean(opts.reveal));
                 return;
             }
             const resolvedName = name ?? (await pickBundleName('view'));
@@ -1875,7 +1884,18 @@ Examples:
             delete bundle.vars[resolvedKey];
             writeBundle(bundle);
             if (willPurge) {
-                const item = secretsKeychainItem(resolvedBundleName, raw.slice('keychain:'.length));
+                const shortId = raw.slice('keychain:'.length);
+                // Purge only the removed key's own storage slot. A corrupted ref
+                // (e.g. a stale manifest write-back leaving OPENAI_API_KEY pointing
+                // at keychain:LINEAR_API_KEY) must never destroy another key's item —
+                // the ref is gone from the bundle either way; the stray item is the
+                // recoverable side of that trade.
+                if (shortId !== resolvedKey) {
+                    console.log(chalk.yellow(`Removed ${resolvedBundleName}.${resolvedKey}, but its ref pointed at '${shortId}' — ` +
+                        `left that keychain item untouched (it belongs to a different key).`));
+                    return;
+                }
+                const item = secretsKeychainItem(resolvedBundleName, shortId);
                 const removed = bundleItemStore(bundle.backend).delete(item);
                 if (removed) {
                     const where = bundle.backend === 'file'
@@ -2157,7 +2177,16 @@ Examples:
                 const remotePassphrase = remoteBackend === 'file' ? (process.env.AGENTS_SECRETS_PASSPHRASE ?? '') : '';
                 // Resolve ONCE for N hosts — reading a bundle can prompt, and doing it
                 // per host would prompt per host.
-                const resolvedForPush = resolveBundleForPush(resolvedBundleName, 'ssh export');
+                //
+                // Same predicate as `view --reveal` / `exec`: a human at a TTY gets the
+                // Touch ID sheet, an agent launch or a piped/CI run stays broker-only
+                // and fails fast with the `agents secrets unlock` hint. Requiring a
+                // prior unlock for an interactive push was an inconsistency, not a
+                // boundary — this read is strictly less exposed than `view --reveal`,
+                // which already prompts.
+                const resolvedForPush = resolveBundleForPush(resolvedBundleName, 'ssh export', {
+                    agentOnly: isHeadlessSecretsContext() || !isInteractiveTerminal(),
+                });
                 const keyCount = resolvedForPush.keyCount;
                 let failures = 0;
                 for (const host of hosts) {
@@ -2561,6 +2590,10 @@ Examples:
             process.exit(1);
         }
         const expiresAt = Date.now() + ttlMs;
+        if (!isSecretsBrokerEnabled()) {
+            console.error(chalk.red('Secrets broker is disabled — re-enable with \'agents daemon services enable secrets-broker\'.'));
+            process.exit(1);
+        }
         if (!(await ensureAgentRunning())) {
             console.error(chalk.red('Could not start the secrets broker.'));
             process.exit(1);
@@ -2582,7 +2615,10 @@ Examples:
         for (const name of targets) {
             try {
                 // noAgent: read the real keychain (one Touch ID) rather than the
-                // agent we're about to populate.
+                // agent we're about to populate. Snapshot time is captured BEFORE the
+                // read so a concurrent eviction always beats this load (broker
+                // tombstones reject snapshots that predate an eviction).
+                const snapshotAt = Date.now();
                 const { bundle, env } = readAndResolveBundleEnv(name, {
                     noAgent: true,
                     caller: 'unlock secrets',
@@ -2600,7 +2636,7 @@ Examples:
                 // held exactly as before. scopeHeldEnv fails closed on an unknown key.
                 const { heldEnv, lease } = scopeHeldEnv({ bundle: name, env, keys: opts.keys ?? null, ttlMs, harness, sleepPersist: durable });
                 const heldExpiresAt = lease ? lease.expiresAt : expiresAt;
-                if (await agentLoad(name, bundle, heldEnv, ttlMs, harness, lease)) {
+                if (await agentLoad(name, bundle, heldEnv, ttlMs, harness, lease, snapshotAt)) {
                     loaded++;
                     // Persist a durable session snapshot so the unlock survives a daemon
                     // restart / upgrade (and sleep too, with --durable). session-store.ts.
@@ -2675,6 +2711,10 @@ Examples:
             console.log(chalk.gray('secrets-agent is macOS-only.'));
             return;
         }
+        if (!isSecretsBrokerEnabled()) {
+            console.log(chalk.yellow('broker: disabled — re-enable with \'agents daemon services enable secrets-broker\''));
+            return;
+        }
         const ping = await agentPing();
         const brokerUp = ping.reachable;
         console.log(chalk.gray('broker: ') +
@@ -2800,6 +2840,9 @@ Examples:
             console.error(chalk.red('The secrets broker is macOS-only.'));
             process.exit(1);
         }
+        if (!isSecretsBrokerEnabled()) {
+            console.error(chalk.yellow('Secrets broker is disabled — the daemon will start but will not host the broker. Re-enable with \'agents daemon services enable secrets-broker\'.'));
+        }
         process.stdout.write(chalk.gray('Starting the daemon…\n'));
         ensureDaemonStarted();
         // The daemon hosts the broker socket-first; wait briefly for it to answer.

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

@@ -1,5 +1,52 @@
 import type { Command } from 'commander';
 import type { SessionMeta } from '../lib/session/types.js';
+import { type BundleHeader, type BundleRecord } from '../lib/session/bundle.js';
 export declare function registerSessionsExportCommand(sessionsCmd: Command): void;
+interface GlobalSelection {
+    since?: string;
+    limit?: string;
+    all?: boolean;
+    agent?: string;
+    redact?: boolean;
+    encrypt?: boolean;
+    toR2?: boolean;
+    output?: string;
+    stdout?: boolean;
+    host?: string[];
+    claude?: boolean;
+    codex?: boolean;
+    kimi?: boolean;
+    grok?: boolean;
+    opencode?: boolean;
+    antigravity?: boolean;
+}
+/**
+ * Upload each record to R2 as its own self-describing one-record bundle, keyed by
+ * the surviving object layout (`sessions/<machine>/<agent>/<sessionId>.jsonl`, or
+ * `.../<sessionId>/<relKey>` for dir-shaped agents). Each object is independently
+ * a valid bundle, so `import --from-r2` restores it through the same parse/place
+ * path as a local bundle. Fails loud on the first upload error (no silent
+ * partial-success).
+ */
+/**
+ * `--to-r2` preflight as a pure, unit-testable function: the impossible-combo +
+ * not-configured gate. Returns the message to fail loud with, or null when the
+ * export may proceed. Only meaningful when `g.toR2` is set (the caller gates on
+ * that). Kept pure — no process.exit, no keychain read — so both the command and
+ * its test drive the exact same decision.
+ */
+export declare function r2ExportGateError(g: Pick<GlobalSelection, 'toR2' | 'host'>, isConfigured: boolean): string | null;
+export declare function uploadToR2(header: BundleHeader, records: BundleRecord[]): Promise<void>;
+/** R2 object key for one record — dir-shaped agents key by relKey, file-shaped by session. */
+export declare function r2KeyForRecord(rec: BundleRecord): string;
+/**
+ * Resolve the AES key for an R2 backup: the fleet-shared R2_SYNC_ENC_KEY from the
+ * r2.backups bundle so any box on the bundle can restore. Unlike a local bundle,
+ * an ephemeral key is useless here (it is never stored, so a fresh box could not
+ * decrypt), so a missing key means the objects go up unencrypted (R2 server-side
+ * encryption only) with a loud warning — never a silent weaker default.
+ */
+export declare function resolveR2BackupKey(): Buffer | null;
 /** ids > query > everything-in-scope. Exported for the id-resolution test. */
 export declare function selectSessions(metas: SessionMeta[], selectors: string[]): SessionMeta[];
+export {};

package/dist/commands/sessions-export.js

@@ -23,11 +23,12 @@ import chalk from 'chalk';
 import { discoverSessions, resolveSessionById, looksLikeSessionId } from '../lib/session/discover.js';
 import { findSessionsById } from '../lib/session/db.js';
 import { filterSessionsByQuery, parseAgentFilter } from './sessions.js';
-import { listLocalTranscripts, SYNC_AGENTS } from '../lib/session/sync/agents.js';
+import { listLocalTranscripts, objectKey, 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 { isSyncConfigured, loadR2Config } from '../lib/session/sync/config.js';
 import { resolveSyncEncKey, generateSyncEncKey } from '../lib/session/sync/transcript-crypto.js';
+import { R2Client } from '../lib/session/sync/r2.js';
 import { buildRecord, makeHeader, mergeRecords, serializeBundle, writeBundleFile, specForAgent, } from '../lib/session/bundle.js';
 import { knownSecretValuesFromEnv } from '../lib/redact.js';
 import { pullBundlesFromHosts } from '../lib/session/remote-bundle.js';
@@ -40,7 +41,8 @@ export function registerSessionsExportCommand(sessionsCmd) {
         .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');
+        .option('--encrypt', 'Seal each transcript body with AES-256-GCM before writing')
+        .option('--to-r2', 'Back the selected sessions up to Cloudflare R2 (requires the r2.backups bundle) instead of a local file');
     setHelpSections(cmd, {
         examples: `# Bundle the last week of sessions to a file
 agents sessions export --since 7d -o week.bundle
@@ -49,11 +51,19 @@ agents sessions export --since 7d -o week.bundle
 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>'`,
+agents sessions export --since 7d --stdout --encrypt | agents ssh boxB 'agents sessions import - --decrypt <key>'
+
+# Back the last month up off-box to Cloudflare R2 (encrypted with the shared key)
+agents sessions export --since 30d --to-r2`,
         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'.`,
+(Kimi) carry all their files. Restore with 'agents sessions import'.
+
+--to-r2 uploads each session to the r2.backups bucket instead of a local file,
+one encrypted object per transcript keyed by machine/agent/session. Bodies are
+sealed with the shared R2_SYNC_ENC_KEY when present. Restore on any box on the
+same bundle with 'agents sessions import --from-r2'.`,
     });
     cmd.action(async (selectors, _options, command) => {
         await runExport(selectors, command);
@@ -61,12 +71,25 @@ line per transcript file. Secrets are redacted by default. Dir-shaped sessions
 }
 async function runExport(selectors, command) {
     const g = command.optsWithGlobals();
+    // --to-r2 preflight: reject the impossible --host combo and fail loud when the
+    // backup target is not configured, rather than silently producing a local file.
+    // isSyncConfigured() is consulted only on the --to-r2 path (it reads the keychain).
+    if (g.toR2) {
+        const gateErr = r2ExportGateError(g, isSyncConfigured());
+        if (gateErr) {
+            process.stderr.write(chalk.red(gateErr + '\n'));
+            process.exit(1);
+        }
+    }
     // --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;
     }
+    if (g.toR2 && (g.output || g.stdout)) {
+        process.stderr.write(chalk.yellow('Note: --to-r2 uploads to R2; -o/--stdout are ignored.\n'));
+    }
     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));
@@ -119,7 +142,9 @@ async function runExport(selectors, command) {
         process.exit(1);
     }
     // 4. Resolve encryption key (opt-in) + redaction (default on via parent --no-redact).
-    const encryptKey = g.encrypt ? resolveExportKey() : null;
+    //    An R2 backup uses the fleet-shared R2_SYNC_ENC_KEY (an ephemeral key would be
+    //    unrecoverable on a fresh box), so it never takes the resolveExportKey path.
+    const encryptKey = g.toR2 ? resolveR2BackupKey() : g.encrypt ? resolveExportKey() : null;
     const redact = g.redact !== false;
     // Value-aware redaction: mask live credential values already in the
     // environment (e.g. an injected secrets bundle) verbatim, whatever their
@@ -146,8 +171,93 @@ async function runExport(selectors, command) {
         redacted: redact,
         records,
     });
+    if (g.toR2) {
+        await uploadToR2(header, records);
+        return;
+    }
     emitBundle(header, records, g);
 }
+/**
+ * Upload each record to R2 as its own self-describing one-record bundle, keyed by
+ * the surviving object layout (`sessions/<machine>/<agent>/<sessionId>.jsonl`, or
+ * `.../<sessionId>/<relKey>` for dir-shaped agents). Each object is independently
+ * a valid bundle, so `import --from-r2` restores it through the same parse/place
+ * path as a local bundle. Fails loud on the first upload error (no silent
+ * partial-success).
+ */
+/**
+ * `--to-r2` preflight as a pure, unit-testable function: the impossible-combo +
+ * not-configured gate. Returns the message to fail loud with, or null when the
+ * export may proceed. Only meaningful when `g.toR2` is set (the caller gates on
+ * that). Kept pure — no process.exit, no keychain read — so both the command and
+ * its test drive the exact same decision.
+ */
+export function r2ExportGateError(g, isConfigured) {
+    if (!g.toR2)
+        return null;
+    if (g.host && g.host.length > 0) {
+        return "--to-r2 backs up THIS machine's sessions; it cannot be combined with --host.";
+    }
+    if (!isConfigured) {
+        return ('R2 backup is not configured: the r2.backups secrets bundle is missing or locked.\n' +
+            'Add it with: agents secrets add r2.backups R2_ACCOUNT_ID R2_BUCKET_NAME R2_ACCESS_KEY_ID R2_SECRET_ACCESS_KEY\n' +
+            '(optionally R2_SYNC_ENC_KEY for client-side encryption).');
+    }
+    return null;
+}
+export async function uploadToR2(header, records) {
+    let client;
+    try {
+        client = new R2Client(loadR2Config());
+    }
+    catch (err) {
+        process.stderr.write(chalk.red(`R2 backup: ${err.message}\n`));
+        process.exit(1);
+    }
+    let uploaded = 0;
+    for (const rec of records) {
+        const recHeader = makeHeader({
+            origin: header.origin,
+            exportedAt: header.exportedAt,
+            encrypted: rec.encrypted,
+            redacted: header.redacted,
+            records: [rec],
+        });
+        const key = r2KeyForRecord(rec);
+        try {
+            await client.put(key, serializeBundle(recHeader, [rec]), 'application/json');
+        }
+        catch (err) {
+            process.stderr.write(chalk.red(`R2 backup failed at ${key}: ${err.message}\n`));
+            process.exit(1);
+        }
+        uploaded++;
+    }
+    process.stderr.write(chalk.green(`Backed up ${header.sessions} session${header.sessions === 1 ? '' : 's'} ` +
+        `(${uploaded} object${uploaded === 1 ? '' : 's'}${header.encrypted ? ', encrypted' : ', UNENCRYPTED'}) → R2.\n`));
+}
+/** R2 object key for one record — dir-shaped agents key by relKey, file-shaped by session. */
+export function r2KeyForRecord(rec) {
+    const spec = specForAgent(rec.agent);
+    const relKey = spec?.dirShaped ? rec.relKey : undefined;
+    return objectKey(rec.machine, rec.agent, rec.sessionId, relKey);
+}
+/**
+ * Resolve the AES key for an R2 backup: the fleet-shared R2_SYNC_ENC_KEY from the
+ * r2.backups bundle so any box on the bundle can restore. Unlike a local bundle,
+ * an ephemeral key is useless here (it is never stored, so a fresh box could not
+ * decrypt), so a missing key means the objects go up unencrypted (R2 server-side
+ * encryption only) with a loud warning — never a silent weaker default.
+ */
+export function resolveR2BackupKey() {
+    const key = resolveSyncEncKey(loadR2Config());
+    if (key)
+        return key;
+    process.stderr.write(chalk.yellow('R2_SYNC_ENC_KEY is not set in the r2.backups bundle — objects are stored WITHOUT client-side\n' +
+        'encryption (R2 server-side only). Add a shared key so backups are zero-knowledge:\n' +
+        '  agents secrets add r2.backups R2_SYNC_ENC_KEY   # value: openssl rand -base64 32\n'));
+    return null;
+}
 /**
  * --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.

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

@@ -1,2 +1,19 @@
 import type { Command } from 'commander';
+import { type ParsedBundle } from '../lib/session/bundle.js';
 export declare function registerSessionsImportCommand(sessionsCmd: Command): void;
+/**
+ * --from-r2: download every session-backup object from the r2.backups bucket and
+ * assemble them into one bundle for the normal placement path. Each object is a
+ * self-describing one-record bundle written by `export --to-r2`, so it parses
+ * with the same parseBundle. A non-bundle object under the prefix (e.g. a legacy
+ * plaintext transcript from the retired sync) is skipped with a count, never
+ * silently swallowed. Fails loud when the bucket holds no restorable backups.
+ */
+/**
+ * `--from-r2` preflight as a pure, unit-testable function: fail loud when the
+ * backup target is not configured. Returns the message to fail loud with, or null
+ * when the restore may proceed. Kept pure (no process.exit, no keychain read) so
+ * the command and its test drive the same decision.
+ */
+export declare function r2ImportGateError(fromR2: boolean, isConfigured: boolean): string | null;
+export declare function pullFromR2(): Promise<ParsedBundle>;

package/dist/commands/sessions-import.js

@@ -10,8 +10,10 @@
  */
 import * as fs from 'fs';
 import chalk from 'chalk';
-import { loadR2Config } from '../lib/session/sync/config.js';
+import { isSyncConfigured, loadR2Config } from '../lib/session/sync/config.js';
 import { resolveSyncEncKey } from '../lib/session/sync/transcript-crypto.js';
+import { R2Client } from '../lib/session/sync/r2.js';
+import { SESSIONS_PREFIX } from '../lib/session/sync/agents.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';
@@ -22,7 +24,8 @@ export function registerSessionsImportCommand(sessionsCmd) {
         .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)');
+        .option('--from-host <target...>', 'Pull sessions live from remote peer(s) over SSH instead of a file (repeatable)')
+        .option('--from-r2', 'Restore session backups from Cloudflare R2 (requires the r2.backups bundle)');
     setHelpSections(cmd, {
         examples: `# Preview what a bundle would restore
 agents sessions import week.bundle --dry-run
@@ -34,11 +37,18 @@ agents sessions import week.bundle
 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 -`,
+agents ssh boxB 'agents sessions export --since 7d --stdout' | agents sessions import -
+
+# Restore everything backed up to R2 (e.g. on a fresh box)
+agents sessions import --from-r2`,
         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).`,
+the same SSH transport as the cross-machine listing (no R2, no daemon).
+
+--from-r2 downloads every session backup in the r2.backups bucket and restores
+it through the same placement, using the shared R2_SYNC_ENC_KEY to decrypt (or
+pass --decrypt <key>). It is the inverse of 'sessions export --to-r2'.`,
     });
     cmd.action(async (bundlePath, options, command) => {
         const g = command.optsWithGlobals();
@@ -46,9 +56,17 @@ the same SSH transport as the cross-machine listing (no R2, no daemon).`,
     });
 }
 async function runImport(bundlePath, options, g, command) {
-    // 1. Obtain the bundle — from remote peer(s), stdin, or a file.
+    // 1. Obtain the bundle — from R2, remote peer(s), stdin, or a file.
     let bundle;
-    if (options.fromHost && options.fromHost.length > 0) {
+    if (options.fromR2) {
+        const gateErr = r2ImportGateError(true, isSyncConfigured());
+        if (gateErr) {
+            process.stderr.write(chalk.red(gateErr + '\n'));
+            process.exit(1);
+        }
+        bundle = await pullFromR2();
+    }
+    else if (options.fromHost && options.fromHost.length > 0) {
         bundle = await pullForImport(options.fromHost, bundlePath, g, command);
     }
     else {
@@ -154,6 +172,96 @@ async function pullForImport(hosts, selector, g, command) {
     });
     return { header, records };
 }
+/**
+ * --from-r2: download every session-backup object from the r2.backups bucket and
+ * assemble them into one bundle for the normal placement path. Each object is a
+ * self-describing one-record bundle written by `export --to-r2`, so it parses
+ * with the same parseBundle. A non-bundle object under the prefix (e.g. a legacy
+ * plaintext transcript from the retired sync) is skipped with a count, never
+ * silently swallowed. Fails loud when the bucket holds no restorable backups.
+ */
+/**
+ * `--from-r2` preflight as a pure, unit-testable function: fail loud when the
+ * backup target is not configured. Returns the message to fail loud with, or null
+ * when the restore may proceed. Kept pure (no process.exit, no keychain read) so
+ * the command and its test drive the same decision.
+ */
+export function r2ImportGateError(fromR2, isConfigured) {
+    if (fromR2 && !isConfigured) {
+        return ('R2 restore is not configured: the r2.backups secrets bundle is missing or locked.\n' +
+            'Add it with: agents secrets add r2.backups R2_ACCOUNT_ID R2_BUCKET_NAME R2_ACCESS_KEY_ID R2_SECRET_ACCESS_KEY');
+    }
+    return null;
+}
+export async function pullFromR2() {
+    let client;
+    let bucket;
+    try {
+        const cfg = loadR2Config();
+        bucket = cfg.bucket;
+        client = new R2Client(cfg);
+    }
+    catch (err) {
+        process.stderr.write(chalk.red(`R2 restore: ${err.message}\n`));
+        process.exit(1);
+    }
+    let keys;
+    try {
+        keys = await client.list(SESSIONS_PREFIX);
+    }
+    catch (err) {
+        process.stderr.write(chalk.red(`R2 restore: listing failed: ${err.message}\n`));
+        process.exit(1);
+    }
+    const records = [];
+    let encryptedAny = false;
+    let redactedAll = true;
+    let skipped = 0;
+    for (const key of keys) {
+        // The retired sync wrote a per-machine manifest.json; it is not a bundle.
+        if (key.endsWith('/manifest.json'))
+            continue;
+        let body;
+        try {
+            body = await client.get(key);
+        }
+        catch (err) {
+            process.stderr.write(chalk.red(`R2 restore: fetching ${key} failed: ${err.message}\n`));
+            process.exit(1);
+        }
+        if (body === null)
+            continue;
+        let parsed;
+        try {
+            parsed = parseBundle(body);
+        }
+        catch {
+            skipped++;
+            continue;
+        }
+        records.push(...parsed.records);
+        if (parsed.header.encrypted)
+            encryptedAny = true;
+        if (!parsed.header.redacted)
+            redactedAll = false;
+    }
+    if (skipped > 0) {
+        process.stderr.write(chalk.yellow(`Skipped ${skipped} object(s) under ${SESSIONS_PREFIX} that are not session bundles.\n`));
+    }
+    const deduped = mergeRecords([records]);
+    if (deduped.length === 0) {
+        process.stderr.write(chalk.red(`No session backups found in R2 bucket '${bucket}'.\n`));
+        process.exit(1);
+    }
+    const header = makeHeader({
+        origin: `r2:${bucket}`,
+        exportedAt: new Date().toISOString(),
+        encrypted: encryptedAny,
+        redacted: redactedAll,
+        records: deduped,
+    });
+    return { header, records: deduped };
+}
 /**
  * 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

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

@@ -15,6 +15,33 @@ export declare function effectiveMode(source: SessionMeta, requested: MigrateMod
     mode: MigrateMode;
     downgraded: boolean;
 };
+/**
+ * Pure. The remote shell commands that create the target's tmux session on the
+ * SAME socket its reaper queries, and that probe its liveness afterward.
+ *
+ * `homeRelSocketPath` is `getDefaultSocketPath()` expressed relative to the
+ * LOCAL home dir (`path.relative(os.homedir(), getDefaultSocketPath())`) — a
+ * portable suffix, not a resolved absolute path, because the local and remote
+ * HOME can differ (different user, different OS). It is spliced in after a
+ * literal, unquoted `$HOME/` so the REMOTE shell resolves it; `$HOME` MUST
+ * NEVER be resolved locally (see AGENTS.md's remote-path guidance).
+ *
+ * Extracted as a pure function so the "does the migrated session land on the
+ * agents socket, not tmux's bare default socket" invariant is unit-testable
+ * without an SSH round-trip (RUSH-2521 review — a bare `tmux` here made the
+ * migrated agent's helpers invisible to `readAllPaneOwners`, so the reaper's
+ * next tick killed the still-live, just-migrated agent as `tmux-session-gone`).
+ */
+export declare function buildMigrateResumeCommands(opts: {
+    sessionName: string;
+    homeRelSocketPath: string;
+    inner: string;
+    cwd?: string;
+}): {
+    launchCmd: string;
+    probeCmd: string;
+    socketFlag: string;
+};
 /**
  * Rehydrate command: launch a fresh agent that reads the transcript. For a
  * non-resumable agent there is no faithful --resume, so we start the agent with