@phnx-labs/agents-cli 1.21.3 → 1.22.1

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/projects.js

@@ -25,10 +25,12 @@ import { gatherRemoteAgentsJson } from '../lib/remote-agents-json.js';
 import { factoryProjectsPath } from '../lib/auto-dispatch.js';
 import { formatFleetWorkspaces, parseRemoteProbe, probeProjectWorkspaces, workspaceTargetsForDef, } from '../lib/project-probe.js';
 import { listProjectDefs, loadProjectDef, writeProjectDef, removeProjectDef, projectDefPath, isSafeProjectName, } from '../lib/projects.js';
-import { rollupSessionsByProject, liveDeadSplit, enrichProjectSignals, formatProjectMembers, } from '../lib/project-status.js';
+import { rollupSessionsByProject, isDeadStatus, liveDeadSplit, enrichProjectSignals, formatProjectMembers, } from '../lib/project-status.js';
 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';
@@ -266,9 +268,45 @@ function statusBar(r) {
         parts.push(chalk.gray(`+${live - shown} other`));
     return parts.join(' · ') || chalk.gray('no live agents');
 }
+/**
+ * Gather the live/remote/Linear/focus signals for the projects about to be
+ * rendered. `status` and `view` share this deliberately: `view` used to build
+ * its own thinner picture, so the command you open to learn everything about
+ * ONE project showed strictly less than the roll-up across all of them — no
+ * agents, no ships, no focus, no schedule verdict. One gatherer means a signal
+ * added for either surface appears on both.
+ *
+ * Only the shown projects are enriched. `skipRemote` still reads the local
+ * artifact log and git focus, and skips just the network calls (`gh`, Linear).
+ */
+async function enrichProjectsForRender(defs, all, opts) {
+    const roll = rollupSessionsByProject(all, [...(await getActiveSessions()), ...(opts.extraSessions ?? [])]);
+    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 [sig, counts] = await Promise.all([
+            enrichProjectSignals(d, opts.windowDays, opts.nowMs, { skipRemote: opts.skipRemote }),
+            !opts.skipRemote && d.linear?.projectId
+                ? fetchLinearProjectCounts(d.linear.projectId)
+                : Promise.resolve(undefined),
+        ]);
+        remote.set(d.name, sig);
+        if (counts)
+            linear.set(d.name, counts);
+        if (d.root)
+            focus.set(d.name, await readFocusAreas(expandLocalHome(d.root), opts.windowDays));
+    }));
+    return { roll, remote, linear, focus };
+}
 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 = [], 
+/** `view` mode: the caller prints the stored definition in full afterwards. */
+detail = false) {
     // 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,
@@ -284,8 +322,12 @@ milestoneLimit = 1) {
         const detail = split.deadByStatus.map((d) => `${d.n} ${d.status}`).join(', ');
         console.log(`  ${chalk.dim('dead')}     ${chalk.yellow(`${split.dead} finished or lost`)} ${chalk.dim(`(${detail})`)}`);
     }
