@gloom-sh/terminal 0.18.5 → 0.19.1

package/src/plugins/builtin/shared/report-freshness.ts

@@ -1,3 +1,4 @@
+import { logFailure } from "../../../utils/log-failure";
 import type { HeadlessPaneFreshness } from "../../../types/headless";
 import type { Quote, QuoteIndexSession } from "../../../types/financials";
 import { isQuoteBeforeLatestSession, isQuoteStaleForCurrentSession } from "../../../market-data/quotes/freshness";
@@ -46,6 +47,14 @@ export function barResolutionFromDates(dates: readonly (string | number | Date)[
 /** Company filings read from EDGAR. Old filings are not stale; there is no schedule to miss. */
 export const SEC_FILINGS: HeadlessPaneFreshness = { source: "SEC EDGAR", status: "not-a-feed", basis: "filed data", oldest: null };
 
+/**
+ * A list of filings, dated by its newest one's filing date and by when it was
+ * read: `newest filing Tue 27 Oct 2026 · retrieved Wed 28 Oct 2026 19:07 UTC`.
+ */
+export const SEC_FILING_ROWS: HeadlessPaneFreshness = {
+  ...SEC_FILINGS, observedKey: "filingDate", asOfLabel: "newest filing", retrievedToo: true,
+};
+
 /**
  * What a filings view opened inside a pane that hosts others (Issuer Debt in
  * Fixed Income) declares as its template's `reportFreshness`, so a capture
@@ -129,8 +138,8 @@ export async function cloudRealtimeAccess(): Promise<boolean | null> {
   if (!apiClient.isSignedIn()) return false;
   try {
     return hasProAccess(apiClient.getCurrentUser() ?? await apiClient.getSession());
-  } catch {
-    return null;
+  } catch (error) {
+    return logFailure("shared.report-freshness", "Read Cloud plan for report freshness failed", null)(error);
   }
 }
 

package/src/plugins/builtin/shared/research-cells.tsx

@@ -14,7 +14,7 @@ import { displayWidth } from "../../../utils/format";
  */
 
 /** The one placeholder for a value the source does not give. */
-const NO_VALUE = "--";
+export const NO_VALUE = "--";
 
 export const missingCell = (colors: ThemeColors): DataTableCell => ({ text: NO_VALUE, value: null, color: colors.textMuted });
 

package/src/plugins/builtin/shared/series-cache.ts

@@ -74,9 +74,9 @@ export function createSeriesCache(kind: string, staleMs: number): SeriesCache {
   let generation = 0;
   let persistence: PluginPersistence | null = null;
   const withFailure = <T extends SeriesCacheLoadResult>(key: string, result: T): T => {
-    const failure = failures.get(key);
-    return failure
-      ? { ...result, stale: true, source: "stale-fallback", refreshError: failure }
+    // A failure is one whatever it said: an Error without a message still leaves the copy a saved one.
+    return failures.has(key)
+      ? { ...result, stale: true, source: "stale-fallback", refreshError: failures.get(key) }
       : result;
   };
   const loadEntry: SeriesCache["loadEntry"] = async (key, loader, options) => {
@@ -103,7 +103,7 @@ export function createSeriesCache(kind: string, staleMs: number): SeriesCache {
         if (owner === generation && requests.get(key) === request) requests.delete(key);
       }
     }, options);
-    return withFailure(key, { ...data, fetchedAt, stale, source, ...(refreshError ? { refreshError } : {}) });
+    return withFailure(key, { ...data, fetchedAt, stale, source, ...(source === "stale-fallback" ? { refreshError } : {}) });
   };
   const reset = () => {
     generation += 1;

package/src/plugins/builtin/shared/ticker-choice.tsx

@@ -1,3 +1,4 @@
+import { logFailure } from "../../../utils/log-failure";
 import { useCallback } from "react";
 import { ChoiceDialog } from "../../../components/ui/choice-dialog";
 import { t } from "../../../i18n";
@@ -29,6 +30,6 @@ export function useOpenTickerChoice(): (symbols: readonly string[]) => void {
       ),
     }).then((symbol) => {
       if (symbol) openTicker(symbol);
-    }).catch(() => {});
+    }).catch(logFailure("shared.ticker-choice", "Open ticker choice failed"));
   }, [dialog, openTicker]);
 }

