@phnx-labs/agents-cli 1.20.74 → 1.20.77

package/dist/commands/secrets.js

@@ -15,19 +15,20 @@ import * as path from 'path';
 import { SSH_TARGET_RE, assertValidSshTarget, sshExec } from '../lib/ssh-exec.js';
 import { quoteWin32ExecArg, composeWin32CommandLine } from '../lib/platform/index.js';
 import { ensureDaemonStarted, isDaemonRunning } from '../lib/daemon.js';
-import { parseHostsOption, remoteResolveEnv, remoteSecretsRaw, remoteSecretsStream, resolveSshTarget, } from '../lib/secrets/remote.js';
+import { parseHostsOption, remoteResolveEnv, remoteSecretsRaw, remoteSecretsStream, resolveHostSshTarget, } from '../lib/secrets/remote.js';
 import { remoteShellFor, buildWindowsStdinImportCommand } from '../lib/hosts/remote-cmd.js';
 import { resolveRemoteOsSync } from '../lib/hosts/remote-os.js';
-import { bundleExists, bundleItemStore, bundlePolicy, deleteBundle, describeBundle, keychainItemsForBundle, keychainRef, listBundles, migrateLegacyBundles, parseDotenv, readAndResolveBundleEnv, isHeadlessSecretsContext, readBundle, renameBundle, rotateBundleSecret, sanitizeProcessEnv, validateBundleName, validateEnvKey, validateExpiresFutureDated, validateSecretType, writeBundle, writeBundleWithItems, } from '../lib/secrets/bundles.js';
+import { bundleBackend, bundleExists, bundleItemStore, bundlePolicy, deleteBundle, describeBundle, keychainItemsForBundle, keychainRef, listBundles, migrateLegacyBundles, parseDotenv, readAndResolveBundleEnv, isHeadlessSecretsContext, readBundle, readBundleIfDecryptable, renameBundle, rotateBundleSecret, sanitizeProcessEnv, validateBundleName, validateEnvKey, validateExpiresFutureDated, validateSecretType, writeBundle, writeBundleWithItems, } from '../lib/secrets/bundles.js';
 import { encryptForFallback, decryptForFallback } from '../lib/secrets/filestore.js';
 import { getKeychainToken, getKeychainTokens, hasKeychainToken, secretsKeychainItem, setKeychainToken, } from '../lib/secrets/index.js';
 import { assertOpAvailable, createPasswordItem, deleteItemByTitle, extractSecrets, itemExistsByTitle, listItems, listVaults, } from '../lib/onepassword.js';
 import { secretsHoldMs, secretsAgentDurable, agentLoad, agentLock, agentPing, agentStatus, ensureAgentRunning, runAgentLoadFromStdin, runSecretsAgent, uninstallSecretsAgentService, } from '../lib/secrets/agent.js';
