@phnx-labs/agents-cli 1.22.22 → 1.22.24

package/dist/commands/secrets-sync.js

@@ -10,9 +10,10 @@ import chalk from 'chalk';
 import { listRemoteBundles, MIN_PASSPHRASE_LEN, pullBundle, pushBundle, } from '../lib/secrets/sync.js';
 import { bundleExists, listBundles } from '../lib/secrets/bundles.js';
 import { isInteractiveTerminal, isPromptCancelled } from './utils.js';
+import { missingSyncPassphraseMessage, resolveSyncPassphraseFromEnv, warnEnvPassphraseReadableOnce, } from '../lib/secrets/sync-passphrase.js';
 async function promptPassphrase(message, confirm = false) {
     if (!isInteractiveTerminal()) {
-        throw new Error('A sync passphrase is required. Run from a TTY, or set AGENTS_SECRETS_PASSPHRASE.');
+        throw new Error(missingSyncPassphraseMessage());
     }
     const { password } = await import('@inquirer/prompts');
     const first = await password({ message, mask: true });
@@ -25,21 +26,18 @@ async function promptPassphrase(message, confirm = false) {
         throw new Error('Passphrases do not match.');
     return first;
 }
-// Print the env-var-source warning at most once per process so a `--all` push
-// over many bundles doesn't flood stderr with the same notice.
-let envPassphraseWarned = false;
 function passphraseFromEnvOrPrompt(confirm) {
-    const fromEnv = process.env.AGENTS_SECRETS_PASSPHRASE;
-    if (fromEnv) {
-        if (fromEnv.length < MIN_PASSPHRASE_LEN) {
+    // Env resolution (current name, then the deprecated master-key name) lives in
+    // lib/secrets/sync-passphrase.ts so this command and `agents sync` share one
+    // chokepoint — otherwise each call site warns separately and the "once per
+    // process" promise is a lie.
+    const { value } = resolveSyncPassphraseFromEnv();
+    if (value) {
+        if (value.length < MIN_PASSPHRASE_LEN) {
             return Promise.reject(new Error(`Passphrase must be at least ${MIN_PASSPHRASE_LEN} characters.`));
         }
-        if (!envPassphraseWarned) {
-            envPassphraseWarned = true;
-            process.stderr.write(chalk.yellow('warn: using AGENTS_SECRETS_PASSPHRASE. Env vars are readable by other same-user processes ' +
-                '(/proc, ps, crash dumps, CI logs) — rotate the passphrase after CI use.\n'));
-        }
-        return Promise.resolve(fromEnv);
+        warnEnvPassphraseReadableOnce();
+        return Promise.resolve(value);
     }
     return promptPassphrase('Sync passphrase', confirm);
 }

package/dist/commands/secrets.d.ts

@@ -48,9 +48,11 @@ export declare function parseImportSource(opts: {
  * defaults). Shared with the command action so the wiring is unit-testable
  * without a live SSH session.
  */
+export declare function resolveUnlockTtlMs(ttl: string | undefined, until: string | undefined, now?: number): number;
 export declare function buildRemoteUnlockArgs(names: string[], opts: {
     all?: boolean;
     ttl?: string;
+    until?: string;
     durable?: boolean;
 }): string[];
 /**

package/dist/commands/secrets.js

@@ -15,7 +15,7 @@ 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, resolveHostSshTarget, verifyRemoteKeychainPush, keychainWriteFailureMessage, } from '../lib/secrets/remote.js';
+import { parseHostsOption, remoteResolveEnv, remoteSecretsRaw, remoteSecretsStream, resolveHostSshTarget, verifyRemoteKeychainPush, keychainWriteFailureMessage, buildRemoteFileImportCommand, } from '../lib/secrets/remote.js';
 import { remoteShellFor, buildWindowsStdinImportCommand } from '../lib/hosts/remote-cmd.js';
 import { resolveRemoteOsSync } from '../lib/hosts/remote-os.js';
 import { bundleBackend, bundleExists, bundleItemStore, bundlePolicy, deleteBundle, describeBundle, keychainItemsForBundle, keychainRef, listBundles, healKeychainBundleMetadataAclOnce, isHeadlessSecretsContext, migrateLegacyBundles, parseDotenv, readAndResolveBundleEnv, readBundle, readBundleIfDecryptable, reAclBundleItems, renameBundle, rotateBundleSecret, sanitizeProcessEnv, validateBundleName, validateEnvKey, validateExpiresFutureDated, validateSecretType, writeBundle, writeBundleWithItems, SECRET_TYPES, } from '../lib/secrets/bundles.js';
@@ -31,6 +31,7 @@ import { readMeta } from '../lib/state.js';
 import { parseDuration } from '../lib/hooks/cache.js';
 import { emit, query } from '../lib/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';
@@ -266,11 +267,31 @@ function maybePrintSyncedHint(name, stillPresent) {
  * 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();
+}
 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'] : []),
@@ -333,10 +354,6 @@ function getCliVersion() {
         return '0.0.0';
     }
 }
-/** POSIX single-quote a string for safe interpolation into a remote shell command. */
-function shellQuote(s) {
-    return `'${s.replace(/'/g, `'\\''`)}'`;
-}
 /**
  * Serialize a resolved env map to `.env` lines that round-trip losslessly through
  * `parseDotenv` on the remote: `KEY="VALUE"`. parseDotenv strips exactly one outer
@@ -1332,7 +1349,7 @@ export function registerSecretsCommands(program) {
             if (bundle.allow_exec)
                 console.log(chalk.yellow('allow_exec: true'));
             if (bundle.backend === 'file')
-                console.log(chalk.gray('backend: file (passphrase-encrypted; reads need AGENTS_SECRETS_PASSPHRASE, no Touch ID)'));
+                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)'));
             if (bundlePolicy(bundle) === 'never') {
@@ -1588,7 +1605,7 @@ export function registerSecretsCommands(program) {
                 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 under AGENTS_SECRETS_PASSPHRASE (no Touch ID).'));
+                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.'));
@@ -1961,7 +1978,7 @@ Examples:
         .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('--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 AGENTS_SECRETS_PASSPHRASE; symmetric counterpart of export --to-file)')
+        .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)')
         .action(async (bundleName, opts) => {
@@ -1977,9 +1994,10 @@ Examples:
                 throw new Error('--from-file, --from-ssh, and --from/--from-1password are mutually exclusive; pick one import source.');
             }
             if (opts.fromFile) {
-                const passphrase = process.env.AGENTS_SECRETS_PASSPHRASE ?? '';
+                // 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 AGENTS_SECRETS_PASSPHRASE set to decrypt the bundle file.');
+                    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'));
@@ -2064,10 +2082,10 @@ Examples:
         .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 (passphrase-encrypted, headless-readable). file forwards AGENTS_SECRETS_PASSPHRASE over stdin.', 'keychain')
+        .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('--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 AGENTS_SECRETS_PASSPHRASE; symmetric counterpart of import --from-file)')
+        .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
@@ -2078,9 +2096,10 @@ Examples:
             const { readAndResolveBundleEnv, bundleToEnvPrefix, isReservedEnvName } = await import('../lib/secrets/bundles.js');
             const resolvedBundleName = bundleName ?? (await pickBundleName('export'));
             if (opts.toFile) {
-                const passphrase = process.env.AGENTS_SECRETS_PASSPHRASE ?? '';
+                // 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 AGENTS_SECRETS_PASSPHRASE set to encrypt the bundle. ' +
+                    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 });
@@ -2097,20 +2116,16 @@ Examples:
                 for (const h of hosts)
                     assertValidSshTarget(h);
                 const remoteBackend = parseBackendOpt(opts.remoteBackend);
-                // For a file-backed remote bundle the remote must encrypt at rest with
-                // a passphrase. We forward the LOCAL AGENTS_SECRETS_PASSPHRASE — the
-                // operator unlocks it once on this (trusted, biometry-gated) machine —
-                // and ship it as the FIRST stdin line so it never lands in argv / `ps`
-                // / the remote shell history. The remote `read -r` consumes that line;
-                // `agents secrets import --from /dev/stdin` reads the .env remainder.
-                let remotePassphrase = '';
-                if (remoteBackend === 'file') {
-                    remotePassphrase = process.env.AGENTS_SECRETS_PASSPHRASE ?? '';
-                    if (!remotePassphrase) {
-                        throw new Error('--remote-backend file needs AGENTS_SECRETS_PASSPHRASE set locally to encrypt the ' +
-                            'bundle at rest on the remote. Set it for this command, then unlock it the same way per run.');
-                    }
-                }
+                // For a file-backed remote bundle a passphrase is OPTIONAL. The file
+                // store is passphrase-free by default: with AGENTS_SECRETS_PASSPHRASE
+                // unset the remote `import --backend file` auto-provisions the remote's
+                // own machine-local key (0600 under ~/.agents/.secrets-key/), so reads
+                // are HEADLESS. We forward the LOCAL AGENTS_SECRETS_PASSPHRASE only when
+                // the operator opts in by setting it (e.g. to key the bundle off-disk
+                // under a shared secret) — shipped as the FIRST stdin line so it never
+                // lands in argv / `ps` / the remote shell history. Forcing a shared
+                // passphrase would defeat headless reads, so we no longer require one.
+                const remotePassphrase = remoteBackend === 'file' ? (process.env.AGENTS_SECRETS_PASSPHRASE ?? '') : '';
                 const { env } = readAndResolveBundleEnv(resolvedBundleName, { caller: `ssh export`, keyMode: 'storage', agentOnly: true });
                 const dotenv = bundleEnvToDotenv(env);
                 const keyCount = Object.keys(env).length;
@@ -2126,19 +2141,22 @@ Examples:
                 for (const host of hosts) {
                     let res;
                     if (remoteBackend === 'file') {
-                        // File backend forwards AGENTS_SECRETS_PASSPHRASE as the FIRST stdin
-                        // line (consumed by `read`, so it never lands in argv / `ps` /
-                        // remote history), then the .env. That `read`/`export` prologue is
-                        // POSIX shell — refuse a Windows target cleanly rather than emit
-                        // broken PowerShell.
+                        // File backend: headless-readable via the remote's machine-local key
+                        // when no passphrase is set; otherwise forwards AGENTS_SECRETS_PASSPHRASE
+                        // as the FIRST stdin line (consumed by `read`, so it never lands in
+                        // argv / `ps` / remote history), then the .env. Both build a POSIX
+                        // `bash -lc` command — refuse a Windows target cleanly rather than
+                        // emit broken PowerShell.
                         if (remoteShellFor(resolveRemoteOsSync(host.split('@').pop() ?? host)) === 'powershell') {
                             failures++;
                             console.error(chalk.red(`${host}: file backend export to a Windows target is not yet supported.`));
                             continue;
                         }
-                        const remoteAgents = `IFS= read -r AGENTS_SECRETS_PASSPHRASE; export AGENTS_SECRETS_PASSPHRASE; ` +
-                            `agents secrets import ${shellQuote(resolvedBundleName)} --from - --backend file${opts.force ? ' --force' : ''}`;
-                        res = sshExec(host, `bash -lc ${shellQuote(remoteAgents)}`, { input: `${remotePassphrase}\n${dotenv}` });
+                        const { remoteCmd, input } = buildRemoteFileImportCommand(resolvedBundleName, dotenv, {
+                            passphrase: remotePassphrase,
+                            force: opts.force,
+                        });
+                        res = sshExec(host, remoteCmd, { input });
                     }
                     else if (remoteShellFor(resolveRemoteOsSync(host.split('@').pop() ?? host)) === 'powershell') {
                         // Keychain on a Windows target: the `agents.ps1` shim doesn't
@@ -2488,11 +2506,16 @@ Examples:
         .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.')
         .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('--for <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('--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) => {
+        if (opts.ttl && opts.until) {
+            console.error(chalk.red('--ttl and --until are mutually exclusive.'));
+            process.exit(1);
+        }
         // Single-valued (not variadic): a variadic --host greedily consumes the
         // positional bundle name (`unlock --host mac wztest` -> host=[mac,wztest],
         // names=[]). Unlock targets one remote at a time anyway.
@@ -2529,6 +2552,15 @@ Examples:
                 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
@@ -2542,15 +2574,15 @@ Examples:
             console.error(chalk.red('Specify one or more bundle names, or --all.'));
             process.exit(1);
         }
-        let ttlMs = secretsHoldMs(); // default hold, capped by secrets.agent.holdMs
-        if (opts.ttl) {
-            const secs = parseDuration(opts.ttl);
-            if (!secs) {
-                console.error(chalk.red(`Invalid --ttl '${opts.ttl}'. Use e.g. 30m, 2h, 8h, 3d.`));
-                process.exit(1);
-            }
-            ttlMs = secs * 1000;
+        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 (!(await ensureAgentRunning())) {
             console.error(chalk.red('Could not start the secrets broker.'));
             process.exit(1);
@@ -2576,7 +2608,7 @@ Examples:
                     noAgent: true,
                     caller: 'unlock secrets',
                     agent: harness,
-                    duration: humanRemaining(Date.now() + ttlMs),
+                    duration: humanRemaining(expiresAt),
                     keyMode: 'storage',
                 });
                 // Migrations are authorized only by this explicit unlock. The bundle
@@ -2592,7 +2624,7 @@ Examples:
                     saveSession(name, {
                         bundle,
                         env,
-                        expiresAt: Date.now() + ttlMs,
+                        expiresAt,
                         sleepPersist: durable,
                         harness,
                     });
@@ -2611,7 +2643,7 @@ Examples:
                         agent: harness,
                         ttlMs,
                     });
-                    console.log(`${chalk.green('unlocked')} ${chalk.cyan(name)} ${chalk.gray(`(${Object.keys(env).length} keys, ${humanRemaining(Date.now() + ttlMs)})`)}`);
+                    console.log(`${chalk.green('unlocked')} ${chalk.cyan(name)} ${chalk.gray(`(${Object.keys(env).length} keys, ${humanRemaining(expiresAt)})`)}`);
                 }
                 else {
                     console.error(chalk.red(`Failed to load '${name}' into the agent.`));

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

@@ -11,6 +11,7 @@
  */
 import { type SessionMeta } from '../lib/session/types.js';
 import type { ActiveSession } from '../lib/session/active.js';
+import { type LiveStatusFilter } from './sessions.js';
 /**
  * The single canonical filter state. Every field has a flag equivalent, so the
  * same view is reachable interactively (hotkeys) or from the command line (flags).
@@ -32,6 +33,23 @@ export interface BrowserFilter {
     projectScope: 'repo' | 'all';
     /** time window (undefined = all time) — the `W` key / `--since`. */
     window?: string;
+    /** individual live states; an OR-union and, like the CLI flags, running-only. */
+    statuses: LiveStatusFilter[];
+    /** named project scope, independent of the repo/all hotkey. */
+    project?: string;
+    /** upper time bound from --until. */
+    until?: string;
+    /** retain only routine-origin sessions. */
+    routine: boolean;
+    /** indexed resource filters shared by the flag and focus surfaces. */
+    skill?: string;
+    plugin?: string;
+    /** discovery cap. */
+    limit: number;
+    /** include unmanaged native-home transcripts. */
+    unmanaged: boolean;
+    /** candidate order shared with --sort. */
+    sort: 'timestamp' | 'cost' | 'duration';
 }
 /**
  * Complete a seed into the filter the picker actually runs on.
@@ -97,6 +115,9 @@ export declare function bareBrowserSeed(opts: {
     inTeam?: string;
     favorites?: boolean;
 }): Partial<BrowserFilter>;
+/** Build the static peer query. Keeping it pure pins the per-device alias
+ * contract: latest/oldest travel unresolved and are resolved by each peer. */
+export declare function remotePoolArgs(f: BrowserFilter, fixedFilters: boolean): string[];
 /**
  * A live session's stable row key: its session id when the agent reported one,
  * else a per-machine handle so an id-less live session (a just-booted harness, a
@@ -135,6 +156,20 @@ export declare function mergeLiveIntoPool(rows: SessionMeta[], live: Map<string,
  * listing that has no live rows to explain it.
  */
 export declare function shouldShowHostColumn(f: BrowserFilter, live: Map<string, ActiveSession> | null, rows: SessionMeta[]): boolean;
+/** Apply the cheap in-memory filters (agent / device / project / running / favorites). */
+export declare function applyFilters(rows: SessionMeta[], live: Map<string, ActiveSession>, f: BrowserFilter, self: string, favorites: Set<string>): SessionMeta[];
+/** One-shot form of the browser's canonical candidate pipeline. Focus uses this
+ * instead of maintaining a second discovery/filter implementation. */
+export declare function collectSessionCandidates(initial: Partial<BrowserFilter>, opts?: {
+    local?: boolean;
+    hosts?: string[];
+    includeLive?: boolean;
+}): Promise<{
+    sessions: SessionMeta[];
+    liveById: Map<string, ActiveSession>;
+    self: string;
+    unreachable: string[];
+}>;
 /**
  * Launch the interactive session browser. `initial` seeds the filter (e.g.
  * `{ running: true }` for `--active`). Resolves after the user resumes a session