gloomberb 0.16.3 → 0.16.4

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

@@ -0,0 +1,63 @@
+import type { RemoteUiNodeSnapshot } from "../../remote/types";
+import type { HeadlessFreshnessStatus, HeadlessPaneFreshness } from "../../types/headless";
+import { isFiniteNumber, isRecord } from "../../utils/guards";
+
+export interface RenderedReportNotices {
+  /** Lines a report prints under its title, such as "21 of 145 strikes". */
+  notices: string[];
+  /** The same facts by key, for `metadata` in JSON: `strikes: { shown, total, window }`. */
+  facts: Record<string, unknown>;
+}
+
+/**
+ * What a rendered pane says about the rows it lists, from the `report-notice`
+ * nodes it publishes: `{ text, key?, value? }`. The pane knows what its view
+ * leaves out (the option chain's strike window); the report repeats it.
+ */
+export function renderedReportNotices(semanticUi: readonly RemoteUiNodeSnapshot[]): RenderedReportNotices {
+  const notices: string[] = [];
+  const facts: Record<string, unknown> = {};
+  for (const node of semanticUi) {
+    if (node.role !== "report-notice" || !node.metadata) continue;
+    const { text, key, value } = node.metadata as { text?: unknown; key?: unknown; value?: unknown };
+    if (typeof text === "string" && text.trim() && !notices.includes(text.trim())) notices.push(text.trim());
+    if (typeof key === "string" && key && value !== undefined) facts[key] = value;
+  }
+  return { notices, facts };
+}
+
+const FRESHNESS_STATUSES: readonly HeadlessFreshnessStatus[] = ["live", "delayed", "stale", "not-a-feed"];
+
+/**
+ * How current a rendered pane says its data is, from the `report-freshness`
+ * node it publishes: `{ asOf?, status?, delayMinutes? }`. A capture keeps no
+ * footer status and few cells carry a time, so a pane that knows its feed
+ * (OMON's chain) dates the report here, as the plain command over the same
+ * data does. A pane whose figures come from several dated quotes (FXC's pair
+ * rates) publishes them instead, see `renderedReportObservations`.
+ */
+export function renderedReportFreshness(
+  semanticUi: readonly RemoteUiNodeSnapshot[],
+): Pick<HeadlessPaneFreshness, "asOf" | "status" | "delayMinutes"> {
+  const metadata = semanticUi.find((node) => node.role === "report-freshness")?.metadata;
+  if (!metadata) return {};
+  const { asOf, status, delayMinutes } = metadata as { asOf?: unknown; status?: unknown; delayMinutes?: unknown };
+  return {
+    ...(typeof asOf === "string" || isFiniteNumber(asOf) ? { asOf } : {}),
+    ...(FRESHNESS_STATUSES.includes(status as HeadlessFreshnessStatus) ? { status: status as HeadlessFreshnessStatus } : {}),
+    ...(isFiniteNumber(delayMinutes) && delayMinutes > 0 ? { delayMinutes } : {}),
+  };
+}
+
+/**
+ * The dated observations a rendered pane's figures come from, from the
+ * `observations` its `report-freshness` node publishes: one record per quote
+ * or rate, in the fields of a headless report's rows (`quoteTime`,
+ * `dataSource`, `delayMinutes`, `stale`, `sessionExchange`, `marketState`).
+ * The report reads them as it reads those rows, so it says what the newest is,
+ * how far the feed is held back, which are stale and where the market stands.
+ */
+export function renderedReportObservations(semanticUi: readonly RemoteUiNodeSnapshot[]): Record<string, unknown>[] {
+  const observations = semanticUi.find((node) => node.role === "report-freshness")?.metadata?.observations;
+  return Array.isArray(observations) ? observations.filter(isRecord) : [];
+}

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

