fm-bench 0.6.3 → 0.7.1

package/src/report.js

@@ -16,6 +16,7 @@ export function flattenResults(results) {
     concurrency: result.concurrency ?? '',
     prompt_id: result.promptId,
     run: result.run,
+    attempts: result.attempts ?? 1,
     ok: result.ok,
     duration_ms: round(result.durationMs),
     ttft_ms: round(result.firstTokenMs),
@@ -58,9 +59,19 @@ export async function writeReport(filePath, payload, format) {
 
 function csvEscape(value) {
   const text = String(value ?? '');
-  if (/[",\n\r]/.test(text)) {
-    return `"${text.replaceAll('"', '""')}"`;
+  const safe = guardFormula(text);
+  if (/[",\n\r]/.test(safe)) {
+    return `"${safe.replaceAll('"', '""')}"`;
   }
+  return safe;
+}
+
+// Spreadsheet programs execute cells that start with =, +, @, or a non-numeric
+// leading -. Prompt text and captured output are untrusted input, so prefix
+// those cells with a single quote to keep them literal text.
+function guardFormula(text) {
+  if (/^[=+@\t\r]/.test(text)) return `'${text}`;
+  if (text.startsWith('-') && !/^-?\d+(\.\d+)?$/.test(text)) return `'${text}`;
   return text;
 }
 

package/src/schema.js

@@ -126,10 +126,26 @@ export function validateReport(value) {
   for (const key of REQUIRED_TOP_LEVEL) {
     if (!(key in report)) errors.push(`missing required field: ${key}`);
   }
-  if (!Array.isArray(report.summary)) errors.push('summary must be an array');
+  if (!Array.isArray(report.summary)) {
+    errors.push('summary must be an array');
+  } else {
+    for (const [index, item] of report.summary.entries()) {
+      if (!item || typeof item !== 'object') {
+        errors.push(`summary[${index}] must be an object`);
+        continue;
+      }
+      const row = /** @type {Record<string, unknown>} */ (item);
+      if (typeof row.model !== 'string' || row.model === '') {
+        errors.push(`summary[${index}].model must be a non-empty string`);
+      }
+    }
+  }
   if (report.schemaVersion != null && report.schemaVersion !== REPORT_SCHEMA_VERSION) {
     errors.push(`unsupported schemaVersion: ${report.schemaVersion} (expected ${REPORT_SCHEMA_VERSION})`);
   }
+  if (report.metrics != null && (typeof report.metrics !== 'object' || Array.isArray(report.metrics))) {
+    errors.push('metrics must be an object when present');
+  }
   if (errors.length > 0) return { ok: false, errors };
   return { ok: true, report };
 }

package/src/stats.js

@@ -1,3 +1,12 @@
+/**
+ * Sample statistics for one metric.
+ *
+ * Spread metrics (`stddev`, `cv`, `ci95*`) need at least two samples. With a
+ * single sample they are `null` rather than `0`, because a "0% variation" or a
+ * zero-width confidence interval is invented precision, not a measurement.
+ *
+ * @param {number[]} values
+ */
 export function summarizeNumbers(values) {
   const clean = values.filter((value) => Number.isFinite(value)).sort((a, b) => a - b);
   if (clean.length === 0) {
@@ -20,11 +29,12 @@ export function summarizeNumbers(values) {
 
   const total = clean.reduce((sum, value) => sum + value, 0);
   const avg = total / clean.length;
-  const variance = clean.length > 1
+  const hasSpread = clean.length > 1;
+  const variance = hasSpread
     ? clean.reduce((sum, value) => sum + (value - avg) ** 2, 0) / (clean.length - 1)
-    : 0;
-  const stddev = Math.sqrt(variance);
-  const margin = clean.length > 1 ? tCritical95(clean.length) * (stddev / Math.sqrt(clean.length)) : 0;
+    : null;
+  const stddev = variance == null ? null : Math.sqrt(variance);
+  const margin = hasSpread ? tCritical95(clean.length) * (stddev / Math.sqrt(clean.length)) : null;
   return {
     count: clean.length,
     min: clean[0],
@@ -32,9 +42,9 @@ export function summarizeNumbers(values) {
     avg,
     sum: total,
     stddev,
-    cv: avg !== 0 ? stddev / Math.abs(avg) : null,
-    ci95Low: avg - margin,
-    ci95High: avg + margin,
+    cv: hasSpread && avg !== 0 ? stddev / Math.abs(avg) : null,
+    ci95Low: hasSpread ? avg - margin : null,
+    ci95High: hasSpread ? avg + margin : null,
     p50: percentile(clean, 50),
     p90: percentile(clean, 90),
     p95: percentile(clean, 95),
@@ -42,16 +52,25 @@ export function summarizeNumbers(values) {
   };
 }
 
-export function percentile(sortedValues, percentileValue) {
-  if (sortedValues.length === 0) return null;
-  if (sortedValues.length === 1) return sortedValues[0];
+/**
+ * Percentile with linear interpolation between closest ranks (the same method
+ * as Excel's PERCENTILE.INC / NumPy's default). Accepts unsorted input so
+ * callers cannot silently get a wrong answer from an unsorted array.
+ *
+ * @param {number[]} values
+ * @param {number} percentileValue 0-100
+ */
+export function percentile(values, percentileValue) {
+  const sorted = values.filter((value) => Number.isFinite(value)).sort((a, b) => a - b);
+  if (sorted.length === 0) return null;
+  if (sorted.length === 1) return sorted[0];
 
-  const rank = (percentileValue / 100) * (sortedValues.length - 1);
+  const rank = (percentileValue / 100) * (sorted.length - 1);
   const low = Math.floor(rank);
   const high = Math.ceil(rank);
-  if (low === high) return sortedValues[low];
+  if (low === high) return sorted[low];
   const weight = rank - low;
-  return sortedValues[low] * (1 - weight) + sortedValues[high] * weight;
+  return sorted[low] * (1 - weight) + sorted[high] * weight;
 }
 
 export function summarizeByModel(results, modelStatuses = [], options = {}) {
@@ -66,6 +85,7 @@ export function summarizeByModel(results, modelStatuses = [], options = {}) {
         concurrency,
         description: status.description,
         available: status.available,
+        unsupported: Boolean(status.unsupported),
         skippedReason: status.available ? '' : status.reason || 'Unavailable',
         results: []
       });
@@ -80,6 +100,7 @@ export function summarizeByModel(results, modelStatuses = [], options = {}) {
         concurrency: result.concurrency,
         description: '',
         available: true,
+        unsupported: false,
         skippedReason: '',
         results: []
       });
@@ -98,7 +119,7 @@ export function summarizeByModel(results, modelStatuses = [], options = {}) {
     const tpot = summarizeNumbers(successes.map((result) => result.tpotMs).filter((value) => value != null));
     const promptTokens = summarizeNumbers(successes.map((result) => result.promptTokens).filter((value) => value != null));
     const outputTokens = summarizeNumbers(successes.map((result) => result.outputTokens).filter((value) => value != null));
-    const charsPerSecond = summarizeNumbers(successes.map((result) => result.charsPerSecond));
+    const charsPerSecond = summarizeNumbers(successes.map((result) => result.charsPerSecond).filter((value) => value != null));
     const tokensPerSecond = summarizeNumbers(successes.map((result) => result.tokensPerSecond).filter((value) => value != null));
     const decodeTokensPerSecond = summarizeNumbers(successes.map((result) => result.decodeTokensPerSecond).filter((value) => value != null));
     const prefillTokensPerSecond = summarizeNumbers(successes.map((result) => result.prefillTokensPerSecond).filter((value) => value != null));
@@ -110,14 +131,18 @@ export function summarizeByModel(results, modelStatuses = [], options = {}) {
     const outputTokenThroughput = outputTokens.sum > 0 && windowMs > 0 ? outputTokens.sum / (windowMs / 1000) : null;
     const totalTokens = promptTokens.sum + outputTokens.sum;
     const totalTokenThroughput = totalTokens > 0 && windowMs > 0 ? totalTokens / (windowMs / 1000) : null;
+    const attempts = entry.results.reduce((sum, result) => sum + (result.attempts ?? 1), 0);
 
     return {
       model: entry.model,
       concurrency: entry.concurrency,
       description: entry.description,
       available: entry.available,
+      unsupported: entry.unsupported,
       skippedReason: entry.skippedReason,
       attempted: entry.results.length,
+      attempts,
+      retried: entry.results.length > 0 ? Math.max(0, attempts - entry.results.length) : 0,
       successes: successes.length,
       failures: failures.length,
       successRate: entry.results.length > 0 ? successes.length / entry.results.length : null,
@@ -147,6 +172,10 @@ function summaryKey(model, concurrency) {
   return `${model}::${concurrency ?? 'default'}`;
 }
 
+// Two-sided 95% t critical values. Exact table entries up to 30 degrees of
+// freedom, then the standard 2.0 / 1.96 approximations for larger samples.
+// fm-bench uses this for a mean confidence interval, which is context for
+// small samples rather than a hypothesis test.
 function tCritical95(n) {
   const df = Math.max(1, n - 1);
   const table = {

package/src/table.js

@@ -1,4 +1,5 @@
 import { stripAnsi } from './ansi.js';
+import { formatCapabilitySummary } from './metrics.js';
 
 export function renderTable(headers, rows, options = {}) {
   const ascii = Boolean(options.ascii);
@@ -52,10 +53,19 @@ export function renderBenchmarkReport(payload, options = {}) {
   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(...wrapText(title, width));
+  lines.push(...wrapText(meta, width));
+  if (tags.length > 0) {
+    for (const line of wrapText(`tags: ${tags.join(', ')}`, width)) lines.push(line);
+  }
+  if (note) {
+    for (const line of wrapText(`note: ${note}`, width)) lines.push(line);
+  }
+  for (const metricNote of unavailableMetricNotes(payload.metrics)) {
+    for (const line of wrapText(`unavailable: ${metricNote}`, width)) {
+      lines.push(line);
+    }
+  }
   lines.push('');
 
   if (mode === 'compact') {
@@ -71,41 +81,43 @@ export function renderBenchmarkReport(payload, options = {}) {
 
 export function legendEntries() {
   return [
-    entry('summary', 'C', 'Concurrency operating point for this row.', 'Higher C means more parallel fm respond processes.'),
-    entry('summary', 'MODEL', 'fm model name, such as system or pcc.', ''),
-    entry('summary', 'STATUS', 'Run status for this model and operating point.', 'ok = all measured jobs passed; partial = at least one failed; skipped = unavailable.'),
-    entry('summary', 'OK / OK/RUNS', 'Successful measured runs over attempted measured runs.', 'Green when no failures; yellow when partial.'),
-    entry('summary', 'SUCC / SUCCESS', 'Success rate: successful runs divided by attempted runs.', 'Green 100%, yellow >=95%, red <95%.'),
-    entry('summary', 'GOOD', 'Goodput rate: successful runs that also met every configured SLO.', 'Only appears when SLO flags are set. Green 100%, yellow >=80%, red <80%.'),
-    entry('summary', 'GOOD RPS', 'SLO-passing requests per second during this measured window.', 'Zero is shown when SLOs are set and no request meets them.'),
-    entry('summary', 'TTFT', 'Time to first streamed output chunk, p50.', 'Lower is better. Uses SLO threshold when set; otherwise relative ranking.'),
-    entry('summary', 'TTFT P95', '95th percentile time to first streamed output chunk.', 'Lower is better.'),
-    entry('summary', 'E2E', 'End-to-end latency, p50, from starting fm respond until full response exits.', 'Lower is better.'),
-    entry('summary', 'E2E P95', '95th percentile end-to-end latency.', 'Lower is better; this is usually the main interactive tail-latency signal.'),
-    entry('summary', 'TPOT', 'Time per output token after the first output token, p50.', 'Lower is better. Requires streaming and token counts.'),
-    entry('summary', 'TPOT P95', '95th percentile time per output token after first token.', 'Lower is better.'),
-    entry('summary', 'USER/S / USER T/S', 'Per-request output tokens per second.', 'Higher is better; relative ranking.'),
-    entry('summary', 'SYS/S / SYS T/S', 'Aggregate successful output-token throughput for the model row.', 'Higher is better; relative ranking.'),
-    entry('summary', 'RPS', 'Successful requests per second over the model row measured window.', 'Higher is better; relative ranking.'),
-    entry('summary', 'CV', 'Coefficient of variation for E2E latency: sample stddev divided by mean.', 'Lower is steadier. Green <=10%, yellow <=25%, red >25%.'),
-    entry('summary', 'NOTE', 'Short unavailable, skipped, or error note.', ''),
-    entry('detail', 'IN AVG / IN TOK AVG', 'Average prompt/input token count from fm token-count.', ''),
-    entry('detail', 'OUT AVG / OUT TOK AVG', 'Average output token count from fm token-count.', ''),
-    entry('detail', 'PREFILL/S / PREFILL TOK/S', 'Prompt tokens divided by TTFT seconds.', 'Higher is better; estimates prompt-processing speed for streaming runs.'),
-    entry('detail', 'DECODE/S / DECODE TOK/S', 'Output tokens after the first token divided by generation seconds.', 'Higher is better; requires streaming and token counts.'),
-    entry('detail', '2ND CHUNK', 'Delay between the first and second streamed stdout chunks, p50.', 'Lower is smoother startup. Chunk-based, not raw token telemetry.'),
-    entry('detail', 'CHUNK P95', '95th percentile gap between consecutive streamed stdout chunks.', 'Lower is smoother streaming.'),
-    entry('detail', 'E2E P99', '99th percentile end-to-end latency.', 'Lower is better; useful for worst-case UX.'),
-    entry('detail', 'E2E 95% CI', '95% confidence interval around mean E2E latency.', 'Narrower usually means a steadier estimate. Treat small samples carefully.'),
-    entry('detail', 'REPEAT', 'Share of repeated runs for a prompt that produced the most common normalized output hash.', 'Green 90%+, yellow 50%+, red below 50%. Blank when there are not repeated comparable outputs.'),
-    entry('detail', 'DESCRIPTION', 'Model description discovered from fm help.', ''),
-    entry('models', 'AVAILABLE', 'Whether fm available reports the model as usable on this machine right now.', ''),
-    entry('models', 'QUOTA', 'Raw fm quota-usage output or unavailable reason.', 'Mostly relevant for Private Cloud Compute.'),
-    entry('compact', 'GOOD / CV / TPOT / CHUNK', 'Compact output combines the same summary and detail metrics into model cards.', 'Same definitions and color rules as table columns.'),
-    entry('colors', 'GREEN', 'Passing, steadier, faster, or better within this benchmark context.', ''),
-    entry('colors', 'YELLOW', 'Marginal, partial, near a budget, or middle-ranked within this benchmark context.', ''),
-    entry('colors', 'RED', 'Failed budget, unstable, slower, lower, or worse within this benchmark context.', ''),
-    entry('colors', 'MUTED', 'Unavailable model, skipped value, or descriptive text.', '')
+    entry('summary', 'C', 'Concurrency operating point for this row.', 'Higher C means more parallel fm respond processes.', 'controlled'),
+    entry('summary', 'MODEL', 'fm model name reported by the detected fm build.', '', 'measured'),
+    entry('summary', 'STATUS', 'Run status for this model and operating point.', 'ok = all measured jobs passed; partial = at least one failed; skipped = unavailable or unsupported.', 'measured'),
+    entry('summary', 'OK / OK/RUNS', 'Successful measured runs over attempted measured runs.', 'Green when no failures; yellow when partial.', 'measured'),
+    entry('summary', 'SUCC / SUCCESS', 'Success rate: successful runs divided by attempted runs.', 'Green 100%, yellow >=95%, red <95%.', 'measured'),
+    entry('summary', 'GOOD', 'Goodput rate: successful runs that also met every configured SLO.', 'Only appears when SLO flags are set. Runs whose SLO metric is unmeasurable count as not good.', 'derived'),
+    entry('summary', 'GOOD RPS', 'SLO-passing requests per second during this measured window.', 'Zero is shown when SLOs are set and no request meets them.', 'derived'),
+    entry('summary', 'TTFT', 'Time from starting fm respond to the first streamed stdout chunk, p50.', 'Proxy for time to first token: measured at chunk granularity, not per token. Lower is better.', 'proxy'),
+    entry('summary', 'TTFT P95', '95th percentile time to the first streamed stdout chunk.', 'Lower is better.', 'proxy'),
+    entry('summary', 'E2E', 'End-to-end latency, p50, from starting fm respond until full response exits.', 'Lower is better. This is a direct wall-clock measurement.', 'measured'),
+    entry('summary', 'E2E P95', '95th percentile end-to-end latency.', 'Lower is better; this is usually the main interactive tail-latency signal.', 'measured'),
+    entry('summary', 'TPOT', 'Time per output token after the first output token, p50.', 'Derived from fm token counts and stream timings. Lower is better.', 'derived'),
+    entry('summary', 'TPOT P95', '95th percentile time per output token after first token.', 'Lower is better.', 'derived'),
+    entry('summary', 'USER/S / USER T/S', 'Per-request output tokens per second.', 'Derived from fm token counts. Higher is better.', 'derived'),
+    entry('summary', 'SYS/S / SYS T/S', 'Aggregate successful output-token throughput for the model row.', 'Higher is better.', 'derived'),
+    entry('summary', 'RPS', 'Successful requests per second over the model row measured window.', 'Measured from process timings. Higher is better.', 'measured'),
+    entry('summary', 'CV', 'Coefficient of variation for E2E latency: sample stddev divided by mean.', 'Lower is steadier. Green <=10%, yellow <=25%, red >25%.', 'derived'),
+    entry('summary', 'NOTE', 'Short unavailable, skipped, or error note.', '', 'measured'),
+    entry('detail', 'IN AVG / IN TOK AVG', 'Average prompt/input token count from fm count-tokens.', 'Blank when the fm build cannot count tokens.', 'measured'),
+    entry('detail', 'OUT AVG / OUT TOK AVG', 'Average output token count from fm count-tokens.', 'Blank when the fm build cannot count tokens.', 'measured'),
+    entry('detail', 'PREFILL/S / PREFILL TOK/S', 'Prompt tokens divided by TTFT seconds.', 'Proxy: prefill is inferred from time to first chunk, not observed directly. Higher is better.', 'proxy'),
+    entry('detail', 'DECODE/S / DECODE TOK/S', 'Output tokens after the first token divided by generation seconds.', 'Derived; requires streaming and token counts. Higher is better.', 'derived'),
+    entry('detail', '2ND CHUNK', 'Delay between the first and second streamed stdout chunks, p50.', 'Lower is smoother startup. Chunk-based, not raw token telemetry.', 'proxy'),
+    entry('detail', 'CHUNK P95', '95th percentile gap between consecutive streamed stdout chunks.', 'Proxy for decode smoothness at chunk granularity. Lower is smoother.', 'proxy'),
+    entry('detail', 'E2E P99', '99th percentile end-to-end latency.', 'Lower is better; useful for worst-case UX.', 'measured'),
+    entry('detail', 'E2E 95% CI', '95% confidence interval around mean E2E latency.', 'Blank with fewer than two successful samples; treat small samples carefully.', 'derived'),
+    entry('detail', 'REPEAT', 'Share of repeated runs for a prompt that produced the most common normalized output hash.', 'Green 90%+, yellow 50%+, red below 50%. Blank when there are not repeated comparable outputs.', 'derived'),
+    entry('detail', 'ATTEMPTS', 'Total fm invocations including retries.', 'Shown in reports; a retried run is still one measured result.', 'measured'),
+    entry('detail', 'DESCRIPTION', 'Model description discovered from fm help.', '', 'measured'),
+    entry('models', 'AVAILABLE', 'Whether fm available reports the model as usable on this machine right now.', '', 'measured'),
+    entry('models', 'QUOTA', 'Quota information when the fm build exposes a quota command.', 'Column is omitted entirely when the installed fm has no quota command.', 'measured'),
+    entry('metrics', 'SOURCE', 'How a metric is obtained: measured, proxy, derived, or controlled.', 'measured = observed directly; proxy = observed at coarser granularity; derived = computed from measured values.', 'measured'),
+    entry('compact', 'GOOD / CV / TPOT / CHUNK', 'Compact output combines the same summary and detail metrics into model cards.', 'Same definitions and color rules as table columns.', 'derived'),
+    entry('colors', 'GREEN', 'Passing, steadier, faster, or better within this benchmark context.', '', 'controlled'),
+    entry('colors', 'YELLOW', 'Marginal, partial, near a budget, or middle-ranked within this benchmark context.', '', 'controlled'),
+    entry('colors', 'RED', 'Failed budget, unstable, slower, lower, or worse within this benchmark context.', '', 'controlled'),
+    entry('colors', 'MUTED', 'Unavailable model, skipped value, or descriptive text.', '', 'controlled')
   ];
 }
 
@@ -114,6 +126,7 @@ export function renderLegend(options = {}) {
   const rows = legendEntries().map((item) => [
     item.table,
     item.column,
+    item.kind || 'measured',
     item.definition,
     item.rule || '-'
   ]);
@@ -122,7 +135,7 @@ export function renderLegend(options = {}) {
     return renderCompactLegend(width);
   }
 
-  return renderWrappedTable(['table', 'column', 'definition', 'rule'], rows, legendColumnWidths(width), options);
+  return renderWrappedTable(['table', 'column', 'source', 'definition', 'rule'], rows, legendColumnWidths(width), options);
 }
 
 export function renderLatencyHistogram(results, options = {}) {
@@ -335,6 +348,19 @@ export function renderModelsTable(models, options = {}) {
     }).join('\n');
   }
 
+  const quotaSupported = options.capabilities
+    ? Boolean(options.capabilities.features?.quota)
+    : models.some((model) => model.quotaSupported === true || (model.quota != null && model.quota !== ''));
+
+  if (!quotaSupported) {
+    return renderTable(['model', 'available', 'description', 'notes'], models.map((model) => [
+      cell(model.name),
+      cell(model.available ? 'yes' : 'no', model.available ? 'green' : 'yellow'),
+      model.description || '-',
+      cleanReason(model.reason || '-')
+    ]), { ...options, wrapColumns: ['description', 'notes'] });
+  }
+
   return renderTable(['model', 'available', 'description', 'quota'], models.map((model) => [
     cell(model.name),
     cell(model.available ? 'yes' : 'no', model.available ? 'green' : 'yellow'),
@@ -343,6 +369,27 @@ export function renderModelsTable(models, options = {}) {
   ]), { ...options, wrapColumns: ['description', 'quota'] });
 }
 
+/**
+ * `fm-bench models` body: fm capability summary, then the model table.
+ * Unsupported capabilities are stated up front so a missing quota column or
+ * blank metric never looks like a bug.
+ */
+export function renderModelsReport(models, options = {}) {
+  const capabilities = options.capabilities;
+  const lines = [];
+  if (capabilities) {
+    lines.push(`fm        ${capabilities.bin}${capabilities.digest ? `  help ${capabilities.digest}` : ''}${capabilities.ok ? '' : '  (no commands detected)'}`);
+    lines.push(`commands  ${capabilities.commands.join(', ') || 'none detected'}`);
+    lines.push(`features  ${formatCapabilitySummary(capabilities)}`);
+    for (const warning of capabilities.warnings) {
+      lines.push(`warn      ${warning}`);
+    }
+    lines.push('');
+  }
+  lines.push(renderModelsTable(models, options));
+  return lines.join('\n');
+}
+
 function formatRangeMs(low, high) {
   if (low == null || high == null || !Number.isFinite(low) || !Number.isFinite(high)) return '-';
   return `${formatMs(Math.max(0, low))}..${formatMs(Math.max(0, high))}`;
@@ -364,15 +411,38 @@ function formatSlo(slo = {}) {
   return parts.length ? `SLO ${parts.join(',')}` : '';
 }
 
-function entry(table, column, definition, rule) {
+function entry(table, column, definition, rule, kind = 'measured') {
   return {
     table,
     column,
     definition,
-    rule
+    rule,
+    kind
   };
 }
 
+/**
+ * Reasons why metric columns are blank. Keeps "unavailable" visible in table
+ * output instead of leaving readers to guess why a column is empty.
+ */
+function unavailableMetricNotes(metrics) {
+  if (!metrics) return [];
+  const notes = [];
+  const tokenMetric = metrics.promptTokens;
+  if (tokenMetric && !tokenMetric.available) {
+    notes.push(`${tokenMetric.label} unavailable — ${tokenMetric.unavailableReason}`);
+  }
+  const ttft = metrics.ttft;
+  if (ttft && !ttft.available) {
+    notes.push(`${ttft.label} unavailable — ${ttft.unavailableReason}`);
+  }
+  const quota = metrics.quota;
+  if (quota && !quota.available) {
+    notes.push(`${quota.label} unavailable — ${quota.unavailableReason}`);
+  }
+  return notes;
+}
+
 const ASCII_TABLE = {
   topLeft: '+',
   topJoin: '+',
@@ -516,7 +586,10 @@ function normalizeCell(value) {
 
 function formatCell(value) {
   if (value == null) return '';
-  return String(value);
+  // Terminal output carries prompt text, captured model output, and fm
+  // diagnostics. Strip ANSI escapes and control characters so they cannot
+  // corrupt the table layout or emit terminal control sequences.
+  return stripAnsi(String(value)).replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/g, '');
 }
 
 function pad(value, width, left = false) {
@@ -546,7 +619,7 @@ function compactReason(value) {
 function renderCompactLegend(width) {
   const lines = [];
   for (const item of legendEntries()) {
-    lines.push(...wrapText(`${item.table.toUpperCase()} ${item.column}`, width));
+    lines.push(...wrapText(`${item.table.toUpperCase()} ${item.column} (${item.kind || 'measured'})`, width));
     lines.push(...wrapText(`  Definition: ${item.definition}`, width));
     if (item.rule) {
       lines.push(...wrapText(`  Rule: ${item.rule}`, width));
@@ -558,13 +631,14 @@ function renderCompactLegend(width) {
 }
 
 function legendColumnWidths(width) {
-  const available = Math.max(40, width - 13);
+  const available = Math.max(40, width - 16);
   const tableWidth = 7;
-  const columnWidth = Math.min(25, Math.max(18, Math.floor(available * 0.28)));
-  const remaining = Math.max(36, available - tableWidth - columnWidth);
-  const definitionWidth = Math.max(18, Math.floor(remaining * 0.52));
-  const ruleWidth = Math.max(18, remaining - definitionWidth);
-  return [tableWidth, columnWidth, definitionWidth, ruleWidth];
+  const columnWidth = Math.min(25, Math.max(18, Math.floor(available * 0.22)));
+  const sourceWidth = 11;
+  const remaining = Math.max(32, available - tableWidth - columnWidth - sourceWidth);
+  const definitionWidth = Math.max(18, Math.floor(remaining * 0.58));
+  const ruleWidth = Math.max(14, remaining - definitionWidth);
+  return [tableWidth, columnWidth, sourceWidth, definitionWidth, ruleWidth];
 }
 
 function wrapText(value, width) {