@phnx-labs/agents-cli 1.20.62 → 1.20.63

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()) {
@@ -345,12 +381,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.prompt || options.at || options.on;
         if (hasInlineFlags) {
             // Inline mode: create job from flags
             if (!nameOrPath) {
@@ -364,7 +406,15 @@ export function registerRoutinesCommands(program) {
                 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,8 +426,8 @@ 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) {
@@ -395,7 +445,8 @@ export function registerRoutinesCommands(program) {
             }
             const config = {
                 name: nameOrPath,
-                schedule,
+                ...(schedule ? { schedule } : {}),
+                ...(trigger ? { trigger } : {}),
                 agent: options.agent,
                 ...(options.workflow ? { workflow: options.workflow } : {}),
                 mode: options.mode,
@@ -686,11 +737,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 +780,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 +788,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 +808,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-sync.d.ts

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

package/dist/commands/sessions-sync.js

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

package/dist/commands/sessions.js

@@ -44,6 +44,7 @@ import { registerSessionsResumeCommand } from './sessions-resume.js';
 import { registerGoCommand } from './go.js';
 import { registerFocusCommand } from './focus.js';
 import { registerSessionsInjectCommand } from './sessions-inject.js';
+import { runBrowserSessions } from '../lib/browser/sessions-list.js';
 const SESSION_AGENT_FILTER_HELP = `Filter by agent, e.g. claude, codex, claude@2.0.65`;
 /**
  * The prioritized harnesses that get a boolean shorthand flag (e.g. `--claude`
@@ -2065,7 +2066,8 @@ export function registerSessionsCommands(program) {
         .option('--no-live', 'Do not enrich the listing with live status/preview for running sessions')
         .option('--cloud', 'Source sessions from Rush Cloud (captured runs) instead of local disk')
         .option('-H, --host <target...>', 'Run this query on remote machine(s) over SSH (host alias or user@host; repeatable)')
-        .option('--device <target...>', 'Alias for --host (device alias from `agents devices`; repeatable)');
+        .option('--device <target...>', 'Alias for --host (device alias from `agents devices`; repeatable)')
+        .option('--browser', 'List browser-profile captures (screenshots, PDFs, recordings, downloads) instead of agent transcripts — alias of `agents browser sessions`');
     setHelpSections(sessionsCmd, {
         examples: `
       # Search prior sessions in this project by topic, file path, or command
@@ -2107,6 +2109,11 @@ export function registerSessionsCommands(program) {
     `,
     });
     sessionsCmd.action(async (query, options) => {
+        if (options.browser) {
+            // Alias for `agents browser sessions`: a profile positional narrows to one profile.
+            runBrowserSessions({ profile: query, json: options.json });
+            return;
+        }
         await sessionsAction(query, options);
     });
     registerSessionsTailCommand(sessionsCmd);

package/dist/commands/setup.js

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

package/dist/commands/ssh.js

@@ -25,6 +25,7 @@ import { clearPendingSentinel } from '../lib/devices/pending.js';
 import { isInteractiveTerminal, isPromptCancelled } from './utils.js';
 import { hostNameFor, renderSshConfig } from '../lib/devices/ssh-config.js';
 import { ASKPASS_BUNDLE_ENV, ASKPASS_KEY_ENV, buildSshInvocation, writeAskpassShim, } from '../lib/devices/connect.js';
+import { planFleetTargets, runFleet, skipLabel, upgradeCommand, } from '../lib/devices/fleet.js';
 /** 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) {
@@ -118,11 +119,34 @@ async function runInteractiveDeviceSync() {
     ].filter(Boolean);
     console.log(parts.join(chalk.gray(' · ')));
 }
-/** Register the `agents devices` command tree. */
+/** Print a per-device result table for fleet update/run. */
+function printFleetResults(results) {
+    const nameW = Math.max(8, ...results.map((r) => r.name.length));
+    console.log(chalk.bold('DEVICE'.padEnd(nameW)) + '  ' +
+        chalk.bold('STATUS'.padEnd(8)) + '  ' +
+        chalk.bold('DETAIL'));
+    for (const r of results) {
+        const status = r.status === 'ok' ? chalk.green('ok'.padEnd(8)) :
+            r.status === 'skipped' ? chalk.gray('skipped'.padEnd(8)) :
+                chalk.red('failed'.padEnd(8));
+        const detail = r.status === 'skipped' ? chalk.gray(skipLabel(r.reason)) :
+            r.status === 'failed' ? chalk.red(r.detail || `exit ${r.code ?? '?'}`) :
+                chalk.gray(r.code === 0 ? 'exit 0' : '');
+        console.log(`${r.name.padEnd(nameW)}  ${status}  ${detail}`);
+    }
+    const ok = results.filter((r) => r.status === 'ok').length;
+    const failed = results.filter((r) => r.status === 'failed').length;
+    const skipped = results.filter((r) => r.status === 'skipped').length;
+    console.log(chalk.gray(`${ok} ok · ${failed} failed · ${skipped} skipped`));
+    if (failed > 0)
+        process.exitCode = 1;
+}
+/** Register the `agents devices` command tree (also aliased as `fleet`). */
 function registerDevicesCommands(program) {
     const devicesCmd = program
         .command('devices')
-        .description('Registry of SSH device profiles (platform, user, address, auth), self-populated from Tailscale.')
+        .alias('fleet')
+        .description('Registry of SSH device profiles (platform, user, address, auth), self-populated from Tailscale. Alias: fleet.')
         .addHelpText('after', `
 Typical workflow:
   agents devices sync            # curate: pick which tailscale nodes to keep (TTY)
@@ -131,6 +155,10 @@ Typical workflow:
   agents devices ignore ipad165  # dismiss a node so it's never re-suggested
   agents devices set win-mini --auth password --bundle muqsit
   agents devices render --write  # write ~/.ssh/config.d/agents include
+  agents fleet update            # roll out latest agents-cli to every online device
+  agents fleet run uname -a      # run a command on every online device
+
+\`agents fleet\` is an alias for \`agents devices\` — same subcommands.
 `);
     devicesCmd
         .command('sync')
@@ -307,6 +335,48 @@ Typical workflow:
         console.log(chalk.green(`Wrote ${file}`));
         console.log(chalk.gray('Add this to ~/.ssh/config (once):  Include config.d/agents'));
     });
+    devicesCmd
+        .command('update')
+        .description('Roll out agents-cli to every online registered device (`agents upgrade --yes` on each). Offline devices are skipped.')
+        .argument('[version]', 'Target version or dist-tag (default: latest)')
+        .action(async (version) => {
+        let cmd;
+        try {
+            cmd = upgradeCommand(version);
+        }
+        catch (err) {
+            console.error(chalk.red(err?.message ?? err));
+            process.exit(1);
+        }
+        const reg = await loadDevices();
+        const targets = planFleetTargets(reg);
+        if (targets.length === 0) {
+            console.log(chalk.gray("No devices. Run 'agents devices sync' first."));
+            return;
+        }
+        console.log(chalk.gray(`Running \`${cmd.join(' ')}\` on ${targets.filter((t) => !t.skip).length} online device(s)…`));
+        const results = runFleet(targets, cmd);
+        printFleetResults(results);
+    });
+    devicesCmd
+        .command('run <cmd...>')
+        .description('Run a command on every online registered device. Offline devices are skipped. Alias surface: agents fleet run …')
+        .allowUnknownOption()
+        .action(async (cmd) => {
+        if (!cmd.length) {
+            console.error(chalk.red('Usage: agents fleet run <cmd...>'));
+            process.exit(1);
+        }
+        const reg = await loadDevices();
+        const targets = planFleetTargets(reg);
+        if (targets.length === 0) {
+            console.log(chalk.gray("No devices. Run 'agents devices sync' first."));
+            return;
+        }
+        console.log(chalk.gray(`Running \`${cmd.join(' ')}\` on ${targets.filter((t) => !t.skip).length} online device(s)…`));
+        const results = runFleet(targets, cmd);
+        printFleetResults(results);
+    });
 }
 /** Register the `agents ssh` smart wrapper. */
 function registerSshWrapper(program) {

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

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

package/dist/commands/sync-provision.js

@@ -0,0 +1,107 @@
+/**
+ * Interactive provisioning flow for cross-machine session sync. Collects R2
+ * credentials, writes the `r2.backups` bundle (via the pure lib helper), probes
+ * connectivity, and opts the machine into the `session-sync` beta. Shared by
+ * `agents setup` (offered, opt-in) and `agents sessions sync --setup` (explicit).
+ *
+ * The prompt/UI lives here in the command layer; the credential-writing and
+ * connectivity logic is the pure, unit-tested `lib/session/sync/provision.ts`.
+ */
+import chalk from 'chalk';
+import ora from 'ora';
+import { isInteractiveTerminal, isPromptCancelled } from './utils.js';
+import { isSyncConfigured } from '../lib/session/sync/config.js';
+import { writeSyncBundle, probeR2Connectivity, readStoredEncKey } from '../lib/session/sync/provision.js';
+import { setBetaEnabled } from '../lib/beta.js';
+const SYNC_BETA = 'session-sync';
+const nonEmpty = (v) => (v.trim().length > 0 ? true : 'required');
+/**
+ * Run the guided session-sync setup. Never throws for expected outcomes
+ * (non-interactive shell, user declines, cancels, or a failed probe) — returns
+ * quietly so a first-run `agents setup` is never blocked by the optional step.
+ */
+export async function promptAndProvisionSessionSync(opts = {}) {
+    if (!isInteractiveTerminal()) {
+        if (opts.explicit)
+            console.error(chalk.red('Session-sync setup needs an interactive terminal.'));
+        return;
+    }
+    const alreadyConfigured = isSyncConfigured();
+    const { confirm, input, password } = await import('@inquirer/prompts');
+    try {
+        if (!opts.explicit) {
+            if (alreadyConfigured)
+                return; // first-run setup: nothing to do
+            const want = await confirm({
+                message: 'Set up cross-machine session sync (encrypted transcripts via Cloudflare R2)?',
+                default: false,
+            });
+            if (!want)
+                return;
+        }
+        else if (alreadyConfigured) {
+            const reconfigure = await confirm({
+                message: 'Session sync is already configured. Re-enter R2 credentials?',
+                default: false,
+            });
+            if (!reconfigure) {
+                const key = readStoredEncKey();
+                if (key) {
+                    console.log(chalk.dim('\nShared encryption key (paste on every other machine you sync):'));
+                    console.log('  ' + chalk.cyan(key));
+                }
+                return;
+            }
+        }
+        console.log(chalk.dim('\nR2 credentials — Cloudflare dashboard > R2 > Manage API Tokens (needs read+write):'));
+        const accountId = (await input({ message: 'R2 account ID:', validate: nonEmpty })).trim();
+        const bucketName = (await input({ message: 'R2 bucket name:', validate: nonEmpty })).trim();
+        const accessKeyId = (await password({ message: 'R2 access key ID:', mask: true })).trim();
+        const secretAccessKey = (await password({ message: 'R2 secret access key:', mask: true })).trim();
+        const endpoint = (await input({
+            message: 'S3 endpoint override (blank = Cloudflare R2):',
+            default: '',
+        })).trim();
+        // Encryption key: the first machine mints one; every other machine pastes it
+        // so the whole fabric shares a single key (and can decrypt each other).
+        const firstMachine = await confirm({ message: 'Is this the FIRST machine in your sync fabric?', default: true });
+        let encKey;
+        if (!firstMachine) {
+            encKey = (await password({
+                message: 'Paste the shared R2_SYNC_ENC_KEY from your first machine:',
+                mask: true,
+                validate: nonEmpty,
+            })).trim();
+        }
+        const { encKeyAction } = writeSyncBundle({
+            accountId, bucketName, accessKeyId, secretAccessKey,
+            endpoint: endpoint || undefined,
+            encKey: encKey || undefined,
+        });
+        const spinner = ora('Validating R2 read+write...').start();
+        const probe = await probeR2Connectivity();
+        if (!probe.ok) {
+            spinner.fail(`R2 probe failed: ${probe.error}`);
+            console.log(chalk.yellow('Credentials were saved to the r2.backups bundle but not verified. Fix them and re-run ' +
+                '`agents sessions sync --setup`, or rotate one key with `agents secrets rotate r2.backups <KEY>`.'));
+            return; // do not auto-enable sync against credentials that don't work
+        }
+        spinner.succeed('R2 read+write verified.');
+        setBetaEnabled([SYNC_BETA], true);
+        console.log(chalk.green('\nSession sync configured and enabled') + chalk.dim(' (the daemon syncs every ~90s).'));
+        if (encKeyAction === 'generated') {
+            const key = readStoredEncKey();
+            console.log(chalk.bold('\nShared encryption key — paste this on every OTHER machine you sync:'));
+            console.log('  ' + chalk.cyan(key ?? '(unavailable)'));
+            console.log(chalk.dim('Anyone with this key can decrypt your transcripts. Keep it secret.'));
+        }
+        console.log(chalk.dim('\nSync now with: agents sessions sync'));
+    }
+    catch (err) {
+        if (isPromptCancelled(err)) {
+            console.log(chalk.yellow('\nSession-sync setup cancelled.'));
+            return;
+        }
+        throw err;
+    }
+}

package/dist/commands/webhook.d.ts

@@ -0,0 +1,9 @@
+/**
+ * `agents webhook` — localhost receiver for signed public webhook ingress.
+ *
+ * The receiver intentionally binds localhost by default. Public exposure is a
+ * separate `agents funnel up <host>` step so the HTTP process can be tested and
+ * rotated without changing the Tailscale Funnel config.
+ */
+import type { Command } from 'commander';
+export declare function registerWebhookCommand(program: Command): void;

package/dist/commands/webhook.js

@@ -0,0 +1,93 @@
+import chalk from 'chalk';
+import { readAndResolveBundleEnv } from '../lib/secrets/bundles.js';
+import { startWebhookServer } from '../lib/triggers/webhook.js';
+const DEFAULT_HOST = '127.0.0.1';
+const DEFAULT_PORT = 8787;
+function positiveInt(value, fallback) {
+    const parsed = Number.parseInt(value ?? '', 10);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+}
+function readWebhookSecrets(bundleName) {
+    const { env } = readAndResolveBundleEnv(bundleName, {
+        caller: 'webhook serve',
+    });
+    const secrets = {};
+    if (env.GITHUB_WEBHOOK_SECRET)
+        secrets.github = env.GITHUB_WEBHOOK_SECRET;
+    if (env.LINEAR_WEBHOOK_SECRET)
+        secrets.linear = env.LINEAR_WEBHOOK_SECRET;
+    if (!secrets.github && !secrets.linear) {
+        throw new Error(`Bundle '${bundleName}' must contain GITHUB_WEBHOOK_SECRET or LINEAR_WEBHOOK_SECRET.`);
+    }
+    return secrets;
+}
+function waitForListening(server) {
+    if (server.listening)
+        return Promise.resolve();
+    return new Promise((resolve, reject) => {
+        const cleanup = () => {
+            server.off('listening', onListening);
+            server.off('error', onError);
+        };
+        const onListening = () => {
+            cleanup();
+            resolve();
+        };
+        const onError = (err) => {
+            cleanup();
+            reject(err);
+        };
+        server.once('listening', onListening);
+        server.once('error', onError);
+    });
+}
+export function registerWebhookCommand(program) {
+    const webhook = program
+        .command('webhook')
+        .description('Run a localhost signed webhook receiver for routine triggers.');
+    webhook
+        .command('serve')
+        .description('Receive signed GitHub/Linear webhooks on /hooks/<source> and fire matching routines.')
+        .requiredOption('--secrets-bundle <name>', 'agents secrets bundle containing GITHUB_WEBHOOK_SECRET and/or LINEAR_WEBHOOK_SECRET')
+        .option('--host <addr>', `Bind address (default ${DEFAULT_HOST})`, DEFAULT_HOST)
+        .option('-p, --port <n>', `Local port (default ${DEFAULT_PORT})`, String(DEFAULT_PORT))
+        .option('--rate-limit <n>', 'Accepted deliveries per source per minute', '60')
+        .action(async (opts) => {
+        let secrets;
+        try {
+            secrets = readWebhookSecrets(opts.secretsBundle);
+        }
+        catch (err) {
+            console.error(chalk.red(err.message));
+            process.exit(1);
+        }
+        const port = positiveInt(opts.port, DEFAULT_PORT);
+        const rateLimit = positiveInt(opts.rateLimit, 60);
+        try {
+            const server = startWebhookServer({
+                host: opts.host ?? DEFAULT_HOST,
+                port,
+                secrets,
+                rateLimitPerMinute: rateLimit,
+                onDelivery: (webhook, fired) => {
+                    console.log(`${new Date().toISOString()} ${webhook.source}:${webhook.event} ` +
+                        `${fired.length ? `fired ${fired.map((f) => f.jobName).join(', ')}` : 'no match'}`);
+                },
+            });
+            await waitForListening(server);
+            const address = server.address();
+            const bound = typeof address === 'object' && address ? address.port : port;
+            console.log(`${chalk.green('agents webhook')} ${chalk.dim('→')} ${chalk.cyan(`http://${opts.host ?? DEFAULT_HOST}:${bound}`)}`);
+            console.log(chalk.dim('signed · localhost by default · endpoints: /hooks/github, /hooks/linear · Ctrl-C to stop'));
+            const shutdown = () => {
+                server.close(() => process.exit(0));
+            };
+            process.on('SIGINT', shutdown);
+            process.on('SIGTERM', shutdown);
+        }
+        catch (err) {
+            console.error(chalk.red(`Could not start webhook receiver: ${err.message}`));
+            process.exit(1);
+        }
+    });
+}