gloomberb 0.16.1 → 0.16.2

package/src/plugins/builtin/market-heatmap/model.ts

@@ -0,0 +1,146 @@
+import type { MarketHeatmapAsset } from "../../../api-client/market-discovery";
+
+/**
+ * The board's grouping and move arithmetic, shared by the pane and the `fn HM`
+ * report so a sector reads the same in both. Isomorphic: no React or renderer.
+ */
+
+type HeatmapMoveAsset = Pick<MarketHeatmapAsset, "symbol" | "hasChange" | "changePercent" | "size" | "sector" | "industry"> & {
+  /** Treemap area, when it is not `size` itself. */
+  weight?: number;
+};
+
+/**
+ * The move, or null when there is none: no change data is not a flat session.
+ * A name without the last session's close still has the move of the open
+ * pre-market or after-hours session it streams (`extendedSession`).
+ */
+export function heatmapMove(asset: Pick<MarketHeatmapAsset, "hasChange" | "changePercent"> & { extendedSession?: string }): number | null {
+  return (asset.hasChange || asset.extendedSession != null) && typeof asset.changePercent === "number" && Number.isFinite(asset.changePercent)
+    ? asset.changePercent
+    : null;
+}
+
+export type HeatmapGrouping = "sector-industry" | "sector" | "flat";
+
+/**
+ * Sector and industry blocks when the board knows its sectors. A board where
+ * most of the value has none (ETFs, or a snapshot whose classification
+ * failed) lays out flat rather than as one big unlabeled block.
+ */
+export function resolveHeatmapGrouping(assets: readonly HeatmapMoveAsset[], industries: boolean): HeatmapGrouping {
+  let total = 0;
+  let classified = 0;
+  const sectors = new Set<string>();
+  for (const asset of assets) {
+    const weight = asset.weight ?? asset.size ?? 0;
+    total += weight;
+    if (asset.sector) {
+      classified += weight;
+      sectors.add(asset.sector);
+    }
+  }
+  if (sectors.size < 2 || classified < total / 2) return "flat";
+  return industries ? "sector-industry" : "sector";
+}
+
+/**
+ * The move of a set of names weighted by their size (market cap, an ETF's net
+ * assets, a position's value), over the names that have both. Null when none do.
+ */
+export function sizeWeightedMove(assets: readonly HeatmapMoveAsset[]): number | null {
+  let weight = 0;
+  let weightedMove = 0;
+  for (const asset of assets) {
+    const change = heatmapMove(asset);
+    const size = asset.size ?? 0;
+    if (change == null || !(size > 0)) continue;
+    weight += size;
+    weightedMove += change * size;
+  }
+  return weight > 0 ? weightedMove / weight : null;
+}
+
+export type HeatmapGroupBy = "sector" | "industry";
+
+export interface HeatmapGroupSummary {
+  /** The sector or industry; null for names the snapshot does not classify, or every name on a flat board. */
+  group: string | null;
+  /** The industry's sector, when grouping by industry. */
+  sector: string | null;
+  names: number;
+  /** Total size: market cap, or net assets on the ETF board. */
+  size: number;
+  /** This group's share of the board's total size. */
+  share: number;
+  move: number | null;
+  /** Names with a move, and the size they carry; the rest have no change data yet. */
+  moved: number;
+  up: number;
+  down: number;
+  unchanged: number;
+  best: { symbol: string; move: number } | null;
+  worst: { symbol: string; move: number } | null;
+}
+
+function summarize(group: string | null, sector: string | null, assets: readonly HeatmapMoveAsset[], boardSize: number): HeatmapGroupSummary {
+  let up = 0;
+  let down = 0;
+  let unchanged = 0;
+  let size = 0;
+  let best: HeatmapGroupSummary["best"] = null;
+  let worst: HeatmapGroupSummary["worst"] = null;
+  for (const asset of assets) {
+    size += asset.size ?? 0;
+    const move = heatmapMove(asset);
+    if (move == null) continue;
+    if (move > 0) up += 1;
+    else if (move < 0) down += 1;
+    else unchanged += 1;
+    if (!best || move > best.move) best = { symbol: asset.symbol, move };
+    if (!worst || move < worst.move) worst = { symbol: asset.symbol, move };
+  }
+  return {
+    group,
+    sector,
+    names: assets.length,
+    size,
+    share: boardSize > 0 ? size / boardSize : 0,
+    move: sizeWeightedMove(assets),
+    moved: up + down + unchanged,
+    up,
+    down,
+    unchanged,
+    best,
+    worst,
+  };
+}
+
+/**
+ * One summary per sector or industry, largest first as the board lays them
+ * out. A flat board (ETFs) is one group of every name. Unclassified names form
+ * their own group last.
+ */
+export function summarizeHeatmapGroups(
+  assets: readonly HeatmapMoveAsset[],
+  groupBy: HeatmapGroupBy,
+): { grouping: HeatmapGrouping; groups: HeatmapGroupSummary[]; board: HeatmapGroupSummary } {
+  const grouping = resolveHeatmapGrouping(assets, groupBy === "industry");
+  const boardSize = assets.reduce((sum, asset) => sum + (asset.size ?? 0), 0);
+  const board = summarize(null, null, assets, boardSize);
+  if (grouping === "flat") return { grouping, groups: [board], board };
+  const buckets = new Map<string, { group: string | null; sector: string | null; assets: HeatmapMoveAsset[] }>();
+  for (const asset of assets) {
+    const sector = asset.sector ?? null;
+    const group = sector == null ? null : grouping === "sector-industry" ? asset.industry ?? null : sector;
+    const key = `${sector ?? ""}\u0000${group ?? ""}`;
+    const bucket = buckets.get(key) ?? { group, sector, assets: [] };
+    bucket.assets.push(asset);
+    buckets.set(key, bucket);
+  }
+  const groups = [...buckets.values()]
+    .map((bucket) => summarize(bucket.group, grouping === "sector-industry" ? bucket.sector : null, bucket.assets, boardSize))
+    .sort((left, right) => Number(left.sector == null && left.group == null) - Number(right.sector == null && right.group == null)
+      || right.size - left.size);
+  return { grouping, groups, board };
+}