-import { saveSession, deleteSession, deleteAllSessions } from '../lib/secrets/session-store.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 } from '../lib/events.js';
+import { emit, query } from '../lib/events.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';
@@ -225,17 +226,29 @@ async function importFromICloud(bundleName, opts) {
     }
 }
 /**
- * Printed under a "bundle not found" 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.
+ * 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) {
+function maybePrintSyncedHint(name, stillPresent) {
     if (process.platform !== 'darwin')
         return;
     try {
-        if (discoverSyncedBundles().some((c) => c.name === name)) {
-            console.error(chalk.yellow(`A legacy iCloud Keychain copy of '${name}' exists. Recover it with: agents secrets import ${name} --from icloud`));
-        }
+        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.
@@ -383,12 +396,12 @@ async function browseRemote(targets, args, tty) {
     };
     if (tty) {
         for (const t of targets) {
-            const target = await resolveSshTarget(t);
+            const target = await resolveHostSshTarget(t);
             render(t, remoteSecretsRaw(target, args, { tty: true, osLookupName: t }));
         }
     }
     else {
-        const resolved = await Promise.all(targets.map(async (t) => ({ name: t, target: await resolveSshTarget(t) })));
+        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 }));
         targets.forEach((t, i) => render(t, results[i]));
     }
@@ -871,7 +884,7 @@ export function registerSecretsCommands(program) {
             }
             catch (err) {
                 console.error(chalk.red(err.message));
-                maybePrintSyncedHint(resolvedName);
+                maybePrintSyncedHint(resolvedName, bundleExists(resolvedName));
                 process.exit(1);
             }
             const entries = describeBundle(bundle);
@@ -1084,8 +1097,9 @@ export function registerSecretsCommands(program) {
                 process.exit(1);
             }
             // `secrets get` is the scriptable automation primitive ($(agents secrets
-            // get bundle KEY)); when embedded in a headless routine/CI script it must
-            // not pop an unwatched Touch ID prompt. Interactive use still prompts.
+            // get bundle KEY)); when embedded in a headless routine/CI script — or run
+            // beneath any agent, which inherits AGENTS_RUNTIME — it must not pop an
+            // unwatched Touch ID prompt. Typed in a plain shell it still prompts.
             const { env } = readAndResolveBundleEnv(item, { caller: 'secrets get', keys: [key], keyMode: 'storage', agentOnly: isHeadlessSecretsContext() });
             if (!(key in env)) {
                 console.error(chalk.red(`Key '${key}' not in bundle '${item}'.`));
@@ -1465,16 +1479,27 @@ Examples:
         .action(async (name, opts) => {
         try {
             const resolvedName = name ?? (await pickBundleName('delete'));
-            const bundle = readBundle(resolvedName);
+            // 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);
                 }
-                const keychainCount = describeBundle(bundle).filter((e) => e.kind === 'keychain').length;
-                const suffix = keychainCount && !opts.keepSecrets
-                    ? ` and purge ${keychainCount} keychain item${keychainCount === 1 ? '' : 's'}`
-                    : '';
+                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}?`,
@@ -1485,7 +1510,7 @@ Examples:
                     return;
                 }
             }
-            if (!opts.keepSecrets) {
+            if (bundle && !opts.keepSecrets) {
                 const store = bundleItemStore(bundle.backend);
                 for (const { item } of keychainItemsForBundle(bundle)) {
                     store.delete(item);
@@ -1583,7 +1608,7 @@ Examples:
                 }
                 assertValidSshTarget(opts.host);
                 const resolvedBundleName = bundleName ?? (await pickBundleName('import into'));
-                const target = await resolveSshTarget(opts.host);
+                const target = await resolveHostSshTarget(opts.host);
                 const env = await remoteResolveEnv(target, resolvedBundleName, { osLookupName: opts.host });
                 const bundle = resolveImportBundle(resolvedBundleName, opts.backend, opts.synced);
                 const { added, skipped } = applyEnvToBundle(bundle, env, opts);
@@ -1793,10 +1818,10 @@ Examples:
                 process.exit(1);
             }
             // `agents secrets export --plaintext` is what release/CI scripts eval.
-            // When it runs detached (both stdio non-TTY) or under a headless agent,
-            // resolve broker-only so it can never pop a Touch ID sheet on the
-            // interactive user's screen. An interactive `eval "$(...)"` keeps its
-            // terminal stdin, so it is not headless and still prompts.
+            // When it runs detached (both stdio non-TTY) or beneath ANY agent — which
+            // inherits AGENTS_RUNTIME — resolve broker-only so it can never pop a Touch
+            // ID sheet on the interactive user's screen. An `eval "$(...)"` typed in a
+            // plain shell carries no AGENTS_RUNTIME, so it is not headless and still prompts.
             const { env } = readAndResolveBundleEnv(resolvedBundleName, {
                 caller: `export to shell`,
                 keyMode: 'process',
@@ -1848,7 +1873,7 @@ Examples:
                 // 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 resolveSshTarget(execOpts.host), bundleName, { osLookupName: execOpts.host });
+                secretEnv = await remoteResolveEnv(await resolveHostSshTarget(execOpts.host), bundleName, { osLookupName: execOpts.host });
             }
             else {
                 const { readAndResolveBundleEnv } = await import('../lib/secrets/bundles.js');
@@ -2032,6 +2057,7 @@ Examples:
         .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.')
         .option('--ttl <duration>', 'How long to hold it (e.g. 30m, 8h, 3d). Default 7d.')
         .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('--for <agent>', 'Scope the unlock to one harness type (for example claude, codex, or kimi).')
         .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>`.')
         .action(async (names, opts) => {
@@ -2052,7 +2078,7 @@ Examples:
             const unlockArgs = buildRemoteUnlockArgs(names, opts);
             let failures = 0;
             for (const h of hosts) {
-                const target = await resolveSshTarget(h);
+                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
@@ -2104,12 +2130,19 @@ Examples:
         // (single-instance start lock, #414) and best-effort — never blocks unlock.
         ensureDaemonStarted();
         let loaded = 0;
+        const harness = opts.for || process.env.AGENTS_AGENT_NAME || 'cli';
         for (const name of targets) {
             try {
                 // noAgent: read the real keychain (one Touch ID) rather than the
                 // agent we're about to populate.
-                const { bundle, env } = readAndResolveBundleEnv(name, { noAgent: true, caller: 'unlock', keyMode: 'storage' });
-                if (await agentLoad(name, bundle, env, ttlMs)) {
+                const { bundle, env } = readAndResolveBundleEnv(name, {
+                    noAgent: true,
+                    caller: 'unlock secrets',
+                    agent: harness,
+                    duration: humanRemaining(Date.now() + ttlMs),
+                    keyMode: 'storage',
+                });
+                if (await agentLoad(name, bundle, env, ttlMs, harness)) {
                     loaded++;
                     // Persist a durable session snapshot so the unlock survives a daemon
                     // restart / upgrade (and sleep too, with --durable). session-store.ts.
@@ -2118,6 +2151,7 @@ Examples:
                         env,
                         expiresAt: Date.now() + ttlMs,
                         sleepPersist: opts.durable ?? secretsAgentDurable(),
+                        harness,
                     });
                     console.log(`${chalk.green('unlocked')} ${chalk.cyan(name)} ${chalk.gray(`(${Object.keys(env).length} keys, ${humanRemaining(Date.now() + ttlMs)})`)}`);
                 }
@@ -2147,7 +2181,7 @@ Examples:
             let total = 0;
             for (const name of names) {
                 total += await agentLock(name);
-                deleteSession(name); // also drop the durable snapshot, or a restart re-warms it
+                deleteBundleSessions(name); // drop every harness scope
             }
             console.log(total > 0 ? chalk.green(`Locked ${total} bundle(s).`) : chalk.gray('Nothing to lock.'));
         }
@@ -2193,16 +2227,47 @@ Examples:
         } })();
         console.log(chalk.gray(`hold: ${holdStr}${configured ? ' (secrets.agent.holdMs)' : ' (default)'} — a daily bundle prompts once, then stays silent for this long or until sleep/logout.`));
         const entries = await agentStatus();
+        const held = new Set(entries.map((e) => e.name));
         if (entries.length === 0) {
             console.log(chalk.gray('No bundles held. The next read of each daily bundle will prompt once, then hold.'));
             console.log(chalk.gray('Pre-warm now with: agents secrets unlock <bundle>  (or --all)'));
-            return;
         }
-        console.log(chalk.bold(`${'BUNDLE'.padEnd(24)} ${'KEYS'.padEnd(5)} LOCKS IN`));
-        for (const e of entries) {
-            console.log(`${chalk.cyan(e.name.padEnd(24))} ${String(e.keyCount).padEnd(5)} ${humanRemaining(e.expiresAt)}`);
+        else {
+            console.log(chalk.bold(`${'BUNDLE'.padEnd(24)} ${'KEYS'.padEnd(5)} LOCKS IN`));
+            for (const e of entries) {
+                console.log(`${chalk.cyan(e.name.padEnd(24))} ${String(e.keyCount).padEnd(5)} ${humanRemaining(e.expiresAt)}`);
+            }
+            console.log(chalk.gray('Reads of held bundles are silent; any bundle not listed prompts once on its next read.'));
+        }
+        // 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`.
         }
-        console.log(chalk.gray('Reads of held bundles are silent; any bundle not listed prompts once on its next read.'));
     });
     cmd
         .command('policy <bundle> [policy]')

package/dist/commands/sessions-browser.js

@@ -197,6 +197,16 @@ function applyFilters(rows, live, f, self) {
         out = out.filter((r) => live.has(r.id));
     return out;
 }
+/** Derive the SSH-launch origin tag for a picker row from the live index. Set
+ * only when the live session's provenance is ssh transport; `device` is the
+ * resolved origin device (absent → the row shows a bare `ssh`). Rows without a
+ * live entry (the running filter off) get no tag — provenance is live-only. */
+function sshOriginTagFor(live, id) {
+    const p = live?.get(id)?.provenance;
+    if (p?.transport !== 'ssh')
+        return undefined;
+    return p.origin?.device ? { device: p.origin.device } : {};
+}
 function headerFor(f) {
     const bits = [
         `device:${f.device ?? 'all'}`,
@@ -214,7 +224,7 @@ function helpFor(_f, mode) {
     if (mode === 'search') {
         return 'type to filter · ↑↓ navigate · esc exit search · ⏎ resume';
     }
-    return 's search · r running · c teams · a agent · d device · p project · w window · y copy-cmd · ⏎ resume · esc quit';
+    return 's search · r running · c teams · a agent · d device · p project · w window · tab preview · y copy-cmd · ⏎ resume · esc quit';
 }
 /**
  * Launch the interactive session browser. `initial` seeds the filter (e.g.
@@ -287,7 +297,7 @@ export async function runSessionBrowser(initial = {}, opts = {}) {
         initialFilter,
         load,
         keyFor: (s) => s.id,
-        labelFor: (s, q) => formatPickerLabel(s, q, cols),
+        labelFor: (s, q) => formatPickerLabel(s, q, cols, sshOriginTagFor(liveCache, s.id)),
         matches: sessionMatchesQuery,
         buildPreview,
         headerFor,

package/dist/commands/sessions-export.js

@@ -20,7 +20,8 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import chalk from 'chalk';
-import { discoverSessions, resolveSessionById } from '../lib/session/discover.js';
+import { discoverSessions, resolveSessionById, isCompleteSessionId } from '../lib/session/discover.js';
+import { findSessionsById } from '../lib/session/db.js';
 import { filterSessionsByQuery, parseAgentFilter } from './sessions.js';
 import { listLocalTranscripts, SYNC_AGENTS } from '../lib/session/sync/agents.js';
 import { machineId } from '../lib/machine-id.js';
@@ -228,16 +229,29 @@ function selectSessions(metas, selectors) {
     const byId = [];
     const unmatched = [];
     for (const sel of selectors) {
-        const hits = resolveSessionById(metas, sel);
-        if (hits.length > 0)
-            byId.push(...hits);
+        const trimmed = sel.trim();
+        // Same reason as resolveSessionQuery: the discovered pool is a minority of
+        // the index, so a complete id absent from it may still be indexed here.
+        const hits = resolveSessionById(metas, trimmed);
+        const resolved = hits.length > 0 || !isCompleteSessionId(trimmed) ? hits : findSessionsById(trimmed);
+        if (resolved.length > 0)
+            byId.push(...resolved);
         else
-            unmatched.push(sel);
+            unmatched.push(trimmed);
     }
     if (byId.length > 0 && unmatched.length === 0) {
         const seen = new Set();
         return byId.filter(s => (seen.has(s.id) ? false : (seen.add(s.id), true)));
     }
+    // A selector that is a COMPLETE session id and still missed cannot be widened:
+    // the id is unique, so the text query below could only bundle sessions that
+    // merely mention it. Bundling those would ship unrelated transcripts to
+    // whoever receives the export, so select nothing and let the caller report it.
+    const missingIds = unmatched.filter(isCompleteSessionId);
+    if (missingIds.length > 0) {
+        process.stderr.write(chalk.red(`No session with id ${missingIds.join(', ')} on this machine.\n`));
+        return [];
+    }
     // Any selector that isn't an id → treat the whole thing as a text query.
     return filterSessionsByQuery(metas, selectors.join(' '));
 }

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

@@ -0,0 +1,29 @@
+import type { Command } from 'commander';
+import type { SessionMeta } from '../lib/session/types.js';
+/** Agents whose sessions cannot be faithfully --resume'd (buildResumeCommand → null). */
+type MigrateMode = 'resume' | 'rehydrate';
+export declare function registerSessionsMigrateCommand(sessionsCmd: Command): void;
+/**
+ * Harness-parity gate (pure, testable). `buildResumeCommand` returns null for the
+ * non-resumable agents (gemini, antigravity, openclaw, rush, hermes, grok, kimi,
+ * droid) — for those a faithful --resume is impossible, so a requested `resume`
+ * transparently becomes `rehydrate`. A resumable agent honors the request.
+ * Returns the effective mode plus whether it was downgraded, so the caller can
+ * print the notice.
+ */
+export declare function effectiveMode(source: SessionMeta, requested: MigrateMode): {
+    mode: MigrateMode;
+    downgraded: boolean;
+};
+/**
+ * Rehydrate command: launch a fresh agent that reads the transcript. For a
+ * non-resumable agent there is no faithful --resume, so we start the agent with
+ * a prompt pointing it at the imported transcript path.
+ */
+export declare function rehydrateCommand(source: SessionMeta): string[];
+/**
+ * `agents sessions migrations` — the border tracker: the append-only ledger of
+ * every session handed off to/from another machine (RUSH-1977).
+ */
+export declare function registerSessionsMigrationsCommand(sessionsCmd: Command): void;
+export {};