@phnx-labs/agents-cli 1.22.29 → 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 · * star · 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 star it just wrote — and so does a favorite
-    // starred 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 starred: 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 star on this row';
-                const on = toggleFavorite(active.id);
-                // reload so the row's star 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-picker.d.ts

@@ -1,5 +1,6 @@
 import type { SessionEvent, SessionMeta, TodoProgress } from '../lib/session/types.js';
-import { classifyFileChanges } from '../lib/session/digest.js';
+import { classifyFileChanges, changeCounts, toolHistogram, detectTestResult } from '../lib/session/digest.js';
+import { extractArtifacts, extractHooks, extractLinks, extractSkills } from '../lib/session/highlights.js';
 /**
  * Compact checklist tally for list rows and previews (RUSH-2045).
  * Example: `✓6/8 · A5 wiring runner`. Empty string when there is no list.
@@ -31,6 +32,12 @@ export interface SessionPickerConfig {
     /** Lines the caller printed above the prompt (hidden-session footer). */
     linesAbovePrompt?: number;
 }
+export declare function clearPreviewMemoryCacheForTest(): void;
+export declare function loadSessionPreviewDigest(session: SessionMeta): {
+    digest?: SessionPreviewDigest;
+    events: SessionEvent[];
+    error?: string;
+};
 /** Build a cached multi-line preview string for display in the session picker. */
 export declare function buildPreview(session: SessionMeta): string;
 /**
@@ -65,6 +72,31 @@ export declare function extractTiming(session: Pick<SessionMeta, 'timestamp' | '
     lastActiveAgo?: string;
     duration?: string;
 };
+export interface SessionPreviewDigest {
+    schemaVersion: 1;
+    firstUser: string;
+    lastAssistant: string;
+    filesRead: number;
+    toolCalls: number;
+    planFile: string;
+    todos?: TodoProgress;
+    subAgentCount: number;
+    toolTags: string[];
+    changes: ReturnType<typeof changeCounts>;
+    dirs: string[];
+    repos: string[];
+    artifacts: ReturnType<typeof extractArtifacts>;
+    skills: ReturnType<typeof extractSkills>;
+    plugins: string[];
+    hooks: ReturnType<typeof extractHooks>;
+    links: ReturnType<typeof extractLinks>;
+    errorCount: number;
+    firstError?: string;
+    toolHistogram: ReturnType<typeof toolHistogram>;
+    test: ReturnType<typeof detectTestResult>;
+}
+/** Fold a harness-normalized event stream into the stable preview data model. */
+export declare function buildSessionPreviewDigest(events: SessionEvent[], session: SessionMeta): SessionPreviewDigest;
 /**
  * Unique directories the session touched, compact and human-readable.
  * Prefer `session.recentDirectoriesTouched` — the scan records it on the row, so

package/dist/commands/sessions-picker.js

@@ -17,8 +17,10 @@ import { linearIssueUrl } from '../lib/session/linear.js';
 import { extractTodoProgress, WORKTREE_RE } from '../lib/session/state.js';
 import { renderMarkdown } from '../lib/markdown.js';
 import { itemPicker } from '../lib/picker.js';
+import { createMemoryCache } from '../lib/memory-cache.js';
 import { classifyFileChanges, changeCounts, toolHistogram, detectTestResult } from '../lib/session/digest.js';
 import { extractArtifacts, extractHooks, extractLinks, extractRepos, extractSkills } from '../lib/session/highlights.js';
+import { getSessionPlugins, readSessionPreviewCache, writeSessionPreviewCache } from '../lib/session/db.js';
 /** A session whose transcript FILE is on another machine (folded in over the
  * live cross-machine fan-out): its `filePath` is on that peer's disk, so the
  * preview can't parse it locally — it shows metadata + a "resume there" note
@@ -100,11 +102,71 @@ function sanitizeMeta(s) {
         todos,
     };
 }
-const previewCache = new Map();
+const previewCache = createMemoryCache({
+    max: 256,
+    ttlMs: 5 * 60_000,
+});
+function previewCacheKey(session, remote) {
+    let fileStamp = '';
+    if (!remote && session.filePath) {
+        try {
+            const stat = fs.statSync(session.filePath);
+            fileStamp = `${stat.mtimeMs}:${stat.size}`;
+        }
+        catch {
+            fileStamp = 'missing';
+        }
+    }
+    // The transcript stamp invalidates derived activity. Metadata that can change
+    // independently (label/ticket/PR/live scanner enrichment) also rides the key.
+    return JSON.stringify([
+        remote ?? '', session.id, fileStamp, session.lastActivity, session.label,
+        session.topic, session.ticketId, session.prUrl, session.messageCount,
+        session.tokenCount, session.model, session.todos, session.plan,
+        session.recentDirectoriesTouched, session.skillsUsed,
+    ]);
+}
+export function clearPreviewMemoryCacheForTest() {
+    previewCache.clear();
+}
+export function loadSessionPreviewDigest(session) {
+    if (!session.filePath || !fs.existsSync(session.filePath))
+        return { events: [] };
+    const safe = sanitizeMeta(session);
+    let events = [];
+    let sourceStamp;
+    try {
+        sourceStamp = fs.statSync(session.filePath);
+    }
+    catch (err) {
+        return { events, error: sanitizeForTerminal(err?.message ?? String(err)) };
+    }
+    let digest = readSessionPreviewCache(session.id, {
+        fileMtimeMs: sourceStamp.mtimeMs,
+        fileSize: sourceStamp.size,
+    });
+    if (!digest) {
+        try {
+            events = parseSession(session.filePath, session.agent);
+            digest = buildSessionPreviewDigest(events, safe);
+            writeSessionPreviewCache({
+                id: session.id,
+                fileMtimeMs: sourceStamp.mtimeMs,
+                fileSize: sourceStamp.size,
+                preview: digest,
+            });
+        }
+        catch (err) {
+            return { events, error: sanitizeForTerminal(err?.message ?? String(err)) };
+        }
+    }
+    digest.plugins = getSessionPlugins(session.id);
+    return { digest, events };
+}
 /** Build a cached multi-line preview string for display in the session picker. */
 export function buildPreview(session) {
     const remote = transcriptOnPeerOf(session);
-    const cacheKey = remote ? `${remote}:${session.id}` : session.id;
+    const cacheKey = previewCacheKey(session, remote);
     const cached = previewCache.get(cacheKey);
     if (cached)
         return cached;
@@ -129,18 +191,11 @@ export function buildPreview(session) {
         previewCache.set(cacheKey, output);
         return output;
     }
-    let events = [];
-    let parseError;
-    try {
-        events = parseSession(session.filePath, session.agent);
-    }
-    catch (err) {
-        parseError = sanitizeForTerminal(err?.message ?? String(err));
-    }
+    const { digest, events, error: parseError } = loadSessionPreviewDigest(session);
     const header = formatHeader(safe, events);
     const body = parseError
         ? '  ' + chalk.red(`Failed to parse session: ${parseError}`)
-        : formatCompactPreview(events, safe);
+        : formatCompactPreview(digest, safe);
     const output = [header, '', body].filter(Boolean).join('\n');
     previewCache.set(cacheKey, output);
     return output;
@@ -368,7 +423,8 @@ const LAST_RESPONSE_MAX_LINES = 15;
 const LAST_RESPONSE_MAX_LINES_WITH_TODOS = 8;
 const TODOS_MAX_ITEMS = 5;
 const DIRS_TOUCHED_MAX = 5;
-function formatCompactPreview(events, session) {
+/** Fold a harness-normalized event stream into the stable preview data model. */
+export function buildSessionPreviewDigest(events, session) {
     let firstUser = '';
     let lastAssistant = '';
     const filesRead = new Set();
@@ -436,9 +492,35 @@ function formatCompactPreview(events, session) {
     // checklist write); fall back to SessionMeta.todos for rows where the scan/
     // fan-out attached progress but the event stream has no TodoWrite yet.
     const todos = latestTodos ?? session.todos;
-    // Digest signals folded into the preview: change lifecycle, tool mix, tests.
     const changes = classifyFileChanges(events);
     const chg = changeCounts(changes);
+    const errorEvents = events.filter(e => e.type === 'error');
+    return {
+        schemaVersion: 1,
+        firstUser,
+        lastAssistant,
+        filesRead: filesRead.size,
+        toolCalls,
+        planFile,
+        todos,
+        subAgentCount,
+        toolTags: [...toolTags],
+        changes: chg,
+        dirs: directoriesTouched(session, events, changes),
+        repos: extractRepos(events, session.cwd),
+        artifacts: extractArtifacts(changes),
+        skills: extractSkills(events),
+        plugins: getSessionPlugins(session.id),
+        hooks: extractHooks(events),
+        links: extractLinks(events),
+        errorCount: errorEvents.length,
+        firstError: errorEvents[0]?.tool,
+        toolHistogram: toolHistogram(toolCounts, 4),
+        test: detectTestResult(events),
+    };
+}
+function formatCompactPreview(digest, session) {
+    const { firstUser, lastAssistant, filesRead, toolCalls, planFile, todos, subAgentCount, toolTags, changes: chg, dirs, repos, artifacts, skills, plugins, hooks, links, errorCount, firstError, toolHistogram: hist, test, } = digest;
     const lines = [];
     const termWidth = process.stdout.columns || 80;
     // Originating user prompt (first non-system user turn).
@@ -464,12 +546,10 @@ function formatCompactPreview(events, session) {
     // Recent activity = directories touched (not raw tool calls). Prefer a
     // parser-supplied dirsTouched when present; else derive from event paths.
     // Width-capped: a long Dirs line used to wrap and swamp the whole pane.
-    const dirs = directoriesTouched(session, events, changes);
     if (dirs.length) {
         lines.push(chalk.cyan('Dirs:    ') + joinWidthCapped(dirs, termWidth - 12));
     }
     // Repos worked in (basename of each `.git` root under the touched paths).
-    const repos = extractRepos(events, session.cwd);
     if (repos.length) {
         lines.push(chalk.cyan('Repos:   ') + chalk.white(repos.slice(0, 4).join(chalk.gray(' · '))));
     }
@@ -487,8 +567,8 @@ function formatCompactPreview(events, session) {
         ].filter(Boolean).join(' ');
         activity.push(`${parts} ${chalk.gray('changed')}`);
     }
-    if (filesRead.size)
-        activity.push(chalk.gray(`${filesRead.size} read`));
+    if (filesRead)
+        activity.push(chalk.gray(`${filesRead} read`));
     if (toolCalls)
         activity.push(chalk.gray(`${toolCalls} tool${toolCalls === 1 ? '' : 's'}`));
     if (activity.length) {
@@ -496,38 +576,35 @@ function formatCompactPreview(events, session) {
     }
     // Documents the session produced (`.agents/artifacts|plans|reports`, other
     // *.md/*.html creations) — the files a human browses later, named + clickable.
-    const artifacts = extractArtifacts(changes);
     if (artifacts.length) {
         const shown = artifacts.slice(0, 5).map(a => linkPath(a.path, a.basename));
         const more = artifacts.length > 5 ? chalk.gray(` · +${artifacts.length - 5} more`) : '';
         lines.push(chalk.cyan('Artifacts: ') + shown.join(chalk.gray(' · ')) + more);
     }
     // Skills invoked (plugin skills included — they ride the same Skill tool).
-    const skills = extractSkills(events);
     if (skills.length) {
         const shown = skills.slice(0, 5).map(s => chalk.white(s.name) + (s.count > 1 ? chalk.gray(` ×${s.count}`) : ''));
         const more = skills.length > 5 ? chalk.gray(` · +${skills.length - 5} more`) : '';
         lines.push(chalk.cyan('Skills:  ') + shown.join(chalk.gray(' · ')) + more);
     }
+    if (plugins.length) {
+        lines.push(chalk.cyan('Plugins: ') + chalk.white(plugins.slice(0, 5).join(chalk.gray(' · '))));
+    }
     // Hooks fired (Claude transcripts record firings; other harnesses don't).
-    const hooks = extractHooks(events);
     if (hooks.length) {
         const shown = hooks.slice(0, 4).map(h => chalk.white(h.name) + (h.count > 1 ? chalk.gray(` ×${h.count}`) : '') + (h.failed ? chalk.red(` (${h.failed} failed)`) : ''));
         const more = hooks.length > 4 ? chalk.gray(` · +${hooks.length - 4} more`) : '';
         lines.push(chalk.cyan('Hooks:   ') + shown.join(chalk.gray(' · ')) + more);
     }
     // Links mentioned in the conversation — clickable (OSC 8), tracker-classified.
-    const links = extractLinks(events);
     if (links.length) {
         const shown = links.slice(0, 5).map(l => chalk.blue(linkUrl(l.url, l.label)));
         const more = links.length > 5 ? chalk.gray(` · +${links.length - 5} more`) : '';
         lines.push(chalk.cyan('Links:   ') + shown.join(chalk.gray(' · ')) + more);
     }
     // Error tally, mirroring the full summary's Errors section in one line.
-    const errorEvents = events.filter(e => e.type === 'error');
-    if (errorEvents.length) {
-        const first = errorEvents[0].tool || 'unknown';
-        lines.push(chalk.cyan('Errors:  ') + chalk.red(`${errorEvents.length} failure${errorEvents.length === 1 ? '' : 's'}`) + chalk.gray(` — first: ${first}`));
+    if (errorCount) {
+        lines.push(chalk.cyan('Errors:  ') + chalk.red(`${errorCount} failure${errorCount === 1 ? '' : 's'}`) + chalk.gray(` — first: ${firstError || 'unknown'}`));
     }
     const metadata = [
         ...toolTags,
@@ -537,12 +614,10 @@ function formatCompactPreview(events, session) {
         lines.push(chalk.cyan('Meta:     ') + chalk.gray(metadata.join(' · ')));
     }
     // Tool mix (top 4) — what kind of work this was.
-    const hist = toolHistogram(toolCounts, 4);
     if (hist.length) {
         lines.push(chalk.cyan('Tools:    ') + chalk.gray(hist.map(h => `${h.tool} ${h.count}`).join(' · ')));
     }
     // Last test/build verdict.
-    const test = detectTestResult(events);
     if (test?.ok) {
         const bits = [
             test.passed !== undefined ? chalk.green(`${test.passed} pass`) : '',

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

@@ -7,6 +7,9 @@ import { type PickedSession } from './sessions-picker.js';
 import { type ToolSearchEnvelope, type ToolProgramCountEnvelope } from '../lib/session/tool-index.js';
 interface SessionFilterOptions {
     agent?: string;
+    version?: string;
+    /** Internal Commander spelling after index.ts disambiguates root --version. */
+    sessionVersion?: string;
     project?: string;
     all?: boolean;
     teams?: boolean;
@@ -56,8 +59,8 @@ interface SessionsOptions extends SessionFilterOptions {
     abandoned?: boolean;
     queued?: boolean;
     unknown?: boolean;
-    /** Show only favorited (starred) 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;
@@ -94,6 +97,12 @@ interface SessionsOptions extends SessionFilterOptions {
     /** Only sessions that used a skill/command owned by this plugin (#12). */
     plugin?: string;
 }
+type InstalledVersionsForAgent = (agent: SessionAgentId) => string[];
+/**
+ * Treat a positional `agent@version` as a structured filter only when it names
+ * a real installed version. Everything else remains ordinary free-text search.
+ */
+export declare function parseInstalledAgentVersionQuery(query: string | undefined, installedVersions?: InstalledVersionsForAgent): string | undefined;
 /**
  * Strip terminal/harness noise from a preview so the column stays a single line
  * of plain prose: OSC title escapes, CSI/SGR ANSI, and the harness wrapper tags
@@ -390,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;
@@ -431,6 +442,8 @@ export declare function renderSessionPreview(query: string, scope: {
     agent?: string;
     project?: string;
     local?: boolean;
+    hosts?: string[];
+    json?: boolean;
 }): Promise<void>;
 /**
  * The one-line live status banner shown above a session preview: the glyph, the
@@ -442,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;
@@ -476,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
@@ -560,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
@@ -601,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.