@@ -49,6 +49,10 @@ export async function buildFunctionReport(
   const startedAt = performance.now();
   const source = resolvePaneFunctionReportSource(resolved);
   if (!source) {
+    // HELP is what a newcomer tries first: send them to the command guide and the function list.
+    if (resolved.pane.id === "help") {
+      throw new Error("HELP is an in-app pane, so it has no report. For the commands run `gloomberb help`; for the functions run `gloomberb catalog`.");
+    }
     throw new Error(`${resolved.token} is an interactive pane and does not expose a data report.`);
   }
 

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

@@ -180,12 +180,10 @@ export async function resolvePaneFunction(
   const normalizedOptions = normalizeCapabilityOptions(capability, args.options, {
     strict: args.requireBotSafe || (!!headless && resolutionSettings.strictHeadlessOptions === true),
   });
-  const settings = capability.botSafe
-    ? {
-      ...optionSettings(args.options),
-      ...capabilityPaneSettings(capability, normalizedOptions),
-    }
-    : optionSettings(args.options);
+  const settings = {
+    ...optionSettings(args.options),
+    ...capabilityPaneSettings(capability, normalizedOptions),
+  };
   if (args.requireBotSafe) {
     validateTickerCardinality(capability, createOptions);
   }

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 { marketHeatmapScreenshotEvidence } from "../../plugins/builtin/market-heatmap/evidence";
 import { worldMapScreenshotEvidence } from "../../plugins/builtin/world-venue-map/evidence";
 
 /** The envelope every pane's rendered chart-data evidence carries. */
@@ -95,6 +96,7 @@ const PANE_SCREENSHOT_EVIDENCE: readonly PaneScreenshotEvidenceHook[] = [
   volSurfaceScreenshotEvidence,
   volatilityScreenshotEvidence,
   worldMapScreenshotEvidence,
+  marketHeatmapScreenshotEvidence,
 ];
 
 export function paneScreenshotEvidenceHook(resolved: ResolvedPaneFunction): PaneScreenshotEvidenceHook | null {

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

@@ -1,4 +1,5 @@
 import { fetchTape } from "../../plugins/builtin/time-sales/client";
+import { isOptionsUnavailableError } from "../../market-data/options-alternatives";
 import type { TapeCapture } from "../../plugins/builtin/time-sales/snapshot-client";
 import { apiClient } from "../../api-client";
 import { snapshotInstrumentKey, type SnapshotMarketData } from "../../market-data/snapshot-provider";
@@ -9,7 +10,7 @@ import { dirname, resolve } from "path";
 import { mkdir } from "fs/promises";
 import type { PaneRuntimeState } from "../../core/state/app/state";
 import { CHART_COMPOSER_PANE_ID, type AppConfig } from "../../types/config";
-import type { OptionsChain, PricePoint, TickerFinancials } from "../../types/financials";
+import type { OptionsChain, PricePoint, Quote, TickerFinancials } from "../../types/financials";
 import type { TickerRecord } from "../../types/ticker";
 import { slugifyName } from "../../utils/slugify";
 import {
@@ -18,7 +19,7 @@ import {
   type HttpProxyRequestEnvelope,
   type HttpProxyResponseEnvelope,
 } from "../../utils/http-proxy-response";
-import { getTheme, getThemeIds } from "../../theme/themes";
+import { requireThemeId } from "../commands/themes";
 import { isRecord } from "../../utils/guards";
 
 const DEFAULT_SHOT_DEVICE_SCALE_FACTOR = 2;
@@ -86,6 +87,7 @@ import {
   clipPriceHistoryToRange,
   createFallbackTicker,
   fetchTickerFinancials,
+  loadBrokerMarkedHolding,
   isFinancialAnalysisFunction,
   readsDailyReturns,
   withShotDailyReturns,
@@ -93,6 +95,9 @@ import {
   withShotPriceHistory,
   withShotSeasonalityHistory,
 } from "./data";
+import { renderedReportFreshness, renderedReportNotices, renderedReportObservations } from "./report-notices";
+import { deriveRenderedFreshness, statusLineVariants, type ReportFreshness } from "./freshness";
+import { quotesFreshness } from "../freshness";
 import {
   financialRatioRenderMismatches,
   financialRatioShotEvidence,
@@ -426,6 +431,10 @@ export interface PaneScreenshotResult {
   usable: boolean;
   unusableReason: string | null;
   dataEvidence: PaneScreenshotDataEvidence | null;
+  /** What the pane says its view leaves out, such as OMON's "21 of 145 strikes". */
+  notices?: string[];
+  /** How current the captured data is, as the capture's status line says it; absent with `--no-status`. */
+  freshness?: ReportFreshness;
   outputPath: string;
   render: DesktopPaneShotRenderResult & {
     expectedText: string[];
@@ -493,7 +502,7 @@ export async function buildDesktopShotPayload(
   };
   const config = stripDesktopShotCredentials<AppConfig>({
     ...context.config,
-    ...(theme ? { theme: resolveShotTheme(theme) } : {}),
+    ...(theme ? { theme: requireThemeId(theme) } : {}),
     layout,
     layouts: [{
       name: "CLI Shot",
@@ -525,7 +534,7 @@ export async function buildDesktopShotPayload(
     shotInstance = { ...shotInstance, settings: { ...shotInstance.settings, ...prepared.settings } };
     for (const [symbol, data] of prepared.financials ?? []) {
       financials.push([symbol, data]);
-      tickers.push(createFallbackTicker(symbol, data, context));
+      tickers.push(await createFallbackTicker(symbol, data, context));
     }
   } else if (resolved.pane.id === "analytics") {
     const loaded = await loadResolvedHeadlessPaneModel(resolved, context, rawArg);
@@ -551,13 +560,23 @@ export async function buildDesktopShotPayload(
       if (!target.instrument) financials.push([label, data]);
       const { symbol } = parsePublicTickerKey(key);
       const ticker = await context.store.loadTicker(key) ?? await context.store.loadTicker(symbol);
-      tickers.push(ticker ?? createFallbackTicker(key, data, context));
+      tickers.push(ticker ?? await createFallbackTicker(key, data, context));
     }
     intradayHistories.push(...chartModel.snapshot.intradayHistories.map((history) => ({
       ...history, start: history.start?.toISOString() ?? null, end: history.end?.toISOString() ?? null,
     })));
   } else for (const symbol of await collectShotSymbolsWithCollections(resolved, context, rawArg)) {
-    const entry = await fetchTickerFinancials(context, symbol);
+    let entry: Awaited<ReturnType<typeof fetchTickerFinancials>>;
+    try {
+      entry = await fetchTickerFinancials(context, symbol);
+    } catch (error) {
+      // The pane values a holding no quote covers, such as an option contract,
+      // at the broker's mark. It has no financials to capture.
+      const holding = COLLECTION_PANE_IDS.has(resolved.pane.id) ? await loadBrokerMarkedHolding(context, symbol) : null;
+      if (!holding) throw error;
+      tickers.push(holding);
+      continue;
+    }
     const requestedRange = shotPriceHistoryRange(resolved);
     let data = entry.financials;
     const exchange = entry.instrument.exchange
@@ -565,7 +584,9 @@ export async function buildDesktopShotPayload(
       ?? data.quote?.listingExchangeName
       ?? data.quote?.exchangeName
       ?? "";
-    const fiveYearsDaily = resolved.pane.id === "realized-vol" || resolved.pane.id === "iv-history" || resolved.pane.id === "macro-day";
+    const fiveYearsDaily = resolved.pane.id === "realized-vol" || resolved.pane.id === "iv-history" || resolved.pane.id === "macro-day"
+      // KELLY's History tab reads monthly returns off five years of daily closes.
+      || resolved.pane.id === "kelly-sizer";
     if (fiveYearsDaily || resolved.pane.id === "iv-screen" || resolved.pane.id === "short-watch"
       || resolved.pane.id === "backtest" || resolved.pane.id === OPTIONS_PANE_ID) {
       // Generic 5Y snapshots can contain weekly bars. The snapshot provider
@@ -600,15 +621,19 @@ export async function buildDesktopShotPayload(
       // letting the pane fetch them.
       data = await withShotPriceHistory(context, symbol, entry.tickerFile, data);
     }
-    tickers.push(entry.tickerFile ?? createFallbackTicker(symbol, data, context));
+    tickers.push(entry.tickerFile ?? await createFallbackTicker(symbol, data, context));
     financials.push([symbol, data]);
     if (resolved.pane.id === "time-sales") {
       tapeSnapshots.push([entry.instrument.symbol, exchange, await fetchTape(entry.instrument.symbol, exchange)]);
     }
     if (includeOptionsChains && context.dataProvider.getOptionsChain) {
+      // A future with no chain of its own is the pane's to explain (the listed alternative), not a failed shot.
       const chain = await context.dataProvider.getOptionsChain(entry.instrument.symbol, exchange, undefined,
-        context.refresh ? { cacheMode: "refresh" } : undefined);
-      optionsChains.push([symbol, chain]);
+        context.refresh ? { cacheMode: "refresh" } : undefined).catch((error: unknown) => {
+        if (isOptionsUnavailableError(error)) return null;
+        throw error;
+      });
+      if (chain) optionsChains.push([symbol, chain]);
     }
   }
   layout.instances[0] = shotInstance;
@@ -666,17 +691,6 @@ async function collectShotSymbolsWithCollections(
   return [...new Set([...symbols, ...members])];
 }
 
-function resolveShotTheme(requested: string): string {
-  const normalized = requested.trim().toLowerCase().replace(/[\s_]+/g, "-");
-  const ids = getThemeIds();
-  const match = ids.find((id) => id.toLowerCase() === normalized)
-    ?? ids.find((id) => getTheme(id).name.toLowerCase().replace(/[\s_]+/g, "-") === normalized);
-  if (!match) {
-    throw new Error(`Unknown theme "${requested}". Available themes: ${ids.join(", ")}`);
-  }
-  return match;
-}
-
 function shotPriceHistoryRange(resolved: ResolvedPaneFunction): TimeRange | null {
   // Captured history is authoritative, and the generic 5Y capture is weekly.
   if (resolved.pane.id === "quote-monitor") return getQuoteMonitorPaneSettings(resolved.instance.settings).chartPeriod;
@@ -691,6 +705,60 @@ function shotPriceHistoryRange(resolved: ResolvedPaneFunction): TimeRange | null
   }
 }
 
+/** The bridge, keeping every quote it serves the page: what a pane that loads its own quotes (WEI) shows. */
+function recordBridgedQuotes(bridge: DesktopPaneShotBridge): { bridge: DesktopPaneShotBridge; quotes: Quote[] } {
+  const quotes: Quote[] = [];
+  const keep = (value: unknown) => {
+    if (isRecord(value) && typeof value.symbol === "string" && typeof value.price === "number") quotes.push(value as unknown as Quote);
+  };
+  return {
+    quotes,
+    bridge: {
+      ...bridge,
+      async marketData(operation, args) {
+        const result = await bridge.marketData(operation, args);
+        if (operation === "getQuote") keep(result);
+        if (operation === "getQuotesBatch" && Array.isArray(result)) {
+          for (const entry of result) keep(isRecord(entry) ? entry.quote : null);
+        }
+        return result;
+      },
+    },
+  };
+}
+
+/**
+ * How current a capture's data is. A pane that says what its data is (its
+ * declared status, or a feed it publishes, such as OMON's chain or the news
+ * wire's delay) is taken at its word; otherwise the quotes it shows date it,
+ * with their delay and where their markets stand; otherwise what the
+ * rendered view carries, which may be nothing.
+ */
+function shotFreshness(
+  resolved: Pick<ResolvedPaneFunction, "pane">,
+  payload: Pick<DesktopPaneShotPayload, "financials" | "instrumentFinancials">,
+  render: Pick<DesktopPaneShotRenderResult, "semanticUi" | "footerText" | "rows">,
+  bridgedQuotes: readonly Quote[],
+  now = Date.now(),
+): ReportFreshness {
+  const declared = { ...resolved.pane.reportFreshness, ...renderedReportFreshness(render.semanticUi ?? []) };
+  const quotes = [
+    ...payload.financials.map(([, financials]) => financials.quote),
+    ...(payload.instrumentFinancials ?? []).map(({ financials }) => financials.quote),
+    ...bridgedQuotes,
+  ];
+  // A pane that publishes the observations behind its figures (FXC's rates) dates itself.
+  const observed = renderedReportObservations(render.semanticUi ?? []);
+  const quoted = declared.status || observed.length > 0
+    ? undefined
+    : quotesFreshness(quotes, declared.source ? { source: declared.source } : undefined, now);
+  return quoted ?? deriveRenderedFreshness(declared, {
+    footerText: render.footerText ?? "",
+    cellTimes: render.rows.flatMap((row) => row.cells.flatMap((cell) => (cell.instant ? [cell.instant] : []))),
+    observed,
+  }, now);
+}
+
 export async function renderDesktopShot({
   resolved,
   context,
@@ -701,6 +769,7 @@ export async function renderDesktopShot({
   theme,
   scale,
   watermark,
+  statusLine = false,
   options,
   captureImage = true,
 }: {
@@ -713,6 +782,8 @@ export async function renderDesktopShot({
   theme?: string | null;
   scale?: number;
   watermark?: string | null;
+  /** Draw the dated status line in the capture's footer. Reports and `--no-status` leave it out. */
+  statusLine?: boolean;
   options: Record<string, string | true>;
   captureImage?: boolean;
 }): Promise<PaneScreenshotResult> {
@@ -721,6 +792,7 @@ export async function renderDesktopShot({
   const previousSessionToken = apiClient.getSessionToken();
   let payload: DesktopPaneShotPayload;
   let render: DesktopPaneShotRenderResult;
+  let freshness: ReportFreshness | undefined;
   apiClient.setSessionToken(apiProxy.sessionToken);
   try {
     payload = await buildDesktopShotPayload(
@@ -734,16 +806,24 @@ export async function renderDesktopShot({
       scale ?? 1,
       watermark ?? null,
     );
+    if (statusLine && captureImage) payload.statusLine = true;
+    const recorded = recordBridgedQuotes(createDesktopShotBridge(context));
+    const shotPayload = payload;
     render = await renderDesktopPaneScreenshot(payload, outputPath, apiProxy, {
       captureImage,
-      bridge: createDesktopShotBridge(context),
+      bridge: recorded.bridge,
+      statusLine: (rendered) => {
+        freshness = shotFreshness(resolved, shotPayload, rendered, recorded.quotes);
+        return statusLineVariants(freshness);
+      },
     });
   } finally {
     apiClient.setSessionToken(previousSessionToken);
   }
   const renderedInstance = payload.config.layout.instances.find(({ instanceId }) => instanceId === payload.paneId);
   if (renderedInstance) resolved = { ...resolved, instance: renderedInstance };
-  return assessPaneScreenshot(resolved, payload, render, rawArg, outputPath);
+  const assessed = assessPaneScreenshot(resolved, payload, render, rawArg, outputPath);
+  return freshness ? { ...assessed, freshness } : assessed;
 }
 
 /** What a rendered capture shows, and whether it is fit to use. */
@@ -807,6 +887,7 @@ export function assessPaneScreenshot(
   const unusableReason = usable
     ? null
     : shotUnusableReasonFor(resolved, payload, render, unavailableSymbols, semanticMismatch);
+  const { notices } = renderedReportNotices(render.semanticUi ?? []);
   return {
     kind: "pane-screenshot",
     target: resolved.token,
@@ -827,6 +908,7 @@ export function assessPaneScreenshot(
     usable,
     unusableReason,
     dataEvidence,
+    ...(notices.length > 0 ? { notices } : {}),
     outputPath,
     render: {
       ...stripDesktopShotCredentials(render),

package/src/cli/registry.ts

@@ -149,6 +149,7 @@ export function createCliCommandContext(
   ownerId: string,
   registryOrPlugins: Pick<CliCommandRegistry, "plugins" | "externalPlugins"> | GloomPlugin[],
   cliOptions: CliGlobalOptions = DEFAULT_CLI_OPTIONS,
+  args: readonly string[] = [],
 ): CliCommandContext {
   const registry = Array.isArray(registryOrPlugins)
     ? { plugins: registryOrPlugins, externalPlugins: [] }
@@ -169,7 +170,7 @@ export function createCliCommandContext(
       renderStats,
       renderTable,
     },
-    printResult: (result, options) => printCliResult(result, cliOptions, options),
+    printResult: (result, options) => printCliResult(result, cliOptions, options, args),
     log: debugLog.createLogger(ownerId === "core" ? "cli" : ownerId),
   };
 }

package/src/cli/result.ts

@@ -7,13 +7,16 @@ import {
   statValueWidth,
   visibleLength,
   wrapText,
+  wrapToTerminal,
   type CliStatEntry,
   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";
+import { withSearchHints } from "./not-a-ticker";
 import { renderReportCsv, renderReportNdjson, type CliReportTables } from "./report-tables";
+import { windowRows, type RowWindow, type RowWindowOptions } from "./row-window";
 
 export interface CliResult<T = unknown> {
   data: T;
@@ -59,6 +62,17 @@ export interface CliResultRenderOptions<T = unknown, Row = Record<string, unknow
   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;
+  /** Text-mode line printed under the rows, such as where a listing stops. Not printed with no rows: say it in `empty`. */
+  footnote?: string;
+  /**
+   * The row key holding each row's date, which makes the rows a dated series:
+   * `--tail` keeps the newest rows whichever way the series runs, and a
+   * `--limit` that keeps the oldest says so, under the text table and as
+   * `metadata.rows` in JSON.
+   */
+  dateKey?: string;
+  /** How many rows to show when neither `--limit` nor `--tail` is given; every row when absent. */
+  defaultLimit?: number;
   /**
    * What CSV and NDJSON write instead of the rows: a report's tables as the
    * text view shows them, CSV with its `# section:` and closing `#` lines.
@@ -89,14 +103,28 @@ const KEY_ACRONYMS: Record<string, string> = {
   usd: "USD",
 };
 
-function applyLimit<T>(data: T, limit?: number): T {
-  if (!Array.isArray(data) || limit == null) return data;
-  return data.slice(0, limit) as T;
+function rowWindowOptions(options: CliGlobalOptions, renderOptions: Pick<CliResultRenderOptions, "defaultLimit">): RowWindowOptions {
+  return options.tail != null ? { tail: options.tail } : { limit: options.limit ?? renderOptions.defaultLimit };
+}
+
+function windowed<Row>(
+  rows: readonly Row[],
+  options: CliGlobalOptions,
+  renderOptions: Pick<CliResultRenderOptions, "dateKey" | "defaultLimit">,
+): RowWindow<Row> {
+  const { dateKey } = renderOptions;
+  const dateOf = dateKey ? (row: Row) => (isPlainObject(row) ? row[dateKey] : undefined) : undefined;
+  return windowRows(rows, rowWindowOptions(options, renderOptions), dateOf);
+}
+
+function asRows<T, Row>(data: T, rows?: (data: T) => Row[]): Row[] {
+  return rows ? rows(data) : (Array.isArray(data) ? data : [data]) as Row[];
 }
 
-function asRows<T, Row>(data: T, limit?: number, rows?: (data: T) => Row[]): Row[] {
-  const resolvedRows = rows ? rows(data) : (Array.isArray(data) ? data : [data]) as Row[];
-  return limit == null ? resolvedRows : resolvedRows.slice(0, limit);
+/** What JSON says about rows the window cut, under `metadata.rows`. */
+function cutMetadata(window: RowWindow<unknown>) {
+  if (window.rows.length >= window.total) return null;
+  return { shown: window.rows.length, total: window.total, kept: window.kept, ...(window.note ? { note: window.note } : {}) };
 }
 
 function isPlainObject(value: unknown): value is Record<string, unknown> {
@@ -277,6 +305,7 @@ function renderTextTable<Row extends Record<string, unknown>>(
       width: column.width,
       maxWidth: column.maxWidth,
       optional: column.optional,
+      dropPriority: column.dropPriority,
       shrink: column.shrink,
     })),
     cells.map((row) => shown.map(({ index }) => row[index]!)),
@@ -310,7 +339,7 @@ function overflowsTerminal<Row extends Record<string, unknown>>(rows: Row[]): bo
 
 /** 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));
+  return cliStyles.muted(wrapToTerminal(formatFreshnessLine(freshness)));
 }
 
 export function serializeCliResult<T, Row extends Record<string, unknown> = Record<string, unknown>>(
@@ -321,11 +350,13 @@ export function serializeCliResult<T, Row extends Record<string, unknown> = Reco
   const { freshness, ...rest } = result;
   if (options.format === "json") {
     const columns = serializeColumns(renderOptions.columns);
+    const window = Array.isArray(result.data) ? windowed(result.data as unknown[], options, renderOptions) : null;
+    const cut = window ? cutMetadata(window) : null;
     const envelope: CliResultJsonEnvelope<T> = {
       ok: true,
       ...rest,
-      ...(freshness ? { metadata: { ...rest.metadata, freshness } } : {}),
-      data: applyLimit(result.data, options.limit),
+      ...(freshness || cut ? { metadata: { ...rest.metadata, ...(freshness ? { freshness } : {}), ...(cut ? { rows: cut } : {}) } } : {}),
+      data: window ? window.rows as T : result.data,
       ...(columns?.length ? { columns } : {}),
     };
     return JSON.stringify(envelope, null, 2);
@@ -342,7 +373,8 @@ function serializeCliRows<T, Row extends Record<string, unknown>>(
 ): string {
   if (renderOptions.tables && options.format === "csv") return renderReportCsv(renderOptions.tables);
   if (renderOptions.tables && options.format === "ndjson") return renderReportNdjson(renderOptions.tables);
-  const rows = asRows(result.data, options.limit, renderOptions.rows);
+  const window = windowed(asRows(result.data, renderOptions.rows), options, renderOptions);
+  const rows = window.rows;
   if (options.format === "ndjson") {
     return rows.map((row) => JSON.stringify(row)).join("\n");
   }
@@ -357,7 +389,9 @@ function serializeCliRows<T, Row extends Record<string, unknown>>(
   if (rows.length === 0) {
     return withHeading(summary || cliStyles.muted(renderOptions.empty ?? "No results."));
   }
-  const body = renderTextRows(rows as Row[], result.data, renderOptions);
+  const table = renderTextRows(rows as Row[], result.data, renderOptions);
+  const notes = [window.note, renderOptions.footnote].filter((note): note is string => !!note);
+  const body = [table, ...notes.map((note) => cliStyles.muted(note))].join("\n");
   return withHeading(summary ? `${summary}\n\n${body}` : body);
 }
 
@@ -382,9 +416,12 @@ export function printCliResult<T, Row extends Record<string, unknown> = Record<s
   result: CliResult<T>,
   options: CliGlobalOptions,
   renderOptions: CliResultRenderOptions<T, Row> = {},
+  args: readonly string[] = [],
 ): void {
   if (options.quiet && options.format === "text") return;
-  const output = serializeCliResult(result, options, renderOptions);
+  // JSON keeps the router's own words; everything else is for a person, so a "Not a ticker" gets its hint.
+  const hinted = (text: string) => options.format === "json" ? text : withSearchHints(text, args);
+  const output = hinted(serializeCliResult(result, options, renderOptions));
   // Bun's console writer can truncate a large pipe write after stdout has been
   // initialized. The stream queues the remaining bytes until the reader drains.
   if (output) process.stdout.write(`${output}\n`);
@@ -392,7 +429,7 @@ export function printCliResult<T, Row extends Record<string, unknown> = Record<s
   // rows, so a warning goes to stderr, out of a file the rows are piped into.
   if (options.format !== "json" && !options.quiet) {
     for (const warning of result.warnings ?? []) {
-      console.error(`${cliStyles.warning("warning:")} ${warning}`);
+      console.error(`${cliStyles.warning("warning:")} ${hinted(warning)}`);
     }
   }
 }

package/src/cli/row-window.ts

@@ -0,0 +1,76 @@
+/**
+ * Which rows `--limit` and `--tail` keep, for every command that prints a
+ * list. `--limit n` keeps the first n rows as printed. `--tail n` keeps the
+ * newest n rows of a dated series, whichever way it runs (the first n of a
+ * newest-first series, the last n of an oldest-first one), and the last n of
+ * any other list. The kept rows stay in their printed order.
+ */
+export interface RowWindowOptions {
+  limit?: number;
+  tail?: number;
+}
+
+export interface RowWindow<Row> {
+  rows: Row[];
+  /** How many rows there were before the cut. */
+  total: number;
+  /** The end of a dated series the cut kept; null when nothing was cut or the rows are not a dated series. */
+  kept: "oldest" | "newest" | null;
+  /**
+   * Said when `--limit` cut an oldest-first series, which reads as the latest
+   * rows but is the earliest: "showing the oldest 2 of 252 rows; --tail 2 for
+   * the latest". Null otherwise.
+   */
+  note: string | null;
+}
+
+function timeOf(value: unknown): number | null {
+  if (value instanceof Date) return Number.isFinite(value.getTime()) ? value.getTime() : null;
+  if (typeof value === "number") return Number.isFinite(value) ? value : null;
+  if (typeof value !== "string" || !value.trim()) return null;
+  const time = Date.parse(value);
+  return Number.isFinite(time) ? time : null;
+}
+
+function firstTime<Row>(rows: readonly Row[], dateOf: (row: Row) => unknown, fromEnd: boolean): number | null {
+  for (let step = 0; step < rows.length; step += 1) {
+    const time = timeOf(dateOf(rows[fromEnd ? rows.length - 1 - step : step]!));
+    if (time != null) return time;
+  }
+  return null;
+}
+
+/** Which way a dated series runs, from its first and last dated rows; null when it is undated or spans one instant. */
+function seriesOrder<Row>(rows: readonly Row[], dateOf: (row: Row) => unknown): "ascending" | "descending" | null {
+  const first = firstTime(rows, dateOf, false);
+  const last = firstTime(rows, dateOf, true);
+  if (first == null || last == null || first === last) return null;
+  return first < last ? "ascending" : "descending";
+}
+
+/** The rows `options` keep. `dateOf` reads a row's date, which makes the rows a dated series. */
+export function windowRows<Row>(
+  rows: readonly Row[],
+  options: RowWindowOptions,
+  dateOf?: (row: Row) => unknown,
+): RowWindow<Row> {
+  const total = rows.length;
+  const count = options.tail ?? options.limit;
+  if (count == null || count >= total) return { rows: [...rows], total, kept: null, note: null };
+  const order = dateOf ? seriesOrder(rows, dateOf) : null;
+  if (options.tail != null) {
+    return {
+      rows: order === "descending" ? rows.slice(0, count) : rows.slice(total - count),
+      total,
+      kept: order ? "newest" : null,
+      note: null,
+    };
+  }
+  const kept = order === "ascending" ? "oldest" : order === "descending" ? "newest" : null;
+  return {
+    rows: rows.slice(0, count),
+    total,
+    kept,
+    note: kept === "oldest" ? `showing the oldest ${count} of ${total} rows; --tail ${count} for the latest` : null,
+  };
+}

package/src/cli/scroll-truncation.ts

@@ -0,0 +1,34 @@
+/** A scrolling box as the page measures it. */
+export interface ScrollBoxMetrics {
+  scrollTop: number;
+  scrollHeight: number;
+  clientHeight: number;
+  scrollLeft: number;
+  scrollWidth: number;
+  clientWidth: number;
+  /** The box draws a scrollbar on that axis, which says it overflows even when the measures cannot. */
+  scrollbarY: boolean;
+  scrollbarX: boolean;
+}
+
+/**
+ * What a capture leaves out of a scrolling box, naming the side: a chain
+ * centred on the money is cut above and below, a list at its top only below.
+ * Self-contained so the screenshot runner can evaluate it in the browser.
+ */
+export function scrollTruncationReasons(box: ScrollBoxMetrics): string[] {
+  const reasons: string[] = [];
+  const cut = (offset: number, content: number, viewport: number, flagged: boolean, noun: string, sides: readonly [string, string, string, string]) => {
+    if (!flagged && !(content > viewport + 1)) return;
+    // One pixel either way is subpixel layout, not a hidden row.
+    const before = offset > 1;
+    const after = offset + viewport < content - 1;
+    // A drawn scrollbar over content that measures as fitting (a list that loads more) cannot say which side.
+    reasons.push(before || after
+      ? `${noun} ${before && after ? sides[2] : before ? sides[0] : sides[1]} the rendered viewport are cut`
+      : `${noun} ${sides[3]} the rendered viewport may be cut`);
+  };
+  cut(box.scrollTop, box.scrollHeight, box.clientHeight, box.scrollbarY, "rows", ["above", "below", "above and below", "above or below"]);
+  cut(box.scrollLeft, box.scrollWidth, box.clientWidth, box.scrollbarX, "columns", ["left of", "right of", "left and right of", "left or right of"]);
+  return reasons;
+}