token-studio 4.8.0

package/docs/public-launch-checklist.md

@@ -0,0 +1,45 @@
+# Public Launch Checklist
+
+Use this checklist before pushing a public GitHub release or publishing an npm package.
+
+## Required Commands
+
+```bash
+npm test
+npm run build
+npm run privacy:check
+npm audit --audit-level=low
+npm pack --dry-run
+git diff --check
+```
+
+## Screenshots
+
+- Use `npx token-studio demo` after npm publication, or `npm run demo` from a cloned repository.
+- Confirm the UI shows Demo Mode.
+- Do not use real `data/usage.sqlite`.
+- Do not include real project paths, local usernames, exported reports, or private output URLs.
+- Current public screenshot assets:
+  - `docs/assets/token-studio-v45-dashboard.png`
+  - `docs/assets/token-studio-v45-review.png`
+  - `docs/assets/token-studio-v45-live.png`
+  - `docs/assets/token-studio-v45-review-mobile.png`
+
+## GitHub Release
+
+- Repository name: `token-studio-roi`.
+- Current public tag: `v4.7.0`.
+- Current local next version: `v4.8.0`.
+- Historical standalone baseline: `v4.0.0`.
+- Suggested topics: `ai-coding`, `token-usage`, `cost-tracking`, `local-first`, `privacy-first`, `roi`, `codex-cli`, `claude-code`.
+- Release notes should say cost is official public token-price conversion, not a provider invoice.
+- Keep `NOTICE.md` in the repository.
+
+## npm
+
+- Primary package name: `token-studio`.
+- Fallback package name if unavailable: `tokenroi`.
+- Primary one-command demo: `npx token-studio demo`.
+- Do not publish until `npm pack --dry-run` shows no SQLite databases, logs, `.env`, `.claude`, `.codex`, `dist`, or `node_modules`.
+- If the package name is unavailable, publish the fallback only after updating README, package metadata, and release notes consistently.
+- `npm whoami` must succeed before running `npm publish --access public`.

package/docs/resume-bullets.md

@@ -0,0 +1,7 @@
+# Resume Bullets
+
+- Built Token Studio ROI, a local-first AI coding ROI review system using Node.js `node:sqlite`, React, Vite, and a privacy-preserving collector registry.
+- Designed a structured attribution layer that connects AI coding token usage to projects, task type, work stage, output status, value level, and output links.
+- Implemented a local ROI Evidence Score and rule-based Advisor to turn usage history into model-switching, context-compression, and attribution cleanup actions without calling an LLM.
+- Added a `token-studio` CLI for demo mode, local start, explicit collection, collector diagnostics, and public-readiness privacy checks.
+- Hardened local write APIs with loopback, local-Origin, and JSON-only checks, while keeping cost conversion tied to official public token prices.

package/docs/statusline.md

@@ -0,0 +1,52 @@
+# Statusline Guardrails
+
+`token-studio statusline` is a read-only SQLite summary for terminal prompts, tmux, scripts, and Claude Code statusline integrations. It does not scan local AI logs, run ccusage, start a daemon, or read conversation content.
+
+## Basic Command
+
+```bash
+npx token-studio statusline --format=text --window-minutes=15 --max-width=100
+```
+
+For script usage:
+
+```bash
+npx token-studio statusline --format=json --window-minutes=15
+```
+
+## Claude Code Statusline
+
+Use the same text command as your statusline command:
+
+```bash
+npx token-studio statusline --format=text --window-minutes=15 --max-width=100
+```
+
+## tmux
+
+```tmux
+set -g status-right "#(npx token-studio statusline --format=text --window-minutes=15 --max-width=80)"
+```
+
+## PowerShell Prompt
+
+```powershell
+function prompt {
+  $ts = npx token-studio statusline --format=text --window-minutes=15 --max-width=80
+  "$ts PS $($PWD)> "
+}
+```
+
+From a cloned repository, replace `npx token-studio` with `node src/cli.mjs`.
+
+## Output Meaning
+
+- `tok`: tokens in the recent local window.
+- `burn`: tokens per hour if the recent pace continues.
+- `cache`: cache hit percentage from structured token events.
+- `actions`: open Advisor Actions.
+- `budget`: custom token/cost guardrail status and usage share.
+- `reset`: next fixed-window reset countdown, or rolling-window duration.
+- `warn`: highest current guardrail warning.
+
+Budget profiles are custom guardrails. They are not provider subscription quota claims.