package/src/plugins/builtin/shared/ticker-company.ts

@@ -0,0 +1,77 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+import { isNoSourceAnswer } from "../../../sources/provider-errors";
+import type { DataProvider } from "../../../types/data-provider";
+import { shortCompanyName } from "../../../tickers/company-name";
+import { classifyInstrumentKind } from "../../../tickers/search/ranking";
+
+/**
+ * A search typed as a ticker (`TRIAL VKTX`, `FDA AZN`): one to five letters,
+ * with a share class. Registries know companies by name, so a symbol no record
+ * mentions is looked up as its company.
+ */
+export function looksLikeTicker(term: string): boolean {
+  return /^[A-Za-z]{1,5}(?:[.-][A-Za-z])?$/.test(term.trim());
+}
+
+/**
+ * The company a ticker is, by the name a registry files its records under:
+ * VKTX is "Viking Therapeutics", AZN "AstraZeneca". Read from the listing's
+ * quote, which names it; a fund or a contract is no company. Null when no
+ * share trades under it. A quote that could not be read (unreachable, busy,
+ * timed out) rejects: it says nothing about the company.
+ */
+export async function tickerCompanyName(dataProvider: Pick<DataProvider, "getQuote"> | null, ticker: string): Promise<string | null> {
+  const symbol = ticker.trim().toUpperCase();
+  if (!dataProvider || !symbol) return null;
+  const quote = await dataProvider.getQuote(symbol).catch((error: unknown) => {
+    if (isNoSourceAnswer(error)) return null;
+    throw error;
+  });
+  const name = quote?.name?.trim();
+  const kind = classifyInstrumentKind(quote?.instrumentType);
+  return name && kind !== "fund" && kind !== "derivative" ? shortCompanyName(name) : null;
+}
+
+export interface TickerCompanySearch {
+  /** The company is being looked up: the pane shows it loading. */
+  resolving: boolean;
+  /** The lookup failed, for the pane's unavailable state; null otherwise. */
+  error: string | null;
+  /** Looks again after a failure: the pane's refresh calls it. */
+  retry: () => void;
+}
+
+/**
+ * A search for a ticker that found nothing is searched again as its company's
+ * name: `onCompany` runs with it, once per `key` (the term as the pane compares
+ * it). `eligible` is true once the search has finished empty and the term reads
+ * as a ticker. A lookup that failed is no answer: it reports `error` until
+ * `retry`, or until the term changes and comes back.
+ */
+export function useTickerCompanySearch(
+  dataProvider: Pick<DataProvider, "getQuote"> | null,
+  term: string,
+  { eligible, key, onCompany }: { eligible: boolean; key: string; onCompany: (name: string) => void },
+): TickerCompanySearch {
+  const [looked, setLooked] = useState<ReadonlySet<string>>(() => new Set());
+  const [failed, setFailed] = useState<string | null>(null);
+  // A failure belongs to its term: another search clears it, so coming back looks again.
+  if (failed !== null && failed !== key) setFailed(null);
+  const onCompanyRef = useRef(onCompany);
+  onCompanyRef.current = onCompany;
+  const resolving = eligible && !looked.has(key) && failed !== key;
+  useEffect(() => {
+    if (!resolving) return;
+    let live = true;
+    tickerCompanyName(dataProvider, term).then((name) => {
+      if (!live) return;
+      setLooked((current) => new Set([...current, key]));
+      if (name) onCompanyRef.current(name);
+    }, () => {
+      if (live) setFailed(key);
+    });
+    return () => { live = false; };
+  }, [dataProvider, key, resolving, term]);
+  const retry = useCallback(() => setFailed(null), []);
+  return { resolving, error: eligible && failed === key ? `Couldn't look up ${term}'s company.` : null, retry };
+}

package/src/plugins/builtin/shared/use-quote-board.ts

