@phnx-labs/agents-cli 1.22.25 → 1.22.27

package/dist/commands/trends.js

@@ -1,158 +1,12 @@
-import chalk from 'chalk';
-import { setHelpSections } from '../lib/help.js';
-import { buildTrendsDashboard, trendsWindow, runRecipe, RECIPE_IDS } from '../lib/analytics/dashboard.js';
-import { listRecipes } from '../lib/analytics/recipes.js';
-import { queryUsage, usageDbPath, USAGE_KINDS } from '../lib/analytics/usage-db.js';
-function parseDays(raw) {
-    const n = parseInt(raw ?? '7', 10);
-    return Number.isFinite(n) && n > 0 ? n : 7;
-}
-function parseLimit(raw, fallback) {
-    const n = parseInt(raw ?? String(fallback), 10);
-    return Number.isFinite(n) && n > 0 ? n : fallback;
-}
-function printSection(section) {
-    console.log(chalk.bold(section.title));
-    if (section.rows.length === 0) {
-        console.log(chalk.gray('  (no data)'));
-        console.log();
-        return;
-    }
-    const keys = Object.keys(section.rows[0]);
-    const widths = keys.map((k) => Math.max(k.length, ...section.rows.map((r) => String(r[k] ?? '').length), 4));
-    const pad = (s, w) => (s.length >= w ? s.slice(0, w) : s + ' '.repeat(w - s.length));
-    console.log(chalk.gray(keys.map((k, i) => pad(k.toUpperCase(), widths[i])).join('  ')));
-    for (const row of section.rows) {
-        console.log(keys.map((k, i) => pad(String(row[k] ?? ''), widths[i])).join('  '));
-    }
-    console.log();
-}
-function renderDashboard(days, asJson) {
-    const dash = buildTrendsDashboard({ days });
-    if (asJson) {
-        console.log(JSON.stringify(dash, null, 2));
-        return;
-    }
-    console.log(chalk.bold(`agents trends — last ${dash.window.days} days`));
-    console.log(chalk.gray(`compute ${dash.durationMs}ms · usage ${usageDbPath()}`));
-    console.log();
-    if (dash.sections.length === 0) {
-        console.log(chalk.gray('No session or usage data in this window yet.'));
-        return;
-    }
-    for (const section of dash.sections)
-        printSection(section);
-}
+/**
+ * Deprecated top-level spelling of the counter-mix tree.
+ *
+ * Implementation lives under `agents insights mix` (see
+ * `lib/analytics/mix-commands.ts`). This file only registers the thin alias so
+ * old scripts and agent briefs keep working while printing one deprecation line
+ * — no second recipe implementation.
+ */
+import { registerDeprecatedTrendsAlias } from '../lib/analytics/mix-commands.js';
 export function registerTrendsCommand(program) {
-    const trends = program
-        .command('trends')
-        .description('Usage analytics — harness/model mix, token ratios, resource frequency')
-        .option('--days <n>', 'Days of history to include', '7')
-        .option('--json', 'Emit JSON instead of tables')
-        .action(function summary() {
-        const opts = this.opts();
-        renderDashboard(parseDays(opts.days), Boolean(opts.json));
-    });
-    setHelpSections(trends, {
-        examples: `
-      # Auto recipe dashboard (7d)
-      agents trends
-
-      # Last 30 days
-      agents trends --days 30
-
-      # One recipe as JSON
-      agents trends harness-mix --json
-
-      # Raw usage events
-      agents trends query --kind secret --days 7
-
-      # List baked recipe ids
-      agents trends recipes
-    `,
-        notes: `
-      Session recipes read sessions.db; resource recipes read ~/.agents/.history/analytics/usage.db.
-      Empty recipes are skipped on the default dashboard.
-      Quota / rate-limits remain on \`agents usage\`; latency on \`agents perf\`.
-    `,
-    });
-    trends.command('recipes')
-        .description('List baked recipe ids')
-        .option('--json', 'Emit JSON')
-        .action((opts) => {
-        const list = listRecipes();
-        if (opts.json) {
-            console.log(JSON.stringify(list, null, 2));
-            return;
-        }
-        for (const r of list) {
-            console.log(`${r.id.padEnd(22)} ${r.store.padEnd(10)} ${r.title}`);
-        }
-    });
-    trends.command('query')
-        .description('Raw usage-event query')
-        .option('--kind <kind>', `One of: ${USAGE_KINDS.join(', ')}`)
-        .option('--name <name>', 'Resource name filter')
-        .option('--event <event>', 'Event name filter')
-        .option('--days <n>', 'Days of history', '7')
-        .option('--limit <n>', 'Max rows', '40')
-        .option('--json', 'Emit JSON')
-        .action((opts) => {
-        const win = trendsWindow(parseDays(opts.days));
-        const kind = opts.kind && USAGE_KINDS.includes(opts.kind)
-            ? opts.kind
-            : undefined;
-        if (opts.kind && !kind) {
-            console.error(`Unknown kind '${opts.kind}'. Expected: ${USAGE_KINDS.join(', ')}`);
-            process.exitCode = 1;
-            return;
-        }
-        const rows = queryUsage({
-            kind,
-            name: opts.name,
-            event: opts.event,
-            sinceIso: win.sinceIso,
-            limit: parseLimit(opts.limit, 40),
-        });
-        if (opts.json) {
-            console.log(JSON.stringify({ window: win, rows }, null, 2));
-            return;
-        }
-        if (rows.length === 0) {
-            console.log(chalk.gray('No usage events.'));
-            return;
-        }
-        printSection({
-            id: 'query',
-            title: 'Usage events',
-            rows: rows.map((r) => ({
-                ts: r.ts,
-                kind: r.kind,
-                name: r.name,
-                event: r.event,
-                agent: r.agent,
-            })),
-        });
-    });
-    for (const id of RECIPE_IDS) {
-        trends.command(id)
-            .description(`Recipe: ${id}`)
-            .option('--days <n>', 'Days of history', '7')
-            .option('--json', 'Emit JSON')
-            .action(function recipeAction() {
-            const parent = this.parent?.opts?.();
-            const opts = { ...parent, ...this.opts() };
-            const win = trendsWindow(parseDays(opts.days));
-            const section = runRecipe(id, win);
-            if (opts.json) {
-                console.log(JSON.stringify({ window: win, section }, null, 2));
-                return;
-            }
-            if (section.empty) {
-                console.log(chalk.gray(`No data for recipe '${id}' in the last ${win.days} days.`));
-                return;
-            }
-            printSection(section);
-        });
-    }
+    registerDeprecatedTrendsAlias(program);
 }

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, loadModes, loadPrune, loadTrash, loadRestore, loadDoctor, loadApply, loadStatus, loadSnapshot, loadProfiles, loadHarness, loadSecrets, loadLogin, loadWallet, loadHelper, loadMenubar, loadBeta, loadSync, loadLock, loadRefreshRules, loadFactory, loadUsage, loadCost, loadInsights, loadPerf, loadTrends, loadOutput, loadBudget, loadAlias, loadMine, loadPty, loadTmux, loadWatchdog, loadBrowser, loadComputer, loadHosts, loadLogs, loadEvents, loadAudit, loadWebhook, loadFunnel, loadHumans, loadSsh, loadPull, loadPush, loadRepo, loadSetup, loadUninstall, loadShare, loadSend, loadFeed, 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, loadModes, loadPrune, loadTrash, loadRestore, loadDoctor, loadApply, loadStatus, loadSnapshot, loadProfiles, loadHarness, loadSecrets, loadLogin, loadWallet, loadHelper, loadMenubar, loadBeta, loadSync, loadLock, loadRefreshRules, loadFactory, loadUsage, loadCost, loadInsights, loadPerf, loadTrends, loadOutput, loadBudget, loadAlias, loadMine, loadPty, loadTmux, loadWatchdog, loadBrowser, loadComputer, loadHosts, loadLogs, loadEvents, loadAudit, loadWebhook, loadFunnel, loadHumans, loadSsh, loadPull, loadPush, loadRepo, loadSetup, loadUninstall, loadBench, 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';
@@ -327,7 +327,7 @@ Credentials and profiles:
 Diagnostics:
   doctor [agent[@version]]        Diagnose CLI availability, sync status, and resource divergence; --check for the CI drift gate
   usage [agent]                   Show rate-limit and quota usage per agent
