gloomberb 0.18.4 → 0.19.0

package/src/types/plugin.ts

@@ -20,6 +20,7 @@ export type {
   HeadlessPaneOptionType,
   HeadlessPaneOptionValue,
   HeadlessPaneOptionValues,
+  HeadlessPaneReference,
   HeadlessPaneResult,
   HeadlessPaneResultByShape,
   HeadlessPaneRow,
@@ -529,6 +530,14 @@ export interface PaneTemplateDef {
   description: string;
   keywords?: string[];
   shortcut?: PaneTemplateShortcut;
+  /**
+   * False leaves the function out of every list and search of functions
+   * (command-bar browse, search and assistant, Help, `gloom catalog` and
+   * search, the plugin directory, chat suggestions) while typing its code
+   * still opens it, `fn` and `shot` still run it and its help still answers.
+   * ATTN until it publishes (attention/listing.ts).
+   */
+  listed?: boolean;
   /** Template-specific headless model. Takes precedence over the pane-level model. */
   headless?: HeadlessPaneDefinition;
   /**
@@ -945,7 +954,7 @@ export interface AppNotificationRequest {
   /**
    * What a built-in notice is about, so the Unread list can keep it after the
    * toast is gone and open it again: `price:<alertId>`, `catalyst:<eventId>`,
-   * `econ:<eventId>` or `team:<cardId>`. Other values are not kept.
+   * `econ:<eventId>`, `team:<cardId>` or `scan:<paneId>`. Other values are not kept.
    */
   refId?: string;
   /** Rendered next to `action`. Use for a dismissing counterpart such as snooze. */

package/src/ui/host.tsx

@@ -82,6 +82,8 @@ export interface ChartVectorShape {
   gradient?: readonly string[];
   /** Opacity of the whole shape, so others can recede behind a highlighted one. */
   opacity?: number;
+  /** Text set just above the shape's first point, such as a retracement level's ratio and price. */
+  label?: string;
 }
 
 interface TextEditBuffer {
@@ -508,6 +510,7 @@ export interface HostCheckboxProps {
 interface HostQueryBarOption {
   value: string;
   label: string;
+  group?: string;
   description?: string;
   disabled?: boolean;
   selected: boolean;

package/src/updater/command-names.ts

@@ -3,7 +3,7 @@ import { lstat, readFile, readlink, stat, symlink, writeFile } from "fs/promises
 import { basename, dirname, join, resolve } from "path";
 
 /**
- * The terminal command is `gloom`. `gloomberb`, its name before 0.19, keeps
+ * The terminal command is `gloom`. `gloomberb`, its name before 0.18.4, keeps
  * working beside it, for scripts and habits.
  *
  * An install from before the rename has only `gloomberb`, and the ways it
@@ -58,17 +58,21 @@ export function linkStandaloneCommand(execPath: string): string | null {
   return addSymlink(name, path);
 }
 
+/** Homebrew's prefixes on Apple Silicon and on Intel. */
+export const HOMEBREW_PREFIXES = ["/opt/homebrew", "/usr/local"];
+
 /** Homebrew's command folders on Apple Silicon and on Intel. */
-const HOMEBREW_BINS = ["/opt/homebrew/bin", "/usr/local/bin"];
+const HOMEBREW_BINS = HOMEBREW_PREFIXES.map((prefix) => join(prefix, "bin"));
 
 /**
- * Where a Mac keeps the desktop app's command: install.sh's folder, Homebrew's,
- * then the rest of PATH. A GUI app's PATH rarely has the first ones, so they
- * are named outright.
+ * Where a Mac keeps the desktop app's command: install.sh's folder, `~/bin`,
+ * Homebrew's, then the rest of PATH. A GUI app's PATH rarely has the first
+ * ones, so they are named outright.
  */
-function macCommandFolders(homeDir: string, pathEnv: string, homebrewBins: readonly string[]): string[] {
+export function macCommandFolders(homeDir: string, pathEnv: string, homebrewBins: readonly string[] = HOMEBREW_BINS): string[] {
   return [...new Set([
     homeDir ? join(homeDir, ".local", "bin") : "",
+    homeDir ? join(homeDir, "bin") : "",
     ...homebrewBins,
     ...pathEnv.split(":"),
   ].filter(Boolean))];
@@ -141,7 +145,7 @@ interface DesktopCommandOptions {
   homeDir: string;
   /** PATH as the app sees it. */
   pathEnv: string;
-  /** `%LOCALAPPDATA%`, where the Windows installer puts the app by default. */
+  /** `%LOCALAPPDATA%`, where the Windows installer puts the app by default (`Programs\Gloom`, `Programs\Gloomberb` before the rename). */
   localAppData?: string;
   /** Homebrew's command folders; tests pass none. */
   homebrewBins?: readonly string[];
@@ -166,6 +170,7 @@ export async function linkDesktopCommands({
     added = await Promise.all(macCommandFolders(homeDir, pathEnv, homebrewBins).map(linkMacCommand));
   } else if (platform === "win32") {
     const folders = new Set([
+      localAppData ? join(localAppData, "Programs", "Gloom", "bin") : "",
       localAppData ? join(localAppData, "Programs", "Gloomberb", "bin") : "",
       ...pathEnv.split(";"),
     ].filter(Boolean));

package/src/updater/failure.ts

@@ -24,7 +24,7 @@ const UPDATE_FAILURE_CODES = [
   "no_build",
   /** The download stopped before the whole file arrived. */
   "interrupted",
-  /** The file arrived whole but does not match its checksum, or does not unpack. */
+  /** The download does not match its checksum, or does not unpack (part of it is missing or damaged). */
   "corrupt",
   "permission_denied",
   /** The macOS app runs from where it cannot be replaced: a disk image, App Translocation, another volume. */
@@ -112,6 +112,9 @@ export function classifyUpdateError(error: unknown): UpdateFailureCode {
   if (status) return httpStatusFailureCode(Number(status));
   if (/checksum mismatch|hash mismatch/i.test(message)) return "corrupt";
   if (/zstd|decompress|gunzip|incorrect header|unexpected end of (?:file|data)/i.test(message)) return "corrupt";
+  // Bun.Archive on a tar that does not read: cut off, damaged, or none at all.
+  // Unpacking says only "ReadError", whatever stopped it.
+  if (/\bReadError\b|truncated tar|damaged tar|unrecognized archive format/i.test(message)) return "corrupt";
   if (/timed? ?out/i.test(message)) return "timeout";
   if (/rate limit/i.test(message)) return "rate_limited";
   if (/read-only file system/i.test(message)) return "read_only";

package/src/utils/cli-output.ts

@@ -74,6 +74,47 @@ const PLAIN_EMPTY_CELL = "—";
 let colorEnabledOverride: boolean | null = null;
 let widthOverride: number | null = null;
 let plainOverride: boolean | null = null;
+/** Output is being rendered for a file (`renderForFile`), which has no terminal width. */
+let renderingForFile = false;
+
+/** Renders for a file from here on; the function returned puts the terminal's rendering back. */
+function enterFileRendering(): () => void {
+  const saved = { color: colorEnabledOverride, plain: plainOverride, file: renderingForFile };
+  colorEnabledOverride = false;
+  plainOverride = true;
+  renderingForFile = true;
+  return () => {
+    colorEnabledOverride = saved.color;
+    plainOverride = saved.plain;
+    renderingForFile = saved.file;
+  };
+}
+
+/**
+ * Output rendered for a file (`fn --output`) as a redirect gets it: plain,
+ * without colour, and fitted to no width but `--width`'s.
+ */
+export function renderForFile<T>(render: () => T): T {
+  const restore = enterFileRendering();
+  try {
+    return render();
+  } finally {
+    restore();
+  }
+}
+
+/**
+ * `renderForFile` around work that renders as it loads: a report whose text is
+ * drawn while it is built is drawn for the file, though stdout is a terminal.
+ */
+export async function buildForFile<T>(build: () => Promise<T>): Promise<T> {
+  const restore = enterFileRendering();
+  try {
+    return await build();
+  } finally {
+    restore();
+  }
+}
 
 function colorEnabled(): boolean {
   if (colorEnabledOverride != null) return colorEnabledOverride;
@@ -176,7 +217,7 @@ export function setCliWidthOverride(value: number | null): void {
 /** Columns the output is fitted to: `--width`, else the terminal's, or null when output is piped or redirected. */
 export function cliTerminalWidth(): number | null {
   if (widthOverride != null) return widthOverride;
-  if (!process.stdout.isTTY) return null;
+  if (renderingForFile || !process.stdout.isTTY) return null;
   const columns = process.stdout.columns;
   return typeof columns === "number" && columns > 0 ? columns : null;
 }

package/src/utils/crypto-pair.ts

@@ -91,6 +91,50 @@ export const MAJOR_COIN_NAMES: ReadonlyMap<string, string> = new Map([
   ["BNB", "BNB"],
 ]);
 
+/**
+ * The largest coins by market value, stablecoins and gold tokens left out, with
+ * how a note names each: the coins whose bare ticker a listed company or fund
+ * may hold instead (SOL is a stale Emeren Group, LINK is Interlink Electronics).
+ * A hint reads this list; `MAJOR_COIN_NAMES` stays the shorter one stories and
+ * company-name lookups use, so a word such as "stellar" is still a company's.
+ */
+export const TOP_COIN_NAMES: ReadonlyMap<string, string> = new Map([
+  ...MAJOR_COIN_NAMES,
+  ["TRX", "tron"],
+  ["ZEC", "zcash"],
+  ["HYPE", "hyperliquid"],
+  ["XMR", "monero"],
+  ["XLM", "stellar"],
+  ["NEAR", "near protocol"],
+  ["TON", "toncoin"],
+  ["UNI", "uniswap"],
+  ["SUI", "sui"],
+  ["HBAR", "hedera"],
+  ["TAO", "bittensor"],
+  ["SHIB", "shiba inu"],
+  ["ENA", "ethena"],
+  ["CRO", "cronos"],
+  ["AAVE", "aave"],
+  ["ONDO", "ondo"],
+  ["PEPE", "pepe"],
+  ["ICP", "internet computer"],
+  ["ETC", "ethereum classic"],
+  ["ARB", "arbitrum"],
+  ["ALGO", "algorand"],
+  ["ATOM", "cosmos"],
+  ["APT", "aptos"],
+  ["FIL", "filecoin"],
+  ["POL", "polygon"],
+  ["OP", "optimism"],
+  ["WLD", "worldcoin"],
+  ["MNT", "mantle"],
+  ["KAS", "kaspa"],
+  ["QNT", "quant"],
+  ["VET", "vechain"],
+  ["INJ", "injective"],
+  ["RENDER", "render"],
+]);
+
 const COIN_PAIR = /^([A-Z0-9]{1,15})[-/](?:USD|EUR|GBP|USDT|USDC|BTC)$/;
 // What a pair's listing name adds after the coin's: its quote currency, an id in brackets.
 const PAIR_NAME_SUFFIX = /(?:\s*\([^)]*\))+$|\s+(?:USD|EUR|GBP|USDT|USDC|BTC|US Dollars?)$/i;

package/src/utils/financial-statements.ts

@@ -116,11 +116,16 @@ export function statementFieldAvailability(row: FinancialStatement | undefined,
   return value && Number.isFinite(Date.parse(value)) ? value : undefined;
 }
 
+/** A date without a publication time is only known to be available after that day. */
+export function financialAvailabilityTime(value: string): number {
+  return Date.parse(value) + (/^\d{4}-\d{2}-\d{2}$/.test(value) ? 86_400_000 : 0);
+}
+
 /** A derived value is dated only when every input's availability is known. */
 export function completeAvailability(values: readonly (string | null | undefined)[]): string | undefined {
   if (values.length === 0 || values.some((value) => !value || !Number.isFinite(Date.parse(value)))) return undefined;
   return values.reduce<string | undefined>((latest, value) => (
-    !latest || Date.parse(value!) > Date.parse(latest) ? value! : latest
+    !latest || financialAvailabilityTime(value!) > financialAvailabilityTime(latest) ? value! : latest
   ), undefined);
 }
 

package/src/utils/forward-dividend.ts

@@ -14,6 +14,8 @@ import { formatDistributionAmount } from "./format";
  * the rate divided back.
  */
 export const LATEST_DISTRIBUTION = "latest distribution annualized";
+/** The basis of a forward rate that is the year's regular payments, which differ too widely for one to be annualized (unevenRegularPayments). */
+export const UNEVEN_REGULAR_PAYMENTS = "trailing regular payments: uneven interims";
 
 /**
  * What a trailing dividend yield is everywhere it shows (DVD, a fund's in

package/src/utils/fundamentals.ts

@@ -6,16 +6,19 @@ import { formatCompact } from "./format";
 import { formatUtcTime } from "./utc-time";
 
 export const RETRACTABLE_VALUATION_FIELDS = ["enterpriseValue", "enterpriseToRevenue"] as const;
+/** Every field a source can retract: the valuation fields, and a receipt's market cap (`marketCapUnavailable`). */
+export const RETRACTED_FUNDAMENTALS_FIELDS = [...RETRACTABLE_VALUATION_FIELDS, "marketCap"] as const;
 
-/** A retraction survives serialization and overrides a contradictory cached number. */
+/** A retraction survives serialization and overrides a contradictory cached number; its reason goes with it. */
 export function redactUnavailableFundamentals(value: Fundamentals | undefined): Fundamentals | undefined {
-  if (!value || value.unavailableFields === undefined) return value;
+  if (!value || (value.unavailableFields === undefined && value.marketCapUnavailable === undefined)) return value;
   const unavailableFields = Array.isArray(value.unavailableFields)
-    ? RETRACTABLE_VALUATION_FIELDS.filter((field) => value.unavailableFields!.includes(field)) : [];
+    ? RETRACTED_FUNDAMENTALS_FIELDS.filter((field) => value.unavailableFields!.includes(field)) : [];
   const result = { ...value };
   if (unavailableFields.length) result.unavailableFields = unavailableFields;
   else delete result.unavailableFields;
   for (const field of unavailableFields) delete result[field];
+  if (!unavailableFields.includes("marketCap")) delete result.marketCapUnavailable;
   return result;
 }
 
@@ -243,6 +246,24 @@ export function epsConversionNote(fundamentals: Pick<Fundamentals, "financialCur
   return eps && amounts && eps !== amounts ? `EPS (TTM) in ${eps}, converted from ${amounts} at report-date rates.` : undefined;
 }
 
+/** What a trailing EPS that is not the filed quarters' is called where it is shown (EE's TTM row). */
+export const SERVED_TRAILING_EPS = "Gloom Cloud's TTM";
+
+/**
+ * "EPS (TTM) and P/E (TTM) are Gloom Cloud's trailing figures, not the last four filed quarters'.": the headline EPS
+ * and P/E are the filed quarters' (time-series/filed-trailing-eps), so served ones say so, naming those `shown`
+ * ("P/E (TTM) is Gloom Cloud's trailing figure, ..." for a fund's P/E with no EPS). Undefined otherwise.
+ */
+export function trailingEpsSourceNote(
+  fundamentals: Pick<Fundamentals, "trailingEpsSource"> | undefined,
+  shown: { eps: boolean; pe: boolean },
+): string | undefined {
+  if (fundamentals?.trailingEpsSource !== "served" || (!shown.eps && !shown.pe)) return undefined;
+  const figures = shown.eps && shown.pe ? "EPS (TTM) and P/E (TTM) are Gloom Cloud's trailing figures"
+    : `${shown.eps ? "EPS (TTM)" : "P/E (TTM)"} is Gloom Cloud's trailing figure`;
+  return `${figures}, not the last four filed quarters'.`;
+}
+
 type PriceEarningsBasis = Pick<Fundamentals, "financialCurrency" | "ttmConversion" | "epsCurrency" | "trailingPEConversion">;
 
 /** The trailing EPS in the price's currency: converted at the rate the served P/E used when it says so. */

package/src/utils/fx-market-hours.ts

@@ -30,12 +30,35 @@ export function isFxMarketOpen(time: number): boolean {
 }
 
 /**
- * The FX trading day an instant belongs to, as "YYYY-MM-DD": the day rolls
- * at 17:00 New York time, so Wednesday 18:00 New York is Thursday's.
+ * The FX trading day a print made at `time` belongs to, as "YYYY-MM-DD": the
+ * day rolls at 17:00 New York time, so Wednesday 18:00 New York is
+ * Thursday's. A print stamped exactly 17:00:00 is that day's close, so it is
+ * still that day's.
  */
 export function fxTradingDay(time: number): string {
   // The roll is 17:00, seven hours before New York's midnight, daylight saving or not.
-  return zonedDateKey(time + 7 * HOUR_MS, NEW_YORK);
+  return zonedDateKey(time - 1 + 7 * HOUR_MS, NEW_YORK);
+}
+
+/**
+ * The FX trading day of a print made at `time` (fxTradingDay), or null for a
+ * print made while the market is shut: from just after Friday's 17:00 New
+ * York close, whose own print still counts, through Sunday's 17:00 open. A
+ * tick over the weekend belongs to no trading day.
+ */
+export function fxPrintTradingDay(time: number): string | null {
+  return Number.isFinite(time) && isFxMarketOpen(time - 1) ? fxTradingDay(time) : null;
+}
+
+/**
+ * The FX trading day the market is on at `time`: the day in progress while it
+ * trades, or the Friday that closed it while it is shut.
+ */
+export function fxTradingDayAt(time: number): string | null {
+  const day = fxPrintTradingDay(time);
+  if (day != null || !Number.isFinite(time)) return day;
+  const shut = currentFxClosureStart(time - 1);
+  return shut != null ? fxTradingDay(shut) : null;
 }
 
 /** The latest 17:00 New York on `weekday` (0 is Sunday) at or before `time`. */

package/src/utils/main-thread-stall.ts

@@ -9,13 +9,43 @@ const SAMPLE_INTERVAL_MS = 250;
  */
 const STALL_THRESHOLD_MS = 400;
 
+export interface StallEvent {
+  blockedMs: number;
+  /** The last measured section before the stall (perf-marks), if any. */
+  lastMeasured?: string;
+  /** How long before the stall was noticed that section ended. */
+  lastMeasuredEndedMsAgo?: number;
+}
+
+let stallSink: ((event: StallEvent) => void) | null = null;
+
+/**
+ * Where this process's stalls go besides the Debug Log: the stall log and its
+ * report (telemetry/stall-reports.ts), or, in the desktop window, the Bun
+ * process that keeps them.
+ */
+export function setStallSink(next: ((event: StallEvent) => void) | null): () => void {
+  stallSink = next;
+  return () => {
+    if (stallSink === next) stallSink = null;
+  };
+}
+
+function noteStall(event: StallEvent): void {
+  try {
+    stallSink?.(event);
+  } catch {
+    // Intentional ignore: reporting a freeze must never become one.
+  }
+}
+
 export interface MainThreadStallMonitorOptions {
   intervalMs?: number;
   thresholdMs?: number;
   now?: () => number;
   schedule?: (callback: () => void, delayMs: number) => unknown;
   cancel?: (handle: unknown) => void;
-  report?: (blockedMs: number, context: Record<string, unknown>) => void;
+  report?: (blockedMs: number, context: Omit<StallEvent, "blockedMs">) => void;
 }
 
 function defaultNow(): number {
@@ -41,7 +71,10 @@ export function startMainThreadStallMonitor(
   const schedule = options.schedule ?? ((callback, delayMs) => setInterval(callback, delayMs));
   const cancel = options.cancel ?? ((handle) => clearInterval(handle as ReturnType<typeof setInterval>));
   const report = options.report
-    ?? ((blockedMs, context) => recordPerfSample("runtime.stall", blockedMs, context));
+    ?? ((blockedMs, context) => {
+      recordPerfSample("runtime.stall", blockedMs, context);
+      noteStall({ blockedMs, ...context });
+    });
 
   let previous = now();
   const handle = schedule(() => {

package/src/utils/market-capitalization.ts

@@ -20,11 +20,34 @@ function explicitCurrency(currency: string | undefined): currency is string {
   return currency != null && /^[A-Z]{3}$/.test(currency);
 }
 
-/** A lightweight quote can omit capitalization without invalidating the snapshot. */
+/** What every view says for a cap Gloom Cloud withheld, in the words its screener uses. */
+const WITHHELD_MARKET_CAP: Record<NonNullable<Fundamentals["marketCapUnavailable"]>, { gap: string; note: string }> = {
+  "receipt-priced-as-ordinary": {
+    gap: "receipt, no ratio",
+    note: "No market cap: a depositary receipt with no known ratio, whose source's cap is the receipt price x the company's ordinary shares.",
+  },
+};
+
+/**
+ * Why a listing has no market cap when Gloom Cloud withheld it: `gap` for a cell, `note` for a line under a
+ * report. Null when the cap was not withheld.
+ */
+export function withheldMarketCap(fundamentals: Pick<Fundamentals, "unavailableFields" | "marketCapUnavailable"> | undefined):
+  { gap: string; note: string } | null {
+  if (!fundamentals?.unavailableFields?.includes("marketCap")) return null;
+  const reason = fundamentals.marketCapUnavailable ? WITHHELD_MARKET_CAP[fundamentals.marketCapUnavailable] : undefined;
+  return reason ?? { gap: "withheld", note: "No market cap: Gloom Cloud withheld it." };
+}
+
+/**
+ * A lightweight quote can omit capitalization without invalidating the snapshot. A cap Gloom Cloud withheld
+ * (withheldMarketCap) is none, the quote's included.
+ */
 export function selectMarketCapitalization(
   quote: Quote | undefined,
   fundamentals: Fundamentals | undefined,
 ): MarketCapitalization | null {
+  if (withheldMarketCap(fundamentals)) return null;
   if (usableValue(quote?.marketCap) && explicitCurrency(quote?.currency)) {
     return { value: quote.marketCap, currency: quote.currency,
       provenance: { kind: "quote", source: quote.providerId } };

package/src/utils/network-failure.ts

@@ -3,9 +3,10 @@ export const DATA_SERVICE_UNREACHABLE_MESSAGE = "Gloom couldn't reach its data s
 
 /**
  * A request that never reached the data service: no connection, a proxy that
- * refused it, a name that did not resolve. The fetch's own error is the
- * `cause`, and its `code` (Bun's `ConnectionRefused`, Node's `ENOTFOUND`) is
- * kept for code that classifies failures by it.
+ * refused it, a name that did not resolve, or a connection that hung with
+ * nothing coming back before the request's deadline. The fetch's own error (or
+ * the deadline's) is the `cause`, and its `code` (Bun's `ConnectionRefused`,
+ * Node's `ENOTFOUND`) is kept for code that classifies failures by it.
  */
 export class DataServiceUnreachableError extends Error {
   readonly code?: string;
@@ -56,9 +57,11 @@ function cameFromServer(error: object): boolean {
 
 /**
  * Whether a request failed before any answer came back. A caller's abort and
- * a timeout are not: the first is on purpose, and the second reached a server
- * that did not answer in time. Nor is anything the server answered, whatever
- * its text or code says.
+ * a bare timeout are not: the first is on purpose, and the second may have
+ * reached a server that did not answer in time. A Cloud request whose deadline
+ * passed with nothing back from the service is one: the client throws it as
+ * `DataServiceUnreachableError`, as it does a refused connection. Nor is
+ * anything the server answered, whatever its text or code says.
  */
 export function isNetworkFailure(error: unknown): boolean {
   if (typeof error === "string") return NO_CONNECTION_MESSAGES.has(error.trim());

package/src/utils/option-expiry.ts

@@ -6,7 +6,9 @@
 
 import type { OptionsChain } from "../types/financials";
 import { hasRegularCloseHour, latestRegularSessionClose, sessionCalendarTimeZone } from "../market-data/market/freshness";
+import { listedCoinOptions } from "../market-data/options-alternatives";
 import { dateOptionHint, readCalendarDate } from "./calendar-date";
+import { isRoundTheClockCoin } from "./crypto-pair";
 import { canonicalExchange, isUsListingExchange } from "./exchanges";
 import { zonedWallClockToUtcMs } from "./zoned-date-time";
 
@@ -20,6 +22,23 @@ export const OPTION_EXPIRATION_FORMAT = "YYYY-MM-DD (2028-01-21), DD.MM.YYYY, Ja
 /** The value's name in a catalog flag, `--expiration <date|unix>`. */
 export const OPTION_EXPIRATION_PLACEHOLDER = "date|unix";
 
+/** Seconds into its UTC day that Deribit stamps each expiry at: its 08:00 UTC settlement. */
+const UTC_SETTLEMENT_SECONDS = 8 * 3600;
+
+/**
+ * Whether an expiry stamp is the settlement instant itself, as Deribit stamps
+ * its BTC and ETH expiries (08:00 UTC), rather than a listed option's date. No
+ * US listing is stamped at that hour: they carry the date's midnight or its close.
+ */
+export function isSettlementStamp(seconds: number): boolean {
+  return Number.isFinite(seconds) && ((seconds % 86_400) + 86_400) % 86_400 === UTC_SETTLEMENT_SECONDS;
+}
+
+/** `08:00 UTC` for a settlement stamp (`isSettlementStamp`); null for a dated one. */
+export function settlementStampTime(seconds: number): string | null {
+  return isSettlementStamp(seconds) ? `${new Date(seconds * 1000).toISOString().slice(11, 16)} UTC` : null;
+}
+
 /** The expiry's calendar date, `2028-01-21`; empty for a stamp that is not a time. */
 export function expiryIsoDate(seconds: number): string {
   const date = new Date(seconds * 1000);
@@ -89,6 +108,9 @@ export function formatDaysToExpiry(expiration: number, asOfMs: number, exchange?
   return isLiveOptionExpiry(expiration, asOfMs, exchange) ? `${Math.max(0, daysToExpiry(expiration, asOfMs))}d` : "expired";
 }
 
+/** The coin board's venue code, which a coin pair's listing carries. */
+const COIN_OPTIONS_VENUE = "CCC";
+
 /** Listed US options trade on the US equity calendar, NYSE's published one. */
 const US_OPTIONS_CALENDAR = "NYSE";
 const lastSessions = new Map<string, { date: string; close: number } | null>();
@@ -105,10 +127,33 @@ function expiryCalendarVenue(exchange: string | undefined): string {
     ? venue : US_OPTIONS_CALENDAR;
 }
 
+/**
+ * The venue to read an expiry's close on for a listing: the coin board for a
+ * coin whose options are listed (BTC-USD, ETH-USD, even when it carries no
+ * venue), else the listing's own.
+ */
+export function optionExpiryVenue(symbol: string | undefined, exchange: string | undefined): string | undefined {
+  return symbol && listedCoinOptions(symbol) ? COIN_OPTIONS_VENUE : exchange;
+}
+
+/**
+ * When a settlement-priced expiry settles (Deribit's BTC and ETH options): its
+ * stamp when it carries the 08:00 UTC settlement, or 08:00 UTC on a typed
+ * date's day for a coin listing. Any day of the week, weekends included: the
+ * US calendar does not apply. Null for a listed US option, whatever its venue.
+ */
+function settlementCloseMs(expiration: number, exchange: string | undefined): number | null {
+  if (isSettlementStamp(expiration)) return expiration * 1000;
+  if (!isRoundTheClockCoin(undefined, exchange)) return null;
+  return Math.floor(expiration / 86_400) * 86_400_000 + UTC_SETTLEMENT_SECONDS * 1000;
+}
+
 /** The expiry's last trading session, on or before its date, on its venue's calendar: the date and when it closed. */
 function expiryLastSession(expiration: number, exchange: string | undefined): { date: string; close: number } | null {
   const date = expiryIsoDate(expiration);
   if (!date) return null;
+  const settles = settlementCloseMs(expiration, exchange);
+  if (settles != null) return { date, close: settles };
   const venue = expiryCalendarVenue(exchange);
   const key = `${venue}:${date}`;
   const known = lastSessions.get(key);
@@ -128,7 +173,9 @@ function expiryLastSession(expiration: number, exchange: string | undefined): {
  * listing venue's last trading day on or before the expiry's date, on that
  * venue's clock and calendar. A US expiry closes at 16:00 New York, at 13:00
  * on a published early close, and one dated on a holiday or a weekend closed
- * with the session before it. Null for a stamp that is not a date.
+ * with the session before it. A Deribit expiry (BTC-USD, ETH-USD) settles at
+ * 08:00 UTC on its own date, a Saturday or Sunday too. Null for a stamp that
+ * is not a date.
  */
 export function optionExpiryCloseMs(expiration: number, exchange?: string): number | null {
   return expiryLastSession(expiration, exchange)?.close ?? null;

package/src/utils/options.ts

@@ -11,6 +11,16 @@ export function formatExpDate(ts: number): string {
   return `${month} ${d.getUTCDate()} '${yy}`;
 }
 
+/**
+ * A strike as every options pane writes it: grouped, with every listed
+ * decimal (`82,000`, `82.5`). 15 significant digits keep every listed decimal
+ * but drop binary noise from computed strikes such as spot * 0.9.
+ */
+export function formatStrikeLabel(strike: number): string {
+  return Number.isFinite(strike)
+    ? strike.toLocaleString("en-US", { maximumSignificantDigits: 15 }) : "\u2014";
+}
+
 /**
  * Parse IBKR option symbol like "UBER 260821C00090000" into components.
  * Returns null if not a recognized option symbol.

package/src/utils/plugin-proxy-hosts.json

@@ -12,6 +12,7 @@
     "data-api.polymarket.com",
     "data.pascal.trade",
     "efts.sec.gov",
+    "forms13f.com",
     "gamma-api.polymarket.com",
     "gateway.polymarket.us",
     "markets.newyorkfed.org",

package/src/utils/price-history.ts

@@ -2,7 +2,7 @@ import type { PricePoint, TickerFinancials } from "../types/financials";
 import { canonicalExchange } from "./exchanges";
 import { isRoundTheClockCoin } from "./crypto-pair";
 import { isCurrencyPairListing, isFxMarketOpen, latestFxWeekClose, latestFxWeekOpen } from "./fx-market-hours";
-import { hasPublishedSessionCalendar, historySourceWeekendDays, latestRegularSessionClose, latestRegularSessionOpen, sessionCalendarTimeZone } from "../market-data/market/freshness";
+import { hasPublishedSessionCalendar, historySourceWeekendDays, isMiddayBreakPrint, latestRegularSessionClose, latestRegularSessionOpen, sessionCalendarTimeZone } from "../market-data/market/freshness";
 import { zonedDateTimeParts } from "./zoned-date-time";
 import { regularHistorySessionStaleness } from "../market-data/history-session";
 import type { HistorySession } from "../types/price-history";
@@ -234,6 +234,12 @@ export function isPriceHistoryStaleForCurrentWindow(
   const age = now - latestTime;
   const allowedLag = allowedBarLagMs(intervalMs);
   if (age <= allowedLag) return false;
+  // A venue paused at midday (SSE/SZSE/BSE, TKO, ...) holds the morning's last
+  // bar current through the break, as the quote freshness rule does. A bar is
+  // labelled by its start, so an hourly bar ending at the break is judged by
+  // when it ends.
+  const latestBarEnd = intervalMs != null ? Math.min(latestTime + intervalMs, now) : latestTime;
+  if (isMiddayBreakPrint(latestBarEnd, options.exchange, now, 0)) return false;
   const sessions = listingSessionsAt(now, options);
   if (!sessions) return age > UNSCHEDULED_HISTORY_MAX_AGE_MS;
   const fetchedAt = options.fetchedAt ?? Number.NEGATIVE_INFINITY;
@@ -354,6 +360,11 @@ function barDate(time: number, timeZone: string): string {
   return `${year}-${String(month).padStart(2, "0")}-${String(day).padStart(2, "0")}`;
 }
 
+/** The venue date a daily bar at `time` names on `exchange`, read as calendarHistoryLastBarDate reads it. */
+export function dailyBarDate(time: number, exchange: string): string {
+  return barDate(time, sessionCalendarTimeZone(exchange) ?? "UTC");
+}
+
 /**
  * The venue date of the latest bar, read as calendarHistoryFetchState reads
  * it, so copies whose sources label a session differently compare equal.

package/src/utils/shell-word.ts

@@ -0,0 +1,8 @@
+/**
+ * One word of a command line as a shell reads it back: as written when it
+ * holds nothing a shell treats specially (`NVDA`, `SAN:EPA`, `BRK.B`), else
+ * in single quotes (`'Altria Group'`, `'$nvda'`, `'AT&T'`).
+ */
+export function shellWord(word: string): string {
+  return /^[\p{L}\p{N}._:@%+,/][\p{L}\p{N}._:@%+,/=-]*$/u.test(word) ? word : `'${word.replaceAll("'", "'\\''")}'`;
+}