@gloom-sh/terminal 0.19.0 → 0.19.1

package/src/plugins/builtin/risk-factors/headless.ts

@@ -1,4 +1,5 @@
 import type { HeadlessBundleSection, HeadlessPaneDefinition } from "../../../types/plugin";
+import { savedCopyMark, unansweredRefreshError } from "../../../data/saved-copies";
 import { loadRiskReportWithClient, loadRiskReportsWithClient, type RiskReportsResult } from "./data";
 import { SEC_FILINGS } from "../shared/report-freshness";
 import { resolveHeadlessIssuerListing } from "../shared/headless-market-data";
@@ -39,7 +40,8 @@ export const riskFactorsHeadless: HeadlessPaneDefinition<"bundle"> = {
     }
     const report = await loadRiskReportWithClient(context.apiClient, ticker, year, { force, listing });
     const sections: HeadlessBundleSection[] = [
-      { title: "Filing", entries: [
+      // A report served from a saved copy dates the report by when it was saved (the list does in the metadata).
+      { title: "Filing", ...savedCopyMark(report), entries: [
         { label: "Ticker", value: report.ticker },
         { label: "Filing year", value: report.reportYear },
         { label: "Filed", value: report.filedAt },
@@ -62,12 +64,13 @@ export const riskFactorsHeadless: HeadlessPaneDefinition<"bundle"> = {
       { key: "group", header: "Group" }, { key: "heading", header: "Heading" },
       { key: "excerpt", header: "Prior source excerpt" }, { key: "note", header: "Analysis" },
     ], rows: report.diff.removed.map((risk, index) => ({ ...risk, note: report.notes.removed.find((note) => note.index === index)?.text ?? null })) });
-    const errors = [list?.refreshError, report.refreshError].filter((error): error is string => !!error);
+    const errors = [unansweredRefreshError(list), unansweredRefreshError(report)].filter((error): error is string => !!error);
     return {
       sections,
       errors: errors.length ? errors : undefined,
       ...(list?.stale || report.stale ? { complete: false } : {}),
       metadata: {
+        ...savedCopyMark(list),
         ticker: report.ticker, requestedYear: selection, reportYear: report.reportYear,
         filedAt: report.filedAt, updatedAt: report.updatedAt, docUrl: report.docUrl,
         reportFetchedAt: report.fetchedAt, reportStale: report.stale,

package/src/plugins/builtin/roadmap/index.tsx

@@ -0,0 +1,28 @@
+import type { PluginModule } from "../plugin-module";
+import { RoadmapPane } from "./pane";
+
+export const roadmapModule: PluginModule = {
+  panes: [
+    {
+      id: "roadmap",
+      name: "Roadmap",
+      icon: "R",
+      component: RoadmapPane,
+      reportFreshness: { status: "not-a-feed", basis: "curated list" },
+      defaultPosition: "right",
+      defaultMode: "floating",
+      defaultFloatingSize: { width: 100, height: 30 },
+    },
+  ],
+
+  paneTemplates: [
+    {
+      id: "roadmap-pane",
+      paneId: "roadmap",
+      label: "Roadmap",
+      description: "What is being built, what is planned and what shipped. Pro members vote on what comes next.",
+      keywords: ["roadmap", "planned", "building", "shipped", "upcoming", "features", "vote", "votes", "request"],
+      shortcut: { prefix: "ROADMAP", aliases: ["RMAP"] },
+    },
+  ],
+};

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

@@ -0,0 +1,67 @@
+import type { RoadmapItem, RoadmapPayload, RoadmapStatus, RoadmapVote } from "../../../api-client/roadmap";
+import type { TableSection } from "../../../components";
+
+export const ROADMAP_STATUS_LABELS: Record<RoadmapStatus, string> = {
+  building: "Building",
+  planned: "Planned",
+  shipped: "Shipped",
+};
+
+const SECTION_ORDER: readonly RoadmapStatus[] = ["building", "planned", "shipped"];
+
+/** Building, then Planned, then Shipped, each in the order the service sent; an empty group is left out. */
+export function roadmapSections(items: readonly RoadmapItem[]): TableSection<RoadmapItem>[] {
+  return SECTION_ORDER.map((status) => ({
+    label: ROADMAP_STATUS_LABELS[status],
+    key: status,
+    items: items.filter((item) => item.status === status),
+  }));
+}
+
+/** Votes are taken on what is not shipped yet; a shipped item's count is final. */
+export function isVotable(item: RoadmapItem): boolean {
+  return item.status !== "shipped";
+}
+
+/**
+ * The items with this session's own votes on top: the count and mark a vote
+ * changed, held until the next read of the list replaces them.
+ */
+export function withLocalVotes(
+  payload: RoadmapPayload | null,
+  local: Readonly<Record<string, RoadmapVote>>,
+): RoadmapItem[] {
+  if (!payload) return [];
+  return payload.items.map((item) => {
+    const vote = local[item.id];
+    return vote ? { ...item, votes: vote.votes, voted: vote.voted } : item;
+  });
+}
+
+/** What the row shows while a vote is on its way: the mark flipped and the count moved by one. */
+export function optimisticVote(item: RoadmapItem, voted: boolean): RoadmapVote {
+  const step = voted === item.voted ? 0 : voted ? 1 : -1;
+  return { id: item.id, votes: Math.max(0, item.votes + step), voted };
+}
+
+/** The votes cell: the count, with a check before it when this account voted. */
+export function votesText(item: RoadmapItem): string {
+  return item.voted ? `✓ ${item.votes}` : String(item.votes);
+}
+
+/** What one vote that failed is called on its row, and the reason the detail gives. */
+export interface VoteFailure {
+  status: string;
+  reason: string;
+}
+
+export function voteFailure(error: unknown, voted: boolean): VoteFailure {
+  const status = typeof error === "object" && error && "status" in error ? (error as { status?: unknown }).status : undefined;
+  const action = voted ? "The vote" : "Taking the vote back";
+  if (status === 401) return { status: "sign in", reason: `${action} did not go through: sign in again to vote.` };
+  if (status === 402 || status === 403) return { status: "Pro only", reason: `${action} did not go through: voting is for verified Pro members.` };
+  if (status === 404) return { status: "removed", reason: "This item is no longer on the roadmap." };
+  if (status === 409) return { status: "closed", reason: "This item shipped, so its votes are final." };
+  const message = error instanceof Error && error.message.trim() ? error.message.trim() : "the request failed";
+  return { status: "failed", reason: `${action} did not go through: ${message.replace(/\.$/, "")}.` };
+}

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

@@ -0,0 +1,244 @@
+import { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState, type RefObject } from "react";
+import { apiClient } from "../../../api-client";
+import { usePlanAccess } from "../../../api-client/plan-access";
+import type { RoadmapItem, RoadmapVote } from "../../../api-client/roadmap";
+import {
+  buildSectionedRows,
+  DataTableStackView,
+  EMPTY_TABLE_CELL,
+  isSectionedItemRow,
+  renderSectionedRowHeader,
+  usePaneStatusFooter,
+  useRowNotes,
+  type DataTableCell,
+  type DataTableColumn,
+  type PaneFooterSegment,
+  type PaneHint,
+  type SectionedRow,
+} from "../../../components";
+import { usePaneRefreshKey } from "../../../components/data-table/table-pane";
+import { DetailReader, type DetailFact } from "../../../components/reader/detail-reader";
+import { useAsyncResource, usePluginPaneState } from "../../../public/react";
+import { useThemeColors } from "../../../theme/theme-context";
+import type { PaneProps } from "../../../types/plugin";
+import { Box, TextAttributes, type ScrollBoxRenderable } from "../../../ui";
+import { formatShortDate } from "../../../utils/datetime-format";
+import {
+  isVotable,
+  optimisticVote,
+  ROADMAP_STATUS_LABELS,
+  roadmapSections,
+  voteFailure,
+  votesText,
+  withLocalVotes,
+  type VoteFailure,
+} from "./model";
+
+/** The roadmap calls the pane makes; tests hand it their own. */
+export type RoadmapClient = Pick<typeof apiClient, "getRoadmap" | "setRoadmapVote">;
+export const RoadmapClientContext = createContext<RoadmapClient | null>(null);
+
+type Row = SectionedRow<RoadmapItem>;
+type ColumnId = "title" | "blurb" | "votes" | "shipped";
+type Column = DataTableColumn & { id: ColumnId };
+
+const rowKey = (row: Row) => row.key;
+const itemKey = (item: RoadmapItem) => item.id;
+const voteSignature = (item: RoadmapItem) => `${item.votes}:${item.voted}`;
+
+/** Said once, quietly, to everyone who cannot vote: no upgrade pitch. */
+const PRO_VOTES_SEGMENT: PaneFooterSegment = { id: "pro-votes", parts: [{ text: "Pro members vote", tone: "muted" }] };
+const NO_SEGMENTS: PaneFooterSegment[] = [];
+
+function shippedDate(item: RoadmapItem): string {
+  return item.shippedAt ? formatShortDate(item.shippedAt, { fallback: "" }) : "";
+}
+
+/** `votesCell` is what the votes cell says: the count, or a vote's failure on that row. */
+function buildColumns(items: readonly RoadmapItem[], width: number, votesCell: (item: RoadmapItem) => string): Column[] {
+  const longest = Math.max(8, ...items.map((item) => item.title.length));
+  const narrow = width < 64;
+  const columns: Column[] = narrow
+    ? [{ id: "title", label: "Feature", width: Math.min(longest, 24), flexGrow: 1, align: "left" }]
+    : [
+      { id: "title", label: "Feature", width: Math.min(longest, width >= 120 ? 36 : 26), align: "left" },
+      { id: "blurb", label: "Summary", width: 16, flexGrow: 1, align: "left" },
+    ];
+  columns.push({ id: "votes", label: "Votes", width: Math.max(5, ...items.map((item) => votesCell(item).length)), align: "right" });
+  if (!narrow && items.some((item) => item.shippedAt)) {
+    columns.push({ id: "shipped", label: "Shipped", width: 12, align: "left" });
+  }
+  return columns;
+}
+
+function RoadmapDetail({ item, failure, width, scrollRef }: {
+  item: RoadmapItem;
+  failure: VoteFailure | null;
+  width: number;
+  scrollRef: RefObject<ScrollBoxRenderable | null>;
+}) {
+  const colors = useThemeColors();
+  // The stack title names the item; the facts and the blurb follow.
+  const facts: DetailFact[] = [
+    { label: "Status", value: ROADMAP_STATUS_LABELS[item.status] },
+    { label: "Votes", value: item.voted ? `${item.votes}, yours included` : String(item.votes) },
+    ...(item.shippedAt ? [{ label: "Shipped", value: shippedDate(item) }] : []),
+    ...(failure ? [{ label: "Vote", value: failure.reason, color: colors.negative }] : []),
+  ];
+  return (
+    <DetailReader
+      ref={scrollRef}
+      resetScrollKey={item.id}
+      width={width}
+      facts={facts}
+      body={item.blurb || null}
+      bodyFormat="text"
+    />
+  );
+}
+
+export function RoadmapPane({ focused, width, height }: PaneProps) {
+  const colors = useThemeColors();
+  const client = useContext(RoadmapClientContext) ?? apiClient;
+  const access = usePlanAccess();
+  // A sign-in, a sign-out or a new plan asks again: the votes and the right to
+  // cast one are the account's. The new loader starts from no list, so the
+  // last account's marks and vote hint go at once, not when (or if) the new
+  // read lands. A refresh of the same session keeps its list.
+  const sessionKey = JSON.stringify([apiClient.getCurrentUser()?.id ?? null, access.emailVerified, access.hasProAccess]);
+  const loader = useCallback((_force: boolean) => client.getRoadmap(), [client, sessionKey]);
+  const resource = useAsyncResource(loader);
+  const sessionRef = useRef(sessionKey);
+  sessionRef.current = sessionKey;
+  const payload = resource.data;
+  const canVote = payload?.canVote === true;
+
+  // This session's votes, over the list until the next read replaces it.
+  const [localVotes, setLocalVotes] = useState<Record<string, RoadmapVote>>({});
+  useEffect(() => setLocalVotes({}), [resource.updatedAt]);
+  const items = useMemo(() => withLocalVotes(payload, localVotes), [payload, localVotes]);
+  const rows = useMemo(() => buildSectionedRows(roadmapSections(items), itemKey), [items]);
+  const { noteFor, setNote, clearNotes } = useRowNotes<RoadmapItem, VoteFailure>(items, { key: itemKey, signature: voteSignature });
+  // Another account's votes and refusals are not this one's.
+  useEffect(() => {
+    setLocalVotes({});
+    clearNotes();
+  }, [sessionKey, clearNotes]);
+
+  const [selectedId, setSelectedId] = usePluginPaneState<string | null>("selectedItemId", null);
+  const [openId, setOpenId] = usePluginPaneState<string | null>("openItemId", null);
+  const selected = items.find((item) => item.id === selectedId) ?? rows.find(isSectionedItemRow)?.item ?? null;
+  const open = openId ? items.find((item) => item.id === openId) ?? null : null;
+  useEffect(() => {
+    // An item that left the roadmap closes once the list that dropped it is in.
+    if (openId && payload && !open) setOpenId(null);
+  }, [open, openId, payload]);
+  const detailScrollRef = useRef<ScrollBoxRenderable>(null);
+
+  const inFlight = useRef(new Set<string>());
+  const reload = resource.reload;
+  const toggleVote = useCallback(async (item: RoadmapItem) => {
+    if (!canVote || !isVotable(item) || inFlight.current.has(item.id)) return;
+    const voted = !item.voted;
+    const session = sessionRef.current;
+    inFlight.current.add(item.id);
+    setNote(item.id, null);
+    setLocalVotes((current) => ({ ...current, [item.id]: optimisticVote(item, voted) }));
+    try {
+      const answer = await client.setRoadmapVote(item.id, voted);
+      // An answer for the account that just left changes nothing on screen.
+      if (sessionRef.current !== session) return;
+      setLocalVotes((current) => ({ ...current, [item.id]: answer }));
+    } catch (error) {
+      if (sessionRef.current !== session) return;
+      setLocalVotes((current) => ({ ...current, [item.id]: { id: item.id, votes: item.votes, voted: item.voted } }));
+      setNote(item.id, voteFailure(error, voted));
+    } finally {
+      inFlight.current.delete(item.id);
+    }
+  }, [canVote, client, setNote]);
+
+  usePaneRefreshKey(() => void reload(), { focused });
+
+  const target = open ?? selected;
+  const hints = useMemo<PaneHint[]>(() => (
+    canVote && target && isVotable(target)
+      ? [{ id: "vote", key: "v", label: target.voted ? " unvote" : "ote", title: target.voted ? "Take vote back" : "Vote", onPress: () => void toggleVote(target) }]
+      : []
+  ), [canVote, target, toggleVote]);
+  usePaneStatusFooter({
+    registrationId: "roadmap",
+    // A failed refresh keeps the list; the failure goes in the footer.
+    loading: resource.loading && !!payload,
+    error: payload ? resource.error : null,
+    info: !canVote && items.length > 0 ? [PRO_VOTES_SEGMENT] : NO_SEGMENTS,
+    hints,
+  });
+
+  const columns = useMemo(
+    () => buildColumns(items, width, (item) => noteFor(item)?.status ?? votesText(item)),
+    [items, noteFor, width],
+  );
+  const renderCell = useCallback((row: Row, column: Column): DataTableCell => {
+    if (!isSectionedItemRow(row)) return EMPTY_TABLE_CELL;
+    const item = row.item;
+    switch (column.id) {
+      case "title":
+        return { text: item.title, color: colors.textBright };
+      case "blurb":
+        return { text: item.blurb, color: colors.textDim };
+      case "votes": {
+        const failure = noteFor(item);
+        if (failure) return { text: failure.status, color: colors.negative };
+        return {
+          text: votesText(item),
+          value: item.votes,
+          color: item.voted ? colors.positive : isVotable(item) ? colors.text : colors.textDim,
+          ...(item.voted ? { attributes: TextAttributes.BOLD } : {}),
+        };
+      }
+      case "shipped":
+        return { text: shippedDate(item), color: colors.textDim };
+    }
+  }, [colors, noteFor]);
+
+  return (
+    <DataTableStackView<Row, Column>
+      focused={focused}
+      detailOpen={!!open}
+      onBack={() => setOpenId(null)}
+      detailTitle={open?.title}
+      detailContent={open ? (
+        <RoadmapDetail item={open} failure={noteFor(open)} width={width} scrollRef={detailScrollRef} />
+      ) : <Box flexGrow={1} />}
+      detailScrollRef={detailScrollRef}
+      rootWidth={width}
+      rootHeight={height}
+      // A refresh keeps the list on screen; only a first read waits or fails in the body.
+      status={payload ? undefined : {
+        loading: resource.loading,
+        error: resource.error,
+        subject: "Roadmap",
+        retry: { onRetry: reload, pending: resource.loading },
+      }}
+      emptyStateTitle="Nothing on the roadmap yet."
+      columns={columns}
+      items={rows}
+      getItemKey={rowKey}
+      isNavigable={isSectionedItemRow}
+      renderSectionHeader={renderSectionedRowHeader}
+      selection={{
+        kind: "id",
+        selectedId: selected?.id ?? null,
+        getId: rowKey,
+        onChange: (id) => setSelectedId(String(id)),
+      }}
+      onActivate={(row) => { if (isSectionedItemRow(row)) setOpenId(row.item.id); }}
+      sortColumnId={null}
+      sortDirection="asc"
+      renderCell={renderCell}
+      selectedTextOverridesCellColor
+      showHorizontalScrollbar={false}
+    />
+  );
+}

package/src/plugins/builtin/scanner/live-headless.ts

@@ -17,6 +17,7 @@ import {
   type LiveScan,
 } from "./live-model";
 import { LIVE_SCAN_INDEXES } from "../../../api-client/live-scan";
+import { formatHiloPrice } from "./hilo-model";
 
 /** `all`, an index (`sp500`) or a sector (`Energy`), as `--universe` takes it. */
 function parseHeadlessUniverse(value: string): LiveScan["universe"] {
@@ -61,7 +62,24 @@ function emptyText(payload: LiveScanPayload): string {
 
 const number = (value: unknown) => (typeof value === "number" ? value : undefined);
 
+/** `2026-10-27 19:59 UTC`: when the scan last ran, to the minute. */
+const utcMinute = (at: number) => `${new Date(at).toISOString().slice(0, 16).replace("T", " ")} UTC`;
+
+/**
+ * What the report says above the matches: outside the session that the
+ * market is closed and when the scan last ran, since a delay means nothing
+ * then; in the session a delayed feed's delay.
+ */
+function headerNotice(payload: LiveScanPayload): string | null {
+  if (payload.status === "closed") {
+    const last = payload.asOf ?? payload.takenAt;
+    return last != null && Number.isFinite(last) ? `Market closed; last scan ${utcMinute(last)}` : "Market closed";
+  }
+  return payload.access === "delayed" ? `Delayed ${payload.delayMinutes} minutes` : null;
+}
+
 function projectLiveScan(payload: LiveScanPayload, scan: LiveScan): HeadlessSnapshotResult {
+  const notice = headerNotice(payload);
   return {
     asOf: new Date(payload.asOf ?? payload.takenAt ?? Date.now()).toISOString(),
     empty: emptyText(payload),
@@ -80,7 +98,7 @@ function projectLiveScan(payload: LiveScanPayload, scan: LiveScan): HeadlessSnap
     ...(payload.status === "degraded" ? { errors: ["Live scanner degraded"] } : {}),
     freshness: freshness(payload),
     metadata: {
-      ...(payload.access === "delayed" ? { notices: [`Delayed ${payload.delayMinutes} minutes`] } : {}),
+      ...(notice ? { notices: [notice] } : {}),
       ...(payload.warnings.length ? { warnings: payload.warnings } : {}),
       status: payload.status,
       access: payload.access,
@@ -117,7 +135,8 @@ export const liveScanHeadless: HeadlessPaneDefinition<"snapshot"> = {
   columns: [
     { key: "symbol", header: "Symbol" },
     { key: "name", header: "Name" },
-    { key: "price", header: "Price", align: "right" },
+    // At the pane's precision: cents, or four decimals under a dollar; the JSON keeps the feed's digits.
+    { key: "price", header: "Price", align: "right", format: (value) => typeof value === "number" ? formatHiloPrice(value) : "--" },
     { key: "changePercent", header: "Chg %", align: "right", format: (value) => formatPercentRaw(number(value)) },
     { key: "relativeVolume", header: "RVol", align: "right", format: (value) => formatMultiple(number(value)) },
     { key: "volume", header: "Volume", align: "right" },

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

@@ -20,6 +20,7 @@ import { fetchFundFacts, fundFactEntries, fundFactPublishers, fundFactsEmpty, fu
 import { REPORT_ROWS } from "../shared/headless-options";
 import { fundAbroadProfile, venueAbroad, type FundAbroadProfile } from "./fund-abroad";
 import { listingAnnouncementsPage } from "../../../utils/exchange-announcements";
+import { companyDataNotes } from "../../../types/company-from";
 
 const SEC_COLUMNS: HeadlessPaneColumn[] = [
   {
@@ -140,7 +141,7 @@ export function createSecHeadless(dependencies: SecHeadlessDependencies = defaul
       return {
         rows,
         textColumns: secTextColumns(rows),
-        ...(note ? { notes: [note] } : {}),
+        ...(note || filings[0]?.companyFrom ? { notes: [...(note ? [note] : []), ...companyDataNotes(filings[0]?.companyFrom)] } : {}),
         ...(form ? { empty: `No ${form} filings found for ${symbol}.` }
           : page ? { empty: `${symbol} files no SEC reports. ${page.name}: ${page.url}` } : {}),
         metadata: {

package/src/plugins/builtin/sec/index.tsx

@@ -12,6 +12,7 @@ import { Box, Text, useUiCapabilities, type ScrollBoxRenderable } from "../../..
 import { FILL_REST } from "../../../components/ui/fill";
 import { t, tf } from "../../../i18n";
 import { EmptyState, ExternalLinkText, FeedDataTableStackView, PaneLinkMenu, QueryBar, Spinner, TickerBadgeList, usePaneNoticeFooter, useTableLoadMore, type FeedDataTableItem, type PaneHint, type QueryBarFilter } from "../../../components";
+import { useCompanyDataFooter } from "../../../components/layout/pane/status-footer";
 import { displayWidth } from "../../../utils/format";
 import type { DetailFact } from "../../../components/reader/detail-reader";
 import type { ThemeColors } from "../../../theme/colors";
@@ -466,6 +467,8 @@ function SecView({ width, height, focused, paneType }: { width: number; height:
     showOpenHint: !!(openFiling ? openFiling.filingUrl : factsUrl ?? abroadPage ?? announcements),
   });
 
+  // A foreign line's filings are its company's, read from the home line.
+  useCompanyDataFooter(issuerFilings[0]?.companyFrom, !openFiling);
   usePaneNoticeFooter({
     registrationId: "sec:form-filter",
     notices: filterHistoryCapped

package/src/plugins/builtin/shared/cloud-resource.ts

@@ -1,5 +1,5 @@
 import { logFailure } from "../../../utils/log-failure";
-import { ApiRequestError, isAccessDenied } from "../../../api-client/errors";
+import { ApiRequestError, isPermanentClientError } from "../../../api-client/errors";
 import type { PluginCacheResult } from "../../../data/plugin-cache";
 
 interface CloudCache<T> {
@@ -12,6 +12,8 @@ export interface CloudResource<T> {
   payload: T;
   stale: boolean;
   refreshError: string | null;
+  /** When the copy shown was saved, when it is one because its refresh failed. */
+  savedAt?: number;
 }
 
 /**
@@ -36,8 +38,9 @@ const isAbort = (error: unknown) => !!error && typeof error === "object" && (err
 
 /**
  * Loads through the cache, falling back to the cached copy when a refresh
- * fails. A refused session still throws, so the pane shows its sign-in wall
- * instead of data the account can no longer see.
+ * fails. A refusal asking again will not change still throws: a refused
+ * session, so the pane shows its sign-in wall instead of data the account can
+ * no longer see, and any other permanent client error (an unknown series).
  *
  * Callers of one key share the request in flight, which runs on the first
  * caller's `signal`. When that caller goes away (a tab left while it loads,
@@ -57,8 +60,13 @@ export async function loadCloudResource<T>(
     throw error;
   });
   if (!result || cancelledByOther(result.error)) result = await cache.load(key, fetch, { force });
-  if (isAccessDenied(result.error)) throw result.error;
-  return { payload: validate(result.data), stale: result.stale, refreshError: result.refreshError ?? null };
+  const saved = result.source === "stale-fallback";
+  if (saved && isPermanentClientError(result.error)) throw result.error;
+  // A copy served because its refresh failed is one by where it came from, whatever the failure said (or did not).
+  return {
+    payload: validate(result.data), stale: result.stale, refreshError: result.refreshError ?? null,
+    ...(saved ? { savedAt: result.fetchedAt } : {}),
+  };
 }
 
 /**

package/src/plugins/builtin/shared/headless-market-data.ts

@@ -6,7 +6,7 @@ import { clipPriceHistoryToRange } from "../../../time-series/history-window";
 import { canonicalExchange, parsePublicTickerKey } from "../../../utils/exchanges";
 import { nonUsSecListingVenue } from "../../../utils/sec";
 
-export async function resolveHeadlessInstrument(ctx: HeadlessPaneContext, symbol: string) {
+export async function resolveHeadlessInstrument(ctx: Pick<HeadlessPaneContext, "resolveInstrument">, symbol: string) {
   return ctx.resolveInstrument ? ctx.resolveInstrument(symbol) : parsePublicTickerKey(symbol);
 }
 
@@ -39,7 +39,7 @@ export async function resolveHeadlessIssuerListing(ctx: HeadlessPaneContext, key
   return resolveIssuerListing(key, exchange, ctx.marketData);
 }
 
-export async function loadHeadlessFinancials(ctx: HeadlessPaneContext, key: string) {
+export async function loadHeadlessFinancials(ctx: Pick<HeadlessPaneContext, "marketData" | "resolveInstrument">, key: string) {
   const { symbol, exchange } = await resolveHeadlessInstrument(ctx, key);
   return ctx.marketData.getTickerFinancials(symbol, exchange ?? "");
 }

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

@@ -47,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

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/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,