@phnx-labs/agents-cli 1.20.18 → 1.20.20

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 ## Unreleased
 
+**`agents secrets start`: persistent secrets-agent service (fixes the broker under heavy load)**
+
+- On a heavily-loaded machine (many concurrent agents, high load average) the on-demand broker — a full CLI cold-start — couldn't get scheduled enough CPU to finish booting and bind its socket, so `unlock`/auto-cache silently failed and reads kept prompting. New `agents secrets start` installs the broker as a **launchd user service** (`RunAtLoad` + `KeepAlive`, `ProcessType: Interactive` for foreground scheduling priority): it starts once and stays up for the whole login session, so every read just connects — the cold start happens once (and launchd retries until it wins), never per read. `agents secrets stop` removes it; `agents secrets status` shows whether it's installed.
+- `unlock` and the auto-cache worker now install/kickstart this service automatically via `ensureAgentRunning`, falling back to the old one-off detached spawn only if the service path is unavailable. So the persistent broker is set up on first use with no extra step.
+- macOS only. Security model unchanged: in-memory only, per-bundle TTL, wiped on screen-lock/sleep.
+
+**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, installSecretsAgentService, runAgentLoadFromStdin, runSecretsAgent, secretsAgentServiceInstalled, uninstallSecretsAgentService, } 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) {
@@ -412,7 +416,7 @@ export function registerSecretsCommands(program) {
     registerCommandGroups(cmd, [
         { title: 'Bundle commands', names: ['list', 'view', 'create', 'rename', 'describe', 'delete'] },
         { title: 'Secret commands', names: ['add', 'rotate', 'remove', 'import', 'export'] },
-        { title: 'Agent commands', names: ['unlock', 'lock', 'status', 'tier'] },
+        { title: 'Agent commands', names: ['start', 'stop', 'unlock', 'lock', 'status', 'tier'] },
         { title: 'Raw item commands', names: ['get', 'set'] },
         { title: 'Sync commands', names: ['push', 'pull', 'remote-list'] },
         { title: 'Utilities', names: ['exec', 'generate', 'migrate-acl'] },
@@ -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',
                     });
@@ -1296,6 +1363,10 @@ Examples:
             console.log(chalk.gray('secrets-agent is macOS-only.'));
             return;
         }
+        console.log(chalk.gray('service: ') +
+            (secretsAgentServiceInstalled()
+                ? chalk.green('installed (persistent)')
+                : chalk.yellow('not installed — run `agents secrets start` for a persistent broker')));
         const entries = await agentStatus();
         if (entries.length === 0) {
             console.log(chalk.gray('No bundles unlocked. The secrets-agent is idle or not running.'));
@@ -1330,11 +1401,44 @@ Examples:
             process.exit(1);
         }
     });
+    cmd
+        .command('start')
+        .description('Install + start the secrets-agent as a persistent background service (macOS). Survives heavy load; reads connect instantly.')
+        .action(async () => {
+        if (process.platform !== 'darwin') {
+            console.error(chalk.red('secrets-agent service is macOS-only.'));
+            process.exit(1);
+        }
+        process.stdout.write(chalk.gray('Installing launchd service…\n'));
+        if (await installSecretsAgentService()) {
+            console.log(chalk.green('secrets-agent service running.') + chalk.gray(' It stays up across the session; unlock/auto-cache now connect instantly.'));
+        }
+        else {
+            console.error(chalk.red('Service installed but did not become reachable in time (machine may be heavily loaded — launchd will keep retrying).'));
+            process.exit(1);
+        }
+    });
+    cmd
+        .command('stop')
+        .description('Stop + remove the persistent secrets-agent service and wipe what it held.')
+        .action(async () => {
+        if (process.platform !== 'darwin')
+            return;
+        await uninstallSecretsAgentService();
+        console.log(chalk.green('secrets-agent service stopped and removed.'));
+    });
     cmd
         .command('_agent-run', { hidden: true })
         .description('Run the secrets-agent broker in the foreground (internal)')
