@phnx-labs/agents-cli 1.21.2 → 1.22.0

package/dist/commands/sessions.js

@@ -14,6 +14,7 @@ import { spawn } from 'child_process';
 import { Option } from 'commander';
 import chalk from 'chalk';
 import { truncate, padRight } from '../lib/format.js';
+import { sanitizeForTerminal } from '../lib/redact.js';
 import { resolveProjectKey } from '../lib/project-key.js';
 import { listProjectDefs, resolveProjectNameForCwd } from '../lib/projects.js';
 import ora from 'ora';
@@ -26,10 +27,10 @@ import { mapPanesToTargets, listClients } from '../lib/tmux/session.js';
 import { resolveViewingIn, viewingInLabel } from '../lib/session/viewing-in.js';
 import { machineId, normalizeHost } from '../lib/session/sync/config.js';
 import { gatherRemoteActive, NO_FANOUT_ENV } from '../lib/session/remote-active.js';
-import { gatherRemoteList, runOnPeer } from '../lib/session/remote-list.js';
+import { gatherRemoteList, gatherRemoteToolProgramCounts, gatherRemoteToolSearch, runOnPeer } from '../lib/session/remote-list.js';
 import { stringWidth, truncateToWidth, padToWidth, terminalWidth } from '../lib/session/width.js';
 import { inferSessionState } from '../lib/session/state.js';
-import { discoverSessions, countSessionsInScope, resolveSessionById, isCompleteSessionId, looksLikeSessionId, searchContentIndex, getSessionRoots } from '../lib/session/discover.js';
+import { discoverSessions, queryIndexedSessions, countSessionsInScope, resolveSessionById, isCompleteSessionId, looksLikeSessionId, searchContentIndex, getSessionRoots, scopeToManaged } from '../lib/session/discover.js';
 import { findSessionsById, querySessions } from '../lib/session/db.js';
 import { filterTeamSessions, safeTeamText } from '../lib/session/team-filter.js';
 import { parseSession } from '../lib/session/parse.js';
@@ -57,8 +58,13 @@ import { registerSessionsInjectCommand } from './sessions-inject.js';
 import { registerSessionsExportCommand } from './sessions-export.js';
 import { registerSessionsImportCommand } from './sessions-import.js';
 import { registerSessionsMigrateCommand, registerSessionsMigrationsCommand } from './sessions-migrate.js';
+import { registerSessionsBackfillCommand } from './sessions-backfill.js';
 import { runBrowserSessions } from '../lib/browser/sessions-list.js';
+import { countToolProgramOccurrences, parseToolProgramCountClause, readToolIndexCoverage, searchToolCalls, TOOL_QUERY_MAX_CLAUSE_BYTES, TOOL_QUERY_MAX_CLAUSES, TOOL_QUERY_MAX_RESULT_SESSIONS, serializeToolSearchEnvelope, toolSearchRemoteReceiveBudget, } from '../lib/session/tool-index.js';
 const SESSION_AGENT_FILTER_HELP = `Filter by agent, e.g. claude, codex, claude@2.0.65`;
