@gloom-sh/terminal 0.19.2 → 0.19.3

package/src/cli/earnings-calendar.ts

@@ -42,6 +42,15 @@ export async function noListingCalendarNote(
   return `${lead}; ADR date ${isoDate(event.earningsDate)} (estimate)`;
 }
 
+/**
+ * "BG, FPI: no earnings date found." for the listings at home a calendar came
+ * back without, each named once; null when it dated them all.
+ */
+export function undatedListingsNote(listings: readonly Pick<CliListing, "key">[]): string | null {
+  const keys = [...new Set(listings.map((listing) => listing.key))];
+  return keys.length > 0 ? `${keys.join(", ")}: no earnings date found.` : null;
+}
+
 /**
  * "SAN = Banco Santander, NYSE (different companies on EPA, LSE)" for a bare symbol whose
  * calendar date is its US line's, when several companies list the symbol:

package/src/cli/entry.ts

@@ -1,12 +1,10 @@
 import "./opentui-libc";
 import { inferCliErrorOptions, printCliError } from "./errors";
 import { isCliHelpFlag } from "./options";
-import { plainByDefault, setCliPlainOverride } from "../utils/cli-output";
-import { loadExternalPlugins } from "../plugins/loader";
-import { restoreExtractedPlugins } from "./restore-plugins";
+import { cliAsciiEnabled, plainByDefault, setCliPlainOverride } from "../utils/cli-output";
+import { localeMayNotReadUtf8 } from "../utils/ascii-text";
+import { writeAsciiWhile } from "./ascii-output";
 import { measurePerfAsync } from "../utils/perf-marks";
-import { flushCrashReports, reportCrash } from "../telemetry/crash-reports";
-import { CRASH_REPORT_EXIT_FLUSH_MS } from "../telemetry/crash-reports-node";
 import type { CliLaunchRequest } from "../types/plugin";
 import { detectUpdateAction } from "../updater";
 import { linkStandaloneCommand } from "../updater/command-names";
@@ -24,6 +22,8 @@ import {
 async function launchOpenTuiApp(cliLaunchRequest: CliLaunchRequest | null = null): Promise<void> {
   // Before anything in the app can reach for the render library, so a temp
   // folder that cannot run it is worked around (or named) first.
+  const { restoreExtractedPlugins } = await import("./restore-plugins");
+  const { loadExternalPlugins } = await import("../plugins/loader");
   const { loadRenderLib } = await import("../renderers/opentui/render-lib");
   await measurePerfAsync("startup.opentui.render-lib", loadRenderLib);
   const { startOpenTuiApp } = await import("../renderers/opentui/start");
@@ -36,6 +36,8 @@ async function launchOpenTuiApp(cliLaunchRequest: CliLaunchRequest | null = null
   } catch (error) {
     // A failed launch still prints and exits as before; the report is only
     // sent when the config was read far enough to install the reporter.
+    const { flushCrashReports, reportCrash } = await import("../telemetry/crash-reports");
+    const { CRASH_REPORT_EXIT_FLUSH_MS } = await import("../telemetry/crash-reports-node");
     reportCrash(error, { kind: "uncaught" });
     await flushCrashReports({ timeoutMs: CRASH_REPORT_EXIT_FLUSH_MS });
     throw error;
@@ -74,21 +76,25 @@ export async function runCliEntrypoint(rawArgs = process.argv.slice(2)): Promise
     return;
   }
 
-  // Loaded only for a command: a bare launch never reads the commands, and
-  // their modules are a noticeable part of what it would load before drawing.
-  const { dispatchCli, failUnknownCliCommand } = await import("./index");
-  // For a screen reader, a pipe or NO_COLOR: no rule lines, arrows in words, fixed table columns. Set
-  // for this process only; `--plain` / `--no-plain` decide it in dispatchCli, and commands run in-process keep theirs.
+  // For a screen reader, a pipe or NO_COLOR: no rule lines, arrows in words, fixed table columns.
   setCliPlainOverride(plainByDefault());
-  const externalPlugins = await loadExternalPlugins();
-  const dispatchResult = await dispatchCli(rawArgs, { externalPlugins });
+  if (inferCliErrorOptions(rawArgs).format === "text" && localeMayNotReadUtf8()) writeAsciiWhile(cliAsciiEnabled);
+  const { dispatchEarlyCommand } = await import("./early-command");
+  if (await dispatchEarlyCommand(rawArgs)) return;
+
+  const { dispatchCli, failUnknownCliCommand } = await import("./index");
+  let plugins: Promise<import("../plugins/loader").LoadedExternalPlugin[]> | undefined;
+  const options = {
+    loadExternalPlugins: () => plugins ??= import("../plugins/loader").then(({ loadExternalPlugins }) => loadExternalPlugins()),
+  };
+  const dispatchResult = await dispatchCli(rawArgs, options);
   if (dispatchResult.kind === "handled") return;
   if (dispatchResult.kind === "launch-ui") {
     await launchOpenTuiApp(dispatchResult.request);
     return;
   }
 
-  await failUnknownCliCommand(rawArgs, { externalPlugins });
+  await failUnknownCliCommand(rawArgs, options);
 }
 
 runCliEntrypoint().catch((error) => {

package/src/cli/errors.ts

@@ -1,10 +1,10 @@
 import type { AppPersistence } from "../data/app-persistence";
-import { ApiRequestError } from "../api-client/errors";
+import { ApiRequestError, wasAskedTwice } from "../api-client/errors";
 import { DEFAULT_CLI_OPTIONS, type CliGlobalOptions } from "./options";
 import { serializeCliError, type CliErrorObject } from "./result";
 import { cliStyles, cliTerminalWidth, wrapText } from "../utils/cli-output";
 import { withSearchHints, type FredSeriesCheck } from "./not-a-ticker";
-import { isProviderBusy, SEARCH_BUSY_CODE, SEARCH_BUSY_MESSAGE } from "../sources/provider-errors";
+import { isProviderBusy, isSourceFailure, SEARCH_BUSY_CODE, SEARCH_BUSY_MESSAGE, serviceDidNotAnswerMessage } from "../sources/provider-errors";
 import { DATA_SERVICE_UNREACHABLE_MESSAGE, isNetworkFailure } from "../utils/network-failure";
 
 const USAGE_PREFIX = "Usage: ";
@@ -14,6 +14,8 @@ export const CLI_ERROR_CODE = "cli_error";
 export const NO_DATA_CODE = "no_data";
 /** The code of a command whose requests never reached the data service. */
 const SERVICE_UNREACHABLE_CODE = "service_unreachable";
