gloomberb 0.18.2 → 0.18.4

package/src/plugins/builtin/portfolio-list/cli/render.ts

@@ -30,6 +30,8 @@ import {
   type PortfolioFuturesTerms,
 } from "../../../../portfolio/futures-positions";
 import { dailyFuturesHistory, loadPortfolioFuturesTerms, type PortfolioFuturesSources } from "../../../../portfolio/futures-terms";
+import { loadPurchaseDateCostFx, withPurchaseDateCostFx, type CostFxHistoryClient, type PurchaseDateCostFx } from "../../../../portfolio/cost-fx";
+import { apiClient } from "../../../../api-client";
 import { formatUtcDayTime, parseReportTime } from "../../../../utils/utc-time";
 import { quoteFreshnessFields } from "../../shared/report-freshness";
 import { resolvePortfolioTotalsCurrency } from "../summary/totals";
@@ -85,7 +87,7 @@ import { importedFromText } from "../imported-from";
 import { findNamedCollection } from "../../../../portfolio/collection-name";
 import { isoDateToday } from "../../../../utils/calendar-date";
 import { lastTradeDate } from "../../../../tickers/listing-fate";
-import { DIVIDEND_READ_DEADLINE_MS, incomeGapNote, loadHoldingDividends, portfolioIncome, projectDrip, type DripYear, type HoldingDividend } from "../income";
+import { DIVIDEND_READ_DEADLINE_MS, incomeGapNote, loadHoldingDividends, portfolioIncome, projectDrip, showsIncomeColumns, type DripYear, type HoldingDividend } from "../income";
 
 /** Money prices pad to the currency's minor unit ($337.90, not $337.9), as the ticker view does. */
 function priceFormatOptions(quote: Parameters<typeof quoteFormatOptions>[0] & { currency?: string }, assetCategory?: string) {
@@ -202,6 +204,8 @@ export interface ShowCollectionOptions {
   dividendDeadlineMs?: number;
   /** Where futures' terms and settlements are read; Gloom Cloud's terms and the data provider's daily bars by default. */
   futuresSources?: PortfolioFuturesSources;
+  /** Where the FX closes of the lots' purchase dates are read; Gloom Cloud by default. */
+  costFxHistory?: CostFxHistoryClient;
 }
 
 export async function showCollection(name: string, ctx: CliCommandContext, options: ShowCollectionOptions = {}) {
@@ -317,8 +321,14 @@ export interface PortfolioValuation {
   unknownContractSize: Set<string>;
   /** Futures valued at the close without a confirmed settlement to value them at. */
   unsettled: Set<string>;
-  /** Holdings in another currency whose cost converts at today's rate: no purchase date or cost FX rate was entered. */
+  /**
+   * Holdings in another currency whose cost converts at today's rate: no
+   * purchase date or cost FX rate was entered (`costFxUndated`), or the
+   * date's FX close could not be read (`costFxUnread`).
+   */
   costAtTodaysRate: Set<string>;
+  costFxUndated: Set<string>;
+  costFxUnread: Set<string>;
   /** Long and short market value of the priced lots, and their net and gross, in the portfolio's currency. */
   exposure: PortfolioExposure;
 }
@@ -346,10 +356,16 @@ function portfolioExposure(values: Iterable<number | null | undefined>): Portfol
 /**
  * What a book says of holdings in another currency whose cost converts at
  * today's rate, which leaves the currency's move since purchase out of their
- * P&L; `named` lists them as the table names its rows.
+ * P&L: those with no purchase date or rate, and those whose date's FX close
+ * could not be read. `named` lists them as the table names its rows.
  */
-export function costAtTodaysRateNote(named: string): string {
-  return `Cost converted at today's rate for ${named}; give portfolio position set a --date or --cost-fx to use the rate when bought.`;
+export function costAtTodaysRateNotes(valuation: Pick<PortfolioValuation, "costFxUndated" | "costFxUnread">,
+  named: (symbols: Iterable<string>) => string): string[] {
+  const undated = valuation.costFxUndated;
+  return [
+    ...undated.size ? [`Cost converted at today's rate for ${named(undated)}; give portfolio position set a --date or --cost-fx to use the rate when bought.`] : [],
+    ...valuation.costFxUnread.size ? [`Cost converted at today's rate for ${named(valuation.costFxUnread)}: the FX close of the purchase date could not be read.`] : [],
+  ];
 }
 
 /**
@@ -368,6 +384,7 @@ export async function valuePortfolioPositions({
   toBase,
   basis = "latest-print",
   futures,
+  purchaseDateFx,
 }: {
   tickers: readonly TickerRecord[];
   quotes: ReadonlyMap<string, CollectionQuote>;
@@ -378,6 +395,11 @@ export async function valuePortfolioPositions({
   basis?: PortfolioValuationBasis;
   /** Each future's contract size and settlement (loadPortfolioFuturesTerms), by symbol. */
   futures?: ReadonlyMap<string, PortfolioFuturesTerms>;
+  /**
+   * The FX closes of the lots' purchase dates in `currency` (loadPurchaseDateCostFx): a dated lot with no rate of
+   * its own into `currency` converts its cost at its date's close, and at today's rate when that could not be read.
+   */
+  purchaseDateFx?: PurchaseDateCostFx;
 }): Promise<PortfolioValuation> {
   const id = portfolioId;
   let totalPnl = 0;
@@ -388,11 +410,13 @@ export async function valuePortfolioPositions({
   const unknownContractSize = new Set<string>();
   const unsettled = new Set<string>();
   const costAtTodaysRate = new Set<string>();
+  const costFxUndated = new Set<string>();
+  const costFxUnread = new Set<string>();
   const values: PortfolioPositionValue[] = [];
   const holdings: AllocationHolding[] = [];
   const known = (value: number | null | undefined): number | null => value != null && Number.isFinite(value) ? value : null;
 
-  for (const ticker of tickers) {
+  for (const ticker of purchaseDateFx ? withPurchaseDateCostFx(tickers, purchaseDateFx, currency, id) : tickers) {
     const quote = quotes.get(ticker.metadata.ticker);
     const futuresTerms = isFuturesTicker(ticker) ? futures?.get(ticker.metadata.ticker) ?? { size: null, settlement: null } : null;
     // A lot entered without its contract size takes the one the terms state; the entries keep the saved record.
@@ -430,7 +454,7 @@ export async function valuePortfolioPositions({
       const atSettlement = valuesAtSettlement(metrics, basis);
       const positionCurrency = metrics.positionCurrency;
       const positionRate = positionCurrency ? await toBase(1, positionCurrency) : Number.NaN;
-      // The cost converts at the rate the lot was bought at when one was entered, else at today's, as its value does.
+      // The cost converts at the rate the lot was bought at, entered or its purchase date's close, else at today's, as its value does.
       const baseMetrics = getPortfolioPositionMetrics({ ...ticker, metadata: { ...ticker.metadata, positions: [position] } }, id, quoteCurrency,
         { currency, convert: value => value * positionRate }, quote);
       const boughtRate = positionCurrency ? lotCostFxRate(position, positionCurrency, currency) : null;
@@ -438,7 +462,10 @@ export async function valuePortfolioPositions({
         : boughtRate !== null ? baseMetrics.totalCost : await toBase(metrics.totalCost, positionCurrency);
       // Only a lot entered by hand can be given the rate it was bought at; a broker's lot reads as it always has.
       const atTodaysRate = position.broker === "manual" && !!positionCurrency && lotCostAtTodaysRate(position, positionCurrency, currency);
-      if (atTodaysRate && metrics.hasCostBasis) costAtTodaysRate.add(ticker.metadata.ticker);
+      if (atTodaysRate && metrics.hasCostBasis) {
+        costAtTodaysRate.add(ticker.metadata.ticker);
+        (purchaseDateFx && position.dateAcquired ? costFxUnread : costFxUndated).add(ticker.metadata.ticker);
+      }
       const costFx = boughtRate !== null ? { rate: boughtRate, currency } : atTodaysRate ? null : undefined;
       const currentValueBase = resolvePortfolioMarketValue(baseMetrics,
         valuationQuote ? await toBase(valuationQuote.price, quoteCurrency) : null)?.gross ?? null;
@@ -481,7 +508,7 @@ export async function valuePortfolioPositions({
 
   const exposure = portfolioExposure(values.map((entry) => entry.position ? entry.row.marketValue as number | null : null));
   return { basis, positions: values, holdings, totalPnl, unavailablePnl, unavailableCost, unavailableMarketValue, brokerPnlSymbols,
-    unknownContractSize, unsettled, costAtTodaysRate, exposure };
+    unknownContractSize, unsettled, costAtTodaysRate, costFxUndated, costFxUnread, exposure };
 }
 
 /**
@@ -686,7 +713,7 @@ async function showCollectionWithMarketData(
   name: string,
   ctx: CliCommandContext,
   { config, store, dataProvider, persistence }: MarketContext,
-  { explain = false, basis = "latest-print", drip, dividendDeadlineMs = DIVIDEND_READ_DEADLINE_MS, futuresSources }: ShowCollectionOptions,
+  { explain = false, basis = "latest-print", drip, dividendDeadlineMs = DIVIDEND_READ_DEADLINE_MS, futuresSources, costFxHistory = apiClient }: ShowCollectionOptions,
 ) {
   const tickers = (await store.loadAllTickers()).sort((left, right) =>
     left.metadata.ticker.localeCompare(right.metadata.ticker)
@@ -702,10 +729,10 @@ async function showCollectionWithMarketData(
 
   const matchedPortfolio = collection.kind === "portfolio" ? collection.portfolio : undefined;
   if (!matchedPortfolio && basis === "regular-close") {
-    ctx.fail(`--close values a portfolio; "${collection.name}" is a watchlist.`, "Usage: gloomberb portfolio show <portfolio> --close");
+    ctx.fail(`--close values a portfolio; "${collection.name}" is a watchlist.`, "Usage: gloom portfolio show <portfolio> --close");
   }
   if (!matchedPortfolio && drip) {
-    ctx.fail(`--drip projects a portfolio's dividends; "${collection.name}" is a watchlist.`, "Usage: gloomberb portfolio show <portfolio> --drip");
+    ctx.fail(`--drip projects a portfolio's dividends; "${collection.name}" is a watchlist.`, "Usage: gloom portfolio show <portfolio> --drip");
   }
   const isPortfolio = !!matchedPortfolio;
   const id = collection.id;
@@ -731,12 +758,13 @@ async function showCollectionWithMarketData(
 
   const futuresHeld = filtered.filter((ticker) => isFuturesTicker(ticker)
     && ticker.metadata.positions.some((position) => position.portfolio === id && position.shares !== 0));
-  const [quotes, futures] = await Promise.all([
+  const [quotes, futures, purchaseDateFx] = await Promise.all([
     loadCollectionQuotes(filtered, collection, dataProvider),
     isPortfolio ? loadPortfolioFuturesTerms(futuresHeld, {
       settlement: basis === "regular-close",
       sources: { history: dailyFuturesHistory(dataProvider), ...futuresSources },
     }) : undefined,
+    isPortfolio ? loadPurchaseDateCostFx(filtered, { into: currency, history: costFxHistory, portfolioId: id }) : undefined,
   ]);
   // Worst of across the holdings' quotes, as the PORT and watchlist reports state it.
   const broker = !!(matchedPortfolio?.brokerId || matchedPortfolio?.brokerInstanceId);
@@ -756,7 +784,7 @@ async function showCollectionWithMarketData(
   }
 
   if (matchedPortfolio) {
-    const valuation = await valuePortfolioPositions({ tickers: filtered, quotes, portfolioId: id, currency, baseCurrency: config.baseCurrency, toBase, basis, futures });
+    const valuation = await valuePortfolioPositions({ tickers: filtered, quotes, portfolioId: id, currency, baseCurrency: config.baseCurrency, toBase, basis, futures, purchaseDateFx });
     // Exports carry no header line, so their source line names the basis.
     freshness = portfolioValuationFreshness(valuation, source, { note: structured });
     const {
@@ -774,7 +802,8 @@ async function showCollectionWithMarketData(
     const { allocation, cash } = await valuePortfolioAllocation({ valuation, portfolio: matchedPortfolio, account, toBase });
     const allocationBySymbol = new Map(allocation.rows.map((row) => [row.symbol, row]));
     // What each holding pays a year: trailing dividends per share times its shares, in the portfolio's currency.
-    const held = filtered.filter((ticker) => valued.some((entry) => entry.ticker === ticker && entry.position));
+    // By symbol: a lot whose cost converts at its purchase date's FX close is valued on a copy of its record.
+    const held = filtered.filter((ticker) => valued.some((entry) => entry.ticker.metadata.ticker === ticker.metadata.ticker && entry.position));
     const { dividends } = await loadHoldingDividends(held, quotes, dataProvider, { deadlineMs: dividendDeadlineMs });
     // Lots without a position or shares are no lot of income; a row of their own keeps its place with none.
     const income = await portfolioIncome(valued.map((entry) => ({
@@ -853,7 +882,7 @@ async function showCollectionWithMarketData(
         const symbol = ticker.metadata.ticker;
         const dividend = dividends.get(symbol);
         if (!dividend) continue;
-        const shares = valued.filter((entry) => entry.ticker === ticker && entry.position && entry.metrics)
+        const shares = valued.filter((entry) => entry.ticker.metadata.ticker === symbol && entry.position && entry.metrics)
           .reduce((sum, entry) => sum + entry.metrics!.totalShares, 0);
         if (shares === 0) continue;
         // Income the table could not show is not projected either; the note under it says why.
@@ -930,7 +959,7 @@ async function showCollectionWithMarketData(
         exposure,
         ...(unknownContractSize.size > 0 ? { unknownContractSizeSymbols: [...unknownContractSize] } : {}),
         ...(unsettled.size > 0 ? { unsettledSymbols: [...unsettled] } : {}),
-        // Holdings in another currency with no purchase date or cost FX rate: their cost converts at today's rate.
+        // Holdings in another currency whose cost converts at today's rate: no purchase date or cost FX rate, or the date's close was not read.
         ...(costAtTodaysRate.size > 0 ? { costAtTodaysRateSymbols: [...costAtTodaysRate] } : {}),
         accountingBasis, ...(manualAccounting ? { manualAccounting } : {}),
         ...(matchedPortfolio.importedFrom ? { importedFrom: matchedPortfolio.importedFrom } : {}),
@@ -959,8 +988,8 @@ async function showCollectionWithMarketData(
       return [weight, target, drift, trade, tradeValue];
     };
 
-    // Income and its yield, once any share or fund has one; with none known, the note under the table says why.
-    const showIncome = income.knownHoldings > 0;
+    // Income and its yield, once any share or fund has one or only lacks a rate into the portfolio's currency; otherwise the note under the table says why.
+    const showIncome = showsIncomeColumns(income);
     const incomeCells = (income: number | null | undefined, yieldPercent: number | null | undefined): string[] =>
       showIncome ? [money(income), formatIncomeYield(yieldPercent)] : [];
     const extendedSessions = extendedSessionsOf(valued.map(({ extended }) => extended?.session));
@@ -1086,7 +1115,7 @@ async function showCollectionWithMarketData(
     const targetNote = describeTargetSum(allocation.targetSum, allocation.weightBasis);
     if (targetNote) notes.push(cliStyles.muted(targetNote));
     if (brokerPnlSymbols.size > 0) notes.push(cliStyles.muted(`P&L for ${named(brokerPnlSymbols)} is the broker's last snapshot.`));
-    if (costAtTodaysRate.size > 0) notes.push(cliStyles.muted(costAtTodaysRateNote(named(costAtTodaysRate))));
+    notes.push(...costAtTodaysRateNotes(valuation, named).map((note) => cliStyles.muted(note)));
     if (unknownContractSize.size > 0) {
       notes.push(cliStyles.warning(`No contract size for ${named(unknownContractSize)}, so ${unknownContractSize.size === 1 ? "its" : "their"} value, cost and P&L are not shown.`));
     }

package/src/plugins/builtin/portfolio-list/cli/shared.ts

@@ -91,9 +91,9 @@ export function misplacedSymbolList(
   const more = collections.length - names.length;
   const existing = names.length > 0
     ? `${label}: ${names.join(", ")}${more > 0 ? ` and ${more} more` : ""}`
-    : `no ${label} yet, create one with \`gloomberb ${noun} create <name>\``;
+    : `no ${label} yet, create one with \`gloom ${noun} create <name>\``;
   return {
-    message: `"${preview}" reads as a list of symbols, not a ${noun} name; did you mean \`gloomberb ${noun} ${verb} <name> <list>\`; ${existing}`,
+    message: `"${preview}" reads as a list of symbols, not a ${noun} name; did you mean \`gloom ${noun} ${verb} <name> <list>\`; ${existing}`,
     details: usage,
   };
 }
@@ -146,6 +146,6 @@ export function rejectCashSymbol(symbol: string, exchange: string | undefined, p
   if (!isCashArgument(symbol, exchange)) return;
   throw new PortfolioCliError(
     "CASH is the portfolio's cash line, not a ticker.",
-    `Record cash with: gloomberb portfolio cash set "${portfolioName}" <amount> [currency]. For the stock that trades as CASH, name its exchange: CASH:NASDAQ.`,
+    `Record cash with: gloom portfolio cash set "${portfolioName}" <amount> [currency]. For the stock that trades as CASH, name its exchange: CASH:NASDAQ.`,
   );
 }

package/src/plugins/builtin/portfolio-list/cli/watchlist-command.ts

@@ -1,9 +1,10 @@
 import { saveConfig } from "../../../../data/config/store";
-import { withConfigData, withMarketData } from "../../../../cli/scoped-context";
+import { withConfigData } from "../../../../cli/scoped-context";
+import { withCollectionConfigData, withCollectionMarketData } from "../../../../cli/suffixed-listing-rows";
 import { countCollectionTickers, findWatchlist } from "../../../../cli/helpers";
 import { slugifyName } from "../../../../utils/slugify";
 import { takeOption } from "../../../../cli/commands/command-utils";
-import { EXCHANGE_OPTION, loadSavedListing, requireListingArg, savedListingName } from "../../../../cli/listing-arg";
+import { EXCHANGE_OPTION, requireSavedListing, savedListingName } from "../../../../cli/listing-arg";
 import {
   cliStyles,
   renderSection,
@@ -21,14 +22,12 @@ import {
 } from "../../../../portfolio/mutations";
 import { showCollection } from "./render";
 import { listingFields, misplacedSymbolList, refuseDryRun, takeCollectionName } from "./shared";
-import { addOneSymbol, addSymbols, FILE_OPTION, printSymbolRows, removeSymbols, requireSymbolList, retryNotice, SYMBOL_LIST_HELP } from "./bulk-symbols";
+import { addOneSymbol, addSymbols, FILE_OPTION, printSymbolRows, removeSymbols, requireSymbolList, retryNotice, shellWord, SYMBOL_LIST_HELP } from "./bulk-symbols";
 import { readNameEntries } from "../../../../cli/name-entries";
 import { CLI_COMMAND_GROUPS } from "../../../../cli/help";
 
-const ADD_USAGE = "Usage: gloomberb watchlist add <watchlist> <symbols...> [--file <path>]";
-const REMOVE_USAGE = "Usage: gloomberb watchlist remove <watchlist> <symbols...> [--file <path>]";
-/** A collection's name as a command argument: quoted when it has spaces. */
-const quotedName = (name: string) => /\s/.test(name) ? `"${name}"` : name;
+const ADD_USAGE = "Usage: gloom watchlist add <watchlist> <symbols...> [--file <path>]";
+const REMOVE_USAGE = "Usage: gloom watchlist remove <watchlist> <symbols...> [--file <path>]";
 
 /** Actions that change a watchlist without a preview, so --dry-run would change it anyway. add previews. */
 const MUTATING_ACTIONS = new Set(["create", "delete", "rm", "remove"]);
@@ -59,7 +58,7 @@ function requireWatchlistArgs(
 async function createWatchlist(name: string, ctx: CliCommandContext) {
   await withConfigData(ctx, async ({ config }) => {
     const trimmedName = name.trim();
-    if (!trimmedName) ctx.fail("Usage: gloomberb watchlist create <name>");
+    if (!trimmedName) ctx.fail("Usage: gloom watchlist create <name>");
 
     const id = slugifyName(trimmedName, "watchlist");
     const duplicate = config.watchlists.some((watchlist) =>
@@ -78,7 +77,7 @@ async function createWatchlist(name: string, ctx: CliCommandContext) {
 }
 
 async function deleteWatchlist(name: string, ctx: CliCommandContext) {
-  await withConfigData(ctx, async ({ config, store }) => {
+  await withCollectionConfigData(ctx, async ({ config, store }) => {
     const watchlist = findWatchlist(config, name);
     if (!watchlist) ctx.fail(`Watchlist "${name}" was not found.`);
 
@@ -93,26 +92,29 @@ async function deleteWatchlist(name: string, ctx: CliCommandContext) {
   });
 }
 
-async function addTickerToWatchlistCommand(watchlist: Watchlist, symbol: string, exchange: string | undefined, ctx: CliCommandContext, market: MarketContext) {
+async function addTickerToWatchlistCommand(
+  watchlist: Watchlist, symbol: string, notes: readonly string[], exchange: string | undefined, ctx: CliCommandContext, market: MarketContext,
+) {
   // A bare symbol is stored on the listing `quote` reads it as, and the notes say which; a match a list would leave for a choice fails.
   await addOneSymbol(ctx, market, {
     symbol,
     exchange,
     collection: { kind: "watchlist", name: watchlist.name },
-    retry: (key) => `gloomberb watchlist add ${quotedName(watchlist.name)} ${key}`,
+    notes,
+    retry: (key) => `gloom watchlist add ${shellWord(watchlist.name)} ${key}`,
     add: (ticker) => addTickerToWatchlist(ticker, watchlist.id),
   });
 }
 
 async function addToWatchlistCommand(args: string[], file: string | undefined, exchange: string | undefined, ctx: CliCommandContext) {
-  await withMarketData(ctx, async (market) => {
+  await withCollectionMarketData(ctx, async (market) => {
     const { watchlist, rest } = requireWatchlistArgs(market.config, args, file, "add", ADD_USAGE, ctx);
     const list = await requireSymbolList(ctx, rest, file, ADD_USAGE, (entries) => readNameEntries(entries, market.dataProvider));
     if (list.single) {
-      await addTickerToWatchlistCommand(watchlist, list.single, exchange, ctx, market);
+      await addTickerToWatchlistCommand(watchlist, list.single, list.notes, exchange, ctx, market);
       return;
     }
-    const retry = (key: string) => `gloomberb watchlist add ${quotedName(watchlist.name)} ${key}`;
+    const retry = (key: string) => `gloom watchlist add ${shellWord(watchlist.name)} ${key}`;
     const dryRun = ctx.cliOptions.dryRun;
     const rows = await addSymbols({
       symbols: list.symbols,
@@ -129,33 +131,36 @@ async function addToWatchlistCommand(args: string[], file: string | undefined, e
   });
 }
 
-async function removeTickerFromWatchlist(watchlist: Watchlist, symbol: string, exchange: string | undefined, ctx: CliCommandContext, { store }: ConfigContext) {
+async function removeTickerFromWatchlist(
+  watchlist: Watchlist, symbol: string, notes: readonly string[], exchange: string | undefined, ctx: CliCommandContext, { store }: ConfigContext,
+) {
   // SAN:EPA and SAN --exchange EPA name the stored listing, which a bare SAN may hold under another venue.
-  const listing = await requireListingArg(symbol, exchange, ctx);
-  const ticker = await loadSavedListing(store, listing);
+  // GARAN.IS is the row of GARAN:BIST, else a row still saved under that key (a broker's).
+  const { listing, ticker } = await requireSavedListing(symbol, exchange, ctx, store, (row) => row.metadata.watchlists.includes(watchlist.id));
   if (!ticker) ctx.fail(`Ticker "${listing.key}" was not found in your local data.`);
   const saved = savedListingName(ticker);
   const result = removeWatchlistMembership(ticker, watchlist.id);
   if (!result.changed) ctx.fail(`${saved.key} is not in "${watchlist.name}".`);
 
   await store.saveTicker(result.ticker);
-  ctx.printResult({ data: { changed: true, ...listingFields(saved), watchlist: watchlist.name } }, {
+  ctx.printResult({ data: { changed: true, ...listingFields(saved), watchlist: watchlist.name }, ...notes.length > 0 ? { warnings: [...notes] } : {} }, {
     text: () => cliStyles.success(`Removed ${saved.label} from "${watchlist.name}".`),
   });
 }
 
 async function removeFromWatchlistCommand(args: string[], file: string | undefined, exchange: string | undefined, ctx: CliCommandContext) {
-  await withConfigData(ctx, async (context) => {
+  await withCollectionConfigData(ctx, async (context) => {
     const { watchlist, rest } = requireWatchlistArgs(context.config, args, file, "remove", REMOVE_USAGE, ctx);
     const list = await requireSymbolList(ctx, rest, file, REMOVE_USAGE);
     if (list.single) {
-      await removeTickerFromWatchlist(watchlist, list.single, exchange, ctx, context);
+      await removeTickerFromWatchlist(watchlist, list.single, list.notes, exchange, ctx, context);
       return;
     }
     const rows = await removeSymbols({
       symbols: list.symbols,
       exchange,
       store: context.store,
+      holds: (ticker) => ticker.metadata.watchlists.includes(watchlist.id),
       remove: (ticker) => removeWatchlistMembership(ticker, watchlist.id),
     });
     printSymbolRows(ctx, rows, { verb: "remove", collection: { kind: "watchlist", name: watchlist.name }, repeated: list.repeated, notes: list.notes });
@@ -247,21 +252,21 @@ export const watchlistCliCommand: CliCommandDef = {
 
     if (action === "show") {
       const name = args.slice(1).join(" ");
-      if (!name) ctx.fail("Usage: gloomberb watchlist show <name>");
+      if (!name) ctx.fail("Usage: gloom watchlist show <name>");
       await showCollection(name, ctx);
       return;
     }
 
     if (action === "create") {
       const name = args.slice(1).join(" ");
-      if (!name) ctx.fail("Usage: gloomberb watchlist create <name>");
+      if (!name) ctx.fail("Usage: gloom watchlist create <name>");
       await createWatchlist(name, ctx);
       return;
     }
 
     if (action === "delete" || action === "rm") {
       const name = args.slice(1).join(" ");
-      if (!name) ctx.fail("Usage: gloomberb watchlist delete <name>");
+      if (!name) ctx.fail("Usage: gloom watchlist delete <name>");
       await deleteWatchlist(name, ctx);
       return;
     }
@@ -282,7 +287,7 @@ export const watchlistCliCommand: CliCommandDef = {
       const path = /\.\w+$/.test(rest.at(-1) ?? "") ? rest.at(-1)! : null;
       const name = (path ? rest.slice(0, -1) : rest).join(" ") || "<watchlist>";
       ctx.fail(
-        `watchlist has no import. To add the symbols in ${path ?? "a file"}, run: gloomberb watchlist add ${/\s/.test(name) ? `"${name}"` : name} --file ${path ?? "<path>"}`,
+        `watchlist has no import. To add the symbols in ${path ?? "a file"}, run: gloom watchlist add ${/\s/.test(name) ? `"${name}"` : name} --file ${path ?? "<path>"}`,
         ADD_USAGE,
       );
     }

package/src/plugins/builtin/portfolio-list/headless.ts

@@ -24,13 +24,14 @@ import {
   valuationTimeText,
   valuePortfolioAllocation,
   valuePortfolioPositions,
-  costAtTodaysRateNote,
+  costAtTodaysRateNotes,
   type CollectionMatch,
   type PortfolioValuation,
 } from "./cli/render";
 import { valuationBasisLabel, type PortfolioValuationBasis } from "../../../portfolio/valuation-basis";
 import { futuresQuantityText, isFuturesTicker } from "../../../portfolio/futures-positions";
 import { dailyFuturesHistory, loadPortfolioFuturesTerms } from "../../../portfolio/futures-terms";
+import { loadPurchaseDateCostFx } from "../../../portfolio/cost-fx";
 import { EXTENDED_SESSION_LABELS, quoteHeadlineTime, type ExtendedSession } from "../../../market-data/market/status";
 import {
   BROKER_ACCOUNT_MISSING_NOTE,
@@ -289,12 +290,13 @@ async function portfolioHoldings(
   const currency = resolvePortfolioTotalsCurrency(target.portfolio, ctx.config.baseCurrency);
   const futuresHeld = tickers.filter((ticker) => isFuturesTicker(ticker)
     && ticker.metadata.positions.some((position) => position.portfolio === target.id && position.shares !== 0));
-  const [quotes, futures] = await Promise.all([
+  const [quotes, futures, purchaseDateFx] = await Promise.all([
     loadCollectionQuotes(tickers, target, ctx.marketData),
     loadPortfolioFuturesTerms(futuresHeld, {
       settlement: basis === "regular-close",
       sources: { history: dailyFuturesHistory(ctx.marketData) },
     }),
+    loadPurchaseDateCostFx(tickers, { into: currency, history: ctx.apiClient, portfolioId: target.id }),
   ]);
   ctx.signal.throwIfAborted();
   const toBase = createBaseConverter(ctx.marketData, currency);
@@ -307,6 +309,7 @@ async function portfolioHoldings(
     toBase,
     basis,
     futures,
+    purchaseDateFx,
   });
   const { allocation, cash } = await valuePortfolioAllocation({ valuation, portfolio: resolved.portfolio, account: resolved.account, toBase });
   ctx.signal.throwIfAborted();
@@ -402,7 +405,7 @@ async function portfolioHoldings(
       : []),
     ...(targetNote ? [targetNote] : []),
     ...(target.portfolio.brokerInstanceId && !resolved.account ? [BROKER_ACCOUNT_MISSING_NOTE] : []),
-    ...(valuation.costAtTodaysRate.size > 0 ? [costAtTodaysRateNote([...valuation.costAtTodaysRate].join(", "))] : []),
+    ...costAtTodaysRateNotes(valuation, (symbols) => [...symbols].join(", ")),
   ];
 
   const positionColumns = allocation.weightBasis === "gross"

package/src/plugins/builtin/portfolio-list/income.ts

@@ -2,6 +2,7 @@ import type { DividendData } from "../dividend-yield/client";
 import { fetchProviderDividendData } from "../dividend-yield/provider-client";
 import { refusedLock } from "../shared/cloud-denied";
 import { ApiRequestError } from "../../../api-client/errors";
+import { isNetworkFailure } from "../../../utils/network-failure";
 import { regularSessionValuationPrice } from "../../../market-data/quotes/regular-session-valuation";
 import { resolveTickerInstrumentKind } from "../../../tickers/instrument-kind";
 import { mapWithConcurrency } from "../../../utils/concurrency";
@@ -65,7 +66,7 @@ function unreadWhy(error: unknown): "sign-in" | "offline" | "failed" {
     current = current instanceof Error ? current.cause : undefined;
   }
   // A request that never got an answer: no connection, DNS, a refused socket.
-  return /fetch failed|network|ECONN|ENOTFOUND|EAI_AGAIN|Unable to connect|socket|offline/i.test(String(error instanceof Error ? error.message : error))
+  return isNetworkFailure(error) || /fetch failed|network|ECONN|ENOTFOUND|EAI_AGAIN|Unable to connect|socket|offline/i.test(String(error instanceof Error ? error.message : error))
     ? "offline" : "failed";
 }
 
@@ -184,6 +185,16 @@ export async function portfolioIncome(
   };
 }
 
+/**
+ * Whether `portfolio show` keeps its Income and Yield columns: once any
+ * holding's income is known, or a holding's is unknown only for want of a
+ * rate into the portfolio's currency, whose rows then show no figure. Income
+ * that could not be read at all gives the columns up to the note alone.
+ */
+export function showsIncomeColumns(income: PortfolioIncome): boolean {
+  return income.knownHoldings > 0 || [...income.gaps.values()].some((gap) => gap.cause === "fx");
+}
+
 const UNREAD_WORDS: Record<"timed-out" | "sign-in" | "offline" | "failed", (seconds: number) => string> = {
   "timed-out": (seconds) => `dividends not read within ${seconds}s`,
   "sign-in": () => "dividends not read without a Gloom sign-in",
@@ -209,7 +220,7 @@ export function incomeGapNote(
     groups.set(key, [...(groups.get(key) ?? []), symbol]);
   }
   const causes = [...groups].map(([cause, symbols]) => `${cause} for ${name(symbols)}`).join("; ");
-  if (income.knownHoldings === 0) return `Income not shown: ${causes}.`;
+  if (income.knownHoldings === 0) return `Income ${showsIncomeColumns(income) ? "unavailable" : "not shown"}: ${causes}.`;
   const others = income.knownHoldings;
   return `Income unavailable: ${causes}. The other ${others === 1 ? "holding pays" : `${others} holdings pay`} ${money(income.knownIncome)} a year.`;
 }

package/src/plugins/builtin/portfolio-list/index.tsx

@@ -1,5 +1,6 @@
-import type { PaneTemplateContext, PaneTemplateInstanceConfig } from "../../../types/plugin";
+import type { PaneTemplateContext, PaneTemplateInstanceConfig, ShortcutArgError } from "../../../types/plugin";
 import type { PluginModule } from "../plugin-module";
+import { unknownCollectionArgError } from "../../../portfolio/collection-name";
 import { PortfolioListPane } from "./pane";
 import {
   buildPortfolioPaneSettingsDef,
@@ -28,6 +29,11 @@ function resolveCollectionIdForKind(context: PaneTemplateContext, kind: "portfol
     : (context.config.watchlists[0]?.id ?? null);
 }
 
+/** `PF Nope`: no portfolio or watchlist has that name or id, so the bar names those that do. */
+function unknownCollectionArg(arg: string, context: PaneTemplateContext): ShortcutArgError | null {
+  return unknownCollectionArgError(arg, [...context.config.portfolios, ...context.config.watchlists], "portfolio or watchlist");
+}
+
 function createCollectionPaneInstance(
   context: PaneTemplateContext,
   kind?: "portfolio" | "watchlist",
@@ -91,7 +97,8 @@ export const portfolioListModule: PluginModule = {
         "portfolio", "watchlist", "collection", "pane", "list",
         "portfolio rebalance", "allocation drift", "target weights", "asset allocation", "cash balance",
       ],
-      shortcut: { prefix: "PF" },
+      // The argument is the report's: `PF Book` opens Book, by name or id in any case.
+      shortcut: { prefix: "PF", argError: unknownCollectionArg },
       headless: collectionHoldingsHeadless,
       canCreate: (context) => resolveCollectionPaneId(context) !== null,
       createInstance: (context, options) => createCollectionPaneInstance(context, undefined, options?.arg),

package/src/plugins/builtin/portfolio-list/pane/index.tsx

@@ -102,7 +102,9 @@ import { useColumnClock } from "../use-column-clock";
 import { liveMarketCapitalization } from "../../../../market-data/quotes/live-valuation";
 import { hasUnknownOptionMultiplier } from "../../../../portfolio/position-metrics";
 import { withFuturesContractSizes } from "../../../../portfolio/futures-positions";
+import { withPurchaseDateCostFx } from "../../../../portfolio/cost-fx";
 import { usePortfolioFuturesTerms } from "./futures-terms";
+import { usePurchaseDateCostFx } from "./purchase-date-fx";
 import {
   allocationWeightBase,
   buildPortfolioAllocation,
@@ -177,11 +179,18 @@ export function PortfolioListPane({ focused, width, height }: PaneProps) {
     () => getCollectionTickersFromConfig(config, tickersBySymbol, activeCollectionId),
     [activeCollectionId, config, tickersBySymbol],
   );
+  // Totals, money columns and account values are in the portfolio's currency.
+  const totalsCurrency = useMemo(
+    () => resolvePortfolioTotalsCurrency(currentPortfolio, config.baseCurrency),
+    [config.baseCurrency, currentPortfolio],
+  );
   // A future counts contracts of the size its terms give, and at the close is valued at its settlement.
   const futuresTerms = usePortfolioFuturesTerms(collectionTickers, { enabled: isPortfolioTab, settlement: valuationBasis === "regular-close" });
+  // A dated lot in another currency costs what its purchase date's FX close says in that currency, as portfolio show values it.
+  const purchaseDateFx = usePurchaseDateCostFx(collectionTickers, { enabled: isPortfolioTab, portfolioId: activeCollectionId, into: totalsCurrency });
   const tickers = useMemo(
-    () => withFuturesContractSizes(collectionTickers, futuresTerms.terms),
-    [collectionTickers, futuresTerms.terms],
+    () => withPurchaseDateCostFx(withFuturesContractSizes(collectionTickers, futuresTerms.terms), purchaseDateFx, totalsCurrency, activeCollectionId),
+    [activeCollectionId, collectionTickers, futuresTerms.terms, purchaseDateFx, totalsCurrency],
   );
   const financialsInstrumentOptions = useMemo(() => ({
     portfolioId: isPortfolioTab ? activeCollectionId : undefined,
@@ -200,11 +209,6 @@ export function PortfolioListPane({ focused, width, height }: PaneProps) {
   // The positions stay as last synced while the broker is away, dated, with one key to bring it back.
   const offlineBrokerFooter = useOfflineBrokerFooter(brokerPortfolio ? offline : null);
   const portfolioTargets = currentPortfolio?.targetWeights;
-  // Totals, money columns and account values are in the portfolio's currency.
-  const totalsCurrency = useMemo(
-    () => resolvePortfolioTotalsCurrency(currentPortfolio, config.baseCurrency),
-    [config.baseCurrency, currentPortfolio],
-  );
   // A boolean, so a quote tick does not rebuild the columns.
   const otherCurrencies = holdsOtherCurrencies(tickers, financialsMap, totalsCurrency);
   const columns = useMemo(
@@ -214,7 +218,9 @@ export function PortfolioListPane({ focused, width, height }: PaneProps) {
   const supplementalData = usePortfolioSupplementalData(tickers, columns, appActive, financialsMap);
   // One lookup for the whole list, only while a perpetual column is on screen.
   const showsPerpetuals = viewMode === "table" && columns.some((column) => PERPETUAL_COLUMN_IDS.has(column.id));
-  const perpetuals = useListPerpetuals(tickers, showsPerpetuals);
+  // The rows in view, from the last render: their contracts follow the quote stream.
+  const [perpetualsInView, setPerpetualsInView] = useState<ReadonlySet<string>>(() => new Set());
+  const perpetuals = useListPerpetuals(tickers, showsPerpetuals, perpetualsInView);
   const openPerpMarket = useOpenPerpMarket();
   const visibleWarmupRequirements = useMemo(
     () => resolveVisibleWarmupRequirements(columns),
@@ -550,6 +556,13 @@ export function PortfolioListPane({ focused, width, height }: PaneProps) {
       }
   ), [height, sortedTickers.length, streamWindow, viewMode]);
 
+  const perpetualsInViewKey = showsPerpetuals
+    ? sortedTickers.slice(effectiveStreamWindow.start, effectiveStreamWindow.end).map((ticker) => ticker.metadata.ticker).join("\u001f")
+    : "";
+  useEffect(() => {
+    setPerpetualsInView(new Set(perpetualsInViewKey ? perpetualsInViewKey.split("\u001f") : []));
+  }, [perpetualsInViewKey]);
+
   usePortfolioPaneStreaming({
     appActive,
     activeCollectionId: isPortfolioTab ? activeCollectionId : undefined,

package/src/plugins/builtin/portfolio-list/pane/purchase-date-fx.ts

@@ -0,0 +1,46 @@
+import { useEffect, useMemo, useRef, useState } from "react";
+import { apiClient } from "../../../../api-client";
+import { loadPurchaseDateCostFx, purchaseDatesToRead, type PurchaseDateCostFx } from "../../../../portfolio/cost-fx";
+import type { TickerRecord } from "../../../../types/ticker";
+
+/** A past close does not change; a date that could not be read is tried again this often. */
+const REFRESH_MS = 30 * 60_000;
+const NO_RATES: PurchaseDateCostFx = new Map();
+
+/**
+ * The FX closes of the purchase dates of the portfolio's dated lots, as
+ * `portfolio show` reads them, so their cost converts at the rate of the day
+ * they were bought into `into`, the currency the pane values the portfolio
+ * in. Read again only when the dated lots or the currency change. Nothing is
+ * read for a portfolio with no such lot.
+ */
+export function usePurchaseDateCostFx(
+  tickers: readonly TickerRecord[],
+  { enabled, portfolioId, into }: { enabled: boolean; portfolioId: string; into: string },
+): PurchaseDateCostFx {
+  const key = useMemo(() => enabled ? [...purchaseDatesToRead(tickers, into, portfolioId).keys()].sort().join(",") : "", [enabled, into, portfolioId, tickers]);
+  const tickersRef = useRef(tickers);
+  tickersRef.current = tickers;
+  // Rates are by currency and date, so those read before a lot was added still hold while the new date is read.
+  const scope = `${into}|${portfolioId}`;
+  const [state, setState] = useState<{ scope: string; rates: PurchaseDateCostFx }>({ scope: "", rates: NO_RATES });
+  const [refresh, setRefresh] = useState(0);
+  const complete = !!key && state.scope === scope && key.split(",").every((date) => state.rates.has(date));
+
+  useEffect(() => {
+    if (!key || complete) return;
+    const timer = setInterval(() => setRefresh((count) => count + 1), REFRESH_MS);
+    return () => clearInterval(timer);
+  }, [complete, key]);
+
+  useEffect(() => {
+    if (!key) return;
+    let cancelled = false;
+    void loadPurchaseDateCostFx(tickersRef.current, { into, history: apiClient, portfolioId }).then((rates) => {
+      if (!cancelled) setState({ scope: `${into}|${portfolioId}`, rates });
+    });
+    return () => { cancelled = true; };
+  }, [into, key, portfolioId, refresh]);
+
+  return key && state.scope === scope ? state.rates : NO_RATES;
+}