@krtclcdy/tersio 2.19.0 → 2.20.0

package/extensions/rtk-session/index.ts

@@ -0,0 +1,164 @@
+import os from 'node:os';
+import path from 'node:path';
+import { activeModesSummary, asPromptArray, getSharedComboState, isComboPresetActive, isOmpSubagentPrompt, lastCustomValue, normalizeInputCommand, normalizeMode, paintStatusBar, paintableCtx, reconcileSharedComboEntries, sessionEntries, setSharedComboListener, setSharedComboMode } from '../shared/session-state.ts';
+import { readRtkDefault } from '../shared/plugin-settings.ts';
+import type { ExtensionApi, ExtensionCtx, InputEvent, SessionEntry, SystemPromptEvent } from '../shared/types.ts';
+
+const DEFAULT_ENABLED = false;
+
+function asBoolean(value: unknown): boolean | null {
+  if (typeof value === 'boolean') return value;
+  if (value === 'on' || value === 'true') return true;
+  if (value === 'off' || value === 'false') return false;
+  return null;
+}
+
+function resolveEnabled(entries: SessionEntry[] | null | undefined): boolean | null {
+  return lastCustomValue(entries, 'rtk-mode', (data) => asBoolean(data?.enabled));
+}
+
+const IS_WINDOWS = process.platform === 'win32';
+const HOME = os.homedir();
+const RTK_BINARY = path.join(HOME, '.bun', 'bin', IS_WINDOWS ? 'rtk.exe' : 'rtk');
+
+const RTK_PROMPT = `RTK mode active for this session.
+Use Rust Token Killer for shell output that would otherwise be noisy. Prefer explicit RTK commands in bash: \`rtk git status\`, \`rtk git diff\`, \`rtk read <file>\`, \`rtk grep <pattern> <path>\`, \`rtk find <glob> <path>\`, \`rtk test <cmd...>\`, \`rtk tsc\`, \`rtk lint\`, or \`rtk <tool> ...\` for supported dev commands.
+Do not use RTK when exact raw output is required, when a specialized OMP tool is required by system policy, or when the command changes state and RTK would hide important confirmation text. Specialized OMP tools still win: read/glob/grep/edit/lsp stay preferred over shell equivalents.`;
+
+interface ZodChain {
+  min: (n: number) => ZodChain;
+  describe: (text: string) => ZodChain;
+}
+
+export default function rtkSessionExtension(pi: ExtensionApi): void {
+  const { z } = pi.zod as { z: { object: (shape: Record<string, unknown>) => Record<string, unknown>; array: (el: unknown) => ZodChain; string: () => ZodChain } };
+  let enabled = DEFAULT_ENABLED;
+  let isActive = false;
+  let lastCtx: ExtensionCtx | undefined = undefined;
+
+  function syncStatus(ctx?: ExtensionCtx): void {
+    lastCtx = paintableCtx(lastCtx, ctx);
+    const c = lastCtx;
+    if (!c?.ui?.setStatus) return;
+    // Combo owns the bar when any preset is active; keep ours empty to avoid duplication.
+    if (isComboPresetActive() || !enabled) {
+      c.ui.setStatus('rtk', undefined);
+      return;
+    }
+    paintStatusBar(c.ui, 'rtk', '⚡', 'rtk: ON', isActive);
+  }
+
+  function setEnabled(next: unknown, ctx?: ExtensionCtx): void {
+    enabled = Boolean(next);
+    pi.appendEntry?.('rtk-mode', { enabled });
+    setSharedComboMode('rtk', enabled);
+    syncStatus(ctx);
+    const active = activeModesSummary(getSharedComboState());
+    ctx?.ui?.notify?.(enabled ? `RTK on — compact shell output for this session. Active: ${active}.` : `RTK off. Active: ${active}.`, 'info');
+  }
+
+  pi.setLabel?.('RTK session toggle');
+
+  // Live mirror: a /tersio or /combo switch publishes shared state — adopt
+  // it at once so the next turn and the rtk_run gate see it, no reload.
+  function syncFromShared(state: { rtk: string }): void {
+    enabled = state.rtk === 'on';
+    syncStatus();
+  }
+  setSharedComboListener(syncFromShared);
+  pi.registerCommand?.('rtk', {
+    description: 'Toggle RTK compact shell-output guidance for this session',
+    handler: async (args, ctx) => {
+      const arg = String(args || '').trim().toLowerCase();
+      if (!arg || arg === 'status') {
+        ctx?.ui?.notify?.(`RTK: ${enabled ? 'on' : 'off'}`, 'info');
+        return;
+      }
+      if (['on', 'enable', 'enabled', 'true'].includes(arg)) {
+        setEnabled(true, ctx);
+        return;
+      }
+      if (['off', 'disable', 'disabled', 'false'].includes(arg)) {
+        setEnabled(false, ctx);
+        return;
+      }
+      ctx?.ui?.notify?.('Usage: /rtk [on|off|status]', 'warning');
+    },
+  });
+
+  pi.registerTool?.({
+    name: 'rtk_run',
+    label: 'RTK Run',
+    description: 'Run the installed `rtk` binary for compact command output when RTK mode is enabled.',
+    parameters: z.object({
+      args: z.array(z.string()).min(1).describe("Arguments passed to rtk, e.g. ['git','status'] or ['read','src/index.ts']"),
+    }),
+    async execute(_toolCallId, params, signal, onUpdate, ctx) {
+      if (!enabled) {
+        return {
+          isError: true,
+          content: [{ type: 'text', text: 'RTK mode is off. Run /rtk on for this session, or use bash explicitly.' }],
+          details: { enabled },
+        };
+      }
+      onUpdate?.({ content: [{ type: 'text', text: `rtk ${params.args.join(' ')}` }], details: { phase: 'start' } });
+      const result = await pi.exec!(RTK_BINARY, params.args, { signal, cwd: ctx?.cwd || pi.cwd });
+      const text = [result.stdout, result.stderr].filter(Boolean).join('\n');
+      return {
+        isError: result.code !== 0,
+        content: [{ type: 'text', text: text || `rtk exited ${result.code}` }],
+        details: { code: result.code, killed: result.killed, enabled },
+      };
+    },
+  });
+
+  pi.on<InputEvent>('input', async (event) => {
+    if (event?.source === 'extension') return;
+    const t = normalizeInputCommand(event?.text);
+    if (t === 'rtk on' || t === 'use rtk') setEnabled(true);
+    if (t === 'rtk off' || t === 'stop rtk') setEnabled(false);
+  });
+  function restoreEnabled(ctx?: ExtensionCtx): void {
+    const entries = sessionEntries(ctx);
+    // Publish the persisted combo state (incl. combo-level) before painting:
+    // bar suppression reads the in-process bridge, which is empty in a fresh
+    // host until the combo extension reconciles — and its reconcile is
+    // UI-gated. Deriving it here makes suppression independent of load order.
+    reconcileSharedComboEntries(entries);
+    // Persisted session state wins; a fresh session falls back to the
+    // installer/user-configured default (off unless configured).
+    const persisted = resolveEnabled(entries);
+    enabled = typeof persisted === 'boolean' ? persisted : readRtkDefault();
+    syncStatus(ctx);
+  }
+
+  pi.on('session_start', async (_event, ctx) => {
+    restoreEnabled(ctx);
+    ctx?.ui?.notify?.(`RTK loaded: ${enabled ? 'on' : 'off'}`, 'info');
+  });
+
+  pi.on('session_branch', async (_event, ctx) => {
+    restoreEnabled(ctx);
+  });
+
+  pi.on('session_tree', async (_event, ctx) => {
+    restoreEnabled(ctx);
+  });
+
+  pi.on('agent_start', async (_event, ctx) => {
+    isActive = true;
+    syncStatus(ctx);
+  });
+
+  pi.on('agent_end', async (_event, ctx) => {
+    isActive = false;
+    syncStatus(ctx);
+  });
+
+  pi.on<SystemPromptEvent>('before_agent_start', async (event) => {
+    const active = isOmpSubagentPrompt(event.systemPrompt) ? getSharedComboState().rtk === 'on' : enabled;
+    if (!active) return;
+    const base = asPromptArray(event.systemPrompt);
+    return { systemPrompt: [...base, RTK_PROMPT] };
+  });
+}