package/index.html

@@ -0,0 +1,16 @@
+<!doctype html>
+<html lang="zh-CN">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Token Studio ROI</title>
+    <link rel="icon" href="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 64 64'%3E%3Crect width='64' height='64' rx='16' fill='%23262520'/%3E%3Ctext x='32' y='39' text-anchor='middle' font-family='Arial,sans-serif' font-size='22' font-weight='700' fill='%23faf7ef'%3ETS%3C/text%3E%3C/svg%3E" />
+    <link rel="preconnect" href="https://fonts.googleapis.com" />
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+    <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&family=Instrument+Serif:ital@0;1&family=JetBrains+Mono:wght@400;500&display=swap" rel="stylesheet" />
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/client/main.jsx"></script>
+  </body>
+</html>

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "token-studio",
+  "version": "4.8.0",
+  "description": "Local AI coding ROI studio for private token, output, and model strategy review.",
+  "type": "module",
+  "bin": {
+    "token-studio": "src/cli.mjs"
+  },
+  "scripts": {
+    "start": "node src/cli.mjs start",
+    "demo": "node src/cli.mjs demo",
+    "collect": "node src/collect.mjs",
+    "doctor": "node src/cli.mjs doctor",
+    "privacy:check": "node src/cli.mjs privacy-check",
+    "closure:check": "node src/closure-check.mjs",
+    "closure:import": "node src/closure-import.mjs",
+    "pricing:update": "node src/update-pricing.mjs",
+    "dev": "node src/dev.mjs",
+    "dev:client": "vite --host 127.0.0.1 --port 5173",
+    "dev:server": "node src/server.mjs",
+    "build": "vite build",
+    "preview": "npm run build && node src/server.mjs",
+    "serve": "node src/server.mjs",
+    "test": "node --test"
+  },
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "dependencies": {
+    "@vitejs/plugin-react": "^6.0.2",
+    "echarts": "^6.0.0",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "vite": "^8.0.16"
+  }
+}

package/render.yaml

@@ -0,0 +1,17 @@
+services:
+  - type: web
+    name: token-studio-roi
+    env: docker
+    plan: starter
+    autoDeploy: true
+    envVars:
+      - key: PORT
+        value: 4173
+      - key: HOST
+        value: 0.0.0.0
+      - key: INGEST_TOKEN
+        generateValue: true
+    disk:
+      name: token-studio-roi-data
+      mountPath: /app/data
+      sizeGB: 1

package/src/auto-attribution.mjs

