@swarmify/agents-cli 1.11.3 → 1.13.0

package/dist/commands/sessions.js

@@ -1,80 +1,354 @@
+/**
+ * Session discovery, search, and rendering commands.
+ *
+ * Implements `agents sessions` -- the unified interface for finding, browsing,
+ * and reading agent conversation transcripts across Claude, Codex, Gemini,
+ * and OpenCode. Supports interactive picker mode, text/path search, markdown
+ * and JSON rendering, role/turn filtering, artifact inspection, and session
+ * resume via agent-native CLI flags.
+ */
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
+import { spawn } from 'child_process';
 import chalk from 'chalk';
 import ora from 'ora';
-import { search } from '@inquirer/prompts';
 import { SESSION_AGENTS } from '../lib/session/types.js';
-import { discoverSessions, resolveSessionById, searchContentIndex } from '../lib/session/discover.js';
+import { discoverArtifacts, readArtifact, resolveArtifact } from '../lib/session/artifacts.js';
+import { discoverSessions, countSessionsInScope, resolveSessionById, searchContentIndex } from '../lib/session/discover.js';
+import { filterTeamSessions } from '../lib/session/team-filter.js';
 import { parseSession } from '../lib/session/parse.js';
-import { renderTranscript, renderSummary, renderTrace, renderJson } from '../lib/session/render.js';
+import { renderConversationMarkdown, renderSummary, renderSummaryHeader, computeSummaryStats, renderJson, filterEvents, parseRoleList } from '../lib/session/render.js';
 import { renderMarkdown } from '../lib/markdown.js';
 import { colorAgent } from '../lib/agents.js';
-import { isInteractiveTerminal, isPromptCancelled, requireInteractiveSelection } from './utils.js';
-const SESSION_AGENT_FILTER_HELP = `Filter by agent (${SESSION_AGENTS.join(', ')})`;
+import { resolveVersion } from '../lib/versions.js';
+import { isInteractiveTerminal, isPromptCancelled } from './utils.js';
+import { sessionPicker } from './sessions-picker.js';
+const SESSION_AGENT_FILTER_HELP = `Filter by agent, e.g. claude, codex, claude@2.0.65`;
 const CLAUDE_RESUME_MATCH_WINDOW_MS = 10 * 60_000;