package/extensions/shared/carbon.ts

@@ -0,0 +1,123 @@
+// extensions/shared/carbon.ts — CO2/energy footprints, EcoLogits-style.
+//
+// Port of the EcoLogits v0.8.2 LLM impact model (genai-impact/ecologits,
+// MPL-2.0 — see ECO_NOTICE.md), following the same served-estimate approach
+// as honey-for-devs' hooks/eco.js: the faithful single-stream (batch-1)
+// ceiling divided by serving_concurrency for continuous-batching amortization.
+//
+// Model params come from EcoLogits' registry where it covers the model;
+// otherwise a documented class borrow (never a silent guess — every borrow
+// carries its source). Unknown ids fall to the gpt-4o default. Everything
+// rendered from here must carry ~est. and never merge with measured figures.
+
+export interface ModelCarbon {
+  activeB: number;
+  totalB: number;
+  provider: string;
+  source: 'registry' | 'borrowed' | 'default';
+}
+
+// EcoLogits 0.8.2 constants — kWh, kgCO2eq, seconds, GB.
+const Q_BITS = 4;
+const E_ALPHA = 8.91e-8;
+const E_BETA = 1.43e-6;
+const L_ALPHA = 8.02e-4;
+const L_BETA = 2.23e-2;
+const GPU_MEM = 80;
+const GPU_EMB_GWP = 143;
+const SRV_GPUS = 8;
+const SRV_POWER = 1;
+const SRV_EMB_GWP = 3000;
+const LIFETIME = 5 * 365 * 24 * 3600;
+const PUE = 1.2;
+
+// Per-provider grid intensity, gCO2eq/kWh (location-based research values).
+const GRIDS: Record<string, number> = {
+  anthropic: 500,
+  openai: 400,
+  google: 330,
+  default: 450,
+};
+
+// Serving amortization: single-stream ceiling ÷ concurrency ≈ served impact.
+export const SERVING_CONCURRENCY = 32;
+
+interface RegistryEntry {
+  match?: string;
+  exact?: string;
+  active: number;
+  total: number;
+  provider: string;
+  source: 'registry' | 'borrowed';
+}
+
+// Registry values verbatim from EcoLogits' model_repository; borrows cite
+// the public param disclosure they stand in for (MoE active/total).
+const TABLE: RegistryEntry[] = [
+  { match: 'opus', active: 625.0, total: 2000, provider: 'anthropic', source: 'registry' },
+  { match: 'sonnet', active: 137.5, total: 440, provider: 'anthropic', source: 'registry' },
+  { match: 'haiku', active: 18.0, total: 18.0, provider: 'anthropic', source: 'registry' },
+  { match: 'gpt-5', active: 93.75, total: 300, provider: 'openai', source: 'registry' },
+  { match: 'gpt', active: 137.5, total: 440, provider: 'openai', source: 'registry' },
+  { match: 'gemini', active: 137.5, total: 440, provider: 'google', source: 'registry' },
+  { match: 'deepseek', active: 37, total: 671, provider: 'default', source: 'borrowed' },
+  { match: 'qwen', active: 22, total: 235, provider: 'default', source: 'borrowed' },
+  { match: 'glm', active: 37, total: 671, provider: 'default', source: 'borrowed' },
+  { match: 'kimi', active: 32, total: 1000, provider: 'default', source: 'borrowed' },
+  { match: 'muse', active: 70, total: 70, provider: 'default', source: 'borrowed' },
+  { match: 'flash', active: 18.0, total: 18.0, provider: 'default', source: 'borrowed' },
+];
+
+const DEFAULT_ENTRY = { active: 137.5, total: 440, provider: 'openai' };
+
+export function carbonParamsFor(model: string): ModelCarbon {
+  const name = model.toLowerCase();
+  for (const row of TABLE) {
+    if (row.match && name.includes(row.match)) {
+      return { activeB: row.active, totalB: row.total, provider: row.provider, source: row.source };
+    }
+  }
+  return { activeB: DEFAULT_ENTRY.active, totalB: DEFAULT_ENTRY.total, provider: DEFAULT_ENTRY.provider, source: 'default' };
+}
+
+export interface Footprint {
+  energyWh: number;
+  gco2: number;
+  gco2Ceiling: number;
+  concurrency: number;
+  provider: string;
+  paramSource: 'registry' | 'borrowed' | 'default';
+}
+
+function impacts(activeB: number, totalB: number, outTokens: number, gridKg: number): { energyKwh: number; gco2: number } {
+  const gpuEnergy = outTokens * (E_ALPHA * activeB + E_BETA);
+  const latency = outTokens * (L_ALPHA * activeB + L_BETA);
+  const gpuCount = Math.ceil(((1.2 * totalB * Q_BITS) / 8 / GPU_MEM));
+  const serverEnergy = (latency / 3600) * SRV_POWER * (gpuCount / SRV_GPUS);
+  const energyKwh = PUE * (serverEnergy + gpuCount * gpuEnergy);
+  const embGwp = (latency / LIFETIME) * ((gpuCount / SRV_GPUS) * SRV_EMB_GWP + gpuCount * GPU_EMB_GWP);
+  return { energyKwh, gco2: (energyKwh * gridKg + embGwp) * 1000 };
+}
+
+export function footprintFor(model: string, outputTokens: number): Footprint {
+  const p = carbonParamsFor(model);
+  const gridKg = (GRIDS[p.provider] ?? GRIDS.default) / 1000;
+  const ceiling = impacts(p.activeB, p.totalB, Math.max(0, Math.floor(outputTokens)), gridKg);
+  const b = SERVING_CONCURRENCY > 0 ? SERVING_CONCURRENCY : 1;
+  return {
+    energyWh: (ceiling.energyKwh / b) * 1000,
+    gco2: ceiling.gco2 / b,
+    gco2Ceiling: ceiling.gco2,
+    concurrency: b,
+    provider: p.provider,
+    paramSource: p.source,
+  };
+}
+
+export function co2GramsFor(model: string, outputTokens: number): number {
+  return footprintFor(model, outputTokens).gco2;
+}
+
+export function energyWhFor(model: string, outputTokens: number): number {
+  return footprintFor(model, outputTokens).energyWh;
+}