-    if (r && r.members.length)
-        console.log(`  ${chalk.dim('agents')}   ${formatProjectMembers(r.members)}`);
+    // Live only. The roster used to list every matched session, so a card headed
+    // `23 live` went on to show `crashed ×25` — the corpses the `dead` row above
+    // already accounts for, counted twice and contradicting the headline.
+    const liveMembers = r?.members.filter((m) => !isDeadStatus(m.status)) ?? [];
+    if (liveMembers.length)
+        console.log(`  ${chalk.dim('agents')}   ${formatProjectMembers(liveMembers)}`);
     const ships = [];
     if (remote?.mergedPrs) {
         ships.push(chalk.green(`${remote.mergedPrs}${remote.mergedPrsTruncated ? '+' : ''} merged (${remote.windowDays}d)`));
@@ -304,6 +346,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 ? ' …' : ''}`);
     }
@@ -331,13 +381,16 @@ milestoneLimit = 1) {
         console.log(`  ${chalk.yellow('!')}        ${chalk.yellow(mismatch.message)}`);
         console.log(`  ${' '.repeat(8)}${chalk.gray(mismatch.remediation)}`);
     }
-    if (def.contexts?.length) {
+    // `view` prints these in full (path + purpose, label + URL) right below, so
+    // the compact one-line summaries would just say the same thing twice.
+    if (!detail && def.contexts?.length) {
         console.log(`  ${chalk.dim('context')}  ${def.contexts.map((c) => c.path).join(' · ')}`);
     }
-    if (def.integrations?.length) {
+    if (!detail && def.integrations?.length) {
         console.log(`  ${chalk.dim('links')}    ${def.integrations.map((i) => i.label ?? i.kind).join(' · ')}`);
     }
-    console.log('');
+    if (!detail)
+        console.log('');
 }
 export function registerProjectsCommands(program) {
     const enabled = isBetaEnabled('projects');
@@ -456,58 +509,70 @@ export function registerProjectsCommands(program) {
     projects
         .command('view <name>')
         .alias('show')
-        .description('Show a project definition, resolved paths, repos, contexts, links, and milestones.')
+        .description('Everything about one project: the full status card, every milestone, and the stored definition.')
         .option('--json', 'Machine-readable output')
-        .option('--no-remote', 'Skip the Linear lookup; definition only')
+        .option('--window <days>', 'Window for merged PRs, artifacts, and focus areas', '7')
+        .option('--no-remote', 'Skip the GitHub and Linear lookups; definition only')
         .action(async (name, opts) => {
         const def = loadProjectDef(name);
         if (!def) {
             console.error(chalk.red(`No project named "${name}". List them: agents projects list`));
             process.exit(1);
         }
-        // Every milestone the project declares, not just the next one — the whole
-        // point of opening ONE project is to see the shape of its plan.
-        const counts = opts.remote !== false && def.linear?.projectId
-            ? await fetchLinearProjectCounts(def.linear.projectId)
-            : undefined;
+        // `view` is `status` for one project PLUS the stored definition and every
+        // milestone. It used to render its own short list — root, repos, a raw
+        // Linear id, issues — so opening a single project told you LESS than the
+        // roll-up did: no agents, no ships, no focus, no schedule verdict.
+        const windowDays = Math.max(1, Number.parseInt(opts.window ?? '7', 10) || 7);
+        const nowMs = Date.now();
+        const all = listProjectDefs();
+        const { roll, remote, linear, focus } = await enrichProjectsForRender([def], all, {
+            windowDays,
+            nowMs,
+            skipRemote: opts.remote === false,
+        });
+        const r = roll.get(def.name);
+        const sig = remote.get(def.name);
+        const counts = linear.get(def.name);
         if (opts.json) {
-            console.log(JSON.stringify({ ...def, linear: { ...def.linear, ...(counts ?? {}) } }, null, 2));
+            console.log(JSON.stringify({
+                ...def,
+                linear: { ...def.linear, ...(counts ?? {}) },
+                schedule: counts?.milestones?.length ? scheduleVerdict(counts.milestones, nowMs) : null,
+                live: r ? liveDeadSplit(r.byStatus).live : 0,
+                dead: r ? liveDeadSplit(r.byStatus).dead : 0,
+                byStatus: r?.byStatus ?? {},
+                members: r?.members ?? [],
+                openPrs: r?.openPrs ?? [],
+                tickets: r?.tickets ?? [],
+                mergedPrs: sig?.mergedPrs ?? 0,
+                latestRelease: sig?.latestRelease ?? null,
+                artifacts: sig?.artifacts ?? 0,
+                focus: focus.get(def.name) ?? [],
+            }, null, 2));
             return;
         }
-        console.log(chalk.bold(def.name) + (def.description ? chalk.dim(`  — ${def.description}`) : ''));
+        // The same card `status` prints, with every milestone instead of the next.
+        renderCard(def, r, sig, undefined, counts, nowMs, Number.POSITIVE_INFINITY, focus.get(def.name) ?? [], true);
+        // Then what only `view` shows: the stored definition, in full.
+        console.log();
         if (def.root)
-            console.log(`  root         ${def.root}`);
+            console.log(`  ${chalk.dim('root')}     ${def.root}`);
         if (def.defaultPath)
-            console.log(`  defaultPath  ${def.defaultPath}`);
-        const repos = [def.repo, ...(def.repos ?? []).map((r) => (r.subpath ? `${r.slug} (${r.subpath})` : r.slug))].filter(Boolean);
-        if (repos.length)
-            console.log(`  repos        ${repos.join(', ')}`);
+            console.log(`  ${chalk.dim('path')}     ${def.defaultPath}`);
+        for (const rp of def.repos ?? []) {
+            const where = [rp.subpath ? `subpath ${rp.subpath}` : undefined, rp.path].filter(Boolean).join(' · ');
+            console.log(`  ${chalk.dim('repo')}     ${rp.slug}${where ? chalk.dim(`  (${where})`) : ''}`);
+        }
         for (const c of def.contexts ?? [])
-            console.log(`  context      ${chalk.cyan(c.path)} — ${c.purpose}`);
-        for (const i of def.integrations ?? [])
-            console.log(`  ${i.kind.padEnd(12)} ${i.url}${i.label ? chalk.dim(`  (${i.label})`) : ''}`);
+            console.log(`  ${chalk.dim('context')}  ${chalk.cyan(c.path)} ${chalk.dim('—')} ${c.purpose}`);
+        for (const ig of def.integrations ?? []) {
+            console.log(`  ${chalk.dim(ig.kind.padEnd(8))} ${ig.url}${ig.label ? chalk.dim(`  (${ig.label})`) : ''}`);
+        }
         if (def.linear?.url || def.linear?.projectId)
-            console.log(`  linear       ${def.linear.url ?? def.linear.projectId}`);
+            console.log(`  ${chalk.dim('linear')}   ${def.linear.url ?? def.linear.projectId}`);
         for (const d of def.docs ?? [])
-            console.log(`  doc          ${d}`);
-        if (counts) {
-            const staleNote = counts.stale ? chalk.dim('  (cached)') : '';
-            console.log(`  issues       ${counts.done}/${counts.total}${counts.truncated ? '+' : ''} done · ${counts.inProgress} in progress${staleNote}`);
-        }
-        const ms = counts?.milestones ?? [];
-        if (ms.length) {
-            console.log(`  ${chalk.bold('milestones')}`);
-            for (const m of ms) {
-                const mark = m.name === counts?.nextMilestone?.name ? chalk.cyan('next') : '';
-                console.log(`    ${mark.padEnd(6)}     ${formatNextMilestone(m, Date.now())}`);
-            }
-            // A milestone nothing is filed against cannot report progress. Say that
-            // once, plainly, rather than printing a row of silent 0%s.
-            const unfiled = ms.filter((m) => m.total === 0).length;
-            if (unfiled === ms.length) {
-                console.log(`    ${chalk.yellow('!')}          ${chalk.yellow(`no issues are assigned to any milestone — progress against them cannot be measured`)}`);
-            }
-        }
+            console.log(`  ${chalk.dim('doc')}      ${d}`);
         console.log(chalk.gray(`  ${projectDefPath(name)}`));
     });
     // ---- edit ----
@@ -578,23 +643,12 @@ export function registerProjectsCommands(program) {
             fleetSkipped = probeRes.skipped;
             fleetSessions = activeRes.sessions;
         }
-        const roll = rollupSessionsByProject(all, [...await getActiveSessions(), ...fleetSessions]);
-        // Enrich only the shown projects. --no-remote still reads the local artifact
-        // log but skips the gh calls + Linear counts (both are network).
-        const remote = new Map();
-        const linear = new Map();
-        await Promise.all(defs.map(async (d) => {
-            const skipRemote = opts.remote === false;
-            const [sig, counts] = await Promise.all([
-                enrichProjectSignals(d, windowDays, nowMs, { skipRemote }),
-                !skipRemote && d.linear?.projectId
-                    ? fetchLinearProjectCounts(d.linear.projectId)
-                    : Promise.resolve(undefined),
-            ]);
-            remote.set(d.name, sig);
-            if (counts)
-                linear.set(d.name, counts);
-        }));
+        const { roll, remote, linear, focus } = await enrichProjectsForRender(defs, all, {
+            windowDays,
+            nowMs,
+            skipRemote: opts.remote === false,
+            extraSessions: fleetSessions,
+        });
         /** This def's slice of the fleet probe, in its own target order. */
         const fleetFor = (d) => {
             const targets = new Set(workspaceTargetsForDef(d));
@@ -612,6 +666,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 ?? [],
@@ -630,7 +688,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.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;
@@ -338,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
@@ -605,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: {