@phnx-labs/agents-cli 1.22.6 → 1.22.8

package/dist/commands/sessions-stats.js

@@ -0,0 +1,263 @@
+import chalk from 'chalk';
+import { discoverSessions, parseTimeFilter } from '../lib/session/discover.js';
+import { queryResourceUsageStats, resourceUsageCoverage, } from '../lib/session/db.js';
+import { listResources } from '../lib/resources.js';
+import { discoverPlugins } from '../lib/plugins.js';
+import { setHelpSections } from '../lib/help.js';
+import { terminalWidth, truncateToWidth, padToWidth, stringWidth } from '../lib/session/width.js';
+const DEFAULT_TOP = 20;
+/**
+ * The both-ends "dead weight" set: installed resources whose identity
+ * (kind + name — name already embeds `plugin:short`, so it matches the stored
+ * invoked name) never appears in the invoked rows. Sorted kind then name.
+ * Pure set-difference so it is unit-testable without touching the filesystem.
+ */
+export function diffZeroInvoked(installed, invoked) {
+    const invokedKeys = new Set(invoked.map(r => `${r.kind}:${r.name}`));
+    return installed
+        .filter(r => !invokedKeys.has(`${r.kind}:${r.name}`))
+        .sort((a, b) => (a.kind === b.kind ? a.name.localeCompare(b.name) : a.kind.localeCompare(b.kind)));
+}
+/**
+ * Enumerate the installed resource set the invoked rows are measured against:
+ * flat skills/commands from the DotAgents layers (`listResources`) plus each
+ * plugin's own skills/commands as `plugin:short` (invisible to the flat scan) —
+ * exactly the union `resolveResourceProvenance` reconciles against at write time.
+ */
+function installedResources(kindFilter, pluginFilter, cwd) {
+    const kinds = kindFilter ? [kindFilter] : ['skill', 'command'];
+    const byKey = new Map();
+    const plugins = discoverPlugins({ cwd });
+    for (const kind of kinds) {
+        const listKind = kind === 'skill' ? 'skills' : 'commands';
+        // Flat (non-namespaced) resources are plugin-less; skip them when the caller
+        // narrows to one plugin.
+        if (!pluginFilter) {
+            for (const r of listResources(listKind, cwd)) {
+                byKey.set(`${kind}:${r.name}`, { kind, name: r.name, plugin: null, source: r.source });
+            }
+        }
+        for (const p of plugins) {
+            if (pluginFilter && p.name !== pluginFilter)
+                continue;
+            const names = kind === 'skill' ? p.skills : p.commands;
+            for (const short of names) {
+                const name = `${p.name}:${short}`;
+                byKey.set(`${kind}:${name}`, { kind, name, plugin: p.name, source: p.marketplace ?? null });
+            }
+        }
+    }
+    return [...byKey.values()];
+}
+export function registerSessionsStatsCommand(sessionsCmd) {
+    const stats = sessionsCmd
+        .command('stats')
+        .description('Which skills/commands you actually invoke, and which installed ones are dead weight.')
+        .option('--kind <kind>', 'Limit to one kind: skill or command')
+        .option('--plugin <name>', "Only this plugin's resources (r.plugin), not every resource a plugin-touching session used")
+        .option('-a, --agent <agent>', 'Only sessions from this agent (e.g. claude)')
+        .option('-p, --project <name>', 'Only sessions in this project')
+        .option('--machine <name>', 'Only sessions recorded on this machine (host)')
+        .option('--since <time>', 'Only sessions newer than this (e.g. 7d, 30d, or ISO date)')
+        .option('--top <n>', `How many ranked rows to show (default ${DEFAULT_TOP})`)
+        .option('--bottom', 'Rank the least-invoked resources first instead of the most-invoked')
+        .option('--zero', 'Show only installed-but-never-invoked resources (the dead weight)')
+        .option('--json', 'Output the stats as JSON')
+        .action(async (_opts, cmd) => {
+        await statsAction(cmd);
+    });
+    setHelpSections(stats, {
+        examples: `
+      # Most-invoked skills and commands, plus the installed ones you never invoke
+      agents sessions stats
+
+      # Just the dead weight — installed but never explicitly invoked
+      agents sessions stats --zero
+
+      # Skills only, last 30 days, machine-readable
+      agents sessions stats --kind skill --since 30d --json
+
+      # One plugin's resources, least-used first
+      agents sessions stats --plugin rush --bottom
+
+      # Backfill historical sessions first if coverage is low
+      agents sessions backfill resources
+    `,
+        notes: `
+      - The signal captures EXPLICIT invocations only: slash commands and \`Skill\` tool calls. An auto-triggered skill (loaded by description match) emits no event, so it reads as 0 — that means "never explicitly invoked", not "never loaded".
+      - Skill invocations are recorded for Claude and Kimi; slash-commands for Claude only. Other harnesses contribute nothing to these counts.
+      - Counts come from the SQLite index. New/changed sessions are recorded on their normal scan; run \`agents sessions backfill resources\` once to fold in historical sessions (a low coverage line means it hasn't run).
+      - --plugin filters the resource rows (this plugin's skills/commands), distinct from the top-level \`agents sessions --plugin\` which filters SESSIONS.
+    `,
+    });
+}
+async function statsAction(cmd) {
+    // The parent `sessions` command owns --agent/--project/--plugin/--since/--json
+    // and keeps parsing them past the subcommand name (it has a positional
+    // [query]), binding them to the PARENT — so read the merged view, not the
+    // action's own options. Same reason sessions-favorite.ts uses optsWithGlobals.
+    const opts = cmd.optsWithGlobals();
+    const kind = normalizeKind(opts.kind);
+    const sinceMs = opts.since ? parseTimeFilter(opts.since) : undefined;
+    const top = resolveTop(opts.top);
+    // Warm the incremental index (like `agents cost`) so recent sessions' usage is
+    // current before we read. Historical gaps still need the explicit backfill.
+    await discoverSessions({ all: true, since: opts.since, limit: 1 });
+    const filter = {};
+    if (opts.agent)
+        filter.agent = opts.agent;
+    if (opts.project)
+        filter.project = opts.project;
+    if (opts.machine)
+        filter.machine = opts.machine;
+    if (typeof sinceMs === 'number')
+        filter.sinceMs = sinceMs;
+    const statsOpts = {
+        ...filter,
+        kind,
+        pluginFilter: opts.plugin,
+        order: opts.bottom ? 'bottom' : 'top',
+    };
+    // Full invoked set (no limit) drives both the zero-invoked diff and the totals;
+    // the ranked view is a slice of it.
+    const allInvoked = queryResourceUsageStats(statsOpts);
+    const ranked = top > 0 ? allInvoked.slice(0, top) : allInvoked;
+    const installed = installedResources(kind, opts.plugin, process.cwd());
+    const zeroInvoked = diffZeroInvoked(installed, allInvoked);
+    const coverage = resourceUsageCoverage();
+    const totalInvocations = allInvoked.reduce((s, r) => s + r.invocations, 0);
+    if (opts.json) {
+        process.stdout.write(JSON.stringify({
+            schemaVersion: 1,
+            kind: 'sessions-stats',
+            generatedAt: new Date().toISOString(),
+            filters: {
+                kind: kind ?? null,
+                plugin: opts.plugin ?? null,
+                agent: opts.agent ?? null,
+                project: opts.project ?? null,
+                machine: opts.machine ?? null,
+                since: opts.since ?? null,
+            },
+            signal: {
+                explicitOnly: true,
+                note: 'Explicit invocations only (slash commands + Skill tool calls). Auto-triggered skills emit no event and read as 0. Skill invocations are recorded for Claude and Kimi; slash-commands for Claude only.',
+            },
+            coverage: {
+                sessionsWithUsage: coverage.covered,
+                sessionsIndexed: coverage.total,
+            },
+            totals: {
+                invokedResources: allInvoked.length,
+                invocations: totalInvocations,
+                zeroInvoked: zeroInvoked.length,
+            },
+            order: opts.bottom ? 'bottom' : 'top',
+            ranked: ranked.map(serializeRow),
+            zeroInvoked: zeroInvoked.map(r => ({
+                kind: r.kind,
+                name: r.name,
+                plugin: r.plugin,
+                source: r.source,
+            })),
+        }, null, 2) + '\n');
+        return;
+    }
+    renderHuman({ opts, kind, ranked, zeroInvoked, coverage, totalInvocations, allInvokedCount: allInvoked.length, top });
+}
+function serializeRow(r) {
+    return {
+        kind: r.kind,
+        name: r.name,
+        plugin: r.plugin,
+        source: r.source,
+        sessions: r.sessions,
+        invocations: r.invocations,
+    };
+}
+function normalizeKind(raw) {
+    if (raw === undefined)
+        return undefined;
+    const k = raw.toLowerCase();
+    if (k === 'skill' || k === 'skills')
+        return 'skill';
+    if (k === 'command' || k === 'commands')
+        return 'command';
+    console.error(chalk.red('error: --kind must be one of: skill, command'));
+    process.exit(1);
+}
+function resolveTop(raw) {
+    if (raw === undefined)
+        return DEFAULT_TOP;
+    const n = Number.parseInt(raw, 10);
+    if (!Number.isFinite(n) || n < 0) {
+        console.error(chalk.red('error: --top must be a non-negative integer'));
+        process.exit(1);
+    }
+    return n;
+}
+function renderHuman(args) {
+    const { opts, kind, ranked, zeroInvoked, coverage, totalInvocations, allInvokedCount } = args;
+    const out = [];
+    const scopeBits = [
+        kind ? kind : null,
+        opts.plugin ? `plugin ${opts.plugin}` : null,
+        opts.agent ? opts.agent : null,
+        opts.project ? `project ${opts.project}` : null,
+        opts.machine ? opts.machine : null,
+        opts.since ? `since ${opts.since}` : null,
+    ].filter(Boolean);
+    out.push(chalk.bold('Resource usage') +
+        chalk.gray(`  ·  ${allInvokedCount} invoked · ${totalInvocations} invocation${totalInvocations !== 1 ? 's' : ''}` +
+            (scopeBits.length ? `  ·  ${scopeBits.join(' · ')}` : '')));
+    out.push(chalk.gray(`  coverage: ${coverage.covered}/${coverage.total} sessions carry the signal`) +
+        (coverage.total > 0 && coverage.covered / coverage.total < 0.5
+            ? chalk.yellow('  — run `agents sessions backfill resources` to fold in history')
+            : ''));
+    out.push(chalk.gray('  signal: explicit invocations only (slash commands + Skill tool); auto-triggered skills read as 0; skills from Claude+Kimi, slash-commands Claude-only'));
+    out.push('');
+    // Ranked section (skipped by --zero).
+    if (!opts.zero) {
+        const heading = opts.bottom ? 'Least invoked' : 'Most invoked';
+        out.push(chalk.bold(heading));
+        if (ranked.length === 0) {
+            out.push(chalk.gray('  (no explicit invocations recorded — run the backfill, or nothing has been invoked yet)'));
+        }
+        else {
+            out.push(...renderRankedTable(ranked));
+        }
+        out.push('');
+    }
+    // Zero-invoked section (the dead weight).
+    out.push(chalk.bold('Installed but never invoked') + chalk.gray(`  (${zeroInvoked.length})`));
+    if (zeroInvoked.length === 0) {
+        out.push(chalk.gray('  (every installed resource has at least one explicit invocation in this window)'));
+    }
+    else {
+        const cols = terminalWidth();
+        for (const r of zeroInvoked) {
+            const tag = chalk.gray(`[${r.kind}]`);
+            const owner = r.plugin ? chalk.gray(`  ${r.plugin}`) : r.source ? chalk.gray(`  ${r.source}`) : '';
+            const nameW = Math.max(12, cols - 12 - stringWidth(owner));
+            out.push(`  ${tag} ${truncateToWidth(r.name, nameW)}${owner}`);
+        }
+    }
+    console.log(out.join('\n'));
+}
+function renderRankedTable(rows) {
+    const cols = terminalWidth();
+    const invW = Math.max(...rows.map(r => String(r.invocations).length), 3);
+    const sessW = Math.max(...rows.map(r => `${r.sessions} sess`.length), 6);
+    const lines = [];
+    for (const r of rows) {
+        const inv = String(r.invocations).padStart(invW);
+        const sess = padToWidth(`${r.sessions} sess`, sessW);
+        const tag = chalk.gray(`[${r.kind}]`);
+        const owner = r.plugin ? chalk.gray(`  ${r.plugin}`) : r.source ? chalk.gray(`  ${r.source}`) : '';
+        const prefix = `  ${chalk.green(inv)}  ${chalk.gray(sess)}  ${tag} `;
+        const suffix = owner;
+        const nameW = Math.max(12, cols - stringWidth(prefix) - stringWidth(suffix));
+        lines.push(prefix + truncateToWidth(r.name, nameW) + suffix);
+    }
+    return lines;
+}

