@gloom-sh/terminal 0.18.5 → 0.19.0

package/src/plugins/builtin/scanner/flow-session.ts

@@ -0,0 +1,146 @@
+import {
+  apiClient,
+  type ScannerFlowSession,
+  type ScannerFlowSessionStrike,
+} from "../../../api-client";
+import { signalWithTimeout } from "../../../utils/async-deadline";
+import { formatFlowPremium } from "./flow-model";
+
+/**
+ * The session's recorded prints summed by the server under the pane's
+ * filters: the net-premium tide through the day and, for one name, its
+ * premium by expiry and strike. A print at the ask counts as bought and one at
+ * the bid as sold; mid or unknown prints count as neither (docs/usage.md, Options flow).
+ */
+export type FlowSessionLoader = (search: string, signal?: AbortSignal) => Promise<ScannerFlowSession>;
+
+export const loadFlowSession: FlowSessionLoader = (search, signal) =>
+  apiClient.getScannerFlowSession(search, signalWithTimeout(signal, 20_000));
+
+/** A summary is refetched this often while the tape is live; it is final once the session closes. */
+export const FLOW_SESSION_LIVE_REFRESH_MS = 60_000;
+
+/** One bucket of the tide: what it added, and the running totals through it. */
+export interface FlowTideRow {
+  at: number;
+  /** Call premium bought at the ask less call premium sold at the bid, through this bucket. */
+  netCalls: number;
+  netPuts: number;
+  /** Net calls less net puts through this bucket: the tide. */
+  net: number;
+  /** What this bucket added to the tide. */
+  change: number;
+  callAsk: number;
+  callBid: number;
+  putAsk: number;
+  putBid: number;
+}
+
+/** The tide bucket by bucket, oldest first, each row with the running totals through it. */
+export function flowTideRows(session: ScannerFlowSession | null | undefined): FlowTideRow[] {
+  let netCalls = 0;
+  let netPuts = 0;
+  return [...(session?.buckets ?? [])].sort((left, right) => left.at - right.at).map((bucket) => {
+    const calls = bucket.callAsk - bucket.callBid;
+    const puts = bucket.putAsk - bucket.putBid;
+    netCalls += calls;
+    netPuts += puts;
+    return {
+      at: bucket.at,
+      netCalls,
+      netPuts,
+      net: netCalls - netPuts,
+      change: calls - puts,
+      callAsk: bucket.callAsk,
+      callBid: bucket.callBid,
+      putAsk: bucket.putAsk,
+      putBid: bucket.putBid,
+    };
+  });
+}
+
+/** The buckets that moved the tide: one whose prints were all mid adds nothing to read. */
+export function flowTideMoves(rows: readonly FlowTideRow[]): FlowTideRow[] {
+  return rows.filter((row) => row.callAsk !== 0 || row.callBid !== 0 || row.putAsk !== 0 || row.putBid !== 0);
+}
+
+/**
+ * The running totals at every bucket from the first to the last, so a line
+ * holds flat through a quiet stretch instead of sloping across it.
+ */
+export function flowTidePoints(rows: readonly FlowTideRow[], bucketMs: number): Array<Pick<FlowTideRow, "at" | "netCalls" | "netPuts" | "net">> {
+  const points: Array<Pick<FlowTideRow, "at" | "netCalls" | "netPuts" | "net">> = [];
+  let previous: FlowTideRow | null = null;
+  for (const row of rows) {
+    if (previous && bucketMs > 0) {
+      for (let at = previous.at + bucketMs; at < row.at; at += bucketMs) {
+        points.push({ at, netCalls: previous.netCalls, netPuts: previous.netPuts, net: previous.net });
+      }
+    }
+    points.push({ at: row.at, netCalls: row.netCalls, netPuts: row.netPuts, net: row.net });
+    previous = row;
+  }
+  return points;
+}
+
+export interface FlowStrikeRow extends ScannerFlowSessionStrike {
+  id: string;
+  /** Net call premium less net put premium at this strike, by the same side rule as the tide. */
+  net: number;
+}
+
+export function flowStrikeRows(session: ScannerFlowSession | null | undefined): FlowStrikeRow[] {
+  return (session?.strikes ?? []).map((strike) => ({
+    ...strike,
+    id: `${strike.expiry}:${strike.strike}`,
+    net: strike.callAsk - strike.callBid - (strike.putAsk - strike.putBid),
+  }));
+}
+
+export type FlowStrikeSort = "expiry" | "strike" | "callPremium" | "callAsk" | "callBid" | "putPremium" | "putAsk" | "putBid" | "net";
+
+/** The breakdown in a column's order; ties fall back to expiry, then strike. */
+export function sortFlowStrikes(
+  rows: readonly FlowStrikeRow[],
+  column: FlowStrikeSort | null,
+  direction: "asc" | "desc",
+): FlowStrikeRow[] {
+  if (!column) return [...rows];
+  const sign = direction === "asc" ? 1 : -1;
+  const byContract = (left: FlowStrikeRow, right: FlowStrikeRow) =>
+    left.expiry.localeCompare(right.expiry) || left.strike - right.strike;
+  return [...rows].sort((left, right) => {
+    const primary = column === "expiry" ? left.expiry.localeCompare(right.expiry)
+      : column === "strike" ? left.strike - right.strike
+        : left[column] - right[column];
+    return primary * sign || byContract(left, right);
+  });
+}
+
+/** A premium that can go either way, with its sign: `+$1.2M`, `-$350K`. */
+export function formatSignedFlowPremium(value: number): string {
+  if (!Number.isFinite(value) || Math.abs(value) < 0.5) return "$0";
+  return `${value > 0 ? "+" : "-"}${formatFlowPremium(Math.abs(value))}`;
+}
+
+/** An expiry as the table reads it: `10/30`, with the year when it is not this one. */
+export function formatStrikeExpiry(expiry: string, now = Date.now()): string {
+  const [year, month, day] = expiry.split("-");
+  if (!year || !month || !day) return expiry;
+  return year === String(new Date(now).getFullYear()) ? `${month}/${day}` : `${month}/${day}/${year.slice(2)}`;
+}
+
+/** A bucket's start as the local wall clock, `10:35`. */
+export function formatTideTime(at: number): string {
+  const date = new Date(at);
+  return `${String(date.getHours()).padStart(2, "0")}:${String(date.getMinutes()).padStart(2, "0")}`;
+}
+
+/** The session's date as the chart's legend names it: `Mon 26 Oct`. */
+export function formatFlowSessionDate(session: string | null | undefined): string | null {
+  if (!session) return null;
+  const date = new Date(`${session}T12:00:00Z`);
+  if (Number.isNaN(date.getTime())) return null;
+  return date.toLocaleDateString("en-US", { weekday: "short", day: "numeric", month: "short", timeZone: "UTC" })
+    .replace(/^(\w+), (\w+) (\d+)$/, "$1 $3 $2");
+}

