@phnx-labs/agents-cli 1.22.29 → 1.22.31

package/dist/commands/secrets.js

@@ -25,8 +25,8 @@ import { getKeychainToken, hasKeychainToken, secretsKeychainItem, setKeychainTok
 import { assertOpAvailable, createPasswordItem, deleteItemByTitle, extractSecrets, itemExistsByTitle, listItems, listVaults, } from '../lib/onepassword.js';
 import { GLOBAL_HARNESS } from '../lib/secrets/scope.js';
 import { createSecretLease, selectLeasedEnv } from '../lib/secrets/lease.js';
-import { secretsHoldMs, secretsAgentDurable, agentLoad, agentLock, agentPing, agentSocketExists, agentStatus, agentRevoke, ensureAgentRunning, runAgentLoadFromStdin, runSecretsAgent, uninstallSecretsAgentService, } from '../lib/secrets/agent.js';
-import { activeLeaseSessions, saveSession, deleteBundleSessions, deleteAllSessions, deleteLeaseSession } from '../lib/secrets/session-store.js';
+import { secretsHoldMs, secretsAgentDurable, agentLoad, agentLock, agentPing, agentStatus, ensureAgentRunning, runAgentLoadFromStdin, runSecretsAgent, uninstallSecretsAgentService, } from '../lib/secrets/agent.js';
+import { saveSession, deleteBundleSessions, deleteAllSessions } from '../lib/secrets/session-store.js';
 import { getCliVersionFresh } from '../lib/version.js';
 import { readMeta } from '../lib/state.js';
 import { parseDuration } from '../lib/hooks/cache.js';
@@ -287,6 +287,30 @@ export function resolveUnlockTtlMs(ttl, until, now = Date.now()) {
     }
     return secretsHoldMs();
 }
+/**
+ * Decide what an `unlock` holds: the whole bundle env, or — with --keys — only
+ * the resolved subset behind a lease that scopes the broker entry (agent.ts
+ * re-selects on load) and its own expiry. Fails closed: createSecretLease throws
+ * on an unknown or empty key subset. The unlock action's single scoping seam,
+ * exported so the whole-bundle vs scoped-subset decision is unit-testable without
+ * a live broker.
+ */
+export function scopeHeldEnv(input) {
+    // null = no --keys → hold the whole bundle. An empty-string --keys is a
+    // deliberate (if empty) scope request and falls through to createSecretLease,
+    // which fails closed ('requires at least one key') rather than holding it all.
+    if (input.keys === null)
+        return { heldEnv: input.env };
+    const lease = createSecretLease({
+        bundle: input.bundle,
+        keys: input.keys.split(','),
+        availableKeys: Object.keys(input.env),
+        ttlMs: input.ttlMs,
+        harness: input.harness,
+        sleepPersist: input.sleepPersist,
+    });
+    return { heldEnv: selectLeasedEnv(lease, input.env), lease };
+}
 export function buildRemoteUnlockArgs(names, opts) {
     return [
         'unlock',
@@ -804,16 +828,31 @@ export function renderExpiringCol(b, now = Date.now()) {
  * new one with the requested backend. Refuses to silently downgrade a
  * keychain-backed bundle to `file` — shared by every `import` source so the
  * guard can't drift between them.
+ *
+ * `force` additionally recreates a bundle whose METADATA RECORD is present but
+ * undecryptable — a file store whose key was lost or rotated out from under it.
+ * That is precisely the state provisioning exists to repair (import is how a box
+ * gets its bundles back), and without this the import dies on `readBundle` and
+ * the only route left is deleting the record by hand on an already-degraded
+ * store. It is gated on `--force` on purpose: recreating unconditionally would
+ * destroy a perfectly healthy bundle for someone who merely forgot to set
+ * `AGENTS_SECRETS_PASSPHRASE`, which is the hazard `readBundleIfDecryptable`
+ * exists to describe. `--force` already means "overwrite what is there".
  */
-function resolveImportBundle(name, backendOpt, synced = false) {
+export function resolveImportBundle(name, backendOpt, synced = false, force = false) {
     const requestedBackend = synced ? 'vault' : resolveBackendOpt(backendOpt);
     if (bundleExists(name)) {
-        const bundle = readBundle(name);
-        if (requestedBackend !== 'keychain' && bundle.backend !== requestedBackend) {
-            throw new Error(`Bundle '${name}' already exists with a different backend; ` +
-                `delete it first to recreate it as ${requestedBackend === 'vault' ? 'synced' : `${requestedBackend}-backed`}.`);
+        // readBundleIfDecryptable nulls ONLY on BundleUndecryptableError; a locked
+        // keychain or logged-out vault still throws, so a recoverable state can
+        // never be mistaken for a lost key and silently overwritten.
+        const bundle = force ? readBundleIfDecryptable(name) : readBundle(name);
+        if (bundle) {
+            if (requestedBackend !== 'keychain' && bundle.backend !== requestedBackend) {
+                throw new Error(`Bundle '${name}' already exists with a different backend; ` +
+                    `delete it first to recreate it as ${requestedBackend === 'vault' ? 'synced' : `${requestedBackend}-backed`}.`);
+            }
+            return bundle;
         }
-        return bundle;
     }
     return { name, backend: requestedBackend === 'keychain' ? undefined : requestedBackend, vars: {} };
 }
@@ -1984,7 +2023,7 @@ Examples:
                 }
                 const env = importBundleFromFile(opts.fromFile, passphrase);
                 const resolvedBundleName = bundleName ?? (await pickBundleName('import into'));
-                const bundle = resolveImportBundle(resolvedBundleName, opts.backend, opts.synced);
+                const bundle = 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)` : ''}.`));
@@ -1998,7 +2037,7 @@ Examples:
                 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);
