@phnx-labs/agents-cli 1.20.64 → 1.20.66

package/dist/commands/output.js

@@ -10,7 +10,7 @@ import { formatUsd, PRICING_VERSION } from '../lib/pricing/index.js';
 import { formatDuration } from '../lib/session/render.js';
 import { terminalWidth, truncateToWidth, padToWidth } from '../lib/session/width.js';
 import { collectGitOutput } from '../lib/output/git-output.js';
-import { loadDevices } from '../lib/devices/registry.js';
+import { loadDevices, isControlDevice } from '../lib/devices/registry.js';
 import { machineId } from '../lib/session/sync/config.js';
 const execFileAsync = promisify(execFile);
 export function registerOutputCommand(program) {
@@ -154,7 +154,7 @@ async function outputAction(options) {
     const self = machineId();
     const registry = await loadDevices();
     const remotes = Object.values(registry)
-        .filter(d => d.tailscale?.online && d.name !== self)
+        .filter(d => d.tailscale?.online && d.name !== self && !isControlDevice(d))
         .map(d => d.name);
     if (!options.json)
         console.error(chalk.gray(`Folding in ${remotes.length} online device${remotes.length !== 1 ? 's' : ''}…`));

package/dist/commands/plugins.js

@@ -573,6 +573,7 @@ Examples:
     pluginsCmd
         .command('update [name]')
         .description('Re-pull a plugin from its original source and re-sync to all versions')
+        .option('--allow-exec-surfaces', 'Consent to an update that introduces new executable surfaces (hooks/, bin/, scripts/, .mcp.json, settings.json, permissions/)')
         .addHelpText('after', `
 Examples:
   # Update a specific plugin
@@ -580,8 +581,11 @@ Examples:
 
   # Update all plugins
   agents plugins update
+
+  # Trust an update that adds new executable surfaces
+  agents plugins update rush-toolkit --allow-exec-surfaces
 `)
-        .action(async (nameArg) => {
+        .action(async (nameArg, options) => {
         const plugins = nameArg ? [getPlugin(nameArg)].filter(Boolean) : discoverPlugins();
         if (nameArg && plugins.length === 0) {
             console.log(chalk.red(`Plugin '${nameArg}' not found`));
@@ -591,24 +595,41 @@ Examples:
             console.log(chalk.gray('No plugins installed.'));
             return;
         }
+        const allowExec = options.allowExecSurfaces === true;
         for (const plugin of plugins) {
             process.stdout.write(`Updating ${plugin.name}... `);
-            const result = await updatePlugin(plugin.name);
+            const result = await updatePlugin(plugin.name, { allowExecSurfaces: allowExec });
             if (!result.success) {
-                console.log(chalk.red(`failed — ${result.error || 'unknown error'}`));
+                if (result.blockedByExecSurfaces) {
+                    // Security (RUSH-1757): the update introduced new executable surfaces.
+                    // Refuse without renewed consent; the last-good content stays in place.
+                    console.log(chalk.yellow('skipped'));
+                    console.log(chalk.yellow(`  Update introduces new executable surfaces: ${(result.newExecSurfaces || []).join(', ')}`));
+                    console.log(chalk.gray('  Kept the currently-installed revision. Re-run with --allow-exec-surfaces if you trust the source.'));
+                }
+                else {
+                    console.log(chalk.red(`failed — ${result.error || 'unknown error'}`));
+                }
                 continue;
             }
             console.log(chalk.green('done'));
-            // Re-sync to all supported installed versions
+            // Reload the plugin so the re-sync reads the freshly-applied revision.
+            const updated = getPlugin(plugin.name) ?? plugin;
+            // Re-sync to all supported installed versions. When the applied revision
+            // carries executable surfaces, only enable them if the user consented on
+            // this update (--allow-exec-surfaces); otherwise the benign content syncs
+            // but stays disabled, matching the install-time trust gate.
             for (const agentId of capableAgents('plugins')) {
-                if (!pluginSupportsAgent(plugin, agentId))
+                if (!pluginSupportsAgent(updated, agentId))
                     continue;
                 const versions = listInstalledVersions(agentId);
                 const defaultVer = getGlobalDefault(agentId);
                 const targetVersions = defaultVer ? [defaultVer] : versions.slice(-1);
                 for (const version of targetVersions) {
-                    const syncResult = syncResourcesToVersion(agentId, version, { plugins: [plugin.name] });
-                    if (syncResult.plugins.length > 0) {
+                    const didSync = allowExec
+                        ? syncPluginToVersion(updated, agentId, getVersionHomePath(agentId, version), { allowExecSurfaces: true, version }).success
+                        : syncResourcesToVersion(agentId, version, { plugins: [updated.name] }).plugins.length > 0;
+                    if (didSync) {
                         console.log(chalk.gray(`  Re-synced to ${agentLabel(agentId)}@${version}`));
                     }
                 }

package/dist/commands/routines.js

@@ -23,7 +23,7 @@ import { detectOverdueJobs } from '../lib/overdue.js';
 import { isInteractiveTerminal, requireInteractiveSelection } from './utils.js';
 import { setHelpSections } from '../lib/help.js';
 import { loadDevices } from '../lib/devices/registry.js';
-import { normalizeHost } from '../lib/machine-id.js';
+import { machineId, normalizeHost } from '../lib/machine-id.js';
 import { addHostOption } from '../lib/hosts/option.js';
 /**
  * Human-friendly wall-clock a run took (e.g. "  · 3 min", "  · 45 sec"), or ""
@@ -289,6 +289,7 @@ export function registerRoutinesCommands(program) {
                     trigger: job.trigger ?? null,
                     timezone: job.timezone ?? null,
                     devices: job.devices ?? [],
+                    host: job.host ?? null,
                     runsHere: jobRunsOnThisDevice(job),
                     enabled: job.enabled,
                     overdue: overdueSet.has(job.name),
@@ -340,7 +341,10 @@ export function registerRoutinesCommands(program) {
             // chalk adds escape codes; pad the raw word and let chalk wrap it.
             const enabledWord = job.enabled ? 'yes' : 'no';
             const enabledPad = Math.max(0, ENABLED_W - enabledWord.length);
-            const deviceFull = job.devices?.join(',') ?? '';
+            // Placement (`→host`) rides in the Devices cell: eligibility →execution.
+            const deviceFull = [job.devices?.join(',') ?? '', job.host ? `→${job.host}` : '']
+                .filter(Boolean)
+                .join(' ');
             const deviceWord = deviceFull.length === 0
                 ? 'all'
                 : deviceFull.length > DEVICE_W
@@ -384,6 +388,8 @@ export function registerRoutinesCommands(program) {
         .option('-t, --timeout <timeout>', 'Kill the agent if it runs longer than this (e.g., 10m, 2h, 3d, 1w; max 1w)', '10m')
         .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('--run-on <name>', 'Execute the job body on this machine over SSH (a registered host, device, capability tag, or user@host). Placement, not eligibility — see --devices. Auto-pins devices to THIS machine unless --devices is given.')
+        .option('--run-cwd <dir>', 'Working directory on the --run-on host (--remote-cwd is taken by the remote-management passthrough)')
         .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>')
@@ -448,6 +454,13 @@ export function registerRoutinesCommands(program) {
             if (options.devices !== undefined) {
                 devices = await parseAndValidateDevices(options.devices);
             }
+            // --run-on without a --devices pin would fire on EVERY daemon in the
+            // fleet, each dispatching to the same host — duplicate runs. Pin to
+            // this machine unless the user chose an explicit eligibility set.
+            if (options.runOn && !devices) {
+                devices = [machineId()];
+                console.log(chalk.gray(`--run-on set with no --devices: pinned firing to this machine (${devices[0]}).`));
+            }
             const config = {
                 name: nameOrPath,
                 ...(schedule ? { schedule } : {}),
@@ -462,6 +475,8 @@ export function registerRoutinesCommands(program) {
                 prompt: options.prompt ?? '',
                 timezone: options.timezone,
                 ...(devices ? { devices } : {}),
+                ...(options.runOn ? { host: options.runOn } : {}),
+                ...(options.runCwd ? { remoteCwd: options.runCwd } : {}),
                 ...(runOnce ? { runOnce: true } : {}),
                 ...(options.endAt ? { endAt: options.endAt } : {}),
                 ...(options.resume ? { resume: options.resume } : {}),
@@ -520,6 +535,12 @@ export function registerRoutinesCommands(program) {
                 enabled: true,
                 ...parsed,
             };
+            // Same duplicate-fire guard as the --run-on flag: a host-placed routine
+            // with no eligibility pin would fire from every daemon in the fleet.
+            if (config.host && (!config.devices || config.devices.length === 0)) {
+                config.devices = [machineId()];
+                console.log(chalk.gray(`host: set with no devices pin: pinned firing to this machine (${config.devices[0]}).`));
+            }
             writeJob(config);
             console.log(chalk.green(`Job '${name}' added`));
             ensureSchedulerRunning();

package/dist/commands/secrets.d.ts

@@ -66,11 +66,27 @@ export declare function buildSecretsExecEnv(parentEnv: NodeJS.ProcessEnv, secret
  * parse, so multi-line values are rejected rather than silently corrupted.
  */
 export declare function bundleEnvToDotenv(env: Record<string, string>): string;
+/**
+ * Encrypt a resolved env map to an offline bundle file using AES-256-GCM
+ * (the same EncFile envelope as the per-item file store). Inner plaintext is
+ * JSON so multi-line values round-trip losslessly. Written with mode 0600;
+ * the passphrase must be supplied explicitly — never auto-provisioned.
+ */
+export declare function exportBundleToFile(env: Record<string, string>, filePath: string, passphrase: string): void;
+/**
+ * Decrypt and parse an offline bundle file produced by exportBundleToFile.
+ * Throws on a missing file, an invalid JSON envelope, or a wrong passphrase.
+ */
+export declare function importBundleFromFile(filePath: string, passphrase: string): Record<string, string>;
 /** The POLICY column for `secrets list`: the prompt policy, plus a concise
  * state hint. `daily` shows `held Nh` when the secrets-agent is currently
  * caching the bundle; `always` and `never` show whether they prompt. `held`
  * maps bundle name → expiry epoch-ms (from agentStatus()). */
 export declare function renderPolicyCol(b: SecretsBundle, held?: Map<string, number>): string;
+/** Human-readable hold window for `secrets status`. Sub-hour values render in
+ * minutes (so a near-floor `holdMs` never shows a confusing "0 hours"), whole
+ * hours up to 2 days, whole days beyond. Pure — unit-tested. */
+export declare function formatHoldWindow(ms: number): string;
 /** Register the `agents secrets` command tree. */
 export declare function registerSecretsCommands(program: Command): void;
 /** Validate a prompt-policy value, throwing a clear message on a bad one (the

package/dist/commands/secrets.js

@@ -16,10 +16,13 @@ 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, 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, } 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';
-import { DEFAULT_TTL_MS, agentLoad, agentLock, agentPing, agentStatus, ensureAgentRunning, runAgentLoadFromStdin, runSecretsAgent, uninstallSecretsAgentService, } from '../lib/secrets/agent.js';
+import { secretsHoldMs, agentLoad, agentLock, agentPing, agentStatus, ensureAgentRunning, runAgentLoadFromStdin, runSecretsAgent, uninstallSecretsAgentService, } from '../lib/secrets/agent.js';
+import { getCliVersionFresh } from '../lib/version.js';
+import { readMeta } from '../lib/state.js';
 import { parseDuration } from '../lib/hooks/cache.js';
 import { emit } from '../lib/events.js';
 import { registerCommandGroups, setHelpSections } from '../lib/help.js';
@@ -298,6 +301,52 @@ export function bundleEnvToDotenv(env) {
     }
     return lines.join('\n') + '\n';
 }
+/**
+ * Encrypt a resolved env map to an offline bundle file using AES-256-GCM
+ * (the same EncFile envelope as the per-item file store). Inner plaintext is
+ * JSON so multi-line values round-trip losslessly. Written with mode 0600;
+ * the passphrase must be supplied explicitly — never auto-provisioned.
+ */
+export function exportBundleToFile(env, filePath, passphrase) {
+    const enc = encryptForFallback(JSON.stringify(env), passphrase);
+    fs.writeFileSync(filePath, JSON.stringify(enc), { mode: 0o600 });
+}
+/**
+ * Decrypt and parse an offline bundle file produced by exportBundleToFile.
+ * Throws on a missing file, an invalid JSON envelope, or a wrong passphrase.
+ */
+export function importBundleFromFile(filePath, passphrase) {
+    const raw = fs.readFileSync(filePath, 'utf-8');
+    let enc;
+    try {
+        enc = JSON.parse(raw);
+    }
+    catch {
+        throw new Error(`Encrypted bundle file ${filePath} is corrupt (not valid JSON).`);
+    }
+    let plaintext;
+    try {
+        plaintext = decryptForFallback(enc, passphrase);
+    }
+    catch {
+        throw new Error(`Failed to decrypt bundle file ${filePath}. Wrong passphrase or tampered file.`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(plaintext);
+    }
+    catch {
+        throw new Error(`Decrypted bundle file ${filePath} has invalid content (expected JSON).`);
+    }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new Error(`Bundle file ${filePath} has unexpected structure.`);
+    }
+    const result = {};
+    for (const [k, v] of Object.entries(parsed)) {
+        result[k] = typeof v === 'string' ? v : String(v);
+    }
+    return result;
+}
 /**
  * Browse `agents secrets <args>` on one or more remote hosts over SSH and print
  * each host's stdout verbatim (lossless — no parsing). With >1 host the output
@@ -400,6 +449,22 @@ export function renderPolicyCol(b, held) {
     const exp = held?.get(b.name);
     return exp ? chalk.green(`daily · held ${compactRemaining(exp)}`) : chalk.gray('daily');
 }
+/** Human-readable hold window for `secrets status`. Sub-hour values render in
+ * minutes (so a near-floor `holdMs` never shows a confusing "0 hours"), whole
+ * hours up to 2 days, whole days beyond. Pure — unit-tested. */
+export function formatHoldWindow(ms) {
+    if (ms < 3_600_000) { // under an hour → minutes (never a confusing "0 hours")
+        const mins = Math.max(1, Math.round(ms / 60_000));
+        if (mins < 60)
+            return `${mins} minute${mins === 1 ? '' : 's'}`;
+        // 59.99m rounds to 60 — call it 1 hour rather than "60 minutes".
+    }
+    const hrs = Math.round(ms / 3_600_000);
+    if (hrs < 48)
+        return `${hrs} hour${hrs === 1 ? '' : 's'}`;
+    const days = Math.round(hrs / 24);
+    return `${days} day${days === 1 ? '' : 's'}`;
+}
 /** Below this width the fixed date columns no longer fit; `list` uses cards. */
 const SECRETS_WIDE = 96;
 /** Format a single bundle as a table row for the `secrets list` output. */
@@ -568,6 +633,51 @@ function countExpiringSoon(meta) {
     }
     return n;
 }
+/**
+ * Resolve an existing import target bundle (inheriting its backend) or create a
+ * new one with the requested backend. Refuses to silently downgrade a
+ * 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);
+    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.`);
+        }
+        return bundle;
+    }
+    return { name, backend: requestedBackend === 'file' ? 'file' : undefined, vars: {} };
+}
+/**
+ * Apply KEY=VALUE entries into a bundle (keychain item or plaintext literal),
+ * honoring `--force`, then persist. Returns the added/skipped tally. Shared by
+ * the .env, --from-file, and --from-ssh import paths.
+ */
+function applyEnvToBundle(bundle, env, opts) {
+    const store = bundleItemStore(bundle.backend, { noAcl: bundlePolicy(bundle) === 'never' });
+    let added = 0;
+    let skipped = 0;
+    for (const [key, value] of Object.entries(env)) {
+        if (!opts.force && key in bundle.vars) {
+            skipped++;
+            continue;
+        }
+        if (opts.allPlaintext) {
+            bundle.vars[key] = { value };
+        }
+        else {
+            const item = secretsKeychainItem(bundle.name, key);
+            store.set(item, value);
+            bundle.vars[key] = keychainRef(key);
+        }
+        added++;
+    }
+    writeBundle(bundle);
+    return { added, skipped };
+}
 /** Register the `agents secrets` command tree. */
 export function registerSecretsCommands(program) {
     const cmd = program
@@ -854,7 +964,10 @@ export function registerSecretsCommands(program) {
                 console.error(chalk.red(`Secrets bundle '${item}' not found.`));
                 process.exit(1);
             }
-            const { env } = readAndResolveBundleEnv(item, { caller: 'secrets get', keys: [key] });
+            // `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() });
             if (!(key in env)) {
                 console.error(chalk.red(`Key '${key}' not in bundle '${item}'.`));
                 process.exit(1);
@@ -1301,8 +1414,46 @@ Examples:
         .option('--backend <backend>', 'When creating the bundle: keychain (default) or file (passphrase-encrypted, headless-readable)', 'keychain')
         .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)')
+        .option('--from-ssh', 'Pull the bundle from a fleet peer over SSH and import it locally (requires --host)')
+        .option('--host <peer>', 'SSH peer to pull from when using --from-ssh (host alias or user@host)')
         .action(async (bundleName, opts) => {
         try {
+            // A single import can name only one source. --from-file / --from-ssh are
+            // early-return paths, so guard them against each other and the --from /
+            // --from-1password pair (which parseImportSource guards on its own).
+            const namedFileOrSsh = [
+                opts.fromFile ? '--from-file' : null,
+                opts.fromSsh ? '--from-ssh' : null,
+            ].filter(Boolean);
+            if (namedFileOrSsh.length > 1 || (namedFileOrSsh.length > 0 && (opts.from || opts.from1password))) {
+                throw new Error('--from-file, --from-ssh, and --from/--from-1password are mutually exclusive; pick one import source.');
+            }
+            if (opts.fromFile) {
+                const passphrase = process.env.AGENTS_SECRETS_PASSPHRASE ?? '';
+                if (!passphrase) {
+                    throw new Error('--from-file needs AGENTS_SECRETS_PASSPHRASE set to decrypt the bundle file.');
+                }
+                const env = importBundleFromFile(opts.fromFile, passphrase);
+                const resolvedBundleName = bundleName ?? (await pickBundleName('import into'));
+                const bundle = resolveImportBundle(resolvedBundleName, opts.backend);
+                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;
+            }
+            if (opts.fromSsh) {
+                if (!opts.host) {
+                    throw new Error('--from-ssh requires --host <peer>.');
+                }
+                assertValidSshTarget(opts.host);
+                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 { 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;
+            }
             const source = parseImportSource(opts);
             if (opts.purge && source.kind !== 'icloud') {
                 throw new Error('--purge only applies to --from icloud.');
@@ -1321,49 +1472,20 @@ Examples:
                 return;
             }
             const resolvedBundleName = bundleName ?? (await pickBundleName('import into'));
-            // Read the bundle if it exists (inheriting its backend); otherwise
-            // create it with the requested backend so a single `import --backend
-            // file` works (this is what `export --host ... --remote-backend file`
-            // drives on the remote).
-            let bundle;
-            if (bundleExists(resolvedBundleName)) {
-                bundle = readBundle(resolvedBundleName);
-                if (requestedBackend === 'file' && bundle.backend !== 'file') {
-                    throw new Error(`Bundle '${resolvedBundleName}' already exists with a keychain backend; ` +
-                        `--backend file cannot change it. Delete it first to recreate as file-backed.`);
-                }
-            }
-            else {
-                bundle = {
-                    name: resolvedBundleName,
-                    backend: requestedBackend === 'file' ? 'file' : undefined,
-                    vars: {},
-                };
-            }
-            const store = bundleItemStore(bundle.backend, { noAcl: bundlePolicy(bundle) === 'never' });
-            let added = 0;
-            let skipped = 0;
+            // resolveImportBundle inherits an existing bundle's backend (and refuses
+            // 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);
             if (source.kind === '1password') {
                 assertOpAvailable();
                 const vault = await resolveVault(source.vault);
                 const items = listItems(vault);
                 const { secrets, skipped: opSkipped } = extractSecrets(items, vault);
-                for (const { envKey, value } of secrets) {
-                    if (!opts.force && envKey in bundle.vars) {
-                        skipped++;
-                        continue;
-                    }
-                    if (opts.allPlaintext) {
-                        bundle.vars[envKey] = { value };
-                    }
-                    else {
-                        const item = secretsKeychainItem(resolvedBundleName, envKey);
-                        store.set(item, value);
-                        bundle.vars[envKey] = keychainRef(envKey);
-                    }
-                    added++;
-                }
-                writeBundle(bundle);
+                const env = {};
+                for (const { envKey, value } of secrets)
+                    env[envKey] = value;
+                const { added, skipped } = applyEnvToBundle(bundle, env, opts);
                 if (opSkipped.length) {
                     console.log(chalk.yellow(`Skipped ${opSkipped.length} item(s) with no importable fields.`));
                 }
@@ -1372,22 +1494,7 @@ Examples:
             else {
                 const raw = readImportDotenv(source.path);
                 const pairs = parseDotenv(raw);
-                for (const [key, value] of Object.entries(pairs)) {
-                    if (!opts.force && key in bundle.vars) {
-                        skipped++;
-                        continue;
-                    }
-                    if (opts.allPlaintext) {
-                        bundle.vars[key] = { value };
-                    }
-                    else {
-                        const item = secretsKeychainItem(resolvedBundleName, key);
-                        store.set(item, value);
-                        bundle.vars[key] = keychainRef(key);
-                    }
-                    added++;
-                }
-                writeBundle(bundle);
+                const { added, skipped } = applyEnvToBundle(bundle, pairs, opts);
                 console.log(chalk.green(`Imported ${added} key(s)${skipped ? `, skipped ${skipped} (already set, pass --force)` : ''}.`));
             }
         }
@@ -1408,10 +1515,22 @@ Examples:
         .option('--remote-backend <backend>', 'Backend for the bundle on the remote (with --host): keychain (default) or file (passphrase-encrypted, headless-readable). file forwards AGENTS_SECRETS_PASSPHRASE over stdin.', 'keychain')
         .option('--force', 'Overwrite existing keys/items on the target (used with --to-1password and --host)')
         .option('--format <shell|json>', 'Output for --plaintext export: shell (default) or json (lossless, machine-readable; used by remote resolve)', 'shell')
+        .option('--to-file <path>', 'Write the bundle as an AES-256-GCM encrypted offline file (needs AGENTS_SECRETS_PASSPHRASE; symmetric counterpart of import --from-file)')
         .action(async (bundleName, opts) => {
         try {
             const { readAndResolveBundleEnv, bundleToEnvPrefix, isReservedEnvName } = await import('../lib/secrets/bundles.js');
             const resolvedBundleName = bundleName ?? (await pickBundleName('export'));
+            if (opts.toFile) {
+                const passphrase = process.env.AGENTS_SECRETS_PASSPHRASE ?? '';
+                if (!passphrase) {
+                    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() });
+                exportBundleToFile(env, opts.toFile, passphrase);
+                console.log(chalk.green(`Exported ${Object.keys(env).length} key(s) to ${opts.toFile}`));
+                return;
+            }
             // The presence of --host selects SSH push: --host is the destination
             // and carries the mode (no separate --to-ssh needed — it would be
             // strictly redundant since SSH always requires at least one host).
@@ -1434,7 +1553,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` });
+                const { env } = readAndResolveBundleEnv(resolvedBundleName, { caller: `ssh export`, agentOnly: isHeadlessSecretsContext() });
                 const dotenv = bundleEnvToDotenv(env);
                 const keyCount = Object.keys(env).length;
                 // Drive the remote's own `agents secrets import --from -` so the values
@@ -1499,7 +1618,7 @@ Examples:
             if (opts.to1password) {
                 assertOpAvailable();
                 const vault = await resolveVault(opts.vault);
-                const { env } = readAndResolveBundleEnv(resolvedBundleName, { caller: `1Password vault ${vault}` });
+                const { env } = readAndResolveBundleEnv(resolvedBundleName, { caller: `1Password vault ${vault}`, agentOnly: isHeadlessSecretsContext() });
                 let created = 0;
                 let overwritten = 0;
                 let skipped = 0;
@@ -1537,7 +1656,15 @@ Examples:
                 console.error(chalk.red('export prints secrets in the clear and requires --plaintext (works for TTY and pipes alike).'));
                 process.exit(1);
             }
-            const { env } = readAndResolveBundleEnv(resolvedBundleName, { caller: `export to shell` });
+            // `agents secrets export --plaintext` is what release/CI scripts eval.
+            // When it runs detached (both stdio non-TTY) or under a headless agent,
+            // resolve broker-only so it can never pop a Touch ID sheet on the
+            // interactive user's screen. An interactive `eval "$(...)"` keeps its
+            // terminal stdin, so it is not headless and still prompts.
+            const { env } = readAndResolveBundleEnv(resolvedBundleName, {
+                caller: `export to shell`,
+                agentOnly: isHeadlessSecretsContext(),
+            });
             if (opts.format === 'json') {
                 // Lossless, machine-readable form consumed by `remoteResolveEnv` over
                 // SSH. Single object of KEY -> value; values verbatim (newlines, quotes).
@@ -1592,6 +1719,7 @@ Examples:
                     caller: `command ${cmd}`,
                     keys: keysSubset,
                     allowExpired: execOpts.allowExpired,
+                    agentOnly: isHeadlessSecretsContext(),
                 }).env;
             }
             const { spawn } = await import('child_process');
@@ -1760,7 +1888,7 @@ Examples:
             console.error(chalk.red('Specify one or more bundle names, or --all.'));
             process.exit(1);
         }
-        let ttlMs = DEFAULT_TTL_MS;
+        let ttlMs = secretsHoldMs(); // default hold, capped by secrets.agent.holdMs
         if (opts.ttl) {
             const secs = parseDuration(opts.ttl);
             if (!secs) {
@@ -1830,21 +1958,44 @@ Examples:
             console.log(chalk.gray('secrets-agent is macOS-only.'));
             return;
         }
-        const brokerUp = (await agentPing()).reachable;
+        const ping = await agentPing();
+        const brokerUp = ping.reachable;
         console.log(chalk.gray('broker: ') +
             (brokerUp
                 ? chalk.green('running') + chalk.gray(isDaemonRunning() ? ' (hosted by the daemon)' : ' (standalone)')
                 : chalk.yellow('not running — starts on demand, or run `agents secrets start` to bring the daemon up now')));
+        // Diagnostic: version skew is the top reason a `daily` bundle keeps
+        // re-prompting — a broker on an older build gets torn down when the CLI
+        // version changes (e.g. `agents-cli-update`), wiping every held bundle.
+        const onDisk = getCliVersionFresh();
+        if (brokerUp && ping.cliVersion && ping.cliVersion !== onDisk) {
+            console.log(chalk.yellow(`  warning: broker is running an older build (${ping.cliVersion} vs ${onDisk} on disk). ` +
+                `A version change can wipe held bundles — reads re-warm on the next access.`));
+        }
+        // Surface the hold window so "why did it prompt again" is answerable.
+        const holdStr = formatHoldWindow(secretsHoldMs());
+        // Only claim "(secrets.agent.holdMs)" when the config is actually honored —
+        // an invalid value (0/NaN/negative) falls back to the default via
+        // clampHoldMs, so it must read "(default)", not misattribute to config.
+        const configured = (() => { try {
+            const v = readMeta().secrets?.agent?.holdMs;
+            return typeof v === 'number' && Number.isFinite(v) && v > 0;
+        }
+        catch {
+            return false;
+        } })();
+        console.log(chalk.gray(`hold: ${holdStr}${configured ? ' (secrets.agent.holdMs)' : ' (default)'} — a daily bundle prompts once, then stays silent for this long or until sleep/logout.`));
         const entries = await agentStatus();
         if (entries.length === 0) {
-            console.log(chalk.gray('No bundles unlocked. The secrets broker is idle or not running.'));
-            console.log(chalk.gray('Try: agents secrets unlock <bundle>'));
+            console.log(chalk.gray('No bundles held. The next read of each daily bundle will prompt once, then hold.'));
+            console.log(chalk.gray('Pre-warm now with: agents secrets unlock <bundle>  (or --all)'));
             return;
         }
         console.log(chalk.bold(`${'BUNDLE'.padEnd(24)} ${'KEYS'.padEnd(5)} LOCKS IN`));
         for (const e of entries) {
             console.log(`${chalk.cyan(e.name.padEnd(24))} ${String(e.keyCount).padEnd(5)} ${humanRemaining(e.expiresAt)}`);
         }
+        console.log(chalk.gray('Reads of held bundles are silent; any bundle not listed prompts once on its next read.'));
     });
     cmd
         .command('policy <bundle> [policy]')

package/dist/commands/serve.js

@@ -1,15 +1,46 @@
 import chalk from 'chalk';
 import { startServeServer, DEFAULT_SERVE_PORT, SERVE_HOST } from '../lib/serve/server.js';
+import { startControlServer } from '../lib/serve/control.js';
+import { ensureControlToken } from '../lib/serve/token.js';
 export function registerServeCommand(program) {
     program
         .command('serve')
         .description('Read-only local web companion: team diffs, routines, and cloud status (binds 127.0.0.1 only).')
         .option('-p, --port <n>', `Port to bind on ${SERVE_HOST}`, String(DEFAULT_SERVE_PORT))
         .option('--interval <ms>', 'SSE refresh cadence in milliseconds', '3000')
+        .option('--control', 'Authenticated control mode (RUSH-1731): adds bearer-gated POST /api/run and /api/session/:id/message so the iOS cockpit can dispatch + steer. Enables binding beyond loopback — pair a device with `agents devices pair-ios`.', false)
+        .option('--bind <addr>', 'Address to bind in --control mode (e.g. your tailnet IP, or 0.0.0.0). Ignored without --control; read-only serve is always loopback.', SERVE_HOST)
         .action(async (opts) => {
         const port = parseInt(opts.port ?? '', 10) || DEFAULT_SERVE_PORT;
         const intervalMs = parseInt(opts.interval ?? '', 10) || 3000;
         try {
+            if (opts.control) {
+                const bind = opts.bind || SERVE_HOST;
+                const minted = ensureControlToken('default');
+                const { server, port: bound } = await startControlServer(port, bind, {
+                    cwd: process.cwd(),
+                    intervalMs,
+                });
+                const url = `http://${bind}:${bound}`;
+                console.log(`${chalk.green('agents serve --control')} ${chalk.dim('→')} ${chalk.cyan(url)}`);
+                if (minted.created) {
+                    console.log(chalk.yellow('New control token (shown once — store it in the cockpit now):'));
+                    console.log(`  ${chalk.bold(minted.token)}  ${chalk.dim(`(id ${minted.id})`)}`);
+                }
+                else {
+                    console.log(chalk.dim('Using existing control token(s). Issue another with `agents devices pair-ios`.'));
+                }
+                if (bind !== SERVE_HOST) {
+                    console.log(chalk.dim('bearer-gated · bind beyond loopback — keep this on the tailnet, never public Funnel · Ctrl-C to stop'));
+                }
+                else {
+                    console.log(chalk.dim('bearer-gated · loopback (pass --bind <tailnet-ip> to reach it from the phone) · Ctrl-C to stop'));
+                }
+                const shutdown = () => server.close(() => process.exit(0));
+                process.on('SIGINT', shutdown);
+                process.on('SIGTERM', shutdown);
+                return;
+            }
             const { server, port: bound } = await startServeServer(port, {
                 cwd: process.cwd(),
                 intervalMs,