@@ -0,0 +1,396 @@
+export const AUTO_ATTRIBUTION_VERSION = 'v4.0.0';
+export const AUTO_ATTRIBUTION_THRESHOLD = 80;
+
+const DEFAULTS = {
+  taskType: '未分类',
+  outputStatus: '未标注',
+  workPurpose: '未说明',
+  workStage: '未说明',
+  valueLevel: '未评估'
+};
+
+const OUTPUT_RULES = {
+  PR: {
+    taskType: '功能开发',
+    outputStatus: '已完成',
+    workPurpose: '功能开发',
+    workStage: '实现',
+    valueLevel: '中',
+    confidence: 85,
+    reason: '已有 PR 产出链接，结构化证据足以判断为已完成的功能开发。'
+  },
+  commit: {
+    taskType: '功能开发',
+    outputStatus: '已完成',
+    workPurpose: '功能开发',
+    workStage: '实现',
+    valueLevel: '中',
+    confidence: 85,
+    reason: '已有 commit 产出链接，结构化证据足以判断为已完成的功能开发。'
+  },
+  部署: {
+    taskType: '运维配置',
+    outputStatus: '已发布',
+    workPurpose: '部署运维',
+    workStage: '发布',
+    valueLevel: '高',
+    confidence: 90,
+    reason: '已有部署产出链接，结构化证据足以判断为已发布。'
+  },
+  文章: {
+    taskType: '内容创作',
+    outputStatus: '已完成',
+    workPurpose: '文档内容',
+    workStage: '发布',
+    valueLevel: '中',
+    confidence: 85,
+    reason: '已有文章产出链接，结构化证据足以判断为已完成的内容产出。'
+  },
+  文档: {
+    taskType: '内容创作',
+    outputStatus: '已完成',
+    workPurpose: '文档内容',
+    workStage: '发布',
+    valueLevel: '中',
+    confidence: 85,
+    reason: '已有文档产出链接，结构化证据足以判断为已完成的文档内容。'
+  },
+  截图: {
+    taskType: '其他',
+    outputStatus: '已完成',
+    workPurpose: '文档内容',
+    workStage: '验证',
+    valueLevel: '中',
+    confidence: 82,
+    reason: '已有截图产出链接，结构化证据足以判断为已完成的可展示产出。'
+  }
+};
+
+export function buildAutoAttributionPlan({
+  sessions = [],
+  projectAliasRules = [],
+  now = new Date(),
+  threshold = AUTO_ATTRIBUTION_THRESHOLD
+} = {}) {
+  const generatedAt = toIso(now);
+  const suggestions = sessions
+    .map(session => buildAutoAttributionSuggestion(session, { projectAliasRules, now, threshold, generatedAt }))
+    .filter(Boolean)
+    .sort((a, b) => Number(b.canApply) - Number(a.canApply)
+      || b.annotationConfidence - a.annotationConfidence
+      || (b.totalTokens || 0) - (a.totalTokens || 0));
+
+  const highConfidence = suggestions.filter(item => item.canApply);
+  const lowConfidence = suggestions.filter(item =>
+    item.annotationConfidence >= 60 && item.annotationConfidence < threshold
+  );
+  const skipped = sessions.length - suggestions.length;
+  const initiallyUnattributed = sessions.filter(isReviewIncomplete).length;
+  const remainingAfterApply = sessions.filter(session => {
+    const suggestion = highConfidence.find(item => sameSession(item, session));
+    return isReviewIncomplete(suggestion ? { ...session, ...suggestion.applicableValues } : session);
+  }).length;
+
+  return {
+    version: AUTO_ATTRIBUTION_VERSION,
+    generatedAt,
+    threshold,
+    totalSessions: sessions.length,
+    suggestionCount: suggestions.length,
+    highConfidenceCount: highConfidence.length,
+    lowConfidenceCount: lowConfidence.length,
+    skippedCount: skipped,
+    initiallyUnattributed,
+    estimatedRemainingUnattributed: remainingAfterApply,
+    estimatedReductionShare: initiallyUnattributed
+      ? (initiallyUnattributed - remainingAfterApply) / initiallyUnattributed
+      : 0,
+    suggestions
+  };
+}
+
+export function buildAutoAttributionSuggestion(session = {}, options = {}) {
+  if (!canAutoWrite(session)) return null;
+
+  const now = options.now instanceof Date ? options.now : new Date(options.now || Date.now());
+  const generatedAt = options.generatedAt || toIso(now);
+  const threshold = Number(options.threshold || AUTO_ATTRIBUTION_THRESHOLD);
+  const reasons = [];
+  const values = {
+    projectAlias: normalizeText(session.manualProjectAlias || session.projectAlias) || null,
+    taskType: session.taskType || DEFAULTS.taskType,
+    outputStatus: session.outputStatus || DEFAULTS.outputStatus,
+    workPurpose: session.workPurpose || DEFAULTS.workPurpose,
+    workStage: session.workStage || DEFAULTS.workStage,
+    valueLevel: session.valueLevel || DEFAULTS.valueLevel,
+    note: normalizeText(session.note) || null
+  };
+  const fieldConfidence = {};
+
+  const alias = inferProjectAlias(session, options.projectAliasRules || []);
+  if (!values.projectAlias && alias.value) {
+    values.projectAlias = alias.value;
+    fieldConfidence.projectAlias = alias.confidence;
+    reasons.push(alias.reason);
+  }
+
+  const outputRule = inferFromOutput(session);
+  if (outputRule) {
+    applyIfDefault(values, fieldConfidence, 'taskType', outputRule.taskType, outputRule.confidence);
+    applyIfDefault(values, fieldConfidence, 'outputStatus', outputRule.outputStatus, outputRule.confidence);
+    applyIfDefault(values, fieldConfidence, 'workPurpose', outputRule.workPurpose, outputRule.confidence);
+    applyIfDefault(values, fieldConfidence, 'workStage', outputRule.workStage, outputRule.confidence);
+    applyIfDefault(values, fieldConfidence, 'valueLevel', outputRule.valueLevel, outputRule.confidence);
+    reasons.push(outputRule.reason);
+  } else {
+    const active = inferActiveStatus(session, now);
+    if (active && isDefault(values.outputStatus, 'outputStatus')) {
+      values.outputStatus = active.outputStatus;
+      fieldConfidence.outputStatus = active.confidence;
+      reasons.push(active.reason);
+    }
+    const shape = inferFromTokenShape(session);
+    if (shape) {
+      applyIfDefault(values, fieldConfidence, 'taskType', shape.taskType, shape.confidence);
+      applyIfDefault(values, fieldConfidence, 'workPurpose', shape.workPurpose, shape.confidence);
+      applyIfDefault(values, fieldConfidence, 'workStage', shape.workStage, shape.confidence);
+      reasons.push(shape.reason);
+    }
+  }
+
+  const changedFields = Object.entries(values)
+    .filter(([field, value]) => field !== 'note' && !sameValue(value, session[field]) && !isUnhelpfulDefault(field, value))
+    .map(([field]) => field);
+  if (!changedFields.length) return null;
+
+  const confidenceValues = Object.values(fieldConfidence).filter(value => Number.isFinite(value));
+  const annotationConfidence = confidenceValues.length
+    ? Math.min(...confidenceValues)
+    : 60;
+  const applicableFields = changedFields.filter(field => Number(fieldConfidence[field] || 0) >= threshold);
+  const applicableValues = Object.fromEntries(applicableFields.map(field => [field, values[field]]));
+  const applyConfidenceValues = applicableFields.map(field => fieldConfidence[field]);
+  const applyConfidence = applyConfidenceValues.length ? Math.min(...applyConfidenceValues) : 0;
+  const annotationReason = reasons.join('；').slice(0, 500);
+  const canApply = applicableFields.length > 0;
+
+  return {
+    device: session.device,
+    source: session.source,
+    sessionId: session.sessionId,
+    projectPath: session.projectPath || null,
+    totalTokens: session.totalTokens || 0,
+    costUSD: session.costUSD || 0,
+    model: session.model || session.pricingModel || null,
+    values,
+    changedFields,
+    applicableFields,
+    applicableValues,
+    fieldConfidence,
+    annotationSource: 'auto',
+    annotationConfidence,
+    applyConfidence,
+    annotationReason,
+    autoVersion: AUTO_ATTRIBUTION_VERSION,
+    autoRunId: null,
+    autoUpdatedAt: generatedAt,
+    canApply,
+    evidence: summarizeEvidence(session, changedFields, annotationConfidence)
+  };
+}
+
+export function attachAutoSuggestions(sessions = [], suggestions = []) {
+  const byKey = new Map(suggestions.map(item => [sessionKey(item), item]));
+  return sessions.map(session => ({
+    ...session,
+    autoSuggestion: byKey.get(sessionKey(session)) || null
+  }));
+}
+
+export function autoAttributionIdentity(suggestion = {}) {
+  return {
+    device: suggestion.device,
+    source: suggestion.source,
+    sessionId: suggestion.sessionId
+  };
+}
+
+function canAutoWrite(session) {
+  const source = normalizeText(session.annotationSource);
+  return !source || source === 'auto';
+}
+
+function inferProjectAlias(session, rules = []) {
+  if (session.ruleProjectAlias) {
+    return {
+      value: session.ruleProjectAlias,
+      confidence: 92,
+      reason: `命中项目别名规则：${session.ruleProjectAlias}`
+    };
+  }
+  const projectPath = normalizeText(session.projectPath);
+  const matchedRuleAlias = matchProjectAliasRule(projectPath, rules);
+  if (matchedRuleAlias) {
+    return {
+      value: matchedRuleAlias,
+      confidence: 92,
+      reason: `命中项目别名规则：${matchedRuleAlias}`
+    };
+  }
+  const fromPath = basename(session.projectPath);
+  if (fromPath) {
+    return {
+      value: fromPath,
+      confidence: 80,
+      reason: `根据项目路径末级目录推断项目别名：${fromPath}`
+    };
+  }
+  const fromSession = basename(projectPathFromSessionId(session.sessionId));
+  if (fromSession) {
+    return {
+      value: fromSession,
+      confidence: 65,
+      reason: `根据 session_id 中的本地路径片段粗略推断项目别名：${fromSession}`
+    };
+  }
+  return { value: null, confidence: 0, reason: '' };
+}
+
+function matchProjectAliasRule(projectPath, rules = []) {
+  const target = normalizeText(projectPath);
+  if (!target) return null;
+  const normalizedTarget = target.toLowerCase();
+  for (const rule of rules) {
+    if (!rule?.enabled) continue;
+    const pattern = normalizeText(rule.pattern);
+    if (!pattern) continue;
+    const normalizedPattern = pattern.toLowerCase();
+    if (rule.matchType === 'prefix' && normalizedTarget.startsWith(normalizedPattern)) return rule.projectAlias;
+    if (rule.matchType === 'contains' && normalizedTarget.includes(normalizedPattern)) return rule.projectAlias;
+    if (rule.matchType === 'regex') {
+      try {
+        if (new RegExp(pattern, 'i').test(target)) return rule.projectAlias;
+      } catch {
+        continue;
+      }
+    }
+  }
+  return null;
+}
+
+function inferFromOutput(session) {
+  if (!session.outputUrl) return null;
+  const type = normalizeText(session.outputType) || '未分类';
+  if (OUTPUT_RULES[type]) return OUTPUT_RULES[type];
+  return {
+    taskType: '其他',
+    outputStatus: '已完成',
+    workPurpose: '其他',
+    workStage: '验证',
+    valueLevel: '中',
+    confidence: 80,
+    reason: '已有产出链接，但类型未分类，因此仅按已完成产出做保守归因。'
+  };
+}
+
+function inferActiveStatus(session, now) {
+  const last = parseDate(session.lastActivity);
+  if (!last) return null;
+  const ageHours = (now.getTime() - last.getTime()) / 36e5;
+  if (ageHours < 0 || ageHours > 48) return null;
+  return {
+    outputStatus: '进行中',
+    confidence: 70,
+    reason: '最近 48 小时内仍有活动且暂无产出链接，保守建议为进行中。'
+  };
+}
+
+function inferFromTokenShape(session) {
+  const input = Number(session.inputTokens || 0);
+  const output = Number(session.outputTokens || 0);
+  const total = Number(session.totalTokens || 0);
+  const ratio = output > 0 ? input / output : input ? Infinity : 0;
+  if (input >= 100_000 && total >= 120_000 && ratio >= 8) {
+    return {
+      taskType: '技术调研',
+      workPurpose: '上下文整理',
+      workStage: '探索',
+      confidence: 65,
+      reason: '输入显著高于输出，且没有产出链接，仅能低置信建议为技术调研或上下文整理。'
+    };
+  }
+  return null;
+}
+
+function applyIfDefault(values, fieldConfidence, field, value, confidence) {
+  if (!isDefault(values[field], field)) return;
+  values[field] = value;
+  fieldConfidence[field] = confidence;
+}
+
+function isDefault(value, field) {
+  return (value || DEFAULTS[field]) === DEFAULTS[field];
+}
+
+function isUnhelpfulDefault(field, value) {
+  return field in DEFAULTS && (value || DEFAULTS[field]) === DEFAULTS[field];
+}
+
+function isReviewIncomplete(session = {}) {
+  return Object.entries(DEFAULTS).some(([field, fallback]) => (session[field] || fallback) === fallback);
+}
+
+function summarizeEvidence(session, fields, confidence) {
+  const bits = [
+    `${fields.length} 个字段`,
+    `置信度 ${confidence}%`
+  ];
+  if (session.outputType && session.outputUrl) bits.push(`产出类型 ${session.outputType}`);
+  if (session.ruleProjectAlias) bits.push('命中别名规则');
+  if (session.projectPath) bits.push('本地项目路径');
+  return bits.join(' · ');
+}
+
+function sameSession(left, right) {
+  return sessionKey(left) === sessionKey(right);
+}
+
+function sessionKey(row = {}) {
+  return `${row.device || ''}::${row.source || ''}::${row.sessionId || ''}`;
+}
+
+function sameValue(left, right) {
+  return normalizeText(left) === normalizeText(right);
+}
+
+function basename(value) {
+  const text = normalizeText(value);
+  if (!text || text === 'Unknown Project') return null;
+  const cleaned = text.replace(/[\\/]+$/, '');
+  const parts = cleaned.split(/[\\/]/).filter(Boolean);
+  return parts.at(-1) || null;
+}
+
+function projectPathFromSessionId(sessionId) {
+  const text = normalizeText(sessionId);
+  if (!text.startsWith('local:')) return '';
+  const lastColon = text.lastIndexOf(':');
+  if (lastColon <= 'local:'.length) return '';
+  const withoutModel = text.slice(0, lastColon);
+  return withoutModel.replace(/^local:[^:]+:/, '');
+}
+
+function parseDate(value) {
+  if (!value) return null;
+  const date = new Date(value);
+  return Number.isNaN(date.getTime()) ? null : date;
+}
+
+function toIso(value) {
+  const date = value instanceof Date ? value : new Date(value);
+  return Number.isNaN(date.getTime()) ? new Date().toISOString() : date.toISOString();
+}
+
+function normalizeText(value) {
+  return String(value ?? '').trim().replace(/\s+/g, ' ');
+}

