@phnx-labs/agents-cli 1.22.30 → 1.22.32

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?: {

package/dist/commands/sessions-browser.js

@@ -19,10 +19,10 @@ import { gatherRemoteList } from '../lib/session/remote-list.js';
 import { resolveVersionAliasLoose } from '../lib/versions.js';
 import { AGENTS } from '../lib/agents.js';
 import { enrichTeamOrigins, safeTeamText } from '../lib/session/team-filter.js';
-import { listFavorites, toggleFavorite } from '../lib/session/favorites.js';
+import { listBookmarks, toggleBookmark } from '../lib/session/bookmarks.js';
 import { machineId, normalizeHost } from '../lib/session/sync/config.js';
 import { buildPreview } from './sessions-picker.js';
-import { formatPickerLabel, pickerColumnsFor, ticketLabel, mergeLocalFirst, gatherActiveSessions, liveHostLabel, LIVE_ROW_PREFIX, cleanPreview, handlePickedSession, shouldIncludeLocal, remoteHostsToDial, matchesTeam, formatLiveStatusHeadline, isRunningLiveSession, matchesLiveStatus, parseAgentFilter, } from './sessions.js';
+import { formatPickerLabel, pickerColumnsFor, ticketLabel, mergeLocalFirst, gatherActiveSessions, liveHostLabel, LIVE_ROW_PREFIX, cleanPreview, handlePickedSession, shouldIncludeLocal, remoteHostsToDial, matchesTeam, formatLiveStatusHeadline, isRunningLiveSession, matchesLiveStatus, parseAgentFilter, resolveRoutineName, } from './sessions.js';
 /**
  * Complete a seed into the filter the picker actually runs on.
  *
@@ -40,7 +40,7 @@ export function buildInitialFilter(initial) {
     return {
         running: initial.running ?? false,
         teams: initial.teams ?? false,
-        favorites: initial.favorites ?? false,
+        bookmarks: initial.bookmarks ?? false,
         agent: initial.agent,
         device: initial.device,
         team: initial.team,
@@ -128,8 +128,8 @@ export function browserFilterToArgv(f, query = '') {
         a.push(`--${status === 'orphaned' ? 'orphan' : status}`);
     if (f.teams)
         a.push('--teams');
-    if (f.favorites)
-        a.push('--favorites');
+    if (f.bookmarks)
+        a.push('--bookmarks');
     if (f.agent)
         a.push('-a', f.agent);
     if (f.device)
@@ -144,8 +144,11 @@ export function browserFilterToArgv(f, query = '') {
         a.push('--until', f.until);
     if (f.project)
         a.push('--project', f.project);
-    if (f.routine)
+    if (f.routine) {
         a.push('--routine');
+        if (typeof f.routine === 'string')
+            a.push(f.routine);
+    }
     if (f.skill)
         a.push('--skill', f.skill);
     if (f.plugin)
@@ -179,7 +182,8 @@ export function activeBrowserSeed(opts) {
     return {
         running: true,
         teams: !!opts.teams,
-        favorites: !!opts.favorites,
+        bookmarks: !!opts.bookmarks,
+        routine: opts.routine ?? false,
         agent: opts.agent,
         projectScope: 'all',
         device: normalizeDeviceSeed(opts.host?.[0]),
@@ -211,7 +215,8 @@ export function bareBrowserSeed(opts) {
     const wholeTeam = !!opts.inTeam;
     return {
         teams: !!opts.teams,
-        favorites: !!opts.favorites,
+        bookmarks: !!opts.bookmarks,
+        routine: opts.routine ?? false,
         agent: opts.agent,
         // The filter carries one device; seed it only when the scope names exactly
         // one, so a two-device scope isn't narrowed to the first of them.
@@ -339,8 +344,11 @@ export function remotePoolArgs(f, fixedFilters) {
         forwarded.push('--until', f.until);
     if (f.project)
         forwarded.push('--project', f.project);
-    if (f.routine)
+    if (f.routine) {
         forwarded.push('--routine');
+        if (typeof f.routine === 'string')
+            forwarded.push(f.routine);
+    }
     if (f.skill)
         forwarded.push('--skill', f.skill);
     if (f.plugin)
@@ -417,6 +425,8 @@ export function liveSessionToMeta(a, self) {
         prNumber: a.pr?.number,
         ticketId: a.ticket?.id,
         worktreeSlug: a.worktree?.slug,
+        origin: a.origin,
+        routineName: a.routineName,
     };
 }
 /**
@@ -453,14 +463,22 @@ export function shouldShowHostColumn(f, live, rows) {
         return false;
     return rows.some((r) => liveHostLabel(live.get(r.id)) !== '');
 }
-/** Apply the cheap in-memory filters (agent / device / project / running / favorites). */
-export function applyFilters(rows, live, f, self, favorites) {
+/** Apply the cheap in-memory filters (agent / device / project / running / bookmarks). */
+export function applyFilters(rows, live, f, self, bookmarks) {
     let out = rows;
     // A projected live row is keyed by pid/task when it has no session id, and a
-    // favorite is always keyed by a real session id — so an id-less row can never
-    // be favorited and correctly drops out here.
-    if (f.favorites)
-        out = out.filter((r) => favorites.has(r.id));
+    // A bookmark is always keyed by a real session id — so an id-less row can
+    // never be bookmarked and correctly drops out here.
+    if (f.bookmarks)
+        out = out.filter((r) => bookmarks.has(r.id));
+    if (f.routine) {
+        out = out.filter((r) => r.origin === 'routine' || !!r.routineName);
+        if (typeof f.routine === 'string') {
+            const routineNames = distinct(out.map((r) => r.routineName));
+            const selected = resolveRoutineName(f.routine, routineNames);
+            out = selected ? out.filter((r) => r.routineName === selected) : [];
+        }
+    }
     if (f.agent) {
         const { agent, version: rawVersion } = parseAgentFilter(f.agent);
         const localVersion = agent && agent in AGENTS
@@ -527,7 +545,7 @@ export async function collectSessionCandidates(initial, opts = {}) {
     const rows = filter.running || opts.includeLive
         ? mergeLiveIntoPool(pool.rows, liveById, self, includeUnindexedLive)
         : pool.rows;
-    const sessions = applyFilters(rows, liveById, filter, self, listFavorites());
+    const sessions = applyFilters(rows, liveById, filter, self, listBookmarks());
     return { sessions, liveById, self, unreachable: pool.unreachable };
 }
 /** Derive the SSH-launch origin tag for a picker row from the live index. Set
@@ -552,15 +570,17 @@ function headerFor(f) {
         bits.push('running');
     if (f.teams)
         bits.push('teams');
-    if (f.favorites)
-        bits.push('favorites');
+    if (f.routine)
+        bits.push(`routine:${typeof f.routine === 'string' ? f.routine : 'all'}`);
+    if (f.bookmarks)
+        bits.push('bookmarks');
     return bits.join(' · ');
 }
 function helpFor(_f, mode) {
     if (mode === 'search') {
         return 'type to filter · ↑↓ navigate · esc exit search · ⏎ resume';
     }
-    return 's search · r running · f favorites · * favorite · c teams · t team · a agent · d device · p project · w window · tab preview · y copy-cmd · ⏎ resume · esc quit';
+    return 's search · r running · b bookmarks · * bookmark · f focus · c teams · t team · a agent · d device · p project · w window · tab preview · y copy-cmd · ⏎ resume · esc quit';
 }
 /**
  * Launch the interactive session browser. `initial` seeds the filter (e.g.
@@ -588,10 +608,11 @@ export async function runSessionBrowser(initial = {}, opts = {}) {
     // The live index is slow (a full ps/tmux scan) and only the running filter
     // needs it — fetch it once, lazily, the first time running is toggled on.
     let liveCache = null;
+    const liveFor = (id) => liveCache?.get(id);
     // Re-read every load (it's an mtime-memoized parse of one small file), so the
-    // `*` key's reload picks up the favorite it just wrote — and so does one
-    // favorited by another session on this machine.
-    let favorites = new Set();
+    // `*` key's reload picks up the bookmark it just wrote — and so does one
+    // bookmarked by another session on this machine.
+    let bookmarks = new Set();
     // Generation guard: two quick keypresses can start overlapping loads whose
     // SSH fan-outs settle out of order. dynamicPicker's own gen ref guards which
     // rows become `items`, but the shared closure state below (cols / cycle pools /
@@ -652,8 +673,8 @@ export async function runSessionBrowser(initial = {}, opts = {}) {
             ...rows.map((r) => safeTeamText(r.spawnedTeam)),
             ...rows.map((r) => safeTeamText(r.teamOrigin?.team)),
         ]);
-        favorites = listFavorites();
-        const filtered = applyFilters(rows, live ?? new Map(), f, self, favorites);
+        bookmarks = listBookmarks();
+        const filtered = applyFilters(rows, live ?? new Map(), f, self, bookmarks);
         cols = pickerColumnsFor(filtered);
         cols.showHost = shouldShowHostColumn(f, live, filtered);
         // Status rides the same gate as the host column: both come from the live
@@ -667,14 +688,14 @@ export async function runSessionBrowser(initial = {}, opts = {}) {
         initialFilter,
         load,
         keyFor: (s) => s.id,
-        labelFor: (s, q) => formatPickerLabel(s, q, cols, sshOriginTagFor(liveCache, s.id), liveHostLabel(liveCache?.get(s.id)), favorites.has(s.id), liveCache?.get(s.id)),
+        labelFor: (s, q) => formatPickerLabel(s, q, cols, sshOriginTagFor(liveCache, s.id), liveHostLabel(liveCache?.get(s.id)), bookmarks.has(s.id), liveCache?.get(s.id)),
         matches: sessionMatchesQuery,
         // Lead the preview with the live status banner — the one place a `crashed` /
         // `orphaned` session gets a sentence instead of a glyph. `buildPreview` is
         // memoized per session, so the volatile live half is prepended here rather
         // than baked into the cached body.
         buildPreview: (s) => {
-            const headline = formatLiveStatusHeadline(liveCache?.get(s.id), favorites.has(s.id));
+            const headline = formatLiveStatusHeadline(liveCache?.get(s.id), bookmarks.has(s.id));
             const body = buildPreview(s);
             return headline ? `${headline}\n${body}` : body;
         },
@@ -685,9 +706,10 @@ export async function runSessionBrowser(initial = {}, opts = {}) {
         enterHint: 'resume',
         emptyMessage: 'No sessions match this filter.',
         loadingMessage: local ? 'Loading…' : 'Loading (reaching other machines)…',
+        submitKeys: { f: 'focus' },
         keyBindings: {
             r: (f) => ({ ...f, running: !f.running }),
-            f: (f) => ({ ...f, favorites: !f.favorites }),
+            b: (f) => ({ ...f, bookmarks: !f.bookmarks }),
             c: (f) => ({ ...f, teams: !f.teams }),
             a: (f) => ({ ...f, agent: cycle(f.agent, agentsInPool) }),
             d: (f) => ({ ...f, device: cycle(f.device, devicesInPool) }),
@@ -700,13 +722,13 @@ export async function runSessionBrowser(initial = {}, opts = {}) {
         },
         onKey: (name, f, active, query) => {
             if (name === '*') {
-                // Only a row with a real session id can be favorited: a projected live row
+                // Only a row with a real session id can be bookmarked: a projected live row
                 // with no id is keyed by pid, which is gone the moment the process is.
                 if (!active || active.id.startsWith(LIVE_ROW_PREFIX))
-                    return 'nothing to favorite on this row';
-                const on = toggleFavorite(active.id);
-                // reload so the row's favorite glyph is repainted — labels are memoized per row.
-                return { flash: on ? `★ favorited ${active.shortId}` : `☆ unfavorited ${active.shortId}`, reload: true };
+                    return 'nothing to bookmark on this row';
+                const on = toggleBookmark(active.id);
+                // Reload so the row's bookmark glyph is repainted — labels are memoized per row.
+                return { flash: on ? `★ bookmarked ${active.shortId}` : `☆ unbookmarked ${active.shortId}`, reload: true };
             }
             // Both cases: `hotkeyToken` hands `onKey` the literal character, and this
             // key worked with caps lock on before it existed.
@@ -722,5 +744,12 @@ export async function runSessionBrowser(initial = {}, opts = {}) {
     });
     if (!picked)
         return;
+    if (picked.action === 'focus') {
+        // `focus.ts` consumes this browser for its selector path, so import only
+        // after selection to keep the shared picker/focus dependency acyclic.
+        const { focusSelectedSession } = await import('./focus.js');
+        await focusSelectedSession(picked.item, liveFor(picked.item.id), self);
+        return;
+    }
     await handlePickedSession({ session: picked.item, action: 'resume' });
 }

package/dist/commands/sessions-stats.js

@@ -95,7 +95,7 @@ async function statsAction(cmd) {
     // The parent `sessions` command owns --agent/--project/--plugin/--since/--json
     // and keeps parsing them past the subcommand name (it has a positional
     // [query]), binding them to the PARENT — so read the merged view, not the
-    // action's own options. Same reason sessions-favorite.ts uses optsWithGlobals.
+    // action's own options. Same reason sessions-bookmark.ts uses optsWithGlobals.
     const opts = cmd.optsWithGlobals();
     const kind = normalizeKind(opts.kind);
     const sinceMs = opts.since ? parseTimeFilter(opts.since) : undefined;

package/dist/commands/sessions.d.ts

@@ -59,8 +59,8 @@ interface SessionsOptions extends SessionFilterOptions {
     abandoned?: boolean;
     queued?: boolean;
     unknown?: boolean;
-    /** Show only favorited sessions — the `f` key's flag twin. */
-    favorites?: boolean;
+    /** Show only bookmarked sessions — the `b` key's flag twin. */
+    bookmarks?: boolean;
     /** Enrich the listing with live glyphs/preview for running rows. Default on;
      * `--no-live` sets this false. Commander's `--no-` convention. */
     live?: boolean;
@@ -399,6 +399,8 @@ export declare function gatherActiveSessions(opts?: {
     sessions: ActiveSession[];
     remoteDeviceCount: number;
 }>;
+/** Apply the routine selector to enriched live rows for every non-browser active view. */
+export declare function filterActiveSessionsByRoutine(sessions: ActiveSession[], routine: boolean | string | undefined): ActiveSession[];
 export type LiveStatusFilter = 'working' | 'idle' | 'waiting' | 'orphaned' | 'crashed' | 'closed' | 'abandoned' | 'queued' | 'unknown';
 /** Match the status words users see, preserving activity's richer working signal. */
 export declare function matchesLiveStatus(session: ActiveSession, status: LiveStatusFilter): boolean;
@@ -432,7 +434,7 @@ export interface RoutineChoice {
     latestRunSessionCount: number;
 }
 export declare function buildRoutineRunGroups(sessions: SessionMeta[]): RoutineRunGroup[];
-export declare function buildRoutineChoices(sessions: SessionMeta[]): RoutineChoice[];
+export declare function buildRoutineChoices(sessions: SessionMeta[], runOnlyNames?: string[]): RoutineChoice[];
 export declare function filterSessionsByRoutine(sessions: SessionMeta[], routine: boolean | string, interactive: boolean): Promise<SessionMeta[] | null>;
 /** Resolve a session by id/query globally and print its compact preview (no pager).
  * Backs `--preview` — the fast path for the "peek before resume" hot loop. */
@@ -453,7 +455,7 @@ export declare function renderSessionPreview(query: string, scope: {
  * reads "orphan" and knows it means "still running in tmux with no window
  * attached", so those two spell it out.
  */
-export declare function formatLiveStatusHeadline(live: ActiveSession | undefined, favorite?: boolean): string;
+export declare function formatLiveStatusHeadline(live: ActiveSession | undefined, bookmarked?: boolean): string;
 /** Merge local and peer envelopes without changing the versioned JSON shape. */
 export declare function mergeToolSearchEnvelopes(local: ToolSearchEnvelope, remotes: ToolSearchEnvelope[]): ToolSearchEnvelope;
 export declare function mergeToolProgramCountEnvelopes(local: ToolProgramCountEnvelope, remotes: ToolProgramCountEnvelope[]): ToolProgramCountEnvelope;
@@ -487,7 +489,7 @@ export declare function teamBadge(session: SessionMeta): {
  * (tracker/PR ref, pulled out of the badge blob so refs align) is only rendered
  * when `showTicket` — otherwise a listing with no refs would waste a column of
  * dashes and needlessly truncate the topic. Worktree stays a trailing badge. */
-export declare function flatSessionRow(session: SessionMeta, live?: ActiveSession, showTicket?: boolean, cols?: PickerColumns, favorite?: boolean): string;
+export declare function flatSessionRow(session: SessionMeta, live?: ActiveSession, showTicket?: boolean, cols?: PickerColumns, bookmarked?: boolean): string;
 /**
  * Live-session index for enriching the default listing, or undefined when
  * enrichment is off (`--no-live`) or irrelevant (`--json`, which serializes
@@ -571,11 +573,11 @@ export interface PickerColumns {
      */
     showHost?: boolean;
     /**
-     * Render the favorite marker column. Like every other conditional column here,
+     * Render the bookmark marker column. Like every other conditional column here,
      * it earns its 2 cells only when some row in the pool is actually starred — a
-     * user who has never favorited anything pays nothing for the feature.
+     * user who has never bookmarked anything pays nothing for the feature.
      */
-    showFavorite?: boolean;
+    showBookmark?: boolean;
     /**
      * Render the live status column (`working` / `waiting` / `orphan` / `crashed`).
      * Live-only, gated the same way as {@link showHost}: it comes from the
@@ -612,7 +614,7 @@ export declare function pickerColumnsFor(sessions: SessionMeta[]): PickerColumns
  * resolvable host (cloud rows, an unreadable process env).
  */
 export declare function liveHostLabel(a: ActiveSession | undefined): string;
-export declare function formatPickerLabel(s: SessionMeta, query: string, cols?: PickerColumns, ssh?: SshOriginTag, host?: string, favorite?: boolean, live?: ActiveSession): string;
+export declare function formatPickerLabel(s: SessionMeta, query: string, cols?: PickerColumns, ssh?: SshOriginTag, host?: string, bookmarked?: boolean, live?: ActiveSession): string;
 /**
  * Pick a hint to show above the picker. Deterministic (keys off the pool size)
  * so it stays fixed across the picker's re-renders within a single run.