package/src/plugins/builtin/market-heatmap/portfolio.ts

@@ -3,6 +3,7 @@ import type { MarketHeatmapAsset, MarketHeatmapUniverseId } from "../../../api-c
 import { useAppSelector, usePaneStateValue } from "../../../state/app/context";
 import type { ColumnConfig } from "../../../types/config";
 import type { TickerFinancials } from "../../../types/financials";
+import { getSessionMoveDisplay, type ExtendedSession } from "../../../market-data/market/status";
 import type { TickerRecord } from "../../../types/ticker";
 import { getSortValue, type ColumnContext } from "../portfolio-list/metrics";
 
@@ -36,6 +37,8 @@ export interface HeatmapBoardAsset extends MarketHeatmapAsset {
   sizeCurrency?: string;
   /** Treemap area, when it is not `size` itself. */
   weight?: number;
+  /** The price and move are this open pre-market or after-hours session's, from the regular close. */
+  extendedSession?: ExtendedSession;
 }
 
 export interface HeatmapPortfolioPane {
@@ -48,6 +51,19 @@ export function heatmapTabId(value: string | null | undefined): HeatmapTabId {
   return "us-equity";
 }
 
+/** Pane state where the pane says which kind of list its portfolio tab shows, for the header to read. */
+export const HEATMAP_COLLECTION_KIND_STATE_KEY = "collectionKind";
+
+/**
+ * Whether Size by changes the board: the market boards and a watchlist, never
+ * a portfolio, whose holdings are always sized by position value. Until the
+ * pane has said which list its tab shows, the control stays away.
+ */
+export function heatmapSizeByApplies(universe: unknown, collectionKind: unknown): boolean {
+  return heatmapTabId(typeof universe === "string" ? universe : null) !== PORTFOLIO_HEATMAP_TAB
+    || collectionKind === "watchlist";
+}
+
 export function isRemoteHeatmapUniverse(value: HeatmapTabId): value is MarketHeatmapUniverseId {
   return value !== PORTFOLIO_HEATMAP_TAB;
 }
@@ -200,16 +216,19 @@ export function buildPortfolioHeatmapAssets({
     const symbol = ticker.metadata.ticker;
     const snapshot = financials.get(symbol);
     const quote = snapshot?.quote;
-    const price = quote != null && Number.isFinite(quote.price) ? quote.price : null;
+    // Colored like the market boards: an open extended session's move, else the regular session's.
+    const display = getSessionMoveDisplay(quote);
+    const price = display != null && Number.isFinite(display.price) ? display.price : null;
     const size = positiveNumber(getSortValue(sizeColumn, ticker, snapshot, context));
-    const hasChange = quote != null && Number.isFinite(quote.changePercent);
+    const hasChange = display?.changePercent != null && Number.isFinite(display.changePercent);
     return {
       symbol,
       name: quote?.name?.trim() || ticker.metadata.name || symbol,
       price: price ?? 0,
-      change: quote != null && Number.isFinite(quote.change) ? quote.change : 0,
-      changePercent: hasChange ? quote.changePercent : 0,
+      change: display?.change != null && Number.isFinite(display.change) ? display.change : 0,
+      changePercent: hasChange ? display.changePercent! : 0,
       hasChange,
+      ...(display?.session ? { extendedSession: display.session } : {}),
       size,
       weight: size == null ? undefined : kind === "portfolio" ? size : heatmapSizeWeight(size, sizeBy),
       sizeKind: "market-cap",

package/src/plugins/builtin/market-movers/headless.ts

@@ -81,6 +81,8 @@ export function createMarketMoversHeadless(
 ): HeadlessPaneDefinition<"rows"> {
   return {
     shape: "rows",
+    // A screener snapshot, not a real-time feed; rows keep the time of their own last price.
+    freshness: { status: "delayed" },
     argument: { kind: "none" },
     options: [{
       key: "list",

package/src/plugins/builtin/market-valuation/headless.ts

@@ -120,6 +120,8 @@ function projectValuationHeadlessBundle(
 
 export const marketValuationHeadless: HeadlessPaneDefinition<"bundle"> = {
   shape: "bundle",
+  // Each indicator row checks its own release schedule and says when it is stale.
+  freshness: { status: "not-a-feed", basis: "published statistics" },
   argument: {
     kind: "free-text",
     placeholder: "indicator",

package/src/plugins/builtin/members/client.ts

@@ -1,7 +1,9 @@
 import { apiClient } from "../../../api-client";
+import { ApiRequestError } from "../../../api-client/errors";
 import type { FundMembersPayload, FundChangesPayload, MemberFundsPayload } from "../../../api-client/members";
 import { createPluginCache } from "../../../data/plugin-cache";
 import { cachedCloudResource, loadCloudResource, unavailableOnServer } from "../shared/cloud-resource";
+import { coveredFund, notCoveredMessage } from "./model";
 const policy = { staleMs: 60_000, expireMs: 2 * 60 * 60_000 };
 export const fundListCache = createPluginCache<MemberFundsPayload>({ kind: "member-funds", source: "gloom-cloud", schemaVersion: 1, policy });
 export const fundMembersCache = createPluginCache<FundMembersPayload>({ kind: "fund-members", source: "gloom-cloud", schemaVersion: 1, policy });
@@ -22,12 +24,27 @@ function validateFunds(data: MemberFundsPayload) {
   if (!data || !Array.isArray(data.funds) || !data.funds.every((fund) => typeof fund.ticker === "string" && typeof fund.name === "string")) throw new Error("Unreadable covered funds response");
   return data;
 }
+const UNAVAILABLE = "Fund members are not available on this server yet.";
 async function fetchPayload<T>(fetcher: () => Promise<T>, validate: (data: T) => T) {
-  try { return validate(await fetcher()); } catch (error) { throw unavailableOnServer(error, "Fund members are not available on this server yet."); }
+  try { return validate(await fetcher()); } catch (error) { throw unavailableOnServer(error, UNAVAILABLE); }
+}
+/**
+ * A 404 for one fund means either an uncovered fund or a server without the route, and the two read the
+ * same. The covered list tells them apart: a fund missing from a readable list is not covered; a list
+ * that cannot be read, or that holds the fund, leaves the server-side message.
+ */
+async function fetchFundPayload<T>(fund: string, fetcher: () => Promise<T>, validate: (data: T) => T, client: Client) {
+  try { return validate(await fetcher()); } catch (error) {
+    if (error instanceof ApiRequestError && error.status === 404) {
+      const funds = await fetchFunds(client).then((payload) => payload.funds, () => []);
+      if (funds.length && !coveredFund(funds, fund)) throw new Error(notCoveredMessage(fund, funds));
+    }
+    throw unavailableOnServer(error, UNAVAILABLE);
+  }
 }
 export const fetchFunds = (client: Client = apiClient) => fetchPayload(() => client.getMemberFunds(), validateFunds);
-export const fetchMembers = (fund: string, client: Client = apiClient) => fetchPayload(() => client.getFundMembers(fund), validateMembers);
-export const fetchChanges = (fund: string, client: Client = apiClient) => fetchPayload(() => client.getFundChanges(fund), validateChanges);
+export const fetchMembers = (fund: string, client: Client = apiClient) => fetchFundPayload(fund, () => client.getFundMembers(fund), validateMembers, client);
+export const fetchChanges = (fund: string, client: Client = apiClient) => fetchFundPayload(fund, () => client.getFundChanges(fund), validateChanges, client);
 export const cachedFunds = () => cachedCloudResource(fundListCache, "list", validateFunds);
 export const loadFunds = (force = false) => loadCloudResource(fundListCache, "list", () => fetchFunds(), { force, validate: validateFunds });
 export const cachedMembers = (fund: string) => cachedCloudResource(fundMembersCache, fund, validateMembers);

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

@@ -15,17 +15,19 @@ export const membersHeadless: HeadlessPaneDefinition<"rows"> = {
   describe: (args) => args.rawArgument ? `MEMB ${args.rawArgument}` : "Index and ETF members",
   async load(args, context) {
     const input = args.symbols[0] ?? args.rawArgument ?? "";
-    if (!input) return { rows: (await fetchFunds(context.apiClient)).funds.map((fund) => ({ ...fund })), columns: [{ key: "ticker", header: "Fund" }, { key: "name", header: "Index" }, { key: "asOf", header: "Holdings as of" }] };
+    if (!input) return { freshness: { status: "not-a-feed", basis: "fund holdings files" }, rows: (await fetchFunds(context.apiClient)).funds.map((fund) => ({ ...fund })), columns: [{ key: "ticker", header: "Fund" }, { key: "name", header: "Index" }, { key: "asOf", header: "Holdings as of" }] };
     const fund = canonicalFund(input);
     if (args.options.tab === "changes") {
       const data = await fetchChanges(fund, context.apiClient);
-      return { rows: data.changes.map((row) => ({ ...row, reason: changeReason(row) })), columns: [{ key: "effectiveDate", header: "Effective" }, { key: "added", header: "Added" }, { key: "removed", header: "Removed" }, { key: "daysToGo", header: "In days", align: "right" }, { key: "reason", header: "Reason" }],
+      return { freshness: { status: "not-a-feed", basis: "index changes" }, rows: data.changes.map((row) => ({ ...row, reason: changeReason(row) })), columns: [{ key: "effectiveDate", header: "Effective" }, { key: "added", header: "Added" }, { key: "removed", header: "Removed" }, { key: "daysToGo", header: "In days", align: "right" }, { key: "reason", header: "Reason" }],
         complete: data.available && !data.stale, metadata: { ...data, changes: undefined } };
     }
     const data = await fetchMembers(fund, context.apiClient);
     const movers = args.options.tab === "movers";
     const rows = memberRows(data.members, movers ? "movers" : "members", "", DEFAULT_SORT).flatMap((row) => row.kind === "item" ? [{ ...row.item }] : []);
-    return { rows, columns: movers ? [...columns.slice(0, 3), { key: "contribution", header: "Contrib. pp", align: "right", format: (value) => percent(value as number | null, "", 3) }] : columns,
+    // Member prices are the pane's 15-minute delayed quotes. As in the pane, the fund's snapshot says
+    // whether it is stale; the members' own flags are not what the pane reads.
+    return { freshness: { status: data.stale ? "stale" : "delayed", delayMinutes: 15, ignoreStaleFlags: true }, rows, columns: movers ? [...columns.slice(0, 3), { key: "contribution", header: "Contrib. pp", align: "right", format: (value) => percent(value as number | null, "", 3) }] : columns,
       complete: !data.stale && data.aggregate.fresh1D === data.aggregate.total,
       unavailableSymbols: data.members.flatMap((row) => row.symbol && row.changePercent === null ? [row.symbol] : []),
       metadata: { fund: data.fund, asOf: data.asOf, snapshotAsOf: data.snapshotAsOf, aggregate: data.aggregate, stale: data.stale } };

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

@@ -1,4 +1,4 @@
-import type { FundChange, FundMember } from "../../../api-client/members";
+import type { FundChange, FundMember, MemberFundsPayload } from "../../../api-client/members";
 import type { DataTableColumn } from "../../../components";
 import { buildSectionedRows, type SectionedRow } from "../../../components/data-table/sections";
 import { getTableWidth } from "../../../components/ui/table-layout";
@@ -6,8 +6,16 @@ import { compareSortValues, type SortPreference } from "../../../utils/sort-valu
 export type MembersTab = "members" | "movers" | "changes";
 export const TABS = [{ value: "members", label: "Members" }, { value: "movers", label: "Movers" }, { value: "changes", label: "Changes" }];
 export const isTab = (value: unknown): value is MembersTab => TABS.some((tab) => tab.value === value);
-export const COVERED = [{ ticker: "IVV", name: "S&P 500" }, { ticker: "IJH", name: "S&P 400" }, { ticker: "IJR", name: "S&P 600" }, { ticker: "IWM", name: "Russell 2000" }, { ticker: "IWB", name: "Russell 1000" }];
+const COVERED = [{ ticker: "IVV", name: "S&P 500" }, { ticker: "IJH", name: "S&P 400" }, { ticker: "IJR", name: "S&P 600" }, { ticker: "IWM", name: "Russell 2000" }, { ticker: "IWB", name: "Russell 1000" }];
 export function canonicalFund(input: string) { const symbol = input.split(":")[0]!.trim().toUpperCase(); return ["SPX", "SPY", "^GSPC"].includes(symbol) ? "IVV" : symbol; }
+/** The covered fund the user asked for, by ticker or by an alias such as SPX, or undefined when it is not covered. */
+export function coveredFund(funds: MemberFundsPayload["funds"], input: string) {
+  const symbol = canonicalFund(input);
+  return funds.find((fund) => fund.ticker === symbol || fund.aliases.some((alias) => alias.toUpperCase() === symbol));
+}
+export function notCoveredMessage(input: string, funds: MemberFundsPayload["funds"]) {
+  return `${input.split(":")[0]!.trim().toUpperCase()} is not a covered fund. Covered: ${funds.map((fund) => fund.ticker).join(", ")}.`;
+}
 export function membersTitle(input: string) {
   const requested = input.split(":")[0]!.trim().toUpperCase();
   const fund = canonicalFund(requested);

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

@@ -12,7 +12,7 @@ import { Box, type ScrollBoxRenderable } from "../../../ui";
 import { nextHeaderSort, type SortPreference } from "../../../utils/sort-values";
 import { isPlainArrowUp, stopSearchFocusNavigation } from "../../../utils/search-focus-navigation";
 import { cachedChanges, cachedFunds, cachedMembers, loadChanges, loadFunds, loadMembers } from "./client";
-import { canonicalFund, changeColumns, changeLabel, changeReason, COVERED, decimal, DEFAULT_SORT, isTab, memberColumns, memberRows, membersTitle, percent, TABS, type MembersTab } from "./model";
+import { canonicalFund, changeColumns, changeLabel, changeReason, coveredFund, decimal, DEFAULT_SORT, isTab, memberColumns, memberRows, membersTitle, notCoveredMessage, percent, TABS, type MembersTab } from "./model";
 
 type ViewProps = Pick<PaneProps, "width" | "height" | "focused"> & { fund: string; active: boolean };
 const rowKey = (row: SectionedRow<FundMember>) => row.key;
@@ -156,13 +156,20 @@ function FundPicker({ width, height, focused, choose }: Pick<PaneProps, "width"
       onActivate={(row) => choose(row.ticker)} sortColumnId={null} sortDirection="asc" renderCell={(row, col) => ({ text: String(row[col.id as "ticker"] ?? "--") })} />}
   </PaneStatusBody>;
 }
+type FundPaneProps = Pick<PaneProps, "width" | "height" | "focused"> & { fund: string; requested: string };
+/** The covered list is the server's, so a fund it adds opens without an app update. A list that cannot be read leaves the fund's own load to report the failure. */
+function CoveredFund({ fund, requested, ...props }: FundPaneProps) {
+  const resource = useAsyncResource(loadFunds, { initialData: cachedFunds });
+  const funds = resource.data?.payload.funds;
+  if (funds?.length && !coveredFund(funds, fund)) return <PaneStatusBody empty emptyTitle={notCoveredMessage(requested, funds)} />;
+  return <FundView key={fund} fund={fund} {...props} />;
+}
 export function MembersPane(props: PaneProps) {
   const { symbol } = usePaneTickerIdentity();
   const [chosen, choose] = usePluginPaneState("fund", "");
-  const fund = canonicalFund(symbol ?? chosen);
-  const definition = COVERED.find((item) => item.ticker === fund);
-  usePaneTitle(membersTitle(symbol ?? chosen));
+  const requested = symbol ?? chosen;
+  const fund = canonicalFund(requested);
+  usePaneTitle(membersTitle(requested));
   if (!fund) return <FundPicker {...props} choose={choose} />;
-  if (!definition) return <EmptyState title="This index or fund is not covered." hint="IVV, IJH, IJR, IWM and IWB are covered. Nasdaq-100 (NDX/QQQ) is not covered." />;
-  return <FundView key={fund} fund={fund} {...props} />;
+  return <CoveredFund fund={fund} requested={requested} {...props} />;
 }

package/src/plugins/builtin/mna/distress/headless.ts

@@ -140,6 +140,7 @@ const text = (value: unknown) => (typeof value === "string" ? value : "");
 
 export const distressHeadless: HeadlessPaneDefinition<"rows"> = {
   shape: "rows",
+  freshness: { source: "Public filings and insolvency notices", status: "not-a-feed", basis: "filed records" },
   description: "Dated public records about companies in difficulty: US 8-K bankruptcy, obligation and listing filings, SEC going-concern disclosures, Taiwan exchange listing designations, and French and UK company insolvency notices. No scores or predictions.",
   argument: { kind: "none" },
   discovery: {

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

@@ -19,6 +19,7 @@ const COLUMNS: HeadlessPaneColumn[] = [
 
 export const mnaHeadless: HeadlessPaneDefinition<"rows"> = {
   shape: "rows",
+  freshness: { status: "not-a-feed", basis: "reported deals" },
   argument: {
     kind: "ticker",
     optional: true,

package/src/plugins/builtin/money-markets/headless.ts

@@ -6,6 +6,7 @@ export const moneyMarketsHeadless: HeadlessPaneDefinition<"bundle"> = {
   discovery: { aliases: ["BTMM"], dataRequirements: ["Gloom Cloud money-markets endpoint"],
     limitations: ["Published daily and weekly observations", "Treasury bill discount yields", "Net liquidity is a same-date proxy"] },
   shape: "bundle", argument: { kind: "none" },
+  freshness: { source: "FRED", status: "not-a-feed", basis: "published daily and weekly data" },
   options: [{ key: "tab", type: "enum", description: "Money-market view.", values: [{ value: "rates" }, { value: "bills" }, { value: "liquidity" }], defaultValue: "rates" }],
   describe: "US money markets",
   async load(args, ctx) {

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

@@ -81,6 +81,8 @@ function projectNewsHeadless(
   return {
     asOf: now.toISOString(),
     items,
+    // Published stories, dated by the newest; the list is a history, so its last story is not stale data.
+    freshness: { status: "not-a-feed", basis: "published stories", observedKey: "publishedAt", oldest: null },
     metadata: {
       nextCursor: response.nextCursor,
       sentiment,

package/src/plugins/builtin/news/wire/index.tsx

@@ -25,6 +25,7 @@ import { NEWS_INDUSTRY_CODES, NEWS_QUERY_PRESETS, parseNewsIndustryCode } from "
 import { createRssNewsCapability } from "./rss/source";
 import { rssCliCommand } from "./rss/cli";
 import { newsFeedHeadless } from "../headless";
+import type { PaneDef } from "../../../../types/plugin";
 
 const TopPane = createNewsPresetPane({
   paneKey: "top:curated",
@@ -61,8 +62,11 @@ export const BreakingPane = createNewsPresetPane({
 
 let disposeBreakingNewsNotifications: (() => void) | null = null;
 
+// A rendered news pane is a list of published stories, dated by its newest.
+const NEWS_REPORT_FRESHNESS: PaneDef["reportFreshness"] = { status: "not-a-feed", basis: "published stories" };
+
 const newsWirePanes: PluginModule["panes"] = [
-    { id: "news-top", name: "Top News", icon: "T", component: TopPane, defaultPosition: "right", defaultMode: "floating", defaultFloatingSize: { width: 90, height: 30 } },
+    { id: "news-top", reportFreshness: NEWS_REPORT_FRESHNESS, name: "Top News", icon: "T", component: TopPane, defaultPosition: "right", defaultMode: "floating", defaultFloatingSize: { width: 90, height: 30 } },
     {
       id: "news-feed",
       name: "News Feed",
@@ -75,6 +79,7 @@ const newsWirePanes: PluginModule["panes"] = [
     },
     {
       id: "news-industry",
+      reportFreshness: NEWS_REPORT_FRESHNESS,
       name: TOPIC_NEWS_TITLE,
       icon: "S",
       component: IndustryPane,
@@ -85,6 +90,7 @@ const newsWirePanes: PluginModule["panes"] = [
     },
     {
       id: NEWS_STORY_PANE_ID,
+      reportFreshness: NEWS_REPORT_FRESHNESS,
       name: "Story",
       icon: "A",
       component: NewsStoryPane,
@@ -94,6 +100,7 @@ const newsWirePanes: PluginModule["panes"] = [
     },
     {
       id: "news-breaking",
+      reportFreshness: NEWS_REPORT_FRESHNESS,
       name: "Breaking News",
       icon: "!",
       component: BreakingPane,

package/src/plugins/builtin/notes/cli.ts

@@ -2,7 +2,8 @@ import { apiClient } from "../../../api-client";
 import { withCliServices, withConfigData } from "../../../cli/scoped-context";
 import { CLI_COMMAND_GROUPS } from "../../../cli/help";
 import { dryRunNote } from "../../../cli/helpers";
-import { requireArg } from "../../../cli/commands/command-utils";
+import { requireArg, takeOption } from "../../../cli/commands/command-utils";
+import { EXCHANGE_OPTION, requireListingArg } from "../../../cli/listing-arg";
 import { createPluginPersistence } from "../../plugin-persistence";
 import type { CliCommandDef } from "../../../types/plugin";
 import { cliStyles } from "../../../utils/cli-output";
@@ -17,9 +18,16 @@ export const notesCliCommand: CliCommandDef = {
   help: {
     group: CLI_COMMAND_GROUPS.portfolios,
     usage: ["notes show <symbol>", "notes set <symbol> <text...>", "notes delete <symbol>", "notes quick list", "notes export [dir]"],
-    examples: ["notes show AAPL", "notes set AAPL \"Services margin above 70%\"", "notes export ~/notes"],
+    options: [EXCHANGE_OPTION],
+    examples: ["notes show AAPL", "notes set AAPL \"Services margin above 70%\"", "notes show SAN:EPA", "notes export ~/notes"],
   },
-  execute: async (args, ctx) => {
+  execute: async (rawArgs, ctx) => {
+    const args = [...rawArgs];
+    const exchange = takeOption(args, "--exchange");
+    // A note belongs to one listing: SAN:EPA, or SAN with --exchange EPA.
+    const noteSymbol = async (usage: string) => (
+      await requireListingArg(requireArg(args[1], usage, ctx), exchange, ctx)
+    ).key;
     await withConfigData(ctx, async (config) => {
       const notes = new NotesFiles(config.dataDir);
       const action = args[0] ?? "list";
@@ -62,14 +70,14 @@ export const notesCliCommand: CliCommandDef = {
         return;
       }
       if (action === "show") {
-        const symbol = requireArg(args[1]?.toUpperCase(), "Usage: gloomberb notes show <symbol>", ctx);
+        const symbol = await noteSymbol("Usage: gloomberb notes show <symbol>");
         ctx.printResult({ data: { symbol, text: await notes.load(symbol) } }, {
           text: (data) => data.text?.trim() ? data.text.trimEnd() : cliStyles.muted(`No note for ${symbol}.`),
         });
         return;
       }
       if (action === "set") {
-        const symbol = requireArg(args[1]?.toUpperCase(), "Usage: gloomberb notes set <symbol> <text...>", ctx);
+        const symbol = await noteSymbol("Usage: gloomberb notes set <symbol> <text...>");
         const text = args.slice(2).join(" ");
         if (!ctx.cliOptions.dryRun) await notes.save(symbol, text);
         ctx.printResult({ data: { changed: !ctx.cliOptions.dryRun, dryRun: ctx.cliOptions.dryRun, symbol, bytes: text.length } }, {
@@ -78,7 +86,7 @@ export const notesCliCommand: CliCommandDef = {
         return;
       }
       if (action === "delete" || action === "rm") {
-        const symbol = requireArg(args[1]?.toUpperCase(), "Usage: gloomberb notes delete <symbol>", ctx);
+        const symbol = await noteSymbol("Usage: gloomberb notes delete <symbol>");
         // Only picks the message; an unreadable note is still deleted.
         const existed = await notes.load(symbol).then((text) => !!text?.trim(), () => true);
         if (!ctx.cliOptions.dryRun) await notes.delete(symbol);

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

@@ -79,6 +79,7 @@ export const notesPlugin: GloomPlugin = {
 
     ctx.registerPane({
       id: "quick-notes",
+      reportFreshness: { source: "Your notes", status: "not-a-feed", basis: "your notes" },
       name: "Notes",
       icon: "N",
       component: QuickNotesPane,

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

@@ -31,6 +31,7 @@ export const openFdaPlugin: GloomPlugin = {
   panes: [
     {
       id: OPENFDA_PANE_ID,
+      reportFreshness: { source: "US FDA", status: "not-a-feed", basis: "published reports" },
       name: "FDA Reports",
       icon: "F",
       component: OpenFdaPane,

package/src/plugins/builtin/options-calculator/headless.ts

@@ -39,6 +39,7 @@ function report(draft: OptionCalcDraft, valuation: OptionValuation | null,
     ],
     complete: valuation !== null && errors.length === 0,
     errors, unavailableSymbols: surface?.error && draft.symbol ? [draft.symbol] : [],
+    ...(surface ? { freshness: { source: "Your inputs and Gloom Cloud volatility" } } : {}),
     metadata: { model, inputs: draft, valuation, impliedVolatility: implied, surface, effectiveTreeSteps,
       warnings: surface?.warnings ?? [], method: model === "american" ? "CRR American tree with discrete cash dividends" : "European Black-Scholes",
       greekUnits: { delta: "underlying units per option unit", gamma: "delta per underlying price unit", theta: "currency per calendar day",
@@ -49,6 +50,7 @@ function report(draft: OptionCalcDraft, valuation: OptionValuation | null,
 
 export const optionsCalculatorHeadless: HeadlessPaneDefinition<"bundle"> = {
   shape: "bundle", argument: { kind: "none" }, describe: "OVME option valuation",
+  freshness: { source: "Your inputs", status: "not-a-feed", basis: "calculator" },
   discovery: { limitations: ["Discrete dividends use days from valuation and cash per underlying unit; model values exclude fees and assignment costs."] },
   options: [
     { key: "model", type: "enum", values: [{ value: "european" }, { value: "american" }], defaultValue: "european", description: "European closed form or American CRR tree" },

package/src/plugins/builtin/options-positioning/headless.ts

@@ -23,6 +23,7 @@ const gamma = (value: unknown) => formatGamma(typeof value === "number" ? value
 /** OPX opens on Strikes, GEX on its own tab; the report carries every section either way. */
 export const optionsPositioningHeadless = (initialTab: PositioningTab): HeadlessPaneDefinition<"bundle"> => ({
   shape: "bundle",
+  freshness: { status: "not-a-feed", basis: "daily open interest", cadence: "daily" },
   argument: { kind: "ticker", optional: true, description: "US option underlying, or SPX; SPY when omitted" },
   describe: (args) => `${initialTab === "gex" ? "GEX" : "OPX"} ${args.symbols[0] ?? "SPY"}`,
   discovery: {
@@ -59,6 +60,8 @@ export const optionsPositioningHeadless = (initialTab: PositioningTab): Headless
     ];
     const changes = openInterest.previousOiDate != null;
     return {
+      // Open interest is published once a day for the prior session; the spot beside it is context.
+      freshness: { asOf: openInterest.oiDate },
       sections: [
         { title: `Expiries · OI as of ${openInterest.oiDate ?? "--"}`, columns: [
           { key: "date", header: "Expiry" }, { key: "days", header: "Days" },

package/src/plugins/builtin/options-scenario/headless.ts

@@ -57,7 +57,12 @@ export const optionsScenarioHeadless: HeadlessPaneDefinition<"bundle"> = {
     // A seeded strategy starts at the spot its quote mids imply; the last print is reported beside it.
     const lastPrint = midVolatility && !supplied(settings.spot) && market.spot != null && money(market.spot) !== money(position!.spot)
       ? market.spot : null;
+    const chain = market.chain;
     return {
+      freshness: suppliedInputs
+        ? { source: "Your inputs", status: "not-a-feed", basis: "scenario" }
+        : { asOf: market.asOf, ...(chain?.dataSource === "live" || chain?.dataSource === "delayed" ? { status: chain.dataSource } : {}),
+          ...(chain?.delayMinutes ? { delayMinutes: chain.delayMinutes } : {}) },
       sections: scenario ? [
         { title: "Position", columns: [
           { key: "side", header: "Side" }, { key: "strike", header: "Strike" }, { key: "expiry", header: "Expiry" },