-async function listAction(options) {
-    const agent = parseAgentFilter(options.agent);
-    const limit = parseInt(options.limit || '20', 10);
-    const spinner = ora('Scanning sessions...').start();
+const LOAD_VERBS = ['Loading', 'Scanning', 'Gathering', 'Indexing', 'Reading'];
+const FIND_VERBS = ['Finding', 'Searching', 'Locating', 'Matching'];
+/** Build a spinner-backed progress tracker that cycles through verbs while scanning sessions. */
+function createScanProgressTracker(verbs, suffix, spinner) {
+    const counts = new Map();
+    let verbIndex = 0;
+    const render = () => {
+        if (!spinner)
+            return;
+        const verb = verbs[verbIndex % verbs.length];
+        const parts = [];
+        for (const agent of SESSION_AGENTS) {
+            const c = counts.get(agent);
+            if (!c || c.total === 0)
+                continue;
+            parts.push(`${agent} ${c.parsed}/${c.total}`);
+        }
+        const base = `${verb} ${suffix}...`;
+        spinner.text = parts.length > 0 ? `${base} (${parts.join(' · ')})` : base;
+    };
+    const interval = spinner
+        ? setInterval(() => {
+            verbIndex++;
+            render();
+        }, 900)
+        : null;
+    render();
+    return {
+        onProgress: (progress) => {
+            counts.set(progress.agent, { parsed: progress.parsed, total: progress.total });
+            render();
+        },
+        stop: () => {
+            if (interval)
+                clearInterval(interval);
+        },
+    };
+}
+const PICKER_RECENT_COUNT = 15;
+const PICKER_POOL_LIMIT = 200;
+/**
+ * Detect whether a positional argument looks like a filesystem path.
+ * Naked paths (., ./, ../, /, ~) filter sessions by project directory.
+ * Everything else is treated as a search query string.
+ */
+function isPathLike(query) {
+    return query === '.' || query.startsWith('./') || query.startsWith('../')
+        || query.startsWith('/') || query.startsWith('~');
+}
+/**
+ * Resolve a path-like query to an absolute directory path.
+ */
+function resolvePathFilter(query) {
+    const expanded = query.startsWith('~')
+        ? path.join(os.homedir(), query.slice(1))
+        : query;
+    return path.resolve(expanded);
+}
+function formatBytes(n) {
+    if (n < 1024)
+        return `${n} B`;
+    if (n < 1024 * 1024)
+        return `${(n / 1024).toFixed(1)} KB`;
+    return `${(n / (1024 * 1024)).toFixed(1)} MB`;
+}
+async function renderArtifactsForSession(session, listAll, name) {
+    const artifacts = discoverArtifacts(session);
+    if (name !== undefined) {
+        const artifact = resolveArtifact(artifacts, name);
+        if (!artifact) {
+            console.error(chalk.red(`No artifact matching "${name}" in session ${session.shortId}.`));
+            if (artifacts.length > 0) {
+                console.error(chalk.gray('Available artifacts:'));
+                for (const a of artifacts) {
+                    console.error(chalk.gray(`  ${a.path}`));
+                }
+            }
+            process.exit(1);
+        }
+        if (!artifact.exists) {
+            console.error(chalk.red(`Artifact exists in session history but the file is no longer on disk: ${artifact.path}`));
+            process.exit(1);
+        }
+        process.stdout.write(readArtifact(artifact));
+        return;
+    }
+    if (artifacts.length === 0) {
+        console.log(chalk.gray('No file-write artifacts found in this session.'));
+        return;
+    }
+    const agentColor = colorAgent(session.agent);
+    console.log('');
+    console.log(agentColor(session.agent) +
+        chalk.gray(` · ${session.shortId} · ${formatRelativeTime(session.timestamp)}`));
+    console.log(chalk.gray('─'.repeat(72)));
+    for (const a of artifacts) {
+        const exists = a.exists ? chalk.green('yes') : chalk.red('no');
+        const size = a.exists && a.sizeBytes !== undefined ? chalk.cyan(formatBytes(a.sizeBytes)) : chalk.gray('-');
+        const tool = chalk.yellow(padRight(a.tool, 10));
+        const when = chalk.gray(formatRelativeTime(a.timestamp));
+        const p = chalk.white(a.path);
+        console.log(`  ${exists}  ${size.padEnd(10)}  ${tool}  ${when.padEnd(16)}  ${p}`);
+    }
+    console.log(chalk.gray(`\n${artifacts.length} artifact${artifacts.length !== 1 ? 's' : ''}.`));
+}
+/** Main action handler for `agents sessions`. Routes to picker, table, or single-session render. */
+async function sessionsAction(query, options) {
+    let filterOpts;
+    try {
+        filterOpts = buildFilterOptions(options);
+    }
+    catch (err) {
+        console.error(chalk.red(err.message));
+        process.exit(1);
+    }
+    const { agent, version } = parseAgentFilter(options.agent);
+    // Path-like queries filter by project directory instead of text search.
+    let pathFilter;
+    let searchQuery;
+    if (query && isPathLike(query)) {
+        const resolved = resolvePathFilter(query);
+        if (!fs.existsSync(resolved)) {
+            console.log(chalk.yellow(`Path not found: ${resolved}`));
+            console.log(chalk.gray('Did you mean to search? Use quotes: agents sessions "' + query + '"'));
+            return;
+        }
+        pathFilter = fs.realpathSync(resolved);
+    }
+    else {
+        searchQuery = query;
+    }
+    // Artifact flags require a session query.
+    if ((options.artifacts || options.artifact !== undefined) && !query) {
+        console.error(chalk.red('--artifacts and --artifact require a session ID or query.'));
+        process.exit(1);
+    }
+    const mode = resolveViewMode(options, filterOpts);
+    // --markdown or any filter flag forces single-session render.
+    const wantsRender = mode === 'markdown' || hasAnyFilter(filterOpts);
+    // Artifact-list or artifact-read paths: widen scope and resolve session globally.
+    if ((options.artifacts || options.artifact !== undefined) && searchQuery) {
+        await renderArtifactsGlobal(searchQuery, options.artifacts ?? false, options.artifact, { agent: options.agent, project: options.project });
+        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) {
+        await renderOneSession(searchQuery, mode, { agent: options.agent, project: options.project, filter: filterOpts });
+        return;
+    }
+    // Interactive picker loads a deep pool but shows only recent sessions
+    // until the user starts typing. Non-interactive/JSON uses the explicit limit.
+    const isInteractive = !options.json && isInteractiveTerminal();
+    const limit = parseInt(options.limit || (isInteractive ? String(PICKER_POOL_LIMIT) : '50'), 10);
+    const since = options.since ?? (isInteractive && !options.all ? '30d' : undefined);
+    const spinner = options.json ? null : ora().start();
+    const tracker = createScanProgressTracker(LOAD_VERBS, 'sessions', spinner);
     try {
-        const sessions = await discoverSessions({
+        // Team-origin filter is pushed down to SQL so the LIMIT applies AFTER it.
+        // Without this, a dev dir with heavy SDK spawn activity (Task subagents,
+        // `agents run`, team agents) can fill the top-N window entirely with
+        // hidden rows and make real CLI sessions appear to vanish.
+        const scope = {
             agent,
-            all: options.all,
+            version,
+            all: pathFilter ? undefined : options.all,
             cwd: process.cwd(),
+            cwdPrefix: pathFilter,
             project: options.project,
-            limit,
-            since: options.since,
+            since,
             until: options.until,
+        };
+        let sessions = await discoverSessions({
+            ...scope,
+            limit,
+            excludeTeamOrigin: !options.teams,
+            onProgress: tracker.onProgress,
         });
-        spinner.stop();
+        tracker.stop();
+        spinner?.stop();
+        // Version filter is pushed down to SQL via scope.version above; no
+        // post-filter needed. Defensive: the team-origin SQL filter covers the
+        // ~100% case, but classifyTeamSession also recognizes sessions with a
+        // meta.json in ~/.agents/teams/agents whose is_team_origin flag was
+        // never set (legacy rows). Keep the in-memory pass so those are still
+        // enriched/hidden.
+        const { visible: visibleSessions } = filterTeamSessions(sessions, !!options.teams);
+        sessions = visibleSessions;
+        const hiddenCount = options.teams
+            ? 0
+            : countSessionsInScope({ ...scope, onlyTeamOrigin: true });
+        // Smart ID routing: a bare query that resolves to one session renders
+        // directly. If nothing matches in the scoped window and the query looks
+        // like a session ID, widen to global scope (incl. Claude /resume history).
+        if (searchQuery) {
+            const idMatches = resolveSessionById(sessions, searchQuery);
+            if (idMatches.length === 1) {
+                await renderSession(idMatches[0], mode, filterOpts);
+                return;
+            }
+            if (idMatches.length === 0 && looksLikeSessionId(searchQuery)) {
+                await renderOneSession(searchQuery, mode, { agent: options.agent, project: options.project, filter: filterOpts });
+                return;
+            }
+        }
+        if (options.json) {
+            const filtered = searchQuery ? filterSessionsByQuery(sessions, searchQuery) : sessions;
+            const serializable = filtered.map(s => {
+                const { _matchedTerms, _bm25Score, ...rest } = s;
+                return rest;
+            });
+            process.stdout.write(JSON.stringify(serializable, null, 2) + '\n');
+            return;
+        }
         if (sessions.length === 0) {
-            console.log(chalk.gray(formatNoSessionsMessage(options.all, false, options.project)));
+            if (pathFilter) {
+                console.log(chalk.gray(`No sessions found for ${pathFilter}.`));
+            }
+            else {
+                console.log(chalk.gray(formatNoSessionsMessage(options.all, options.project)));
+            }
+            if (hiddenCount > 0) {
+                console.log(chalk.gray(formatTeamHiddenFooter(hiddenCount)));
+            }
             return;
         }
-        if (shouldUseFilteredSessionSearch(options)) {
-            const picked = await pickSession(sessions, formatSearchMessage(options));
+        if (isInteractiveTerminal()) {
+            const message = pathFilter
+                ? `Search sessions (${path.basename(pathFilter)}):`
+                : formatSearchMessage(options);
+            const picked = await pickSessionInteractive(sessions, message, searchQuery, hiddenCount);
             if (picked) {
-                await renderSession(picked, 'summary');
+                await handlePickedSession(picked);
                 return;
             }
+            return;
         }
-        // Print header
-        console.log(chalk.gray(padRight('ID', 10) +
-            padRight('Account', 20) +
-            padRight('Agent', 18) +
-            padRight('Project', 16) +
-            padRight('When', 14) +
-            padRight('Msgs', 8) +
-            padRight('Tokens', 10) +
-            'Topic'));
-        for (const session of sessions) {
-            const agentColor = colorAgent(session.agent);
-            const when = formatRelativeTime(session.timestamp);
-            const project = session.project || '-';
-            const account = session.account || '';
-            const agentLabel = session.version
-                ? `${session.agent}@${session.version}`
-                : session.agent;
-            const topic = session.topic || '';
-            console.log(chalk.white(padRight(session.shortId, 10)) +
-                chalk.gray(padRight(truncate(account, 18), 20)) +
-                agentColor(padRight(truncate(agentLabel, 16), 18)) +
-                chalk.cyan(padRight(truncate(project, 14), 16)) +
-                chalk.gray(padRight(when, 14)) +
-                chalk.gray(padRight(formatCompactMetric(session.messageCount), 8)) +
-                chalk.gray(padRight(formatCompactMetric(session.tokenCount), 10)) +
-                chalk.white(truncate(topic, 40)));
-        }
-        console.log(chalk.gray(`\n${sessions.length} session${sessions.length === 1 ? '' : 's'}. Use 'agents sessions view <id>' to read.`));
+        // Non-interactive fallback (piped output)
+        const filtered = searchQuery ? filterSessionsByQuery(sessions, searchQuery) : sessions;
+        printSessionTable(filtered, hiddenCount);
     }
     catch (err) {
-        spinner.stop();
+        tracker.stop();
+        spinner?.stop();
         console.error(chalk.red(`Failed to discover sessions: ${err.message}`));
         process.exit(1);
     }
 }
-async function renderSession(session, mode) {
+function looksLikeSessionId(query) {
+    return /^[0-9a-f-]{6,}$/i.test(query.trim());
+}
+function teamTag(session) {
+    const origin = session.teamOrigin;
+    if (!origin)
+        return '';
+    const parts = [origin.handle, origin.mode].filter(Boolean).join(' · ');
+    return parts ? `[${parts}] ` : '[team] ';
+}
+function printSessionTable(sessions, hiddenCount = 0) {
+    for (const session of sessions) {
+        const agentColor = colorAgent(session.agent);
+        const when = formatRelativeTime(session.timestamp);
+        const project = session.project || '-';
+        const tag = teamTag(session);
+        const label = session.label;
+        const topic = tag ? `${tag}${session.topic ?? ''}` : session.topic;
+        const versionStr = session.version || '-';
+        console.log(chalk.white(padRight(session.shortId, 10)) +
+            agentColor(padRight(truncate(session.agent, 8), 9)) +
+            chalk.yellow(padRight(truncate(versionStr, 7), 8)) +
+            chalk.cyan(padRight(truncate(project, 14), 16)) +
+            renderTopicCell(label, topic, '', 48, 50) +
+            chalk.gray(when));
+    }
+    const countLine = `${sessions.length} session${sessions.length === 1 ? '' : 's'}.`;
+    console.log(chalk.gray(`\n${countLine}`));
+    if (hiddenCount > 0) {
+        console.log(chalk.gray(formatTeamHiddenFooter(hiddenCount)));
+    }
+}
+function buildFilterOptions(options) {
+    const opts = {};
+    if (options.include)
+        opts.include = parseRoleList(options.include, '--include');
+    if (options.exclude)
+        opts.exclude = parseRoleList(options.exclude, '--exclude');
+    if (opts.include && opts.exclude) {
+        throw new Error('--include and --exclude are mutually exclusive');
+    }
+    const parseCount = (raw, flag) => {
+        const n = Number(raw);
+        if (!Number.isFinite(n) || !Number.isInteger(n) || n <= 0) {
+            throw new Error(`${flag} expects a positive integer, got "${raw}"`);
+        }
+        return n;
+    };
+    if (options.first !== undefined)
+        opts.first = parseCount(options.first, '--first');
+    if (options.last !== undefined)
+        opts.last = parseCount(options.last, '--last');
+    if (opts.first !== undefined && opts.last !== undefined) {
+        throw new Error('--first and --last are mutually exclusive');
+    }
+    return opts;
+}
+function hasAnyFilter(opts) {
+    return !!(opts.include?.length || opts.exclude?.length || opts.first !== undefined || opts.last !== undefined);
+}
+/**
+ * Default is summary. Any explicit format flag wins. When filters are present
+ * without a format, default to markdown since summary is an aggregate view
+ * that filters don't meaningfully narrow.
+ */
+function resolveViewMode(options, filters) {
+    if (options.markdown)
+        return 'markdown';
+    if (options.json)
+        return 'json';
+    if (hasAnyFilter(filters))
+        return 'markdown';
+    return 'summary';
+}
+async function renderSession(session, mode, filters) {
     // OpenCode stores sessions in SQLite; filePath is "db_path#session_id"
     const realPath = session.filePath.split('#')[0];
     if (!fs.existsSync(realPath)) {
@@ -89,81 +363,115 @@ async function renderSession(session, mode) {
         console.log(chalk.gray(`Time: ${session.timestamp}`));
         return;
     }
-    // Session header
-    const agentColor = colorAgent(session.agent);
-    console.log('');
-    console.log(agentColor(session.agent) +
-        (session.version ? chalk.yellow(` ${session.version}`) : '') +
-        (session.project ? chalk.cyan(` ${session.project}`) : '') +
-        chalk.gray(` ${formatRelativeTime(session.timestamp)}`) +
-        (session.account ? chalk.gray(` (${session.account})`) : ''));
-    console.log(chalk.gray('─'.repeat(60)));
     const spinner = ora(`Parsing ${session.agent} session...`).start();
-    const events = parseSession(session.filePath, session.agent);
+    let events = parseSession(session.filePath, session.agent);
     spinner.stop();
-    let output;
-    switch (mode) {
-        case 'transcript':
-            output = renderTranscript(events);
-            break;
-        case 'summary':
-            output = renderMarkdown(renderSummary(events));
-            break;
-        case 'trace':
-            output = renderMarkdown(renderTrace(events));
-            break;
-        case 'json':
-            output = renderJson(events);
-            break;
-    }
-    process.stdout.write(output);
-}
-function formatPickerLabel(s) {
+    events = filterEvents(events, filters);
+    const agentColor = colorAgent(session.agent);
+    console.log('');
+    if (mode === 'summary') {
+        const stats = computeSummaryStats(events);
+        const modelStr = stats.models.length > 0 ? chalk.yellow(`  ${stats.models.join(', ')}`) : '';
+        const branchStr = session.gitBranch ? chalk.gray(` (${session.gitBranch})`) : '';
+        const absTime = formatAbsoluteTime(session.timestamp);
+        console.log(agentColor(session.agent) +
+            (session.version ? chalk.yellow(` ${session.version}`) : '') +
+            modelStr +
+            (session.project ? chalk.cyan(`  ${session.project}`) + branchStr : branchStr) +
+            chalk.gray(`  ${absTime} (${formatRelativeTime(session.timestamp)})`) +
+            (session.account ? chalk.gray(` · ${session.account}`) : ''));
+        const statsLine = renderSummaryHeader(stats);
+        if (statsLine)
+            console.log(chalk.gray(statsLine));
+        console.log(chalk.gray('─'.repeat(60)));
+        process.stdout.write(renderSummary(events, session.cwd));
+        return;
+    }
+    if (mode === 'markdown') {
+        console.log(agentColor(session.agent) +
+            (session.version ? chalk.yellow(` ${session.version}`) : '') +
+            (session.project ? chalk.cyan(` ${session.project}`) : '') +
+            chalk.gray(` ${formatRelativeTime(session.timestamp)}`) +
+            (session.account ? chalk.gray(` (${session.account})`) : ''));
+        console.log(chalk.gray('─'.repeat(60)));
+        process.stdout.write(renderMarkdown(renderConversationMarkdown(events)));
+        return;
+    }
+    // json — no header, raw events only (pipeable)
+    process.stdout.write(renderJson(events));
+}
+function renderTopicCell(label, topic, query, visibleWidth, paddedWidth) {
+    const lbl = (label ?? '').trim();
+    const tpc = (topic ?? '').trim();
+    const sep = ' · ';
+    const raw = lbl && tpc ? `${lbl}${sep}${tpc}` : (lbl || tpc);
+    const visible = truncate(raw, visibleWidth);
+    const padding = ' '.repeat(Math.max(0, paddedWidth - visible.length));
+    const labelEnd = lbl ? Math.min(lbl.length, visible.length) : 0;
+    let matchStart = -1, matchEnd = -1;
+    const q = query.trim().toLowerCase();
+    if (q) {
+        const lower = visible.toLowerCase();
+        for (const term of q.split(/\s+/).filter(Boolean)) {
+            const idx = lower.indexOf(term);
+            if (idx !== -1) {
+                matchStart = idx;
+                matchEnd = idx + term.length;
+                break;
+            }
+        }
+    }
+    const cuts = new Set([0, labelEnd, visible.length]);
+    if (matchStart >= 0) {
+        cuts.add(matchStart);
+        cuts.add(matchEnd);
+    }
+    const boundaries = [...cuts].sort((a, b) => a - b);
+    let out = '';
+    for (let i = 0; i < boundaries.length - 1; i++) {
+        const s = boundaries[i], e = boundaries[i + 1];
+        if (s >= e)
+            continue;
+        const text = visible.slice(s, e);
+        const isLabel = s < labelEnd;
+        const isMatch = matchStart >= 0 && s >= matchStart && e <= matchEnd;
+        out += (isMatch || isLabel) ? chalk.bold.white(text) : chalk.white(text);
+    }
+    return out + padding;
+}
+function formatPickerLabel(s, query) {
     const agentColor = colorAgent(s.agent);
     const when = formatRelativeTime(s.timestamp);
     const project = s.project || '-';
-    const account = s.account || '';
-    const agentLabel = s.version ? `${s.agent}@${s.version}` : s.agent;
-    const topic = s.topic || '';
-    const matchTerms = s._matchedTerms;
-    // Append matched terms badge
-    const matchBadge = matchTerms && matchTerms.length > 0
-        ? chalk.yellow(` [${matchTerms.join(', ')}]`)
-        : '';
+    const tag = teamTag(s);
+    const label = s.label;
+    const topic = tag ? `${tag}${s.topic ?? ''}` : s.topic;
+    const versionStr = s.version || '-';
     return (chalk.white(padRight(s.shortId, 10)) +
-        chalk.gray(padRight(truncate(account, 18), 20)) +
-        agentColor(padRight(truncate(agentLabel, 16), 18)) +
+        agentColor(padRight(truncate(s.agent, 8), 9)) +
+        chalk.yellow(padRight(truncate(versionStr, 7), 8)) +
         chalk.cyan(padRight(truncate(project, 14), 16)) +
-        chalk.gray(padRight(when, 14)) +
-        chalk.gray(padRight(formatCompactMetric(s.messageCount), 8)) +
-        chalk.gray(padRight(formatCompactMetric(s.tokenCount), 10)) +
-        chalk.white(truncate(topic, 30)) +
-        matchBadge);
+        renderTopicCell(label, topic, query, 48, 50) +
+        chalk.gray(when));
 }
-async function pickSession(sessions, message = 'Search sessions:') {
+async function pickSessionInteractive(sessions, message = 'Search sessions:', initialSearch, hiddenCount = 0) {
+    if (hiddenCount > 0) {
+        console.log(chalk.gray(formatTeamHiddenFooter(hiddenCount)));
+    }
     try {
-        return await search({
+        return await sessionPicker({
             message,
-            pageSize: 12,
-            source: async (input) => {
-                const matches = filterSessionsByQuery(sessions, input).slice(0, 30);
-                if (matches.length === 0) {
-                    return [{
-                            name: input?.trim()
-                                ? `No sessions found for "${input.trim()}"`
-                                : 'No sessions found',
-                            value: null,
-                            disabled: 'Keep typing',
-                        }];
-                }
-                return matches.map(s => ({
-                    name: formatPickerLabel(s),
-                    value: s,
-                    description: formatSearchDescription(s),
-                    short: s.shortId,
-                }));
+            sessions,
+            filter: (query) => {
+                // No query: show the full pool (picker viewport still paginates via pageSize).
+                // Typing: search the full pool.
+                if (!query.trim())
+                    return sessions;
+                return filterSessionsByQuery(sessions, query);
             },
-            validate: (value) => value ? true : 'No matching sessions.',
+            labelFor: (s, query) => formatPickerLabel(s, query),
+            pageSize: PICKER_RECENT_COUNT,
+            initialSearch,
         });
     }
     catch (err) {
@@ -172,16 +480,81 @@ async function pickSession(sessions, message = 'Search sessions:') {
         throw err;
     }
 }
+async function handlePickedSession(picked) {
+    if (picked.action === 'view') {
+        await renderSession(picked.session, 'summary', {});
+        return;
+    }
+    const cwd = picked.session.cwd && fs.existsSync(picked.session.cwd)
+        ? picked.session.cwd
+        : process.cwd();
+    const activeVersion = resolveVersion(picked.session.agent, cwd) ?? undefined;
+    const resume = buildResumeCommand(picked.session, activeVersion);
+    if (!resume) {
+        console.log(chalk.yellow(`Resume is not supported for ${picked.session.agent} sessions yet. Showing summary instead.`));
+        await renderSession(picked.session, 'summary', {});
+        return;
+    }
+    if (picked.session.version && activeVersion && picked.session.version !== activeVersion) {
+        console.log(chalk.gray(`Cross-version handoff: session is ${picked.session.agent} ${picked.session.version}, ` +
+            `default is ${activeVersion}. Starting fresh and passing /continue so the new agent ` +
+            `reads the prior transcript via 'agents sessions'.`));
+    }
+    console.log(chalk.gray(`Resuming: ${resume.join(' ')} (cwd: ${cwd})`));
+    await new Promise((resolve) => {
+        const child = spawn(resume[0], resume.slice(1), {
+            cwd,
+            stdio: 'inherit',
+            shell: false,
+        });
+        child.on('error', (err) => {
+            console.error(chalk.red(`Failed to launch ${resume[0]}: ${err.message}`));
+            if (err.code === 'ENOENT') {
+                console.error(chalk.gray(`Make sure '${resume[0]}' is on your PATH.`));
+            }
+            resolve();
+        });
+        child.on('close', () => resolve());
+    });
+}
+/**
+ * Build the shell command that resumes a picked session.
+ *
+ * Cross-version handoff: when the session was created on a different version
+ * than the one the shim will launch (activeVersion), the session file lives in
+ * the other version's isolated home and `--resume <id>` would silently fail to
+ * find it. Fall back to a fresh session seeded with `/continue <id>`, which is
+ * wired (~/.claude/commands/continue.md) to read the prior transcript via
+ * `agents sessions <id>` — that reader is version-agnostic.
+ */
+export function buildResumeCommand(session, activeVersion) {
+    const versionMismatch = !!(session.version && activeVersion && session.version !== activeVersion);
+    switch (session.agent) {
+        case 'claude':
+            if (versionMismatch)
+                return ['claude', `/continue ${session.id}`];
+            return ['claude', '--resume', session.id];
+        case 'codex':
+            if (versionMismatch)
+                return ['codex', `/continue ${session.id}`];
+            return ['codex', 'resume', session.id];
+        case 'opencode':
+            return ['opencode', '--session', session.id];
+        case 'gemini':
+        case 'openclaw':
+            return null;
+    }
+}
 function parseAgentFilter(agentName) {
-    const agent = agentName;
-    if (agent && !SESSION_AGENTS.includes(agent)) {
-        console.error(chalk.red(`Unknown agent: ${agent}. Use: ${SESSION_AGENTS.join(', ')}`));
+    if (!agentName)
+        return {};
+    const [name, version] = agentName.split('@', 2);
+    const agent = name;
+    if (!SESSION_AGENTS.includes(agent)) {
+        console.error(chalk.red(`Unknown agent: ${name}. Use: ${SESSION_AGENTS.join(', ')}`));
         process.exit(1);
     }
-    return agent;
-}
-function shouldUseFilteredSessionSearch(options) {
-    return isInteractiveTerminal() && Boolean(options.agent || options.project);
+    return { agent, version };
 }
 function formatSearchMessage(options) {
     const filters = [];
@@ -193,15 +566,21 @@ function formatSearchMessage(options) {
         return 'Search sessions:';
     return `Search sessions (${filters.join(', ')}):`;
 }
-function formatSearchDescription(session) {
-    return [session.id, session.cwd].filter(Boolean).join('  ');
-}
-function filterSessionsByQuery(sessions, query) {
+/** Filter and rank sessions by a multi-term search query across metadata and content. */
+export function filterSessionsByQuery(sessions, query) {
     const trimmed = query?.trim().toLowerCase() || '';
     if (!trimmed)
         return sessions;
     const terms = trimmed.split(/\s+/).filter(Boolean);
     const contentIndex = searchContentIndex(sessions, trimmed);
+    // If the query exactly matches a session label, short-circuit the structural
+    // scorer (which would otherwise surface every session whose topic happens to
+    // contain the same words) and return only the label hits.
+    const EXACT_LABEL_SCORE = 1_000_000;
+    const exactLabelHits = [...contentIndex.values()].filter(s => (s._bm25Score ?? 0) >= EXACT_LABEL_SCORE);
+    if (exactLabelHits.length > 0) {
+        return exactLabelHits.sort((a, b) => (b._bm25Score ?? 0) - (a._bm25Score ?? 0));
+    }
     return sessions
         .map(session => ({ session, score: scoreSessionQuery(session, terms) }))
         .filter(entry => {
@@ -274,102 +653,131 @@ function scoreSessionQuery(session, terms) {
     }
     return score;
 }
-async function viewAction(idQuery, options) {
-    // Default to summary, opt into full transcript
-    let mode = 'summary';
-    if (options.transcript)
-        mode = 'transcript';
-    else if (options.trace)
-        mode = 'trace';
-    else if (options.json)
-        mode = 'json';
-    const agent = parseAgentFilter(options.agent);
-    const spinner = ora('Finding session...').start();
+/**
+ * Narrow a session list by --project and --agent before search resolution.
+ * Without this, a query like "scoped search" could match sessions in BOTH
+ * the project you specified AND elsewhere, producing an ambiguity error
+ * even though the user already pointed at the correct scope.
+ */
+function applyScopeFilters(sessions, scope) {
+    let filtered = sessions;
+    if (scope.project) {
+        const projectQuery = scope.project.toLowerCase();
+        filtered = filtered.filter((s) => {
+            const project = (s.project || '').toLowerCase();
+            const cwd = (s.cwd || '').toLowerCase();
+            return project.includes(projectQuery) || cwd.includes(projectQuery);
+        });
+    }
+    if (scope.agent) {
+        // Accept "claude" or "claude@2.1.112". Version suffix narrows further.
+        const [wantAgent, wantVersion] = scope.agent.split('@');
+        filtered = filtered.filter((s) => {
+            if (s.agent !== wantAgent)
+                return false;
+            if (wantVersion && s.version !== wantVersion)
+                return false;
+            return true;
+        });
+    }
+    return filtered;
+}
+async function renderArtifactsGlobal(query, listAll, name, scope) {
+    const spinner = ora().start();
+    const tracker = createScanProgressTracker(FIND_VERBS, 'session', spinner);
     try {
-        const allSessions = await discoverSessions({
-            agent,
-            all: Boolean(idQuery) || options.all,
+        const discovered = await discoverSessions({
+            all: true,
             cwd: process.cwd(),
-            project: options.project,
             limit: 5000,
-            since: options.since,
-            until: options.until,
+            onProgress: tracker.onProgress,
         });
-        let session;
-        if (!idQuery) {
-            // No ID provided -- show interactive picker
+        tracker.stop();
+        const allSessions = applyScopeFilters(discovered, scope);
+        const matches = resolveSessionById(allSessions, query);
+        const queryMatches = matches.length > 0 ? matches : filterSessionsByQuery(allSessions, query);
+        if (queryMatches.length === 0) {
             spinner.stop();
-            if (allSessions.length === 0) {
-                console.log(chalk.gray(formatNoSessionsMessage(options.all, true)));
-                return;
-            }
-            if (!isInteractiveTerminal()) {
-                requireInteractiveSelection('Selecting a session to view', [
-                    'agents sessions list',
-                    'agents sessions view <id>',
-                ]);
+            console.error(chalk.red(`No session found matching: ${query}`));
+            process.exit(1);
+        }
+        if (queryMatches.length > 1) {
+            spinner.stop();
+            console.error(chalk.red(`Multiple sessions match "${query}":`));
+            for (const m of queryMatches.slice(0, 10)) {
+                console.error(chalk.cyan(`  ${m.shortId}  ${m.id}  ${m.label ?? m.topic ?? ''}`));
             }
-            const picked = await pickSession(allSessions, formatSearchMessage(options));
-            if (!picked)
-                return;
-            session = picked;
+            console.error(chalk.gray('Pass a longer ID to narrow it down.'));
+            process.exit(1);
         }
-        else {
-            const matches = resolveSessionById(allSessions, idQuery);
-            let queryMatches = matches.length > 0 ? matches : filterSessionsByQuery(allSessions, idQuery);
-            // Content search fallback when no title/topic/project matches
-            if (queryMatches.length === 0) {
-                const contentResults = searchContentIndex(allSessions, idQuery);
-                if (contentResults.size > 0) {
-                    const matchedSessions = Array.from(contentResults.values())
-                        .sort((a, b) => (b._bm25Score ?? 0) - (a._bm25Score ?? 0));
-                    if (matchedSessions.length === 1) {
-                        session = matchedSessions[0];
-                        console.log(chalk.gray(`Found by content match (terms: ${matchedSessions[0]._matchedTerms?.join(', ')})`));
-                    }
-                    else {
-                        queryMatches = matchedSessions;
-                    }
+        spinner.stop();
+        await renderArtifactsForSession(queryMatches[0], listAll, name);
+    }
+    catch (err) {
+        if (isPromptCancelled(err))
+            return;
+        tracker.stop();
+        spinner.stop();
+        console.error(chalk.red(`Failed to read session: ${err.message}`));
+        process.exit(1);
+    }
+}
+async function renderOneSession(query, mode, scope) {
+    const spinner = ora().start();
+    const tracker = createScanProgressTracker(FIND_VERBS, 'session', spinner);
+    try {
+        const discovered = await discoverSessions({
+            all: true,
+            cwd: process.cwd(),
+            limit: 5000,
+            onProgress: tracker.onProgress,
+        });
+        tracker.stop();
+        const allSessions = applyScopeFilters(discovered, scope);
+        let session;
+        const matches = resolveSessionById(allSessions, query);
+        let queryMatches = matches.length > 0 ? matches : filterSessionsByQuery(allSessions, query);
+        if (queryMatches.length === 0) {
+            const contentResults = searchContentIndex(allSessions, query);
+            if (contentResults.size > 0) {
+                const matchedSessions = Array.from(contentResults.values())
+                    .sort((a, b) => (b._bm25Score ?? 0) - (a._bm25Score ?? 0));
+                if (matchedSessions.length === 1) {
+                    session = matchedSessions[0];
+                }
+                else {
+                    queryMatches = matchedSessions;
                 }
             }
-            if (queryMatches.length === 0) {
-                spinner.stop();
-                const historyEntry = findClaudeHistoryEntry(idQuery);
-                if (historyEntry) {
-                    const resumeMatch = resolveClaudeHistoryEntryToTranscript(historyEntry, allSessions);
-                    if (resumeMatch) {
-                        session = resumeMatch.session;
-                        console.log(chalk.gray(`Resolved Claude history entry ${idQuery} to transcript ${resumeMatch.session.id}.`));
-                    }
-                    else {
-                        renderClaudeHistoryOnlyId(idQuery, historyEntry, allSessions);
-                        process.exit(1);
-                    }
+        }
+        if (queryMatches.length === 0 && !session) {
+            spinner.stop();
+            const historyEntry = findClaudeHistoryEntry(query);
+            if (historyEntry) {
+                const resumeMatch = resolveClaudeHistoryEntryToTranscript(historyEntry, allSessions);
+                if (resumeMatch) {
+                    session = resumeMatch.session;
                 }
                 else {
-                    console.error(chalk.red(`No session found matching: ${idQuery}`));
-                    console.error(chalk.gray('Run "agents sessions" to list available sessions.'));
+                    renderClaudeHistoryOnlyId(query, historyEntry, allSessions);
                     process.exit(1);
                 }
             }
-            if (queryMatches.length === 0) {
-                // session already resolved from history fallback
+            else {
+                console.error(chalk.red(`No session found matching: ${query}`));
+                console.error(chalk.gray('Run "agents sessions" to browse sessions.'));
+                process.exit(1);
             }
-            else if (queryMatches.length > 1) {
+        }
+        if (!session) {
+            if (queryMatches.length > 1) {
                 spinner.stop();
-                if (!isInteractiveTerminal()) {
-                    console.error(chalk.red(`Multiple sessions match: ${idQuery}`));
-                    console.error(chalk.gray('Pass a longer ID/query or one of these exact IDs:'));
-                    for (const match of queryMatches.slice(0, 10)) {
-                        console.error(chalk.cyan(`  ${match.id}`));
-                    }
-                    process.exit(1);
+                console.error(chalk.red(`Multiple sessions match "${query}":`));
+                for (const match of queryMatches.slice(0, 10)) {
+                    console.error(chalk.cyan(`  ${match.shortId}  ${match.id}  ${match.label ?? match.topic ?? ''}`));
                 }
-                // Multiple matches -- let the user pick
-                const picked = await pickSession(queryMatches, formatSearchMessage(options));
-                if (!picked)
-                    return;
-                session = picked;
+                console.error(chalk.gray('Pass a longer ID to narrow it down.'));
+                process.exit(1);
             }
             else {
                 session = queryMatches[0];
@@ -379,69 +787,108 @@ async function viewAction(idQuery, options) {
             throw new Error('Session resolution failed');
         }
         spinner.stop();
-        await renderSession(session, mode);
+        await renderSession(session, mode, scope.filter);
     }
     catch (err) {
         if (isPromptCancelled(err))
             return;
+        tracker.stop();
         spinner.stop();
         console.error(chalk.red(`Failed to read session: ${err.message}`));
         process.exit(1);
     }
 }
+/** Register the `agents sessions` command with all its options and help text. */
 export function registerSessionsCommands(program) {
-    const sessionsCmd = program
+    program
         .command('sessions')
-        .description('List and view agent sessions for the current directory by default')
-        .option('--agent <agent>', SESSION_AGENT_FILTER_HELP)
-        .option('--all', 'Show sessions from every directory')
-        .option('--project <name>', 'Filter by project name across all directories')
-        .option('--since <time>', 'Filter sessions newer than time (e.g., "7d", "30d", ISO timestamp)')
-        .option('--until <time>', 'Filter sessions older than time (ISO timestamp)')
-        .option('-n, --limit <n>', 'Max sessions to show', '20')
-        .action(async (options) => {
-        await listAction(options);
-    });
-    sessionsCmd
-        .command('list')
-        .description('List sessions for the current directory by default')
-        .option('--agent <agent>', SESSION_AGENT_FILTER_HELP)
-        .option('--all', 'Show sessions from every directory')
-        .option('--project <name>', 'Filter by project name across all directories')
-        .option('--since <time>', 'Filter sessions newer than time (e.g., "7d", "30d", ISO timestamp)')
-        .option('--until <time>', 'Filter sessions older than time (ISO timestamp)')
-        .option('-n, --limit <n>', 'Max sessions to show', '20')
-        .action(async (options) => {
-        await listAction(options);
-    });
-    sessionsCmd
-        .command('view [id]')
-        .description('View a session by ID or search query (picker defaults to live search)')
-        .option('--agent <agent>', SESSION_AGENT_FILTER_HELP)
-        .option('--all', 'Show sessions from every directory')
-        .option('--project <name>', 'Filter by project name across all directories')
-        .option('--since <time>', 'Filter sessions newer than time (e.g., "7d", "30d", ISO timestamp)')
-        .option('--until <time>', 'Filter sessions older than time (ISO timestamp)')
-        .option('--transcript', 'Show full conversation transcript')
-        .option('--trace', 'Show reasoning trace as markdown')
-        .option('--json', 'Output normalized events as JSON')
-        .action(async (id, options, command) => {
-        const parentOptions = typeof command?.parent?.opts === 'function'
-            ? command.parent.opts()
-            : {};
-        await viewAction(id, { ...parentOptions, ...options });
+        .argument('[query]', 'Session ID, search query, or path (., ../, /path) to filter by project')
+        .description('Find, browse, and read agent conversation transcripts across Claude, Codex, Gemini, and OpenCode.')
+        .option('-a, --agent <agent>', 'Filter by agent type and version (e.g., claude, codex@0.116.0)')
+        .option('--all', 'Include sessions from every directory (not just current project)')
+        .option('--teams', 'Include team-spawned sessions (hidden by default)')
+        .option('--project <name>', 'Filter by project name (searches across all directories)')
+        .option('--since <time>', 'Only sessions newer than this (e.g., 2h, 7d, 4w, or ISO date)')
+        .option('--until <time>', 'Only sessions older than this (ISO timestamp)')
+        .option('-n, --limit <n>', 'Maximum number of sessions to return', '50')
+        .option('--markdown', 'Render the session as markdown (user, assistant, thinking, tool calls)')
+        .option('--json', 'Output JSON (session list when browsing, event array when rendering one session)')
+        .option('--include <roles>', 'Only include these roles (comma-separated): user, assistant, thinking, tools')
+        .option('--exclude <roles>', 'Exclude these roles (comma-separated): user, assistant, thinking, tools')
+        .option('--first <n>', 'Keep only the first N turns (a turn starts at each user message)')
+        .option('--last <n>', 'Keep only the last N turns (a turn starts at each user message)')
+        .option('--artifacts', 'List all files written or edited during a session')
+        .option('--artifact <name>', 'Read a specific artifact by filename or path (outputs to stdout)')
+        .addHelpText('after', `
+Examples:
+  # Interactive picker: browse and search recent sessions (TTY only)
+  agents sessions
+
+  # List sessions from current project (last 30 days, piped output shows table)
+  agents sessions | head -20
+
+  # Search sessions by text (topic, file paths, commands)
+  agents sessions "add auth middleware"
+
+  # Filter by project across all directories
+  agents sessions --project agents-cli --all
+
+  # Filter by agent and time window
+  agents sessions --agent claude --since 7d
+
+  # Filter sessions in a specific directory
+  agents sessions /Users/muqsit/src/my-project
+
+  # Default summary view for one session
+  agents sessions a1b2c3d4
+
+  # Full conversation (user + assistant + thinking + tools) as markdown
+  agents sessions a1b2c3d4 --markdown
+
+  # Same conversation as structured JSON events
+  agents sessions a1b2c3d4 --json
+
+  # Only user messages (filter flags auto-select markdown)
+  agents sessions a1b2c3d4 --include user
+
+  # Everything except thinking, as markdown
+  agents sessions a1b2c3d4 --exclude thinking --markdown
+
+  # Last 3 turns as markdown
+  agents sessions a1b2c3d4 --last 3
+
+  # First 10 turns, user messages only, as JSON
+  agents sessions a1b2c3d4 --first 10 --include user --json
+
+  # Export all recent sessions as JSON for analysis
+  agents sessions --since 30d --limit 200 --json > sessions.json
+
+  # Include team-spawned sessions in results
+  agents sessions --teams
+
+Notes:
+  - --include and --exclude are mutually exclusive.
+  - --first and --last are mutually exclusive.
+  - A filter flag without --markdown/--json defaults to --markdown output.
+`)
+        .action(async (query, options) => {
+        await sessionsAction(query, options);
     });
 }
-function formatNoSessionsMessage(showAll, picker = false, project) {
+function formatNoSessionsMessage(showAll, project) {
     const projectQuery = project?.trim();
     if (projectQuery) {
         return `No sessions found for project "${projectQuery}".`;
     }
     if (showAll)
         return 'No sessions found.';
-    const command = picker ? 'agents sessions view --all' : 'agents sessions --all';
+    const command = 'agents sessions --all';
     return `No sessions found for ${process.cwd()}. Run "${command}" to see sessions from every directory.`;
 }
+function formatTeamHiddenFooter(hiddenCount) {
+    const noun = hiddenCount === 1 ? 'team session' : 'team sessions';
+    return `(${hiddenCount} ${noun} hidden — use --teams to show, or \`agents teams status\`)`;
+}
 function findClaudeHistoryEntry(idQuery) {
     const historyPath = path.join(os.homedir(), '.claude', 'history.jsonl');
     if (!fs.existsSync(historyPath))
@@ -499,7 +946,7 @@ function renderClaudeHistoryOnlyId(idQuery, historyEntry, allSessions) {
         for (const session of relatedSessions) {
             console.error(chalk.gray(`  ${session.shortId}  ${session.id}  ${session.project || '-'}  ${formatRelativeTime(session.timestamp)}`));
         }
-        console.error(chalk.gray('Use one of the transcript IDs above with "agents sessions view <id>".'));
+        console.error(chalk.gray('Use one of the transcript IDs above with "agents sessions <id>".'));
         return;
     }
     if (historyEntry.display === '/resume') {
@@ -516,7 +963,13 @@ function findClaudeSessionsInProject(sessions, historyEntry) {
 function findClaudeProjectSessions(sessions, historyEntry) {
     if (!historyEntry.project)
         return [];
-    const projectRoot = historyEntry.project;
+    // Resolve symlinks (e.g. macOS /var -> /private/var) so we match sessions
+    // whose cwd was canonicalized at scan time.
+    let projectRoot = historyEntry.project;
+    try {
+        projectRoot = fs.realpathSync(projectRoot);
+    }
+    catch { /* dir gone */ }
     return sessions.filter(session => session.agent === 'claude' &&
         typeof session.cwd === 'string' &&
         isWithinProject(session.cwd, projectRoot));
@@ -597,24 +1050,21 @@ function sessionDistance(session, historyEntry) {
 // ---------------------------------------------------------------------------
 // Formatting helpers
 // ---------------------------------------------------------------------------
+function formatAbsoluteTime(isoTimestamp) {
+    const d = new Date(isoTimestamp);
+    if (isNaN(d.getTime()))
+        return isoTimestamp;
+    const months = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
+    const hh = String(d.getHours()).padStart(2, '0');
+    const mm = String(d.getMinutes()).padStart(2, '0');
+    return `${months[d.getMonth()]} ${d.getDate()} ${hh}:${mm}`;
+}
 function padRight(s, width) {
     return s.length >= width ? s + ' ' : s + ' '.repeat(width - s.length);
 }
 function truncate(s, max) {
     return s.length > max ? s.slice(0, max - 1) + '.' : s;
 }
-function formatCompactMetric(value) {
-    if (value === undefined)
-        return '-';
-    if (value < 1000)
-        return String(value);
-    if (value < 1_000_000) {
-        const compact = value / 1000;
-        return compact >= 100 ? `${Math.round(compact)}k` : `${compact.toFixed(1).replace(/\.0$/, '')}k`;
-    }
-    const compact = value / 1_000_000;
-    return compact >= 100 ? `${Math.round(compact)}m` : `${compact.toFixed(1).replace(/\.0$/, '')}m`;
-}
 function formatRelativeTime(isoTimestamp) {
     const now = Date.now();
     const then = new Date(isoTimestamp).getTime();