fm-bench 0.4.3 → 0.5.0

package/README.md

@@ -51,6 +51,8 @@ prompts 5 | runs 3 | concurrency 1,2 | stream on | measured 30 | failed 0 | skip
 ```sh
 fm-bench [run] [options]
 fm-bench models [options]
+fm-bench compare <before.json> <after.json> [options]
+fm-bench history [dir] [options]
 fm-bench legend [options]
 fm-bench doctor [options]
 ```
@@ -59,9 +61,13 @@ fm-bench doctor [options]
 
 `models` lists discovered models, availability, descriptions, and quota output.
 
+`compare` reads two saved JSON reports and prints a side-by-side regression table showing absolute and percent change for every latency, throughput, and reliability metric. Green/yellow/red coloring applies lower-is-better logic for latency and CV and higher-is-better for throughput. Use `--json` to get the diff as structured data.
+
+`history` scans a directory for fm-bench JSON report files and prints a chronological trend table. Pairs with `--output-dir` to build a persistent benchmark archive.
+
 `legend` explains every terminal table column, compact-card field, model-list column, and color rule. It does not run `fm`.
 
-`doctor` checks Node, macOS, `fm`, and model availability.
+`doctor` checks Node, macOS, `fm`, model availability, CPU, memory, thermal throttle state, and battery status.
 
 ## Benchmark Options
 
@@ -72,9 +78,15 @@ fm-bench --models system --runs 3 --profile throughput --warmup 1
 fm-bench --models system --profile interactive --sweep-concurrency 1,2,4
 fm-bench --profile client --sweep-concurrency 1,2 --request-rate 0.5 --ramp-up-ms 2000
 fm-bench --models system --runs 5 --slo-ttft-ms 750 --slo-e2e-ms 4000
+fm-bench --profile reasoning --runs 5 --retry 2
+fm-bench --profile coding --runs 3 --tag pre-update --output-dir reports/
 fm-bench --prompt "Reply with exactly: ok" --runs 5
 fm-bench --prompt-file prompts.json --format json --out reports/bench.json
 fm-bench --format csv --out reports/bench.csv