+                const bundle = 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)` : ''}.`));
@@ -2026,7 +2065,7 @@ Examples:
             // to downgrade keychain -> file) or creates it with the requested backend
             // so a single `import --backend file` works (what `export --host ...
             // --remote-backend file` drives on the remote).
-            const bundle = resolveImportBundle(resolvedBundleName, opts.backend, opts.synced);
+            const bundle = resolveImportBundle(resolvedBundleName, opts.backend, opts.synced, opts.force);
             if (source.kind === '1password') {
                 assertOpAvailable();
                 const vault = await resolveVault(source.vault);
@@ -2427,96 +2466,14 @@ Examples:
             console.log(password);
         }
     });
-    cmd
-        .command('lease <bundle>')
-        .description('Hold only an explicit subset of a bundle until an independent expiry.')
-        .requiredOption('--keys <keys>', 'Comma-separated key subset')
-        .requiredOption('--for <duration>', 'Lease duration, for example 30m or 8h')
-        .option('--agent <agent>', 'Narrow the lease to one harness; default is global')
-        .option('--durable', 'Keep the lease across sleep as well as broker restart')
-        .action(async (name, opts) => {
-        if (process.platform !== 'darwin') {
-            throw new Error('Scoped lease brokering is not available on this platform yet.');
-        }
-        const seconds = parseDuration(opts.for);
-        if (seconds === null)
-            throw new Error(`Invalid lease duration '${opts.for}'.`);
-        const ttlMs = seconds * 1000;
-        const harness = opts.agent || GLOBAL_HARNESS;
-        const { bundle, env } = readAndResolveBundleEnv(name, {
-            noAgent: true,
-            interactiveUnlock: true,
-            caller: 'lease secrets',
-            agent: harness,
-            keyMode: 'storage',
-        });
-        const lease = createSecretLease({
-            bundle: name,
-            keys: opts.keys.split(','),
-            availableKeys: Object.keys(env),
-            ttlMs,
-            harness,
-            sleepPersist: opts.durable,
-        });
-        const leasedEnv = selectLeasedEnv(lease, env);
-        if (!(await ensureAgentRunning()) || !(await agentLoad(name, bundle, leasedEnv, ttlMs, harness, lease))) {
-            throw new Error('Could not load the scoped lease into the secrets broker.');
-        }
-        ensureDaemonStarted();
-        saveSession(name, {
-            bundle,
-            env: leasedEnv,
-            expiresAt: lease.expiresAt,
-            sleepPersist: lease.sleepPersist,
-            harness,
-            lease,
-        });
-        emitSecretAudit({
-            event: 'secrets.unlocked', bundle: name, operation: 'lease', source: lease.sleepPersist ? 'broker+durable' : 'broker',
-            status: 'success', keys: lease.keys, keyCount: lease.keys.length, agent: harness, ttlMs: lease.expiresAt - lease.createdAt,
-        });
-        console.log(`${chalk.green('leased')} ${chalk.cyan(lease.id)} ${chalk.gray(`(${name}: ${lease.keys.join(', ')}, ${humanRemaining(lease.expiresAt)})`)}`);
-    });
-    cmd
-        .command('leases')
-        .description('List active scoped secret leases.')
-        .action(async () => {
-        const brokerLeases = (await agentStatus()).filter((entry) => entry.leaseId);
-        const byId = new Map(brokerLeases.map((entry) => [entry.leaseId, entry]));
-        for (const { name, lease } of activeLeaseSessions()) {
-            if (!byId.has(lease.id))
-                byId.set(lease.id, { name, expiresAt: lease.expiresAt, keyCount: lease.keys.length, harness: lease.harness, leaseId: lease.id, keys: lease.keys });
-        }
-        const leases = [...byId.values()];
-        if (leases.length === 0) {
-            console.log(chalk.gray('No active secret leases.'));
-            return;
-        }
-        console.log(`${'ID'.padEnd(24)} ${'BUNDLE'.padEnd(24)} ${'KEYS'.padEnd(24)} EXPIRES IN`);
-        for (const lease of leases) {
-            console.log(`${lease.leaseId.padEnd(24)} ${lease.name.padEnd(24)} ${(lease.keys ?? []).join(',').padEnd(24)} ${humanRemaining(lease.expiresAt)}`);
-        }
-    });
-    cmd
-        .command('revoke <lease-id>')
-        .description('Revoke one scoped secret lease immediately.')
-        .action(async (leaseId) => {
-        if (agentSocketExists() && !(await agentPing()).reachable) {
-            throw new Error('Cannot revoke while the secrets broker is using an incompatible protocol. Restart the broker and retry.');
-        }
-        const persisted = deleteLeaseSession(leaseId);
-        const wiped = await agentRevoke(leaseId);
-        if (wiped + persisted === 0)
-            throw new Error(`Secret lease '${leaseId}' is not active.`);
-        console.log(chalk.green(`Revoked secret lease ${leaseId}.`));
-    });
     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.')
         .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('--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>`.')
         .action(async (names, opts) => {
@@ -2524,6 +2481,19 @@ Examples:
             console.error(chalk.red('--ttl and --until are mutually exclusive.'));
             process.exit(1);
         }
+        if (opts.keys !== undefined) {
+            // --keys scopes ONE bundle to an explicit subset. It is local-only (a
+            // remote --host 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.'));
+                process.exit(1);
+            }
+            if (opts.all || !names || names.length !== 1) {
+                console.error(chalk.red('--keys scopes ONE bundle to a subset of its keys: name exactly one bundle (not --all).'));
+                process.exit(1);
+            }
+        }
         // Single-valued (not variadic): a variadic --host greedily consumes the
         // positional bundle name (`unlock --host mac wztest` -> host=[mac,wztest],
         // names=[]). Unlock targets one remote at a time anyway.
