@phnx-labs/agents-cli 1.20.63 → 1.20.65

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/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 ""
@@ -149,7 +149,7 @@ async function pickJob(message, filter, alternatives = [], cwd) {
             message,
             choices: jobs.map((job) => ({
                 value: job.name,
-                name: `${job.name} ${chalk.gray(`(${job.workflow ? `wf:${job.workflow}` : job.agent}, ${job.schedule ?? fireConditionLabel(job)})`)}`,
+                name: `${job.name} ${chalk.gray(`(${job.command ? 'command' : job.workflow ? `wf:${job.workflow}` : job.agent}, ${job.schedule ?? fireConditionLabel(job)})`)}`,
             })),
         });
     }
@@ -282,12 +282,14 @@ export function registerRoutinesCommands(program) {
                     name: job.name,
                     agent: job.agent ?? null,
                     workflow: job.workflow ?? null,
+                    command: job.command ?? null,
                     repo: job.repo ?? null,
                     schedule: job.schedule ?? null,
                     scheduleHuman: fireConditionLabel(job),
                     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),
@@ -339,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
@@ -356,9 +361,11 @@ export function registerRoutinesCommands(program) {
                     : lastStatus === 'timeout' ? chalk.yellow
                         : chalk.gray;
             const overdueTag = overdueSet.has(job.name) ? chalk.yellow(' (overdue)') : '';
-            const agentLabelPadded = job.workflow
-                ? chalk.magenta(`wf:${job.workflow}`.padEnd(10))
-                : (job.agent || '').padEnd(10);
+            const agentLabelPadded = job.command
+                ? chalk.magenta('command'.padEnd(10))
+                : job.workflow
+                    ? chalk.magenta(`wf:${job.workflow}`.padEnd(10))
+                    : (job.agent || '').padEnd(10);
             console.log(`  ${chalk.cyan(job.name.padEnd(NAME_W))} ${agentLabelPadded} ${repoCell}${' '.repeat(repoPadding)} ${deviceCell}${' '.repeat(devicePad)} ${schedStr.padEnd(SCHED_W)} ${enabledStr}${' '.repeat(enabledPad)} ${chalk.gray(nextStr.padEnd(NEXT_W))} ${statusColor(lastStatus)}${overdueTag}`);
         }
         if (overdueSet.size > 0) {
@@ -374,12 +381,15 @@ export function registerRoutinesCommands(program) {
         .option('-s, --schedule <cron>', 'Cron schedule in standard format (5 fields: minute hour day month weekday)')
         .option('-a, --agent <agent>', 'Which agent runs this routine: claude, codex, gemini, cursor, or opencode')
         .option('--workflow <name>', 'Run an installed workflow (~/.agents/workflows/<name>) via `agents run`. Mutually exclusive with --agent.')
+        .option('--command <sh>', 'Run a plain shell command directly (no agent, no auth, no sandbox) — for deterministic housekeeping routines. Mutually exclusive with --agent and --workflow; --prompt is not used.')
         .option('-p, --prompt <prompt>', 'Task instruction for the agent')
         .option('-m, --mode <mode>', "Execution mode: plan (read-only), edit (can write files), auto (smart classifier, the default), or skip (bypass all permission prompts). 'full' accepted as alias for skip.", 'auto')
         .option('-e, --effort <effort>', 'Reasoning effort: low | medium | high | xhigh | max | auto', 'auto')
         .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>')
@@ -392,7 +402,7 @@ export function registerRoutinesCommands(program) {
         .option('--resume <sessionId>', 'At fire time, resume this existing session id (via `agents run <agent> --resume`) instead of starting fresh — the actual session reopens with full context and the prompt becomes its next turn. Powers self-scheduled wake-ups (e.g. /hibernate). Requires --agent claude or codex; runs un-sandboxed (the session store lives in the real home, not the job overlay).')
         .action(async (nameOrPath, options) => {
         // Check if inline mode (has flags) or file mode
-        const hasInlineFlags = options.schedule || options.agent || options.workflow || options.prompt || options.at || options.on;
+        const hasInlineFlags = options.schedule || options.agent || options.workflow || options.command || options.prompt || options.at || options.on;
         if (hasInlineFlags) {
             // Inline mode: create job from flags
             if (!nameOrPath) {
@@ -400,9 +410,9 @@ export function registerRoutinesCommands(program) {
                 console.log(chalk.gray('Usage: agents routines add <name> --schedule "..." --agent <agent> --prompt "..."'));
                 process.exit(1);
             }
-            // Validate mutually exclusive --agent / --workflow
-            if (options.agent && options.workflow) {
-                console.log(chalk.red('--agent and --workflow are mutually exclusive; specify exactly one'));
+            // Validate mutually exclusive --agent / --workflow / --command
+            if ([options.agent, options.workflow, options.command].filter(Boolean).length > 1) {
+                console.log(chalk.red('--agent, --workflow, and --command are mutually exclusive; specify exactly one'));
                 process.exit(1);
             }
             let schedule = options.schedule;
@@ -430,11 +440,12 @@ export function registerRoutinesCommands(program) {
                 console.log(chalk.red('Schedule or trigger is required (use --schedule, --at, or --on)'));
                 process.exit(1);
             }
-            if (!options.agent && !options.workflow) {
-                console.log(chalk.red('An agent or workflow is required (use --agent or --workflow)'));
+            if (!options.agent && !options.workflow && !options.command) {
+                console.log(chalk.red('An agent, workflow, or command is required (use --agent, --workflow, or --command)'));
                 process.exit(1);
             }
-            if (!options.prompt) {
+            // Command routines run a plain shell and take no prompt; agent/workflow routines require one.
+            if (!options.command && !options.prompt) {
                 console.log(chalk.red('Prompt is required (use --prompt)'));
                 process.exit(1);
             }
@@ -443,19 +454,29 @@ 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 } : {}),
                 ...(trigger ? { trigger } : {}),
-                agent: options.agent,
+                ...(options.agent ? { agent: options.agent } : {}),
                 ...(options.workflow ? { workflow: options.workflow } : {}),
+                ...(options.command ? { command: options.command } : {}),
                 mode: options.mode,
                 effort: options.effort,
                 timeout: options.timeout,
                 enabled: !options.disabled,
-                prompt: options.prompt,
+                prompt: options.prompt ?? '',
                 timezone: options.timezone,
                 ...(devices ? { devices } : {}),
+                ...(options.runOn ? { host: options.runOn } : {}),
+                ...(options.runCwd ? { remoteCwd: options.runCwd } : {}),
                 ...(runOnce ? { runOnce: true } : {}),
                 ...(options.endAt ? { endAt: options.endAt } : {}),
                 ...(options.resume ? { resume: options.resume } : {}),
@@ -514,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();
@@ -664,7 +691,7 @@ export function registerRoutinesCommands(program) {
             console.log(chalk.gray(`  ${eligibility.suggestion}`));
             process.exit(1);
         }
-        const runLabel = job.workflow ? `workflow: ${job.workflow}` : `agent: ${job.agent}`;
+        const runLabel = job.command ? 'command' : job.workflow ? `workflow: ${job.workflow}` : `agent: ${job.agent}`;
         console.log(chalk.bold(`Running job '${name}' (${runLabel}, mode: ${job.mode})\n`));
         const spinner = ora('Executing...').start();
         try {

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]')