package/dist/commands/sessions.d.ts

@@ -389,7 +389,7 @@ export declare function flatSessionRow(session: SessionMeta, live?: ActiveSessio
 export declare function maybeLiveIndex(options: SessionsOptions): Promise<Map<string, ActiveSession> | undefined>;
 /**
  * Group key for the overview: resolve the cwd through the same canonical
- * resolver the `agents activity` timeline groups by — a defined project's name
+ * resolver the `agents feed` timeline groups by — a defined project's name
  * when `defs` contains the cwd (multi-repo projects read as one group), else
  * the repo-level key, so a monorepo subdir (`<repo>/apps/cli`) reads as
  * `<repo>` in both views. Falls back to the indexed project name (stamped at

package/dist/commands/sessions.js

@@ -59,6 +59,7 @@ 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 { registerSessionsStatsCommand } from './sessions-stats.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`;
@@ -2210,7 +2211,7 @@ export async function maybeLiveIndex(options) {
 }
 /**
  * Group key for the overview: resolve the cwd through the same canonical
- * resolver the `agents activity` timeline groups by — a defined project's name
+ * resolver the `agents feed` timeline groups by — a defined project's name
  * when `defs` contains the cwd (multi-repo projects read as one group), else
  * the repo-level key, so a monorepo subdir (`<repo>/apps/cli`) reads as
  * `<repo>` in both views. Falls back to the indexed project name (stamped at
@@ -3643,6 +3644,18 @@ export function registerSessionsCommands(program) {
       # Show only what's running right now (terminals, teams, cloud, headless)
       agents sessions --active
 
+      # --- Session lifecycle (one verb per intent) ---
+      # Jump to a live session (attach its terminal, or open a tab + resume)
+      agents sessions focus a1b2c3d4
+      # Attach only — never fork a copy (old: sessions go)
+      agents sessions focus a1b2c3d4 --attach-only
+      # Interactive → headless (keep working unattended)
+      agents sessions detach a1b2c3d4
+      # Headless → interactive in this terminal
+      agents sessions attach a1b2c3d4
+      # Multi-select history and open each in a tab
+      agents sessions resume
+
       # The interactive list folds in other online machines automatically,
       # labelled by host with this machine first. Stay local with --local:
       agents sessions --local
@@ -3683,6 +3696,12 @@ export function registerSessionsCommands(program) {
       agents sessions --all "deploy script" --host box-a --host box-b
     `,
         notes: `
+      Session lifecycle (pick one verb — they are not synonyms):
+        focus [id]              jump to a live session (attach, or open tab + resume)
+        focus [id] --attach-only  attach only; never fork (replaces sessions go)
+        detach <id>             interactive → headless continuation
+        attach <id>             headless → interactive in this terminal
+        resume [query]          multi-select history → open tabs (or run --resume <id>)
       - The interactive listing folds in your other online machines automatically (live over SSH, no sync) — each row is labelled by host, this machine first. Use --local to skip the fan-out; --json and single-id lookups stay local.
       - --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.
@@ -3720,6 +3739,7 @@ export function registerSessionsCommands(program) {
     registerSessionsMigrateCommand(sessionsCmd);
     registerSessionsMigrationsCommand(sessionsCmd);
     registerSessionsBackfillCommand(sessionsCmd);
+    registerSessionsStatsCommand(sessionsCmd);
 }
 function formatNoSessionsMessage(showAll, project) {
     const projectQuery = project?.trim();

package/dist/commands/snapshot.d.ts

@@ -0,0 +1,11 @@
+/**
+ * `agents snapshot` — one-process consumer snapshot for pollers.
+ *
+ * Replaces the N× `view --json` + `sessions --active --json` (+ optional feed)
+ * fork storm with a single command. Does NOT replace `agents status`, which
+ * remains the UnifiedSyncStatus sync contract for menubar / Agency drift.
+ *
+ * JSON shape: {@link FleetSnapshot} in `lib/snapshot.ts` (version: 1).
+ */
+import type { Command } from 'commander';
+export declare function registerSnapshotCommand(program: Command): void;

package/dist/commands/snapshot.js

@@ -0,0 +1,107 @@
+/**
+ * `agents snapshot` — one-process consumer snapshot for pollers.
+ *
+ * Replaces the N× `view --json` + `sessions --active --json` (+ optional feed)
+ * fork storm with a single command. Does NOT replace `agents status`, which
+ * remains the UnifiedSyncStatus sync contract for menubar / Agency drift.
+ *
+ * JSON shape: {@link FleetSnapshot} in `lib/snapshot.ts` (version: 1).
+ */
+import chalk from 'chalk';
+import { addHostOption } from '../lib/hosts/option.js';
+import { setHelpSections } from '../lib/help.js';
+import { resolveAgentName, AGENTS } from '../lib/agents.js';
+import { computeSnapshot } from '../lib/snapshot.js';
+import { resolveSurface } from './utils.js';
+function resolveAgentFilter(raw) {
+    if (!raw)
+        return undefined;
+    const name = resolveAgentName(raw.split('@')[0]);
+    if (!name) {
+        console.error(chalk.red(`Unknown agent "${raw}".`));
+        process.exit(1);
+    }
+    return name;
+}
+/** Compact human summary — the JSON path is the real contract. */
+function renderHuman(snap) {
+    console.log(chalk.bold('Fleet snapshot') + chalk.gray(`  ·  ${snap.host}  ·  ${snap.capturedAt}`));
+    const invParts = [];
+    for (const a of snap.inventory) {
+        if (a.versions.length === 0)
+            continue;
+        const def = a.versions.find((v) => v.isDefault) ?? a.versions[0];
+        const label = AGENTS[a.agent]?.name ?? a.agent;
+        const signed = def.signedIn ? chalk.green('in') : chalk.gray('out');
+        invParts.push(`${label}@${def.version} (${signed})`);
+    }
+    console.log(`  ${'Inventory'.padEnd(12)} ${invParts.length ? invParts.join(chalk.gray(' · ')) : chalk.gray('(none installed)')}`);
+    const { running, live, byContext, byAgent } = snap.agents;
+    const ctx = Object.entries(byContext)
+        .map(([k, n]) => `${k}:${n}`)
+        .join(' ');
+    const ag = Object.entries(byAgent)
+        .map(([k, n]) => `${k}:${n}`)
+        .join(' ');
+    console.log(`  ${'Sessions'.padEnd(12)} ${live} live · ${running} running` +
+        (snap.remoteDeviceCount > 0 ? chalk.gray(` · ${snap.remoteDeviceCount} remote device(s)`) : '') +
+        (ctx ? chalk.gray(` · ${ctx}`) : '') +
+        (ag ? chalk.gray(` · ${ag}`) : ''));
+    if (snap.feed) {
+        console.log(`  ${'Feed'.padEnd(12)} ${snap.feed.openBlocks} open block${snap.feed.openBlocks === 1 ? '' : 's'}`);
+    }
+    if (snap.sync) {
+        const need = snap.sync.agents.filter((a) => a.needsSync).length;
+        const sys = snap.sync.system.unknown
+            ? 'system unknown'
+            : snap.sync.system.behind > 0
+                ? `system ${snap.sync.system.behind} behind`
+                : 'system ok';
+        console.log(`  ${'Sync'.padEnd(12)} ${sys} · ${need} version${need === 1 ? '' : 's'} need sync`);
+    }
+    console.log(chalk.gray('\n  Machine-readable: agents snapshot --json\n' +
+        '  Sync-only (unchanged): agents status --json'));
+}
+export function registerSnapshotCommand(program) {
+    const cmd = addHostOption(program
+        .command('snapshot')
+        .description('One-process poll snapshot: install inventory + active sessions (optional feed/sync). Not the sync-status command — use `agents status` for drift.'))
+        .option('--json', 'Emit the machine-readable FleetSnapshot contract (version 1)')
+        .option('--all-hosts', 'Include remote devices in the sessions gather (same fan-out as `sessions --active`; default is this machine only)')
+        .option('--with-feed', 'Include open feed-block summary (needs-you count + compact rows)')
+        .option('--with-sync', 'Include UnifiedSyncStatus (same engine as `agents status`; opt-in)')
+        .option('--agent <name>', 'Restrict inventory to one agent (e.g. claude)');
+    setHelpSections(cmd, {
+        examples: `
+      # One-shot inventory + local active sessions (JSON)
+      agents snapshot --json
+
+      # Same, plus open feed blocks for needs-you polls
+      agents snapshot --json --with-feed
+
+      # Fleet-wide active sessions (matches sessions --active scope)
+      agents snapshot --json --all-hosts
+
+      # Inventory for one harness only (Factory-style usage poll)
+      agents snapshot --json --agent claude
+
+      # Run the whole snapshot on another device
+      agents snapshot --json --host yosemite-s0
+    `,
+    });
+    cmd.action(async (opts, command) => {
+        const surface = resolveSurface(command);
+        const agent = resolveAgentFilter(opts.agent);
+        const snap = await computeSnapshot({
+            agent,
+            local: opts.allHosts !== true,
+            withFeed: opts.withFeed === true,
+            withSync: opts.withSync === true,
+        });
+        if (surface.json || opts.json) {
+            console.log(JSON.stringify(snap, null, 2));
+            return;
+        }
+        renderHuman(snap);
+    });
+}

package/dist/commands/teams.js

@@ -275,7 +275,8 @@ function throttleWarningLine(agent, version, r) {
     const acct = r.email ? ` (${r.email})` : '';
     const reason = r.reason === 'out_of_credits' ? 'is out of credits'
         : r.reason === 'signed_out' ? 'is not signed in'
-            : 'is rate-limited right now';
+            : r.reason === 'revoked' ? 'needs re-login (its token was revoked)'
+                : 'is rate-limited right now';
     return (chalk.yellow(`⚠ ${who}${acct} ${reason}.`) +
         chalk.gray(`\n  A pinned version skips account rotation, so it will launch on this account and may immediately hit its limit.` +
             `\n  Use a bare \`${agent}\` teammate to let the team pick a healthy account, or pass --force to silence this.`));

package/dist/commands/view.d.ts

@@ -12,6 +12,7 @@ import type { AccountInfo } from '../lib/agents.js';
 import type { AgentId } from '../lib/types.js';
 import { type ConfiguredModelSource } from '../lib/models.js';
 import { type ProfileSummary } from '../lib/profiles.js';
+import { type ByokUsageResult } from '../lib/byok-usage.js';
 /** Shared account identity formatter, re-exported for the view-specific tests. */
 export declare const accountColumnLabel: typeof accountDisplayLabel;
 /**
@@ -46,7 +47,7 @@ export declare function descriptionForPrefix(desc: string | undefined, prefix: s
  * `installedHosts` is the set of agent ids with a usable install; a harness whose
  * host is missing is flagged rather than silently listed as runnable.
  */
-export declare function renderHarnessBlocks(harnesses: ProfileSummary[], installedHosts: Set<AgentId>, showPaths: boolean): void;
+export declare function renderHarnessBlocks(harnesses: ProfileSummary[], installedHosts: Set<AgentId>, showPaths: boolean, byokMap?: Map<string, ByokUsageResult>): void;
 /** Machine-readable entry for a single installed version. */
 export interface ViewJsonVersion {
     version: string;
@@ -128,6 +129,13 @@ export declare function parseResourceSections(options: {
     resources?: string | boolean;
     detailed?: boolean;
 } & ViewSectionFilter, jsonMode: boolean): Set<ResourceSection>;
+/**
+ * Collect structured info for one or more agents without rendering to the
+ * terminal. Used by `--json` output and any programmatic consumer (e.g. the
+ * agents-cli extension's "resume current session in best available version"
+ * command).
+ */
+export declare function collectAgentsJson(filterAgentId?: AgentId, resourceSections?: Set<ResourceSection>): Promise<ViewJsonAgent[]>;
 /**
  * Identity key for duplicate-install detection. Prefers accountKey — which
  * encodes account AND org — over the bare email: two installs can share an

package/dist/commands/view.js

@@ -27,6 +27,7 @@ import { getConfiguredRunStrategy } from '../lib/rotate.js';
 import { resolveRunDefaults } from '../lib/run-defaults.js';
 import { resolveConfiguredModel } from '../lib/models.js';
 import { listProfiles, profileExists, profileSummary, readProfile } from '../lib/profiles.js';
+import { getByokUsageForHarness, hasByokProvider, renderByokBar } from '../lib/byok-usage.js';
 import { renderHarnessDetail } from './harness.js';
 import { loadManifest, isStale } from '../lib/staleness/index.js';
 import { confirm } from '@inquirer/prompts';
@@ -67,9 +68,28 @@ function getHarnesses(filterAgentId) {
         .filter((profile) => !filterAgentId || profile.host.agent === filterAgentId)
         .map(profileSummary);
 }
-/** "via <host> <version>" — which native harness actually executes this one. */
-function harnessHostTag(harness) {
-    return harness.hostVersion ? `via ${harness.agent} ${harness.hostVersion}` : `via ${harness.agent}`;
+/** Version-first label: "<version> (forked from <host>[, tracks default])" */
+function harnessVersionLabel(harness, globalDefault) {
+    const version = harness.hostVersion ?? globalDefault;
+    if (version) {
+        const trailer = harness.hostVersion
+            ? chalk.gray(` (forked from ${harness.agent})`)
+            : chalk.gray(` (forked from ${harness.agent}, `) +
+                chalk.green(`tracks default`) +
+                chalk.gray(`)`);
+        return `${version}${trailer}`;
+    }
+    return chalk.gray(`(forked from ${harness.agent})`);
+}
+/** One-hop or two-hop fork origin label for the harness block header. */
+function buildHarnessOrigin(harness, allHarnesses) {
+    if (!harness.forkedFrom || harness.forkedFrom === harness.agent)
+        return 'custom';
+    const parent = allHarnesses.find((h) => h.name === harness.forkedFrom);
+    if (parent?.forkedFrom) {
+        return `custom · forked from ${harness.forkedFrom} -> ${parent.forkedFrom}`;
+    }
+    return `custom · forked from ${harness.forkedFrom}`;
 }
 /**
  * Resolve a resource path to something the IDE can open inline. When `p` is a
@@ -172,24 +192,23 @@ export function descriptionForPrefix(desc, prefix) {
  * `installedHosts` is the set of agent ids with a usable install; a harness whose
  * host is missing is flagged rather than silently listed as runnable.
  */
-export function renderHarnessBlocks(harnesses, installedHosts, showPaths) {
+export function renderHarnessBlocks(harnesses, installedHosts, showPaths, byokMap) {
     if (harnesses.length === 0)
         return;
     const modelWidth = Math.max(...harnesses.map((h) => h.model.length));
     const authWidth = Math.max(...harnesses.map((h) => h.auth.length));
     for (const harness of harnesses) {
-        // The `via <host>` tag on the row already names a native fork parent, so
-        // only a fork of another custom harness adds lineage worth printing.
-        const origin = harness.forkedFrom && harness.forkedFrom !== harness.agent
-            ? `custom · forked from ${harness.forkedFrom}`
-            : 'custom';
+        const origin = buildHarnessOrigin(harness, harnesses);
         const missingHost = installedHosts.has(harness.agent)
             ? ''
             : chalk.yellow(` (host ${harness.agent} not installed)`);
         console.log(`  ${chalk.bold(harness.label)}${chalk.gray(` (${origin})`)}${missingHost}`);
+        const versionTag = harnessVersionLabel(harness, getGlobalDefault(harness.agent));
+        const byokEntry = byokMap?.get(harness.name);
+        const byokBar = byokEntry ? `  ${renderByokBar(byokEntry)}` : '';
         console.log(`    ${chalk.yellow(harness.model.padEnd(modelWidth))}  ` +
             `${chalk.cyan(harness.auth.padEnd(authWidth))}  ` +
-            chalk.gray(harnessHostTag(harness)));
+            versionTag + byokBar);
         if (showPaths)
             console.log(chalk.gray(`      ${harness.path}`));
         console.log();
@@ -616,7 +635,39 @@ async function showInstalledVersions(filterAgentId, viewOpts) {
     // Custom harnesses sit in the same list as the native ones — they are run the
     // same way (`agents run <name>`), so they read as their own agent type rather
     // than as an indented row under whichever host CLI executes them.
-    renderHarnessBlocks(harnesses, installedHosts, showPaths);
+    const byokMap = new Map();
+    const byKeychainItem = new Map();
+    for (const h of harnesses) {
+        if (!h.provider || !hasByokProvider(h.provider))
+            continue;
+        let prof = null;
+        try {
+            prof = readProfile(h.name);
+        }
+        catch {
+            continue;
+        }
+        if (!prof.auth)
+            continue;
+        const item = prof.auth.keychainItem;
+        const existing = byKeychainItem.get(item);
+        if (existing) {
+            existing.names.push(h.name);
+        }
+        else {
+            byKeychainItem.set(item, { profile: prof, names: [h.name] });
+        }
+    }
+    if (byKeychainItem.size > 0) {
+        const fetched = await Promise.all([...byKeychainItem.values()].map(({ profile, names }) => getByokUsageForHarness(profile, { forceRefresh: viewOpts?.forceRefresh }).then((result) => ({ result, names }))));
+        for (const { result, names } of fetched) {
+            if (!result?.budget)
+                continue;
+            for (const name of names)
+                byokMap.set(name, result);
+        }
+    }
+    renderHarnessBlocks(harnesses, installedHosts, showPaths, byokMap.size > 0 ? byokMap : undefined);
     // Show globally installed (not managed) agents
     if (globallyInstalled.length > 0) {
         console.log(chalk.bold('Not Managed by Agents CLI\n'));
@@ -1191,7 +1242,7 @@ export function parseResourceSections(options, jsonMode) {
  * agents-cli extension's "resume current session in best available version"
  * command).
  */
-async function collectAgentsJson(filterAgentId, resourceSections) {
+export async function collectAgentsJson(filterAgentId, resourceSections) {
     const agentsToShow = filterAgentId ? [filterAgentId] : ALL_AGENT_IDS;
     const wantResources = !!resourceSections && resourceSections.size > 0;
     // Only pay for the git-status + resource scans when resources were requested.

package/dist/index.js

@@ -94,7 +94,7 @@ if (IS_DEV_BUILD) {
 // module on each invocation (which loaded the whole ~50-module tree before the
 // first byte of output), the registry maps a command name to a thunk that
 // imports only what that command needs. See src/lib/startup/command-registry.ts.
-import { COMMAND_LOADERS, LAZY_COMMAND_NAMES, loadView, loadInspect, loadFeedback, loadCommands, loadHooks, loadSkills, loadRules, loadMemory, loadPermissions, loadMcp, loadCli, loadSubagents, loadPlugins, loadWorkflows, loadWorktree, loadVersions, loadImport, loadExport, loadPackages, loadRoutines, loadMonitors, loadProjects, loadRun, loadFork, loadDefaults, loadSet, loadModels, loadPrune, loadTrash, loadRestore, loadDoctor, loadApply, loadStatus, loadProfiles, loadHarness, loadSecrets, loadLogin, loadWallet, loadHelper, loadMenubar, loadBeta, loadSync, loadLock, loadRefreshRules, loadFactory, loadUsage, loadCost, loadPerf, loadTrends, loadOutput, loadBudget, loadAlias, loadMine, loadPty, loadTmux, loadWatchdog, loadBrowser, loadComputer, loadHosts, loadLogs, loadEvents, loadAudit, loadWebhook, loadFunnel, loadSsh, loadPull, loadPush, loadRepo, loadSetup, loadUninstall, loadShare, loadSend, loadFeed, loadActivity, loadMailboxes, } from './lib/startup/command-registry.js';
+import { COMMAND_LOADERS, LAZY_COMMAND_NAMES, loadView, loadInspect, loadFeedback, loadCommands, loadHooks, loadSkills, loadRules, loadMemory, loadPermissions, loadMcp, loadCli, loadSubagents, loadPlugins, loadWorkflows, loadWorktree, loadVersions, loadImport, loadExport, loadPackages, loadRoutines, loadMonitors, loadProjects, loadRun, loadFork, loadDefaults, loadSet, loadModels, loadPrune, loadTrash, loadRestore, loadDoctor, loadApply, loadStatus, loadSnapshot, loadProfiles, loadHarness, loadSecrets, loadLogin, loadWallet, loadHelper, loadMenubar, loadBeta, loadSync, loadLock, loadRefreshRules, loadFactory, loadUsage, loadCost, loadPerf, loadTrends, loadOutput, loadBudget, loadAlias, loadMine, loadPty, loadTmux, loadWatchdog, loadBrowser, loadComputer, loadHosts, loadLogs, loadEvents, loadAudit, loadWebhook, loadFunnel, loadSsh, loadPull, loadPush, loadRepo, loadSetup, loadUninstall, loadShare, loadSend, loadFeed, loadMailboxes, } from './lib/startup/command-registry.js';
 import { applyGlobalHelpConventions } from './lib/help.js';
 import { renderWhatsNew } from './lib/whats-new.js';
 import { getCliLaunch } from './lib/cli-entry.js';
@@ -317,6 +317,8 @@ Credentials and profiles:
 
 Diagnostics:
   doctor [agent[@version]]        Diagnose CLI availability, sync status, and resource divergence; --check for the CI drift gate
+  status                          Unified sync status (drift/missing) — not the live fleet snapshot
+  snapshot                        One-process poll: inventory + active sessions (+ optional feed/sync)
   usage [agent]                   Show rate-limit and quota usage per agent
   perf                            Latency rollups (hooks, commands, runs) from the disposable perf warehouse
 
@@ -938,6 +940,7 @@ async function registerAllEagerCommands() {
     registerCheckTombstoneCommand(program);
     await reg(loadApply);
     await reg(loadStatus);
+    await reg(loadSnapshot);
     registerExecAliasCommand(program);
     await reg(loadProfiles);
     await reg(loadHarness);
@@ -972,7 +975,6 @@ async function registerAllEagerCommands() {
     await reg(loadFunnel);
     registerHqTombstoneCommand(program);
     await reg(loadFeed);
-    await reg(loadActivity);
     await reg(loadMailboxes);
     await reg(loadSsh);
     registerJobsCronAliasCommand(program, 'jobs');