@phnx-labs/agents-cli 1.20.62 → 1.20.64

package/dist/commands/repo.js

@@ -9,6 +9,7 @@ import { confirm, input } from '@inquirer/prompts';
 import { isInteractiveTerminal, isPromptCancelled } from './utils.js';
 import { setHelpSections } from '../lib/help.js';
 import { itemPicker } from '../lib/picker.js';
+import { addHostOption } from '../lib/hosts/option.js';
 import { inspectRepo, resolveRepoTarget, } from './inspect.js';
 const HOME = os.homedir();
 /**
@@ -27,7 +28,7 @@ function resolveRepoPath(target) {
     return path.join(HOME, `.agents-${trimmed}`);
 }
 import { applyExtraAliasToVersions, ensureAgentsDir, getExtraRepoDir, getSystemAgentsDir, getUserAgentsDir, readMeta, resolveExtraRepoDir, updateMeta, } from '../lib/state.js';
-import { parseSource, pullRepo, commitAndPush, isGitRepo, isSystemRepoOrigin, adoptRepo } from '../lib/git.js';
+import { parseSource, pullRepo, commitAndPush, isGitRepo, isSystemRepoOrigin, adoptRepo, displayHomePath, } from '../lib/git.js';
 import { DEFAULT_SYSTEM_REPO } from '../lib/types.js';
 import { ALL_AGENT_IDS, isAgentName, resolveAgentName } from '../lib/agents.js';
 import { refresh } from '../lib/refresh.js';
@@ -465,34 +466,44 @@ async function listRepos(alias, opts = {}) {
     }
     console.log('');
 }
-/** Register the `agents repo` command tree. */
+/**
+ * Label for push/pull spinners and results: alias + resolved dir + tracking ref.
+ * e.g. `user (~/.agents → origin/main)`.
+ */
+function formatRepoTarget(alias, dir, branch) {
+    const ref = branch ? `origin/${branch}` : 'origin';
+    return `${alias} (${displayHomePath(dir)} → ${ref})`;
+}
+/** Register the `agents repos` command tree (`repo` is a convenience alias). */
 export function registerRepoCommands(program) {
-    const repoCmd = program
-        .command('repo')
-        .alias('repos')
-        .description('Manage extra DotAgent repos alongside ~/.agents/ (for private or team skills).');
+    // addHostOption on the group so --help documents --host/--device; remote
+    // routing is handled pre-parse by maybeRunOnHost (passthrough.ts).
+    const repoCmd = addHostOption(program
+        .command('repos')
+        .alias('repo')
+        .description('Manage extra DotAgent repos alongside ~/.agents/ (for private or team skills).'));
     setHelpSections(repoCmd, {
         examples: `
       # Scaffold an editable repo (default: ~/.agents/)
-      agents repo init
+      agents repos init
 
       # Scaffold a named repo at ~/.agents-work/
-      agents repo init work
+      agents repos init work
 
       # Register an existing repo (clones to ~/.agents-<alias>/)
-      agents repo add gh:yourname/.agents-work
+      agents repos add gh:yourname/.agents-work
 
       # Register with a custom alias
-      agents repo add git@github.com:acme/team-skills.git --as acme
+      agents repos add git@github.com:acme/team-skills.git --as acme
 
       # See what's registered
-      agents repo list
+      agents repos list
 
       # View one repo's contents (git state + resource counts); omit the name for a picker
       agents repos view system
 
       # Temporarily disable without deleting
-      agents repo disable acme
+      agents repos disable acme
     `,
         notes: `
       Managed extras live at ~/.agents-<alias>/ as peer dirs to ~/.agents/. User-owned
@@ -850,20 +861,20 @@ export function registerRepoCommands(program) {
                 }
                 continue;
             }
-            const spinner = ora(`Pulling ${t.alias}...`).start();
+            const spinner = ora(`Pulling ${formatRepoTarget(t.alias, t.dir)}...`).start();
             const result = await pullRepo(t.dir);
             if (result.success) {
-                spinner.succeed(`${t.alias} -> ${result.commit}`);
+                spinner.succeed(`${formatRepoTarget(t.alias, t.dir, result.branch)}: ${result.commit}`);
             }
             else {
-                spinner.fail(`${t.alias}: ${result.error}`);
+                spinner.fail(`${formatRepoTarget(t.alias, t.dir)}: ${result.error}`);
             }
         }
     });
     repoCmd
         .command('push [alias]')
         .description('Commit and push the user repo or a user-owned extra. Refuses to push the system repo.')
-        .option('-m, --message <msg>', 'Commit message', 'Update via agents repo push')
+        .option('-m, --message <msg>', 'Commit message', 'Update via agents repos push')
         .action(async (alias, options) => {
         const targets = collectRepoTargets(alias);
         if (!targets) {
@@ -893,13 +904,13 @@ export function registerRepoCommands(program) {
             return;
         }
         for (const t of pushable) {
-            const spinner = ora(`Pushing ${t.alias}...`).start();
+            const spinner = ora(`Pushing ${formatRepoTarget(t.alias, t.dir)}...`).start();
             const result = await commitAndPush(t.dir, options.message);
             if (result.success) {
-                spinner.succeed(`${t.alias} pushed`);
+                spinner.succeed(`${formatRepoTarget(t.alias, t.dir, result.branch)}: ${result.detail ?? 'pushed'}`);
             }
             else {
-                spinner.fail(`${t.alias}: ${result.error}`);
+                spinner.fail(`${formatRepoTarget(t.alias, t.dir)}: ${result.error}`);
             }
         }
     });

package/dist/commands/routines.js

@@ -12,7 +12,7 @@ import * as path from 'path';
 import * as yaml from 'yaml';
 import { isDaemonRunning, signalDaemonReload, startDaemon, stopDaemon, readDaemonLog, getDaemonStatus, } from '../lib/daemon.js';
 import { humanizeCron, humanizeNextRun, formatRepoLink, REPO_DISPLAY_MAX } from '../lib/routines-format.js';
-import { listJobs as listAllJobs, deleteJob, readJob, validateJob, writeJob, setJobEnabled, listRuns, getLatestRun, getRunDir, getJobPath, parseAtTime, jobRunsOnThisDevice, checkJobDeviceEligibility, } from '../lib/routines.js';
+import { listJobs as listAllJobs, deleteJob, readJob, validateJob, writeJob, setJobEnabled, listRuns, getLatestRun, getRunDir, getJobPath, parseAtTime, jobRunsOnThisDevice, checkJobDeviceEligibility, normalizeTriggerEvent, } from '../lib/routines.js';
 import { fireWebhookJobs, matchJobsToWebhook } from '../lib/triggers/webhook.js';
 import { getRoutinesDir } from '../lib/state.js';
 import { IS_WINDOWS } from '../lib/platform/index.js';
@@ -54,13 +54,49 @@ function fireConditionLabel(job) {
     if (job.schedule)
         return humanizeCron(job.schedule, job.timezone);
     if (job.trigger) {
-        const scope = job.trigger.repo
-            ? ` (${job.trigger.repo}${job.trigger.branch ? `@${job.trigger.branch}` : ''})`
-            : '';
-        return `on ${job.trigger.event}${scope}`;
+        if (job.trigger.type === 'github_event') {
+            const scope = job.trigger.repo
+                ? ` (${job.trigger.repo}${job.trigger.branch ? `@${job.trigger.branch}` : ''})`
+                : '';
+            return `on github:${job.trigger.event}${scope}`;
+        }
+        const filters = [
+            job.trigger.action ? `action=${job.trigger.action}` : null,
+            job.trigger.teamKey ? `team=${job.trigger.teamKey}` : null,
+            job.trigger.label ? `label=${job.trigger.label}` : null,
+        ].filter(Boolean).join(', ');
+        return `on linear:${job.trigger.event}${filters ? ` (${filters})` : ''}`;
     }
     return '-';
 }
+function parseRoutineTrigger(options) {
+    const raw = typeof options.on === 'string' ? options.on : undefined;
+    if (!raw)
+        return undefined;
+    const [sourceMaybe, eventMaybe] = raw.includes(':') ? raw.split(':', 2) : ['github', raw];
+    if (sourceMaybe === 'github') {
+        const event = normalizeTriggerEvent(eventMaybe);
+        if (!event)
+            throw new Error(`Unknown GitHub trigger event '${eventMaybe}'`);
+        const trigger = { type: 'github_event', event };
+        if (typeof options.repo === 'string')
+            trigger.repo = options.repo;
+        if (typeof options.branch === 'string')
+            trigger.branch = options.branch;
+        return trigger;
+    }
+    if (sourceMaybe === 'linear') {
+        const trigger = { type: 'linear_event', event: eventMaybe };
+        if (typeof options.action === 'string')
+            trigger.action = options.action;
+        if (typeof options.teamKey === 'string')
+            trigger.teamKey = options.teamKey;
+        if (typeof options.label === 'string')
+            trigger.label = options.label;
+        return trigger;
+    }
+    throw new Error('--on source must be github or linear');
+}
 /** Start or reload the background scheduler so newly-added jobs fire on time. */
 function ensureSchedulerRunning() {
     if (isDaemonRunning()) {
@@ -113,7 +149,7 @@ async function pickJob(message, filter, alternatives = [], cwd) {
             message,
             choices: jobs.map((job) => ({
                 value: job.name,
-                name: `${job.name} ${chalk.gray(`(${job.workflow ? `wf:${job.workflow}` : job.agent}, ${job.schedule ?? fireConditionLabel(job)})`)}`,
+                name: `${job.name} ${chalk.gray(`(${job.command ? 'command' : job.workflow ? `wf:${job.workflow}` : job.agent}, ${job.schedule ?? fireConditionLabel(job)})`)}`,
             })),
         });
     }
@@ -246,6 +282,7 @@ export function registerRoutinesCommands(program) {
                     name: job.name,
                     agent: job.agent ?? null,
                     workflow: job.workflow ?? null,
+                    command: job.command ?? null,
                     repo: job.repo ?? null,
                     schedule: job.schedule ?? null,
                     scheduleHuman: fireConditionLabel(job),
@@ -320,9 +357,11 @@ export function registerRoutinesCommands(program) {
                     : lastStatus === 'timeout' ? chalk.yellow
                         : chalk.gray;
             const overdueTag = overdueSet.has(job.name) ? chalk.yellow(' (overdue)') : '';
-            const agentLabelPadded = job.workflow
-                ? chalk.magenta(`wf:${job.workflow}`.padEnd(10))
-                : (job.agent || '').padEnd(10);
+            const agentLabelPadded = job.command
+                ? chalk.magenta('command'.padEnd(10))
+                : job.workflow
+                    ? chalk.magenta(`wf:${job.workflow}`.padEnd(10))
+                    : (job.agent || '').padEnd(10);
             console.log(`  ${chalk.cyan(job.name.padEnd(NAME_W))} ${agentLabelPadded} ${repoCell}${' '.repeat(repoPadding)} ${deviceCell}${' '.repeat(devicePad)} ${schedStr.padEnd(SCHED_W)} ${enabledStr}${' '.repeat(enabledPad)} ${chalk.gray(nextStr.padEnd(NEXT_W))} ${statusColor(lastStatus)}${overdueTag}`);
         }
         if (overdueSet.size > 0) {
@@ -338,6 +377,7 @@ export function registerRoutinesCommands(program) {
         .option('-s, --schedule <cron>', 'Cron schedule in standard format (5 fields: minute hour day month weekday)')
         .option('-a, --agent <agent>', 'Which agent runs this routine: claude, codex, gemini, cursor, or opencode')
         .option('--workflow <name>', 'Run an installed workflow (~/.agents/workflows/<name>) via `agents run`. Mutually exclusive with --agent.')
+        .option('--command <sh>', 'Run a plain shell command directly (no agent, no auth, no sandbox) — for deterministic housekeeping routines. Mutually exclusive with --agent and --workflow; --prompt is not used.')
         .option('-p, --prompt <prompt>', 'Task instruction for the agent')
         .option('-m, --mode <mode>', "Execution mode: plan (read-only), edit (can write files), auto (smart classifier, the default), or skip (bypass all permission prompts). 'full' accepted as alias for skip.", 'auto')
         .option('-e, --effort <effort>', 'Reasoning effort: low | medium | high | xhigh | max | auto', 'auto')
@@ -345,12 +385,18 @@ export function registerRoutinesCommands(program) {
         .option('--timezone <tz>', 'Interpret schedule in this timezone (e.g., America/Los_Angeles)')
         .option('--devices <names>', 'Fleet allowlist (comma-separated): only listed devices schedule and fire this routine. Omit for unrestricted.')
         .option('--at <time>', 'One-shot mode: run once at this time (e.g., "14:30" or "2026-02-24 09:00"), then disable')
+        .option('--on <source:event>', 'Webhook trigger instead of/in addition to a schedule: github:pull_request or linear:Issue')
+        .option('--repo <owner/name>', 'GitHub repo filter for --on github:<event>')
+        .option('--branch <name>', 'GitHub branch filter for --on github:<event>')
+        .option('--action <name>', 'Linear action filter for --on linear:<event> (e.g. update)')
+        .option('--team-key <key>', 'Linear team key filter for --on linear:<event> (e.g. RUSH)')
+        .option('--label <name>', 'Linear issue label filter for --on linear:Issue')
         .option('--end-at <iso>', 'Stop firing on or after this ISO 8601 timestamp (e.g., "2026-12-31T23:59:00Z"); routine auto-disables.')
         .option('--disabled', 'Create the routine but keep it paused (enable later with resume)')
         .option('--resume <sessionId>', 'At fire time, resume this existing session id (via `agents run <agent> --resume`) instead of starting fresh — the actual session reopens with full context and the prompt becomes its next turn. Powers self-scheduled wake-ups (e.g. /hibernate). Requires --agent claude or codex; runs un-sandboxed (the session store lives in the real home, not the job overlay).')
         .action(async (nameOrPath, options) => {
         // Check if inline mode (has flags) or file mode
-        const hasInlineFlags = options.schedule || options.agent || options.workflow || options.prompt || options.at;
+        const hasInlineFlags = options.schedule || options.agent || options.workflow || options.command || options.prompt || options.at || options.on;
         if (hasInlineFlags) {
             // Inline mode: create job from flags
             if (!nameOrPath) {
@@ -358,13 +404,21 @@ export function registerRoutinesCommands(program) {
                 console.log(chalk.gray('Usage: agents routines add <name> --schedule "..." --agent <agent> --prompt "..."'));
                 process.exit(1);
             }
-            // Validate mutually exclusive --agent / --workflow
-            if (options.agent && options.workflow) {
-                console.log(chalk.red('--agent and --workflow are mutually exclusive; specify exactly one'));
+            // Validate mutually exclusive --agent / --workflow / --command
+            if ([options.agent, options.workflow, options.command].filter(Boolean).length > 1) {
+                console.log(chalk.red('--agent, --workflow, and --command are mutually exclusive; specify exactly one'));
                 process.exit(1);
             }
             let schedule = options.schedule;
+            let trigger;
             let runOnce = false;
+            try {
+                trigger = parseRoutineTrigger(options);
+            }
+            catch (err) {
+                console.log(chalk.red(err.message));
+                process.exit(1);
+            }
             // Handle --at for one-shot jobs
             if (options.at) {
                 const parsed = parseAtTime(options.at);
@@ -376,15 +430,16 @@ export function registerRoutinesCommands(program) {
                 schedule = parsed.schedule;
                 runOnce = parsed.runOnce;
             }
-            if (!schedule) {
-                console.log(chalk.red('Schedule is required (use --schedule or --at)'));
+            if (!schedule && !trigger) {
+                console.log(chalk.red('Schedule or trigger is required (use --schedule, --at, or --on)'));
                 process.exit(1);
             }
-            if (!options.agent && !options.workflow) {
-                console.log(chalk.red('An agent or workflow is required (use --agent or --workflow)'));
+            if (!options.agent && !options.workflow && !options.command) {
+                console.log(chalk.red('An agent, workflow, or command is required (use --agent, --workflow, or --command)'));
                 process.exit(1);
             }
-            if (!options.prompt) {
+            // Command routines run a plain shell and take no prompt; agent/workflow routines require one.
+            if (!options.command && !options.prompt) {
                 console.log(chalk.red('Prompt is required (use --prompt)'));
                 process.exit(1);
             }
@@ -395,14 +450,16 @@ export function registerRoutinesCommands(program) {
             }
             const config = {
                 name: nameOrPath,
-                schedule,
-                agent: options.agent,
+                ...(schedule ? { schedule } : {}),
+                ...(trigger ? { trigger } : {}),
+                ...(options.agent ? { agent: options.agent } : {}),
                 ...(options.workflow ? { workflow: options.workflow } : {}),
+                ...(options.command ? { command: options.command } : {}),
                 mode: options.mode,
                 effort: options.effort,
                 timeout: options.timeout,
                 enabled: !options.disabled,
-                prompt: options.prompt,
+                prompt: options.prompt ?? '',
                 timezone: options.timezone,
                 ...(devices ? { devices } : {}),
                 ...(runOnce ? { runOnce: true } : {}),
@@ -613,7 +670,7 @@ export function registerRoutinesCommands(program) {
             console.log(chalk.gray(`  ${eligibility.suggestion}`));
             process.exit(1);
         }
-        const runLabel = job.workflow ? `workflow: ${job.workflow}` : `agent: ${job.agent}`;
+        const runLabel = job.command ? 'command' : job.workflow ? `workflow: ${job.workflow}` : `agent: ${job.agent}`;
         console.log(chalk.bold(`Running job '${name}' (${runLabel}, mode: ${job.mode})\n`));
         const spinner = ora('Executing...').start();
         try {
@@ -686,11 +743,17 @@ export function registerRoutinesCommands(program) {
     });
     routinesCmd
         .command('webhook')
-        .description('Fire trigger-based routines from a single GitHub webhook payload (read from --file or stdin). One-shot: matches and fires, then exits. For a long-running receiver, run this behind your own HTTP forwarder.')
-        .requiredOption('--event <name>', 'GitHub event name, as sent in the X-GitHub-Event header (e.g. pull_request, push, workflow_run)')
+        .description('Fire trigger-based routines from a single webhook payload (read from --file or stdin). One-shot: matches and fires, then exits.')
+        .option('--source <name>', 'Webhook source: github or linear', 'github')
+        .requiredOption('--event <name>', 'Source event name: GitHub X-GitHub-Event value, or Linear payload type')
         .option('--file <path>', 'Read the webhook JSON payload from this file instead of stdin')
         .option('--dry-run', 'Show which routines would fire without firing them')
         .action(async (options) => {
+        const source = options.source;
+        if (source !== 'github' && source !== 'linear') {
+            console.log(chalk.red(`Unknown webhook source "${options.source}". Use github or linear.`));
+            process.exit(1);
+        }
         // Load the raw JSON payload: --file wins, else drain stdin.
         let raw;
         if (options.file) {
@@ -723,7 +786,7 @@ export function registerRoutinesCommands(program) {
             console.log(chalk.red(`Invalid webhook payload JSON: ${err.message}`));
             process.exit(1);
         }
-        const webhook = { event: options.event, payload };
+        const webhook = { source, event: options.event, payload };
         // Matching is intentionally user-layer only (fireWebhookJobs defaults to
         // listJobs() with no cwd), mirroring `run`/`catchup`: a webhook must never
         // fire a cloned project repo's `.agents/routines/*.yml` and run an
@@ -731,10 +794,10 @@ export function registerRoutinesCommands(program) {
         if (options.dryRun) {
             const matched = matchJobsToWebhook(listAllJobs(), webhook);
             if (matched.length === 0) {
-                console.log(chalk.gray(`No routines match a ${options.event} event for this payload.`));
+                console.log(chalk.gray(`No routines match a ${source}:${options.event} event for this payload.`));
                 return;
             }
-            console.log(chalk.bold(`${matched.length} routine(s) would fire on ${options.event}:\n`));
+            console.log(chalk.bold(`${matched.length} routine(s) would fire on ${source}:${options.event}:\n`));
             for (const job of matched) {
                 console.log(`  ${chalk.cyan(job.name)} — ${fireConditionLabel(job)}`);
             }
@@ -751,10 +814,10 @@ export function registerRoutinesCommands(program) {
         }
         const fired = await fireWebhookJobs(webhook);
         if (fired.length === 0) {
-            console.log(chalk.gray(`No routines match a ${options.event} event for this payload.`));
+            console.log(chalk.gray(`No routines match a ${source}:${options.event} event for this payload.`));
             return;
         }
-        console.log(chalk.bold(`Fired ${fired.length} routine(s) on ${options.event}:\n`));
+        console.log(chalk.bold(`Fired ${fired.length} routine(s) on ${source}:${options.event}:\n`));
         for (const f of fired) {
             console.log(`  ${chalk.cyan(f.jobName)} → ${chalk.green('started')} (run: ${f.runId})`);
         }

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

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

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;