gloomberb 0.16.2 → 0.16.4

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

@@ -18,8 +18,18 @@ import type {
   HeadlessSeriesResult,
   HeadlessSnapshotResult,
 } from "../../types/plugin";
-import { cliStyles, renderSection, renderStats, renderTable } from "../../utils/cli-output";
+import { cliStyles, renderSection, renderStats, renderTable, wrapToTerminal } from "../../utils/cli-output";
 import { humanizeCliKey } from "../result";
+import {
+  exportEntriesTable,
+  exportNumber,
+  exportRowsTable,
+  float32Shortest,
+  reportFooterLines,
+  type CliReportTable,
+  type CliReportTables,
+} from "../report-tables";
+import { labelWithUnit } from "../../utils/display-number";
 import { observationDate } from "../../time-series/price-comparison";
 import type { ResolvedSeries } from "../../time-series/types";
 import type { PaneFunctionReport } from "./report";
@@ -316,20 +326,6 @@ function displayNumber(value: number): string {
   return String(float32Shortest(value) ?? Number(value.toPrecision(12)));
 }
 
-/**
- * Some feeds store prices as float32, so 338.93 arrives as 338.929992676. A value
- * that is exactly a float32 prints as the shortest decimal that rounds back to it,
- * which leaves genuine doubles (never exactly float32 unless short) untouched.
- */
-function float32Shortest(value: number): number | null {
-  if (Math.fround(value) !== value) return null;
-  for (let digits = 1; digits <= 9; digits += 1) {
-    const candidate = Number(value.toPrecision(digits));
-    if (Math.fround(candidate) === value) return candidate;
-  }
-  return null;
-}
-
 function displayTime(time: number): string {
   if (!Number.isFinite(time)) return "-";
   return formatUtcTime(new Date(time));
@@ -337,14 +333,36 @@ function displayTime(time: number): string {
 
 const CALENDAR_RESOLUTIONS = new Set(["1d", "1wk", "1mo"]);
 
-/** Session bars print the trading date the chart and comparison notice use, not the bar's open instant. */
-function seriesPointDate(series: HeadlessSeries, date: HeadlessSeries["points"][number]["date"]): string {
-  const time = date instanceof Date ? date.getTime() : typeof date === "number" ? date : Date.parse(date);
-  if (!Number.isFinite(time)) return typeof date === "string" ? date : "-";
+type SeriesPointDate = HeadlessSeries["points"][number]["date"];
+
+function seriesPointTime(date: SeriesPointDate): number {
+  return date instanceof Date ? date.getTime() : typeof date === "number" ? date : Date.parse(date);
+}
+
+function isDateOnly(date: SeriesPointDate): boolean {
+  return typeof date === "string" && /^\d{4}-\d{2}-\d{2}$/.test(date);
+}
+
+/** Session bars are dated by the trading date the chart and comparison notice use, not the bar's open instant. */
+function calendarSeries(series: HeadlessSeries): (HeadlessSeries & Partial<Pick<ResolvedSeries, "historyResolution" | "timeBasis">>) | null {
   const resolved = series as HeadlessSeries & Partial<Pick<ResolvedSeries, "historyResolution" | "timeBasis">>;
-  return resolved.historyResolution && CALENDAR_RESOLUTIONS.has(resolved.historyResolution)
-    ? observationDate(time, resolved)
-    : formatUtcTime({ time, dateOnly: typeof date === "string" && /^\d{4}-\d{2}-\d{2}$/.test(date) });
+  return resolved.historyResolution && CALENDAR_RESOLUTIONS.has(resolved.historyResolution) ? resolved : null;
+}
+
+function seriesPointDate(series: HeadlessSeries, date: SeriesPointDate): string {
+  const time = seriesPointTime(date);
+  if (!Number.isFinite(time)) return typeof date === "string" ? date : "-";
+  const calendar = calendarSeries(series);
+  return calendar ? observationDate(time, calendar) : formatUtcTime({ time, dateOnly: isDateOnly(date) });
+}
+
+/** The same date for a spreadsheet: the trading date, the calendar date, or the ISO instant. */
+function seriesPointExportDate(series: HeadlessSeries, date: SeriesPointDate): string {
+  const time = seriesPointTime(date);
+  if (!Number.isFinite(time)) return typeof date === "string" ? date : "";
+  const calendar = calendarSeries(series);
+  if (calendar) return observationDate(time, calendar);
+  return isDateOnly(date) ? date as string : new Date(time).toISOString().replace(".000Z", "Z");
 }
 
 function seriesValue(series: HeadlessSeries, value: number | null): string {
@@ -364,6 +382,7 @@ function renderRows(
       header: humanizeCliKey(column.header),
       align: column.align,
       width: column.width,
+      shrink: column.shrink,
     })),
     rows.map((row) => columns.map((column) => {
       const value = row[column.key];
@@ -377,6 +396,10 @@ function renderEntries(entries: HeadlessPaneEntry[]): string {
   return renderStats(entries.map((entry) => [entry.label, entry.formatted ?? displayValue(entry.value)]));
 }
 
+function statisticsEntries(stats: NonNullable<HeadlessSeriesResult["stats"]>): HeadlessPaneEntry[] {
+  return Array.isArray(stats) ? stats : Object.entries(stats).map(([label, value]) => ({ label, value }));
+}
+
 function renderBundle(
   definition: HeadlessPaneDefinition,
   result: HeadlessBundleResult,
@@ -412,14 +435,118 @@ function renderSeries(result: HeadlessSeriesResult): string[] {
   ];
   const lines = [renderRows(rows, columns, undefined)];
   if (result.stats) {
-    const entries = Array.isArray(result.stats)
-      ? result.stats
-      : Object.entries(result.stats).map(([label, value]) => ({ label, value }));
-    lines.push("", renderSection("Statistics"), renderEntries(entries));
+    lines.push("", renderSection("Statistics"), renderEntries(statisticsEntries(result.stats)));
   }
   return lines;
 }
 
+/** The headers the text table prints. */
+function displayedColumns(columns: HeadlessPaneColumn[]): HeadlessPaneColumn[] {
+  return columns.map((column) => ({ ...column, header: humanizeCliKey(column.header) }));
+}
+
+const SERIES_FIELDS = ["value", "open", "high", "low", "close", "volume"] as const;
+
+/** Every point of a series: its date (the trading date for session bars) and its values, in the series' unit. */
+function seriesTable(series: HeadlessSeries): CliReportTable {
+  const fields = SERIES_FIELDS.filter((field) => series.points.some((point) => point[field] != null));
+  const unit = series.unit?.trim() ?? "";
+  const dates = series.points.map((point) => seriesPointExportDate(series, point.date));
+  const header = (field: (typeof SERIES_FIELDS)[number]) => {
+    const name = `${field[0]!.toUpperCase()}${field.slice(1)}`;
+    return field === "volume" ? name : labelWithUnit(name, unit);
+  };
+  return {
+    title: series.label,
+    columns: [dates.every((date) => date.length <= 10) ? "Date" : "Time", ...fields.map(header)],
+    rows: series.points.map((point, index) => [
+      dates[index]!,
+      ...fields.map((field) => {
+        const value = point[field];
+        return typeof value === "number" && Number.isFinite(value) ? exportNumber(value) : "";
+      }),
+    ]),
+  };
+}
+
+/** What a report leaves out, for the closing `# incomplete` line. */
+function incompleteDetail(
+  result: HeadlessPaneResult,
+  status: { complete: boolean; unavailableSymbols: string[] },
+): boolean | string {
+  if (status.complete) return false;
+  const requested = result.metadata?.requested;
+  const available = result.metadata?.available;
+  if (typeof requested === "number" && typeof available === "number" && available < requested) {
+    return `${available} of ${requested} available`;
+  }
+  return status.unavailableSymbols.length > 0 ? `no data for ${status.unavailableSymbols.join(", ")}` : true;
+}
+
+function textNotices(result: HeadlessPaneResult): string[] {
+  const notices = result.metadata?.notices;
+  if (!Array.isArray(notices)) return [];
+  return [...new Set(notices.filter((notice): notice is string => typeof notice === "string" && notice.trim().length > 0))];
+}
+
+/**
+ * The tables of a headless report for `--csv` and `--ndjson`, with the text
+ * view's columns: a rows or snapshot report is one table, a bundle one per
+ * section (key/value sections as `Metric,Value`), a series report one per
+ * series with every point, then its statistics. The footer carries the text
+ * view's closing line, notices, notes and errors.
+ */
+export function headlessReportTables(
+  definition: HeadlessPaneDefinition,
+  result: HeadlessPaneResult,
+  args: HeadlessPaneLoadArgs,
+  fallbackTitle: string,
+  freshness: ReportFreshness,
+  status: { complete: boolean; unavailableSymbols: string[] },
+): CliReportTables {
+  const title = reportTitle(definition, args, result, fallbackTitle);
+  let tables: CliReportTable[];
+  switch (definition.shape) {
+    case "rows": {
+      const rowsResult = result as HeadlessPaneResult & { rows: HeadlessPaneRow[]; columns?: HeadlessPaneColumn[] };
+      const columns = displayedColumns(columnsFor(rowsResult.rows, rowsResult.columns, definition.columns));
+      tables = [exportRowsTable(title, columns, rowsResult.rows)];
+      break;
+    }
+    case "bundle":
+      tables = (result as HeadlessBundleResult).sections.map((section) => (
+        "rows" in section && section.rows
+          ? exportRowsTable(section.title, displayedColumns(columnsFor(section.rows, section.columns, definition.columns)), section.rows)
+          : exportEntriesTable(section.title, section.entries)
+      ));
+      break;
+    case "series": {
+      const seriesResult = result as HeadlessSeriesResult;
+      tables = seriesResult.series.map(seriesTable);
+      if (seriesResult.stats) tables.push(exportEntriesTable("Statistics", statisticsEntries(seriesResult.stats)));
+      break;
+    }
+    case "snapshot": {
+      const snapshot = result as HeadlessSnapshotResult;
+      tables = [exportRowsTable(title, displayedColumns(columnsFor(snapshot.items, undefined, definition.columns)), snapshot.items)];
+      break;
+    }
+    default: {
+      const _exhaustive: never = definition.shape;
+      return _exhaustive;
+    }
+  }
+  return {
+    tables,
+    footer: reportFooterLines({
+      freshness,
+      incomplete: incompleteDetail(result, status),
+      errors: result.errors,
+      notes: [...textNotices(result), ...(result.notes ?? [])],
+    }),
+  };
+}
+
 function reportTitle(
   definition: HeadlessPaneDefinition,
   args: HeadlessPaneLoadArgs,
@@ -433,8 +560,8 @@ function reportTitle(
 /** 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}`)];
+    ? [cliStyles.warning(wrapToTerminal(`${label}: ${messages[0]}`))]
+    : [cliStyles.warning(`${label}:`), ...messages.map((message) => wrapToTerminal(`  ${message}`))];
 }
 
 /**
@@ -450,11 +577,8 @@ export function renderHeadlessPaneText(
   freshness: ReportFreshness = deriveHeadlessFreshness(definition, result),
 ): string {
   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))];
-    if (textNotices.length) lines.push(...textNotices, "");
-  }
+  const notices = textNotices(result);
+  if (notices.length) lines.push(...notices, "");
   switch (definition.shape) {
     case "rows": {
       const rowsResult = result as HeadlessPaneResult & { rows: HeadlessPaneRow[]; columns?: HeadlessPaneColumn[] };
@@ -480,7 +604,7 @@ export function renderHeadlessPaneText(
   }
   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");
+  return [lines.join("\n").trimEnd(), "", cliStyles.muted(wrapToTerminal(formatFreshnessLine(freshness)))].join("\n");
 }
 
 function resultRowCount(definition: HeadlessPaneDefinition, result: HeadlessPaneResult): number {
@@ -513,6 +637,7 @@ export async function buildHeadlessFunctionReport(
   const unavailableSymbols = loaded.result.unavailableSymbols ?? (rowCount === 0 ? symbols : []);
   const serialized = serializeHeadlessPaneResult(loaded.definition, loaded.result);
   const freshness = deriveHeadlessFreshness(loaded.definition, loaded.result);
+  const complete = loaded.result.complete !== false && unavailableSymbols.length === 0 && !loaded.result.errors?.length;
   return {
     data: {
       kind: loaded.definition.shape,
@@ -522,7 +647,7 @@ export async function buildHeadlessFunctionReport(
       options: resolved.options,
       rowCount,
       empty: rowCount === 0,
-      complete: loaded.result.complete !== false && unavailableSymbols.length === 0 && !loaded.result.errors?.length,
+      complete,
       unavailableSymbols,
       ...serialized,
       freshness,
@@ -534,5 +659,13 @@ export async function buildHeadlessFunctionReport(
       resolved.label,
       freshness,
     ),
+    tables: headlessReportTables(
+      loaded.definition,
+      loaded.result,
+      loaded.args,
+      resolved.label,
+      freshness,
+      { complete, unavailableSymbols },
+    ),
   };
 }

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

@@ -23,6 +23,7 @@ import {
 import { accessGateStatus, incompleteReportGateMessage } from "./access-gate";
 import { withPersistedCloudSession } from "./cloud-session";
 import { loadForListing } from "../listing-arg";
+import { selectReportTables } from "../report-tables";
 
 async function withPaneRuntime<T>(
   ctx: CliCommandContext,
@@ -33,7 +34,7 @@ async function withPaneRuntime<T>(
     registry: PaneFunctionCatalog;
     resolved: ResolvedPaneFunction;
   }) => Promise<T>,
-  settings: { strictHeadlessOptions?: boolean } = {},
+  settings: { strictHeadlessOptions?: boolean; tableSection?: boolean } = {},
 ): Promise<T> {
   return withMarketData(ctx, async (market) => {
     const context: MarketContext = ctx.cliOptions.refresh ? { ...market, refresh: true } : market;
@@ -59,6 +60,11 @@ export async function runPaneFunction(args: string[], ctx: CliCommandContext) {
           + `Use "gloomberb catalog ${resolved.token}" to inspect readiness.`,
         );
       }
+      const tabular = ctx.cliOptions.format === "csv" || ctx.cliOptions.format === "ndjson";
+      if (resolved.tableSection !== undefined && !tabular) {
+        throw new Error("--section picks one table of --csv or --ndjson output.");
+      }
+      if (resolved.tableSection === true) throw new Error("--section needs a section title or number.");
       // A report that fails or comes back empty for an exchange the symbol is not listed on says so.
       const report = await withPersistedCloudSession(
         context,
@@ -82,8 +88,9 @@ export async function runPaneFunction(args: string[], ctx: CliCommandContext) {
       }
       ctx.printResult({ data: report.data }, {
         text: () => report.text,
+        ...(tabular ? { tables: selectReportTables(report.tables, resolved.tableSection) } : {}),
       });
-    }, { strictHeadlessOptions: true });
+    }, { strictHeadlessOptions: true, tableSection: true });
   });
 }
 
@@ -111,6 +118,7 @@ export async function runPaneScreenshot(args: string[], ctx: CliCommandContext)
         theme: parsed.theme,
         scale: parsed.scale,
         watermark: parsed.watermark,
+        statusLine: parsed.status !== false,
         options: parsed.options,
       });
       if (parsed.requireBotSafe && !result.usable) {
@@ -130,7 +138,9 @@ export async function runPaneScreenshot(args: string[], ctx: CliCommandContext)
             ["Rows", String(data.rowCount)],
             ["Status", issues.length > 0 ? cliStyles.warning(issues.join(", ")) : cliStyles.success("complete")],
           ];
+          if (data.render.statusLine) stats.push(["Status line", data.render.statusLine]);
           if (data.unusableReason) stats.push(["Reason", data.unusableReason]);
+          if (data.notices?.length) stats.push(["Notes", data.notices.join(" ")]);
           if (data.unavailableSymbols.length > 0) stats.push(["No data for", data.unavailableSymbols.join(", ")]);
           if (data.render.emptyStateMarkers.length > 0) stats.push(["Empty states", data.render.emptyStateMarkers.join(", ")]);
           if (data.render.missingExpectedText.length > 0) stats.push(["Missing text", data.render.missingExpectedText.join(", ")]);

package/src/cli/pane-functions/market-session.ts

@@ -0,0 +1,133 @@
+import { canonicalExchange, isUsListingExchange } from "../../utils/exchanges";
+import {
+  activeUsMarketSession,
+  isAlwaysOpenExchange,
+  isRegularSessionTime,
+  latestRegularSessionClose,
+  latestRegularSessionOpen,
+  nextRegularSessionOpen,
+} from "../../market-data/market/freshness";
+import { currentFxClosureStart } from "../../utils/fx-market-hours";
+import { zonedDateKey } from "../../utils/zoned-date-time";
+import type { ReportTime } from "../../utils/utc-time";
+
+/** Where the venues behind a quote report stand, as a report says it after the delay. */
+type ReportMarketState = "open" | "pre-market" | "after-hours" | "closed";
+
+export interface ReportMarket {
+  state: ReportMarketState;
+  /** While no venue is in its regular session: the next regular open of the first to open, when its calendar is known. */
+  reopensAt?: string;
+  /** That open's date at its venue, so a Monday open in Sydney reads Monday. */
+  reopensOn?: string;
+}
+
+/** One dated row of a quote report: the venue it trades on and the session its source reports. */
+export interface SessionObservation {
+  exchange: string;
+  marketState?: string;
+  time: ReportTime | null;
+}
+
+interface VenueSession {
+  state: ReportMarketState | "always";
+  next?: { date: string; open: number };
+  /** The latest regular session that has closed: its local date and open. */
+  last?: { date: string; open: number | null };
+  timeZone?: string;
+}
+
+const CLOSED_STATES = new Set(["CLOSED", "PREPRE", "POSTPOST"]);
+
+/**
+ * A venue's session now, from its calendar (weekends and published holidays),
+ * or from the state its source reports when the app has no calendar for it,
+ * such as an index publisher or a futures exchange. Null when neither says.
+ */
+function venueSession(exchange: string, marketState: string | undefined, now: number): VenueSession | null {
+  if (isAlwaysOpenExchange(exchange)) return { state: "always" };
+  const next = nextRegularSessionOpen(exchange, now);
+  if (next) {
+    const { timeZone } = next;
+    const latestClose = latestRegularSessionClose(exchange, now);
+    const last = latestClose ? { date: latestClose.date, open: latestRegularSessionOpen(exchange, latestClose.close) } : undefined;
+    if (isRegularSessionTime(exchange, now)) return { state: "open", timeZone };
+    if (isUsListingExchange(exchange)) {
+      const today = zonedDateKey(now, timeZone);
+      const session = activeUsMarketSession(now);
+      if (session === "PRE" && next.date === today) return { state: "pre-market", next, last, timeZone };
+      if (session === "POST" && last?.date === today) return { state: "after-hours", next, last, timeZone };
+    }
+    return { state: "closed", next, last, timeZone };
+  }
+  if (marketState === "REGULAR") return { state: "open" };
+  if (marketState === "PRE") return { state: "pre-market" };
+  if (marketState === "POST") return { state: "after-hours" };
+  if (marketState && CLOSED_STATES.has(marketState)) return { state: "closed" };
+  return null;
+}
+
+/** The venue spot FX pairs trade on. It has no session calendar here; its week is in `fx-market-hours`. */
+const FX_VENUE = "CCY";
+const DAY_MS = 24 * 60 * 60_000;
+
+/**
+ * The newest observation is its venue's latest close: the venue has not
+ * opened since, and the print is from that session's day, after its open (an
+ * after-hours print of that day counts). Returns that session's local date.
+ */
+function closeDateOf(observation: SessionObservation, session: VenueSession, now: number): string | null {
+  const time = observation.time;
+  if (!time || time.dateOnly) return null;
+  // FX closes once a week, Friday 17:00 New York time, and its trading day turns
+  // at 17:00: a print from that last day, or a quiet tick over the weekend, is
+  // that Friday's close, not the day it happens to be stamped with.
+  const weekClose = canonicalExchange(observation.exchange) === FX_VENUE ? currentFxClosureStart(now) : null;
+  if (weekClose != null) return time.time >= weekClose - DAY_MS ? zonedDateKey(weekClose - 1, "America/New_York") : null;
+  if (session.last && session.timeZone) {
+    if (session.last.open != null && time.time < session.last.open) return null;
+    return zonedDateKey(time.time, session.timeZone) === session.last.date ? session.last.date : null;
+  }
+  // No calendar: the source says the session is over, and the print is dated in UTC.
+  return session.state === "closed" && !session.last ? new Date(time.time).toISOString().slice(0, 10) : null;
+}
+
+/**
+ * Where the markets behind a quote report stand now, and whether the newest
+ * observation is a close. Null market when the venues disagree (Tokyo open,
+ * New York closed), trade around the clock, or none can be placed; a report
+ * then says nothing rather than guess.
+ */
+export function reportMarketSession(
+  observations: readonly SessionObservation[],
+  now: number,
+): { market: ReportMarket | null; closeDate: string | null } {
+  const sessions = new Map<string, VenueSession>();
+  let newest: { observation: SessionObservation; session: VenueSession } | null = null;
+  for (const observation of observations) {
+    const exchange = canonicalExchange(observation.exchange);
+    if (!exchange) continue;
+    const key = `${exchange}:${observation.marketState ?? ""}`;
+    const session = sessions.get(key) ?? venueSession(exchange, observation.marketState, now);
+    if (!session) continue;
+    sessions.set(key, session);
+    if (observation.time && (!newest || observation.time.time > (newest.observation.time?.time ?? -Infinity))) {
+      newest = { observation, session };
+    }
+  }
+  const states = new Set([...sessions.values()].map((session) => session.state));
+  if (states.size !== 1 || states.has("always")) return { market: null, closeDate: null };
+  const state = [...states][0] as ReportMarketState;
+  const reopen = state === "closed" || state === "pre-market"
+    ? [...sessions.values()].reduce<{ date: string; open: number } | null>((first, session) => (
+      session.next && (!first || session.next.open < first.open) ? session.next : first
+    ), null)
+    : null;
+  return {
+    market: {
+      state,
+      ...(reopen ? { reopensAt: new Date(reopen.open).toISOString(), reopensOn: reopen.date } : {}),
+    },
+    closeDate: (state === "closed" || state === "pre-market") && newest ? closeDateOf(newest.observation, newest.session, now) : null,
+  };
+}

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

@@ -32,6 +32,8 @@ export interface ParsedPaneFunctionArgs {
   scale: number;
   /** Small label drawn in the pane title bar, e.g. a domain; null draws nothing. */
   watermark: string | null;
+  /** A screenshot carries its dated status line in the pane footer; `--no-status` sets this false. */
+  status?: boolean;
   requireBotSafe: boolean;
   /** The listing a one-ticker function's argument named, once `applyListingArgument` has resolved it. */
   listing?: ListingArg;
@@ -67,7 +69,7 @@ export function parseArgumentsOption(value: string): Record<string, string> {
   return pairs;
 }
 
-export function parsePaneFunctionArgs(args: string[], globalOptions: { limit?: number } = {}): ParsedPaneFunctionArgs {
+export function parsePaneFunctionArgs(args: string[], globalOptions: { limit?: number; tail?: number } = {}): ParsedPaneFunctionArgs {
   const positionals: string[] = [];
   const options: Record<string, string | true> = {};
   let outputPath: string | null = null;
@@ -76,6 +78,7 @@ export function parsePaneFunctionArgs(args: string[], globalOptions: { limit?: n
   let theme: string | null = null;
   let scale = 1;
   let watermark: string | null = null;
+  let status = true;
   let requireBotSafe = false;
 
   for (let index = 0; index < args.length; index += 1) {
@@ -94,6 +97,11 @@ export function parsePaneFunctionArgs(args: string[], globalOptions: { limit?: n
     const equalsIndex = raw.indexOf("=");
     const key = equalsIndex >= 0 ? raw.slice(0, equalsIndex) : raw;
     const inlineValue = equalsIndex >= 0 ? raw.slice(equalsIndex + 1) : undefined;
+    // A switch: the token after it is the function's argument, never its value.
+    if (normalizeOptionKey(key) === "noStatus" && inlineValue === undefined) {
+      status = false;
+      continue;
+    }
     const next = args[index + 1];
     const nextValue = inlineValue === undefined && next && !next.startsWith("--") ? args[++index] : true;
     const value: string | true = inlineValue ?? nextValue ?? true;
@@ -118,6 +126,7 @@ export function parsePaneFunctionArgs(args: string[], globalOptions: { limit?: n
       scale = parseScale(value);
     } else if (normalizedKey === "watermark" && value !== true) {
       watermark = value.trim() || null;
+
     } else if (normalizedKey === "arguments" && value !== true) {
       Object.assign(options, parseArgumentsOption(value));
     } else {
@@ -127,10 +136,12 @@ export function parsePaneFunctionArgs(args: string[], globalOptions: { limit?: n
 
   const target = positionals[0]?.trim() ?? "";
   const arg = positionals.slice(1).join(" ").trim();
-  // The outer CLI parser consumes --limit before fn/shot sees its arguments.
-  // Restore it for the pane's own schema and loader, including bounds checks.
+  // The outer CLI parser consumes --limit and --tail before fn/shot sees its arguments.
+  // Restore them for the pane's own schema and loader, including bounds checks,
+  // so a function without a tail option says so instead of ignoring it.
   if (globalOptions.limit != null) options.limit = String(globalOptions.limit);
-  return { target, arg, options, outputPath, width, height, theme, scale, watermark, requireBotSafe };
+  if (globalOptions.tail != null) options.tail = String(globalOptions.tail);
+  return { target, arg, options, outputPath, width, height, theme, scale, watermark, status, requireBotSafe };
 }
 
 export function parsePaneCatalogArgs(args: string[]): ParsedPaneCatalogArgs {

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

@@ -2,8 +2,9 @@ import type { MarketContext } from "../types";
 import type { NormalizedPaneFunctionOptions } from "./capabilities";
 import type { ResolvedPaneFunction } from "./resolver";
 import { buildHeadlessFunctionReport } from "./headless";
-import { appendDomReportFooter, buildDomFunctionReport } from "./dom";
+import { appendDomReportFooter, buildDomFunctionReport, domReportNote } from "./dom";
 import type { ReportFreshness } from "./freshness";
+import type { CliReportTables } from "../report-tables";
 
 export type PaneFunctionReportSource = "headless" | "dom";
 
@@ -29,6 +30,8 @@ interface PaneFunctionReportData {
 export interface PaneFunctionReport {
   data: PaneFunctionReportData;
   text: string;
+  /** What `--csv` and `--ndjson` write: the text view's tables as flat rows, and the closing `#` lines. */
+  tables: CliReportTables;
 }
 
 export function resolvePaneFunctionReportSource(
@@ -46,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.`);
   }
 
@@ -61,6 +68,10 @@ export async function buildFunctionReport(
       report.data.truncated === true,
       report.data.freshness,
     );
+    report.tables = {
+      ...report.tables,
+      footer: [...report.tables.footer, `note: ${domReportNote(elapsedMs, report.data.truncated === true)}`],
+    };
   }
   return report;
 }