@phnx-labs/agents-cli 1.22.84 → 1.22.86

package/dist/commands/secrets.js

@@ -1,3030 +0,0 @@
-/**
- * Secrets bundle management commands.
- *
- * Registers the `agents secrets` command tree for creating, viewing,
- * and managing named bundles of environment variables backed by macOS
- * Keychain. Bundles are injected at run time via `agents run --secrets`.
- */
-import { Option } from 'commander';
-import chalk from 'chalk';
-import { padVisible, readStdinSync } from '../lib/format.js';
-import { terminalWidth, truncateToWidth, stringWidth } from '../lib/session/width.js';
-import * as fs from 'fs';
-import * as os from 'os';
-import * as path from 'path';
-import { SSH_TARGET_RE, assertValidSshTarget } from '../lib/ssh-exec.js';
-import { quoteWin32ExecArg, composeWin32CommandLine } from '../lib/platform/index.js';
-import { ensureDaemonStarted, isDaemonRunning } from '../lib/daemon/daemon.js';
-import { parseHostsOption, remoteResolveEnv, remoteSecretsRaw, remoteSecretsStream, resolveHostSshTarget, } from '../lib/secrets/remote.js';
-import { resolveBundleForPush, pushResolvedBundleToHost, bundleEnvToDotenv } from '../lib/secrets/push.js';
-export { bundleEnvToDotenv };
-import { bundleBackend, bundleExists, bundleItemStore, bundlePolicy, deleteBundle, describeBundle, keychainItemsForBundle, keychainRef, listBundles, healKeychainBundleMetadataAclOnce, isHeadlessSecretsContext, isAgentInvocationContext, migrateLegacyBundles, parseDotenv, readAndResolveBundleEnv, readBundle, readBundleIfDecryptable, reAclBundleItems, renameBundle, rotateBundleSecret, sanitizeProcessEnv, validateBundleName, validateEnvKey, validateExpiresFutureDated, validateSecretType, writeBundle, writeBundleWithItems, assertFileBundleDecryptable, isReservedBundleName, ReservedBundleWrongBackendError, SECRET_TYPES, } from '../lib/secrets/bundles.js';
-import { parseListFilters, bundleMatchesFilter, bundleExpiry, filterIsActive, describeFilter, parseSortField, sortBundles, SORT_FIELDS, REF_KINDS, DEFAULT_EXPIRING_DAYS, } from '../lib/secrets/list-filter.js';
-import { encryptForFallback, decryptForFallback } from '../lib/secrets/filestore.js';
-import { getKeychainToken, hasKeychainToken, secretsKeychainItem, setKeychainToken, maybeAutoRekey, } from '../lib/secrets/index.js';
-import { assertOpAvailable, createPasswordItem, deleteItemByTitle, extractSecrets, itemExistsByTitle, listItems, listVaults, } from '../lib/onepassword.js';
-import { GLOBAL_HARNESS } from '../lib/secrets/scope.js';
-import { createSecretLease, selectLeasedEnv } from '../lib/secrets/lease.js';
-import { secretsHoldMs, secretsAgentDurable, agentLoad, agentLock, agentPing, agentStatus, ensureAgentRunning, runAgentLoadFromStdin, runSecretsAgent, uninstallSecretsAgentService, isSecretsBrokerEnabled, } from '../lib/secrets/agent.js';
-import { saveSession, deleteBundleSessions, deleteAllSessions } from '../lib/secrets/session-store.js';
-import { getCliVersionFresh } from '../lib/version.js';
-import { readMeta } from '../lib/state.js';
-import { parseDuration } from '../lib/hooks/cache.js';
-import { emit, query } from '../lib/feed/events.js';
-import { emitSecretAudit } from '../lib/secrets/audit.js';
-import { SYNC_PASSPHRASE_ENV, resolveSyncPassphraseFromEnv } from '../lib/secrets/sync-passphrase.js';
-import { getBundleUsage, getAllBundleUsage, getUsageHistory, SECRET_USAGE_EVENTS, } from '../lib/secrets/usage-db.js';
-import { frequentlyPromptedBundles } from '../lib/secrets/unlock-hints.js';
-import { registerCommandGroups, setHelpSections } from '../lib/help.js';
-import { isInteractiveTerminal, isPromptCancelled } from './utils.js';
-import { discoverSyncedBundles, importSyncedBundle, } from '../lib/secrets/icloud-import.js';
-import { registerSecretsSyncCommands } from './secrets-sync.js';
-import { registerSecretsMigrateAclCommand } from './secrets-migrate.js';
-import { registerSecretsImportKeyringCommand } from './secrets-import.js';
-import { registerSecretsRotatePassphraseCommand } from './secrets-rotate-passphrase.js';
-import { registerSecretsVaultCommands } from './secrets-vault.js';
-/** Prompt the user for a secret value with masked input. Requires an interactive TTY. */
-async function promptForSecret(message) {
-    if (!isInteractiveTerminal()) {
-        throw new Error('A secret is required but the shell is not interactive. Pass --value, --value-stdin, or run from a TTY.');
-    }
-    const { password } = await import('@inquirer/prompts');
-    return await password({ message, mask: true });
-}
-/** Prompt the user to pick an existing bundle by name. Requires an interactive TTY. */
-async function pickBundleName(action) {
-    const bundles = listBundles();
-    if (bundles.length === 0) {
-        throw new Error('No secrets bundles configured. Try: agents secrets create <name>');
-    }
-    if (!isInteractiveTerminal()) {
-        throw new Error('A bundle name is required. Pass it as an argument or run from a TTY.');
-    }
-    const { select } = await import('@inquirer/prompts');
-    return await select({
-        message: `Which bundle to ${action}?`,
-        choices: bundles.map((b) => ({
-            name: b.name,
-            value: b.name,
-            description: b.description || undefined,
-        })),
-    });
-}
-/** Prompt the user to type a new bundle name. Requires an interactive TTY. */
-async function promptBundleName() {
-    if (!isInteractiveTerminal()) {
-        throw new Error('A bundle name is required. Pass it as an argument or run from a TTY.');
-    }
-    const { input } = await import('@inquirer/prompts');
-    return await input({
-        message: 'Bundle name',
-        validate: (value) => {
-            try {
-                validateBundleName(value);
-                return true;
-            }
-            catch (err) {
-                return err.message;
-            }
-        },
-    });
-}
-/** Prompt the user to pick an existing key from a bundle. Requires an interactive TTY. */
-async function pickKey(bundle, action) {
-    const keys = Object.keys(bundle.vars);
-    if (keys.length === 0) {
-        throw new Error(`Bundle '${bundle.name}' has no keys.`);
-    }
-    if (!isInteractiveTerminal()) {
-        throw new Error('A key name is required. Pass it as an argument or run from a TTY.');
-    }
-    const { select } = await import('@inquirer/prompts');
-    return await select({
-        message: `Which key to ${action}?`,
-        choices: keys.map((k) => ({ name: k, value: k })),
-    });
-}
-/** Prompt the user to type a new key name for a bundle. Requires an interactive TTY. */
-async function promptKeyName(bundleName) {
-    if (!isInteractiveTerminal()) {
-        throw new Error('A key name is required. Pass it as an argument or run from a TTY.');
-    }
-    const { input } = await import('@inquirer/prompts');
-    return await input({
-        message: `Key name to add to '${bundleName}'`,
-        validate: (value) => {
-            try {
-                validateEnvKey(value);
-                return true;
-            }
-            catch (err) {
-                return err.message;
-            }
-        },
-    });
-}
-/** Resolve a 1Password vault name — use the provided value, or prompt interactively. */
-async function resolveVault(vaultOpt) {
-    if (vaultOpt)
-        return vaultOpt;
-    const vaults = listVaults();
-    if (vaults.length === 0)
-        throw new Error('No 1Password vaults found. Make sure you are signed in: op signin');
-    if (vaults.length === 1)
-        return vaults[0].name;
-    if (!isInteractiveTerminal()) {
-        throw new Error(`Multiple vaults found. Pass --vault <name> (available: ${vaults.map((v) => v.name).join(', ')})`);
-    }
-    const { select } = await import('@inquirer/prompts');
-    return await select({
-        message: 'Which 1Password vault?',
-        choices: vaults.map((v) => ({ name: v.name, value: v.name })),
-    });
-}
-/** Read all available data from stdin synchronously, trimmed. */
-/**
- * Read the raw `.env` text for `import --from <path|->`. A `-` reads the .env
- * from stdin (the SSH push path: `export --device` pipes the resolved dotenv over
- * ssh stdin, which has no `/dev/stdin` on a Windows remote); any other value is
- * a filesystem path.
- */
-export function readImportDotenv(from) {
-    return from === '-' ? readStdinSync() : fs.readFileSync(from, 'utf-8');
-}
-/**
- * Parse the unified `--from <source>` value: a .env path (`-` reads stdin),
- * `1password:<vault>` (bare `1password` prompts for the vault), or `icloud`
- * (legacy iCloud Keychain bundles). The deprecated `--from-1password --vault`
- * pair maps onto the 1password source. A file literally named `icloud` or
- * `1password` can still be imported via an explicit path (`./icloud`).
- */
-export function parseImportSource(opts) {
-    if (opts.from && opts.from1password) {
-        throw new Error('--from and --from-1password are mutually exclusive.');
-    }
-    if (opts.from1password)
-        return { kind: '1password', vault: opts.vault };
-    if (!opts.from) {
-        throw new Error("Pass --from <source>: a .env path (- reads stdin), '1password:<vault>', or 'icloud'.");
-    }
-    if (opts.from === 'icloud')
-        return { kind: 'icloud' };
-    if (opts.from === '1password')
-        return { kind: '1password', vault: opts.vault };
-    if (opts.from.startsWith('1password:')) {
-        const vault = opts.from.slice('1password:'.length);
-        return { kind: '1password', vault: vault || opts.vault };
-    }
-    return { kind: 'dotenv', path: opts.from };
-}
-/**
- * `secrets import --from icloud` — recover bundles stranded in the iCloud
- * Keychain by the device-local cutover. With a bundle name, imports exactly
- * that bundle; without one, interactively multi-selects from everything
- * discovered (all pre-checked — the common case is "bring them all back").
- */
-async function importFromICloud(bundleName, opts) {
-    if (process.platform !== 'darwin') {
-        throw new Error('--from icloud reads the macOS iCloud Keychain and is only available on macOS.');
-    }
-    const candidates = discoverSyncedBundles();
-    if (candidates.length === 0) {
-        console.log('No legacy iCloud Keychain bundles found.');
-        return;
-    }
-    const describe = (c) => `${c.name} (${c.keys.length} key${c.keys.length === 1 ? '' : 's'}${c.hasMeta ? '' : ', no metadata'})`;
-    let chosen;
-    if (bundleName) {
-        const hit = candidates.find((c) => c.name === bundleName);
-        if (!hit) {
-            throw new Error(`No iCloud Keychain bundle named '${bundleName}'. Found: ${candidates.map((c) => c.name).join(', ')}`);
-        }
-        chosen = [hit];
-    }
-    else if (!isInteractiveTerminal()) {
-        throw new Error(`Found ${candidates.length} iCloud Keychain bundle(s): ${candidates.map((c) => c.name).join(', ')}. ` +
-            'Pass a bundle name to import non-interactively.');
-    }
-    else {
-        const { checkbox } = await import('@inquirer/prompts');
-        chosen = await checkbox({
-            message: 'Which iCloud Keychain bundles to import?',
-            choices: candidates.map((c) => ({ name: describe(c), value: c, checked: true })),
-        });
-        if (chosen.length === 0) {
-            console.log('Nothing selected.');
-            return;
-        }
-    }
-    for (const candidate of chosen) {
-        const result = importSyncedBundle(candidate, opts);
-        const parts = [`imported ${result.added} key(s)`];
-        if (result.skipped)
-            parts.push(`skipped ${result.skipped} (already set, pass --force)`);
-        if (result.missing.length)
-            parts.push(`unreadable (left in iCloud): ${result.missing.join(', ')}`);
-        if (result.unimportable.length)
-            parts.push(`reserved, not importable (left in iCloud): ${result.unimportable.join(', ')}`);
-        if (opts.purge)
-            parts.push(`purged ${result.purged} iCloud item(s)`);
-        const line = `${candidate.name}: ${parts.join(', ')}`;
-        const warn = result.missing.length > 0 || result.unimportable.length > 0;
-        console.log(warn ? chalk.yellow(line) : chalk.green(line));
-    }
-}
-/**
- * Printed under a read failure: if the name matches a bundle stranded in the
- * iCloud Keychain (pre-device-local-cutover era), point at the recovery command
- * instead of leaving a dead end.
- *
- * `stillPresent` distinguishes the two failures, because they need different
- * commands. A MISSING bundle imports straight from iCloud. A bundle that is on
- * disk but undecryptable does not: `import` reads the existing bundle before
- * writing into it, so it fails the same way the read just did. That one has to
- * be deleted first — which is why naming the wrong command here bricked the
- * name entirely.
- */
-function maybePrintSyncedHint(name, stillPresent) {
-    if (process.platform !== 'darwin')
-        return;
-    try {
-        if (!discoverSyncedBundles().some((c) => c.name === name))
-            return;
-        console.error(chalk.yellow(stillPresent
-            ? `A legacy iCloud Keychain copy of '${name}' exists, but the local copy is unreadable and ` +
-                `import writes into it. Delete the local copy first, then recover:\n` +
-                `  agents secrets delete ${name}\n` +
-                `  agents secrets import ${name} --from icloud`
-            : `A legacy iCloud Keychain copy of '${name}' exists. Recover it with: agents secrets import ${name} --from icloud`));
-    }
-    catch {
-        // Hint only — never mask the original error.
-    }
-}
-/**
- * Build the remote `agents secrets unlock` argv for `unlock --device`. `--all`
- * forwards verbatim; otherwise the explicit bundle names. A `--ttl` is passed
- * through as-is so the REMOTE parses its own duration (its platform rules, its
- * defaults). Shared with the command action so the wiring is unit-testable
- * without a live SSH session.
- */
-export function resolveUnlockTtlMs(ttl, until, now = Date.now()) {
-    if (ttl && until)
-        throw new Error('--ttl and --until are mutually exclusive.');
-    if (until) {
-        const expiresAt = Date.parse(until);
-        if (!Number.isFinite(expiresAt))
-            throw new Error("Invalid --until '" + until + "'. Use an ISO date or timestamp.");
-        if (expiresAt <= now)
-            throw new Error("Invalid --until '" + until + "': date must be in the future.");
-        return expiresAt - now;
-    }
-    if (ttl) {
-        const secs = parseDuration(ttl);
-        if (!secs)
-            throw new Error("Invalid --ttl '" + ttl + "'. Use e.g. 30m, 2h, 8h, 3d.");
-        return secs * 1000;
-    }
-    return secretsHoldMs();
-}
-/**
- * Decide what an `unlock` holds: the whole bundle env, or — with --keys — only
- * the resolved subset behind a lease that scopes the broker entry (agent.ts
- * re-selects on load) and its own expiry. Fails closed: createSecretLease throws
- * on an unknown or empty key subset. The unlock action's single scoping seam,
- * exported so the whole-bundle vs scoped-subset decision is unit-testable without
- * a live broker.
- */
-export function scopeHeldEnv(input) {
-    // null = no --keys → hold the whole bundle. An empty-string --keys is a
-    // deliberate (if empty) scope request and falls through to createSecretLease,
-    // which fails closed ('requires at least one key') rather than holding it all.
-    if (input.keys === null)
-        return { heldEnv: input.env };
-    const lease = createSecretLease({
-        bundle: input.bundle,
-        keys: input.keys.split(','),
-        availableKeys: Object.keys(input.env),
-        ttlMs: input.ttlMs,
-        harness: input.harness,
-        sleepPersist: input.sleepPersist,
-    });
-    return { heldEnv: selectLeasedEnv(lease, input.env), lease };
-}
-export function buildRemoteUnlockArgs(names, opts) {
-    return [
-        'unlock',
-        ...(opts.all ? ['--all'] : names),
-        ...(opts.ttl ? ['--ttl', opts.ttl] : []),
-        ...(opts.until ? ['--until', opts.until] : []),
-        // Forward --durable so a remote unlock honors it too; without this the remote
-        // silently falls back to its own secrets.agent.durable default (off).
-        ...(opts.durable ? ['--durable'] : []),
-    ];
-}
-/**
- * Build the remote `agents secrets list` argv for `list --device`. Every filter
- * must be forwarded: `browseRemote` sends this argv verbatim, so a flag left out
- * here is not an error — the remote just lists everything, and
- * `secrets list --device zion --expired` reports every bundle on zion as expired.
- * Silent and wrong beats loud and wrong only for the person who wrote the bug.
- *
- * Values pass through unparsed so the REMOTE validates them under its own rules,
- * matching how `--ttl` is forwarded by buildRemoteUnlockArgs.
- */
-export function buildRemoteListArgs(opts, query) {
-    return [
-        'list',
-        ...(query ? [query] : []),
-        ...(opts.json ? ['--json'] : []),
-        ...(opts.policy ? ['--policy', opts.policy] : []),
-        ...(opts.backend ? ['--backend', opts.backend] : []),
-        ...(opts.type ? ['--type', opts.type] : []),
-        ...(opts.kind ? ['--kind', opts.kind] : []),
-        ...(opts.held ? ['--held'] : []),
-        ...(opts.notHeld ? ['--not-held'] : []),
-        ...(opts.expired ? ['--expired'] : []),
-        // `--expiring` is optional-value: `true` means the bare flag was passed.
-        ...(opts.expiring === true ? ['--expiring'] : opts.expiring ? ['--expiring', String(opts.expiring)] : []),
-        ...(opts.unused ? ['--unused', opts.unused] : []),
-        ...(opts.sort ? ['--sort', opts.sort] : []),
-        ...(opts.limit ? ['--limit', opts.limit] : []),
-    ];
-}
-// SSH target validation is defined canonically in src/lib/ssh-exec.ts and
-// re-exported here for back-compat with existing importers of these symbols.
-export { SSH_TARGET_RE, assertValidSshTarget };
-/**
- * Build the child environment for `agents secrets exec`. Strips
- * loader/interpreter hijack vars (matching agent spawns in exec.ts) and never
- * forwards AGENTS_SECRETS_PASSPHRASE — the master decryption key must not reach
- * the executed command.
- */
-export function buildSecretsExecEnv(parentEnv, secretEnv) {
-    const env = { ...sanitizeProcessEnv(parentEnv), ...secretEnv };
-    delete env.AGENTS_SECRETS_PASSPHRASE;
-    return env;
-}
-/**
- * Resolve the CLI version for the MCP server's `serverInfo.version`. package.json
- * sits at the repo root — two levels up from both `src/commands/` (bun/tsx dev)
- * and `dist/commands/` (built). Cosmetic only, so any failure falls back cleanly.
- */
-function getCliVersion() {
-    try {
-        const pkgPath = new URL('../../package.json', import.meta.url);
-        return JSON.parse(fs.readFileSync(pkgPath, 'utf-8')).version ?? '0.0.0';
-    }
-    catch {
-        return '0.0.0';
-    }
-}
-/**
- * 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
- * is grouped under a `── <host> ──` header. `tty` forces an interactive ssh
- * session (run sequentially) so a remote Touch-ID / passphrase prompt can
- * surface (e.g. `view --reveal`); otherwise hosts are queried in parallel.
- * Exits non-zero if any host fails.
- *
- * `secret` marks a browse that streams plaintext VALUES back (`view --reveal`)
- * rather than only key names (`list`, masked `view`). A secret browse rides the
- * credential-transport posture — managed host-key pinning + no multiplex — so a
- * revealed value can't be intercepted on an unpinned/multiplexed connection
- * (RUSH-2527). It composes with `tty`: `view --reveal` at a terminal is both.
- */
-async function browseRemote(targets, args, tty, secret = false) {
-    const multi = targets.length > 1;
-    let failures = 0;
-    const render = (name, res) => {
-        if (multi)
-            console.log(chalk.bold.cyan(`\n── ${name} ──`));
-        if (res.code === 0) {
-            if (res.stdout)
-                process.stdout.write(res.stdout.endsWith('\n') ? res.stdout : `${res.stdout}\n`);
-            if (res.stderr.trim())
-                process.stderr.write(chalk.gray(res.stderr));
-        }
-        else {
-            failures++;
-            const msg = (res.stderr || res.stdout || '').trim();
-            const why = res.timedOut ? 'timed out' : res.code === null ? 'ssh failed' : `exit ${res.code}`;
-            console.error(chalk.red(`${name}: ${why}${msg ? `: ${msg}` : ''}`));
-        }
-    };
-    if (tty) {
-        for (const t of targets) {
-            const target = await resolveHostSshTarget(t);
-            render(t, remoteSecretsRaw(target, args, { tty: true, osLookupName: t, secret }));
-        }
-    }
-    else {
-        const resolved = await Promise.all(targets.map(async (t) => ({ name: t, target: await resolveHostSshTarget(t) })));
-        const results = resolved.map(({ name, target }) => remoteSecretsRaw(target, args, { osLookupName: name, secret }));
-        targets.forEach((t, i) => render(t, results[i]));
-    }
-    if (failures > 0)
-        process.exit(1);
-}
-/** Strip ANSI escape sequences so padding can be computed on visible width. */
-/** Render an ISO-8601 timestamp as a compact relative age: "now", "5m", "1h", "3d", "2w", "4mo", "1y". */
-function relativeAge(iso) {
-    const t = Date.parse(iso);
-    if (!Number.isFinite(t))
-        return '-';
-    const deltaMs = Date.now() - t;
-    if (deltaMs < 0)
-        return 'now';
-    const sec = Math.floor(deltaMs / 1000);
-    if (sec < 60)
-        return 'now';
-    const min = Math.floor(sec / 60);
-    if (min < 60)
-        return `${min}m`;
-    const hr = Math.floor(min / 60);
-    if (hr < 24)
-        return `${hr}h`;
-    const day = Math.floor(hr / 24);
-    if (day < 7)
-        return `${day}d`;
-    if (day < 30)
-        return `${Math.floor(day / 7)}w`;
-    const mo = Math.floor(day / 30);
-    if (mo < 12)
-        return `${mo}mo`;
-    return `${Math.floor(day / 365)}y`;
-}
-/** Long-form relative age for the `view` command. "now" stays as "now"; otherwise appends " ago". */
-function humanAge(iso) {
-    const age = relativeAge(iso);
-    if (age === 'now' || age === '-')
-        return age;
-    return `${age} ago`;
-}
-/** Compact span for a fixed duration: "45m" / "19h" / "2d". Shared by
- * `compactRemaining` (a countdown) and the POLICY column's hold-window
- * annotation (a fixed length) so the two can never round onto different unit
- * thresholds and disagree about the same number of milliseconds. */
-export function compactDurationMs(ms) {
-    const mins = Math.round(ms / 60000);
-    if (mins < 60)
-        return `${mins}m`;
-    const hours = Math.round(mins / 60);
-    if (hours < 24)
-        return `${hours}h`;
-    return `${Math.round(hours / 24)}d`;
-}
-/** Compact remaining-time for the list POLICY column: "19h" / "45m" / "2d". */
-function compactRemaining(expiresAt) {
-    const ms = expiresAt - Date.now();
-    if (ms <= 0)
-        return 'expired';
-    return compactDurationMs(ms);
-}
-/** The POLICY column for `secrets list`. `hold` is a duration, not a mode — it
- * means "prompt once, then stay silent for this long" — so the column states
- * the window (`hold 7d`) rather than the bare tier name, and appends `· held Nd`
- * while the secrets-agent is actually caching the bundle. `always` and `never`
- * carry no window and gain nothing here. `holdMs` is the configured global hold
- * (`secretsHoldMs()`), passed in rather than read so this stays pure; `held`
- * maps bundle name → expiry epoch-ms (from agentStatus()). */
-export function renderPolicyCol(b, holdMs, held) {
-    // `never` is loud on purpose — it's the only tier with no user-presence gate.
-    if (bundlePolicy(b) === 'never')
-        return chalk.red.bold('never · no prompt');
-    if (bundlePolicy(b) === 'always')
-        return chalk.yellow('always · prompt');
-    const window = compactDurationMs(holdMs);
-    // A lapsed entry is not held. Without this guard a stale broker row renders
-    // the countdown's `expired` sentinel as if it were a live hold.
-    const exp = liveHold(held?.get(b.name));
-    return exp !== null
-        ? chalk.green(`hold ${window} · held ${compactRemaining(exp)}`)
-        : chalk.gray(`hold ${window}`);
-}
-/** The hold-window line at the top of `secrets status`. Names the `hold` policy
- * the window belongs to — the rename in #1604 left this surface still saying
- * "daily", the one name the CLI no longer accepts in its own help. Pure so the
- * vocabulary is pinned by a test rather than re-drifting on the next rename. */
-export function renderHoldSummary(holdStr, configured) {
-    const source = configured ? ' (secrets.agent.holdMs)' : ' (default)';
-    return `hold: ${holdStr}${source} — a bundle on the hold policy prompts once, then stays silent for this long or until sleep/logout.`;
-}
-/** The empty-broker line under the hold summary. Named here, beside
- * `renderHoldSummary`, for the same reason: it is the second line the rename
- * left saying `daily`, and a test pins both. */
-export const NO_BUNDLES_HELD_LINE = 'No bundles held. The next read of each hold-policy bundle will prompt once, then hold.';
-/** 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;
-/** A broker hold expiry, or null once it has lapsed. One definition of "held",
- * shared by the POLICY column, the `--held` filter, and the JSON payload, so the
- * three can never disagree about the same bundle. */
-export function liveHold(expiresAt, now = Date.now()) {
-    return expiresAt !== undefined && expiresAt > now ? expiresAt : null;
-}
-/** Width of the POLICY column. The widest cell is `hold 30d · held 30d` (19
- * visible chars) — `clampHoldMs` caps the window at 30d and `renderPolicyCol`
- * drops lapsed holds, so nothing longer can be produced. */
-const POLICY_COL_WIDTH = 20;
-/** Format a single bundle as a table row for the `secrets list` output. */
-function renderBundleRow(b, holdMs, held, cols = terminalWidth()) {
-    const entries = describeBundle(b);
-    const keys = entries.length;
-    const expiring = renderExpiringCol(b);
-    // Timestamp distinction:
-    //   "?"     -> legacy bundle, never written under the timestamping code.
-    //   "never" -> bundle has been written but the action never happened
-    //              (currently only used for USED — CREATED/UPDATED are always
-    //              set together by writeBundle).
-    //   <age>   -> real data.
-    const created = b.created_at ? relativeAge(b.created_at) : chalk.gray('?');
-    const updated = b.updated_at ? relativeAge(b.updated_at) : chalk.gray('?');
-    const used = b.last_used
-        ? relativeAge(b.last_used)
-        : (b.created_at ? chalk.gray('never') : chalk.gray('?'));
-    const head = `${chalk.cyan(b.name.padEnd(20))} ` +
-        `${String(keys).padEnd(5)} ` +
-        `${padVisible(renderPolicyCol(b, holdMs, held), POLICY_COL_WIDTH)} ` +
-        `${padVisible(expiring, 9)} ` +
-        `${padVisible(created, 9)} ` +
-        `${padVisible(updated, 9)} ` +
-        `${padVisible(used, 7)}`;
-    // Mark non-keychain bundles so `list` distinguishes storage at a glance.
-    const tag = b.backend === 'file'
-        ? chalk.magenta('[file] ')
-        : b.backend === 'vault'
-            ? chalk.blue('[synced] ')
-            : '';
-    // Cap the free-form description to whatever space is left on the line so a long
-    // description can't push the row to 200+ chars and wrap into a smear.
-    const budget = cols - stringWidth(head) - 1 - stringWidth(tag);
-    const desc = b.description && budget > 3
-        ? chalk.gray(truncateToWidth(safePrint(b.description), budget))
-        : '';
-    const trailer = `${tag}${desc}`.trimEnd();
-    return trailer ? `${head} ${trailer}` : head.trimEnd();
-}
-/** Narrow-terminal card: name + compact meta on one line, description below. */
-function renderBundleCard(b, holdMs, held, cols) {
-    const keys = describeBundle(b).length;
-    const used = b.last_used ? relativeAge(b.last_used) : (b.created_at ? 'never' : '?');
-    const tag = b.backend === 'file'
-        ? chalk.magenta(' [file]')
-        : b.backend === 'vault'
-            ? chalk.blue(' [synced]')
-            : '';
-    const meta = chalk.gray(`${keys} key${keys === 1 ? '' : 's'} · `) + renderPolicyCol(b, holdMs, held) + chalk.gray(` · used ${used}`);
-    const line1 = `${chalk.cyan(b.name)}  ${meta}${tag}`;
-    if (!b.description)
-        return line1;
-    return `${line1}\n    ${chalk.gray(truncateToWidth(safePrint(b.description), cols - 4))}`;
-}
-/** Colorize a variable source kind (literal, keychain, env, file, exec). */
-function kindLabel(kind) {
-    switch (kind) {
-        case 'literal': return chalk.gray('literal');
-        case 'keychain': return chalk.green('keychain');
-        case 'env': return chalk.blue('env');
-        case 'file': return chalk.magenta('file');
-        case 'exec': return chalk.red('exec');
-        default: return kind;
-    }
-}
-/** Mask a value with asterisks unless reveal is true. */
-function redact(value, reveal) {
-    if (reveal)
-        return value;
-    if (!value)
-        return '';
-    return '*'.repeat(Math.min(value.length, 8));
-}
-/**
- * Strip ASCII / C1 control bytes from a string before printing it to the
- * terminal. Bundle descriptions, notes, and remote-supplied names can carry
- * arbitrary text and a malicious value containing ANSI escape sequences (e.g.
- * OSC 52 clipboard set, screen-clear, cursor moves) would otherwise be
- * interpreted by the user's terminal. Allow tab and newline so multi-line
- * notes still render; strip everything else in the C0/C1 ranges plus DEL.
- */
-function safePrint(s) {
-    return s.replace(/[\x00-\x08\x0B-\x1F\x7F-\x9F]/g, '');
-}
-/**
- * Build a VarMeta patch from CLI flags. Validates each provided field. Returns
- * undefined if no meta flag was passed (so callers know to skip meta updates).
- *
- * `--note -` reads the note from stdin so users can pass long/multi-line notes
- * without shell-escaping. It's mutually exclusive with `--value-stdin`; both
- * trying to consume stdin would race and silently corrupt one or the other.
- */
-function buildMetaPatch(raw) {
-    if (raw.type === undefined && raw.expires === undefined && raw.note === undefined) {
-        return undefined;
-    }
-    const patch = {};
-    if (raw.type !== undefined) {
-        validateSecretType(raw.type);
-        patch.type = raw.type;
-    }
-    if (raw.expires !== undefined) {
-        validateExpiresFutureDated(raw.expires);
-        patch.expires = raw.expires;
-    }
-    if (raw.note !== undefined) {
-        if (raw.note === '-') {
-            if (raw.valueStdin) {
-                throw new Error('--note - and --value-stdin both want stdin; only one can read it.');
-            }
-            const fromStdin = readStdinSync();
-            if (!fromStdin)
-                throw new Error('No note received on stdin.');
-            patch.note = fromStdin;
-        }
-        else {
-            patch.note = raw.note;
-        }
-    }
-    return patch;
-}
-/** Whole days from now until midnight-UTC of the given ISO date. Negative if past. */
-function daysUntil(iso) {
-    const target = new Date(iso + 'T23:59:59Z').getTime();
-    const now = Date.now();
-    return Math.floor((target - now) / (24 * 60 * 60 * 1000));
-}
-/** Render the meta line under a var, indented. Returns empty string if nothing to show. */
-function renderMetaLine(meta, reveal) {
-    if (!meta)
-        return '';
-    const parts = [];
-    if (meta.type)
-        parts.push(`type: ${meta.type}`);
-    if (meta.expires) {
-        const days = daysUntil(meta.expires);
-        const tail = `(in ${days} days)`;
-        let colored;
-        if (days < 0) {
-            colored = chalk.red(`expires: ${meta.expires} ${tail}`);
-        }
-        else if (days < 30) {
-            colored = chalk.yellow(`expires: ${meta.expires} ${tail}`);
-        }
-        else {
-            colored = chalk.gray(`expires: ${meta.expires} ${tail}`);
-        }
-        parts.push(colored);
-    }
-    if (meta.note) {
-        let note = safePrint(meta.note);
-        if (!reveal && note.length > 80) {
-            note = note.slice(0, 79) + '\u2026';
-        }
-        parts.push(`note: ${note}`);
-    }
-    if (parts.length === 0)
-        return '';
-    return `    ${parts.join('  ')}`;
-}
-/** Count entries in `meta` whose `expires` falls in the next 30 days. Excludes
- * keys that have ALREADY expired — those are counted by `bundleExpiry().expired`
- * and rendered separately, since a lapsed key is a different problem from one
- * coming due. */
-function countExpiringSoon(meta) {
-    if (!meta)
-        return 0;
-    let n = 0;
-    for (const m of Object.values(meta)) {
-        if (!m.expires)
-            continue;
-        const d = daysUntil(m.expires);
-        if (d >= 0 && d < 30)
-            n++;
-    }
-    return n;
-}
-/** Human labels for the usage events, in the order `view` prints them. */
-const USAGE_EVENT_LABELS = {
-    access: 'accessed',
-    unlock: 'unlocked',
-    import: 'imported',
-    export: 'exported',
-    create: 'created',
-    view: 'viewed',
-};
-/**
- * Compact one-line usage summary for `secrets view` — each recorded event with
- * its count and how long ago it last happened ("accessed 42× (last 2h ago) ·
- * exported 3× (last 1d ago)"). Empty string when nothing has been recorded yet.
- * Pure — unit-tested.
- */
-export function formatUsageLine(summary) {
-    if (!summary || summary.total === 0)
-        return '';
-    const parts = [];
-    for (const ev of SECRET_USAGE_EVENTS) {
-        const stat = summary.events[ev];
-        if (stat.count === 0)
-            continue;
-        const age = stat.last ? relativeAge(stat.last) : null;
-        parts.push(`${USAGE_EVENT_LABELS[ev]} ${stat.count}×${age ? ` (last ${age})` : ''}`);
-    }
-    return parts.join(' · ');
-}
-/**
- * The held-state line for `secrets view`: whether the secrets-agent currently
- * holds this bundle (so reads are prompt-free) and for how long, or that Touch
- * ID is required on the next read. Only meaningful for keychain bundles on macOS
- * — file/vault backends have no broker to hold, and a `never`-policy bundle is
- * always readable — so both return an empty line and the caller skips it.
- * `heldExpiresAt` is the max expiry across every held scope.
- */
-export function renderViewStatusLine(b, heldExpiresAt) {
-    if (process.platform !== 'darwin')
-        return '';
-    if ((b.backend ?? 'keychain') !== 'keychain')
-        return '';
-    if (bundlePolicy(b) === 'never')
-        return '';
-    if (heldExpiresAt && heldExpiresAt > Date.now()) {
-        return chalk.green(`status:     unlocked (held ${compactRemaining(heldExpiresAt)}; reads are prompt-free until it locks)`);
-    }
-    return chalk.gray('status:     locked (Touch ID required on the next read; `agents secrets unlock` holds it)');
-}
-/**
- * The EXPIRING cell. Counts keys needing attention — already expired plus due
- * within 30 days — and colours by the worst of the two: red once anything has
- * lapsed, yellow while everything is merely upcoming.
- *
- * Expired keys used to be invisible here. `countExpiringSoon` requires
- * `d >= 0`, so a bundle whose token died last month rendered `-`, identical to
- * one with no expiry at all; the only places it surfaced were `secrets view`
- * and a hard abort at inject time, i.e. after it had already broken something.
- */
-export function renderExpiringCol(b, now = Date.now()) {
-    const { expired, soon } = bundleExpiry(b, now);
-    const total = expired + soon;
-    if (total === 0)
-        return chalk.gray('-');
-    return expired > 0 ? chalk.red(String(total)) : chalk.yellow(String(total));
-}
-/**
- * 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.
- *
- * `force` additionally recreates a bundle whose METADATA RECORD is present but
- * undecryptable — a file store whose key was lost or rotated out from under it.
- * That is precisely the state provisioning exists to repair (import is how a box
- * gets its bundles back), and without this the import dies on `readBundle` and
- * the only route left is deleting the record by hand on an already-degraded
- * store. It is gated on `--force` on purpose: recreating unconditionally would
- * destroy a perfectly healthy bundle for someone who merely forgot to set
- * `AGENTS_SECRETS_PASSPHRASE`, which is the hazard `readBundleIfDecryptable`
- * exists to describe. `--force` already means "overwrite what is there".
- */
-export function resolveImportBundle(name, backendOpt, synced = false, force = false) {
-    if (isReservedBundleName(name) && (synced || (backendOpt && backendOpt !== 'file'))) {
-        throw new ReservedBundleWrongBackendError(name, synced ? 'vault' : resolveBackendOpt(backendOpt));
-    }
-    const requestedBackend = isReservedBundleName(name)
-        ? 'file'
-        : (synced ? 'vault' : resolveBackendOpt(backendOpt));
-    if (bundleExists(name)) {
-        // readBundleIfDecryptable nulls ONLY on BundleUndecryptableError; a locked
-        // keychain or logged-out vault still throws, so a recoverable state can
-        // never be mistaken for a lost key and silently overwritten.
-        const bundle = force ? readBundleIfDecryptable(name) : readBundle(name);
-        if (bundle) {
-            if (requestedBackend !== 'keychain' && bundle.backend !== requestedBackend) {
-                throw new Error(`Bundle '${name}' already exists with a different backend; ` +
-                    `delete it first to recreate it as ${requestedBackend === 'vault' ? 'synced' : `${requestedBackend}-backed`}.`);
-            }
-            return bundle;
-        }
-    }
-    return { name, backend: requestedBackend === 'keychain' ? undefined : requestedBackend, 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 storedItems = new Map();
-    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);
-            storedItems.set(item, value);
-            bundle.vars[key] = keychainRef(key);
-        }
-        added++;
-    }
-    if (storedItems.size > 0) {
-        writeBundleWithItems(bundle, storedItems);
-    }
-    else {
-        writeBundle(bundle);
-    }
-    if (added > 0) {
-        assertFileBundleDecryptable(bundle.name, Object.keys(env).filter((k) => k in bundle.vars));
-    }
-    return { added, skipped };
-}
-/** Register the `agents secrets` command tree. */
-export function registerSecretsCommands(program) {
-    const cmd = program
-        .command('secrets')
-        .description('Named bundles of env variables backed by macOS Keychain (device-local, biometry-gated). Inject into agents via `agents run --secrets <name>`.');
-    setHelpSections(cmd, {
-        examples: `
-      # Create a bundle
-      agents secrets create prod --description "Production keys for the api stack"
-
-      # Add a keychain-backed secret (prompts for the value)
-      agents secrets add prod STRIPE_API_KEY
-
-      # Add a non-sensitive literal
-      agents secrets add prod LOG_LEVEL --value info
-
-      # Inject the bundle into an agent run
-      agents run claude "deploy the worker" --secrets prod
-
-      # See what's in the bundle (values masked); shows its policy, held state, and usage
-      agents secrets view prod
-
-      # Order the list by how recently / how often each bundle is used
-      agents secrets list --sort used
-      agents secrets list --sort uses
-
-      # Stop a noisy automation bundle from prompting every run: ask once a week
-      agents secrets policy prod hold
-
-      # Run a one-off command with secrets injected (values ride the child env, never stdout)
-      agents secrets exec prod -- ./deploy.sh
-
-      # Need one value inside a script? Read it under injection, not with a printer
-      agents secrets exec prod -- printenv STRIPE_API_KEY
-
-      # Deliberately reveal values at your terminal (interactive only)
-      agents secrets view prod --reveal
-
-      # Push the bundle to remote machine(s) over SSH (lands as a native bundle there)
-      agents secrets export prod --device yosemite-s0 --device yosemite-s1 --force
-    `,
-        notes: `
-      Bundles are containers; secrets are the variables inside them. Keychain values
-      never touch disk in plaintext. Every item is device-local and gated by Touch ID
-      or device passcode; cross-machine sync is handled by 'agents secrets push/pull'.
-
-      Naming: name a bundle after the thing it holds credentials for, so an agent can
-      guess it without listing. For a website, use its domain WITH the real suffix —
-      'stripe.com', 'openai.ai', 'github.com'. For a desktop app, use the app's binary
-      suffix — 'slack.app' (macOS) or 'photoshop.exe' (Windows). Always pass
-      '--description' so 'list' / 'view' explain the bundle without opening it; an
-      undescribed bundle prints a "No description found" nudge. 'view' also shows
-      whether the bundle is currently unlocked (held by the agent) and how often / how
-      recently it has been created, imported, exported, viewed, and accessed;
-      'list --sort used|uses' orders by recency / frequency, and
-      'agents secrets activity [bundle]' prints the recent value-free event timeline.
-
-      Touch ID noise: macOS pops a prompt per bundle per process. Each bundle has
-      a prompt policy, shown in the POLICY column of 'agents secrets list':
-        hold (default)    ask once, then serve it silently from the local agent
-                          for the hold window ('secrets.agent.holdMs', 7d by
-                          default), until sleep / logout or 'lock' (a bare
-                          screen-lock does NOT drop it). Accepts the older names
-                          'daily' and 'session'.
-        always            ask for Touch ID every time — never auto-held.
-        never             no biometry ACL at all — reads are silent forever, even
-                          if the agent is down. Automation credentials only.
-      The default is 'hold' (one Touch ID per hold window); change it globally with
-      'secrets.policy' in agents.yaml, or per bundle with 'agents secrets policy
-      <bundle> always'. 'agents secrets unlock <bundle>' holds any bundle after one
-      prompt regardless of policy. Nothing on disk.
-
-      See also:
-        agents secrets policy <bundle> hold            ask once per hold window (7d by default), not every run
-        agents secrets unlock <bundle>                 hold a bundle after one Touch ID
-        agents secrets lock                            wipe held bundles (re-prompt next read)
-        agents secrets status                          show held bundles + when they lock
-        agents secrets rotate <bundle> <key>           rotate value, preserve metadata
-        agents secrets import <bundle> --from .env     bulk import from .env
-        agents secrets import <bundle> --from 1password:<vault>
-        agents secrets import --from icloud            recover legacy iCloud Keychain bundles
-        agents secrets generate [length]               generate a random password / PIN / hex
-        agents secrets migrate-acl                     upgrade legacy items to the biometry ACL
-    `,
-    });
-    registerCommandGroups(cmd, [
-        { title: 'Bundle commands', names: ['list', 'view', 'activity', 'create', 'rename', 'describe', 'delete'] },
-        { title: 'Secret commands', names: ['add', 'rotate', 'remove', 'import', 'export'] },
-        { title: 'Agent commands', names: ['start', 'stop', 'unlock', 'lock', 'status', 'policy'] },
-        { title: 'Raw item commands', names: ['get', 'set'] },
-        { title: 'Sync commands', names: ['push', 'pull', 'remote-list'] },
-        { title: 'Utilities', names: ['exec', 'mcp', 'generate', 'migrate-acl'] },
-        { title: 'Synced vault', names: ['vault'] },
-    ]);
-    registerSecretsVaultCommands(cmd);
-    const listCmd = cmd
-        .command('list [query]')
-        .alias('ls')
-        .description('List configured secrets bundles, optionally filtered (use --device/--devices for other machines over SSH)')
-        .option('--device <target>', 'List bundles on a remote device over SSH (enrolled `agents hosts` name, ssh-config alias, or user@host)')
-        .option('--devices <list>', 'Comma-separated devices to list in one shot, e.g. yosemite-s0,yosemite-s1')
-        .option('--json', 'Emit machine-readable JSON (bundle metadata only — never secret values) instead of the table')
-        .option('--policy <list>', "Only these prompt policies (comma-separated): hold, always, never. '--policy never' is the audit for bundles that read with no Touch ID at all")
-        .option('--backend <list>', 'Only these backends (comma-separated): keychain, file, vault')
-        .option('--type <list>', `Only bundles carrying a key of these types (comma-separated): ${SECRET_TYPES.join(', ')}`)
-        .option('--kind <list>', `Only bundles carrying a value of these ref kinds (comma-separated): ${REF_KINDS.join(', ')}. '--kind literal' finds raw values stored inline; '--kind exec' finds bundles that shell out`)
-        .option('--held', 'Only bundles the secrets-agent is holding right now (read silently, no Touch ID). macOS only')
-        .option('--not-held', 'Only bundles the agent is NOT holding — the next read of each will prompt. macOS only')
-        .option('--expired', 'Only bundles with at least one key whose expiry has already passed')
-        .option('--expiring [days]', `Only bundles with a key falling due within N days (default ${DEFAULT_EXPIRING_DAYS})`)
-        .option('--unused <duration>', 'Only bundles not read since this far back (e.g. 30d, 4w, 3mo). Never-used bundles always match')
-        .addOption(new Option('--sort <field>', 'Sort by: name (default), used (most recently used), uses (most frequently accessed), created, updated, expiry').choices([...SORT_FIELDS]))
-        .option('-n, --limit <n>', 'Show at most this many bundles (after filtering and sorting)')
-        .action(async (query, opts) => {
-        const targets = parseHostsOption({ device: opts.device, devices: opts.devices });
-        if (targets.length > 0) {
-            // Forward the filters — browseRemote sends this argv verbatim, so a
-            // dropped flag would make the remote silently list everything.
-            await browseRemote(targets, buildRemoteListArgs(opts, query), false);
-            return;
-        }
-        // Parse before touching the keychain so a typo'd flag fails instantly,
-        // and render the message rather than a stack trace (the `policy` pattern).
-        let filter;
-        let sortField;
-        let limit;
-        try {
-            filter = parseListFilters(opts, query);
-            sortField = parseSortField(opts.sort);
-            limit = opts.limit === undefined ? undefined : Number(opts.limit);
-            if (limit !== undefined && (!Number.isInteger(limit) || limit < 1)) {
-                throw new Error(`Invalid --limit '${opts.limit}'. Use a whole number of bundles, e.g. --limit 10.`);
-            }
-            // The broker is macOS-only, so off darwin `held` is always empty and a
-            // hold-state filter would answer from no data — every bundle would look
-            // not-held. Refuse rather than return a confidently wrong list.
-            if (filter.held !== undefined && process.platform !== 'darwin') {
-                throw new Error('--held/--not-held need the secrets-agent, which is macOS-only. Run it on a Mac, or with --device <mac>.');
-            }
-        }
-        catch (err) {
-            console.error(chalk.red(err.message));
-            process.exit(1);
-        }
-        const all = listBundles();
-        // The configured hold window, read once for the whole listing — it is
-        // global, so every `hold` bundle renders the same span.
-        const holdMs = secretsHoldMs();
-        // Cross-reference the secrets-agent so `hold` bundles that are currently
-        // held can show "· held Nh". Soft-fails to no hint if the broker is down.
-        const held = new Map();
-        if (process.platform === 'darwin') {
-            try {
-                for (const e of await agentStatus())
-                    held.set(e.name, e.expiresAt);
-            }
-            catch {
-                /* broker not running — render policy without the countdown */
-            }
-        }
-        // Value-free usage read-model backs `--sort used|uses` and the --json
-        // `uses`/`usage` fields. Open the DB only when a caller actually needs it
-        // (a machine payload, or a usage-ranked sort) so a plain human `list`
-        // stays a pure keychain read.
-        const needUsage = Boolean(opts.json) || sortField === 'used' || sortField === 'uses';
-        const usage = needUsage ? getAllBundleUsage() : new Map();
-        const usageHints = new Map();
-        for (const [name, s] of usage)
-            usageHints.set(name, { lastUsedAt: s.lastUsedAt, uses: s.events.access.count });
-        // Filter, sort, then cap — before the --json branch, so the machine
-        // payload is the exact twin of the table (the sessions ordering rule).
-        const now = Date.now();
-        const matched = all.filter((b) => bundleMatchesFilter(b, filter, { held, now }));
-        const sorted = sortBundles(matched, sortField, usageHints);
-        const bundles = limit === undefined ? sorted : sorted.slice(0, limit);
-        if (opts.json) {
-            // Discovery payload for agents: metadata only, no secret values. Gated on
-            // the explicit --json flag (not stdout.isTTY) so piping the human table to
-            // a pager never silently swaps formats.
-            const payload = bundles.map((b) => ({
-                name: b.name,
-                keys: describeBundle(b).length,
-                policy: bundlePolicy(b),
-                // The window `policy: "hold"` is shorthand for. Null on always/never,
-                // which have no window at all.
-                holdMs: bundlePolicy(b) === 'hold' ? holdMs : null,
-                backend: b.backend === 'file' ? 'file' : 'keychain',
-                allowExec: Boolean(b.allow_exec),
-                expiringSoon: countExpiringSoon(b.meta),
-                // Already-lapsed keys, which `expiringSoon` deliberately excludes. A
-                // machine caller polling for rotation needs both numbers.
-                expired: bundleExpiry(b, now).expired,
-                description: b.description ?? null,
-                createdAt: b.created_at ?? null,
-                updatedAt: b.updated_at ?? null,
-                lastUsed: b.last_used ?? null,
-                // Same liveness rule the POLICY column and --held use: a broker entry
-                // past its expiry is not held. Without the check this field reported a
-                // stale past timestamp as if the bundle were still warm, disagreeing
-                // with the table and the filter about the very same bundle.
-                heldExpiresAt: liveHold(held.get(b.name), now),
-                // Value-free usage from the read-model: `uses` is the recorded access
-                // (read/inject) count; `usage` is the full per-kind rollup. Null when
-                // nothing has been recorded yet.
-                uses: usage.get(b.name)?.events.access.count ?? 0,
-                usage: usage.get(b.name) ?? null,
-            }));
-            process.stdout.write(JSON.stringify(payload) + '\n');
-            return;
-        }
-        if (bundles.length === 0) {
-            // Distinguish "you have none" from "your filter excluded all of them",
-            // and name the axes that did it — otherwise the only way to find out
-            // which flag emptied the list is to remove them one at a time.
-            if (filterIsActive(filter)) {
-                console.log(chalk.gray(`No bundles ${describeFilter(filter)}. ${all.length} bundle${all.length === 1 ? '' : 's'} total.`));
-                console.log(chalk.gray('Try: agents secrets list  (no filters)'));
-            }
-            else {
-                console.log(chalk.gray('No secrets bundles configured.'));
-                console.log(chalk.gray('Try: agents secrets create <name>'));
-            }
-            return;
-        }
-        const cols = terminalWidth();
-        if (cols >= SECRETS_WIDE) {
-            console.log(chalk.bold(`${'NAME'.padEnd(20)} ${'KEYS'.padEnd(5)} ${'POLICY'.padEnd(POLICY_COL_WIDTH)} ${'EXPIRING'.padEnd(9)} ${'CREATED'.padEnd(9)} ${'UPDATED'.padEnd(9)} ${'USED'.padEnd(7)} DESCRIPTION`));
-            for (const b of bundles) {
-                console.log(renderBundleRow(b, holdMs, held, cols));
-            }
-        }
-        else {
-            for (const b of bundles) {
-                console.log(renderBundleCard(b, holdMs, held, cols));
-            }
-        }
-    });
-    setHelpSections(listCmd, {
-        examples: `
-      # Everything, newest-used first
-      agents secrets list --sort used
-
-      # Order by how often each bundle is read (most-accessed first)
-      agents secrets list --sort uses
-
-      # Find one by name or description
-      agents secrets list github
-
-      # The security audit: which bundles read with NO Touch ID at all?
-      agents secrets list --policy never
-
-      # Which still store a raw value inline, or can shell out?
-      agents secrets list --kind literal
-      agents secrets list --kind exec
-
-      # What has already lapsed, and what is about to
-      agents secrets list --expired
-      agents secrets list --expiring 7 --sort expiry
-
-      # What can I delete? Untouched in three months
-      agents secrets list --unused 3mo --sort used
-
-      # Which bundles will prompt me on the next read (macOS)
-      agents secrets list --not-held
-
-      # Combine axes — every filter narrows further
-      agents secrets list --policy hold --backend file --expiring
-
-      # Same filters, on another machine, machine-readable
-      agents secrets list --expired --device mac-mini --json
-    `,
-        notes: `
-      - Filters compose: every flag you add narrows the list further.
-      - An unknown value is an error, not an empty list — '--policy hodl' names the valid set.
-      - --held/--not-held read live broker state, so they need macOS. Use --device <mac> from elsewhere.
-      - --expired and --expiring are different questions: already lapsed vs coming due. The EXPIRING column counts both and turns red once anything has lapsed.
-      - --unused matches bundles never read at all, not just old ones.
-      - Filters apply before --json, so the JSON is the exact twin of the table.
-      - Filters are forwarded over --device, so a remote list narrows the same way.
-      - --sort used|uses read the value-free usage read-model (~/.agents/secrets/secrets.db); see 'agents secrets activity'.
-    `,
-    });
-    const activityCmd = cmd
-        .command('activity [name]')
-        .description('Show the recent value-free usage timeline (created / imported / exported / viewed / accessed / unlocked) for one bundle, or across all bundles')
-        .option('-n, --limit <n>', 'Show at most this many events (default 20)')
-        .option('--json', 'Emit machine-readable JSON (metadata only — never secret values)')
-        .action((name, opts) => {
-        let limit = opts.limit === undefined ? 20 : Number(opts.limit);
-        if (!Number.isInteger(limit) || limit < 1) {
-            console.error(chalk.red(`Invalid --limit '${opts.limit}'. Use a whole number of events, e.g. --limit 50.`));
-            process.exit(1);
-        }
-        const events = getUsageHistory(name, limit);
-        if (opts.json) {
-            process.stdout.write(JSON.stringify(events) + '\n');
-            return;
-        }
-        if (events.length === 0) {
-            console.log(chalk.gray(name ? `No recorded activity for '${name}'.` : 'No recorded secrets activity yet.'));
-            return;
-        }
-        for (const e of events) {
-            const who = e.agent ? chalk.gray(` by ${e.agent}`) : '';
-            const where = e.source ? chalk.gray(` (${e.source}${e.host ? ` ${e.host}` : ''})`) : '';
-            const bundleTag = name ? '' : chalk.cyan(` ${e.bundle}`);
-            console.log(`${chalk.gray(relativeAge(e.ts).padEnd(10))} ${chalk.bold(e.event.padEnd(8))}${bundleTag}${who}${where}`);
-        }
-    });
-    setHelpSections(activityCmd, {
-        examples: `
-      # The recent value-free event timeline across every bundle
-      agents secrets activity
-
-      # Just one bundle, more history
-      agents secrets activity anthropic.com --limit 50
-
-      # Machine-readable
-      agents secrets activity anthropic.com --json
-    `,
-        notes: `
-      - Reads the value-free usage read-model (~/.agents/secrets/secrets.db), fed off the
-        same emitSecretAudit chokepoint as 'agents events'. Never a secret value.
-      - History is bounded to the last 90 days; the full audit trail is 'agents events --module secrets'.
-    `,
-    });
-    cmd
-        .command('view [name]')
-        .alias('show')
-        .description('Show a bundle. Keychain values are masked by default — pass --reveal to see them.')
-        .option('--reveal', 'Print keychain-backed values in the clear (interactive terminal only)')
-        .option('--json', 'Emit machine-readable JSON (values masked unless --reveal) instead of the human view')
-        .option('--device <target>', 'Show a bundle on a remote device over SSH (enrolled `agents hosts` name, ssh-config alias, or user@host)')
-        .option('--devices <list>', 'Comma-separated devices to show in one shot, e.g. yosemite-s0,yosemite-s1')
-        .action(async (name, opts) => {
-        try {
-            // `--reveal` is a deliberate HUMAN reveal: interactive terminal only, and
-            // never inside an agent session (an agent under tmux has a TTY, so the
-            // env markers are the load-bearing check). The old `--plaintext` escape
-            // that allowed a piped/non-TTY reveal is removed (RUSH-2774) — printed
-            // values land in an agent's context and session transcript.
-            if (opts.reveal && (isAgentInvocationContext() || !isInteractiveTerminal())) {
-                console.error(chalk.red('--reveal prints values in the clear and needs a real interactive terminal outside an agent session.'));
-                console.error(chalk.dim('Run the consuming command under injection instead: agents secrets exec <bundle> -- <cmd>'));
-                process.exit(1);
-            }
-            const targets = parseHostsOption({ device: opts.device, devices: opts.devices });
-            if (targets.length > 0) {
-                if (!name) {
-                    console.error(chalk.red('A bundle name is required when viewing a remote host (interactive pick needs a local terminal).'));
-                    process.exit(1);
-                }
-                const args = ['view', name];
-                if (opts.reveal)
-                    args.push('--reveal');
-                if (opts.json)
-                    args.push('--json');
-                // With --reveal, force a TTY so the remote keychain prompt can surface
-                // and the remote's own interactive-terminal gate is satisfied. The
-                // early gate above already proved this side is an interactive,
-                // non-agent terminal.
-                const tty = Boolean(opts.reveal);
-                // `--reveal` streams the plaintext value back over ssh stdout — a
-                // secret-bearing read that must pin the host key and not multiplex,
-                // whether it runs on the interactive (tty) or `--plaintext` non-tty path.
-                await browseRemote(targets, args, tty, Boolean(opts.reveal));
-                return;
-            }
-            const resolvedName = name ?? (await pickBundleName('view'));
-            let bundle;
-            try {
-                bundle = readBundle(resolvedName);
-            }
-            catch (err) {
-                console.error(chalk.red(err.message));
-                maybePrintSyncedHint(resolvedName, bundleExists(resolvedName));
-                process.exit(1);
-            }
-            const entries = describeBundle(bundle);
-            // Value-free usage read-model (per-kind counts + recency + per-agent) for
-            // both the human and --json views. Read before recording this view so the
-            // just-happened view isn't counted in its own summary.
-            const usage = getBundleUsage(bundle.name);
-            // Is the secrets-agent currently holding this bundle? A held bundle reads
-            // prompt-free. macOS keychain only; take the max expiry across every scope
-            // it's held under. Soft-fails to "not held" if the broker is down.
-            let heldExpiresAt = null;
-            if (process.platform === 'darwin' && (bundle.backend ?? 'keychain') === 'keychain') {
-                try {
-                    for (const e of await agentStatus()) {
-                        if (e.name === bundle.name && (heldExpiresAt === null || e.expiresAt > heldExpiresAt)) {
-                            heldExpiresAt = e.expiresAt;
-                        }
-                    }
-                }
-                catch {
-                    /* broker not running — render as not held */
-                }
-            }
-            // Record the inspection through the ONE chokepoint (events.jsonl + the
-            // usage read-model). Value-free; a masked `view` is metadata only.
-            emitSecretAudit({ event: 'secrets.view', bundle: bundle.name, operation: opts.json ? 'view --json' : 'view', source: 'view', status: 'success' });
-            if (opts.json) {
-                // Machine-readable discovery for agents. Values are null unless --reveal
-                // (already gated above: interactive terminal, outside an agent session).
-                // Gated on the explicit flag, not stdout.isTTY, so a piped human view
-                // never silently swaps formats.
-                const reveal = Boolean(opts.reveal);
-                const revealed = new Map();
-                if (reveal) {
-                    const { env } = readAndResolveBundleEnv(bundle.name, {
-                        caller: 'view --reveal --json',
-                        keyMode: 'storage',
-                        // An explicit human `--reveal` at a terminal is a deliberate value
-                        // access → resolve interactively (one Touch ID). Under an agent
-                        // (AGENTS_RUNTIME) or headless (no TTY) it stays broker-only.
-                        agentOnly: isHeadlessSecretsContext() || !isInteractiveTerminal(),
-                    });
-                    for (const entry of entries) {
-                        if (entry.kind === 'keychain' && env[entry.key] !== undefined) {
-                            revealed.set(secretsKeychainItem(bundle.name, entry.detail), env[entry.key]);
-                        }
-                    }
-                    const exposed = revealed.size + entries.filter((e) => e.kind === 'literal').length;
-                    if (exposed > 0) {
-                        emitSecretAudit({
-                            event: 'secrets.get',
-                            bundle: bundle.name,
-                            operation: 'view --reveal --json',
-                            source: 'reveal',
-                            status: 'success',
-                            keyCount: exposed,
-                        });
-                    }
-                }
-                const keys = entries.map((e) => {
-                    const row = {
-                        key: e.key,
-                        kind: e.kind,
-                        detail: e.detail || null,
-                        value: null,
-                    };
-                    if (e.kind === 'keychain') {
-                        const item = secretsKeychainItem(bundle.name, e.detail);
-                        row.stored = hasKeychainToken(item);
-                        if (reveal && revealed.has(item))
-                            row.value = revealed.get(item);
-                    }
-                    else if (e.kind === 'literal' && reveal) {
-                        const raw = bundle.vars[e.key];
-                        row.value =
-                            typeof raw === 'string'
-                                ? raw
-                                : (raw && typeof raw === 'object' && 'value' in raw ? raw.value : '');
-                    }
-                    return row;
-                });
-                process.stdout.write(JSON.stringify({
-                    name: bundle.name,
-                    description: bundle.description ?? null,
-                    policy: bundlePolicy(bundle),
-                    // The window `policy: "hold"` is shorthand for. Null on
-                    // always/never, which have no window at all.
-                    holdMs: bundlePolicy(bundle) === 'hold' ? secretsHoldMs() : null,
-                    backend: bundle.backend === 'file' ? 'file' : 'keychain',
-                    allowExec: Boolean(bundle.allow_exec),
-                    createdAt: bundle.created_at ?? null,
-                    updatedAt: bundle.updated_at ?? null,
-                    lastUsed: bundle.last_used ?? null,
-                    // Held state + value-free usage rollup, same data the human view
-                    // shows. `heldExpiresAt` is null when the bundle is not held.
-                    heldExpiresAt,
-                    usage: usage ?? null,
-                    uses: usage?.events.access.count ?? 0,
-                    revealed: reveal,
-                    keys,
-                }) + '\n');
-                return;
-            }
-            console.log(chalk.bold(bundle.name));
-            if (bundle.description) {
-                console.log(chalk.gray(safePrint(bundle.description)));
-            }
-            else {
-                // A described bundle is self-documenting for the next agent/human that
-                // reads it. Nudge — never block — toward adding one.
-                console.log(chalk.yellow(`No description found. Add one: agents secrets describe ${bundle.name} "what this bundle is for"`));
-            }
-            if (bundle.allow_exec)
-                console.log(chalk.yellow('allow_exec: true'));
-            if (bundle.backend === 'file')
-                console.log(chalk.gray('backend: file (encrypted at rest; headless reads via a machine-local key, or AGENTS_SECRETS_PASSPHRASE if set — no Touch ID)'));
-            if (bundle.backend === 'vault')
-                console.log(chalk.gray('storage: synced (age-encrypted ~/.agents/vault.age; needs `agents secrets vault unlock`)'));
-            if (bundlePolicy(bundle) === 'never') {
-                console.log(chalk.red.bold('policy: never — NO biometry ACL; reads are silent (no Touch ID, no user-presence check). Automation-only.'));
-            }
-            else {
-                console.log(bundlePolicy(bundle) === 'hold'
-                    // The window comes from secretsHoldMs(), never a literal — this
-                    // line used to hardcode "7d by default" and so misstated the
-                    // window for anyone who had configured secrets.agent.holdMs.
-                    ? chalk.gray(`policy: hold (ask once, then held for ${formatHoldWindow(secretsHoldMs())} — until sleep / logout; screen-lock does not drop it)`)
-                    : chalk.gray('policy: always (asks for Touch ID every time — never auto-held)'));
-            }
-            const statusLine = renderViewStatusLine(bundle, heldExpiresAt);
-            if (statusLine)
-                console.log(statusLine);
-            if (bundle.created_at)
-                console.log(chalk.gray(`created_at: ${bundle.created_at} (${humanAge(bundle.created_at)})`));
-            if (bundle.updated_at)
-                console.log(chalk.gray(`updated_at: ${bundle.updated_at} (${humanAge(bundle.updated_at)})`));
-            if (bundle.last_used)
-                console.log(chalk.gray(`last_used:  ${bundle.last_used} (${humanAge(bundle.last_used)})`));
-            const usageLine = formatUsageLine(usage);
-            if (usageLine)
-                console.log(chalk.gray(`usage:      ${usageLine}`));
-            if (usage && usage.byAgent.length > 0) {
-                const top = usage.byAgent.slice(0, 3).map((a) => `${a.agent} ${a.count}×`).join(', ');
-                console.log(chalk.gray(`by:         ${top}`));
-            }
-            console.log();
-            if (entries.length === 0) {
-                console.log(chalk.gray('(no keys)'));
-                return;
-            }
-            const reveal = Boolean(opts.reveal);
-            // An explicit human `view --reveal` at a terminal is a deliberate value
-            // access: resolve interactively (one Touch ID) so a locked bundle shows
-            // its values. Under an agent (AGENTS_RUNTIME) or headless (no TTY) it
-            // stays broker-only and errors with the unlock hint — never a sheet.
-            const revealedValues = new Map();
-            if (reveal) {
-                const { env } = readAndResolveBundleEnv(bundle.name, {
-                    caller: 'view --reveal',
-                    keyMode: 'storage',
-                    agentOnly: isHeadlessSecretsContext() || !isInteractiveTerminal(),
-                });
-                for (const entry of entries) {
-                    if (entry.kind === 'keychain' && env[entry.key] !== undefined) {
-                        revealedValues.set(secretsKeychainItem(bundle.name, entry.detail), env[entry.key]);
-                    }
-                }
-                // Revealing plaintext bypasses readAndResolveBundleEnv (the usual
-                // audit chokepoint), so emit here — a `--reveal` exposes real values
-                // and must show up in `agents events --module secrets`. Count both the
-                // keychain values actually decrypted AND the inline literals (which
-                // `--reveal` always prints, even for a literal-only bundle with no
-                // keychain refs — see the entries loop below). Values are never
-                // included, only how many keys were exposed. Emit only when something
-                // was actually shown (a cancelled Touch ID + no literals reveals none).
-                const literalCount = entries.filter((e) => e.kind === 'literal').length;
-                const exposedCount = revealedValues.size + literalCount;
-                if (exposedCount > 0) {
-                    emitSecretAudit({
-                        event: 'secrets.get',
-                        bundle: bundle.name,
-                        operation: 'view --reveal',
-                        source: 'reveal',
-                        status: 'success',
-                        keyCount: exposedCount,
-                    });
-                }
-            }
-            for (const e of entries) {
-                if (e.kind === 'keychain') {
-                    const item = secretsKeychainItem(bundle.name, e.detail);
-                    const stored = bundleItemStore(bundle.backend).has(item);
-                    const marker = stored ? chalk.green('stored') : chalk.red('missing');
-                    let valueCol = `[keychain:${e.detail}] ${marker}`;
-                    if (reveal && revealedValues.has(item)) {
-                        valueCol = redact(revealedValues.get(item), true);
-                    }
-                    console.log(`  ${chalk.cyan(e.key.padEnd(28))} ${kindLabel(e.kind).padEnd(18)} ${valueCol}`);
-                }
-                else if (e.kind === 'literal') {
-                    const raw = bundle.vars[e.key];
-                    const literalValue = typeof raw === 'string'
-                        ? raw
-                        : (raw && typeof raw === 'object' && 'value' in raw ? raw.value : '');
-                    console.log(`  ${chalk.cyan(e.key.padEnd(28))} ${kindLabel(e.kind).padEnd(18)} ${redact(literalValue, reveal)}`);
-                }
-                else {
-                    console.log(`  ${chalk.cyan(e.key.padEnd(28))} ${kindLabel(e.kind).padEnd(18)} ${e.detail}`);
-                }
-                const metaLine = renderMetaLine(bundle.meta?.[e.key], reveal);
-                if (metaLine)
-                    console.log(metaLine);
-            }
-        }
-        catch (err) {
-            if (isPromptCancelled(err))
-                return;
-            console.error(chalk.red(err.message));
-            process.exit(1);
-        }
-    });
-    cmd
-        .command('get <item> [key]')
-        .description('Print one raw keychain item by name, for shell hooks/automation. Cross-platform. Bundle values are never printed — run commands under `agents secrets exec` instead.')
-        .action((item, key) => {
-        if (key !== undefined) {
-            // The bundle-key form (`get <bundle> <KEY>`) is REMOVED (RUSH-2774): a
-            // one-liner that prints a bundle credential is the exfiltration path
-            // this change closes, for every caller. The injection replacement is
-            // just as short for a human script and never touches this stdout.
-            console.error(chalk.red(`'secrets get <bundle> <KEY>' has been removed — printing a bundle value to stdout is the exfiltration path this blocks.`));
-            console.error(chalk.dim(`Use: agents secrets exec ${item} -- printenv ${key}   (or run the consuming command directly under exec)`));
-            process.exit(1);
-        }
-        // Raw keychain item path — a single ad-hoc token, not a credential bundle.
-        // Deliberately NOT agent-gated (unlike the removed bundle-key form): shell
-        // hooks that run inside agent sessions inherit the session env markers and
-        // legitimately capture a raw item into their own variables (e.g. the
-        // posthog analytics hook), where the value never reaches the transcript.
-        // A single ad-hoc token is the accepted narrower residual (RUSH-2774).
-        try {
-            // Routes through the platform keychain layer: macOS reads bare items
-            // via /usr/bin/security (no Touch ID), Linux via secret-tool with the
-            // encrypted-file fallback. The value goes to stdout (newline-terminated
-            // so `$(agents secrets get NAME)` captures it cleanly); diagnostics go
-            // to stderr so they never pollute the captured value.
-            const value = getKeychainToken(item);
-            // Raw item reads bypass readAndResolveBundleEnv, so audit here too.
-            // `item` is the keychain service name, never the value.
-            emitSecretAudit({ event: 'secrets.get', item, source: 'raw-item', status: 'success' });
-            process.stdout.write(value.endsWith('\n') ? value : `${value}\n`);
-        }
-        catch {
-            // Missing item is a normal, quiet outcome for a hook probe: exit 1,
-            // print nothing to stdout. Callers test the exit code / empty capture.
-            process.exit(1);
-        }
-    });
-    cmd
-        .command('set <item>')
-        .description('Store a raw keychain item by name (for shell hooks/automation). Cross-platform; no bundle required.')
-        .option('--value <v>', 'Value to store (omit to read from stdin or be prompted)')
-        .option('--value-stdin', 'Read the value from stdin')
-        .action(async (item, opts) => {
-        try {
-            let value;
-            if (opts.value !== undefined) {
-                value = opts.value;
-            }
-            else if (opts.valueStdin) {
-                value = readStdinSync();
-                if (!value)
-                    throw new Error('No value received on stdin.');
-            }
-            else {
-                value = await promptForSecret(`Enter value for ${item}`);
-            }
-            // setKeychainToken stores bare items WITHOUT the biometry ACL on macOS
-            // so `agents secrets get` can read them back without a password sheet;
-            // on Linux it goes through secret-tool / encrypted-file fallback.
-            setKeychainToken(item, value);
-            // Raw item writes bypass writeBundle (the usual secrets.set chokepoint).
-            emit('secrets.set', { module: 'secrets', item, source: 'raw-item' });
-            console.error(chalk.green(`Stored keychain item '${item}'.`));
-        }
-        catch (err) {
-            if (isPromptCancelled(err))
-                return;
-            console.error(chalk.red(err.message));
-            process.exit(1);
-        }
-    });
-    cmd
-        .command('create [name]')
-        .description('Create an empty bundle. Name it after what it holds — a website by domain (stripe.com, openai.ai), a desktop app by its binary suffix (slack.app, photoshop.exe) — and pass --description.')
-        .option('--description <text>', 'Free-form description (recommended — an undescribed bundle prints a "No description found" nudge)')
-        .option('--allow-exec', 'Allow exec: refs in this bundle (off by default)')
-        .option('--policy <policy>', "prompt policy: hold (default, ask once per hold window — secrets.agent.holdMs, 7d by default), always (ask every time), or never (silent, NO biometry ACL — needs --i-understand). 'daily'/'session' are accepted aliases for 'hold'.")
-        .addOption(new Option('--tier <policy>', 'deprecated alias for --policy').hideHelp())
-        .option('--i-understand', 'Confirm creating a "never"-policy bundle (no biometry ACL) without an interactive prompt')
-        .option('--backend <backend>', 'storage backend: keychain or file (defaults to agents.yaml secrets.backend)')
-        .option('--synced', 'Store this bundle in the age-encrypted synced secrets file for user-managed cross-machine file sync')
-        .option('--force', 'Overwrite an existing bundle')
-        .action(async (name, opts) => {
-        try {
-            const resolvedName = name ?? (await promptBundleName());
-            validateBundleName(resolvedName);
-            // Leave policy unset unless the user explicitly chose one, so the bundle
-            // inherits the configured default (`hold`) instead of being pinned.
-            const policyOpt = opts.policy ?? opts.tier;
-            const policy = policyOpt ? parsePolicyOpt(policyOpt) : undefined;
-            let backend = opts.synced ? 'vault' : resolveBackendOpt(opts.backend);
-            if (isReservedBundleName(resolvedName)) {
-                // Reserved `auth` is file-backed by construction. Omitting --backend
-                // still forces file even when agents.yaml defaults to keychain; an
-                // explicit non-file backend fails loud (SEC-GAP-3).
-                if (opts.synced || (opts.backend && opts.backend !== 'file')) {
-                    throw new ReservedBundleWrongBackendError(resolvedName, backend);
-                }
-                backend = 'file';
-            }
-            if (bundleExists(resolvedName) && !opts.force) {
-                console.error(chalk.red(`Bundle '${resolvedName}' already exists. Use --force to overwrite.`));
-                process.exit(1);
-            }
-            // The `never` tier is the least-safe option — gate it loudly. Throws in a
-            // headless shell without --i-understand; prompts otherwise.
-            const ack = assertNeverPolicyAcknowledged(policy, { iUnderstand: opts.iUnderstand, interactive: isInteractiveTerminal() });
-            if (ack === 'prompt' && !(await confirmNeverPolicyInteractive(resolvedName))) {
-                console.error(chalk.yellow('Aborted.'));
-                return;
-            }
-            const bundle = {
-                name: resolvedName,
-                description: opts.description,
-                allow_exec: opts.allowExec,
-                backend: backend === 'keychain' ? undefined : backend,
-                policy,
-                vars: {},
-            };
-            writeBundle(bundle);
-            // Record the create through the ONE chokepoint (events.jsonl + the usage
-            // read-model). Value-free — bundle name only.
-            emitSecretAudit({ event: 'secrets.create', bundle: resolvedName, operation: 'create', source: 'create', status: 'success' });
-            const policyTag = bundlePolicy(bundle) === 'hold'
-                ? 'policy: hold'
-                : bundlePolicy(bundle) === 'always'
-                    ? 'policy: always ask'
-                    : 'policy: never (NO biometry ACL)';
-            const tags = [
-                policyTag,
-                backend === 'file' ? 'backend: file' : null,
-                backend === 'vault' ? 'synced' : null,
-            ].filter(Boolean);
-            console.log(chalk.green(`Bundle '${resolvedName}' created (${tags.join(', ')}).`));
-            if (!bundle.description) {
-                // A described bundle is self-documenting for the next agent that reads
-                // `list` / `view`. Nudge toward one at create time — never blocking.
-                console.log(chalk.yellow(`No description found. Add one: agents secrets describe ${resolvedName} "what this bundle is for"`));
-            }
-            if (bundlePolicy(bundle) === 'never') {
-                console.log(chalk.red('Stored without biometry protection — reads are silent. Automation-only; rotate anything sensitive out of it.'));
-            }
-            if (backend === 'file') {
-                console.log(chalk.gray('File-backed: items are AES-256-GCM encrypted at rest under a machine-local key (or AGENTS_SECRETS_PASSPHRASE if set); headless reads, no Touch ID.'));
-            }
-            if (backend === 'vault') {
-                console.log(chalk.gray('Synced: items are encrypted in ~/.agents/vault.age. Copy that file with your sync tool of choice.'));
-            }
-            console.log(chalk.gray(`Try: agents secrets add ${resolvedName} MY_KEY`));
-        }
-        catch (err) {
-            if (isPromptCancelled(err))
-                return;
-            console.error(chalk.red(err.message));
-            process.exit(1);
-        }
-    });
-    cmd
-        .command('rename <old> <new>')
-        .alias('mv')
-        .description('Rename a bundle. Moves the metadata and every keychain-backed value to the new name.')
-        .option('--force', 'Overwrite the destination bundle if it already exists (purges its keychain items first)')
-        .action((oldName, newName, opts) => {
-        try {
-            renameBundle(oldName, newName, { force: opts.force });
-            console.log(chalk.green(`Bundle '${oldName}' renamed to '${newName}'.`));
-        }
-        catch (err) {
-            console.error(chalk.red(err.message));
-            process.exit(1);
-        }
-    });
-    cmd
-        .command('describe <name> [text...]')
-        .description('Update the description of a bundle. Pass --clear to remove it.')
-        .option('--clear', 'Remove the existing description')
-        .action((name, textParts, opts) => {
-        try {
-            const bundle = readBundle(name);
-            const text = textParts.join(' ').trim();
-            if (opts.clear) {
-                if (text) {
-                    console.error(chalk.red('Pass either description text or --clear, not both.'));
-                    process.exit(1);
-                }
-                bundle.description = undefined;
-            }
-            else {
-                if (!text) {
-                    console.error(chalk.red('Description text is required. Pass it as an argument or use --clear.'));
-                    process.exit(1);
-                }
-                bundle.description = text;
-            }
-            writeBundle(bundle);
-            console.log(chalk.green(opts.clear
-                ? `Bundle '${name}' description cleared.`
-                : `Bundle '${name}' description updated.`));
-        }
-        catch (err) {
-            console.error(chalk.red(err.message));
-            process.exit(1);
-        }
-    });
-    cmd
-        .command('add [bundle] [key]')
-        .description('Add a variable to a bundle. Defaults to keychain-backed; pass --value for literal, --env/--file/--exec for refs.')
-        .option('--value <v>', 'Store as a plaintext literal in the bundle (non-sensitive values only)')
-        .option('--value-stdin', 'Read the value from stdin (stored in keychain unless combined with --value)')
-        .option('--env <VAR>', 'Store as an env: ref that reads from the parent process.env at run time')
-        .option('--file <path>', 'Store as a file: ref that reads from a file at run time')
-        .option('--exec <cmd>', 'Store as an exec: ref that runs a command at run time (requires allow_exec)')
-        .option('--type <kind>', 'Tag this secret with a type (api-key, token, password, url, database-url, ssh-key, certificate, webhook, note)')
-        .option('--expires <YYYY-MM-DD>', 'Mark when this secret expires (must be future-dated)')
-        .option('--note <text>', 'Attach a freeform note. Pass `-` to read from stdin (mutually exclusive with --value-stdin).')
-        .action(async (bundleName, key, opts) => {
-        try {
-            const resolvedBundleName = bundleName ?? (await pickBundleName('add to'));
-            const bundle = readBundle(resolvedBundleName);
-            const resolvedKey = key ?? (await promptKeyName(resolvedBundleName));
-            validateEnvKey(resolvedKey);
-            if (resolvedKey in bundle.vars) {
-                throw new Error(`Key '${resolvedKey}' already exists in bundle '${resolvedBundleName}'. Use 'agents secrets rotate' to refresh it.`);
-            }
-            const sources = [opts.value !== undefined, Boolean(opts.env), Boolean(opts.file), Boolean(opts.exec)].filter(Boolean).length;
-            if (sources > 1) {
-                throw new Error('Pick one of: --value, --env, --file, --exec.');
-            }
-            const metaPatch = buildMetaPatch(opts);
-            const applyMeta = () => {
-                if (!metaPatch)
-                    return;
-                if (!bundle.meta)
-                    bundle.meta = {};
-                bundle.meta[resolvedKey] = { ...(bundle.meta[resolvedKey] ?? {}), ...metaPatch };
-            };
-            if (opts.env) {
-                bundle.vars[resolvedKey] = `env:${opts.env}`;
-                applyMeta();
-                writeBundle(bundle);
-                console.log(chalk.green(`${resolvedBundleName}.${resolvedKey} -> env:${opts.env}`));
-                return;
-            }
-            if (opts.file) {
-                bundle.vars[resolvedKey] = `file:${opts.file}`;
-                applyMeta();
-                writeBundle(bundle);
-                console.log(chalk.green(`${resolvedBundleName}.${resolvedKey} -> file:${opts.file}`));
-                return;
-            }
-            if (opts.exec) {
-                if (!bundle.allow_exec) {
-                    throw new Error(`Bundle '${resolvedBundleName}' does not allow exec refs. Re-create with --allow-exec.`);
-                }
-                bundle.vars[resolvedKey] = `exec:${opts.exec}`;
-                applyMeta();
-                writeBundle(bundle);
-                console.log(chalk.green(`${resolvedBundleName}.${resolvedKey} -> exec:${opts.exec}`));
-                return;
-            }
-            if (opts.value !== undefined) {
-                bundle.vars[resolvedKey] = { value: opts.value };
-                applyMeta();
-                writeBundle(bundle);
-                console.log(chalk.green(`${resolvedBundleName}.${resolvedKey} = <literal>`));
-                return;
-            }
-            // Default path: stored in the bundle's backend (keychain or file).
-            let secretValue;
-            if (opts.valueStdin) {
-                secretValue = readStdinSync();
-                if (!secretValue)
-                    throw new Error('No value received on stdin.');
-            }
-            else {
-                secretValue = await promptForSecret(`Enter value for ${resolvedBundleName}.${resolvedKey}`);
-            }
-            const item = secretsKeychainItem(resolvedBundleName, resolvedKey);
-            bundle.vars[resolvedKey] = keychainRef(resolvedKey);
-            applyMeta();
-            writeBundleWithItems(bundle, new Map([[item, secretValue]]));
-            const where = bundle.backend === 'file'
-                ? 'encrypted file store'
-                : bundle.backend === 'vault'
-                    ? 'synced secrets file'
-                    : 'keychain';
-            console.log(chalk.green(`${resolvedBundleName}.${resolvedKey} stored in ${where} (${item}).`));
-        }
-        catch (err) {
-            if (isPromptCancelled(err))
-                return;
-            console.error(chalk.red(err.message));
-            process.exit(1);
-        }
-    });
-    cmd
-        .command('rotate [bundle] [key]')
-        .description('Rotate an existing keychain-backed secret (replaces the value, preserves metadata unless overridden).')
-        .option('--value <v>', 'New value (non-secret cases). Prompts interactively if omitted.')
-        .option('--value-stdin', 'Read the new value from stdin (stored in keychain unless combined with --value)')
-        .option('--type <kind>', 'Update the type metadata (api-key, token, password, url, database-url, ssh-key, certificate, webhook, note)')
-        .option('--expires <YYYY-MM-DD>', 'Update the expiration date (must be future-dated)')
-        .option('--note <text>', 'Update the note. Pass `-` to read from stdin (mutually exclusive with --value-stdin).')
-        .option('--clear-meta', 'Wipe all metadata for this key while rotating')
-        .addHelpText('after', `
-Examples:
-  # Rotate the value, preserve all metadata
-  agents secrets rotate prod STRIPE_API_KEY
-
-  # Rotate with a metadata refresh
-  agents secrets rotate prod STRIPE_API_KEY --type api-key --expires 2027-01-15 --note "rotated after employee offboarding"
-`)
-        .action(async (bundleName, key, opts) => {
-        try {
-            const resolvedBundleName = bundleName ?? (await pickBundleName('rotate in'));
-            const bundle = readBundle(resolvedBundleName);
-            const resolvedKey = key ?? (await pickKey(bundle, 'rotate'));
-            if (!(resolvedKey in bundle.vars)) {
-                throw new Error(`Key '${resolvedKey}' not in bundle '${resolvedBundleName}'. Use 'agents secrets add' to add a new key.`);
-            }
-            const raw = bundle.vars[resolvedKey];
-            if (typeof raw !== 'string' || !raw.startsWith('keychain:')) {
-                throw new Error(`Key '${resolvedKey}' in bundle '${resolvedBundleName}' is not keychain-backed; cannot rotate.`);
-            }
-            const metaPatch = buildMetaPatch(opts);
-            if (opts.clearMeta && metaPatch) {
-                throw new Error('--clear-meta and --type/--expires/--note are mutually exclusive.');
-            }
-            // Resolve the new value: --value > --value-stdin > prompt.
-            let newValue;
-            if (opts.value !== undefined) {
-                newValue = opts.value;
-            }
-            else if (opts.valueStdin) {
-                newValue = readStdinSync();
-                if (!newValue)
-                    throw new Error('No value received on stdin.');
-            }
-            else {
-                newValue = await promptForSecret(`Enter new value for ${resolvedBundleName}.${resolvedKey}`);
-            }
-            rotateBundleSecret(bundle, resolvedKey, {
-                newValue,
-                clearMeta: opts.clearMeta,
-                meta: metaPatch,
-            });
-            const where = bundle.backend === 'vault' ? 'synced secrets file' : bundle.backend === 'file' ? 'encrypted file store' : 'keychain';
-            console.log(chalk.green(`${resolvedBundleName}.${resolvedKey} rotated in ${where}.`));
-        }
-        catch (err) {
-            if (isPromptCancelled(err))
-                return;
-            console.error(chalk.red(err.message));
-            process.exit(1);
-        }
-    });
-    cmd
-        .command('remove [bundle] [key]')
-        .description('Remove a key from the bundle. Purges the keychain item if the ref was keychain:. Use --keep-secret to retain it.')
-        .option('--keep-secret', 'Leave the keychain item in place after removing the ref from the bundle')
-        .option('-y, --yes', 'Skip the confirmation prompt when purging a keychain item')
-        .action(async (bundleName, key, opts) => {
-        try {
-            const resolvedBundleName = bundleName ?? (await pickBundleName('remove from'));
-            const bundle = readBundle(resolvedBundleName);
-            const resolvedKey = key ?? (await pickKey(bundle, 'remove'));
-            if (!(resolvedKey in bundle.vars)) {
-                console.error(chalk.red(`Key '${resolvedKey}' not found in bundle '${resolvedBundleName}'.`));
-                process.exit(1);
-            }
-            const raw = bundle.vars[resolvedKey];
-            const willPurge = !opts.keepSecret && typeof raw === 'string' && raw.startsWith('keychain:');
-            if (willPurge && !opts.yes) {
-                if (!isInteractiveTerminal()) {
-                    console.error(chalk.red(`Refusing to purge keychain item for ${resolvedBundleName}.${resolvedKey} non-interactively. ` +
-                        `Pass --yes to confirm or --keep-secret to retain the keychain entry.`));
-                    process.exit(1);
-                }
-                const { confirm } = await import('@inquirer/prompts');
-                const ok = await confirm({
-                    message: `Purge keychain item for ${resolvedBundleName}.${resolvedKey}? (use --keep-secret to retain)`,
-                    default: false,
-                });
-                if (!ok) {
-                    console.log(chalk.gray('Aborted. Bundle metadata unchanged.'));
-                    return;
-                }
-            }
-            delete bundle.vars[resolvedKey];
-            writeBundle(bundle);
-            if (willPurge) {
-                const shortId = raw.slice('keychain:'.length);
-                // Purge only the removed key's own storage slot. A corrupted ref
-                // (e.g. a stale manifest write-back leaving OPENAI_API_KEY pointing
-                // at keychain:LINEAR_API_KEY) must never destroy another key's item —
-                // the ref is gone from the bundle either way; the stray item is the
-                // recoverable side of that trade.
-                if (shortId !== resolvedKey) {
-                    console.log(chalk.yellow(`Removed ${resolvedBundleName}.${resolvedKey}, but its ref pointed at '${shortId}' — ` +
-                        `left that keychain item untouched (it belongs to a different key).`));
-                    return;
-                }
-                const item = secretsKeychainItem(resolvedBundleName, shortId);
-                const removed = bundleItemStore(bundle.backend).delete(item);
-                if (removed) {
-                    const where = bundle.backend === 'file'
-                        ? 'encrypted file item'
-                        : bundle.backend === 'vault'
-                            ? 'synced secrets item'
-                            : 'keychain item';
-                    console.log(chalk.green(`Removed ${resolvedBundleName}.${resolvedKey} and purged ${where}.`));
-                    return;
-                }
-            }
-            console.log(chalk.green(`Removed ${resolvedBundleName}.${resolvedKey}.`));
-        }
-        catch (err) {
-            if (isPromptCancelled(err))
-                return;
-            console.error(chalk.red(err.message));
-            process.exit(1);
-        }
-    });
-    cmd
-        .command('delete [name]')
-        .description('Delete a bundle and purge all its keychain items (use --keep-secrets to retain them).')
-        .option('--keep-secrets', 'Leave keychain items in place after deleting the bundle')
-        .option('-y, --yes', 'Skip the confirmation prompt')
-        .action(async (name, opts) => {
-        try {
-            const resolvedName = name ?? (await pickBundleName('delete'));
-            // An undecryptable bundle (lost/rotated passphrase) must still be
-            // deletable: deletion is the ONLY way out of that state, and every other
-            // verb — view, add, import — refuses to touch the name until it's gone.
-            // Its key refs are unreadable, so its keychain items cannot be
-            // enumerated for purging; say so rather than claiming a clean purge.
-            const bundle = readBundleIfDecryptable(resolvedName);
-            if (!opts.yes) {
-                if (!isInteractiveTerminal()) {
-                    console.error(chalk.red(`Refusing to delete '${resolvedName}' without --yes in a non-interactive shell.`));
-                    process.exit(1);
-                }
-                let suffix;
-                if (!bundle) {
-                    suffix = ' (unreadable — its keychain items cannot be enumerated and will be left in place)';
-                }
-                else {
-                    const keychainCount = describeBundle(bundle).filter((e) => e.kind === 'keychain').length;
-                    suffix = keychainCount && !opts.keepSecrets
-                        ? ` and purge ${keychainCount} keychain item${keychainCount === 1 ? '' : 's'}`
-                        : '';
-                }
-                const { confirm } = await import('@inquirer/prompts');
-                const proceed = await confirm({
-                    message: `Delete bundle '${resolvedName}'${suffix}?`,
-                    default: false,
-                });
-                if (!proceed) {
-                    console.log(chalk.gray('Cancelled.'));
-                    return;
-                }
-            }
-            if (bundle && !opts.keepSecrets) {
-                const store = bundleItemStore(bundle.backend);
-                for (const { item } of keychainItemsForBundle(bundle)) {
-                    store.delete(item);
-                }
-            }
-            const existed = deleteBundle(resolvedName);
-            if (!existed) {
-                console.error(chalk.red(`Bundle '${resolvedName}' not found.`));
-                process.exit(1);
-            }
-            console.log(chalk.green(`Bundle '${resolvedName}' deleted.`));
-        }
-        catch (err) {
-            if (isPromptCancelled(err))
-                return;
-            console.error(chalk.red(err.message));
-            process.exit(1);
-        }
-    });
-    cmd
-        .command('migrate')
-        .description('Interactively migrate legacy YAML bundles into Keychain')
-        .action(async () => {
-        try {
-            if (!isInteractiveTerminal()) {
-                console.error(chalk.red('Refusing to migrate legacy secrets without an interactive confirmation prompt.'));
-                process.exit(1);
-            }
-            const { confirm } = await import('@inquirer/prompts');
-            const migrated = await migrateLegacyBundles(async (candidate) => {
-                console.log(chalk.bold(`Legacy bundle '${candidate.name}'`));
-                console.log(chalk.gray(candidate.file));
-                for (const key of candidate.keys) {
-                    console.log(`  ${key}`);
-                }
-                return await confirm({
-                    message: `Migrate legacy bundle '${candidate.name}' into Keychain?`,
-                    default: false,
-                });
-            });
-            if (migrated === 0) {
-                console.log(chalk.gray('No legacy bundles migrated.'));
-                return;
-            }
-            console.log(chalk.green(`Migrated ${migrated} legacy bundle${migrated === 1 ? '' : 's'} into keychain.`));
-        }
-        catch (err) {
-            if (isPromptCancelled(err))
-                return;
-            console.error(chalk.red(err.message));
-            process.exit(1);
-        }
-    });
-    cmd
-        .command('import [bundle]')
-        .description('Import keys into a bundle from a .env file, a 1Password vault, or legacy iCloud Keychain bundles. The bundle is created if it does not exist. Values are stored in the bundle\'s backend (keychain by default).')
-        .option('--from <source>', "Source: a .env path (- reads stdin), '1password:<vault>', or 'icloud' (legacy iCloud Keychain bundles)")
-        .addOption(new Option('--from-1password', 'deprecated alias for --from 1password:<vault>').hideHelp())
-        .addOption(new Option('--vault <name>', 'deprecated: name the vault in --from 1password:<vault>').hideHelp())
-        .option('--all-plaintext', 'Store every imported value as a literal in the bundle metadata (skip keychain item creation)')
-        .option('--backend <backend>', 'When creating the bundle: keychain or file (defaults to agents.yaml secrets.backend)')
-        .option('--synced', 'When creating the bundle, store it in the age-encrypted synced secrets file')
-        .option('--force', 'Overwrite an existing key in the bundle')
-        .option('--policy <policy>', 'Set the bundle prompt policy as part of this import (always, hold, or never)')
-        .option('--i-understand', 'Confirm an import with policy never (no biometry ACL)')
-        .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 ${SYNC_PASSPHRASE_ENV}; symmetric counterpart of export --to-file)`)
-        .option('--from-ssh', 'Pull the bundle from a fleet peer over SSH and import it locally (requires --device)')
-        .option('--device <peer>', 'SSH peer to pull from when using --from-ssh (device alias or user@host)')
-        .action(async (bundleName, opts) => {
-        try {
-            const importPolicy = opts.policy ? parsePolicyOpt(opts.policy) : undefined;
-            const policyAck = assertNeverPolicyAcknowledged(importPolicy, {
-                iUnderstand: opts.iUnderstand,
-                interactive: isInteractiveTerminal(),
-            });
-            if (policyAck === 'prompt' && !(await confirmNeverPolicyInteractive(bundleName ?? 'imported bundle'))) {
-                console.error(chalk.yellow('Aborted.'));
-                return;
-            }
-            const applyImportPolicy = (bundle) => {
-                if (importPolicy)
-                    bundle.policy = importPolicy;
-                return bundle;
-            };
-            // 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) {
-                // Transport, not the local store's master key — see lib/secrets/sync-passphrase.ts.
-                const passphrase = resolveSyncPassphraseFromEnv().value ?? '';
-                if (!passphrase) {
-                    throw new Error(`--from-file needs ${SYNC_PASSPHRASE_ENV} set to decrypt the bundle file.`);
-                }
-                const env = importBundleFromFile(opts.fromFile, passphrase);
-                const resolvedBundleName = bundleName ?? (await pickBundleName('import into'));
-                const bundle = applyImportPolicy(resolveImportBundle(resolvedBundleName, opts.backend, opts.synced, opts.force));
-                const { added, skipped } = applyEnvToBundle(bundle, env, opts);
-                emitSecretAudit({ event: 'secrets.import', bundle: bundle.name, operation: 'import --from-file', source: 'file', status: 'success', keyCount: added });
-                console.log(chalk.green(`Imported ${added} key(s) from file${skipped ? `, skipped ${skipped} (already set, pass --force)` : ''}.`));
-                return;
-            }
-            if (opts.fromSsh) {
-                if (!opts.device) {
-                    throw new Error('--from-ssh requires --device <peer>.');
-                }
-                assertValidSshTarget(opts.device);
-                const resolvedBundleName = bundleName ?? (await pickBundleName('import into'));
-                const target = await resolveHostSshTarget(opts.device);
-                const env = await remoteResolveEnv(target, resolvedBundleName, { osLookupName: opts.device });
-                const bundle = applyImportPolicy(resolveImportBundle(resolvedBundleName, opts.backend, opts.synced, opts.force));
-                const { added, skipped } = applyEnvToBundle(bundle, env, opts);
-                emitSecretAudit({ event: 'secrets.import', bundle: bundle.name, operation: 'import --from-ssh', source: 'ssh', host: opts.device, status: 'success', keyCount: added });
-                console.log(chalk.green(`Imported ${added} key(s) from ${opts.device}${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.');
-            }
-            if (opts.from1password) {
-                console.log(chalk.yellow('--from-1password is deprecated; use --from 1password:<vault>.'));
-            }
-            const requestedBackend = opts.synced ? 'vault' : resolveBackendOpt(opts.backend);
-            if (source.kind === 'icloud') {
-                await importFromICloud(bundleName, {
-                    force: opts.force,
-                    allPlaintext: opts.allPlaintext,
-                    backend: requestedBackend === 'keychain' ? undefined : requestedBackend,
-                    purge: opts.purge,
-                });
-                return;
-            }
-            const resolvedBundleName = bundleName ?? (await pickBundleName('import into'));
-            // 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 --device ...
-            // --remote-backend file` drives on the remote).
-            const bundle = applyImportPolicy(resolveImportBundle(resolvedBundleName, opts.backend, opts.synced, opts.force));
-            if (source.kind === '1password') {
-                assertOpAvailable();
-                const vault = await resolveVault(source.vault);
-                const items = listItems(vault);
-                const { secrets, skipped: opSkipped } = extractSecrets(items, vault);
-                const env = {};
-                for (const { envKey, value } of secrets)
-                    env[envKey] = value;
-                const { added, skipped } = applyEnvToBundle(bundle, env, opts);
-                emitSecretAudit({ event: 'secrets.import', bundle: bundle.name, operation: `import --from 1password:${vault}`, source: '1password', status: 'success', keyCount: added });
-                if (opSkipped.length) {
-                    console.log(chalk.yellow(`Skipped ${opSkipped.length} item(s) with no importable fields.`));
-                }
-                console.log(chalk.green(`Imported ${added} key(s) from 1Password vault '${vault}'${skipped ? `, skipped ${skipped} (already set, pass --force)` : ''}.`));
-            }
-            else {
-                const raw = readImportDotenv(source.path);
-                const pairs = parseDotenv(raw);
-                const { added, skipped } = applyEnvToBundle(bundle, pairs, opts);
-                emitSecretAudit({ event: 'secrets.import', bundle: bundle.name, operation: 'import --from env-file', source: 'env-file', status: 'success', keyCount: added });
-                console.log(chalk.green(`Imported ${added} key(s)${skipped ? `, skipped ${skipped} (already set, pass --force)` : ''}.`));
-            }
-        }
-        catch (err) {
-            if (isPromptCancelled(err))
-                return;
-            console.error(chalk.red(err.message));
-            process.exit(1);
-        }
-    });
-    cmd
-        .command('export [bundle]')
-        .description('Move a bundle without exposing it: push to remote machine(s) over SSH with --device, to a 1Password vault with --to-1password, or to an encrypted file with --to-file.')
-        // Both transport flags are hidden, not documented: the ONLY caller is the
-        // machine-to-machine SSH resolve (remoteResolveEnv / verifyRemoteKeychainPush),
-        // which sets AGENTS_SECRETS_REMOTE_TRANSPORT=1 on the remote invocation. The
-        // old public shell-eval mode (`eval "$(agents secrets export … --plaintext)"`)
-        // was the top agent-exfiltration path and is removed (RUSH-2774).
-        .addOption(new Option('--plaintext', 'internal remote-resolve transport').hideHelp())
-        .addOption(new Option('--format <json>', 'internal remote-resolve transport').hideHelp())
-        .option('--to-1password', 'Push every key in the bundle as a PASSWORD item in a 1Password vault')
-        .option('--vault <name>', '1Password vault name (used with --to-1password)')
-        .option('--device <target...>', 'Push the bundle over SSH to this device (host alias or user@host); repeatable for multiple machines')
-        .option('--remote-backend <backend>', 'Backend for the bundle on the remote device (with --device): keychain (default) or file. file is headless-readable via the remote\'s machine-local key and never forwards AGENTS_SECRETS_PASSPHRASE.', 'keychain')
-        .option('--force', 'Overwrite existing keys/items on the target (used with --to-1password and --device)')
-        .option('--to-file <path>', `Write the bundle as an AES-256-GCM encrypted offline file (needs ${SYNC_PASSPHRASE_ENV}; symmetric counterpart of import --from-file)`)
-        .action(async (bundleName, opts) => {
-        try {
-            const { readAndResolveBundleEnv } = await import('../lib/secrets/bundles.js');
-            const resolvedBundleName = bundleName ?? (await pickBundleName('export'));
-            if (opts.toFile) {
-                // Transport, not the local store's master key — see lib/secrets/sync-passphrase.ts.
-                const passphrase = resolveSyncPassphraseFromEnv().value ?? '';
-                if (!passphrase) {
-                    throw new Error(`--to-file needs ${SYNC_PASSPHRASE_ENV} 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', keyMode: 'storage', agentOnly: true });
-                exportBundleToFile(env, opts.toFile, passphrase);
-                emitSecretAudit({ event: 'secrets.export', bundle: resolvedBundleName, operation: 'export --to-file', source: 'file', status: 'success', keyCount: Object.keys(env).length });
-                console.log(chalk.green(`Exported ${Object.keys(env).length} key(s) to ${opts.toFile}`));
-                return;
-            }
-            // The presence of --device selects SSH push: --device is the destination
-            // and carries the mode (no separate --to-ssh needed — it would be
-            // strictly redundant since SSH always requires at least one device).
-            const hosts = opts.device ?? [];
-            if (hosts.length > 0) {
-                for (const h of hosts)
-                    assertValidSshTarget(h);
-                const parsedBackend = parseBackendOpt(opts.remoteBackend);
-                // `--remote-backend` documents keychain|file only, and parseBackendOpt
-                // exits on anything else — but its return type still admits 'vault',
-                // which has no remote-push path. Refuse it here rather than let it fall
-                // through to the keychain branch and half-work.
-                if (parsedBackend === 'vault') {
-                    console.error(chalk.red("--remote-backend vault is not supported; use 'keychain' or 'file'."));
-                    process.exit(1);
-                }
-                let remoteBackend = parsedBackend;
-                if (isReservedBundleName(resolvedBundleName)) {
-                    if (opts.remoteBackend && opts.remoteBackend !== 'file') {
-                        throw new ReservedBundleWrongBackendError(resolvedBundleName, parsedBackend);
-                    }
-                    remoteBackend = 'file';
-                }
-                // File-backend export NEVER forwards AGENTS_SECRETS_PASSPHRASE
-                // (PHNX-2371). Forwarding it keys the remote ciphertext to a secret
-                // the destination daemon does not hold, so later headless reads fail
-                // while import still prints "Imported N key(s)". The remote
-                // auto-provisions its own machine-local key instead.
-                // Resolve ONCE for N hosts — reading a bundle can prompt, and doing it
-                // per host would prompt per host.
-                //
-                // Same predicate as `view --reveal` / `exec`: a human at a TTY gets the
-                // Touch ID sheet, an agent launch or a piped/CI run stays broker-only
-                // and fails fast with the `agents secrets unlock` hint. Requiring a
-                // prior unlock for an interactive push was an inconsistency, not a
-                // boundary — this read is strictly less exposed than `view --reveal`,
-                // which already prompts.
-                const resolvedForPush = resolveBundleForPush(resolvedBundleName, 'ssh export', {
-                    agentOnly: isHeadlessSecretsContext() || !isInteractiveTerminal(),
-                });
-                const keyCount = resolvedForPush.keyCount;
-                let failures = 0;
-                for (const host of hosts) {
-                    const out = pushResolvedBundleToHost(resolvedForPush, resolvedBundleName, host, {
-                        remoteBackend,
-                        force: opts.force,
-                        operation: 'ssh export',
-                    });
-                    if (!out.ok) {
-                        failures++;
-                        console.error(chalk.red(`${host}: ${out.message}`));
-                        continue;
-                    }
-                    console.log(chalk.green(`${host} -> '${resolvedBundleName}': ${out.message}`));
-                }
-                emitSecretAudit({ event: 'secrets.export', bundle: resolvedBundleName, operation: `export --device ${hosts.join(',')}`, source: 'ssh', host: hosts.join(','), status: failures > 0 ? 'error' : 'success', keyCount });
-                if (failures > 0)
-                    process.exit(1);
-                return;
-            }
-            if (opts.to1password) {
-                assertOpAvailable();
-                const vault = await resolveVault(opts.vault);
-                const { env } = readAndResolveBundleEnv(resolvedBundleName, { caller: `1Password vault ${vault}`, keyMode: 'storage', agentOnly: true });
-                let created = 0;
-                let overwritten = 0;
-                let skipped = 0;
-                for (const [key, value] of Object.entries(env)) {
-                    const exists = itemExistsByTitle(key, vault);
-                    if (exists) {
-                        if (!opts.force) {
-                            skipped++;
-                            continue;
-                        }
-                        deleteItemByTitle(key, vault);
-                        createPasswordItem(key, value, vault);
-                        overwritten++;
-                    }
-                    else {
-                        createPasswordItem(key, value, vault);
-                        created++;
-                    }
-                }
-                const parts = [];
-                if (created)
-                    parts.push(`${created} created`);
-                if (overwritten)
-                    parts.push(`${overwritten} overwritten`);
-                if (skipped)
-                    parts.push(`${skipped} skipped (already exist, pass --force)`);
-                emitSecretAudit({ event: 'secrets.export', bundle: resolvedBundleName, operation: `export --to-1password ${vault}`, source: '1password', status: 'success', keyCount: created + overwritten });
-                console.log(chalk.green(`Exported to 1Password vault '${vault}': ${parts.join(', ')}.`));
-                return;
-            }
-            // The shell-eval print mode (`eval "$(agents secrets export … --plaintext)"`)
-            // is REMOVED (RUSH-2774): a whole bundle printed to stdout lands in a
-            // coding agent's context and session transcript, and it was the single
-            // most-copied exfiltration one-liner on the fleet. The sole surviving
-            // stdout emitter is the machine-to-machine SSH resolve transport, which
-            // requires the remote-invocation marker AND a non-agent context — both
-            // set only by remoteResolveEnv / verifyRemoteKeychainPush building the
-            // remote command. Everything else gets the refusal with the paved paths.
-            const isTransportCall = process.env.AGENTS_SECRETS_REMOTE_TRANSPORT === '1' &&
-                Boolean(opts.plaintext) &&
-                opts.format === 'json' &&
-                !isAgentInvocationContext();
-            if (!isTransportCall) {
-                console.error(chalk.red('export no longer prints values. Pick a destination:'));
-                console.error(chalk.red('  --device <host> | --to-1password | --to-file <path>'));
-                console.error(chalk.dim(`Run a command with the values injected instead:  agents secrets exec ${resolvedBundleName} -- <cmd>`));
-                console.error(chalk.dim(`Reveal one value at your terminal:               agents secrets view ${resolvedBundleName} --reveal`));
-                process.exit(1);
-            }
-            // Machine-readable form consumed by `remoteResolveEnv` over SSH: single
-            // object of injected env KEY -> value; values verbatim. Broker-only, so a
-            // headless remote read fails fast rather than raising Touch ID. The
-            // resolve emits its own `secrets.get` audit on the remote; no export
-            // event here — that would tally every peer pull as an export.
-            const { env } = readAndResolveBundleEnv(resolvedBundleName, {
-                caller: 'remote resolve transport',
-                keyMode: 'process',
-                agentOnly: true,
-            });
-            process.stdout.write(JSON.stringify(env));
-        }
-        catch (err) {
-            if (isPromptCancelled(err))
-                return;
-            console.error(chalk.red(err.message));
-            process.exit(1);
-        }
-    });
-    cmd
-        .command('exec <bundle> [command...]')
-        .description('Run a command with the bundle\'s secrets injected into the environment (use --device to resolve the bundle from a remote machine, ephemerally)')
-        .option('--device <target>', 'Resolve <bundle> on a remote device over SSH and inject it (ephemeral — never stored on this machine)')
-        .option('--keys <keys>', 'Inject only this comma-separated subset of keys (e.g. KEY1,KEY2). Missing keys are an error.')
-        .option('--allow-expired', 'Inject keys even if their expiry date has passed (overrides the pre-run expiry abort).')
-        .allowUnknownOption()
-        .action(async (bundleName, commandParts, execOpts) => {
-        try {
-            if (commandParts.length === 0) {
-                console.error(chalk.red('Usage: agents secrets exec <bundle> -- <command...>'));
-                process.exit(1);
-            }
-            const [cmd, ...args] = commandParts;
-            const keysSubset = execOpts.keys
-                ? execOpts.keys.split(',').map((k) => k.trim()).filter(Boolean)
-                : undefined;
-            let secretEnv;
-            if (execOpts.device) {
-                // Least-privilege flags do not yet cross the SSH resolver —
-                // silently applying them would inject the full remote env or an
-                // expired key. Fail loud so the user can drop the flag or run
-                // locally instead.
-                const { assertRemoteBundleFlagsUnsupported } = await import('../lib/secrets/bundles.js');
-                assertRemoteBundleFlagsUnsupported(bundleName, execOpts.device, { keys: keysSubset, allowExpired: execOpts.allowExpired }, { keysFlag: '--keys', allowExpiredFlag: '--allow-expired' });
-                secretEnv = await remoteResolveEnv(await resolveHostSshTarget(execOpts.device), bundleName, { osLookupName: execOpts.device });
-            }
-            else {
-                const { readAndResolveBundleEnv } = await import('../lib/secrets/bundles.js');
-                secretEnv = readAndResolveBundleEnv(bundleName, {
-                    caller: `command ${cmd}`,
-                    keys: keysSubset,
-                    allowExpired: execOpts.allowExpired,
-                    // An explicit `secrets exec` at a real terminal is a deliberate use of
-                    // the values: an unlocked bundle runs silently, a locked one resolves
-                    // with one Touch ID sheet, then the command runs with the secrets
-                    // injected. Under an agent (AGENTS_RUNTIME) or headless (no TTY) it
-                    // stays broker-only and points at the explicit unlock command instead
-                    // of raising a sheet — so release/CI scripts never prompt.
-                    agentOnly: isHeadlessSecretsContext() || !isInteractiveTerminal(),
-                }).env;
-            }
-            const { spawn } = await import('child_process');
-            // On Windows, spawn without a shell ENOENTs for `.cmd`/`.bat` launchers
-            // (npm, yarn, most JS CLIs) and shell built-ins, so we set shell:true.
-            // With shell:true Node hands cmd.exe a single command line with NO quoting
-            // of its own. Compose that line ourselves (composeWin32CommandLine quotes
-            // every token) and pass an EMPTY args array so Node never concatenates the
-            // user-supplied args unescaped (DEP0190 + injection). See that helper for
-            // the cmd.exe %VAR%/!VAR! expansion caveat.
-            const useShell = process.platform === 'win32';
-            const spawnCmd = useShell ? composeWin32CommandLine(cmd, args) : cmd;
-            const spawnArgs = useShell ? [] : args;
-            const proc = spawn(spawnCmd, spawnArgs, {
-                stdio: 'inherit',
-                shell: useShell,
-                env: buildSecretsExecEnv(process.env, secretEnv),
-            });
-            proc.on('close', (code) => process.exit(code ?? 0));
-            proc.on('error', (err) => {
-                console.error(chalk.red(`Failed to run '${cmd}': ${err.message}`));
-                process.exit(1);
-            });
-        }
-        catch (err) {
-            if (isPromptCancelled(err))
-                return;
-            console.error(chalk.red(err.message));
-            process.exit(1);
-        }
-    });
-    cmd
-        .command('mcp')
-        .description('Run a stdio MCP server exposing get_secret(bundle, key) — hand credentials to an MCP-speaking agent by name at call time, never through the child process environment')
-        .action(async () => {
-        // JIT credential delivery (#333): unlike `secrets exec`, which bakes every
-        // resolved value into the child's env, this speaks MCP over stdio so a
-        // framework requests one secret at a time and the raw value never enters
-        // process.env. stdout is the JSON-RPC channel — nothing else may print there.
-        const { runSecretsMcpServer } = await import('../lib/secrets/mcp.js');
-        await runSecretsMcpServer({ version: getCliVersion() });
-    });
-    const openclawKeychain = cmd
-        .command('openclaw-keychain')
-        .description('Migrate supported OpenClaw credentials from plaintext config to macOS Keychain-backed SecretRefs');
-    openclawKeychain
-        .command('migrate [config]')
-        .description('Rewrite supported OpenClaw plaintext secrets to exec SecretRefs backed by macOS Keychain')
-        .option('--account <name>', 'Keychain account name', 'openclaw')
-        .option('--dry-run', 'Inspect the migration without writing Keychain or config changes')
-        .action(async (configArg, opts) => {
-        try {
-            const configPath = configArg || path.join(os.homedir(), '.openclaw', 'openclaw.json');
-            const { migrateOpenClawConfigToKeychainRefs, storeOpenClawKeychainServices } = await import('../lib/openclaw-keychain.js');
-            const before = fs.readFileSync(configPath, 'utf-8');
-            const config = JSON.parse(before);
-            const result = migrateOpenClawConfigToKeychainRefs(config, { account: opts.account });
-            if (result.unsupportedEnvKeys.length > 0) {
-                throw new Error(`OpenClaw top-level env keys have no supported SecretRef target: ${result.unsupportedEnvKeys.join(', ')}. ` +
-                    `Move them to a supported credential field before removing plaintext.`);
-            }
-            if (!opts.dryRun) {
-                storeOpenClawKeychainServices(result.services, opts.account);
-                if (result.changed)
-                    fs.writeFileSync(configPath, `${JSON.stringify(config, null, 2)}\n`, 'utf-8');
-            }
-            console.log(`OpenClaw Keychain migration ${opts.dryRun ? 'plan' : 'complete'}: ${result.services.length} secret${result.services.length === 1 ? '' : 's'}, ${result.replacedPaths.length} ref${result.replacedPaths.length === 1 ? '' : 's'}, ${result.removedEnvPaths.length} env entr${result.removedEnvPaths.length === 1 ? 'y' : 'ies'} removed.`);
-            for (const p of result.replacedPaths)
-                console.log(`ref ${p}`);
-            for (const p of result.removedEnvPaths)
-                console.log(`removed ${p}`);
-            process.exit(0);
-        }
-        catch (err) {
-            console.error(chalk.red(err.message));
-            process.exit(1);
-        }
-    });
-    openclawKeychain
-        .command('resolve')
-        .description('OpenClaw exec SecretRef resolver for Keychain service ids')
-        .option('--account <name>', 'Keychain account name', 'openclaw')
-        .action(async (opts) => {
-        try {
-            const { readOpenClawKeychainService, resolveOpenClawKeychainRequest } = await import('../lib/openclaw-keychain.js');
-            const raw = readStdinSync();
-            const request = raw.trim() ? JSON.parse(raw) : {};
-            const response = resolveOpenClawKeychainRequest(request, (service) => readOpenClawKeychainService(service, opts.account));
-            process.stdout.write(JSON.stringify(response));
-            process.exit(0);
-        }
-        catch {
-            process.stdout.write(JSON.stringify({ protocolVersion: 1, values: {}, errors: { value: { code: 'NOT_FOUND' } } }));
-            process.exit(1);
-        }
-    });
-    cmd
-        .command('generate [length]')
-        .description('Generate a random password')
-        .option('-U, --uppercase', 'Include A-Z (default: on)')
-        .option('-l, --lowercase', 'Include a-z (default: on)')
-        .option('-d, --digits', 'Include 0-9 (default: on)')
-        .option('-s, --symbols', 'Include symbols (default: on)')
-        .option('--no-uppercase', 'Exclude A-Z')
-        .option('--no-lowercase', 'Exclude a-z')
-        .option('--no-digits', 'Exclude 0-9')
-        .option('--no-symbols', 'Exclude symbols')
-        .option('--strong', 'Include all character classes')
-        .option('--pin', 'Digits only (shortcut for -d --no-uppercase --no-lowercase --no-symbols)')
-        .option('--hex', 'Hex characters only (0-9, a-f)')
-        .option('-c, --copy', 'Copy to clipboard (does not print)')
-        .action(async (lengthArg, opts) => {
-        const length = lengthArg ? parseInt(lengthArg, 10) : 32;
-        if (isNaN(length) || length < 1 || length > 1024) {
-            console.error(chalk.red('Length must be a number between 1 and 1024.'));
-            process.exit(1);
-        }
-        const UPPER = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ';
-        const LOWER = 'abcdefghijklmnopqrstuvwxyz';
-        const DIGITS = '0123456789';
-        const SYMBOLS = '!@#$%^&*()-_=+[]{}|;:,.<>?';
-        const HEX_LOWER = '0123456789abcdef';
-        let charClasses = [];
-        if (opts.hex) {
-            charClasses = [HEX_LOWER];
-        }
-        else if (opts.pin) {
-            charClasses = [DIGITS];
-        }
-        else {
-            const useUpper = opts.strong || opts.uppercase !== false;
-            const useLower = opts.strong || opts.lowercase !== false;
-            const useDigits = opts.strong || opts.digits !== false;
-            const useSymbols = opts.strong || opts.symbols !== false;
-            if (useUpper)
-                charClasses.push(UPPER);
-            if (useLower)
-                charClasses.push(LOWER);
-            if (useDigits)
-                charClasses.push(DIGITS);
-            if (useSymbols)
-                charClasses.push(SYMBOLS);
-        }
-        if (charClasses.length === 0) {
-            console.error(chalk.red('At least one character class must be enabled.'));
-            process.exit(1);
-        }
-        const randomBytes = crypto.getRandomValues(new Uint32Array(length * 2));
-        let password = '';
-        for (let i = 0; i < length; i++) {
-            const classIndex = randomBytes[i * 2] % charClasses.length;
-            const charClass = charClasses[classIndex];
-            const charIndex = randomBytes[i * 2 + 1] % charClass.length;
-            password += charClass[charIndex];
-        }
-        if (opts.copy) {
-            try {
-                await copyToClipboard(password);
-                console.log(chalk.green(`Password copied to clipboard (${length} chars)`));
-            }
-            catch (err) {
-                console.error(chalk.red(`Clipboard copy failed: ${err.message}`));
-                console.error(chalk.gray('Re-run without --copy to print the password instead.'));
-                process.exitCode = 1;
-            }
-        }
-        else {
-            console.log(password);
-        }
-    });
-    cmd
-        .command('unlock [names...]')
-        .description('Hold a bundle in the secrets-agent after one Touch ID, so concurrent runs read it without re-prompting (macOS). With --device, unlock FILE-backed bundle(s) on a remote (the passphrase prompt surfaces over the SSH TTY); keychain/biometry bundles are GUI-only and can\'t be remote-unlocked.')
-        .option('--ttl <duration>', 'How long to hold it (e.g. 30m, 8h, 3d). Default 7d.')
-        .option('--until <date>', 'Hold until this absolute date or timestamp (for example 2026-08-06T12:00:00Z). Mutually exclusive with --ttl.')
-        .option('--durable', 'Keep the unlock across sleep + reboot too (default: survives upgrade/restart but re-locks on sleep). Set secrets.agent.durable in agents.yaml to make this the default.')
-        .option('--agent <agent>', 'Narrow the unlock to ONE harness type (for example claude, codex, or kimi). Default: the grant is global — every harness and a plain shell can read it, so one Touch ID covers them all.')
-        .option('--keys <keys>', 'Hold ONLY this comma-separated subset of the bundle\'s keys instead of the whole bundle. Scopes exactly one bundle; fails closed on an unknown key. `secrets status` shows which keys a scoped hold covers.')
-        .option('--all', 'Unlock every configured bundle')
-        .option('--device <target>', 'Unlock the bundle(s) on this remote device over SSH instead of locally (file-backed bundles only — the remote\'s passphrase prompt surfaces on your terminal over a -tt session). Single-valued (NOT variadic) so it never swallows the bundle name: `unlock <name> --device <machine>`.')
-        .action(async (names, opts) => {
-        if (opts.ttl && opts.until) {
-            console.error(chalk.red('--ttl and --until are mutually exclusive.'));
-            process.exit(1);
-        }
-        if (opts.keys !== undefined) {
-            // --keys scopes ONE bundle to an explicit subset. It is local-only (a
-            // remote --device unlock holds the whole file-backed bundle) and cannot
-            // combine with --all, which would hold every bundle whole.
-            if (opts.device) {
-                console.error(chalk.red('--keys is local-only; a remote (--device) unlock holds the whole file-backed bundle.'));
-                process.exit(1);
-            }
-            if (opts.all || !names || names.length !== 1) {
-                console.error(chalk.red('--keys scopes ONE bundle to a subset of its keys: name exactly one bundle (not --all).'));
-                process.exit(1);
-            }
-        }
-        // Single-valued (not variadic): a variadic --device greedily consumes the
-        // positional bundle name (`unlock --device mac wztest` -> device=[mac,wztest],
-        // names=[]). Unlock targets one remote at a time anyway.
-        const hosts = opts.device ? [opts.device] : [];
-        if (hosts.length > 0) {
-            // Remote unlock: the REMOTE enforces its own platform rules, so the
-            // local darwin-only guard below does NOT apply. Only file-backed
-            // bundles are remote-unlockable — their passphrase prompt surfaces over
-            // the -tt SSH TTY; a keychain/biometry bundle would trigger a local GUI
-            // Touch-ID sheet that can't cross SSH.
-            if (!opts.all && (!names || names.length === 0)) {
-                console.error(chalk.red('Specify one or more bundle names, or --all.'));
-                process.exit(1);
-            }
-            const unlockArgs = buildRemoteUnlockArgs(names, opts);
-            let failures = 0;
-            for (const h of hosts) {
-                const target = await resolveHostSshTarget(h);
-                // FOREGROUND stream (stdio inherited), NOT the piped remoteSecretsRaw:
-                // the remote's passphrase prompt only surfaces if the remote process
-                // sees a real TTY, which requires our local terminal to pass straight
-                // through. The remote's prompt + output stream to this terminal; we get
-                // back only the exit code.
-                const code = remoteSecretsStream(target, unlockArgs, { osLookupName: h });
-                if (code === 0) {
-                    console.log(chalk.green(`${h}: unlocked`));
-                }
-                else {
-                    failures++;
-                    console.error(chalk.red(`${h}: unlock failed (exit ${code})`));
-                }
-            }
-            if (failures > 0)
-                process.exit(1);
-            return;
-        }
-        if (opts.until) {
-            try {
-                resolveUnlockTtlMs(undefined, opts.until);
-            }
-            catch (err) {
-                console.error(chalk.red(err.message));
-                process.exit(1);
-            }
-        }
-        if (process.platform !== 'darwin') {
-            // No broker + no biometry prompt off darwin: secrets already resolve
-            // durably from the OS store (libsecret / Credential Manager) on every
-            // read with no prompt, so an unlock is a friendly no-op — not an error.
-            // Accept --durable as a documented no-op so the command is uniform.
-            console.log(chalk.gray('Nothing to unlock: secrets already persist on this OS — reads never re-prompt.'));
-            return;
-        }
-        let targets = opts.all ? listBundles().map((b) => b.name) : names;
-        if (!targets || targets.length === 0) {
-            console.error(chalk.red('Specify one or more bundle names, or --all.'));
-            process.exit(1);
-        }
-        let ttlMs;
-        try {
-            ttlMs = resolveUnlockTtlMs(opts.ttl, opts.until);
-        }
-        catch (err) {
-            console.error(chalk.red(err.message));
-            process.exit(1);
-        }
-        const expiresAt = Date.now() + ttlMs;
-        if (!isSecretsBrokerEnabled()) {
-            console.error(chalk.red('Secrets broker is disabled — re-enable with \'agents daemon services enable secrets-broker\'.'));
-            process.exit(1);
-        }
-        if (!(await ensureAgentRunning())) {
-            console.error(chalk.red('Could not start the secrets broker.'));
-            process.exit(1);
-        }
-        // #415: the daemon should be always-on for any background need, not only
-        // after `routines add`. `ensureAgentRunning` prefers the daemon (it hosts
-        // the broker, #416), but can fall back to a one-off broker spawn when the
-        // daemon can't come up — so ensure the daemon is up regardless. Idempotent
-        // (single-instance start lock, #414) and best-effort — never blocks unlock.
-        ensureDaemonStarted();
-        let loaded = 0;
-        // An unlock is a deliberate act, so it grants GLOBALLY unless `--agent`
-        // narrows it to one harness. It must NOT inherit the ambient
-        // AGENTS_AGENT_NAME: that silently scoped a terminal unlock to whichever
-        // agent happened to launch the shell, leaving the grant unreadable to
-        // every other reader for its whole TTL.
-        const harness = opts.agent || GLOBAL_HARNESS;
-        const durable = opts.durable ?? secretsAgentDurable();
-        for (const name of targets) {
-            try {
-                // noAgent: read the real keychain (one Touch ID) rather than the
-                // agent we're about to populate. Snapshot time is captured BEFORE the
-                // read so a concurrent eviction always beats this load (broker
-                // tombstones reject snapshots that predate an eviction).
-                const snapshotAt = Date.now();
-                const { bundle, env } = readAndResolveBundleEnv(name, {
-                    noAgent: true,
-                    caller: 'unlock secrets',
-                    agent: harness,
-                    duration: humanRemaining(expiresAt),
-                    keyMode: 'storage',
-                });
-                // Migrations are authorized only by this explicit unlock. The bundle
-                // metadata was included in the successful authenticated batch, so the
-                // ACL heal can rewrite that already-read value without another read.
-                maybeAutoRekey();
-                healKeychainBundleMetadataAclOnce(new Map([[bundle.name, JSON.stringify(bundle)]]));
-                // With --keys, hold ONLY the resolved subset behind a lease that scopes
-                // the broker entry and its own expiry; without it, the whole bundle is
-                // held exactly as before. scopeHeldEnv fails closed on an unknown key.
-                const { heldEnv, lease } = scopeHeldEnv({ bundle: name, env, keys: opts.keys ?? null, ttlMs, harness, sleepPersist: durable });
-                const heldExpiresAt = lease ? lease.expiresAt : expiresAt;
-                if (await agentLoad(name, bundle, heldEnv, ttlMs, harness, lease, snapshotAt)) {
-                    loaded++;
-                    // Persist a durable session snapshot so the unlock survives a daemon
-                    // restart / upgrade (and sleep too, with --durable). session-store.ts.
-                    // A scoped hold persists its lease so it rehydrates scoped.
-                    saveSession(name, {
-                        bundle,
-                        env: heldEnv,
-                        expiresAt: heldExpiresAt,
-                        sleepPersist: durable,
-                        harness,
-                        lease,
-                    });
-                    // Audit the GRANT itself — the broker + durable session now serve this
-                    // bundle prompt-free for the whole TTL, to every reader in `harness`
-                    // scope. The pre-read above emits `secrets.get`; this records the
-                    // longer-lived unlock a `secrets.get` does not capture. Key NAMES only.
-                    emitSecretAudit({
-                        event: 'secrets.unlocked',
-                        bundle: name,
-                        operation: 'unlock',
-                        source: durable ? 'broker+durable' : 'broker',
-                        status: 'success',
-                        keyCount: Object.keys(heldEnv).length,
-                        keys: Object.keys(heldEnv).sort(),
-                        agent: harness,
-                        ttlMs,
-                    });
-                    const scoped = lease ? chalk.gray(` scoped to ${lease.keys.join(', ')}`) : '';
-                    console.log(`${chalk.green('unlocked')} ${chalk.cyan(name)} ${chalk.gray(`(${Object.keys(heldEnv).length} keys, ${humanRemaining(heldExpiresAt)})`)}${scoped}`);
-                }
-                else {
-                    console.error(chalk.red(`Failed to load '${name}' into the agent.`));
-                }
-            }
-            catch (err) {
-                if (isPromptCancelled(err)) {
-                    console.error(chalk.yellow(`Cancelled unlocking '${name}'.`));
-                    continue;
-                }
-                console.error(chalk.red(`${name}: ${err.message}`));
-            }
-        }
-        if (loaded === 0)
-            process.exit(1);
-    });
-    cmd
-        .command('lock [names...]')
-        .description('Wipe bundles from the secrets-agent (forces Touch ID again next read). Default: all.')
-        .option('--all', 'Wipe every unlocked bundle (same as no names)')
-        .action(async (names, opts) => {
-        if (process.platform !== 'darwin')
-            return; // nothing to lock off darwin
-        if (names && names.length > 0 && !opts.all) {
-            let total = 0;
-            for (const name of names) {
-                total += await agentLock(name);
-                deleteBundleSessions(name); // drop every harness scope
-            }
-            console.log(total > 0 ? chalk.green(`Locked ${total} bundle(s).`) : chalk.gray('Nothing to lock.'));
-        }
-        else {
-            const wiped = await agentLock();
-            deleteAllSessions();
-            console.log(wiped > 0 ? chalk.green(`Locked ${wiped} bundle(s).`) : chalk.gray('Nothing to lock.'));
-        }
-    });
-    cmd
-        .command('status')
-        .description('Show which bundles the secrets-agent currently holds and when they lock.')
-        .action(async () => {
-        if (process.platform !== 'darwin') {
-            console.log(chalk.gray('secrets-agent is macOS-only.'));
-            return;
-        }
-        if (!isSecretsBrokerEnabled()) {
-            console.log(chalk.yellow('broker: disabled — re-enable with \'agents daemon services enable secrets-broker\''));
-            return;
-        }
-        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 `hold` 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(renderHoldSummary(holdStr, configured)));
-        const entries = await agentStatus();
-        const held = new Set(entries.map((e) => e.name));
-        if (entries.length === 0) {
-            console.log(chalk.gray(NO_BUNDLES_HELD_LINE));
-            console.log(chalk.gray('Pre-warm now with: agents secrets unlock <bundle>  (or --all)'));
-        }
-        else {
-            console.log(chalk.bold(`${'BUNDLE'.padEnd(24)} ${'KEYS'.padEnd(5)} LOCKS IN`));
-            for (const e of entries) {
-                // A scoped hold (unlock --keys) carries the held key names, so name them
-                // rather than leave the bundle looking whole.
-                const scoped = e.keys?.length ? chalk.gray(`  scoped: ${e.keys.join(', ')}`) : '';
-                console.log(`${chalk.cyan(e.name.padEnd(24))} ${String(e.keyCount).padEnd(5)} ${humanRemaining(e.expiresAt)}${scoped}`);
-            }
-            console.log(chalk.gray('Reads of held bundles are silent; any bundle not listed prompts once on its next read.'));
-        }
-        // Usage hint: bundles you keep getting a Touch ID prompt for — a keychain
-        // read that fell through to biometry (not served by the broker/session)
-        // >= a few times in the last week, and not currently held. Unlocking each
-        // once silences it for the hold window. This runs even when NO bundle is
-        // held — that user re-prompts on every read and most needs the nudge.
-        // Excludes `never`/no-ACL bundles (never prompt) and file/vault bundles
-        // (resolve by passphrase, not the keychain broker — `unlock` is a no-op).
-        try {
-            const weekAgo = new Date(Date.now() - 7 * 24 * 60 * 60 * 1000);
-            const reads = query({ eventTypes: ['secrets.get'], startDate: weekAgo });
-            const hot = frequentlyPromptedBundles(reads, held, { minReads: 3 }).filter((h) => {
-                try {
-                    return bundleBackend(h.name) === 'keychain' && bundlePolicy(readBundle(h.name)) !== 'never';
-                }
-                catch {
-                    return false; // bundle gone / unreadable metadata — nothing to suggest
-                }
-            });
-            if (hot.length > 0) {
-                console.log();
-                console.log(chalk.bold('Prompted often — unlock once to silence:'));
-                for (const h of hot) {
-                    console.log(`${chalk.cyan(h.name.padEnd(24))} ${chalk.gray(`${h.count}× in the last 7d`)}  →  ${chalk.green(`agents secrets unlock ${h.name}`)}`);
-                }
-            }
-        }
-        catch {
-            // Best-effort hint — never let usage analysis break `secrets status`.
-        }
-    });
-    cmd
-        .command('policy <bundle> [policy]')
-        .alias('tier')
-        .description("Show or set a bundle's prompt policy: hold (default, ask once per hold window — secrets.agent.holdMs, 7d by default), always (ask every time), or never (silent, NO biometry ACL). 'daily'/'session' are accepted aliases for 'hold'.")
-        .option('--i-understand', 'Confirm switching to the "never" policy (no biometry ACL) without an interactive prompt')
-        .action(async (bundleName, policyArg, opts) => {
-        try {
-            const bundle = readBundle(bundleName);
-            if (policyArg === undefined) {
-                console.log(`${chalk.cyan(bundle.name)} policy: ${chalk.bold(bundlePolicy(bundle))}`);
-                return;
-            }
-            const next = parsePolicyOpt(policyArg);
-            // Switching to `never` drops the biometry ACL — gate it exactly like create.
-            const ack = assertNeverPolicyAcknowledged(next, { iUnderstand: opts.iUnderstand, interactive: isInteractiveTerminal() });
-            if (ack === 'prompt' && !(await confirmNeverPolicyInteractive(bundle.name))) {
-                console.error(chalk.yellow('Aborted.'));
-                return;
-            }
-            bundle.policy = next;
-            // Re-store the VALUE items so their keychain ACL matches the new tier —
-            // NOT just the metadata. macOS gates each read on the item's own ACL
-            // (SEC-19); a metadata-only write would leave a hold/always bundle's
-            // biometry ACL in place and keep popping Touch ID forever after a switch
-            // to `never`. reAclBundleItems reads once (the last prompt this bundle
-            // raises when tightening to `never`), rewrites no-ACL, and evicts any
-            // broker-held copy so the change takes effect on the very next read.
-            reAclBundleItems(bundle);
-            console.log(chalk.green(`${bundle.name} policy set to ${next}.`));
-            if (next === 'hold') {
-                console.log(chalk.gray('Held by the secrets-agent for ~7 days after one unlock (auto-cache is on by default; disable with `secrets.agent.auto: false` in agents.yaml).'));
-            }
-            else if (next === 'always') {
-                console.log(chalk.gray('Asks for Touch ID every time — never auto-held.'));
-            }
-            else {
-                console.log(chalk.red('Stored without biometry protection — reads are silent. Automation-only.'));
-            }
-        }
-        catch (err) {
-            console.error(chalk.red(err.message));
-            process.exit(1);
-        }
-    });
-    cmd
-        .command('start')
-        .description('Bring up the always-on daemon that hosts the secrets broker (macOS). Survives heavy load; reads connect instantly.')
-        .action(async () => {
-        if (process.platform !== 'darwin') {
-            console.error(chalk.red('The secrets broker is macOS-only.'));
-            process.exit(1);
-        }
-        if (!isSecretsBrokerEnabled()) {
-            console.error(chalk.yellow('Secrets broker is disabled — the daemon will start but will not host the broker. Re-enable with \'agents daemon services enable secrets-broker\'.'));
-        }
-        process.stdout.write(chalk.gray('Starting the daemon…\n'));
-        ensureDaemonStarted();
-        // The daemon hosts the broker socket-first; wait briefly for it to answer.
-        const deadline = Date.now() + 10000;
-        let reachable = (await agentPing()).reachable;
-        while (!reachable && Date.now() < deadline) {
-            await new Promise((r) => setTimeout(r, 200));
-            reachable = (await agentPing()).reachable;
-        }
-        if (reachable) {
-            console.log(chalk.green('secrets broker running.') + chalk.gray(' Hosted by the always-on daemon; unlock/auto-cache now connect instantly.'));
-        }
-        else {
-            console.error(chalk.red('Daemon started but the broker did not become reachable in time (machine may be heavily loaded — it will keep retrying).'));
-            process.exit(1);
-        }
-    });
-    cmd
-        .command('stop')
-        .description('Lock all bundles and retire any legacy standalone service. The always-on daemon (which hosts the broker) is left running.')
-        .action(async () => {
-        if (process.platform !== 'darwin')
-            return;
-        await uninstallSecretsAgentService();
-        console.log(chalk.green('Locked all bundles.') + chalk.gray(' The broker stays hosted by the always-on daemon; a legacy standalone service, if any, was retired.'));
-    });
-    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 runAgentLoadFromStdin();
-    });
-    registerSecretsSyncCommands(cmd);
-    registerSecretsMigrateAclCommand(cmd);
-    registerSecretsImportKeyringCommand(cmd);
-    registerSecretsRotatePassphraseCommand(cmd);
-}
-/** Validate a prompt-policy value, throwing a clear message on a bad one (the
- * caller's try/catch renders it and exits). Accepts the legacy `biometry` /
- * `session` / `none` tokens as aliases for `always` / `daily` / `never` so older
- * flags and scripts keep working. `never`/`none` is the no-biometry-ACL tier —
- * accepted here, then gated behind a loud confirmation in the command layer. */
-export function parsePolicyOpt(raw) {
-    const v = (raw ?? 'always').toLowerCase();
-    if (v === 'always' || v === 'biometry')
-        return 'always';
-    if (v === 'hold' || v === 'daily' || v === 'session')
-        return 'hold';
-    if (v === 'never' || v === 'none')
-        return 'never';
-    throw new Error(`Invalid policy '${raw}'. Use 'always', 'hold', or 'never'.`);
-}
-/**
- * Gate a create/switch to the `never` prompt-policy behind an explicit,
- * deliberate acknowledgement — it is the least-safe tier (no user-presence
- * check on any read). Returns:
- *   - `'ok'`    — not `never`, or already acknowledged via `--i-understand`.
- *   - `'prompt'` — interactive shell: caller must run a loud confirm prompt.
- * Throws in a non-interactive shell when the flag is absent, so a headless
- * `create --policy never` can't silently downgrade a bundle's protection.
- */
-export function assertNeverPolicyAcknowledged(policy, opts) {
-    if (policy !== 'never')
-        return 'ok';
-    if (opts.iUnderstand)
-        return 'ok';
-    if (!opts.interactive) {
-        throw new Error("Refusing to set the 'never' prompt-policy without confirmation. This tier stores " +
-            'the bundle WITHOUT the biometry access control: every read is silent, with no Touch ID ' +
-            'and no user-presence check — any code running as you can read it. Re-run with ' +
-            '--i-understand to confirm you want an unprotected, automation-only bundle.');
-    }
-    return 'prompt';
-}
-/** Loud confirm prompt shown before creating/switching to `never` in a TTY.
- * Returns true to proceed. Kept separate from assertNeverPolicyAcknowledged so
- * the decision logic stays pure and unit-testable. */
-async function confirmNeverPolicyInteractive(bundleName) {
-    console.error(chalk.red.bold('WARNING: policy "never" stores this bundle with NO biometry ACL.'));
-    console.error(chalk.red(`Reads of '${bundleName}' will be fully silent — no Touch ID, no user-presence check.`));
-    console.error(chalk.yellow('Use it only for low-sensitivity, automation-only credentials.'));
-    const { confirm } = await import('@inquirer/prompts');
-    return confirm({ message: `Store '${bundleName}' WITHOUT biometry protection?`, default: false });
-}
-/** Validate a --backend value, exiting with a clear message on a bad one. */
-export function secretsDefaultBackend() {
-    const raw = readMeta().secrets?.backend;
-    if (raw === undefined)
-        return 'keychain';
-    if (raw === 'keychain' || raw === 'file' || raw === 'vault')
-        return raw;
-    console.error(chalk.red(`Invalid secrets.backend '${raw}'. Use 'keychain', 'file', or 'vault'.`));
-    process.exit(1);
-}
-function parseBackendOpt(raw, defaultBackend = 'keychain') {
-    const v = (raw ?? defaultBackend).toLowerCase();
-    if (!raw && v === 'vault')
-        return 'vault';
-    if (v === 'keychain' || v === 'file')
-        return v;
-    console.error(chalk.red(`Invalid --backend '${raw}'. Use 'keychain' or 'file'. For cross-machine file sync, pass --synced.`));
-    process.exit(1);
-}
-function resolveBackendOpt(raw) {
-    return parseBackendOpt(raw, raw === undefined ? secretsDefaultBackend() : 'keychain');
-}
-/** Human-readable "locks in 3 hours" / "locks in 5 minutes" from an epoch-ms expiry. */
-function humanRemaining(expiresAt) {
-    const ms = expiresAt - Date.now();
-    if (ms <= 0)
-        return 'expired';
-    const mins = Math.round(ms / 60000);
-    if (mins < 60)
-        return `locks in ${mins} minute${mins === 1 ? '' : 's'}`;
-    const hours = Math.round(mins / 60);
-    if (hours < 24)
-        return `locks in ${hours} hour${hours === 1 ? '' : 's'}`;
-    const days = Math.round(hours / 24);
-    return `locks in ${days} day${days === 1 ? '' : 's'}`;
-}
-// `quoteWin32ExecArg` now lives in lib/platform/exec.ts (shared with the agent
-// run/shim spawn paths); re-exported here for the colocated secrets tests.
-export { quoteWin32ExecArg };
-/**
- * Copy text to the system clipboard, cross-platform.
- * macOS: `pbcopy`. Windows: `clip`. Linux: tries `wl-copy` (Wayland), then
- * `xclip`, then `xsel` (X11). Throws with an install hint if none are present.
- */
-async function copyToClipboard(text) {
-    const { spawn } = await import('child_process');
-    const candidates = process.platform === 'darwin'
-        ? [['pbcopy', []]]
-        : process.platform === 'win32'
-            ? [['clip', []]]
-            : [
-                ['wl-copy', []],
-                ['xclip', ['-selection', 'clipboard']],
-                ['xsel', ['--clipboard', '--input']],
-            ];
-    let lastErr = null;
-    for (const [cmd, args] of candidates) {
-        try {
-            await new Promise((resolve, reject) => {
-                const proc = spawn(cmd, args, { stdio: ['pipe', 'ignore', 'ignore'] });
-                proc.on('error', reject);
-                proc.on('close', (code) => (code === 0 ? resolve() : reject(new Error(`${cmd} exited ${code}`))));
-                proc.stdin.write(text);
-                proc.stdin.end();
-            });
-            return;
-        }
-        catch (err) {
-            lastErr = err;
-        }
-    }
-    const hint = process.platform === 'linux'
-        ? ' Install one: wl-clipboard (Wayland) or xclip / xsel (X11).'
-        : '';
-    throw new Error(`no clipboard tool available (${lastErr?.message ?? 'none found'}).${hint}`);
-}