pan-wizard 2.9.1 → 3.5.0

package/pan-wizard-core/bin/lib/constants.cjs

@@ -33,6 +33,7 @@ const CONTEXT_SUFFIX = '-context.md';
 const RESEARCH_SUFFIX = '-research.md';
 const VERIFICATION_SUFFIX = '-verification.md';
 const UAT_SUFFIX = '-uat.md';
+const VALIDATION_SUFFIX = '-validation.md';
 
 // ─── File matching helpers ───────────────────────────────────────────────────
 
@@ -123,7 +124,7 @@ const FOCUS_DIR = 'focus';
 const AUTO_RUN_FILE = 'auto-run.json';
 
 /** Focus auto-runner categories */
-const FOCUS_CATEGORIES = ['cleanup', 'tests', 'stability', 'features', 'docs', 'optimize', 'prompts'];
+const FOCUS_CATEGORIES = ['cleanup', 'tests', 'stability', 'features', 'docs', 'optimize', 'prompts', 'security', 'distill'];
 
 /** Category → priority index range (indices into PRIORITY_LEVELS) */
 const CATEGORY_PRIORITY_RANGE = {
@@ -134,6 +135,8 @@ const CATEGORY_PRIORITY_RANGE = {
   docs:      { min: 5, max: 6 },  // P5-P6
   optimize:  { min: 1, max: 4 },  // P1-P4
   prompts:   { min: 0, max: 6 },  // P0-P6 (all priorities — prompt order is authoritative)
+  security:  { min: 0, max: 2 },  // P0-P2 (critical/high/medium only — low/info skipped)
+  distill:   { min: 1, max: 5 },  // P1-P5 (AI bloat: structural quality, not safety-critical)
 };
 
 /** Category → default mode + budget */
@@ -145,6 +148,8 @@ const CATEGORY_DEFAULTS = {
   docs:      { mode: 'balanced', budget: 30 },
   optimize:  { mode: 'balanced', budget: 50 },
   prompts:   { mode: 'balanced', budget: 100 },
+  security:  { mode: 'bugfix',   budget: 40 },
+  distill:   { mode: 'balanced', budget: 50 },
 };
 
 /** Doc files to scan for staleness (focus sync) */
@@ -595,6 +600,37 @@ const AUTORUN_STATUSES = {
 const FILLED_BLOCK = '\u2588';
 const EMPTY_BLOCK = '\u2591';
 
+// ─── Opus 4.7 capability thresholds ─────────────────────────────────────────
+// Used by resolveModel to pick tier given cache/thinking/context hints.
+
+/** Context estimate (tokens) above which only 1M-context models (reasoning tier) apply */
+const LARGE_CONTEXT_TOKEN_THRESHOLD = 700000;
+/** Context estimate below which fast tier is viable for cached + non-thinking work */
+const SMALL_CONTEXT_TOKEN_THRESHOLD = 50000;
+/** Files whose content is stable across agent calls in a phase — candidates for prompt caching */
+const CACHEABLE_CONTEXT_FILES = [
+  'project.md',
+  'requirements.md',
+  'roadmap.md',
+  'state.md',
+  'standards.md',
+];
+/** Default thinking budget (tokens) for verification-heavy agents */
+const THINKING_BUDGETS = {
+  'pan-plan-checker': 8000,
+  'pan-verifier': 6000,
+  'pan-integration-checker': 6000,
+  'pan-reviewer': 4000,
+  'pan-debugger': 8000,
+  'pan-roadmapper': 4000,
+  default: 2000,
+};
+/** Whether focus-auto should insert a thinking-gated reflection step between cycles */
+const REFLECTION_THRESHOLD = {
+  enabled_default: false,
+  enable_on_tiers: ['reasoning'],
+};
+
 module.exports = {
   // Directories
   PLANNING_DIR,
@@ -619,6 +655,7 @@ module.exports = {
   RESEARCH_SUFFIX,
   VERIFICATION_SUFFIX,
   UAT_SUFFIX,
+  VALIDATION_SUFFIX,
   // File matchers
   isPlanFile,
   isSummaryFile,
@@ -674,6 +711,12 @@ module.exports = {
   MAX_SLUG_LENGTH,
   FILLED_BLOCK,
   EMPTY_BLOCK,
+  // Opus 4.7 capabilities
+  LARGE_CONTEXT_TOKEN_THRESHOLD,
+  SMALL_CONTEXT_TOKEN_THRESHOLD,
+  CACHEABLE_CONTEXT_FILES,
+  THINKING_BUDGETS,
+  REFLECTION_THRESHOLD,
   CONTEXT_WINDOW,
   WARNING_THRESHOLD,
   CRITICAL_THRESHOLD,

package/pan-wizard-core/bin/lib/context-budget.cjs

@@ -101,6 +101,29 @@ function cmdContextBudget(cwd, raw) {
     recommendation = `Within budget. ~${additionalPlans} more plans could fit before degradation.`;
   }
 
+  // E-8: cache metrics — surface how much of the total context would be
+  // served from prompt cache when Opus 4.7 cache_control is active.
+  const { buildCachedContext } = require('./core.cjs');
+  let cache = null;
+  try {
+    const cached = buildCachedContext(cwd);
+    const cacheTokens = Math.ceil(cached.total_bytes / 4); // CHARS_PER_TOKEN ~ 4
+    const eligiblePct = totalTokens > 0
+      ? Math.round((cacheTokens / totalTokens) * 1000) / 10
+      : 0;
+    cache = {
+      block_count: cached.blocks.length,
+      block_paths: cached.blocks.map(b => b.path),
+      total_bytes: cached.total_bytes,
+      total_tokens: cacheTokens,
+      eligible_pct: eligiblePct,
+      sha: cached.sha,
+    };
+  } catch {
+    // buildCachedContext failed — surface as null, not as an error.
+    cache = null;
+  }
+
   const result = {
     status,
     currentPhase: currentPhase || null,
@@ -117,6 +140,7 @@ function cmdContextBudget(cwd, raw) {
     },
     contextWindow: CONTEXT_WINDOW,
     budgetUtilization: Math.round(utilization * 1000) / 1000,
+    cache,
     recommendation,
   };
 
@@ -136,6 +160,9 @@ function cmdContextBudget(cwd, raw) {
       `  Total:       ${totalTokens.toLocaleString()} / ${CONTEXT_WINDOW.toLocaleString()}`,
       ``,
       `Utilization: ${(utilization * 100).toFixed(1)}%`,
+      cache && cache.block_count > 0
+        ? `Cache: ${cache.block_count} blocks, ${cache.total_tokens.toLocaleString()} tokens (${cache.eligible_pct}% of total)`
+        : `Cache: 0 blocks (no cacheable .planning files)`,
       `${recommendation}`,
     ];
     return output(result, true, lines.join('\n'));

package/pan-wizard-core/bin/lib/core.cjs

@@ -33,10 +33,10 @@ const {
  * "inherit" means the host runtime uses its own top-tier model selection.
  */
 const PROVIDER_MODELS = {
-  anthropic: { reasoning: 'inherit', mid: 'sonnet', fast: 'haiku' },
-  openai:    { reasoning: 'inherit', mid: 'mid',    fast: 'fast'  },
-  google:    { reasoning: 'inherit', mid: 'mid',    fast: 'fast'  },
-  default:   { reasoning: 'inherit', mid: 'sonnet', fast: 'haiku' },
+  anthropic: { reasoning: 'inherit', mid: 'sonnet',                 fast: 'haiku' },
+  openai:    { reasoning: 'inherit', mid: 'mid',                    fast: 'fast'  },
+  google:    { reasoning: 'inherit', mid: 'gemini-2.5-flash',       fast: 'gemini-2.5-flash-lite' },
+  default:   { reasoning: 'inherit', mid: 'sonnet',                 fast: 'haiku' },
 };
 
 /** Maps legacy Anthropic model names to provider-agnostic tier aliases. */
@@ -493,7 +493,7 @@ function getRoadmapPhaseInternal(cwd, phaseNum) {
     const sectionEnd = nextHeaderMatch ? headerIndex + nextHeaderMatch.index : content.length;
     const section = content.slice(headerIndex, sectionEnd).trim();
 
-    const goalMatch = section.match(/\*\*Goal:\*\*\s*([^\n]+)/i);
+    const goalMatch = section.match(/(?:\*\*Goal:\*\*|\*\*Goal\*\*:)\s*([^\n]+)/i);
     const goal = goalMatch ? goalMatch[1].trim() : null;
 
     return {
@@ -522,12 +522,49 @@ function getPhaseModelTier(cwd, phaseNum) {
   return match ? match[1] : null;
 }
 
+/**
+ * Adjust a resolved tier given Opus 4.7-era capability hints.
+ *
+ * Rules, in priority order:
+ *   1. context_estimate > LARGE_CONTEXT_TOKEN_THRESHOLD → force reasoning (only 1M-ctx tier).
+ *   2. needs_thinking → upgrade fast → mid; leave mid/reasoning alone.
+ *   3. cache_warm + !needs_thinking + context_estimate < SMALL_CONTEXT_TOKEN_THRESHOLD →
+ *      allow downgrade mid → fast (cheap, cached, simple tasks don't need mid).
+ *
+ * @param {string} tier - Baseline tier (reasoning|mid|fast)
+ * @param {Object} [opts] - {context_estimate, needs_thinking, cache_warm}
+ * @returns {string} Possibly-adjusted tier
+ */
+function adjustTierForCapabilities(tier, opts) {
+  if (!opts) return tier;
+  const { context_estimate, needs_thinking, cache_warm } = opts;
+  const { LARGE_CONTEXT_TOKEN_THRESHOLD, SMALL_CONTEXT_TOKEN_THRESHOLD } = require('./constants.cjs');
+
+  if (typeof context_estimate === 'number' && context_estimate > LARGE_CONTEXT_TOKEN_THRESHOLD) {
+    return 'reasoning';
+  }
+  if (needs_thinking && tier === 'fast') {
+    return 'mid';
+  }
+  if (
+    cache_warm &&
+    !needs_thinking &&
+    typeof context_estimate === 'number' &&
+    context_estimate < SMALL_CONTEXT_TOKEN_THRESHOLD &&
+    tier === 'mid'
+  ) {
+    return 'fast';
+  }
+  return tier;
+}
+
 /**
  * Resolve the model for a given agent type based on profile, provider, and routing strategy.
  * Returns "inherit" for reasoning-tier to let the host runtime use its top-tier model.
  * @param {string} cwd - Project root directory
  * @param {string} agentType - Agent name (e.g., "pan-planner", "pan-executor")
- * @param {Object} [taskMetadata] - Optional metadata for complexity routing
+ * @param {Object} [taskMetadata] - Optional metadata. Supports complexity fields and
+ *   Opus 4.7 capability hints: {context_estimate, needs_thinking, cache_warm}.
  * @returns {string} Model identifier: "inherit", "sonnet", "haiku", "mid", "fast", etc.
  */
 function resolveModelInternal(cwd, agentType, taskMetadata) {
@@ -562,6 +599,15 @@ function resolveModelInternal(cwd, agentType, taskMetadata) {
     tier = resolveComplexityTier(tier, { ...taskMetadata, thresholds });
   }
 
+  // Opus 4.7 capability adjustment (only when hints are present)
+  if (taskMetadata && (
+    taskMetadata.context_estimate !== undefined ||
+    taskMetadata.needs_thinking !== undefined ||
+    taskMetadata.cache_warm !== undefined
+  )) {
+    tier = adjustTierForCapabilities(tier, taskMetadata);
+  }
+
   return resolveTierToModel(tier, provider);
 }
 
@@ -731,6 +777,43 @@ function scanPendingTodos(cwd, area) {
  * @param {string} cwd - Project root
  * @returns {{ count: number, items: Array<{file: string, line: number, tag: string, text: string}> }}
  */
+/**
+ * Build an ordered list of cacheable context blocks for agent prompts.
+ *
+ * Reads files from .planning/ that are stable across agent calls within a phase
+ * (project.md, requirements.md, roadmap.md, state.md, standards.md). Each block
+ * is tagged `cache: true` so the host runtime (or installer) can translate to
+ * the appropriate per-runtime caching syntax (Anthropic cache_control, etc.).
+ *
+ * Files that don't exist are skipped silently. The order matches the file list
+ * in constants.cjs to keep prompt prefixes byte-stable across calls (which is
+ * what cache key matching requires).
+ *
+ * @param {string} cwd - Project root
+ * @returns {{blocks: Array<{path: string, content: string, cache: true}>, total_bytes: number, sha: string}}
+ */
+function buildCachedContext(cwd) {
+  const { PLANNING_DIR, CACHEABLE_CONTEXT_FILES } = require('./constants.cjs');
+  const crypto = require('crypto');
+  const blocks = [];
+  let totalBytes = 0;
+  const hasher = crypto.createHash('sha256');
+
+  for (const file of CACHEABLE_CONTEXT_FILES) {
+    const abs = path.join(cwd, PLANNING_DIR, file);
+    try {
+      const content = fs.readFileSync(abs, 'utf-8');
+      blocks.push({ path: toPosix(path.join(PLANNING_DIR, file)), content, cache: true });
+      totalBytes += Buffer.byteLength(content, 'utf-8');
+      hasher.update(file + '\0' + content + '\0');
+    } catch {
+      // Missing files are expected (e.g. standards.md in non-regulated projects).
+    }
+  }
+
+  return { blocks, total_bytes: totalBytes, sha: hasher.digest('hex').slice(0, 16) };
+}
+
 function scanSourceTodos(cwd) {
   const items = [];
   const libDir = path.join(cwd, 'pan-wizard-core', 'bin', 'lib');
@@ -783,6 +866,7 @@ module.exports = {
   getArchivedPhaseDirs,
   getRoadmapPhaseInternal,
   resolveModelInternal,
+  adjustTierForCapabilities,
   detectProvider,
   resolveTierToModel,
   resolveComplexityTier,
@@ -792,6 +876,7 @@ module.exports = {
   generateSlugInternal,
   getMilestoneInfo,
   toPosix,
+  buildCachedContext,
   scanPendingTodos,
   scanSourceTodos,
 };

package/pan-wizard-core/bin/lib/cost.cjs

@@ -0,0 +1,359 @@
+/**
+ * Cost — per-call cost aggregation and dashboard (Spec B v2 Y-6, v3.0).
+ *
+ * Storage: `.planning/metrics/tokens.jsonl` — append-only JSON Lines.
+ *
+ * Each line is a cost record:
+ *   {
+ *     ts: "2026-04-18T12:34:56.789Z",
+ *     agent: "pan-planner" | null,         // agent name, if spawned as agent
+ *     command: "exec-phase" | null,         // command name, if invoked directly
+ *     model: "claude-opus-4-7" | null,      // model id when known
+ *     tier: "reasoning" | "mid" | "fast" | null,
+ *     input_tokens: 12345,
+ *     output_tokens: 678,
+ *     cache_read_tokens: 0,
+ *     cache_write_tokens: 0,
+ *     cost_usd: 0.123,                      // computed if model+tokens known, else null
+ *     phase: "07" | null,
+ *     session: "abc123" | null
+ *   }
+ *
+ * The appender is deliberately tolerant: if fields are missing the record
+ * is still written; aggregation skips null fields gracefully. Non-blocking
+ * — failure to write never breaks the caller (cost is observability, not
+ * critical path).
+ *
+ * Aggregation produces:
+ *   - by agent, by command, by tier, by day
+ *   - totals: input/output/cache tokens, cost
+ *   - hit rate: cache_read / (cache_read + input - cache_write) if any cache activity
+ *
+ * Rate table is approximate — real pricing comes from the provider's API.
+ * Rates are US dollars per million tokens, indicative as of 2026-04. Users
+ * can override with `.planning/config.json` → `cost.rates`.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { output, error, safeReadFile, loadConfig } = require('./core.cjs');
+const { PLANNING_DIR } = require('./constants.cjs');
+const { planningPath } = require('./utils.cjs');
+
+const METRICS_DIR = 'metrics';
+const TOKENS_FILE = 'tokens.jsonl';
+
+/**
+ * Default rate table ($ per million tokens).
+ * Override per-model in config.json → cost.rates.
+ */
+const DEFAULT_RATES = {
+  // Anthropic
+  'claude-opus-4-7':    { input: 15.0, output: 75.0, cache_read: 1.5,  cache_write: 18.75 },
+  'claude-opus-4-6':    { input: 15.0, output: 75.0, cache_read: 1.5,  cache_write: 18.75 },
+  'claude-sonnet-4-6':  { input: 3.0,  output: 15.0, cache_read: 0.3,  cache_write: 3.75 },
+  'claude-haiku-4-5':   { input: 1.0,  output: 5.0,  cache_read: 0.1,  cache_write: 1.25 },
+
+  // Google Gemini — published rates (per million tokens, approximate; users can override via config.json → cost.rates).
+  // 2.5 tier uses the <=200K-context tier; long-context calls may be billed at ~2x. Cache rates are Google's context-cache pricing (~25% of input rate).
+  'gemini-2.5-pro':         { input: 1.25, output: 10.0, cache_read: 0.3125, cache_write: 1.25 },
+  'gemini-2.5-flash':       { input: 0.30, output: 2.50, cache_read: 0.075,  cache_write: 0.30 },
+  'gemini-2.5-flash-lite':  { input: 0.10, output: 0.40, cache_read: 0.025,  cache_write: 0.10 },
+  'gemini-1.5-pro':         { input: 1.25, output: 5.00, cache_read: 0.3125, cache_write: 1.25 },
+
+  // Tier fallbacks when model id is unknown
+  'reasoning': { input: 15.0, output: 75.0, cache_read: 1.5,  cache_write: 18.75 },
+  'mid':       { input: 3.0,  output: 15.0, cache_read: 0.3,  cache_write: 3.75 },
+  'fast':      { input: 1.0,  output: 5.0,  cache_read: 0.1,  cache_write: 1.25 },
+};
+
+function metricsDir(cwd) {
+  return path.join(planningPath(cwd), METRICS_DIR);
+}
+
+function tokensFile(cwd) {
+  return path.join(metricsDir(cwd), TOKENS_FILE);
+}
+
+function resolveRate(model, tier, configRates) {
+  if (configRates) {
+    if (model && configRates[model]) return configRates[model];
+    if (tier && configRates[tier]) return configRates[tier];
+  }
+  if (model && DEFAULT_RATES[model]) return DEFAULT_RATES[model];
+  if (tier && DEFAULT_RATES[tier]) return DEFAULT_RATES[tier];
+  return null;
+}
+
+/**
+ * Compute cost in USD for a single record given known rates.
+ * Returns null when rate is unknown.
+ * @param {Object} rec - Cost record
+ * @param {Object} [configRates] - Optional rate overrides
+ * @returns {number|null}
+ */
+function computeCost(rec, configRates) {
+  const rate = resolveRate(rec.model, rec.tier, configRates);
+  if (!rate) return null;
+  const input = rec.input_tokens || 0;
+  const output = rec.output_tokens || 0;
+  const cacheRead = rec.cache_read_tokens || 0;
+  const cacheWrite = rec.cache_write_tokens || 0;
+  // Non-cache-hit input tokens = input - cache_read (cache_read already in input on some providers,
+  // separate on others; we treat cache_read as a reduction of effective new input).
+  const newInput = Math.max(0, input - cacheRead);
+  const usd = (newInput * rate.input + output * rate.output
+    + cacheRead * rate.cache_read + cacheWrite * rate.cache_write) / 1_000_000;
+  return Math.round(usd * 10000) / 10000;
+}
+
+/**
+ * Append a cost record. Non-blocking — errors are swallowed so instrumentation
+ * never breaks the caller.
+ * @param {string} cwd - Project root
+ * @param {Object} rec - Partial record; missing fields default to null/0.
+ * @returns {{appended: boolean, file?: string, error?: string}}
+ */
+function appendRecord(cwd, rec) {
+  const normalized = {
+    ts: rec.ts || new Date().toISOString(),
+    agent: rec.agent || null,
+    command: rec.command || null,
+    model: rec.model || null,
+    tier: rec.tier || null,
+    input_tokens: Number(rec.input_tokens) || 0,
+    output_tokens: Number(rec.output_tokens) || 0,
+    cache_read_tokens: Number(rec.cache_read_tokens) || 0,
+    cache_write_tokens: Number(rec.cache_write_tokens) || 0,
+    phase: rec.phase || null,
+    session: rec.session || null,
+  };
+  // Allow caller-supplied cost override; otherwise compute.
+  normalized.cost_usd = typeof rec.cost_usd === 'number'
+    ? rec.cost_usd
+    : computeCost(normalized);
+
+  try {
+    fs.mkdirSync(metricsDir(cwd), { recursive: true });
+    fs.appendFileSync(tokensFile(cwd), JSON.stringify(normalized) + '\n', 'utf-8');
+    return { appended: true, file: tokensFile(cwd) };
+  } catch (e) {
+    return { appended: false, error: e.message };
+  }
+}
+
+/**
+ * Read all cost records from the log.
+ * @param {string} cwd
+ * @returns {Array<Object>}
+ */
+function readRecords(cwd) {
+  const raw = safeReadFile(tokensFile(cwd));
+  if (!raw) return [];
+  const records = [];
+  for (const line of raw.split('\n')) {
+    if (!line.trim()) continue;
+    try {
+      records.push(JSON.parse(line));
+    } catch { /* skip malformed line */ }
+  }
+  return records;
+}
+
+/**
+ * Aggregate records into totals + breakdowns.
+ * @param {string} cwd
+ * @param {Object} [opts] - {since, until, group_by}
+ * @returns {Object} Aggregation
+ */
+function aggregate(cwd, opts) {
+  const records = readRecords(cwd);
+  const since = opts?.since ? new Date(opts.since).getTime() : null;
+  const until = opts?.until ? new Date(opts.until).getTime() : null;
+  const config = loadConfig(cwd);
+  const configRates = config?.cost?.rates;
+
+  const filtered = records.filter(r => {
+    if (!r.ts) return true;
+    const t = new Date(r.ts).getTime();
+    if (since !== null && t < since) return false;
+    if (until !== null && t > until) return false;
+    return true;
+  });
+
+  const totals = {
+    calls: filtered.length,
+    input_tokens: 0,
+    output_tokens: 0,
+    cache_read_tokens: 0,
+    cache_write_tokens: 0,
+    cost_usd: 0,
+    cost_unknown: 0,
+  };
+
+  const byAgent = {};
+  const byCommand = {};
+  const byTier = {};
+  const byDay = {};
+
+  function bump(map, key, rec) {
+    if (!key) return;
+    if (!map[key]) map[key] = { calls: 0, input: 0, output: 0, cache_read: 0, cache_write: 0, cost: 0 };
+    map[key].calls += 1;
+    map[key].input += rec.input_tokens || 0;
+    map[key].output += rec.output_tokens || 0;
+    map[key].cache_read += rec.cache_read_tokens || 0;
+    map[key].cache_write += rec.cache_write_tokens || 0;
+    const cost = typeof rec.cost_usd === 'number' ? rec.cost_usd : computeCost(rec, configRates);
+    if (typeof cost === 'number') map[key].cost += cost;
+  }
+
+  for (const r of filtered) {
+    totals.input_tokens += r.input_tokens || 0;
+    totals.output_tokens += r.output_tokens || 0;
+    totals.cache_read_tokens += r.cache_read_tokens || 0;
+    totals.cache_write_tokens += r.cache_write_tokens || 0;
+    const cost = typeof r.cost_usd === 'number' ? r.cost_usd : computeCost(r, configRates);
+    if (typeof cost === 'number') totals.cost_usd += cost;
+    else totals.cost_unknown += 1;
+
+    bump(byAgent, r.agent, r);
+    bump(byCommand, r.command, r);
+    bump(byTier, r.tier, r);
+    const day = r.ts ? r.ts.slice(0, 10) : null;
+    bump(byDay, day, r);
+  }
+
+  totals.cost_usd = Math.round(totals.cost_usd * 10000) / 10000;
+
+  // Cache hit rate: cache_read / (cache_read + new input tokens billed at full rate)
+  const billedInput = Math.max(0, totals.input_tokens - totals.cache_read_tokens);
+  const hitDenom = totals.cache_read_tokens + billedInput;
+  const cacheHitRatePct = hitDenom > 0
+    ? Math.round((totals.cache_read_tokens / hitDenom) * 1000) / 10
+    : null;
+
+  return {
+    totals,
+    cache_hit_rate_pct: cacheHitRatePct,
+    by_agent: byAgent,
+    by_command: byCommand,
+    by_tier: byTier,
+    by_day: byDay,
+    window: {
+      since: opts?.since || null,
+      until: opts?.until || null,
+    },
+  };
+}
+
+/**
+ * Render aggregation as a human-readable table.
+ * @param {Object} agg - from aggregate()
+ * @returns {string}
+ */
+function renderTable(agg) {
+  const lines = [];
+  lines.push('=== PAN Wizard Cost Dashboard ===');
+  const window = agg.window.since || agg.window.until
+    ? `  Window: ${agg.window.since || '(any)'} → ${agg.window.until || 'now'}`
+    : '  Window: all time';
+  lines.push(window);
+  lines.push('');
+  lines.push('Totals');
+  lines.push(`  Calls              : ${agg.totals.calls}`);
+  lines.push(`  Input tokens       : ${agg.totals.input_tokens.toLocaleString()}`);
+  lines.push(`  Output tokens      : ${agg.totals.output_tokens.toLocaleString()}`);
+  lines.push(`  Cache read         : ${agg.totals.cache_read_tokens.toLocaleString()}`);
+  lines.push(`  Cache write        : ${agg.totals.cache_write_tokens.toLocaleString()}`);
+  lines.push(`  Estimated cost     : $${agg.totals.cost_usd.toFixed(4)}${agg.totals.cost_unknown > 0 ? ` (+${agg.totals.cost_unknown} unknown)` : ''}`);
+  lines.push(`  Cache hit rate     : ${agg.cache_hit_rate_pct == null ? 'n/a' : `${agg.cache_hit_rate_pct}%`}`);
+
+  function section(title, map) {
+    const keys = Object.keys(map).sort((a, b) => (map[b].cost || 0) - (map[a].cost || 0));
+    if (keys.length === 0) return;
+    lines.push('');
+    lines.push(title);
+    lines.push('  ' + 'name'.padEnd(28) + 'calls'.padStart(7) + 'input'.padStart(11) + 'output'.padStart(9) + '  cost');
+    for (const k of keys) {
+      const row = map[k];
+      lines.push('  ' + k.slice(0, 28).padEnd(28)
+        + String(row.calls).padStart(7)
+        + row.input.toLocaleString().padStart(11)
+        + row.output.toLocaleString().padStart(9)
+        + '  $' + row.cost.toFixed(4));
+    }
+  }
+  section('By agent', agg.by_agent);
+  section('By command', agg.by_command);
+  section('By tier', agg.by_tier);
+  section('By day', agg.by_day);
+
+  return lines.join('\n');
+}
+
+/**
+ * Render aggregation as an ASCII bar chart of cost per day.
+ * @param {Object} agg
+ * @returns {string}
+ */
+function renderChart(agg) {
+  const days = Object.keys(agg.by_day).sort();
+  if (days.length === 0) return 'No cost data in window.';
+  const max = Math.max(...days.map(d => agg.by_day[d].cost || 0), 0.0001);
+  const width = 30;
+  const lines = ['=== Cost per day ==='];
+  for (const day of days) {
+    const cost = agg.by_day[day].cost || 0;
+    const len = Math.round((cost / max) * width);
+    const bar = '█'.repeat(len) + '░'.repeat(width - len);
+    lines.push(`  ${day}  ${bar}  $${cost.toFixed(4)}`);
+  }
+  lines.push('');
+  lines.push(`  Total window cost: $${agg.totals.cost_usd.toFixed(4)}`);
+  return lines.join('\n');
+}
+
+// ─── CLI wrappers ───────────────────────────────────────────────────────────
+
+function cmdCostReport(cwd, opts, raw) {
+  const format = opts?.format || 'json';
+  const agg = aggregate(cwd, opts);
+  if (format === 'table') {
+    output(agg, raw, renderTable(agg));
+  } else if (format === 'chart') {
+    output(agg, raw, renderChart(agg));
+  } else {
+    output(agg, raw);
+  }
+}
+
+function cmdCostAppend(cwd, rec, raw) {
+  const result = appendRecord(cwd, rec);
+  output(result, raw);
+}
+
+function cmdCostClear(cwd, raw) {
+  try {
+    fs.unlinkSync(tokensFile(cwd));
+    output({ cleared: true, file: tokensFile(cwd) }, raw);
+  } catch (e) {
+    output({ cleared: false, error: e.message }, raw);
+  }
+}
+
+module.exports = {
+  computeCost,
+  appendRecord,
+  readRecords,
+  aggregate,
+  renderTable,
+  renderChart,
+  resolveRate,
+  cmdCostReport,
+  cmdCostAppend,
+  cmdCostClear,
+  METRICS_DIR,
+  TOKENS_FILE,
+  DEFAULT_RATES,
+};