-  insights                        How you work — tools, friction, rhythm, split by Claude account
+  insights                        How work looks — behaviour (default) or counter mix (insights mix)
   perf                            Latency rollups (hooks, commands, runs) from the disposable perf warehouse
 
 Config sync:
@@ -392,15 +392,15 @@ async function showWhatsNew(fromVersion, toVersion) {
 const UPDATE_CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000; // 24 hours
 import { getUpdateCheckPath, getMigratedSentinelPath, getUserAgentsDir, getRuntimeStateDir } from './lib/state.js';
 import { resolveBrandName, disabledCommandsForActiveBrand } from './lib/brand.js';
-import { readUpdateCache, saveUpdateCheck, dismissUpdateVersion, shouldPromptUpgrade, findAgentsCliInstalls, resolveRunningPackageRoot, } from './lib/self-update.js';
+import { readUpdateCache, saveUpdateCheck, dismissUpdateVersion, shouldPromptUpgrade, buildMultiInstallInventory, findAgentsCliInstalls, resolveRunningPackageRoot, } from './lib/self-update.js';
 const UPDATE_CHECK_FILE = getUpdateCheckPath();
 /**
- * Warn once when PATH resolves `agents` to a different agents-cli install
- * than the copy that is currently running (or to several). Divergent installs
+ * Warn once when this machine contains a different agents-cli install than the
+ * copy that is currently running (or several). Divergent installs
  * are how self-updates "succeed" without changing the command the user types.
- * The warning re-fires only when the set of install roots changes; dev builds
- * (0.0.0-dev) are ignored because side-by-side dev installs are a supported
- * workflow.
+ * The warning re-fires only when the set of install roots or their helper-copy
+ * safety changes. Dev builds are included because old dev copies can still
+ * overwrite the shared macOS helper bundle non-atomically.
  */
 function maybeWarnMultiInstall() {
     const sentinel = path.join(getRuntimeStateDir(), 'multi-install-warned');
@@ -414,31 +414,26 @@ function maybeWarnMultiInstall() {
         // "/$bunfs" install. This warning is advisory — stay silent instead.
         return;
     }
-    const byRoot = new Map();
-    byRoot.set(runningRoot, { version: VERSION, note: 'running' });
-    for (const install of findAgentsCliInstalls(process.env.PATH || '')) {
-        if (install.version.startsWith('0.0.0-dev'))
-            continue;
-        if (!byRoot.has(install.packageRoot)) {
-            byRoot.set(install.packageRoot, { version: install.version, note: `agents on PATH: ${install.binPath}` });
-        }
-    }
-    if (byRoot.size < 2) {
+    const inventory = buildMultiInstallInventory(runningRoot, VERSION, findAgentsCliInstalls(process.env.PATH || ''));
+    if (inventory.length < 2) {
         try {
             fs.unlinkSync(sentinel);
         }
         catch { /* nothing recorded */ }
         return;
     }
-    const key = [...byRoot.keys()].sort().join('\n');
+    const key = inventory
+        .map((info) => `${info.packageRoot}\t${info.version}\t${info.note}`)
+        .sort()
+        .join('\n');
     try {
         if (fs.readFileSync(sentinel, 'utf-8') === key)
             return;
     }
     catch { /* not warned for this set yet */ }
     console.error(chalk.yellow('Multiple agents-cli installs detected:'));
-    for (const [root, info] of byRoot) {
-        console.error(chalk.gray(`  ${root}  ${info.version}  (${info.note})`));
+    for (const info of inventory) {
+        console.error(chalk.gray(`  ${info.packageRoot}  ${info.version}  (${info.note})`));
     }
     console.error(chalk.gray('Upgrades apply to the running copy. Remove a stale copy with: npm uninstall -g --prefix <prefix> @phnx-labs/agents-cli'));
     try {
@@ -967,6 +962,7 @@ async function registerAllEagerCommands() {
     await reg(loadCost);
     await reg(loadInsights);
     await reg(loadPerf);
+    await reg(loadBench);
     await reg(loadTrends);
     await reg(loadOutput);
     await reg(loadBudget);

package/dist/lib/agents.d.ts

@@ -34,6 +34,17 @@ export declare function findInPath(command: string): string | null;
 export declare const AGENTS: Record<AgentId, AgentConfig>;
 /** All current and legacy agent IDs derived from the AGENTS registry. */
 export declare const ALL_AGENT_IDS: AgentId[];
+/**
+ * CLI command templates per agent for daemon-fired routine jobs, with
+ * {prompt} as a placeholder. Lives here (not runner.ts) so routines.ts can
+ * import ROUTINE_AGENT_IDS for schedule-time validation without a circular
+ * import (runner.ts already imports from routines.ts).
+ */
+export declare const ROUTINE_AGENT_COMMANDS: Record<string, string[]>;
+/** Agents the routine daemon can actually run when firing locally, derived
+ * from the command table above so the `--agent` help and validateJob's
+ * schedule-time check can never drift from it. */
+export declare const ROUTINE_AGENT_IDS: readonly string[];
 /** Agents retained only for legacy reads, not install/import/sync targets. */
 export declare const HARD_DEPRECATED_AGENT_IDS: AgentId[];
 /** Agents that can receive managed installs, imports, and resource sync writes. */

package/dist/lib/agents.js

@@ -384,14 +384,22 @@ export const AGENTS = {
         instructionsFile: 'workspace/AGENTS.md', // Primary memory file (also has SOUL.md, IDENTITY.md, etc.)
         format: 'markdown',
         variableSyntax: '{{ARGUMENTS}}',
-        supportsHooks: true,
+        // hooks: NOT supported. OpenClaw only exposes a fixed set of internal,
+        // named hooks (e.g. `boot-md`, which runs BOOT.md on gateway restart) —
+        // there is no general event->shell-command registration surface (no
+        // PreToolUse/PostToolUse/UserPromptSubmit equivalent an agents-cli
+        // hooks.yaml manifest could target). registerHooksToSettings has no
+        // `openclaw` case and silently no-ops (RUSH-2122: capability claimed
+        // hooks:true with zero hooks ever installed). Flip back to `true` only
+        // alongside a real registerHooksForOpenClaw implementation.
+        supportsHooks: false,
         // allowlist: maps blanket (whole-tool) rules to ~/.openclaw/openclaw.json
         // tools.alsoAllow (allow) / tools.deny (deny). OpenClaw gates at tool
         // granularity only, so sub-command/path/domain patterns are skipped.
         // OpenClaw is self-updating (no pinned since), so `true` is correct.
         // Workflows sync as Lobster `.lobster` files under `.openclaw/workflows/`;
         // the Lobster tool runs them by receiving the file path as `pipeline`.
-        capabilities: { hooks: true, mcp: true, mcpHttp: false, mcpHeaders: false, allowlist: true, skills: true, commands: false, plugins: true, subagents: true, rules: { file: 'workspace/AGENTS.md' }, workflows: true, memory: true, modes: ['plan', 'edit', 'skip'], interactiveRepl: true },
+        capabilities: { hooks: false, mcp: true, mcpHttp: false, mcpHeaders: false, allowlist: true, skills: true, commands: false, plugins: true, subagents: true, rules: { file: 'workspace/AGENTS.md' }, workflows: true, memory: true, modes: ['plan', 'edit', 'skip'], interactiveRepl: true },
     },
     copilot: {
         id: 'copilot',
@@ -884,6 +892,25 @@ export const AGENTS = {
 };
 /** All current and legacy agent IDs derived from the AGENTS registry. */
 export const ALL_AGENT_IDS = Object.keys(AGENTS);
+/**
+ * CLI command templates per agent for daemon-fired routine jobs, with
+ * {prompt} as a placeholder. Lives here (not runner.ts) so routines.ts can
+ * import ROUTINE_AGENT_IDS for schedule-time validation without a circular
+ * import (runner.ts already imports from routines.ts).
+ */
+export const ROUTINE_AGENT_COMMANDS = {
+    claude: ['claude', '-p', '--verbose', '{prompt}', '--output-format', 'stream-json', '--permission-mode', 'plan'],
+    codex: ['codex', 'exec', '{prompt}', '--json'],
+    gemini: ['gemini', '{prompt}', '--output-format', 'stream-json'],
+    cursor: ['cursor-agent', '-p', '{prompt}', '--output-format', 'stream-json'],
+    kimi: ['kimi', '--prompt', '{prompt}', '--output-format', 'stream-json'],
+    droid: ['droid', 'exec', '{prompt}', '-o', 'stream-json'],
+    muse: ['muse', 'exec', '{prompt}', '--json'],
+};
+/** Agents the routine daemon can actually run when firing locally, derived
+ * from the command table above so the `--agent` help and validateJob's
+ * schedule-time check can never drift from it. */
+export const ROUTINE_AGENT_IDS = Object.freeze(Object.keys(ROUTINE_AGENT_COMMANDS));
 /** Agents retained only for legacy reads, not install/import/sync targets. */
 export const HARD_DEPRECATED_AGENT_IDS = ALL_AGENT_IDS.filter((id) => AGENTS[id].deprecated?.hard);
 /** Agents that can receive managed installs, imports, and resource sync writes. */

package/dist/lib/analytics/dashboard.d.ts

@@ -1,11 +1,15 @@
-import { RECIPE_IDS, runRecipe, trendsWindow, type RecipeId, type RecipeSection, type TrendsWindow } from './recipes.js';
-export interface TrendsDashboard {
-    window: TrendsWindow;
+import { RECIPE_IDS, runRecipe, analyticsWindow, type RecipeId, type RecipeSection, type AnalyticsWindow } from './recipes.js';
+export interface MixDashboard {
+    window: AnalyticsWindow;
     durationMs: number;
     sections: RecipeSection[];
 }
-export declare function buildTrendsDashboard(opts?: {
+/** @deprecated Use MixDashboard. */
+export type TrendsDashboard = MixDashboard;
+export declare function buildMixDashboard(opts?: {
     days?: number;
     ids?: RecipeId[];
-}): TrendsDashboard;
-export { trendsWindow, runRecipe, RECIPE_IDS, type RecipeId, type RecipeSection };
+}): MixDashboard;
+/** @deprecated Use buildMixDashboard. */
+export declare const buildTrendsDashboard: typeof buildMixDashboard;
+export { analyticsWindow, analyticsWindow as trendsWindow, runRecipe, RECIPE_IDS, type RecipeId, type RecipeSection, type AnalyticsWindow, };

package/dist/lib/analytics/dashboard.js

@@ -1,4 +1,4 @@
-import { RECIPE_IDS, runRecipe, trendsWindow, } from './recipes.js';
+import { RECIPE_IDS, runRecipe, analyticsWindow, } from './recipes.js';
 const DEFAULT_ORDER = [
     'harness-mix',
     'model-mix',
@@ -9,9 +9,9 @@ const DEFAULT_ORDER = [
     'browser-activity',
     'resource-mix',
 ];
-export function buildTrendsDashboard(opts = {}) {
+export function buildMixDashboard(opts = {}) {
     const t0 = Date.now();
-    const win = trendsWindow(opts.days ?? 7);
+    const win = analyticsWindow(opts.days ?? 7);
     const ids = opts.ids ?? DEFAULT_ORDER;
     const sections = [];
     for (const id of ids) {
@@ -28,4 +28,6 @@ export function buildTrendsDashboard(opts = {}) {
         sections,
     };
 }
-export { trendsWindow, runRecipe, RECIPE_IDS };
+/** @deprecated Use buildMixDashboard. */
+export const buildTrendsDashboard = buildMixDashboard;
+export { analyticsWindow, analyticsWindow as trendsWindow, runRecipe, RECIPE_IDS, };

package/dist/lib/analytics/mix-commands.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Counter / warehouse mix recipes under `agents insights`.
+ *
+ * These used to live as the top-level `agents trends` tree. That name was a
+ * peer of `agents insights` with overlapping "analytics" meaning, so agents and
+ * humans kept picking the wrong verb. The cheap counter path (sessions index +
+ * usage.db) still exists — it is now `agents insights mix` and the recipe
+ * subcommands below. Latency stays on `agents perf`; quota on `agents usage`.
+ *
+ * `agents trends` remains a thin deprecated alias registered from
+ * `commands/trends.ts` that shares this same registration — no second copy of
+ * the recipe tree.
+ */
+import type { Command } from 'commander';
+export declare function parseMixDays(raw: string | undefined): number;
+export declare function printMixSection(section: {
+    id: string;
+    title: string;
+    rows: Array<Record<string, string | number | null>>;
+}): void;
+export declare function renderMixDashboard(days: number, asJson: boolean, bannerLabel?: string): void;
+/** One-line deprecation for the retired top-level `agents trends` spelling. */
+export declare function printTrendsDeprecation(): void;
+export interface RegisterMixCommandsOptions {
+    /**
+     * When true, every action prints the trends deprecation line first. Used only
+     * by the thin top-level `agents trends` alias — the real tree under insights
+     * never sets this.
+     */
+    deprecated?: boolean;
+    /**
+     * Banner label for the multi-recipe dashboard (default: agents insights mix).
+     * The deprecated alias passes `agents insights mix` still, so callers learn
+     * the new name even when they typed trends.
+     */
+    dashboardBanner?: string;
+}
+/**
+ * Attach counter-mix subcommands to a parent (typically `insights` or the
+ * deprecated `trends` alias).
+ *
+ * Layout:
+ *   <parent> mix                 multi-recipe board (default for trends alias)
+ *   <parent> recipes             list recipe ids
+ *   <parent> query               raw usage.db rows
+ *   <parent> harness-mix|…       one baked recipe
+ */
+export declare function registerMixCommands(parent: Command, opts?: RegisterMixCommandsOptions): void;
+/**
+ * Thin top-level `agents trends` alias: same mix tree, deprecation on every path,
+ * default action = mix board (old `agents trends` with no subcommand).
+ */
+export declare function registerDeprecatedTrendsAlias(program: Command): void;

package/dist/lib/analytics/mix-commands.js

@@ -0,0 +1,229 @@
+/**
+ * Counter / warehouse mix recipes under `agents insights`.
+ *
+ * These used to live as the top-level `agents trends` tree. That name was a
+ * peer of `agents insights` with overlapping "analytics" meaning, so agents and
+ * humans kept picking the wrong verb. The cheap counter path (sessions index +
+ * usage.db) still exists — it is now `agents insights mix` and the recipe
+ * subcommands below. Latency stays on `agents perf`; quota on `agents usage`.
+ *
+ * `agents trends` remains a thin deprecated alias registered from
+ * `commands/trends.ts` that shares this same registration — no second copy of
+ * the recipe tree.
+ */
+import chalk from 'chalk';
+import { setHelpSections } from '../help.js';
+import { buildMixDashboard, analyticsWindow, runRecipe, RECIPE_IDS, } from './dashboard.js';
+import { listRecipes } from './recipes.js';
+import { queryUsage, usageDbPath, USAGE_KINDS } from './usage-db.js';
+export function parseMixDays(raw) {
+    const n = parseInt(raw ?? '7', 10);
+    return Number.isFinite(n) && n > 0 ? n : 7;
+}
+function parseLimit(raw, fallback) {
+    const n = parseInt(raw ?? String(fallback), 10);
+    return Number.isFinite(n) && n > 0 ? n : fallback;
+}
+export function printMixSection(section) {
+    console.log(chalk.bold(section.title));
+    if (section.rows.length === 0) {
+        console.log(chalk.gray('  (no data)'));
+        console.log();
+        return;
+    }
+    const keys = Object.keys(section.rows[0]);
+    const widths = keys.map((k) => Math.max(k.length, ...section.rows.map((r) => String(r[k] ?? '').length), 4));
+    const pad = (s, w) => (s.length >= w ? s.slice(0, w) : s + ' '.repeat(w - s.length));
+    console.log(chalk.gray(keys.map((k, i) => pad(k.toUpperCase(), widths[i])).join('  ')));
+    for (const row of section.rows) {
+        console.log(keys.map((k, i) => pad(String(row[k] ?? ''), widths[i])).join('  '));
+    }
+    console.log();
+}
+export function renderMixDashboard(days, asJson, bannerLabel = 'agents insights mix') {
+    const dash = buildMixDashboard({ days });
+    if (asJson) {
+        console.log(JSON.stringify(dash, null, 2));
+        return;
+    }
+    console.log(chalk.bold(`${bannerLabel} — last ${dash.window.days} days`));
+    console.log(chalk.gray(`compute ${dash.durationMs}ms · usage ${usageDbPath()}`));
+    console.log();
+    if (dash.sections.length === 0) {
+        console.log(chalk.gray('No session or usage data in this window yet.'));
+        return;
+    }
+    for (const section of dash.sections)
+        printMixSection(section);
+}
+/** One-line deprecation for the retired top-level `agents trends` spelling. */
+export function printTrendsDeprecation() {
+    console.error(chalk.yellow('agents trends is deprecated — use `agents insights mix` (or `agents insights <recipe>`).'));
+}
+/**
+ * Attach counter-mix subcommands to a parent (typically `insights` or the
+ * deprecated `trends` alias).
+ *
+ * Layout:
+ *   <parent> mix                 multi-recipe board (default for trends alias)
+ *   <parent> recipes             list recipe ids
+ *   <parent> query               raw usage.db rows
+ *   <parent> harness-mix|…       one baked recipe
+ */
+export function registerMixCommands(parent, opts = {}) {
+    const before = () => {
+        if (opts.deprecated)
+            printTrendsDeprecation();
+    };
+    const banner = opts.dashboardBanner ?? 'agents insights mix';
+    const mix = parent
+        .command('mix')
+        .description('Counter recipes — harness/model mix, token ratios, resource frequency (sessions index + usage.db)')
+        .option('--days <n>', 'Days of history to include', '7')
+        .option('--json', 'Emit JSON instead of tables')
+        .action(function summary() {
+        before();
+        const o = this.opts();
+        renderMixDashboard(parseMixDays(o.days), Boolean(o.json), banner);
+    });
+    setHelpSections(mix, {
+        examples: `
+      # Auto recipe board (7d)
+      agents insights mix
+
+      # Last 30 days
+      agents insights mix --days 30
+
+      # One recipe as JSON
+      agents insights harness-mix --json
+
+      # Raw usage events
+      agents insights query --kind secret --days 7
+
+      # List baked recipe ids
+      agents insights recipes
+    `,
+        notes: `
+      Session recipes read sessions.db; resource recipes read ~/.agents/.history/analytics/usage.db.
+      Empty recipes are skipped on the default mix board.
+      This is the cheap counter path. Behavioural report (transcript content, account split)
+      is bare \`agents insights\`. Latency is \`agents perf\`; quota is \`agents usage\`.
+      Skill/slash-command popularity is \`agents sessions stats\`.
+    `,
+    });
+    parent.command('recipes')
+        .description('List baked mix-recipe ids')
+        .option('--json', 'Emit JSON')
+        .action((o) => {
+        before();
+        const list = listRecipes();
+        if (o.json) {
+            console.log(JSON.stringify(list, null, 2));
+            return;
+        }
+        for (const r of list) {
+            console.log(`${r.id.padEnd(22)} ${r.store.padEnd(10)} ${r.title}`);
+        }
+    });
+    parent.command('query')
+        .description('Raw usage-event query (usage.db)')
+        .option('--kind <kind>', `One of: ${USAGE_KINDS.join(', ')}`)
+        .option('--name <name>', 'Resource name filter')
+        .option('--event <event>', 'Event name filter')
+        .option('--days <n>', 'Days of history', '7')
+        .option('--limit <n>', 'Max rows', '40')
+        .option('--json', 'Emit JSON')
+        .action((o) => {
+        before();
+        const win = analyticsWindow(parseMixDays(o.days));
+        const kind = o.kind && USAGE_KINDS.includes(o.kind)
+            ? o.kind
+            : undefined;
+        if (o.kind && !kind) {
+            console.error(`Unknown kind '${o.kind}'. Expected: ${USAGE_KINDS.join(', ')}`);
+            process.exitCode = 1;
+            return;
+        }
+        const rows = queryUsage({
+            kind,
+            name: o.name,
+            event: o.event,
+            sinceIso: win.sinceIso,
+            limit: parseLimit(o.limit, 40),
+        });
+        if (o.json) {
+            console.log(JSON.stringify({ window: win, rows }, null, 2));
+            return;
+        }
+        if (rows.length === 0) {
+            console.log(chalk.gray('No usage events.'));
+            return;
+        }
+        printMixSection({
+            id: 'query',
+            title: 'Usage events',
+            rows: rows.map((r) => ({
+                ts: r.ts,
+                kind: r.kind,
+                name: r.name,
+                event: r.event,
+                agent: r.agent,
+            })),
+        });
+    });
+    for (const id of RECIPE_IDS) {
+        parent.command(id)
+            .description(`Mix recipe: ${id}`)
+            .option('--days <n>', 'Days of history', '7')
+            .option('--json', 'Emit JSON')
+            .action(function recipeAction() {
+            before();
+            const parentOpts = this.parent?.opts?.();
+            const o = { ...parentOpts, ...this.opts() };
+            const win = analyticsWindow(parseMixDays(o.days));
+            const section = runRecipe(id, win);
+            if (o.json) {
+                console.log(JSON.stringify({ window: win, section }, null, 2));
+                return;
+            }
+            if (section.empty) {
+                console.log(chalk.gray(`No data for recipe '${id}' in the last ${win.days} days.`));
+                return;
+            }
+            printMixSection(section);
+        });
+    }
+}
+/**
+ * Thin top-level `agents trends` alias: same mix tree, deprecation on every path,
+ * default action = mix board (old `agents trends` with no subcommand).
+ */
+export function registerDeprecatedTrendsAlias(program) {
+    const trends = program
+        .command('trends')
+        .description('Deprecated alias of `agents insights mix` — counter recipes over sessions + usage.db')
+        .option('--days <n>', 'Days of history to include', '7')
+        .option('--json', 'Emit JSON instead of tables')
+        .action(function summary() {
+        printTrendsDeprecation();
+        const o = this.opts();
+        renderMixDashboard(parseMixDays(o.days), Boolean(o.json), 'agents insights mix');
+    });
+    setHelpSections(trends, {
+        examples: `
+      # Prefer the canonical spelling
+      agents insights mix
+
+      # Still works (prints a deprecation line)
+      agents trends
+      agents trends harness-mix --json
+    `,
+        notes: `
+      \`agents trends\` is a compatibility alias. New code and agent briefs should use
+      \`agents insights mix\` / \`agents insights <recipe>\`. Behavioural report remains
+      bare \`agents insights\`. Latency remains \`agents perf\`.
+    `,
+    });
+    // Same subcommands as insights, with deprecation on every fire.
+    registerMixCommands(trends, { deprecated: true, dashboardBanner: 'agents insights mix' });
+}