gloomberb 0.16.0 → 0.16.2

package/src/cli/pane-functions/headless.ts

@@ -1,4 +1,5 @@
 import { getSharedRegistry } from "../../plugins/registry";
+import { findCachedPortfolioAccount } from "../../plugins/builtin/portfolio-list/cached-account";
 import { parsePublicTickerKey } from "../../utils/exchanges";
 import { apiClient } from "../../api-client";
 import type { MarketContext } from "../types";
@@ -24,6 +25,8 @@ import type { ResolvedSeries } from "../../time-series/types";
 import type { PaneFunctionReport } from "./report";
 import type { ResolvedPaneFunction } from "./resolver";
 import { isRecord } from "../../utils/guards";
+import { formatUtcTime } from "../../utils/utc-time";
+import { deriveHeadlessFreshness, formatFreshnessLine, type ReportFreshness } from "./freshness";
 
 interface SerializableHeadlessColumn {
   key: string;
@@ -149,7 +152,9 @@ async function loadHeadlessPaneModel(
  */
 export async function loadResolvedHeadlessPaneModel(
   resolved: ResolvedPaneFunction,
-  context: Pick<MarketContext, "config" | "store" | "refresh"> & { dataProvider: HeadlessPaneContext["marketData"] },
+  context: Pick<MarketContext, "config" | "store" | "refresh"> & Partial<Pick<MarketContext, "persistence">> & {
+    dataProvider: HeadlessPaneContext["marketData"];
+  },
   rawArgument: string,
   signal: AbortSignal = new AbortController().signal,
 ): Promise<LoadedHeadlessPaneModel> {
@@ -168,7 +173,7 @@ export async function loadResolvedHeadlessPaneModel(
       const portfolio = context.config.portfolios.find(row => row.id === id);
       if (!portfolio) return null;
       const tickers = (await context.store.loadAllTickers()).filter(row => row.metadata.portfolios.includes(id));
-      return { portfolio, tickers };
+      return { portfolio, tickers, account: findCachedPortfolioAccount(context.config, portfolio, context.persistence?.resources) };
     },
     async resolveWatchlist(id) {
       if (!context.config.watchlists.some(row => row.id === id)) return null;
@@ -244,6 +249,7 @@ export function serializeHeadlessPaneResult(
 ): Record<string, unknown> {
   const common = {
     ...(result.errors ? { errors: result.errors } : {}),
+    ...(result.notes?.length ? { notes: result.notes } : {}),
     ...(result.metadata ? { metadata: result.metadata } : {}),
   };
   switch (definition.shape) {
@@ -326,8 +332,7 @@ function float32Shortest(value: number): number | null {
 
 function displayTime(time: number): string {
   if (!Number.isFinite(time)) return "-";
-  const iso = new Date(time).toISOString();
-  return iso.endsWith("T00:00:00.000Z") ? iso.slice(0, 10) : `${iso.slice(0, 16).replace("T", " ")} UTC`;
+  return formatUtcTime(new Date(time));
 }
 
 const CALENDAR_RESOLUTIONS = new Set(["1d", "1wk", "1mo"]);
@@ -339,7 +344,7 @@ function seriesPointDate(series: HeadlessSeries, date: HeadlessSeries["points"][
   const resolved = series as HeadlessSeries & Partial<Pick<ResolvedSeries, "historyResolution" | "timeBasis">>;
   return resolved.historyResolution && CALENDAR_RESOLUTIONS.has(resolved.historyResolution)
     ? observationDate(time, resolved)
-    : displayTime(time);
+    : formatUtcTime({ time, dateOnly: typeof date === "string" && /^\d{4}-\d{2}-\d{2}$/.test(date) });
 }
 
 function seriesValue(series: HeadlessSeries, value: number | null): string {
@@ -415,18 +420,36 @@ function renderSeries(result: HeadlessSeriesResult): string[] {
   return lines;
 }
 
-function reportTitle(definition: HeadlessPaneDefinition, args: HeadlessPaneLoadArgs, fallback: string): string {
-  if (typeof definition.describe === "function") return definition.describe(args);
+function reportTitle(
+  definition: HeadlessPaneDefinition,
+  args: HeadlessPaneLoadArgs,
+  result: HeadlessPaneResult,
+  fallback: string,
+): string {
+  if (typeof definition.describe === "function") return definition.describe(args, result);
   return definition.describe ?? fallback;
 }
 
+/** One message stays on the label's line; several each get a line of their own, so none runs into the next. */
+function renderMessages(label: string, messages: readonly string[]): string[] {
+  return messages.length === 1
+    ? [cliStyles.warning(`${label}: ${messages[0]}`)]
+    : [cliStyles.warning(`${label}:`), ...messages.map((message) => `  ${message}`)];
+}
+
+/**
+ * The text form of every headless report. It always ends with the source,
+ * as-of and status line, so no pane can leave it out; a pane can only make it
+ * more accurate through its `freshness` declaration.
+ */
 export function renderHeadlessPaneText(
   definition: HeadlessPaneDefinition,
   result: HeadlessPaneResult,
   args: HeadlessPaneLoadArgs,
   fallbackTitle: string,
+  freshness: ReportFreshness = deriveHeadlessFreshness(definition, result),
 ): string {
-  const lines = [cliStyles.bold(reportTitle(definition, args, fallbackTitle)), ""];
+  const lines = [cliStyles.bold(reportTitle(definition, args, result, fallbackTitle)), ""];
   const notices = result.metadata?.notices;
   if (Array.isArray(notices)) {
     const textNotices = [...new Set(notices.filter((notice): notice is string => typeof notice === "string" && notice.trim().length > 0))];
@@ -446,7 +469,8 @@ export function renderHeadlessPaneText(
       break;
     case "snapshot": {
       const snapshot = result as HeadlessSnapshotResult;
-      lines.push(`As of: ${displayValue(snapshot.asOf)}`, "", renderRows(snapshot.items, undefined, definition.columns));
+      // The closing source line carries the snapshot's as-of, so it is not printed twice.
+      lines.push(renderRows(snapshot.items, undefined, definition.columns));
       break;
     }
     default: {
@@ -454,8 +478,9 @@ export function renderHeadlessPaneText(
       return _exhaustive;
     }
   }
-  if (result.errors?.length) lines.push("", cliStyles.warning(`Errors: ${result.errors.join(" ")}`));
-  return lines.join("\n").trimEnd();
+  if (result.notes?.length) lines.push("", ...renderMessages("Notes", result.notes));
+  if (result.errors?.length) lines.push("", ...renderMessages("Errors", result.errors));
+  return [lines.join("\n").trimEnd(), "", cliStyles.muted(formatFreshnessLine(freshness))].join("\n");
 }
 
 function resultRowCount(definition: HeadlessPaneDefinition, result: HeadlessPaneResult): number {
@@ -487,6 +512,7 @@ export async function buildHeadlessFunctionReport(
   const symbols = loaded.result.symbols ?? loaded.args.symbols;
   const unavailableSymbols = loaded.result.unavailableSymbols ?? (rowCount === 0 ? symbols : []);
   const serialized = serializeHeadlessPaneResult(loaded.definition, loaded.result);
+  const freshness = deriveHeadlessFreshness(loaded.definition, loaded.result);
   return {
     data: {
       kind: loaded.definition.shape,
@@ -499,12 +525,14 @@ export async function buildHeadlessFunctionReport(
       complete: loaded.result.complete !== false && unavailableSymbols.length === 0 && !loaded.result.errors?.length,
       unavailableSymbols,
       ...serialized,
+      freshness,
     },
     text: renderHeadlessPaneText(
       loaded.definition,
       loaded.result,
       loaded.args,
       resolved.label,
+      freshness,
     ),
   };
 }

package/src/cli/pane-functions/index.ts

@@ -14,13 +14,15 @@ import {
   parsePaneFunctionArgs,
   type ParsedPaneFunctionArgs,
 } from "./options";
-import { resolvePaneFunction, type ResolvedPaneFunction } from "./resolver";
+import { applyListingArgument, resolvePaneFunction, type ResolvedPaneFunction } from "./resolver";
 import { buildFunctionReport } from "./report";
 import { defaultScreenshotPath, renderDesktopShot } from "./screenshot";
 import {
   buildPaneCatalogEntries,
 } from "./catalog";
+import { accessGateStatus, incompleteReportGateMessage } from "./access-gate";
 import { withPersistedCloudSession } from "./cloud-session";
+import { loadForListing } from "../listing-arg";
 
 async function withPaneRuntime<T>(
   ctx: CliCommandContext,
@@ -33,11 +35,11 @@ async function withPaneRuntime<T>(
   }) => Promise<T>,
   settings: { strictHeadlessOptions?: boolean } = {},
 ): Promise<T> {
-  const parsed = parsePaneFunctionArgs(args, ctx.cliOptions);
   return withMarketData(ctx, async (market) => {
     const context: MarketContext = ctx.cliOptions.refresh ? { ...market, refresh: true } : market;
     const registry = await createPaneCatalog(context, ctx.plugins);
     try {
+      const parsed = await applyListingArgument(registry, context, parsePaneFunctionArgs(args, ctx.cliOptions));
       const resolved = await resolvePaneFunction(registry, context, parsed, settings);
       return await run({ parsed, context, registry, resolved });
     } finally {
@@ -57,14 +59,23 @@ export async function runPaneFunction(args: string[], ctx: CliCommandContext) {
           + `Use "gloomberb catalog ${resolved.token}" to inspect readiness.`,
         );
       }
+      // A report that fails or comes back empty for an exchange the symbol is not listed on says so.
       const report = await withPersistedCloudSession(
         context,
-        () => buildFunctionReport(resolved, context, parsed.arg),
+        () => loadForListing(
+          parsed.listing ?? [],
+          context,
+          ctx,
+          () => buildFunctionReport(resolved, context, parsed.arg),
+          (built) => built.data.empty || !built.data.complete,
+        ),
       );
       if (parsed.requireBotSafe && (report.data.empty || !report.data.complete)) {
         const unavailable = report.data.unavailableSymbols.length > 0
           ? ` Missing data for ${report.data.unavailableSymbols.join(", ")}.`
           : "";
+        const gated = incompleteReportGateMessage(resolved.token, report.data.errors);
+        if (gated) throw new Error(gated);
         throw new Error(
           `${resolved.token} did not produce a complete bot-safe report.${unavailable}`,
         );
@@ -110,7 +121,7 @@ export async function runPaneScreenshot(args: string[], ctx: CliCommandContext)
       ctx.printResult({ data: result }, {
         text: (data) => {
           const issues = [
-            data.empty ? "empty" : null,
+            data.render.accessGate && (data.empty || !data.usable) ? accessGateStatus(data.render.accessGate) : data.empty ? "empty" : null,
             data.complete ? null : "incomplete",
             data.semanticMismatch ? "does not match the data" : null,
             data.usable ? null : "not usable",

package/src/cli/pane-functions/options.ts

@@ -9,6 +9,7 @@ import {
 } from "../../plugins/builtin/ticker-detail/financials/ratios";
 import type { PaneRuntimeState } from "../../core/state/app/state";
 import type { NormalizedPaneFunctionOptions } from "./capabilities";
+import type { ListingArg } from "../listing-arg";
 
 const DEFAULT_SHOT_WIDTH = 1280;
 const DEFAULT_SHOT_HEIGHT = 720;
@@ -32,6 +33,8 @@ export interface ParsedPaneFunctionArgs {
   /** Small label drawn in the pane title bar, e.g. a domain; null draws nothing. */
   watermark: string | null;
   requireBotSafe: boolean;
+  /** The listing a one-ticker function's argument named, once `applyListingArgument` has resolved it. */
+  listing?: ListingArg;
 }
 
 export interface ParsedPaneCatalogArgs {

package/src/cli/pane-functions/report.ts

@@ -3,6 +3,7 @@ import type { NormalizedPaneFunctionOptions } from "./capabilities";
 import type { ResolvedPaneFunction } from "./resolver";
 import { buildHeadlessFunctionReport } from "./headless";
 import { appendDomReportFooter, buildDomFunctionReport } from "./dom";
+import type { ReportFreshness } from "./freshness";
 
 export type PaneFunctionReportSource = "headless" | "dom";
 
@@ -20,6 +21,8 @@ interface PaneFunctionReportData {
   empty: boolean;
   complete: boolean;
   unavailableSymbols: string[];
+  /** Source, as-of in UTC and live/delayed/stale/not-a-feed status; the last line of the text report. */
+  freshness: ReportFreshness;
   [key: string]: unknown;
 }
 
@@ -56,6 +59,7 @@ export async function buildFunctionReport(
       report.text,
       elapsedMs,
       report.data.truncated === true,
+      report.data.freshness,
     );
   }
   return report;

package/src/cli/pane-functions/resolver.ts

@@ -10,6 +10,7 @@ import { applyChartComposerCapabilityOptions } from "../../plugins/builtin/chart
 import { parseChartSpec } from "../../plugins/builtin/chart-composer/chart-spec";
 import { normalizeTickerInput } from "../../tickers/search";
 import { slugifyName } from "../../utils/slugify";
+import { resolveCliListing } from "../listing-arg";
 import type { MarketContext } from "../types";
 import {
   buildPaneFunctionLookup,
@@ -94,6 +95,37 @@ async function buildPaneInstance(
   };
 }
 
+function findPaneFunction(registry: PaneFunctionCatalog, target: string): { template?: PaneTemplateDef; pane?: PaneDef } | null {
+  const entry = buildPaneFunctionLookup(registry).get(normalizeLookupToken(target));
+  if (!entry) return null;
+  const template = "paneId" in entry && "description" in entry ? entry as PaneTemplateDef : undefined;
+  return { template, pane: template ? registry.panes.get(template.paneId) : entry as PaneDef };
+}
+
+/**
+ * `fn ANR SAN --exchange EPA` is `fn ANR SAN:EPA`: a function that takes one
+ * ticker gets the listing in its argument, and an exchange the app does not
+ * know fails with the venues the symbol trades on.
+ */
+export async function applyListingArgument(
+  registry: PaneFunctionCatalog,
+  context: MarketContext,
+  args: ParsedPaneFunctionArgs,
+): Promise<ParsedPaneFunctionArgs> {
+  const found = args.target ? findPaneFunction(registry, args.target) : null;
+  if (!found?.pane || !args.arg || /\s/.test(args.arg)) return args;
+  const headless = getHeadlessPaneDefinition(found.template, found.pane);
+  const takesOneTicker = headless ? headless.argument.kind === "ticker" : found.template?.shortcut?.argKind === "ticker";
+  // A function with an exchange option of its own (DIST) keeps it.
+  if (!takesOneTicker || getPaneFunctionCapability(found.template, found.pane).options.some((option) => option.key === "exchange")) {
+    return args;
+  }
+  const exchange = typeof args.options.exchange === "string" ? args.options.exchange : undefined;
+  const listing = await resolveCliListing(args.arg, exchange, context);
+  const { exchange: _exchange, ...options } = args.options;
+  return { ...args, arg: listing.key, options, listing };
+}
+
 export async function resolvePaneFunction(
   registry: PaneFunctionCatalog,
   context: MarketContext,
@@ -104,9 +136,8 @@ export async function resolvePaneFunction(
     throw new Error("Usage: gloomberb fn <function-or-pane> [argument] [--key value]");
   }
 
-  const lookup = buildPaneFunctionLookup(registry);
-  const entry = lookup.get(normalizeLookupToken(args.target));
-  if (!entry) {
+  const found = findPaneFunction(registry, args.target);
+  if (!found) {
     const shortcuts = [...registry.paneTemplates.values()]
       .map((template) => template.shortcut?.prefix)
       .filter((prefix): prefix is string => !!prefix)
@@ -114,10 +145,7 @@ export async function resolvePaneFunction(
     throw new Error(`Unknown function or pane "${args.target}". Try one of: ${shortcuts.slice(0, 18).join(", ")}`);
   }
 
-  const template = "paneId" in entry && "description" in entry ? entry as PaneTemplateDef : undefined;
-  const pane = template
-    ? registry.panes.get(template.paneId)
-    : entry as PaneDef;
+  const { template, pane } = found;
   if (!pane) {
     throw new Error(`Template "${template?.id}" points at missing pane "${template?.paneId}".`);
   }

package/src/cli/pane-functions/screenshot-evidence.ts

@@ -18,6 +18,7 @@ import { scenarioScreenshotEvidence } from "../../plugins/builtin/options-scenar
 import { realizedVolScreenshotEvidence } from "../../plugins/builtin/realized-vol/evidence";
 import { volSurfaceScreenshotEvidence } from "../../plugins/builtin/vol-surface/evidence";
 import { volatilityScreenshotEvidence } from "../../plugins/builtin/volatility/evidence";
+import { worldMapScreenshotEvidence } from "../../plugins/builtin/world-venue-map/evidence";
 
 /** The envelope every pane's rendered chart-data evidence carries. */
 export interface PaneScreenshotEvidence {
@@ -93,6 +94,7 @@ const PANE_SCREENSHOT_EVIDENCE: readonly PaneScreenshotEvidenceHook[] = [
   realizedVolScreenshotEvidence,
   volSurfaceScreenshotEvidence,
   volatilityScreenshotEvidence,
+  worldMapScreenshotEvidence,
 ];
 
 export function paneScreenshotEvidenceHook(resolved: ResolvedPaneFunction): PaneScreenshotEvidenceHook | null {

package/src/cli/pane-functions/screenshot.ts

@@ -72,6 +72,8 @@ import { getCloudApiBaseUrl } from "../../api-client/request";
 import { collectExternalPluginBundles } from "../../renderers/electrobun/bun/external-plugins";
 import type { ResolvedSeries } from "../../time-series/types";
 import { getQuoteMonitorPaneSettings } from "../../plugins/builtin/ticker-detail/settings";
+import { accessGateSentence } from "./access-gate";
+import { findCollection } from "../../plugins/builtin/portfolio-list/cli/render";
 import {
   paneEvidenceMismatches,
   paneScreenshotEvidenceHook,
@@ -651,8 +653,9 @@ async function collectShotSymbolsWithCollections(
   context: MarketContext,
   rawArg: string,
 ): Promise<string[]> {
-  const symbols = collectShotSymbols(resolved, rawArg);
-  if (!COLLECTION_PANE_IDS.has(resolved.pane.id)) return symbols;
+  if (!COLLECTION_PANE_IDS.has(resolved.pane.id)) return collectShotSymbols(resolved, rawArg);
+  // `shot PF Retirement` names a portfolio, not a ticker to fetch.
+  const symbols = rawArg.trim() && findCollection(context.config, rawArg) ? [] : collectShotSymbols(resolved, rawArg);
   const members = (await context.store.loadAllTickers())
     .filter(({ metadata }) => metadata.portfolios.length > 0 || metadata.watchlists.length > 0)
     .map(({ metadata }) => metadata.ticker);
@@ -857,7 +860,7 @@ export function filledKeyValueCount(rows: DesktopPaneShotRenderResult["visibleKe
 export function shotUnusableReasonFor(
   resolved: ResolvedPaneFunction,
   payload: DesktopPaneShotPayload,
-  render: Pick<DesktopPaneShotRenderResult, "loadingStateDetected" | "errorStateDetected" | "emptyStateDetected">,
+  render: Pick<DesktopPaneShotRenderResult, "loadingStateDetected" | "errorStateDetected" | "emptyStateDetected" | "accessGate">,
   unavailableSymbols: string[],
   semanticMismatch: boolean,
 ): string {
@@ -871,6 +874,7 @@ export function shotUnusableReasonFor(
     return `No intraday price history is available for ${symbol} for the requested session window.`;
   }
   if (render.loadingStateDetected) return "The pane was still loading when the screenshot was captured.";
+  if (render.accessGate) return accessGateSentence(render.accessGate);
   if (render.errorStateDetected) return "The pane rendered an error state.";
   if (render.emptyStateDetected) return "The pane rendered an empty state.";
   if (unavailableSymbols.length > 0) return `Data is unavailable for ${unavailableSymbols.join(", ")}.`;

package/src/cli/result.ts

@@ -11,11 +11,19 @@ import {
   type CliTableColumn,
 } from "../utils/cli-output";
 import { serializeCsv } from "../utils/csv";
+import { formatUtcTime, isEpochMilliseconds, isZonedIsoDateTime } from "../utils/utc-time";
+import { formatFreshnessLine, type ReportFreshness } from "./pane-functions/freshness";
 
 export interface CliResult<T = unknown> {
   data: T;
   metadata?: Record<string, unknown>;
   warnings?: string[];
+  /**
+   * Source, as-of and status of market data, as every `fn` report states them
+   * (docs/usage.md#how-current-a-report-is): the last line of the text output
+   * and `metadata.freshness` in JSON. CSV and NDJSON stay rows only.
+   */
+  freshness?: ReportFreshness;
 }
 
 export interface CliErrorObject {
@@ -47,21 +55,20 @@ export interface CliResultRenderOptions<T = unknown, Row = Record<string, unknow
   empty?: string;
   /** Text-mode block printed above the rows, for figures that are not rows. */
   summary?: (data: T) => string;
+  /** Text-mode line printed first, naming what the result is about, such as the listing a symbol resolved to. */
+  heading?: string;
 }
 
-interface CliResultJsonEnvelope<T> extends CliResult<T> {
+interface CliResultJsonEnvelope<T> extends Omit<CliResult<T>, "freshness"> {
   ok: true;
   columns?: Array<Pick<CliResultColumn, "key" | "header" | "align" | "width">>;
 }
 
 type TextCellContext = "table" | "record";
 
-const ISO_DATE_TIME = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?(?:Z|[+-]\d{2}:?\d{2})?$/;
-const TIME_KEY = /(?:At|Time|Timestamp)$/;
+// Keys whose epoch-millisecond numbers are times rather than counts or prices.
+const TIME_KEY = /(?:At|Time|Timestamp|Updated|AsOf)$|^(?:asOf|timestamp)$/;
 const IDENTIFIER_KEY = /^id$|Id$/;
-// Epoch milliseconds between 2001 and 2286, so counts and prices are never read as dates.
-const EPOCH_MS_MIN = 1e12;
-const EPOCH_MS_MAX = 1e13;
 const KEY_ACRONYMS: Record<string, string> = {
   api: "API",
   cik: "CIK",
@@ -106,13 +113,8 @@ export function humanizeCliKey(key: string): string {
     .join(" ");
 }
 
-function pad2(value: number): string {
-  return String(value).padStart(2, "0");
-}
-
-function formatLocalDateTime(date: Date): string {
-  if (Number.isNaN(date.getTime())) return "";
-  return `${date.getFullYear()}-${pad2(date.getMonth() + 1)}-${pad2(date.getDate())} ${pad2(date.getHours())}:${pad2(date.getMinutes())}`;
+function isTimeValue(key: string | undefined, value: number): boolean {
+  return key != null && TIME_KEY.test(key) && isEpochMilliseconds(value);
 }
 
 // Six significant digits hide float noise (0.9499999999999886) without cutting real precision;
@@ -132,16 +134,13 @@ function formatTextValue(
 ): string {
   const missing = context === "record" ? cliStyles.muted("-") : "";
   if (value == null || value === "") return missing;
-  if (value instanceof Date) return formatLocalDateTime(value);
+  // Times print in UTC with the zone named, never in the host's zone; JSON and CSV keep the raw value.
+  if (value instanceof Date) return formatUtcTime(value);
   if (typeof value === "boolean") return value ? "yes" : "no";
-  if (typeof value === "number") {
-    if (key && TIME_KEY.test(key) && value >= EPOCH_MS_MIN && value < EPOCH_MS_MAX) {
-      return formatLocalDateTime(new Date(value));
-    }
-    return formatTextNumber(value);
-  }
+  if (typeof value === "number") return isTimeValue(key, value) ? formatUtcTime(value) : formatTextNumber(value);
   if (typeof value === "string") {
-    return ISO_DATE_TIME.test(value) ? formatLocalDateTime(new Date(value)) || value : value;
+    // A date and time without a zone stays as the source wrote it: its zone is unknown.
+    return isZonedIsoDateTime(value) ? formatUtcTime(value) : value;
   }
   if (Array.isArray(value)) {
     if (value.length === 0) return context === "record" ? cliStyles.muted("none") : "";
@@ -198,9 +197,7 @@ function isEmptyTextValue(value: unknown): boolean {
 function inferTextColumns(rows: Record<string, unknown>[]): CliResultColumn<Record<string, unknown>>[] {
   return inferColumns(rows).map((column) => {
     const values = rows.map((row) => row?.[column.key]).filter((value) => !isEmptyTextValue(value));
-    const numeric = values.length > 0 && values.every((value) => typeof value === "number" && !(
-      TIME_KEY.test(column.key) && value >= EPOCH_MS_MIN && value < EPOCH_MS_MAX
-    ));
+    const numeric = values.length > 0 && values.every((value) => typeof value === "number" && !isTimeValue(column.key, value));
     return {
       ...column,
       header: humanizeCliKey(column.key),
@@ -304,22 +301,38 @@ function overflowsTerminal<Row extends Record<string, unknown>>(rows: Row[]): bo
   return width > terminalWidth;
 }
 
+/** The closing source, as-of and status line of a text result, for output printed without `printResult`. */
+export function cliFreshnessFooter(freshness: ReportFreshness): string {
+  return cliStyles.muted(formatFreshnessLine(freshness));
+}
+
 export function serializeCliResult<T, Row extends Record<string, unknown> = Record<string, unknown>>(
   result: CliResult<T>,
   options: CliGlobalOptions,
   renderOptions: CliResultRenderOptions<T, Row> = {},
 ): string {
+  const { freshness, ...rest } = result;
   if (options.format === "json") {
     const columns = serializeColumns(renderOptions.columns);
     const envelope: CliResultJsonEnvelope<T> = {
       ok: true,
-      ...result,
+      ...rest,
+      ...(freshness ? { metadata: { ...rest.metadata, freshness } } : {}),
       data: applyLimit(result.data, options.limit),
       ...(columns?.length ? { columns } : {}),
     };
     return JSON.stringify(envelope, null, 2);
   }
+  const body = serializeCliRows(rest, options, renderOptions);
+  if (options.format !== "text" || !freshness) return body;
+  return body ? `${body}\n\n${cliFreshnessFooter(freshness)}` : cliFreshnessFooter(freshness);
+}
 
+function serializeCliRows<T, Row extends Record<string, unknown>>(
+  result: CliResult<T>,
+  options: CliGlobalOptions,
+  renderOptions: CliResultRenderOptions<T, Row>,
+): string {
   const rows = asRows(result.data, options.limit, renderOptions.rows);
   if (options.format === "ndjson") {
     return rows.map((row) => JSON.stringify(row)).join("\n");
@@ -331,11 +344,12 @@ export function serializeCliResult<T, Row extends Record<string, unknown> = Reco
     return renderOptions.text(result.data);
   }
   const summary = renderOptions.summary?.(result.data) ?? "";
+  const withHeading = (text: string) => renderOptions.heading ? `${renderOptions.heading}\n${text}` : text;
   if (rows.length === 0) {
-    return summary || cliStyles.muted(renderOptions.empty ?? "No results.");
+    return withHeading(summary || cliStyles.muted(renderOptions.empty ?? "No results."));
   }
   const body = renderTextRows(rows as Row[], result.data, renderOptions);
-  return summary ? `${summary}\n\n${body}` : body;
+  return withHeading(summary ? `${summary}\n\n${body}` : body);
 }
 
 function renderTextRows<T, Row extends Record<string, unknown>>(

package/src/cli/ticker-resolution.ts

@@ -3,19 +3,21 @@ import type { TickerRecord } from "../types/ticker";
 import type { TickerRepository } from "../data/ticker-repository";
 import { resolveTickerSearch, upsertTickerFromSearchResult } from "../tickers/search";
 import { canonicalExchange } from "../utils/exchanges";
+import { resolveCliListing } from "./listing-arg";
 
+/** The saved ticker for a symbol (`SAN:EPA`, or `SAN` with `--exchange EPA`), saving it from search first if needed. */
 export async function resolveTickerForCli(
   symbol: string,
   store: TickerRepository,
   dataProvider: DataProvider,
+  exchange?: string,
 ): Promise<TickerRecord> {
-  const normalized = symbol.trim().toUpperCase();
-  if (!normalized) {
+  if (!symbol.trim()) {
     throw new Error("Ticker symbol is required.");
   }
-
-  const localTicker = await store.loadTicker(normalized);
-  if (localTicker) return localTicker;
+  const listing = await resolveCliListing(symbol, exchange, { store, dataProvider });
+  if (listing.saved) return listing.saved;
+  const normalized = listing.key;
 
   const localTickers = new Map(
     (await store.loadAllTickers()).map((ticker) => [ticker.metadata.ticker.toUpperCase(), ticker] as const),