@@ -1,3 +1,4 @@
+import { logFailure } from "../../../utils/log-failure";
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import type { DataTableCell, DataTableVisibleRange, PaneFooterSegment } from "../../../components";
 import { savedCopyFooterSegment } from "../../../components/layout/pane/footer/model";
@@ -341,7 +342,7 @@ export function useQuoteBoard(symbols: string[], options: QuoteBoardOptions = {}
         if (fetchGenRef.current !== gen) return;
         setSnapshots((prev) => paintCachedQuotes(prev, cached));
       })
-      .catch(() => {});
+      .catch(logFailure("shared.use-quote-board", "Paint cached board quotes failed"));
   }, [dataProvider]);
 
   /** The cache-first full load: the listed symbols' cached quotes at once, then from the network. */

package/src/plugins/builtin/shared/volatility/live-session.ts

@@ -112,6 +112,21 @@ export function useOptionsSessionOpen(enabled = true): boolean {
   return state.nextChangeAt != null && Date.now() >= state.nextChangeAt ? usOptionsSession(Date.now()).open : state.open;
 }
 
+export interface LiveSessionRefresh {
+  /** The refresh cycle is running, which is what "live" means. */
+  live: boolean;
+  /**
+   * Why the last refresh failed, until one succeeds or the cycle stops. The
+   * data it would have replaced stays on screen, so the pane shows this where
+   * it shows its own failed refreshes.
+   */
+  error: string | null;
+}
+
+function isCancellation(error: unknown): boolean {
+  return !!error && typeof error === "object" && (error as { name?: unknown }).name === "AbortError";
+}
+
 /**
  * Calls `refresh` every `intervalMs` while enabled, the pane can be seen (the
  * app is visible and the pane is not covered) and the options market is open.
@@ -119,18 +134,19 @@ export function useOptionsSessionOpen(enabled = true): boolean {
  * after the caller's own load (`loadedAt`); returning after a hidden or
  * covered stretch, or reaching the open, more than an interval after the last
  * data fires straight away. A refresh still in flight is never overlapped by
- * the next. Returns whether the refresh cycle is running, which is what
- * "live" means.
+ * the next. A refresh that throws or rejects is reported as `error` until the
+ * next one succeeds; a cancelled one (an AbortError) is no failure.
  */
 export function useLiveSessionRefresh(
   refresh: () => void | Promise<unknown>,
   intervalMs: number,
   enabled: boolean,
   loadedAt?: number | null,
-): boolean {
+): LiveSessionRefresh {
   const visible = usePaneVisible();
   const open = useOptionsSessionOpen(enabled);
   const active = enabled && visible && open;
+  const [error, setError] = useState<string | null>(null);
   const refreshRef = useRef(refresh);
   refreshRef.current = refresh;
   const lastRef = useRef(Date.now());
@@ -142,21 +158,31 @@ export function useLiveSessionRefresh(
     let cancelled = false;
     // A load the caller finished itself counts as the latest refresh.
     if (loadedAtRef.current != null && loadedAtRef.current > lastRef.current) lastRef.current = loadedAtRef.current;
+    const succeeded = () => { if (!cancelled) setError(null); };
+    const failed = (failure: unknown) => {
+      if (cancelled || isCancellation(failure)) return;
+      const message = (failure instanceof Error ? failure.message : String(failure ?? "")).trim();
+      setError(message || "Live refresh failed");
+    };
     const run = () => {
       if (inFlight || cancelled) return;
       lastRef.current = Date.now();
       let pending: void | Promise<unknown>;
-      try { pending = refreshRef.current(); } catch { return; }
+      try { pending = refreshRef.current(); } catch (failure) {
+        failed(failure);
+        return;
+      }
       if (pending && typeof (pending as Promise<unknown>).then === "function") {
         inFlight = true;
-        void (pending as Promise<unknown>).catch(() => {}).finally(() => { inFlight = false; });
-      }
+        void (pending as Promise<unknown>).then(succeeded, failed).finally(() => { inFlight = false; });
+      } else succeeded();
     };
     if (Date.now() - lastRef.current >= intervalMs) run();
     const timer = setInterval(run, intervalMs);
-    return () => { cancelled = true; clearInterval(timer); };
+    // A stopped cycle's failure is old news: the pane's own loads take over.
+    return () => { cancelled = true; clearInterval(timer); setError(null); };
   }, [active, intervalMs]);