+/** The code of a command whose data no source could serve just now, one having failed rather than had none. */
+const SOURCE_UNAVAILABLE_CODE = "source_unavailable";
 
 /** What to check when nothing answered: the connection, and the proxy when one is set. */
 function unreachableHint(): string {
@@ -121,6 +123,14 @@ function cliErrorObject(error: unknown): CliErrorObject {
   if (isNetworkFailure(error)) {
     return unreachableError();
   }
+  // A source failed (a timeout, a rate limit) where none had the data to answer: asked again it may.
+  if (isSourceFailure(error)) {
+    return { code: SOURCE_UNAVAILABLE_CODE, message: error instanceof Error ? error.message : String(error), retryable: true };
+  }
+  // A listing read the data service failed to answer twice: said in Gloom's words. Any other 5xx keeps the server's.
+  if (wasAskedTwice(error)) {
+    return { code: SOURCE_UNAVAILABLE_CODE, message: serviceDidNotAnswerMessage(), retryable: true };
+  }
   // Gloom Cloud refused what was asked (an unknown series, a bad date): the input was wrong, not the program.
   if (error instanceof ApiRequestError && error.status === 400) {
     return { code: CLI_ERROR_CODE, message: error.message };

package/src/cli/help.ts

@@ -54,7 +54,7 @@ const GLOBAL_OPTIONS: Array<[string, string]> = [
   ["-q, --quiet", "Print no results or errors in text mode, for commands that print results"],
   ["--color, --no-color", "Force or turn off colors (NO_COLOR also turns them off)"],
   ["--plain, --no-plain", "Plain text for a screen reader or large text: no rule lines, arrows as words, every table column kept with a dash in empty cells. On by default when NO_COLOR is set or output is piped; --no-plain turns it off"],
-  ["--width <n>", "Fit tables to n columns (default: the terminal width; piped output is not fitted). shot takes its own --width in pixels"],
+  ["--width <n>", "Fit tables to n columns (default: the terminal width; piped output fits COLUMNS when set, else is not fitted). shot takes its own --width in pixels"],
 ];
 
 const EXIT_CODES: Array<[string, string]> = [

package/src/cli/history-export.ts

@@ -21,7 +21,7 @@ export interface HistoryListRow extends HistoryRow {
 type ExportedRow = Record<string, unknown>;
 
 /** A bar's mark as an export writes it: true or false on a bar, nothing on a symbol's row with no bar. */
-function barMark(key: "partial" | "filled" | "unsettled") {
+function barMark(key: "partial" | "filled" | "unsettled" | "roll" | "thin") {
   return (row: ExportedRow) => row.date ? row[key] === true : "";
 }
 
@@ -32,7 +32,7 @@ function barMark(key: "partial" | "filled" | "unsettled") {
  * whether or not any bar of this run has one, so files of different symbols
  * or days line up when joined.
  */
-export const HISTORY_EXPORT_COLUMNS: CliResultColumn<ExportedRow>[] = [
+const HISTORY_EXPORT_COLUMNS: CliResultColumn<ExportedRow>[] = [
   { key: "date", header: "Date" },
   { key: "open", header: "Open" },
   { key: "high", header: "High" },
@@ -47,8 +47,28 @@ export const HISTORY_EXPORT_COLUMNS: CliResultColumn<ExportedRow>[] = [
   { key: "volumeNote", header: "Volume note" },
   { key: "venueVolume", header: "Venue volume" },
   { key: "volumeVenue", header: "Volume venue" },
+  { key: "volumeBasis", header: "Volume basis" },
 ];
 
+/** A continuous future's contract per bar, the bar it rolled at, and a bar that traded far below those around it. */
+const CONTRACT_EXPORT_COLUMNS: CliResultColumn<ExportedRow>[] = [
+  { key: "contract", header: "Contract" },
+  { key: "roll", header: "Roll", value: barMark("roll") },
+  { key: "thin", header: "Thin", value: barMark("thin") },
+];
+
+/**
+ * The columns of an export of these rows: HISTORY_EXPORT_COLUMNS, and when a
+ * bar names its contract (a continuous future such as NG=F) Contract, Roll and
+ * Thin after them, for every row of the export. A stock's or a coin's file is
+ * as it always was.
+ */
+export function historyExportColumns(rows: readonly Pick<HistoryRow, "contract">[]): CliResultColumn<ExportedRow>[] {
+  return rows.some((row) => typeof row.contract === "string" && row.contract !== "")
+    ? [...HISTORY_EXPORT_COLUMNS, ...CONTRACT_EXPORT_COLUMNS]
+    : HISTORY_EXPORT_COLUMNS;
+}
+
 /** Flags of a break before a bar, whose prices stay; every other code left the prices blank. */
 const BREAK_FLAGS = new Set(["gap", "jump"]);
 

package/src/cli/history-rows.ts

@@ -18,6 +18,7 @@ import {
   isWickFlag, latestTradeIndex, missingVolumeNotice, pricePointIntegrityFlags, pricePointValues, pricePointWickFlags,
 } from "../utils/price-history-integrity";
 import { formatUtcTime } from "../utils/utc-time";
+import { maxDrawdown, type MaxDrawdown } from "../utils/max-drawdown";
 import { historyCoverageNotice } from "../sources/history-coverage";
 import { barLastSession, barPeriodToDate, type BarPeriodToDate } from "../market-data/market/bar-period";
 import { barSizeFromGap, medianBarGap } from "../time-series/bar-spacing";
@@ -81,6 +82,17 @@ export interface HistoryRow {
   /** A bar without the market's volume: the trades of one venue alone (`volumeVenue`), never its volume. */
   venueVolume?: number;
   volumeVenue?: string;
+  /**
+   * What the bar's volume counts, where the source says: `aggregate` across venues on a coin's daily bar,
+   * `3 spot venues` on its intraday bar, whose volume is summed over those venues.
+   */
+  volumeBasis?: string;
+  /** A continuous future's bar (NG=F): the contract it closes on (NGZ26), where the source says. */
+  contract?: string;
+  /** The first bar on a contract after another's: the series rolled into `contract` at this bar. */
+  roll?: true;
+  /** The bar traded far below the bars around it (THIN_VOLUME_SHARE of their median): a price on few trades. */
+  thin?: true;
 }
 
 /** A coin's volume: traded value in its quote currency, per UTC day on daily bars. */
@@ -306,6 +318,7 @@ export function historyRows(
       ...(values.volume == null && point.venueVolume
         ? { venueVolume: point.venueVolume.volume, volumeVenue: point.venueVolume.venue }
         : {}),
+      ...(values.volume != null && point.volumeBasis ? { volumeBasis: point.volumeBasis } : {}),
       // A coin trades every day, so a bar without volume says why.
       ...(volume && values.volume == null
         ? {
@@ -316,12 +329,136 @@ export function historyRows(
     };
   });
   const breaks = historyBreakFlags(times, rows.map((row) => row.close), interval);
+  const thin = thinVolumeBars(rows.map((row, index) => ({ ...row, contract: points[index]!.contract })));
+  let contract: string | null = null;
   return rows.map((row, index) => {
     const flags = [...flagCodes(row), ...breaks[index]!];
-    return flags.length > 0 ? { ...row, flag: flags.join(",") } : row;
+    const own = points[index]!.contract;
+    // A roll is a change between two known contracts; a bar naming none (before the source knew) is no roll.
+    const rolled = !!own && contract != null && own !== contract;
+    if (own) contract = own;
+    const marked = {
+      ...row,
+      ...(own ? { contract: own } : {}),
+      ...(rolled ? { roll: true as const } : {}),
+      ...(thin[index] ? { thin: true as const } : {}),
+    };
+    return flags.length > 0 ? { ...marked, flag: flags.join(",") } : marked;
   });
 }
 
+/** Bars on each side of a bar whose volumes it is held against. */
+const THIN_NEIGHBOURS = 5;
+/** A bar under this share of its neighbours' median volume traded thin. */
+const THIN_VOLUME_SHARE = 0.05;
+
+/**
+ * For each bar of a continuous future, whether it traded far below the bars
+ * around it: a volume under THIN_VOLUME_SHARE of the median of up to
+ * THIN_NEIGHBOURS bars either side that have one (at least four). NG=F's
+ * 2026-10-28 bar on 15 lots between days of 150,000 is a price few trades
+ * made. Only a bar naming its contract is judged, against others that do: a
+ * stock's or a coin's quiet day is not a contract's thin one. A bar still
+ * forming, or with no trade at all (no volume, or 0), is not judged.
+ */
+function thinVolumeBars(rows: readonly (Pick<HistoryRow, "volume" | "partial"> & { contract?: string })[]): boolean[] {
+  const judged = (row: (typeof rows)[number]): row is (typeof rows)[number] & { volume: number } =>
+    !!row.contract && !row.partial && row.volume != null && Number.isFinite(row.volume) && row.volume > 0;
+  return rows.map((row, index) => {
+    if (!judged(row)) return false;
+    const around = [...rows.slice(Math.max(0, index - THIN_NEIGHBOURS), index), ...rows.slice(index + 1, index + 1 + THIN_NEIGHBOURS)]
+      .filter(judged)
+      .map((other) => other.volume)
+      .sort((left, right) => left - right);
+    if (around.length < 4) return false;
+    const middle = around.length / 2;
+    const median = around.length % 2 ? around[Math.floor(middle)]! : (around[middle - 1]! + around[middle]!) / 2;
+    return median > 0 && row.volume < THIN_VOLUME_SHARE * median;
+  });
+}
+
+/** A roll of a continuous future: the bar it rolled at, and the contracts either side. */
+interface HistoryRoll {
+  date: string;
+  from: string;
+  to: string;
+}
+
+/** Every roll in a history's bars (`roll`), oldest first. */
+function historyRolls(rows: readonly Pick<HistoryRow, "date" | "contract" | "roll">[]): HistoryRoll[] {
+  let contract: string | null = null;
+  const rolls: HistoryRoll[] = [];
+  for (const row of rows) {
+    if (row.roll && contract && row.contract) rolls.push({ date: row.date, from: contract, to: row.contract });
+    if (row.contract) contract = row.contract;
+  }
+  return rolls;
+}
+
+/**
+ * A history's bars split at every roll, each run one contract's, oldest
+ * first: what a drawdown or a change is read within, never across a roll.
+ * One run, named by no contract, for a history that names none.
+ */
+function historyContractRuns<Row extends Pick<HistoryRow, "contract" | "roll">>(rows: readonly Row[]): Array<{ contract: string | null; rows: Row[] }> {
+  const runs: Array<{ contract: string | null; rows: Row[] }> = [];
+  for (const row of rows) {
+    const current = runs.at(-1);
+    if (!current || row.roll) runs.push({ contract: row.contract ?? null, rows: [row] });
+    else {
+      current.rows.push(row);
+      current.contract ??= row.contract ?? null;
+    }
+  }
+  return runs;
+}
+
+/**
+ * The largest drawdown of a history's bars within one contract: each run
+ * between rolls read on its own (historyContractRuns), the deepest kept and
+ * named by its contract when the bars roll. A history naming no contract is
+ * one run, its drawdown `maxDrawdown`'s.
+ */
+export function historyContractDrawdown(
+  rows: readonly Pick<HistoryRow, "date" | "close" | "contract" | "roll">[],
+): { drawdown: MaxDrawdown; contract: string | null } | null {
+  const runs = historyContractRuns(rows);
+  let deepest: { drawdown: MaxDrawdown; contract: string | null } | null = null;
+  for (const run of runs) {
+    const drawdown = maxDrawdown(run.rows);
+    if (drawdown && (!deepest || drawdown.drawdown < deepest.drawdown.drawdown)) deepest = { drawdown, contract: runs.length > 1 ? run.contract : null };
+  }
+  return deepest;
+}
+
+/**
+ * "NG=F is the front month: rolled from NGX26 to NGZ26 on 2026-10-26 (marked
+ * roll)": the rolls a continuous future's bars make, the latest few by date,
+ * the rest counted. Null without one.
+ */
+export function historyRollNote(symbol: string, rows: readonly Pick<HistoryRow, "date" | "contract" | "roll">[]): string | null {
+  const rolls = historyRolls(rows);
+  if (rolls.length === 0) return null;
+  const shown = rolls.slice(-LISTED_GAPS);
+  const earlier = rolls.length - shown.length;
+  const listed = shown.map((roll) => `from ${roll.from} to ${roll.to} on ${historyDate(roll.date)}`);
+  return `${symbol} is the front month: ${earlier > 0 ? `${earlier} earlier ${earlier === 1 ? "roll" : "rolls"}, then ` : ""}`
+    + `rolled ${listItems(listed)} (marked roll); drawdowns are read within one contract`;
+}
+
+/**
+ * "2026-10-28 traded thin: under 5% of the volume of the bars around it", the
+ * bars marked `thin`, the latest few by date. Null without one.
+ */
+export function historyThinNote(rows: readonly Pick<HistoryRow, "date" | "thin">[]): string | null {
+  const thin = rows.filter((row) => row.thin).map((row) => historyDate(row.date));
+  if (thin.length === 0) return null;
+  const shown = thin.slice(-LISTED_GAPS);
+  const earlier = thin.length - shown.length;
+  const dates = listItems([...earlier > 0 ? [`${earlier} earlier ${earlier === 1 ? "bar" : "bars"}`] : [], ...shown]);
+  return `${dates} traded thin: under ${THIN_VOLUME_SHARE * 100}% of the volume of the bars around ${thin.length === 1 ? "it" : "them"}`;
+}
+
 /**
  * The newest weekly or monthly bar while its period has not ended at `now`
  * (barPeriodToDate): marked `partial`, as a bar its source marks is, with
@@ -369,9 +506,22 @@ export function historyVolume(
   return coin && unit.kind === "currency" && unit.currency ? { unit: unit.currency } : null;
 }
 
-/** `volume in USD per UTC day` for a coin's daily bars; `volume in USD` for others. */
-export function historyVolumeText(volume: HistoryVolume, interval: ManualChartResolution | null): string {
-  return interval === "1d" ? `volume in ${volume.unit} per UTC day` : `volume in ${volume.unit}`;
+/**
+ * `volume in USD per UTC day` for a coin's daily bars, `volume in USD` for others, with what it counts when every bar
+ * with a volume says the same (`historyVolumeBasis`): `volume in USD per UTC day, aggregate across venues`, `volume in
+ * USD summed over 3 spot venues`.
+ */
+export function historyVolumeText(volume: HistoryVolume, interval: ManualChartResolution | null, basis: string | null = null): string {
+  const text = interval === "1d" ? `volume in ${volume.unit} per UTC day` : `volume in ${volume.unit}`;
+  if (!basis) return text;
+  return basis === "aggregate" ? `${text}, aggregate across venues` : `${text} summed over ${basis}`;
+}
+
+/** What the volume of every bar that has one counts, when they all say the same; null otherwise. */
+export function historyVolumeBasis(rows: readonly Pick<HistoryRow, "volume" | "volumeBasis">[]): string | null {
+  const bases = new Set(rows.filter((row) => row.volume != null).map((row) => row.volumeBasis ?? null));
+  const [basis] = bases.size === 1 ? [...bases] : [null];
+  return basis ?? null;
 }
 
 function listDates(dates: readonly string[]): string {

package/src/cli/index.ts

@@ -408,6 +408,7 @@ const CLI_DESCRIPTION = "Market research and portfolio tracker for the terminal"
 
 export interface DispatchCliOptions {
   externalPlugins?: LoadedExternalPlugin[];
+  loadExternalPlugins?: () => Promise<LoadedExternalPlugin[]>;
 }
 
 /** Old names kept so existing scripts still run; help and suggestions leave them out. */
@@ -430,6 +431,7 @@ async function createRegistry(options: DispatchCliOptions = {}): Promise<CliComm
   registry = buildCliCommandRegistry({
     coreCommands,
     externalPlugins: options.externalPlugins ?? [],
+    ...(options.externalPlugins === undefined ? { loadExternalPlugins: options.loadExternalPlugins } : {}),
     config,
   });
   return registry;
@@ -456,11 +458,25 @@ export async function dispatchCli(args: string[], options: DispatchCliOptions =
   }
 
   const registry = await createRegistry(options);
-  const resolved = registry.lookup.get(normalizeCliCommandToken(foldTypedText(command)));
+  const token = normalizeCliCommandToken(foldTypedText(command));
+  let resolved = registry.lookup.get(token);
+  if (!resolved) {
+    await registry.ensureExternalPlugins?.();
+    resolved = registry.lookup.get(token);
+  }
   if (!resolved) {
     return { kind: "unhandled" };
   }
 
+  // The overview includes installed commands; one built-in command's help only
+  // needs that command. An unknown help topic may belong to an installed plugin.
+  if (resolved.command.name === "help") {
+    const topic = parsed.args[1];
+    if (!topic || !registry.lookup.has(normalizeCliCommandToken(foldTypedText(topic)))) {
+      await registry.ensureExternalPlugins?.();
+    }
+  }
+
   // Help flags never reach the command, where they would read as a symbol, a
   // plugin name, or a note to write.
   const helpOnly = parsed.help && resolved.command.name !== "help";
@@ -500,6 +516,7 @@ export async function failUnknownCliCommand(args: string[], options: DispatchCli
     // Intentional ignore: dispatchCli already reports invalid flags.
   }
   const registry = await createRegistry(options);
+  await registry.ensureExternalPlugins?.();
   const commands = listedCommands(registry).map((entry) => entry.command);
   // A function's code typed as a command is pointed at `fn`, and a word the catalog knows at its
   // functions, with the arguments the reader gave.

package/src/cli/known-gaps.ts

@@ -87,8 +87,15 @@ export const MUNI_LINE = "Municipal bonds: no AAA muni curve (MMD and BVAL are l
  * `tickers` are terms that are also a real ticker (BDI is Black Diamond Group):
  * a query that is only that word still gets the line, but `quote` adds it only
  * to the exchange question or the failure of the bare symbol, never to a quote.
+ *
+ * An entry with `words` matches on tokens, not only the whole query: a query
+ * holding one of its terms, every other word a term or one of `words`
+ * ("panamax rates", "bulk freight", "freight cost"). A word outside both keeps
+ * it a different question ("freight forwarder stocks", "ocean freight
+ * carriers"). An entry without `words` matches the whole query alone, since
+ * its terms are words of company names too ("carbon", "second").
  */
-const KNOWN_GAPS: ReadonlyArray<{ terms: readonly string[]; tickers?: readonly string[]; message: string }> = [
+const KNOWN_GAPS: ReadonlyArray<{ terms: readonly string[]; words?: readonly string[]; tickers?: readonly string[]; message: string }> = [
   {
     terms: ["EUA", "EUAs", "EU ETS", "EU allowance", "EU allowances", "EU carbon", "carbon", "carbon allowance", "carbon allowances",
       "carbon price", "carbon prices", "carbon credits", "emission allowances", "emissions allowances"],
@@ -107,8 +114,12 @@ const KNOWN_GAPS: ReadonlyArray<{ terms: readonly string[]; tickers?: readonly s
   {
     terms: ["Baltic", "Baltic Dry", "Baltic Dry Index", "Baltic Exchange", "Baltic index", "Baltic indices", "BDI", "BDIY", "freight",
       "freight rate", "freight rates", "freight index", "freight futures", "freight forward", "freight forwards", "freight forward agreement",
-      "freight forward agreements", "FFA", "FFAs", "capesize", "panamax", "supramax", "charter rate", "charter rates", "dry bulk",
-      "dry bulk rates", "dry bulk freight"],
+      "freight forward agreements", "FFA", "FFAs", "capesize", "panamax", "supramax", "handysize", "kamsarmax", "newcastlemax",
+      "charter rate", "charter rates", "dry bulk", "dry bulk rates", "dry bulk freight", "shipping rate", "shipping rates", "shipping cost",
+      "shipping costs", "time charter", "TCE"],
+    words: ["rate", "rates", "cost", "costs", "price", "prices", "index", "indices", "indexes", "level", "levels", "chart", "charts",
+      "history", "historical", "data", "spot", "today", "current", "latest", "daily", "weekly", "market", "markets", "bulk", "dry",
+      "bulker", "bulkers", "vessel", "vessels", "ship", "ships", "route", "routes", "earnings", "equivalent", "futures", "the", "of", "for"],
     tickers: ["BDI"],
     message: "Baltic indices (BDI, Capesize, Panamax, Supramax) and freight forwards (FFA) are not covered. Traded proxies: BDRY (freight futures ETF), "
       + "SBLK, GNK, DSX (dry-bulk shipowners); chokepoint transits: fn CHOKE; news \"dry bulk\".",
@@ -326,6 +337,14 @@ const COMMAND_POINTERS: ReadonlyArray<{
       "change", "ranking", "rankings", "dashboard", "lending", "staking"],
     line: "DeFi TVL, top protocols and chains with 7D and 30D change: gloom fn CRYP --list defi (by chain: --by chain)",
   },
+  {
+    // Ahead of DIST, which "difficulty" finds by its description; the four series are listed after it.
+    names: ["hashrate", "hash rate", "hashprice", "hash price", "difficulty", "retarget", "mining", "miner", "miners"],
+    words: ["bitcoin", "btc", "network", "crypto", "stock", "stocks", "equities", "listed", "next",
+      "estimate", "adjustment", "chart", "history"],
+    line: "Bitcoin network: gloom fn G hashrate, difficulty or hashprice; listed miners: gloom fn THEM crypto",
+    leads: true,
+  },
 ];
 
 /** The command for a query that names a setting ("light theme") or a portfolio report ("drip"), else null. */
@@ -398,7 +417,23 @@ export function knownGapForTicker(symbol: string): string | null {
 }
 
 /**
- * The line for a query that names a known subject as a whole ("carbon allowances", "EUA"), a Treasury yield
+ * Whether a query names a known subject: as a whole ("Baltic Dry", "dry-bulk"), or, for an entry with `words`,
+ * by a term among words that only qualify it ("panamax rates", "bulk freight").
+ */
+function namesKnownGap(gap: (typeof KNOWN_GAPS)[number], query: string): boolean {
+  const key = lookupKey(query);
+  if (gap.terms.some((term) => lookupKey(term) === key)) return true;
+  if (!gap.words) return false;
+  const asked = words(query);
+  const named = new Set(gap.terms.flatMap((term) => {
+    const parts = words(term);
+    return containsWords(asked, parts) ? parts : [];
+  }));
+  return named.size > 0 && asked.every((word) => named.has(word) || gap.words!.includes(word));
+}
+
+/**
+ * The line for a query that names a known subject ("carbon allowances", "EUA", "panamax rates"), a Treasury yield
  * typed as a ticker (US10Y), a topic with no function ("defense budget"), or a macro release no series carries
  * ("ISM manufacturing", "GDPNow"), else null.
  */
@@ -406,7 +441,7 @@ export function knownGapMessage(query: string): string | null {
   const key = lookupKey(query);
   if (!key) return null;
   const tenor = treasuryYieldTenor(query);
-  return KNOWN_GAPS.find((gap) => gap.terms.some((term) => lookupKey(term) === key))?.message
+  return KNOWN_GAPS.find((gap) => namesKnownGap(gap, query))?.message
     ?? (tenor ? treasuryYieldLine(tenor) : null)
     ?? topicPointer(query)?.message
     ?? macroReleaseTopic(query)?.line ?? null;

package/src/cli/listing-arg.ts

@@ -17,7 +17,7 @@ import {
 import { findUsListingOfCompany, type UsListing } from "../tickers/us-listing";
 import { findListingOfCompanyName, isCompanyNameInput, marksAnotherListing, readTerminalCodeArg, type CompanyNameListing } from "../tickers/company-name-listing";
 import { movedAwayChange, startTickerChangeLookup, type MovedTickerChange } from "../tickers/ticker-changes";
-import { lineMayHaveMoved, loadListingFate, MovedSymbolError, type ListingFate } from "../tickers/listing-fate";
+import { lineMayHaveMoved, listingChangeLine, loadListingFate, MovedSymbolError, SUCCESSOR_CHANGE_WAIT_MS, type ListingFate } from "../tickers/listing-fate";
 import { quotedListingName } from "../tickers/listing-name";
 import { cliStyles } from "../utils/cli-output";
 import { groupByCompany, namesDepositaryReceipt, sameCompany, sameListedName, shortCompanyName } from "../tickers/company-name";
@@ -25,6 +25,7 @@ import {
   canonicalExchange,
   exchangeCodeVenues,
   exchangeLabel,
+  exchangeName,
   isKnownExchangeCode,
   isSharedExchangeCode,
   isUsListingExchange,
@@ -36,7 +37,7 @@ import { withMarketData } from "./scoped-context";
 import { failWithFields } from "./errors";
 import { stripStrayEdges } from "./symbol-args";
 import { isNoProviderMessage, isNoSourceAnswer, isProviderBusy } from "../sources/provider-errors";
-import { dashedCoinPair, exchangeLineCoinListing, isSpotCommodityOrCurrencyPair, MAJOR_COIN_NAMES } from "../utils/crypto-pair";
+import { dashedCoinPair, exchangeLineCoinListing, isSpotCommodityOrCurrencyPair, MAJOR_COIN_NAMES, TOP_COIN_NAMES } from "../utils/crypto-pair";
 import { boardCoinFor, primeBoardCoins } from "./board-coins";
 import { knownGapMessage } from "./known-gaps";
 import { currencyPairSpelling } from "../utils/currency-pair";
@@ -60,7 +61,7 @@ import {
 import { listingAbroadVenue } from "../utils/sec";
 import { savedAbroadForBareSymbol, savedUsListingOf } from "../tickers/search/bare-symbol";
 import { listingSuffixCandidate, listingSuffixVenue, tickerHasListingSuffix } from "../sources/listing-symbols";
-import { notTheCoinNote } from "./commands/crypto-hints";
+import { coinElsewhereNote, notTheCoinNote } from "./commands/crypto-hints";
 
 /** The `--exchange` option of every command that takes a ticker. */
 export const EXCHANGE_OPTION = {
@@ -414,9 +415,15 @@ export function listingChoiceNote(
     .filter((exchange) => exchange !== chosen.exchange);
   if (others.length === 0) return null;
   const more = others.length - MAX_OTHER_LISTINGS;
-  const named = `${others.slice(0, MAX_OTHER_LISTINGS).join(", ")}${more > 0 ? ` and ${more} more: gloom search ${symbol}` : ""}`;
+  const named = `${others.slice(0, MAX_OTHER_LISTINGS).map(venueInProse).join(", ")}${more > 0 ? ` and ${more} more: gloom search ${symbol}` : ""}`;
   const which = others.length === 1 ? "a different company" : "different companies";
-  return `${symbol} = ${name ? `${shortCompanyName(name)}, ` : ""}${chosen.exchange} (${which} on ${named})`;
+  return `${symbol} = ${name ? `${shortCompanyName(name)}, ` : ""}${exchangeName(chosen.exchange)} (${which} on ${named})`;
+}
+
+/** A venue as a sentence names it, in full: "the Warsaw Stock Exchange", "Xetra", "NASDAQ" (a name that is its code). */
+function venueInProse(code: string): string {
+  const name = exchangeName(code);
+  return /\b(?:Exchange|Bourse|Market)$/.test(name) ? `the ${name}` : name;
 }
 
 // Quotes of these never name a company's listing, so they are never a choice between companies.
@@ -454,6 +461,19 @@ export function coinListingNotes(
   return note ? [note] : [];
 }
 
+/**
+ * `coinListingNotes` for each listing of a list (CORR RIOT,BTC), asked only
+ * of a bare top coin code, whose quote alone says whether it is the coin.
+ */
+export async function listCoinNotes(
+  listings: ReadonlyArray<Pick<CliListing, "symbol" | "exchange" | "request">>,
+  deps: Pick<ListingDeps, "dataProvider">,
+): Promise<string[]> {
+  const bare = listings.filter((listing) => !listing.exchange && TOP_COIN_NAMES.has(listing.symbol));
+  const quotes = await Promise.all(bare.map((listing) => loadListingQuote(deps.dataProvider, listing)));
+  return bare.flatMap((listing, index) => coinListingNotes(listing, quotes[index]));
+}
+
 /**
  * `listingChoiceNote` for a listing a command resolved, from the quote it was
  * read on: only a bare symbol went where the data service chose. A named
@@ -636,8 +656,12 @@ function describeOtherListings(
   // Every other listing was asked and had nothing: they are named as such, with nothing to try.
   const heading = choose ? "Listings" : lines.length === 0 ? `No ${request.noun} on its other listings either` : "Other listings";
   const named = lines.length === 0 ? without : offered;
-  const details = lines.length === 0 ? `${heading}: ${without.map((venue) => venueKey(listing.symbol, venue)).join(", ")}.`
+  const listed = lines.length === 0 ? `${heading}: ${without.map((venue) => venueKey(listing.symbol, venue)).join(", ")}.`
     : lines.length === 1 ? `${heading}: ${lines[0]}` : [`${heading}:`, ...lines.map((line) => `  ${line}`)].join("\n");
+  // A top coin's code (HYPE, SOL) none of the listings is: the coin may be what was meant.
+  const coin = coinElsewhereNote(listing.symbol, [...resolved ? [resolved] : [], ...others]
+    .map((venue) => ({ key: venueKey(listing.symbol, venue), name: venue.name })));
+  const details = coin ? `${listed}\n${coin}` : listed;
   return {
     // The symbol went to no venue, so none of them is said to lack the data.
     message: choose
@@ -786,6 +810,11 @@ export interface ReadListing {
   name: string | null;
   /** A bare coin ticker read as a listing that is not the coin (`coinListingNotes`); null otherwise. */
   coinNote: string | null;
+  /**
+   * What became of the company that had the symbol, as `quote` says it ("GOGL was Golden Ocean Group until
+   * 2025, now Cmb.Tech: CMBT"), when asked for (`successor`); null otherwise.
+   */
+  successorNote?: string | null;
 }
 
 /**
@@ -801,13 +830,19 @@ export async function readBareListing(
   symbol: string,
   deps: ListingDeps,
   request: ListingDataRequest,
-  { refresh = false }: { refresh?: boolean } = {},
+  /** `successor`: also say what became of the company that had the symbol, looked up beside its quote. */
+  { refresh = false, successor = false }: { refresh?: boolean; successor?: boolean } = {},
 ): Promise<ReadListing | null> {
   const listing = await resolveCliListing(symbol, null, deps);
   if (listing.exchange) return null;
+  const changes = successor ? startTickerChangeLookup(deps.dataProvider, listing.symbol, listing.exchange) : null;
   const answer = await loadListingQuoteAnswer(deps.dataProvider, listing);
   if (answer.quote) {
-    return { symbol: listing.symbol, exchange: listing.request.exchange, name: answer.quote.name?.trim() || null, coinNote: coinListingNotes(listing, answer.quote)[0] ?? null };
+    const successorNote = changes
+      ? listingChangeLine(await loadListingFate(listing, deps.dataProvider, { quote: answer.quote, changes, graceMs: SUCCESSOR_CHANGE_WAIT_MS }))
+      : null;
+    return { symbol: listing.symbol, exchange: listing.request.exchange, name: answer.quote.name?.trim() || null, coinNote: coinListingNotes(listing, answer.quote)[0] ?? null,
+      ...successorNote ? { successorNote } : {} };
   }
   if (!isNoProviderError(answer.error)) return null;
   const other = await quoteBareListing(listing, deps, request, { refresh });
@@ -861,10 +896,12 @@ export function listingFateLoader(
   listing: Pick<CliListing, "symbol" | "exchange" | "request">,
   deps: Pick<ListingDeps, "dataProvider">,
   quote: Promise<Quote | null>,
+  /** `successor`: the command says what became of the company too (GOGL's merger), so the lookup is waited for. */
+  { successor = false }: { successor?: boolean } = {},
 ): () => Promise<ListingFate> {
   const changes = startTickerChangeLookup(deps.dataProvider, listing.symbol, listing.exchange);
   let fate: Promise<ListingFate> | null = null;
-  return () => fate ??= loadListingFate(listing, deps.dataProvider, { quote, changes });
+  return () => fate ??= loadListingFate(listing, deps.dataProvider, { quote, changes, ...successor ? { graceMs: SUCCESSOR_CHANGE_WAIT_MS } : {} });
 }
 
 /**