+function collectQueryClause(value, previous) {
+    return [...previous, value];
+}
 /**
  * The prioritized harnesses that get a boolean shorthand flag (e.g. `--claude`
  * === `--agent claude`). The rest stay reachable via `--agent <name>`, which
@@ -1172,6 +1178,12 @@ export function hasNoBrowserDisqualifyingFlags(options, query) {
         !options.markdown &&
         !options.until &&
         !options.project &&
+        // The interactive browser picker is a fuzzy-search TUI over the discovered
+        // pool, not a SQL-filtered listing — it cannot represent a skill/plugin
+        // scope. Falling through to it here would silently drop the filter and
+        // show the unfiltered pool instead (same reasoning as --project/--sort).
+        !options.skill &&
+        !options.plugin &&
         !options.sort &&
         !options.artifacts &&
         options.artifact === undefined &&
@@ -1202,6 +1214,10 @@ function canonicalSessionsCommand(query, options) {
         a.push('--device', h);
     if (options.project)
         a.push('--project', options.project);
+    if (options.skill)
+        a.push('--skill', options.skill);
+    if (options.plugin)
+        a.push('--plugin', options.plugin);
     if (options.all)
         a.push('--all');
     if (options.since)
@@ -1286,6 +1302,114 @@ export function formatLiveStatusHeadline(live, favorite = false) {
     }
     return `${star}${glyph} ${statusColor(live.status)(word)}${suffix}`;
 }
+/** Merge local and peer envelopes without changing the versioned JSON shape. */
+export function mergeToolSearchEnvelopes(local, remotes) {
+    const all = [local, ...remotes];
+    const sessions = new Map();
+    for (const envelope of all) {
+        for (const session of envelope.sessions) {
+            sessions.set(`${session.machine ?? 'local'}\0${session.id}`, session);
+        }
+    }
+    return {
+        schemaVersion: 1,
+        generatedAt: new Date().toISOString(),
+        query: local.query,
+        coverage: {
+            indexedFiles: all.reduce((n, envelope) => n + envelope.coverage.indexedFiles, 0),
+            indexedCalls: all.reduce((n, envelope) => n + envelope.coverage.indexedCalls, 0),
+            skippedFiles: all.reduce((n, envelope) => n + envelope.coverage.skippedFiles, 0),
+            limitedFiles: all.reduce((n, envelope) => n + envelope.coverage.limitedFiles, 0),
+            remainingFiles: all.reduce((n, envelope) => n + envelope.coverage.remainingFiles, 0),
+            complete: all.every((envelope) => envelope.coverage.complete),
+        },
+        sessions: [...sessions.values()].sort((a, b) => b.timestamp.localeCompare(a.timestamp)),
+    };
+}
+export function mergeToolProgramCountEnvelopes(local, remotes) {
+    const all = [local, ...remotes];
+    return {
+        schemaVersion: 1,
+        kind: 'tool-program-count',
+        generatedAt: new Date().toISOString(),
+        query: local.query,
+        coverage: {
+            indexedFiles: all.reduce((sum, envelope) => sum + envelope.coverage.indexedFiles, 0),
+            indexedCalls: all.reduce((sum, envelope) => sum + envelope.coverage.indexedCalls, 0),
+            skippedFiles: all.reduce((sum, envelope) => sum + envelope.coverage.skippedFiles, 0),
+            limitedFiles: all.reduce((sum, envelope) => sum + envelope.coverage.limitedFiles, 0),
+            remainingFiles: all.reduce((sum, envelope) => sum + envelope.coverage.remainingFiles, 0),
+            complete: all.every((envelope) => envelope.coverage.complete),
+        },
+        totals: {
+            occurrences: all.reduce((sum, envelope) => sum + envelope.totals.occurrences, 0),
+            toolCalls: all.reduce((sum, envelope) => sum + envelope.totals.toolCalls, 0),
+            sessions: all.reduce((sum, envelope) => sum + envelope.totals.sessions, 0),
+        },
+        machines: all.flatMap((envelope) => envelope.machines),
+    };
+}
+/** Partition a fleet query by transcript origin so synced mirrors cannot duplicate results. */
+export function toolOriginSessions(sessions, machine, originOnly) {
+    return originOnly
+        ? sessions.filter((session) => (session.machine ?? machine) === machine)
+        : sessions;
+}
+export function printToolProgramCount(envelope) {
+    const { totals } = envelope;
+    const qualifier = envelope.coverage.complete ? '' : 'at least ';
+    console.log(`${envelope.query.program}: ${qualifier}${totals.occurrences.toLocaleString()} static occurrence${totals.occurrences === 1 ? '' : 's'} `
+        + `in ${totals.toolCalls.toLocaleString()} tool call${totals.toolCalls === 1 ? '' : 's'} `
+        + `across ${totals.sessions.toLocaleString()} session${totals.sessions === 1 ? '' : 's'}.`);
+    if (!envelope.coverage.complete) {
+        console.log(chalk.yellow(`Partial tool index: ${envelope.coverage.remainingFiles.toLocaleString()} transcript${envelope.coverage.remainingFiles === 1 ? '' : 's'} still need `
+            + '`agents sessions backfill tools`.'));
+    }
+}
+export function toolSearchFleetSortError(sort, spansDevices) {
+    if (!spansDevices || !sort || sort === 'recent')
+        return undefined;
+    return 'Tool search across devices supports only --sort recent; cost and duration are local-only.';
+}
+/** Compact grouped evidence for humans; JSON retains every bounded field. */
+export function printToolSearch(envelope) {
+    for (const session of envelope.sessions) {
+        const machineName = session.machine
+            ? truncate(sanitizeForTerminal(session.machine).replace(/\s+/g, ' '), 80)
+            : '';
+        const machine = machineName ? ` @ ${machineName}` : '';
+        const rawHeading = session.label || session.topic || session.project || session.shortId;
+        const heading = truncate(sanitizeForTerminal(rawHeading).replace(/\s+/g, ' '), Math.max(30, terminalWidth() - 20));
+        console.log(`${chalk.cyan(session.shortId)}${chalk.gray(machine)}  ${heading}`);
+        for (const call of session.calls) {
+            const tool = truncate(sanitizeForTerminal(call.tool).replace(/\s+/g, ' '), 80);
+            const safePrograms = call.programs.map((program) => truncate(sanitizeForTerminal(program).replace(/\s+/g, ' '), 80));
+            const programs = safePrograms.length > 0 ? ` [${safePrograms.join(', ')}]` : '';
+            const status = call.outcome === 'unknown' ? '' : ` ${call.outcome}`;
+            const input = truncate(sanitizeForTerminal(call.input).replace(/\s+/g, ' '), Math.max(30, terminalWidth() - 26));
+            console.log(`  ${chalk.gray(`#${call.ordinal + 1}`)} ${tool}${programs}${status}  ${input}`);
+            const snippet = call.error || call.output;
+            if (snippet) {
+                console.log(`     ${chalk.gray(truncate(sanitizeForTerminal(snippet).replace(/\s+/g, ' '), Math.max(30, terminalWidth() - 8)))}`);
+            }
+        }
+        console.log();
+    }
+    const count = envelope.sessions.length;
+    console.log(chalk.gray(`${count} matching session${count === 1 ? '' : 's'}.`));
+    if (!envelope.coverage.complete) {
+        const skipped = envelope.coverage.skippedFiles > 0
+            ? ` ${envelope.coverage.skippedFiles} transcript${envelope.coverage.skippedFiles === 1 ? ' was' : 's were'} skipped.`
+            : '';
+        const limited = envelope.coverage.limitedFiles > 0
+            ? ` ${envelope.coverage.limitedFiles} transcript${envelope.coverage.limitedFiles === 1 ? ' has' : 's have'} incomplete evidence because a safety limit was reached.`
+            : '';
+        const retry = envelope.coverage.remainingFiles > 0
+            ? ' Run `agents sessions backfill tools` to index historical transcripts.'
+            : '';
+        console.log(chalk.yellow(`Tool index coverage is partial: ${envelope.coverage.remainingFiles} transcript${envelope.coverage.remainingFiles === 1 ? '' : 's'} remain.${skipped}${limited}${retry}`));
+    }
+}
 /** Main action handler for `agents sessions`. Routes to picker, table, or single-session render. */
 async function sessionsAction(query, options, 
 /**
@@ -1294,9 +1418,70 @@ async function sessionsAction(query, options,
  * because the default arrives as a string like any typed value.
  */
 limitSource) {
-    // Explicit --query is interchangeable with the positional; it's how you search
-    // for text that collides with a subcommand name (e.g. `sessions --query go`).
-    query = query ?? options.query;
+    const queryClauses = options.query ?? [];
+    const toolOnly = options.include?.split(',').map((role) => role.trim()).filter(Boolean).join(',') === 'tools';
+    const toolEvidenceMode = toolOnly;
+    if (options.count && !toolOnly) {
+        console.error(chalk.red('--count requires --include tools.'));
+        process.exitCode = 1;
+        return;
+    }
+    if (!toolEvidenceMode) {
+        if (queryClauses.length > 1) {
+            console.error(chalk.red('Repeated --query clauses require --include tools.'));
+            process.exitCode = 1;
+            return;
+        }
+        // Outside tool evidence mode, --query retains its original positional-search
+        // meaning. The collector only makes it repeatable for tool clauses.
+        query = query ?? queryClauses[0];
+    }
+    if (options.fleet && !toolEvidenceMode) {
+        console.error(chalk.red('--fleet applies to tool-call queries: add --include tools.'));
+        process.exitCode = 1;
+        return;
+    }
+    if (toolEvidenceMode && (options.markdown || options.redact === false)) {
+        const incompatible = [
+            options.markdown ? '--markdown' : undefined,
+            options.redact === false ? '--no-redact' : undefined,
+        ].filter((flag) => flag !== undefined);
+        console.error(chalk.red(`${incompatible.join(' and ')} cannot be used with --include tools.`));
+        console.error(chalk.gray('Tool evidence is always redacted and byte-bounded; drop the conflicting render flag.'));
+        process.exitCode = 1;
+        return;
+    }
+    if (toolEvidenceMode && queryClauses.length > TOOL_QUERY_MAX_CLAUSES) {
+        console.error(chalk.red(`Tool search accepts at most ${TOOL_QUERY_MAX_CLAUSES} --query clauses.`));
+        process.exitCode = 1;
+        return;
+    }
+    if (toolEvidenceMode && queryClauses.some((clause) => Buffer.byteLength(clause) > TOOL_QUERY_MAX_CLAUSE_BYTES)) {
+        console.error(chalk.red(`Each tool --query clause is limited to ${TOOL_QUERY_MAX_CLAUSE_BYTES} bytes.`));
+        process.exitCode = 1;
+        return;
+    }
+    if (options.count && (queryClauses.length !== 1 || query !== undefined)) {
+        console.error(chalk.red('--count requires exactly one --query program:<name> clause and no positional query.'));
+        process.exitCode = 1;
+        return;
+    }
+    if (options.count && (limitSource === 'cli' || limitSource === 'env')) {
+        console.error(chalk.red('--count covers the complete filtered scope and cannot be combined with --limit.'));
+        process.exitCode = 1;
+        return;
+    }
+    let countProgram;
+    if (options.count) {
+        try {
+            countProgram = parseToolProgramCountClause(queryClauses[0]);
+        }
+        catch (error) {
+            console.error(chalk.red(error instanceof Error ? error.message : String(error)));
+            process.exitCode = 1;
+            return;
+        }
+    }
     // Normalize convenience flags before any routing reads them: per-agent
     // shorthands fold into --agent, and --device is an alias for --host (both
     // resolve against the same device registry).
@@ -1352,13 +1537,19 @@ limitSource) {
         });
         return;
     }
