@phnx-labs/agents-cli 1.22.30 → 1.22.31

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;
@@ -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.

package/dist/commands/sessions.js

@@ -55,8 +55,8 @@ import { setHelpSections } from '../lib/help.js';
 import { registerSessionsTailCommand } from './sessions-tail.js';
 import { registerSessionsResumeCommand } from './sessions-resume.js';
 import { registerSessionsForkCommand } from './fork.js';
-import { registerSessionsFavoriteCommand } from './sessions-favorite.js';
-import { isFavorite, listFavorites } from '../lib/session/favorites.js';
+import { registerSessionsBookmarkCommand } from './sessions-bookmark.js';
+import { isBookmarked, listBookmarks } from '../lib/session/bookmarks.js';
 import { registerGoCommand } from './go.js';
 import { registerFocusCommand } from './focus.js';
 import { registerReconnectCommand } from './reconnect.js';
@@ -1361,26 +1361,25 @@ async function renderActiveSessions(asJson, waitingOnly = false, opts = {}) {
     const self = machineId();
     const gathered = await gatherActiveSessions(opts);
     const { remoteDeviceCount } = gathered;
-    // --favorites narrows the live view too. Applied HERE, not only in the
+    // Backfill agent version, refs, created time, and routine provenance from the
+    // historical index. Routine filtering needs that provenance before it narrows
+    // the live pool; doing it here also enriches both JSON and human output.
+    backfillActiveRowsFromIndex(gathered.sessions);
+    // --bookmarks narrows the live view too. Applied HERE, not only in the
     // browser: the browser is skipped for --json, --waiting, a pipe, a multi-host
     // scope, and an SSH-fanout peer, and the flag silently did nothing on every
-    // one of those paths — including `--active --favorites --json`, which is
+    // one of those paths — including `--active --bookmarks --json`, which is
     // exactly what the browser's own `y` copy-cmd hands to an agent.
-    const merged = opts.favoritesOnly
-        ? gathered.sessions.filter((s) => !!s.sessionId && listFavorites().has(s.sessionId))
+    const merged = opts.bookmarksOnly
+        ? gathered.sessions.filter((s) => !!s.sessionId && listBookmarks().has(s.sessionId))
         : gathered.sessions;
+    const routineFiltered = filterActiveSessionsByRoutine(merged, opts.routine);
     // Status flags form a union. --waiting additionally retains its scriptable
     // gate: exit non-zero when the union contains a session awaiting the user.
     const statusFiltered = opts.statuses?.length
-        ? merged.filter((session) => opts.statuses.some((status) => matchesLiveStatus(session, status)))
-        : merged.filter(isRunningLiveSession);
+        ? routineFiltered.filter((session) => opts.statuses.some((status) => matchesLiveStatus(session, status)))
+        : routineFiltered.filter(isRunningLiveSession);
     const sessions = statusFiltered;
-    // Backfill agent version + ticket/PR/label/created onto the live rows from the
-    // historical index (RUSH-2205) — a running process reports none of these, and
-    // an orphan row usually lacks them. Done before both the JSON and human paths
-    // so every consumer (incl. the SSH fan-out's remote --json) sees enriched rows;
-    // transcripts sync across the fleet, so a remote row resolves from the local DB.
-    backfillActiveRowsFromIndex(sessions);
     if (asJson) {
         // Resolve who is watching each local tmux pane before serializing: `viewingIn`
         // is how a consumer distinguishes a session someone is looking at from one
@@ -1426,6 +1425,19 @@ async function renderActiveSessions(asJson, waitingOnly = false, opts = {}) {
     if (waitingOnly && sessions.some(isAwaitingUser))
         process.exitCode = 1;
 }
+/** Apply the routine selector to enriched live rows for every non-browser active view. */
+export function filterActiveSessionsByRoutine(sessions, routine) {
+    if (!routine)
+        return sessions;
+    const routineSessions = sessions.filter((session) => session.origin === 'routine' || !!session.routineName);
+    if (typeof routine !== 'string')
+        return routineSessions;
+    const names = [...new Set(routineSessions.map((session) => session.routineName).filter((name) => !!name))];
+    const selected = resolveRoutineName(routine, names);
+    return selected
+        ? routineSessions.filter((session) => session.routineName === selected)
+        : [];
+}
 /** Match the status words users see, preserving activity's richer working signal. */
 export function matchesLiveStatus(session, status) {
     if (status === 'working')
@@ -1492,7 +1504,9 @@ export function isBareBrowserListing(options, query) {
  */
 export function hasNoBrowserDisqualifyingFlags(options, query) {
     return (!query &&
-        !options.routine &&
+        // A named team view is a flat selectable pool; the bare --teams report
+        // stays grouped and printed because the browser cannot preserve its shape.
+        (!options.teams || !!options.inTeam) &&
         !options.flat &&
         !options.tree &&
         !options.markdown &&
@@ -1657,8 +1671,8 @@ function canonicalSessionsCommand(query, options) {
         a.push('--local');
     if (options.waiting)
         a.push('--waiting');
-    if (options.favorites)
-        a.push('--favorites');
+    if (options.bookmarks)
+        a.push('--bookmarks');
     const q = (query ?? '').trim();
     if (q)
         a.push(JSON.stringify(q));
@@ -1768,7 +1782,7 @@ export async function renderSessionPreview(query, scope) {
         }));
         return;
     }
-    const headline = formatLiveStatusHeadline(live, isFavorite(session.id));
+    const headline = formatLiveStatusHeadline(live, isBookmarked(session.id));
     if (headline)
         console.log(headline);
     console.log(buildPreview(session));
@@ -1783,12 +1797,12 @@ export async function renderSessionPreview(query, scope) {
  * reads "orphan" and knows it means "still running in tmux with no window
  * attached", so those two spell it out.
  */
-export function formatLiveStatusHeadline(live, favorite = false) {
-    const star = favorite ? chalk.yellow('★ ') : '';
+export function formatLiveStatusHeadline(live, bookmarked = false) {
+    const star = bookmarked ? chalk.yellow('★ ') : '';
     // With no live row there is no status to lead with, so the star has to say
     // what it means on its own — a bare `★` above a preview reads as noise.
     if (!live)
-        return favorite ? chalk.yellow('★ favorited') : '';
+        return bookmarked ? chalk.yellow('★ bookmarked') : '';
     const { glyph } = liveGlyphAndPreview(live);
     const word = liveStatusWord(live) || live.status;
     // One definition, shared with `--waiting`. A second local copy drifted: the
@@ -2140,7 +2154,8 @@ limitSource) {
                 host: options.host,
                 since: options.since,
                 all: options.all,
-                favorites: options.favorites,
+                bookmarks: options.bookmarks,
+                routine: options.routine,
             }), { local: options.local === true, hosts: options.host });
             return;
         }
@@ -2150,8 +2165,9 @@ limitSource) {
         await renderActiveSessions(options.json === true, options.waiting === true, {
             local: forceLocal,
             hosts: options.host,
-            favoritesOnly: options.favorites === true,
+            bookmarksOnly: options.bookmarks === true,
             statuses: liveStatuses,
+            routine: options.routine,
         });
         return;
     }
@@ -2165,12 +2181,10 @@ limitSource) {
     // printed/render paths (agents and scripts unaffected). An explicit --since seeds
     // the browser's window so the flag is honored, not swallowed.
     //
-    // `--teams` diverts to the printed team-grouped report (printTeamsView, below):
-    // grouping teammates under their team is a shape the flat fuzzy picker cannot
-    // represent, so like --tree it is a printed listing, not an interactive pick.
-    // --teams --flat/--tree keep their inline table rendering; a search query keeps
-    // the picker so `<term> --teams` still searches.
-    if (isBareBrowserListing(options, query) && !options.teams) {
+    // Bare `--teams` still diverts to the printed team-grouped report because the
+    // flat picker cannot preserve that shape. `--in-team <name> --teams` is one
+    // flat lineage, so it qualifies through hasNoBrowserDisqualifyingFlags.
+    if (isBareBrowserListing(options, query)) {
         const { runSessionBrowser, bareBrowserSeed } = await import('./sessions-browser.js');
         await runSessionBrowser(bareBrowserSeed({
             teams: options.teams,
@@ -2179,7 +2193,8 @@ limitSource) {
             since: options.since,
             host: options.host,
             inTeam: options.inTeam,
-            favorites: options.favorites,
+            bookmarks: options.bookmarks,
+            routine: options.routine,
         }), { local: options.local === true, hosts: options.host });
         return;
     }
@@ -2349,11 +2364,11 @@ limitSource) {
         // read. Match either, after that pass has populated `teamOrigin`.
         if (options.inTeam)
             sessions = sessions.filter((s) => matchesTeam(s, options.inTeam));
-        // --favorites narrows to the starred set. Applied here, before the JSON
-        // emit, so `--favorites --json` is the machine-readable twin of the `f` key.
-        if (options.favorites) {
-            const starred = listFavorites();
-            sessions = sessions.filter((s) => starred.has(s.id));
+        // --bookmarks narrows to the bookmarked set. Applied here, before the JSON
+        // emit, so `--bookmarks --json` is the machine-readable twin of the `b` key.
+        if (options.bookmarks) {
+            const bookmarks = listBookmarks();
+            sessions = sessions.filter((s) => bookmarks.has(s.id));
         }
         if (toolEvidenceMode) {
             const self = toolSelf;
@@ -2659,7 +2674,7 @@ function timeCell(age, topicSlack) {
  * (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 function flatSessionRow(session, live, showTicket = false, cols = {}, favorite = false) {
+export function flatSessionRow(session, live, showTicket = false, cols = {}, bookmarked = false) {
     const agentColor = colorAgent(session.agent);
     const age = sessionAgeParts(session.timestamp, session.lastActivity);
     const project = session.project || '-';
@@ -2696,18 +2711,18 @@ export function flatSessionRow(session, live, showTicket = false, cols = {}, fav
     const width = terminalWidth();
     const requestedModelW = cols.showModel ? (cols.modelWidth ?? PICKER_MODEL_MAX) : 0;
     // Same conditional 2 cells as the picker's marker, for the same reason.
-    const favW = cols.showFavorite ? 2 : 0;
-    const favCell = cols.showFavorite ? (favorite ? chalk.yellow('★ ') : '  ') : '';
+    const bookmarkW = cols.showBookmark ? 2 : 0;
+    const bookmarkCell = cols.showBookmark ? (bookmarked ? chalk.yellow('★ ') : '  ') : '';
     // Sized against the last-activity label alone, so the creation field is an
     // additive decision the row makes only once it knows what space is left.
-    const fixedW = favW + (10 + 9 + 8 + 16) + glyphW + statusW + machineW + ticketW + wtW + team.width + stringWidth(age.last) + 1;
+    const fixedW = bookmarkW + (10 + 9 + 8 + 16) + glyphW + statusW + machineW + ticketW + wtW + team.width + stringWidth(age.last) + 1;
     const modelSlack = width - fixedW - MIN_TOPIC_W;
     const modelW = requestedModelW <= modelSlack
         ? requestedModelW
         : modelSlack >= PICKER_MODEL_MIN ? modelSlack : 0;
     const when = timeCell(age, width - fixedW - modelW);
     const topicW = Math.max(MIN_TOPIC_W, width - fixedW - modelW - when.extraW);
-    return (favCell +
+    return (bookmarkCell +
         chalk.white(padToWidth(truncateToWidth(session.shortId, 9), 10)) +
         agentColor(padToWidth(truncateToWidth(session.agent, 8), 9)) +
         chalk.yellow(padToWidth(truncateToWidth(session.version || '-', 7), 8)) +
@@ -2907,9 +2922,9 @@ function printSessionTable(sessions, hiddenCount = 0, tree = false, liveIndex) {
     // column (and its compact labels) is computed the same way the picker does it.
     const showTicket = sessions.some((s) => ticketLabel(s) !== '');
     const cols = pickerColumnsFor(sessions);
-    const favorites = listFavorites();
+    const bookmarks = listBookmarks();
     for (const session of sessions) {
-        console.log(flatSessionRow(session, liveIndex?.get(session.id), showTicket, cols, favorites.has(session.id)));
+        console.log(flatSessionRow(session, liveIndex?.get(session.id), showTicket, cols, bookmarks.has(session.id)));
     }
     const countLine = `${sessions.length} session${sessions.length === 1 ? '' : 's'}.`;
     console.log(chalk.gray(`\n${countLine}`));
@@ -3252,10 +3267,10 @@ export function pickerColumnsFor(sessions) {
         showModel: sessions.some((s) => !!s.model),
         modelWidth: modelColumnWidth(sessions),
         showTicket: sessions.some((s) => ticketLabel(s) !== ''),
-        showFavorite: (() => {
+        showBookmark: (() => {
             // One read of the store per pool, not one per row.
-            const starred = listFavorites();
-            return starred.size > 0 && sessions.some((s) => starred.has(s.id));
+            const bookmarks = listBookmarks();
+            return bookmarks.size > 0 && sessions.some((s) => bookmarks.has(s.id));
         })(),
     };
 }
@@ -3275,7 +3290,7 @@ export function liveHostLabel(a) {
     const viewer = a.viewingIn?.app;
     return viewer && viewer !== a.host ? `${a.host}→${viewer}` : a.host;
 }
-export function formatPickerLabel(s, query, cols = {}, ssh, host = '', favorite = false, live) {
+export function formatPickerLabel(s, query, cols = {}, ssh, host = '', bookmarked = false, live) {
     const agentColor = colorAgent(s.agent);
     const age = sessionAgeParts(s.timestamp, s.lastActivity);
     const project = s.project || '-';
@@ -3317,11 +3332,11 @@ export function formatPickerLabel(s, query, cols = {}, ssh, host = '', favorite
     const ticketW = cols.showTicket ? TICKET_W + 1 : 0;
     const hostW = cols.showHost ? PICKER_HOST_W : 0;
     const wtW = wt ? stringWidth(wt) + 1 : 0;
-    // Within a pool that HAS starred rows the marker holds its 2 cells whether this
-    // row is starred or not, so the columns after it never jog; a pool with none
-    // drops the column entirely (`showFavorite`) and costs nothing.
-    const favW = cols.showFavorite ? 2 : 0;
-    const favCell = cols.showFavorite ? (favorite ? chalk.yellow('★ ') : '  ') : '';
+    // Within a pool that HAS bookmarked rows the marker holds its 2 cells whether
+    // this row is bookmarked or not, so the columns after it never jog; a pool
+    // with none drops the column entirely (`showBookmark`) and costs nothing.
+    const bookmarkW = cols.showBookmark ? 2 : 0;
+    const bookmarkCell = cols.showBookmark ? (bookmarked ? chalk.yellow('★ ') : '  ') : '';
     // The same status word the flat listing shows, so a session that is `orphan`
     // or `crashed` reads that way in the browser too — not only in its preview.
     // Constant width whenever the column is on. `liveStatusCell` already pads its
@@ -3333,10 +3348,10 @@ export function formatPickerLabel(s, query, cols = {}, ssh, host = '', favorite
     const statusCell = cols.showStatus ? (status.cell || ' '.repeat(LIVE_STATUS_W)) : '';
     // Sized against the last-activity label alone; the creation field is then an
     // additive decision made against whatever width is left (see the flat listing).
-    const baseTopicW = terminalWidth() - gutter - favW - statusW - (10 + 9 + 8 + 16) - machineColW - hostW - ticketW - wtW - sshW - team.width - stringWidth(age.last) - 1;
+    const baseTopicW = terminalWidth() - gutter - bookmarkW - statusW - (10 + 9 + 8 + 16) - machineColW - hostW - ticketW - wtW - sshW - team.width - stringWidth(age.last) - 1;
     const when = timeCell(age, baseTopicW);
     const topicW = Math.max(MIN_TOPIC_W, baseTopicW - when.extraW);
-    return (favCell +
+    return (bookmarkCell +
         // Truncated, not just padded: an indexed shortId is always 8 chars, but a
         // live row with no session id is named by its pid or cloud task, which can
         // run past the column and shunt every later column out of alignment.
@@ -4459,6 +4474,7 @@ export function registerSessionsCommands(program) {
         .option('--grok', 'Shorthand for --agent grok')
         .option('--opencode', 'Shorthand for --agent opencode')
         .option('--all', 'Widen every non-status filter to "all": every directory (not just this project) and all time (no window cap). Status filters like --active still compose; -a/--device/--since still narrow their axis.')
+        .option('--bookmarks', 'Show only bookmarked sessions — bookmark them with `*` in the browser or `agents sessions bookmark <id>`')
         .option('--unmanaged', "Also show sessions from your own ~/.<agent> installs (hidden once agents-cli manages that agent)")
         .option('--team, --teams', 'Show team-spawned sessions (hidden by default), grouped by team — each team names its spawner and spawn time, teammates show their mode + handle, and team-flagged spawns with no teammate record sink into a (no team) bucket. --flat/--tree keep the plain inline table')
         .option('--in-team <name>', "Only this team: the session that spawned it plus (with --teams) its teammates. Spans every directory and all time, since a team's worktrees and history sit outside the default window.")
@@ -4492,7 +4508,6 @@ export function registerSessionsCommands(program) {
         .option('--abandoned', 'Show sessions with no transcript progress for the abandonment window (implies --active)')
         .option('--queued', 'Show queued sessions that have not started running (implies --active)')
         .option('--unknown', 'Show sessions whose live state cannot be determined (implies --active)')
-        .option('--favorites', 'Show only favorited sessions — favorite them with `*` in the browser or `agents sessions favorite <id>`')
         .option('--tree', 'Group the listing by directory; drops the id/version columns for readability')
         .option('--flat', 'Plain flat table (one row per session) instead of the grouped project overview')
         .option('--no-live', 'Do not enrich the listing with live status/preview for running sessions')
@@ -4662,7 +4677,7 @@ export function registerSessionsCommands(program) {
     registerSessionsTailCommand(sessionsCmd);
     registerSessionsResumeCommand(sessionsCmd);
     registerSessionsForkCommand(sessionsCmd);
-    registerSessionsFavoriteCommand(sessionsCmd);
+    registerSessionsBookmarkCommand(sessionsCmd);
     registerGoCommand(sessionsCmd);
     registerFocusCommand(sessionsCmd);
     registerReconnectCommand(sessionsCmd);

package/dist/index.js

@@ -1247,7 +1247,7 @@ if (process.env.AGENTS_SKIP_MIGRATION !== '1') {
         // Bumping the suffix re-runs migrations for every user; binary releases that
         // don't change the schema must NOT re-run (they would destroy user content
         // when migration steps overlap with user-authored paths). See issue #20.
-        const sentinelValue = 'v17';
+        const sentinelValue = 'v18';
         let needRun = true;
         try {
             if (fs.existsSync(sentinel) && fs.readFileSync(sentinel, 'utf-8').trim() === sentinelValue) {

package/dist/lib/migrate.js

@@ -1015,6 +1015,11 @@ function migrateRuntimeToHistory() {
         catch { /* best-effort */ }
     }
 }
+/** Rename the session marker store after the product vocabulary changed from
+ * favorite to bookmark. The destination wins if a newer CLI already wrote it. */
+function migrateLegacySessionMarkersToBookmarks() {
+    moveFileOnce(path.join(HISTORY_DIR, 'favorites.json'), path.join(HISTORY_DIR, 'bookmarks.json'));
+}
 /**
  * Restore plugins from the cache bucket back to the user-root.
  *
@@ -2178,6 +2183,7 @@ export async function runMigration() {
     migrateSplitDeviceLocalMeta();
     // Bucket moves: collapse runtime state into ~/.agents/.history and ~/.agents/.cache.
     migrateRuntimeToHistory();
+    migrateLegacySessionMarkersToBookmarks();
     migrateRuntimeToCache();
     // Restore plugins (user-authored) from cache back to user-root. Runs AFTER
     // migrateRuntimeToCache so any legacy plugins/ still at the user-root from