package/extensions/shared/mode-reinforcement.ts

@@ -0,0 +1,29 @@
+import { asPromptArray, reconcileSharedComboEntries, sessionEntries, systemPromptIncludes } from './session-state.ts';
+import type { ExtensionApi, SystemPromptEvent } from './types.ts';
+
+const MARKER = 'SUPREME TOKEN SAVER MODES ACTIVE';
+
+function instruction(state: { caveman: string; rtk: string; ponytail: string }): string | null {
+  const modes = [
+    state.caveman !== 'off' && `caveman=${state.caveman}`,
+    state.rtk === 'on' && 'rtk=on',
+    state.ponytail !== 'off' && `ponytail=${state.ponytail}`,
+  ].filter(Boolean);
+  if (!modes.length) return null;
+
+  return `${MARKER}: ${modes.join(' · ')}. Keep these active for the entire response: concise Caveman prose, RTK for eligible noisy shell output, and the smallest correct Ponytail solution. Do not weaken or disable a mode unless the user explicitly asks.`;
+}
+
+export default function modeReinforcementExtension(pi: ExtensionApi): void {
+  pi.setLabel?.('Tersio mode reinforcement');
+
+  pi.on('before_agent_start', async (event: SystemPromptEvent, ctx) => {
+    if (!ctx?.hasUI) return;
+    const text = instruction(reconcileSharedComboEntries(sessionEntries(ctx)));
+    if (!text) return;
+
+    const base = asPromptArray(event.systemPrompt);
+    if (systemPromptIncludes(base, MARKER)) return;
+    return { systemPrompt: [...base, text] };
+  });
+}