+    if (toolEvidenceMode && options.local === true
+        && options.host && !shouldIncludeLocal(options.host, machineId())) {
+        console.error(chalk.red('--local and --device name opposite scopes: --local skips the SSH fan-out that --device needs.'));
+        console.error(chalk.gray('Drop one — `--device <box>` to read that machine, `--local` to stay on this one.'));
+        process.exit(1);
+    }
     // --host WITHOUT --active. `--json` fans the recent listing out and emits ONE
     // clean merged SessionMeta[] array (same shape as the local --json path), for
     // scripts/extensions that JSON.parse a remote's history. Without --json it
     // keeps the legacy per-host stream (each remote's raw stdout under a
     // `── host ──` banner). With --active, the hosts are folded into the merged
     // machine-grouped view instead (handled below).
-    if (options.host && options.host.length > 0 && !options.active) {
+    if (options.host && options.host.length > 0 && !options.active && !toolEvidenceMode) {
         // --local means "skip the SSH fan-out"; --host means "look only over there".
         // Together they ask for a peer's sessions without dialing the peer, which can
         // only ever be empty — so say that instead of rendering a blank list.
@@ -1493,7 +1684,7 @@ limitSource) {
     }
     const mode = resolveViewMode(options, filterOpts);
     // --markdown or any filter flag forces single-session render.
-    const wantsRender = mode === 'markdown' || hasAnyFilter(filterOpts);
+    const wantsRender = !toolEvidenceMode && (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 });
@@ -1526,11 +1717,24 @@ limitSource) {
     const limit = wantsOverview
         ? OVERVIEW_POOL_LIMIT
         : parseInt(userSetLimit ? options.limit : wantsWholeTeam ? String(WHOLE_TEAM_POOL_LIMIT) : DEFAULT_LIMIT, 10);
+    if (toolEvidenceMode && (!Number.isSafeInteger(limit) || limit < 1 || limit > TOOL_QUERY_MAX_RESULT_SESSIONS)) {
+        console.error(chalk.red(`Tool search --limit must be from 1 to ${TOOL_QUERY_MAX_RESULT_SESSIONS}.`));
+        process.exitCode = 1;
+        return;
+    }
     // Overview: recency order across the whole index, no default window; an explicit
     // --since still narrows. Non-overview keeps the prior interactive-30d default.
     const since = wantsOverview
         ? options.since
         : (options.since ?? (isInteractive && !options.all && !wantsWholeTeam ? '30d' : undefined));
+    const toolSpansDevices = toolEvidenceMode
+        && (options.fleet || (options.host?.length ?? 0) > 0);
+    const toolSortError = toolSearchFleetSortError(options.sort, toolSpansDevices);
+    if (toolSortError) {
+        console.error(chalk.red(toolSortError));
+        process.exitCode = 1;
+        return;
+    }
     const spinner = options.json ? null : ora().start();
     const tracker = createScanProgressTracker(LOAD_VERBS, 'sessions', spinner);
     try {
@@ -1546,27 +1750,53 @@ limitSource) {
             // --in-team spans directories by construction: a team's teammates run in
             // their own worktrees, so scoping to the current cwd hides most of the
             // lineage the flag exists to show.
-            all: pathFilter ? undefined : options.all || wantsWholeTeam,
+            all: pathFilter ? undefined : options.all || wantsWholeTeam || toolSpansDevices,
             cwd: process.cwd(),
             // Default overview scopes to the current repo SUBTREE (prefix match), so a
             // monorepo shows its sub-projects grouped instead of collapsing to the one
             // exact-cwd project. `--all` clears the prefix and spans the whole index.
-            cwdPrefix: pathFilter ?? (wantsOverview && !options.all && !wantsWholeTeam ? process.cwd() : undefined),
+            cwdPrefix: pathFilter ?? (wantsOverview && !options.all && !wantsWholeTeam && !toolSpansDevices ? process.cwd() : undefined),
             project: options.project,
             since,
             until: options.until,
             sortBy,
             origin: options.routine ? 'routine' : undefined,
+            skipExistenceCheck: toolEvidenceMode,
+            unbounded: toolEvidenceMode,
+            skill: options.skill,
+            plugin: options.plugin,
         };
         let hiddenUnmanaged = 0;
-        let sessions = await discoverSessions({
-            ...scope,
-            limit,
-            excludeTeamOrigin: !options.teams,
-            onProgress: tracker.onProgress,
-            includeUnmanaged: options.unmanaged,
-            onHiddenUnmanaged: (n) => { hiddenUnmanaged = n; },
-        });
+        const toolSelf = toolEvidenceMode ? machineId() : undefined;
+        const toolIncludesLocal = !toolEvidenceMode
+            || process.env[NO_FANOUT_ENV] === '1'
+            || shouldIncludeLocal(options.host, toolSelf);
+        const indexedIdMatches = toolIncludesLocal && toolEvidenceMode && searchQuery && looksLikeSessionId(searchQuery)
+            ? scopeToManaged(findSessionsById(searchQuery, { agent, version, project: options.project }), agent ? [agent] : SESSION_AGENTS, { agent, includeUnmanaged: options.unmanaged })
+            : [];
+        let sessions;
+        if (!toolIncludesLocal) {
+            sessions = [];
+        }
+        else if (indexedIdMatches.length > 0) {
+            sessions = indexedIdMatches.map((session) => ({
+                ...session,
+                machine: session.machine ?? toolSelf,
+            }));
+        }
+        else {
+            const readOptions = {
+                ...scope,
+                limit,
+                excludeTeamOrigin: !options.teams,
+                onProgress: tracker.onProgress,
+                includeUnmanaged: options.unmanaged,
+                onHiddenUnmanaged: (n) => { hiddenUnmanaged = n; },
+            };
+            sessions = toolEvidenceMode
+                ? await queryIndexedSessions(readOptions, { resolveLinear: false })
+                : await discoverSessions(readOptions);
+        }
         tracker.stop();
         spinner?.stop();
         // Version filter is pushed down to SQL via scope.version above; no
@@ -1589,6 +1819,58 @@ limitSource) {
             const starred = listFavorites();
             sessions = sessions.filter((s) => starred.has(s.id));
         }
