@phnx-labs/agents-cli 1.21.2 → 1.22.0

package/dist/commands/models.js

@@ -11,9 +11,11 @@ import { homeDir } from '../lib/platform/index.js';
 import { resolveAgentName, formatAgentError, agentLabel, } from '../lib/agents.js';
 import { listInstalledVersions, getGlobalDefault, resolveVersion, resolveVersionAlias } from '../lib/versions.js';
 import { getModelCatalog, locateModelSource } from '../lib/models.js';
+import { resolveTierMap, MODEL_TIERS } from '../lib/model-tiers.js';
+import { getModelPricing } from '../lib/pricing/index.js';
 import { terminalWidth, truncateToWidth, stringWidth } from '../lib/session/width.js';
 import { wrapJoined } from './inspect.js';
-const MODEL_CAPABLE_AGENTS = ['claude', 'codex', 'opencode', 'cursor', 'openclaw', 'antigravity', 'kimi', 'grok'];
+const MODEL_CAPABLE_AGENTS = ['claude', 'codex', 'opencode', 'cursor', 'openclaw', 'antigravity', 'kimi', 'grok', 'droid'];
 /**
  * Agents that don't necessarily install under ~/.agents/versions (cursor ships
  * via a curl script). For these, fall back to the PATH binary and synthesize
@@ -52,6 +54,7 @@ export function registerModelsCommand(program) {
                 agent,
                 version,
                 catalog: getModelCatalog(agent, version),
+                tiers: resolveTierMap(agent, version),
             }));
             console.log(JSON.stringify(out, null, 2));
             return;
@@ -122,8 +125,16 @@ function printCatalog(agent, version, isDefault, options) {
     const tag = isDefault ? chalk.gray(' (default)') : '';
     const header = `${agentLabel(agent)} ${chalk.bold(version)}${tag}`;
     console.log(header);
+    // Cost tiers first -- the thing an orchestrating agent reads to pick a model.
+    printTiers(agent, version);
     const src = locateModelSource(agent, version);
     if (!src) {
+        if (agent === 'droid') {
+            // Droid has no extractable catalog (no models CLI/API/config); the curated
+            // tier map above is the whole surface.
+            console.log(chalk.gray('  (Droid has no model list command; tiers are a curated, credit-multiplier map.)'));
+            return;
+        }
         console.log(chalk.yellow(`  Could not locate model source for ${agent}@${version}.`));
         console.log(chalk.gray(`  Expected the agent's CLI bundle or native binary under ~/.agents/.history/versions/${agent}/${version}/.`));
         return;
@@ -171,6 +182,30 @@ function printCatalog(agent, version, isDefault, options) {
         }
     }
 }
+/** Rough blended $/Mtok label for a model id, or '' when unpriced. */
+function priceLabel(id) {
+    const p = getModelPricing(id);
+    if (!p)
+        return chalk.gray('  --');
+    const perM = (p.inputPerToken + p.outputPerToken) * 1e6;
+    return chalk.gray(`  ~$${perM.toFixed(0)}/Mtok`);
+}
+/** Print the cheap/default/best/ultra tier map for an (agent, version). */
+function printTiers(agent, version) {
+    const map = resolveTierMap(agent, version);
+    if (!MODEL_TIERS.some((t) => map[t].model))
+        return;
+    console.log(chalk.gray('  tiers:'));
+    for (const t of MODEL_TIERS) {
+        const r = map[t];
+        if (!r.model)
+            continue;
+        const eff = r.effort ? chalk.gray(` @${r.effort}`) : '';
+        const clamp = r.clampedFrom ? chalk.gray(' (clamped)') : '';
+        console.log(`    ${chalk.cyan(t.padEnd(8))} ${chalk.bold(r.model)}${eff}${priceLabel(r.model)}${clamp}`);
+    }
+    console.log();
+}
 /** Abbreviate a path by replacing the home directory with ~. */
 function shortPath(p) {
     return p.replace(homeDir(), '~');

package/dist/commands/perf.d.ts

@@ -14,6 +14,13 @@
 import type { Command } from 'commander';
 import { type PerfAggregateRow } from '../lib/perf/db.js';
 import { type HookProfileRow } from '../lib/hooks/profile.js';
+interface PerfGlobalOpts {
+    days?: string;
+    warnMs?: string;
+    json?: boolean;
+    limit?: string;
+    project?: string;
+}
 /** Map warehouse rows shaped like hook.fire into the existing HookProfileRow UI. */
 export declare function asHookRows(rows: PerfAggregateRow[]): HookProfileRow[];
 export declare function renderHookTable(rows: HookProfileRow[], warnMs: number): void;
@@ -24,4 +31,13 @@ export declare function renderHookTable(rows: HookProfileRow[], warnMs: number):
  * hit ignores it (a caller filtering by project has no legacy rows to miss).
  */
 export declare function loadHookProfile(days: number, project?: string): HookProfileRow[];
+/**
+ * Sessions stuck repeatedly hitting the SAME guard block (git-guard,
+ * rm-guard, git-require-clean-tree, …) instead of adapting after the first
+ * denial. Reads the `friction` event sink (emitFriction in events.ts) that
+ * guard hooks self-report into via `agents _internal friction` before they
+ * exit 2 — see lib/friction-heuristics.ts for the grouping.
+ */
+export declare function frictionAction(opts: PerfGlobalOpts): void;
 export declare function registerPerfCommand(program: Command): void;
+export {};

package/dist/commands/perf.js

@@ -175,7 +175,17 @@ function runAction(opts) {
  * guard hooks self-report into via `agents _internal friction` before they
  * exit 2 — see lib/friction-heuristics.ts for the grouping.
  */
-function frictionAction(opts) {
+export function frictionAction(opts) {
+    // --project is declared on the shared `perf` parent for hooks/commands/run,
+    // where every sample carries a cwd. friction events (emitFriction in
+    // events.ts) don't carry one today — agents _internal friction has no
+    // --cwd flag — so silently accepting the flag here would look like it
+    // filtered when it did nothing. Fail loud instead of no-op.
+    if (opts.project) {
+        console.error(chalk.red("agents perf friction does not support --project yet — friction events carry no cwd to filter on."));
+        process.exitCode = 1;
+        return;
+    }
     const days = parseDays(opts.days);
     const startDate = new Date(Date.now() - days * 86_400_000);
     const events = query({ eventTypes: ['friction'], startDate });

package/dist/commands/projects.d.ts

@@ -20,7 +20,17 @@ export declare const PROJECTS_NO_FANOUT_ENV = "AGENTS_PROJECTS_LOCAL";
  * string when everything answered.
  */
 export declare function formatFleetSkippedNote(skipped: string[]): string;
-/** Best-effort `owner/repo` from a repo's origin remote. */
+/**
+ * Best-effort `owner/repo` from a repo's origin remote.
+ *
+ * `stderr: 'ignore'` is load-bearing, not tidiness. A checkout with no origin
+ * makes git print `error: No such remote 'origin'` on ITS stderr, which is the
+ * terminal's — the catch below never sees it. That was invisible while this was
+ * called once from `add` inside a real repo, and became noise the moment
+ * `import --from-factory` started calling it per row: importing 12 registry
+ * rows printed two raw git errors between the progress lines. Absence of a
+ * remote is an expected answer here (`undefined`), not something to report.
+ */
 export declare function originSlug(cwd: string): string | undefined;
 /** One `projects list` row, pre-render. */
 export interface ProjectListRow {

package/dist/commands/projects.js

@@ -29,6 +29,8 @@ import { rollupSessionsByProject, liveDeadSplit, enrichProjectSignals, formatPro
 import { fetchLinearProjectCounts } from '../lib/linear-project-counts.js';
 import { listLinearProjects, pickLinearProject } from '../lib/linear-projects.js';
 import { checkRepoSlug } from '../lib/project-doctor.js';
+import { readFocusAreas } from '../lib/project-focus.js';
+import { formatVerdict, scheduleVerdict } from '../lib/project-schedule.js';
 import { buildFactoryImportCandidates, buildLinearImportCandidates, validateImportOpts, } from '../lib/project-import.js';
 /** Recursion guard: a peer answering a probe fan-out never re-fans-out itself. */
 export const PROJECTS_NO_FANOUT_ENV = 'AGENTS_PROJECTS_LOCAL';
@@ -57,10 +59,24 @@ function parseContextFlag(raw) {
         return { path: raw.trim(), purpose: '' };
     return { path: raw.slice(0, i).trim(), purpose: raw.slice(i + 1).trim() };
 }
-/** Best-effort `owner/repo` from a repo's origin remote. */
+/**
+ * Best-effort `owner/repo` from a repo's origin remote.
+ *
+ * `stderr: 'ignore'` is load-bearing, not tidiness. A checkout with no origin
+ * makes git print `error: No such remote 'origin'` on ITS stderr, which is the
+ * terminal's — the catch below never sees it. That was invisible while this was
+ * called once from `add` inside a real repo, and became noise the moment
+ * `import --from-factory` started calling it per row: importing 12 registry
+ * rows printed two raw git errors between the progress lines. Absence of a
+ * remote is an expected answer here (`undefined`), not something to report.
+ */
 export function originSlug(cwd) {
     try {
-        const url = execFileSync('git', ['remote', 'get-url', 'origin'], { cwd, encoding: 'utf8' }).trim();
+        const url = execFileSync('git', ['remote', 'get-url', 'origin'], {
+            cwd,
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        }).trim();
         return parseOwnerRepoFromRemote(url) ?? undefined;
     }
     catch {
@@ -254,7 +270,9 @@ function statusBar(r) {
 }
 function renderCard(def, r, remote, fleet, linear, nowMs = Date.now(), 
 /** How many milestones to print. `status` shows the next one; `view` shows all. */
-milestoneLimit = 1) {
+milestoneLimit = 1, 
+/** Directories the window's work landed in, from local git. */
+focus = []) {
     // The headline counts LIVE agents. It used to be every matched session, which
     // read `39 agents` on a project where 19 had crashed. `planPct` used to sit
     // here too and is gone: it summed each session's latest checklist snapshot,
@@ -290,6 +308,14 @@ milestoneLimit = 1) {
     for (const line of formatMilestoneLines(linear?.milestones ?? [], linear?.nextMilestone, nowMs, milestoneLimit)) {
         console.log(line);
     }
+    // What the dates prove — never an invented "on track". See project-schedule.ts.
+    const verdict = linear?.milestones?.length ? formatVerdict(scheduleVerdict(linear.milestones, nowMs)) : undefined;
+    if (verdict) {
+        console.log(`  ${chalk.dim('schedule')} ${verdict.warn ? chalk.yellow(verdict.text) : verdict.text}`);
+    }
+    if (focus.length) {
+        console.log(`  ${chalk.dim('focus')}    ${focus.map((f) => `${f.path} ${chalk.dim(String(f.touches))}`).join(chalk.dim('  ·  '))}`);
+    }
     if (r && r.tickets.length) {
         console.log(`  ${chalk.dim('tickets')}  ${r.tickets.slice(0, 8).join(' · ')}${r.tickets.length > 8 ? ' …' : ''}`);
     }
@@ -569,6 +595,8 @@ export function registerProjectsCommands(program) {
         // log but skips the gh calls + Linear counts (both are network).
         const remote = new Map();
         const linear = new Map();
+        // Local git, no API, no rate limit — measured 0.23s over a 897-commit week.
+        const focus = new Map();
         await Promise.all(defs.map(async (d) => {
             const skipRemote = opts.remote === false;
             const [sig, counts] = await Promise.all([
@@ -580,6 +608,8 @@ export function registerProjectsCommands(program) {
             remote.set(d.name, sig);
             if (counts)
                 linear.set(d.name, counts);
+            if (d.root)
+                focus.set(d.name, await readFocusAreas(expandLocalHome(d.root), windowDays));
         }));
         /** This def's slice of the fleet probe, in its own target order. */
         const fleetFor = (d) => {
@@ -598,6 +628,10 @@ export function registerProjectsCommands(program) {
                     byStatus: r?.byStatus ?? {},
                     members: r?.members ?? [],
                     plan: r?.plan ?? { done: 0, total: 0 },
+                    schedule: linear.get(d.name)?.milestones?.length
+                        ? scheduleVerdict(linear.get(d.name).milestones, nowMs)
+                        : null,
+                    focus: focus.get(d.name) ?? [],
                     live: r ? liveDeadSplit(r.byStatus).live : 0,
                     dead: r ? liveDeadSplit(r.byStatus).dead : 0,
                     openPrs: r?.openPrs ?? [],
@@ -616,7 +650,7 @@ export function registerProjectsCommands(program) {
             return;
         }
         for (const d of defs) {
-            renderCard(d, roll.get(d.name), remote.get(d.name), opts.fleet ? fleetFor(d) : undefined, linear.get(d.name), nowMs);
+            renderCard(d, roll.get(d.name), remote.get(d.name), opts.fleet ? fleetFor(d) : undefined, linear.get(d.name), nowMs, 1, focus.get(d.name) ?? []);
         }
         if (fleetSkipped.length > 0)
             process.stdout.write(formatFleetSkippedNote(fleetSkipped));

package/dist/commands/sessions-backfill.d.ts

@@ -0,0 +1,32 @@
+import type { Command } from 'commander';
+import { type ToolIndexCoverage } from '../lib/session/tool-index.js';
+export interface ToolBackfillMachineResult {
+    machine: string;
+    indexedFiles: number;
+    indexedCalls: number;
+    coverage: ToolIndexCoverage;
+}
+export interface ToolBackfillEnvelope {
+    schemaVersion: 1;
+    kind: 'tools-backfill';
+    generatedAt: string;
+    complete: boolean;
+    machines: ToolBackfillMachineResult[];
+}
+interface ToolBackfillOptions {
+    agent?: string;
+    project?: string;
+    since?: string;
+    until?: string;
+    unmanaged?: boolean;
+    teams?: boolean;
+    json?: boolean;
+    local?: boolean;
+    fleet?: boolean;
+    host?: string[] | string;
+    device?: string[] | string;
+}
+export declare function backfillToolsLocal(options: ToolBackfillOptions, oneBatch?: boolean): Promise<ToolBackfillMachineResult>;
+export declare function runToolsBackfill(options: ToolBackfillOptions): Promise<ToolBackfillEnvelope>;
+export declare function registerSessionsBackfillCommand(sessionsCmd: Command): void;
+export {};

package/dist/commands/sessions-backfill.js

@@ -0,0 +1,186 @@
+import chalk from 'chalk';
+import { setHelpSections } from '../lib/help.js';
+import { gatherRemoteAgentsJson } from '../lib/remote-agents-json.js';
+import { discoverSessions } from '../lib/session/discover.js';
+import { machineId } from '../lib/session/sync/config.js';
+import { SESSION_AGENTS } from '../lib/session/types.js';
+import { ensureToolIndex, readToolIndexCoverage } from '../lib/session/tool-index.js';
+import { NO_FANOUT_ENV } from '../lib/session/remote-active.js';
+const BACKFILL_REMOTE_TIMEOUT_MS = 10 * 60_000;
+function parseAgent(value) {
+    if (!value)
+        return {};
+    const separator = value.indexOf('@');
+    const name = (separator < 0 ? value : value.slice(0, separator));
+    if (!SESSION_AGENTS.includes(name))
+        throw new Error(`Unknown session agent: ${name}`);
+    return { agent: name, version: separator < 0 ? undefined : value.slice(separator + 1) || undefined };
+}
+function mergeHosts(options) {
+    const values = [options.host, options.device].flatMap((value) => value === undefined ? [] : Array.isArray(value) ? value : [value]);
+    return [...new Set(values)];
+}
+export async function backfillToolsLocal(options, oneBatch = false) {
+    const { agent, version } = parseAgent(options.agent);
+    const sessions = await discoverSessions({
+        agent,
+        version,
+        project: options.project,
+        since: options.since,
+        until: options.until,
+        all: true,
+        unbounded: true,
+        skipExistenceCheck: true,
+        includeUnmanaged: options.unmanaged,
+        excludeTeamOrigin: !options.teams,
+    });
+    let indexedFiles = 0;
+    let indexedCalls = 0;
+    for (;;) {
+        const batch = await ensureToolIndex(sessions);
+        indexedFiles += batch.indexedFiles;
+        indexedCalls += batch.indexedCalls;
+        if (oneBatch || batch.remainingFiles === 0 || batch.indexedFiles === 0)
+            break;
+    }
+    return {
+        machine: machineId(),
+        indexedFiles,
+        indexedCalls,
+        coverage: readToolIndexCoverage(sessions),
+    };
+}
+function parseRemoteBackfill(stdout, machine) {
+    try {
+        const envelope = JSON.parse(stdout);
+        if (envelope.schemaVersion !== 1 || envelope.kind !== 'tools-backfill'
+            || !Array.isArray(envelope.machines) || envelope.machines.length !== 1) {
+            return { items: [], valid: false };
+        }
+        const item = envelope.machines[0];
+        const coverage = item.coverage;
+        const coverageKeys = ['indexedFiles', 'indexedCalls', 'skippedFiles', 'limitedFiles', 'remainingFiles'];
+        if (!coverage || typeof coverage.complete !== 'boolean'
+            || !Number.isSafeInteger(item.indexedFiles) || item.indexedFiles < 0
+            || !Number.isSafeInteger(item.indexedCalls) || item.indexedCalls < 0
+            || coverageKeys.some((key) => !Number.isSafeInteger(coverage[key]) || coverage[key] < 0)) {
+            return { items: [], valid: false };
+        }
+        return { items: [{ ...item, machine }], valid: true };
+    }
+    catch {
+        return { items: [], valid: false };
+    }
+}
+function peerArgs(options) {
+    const args = ['sessions', 'backfill', 'tools', '--json', '--local'];
+    if (options.agent)
+        args.push('--agent', options.agent);
+    if (options.project)
+        args.push('--project', options.project);
+    if (options.since)
+        args.push('--since', options.since);
+    if (options.until)
+        args.push('--until', options.until);
+    if (options.unmanaged)
+        args.push('--unmanaged');
+    if (options.teams)
+        args.push('--teams');
+    return args;
+}
+export async function runToolsBackfill(options) {
+    const hosts = mergeHosts(options);
+    const includeLocal = options.local === true || hosts.length === 0;
+    const fanOut = options.local !== true && (options.fleet === true || hosts.length > 0);
+    if (!fanOut) {
+        const machines = includeLocal
+            ? [await backfillToolsLocal(options, process.env[NO_FANOUT_ENV] === '1')]
+            : [];
+        return {
+            schemaVersion: 1,
+            kind: 'tools-backfill',
+            generatedAt: new Date().toISOString(),
+            complete: machines.every((machine) => machine.coverage.complete),
+            machines,
+        };
+    }
+    const machineTotals = new Map();
+    let unreachable = false;
+    for (;;) {
+        const localPromise = includeLocal ? backfillToolsLocal(options, true) : Promise.resolve(undefined);
+        const [local, remote] = await Promise.all([localPromise, gatherRemoteAgentsJson({
+                args: peerArgs(options),
+                noFanoutEnv: NO_FANOUT_ENV,
+                hosts: hosts.length > 0 ? hosts : undefined,
+                timeoutMs: BACKFILL_REMOTE_TIMEOUT_MS,
+                parse: parseRemoteBackfill,
+            })]);
+        const round = [local, ...remote.items].filter((item) => item !== undefined);
+        for (const item of round) {
+            const prior = machineTotals.get(item.machine);
+            machineTotals.set(item.machine, {
+                ...item,
+                indexedFiles: (prior?.indexedFiles ?? 0) + item.indexedFiles,
+                indexedCalls: (prior?.indexedCalls ?? 0) + item.indexedCalls,
+            });
+        }
+        unreachable = remote.discoveryFailed || remote.skipped.length > 0 || remote.parseFailed.length > 0;
+        const progressed = round.reduce((sum, item) => sum + item.indexedFiles, 0);
+        if (unreachable || progressed === 0 || (round.length > 0 && round.every((item) => item.coverage.complete)))
+            break;
+    }
+    const machines = [...machineTotals.values()];
+    return {
+        schemaVersion: 1,
+        kind: 'tools-backfill',
+        generatedAt: new Date().toISOString(),
+        complete: !unreachable && machines.every((machine) => machine.coverage.complete),
+        machines,
+    };
+}
+export function registerSessionsBackfillCommand(sessionsCmd) {
+    const backfill = sessionsCmd.command('backfill').description('Populate derived session data explicitly.');
+    const tools = backfill.command('tools').description('Parse historical tool calls once into the local SQLite index.');
+    setHelpSections(tools, {
+        examples: `
+      # Backfill this machine once; reruns resume and skip completed transcripts
+      agents sessions backfill tools
+
+      # Backfill every online compute device, keeping each index local
+      agents sessions backfill tools --fleet --json
+
+      # Narrow the historical work
+      agents sessions backfill tools --agent codex --since 7d
+    `,
+        notes: `
+      - This command is the only historical transcript parse for tool indexing. Tool queries never trigger it.
+      - New and changed sessions are indexed during their normal incremental scan.
+      - No embeddings, vector database, network model, or semantic processing is used.
+    `,
+    });
+    tools.action(async (_options, command) => {
+        const options = command.optsWithGlobals();
+        if (options.local && (options.fleet || mergeHosts(options).length > 0)) {
+            console.error(chalk.red('--local cannot be combined with --fleet, --host, or --device.'));
+            process.exitCode = 1;
+            return;
+        }
+        try {
+            const envelope = await runToolsBackfill(options);
+            if (options.json)
+                process.stdout.write(JSON.stringify(envelope, null, 2) + '\n');
+            else {
+                for (const machine of envelope.machines) {
+                    console.log(`${machine.machine}: indexed ${machine.indexedFiles.toLocaleString()} transcript${machine.indexedFiles === 1 ? '' : 's'} and ${machine.indexedCalls.toLocaleString()} tool call${machine.indexedCalls === 1 ? '' : 's'}.`);
+                }
+                if (!envelope.complete) {
+                    console.log(chalk.yellow('Backfill is partial; rerun the command after resolving skipped or limited transcripts.'));
+                }
+            }
+        }
+        catch (error) {
+            console.error(chalk.red(error instanceof Error ? error.message : String(error)));
+            process.exitCode = 1;
+        }
+    });
+}

package/dist/commands/sessions-picker.js

@@ -374,6 +374,13 @@ function formatCompactPreview(events, session) {
     let latestTodos;
     let subAgentCount = 0;
     const toolTags = new Set();
+    // usedBrowser/usedComputer are computed at scan time from a sessionId-scoped
+    // events-log read (session/db.ts detectToolUsage), NOT a transcript regex —
+    // undefined means a legacy row this scanner hasn't computed the field for
+    // yet, so only THEN does classifySessionTool's transcript-derived guess run
+    // below (mirrors directoriesTouched's prefer-persisted/fall-back-to-derived
+    // pattern for recentDirectoriesTouched).
+    const knownToolUsage = session.usedBrowser !== undefined;
     for (const event of events) {
         if (event.type === 'message') {
             if (event.role === 'user' && !firstUser && event.content) {
@@ -388,8 +395,10 @@ function formatCompactPreview(events, session) {
         else if (event.type === 'tool_use' && !event._local) {
             const tool = event.tool || '';
             const command = event.command || '';
-            for (const tag of classifySessionTool(tool, command))
-                toolTags.add(tag);
+            if (!knownToolUsage) {
+                for (const tag of classifySessionTool(tool, command))
+                    toolTags.add(tag);
+            }
             if (isSubAgentTool(tool, command))
                 subAgentCount++;
             const p = event.path || event.args?.file_path || event.args?.path || '';
@@ -412,6 +421,12 @@ function formatCompactPreview(events, session) {
             toolCalls++;
         }
     }
+    // Persisted field wins when computed — it comes from real browser.navigate/
+    // browser.screenshot/computer.action events, not a fuzzy tool-name regex.
+    if (session.usedBrowser)
+        toolTags.add('browser');
+    if (session.usedComputer)
+        toolTags.add('computer');
     // Prefer the transcript-derived list when we just re-parsed the file (freshest
     // checklist write); fall back to SessionMeta.todos for rows where the scan/
     // fan-out attached progress but the event stream has no TodoWrite yet.

package/dist/commands/sessions.d.ts

@@ -4,6 +4,7 @@ import type { SessionAgentId, SessionMeta, ViewMode } from '../lib/session/types
 import { type ActiveSession } from '../lib/session/active.js';
 import { gatherRemoteList, runOnPeer } from '../lib/session/remote-list.js';
 import { type PickedSession } from './sessions-picker.js';
+import { type ToolSearchEnvelope, type ToolProgramCountEnvelope } from '../lib/session/tool-index.js';
 interface SessionFilterOptions {
     agent?: string;
     project?: string;
@@ -17,7 +18,7 @@ interface SessionFilterOptions {
 interface SessionsOptions extends SessionFilterOptions {
     /** Also list sessions from the user's own unmanaged ~/.<agent> installs. */
     unmanaged?: boolean;
-    query?: string;
+    query?: string[];
     /** Resolve one historical selector to metadata only (requires --json). */
     resolve?: string;
     /** Versioned internal peer protocol; old/unsafe peers must reject it. */
@@ -55,6 +56,10 @@ interface SessionsOptions extends SessionFilterOptions {
     local?: boolean;
     /** --device <target...> — alias for --host; resolves against the device registry. */
     device?: string[];
+    /** Query every registered online compute device and merge tool evidence. */
+    fleet?: boolean;
+    /** Aggregate static program sites instead of returning matching call evidence. */
+    count?: boolean;
     /** Per-agent shorthands: aliases for `--agent <name>` (prioritized harnesses). */
     claude?: boolean;
     codex?: boolean;
@@ -70,6 +75,11 @@ interface SessionsOptions extends SessionFilterOptions {
     printCmd?: boolean;
     /** Print a compact preview of the matched session and exit (no pager). */
     preview?: boolean;
+    /** Only sessions that invoked this skill (#12) — matches a bare name or a
+     * namespaced plugin skill's short name (`--skill design` finds `rush:design`). */
+    skill?: string;
+    /** Only sessions that used a skill/command owned by this plugin (#12). */
+    plugin?: string;
 }
 /**
  * Strip terminal/harness noise from a preview so the column stays a single line
@@ -333,6 +343,15 @@ export declare function renderSessionPreview(query: string, scope: {
  * attached", so those two spell it out.
  */
 export declare function formatLiveStatusHeadline(live: ActiveSession | undefined, favorite?: boolean): string;
+/** Merge local and peer envelopes without changing the versioned JSON shape. */
+export declare function mergeToolSearchEnvelopes(local: ToolSearchEnvelope, remotes: ToolSearchEnvelope[]): ToolSearchEnvelope;
+export declare function mergeToolProgramCountEnvelopes(local: ToolProgramCountEnvelope, remotes: ToolProgramCountEnvelope[]): ToolProgramCountEnvelope;
+/** Partition a fleet query by transcript origin so synced mirrors cannot duplicate results. */
+export declare function toolOriginSessions(sessions: SessionMeta[], machine: string, originOnly: boolean): SessionMeta[];
+export declare function printToolProgramCount(envelope: ToolProgramCountEnvelope): void;
+export declare function toolSearchFleetSortError(sort: string | undefined, spansDevices: boolean): string | undefined;
+/** Compact grouped evidence for humans; JSON retains every bounded field. */
+export declare function printToolSearch(envelope: ToolSearchEnvelope): void;
 /**
  * Whether a session belongs to `team`, from either end: it spawned the team, or
  * it is one of the team's teammates. Case-insensitive, matching the SQL
@@ -600,6 +619,8 @@ export declare function fleetCandidatesByQuery(rows: SessionMeta[], query: strin
 /** 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 declare function metadataResolveForwardedArgs(selector: string, scope: Pick<SessionFilterOptions, 'agent' | 'project'>): string[];
+/** Build the local-only peer argv for a distributed tool search. */
+export declare function toolSearchForwardedArgs(argv: string[], hosts: string[]): string[];
 /** 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 declare function metadataResolveOutcome(localMatches: SessionMeta[], remote: {