+        .option('--service', 'run as a persistent launchd service (never idle-exit)')
+        .action(async (opts) => {
+        await runSecretsAgent({ service: Boolean(opts.service) });
+    });
+    cmd
+        .command('_agent-load', { hidden: true })
+        .description('Detached auto-cache worker: load a bundle from stdin into the broker (internal)')
         .action(async () => {
-        await runSecretsAgent();
+        await runAgentLoadFromStdin();
     });
     registerSecretsSyncCommands(cmd);
     registerSecretsMigrateAclCommand(cmd);
@@ -1353,6 +1457,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/commands/versions.js

@@ -105,7 +105,13 @@ async function versionPruneAction(specs, options, commandName) {
         }
         const { agent, version } = parsed;
         const agentConfig = AGENTS[agent];
-        if (version === 'latest' || version === 'oldest' || !spec.includes('@')) {
+        // Script-installed agents (droid, grok) can have a *literal* `latest`
+        // version dir on disk when the post-install version probe failed. An
+        // explicit `<agent>@latest` should remove that dir directly rather than
+        // routing to the interactive picker (which can't run non-interactively),
+        // so treat an installed literal `latest` as a concrete pinned version.
+        const isLiteralLatestInstalled = version === 'latest' && spec.includes('@') && isVersionInstalled(agent, 'latest');
+        if (!isLiteralLatestInstalled && (version === 'latest' || version === 'oldest' || !spec.includes('@'))) {
             const versions = listInstalledVersions(agent);
             if (versions.length === 0) {
                 console.log(chalk.gray(`No versions of ${agentLabel(agentConfig.id)} installed`));

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

@@ -37,6 +37,17 @@ export interface AgentStatusEntry {
     expiresAt: number;
     keyCount: number;
 }
+/** True if the launchd plist for the persistent broker is installed. */
+export declare function secretsAgentServiceInstalled(): boolean;
+/**
+ * Install + start the persistent broker as a launchd user service (idempotent).
+ * Writes the plist, bootstraps it into the GUI domain, and waits for the socket.
+ * `ProcessType: Interactive` asks launchd to schedule it at foreground priority
+ * so it can boot even when the machine is loaded. Returns true once reachable.
+ */
+export declare function installSecretsAgentService(timeoutMs?: number): Promise<boolean>;
+/** Stop + remove the persistent broker service, and wipe whatever it held. */
+export declare function uninstallSecretsAgentService(): Promise<void>;
 export type Request = {
     cmd: 'ping';
 } | {
@@ -95,7 +106,9 @@ export declare function handleAgentRequest(store: Map<string, StoredBundle>, req
  * `agents secrets _agent-run`. Holds the store in memory, serves the socket,
  * sweeps expired entries, wipes on screen-lock/sleep, and self-exits when idle.
  */
-export declare function runSecretsAgent(): Promise<void>;
+export declare function runSecretsAgent(opts?: {
+    service?: boolean;
+}): Promise<void>;
 /** True if a broker socket exists at all. Cheap; gates the sync read so the
  * never-unlocked path stays a single stat. */
 export declare function agentSocketExists(): boolean;
@@ -115,10 +128,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
@@ -127,8 +153,13 @@ export declare function agentLock(name?: string): Promise<number>;
 /** List currently-unlocked bundles, or [] when no broker is running. */
 export declare function agentStatus(): Promise<AgentStatusEntry[]>;
 /**
- * Ensure a broker is running and reachable, spawning one detached if not.
- * Returns true once the socket answers a ping. On protocol-version skew, kills
- * the stale broker and respawns. macOS only.
+ * Ensure a broker is running and reachable. Returns true once the socket answers
+ * a ping. macOS only.
+ *
+ * Prefers the persistent launchd service: if it isn't installed we install it
+ * (which makes the broker survive for the whole login session, so subsequent
+ * reads never cold-start); if it's installed but unreachable we kickstart it.
+ * Only when the service path can't be used do we fall back to a one-off detached
+ * broker — that's the model that gets starved under heavy load, so it's last.
  */
 export declare function ensureAgentRunning(timeoutMs?: number): Promise<boolean>;