@phnx-labs/agents-cli 1.20.16 → 1.20.17

package/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## Unreleased
 
+**Headless Linux: `agents secrets` works out of the box when the keyring is locked**
+
+- On a headless server the libsecret/GNOME-keyring collection is locked, so the encrypted-file fallback is the only option — but it previously hard-failed unless `AGENTS_SECRETS_PASSPHRASE` was set, leaving `agents secrets` silently unusable. Now, on a headless run with no passphrase set, a random machine-local passphrase is auto-provisioned once at `~/.agents/.cache/secrets/.passphrase` (mode 0600) so the encrypted-file store just works. `AGENTS_SECRETS_PASSPHRASE` still takes precedence (off-disk key), an existing `.passphrase` is reused for stable interactive/headless behavior, and interactive TTY sessions are still prompted. Security model + resolution order documented in `docs/secrets.md`. (#371)
+
 **`agents secrets get/set <item>`: raw, cross-platform keychain access for hooks**
 
 - New `agents secrets get <item>` / `agents secrets set <item>` read and write a single keychain item **by bare name** (outside the bundle namespace), so shell hooks and automation have one platform-agnostic credential primitive to call instead of hardcoding `/usr/bin/security` (macOS-only) or `secret-tool` (Linux-only). `get` prints the value to stdout (newline-terminated for clean `$(…)` capture), sends diagnostics to stderr, and exits 1 with empty stdout when the item is missing — exactly what a `SessionStart` hook needs to probe-and-fallback quietly. Routing goes through the existing cross-platform keychain layer: macOS via `/usr/bin/security`, Linux via `secret-tool` with the encrypted-file fallback.

package/dist/commands/sync.d.ts

@@ -2,11 +2,18 @@
  * `agents sync` — synchronize central resources into an installed agent version.
  *
  * Forms:
- *   agents sync claude                                  # uses default/sole installed version
- *   agents sync claude@2.1.142                          # explicit version
- *   agents sync claude@latest                           # newest installed
+ *   agents sync                                         # umbrella: fetch remote (repos+secrets+sessions) -> reconcile all
+ *   agents sync --repos|--secrets|--sessions            # umbrella: fetch only those, then reconcile
+ *   agents sync --cloud                                 # umbrella: fetch all, skip reconcile
+ *   agents sync --local                                 # umbrella: reconcile all, no fetch
+ *   agents sync claude                                  # one agent: uses default/sole installed version
+ *   agents sync claude@2.1.142                          # one agent: explicit version
+ *   agents sync claude@latest                           # one agent: newest installed
  *   agents sync --agent claude --agent-version 2.1.142  # legacy form, still supported
  *
+ * The umbrella stages live in lib/sync-umbrella.ts; this file dispatches to them
+ * when no agent is given.
+ *
  * In a TTY the command previews available/new resources and lets the user
  * select what to sync (same prompts shown after `agents add`). Pass
  * --yes for non-interactive auto-sync, --force to re-sync when nothing

package/dist/commands/sync.js

@@ -2,11 +2,18 @@
  * `agents sync` — synchronize central resources into an installed agent version.
  *
  * Forms:
- *   agents sync claude                                  # uses default/sole installed version
- *   agents sync claude@2.1.142                          # explicit version
- *   agents sync claude@latest                           # newest installed
+ *   agents sync                                         # umbrella: fetch remote (repos+secrets+sessions) -> reconcile all
+ *   agents sync --repos|--secrets|--sessions            # umbrella: fetch only those, then reconcile
+ *   agents sync --cloud                                 # umbrella: fetch all, skip reconcile
+ *   agents sync --local                                 # umbrella: reconcile all, no fetch
+ *   agents sync claude                                  # one agent: uses default/sole installed version
+ *   agents sync claude@2.1.142                          # one agent: explicit version
+ *   agents sync claude@latest                           # one agent: newest installed
  *   agents sync --agent claude --agent-version 2.1.142  # legacy form, still supported
  *
+ * The umbrella stages live in lib/sync-umbrella.ts; this file dispatches to them
+ * when no agent is given.
+ *
  * In a TTY the command previews available/new resources and lets the user
  * select what to sync (same prompts shown after `agents add`). Pass
  * --yes for non-interactive auto-sync, --force to re-sync when nothing
@@ -25,12 +32,13 @@ import { isVersionInstalled, syncResourcesToVersion, parseAgentSpec, resolveVers
 import { compileRulesForProject } from '../lib/rules/compile.js';
 import { runLaunchSync } from '../lib/project-launch.js';
 import { isInteractiveTerminal, isPromptCancelled } from './utils.js';
+import { runUmbrellaSync } from '../lib/sync-umbrella.js';
 /** Register the `agents sync` command. */
 export function registerSyncCommand(program) {
     program
         .command('sync [agentSpec]')
-        .summary('Sync resources into an installed agent version')
-        .description('Sync resources (commands, skills, hooks, rules, MCPs, plugins, etc.) into an installed agent version. Previews what will change and lets you pick.\n\n[agentSpec] is the agent name with an optional @version, e.g. "claude" or "claude@2.1.142". Omit the version to sync into the active (or sole installed) one.')
+        .summary('Make this machine current, or sync resources into one agent')
+        .description('With an [agentSpec], syncs resources (commands, skills, hooks, rules, MCPs, plugins, etc.) into that installed agent version — previews changes and lets you pick. e.g. "claude" or "claude@2.1.142".\n\nWith NO agent, runs the umbrella verb: fetch remote state (config repos + secrets + sessions) then reconcile it into every installed agent. Scope it with --repos / --secrets / --sessions, --cloud (fetch only), or --local (reconcile only).')
         .option('--agent <agent>', 'Agent identifier (legacy form; prefer the positional spec)')
         .option('--agent-version <version>', 'Version to sync into (legacy form; prefer "agent@version")')
         .option('--project-dir <path>', 'Path to project-level .agents/ directory containing project-scoped resources')
@@ -39,10 +47,66 @@ export function registerSyncCommand(program) {
         .option('-y, --yes', 'Skip the interactive preview and auto-sync all detected resources', false)
         .option('--force', 'Re-sync even if no changes are detected since the last sync', false)
         .option('--quiet', 'Suppress all output (exit code indicates success)', false)
+        // Umbrella verb (no agent given): make this machine current.
+        .option('--repos', 'Umbrella: git-pull ~/.agents + enabled ~/.agents-* extras', false)
+        .option('--secrets', 'Umbrella: pull encrypted secret bundles from the remote', false)
+        .option('--sessions', 'Umbrella: sync session transcripts across machines', false)
+        .option('--cloud', 'Umbrella: fetch all remote state but skip the local reconcile', false)
+        .option('--local', "Umbrella: reconcile resources into installed agents only (no fetch)", false)
         .action(async (agentSpec, opts) => {
         await runSync(agentSpec, opts);
     });
 }
+/**
+ * The umbrella verb: bare `agents sync` (no agent) makes this machine current.
+ * Resolves the flags + a secrets passphrase (env-only for now; tokenized auth
+ * arrives with `agents login`) and runs the fetch+reconcile stages, then prints
+ * a one-line summary. Stage failures are non-fatal and surfaced as warnings.
+ */
+async function runUmbrella(opts, quiet, outLog, errLog) {
+    const flags = {
+        repos: opts.repos,
+        secrets: opts.secrets,
+        sessions: opts.sessions,
+        cloud: opts.cloud,
+        local: opts.local,
+    };
+    const passphrase = process.env.AGENTS_SECRETS_PASSPHRASE || undefined;
+    if (!quiet)
+        outLog(chalk.bold('Syncing this machine…'));
+    try {
+        const result = await runUmbrellaSync({
+            flags,
+            yes: !!opts.yes,
+            passphrase,
+            log: (msg) => { if (!quiet)
+                outLog(chalk.gray(`  ${msg}`)); },
+        });
+        if (!quiet) {
+            const parts = [];
+            if (result.repos) {
+                parts.push(`repos ${result.repos.pulled} pulled` +
+                    (result.repos.errors.length ? `, ${result.repos.errors.length} failed` : ''));
+            }
+            if (result.secrets) {
+                parts.push(result.secrets.skipped ? 'secrets skipped' : `secrets ${result.secrets.pulled} pulled`);
+            }
+            if (result.sessions) {
+                parts.push(result.sessions.ran ? `sessions ${result.sessions.merged} merged` : 'sessions off');
+            }
+            if (result.reconciled)
+                parts.push('reconciled');
+            outLog(chalk.green(`✓ sync: ${parts.join(' · ') || 'nothing to do'}`));
+            const errs = [...(result.repos?.errors ?? []), ...(result.secrets?.errors ?? [])];
+            for (const e of errs)
+                errLog(chalk.yellow(`  ! ${e}`));
+        }
+    }
+    catch (err) {
+        errLog(chalk.red(`sync failed: ${err.message}`));
+        process.exitCode = 1;
+    }
+}
 async function runSync(agentSpec, opts) {
     const quiet = !!opts.quiet;
     const errLog = (msg) => { if (!quiet)
@@ -77,10 +141,9 @@ async function runSync(agentSpec, opts) {
         version = opts.agentVersion;
     }
     if (!agentId) {
-        errLog(chalk.red('Usage: agents sync <agent>[@version]'));
-        errLog(chalk.gray('       agents sync claude'));
-        errLog(chalk.gray('       agents sync claude@2.1.142'));
-        process.exitCode = 1;
+        // No agent specified → the umbrella verb: make this machine current
+        // (fetch repos + secrets + sessions, then reconcile all installed agents).
+        await runUmbrella(opts, quiet, outLog, errLog);
         return;
     }
     // ---------- 2. Resolve version (project pin → global default → sole installed) ----------

package/dist/lib/hooks.js

@@ -90,6 +90,18 @@ function isManagedHookCommand(command, prefixes) {
     for (const prefix of prefixes) {
         if (resolved.startsWith(prefix))
             return true;
+        // The command dir above is realpath-resolved, but a raw prefix may still
+        // point through a symlink (macOS TMPDIR /var -> /private/var, or a
+        // symlinked ~/.agents). Compare against a realpath-normalized prefix too
+        // so the two sides match. Strip the trailing sep, resolve the dir, re-add.
+        const rawPrefixDir = prefix.endsWith(path.sep) ? prefix.slice(0, -path.sep.length) : prefix;
+        let resolvedPrefix = prefix;
+        try {
+            resolvedPrefix = fs.realpathSync(rawPrefixDir) + path.sep;
+        }
+        catch { /* absent or broken link */ }
+        if (resolvedPrefix !== prefix && resolved.startsWith(resolvedPrefix))
+            return true;
     }
     return false;
 }

package/dist/lib/plugin-marketplace.js

@@ -209,17 +209,24 @@ export function validateClaudePluginManifest(manifest) {
         const value = m[field];
         if (value === undefined || value === null)
             continue;
+        // How-to-fix written so a human OR a coding agent reading stderr can act
+        // without further investigation. Deleting the field is the recommended fix:
+        // Claude auto-discovers skills/commands/agents from their directories, which
+        // is why every well-formed plugin omits these fields entirely.
+        const fix = `Fix: delete the "${field}" field from plugin.json (recommended — Claude ` +
+            `auto-discovers from the ${field}/ directory), or rewrite every entry as a ` +
+            `"./"-relative path (e.g. "./${field}/<name>").`;
         const entries = Array.isArray(value) ? value : [value];
         for (const entry of entries) {
             if (typeof entry !== 'string') {
-                warnings.push(`plugin.json field "${field}" must contain relative paths starting with "./" ` +
-                    `(e.g. "./${field}/<name>"); found a non-string value. Claude Code will reject the whole plugin.`);
+                warnings.push(`field "${field}" must be a "./"-relative path string or an array of them; ` +
+                    `found a non-string entry. Claude Code silently rejects the ENTIRE plugin. ${fix}`);
                 break;
             }
             if (!entry.startsWith('./')) {
-                warnings.push(`plugin.json field "${field}" entry "${entry}" must be a relative path starting with "./" ` +
-                    `(e.g. "./${field}/${entry}"). Claude Code rejects the entire plugin otherwise — ` +
-                    `remove the field to auto-discover from ${field}/, or use relative paths.`);
+                warnings.push(`field "${field}" entry "${entry}" must be a relative path starting with "./" ` +
+                    `(e.g. "./${field}/${entry}"), not a bare name. Claude Code silently rejects the ` +
+                    `ENTIRE plugin — no commands or skills load. ${fix}`);
                 break;
             }
         }
@@ -268,7 +275,10 @@ export function syncMarketplaceManifest(spec, agent, versionHome) {
             continue;
         }
         for (const warning of validateClaudePluginManifest(manifest)) {
-            process.stderr.write(`agents-cli: plugin '${manifest.name ?? entry.name}': ${warning}\n`);
+            // Reference the plugin by name, not the marketplace-copy path: that copy is
+            // regenerated from source on every sync, so editing it gets stomped. The fix
+            // belongs in the plugin's SOURCE .claude-plugin/plugin.json.
+            process.stderr.write(`agents-cli: plugin '${manifest.name ?? entry.name}' has a Claude-invalid manifest — ${warning}\n`);
         }
         entries.push({
             name: manifest.name,

package/dist/lib/secrets/drivers/rush.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Rush `SyncBackend` driver — the original (and currently default) transport
+ * for `agents secrets push/pull`. Talks to api.prix.dev and authenticates with
+ * the session token written by `rush login` (`~/.rush/user.yaml`).
+ *
+ * This is the ONE place in the secrets module allowed to reference Rush
+ * (api.prix.dev / ~/.rush). It is an opt-in driver kept for backwards
+ * compatibility with bundles already pushed to Rush; `sync.ts` selects it as
+ * the default but the transport seam (`SyncBackend`) lets other backends drop
+ * in without touching the crypto or push/pull logic.
+ */
+import type { SyncBackend } from '../sync-backend.js';
+/** The Rush transport. Plaintext never reaches here — only ciphertext envelopes. */
+export declare const rushSyncBackend: SyncBackend;

package/dist/lib/secrets/drivers/rush.js

@@ -0,0 +1,84 @@
+/**
+ * Rush `SyncBackend` driver — the original (and currently default) transport
+ * for `agents secrets push/pull`. Talks to api.prix.dev and authenticates with
+ * the session token written by `rush login` (`~/.rush/user.yaml`).
+ *
+ * This is the ONE place in the secrets module allowed to reference Rush
+ * (api.prix.dev / ~/.rush). It is an opt-in driver kept for backwards
+ * compatibility with bundles already pushed to Rush; `sync.ts` selects it as
+ * the default but the transport seam (`SyncBackend`) lets other backends drop
+ * in without touching the crypto or push/pull logic.
+ */
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import * as yaml from 'yaml';
+const PROXY_BASE = 'https://api.prix.dev';
+const USER_YAML = path.join(os.homedir(), '.rush', 'user.yaml');
+const BUNDLE_ENDPOINT = '/api/v1/secrets/bundles';
+function readRushToken() {
+    if (!fs.existsSync(USER_YAML)) {
+        throw new Error('Not logged in to Rush. Run `rush login` first.');
+    }
+    const raw = fs.readFileSync(USER_YAML, 'utf-8');
+    const data = yaml.parse(raw);
+    const token = data?.session?.access_token;
+    if (!token) {
+        throw new Error('No session token in ~/.rush/user.yaml. Run `rush login` first.');
+    }
+    return token;
+}
+async function api(method, endpoint, body) {
+    const token = readRushToken();
+    const url = endpoint.startsWith('http') ? endpoint : `${PROXY_BASE}${endpoint}`;
+    return fetch(url, {
+        method,
+        headers: {
+            Authorization: `Bearer ${token}`,
+            'Content-Type': 'application/json',
+        },
+        body: body === undefined ? undefined : JSON.stringify(body),
+    });
+}
+function bundlePath(name) {
+    return `${BUNDLE_ENDPOINT}/${encodeURIComponent(name)}`;
+}
+/** The Rush transport. Plaintext never reaches here — only ciphertext envelopes. */
+export const rushSyncBackend = {
+    async putEnvelope(name, payload) {
+        const res = await api('PUT', bundlePath(name), payload);
+        if (!res.ok) {
+            const body = await res.text().catch(() => '');
+            throw new Error(`Push failed (${res.status} ${res.statusText}): ${body}`);
+        }
+    },
+    async getEnvelope(name) {
+        const res = await api('GET', bundlePath(name));
+        if (res.status === 404)
+            return null;
+        if (!res.ok) {
+            const body = await res.text().catch(() => '');
+            throw new Error(`Pull failed (${res.status} ${res.statusText}): ${body}`);
+        }
+        return await res.json();
+    },
+    async deleteEnvelope(name) {
+        const res = await api('DELETE', bundlePath(name));
+        if (res.status === 404)
+            return false;
+        if (!res.ok) {
+            const body = await res.text().catch(() => '');
+            throw new Error(`Delete failed (${res.status} ${res.statusText}): ${body}`);
+        }
+        return true;
+    },
+    async listEnvelopes() {
+        const res = await api('GET', BUNDLE_ENDPOINT);
+        if (!res.ok) {
+            const body = await res.text().catch(() => '');
+            throw new Error(`List failed (${res.status} ${res.statusText}): ${body}`);
+        }
+        const data = await res.json();
+        return data.bundles ?? [];
+    },
+};

package/dist/lib/secrets/linux.js

@@ -38,6 +38,7 @@ let isAvailable = false;
 // ---------- file fallback state ----------
 let useFileFallback = false;
 let warnedFallback = false;
+let warnedAutoPassphrase = false;
 let fileDirOverride = null;
 let cachedPassphrase = null;
 function fileDir() {
@@ -87,7 +88,13 @@ function preflight() {
         checkedAvailability = true;
     }
     if (!isAvailable) {
-        if (process.env.AGENTS_SECRETS_PASSPHRASE) {
+        // No secret-tool. Route to the encrypted-file fallback whenever a passphrase
+        // source exists or can be auto-provisioned: an explicit
+        // AGENTS_SECRETS_PASSPHRASE, an already-provisioned machine-local passphrase,
+        // or a headless context (no TTY) where getPassphrase() auto-provisions one.
+        // Only an INTERACTIVE session with none of these gets the install hint —
+        // installing libsecret is the better fix when someone is at the keyboard.
+        if (process.env.AGENTS_SECRETS_PASSPHRASE || machinePassphraseExists() || !process.stdin.isTTY) {
             activateFileFallback();
             return 'file';
         }
@@ -141,6 +148,67 @@ function readPassphraseFromTty() {
         fs.closeSync(fd);
     }
 }
+/** Path of the auto-provisioned machine-local passphrase. Lives alongside the
+ *  encrypted items but is never itself an item (no `.enc` suffix, so it's
+ *  excluded from list/has/get and from fileFallbackPreviouslyActivated). */
+function passphraseFilePath() {
+    return path.join(fileDir(), '.passphrase');
+}
+/** True if a machine-local passphrase has already been provisioned. */
+function machinePassphraseExists() {
+    try {
+        return fs.readFileSync(passphraseFilePath(), 'utf8').trim().length > 0;
+    }
+    catch {
+        return false;
+    }
+}
+function readMachinePassphrase() {
+    try {
+        const p = fs.readFileSync(passphraseFilePath(), 'utf8').trim();
+        return p.length > 0 ? p : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Provision (or read back) a stable machine-local passphrase for the encrypted
+ * file store, so `agents secrets` works out of the box on a headless box where
+ * the keyring is locked and no AGENTS_SECRETS_PASSPHRASE is set.
+ *
+ * Security model: this is encryption-at-rest with the key held in a 0600 file —
+ * the same posture as an SSH private key, and identical to the common
+ * "export AGENTS_SECRETS_PASSPHRASE=… in ~/.zshenv (chmod 600)" workaround. The
+ * keyring (key in a daemon's locked memory) is stronger but is unavailable
+ * without a graphical/unlocked session. For an off-disk key, set
+ * AGENTS_SECRETS_PASSPHRASE (it always takes precedence) or unlock the keyring.
+ */
+function provisionMachinePassphrase() {
+    const existing = readMachinePassphrase();
+    if (existing)
+        return existing;
+    ensureFileDir();
+    const generated = randomBytes(32).toString('base64');
+    const fp = passphraseFilePath();
+    try {
+        // wx: fail if a concurrent process created it first (then we read theirs).
+        fs.writeFileSync(fp, generated, { mode: 0o600, flag: 'wx' });
+    }
+    catch {
+        const raced = readMachinePassphrase();
+        if (raced)
+            return raced;
+        throw new Error(`Failed to provision machine-local passphrase at ${fp}.`);
+    }
+    if (!warnedAutoPassphrase) {
+        warnedAutoPassphrase = true;
+        process.stderr.write(`[agents] keyring locked and no AGENTS_SECRETS_PASSPHRASE set; provisioned a ` +
+            `machine-local passphrase at ${fp} (mode 0600). Set AGENTS_SECRETS_PASSPHRASE ` +
+            `for a key held off disk.\n`);
+    }
+    return generated;
+}
 function getPassphrase() {
     if (cachedPassphrase !== null)
         return cachedPassphrase;
@@ -149,16 +217,25 @@ function getPassphrase() {
         cachedPassphrase = env;
         return env;
     }
-    if (!process.stdin.isTTY) {
-        throw new Error('Secret-service collection is locked and no AGENTS_SECRETS_PASSPHRASE is set.\n' +
-            'Set AGENTS_SECRETS_PASSPHRASE in your environment to use the encrypted-file fallback,\n' +
-            'or unlock the keyring (e.g. configure pam_gnome_keyring for SSH login).');
+    // A previously-provisioned machine-local passphrase is this machine's stable
+    // file-store key — prefer it for both interactive and headless runs so they
+    // always agree (a TTY run won't re-prompt once the file exists).
+    const onDisk = readMachinePassphrase();
+    if (onDisk) {
+        cachedPassphrase = onDisk;
+        return onDisk;
+    }
+    // First run, no env, no provisioned key: prompt when interactive, otherwise
+    // (headless — the reported bug) auto-provision instead of hard-failing.
+    if (process.stdin.isTTY) {
+        const p = readPassphraseFromTty();
+        if (!p)
+            throw new Error('No passphrase entered.');
+        cachedPassphrase = p;
+        return p;
     }
-    const p = readPassphraseFromTty();
-    if (!p)
-        throw new Error('No passphrase entered.');
-    cachedPassphrase = p;
-    return p;
+    cachedPassphrase = provisionMachinePassphrase();
+    return cachedPassphrase;
 }
 function deriveKey(passphrase, salt) {
     return scryptSync(passphrase, salt, 32);
@@ -423,6 +500,7 @@ export function _resetForTest(opts = {}) {
     fileDirOverride = opts.fileDir ?? null;
     useFileFallback = opts.forceFileFallback ?? false;
     warnedFallback = false;
+    warnedAutoPassphrase = false;
     cachedPassphrase = opts.passphrase ?? null;
     checkedAvailability = false;
     isAvailable = false;

package/dist/lib/secrets/sync-backend.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Transport seam for encrypted secrets-bundle sync.
+ *
+ * A `SyncBackend` moves opaque ciphertext envelopes to and from some remote.
+ * It NEVER sees plaintext: encryption (`encryptBlob`) happens in `sync.ts`
+ * before `putEnvelope`, and decryption (`decryptBlob`) happens after
+ * `getEnvelope`. This mirrors the `KeychainBackend` storage seam
+ * (`src/lib/secrets/index.ts`) but abstracts *transport* rather than at-rest
+ * storage — so the high-level push/pull logic in `sync.ts` is decoupled from
+ * any specific backend (Rush's api.prix.dev, a future Supabase driver, an
+ * in-memory test double, …).
+ */
+/** Encrypted bundle envelope (AES-256-GCM, key via PBKDF2-SHA256). All byte
+ *  fields are base64. The server only ever stores/returns this — never plaintext. */
+export interface EncryptedEnvelope {
+    v: 1;
+    kdf: 'pbkdf2-sha256';
+    iter: number;
+    salt: string;
+    iv: string;
+    ct: string;
+    tag: string;
+}
+/** A stored bundle object: the ciphertext envelope plus a last-updated stamp. */
+export interface SyncEnvelope {
+    envelope: EncryptedEnvelope;
+    updated_at: string;
+}
+/** Lightweight listing entry returned by `listEnvelopes`. */
+export interface RemoteBundleSummary {
+    name: string;
+    updated_at: string;
+}
+/**
+ * Pluggable transport for encrypted bundles. Implementations handle only the
+ * wire/storage; the crypto and bundle snapshot/restore stay backend-agnostic
+ * in `sync.ts`.
+ */
+export interface SyncBackend {
+    /** Store (create or overwrite) the envelope for `name`. */
+    putEnvelope(name: string, payload: SyncEnvelope): Promise<void>;
+    /** Fetch the envelope for `name`, or `null` if the remote has none. */
+    getEnvelope(name: string): Promise<SyncEnvelope | null>;
+    /** Delete `name` on the remote. Returns false if it didn't exist. */
+    deleteEnvelope(name: string): Promise<boolean>;
+    /** List every bundle the authenticated user has on the remote. */
+    listEnvelopes(): Promise<RemoteBundleSummary[]>;
+}

package/dist/lib/secrets/sync-backend.js

@@ -0,0 +1,13 @@
+/**
+ * Transport seam for encrypted secrets-bundle sync.
+ *
+ * A `SyncBackend` moves opaque ciphertext envelopes to and from some remote.
+ * It NEVER sees plaintext: encryption (`encryptBlob`) happens in `sync.ts`
+ * before `putEnvelope`, and decryption (`decryptBlob`) happens after
+ * `getEnvelope`. This mirrors the `KeychainBackend` storage seam
+ * (`src/lib/secrets/index.ts`) but abstracts *transport* rather than at-rest
+ * storage — so the high-level push/pull logic in `sync.ts` is decoupled from
+ * any specific backend (Rush's api.prix.dev, a future Supabase driver, an
+ * in-memory test double, …).
+ */
+export {};

package/dist/lib/secrets/sync.d.ts

@@ -1,28 +1,21 @@
 /**
- * Remote sync client for secrets bundles.
+ * Remote sync for secrets bundles — backend-agnostic.
  *
  * Replaces the previous "leave it to iCloud Keychain" model with explicit
- * push/pull against api.prix.dev. Bundle contents (vars + secret values) are
- * encrypted client-side with AES-256-GCM under a key derived from a
- * user-supplied passphrase via PBKDF2-SHA256. Plaintext never leaves the
- * machine — api.prix.dev only ever sees the ciphertext + KDF parameters.
+ * push/pull. Bundle contents (vars + secret values) are encrypted client-side
+ * with AES-256-GCM under a key derived from a user-supplied passphrase via
+ * PBKDF2-SHA256; only the resulting ciphertext envelope is handed to the
+ * transport. The transport itself is a pluggable `SyncBackend` (see
+ * `sync-backend.ts`) — the Rush driver (`drivers/rush.ts`, api.prix.dev) is the
+ * default for backwards compatibility, swappable via `setSyncBackend`. Plaintext
+ * never leaves this module; the backend only ever sees ciphertext + KDF params.
  */
 import { type SecretsBundle } from './bundles.js';
+import type { SyncBackend, RemoteBundleSummary, EncryptedEnvelope } from './sync-backend.js';
+export type { EncryptedEnvelope, RemoteBundleSummary } from './sync-backend.js';
 export declare const MIN_PASSPHRASE_LEN = 12;
-/** Envelope for an encrypted bundle. All byte fields are base64. */
-export interface EncryptedEnvelope {
-    v: 1;
-    kdf: 'pbkdf2-sha256';
-    iter: number;
-    salt: string;
-    iv: string;
-    ct: string;
-    tag: string;
-}
-interface RemoteBundleSummary {
-    name: string;
-    updated_at: string;
-}
+/** Override the sync transport. Returns the previous backend (restore in tests). */
+export declare function setSyncBackend(next: SyncBackend): SyncBackend;
 /** Encrypt a JSON-serializable payload with a passphrase. */
 export declare function encryptBlob(plaintext: string, passphrase: string): EncryptedEnvelope;
 /** Decrypt an envelope. Throws on bad passphrase (auth tag mismatch). */
@@ -37,7 +30,7 @@ export interface BundleSnapshot {
 export interface PushOptions {
     passphrase: string;
 }
-/** Push a local bundle to api.prix.dev. Encrypts client-side; server only sees ciphertext. */
+/** Push a local bundle to the remote. Encrypts client-side; the backend only sees ciphertext. */
 export declare function pushBundle(name: string, opts: PushOptions): Promise<{
     updated_at: string;
 }>;
@@ -47,10 +40,9 @@ export interface PullOptions {
     /** When true, overwrite an existing local bundle. */
     force?: boolean;
 }
-/** Pull a bundle by name from api.prix.dev and materialize it locally. */
+/** Pull a bundle by name from the remote and materialize it locally. */
 export declare function pullBundle(name: string, opts: PullOptions): Promise<SecretsBundle>;
 /** Delete a bundle on the remote. */
 export declare function deleteRemoteBundle(name: string): Promise<boolean>;
-/** List bundles currently stored on api.prix.dev for this user. */
+/** List bundles currently stored on the remote for this user. */
 export declare function listRemoteBundles(): Promise<RemoteBundleSummary[]>;
-export {};

package/dist/lib/secrets/sync.js

@@ -1,22 +1,19 @@
 /**
- * Remote sync client for secrets bundles.
+ * Remote sync for secrets bundles — backend-agnostic.
  *
  * Replaces the previous "leave it to iCloud Keychain" model with explicit
- * push/pull against api.prix.dev. Bundle contents (vars + secret values) are
- * encrypted client-side with AES-256-GCM under a key derived from a
- * user-supplied passphrase via PBKDF2-SHA256. Plaintext never leaves the
- * machine — api.prix.dev only ever sees the ciphertext + KDF parameters.
+ * push/pull. Bundle contents (vars + secret values) are encrypted client-side
+ * with AES-256-GCM under a key derived from a user-supplied passphrase via
+ * PBKDF2-SHA256; only the resulting ciphertext envelope is handed to the
+ * transport. The transport itself is a pluggable `SyncBackend` (see
+ * `sync-backend.ts`) — the Rush driver (`drivers/rush.ts`, api.prix.dev) is the
+ * default for backwards compatibility, swappable via `setSyncBackend`. Plaintext
+ * never leaves this module; the backend only ever sees ciphertext + KDF params.
  */
 import * as crypto from 'crypto';
-import * as fs from 'fs';
-import * as os from 'os';
-import * as path from 'path';
-import * as yaml from 'yaml';
 import { getKeychainToken, hasKeychainToken, secretsKeychainItem, setKeychainToken, } from './index.js';
 import { readBundle, writeBundle, keychainItemsForBundle, validateBundleName, } from './bundles.js';
-const PROXY_BASE = 'https://api.prix.dev';
-const USER_YAML = path.join(os.homedir(), '.rush', 'user.yaml');
-const BUNDLE_ENDPOINT = '/api/v1/secrets/bundles';
+import { rushSyncBackend } from './drivers/rush.js';
 // PBKDF2 cost. 600k SHA-256 iters matches OWASP 2023+ guidance and keeps a
 // passphrase prompt under a second on the hardware the CLI targets.
 const PBKDF2_ITER = 600_000;
@@ -24,29 +21,19 @@ export const MIN_PASSPHRASE_LEN = 12;
 const KEY_LEN = 32;
 const SALT_LEN = 16;
 const IV_LEN = 12;
-function readRushToken() {
-    if (!fs.existsSync(USER_YAML)) {
-        throw new Error('Not logged in to Rush. Run `rush login` first.');
-    }
-    const raw = fs.readFileSync(USER_YAML, 'utf-8');
-    const data = yaml.parse(raw);
-    const token = data?.session?.access_token;
-    if (!token) {
-        throw new Error('No session token in ~/.rush/user.yaml. Run `rush login` first.');
-    }
-    return token;
-}
-async function api(method, endpoint, body) {
-    const token = readRushToken();
-    const url = endpoint.startsWith('http') ? endpoint : `${PROXY_BASE}${endpoint}`;
-    return fetch(url, {
-        method,
-        headers: {
-            Authorization: `Bearer ${token}`,
-            'Content-Type': 'application/json',
-        },
-        body: body === undefined ? undefined : JSON.stringify(body),
-    });
+/**
+ * Active transport backend. Defaults to the Rush driver for backwards
+ * compatibility with bundles already pushed to api.prix.dev; `setSyncBackend`
+ * swaps it (a future Supabase driver, or an in-memory double in tests). The
+ * crypto + snapshot/restore below stay backend-agnostic — the backend only
+ * ever moves ciphertext envelopes, never plaintext.
+ */
+let backend = rushSyncBackend;
+/** Override the sync transport. Returns the previous backend (restore in tests). */
+export function setSyncBackend(next) {
+    const prev = backend;
+    backend = next;
+    return prev;
 }
 function deriveKey(passphrase, salt) {
     return crypto.pbkdf2Sync(passphrase, salt, PBKDF2_ITER, KEY_LEN, 'sha256');
@@ -115,32 +102,23 @@ function restoreSnapshot(snap) {
     }
     writeBundle(bundle);
 }
-/** Push a local bundle to api.prix.dev. Encrypts client-side; server only sees ciphertext. */
+/** Push a local bundle to the remote. Encrypts client-side; the backend only sees ciphertext. */
 export async function pushBundle(name, opts) {
     validateBundleName(name);
     const snap = snapshotBundle(name);
     const envelope = encryptBlob(JSON.stringify(snap), opts.passphrase);
     const updated_at = new Date().toISOString();
     const payload = { envelope, updated_at };
-    const res = await api('PUT', `${BUNDLE_ENDPOINT}/${encodeURIComponent(name)}`, payload);
-    if (!res.ok) {
-        const body = await res.text().catch(() => '');
-        throw new Error(`Push failed (${res.status} ${res.statusText}): ${body}`);
-    }
+    await backend.putEnvelope(name, payload);
     return { updated_at };
 }
-/** Pull a bundle by name from api.prix.dev and materialize it locally. */
+/** Pull a bundle by name from the remote and materialize it locally. */
 export async function pullBundle(name, opts) {
     validateBundleName(name);
-    const res = await api('GET', `${BUNDLE_ENDPOINT}/${encodeURIComponent(name)}`);
-    if (res.status === 404) {
-        throw new Error(`Remote bundle '${name}' not found on api.prix.dev.`);
-    }
-    if (!res.ok) {
-        const body = await res.text().catch(() => '');
-        throw new Error(`Pull failed (${res.status} ${res.statusText}): ${body}`);
+    const data = await backend.getEnvelope(name);
+    if (!data) {
+        throw new Error(`Remote bundle '${name}' not found.`);
     }
-    const data = await res.json();
     const plaintext = decryptBlob(data.envelope, opts.passphrase);
     const snap = JSON.parse(plaintext);
     if (!snap || !snap.bundle || snap.bundle.name !== name) {
@@ -159,22 +137,9 @@ export async function pullBundle(name, opts) {
 /** Delete a bundle on the remote. */
 export async function deleteRemoteBundle(name) {
     validateBundleName(name);
-    const res = await api('DELETE', `${BUNDLE_ENDPOINT}/${encodeURIComponent(name)}`);
-    if (res.status === 404)
-        return false;
-    if (!res.ok) {
-        const body = await res.text().catch(() => '');
-        throw new Error(`Delete failed (${res.status} ${res.statusText}): ${body}`);
-    }
-    return true;
+    return backend.deleteEnvelope(name);
 }
-/** List bundles currently stored on api.prix.dev for this user. */
+/** List bundles currently stored on the remote for this user. */
 export async function listRemoteBundles() {
-    const res = await api('GET', BUNDLE_ENDPOINT);
-    if (!res.ok) {
-        const body = await res.text().catch(() => '');
-        throw new Error(`List failed (${res.status} ${res.statusText}): ${body}`);
-    }
-    const data = await res.json();
-    return data.bundles ?? [];
+    return backend.listEnvelopes();
 }

package/dist/lib/sync-umbrella.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Umbrella `agents sync` orchestration — "make this machine current".
+ *
+ * Bare `agents sync` fetches remote state (config repos + secrets + sessions)
+ * then reconciles it into every installed agent's version home. Each stage is
+ * an existing exported library function; this module only sequences them and
+ * decides — from the flags — which stages run (`planUmbrellaStages`). The
+ * planner is pure so the flag matrix is unit-tested without any I/O.
+ *
+ * Stage backends:
+ *   repos    -> git pull of ~/.agents + enabled ~/.agents-* extras (pullRepo)
+ *   secrets  -> listRemoteBundles + pullBundle (needs a passphrase; skipped
+ *               cleanly when none is available — tokenized non-interactive auth
+ *               arrives with `agents login`, #366/#367)
+ *   sessions -> syncSessions(), gated by isSyncConfigured() exactly like the daemon
+ *   reconcile-> refresh({ skipPrompts }) — re-materialize resources into homes
+ */
+/** The five umbrella flags off `agents sync`. */
+export interface UmbrellaFlags {
+    repos?: boolean;
+    secrets?: boolean;
+    sessions?: boolean;
+    cloud?: boolean;
+    local?: boolean;
+}
+/** Which stages a given flag combination runs. */
+export interface UmbrellaPlan {
+    fetchRepos: boolean;
+    fetchSecrets: boolean;
+    fetchSessions: boolean;
+    reconcile: boolean;
+}
+/**
+ * Decide which stages run. Pure — no I/O. Semantics:
+ *   bare (no flags)        fetch all three, then reconcile
+ *   --local                reconcile only, no fetch
+ *   --cloud                fetch (all, or the selected subset), skip reconcile
+ *   --repos/--secrets/...  fetch only the selected types, then reconcile
+ * `--local` wins over everything; `--cloud` suppresses reconcile.
+ */
+export declare function planUmbrellaStages(f: UmbrellaFlags): UmbrellaPlan;
+export interface UmbrellaResult {
+    plan: UmbrellaPlan;
+    repos?: {
+        pulled: number;
+        errors: string[];
+    };
+    secrets?: {
+        pulled: number;
+        skipped: boolean;
+        reason?: string;
+        errors: string[];
+    };
+    sessions?: {
+        ran: boolean;
+        pushed: number;
+        pulled: number;
+        merged: number;
+    };
+    reconciled: boolean;
+}
+export interface RunUmbrellaArgs {
+    flags: UmbrellaFlags;
+    /** Progress sink (already quiet-aware in the caller). */
+    log: (msg: string) => void;
+    /** Pass `skipPrompts` through to reconcile / non-interactive behavior. */
+    yes: boolean;
+    /** Secrets passphrase, if available (env var or prompt). Undefined => skip secrets. */
+    passphrase?: string;
+}
+/**
+ * Execute the planned stages in order: repos -> secrets -> sessions -> reconcile.
+ * A failure in one fetch stage is recorded and does not abort the others or the
+ * reconcile — `agents sync` should make as much current as it can in one pass.
+ */
+export declare function runUmbrellaSync(args: RunUmbrellaArgs): Promise<UmbrellaResult>;

package/dist/lib/sync-umbrella.js

@@ -0,0 +1,125 @@
+/**
+ * Umbrella `agents sync` orchestration — "make this machine current".
+ *
+ * Bare `agents sync` fetches remote state (config repos + secrets + sessions)
+ * then reconciles it into every installed agent's version home. Each stage is
+ * an existing exported library function; this module only sequences them and
+ * decides — from the flags — which stages run (`planUmbrellaStages`). The
+ * planner is pure so the flag matrix is unit-tested without any I/O.
+ *
+ * Stage backends:
+ *   repos    -> git pull of ~/.agents + enabled ~/.agents-* extras (pullRepo)
+ *   secrets  -> listRemoteBundles + pullBundle (needs a passphrase; skipped
+ *               cleanly when none is available — tokenized non-interactive auth
+ *               arrives with `agents login`, #366/#367)
+ *   sessions -> syncSessions(), gated by isSyncConfigured() exactly like the daemon
+ *   reconcile-> refresh({ skipPrompts }) — re-materialize resources into homes
+ */
+import { pullRepo } from './git.js';
+import { getUserAgentsDir, getEnabledExtraRepos } from './state.js';
+import { listRemoteBundles, pullBundle } from './secrets/sync.js';
+/**
+ * Decide which stages run. Pure — no I/O. Semantics:
+ *   bare (no flags)        fetch all three, then reconcile
+ *   --local                reconcile only, no fetch
+ *   --cloud                fetch (all, or the selected subset), skip reconcile
+ *   --repos/--secrets/...  fetch only the selected types, then reconcile
+ * `--local` wins over everything; `--cloud` suppresses reconcile.
+ */
+export function planUmbrellaStages(f) {
+    if (f.local) {
+        return { fetchRepos: false, fetchSecrets: false, fetchSessions: false, reconcile: true };
+    }
+    const anySelector = !!(f.repos || f.secrets || f.sessions);
+    if (anySelector) {
+        return {
+            fetchRepos: !!f.repos,
+            fetchSecrets: !!f.secrets,
+            fetchSessions: !!f.sessions,
+            reconcile: !f.cloud,
+        };
+    }
+    // No per-type selector: bare = all + reconcile; --cloud = all, no reconcile.
+    return { fetchRepos: true, fetchSecrets: true, fetchSessions: true, reconcile: !f.cloud };
+}
+/**
+ * Execute the planned stages in order: repos -> secrets -> sessions -> reconcile.
+ * A failure in one fetch stage is recorded and does not abort the others or the
+ * reconcile — `agents sync` should make as much current as it can in one pass.
+ */
+export async function runUmbrellaSync(args) {
+    const { flags, log, yes, passphrase } = args;
+    const plan = planUmbrellaStages(flags);
+    const result = { plan, reconciled: false };
+    if (plan.fetchRepos) {
+        const dirs = [
+            { alias: 'user', dir: getUserAgentsDir() },
+            ...getEnabledExtraRepos().map((e) => ({ alias: e.alias, dir: e.dir })),
+        ];
+        let pulled = 0;
+        const errors = [];
+        for (const { alias, dir } of dirs) {
+            const r = await pullRepo(dir);
+            if (r.success) {
+                pulled++;
+                log(`repos: ${alias} → ${r.commit}`);
+            }
+            else {
+                errors.push(`${alias}: ${r.error ?? 'unknown error'}`);
+            }
+        }
+        result.repos = { pulled, errors };
+    }
+    if (plan.fetchSecrets) {
+        if (!passphrase) {
+            result.secrets = {
+                pulled: 0,
+                skipped: true,
+                reason: 'no passphrase — set AGENTS_SECRETS_PASSPHRASE or run `agents login` (#366)',
+                errors: [],
+            };
+            log('secrets: skipped (no passphrase available)');
+        }
+        else {
+            let pulled = 0;
+            const errors = [];
+            try {
+                const remote = await listRemoteBundles();
+                for (const b of remote) {
+                    try {
+                        await pullBundle(b.name, { passphrase, force: true });
+                        pulled++;
+                        log(`secrets: ${b.name}`);
+                    }
+                    catch (err) {
+                        errors.push(`${b.name}: ${err.message}`);
+                    }
+                }
+            }
+            catch (err) {
+                errors.push(err.message);
+            }
+            result.secrets = { pulled, skipped: false, errors };
+        }
+    }
+    if (plan.fetchSessions) {
+        // Gate exactly like the daemon: a missing r2.backups bundle is a clean no-op,
+        // not an error that fails the whole sync.
+        const { isSyncConfigured } = await import('./session/sync/config.js');
+        if (isSyncConfigured()) {
+            const { syncSessions } = await import('./session/sync/sync.js');
+            const r = await syncSessions();
+            result.sessions = { ran: true, pushed: r.pushed, pulled: r.pulled, merged: r.merged };
+            log(`sessions: pushed ${r.pushed}, pulled ${r.pulled}, merged ${r.merged}`);
+        }
+        else {
+            result.sessions = { ran: false, pushed: 0, pulled: 0, merged: 0 };
+        }
+    }
+    if (plan.reconcile) {
+        const { refresh } = await import('./refresh.js');
+        await refresh({ skipPrompts: yes });
+        result.reconciled = true;
+    }
+    return result;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phnx-labs/agents-cli",
-  "version": "1.20.16",
+  "version": "1.20.17",
   "description": "One CLI for all your AI coding agents - versions, config, cloud dispatch, sessions, and teams (now with first-class Grok Build CLI support)",
   "type": "module",
   "main": "dist/index.js",