gloomberb 0.19.0 → 0.19.2

package/src/cli/commands/market.ts

@@ -3,6 +3,7 @@ import type { CliCommandDef } from "../../types/plugin";
 import { TIME_RANGES, type TimeRange } from "../../time-series/range";
 import { yearToDateStartIndex } from "../../market-data/market/year-to-date";
 import type { EarningsEvent, QuoteBatchResult, QuoteSubscriptionTarget, SecFilingItem } from "../../types/data-provider";
+import { companyDataNotes, type CompanyFrom } from "../../types/company-from";
 import type { NewsArticle, NewsFeed, NewsQuery } from "../../news/types";
 import type {
   AnalystResearchData,
@@ -39,7 +40,7 @@ import {
   quoteChangeText,
 } from "../helpers";
 import { cliArrow, cliStyles, colorBySign, renderSection, renderStats } from "../../utils/cli-output";
-import { filledPeriodsNote, stalePeriodNote, statementHistoryNotes } from "../../utils/financial-statements";
+import { filledPeriodsNote, hasOlderStatements, stalePeriodNote, statementHistoryNotes } from "../../utils/financial-statements";
 import { formatPerShareNumber } from "../../utils/reported-money";
 import { isCurrencyPairListing } from "../../utils/fx-market-hours";
 import {
@@ -130,6 +131,7 @@ import {
   historyCoverageWarning,
   historyFacts,
   historyFlagNote,
+  historyWickNote,
   historyGapNote,
   historyJumpNote,
   historyUnbrokenFrom,
@@ -165,6 +167,7 @@ import { bareFuturesCode, futuresBoardContract } from "../../market-data/futures
 import { commodityNamedIn, commoditySearchName } from "../../market-data/commodity-names";
 import { newsEmptyMessage } from "./news-hints";
 import {
+  closestStoriesReason,
   commodityNewsRoute,
   commonWordCandidate,
   METALS_NEWS_TOPIC,
@@ -179,6 +182,7 @@ import {
   noMetalStoriesMessage,
   noStoriesMessage,
   quotedSearchCommand,
+  searchClosestNewsStories,
   searchNewsStories,
   wordMeansMore,
 } from "./news-search";
@@ -189,7 +193,7 @@ import { exportedFundamentals } from "../../utils/price-earnings";
 import { fundamentalsFreshness, fxPairFreshness, quotesFreshness, rowsFreshness, valuationFreshness } from "../freshness";
 import { fxRateNotes } from "../../plugins/builtin/shared/fx-rate-freshness";
 import { quoteBarNotes } from "../../market-data/quotes/intraday-bar";
-import { depositaryPairText, isReceiptSide, listingDepositaryPair } from "../../market-data/depositary-pair";
+import { cedearRatioText, depositaryPairText, isReceiptSide, listingCedearRatio, listingDepositaryPair } from "../../market-data/depositary-pair";
 import { isPesoDollarPair, loadPesoDollarRates, pesoDollarRateLines, pesoDollarRatesJson } from "../peso-dollar-rates";
 import { atRegularSessionPrice, regularSessionValuationPrice } from "../../market-data/quotes/regular-session-valuation";
 import { viewMarketCapitalization } from "../../utils/market-capitalization";
@@ -199,6 +203,7 @@ import {
   cloudNewsFreshness,
   cloudRealtimeAccess,
   REPORTED_DATA,
+  SEC_FILING_ROWS,
   SEC_FILINGS,
 } from "../../plugins/builtin/shared/report-freshness";
 import {
@@ -242,7 +247,7 @@ import {
   type ListingIdentity,
 } from "../listing-arg";
 import { bareListingNote, listingFateNotes, noLongerTradingNote, tradingListing } from "../../tickers/listing-fate";
-import { isYieldIndexSymbol } from "../index-roots";
+import { isYieldIndexSymbol } from "../../tickers/index-roots";
 import {
   analyzeTaxEquivalent, distributionBasis, loadTreasuryTenors, parseTaxRates, TAX_RATE_HELP_OPTIONS, taxEquivalentJson, type TaxRates,
 } from "../../market-data/tax-equivalent";
@@ -913,7 +918,7 @@ function corporateActionRows(data: CorporateActionsData) {
     ...declaredDividends(data).map((event) => ({
       type: "dividend",
       date: event.exDate,
-      detail: `declared ${currency ? formatDistributionAmount(event.amount, currency) : cleanDecimal(event.amount)}`
+      detail: `declared ${event.special ? "special " : ""}${currency ? formatDistributionAmount(event.amount, currency) : cleanDecimal(event.amount)}`
         + (event.payDate ? `, payable ${event.payDate}` : ""),
     })),
     ...data.splits.map((event) => ({
@@ -1105,8 +1110,10 @@ async function runQuote(rawArgs: string[], ctx: Parameters<CliCommandDef["execut
         const quiet = ended ? null : noPrintsTodayText(row.quote, now);
         return [ended ?? (quiet ? `${label}: ${quiet}` : []), quoteBarNotes(label, row.quote, now)].flat();
       }),
-      // A receipt and its home line each say the ratio, as `ticker` does.
+      // A receipt and its home line each say the ratio, as `ticker` does; a CEDEAR names itself in its own.
       ...data.flatMap((row) => {
+        const cedear = listingCedearRatio({ quote: row.quote });
+        if (cedear) return [`${cedearRatioText(cedear)}.`];
         const pair = listingDepositaryPair({ quote: row.quote });
         return pair ? [`${row.target.symbol}: ${depositaryPairText(pair, isReceiptSide({ quote: row.quote }))}.`] : [];
       }),
@@ -1458,7 +1465,7 @@ async function loadListingHistory(
     ...window ? [...windowHistoryNotes(window, data), coverage ?? []]
       : range === "YTD" ? ytdHistoryNotes(data) : [...historyNotes(range, interval, data[0]?.date, Date.now(), coverage != null), coverage ?? []],
     // The status line says how far a bar still forming runs; the note is for the bars it does not name.
-    gaps ?? [], historyJumpNote(data) ?? [], historyFlagNote(data) ?? [], historyMissingVolumeNote(data) ?? [],
+    gaps ?? [], historyJumpNote(data) ?? [], historyFlagNote(data) ?? [], historyWickNote(data) ?? [], historyMissingVolumeNote(data) ?? [],
     historyVenueVolumeNote(data) ?? [],
     historyBarStatusNote(forming ? served : data, { tradingDay: venueTradingDay(venue, Date.now()) }) ?? [],
   ].flat();
@@ -1875,7 +1882,11 @@ async function runFinancials(rawArgs: string[], ctx: Parameters<CliCommandDef["e
     // Years filled from the listing's exchange, for the revenue and net income columns.
     const filled = filledPeriodsNote(financials.annualStatements.filter((statement) => rows.some((row) => row.date === statement.date)),
       new Set(["totalRevenue", "netIncome"]));
-    const historyNotes = [...stale ? [stale] : [], ...filled ? [filled] : [], ...statementHistoryNotes("annual", rows.map((row) => row.date), listing.key)];
+    // GF is pointed to only when the listing's extended history goes further back than these years.
+    const dates = rows.map((row) => row.date);
+    const older = await hasOlderStatements(() => market.dataProvider.getTickerFinancials(listing.request.symbol, listing.request.exchange,
+      { statementHistory: "extended" }), "annual", dates);
+    const historyNotes = [...stale ? [stale] : [], ...filled ? [filled] : [], ...statementHistoryNotes("annual", dates, listing.key, older)];
     // NDJSON keeps the raw statement rows it always wrote; CSV gets the table and its closing lines.
     const tables = tabular
       ? selectTables({
@@ -1932,26 +1943,29 @@ const NEWS_COLUMNS = [
 async function printNewsSearch(
   text: string,
   articles: NewsArticle[],
-  { reason, empty, commodity = true, failure, ticker = null }: {
+  { reason, empty, commodity = true, failure, ticker = null, closest = false }: {
     reason?: string;
     empty?: string;
     commodity?: boolean;
     failure?: string;
     /** The listing a coin pair's search stands in for. */
     ticker?: string | null;
+    /** No story has every word: these are the ones with the most. */
+    closest?: boolean;
   },
   ctx: Parameters<CliCommandDef["execute"]>[1],
 ) {
   const searched = failure === undefined;
   const named = searched && commodity && articles.length === 0 && commodityNamedIn(text) !== null;
   const route = named ? await commodityNewsRoute(text) : null;
+  const closestReason = closest && articles.length > 0 ? closestStoriesReason(text) : null;
   ctx.printResult({
     data: articles,
     ...(searched ? {} : { warnings: [`Searching stories for "${text}" failed: ${failure}`] }),
-    metadata: { ticker, search: text, feed: null, ...(route ? { futuresNews: route.command } : {}) },
+    metadata: { ticker, search: text, feed: null, ...(closestReason ? { match: "closest" } : {}), ...(route ? { futuresNews: route.command } : {}) },
     freshness: rowsFreshness(newsRows(articles), cloudNewsFreshness(await cloudRealtimeAccess())),
   }, {
-    heading: newsSearchHeading(text, reason),
+    heading: newsSearchHeading(text, [reason, closestReason].filter(Boolean).join("  ·  ") || undefined),
     rows: newsRows,
     columns: NEWS_COLUMNS,
     empty: named ? noStoriesMessage(text, route) : empty ?? (searched ? noStoriesMessage(text, null) : "No stories to show."),
@@ -2013,7 +2027,8 @@ async function runNews(rawArgs: string[], ctx: Parameters<CliCommandDef["execute
     if (exchangeOption || feed) ctx.fail(`${exchangeOption ? "--exchange" : "--feed"} goes with a symbol, not with text to search stories for.`, "Usage: gloom news <query>");
     const problem = newsSearchTextProblem(text);
     if (problem) ctx.fail(problem);
-    await printNewsSearch(text, await searchNewsStories(text, limit), {}, ctx);
+    const answer = await searchClosestNewsStories(text, limit);
+    await printNewsSearch(text, answer.found, { closest: answer.closest }, ctx);
     return;
   }
   // A metal's future or name is its market's news, not a company's: GOLD in capitals stays Gold.com's.
@@ -2193,7 +2208,7 @@ async function runFilings(rawArgs: string[], ctx: Parameters<CliCommandDef["exec
           ...listingMetadata(resolved), ...(form ? { form } : {}),
           ...(page ? { announcementsPage: page.url } : {}),
         },
-        freshness: rowsFreshness(filingRows(filings), { ...SEC_FILINGS, observedKey: "filingDate" }),
+        freshness: rowsFreshness(filingRows(filings), SEC_FILING_ROWS),
         ...(choice.length > 0 ? { warnings: choice } : {}),
       }, {
         heading: listingHeading(resolved),
@@ -2205,7 +2220,7 @@ async function runFilings(rawArgs: string[], ctx: Parameters<CliCommandDef["exec
         empty: [form ? `No ${form} filings found for ${listingTitle(resolved)}.`
           : identity ? noSecReportsNotice(resolved)
           : `No SEC filings found for ${listingTitle(resolved)}.`, pageLine].filter(Boolean).join("\n"),
-        ...(pageLine ? { footnote: pageLine, exportNotes: [pageLine] } : {}),
+        ...filingsFootnote(pageLine, filings[0]?.companyFrom),
       });
     } catch (error) {
       if (!(error instanceof SecRegistrantMismatchError)) throw error;
@@ -2223,6 +2238,16 @@ async function runFilings(rawArgs: string[], ctx: Parameters<CliCommandDef["exec
   });
 }
 
+/**
+ * The lines `filings` prints under its rows and CSV writes as notes: an ASX
+ * listing's announcements page, and whose filings a foreign line shows when
+ * they are its company's home line's.
+ */
+function filingsFootnote(pageLine: string | null | undefined, companyFrom: CompanyFrom | undefined): { footnote?: string; exportNotes?: string[] } {
+  const lines = [...(pageLine ? [pageLine] : []), ...companyDataNotes(companyFrom)];
+  return lines.length ? { footnote: lines.join("\n"), exportNotes: lines } : {};
+}
+
 /**
  * `filings` for a company on ASX that files nothing with the SEC: its latest
  * ASX announcements from Gloom Cloud, newest first, under the line saying it
@@ -2393,7 +2418,8 @@ async function printBeneficialOwners(
     heading: `${listingHeading(identity)}${cliStyles.muted(beneficialListFacts(payload, form, rows.length, history).map((fact) => `  ·  ${fact}`).join(""))}`,
     // Text draws each column as the HDS report does; CSV and JSON keep the raw values.
     textColumns: BENEFICIAL_REPORT_COLUMNS.map((column) => ({ ...column, format: column.textFormat ?? column.format })),
-    ...(legend ? { footnote: legend } : {}),
+    // A foreign line's owners read from its company's home line say whose.
+    ...(legend || payload.companyFrom ? { footnote: [legend, ...companyDataNotes(payload.companyFrom)].filter(Boolean).join("\n") } : {}),
     columns: [
       ...BENEFICIAL_REPORT_COLUMNS.map(({ key, header, align }) => ({ key, header, ...(align ? { align } : {}) })),
       { key: "otherPersons", header: "Other persons" },
@@ -2494,7 +2520,7 @@ async function runHolders(
     const columns = holderReportColumns(shownRows, valueCurrency);
     // Dated as HDS dates it: by the list's as-of; an insider report of Form 4 filings alone as INS dates it, by the newest.
     const freshness = form4Only
-      ? rowsFreshness(form4?.newestFiled ? [{ filingDate: form4.newestFiled }] : [], { ...SEC_FILINGS, basis: "Form 4 filings", observedKey: "filingDate" })
+      ? rowsFreshness(form4?.newestFiled ? [{ filingDate: form4.newestFiled }] : [], { ...SEC_FILING_ROWS, basis: "Form 4 filings" })
       : rowsFreshness(shownRows, { ...SEC_FILINGS, basis: "13F filings" }, { asOf: data.asOf ?? null });
     // Named as fn HDS takes it, so the closing notes point to the same listing.
     const requested = exchangeOption && !raw.includes(":") ? `${raw}:${exchangeOption.toUpperCase()}` : raw;
@@ -2564,6 +2590,8 @@ async function runHolders(
         insiderCommand ? insiderSummary(data, listing, identity, form4) : "",
       ].filter(Boolean).join("\n"),
       empty: `No holders reported for ${listingTitle(identity)}.`,
+      // Holders read from the company's home line say whose; the SEC index's are the listing's own.
+      ...(!indexed && data.companyFrom ? { footnote: companyDataNotes(data.companyFrom).join("\n") } : {}),
     });
   });
 }
@@ -3257,7 +3285,7 @@ export const marketDataCliCommands: BuiltinCliCommandDef[] = [
         title: "Bars",
         lines: [
           `Each range comes in one bar size: ${historyIntervalsByRange()}. The line under the heading, and the --json metadata, give the currency, the bar size actually served, the first and last bar and the bar count. A warning says when the bars are coarser, or start later, than the range asked for, and for a coin, which trades every day, names each day it has no bar for.`,
-          "A bar whose prices contradict each other (high below the open or close, or low above them) is left blank and flagged, such as high<open, with the count in a warning. --json rows carry currency, unit, interval and flag.",
+          "A bar whose prices contradict each other (high below the open or close, or low above them) is left blank and flagged, such as high<open, with the count in a warning. A low under half the open and close, or a high over twice them, is left blank alone and flagged low<close/2 or high>2*open. --json rows carry currency, unit, interval and flag.",
           "A break in the series flags the bar after it, which keeps its prices: gap after more than three months with no bar (weeks for weekly, daily and intraday bars), jump when the close is over 100 times the one before or under a hundredth of it. A warning names each break, and the heading says the date the series runs unbroken from.",
           "The heading's last line is the max drawdown of the bars shown: the largest fall from a close to a later close, with the peak and the trough, their dates, and the date a close got back to the peak, if one did (maxDrawdown in --json).",
         ],

package/src/cli/commands/news-search.ts

@@ -82,6 +82,28 @@ export async function searchNewsStories(text: string, limit: number, topics?: re
   return response.items.map((item) => mapCloudNewsArticle(item));
 }
 
+/** A search's stories, and whether they are its closest ones because no story has every word. */
+export interface NewsSearchAnswer {
+  found: NewsArticle[];
+  closest: boolean;
+}
+
+/**
+ * The stories matching the text; when no story has every word of a search of
+ * several, the ones with the most of them, most words first. Spellings of
+ * one word are one word to the service: lockup, lock-up and lock up;
+ * spinoff and spin-off; expiry and expiration.
+ */
+export async function searchClosestNewsStories(text: string, limit: number): Promise<NewsSearchAnswer> {
+  const response = await apiClient.searchCloudNews(text, limit, undefined, { closest: true });
+  return { found: response.items.map((item) => mapCloudNewsArticle(item)), closest: response.match === "closest" };
+}
+
+/** What the heading says of a search no story has every word of. */
+export function closestStoriesReason(text: string): string {
+  return `no story has every word of "${text}"; the closest, most words first`;
+}
+
 /** The NI code of the metal markets: prices, futures, bullion and the trusts that hold it, not a miner's releases. */
 export const METALS_NEWS_TOPIC = "metals";
 

package/src/cli/commands/overview.ts

@@ -2,7 +2,7 @@ import { logFailure } from "../../utils/log-failure";
 import { apiClient } from "../../api-client";
 import { ApiRequestError } 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";
@@ -25,17 +25,27 @@ import {
 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,
@@ -303,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()]!;
@@ -470,13 +480,15 @@ 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 now = Date.now();
     const todayStart = Math.floor(now / DAY_MS) * DAY_MS;
@@ -487,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));
@@ -506,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;
@@ -522,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,
@@ -553,15 +569,20 @@ async function runEcon(args: string[], ctx: Parameters<CliCommandDef["execute"]>
     // 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,
@@ -607,6 +628,35 @@ 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 (a series Gloom Cloud no
+ * longer serves, access denied) is said, not covered: `loadCachedFredSeries`
+ * throws it.
+ */
+async function loadFredSeries(
+  seriesId: string,
+  params: { startDate?: string; limit?: number; sortOrder: "asc" | "desc" },
+): Promise<CloudFredSeriesPayload> {
+  return (await loadCachedFredSeries({ seriesId, ...params }, () => apiClient.getCloudFredSeries(seriesId, params))).data;
+}
+
 async function runFredList(filter: string, ctx: Parameters<CliCommandDef["execute"]>[1]) {
   let catalog;
   try {
@@ -652,9 +702,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;
   });
@@ -668,7 +728,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 } : {}),
@@ -687,7 +749,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")) {
@@ -759,10 +821,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.
@@ -775,7 +839,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.
@@ -907,10 +971,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

@@ -16,6 +16,7 @@ import {
   candidateExchange,
   LISTING_SEARCH_LIMIT,
   listingDistance,
+  primaryCompanyLine,
   searchTickerCandidates,
   type TickerSearchCandidate,
 } from "../../tickers/search";
@@ -34,8 +35,7 @@ import { readBrokerIndexCode } from "../listing-arg";
 import { knownGapMessage, commandPointer } from "../known-gaps";
 import { instrumentTypeLabel } from "../../tickers/instrument-kind";
 import { canonicalExchange, isUsListingExchange } from "../../utils/exchanges";
-import { companyNameExtraWords, groupByCompany, sameCompany } from "../../tickers/company-name";
-import { namedByService } from "../../tickers/company-name-listing";
+import { companyLines, companyNameExtraWords, groupByCompany, namedByService, sameCompany } from "../../tickers/company-name";
 import { findCatalogSeries, renderSeriesMatches, type SeriesMatch } from "../series-search";
 import { centralBankAskedAbout, centralBankCiting, type CentralBank } from "../../utils/central-banks";
 import { createPaneCatalog } from "../pane-functions/discovery";
@@ -283,17 +283,17 @@ function withHomeListingPrimary(query: string, candidates: TickerSearchCandidate
     || primary.symbol.toUpperCase() === query.toUpperCase()) return candidates;
   const company = resolveSearchName(primary);
   const marked = !!primary.result && namedByService(query, primary.result);
-  const lines = candidates.filter((candidate) => candidate.kind === "search" && candidate.category !== "Funds & Derivatives"
-    && (candidate.instrumentClass === "equity" || candidate.instrumentClass === "other") && sameCompany(resolveSearchName(candidate), company)
-    && (!marked || companyNameExtraWords(resolveSearchName(candidate), company) != null));
-  const score = (candidate: TickerSearchCandidate) => candidate.result?.popularity ?? candidate.popularity ?? null;
-  const [home] = [...lines].sort((a, b) => listingDistance(a) - listingDistance(b) || (score(b) ?? -1) - (score(a) ?? -1) || candidates.indexOf(a) - candidates.indexOf(b));
-  if (!home || home === primary) return candidates;
-  const closer = listingDistance(home) < listingDistance(primary);
-  const [homeScore, primaryScore] = [score(home), score(primary)];
-  const moreSearched = !marked && listingDistance(home) === listingDistance(primary) && homeScore != null
-    && (primaryScore == null || homeScore >= primaryScore * 2);
-  if (!closer && !moreSearched) return candidates;
+  // Never a line of another business its name is in (`companyLines`): Siemens Energy AG is not Siemens AG's.
+  const lines = companyLines(primary, candidates.filter((candidate) => candidate === primary || (candidate.kind === "search"
+    && candidate.category !== "Funds & Derivatives" && (candidate.instrumentClass === "equity" || candidate.instrumentClass === "other"))),
+  (candidate) => ({
+    name: resolveSearchName(candidate), exchange: candidateExchange(candidate),
+    receipt: listingDistance(candidate) === 2, home: candidate.result?.homeListing === true,
+  })).filter((candidate) => candidate === primary || !marked || companyNameExtraWords(resolveSearchName(candidate), company) != null);
+  const home = primaryCompanyLine(primary, lines, (candidate) => ({
+    distance: listingDistance(candidate), score: candidate.result?.popularity ?? candidate.popularity ?? null,
+  }), { named: marked });
+  if (home === primary) return candidates;
   const rest = candidates.filter((candidate) => candidate !== home);
   const at = rest.indexOf(primary);
   return [...rest.slice(0, at), { ...home, category: "Primary Listing" as const }, { ...primary, category: "Other Listings" as const }, ...rest.slice(at + 1)];