@phnx-labs/agents-cli 1.22.29 → 1.22.31

package/dist/commands/sessions.js

@@ -46,17 +46,17 @@ import { getShimsDir } from '../lib/state.js';
 import { fuzzyMatch, FUZZY_PRESETS } from '../lib/fuzzy.js';
 import { itemPicker } from '../lib/picker.js';
 import { resolveSessionAlias } from '../lib/session/actor-sidecar.js';
-import { resolveVersionAliasLoose } from '../lib/versions.js';
+import { listInstalledVersions, resolveVersionAliasLoose } from '../lib/versions.js';
 import { getAgentsInvocation } from '../lib/daemon.js';
 import { sessionRecoveryRunArgs } from '../lib/session/recovery.js';
 import { isInteractiveTerminal, isPromptCancelled } from './utils.js';
-import { sessionPicker, buildPreview, formatTodoCompact, githubRepoUrlFromCwd, } from './sessions-picker.js';
+import { sessionPicker, buildPreview, loadSessionPreviewDigest, formatTodoCompact, githubRepoUrlFromCwd, } from './sessions-picker.js';
 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';
@@ -95,6 +95,44 @@ function applyAgentShorthands(options) {
     if (hit)
         options.agent = hit;
 }
+/**
+ * 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 function parseInstalledAgentVersionQuery(query, installedVersions = (agent) => (agent in AGENTS ? listInstalledVersions(agent) : [])) {
+    const trimmed = query?.trim();
+    if (!trimmed)
+        return undefined;
+    const at = trimmed.indexOf('@');
+    if (at <= 0 || at !== trimmed.lastIndexOf('@') || at === trimmed.length - 1)
+        return undefined;
+    const agentName = trimmed.slice(0, at).toLowerCase();
+    if (!SESSION_AGENTS.includes(agentName))
+        return undefined;
+    const agent = agentName;
+    const version = trimmed.slice(at + 1);
+    return installedVersions(agent).includes(version) ? `${agent}@${version}` : undefined;
+}
+function applyVersionFilters(query, options) {
+    const explicitVersion = options.version ?? options.sessionVersion;
+    if (explicitVersion) {
+        if (!options.agent) {
+            throw new Error('--version requires --agent (for example: --agent claude --version 2.1.181).');
+        }
+        if (options.agent.includes('@')) {
+            throw new Error('Pass the version either in --agent <agent@version> or with --version, not both.');
+        }
+        options.agent = `${options.agent}@${explicitVersion}`;
+    }
+    if (!options.agent) {
+        const positionalFilter = parseInstalledAgentVersionQuery(query);
+        if (positionalFilter) {
+            options.agent = positionalFilter;
+            return undefined;
+        }
+    }
+    return query;
+}
 const CLAUDE_RESUME_MATCH_WINDOW_MS = 10 * 60_000;
 const LOAD_VERBS = ['Loading', 'Scanning', 'Gathering', 'Indexing', 'Reading'];
 const FIND_VERBS = ['Finding', 'Searching', 'Locating', 'Matching'];
@@ -1323,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
@@ -1388,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')
@@ -1454,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 &&
@@ -1619,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));
@@ -1629,29 +1681,108 @@ function canonicalSessionsCommand(query, options) {
 /** 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. */
 export async function renderSessionPreview(query, scope) {
-    const discovered = await discoverSessions({ all: true, cwd: process.cwd(), limit: 5000 });
-    const pool = applyScopeFilters(discovered, scope);
-    const { matches, completeId } = resolveSessionQuery(pool, query);
-    const session = matches[0];
-    if (!session) {
-        // A complete id that missed is not "no match for this text" — say which, and
-        // give the same fleet pointer the render paths give.
-        if (completeId)
-            notFoundByIdMessage(query).forEach(l => console.log(l));
-        else
-            console.log(chalk.gray(`No session matches "${query}".`));
+    let outcome = await resolveSessionMetadataValue(query, scope);
+    // A just-created transcript may not have reached the incremental index yet.
+    // Keep the indexed path hot, but repair a local cold miss once before saying
+    // it does not exist. This also preserves Claude history-alias discovery.
+    if (outcome.kind !== 'resolved'
+        && (!scope.hosts?.length || shouldIncludeLocal(scope.hosts, machineId()))) {
+        const discovered = applyScopeFilters(await discoverSessions({ all: true, cwd: process.cwd(), limit: 5000 }), scope);
+        const localMatches = resolveSessionQuery(discovered, query, { indexFallback: false }).matches
+            .map(session => ({ ...session, machine: session.machine || machineId() }));
+        const exact = localMatches.find(session => selectorAllowsEarlyExit(query)
+            && session.id.toLowerCase() === query.trim().toLowerCase());
+        if (exact)
+            outcome = { kind: 'resolved', session: exact };
+        else if (outcome.kind === 'not-found' && localMatches.length > 0) {
+            outcome = metadataResolveOutcome(localMatches, { sessions: [], unreachable: [] }, query);
+        }
+    }
+    if (outcome.kind === 'partial') {
+        console.error(chalk.red(`Partial session resolution: ${outcome.failedPeers.join(', ')} did not answer.`));
+        console.error(chalk.gray('No preview was rendered because the short ID may be ambiguous on an unreachable peer.'));
+        process.exitCode = 2;
+        return;
+    }
+    if (outcome.kind === 'not-found') {
+        notFoundByIdMessage(query).forEach(l => console.error(l));
+        process.exitCode = 1;
+        return;
+    }
+    if (outcome.kind === 'ambiguous') {
+        console.error(chalk.red(`Multiple sessions match "${query}" across the fleet:`));
+        for (const candidate of outcome.candidates) {
+            const match = candidate.hits[0].session;
+            const machines = candidate.hits.map(hit => hit.machine).join(', ');
+            console.error(chalk.cyan(`  ${match.shortId}  ${match.id}`) + chalk.gray(`  ${machines}  ${match.agent}${match.version ? ` ${match.version}` : ''}`));
+        }
+        console.error(chalk.gray('Pass the full session ID to narrow it down.'));
+        process.exitCode = 1;
+        return;
+    }
+    const session = outcome.session;
+    if (session._remote && session.machine && session.machine !== machineId()) {
+        const args = ['sessions', 'preview', session.id, '--local'];
+        if (scope.json)
+            args.push('--json');
+        const rendered = await runOnPeer(args, session.machine);
+        if (rendered === 'no-target') {
+            console.error(chalk.red(`Session ${session.id} is on ${session.machine}, but that device is not reachable.`));
+            process.exitCode = 1;
+        }
         return;
     }
     // Lead with the live status when the session is still running, so the preview
     // says working / waiting / idle up front — not just the historical transcript.
-    // `--local --preview` is freely combinable with `--local` (RUSH-2118): thread
-    // it through so this probe never dials a remote-host teammate either.
+    // The shared snapshot is accepted for at most 15 seconds. The durable preview
+    // below contains no live status, so a long-lived process can never keep a
+    // stale working/waiting headline in its transcript cache.
     let live;
     try {
-        live = indexActiveBySessionId(await getActiveSessions({ localOnly: scope.local === true })).get(session.id);
+        const loaded = await loadLocalActiveSessions();
+        live = indexActiveBySessionId(loaded.sessions).get(session.id);
     }
     catch { /* plain preview on any probe failure */ }
-    const headline = formatLiveStatusHeadline(live, isFavorite(session.id));
+    if (scope.json) {
+        const { digest, error } = loadSessionPreviewDigest(session);
+        console.log(JSON.stringify({
+            schemaVersion: 1,
+            session: {
+                id: session.id,
+                shortId: session.shortId,
+                agent: session.agent,
+                version: session.version,
+                model: session.model,
+                account: session.account,
+                machine: session.machine ?? machineId(),
+                cwd: session.cwd,
+                project: session.project,
+                gitBranch: session.gitBranch,
+                createdAt: session.timestamp,
+                lastActivity: session.lastActivity,
+                durationMs: session.durationMs,
+                messageCount: session.messageCount,
+                tokenCount: session.tokenCount,
+                costUsd: session.costUsd,
+                label: session.label,
+                ticketId: session.ticketId,
+                prUrl: session.prUrl,
+            },
+            active: live ? {
+                status: live.status,
+                activity: live.activity,
+                awaitingReason: live.awaitingReason,
+                lastActivityMs: live.lastActivityMs,
+                startedAtMs: live.startedAtMs,
+                pid: live.pid,
+                host: live.host,
+            } : null,
+            preview: digest ?? null,
+            error: error ?? null,
+        }));
+        return;
+    }
+    const headline = formatLiveStatusHeadline(live, isBookmarked(session.id));
     if (headline)
         console.log(headline);
     console.log(buildPreview(session));
@@ -1666,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
@@ -1879,6 +2010,14 @@ limitSource) {
     // shorthands fold into --agent, and --device is an alias for --host (both
     // resolve against the same device registry).
     applyAgentShorthands(options);
+    try {
+        query = applyVersionFilters(query, options);
+    }
+    catch (error) {
+        console.error(chalk.red(error instanceof Error ? error.message : String(error)));
+        process.exitCode = 1;
+        return;
+    }
     // --device / --devices both alias --host. A bare `all` / `fleet` sentinel means
     // "search every peer" — which is already the default — so it resolves to no
     // explicit host set rather than erroring on a device literally named "all".
@@ -1984,7 +2123,7 @@ limitSource) {
             console.error(chalk.red('--preview requires a session id or query.'));
             process.exit(1);
         }
-        await renderSessionPreview(query, { agent: options.agent, project: options.project, local: options.local });
+        await renderSessionPreview(query, { agent: options.agent, project: options.project, local: options.local, hosts: options.host });
         return;
     }
     if (liveOnly) {
@@ -2015,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;
         }
