@phnx-labs/agents-cli 1.20.18 → 1.20.19

package/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## Unreleased
 
+**Fix: secrets-agent auto-cache now survives a slow broker cold-start under load**
+
+- `secrets.agent.auto` (auto-cache on first read of a `session`-tier bundle) used a fire-and-forget inline loader that gave up connecting to the broker after 3s. But the broker it spawns is itself a full CLI cold-starting; under heavy load (many concurrent agents) that can exceed 3s, so the loader quit before the broker bound and the cache silently never populated — every read kept prompting. The auto-load now runs through a detached `secrets _agent-load` worker that reuses the robust `ensureAgentRunning` path (spawn-then-ping, 20s budget) and loads synchronously, so it reliably populates even when the broker is slow to start. Manual `agents secrets unlock` was always reliable and is unchanged. (secret values still travel over stdin, never argv.)
+
 **`agents secrets unlock`: a secrets-agent that ends Touch ID prompt spam (macOS)**
 
 - macOS pops a Touch ID prompt **per bundle, per process** — the biometry assertion is process-local and macOS refuses to cache `kSecAccessControl`+biometry items, so running several agents at once (`agents teams`, parallel `agents run --secrets`) re-prompts once per process. New `agents secrets unlock <bundle>` reads the bundle once (one prompt) and holds the resolved env in a local broker; every later resolution — `agents run`, teammates, browser profiles, the routines daemon — is served from memory over a user-only Unix socket (`~/.agents/.cache/helpers/secrets-agent/`, `0700`) with no prompt. `agents secrets lock` wipes it; `agents secrets status` shows what's held and when it locks. The hold also ends on TTL expiry (default 24h, `--ttl`) and on screen-lock / sleep.

package/dist/commands/secrets.js

@@ -8,10 +8,10 @@
 import chalk from 'chalk';
 import * as fs from 'fs';
 import { spawnSync } from 'child_process';
-import { bundleExists, bundleTier, deleteBundle, describeBundle, keychainItemsForBundle, keychainRef, listBundles, migrateLegacyBundles, parseDotenv, readAndResolveBundleEnv, readBundle, renameBundle, rotateBundleSecret, validateBundleName, validateEnvKey, validateExpiresFutureDated, validateSecretType, writeBundle, } from '../lib/secrets/bundles.js';
-import { deleteKeychainToken, getKeychainToken, getKeychainTokens, hasKeychainToken, secretsKeychainItem, setKeychainToken, } from '../lib/secrets/index.js';
+import { bundleExists, bundleItemStore, bundleTier, deleteBundle, describeBundle, keychainItemsForBundle, keychainRef, listBundles, migrateLegacyBundles, parseDotenv, readAndResolveBundleEnv, readBundle, renameBundle, rotateBundleSecret, validateBundleName, validateEnvKey, validateExpiresFutureDated, validateSecretType, writeBundle, } from '../lib/secrets/bundles.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, agentStatus, ensureAgentRunning, runSecretsAgent, } from '../lib/secrets/agent.js';
+import { DEFAULT_TTL_MS, agentLoad, agentLock, agentStatus, ensureAgentRunning, runAgentLoadFromStdin, runSecretsAgent, } from '../lib/secrets/agent.js';
 import { parseDuration } from '../lib/hooks/cache.js';
 import { registerCommandGroups, setHelpSections } from '../lib/help.js';
 import { isInteractiveTerminal, isPromptCancelled } from './utils.js';