package/src/plugins/builtin/scanner/headless.ts

@@ -1,12 +1,17 @@
 import { ApiRequestError } from "../../../api-client/errors";
 import type {
+  ScannerFlowEvent,
+  ScannerFlowHistoryPage,
   ScannerFlowPayload,
+  ScannerFlowSession,
   ScannerHiloPayload,
   ScannerKind,
   ScannerPayload,
 } from "../../../api-client";
 import type {
+  HeadlessBundleSection,
   HeadlessPaneApiClient,
+  HeadlessPaneColumn,
   HeadlessPaneDefinition,
   HeadlessPaneFreshness,
   HeadlessPaneLoadArgs,
@@ -17,9 +22,20 @@ import {
   DEFAULT_FLOW_FILTERS,
   FLOW_FILTER_OPTIONS,
   filterFlowEvents,
+  flowHistoryQuery,
+  flowHistorySearch,
+  flowScopeSymbol,
+  flowSessionSearch,
+  formatFlowPremium,
+  formatFlowVolOi,
+  mergeFlowRows,
   type FlowFilters,
+  type FlowScope,
 } from "./flow-model";
-import { explainRefusal } from "../shared/cloud-denied";
+import { flowStrikeRows, flowTideMoves, flowTideRows, formatSignedFlowPremium } from "./flow-session";
+import { signalWithTimeout } from "../../../utils/async-deadline";
+import { errorMessage } from "../../../utils/errors";
+import { explainRefusal, refusedLock } from "../shared/cloud-denied";
 import { captureScannerEvent, SCANNER_SNAPSHOT_TIMEOUT_MS } from "../shared/scanner-capture";
 import { flowLockNote } from "./lock-note";
 import { buildHiloBarRows, filterHiloRows, formatHiloPrice, type HiloMinPrice, type HiloSort } from "./hilo-model";
@@ -175,15 +191,121 @@ function flowOption(key: FlowHeadlessFilterKey): HeadlessPaneOptionDef {
   };
 }
 
