gloomberb 0.18.2 → 0.18.4

package/src/cli/report-tables.ts

@@ -57,6 +57,12 @@ export interface CliReportColumn<Row = Record<string, unknown>> {
   format?: (value: unknown, row: Row) => string;
   /** The row field naming the unit of a number in this column; the number then exports as it is, with that unit. */
   unitKey?: string;
+  /**
+   * With `unitKey`: the unit always goes to a `<header> unit` column beside
+   * the figures, never into the header, so the header is the same whichever
+   * rows loaded (a market cap in one currency for some peers, in another for others).
+   */
+  unitColumn?: boolean;
 }
 
 /** A label/value line of a report. `unit` names the unit of a numeric `value` when `formatted` cannot say it. */
@@ -69,7 +75,8 @@ export interface CliReportEntry {
 }
 
 type Cell =
-  | { kind: "blank" }
+  /** `unit`: what the column draws a number of this row in, so a missing figure still names its unit. */
+  | { kind: "blank"; unit?: string }
   | { kind: "text"; text: string; time?: boolean }
   | { kind: "number"; value: number; unit: string }
   /** Text that may read as a number, once the whole column is known. */
@@ -80,6 +87,10 @@ type ResolvedCell = Exclude<Cell, { kind: "textual" }>;
 interface ResolvedColumn {
   header: string;
   cells: ResolvedCell[];
+  /** The unit the column draws its numbers in, for a table with no rows to say it. */
+  unit?: string;
+  /** The unit always has a column of its own (`unitColumn`). */
+  unitColumn?: boolean;
 }
 
 const BLANK = { kind: "blank" } as const;
@@ -265,8 +276,9 @@ function resolveColumn(header: string, cells: Cell[], parseText: boolean): Resol
   };
 }
 
