ultracost 0.2.1 → 0.3.1

package/bin/cli.js

@@ -1,15 +1,26 @@
 #!/usr/bin/env node
 import { existsSync, readFileSync } from 'node:fs';
-import { join } from 'node:path';
+import { join, basename } from 'node:path';
 import { loadPolicy } from '../src/policy.js';
-import { scan, fixFile, collectFiles, auditScripts } from '../src/guard.js';
-import { estimateFile } from '../src/estimate.js';
+import { scan, fixFile, collectFiles, auditScripts, stageList, CODES } from '../src/guard.js';
+import { estimateFile, scenarioTotals } from '../src/estimate.js';
 import { refreshPricing, writePricingToPolicy, DEFAULT_PRICING_URL } from '../src/pricing.js';
-import { install, uninstall, readSettings } from '../src/install.js';
+import { install, uninstall } from '../src/install.js';
+import { detectDelivery } from '../src/detect.js';
+import { readTranscripts, locateWorkflowRuns } from '../src/transcript.js';
+import { costFromUsage, modelPrice, totalTokens } from '../src/cost.js';
+import { tierOfModel, classifyPrompt, semanticFindings } from '../src/classify.js';
 import {
-  ROOT, CLAUDE_MD, HOOK_PATH, POLICY_PATH, SETTINGS, PROJECTS_DIR, tilde, MARKER_START
+  reconcileRun, calibrationFromRuns, writeCalibration, readCalibration, applyCalibration,
+  ledgerSync, spentToday
+} from '../src/loop.js';
+import {
+  ROOT, CLAUDE_MD, HOOK_PATH, POLICY_PATH, SETTINGS, PROJECTS_DIR, CALIBRATION_PATH, LEDGER_PATH, tilde
 } from '../src/paths.js';
-import { c, log, ok, warn, err, info } from '../src/log.js';
+import { log, ok, warn, err, info } from '../src/log.js';
+import { color, dim, bold, panel, columns, bar, sparkline, gradient, symbols, COLORS } from '../src/render.js';
+
+const fmt = (n) => (n >= 1e9 ? (n / 1e9).toFixed(2) + 'B' : n >= 1e6 ? (n / 1e6).toFixed(2) + 'M' : n >= 1e3 ? (n / 1e3).toFixed(1) + 'k' : String(n));
 
 const version = JSON.parse(readFileSync(join(ROOT, 'package.json'), 'utf8')).version;
 const argv = process.argv.slice(2);
@@ -17,7 +28,14 @@ const cmd = argv[0] || 'help';
 const has = (flag) => argv.includes(flag);
 const positional = argv.slice(1).filter((a) => !a.startsWith('-'));
 
+// When invoked through `npx ultracost ...`, the binary isn't on PATH afterwards, so
+// printed hints must keep the `npx` prefix (npx caches under .../_npx/).
+const NPX = (process.argv[1] || '').includes('/_npx/');
+const SELF = NPX ? 'npx ultracost' : 'ultracost';
+
 const money = (x) => '$' + Number(x).toFixed(4);
