@phnx-labs/agents-cli 1.20.72 → 1.20.73

package/dist/commands/secrets.js

@@ -10,13 +10,15 @@ import chalk from 'chalk';
 import { padVisible, readStdinSync } from '../lib/format.js';
 import { terminalWidth, truncateToWidth, stringWidth } from '../lib/session/width.js';
 import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
 import { SSH_TARGET_RE, assertValidSshTarget, sshExec } from '../lib/ssh-exec.js';
 import { quoteWin32ExecArg, composeWin32CommandLine } from '../lib/platform/index.js';
 import { ensureDaemonStarted, isDaemonRunning } from '../lib/daemon.js';
 import { parseHostsOption, remoteResolveEnv, remoteSecretsRaw, remoteSecretsStream, resolveSshTarget, } from '../lib/secrets/remote.js';
 import { remoteShellFor, buildWindowsStdinImportCommand } from '../lib/hosts/remote-cmd.js';
 import { resolveRemoteOsSync } from '../lib/hosts/remote-os.js';
-import { bundleExists, bundleItemStore, bundlePolicy, deleteBundle, describeBundle, keychainItemsForBundle, keychainRef, listBundles, migrateLegacyBundles, parseDotenv, readAndResolveBundleEnv, isHeadlessSecretsContext, readBundle, renameBundle, rotateBundleSecret, sanitizeProcessEnv, validateBundleName, validateEnvKey, validateExpiresFutureDated, validateSecretType, writeBundle, } from '../lib/secrets/bundles.js';
+import { bundleExists, bundleItemStore, bundlePolicy, deleteBundle, describeBundle, keychainItemsForBundle, keychainRef, listBundles, migrateLegacyBundles, parseDotenv, readAndResolveBundleEnv, isHeadlessSecretsContext, readBundle, renameBundle, rotateBundleSecret, sanitizeProcessEnv, validateBundleName, validateEnvKey, validateExpiresFutureDated, validateSecretType, writeBundle, writeBundleWithItems, } from '../lib/secrets/bundles.js';
 import { encryptForFallback, decryptForFallback } from '../lib/secrets/filestore.js';
 import { getKeychainToken, getKeychainTokens, hasKeychainToken, secretsKeychainItem, setKeychainToken, } from '../lib/secrets/index.js';
 import { assertOpAvailable, createPasswordItem, deleteItemByTitle, extractSecrets, itemExistsByTitle, listItems, listVaults, } from '../lib/onepassword.js';
@@ -29,6 +31,7 @@ import { emit } from '../lib/events.js';
 import { registerCommandGroups, setHelpSections } from '../lib/help.js';
 import { isInteractiveTerminal, isPromptCancelled } from './utils.js';
 import { discoverSyncedBundles, importSyncedBundle, } from '../lib/secrets/icloud-import.js';
+import { getVaultSession, vaultExists } from '../lib/secrets/vault.js';
 import { registerSecretsSyncCommands } from './secrets-sync.js';
 import { registerSecretsMigrateAclCommand } from './secrets-migrate.js';
 import { registerSecretsImportKeyringCommand } from './secrets-import.js';