+        if (toolEvidenceMode) {
+            const self = toolSelf;
+            const selectedSessions = searchQuery
+                ? filterSessionsByQuery(sessions, searchQuery)
+                : sessions;
+            const localSessions = selectedSessions;
+            const mayFanOut = options.local !== true && process.env[NO_FANOUT_ENV] !== '1';
+            const hosts = remoteHostsToDial(options.host, self);
+            const originOnly = process.env[NO_FANOUT_ENV] === '1'
+                || (mayFanOut && (options.fleet || (options.host?.length ?? 0) > 0));
+            const querySessions = toolOriginSessions(localSessions, self, originOnly);
+            if (countProgram) {
+                const countCoverage = readToolIndexCoverage(querySessions);
+                let countEnvelope = countToolProgramOccurrences(querySessions, countProgram, countCoverage, self);
+                if (!toolIncludesLocal)
+                    countEnvelope.machines = [];
+                if (mayFanOut && (options.fleet || (options.host?.length ?? 0) > 0)
+                    && (!options.host?.length || (hosts && hosts.length > 0))) {
+                    const stripped = toolSearchForwardedArgs(process.argv, options.host ?? []);
+                    const remote = await gatherRemoteToolProgramCounts(stripped, options.host?.length ? hosts : undefined, countProgram);
+                    countEnvelope = mergeToolProgramCountEnvelopes(countEnvelope, remote.envelopes.map((item) => item.envelope));
+                    if (remote.unreachable.length > 0)
+                        countEnvelope.coverage.complete = false;
+                }
+                if (options.json)
+                    process.stdout.write(JSON.stringify(countEnvelope, null, 2) + '\n');
+                else
+                    printToolProgramCount(countEnvelope);
+                return;
+            }
+            const coverage = readToolIndexCoverage(querySessions);
+            let envelope = searchToolCalls(querySessions, queryClauses, coverage, limit);
+            if (mayFanOut && (options.fleet || (options.host?.length ?? 0) > 0)) {
+                if (!options.host?.length || (hosts && hosts.length > 0)) {
+                    const stripped = toolSearchForwardedArgs(process.argv, options.host ?? []);
+                    const remote = await gatherRemoteToolSearch(stripped, options.host?.length ? hosts : undefined, toolSearchRemoteReceiveBudget(envelope), queryClauses);
+                    envelope = mergeToolSearchEnvelopes(envelope, remote.envelopes.map((item) => item.envelope));
+                    if (remote.truncated.length > 0 || remote.unreachable.length > 0) {
+                        envelope.coverage.complete = false;
+                    }
+                }
+            }
+            envelope.sessions = envelope.sessions.slice(0, limit);
+            const serializedEnvelope = serializeToolSearchEnvelope(envelope);
+            if (options.json) {
+                process.stdout.write(serializedEnvelope);
+            }
+            else {
+                printToolSearch(envelope);
+            }
+            return;
+        }
         // Under --in-team the visible list is one team, so the whole-index team-origin
         // count would be a non-sequitur next to it.
         const hiddenCount = options.teams || options.inTeam
