opencode-token-tracker 1.7.0 → 1.8.0

package/dist/bin/opencode-tokens.js

@@ -1,11 +1,18 @@
 #!/usr/bin/env node
 import { closeSync, copyFileSync, existsSync, mkdirSync, openSync, readFileSync, readSync, statSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { join } from "node:path";
-import { BUILTIN_PRICING, DEFAULT_CONFIG, formatCost, formatTokens, getStartOfDay, getStartOfMonth, getStartOfWeek, validateConfig, BUILTIN_PRICING_META, resolvePricingStatus, round2 } from "../lib/shared.js";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { BUILTIN_PRICING, BUILTIN_PRICING_META, DEFAULT_CONFIG, PRICING_STALE_AFTER_DAYS, formatCost, formatLocalDateKey, formatTokens, getBuiltinPricingAudit, getEffectivePricingAudit, getPricingFreshness, getStartOfDay, getStartOfMonth, getStartOfWeek, hasBillableTokenUsage, mergeSessionMeta, resolvePricingStatus, resolveRootSession, round2, sessionDisplayLabel, validateConfig, } from "../lib/shared.js";
 const CONFIG_DIR = join(homedir(), ".config", "opencode");
 const CONFIG_FILE = join(CONFIG_DIR, "token-tracker.json");
 const LOG_FILE = join(CONFIG_DIR, "logs", "token-tracker", "tokens.jsonl");
+const SESSIONS_LOG_FILE = join(CONFIG_DIR, "logs", "token-tracker", "sessions.jsonl");
+const PACKAGE_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
+const OPENCODE_CONFIG_FILES = [
+    join(CONFIG_DIR, "opencode.json"),
+    join(CONFIG_DIR, "opencode.jsonc"),
+];
 // ============================================================================
 // Helpers
 // ============================================================================
@@ -15,10 +22,46 @@ function padRight(str, len) {
 function padLeft(str, len) {
     return str.length >= len ? str : `${" ".repeat(len - str.length)}${str}`;
 }
-function truncateSessionId(sessionId) {
-    if (!sessionId)
-        return "unknown";
-    return sessionId.length > 16 ? `${sessionId.slice(0, 14)}…` : sessionId;
+function formatAge(ts) {
+    const diffMs = Date.now() - ts;
+    if (diffMs < 60_000)
+        return "less than 1m ago";
+    const minutes = Math.floor(diffMs / 60_000);
+    if (minutes < 60)
+        return `${minutes}m ago`;
+    const hours = Math.floor(minutes / 60);
+    if (hours < 24)
+        return `${hours}h ago`;
+    return `${Math.floor(hours / 24)}d ago`;
+}
+// Compact relative time for table columns: "just now" / "5m ago" / "2h ago" / "3d ago".
+function formatLastActive(ts) {
+    if (Date.now() - ts < 60_000)
+        return "just now";
+    return formatAge(ts);
+}
+const ZERO_COST_PROVIDER_HINTS = [
+    { match: "copilot", reason: "subscription/bundled provider" },
+    { match: "cursor", reason: "subscription/bundled provider" },
+    { match: "free", reason: "free provider name" },
+    { match: "ollama", reason: "local/self-hosted provider" },
+    { match: "lmstudio", reason: "local/self-hosted provider" },
+    { match: "lm-studio", reason: "local/self-hosted provider" },
+    { match: "llamacpp", reason: "local/self-hosted provider" },
+    { match: "llama.cpp", reason: "local/self-hosted provider" },
+    { match: "local", reason: "local/self-hosted provider" },
+    { match: "localhost", reason: "local/self-hosted provider" },
+    { match: "self-hosted", reason: "local/self-hosted provider" },
+    { match: "selfhosted", reason: "local/self-hosted provider" },
+];
+function getZeroCostProviderMatch(provider) {
+    const normalized = provider.toLowerCase().replace(/\s+/g, "");
+    for (const hint of ZERO_COST_PROVIDER_HINTS) {
+        if (normalized.includes(hint.match)) {
+            return { provider, reason: hint.reason };
+        }
+    }
+    return undefined;
 }
 function parseArgs(args) {
     const positional = [];
@@ -49,7 +92,7 @@ function parseArgs(args) {
             i++;
             continue;
         }
-        if (arg.startsWith("-") && arg.length === 2 && arg !== "--") {
+        if (/^-[A-Za-z]$/.test(arg)) {
             const next = args[i + 1];
             if (next && !next.startsWith("-")) {
                 flags.set(arg.slice(1), next);
@@ -109,7 +152,7 @@ function loadEntries(since) {
                     shouldStop = true;
                     break;
                 }
-                if (!entry.input && !entry.output)
+                if (!hasBillableTokenUsage(entry))
                     continue;
                 entries.push(entry);
             }
@@ -122,7 +165,7 @@ function loadEntries(since) {
     if (!shouldStop && leftover.trim()) {
         try {
             const entry = JSON.parse(leftover.trim());
-            if (entry.type === "tokens" && (!since || entry._ts >= since) && (entry.input || entry.output)) {
+            if (entry.type === "tokens" && (!since || entry._ts >= since) && hasBillableTokenUsage(entry)) {
                 entries.push(entry);
             }
         }
@@ -230,10 +273,93 @@ function printTable(title, groups, labelHeader) {
     }
     console.log();
 }
+function loadSessionMeta() {
+    if (!existsSync(SESSIONS_LOG_FILE))
+        return new Map();
+    const records = [];
+    try {
+        const content = readFileSync(SESSIONS_LOG_FILE, "utf-8");
+        for (const line of content.split("\n")) {
+            const trimmed = line.trim();
+            if (!trimmed)
+                continue;
+            try {
+                const rec = JSON.parse(trimmed);
+                if (rec.type !== "session")
+                    continue;
+                records.push(rec);
+            }
+            catch {
+                // Skip malformed lines
+            }
+        }
+    }
+    catch {
+        return new Map();
+    }
+    return mergeSessionMeta(records);
+}
+function printSessionBreakdown(entries, metaMap, options = {}) {
+    const { rollUp = true, heading = "By Session" } = options;
+    const parentOf = new Map();
+    for (const meta of metaMap.values()) {
+        parentOf.set(meta.sessionId, meta.parentID);
+    }
+    // Rolled-up view groups every child/subagent session under its top-level
+    // session; the raw view keeps each session's own id so sub-agents stay
+    // visible as separate rows labelled by their own title.
+    const groupKeyOf = (sessionId) => rollUp ? resolveRootSession(sessionId, parentOf) : sessionId;
+    const rows = new Map();
+    for (const e of entries) {
+        const key = groupKeyOf(e.sessionId ?? "unknown");
+        let row = rows.get(key);
+        if (!row) {
+            row = { stats: createEmptyStats(), lastActive: 0 };
+            rows.set(key, row);
+        }
+        row.stats.input += e.input ?? 0;
+        row.stats.output += e.output ?? 0;
+        row.stats.reasoning += e.reasoning ?? 0;
+        row.stats.cacheRead += e.cacheRead ?? 0;
+        row.stats.cacheWrite += e.cacheWrite ?? 0;
+        row.stats.cost += e.cost ?? 0;
+        row.stats.count += 1;
+        if (e._ts > row.lastActive)
+            row.lastActive = e._ts;
+    }
+    const sorted = Array.from(rows.entries()).sort((a, b) => b[1].stats.cost - a[1].stats.cost);
+    if (sorted.length === 0) {
+        console.log(`\n  No data for ${heading}\n`);
+        return;
+    }
+    const LABEL_MAX = 40;
+    const labeled = sorted.map(([key, row]) => ({
+        label: sessionDisplayLabel(key, metaMap.get(key), LABEL_MAX),
+        lastActive: row.lastActive ? formatLastActive(row.lastActive) : "-",
+        stats: row.stats,
+    }));
+    const labelHeader = "Session";
+    const activeHeader = "Last Active";
+    const labelWidth = Math.max(labelHeader.length, ...labeled.map((r) => r.label.length));
+    const activeWidth = Math.max(activeHeader.length, ...labeled.map((r) => r.lastActive.length));
+    const tokensWidth = 10;
+    const costWidth = 10;
+    const countWidth = 6;
+    console.log();
+    console.log(`  ${heading}`);
+    console.log(`  ${"─".repeat(labelWidth + activeWidth + tokensWidth + costWidth + countWidth + 8)}`);
+    console.log(`  ${padRight(labelHeader, labelWidth)}  ${padRight(activeHeader, activeWidth)}  ${padLeft("Tokens", tokensWidth)}  ${padLeft("Cost", costWidth)}  ${padLeft("Msgs", countWidth)}`);
+    console.log(`  ${"-".repeat(labelWidth)}  ${"-".repeat(activeWidth)}  ${"-".repeat(tokensWidth)}  ${"-".repeat(costWidth)}  ${"-".repeat(countWidth)}`);
+    for (const r of labeled) {
+        const totalTokens = r.stats.input + r.stats.output;
+        console.log(`  ${padRight(r.label, labelWidth)}  ${padRight(r.lastActive, activeWidth)}  ${padLeft(formatTokens(totalTokens, 2), tokensWidth)}  ${padLeft(formatCost(r.stats.cost), costWidth)}  ${padLeft(r.stats.count.toString(), countWidth)}`);
+    }
+    console.log();
+}
 function printDailyBreakdown(entries) {
     const byDay = groupBy(entries, (e) => {
         const date = new Date(e._ts);
-        return date.toISOString().slice(0, 10);
+        return formatLocalDateKey(date);
     });
     const sorted = Array.from(byDay.entries()).sort((a, b) => b[0].localeCompare(a[0]));
     if (sorted.length === 0) {
@@ -258,6 +384,38 @@ function printDailyBreakdown(entries) {
 // ============================================================================
 // Commands
 // ============================================================================
+const STATS_BREAKDOWNS = ["model", "agent", "provider", "day", "daily", "session", "raw-session", "all"];
+const STATS_PERIODS = ["today", "week", "month", "all"];
+const TOP_LEVEL_COMMANDS = ["budget", "doctor", "pricing", "models", "config", "export", "trend"];
+function isStatsBreakdown(value) {
+    return STATS_BREAKDOWNS.includes(value);
+}
+function isStatsPeriod(value) {
+    return STATS_PERIODS.includes(value);
+}
+function isTopLevelCommand(value) {
+    return TOP_LEVEL_COMMANDS.includes(value);
+}
+function getStatsBreakdown(flags) {
+    const longValue = flagValue(flags, "by");
+    const shortValue = flagValue(flags, "b");
+    if (flags.has("by") && !longValue) {
+        failCli("Missing value for --by", "Usage: opencode-tokens [today|week|month|all] --by model|agent|provider|daily|session|raw-session|all");
+        return undefined;
+    }
+    if (flags.has("b") && !shortValue) {
+        failCli("Missing value for -b", "Usage: opencode-tokens [today|week|month|all] -b model|agent|provider|daily|session|raw-session|all");
+        return undefined;
+    }
+    const breakdown = longValue ?? shortValue;
+    if (!breakdown)
+        return undefined;
+    if (!isStatsBreakdown(breakdown)) {
+        failCli(`Unsupported stats breakdown: ${breakdown}`, "Allowed breakdowns: model, agent, provider, daily, day, session, raw-session, all");
+        return undefined;
+    }
+    return breakdown;
+}
 function cmdStats(period, breakdown) {
     const now = new Date();
     let since;
@@ -302,7 +460,10 @@ function cmdStats(period, breakdown) {
             printDailyBreakdown(entries);
             break;
         case "session":
-            printTable("By Session", groupBy(entries, (e) => truncateSessionId(e.sessionId)), "Session");
+            printSessionBreakdown(entries, loadSessionMeta());
+            break;
+        case "raw-session":
+            printSessionBreakdown(entries, loadSessionMeta(), { rollUp: false, heading: "By Raw Session" });
             break;
         case "all":
             printTable("By Model", groupBy(entries, (e) => e.model ?? "unknown"), "Model");
@@ -311,6 +472,40 @@ function cmdStats(period, breakdown) {
             break;
     }
 }
+function formatPricingAudit(audit) {
+    if (!audit)
+        return "-";
+    const expiry = audit.expiresAt ? `; valid until ${audit.expiresAt}` : "";
+    const basis = audit.basis === "peak" ? "; peak estimate" : "";
+    return `${getPricingFreshness(audit)}; reviewed ${audit.reviewedAt}${basis}${expiry}`;
+}
+function printPricingAuditNotes() {
+    console.log(`  Audit status: recent = reviewed within ${PRICING_STALE_AFTER_DAYS} days; stale = older; expired = past known validity; unknown = check date/clock.`);
+    console.log(`  A recent audit does not guarantee that provider prices are unchanged.`);
+    console.log(`  DeepSeek Flash/Pro: peak-rate estimate; off-peak rates are 50% lower. No automatic time/holiday selection.`);
+    console.log(`  Retired DeepSeek aliases keep legacy estimates and are marked expired.`);
+    console.log(`  Current pricing/configuration affects new records only; stored historical costs are not recalculated.`);
+    console.log();
+}
+function getPricingAuditWarnings(entries, config) {
+    const warnings = new Map();
+    const seen = new Set();
+    for (const entry of entries) {
+        const model = entry.model ?? "unknown";
+        const provider = entry.provider ?? "unknown";
+        const key = `${model}|${provider}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        const audit = getEffectivePricingAudit(config, model, provider);
+        if (!audit)
+            continue;
+        const freshness = getPricingFreshness(audit);
+        if (freshness !== "recent")
+            warnings.set(key, { model, provider, audit, freshness });
+    }
+    return Array.from(warnings.values()).sort((a, b) => Number(b.freshness === "expired") - Number(a.freshness === "expired"));
+}
 function cmdPricing() {
     const config = loadConfig();
     console.log(`
@@ -318,27 +513,30 @@ function cmdPricing() {
   ══════════════════════════════════════════════════════════════════
   Pricing last updated:  ${BUILTIN_PRICING_META.pricingLastUpdated}
   Metadata last updated: ${BUILTIN_PRICING_META.metadataLastUpdated}
+  Baseline audit:        ${BUILTIN_PRICING_META.baselineLastUpdated} (unless a model has its own date)
   Source:                ${BUILTIN_PRICING_META.source}
+  Scope:                 ${BUILTIN_PRICING_META.notes}
 `);
     // Group by provider
     const groups = {
-        "Anthropic Claude": ["claude-opus-4.6", "claude-opus-4.5", "claude-sonnet-4.5", "claude-sonnet-4", "claude-haiku-4.5", "claude-haiku-4", "claude-opus-4.1", "claude-opus-4", "claude-haiku-3"],
-        "OpenAI": ["gpt-5.2", "gpt-5.2-pro", "gpt-5-mini", "gpt-5.1", "gpt-5", "gpt-4.1", "gpt-4.1-mini", "gpt-4.1-nano", "gpt-4o", "gpt-4o-mini", "o3", "o3-mini", "o4-mini", "o1", "o1-mini"],
-        "DeepSeek": ["deepseek-chat", "deepseek-reasoner"],
-        "Google Gemini": ["gemini-3-pro", "gemini-3-pro-preview", "gemini-3-flash", "gemini-3-flash-preview", "gemini-2.5-pro", "gemini-2.5-flash", "gemini-2.5-flash-lite", "gemini-2.0-flash", "gemini-2.0-flash-lite"],
+        "Anthropic Claude": ["claude-opus-4.8", "claude-opus-4.7", "claude-opus-4.6", "claude-opus-4.5", "claude-sonnet-4.6", "claude-sonnet-4.5", "claude-sonnet-4", "claude-haiku-4.5", "claude-haiku-4", "claude-opus-4.1", "claude-opus-4", "claude-haiku-3"],
+        "OpenAI": ["gpt-5.5", "gpt-5.5-pro", "gpt-5.4", "gpt-5.4-mini", "gpt-5.4-nano", "gpt-5.4-pro", "gpt-5.3-codex", "gpt-5.3-chat-latest", "gpt-5.2", "gpt-5.2-pro", "gpt-5-mini", "gpt-5-nano", "gpt-5.1", "gpt-5.1-chat-latest", "gpt-5.1-codex-max", "gpt-5.1-codex", "gpt-5.1-codex-mini", "gpt-5", "gpt-5-chat-latest", "gpt-5-codex", "gpt-4.1", "gpt-4.1-mini", "gpt-4.1-nano", "gpt-4o", "gpt-4o-mini", "o3", "o3-mini", "o4-mini", "o1", "o1-mini"],
+        "DeepSeek": ["deepseek-flash", "deepseek-v4-flash", "deepseek-v4-flash-vision-exp", "deepseek-v4-pro", "deepseek-chat", "deepseek-reasoner"],
+        "Moonshot Kimi": ["kimi-k2.7-code"],
+        "Google Gemini": ["gemini-3.1-pro-preview", "gemini-3-pro", "gemini-3-pro-preview", "gemini-3.5-flash", "gemini-3-flash", "gemini-3-flash-preview", "gemini-3.1-flash-lite", "gemini-2.5-pro", "gemini-2.5-flash", "gemini-2.5-flash-lite", "gemini-2.0-flash", "gemini-2.0-flash-lite"],
     };
-    const modelWidth = 20;
+    const modelWidth = Math.max(24, ...Object.values(groups).flat().map(model => model.length + (config.models[model] ? 2 : 0)));
     const priceWidth = 10;
     for (const [group, models] of Object.entries(groups)) {
         console.log(`  ${group}`);
         console.log(`  ${"-".repeat(modelWidth + priceWidth * 4 + 12)}`);
-        console.log(`  ${padRight("Model", modelWidth)}  ${padLeft("Input", priceWidth)}  ${padLeft("Output", priceWidth)}  ${padLeft("CacheRd", priceWidth)}  ${padLeft("CacheWr", priceWidth)}`);
+        console.log(`  ${padRight("Model", modelWidth)}  ${padLeft("Input", priceWidth)}  ${padLeft("Output", priceWidth)}  ${padLeft("CacheRd", priceWidth)}  ${padLeft("CacheWr", priceWidth)}  Audit`);
         for (const model of models) {
             const p = BUILTIN_PRICING[model];
             if (!p)
                 continue;
             const overridden = config.models[model] ? " *" : "";
-            console.log(`  ${padRight(`${model}${overridden}`, modelWidth)}  ${padLeft(`$${p.input.toString()}`, priceWidth)}  ${padLeft(`$${p.output.toString()}`, priceWidth)}  ${padLeft(p.cacheRead ? `$${p.cacheRead.toString()}` : "-", priceWidth)}  ${padLeft(p.cacheWrite ? `$${p.cacheWrite.toString()}` : "-", priceWidth)}`);
+            console.log(`  ${padRight(`${model}${overridden}`, modelWidth)}  ${padLeft(`$${p.input.toString()}`, priceWidth)}  ${padLeft(`$${p.output.toString()}`, priceWidth)}  ${padLeft(p.cacheRead !== undefined ? `$${p.cacheRead.toString()}` : "-", priceWidth)}  ${padLeft(p.cacheWrite !== undefined ? `$${p.cacheWrite.toString()}` : "-", priceWidth)}  ${formatPricingAudit(getBuiltinPricingAudit(model))}`);
         }
         console.log();
     }
@@ -354,8 +552,8 @@ function cmdPricing() {
     console.log(`    When a model is not matched in the built-in pricing table or user configuration,`);
     console.log(`    it falls back to the default rate ($1.0 / $4.0 per 1M tokens).`);
     console.log(`    You can easily override it in your configuration.`);
-    console.log(`    ${BUILTIN_PRICING_META.notes}`);
     console.log();
+    printPricingAuditNotes();
 }
 function cmdModels() {
     const entries = loadEntries();
@@ -390,11 +588,22 @@ function cmdModels() {
     const providerWidth = 16;
     const countWidth = 8;
     const statusWidth = 12;
-    console.log(`  ${padRight("Model", modelWidth)}  ${padRight("Provider", providerWidth)}  ${padLeft("Msgs", countWidth)}  ${padRight("Pricing", statusWidth)}`);
+    console.log(`  ${padRight("Model", modelWidth)}  ${padRight("Provider", providerWidth)}  ${padLeft("Msgs", countWidth)}  ${padRight("Pricing", statusWidth)}  Audit`);
     console.log(`  ${"-".repeat(modelWidth)}  ${"-".repeat(providerWidth)}  ${"-".repeat(countWidth)}  ${"-".repeat(statusWidth)}`);
+    const defaultModels = [];
+    const zeroCostProviderModels = [];
     for (const { model, provider, count } of sorted) {
         const status = resolvePricingStatus(config, model, provider);
-        console.log(`  ${padRight(model, modelWidth)}  ${padRight(provider, providerWidth)}  ${padLeft(count.toString(), countWidth)}  ${padRight(status, statusWidth)}`);
+        if (status === "default") {
+            const zeroCostMatch = getZeroCostProviderMatch(provider);
+            if (zeroCostMatch) {
+                zeroCostProviderModels.push({ model, provider, count, reason: zeroCostMatch.reason });
+            }
+            else {
+                defaultModels.push({ model, provider, count });
+            }
+        }
+        console.log(`  ${padRight(model, modelWidth)}  ${padRight(provider, providerWidth)}  ${padLeft(count.toString(), countWidth)}  ${padRight(status, statusWidth)}  ${formatPricingAudit(getEffectivePricingAudit(config, model, provider))}`);
     }
     console.log();
     console.log(`  Pricing status:`);
@@ -403,6 +612,211 @@ function cmdModels() {
     console.log(`    model cfg    = overridden by models config`);
     console.log(`    default      = unknown model, using $1/$4 per 1M tokens`);
     console.log();
+    printPricingAuditNotes();
+    if (getPricingAuditWarnings(entries, config).length > 0) {
+        console.log(`  Review stale/expired built-in prices with: opencode-tokens pricing`);
+        console.log();
+    }
+    if (zeroCostProviderModels.length > 0 || defaultModels.length > 0) {
+        console.log(`  Next steps for default pricing:`);
+        const total = zeroCostProviderModels.length + defaultModels.length;
+        console.log(`    ${total} model/provider ${total === 1 ? "pair uses" : "pairs use"} the default $1/$4 estimate.`);
+        console.log(`    Run: opencode-tokens config init`);
+        console.log(`    Or:  opencode-tokens config generate`);
+        console.log();
+        if (zeroCostProviderModels.length > 0) {
+            console.log(`    Likely zero-cost provider overrides to review:`);
+            for (const { provider, reason } of dedupeZeroCostProviderMatches(zeroCostProviderModels).slice(0, 5)) {
+                console.log(`    - ${provider} (${reason}): { "input": 0, "output": 0 }`);
+            }
+            if (zeroCostProviderModels.length > 5) {
+                console.log(`    - ...and ${zeroCostProviderModels.length - 5} more model/provider pairs`);
+            }
+            console.log();
+        }
+        if (defaultModels.length > 0) {
+            console.log(`    Model overrides to review before saving:`);
+            for (const { model, provider, count } of defaultModels.slice(0, 5)) {
+                console.log(`    - ${model} (${provider}, ${count} msgs): { "input": 1, "output": 4 }`);
+            }
+            if (defaultModels.length > 5) {
+                console.log(`    - ...and ${defaultModels.length - 5} more`);
+            }
+            console.log();
+        }
+    }
+}
+function cmdDoctor() {
+    const entries = loadEntries();
+    const configDiagnostics = inspectTrackerConfig();
+    const pluginDiagnostics = inspectOpenCodePluginConfig();
+    console.log(`
+  OpenCode Token Tracker Doctor
+  ══════════════════════════════════════════════════════════════════
+`);
+    console.log(`  CLI`);
+    console.log(`    Entry: ${process.argv[1] ?? "unknown"}`);
+    console.log(`    Package version: ${readPackageJsonVersion()}`);
+    console.log();
+    console.log(`  OpenCode plugin config`);
+    if (pluginDiagnostics.found) {
+        console.log(`    File: ${pluginDiagnostics.path}`);
+        console.log(`    Plugin entry: ${pluginDiagnostics.hasPlugin ? "found" : "missing"}`);
+    }
+    else {
+        console.log(`    File: not found (${OPENCODE_CONFIG_FILES.map((p) => p.replace(`${homedir()}/`, "~/")).join(" or ")})`);
+        console.log(`    Plugin entry: unknown`);
+    }
+    console.log();
+    console.log(`  Tracker config`);
+    console.log(`    File: ${CONFIG_FILE}`);
+    console.log(`    Status: ${configDiagnostics.exists ? "exists" : "using defaults"}`);
+    if (configDiagnostics.parseError) {
+        console.log(`    Warning: ${configDiagnostics.parseError}`);
+    }
+    for (const warning of configDiagnostics.warnings) {
+        console.log(`    Warning: ${warning}`);
+    }
+    const budget = configDiagnostics.config.budget;
+    const hasBudget = Boolean(budget.daily || budget.weekly || budget.monthly);
+    console.log(`    Budget: ${hasBudget ? "configured" : "not configured"}`);
+    console.log();
+    console.log(`  Token log`);
+    if (!existsSync(LOG_FILE)) {
+        console.log(`    File: not found (${LOG_FILE})`);
+        console.log(`    Entries: 0`);
+    }
+    else {
+        const latest = entries[entries.length - 1];
+        console.log(`    File: ${LOG_FILE}`);
+        console.log(`    Entries: ${entries.length}`);
+        console.log(`    Latest: ${latest ? `${new Date(latest._ts).toISOString()} (${formatAge(latest._ts)})` : "none"}`);
+    }
+    console.log();
+    const defaultModels = getDefaultModelProviders(entries, configDiagnostics.config);
+    const auditWarnings = getPricingAuditWarnings(entries, configDiagnostics.config);
+    const zeroCostProviders = dedupeZeroCostProviderMatches(defaultModels.flatMap(({ model, provider, count }) => {
+        const match = getZeroCostProviderMatch(provider);
+        return match ? [{ model, provider, count, reason: match.reason }] : [];
+    }));
+    console.log(`  Pricing`);
+    console.log(`    Built-in pricing updated: ${BUILTIN_PRICING_META.pricingLastUpdated}`);
+    console.log(`    ${BUILTIN_PRICING_META.notes}`);
+    console.log(`    Built-in audit warnings: ${auditWarnings.length}`);
+    for (const { model, provider, audit } of auditWarnings.slice(0, 5)) {
+        console.log(`    - ${model} (${provider}): ${formatPricingAudit(audit)}`);
+    }
+    if (auditWarnings.length > 5)
+        console.log(`    - ...and ${auditWarnings.length - 5} more; see opencode-tokens models`);
+    console.log(`    DeepSeek Flash/Pro use peak-rate estimates; off-peak rates are 50% lower.`);
+    console.log(`    Default-priced model/provider pairs: ${defaultModels.length}`);
+    for (const { model, provider, count } of defaultModels.slice(0, 5)) {
+        console.log(`    - ${model} (${provider}, ${count} msgs)`);
+    }
+    if (defaultModels.length > 5) {
+        console.log(`    - ...and ${defaultModels.length - 5} more`);
+    }
+    if (zeroCostProviders.length > 0) {
+        console.log(`    Likely zero-cost providers:`);
+        for (const { provider, reason } of zeroCostProviders.slice(0, 5)) {
+            console.log(`    - ${provider} (${reason})`);
+        }
+    }
+    console.log();
+    const nextSteps = [];
+    if (!pluginDiagnostics.found || !pluginDiagnostics.hasPlugin) {
+        nextSteps.push(`Add "opencode-token-tracker" to your OpenCode plugin config.`);
+    }
+    if (!existsSync(LOG_FILE) || entries.length === 0) {
+        nextSteps.push(`Run an OpenCode request, then check ${LOG_FILE}.`);
+    }
+    if (configDiagnostics.parseError || configDiagnostics.warnings.length > 0) {
+        nextSteps.push(`Fix ${CONFIG_FILE} or regenerate it with: opencode-tokens config generate`);
+    }
+    if (defaultModels.length > 0) {
+        nextSteps.push(`Review default pricing with: opencode-tokens models`);
+        nextSteps.push(`Generate suggested overrides with: opencode-tokens config init`);
+    }
+    if (auditWarnings.length > 0) {
+        nextSteps.push(`Review stale/expired built-in prices with: opencode-tokens pricing`);
+    }
+    if (!hasBudget) {
+        nextSteps.push(`Configure optional budgets with: opencode-tokens config init`);
+    }
+    console.log(`  Next steps`);
+    if (nextSteps.length === 0) {
+        console.log(`    No obvious issues found.`);
+    }
+    else {
+        for (const step of nextSteps) {
+            console.log(`    - ${step}`);
+        }
+    }
+    console.log();
+}
+function readPackageJsonVersion() {
+    try {
+        const pkg = JSON.parse(readFileSync(join(PACKAGE_ROOT, "package.json"), "utf-8"));
+        return typeof pkg.version === "string" ? pkg.version : "unknown";
+    }
+    catch {
+        return "unknown";
+    }
+}
+function inspectOpenCodePluginConfig() {
+    for (const path of OPENCODE_CONFIG_FILES) {
+        if (!existsSync(path))
+            continue;
+        const raw = readFileSync(path, "utf-8");
+        return {
+            found: true,
+            path,
+            hasPlugin: raw.includes("opencode-token-tracker"),
+        };
+    }
+    return { found: false, hasPlugin: false };
+}
+function inspectTrackerConfig() {
+    if (!existsSync(CONFIG_FILE)) {
+        return { exists: false, config: DEFAULT_CONFIG, warnings: [] };
+    }
+    try {
+        const raw = JSON.parse(readFileSync(CONFIG_FILE, "utf-8"));
+        const result = validateConfig(raw);
+        return { exists: true, config: result.config, warnings: result.warnings };
+    }
+    catch {
+        return { exists: true, config: DEFAULT_CONFIG, warnings: [], parseError: "Config file is not valid JSON, using defaults" };
+    }
+}
+function getDefaultModelProviders(entries, config) {
+    const counts = new Map();
+    for (const e of entries) {
+        const model = e.model ?? "unknown";
+        const provider = e.provider ?? "unknown";
+        if (model === "unknown" || provider === "unknown")
+            continue;
+        const key = `${model}|${provider}`;
+        let item = counts.get(key);
+        if (!item) {
+            item = { model, provider, count: 0, lastUsed: 0 };
+            counts.set(key, item);
+        }
+        item.count++;
+        item.lastUsed = Math.max(item.lastUsed, e._ts);
+    }
+    return Array.from(counts.values())
+        .filter(({ model, provider }) => resolvePricingStatus(config, model, provider) === "default")
+        .sort((a, b) => b.lastUsed - a.lastUsed);
+}
+function dedupeZeroCostProviderMatches(items) {
+    const providers = new Map();
+    for (const item of items) {
+        if (!providers.has(item.provider)) {
+            providers.set(item.provider, { provider: item.provider, reason: item.reason });
+        }
+    }
+    return Array.from(providers.values());
 }
 function cmdConfig(positional) {
     const action = positional[1];
@@ -444,12 +858,14 @@ function cmdConfig(positional) {
             },
         };
         const suggestedProviders = [];
-        // Add providers as comments/examples (Common free providers)
+        const suggestedProviderNames = new Set();
+        // Add likely zero-cost providers detected from logs.
         for (const provider of providers) {
-            const pLower = provider.toLowerCase();
-            if (pLower.includes("copilot") || pLower.includes("cursor") || pLower.includes("free")) {
+            const zeroCostMatch = getZeroCostProviderMatch(provider);
+            if (zeroCostMatch) {
                 exampleConfig.providers[provider] = { input: 0, output: 0 };
-                suggestedProviders.push(provider);
+                suggestedProviders.push(zeroCostMatch);
+                suggestedProviderNames.add(provider);
             }
         }
         const suggestedModels = [];
@@ -458,6 +874,8 @@ function cmdConfig(positional) {
             const [model, provider] = mp.split("|");
             if (model === "unknown" || provider === "unknown")
                 continue;
+            if (suggestedProviderNames.has(provider))
+                continue;
             const status = resolvePricingStatus(config, model, provider);
             if (status === "default") {
                 exampleConfig.models[model] = { input: 1, output: 4 };
@@ -488,10 +906,10 @@ function cmdConfig(positional) {
         }
         if (suggestedProviders.length > 0) {
             suggestionsSummary += `
-  Detected zero-cost/subscription providers:
+  Detected likely zero-cost providers:
 `;
-            for (const p of suggestedProviders) {
-                suggestionsSummary += `    • ${p} (automatically pre-configured to $0.00)\n`;
+            for (const { provider, reason } of suggestedProviders) {
+                suggestionsSummary += `    • ${provider} (${reason}, automatically pre-configured to $0.00)\n`;
             }
         }
         if (suggestedModels.length > 0) {
@@ -518,11 +936,11 @@ function cmdConfig(positional) {
 
   Examples:
     { "input": 15, "output": 75 }     = $15 per 1M input, $75 per 1M output
-    { "input": 0, "output": 0 }       = Free (subscription or local model)
+    { "input": 0, "output": 0 }       = Free (subscription or local provider/model)
 
   Common scenarios:
     - GitHub Copilot, Cursor, etc.   → Set provider to { input: 0, output: 0 }
-    - Local/self-hosted models       → Set to 0
+    - Ollama, LM Studio, localhost   → Set provider to { input: 0, output: 0 }
     - Direct API usage               → Look up provider's pricing page
 
   Where to find pricing:
@@ -570,11 +988,11 @@ function cmdConfig(positional) {
     if (action === "get") {
         const key = positional[2];
         if (!key) {
-            console.log("\n  Usage: opencode-tokens config get <key>\n");
+            failCli("Missing config key", "Usage: opencode-tokens config get <key>");
             return;
         }
         if (!SETTABLE_KEYS[key]) {
-            console.log(`\n  Unknown key: ${key}\n  Available: ${Object.keys(SETTABLE_KEYS).join(", ")}\n`);
+            failCli(`Unknown config key: ${key}`, `Available keys: ${Object.keys(SETTABLE_KEYS).join(", ")}`);
             return;
         }
         const value = resolveConfigKey(config, key);
@@ -584,27 +1002,31 @@ function cmdConfig(positional) {
     if (action === "set") {
         const key = positional[2];
         const rawValue = positional[3];
-        if (!key || !rawValue) {
-            console.log("\n  Usage: opencode-tokens config set <key> <value>\n");
+        if (!key) {
+            failCli("Missing config key", "Usage: opencode-tokens config set <key> <value>");
+            return;
+        }
+        if (!rawValue) {
+            failCli("Missing config value", "Usage: opencode-tokens config set <key> <value>");
             return;
         }
         const spec = SETTABLE_KEYS[key];
         if (!spec) {
-            console.log(`\n  Unknown key: ${key}\n  Available: ${Object.keys(SETTABLE_KEYS).join(", ")}\n`);
+            failCli(`Unknown config key: ${key}`, `Available keys: ${Object.keys(SETTABLE_KEYS).join(", ")}`);
             return;
         }
         const value = parseConfigValue(rawValue);
         if (typeof value !== spec.type) {
-            console.log(`\n  Invalid type: expected ${spec.type}, got ${typeof value}\n`);
+            failCli(`Invalid type for ${key}: expected ${spec.type}, got ${typeof value}`);
             return;
         }
         if (typeof value === "number") {
             if (value < 0) {
-                console.log(`\n  Value must be >= 0\n`);
+                failCli(`Invalid value for ${key}: must be >= 0`);
                 return;
             }
             if (spec.max !== undefined && value > spec.max) {
-                console.log(`\n  Value must be <= ${spec.max}\n`);
+                failCli(`Invalid value for ${key}: must be <= ${spec.max}`);
                 return;
             }
         }
@@ -615,12 +1037,12 @@ function cmdConfig(positional) {
     if (action === "unset") {
         const key = positional[2];
         if (!key) {
-            console.log("\n  Usage: opencode-tokens config unset <key>\n");
+            failCli("Missing config key", "Usage: opencode-tokens config unset <key>");
             return;
         }
         const spec = SETTABLE_KEYS[key];
         if (!spec) {
-            console.log(`\n  Unknown key: ${key}\n  Available: ${Object.keys(SETTABLE_KEYS).join(", ")}\n`);
+            failCli(`Unknown config key: ${key}`, `Available keys: ${Object.keys(SETTABLE_KEYS).join(", ")}`);
             return;
         }
         applyConfigUnset(key);
@@ -628,8 +1050,7 @@ function cmdConfig(positional) {
         return;
     }
     if (action && action !== "show") {
-        console.log(`\n  Unknown config action: ${action}`);
-        console.log(`  Usage: opencode-tokens config [show|init|generate|get|set|unset]\n`);
+        failCli(`Unknown config action: ${action}`, "Usage: opencode-tokens config [show|init|generate|get|set|unset]");
         return;
     }
     // Show current config
@@ -733,10 +1154,48 @@ function saveConfig(raw) {
 // ============================================================================
 // Export
 // ============================================================================
+const EXPORT_FORMATS = ["csv", "json"];
+const EXPORT_PERIODS = ["today", "week", "month", "all"];
+function failCli(message, usage) {
+    process.stderr.write(`\n  Error: ${message}\n`);
+    if (usage) {
+        process.stderr.write(`  ${usage}\n`);
+    }
+    process.stderr.write("\n");
+    process.exitCode = 1;
+}
+function isExportFormat(format) {
+    return EXPORT_FORMATS.includes(format);
+}
+function isExportPeriod(period) {
+    return EXPORT_PERIODS.includes(period);
+}
 function cmdExport(flags) {
-    const format = flagValue(flags, "format") || "csv";
-    const period = flagValue(flags, "period") || "all";
+    const formatValue = flagValue(flags, "format");
+    const periodValue = flagValue(flags, "period");
     const outputFile = flagValue(flags, "output");
+    if (flags.has("format") && !formatValue) {
+        failCli("Missing value for --format", "Usage: opencode-tokens export --format csv|json");
+        return;
+    }
+    if (flags.has("period") && !periodValue) {
+        failCli("Missing value for --period", "Usage: opencode-tokens export --period today|week|month|all");
+        return;
+    }
+    if (flags.has("output") && !outputFile) {
+        failCli("Missing value for --output", "Usage: opencode-tokens export --output <file>");
+        return;
+    }
+    const format = formatValue ?? "csv";
+    const period = periodValue ?? "all";
+    if (!isExportFormat(format)) {
+        failCli(`Unsupported export format: ${format}`, "Allowed formats: csv, json");
+        return;
+    }
+    if (!isExportPeriod(period)) {
+        failCli(`Unsupported export period: ${period}`, "Allowed periods: today, week, month, all");
+        return;
+    }
     const now = new Date();
     let since;
     switch (period) {
@@ -780,7 +1239,14 @@ function cmdExport(flags) {
         output = `${[headers.join(","), ...rows].join("\n")}\n`;
     }
     if (outputFile) {
-        writeFileSync(outputFile, output);
+        try {
+            writeFileSync(outputFile, output);
+        }
+        catch (error) {
+            const detail = error instanceof Error ? error.message : String(error);
+            failCli(`Failed to write export file: ${detail}`);
+            return;
+        }
         console.log(`\n  Exported ${entries.length} entries to ${outputFile}\n`);
     }
     else {
@@ -897,6 +1363,7 @@ function cmdHelp() {
   Commands:
     (default)     Show usage statistics
     budget        Show budget status (daily/weekly/monthly)
+    doctor        Diagnose plugin config, logs, and pricing fallbacks
     pricing       Show built-in pricing table
     models        Show your used models and their pricing status
     config        Show/generate/modify configuration
@@ -909,7 +1376,8 @@ function cmdHelp() {
     month         Show this month's usage
     all           Show all-time usage (default)
 
-    --by <type>   Group by: model, agent, provider, session, daily, all
+    --by <type>   Group by: model, agent, provider, session, raw-session, daily, all
+                  (session = rolled up to top-level; raw-session = per session, sub-agents shown separately)
 
   Export Options:
     --format      csv (default) or json
@@ -935,8 +1403,10 @@ function cmdHelp() {
 
   Examples:
     opencode-tokens                       # All-time summary
+    opencode-tokens doctor                # Diagnose setup and logs
     opencode-tokens today --by model      # Today by model
-    opencode-tokens week --by session     # This week by session
+    opencode-tokens week --by session     # This week by top-level session
+    opencode-tokens --by raw-session      # Per session, sub-agents shown separately
     opencode-tokens trend --days 7        # 7-day cost trend
     opencode-tokens export --format csv   # Export all data as CSV
     opencode-tokens config set budget.daily 10  # Set daily budget to $10
@@ -945,6 +1415,10 @@ function cmdHelp() {
   Costs are estimates from local logs; budgets are warnings, not enforcement.
 `);
 }
+const TREND_METRICS = ["cost", "tokens", "messages"];
+function isTrendMetric(metric) {
+    return TREND_METRICS.includes(metric);
+}
 function getTrendValue(point, metric) {
     return metric === "tokens" ? point.tokens : metric === "messages" ? point.messages : point.cost;
 }
@@ -958,6 +1432,25 @@ function formatSignedTrendValue(value, metric) {
 function metricLabel(metric) {
     return metric === "tokens" ? "Token Trend" : metric === "messages" ? "Message Trend" : "Cost Trend";
 }
+function parsePositiveIntegerOption(flags, name, defaultValue, usage) {
+    const value = flagValue(flags, name);
+    if (flags.has(name) && !value) {
+        failCli(`Missing value for --${name}`, usage);
+        return undefined;
+    }
+    if (!value)
+        return defaultValue;
+    if (!/^\d+$/.test(value)) {
+        failCli(`Invalid value for --${name}: ${value}`, usage);
+        return undefined;
+    }
+    const parsed = Number.parseInt(value, 10);
+    if (parsed <= 0) {
+        failCli(`Invalid value for --${name}: ${value}`, usage);
+        return undefined;
+    }
+    return parsed;
+}
 function buildLineRows(points, width, height) {
     const grid = Array.from({ length: height }, () => Array.from({ length: width }, () => " "));
     // 1. Calculate the exact integer row r[x] for every column x from 0 to width - 1
@@ -1064,9 +1557,22 @@ function buildTrendXAxis(points, chartPoints, chartWidth) {
     };
 }
 function cmdTrend(flags) {
-    const days = parseInt(String(flagValue(flags, "days") ?? "30"), 10);
-    const metric = flagValue(flags, "metric") ?? "cost";
-    const width = parseInt(String(flagValue(flags, "width") ?? "60"), 10);
+    const days = parsePositiveIntegerOption(flags, "days", 30, "Usage: opencode-tokens trend --days <positive-integer>");
+    if (days === undefined)
+        return;
+    const metricValue = flagValue(flags, "metric");
+    if (flags.has("metric") && !metricValue) {
+        failCli("Missing value for --metric", "Usage: opencode-tokens trend --metric cost|tokens|messages");
+        return;
+    }
+    const metric = metricValue ?? "cost";
+    if (!isTrendMetric(metric)) {
+        failCli(`Unsupported trend metric: ${metric}`, "Allowed metrics: cost, tokens, messages");
+        return;
+    }
+    const width = parsePositiveIntegerOption(flags, "width", 60, "Usage: opencode-tokens trend --width <positive-integer>");
+    if (width === undefined)
+        return;
     const since = getStartOfDay(new Date(Date.now() - days * 86400000));
     const entries = loadEntries(since);
     if (entries.length === 0) {
@@ -1173,33 +1679,45 @@ function main() {
         return;
     }
     const { command } = parsed;
-    switch (command) {
-        case "budget":
-            cmdBudget();
-            return;
-        case "pricing":
-            cmdPricing();
-            return;
-        case "models":
-            cmdModels();
-            return;
-        case "config":
-            cmdConfig(parsed.positional);
-            return;
-        case "export":
-            cmdExport(parsed.flags);
-            return;
-        case "trend":
-            cmdTrend(parsed.flags);
-            return;
-    }
+    if (isTopLevelCommand(command))
+        switch (command) {
+            case "budget":
+                cmdBudget();
+                return;
+            case "doctor":
+                cmdDoctor();
+                return;
+            case "pricing":
+                cmdPricing();
+                return;
+            case "models":
+                cmdModels();
+                return;
+            case "config":
+                cmdConfig(parsed.positional);
+                return;
+            case "export":
+                cmdExport(parsed.flags);
+                return;
+            case "trend":
+                cmdTrend(parsed.flags);
+                return;
+        }
     // Default: stats
     let period = "all";
-    const breakdown = flagValue(parsed.flags, "by") || (parsed.flags.has("b") ? String(parsed.flags.get("b")) : undefined);
-    for (const p of ["today", "week", "month", "all"]) {
-        if (parsed.positional.includes(p)) {
-            period = p;
-            break;
+    const breakdown = getStatsBreakdown(parsed.flags);
+    if (process.exitCode)
+        return;
+    if (command) {
+        if (!isStatsPeriod(command)) {
+            failCli(`Unknown command or stats period: ${command}`, "Usage: opencode-tokens [today|week|month|all] [--by model|agent|provider|daily|session|raw-session|all]");
+            return;
+        }
+        period = command;
+        const extraArgs = parsed.positional.slice(1);
+        if (extraArgs.length > 0) {
+            failCli(`Unexpected argument for stats command: ${extraArgs[0]}`, "Usage: opencode-tokens [today|week|month|all] [--by model|agent|provider|daily|session|raw-session|all]");
+            return;
         }
     }
     cmdStats(period, breakdown);