@@ -2602,12 +2572,13 @@ Examples:
         // (single-instance start lock, #414) and best-effort — never blocks unlock.
         ensureDaemonStarted();
         let loaded = 0;
-        // An unlock is a deliberate act, so it grants GLOBALLY unless `--for`
+        // An unlock is a deliberate act, so it grants GLOBALLY unless `--agent`
         // narrows it to one harness. It must NOT inherit the ambient
         // AGENTS_AGENT_NAME: that silently scoped a terminal unlock to whichever
         // agent happened to launch the shell, leaving the grant unreadable to
         // every other reader for its whole TTL.
-        const harness = opts.for || GLOBAL_HARNESS;
+        const harness = opts.agent || GLOBAL_HARNESS;
+        const durable = opts.durable ?? secretsAgentDurable();
         for (const name of targets) {
             try {
                 // noAgent: read the real keychain (one Touch ID) rather than the
@@ -2624,17 +2595,23 @@ Examples:
                 // ACL heal can rewrite that already-read value without another read.
                 maybeAutoRekey();
                 healKeychainBundleMetadataAclOnce(new Map([[bundle.name, JSON.stringify(bundle)]]));
-                if (await agentLoad(name, bundle, env, ttlMs, harness)) {
+                // With --keys, hold ONLY the resolved subset behind a lease that scopes
+                // the broker entry and its own expiry; without it, the whole bundle is
+                // held exactly as before. scopeHeldEnv fails closed on an unknown key.
+                const { heldEnv, lease } = scopeHeldEnv({ bundle: name, env, keys: opts.keys ?? null, ttlMs, harness, sleepPersist: durable });
+                const heldExpiresAt = lease ? lease.expiresAt : expiresAt;
+                if (await agentLoad(name, bundle, heldEnv, ttlMs, harness, lease)) {
                     loaded++;
                     // Persist a durable session snapshot so the unlock survives a daemon
                     // restart / upgrade (and sleep too, with --durable). session-store.ts.
-                    const durable = opts.durable ?? secretsAgentDurable();
+                    // A scoped hold persists its lease so it rehydrates scoped.
                     saveSession(name, {
                         bundle,
-                        env,
-                        expiresAt,
+                        env: heldEnv,
+                        expiresAt: heldExpiresAt,
                         sleepPersist: durable,
                         harness,
+                        lease,
                     });
                     // Audit the GRANT itself — the broker + durable session now serve this
                     // bundle prompt-free for the whole TTL, to every reader in `harness`
@@ -2646,12 +2623,13 @@ Examples:
                         operation: 'unlock',
                         source: durable ? 'broker+durable' : 'broker',
                         status: 'success',
-                        keyCount: Object.keys(env).length,
-                        keys: Object.keys(env).sort(),
+                        keyCount: Object.keys(heldEnv).length,
+                        keys: Object.keys(heldEnv).sort(),
                         agent: harness,
                         ttlMs,
                     });
-                    console.log(`${chalk.green('unlocked')} ${chalk.cyan(name)} ${chalk.gray(`(${Object.keys(env).length} keys, ${humanRemaining(expiresAt)})`)}`);
+                    const scoped = lease ? chalk.gray(` scoped to ${lease.keys.join(', ')}`) : '';
+                    console.log(`${chalk.green('unlocked')} ${chalk.cyan(name)} ${chalk.gray(`(${Object.keys(heldEnv).length} keys, ${humanRemaining(heldExpiresAt)})`)}${scoped}`);
                 }
                 else {
                     console.error(chalk.red(`Failed to load '${name}' into the agent.`));
@@ -2733,7 +2711,10 @@ Examples:
         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)}`);
+                // A scoped hold (unlock --keys) carries the held key names, so name them
+                // rather than leave the bundle looking whole.
+                const scoped = e.keys?.length ? chalk.gray(`  scoped: ${e.keys.join(', ')}`) : '';
+                console.log(`${chalk.cyan(e.name.padEnd(24))} ${String(e.keyCount).padEnd(5)} ${humanRemaining(e.expiresAt)}${scoped}`);
             }
             console.log(chalk.gray('Reads of held bundles are silent; any bundle not listed prompts once on its next read.'));
         }

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

@@ -0,0 +1,20 @@
+/**
+ * `agents sessions bookmark` — the non-TTY half of the bookmark hotkey.
+ *
+ * The `*` hotkey in the interactive browser is how a human bookmarks a session;
+ * this is how a script, an agent, or a machine without a TTY does the same thing,
+ * and it is what makes the feature testable end to end without driving a terminal
+ * UI. Both write the one store in `lib/session/bookmarks.ts`.
+ */
+import type { Command } from 'commander';
+/**
+ * Resolve one user-typed id (usually the 8-char short id the listing prints) to
+ * a full session id. Ambiguity is an ERROR, not a silent first-match: bookmarking
+ * the wrong session is invisible until the user wonders where their bookmark went.
+ */
+export declare function resolveBookmarkTarget(idQuery: string): {
+    id: string;
+} | {
+    error: string;
+};
+export declare function registerSessionsBookmarkCommand(sessionsCmd: Command): void;

package/dist/commands/{sessions-favorite.js → sessions-bookmark.js}

@@ -1,27 +1,27 @@
 /**
- * `agents sessions favorite` — the non-TTY half of the star.
+ * `agents sessions bookmark` — the non-TTY half of the bookmark hotkey.
  *
- * The `*` hotkey in the interactive browser is how a human stars a session; this
- * is how a script, an agent, or a machine without a TTY does the same thing, and
- * it is what makes the feature testable end to end without driving a terminal UI.
- * Both write the one store in `lib/session/favorites.ts`.
+ * The `*` hotkey in the interactive browser is how a human bookmarks a session;
+ * this is how a script, an agent, or a machine without a TTY does the same thing,
+ * and it is what makes the feature testable end to end without driving a terminal
+ * UI. Both write the one store in `lib/session/bookmarks.ts`.
  */
 import chalk from 'chalk';
 import { setHelpSections } from '../lib/help.js';
 import { findSessionsById } from '../lib/session/db.js';
 import { isCompleteSessionId } from '../lib/session/discover.js';
-import { isFavorite, listFavorites, setFavorite } from '../lib/session/favorites.js';
+import { isBookmarked, listBookmarks, setBookmark } from '../lib/session/bookmarks.js';
 /**
  * Resolve one user-typed id (usually the 8-char short id the listing prints) to
- * a full session id. Ambiguity is an ERROR, not a silent first-match: starring
- * the wrong session is invisible until the user wonders where their star went.
+ * a full session id. Ambiguity is an ERROR, not a silent first-match: bookmarking
+ * the wrong session is invisible until the user wonders where their bookmark went.
  */
-export function resolveFavoriteTarget(idQuery) {
+export function resolveBookmarkTarget(idQuery) {
     const matches = findSessionsById(idQuery);
     // A COMPLETE id needs no index entry: the id is the key the store is built on,
     // and requiring a transcript row would refuse exactly the newest sessions — a
-    // live one that has not been indexed yet. The browser's `*` stars those from
-    // the live row, so demanding a DB hit here would make the two disagree.
+    // live one that has not been indexed yet. The browser's `*` bookmarks those
+    // from the live row, so demanding a DB hit here would make the two disagree.
     if (matches.length === 0) {
         return isCompleteSessionId(idQuery.trim())
             ? { id: idQuery.trim() }
@@ -33,33 +33,33 @@ export function resolveFavoriteTarget(idQuery) {
     }
     return { id: matches[0].id };
 }
-export function registerSessionsFavoriteCommand(sessionsCmd) {
+export function registerSessionsBookmarkCommand(sessionsCmd) {
     const cmd = sessionsCmd
-        .command('favorite')
-        .argument('[ids...]', 'Session ids to star (full or short id prefix)')
-        .description('Star sessions so they are easy to find again — list them with --favorites, or `f` in the browser.')
-        .option('--remove', 'Unstar the given sessions instead of starring them')
-        .option('--list', 'List the starred sessions (the default when no ids are given)')
+        .command('bookmark')
+        .argument('[ids...]', 'Session ids to bookmark (full or short id prefix)')
+        .description('Bookmark sessions so they are easy to find again — list them with --bookmarks, or `b` in the browser.')
+        .option('--remove', 'Remove the given sessions from bookmarks instead of adding them')
+        .option('--list', 'List the bookmarked sessions (the default when no ids are given)')
         .option('--json', 'Output JSON');
     setHelpSections(cmd, {
         examples: `