+const money6 = (x) => '$' + Number(x);
+const title = (t) => log(gradient(t, COLORS.violet, COLORS.cyan));
 
 try {
   await dispatch();
@@ -32,7 +50,14 @@ async function dispatch() {
     case 'check': case 'guard': cmdCheck(); break;
     case 'audit': cmdAudit(); break;
     case 'estimate': cmdEstimate(); break;
+    case 'explain': cmdExplain(); break;
+    case 'simulate': cmdSimulate(); break;
+    case 'diff': cmdDiff(); break;
     case 'pricing': await cmdPricing(); break;
+    case 'usage': cmdUsage(); break;
+    case 'reconcile': cmdReconcile(); break;
+    case 'calibrate': cmdCalibrate(); break;
+    case 'ledger': case 'savings': cmdLedger(); break;
     case 'status': cmdStatus(); break;
     case 'doctor': cmdDoctor(); break;
     case 'uninstall': cmdUninstall(); break;
@@ -46,47 +71,78 @@ async function dispatch() {
 }
 
 function cmdHelp() {
-  log(`
-${c.bold('ultracost')} ${c.dim('v' + version)} — per-stage model routing for Claude Code workflows
-
-${c.bold('Usage')}
-  ultracost init                 Install routing rules, hook, and default policy
-  ultracost check [path]         Scan workflow scripts for unpinned agent() stages
-  ultracost audit [dir]          Report pin stats across your real workflow scripts
-  ultracost estimate <script>    Estimate agents, model mix, and cost vs all-Opus baseline
-  ultracost pricing [refresh]    Show pricing, or refresh it from Anthropic's official page
-  ultracost status               Show active policy and install state
-  ultracost doctor               Diagnose the installation
-  ultracost uninstall            Remove everything ultracost installed
-
-${c.bold('check flags')}
-  --json                        Machine-readable output
-  --fix                         Insert the default model on unpinned stages
-  --quiet                       Only print problems
-
-${c.bold('estimate / audit flags')}
-  --json                        Machine-readable output
-  ${c.dim('audit default dir:')} ${tilde(PROJECTS_DIR)}/**/workflows/scripts/*.js
-
-${c.bold('pricing flags')}
-  refresh                       Fetch official prices and update the installed policy
-  --url <url>                   Override the pricing page URL
-
-${c.bold('Policy')}
-  Edit ${tilde(POLICY_PATH)} to change tiers/rules/effort/pricing, then re-run ${c.cyan('ultracost init')}.
-`);
+  log('');
+  title('  ultracost');
+  log('  ' + dim('v' + version + ' — per-stage model routing for Claude Code workflows'));
+  log('');
+  log(bold('  Routing & guard'));
+  log(columns([
+    ['init', 'Install routing rules, hook, and default policy'],
+    ['check [path]', 'Flag agent() stages that would inherit the session model'],
+    ['audit [dir]', 'Pin stats across your real workflow scripts'],
+    ['explain <script>', 'Per-stage rationale: tier, effort, tokens, cost, warnings']
+  ], { indent: 2, gap: 3 }));
+  log('');
+  log(bold('  Cost'));
+  log(columns([
+    ['estimate <script>', 'Agents, model mix, and cost vs an all-opus baseline'],
+    ['simulate <script>', 'Cost under alternative policies, side by side'],
+    ['diff <a> <b>', 'Cost delta between two workflow versions (--ci for PRs)'],
+    ['usage [dir]', 'Real token cost from local transcripts (main vs subagents)'],
+    ['reconcile [--last]', 'Estimate vs actual for a real workflow run'],
+    ['ledger', 'Cumulative savings vs all-opus across recorded runs'],
+    ['calibrate', 'Tune the estimator from your real token usage'],
+    ['pricing [refresh]', "Show pricing, or refresh from Anthropic's official page"]
+  ], { indent: 2, gap: 3 }));
+  log('');
+  log(bold('  State'));
+  log(columns([
+    ['status', 'Active policy + how ultracost is delivered (plugin/cli)'],
+    ['doctor', 'Diagnose the installation'],
+    ['uninstall', 'Remove everything the CLI installed']
+  ], { indent: 2, gap: 3 }));
+  log('');
+  info(`  policy: ${tilde(POLICY_PATH)}   ·   flags: --json --fix --quiet`);
+  log('');
 }
 
 function cmdInit() {
+  const d = detectDelivery();
+  if (d.verdict === 'plugin' && !has('--force')) {
+    log(panel([
+      `${color.green('●')} ultracost is already delivered by the plugin ${dim('(enabled + hooks active' + (d.plugin.version ? ', v' + d.plugin.version : '') + ')')}`,
+      '',
+      dim('Running init would write duplicate routing rules into ~/.claude that conflict'),
+      dim('with plugin delivery. Use the plugin as-is, or:'),
+      `  ${color.cyan(SELF + ' init --force')}   ${dim('install the CLI path too (advanced)')}`
+    ], { title: 'init skipped', hex: COLORS.amber }));
+    return;
+  }
+
   const { policy, source } = loadPolicy();
   const r = install(policy, { force: has('--force') });
-  log(`${c.bold('ultracost init')}\n`);
-  ok(`policy: ${r.policy} (${tilde(POLICY_PATH)})`);
-  ok(`rules: ${r.rules} (${tilde(CLAUDE_MD)})`);
-  ok(`hook: ${r.hook} (${tilde(HOOK_PATH)})`);
-  if (r.register === 'invalid') warn(`settings.json is invalid JSON — register the hook manually`);
-  else ok(`hook ${r.register} in ${tilde(SETTINGS)}`);
-  info(`\nactive policy from ${tilde(source)} — new sessions pick this up immediately.`);
+  log('');
+  title('  ultracost init');
+  log('');
+  ok(`policy: ${r.policy} ${dim('(' + tilde(POLICY_PATH) + ')')}`);
+  ok(`rules: ${r.rules} ${dim('(' + tilde(CLAUDE_MD) + ')')}`);
+  ok(`hook: ${r.hook} ${dim('(' + tilde(HOOK_PATH) + ')')}`);
+  if (r.register === 'invalid') warn('settings.json is invalid JSON — register the hook manually');
+  else ok(`hook ${r.register} ${dim('in ' + tilde(SETTINGS))}`);
+  if (d.verdict === 'both' || d.plugin.enabled) {
+    log('');
+    warn('the plugin is also active — you now have dual delivery; rules may be injected twice.');
+    info(`remove one: /plugin uninstall ultracost@ultracost  (or)  ${SELF} uninstall`);
+  }
+  log('');
+  info(`active policy from ${tilde(source)} — new sessions pick this up immediately.`);
+  log('');
+}
+
+function severityGlyph(sev) {
+  if (sev === 'error') return color.red(symbols.err);
+  if (sev === 'warn') return color.amber(symbols.warn);
+  return color.green(symbols.ok);
 }
 
 function cmdCheck() {
@@ -109,21 +165,39 @@ function cmdCheck() {
     process.exit(errors.length ? 1 : 0);
   }
 
+  log('');
   if (!findings.length) {
-    ok(`${files.length} file(s) scanned — every agent() stage pins a model.`);
+    log(panel([`${color.green(symbols.ok)} every agent() stage pins a model`], { title: `check · ${files.length} file(s)`, hex: COLORS.green }));
+    log('');
     return;
   }
+
+  // group findings by file
+  const byFile = new Map();
   for (const f of findings) {
-    const tag = f.severity === 'error' ? c.red(f.code) : c.yellow(f.code);
-    log(`${c.dim(tilde(f.file) + ':' + f.line + ':' + f.column)}  ${tag}  ${f.message}`);
-    if (!has('--quiet')) log(`    ${c.dim(f.snippet)}`);
+    if (!byFile.has(f.file)) byFile.set(f.file, []);
+    byFile.get(f.file).push(f);
   }
-  log('');
-  log(`${errors.length} error(s), ${warns.length} warning(s) in ${files.length} file(s).`);
+  for (const [file, fs] of byFile) {
+    const e = fs.filter((x) => x.severity === 'error').length;
+    const w = fs.filter((x) => x.severity === 'warn').length;
+    const head = `${tilde(file)}  ${e ? color.red(e + ' error' + (e > 1 ? 's' : '')) : ''}${e && w ? dim(' · ') : ''}${w ? color.amber(w + ' warning' + (w > 1 ? 's' : '')) : ''}`;
+    log('  ' + bold(head));
+    for (const f of fs) {
+      const tag = f.severity === 'error' ? color.red(f.code) : color.amber(f.code);
+      log(`    ${severityGlyph(f.severity)} ${dim(f.line + ':' + f.column)}  ${tag}  ${f.message}`);
+      if (!has('--quiet')) log(`      ${dim(f.snippet)}`);
+    }
+    log('');
+  }
+  const summary = `${errors.length ? color.red(errors.length + ' error(s)') : color.green('0 errors')}  ·  ${warns.length ? color.amber(warns.length + ' warning(s)') : dim('0 warnings')}  ${dim('in ' + files.length + ' file(s)')}`;
+  log('  ' + summary);
   if (errors.length) {
-    info(`Fix with: ultracost check ${positional[0] || '.'} --fix`);
+    info(`  fix the unambiguous ones: ${SELF} check ${positional[0] || '.'} --fix`);
+    log('');
     process.exit(1);
   }
+  log('');
 }
 
 function cmdAudit() {
@@ -136,49 +210,324 @@ function cmdAudit() {
     return;
   }
 
-  log(`${c.bold('ultracost audit')}\n`);
+  log('');
+  title('  ultracost audit');
+  log('');
   if (!files.length) {
     warn(`no workflow scripts found under ${tilde(base)}`);
     info(`looked for ${tilde(base)}/**/workflows/scripts/*.js`);
     return;
   }
-  info(`scanned ${totals.scripts} script(s) under ${tilde(base)}\n`);
-  const pct = (totals.unpinnedRatio * 100).toFixed(1);
-  log(`  agent() stages   ${totals.stages}`);
-  log(`  pinned           ${c.green(totals.pinned)}`);
-  log(`  ${c.red('unpinned')}         ${c.red(totals.unpinned)}   ${c.dim('(UC001/UC002 — inherit the session model)')}`);
-  log(`  banned           ${totals.banned}   ${c.dim('(UC003)')}`);
-  log(`  inherit          ${totals.inherit}   ${c.dim('(UC004)')}`);
-  log(`  dynamic          ${totals.dynamic}   ${c.dim('(UC005 — options is a variable)')}`);
-  log('');
-  log(`  ${c.bold('unpinned ratio')}   ${pct}%`);
+  info(`  scanned ${totals.scripts} script(s) under ${tilde(base)}`);
+  log('');
+  const pinnedPct = totals.stages ? (totals.pinned / totals.stages) * 100 : 0;
+  const unpinnedPct = totals.unpinnedRatio * 100;
+  log(columns([
+    ['agent() stages', String(totals.stages)],
+    ['pinned', color.green(String(totals.pinned))],
+    ['unpinned', color.red(String(totals.unpinned)), dim('UC001/UC002 — inherit the session model')],
+    ['banned', String(totals.banned), dim('UC003')],
+    ['inherit', String(totals.inherit), dim('UC004')],
+    ['dynamic', String(totals.dynamic), dim('UC005')],
+    ['wrong-tier', String(totals.wrongTier ?? 0), dim('UC006/UC008')],
+    ['over-effort', String(totals.overEffort ?? 0), dim('UC007')]
+  ], { indent: 2, gap: 2, align: ['left', 'right', 'left'] }));
+  log('');
+  log('  ' + bold('pinned   ') + bar(totals.pinned, totals.stages || 1, 30, COLORS.green) + `  ${pinnedPct.toFixed(1)}%`);
+  log('  ' + bold('unpinned ') + bar(totals.unpinned, totals.stages || 1, 30, COLORS.red) + `  ${unpinnedPct.toFixed(1)}%`);
+  log('');
 }
 
 function cmdEstimate() {
   const target = positional[0];
-  if (!target) { err('usage: ultracost estimate <workflow-script.js> [--json]'); process.exit(1); }
+  if (!target) { err(`usage: ${SELF} estimate <workflow-script.js> [--json]`); process.exit(1); }
   if (!existsSync(target)) { err(`not found: ${target}`); process.exit(1); }
   const { policy } = loadPolicy();
-  const est = estimateFile(target, policy);
+  const cal = readCalibration();
+  const est = estimateFile(target, applyCalibration(policy, cal));
 
   if (has('--json')) {
-    log(JSON.stringify({ target, ...est }, null, 2));
+    log(JSON.stringify({ target, calibrated: !!cal, ...est }, null, 2));
     return;
   }
 
   const a = est.agents;
-  const fan = a.fanoutGroups ? ` + ${a.fanoutGroups} fan-out group(s) x ~${a.assumedPerFanout} = ~${a.assumedTotal}` : '';
-  const mix = Object.entries(est.modelMix).map(([k, v]) => `${v}x ${k}`).join(', ') || 'none';
-  log(`${c.bold('ultracost estimate')}  ${c.dim(tilde(target))}\n`);
-  log(`  agents      ${a.known} fixed${fan}`);
-  log(`  model mix   ${mix}`);
-  log('');
-  log(`  baseline (all ${est.assumptions.sessionModel})   ${money(est.cost.baseline)}`);
-  log(`  tiered (ultracost)        ${money(est.cost.tiered)}`);
-  log(`  ${c.green('savings')}                   ${c.green(money(est.cost.savings))}  ${c.green('(' + est.cost.savingsPct + '%)')}`);
-  log('');
-  info(`estimate; pricing as of ${est.assumptions.pricingAsOf || 'n/a'}; fan-out assumes ~${a.assumedPerFanout} items/group; unpinned stages inherit ${est.assumptions.sessionModel} (no saving).`);
-  if (est.cost.savingsPct === 0 && est.stages.length) info('tip: pin cheaper tiers (sonnet) on mechanical stages to cut cost.');
+  const fan = a.fanoutGroups ? `${a.known} fixed + ${a.fanoutGroups} fan-out x ~${a.assumedPerFanout} = ~${a.assumedTotal}` : `${a.known}`;
+  const mix = Object.entries(est.modelMix).map(([k, v]) => color[mixKey(k)](`${v}x ${k}`)).join('  ') || 'none';
+
+  log('');
+  title('  ultracost estimate');
+  log('  ' + dim(tilde(target)));
+  log('');
+  log(columns([
+    ['agents', fan],
+    ['model mix', mix]
+  ], { indent: 2, gap: 3 }));
+  log('');
+  const pct = est.cost.savingsPct;
+  log(columns([
+    [dim('baseline'), dim('all ' + est.assumptions.sessionModel), money(est.cost.baseline)],
+    ['tiered', dim('ultracost'), money(est.cost.tiered)],
+    [color.green('savings'), color.green(pct + '%'), color.green(money(est.cost.savings))]
+  ], { indent: 2, gap: 3, align: ['left', 'left', 'right'] }));
+  log('');
+  log('  ' + bar(est.cost.savings, est.cost.baseline || 1, 30, COLORS.green) + `  ${pct}% saved`);
+  log('');
+  info(`  estimate; pricing as of ${est.assumptions.pricingAsOf || 'n/a'}; fan-out assumes ~${a.assumedPerFanout} items/group; unpinned stages inherit ${est.assumptions.sessionModel}.`);
+  if (cal) info(`  token prior calibrated from your real runs (${SELF} calibrate; ${cal.samples} samples).`);
+  if (pct === 0 && est.stages.length) info('  tip: pin cheaper tiers (sonnet) on mechanical stages to cut cost.');
+  log('');
+}
+
+function cmdUsage() {
+  const { policy } = loadPolicy();
+  const records = readTranscripts({ root: positional[0] });
+  if (has('--json')) {
+    const rows = records.map((r) => ({ kind: r.kind, model: r.model, project: r.project, cost: costFromUsage(r.usage, modelPrice(r.model, policy), policy), tokens: totalTokens(r.usage) }));
+    log(JSON.stringify({ records: rows.length, rows }, null, 2));
+    return;
+  }
+  log('');
+  title('  ultracost usage');
+  log('  ' + dim('real token cost from local transcripts'));
+  log('');
+  if (!records.length) { warn('no transcripts found under your Claude Code projects dir'); log(''); return; }
+
+  const byKind = {};
+  const byModel = {};
+  let total = 0;
+  let tokens = 0;
+  for (const r of records) {
+    const cost = costFromUsage(r.usage, modelPrice(r.model, policy), policy);
+    const tk = totalTokens(r.usage);
+    total += cost; tokens += tk;
+    byKind[r.kind] = (byKind[r.kind] || 0) + cost;
+    const mk = tierOfModel(r.model);
+    byModel[mk] = (byModel[mk] || 0) + cost;
+  }
+  log(panel([
+    `${bold(money(total))}  ${dim('across ' + records.length + ' assistant turns · ' + fmt(tokens) + ' tokens')}`
+  ], { title: 'total cost', hex: COLORS.violet }));
+  log('');
+  const kindRows = ['main', 'subagent', 'workflow-stage'].filter((k) => byKind[k]).map((k) => [k, money(byKind[k])]);
+  log(columns(kindRows, { indent: 2, gap: 3, align: ['left', 'right'] }));
+  log('');
+  const maxModel = Math.max(1, ...Object.values(byModel));
+  for (const [k, v] of Object.entries(byModel).sort((a, b) => b[1] - a[1])) {
+    log('  ' + color[mixKey(k)](pad9(k)) + ' ' + bar(v, maxModel, 26, COLORS[mixKey(k)]) + '  ' + money(v));
+  }
+  log('');
+}
+function pad9(s) { return (s + '         ').slice(0, 9); }
+
+function pickRun(runs) {
+  if (has('--last')) return runs[0];
+  if (positional[0]) return runs.find((r) => r.wfId.includes(positional[0])) || null;
+  return runs[0];
+}
+
+function cmdReconcile() {
+  const { policy } = loadPolicy();
+  const runs = locateWorkflowRuns();
+  if (!runs.length) { warn('no dynamic-workflow runs found in your transcripts yet'); return; }
+  const run = pickRun(runs);
+  if (!run) { err(`no workflow run matching "${positional[0]}"`); process.exit(1); }
+  const rec = reconcileRun(run, policy);
+
+  if (has('--json')) { log(JSON.stringify(rec, null, 2)); return; }
+
+  log('');
+  title('  ultracost reconcile');
+  log('  ' + dim(rec.wfId + ' · ' + (rec.ts ? rec.ts.slice(0, 10) : '') + ' · ' + rec.stages.length + ' stages'));
+  log('');
+  const rows = rec.stages.map((s, i) => [
+    dim('#' + (i + 1)),
+    color[mixKey(s.tier)](s.tier),
+    fmt(s.tokens),
+    money(s.actualCost),
+    dim(money(s.opusCost))
+  ]);
+  log(columns(rows, { indent: 2, gap: 3, align: ['right', 'left', 'right', 'right', 'right'], head: [dim('#'), 'tier', 'tokens', 'actual', 'all-opus'] }));
+  log('');
+  const t = rec.totals;
+  log(columns([
+    [dim('actual'), money(t.actual)],
+    [dim('all-opus baseline'), money(t.allOpus)],
+    [color.green('saved'), color.green(money(t.saved) + '  (' + t.savedPct + '%)')]
+  ], { indent: 2, gap: 3, align: ['left', 'right'] }));
+  log('  ' + bar(t.saved, t.allOpus || 1, 30, COLORS.green) + `  ${t.savedPct}% saved`);
+  log('');
+  info('  reconciled from real per-stage token usage (subagents/workflows/wf_*/agent-*.jsonl).');
+  log('');
+}
+
+function cmdCalibrate() {
+  const { policy } = loadPolicy();
+  const runs = locateWorkflowRuns();
+  const cal = calibrationFromRuns(runs, policy);
+  if (!cal) { warn('not enough real workflow-stage data to calibrate yet'); return; }
+  const path = writeCalibration(cal);
+
+  if (has('--json')) { log(JSON.stringify(cal, null, 2)); return; }
+  log('');
+  title('  ultracost calibrate');
+  log('');
+  const lines = [
+    `samples   ${cal.samples} stages from ${cal.runs} run(s) ${dim('(' + cal.droppedOutliers + ' outliers dropped)')}`,
+    `tokens/stage   ${fmt(cal.tokensPerStage.input)} in / ${fmt(cal.tokensPerStage.output)} out`
+  ];
+  for (const [k, v] of Object.entries(cal.perModel)) lines.push(`  ${color[mixKey(k)](k)}   ${fmt(v.input)} in / ${fmt(v.output)} out ${dim('(' + v.samples + ')')}`);
+  log(panel(lines, { title: 'calibrated token prior', hex: COLORS.cyan }));
+  log('');
+  ok(`written to ${tilde(path)} — ${SELF} estimate now uses your real token sizes.`);
+  log('');
+}
+
+function cmdLedger() {
+  const { policy } = loadPolicy();
+  const runs = locateWorkflowRuns();
+  const entries = ledgerSync(runs, policy);
+
+  if (has('--json')) { log(JSON.stringify({ entries }, null, 2)); return; }
+  log('');
+  title('  ultracost ledger');
+  log('  ' + dim('cumulative savings vs an all-opus baseline'));
+  log('');
+  if (!entries.length) { warn('no recorded workflow runs yet — run some ultracode workflows, then re-check'); log(''); return; }
+  const saved = entries.reduce((n, e) => n + (e.saved || 0), 0);
+  const actual = entries.reduce((n, e) => n + (e.actual || 0), 0);
+  const allOpus = entries.reduce((n, e) => n + (e.allOpus || 0), 0);
+  const pct = allOpus ? Math.round((1 - actual / allOpus) * 100) : 0;
+  log(panel([
+    `${color.green(bold(money(saved)))}  ${dim('saved across ' + entries.length + ' run(s)')}`,
+    `${dim('actual ' + money(actual) + '  ·  all-opus ' + money(allOpus) + '  ·  ' + pct + '% saved')}`,
+    `${dim('today: ' + money(spentToday(entries)))}`
+  ], { title: 'savings ledger', hex: COLORS.green }));
+  log('');
+  const spark = sparkline(entries.map((e) => e.saved), COLORS.green);
+  if (spark) log('  per-run saved  ' + spark);
+  log('  ' + dim(`ledger at ${tilde(LEDGER_PATH)}`));
+  log('');
+}
+
+function mixKey(k) {
+  return k === 'opus' ? 'violet' : k === 'sonnet' ? 'cyan' : k === 'haiku' ? 'red' : 'slate';
+}
+
+function cmdExplain() {
+  const target = positional[0];
+  if (!target || !existsSync(target)) { err(`usage: ${SELF} explain <workflow-script.js>`); process.exit(1); }
+  const { policy } = loadPolicy();
+  const pol = applyCalibration(policy);
+  const est = estimateFile(target, pol);
+  const stages = stageList(readFileSync(target, 'utf8'));
+
+  if (has('--json')) {
+    const out = est.stages.map((s, i) => {
+      const prompt = stages[i]?.prompt || null;
+      const cls = prompt ? classifyPrompt(prompt, policy) : null;
+      return { line: s.line, model: s.model, effort: s.effort, fanout: s.fanout, pinned: s.pinned, tieredCost: s.tieredCost, prompt, classified: cls };
+    });
+    log(JSON.stringify({ target, stages: out }, null, 2));
+    return;
+  }
+
+  log('');
+  title('  ultracost explain');
+  log('  ' + dim(tilde(target)) + (pol._calibrated ? dim('  · calibrated') : ''));
+  log('');
+  const rows = est.stages.map((s, i) => {
+    const prompt = stages[i]?.prompt;
+    const cls = prompt ? classifyPrompt(prompt, policy) : null;
+    const reads = cls && cls.tier ? `${cls.tier}${cls.confidence === 'high' ? '' : '?'}` : dim('—');
+    const flags = prompt
+      ? semanticFindings({ model: s.model, effort: s.effort, prompt }, policy, CODES).map((f) => f.code)
+      : [];
+    const tierName = tierOfModel(s.model);
+    return [
+      dim('#' + (i + 1)),
+      color[mixKey(tierName)](s.model) + (s.fanout ? dim(' xN') : ''),
+      s.effort || dim('—'),
+      reads,
+      money(s.tieredCost),
+      flags.length ? color.amber(flags.join(',')) : color.green('ok')
+    ];
+  });
+  log(columns(rows, {
+    indent: 2, gap: 3,
+    align: ['right', 'left', 'left', 'left', 'right', 'left'],
+    head: [dim('#'), 'model', 'effort', 'reads-like', 'est', 'check']
+  }));
+  log('');
+  log('  ' + dim(`${est.agents.assumedTotal} agents · tiered ${money(est.cost.tiered)} · ${est.cost.savingsPct}% under all-${est.assumptions.sessionModel}`));
+  info(`  "reads-like" is the tier the prompt looks like; a "?" means low confidence. Flags: UC006 wrong-tier, UC007 over-effort, UC008 alwaysOpus.`);
+  log('');
+}
+
+function cmdSimulate() {
+  const target = positional[0];
+  if (!target || !existsSync(target)) { err(`usage: ${SELF} simulate <workflow-script.js>`); process.exit(1); }
+  const { policy } = loadPolicy();
+  const s = scenarioTotals(readFileSync(target, 'utf8'), applyCalibration(policy));
+
+  if (has('--json')) { log(JSON.stringify({ target, ...s }, null, 2)); return; }
+
+  log('');
+  title('  ultracost simulate');
+  log('  ' + dim(tilde(target) + ' · ' + s.stages + ' stage(s)'));
+  log('');
+  const max = Math.max(s.allOpus, s.allSonnet, s.tiered, 1e-9);
+  const row = (label, val, hex, note) => log('  ' + bold(pad14(label)) + ' ' + bar(val, max, 24, hex) + '  ' + money(val) + (note ? '  ' + dim(note) : ''));
+  row('all-opus', s.allOpus, COLORS.violet, 'unguided ultracode default');
+  row('tiered (yours)', s.tiered, COLORS.green, `${s.allOpus ? Math.round((1 - s.tiered / s.allOpus) * 100) : 0}% under all-opus`);
+  row('all-sonnet', s.allSonnet, COLORS.cyan, 'aggressive cost-first');
+  log('');
+  info('  relative estimate; tiered is your current per-stage pins. Quality-first keeps reasoning on opus.');
+  log('');
+}
+function pad14(s) { return (s + '              ').slice(0, 14); }
+
+function cmdDiff() {
+  const [a, b] = positional;
+  if (!a || !b || !existsSync(a) || !existsSync(b)) { err(`usage: ${SELF} diff <old-script.js> <new-script.js> [--ci]`); process.exit(1); }
+  const { policy } = loadPolicy();
+  const pol = applyCalibration(policy);
+  const ea = estimateFile(a, pol);
+  const eb = estimateFile(b, pol);
+  const dCost = eb.cost.tiered - ea.cost.tiered;
+  const dAgents = eb.agents.assumedTotal - ea.agents.assumedTotal;
+  const pct = ea.cost.tiered ? Math.round((dCost / ea.cost.tiered) * 100) : 0;
+
+  if (has('--json')) {
+    log(JSON.stringify({ a, b, old: ea.cost, new: eb.cost, deltaTiered: dCost, deltaAgents: dAgents }, null, 2));
+    return;
+  }
+  if (has('--ci')) {
+    const sign = dCost >= 0 ? '+' : '−';
+    log('## ultracost cost diff');
+    log('');
+    log('| version | agents | tiered | vs all-opus |');
+    log('|---|---|---|---|');
+    log(`| \`${basename(a)}\` | ${ea.agents.assumedTotal} | ${money(ea.cost.tiered)} | ${ea.cost.savingsPct}% |`);
+    log(`| \`${basename(b)}\` | ${eb.agents.assumedTotal} | ${money(eb.cost.tiered)} | ${eb.cost.savingsPct}% |`);
+    log('');
+    log(`**Δ tiered cost: ${sign}${money(Math.abs(dCost))} (${pct >= 0 ? '+' : ''}${pct}%)** · Δ agents: ${dAgents >= 0 ? '+' : ''}${dAgents}`);
+    return;
+  }
+
+  log('');
+  title('  ultracost diff');
+  log('  ' + dim(`${basename(a)} → ${basename(b)}`));
+  log('');
+  log(columns([
+    [dim(basename(a)), `${ea.agents.assumedTotal} agents`, money(ea.cost.tiered)],
+    [dim(basename(b)), `${eb.agents.assumedTotal} agents`, money(eb.cost.tiered)]
+  ], { indent: 2, gap: 3, align: ['left', 'right', 'right'] }));
+  log('');
+  const up = dCost > 0;
+  const deltaStr = `${up ? '+' : ''}${money(dCost)}  (${pct >= 0 ? '+' : ''}${pct}%)  ·  ${dAgents >= 0 ? '+' : ''}${dAgents} agents`;
+  log('  ' + bold('Δ ') + (up ? color.red(deltaStr) : color.green(deltaStr)));
+  log('');
 }
 
 async function cmdPricing() {
@@ -197,68 +546,116 @@ async function cmdPricing() {
 }
 
 function showPricing(pr) {
-  log(`${c.bold('ultracost pricing')} ${c.dim('(USD per million tokens)')}`);
-  if (pr?._source) info(`source: ${pr._source}`);
-  if (pr?._asOf) info(`as of:  ${pr._asOf}`);
-  for (const k of ['opus', 'sonnet', 'haiku']) {
-    if (pr?.[k]) log(`  ${c.cyan(k)}: $${pr[k].input} in / $${pr[k].output} out`);
-  }
-  info('refresh from the official page: ultracost pricing refresh');
+  log('');
+  title('  ultracost pricing');
+  log('  ' + dim('USD per million tokens' + (pr?._asOf ? ' · as of ' + pr._asOf : '')));
+  log('');
+  const rows = ['opus', 'sonnet', 'haiku'].filter((k) => pr?.[k]).map((k) => [
+    color[mixKey(k)](k), money6(pr[k].input) + ' in', money6(pr[k].output) + ' out'
+  ]);
+  log(columns(rows, { indent: 2, gap: 3, align: ['left', 'right', 'right'] }));
+  log('');
+  if (pr?._source) info(`  source: ${pr._source}`);
+  info(`  refresh: ${SELF} pricing refresh`);
+  log('');
+}
+
+function deliveryHex(v) {
+  return v === 'none' ? COLORS.red : v === 'both' ? COLORS.amber : COLORS.green;
 }
 
 function cmdStatus() {
   const { policy, source } = loadPolicy();
-  log(`${c.bold('ultracost status')}\n`);
-  info(`policy source: ${tilde(source)}`);
-  log(`${c.bold('tiers')} (never: ${policy.neverUse.join(', ') || 'none'})`);
-  for (const [name, t] of Object.entries(policy.tiers)) {
-    const mark = name === policy.default ? c.green(' (default)') : '';
-    log(`  ${c.cyan(name)}: ${t.model}${t.effort ? ' @ ' + t.effort : ''}${mark}`);
+  const d = detectDelivery();
+  log('');
+  title('  ultracost status');
+  log('');
+
+  const dot = (on) => (on ? color.green('●') : dim('○'));
+  const dl = [];
+  const pluginActive = d.verdict === 'plugin' || d.verdict === 'both';
+  const cliActive = d.verdict === 'cli' || d.verdict === 'both';
+  dl.push(`${dot(pluginActive)} plugin   ${pluginActive ? color.green('active') : dim('not enabled')}` +
+    (pluginActive ? '  ' + dim('v' + (d.plugin.version || '?') + ' · SessionStart + PreToolUse hooks') : ''));
+  dl.push(`${dot(cliActive)} cli      ${cliActive ? color.green('active') : dim('not installed')}` +
+    (cliActive ? '  ' + dim('~/.claude/CLAUDE.md + SessionStart hook') : ''));
+  log(panel(dl, { title: 'delivery · ' + d.verdict, hex: deliveryHex(d.verdict) }));
+  log('');
+
+  const tierRows = Object.entries(policy.tiers).map(([name, t]) => [
+    color[mixKey(t.model)] ? color[mixKey(t.model)](name) : name,
+    `${t.model}${t.effort ? ' @ ' + t.effort : ''}`,
+    name === policy.default ? color.green('default') : ''
+  ]);
+  log(panel([
+    columns(tierRows, { gap: 3, align: ['left', 'left', 'left'] }),
+    dim('never: ' + (policy.neverUse.join(', ') || 'none'))
+  ].join('\n').split('\n'), { title: 'policy', hex: COLORS.violet }));
+  log('');
+
+  // Caveats that change behavior, surfaced loudly.
+  if (d.bypass) {
+    warn(`permission mode is ${bold(d.permissionMode || 'bypassPermissions')} — the gate's ask path auto-approves, so clean workflows won't pause.`);
+    info('unpinned/banned workflows are still hard-denied; turn off bypass (shift+tab) for the full pre-flight stop.');
   }
-  log(`\n${c.bold('install')}`);
-  state(existsSync(CLAUDE_MD) && readFileSync(CLAUDE_MD, 'utf8').includes(MARKER_START), `rules in ${tilde(CLAUDE_MD)}`);
-  state(existsSync(HOOK_PATH), `hook at ${tilde(HOOK_PATH)}`);
-  const settings = readSettings();
-  const registered = settings && settings.hooks?.SessionStart?.some((h) => h.hooks?.some((hh) => hh.command?.includes('ultracost')));
-  state(!!registered, `hook registered in settings.json`);
+  if (d.verdict === 'both') warn('dual delivery: plugin AND cli both active — rules may be injected twice. Remove one.');
+  if (d.verdict === 'none') warn(`ultracost is not active — install the plugin or run ${SELF} init.`);
+  if (d.gateEnv) info(`ULTRACOST_GATE=${d.gateEnv}`);
+  if (d.settingsInvalid) err('settings.json or settings.local.json is invalid JSON');
+  info(`policy source: ${tilde(source)}`);
+  log('');
 }
 
 function cmdDoctor() {
-  log(`${c.bold('ultracost doctor')}\n`);
+  const d = detectDelivery();
+  const lines = [];
   let issues = 0;
-  const need = (cond, msg) => { if (cond) ok(msg); else { warn(msg); issues++; } };
+  const add = (good, label, detail) => {
+    lines.push(`${good ? color.green(symbols.ok) : color.amber(symbols.warn)} ${label}${detail ? '  ' + dim(detail) : ''}`);
+    if (!good) issues++;
+  };
 
   try {
     const { policy } = loadPolicy();
-    ok(`policy is valid (${Object.keys(policy.tiers).length} tiers)`);
+    add(true, `policy valid ${dim('(' + Object.keys(policy.tiers).length + ' tiers)')}`);
   } catch (e) {
-    err(e.message); issues++;
+    add(false, 'policy invalid', e.message);
   }
-  need(existsSync(CLAUDE_MD) && readFileSync(CLAUDE_MD, 'utf8').includes(MARKER_START), `routing rules present in ${tilde(CLAUDE_MD)}`);
-  need(existsSync(HOOK_PATH), `re-inject hook installed`);
-
-  const settings = readSettings();
-  if (settings === undefined) { err(`${tilde(SETTINGS)} is invalid JSON`); issues++; }
-  else {
-    const registered = settings?.hooks?.SessionStart?.some((h) => h.hooks?.some((hh) => hh.command?.includes('ultracost')));
-    need(!!registered, `hook registered for SessionStart`);
-    if (settings?.permissions?.defaultMode && settings.permissions.defaultMode !== 'auto') {
-      info(`tip: permission mode is "${settings.permissions.defaultMode}" — workflow subagents may prompt`);
-    }
+
+  if (d.verdict === 'plugin' || d.verdict === 'both') {
+    add(d.plugin.hooks.sessionStart, 'plugin SessionStart policy injection');
+    add(d.plugin.hooks.preToolUse, 'plugin PreToolUse cost gate');
+  } else if (d.verdict === 'cli') {
+    add(d.cli.rules, 'routing rules in ~/.claude/CLAUDE.md');
+    add(d.cli.settingsHook, 'SessionStart hook registered');
+    add(d.cli.hook, 're-inject hook installed');
+  } else {
+    add(false, 'ultracost is not active', `install the plugin (/plugin install ultracost@ultracost) or run ${SELF} init`);
   }
 
+  if (d.verdict === 'both') { lines.push(`${color.amber(symbols.warn)} dual delivery — plugin AND cli both active; remove one to avoid double-injected rules`); issues++; }
+  if (d.settingsInvalid) { lines.push(`${color.red(symbols.err)} settings.json or settings.local.json is invalid JSON`); issues++; }
+  if (d.bypass) lines.push(dim(`note: ${d.permissionMode || 'bypass'} mode auto-approves the gate's ask path; unpinned workflows are still hard-denied`));
+  lines.push(dim('note: pin per stage via the agent() model param — subagent frontmatter "model:" is ignored on some Claude Code 2.1.x (claude-code#52681)'));
+
+  log('');
+  log(panel(lines, { title: issues ? `doctor · ${issues} issue(s)` : 'doctor · all clear', hex: issues ? COLORS.amber : COLORS.green }));
   log('');
-  if (issues === 0) log(c.green('All clear. Routing is configured.'));
-  else { log(c.red(`${issues} issue(s).`)); info('Run: ultracost init'); process.exit(1); }
+  if (issues) { info(`fix: ${SELF} init  (cli)  or  /plugin install ultracost@ultracost  (plugin)`); process.exit(1); }
 }
 
 function cmdUninstall() {
   const r = uninstall();
-  log(`${c.bold('ultracost uninstall')}\n`);
-  for (const [k, v] of Object.entries(r)) info(`${k}: ${v}`);
+  log('');
+  title('  ultracost uninstall');
+  log('');
+  for (const [k, v] of Object.entries(r)) info(`  ${k}: ${v}`);
   ok('done.');
-}
-
-function state(good, label) {
-  log(`  ${good ? c.green('on ') : c.red('off')} ${label}`);
+  const d = detectDelivery();
+  if (d.plugin.enabled) {
+    log('');
+    info('note: the plugin is still installed — remove it in Claude Code with:');
+    info('  /plugin uninstall ultracost@ultracost   then   /plugin marketplace remove ultracost');
+  }
+  log('');
 }