@gloom-sh/terminal 0.18.5 → 0.19.1

package/src/cli/commands/options-chain.ts

@@ -4,7 +4,7 @@ import type { DataProvider } from "../../types/data-provider";
 import type { CliListing } from "../listing-arg";
 import { cliStyles, cliTerminalWidth, wrapText } from "../../utils/cli-output";
 import { isFiniteNumber } from "../../utils/guards";
-import { calculateOptionGreeks, solveChainVolatilities } from "../../plugins/builtin/options/analytics";
+import { calculateOptionGreeks, ivSolvedNote, solveChainVolatilities } from "../../plugins/builtin/options/analytics";
 import { optionQuoteSide } from "../../plugins/builtin/options/market-reference";
 import {
   formatModelSpotPrice, modelSpotLabel, optionModelSpot, type OptionModelSpot,
@@ -16,9 +16,30 @@ import { DEFAULT_OPTION_CALC_DRAFT } from "../../plugins/builtin/options-calcula
 import { expiryIsoDate, OPTION_EXPIRATION_PLACEHOLDER, parseOptionExpiration, settlementStampTime } from "../../utils/option-expiry";
 import { loadModelDividendYield } from "../../market-data/model-dividend-yield";
 import { formatUtcTime } from "../../utils/utc-time";
+import { takeOption } from "./command-utils";
 
 export const OPTIONS_USAGE = `options <symbol> [--expiration <${OPTION_EXPIRATION_PLACEHOLDER}>]`;
 
+/** `--expiration` as `options` names it, and `--expiry` as `fn GEX` and `fn OPX` do. */
+const OPTIONS_EXPIRATION_FLAGS = ["--expiration", "--expiry"] as const;
+type OptionsExpirationFlag = (typeof OPTIONS_EXPIRATION_FLAGS)[number];
+
+/**
+ * Takes the expiry option out of `args`, under either spelling: its value,
+ * the flag as typed (for messages), whether it was given at all (a flag with
+ * no value is given), and whether both spellings were.
+ */
+export function takeExpirationOption(args: string[]): {
+  value: string | undefined;
+  flag: OptionsExpirationFlag;
+  given: boolean;
+  both: boolean;
+} {
+  const typed = OPTIONS_EXPIRATION_FLAGS.filter((flag) => args.some((arg) => arg === flag || arg.startsWith(`${flag}=`)));
+  const [expiration, expiry] = OPTIONS_EXPIRATION_FLAGS.map((flag) => takeOption(args, flag));
+  return { value: expiration ?? expiry, flag: typed.length === 1 ? typed[0]! : "--expiration", given: typed.length > 0, both: typed.length > 1 };
+}
+
 export { parseOptionExpiration };
 
 /** Whether the chain holds contracts of the requested expiry, matched by UTC calendar date as the chain stamps them. */
@@ -63,6 +84,8 @@ export interface OptionModelInputs {
 interface OptionModelFigures {
   /** Annualized volatility as a fraction, solved from the chain's quotes. */
   iv: number | null;
+  /** `iv` was read off the neighbouring strikes: this strike has no two-sided out-of-the-money quote to solve from. */
+  ivFilled?: boolean;
   delta: number | null;
 }
 
@@ -73,6 +96,7 @@ export const OPTION_MODEL_RATE = DEFAULT_OPTION_CALC_DRAFT.rate;
 export const MARKED_OPTION_FIELDS = {
   iv: "The venue's mark implied volatility (decimal), one per contract. Delta and the other greeks under mark are the venue's too: "
     + "Black-76 at the expiry's forward with no discounting, to its settlement.",
+  ivSource: "mark: iv is the venue's own, never solved or filled here.",
   bid: "Prices in USD are the coin prices (coin) at the expiry's forward (mark.forward), the venue's own model price.",
   mark: "price in USD; iv; delta and gamma per 1.00 move in the underlying; vega per volatility point and theta per calendar day, in USD.",
 } as const;
@@ -91,6 +115,8 @@ export function chainCoinCurrency(chain: OptionsChain): string | null {
 export const OPTION_VOLATILITY_FIELDS = {
   iv: "Annualized volatility (decimal) solved from the quote midpoint, one per strike from its out-of-the-money side, at the "
     + "spot, valuation time and rate in metadata.model. Delta here and dealer gamma (GEX) are valued with it.",
+  ivSource: "solved: iv comes from the strike's out-of-the-money quote midpoint. filled: that side has no two-sided quote, so iv is read off the "
+    + "nearest solved strikes (flat beyond the last one); it is no market's volatility, and delta is valued with it all the same.",
   impliedVolatility: "The data provider's own reported implied volatility, passed through unchanged. Delta does not use it; "
     + "GEX falls back to it only at a strike with no two-sided quote on either side.",
 } as const;
@@ -116,8 +142,9 @@ function optionModelFigures(chain: OptionsChain, inputs: OptionModelInputs): Map
       for (const contract of contracts) {
         const volatility = volatilities.byStrike.get(contract.strike);
         const delta = calculateOptionGreeks(contract, side, inputs.spot, inputs.dividendYield, volatilities)?.delta;
+        const iv = volatility != null && Number.isFinite(volatility) && volatility > 0 ? volatility : null;
         figures.set(contract, {
-          iv: volatility != null && Number.isFinite(volatility) && volatility > 0 ? volatility : null,
+          iv, ivFilled: iv != null && volatilities.filled.has(contract.strike),
           delta: delta != null && Number.isFinite(delta) ? delta : null,
         });
       }
@@ -167,7 +194,8 @@ export async function loadOptionModelInputs(
 /** The chain with each contract's modeled `iv` and `delta` added; every provider field is kept. */
 export function chainWithModelFigures(chain: OptionsChain, inputs: OptionModelInputs): OptionsChain {
   const figures = optionModelFigures(chain, inputs);
-  const add = (contract: OptionContract) => ({ ...contract, iv: figures.get(contract)?.iv ?? null, delta: figures.get(contract)?.delta ?? null });
+  const add = (contract: OptionContract) => ({ ...contract, iv: figures.get(contract)?.iv ?? null, ivFilled: figures.get(contract)?.ivFilled ?? false,
+    delta: figures.get(contract)?.delta ?? null });
   return { ...chain, calls: chain.calls.map(add), puts: chain.puts.map(add) };
 }
 
@@ -180,6 +208,13 @@ export interface OptionsChainBasis {
   spot: OptionModelSpot | null;
   dividendYield: number | null;
   openInterest: OpenInterestAsOf | null;
+  /** A strike's IV is filled from its neighbours (`chainHasFilledIv`), which the closing line says. */
+  ivFilled?: boolean;
+}
+
+/** Whether any contract's IV was read off the neighbouring strikes (see `ChainVolatilities.filled`). */
+export function chainHasFilledIv(chain: OptionsChain): boolean {
+  return [...chain.calls, ...chain.puts].some((contract) => (contract as OptionContract & OptionModelFigures).ivFilled === true);
 }
 
 /** The chain with `iv` and `delta` valued at the spot `optionModelSpot` picks for it, and that spot. */
@@ -207,7 +242,8 @@ export async function loadOptionsChainOpenInterest(symbol: string, chain: Option
 }
 
 /**
- * The line under the chain: `Greeks at spot 89.79 (close Mon 12 Oct 20:00 UTC), dividend yield 2.34%, rate 4% · OI as of Fri 9 Oct`.
+ * The line under the chain: `Greeks at spot 89.79 (close Mon 12 Oct 20:00 UTC), dividend yield 2.34%, rate 4% · IV solved from quote mids ·
+ * OI as of Fri 9 Oct`, with `, ~ filled from neighbouring strikes` after the IV when a strike has no quote to solve from.
  * An open interest whose date cannot be established says why. A chain its
  * venue marks says whose marks they are: `Deribit marks: IV and greeks at
  * each expiry's forward, rate 0%; $ is the BTC price at the forward · OI live, Thu 22 Oct 22:42 UTC`.
@@ -230,6 +266,7 @@ export function optionsBasisFootnote(basis: OptionsChainBasis, chain?: OptionsCh
       // An unknown yield is valued as none, and says so rather than read as a stated 0%.
       + `dividend yield ${basis.dividendYield == null ? "unknown (valued at 0%)" : `${Number((basis.dividendYield * 100).toFixed(2))}%`}, `
       + `rate ${Number((OPTION_MODEL_RATE * 100).toFixed(2))}%`);
+    parts.push(ivSolvedNote(basis.ivFilled === true));
   }
   const oi = basis.openInterest;
   parts.push(oi?.date ? openInterestAsOfLabel(oi)
@@ -266,6 +303,8 @@ export function optionRows(chain: OptionsChain) {
       volume: contract.volume,
       openInterest: contract.openInterest,
       iv: modeled.iv ?? null,
+      // Solved from the strike's quote, or filled from its neighbours when it has none to solve from; a venue's own mark is neither.
+      ivSource: modeled.iv == null ? null : contract.mark ? "mark" : modeled.ivFilled ? "filled" : "solved",
       delta: modeled.delta ?? null,
       expiration: expiryIsoDate(contract.expiration),
       // A venue's marks and coin prices (Deribit), beside the dollar ones.
@@ -301,9 +340,11 @@ export function formatOptionQuoteCell(row: Record<string, unknown>, side: "bid"
   return quote == null ? "—" : String(quote);
 }
 
-/** Implied volatility as a percent; a dash when it could not be solved, never 0.0%. */
-export function formatOptionIvCell(value: unknown): string {
-  return isFiniteNumber(value) && value > 0 ? `${(value * 100).toFixed(1)}%` : "—";
+/** Implied volatility as a percent; a dash when it could not be solved, never 0.0%, and a leading "~" when it was filled from neighbouring strikes. */
+export function formatOptionIvCell(value: unknown, row?: Record<string, unknown>): string {
+  if (!isFiniteNumber(value) || !(value > 0)) return "—";
+  const text = `${(value * 100).toFixed(1)}%`;
+  return row?.ivSource === "filled" ? `~${text}` : text;
 }
 
 /** Delta to two places, signed for puts; a dash when it could not be valued, and no "-0.00" for a far wing. */

package/src/cli/commands/options-leaps.ts

@@ -281,6 +281,8 @@ export type LeapsRow = {
   // The fields below are on a row only when `--columns` asked for them.
   /** `iv`: the implied volatility the contract's delta is valued at, percent a year. */
   ivPercent?: number | null;
+  /** `iv`: `filled` when that strike has no two-sided out-of-the-money quote to solve from and its IV is read off the neighbouring strikes. */
+  ivSource?: "solved" | "filled" | null;
   /** `ivr`: the underlying's 30-day IV rank against its 52 weeks, 0 to 100, and the close it ranks. */
   ivRank?: number | null;
   ivRankAsOf?: string | null;
@@ -369,7 +371,10 @@ function screenLeapsChain(
       dataSource: chain.dataSource ?? null,
       delayMinutes: chain.delayMinutes ?? null,
     };
-    if (wants.has("iv")) row.ivPercent = contract.iv != null && Number.isFinite(contract.iv) ? round(contract.iv * 100, 2) : null;
+    if (wants.has("iv")) {
+      row.ivPercent = contract.iv != null && Number.isFinite(contract.iv) ? round(contract.iv * 100, 2) : null;
+      row.ivSource = row.ivPercent == null ? null : (contract as { ivFilled?: boolean }).ivFilled ? "filled" : "solved";
+    }
     // A two-sided quote passed the spread cap, so the midpoint is there.
     const mid = optionMid(contract)!;
     if (wants.has("cost")) row.costPerContract = round(mid * SHARES_PER_CONTRACT, 2);
@@ -694,7 +699,7 @@ const LEAPS_COLUMNS: CliResultColumn<LeapsRow>[] = [
 
 /** What each `--columns` name adds to the exports, after Extrinsic/yr %. */
 const EXTRA_EXPORT_COLUMNS: Record<LeapsExtraColumn, CliResultColumn<LeapsRow>[]> = {
-  iv: [{ key: "ivPercent", header: "IV %", align: "right", format: formatPercent }],
+  iv: [{ key: "ivPercent", header: "IV %", align: "right", format: formatPercent }, { key: "ivSource", header: "IV source" }],
   ivr: [{ key: "ivRank", header: "IV Rank", align: "right" }, { key: "ivRankAsOf", header: "IV Rank As Of" }],
   cost: [{ key: "costPerContract", header: "Cost/Contract (mid x 100)", align: "right" }],
   breakeven: [
@@ -717,7 +722,8 @@ const LEAPS_TEXT_COLUMNS: CliResultColumn<LeapsRow>[] = TEXT_COLUMN_KEYS.map((ke
 
 /** The text table's columns for a contract's own `--columns` figures; the underlying's go in a table of their own above. */
 const EXTRA_TEXT_COLUMNS: Partial<Record<LeapsExtraColumn, CliResultColumn<LeapsRow>[]>> = {
-  iv: [{ key: "ivPercent", header: "IV", align: "right", format: formatPercent }],
+  iv: [{ key: "ivPercent", header: "IV", align: "right", format: (value, row) => row.ivSource === "filled" && typeof value === "number" && Number.isFinite(value)
+    ? `~${value.toFixed(1)}%` : formatPercent(value) }],
   "carry-net": [{ key: "carryNetPerYearPercent", header: "Net/yr", align: "right", format: formatPercent }],
   cost: [{ key: "costPerContract", header: "Cost", align: "right", format: formatWhole }],
   breakeven: [

package/src/cli/commands/overview.ts

@@ -1,8 +1,8 @@
 import { logFailure } from "../../utils/log-failure";
 import { apiClient } from "../../api-client";
-import { ApiRequestError } from "../../api-client/errors";
+import { ApiRequestError, isPermanentClientError } from "../../api-client/errors";
 import type { CliCommandDef } from "../../types/plugin";
-import { withCliServices, withMarketData } from "../context";
+import { withCliServices, withConfigData, withMarketData } from "../context";
 import { CLI_ERROR_CODE, failWithFields } from "../errors";
 import type { CliResultColumn } from "../result";
 import { formatCompact } from "../../utils/format";
@@ -23,25 +23,36 @@ import {
   type MoverRankBasis,
 } from "../../plugins/builtin/market-movers/model";
 import { MOVER_CANDIDATES } from "../../plugins/builtin/market-movers/client";
+import { hasPartialFloat, meetsMinFloat, minFloatShares, normalizeMinFloat, PARTIAL_FLOAT_NOTE } from "../../plugins/builtin/market-movers/min-float";
 import { fetchEconCalendarFrom } from "../../plugins/builtin/econ/calendar-source";
-import { computedFredSeriesNote, seriesNotOnFred } from "../../sources/gloomberb-cloud/fred-series";
+import {
+  attachFredSeriesPersistence, computedFredSeriesNote, loadCachedFredSeries, resetFredSeriesPersistence, seriesNotOnFred,
+} from "../../sources/gloomberb-cloud/fred-series";
+import type { CloudFredSeriesPayload } from "../../api-client";
+import { savedCopyMark } from "../../data/saved-copies";
+import { ratesMacroPluginMeta } from "../../plugins/builtin/builtin-plugin-meta";
+import { createCommandPluginPersistence } from "../saved-copy-persistence";
 import { EXTENDED_SESSION_LABELS, getQuoteSessionFields, type ExtendedSession } from "../../market-data/market/status";
 import {
   COUNTRY_CYCLE,
   COUNTRY_FILTER_HINT,
+  awaitsConsensus,
   countriesWithoutEvents,
+  econEventName,
   FILTER_CYCLE,
   loadCalendar,
   eventCountry,
   matchesCountry,
+  matchesEventSearch,
   matchesImpact,
+  NO_CONSENSUS_NOTE,
   noScheduledReleasesMessage,
   parseCountryFilter,
   shortCalendarEnd,
   type CountryFilter,
   type ImpactFilter,
 } from "../../plugins/builtin/econ/calendar-model";
-import { hasNoReleaseTime, hasNoStatedTime } from "../../plugins/builtin/econ/types";
+import { hasNoReleaseTime, hasNoStatedTime, type EconEvent } from "../../plugins/builtin/econ/types";
 import { econRowFigures } from "../../plugins/builtin/econ/figures";
 import { isoDate, rejectExtraArgs, requireArg, requireOneArg, takeFlag, takeOption } from "./command-utils";
 import { buildCorrelationSeries } from "../../plugins/builtin/correlation/matrix/model";
@@ -141,7 +152,7 @@ const MOVER_LISTS: Record<string, ScreenerCategory | "trending"> = {
   "most-active": "most_actives",
   trending: "trending",
 };
-const MOVERS_USAGE = "movers [gainers|losers|active|trending] [--session regular|extended]";
+const MOVERS_USAGE = "movers [gainers|losers|active|trending] [--session regular|extended] [--min-float <shares>]";
 /** The most rows the movers list serves in one request. */
 const MOVER_REQUEST_CAP = 100;
 /** A one-shot list waits this long for its rows' average volumes and sizes, as `fn MOST` does. */
@@ -154,6 +165,16 @@ function moverRankBasis(value: string | undefined, ctx: Parameters<CliCommandDef
   return basis;
 }
 
+/** `--min-float` in shares, null for none; fails on a value that is not a share count. */
+function moverMinFloat(value: string | undefined, ctx: Parameters<CliCommandDef["execute"]>[1]): number | null {
+  if (value == null) return null;
+  try {
+    return minFloatShares(normalizeMinFloat(value));
+  } catch (error) {
+    ctx.fail(error instanceof Error ? error.message : String(error));
+  }
+}
+
 function screenerCategory(args: readonly string[], ctx: Parameters<CliCommandDef["execute"]>[1]): ScreenerCategory | "trending" {
   rejectExtraArgs(args, 1, { usage: MOVERS_USAGE, takes: "one list" }, ctx);
   const list = args[0]?.toLowerCase() ?? "gainers";
@@ -199,12 +220,14 @@ async function runMoverCommand(rawArgs: string[], ctx: Parameters<CliCommandDef[
   const args = [...rawArgs];
   const sessionOption = takeOption(args, "--session");
   const basis = moverRankBasis(sessionOption, ctx);
+  const minFloat = moverMinFloat(takeOption(args, "--min-float"), ctx);
   const category = screenerCategory(args, ctx);
   const limit = ctx.cliOptions.limit ?? 25;
   if (sessionOption != null && (category === "trending" || category === "most_actives")) {
     ctx.fail("--session ranks Gainers and Losers.", category === "trending"
       ? "Trending keeps its source's order." : "Most active ranks by volume.");
   }
+  if (minFloat != null && category === "trending") ctx.fail("--min-float filters Gainers, Losers and Most active.", "Trending carries no float.");
   if (category === "trending") {
     await withCliServices(ctx, async (services) => {
       const trending = await fetchTrending(limit, undefined, { forceRefresh: ctx.cliOptions.refresh });
@@ -220,8 +243,8 @@ async function runMoverCommand(rawArgs: string[], ctx: Parameters<CliCommandDef[
   }
 
   // After the close a price list keeps only the rows moving its way on the basis
-  // asked for, so it reads more candidates than it shows.
-  const count = category === "most_actives" ? limit : Math.min(MOVER_REQUEST_CAP, Math.max(limit, MOVER_CANDIDATES));
+  // asked for, and a minimum float drops rows, so they read more candidates than they show.
+  const count = category === "most_actives" && minFloat == null ? limit : Math.min(MOVER_REQUEST_CAP, Math.max(limit, MOVER_CANDIDATES));
   // With the saved session, as MOST reads it: a Pro account gets the real-time lists, anyone else the delayed ones.
   const movers = await withMarketData(ctx, () =>
     fetchPreferredMarketMovers(category, count, { forceRefresh: ctx.cliOptions.refresh, session: basis, metadataWaitMs: MOVER_METADATA_WAIT_MS }));
@@ -230,7 +253,7 @@ async function runMoverCommand(rawArgs: string[], ctx: Parameters<CliCommandDef[
   // the regular session's move (its close's after the close), or with
   // --session extended by the extended print's move from that close.
   const { quotes, rankedBy } = rankMoverQuotes(category, movers.quotes.map(moverRegularSession), basis);
-  const rows = quotes.slice(0, limit).map((quote) => {
+  const rows = quotes.filter((quote) => meetsMinFloat(quote.floatShares, minFloat)).slice(0, limit).map((quote) => {
     const { extended, ...row } = quote;
     return {
       ...row,
@@ -244,16 +267,18 @@ async function runMoverCommand(rawArgs: string[], ctx: Parameters<CliCommandDef[
   // As the MOST report reads it: real-time for a Pro account, delayed otherwise, each row dated by its own last price.
   ctx.printResult({
     data: rows,
-    metadata: { category, rankedBy },
+    metadata: { category, rankedBy, ...(minFloat != null ? { minFloat } : {}) },
     ...(fellBack ? { warnings: ["No pre-market or after-hours prints now, so the list is ranked by the regular-session move."] } : {}),
     freshness: rowsFreshness(rows, { status: movers.source === "cloud" ? "live" : "delayed" }, { stale: movers.stale }),
   }, {
     heading: `Ranked by ${MOVER_RANKING_LABELS[rankedBy]}`,
+    ...(minFloat != null && hasPartialFloat(rows) ? { footnote: PARTIAL_FLOAT_NOTE } : {}),
     columns: [
       ...MOVER_COLUMNS.slice(0, 4),
       ...EXTENDED_COLUMNS,
       { key: "volume", header: "Volume", align: "right", value: (row) => formatCompact(Number(row.volume)) },
       { ...MARKET_CAP_CELL, value: (row) => row.marketCap == null ? "" : formatCompact(Number(row.marketCap)) },
+      ...(minFloat != null ? [{ key: "floatShares", header: "Float", align: "right" as const, value: (row: Record<string, unknown>) => formatCompact(Number(row.floatShares)) }] : []),
     ],
   });
 }
@@ -288,7 +313,7 @@ function utcDateTimePart(value: unknown, part: "date" | "time", readerClock = tr
   return part === "date" ? iso.slice(0, 10) : `${iso.slice(11, 16)} UTC${readerClock ? localTimeSuffix(date.getTime()) : ""}`;
 }
 
-const ECON_USAGE = "econ [--country <regions or countries>] [--impact <level>] [--from <date>] [--tz <zone>]";
+const ECON_USAGE = "econ [--country <regions or countries>] [--impact <level>] [--search <words>] [--from <date>] [--tz <zone>]";
 const WEEKDAYS = ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"] as const;
 /** "Sat" for 2026-10-31. */
 const weekdayOf = (date: string) => WEEKDAYS[new Date(`${date}T00:00:00Z`).getUTCDay()]!;
@@ -325,6 +350,19 @@ function econHeadColumns(viewerZone: string | null): CliResultColumn[] {
   ];
 }
 
+/**
+ * The text table's columns up to the event. Plain output keeps every column a
+ * query has, so a column that is empty by construction has to be left out
+ * here, not hidden by the table: the viewer's clock only exists with --tz, and
+ * the publisher's own clock only on rows a bank or statistics office times
+ * itself. Exports keep both, so a script's header never moves.
+ */
+function econTextHeadColumns(viewerZone: string | null, publisherTimed: boolean): CliResultColumn[] {
+  return econHeadColumns(viewerZone).filter((column) => (
+    column.key === "viewerTime" ? !!viewerZone : column.key === "localTime" ? publisherTimed : true
+  ));
+}
+
 /**
  * Actual, Forecast and Prior: as the text draws them (`30.3K`, `-4.1M bbl`) in the table, as
  * numbers in the exports (30300, -4100000), where Unit and Scale say what they count and how they were drawn.
@@ -349,6 +387,9 @@ const econExportColumns: CliResultColumn[] = [
   { key: "actualText", header: "actual_text" },
   { key: "forecastText", header: "forecast_text" },
   { key: "priorText", header: "prior_text" },
+  // Which feed the forecast was read from and when, so a consensus can be told from another read of it.
+  { key: "consensusFeed", header: "consensus_feed" },
+  { key: "consensusReadAt", header: "consensus_read_at" },
 ];
 
 /**
@@ -409,6 +450,16 @@ function blankTimeNotes(rows: ReadonlyArray<{ event: string; country: string; ti
   return [...byNote].map(([note, events]) => `No time for ${events.join(", ")}: ${note.charAt(0).toLowerCase()}${note.slice(1)}.`);
 }
 
+/**
+ * Whether a row has come out: it has an actual, or it has no figure at all (a
+ * speech, a meeting, a holiday) and its time has passed. A row with a forecast
+ * or a prior and no actual is still to come, whatever its time.
+ */
+function cameOut(event: Pick<EconEvent, "actual" | "forecast" | "prior" | "date">, now: number): boolean {
+  if (event.actual?.trim()) return true;
+  return !event.forecast?.trim() && !event.prior?.trim() && event.date.getTime() <= now;
+}
+
 /**
  * A `--from` the stored calendar does not reach back to, which Gloom Cloud refuses
  * with "The calendar reaches back 400 days": an input error naming the earliest
@@ -429,15 +480,18 @@ async function runEcon(args: string[], ctx: Parameters<CliCommandDef["execute"]>
   const rawArgs = [...args];
   const country = parseCountry(takeOption(rawArgs, "--country"), ctx);
   const impact: ImpactFilter = parseFilter(takeOption(rawArgs, "--impact"), FILTER_CYCLE, "impact", ctx);
+  const search = takeOption(rawArgs, "--search")?.trim() ?? null;
+  if (search === "") ctx.fail("--search needs the words of an event's name.", "Such as econ --search nonfarm.");
   const fromOption = parseDateOption(takeOption(rawArgs, "--from"), "--from", ctx);
   const tzOption = takeOption(rawArgs, "--tz");
   const viewerZone = tzOption == null ? null : canonicalTimeZone(tzOption);
   if (tzOption != null && !viewerZone) {
     ctx.fail(`Unknown time zone "${tzOption}".`, "Use an IANA zone name, such as America/New_York, Europe/London or Asia/Tokyo.");
   }
-  rejectArgs(rawArgs, ECON_USAGE, ctx, "Filter with --country and --impact.");
+  rejectArgs(rawArgs, ECON_USAGE, ctx, "Filter with --country, --impact and --search.");
   await withCliServices(ctx, async () => {
-    const todayStart = Math.floor(Date.now() / DAY_MS) * DAY_MS;
+    const now = Date.now();
+    const todayStart = Math.floor(now / DAY_MS) * DAY_MS;
     // An earlier day reads the stored calendar, which keeps past events after the week's listing drops them.
     // A server without it, a server error or no network lists the current calendar (cached when offline) instead.
     const stored = fromOption != null && fromOption < isoDate(new Date(todayStart))
@@ -445,7 +499,9 @@ async function runEcon(args: string[], ctx: Parameters<CliCommandDef["execute"]>
       : null;
     const past = stored?.events ? stored : null;
     const unread = stored && !stored.events && stored.failure ? `The stored calendar could not be read (${stored.failure}); listing the current calendar` : null;
-    const { data: events, fetchedAt, stale } = past ? { data: past.events, fetchedAt: Date.now(), stale: false } : await loadCalendar(ctx.cliOptions.refresh);
+    const { data: events, fetchedAt, stale, source } = past
+      ? { data: past.events, fetchedAt: Date.now(), stale: false, source: "network" as const }
+      : await loadCalendar(ctx.cliOptions.refresh);
     // The calendar lists from today (UTC). --from moves the first day; --tail
     // alone keeps the newest events of the whole calendar, the past week's too.
     const from = fromOption ?? (ctx.cliOptions.tail != null ? null : new Date(todayStart).toISOString().slice(0, 10));
@@ -464,9 +520,10 @@ async function runEcon(args: string[], ctx: Parameters<CliCommandDef["execute"]>
     // Countries asked for that nothing in the window is for: a quiet week there, not an unknown country.
     const inWindow = events.filter((event) => event.date.getTime() >= fromTime);
     const unscheduled = countriesWithoutEvents(country, inWindow);
-    const rows = inWindow
-      .filter((event) => matchesCountry(event, country) && matchesImpact(event, impact))
-      .sort((left, right) => left.date.getTime() - right.date.getTime())
+    const listed = inWindow
+      .filter((event) => matchesCountry(event, country) && matchesImpact(event, impact) && (search == null || matchesEventSearch(event, search)))
+      .sort((left, right) => left.date.getTime() - right.date.getTime());
+    const rows = listed
       .map((event) => {
         // The viewer's clock (--tz) for a row with a time: its date and time there.
         const clock = viewerZone && !hasNoReleaseTime(event) ? zonedClock(event.date.getTime(), viewerZone) : null;
@@ -480,7 +537,8 @@ async function runEcon(args: string[], ctx: Parameters<CliCommandDef["execute"]>
           ...(viewerZone ? { viewerDate: clock?.date ?? null, viewerTime: clock?.time ?? null } : {}),
           country: eventCountry(event),
           impact: event.impact,
-          event: event.event,
+          // As the calendar names it: the Fed's decision is the upper bound of its range.
+          event: econEventName(event),
           actual: figures.actual,
           forecast: figures.forecast,
           prior: figures.prior,
@@ -497,25 +555,34 @@ async function runEcon(args: string[], ctx: Parameters<CliCommandDef["execute"]>
           // Who publishes the figure (Freddie Mac for the 30-year mortgage rate), the period it covers and its page.
           publisher: event.source?.name ?? null,
           referencePeriod: event.referencePeriod ?? null,
-          // When the figure came out: the row's time once it has an actual (its day alone when it states no time), null before.
-          released: event.actual?.trim() ? (hasNoReleaseTime(event) ? isoDate(event.date).slice(0, 10) : isoDate(event.date)) : null,
+          // When the figure came out: the row's time once it has an actual, and for a row with no figures (a speech, a
+          // meeting) once its time has passed; its day alone when it states no time, null before.
+          released: cameOut(event, now) ? (hasNoReleaseTime(event) ? isoDate(event.date).slice(0, 10) : isoDate(event.date)) : null,
           sourceUrl: event.source?.url ?? null,
-          // The same indicator from one release to the next; empty until Gloom Cloud names it.
+          // The same indicator from one release to the next, as Gloom Cloud names it.
           indicatorId: event.indicatorId ?? null,
+          // The feed the forecast was read from and when, for a row with a forecast.
+          consensusFeed: event.consensus?.source ?? null,
+          consensusReadAt: event.consensus?.readAt ?? null,
         };
       });
     // A filter of countries only, none of which has anything in the window, says so as its empty list.
     const allUnscheduled = unscheduled.length > 0 && unscheduled.length === country.split(",").length;
     const notes = [listedBefore, listedAfter, ...(rows.length > 0 ? blankTimeNotes(rows) : []),
-      rows.length > 0 && unscheduled.length > 0 ? noScheduledReleasesMessage(unscheduled) : null]
+      rows.length > 0 && unscheduled.length > 0 ? noScheduledReleasesMessage(unscheduled) : null,
+      // A dash under Forecast on a release still to come is a consensus not in yet, not a missing figure.
+      listed.some(awaitsConsensus) ? NO_CONSENSUS_NOTE : null]
       .filter((note): note is string => !!note);
     const footnote = notes.join("\n");
+    // The calendar as read, not its rows: those are scheduled, mostly ahead. One that could not be
+    // refreshed is the copy an earlier read saved, and says when that was.
+    const read = rowsFreshness([], { status: "not-a-feed", basis: "calendar", asOf: fetchedAt }, { stale });
+    const calendarFreshness = read && source === "stale-fallback" ? { ...read, savedAt: new Date(fetchedAt).toISOString() } : read;
     ctx.printResult({
       data: rows,
       ...(unread ? { warnings: [unread] } : {}),
-      metadata: { country, impact, from, listedThrough, storedFrom: past?.storedFrom ?? null, ...(viewerZone ? { timeZone: viewerZone } : {}) },
-      // The calendar as read, not its rows: those are scheduled, mostly ahead.
-      freshness: rowsFreshness([], { status: "not-a-feed", basis: "calendar", asOf: fetchedAt }, { stale }),
+      metadata: { country, impact, ...(search != null ? { search } : {}), from, listedThrough, storedFrom: past?.storedFrom ?? null, ...(viewerZone ? { timeZone: viewerZone } : {}) },
+      freshness: calendarFreshness,
     }, {
       dateKey: "date",
       defaultLimit: 50,
@@ -535,7 +602,7 @@ async function runEcon(args: string[], ctx: Parameters<CliCommandDef["execute"]>
       }),
       // The exports add what a script needs to read a row; the text table keeps the columns it had.
       columns: [...econHeadColumns(viewerZone), ...econFigureColumns(false), ...econExportColumns],
-      textColumns: [...econHeadColumns(viewerZone), ...econFigureColumns(true), ECON_PUBLISHER_COLUMN],
+      textColumns: [...econTextHeadColumns(viewerZone, rows.some((row) => !!publisherClock(row.localTime, row.timeZone))), ...econFigureColumns(true), ECON_PUBLISHER_COLUMN],
     });
   });
 }
@@ -561,6 +628,36 @@ function isUnsupportedSeries(error: unknown): boolean {
   return error.details?.code === "unsupported_series" || /^Unsupported FRED series\b/i.test(message);
 }
 
+/**
+ * Runs `run` with the FRED series cache saving what it fetches in the profile,
+ * where the app's rates and macro panes keep it: a refresh that fails then
+ * answers from the copy an earlier read saved, and the report says so.
+ */
+function withSavedFredSeries<T>(ctx: Parameters<CliCommandDef["execute"]>[1], run: () => Promise<T>): Promise<T> {
+  return withConfigData(ctx, async ({ persistence }) => {
+    attachFredSeriesPersistence(createCommandPluginPersistence(persistence.resources, `plugin:${ratesMacroPluginMeta.stateId}`));
+    try {
+      return await run();
+    } finally {
+      resetFredSeriesPersistence();
+    }
+  });
+}
+
+/**
+ * A FRED series from Gloom Cloud, or the copy an earlier read saved when it
+ * cannot be refreshed (marked as such). A refusal asking again will not change
+ * (a series Gloom Cloud no longer serves, access denied) is said, not covered.
+ */
+async function loadFredSeries(
+  seriesId: string,
+  params: { startDate?: string; limit?: number; sortOrder: "asc" | "desc" },
+): Promise<CloudFredSeriesPayload> {
+  const result = await loadCachedFredSeries({ seriesId, ...params }, () => apiClient.getCloudFredSeries(seriesId, params));
+  if (result.source === "stale-fallback" && isPermanentClientError(result.error)) throw result.error;
+  return result.data;
+}
+
 async function runFredList(filter: string, ctx: Parameters<CliCommandDef["execute"]>[1]) {
   let catalog;
   try {
@@ -606,9 +703,19 @@ async function runFred(rawArgs: string[], ctx: Parameters<CliCommandDef["execute
     ctx.fail(change ? `Unknown change "${change}".` : "--change needs 1D or 1W.", "Use 1D (from the previous observation) or 1W (from a week before).");
   }
   const seriesId = requireOneArg(args, FRED_USAGE, "series", ctx).toUpperCase();
+  await withSavedFredSeries(ctx, () => printFredSeries(ctx, { seriesId, start, startDate, sortOrder, horizon }));
+}
+
+async function printFredSeries(ctx: Parameters<CliCommandDef["execute"]>[1], { seriesId, start, startDate, sortOrder, horizon }: {
+  seriesId: string;
+  start: string | undefined;
+  startDate: string;
+  sortOrder: "asc" | "desc";
+  horizon: ReturnType<typeof parseFredChange>;
+}) {
   // A change needs the observation it is measured from: the fetch reaches back before the first row shown.
   const fetchStart = horizon ? fredChangeFetchStart(startDate) : startDate;
-  const data = await apiClient.getCloudFredSeries(seriesId, { startDate: fetchStart, sortOrder }).catch((error: unknown) => {
+  const data = await loadFredSeries(seriesId, { startDate: fetchStart, sortOrder }).catch((error: unknown) => {
     if (isUnsupportedSeries(error)) ctx.fail(`Unsupported FRED series ${seriesId}. List supported series with: gloom fred --list`);
     throw error;
   });
@@ -622,7 +729,9 @@ async function runFred(rawArgs: string[], ctx: Parameters<CliCommandDef["execute
   const releasedOf = (observation: { publisher?: string; publishedAt?: string; releasedOn?: string }) =>
     observation.releasedOn ?? (observation.publisher?.trim() ? observation.publishedAt : undefined);
   // A value FRED does not list yet carries its publisher and when it published, in every export.
+  // A row from the copy an earlier read saved, the refresh having failed, carries its mark: the source line says so.
   const exportRow = (observation: { date: string; value: number | null; publisher?: string; publishedAt?: string; releasedOn?: string }) => ({
+    ...savedCopyMark(data),
     date: observation.date,
     value: fredExportValue(seriesId, observation.value),
     ...(changes ? { change: changes.get(observation.date)?.change ?? null, changeFrom: changes.get(observation.date)?.changeFrom ?? null } : {}),
@@ -641,7 +750,7 @@ async function runFred(rawArgs: string[], ctx: Parameters<CliCommandDef["execute
     computedFredSeriesNote(seriesId),
   ].filter((note): note is string => note != null);
   // Nothing on or after the start: name where the series ends, so an empty answer is not a dead end.
-  const latest = rows.length > 0 ? null : await apiClient.getCloudFredSeries(seriesId, { limit: 1, sortOrder: "desc" })
+  const latest = rows.length > 0 ? null : await loadFredSeries(seriesId, { limit: 1, sortOrder: "desc" })
     .then((payload) => payload.observations[0] ?? null).catch(logFailure("cli.commands-overview", "Read latest economic series observation failed", null));
   // CSV and NDJSON are rows alone: an empty one would read as a series with no data, so it fails and says where the series ends.
   if (rows.length === 0 && (ctx.cliOptions.format === "csv" || ctx.cliOptions.format === "ndjson")) {
@@ -713,10 +822,12 @@ async function runYieldCurve(rawArgs: string[], ctx: Parameters<CliCommandDef["e
   const startDate = parseStartDate(takeOption(args, "--start"), ctx);
   rejectArgs(args, "yield-curve [--start <date>]", ctx);
   const series = Object.keys(YIELD_TENORS);
-  const results = await Promise.all(series.map(async (seriesId) => {
-    const data = await apiClient.getCloudFredSeries(seriesId, { startDate, sortOrder: "desc" });
+  const results = await withSavedFredSeries(ctx, () => Promise.all(series.map(async (seriesId) => {
+    const data = await loadFredSeries(seriesId, { startDate, sortOrder: "desc" });
     const [latest, previous] = data.observations;
     return {
+      // A tenor from the copy an earlier read saved, the refresh having failed, says so in the source line.
+      ...savedCopyMark(data),
       seriesId,
       date: latest?.date ?? "",
       // Yields in percent, which the exports' `currency_or_unit` column says (`pct`), as `fred` does.
@@ -729,7 +840,7 @@ async function runYieldCurve(rawArgs: string[], ctx: Parameters<CliCommandDef["e
       latest,
       publishedAt: latest?.publisher ? null : fredPublicationTime(data.info, latest?.date),
     };
-  }));
+  })));
   // Tenors whose latest yield FRED does not list yet name the Treasury and when it published them.
   const ahead = fredProvenance(results.flatMap((row) => row.latest ? [row.latest] : []));
   // The curve shown was published with its last tenor: the newest of their FRED updates, when each has one.
@@ -826,8 +937,11 @@ export const overviewCliCommands: CliCommandDef[] = [
       options: [{
         flags: "--session <basis>",
         description: "Rank gainers and losers by the regular-session move (regular, the default) or by the pre-market or after-hours move from the close (extended)",
+      }, {
+        flags: "--min-float <shares>",
+        description: "Keep the gainers, losers or most active whose float (the one EQS serves) is at least this many shares, such as 10M or 500k; a row with no float is left out",
       }],
-      examples: ["movers", "movers losers --limit 10", "movers gainers --session extended", "movers trending"],
+      examples: ["movers", "movers losers --limit 10", "movers gainers --session extended", "movers gainers --min-float 10M", "movers trending"],
     },
     execute: runMoverCommand,
   },
@@ -858,10 +972,11 @@ export const overviewCliCommands: CliCommandDef[] = [
       options: [
         { flags: "--country <regions or countries>", description: "US, G7, EU, all (default), or countries by their two-letter codes, comma separated, such as MX or MX,BR,ZA" },
         { flags: "--impact <level>", description: "high, medium, low, or all (default all)" },
+        { flags: "--search <words>", description: "Events whose name has these words, case, spaces and hyphens aside, such as nonfarm or fed funds" },
         { flags: "--from <date>", description: `First day listed, as ${DATE_OPTION_EXAMPLES} (default today, UTC); an earlier day lists past events from the stored calendar and says where it starts` },
         { flags: "--tz <zone>", description: "Add a column with each release's time on that clock, an IANA zone such as America/New_York; with the weekday when it falls on another day than the UTC date" },
       ],
-      examples: ["econ", "econ --country US --impact high", "econ --country MX,BR,ZA,IN,KR", "econ --from 2026-10-12 --country US",
+      examples: ["econ", "econ --country US --impact high", "econ --search nonfarm", "econ --country MX,BR,ZA,IN,KR", "econ --from 2026-10-12 --country US",
         "econ --country BR --tz America/New_York", "econ --tail 20"],
     },
     execute: runEcon,

package/src/cli/commands/search.ts

@@ -133,7 +133,7 @@ export async function searchCandidatesForCli({
     const quote = BARE_SYMBOL.test(symbol) && candidates.some((candidate) => candidate.symbol.toUpperCase() === symbol)
       ? await (quoted ?? loadSearchedQuote(symbol, savedExchange, dataProvider))
       : null;
-    return withQuotedNames(symbol, withHomeListingPrimary(trimmedQuery, withPrimaryListingFirst(symbol, candidates, quote)), quote)
+    return withQuotedNames(symbol, withUsLineOfPrimary(withHomeListingPrimary(trimmedQuery, withPrimaryListingFirst(symbol, candidates, quote))), quote)
       .slice(0, totalLimit);
   } catch (error) {
     // Not "No matches found": a script or a reader would take that for a name nothing lists.
@@ -299,6 +299,26 @@ function withHomeListingPrimary(query: string, candidates: TickerSearchCandidate
   return [...rest.slice(0, at), { ...home, category: "Primary Listing" as const }, { ...primary, category: "Other Listings" as const }, ...rest.slice(at + 1)];
 }
 
+/**
+ * A company whose primary listing is abroad lists the US line of the same
+ * symbol right after it: the line `quote SHEL` reads (a bare symbol is its US
+ * listing), which a name search ("shell") would otherwise rank below the
+ * company's lines on other venues and cut. Any other list keeps its order.
+ */
+function withUsLineOfPrimary(candidates: TickerSearchCandidate[]): TickerSearchCandidate[] {
+  const primary = candidates.find((candidate) => candidate.category === "Primary Listing");
+  if (!primary || primary.kind !== "search" || isUsListingExchange(candidateExchange(primary))) return candidates;
+  const symbol = primary.symbol.toUpperCase();
+  const company = resolveSearchName(primary);
+  const us = candidates.find((candidate) => candidate !== primary && candidate.kind === "search" && !candidate.contractKey
+    && candidate.category !== "Funds & Derivatives" && candidate.symbol.toUpperCase() === symbol
+    && isUsListingExchange(candidateExchange(candidate)) && sameCompany(resolveSearchName(candidate), company));
+  if (!us) return candidates;
+  const rest = candidates.filter((candidate) => candidate !== us);
+  const at = rest.indexOf(primary) + 1;
+  return [...rest.slice(0, at), { ...us, category: "Other Listings" as const }, ...rest.slice(at)];
+}
+
 /** The candidate on the venue the quote prices; the US exchanges share one symbol, so a quote on any of them is its one US line. */
 function quotedCandidate(candidates: readonly TickerSearchCandidate[], quote: Quote | null): TickerSearchCandidate | undefined {
   const quoted = canonicalExchange(quote?.listingExchangeName || quote?.exchangeName);