package/extensions/shared/plugin-settings.ts

@@ -0,0 +1,57 @@
+// Plugin settings reader for the Tersio extensions.
+// Reads omp's persisted plugin state (~/.omp/plugins/omp-plugins.lock.json),
+// written by `omp plugin config set @krtclcdy/tersio <key> <value>` and by
+// the installer profile step. Tolerant: any parse failure yields {} so every
+// caller falls back to its own default.
+
+import { existsSync, readFileSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+export const PLUGIN_NAME = '@krtclcdy/tersio';
+
+function lockPaths(): string[] {
+  const configHome = process.env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config');
+  return [
+    path.join(os.homedir(), '.omp', 'plugins', 'omp-plugins.lock.json'),
+    path.join(configHome, 'omp', 'plugins', 'omp-plugins.lock.json'),
+  ];
+}
+
+// `settings[PLUGIN_NAME]` in the lock file; empty object when missing.
+export function readPluginSettings(): Record<string, unknown> {
+  for (const p of lockPaths()) {
+    if (!existsSync(p)) continue;
+    try {
+      const config = JSON.parse(readFileSync(p, 'utf8')) as { settings?: Record<string, Record<string, unknown>> };
+      const values = config.settings?.[PLUGIN_NAME];
+      if (values && typeof values === 'object' && !Array.isArray(values)) return values;
+    } catch { /* tolerate corrupt file */ }
+  }
+  return {};
+}
+
+const COMBO_LEVELS = new Set(['off', 'medium', 'balanced', 'max']);
+const CAVEMAN_MODES = new Set(['off', 'lite', 'full', 'ultra', 'wenyan']);
+const PONYTAIL_MODES = new Set(['off', 'lite', 'full', 'ultra', 'review']);
+
+function readStringDefault(key: string, valid: Set<string>): string {
+  const raw = readPluginSettings()[key];
+  return typeof raw === 'string' && valid.has(raw) ? raw : 'off';
+}
+
+export function readComboDefault(): string {
+  return readStringDefault('comboDefault', COMBO_LEVELS);
+}
+
+export function readCavemanDefault(): string {
+  return readStringDefault('cavemanDefault', CAVEMAN_MODES);
+}
+
+export function readRtkDefault(): boolean {
+  const raw = readPluginSettings().rtkDefault;
+  return typeof raw === 'boolean' ? raw : false;
+}
+
+export function readPonytailDefault(): string {
+  return readStringDefault('ponytailDefault', PONYTAIL_MODES);
+}

package/extensions/shared/pricing.ts

@@ -0,0 +1,168 @@
+// extensions/shared/pricing.ts — dynamic model pricing from LiteLLM.
+// Lookup order: exact id in the live cache → provider-prefix strip → default.
+// The cache is the full LiteLLM feed (3k+ ids), refreshed lazily in background
+// and on `tersio update`; every reader is sync and offline-safe. No static
+// per-model table — list prices rot, the feed does not. Unknown models report
+// the default with known:false so the dashboard labels them honestly.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+export interface ModelPrice {
+  input: number;
+  output: number;
+  cacheRead: number;
+  cacheWrite: number;
+}
+
+// Sonnet-class default for unpriced models; always paired with known:false.
+export const DEFAULT_PRICE: ModelPrice = { input: 2, output: 10, cacheRead: 0.2, cacheWrite: 2.5 };
+
+const LITELLM_URL = 'https://raw.githubusercontent.com/BerriAI/litellm/main/model_prices_and_context_window.json';
+// Live cache refreshes lazily: readers use the file even when stale, and only
+// one refresh runs per process. `tersio update` still forces a fresh fetch.
+const CACHE_TTL_MS = 7 * 24 * 3600 * 1000;
+let refreshInflight: Promise<boolean> | null = null;
+
+export function pricesCachePath(): string {
+  const override = process.env.TERSIO_PRICES_FILE;
+  if (override) return override;
+  return path.join(os.homedir(), '.omp', 'plugins', 'tersio-prices.json');
+}
+
+export function pricesUrl(): string {
+  return process.env.TERSIO_PRICES_URL || LITELLM_URL;
+}
+
+export interface LivePrices {
+  fetchedAt: number;
+  // Compact tuples [input, output, cacheRead, cacheWrite] per LiteLLM id —
+  // the full feed caches to ~1MB instead of multi-MB objects.
+  exact: Record<string, [number, number, number, number]>;
+  deprecated?: string[];
+}
+
+function toPrice(t: [number, number, number, number]): ModelPrice {
+  return { input: t[0], output: t[1], cacheRead: t[2], cacheWrite: t[3] };
+}
+
+// Tolerate both cache shapes: compact tuples (new) and ModelPrice objects
+// (written by older refreshes) — a version bump never orphans the cache.
+function asPrice(v: unknown): ModelPrice | null {
+  if (Array.isArray(v) && v.length === 4 && v.every((n) => typeof n === 'number' && Number.isFinite(n) && n >= 0)) {
+    return toPrice(v as [number, number, number, number]);
+  }
+  if (v && typeof v === 'object') {
+    const o = v as Record<string, unknown>;
+    if (['input', 'output', 'cacheRead', 'cacheWrite'].every((k) => typeof o[k] === 'number' && Number.isFinite(o[k]) && (o[k] as number) >= 0)) {
+      return o as unknown as ModelPrice;
+    }
+  }
+  return null;
+}
+
+export function loadLivePrices(): LivePrices | null {
+  let raw: string;
+  try {
+    raw = fs.readFileSync(pricesCachePath(), 'utf8');
+  } catch {
+    return null;
+  }
+  try {
+    const parsed = JSON.parse(raw) as { fetchedAt?: unknown; exact?: unknown; deprecated?: unknown };
+    if (typeof parsed.fetchedAt !== 'number' || !parsed.exact || typeof parsed.exact !== 'object') return null;
+    const exact: Record<string, [number, number, number, number]> = {};
+    for (const [k, v] of Object.entries(parsed.exact as Record<string, unknown>)) {
+      const p = asPrice(v);
+      if (p) exact[k] = [p.input, p.output, p.cacheRead, p.cacheWrite];
+    }
+    if (!Object.keys(exact).length) return null;
+    // Stale entries stay usable; refreshPricesIfStale refreshes in background.
+    const deprecated = Array.isArray(parsed.deprecated) ? (parsed.deprecated as unknown[]).filter((d): d is string => typeof d === 'string') : [];
+    return { fetchedAt: parsed.fetchedAt, exact, deprecated };
+  } catch {
+    return null;
+  }
+}
+
+function num(v: unknown): number | null {
+  return typeof v === 'number' && Number.isFinite(v) && v >= 0 ? v : null;
+}
+
+export function priceFor(model: string, live?: LivePrices | null): { price: ModelPrice; known: boolean; live: boolean } {
+  const table = live === undefined ? loadLivePrices() : live;
+  if (table) {
+    const hit = asPrice(table.exact[model] ?? table.exact[model.toLowerCase()]);
+    if (hit) return { price: hit, known: true, live: true };
+    // Provider-prefixed ids ("azure/gpt-4o", "dashscope/qwen-max"): match the
+    // first cached id that ends with the bare model name.
+    const name = model.toLowerCase();
+    const key = Object.keys(table.exact).find((k) => k.toLowerCase() === name || k.toLowerCase().endsWith(`/${name}`));
+    const prefixed = key ? asPrice(table.exact[key]) : null;
+    if (prefixed) return { price: prefixed, known: true, live: true };
+  }
+  return { price: DEFAULT_PRICE, known: false, live: false };
+}
+// Fetch LiteLLM pricing, keep every id with valid input/output rates, write
+// the cache. False on any failure (offline, timeout, shape change) — callers
+// fall back silently.
+export async function refreshPrices(): Promise<boolean> {
+  if (refreshInflight) return refreshInflight;
+  refreshInflight = (async () => {
+    let res: Response;
+    try {
+      const ctl = new AbortController();
+      const timer = setTimeout(() => ctl.abort(), 15000);
+      try {
+        res = await fetch(pricesUrl(), { signal: ctl.signal });
+      } finally {
+        clearTimeout(timer);
+      }
+      if (!res.ok) return false;
+    } catch {
+      return false;
+    }
+    let data: Record<string, Record<string, unknown>>;
+    try {
+      data = (await res.json()) as Record<string, Record<string, unknown>>;
+    } catch {
+      return false;
+    }
+    const exact: Record<string, [number, number, number, number]> = {};
+    const deprecated: string[] = [];
+    for (const [id, row] of Object.entries(data)) {
+      if (!row || typeof row !== 'object') continue;
+      const input = num(row.input_cost_per_token);
+      const output = num(row.output_cost_per_token);
+      if (input === null || output === null) continue;
+      exact[id] = [
+        input * 1e6,
+        output * 1e6,
+        (num(row.cache_read_input_token_cost) ?? input) * 1e6,
+        (num(row.cache_creation_input_token_cost) ?? input) * 1e6,
+      ];
+      if (typeof row.deprecation_date === 'string' && row.deprecation_date) deprecated.push(id);
+    }
+    if (!Object.keys(exact).length) return false;
+    try {
+      fs.mkdirSync(path.dirname(pricesCachePath()), { recursive: true });
+      fs.writeFileSync(pricesCachePath(), JSON.stringify({ fetchedAt: Date.now(), exact, deprecated }), 'utf8');
+      return true;
+    } catch {
+      return false;
+    }
+  })();
+  try {
+    return await refreshInflight;
+  } finally {
+    refreshInflight = null;
+  }
+}
+
+// Fire-and-forget refresh when the cache is stale or missing. Readers keep
+// using the stale file (or the built-in table) — pricing never blocks.
+export function refreshPricesIfStale(): void {
+  const live = loadLivePrices();
+  if (live && Date.now() - live.fetchedAt <= CACHE_TTL_MS) return;
+  void refreshPrices().catch(() => false);
+}