-  return active;
+  return { live: active, error: active ? error : null };
 }
 
 /**

package/src/plugins/builtin/shared/volatility/pricing.ts

@@ -134,6 +134,25 @@ export function valueOption(input: OptionPricingInput): OptionValuation {
   };
 }
 
+/**
+ * The chance the underlying closes above `strike` at expiry under the same
+ * Black-Scholes-Merton model: N(d2), the risk-neutral probability a call there
+ * finishes in the money. 1 or 0 when nothing is left uncertain (expiry, zero
+ * volatility), by where the discounted forward sits.
+ */
+export function probabilityAbove(input: Omit<OptionPricingInput, "side">): number {
+  const spot = Math.max(0, finite(input.spot));
+  const strike = Math.max(0, finite(input.strike));
+  const years = Math.max(0, finite(input.daysToExpiry)) / DAYS_PER_YEAR;
+  const rate = finite(input.rate);
+  const dividendYield = finite(input.dividendYield);
+  const volatility = Math.max(0, finite(input.volatility));
+  if (strike <= 0) return 1;
+  if (years <= 0 || volatility <= 0 || spot <= 0) return spot * Math.exp((rate - dividendYield) * years) > strike ? 1 : 0;
+  const d2 = (Math.log(spot / strike) + (rate - dividendYield - volatility * volatility / 2) * years) / (volatility * Math.sqrt(years));
+  return normalCdf(d2);
+}
+
 export interface ImpliedVolatilityResult {
   volatility: number | null;
   /** Why no volatility could be solved, phrased for the pane body. */

package/src/plugins/builtin/shared/wall-view-lifecycle.ts

@@ -1,3 +1,5 @@
+import { logFailure } from "../../../utils/log-failure";
+
 type Arm = "control" | "teaser" | null;
 type TeaserKind = "summary" | "sample" | "none";
 const active = new Map<string, Set<object>>();
@@ -17,7 +19,7 @@ export function trackWallView({ identity, placement, exposure, currentIdentity,
   active.set(key, copies);
   let released = false;
   let reported = false;
-  const answer = exposure.catch(() => null);
+  const answer = exposure.catch(logFailure("shared.wall-view-lifecycle", "Resolve wall experiment arm failed", null));
 
   return {
     exposure: answer,

package/src/plugins/builtin/themes/model.ts

@@ -17,14 +17,16 @@ export function boardYtdBase(payload: { asOf?: unknown; regularSessionDate?: unk
 }
 
 /**
- * A period's header. YTD names its base close, as long as `room` allows:
- * `YTD vs 31 Dec close`, `YTD vs 31 Dec`, then `YTD 31 Dec`.
+ * A period's header. YTD says what it is, a return against the close it is
+ * measured from, as long as `room` allows: `YTD vs 31 Dec close`, `YTD vs 31
+ * Dec`, then `YTD`.
  */
 export function periodLabel(period: ThemePeriod, ytdBase: string | null, room = Infinity): string {
   if (period !== "returnYtdPercent" || !ytdBase) return PERIOD_LABELS[period];
-  const labels = [`YTD vs ${ytdBase} close`, `YTD vs ${ytdBase}`, `YTD ${ytdBase}`];
+  const labels = [`YTD vs ${ytdBase} close`, `YTD vs ${ytdBase}`, "YTD"];
   return labels.find((label) => label.length <= room) ?? labels.at(-1)!;
 }
+
 export interface ThemeSort { columnId: string; direction: SortDirection }
 export const DEFAULT_SORT: ThemeSort = { columnId: "changePercent", direction: "desc" };
 export function percent(value: number | null): string {
@@ -32,12 +34,17 @@ export function percent(value: number | null): string {
   const rounded = Number(value.toFixed(2));
   return `${rounded > 0 ? "+" : ""}${rounded.toFixed(2)}%`;
 }
+/** How many of a theme's names a figure is drawn from, when not all of them: `7 of 8`. Empty when every name is in it. */
+export function coverageText(metric: ThemeAggregate): string {
+  return metric.covered < metric.total ? `${metric.covered} of ${metric.total}` : "";
+}
 export function aggregateText(metric: ThemeAggregate, breadth = false): string {
   const value = breadth && metric.value !== null ? `${Math.round(metric.value)}%` : percent(metric.value);
-  return `${value}${metric.covered < metric.total ? ` ${metric.covered}/${metric.total}` : ""}`;
+  const coverage = coverageText(metric);
+  return `${value}${coverage ? ` ${coverage}` : ""}`;
 }
 export const memberPrice = (value: number | null) => value === null ? "--" : value.toLocaleString("en-US", { minimumFractionDigits: 2, maximumFractionDigits: 2 });
-export const coverageWidth = (metrics: readonly ThemeAggregate[]) => Math.max(0, ...metrics.map((metric) => metric.covered < metric.total ? `${metric.covered}/${metric.total}`.length + 1 : 0));
+export const coverageWidth = (metrics: readonly ThemeAggregate[]) => Math.max(0, ...metrics.map((metric) => coverageText(metric) ? coverageText(metric).length + 1 : 0));
 export function sortThemes(rows: readonly ThemeSummary[], sort: ThemeSort): ThemeSummary[] {
   const value = (row: ThemeSummary) => {
     if (sort.columnId === "name") return row.name;
@@ -152,9 +159,11 @@ export function themeColumns(width: number, rows: readonly ThemeSummary[], ytdBa
   const metricWidth = (period: ThemePeriod) => Math.max(8, ...rows.map((row) => percent(row.returns[period].value).length)) + suffixWidth(period);
   // The same trailing space is reserved in every cell and its header. A note
   // occupies that space without moving the number away from its label.
-  const label = (period: ThemePeriod, room?: number) => periodLabel(period, ytdBase, room) + " ".repeat(suffixWidth(period));
+  const label = (period: ThemePeriod, room: number) => periodLabel(period, ytdBase, room) + " ".repeat(suffixWidth(period));
+  // The board always keeps room for `YTD vs 31 Dec`, so even a narrow one says what its YTD is measured against.
+  const leastRoom = ytdBase ? `YTD vs ${ytdBase}`.length : 0;
   const columns = [column("name", "Theme", 26, "left"), column("memberCount", "N", 3),
-    ...THEME_PERIODS.map((period) => column(period, label(period, 0), Math.max(metricWidth(period), label(period, 0).length + HEADER_ROOM))),
+    ...THEME_PERIODS.map((period) => column(period, label(period, leastRoom), Math.max(metricWidth(period), label(period, leastRoom).length + HEADER_ROOM))),
     column("breadth", "Breadth" + " ".repeat(coverageWidth(rows.map((row) => row.breadth))), 7 + coverageWidth(rows.map((row) => row.breadth))),
     column("best", "Best 1D", 15), column("worst", "Worst 1D", 15)];
   const fitted = fitColumns(columns, width, ["worst", "best", "return3MPercent", "returnYtdPercent", "return1MPercent", "return1WPercent", "memberCount"]);

package/src/plugins/builtin/themes/pane.tsx

@@ -5,14 +5,14 @@ import { usePaneRefreshKey } from "../../../components/data-table/table-pane";
 import type { ExtendedSession } from "../../../market-data/market/status";
 import { useAsyncResource, useAutoRefresh, usePluginPaneState, usePluginTickerActions, useUpdatedAgo } from "../../../public/react";
 import { usePaneInstance } from "../../../state/app/context";
-import { priceColor, shownPriceColor } from "../../../theme/colors";
+import { shownPriceColor } from "../../../theme/colors";
 import { useThemeColors } from "../../../theme/theme-context";
 import { Box, Text } from "../../../ui";
 import { nextHeaderSort } from "../../../utils/sort-values";
 import { useMembersMenu } from "../shared/members-menu";
 import { cachedMembers, cachedThemes, loadMembers, loadThemes } from "./client";
 import {
-  aggregateText, boardYtdBase, coverageWidth, DEFAULT_SORT, extendedMove, matchTheme, memberColumns, memberExtendedSessions, memberPrice, percent,
+  aggregateText, boardYtdBase, coverageText, coverageWidth, DEFAULT_SORT, extendedMove, matchTheme, memberColumns, memberExtendedSessions, memberPrice, percent,
   isLiveBoard, LIVE_BOARD_REFRESH_MS, SNAPSHOT_STALE_MS, snapshotFooterText, sortMembers, sortThemes, themeColumns, type ThemeSort,
 } from "./model";
 
@@ -135,14 +135,14 @@ export function ThemesBoard({ width, height, focused, tabStrip, tabRows = 0 }: T
     if (column.id === "best" || column.id === "worst") {
       const member = row[column.id];
       return { text: member ? `${member.symbol} ${percent(member.changePercent)}` : "--", value: member?.changePercent ?? null,
-        color: member ? priceColor(member.changePercent, colors) : colors.textMuted };
+        color: member ? shownPriceColor(member.changePercent, 2, colors) : colors.textMuted };
     }
     const breadth = column.id === "breadth";
     const metric = breadth ? row.breadth : row.returns[column.id as ThemePeriod];
     const suffixWidth = coverageWidth((data?.themes ?? []).map((theme) => breadth ? theme.breadth : theme.returns[column.id as ThemePeriod]));
-    const color = metric.value === null || breadth ? colors.textMuted : priceColor(metric.value, colors);
+    const color = metric.value === null || breadth ? colors.textMuted : shownPriceColor(metric.value, 2, colors);
     const valueText = breadth && metric.value !== null ? `${Math.round(metric.value)}%` : percent(metric.value);
-    const suffix = metric.covered < metric.total ? `${metric.covered}/${metric.total}` : "";
+    const suffix = coverageText(metric);
     return { text: aggregateText(metric, breadth), value: metric.value,
       color, content: suffixWidth ? <Box flexDirection="row" width={column.width} justifyContent="flex-end">
         <Text fg={color}>{valueText}</Text><Text fg={colors.textMuted}>{suffix.padStart(suffixWidth)}</Text>

package/src/plugins/builtin/thirteenf/api.ts

@@ -31,6 +31,12 @@ const FORMS_13F_CACHE_POLICY = {
 
 export interface Forms13FReadOptions {
   onWarning?: (warning: string) => void;
+  /**
+   * A read answered from the copy saved at `savedAt` (ms) because its refresh
+   * failed, said by when it was saved (a command's closing line) instead of
+   * as an `onWarning` line.
+   */
+  onSavedCopy?: (savedAt: number) => void;
   forceRefresh?: boolean;
 }
 
@@ -157,7 +163,12 @@ async function fetchForms13F<T>(
       const retained = options.cache !== false
         ? store?.getResource<T>(CACHE_KIND, key, { ...cacheOptions, allowExpired: true }) : null;
       // A caller may retain old research only when it can surface its provenance.
-      if (!retained || !options.onWarning) throw error;
+      if (!retained) throw error;
+      if (options.onSavedCopy && Number.isFinite(retained.fetchedAt)) {
+        options.onSavedCopy(retained.fetchedAt);
+        return retained.value;
+      }
+      if (!options.onWarning) throw error;
       const retrieved = new Date(retained.fetchedAt);
       const age = Number.isFinite(retrieved.getTime()) ? `retrieved ${retrieved.toISOString()}` : "with unavailable retrieval time";
       const reason = (error instanceof Error ? error.message : String(error)).trim() || "Request failed";

package/src/plugins/builtin/thirteenf/data.ts

@@ -115,7 +115,7 @@ export async function loadBrowserRows(
   tab: ThirteenFBrowserTab,
   query: string,
   signal?: AbortSignal,
-  options: { forceRefresh?: boolean; offset?: number; limit?: number } = {},
+  options: Pick<Forms13FReadOptions, "forceRefresh" | "onSavedCopy"> & { offset?: number; limit?: number } = {},
 ): Promise<BrowserLoadResult> {
   const warnings: string[] = [];
   const result = await loadBrowserPage(tab, query, signal, { ...options, onWarning: warning => warnings.push(warning) });
@@ -136,13 +136,13 @@ async function loadBrowserPage(
   const offset = Math.max(0, options.offset ?? 0);
   const browserLimit = Math.max(1, options.limit ?? BROWSER_PAGE_LIMIT);
   const latestLimit = Math.max(1, options.limit ?? LATEST_FILINGS_PAGE_LIMIT);
-  const apiOptions = { forceRefresh: options.forceRefresh, onWarning: options.onWarning };
+  const apiOptions = { forceRefresh: options.forceRefresh, onWarning: options.onWarning, onSavedCopy: options.onSavedCopy };
   const pageApiOptions = { ...apiOptions, offset };
 
   if (tab === "performance") {
     const topFunds = await listTopThirteenFFunds(quarter, browserLimit, signal, pageApiOptions);
     const quarters = priorQuarters(quarter);
-    const history = await loadRankingHistory(quarters, signal, { ...apiOptions, onWarning: options.onWarning });
+    const history = await loadRankingHistory(quarters, signal, apiOptions);
     const funds: ThirteenFFund[] = topFunds.map((fund) => ({ cik: fund.cik, name: fund.name }));
     const rows = buildBrowserRows({ topFunds, source: "performance" }).map(row => ({ ...row, priorReturns: quarters.map((previous, index) => ({ quarter: previous, value: history[index]?.get(row.cik) ?? null })) }));
     const result: BrowserLoadResult = {
@@ -437,10 +437,10 @@ export async function loadFundPerformance(
   cik: string,
   fallbackName: string,
   signal?: AbortSignal,
-  options: { forceRefresh?: boolean; splitFactor?: SplitFactorLookup } = {},
+  options: Pick<Forms13FReadOptions, "forceRefresh" | "onSavedCopy"> & { splitFactor?: SplitFactorLookup } = {},
 ): Promise<FundPerformanceResult> {
   const warnings: string[] = [];
-  const apiOptions = { forceRefresh: options.forceRefresh, onWarning: (warning: string) => warnings.push(warning) };
+  const apiOptions = { forceRefresh: options.forceRefresh, onSavedCopy: options.onSavedCopy, onWarning: (warning: string) => warnings.push(warning) };
   const detail = await loadFundDetail(cik, fallbackName, signal, options);
   const period = detail.latestForm?.periodOfReport;
   const quarter = period ? periodToQuarter(period) : null;
@@ -496,11 +496,11 @@ export async function loadFundDetail(
   fallbackName: string,
   signal?: AbortSignal,
   /** `filingGap: false` skips EDGAR's filing list, for a load that never shows it (an overlap). */
-  options: { forceRefresh?: boolean; filingGap?: boolean } = {},
+  options: Pick<Forms13FReadOptions, "forceRefresh" | "onSavedCopy"> & { filingGap?: boolean } = {},
 ): Promise<FundDetailData> {
   const now = new Date();
   const warnings: string[] = [];
-  const apiOptions = { forceRefresh: options.forceRefresh, onWarning: (warning: string) => warnings.push(warning) };
+  const apiOptions = { forceRefresh: options.forceRefresh, onSavedCopy: options.onSavedCopy, onWarning: (warning: string) => warnings.push(warning) };
 
   const forms = await listThirteenFForms(
     cik,

package/src/plugins/builtin/thirteenf/headless.ts

@@ -6,6 +6,7 @@ import type {
   HeadlessShotState,
 } from "../../../types/plugin";
 import { formatShortDate } from "../../../utils/datetime-format";
+import { servedFromSavedCopy } from "../../../data/saved-copies";
 import { normalizeCik, searchThirteenFFunds, TOP_FUNDS_MAX_LIMIT } from "./api";
 import { ApiRequestError } from "../../../api-client/errors";
 import { REPORT_PAGE, REPORT_ROWS } from "../shared/headless-options";
@@ -229,15 +230,40 @@ export interface ThirteenFHeadlessDependencies {
   loadEtfHoldings?(ticker: string, ctx: HeadlessPaneContext): Promise<FundMembersPayload>;
 }
 
+/** The oldest copy a load's 13F reads answered from because their refresh failed, by the load's context. */
+const savedCopies = new WeakMap<HeadlessPaneContext, { savedAt: number | null }>();
+
+/** How a 13F read for the load `ctx` says it answered from the copy saved at `savedAt`. */
+const noteSavedCopy = (ctx: HeadlessPaneContext) => (savedAt: number) => {
+  const entry = savedCopies.get(ctx);
+  if (entry) entry.savedAt = Math.min(entry.savedAt ?? savedAt, savedAt);
+};
+
+/**
+ * One load, whose report ends with when the oldest saved copy it answered
+ * from was saved (`couldn't refresh; saved copy from <time>`), as every
+ * command says it, instead of listing each failed refresh as an error.
+ */
+async function readingSavedCopies<T extends object>(ctx: HeadlessPaneContext, run: () => Promise<T>): Promise<T> {
+  const entry: { savedAt: number | null } = { savedAt: null };
+  savedCopies.set(ctx, entry);
+  try {
+    const result = await run();
+    return entry.savedAt == null ? result : servedFromSavedCopy(result, entry.savedAt);
+  } finally {
+    if (savedCopies.get(ctx) === entry) savedCopies.delete(ctx);
+  }
+}
+
 const defaultDependencies: Required<ThirteenFHeadlessDependencies> = {
   loadBrowser: (tab, query, limit, _args, ctx) => loadBrowserRows(
     tab,
     query,
     ctx.signal,
-    { limit },
+    { limit, onSavedCopy: noteSavedCopy(ctx) },
   ),
   // An overlap never shows a fund's missed quarter, so it does not ask EDGAR.
-  loadDetail: (cik, name, args, ctx) => loadFundDetail(cik, name, ctx.signal, { filingGap: !isOverlapLoad(args) }),
+  loadDetail: (cik, name, args, ctx) => loadFundDetail(cik, name, ctx.signal, { filingGap: !isOverlapLoad(args), onSavedCopy: noteSavedCopy(ctx) }),
   loadSplitFactors: (detail, ctx) => loadSplitFactors(
     detail,
     (ticker, after, through) => corporateSplitFactor(ctx.marketData, ticker, after, through),
@@ -247,6 +273,7 @@ const defaultDependencies: Required<ThirteenFHeadlessDependencies> = {
   searchFunds: (query, ctx) => searchThirteenFFunds(query, THIRTEENF_MAX_LIMIT, ctx.signal),
   loadPerformance: (cik, name, ctx) => loadFundPerformance(cik, name, ctx.signal, {
     splitFactor: (ticker, after, through) => corporateSplitFactor(ctx.marketData, ticker, after, through),
+    onSavedCopy: noteSavedCopy(ctx),
   }),
   loadEtfFunds: async (ctx) => (await fetchFunds(ctx.apiClient)).funds,
   loadEtfHoldings: (ticker, ctx) => fetchMembers(ticker, ctx.apiClient),
@@ -541,7 +568,7 @@ export function createThirteenFHeadless(
     ],
     describe: (args, result) => thirteenFTitle(args, result?.metadata),
     shotState: async (args, load) => thirteenFShotState(args, (await load()).metadata ?? {}),
-    async load(args, ctx) {
+    load: (args, ctx) => readingSavedCopies(ctx, async () => {
       const query = typeof args.argument === "string" ? args.argument.trim() : "";
       const requestedView = String(args.options.view) as HeadlessThirteenFView;
       const compare = typeof args.options.compare === "string" ? args.options.compare.trim() : "";
@@ -920,7 +947,7 @@ export function createThirteenFHeadless(
           ],
         },
       };
-    },
+    }),
   };
 }