@@ -235,7 +235,11 @@ function renderBundleRow(b) {
         `${padVisible(created, 9)} ` +
         `${padVisible(updated, 9)} ` +
         `${padVisible(used, 7)}`;
-    return b.description ? `${head} ${chalk.gray(safePrint(b.description))}` : head.trimEnd();
+    // Mark file-backed bundles so `list` distinguishes them from keychain ones.
+    const tag = b.backend === 'file' ? chalk.magenta('[file] ') : '';
+    const desc = b.description ? chalk.gray(safePrint(b.description)) : '';
+    const trailer = `${tag}${desc}`.trimEnd();
+    return trailer ? `${head} ${trailer}` : head.trimEnd();
 }
 /** Colorize a variable source kind (literal, keychain, env, file, exec). */
 function kindLabel(kind) {
@@ -449,6 +453,8 @@ export function registerSecretsCommands(program) {
                 console.log(chalk.gray(safePrint(bundle.description)));
             if (bundle.allow_exec)
                 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 (bundleTier(bundle) === 'session')
                 console.log(chalk.gray('tier: session (secrets-agent eligible)'));
             if (bundle.created_at)
@@ -573,12 +579,14 @@ export function registerSecretsCommands(program) {
         .option('--description <text>', 'Free-form description')
         .option('--allow-exec', 'Allow exec: refs in this bundle (off by default)')
         .option('--tier <tier>', 'secrets-agent tier: biometry (default) or session', 'biometry')
+        .option('--backend <backend>', 'storage backend: keychain (default) or file (passphrase-encrypted, headless-readable)', 'keychain')
         .option('--force', 'Overwrite an existing bundle')
         .action(async (name, opts) => {
         try {
             const resolvedName = name ?? (await promptBundleName());
             validateBundleName(resolvedName);
             const tier = parseTierOpt(opts.tier);
+            const backend = parseBackendOpt(opts.backend);
             if (bundleExists(resolvedName) && !opts.force) {
                 console.error(chalk.red(`Bundle '${resolvedName}' already exists. Use --force to overwrite.`));
                 process.exit(1);
@@ -587,11 +595,16 @@ export function registerSecretsCommands(program) {
                 name: resolvedName,
                 description: opts.description,
                 allow_exec: opts.allowExec,
+                backend: backend === 'file' ? 'file' : undefined,
                 tier,
                 vars: {},
             };
             writeBundle(bundle);
-            console.log(chalk.green(`Bundle '${resolvedName}' created${tier === 'session' ? ' (tier: session)' : ''}.`));
+            const tags = [tier === 'session' ? 'tier: session' : null, backend === 'file' ? 'backend: file' : null].filter(Boolean);
+            console.log(chalk.green(`Bundle '${resolvedName}' created${tags.length ? ` (${tags.join(', ')})` : ''}.`));
+            if (backend === 'file') {
+                console.log(chalk.gray('File-backed: items are AES-256-GCM encrypted under AGENTS_SECRETS_PASSPHRASE (no Touch ID).'));
+            }
             console.log(chalk.gray(`Try: agents secrets add ${resolvedName} MY_KEY`));
         }
         catch (err) {
@@ -711,7 +724,7 @@ export function registerSecretsCommands(program) {
                 console.log(chalk.green(`${resolvedBundleName}.${resolvedKey} = <literal>`));
                 return;
             }
-            // Default path: keychain-backed.
+            // Default path: stored in the bundle's backend (keychain or file).
             let secretValue;
             if (opts.valueStdin) {
                 secretValue = readStdinSync();
@@ -722,11 +735,12 @@ export function registerSecretsCommands(program) {
                 secretValue = await promptForSecret(`Enter value for ${resolvedBundleName}.${resolvedKey}`);
             }
             const item = secretsKeychainItem(resolvedBundleName, resolvedKey);
-            setKeychainToken(item, secretValue);
+            bundleItemStore(bundle.backend).set(item, secretValue);
             bundle.vars[resolvedKey] = keychainRef(resolvedKey);
             applyMeta();
             writeBundle(bundle);
-            console.log(chalk.green(`${resolvedBundleName}.${resolvedKey} stored in keychain (${item}).`));
+            const where = bundle.backend === 'file' ? 'encrypted file store' : 'keychain';
+            console.log(chalk.green(`${resolvedBundleName}.${resolvedKey} stored in ${where} (${item}).`));
         }
         catch (err) {
             if (isPromptCancelled(err))
@@ -831,9 +845,10 @@ Examples:
             writeBundle(bundle);
             if (willPurge) {
                 const item = secretsKeychainItem(resolvedBundleName, raw.slice('keychain:'.length));
-                const removed = deleteKeychainToken(item);
+                const removed = bundleItemStore(bundle.backend).delete(item);
                 if (removed) {
-                    console.log(chalk.green(`Removed ${resolvedBundleName}.${resolvedKey} and purged keychain item.`));
+                    const where = bundle.backend === 'file' ? 'encrypted file item' : 'keychain item';
+                    console.log(chalk.green(`Removed ${resolvedBundleName}.${resolvedKey} and purged ${where}.`));
                     return;
                 }
             }
@@ -875,8 +890,9 @@ Examples:
                 }
             }
             if (!opts.keepSecrets) {
+                const store = bundleItemStore(bundle.backend);
                 for (const { item } of keychainItemsForBundle(bundle)) {
-                    deleteKeychainToken(item);
+                    store.delete(item);
                 }
             }
             const existed = deleteBundle(resolvedName);
@@ -929,11 +945,12 @@ Examples:
     });
     cmd
         .command('import [bundle]')
-        .description('Import keys from a .env file or a 1Password vault into a bundle. By default every key is stored in keychain.')
+        .description('Import keys from a .env file or a 1Password vault into a bundle. The bundle is created if it does not exist. Values are stored in the bundle\'s backend (keychain by default).')
         .option('--from <path>', 'Path to a .env file')
         .option('--from-1password', 'Import secrets from a 1Password vault (requires the op CLI)')
         .option('--vault <name>', '1Password vault name (used with --from-1password)')
         .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('--force', 'Overwrite an existing key in the bundle')
         .action(async (bundleName, opts) => {
         try {
@@ -944,7 +961,27 @@ Examples:
                 throw new Error('--from and --from-1password are mutually exclusive.');
             }
             const resolvedBundleName = bundleName ?? (await pickBundleName('import into'));
-            const bundle = readBundle(resolvedBundleName);
+            const requestedBackend = parseBackendOpt(opts.backend);
+            // 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 --to-ssh --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);
             let added = 0;
             let skipped = 0;
             if (opts.from1password) {
@@ -962,7 +999,7 @@ Examples:
                     }
                     else {
                         const item = secretsKeychainItem(resolvedBundleName, envKey);
-                        setKeychainToken(item, value);
+                        store.set(item, value);
                         bundle.vars[envKey] = keychainRef(envKey);
                     }
                     added++;
@@ -986,7 +1023,7 @@ Examples:
                     }
                     else {
                         const item = secretsKeychainItem(resolvedBundleName, key);
-                        setKeychainToken(item, value);
+                        store.set(item, value);
                         bundle.vars[key] = keychainRef(key);
                     }
                     added++;
@@ -1010,6 +1047,7 @@ Examples:
         .option('--vault <name>', '1Password vault name (used with --to-1password)')
         .option('--to-ssh', 'Push the bundle to remote machine(s) over SSH via their native agents-cli import')
         .option('--host <target...>', 'SSH target(s) for --to-ssh: host alias or user@host (repeatable)')
+        .option('--remote-backend <backend>', 'Backend for the bundle on the remote: 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 --to-ssh)')
         .action(async (bundleName, opts) => {
         try {
@@ -1022,22 +1060,51 @@ Examples:
                 }
                 for (const h of hosts)
                     assertValidSshTarget(h);
+                const remoteBackend = parseBackendOpt(opts.remoteBackend);
+                // For a file-backed remote bundle the remote must encrypt at rest with
+                // a passphrase. We forward the LOCAL AGENTS_SECRETS_PASSPHRASE — the
+                // operator unlocks it once on this (trusted, biometry-gated) machine —
+                // and ship it as the FIRST stdin line so it never lands in argv / `ps`
+                // / the remote shell history. The remote `read -r` consumes that line;
+                // `agents secrets import --from /dev/stdin` reads the .env remainder.
+                let remotePassphrase = '';
+                if (remoteBackend === 'file') {
+                    remotePassphrase = process.env.AGENTS_SECRETS_PASSPHRASE ?? '';
+                    if (!remotePassphrase) {
+                        throw new Error('--remote-backend file needs AGENTS_SECRETS_PASSPHRASE set locally to encrypt the ' +
+                            '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 dotenv = bundleEnvToDotenv(env);
                 const keyCount = Object.keys(env).length;
-                // Drive the remote's own `agents secrets` CLI so values land in its native
-                // backend (Keychain on macOS, libsecret / encrypted-file on Linux). Create
-                // the bundle if missing, then import the piped .env. `bash -lc` so the login
-                // PATH resolves `agents`; the .env flows over ssh stdin and is never parsed
-                // by a remote shell.
+                // Drive the remote's own `agents secrets` CLI so values land in its
+                // chosen backend. `bash -lc` so the login PATH resolves `agents`; the
+                // .env (and, for file, the passphrase) flow over ssh stdin and are
+                // never parsed by a remote shell.
                 const force = opts.force ? ' --force' : '';
-                const remoteAgents = `agents secrets create ${shellQuote(resolvedBundleName)} >/dev/null 2>&1 || true; ` +
-                    `agents secrets import ${shellQuote(resolvedBundleName)} --from /dev/stdin${force}`;
+                const backendFlag = remoteBackend === 'file' ? ' --backend file' : '';
+                let remoteAgents;
+                let input;
+                if (remoteBackend === 'file') {
+                    // import --backend file auto-creates the file-backed bundle; no
+                    // separate `create` needed.
+                    remoteAgents =
+                        `IFS= read -r AGENTS_SECRETS_PASSPHRASE; export AGENTS_SECRETS_PASSPHRASE; ` +
+                            `agents secrets import ${shellQuote(resolvedBundleName)} --from /dev/stdin${backendFlag}${force}`;
+                    input = `${remotePassphrase}\n${dotenv}`;
+                }
+                else {
+                    remoteAgents =
+                        `agents secrets create ${shellQuote(resolvedBundleName)} >/dev/null 2>&1 || true; ` +
+                            `agents secrets import ${shellQuote(resolvedBundleName)} --from /dev/stdin${force}`;
+                    input = dotenv;
+                }
                 const remoteCmd = `bash -lc ${shellQuote(remoteAgents)}`;
                 let failures = 0;
                 for (const host of hosts) {
                     const res = spawnSync('ssh', ['-o', 'BatchMode=yes', host, remoteCmd], {
-                        input: dotenv,
+                        input,
                         stdio: ['pipe', 'pipe', 'pipe'],
                         encoding: 'utf-8',
                     });
@@ -1336,6 +1403,12 @@ Examples:
         .action(async () => {
         await runSecretsAgent();
     });
+    cmd
+        .command('_agent-load', { hidden: true })
+        .description('Detached auto-cache worker: load a bundle from stdin into the broker (internal)')
+        .action(async () => {
+        await runAgentLoadFromStdin();
+    });
     registerSecretsSyncCommands(cmd);
     registerSecretsMigrateAclCommand(cmd);
 }
@@ -1353,6 +1426,14 @@ function parseTierOpt(raw) {
     console.error(chalk.red(`Invalid --tier '${raw}'. Use 'biometry' or 'session'.`));
     process.exit(1);
 }
+/** Validate a --backend value, exiting with a clear message on a bad one. */
+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'.`));
+    process.exit(1);
+}
 /** Human-readable "locks in 3 hours" / "locks in 5 minutes" from an epoch-ms expiry. */
 function humanRemaining(expiresAt) {
     const ms = expiresAt - Date.now();

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

@@ -115,10 +115,23 @@ export declare function secretsAgentAutoEnabled(): boolean;
  * Fire-and-forget: populate the broker with a freshly-resolved bundle so the
  * NEXT process reads it without a prompt. Used by the auto-cache path after a
  * real keychain read of a `session`-tier bundle. Adds no latency to the caller
- * — it spawns the agent (if needed) and a detached loader, both unref'd, then
- * returns immediately. Entirely best-effort; never throws. macOS only.
+ * — it spawns a detached `secrets _agent-load` worker (passing the resolved env
+ * over stdin, never argv) and returns immediately.
+ *
+ * The worker reuses the robust `ensureAgentRunning` path (spawn-then-ping with a
+ * generous budget) rather than a tight inline retry loop: under heavy load the
+ * broker is itself a cold-starting full CLI and can take several seconds to bind
+ * the socket, so a short fixed budget would give up before it's ready and the
+ * cache would silently never populate. Best-effort; never throws. macOS only.
  */
 export declare function agentAutoLoadSync(name: string, bundle: SecretsBundle, env: Record<string, string>, ttlMs: number): void;
+/**
+ * Body of the hidden `secrets _agent-load` worker. Reads one `{name, bundle,
+ * env, ttlMs}` payload from stdin, ensures the broker is up (robust, generous
+ * budget), and loads the bundle into it. Detached from the originating read, so
+ * its latency is invisible — which is why it can afford a long ensure budget.
+ */
+export declare function runAgentLoadFromStdin(): Promise<void>;
 /** Store a resolved bundle in the broker. Returns false on transport failure. */
 export declare function agentLoad(name: string, bundle: SecretsBundle, env: Record<string, string>, ttlMs: number): Promise<boolean>;
 /** Wipe one bundle (or all if name omitted) from the broker. Returns the count

package/dist/lib/secrets/agent.js

@@ -61,24 +61,27 @@ function pidPath() {
     return path.join(agentDir(), 'agent.pid');
 }
 /**
- * Argv for re-invoking THIS cli to run the broker, so a side-by-side dev build
- * spawns its own broker rather than the registry-installed one. We always go
- * through `process.execPath` (the node binary) with the JS entrypoint as the
- * first arg — the entrypoint isn't reliably executable in dev builds (invoked
- * as `node dist/index.js`, no +x), so spawning it directly EACCES'd.
+ * Argv for re-invoking THIS cli with a hidden subcommand, so a side-by-side dev
+ * build spawns its own helpers rather than the registry-installed one. We always
+ * go through `process.execPath` (the node binary) with the JS entrypoint as the
+ * first arg — the entrypoint isn't reliably executable in dev builds (invoked as
+ * `node dist/index.js`, no +x), so spawning it directly EACCES'd.
  */
-function brokerSpawn() {
+function cliSpawn(sub) {
     const argv1 = process.argv[1];
     const entry = argv1 && fs.existsSync(argv1) ? argv1 : null;
     if (entry)
-        return { cmd: process.execPath, args: [entry, 'secrets', '_agent-run'] };
+        return { cmd: process.execPath, args: [entry, ...sub] };
     // No resolvable entrypoint (unusual) — fall back to the PATH shim.
     let bin = 'agents';
     try {
         bin = execFileSync('which', ['agents'], { encoding: 'utf-8' }).trim();
     }
     catch { /* default */ }
-    return { cmd: bin, args: ['secrets', '_agent-run'] };
+    return { cmd: bin, args: sub };
+}
+function brokerSpawn() {
+    return cliSpawn(['secrets', '_agent-run']);
 }
 // ─── Broker server (runs in the detached `secrets _agent-run` process) ───────
 /**
@@ -371,64 +374,60 @@ export function secretsAgentAutoEnabled() {
         return false;
     }
 }
-/**
- * Inline node program that loads one bundle into the broker, started detached
- * from the hot path. Reads the JSON payload from stdin (so secret values never
- * appear in argv / `ps`), retries the socket for a few seconds to absorb a
- * cold-started agent, sends the load, and exits. argv after -e: [execPath, <socket>].
- */
-const DETACHED_LOAD_PROGRAM = `
-const net = require('net');
-const sock = process.argv[1];
-let input = '';
-process.stdin.setEncoding('utf-8');
-process.stdin.on('data', (d) => { input += d; });
-process.stdin.on('end', () => {
-  let payload; try { payload = JSON.parse(input); } catch (e) { process.exit(1); }
-  let attempts = 0;
-  const tryConnect = () => {
-    const c = net.createConnection(sock);
-    c.on('connect', () => {
-      c.write(JSON.stringify({ cmd: 'load', name: payload.name, bundle: payload.bundle, env: payload.env, ttlMs: payload.ttlMs }) + '\\n');
-    });
-    c.setEncoding('utf-8');
-    c.on('data', () => { try { c.destroy(); } catch (e) {} process.exit(0); });
-    c.on('error', () => {
-      try { c.destroy(); } catch (e) {}
-      if (++attempts >= 30) process.exit(1);
-      setTimeout(tryConnect, 100);
-    });
-  };
-  tryConnect();
-});
-`;
 /**
  * Fire-and-forget: populate the broker with a freshly-resolved bundle so the
  * NEXT process reads it without a prompt. Used by the auto-cache path after a
  * real keychain read of a `session`-tier bundle. Adds no latency to the caller
- * — it spawns the agent (if needed) and a detached loader, both unref'd, then
- * returns immediately. Entirely best-effort; never throws. macOS only.
+ * — it spawns a detached `secrets _agent-load` worker (passing the resolved env
+ * over stdin, never argv) and returns immediately.
+ *
+ * The worker reuses the robust `ensureAgentRunning` path (spawn-then-ping with a
+ * generous budget) rather than a tight inline retry loop: under heavy load the
+ * broker is itself a cold-starting full CLI and can take several seconds to bind
+ * the socket, so a short fixed budget would give up before it's ready and the
+ * cache would silently never populate. Best-effort; never throws. macOS only.
  */
 export function agentAutoLoadSync(name, bundle, env, ttlMs) {
     if (!onDarwin())
         return;
     try {
-        if (!agentSocketExists()) {
-            const { cmd, args } = brokerSpawn();
-            spawn(cmd, args, { stdio: 'ignore', detached: true }).unref();
-        }
-        const loader = spawn(process.execPath, ['-e', DETACHED_LOAD_PROGRAM, socketPath()], {
-            stdio: ['pipe', 'ignore', 'ignore'],
-            detached: true,
-        });
-        loader.stdin?.write(JSON.stringify({ name, bundle, env, ttlMs }));
-        loader.stdin?.end();
-        loader.unref();
+        const { cmd, args } = cliSpawn(['secrets', '_agent-load']);
+        const worker = spawn(cmd, args, { stdio: ['pipe', 'ignore', 'ignore'], detached: true });
+        worker.stdin?.write(JSON.stringify({ name, bundle, env, ttlMs }));
+        worker.stdin?.end();
+        worker.unref();
     }
     catch {
         // best-effort: the next read just pops Touch ID as it would today
     }
 }
+/**
+ * Body of the hidden `secrets _agent-load` worker. Reads one `{name, bundle,
+ * env, ttlMs}` payload from stdin, ensures the broker is up (robust, generous
+ * budget), and loads the bundle into it. Detached from the originating read, so
+ * its latency is invisible — which is why it can afford a long ensure budget.
+ */
+export async function runAgentLoadFromStdin() {
+    if (!onDarwin())
+        return;
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(chunk);
+    let payload;
+    try {
+        payload = JSON.parse(Buffer.concat(chunks).toString('utf-8'));
+    }
+    catch {
+        return; // malformed payload — nothing to load
+    }
+    if (!payload || !payload.name || !payload.bundle || !payload.env)
+        return;
+    // Generous budget: the broker is a cold-starting full CLI; under load it can
+    // take several seconds to bind. We're detached, so waiting costs nothing.
+    if (!(await ensureAgentRunning(20000)))
+        return;
+    await agentLoad(payload.name, payload.bundle, payload.env, payload.ttlMs ?? DEFAULT_TTL_MS);
+}
 /** Store a resolved bundle in the broker. Returns false on transport failure. */
 export async function agentLoad(name, bundle, env, ttlMs) {
     const r = await request({ cmd: 'load', name, bundle, env, ttlMs });

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

@@ -1,17 +1,32 @@
 /**
- * Secret bundles — named sets of keychain-backed environment variables.
+ * Secret bundles — named sets of environment variables backed by a secret store.
  *
- * Bundle metadata (name, description, vars map) is stored in the macOS
- * Keychain as a JSON blob under `agents-cli.bundles.<name>`. Secret values
- * live one per keychain item under `agents-cli.secrets.<bundle>.<key>`.
- * Every item is device-local and gated by Touch ID / device passcode — see
- * src/lib/secrets/index.ts for the access-control story. Nothing about
- * secrets ever lives in plaintext on disk.
+ * Bundle metadata (name, description, vars map) is stored as a JSON blob under
+ * `agents-cli.bundles.<name>`; secret values live one per item under
+ * `agents-cli.secrets.<bundle>.<key>`. Two backends carry those items:
+ *
+ *  - `keychain` (default): the macOS Keychain (device-local, Touch ID / device
+ *    passcode gated) or Linux libsecret — see src/lib/secrets/index.ts.
+ *  - `file`: an AES-256-GCM encrypted-file store keyed by a passphrase
+ *    (src/lib/secrets/filestore.ts). Opt-in, for headless / remote runs where
+ *    no biometry prompt can be satisfied (e.g. a release on a remote Mac over
+ *    SSH). The item-name scheme is identical, so the only difference is where
+ *    bytes land. A file-backed bundle is discovered by the presence of its
+ *    metadata item in the file store.
  *
  * Cross-machine sync is handled by src/lib/secrets/sync.ts via an explicit
  * encrypted export/import flow; the bundle layer is sync-agnostic.
  */
 import { type BundleValue, type SecretRef } from './index.js';
+/** Which store carries a bundle's items. */
+export type SecretsBackend = 'keychain' | 'file';
+/**
+ * Discover a bundle's backend by location: a file-backed bundle's metadata
+ * item exists in the encrypted-file store. This is a plain file-existence
+ * check — no passphrase, no Touch ID — so it sidesteps the chicken-and-egg of
+ * "read metadata to learn where metadata lives." Absent ⇒ keychain.
+ */
+export declare function bundleBackend(name: string): SecretsBackend;
 /** Allowed values for a secret's `type` metadata field. */
 export declare const SECRET_TYPES: readonly ["api-key", "token", "password", "url", "database-url", "ssh-key", "certificate", "webhook", "note"];
 export type SecretType = typeof SECRET_TYPES[number];
@@ -38,6 +53,8 @@ export interface SecretsBundle {
     name: string;
     description?: string;
     allow_exec?: boolean;
+    /** Which store carries this bundle's items. Absent ⇒ `keychain` (the default). */
+    backend?: SecretsBackend;
     /** Secrets-agent interaction tier. Absent ⇒ `biometry` (the safe default). */
     tier?: SecretsTier;
     /** ISO 8601 UTC timestamp. Set once on the first writeBundle() for a bundle. */
@@ -156,6 +173,19 @@ export interface RenameOptions {
  * a safe no-op for the source items.
  */
 export declare function renameBundle(oldName: string, newName: string, opts?: RenameOptions): void;
+/**
+ * The store (keychain or encrypted file) that carries a bundle's items. The
+ * CLI uses this to read/write/delete per-key items (built with
+ * secretsKeychainItem) in the same store as the bundle's metadata, for `add` /
+ * `import` / `remove` / `delete`. Pass the bundle's resolved backend
+ * (`bundle.backend ?? 'keychain'`).
+ */
+export declare function bundleItemStore(backend: SecretsBackend | undefined): {
+    set(item: string, value: string): void;
+    delete(item: string): boolean;
+    get(item: string): string;
+    has(item: string): boolean;
+};
 export declare function keychainItemsForBundle(bundle: SecretsBundle): Array<{
     key: string;
     item: string;