@@ -2025,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;
     }
@@ -2040,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,
@@ -2054,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;
     }
@@ -2095,6 +2235,12 @@ limitSource) {
         await renderArtifactsGlobal(searchQuery, options.artifacts ?? false, options.artifact, artifactLookupScope(options.agent, options.project, options.routine));
         return;
     }
+    // A supplied ID is already the lookup key. Resolve it directly from SQLite
+    // and, when needed, the peer indexes before any broad transcript discovery.
+    if (!toolEvidenceMode && searchQuery && looksLikeSessionId(searchQuery)) {
+        await renderOneSession(searchQuery, mode, { agent: options.agent, project: options.project, routine: options.routine, filter: filterOpts, redact: options.redact, local: options.local, hosts: options.host });
+        return;
+    }
     // When the user explicitly asks to render (via mode flag), resolve the
     // query globally so sessions outside the default cwd/30d window are found.
     if (wantsRender && searchQuery) {
@@ -2218,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;
@@ -2528,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 || '-';
@@ -2565,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)) +
@@ -2776,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}`));
@@ -3121,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));
         })(),
     };
 }
@@ -3144,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 || '-';
@@ -3186,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
@@ -3202,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.
@@ -3694,6 +3840,11 @@ export function filterSessionsByQuery(sessions, query) {
     const trimmed = query?.trim().toLowerCase() || '';
     if (!trimmed)
         return sessions;
+    const installedAgentVersion = parseInstalledAgentVersionQuery(trimmed);
+    if (installedAgentVersion) {
+        const { agent, version } = parseAgentFilter(installedAgentVersion);
+        return sessions.filter((session) => session.agent === agent && session.version === version);
+    }
     const terms = trimmed.split(/\s+/).filter(Boolean);
     const contentIndex = searchContentIndex(sessions, trimmed);
     // If the query exactly matches a session label, short-circuit the structural
@@ -3863,6 +4014,53 @@ async function renderArtifactsGlobal(query, listAll, name, scope) {
     }
 }
 async function renderOneSession(query, mode, scope) {
+    if (looksLikeSessionId(query)) {
+        const outcome = await resolveSessionMetadataValue(query, scope);
+        if (outcome.kind === 'partial') {
+            console.error(chalk.red(`Partial session resolution: ${outcome.failedPeers.join(', ')} did not answer.`));
+            process.exit(2);
+        }
+        // An index miss can be a transcript created since the last incremental
+        // scan, or a Claude history alias. Fall through to the established
+        // discovery/history resolver below only on that cold miss.
+        if (outcome.kind === 'ambiguous') {
+            console.error(chalk.red(`Multiple sessions match "${query}" across the fleet:`));
+            for (const candidate of outcome.candidates) {
+                const match = candidate.hits[0].session;
+                const machines = candidate.hits.map(hit => hit.machine).join(', ');
+                console.error(chalk.cyan(`  ${match.shortId}  ${match.id}`) + chalk.gray(`  ${machines}  ${match.agent}${match.version ? ` ${match.version}` : ''}`));
+            }
+            console.error(chalk.gray('Pass the full session ID to narrow it down.'));
+            process.exit(1);
+        }
+        if (outcome.kind === 'resolved') {
+            const resolved = outcome.session;
+            if (resolved._remote && resolved.machine && resolved.machine !== machineId()) {
+                const args = ['sessions', resolved.id, '--local'];
+                const flag = modeFlag(mode);
+                if (flag)
+                    args.push(flag);
+                if (scope.filter.include?.length)
+                    args.push('--include', scope.filter.include.join(','));
+                if (scope.filter.exclude?.length)
+                    args.push('--exclude', scope.filter.exclude.join(','));
+                if (scope.filter.first !== undefined)
+                    args.push('--first', String(scope.filter.first));
+                if (scope.filter.last !== undefined)
+                    args.push('--last', String(scope.filter.last));
+                if (scope.redact === false)
+                    args.push('--no-redact');
+                const rendered = await runOnPeer(args, resolved.machine);
+                if (rendered === 'no-target') {
+                    console.error(chalk.red(`Session ${resolved.id} is on ${resolved.machine}, but that device is not reachable.`));
+                    process.exit(1);
+                }
+                return;
+            }
+            await renderSession(resolved, mode, scope.filter, { redact: scope.redact });
+            return;
+        }
+    }
     const spinner = ora().start();
     const tracker = createScanProgressTracker(FIND_VERBS, 'session', spinner);
     try {
@@ -4070,6 +4268,16 @@ function resolveIndexedMetadataRows(indexed, selector) {
     }
     return resolveSessionQuery(indexed, selector, { indexFallback: false }).matches;
 }
+/**
+ * ID-shaped selectors go straight to SQLite's primary-key/short-id lookup.
+ * Keyword and label selectors still need the broader metadata pool.
+ */
+function indexedRowsForSelector(selector, scope) {
+    const indexed = looksLikeSessionId(selector)
+        ? findSessionsById(selector)
+        : querySessions();
+    return applyScopeFilters(indexed, scope);
+}
 /** Fixed peer argv for the metadata resolver. Scope flags compose identically on
  * every host; `--all` removes the SSH login cwd/time window, not agent/project filters. */
 export function metadataResolveForwardedArgs(selector, scope) {
@@ -4121,7 +4329,7 @@ export function metadataResolveOutcome(localMatches, remote, selector) {
 export async function resolveSessionMetadataValue(selector, scope = {}, deps = { gatherRemoteList }) {
     const localMachine = machineId();
     const includeLocal = !scope.hosts?.length || shouldIncludeLocal(scope.hosts, localMachine);
-    const indexed = includeLocal ? applyScopeFilters(querySessions(), scope) : [];
+    const indexed = includeLocal ? indexedRowsForSelector(selector, scope) : [];
     const localMatches = resolveIndexedMetadataRows(indexed, selector)
         .map(session => ({ ...session, machine: session.machine || localMachine }));
     // A full-UUID local hit resolves with ZERO SSH: a UUID is globally unique, so
@@ -4158,7 +4366,7 @@ export async function resolveSessionMetadataValue(selector, scope = {}, deps = {
 async function resolveSessionMetadata(selector, scope, deps = { gatherRemoteList }) {
     const localMachine = machineId();
     const includeLocal = !scope.hosts?.length || shouldIncludeLocal(scope.hosts, localMachine);
-    const indexed = includeLocal ? applyScopeFilters(querySessions(), scope) : [];
+    const indexed = includeLocal ? indexedRowsForSelector(selector, scope) : [];
     const localMatches = resolveIndexedMetadataRows(indexed, selector)
         .map(session => ({ ...session, machine: session.machine || localMachine }));
     // A peer is already inside gatherRemoteList. Return all local candidates so
@@ -4257,6 +4465,8 @@ export function registerSessionsCommands(program) {
         .addOption(new Option('--resolve-safe-v1 <selector>').hideHelp())
         .description('Find, browse, and read agent conversation transcripts. Live roster: `agents sessions --active` (alias: `agents roster`).')
         .option('-a, --agent <agent>', 'Filter by agent type and version (e.g., claude, codex@0.116.0)')
+        .addOption(new Option('--session-version <version>', 'Internal spelling for the public sessions --version filter')
+        .hideHelp())
         .option('--claude', 'Shorthand for --agent claude')
         .option('--codex', 'Shorthand for --agent codex')
         .option('--kimi', 'Shorthand for --agent kimi')
@@ -4264,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.")
@@ -4297,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 (starred) sessions — star 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')
@@ -4350,6 +4560,10 @@ export function registerSessionsCommands(program) {
       # Search across every directory, not just this project
       agents sessions "topic" --all
 
+      # Filter one installed harness version (equivalent forms)
+      agents sessions claude@2.1.181
+      agents sessions --agent claude --version 2.1.181
+
       # Team-spawned sessions, grouped by team (spawner + spawn time per team,
       # teammate mode/handle per row; team-flagged spawns with no team record
       # in a trailing (no team) bucket)
@@ -4397,6 +4611,7 @@ export function registerSessionsCommands(program) {
         resume [query]          multi-select history → open tabs (or run --resume <id>)
       - The interactive listing and every live-status flag fold in your other online machines automatically (live over SSH, no sync) — each row is labelled by host, this machine first. Use --local to skip the fan-out; single-id lookups stay local.
       - --all is not a device flag: it widens historical directory and time filters. Fleet collection is already the default. A status flag (--working/--idle/--waiting/--orphan/--crashed/--closed/--abandoned/--queued/--unknown) implies --active; combine status flags for a union.
+      - --version <version> requires --agent and is equivalent to --agent <agent@version>.
       - --host runs the query on the remote's own index over SSH (host alias or user@host); repeat or pass several to fan out. SSH access is the only auth.
       - --in-team matches both ends of the lineage: the session that ran 'agents teams create/add', and (with --teams) that team's teammates. In the interactive list, 't' cycles the same filter over the teams in view.
       - --include and --exclude are mutually exclusive.
@@ -4420,10 +4635,49 @@ export function registerSessionsCommands(program) {
         }
         await sessionsAction(query, options, command.getOptionValueSource('limit'));
     });
+    const previewCmd = sessionsCmd
+        .command('preview')
+        .argument('<id>', 'Full session ID or displayed 8-character short ID')
+        .description('Show one rich session card without rendering the full transcript')
+        .option('-a, --agent <agent>', 'Narrow the ID to one agent type/version')
+        .option('-p, --project <name>', 'Narrow the ID to one project')
+        .option('--local', 'Only this machine; do not resolve the ID across the fleet')
+        .option('-H, --host <target...>', 'Resolve only on the named device(s)')
+        .option('--device <target...>', 'Alias for --host')
+        .option('--json', 'Output the session preview as JSON');
+    setHelpSections(previewCmd, {
+        examples: `
+      # Preview by the 8-character ID shown in agents sessions
+      agents sessions preview 407b8dd5
+
+      # A full UUID resolves on the first device that owns it
+      agents sessions preview c70ecdea-6210-4039-9845-246a3a7a9942
+
+      # Stay on this machine or restrict the authoritative lookup to one peer
+      agents sessions preview 407b8dd5 --local
+      agents sessions preview 407b8dd5 --device zion
+    `,
+        notes: `
+      - Full UUIDs are globally unique and may stop the fleet lookup at the first exact hit.
+      - Short IDs wait for every selected device so ambiguity is never hidden.
+      - Active status is refreshed through the bounded live-state TTL; transcript-derived details use the durable session index.
+    `,
+    });
+    previewCmd.action(async (id) => {
+        const options = previewCmd.optsWithGlobals();
+        const hosts = [...(options.host ?? []), ...(options.device ?? [])];
+        await renderSessionPreview(id, {
+            agent: options.agent,
+            project: options.project,
+            local: options.local,
+            hosts: hosts.length > 0 ? hosts : undefined,
+            json: options.json,
+        });
+    });
     registerSessionsTailCommand(sessionsCmd);
     registerSessionsResumeCommand(sessionsCmd);
     registerSessionsForkCommand(sessionsCmd);
-    registerSessionsFavoriteCommand(sessionsCmd);
+    registerSessionsBookmarkCommand(sessionsCmd);
     registerGoCommand(sessionsCmd);
     registerFocusCommand(sessionsCmd);
     registerReconnectCommand(sessionsCmd);