@@ -3154,6 +3436,15 @@ export function metadataResolveForwardedArgs(selector, scope) {
         args.push('--project', scope.project);
     return args;
 }
+/** Build the local-only peer argv for a distributed tool search. */
+export function toolSearchForwardedArgs(argv, hosts) {
+    const args = ensureWholeIndex(buildForwardedArgs(argv, new Set(hosts)).filter((arg) => arg !== '--fleet'));
+    if (!args.includes('--json'))
+        args.push('--json');
+    if (!args.includes('--local'))
+        args.push('--local');
+    return args;
+}
 /** Resolution must fail closed when any selected peer did not answer. Choosing
  * from a partial fleet can turn an unseen candidate into a false unique match. */
 export function metadataResolveOutcome(localMatches, remote, selector) {
@@ -3289,7 +3580,7 @@ export function registerSessionsCommands(program) {
     const sessionsCmd = program
         .command('sessions')
         .argument('[query]', 'Session ID, search query, or path (., ../, /path) to filter by project')
-        .option('--query <text>', 'Search text — use when the term collides with a subcommand name (e.g. "go")')
+        .option('--query <clause>', 'Search text; repeat with --include tools to require distinct matching calls', collectQueryClause, [])
         .option('--resolve <selector>', 'Resolve one full ID, unique prefix, or keyword query to safe session metadata (requires --json; searches the fleet unless --local)')
         .addOption(new Option('--resolve-safe-v1 <selector>').hideHelp())
         .description('Find, browse, and read agent conversation transcripts across Claude, Codex, Gemini, and OpenCode.')
@@ -3306,6 +3597,8 @@ export function registerSessionsCommands(program) {
         .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.")
         .option('--routine', 'Show only sessions archived from routine runs')
         .option('-p, --project <name>', 'Filter by project name (searches across all directories)')
+        .option('--skill <name>', 'Only sessions that invoked this skill (matches a bare name or a namespaced plugin skill\'s short name, e.g. --skill design finds rush:design)')
+        .option('--plugin <name>', 'Only sessions that used a skill/command owned by this plugin')
         .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', DEFAULT_LIMIT)
@@ -3330,6 +3623,8 @@ export function registerSessionsCommands(program) {
         .option('--cloud', 'Source sessions from Rush Cloud (captured runs) instead of local disk')
         .option('-H, --host <target...>', 'Run this query on remote machine(s) over SSH (host alias or user@host; repeatable)')
         .option('--device <target...>', 'Alias for --host (device alias from `agents devices`; repeatable)')
+        .option('--fleet', 'With --include tools: query every registered online compute device and merge compact matches')
+        .option('--count', 'With one program:<name> tool query: count static occurrences, containing calls, and sessions')
         .option('--browser', 'List browser-profile captures (screenshots, PDFs, recordings, downloads) instead of agent transcripts — alias of `agents browser sessions`')
         .option('--no-interactive', 'Print the listing instead of opening the interactive browser (default on a TTY for the bare listing and --active)')
         .option('--print-cmd', 'Print the canonical `ag sessions …` command for the given flags and exit (the twin of the browser’s `y` hotkey)')
@@ -3366,6 +3661,18 @@ export function registerSessionsCommands(program) {
       # Export for analysis
       agents sessions --since 30d --limit 200 --json > sessions.json
 
+      # List indexed tool calls in recent Codex sessions on one device
+      agents sessions --include tools --agent codex --device mac-mini --since 7d
+
+      # Each repeated clause must match a different call in the same session
+      agents sessions --include tools --query 'program:git input:merge' --query 'program:gh output:CONFLICT' --fleet --json
+
+      # Count every pre-indexed static git site without reparsing transcripts
+      agents sessions --include tools --query 'program:git' --count --fleet --json
+
+      # Explicitly populate historical tool rows once on every device
+      agents sessions backfill tools --fleet
+
       # Resolve one historical selector to metadata only, across the fleet
       agents sessions --resolve d3470b57 --json
 
@@ -3380,6 +3687,11 @@ export function registerSessionsCommands(program) {
       - --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.
+      - With --include tools, repeat --query for same-session AND across distinct calls. Fields: tool, program, input, output, status, exit, error.
+      - --count accepts exactly one program:<name> clause and reports static source occurrences, containing tool calls, and sessions.
+      - Tool queries read SQLite only. Run 'agents sessions backfill tools' once for historical transcripts; normal scans index new and changed sessions.
+      - Tool evidence is redacted and bounded before it reaches SQLite. --markdown and --no-redact conflict with --include tools.
+      - Tool queries accept 32 clauses (4 KiB each), --limit 1–1,000, and at most 8 MiB of materialized evidence.
       - --first and --last are mutually exclusive.
       - A filter flag (--include/--exclude/--first/--last) without --markdown/--json defaults to --markdown output.
       - --cloud sources from Rush Cloud captured runs instead of local disk.
@@ -3407,6 +3719,7 @@ export function registerSessionsCommands(program) {
     registerSessionsImportCommand(sessionsCmd);
     registerSessionsMigrateCommand(sessionsCmd);
     registerSessionsMigrationsCommand(sessionsCmd);
+    registerSessionsBackfillCommand(sessionsCmd);
 }
 function formatNoSessionsMessage(showAll, project) {
     const projectQuery = project?.trim();

package/dist/commands/teams.js

@@ -1279,7 +1279,7 @@ export function registerTeamsCommands(program) {
         .option('-n, --name <name>', 'Friendly name for this teammate (e.g. alice). Required if using --after. Unique within team.')
         .option('-m, --mode <mode>', `Permissions: plan (read-only) | edit (can write files) | auto (smart classifier auto-approves safe ops) | skip (bypass all permission prompts). 'full' accepted as alias for skip. Teammates run headless: plan works headless on claude/codex/droid/opencode; kimi/grok/cursor/antigravity have no headless plan mode and auto-downgrade a plan request to auto.`, 'edit')
         .option('-e, --effort <effort>', `Reasoning intensity: ${VALID_EFFORTS.join('|')}`, 'medium')
-        .option('--model <model>', 'Override the effort tier and use this specific model (e.g. claude-opus-4-6)')
+        .option('--model <model>', 'Cost tier (cheap|default|best|ultra) or a concrete id (e.g. claude-opus-4-8); tiers resolve per harness+version to a supported model')
         .option('--env <key=value>', 'Set an environment variable for this teammate (repeatable for multiple vars)', (val, prev) => [...prev, val], [])
         .option('--cwd <dir>', 'Working directory for this teammate (default: current directory)')
         .option('--worktree <name>', 'Run this teammate in a dedicated git worktree (required when team has --enable-worktrees)')

package/dist/commands/worktree.d.ts

@@ -11,9 +11,9 @@
  *   agents worktree prune                     -> removes every clean+merged one
  *
  * Worktrees live at <repo>/.agents/worktrees/<terminal-id>, on a branch
- * named agents/<terminal-id>. The branch starts at HEAD of the parent repo.
- * This matches the agent-system rule that keeps all coding-agent worktrees
- * under the repo-local .agents/ state directory.
+ * named agents/<terminal-id>. New branches start at the freshly-fetched
+ * origin/<default> (not local HEAD), matching lib/teams/worktree.ts and the
+ * agent-system rule that keeps coding-agent worktrees under .agents/.
  */
 import type { Command } from 'commander';
 export declare function registerWorktreeCommands(program: Command): void;

package/dist/commands/worktree.js

@@ -67,6 +67,25 @@ async function inspect(root, terminalId) {
     }
     return { exists, dirty, aheadOfUpstream, hasUpstream, branchMerged };
 }
+/** Resolve origin/HEAD → default branch name; falls back to `main`. */
+async function defaultBranch(root) {
+    try {
+        await execFileAsync('git', ['remote', 'set-head', 'origin', '--auto'], { cwd: root });
+    }
+    catch {
+        // offline / no origin
+    }
+    try {
+        const { stdout } = await execFileAsync('git', ['symbolic-ref', '--short', 'refs/remotes/origin/HEAD'], { cwd: root });
+        const base = stdout.trim().replace(/^origin\//, '');
+        if (base)
+            return base;
+    }
+    catch {
+        // no origin/HEAD
+    }
+    return 'main';
+}
 async function provision(root, terminalId) {
     const wt = worktreePathFor(root, terminalId);
     const branch = branchNameFor(terminalId);
@@ -84,10 +103,22 @@ async function provision(root, terminalId) {
     catch {
         branchExists = false;
     }
-    const args = branchExists
-        ? ['worktree', 'add', wt, branch]
-        : ['worktree', 'add', '-b', branch, wt, 'HEAD'];
-    await execFileAsync('git', args, { cwd: root });
+    if (branchExists) {
+        await execFileAsync('git', ['worktree', 'add', wt, branch], { cwd: root });
+        return wt;
+    }
+    // New branch: fetch + base on origin/<default>, never local HEAD (stale trap).
+    const base = await defaultBranch(root);
+    try {
+        await execFileAsync('git', ['fetch', 'origin'], { cwd: root });
+    }
+    catch (err) {
+        const detail = (err?.stderr || err?.message || String(err)).toString().trim();
+        die(`git fetch origin failed in ${root}` +
+            (detail ? `: ${detail}` : '') +
+            `. Cannot provision a worktree from a stale remote-tracking ref.`);
+    }
+    await execFileAsync('git', ['worktree', 'add', '-b', branch, wt, `origin/${base}`], { cwd: root });
     return wt;
 }
 async function release(root, terminalId, force) {

package/dist/index.js

@@ -99,6 +99,7 @@ import { applyGlobalHelpConventions } from './lib/help.js';
 import { renderWhatsNew } from './lib/whats-new.js';
 import { getCliLaunch } from './lib/cli-entry.js';
 import { emit, emitFriction, redactArgs } from './lib/events.js';
+import { stampProvenance } from './lib/event-provenance.js';
 import { die } from './lib/format.js';
 // Transparent shim delegate: the generated Windows `.cmd` shims invoke
 // `agents __shim <agent>[@version] <raw args>`. Intercept here, before commander
@@ -211,12 +212,19 @@ program.hook('postAction', (_thisCommand, actionCommand) => {
         }
         // Disposable perf warehouse — fail-soft spool append (no SQLite on this path).
         if (durationMs !== undefined && parts[0] !== 'perf') {
+            // sessionId/agent are resolvable here the same way emit() resolves them
+            // for command.start/command.end above (the shared provenance floor,
+            // event-provenance.ts) — without this, every command.end perf sample
+            // was anonymous, unlike the audit log record right next to it.
+            const { sessionId, agent } = stampProvenance();
             void import('./lib/perf/spool.js').then(({ recordSample }) => {
                 recordSample({
                     kind: 'command.end',
                     label: command,
                     durationMs,
                     cwd: process.cwd(),
+                    sessionId,
+                    agent,
                 });
             }).catch(() => { });
         }

package/dist/lib/browser/service.js

@@ -486,6 +486,7 @@ export class BrowserService {
             const sessionId = await this.getSessionId(conn, cdpTargetId);
             await conn.cdp.send('Page.navigate', { url }, sessionId);
             await this.saveTaskState(task.profile, conn.tasks);
+            emit('browser.navigate', { profile: task.profile, task: task.name, url, tabId: currentShortId, created: false });
             return { tabId: currentShortId, url, created: false };
         }
         // No current tab - create one
@@ -500,6 +501,7 @@ export class BrowserService {
             task.tabs[shortId] = cdpTargetId;
             task.currentTabId = shortId;
             await this.saveTaskState(task.profile, conn.tasks);
+            emit('browser.navigate', { profile: task.profile, task: task.name, url, tabId: shortId, created: true });
             return { tabId: shortId, url, created: true };
         }
         // Chrome: create new tab
@@ -511,6 +513,7 @@ export class BrowserService {
         task.currentTabId = shortId;
         this.invalidateTargetCache(conn);
         await this.saveTaskState(task.profile, conn.tasks);
+        emit('browser.navigate', { profile: task.profile, task: task.name, url, tabId: shortId, created: true });
         return { tabId: shortId, url, created: true };
     }
     async tabAdd(taskId, url, profileName) {
@@ -705,6 +708,16 @@ export class BrowserService {
         await fs.promises.writeFile(finalPath, buffer);
         const dims = (extension === 'png' ? readPngDimensions(buffer) : readJpegDimensions(buffer)) ??
             { width: 0, height: 0 };
+        emit('browser.screenshot', {
+            profile: profileName,
+            task: task.name,
+            tabId: shortId,
+            path: finalPath,
+            bytes: buffer.length,
+            width: dims.width,
+            height: dims.height,
+            quality,
+        });
         return { path: finalPath, bytes: buffer.length, width: dims.width, height: dims.height };
     }
     /**