@phnx-labs/agents-cli 1.22.39 → 1.22.40

package/dist/commands/{login.js → secrets-vault.js}

@@ -1,7 +1,15 @@
+/**
+ * `agents secrets vault` — unlock/lock the age-encrypted synced-secrets file
+ * at ~/.agents/vault.age (distinct from `agents secrets unlock|lock`, which
+ * holds keychain bundles in the secrets-agent).
+ *
+ * Formerly top-level `agents login` / `agents logout`.
+ */
 import chalk from 'chalk';
 import * as fs from 'fs';
 import { readStdinSync } from '../lib/format.js';
 import { clearVaultKey, createVault, getVaultSession, joinVault, unlock, vaultExists, vaultPath, } from '../lib/secrets/vault.js';
+import { setHelpSections } from '../lib/help.js';
 import { isInteractiveTerminal, isPromptCancelled } from './utils.js';
 async function promptPassword(message) {
     if (!isInteractiveTerminal()) {
@@ -19,7 +27,7 @@ async function readPassword(opts, message) {
     }
     return promptPassword(message);
 }
-async function chooseFreshLoginMode(opts) {
+async function chooseFreshMode(opts) {
     if (opts.create && opts.join)
         throw new Error('--create and --join are mutually exclusive.');
     if (opts.create)
@@ -31,10 +39,10 @@ async function chooseFreshLoginMode(opts) {
     }
     const { select } = await import('@inquirer/prompts');
     return select({
-        message: 'No synced secrets login found. What do you want to do?',
+        message: 'No synced secrets vault found. What do you want to do?',
         choices: [
-            { name: 'Create a new login', value: 'create' },
-            { name: 'Join with an existing synced secrets file', value: 'join' },
+            { name: 'Create a new vault', value: 'create' },
+            { name: 'Join with an existing vault.age file', value: 'join' },
         ],
     });
 }
@@ -51,9 +59,21 @@ function formatRemaining(expiresAt) {
     const days = Math.round(hours / 24);
     return `${days} day${days === 1 ? '' : 's'}`;
 }
-export function registerLoginCommands(program) {
-    program
-        .command('login')
+/** Register `agents secrets vault unlock|lock` under the secrets parent. */
+export function registerSecretsVaultCommands(secretsCmd) {
+    const vault = secretsCmd
+        .command('vault')
+        .description('Unlock or lock the age-encrypted synced-secrets file (~/.agents/vault.age)');
+    setHelpSections(vault, {
+        examples: `agents secrets vault unlock
+agents secrets vault unlock --create
+agents secrets vault unlock --join ~/Downloads/vault.age
+agents secrets vault lock`,
+        notes: `This is the synced vault passphrase cache — not \`agents secrets unlock\`, which holds keychain bundles in the secrets-agent after Touch ID.
+Harness OAuth sign-out is \`agents accounts logout\` (OAuth native logins only).`,
+    });
+    vault
+        .command('unlock')
         .description('Unlock synced secrets for this shell session')
         .option('--create', 'Create a new encrypted synced-secrets file at ~/.agents/vault.age')
         .option('--join <path>', 'Copy and unlock an existing vault.age file')
@@ -69,10 +89,10 @@ export function registerLoginCommands(program) {
                 unlock(password);
                 const session = getVaultSession();
                 const ttl = session.loggedIn ? formatRemaining(session.expiresAt) : '8 hours';
-                console.log(chalk.green(`Logged in. Synced secrets unlocked for ${ttl}.`));
+                console.log(chalk.green(`Unlocked. Synced secrets available for ${ttl}.`));
                 return;
             }
-            const mode = await chooseFreshLoginMode(opts);
+            const mode = await chooseFreshMode(opts);
             if (mode === 'join') {
                 let source = opts.join;
                 if (!source) {
@@ -86,12 +106,12 @@ export function registerLoginCommands(program) {
                 }
                 const password = await readPassword(opts, 'Master password');
                 joinVault(password, source, { overwrite: opts.force });
-                console.log(chalk.green(`Logged in. Copied synced secrets file to ${vaultPath()}.`));
+                console.log(chalk.green(`Unlocked. Copied synced secrets file to ${vaultPath()}.`));
                 return;
             }
             const password = await readPassword(opts, 'Choose a master password');
             createVault(password, { overwrite: opts.force });
-            console.log(chalk.green(`Logged in. Created synced secrets file at ${vaultPath()}.`));
+            console.log(chalk.green(`Unlocked. Created synced secrets file at ${vaultPath()}.`));
         }
         catch (err) {
             if (isPromptCancelled(err))
@@ -100,11 +120,11 @@ export function registerLoginCommands(program) {
             process.exit(1);
         }
     });
-    program
-        .command('logout')
+    vault
+        .command('lock')
         .description('Forget the cached synced-secrets key')
         .action(() => {
         clearVaultKey();
-        console.log(chalk.green('Logged out. Synced secrets are locked.'));
+        console.log(chalk.green('Locked. Synced secrets require unlock again.'));
     });
 }

package/dist/commands/secrets.d.ts

@@ -17,7 +17,7 @@ import { type BundleUsageSummary } from '../lib/secrets/usage-db.js';
 /** 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 --host` pipes the resolved dotenv over
+ * 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.
  */
@@ -45,7 +45,7 @@ export declare function parseImportSource(opts: {
     vault?: string;
 }): ImportSource;
 /**
- * Build the remote `agents secrets unlock` argv for `unlock --host`. `--all`
+ * 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
@@ -78,10 +78,10 @@ export declare function buildRemoteUnlockArgs(names: string[], opts: {
     durable?: boolean;
 }): string[];
 /**
- * Build the remote `agents secrets list` argv for `list --host`. Every filter
+ * 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 --host zion --expired` reports every bundle on zion as expired.
+ * `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,

package/dist/commands/secrets.js

@@ -14,7 +14,7 @@ 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.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 };
@@ -30,7 +30,7 @@ import { saveSession, deleteBundleSessions, deleteAllSessions } from '../lib/sec
 import { getCliVersionFresh } from '../lib/version.js';
 import { readMeta } from '../lib/state.js';
 import { parseDuration } from '../lib/hooks/cache.js';
-import { emit, query } from '../lib/events.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';
@@ -43,6 +43,7 @@ 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()) {
@@ -144,7 +145,7 @@ async function resolveVault(vaultOpt) {
 /** 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 --host` pipes the resolved dotenv over
+ * 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.
  */
@@ -262,7 +263,7 @@ function maybePrintSyncedHint(name, stillPresent) {
     }
 }
 /**
- * Build the remote `agents secrets unlock` argv for `unlock --host`. `--all`
+ * 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
@@ -323,10 +324,10 @@ export function buildRemoteUnlockArgs(names, opts) {
     ];
 }
 /**
- * Build the remote `agents secrets list` argv for `list --host`. Every filter
+ * 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 --host zion --expired` reports every bundle on zion as expired.
+ * `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,
@@ -927,7 +928,7 @@ export function registerSecretsCommands(program) {
       eval "$(agents secrets export prod --plaintext)"
 
       # Push the bundle to remote machine(s) over SSH (lands as a native bundle there)
-      agents secrets export prod --host yosemite-s0 --host yosemite-s1 --force
+      agents secrets export prod --device yosemite-s0 --device yosemite-s1 --force
 
       # Run a one-off command with secrets injected
       agents secrets exec prod -- ./deploy.sh
@@ -983,15 +984,15 @@ export function registerSecretsCommands(program) {
         { 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 --host/--hosts for other machines over SSH)')
-        .option('--host <target>', 'List bundles on a remote host over SSH (enrolled `agents hosts` name, ssh-config alias, or user@host)')
-        .option('--hosts <list>', 'Comma-separated hosts to list in one shot, e.g. yosemite-s0,yosemite-s1')
-        .option('--device <target>', 'Alias for --host')
-        .option('--devices <list>', 'Alias for --hosts')
+        .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')
@@ -1005,7 +1006,7 @@ export function registerSecretsCommands(program) {
         .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(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.
@@ -1028,7 +1029,7 @@ export function registerSecretsCommands(program) {
             // 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 --host <mac>.');
+                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) {
@@ -1160,16 +1161,16 @@ export function registerSecretsCommands(program) {
       agents secrets list --policy hold --backend file --expiring
 
       # Same filters, on another machine, machine-readable
-      agents secrets list --expired --host mac-mini --json
+      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 --host <mac> from elsewhere.
+      - --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 --host, so a remote list narrows the same way.
+      - 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'.
     `,
     });
@@ -1224,13 +1225,11 @@ export function registerSecretsCommands(program) {
         .option('--reveal', 'Print keychain-backed values in the clear (TTY only unless --plaintext)')
         .option('--plaintext', 'Allow --reveal in non-interactive shells (use with care)')
         .option('--json', 'Emit machine-readable JSON (values masked unless --reveal) instead of the human view')
-        .option('--host <target>', 'Show a bundle on a remote host over SSH (enrolled `agents hosts` name, ssh-config alias, or user@host)')
-        .option('--hosts <list>', 'Comma-separated hosts to show in one shot, e.g. yosemite-s0,yosemite-s1')
-        .option('--device <target>', 'Alias for --host')
-        .option('--devices <list>', 'Alias for --hosts')
+        .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 {
-            const targets = parseHostsOption(opts);
+            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).'));
@@ -1382,7 +1381,7 @@ export function registerSecretsCommands(program) {
             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 login)'));
+                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.'));
             }
@@ -2019,12 +2018,28 @@ Examples:
         .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 --host)')
-        .option('--host <peer>', 'SSH peer to pull from when using --from-ssh (host alias or user@host)')
+        .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).
@@ -2043,24 +2058,24 @@ Examples:
                 }
                 const env = importBundleFromFile(opts.fromFile, passphrase);
                 const resolvedBundleName = bundleName ?? (await pickBundleName('import into'));
-                const bundle = resolveImportBundle(resolvedBundleName, opts.backend, opts.synced, opts.force);
+                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.host) {
-                    throw new Error('--from-ssh requires --host <peer>.');
+                if (!opts.device) {
+                    throw new Error('--from-ssh requires --device <peer>.');
                 }
-                assertValidSshTarget(opts.host);
+                assertValidSshTarget(opts.device);
                 const resolvedBundleName = bundleName ?? (await pickBundleName('import into'));
-                const target = await resolveHostSshTarget(opts.host);
-                const env = await remoteResolveEnv(target, resolvedBundleName, { osLookupName: opts.host });
-                const bundle = resolveImportBundle(resolvedBundleName, opts.backend, opts.synced, opts.force);
+                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.host, status: 'success', keyCount: added });
-                console.log(chalk.green(`Imported ${added} key(s) from ${opts.host}${skipped ? `, skipped ${skipped} (already set, pass --force)` : ''}.`));
+                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);
@@ -2083,9 +2098,9 @@ Examples:
             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 --host ...
+            // so a single `import --backend file` works (what `export --device ...
             // --remote-backend file` drives on the remote).
-            const bundle = resolveImportBundle(resolvedBundleName, opts.backend, opts.synced, opts.force);
+            const bundle = applyImportPolicy(resolveImportBundle(resolvedBundleName, opts.backend, opts.synced, opts.force));
             if (source.kind === '1password') {
                 assertOpAvailable();
                 const vault = await resolveVault(source.vault);
@@ -2118,23 +2133,17 @@ Examples:
     });
     cmd
         .command('export [bundle]')
-        .description('Resolve a bundle and print KEY=VALUE lines, push it to a 1Password vault with --to-1password, or push it to remote machine(s) over SSH with --host.')
+        .description('Resolve a bundle and print KEY=VALUE lines, push it to a 1Password vault with --to-1password, or push it to remote machine(s) over SSH with --device.')
         .option('--plaintext', 'Acknowledge that the resolved values will be printed in the clear (shell export mode)')
         .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('--host <target...>', 'Push the bundle over SSH to this target (host alias or user@host); repeatable for multiple machines')
-        .option('--device <target...>', 'Alias for --host; repeatable')
-        .option('--remote-backend <backend>', 'Backend for the bundle on the remote (with --host): keychain (default) or file. file is headless-readable via the remote\'s machine-local key; it forwards AGENTS_SECRETS_PASSPHRASE over stdin only if set (opt-in).', 'keychain')
-        .option('--force', 'Overwrite existing keys/items on the target (used with --to-1password and --host)')
+        .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; it forwards AGENTS_SECRETS_PASSPHRASE over stdin only if set (opt-in).', 'keychain')
+        .option('--force', 'Overwrite existing keys/items on the target (used with --to-1password and --device)')
         .option('--format <shell|json>', 'Output for --plaintext export: shell (default) or json (lossless, machine-readable; used by remote resolve)', 'shell')
         .option('--to-file <path>', `Write the bundle as an AES-256-GCM encrypted offline file (needs ${SYNC_PASSPHRASE_ENV}; symmetric counterpart of import --from-file)`)
         .action(async (bundleName, opts) => {
         try {
-            // `--device` is an alias for `--host` (fleet vocabulary parity with
-            // `agents run --device`); fold it into the host list up front so
-            // every downstream branch sees one resolved target list.
-            if (opts.device?.length)
-                opts.host = [...(opts.host ?? []), ...opts.device];
             const { readAndResolveBundleEnv, bundleToEnvPrefix, isReservedEnvName } = await import('../lib/secrets/bundles.js');
             const resolvedBundleName = bundleName ?? (await pickBundleName('export'));
             if (opts.toFile) {
@@ -2150,10 +2159,10 @@ Examples:
                 console.log(chalk.green(`Exported ${Object.keys(env).length} key(s) to ${opts.toFile}`));
                 return;
             }
-            // The presence of --host selects SSH push: --host is the destination
+            // 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 host).
-            const hosts = opts.host ?? [];
+            // 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);
@@ -2203,7 +2212,7 @@ Examples:
                     }
                     console.log(chalk.green(`${host} -> '${resolvedBundleName}': ${out.message}`));
                 }
-                emitSecretAudit({ event: 'secrets.export', bundle: resolvedBundleName, operation: `export --host ${hosts.join(',')}`, source: 'ssh', host: hosts.join(','), status: failures > 0 ? 'error' : 'success', keyCount });
+                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;
@@ -2287,8 +2296,8 @@ Examples:
     });
     cmd
         .command('exec <bundle> [command...]')
-        .description('Run a command with the bundle\'s secrets injected into the environment (use --host to resolve the bundle from a remote machine, ephemerally)')
-        .option('--host <target>', 'Resolve <bundle> on a remote host over SSH and inject it (ephemeral — never stored on this machine)')
+        .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()
@@ -2303,14 +2312,14 @@ Examples:
                 ? execOpts.keys.split(',').map((k) => k.trim()).filter(Boolean)
                 : undefined;
             let secretEnv;
-            if (execOpts.host) {
+            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.host, { keys: keysSubset, allowExpired: execOpts.allowExpired }, { keysFlag: '--keys', allowExpiredFlag: '--allow-expired' });
-                secretEnv = await remoteResolveEnv(await resolveHostSshTarget(execOpts.host), bundleName, { osLookupName: execOpts.host });
+                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');
@@ -2497,14 +2506,14 @@ Examples:
     });
     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 --host, 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.')
+        .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('--host <target>', 'Unlock the bundle(s) on this remote machine 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> --host <machine>`.')
+        .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.'));
@@ -2512,10 +2521,10 @@ Examples:
         }
         if (opts.keys !== undefined) {
             // --keys scopes ONE bundle to an explicit subset. It is local-only (a
-            // remote --host unlock holds the whole file-backed bundle) and cannot
+            // remote --device unlock holds the whole file-backed bundle) and cannot
             // combine with --all, which would hold every bundle whole.
-            if (opts.host) {
-                console.error(chalk.red('--keys is local-only; a remote (--host) unlock holds the whole file-backed bundle.'));
+            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) {
@@ -2523,10 +2532,10 @@ Examples:
                 process.exit(1);
             }
         }
-        // Single-valued (not variadic): a variadic --host greedily consumes the
-        // positional bundle name (`unlock --host mac wztest` -> host=[mac,wztest],
+        // 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.host ? [opts.host] : [];
+        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

package/dist/commands/sessions-backfill.js

@@ -204,7 +204,7 @@ export function registerSessionsBackfillCommand(sessionsCmd) {
     tools.action(async (_options, command) => {
         const options = command.optsWithGlobals();
         if (options.local && (options.fleet || mergeHosts(options).length > 0)) {
-            console.error(chalk.red('--local cannot be combined with --fleet, --host, or --device.'));
+            console.error(chalk.red('--local cannot be combined with --fleet or --device.'));
             process.exitCode = 1;
             return;
         }

package/dist/commands/sessions-browser.d.ts

@@ -81,7 +81,7 @@ export declare function sessionMatchesQuery(s: SessionMeta, query: string): bool
  * `--print-cmd`.
  */
 export declare function browserFilterToArgv(f: BrowserFilter, query?: string): string[];
-/** Normalize a `--host`/`--device` token (`alias`, `user@host`, `host.domain`) to
+/** Normalize a `--device`/`--device` token (`alias`, `user@host`, `host.domain`) to
  * the canonical machine id the rows carry in `.machine`, so a flag seed matches
  * (the `d` hotkey already cycles canonical ids). Mirrors sessions.ts `hostToken`. */
 export declare function normalizeDeviceSeed(host: string | undefined): string | undefined;

package/dist/commands/sessions-browser.js

@@ -16,12 +16,12 @@ import { dynamicPicker } from '../lib/picker.js';
 import { isSessionTrackedAgent } from '../lib/session/types.js';
 import { discoverSessions } from '../lib/session/discover.js';
 import { gatherRemoteList } from '../lib/session/remote-list.js';
-import { resolveVersionAliasLoose } from '../lib/versions.js';
+import { resolveVersionAliasLoose } from '../lib/installations/versions.js';
 import { AGENTS } from '../lib/agents.js';
 import { enrichTeamOrigins, safeTeamText, shouldShowTeamSessions } from '../lib/session/team-filter.js';
 import { listBookmarks, toggleBookmark } from '../lib/session/bookmarks.js';
 import { machineId, normalizeHost } from '../lib/session/sync/config.js';
-import { buildPreview } from './sessions-picker.js';
+import { buildPreview, setRemotePreviewRepaint } from './sessions-picker.js';
 import { formatPickerLabel, pickerColumnsFor, ticketLabel, mergeLocalFirst, gatherActiveSessions, liveHostLabel, LIVE_ROW_PREFIX, cleanPreview, handlePickedSession, shouldIncludeLocal, remoteHostsToDial, matchesTeam, formatLiveStatusHeadline, isRunningLiveSession, matchesLiveStatus, parseAgentFilter, resolveRoutineName, } from './sessions.js';
 /**
  * Complete a seed into the filter the picker actually runs on.
@@ -164,7 +164,7 @@ export function browserFilterToArgv(f, query = '') {
         a.push(JSON.stringify(q));
     return a;
 }
-/** Normalize a `--host`/`--device` token (`alias`, `user@host`, `host.domain`) to
+/** Normalize a `--device`/`--device` token (`alias`, `user@host`, `host.domain`) to
  * the canonical machine id the rows carry in `.machine`, so a flag seed matches
  * (the `d` hotkey already cycles canonical ids). Mirrors sessions.ts `hostToken`. */
 export function normalizeDeviceSeed(host) {
@@ -253,7 +253,7 @@ function copyToClipboard(text) {
  * The live index is fetched separately/lazily — it's the slow part and only the
  * running filter needs it, so a bare browse stays instant.
  *
- * `hosts` is the explicit `--host`/`--device` scope (if any): it restricts which
+ * `hosts` is the explicit `--device`/`--device` scope (if any): it restricts which
  * peers are dialed and whether local is included, honoring the flag's "scope,
  * not add" contract instead of always sweeping the whole fleet. */
 async function fetchRawPool(f, self, local, hosts, fixedFilters = false) {
@@ -699,6 +699,9 @@ export async function runSessionBrowser(initial = {}, opts = {}) {
             const body = buildPreview(s);
             return headline ? `${headline}\n${body}` : body;
         },
+        // A remote row's digest arrives over SSH after the pane painted — this is
+        // what lets its completion swap the metadata card for the full preview.
+        registerPreviewRepaint: setRemotePreviewRepaint,
         headerFor: (f) => unreachable.length > 0
             ? `${headerFor(f)} · ${chalk.yellow(`${unreachable.join(', ')}: unreachable`)}`
             : headerFor(f),
@@ -741,7 +744,8 @@ export async function runSessionBrowser(initial = {}, opts = {}) {
             }
             return undefined;
         },
-    });
+        // A late digest fetch must not poke a closed prompt.
+    }).finally(() => setRemotePreviewRepaint(undefined));
     if (!picked)
         return;
     if (picked.action === 'focus') {

package/dist/commands/sessions-export.js

@@ -196,7 +196,7 @@ export function r2ExportGateError(g, isConfigured) {
     if (!g.toR2)
         return null;
     if (g.host && g.host.length > 0) {
-        return "--to-r2 backs up THIS machine's sessions; it cannot be combined with --host.";
+        return "--to-r2 backs up THIS machine's sessions; it cannot be combined with --device.";
     }
     if (!isConfigured) {
         return ('R2 backup is not configured: the r2.backups secrets bundle is missing or locked.\n' +
@@ -266,7 +266,7 @@ export function resolveR2BackupKey() {
  */
 async function runRemoteExport(g, selectors, command) {
     if (g.encrypt) {
-        process.stderr.write(chalk.yellow('Note: --encrypt is ignored with --host (the SSH stream is already encrypted). Encrypt a local bundle instead.\n'));
+        process.stderr.write(chalk.yellow('Note: --encrypt is ignored with --device (the SSH stream is already encrypted). Encrypt a local bundle instead.\n'));
     }
     const { bundles, errors } = await pullBundlesFromHosts(g.host, forwardExportArgs(g, selectors, command));
     for (const e of errors)

package/dist/commands/sessions-inject.js

@@ -14,8 +14,7 @@
  */
 import chalk from 'chalk';
 import { getActiveSessions } from '../lib/session/active.js';
-import { resolveInjectTargetForSession } from '../lib/terminal/resolve.js';
-import { injectIntoTerminal } from '../lib/terminal/index.js';
+import { injectIntoTerminal, resolveInjectTargetForSession } from '../lib/terminal/index.js';
 import { setHelpSections } from '../lib/help.js';
 /** Resolve a session id (short or full) to an addressable terminal target, via the
  * same resolver the watchdog uses so both agree on what is reachable. */
@@ -56,7 +55,7 @@ async function runInject(sessionId, text, options) {
         enter: options.enter !== false,
         combined: options.combined,
         socket: options.socket,
-        host: options.host,
+        host: options.device,
     });
     if (options.json) {
         console.log(JSON.stringify(res));
@@ -78,7 +77,7 @@ export function registerSessionsInjectCommand(sessionsCmd) {
         .option('--pane <id>', 'Target a tmux pane id directly (e.g. %3), skipping session lookup')
         .option('--pty <id>', 'Target an agents-pty session id directly, skipping session lookup')
         .option('--socket <path>', 'tmux socket path (defaults to the session/shared socket)')
-        .option('--host <target>', 'Deliver on a remote host over SSH (tmux/AppleScript backends)')
+        .option('--device <target>', 'Deliver on a remote device over SSH (tmux/AppleScript backends)')
         .option('--no-enter', 'Send only the text, without a trailing Enter')
         .option('--combined', 'Fuse text + Enter into ONE write (default: two writes, Ink-TUI safe)')
         .option('--json', 'Output the InjectResult as JSON');
@@ -99,7 +98,7 @@ export function registerSessionsInjectCommand(sessionsCmd) {
       - A session is addressable by id when it resolves to a precise split —
         tmux, iTerm, a VSCodium/Cursor/VS Code integrated terminal, or a pty
         (resolveInjectTargetForSession). Use --pane/--pty for direct targeting.
-      - Built on the Terminal Engine (src/lib/terminal): --host runs the tmux /
+      - Built on the Terminal Engine (src/lib/terminal): --device runs the tmux /
         AppleScript spec over the same SSH transport the launch engine uses.
     `,
     });