gloomberb 0.16.3 → 0.16.4

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

@@ -26,9 +26,10 @@ import {
   useUiCapabilities,
 } from "../../../ui";
 import { isPermanentClientError } from "../../../api-client/errors";
+import type { IssuerListingParams } from "../../../api-client/paths";
 import { useFilingYearReader } from "../shared/filing-year-reader";
 import { useProFeatureWall, type ProFeatureWallCopy, type ReadGuard } from "../shared/pro-feature-wall";
-import { useBoundTicker } from "../shared/ticker-request";
+import { useBoundTicker, useIssuerListing } from "../shared/ticker-request";
 import { SplitBar } from "../../../components/ui/split-bar";
 import { loadProxyStatement, loadProxyStatements } from "./data";
 import {
@@ -249,27 +250,35 @@ export function ExecutivesPane({
   nested?: boolean;
 }) {
   const { wall, guard } = useProFeatureWall(EXEC_WALL, { width, height });
-  const { symbol } = useBoundTicker();
+  const { symbol, ticker: boundTicker } = useBoundTicker();
   const ticker = symbol ? symbol.toUpperCase() : null;
+  const listing = useIssuerListing(boundTicker);
   if (wall) return wall;
-  if (!ticker) return <EmptyState title="Pick a ticker to see its executives." />;
-  return <ExecutiveResearch key={ticker} ticker={ticker} focused={focused} width={width} nested={nested} guard={guard} />;
+  if (!ticker) return <EmptyState title="Select a ticker." />;
+  return <ExecutiveResearch key={ticker} ticker={ticker} listing={listing} focused={focused} width={width} nested={nested} guard={guard} />;
 }
 
 export function ExecutivesResearchTab(props: { focused: boolean; width: number; height: number }) {
   return <ExecutivesPane {...props} nested />;
 }
 
-function ExecutiveResearch({ ticker, focused, width, nested, guard }: { ticker: string; focused: boolean; width: number; nested: boolean; guard: ReadGuard }) {
+function ExecutiveResearch({ ticker, listing, focused, width, nested, guard }: {
+  ticker: string;
+  listing: IssuerListingParams;
+  focused: boolean;
+  width: number;
+  nested: boolean;
+  guard: ReadGuard;
+}) {
   const nativePaneChrome = useUiCapabilities().nativePaneChrome === true;
   const rendererHost = useRendererHost();
   const [selectedYear, setYear] = usePaneStateValue<number | null>("proxyYear", null);
-  const loadYears = useCallback((force: boolean) => guard(loadProxyStatements(ticker, { force })), [guard, ticker]);
+  const loadYears = useCallback((force: boolean) => guard(loadProxyStatements(ticker, { force, listing })), [guard, listing, ticker]);
   const list = useAsyncResource(loadYears, { clearOnError: isPermanentClientError });
   const years = useMemo(() => (list.data?.data?.proxies ?? []).map((entry) => entry.proxyYear), [list.data]);
   const year = selectedYear !== null && years.includes(selectedYear)
     ? selectedYear : years[0] ?? null;
-  const loadStatement = useCallback((force: boolean) => guard(loadProxyStatement(ticker, year!, { force })), [guard, ticker, year]);
+  const loadStatement = useCallback((force: boolean) => guard(loadProxyStatement(ticker, year!, { force, listing })), [guard, listing, ticker, year]);
   const detail = useAsyncResource(year === null ? null : loadStatement, { clearOnError: isPermanentClientError });
   const statement = detail.data?.data ?? null;
   const loading = list.loading || detail.loading;

package/src/plugins/builtin/filing-events/pane.tsx

@@ -1,5 +1,7 @@
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { apiClient } from "../../../api-client";
+import { ApiRequestError } from "../../../api-client/errors";
+import type { IssuerListingParams } from "../../../api-client/paths";
 import {
   BulletList,
   EmptyState,
@@ -24,7 +26,7 @@ import {
 import { truncateToDisplayWidth } from "../../../utils/format";
 import { isPlainKey } from "../../../utils/keyboard";
 import { useProFeatureWall, type ProFeatureWallCopy, type ReadGuard } from "../shared/pro-feature-wall";
-import { useBoundTicker, useTickerRequest } from "../shared/ticker-request";
+import { useBoundTicker, useIssuerListing, useTickerRequest } from "../shared/ticker-request";
 import {
   buildFilingEventsFeed,
   resolveFeedScrollTop,
@@ -100,6 +102,20 @@ function FilingEntry({
   );
 }
 
+/**
+ * The latest 8-Ks of a listing. The service answers 404 when it can tie no
+ * filer to the ticker, as for a listing abroad whose company files none:
+ * that is no 8-Ks, not a failure.
+ */
+async function fetchFilingEvents(ticker: string, listing: IssuerListingParams) {
+  try {
+    return await apiClient.getFilingEvents(ticker, 100, listing);
+  } catch (error) {
+    if (error instanceof ApiRequestError && error.status === 404) return { ticker, events: [] };
+    throw error;
+  }
+}
+
 interface FilingEventsPaneProps {
   focused: boolean;
   width: number;
@@ -116,14 +132,15 @@ function FilingEventsReader({
   width,
   guard,
 }: FilingEventsPaneProps & { guard: ReadGuard }) {
-  const { symbol, exchange } = useBoundTicker();
+  const { symbol, exchange, ticker: boundTicker } = useBoundTicker();
   const ticker = symbol ? symbol.toUpperCase() : null;
+  const { name } = useIssuerListing(boundTicker);
   const nativePaneChrome = useUiCapabilities().nativePaneChrome === true;
   const rendererHost = useRendererHost();
 
   const loadFilingEvents = useCallback(
-    (listing: string) => guard(apiClient.getFilingEvents(listing, 100)),
-    [guard],
+    (key: string, venue: string) => guard(fetchFilingEvents(key, { exchange: venue, name })),
+    [guard, name],
   );
   const { data, loading, error, reload } = useTickerRequest(loadFilingEvents, ticker, exchange);
   const events = data?.events ?? [];
@@ -227,7 +244,7 @@ function FilingEventsReader({
     return { info, hints };
   }, [loading, error, ticker, selected, openFiling]);
 
-  if (!ticker) return <EmptyState title="Pick a ticker to see its 8-K filings." />;
+  if (!ticker) return <EmptyState title="Select a ticker." />;
   if (loading && !data) {
     return <PaneStatusBody loading align="center" loadingLabel="Loading 8-Ks..." />;
   }

package/src/plugins/builtin/fx-matrix/freshness.ts

@@ -0,0 +1,65 @@
+import type { QueryEntry } from "../../../market-data/result-types";
+import type { Quote } from "../../../types/financials";
+import { isFxMarketOpen } from "../../../utils/fx-market-hours";
+import { quoteFreshnessFields } from "../shared/report-freshness";
+
+/** The venue FX pairs trade on, so a report can place the matrix's market. */
+const FX_VENUE = "CCY";
+
+/**
+ * One rate the matrix draws, in the fields a report reads to date it: when it
+ * was observed, whether it is live or delayed (and by how much), whether it is
+ * stale, and where its market stands. The pane publishes these for `fn FXC`
+ * and `shot FXC`; they are not shown in the pane.
+ */
+type FxRateObservation = {
+  currency: string;
+  /** ISO time of the observation; absent when the rate carries none. */
+  quoteTime?: string;
+  dataSource?: "live" | "delayed";
+  delayMinutes?: number;
+  stale: boolean;
+  sessionExchange: string;
+  marketState: NonNullable<Quote["marketState"]>;
+};
+
+function isoTime(time: number | undefined | null): string | undefined {
+  return time != null && Number.isFinite(time) ? new Date(time).toISOString() : undefined;
+}
+
+/**
+ * The observation behind each rate the matrix shows, except USD (the base,
+ * observed nowhere) and a currency with no usable rate (drawn as a dash).
+ *
+ * A rate read from a live pair quote (`legQuote`) says what that quote says:
+ * live or delayed, by how much, and its market state. Any other rate is the
+ * loaded snapshot: a snapshot refreshed on a schedule, so delayed, dated by
+ * the snapshot's own observation time and placed on the FX week, which runs
+ * Sunday 17:00 to Friday 17:00 New York time. A rate is stale when its entry
+ * says so (a failed refresh, or its own schedule), as the pane's footer counts.
+ */
+export function fxRateObservations(
+  currencies: readonly string[],
+  rates: ReadonlyMap<string, number>,
+  read: (currency: string) => { entry?: QueryEntry<number> | null; legQuote?: Quote | null },
+  now = Date.now(),
+): FxRateObservation[] {
+  return [...new Set(currencies)].flatMap((currency) => {
+    if (currency === "USD") return [];
+    const rate = rates.get(currency);
+    if (rate == null || !Number.isFinite(rate) || rate <= 0) return [];
+    const { entry, legQuote } = read(currency);
+    const fields = legQuote ? quoteFreshnessFields(legQuote, now) : null;
+    const entryStale = entry?.error != null || (entry?.staleAt != null && entry.staleAt <= now);
+    const quoteTime = isoTime(entry?.asOf ?? legQuote?.lastUpdated);
+    return [{
+      currency,
+      ...(quoteTime ? { quoteTime } : {}),
+      dataSource: fields?.dataSource ?? "delayed",
+      ...(fields?.delayMinutes ? { delayMinutes: fields.delayMinutes } : {}),
+      stale: entryStale || fields?.stale === true,
+      sessionExchange: fields?.sessionExchange ?? FX_VENUE,
+      marketState: fields?.marketState ?? (isFxMarketOpen(now) ? "REGULAR" : "CLOSED"),
+    }];
+  });
+}

package/src/plugins/builtin/fx-matrix/index.tsx

@@ -12,6 +12,7 @@ import { CountryFlag } from "../../../components/ui/country-flag";
 import { getSharedMarketDataCoordinator } from "../../../market-data/coordinator";
 import { useFxRatesMap } from "../../../market-data/hooks";
 import { resolveEntryData } from "../../../market-data/selectors";
+import { useRemoteUiNode } from "../../../remote/semantic-tree";
 import { usePaneSettingValue } from "../../../state/app/context";
 import { colors } from "../../../theme/colors";
 import type { PaneProps } from "../../../types/plugin";
@@ -25,8 +26,9 @@ import { useLiveStreamingSetting } from "../../../state/hooks/live-streaming";
 import { fxLegQuoteKey, fxLegReferenceRate, fxLegTargets, fxLegs, fxLegsBehind, liveFxLegEntry } from "./live-legs";
 import { CURRENCY_FLAG_REGIONS, FX_CURRENCIES, formatRate, resolveCurrencies, type FxCurrency } from "./pairs";
 import { crossMovePercent, directionTint, nextTintLevel } from "./direction";
-import { fxMatrixSettings } from "./settings";
+import { FX_MATRIX_REPORT_OPTIONS, fxMatrixReportNotices, fxMatrixSettings } from "./settings";
 import { createFxExportMetadata } from "./export";
+import { fxRateObservations } from "./freshness";
 
 const FX_MATRIX_PANE_ID = "fx-matrix";
 /** Stable identity: a fresh literal here would reload the board every render. */
@@ -114,6 +116,23 @@ function FxMatrixPane({ focused, width, height }: PaneProps) {
       ? { ...entry, error: entry.error ? { ...entry.error } : null }
       : undefined] as const;
   }));
+  // A report or capture of the board is dated by the rates it draws: when each
+  // was observed, whether it is delayed or stale, and where the FX market
+  // stands. The pane draws none of this; its footer keeps its own status.
+  useRemoteUiNode({
+    role: "report-freshness",
+    label: "Rate freshness",
+    getMetadata: () => {
+      const legQuotes = new Map(legs.map((leg) => [leg.currency, resolveEntryData(legEntries.get(fxLegQuoteKey(leg)))] as const));
+      return {
+        observations: fxRateObservations(currencies, rates, (currency) => ({
+          entry: rateEntries.get(currency),
+          // Only a rate that is the pair quote's own says what that quote says.
+          legQuote: liveEntries.has(currency) ? legQuotes.get(currency) : null,
+        })),
+      };
+    },
+  });
   const status = summarizeFxRates(currencies, rates, (currency) => rateEntries.get(currency));
   const statusText = fxStatusLabel(status);
   const snapshotFetchedAt = summarizeFxRates(currencies, snapshotRates, (currency) => (
@@ -253,6 +272,8 @@ export const fxMatrixModule: PluginModule = {
       defaultFloatingSize: { width: 105, height: 14 },
       tableExport: true,
       settings: fxMatrixSettings,
+      reportOptions: FX_MATRIX_REPORT_OPTIONS,
+      reportNotices: fxMatrixReportNotices,
     },
   ],
 

package/src/plugins/builtin/fx-matrix/pairs.ts

@@ -60,7 +60,7 @@ export function formatRate(rate: number, referenceRate = rate): string {
   return rate.toFixed(decimals);
 }
 
-function isFxCurrency(code: unknown): code is FxCurrency {
+export function isFxCurrency(code: unknown): code is FxCurrency {
   return typeof code === "string" && FX_CURRENCIES.includes(code as FxCurrency);
 }
 

package/src/plugins/builtin/fx-matrix/settings.ts

@@ -1,5 +1,5 @@
-import type { PaneSettingsContext, PaneSettingsDef } from "../../../types/plugin";
-import { CURRENCY_SETS, FX_CURRENCIES, resolveCurrencies } from "./pairs";
+import type { PaneReportOptionDef, PaneSettingsContext, PaneSettingsDef } from "../../../types/plugin";
+import { CURRENCY_SETS, FX_CURRENCIES, MAJOR_CURRENCIES, isFxCurrency, resolveCurrencies } from "./pairs";
 
 const CUSTOM_SET = "custom";
 
@@ -60,3 +60,43 @@ export function fxMatrixSettings(context: PaneSettingsContext): PaneSettingsDef
     },
   };
 }
+
+const SET_NAMES = CURRENCY_SETS.map((set) => set.id).join(", ");
+
+/**
+ * `--currencies` as typed: codes and set names in any case, separated by
+ * commas or spaces, returned as the codes in order without repeats. A token
+ * that is neither fails, naming it and the codes the board carries, where the
+ * pane setting would drop it and quietly show the majors.
+ */
+function parseCurrenciesOption(value: string): string {
+  const tokens = value.split(/[\s,]+/).filter(Boolean);
+  const unknown = tokens.filter((token) => (
+    !isFxCurrency(token.toUpperCase()) && !CURRENCY_SETS.some((set) => set.id === token.toLowerCase())
+  ));
+  if (unknown.length > 0) {
+    throw new Error(
+      `Unknown ${unknown.length > 1 ? "currencies" : "currency"} ${unknown.join(", ")} for --currencies. `
+      + `Use codes from ${FX_CURRENCIES.join(", ")}, or a set: ${SET_NAMES}.`,
+    );
+  }
+  if (tokens.length === 0) throw new Error("--currencies needs at least one code, such as USD,ZAR,NGN.");
+  return resolveCurrencies(value).join(",");
+}
+
+/** `fn FXC --currencies USD,ZAR,NGN`: the board's currency list, as its settings choose it. */
+export const FX_MATRIX_REPORT_OPTIONS: readonly PaneReportOptionDef[] = [{
+  key: "currencies",
+  type: "string",
+  placeholder: "codes",
+  description: `The currencies to cross, in order: codes separated by commas, or a set (${SET_NAMES}). `
+    + `Without it, the ${MAJOR_CURRENCIES.length} majors. Codes: ${FX_CURRENCIES.join(", ")}`,
+  example: "--currencies USD,ZAR,NGN,SAR,ILS",
+  normalize: parseCurrenciesOption,
+}];
+
+/** A report of the default board says it is only the majors, and how to choose others. */
+export function fxMatrixReportNotices(settings: Readonly<Record<string, unknown>>): string[] {
+  if (settings.currencies != null) return [];
+  return [`Showing the ${MAJOR_CURRENCIES.length} majors. Choose others with --currencies USD,ZAR,NGN; gloomberb catalog FXC lists all ${FX_CURRENCIES.length}.`];
+}

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

@@ -3,6 +3,7 @@ import type { HeadlessPaneDefinition } from "../../../types/plugin";
 import { fetchGpuBoard, fetchGpuEvents, fetchGpuHistory, loadGpuEquityHistory } from "./client";
 import { GPU_TABS, gpuArgument, gpuBasisLabel, gpuChange, gpuEquityRows, gpuEventDate, gpuProvenanceLabel, gpuLabel, gpuRows, gpuSource, gpuTab } from "./model";
 import { quoteFreshnessFields } from "../shared/report-freshness";
+import { getRegularSessionDisplay } from "../../../market-data/market/status";
 
 const observationRow = (row: GpuObservation) => ({ gpu: gpuLabel(row), source: gpuSource(row), basis: gpuBasisLabel(row.basis),
   price: row.pricePerGpuHr, availability: row.availability, observedAt: row.observedAt, effectiveAt: row.effectiveAt, provenance: row.provenance ?? "live", provenanceLabel: gpuProvenanceLabel(row, true),
@@ -19,14 +20,17 @@ export const gpuHeadless: HeadlessPaneDefinition<"bundle"> = {
   shape: "bundle", argument: { kind: "free-text", optional: true, placeholder: "GPU", description: "GPU model, such as H100 or B200." },
   options: [{ key: "tab", type: "enum", values: GPU_TABS.map(({ value }) => ({ value })), defaultValue: "board", description: "Board, sourced history, dated changes or related equities." }],
   discovery: { aliases: ["GPU"], dataRequirements: ["GPU rental price observations"],
-    limitations: ["List prices, provider-declared spot and asks are distinct bases", "1D/7D/30D need sufficient observation history; unavailable changes remain null"] },
+    limitations: ["List prices, provider-declared spot and asks are distinct bases",
+      "Hyperscaler and Neocloud rows are list indexes: the median of the providers' list prices linked over time, so a provider joining or leaving causes no jump; sample.rawMedian is the raw median of today's providers and can differ slightly",
+      "1D/7D/30D need sufficient observation history; unavailable changes remain null"] },
   describe: "GPU rental prices in USD per GPU-hour",
   async load(args, ctx) {
     const argument = Array.isArray(args.argument) ? args.argument.join(" ") : args.argument;
     const model = gpuArgument(argument);
     const tab = gpuTab(args.options.tab);
     const board = await fetchGpuBoard(ctx.apiClient);
-    const metadata = { asOf: board.asOf, stale: board.stale, complete: board.status === "available" && !board.access?.locked, unit: "USD/GPU-hour", access: board.access };
+    const metadata = { asOf: board.asOf, stale: board.stale, complete: board.status === "available" && !board.access?.locked, unit: "USD/GPU-hour", access: board.access,
+      methodology: "docs/gpu-rental-prices.md#list-indexes" };
     // Prices observed on providers' pages, not a feed; each board row says whether its source has gone quiet.
     const freshness = { source: "GPU cloud providers", status: "not-a-feed" as const, basis: "observed prices" };
     if (tab === "history") {
@@ -52,7 +56,9 @@ export const gpuHeadless: HeadlessPaneDefinition<"bundle"> = {
       const rows = await Promise.all(related.map(async (row) => {
         const quote = await ctx.marketData.getQuote(row.symbol, row.exchange).catch(() => null);
         const history = histories.find((entry) => entry.symbol === row.symbol);
-        return { symbol: row.symbol, role: row.role, price: quote?.price ?? null, change1d: quote?.changePercent ?? null,
+        // The regular session's last and move, as the pane's board shows them.
+        const headline = getRegularSessionDisplay(quote);
+        return { symbol: row.symbol, role: row.role, price: headline?.price ?? null, change1d: headline?.changePercent ?? null,
           change5d: history?.value ?? null, fiveDayAsOf: history?.asOf ?? null, quoteAsOf: quote?.lastUpdated ? new Date(quote.lastUpdated).toISOString() : null,
           ...quoteFreshnessFields(quote),
           gpu: row.reference ? gpuLabel(row.reference) : row.gpuModel, gpuSource: row.reference ? gpuSource(row.reference) : null, gpuChange7d: row.reference?.change7d ?? null };

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

@@ -1,6 +1,6 @@
 import type { GpuBasis, GpuBoardRow, GpuEvent, GpuObservation } from "../../../api-client/gpu";
 import { staticSeries } from "../../../components/chart/static/series";
-import { SERIES_COLORS } from "../../../time-series/resolve";
+import { SERIES_COLORS } from "../../../theme/series-colors";
 import type { ResolvedSeries } from "../../../time-series/types";
 import type { PricePoint } from "../../../types/financials";
 
@@ -32,16 +32,25 @@ const PROVIDER_NAMES: Record<string, string> = {
   scaleway: "Scaleway", horizon: "Horizon", verda: "Verda", latitude: "Latitude", imwt: "IMWT",
 };
 
+/**
+ * The provider-class rows are chain-linked list indexes, not raw medians. Servers that predate the
+ * rename still send "list median"; both strings read as the index.
+ */
+const LIST_INDEX_PROVIDER = /^(Hyperscaler|Neocloud) list (?:index|median)$/;
+
 /** Cloud operators are the product being compared. The data collection intermediary stays invisible. */
 export function gpuSource(row: Pick<GpuObservation, "source" | "provider" | "skuKey">): string {
+  const listIndex = LIST_INDEX_PROVIDER.exec(row.provider);
+  if (listIndex) return `${listIndex[1]} list index`;
   if (row.source === "vast" || row.source === "vast-ai") return "Marketplace ask median";
   if (row.source === "akash") return "Decentralized ask median";
   if (row.source === "runpod") return /community/i.test(`${row.provider} ${row.skuKey}`) ? "Community cloud asks" : "Secure cloud asks";
   return PROVIDER_NAMES[row.provider.toLowerCase()] ?? row.provider;
 }
 
-/** A source inside its basis section: the section already says list or ask, so a median drops the word. */
-export const gpuShortSource = (row: Pick<GpuObservation, "source" | "provider" | "skuKey">) => gpuSource(row).replace(/ (?:list|ask) median$/, " median");
+/** A source inside its basis section: the section already says list or ask, so an index or median drops the word. */
+export const gpuShortSource = (row: Pick<GpuObservation, "source" | "provider" | "skuKey">) =>
+  gpuSource(row).replace(/ list index$/, " index").replace(/ ask median$/, " median");
 
 export function gpuTime(value: string | null | undefined, compact = false): string {
   if (!value) return "-";
@@ -73,7 +82,7 @@ export function gpuBasisColor(basis: GpuBasis): string {
 export const gpuVariant = (row: Pick<GpuObservation, "formFactor" | "memoryGb">): string[] =>
   [row.formFactor, row.memoryGb ? `${row.memoryGb}GB` : null].filter((part): part is string => !!part);
 
-/** Medians lead their section: provider-class medians and the marketplace offer medians. */
+/** Indexes and medians lead their section: the provider-class list indexes and the marketplace offer medians. */
 export const gpuHeadline = (row: Pick<GpuObservation, "providerClass" | "source">) =>
   !row.source.startsWith("ref-") && (row.providerClass === "aggregate" || row.source === "vast" || row.source === "vast-ai" || row.source === "akash");
 
@@ -320,7 +329,7 @@ export function gpuEquityRows(rows: readonly GpuBoardRow[], selectedModel: strin
     const aggregates = candidates.filter((row) => row.providerClass === "aggregate").sort((a, b) =>
       Number(b.formFactor === "SXM") - Number(a.formFactor === "SXM") || (b.stats?.n ?? 0) - (a.stats?.n ?? 0) || (b.memoryGb ?? 0) - (a.memoryGb ?? 0));
     const reference = "provider" in equity ? candidates.find((row) => gpuSource(row) === equity.provider)
-      : aggregates.find((row) => row.provider === "Neocloud list median") ?? aggregates[0];
+      : aggregates.find((row) => row.provider.startsWith("Neocloud")) ?? aggregates[0];
     return { ...equity, gpuModel: model, reference: reference ?? null };
   });
 }

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

@@ -153,6 +153,7 @@ function HelpPane({ focused, width, height }: PaneProps) {
       entry("des", ["DES", "<ticker>"], "Open security details for a specific ticker."),
       entry("help-card", ["HELP", "<function>"], "Open a function's help card: what it shows, its keys, how fresh its data is. HELP HELP reaches support."),
       entry("upgrade", ["UPGRADE"], tf("Go Pro for real-time data at gloom.sh/cloud, free for {days} days.", { days: trialDays })),
+      entry("mcp", ["MCP"], "Connect Claude Code, Codex, Cursor or any MCP client to Gloom's research tools."),
       entry("move", ["Up/Down", "Ctrl+P/N"], "Move through command bar results."),
       entry("page", ["PageUp/PageDown", "Ctrl+Home/End"], "Jump a page, or to the first or last result."),
       entry("run", ["Enter", "Shift+Enter"], "Run the selected result or its secondary action."),

package/src/plugins/builtin/holders/beneficial-client.ts

@@ -7,7 +7,9 @@ import type {
   BeneficialOwnersPayload,
 } from "../../../api-client/beneficial-owners";
 import { ApiRequestError, isAccessDenied } from "../../../api-client/errors";
+import { listingAbroad, type IssuerListingParams } from "../../../api-client/paths";
 import { createPluginCache } from "../../../data/plugin-cache";
+import { secListingKey } from "../../../utils/sec";
 import { finiteOrNull, recordOrNull } from "../../../utils/guards";
 import { cachedCloudResource, loadCloudResource, type CloudResource } from "../shared/cloud-resource";
 import { CLOUD_SESSION_REQUIRED } from "../shared/research-cloud-session";
@@ -28,6 +30,8 @@ export interface BeneficialOwnersRequest {
   form?: BeneficialOwnersForm;
   /** Every report instead of the latest per filer. */
   history?: boolean;
+  /** The listing's venue and company, for a listing outside the US. */
+  listing?: IssuerListingParams;
 }
 
 type BeneficialOwnersClient = Pick<typeof apiClient, "getCloudSecBeneficialOwners">;
@@ -142,7 +146,7 @@ function describeFailure(error: unknown, ticker: string): unknown {
  */
 export async function fetchBeneficialOwners(
   ticker: string,
-  { form = "all", history = false }: BeneficialOwnersRequest = {},
+  { form = "all", history = false, listing }: BeneficialOwnersRequest = {},
   { client = apiClient, signal }: { client?: BeneficialOwnersClient; signal?: AbortSignal } = {},
 ): Promise<BeneficialOwnersPayload> {
   const symbol = ticker.trim().toUpperCase();
@@ -154,6 +158,8 @@ export async function fetchBeneficialOwners(
     for (;;) {
       const page = normalizeBeneficialOwnersPayload(await client.getCloudSecBeneficialOwners({
         ticker: symbol,
+        exchange: listing?.exchange,
+        name: listing?.name,
         form,
         history,
         limit: PAGE_SIZE,
@@ -178,10 +184,20 @@ export async function fetchBeneficialOwners(
       offset = nextOffset;
     }
   } catch (error) {
+    // A listing abroad whose company the SEC does not know has no reports.
+    const abroad = listingAbroad(symbol, listing?.exchange);
+    if (abroad && error instanceof ApiRequestError && error.status === 404) return noReports(symbol, history);
     throw describeFailure(error, symbol);
   }
 }
 
+function noReports(ticker: string, history: boolean): BeneficialOwnersPayload {
+  return {
+    ticker, cik: "", companyName: "", asOf: null, owners: [], ...(history ? { filings: [] } : {}),
+    hasMore: false, nextOffset: null, coverage: null,
+  };
+}
+
 /** Pages can overlap when a report lands between two requests. */
 function dedupe(rows: BeneficialOwnerFiling[]): BeneficialOwnerFiling[] {
   const seen = new Set<string>();
@@ -193,17 +209,23 @@ function dedupe(rows: BeneficialOwnerFiling[]): BeneficialOwnerFiling[] {
   });
 }
 
-const cacheKey = (ticker: string) => ticker.trim().toUpperCase();
+// SAN in Paris is not SAN in New York: a listing abroad is cached under its venue.
+const cacheKey = (ticker: string, listing?: IssuerListingParams) => secListingKey(ticker, listing?.exchange);
 
-export function cachedBeneficialOwners(ticker: string): CloudResource<BeneficialOwnersPayload> | null {
-  return cachedCloudResource(beneficialOwnersCache, cacheKey(ticker));
+export function cachedBeneficialOwners(ticker: string, listing?: IssuerListingParams): CloudResource<BeneficialOwnersPayload> | null {
+  return cachedCloudResource(beneficialOwnersCache, cacheKey(ticker, listing));
 }
 
 /** The pane's list: the latest report per filer, both kinds, cached on disk. */
-export async function loadBeneficialOwners(ticker: string, force = false): Promise<CloudResource<BeneficialOwnersPayload>> {
+export async function loadBeneficialOwners(
+  ticker: string,
+  force = false,
+  listing?: IssuerListingParams,
+): Promise<CloudResource<BeneficialOwnersPayload>> {
+  const key = cacheKey(ticker, listing);
   try {
-    return await loadCloudResource(beneficialOwnersCache, cacheKey(ticker), () => fetchBeneficialOwners(ticker), { force });
+    return await loadCloudResource(beneficialOwnersCache, key, () => fetchBeneficialOwners(ticker, { listing }), { force });
   } catch (error) {
-    throw describeFailure(error, cacheKey(ticker));
+    throw describeFailure(error, key);
   }
 }

package/src/plugins/builtin/holders/beneficial-view.tsx

@@ -10,6 +10,7 @@ import {
   type DataTableKeyEvent,
 } from "../../../components";
 import { handleRefreshKey, loadingErrorFooterInfo } from "../../../components/data-table/table-pane";
+import type { IssuerListingParams } from "../../../api-client/paths";
 import { useAsyncResource } from "../../../react/async-resource";
 import { useAutoRefresh } from "../../../react/auto-refresh";
 import { colors, priceColor } from "../../../theme/colors";
@@ -55,10 +56,13 @@ export function BeneficialOwnersView({
   fundMatches,
   onCycleView,
   onRefreshHolders,
+  listing,
 }: {
   focused: boolean;
   width: number;
   symbol: string | null;
+  /** The listing's venue and company, for a listing outside the US. */
+  listing?: IssuerListingParams;
   holderRows: readonly HolderRow[];
   fundMatches: ReadonlyMap<string, Holder13FMatch>;
   onCycleView: () => void;
@@ -75,11 +79,11 @@ export function BeneficialOwnersView({
 
   // A session change retries a request the sign-in wall was shown for.
   const loader = useMemo(
-    () => symbol ? (force: boolean) => loadBeneficialOwners(symbol, force) : null,
-    [symbol, session.requestKey],
+    () => symbol ? (force: boolean) => loadBeneficialOwners(symbol, force, listing) : null,
+    [symbol, listing, session.requestKey],
   );
   const resource = useAsyncResource(loader, {
-    initialData: () => symbol ? cachedBeneficialOwners(symbol) : null,
+    initialData: () => symbol ? cachedBeneficialOwners(symbol, listing) : null,
     clearOnError: (error) => error instanceof Error && isCloudSessionRequired(error.message),
   });
   useAutoRefresh(resource.updatedAt, resource.load);

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

@@ -35,6 +35,7 @@ const CHANGE_COLUMN_KEYS = new Set(["changeShares", "changePercent"]);
 const BASIS_COLUMN_KEY = "shareBasis";
 import type { BeneficialOwnersPayload } from "../../../api-client/beneficial-owners";
 import { fetchBeneficialOwners, type BeneficialOwnersRequest } from "./beneficial-client";
+import { resolveHeadlessIssuerListing } from "../shared/headless-market-data";
 import type { BeneficialColumnId } from "./beneficial-model";
 import {
   BENEFICIAL_REPORT_COLUMNS,
@@ -136,7 +137,11 @@ export interface HoldersHeadlessDependencies {
 
 const defaultDependencies: HoldersHeadlessDependencies = {
   loadSnapshot: (symbol, _args, ctx) => loadHolderSnapshot(ctx.marketData, symbol),
-  loadBeneficialOwners: (symbol, request, ctx) => fetchBeneficialOwners(symbol, request, {
+  // A listing abroad names its venue and company, so it never reads a US namesake's owners.
+  loadBeneficialOwners: async (symbol, request, ctx) => fetchBeneficialOwners(symbol, {
+    ...request,
+    listing: await resolveHeadlessIssuerListing(ctx, symbol),
+  }, {
     client: ctx.apiClient,
     signal: ctx.signal,
   }),

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

@@ -43,6 +43,7 @@ import {
 import { loadHolderData } from "./client";
 import { HoldersTreemap } from "./treemap";
 import { BeneficialOwnersView } from "./beneficial-view";
+import { useIssuerListing } from "../shared/ticker-request";
 import type { HolderColumn, HolderColumnId, HolderRow, SortPreference, ViewMode } from "./types";
 import { loadHolder13FMatches, type Holder13FMatch } from "./thirteenf-match";
 import { useSampledValue, useTickerQuoteStream } from "../../../state/hooks/live-ticker-financials";
@@ -65,6 +66,7 @@ export function HoldersView({ focused, width, height }: { focused: boolean; widt
   const fundMatchAbortRef = useRef<AbortController | null>(null);
 
   const exchange = ticker?.metadata.exchange ?? "";
+  const issuerListing = useIssuerListing(ticker);
   const loadHolders = useMemo(() => symbol ? async (forceRefresh: boolean) => {
     if (!dataProvider) throw new Error("Holder data unavailable");
     return loadHolderData(dataProvider, symbol, exchange, forceRefresh ? { cacheMode: "refresh" } : undefined);
@@ -337,6 +339,7 @@ export function HoldersView({ focused, width, height }: { focused: boolean; widt
           focused={focused}
           width={width}
           symbol={symbol ?? null}
+          listing={issuerListing}
           holderRows={rows}
           fundMatches={fundMatches}
           onCycleView={toggleView}

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

@@ -22,7 +22,7 @@ import {
   type StatItem,
 } from "../../../components";
 import { useDebouncedPluginPaneState, usePluginPaneState } from "../../runtime";
-import { isUsEquityTicker } from "../../../utils/sec";
+import { mayBeUsEquityTicker } from "../../../utils/sec";
 import { formatCompact } from "../../../utils/format";
 import { nextHeaderSort } from "../../../utils/sort-values";
 import { formatShortDate } from "../../../utils/datetime-format";
@@ -130,7 +130,7 @@ function InsiderView({ width, height, focused }: { width: number; height: number
     [setOpenItemIdState],
   );
   const [sort, setSort] = useState<StackSortPreference<InsiderColumnId>>({ columnId: "date", direction: "desc" });
-  const eligibleTicker = isUsEquityTicker(ticker);
+  const eligibleTicker = mayBeUsEquityTicker(ticker);
   const instrument = instrumentFromTicker(ticker, ticker?.metadata.ticker ?? null);
 
   const filingsEntry = useSecFilingsQuery(
@@ -458,7 +458,7 @@ export const insiderModule: PluginModule = {
         description: "Insider transaction activity for the selected ticker.",
         keywords: ["insider", "form 4", "ownership", "transactions", "ins"],
         shortcut: "INS",
-        canCreate: (_context, options) => !options?.ticker || isUsEquityTicker(options.ticker),
+        canCreate: (_context, options) => !options?.ticker || mayBeUsEquityTicker(options.ticker),
       }),
       headless: insiderHeadless,
     },
@@ -471,7 +471,7 @@ export const insiderModule: PluginModule = {
       order: 47,
       component: InsiderView,
       instruments: ["equity"],
-      isVisible: ({ ticker }) => isUsEquityTicker(ticker),
+      isVisible: ({ ticker }) => mayBeUsEquityTicker(ticker),
     });
   },
 };