@gloom-sh/terminal 0.18.5 → 0.19.0

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

@@ -1,9 +1,10 @@
-import { METRIC_ALERTS_KEY, isDailyMetric, metricName } from "./metric-model";
+import { METRIC_ALERTS_KEY, RELATIVE_ALERTS_KEY, closeBasis, metricName, metricReadingText } from "./metric-model";
 import { metricAvailabilityError } from "./metric-data";
-import { readLevelAlertStores } from "./storage";
+import { relativeAlertText } from "./metric-command";
+import { levelAlertStoreKey, readLevelAlertStores } from "./storage";
 import { Box, type ScrollBoxRenderable } from "../../../ui";
 import { Button, DetailScrollBody, KeyValueRow, Notice, PaneStatusBody, PaneFooterScope, usePaneTabs } from "../../../components";
-import { usePluginPaneState } from "../../runtime";
+import { usePluginPaneState, usePluginState } from "../../runtime";
 import { EventAlertsPane } from "./events-pane";
 import { AlertHistoryPane } from "./history-pane";
 import { useCallback, useEffect, useMemo, useRef, useState, useSyncExternalStore, type RefObject } from "react";
@@ -30,16 +31,21 @@ import {
   readAlertsStoreError,
   serializeAlerts,
 } from "./alert-engine";
-import { parseAlertCommandValues } from "./command";
+import { parseAlertEdit } from "./command";
 import { ALERT_TABS, ALERTS_KEY } from "./constants";
 import {
+  alertListing,
   conditionLabel,
   formatAlertDistance,
   formatAlertTargetPrice,
   formatCurrentPrice,
   formatQuoteChecked,
+  isoUtc,
+  listingWithCurrency,
   relativeTime,
 } from "./format";
+import { FIRED_LOG_KEY } from "./fired-log";
+import { withAlertChange } from "./alert-log";
 import type { AlertRule } from "./types";
 import { useQuoteEntries } from "../../../market-data/hooks";
 import { buildQuoteKey, resolveEntryData } from "../../../market-data/selectors";
@@ -57,7 +63,8 @@ type AlertColumnId =
   | "away"
   | "condition"
   | "quote"
-  | "triggered";
+  | "triggered"
+  | "created";
 
 type AlertColumn = DataTableColumn & { id: AlertColumnId };
 
@@ -69,8 +76,11 @@ const ALERT_COLUMNS: AlertColumn[] = [
   { id: "target", label: "Target", width: 11, align: "right" },
   { id: "away", label: "Away", width: 8, align: "right" },
   { id: "condition", label: "Trigger", width: 12, align: "left" },
-  { id: "quote", label: "Quote", width: 14, align: "left" },
+  // Wide enough to say "not checked yet" for an alert no check has read.
+  { id: "quote", label: "Quote", width: 15, align: "left" },
   { id: "triggered", label: "Alerted", width: 8, align: "left" },
+  // The day the alert was made (UTC), as Events lists its rules; the detail gives the instant.
+  { id: "created", label: "Since", width: 10, align: "left" },
 ];
 
 const DETAIL_ROW = { labelWidth: 10, emphasis: false } as const;