@@ -495,8 +498,12 @@ function renderBundleRow(b, held, cols = terminalWidth()) {
         `${padVisible(created, 9)} ` +
         `${padVisible(updated, 9)} ` +
         `${padVisible(used, 7)}`;
-    // Mark file-backed bundles so `list` distinguishes them from keychain ones.
-    const tag = b.backend === 'file' ? chalk.magenta('[file] ') : '';
+    // Mark non-keychain bundles so `list` distinguishes storage at a glance.
+    const tag = b.backend === 'file'
+        ? chalk.magenta('[file] ')
+        : b.backend === 'vault'
+            ? chalk.blue('[synced] ')
+            : '';
     // Cap the free-form description to whatever space is left on the line so a long
     // description can't push the row to 200+ chars and wrap into a smear.
     const budget = cols - stringWidth(head) - 1 - stringWidth(tag);
@@ -510,7 +517,11 @@ function renderBundleRow(b, held, cols = terminalWidth()) {
 function renderBundleCard(b, held, cols) {
     const keys = describeBundle(b).length;
     const used = b.last_used ? relativeAge(b.last_used) : (b.created_at ? 'never' : '?');
-    const tag = b.backend === 'file' ? chalk.magenta(' [file]') : '';
+    const tag = b.backend === 'file'
+        ? chalk.magenta(' [file]')
+        : b.backend === 'vault'
+            ? chalk.blue(' [synced]')
+            : '';
     const meta = chalk.gray(`${keys} key${keys === 1 ? '' : 's'} · `) + renderPolicyCol(b, held) + chalk.gray(` · used ${used}`);
     const line1 = `${chalk.cyan(b.name)}  ${meta}${tag}`;
     if (!b.description)
@@ -643,17 +654,17 @@ function countExpiringSoon(meta) {
  * keychain-backed bundle to `file` — shared by every `import` source so the
  * guard can't drift between them.
  */
-function resolveImportBundle(name, backendOpt) {
-    const requestedBackend = parseBackendOpt(backendOpt);
+function resolveImportBundle(name, backendOpt, synced = false) {
+    const requestedBackend = synced ? 'vault' : parseBackendOpt(backendOpt);
     if (bundleExists(name)) {
         const bundle = readBundle(name);
-        if (requestedBackend === 'file' && bundle.backend !== 'file') {
-            throw new Error(`Bundle '${name}' already exists with a keychain backend; ` +
-                `--backend file cannot change it. Delete it first to recreate as file-backed.`);
+        if (requestedBackend !== 'keychain' && bundle.backend !== requestedBackend) {
+            throw new Error(`Bundle '${name}' already exists with a different backend; ` +
+                `delete it first to recreate it as ${requestedBackend === 'vault' ? 'synced' : `${requestedBackend}-backed`}.`);
         }
         return bundle;
     }
-    return { name, backend: requestedBackend === 'file' ? 'file' : undefined, vars: {} };
+    return { name, backend: requestedBackend === 'keychain' ? undefined : requestedBackend, vars: {} };
 }
 /**
  * Apply KEY=VALUE entries into a bundle (keychain item or plaintext literal),
@@ -661,7 +672,7 @@ function resolveImportBundle(name, backendOpt) {
  * the .env, --from-file, and --from-ssh import paths.
  */
 function applyEnvToBundle(bundle, env, opts) {
-    const store = bundleItemStore(bundle.backend, { noAcl: bundlePolicy(bundle) === 'never' });
+    const storedItems = new Map();
     let added = 0;
     let skipped = 0;
     for (const [key, value] of Object.entries(env)) {
@@ -674,12 +685,17 @@ function applyEnvToBundle(bundle, env, opts) {
         }
         else {
             const item = secretsKeychainItem(bundle.name, key);
-            store.set(item, value);
+            storedItems.set(item, value);
             bundle.vars[key] = keychainRef(key);
         }
         added++;
     }
-    writeBundle(bundle);
+    if (storedItems.size > 0) {
+        writeBundleWithItems(bundle, storedItems);
+    }
+    else {
+        writeBundle(bundle);
+    }
     return { added, skipped };
 }
 /** Register the `agents secrets` command tree. */
@@ -759,18 +775,14 @@ export function registerSecretsCommands(program) {
         .description('List configured secrets bundles (use --host/--hosts to list bundles on other machines over SSH)')
         .option('--host <target>', 'List bundles on a remote host over SSH (enrolled `agents hosts` name, ssh-config alias, or user@host)')
         .option('--hosts <list>', 'Comma-separated hosts to list in one shot, e.g. yosemite-s0,yosemite-s1')
+        .option('--json', 'Emit machine-readable JSON (bundle metadata only — never secret values) instead of the table')
         .action(async (opts) => {
         const targets = parseHostsOption(opts);
         if (targets.length > 0) {
-            await browseRemote(targets, ['list'], false);
+            await browseRemote(targets, opts.json ? ['list', '--json'] : ['list'], false);
             return;
         }
         const bundles = listBundles();
-        if (bundles.length === 0) {
-            console.log(chalk.gray('No secrets bundles configured.'));
-            console.log(chalk.gray('Try: agents secrets create <name>'));
-            return;
-        }
         // Cross-reference the secrets-agent so `daily` bundles that are currently
         // held can show "· held Nh". Soft-fails to no hint if the broker is down.
         const held = new Map();
@@ -783,6 +795,31 @@ export function registerSecretsCommands(program) {
                 /* broker not running — render policy without the countdown */
             }
         }
+        if (opts.json) {
+            // Discovery payload for agents: metadata only, no secret values. Gated on
+            // the explicit --json flag (not stdout.isTTY) so piping the human table to
+            // a pager never silently swaps formats.
+            const payload = bundles.map((b) => ({
+                name: b.name,
+                keys: describeBundle(b).length,
+                policy: bundlePolicy(b),
+                backend: b.backend === 'file' ? 'file' : 'keychain',
+                allowExec: Boolean(b.allow_exec),
+                expiringSoon: countExpiringSoon(b.meta),
+                description: b.description ?? null,
+                createdAt: b.created_at ?? null,
+                updatedAt: b.updated_at ?? null,
+                lastUsed: b.last_used ?? null,
+                heldExpiresAt: held.get(b.name) ?? null,
+            }));
+            process.stdout.write(JSON.stringify(payload) + '\n');
+            return;
+        }
+        if (bundles.length === 0) {
+            console.log(chalk.gray('No secrets bundles configured.'));
+            console.log(chalk.gray('Try: agents secrets create <name>'));
+            return;
+        }
         const cols = terminalWidth();
         if (cols >= SECRETS_WIDE) {
             console.log(chalk.bold(`${'NAME'.padEnd(20)} ${'KEYS'.padEnd(5)} ${'POLICY'.padEnd(18)} ${'EXPIRING'.padEnd(9)} ${'CREATED'.padEnd(9)} ${'UPDATED'.padEnd(9)} ${'USED'.padEnd(7)} DESCRIPTION`));
@@ -802,6 +839,7 @@ export function registerSecretsCommands(program) {
         .description('Show a bundle. Keychain values are masked by default — pass --reveal to see them.')
         .option('--reveal', 'Print keychain-backed values in the clear (TTY only unless --plaintext)')
         .option('--plaintext', 'Allow --reveal in non-interactive shells (use with care)')
+        .option('--json', 'Emit machine-readable JSON (values masked unless --reveal) instead of the human view')
         .option('--host <target>', 'Show a bundle on a remote host over SSH (enrolled `agents hosts` name, ssh-config alias, or user@host)')
         .option('--hosts <list>', 'Comma-separated hosts to show in one shot, e.g. yosemite-s0,yosemite-s1')
         .action(async (name, opts) => {
@@ -817,6 +855,8 @@ export function registerSecretsCommands(program) {
                     args.push('--reveal');
                 if (opts.plaintext)
                     args.push('--plaintext');
+                if (opts.json)
+                    args.push('--json');
                 // With --reveal, force a TTY so the remote keychain prompt can surface
                 // (and the remote's "--reveal in a non-TTY needs --plaintext" gate is
                 // satisfied) — only when this side is itself interactive.
@@ -835,6 +875,76 @@ export function registerSecretsCommands(program) {
                 process.exit(1);
             }
             const entries = describeBundle(bundle);
+            if (opts.json) {
+                // Machine-readable discovery for agents. Values are null unless --reveal
+                // (which still routes through the same non-TTY/plaintext gate + audit
+                // event as the human path). Gated on the explicit flag, not stdout.isTTY,
+                // so a piped human view never silently swaps formats.
+                const reveal = Boolean(opts.reveal);
+                if (reveal && !isInteractiveTerminal() && !opts.plaintext) {
+                    console.error(chalk.red('--reveal in a non-TTY requires --plaintext.'));
+                    process.exit(1);
+                }
+                const revealed = new Map();
+                if (reveal) {
+                    const items = entries
+                        .filter((e) => e.kind === 'keychain')
+                        .map((e) => secretsKeychainItem(bundle.name, e.detail));
+                    try {
+                        for (const [item, value] of getKeychainTokens(items))
+                            revealed.set(item, value);
+                    }
+                    catch {
+                        /* cancelled / batch failure — fall through to masked (null) values */
+                    }
+                    const exposed = revealed.size + entries.filter((e) => e.kind === 'literal').length;
+                    if (exposed > 0) {
+                        emit('secrets.get', {
+                            module: 'secrets',
+                            bundle: bundle.name,
+                            operation: 'view --reveal --json',
+                            source: 'reveal',
+                            status: 'success',
+                            keyCount: exposed,
+                        });
+                    }
+                }
+                const keys = entries.map((e) => {
+                    const row = {
+                        key: e.key,
+                        kind: e.kind,
+                        detail: e.detail || null,
+                        value: null,
+                    };
+                    if (e.kind === 'keychain') {
+                        const item = secretsKeychainItem(bundle.name, e.detail);
+                        row.stored = hasKeychainToken(item);
+                        if (reveal && revealed.has(item))
+                            row.value = revealed.get(item);
+                    }
+                    else if (e.kind === 'literal' && reveal) {
+                        const raw = bundle.vars[e.key];
+                        row.value =
+                            typeof raw === 'string'
+                                ? raw
+                                : (raw && typeof raw === 'object' && 'value' in raw ? raw.value : '');
+                    }
+                    return row;
+                });
+                process.stdout.write(JSON.stringify({
+                    name: bundle.name,
+                    description: bundle.description ?? null,
+                    policy: bundlePolicy(bundle),
+                    backend: bundle.backend === 'file' ? 'file' : 'keychain',
+                    allowExec: Boolean(bundle.allow_exec),
+                    createdAt: bundle.created_at ?? null,
+                    updatedAt: bundle.updated_at ?? null,
+                    lastUsed: bundle.last_used ?? null,
+                    revealed: reveal,
+                    keys,
+                }) + '\n');
+                return;
+            }
             console.log(chalk.bold(bundle.name));
             if (bundle.description)
                 console.log(chalk.gray(safePrint(bundle.description)));
@@ -842,6 +952,8 @@ export function registerSecretsCommands(program) {
                 console.log(chalk.yellow('allow_exec: true'));
             if (bundle.backend === 'file')
                 console.log(chalk.gray('backend: file (passphrase-encrypted; reads need AGENTS_SECRETS_PASSPHRASE, no Touch ID)'));
+            if (bundle.backend === 'vault')
+                console.log(chalk.gray('storage: synced (age-encrypted ~/.agents/vault.age; needs agents login)'));
             if (bundlePolicy(bundle) === 'never') {
                 console.log(chalk.red.bold('policy: never — NO biometry ACL; reads are silent (no Touch ID, no user-presence check). Automation-only.'));
             }
@@ -866,15 +978,18 @@ export function registerSecretsCommands(program) {
                 console.error(chalk.red('--reveal in a non-TTY requires --plaintext.'));
                 process.exit(1);
             }
-            // Batch every keychain read into one helper call so --reveal pops
-            // Touch ID once for the whole bundle instead of once per key.
+            // Batch every backend read into one helper call where supported, so
+            // keychain --reveal pops Touch ID once and synced/file bundles use
+            // their declared storage.
             const revealedValues = new Map();
             if (reveal) {
                 const items = entries
                     .filter((e) => e.kind === 'keychain')
                     .map((e) => secretsKeychainItem(bundle.name, e.detail));
                 try {
-                    const fetched = getKeychainTokens(items);
+                    const fetched = bundle.backend
+                        ? new Map(items.map((item) => [item, bundleItemStore(bundle.backend).get(item)]))
+                        : getKeychainTokens(items);
                     for (const [item, value] of fetched)
                         revealedValues.set(item, value);
                 }
@@ -905,7 +1020,7 @@ export function registerSecretsCommands(program) {
             for (const e of entries) {
                 if (e.kind === 'keychain') {
                     const item = secretsKeychainItem(bundle.name, e.detail);
-                    const stored = hasKeychainToken(item);
+                    const stored = bundleItemStore(bundle.backend).has(item);
                     const marker = stored ? chalk.green('stored') : chalk.red('missing');
                     let valueCol = `[keychain:${e.detail}] ${marker}`;
                     if (reveal && revealedValues.has(item)) {
@@ -964,14 +1079,14 @@ export function registerSecretsCommands(program) {
         // Ungated like the raw path (it IS the automation primitive); the
         // `secrets.get` audit event is emitted inside readAndResolveBundleEnv.
         try {
-            if (!bundleExists(item)) {
+            if (!bundleExists(item) && !(vaultExists() && !getVaultSession().loggedIn)) {
                 console.error(chalk.red(`Secrets bundle '${item}' not found.`));
                 process.exit(1);
             }
             // `secrets get` is the scriptable automation primitive ($(agents secrets
             // get bundle KEY)); when embedded in a headless routine/CI script it must
             // not pop an unwatched Touch ID prompt. Interactive use still prompts.
-            const { env } = readAndResolveBundleEnv(item, { caller: 'secrets get', keys: [key], agentOnly: isHeadlessSecretsContext() });
+            const { env } = readAndResolveBundleEnv(item, { caller: 'secrets get', keys: [key], keyMode: 'storage', agentOnly: isHeadlessSecretsContext() });
             if (!(key in env)) {
                 console.error(chalk.red(`Key '${key}' not in bundle '${item}'.`));
                 process.exit(1);
@@ -1026,7 +1141,8 @@ export function registerSecretsCommands(program) {
         .option('--policy <policy>', 'prompt policy: daily (default, ask once a week), always (ask every time), or never (silent, NO biometry ACL — needs --i-understand)')
         .addOption(new Option('--tier <policy>', 'deprecated alias for --policy').hideHelp())
         .option('--i-understand', 'Confirm creating a "never"-policy bundle (no biometry ACL) without an interactive prompt')
-        .option('--backend <backend>', 'storage backend: keychain (default) or file (passphrase-encrypted, headless-readable)', 'keychain')
+        .option('--backend <backend>', 'storage backend: keychain (default) or file (passphrase-encrypted)', 'keychain')
+        .option('--synced', 'Store this bundle in the age-encrypted synced secrets file for user-managed cross-machine file sync')
         .option('--force', 'Overwrite an existing bundle')
         .action(async (name, opts) => {
         try {
@@ -1036,7 +1152,7 @@ export function registerSecretsCommands(program) {
             // inherits the configured default (`daily`) instead of being pinned.
             const policyOpt = opts.policy ?? opts.tier;
             const policy = policyOpt ? parsePolicyOpt(policyOpt) : undefined;
-            const backend = parseBackendOpt(opts.backend);
+            const backend = opts.synced ? 'vault' : parseBackendOpt(opts.backend);
             if (bundleExists(resolvedName) && !opts.force) {
                 console.error(chalk.red(`Bundle '${resolvedName}' already exists. Use --force to overwrite.`));
                 process.exit(1);
@@ -1052,7 +1168,7 @@ export function registerSecretsCommands(program) {
                 name: resolvedName,
                 description: opts.description,
                 allow_exec: opts.allowExec,
-                backend: backend === 'file' ? 'file' : undefined,
+                backend: backend === 'keychain' ? undefined : backend,
                 policy,
                 vars: {},
             };
@@ -1062,7 +1178,11 @@ export function registerSecretsCommands(program) {
                 : bundlePolicy(bundle) === 'always'
                     ? 'policy: always ask'
                     : 'policy: never (NO biometry ACL)';
-            const tags = [policyTag, backend === 'file' ? 'backend: file' : null].filter(Boolean);
+            const tags = [
+                policyTag,
+                backend === 'file' ? 'backend: file' : null,
+                backend === 'vault' ? 'synced' : null,
+            ].filter(Boolean);
             console.log(chalk.green(`Bundle '${resolvedName}' created (${tags.join(', ')}).`));
             if (bundlePolicy(bundle) === 'never') {
                 console.log(chalk.red('Stored without biometry protection — reads are silent. Automation-only; rotate anything sensitive out of it.'));
@@ -1070,6 +1190,9 @@ export function registerSecretsCommands(program) {
             if (backend === 'file') {
                 console.log(chalk.gray('File-backed: items are AES-256-GCM encrypted under AGENTS_SECRETS_PASSPHRASE (no Touch ID).'));
             }
+            if (backend === 'vault') {
+                console.log(chalk.gray('Synced: items are encrypted in ~/.agents/vault.age. Copy that file with your sync tool of choice.'));
+            }
             console.log(chalk.gray(`Try: agents secrets add ${resolvedName} MY_KEY`));
         }
         catch (err) {
@@ -1200,11 +1323,14 @@ export function registerSecretsCommands(program) {
                 secretValue = await promptForSecret(`Enter value for ${resolvedBundleName}.${resolvedKey}`);
             }
             const item = secretsKeychainItem(resolvedBundleName, resolvedKey);
-            bundleItemStore(bundle.backend, { noAcl: bundlePolicy(bundle) === 'never' }).set(item, secretValue);
             bundle.vars[resolvedKey] = keychainRef(resolvedKey);
             applyMeta();
-            writeBundle(bundle);
-            const where = bundle.backend === 'file' ? 'encrypted file store' : 'keychain';
+            writeBundleWithItems(bundle, new Map([[item, secretValue]]));
+            const where = bundle.backend === 'file'
+                ? 'encrypted file store'
+                : bundle.backend === 'vault'
+                    ? 'synced secrets file'
+                    : 'keychain';
             console.log(chalk.green(`${resolvedBundleName}.${resolvedKey} stored in ${where} (${item}).`));
         }
         catch (err) {
@@ -1265,7 +1391,8 @@ Examples:
                 clearMeta: opts.clearMeta,
                 meta: metaPatch,
             });
-            console.log(chalk.green(`${resolvedBundleName}.${resolvedKey} rotated in keychain.`));
+            const where = bundle.backend === 'vault' ? 'synced secrets file' : bundle.backend === 'file' ? 'encrypted file store' : 'keychain';
+            console.log(chalk.green(`${resolvedBundleName}.${resolvedKey} rotated in ${where}.`));
         }
         catch (err) {
             if (isPromptCancelled(err))
@@ -1312,7 +1439,11 @@ Examples:
                 const item = secretsKeychainItem(resolvedBundleName, raw.slice('keychain:'.length));
                 const removed = bundleItemStore(bundle.backend).delete(item);
                 if (removed) {
-                    const where = bundle.backend === 'file' ? 'encrypted file item' : 'keychain item';
+                    const where = bundle.backend === 'file'
+                        ? 'encrypted file item'
+                        : bundle.backend === 'vault'
+                            ? 'synced secrets item'
+                            : 'keychain item';
                     console.log(chalk.green(`Removed ${resolvedBundleName}.${resolvedKey} and purged ${where}.`));
                     return;
                 }
@@ -1415,7 +1546,8 @@ Examples:
         .addOption(new Option('--from-1password', 'deprecated alias for --from 1password:<vault>').hideHelp())
         .addOption(new Option('--vault <name>', 'deprecated: name the vault in --from 1password:<vault>').hideHelp())
         .option('--all-plaintext', 'Store every imported value as a literal in the bundle metadata (skip keychain item creation)')
-        .option('--backend <backend>', 'When creating the bundle: keychain (default) or file (passphrase-encrypted, headless-readable)', 'keychain')
+        .option('--backend <backend>', 'When creating the bundle: keychain (default) or file (passphrase-encrypted)', 'keychain')
+        .option('--synced', 'When creating the bundle, store it in the age-encrypted synced secrets file')
         .option('--force', 'Overwrite an existing key in the bundle')
         .option('--purge', 'With --from icloud: delete the iCloud copies after a successful import (iCloud propagates the deletion to your other devices)')
         .option('--from-file <path>', 'Import from an AES-256-GCM encrypted offline bundle file (needs AGENTS_SECRETS_PASSPHRASE; symmetric counterpart of export --to-file)')
@@ -1440,7 +1572,7 @@ Examples:
                 }
                 const env = importBundleFromFile(opts.fromFile, passphrase);
                 const resolvedBundleName = bundleName ?? (await pickBundleName('import into'));
-                const bundle = resolveImportBundle(resolvedBundleName, opts.backend);
+                const bundle = resolveImportBundle(resolvedBundleName, opts.backend, opts.synced);
                 const { added, skipped } = applyEnvToBundle(bundle, env, opts);
                 console.log(chalk.green(`Imported ${added} key(s) from file${skipped ? `, skipped ${skipped} (already set, pass --force)` : ''}.`));
                 return;
@@ -1453,7 +1585,7 @@ Examples:
                 const resolvedBundleName = bundleName ?? (await pickBundleName('import into'));
                 const target = await resolveSshTarget(opts.host);
                 const env = await remoteResolveEnv(target, resolvedBundleName, { osLookupName: opts.host });
-                const bundle = resolveImportBundle(resolvedBundleName, opts.backend);
+                const bundle = resolveImportBundle(resolvedBundleName, opts.backend, opts.synced);
                 const { added, skipped } = applyEnvToBundle(bundle, env, opts);
                 console.log(chalk.green(`Imported ${added} key(s) from ${opts.host}${skipped ? `, skipped ${skipped} (already set, pass --force)` : ''}.`));
                 return;
@@ -1465,12 +1597,12 @@ Examples:
             if (opts.from1password) {
                 console.log(chalk.yellow('--from-1password is deprecated; use --from 1password:<vault>.'));
             }
-            const requestedBackend = parseBackendOpt(opts.backend);
+            const requestedBackend = opts.synced ? 'vault' : parseBackendOpt(opts.backend);
             if (source.kind === 'icloud') {
                 await importFromICloud(bundleName, {
                     force: opts.force,
                     allPlaintext: opts.allPlaintext,
-                    backend: requestedBackend === 'file' ? 'file' : undefined,
+                    backend: requestedBackend === 'keychain' ? undefined : requestedBackend,
                     purge: opts.purge,
                 });
                 return;
@@ -1480,7 +1612,7 @@ Examples:
             // to downgrade keychain -> file) or creates it with the requested backend
             // so a single `import --backend file` works (what `export --host ...
             // --remote-backend file` drives on the remote).
-            const bundle = resolveImportBundle(resolvedBundleName, opts.backend);
+            const bundle = resolveImportBundle(resolvedBundleName, opts.backend, opts.synced);
             if (source.kind === '1password') {
                 assertOpAvailable();
                 const vault = await resolveVault(source.vault);
@@ -1530,7 +1662,7 @@ Examples:
                     throw new Error('--to-file needs AGENTS_SECRETS_PASSPHRASE set to encrypt the bundle. ' +
                         'Set it for this command, then supply the same value when importing.');
                 }
-                const { env } = readAndResolveBundleEnv(resolvedBundleName, { caller: 'export --to-file', agentOnly: isHeadlessSecretsContext() });
+                const { env } = readAndResolveBundleEnv(resolvedBundleName, { caller: 'export --to-file', keyMode: 'storage', agentOnly: isHeadlessSecretsContext() });
                 exportBundleToFile(env, opts.toFile, passphrase);
                 console.log(chalk.green(`Exported ${Object.keys(env).length} key(s) to ${opts.toFile}`));
                 return;
@@ -1557,7 +1689,7 @@ Examples:
                             'bundle at rest on the remote. Set it for this command, then unlock it the same way per run.');
                     }
                 }
-                const { env } = readAndResolveBundleEnv(resolvedBundleName, { caller: `ssh export`, agentOnly: isHeadlessSecretsContext() });
+                const { env } = readAndResolveBundleEnv(resolvedBundleName, { caller: `ssh export`, keyMode: 'storage', agentOnly: isHeadlessSecretsContext() });
                 const dotenv = bundleEnvToDotenv(env);
                 const keyCount = Object.keys(env).length;
                 // Drive the remote's own `agents secrets import --from -` so the values
@@ -1622,7 +1754,7 @@ Examples:
             if (opts.to1password) {
                 assertOpAvailable();
                 const vault = await resolveVault(opts.vault);
-                const { env } = readAndResolveBundleEnv(resolvedBundleName, { caller: `1Password vault ${vault}`, agentOnly: isHeadlessSecretsContext() });
+                const { env } = readAndResolveBundleEnv(resolvedBundleName, { caller: `1Password vault ${vault}`, keyMode: 'storage', agentOnly: isHeadlessSecretsContext() });
                 let created = 0;
                 let overwritten = 0;
                 let skipped = 0;
@@ -1667,11 +1799,12 @@ Examples:
             // terminal stdin, so it is not headless and still prompts.
             const { env } = readAndResolveBundleEnv(resolvedBundleName, {
                 caller: `export to shell`,
+                keyMode: 'process',
                 agentOnly: isHeadlessSecretsContext(),
             });
             if (opts.format === 'json') {
-                // Lossless, machine-readable form consumed by `remoteResolveEnv` over
-                // SSH. Single object of KEY -> value; values verbatim (newlines, quotes).
+                // Machine-readable form consumed by `remoteResolveEnv` over SSH.
+                // Single object of injected env KEY -> value; values verbatim.
                 process.stdout.write(JSON.stringify(env));
                 return;
             }
@@ -1766,6 +1899,60 @@ Examples:
         const { runSecretsMcpServer } = await import('../lib/secrets/mcp.js');
         await runSecretsMcpServer({ version: getCliVersion() });
     });
+    const openclawKeychain = cmd
+        .command('openclaw-keychain')
+        .description('Migrate supported OpenClaw credentials from plaintext config to macOS Keychain-backed SecretRefs');
+    openclawKeychain
+        .command('migrate [config]')
+        .description('Rewrite supported OpenClaw plaintext secrets to exec SecretRefs backed by macOS Keychain')
+        .option('--account <name>', 'Keychain account name', 'openclaw')
+        .option('--dry-run', 'Inspect the migration without writing Keychain or config changes')
+        .action(async (configArg, opts) => {
+        try {
+            const configPath = configArg || path.join(os.homedir(), '.openclaw', 'openclaw.json');
+            const { migrateOpenClawConfigToKeychainRefs, storeOpenClawKeychainServices } = await import('../lib/openclaw-keychain.js');
+            const before = fs.readFileSync(configPath, 'utf-8');
+            const config = JSON.parse(before);
+            const result = migrateOpenClawConfigToKeychainRefs(config, { account: opts.account });
+            if (result.unsupportedEnvKeys.length > 0) {
+                throw new Error(`OpenClaw top-level env keys have no supported SecretRef target: ${result.unsupportedEnvKeys.join(', ')}. ` +
+                    `Move them to a supported credential field before removing plaintext.`);
+            }
+            if (!opts.dryRun) {
+                storeOpenClawKeychainServices(result.services, opts.account);
+                if (result.changed)
+                    fs.writeFileSync(configPath, `${JSON.stringify(config, null, 2)}\n`, 'utf-8');
+            }
+            console.log(`OpenClaw Keychain migration ${opts.dryRun ? 'plan' : 'complete'}: ${result.services.length} secret${result.services.length === 1 ? '' : 's'}, ${result.replacedPaths.length} ref${result.replacedPaths.length === 1 ? '' : 's'}, ${result.removedEnvPaths.length} env entr${result.removedEnvPaths.length === 1 ? 'y' : 'ies'} removed.`);
+            for (const p of result.replacedPaths)
+                console.log(`ref ${p}`);
+            for (const p of result.removedEnvPaths)
+                console.log(`removed ${p}`);
+            process.exit(0);
+        }
+        catch (err) {
+            console.error(chalk.red(err.message));
+            process.exit(1);
+        }
+    });
+    openclawKeychain
+        .command('resolve')
+        .description('OpenClaw exec SecretRef resolver for Keychain service ids')
+        .option('--account <name>', 'Keychain account name', 'openclaw')
+        .action(async (opts) => {
+        try {
+            const { readOpenClawKeychainService, resolveOpenClawKeychainRequest } = await import('../lib/openclaw-keychain.js');
+            const raw = readStdinSync();
+            const request = raw.trim() ? JSON.parse(raw) : {};
+            const response = resolveOpenClawKeychainRequest(request, (service) => readOpenClawKeychainService(service, opts.account));
+            process.stdout.write(JSON.stringify(response));
+            process.exit(0);
+        }
+        catch {
+            process.stdout.write(JSON.stringify({ protocolVersion: 1, values: {}, errors: { value: { code: 'NOT_FOUND' } } }));
+            process.exit(1);
+        }
+    });
     cmd
         .command('generate [length]')
         .description('Generate a random password')
@@ -1921,7 +2108,7 @@ Examples:
             try {
                 // noAgent: read the real keychain (one Touch ID) rather than the
                 // agent we're about to populate.
-                const { bundle, env } = readAndResolveBundleEnv(name, { noAgent: true, caller: 'unlock' });
+                const { bundle, env } = readAndResolveBundleEnv(name, { noAgent: true, caller: 'unlock', keyMode: 'storage' });
                 if (await agentLoad(name, bundle, env, ttlMs)) {
                     loaded++;
                     // Persist a durable session snapshot so the unlock survives a daemon
@@ -2160,7 +2347,7 @@ function parseBackendOpt(raw) {
     const v = (raw ?? 'keychain').toLowerCase();
     if (v === 'keychain' || v === 'file')
         return v;
-    console.error(chalk.red(`Invalid --backend '${raw}'. Use 'keychain' or 'file'.`));
+    console.error(chalk.red(`Invalid --backend '${raw}'. Use 'keychain' or 'file'. For cross-machine file sync, pass --synced.`));
     process.exit(1);
 }
 /** Human-readable "locks in 3 hours" / "locks in 5 minutes" from an epoch-ms expiry. */

package/dist/commands/send.d.ts

@@ -0,0 +1,15 @@
+/**
+ * `agents send <text> --channel <name> --to <target>` — deliver a message over
+ * any registered channel (mailbox, telegram, imessage, slack, discord, apps).
+ *
+ * `agents notify <text>` — owner-facing alias. Fills channel + target from the
+ * `notify.owner` block in agents.yaml when not passed, so routines/agents ping
+ * the owner without hardcoding a chat id / host / account.
+ *
+ * Both go through one `doSend()` seam: resolve the provider for the channel
+ * (notify.transports picks the transport per host) and call provider.send().
+ * The agent mailbox is just one channel; `agents message` stays the richer
+ * agent-control command (feed-claim / identity / PTY / resume) on the same spool.
+ */
+import type { Command } from 'commander';
+export declare function registerSendCommand(program: Command): void;

package/dist/commands/send.js

@@ -0,0 +1,62 @@
+import chalk from 'chalk';
+import { die } from '../lib/format.js';
+import { readMeta } from '../lib/state.js';
+import { registerBuiltinProviders } from '../lib/channels/providers/index.js';
+import { resolveTransport } from '../lib/channels/resolve.js';
+async function doSend(text, channel, to, opts) {
+    registerBuiltinProviders();
+    const provider = resolveTransport(channel, readMeta());
+    const result = await provider.send(text, {
+        target: to,
+        thread: opts.thread,
+        attachments: opts.attachment,
+        from: opts.from,
+        dryRun: opts.dryRun,
+    });
+    if (opts.json) {
+        console.log(JSON.stringify(result));
+        if (!result.ok)
+            process.exit(1);
+        return;
+    }
+    if (!result.ok) {
+        die(`send failed [${result.channel} → ${result.id}]: ${result.error ?? 'unknown error'}`);
+    }
+    const suffix = result.msgId ? chalk.dim(` (${result.msgId})`) : '';
+    const dry = opts.dryRun ? chalk.dim(' [dry-run]') : '';
+    console.log(chalk.green(`Sent via ${result.channel} → ${result.id}`) + suffix + dry);
+}
+export function registerSendCommand(program) {
+    program
+        .command('send <text>')
+        .description('Send a message through a channel provider (mailbox, telegram, imessage, slack, discord).')
+        .requiredOption('--channel <name>', 'channel / provider name')
+        .requiredOption('--to <target>', 'channel-specific recipient id')
+        .option('--thread <id>', 'channel thread id / timestamp')
+        .option('--attachment <path...>', 'file attachment path (repeatable)')
+        .option('--from <who>', 'sender label (mailbox)')
+        .option('--json', 'output JSON')
+        .option('--dry-run', 'resolve + build but do not send')
+        .action(async (text, opts) => {
+        await doSend(text, opts.channel, opts.to, opts);
+    });
+    program
+        .command('notify <text>')
+        .description('Notify the owner (channel + target default to notify.owner in agents.yaml).')
+        .option('--channel <name>', 'override owner channel')
+        .option('--to <target>', 'override owner target')
+        .option('--thread <id>', 'channel thread id / timestamp')
+        .option('--attachment <path...>', 'file attachment path (repeatable)')
+        .option('--json', 'output JSON')
+        .option('--dry-run', 'resolve + build but do not send')
+        .action(async (text, opts) => {
+        const owner = readMeta().notify?.owner;
+        const channel = opts.channel ?? owner?.channel;
+        const to = opts.to ?? owner?.to;
+        if (!channel || !to) {
+            die('notify: no --channel/--to given and no notify.owner.{channel,to} in agents.yaml. ' +
+                'Set notify.owner or pass --channel/--to.');
+        }
+        await doSend(text, channel, to, opts);
+    });
+}