-function projectFlowSnapshot(
-  payload: ScannerFlowPayload,
+/** The pane's tabs, each a section of the report; left out, the report has every one. */
+type FlowReportTab = "prints" | "tide" | "strikes";
+
+/** Recorded prints of one name a report lists under the live ones. */
+const FLOW_REPORT_RECORDED = 100;
+
+/** The side rule, said once in every report that sums prints by side. */
+export const FLOW_SIDE_RULE = "Net premium counts a print at the ask as bought and one at the bid as sold; mid or unknown prints count as neither.";
+
+const utcTime = (value: unknown) => {
+  const time = Number(value);
+  return Number.isFinite(time) ? `${new Date(time).toISOString().slice(0, 19).replace("T", " ")} UTC` : "-";
+};
+const signedPremium = (value: unknown) => typeof value === "number" ? formatSignedFlowPremium(value) : "";
+/** A side's premium in the text view: `$2.1M`, blank where none traded. */
+const premium = (value: unknown) => typeof value === "number" && value > 0 ? formatFlowPremium(value) : "";
+
+const PRINT_COLUMNS: HeadlessPaneColumn[] = [
+  { key: "at", header: "Time", format: utcTime },
+  { key: "underlying", header: "Ticker" },
+  { key: "right", header: "Right" },
+  { key: "kind", header: "Kind" },
+  { key: "strike", header: "Strike", align: "right" },
+  { key: "expiry", header: "Expiry" },
+  { key: "side", header: "Side" },
+  { key: "size", header: "Size", align: "right" },
+  { key: "premium", header: "Premium", align: "right", textFormat: premium },
+  { key: "volOi", header: "Vol/OI", align: "right", textFormat: (value) => formatFlowVolOi(typeof value === "number" ? value : null) },
+];
+
+const TIDE_COLUMNS: HeadlessPaneColumn[] = [
+  { key: "at", header: "Time", format: utcTime },
+  { key: "callAsk", header: "Call ask", align: "right", description: "Call premium bought at the ask in the bucket." },
+  { key: "callBid", header: "Call bid", align: "right", description: "Call premium sold at the bid in the bucket." },
+  { key: "putAsk", header: "Put ask", align: "right", description: "Put premium bought at the ask in the bucket." },
+  { key: "putBid", header: "Put bid", align: "right", description: "Put premium sold at the bid in the bucket." },
+  { key: "netCalls", header: "Net calls", align: "right", textFormat: signedPremium, description: "Call ask less call bid premium through the bucket." },
+  { key: "netPuts", header: "Net puts", align: "right", textFormat: signedPremium, description: "Put ask less put bid premium through the bucket." },
+  { key: "net", header: "Net premium", align: "right", textFormat: signedPremium, description: "Net calls less net puts through the bucket: the tide." },
+  { key: "change", header: "Change", align: "right", textFormat: signedPremium, description: "What the bucket added to the net premium." },
+];
+const TIDE_TEXT_COLUMNS = TIDE_COLUMNS.filter((column) => !["callAsk", "callBid", "putAsk", "putBid"].includes(column.key));
+
+const STRIKE_COLUMNS: HeadlessPaneColumn[] = [
+  { key: "expiry", header: "Expiry" },
+  { key: "strike", header: "Strike", align: "right" },
+  { key: "callPremium", header: "Calls", align: "right", textFormat: premium, description: "All call premium, mid and unknown prints included." },
+  { key: "callAsk", header: "Call ask", align: "right", textFormat: premium },
+  { key: "callBid", header: "Call bid", align: "right", textFormat: premium },
+  { key: "putPremium", header: "Puts", align: "right", textFormat: premium, description: "All put premium, mid and unknown prints included." },
+  { key: "putAsk", header: "Put ask", align: "right", textFormat: premium },
+  { key: "putBid", header: "Put bid", align: "right", textFormat: premium },
+  { key: "net", header: "Net", align: "right", textFormat: signedPremium, description: "Net call premium less net put premium at the strike." },
+  { key: "prints", header: "Prints", align: "right" },
+];
+
+interface FlowReportData {
+  payload: ScannerFlowPayload;
+  /** One name's recorded prints below the live tape; null for the market. */
+  recorded: ScannerFlowHistoryPage | null;
+  /** The session's prints summed; null when the report leaves the tide and strikes out. */
+  session: ScannerFlowSession | null;
+}
+
+/** Newest first, the buckets that moved the tide with the running totals through each, as the pane's table lists them. */
+function tideReportRows(session: ScannerFlowSession | null): Array<Record<string, unknown>> {
+  return flowTideMoves(flowTideRows(session)).reverse().map((row) => ({ ...row }));
+}
+
+function projectFlowReport(
+  data: FlowReportData,
   filters: FlowFilters,
+  scope: FlowScope,
+  tab: FlowReportTab | null,
   now = Date.now(),
-): HeadlessSnapshotResult {
-  const events = filterFlowEvents(payload.events, filters, new Set(), now);
+): { sections: HeadlessBundleSection[]; asOf: string; metadata: Record<string, unknown>; notes?: string[]; errors?: string[]; freshness: HeadlessPaneFreshness } {
+  const { payload, recorded, session } = data;
+  const symbol = scope.symbol ?? null;
+  const live = filterFlowEvents(payload.events, filters, scope, now);
+  const prints: ScannerFlowEvent[] = recorded ? mergeFlowRows(live, recorded.events) : live;
+  const shows = (section: FlowReportTab) => !tab || tab === section;
+  const sessionDate = session?.session ?? null;
+  const sections: HeadlessBundleSection[] = [];
+  if (shows("prints")) {
+    sections.push({
+      title: symbol ? `${symbol} prints` : "Prints",
+      columns: PRINT_COLUMNS,
+      rows: prints.map((event) => ({ ...event })),
+      empty: symbol ? `No ${symbol} prints under these filters.` : "No prints on the tape under these filters.",
+    });
+  }
+  if (shows("tide")) {
+    sections.push({
+      title: sessionDate ? `Net premium through the ${sessionDate} session` : "Net premium through the session",
+      columns: TIDE_COLUMNS,
+      textColumns: TIDE_TEXT_COLUMNS,
+      rows: tideReportRows(session),
+      unit: "USD",
+      empty: "No prints under these filters this session.",
+    });
+  }
+  if (symbol && shows("strikes")) {
+    sections.push({
+      title: sessionDate ? `${symbol} by expiry and strike, ${sessionDate}` : `${symbol} by expiry and strike`,
+      columns: STRIKE_COLUMNS,
+      rows: flowStrikeRows(session).map(({ id: _id, ...row }) => row),
+      unit: "USD",
+      empty: `No ${symbol} prints under these filters this session.`,
+    });
+  }
+  const sums = shows("tide") || (!!symbol && shows("strikes"));
   return {
+    sections,
     asOf: new Date(payload.asOf).toISOString(),
-    items: events.map((event) => ({ ...event })),
+    ...(sums ? { notes: [FLOW_SIDE_RULE] } : {}),
     ...(payload.status === "degraded" ? { errors: ["Scanner feed degraded"] } : {}),
     freshness: scannerFreshness(payload),
     metadata: {
@@ -192,6 +314,8 @@ function projectFlowSnapshot(
       delayMinutes: payload.delayMinutes,
       received: payload.events?.length ?? 0,
       filters,
+      ...(symbol ? { symbol } : {}),
+      ...(session ? { session: session.session, bucketMinutes: session.bucketMs / 60_000 } : {}),
     },
   };
 }
@@ -202,46 +326,91 @@ interface FlowHeadlessDependencies {
     client: Pick<HeadlessPaneApiClient, "subscribeScanner">,
     signal: AbortSignal,
   ): Promise<ScannerFlowPayload>;
+  recorded(search: string, client: Pick<HeadlessPaneApiClient, "getScannerFlowHistory">, signal: AbortSignal): Promise<ScannerFlowHistoryPage>;
+  session(search: string, client: Pick<HeadlessPaneApiClient, "getScannerFlowSession">, signal: AbortSignal): Promise<ScannerFlowSession>;
 }
 
-function createFlowHeadless(
-  dependencies: FlowHeadlessDependencies = {
-    load: (_args, client, signal) => loadScannerSnapshot<ScannerFlowPayload>(client, "flow", signal),
-  },
-): HeadlessPaneDefinition<"snapshot"> {
+const flowDependencies: FlowHeadlessDependencies = {
+  load: (_args, client, signal) => loadScannerSnapshot<ScannerFlowPayload>(client, "flow", signal),
+  recorded: (search, client, signal) => client.getScannerFlowHistory(search, signalWithTimeout(signal, 20_000)),
+  session: (search, client, signal) => client.getScannerFlowSession(search, signalWithTimeout(signal, 20_000)),
+};
+
+export function createFlowHeadless(
+  dependencies: FlowHeadlessDependencies = flowDependencies,
+): HeadlessPaneDefinition<"bundle"> {
   const keys: FlowHeadlessFilterKey[] = ["minPremium", "side", "kind", "volOi", "expiry"];
   return {
-    shape: "snapshot",
-    argument: { kind: "none" },
-    options: keys.map(flowOption),
-    columns: [
+    shape: "bundle",
+    argument: {
+      kind: "ticker",
+      optional: true,
+      placeholder: "ticker",
+      description: "Optional ticker: its prints and its premium by expiry and strike. Omit for the whole market.",
+    },
+    options: [
+      ...keys.map(flowOption),
       {
-        key: "at",
-        header: "Time",
-        format: (value: unknown) => {
-          const time = Number(value);
-          return Number.isFinite(time) ? `${new Date(time).toISOString().slice(0, 19).replace("T", " ")} UTC` : "-";
-        },
+        key: "tab",
+        settingKey: "tab",
+        description: "One section: the prints, the net-premium tide through the session, or a ticker's strikes. Every section when left out.",
+        type: "enum",
+        values: [{ value: "prints" }, { value: "tide" }, { value: "strikes" }],
       },
-      { key: "underlying", header: "Ticker" },
-      { key: "right", header: "Right" },
-      { key: "kind", header: "Kind" },
-      { key: "strike", header: "Strike", align: "right" },
-      { key: "expiry", header: "Expiry" },
-      { key: "side", header: "Side" },
-      { key: "size", header: "Size", align: "right" },
-      { key: "premium", header: "Premium", align: "right" },
-      { key: "volOi", header: "Vol/OI", align: "right" },
     ],
-    describe: "Options Flow",
+    describe: (args) => {
+      const symbol = flowScopeSymbol(Array.isArray(args.argument) ? args.argument[0] : args.argument);
+      return symbol ? `Options Flow: ${symbol}` : "Options Flow";
+    },
     async load(args, ctx) {
-      const payload = await dependencies.load(args, ctx.apiClient, ctx.signal)
-        .catch(async (error: unknown) => { throw await explainRefusal(error, flowLockNote, { symbol: null }); });
-      return projectFlowSnapshot(payload, {
+      const symbol = flowScopeSymbol(Array.isArray(args.argument) ? args.argument[0] : args.argument);
+      const tab = typeof args.options.tab === "string" && args.options.tab ? args.options.tab as FlowReportTab : null;
+      if (tab === "strikes" && !symbol) throw new Error("--tab strikes needs a ticker: gloom fn FLOW <ticker> --tab strikes.");
+      const filters: FlowFilters = {
         ...DEFAULT_FLOW_FILTERS,
         ...(args.options as Partial<FlowFilters>),
         universe: "active",
-      });
+      };
+      const scope: FlowScope = { symbol, watchlist: new Set() };
+      const refuse = async (error: unknown): Promise<never> => {
+        throw await explainRefusal(error, flowLockNote, { symbol, context: ctx });
+      };
+      // The live feed answers the entitlement first, as the pane's does.
+      const payload = await dependencies.load(args, ctx.apiClient, ctx.signal).catch(refuse);
+      // The recorded prints and the session's sums add to the tape: one that
+      // fails (a timeout, a server without the route) is said under errors and
+      // the rest of the report stands. A wall still refuses the whole read.
+      const failures: string[] = [];
+      const extra = async <T>(load: Promise<T> | null, what: string): Promise<T | null> => {
+        if (!load) return null;
+        try {
+          return await load;
+        } catch (error) {
+          if (ctx.signal.aborted || refusedLock(error)) return refuse(error);
+          failures.push(`${what} unavailable: ${errorMessage(error)}`);
+          return null;
+        }
+      };
+      const wantsPrints = !tab || tab === "prints";
+      const wantsSession = !tab || tab === "tide" || tab === "strikes";
+      const [recorded, session] = await Promise.all([
+        extra(symbol && wantsPrints
+          ? dependencies.recorded(flowHistorySearch(flowHistoryQuery(filters, scope, undefined, FLOW_REPORT_RECORDED)), ctx.apiClient, ctx.signal)
+          : null, "Recorded prints"),
+        extra(wantsSession ? dependencies.session(flowSessionSearch(filters, scope), ctx.apiClient, ctx.signal) : null, "Session totals"),
+      ]);
+      // Asked for the session's sums alone, a failure to read them is the report's.
+      if (!wantsPrints && failures.length > 0) throw new Error(failures[0]);
+      const report = projectFlowReport({ payload, recorded, session }, filters, scope, wantsSession && !session ? "prints" : tab);
+      const errors = [...report.errors ?? [], ...failures];
+      return {
+        sections: report.sections,
+        ...(report.notes ? { notes: report.notes } : {}),
+        ...(errors.length > 0 ? { errors } : {}),
+        ...(symbol ? { symbols: [symbol] } : {}),
+        freshness: report.freshness,
+        metadata: { asOf: report.asOf, ...report.metadata },
+      };
     },
   };
 }

package/src/plugins/builtin/scanner/index.ts

@@ -1,6 +1,6 @@
 import type { PaneSettingsDef } from "../../../types/plugin";
 import type { PluginModule } from "../plugin-module";
-import { DEFAULT_FLOW_FILTERS, FLOW_FILTER_OPTIONS } from "./flow-model";
+import { DEFAULT_FLOW_FILTERS, FLOW_FILTER_OPTIONS, flowScopeSymbol } from "./flow-model";
 import FlowPane from "./flow-pane";
 import HiloPane from "./hilo-pane";
 import LiveScanPane from "./live-pane";
@@ -123,11 +123,22 @@ export const scannerModule: PluginModule = {
       id: "scanner-flow-pane",
       paneId: FLOW_PANE_ID,
       label: "Options Flow",
-      description: "Unusual options activity: sweeps, blocks, and large premium prints.",
-      keywords: ["flow", "options", "sweep", "block", "unusual", "premium", "scanner"],
-      shortcut: { prefix: "FLOW" },
+      description: "Unusual options activity: sweeps, blocks, large premium prints, and the net premium tide.",
+      keywords: ["flow", "options", "sweep", "block", "unusual", "premium", "scanner", "tide", "net premium", "market tide"],
+      shortcut: { prefix: "FLOW", argKind: "ticker", argPlaceholder: "ticker", argOptional: true, openWithoutArg: true },
       headless: flowHeadless,
-      createInstance: () => ({ settings: { ...DEFAULT_FLOW_FILTERS } }),
+      // One window per name, and one for the whole market.
+      createInstance: (_context, options) => {
+        const symbol = flowScopeSymbol(options?.symbol ?? options?.arg);
+        return symbol
+          ? {
+            instanceId: `${FLOW_PANE_ID}:${symbol}`,
+            title: `FLOW ${symbol}`,
+            binding: { kind: "fixed" as const, symbol },
+            settings: { ...DEFAULT_FLOW_FILTERS, symbol },
+          }
+          : { settings: { ...DEFAULT_FLOW_FILTERS } };
+      },
     },
     {
       id: LIVE_SCAN_TEMPLATE_ID,

package/src/plugins/builtin/scanner/live-headless.ts

@@ -4,7 +4,18 @@ import type {
   HeadlessPaneFreshness,
   HeadlessSnapshotResult,
 } from "../../../types/plugin";
-import { conditionColumnLabel, conditionText, DEFAULT_LIVE_SCAN, LIVE_SCAN_SECTORS, parseUniverseValue, readLiveScan, type LiveScan } from "./live-model";
+import { formatPercentRaw } from "../../../utils/format";
+import {
+  conditionColumnLabel,
+  conditionText,
+  DEFAULT_LIVE_SCAN,
+  formatMultiple,
+  LIVE_SCAN_SECTORS,
+  parseUniverseValue,
+  readLiveScan,
+  warmingWindowsText,
+  type LiveScan,
+} from "./live-model";
 import { LIVE_SCAN_INDEXES } from "../../../api-client/live-scan";
 
 /** `all`, an index (`sp500`) or a sector (`Energy`), as `--universe` takes it. */
@@ -39,9 +50,21 @@ function freshness(payload: LiveScanPayload): HeadlessPaneFreshness {
   return payload.access === "realtime" ? { status: "live" } : { status: "delayed", delayMinutes: payload.delayMinutes };
 }
 
+/** Why a scan lists nothing, as the pane says it: still starting, warming up, closed, or no match. */
+function emptyText(payload: LiveScanPayload): string {
+  if (payload.status === "starting") return "The scanner is starting. Matches appear within a minute.";
+  if (payload.status === "closed") return "Nothing matched at the close. The scan runs again at the open.";
+  const warming = warmingWindowsText(payload);
+  if (warming) return `The scanner is warming up: conditions over ${warming} match nothing until that much of the session has been watched.`;
+  return "Nothing matches right now.";
+}
+
+const number = (value: unknown) => (typeof value === "number" ? value : undefined);
+
 function projectLiveScan(payload: LiveScanPayload, scan: LiveScan): HeadlessSnapshotResult {
   return {
     asOf: new Date(payload.asOf ?? payload.takenAt ?? Date.now()).toISOString(),
+    empty: emptyText(payload),
     items: payload.matches.map((match) => ({
       symbol: match.symbol,
       exchange: match.exchange ?? null,
@@ -64,6 +87,7 @@ function projectLiveScan(payload: LiveScanPayload, scan: LiveScan): HeadlessSnap
       scanned: payload.scanned,
       matched: payload.matched,
       conditions: scan.conditions.map(conditionText),
+      ...(payload.warmingWindows?.length ? { warmingWindows: payload.warmingWindows } : {}),
     },
   };
 }
@@ -94,8 +118,8 @@ export const liveScanHeadless: HeadlessPaneDefinition<"snapshot"> = {
     { key: "symbol", header: "Symbol" },
     { key: "name", header: "Name" },
     { key: "price", header: "Price", align: "right" },
-    { key: "changePercent", header: "Chg %", align: "right" },
-    { key: "relativeVolume", header: "RVol", align: "right" },
+    { key: "changePercent", header: "Chg %", align: "right", format: (value) => formatPercentRaw(number(value)) },
+    { key: "relativeVolume", header: "RVol", align: "right", format: (value) => formatMultiple(number(value)) },
     { key: "volume", header: "Volume", align: "right" },
   ],
   describe: "Live Scanner",

package/src/plugins/builtin/scanner/live-model.ts

@@ -5,6 +5,7 @@ import {
   type LiveScanDirection,
   type LiveScanIndex,
   type LiveScanMatch,
+  type LiveScanPayload,
   type LiveScanWindow,
   type LiveScanWireDefinition,
 } from "../../../api-client/live-scan";
@@ -208,6 +209,16 @@ export function formatMultiple(value: number | null | undefined): string {
   return value >= 10 ? `${Math.round(value)}x` : `${value.toFixed(1)}x`;
 }
 
+/**
+ * The windows a running scan's conditions cannot measure yet (the scanner
+ * started recently), as a list to read: `5 min, 15 min`. Empty when there are
+ * none, or when the scanner is not running a session.
+ */
+export function warmingWindowsText(payload: LiveScanPayload | null): string {
+  const windows = payload?.status === "live" || payload?.status === "degraded" ? payload.warmingWindows : [];
+  return (windows ?? []).map((window) => `${window} min`).join(", ");
+}
+
 /** A time of day the scanner saw something, to the second. */
 export function formatScanTime(at: number | null | undefined): string {
   if (at == null || !Number.isFinite(at)) return "--";

package/src/plugins/builtin/scanner/live-pane.tsx

@@ -60,6 +60,7 @@ import {
   universeLabel,
   universeOptions,
   universeValue,
+  warmingWindowsText,
   type LiveScan,
   type SavedLiveScan,
 } from "./live-model";
@@ -194,9 +195,8 @@ function emptyState(payload: LiveScanPayload | null): { title: string; hint?: st
 }
 
 function warmingNotice(payload: LiveScanPayload | null): string | null {
-  const windows = payload?.status === "live" || payload?.status === "degraded" ? payload.warmingWindows : [];
-  if (!windows?.length) return null;
-  const list = windows.map((window) => `${window} min`).join(", ");
+  const list = warmingWindowsText(payload);
+  if (!list) return null;
   return `The scanner started recently: conditions over ${list} match nothing until that much of the session has been watched.`;
 }
 

package/src/plugins/builtin/scanner/lock-note.ts

@@ -5,12 +5,13 @@ import { proLockNote } from "../shared/pro-lock-note";
  * FLOW is Pro whole: the one scanner with no delayed tier to fall back to.
  * The options chain needs no account and lists each contract's day volume and
  * open interest, the raw counts behind a sweep or a block, without the prints.
- * FLOW takes no ticker, so the route names none to check.
+ * FLOW takes a ticker only to narrow the market to one name, so the note
+ * repeats it only when the reader gave one.
  */
 export function flowLockNote(lock: PaneLock): Promise<string> {
   return proLockNote(lock, {
     token: "FLOW",
-    argument: "none",
+    argument: "optional",
     does: "it streams real-time sweeps, blocks and large premium prints across US options exchanges",
     shows: "it",
     free: [{ text: (ticker, company) => `gloom options ${ticker} lists ${company}'s option chain, each contract with its volume and open interest.` }],

package/src/plugins/builtin/seasonality/headless.ts

@@ -1,6 +1,7 @@
 import type { HeadlessPaneDefinition } from "../../../types/plugin";
 import { resolveHeadlessInstrument } from "../shared/headless-market-data";
 import { loadSeasonalityHistory } from "./client";
+import { closedHistoryBarDay, formingHistoryBar } from "../ticker-detail/data-panes/history-bars";
 import { MONTH_LABELS, projectSeasonality, projectWeekdays, TURN_OF_MONTH_LABELS } from "./model";
 
 const percent = (digits: number) => (value: unknown) => typeof value === "number" ? `${(value * 100).toFixed(digits)}%` : "--";
@@ -9,7 +10,7 @@ const statColumns = (digits: number, countHeader: string) => [{ key: "mean", hea
 
 export const seasonalityHeadless: HeadlessPaneDefinition<"bundle"> = {
   shape: "bundle", argument: { kind: "ticker", description: "Ticker" },
-  // Dated by the month of its last monthly close.
+  // Dated by its last monthly close, or by how far the running month's bar runs (`month to date, through Fri 23 Oct 2026`).
   freshness: { status: "not-a-feed", basis: "monthly closes", maxAgeMinutes: 45 * 24 * 60 },
   describe: (args) => `SEAS ${args.symbols[0] ?? ""}`,
   discovery: { screenshotReadiness: "live-dom", limitations: ["Local-price closes; dividends and FX are excluded.",
@@ -46,6 +47,13 @@ export const seasonalityHeadless: HeadlessPaneDefinition<"bundle"> = {
       };
     }
     const model = projectSeasonality(history.history, { symbol: instrument.symbol, lookbackYears: Number(args.options.lookbackYears) || 10 });
+    // Monthly bars are dated by their month's first day, which is no close while the month runs.
+    const bar = model.asOf?.toISOString().slice(0, 10);
+    // The venue whose sessions say whether the month still runs: the key's, or for a bare symbol its quote's.
+    const quote = bar && !instrument.exchange ? await ctx.marketData.getQuote(instrument.symbol, "").catch(() => null) : null;
+    const venue = instrument.exchange || quote?.listingExchangeName || quote?.exchangeName || undefined;
+    const forming = formingHistoryBar("1mo", bar, venue, Date.now());
+    const closed = forming ? null : closedHistoryBarDay("1mo", bar, venue, Date.now());
     const monthColumns = MONTH_LABELS.map((label, month) => ({ key: `m${month}`, header: label, format: percent(1) }));
     return {
       sections: [
@@ -57,6 +65,7 @@ export const seasonalityHeadless: HeadlessPaneDefinition<"bundle"> = {
       complete: !history.stale && !history.error && model.years.length > 0,
       unavailableSymbols: model.years.length ? [] : [instrument.symbol],
       ...common,
+      ...(forming ? { freshness: { periodToDate: forming } } : closed ? { freshness: { asOf: closed } } : {}),
       metadata: { unit: "decimal return, local-price close to close", asOf: model.asOf?.toISOString() ?? null, stale: history.stale,
         fetchedAt: history.fetchedAt, averagePath: model.averagePath, methodology: "docs/research-data.md#seasonality" },
     };