-      # Star a session by its short id (the 8 chars the listing prints)
-      agents sessions favorite 26c27162
+      # Bookmark a session by its short id (the 8 chars the listing prints)
+      agents sessions bookmark 26c27162
 
-      # See what is starred
-      agents sessions favorite --list
+      # See what is bookmarked
+      agents sessions bookmark --list
 
-      # Browse only the starred ones
-      agents sessions --favorites
+      # Browse only the bookmarked ones
+      agents sessions --bookmarks
 
-      # Unstar it again
-      agents sessions favorite 26c27162 --remove
+      # Remove it from bookmarks again
+      agents sessions bookmark 26c27162 --remove
     `,
         notes: `
-      In the interactive browser (\`agents sessions\`), \`*\` stars the highlighted
-      session and \`f\` filters the list down to the starred ones.
+      In the interactive browser (\`agents sessions\`), \`*\` bookmarks the highlighted
+      session and \`b\` filters the list down to the bookmarked ones.
 
-      Stars live in ~/.agents/.history/favorites.json, keyed by session id, so
+      Bookmarks live in ~/.agents/.history/bookmarks.json, keyed by session id, so
       they survive a reindex of the session cache. They are per-machine: session
       sync carries transcripts, not this file.
     `,
@@ -74,32 +74,32 @@ export function registerSessionsFavoriteCommand(sessionsCmd) {
         // owns; it is still declared on this command so `--help` documents it.
         const json = self.optsWithGlobals().json === true;
         if (options.list || ids.length === 0) {
-            const starred = [...listFavorites()].sort();
+            const bookmarked = [...listBookmarks()].sort();
             if (json) {
-                process.stdout.write(JSON.stringify({ favorites: starred }, null, 2) + '\n');
+                process.stdout.write(JSON.stringify({ bookmarks: bookmarked }, null, 2) + '\n');
                 return;
             }
-            if (starred.length === 0) {
-                console.log(chalk.gray('No favorited sessions. Star one with `agents sessions favorite <id>`.'));
+            if (bookmarked.length === 0) {
+                console.log(chalk.gray('No bookmarked sessions. Bookmark one with `agents sessions bookmark <id>`.'));
                 return;
             }
-            for (const id of starred)
+            for (const id of bookmarked)
                 console.log(`${chalk.yellow('★')} ${id}`);
-            console.log(chalk.gray(`\n${starred.length} favorite${starred.length === 1 ? '' : 's'}.`));
+            console.log(chalk.gray(`\n${bookmarked.length} bookmark${bookmarked.length === 1 ? '' : 's'}.`));
             return;
         }
         const on = !options.remove;
         const results = [];
         for (const idQuery of ids) {
-            const resolved = resolveFavoriteTarget(idQuery);
+            const resolved = resolveBookmarkTarget(idQuery);
             if ('error' in resolved) {
                 results.push({ query: idQuery, error: resolved.error });
                 continue;
             }
-            // Unstarring something that was never starred, or starring it twice, is a
-            // no-op the store already short-circuits — report the resulting state.
-            setFavorite(resolved.id, on);
-            results.push({ query: idQuery, id: resolved.id, favorite: isFavorite(resolved.id) });
+            // Removing a bookmark that does not exist, or bookmarking it twice,
+            // is a no-op the store already short-circuits — report the resulting state.
+            setBookmark(resolved.id, on);
+            results.push({ query: idQuery, id: resolved.id, bookmark: isBookmarked(resolved.id) });
         }
         if (json) {
             process.stdout.write(JSON.stringify({ results }, null, 2) + '\n');
@@ -109,11 +109,11 @@ export function registerSessionsFavoriteCommand(sessionsCmd) {
                 if (r.error)
                     console.error(chalk.red(r.error));
                 else
-                    console.log(`${r.favorite ? chalk.yellow('★ favorited') : chalk.gray('☆ unfavorited')} ${r.id}`);
+                    console.log(`${r.bookmark ? chalk.yellow('★ bookmarked') : chalk.gray('☆ unbookmarked')} ${r.id}`);
             }
         }
-        // A failed lookup is a failed command — a script must not read "starred" from
-        // a zero exit when nothing was starred.
+        // A failed lookup is a failed command — a script must not read "bookmarked"
+        // from a zero exit when nothing was bookmarked.
         if (results.some((r) => r.error))
             process.exitCode = 1;
     });

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

@@ -27,8 +27,8 @@ export interface BrowserFilter {
     device?: string;
     /** filter to one team's lineage, or all — the `T` key / `--in-team`. */
     team?: string;
-    /** favorited-only — the `f` key / `--favorites`. */
-    favorites: boolean;
+    /** bookmarked-only — the `b` key / `--bookmarks`. */
+    bookmarks: boolean;
     /** this-repo subtree vs every directory — the `P` key / `--all`. */
     projectScope: 'repo' | 'all';
     /** time window (undefined = all time) — the `W` key / `--since`. */
@@ -39,8 +39,8 @@ export interface BrowserFilter {
     project?: string;
     /** upper time bound from --until. */
     until?: string;
-    /** retain only routine-origin sessions. */
-    routine: boolean;
+    /** retain only routine-origin sessions, optionally narrowed to one routine. */
+    routine: boolean | string;
     /** indexed resource filters shared by the flag and focus surfaces. */
     skill?: string;
     plugin?: string;
@@ -97,7 +97,8 @@ export declare function activeBrowserSeed(opts: {
     host?: string[];
     since?: string;
     all?: boolean;
-    favorites?: boolean;
+    bookmarks?: boolean;
+    routine?: boolean | string;
 }): Partial<BrowserFilter>;
 /**
  * The initial filter for the bare interactive listing: current-repo subtree by
@@ -113,7 +114,8 @@ export declare function bareBrowserSeed(opts: {
     since?: string;
     host?: string[];
     inTeam?: string;
-    favorites?: boolean;
+    bookmarks?: boolean;
+    routine?: boolean | string;
 }): 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. */
@@ -156,8 +158,8 @@ 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[];
+/** Apply the cheap in-memory filters (agent / device / project / running / bookmarks). */
+export declare function applyFilters(rows: SessionMeta[], live: Map<string, ActiveSession>, f: BrowserFilter, self: string, bookmarks: 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?: {