@@ -89,20 +99,28 @@ function AlertDetail({ alert, scrollRef }: { alert: AlertRule; scrollRef: RefObj
   const reason = alert.lastCheckError
     ? alert.lastCheckError.includes(alert.symbol) ? alert.lastCheckError : `${alert.symbol}: ${alert.lastCheckError}`
     : null;
+  const basis = alert.metric ? closeBasis(alert.metric) : null;
   return (
     <DetailScrollBody ref={scrollRef} resetScrollKey={alert.id}>
       <Box flexDirection="column">
         {reason ? <Box paddingBottom={1}><Notice tone="warning">{reason}</Notice></Box> : null}
         <KeyValueRow {...DETAIL_ROW} label="State" value={alert.status === "triggered" ? "Triggered" : "Active"} tone={alert.status === "triggered" ? "positive" : "muted"} />
+        <KeyValueRow {...DETAIL_ROW} label="Listing" value={listingWithCurrency(alertListing(alert), alert.lastQuoteCurrency)} />
         {/* With no quote the reason above says why; the price and its distance wait for one. */}
-        {alert.metric && isDailyMetric(alert.metric) ? <KeyValueRow {...DETAIL_ROW} label="Close date" value={alert.lastDailyClose ?? "Awaiting daily close"} /> : null}
+        {basis ? <KeyValueRow {...DETAIL_ROW} label="Close date" value={alert.lastDailyClose ?? `Awaiting ${basis}`} /> : null}
         {reason ? null : <KeyValueRow {...DETAIL_ROW} label="Current" value={formatCurrentPrice(alert, 24)} />}
+        {/* The two readings that place the quadrant, as RRG states them. */}
+        {!reason && alert.metric?.kind === "rrg" && alert.lastCheckedPrice != null && alert.lastCheckedTarget != null ? <>
+          <KeyValueRow {...DETAIL_ROW} label="Strength" value={alert.lastCheckedPrice.toFixed(2)} />
+          <KeyValueRow {...DETAIL_ROW} label="Momentum" value={alert.lastCheckedTarget.toFixed(2)} />
+        </> : null}
         {reason ? null : <KeyValueRow {...DETAIL_ROW} label="Away" value={formatAlertDistance(alert)} />}
         {reason
           ? alert.lastCheckedAt ? <KeyValueRow {...DETAIL_ROW} label="Checked" value={relativeTime(alert.lastCheckedAt)} tone="muted" /> : null
           : <KeyValueRow {...DETAIL_ROW} label="Quote" value={formatQuoteChecked(alert)} tone="muted" />}
         {alert.triggeredAt ? <KeyValueRow {...DETAIL_ROW} label="Alerted" value={relativeTime(alert.triggeredAt)} /> : null}
         <KeyValueRow {...DETAIL_ROW} label="Armed" value={relativeTime(alert.armedAt ?? alert.createdAt)} tone="muted" />
+        <KeyValueRow {...DETAIL_ROW} label="Created" value={isoUtc(alert.createdAt)} tone="muted" />
       </Box>
     </DetailScrollBody>
   );
@@ -144,7 +162,10 @@ export function AlertsPane(props: PaneProps) {
 function PriceAlertsPane({ focused, width, height }: PaneProps) {
   const [alertsJson, setAlertsJson] = usePluginConfigState<unknown>(ALERTS_KEY, "[]");
   const [metricsJson, setMetricsJson] = usePluginConfigState<unknown>(METRIC_ALERTS_KEY, "[]");
+  const [relativeJson, setRelativeJson] = usePluginConfigState<unknown>(RELATIVE_ALERTS_KEY, "[]");
   const { openPluginCommandWorkflow, notify } = usePluginAppActions();
+  // Deleting or re-arming a rule goes in this device's alert log, beside the alerts that fired.
+  const [, setAlertLog] = usePluginState<unknown>(FIRED_LOG_KEY, []);
   const dialog = useDialog();
   const [selectedIdx, setSelectedIdx] = useState(0);
   const [detailOpen, setDetailOpen] = useState(false);
@@ -152,9 +173,11 @@ function PriceAlertsPane({ focused, width, height }: PaneProps) {
   const detailAlertId = useRef<string | null>(null);
   const detailScrollRef = useRef<ScrollBoxRenderable | null>(null);
   // Keep the rule and daily-close basis visible in a narrow pane; the detail keeps all figures.
-  const columns = width < 106 ? ALERT_COLUMNS.filter(column => column.id !== "away" && column.id !== "triggered") : ALERT_COLUMNS;
+  const columns = width < 106 ? ALERT_COLUMNS.filter(column => column.id !== "away" && column.id !== "triggered" && column.id !== "created")
+    : width < 118 ? ALERT_COLUMNS.filter(column => column.id !== "created") : ALERT_COLUMNS;
   const showHorizontalScrollbar = columns.reduce((sum, column) => sum + column.width + 1, 2) > width;
-  const stores = useMemo(() => readLevelAlertStores(key => key === ALERTS_KEY ? alertsJson : metricsJson), [alertsJson, metricsJson]);
+  const stores = useMemo(() => readLevelAlertStores(key => key === ALERTS_KEY ? alertsJson : key === METRIC_ALERTS_KEY ? metricsJson : relativeJson),
+    [alertsJson, metricsJson, relativeJson]);
   const storeError = stores.error;
 
   const { alerts, rows } = useMemo(() => {
@@ -205,16 +228,17 @@ function PriceAlertsPane({ focused, width, height }: PaneProps) {
   }), [liveEntries, rows]);
 
   const savePaneAlerts = useCallback((id: string, next: (current: AlertRule[]) => AlertRule[]): string | null => {
-    const key = alerts.find(alert => alert.id === id)?.metric ? METRIC_ALERTS_KEY : ALERTS_KEY;
+    const found = alerts.find(alert => alert.id === id);
+    const key = found ? levelAlertStoreKey(found) : ALERTS_KEY;
     if (stores.errors[key]) return stores.errors[key];
     let error: string | null = null;
-    const setJson = key === METRIC_ALERTS_KEY ? setMetricsJson : setAlertsJson;
+    const setJson = key === METRIC_ALERTS_KEY ? setMetricsJson : key === RELATIVE_ALERTS_KEY ? setRelativeJson : setAlertsJson;
     setJson((currentJson: unknown) => {
       error = readAlertsStoreError(currentJson);
       return error ? currentJson : serializeAlerts(next(deserializeAlerts(currentJson)));
     });
     return error;
-  }, [alerts, setAlertsJson, setMetricsJson, stores]);
+  }, [alerts, setAlertsJson, setMetricsJson, setRelativeJson, stores]);
 
   const deleteAlert = useCallback(async (id: string) => {
     const alert = alerts.find((a) => a.id === id);
@@ -230,15 +254,24 @@ function PriceAlertsPane({ focused, width, height }: PaneProps) {
       notify({ body: error, type: "error" });
       return;
     }
+    setAlertLog((saved: unknown) => withAlertChange(saved, "deleted", alert));
     setSelectedIdx((prev) => Math.max(0, Math.min(prev, rows.length - 2)));
-  }, [alerts, dialog, notify, rows.length, savePaneAlerts]);
+  }, [alerts, dialog, notify, rows.length, savePaneAlerts, setAlertLog]);
 
   const rearmAlert = useCallback((id: string) => {
-    const error = savePaneAlerts(id,
-      (current) => current.map((a) => (a.id === id ? rebuildAlert(a) : a)),
-    );
-    if (error) notify({ body: error, type: "error" });
-  }, [notify, savePaneAlerts]);
+    // Only an alert that went off is re-armed, as the store reads at the write: one still waiting is left, and not logged.
+    const rearmed: AlertRule[] = [];
+    const error = savePaneAlerts(id, (current) => current.map((a) => {
+      if (a.id !== id || a.status !== "triggered") return a;
+      rearmed.push(a);
+      return rebuildAlert(a);
+    }));
+    if (error) {
+      notify({ body: error, type: "error" });
+      return;
+    }
+    for (const alert of rearmed) setAlertLog((saved: unknown) => withAlertChange(saved, "rearmed", alert));
+  }, [notify, savePaneAlerts, setAlertLog]);
 
   const startAddAlert = useCallback(() => {
     openPluginCommandWorkflow("set-alert");
@@ -276,11 +309,9 @@ function PriceAlertsPane({ focused, width, height }: PaneProps) {
             description: "SYMBOL above|below|crosses PRICE",
             placeholder: "AAPL above 200",
           }}
-          currentValue={selected.metric ? formatAlertDescription(selected).replace(" (TTM)", "").replace(" · on daily close", "") : `${selected.symbol} ${selected.condition} ${selected.targetPrice}`}
+          currentValue={relativeAlertText(selected) ?? (selected.metric ? formatAlertDescription(selected).replace(" (TTM)", "").replace(" · on daily close", "") : `${selected.symbol} ${selected.condition} ${selected.targetPrice}`)}
           onApply={async (value) => {
-            const parsed = parseAlertCommandValues({ shortcut: value });
-            if (!parsed) throw new Error("Use SYMBOL above|below|crosses PRICE.");
-            if (!!parsed.metric !== !!selected.metric) throw new Error("Add a new alert to change between price and a valuation or technical measure.");
+            const parsed = parseAlertEdit(selected, value);
             const error = savePaneAlerts(selected.id, (current) => current.map((alert) => (
               alert.id === selected.id
                 ? { ...editAlert(alert, parsed.symbol, parsed.condition, parsed.price), ...(parsed.metric ? { metric: parsed.metric } : {}) }
@@ -382,6 +413,9 @@ function PriceAlertsPane({ focused, width, height }: PaneProps) {
       case "current":
         return {
           text: formatCurrentPrice(alert, column.width),
+          // The quadrant word exports with the readings that place it.
+          ...(alert.metric?.kind === "rrg" && !alert.lastCheckError && alert.lastCheckedPrice != null && alert.lastCheckedTarget != null
+            ? { value: metricReadingText(alert.metric, { value: alert.lastCheckedPrice, target: alert.lastCheckedTarget }) } : {}),
           color: alert.lastCheckError ? colors.negative : colors.text,
         };
       case "target":
@@ -392,10 +426,12 @@ function PriceAlertsPane({ focused, width, height }: PaneProps) {
           color: colors.textDim,
         };
       case "condition":
-        return { text: alert.metric?.kind === "ma_cross" ? `Cross ${alert.metric.direction}` : conditionLabel(alert.condition) };
+        return { text: alert.metric?.kind === "ma_cross" ? `Cross ${alert.metric.direction}` : alert.metric?.kind === "rrg" ? "Enters" : conditionLabel(alert.condition) };
       case "quote":
         return {
           text: formatQuoteChecked(alert),
+          // A settled close exports as its session date.
+          ...(alert.metric && closeBasis(alert.metric) && alert.lastDailyClose && !alert.lastCheckError ? { value: alert.lastDailyClose } : {}),
           color: alert.lastCheckError ? colors.negative : colors.textDim,
         };
       case "triggered":
@@ -403,6 +439,8 @@ function PriceAlertsPane({ focused, width, height }: PaneProps) {
           text: alert.triggeredAt ? relativeTime(alert.triggeredAt) : "-",
           color: colors.textDim,
         };
+      case "created":
+        return { text: isoUtc(alert.createdAt).slice(0, 10), color: colors.textDim };
     }
   }, []);
 

package/src/plugins/builtin/alerts/quotes.ts

@@ -2,6 +2,7 @@ import type { DataProvider } from "../../../types/data-provider";
 import type { Quote } from "../../../types/financials";
 import { getActiveQuoteDisplay } from "../../../market-data/market/status";
 import { isQuoteStaleForCurrentSession } from "../../../market-data/quotes/freshness";
+import { canonicalExchange } from "../../../utils/exchanges";
 import type { AlertRule } from "./types";
 
 export function normalizeAlertSymbol(value: string | null | undefined): string {
@@ -46,13 +47,18 @@ export function quoteAlertFields(
   | "lastQuoteUpdatedAt"
   | "lastQuoteSource"
   | "lastQuoteProviderId"
+  | "lastQuoteCurrency"
+  | "lastQuoteExchange"
 > & { lastCheckError?: undefined } {
+  const exchange = quote.listingExchangeName || quote.exchangeName;
   return {
     lastCheckedPrice: quote.price,
     lastCheckedAt: checkedAt,
     lastQuoteUpdatedAt: quote.lastUpdated,
     lastQuoteSource: quote.dataSource,
     lastQuoteProviderId: quote.providerId,
+    ...(quote.currency ? { lastQuoteCurrency: quote.currency } : {}),
+    ...(exchange ? { lastQuoteExchange: canonicalExchange(exchange) } : {}),
     lastCheckError: undefined,
   };
 }

package/src/plugins/builtin/alerts/storage.ts

@@ -1,4 +1,4 @@
-import { METRIC_ALERTS_KEY } from "./metric-model";
+import { METRIC_ALERTS_KEY, RELATIVE_ALERTS_KEY, metricAlertsKey } from "./metric-model";
 import type { AppConfig } from "../../../types/config";
 import type { GloomPluginContext } from "../../../types/plugin";
 import {
@@ -21,8 +21,9 @@ export async function saveAlerts(
   scope: "all" | "price" | "metric" = "all",
 ): Promise<void> {
   const stores = readLevelAlertStores((key) => ctx.configState.get<unknown>(key));
-  const entries = Object.entries(writeLevelAlertStores(alerts)).filter(([key]) => scope === "all"
-    || key === (scope === "price" ? ALERTS_KEY : METRIC_ALERTS_KEY));
+  // An unreadable list is never written over; one that has nothing to write does not hold up the others.
+  const entries = Object.entries(writeLevelAlertStores(alerts)).filter(([key, value]) => (scope === "all"
+    || (scope === "price" ? key === ALERTS_KEY : key !== ALERTS_KEY)) && !(stores.errors[key] && value === "[]"));
   for (const [key] of entries) if (stores.errors[key]) throw new Error(stores.errors[key]!);
   for (const [key, value] of entries) {
     if (ctx.configState.get<unknown>(key) !== value) await ctx.configState.set(key, value);
@@ -46,17 +47,20 @@ export function readAlertStores(config: AppConfig) {
 export function readLevelAlertStores(get: (key: string) => unknown): { alerts: AlertRule[]; error: string | null; errors: Record<string, string | null> } {
   const alerts: AlertRule[] = [];
   const errors: Record<string, string | null> = {};
-  for (const key of [ALERTS_KEY, METRIC_ALERTS_KEY]) {
+  for (const key of LEVEL_ALERT_KEYS) {
     const raw = get(key);
     let error = readAlertsStoreError(raw);
     const rows = error ? [] : deserializeAlerts(raw);
-    if (rows.some(a => Boolean(a.metric) !== (key === METRIC_ALERTS_KEY))) error = "Saved alerts contain a rule in the wrong list. Original data has been kept.";
-    errors[key] = key === METRIC_ALERTS_KEY ? error?.replaceAll("price alerts", "valuation and technical alerts") ?? null : error;
+    if (rows.some(a => levelAlertStoreKey(a) !== key)) error = "Saved alerts contain a rule in the wrong list. Original data has been kept.";
+    errors[key] = key === METRIC_ALERTS_KEY ? error?.replaceAll("price alerts", "valuation and technical alerts") ?? null
+      : key === RELATIVE_ALERTS_KEY ? error?.replaceAll("price alerts", "relative strength alerts") ?? null : error;
     if (!error) alerts.push(...rows);
   }
   return { alerts, errors, error: Object.values(errors).filter(Boolean).join(" ") || null };
 }
 export function writeLevelAlertStores(alerts: AlertRule[]): Record<string, string> {
-  return { [ALERTS_KEY]: serializeAlerts(alerts.filter(a => !a.metric)),
-    [METRIC_ALERTS_KEY]: serializeAlerts(alerts.filter(a => a.metric)) };
+  return Object.fromEntries(LEVEL_ALERT_KEYS.map(key => [key, serializeAlerts(alerts.filter(a => levelAlertStoreKey(a) === key))]));
 }
+/** Price, valuation/technical and relative strength rules each keep their own synced list. */
+const LEVEL_ALERT_KEYS = [ALERTS_KEY, METRIC_ALERTS_KEY, RELATIVE_ALERTS_KEY] as const;
+export const levelAlertStoreKey = (alert: Pick<AlertRule, "metric">): string => alert.metric ? metricAlertsKey(alert.metric) : ALERTS_KEY;

package/src/plugins/builtin/alerts/types.ts

@@ -23,5 +23,9 @@ export interface AlertRule {
   lastQuoteUpdatedAt?: number;
   lastQuoteSource?: QuoteDataSource;
   lastQuoteProviderId?: string;
+  /** The currency of the quote the alert was last checked on (USD): its listing's, which lists show beside it. */
+  lastQuoteCurrency?: string;
+  /** The venue that quote was from (ARCA), which names the listing of a rule set by symbol alone. */
+  lastQuoteExchange?: string;
   message?: string;
 }

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

@@ -1,6 +1,7 @@
 import { usePaneSettingValue } from "../../../public/react";
 import { PortfolioRiskPane } from "./risk-pane";
 import { portfolioRiskHeadless } from "./risk-headless";
+import { NO_HOLDINGS_HINT } from "./risk-model";
 import { portfolioRiskCache } from "./risk-client";
 import { Box, Text } from "../../../ui";
 import { useCallback, useEffect, useMemo, useState } from "react";
@@ -398,7 +399,7 @@ function LegacyPortfolioAnalyticsPane({ focused, width, height }: PaneProps) {
                 message={accountsError ?? undefined}
                 hint={accountsError
                   ? "Reconnect the broker in the Brokers pane (BR), then refresh."
-                  : "Add holdings from the Portfolio pane (PF), or connect a broker in BR to sync them."}
+                  : NO_HOLDINGS_HINT}
               />
             </Box>
           ) : historyOnly ? (

package/src/plugins/builtin/analytics/risk-client.ts

@@ -58,7 +58,12 @@ interface RiskMarketHistory {
    * Set when the listing quotes in another currency and its closes were
    * restated in USD at same-date daily FX closes; quote and closeMark are then in USD.
    */
-  converted?: { currency: string; fxAsOf: string } | null;
+  converted?: {
+    currency: string;
+    fxAsOf: string;
+    /** US sessions converted at the FX close before them, the pair having none that day (bridgedFxClose). */
+    fxBridged?: string[];
+  } | null;
   error: string | null;
 }
 export interface RiskMarketSnapshot {
@@ -162,6 +167,8 @@ export function validateRiskHistory(
   closeMark: { price: number; date: string; currency: string } | null;
   /** Latest completed close in the returns' currency, whatever marks the holding. */
   latestClose: { price: number; date: string };
+  /** With a conversion, the US sessions converted at the FX close before them (bridgedFxClose). */
+  fxBridged?: string[];
 } {
   if (
     response.status !== "success" ||
@@ -244,13 +251,14 @@ export function validateRiskHistory(
   if (local.integrity)
     throw new Error("Daily history has inconsistent OHLC observations");
   // A converted series is on the NYSE calendar the basket and SPY share.
-  const series = conversion
+  const usd = conversion
     ? convertClosesToUsd(
         points.map((point) => ({ date: new Date(point.date).toISOString().slice(0, 10), close: point.close })),
         conversion.fx,
         conversion.divisor,
       )
-    : prices;
+    : null;
+  const series = usd ? usd.points : prices;
   const returns = conversion ? resolveDatedReturns(series).returns : local.returns;
   const cadence = qualifySharpeCadence(returns, [
     { symbol: instrument.symbol, exchange: conversion ? "NYSE" : exchange, history: series },
@@ -264,6 +272,7 @@ export function validateRiskHistory(
   };
   return {
     returns,
+    ...(usd?.bridged.length ? { fxBridged: usd.bridged } : {}),
     asOf: latestClose.date,
     // A missing or stale quote is not a current mark; the latest dated close is.
     closeMark:
@@ -591,7 +600,7 @@ export async function fetchPortfolioRiskMarket(
             historyParams,
             signal ? { signal } : undefined,
           );
-          const { latestClose, ...resolved } = validateRiskHistory(
+          const { latestClose, fxBridged, ...resolved } = validateRiskHistory(
             response,
             instrument,
             quote,
@@ -610,7 +619,9 @@ export async function fetchPortfolioRiskMarket(
               quote: current,
               currency: "USD",
               closeMark: current ? null : { ...latestClose, currency: "USD" },
-              converted: { currency: conversion.listingCurrency, fxAsOf: fxCloses.asOf },
+              converted: {
+                currency: conversion.listingCurrency, fxAsOf: fxCloses.asOf, ...(fxBridged?.length ? { fxBridged } : {}),
+              },
               error: null,
             };
             continue;

package/src/plugins/builtin/analytics/risk-fx.ts

@@ -38,10 +38,18 @@ export interface RiskConversion {
 export const FX_UNAVAILABLE = "Foreign holdings: daily FX closes unavailable";
 export const FX_NO_PAIR = "Foreign holdings: no daily FX pair for this currency";
 export const FX_STALE = "Foreign holdings: daily FX history is stale";
-export const FX_GAP = "Foreign holdings: daily FX history has gaps on the holding's dates";
+export const FX_GAP = "Foreign holdings: daily FX history has gaps longer than three days on the holding's dates";
 export const FX_DISAGREES = "Foreign holdings: daily FX closes disagree with the current rate";
 export const LOCAL_GAP = "Foreign holdings: local daily history has a gap longer than a market holiday";
 
+/**
+ * Most FX trading days in a row (weekdays) a pair may go without a daily
+ * close and still be bridged with the last close before them: Good Friday and
+ * Easter Monday, 25 December, 1 January, which the daily source skips while
+ * US sessions continue. A longer run is missing data and rejects the series.
+ */
+const MAX_BRIDGED_FX_DAYS = 3;
+
 /**
  * Longest run of calendar days a listing may go without a close while US
  * sessions continue (Golden Week, Lunar New Year, national holidays). A longer
@@ -70,6 +78,42 @@ export function accountFxReason(currency: string, problem: string): string {
   return `${pair} ${tail ?? "daily FX closes unavailable"}`;
 }
 
+/**
+ * The FX close a date converts at: the pair's own close that day, or the last
+ * close before it across at most MAX_BRIDGED_FX_DAYS weekdays without one
+ * (`bridged`). Null when the gap is longer, or no close comes before it.
+ */
+export function bridgedFxClose(rateOn: (date: string) => number | undefined, date: string): { rate: number; bridged: boolean } | null {
+  let missing = 0;
+  for (let time = Date.parse(`${date}T00:00:00Z`), step = 0; step <= 7 + MAX_BRIDGED_FX_DAYS; step++, time -= DAY_MS) {
+    const day = new Date(time).toISOString().slice(0, 10);
+    const rate = rateOn(day);
+    if (rate != null && rate > 0) return { rate, bridged: day !== date };
+    const weekday = new Date(time).getUTCDay();
+    if (weekday !== 0 && weekday !== 6 && ++missing > MAX_BRIDGED_FX_DAYS) return null;
+  }
+  return null;
+}
+
+/**
+ * "GBP/USD has no daily close on 2025-04-18 and 2025-04-21; the returns across
+ * them use the close before": what a conversion bridged (bridgedFxClose), said
+ * once per pair. Null when it bridged nothing.
+ */
+export function fxBridgeNote(pair: string, dates: Iterable<string>): string | null {
+  const days = [...new Set(dates)].sort();
+  if (!days.length) return null;
+  const shown = days.length > 4 ? [...days.slice(0, 3), `${days.length - 3} more days`] : days;
+  const list = shown.length === 1 ? shown[0]! : `${shown.slice(0, -1).join(", ")} and ${shown.at(-1)!}`;
+  return `${pair} has no daily close on ${list}; the returns across ${days.length === 1 ? "it use the close before it" : "them use the close before each"}.`;
+}
+
+/** Account returns, and the dates whose FX close was the last one before them (bridgedFxClose). */
+export interface AccountReturns {
+  returns: DatedReturn[];
+  bridged: string[];
+}
+
 /**
  * Restates daily USD returns in the account currency at the FX closes of each
  * return's own start and end dates: the holding's USD value is divided by the
@@ -77,23 +121,29 @@ export function accountFxReason(currency: string, problem: string): string {
  * (1 + r) * fx(start) / fx(end) - 1. A listing already converted from its own
  * currency to USD therefore converts at the cross of the two closes of the
  * same date. Returns before the first FX close or after the last are dropped,
- * so the series starts and ends with the FX history; a return inside it with an
- * endpoint that has no FX close rejects the whole series instead of bridging it.
+ * so the series starts and ends with the FX history. An endpoint without an FX
+ * close converts at the last close before it across a gap of up to
+ * MAX_BRIDGED_FX_DAYS FX trading days (Good Friday and Easter Monday), and
+ * says so in `bridged`; a longer gap rejects the whole series.
  */
 export function convertReturnsToAccount(
   returns: readonly DatedReturn[],
   fx: Pick<AccountFx, "currency" | "closes" | "first" | "asOf">,
-): DatedReturn[] {
+): AccountReturns {
   if (!fx.first || !fx.asOf) throw new Error(accountFxReason(fx.currency, FX_UNAVAILABLE));
   const converted: DatedReturn[] = [];
+  const bridged = new Set<string>();
+  const rateOn = (date: string) => fx.closes[date];
   for (const point of returns) {
     if (point.startDateKey < fx.first || point.dateKey > fx.asOf) continue;
-    const start = fx.closes[point.startDateKey],
-      end = fx.closes[point.dateKey];
-    if (!(start! > 0) || !(end! > 0)) throw new Error(accountFxReason(fx.currency, FX_GAP));
-    converted.push({ ...point, value: (1 + point.value) * (start! / end!) - 1 });
+    const start = bridgedFxClose(rateOn, point.startDateKey),
+      end = bridgedFxClose(rateOn, point.dateKey);
+    if (!start || !end) throw new Error(accountFxReason(fx.currency, FX_GAP));
+    if (start.bridged) bridged.add(point.startDateKey);
+    if (end.bridged) bridged.add(point.dateKey);
+    converted.push({ ...point, value: (1 + point.value) * (start.rate / end.rate) - 1 });
   }
-  return converted;
+  return { returns: converted, bridged: [...bridged].sort() };
 }
 
 /** The pair that restates a listing currency in USD, or null when there is none. */
@@ -127,7 +177,9 @@ export function validateFxHistory(
  * On a US session the listing did not trade (its own holiday), the holding is
  * worth its last local close at that day's FX close: its USD value moves with
  * the currency alone, as it would in the account. A US session with no FX
- * close, or a local silence longer than any market holiday, rejects the whole
+ * close converts at the last close before it across a gap of up to
+ * MAX_BRIDGED_FX_DAYS FX trading days, listed in `bridged`; a longer FX gap,
+ * or a local silence longer than any market holiday, rejects the whole
  * series instead of bridging it. The series ends at the earlier of the last
  * local close and the last FX close, so no close is carried past the data.
  */
@@ -135,7 +187,7 @@ export function convertClosesToUsd(
   local: readonly { date: string; close: number }[],
   fx: FxCloses,
   divisor: number,
-): PricePoint[] {
+): { points: PricePoint[]; bridged: string[] } {
   const points = [...local]
     .map((point) => ({ date: point.date.slice(0, 10), close: point.close }))
     .sort((left, right) => left.date.localeCompare(right.date));
@@ -143,6 +195,8 @@ export function convertClosesToUsd(
   const start = points[0]!.date > fx.first ? points[0]!.date : fx.first;
   const end = points.at(-1)!.date < fx.asOf ? points.at(-1)!.date : fx.asOf;
   const converted: PricePoint[] = [];
+  const bridged: string[] = [];
+  const rateOn = (date: string) => fx.closes.get(date);
   let cursor = 0;
   for (let time = Date.parse(`${start}T00:00:00Z`); time <= Date.parse(`${end}T00:00:00Z`); time += DAY_MS) {
     const date = new Date(time).toISOString().slice(0, 10);
@@ -153,11 +207,12 @@ export function convertClosesToUsd(
     const last = points[cursor]!;
     if (last.date > date) continue;
     if (time - Date.parse(`${last.date}T00:00:00Z`) > MAX_LOCAL_CLOSED_DAYS * DAY_MS) throw new Error(LOCAL_GAP);
-    const rate = fx.closes.get(date);
-    if (rate == null) throw new Error(FX_GAP);
-    const close = (last.close * rate) / divisor;
+    const fxClose = bridgedFxClose(rateOn, date);
+    if (!fxClose) throw new Error(FX_GAP);
+    if (fxClose.bridged) bridged.push(date);
+    const close = (last.close * fxClose.rate) / divisor;
     converted.push({ date: new Date(time), open: close, high: close, low: close, close });
   }
   if (converted.length < 2) throw new Error("Daily history unavailable");
-  return converted;
+  return { points: converted, bridged };
 }

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

@@ -3,6 +3,7 @@ import type { HeadlessPaneDefinition } from "../../../types/plugin";
 import { fetchPortfolioRiskMarket, RISK_HISTORY_LIMIT } from "./risk-client";
 import { parsePortfolioRiskEvidence } from "./risk-evidence";
 import { describeCollections } from "../../../portfolio/collection-name";
+import { shellWord } from "../../../utils/shell-word";
 import { formatShocks, parseAssetShifts, parseFxShifts, riskCashLines } from "./risk-book";
 import {
   BASKET_VIEWS,
@@ -48,6 +49,22 @@ function reportPortfolioName(metadata: Record<string, unknown> | undefined): str
   return typeof name === "string" ? name : undefined;
 }
 
+/**
+ * What a portfolio with nothing to estimate says, as one line: the commands
+ * that fill it. Risk is read from lots, so a symbol listed without shares
+ * (`portfolio add`) is no holding yet; `portfolio position set` gives it
+ * shares, and adds the symbol too when it is not listed.
+ */
+function emptyPortfolioHint(name: string, listed: readonly string[]): string {
+  const portfolio = shellWord(name);
+  if (listed.length > 0) {
+    return `${name} lists ${listed.slice(0, 3).join(", ")}${listed.length > 3 ? ` and ${listed.length - 3} more` : ""} but holds no shares: `
+      + `gloom portfolio position set ${portfolio} ${shellWord(listed[0]!)} 10 150.`;
+  }
+  return `No holdings in ${name}. Add symbols with gloom portfolio add ${portfolio} AAPL,MSFT, `
+    + `then their shares with gloom portfolio position set ${portfolio} AAPL 10 150.`;
+}
+
 /** Rows of one view in the compact result; the pane and reports keep every row. */
 const COMPACT_ROW_LIMIT = 100;
 /** The correlation view is every pair of holdings; the compact result keeps the strongest. */
@@ -260,6 +277,16 @@ export const portfolioRiskHeadless: HeadlessPaneDefinition<"bundle"> = {
       throw new Error(
         "Imported evidence belongs to a different portfolio or currency",
       );
+    // A portfolio with no holdings and no cash has nothing to estimate: say how to fill it, not a table of dashes.
+    if (tickers.length === 0 && cash.length === 0 && !evidence) {
+      const listed = local.tickers.filter((ticker) => ticker.metadata.portfolios.includes(id)).map((ticker) => ticker.metadata.ticker);
+      return {
+        sections: [],
+        complete: false,
+        empty: emptyPortfolioHint(local.portfolio.name, listed),
+        metadata: { portfolio: { id, name: local.portfolio.name, currency: local.portfolio.currency } },
+      };
+    }
     const requestedView = isRiskView(args.options.view) ? args.options.view : null;
     const view: string = requestedView ?? "risk";
     const localOnly =