+fm-bench --histogram
+fm-bench --ci --slo-ttft-ms 750 --slo-e2e-ms 4000
+fm-bench compare reports/before.json reports/after.json
+fm-bench history reports/
 fm-bench legend
 fm-bench legend --json
 ```
@@ -89,11 +101,15 @@ Useful flags:
 - `--request-rate <rps>`: pace request starts at a target requests-per-second rate.
 - `--ramp-up-ms <n>`: gradually ramp request pacing over `n` milliseconds.
 - `--timeout-ms <n>`: timeout per `fm` call.
+- `--retry <n>`: retry failed `fm` calls up to `n` times with exponential backoff (500ms–4s). Useful for handling transient model busy errors.
 - `--slo-ttft-ms <n>`, `--slo-e2e-ms <n>`, `--slo-tpot-ms <n>`: count goodput against latency budgets.
-- `--profile quick|standard|interactive|throughput|client|stress`: built-in prompt suite.
+- `--ci`: exit with code 1 if any run fails or any SLO budget is violated. Disables color and progress. Designed for GitHub Actions and CI pipelines.
+- `--profile quick|standard|interactive|throughput|client|stress|reasoning|coding|creative`: built-in prompt suite.
 - `--prompt <text>`: custom prompt, repeatable.
 - `--prompt-file <file>`: JSON, JSONL, or blank-line separated text prompts.
 - `--instructions <text>`: passed to `fm respond`.
+- `--tag <name>`: tag this run (repeatable). Tags appear in the JSON payload and report header.
+- `--note <text>`: freeform note attached to the JSON payload and report header.
 - `--available-only`: hide unavailable discovered models.
 - `--capture-output`: include raw model output in JSON reports.
 - `--json`, `--csv`, `--format table|json|csv`: choose output format.
@@ -102,7 +118,60 @@ Useful flags:
 - `--progress`, `--no-progress`: force or disable the live progress status line on stderr.
 - `--compact`: force the narrow terminal layout.
 - `--width <n>`: render as if the terminal has `n` columns.
+- `--histogram`: print an ASCII latency distribution bar chart after the report.
 - `--out <file>`: save a report.
+- `--output-dir <dir>`: auto-save a timestamped JSON report to a directory on every run.
+
+## Prompt Profiles
+
+Nine built-in profiles cover a range of workloads:
+
+| Profile | Prompts | Focus |
+|---------|---------|-------|
+| `quick` | 1 | Single-prompt smoke test |
+| `standard` | 3 | Short chat, structured JSON, medium generation |
+| `interactive` | 3 | Short conversational turns |
+| `throughput` | 3 | Longer generation and transformation tasks |
+| `client` | 5 | Broad real-world mix: chat, content, extraction, summarization, code review |
+| `stress` | 5 | Diverse stress mix with math and reasoning |
+| `reasoning` | 5 | Multi-step math, logic, causal chains, estimation, debugging |
+| `coding` | 5 | Code review, refactoring, algorithms, code explanation, system design |
+| `creative` | 5 | Product copy, error messages, analogies, commit messages, doc writing |
+
+Use `--profile reasoning` or `--profile coding` for richer signal when evaluating a model's capability alongside raw speed.
+
+## Compare Reports
+
+Save two runs to JSON and diff them:
+
+```sh
+fm-bench --runs 5 --json --out before.json
+# ... update your system, wait, or run again ...
+fm-bench --runs 5 --json --out after.json
+fm-bench compare before.json after.json
+```
+
+Output shows each model/concurrency row with before value, delta percentage (color-coded green/yellow/red), and after value for TTFT, E2E, TPOT, tokens/s, RPS, success rate, and CV.
+
+## Benchmark History
+
+Use `--output-dir` to build an archive, then view trends with `history`:
+
+```sh
+fm-bench --output-dir reports/ --runs 3
+fm-bench --output-dir reports/ --runs 3
+fm-bench history reports/
+```
+
+## CI Integration
+
+Use `--ci` to fail the pipeline when quality regresses:
+
+```sh
+fm-bench --ci --slo-ttft-ms 750 --slo-e2e-ms 4000 --runs 5
+```
+
+Exit code is 0 on pass, 1 on any failure or SLO violation. Prints `fm-bench ci: PASS` or `fm-bench ci: FAIL — <reasons>` to stderr.
 
 ## Prompt Files
 
@@ -149,7 +218,7 @@ Token counts come from `fm token-count --quiet`. If `fm` cannot count a response
 
 Measured runs stream by default so `fm-bench` can capture TTFT and streaming smoothness. Use `--no-stream` if you need buffered `fm respond` behavior; TTFT, TPOT, second-chunk, and chunk-gap fields that depend on streaming will be blank.
 
-Terminal output is responsive. Wide terminals show full scoreboard and detail tables, medium terminals show a tighter operating-point table, and narrow terminals switch to compact model cards. Use `--width` to preview a layout and `--ascii` for log systems that do not render Unicode borders well.
+Terminal output is responsive. Wide terminals show full scoreboard and detail tables, medium terminals show a tighter operating-point table, and narrow terminals switch to compact model cards. Long `NOTE`, `DESCRIPTION`, and model quota cells wrap so error context stays visible instead of being hidden behind ellipses. Use `--width` to preview a layout and `--ascii` for log systems that do not render Unicode borders well.
 
 ## Table Legend
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fm-bench",
-  "version": "0.4.3",
+  "version": "0.5.0",
   "description": "Dynamic benchmark CLI for Apple's fm command on macOS 27+.",
   "type": "module",
   "bin": {

package/src/bench.js

@@ -229,11 +229,18 @@ async function runScenario(context) {
 }
 
 async function runSingleBenchmark(fmBin, job, promptTokenCounts, options, benchmarkStartedAt) {
+  const maxAttempts = 1 + Math.max(0, options.retry ?? 0);
   const startOffsetMs = Number(process.hrtime.bigint() - benchmarkStartedAt) / 1e6;
-  const response = await respond(fmBin, job.model.name, job.prompt.prompt, {
-    ...options,
-    stream: options.stream
-  });
+  let response;
+  for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+    response = await respond(fmBin, job.model.name, job.prompt.prompt, {
+      ...options,
+      stream: options.stream
+    });
+    if (response.ok || attempt >= maxAttempts) break;
+    const backoffMs = Math.min(500 * 2 ** (attempt - 1), 4000);
+    await new Promise((resolve) => setTimeout(resolve, backoffMs));
+  }
   const endOffsetMs = Number(process.hrtime.bigint() - benchmarkStartedAt) / 1e6;
   const outputTokens = response.ok
     ? await countTokens(fmBin, response.output, options)
@@ -338,7 +345,10 @@ function publicOptions(options) {
       e2eMs: options.sloE2eMs || null,
       tpotMs: options.sloTpotMs || null
     },
-    instructions: options.instructions ? '[set]' : ''
+    instructions: options.instructions ? '[set]' : '',
+    retry: options.retry ?? 0,
+    tags: options.tags?.length ? options.tags : [],
+    note: options.note ?? null
   };
 }
 

package/src/cli.js

@@ -1,10 +1,12 @@
 import fs from 'node:fs/promises';
 import { createRequire } from 'node:module';
 import { inspectModels, runBenchmark } from './bench.js';
+import { diffReports, renderCompareReport } from './compare.js';
+import { loadHistory, renderHistoryReport } from './history.js';
 import { runProcess } from './process.js';
 import { createProgress } from './progress.js';
 import { flattenResults, toCsv, writeReport } from './report.js';
-import { legendEntries, renderBenchmarkReport, renderLegend, renderModelsTable } from './table.js';
+import { legendEntries, renderBenchmarkReport, renderLatencyHistogram, renderLegend, renderModelsTable } from './table.js';
 
 const require = createRequire(import.meta.url);
 const packageJson = require('../package.json');
@@ -38,6 +40,16 @@ export async function runCli(argv = process.argv.slice(2)) {
     return;
   }
 
+  if (parsed.command === 'compare') {
+    await runCompare(parsed, renderOptions(parsed));
+    return;
+  }
+
+  if (parsed.command === 'history') {
+    await runHistory(parsed, renderOptions(parsed));
+    return;
+  }
+
   if (parsed.command === 'models') {
     const inspection = await inspectModels(parsed);
     if (parsed.format === 'json') {
@@ -48,6 +60,11 @@ export async function runCli(argv = process.argv.slice(2)) {
     return;
   }
 
+  if (parsed.ci) {
+    if (parsed.color === 'auto') parsed.color = 'never';
+    if (parsed.progress === 'auto') parsed.progress = 'never';
+  }
+
   const progress = createProgress({
     ...renderOptions(parsed),
     enabled: resolveProgress(parsed),
@@ -70,6 +87,10 @@ export async function runCli(argv = process.argv.slice(2)) {
     console.log(toCsv(flattenResults(payload.results)));
   } else {
     console.log(renderBenchmarkReport(payload, renderOptions(parsed)));
+    if (parsed.histogram) {
+      console.log();
+      console.log(renderLatencyHistogram(payload.results, renderOptions(parsed)));
+    }
     if (parsed.verbose) {
       console.log();
       console.log(toCsv(flattenResults(payload.results)));
@@ -83,11 +104,62 @@ export async function runCli(argv = process.argv.slice(2)) {
       console.error(`Saved ${reportFormat.toUpperCase()} report to ${written}`);
     }
   }
+
+  if (parsed.outputDir) {
+    const stamp = payload.startedAt.replace(/[:.]/g, '-').replace('T', '_').slice(0, 19);
+    const firstModel = parsed.models?.flatMap((m) => String(m).split(',')).map((m) => m.trim()).filter(Boolean)[0] || 'all';
+    const modelSlug = firstModel.replace(/[^a-z0-9]/gi, '_');
+    const filename = `fm-bench_${stamp}_${modelSlug}.json`;
+    const filePath = `${parsed.outputDir}/${filename}`;
+    const written = await writeReport(filePath, payload, 'json');
+    if (parsed.format !== 'json') {
+      console.error(`Saved JSON report to ${written}`);
+    }
+  }
+
+  if (parsed.ci) {
+    const ciResult = evaluateCi(payload);
+    if (!ciResult.passed) {
+      const reasons = ciResult.reasons.join('; ');
+      console.error(`fm-bench ci: FAIL — ${reasons}`);
+      const error = new Error(`CI checks failed: ${reasons}`);
+      error.exitCode = 1;
+      throw error;
+    }
+    console.error(`fm-bench ci: PASS`);
+  }
+}
+
+function evaluateCi(payload) {
+  const reasons = [];
+  const totalFailed = payload.summary.reduce((sum, item) => sum + item.failures, 0);
+  if (totalFailed > 0) {
+    reasons.push(`${totalFailed} run(s) failed`);
+  }
+
+  const hasSlo = payload.options?.slo && (
+    payload.options.slo.ttftMs || payload.options.slo.e2eMs || payload.options.slo.tpotMs
+  );
+  if (hasSlo) {
+    for (const item of payload.summary) {
+      if (!item.available) continue;
+      if (item.goodputRate != null && item.goodputRate < 1) {
+        const pct = Math.round((1 - item.goodputRate) * 100);
+        reasons.push(`${item.model} c${item.concurrency ?? 1}: ${pct}% of runs violated SLO`);
+      }
+    }
+  }
+
+  return {
+    passed: reasons.length === 0,
+    reasons
+  };
 }
 
 export function parseArgs(argv) {
   const options = {
     command: 'run',
+    compareFiles: [],
     models: [],
     prompts: [],
     runs: 1,
@@ -107,16 +179,21 @@ export function parseArgs(argv) {
     captureOutput: false,
     availableOnly: false,
     failFast: false,
+    retry: 0,
+    ci: false,
+    tags: [],
+    note: null,
     verbose: false,
     ascii: false,
     color: 'auto',
     progress: 'auto',
     compact: false,
-    width: null
+    width: null,
+    histogram: false
   };
 
   const args = [...argv];
-  if (args[0] && !args[0].startsWith('-') && ['run', 'models', 'doctor', 'legend', 'metrics', 'help'].includes(args[0])) {
+  if (args[0] && !args[0].startsWith('-') && ['run', 'models', 'doctor', 'legend', 'metrics', 'compare', 'history', 'help'].includes(args[0])) {
     options.command = args.shift();
   }
 
@@ -189,6 +266,9 @@ export function parseArgs(argv) {
         break;
       case '--profile':
         options.profile = requireValue(arg, args);
+        if (!['quick', 'standard', 'interactive', 'throughput', 'client', 'stress', 'reasoning', 'coding', 'creative'].includes(options.profile)) {
+          throw new Error(`--profile must be one of: quick, standard, interactive, throughput, client, stress, reasoning, coding, creative`);
+        }
         break;
       case '-i':
       case '--instructions':
@@ -248,10 +328,16 @@ export function parseArgs(argv) {
       case '--width':
         options.width = parsePositiveInt(requireValue(arg, args), arg);
         break;
+      case '--histogram':
+        options.histogram = true;
+        break;
       case '-o':
       case '--out':
         options.out = requireValue(arg, args);
         break;
+      case '--output-dir':
+        options.outputDir = requireValue(arg, args);
+        break;
       case '--capture-output':
         options.captureOutput = true;
         break;
@@ -261,6 +347,18 @@ export function parseArgs(argv) {
       case '--fail-fast':
         options.failFast = true;
         break;
+      case '--retry':
+        options.retry = parseNonNegativeInt(requireValue(arg, args), arg);
+        break;
+      case '--ci':
+        options.ci = true;
+        break;
+      case '--tag':
+        options.tags.push(requireValue(arg, args));
+        break;
+      case '--note':
+        options.note = requireValue(arg, args);
+        break;
       case '-v':
       case '--verbose':
         options.verbose = true;
@@ -275,8 +373,14 @@ export function parseArgs(argv) {
         if (arg.startsWith('-')) {
           throw new Error(`Unknown option: ${arg}`);
         }
-        options.prompts.push([arg, ...args].join(' '));
-        args.length = 0;
+        if (options.command === 'compare') {
+          options.compareFiles.push(arg);
+        } else if (options.command === 'history') {
+          options.historyDir = arg;
+        } else {
+          options.prompts.push([arg, ...args].join(' '));
+          args.length = 0;
+        }
         break;
     }
   }
@@ -284,6 +388,64 @@ export function parseArgs(argv) {
   return options;
 }
 
+async function runHistory(options, renderOpts) {
+  const dir = options.historyDir || options.outputDir || '.';
+  const reports = await loadHistory(dir);
+
+  if (options.format === 'json') {
+    const data = reports.map(({ filePath, report }) => ({
+      file: filePath,
+      startedAt: report.startedAt,
+      version: report.version,
+      summary: report.summary
+    }));
+    console.log(JSON.stringify(data, null, 2));
+  } else {
+    console.log(renderHistoryReport(reports, renderOpts));
+  }
+}
+
+async function runCompare(options, renderOpts) {
+  const files = options.compareFiles;
+  if (files.length < 2) {
+    throw new Error('compare requires two JSON report files: fm-bench compare before.json after.json');
+  }
+  if (files.length > 2) {
+    throw new Error('compare accepts exactly two JSON report files');
+  }
+
+  const [beforePath, afterPath] = files;
+  const [beforeText, afterText] = await Promise.all([
+    fs.readFile(beforePath, 'utf8'),
+    fs.readFile(afterPath, 'utf8')
+  ]);
+
+  let before, after;
+  try {
+    before = JSON.parse(beforeText);
+  } catch {
+    throw new Error(`Cannot parse ${beforePath} as JSON`);
+  }
+  try {
+    after = JSON.parse(afterText);
+  } catch {
+    throw new Error(`Cannot parse ${afterPath} as JSON`);
+  }
+
+  const diff = diffReports(before, after);
+
+  if (options.format === 'json') {
+    console.log(JSON.stringify(diff, null, 2));
+  } else {
+    console.log(renderCompareReport(diff, renderOpts));
+  }
+
+  if (options.out) {
+    await fs.writeFile(options.out, `${JSON.stringify(diff, null, 2)}\n`, 'utf8');
+    console.error(`Saved compare report to ${options.out}`);
+  }
+}
+
 async function runDoctor(options) {
   const checks = [];
   checks.push(['node', process.version, true]);
@@ -295,13 +457,46 @@ async function runDoctor(options) {
   const major = versionMatch ? Number.parseInt(versionMatch[1].split('.')[0], 10) : null;
   checks.push(['macOS', versionMatch?.[1] || 'unknown', major == null || major >= 27]);
 
+  const hwModel = await runProcess('sysctl', ['-n', 'hw.model'], { timeoutMs: 3_000 });
+  const hwModelStr = (hwModel.stdout || '').trim();
+  if (hwModelStr) checks.push(['hw.model', hwModelStr, true]);
+
+  const cpuBrand = await runProcess('sysctl', ['-n', 'machdep.cpu.brand_string'], { timeoutMs: 3_000 });
+  const cpuBrandStr = (cpuBrand.stdout || '').trim();
+  if (cpuBrandStr) checks.push(['cpu', cpuBrandStr, true]);
+
+  const memBytes = await runProcess('sysctl', ['-n', 'hw.memsize'], { timeoutMs: 3_000 });
+  const memRaw = (memBytes.stdout || '').trim();
+  if (memRaw) {
+    const gb = (Number(memRaw) / (1024 ** 3)).toFixed(0);
+    checks.push(['memory', `${gb} GB`, true]);
+  }
+
+  const thermalResult = await runProcess('pmset', ['-g', 'therm'], { timeoutMs: 5_000 });
+  const thermalOut = (thermalResult.stdout || thermalResult.stderr || '').trim();
+  const thermalMatch = thermalOut.match(/CPU_Scheduler_Limit\s*=\s*(\d+)/);
+  if (thermalMatch) {
+    const limit = Number.parseInt(thermalMatch[1], 10);
+    checks.push(['thermal limit', `${limit}%`, limit >= 100]);
+  }
+
+  const batteryResult = await runProcess('pmset', ['-g', 'batt'], { timeoutMs: 5_000 });
+  const batteryOut = (batteryResult.stdout || '').trim();
+  const batteryLine = batteryOut.split('\n').find((line) => line.includes('%'));
+  if (batteryLine) {
+    const pctMatch = batteryLine.match(/(\d+)%/);
+    const charging = /charging|AC Power|charged/i.test(batteryLine);
+    const pct = pctMatch ? `${pctMatch[1]}%` : '?%';
+    checks.push(['battery', `${pct}${charging ? ' (charging/AC)' : ' (battery)'}`, charging || Number.parseInt(pctMatch?.[1], 10) >= 20]);
+  }
+
   const inspection = await inspectModels(options);
   checks.push(['fm', inspection.fmBin, inspection.models.length > 0]);
   for (const model of inspection.models) {
     checks.push([`model:${model.name}`, model.available ? 'available' : model.reason || 'unavailable', model.available]);
   }
 
-  const lines = checks.map(([name, detail, ok]) => `${ok ? 'ok  ' : 'warn'} ${name.padEnd(14)} ${String(detail).replace(/\s+/g, ' ').trim()}`);
+  const lines = checks.map(([name, detail, ok]) => `${ok ? 'ok  ' : 'warn'} ${name.padEnd(16)} ${String(detail).replace(/\s+/g, ' ').trim()}`);
   console.log(lines.join('\n'));
 
   if (options.out) {
@@ -374,12 +569,16 @@ Dynamic benchmark CLI for Apple's fm command on macOS 27+.
 Usage:
   fm-bench [run] [options]
   fm-bench models [options]
+  fm-bench compare <before.json> <after.json> [options]
+  fm-bench history [dir] [options]
   fm-bench legend [options]
   fm-bench doctor [options]
 
 Commands:
   run                  Benchmark discovered or selected fm models
   models               List discovered models and availability
+  compare              Compare two saved JSON reports and show metric deltas
+  history              Show a trend table from all fm-bench JSON reports in a directory
   legend               Explain every terminal table column and color rule
   doctor               Check Node, macOS, fm, and model availability
 
@@ -398,7 +597,7 @@ Run options:
       --slo-tpot-ms <n>     Count request as good only if TPOT is <= n
   -p, --prompt <text>       Prompt to benchmark; repeatable
       --prompt-file <file>  .json, .jsonl, or blank-line separated text prompts
-      --profile <name>      quick, standard, interactive, throughput, client, or stress
+      --profile <name>      quick, standard, interactive, throughput, client, stress, reasoning, coding, or creative
   -i, --instructions <text> Instructions passed to fm respond
       --use-case <case>     Pass a system model use case through to fm
       --guardrails <level>  Pass a system model guardrail level through to fm
@@ -409,6 +608,10 @@ Run options:
       --available-only      Hide unavailable discovered models
       --capture-output      Include raw model output in JSON reports
       --fail-fast           Stop after the first failed measured run
+      --retry <n>           Retry failed fm calls up to n times with exponential backoff
+      --ci                  Exit 1 if any run fails or any SLO is violated; disables color and progress
+      --tag <name>          Tag this run; repeatable; included in JSON payload and report header
+      --note <text>         Freeform note included in JSON payload and report header
 
 Output:
       --format <type>       table, json, or csv (default: table)
@@ -421,7 +624,9 @@ Output:
       --no-progress         Disable live progress on stderr
       --compact             Force compact terminal layout
       --width <n>           Render for a specific terminal width
+      --histogram           Print an ASCII latency distribution histogram after the report
   -o, --out <file>          Save JSON or CSV report based on file extension
+      --output-dir <dir>    Save a timestamped JSON report to a directory automatically
   -v, --verbose             Include per-run CSV after the summary table
 
 Environment:
@@ -434,6 +639,11 @@ Examples:
   fm-bench --models system,pcc --runs 3 --profile stress
   fm-bench --profile client --sweep-concurrency 1,2 --request-rate 0.5
   fm-bench --prompt "Reply with exactly: ok" --json --out bench.json
+  fm-bench --profile reasoning --runs 5 --retry 2
+  fm-bench compare before.json after.json
+  fm-bench compare before.json after.json --json
+  fm-bench history ./reports
+  fm-bench history ./reports --json
   fm-bench legend
   fm-bench models
   fm-bench doctor

package/src/compare.js

@@ -0,0 +1,241 @@
+import { formatMs, formatNumber, formatPercent } from './table.js';
+
+export function diffReports(before, after) {
+  const beforeByKey = indexSummary(before.summary ?? []);
+  const afterByKey = indexSummary(after.summary ?? []);
+
+  const keys = new Set([...beforeByKey.keys(), ...afterByKey.keys()]);
+  const rows = [];
+
+  for (const key of [...keys].sort()) {
+    const b = beforeByKey.get(key);
+    const a = afterByKey.get(key);
+    rows.push(buildDiffRow(key, b ?? null, a ?? null));
+  }
+
+  return {
+    before: reportMeta(before),
+    after: reportMeta(after),
+    rows
+  };
+}
+
+function reportMeta(report) {
+  return {
+    version: report.version ?? '?',
+    startedAt: report.startedAt ?? '',
+    finishedAt: report.finishedAt ?? '',
+    runs: report.options?.runs ?? null,
+    profile: report.options?.profile ?? null,
+    concurrency: report.options?.concurrency ?? null
+  };
+}
+
+function indexSummary(summary) {
+  const map = new Map();
+  for (const item of summary) {
+    const key = `${item.model}::${item.concurrency ?? 1}`;
+    map.set(key, item);
+  }
+  return map;
+}
+
+function buildDiffRow(key, before, after) {
+  const [model, concurrencyStr] = key.split('::');
+  return {
+    model,
+    concurrency: Number.parseInt(concurrencyStr, 10) || 1,
+    available: {
+      before: before?.available ?? null,
+      after: after?.available ?? null
+    },
+    ttftP50: diffMs(before?.ttft?.p50, after?.ttft?.p50),
+    ttftP95: diffMs(before?.ttft?.p95, after?.ttft?.p95),
+    e2eP50: diffMs(before?.latency?.p50, after?.latency?.p50),
+    e2eP95: diffMs(before?.latency?.p95, after?.latency?.p95),
+    e2eP99: diffMs(before?.latency?.p99, after?.latency?.p99),
+    tpotP50: diffMs(before?.tpot?.p50, after?.tpot?.p50),
+    successRate: diffPercent(before?.successRate, after?.successRate),
+    goodputRate: diffPercent(before?.goodputRate, after?.goodputRate),
+    tokensPerSecond: diffNumber(before?.tokensPerSecond?.avg, after?.tokensPerSecond?.avg, false),
+    rps: diffNumber(before?.rps, after?.rps, false),
+    cv: diffPercent(before?.latency?.cv, after?.latency?.cv)
+  };
+}
+
+function diffMs(before, after) {
+  return {
+    before: before ?? null,
+    after: after ?? null,
+    delta: numDelta(before, after),
+    deltaPercent: percentDelta(before, after)
+  };
+}
+
+function diffNumber(before, after, lowerIsBetter = true) {
+  return {
+    before: before ?? null,
+    after: after ?? null,
+    delta: numDelta(before, after),
+    deltaPercent: percentDelta(before, after),
+    lowerIsBetter
+  };
+}
+
+function diffPercent(before, after) {
+  return {
+    before: before ?? null,
+    after: after ?? null,
+    delta: numDelta(before, after),
+    deltaPercent: percentDelta(before, after)
+  };
+}
+
+function numDelta(before, after) {
+  if (!Number.isFinite(before) || !Number.isFinite(after)) return null;
+  return after - before;
+}
+
+function percentDelta(before, after) {
+  if (!Number.isFinite(before) || !Number.isFinite(after) || before === 0) return null;
+  return (after - before) / Math.abs(before);
+}
+
+export function renderCompareReport(diff, options = {}) {
+  const { color = false, ascii = false } = options;
+  const width = options.width || process.stdout.columns || 120;
+  const V = ascii ? '|' : '│';
+  const H = ascii ? '-' : '─';
+  const TL = ascii ? '+' : '┌';
+  const TR = ascii ? '+' : '┐';
+  const BL = ascii ? '+' : '└';
+  const BR = ascii ? '+' : '┘';
+  const ML = ascii ? '+' : '├';
+  const MR = ascii ? '+' : '┤';
+  const TJ = ascii ? '+' : '┬';
+  const MJ = ascii ? '+' : '┼';
+  const BJ = ascii ? '+' : '┴';
+
+  const lines = [];
+
+  const beforeLabel = `${diff.before.version}  ${diff.before.startedAt ? diff.before.startedAt.slice(0, 19).replace('T', ' ') : '?'}`;
+  const afterLabel = `${diff.after.version}  ${diff.after.startedAt ? diff.after.startedAt.slice(0, 19).replace('T', ' ') : '?'}`;
+
+  lines.push(`fm-bench compare`);
+  lines.push(`  before: ${beforeLabel}`);
+  lines.push(`  after:  ${afterLabel}`);
+  lines.push('');
+
+  const colWidths = [8, 3, 10, 10, 10, 10, 10, 10, 8, 8, 9, 7, 7];
+  const headers = ['MODEL', 'C', 'TTFT P50', 'TTFT P95', 'E2E P50', 'E2E P95', 'E2E P99', 'TPOT P50', 'SUCC', 'GOOD', 'USER T/S', 'RPS', 'CV'];
+
+  const renderRule = (l, j, r) => `${l}${colWidths.map((w) => H.repeat(w + 2)).join(j)}${r}`;
+  const renderRow = (cells) => `${V}${cells.map((cell, i) => ` ${fitCell(cell, colWidths[i])} `).join(V)}${V}`;
+
+  lines.push(renderRule(TL, TJ, TR));
+  lines.push(renderRow(headers.map((h, i) => pad(h, colWidths[i]))));
+  lines.push(renderRule(ML, MJ, MR));
+
+  for (const row of diff.rows) {
+    const bLine = renderRow([
+      fitCell(row.model, colWidths[0]),
+      fitCell(String(row.concurrency), colWidths[1]),
+      fmtDiffMs(row.ttftP50, 'before', color),
+      fmtDiffMs(row.ttftP95, 'before', color),
+      fmtDiffMs(row.e2eP50, 'before', color),
+      fmtDiffMs(row.e2eP95, 'before', color),
+      fmtDiffMs(row.e2eP99, 'before', color),
+      fmtDiffMs(row.tpotP50, 'before', color),
+      fitCell(row.successRate.before != null ? formatPercent(row.successRate.before) : '-', colWidths[8]),
+      fitCell(row.goodputRate.before != null ? formatPercent(row.goodputRate.before) : '-', colWidths[9]),
+      fitCell(row.tokensPerSecond.before != null ? formatNumber(row.tokensPerSecond.before) : '-', colWidths[10]),
+      fitCell(row.rps.before != null ? formatNumber(row.rps.before) : '-', colWidths[11]),
+      fitCell(row.cv.before != null ? formatPercent(row.cv.before) : '-', colWidths[12])
+    ]);
+
+    const deltaLine = renderRow([
+      fitCell('', colWidths[0]),
+      fitCell('', colWidths[1]),
+      fmtDelta(row.ttftP50, true, color, colWidths[2]),
+      fmtDelta(row.ttftP95, true, color, colWidths[3]),
+      fmtDelta(row.e2eP50, true, color, colWidths[4]),
+      fmtDelta(row.e2eP95, true, color, colWidths[5]),
+      fmtDelta(row.e2eP99, true, color, colWidths[6]),
+      fmtDelta(row.tpotP50, true, color, colWidths[7]),
+      fmtDelta(row.successRate, false, color, colWidths[8]),
+      fmtDelta(row.goodputRate, false, color, colWidths[9]),
+      fmtDelta(row.tokensPerSecond, false, color, colWidths[10]),
+      fmtDelta(row.rps, false, color, colWidths[11]),
+      fmtDelta(row.cv, true, color, colWidths[12])
+    ]);
+
+    const aLine = renderRow([
+      fitCell('', colWidths[0]),
+      fitCell('', colWidths[1]),
+      fmtDiffMs(row.ttftP50, 'after', color),
+      fmtDiffMs(row.ttftP95, 'after', color),
+      fmtDiffMs(row.e2eP50, 'after', color),
+      fmtDiffMs(row.e2eP95, 'after', color),
+      fmtDiffMs(row.e2eP99, 'after', color),
+      fmtDiffMs(row.tpotP50, 'after', color),
+      fitCell(row.successRate.after != null ? formatPercent(row.successRate.after) : '-', colWidths[8]),
+      fitCell(row.goodputRate.after != null ? formatPercent(row.goodputRate.after) : '-', colWidths[9]),
+      fitCell(row.tokensPerSecond.after != null ? formatNumber(row.tokensPerSecond.after) : '-', colWidths[10]),
+      fitCell(row.rps.after != null ? formatNumber(row.rps.after) : '-', colWidths[11]),
+      fitCell(row.cv.after != null ? formatPercent(row.cv.after) : '-', colWidths[12])
+    ]);
+
+    lines.push(bLine);
+    lines.push(deltaLine);
+    lines.push(aLine);
+  }
+
+  lines.push(renderRule(BL, BJ, BR));
+  lines.push('');
+  lines.push('Rows: before → delta (% change) → after  |  Lower is better for latency and CV; higher for throughput and success.');
+
+  return lines.join('\n');
+}
+
+function fmtDiffMs(diff, which, color) {
+  const value = diff[which];
+  if (value == null) return '-';
+  return formatMs(value);
+}
+
+function fmtDelta(diff, lowerIsBetter, color, width) {
+  const { delta, deltaPercent } = diff;
+  if (delta == null || deltaPercent == null) return fitCell('n/a', width ?? 10);
+
+  const pct = Math.round(deltaPercent * 100);
+  const sign = delta >= 0 ? '+' : '';
+  const label = `${sign}${pct}%`;
+
+  let tone = null;
+  if (lowerIsBetter) {
+    tone = pct < -5 ? 'green' : pct > 5 ? 'red' : 'yellow';
+  } else {
+    tone = pct > 5 ? 'green' : pct < -5 ? 'red' : 'yellow';
+  }
+
+  const text = fitCell(label, width ?? 10);
+  if (color) return applyTone(text, tone);
+  return text;
+}
+
+function applyTone(text, tone) {
+  const TONES = { green: '\x1b[32m', yellow: '\x1b[33m', red: '\x1b[31m' };
+  const reset = '\x1b[0m';
+  return tone && TONES[tone] ? `${TONES[tone]}${text}${reset}` : text;
+}
+
+function pad(text, width) {
+  const len = String(text ?? '').length;
+  return String(text ?? '') + ' '.repeat(Math.max(0, width - len));
+}
+
+function fitCell(text, width) {
+  const str = String(text ?? '');
+  if (str.length <= width) return str + ' '.repeat(width - str.length);
+  return `${str.slice(0, width - 1)}…`;
+}

package/src/history.js

@@ -0,0 +1,95 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { formatMs, formatNumber, formatPercent } from './table.js';
+
+export async function loadHistory(dir) {
+  const absDir = path.resolve(dir);
+  let entries;
+  try {
+    entries = await fs.readdir(absDir);
+  } catch {
+    throw new Error(`Cannot read directory: ${absDir}`);
+  }
+
+  const jsonFiles = entries
+    .filter((name) => name.endsWith('.json'))
+    .map((name) => path.join(absDir, name))
+    .sort();
+
+  const reports = [];
+  for (const filePath of jsonFiles) {
+    try {
+      const text = await fs.readFile(filePath, 'utf8');
+      const parsed = JSON.parse(text);
+      if (parsed.tool === 'fm-bench' && parsed.summary) {
+        reports.push({ filePath, report: parsed });
+      }
+    } catch {
+      // skip unparseable files
+    }
+  }
+
+  return reports;
+}
+
+export function renderHistoryReport(reports, options = {}) {
+  if (reports.length === 0) {
+    return 'No fm-bench JSON reports found in the given directory.';
+  }
+
+  const { color = false, ascii = false } = options;
+  const V = ascii ? '|' : '│';
+  const H = ascii ? '-' : '─';
+  const TL = ascii ? '+' : '┌';
+  const TR = ascii ? '+' : '┐';
+  const BL = ascii ? '+' : '└';
+  const BR = ascii ? '+' : '┘';
+  const ML = ascii ? '+' : '├';
+  const MR = ascii ? '+' : '┤';
+  const TJ = ascii ? '+' : '┬';
+  const MJ = ascii ? '+' : '┼';
+  const BJ = ascii ? '+' : '┴';
+
+  const colWidths = [19, 8, 3, 6, 9, 9, 9, 9, 5];
+  const headers = ['STARTED AT', 'MODEL', 'C', 'RUNS', 'TTFT P50', 'E2E P50', 'E2E P95', 'USER T/S', 'SUCC'];
+
+  const renderRule = (l, j, r) => `${l}${colWidths.map((w) => H.repeat(w + 2)).join(j)}${r}`;
+  const renderRowLine = (cells) => `${V}${cells.map((text, i) => ` ${fit(text, colWidths[i])} `).join(V)}${V}`;
+
+  const lines = [];
+  lines.push(`fm-bench history (${reports.length} report${reports.length === 1 ? '' : 's'})`);
+  lines.push('');
+  lines.push(renderRule(TL, TJ, TR));
+  lines.push(renderRowLine(headers.map((h, i) => h)));
+  lines.push(renderRule(ML, MJ, MR));
+
+  for (const { filePath, report } of reports) {
+    const started = report.startedAt ? report.startedAt.slice(0, 19).replace('T', ' ') : '?';
+    const modelRows = report.summary ?? [];
+
+    for (const item of modelRows) {
+      if (!item.available) continue;
+      const row = [
+        started,
+        item.model ?? '-',
+        String(item.concurrency ?? 1),
+        String(item.successes ?? '-'),
+        item.ttft?.p50 != null ? formatMs(item.ttft.p50) : '-',
+        item.latency?.p50 != null ? formatMs(item.latency.p50) : '-',
+        item.latency?.p95 != null ? formatMs(item.latency.p95) : '-',
+        item.tokensPerSecond?.avg != null ? formatNumber(item.tokensPerSecond.avg) : '-',
+        item.successRate != null ? formatPercent(item.successRate) : '-'
+      ];
+      lines.push(renderRowLine(row));
+    }
+  }
+
+  lines.push(renderRule(BL, BJ, BR));
+  return lines.join('\n');
+}
+
+function fit(text, width) {
+  const str = String(text ?? '');
+  if (str.length <= width) return str + ' '.repeat(width - str.length);
+  return `${str.slice(0, width - 1)}…`;
+}

package/src/prompts.js

@@ -93,6 +93,72 @@ const PROFILES = {
       id: 'summarize',
       prompt: 'Summarize this in two bullets: local model benchmarks should measure first-token latency, total latency, throughput, failures, and the exact prompt suite so results can be compared later.'
     }
+  ],
+  reasoning: [
+    {
+      id: 'math-word',
+      prompt: 'A server processes 1,200 requests per minute at peak. Each request uses 0.8 ms of CPU time on average. How many CPU cores are needed to handle peak load at 70% utilization? Show your reasoning step-by-step, then give a single final answer.'
+    },
+    {
+      id: 'logic-sequence',
+      prompt: 'Five engineers — Alice, Bob, Carol, Dave, Eve — each deploy one service. Alice deploys before Bob. Carol deploys after Dave but before Eve. Bob deploys before Dave. List the deployment order from first to last.'
+    },
+    {
+      id: 'causal-chain',
+      prompt: 'A CI pipeline has: lint (2 min), unit tests (5 min, parallel), integration tests (8 min, depends on unit), build (3 min, depends on integration), deploy (1 min, depends on build). What is the minimum wall-clock time from start to deployed? Explain each step.'
+    },
+    {
+      id: 'estimation',
+      prompt: 'Estimate how many tokens per day a popular AI coding assistant might process if it has 500,000 daily active users, each averaging 30 completions of 200 output tokens. Show your calculation and state any assumptions.'
+    },
+    {
+      id: 'debug-logic',
+      prompt: 'This function should return the median of a list: def median(lst): lst.sort(); n=len(lst); return lst[n//2] if n%2 else (lst[n//2-1]+lst[n//2])/2. Find all bugs and explain why each is a bug.'
+    }
+  ],
+  coding: [
+    {
+      id: 'code-review',
+      prompt: 'Review this TypeScript for correctness, performance, and readability issues: async function fetchAll(urls: string[]) { const results = []; for (const url of urls) { const r = await fetch(url); results.push(await r.json()); } return results; } Give three specific improvements with brief explanations.'
+    },
+    {
+      id: 'refactor',
+      prompt: 'Refactor this JavaScript to be cleaner and handle edge cases: function getUser(id, cb) { db.query("SELECT * FROM users WHERE id=" + id, function(err, rows) { if (err) { cb(null, err); } else { cb(rows[0]); } }); } Return only the improved code and a two-sentence explanation.'
+    },
+    {
+      id: 'algorithm',
+      prompt: 'Write a JavaScript function findDuplicates(arr) that returns all duplicate values in O(n) time and O(n) space. Include a brief complexity explanation and two edge-case examples.'
+    },
+    {
+      id: 'explain-code',
+      prompt: 'Explain what this code does, why it might be used, and one potential problem: const cache = new WeakMap(); function memoize(fn) { return function(...args) { if (!cache.has(this)) cache.set(this, new Map()); const key = JSON.stringify(args); if (!cache.get(this).has(key)) cache.get(this).set(key, fn.apply(this, args)); return cache.get(this).get(key); }; }'
+    },
+    {
+      id: 'system-design',
+      prompt: 'Design a rate limiter in 120 words or fewer: specify the data structure, the algorithm (token bucket, sliding window, or fixed window), and how you handle distributed deployments. Be precise and practical.'
+    }
+  ],
+  creative: [
+    {
+      id: 'product-announcement',
+      prompt: 'Write a 100-word product announcement for a developer tool called "PulseDB" that shows real-time query performance heatmaps in the terminal. Tone: enthusiastic but not hypey. Include one concrete example of what a user would see.'
+    },
+    {
+      id: 'error-message',
+      prompt: 'Rewrite this cryptic error into a helpful, actionable message a junior developer could act on: "Error: ECONNREFUSED 127.0.0.1:5432 errno: -111 syscall: connect code: ECONNREFUSED". Include what likely caused it and the first two things to check.'
+    },
+    {
+      id: 'technical-analogy',
+      prompt: 'Explain CPU context switching to someone who has never programmed, using a single concrete analogy from everyday life. Keep it under 80 words and make sure the analogy captures the performance cost.'
+    },
+    {
+      id: 'commit-message',
+      prompt: 'Write a clear and conventional git commit message for a change that adds retry logic with exponential backoff and jitter to the HTTP client. Include a subject line and a 3-bullet body.'
+    },
+    {
+      id: 'doc-summary',
+      prompt: 'Write a one-paragraph README introduction for an open-source CLI tool called "logslice" that extracts time-bounded log windows from large log files without loading them fully into memory. Target audience: backend engineers.'
+    }
   ]
 };
 

package/src/table.js

@@ -3,24 +3,30 @@ import { stripAnsi } from './ansi.js';
 export function renderTable(headers, rows, options = {}) {
   const ascii = Boolean(options.ascii);
   const maxCellWidth = options.maxCellWidth || 60;
-  const normalizedRows = rows.map((row) => row.map((cell) => {
+  const wrapColumns = normalizeWrapColumns(headers, options.wrapColumns);
+  const normalizedRows = rows.map((row) => row.map((cell, index) => {
     const normalized = normalizeCell(cell);
     return {
       ...normalized,
-      text: truncate(normalized.text, maxCellWidth)
+      text: wrapColumns.has(index) ? normalized.text : truncate(normalized.text, maxCellWidth)
     };
   }));
-  const widths = headers.map((header, index) => {
+  const widths = fitTableWidths(headers, headers.map((header, index) => {
     const values = [truncate(header, maxCellWidth), ...normalizedRows.map((row) => row[index]?.text ?? '')];
+    if (wrapColumns.has(index)) {
+      return Math.max(...values.map((value) => Math.min(maxCellWidth, visibleLength(value))));
+    }
     return Math.max(...values.map(visibleLength));
-  });
+  }), wrapColumns, terminalWidth(options));
   const style = ascii ? ASCII_TABLE : UNICODE_TABLE;
 
   const top = rule(style.topLeft, style.topJoin, style.topRight, style.horizontal, widths);
   const middle = rule(style.midLeft, style.midJoin, style.midRight, style.horizontal, widths);
   const bottom = rule(style.bottomLeft, style.bottomJoin, style.bottomRight, style.horizontal, widths);
   const headerLine = rowLine(headers.map((header) => truncate(header, maxCellWidth)), widths, style, true, options);
-  const bodyLines = normalizedRows.map((row) => rowLine(row, widths, style, false, options));
+  const bodyLines = wrapColumns.size > 0
+    ? normalizedRows.flatMap((row) => wrappedRowLines(row, widths, style, wrapColumns, options))
+    : normalizedRows.map((row) => rowLine(row, widths, style, false, options));
 
   return [top, headerLine, middle, ...bodyLines, bottom].join('\n');
 }
@@ -44,8 +50,12 @@ export function renderBenchmarkReport(payload, options = {}) {
 
   const title = `fm-bench ${payload.version} | ${payload.environment.platform}/${payload.environment.arch} | ${payload.environment.fmBin}`;
   const meta = `prompts ${payload.prompts.length} | runs ${payload.options.runs} | concurrency ${concurrencies} | stream ${payload.options.stream ? 'on' : 'off'} | measured ${measured} | failed ${failed} | skipped ${skipped} | elapsed ${formatMs(elapsedMs)}${slo ? ` | ${slo}` : ''}`;
+  const tags = payload.options?.tags?.length ? payload.options.tags : [];
+  const note = payload.options?.note ?? null;
   lines.push(truncate(title, width));
   lines.push(truncate(meta, width));
+  if (tags.length > 0) lines.push(truncate(`tags: ${tags.join(', ')}`, width));
+  if (note) lines.push(truncate(`note: ${note}`, width));
   lines.push('');
 
   if (mode === 'compact') {
@@ -115,6 +125,49 @@ export function renderLegend(options = {}) {
   return renderWrappedTable(['table', 'column', 'definition', 'rule'], rows, legendColumnWidths(width), options);
 }
 
+export function renderLatencyHistogram(results, options = {}) {
+  const { ascii = false, color = false, width: termWidth = 80 } = options;
+  const successes = results.filter((r) => r.ok && Number.isFinite(r.durationMs));
+  if (successes.length === 0) return 'No successful results to histogram.';
+
+  const values = successes.map((r) => r.durationMs).sort((a, b) => a - b);
+  const min = values[0];
+  const max = values[values.length - 1];
+
+  if (min === max) {
+    return `E2E latency histogram: all ${values.length} values = ${formatMs(min)}`;
+  }
+
+  const numBuckets = Math.min(20, Math.max(5, Math.floor((termWidth - 20) / 4)));
+  const bucketSize = (max - min) / numBuckets;
+  const counts = new Array(numBuckets).fill(0);
+
+  for (const v of values) {
+    const idx = Math.min(numBuckets - 1, Math.floor((v - min) / bucketSize));
+    counts[idx] += 1;
+  }
+
+  const maxCount = Math.max(...counts);
+  const barWidth = Math.max(1, termWidth - 24);
+  const lines = [];
+  const bar = ascii ? '#' : '█';
+  const halfBar = ascii ? ':' : '▌';
+
+  lines.push(`E2E latency distribution (n=${values.length}, ${formatMs(min)}…${formatMs(max)}):`);
+
+  for (let i = 0; i < numBuckets; i += 1) {
+    const bucketMin = min + i * bucketSize;
+    const bucketMax = bucketMin + bucketSize;
+    const label = `${formatMs(bucketMin)}`.padStart(7);
+    const fillLength = Math.round((counts[i] / maxCount) * barWidth);
+    const filled = bar.repeat(fillLength);
+    const countStr = counts[i] > 0 ? String(counts[i]) : '';
+    lines.push(`${label} ${filled}${countStr ? ` ${countStr}` : ''}`);
+  }
+
+  return lines.join('\n');
+}
+
 export function formatMs(value) {
   if (value == null || !Number.isFinite(value)) return '-';
   if (value >= 1000) return `${(value / 1000).toFixed(2)}s`;
@@ -155,7 +208,7 @@ export function renderSummaryTable(summary, options = {}) {
       cell(formatNumber(item.outputTokenThroughput), tones.systemTps),
       cell(formatNumber(item.rps), tones.rps),
       cell(formatPercent(item.latency.cv), cvTone(item.latency.cv)),
-      cell(item.available ? '' : compactReason(item.skippedReason), item.available ? null : 'yellow')
+      cell(item.available ? '' : cleanReason(item.skippedReason), item.available ? null : 'yellow')
     ];
 
     if (mode === 'medium') {
@@ -194,7 +247,7 @@ export function renderSummaryTable(summary, options = {}) {
     ? (hasGoodput ? mediumHeaders : mediumHeaders.filter((header) => header !== 'good' && header !== 'good rps'))
     : (hasGoodput ? wideHeaders : wideHeaders.filter((header) => header !== 'good' && header !== 'good rps'));
 
-  return renderTable(headers, rows, { ...options, maxCellWidth: mode === 'medium' ? 24 : 52 });
+  return renderTable(headers, rows, { ...options, maxCellWidth: mode === 'medium' ? 24 : 52, wrapColumns: ['note'] });
 }
 
 export function renderDetailTable(summary, options = {}) {
@@ -241,7 +294,7 @@ export function renderDetailTable(summary, options = {}) {
       'description'
     ];
 
-  return renderTable(headers, rows, { ...options, maxCellWidth: mode === 'medium' ? 34 : 52 });
+  return renderTable(headers, rows, { ...options, maxCellWidth: mode === 'medium' ? 34 : 52, wrapColumns: ['description'] });
 }
 
 export function renderCompactSummary(summary, options = {}) {
@@ -286,8 +339,8 @@ export function renderModelsTable(models, options = {}) {
     cell(model.name),
     cell(model.available ? 'yes' : 'no', model.available ? 'green' : 'yellow'),
     model.description || '-',
-    compactReason(model.quota || model.reason || '-')
-  ]), options);
+    cleanReason(model.quota || model.reason || '-')
+  ]), { ...options, wrapColumns: ['description', 'quota'] });
 }
 
 function formatRangeMs(low, high) {
@@ -372,6 +425,69 @@ function renderWrappedTable(headers, rows, widths, options = {}) {
   return [top, headerLine, middle, ...bodyLines, bottom].join('\n');
 }
 
+function normalizeWrapColumns(headers, wrapColumns = []) {
+  const normalized = new Set();
+  for (const column of wrapColumns || []) {
+    if (Number.isInteger(column)) {
+      if (column >= 0 && column < headers.length) normalized.add(column);
+      continue;
+    }
+
+    const index = headers.findIndex((header) => String(header).toLowerCase() === String(column).toLowerCase());
+    if (index >= 0) normalized.add(index);
+  }
+  return normalized;
+}
+
+function fitTableWidths(headers, widths, wrapColumns, targetWidth) {
+  if (!targetWidth || wrapColumns.size === 0 || renderedTableWidth(widths) <= targetWidth) return widths;
+
+  const fitted = [...widths];
+  const minimums = fitted.map((width, index) => (
+    wrapColumns.has(index)
+      ? Math.max(visibleLength(String(headers[index]).toUpperCase()), Math.min(12, width))
+      : width
+  ));
+  let excess = renderedTableWidth(fitted) - targetWidth;
+
+  while (excess > 0) {
+    const candidates = [...wrapColumns]
+      .filter((index) => fitted[index] > minimums[index])
+      .sort((a, b) => fitted[b] - fitted[a]);
+    if (candidates.length === 0) break;
+
+    for (const index of candidates) {
+      if (excess <= 0) break;
+      fitted[index] -= 1;
+      excess -= 1;
+    }
+  }
+
+  return fitted;
+}
+
+function renderedTableWidth(widths) {
+  return widths.reduce((sum, width) => sum + width, 0) + (widths.length * 3) + 1;
+}
+
+function wrappedRowLines(row, widths, style, wrapColumns, options = {}) {
+  const wrappedCells = row.map((value, index) => {
+    const normalized = normalizeCell(value);
+    return {
+      tone: normalized.tone,
+      lines: wrapColumns.has(index) ? wrapText(normalized.text, widths[index]) : [normalized.text]
+    };
+  });
+  const height = Math.max(...wrappedCells.map((item) => item.lines.length));
+  const lines = [];
+
+  for (let lineIndex = 0; lineIndex < height; lineIndex += 1) {
+    lines.push(rowLine(wrappedCells.map((item) => cell(item.lines[lineIndex] ?? '', item.tone)), widths, style, false, options));
+  }
+
+  return lines;
+}
+
 function rowLine(row, widths, style, header = false, options = {}) {
   return `${style.vertical}${row.map((cell, index) => {
     const normalized = header ? { text: String(cell).toUpperCase(), tone: 'header' } : normalizeCell(cell);
@@ -417,8 +533,12 @@ function visibleLength(value) {
   return stripAnsi(value).length;
 }
 
+function cleanReason(value) {
+  return String(value || '').replace(/\s+/g, ' ').trim();
+}
+
 function compactReason(value) {
-  const clean = String(value || '').replace(/\s+/g, ' ').trim();
+  const clean = cleanReason(value);
   if (clean.length <= 58) return clean;
   return `${clean.slice(0, 55)}...`;
 }