package/extensions/shared/rtk-gain.ts

@@ -0,0 +1,105 @@
+// extensions/shared/rtk-gain.ts — measured RTK savings from its own store.
+// RTK records every invocation (input/output/saved tokens, savings %, exec
+// time) in history.db; `rtk gain` renders the same rows. We read them with
+// the sqlite3 CLI (present on macOS; best-effort elsewhere) so the dashboard
+// shows measured figures, never estimates. Missing DB/CLI → empty, no throw.
+//
+// Caveman and Ponytail have no per-command counters (instruction-following
+// isn't metered); their gains are bench-measured in BENCHMARK.md and cited
+// as static figures wherever RTK rows appear.
+//
+// Rows group by command alone, machine-wide: one row per command no matter
+// which repo ran it. Project filtering stays out — wasted column, same logic.
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+export interface RtkCommandRow {
+  command: string;
+  count: number;
+  saved: number;
+  avgPct: number;
+  avgMs: number;
+}
+
+export interface RtkGain {
+  commands: number;
+  input: number;
+  saved: number;
+  avgPct: number;
+  totalMs: number;
+  byCommand: RtkCommandRow[];
+}
+
+const EMPTY: RtkGain = { commands: 0, saved: 0, input: 0, avgPct: 0, totalMs: 0, byCommand: [] };
+
+// RTK stores the whole command line, and `rtk ls -d` with a long path list
+// runs to tens of KB. The table shows one clipped cell, so bound the string
+// before it crosses the sqlite3 CLI and lands in every /data.json poll.
+const MAX_CMD_CHARS = 200;
+
+// The query() reader is line- and tab-delimited, and RTK stores heredocs and
+// `node -e` scripts verbatim (~67 rows here), so one logical row can arrive as
+// several lines and derail every row after it. Fold whitespace into spaces
+// first: the stored command keeps its newlines, only the read view flattens.
+const CMD_ONE_LINE = `replace(replace(replace(rtk_cmd, char(10), ' '), char(13), ' '), char(9), ' ')`;
+
+export function rtkDbPath(): string {
+  const override = process.env.TERSIO_RTK_DB;
+  if (override) return override;
+  if (process.platform === 'darwin') {
+    return path.join(os.homedir(), 'Library', 'Application Support', 'rtk', 'history.db');
+  }
+  const xdg = process.env.XDG_DATA_HOME || path.join(os.homedir(), '.local', 'share');
+  return path.join(xdg, 'rtk', 'history.db');
+}
+
+function query(db: string, sql: string): string[][] {
+  const out = execFileSync('sqlite3', ['-separator', '\t', db, sql], {
+    encoding: 'utf8',
+    timeout: 5000,
+    stdio: ['ignore', 'pipe', 'ignore'],
+  });
+  return out
+    .split('\n')
+    .filter((line) => line.trim())
+    .map((line) => line.split('\t'));
+}
+
+export function readRtkGain(limit = 10, cutoffMs?: number): RtkGain {
+  try {
+    if (!fs.existsSync(rtkDbPath())) return EMPTY;
+    // View-level cutoff only: rows stay in rtk's own database untouched.
+    // strftime('%s') normalizes ISO-8601 timestamps to epoch seconds; rows
+    // with unparseable timestamps (0) drop out of a filtered view.
+    const where = cutoffMs && cutoffMs > 0
+      ? `WHERE CAST(strftime('%s', timestamp) AS INTEGER) >= ${Math.floor(cutoffMs / 1000)}`
+      : '';
+    const [[commands = '0', saved = '0', input = '0', avgPct = '0', totalMs = '0'] = []] = query(
+      rtkDbPath(),
+      `SELECT COUNT(*), COALESCE(SUM(saved_tokens),0), COALESCE(SUM(input_tokens),0), COALESCE(AVG(savings_pct),0), COALESCE(SUM(exec_time_ms),0) FROM commands ${where};`,
+    );
+    const byCommand = query(
+      rtkDbPath(),
+      `SELECT substr(${CMD_ONE_LINE}, 1, ${MAX_CMD_CHARS}), COUNT(*), COALESCE(SUM(saved_tokens),0), COALESCE(AVG(savings_pct),0), COALESCE(AVG(exec_time_ms),0) FROM commands ${where} GROUP BY rtk_cmd ORDER BY SUM(saved_tokens) DESC LIMIT ${Math.max(1, Math.floor(limit))};`,
+    ).map(([command, count, savedRow, pct, ms]) => ({
+      command,
+      count: Number(count) || 0,
+      saved: Number(savedRow) || 0,
+      avgPct: Number(pct) || 0,
+      avgMs: Number(ms) || 0,
+    }));
+    const totalIn = Number(input) || 0;
+    return {
+      commands: Number(commands) || 0,
+      saved: Number(saved) || 0,
+      input: totalIn,
+      avgPct: totalIn ? ((Number(saved) || 0) / totalIn) * 100 : 0,
+      totalMs: Number(totalMs) || 0,
+      byCommand,
+    };
+  } catch {
+    return EMPTY;
+  }
+}