package/src/ccusage-bridge.mjs

@@ -0,0 +1,74 @@
+import { spawn } from 'node:child_process';
+import { basename } from 'node:path';
+import { parseCcusageJsonText, planCcusageImport } from './ccusage-import.mjs';
+
+export const CCUSAGE_CLI_REPORTS = ['daily', 'weekly', 'monthly', 'session', 'blocks'];
+
+export async function runCcusageCliImportPlan({
+  report = 'session',
+  ccusageBin = null,
+  device,
+  now = new Date()
+} = {}) {
+  const invocation = ccusageInvocation({ report, ccusageBin });
+  const { stdout } = await runCommand(invocation);
+  const payload = parseCcusageJsonText(stdout);
+  const plan = planCcusageImport(payload, {
+    device,
+    now,
+    importSource: 'import:ccusage-cli',
+    toolCategory: 'import:ccusage-cli',
+    command: invocation.commandLabel
+  });
+  return { plan, invocation };
+}
+
+export function ccusageInvocation({ report = 'session', ccusageBin = null } = {}) {
+  const normalizedReport = String(report || 'session').toLowerCase();
+  if (!CCUSAGE_CLI_REPORTS.includes(normalizedReport)) {
+    throw new Error(`--report must be one of: ${CCUSAGE_CLI_REPORTS.join(', ')}`);
+  }
+  if (ccusageBin) {
+    const command = String(ccusageBin);
+    return {
+      command,
+      args: [normalizedReport, '--json', '--no-cost'],
+      commandLabel: `${basename(command)} ${normalizedReport} --json --no-cost`
+    };
+  }
+  return {
+    command: process.platform === 'win32' ? 'npx.cmd' : 'npx',
+    args: ['ccusage@latest', normalizedReport, '--json', '--no-cost'],
+    commandLabel: `npx ccusage@latest ${normalizedReport} --json --no-cost`
+  };
+}
+
+function runCommand(invocation) {
+  return new Promise((resolve, reject) => {
+    const shell = process.platform === 'win32' && /\.(cmd|bat)$/i.test(invocation.command);
+    const child = spawn(invocation.command, invocation.args, {
+      cwd: process.cwd(),
+      env: process.env,
+      stdio: ['ignore', 'pipe', 'pipe'],
+      windowsHide: true,
+      shell
+    });
+    let stdout = '';
+    let stderr = '';
+    child.stdout.setEncoding('utf8');
+    child.stderr.setEncoding('utf8');
+    child.stdout.on('data', chunk => { stdout += chunk; });
+    child.stderr.on('data', chunk => { stderr += chunk; });
+    child.on('error', error => {
+      reject(new Error(`ccusage CLI failed to start: ${error.message}`));
+    });
+    child.on('close', code => {
+      if (code === 0) {
+        resolve({ stdout, stderr });
+        return;
+      }
+      const detail = stderr.trim() || stdout.trim() || `exit code ${code}`;
+      reject(new Error(`ccusage CLI failed: ${detail.slice(0, 800)}`));
+    });
+  });
+}