@phnx-labs/agents-cli 1.22.30 → 1.22.31

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 1.22.31
+
+- **`agents secrets unlock --keys` folds in the scoped-hold surface; the `secrets lease`/`leases`/`revoke` commands are deleted (RUSH-2350).** `unlock` now takes `--keys K1,K2` to hold ONLY that subset of a bundle behind its own expiry instead of the whole bundle — the one capability `lease` had that `unlock` did not, now on the command agents already reach for. Without `--keys`, `unlock` behaves exactly as before (whole bundle). An unknown or empty key subset fails closed (`Unknown secret lease key(s): …` / `requires at least one key`), `--keys` scopes exactly one local bundle (rejected with `--all`/`--host`), and `secrets status` now names the held keys of a scoped hold; `secrets lock <name>` releases it. The duplicate `secrets lease`/`secrets leases`/`secrets revoke` trio is gone — it had zero consumers, and its jobs (list holdings, release one) are already `secrets status` and `secrets lock`. No alias or deprecation shim (per the repo's no-unasked-shims rule). The underlying lease model (`src/lib/secrets/lease.ts`) is unchanged — `unlock --keys` reuses it. Source: `apps/cli/src/commands/secrets.ts` (`scopeHeldEnv`, the `unlock`/`status` actions), `apps/cli/src/lib/secrets/{agent,session-store}.ts`, `apps/cli/src/commands/secrets.scope.test.ts`, `apps/cli/src/commands/secrets.flags.test.ts`.
+
+- **Session previews use bookmark and focus as separate actions (RUSH-2373).** The shared interactive browser for ordinary, team, and routine sessions now uses `*` to bookmark the highlighted row, `b` / `--bookmarks` to filter bookmarks, and `f` to focus the highlighted session through the same attach-or-recover flow as `agents sessions focus`. Enter still resumes. The non-TTY surface is now `agents sessions bookmark`; its flag, JSON keys, code symbols, and durable store are bookmark-only, with a one-time migration from `~/.agents/.history/favorites.json` to `bookmarks.json`. The retired favorite command and flag are not aliases. Source: `apps/cli/src/commands/sessions-browser.ts`, `sessions-bookmark.ts`, `focus.ts`, `apps/cli/src/lib/session/bookmarks.ts`, `apps/cli/src/lib/migrate.ts`.
+
 ## 1.22.30
 
 - **`agents secrets import --force` now repairs a bundle whose metadata record is

package/README.md

@@ -338,8 +338,9 @@ On a terminal, `agents sessions --active` (and a bare `agents sessions`) open th
 |---|---|---|
 | `s` | search text | `--query` / positional |
 | `r` | running only | `--active` |
-| `f` | favorites only | `--favorites` |
-| `*` | star / unstar the highlighted session | `agents sessions favorite <id>` |
+| `b` | bookmarks only | `--bookmarks` |
+| `*` | bookmark / unbookmark the highlighted session | `agents sessions bookmark <id>` |
+| `f` | focus the highlighted session | `agents sessions focus <id>` |
 | `c` | team sessions | `--team` (alias: `--teams`) |
 | `a` | agent (cycles) | `-a` |
 | `d` | device (cycles) | `--device` |
@@ -349,7 +350,7 @@ On a terminal, `agents sessions --active` (and a bare `agents sessions`) open th
 | `⏎` | resume / attach | `resume` / `focus` |
 | `y` | copy the equivalent command | `--print-cmd` |
 
-**Star the sessions you keep coming back to.** `*` marks the highlighted row (a `★` shows in the listing), `f` narrows to the starred ones, and `agents sessions favorite <id>` / `--favorites` do the same outside a TTY. Stars live in `~/.agents/.history/favorites.json` keyed by session id, so they survive a reindex of the session cache. They're per-machine — session sync carries transcripts, not this file.
+**Bookmark the sessions you keep coming back to.** `*` marks the highlighted row (a `★` shows in the listing), `b` narrows to bookmarks, and `agents sessions bookmark <id>` / `--bookmarks` do the same outside a TTY. Press `f` to focus the highlighted row through the same attach-or-recover flow as `agents sessions focus <id>`; Enter keeps its existing resume behavior. Bookmarks live in `~/.agents/.history/bookmarks.json` keyed by session id, so they survive a reindex of the session cache. They're per-machine — session sync carries transcripts, not this file.
 
 **A session that lost its host says so.** When an editor window or an SSH connection goes down hard, the agent it owned used to simply disappear from `--active`; when an agent outlived its window in tmux, it reported a plain `idle`. Both now carry their own status: `✗ crashed` (the host went down and took the agent with it) and `◍ orphan` (still alive, but no client is attached — nothing is showing it). Read from tmux's attached-client count and the editor window's registry heartbeat, so a deliberate `agents sessions detach` is never mistaken for one, and a session that is still *working* headlessly is left alone.
 
@@ -359,7 +360,7 @@ Filters **stack** (they AND together), the active set shows in the header, and t
 | --- | --- |
 | ![sessions browser, preview hidden](assets/demos/sessions-preview-before.png) | ![sessions browser, preview open with a links line](assets/demos/sessions-preview-after.png) |
 
-Each live session resolves to `working`, `waiting_input` (with why -- a question, a plan review, or a permission prompt), `idle`, or a lifecycle state such as `orphaned`, `crashed`, `closed`, `abandoned`, `queued`, or `unknown`. Pass the matching flag (`--working`, `--idle`, `--waiting`, `--orphan`, `--crashed`, `--closed`, `--abandoned`, `--queued`, `--unknown`) directly; each implies `--active`, and several flags form a union. The fleet fan-out is already the default; `--local` opts out. `--all` instead widens historical directory and time scope. Rows also carry badges for the PR, worktree, and ticket. `agents sessions focus [selector]` accepts the same agent/version, device, time, team, project, skill/plugin, favorite, and live-state filters as the session browser. A unique id focuses directly; an agent/version or text selector always opens the preview picker. Immediately before attach it checks the tmux pane process: a living pane is joined in place, while a dead/missing pane enters recovery instead of showing tmux's `Pane is dead` screen.
+Each live session resolves to `working`, `waiting_input` (with why -- a question, a plan review, or a permission prompt), `idle`, or a lifecycle state such as `orphaned`, `crashed`, `closed`, `abandoned`, `queued`, or `unknown`. Pass the matching flag (`--working`, `--idle`, `--waiting`, `--orphan`, `--crashed`, `--closed`, `--abandoned`, `--queued`, `--unknown`) directly; each implies `--active`, and several flags form a union. The fleet fan-out is already the default; `--local` opts out. `--all` instead widens historical directory and time scope. Rows also carry badges for the PR, worktree, and ticket. `agents sessions focus [selector]` accepts the same agent/version, device, time, team, project, skill/plugin, bookmark, and live-state filters as the session browser. A unique id focuses directly; an agent/version or text selector always opens the preview picker. Immediately before attach it checks the tmux pane process: a living pane is joined in place, while a dead/missing pane enters recovery instead of showing tmux's `Pane is dead` screen.
 
 Landing on a session cold? `agents sessions <id>` prints a catch-up digest: an inferred title, files changed grouped by directory (created / modified / deleted), a histogram of which tools did the work (including parsed Bash commands -- `git`, `npm`, `ffmpeg`, `ssh`, and so on), and the last test verdict -- the signals to reload a task in seconds.
 

package/dist/commands/focus.d.ts

@@ -42,7 +42,7 @@ export interface FocusOptions {
     since?: string;
     until?: string;
     limit?: string;
-    favorites?: boolean;
+    bookmarks?: boolean;
     unmanaged?: boolean;
     sort?: string;
     working?: boolean;
@@ -74,6 +74,9 @@ export declare function selectFallback(attachOnly: boolean | undefined): Unreach
 export declare function focusAction(id: string | undefined, opts: FocusOptions): Promise<void>;
 /** A retained pane is not attachable merely because tmux can still display it. */
 export declare function isAttachableLiveSession(session: ActiveSession): boolean;
+/** Focus one row selected by the shared session browser through the same
+ * attach/recover decision as `agents sessions focus <id>`. */
+export declare function focusSelectedSession(meta: SessionMeta, active: ActiveSession | undefined, self: string): Promise<void>;
 /**
  * How a single selected live session opens in its new tab.
  *  - `attach` — a live tmux pane joined in the tab (a second client, no fork),

package/dist/commands/focus.js

@@ -32,7 +32,7 @@ const INHERITED_FOCUS_OPTIONS = [
     'local', 'host', 'device', 'active', 'agent',
     'claude', 'codex', 'kimi', 'antigravity', 'grok', 'opencode',
     'all', 'teams', 'inTeam', 'routine', 'project', 'skill', 'plugin',
-    'since', 'until', 'limit', 'favorites', 'unmanaged', 'sort',
+    'since', 'until', 'limit', 'bookmarks', 'unmanaged', 'sort',
     'working', 'idle', 'waiting', 'orphan', 'orphaned', 'crashed',
     'closed', 'abandoned', 'queued', 'unknown',
 ];
@@ -93,7 +93,7 @@ export function registerFocusCommand(program) {
         .option('--since <time>', 'Only sessions newer than this (for example 7d)')
         .option('--until <time>', 'Only sessions older than this timestamp')
         .option('-n, --limit <n>', 'Maximum candidates to load', '500')
-        .option('--favorites', 'Only favorited sessions')
+        .option('--bookmarks', 'Only bookmarked sessions')
         .option('--unmanaged', 'Also include native-home sessions outside managed versions')
         .option('--sort <field>', 'Order candidates by recent, cost, or duration', 'recent')
         .option('--working', 'Only live sessions currently doing work')
@@ -184,7 +184,7 @@ export async function focusAction(id, opts) {
             agent: agentSelector ?? focusOptionAgent(opts),
             teams: opts.teams === true,
             team: opts.inTeam,
-            favorites: opts.favorites === true,
+            bookmarks: opts.bookmarks === true,
             projectScope: opts.all || hosts.length > 0 || !!opts.project || idLookup ? 'all' : 'repo',
             project: opts.project,
             window: opts.since ?? (opts.all || idLookup ? undefined : '30d'),
@@ -304,7 +304,7 @@ function looksLikeIdentitySelector(selector) {
 function hasFocusFilters(opts, statuses) {
     return statuses.length > 0 || !!(opts.active || opts.local || opts.host?.length || opts.device?.length || focusOptionAgent(opts) ||
         opts.all || opts.teams || opts.inTeam || opts.routine || opts.project || opts.skill || opts.plugin ||
-        opts.since || opts.until || opts.favorites || opts.unmanaged || (opts.sort && opts.sort !== 'recent'));
+        opts.since || opts.until || opts.bookmarks || opts.unmanaged || (opts.sort && opts.sort !== 'recent'));
 }
 function focusSort(value) {
     if (!value || value === 'recent')
@@ -370,6 +370,21 @@ async function focusResolvedSession(meta, liveById, self, fallback, attachOnly)
     }
     await resumeSessionInPlace(meta);
 }
+/** Focus one row selected by the shared session browser through the same
+ * attach/recover decision as `agents sessions focus <id>`. */
+export async function focusSelectedSession(meta, active, self) {
+    if (active && !active.sessionId) {
+        if (isAttachableLiveSession(active)) {
+            await jumpTo(active, self, resumeInNewTab);
+            return;
+        }
+        console.log(chalk.yellow('This live session has no session id or living attach rail to focus.'));
+        process.exitCode = 1;
+        return;
+    }
+    const liveById = active ? new Map([[meta.id, active]]) : new Map();
+    await focusResolvedSession(meta, liveById, self, resumeInNewTab, false);
+}
 function activeFromMeta(meta) {
     return {
         context: 'headless',

package/dist/commands/secrets.d.ts

@@ -12,6 +12,7 @@ import { bundleEnvToDotenv } from '../lib/secrets/push.js';
 export { bundleEnvToDotenv };
 import { type SecretsBackend, type SecretsBundle, type SecretsPolicy } from '../lib/secrets/bundles.js';
 import { type SecretsListFilterOpts } from '../lib/secrets/list-filter.js';
+import { type SecretLease } from '../lib/secrets/lease.js';
 import { type BundleUsageSummary } from '../lib/secrets/usage-db.js';
 /** Read all available data from stdin synchronously, trimmed. */
 /**
@@ -51,6 +52,25 @@ export declare function parseImportSource(opts: {
  * without a live SSH session.
  */
 export declare function resolveUnlockTtlMs(ttl: string | undefined, until: string | undefined, now?: number): number;
+/**
+ * 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 declare function scopeHeldEnv(input: {
+    bundle: string;
+    env: Record<string, string>;
+    keys: string | null;
+    ttlMs: number;
+    harness: string;
+    sleepPersist: boolean;
+}): {
+    heldEnv: Record<string, string>;
+    lease?: SecretLease;
+};
 export declare function buildRemoteUnlockArgs(names: string[], opts: {
     all?: boolean;
     ttl?: string;

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',
@@ -2442,89 +2466,6 @@ 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('--ttl <duration>', 'How long to hold it (e.g. 30m, 8h, 3d)')
-        .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.ttl);
-        if (seconds === null)
-            throw new Error(`Invalid lease duration '${opts.ttl}'.`);
-        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.')
@@ -2532,6 +2473,7 @@ Examples:
         .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>`.')
         .action(async (names, opts) => {
@@ -2539,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.
@@ -2623,6 +2578,7 @@ Examples:
         // agent happened to launch the shell, leaving the grant unreadable to
         // every other reader for its whole TTL.
         const harness = opts.agent || GLOBAL_HARNESS;
+        const durable = opts.durable ?? secretsAgentDurable();
         for (const name of targets) {
             try {
                 // noAgent: read the real keychain (one Touch ID) rather than the
@@ -2639,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`
@@ -2661,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.`));
@@ -2748,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-favorite.d.ts → sessions-bookmark.d.ts}

@@ -1,20 +1,20 @@
 /**
- * `agents sessions favorite` — the non-TTY half of the favorite hotkey.
+ * `agents sessions bookmark` — the non-TTY half of the bookmark hotkey.
  *
- * The `*` hotkey in the interactive browser is how a human favorites a session;
+ * 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/favorites.ts`.
+ * 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: favoriting
- * the wrong session is invisible until the user wonders where their favorite 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 declare function resolveFavoriteTarget(idQuery: string): {
+export declare function resolveBookmarkTarget(idQuery: string): {
     id: string;
 } | {
     error: string;
 };
-export declare function registerSessionsFavoriteCommand(sessionsCmd: Command): void;
+export declare function registerSessionsBookmarkCommand(sessionsCmd: Command): void;

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

@@ -1,26 +1,26 @@
 /**
- * `agents sessions favorite` — the non-TTY half of the favorite hotkey.
+ * `agents sessions bookmark` — the non-TTY half of the bookmark hotkey.
  *
- * The `*` hotkey in the interactive browser is how a human favorites a session;
+ * 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/favorites.ts`.
+ * 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: favoriting
- * the wrong session is invisible until the user wonders where their favorite 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 `*` favorites those
+    // 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())
@@ -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 favorite (full or short id prefix)')
-        .description('Favorite sessions so they are easy to find again — list them with --favorites, or `f` in the browser.')
-        .option('--remove', 'Remove the given sessions from favorites instead of adding them')
-        .option('--list', 'List the favorited 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: `
-      # Favorite 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 favorited
-      agents sessions favorite --list
+      # See what is bookmarked
+      agents sessions bookmark --list
 
-      # Browse only the favorited ones
-      agents sessions --favorites
+      # Browse only the bookmarked ones
+      agents sessions --bookmarks
 
-      # Remove it from favorites again
-      agents sessions favorite 26c27162 --remove
+      # Remove it from bookmarks again
+      agents sessions bookmark 26c27162 --remove
     `,
         notes: `
-      In the interactive browser (\`agents sessions\`), \`*\` favorites the highlighted
-      session and \`f\` filters the list down to the favorited ones.
+      In the interactive browser (\`agents sessions\`), \`*\` bookmarks the highlighted
+      session and \`b\` filters the list down to the bookmarked ones.
 
-      Favorites 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 favorited = [...listFavorites()].sort();
+            const bookmarked = [...listBookmarks()].sort();
             if (json) {
-                process.stdout.write(JSON.stringify({ favorites: favorited }, null, 2) + '\n');
+                process.stdout.write(JSON.stringify({ bookmarks: bookmarked }, null, 2) + '\n');
                 return;
             }
-            if (favorited.length === 0) {
-                console.log(chalk.gray('No favorited sessions. Favorite 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 favorited)
+            for (const id of bookmarked)
                 console.log(`${chalk.yellow('★')} ${id}`);
-            console.log(chalk.gray(`\n${favorited.length} favorite${favorited.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;
             }
-            // Unfavoriting something that was never favorited, or favoriting it twice,
+            // Removing a bookmark that does not exist, or bookmarking 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) });
+            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 "favorited"
-        // from a zero exit when nothing was favorited.
+        // 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?: {