+/** The units a column's numbers are in, a missing figure's own among them, so the header does not change with which figures are missing. */
 function numberUnits(cells: readonly ResolvedCell[]): Set<string> {
-  return new Set(cells.flatMap((cell) => cell.kind === "number" ? [cell.unit] : []));
+  return new Set(cells.flatMap((cell) => cell.kind === "number" ? [cell.unit] : cell.kind === "blank" && cell.unit != null ? [cell.unit] : []));
 }
 
 function cellValue(cell: ResolvedCell): CliReportValue {
@@ -312,9 +324,9 @@ function rowUnits(columns: readonly ResolvedColumn[], mixed: readonly boolean[],
  * metrics whose rows each have one, and otherwise a `<header> unit` column
  * beside a column that mixes them (a rate in % and a spread in bp).
  */
-function assembleTable(title: string, columns: readonly ResolvedColumn[], rowCount: number): CliReportTable {
-  const units = columns.map((column) => numberUnits(column.cells));
-  const mixed = units.map((columnUnits) => columnUnits.size > 1);
+function assembleTable(title: string, columns: readonly ResolvedColumn[], rowCount: number, status?: StatusColumn): CliReportTable {
+  const units = columns.map((column) => rowCount === 0 && column.unit != null ? new Set([column.unit]) : numberUnits(column.cells));
+  const mixed = units.map((columnUnits, index) => columnUnits.size > 1 || columns[index]!.unitColumn === true);
   const byRow = mixed.some(Boolean) ? rowUnits(columns, mixed, rowCount) : null;
   const layout = columns.flatMap((column, index) => {
     const columnUnits = units[index]!;
@@ -338,6 +350,7 @@ function assembleTable(title: string, columns: readonly ResolvedColumn[], rowCou
       },
     ];
   });
+  if (status) layout.push({ header: status.header, value: (row: number) => status.values[row] ?? "" });
   return {
     title,
     columns: layout.map((column) => column.header),
@@ -345,28 +358,151 @@ function assembleTable(title: string, columns: readonly ResolvedColumn[], rowCou
   };
 }
 
+/** The `status` column a table of rows ends its own columns with: why a figure is missing, by row. */
+interface StatusColumn {
+  header: string;
+  values: string[];
+}
+
+/**
+ * A number a probe draws through a column's format, to read the unit the
+ * column draws numbers in. A figure format rounds it; a format that prints
+ * it whole passes values through as text and draws no figures of its own.
+ */
+const UNIT_PROBE = 0.1234567891;
+
+/**
+ * A row with nothing in it that a format can still read through: every
+ * field, call and conversion of it is empty. For a format that reads fields of
+ * the row beyond its value and would throw on an empty one.
+ */
+const EMPTY_ROW: unknown = (() => {
+  const empty: unknown = new Proxy(function empty() {}, {
+    get: (_target, key) => key === Symbol.toPrimitive ? (hint: string) => (hint === "number" ? Number.NaN : "") : empty,
+    apply: () => empty,
+  });
+  return empty;
+})();
+
+/**
+ * The unit a column draws a number of this row in (`%` for an IV, `""` for a
+ * plain figure), read from what its format draws for one; null when it draws
+ * no figure for one, passes the value through as it is, or throws.
+ */
+function drawnUnit<Row>(column: CliReportColumn<Row>, row: Row, rowUnitKey?: string): string | null {
+  // A figure in the row's own unit is bare: the row's `currency_or_unit` names it.
+  if (rowUnitKey && column.unitKey === rowUnitKey) return "";
+  const unit = column.unitKey ? (row as Record<string, unknown> | undefined)?.[column.unitKey] : undefined;
+  if (typeof unit === "string" && unit) return unit;
+  if (!column.format) return null;
+  try {
+    const drawn = column.format(UNIT_PROBE, row);
+    if (typeof drawn !== "string" || drawn.trim() === String(UNIT_PROBE)) return null;
+    const read = readDisplay(drawn);
+    return read && read !== BLANK_DISPLAY ? read.unit : null;
+  } catch {
+    // Intentional ignore: a format that cannot draw a number for this row draws no unit for it.
+    return null;
+  }
+}
+
+/**
+ * The unit a column draws its figures in whatever the rows, read without one:
+ * on an empty row, or through a row of nothing when the format throws on an
+ * empty one. The same with rows and without, so a header and the table's
+ * status column do not depend on what was loaded. Null for a column of text.
+ */
+function columnUnit<Row>(column: CliReportColumn<Row>): string | null {
+  if (column.unitKey) return "";
+  if (!column.format) return null;
+  try {
+    column.format(UNIT_PROBE, {} as Row);
+    return drawnUnit(column, {} as Row);
+  } catch {
+    // Intentional ignore: the format reads a field an empty row lacks; read it through a row of nothing.
+    return drawnUnit(column, EMPTY_ROW as Row);
+  }
+}
+
+/** What a status cell says: each reason once, after the columns it is the reason for. */
+function statusText(reasons: ReadonlyArray<{ header: string; text: string }>): string {
+  const byText = new Map<string, string[]>();
+  for (const { header, text } of reasons) byText.set(text, [...byText.get(text) ?? [], header]);
+  return [...byText].map(([text, headers]) => `${headers.join(", ")}: ${text}`).join("; ");
+}
+
+const isMissing = (value: unknown) => value == null || (typeof value === "number" && !Number.isFinite(value));
+
 // Codes a spreadsheet must not turn into numbers, even when they are digits.
 const IDENTIFIER_KEY = /^(?:id|cik|code|cusip|figi|isin|symbol|ticker)$|(?:Id|Cik|Code|Cusip|Figi|Isin|Symbol|Ticker)$/;
 
-/** A table of rows under the columns the text view draws. */
+/**
+ * A table of rows under the columns the text view draws. A figure that is
+ * missing still names the unit its column draws it in, so a header is the same
+ * whichever figures a symbol has. With `status`, a reason the text draws in
+ * place of a missing figure (`not quoted`, `under 7d`) leaves the cell empty
+ * and goes to the `status` column the table ends its own columns with, so a
+ * column of figures holds only numbers. Only a row whose own value is missing,
+ * in a column that draws that row's figures, has a reason: text a format draws
+ * from the rest of the row (a range, N/M, ATM) stays. A table has the column
+ * when one of its columns draws figures through a format, read from the
+ * columns alone so it is there with or without rows, and a table of text has
+ * none; beside a column of its own named Status it is `value_status`.
+ * `rowUnitKey` is the row field its `currency_or_unit` cell is read from: a
+ * column whose `unitKey` is that field exports its figures bare under its own
+ * header (`Last`, never `Last ($)` beside a franc), each row's unit named there.
+ */
 export function exportRowsTable<Row extends Record<string, unknown>>(
   title: string,
   columns: readonly CliReportColumn<Row>[],
   rows: readonly Row[],
+  { status = false, rowUnitKey }: { status?: boolean; rowUnitKey?: string } = {},
 ): CliReportTable {
-  return assembleTable(title, columns.map((column) => resolveColumn(
-    column.header,
-    rows.map((row): Cell => {
-      const record = row as Record<string, unknown> | undefined;
-      const value = record?.[column.key];
-      const unit = column.unitKey ? record?.[column.unitKey] : undefined;
-      if (typeof unit === "string" && unit && typeof value === "number" && Number.isFinite(value)) {
-        return { kind: "number", value: exportNumber(value), unit };
-      }
-      return exportCell(value, column.format ? column.format(value, row) : null, column.key);
-    }),
-    !IDENTIFIER_KEY.test(column.key),
-  )), rows.length);
+  const reasons = rows.map((): Array<{ header: string; text: string }> => []);
+  const units = columns.map(columnUnit);
+  // Decided by the columns alone, so a table has the column, or not, whatever rows it has.
+  const withStatus = status && units.some((unit) => unit != null);
+  const resolved = columns.map((column, columnIndex): ResolvedColumn => {
+    const rowUnits = rows.map((row) => drawnUnit(column, row, rowUnitKey));
+    const values = rows.map((row) => (row as Record<string, unknown> | undefined)?.[column.key]);
+    const inRowUnit = !!rowUnitKey && column.unitKey === rowUnitKey;
+    const { header, cells } = resolveColumn(
+      column.header,
+      rows.map((row, index): Cell => {
+        const value = values[index];
+        const unit = column.unitKey ? (row as Record<string, unknown> | undefined)?.[column.unitKey] : undefined;
+        const drawn = column.format ? column.format(value, row) : null;
+        // A figure the text leaves out of this row (another session's print) is not one of its figures.
+        const left = drawn != null && readDisplay(drawn) === BLANK_DISPLAY;
+        if (!left && typeof value === "number" && Number.isFinite(value) && (inRowUnit || (typeof unit === "string" && unit))) {
+          return { kind: "number", value: exportNumber(value), unit: inRowUnit ? "" : unit as string };
+        }
+        return exportCell(value, drawn, column.key);
+      }),
+      !IDENTIFIER_KEY.test(column.key),
+    );
+    const table: ResolvedColumn = {
+      header,
+      cells: cells.map((cell, index): ResolvedCell => {
+        const unit = rowUnits[index];
+        const blank: ResolvedCell = unit != null ? { kind: "blank", unit } : BLANK;
+        if (cell.kind === "blank") return cell.unit == null ? blank : cell;
+        // Text drawn in place of a figure this row does not have, where the column draws this row's figures: a reason.
+        // Text drawn from the rest of the row (a range, N/M, ATM) is no figure's absence and stays.
+        if (!withStatus || cell.kind !== "text" || cell.time || unit == null || !isMissing(values[index])) return cell;
+        reasons[index]!.push({ header: column.header, text: cell.text });
+        return blank;
+      }),
+    };
+    const unit = units[columnIndex];
+    const withUnit = unit == null ? table : { ...table, unit };
+    return column.unitColumn && column.unitKey && !inRowUnit ? { ...withUnit, unitColumn: true } : withUnit;
+  });
+  const statusColumn = withStatus ? {
+    header: columns.some((column) => column.header.trim().toLowerCase() === "status") ? "value_status" : "status",
+    values: reasons.map(statusText),
+  } : undefined;
+  return assembleTable(title, resolved, rows.length, statusColumn);
 }
 
 /** Label/value lines as `Metric,Value`; a number's unit moves into its label. */
@@ -434,18 +570,33 @@ function sectionList(tables: readonly CliReportTable[]): string {
 }
 
 /**
- * `--section`: one table, by its title (any case) or its 1-based position.
- * Without a selector the report keeps every table.
+ * The table `--section` names by title, in any case: the one titled so, else
+ * the one whose title starts with it, as a title that carries its date does
+ * (`Strikes` for `Strikes · Oct 30 '26`). A start several titles share picks
+ * none.
+ */
+function sectionByTitle(tables: readonly CliReportTable[], wanted: string): CliReportTable | undefined {
+  const name = wanted.toLowerCase();
+  const titles = tables.map((table) => table.title.trim().toLowerCase());
+  const exact = titles.indexOf(name);
+  if (exact >= 0) return tables[exact];
+  const starting = tables.filter((_, index) => titles[index]!.startsWith(name));
+  if (starting.length > 1) {
+    throw new Error(`"${wanted}" starts more than one section: ${starting.map((table) => table.title).join(", ")}. Give more of the title, or its number.`);
+  }
+  return starting[0];
+}
+
+/**
+ * `--section`: one table, by its title or the start of it (any case), or its
+ * 1-based position. Without a selector the report keeps every table.
  */
 export function selectReportTables(report: CliReportTables, selector: string | true | undefined): CliReportTables {
   if (selector === undefined) return report;
   if (selector === true || !selector.trim()) throw new Error("--section needs a section title or number.");
   const wanted = selector.trim();
   if (report.tables.length === 0) throw new Error(`No section "${wanted}": this report has no tables.`);
-  const index = /^\d+$/.test(wanted)
-    ? Number(wanted) - 1
-    : report.tables.findIndex((table) => table.title.trim().toLowerCase() === wanted.toLowerCase());
-  const table = report.tables[index];
+  const table = /^\d+$/.test(wanted) ? report.tables[Number(wanted) - 1] : sectionByTitle(report.tables, wanted);
   if (!table) throw new Error(`No section "${wanted}". Sections: ${sectionList(report.tables)}.`);
   return { ...report, tables: [table] };
 }
@@ -464,7 +615,10 @@ function csvLine(row: readonly unknown[]): string {
 
 /**
  * A table with the fixed columns after its own, every row naming what it is
- * and the source and as-of the footer cites. A table without columns stays empty.
+ * and the source and as-of the footer cites. A fixed column the table already
+ * has under the same name is left out, so its own per-row values stay the
+ * only ones (CBR's `source` and `as_of`) and a reader keyed by name finds one
+ * column. A table without columns stays empty.
  */
 function identifiedTable(table: CliReportTable, report: CliReportTables, freshness: ReportFreshness | undefined): CliReportTable {
   if (!freshness || table.columns.length === 0) return table;
@@ -474,7 +628,16 @@ function identifiedTable(table: CliReportTable, report: CliReportTables, freshne
     const own = table.rowIdentities?.[index];
     return own ? exportIdentityCells(freshness, { ...identity, ...own }) : cells;
   };
-  return { ...table, columns: [...table.columns, ...EXPORT_IDENTITY_COLUMNS], rows: table.rows.map((row, index) => [...row, ...rowCells(index)]) };
+  const added = EXPORT_IDENTITY_COLUMNS.flatMap((column, index) => table.columns.includes(column) ? [] : [index]);
+  if (added.length === 0) return table;
+  return {
+    ...table,
+    columns: [...table.columns, ...added.map((index) => EXPORT_IDENTITY_COLUMNS[index]!)],
+    rows: table.rows.map((row, index) => {
+      const identityCells = rowCells(index);
+      return [...row, ...added.map((column) => identityCells[column]!)];
+    }),
+  };
 }
 
 /**

package/src/cli/restore-plugins.ts

@@ -1,8 +1,10 @@
 import { saveConfig } from "../data/config/store";
 import { loadCliConfigIfAvailable } from "./context";
 import { getPluginsDir } from "../plugins/loader";
-import { seedExtractedPlugins } from "../plugins/extracted-plugins";
+import { pluginSeedFailure, pluginSeedNotice, samePluginSeedFailure, seedExtractedPlugins } from "../plugins/extracted-plugins";
+import { setPluginSeedNotice } from "../plugins/seed-notice";
 import { debugLog } from "../utils/debug-log";
+import type { AppConfig } from "../types/config";
 
 const log = debugLog.createLogger("plugin-seed");
 
@@ -10,39 +12,52 @@ const log = debugLog.createLogger("plugin-seed");
  * Reinstalls plugins that moved out of this repository into their own.
  *
  * Runs before the plugin catalog is read so a restored plugin is available in
- * the same session, and stays quiet on failure: an offline launch should start
- * normally and try again next time, not block on a network request.
+ * the same session, and never blocks or prints: an offline launch should
+ * start normally and try again next time. What it could not install becomes
+ * one notice the app shows once it is up (`setPluginSeedNotice`), saying why
+ * when git is missing, and `doctor` names the plugins.
  *
- * Returns the seeded ids so a caller that already holds the config in memory
- * can adopt them. The desktop loads its config before restoring, and without
- * this it would keep an object whose `seededPlugins` is one launch stale and
- * overwrite the record on the next save.
+ * Returns what it recorded (the seeded ids, and what failed) so a caller that
+ * already holds the config in memory can adopt it. The desktop loads its
+ * config before restoring, and without this it would keep an object one
+ * launch stale and overwrite the record on the next save.
  */
-export async function restoreExtractedPlugins(): Promise<string[] | null> {
+export async function restoreExtractedPlugins(): Promise<Pick<AppConfig, "seededPlugins" | "pluginSeedFailure"> | null> {
   try {
     const config = await loadCliConfigIfAvailable();
     // No data directory yet means a first run: there is nothing to restore.
     if (!config) return null;
-    // Through the registry like `gloomberb install`: the reviewed commit, and
+    // Through the registry like `gloom install`: the reviewed commit, and
     // nothing on a Gloomberb too old for it. That failure is retried at the
     // next launch, by when this Gloomberb has usually updated itself. The
     // registry is read once, and only when something is left to install.
-    const { installListedPlugin, loadRegistryListings } = await import("../plugins/installer");
+    // Quiet: the terminal app is about to own the screen, and git's or bun's
+    // output would be left behind in the scrollback.
+    const { gitInstalled, installListedPlugin, loadRegistryListings } = await import("../plugins/installer");
     let listings: ReturnType<typeof loadRegistryListings> | undefined;
+    let gitMissing: boolean | undefined;
     const result = await seedExtractedPlugins(config, async (repo) => {
+      // Without git every clone fails the same way: no registry read, no attempt.
+      gitMissing ??= !gitInstalled();
+      if (gitMissing) throw new Error("git is not installed");
       listings ??= loadRegistryListings();
-      return installListedPlugin(repo, {}, await listings);
+      return installListedPlugin(repo, { quiet: true }, await listings);
     });
+    // Recorded, so doctor knows a launch tried, and a failure the next launch
+    // retries is not announced again while it lasts.
+    const failure = pluginSeedFailure(result.failed, gitMissing === true);
+    setPluginSeedNotice(pluginSeedNotice(failure, config.pluginSeedFailure));
 
     const seeded = [...new Set(result.seeded)].sort();
     const existing = [...new Set(config.seededPlugins ?? [])].sort();
-    if (seeded.join() === existing.join()) return seeded;
+    const record = { seededPlugins: seeded, pluginSeedFailure: failure };
+    if (seeded.join() === existing.join() && samePluginSeedFailure(failure, config.pluginSeedFailure)) return record;
 
-    await saveConfig({ ...config, seededPlugins: seeded });
+    await saveConfig({ ...config, ...record });
     if (result.installed.length > 0) {
       log.info(`Restored ${result.installed.join(", ")} into ${getPluginsDir()}`);
     }
-    return seeded;
+    return record;
   } catch (error) {
     log.error(`Plugin restore skipped: ${error}`);
     return null;

package/src/cli/result.ts

@@ -1,5 +1,6 @@
 import type { CliGlobalOptions } from "./options";
 import {
+  cliPlainEnabled,
   cliStyles,
   cliTerminalWidth,
   renderStats,
@@ -13,7 +14,7 @@ import {
 } from "../utils/cli-output";
 import { serializeCsv } from "../utils/csv";
 import { formatUtcTime, isEpochMilliseconds, isZonedIsoDateTime } from "../utils/utc-time";
-import { formatFreshnessLine, type ReportFreshness } from "./pane-functions/freshness";
+import { formatFreshnessLine, withSavedCopy, type ReportFreshness } from "./pane-functions/freshness";
 import { withSearchHints, type FredSeriesCheck } from "./not-a-ticker";
 import { renderReportCsv, renderReportNdjson, withCsvFooter, type CliReportTables } from "./report-tables";
 import {
@@ -46,6 +47,12 @@ export interface CliResult<T = unknown> {
    * `fear-greed` prints its row alone.
    */
   exportFreshness?: ReportFreshness;
+  /**
+   * Why a result that still prints counts as a failure (a report with no
+   * data): the command exits 1, and JSON says `ok: false` with this as
+   * `error` beside the data, so the envelope and the exit status agree.
+   */
+  failure?: CliErrorObject;
 }
 
 export interface CliErrorObject {
@@ -92,6 +99,11 @@ export interface CliResultRenderOptions<T = unknown, Row = Record<string, unknow
    * `metadata.rows` in JSON.
    */
   dateKey?: string;
+  /**
+   * The row key that splits the rows into series of their own, each windowed
+   * apart: with `symbol`, `--tail 5` keeps every symbol's newest five rows.
+   */
+  seriesKey?: string;
   /** How many rows to show when neither `--limit` nor `--tail` is given; every row when absent. */
   defaultLimit?: number;
   /**
@@ -108,10 +120,20 @@ export interface CliResultRenderOptions<T = unknown, Row = Record<string, unknow
   exportIdentity?: ExportIdentity | ((row: Row) => ExportIdentity);
   /** What CSV says after the source lines as `# note:` lines: what the rows do not show, such as where a series begins. */
   exportNotes?: readonly string[];
+  /**
+   * Why a row's figures are empty (`Not a ticker: ZZZZQQ.`, `Chg%: no previous
+   * close`), for the `status` column CSV writes after the row's own columns and
+   * the `status` field of an NDJSON row; empty for a whole row. The column is
+   * there whenever this is, with rows or without, so the header never depends
+   * on what loaded. A figure that is no number (NaN) is written empty and,
+   * without a reason here, named as `<header>: not available`.
+   */
+  exportStatus?: (row: Row) => string | null | undefined;
 }
 
-interface CliResultJsonEnvelope<T> extends Omit<CliResult<T>, "freshness" | "exportFreshness"> {
-  ok: true;
+interface CliResultJsonEnvelope<T> extends Omit<CliResult<T>, "freshness" | "exportFreshness" | "failure"> {
+  ok: boolean;
+  error?: CliErrorObject;
   /** Where the data comes from, as CSV's closing `#` lines say it. */
   source?: ExportSource;
   columns?: Array<Pick<CliResultColumn, "key" | "header" | "align" | "width">>;
@@ -142,11 +164,28 @@ function rowWindowOptions(options: CliGlobalOptions, renderOptions: Pick<CliResu
 function windowed<Row>(
   rows: readonly Row[],
   options: CliGlobalOptions,
-  renderOptions: Pick<CliResultRenderOptions, "dateKey" | "defaultLimit">,
+  renderOptions: Pick<CliResultRenderOptions, "dateKey" | "defaultLimit" | "seriesKey">,
 ): RowWindow<Row> {
-  const { dateKey } = renderOptions;
+  const { dateKey, seriesKey } = renderOptions;
   const dateOf = dateKey ? (row: Row) => (isPlainObject(row) ? row[dateKey] : undefined) : undefined;
-  return windowRows(rows, rowWindowOptions(options, renderOptions), dateOf);
+  const windowOptions = rowWindowOptions(options, renderOptions);
+  if (!seriesKey) return windowRows(rows, windowOptions, dateOf);
+  const series = new Map<unknown, Row[]>();
+  for (const row of rows) {
+    const key = isPlainObject(row) ? row[seriesKey] : undefined;
+    const group = series.get(key);
+    if (group) group.push(row);
+    else series.set(key, [row]);
+  }
+  const windows = [...series.values()].map((group) => windowRows(group, windowOptions, dateOf));
+  const count = windowOptions.tail ?? windowOptions.limit;
+  return {
+    rows: windows.flatMap((window) => window.rows),
+    total: rows.length,
+    kept: windows.find((window) => window.kept)?.kept ?? null,
+    note: windows.some((window) => window.note)
+      ? `showing the oldest ${count} ${count === 1 ? "row" : "rows"} of each ${seriesKey}; --tail ${count} for the latest` : null,
+  };
 }
 
 function asRows<T, Row>(data: T, rows?: (data: T) => Row[]): Row[] {
@@ -199,7 +238,7 @@ function formatTextValue(
   depth = 0,
   width: number | null = null,
 ): string {
-  const missing = context === "record" ? cliStyles.muted("-") : "";
+  const missing = context === "record" ? cliPlainEnabled() ? "—" : cliStyles.muted("-") : "";
   if (value == null || value === "") return missing;
   // Times print in UTC with the zone named, never in the host's zone; JSON and CSV keep the raw value.
   if (value instanceof Date) return formatUtcTime(value);
@@ -284,23 +323,69 @@ function serializeColumns<Row>(columns?: CliResultColumn<Row>[]) {
   }));
 }
 
+/** A number a spreadsheet cannot read: NaN or an infinity, which exports write empty, never as the word. */
+function isNonFiniteNumber(value: unknown): boolean {
+  return typeof value === "number" && !Number.isFinite(value);
+}
+
+/**
+ * What a row's status cell says: the command's reason, else the figures
+ * written empty for being no number. Empty when nothing is missing.
+ */
+function exportStatusText(reason: string | null | undefined, blanked: readonly string[]): string {
+  const own = reason?.trim();
+  if (own) return own;
+  return blanked.length > 0 ? `${blanked.join(", ")}: not available` : "";
+}
+
+/** `status`, or `value_status` beside a column of the table's own named Status. */
+function statusHeader(headers: readonly string[]): string {
+  return headers.some((header) => header.trim().toLowerCase() === "status") ? "value_status" : "status";
+}
+
 function renderCsv<Row extends Record<string, unknown>>(
   rows: Row[],
   columns?: CliResultColumn<Row>[],
   identity?: (row: Row) => string[],
+  status?: (row: Row) => string | null | undefined,
 ): string {
   const resolvedColumns = columns && columns.length > 0
     ? columns
     : inferColumns(rows as Record<string, unknown>[]) as CliResultColumn<Row>[];
+  const headers = resolvedColumns.map((column) => column.header);
   return serializeCsv([
-    [...resolvedColumns.map((column) => column.header), ...identity ? EXPORT_IDENTITY_COLUMNS : []],
-    ...rows.map((row) => [
-      ...resolvedColumns.map((column) => (column.value ? column.value(row) : row[column.key])),
-      ...identity?.(row) ?? [],
-    ]),
+    [...headers, ...status ? [statusHeader(headers)] : [], ...identity ? EXPORT_IDENTITY_COLUMNS : []],
+    ...rows.map((row) => {
+      const values = resolvedColumns.map((column) => (column.value ? column.value(row) : row[column.key]));
+      const blanked = resolvedColumns.flatMap((column, index) => isNonFiniteNumber(values[index]) ? [column.header] : []);
+      return [
+        ...values.map((value) => isNonFiniteNumber(value) ? "" : value),
+        ...status ? [exportStatusText(status(row), blanked)] : [],
+        ...identity?.(row) ?? [],
+      ];
+    }),
   ]);
 }
 
+/**
+ * The key an NDJSON row says why its figures are empty under: `status`, or
+ * `value_status` beside a field of the row's own that the export writes under
+ * that name (an order's status), as CSV's header does.
+ */
+function ndjsonStatusKey(rows: readonly unknown[], columns?: readonly CliResultColumn<never>[]): string {
+  const own = columns && columns.length > 0
+    ? columns.some((column) => column.key === "status")
+    : rows.some((row) => isPlainObject(row) && "status" in row);
+  return own ? "value_status" : "status";
+}
+
+/** An NDJSON row: a figure that is no number is null, and the row says why its figures are empty when the command does. */
+function ndjsonRow<Row extends Record<string, unknown>>(row: Row, status: ((row: Row) => string | null | undefined) | undefined, statusKey: string): Record<string, unknown> {
+  const blanked = Object.entries(row).flatMap(([key, value]) => isNonFiniteNumber(value) ? [key] : []);
+  const own = blanked.length > 0 ? { ...row, ...Object.fromEntries(blanked.map((key) => [key, null])) } : row;
+  return status ? { ...own, [statusKey]: exportStatusText(status(row), blanked) || null } : own;
+}
+
 function stringField(row: Record<string, unknown>, key: string): string | null {
   const value = row?.[key];
   return typeof value === "string" && value.trim() ? value : null;
@@ -341,10 +426,11 @@ function renderTextTable<Row extends Record<string, unknown>>(
 ): string {
   const resolvedColumns = textColumns(rows, columns);
   const cells = rows.map((row) => resolvedColumns.map((column) => formatTextCell(column, row, "table")));
-  // A column no row fills is noise in a table; exports keep it.
+  // A column no row fills is noise in a table; exports keep it, and so does plain output, whose
+  // tables keep one shape from query to query with "—" in the empty cells.
   const filled = resolvedColumns
     .map((column, index) => ({ column, index }))
-    .filter(({ column, index }) => column.width != null || cells.some((row) => row[index] !== ""));
+    .filter(({ column, index }) => cliPlainEnabled() || column.width != null || cells.some((row) => row[index] !== ""));
   const shown = filled.length > 0 ? filled : resolvedColumns.map((column, index) => ({ column, index }));
   return renderTable(
     shown.map(({ column }) => ({
@@ -388,9 +474,13 @@ function overflowsTerminal<Row extends Record<string, unknown>>(rows: Row[]): bo
   return width > terminalWidth;
 }
 
-/** The closing source, as-of and status line of a text result, for output printed without `printResult`. */
-export function cliFreshnessFooter(freshness: ReportFreshness): string {
-  return cliStyles.muted(wrapToTerminal(formatFreshnessLine(freshness)));
+/**
+ * The closing source, as-of and status line of a text result, for output
+ * printed without `printResult`; `shown` is the data the line is drawn from,
+ * which says whether it came from a saved copy.
+ */
+export function cliFreshnessFooter(freshness: ReportFreshness, shown?: unknown): string {
+  return cliStyles.muted(wrapToTerminal(formatFreshnessLine(withSavedCopy(freshness, shown))));
 }
 
 export function serializeCliResult<T, Row extends Record<string, unknown> = Record<string, unknown>>(
@@ -398,14 +488,17 @@ export function serializeCliResult<T, Row extends Record<string, unknown> = Reco
   options: CliGlobalOptions,
   renderOptions: CliResultRenderOptions<T, Row> = {},
 ): string {
-  const { freshness, exportFreshness, ...rest } = result;
-  const cited = freshness ?? exportFreshness;
+  const { freshness: reported, exportFreshness, failure, ...rest } = result;
+  // Rows shown from a saved copy, its refresh having failed, say so in place of live or delayed.
+  const freshness = reported && withSavedCopy(reported, result.data);
+  const cited = freshness ?? (exportFreshness && withSavedCopy(exportFreshness, result.data));
   if (options.format === "json") {
     const columns = serializeColumns(renderOptions.columns);
     const window = Array.isArray(result.data) ? windowed(result.data as unknown[], options, renderOptions) : null;
     const cut = window ? cutMetadata(window) : null;
     const envelope: CliResultJsonEnvelope<T> = {
-      ok: true,
+      ok: !failure,
+      ...(failure ? { error: failure } : {}),
       ...rest,
       ...(freshness || cut ? { metadata: { ...rest.metadata, ...(freshness ? { freshness } : {}), ...(cut ? { rows: cut } : {}) } } : {}),
       data: window ? window.rows as T : result.data,
@@ -435,14 +528,18 @@ function serializeCliRows<T, Row extends Record<string, unknown>>(
   }
   const window = windowed(asRows(result.data, renderOptions.rows), options, renderOptions);
   const rows = window.rows;
+  const status = renderOptions.exportStatus;
   if (options.format === "ndjson") {
-    return rows.map((row) => JSON.stringify(cited && isPlainObject(row)
-      ? { ...row, ...exportIdentityFields(cited, rowIdentity(row as Row, renderOptions.exportIdentity)) }
-      : row)).join("\n");
+    const statusKey = ndjsonStatusKey(rows, renderOptions.columns as readonly CliResultColumn<never>[] | undefined);
+    return rows.map((row) => {
+      if (!isPlainObject(row)) return JSON.stringify(row);
+      const fields = ndjsonRow(row as Row, status, statusKey);
+      return JSON.stringify(cited ? { ...fields, ...exportIdentityFields(cited, rowIdentity(row as Row, renderOptions.exportIdentity)) } : fields);
+    }).join("\n");
   }
   if (options.format === "csv") {
-    if (!cited) return renderCsv(rows as Row[], renderOptions.columns);
-    const csv = renderCsv(rows as Row[], renderOptions.columns, (row) => exportIdentityCells(cited, rowIdentity(row, renderOptions.exportIdentity)));
+    if (!cited) return renderCsv(rows as Row[], renderOptions.columns, undefined, status);
+    const csv = renderCsv(rows as Row[], renderOptions.columns, (row) => exportIdentityCells(cited, rowIdentity(row, renderOptions.exportIdentity)), status);
     return withCsvFooter(csv, [...exportSourceLines(cited), ...(renderOptions.exportNotes ?? []).map((note) => `note: ${note}`)]);
   }
   if (renderOptions.text) {