@gloom-sh/terminal 0.19.1 → 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/glossary.ts

@@ -404,7 +404,8 @@ export const GLOSSARY: readonly GlossaryEntry[] = [
   },
   {
     term: "Net debt", aliases: ["net debt/ebitda", "net debt to ebitda", "net leverage"], functions: ["FA"], shown: ["Net Debt"],
-    definition: "Total debt less cash and short-term investments. Negative means more cash than debt. "
+    definition: "Total debt less cash and short-term investments, with the balance sheet's lease liabilities under IFRS (\"incl. leases\"); "
+      + "a company reporting under US GAAP (a 10-K, or a 20-F such as Alibaba's) keeps its operating leases out (\"excl. op. leases\"). Negative means more cash than debt. "
       + "Net debt / EBITDA is how many years of EBITDA would repay it; FA divides by a year of EBITDA, the trailing four quarters in a quarterly column.",
   },
   {

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

@@ -14,8 +14,11 @@ import { isRoundTheClockCoin } from "../utils/crypto-pair";
 import { currencyPairCode } from "../utils/currency-pair";
 import { currencyUnitLabel, resolveCurrencyUnit } from "../utils/currency-units";
 import { getPricePointTimestamp } from "../utils/price-history";
-import { latestTradeIndex, missingVolumeNotice, pricePointIntegrityFlags, pricePointValues } from "../utils/price-history-integrity";
+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";
@@ -79,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. */
@@ -253,10 +267,17 @@ function flagCodes(row: Pick<HistoryRow, "flag">): string[] {
   return row.flag ? row.flag.split(",") : [];
 }
 
+/** The codes of a bar left blank for prices that contradict each other: not a break before it, nor a withheld wick. */
+function blankingCodes(row: Pick<HistoryRow, "flag">): string[] {
+  return flagCodes(row).filter((code) => !BREAK_FLAGS.has(code) && !isWickFlag(code));
+}
+
 /**
  * Intraday bars keep their UTC time; daily and longer bars are trading dates.
  * A bar whose prices contradict each other is blanked exactly as HP blanks it,
- * and says why in `flag`. A bar after a gap or a jump in the series keeps its
+ * and says why in `flag`. A low or high too far from the open and close to
+ * have traded is left blank, the rest of the bar kept, flagged `low<close/2`
+ * or `high>2*open`. A bar after a gap or a jump in the series keeps its
  * prices and is flagged `gap` or `jump`.
  */
 export function historyRows(
@@ -277,7 +298,7 @@ export function historyRows(
     const time = times[index]!;
     const iso = Number.isFinite(time) ? new Date(time).toISOString() : "";
     const values = pricePointValues(point);
-    const flags = pricePointIntegrityFlags(point);
+    const flags = [...pricePointIntegrityFlags(point), ...pricePointWickFlags(point)];
     const price = (value: number | null) => value == null ? null : cleanBarPrice(value, priceDivisor);
     return {
       date: intraday ? iso.replace(".000Z", "Z") : iso.slice(0, 10),
@@ -297,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
         ? {
@@ -307,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
@@ -360,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 {
@@ -448,7 +607,7 @@ export function historyMissingVolumeNote(
   if (!historyReportsVolume(rows)) return null;
   const latestTrade = latestTradeIndex(rows.map((row) => Date.parse(row.date)));
   const missing = rows.filter((row, index) => row.volume == null && row.venueVolume == null && !row.partial && !row.filled
-    && !flagCodes(row).some((code) => !BREAK_FLAGS.has(code)) && index !== latestTrade).length;
+    && blankingCodes(row).length === 0 && index !== latestTrade).length;
   return missingVolumeNotice(missing, rows.length) ?? null;
 }
 
@@ -833,10 +992,9 @@ export function historyGapNote(
  * keep their prices and are not counted.
  */
 export function historyFlagNote(rows: readonly Pick<HistoryRow, "flag">[]): string | null {
-  const contradictions = (row: Pick<HistoryRow, "flag">) => flagCodes(row).filter((code) => !BREAK_FLAGS.has(code));
-  const flagged = rows.filter((row) => contradictions(row).length > 0);
+  const flagged = rows.filter((row) => blankingCodes(row).length > 0);
   if (flagged.length === 0) return null;
-  const codes = new Set(flagged.flatMap(contradictions));
+  const codes = new Set(flagged.flatMap(blankingCodes));
   const kinds = [
     codes.has("high<open") || codes.has("high<close") ? "high below open or close" : "",
     codes.has("low>open") || codes.has("low>close") ? "low above open or close" : "",
@@ -845,3 +1003,23 @@ export function historyFlagNote(rows: readonly Pick<HistoryRow, "flag">[]): stri
   const count = `${flagged.length} of ${rows.length} ${flagged.length === 1 && rows.length === 1 ? "bar" : "bars"}`;
   return `${count} ${flagged.length === 1 ? "has" : "have"} ${kinds.join(", or ")} in the source data; their prices are left blank`;
 }
+
+/**
+ * "The low of 2021-11-29 is under half its open and close, too far to have
+ * traded; left blank and out of ranges", or null when no bar has such a wick
+ * (pricePointWickFlags). Three or more bars are counted.
+ */
+export function historyWickNote(rows: readonly Pick<HistoryRow, "date" | "flag">[]): string | null {
+  const flagged = rows.filter((row) => flagCodes(row).some(isWickFlag));
+  if (flagged.length === 0) return null;
+  const sides = new Set(flagged.flatMap((row) => flagCodes(row).filter(isWickFlag).map((code) => code.slice(0, code.indexOf(code.startsWith("low") ? "<" : ">")))));
+  const reason = "too far to have traded; left blank and out of ranges";
+  const only = flagged[0]!;
+  if (flagged.length === 1 && sides.size === 1) {
+    return sides.has("low") ? `The low of ${only.date} is under half its open and close, ${reason}`
+      : `The high of ${only.date} is over twice its open and close, ${reason}`;
+  }
+  const kinds = [sides.has("low") ? "a low under half" : "", sides.has("high") ? "a high over twice" : ""].filter(Boolean).join(" or ");
+  const dates = flagged.length <= LISTED_GAPS ? ` (${listItems(flagged.map((row) => row.date))})` : "";
+  return `${flagged.length} of ${rows.length} bars have ${kinds} their open and close${dates}, ${reason}`;
+}

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\".",
@@ -222,6 +233,17 @@ const TOPIC_POINTERS: ReadonlyArray<{
     closestLabel: "COMEX curves",
     closest: [["CTM", "gloom fn CTM HG for copper, gloom fn CTM ALI for aluminium"]],
   },
+  {
+    // No source serves a jet fuel (kerosene) price. Heating oil, NY Harbor ULSD, is what airlines hedge it with and
+    // analysts read it by; the EIA's weekly US stocks are a catalog series (checked 2026-10-29: quote HO=F,
+    // fn COT HO and fn G CAP:doe:jet all answer).
+    topic: "Jet fuel (kerosene)",
+    availability: "no price series; heating oil (NY Harbor ULSD) is the usual proxy, its price: gloom quote HO=F. "
+      + "US jet fuel stocks (EIA, weekly): gloom fn G CAP:doe:jet",
+    phrases: ["jet fuel", "jet fuels", "kerosene", "kerosine", "jet kerosene", "aviation fuel", "aviation fuels", "avtur"],
+    closestLabel: "positioning",
+    closest: [["COT", "heating oil, the usual jet fuel proxy: gloom fn COT HO"]],
+  },
   {
     // "exchange reserves" alone reads as crypto's; "foreign exchange reserves" is a central bank's, so only whole.
     topic: "Crypto exchange reserves and exchange flows",
@@ -315,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. */
@@ -387,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.
  */
@@ -395,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;